diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
index 70634bb543..4ebcbc33d9 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.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-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: 7e51345e7eba8a58db63807e31d4a11481e3ffea
-2026-08-05-profile-plugin-bundles.zh.md: b2631603737ea9412eb97029ff01d751d8084cec
+2026-08-05-profile-plugin-bundles.md: 48786a9c1ccaceb5f16c9eefed01e556cf759e6d
+2026-08-05-profile-plugin-bundles.zh.md: c88cbf98e4276549a6fae6a5b1253d3d838a64ca
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
index 7e51345e7e..48786a9c1c 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
@@ -14,7 +14,7 @@ Everything becomes a **profile**: a directory `$DSH_HOME/profiles/<name>` with a
 
 The default Profile templates use `@deepseek-ai/dsh-base` as the shared core for `web`, `headless`, `sdk`, and `acp`, with one mode bundle above it. The [standalone `sdk-minimal` profile](../../../../packages/bundle/sdk-minimal/README.md) instead lists one bundle that owns its complete explicit tree. Generic `dsh --profile <name>` hands its remaining arguments to that profile's command-line startup row: Web owns its flag family, headless owns its task positional, and the protocol profiles accept no app options. Patch overlays use launcher-owned `--patch`. A new, non-shipped target can use `--from-default-profile <template>` to copy one default template's bundle list and patch-reload policy before boot or config dump. This creates an independent profile with empty dependencies and an empty user patch: it neither reads a local profile named by the template nor records an inheritance relationship. The launcher claims the complete target directory exclusively, so existing state and concurrent creators fail without modification. `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes a base-backed profile and reconciles `dsh.profile.bundles` with installed bundle declarations; a package without a bundle declaration remains a plain dependency. [Headless as a direct core entry point](../../archived/architecture/2026-08-09-headless-direct-core-entry-point.md) owns the headless composition contract.
 
-Resolution is two-anchored by construction: `dsh.profile.bundles` names resolve from the dsh installation first, then the profile directory — so in-box bundles always come from the same installation as the running `dsh` and pnpm never manages them — while bare plugin names in patch rows resolve through the profile directory's Node parent-walk into the maintained flat fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
+Resolution is two-anchored by construction: `dsh.profile.bundles` names resolve from the dsh installation first, then the profile directory, so in-box bundles always come from the same installation as the running `dsh` and pnpm never manages them. Bare plugin names in patch rows use the [immutable profile resolution generation](2026-09-09-profile-resolution-generations.md), which applies the same installation-first and ordered-bundle rules in memory; retained link and dual modes can materialize the same result.
 
 Two supporting refactors: the webserver's built-in static dist serving became the single-owner **fallback seat** (`registerFallback`/`applyIndexTaps`), with the SPA server extracted to `@deepseek-ai/dsh-host-frontend-static` so the web bundle owns its dist as composition, not launcher code; and the personal-overlay machinery of the [dsh CLI personal-config decision](../../archived/feature/2026-07-20-dsh-cli-personal-config.md) (`loadPersonalPatches`, `$DSH_HOME/config.yaml`) was retargeted to the per-profile and home-level `cordis.patch.yml` layers (`loadOptionalPatches`, `watchUserPatches` taking a filename), superseding that note's entry modes and file location while keeping its Harness-home root, patch semantics, and fail-loud parsing.
 
@@ -31,5 +31,5 @@ Two supporting refactors: the webserver's built-in static dist serving became th
 - New composition surfaces (a TUI, provider packs) ship as ordinary npm packages installable per profile, without a repository row for every deployment shape.
 - Users can start an independent custom profile from any shipped application template without copying machine-local profile state.
 - `apps/cli` shrank to argv parsing, profile machinery consumption, and the pnpm forwarder; `AppCLIEntry` and the per-surface boot paths are gone.
-- The keyless web e2e scaffold boots the same bundle layers over the same empty-root shape as production, including the profiles module fallback, so composition drift between test and product fails loudly.
+- The keyless web e2e scaffold boots the same bundle layers over the same empty-root shape as production and exercises the same profile package-selection rules, so composition drift between test and product fails loudly.
 - Under the pre-release stance, backends carry no compatibility behavior for old on-disk configuration; `$DSH_HOME/config.yaml` is ignored.
diff --git a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
index b263160373..c88cbf98e4 100644
--- a/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 默认 Profile 模板为 `web`、`headless`、`sdk` 与 `acp` 使用 `@deepseek-ai/dsh-base` 作为共享核心，并在其上叠加一个模式组合包。[独立 `sdk-minimal` profile](../../../../packages/bundle/sdk-minimal/README.zh.md)则只列出一个拥有完整显式配置树的组合包。通用的 `dsh --profile <name>` 把剩余参数交给该 profile 的命令行启动行：Web 持有自己的 flag 家族，headless 持有任务位置参数，协议 profile 不接受应用选项。patch overlay 使用启动器持有的 `--patch`。新的非内置目标可以使用 `--from-default-profile <template>`，在启动或配置 dump 之前复制一个默认模板的 bundle 列表与 patch 重载策略。这会创建依赖为空、用户 patch 为空的独立 profile：它既不读取与模板同名的本地 profile，也不记录继承关系。launcher 会以独占方式领取完整的目标目录，因此既有状态和并发创建者都会在不作修改的情况下失败。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化一个以 base 为基础的 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 入口](../../archived/architecture/2026-08-09-headless-direct-core-entry-point.md)负责 headless 组合约定。
 
-解析在构造上就是双锚点的：`dsh.profile.bundles` 中的名称先从 dsh 安装目录解析，再从 profile 目录解析——因此内置组合包始终来自与运行中 `dsh` 相同的安装，pnpm 从不管理它们——而 patch 行中的裸插件名称经 profile 目录的 Node 父目录逐级查找，落到受维护的扁平回退目录 `$DSH_HOME/profiles/node_modules`（安装目录的应用与各组合包所依赖的每个包各一个符号链接，每次启动时修复）。
+解析在构造上就是双锚点的：`dsh.profile.bundles` 中的名称先从 dsh 安装目录解析，再从 profile 目录解析，因此内置组合包始终来自与运行中 `dsh` 相同的安装，pnpm 从不管理它们。patch 行中的裸插件名称使用[不可变 profile resolution generation](2026-09-09-profile-resolution-generations.zh.md)，在内存中应用相同的安装优先与有序 bundle 规则；保留的 link 与 dual 模式可以物化同一结果。
 
 两项配套重构：webserver 内置的静态 dist 服务改为单一所有者的**回退席位**（`registerFallback`／`applyIndexTaps`），SPA 服务器提取到 `@deepseek-ai/dsh-host-frontend-static`，使 web 组合包以组合的方式持有自己的 dist，而不是靠启动器代码；[dsh CLI 个人配置决策](../../archived/feature/2026-07-20-dsh-cli-personal-config.md)的个人 overlay 机制（`loadPersonalPatches`、`$DSH_HOME/config.yaml`）改为面向逐 profile 与 home 级的 `cordis.patch.yml` 层（`loadOptionalPatches`、接受文件名的 `watchUserPatches`），取代该笔记的各入口模式与文件位置，同时保留其 Harness home 根目录、patch 语义与响亮失败的解析。
 
@@ -31,5 +31,5 @@ Status: implemented
 - 新的组合表层（TUI、提供方扩展包）以普通 npm 包形式交付，可按 profile 安装，无需在仓库中为每种部署形态各留一行。
 - 用户可以从任意随附应用模板启动一个独立的自定义 profile，而不会复制机器本地的 profile 状态。
 - `apps/cli` 收缩为 argv 解析、profile 机制的消费方和 pnpm 转发器；`AppCLIEntry` 与各表层专属的启动路径全部移除。
-- 无密钥 web e2e 脚手架以与生产相同的空根形态启动相同的组合包层，包括 profiles 模块回退，因此测试与产品之间的组合漂移会响亮失败。
+- 无密钥 web e2e 脚手架以与生产相同的空根形态启动相同的组合包层，并执行相同的 profile 包选择规则，因此测试与产品之间的组合漂移会响亮失败。
 - 按发布前姿态，后端不携带旧磁盘配置的兼容行为；`$DSH_HOME/config.yaml` 会被忽略。
diff --git a/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.i18n.yaml
index 7fda5604f7..0ac7d7109d 100644
--- a/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.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-18-experimental-agent-teams-packages.md
-2026-08-18-experimental-agent-teams-packages.md: 2a00b651e0073434a5a68df13b9716adcab5fccf
-2026-08-18-experimental-agent-teams-packages.zh.md: df73ee5c05fd3a25bf843bee10b06535a1512783
+2026-08-18-experimental-agent-teams-packages.md: 4a78a60c2ad7463c06b670e6ec664579ffd767b9
+2026-08-18-experimental-agent-teams-packages.zh.md: 8056cd8194695e8ce41acb359e51c040d4ed3aec
diff --git a/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.md b/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.md
index 2a00b651e0..4a78a60c2a 100644
--- a/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.md
+++ b/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.md
@@ -20,7 +20,7 @@ The generic caller-reserved continuable child identity and selective direct-chil
 
 The published Host-side Agent Teams profile bundle depends on the Team packages and applies after `dsh-base`. It inserts the Team rows and disables the global continuable-child controls whose model-visible names overlap the Team tools. The separate published Web profile applies after `dsh-web-app` and the Host profile; it inserts the Team UI, which mounts the Remote contribution generated by the Team package. Both layers remain opt-in and leave the shipped base, CLI, Web, and Python runtime dependency graphs unchanged.
 
-Profile installation resolves each published bundle and its dependencies through the profile's package manager. The generic profile launcher then applies the selected layers without adding them to any shipped profile or changing another profile's resolution.
+Profile startup resolves selected bundles before computing the [immutable profile resolution generation](2026-09-09-profile-resolution-generations.md). The generation retains installation-first precedence, traverses each explicit bundle root completely in profile order, and keeps pnpm-managed profile packages authoritative. Runtime mode enforces the result in memory; retained link and dual modes materialize the same result as shared and profile-owned projections. A private profile layer can therefore carry experimental plugin rows without adding those plugins to a release app, requiring profile users to install transitive packages directly, weakening packaged-runtime module identity, or changing another profile's resolution.
 
 Experimental status changes compatibility and support expectations, not publication for these five packages. They retain the repository's ordinary documentation, invariant, lifecycle, security, unit, real-composition, and snapshot requirements. Promotion still requires review of the public contracts, limitations, test evidence, runtime dependents, and a named owner accepting stable-package obligations.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.zh.md b/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.zh.md
index df73ee5c05..8056cd8194 100644
--- a/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-18-experimental-agent-teams-packages.zh.md
@@ -20,7 +20,7 @@ dsh 打包与发布集合以及本地基线发布器包含这五个 Agent Teams
 
 公开发布的 Host 侧 Agent Teams profile bundle 依赖 Team 包，并在 `dsh-base` 之后应用。它会插入 Team 配置行，并禁用模型可见名称与 Team 工具重叠的全局 continuable-child control。独立公开发布的 Web profile 在 `dsh-web-app` 与 Host profile 之后应用；它会插入 Team UI，后者挂载 Team package 生成的 Remote contribution。两个层都保持显式启用，不改变随附 base、CLI、Web 与 Python runtime 的依赖图。
 
-profile 安装通过自身 package manager 解析每个公开 bundle 及其依赖。通用 profile launcher 随后应用所选层，不会把它们加入任何随附 profile，也不会改变其他 profile 的解析结果。
+profile 启动会先解析所选 bundle，再计算[不可变 profile resolution generation](2026-09-09-profile-resolution-generations.zh.md)。generation 保留安装优先顺序，按 profile 顺序完整遍历每个显式 bundle 根，并让 pnpm 管理的 profile 包保持优先。runtime 模式在内存中强制该结果；保留的 link 与 dual 模式把同一结果物化为共享和 profile 自有投影。因此，私有 profile 层可以携带实验性 plugin 配置行，而无需把这些 plugin 加入发布 app、要求 profile 用户直接安装传递依赖、破坏 packaged-runtime 的模块身份，或改变其他 profile 的解析结果。
 
 对这五个包而言，实验性状态改变兼容性与支持预期，而不阻止发布。这些包仍须满足仓库的一般文档、不变式、生命周期、安全、单元测试、真实组合测试和快照要求。promotion 前仍须评审公开约定、限制、测试证据、运行时依赖方，并由一名具名 owner 接受稳定包义务。
 
diff --git a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.i18n.yaml
index 2be979e55d..1d5d4521cf 100644
--- a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.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-21-deepseek-llm-api-request-extensions.md
-2026-08-21-deepseek-llm-api-request-extensions.md: a0e38c1da5af32b0ba5e07df632ac4e25148419e
-2026-08-21-deepseek-llm-api-request-extensions.zh.md: 763f418c7bd6029c08027cd5f4705bffd984b9ee
+2026-08-21-deepseek-llm-api-request-extensions.md: 7a3609a3f7d8b2aa6edb634643ef234b7e3e8c07
+2026-08-21-deepseek-llm-api-request-extensions.zh.md: 69426df3cc85851e448b98dc51af79555b8cbafc
diff --git a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.md b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.md
index a0e38c1da5..7a3609a3f7 100644
--- a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.md
+++ b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.md
@@ -14,13 +14,13 @@ Both values belong only on the official DeepSeek adapter path. Adding them to `G
 
 ## Decision
 
-`@deepseek-ai/dsh-deepseek-llm-api-extensions` registers `ctx.deepseekLlmApiExtensions`, an additive registry of top-level fields for `deepseek-official` request bodies. A contributor claims one declaration-merged field with `register()`. The adapter invokes `prepare()` after serializing the exact wire messages, passes the request cancellation signal, rejects preparation or base-field collision before HTTP, merges the detached fields, and calls the captured `accept()` transaction after HTTP 2xx. The registry stops awaiting preparation after cancellation even if a contributor ignores the signal. Acceptance failures remain request failures under `REQUEST_EXTENSION`; transport and non-2xx failures never accept a contribution. A composition without the registry retains the reusable base adapter. Shipped compositions mount the registry and both contributors: package metadata is enabled by default, while Session-log upload is disabled by default and requires `session-log-deepseek.enabled: true`. Keyless `deepseek-official` replay invokes preparation with a synthetic empty base body and the same acceptance transaction before its first recorded chunk, preserving post-2xx extension side effects rather than field bytes.
+`@deepseek-ai/dsh-deepseek-llm-api-extensions` registers `ctx.deepseekLlmApiExtensions`, an additive registry of top-level fields for `deepseek-official` request bodies. A contributor claims one declaration-merged field with `register()`. The adapter invokes `prepare()` after serializing the exact wire messages, passes the request cancellation signal, rejects preparation or base-field collision before HTTP, merges the detached fields, and calls the captured `accept()` transaction after HTTP 2xx. The registry stops awaiting preparation after cancellation even if a contributor ignores the signal. Acceptance failures remain request failures under `REQUEST_EXTENSION`; transport and non-2xx failures never accept a contribution. A composition without the registry retains the reusable base adapter. Shipped compositions mount the registry and both contributors: both package metadata and Session-log upload are enabled by default; `session-log-deepseek.enabled: false` disables log upload under the [default-upload decision](2026-09-14-session-log-upload-default.md). Keyless `deepseek-official` replay invokes preparation with a synthetic empty base body and the same acceptance transaction before its first recorded chunk, preserving post-2xx extension side effects rather than field bytes.
 
 The provider-neutral `llm` package and `llm-pi-ai` contain no extension type, service lookup, field merge, or acceptance call.
 
 ## Incremental session-log field
 
-`@deepseek-ai/dsh-session-log-deepseek` owns `dsh_session_log` as an explicit opt-in. When enabled, each request carrying a live Session id sends the contiguous canonical event suffix after the greatest durable `session-log-deepseek/delivery-accepted` watermark for that same Session identity. The field includes the immutable Session header and complete event envelopes. A 2xx appends a new watermark for the transmitted `throughSeq`; that event enters the following request's suffix. Forked logs retain parent watermark ids, so a child starts from sequence zero under its own identity. Concurrent acceptances may arrive out of order, and the maximum watermark remains authoritative. A process-local fold scans each Session event once and incrementally consumes later appends; a new Session object or HMR generation rebuilds the fold from durable history.
+`@deepseek-ai/dsh-session-log-deepseek` owns the default-on `dsh_session_log` field. When enabled, each request carrying a live Session id sends the contiguous canonical event suffix after the greatest durable `session-log-deepseek/delivery-accepted` watermark for that same Session identity. The field includes the immutable Session header and complete event envelopes. A 2xx appends a new watermark for the transmitted `throughSeq`; that event enters the following request's suffix. Forked logs retain parent watermark ids, so a child starts from sequence zero under its own identity. Concurrent acceptances may arrive out of order, and the maximum watermark remains authoritative. A process-local fold scans each Session event once and incrementally consumes later appends; a new Session object or HMR generation rebuilds the fold from durable history.
 
 The failure direction is at least once. A transport or provider rejection records no watermark. A crash after remote acceptance but before the watermark persists causes replay after resume, never a skipped sequence. Existing session checkpoints persist the event; the upload plugin owns no second store.
 
@@ -50,7 +50,7 @@ The process-lifetime manifest-identity cache remains separate because in-process
 
 ## Verification
 
-Registry tests pin duplicate ownership, effect-scoped disposal, detached field values, concurrent and abortable preparation, receiver-preserving acceptance, one acceptance settlement, and failure aggregation. Session tests pin the default-off policy, explicit full-first/suffix-later delivery, direct complete event envelopes independent of base-body messages, incremental watermark folding, persisted restart recovery, fork identity fencing, out-of-order acceptance, and late invariant loading. Package-inventory tests pin default-on and explicit-off policies, host and standing-preset discovery, conflicting Loader resolution bases, manifest resolution, lifecycle filtering, and exact name/version ordering. The direct adapter mock proves pre-HTTP preparation failure, cancellation, non-2xx non-acceptance, 2xx acceptance before a later stream failure, and field collision. Keyless replay pins post-2xx extension acceptance, and the TypeScript JSON-RPC plus Python packaged-runtime snapshots project the acceptance event through both SDKs. Real Loader composition pins default package metadata plus opt-in Session upload, one real-API request mounts both shipped extensions and proves the official endpoint accepts them, and pi-ai tests retain their unchanged wire requests.
+Registry tests pin duplicate ownership, effect-scoped disposal, detached field values, concurrent and abortable preparation, receiver-preserving acceptance, one acceptance settlement, and failure aggregation. Session tests pin default-on and explicit-off policies, full-first/suffix-later delivery, direct complete event envelopes independent of base-body messages, incremental watermark folding, persisted restart recovery, fork identity fencing, out-of-order acceptance, and late invariant loading. Package-inventory tests pin default-on and explicit-off policies, host and standing-preset discovery, conflicting Loader resolution bases, manifest resolution, lifecycle filtering, and exact name/version ordering. The direct adapter mock proves pre-HTTP preparation failure, cancellation, non-2xx non-acceptance, 2xx acceptance before a later stream failure, and field collision. Keyless replay pins post-2xx extension acceptance, and the TypeScript JSON-RPC plus Python packaged-runtime snapshots project the acceptance event through both SDKs. Real Loader composition pins default package metadata and Session upload plus explicit upload disablement, one real-API request mounts both shipped extensions and proves the official endpoint accepts them, and pi-ai tests retain their unchanged wire requests.
 
 ## Alternatives considered
 
@@ -85,7 +85,7 @@ About 98% of the measured v1 real-session events were `assistant/chunk`. Omittin
 
 ## Consequences
 
-Official DeepSeek requests carry active package versions to their resolved `baseURL`, including configured gateways. An explicit Session-log opt-in also carries the complete newly unaccepted Session suffix. The fields are model-hidden and add no prompt tokens or KV-cache changes, but can substantially increase HTTP body size. Manifest resolution, field collision, acceptance logging, or provider schema rejection fails the model request rather than silently dropping metadata.
+Official DeepSeek requests carry active package versions to their resolved `baseURL`, including configured gateways. Unless Session-log upload is disabled, each eligible request also carries the complete newly unaccepted Session suffix. The fields are model-hidden and add no prompt tokens or KV-cache changes, but can substantially increase HTTP body size. Manifest resolution, field collision, acceptance logging, or provider schema rejection fails the model request rather than silently dropping metadata.
 
 The `delivery-accepted` event becomes part of the canonical log and is itself delivered on a later request. Crash recovery can duplicate a suffix but does not infer acceptance from assistant output or create a second local cursor store. Direct calls without a live Session omit the session field; host package inventory remains available.
 
diff --git a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md
index 763f418c7b..69426df3cc 100644
--- a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md
@@ -14,13 +14,13 @@ Status: implemented
 
 ## 决策
 
-`@deepseek-ai/dsh-deepseek-llm-api-extensions` 注册 `ctx.deepseekLlmApiExtensions`，即 `deepseek-official` 请求正文顶层字段的增量注册表。贡献方通过 `register()` 认领一个经声明合并的字段。适配器在序列化确切协议消息后调用 `prepare()`、传入请求取消信号，在 HTTP 前拒绝准备失败或基础字段冲突，合并分离字段，并在 HTTP 2xx 后调用捕获的 `accept()` 事务。即使贡献方忽略信号，注册表也会在取消后停止等待准备。接受失败仍以 `REQUEST_EXTENSION` 使请求失败；传输失败与非 2xx 失败绝不会接受贡献。未挂载注册表的组合会保留可复用基础适配器。随附组合会挂载注册表与两个贡献方：插件包元数据默认开启，会话日志上传默认关闭，需要设置 `session-log-deepseek.enabled: true`。无密钥 `deepseek-official` 回放会使用合成的空基础正文执行准备，并在第一个已记录分片前调用同一接受事务；它保持的是 2xx 后扩展副作用，而非字段字节。
+`@deepseek-ai/dsh-deepseek-llm-api-extensions` 注册 `ctx.deepseekLlmApiExtensions`，即 `deepseek-official` 请求正文顶层字段的增量注册表。贡献方通过 `register()` 认领一个经声明合并的字段。适配器在序列化确切协议消息后调用 `prepare()`、传入请求取消信号，在 HTTP 前拒绝准备失败或基础字段冲突，合并分离字段，并在 HTTP 2xx 后调用捕获的 `accept()` 事务。即使贡献方忽略信号，注册表也会在取消后停止等待准备。接受失败仍以 `REQUEST_EXTENSION` 使请求失败；传输失败与非 2xx 失败绝不会接受贡献。未挂载注册表的组合会保留可复用基础适配器。随附组合会挂载注册表与两个贡献方：插件包元数据和会话日志上传均默认开启；按[默认上传决策](2026-09-14-session-log-upload-default.zh.md)，设置 `session-log-deepseek.enabled: false` 可关闭日志上传。无密钥 `deepseek-official` 回放会使用合成的空基础正文执行准备，并在第一个已记录分片前调用同一接受事务；它保持的是 2xx 后扩展副作用，而非字段字节。
 
 提供方无关的 `llm` 包与 `llm-pi-ai` 不包含任何扩展类型、服务查找、字段合并或接受调用。
 
 ## 增量会话日志字段
 
-`@deepseek-ai/dsh-session-log-deepseek` 以显式选择启用的方式拥有 `dsh_session_log`。启用后，每个携带存活会话 id 的请求都会发送该确切会话身份最大持久 `session-log-deepseek/delivery-accepted` 水位之后的连续权威事件后缀。该字段包含不可变会话 header 与完整事件信封。2xx 会为已发送的 `throughSeq` 追加新水位；该事件会进入下一次请求的后缀。Fork 日志会保留父级水位 id，因此子会话会在自己的身份下从序列零开始。并发接受可能乱序到达，最大水位仍保持权威。进程内 fold 会让每条会话事件只被扫描一次，并增量消费后续追加；新的会话对象或 HMR generation 会从持久历史重建该 fold。
+`@deepseek-ai/dsh-session-log-deepseek` 拥有默认开启的 `dsh_session_log` 字段。启用后，每个携带存活会话 id 的请求都会发送该确切会话身份最大持久 `session-log-deepseek/delivery-accepted` 水位之后的连续权威事件后缀。该字段包含不可变会话 header 与完整事件信封。2xx 会为已发送的 `throughSeq` 追加新水位；该事件会进入下一次请求的后缀。Fork 日志会保留父级水位 id，因此子会话会在自己的身份下从序列零开始。并发接受可能乱序到达，最大水位仍保持权威。进程内 fold 会让每条会话事件只被扫描一次，并增量消费后续追加；新的会话对象或 HMR generation 会从持久历史重建该 fold。
 
 失败方向为至少一次。传输失败或提供方拒绝不会记录水位。远端接受后、水位持久化前发生崩溃，会在恢复后触发重放，绝不会跳过序列。现有会话检查点会持久化该事件；上传插件不拥有第二份存储。
 
@@ -50,7 +50,7 @@ Status: implemented
 
 ## 验证
 
-注册表测试固定重复所有权、effect 作用域 dispose（资源释放）、分离字段值、并发且可取消的准备、保留接收者的接受操作、单次接受结算与失败聚合。会话测试固定默认关闭策略、显式启用后的首次完整／后续后缀交付、与基础正文消息无关的直接完整事件信封、增量水位 fold、持久化重启恢复、fork 身份围栏、乱序接受与 invariant 延迟加载。插件包清单测试固定默认开启与显式关闭策略、宿主与 standing preset 发现、冲突的 Loader 解析基址、manifest 解析、生命周期过滤及确切名称／版本排序。直接适配器 mock 测试证明 HTTP 前准备失败、取消、非 2xx 不接受、2xx 在后续流失败前接受，以及字段冲突。无密钥回放会固定 2xx 后扩展接受，TypeScript JSON-RPC 与 Python 打包运行时快照则通过两套 SDK 投影接受事件。真实 Loader 组合会固定默认包元数据与显式启用的会话上传，一个真实 API 请求会挂载两个随附扩展并证明官方端点接受它们；pi-ai 测试保持其协议请求不变。
+注册表测试固定重复所有权、effect 作用域 dispose（资源释放）、分离字段值、并发且可取消的准备、保留接收者的接受操作、单次接受结算与失败聚合。会话测试固定默认开启与显式关闭策略、首次完整／后续后缀交付、与基础正文消息无关的直接完整事件信封、增量水位 fold、持久化重启恢复、fork 身份围栏、乱序接受与 invariant 延迟加载。插件包清单测试固定默认开启与显式关闭策略、宿主与 standing preset 发现、冲突的 Loader 解析基址、manifest 解析、生命周期过滤及确切名称／版本排序。直接适配器 mock 测试证明 HTTP 前准备失败、取消、非 2xx 不接受、2xx 在后续流失败前接受，以及字段冲突。无密钥回放会固定 2xx 后扩展接受，TypeScript JSON-RPC 与 Python 打包运行时快照则通过两套 SDK 投影接受事件。真实 Loader 组合会固定默认包元数据、默认会话上传与显式关闭上传，一个真实 API 请求会挂载两个随附扩展并证明官方端点接受它们；pi-ai 测试保持其协议请求不变。
 
 ## 考虑过的替代方案
 
@@ -85,7 +85,7 @@ Status: implemented
 
 ## 后果
 
-DeepSeek 官方请求会把存活包版本发送到解析后的 `baseURL`，包括已配置 gateway。显式选择启用会话日志后，请求还会携带完整的未接受会话新后缀。这些字段对模型不可见，不增加提示词 token，也不改变 KV Cache，但可能显著增大 HTTP 正文。Manifest 解析、字段冲突、接受记录或提供方 schema 拒绝会使模型请求失败，而不会静默丢弃元数据。
+DeepSeek 官方请求会把存活包版本发送到解析后的 `baseURL`，包括已配置 gateway。除非关闭会话日志上传，否则符合条件的请求还会携带完整的未接受会话新后缀。这些字段对模型不可见，不增加提示词 token，也不改变 KV Cache，但可能显著增大 HTTP 正文。Manifest 解析、字段冲突、接受记录或提供方 schema 拒绝会使模型请求失败，而不会静默丢弃元数据。
 
 `delivery-accepted` 事件会成为权威日志的一部分，并在后续请求中自行交付。崩溃恢复可能重复后缀，但不会根据 assistant 输出推断接受，也不会创建第二份本地游标存储。缺少存活会话的直接调用会省略会话字段；宿主包清单仍然可用。
 
diff --git a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.i18n.yaml
index 7fd3cc3676..3dcffdc51a 100644
--- a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md
-2026-09-01-v2-embedded-assistant-streams.md: 219879600f8435a6ecc9593661dd3f463ed1158c
-2026-09-01-v2-embedded-assistant-streams.zh.md: d38c180b1f1de689620f2e0533d2b02f4a71e466
+2026-09-01-v2-embedded-assistant-streams.md: 89b494959fcc10a2c9847908adcf13d5eedcd749
+2026-09-01-v2-embedded-assistant-streams.zh.md: 63cb425740cd2243361ec00a6dadad82c38f6f0f
diff --git a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md
index 219879600f..89b494959f 100644
--- a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md
+++ b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md
@@ -31,7 +31,7 @@ The migration publication verifier and frozen v2 fixture validator require the e
 
 The Web follow adapter opts into these process-local frames and adds the last durable sequence observed at each start. It presents chunks as Client-only `assistant/live-chunk` updates between durable cursors, stages only a later matching settlement until the committed end, and reopens follow on a revision gap. A committed end publishes a named settlement delta that removes the attempt's transient matches, adds the durable entry, and replays only affected Conversation Contexts; an abandoned end publishes the same delta without an entry. A reconnect baseline carries the active attempt's durable start cursor and compact prefix.
 
-The Client event source passes durable settlements through unchanged. The Chat and Trajectory Assistant nodes fold `assistant/live-chunk` while an attempt is active, build settled output directly from `assistant/message`, and do not replay an `assistant/attempt` stream for presentation. Cold settled presentation therefore does not reconstruct per-token timing; other consumers may expand the durable stream when they require its exact evidence.
+The Client event source passes durable settlements through unchanged. Chat and Trajectory fold `assistant/live-chunk` while an attempt is active and build settled output directly from `assistant/message`. Chat does not reconstruct first-token timing after settlement retires the transient chunks. Trajectory reads timing from the [compact stream records](2026-09-06-embedded-stream-record-readers.md) in `assistant/message` and `assistant/attempt`, including when opening history. Neither target expands settled streams into per-delta objects for presentation; other consumers may expand the durable stream when they require its exact evidence.
 
 ### Released v1 to v2 migration
 
diff --git a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.zh.md b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.zh.md
index d38c180b1f..63cb425740 100644
--- a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.zh.md
@@ -31,7 +31,7 @@ Migration publication verifier 与冻结的 v2 fixture validator 要求嵌入式
 
 Web follow adapter 显式选择接收这些进程本地 frame，并为每个 start 补充当时观察到的最后一个持久序号。它把 chunk 呈现为持久 cursor 之间的 Client-only `assistant/live-chunk` update，只暂存 start 之后匹配的 settlement，并在 revision 缺口时重新打开 follow。committed end 会发布具名 settlement delta，删除该 attempt 的 transient match、加入持久 entry，并只重放受影响的 Conversation Context；abandoned end 会发布不含 entry 的同类 delta。重连 baseline 携带活跃 attempt 的持久起始 cursor 与紧凑前缀。
 
-Client event source 原样传递持久 settlement。Chat 与 Trajectory 的 Assistant node 在 attempt 活跃期间折叠 `assistant/live-chunk`，直接从 `assistant/message` 构建 settled output，并且不为展示重放 `assistant/attempt` stream。因此冷恢复的 settled presentation 不会重建逐 token timing；其他消费方需要精确证据时仍可展开持久 stream。
+Client event source 原样传递持久 settlement。Chat 与 Trajectory 在 attempt 活跃时折叠 `assistant/live-chunk`，直接从 `assistant/message` 构造 settled output。结算移除临时 chunk 后，Chat 不会重建首 token 计时。Trajectory 从 `assistant/message` 与 `assistant/attempt` 中的[紧凑流记录](2026-09-06-embedded-stream-record-readers.zh.md)读取计时，包括打开历史时。两个目标都不会为展示将已结算流展开为逐 delta 对象；其他消费方需要精确证据时仍可展开持久 stream。
 
 ### 已发布 v1 到 v2 迁移
 
diff --git a/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.i18n.yaml
index 60a3e40c85..f62b326074 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.md
-2026-09-05-canonical-feedback-log.md: c890064817ac0604fa4cc2b4073850174195e511
-2026-09-05-canonical-feedback-log.zh.md: e7e8563df8ad37d7aba641e58da4fc8872ec10b9
+2026-09-05-canonical-feedback-log.md: ce7b705b24cb0a4f7432215e19589095a9afc719
+2026-09-05-canonical-feedback-log.zh.md: 7d970ff7aea4962ea52c764fec5b6c07e3669099
diff --git a/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.md b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.md
index c890064817..ce7b705b24 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.md
@@ -14,7 +14,7 @@ The canonical Session log owns feedback. Session-level remarks use `feedback/rec
 
 Live message-feedback mutations append through the owning Session and await its durability checkpoint; cold mutations hold a persistence write handle across read, comparison, append, and flush without creating a Session or Agent. A matching no-op appends nothing but still awaits persistence. Failures propagate, and a failed live flush can leave an observable in-memory item for retry. Per-item versions prevent unrelated message edits from conflicting; strict stale-write rejection prevents ABA overwrites even when the desired value matches. Target validation binds a judgment to a sent assistant message, and forks keep independent judgments. These choices retain rationale recorded in the [archived sidecar decision](../../archived/architecture/2026-08-10-message-feedback-sidecar.md), whose storage and commit mechanism is superseded.
 
-The existing opt-in [session-log-deepseek contribution](../../../../packages/session/session-log-deepseek/README.md) includes feedback in the ordinary `dsh_session_log` suffix on a subsequent eligible request. It uses the existing DeepSeek destination selection and acceptance watermark. There is no separate `dsh_feedback` uploader, feedback-triggered LLM request, or model-input field. The [explicit-feedback OTel decision](2026-09-05-nonofficial-feedback-otel.md) owns the independent feedback-triggered upload for all users and providers.
+The existing default-on [session-log-deepseek contribution](../../../../packages/session/session-log-deepseek/README.md) includes feedback in the ordinary `dsh_session_log` suffix on a subsequent eligible request. It uses the existing DeepSeek destination selection and acceptance watermark. There is no separate `dsh_feedback` uploader, feedback-triggered LLM request, or model-input field. The [explicit-feedback OTel decision](2026-09-05-nonofficial-feedback-otel.md) owns the independent feedback-triggered upload for all users and providers.
 
 The command confirms recording with the Session and anonymous user ids, without depending on telemetry or disclosing its policy. Its append remains unflushed. This supersedes the command-copy decision in the [archived sharing disclosure note](../../archived/feature/2026-08-07-feedback-acknowledgement-sharing-disclosure.md). The [telemetry service's policy API](../../../../packages/session/session-telemetry/README.md#the-sharing-disclosure) remains independently available: a backend discloses its policy, not delivery or retention, and the optional OTel package does not own that vocabulary.
 
@@ -24,7 +24,7 @@ The command confirms recording with the Session and anonymous user ids, without
 
 **Reuse `feedback/record` for message edits.** A free-text Session remark does not identify an item mutation. Distinct events preserve message identity and deletion semantics; upload policy remains consumer-owned.
 
-**Add a dedicated feedback uploader or immediate LLM request.** The opt-in log contribution carries canonical events on eligible requests. The existing OTel pipeline independently handles explicit-feedback uploads for all providers, without a custom feedback uploader or another model request.
+**Add a dedicated feedback uploader or immediate LLM request.** The default-on log contribution carries canonical events on eligible requests. The existing OTel pipeline independently handles explicit-feedback uploads for all providers, without a custom feedback uploader or another model request.
 
 ## Consequences
 
diff --git a/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.zh.md b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.zh.md
index e7e8563df8..7d970ff7ae 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-canonical-feedback-log.zh.md
@@ -14,7 +14,7 @@ Status: implemented
 
 live 消息反馈变更通过所属 Session 追加，并等待其持久化检查点；cold 变更在读取、比较、追加和 flush 期间持有持久化写句柄，不创建 Session 或 Agent。匹配版本的无变更操作不追加事件，但仍等待持久化。故障会原样传播，live flush 失败可能留下可观测的内存条目以供重试。逐条版本避免不同消息的编辑互相冲突；严格拒绝陈旧写入避免 ABA 覆盖，即使期望值已经匹配也不例外。目标校验把判断绑定到已发送的 assistant 消息，fork 保持独立判断。这些选择保留[已归档伴随记录决策](../../archived/architecture/2026-08-10-message-feedback-sidecar.md)记载的理由，但其存储与提交机制已被取代。
 
-现有需显式启用的 [session-log-deepseek 贡献](../../../../packages/session/session-log-deepseek/README.zh.md)会在后续符合条件的请求中，把反馈纳入普通 `dsh_session_log` 后缀。它使用现有的 DeepSeek 目标选择和接受水位。没有独立的 `dsh_feedback` 上传器、反馈触发的 LLM 请求或模型输入字段。[显式反馈 OTel 决策](2026-09-05-nonofficial-feedback-otel.zh.md)负责面向所有用户和提供方的独立反馈触发上传。
+现有默认开启的 [session-log-deepseek 贡献](../../../../packages/session/session-log-deepseek/README.zh.md)会在后续符合条件的请求中，把反馈纳入普通 `dsh_session_log` 后缀。它使用现有的 DeepSeek 目标选择和接受水位。没有独立的 `dsh_feedback` 上传器、反馈触发的 LLM 请求或模型输入字段。[显式反馈 OTel 决策](2026-09-05-nonofficial-feedback-otel.zh.md)负责面向所有用户和提供方的独立反馈触发上传。
 
 命令用 Session 与匿名用户 id 确认记录，不依赖遥测，也不披露其策略。其追加仍不执行 flush。这取代[已归档共享披露记录](../../archived/feature/2026-08-07-feedback-acknowledgement-sharing-disclosure.md)中的命令文案决策。[遥测服务的策略 API](../../../../packages/session/session-telemetry/README.zh.md#the-sharing-disclosure) 仍可独立使用：后端披露策略，而不保证投递或保留，可选 OTel 包不拥有这套词汇。
 
@@ -24,7 +24,7 @@ live 消息反馈变更通过所属 Session 追加，并等待其持久化检查
 
 **对消息编辑复用 `feedback/record`。** 自由文本的 Session 备注不能标识条目变更。独立事件保留消息身份和删除语义；上传策略仍由消费方负责。
 
-**增加专用反馈上传器或立即发起 LLM 请求。** 需显式启用的日志贡献在符合条件的请求上传送权威事件。现有 OTel 流水线独立处理所有提供方的显式反馈上传，无需自定义反馈上传器或另一个模型请求。
+**增加专用反馈上传器或立即发起 LLM 请求。** 默认开启的日志贡献在符合条件的请求上传送权威事件。现有 OTel 流水线独立处理所有提供方的显式反馈上传，无需自定义反馈上传器或另一个模型请求。
 
 ## 后果
 
diff --git a/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.i18n.yaml
index 0db0adb2fd..58f161426a 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.md
-2026-09-05-nonofficial-feedback-otel.md: bbc947455f7a84a41af6651223eb62129fa8d452
-2026-09-05-nonofficial-feedback-otel.zh.md: de9b0322861118cdc1163a0faefb172fc1062776
+2026-09-05-nonofficial-feedback-otel.md: 8225d8bea030c4f09b60fd1a228f0425e9489d39
+2026-09-05-nonofficial-feedback-otel.zh.md: e8ea48b3fe2f228ef57ae1a20f92100dfc333f9c
diff --git a/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.md b/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.md
index bbc947455f..8225d8bea0 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.md
@@ -16,7 +16,7 @@ An authorized prefix includes all unhanded canonical context from seq 0 through
 
 The backend uses on-demand capture with complete history and the existing redaction waterfall. `DISABLED` constructs no transport. `FULL` is rejected rather than aliased. Direct `ctx.sessionTelemetry.emit()` calls are no-ops, so callers cannot bypass feedback authorization. SDK scheduled flush and shutdown may finish previously authorized batches but never capture new records. Sending after submission needs no further user interaction or model call.
 
-The [canonical-feedback decision](2026-09-05-canonical-feedback-log.md) owns storage, versions, deletion, and plain command confirmation. The [opt-in DeepSeek contribution](../../../../packages/session/session-log-deepseek/README.md) remains independent, with its existing destination and acceptance behavior.
+The [canonical-feedback decision](2026-09-05-canonical-feedback-log.md) owns storage, versions, deletion, and plain command confirmation. The [default-on DeepSeek contribution](../../../../packages/session/session-log-deepseek/README.md) remains independent, with its existing destination and acceptance behavior.
 
 ## Alternatives considered
 
@@ -28,6 +28,6 @@ The [canonical-feedback decision](2026-09-05-canonical-feedback-log.md) owns sto
 
 ## Consequences
 
-Handoff is best-effort, not collector acceptance. Same-object cursors suppress repeated capture, but fresh cold snapshots and new feedback after restart can repeat prefixes; receivers deduplicate on `(session.id, session.format_version, event.seq)`. There is no durable OTel outbox, delivery watermark, or harness HTTP retry promise. SDK batching and loss behavior apply after enqueue. OTel and the opt-in DeepSeek path can overlap. Withdrawal exports a deletion event, not remote erasure.
+Handoff is best-effort, not collector acceptance. Same-object cursors suppress repeated capture, but fresh cold snapshots and new feedback after restart can repeat prefixes; receivers deduplicate on `(session.id, session.format_version, event.seq)`. There is no durable OTel outbox, delivery watermark, or harness HTTP retry promise. SDK batching and loss behavior apply after enqueue. OTel and the default-on DeepSeek path can overlap. Withdrawal exports a deletion event, not remote erasure.
 
 [OTel tests](../../../../packages/session/session-telemetry-otel/tests/otel.spec.ts) cover explicit-feedback capture, provider-independent behavior, lifecycle silence, fork consent, cold commits, and direct-call denial. [Coordinator tests](../../../../packages/session/session-telemetry/tests/telemetry.spec.ts) cover history capture; [base tests](../../../../packages/bundle/base/tests/base.spec.ts) pin the mounted default.
diff --git a/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.zh.md b/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.zh.md
index de9b032286..e8ea48b3fe 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-nonofficial-feedback-otel.zh.md
@@ -16,7 +16,7 @@ Status: implemented
 
 后端使用包含完整历史的按需捕获与现有脱敏 waterfall（瀑布式事件）。`DISABLED` 不构造传输。`FULL` 被拒绝，不作为别名。直接调用 `ctx.sessionTelemetry.emit()` 是空操作，因此调用方不能绕过反馈授权。SDK 定时刷新和关闭可以完成先前已授权的批次，但绝不捕获新记录。提交后的发送无需进一步用户交互或模型调用。
 
-[权威反馈决策](2026-09-05-canonical-feedback-log.zh.md)负责存储、版本、删除与纯命令确认。[需主动开启的 DeepSeek 贡献](../../../../packages/session/session-log-deepseek/README.zh.md)保持独立，保留现有目标与接受行为。
+[权威反馈决策](2026-09-05-canonical-feedback-log.zh.md)负责存储、版本、删除与纯命令确认。[默认开启的 DeepSeek 贡献](../../../../packages/session/session-log-deepseek/README.zh.md)保持独立，保留现有目标与接受行为。
 
 ## 考虑过的替代方案
 
@@ -28,6 +28,6 @@ Status: implemented
 
 ## 后果
 
-交接尽力而为，不代表采集端接受。同对象游标抑制重复捕获，但新冷快照和重启后的新反馈可能重复前缀；接收方按 `(session.id, session.format_version, event.seq)` 去重。没有持久化 OTel outbox、投递水位或 harness HTTP 重试承诺。入队后适用 SDK 批处理与丢失行为。OTel 与需主动开启的 DeepSeek 路径可能重叠。撤回导出删除事件，不是远端擦除。
+交接尽力而为，不代表采集端接受。同对象游标抑制重复捕获，但新冷快照和重启后的新反馈可能重复前缀；接收方按 `(session.id, session.format_version, event.seq)` 去重。没有持久化 OTel outbox、投递水位或 harness HTTP 重试承诺。入队后适用 SDK 批处理与丢失行为。OTel 与默认开启的 DeepSeek 路径可能重叠。撤回导出删除事件，不是远端擦除。
 
 [OTel 测试](../../../../packages/session/session-telemetry-otel/tests/otel.spec.ts)覆盖显式反馈捕获、提供方无关行为、生命周期静默、fork 同意、冷会话提交与直接调用拒绝。[协调器测试](../../../../packages/session/session-telemetry/tests/telemetry.spec.ts)覆盖历史捕获；[基础配置测试](../../../../packages/bundle/base/tests/base.spec.ts)固定挂载默认值。
diff --git a/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.i18n.yaml
index a5e163f76e..f19cf66c4d 100644
--- a/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.md
-2026-09-06-embedded-stream-record-readers.md: 76e109de577d070093bb7123aa50d9a4ae7fcbe5
-2026-09-06-embedded-stream-record-readers.zh.md: 33f4b31117197c47e7f2ff1637bc13fa2cbf1a8c
+2026-09-06-embedded-stream-record-readers.md: efad86a4f940bf3b56d4b141a8fe1e3659c8dd9c
+2026-09-06-embedded-stream-record-readers.zh.md: f7131a27171163954bca8b7013dc6d90f907c552
diff --git a/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.md b/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.md
index 76e109de57..efad86a4f9 100644
--- a/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.md
+++ b/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.md
@@ -20,7 +20,7 @@ After v2 embedded streams settlement widened with the message content and Chat a
 - Run readers: `runFirstTokenTime` and `runFirstVisibleTime` reconstruct the first qualifying member's time from `time0` and the `dt` gaps and stop scanning there; a name-bearing Tool-call run yields `time0` without reading a fragment.
 - Stream readers: `assistantStreamFirstTokenTime`, `assistantStreamHasVisibleContent`, `assistantStreamHasVisibleText`, `lastAssistantStreamChunk(stream, type)` (backward scan), `assistantStreamChunks(stream, type)`, `joinAssistantStreamText`, and `assembleAssistantStream`, which feeds a `BlockAssembler` one joined delta per run (assembly only concatenates, so blocks, usage, finish, and replay state equal the per-member result). `RawStreamChunkType` excludes the delta types, so a raw-chunk lookup can never silently skip packed members.
 
-Session Stats, Chat, and Trajectory read `assistantStreamFirstTokenTime` from both `assistant/attempt` and `assistant/message`, retaining the Step's first token across retries. Chat and Trajectory settle content from the assembled message while reading timing independently, so reopening history retains TTFT and decoding metrics without expanding streams. The token meter reads `lastAssistantStreamChunk(stream, 'usage')` and assembles provider output through `assembleAssistantStream`; the subagent output fold appends `joinAssistantStreamText`; the Session Controller scans `assistantStreamChunks(stream, 'block-end')` for images.
+Session Stats and Trajectory read `assistantStreamFirstTokenTime` from both `assistant/attempt` and `assistant/message`, retaining the Step's first token across retries. Trajectory settles content from the assembled message while reading timing independently, so reopening history retains TTFT and decoding metrics without expanding streams. Chat follows its [settled-reply timing policy](../bug-fix/2026-09-14-chat-presentation-defaults.md). The token meter reads `lastAssistantStreamChunk(stream, 'usage')` and assembles provider output through `assembleAssistantStream`; the subagent output fold appends `joinAssistantStreamText`; the Session Controller scans `assistantStreamChunks(stream, 'block-end')` for images.
 
 `expandAssistantStream` keeps its strict validation and its remaining callers, which need every member or validate the stream at a durable boundary: Session restore validation, the v1-to-v2 migration validator and publication Worker replay, the reconnect baseline, and test support.
 
diff --git a/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.zh.md b/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.zh.md
index 33f4b31117..f7131a2717 100644
--- a/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-06-embedded-stream-record-readers.zh.md
@@ -20,7 +20,7 @@ Session 格式 v2 将每次模型尝试的紧凑流（`AssistantStreamRecord[]`
 - Run 读取器：`runFirstTokenTime` 与 `runFirstVisibleTime` 从 `time0` 与 `dt` 间隔重建首个合格成员的时间并停止扫描；带名称的 Tool-call run 直接产出 `time0`，不读片段。
 - 流读取器：`assistantStreamFirstTokenTime`、`assistantStreamHasVisibleContent`、`assistantStreamHasVisibleText`、`lastAssistantStreamChunk(stream, type)`（逆向扫描）、`assistantStreamChunks(stream, type)`、`joinAssistantStreamText` 与 `assembleAssistantStream`（每个 run 向 `BlockAssembler` 喂入一个拼接后的 delta；组装只做拼接，因此 blocks、usage、finish 与 replay state 与逐成员结果一致）。`RawStreamChunkType` 排除 delta 类型，因此原始 chunk 查找不可能静默跳过打包成员。
 
-Session Stats、Chat 与 Trajectory 从 `assistant/attempt` 和 `assistant/message` 读取 `assistantStreamFirstTokenTime`，跨重试保留步骤的首个 token。Chat 与 Trajectory 从组装后的消息结算内容，并独立读取计时，因此重新打开历史时无需展开流便能保留 TTFT 与解码指标。token 计量读取 `lastAssistantStreamChunk(stream, 'usage')` 并通过 `assembleAssistantStream` 组装提供商输出；子代理输出折叠追加 `joinAssistantStreamText`；Session Controller 用 `assistantStreamChunks(stream, 'block-end')` 扫描镜像。
+Session Stats 与 Trajectory 从 `assistant/attempt` 和 `assistant/message` 读取 `assistantStreamFirstTokenTime`，跨重试保留步骤的首个 token。Trajectory 从组装后的消息结算内容，并独立读取计时，因此重新打开历史时无需展开流便能保留 TTFT 与解码指标。Chat 遵循[已结算回复的计时策略](../bug-fix/2026-09-14-chat-presentation-defaults.zh.md)。token 计量读取 `lastAssistantStreamChunk(stream, 'usage')` 并通过 `assembleAssistantStream` 组装提供商输出；子代理输出折叠追加 `joinAssistantStreamText`；Session Controller 用 `assistantStreamChunks(stream, 'block-end')` 扫描镜像。
 
 `expandAssistantStream` 保留其严格校验与其余调用方（需要每个成员或在持久边界校验流）：Session 恢复校验、v1-to-v2 迁移校验器与发布 Worker 重放、重连基线、测试支撑。
 
diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml
index 7f1944282d..511e949e4c 100644
--- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
-2026-09-08-document-preview-operations.md: 3703933273e743c8df32bf0352fc276fe21dcb93
-2026-09-08-document-preview-operations.zh.md: b4896e95959d0f276ee69dfeaee9528319981714
+2026-09-08-document-preview-operations.md: 43cc8d935763512a53379466bb796b5cac469793
+2026-09-08-document-preview-operations.zh.md: 44eccba894b3748a1d8640561a9eb760de481919
diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
index 3703933273..43cc8d9357 100644
--- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
+++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
@@ -16,9 +16,9 @@ Document Preview separates resource observation from content reads. The [resourc
 
 Readable files use `dsh-resource://file/session/<sessionId>/<path>`. The path may be workspace-relative or absolute; an encoded absolute path retains its leading slash. `fileAddressFor` always emits this Session-address form. The provider and Preview RPC take the Session only from that address, never from the current selection, first holder, or owning tab. A Session-less `absolute` URI cannot be read; the provider reports `workspace-file/unknown-workspace`. Session authorization is a file-protocol rule, not an additional Resource identity.
 
-[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.md) owns format selection and loading policy. Metadata registers with `ctx.documentPreviews`; components register separately into the keyed `sidebar.right.tab.document` Slot. Extension registrations precede builtins, then longer suffixes and registration order decide. The toolbar lists matching alternatives and remembers a manual choice per tab; plain text is the fallback. The child receives accumulated text or complete native bytes, the original resource address, and the standard `useResource` and `useTabInfo` hooks. Preview calls existing `read`, `readAll`, and `readRelated` through ordinary injection and decodes bytes in its own `rpc.ts`. Refresh remains per tab, with no resource reload, shared `changed` acknowledgement, extra resource wrapper, or content Session.
+[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.md) owns format selection and loading policy. Metadata registers with `ctx.documentPreviews`; components register separately into the keyed `sidebar.right.tab.document` Slot. Extension registrations precede builtins, then longer suffixes and registration order decide. The toolbar lists matching alternatives only when at least two exist and remembers a manual choice per tab; plain text is the fallback except for suffixes a registration declares binary or the owner's unviewable list names ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The child receives accumulated text or complete native bytes, the original resource address, and the standard `useResource` and `useTabInfo` hooks. Preview calls existing `read`, `readAll`, and `readRelated` through ordinary injection and decodes bytes in its own `rpc.ts`. Refresh remains per tab, with no resource reload, shared `changed` acknowledgement, extra resource wrapper, or content Session.
 
-Markdown and code reuse the incremental primitives with cumulative paged text. HTML, PDF, and images read complete `Uint8Array<ArrayBuffer>` data; Host transport remains base64. Published buffers are borrowed read-only and never persist into layout or Session JSON. PDF.js runs in an owned Worker with version-matched bundled font and decoder data, and copies input before transfer to preserve Preview's retained buffer. HTML runs in a Blob iframe with `sandbox="allow-scripts"`, without same-origin, popup, form, download, or top-navigation privileges. The browser retains its normal external-network rules. Bounded static local JS/CSS reads stay in the parent; the opaque frame creates its own asset Blobs, because it cannot load parent-origin Blobs. PNG, JPEG, GIF, WebP, BMP, ICO, and SVG use image-specific Blob URLs in an `<img>` static-image context. They retain intrinsic CSS-pixel dimensions; auto margins centre images smaller than the shared scroller, while larger dimensions extend its horizontal or vertical scroll range. The renderer provides no zoom or drag-to-pan. SVG markup never enters the application DOM or an iframe, so scripts remain inert and cannot reach the parent page. Replacing HTML or an image revokes its root Blob URL.
+Markdown and code reuse the incremental primitives with cumulative paged text. HTML, PDF, and images read complete `Uint8Array<ArrayBuffer>` data; Host transport remains base64. Published buffers are borrowed read-only and never persist into layout or Session JSON. PDF.js runs in an owned Worker with version-matched bundled font and decoder data, and copies input before transfer to preserve Preview's retained buffer. HTML runs in a Blob iframe with `sandbox="allow-scripts"`, without same-origin, popup, form, download, or top-navigation privileges. The browser retains its normal external-network rules. Bounded static local JS/CSS reads stay in the parent; the opaque frame creates its own asset Blobs, because it cannot load parent-origin Blobs. PNG, JPEG, GIF, WebP, BMP, ICO, and SVG use image-specific Blob URLs in an `<img>` static-image context. An image wider than the pane scales down to its width at its aspect ratio; a smaller image keeps its intrinsic CSS-pixel dimensions centred by auto margins, and a taller image extends the shared scroller's vertical range ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The renderer provides no zoom or drag-to-pan. SVG markup never enters the application DOM or an iframe, so scripts remain inert and cannot reach the parent page. Replacing HTML or an image revokes its root Blob URL.
 
 ## Alternatives considered
 
@@ -38,4 +38,4 @@ Markdown and code reuse the incremental primitives with cumulative paged text. H
 
 ## Consequences
 
-Renderers can be replaced without changing the tab or file protocol. Full-file formats pay bounded whole-file memory and PDF adds bundled Worker/font/decoder bytes. Format selection and view state are page-local, not durable Session data. Preview owns RPC cancellation and native buffers independently of metadata observation. A tab retains its read version and the observation version captured at read start; refreshing it neither discards another tab's content nor clears its change notice. File reads remain non-transactional, and opaque versions are compared for equality, not ordering. The [recorded browser scenario](../../../../apps/web/tests/document-preview.e2e.ts) exercises the shared toolbar, incremental text, isolated HTML dependencies, intrinsic raster and SVG rendering with two-axis scrolling, inert SVG scripts, and lazy continuous PDF Worker rendering.
+Renderers can be replaced without changing the tab or file protocol. Full-file formats pay bounded whole-file memory and PDF adds bundled Worker/font/decoder bytes. Format selection and view state are page-local, not durable Session data. Preview owns RPC cancellation and native buffers independently of metadata observation. A tab retains its read version and the observation version captured at read start; refreshing it neither discards another tab's content nor clears its change notice. File reads remain non-transactional, and opaque versions are compared for equality, not ordering. The [recorded browser scenario](../../../../apps/web/tests/document-preview.e2e.ts) exercises the shared toolbar, incremental text, isolated HTML dependencies, width-fitted raster and SVG rendering, inert SVG scripts, and lazy continuous PDF Worker rendering.
diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md
index b4896e9595..44eccba894 100644
--- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md
@@ -16,9 +16,9 @@ Document Preview 将资源观察与内容读取分开。[资源模型](2026-09-0
 
 可读取的文件使用 `dsh-resource://file/session/<sessionId>/<path>`。路径可以相对工作区，也可以是绝对路径；编码后的绝对路径保留前导斜杠。`fileAddressFor` 始终生成这种 Session 地址。提供方与 Preview RPC 只从该地址取 Session，不取当前选择、首个持有者或 tab 所属 Session。不带 Session 的 `absolute` URI 无法读取；提供方报告 `workspace-file/unknown-workspace`。Session 授权是文件协议规则，不是额外的 Resource 身份。
 
-[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md) 负责格式选择和加载策略。元数据通过 `ctx.documentPreviews` 注册；组件单独注册到 keyed `sidebar.right.tab.document` Slot。扩展注册优先于内置注册，其次比较后缀长度和注册顺序。工具栏列出匹配候选，按 tab 记住手动选择；纯文本是兜底。子组件收到累积文本或完整原生字节、原始资源地址，以及标准 `useResource` 和 `useTabInfo` 钩子。Preview 经普通注入调用既有 `read`、`readAll` 与 `readRelated`，在自己的 `rpc.ts` 解码字节。刷新仍按 tab 独立进行，不引入资源 reload、共享 `changed` 确认、额外资源包装层或内容 Session。
+[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md) 负责格式选择和加载策略。元数据通过 `ctx.documentPreviews` 注册；组件单独注册到 keyed `sidebar.right.tab.document` Slot。扩展注册优先于内置注册，其次比较后缀长度和注册顺序。工具栏仅在候选不少于两个时列出匹配候选，按 tab 记住手动选择；纯文本是兜底，但注册声明为二进制的后缀和 owner 的 unviewable 清单所列后缀除外（[侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md)）。子组件收到累积文本或完整原生字节、原始资源地址，以及标准 `useResource` 和 `useTabInfo` 钩子。Preview 经普通注入调用既有 `read`、`readAll` 与 `readRelated`，在自己的 `rpc.ts` 解码字节。刷新仍按 tab 独立进行，不引入资源 reload、共享 `changed` 确认、额外资源包装层或内容 Session。
 
-Markdown 和代码通过累积的分页文本复用增量渲染原语。HTML、PDF 和图片读取完整 `Uint8Array<ArrayBuffer>` 数据；Host 传输保持 base64。发布后的缓冲区只读借用，绝不持久化进布局或 Session JSON。PDF.js 在自有 Worker 中运行，字体和解码数据以相同版本随包发布，转移输入前先复制，以保留 Preview 的缓冲区。HTML 在 Blob iframe 中运行，设置 `sandbox="allow-scripts"`，不授予同源、弹窗、表单、下载或顶层导航权限。浏览器保持正常的外部网络规则。有上限的静态本地 JS/CSS 读取由父页面负责；不透明源 iframe 创建自己的资源 Blob，因为它不能加载父源创建的 Blob。PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 使用图片专用 Blob URL，在 `<img>` 静态图片上下文中渲染。它们保留固有 CSS 像素尺寸；auto margin 让小于共享滚动区的图片居中，较大的尺寸则扩展横向或纵向滚动范围。渲染器不提供缩放或拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此脚本保持不可执行，也无法访问父页面。替换 HTML 或图片时会撤销其根 Blob URL。
+Markdown 和代码通过累积的分页文本复用增量渲染原语。HTML、PDF 和图片读取完整 `Uint8Array<ArrayBuffer>` 数据；Host 传输保持 base64。发布后的缓冲区只读借用，绝不持久化进布局或 Session JSON。PDF.js 在自有 Worker 中运行，字体和解码数据以相同版本随包发布，转移输入前先复制，以保留 Preview 的缓冲区。HTML 在 Blob iframe 中运行，设置 `sandbox="allow-scripts"`，不授予同源、弹窗、表单、下载或顶层导航权限。浏览器保持正常的外部网络规则。有上限的静态本地 JS/CSS 读取由父页面负责；不透明源 iframe 创建自己的资源 Blob，因为它不能加载父源创建的 Blob。PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 使用图片专用 Blob URL，在 `<img>` 静态图片上下文中渲染。比面板宽的图片按纵横比缩小到面板宽度；较小的图片保留固有 CSS 像素尺寸并由 auto margin 居中，较高的图片扩展共享滚动区的纵向范围（[侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md)）。渲染器不提供缩放或拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此脚本保持不可执行，也无法访问父页面。替换 HTML 或图片时会撤销其根 Blob URL。
 
 ## 考虑过的替代方案
 
@@ -38,4 +38,4 @@ Markdown 和代码通过累积的分页文本复用增量渲染原语。HTML、P
 
 ## 影响
 
-替换渲染器不需要改变 Tab 或文件协议。全文格式承担有上限的整文件内存成本，PDF 增加随包发布的 Worker、字体和解码器字节。格式选择和查看状态仅属于当前页面，不是持久 Session 数据。Preview 独立于元数据观察，拥有 RPC 取消和原生缓冲区。tab 保留读取版本及读取开始时捕获的观察版本；刷新它既不丢弃其他 tab 的内容，也不清除其变更提示。文件读取仍非事务，不透明版本只比较相等性、不排序。[录制的浏览器场景](../../../../apps/web/tests/document-preview.e2e.ts) 覆盖共用工具栏、增量文本、隔离的 HTML 依赖、可双轴滚动的固有尺寸位图与 SVG 渲染、不可执行的 SVG 脚本，以及惰性连续 PDF Worker 渲染。
+替换渲染器不需要改变 Tab 或文件协议。全文格式承担有上限的整文件内存成本，PDF 增加随包发布的 Worker、字体和解码器字节。格式选择和查看状态仅属于当前页面，不是持久 Session 数据。Preview 独立于元数据观察，拥有 RPC 取消和原生缓冲区。tab 保留读取版本及读取开始时捕获的观察版本；刷新它既不丢弃其他 tab 的内容，也不清除其变更提示。文件读取仍非事务，不透明版本只比较相等性、不排序。[录制的浏览器场景](../../../../apps/web/tests/document-preview.e2e.ts) 覆盖共用工具栏、增量文本、隔离的 HTML 依赖、按宽度适配的位图与 SVG 渲染、不可执行的 SVG 脚本，以及惰性连续 PDF Worker 渲染。
diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.i18n.yaml
new file mode 100644
index 0000000000..aac049979c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.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-09-profile-resolution-generations.md
+2026-09-09-profile-resolution-generations.md: 09ea70e49a4c876eac88e58262644e76c058fca5
+2026-09-09-profile-resolution-generations.zh.md: 0f852e9d31ef4c362f341d6b8fb6d5560225240f
diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md
new file mode 100644
index 0000000000..09ea70e49a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.md
@@ -0,0 +1,118 @@
+# Agent Note: Add immutable profile resolution generations
+
+Status: implemented
+
+English | [中文](2026-09-09-profile-resolution-generations.zh.md)
+
+## Problem
+
+A profile loads plugin rows from its own package project, while Harness packages and packages carried by selected bundles can live outside that project's ordinary dependency tree. The current launcher bridges the trees by calculating package precedence at startup and materializing that result as shared symlinks, profile-owned links, or packaged-executable proxy packages. The files persist across processes and installations, require reconciliation and locking, expose generated proxy manifests to metadata readers, and cannot represent a process-local change atomically.
+
+The runtime design preserves the existing selection rules rather than introducing a second package policy. It covers imports performed by plugin modules as well as Loader row imports and works in the main thread and Harness-owned Workers. Generation replacement accepts only additive package sets and never mutates a live table entry by entry.
+
+## Decision
+
+Profile startup computes one immutable `ResolutionGeneration` from the same dependency traversal that supplies the disk module fallback. The launcher defaults to link mode and preserves the existing materialized lookup behavior. Internal callers and tests can select runtime mode, which installs the generation into Node's ESM and CommonJS resolvers, or dual mode, which materializes and verifies the same generation. `PluginPackages.replace()` publishes a complete additive successor with one reference replacement.
+
+### One selection algorithm
+
+The package traversal remains in `@deepseek-ai/dsh-app-boot` beside profile loading. The disk materializer and the runtime resolver consume one pure plan; neither owns a copy of the precedence algorithm. Ordinary Node callers can select link, dual, or runtime mode, while an omitted mode selects link. Packaged executables and the Electron Host select runtime mode because their dependency trees may live in a virtual filesystem; dual remains an internal comparison path.
+
+The installation manifest is the first root. Its graph traverses `dependencies` followed by `peerDependencies` breadth-first, resolving each edge from the manifest that declares it. The first installed package reached under a name owns that name. Selected bundle roots then run in profile order, with each earlier root's complete graph taking precedence over every later root. Names supplied by the installation are reserved, and bundle package roots themselves do not become plugin fallbacks. Missing declared packages are skipped as before.
+
+Profile-local and plugin-private `node_modules` entries stay outside the fallback entries, and Node checks them before the virtual fallback position. The generation records only installed direct profile package names for a no-I/O native fast path. Each fallback entry records the package name, version, selected lookup directory, declaring manifest anchor, and scope needed to rerun Node's native resolution from the selected package and validate that a successor preserves existing mappings.
+
+The existing `healProfilesModuleFallback()` remains as the disk materializer for the same computed result, which permits direct comparison without rewriting the selection rules. The launcher uses it by default. Runtime mode computes the generation without materializing it, while dual mode materializes and installs that generation for comparison.
+
+### Immutable generations
+
+A resolver registration holds one `current` generation. Each synchronous resolution captures that reference once. Generation construction reads every required manifest before publication; an error leaves the current generation unchanged. Successful publication replaces one reference, and in-flight calls may finish against the generation they captured.
+
+Selection and package-metadata caches belong to a generation. Publishing a successor invalidates them by making the old generation unreachable after its callers finish; update code does not mutate or clear individual entries. A generation hit and a successful native selection can be cached, but a generation miss is rescanned so a profile-local package installed after the miss becomes visible as it does in link mode. Calls with explicit CommonJS paths or non-default conditions never reuse a default-resolution cache entry.
+
+The launcher constructs one startup generation. The service accepts an additive successor, but no package-manager transaction invokes replacement in this implementation.
+
+### Shared ESM and CommonJS rule
+
+The resolver uses `node-addon-require-builtin` to read `internal/modules/esm/loader` and `internal/modules/cjs/loader`. The ESM adapter wraps the per-thread singleton `CascadedLoader` resolve methods. The CommonJS adapter wraps the internal builtin's `Module._resolveFilename`; that `Module` is the same object exported by `node:module`.
+
+Both adapters call one routing function. It ignores builtins, relative or absolute paths, URLs, parents outside the profile scope, and explicit calls outside the supported lookup. A `#imports` request uses Node's mapping from its owning manifest; an external bare target follows the same local, generation, and after-fallback package order with the request's conditions, while Node retains exact target resolution. For a scoped bare request, a package self-reference keeps the original parent even when an npm alias gives its installed directory another name. A profile-local or plugin-private package also keeps the original parent when Node resolves the requested entry before the virtual shared-fallback position; a CommonJS package directory without `exports` does not suppress the fallback when only its requested subpath is absent. Otherwise the router uses a generation hit through that entry's declaring anchor or continues native lookup after the virtual fallback. Explicit CommonJS path lists apply the same insertion rule independently to each path in caller order.
+
+The adapters call the captured native resolver after routing. Node remains responsible for exports, import and require conditions, main files, subpaths, extensions, native caches, and error codes. Routed ESM failures replace the internal lookup anchor in Node's diagnostic with the original importer. A selected package's invalid export or missing target does not trigger another same-name candidate. CommonJS does not replace `_findPath` or reproduce `_resolveFilename`.
+
+The guarantee covers Node's default `import`, `import()`, `import.meta.resolve`, `require`, and `require.resolve` after installation in that thread. It does not cover already linked modules, custom `vm` linkers, opaque non-Node importers, or third-party Workers.
+
+### Active plugin list and package metadata
+
+The resolution generation lists available fallback packages; Loader entries form the active plugin list. Consumers keep using Loader's existing entry lifecycle and filter the entries relevant to their own scope. Consumers that need package metadata pass a specifier and owning tree base URL to a lightweight `app-boot` service without requiring a `./package.json` export. An installed generation is authoritative, including a miss; a service created without a generation retains native lookup for low-level embedders.
+
+The resolver does not expose `imported(entry)` and does not observe ModuleJobs, wrap Entry methods, associate fibers with import calls, replace registry or tree methods, or adapt HMR transactions. A repeated query uses the same generation and therefore cannot drift from the route used for the import. Non-Node importers that need package metadata must explicitly implement the same deterministic resolver interface.
+
+The implementation lives under `app-boot/src/profile-resolution/`. `service.ts` provides the long-lived `ctx.pluginPackages` and owns the main-thread resolver and Worker-generation lifetimes; `resolver.ts` implements generation lookup and the Node Internal adapters; `worker-bootstrap.ts` installs an inherited generation in one thread. Existing profile selection and disk materialization remain in `profile.ts`. Workers reference the bootstrap only through the public `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` export.
+
+The service definition and provider remain together in `app-boot` because profile boot owns the resolver lifetime. Extracting a separate capability seam becomes warranted when a launcher-independent provider or independently evolving consumers require it.
+
+### Workers and generation updates
+
+The main thread publishes a structured-clone representation of the current generation through Worker environment data. Each built Harness-owned Worker uses its build banner to obtain its own ESM and CommonJS internal objects and install the same adapters without traversing manifests. The bootstrap bundle has no static package imports. Source Worker entries retain their existing self-contained dependencies. Third-party Workers remain unchanged.
+
+New Workers inherit the latest published generation. Existing Workers keep the generation they inherited, so a caller that publishes a successor must restart them. The ESM bootstrap cannot affect static dependencies linked before its execution, so Worker bundles keep pre-bootstrap static imports natively resolvable and start code needing the profile resolver through a later dynamic import.
+
+### Additive package changes
+
+A caller adding a package completes its pnpm transaction before constructing a successor generation. Replacement rejects any generation that changes the directory or version of an existing package. The caller publishes an additive successor before mounting the new Loader row; this implementation does not provide that package transaction. A mount failure may leave the package installed but inactive.
+
+Replacing, upgrading, or removing an already loaded package requires process restart because Node's ESM Module Map, CommonJS cache, existing object references, and running Workers can retain the old module identity. Generation replacement does not claim to unload modules.
+
+### Disk migration
+
+Runtime-only launch paths do not create, update, or retire symlinks and proxy packages. The resolver treats the legacy shared fallback and `.dsh-module-fallback` projections as virtual insertion positions: a generation hit uses the table target, while a miss skips those old positions before continuing native ancestor lookup. During a dual phase, the launcher materializes and installs the same generation; tests disable each backend in turn and compare their targets.
+
+Legacy disk state remains available to link-only launches, old processes, and rollback without participating in runtime-only selection. Removing that state is a separate maintenance operation outside this change.
+
+### Mode behavior
+
+Link, dual, and runtime modes use the same generation schema and dependency-selection policy. Link mode persists the computed result, runtime mode installs it only in the process, and dual mode requires Node's materialized result to equal the generation route.
+
+The `dsh` launcher selects link mode when an ordinary Node caller omits `resolutionMode`, so existing npm-installed profile startup keeps its filesystem behavior. A pkg executable always selects runtime mode, and the Electron Host installs its runtime generation before any profile row mounts. Tests and low-level embedders can still select runtime or dual explicitly.
+
+Runtime mode requires a supported Node Internal loader interface and does not create, update, or retire fallback links. Dual mode retains link writes and fails when Node's disk result differs from the generation. Writable profile state and package-manager transactions remain outside the resolver.
+
+Pkg and packaged Electron carriers force runtime resolution. The Electron Host runs through the Electron executable with `ELECTRON_RUN_AS_NODE=1`, reads its dsh tree from ASAR, and maps executable ASAR entries to electron-builder's unpacked tree. Neither carrier creates, updates, or removes legacy resolution links.
+
+### Performance and verification
+
+Generation construction is startup or update work, not resolve work, and its absolute latency is reported separately. Ordinary hot paths consist of scope classification, bare-name extraction, local-before-fallback selection, a Map lookup, and one native resolution; a cache hit returns the generation-owned result directly. A CommonJS request may perform one native probe followed by one routed resolution when a local package directory exists without `exports` but lacks the requested subpath. Out-of-scope calls do not read manifests and cache only whether each parent belongs to the profile scope.
+
+One-off local measurements taken during implementation ran built JavaScript under plain Node in fresh processes and compared it with a process that installed no hook. The measurement script and results are not committed, and these figures are not a benchmark or CI budget. Seven alternating rounds covered outside, profile-local, and fallback imports through dynamic import, `import.meta.resolve`, require, and `require.resolve`. Across Node 22.19, 24.18, and 26.8, the largest positive hot-path median was 4.5%. On Node 24.18, a 256-package cold workload regressed by at most 11.2% and generation construction took 16.027 ms median; the 32-package local `require.resolve` case added 1.033 ms across the batch (+34.7%) from fixed startup cost.
+
+Behavior tests compare the runtime generation with the disk materializer over the same package trees, then exercise root order, transitive and peer dependencies, local and external precedence, exports and subpath errors, conditions, and explicit CommonJS options. The Node compatibility matrix runs the resolver, service, and bootstrap specifications across the supported internal-loader variants. Worker tests verify environment-data publication and bootstrap installation with mocked thread and native-loader interfaces; they do not launch a built Worker. Generation tests prove failed construction does not publish partial state and successful replacement is atomic.
+
+## Alternatives considered
+
+**Keep disk projections permanently.** This preserves native lookup without process hooks, but retains cross-process mutation, stale generations, proxy manifests, writer locks, and packaged-runtime divergence. A bounded dual migration remains useful because both backends consume the same generation.
+
+**Expand the dependency graph lazily during resolve.** This spreads manifest reads and errors across first-use calls, changes timing from the disk implementation, complicates Worker startup, and makes the hot path depend on graph size. Complete generation construction is easier to compare and replace atomically.
+
+**Use `module.registerHooks`.** The public API puts every relevant resolution through Node's global hook dispatch before profile scope can reject it. Direct access to the existing internal ESM and CommonJS resolver objects permits a smaller fast path while retaining Node as the final resolver.
+
+**Record each Entry's actual import through Loader and HMR adapters.** Actual import records support stateful resolvers that return different targets for identical inputs. This design instead makes the generation authoritative and deterministic, so those records duplicate the resolver's answer while adding Entry, fiber, registry, ModuleJob, and HMR lifecycle state.
+
+**Mutate one long-lived table after each package operation.** Incremental mutation exposes partial graphs and requires targeted cache invalidation. Building a complete successor makes failure atomic and keeps all caches generation-owned.
+
+**Hot-replace already loaded package versions.** A resolution-table swap cannot invalidate every live module instance or object reference. Restart preserves one package identity per process.
+
+## Verification
+
+- One eager computation supplies the retained disk materializer and runtime generation.
+- Link-only, dual, and runtime-only tests consume the same generation; runtime startup neither writes nor retires module-resolution data.
+- Pkg and Electron carriers select runtime resolution; Electron executes its Host in Node mode from the ASAR-backed dsh tree while native executable entries remain unpacked.
+- ESM and CommonJS adapters share one router and delegate final resolution to Node without `module.registerHooks` or `_findPath` replacement.
+- Production metadata lookup does not record Loader import results or wrap Entry, registry, tree, or HMR methods.
+- The Node compatibility matrix runs main-thread resolver specifications across supported loader interfaces; service and bootstrap specifications cover Worker environment-data and installation interfaces without launching a built Worker.
+- One-off built plain-Node measurements produced the hot and cold observations above against no-hook Node; the script and results are not committed evidence.
+- Package READMEs, architecture references, generated catalogs, and the bilingual pair describe the shipped implementation.
+
+## Consequences
+
+Runtime startup avoids disk mutation and proxy manifests while preserving the existing package-selection algorithm. It accepts the maintenance cost of Node Internal compatibility tests and an early, self-contained bootstrap in each owned Worker. Link remains the ordinary Node launcher default, dual keeps a migration comparison path, and pkg plus Electron carriers force runtime resolution without retiring old links. Generation replacement remains additive until the product owns module-cache invalidation and Worker restart.
diff --git a/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md
new file mode 100644
index 0000000000..0f852e9d31
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-09-profile-resolution-generations.zh.md
@@ -0,0 +1,118 @@
+# Agent Note: 增加不可变 profile 解析代际
+
+Status: implemented
+
+[English](2026-09-09-profile-resolution-generations.md) | 中文
+
+## Problem
+
+profile 从自己的包项目加载插件配置项，而 Harness 包和所选 bundle 携带的包可能位于该项目普通依赖树之外。当前启动器在启动时计算包优先级，再将结果物化为共享 symlink、profile 自有链接或打包可执行文件的代理包。文件跨进程和安装版本持续存在，需要协调和锁来维护，并向元数据读取方暴露生成的代理 manifest，也无法原子表示进程内变更。
+
+运行时设计保留现有选包规则，不另建一套包策略。它覆盖插件模块内部的 import 以及 Loader 配置项的 import，并在主线程和 Harness 自有 Worker 中工作。generation 替换只接受新增包的集合，不会逐项修改正在使用的表。
+
+## Decision
+
+profile 启动从磁盘 module fallback 使用的同一套依赖遍历生成一个不可变 `ResolutionGeneration`。launcher 默认使用 link 模式，保留现有的物化查找行为。内部调用方和测试可以选择 runtime 模式，把 generation 安装到 Node 的 ESM 与 CommonJS resolver；也可以选择 dual 模式，同时物化并校验同一份 generation。`PluginPackages.replace()` 通过一次引用替换发布完整的新增型后继 generation。
+
+### 唯一选包算法
+
+包遍历继续放在 `@deepseek-ai/dsh-app-boot` 的 profile 加载代码旁。磁盘 materializer 和运行时解析器消费同一个纯计划；两者都不持有另一份优先级算法。普通 Node 调用方可以选择 link、dual 或 runtime 模式，省略模式时使用 link。打包可执行文件与 Electron Host 会选择 runtime，因为其依赖树可能位于虚拟文件系统；dual 保留为内部对比路径。
+
+安装 manifest 是第一个根。它按 BFS 依次遍历 `dependencies` 和 `peerDependencies`，每条边从声明它的 manifest 解析，同名包由第一次找到的已安装包占有。所选 bundle 随后按 profile 顺序逐根遍历；每个较早根的完整依赖图优先于所有较晚根。安装闭包中的名称被保留，bundle 包根本身不成为插件 fallback。与旧行为相同，已声明但未安装的包会被跳过。
+
+profile 本地和插件私有 `node_modules` 不进入 fallback entries，由 Node 在虚拟 fallback 位置之前选择。generation 只记录已安装的 profile 直接包名用于 native 快速分流；每个 fallback 记录包名、版本、旧规则选中的查找目录、声明该边的 manifest 锚点和作用域，足以从选定包重新进入 Node 原生解析并验证换代保持既有映射。
+
+旧 `healProfilesModuleFallback()` 保留为相同纯计算结果的磁盘 materializer，便于直接比较并避免重写旧规则。launcher 默认调用它。runtime 模式只计算 generation 而不物化，dual 模式会物化并安装该 generation 进行比较。
+
+### 不可变 generation
+
+一个解析器 registration 持有一个 `current` generation。每个同步 resolve 在入口只捕获一次该引用，完整调用只读该引用。generation 构造在发布前读取所有必需 manifest；失败时当前 generation 不变。发布成功只替换一个引用，执行中的调用可以继续使用它已捕获的 generation。
+
+选包缓存和包元数据缓存归 generation 所有。发布下一代后，旧 generation 在调用方退出后自然不可达，不逐项清理缓存。generation 命中和原生解析成功结果可以缓存，但 generation 未命中会重新扫描，因此未命中后安装的 profile 本地包会像 link 模式一样变为可见。显式 CommonJS paths 或非默认 conditions 不得复用默认解析缓存。
+
+launcher 只构造启动 generation。服务接受新增型后继 generation，但本实现没有包管理器事务调用替换操作。
+
+### ESM 与 CommonJS 共用规则
+
+resolver 使用 `node-addon-require-builtin` 读取 `internal/modules/esm/loader` 和 `internal/modules/cjs/loader`。ESM 适配器包装每线程单例 `CascadedLoader` 的 resolve 方法。CommonJS 适配器包装内部 builtin 导出的 `Module._resolveFilename`；该 `Module` 与 `node:module` 导出的对象相同。
+
+两个适配器调用同一个路由函数。builtin、相对或绝对路径、URL、profile 作用域外 parent 和支持的查找以外的显式调用都直接委托原生实现。`#imports` 请求使用所属 manifest 中的 Node 映射；外部 bare target 按相同 conditions 遵循本地包、generation 和 after-fallback 的选包顺序，精确 target 解析仍由 Node 负责。对于作用域内的 bare request，package self-reference 保留原 parent，即使 npm alias 使安装目录使用另一个名称。Node 能在虚拟共享 fallback 之前从 profile 本地包或插件私有包解析到所请求入口时，也保留原 parent；没有 `exports` 的 CommonJS 包目录仅缺少所请求 subpath 时，不会压过 fallback。其他请求在 generation 命中时通过该条目的声明锚点解析，未命中时从虚拟 fallback 之后继续原生查找。显式 CommonJS path 列表按调用方顺序，对每个 path 独立应用相同的插入规则。
+
+适配器完成路由后调用捕获的原生 resolver。exports、import/require conditions、main、subpath、扩展名、原生缓存和错误码仍归 Node 处理。路由后的 ESM 失败会把 Node 诊断中的内部查找锚点替换为原始 importer。选中包的无效 export 或缺失目标不会触发另一个同名候选。CommonJS 不替换 `_findPath`，也不复制 `_resolveFilename`。
+
+保证范围是当前线程安装后发生的 Node 默认 `import`、`import()`、`import.meta.resolve`、`require` 和 `require.resolve`。已经链接的模块、自定义 `vm` linker、不透明的非 Node importer 和第三方 Worker 不在透明保证范围。
+
+### 活动插件列表与包元数据
+
+resolution generation 列出可用 fallback 包；Loader entries 组成活动插件列表，两者不能合并。消费方继续使用 Loader 原有 entry 生命周期，并按自身 scope 过滤相关 entries。需要 package metadata 的消费方将 specifier 和所属树的 base URL 交给 app-boot 中的轻量服务，无需 package 导出 `./package.json`。安装 generation 后，即使查询未命中也以 generation 为准；底层嵌入方只安装服务而不提供 generation 时，服务保留 Node 原生查找。
+
+解析器不提供 `imported(entry)`，不观察 ModuleJob，不包装 Entry 方法，不把 fiber 与 import 调用关联，也不替换 registry、tree 或 HMR 方法。重复查询读取同一个 generation，因此不会偏离 import 使用的路线。需要包元数据的非 Node importer 必须显式实现同一个确定性 resolver 接口，不能把调用来源推断重新引入 Node 主路径。
+
+实现集中在 `app-boot/src/profile-resolution/`。`service.ts` 提供长期存在的 `ctx.pluginPackages`，并拥有主线程 resolver 与 Worker generation 的生命周期；`resolver.ts` 实现 generation 查询和 Node Internal 适配器；`worker-bootstrap.ts` 在线程内安装继承的 generation。旧 profile 选包和磁盘 materialize 逻辑留在 `profile.ts`。Worker 只通过 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` 公开入口引用 bootstrap。
+
+服务定义与提供方继续放在 `app-boot`，因为 profile boot 拥有 resolver 生命周期。出现与 launcher 无关的提供方或需要独立演进的消费方时，再抽出单独的能力 seam。
+
+### Worker 与 generation 更新
+
+主线程通过 Worker environment data 发布当前 generation 的可结构化克隆表示和 profile scope。每个 Harness 自有 Worker 构建产物通过构建 banner 获取自己的 ESM/CJS Internal 并安装同一适配器，不重新遍历 manifest。bootstrap bundle 不静态导入任何包。源码 Worker 入口保持原有自包含依赖；第三方 Worker 保持不变。
+
+新 Worker 继承最新发布的 generation。已运行的 Worker 保留启动时继承的 generation，因此发布后继 generation 的调用方必须重启它们。ESM bootstrap 无法影响其执行前已链接的静态依赖，因此 Worker bundle 必须保证 bootstrap 之前的静态 import 可由原生 Node 解析，需要 profile resolver 的业务入口在 bootstrap 后通过 dynamic import 启动。
+
+### 只增加包的变更
+
+添加包的调用方先完成 pnpm 事务，再构造下一代。替换操作会拒绝改变任何既有 package name 的目录或版本。调用方先发布只增加映射的后继 generation，再挂载新的 Loader 配置项；本实现不提供该包事务。挂载失败可以留下已安装但未启用的包。
+
+替换、升级或删除已加载包需要重启，因为 Node 的 ESM Module Map、CommonJS cache、现存对象引用和运行中的 Worker 都可能保留旧模块 identity。generation 换代不声称卸载模块。
+
+### 磁盘迁移
+
+runtime-only 启动流程不创建、更新或退休 symlink 和代理包。resolver 把旧共享 fallback 和 `.dsh-module-fallback` 投影视为虚拟插入位置：generation 命中时使用表中目标，未命中时越过旧位置继续原生祖先查找。dual 阶段物化并安装同一个 generation；测试分别禁用一个后端并比较目标。
+
+旧磁盘状态继续供 link-only 启动、旧进程和回滚使用，但不参与 runtime-only 选择。清理旧链接是本次变更之外的独立维护操作。
+
+### 模式行为
+
+link、dual 与 runtime 模式使用同一种 generation schema 和依赖选择策略。link 模式持久化计算结果，runtime 模式只在进程内安装，dual 模式要求 Node 的磁盘结果与 generation 路由一致。
+
+普通 Node 调用方省略 `resolutionMode` 时，`dsh` launcher 选择 link 模式，因此既有 npm 安装的 profile 启动保留文件系统行为。pkg 可执行文件始终选择 runtime，Electron Host 则在挂载任何 profile 条目前安装 runtime generation。测试与底层嵌入方仍可显式选择 runtime 或 dual。
+
+runtime 模式要求受支持的 Node Internal loader 接口，并且不会创建、更新或退休 fallback 链接。dual 模式保留链接写入，并在 Node 的磁盘结果与 generation 不同时失败。可写 profile 状态和包管理器事务不属于 resolver。
+
+pkg 与打包 Electron 载体强制使用 runtime 解析。Electron Host 通过设置 `ELECTRON_RUN_AS_NODE=1` 的 Electron 可执行文件运行，从 ASAR 读取 dsh 依赖树，并把 ASAR 中的可执行条目映射到 electron-builder 的 unpacked 目录。两种载体都不会创建、更新或删除旧解析链接。
+
+### 性能与验证
+
+generation 构造发生在启动或显式更新阶段，不属于单次 resolve，但需要单独报告绝对延迟。普通热路径只包括 scope 分类、bare name 提取、本地优先判断、Map 查询和一次原生解析；缓存命中直接返回 generation 级结果。当本地 CommonJS 包目录没有 `exports` 且仅缺少所请求 subpath 时，一次请求可能先执行一次原生探测，再执行一次路由解析。作用域外调用不读取 manifest，只缓存 parent 是否位于 profile scope。
+
+实现期间的一次性本地测量用 plain Node 在全新进程中执行构建后的 JavaScript，并与完全没有安装 hook 的进程比较。测量脚本和结果未提交，这些数据不是 benchmark 或 CI 预算。七轮交替顺序覆盖 outside、profile-local 和 fallback 的 dynamic import、`import.meta.resolve`、require、`require.resolve`。Node 22.19、24.18 和 26.8 的热路径中位数最大正向回退为 4.5%。Node 24.18 的 256 包 cold workload 最大回退为 11.2%，generation 构造中位数为 16.027 ms；32 包本地 `require.resolve` 因固定启动成本在整批增加 1.033 ms（+34.7%）。
+
+行为测试在同一包树上比较运行时 generation 与磁盘 materializer，再覆盖根顺序、传递依赖和 peer、本地与外层优先级、exports 与 subpath 错误、conditions 和显式 CommonJS options。Node 兼容矩阵会在受支持的内部 loader 变体上运行 resolver、service 和 bootstrap 规格。Worker 测试通过 mock 线程与 native loader 接口验证 environment data 发布和 bootstrap 安装，但不会启动构建后的 Worker。generation 测试证明构造失败不发布部分状态，成功换代只做原子引用替换。
+
+## Alternatives considered
+
+**永久保留磁盘投影。** 这能在没有进程 hook 时沿用原生查找，但仍有跨进程写入、陈旧 generation、代理 manifest、写锁和打包运行时差异。迁移期 dual 模式仍有价值，因为两个后端消费同一个 generation。
+
+**在 resolve 时惰性扩展依赖图。** 这会把 manifest 读取和错误分散到首次使用，改变磁盘实现的时机，使 Worker 启动更复杂，并让热路径成本随依赖图变化。完整构造 generation 更容易比较和原子替换。
+
+**使用 `module.registerHooks`。** 公共 API 会在 profile scope 拒绝请求之前让相关解析进入 Node 的全局 hook 分发。直接访问已有 ESM/CJS 内部解析器可以保留更小的快速路径，并继续让 Node 完成最终解析。
+
+**通过 Loader 和 HMR 适配器记录每个 Entry 的实际 import。** 实际 import 记录能支持相同输入返回不同目标的有状态 resolver。本设计改为以 generation 作为确定性权威，因此这些记录只会复制 resolver 的答案，同时增加 Entry、fiber、registry、ModuleJob 和 HMR 生命周期状态。
+
+**每次包操作增量修改一张长期表。** 增量修改会暴露半成品依赖图，并要求定点失效缓存。完整构造下一代使失败保持原子，并让所有缓存随 generation 生命周期存在。
+
+**热替换已经加载的包版本。** 解析表换代无法使所有存活模块实例和对象引用失效。重启可以保证每个进程只使用一个 package identity。
+
+## Verification
+
+- 一次 eager 计算同时供应保留的磁盘 materializer 和运行时 generation。
+- link-only、dual 和 runtime-only 测试消费同一个 generation；runtime 启动既不写入也不退休模块解析数据。
+- pkg 与 Electron 载体选择 runtime 解析；Electron 以 Node 模式从 ASAR 承载的 dsh 依赖树执行 Host，原生可执行条目保持 unpacked。
+- ESM 与 CommonJS 适配器共享同一个路由器，并把最终解析委托给 Node，不使用 `module.registerHooks` 或替换 `_findPath`。
+- 生产 package metadata 查询不记录 Loader import 结果，也不包装 Entry、registry、tree 或 HMR 方法。
+- Node 兼容矩阵会在受支持的 loader 接口上运行主线程 resolver 规格；service 和 bootstrap 规格覆盖 Worker environment data 与安装接口，但不会启动构建后的 Worker。
+- 一次性 plain Node 构建产物测量得到上述相对无 hook Node 的热路径和 cold 观察结果；脚本与结果并未提交为证据。
+- package README、架构引用、生成目录和双语文档对描述已交付实现。
+
+## Consequences
+
+runtime 启动避免磁盘修改和代理 manifest，同时保留既有选包算法。代价是持续维护 Node Internal 兼容测试，并在每个自有 Worker 中最早执行自包含 bootstrap。link 保持普通 Node launcher 的默认值，dual 保留迁移比较路径，pkg 与 Electron 载体则强制使用 runtime 且不退休旧链接。在产品拥有模块缓存失效和 Worker 重启前，generation 替换只能新增映射。
diff --git a/.agents/notes/implemented/architecture/2026-09-14-session-log-upload-default.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-14-session-log-upload-default.i18n.yaml
new file mode 100644
index 0000000000..420bcd267c
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-14-session-log-upload-default.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-14-session-log-upload-default.md
+2026-09-14-session-log-upload-default.md: c1e7c9e050d1b1809ff3abba03fe4e17a3779daa
+2026-09-14-session-log-upload-default.zh.md: d7b6e64098eca3fe07c43272fcba18a3790182e2
diff --git a/.agents/notes/implemented/architecture/2026-09-14-session-log-upload-default.md b/.agents/notes/implemented/architecture/2026-09-14-session-log-upload-default.md
new file mode 100644
index 0000000000..c1e7c9e050
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-14-session-log-upload-default.md
@@ -0,0 +1,28 @@
+# Agent Note: Default DeepSeek Session-log upload
+
+Status: implemented
+
+English | [中文](2026-09-14-session-log-upload-default.zh.md)
+## Problem
+
+Ordinary DeepSeek requests do not contain the complete canonical Session trajectory. Requiring each installation to enable log contribution prevents the default product configuration from supplying that trajectory. Recorded-session scenarios also need stable, explicit upload policies because acceptance events are part of their expected logs.
+
+## Decision
+
+`session-log-deepseek.Config.enabled` defaults to `true` in every process. An explicit `enabled: false` disables the contribution. The plugin does not inspect test-runner or snapshot environment variables.
+
+This supersedes only the opt-in default in the [request-extension decision](2026-08-21-deepseek-llm-api-request-extensions.md); that note still owns field serialization, destinations, acceptance, and retry semantics. The headless and ACP corpus base patches and Web scaffold explicitly disable upload. Later scenario patches can enable it. The SDK text-turn recording omits the setting and exercises the shipped default, including durable acceptance events.
+
+## Alternatives considered
+
+**Derive the production default from test environment markers.** This also changes downstream SDK behavior when callers inherit those variables and makes ordinary tests exercise a different product default.
+
+**Refresh every recorded Session to include upload acceptance.** Explicit test composition preserves the existing scenarios while a default-configured SDK recording and Loader regression cover the default-on path.
+
+**Retain opt-in upload.** This does not supply the complete trajectory from ordinary product requests without installation-specific configuration.
+
+## Consequences
+
+Eligible requests send the complete unaccepted canonical log suffix, including message text, tool arguments and results, workspace paths, and feedback, to the resolved DeepSeek endpoint or configured gateway. No prompt tokens or model-visible content are added. Request bodies can grow substantially, and provider rejection still fails the request. OTel remains independent; disabling OTel does not disable this contribution.
+
+Configuration tests cover default-on and explicit overrides with and without test environment markers. Both DeepSeek protocol Loader cases observe the default request field and recorded acceptance watermark, and explicit-off cases observe their absence. Existing headless, ACP, Web, and SDK recordings validate their declared upload policies without rewriting committed Session generations.
diff --git a/.agents/notes/implemented/architecture/2026-09-14-session-log-upload-default.zh.md b/.agents/notes/implemented/architecture/2026-09-14-session-log-upload-default.zh.md
new file mode 100644
index 0000000000..d7b6e64098
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-14-session-log-upload-default.zh.md
@@ -0,0 +1,28 @@
+# Agent Note: DeepSeek 会话日志默认上传
+
+Status: implemented
+
+[English](2026-09-14-session-log-upload-default.md) | 中文
+## 问题
+
+普通 DeepSeek 请求不包含完整的规范会话轨迹。要求每个安装环境启用日志贡献，会使默认产品配置无法提供该轨迹。录制会话场景也需要稳定、明确的上传策略，因为接受事件属于其期望日志。
+
+## 决策
+
+`session-log-deepseek.Config.enabled` 在所有进程中均默认为 `true`。显式设置 `enabled: false` 可关闭贡献。插件不读取测试运行器或快照环境变量。
+
+本决策仅取代[请求扩展决策](2026-08-21-deepseek-llm-api-request-extensions.zh.md)中的主动启用默认策略；该记录仍负责字段序列化、目的地址、接受与重试语义。headless 和 ACP 语料的基础 patch 以及 Web scaffold 显式关闭上传。后续场景 patch 可以启用上传。SDK text-turn 录制省略该设置，验证产品默认值及持久接受事件。
+
+## 考虑过的替代方案
+
+**根据测试环境标记决定生产默认值。** 调用者继承这些变量时，下游 SDK 行为也会改变，普通测试还会采用不同的产品默认值。
+
+**刷新所有录制会话以包含上传接受事件。** 显式测试配置保留现有场景，同时使用默认配置的 SDK 录制和 Loader 回归验证默认开启路径。
+
+**保留主动启用策略。** 没有安装环境专用配置时，该策略无法从普通产品请求提供完整轨迹。
+
+## 后果
+
+符合条件的请求会向解析后的 DeepSeek 端点或已配置网关发送完整的未接受规范日志后缀，包括消息文本、工具参数与结果、工作区路径和反馈。不增加提示词 token 或模型可见内容。请求正文可能显著增大，提供方拒绝仍会使请求失败。OTel 保持独立，关闭 OTel 不会关闭此贡献。
+
+配置测试覆盖有无测试环境标记时的默认开启与显式覆盖。两种 DeepSeek 协议的 Loader 用例观察默认请求字段和已记录的接受水位，显式关闭用例观察两者均不存在。现有 headless、ACP、Web 和 SDK 录制验证各自声明的上传策略，无需重写已提交的会话代际。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.i18n.yaml
new file mode 100644
index 0000000000..29767853c0
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.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/bug-fix/2026-09-11-incremental-terminal-retention.md
+2026-09-11-incremental-terminal-retention.md: 7e2507775bc39ed2599c2af1173f949bbf352145
+2026-09-11-incremental-terminal-retention.zh.md: 6c6fb95fa0c593ae2b7abb0007d5e7c6fc9f4e7d
diff --git a/.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.md b/.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.md
new file mode 100644
index 0000000000..7e2507775b
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.md
@@ -0,0 +1,64 @@
+# Agent Note: incremental terminal retention
+
+Status: implemented
+
+English | [中文](2026-09-11-incremental-terminal-retention.zh.md)
+
+## Problem
+
+Persistent terminal output passes through scrollback and unread-send byte limits on every PTY callback. Rebuilding the entire retained string to enforce those limits makes callback cost grow with retained output. A 4 MiB scrollback window makes this repeated work substantial even when each incoming chunk is small.
+
+## Decision
+
+The private buffer in [terminal-bash](../../../../packages/terminal/terminal-bash/src/session.ts) retains a linked sequence of strings, a head offset, and aggregate UTF-8 byte and newline counts. Appends inspect incoming text and evict only the oldest code points until both limits hold. Every evicted code point is charged to an earlier append, so total retention work is linear in input size. Reads assemble the retained strings; they remain proportional to retained output.
+
+The retained suffix matches line trimming followed by UTF-8 trimming. A trailing newline contributes an empty logical line. Truncation stays sticky until consumption clears the buffer. Adjacent surrogate halves across chunks count as one four-byte code point and are evicted together; unpaired halves retain JavaScript string identity and count as three UTF-8 bytes. The read-time `utf8Tail()` remains independent and unchanged.
+
+Every nonempty input is copied through UTF-16 before retention, preserving unpaired surrogates while detaching slices returned by the sanitizer from discarded control text. This applies to small pending fragments as well as large chunks. Private `truncated` and `isEmpty` getters let send settlement and startup polling inspect status without assembling scrollback.
+
+After at least half of the leading string is discarded, its suffix is copied to release the original backing storage. The copy costs no more than the discarded prefix, preserving amortized linear work and bounding retained string storage by the retained window. Linked nodes avoid array shifts or periodic scans of all retained chunks. Small inputs coalesce in the non-head tail up to 4096 UTF-16 units; allocating its successor copies those fragments into one owned string. Large tails already own their storage and are not copied again at this point. The head never grows during appends, and a cached last code unit avoids flattening pending fragments to inspect a cross-chunk surrogate pair. This bounds fragment metadata even for one-byte callbacks without rescanning retained text.
+
+The [persistent PTY decision](../feature/2026-07-16-persistent-pty-sessions.md) continues to own session lifecycle, model-visible output, and retention semantics. This decision specializes storage and performance; it supersedes no active decision record.
+
+## Measurement design
+
+The terminal I/O benchmark drives `LocalPtySession` with a synthetic subprocess handle. Fixed 16 KiB ASCII chunks without newlines exercise the byte limit with a long logical line. Steady-state cases fill either a 128 KiB or 4 MiB window, then append the same additional 1 MiB. A separate empty-window case sends 5 MiB. The line limit is 10,000; unread output is limited to the smaller of 256 KiB and the scrollback capacity.
+
+Synchronous ingestion measures the send start and provider callbacks. Completion additionally waits for emulator processing and readiness, then reads the bounded terminal result. Retained heap is sampled after explicit GC while the session and returned output remain reachable. Built JavaScript runs under plain Node. These measurements exclude shell startup, operating-system PTY transport, model latency, and browser rendering.
+
+### Local reference measurements
+
+On Apple M5 Pro, macOS arm64, Node v26.5.0, five fresh workers per case compare the eager-retention baseline with incremental retention. The same worker and inputs measure both versions; only the private session implementation differs. Times below are milliseconds in sample order.
+
+| Case / metric | Eager retention samples | Incremental retention samples |
+|---|---|---|
+| 128 KiB steady / ingestion | 232.164, 234.564, 219.511, 219.615, 221.434 | 10.493, 10.474, 9.917, 10.524, 10.327 |
+| 128 KiB steady / completion | 245.365, 247.826, 233.322, 232.854, 234.926 | 19.600, 19.991, 19.290, 20.049, 19.773 |
+| 4 MiB steady / ingestion | 4159.780, 4271.184, 4179.700, 4223.583, 4128.541 | 8.752, 8.584, 8.808, 8.582, 10.073 |
+| 4 MiB steady / completion | 4183.374, 4296.630, 4205.122, 4247.787, 4151.634 | 29.760, 30.679, 31.510, 31.781, 37.748 |
+| 5 MiB send / ingestion | 5186.998, 5122.875, 5127.790, 5177.788, 5157.274 | 26.440, 27.453, 26.710, 26.328, 27.334 |
+| 5 MiB send / completion | 5297.536, 5181.298, 5182.416, 5234.920, 5211.802 | 89.475, 83.310, 88.491, 89.440, 89.339 |
+
+The large/small steady-ingestion median ratio is 18.88 for eager retention and 0.84 for incremental retention. The 5 MiB completion median falls from 5211.802 ms to 89.339 ms (58.3×). Maximum retained heap for the large steady case rises from 4,512,656 to 6,219,296 bytes; this measures live session and result allocations together, not just buffer strings.
+
+A separate memory case sends 5 MiB in 16-byte callbacks and samples retained heap once after completion. It retains 5,802,840 bytes with tail aggregation. The same assertion with uncoalesced linked nodes fails at 22,969,720 bytes against the 16 MiB bound. This case has no performance timing verdict.
+
+The filtered-output memory case emits 513 callbacks of 64 KiB each, containing a complete 56 KiB OSC sequence followed by 8 KiB of visible text. This passes through the production sanitizer before filling a 4 MiB visible window and taking a bounded read. With incoming slices retained directly, the assertion fails at 36,706,592 bytes. Copying inputs into independent storage reduces retained heap to 7,635,440 bytes, below the unchanged 16 MiB limit. These measurements use Node v26.5.0 and fresh workers.
+
+A real PTY diagnostic runs `node -e 'process.stdout.write("x".repeat(5*1024*1024))'` through the built local subprocess provider. One baseline sample takes 106962.523 ms; one final candidate sample takes 249.007 ms. Timing begins before PTY/process spawn and ends after `session_exit` and the bounded read. Both samples exit with code 0, no signal, and truncated 256 KiB viewport/read payloads. This includes native PTY transport and Node startup, but excludes an interactive shell and prompt-readiness round trip.
+
+The [required benchmark](../../../../benchmarks/terminal-io/terminal-io.bench.ts) applies the shared CI scale and headroom to reference expectations of 20 ms steady ingestion, 50 ms steady completion, and 120 ms full completion, yielding limits of 50/125/300 ms. Median capacity scaling must stay below 4×; maximum retained heap is 16 MiB. Ratios and memory limits are unscaled. Substituting the original compiled session worker makes both timing cases fail: capacity ratio 18.977 exceeds 4, and full completion 5066.719 ms exceeds 300 ms. The final worker passes all four cases. The local benchmark command is `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/terminal-io/terminal-io.bench.ts` after the benchmark build.
+
+## Alternatives considered
+
+**Cache only the byte count.** This leaves the per-append line split and full-string prefix deletion dependent on retained output. Both limits need incremental accounting.
+
+**Keep the complete output until a read.** This makes producer cost small but permits unbounded retention between reads. The configured limits apply during production.
+
+**Retain one node per callback.** Tiny callbacks make node metadata much larger than the bounded text. Bounded tail aggregation keeps node count tied to stored text blocks.
+
+**Store encoded UTF-8 chunks.** Encoding replaces unpaired UTF-16 surrogates. String chunks preserve the existing buffer semantics without adding a second text representation.
+
+## Consequences
+
+Append-time work no longer depends on repeatedly scanning the retained window. Snapshot and consume still allocate a combined string. Retention adds linked nodes and a bounded collection of pending small fragments. Functional tests cover byte/line interactions, consumption, split surrogate pairs, and 4 MiB retention. Performance evidence complements these output assertions; a synthetic provider does not establish real-shell command latency.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.zh.md b/.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.zh.md
new file mode 100644
index 0000000000..6c6fb95fa0
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.zh.md
@@ -0,0 +1,64 @@
+# Agent Note: 增量终端保留策略
+
+Status: implemented
+
+[English](2026-09-11-incremental-terminal-retention.md) | 中文
+
+## 问题
+
+持久终端输出在每次 PTY 回调中都受 scrollback 和未读发送输出的字节上限约束。如果每次执行这些限制都重建完整的保留字符串，回调成本就会随保留输出量增长。即使每个输入分片很小，4 MiB scrollback 窗口也会使这项重复工作产生显著开销。
+
+## 决策
+
+[terminal-bash](../../../../packages/terminal/terminal-bash/src/session.ts) 的私有缓冲区保留字符串链表、头部偏移，以及 UTF-8 字节数与换行符数的汇总值。追加操作检查输入文本，并仅淘汰最旧的码点，直到两个限制都满足。每个被淘汰码点的成本可归于之前的追加操作，因此保留策略的总工作量与输入量呈线性关系。读取时拼接保留字符串，成本仍与保留输出量成正比。
+
+保留后缀与先按行数裁剪、再按 UTF-8 字节数裁剪的结果一致。末尾换行符贡献一个空逻辑行。截断标志保持为真，直到消费操作清空缓冲区。跨分片相邻的代理项两半按一个四字节码点计数，并共同淘汰；未配对代理项保留 JavaScript 字符串原值，按三个 UTF-8 字节计数。读取时的 `utf8Tail()` 保持独立且不变。
+
+每个非空输入都在保留前通过 UTF-16 复制，在保留未配对代理项的同时，使清理器返回的切片脱离已丢弃的控制文本。待处理的小片段与大分片都遵循这一规则。私有 `truncated` 和 `isEmpty` getter 让发送结算和启动轮询无需拼接 scrollback 即可检查状态。
+
+头部字符串至少一半被丢弃后，其后缀会被复制，以释放原始底层存储。复制成本不超过已丢弃前缀，因此维持摊还线性工作量，并使保留字符串存储受保留窗口约束。链表节点避免数组头部移除或定期扫描所有保留分片。小输入在非头部的尾节点合并，最多积累 4096 个 UTF-16 单元；分配后继节点时，将这些片段复制为一个独立字符串。大尾块已经拥有独立存储，此处不会再次复制。追加期间头节点不会增长，缓存的末尾码元也避免了为检查跨分片代理对而将待处理片段展平。这样即使每次回调只有一个字节，片段元数据也有界，且无需重新扫描保留文本。
+
+[持久 PTY 决策](../feature/2026-07-16-persistent-pty-sessions.zh.md)继续负责会话生命周期、模型可见输出与保留语义。本决策细化存储与性能，不取代任何活跃决策记录。
+
+## 测量设计
+
+终端 I/O 基准通过合成子进程句柄驱动 `LocalPtySession`。固定的 16 KiB ASCII 分片不含换行符，以长逻辑行触发字节上限。稳态场景先填满 128 KiB 或 4 MiB 窗口，再追加同样的 1 MiB。独立的空窗口场景发送 5 MiB。行数上限为 10,000；未读输出上限为 256 KiB 与 scrollback 容量中的较小值。
+
+同步接收计时覆盖发送启动与提供方回调。完成计时还等待终端模拟器处理与就绪，再读取有界终端结果。保留堆在显式 GC 后采样，此时会话与返回输出仍可达。构建后的 JavaScript 在普通 Node 下运行。这些测量不含 shell 启动、操作系统 PTY 传输、模型延迟或浏览器渲染。
+
+### 本地参考测量
+
+在 Apple M5 Pro、macOS arm64、Node v26.5.0 上，每个场景用五个全新 worker 比较全量保留计算基线 与增量保留策略。两个版本使用相同 worker 和输入，仅私有会话实现不同。下表时间单位为毫秒，按采样顺序排列。
+
+| 场景 / 指标 | 全量保留计算样本 | 增量保留计算样本 |
+|---|---|---|
+| 128 KiB 稳态 / 接收 | 232.164, 234.564, 219.511, 219.615, 221.434 | 10.493, 10.474, 9.917, 10.524, 10.327 |
+| 128 KiB 稳态 / 完成 | 245.365, 247.826, 233.322, 232.854, 234.926 | 19.600, 19.991, 19.290, 20.049, 19.773 |
+| 4 MiB 稳态 / 接收 | 4159.780, 4271.184, 4179.700, 4223.583, 4128.541 | 8.752, 8.584, 8.808, 8.582, 10.073 |
+| 4 MiB 稳态 / 完成 | 4183.374, 4296.630, 4205.122, 4247.787, 4151.634 | 29.760, 30.679, 31.510, 31.781, 37.748 |
+| 5 MiB 发送 / 接收 | 5186.998, 5122.875, 5127.790, 5177.788, 5157.274 | 26.440, 27.453, 26.710, 26.328, 27.334 |
+| 5 MiB 发送 / 完成 | 5297.536, 5181.298, 5182.416, 5234.920, 5211.802 | 89.475, 83.310, 88.491, 89.440, 89.339 |
+
+大/小窗口稳态接收时间的中位数比值在全量保留计算下为 18.88，在增量保留计算下为 0.84。5 MiB 完成时间的中位数从 5211.802 ms 降至 89.339 ms（58.3×）。大窗口稳态场景的最大保留堆从 4,512,656 字节升至 6,219,296 字节；该指标同时测量活跃会话与结果分配，并非仅缓冲区字符串。
+
+独立的内存场景以 16 字节回调发送 5 MiB，在完成后对保留堆采样一次。尾部合并时保留 5,802,840 字节。相同断言在未合并链表节点下失败：22,969,720 字节超过 16 MiB 上限。此场景不判定性能耗时。
+
+过滤输出的内存场景发送 513 个 64 KiB 回调，每个含完整的 56 KiB OSC 序列及其后的 8 KiB 可见文本。数据经过生产清理器，填满 4 MiB 可见窗口后进行有界读取。直接保留输入切片时，断言以 36,706,592 字节失败。将输入复制到独立存储后，保留堆降至 7,635,440 字节，低于不变的 16 MiB 上限。这些测量使用 Node v26.5.0 和全新 worker。
+
+真实 PTY 诊断通过构建后的本地子进程提供方运行 `node -e 'process.stdout.write("x".repeat(5*1024*1024))'`。一次基线样本耗时 106962.523 ms；一次最终候选样本耗时 249.007 ms。计时从 PTY/进程 spawn 前开始，到 `session_exit` 和有界读取完成后结束。两个样本均以代码 0 退出，无信号，viewport/read 载荷均为已截断的 256 KiB。这包括原生 PTY 传输与 Node 启动，不包括交互式 shell 及提示符就绪往返。
+
+[必需基准](../../../../benchmarks/terminal-io/terminal-io.bench.ts)对参考预期值应用共享 CI 系数与余量：稳态接收 20 ms、稳态完成 50 ms、完整发送完成 120 ms，对应限制为 50/125/300 ms。容量扩展的中位数比值必须低于 4×；最大保留堆为 16 MiB。比值与内存限制不缩放。替换为原始编译后会话 worker 时，两个计时场景都失败：容量比值 18.977 超过 4，完整发送完成时间 5066.719 ms 超过 300 ms。最终 worker 的四个场景均通过。本地命令为 `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/terminal-io/terminal-io.bench.ts`，在基准构建完成后执行。
+
+## 考虑过的替代方案
+
+**仅缓存字节数。** 这仍会使每次追加的按行拆分和完整字符串前缀删除依赖保留输出量。两个限制都需要增量计数。
+
+**在读取前保留全部输出。** 这使生产成本较小，但允许读取之间的保留量无限增长。配置的限制必须在产生输出时生效。
+
+**每次回调保留一个节点。** 微小回调会使节点元数据远大于有界文本。受限的尾部合并使节点数与存储的文本块相关。
+
+**保留编码后的 UTF-8 分片。** 编码会替换未配对 UTF-16 代理项。字符串分片无需引入第二种文本表示，即可保留现有缓冲区语义。
+
+## 影响
+
+追加工作不再依赖重复扫描保留窗口。Snapshot 和 consume 仍分配拼接后的字符串。保留策略额外维护链表节点与有界的待处理小片段集合。功能测试覆盖字节数与行数的交互、消费操作、跨分片代理对，以及 4 MiB 保留窗口。性能证据补充这些输出断言；合成提供方不能证明真实 shell 命令延迟。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-14-chat-presentation-defaults.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-14-chat-presentation-defaults.i18n.yaml
new file mode 100644
index 0000000000..9ce88177ba
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-14-chat-presentation-defaults.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/bug-fix/2026-09-14-chat-presentation-defaults.md
+2026-09-14-chat-presentation-defaults.md: 6703a14e2ad108c4b43dd50692a44c159cf3ea5a
+2026-09-14-chat-presentation-defaults.zh.md: 67ca433339ecf6e44d3f74b6c3ff9e465f802b0b
diff --git a/.agents/notes/implemented/bug-fix/2026-09-14-chat-presentation-defaults.md b/.agents/notes/implemented/bug-fix/2026-09-14-chat-presentation-defaults.md
new file mode 100644
index 0000000000..6703a14e2a
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-14-chat-presentation-defaults.md
@@ -0,0 +1,25 @@
+# Agent Note: Keep Chat presentation independent of Trajectory inspection
+
+Status: implemented
+
+English | [中文](2026-09-14-chat-presentation-defaults.zh.md)
+
+## Problem
+
+Trajectory inspection benefits from exposing complete recorded reasoning. Applying that default to Chat expands the live transcript during reasoning and changes its height when an answer or Tool call arrives. The Trajectory inspection change also added historical first-token recovery to Chat without a separate Chat behavior decision.
+
+## Decision
+
+[Chat](../../../../packages/client/ui-chat/README.md#turn-process-folding) starts each reasoning row collapsed and retains the reader's manual disclosure choice through subsequent output and settlement. Settlement retires the observed live chunks and rebuilds Chat reply nodes from durable events without recovering first-token time from embedded streams. Consequently, completed-turn TTFT and decoding speed are absent after live settlement as well as after reopening history. Turn-level process folding remains independently owned.
+
+[Trajectory inspection](../feature/2026-09-09-ptc-trajectory-code-inspection.md) keeps its expanded reasoning default, recorded timing, JSON controls, and PTC code inspector. The [compact stream readers](../architecture/2026-09-06-embedded-stream-record-readers.md) remain available to Trajectory and other consumers. These decisions partially supersede the Chat presentation additions while preserving both notes' independent rationale.
+
+## Alternatives considered
+
+**Keep Chat's automatic expansion and historical timing recovery.** These change Chat behavior beyond the requested Trajectory inspection work. Reintroducing either requires a separate Chat product decision and its own verification.
+
+**Revert the entire inspection change.** That would remove the requested Trajectory behavior along with the unintended Chat changes.
+
+## Consequences
+
+Chat reasoning requires a click to inspect in full. Elapsed turn time and the independently projected Session Stats remain available. Assembler tests distinguish transient retirement at live settlement from reopening durable history; browser replay verifies the completed-turn timing dialog before and after reload. Component tests cover collapsed streaming and reasoning-only replies and manual disclosure across answer and Tool-call arrival. Trajectory tests retain its separate defaults and timing.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-14-chat-presentation-defaults.zh.md b/.agents/notes/implemented/bug-fix/2026-09-14-chat-presentation-defaults.zh.md
new file mode 100644
index 0000000000..67ca433339
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-14-chat-presentation-defaults.zh.md
@@ -0,0 +1,25 @@
+# Agent Note: 保持 Chat 展示与 Trajectory 查看独立
+
+Status: implemented
+
+[English](2026-09-14-chat-presentation-defaults.md) | 中文
+
+## 问题
+
+Trajectory 查看适合直接展示完整的已记录思考。将该默认行为应用到 Chat 会在思考期间展开实时对话，并在回答或工具调用到来时改变其高度。Trajectory 查看改动还为 Chat 增加了历史首 token 计时恢复，却没有独立的 Chat 行为决策。
+
+## 决策
+
+[Chat](../../../../packages/client/ui-chat/README.zh.md#turn-process-folding) 的每个思考行初始都折叠，后续输出和结算保留用户手动选择的展开状态。结算会移除观测到的实时 chunk，并从持久事件重建 Chat 回复节点，不从内嵌流恢复首 token 时间。因此，实时结算后和重新打开历史后，已完成轮次都不显示 TTFT 和解码速度。轮次级过程折叠仍独立维护。
+
+[Trajectory 查看](../feature/2026-09-09-ptc-trajectory-code-inspection.zh.md) 保留思考默认展开、已记录计时、JSON 控件和 PTC 代码查看器。[紧凑流读取器](../architecture/2026-09-06-embedded-stream-record-readers.zh.md) 仍供 Trajectory 和其他消费方使用。这些决策部分取代了 Chat 展示增量，同时保留两份记录各自独立的理由。
+
+## 考虑过的替代方案
+
+**保留 Chat 自动展开和历史计时恢复。** 这些改变了所请求的 Trajectory 查看工作之外的 Chat 行为。重新引入任一行为都需要独立的 Chat 产品决策及相应验证。
+
+**撤回整个查看改动。** 这会在撤回意外 Chat 改动的同时移除所请求的 Trajectory 行为。
+
+## 影响
+
+Chat 思考需要点击才能查看全文。轮次总耗时和独立投影的 Session Stats 仍可用。组装器测试区分实时结算时移除临时数据与重新打开持久历史；浏览器回放验证重载前后的已完成轮次计时对话框。组件测试覆盖流式与仅思考回复的默认折叠，以及回答和工具调用到来时的手动展开状态。Trajectory 测试保留其独立默认值和计时。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-14-web-diff-context.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-14-web-diff-context.i18n.yaml
new file mode 100644
index 0000000000..286919457a
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-14-web-diff-context.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/bug-fix/2026-09-14-web-diff-context.md
+2026-09-14-web-diff-context.md: 072af0966689d475d7fdd1df83861fa847f3745f
+2026-09-14-web-diff-context.zh.md: cd165a443451fc5ba580078b1b431a2788671dbe
diff --git a/.agents/notes/implemented/bug-fix/2026-09-14-web-diff-context.md b/.agents/notes/implemented/bug-fix/2026-09-14-web-diff-context.md
new file mode 100644
index 0000000000..072af09666
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-14-web-diff-context.md
@@ -0,0 +1,33 @@
+# Agent Note: Web diff cards compare contextual content
+
+Status: implemented
+
+English | [中文](2026-09-14-web-diff-context.zh.md)
+
+## Problem
+
+Filesystem result metadata carries before/after fragments that include unchanged context. Treating each complete fragment as removed or added mislabels shared lines and inflates both card and collapsed-row totals.
+
+## Decision
+
+The Web primitive derives line patches with the maintained `diff` library, using `maxEditLength: 256`. Each exact change includes up to three neutral context lines on either side; distant changes use separate hunks and shared context contributes to neither total. Beyond 256 additions/deletions per fragment, search stops and the complete old/new fragments render as a coarse replacement, including shared lines in the display, copy, and counts. The card and `diffTotals` use this same deterministic derivation. This remains Client presentation under the [tool presentation ownership decision](../architecture/2026-08-23-client-derived-tool-presentation.md), without changing persisted metadata or public props.
+
+## Alternatives considered
+
+Unbounded comparison stalls collapsed summaries on heavily changed fragments. A deterministic edit-distance limit preserves exact sparse edits regardless of file length; a wall-clock timeout could make the summary and body choose different results under load. A coarse replacement sacrifices alignment above the limit while retaining every input line. Caching or asynchronous rendering adds ownership and invalidation work that the bounded comparison does not require. Extending durable metadata or maintaining a custom diff algorithm is unnecessary for this presentation behavior.
+
+## Measurement
+
+A local CPU diagnostic bundled the production `DiffBlock.tsx` entry with esbuild (`--bundle --platform=node --format=esm`) and timed `diffTotals` under Node 26.5.0 on macOS ARM64. Each fragment has 10,000 lines: unique indexed lines replaced completely, 100 evenly spaced replacements, or alternating repeated `old`/`shared` versus `new`/`shared` lines. Input construction and module loading are excluded; returned totals remain reachable. These are function timings, not browser paint or input latency, and carry no CI timing threshold.
+
+| Input | Unbounded milliseconds | Bounded search milliseconds |
+| --- | --- | --- |
+| Complete replacement | 6492.16, 6777.79, 6786.79 | 5.25, 4.66, 4.19 |
+| 100 sparse replacements | 8.19, 4.58, 4.01 | 7.58, 4.26, 4.13 |
+| Alternating repeated lines | 3383.13 | 10.26, 7.46, 5.52 |
+
+The bound admits all 100 sparse replacements unchanged. The 129-replacement regression fails without it because the unbounded implementation returns exact counts instead of the required complete-fragment fallback.
+
+## Consequences
+
+The browser build includes `diff`. The bound limits edit-graph search, not wall-clock duration: normalization, fallback rows, and copied output still scale with input length, and expanded cards also derive their rows separately. The content-line rule treats a final newline as a terminator. Regressions cover exact output at 256 edits, complete coarse output above the limit, a sparse edit in 10,000 lines, shared and distant context, repeated lines, copied prefixes, and summary/footer parity. Authored and borrowed Session snapshots cover coarse and exact browser cards respectively.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-14-web-diff-context.zh.md b/.agents/notes/implemented/bug-fix/2026-09-14-web-diff-context.zh.md
new file mode 100644
index 0000000000..cd165a4434
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-14-web-diff-context.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: Web diff 卡片比较含上下文的内容
+
+Status: implemented
+
+[English](2026-09-14-web-diff-context.md) | 中文
+
+## Problem
+
+文件系统结果元数据携带的前后文本片段包含未改动的上下文。把完整片段分别当作删除和新增会错误标记共享行，并夸大卡片和折叠工具行的统计。
+
+## Decision
+
+Web 原语通过维护中的 `diff` 库生成行补丁，使用 `maxEditLength: 256`。每处精确改动两侧最多保留三行中性上下文；远距离改动分成独立 hunk，共享上下文不计入增删统计。每个片段的新增与删除行数超过 256 时，搜索停止，完整新旧片段按粗粒度替换呈现，共享行也计入显示、复制和统计。卡片与 `diffTotals` 使用同一确定性推导。这遵循[工具呈现归属决策](../architecture/2026-08-23-client-derived-tool-presentation.zh.md)，仍属于 Client 呈现，不改变持久化元数据或公开 props。
+
+## Alternatives considered
+
+无上限比较会让大量改动片段的折叠摘要停顿。确定性的编辑距离上限能让稀疏编辑保持精确，不受文件长度影响；墙钟超时可能使摘要和正文在负载下选择不同结果。粗粒度替换在超过上限后放弃对齐，但保留全部输入行。缓存或异步渲染会增加归属和失效处理，而有界比较不需要这些机制。该呈现行为无需扩展持久化元数据或维护自定义 diff 算法。
+
+## Measurement
+
+本地 CPU 诊断用 esbuild（`--bundle --platform=node --format=esm`）打包生产 `DiffBlock.tsx` 入口，并在 macOS ARM64 的 Node 26.5.0 下计时 `diffTotals`。每个片段有一万行：全部替换带唯一索引的行、均匀分布的 100 处替换，或交替重复的 `old`/`shared` 与 `new`/`shared` 行。不计输入构造和模块加载；返回的统计值保持可达。这些是函数耗时，不是浏览器绘制或输入延迟，也没有作为 CI 时间阈值。
+
+| 输入 | 无上限毫秒数 | 有界搜索毫秒数 |
+| --- | --- | --- |
+| 全部替换 | 6492.16, 6777.79, 6786.79 | 5.25, 4.66, 4.19 |
+| 100 处稀疏替换 | 8.19, 4.58, 4.01 | 7.58, 4.26, 4.13 |
+| 交替重复行 | 3383.13 | 10.26, 7.46, 5.52 |
+
+上限允许全部 100 处稀疏替换保持精确。移除上限时，129 处替换回归会失败，因为无上限实现返回精确统计，而非要求的完整片段回退。
+
+## Consequences
+
+浏览器构建包含 `diff`。上限约束编辑图搜索，不约束墙钟时长：规范化、回退行及复制内容仍随输入长度增长，展开卡片也会单独推导正文行。内容行规则把末尾换行视为终止符。回归覆盖 256 次编辑时的精确输出、超过上限后的完整粗粒度输出、一万行中的稀疏编辑、共享和远距离上下文、重复行、复制前缀及摘要与底部统计一致性。编写和借用的 Session 快照分别覆盖粗粒度和精确的浏览器卡片。
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.i18n.yaml
new file mode 100644
index 0000000000..b8c09374e3
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.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-08-03-web-sticky-collapsible-headers.md
+2026-08-03-web-sticky-collapsible-headers.md: 6e8b4b94c9c6aa40bc7190e6705b84caa8189c52
+2026-08-03-web-sticky-collapsible-headers.zh.md: d4e1f69539db6870ae60d5c4b05cd52c7d129360
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.md b/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.md
new file mode 100644
index 0000000000..6e8b4b94c9
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.md
@@ -0,0 +1,41 @@
+# Agent Note: Web sticky collapsible headers — Think and compaction toggles pin while scrolling
+
+Status: implemented
+
+English | [中文](2026-08-03-web-sticky-collapsible-headers.zh.md)
+
+## Problem
+
+Two conversation blocks render their expanded body uncapped, flowing with the page instead of scrolling inside a bounded surface: the Web Think row (`.thinkBody`) and the compaction marker (`.compactionBody`). Every other tool row caps its body and scrolls it inside its own card, so its disclosure header stays visible. The two uncapped blocks do not. A long chain of thought or a long compaction summary carries its own disclosure header off the top of the viewport, so a reader who wants to collapse the block again must scroll the full body back up to reach the toggle.
+
+## Decision
+
+The disclosure header of each uncapped block sticks to the conversation scroll container's top while the block is open. The header remains in normal flow when collapsed, so a collapsed block scrolls away like any other row.
+
+Both blocks already scroll against the shared conversation scroll container (`[data-conversation-scroll]`), not an inner box, so `position: sticky; top: 0` on the header pins it against that container. A base-token background masks the prose that scrolls under the pinned header.
+
+The pinned header's stacking rank differs by block, because their bodies differ. The Think body is plain text with no sticky descendant, so `z-index: 1` suffices. The compaction body renders markdown, and a fenced code block in the summary pins its own banner at `z-index: 6` (`packages/client/ui-primitives/src/markdown/CodeBlock.module.css`) with a Copy control inside it; the compaction header therefore uses `z-index: 7` and holds that banner below its own band, so the header never covers the Copy control and the banner never covers the toggle. The band's height is one component-local measurement (`--dsh-compaction-header-height` on `.compactionRow`) shared by the toggle's `height` and the banner's `top`; the banner rule wins over CodeBlock's `top: 0` by specificity, because the two sheets load in their own packages. The pinned header also overrides its hover fill to the opaque `--dsw-alias-interactive-bg-hover-solid` token and squares its corners for as long as the row is open: the default translucent hover token would let the scrolling prose show through the moment the pointer lands on the toggle, and the base 6px radius would leave the same prose visible at the corners. `:hover` raises the rule's specificity above the later base hover rule, so declaration order does not decide the winner. Two other elements take `z-index: 7` to clear the same code banners: the composer seat and the turn-navigation rail slot (`TurnNavigator.module.css`, ui-chat). Their order among equal ranks is stated once, in the composer seat's comment (`packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css`).
+
+The rules are scoped so only the two uncapped blocks are affected; the capped tool rows keep their existing behavior, since stacking sticky headers across a run of tool rows would pile them at the top. The Think rule is `packages/client/ui-chat/src/client/chat/ReasoningRow.module.css` `.root[data-expanded] [data-open] [data-disclosure-row]` — gated on `DisclosureRow`'s `data-open` so a collapsed Think row never sticks, and scoped under the Think row's own root so no tool-call variant is touched. The compaction rule is `packages/client/ui-chat/src/client/chat/MessageItem.module.css` `.compactionRow:has(.compactionBody) .compactionButton` — the body sibling exists in the DOM only while open, so `:has()` gates the stick on the open state.
+
+No session, wire, durable event, or model-visible contract changes; this is a presentation-only CSS change owned by the existing components.
+
+## Alternatives considered
+
+**Cap the two bodies with `max-height` + internal scroll, matching the tool cards.** Rejected: the Think body is deliberately uncapped so reasoning reads as ordinary message prose ([web-thinking-tail-scroll](../../archived/feature/2026-08-02-web-thinking-tail-scroll.md) and the `.thinkBody` comment own that intent), and the compaction summary is a reading surface. An inner scrollport introduces nested scrolling — the wheel switches from page to box under the cursor — and compresses long technical prose into a small window that is worse to read. Sticky headers keep the flowing-prose reading model and still keep the toggle reachable.
+
+**Add sticky headers to every collapsible row for consistency.** Rejected: the capped tool rows already keep their header visible because their body scrolls internally, so they have no problem to solve. Making their headers sticky against the page would stack one pinned header per open row at the top of the viewport during a scroll through a run of tool calls, which is visual noise, not consistency.
+
+**Offset the summary's code banner from `CodeBlock` rather than from the compaction rule.** Rejected: `CodeBlock` could read a property such as `--dsl-code-block-banner-top` that this consumer sets, which would leave the code block the owner of its own geometry and avoid a `:has()` selector reaching into another package's DOM. It also routes every consumer's layout through a property only this block sets, and the offset is this block's presentation concern rather than the code block's: the local rule states the offset beside the toggle that creates it, and `[data-code-block-banner]` is the hook `CodeBlock` already publishes for owner styling.
+
+**A shared sticky rule on the `DisclosureRow` primitive.** Rejected: `DisclosureRow` backs Think, every tool-call variant, and the context-injection row; a rule there would hit the capped rows too. The behavior belongs only to the uncapped consumers, so each scopes the rule to its own block.
+
+## Consequences
+
+The collapse toggle for a long Think block or compaction summary stays reachable without scrolling the body back to its start, while both bodies keep flowing as page prose. The change is CSS-only: no timer, subscription, durable state, DOM structure change, or transport traffic. The compaction rule uses the CSS `:has()` selector, supported across the browsers the Web UI targets.
+
+## Testing
+
+The unit specs pin the DOM anchors the selectors key on: `packages/client/ui-chat/tests/reasoning-row.client.spec.tsx` asserts an open Think row nests `[data-disclosure-row]` under `[data-variant='think'][data-expanded] [data-open]` and that a collapsed row has no `[data-open]`; `packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx` asserts the compaction body appears under `.compactionRow` only while open. `packages/client/ui-chat/tests/sticky-header-styles.client.spec.ts` reads the rules as CSS text and pins the declarations the pinning depends on: `position: sticky`, `top: 0`, the square corners, the `z-index` rank of each side, the single measurement shared by the toggle's height and the code banner's offset, and the opaque hover token, because jsdom computes no sticky layout and the render specs cannot fail on a changed declaration.
+
+The real-browser evidence is two keyless Chromium e2e paths. `apps/web/tests/lifecycle-chrome.e2e.ts` expands the settled turn's process row, opens the Think row, and asserts its header computes `position: sticky`, `top: 0px` (and is not sticky while collapsed); that fixture's recorded reasoning is a single line, too short to overflow, so it proves only that the CSS resolves onto the Think header. `apps/web/tests/seeded-history.e2e.ts` carries the pinned-while-scrolling evidence: it seeds a compaction whose summary length this suite controls (a fenced code block plus 40 list items), shrinks the viewport to force overflow, scrolls the marker into its pinned state, and asserts the header computes `position: sticky`, `top: 0px`, a `z-index` greater than the code block banner's, that it holds at the scrollport top after the scroll, that its own center is the topmost hit-tested element (the toggle stays clickable), and that its hover fill stays fully opaque (alpha 1). The same case scrolls the summary's code banner into its own stuck position and asserts the banner stops below the toggle's band and that the banner's Copy control owns its center, so the offset cannot regress into a covered control. The case also writes a keyless geometry golden (`snapshots/web/seeded-history/sticky-geometry.expected.md`) fixing these platform-independent semantic facts, since this is a user-visible CSS behavior that changes no DOM and no accessible name, so the aria goldens cannot capture it. The PR demo GIF, recorded against a real server and a real model round, carries the visual evidence that the pinned header stays at the top while the body scrolls.
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.zh.md
new file mode 100644
index 0000000000..d4e1f69539
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.zh.md
@@ -0,0 +1,41 @@
+# Agent Note：Web 可折叠块的钉住标题 —— Think 与压缩标记的折叠按钮在滚动时钉住
+
+Status: implemented
+
+[English](2026-08-03-web-sticky-collapsible-headers.md) | 中文
+
+## 问题
+
+会话里有两个块的展开正文不封顶，随整页滚动，而不是在有界的表面内部滚动：Web Think 行（`.thinkBody`）和压缩标记（`.compactionBody`）。其他每个工具行都给正文封顶并在自己的卡片内部滚动，所以折叠标题始终可见。这两个不封顶的块做不到。一段很长的思维链或很长的压缩摘要会把自己的折叠标题顶出视口上方，想再次折叠该块的读者必须把整段正文滚回顶部才能够到折叠按钮。
+
+## 决策
+
+每个不封顶块的折叠标题在块展开时钉在会话滚动容器的顶部。折叠时标题保持在正常文档流中，所以折叠的块会像其他行一样滚走。
+
+这两个块本来就是相对共享的会话滚动容器（`[data-conversation-scroll]`）滚动，而非某个内层框，所以在标题上加 `position: sticky; top: 0` 就把它钉在该容器上。一个 base token 背景遮住在钉住的标题下方滚过的正文。
+
+钉住的标题的层叠级别按块而异，因为两者正文不同。Think 正文是纯文本、无 sticky 后代，`z-index: 1` 就够。压缩正文渲染 markdown，摘要里的围栏代码块会把自己的 banner 钉在 `z-index: 6`（`packages/client/ui-primitives/src/markdown/CodeBlock.module.css`），banner 里带一个 Copy 控件；因此压缩标题用 `z-index: 7`，并让那个 banner 停在自己的标题带下方，这样标题永远不会盖住 Copy 控件，banner 也不会盖住折叠按钮。标题带高度是一个组件局部量（`.compactionRow` 上的 `--dsh-compaction-header-height`），由折叠按钮的 `height` 与 banner 的 `top` 共用；banner 规则靠特异性压过 CodeBlock 的 `top: 0`，因为两张样式表分属不同的包。钉住的标题还把 hover 底覆盖为不透明的 `--dsw-alias-interactive-bg-hover-solid` token，并在整行展开期间都保持直角：默认的半透明 hover token 会在指针落到折叠按钮准备折叠的瞬间让滚动的正文透出，而基础的 6px 圆角会让同样的正文在四角露出来。`:hover` 把该规则的特异性抬到文件更靠后的 hover 基础规则之上，所以胜负不由声明顺序决定。另外还有两个元素为了避开同一批代码 banner 取 `z-index: 7`：输入框座与轮次导航轨道槽（`TurnNavigator.module.css`，ui-chat）。同级之间的先后顺序只写在一处：`packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css` 中输入框座的注释。
+
+规则被限定作用域，只影响这两个不封顶的块；封顶的工具行保持原有行为，因为让一连串工具行的 sticky 标题层层堆叠会把它们全挤在顶部。Think 规则是 `packages/client/ui-chat/src/client/chat/ReasoningRow.module.css` 的 `.root[data-expanded] [data-open] [data-disclosure-row]`，用 `DisclosureRow` 的 `data-open` 门控，折叠的 Think 行绝不钉住，并限定在 Think 行自己的 root 之下，不触及任何工具调用 variant。压缩规则是 `packages/client/ui-chat/src/client/chat/MessageItem.module.css` 的 `.compactionRow:has(.compactionBody) .compactionButton`，正文兄弟节点只在展开时存在于 DOM，所以 `:has()` 就以展开状态门控钉住。
+
+不改动任何 session、wire、durable event 或 model-visible 契约；这是一处纯展示层的 CSS 改动，由既有组件拥有。
+
+## 曾考虑的替代方案
+
+**用 `max-height` 加内部滚动给这两个正文封顶，与工具卡片一致。** 否决：Think 正文是刻意不封顶的，好让推理读起来像普通消息正文（[web-thinking-tail-scroll](../../archived/feature/2026-08-02-web-thinking-tail-scroll.md) 和 `.thinkBody` 注释拥有这一意图），压缩摘要是一个阅读表面。内层滚动框会引入嵌套滚动，滚轮在光标下从整页切换到框内，并把很长的技术性正文压进一个更难读的小窗口。钉住标题保留了流式正文的阅读模型，同时让折叠按钮依然够得着。
+
+**为一致性给每个可折叠行都加钉住标题。** 否决：封顶的工具行因为正文在内部滚动，标题本来就一直可见，没有需要解决的问题。让它们的标题相对整页钉住，会在滚过一连串工具调用时把每个展开行各自钉住的标题堆叠在视口顶部，这是视觉噪音，不是一致性。
+
+**把摘要内代码栏的偏移交给 `CodeBlock` 承担。** 否决：可以让 `CodeBlock` 读取使用方设置的 `--dsl-code-block-banner-top` 之类的属性，这样代码块继续拥有自己的几何，也避免用 `:has()` 选择器伸进另一个包的 DOM。代价是把所有使用方的布局都接到一个只有这个块会设置的属性上，而这段偏移是这个块的呈现问题、不是代码块的：局部规则把偏移写在造成它的折叠按钮旁边，而 `[data-code-block-banner]` 本来就是 `CodeBlock` 为使用者样式发布的钩子。
+
+**在 `DisclosureRow` 基元上加一条共享的 sticky 规则。** 否决：`DisclosureRow` 支撑 Think、每个工具调用 variant 以及 context-injection 行；在那里加规则会一并命中封顶行。该行为只属于不封顶的消费者，所以各自把规则限定在自己的块上。
+
+## 后果
+
+很长的 Think 块或压缩摘要的折叠按钮无需把正文滚回起点就能够到，同时两个正文都保持作为整页正文流动。改动是纯 CSS：没有计时器、订阅、durable state、DOM 结构改动或传输流量。压缩规则使用 CSS `:has()` 选择器，Web UI 所面向的各浏览器均支持。
+
+## 测试
+
+单元测试钉住选择器所依赖的 DOM 锚点：`packages/client/ui-chat/tests/reasoning-row.client.spec.tsx` 断言展开的 Think 行在 `[data-variant='think'][data-expanded] [data-open]` 之下嵌套了 `[data-disclosure-row]`，且折叠行没有 `[data-open]`；`packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx` 断言压缩正文只在展开时出现在 `.compactionRow` 之下。`packages/client/ui-chat/tests/sticky-header-styles.client.spec.ts` 把这两条规则当作 CSS 文本读取，逐条固定钉住所依赖的声明：`position: sticky`、`top: 0`、直角圆角、两侧各自的 `z-index` 级别、折叠按钮高度与代码 banner 偏移共用的那一个量，以及不透明的 hover token——因为 jsdom 不计算 sticky 布局，渲染类测试也无法在某条声明被改动时变红。
+
+真实浏览器证据由两条 keyless Chromium e2e 路径承载。`apps/web/tests/lifecycle-chrome.e2e.ts` 展开已结束轮次的 process 行、展开 Think 行，并断言其标题计算出 `position: sticky`、`top: 0px`（折叠时非 sticky）；该 fixture 录制的 reasoning 只有一行，太短不足以溢出，所以它只证明 CSS 解析到了 Think 标题。`apps/web/tests/seeded-history.e2e.ts` 承载「钉住态随滚动」的证据：它种入一个摘要长度由本套件控制的压缩（一个围栏代码块加 40 个列表项），把视口压小以强制溢出，滚动到 marker 的钉住态，断言标题计算出 `position: sticky`、`top: 0px`、`z-index` 大于代码块 banner、滚动后仍停在滚动口顶边、其自身中心是命中测试命中的最上层元素（折叠按钮保持可点击），以及其 hover 底保持完全不透明（alpha 1）。同一用例还把摘要里的代码 banner 滚到它自己的钉住位置，断言 banner 停在标题带下方、且 banner 的 Copy 控件在它的中心点命中自身，使这条偏移不会退化成控件被盖住。同一用例还写出一份 keyless 几何 golden（`snapshots/web/seeded-history/sticky-geometry.expected.md`），把这些与平台无关的语义事实固定下来，因为这是一处用户可见、但不改动 DOM 与无障碍名称的 CSS 行为，无障碍 golden 捕获不到它。PR demo GIF 用真实服务器加真实模型轮次录制，承载视觉证据：钉住的标题在正文滚动时停留在顶部。
diff --git a/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.i18n.yaml b/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.i18n.yaml
index c9f4dad8fa..d88fb31e2e 100644
--- a/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.md
-2026-09-09-ptc-trajectory-code-inspection.md: 477d199f519b5d515e5d58430bd902d9d209e46b
-2026-09-09-ptc-trajectory-code-inspection.zh.md: f305569176214c63ac549b0ec5103289e3e57a88
+2026-09-09-ptc-trajectory-code-inspection.md: 19779d20e8d08ce0ca9678ab6626765faa13cf65
+2026-09-09-ptc-trajectory-code-inspection.zh.md: 7cdb2321d61893e43426798d311847662450d289
diff --git a/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.md b/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.md
index 477d199f51..19779d20e8 100644
--- a/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.md
+++ b/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.md
@@ -16,6 +16,8 @@ The result view preserves recorded text and uses a tree only for complete JSON o
 
 The [PTC runtime decision](2026-06-15-ptc.md) still owns execution and settlement; the [client presentation decision](../architecture/2026-08-23-client-derived-tool-presentation.md) still owns deriving UI from recorded facts. This inspector adds no Session events or host presentation fields.
 
+Trajectory thinking opens by default and supports manual disclosure. [Chat disclosure defaults](../bug-fix/2026-09-14-chat-presentation-defaults.md) are a separate presentation decision.
+
 ## Alternatives considered
 
 **Keep source inside the argument tree.** JSON escaping obscures program structure and makes copying executable source cumbersome.
@@ -26,4 +28,4 @@ The [PTC runtime decision](2026-06-15-ptc.md) still owns execution and settlemen
 
 ## Consequences
 
-Readers can inspect and copy recorded programs without changing replay data. Schemas with no recognizable language hint receive no syntax highlighting. Component tests cover recorded-name recognition, schema fallback, exact source and argument copying, output states, and independent wrapping. JSON-tree tests cover clipping geometry, missing `ResizeObserver`, clipboard settlement after hover changes or unmount, and value-read counts during hover. Thinking tests cover body arrival, manual disclosure, and switching records; the [PTC browser scenario](../../../../apps/web/tests/ptc-round.e2e.ts) pins the assembled inspector and verifies overflow and the original-JSON round trip.
+Readers can inspect and copy recorded programs without changing replay data. Schemas with no recognizable language hint receive no syntax highlighting. Component tests cover recorded-name recognition, schema fallback, exact source and argument copying, output states, and independent wrapping. JSON-tree tests cover clipping geometry, missing `ResizeObserver`, clipboard settlement after hover changes or unmount, and value-read counts during hover. Thinking tests cover manual disclosure and switching Trajectory records; the [PTC browser scenario](../../../../apps/web/tests/ptc-round.e2e.ts) pins the assembled inspector and verifies overflow and the original-JSON round trip.
diff --git a/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.zh.md b/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.zh.md
index f305569176..7cdb2321d6 100644
--- a/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-09-ptc-trajectory-code-inspection.zh.md
@@ -16,6 +16,8 @@ PTC 程序以 JSON 字符串参数传入。转义使长程序在通用参数树
 
 [PTC 运行时决策](2026-06-15-ptc.zh.md) 仍负责执行与结算；[客户端展示决策](../architecture/2026-08-23-client-derived-tool-presentation.zh.md) 仍负责从已记录事实派生 UI。此检查器不增加 Session 事件或宿主展示字段。
 
+Trajectory 思考默认展开，并支持手动展开折叠。[Chat 展开默认值](../bug-fix/2026-09-14-chat-presentation-defaults.zh.md)是独立的展示决策。
+
 ## 考虑过的替代方案
 
 **把源码保留在参数树中。** JSON 转义遮蔽程序结构，也使复制可执行源码变得繁琐。
@@ -26,4 +28,4 @@ PTC 程序以 JSON 字符串参数传入。转义使长程序在通用参数树
 
 ## 后果
 
-读者可以检查和复制已记录的程序，无需修改回放数据。Schema 没有可识别的语言提示时不提供语法高亮。组件测试覆盖记录工具名识别、Schema 回退、源码与参数原样复制、输出状态及独立换行。JSON 树测试覆盖裁剪几何、缺少 `ResizeObserver`、悬停切换或卸载后剪贴板写入落定，以及悬停期间读取值的次数。思考测试覆盖正文到达、手动展开折叠及记录切换；[PTC 浏览器场景](../../../../apps/web/tests/ptc-round.e2e.ts) 固定组装后的检查器展示，并验证溢出和原始 JSON 的往返切换。
+读者可以检查和复制已记录的程序，无需修改回放数据。Schema 没有可识别的语言提示时不提供语法高亮。组件测试覆盖记录工具名识别、Schema 回退、源码与参数原样复制、输出状态及独立换行。JSON 树测试覆盖裁剪几何、缺少 `ResizeObserver`、悬停切换或卸载后剪贴板写入落定，以及悬停期间读取值的次数。思考测试覆盖手动展开折叠及 Trajectory 记录切换；[PTC 浏览器场景](../../../../apps/web/tests/ptc-round.e2e.ts) 固定组装后的检查器展示，并验证溢出和原始 JSON 的往返切换。
diff --git a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.i18n.yaml b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.i18n.yaml
index 21ad4429b4..a41368552d 100644
--- a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md
-2026-09-09-web-sidebar-terminal.md: ce1162a84d3f96336cbb217dbdfe62d12ac23280
-2026-09-09-web-sidebar-terminal.zh.md: 51e0f374b5fde389323868e56fbd86d3bc5720b3
+2026-09-09-web-sidebar-terminal.md: 9b0c1916872c04611f94bf00f7057cce99671c68
+2026-09-09-web-sidebar-terminal.zh.md: 5bc25f80cf6d33e07d2cec1b48e1f4ca7f7d750c
diff --git a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md
index ce1162a84d..9b0c191687 100644
--- a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md
+++ b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.md
@@ -10,7 +10,11 @@ Web users need an interactive shell beside a Session to inspect the workspace an
 
 ## Decision
 
-`api-terminal-controller` owns user terminals by Session and exposes the `terminal` Remote namespace. `ui-sidebar-terminal` registers native right-sidebar tabs, xterm.js rendering and FitAddon sizing. A new terminal offers installed shells and waits for Start. Host discovery verifies the configured candidates, with the execution default first; creation accepts only a currently discovered path. The browser remembers the last selected shell path in origin-scoped localStorage and falls back to the current default if that path is unavailable. The terminal type declares independent instances, so ordinary page deduplication cannot collapse separate processes when opening or docking tabs. The existing sidebar controls open additional tabs; double-clicking a tab title renames its terminal. Terminal processes use the composed subprocess provider and Session sandbox policy. Shell resolution occurs during discovery and creation; reading limits and reconnecting an existing process do not depend on the default executable remaining available. Interactive shell configuration supplies Tab completion and optional inline suggestions.
+Guide entries declare stable ids within their provider. A keyed `sidebar.right.tab.guide.entry` slot dispatches by the active provider id, so an extension replacing a builtin also controls its guide rendering. The sidebar owns card placement and the default fallback; provider components own their controls and read the enclosing tab through framework hooks. An entry slot allows a shell menu without replacing the entire guide or nesting an interactive button inside another button.
+
+The application theme supplies terminal default colors. The body reads resolved CSS tokens, and updates xterm only when those colors change. Public OSC parser observers retain indexed and default-color overrides separately from the DSH defaults; resets remove the corresponding override before restoring the current theme. Observers delegate queries and color handling to xterm. xterm's minimum contrast adjustment improves text legibility without remapping ANSI backgrounds. The DOM cursor reads the rendered cell background after each render and uses a contrasting fill through scoped CSS variables, so cursor movement never resets the palette. Browser checks cover indexed, true-color and inverse cells, light/dark switching, OSC retention and reset, and blinking cursor styles.
+
+`api-terminal-controller` owns user terminals by Session and exposes the `terminal` Remote namespace. `ui-sidebar-terminal` registers native right-sidebar tabs, xterm.js rendering and FitAddon sizing. The terminal guide card has a primary action for the remembered available shell and a separate installed-shell menu. Selecting a menu item records its path and opens a new terminal immediately; discovery alone allocates no process. Each tab owns its startup and close lifecycle. Host discovery verifies the configured candidates, with the execution default first; creation accepts only a currently discovered path. The browser remembers the last selected shell path in origin-scoped localStorage and falls back to the current default if that path is unavailable. The terminal type declares independent instances, so ordinary page deduplication cannot collapse separate processes when opening or docking tabs. The existing sidebar controls open additional tabs; double-clicking a tab title renames its terminal. Terminal processes use the composed subprocess provider and Session sandbox policy. Shell resolution occurs during discovery and creation; reading limits and reconnecting an existing process do not depend on the default executable remaining available. Interactive shell configuration supplies Tab completion and optional inline suggestions.
 
 Close and replacement remove the tab synchronously and run process cleanup in the background. The Client first records the unfinished close request under a terminal-specific localStorage key; success removes it, and startup retries requests that remain. A cleanup failure produces a lightweight notification with a retry action without reopening the tab. Independent keys prevent another window from overwriting unrelated cleanup requests. Collapse, tab/Session switching, floating, fullscreen and browser disconnection preserve the process. Component cleanup and `TabDomain.signal` only detach browser work because the same lifetime can end during plugin reload. Failed process cleanup retains ownership, including failures after allocation but before create publication. Session owner disposal and Host plugin disposal also clean up terminals. A definitive missing-Session response retires its saved close request because the Session owns process cleanup; transport failures remain retryable. Client plugin disposal awaits every detached stream so a replacement plugin does not inherit unfinished Client cleanup.
 
diff --git a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.zh.md b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.zh.md
index 51e0f374b5..5bc25f80cf 100644
--- a/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-09-web-sidebar-terminal.zh.md
@@ -10,7 +10,11 @@ Web 用户需要在 Session 旁使用交互式 shell 检查工作区和运行命
 
 ## 决定
 
-`api-terminal-controller` 按 Session 管理用户终端并提供 `terminal` Remote namespace。`ui-sidebar-terminal` 注册原生右侧栏标签页，使用 xterm.js 渲染和 FitAddon 测量尺寸。新终端提供已安装 shell 的选择并等待用户启动。Host 探测会验证配置的候选，并把执行环境默认项放在首位；创建只接受当前探测返回的路径。浏览器在当前站点 localStorage 中记住上次选择的 shell 路径，该路径不可用时回到当前默认项。终端类型声明独立实例，因此打开或停靠标签页时，普通页面的去重规则不会合并不同进程。已有侧栏控件负责打开更多标签页，双击标签页标题可重命名终端。终端进程使用组合的 subprocess provider 和 Session sandbox policy。shell 在探测和创建时解析；读取限制和重新连接已有进程不依赖默认可执行文件仍然可用。交互式 shell 配置提供 Tab 补全和可选的内联建议。
+开始页入口声明 provider 内稳定的 id。keyed `sidebar.right.tab.guide.entry` slot 按当前生效的 provider id 分发，因此替代 builtin 的 extension 也控制对应入口的渲染。侧栏负责卡片排列和默认回退，provider 组件负责自己的控件，并通过框架 hook 读取所在标签页。入口 slot 可以承载 shell 菜单，无需替换整个开始页或把交互按钮嵌套在另一个按钮内。
+
+应用主题提供终端的默认颜色。终端正文读取解析后的 CSS 令牌，仅在颜色变化时更新 xterm。公开的 OSC 解析观察器将索引色和默认颜色覆盖与 DSH 默认值分开保存；重置命令先删除对应覆盖，再恢复当前主题。观察器将查询和颜色处理交给 xterm。xterm 的最小对比度调整改善文字可读性，同时不重新映射 ANSI 背景色。DOM 光标在每次渲染后读取单元格实际背景，通过局部 CSS 变量使用有足够对比度的填充色，因此光标移动不会重置调色板。浏览器检查覆盖索引色、真彩色、反色单元格、明暗主题切换、OSC 保留和重置，以及闪烁光标样式。
+
+`api-terminal-controller` 按 Session 管理用户终端并提供 `terminal` Remote namespace。`ui-sidebar-terminal` 注册原生右侧栏标签页，使用 xterm.js 渲染和 FitAddon 测量尺寸。终端开始页卡片的主操作打开上次选择且仍可用的 shell，独立菜单提供已安装 shell。选择菜单项会记录路径并立即打开新终端；仅探测 shell 不分配进程。每个标签页拥有自己的启动和关闭生命周期。Host 探测会验证配置的候选，并把执行环境默认项放在首位；创建只接受当前探测返回的路径。浏览器在当前站点 localStorage 中记住上次选择的 shell 路径，该路径不可用时回到当前默认项。终端类型声明独立实例，因此打开或停靠标签页时，普通页面的去重规则不会合并不同进程。已有侧栏控件负责打开更多标签页，双击标签页标题可重命名终端。终端进程使用组合的 subprocess provider 和 Session sandbox policy。shell 在探测和创建时解析；读取限制和重新连接已有进程不依赖默认可执行文件仍然可用。交互式 shell 配置提供 Tab 补全和可选的内联建议。
 
 关闭和替换会同步移除标签页，并在后台清理进程。Client 先以终端独立的 localStorage key 保存未完成的关闭请求；成功后删除，启动时重试剩余请求。清理失败时显示带重试操作的轻量通知，不重新打开标签页。独立 key 避免其他窗口覆盖无关的清理请求。折叠、切换标签页或 Session、浮动、全屏和浏览器断线均保留进程。组件清理和 `TabDomain.signal` 只停止浏览器工作，因为插件重新加载也会结束这些生命周期。进程清理失败时保留所有权，包括分配完成但 create 尚未发布时的失败。Session owner 和 Host 插件卸载也会清理终端。 明确的 Session 不存在响应会清除已保存的关闭请求，因为进程清理由 Session 负责；传输失败仍可重试。Client 插件卸载等待所有断开的流结束，避免替换插件继承未完成的 Client 清理。
 
diff --git a/.agents/notes/implemented/feature/2026-09-11-sidebar-document-preview-polish.i18n.yaml b/.agents/notes/implemented/feature/2026-09-11-sidebar-document-preview-polish.i18n.yaml
new file mode 100644
index 0000000000..fe0979cdb2
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-11-sidebar-document-preview-polish.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-11-sidebar-document-preview-polish.md
+2026-09-11-sidebar-document-preview-polish.md: b78141881513167a08050afb287eb4d1bcb43995
+2026-09-11-sidebar-document-preview-polish.zh.md: 43016af0dff72ed09a19271535912ba9abd65d9c
diff --git a/.agents/notes/implemented/feature/2026-09-11-sidebar-document-preview-polish.md b/.agents/notes/implemented/feature/2026-09-11-sidebar-document-preview-polish.md
new file mode 100644
index 0000000000..b781418815
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-11-sidebar-document-preview-polish.md
@@ -0,0 +1,35 @@
+# Agent Note: Sidebar document preview polish
+
+Status: implemented
+
+English | [中文](2026-09-11-sidebar-document-preview-polish.zh.md)
+
+## Problem
+
+The Sidebar document preview accumulated several experience defects (issue #3974). Images rendered at their intrinsic CSS-pixel size, so a wide image overflowed the pane and forced horizontal scrolling. The viewer dropdown always appended the plain-text fallback, so bitmap and PDF files offered a "Plain text" choice whose result is unreadable bytes, and files with one real renderer still showed a control with nothing meaningful to switch to. Binary containers with no renderer at all (video, archives, office documents) fell into the plain-text reader and surfaced a read error instead of a designed empty state. Each renderer carried its own loading copy and position, so opening a file flashed through several differently worded, differently placed indicators. PDF pages sat inside a double inset that shrank every page below the pane's width. Switching sidebar tabs remounted the file tree at scroll top, losing the reader's place.
+
+## Decision
+
+**Image width fit.** The image frame follows the scroller's width with a 12px inset; the image itself carries `max-width: 100%` and an 8px corner radius, so a wider image scales down to the pane's width at its aspect ratio, a smaller image keeps its intrinsic size centred by auto margins, and a taller image scrolls vertically in the shared body. Height fitting was considered and dropped: it needs a fixed-height frame, and mixed portrait cases produced surprising layouts for no user request.
+
+**Binary viewer choices.** `DocumentPreviewDefinition` gains optional `binaryExtensions`, the suffixes among a renderer's `extensions` whose bytes are not readable text; `register` rejects an entry absent from `extensions`. The renderer owns this knowledge: the image body declares `png, jpg, jpeg, gif, webp, bmp, ico` and leaves `svg` out because SVG source is readable XML; the PDF body declares `pdf`. `binaryDocumentPath` in the registry module answers whether any registered definition declares a filename's suffix binary, and the preview owner skips the plain-text fallback for such files. The header renders the viewer menu only when at least two candidates exist; a single candidate shows no viewer control at all.
+
+**Unsupported empty state.** The owner-side list in `document/unviewable.ts` names binary container suffixes (video, audio, archives, office documents, executables, fonts, disk images, design formats) that no renderer claims. The owner consults it only when no implementation matches, so any renderer registration always wins; a matching file shows the path header, the file-type icon, and one `unsupportedFile` line, and never issues a read. An uncertain suffix stays out of the list and keeps the plain-text fallback; a text-claimed file whose bytes fail the reader's checks reports the same copy through `error.notText`.
+
+**Unified loading.** `LoadingIndicator` renders icon-only, carrying its label as `aria-label` with no visible text; every renderer's loading copy is the shared "Reading…". Every wait before content exists — the owner's first read, PDF parsing, HTML packaging, image decoding — centres the spinner in the pane, so opening a file shows one spinner in one position until the body appears. An unrendered PDF page holds its place as a static 3:4 placeholder block on the theme's skeleton token `--dsw-alias-bg-skeleton` with no spinner; the document-open wait stays the owner's centred read spinner rather than the first page's placeholder, because the read spinner precedes the placeholder and a handoff between them visibly jumps positions. Placeholders carry no shimmer animation, whose per-page cost outweighs its value.
+
+**PDF full-bleed and copy.** The PDF body and page insets are removed so pages fill the pane's width edge to edge; the image renderer keeps its own 12px inset. Chinese error and status lines across the preview dictionaries drop trailing full stops.
+
+**Files tree scroll restore.** `ui-sidebar-files` follows the document preview's own pattern: the tree store gains `scrollTop` with a `scrolled` action, the body tracks its scroll offset locally and commits it once, on unmount and only while the owner's signal is live, and a remount restores it in a layout effect. Loaded levels already outlive the body in the store, so the remounted tree lays out at full height before the offset re-lands.
+
+## Alternatives considered
+
+**A boolean `binary` flag per definition.** The image renderer covers both bitmaps and SVG under one registration, so binariness is a property of the suffix, not the renderer.
+
+**Filtering in the preview owner by a hardcoded suffix list for registered renderers.** The owner would duplicate knowledge each renderer already holds, and external renderers could not extend the set; the owner-side list exists only for suffixes no renderer claims.
+
+**A one-item static viewer label.** Rendering the single remaining candidate as a static name puts a control that offers no action in the header; it is noise, so the header renders nothing.
+
+## Consequences
+
+Images never scroll horizontally; the pane's width is the only layout input, so no zoom control was added. Bitmap and PDF tabs show no viewer control; SVG keeps the menu with the plain-text choice; unclaimed binary containers show the empty state without reading. From open to first content every preview shows one centred icon-only spinner, and PDF pages appear as quiet placeholder blocks. The file tree comes back where the reader left it after any tab switch. Registry unit tests pin `binaryDocumentPath` matching and `register`'s rejection of a binary suffix outside `extensions`, toolbar tests pin the fallback/menu/empty-state branches, files-body tests pin scroll capture on unmount and restore across a remount, and the keyless Web document-preview scenario measures the width-fitted SVG against the pane and asserts the viewer control's absence per suffix.
diff --git a/.agents/notes/implemented/feature/2026-09-11-sidebar-document-preview-polish.zh.md b/.agents/notes/implemented/feature/2026-09-11-sidebar-document-preview-polish.zh.md
new file mode 100644
index 0000000000..43016af0df
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-11-sidebar-document-preview-polish.zh.md
@@ -0,0 +1,35 @@
+# Agent Note：侧边栏文档预览打磨
+
+Status: implemented
+
+[English](2026-09-11-sidebar-document-preview-polish.md) | 中文
+
+## 问题
+
+侧边栏文档预览积累了多处体验缺陷（issue #3974）。图片按固有 CSS 像素尺寸渲染，宽图撑出面板、只能横向滚动。查看器下拉总是追加纯文本兜底，位图和 PDF 文件因此提供一个结果是不可读字节的「纯文本」选项，而只有一个真实渲染器的文件仍显示一个没有可切换项的控件。完全没有渲染器的二进制容器（视频、压缩包、office 文档）落入纯文本读取器，呈现的是读取报错而非设计过的空态。各渲染器自带不同的 loading 文案和位置，打开文件时会闪过多个措辞、位置都不同的指示器。PDF 页面被双层内边距包裹，每一页都窄于面板宽度。切换侧栏 tab 会让文件树重挂载回到顶部，丢掉读者原来的位置。
+
+## 决定
+
+**图片宽度适配。** 图片外框跟随滚动容器的宽度并带 12px 内边距；图片本身使用 `max-width: 100%` 和 8px 圆角，宽图按纵横比缩小到面板宽度，小图保持固有尺寸并由 auto margin 居中，超高图在共享正文中纵向滚动。高度适配曾被考虑后放弃：它需要外框定高，且混合纵向场景会在没有用户诉求的情况下产生意外布局。
+
+**二进制查看器选项。** `DocumentPreviewDefinition` 新增可选的 `binaryExtensions`，即渲染器 `extensions` 中字节不可按文本阅读的后缀；`register` 拒绝不在 `extensions` 内的条目。这份知识由渲染器持有：图片正文声明 `png, jpg, jpeg, gif, webp, bmp, ico`，不含 `svg`，因为 SVG 源码是可读的 XML；PDF 正文声明 `pdf`。注册表模块的 `binaryDocumentPath` 判断是否有已注册定义把文件名后缀声明为二进制，预览 owner 对这类文件跳过纯文本兜底。头部仅在候选不少于两个时渲染查看器菜单；只剩一个候选时完全不渲染查看器控件。
+
+**不支持预览的空态。** owner 侧的 `document/unviewable.ts` 列出没有渲染器认领的二进制容器后缀（视频、音频、压缩包、office 文档、可执行文件、字体、磁盘镜像、设计格式）。owner 仅在没有实现匹配时查询该列表，因此任何渲染器注册始终优先；匹配的文件显示路径头部、文件类型图标和一行 `unsupportedFile` 说明，并且不会发起读取。不确定的后缀不进入列表、保留纯文本兜底；被文本认领但字节未通过读取器检查的文件通过 `error.notText` 报告同一句文案。
+
+**统一 loading。** `LoadingIndicator` 只渲染图标，标签作为 `aria-label` 携带、没有可见文字；所有渲染器的 loading 文案统一为共享的「正在读取…」。内容出现前的每个等待——owner 首次读取、PDF 解析、HTML 打包、图片解码——都把 spinner 居中在面板中，打开文件到正文出现始终是同一位置的一个 spinner。未渲染的 PDF 页以主题骨架色 `--dsw-alias-bg-skeleton` 上的静态 3:4 占位块保持位置、不带 spinner；文档打开的等待保持为 owner 的居中读取 spinner，而不是特化进第一页的占位块，因为读取 spinner 在占位块之前出现，两者交接会明显跳位。占位块不带扫光动画，其逐页动画成本高于价值。
+
+**PDF 铺满与文案。** 移除 PDF 正文和页面的内边距，页面贴边占满面板宽度；图片渲染器保留自己的 12px 内边距。预览各字典的中文报错与状态文案去掉句尾句号。
+
+**文件树滚动恢复。** `ui-sidebar-files` 沿用文档预览自己的模式：树存储新增 `scrollTop` 与 `scrolled` action，正文在本地记录自己的滚动偏移、只在卸载时且 owner 的 signal 仍存活的情况下提交一次，重挂载时在 layout effect 中恢复。已加载的层本就在存储中比正文活得久，因此重挂载的树在偏移落回之前已按完整高度布局。
+
+## 曾考虑的替代方案
+
+**按定义级布尔 `binary` 标志。** 图片渲染器在一个注册中同时覆盖位图和 SVG，二进制与否是后缀的属性，不是渲染器的属性。
+
+**在预览 owner 中按硬编码后缀列表过滤已注册渲染器。** owner 会重复各渲染器已持有的知识，外部渲染器也无法扩展该集合；owner 侧列表只服务于没有渲染器认领的后缀。
+
+**单项静态查看器标签。** 把唯一候选渲染为静态名称，会在头部放一个不提供任何操作的控件；它只是噪音，因此头部什么都不渲染。
+
+## 后果
+
+图片不再产生横向滚动；面板宽度是唯一布局输入，因此未增加缩放控件。位图和 PDF tab 不显示查看器控件；SVG 保留含纯文本选项的菜单；未被认领的二进制容器显示空态且不读取。从打开到首个内容，每种预览都只显示一个居中的纯图标 spinner，PDF 页面以安静的占位块出现。任何 tab 切换之后，文件树都回到读者离开的位置。注册表单元测试固定 `binaryDocumentPath` 的匹配行为与 `register` 对 `extensions` 之外二进制后缀的拒绝，工具栏测试固定兜底/菜单/空态分支，files-body 测试固定卸载时的滚动捕获与跨重挂载的恢复，keyless Web document-preview 场景按面板测量适配宽度后的 SVG 并按后缀断言查看器控件的有无。
diff --git a/.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.i18n.yaml b/.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.i18n.yaml
new file mode 100644
index 0000000000..c91b5f6407
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.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-14-docs-mermaid-viewer.md
+2026-09-14-docs-mermaid-viewer.md: 03aecb7b4df1c79d2eb254375f6b2c68145079ac
+2026-09-14-docs-mermaid-viewer.zh.md: b66f427a4820eef0d6fa25b163cfc8e3548ec0c6
diff --git a/.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.md b/.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.md
new file mode 100644
index 0000000000..03aecb7b4d
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.md
@@ -0,0 +1,33 @@
+# Agent Note: Documentation Mermaid viewer
+
+Status: implemented
+
+English | [中文](2026-09-14-docs-mermaid-viewer.zh.md)
+
+## Problem
+
+Complex Mermaid diagrams lose readable detail when scaled to the documentation column. Long sequence diagrams need both magnification and movement to inspect interactions while retaining an overview.
+
+## Decision
+
+The [VitePress theme](../../../../website/.vitepress/theme/index.ts) adds a corner fullscreen icon to each rendered Mermaid SVG. A native modal dialog provides an inert background and Escape dismissal. Its visible title also names it for assistive technology; a missing or blank page heading uses the localized viewer title. A floating toolbar groups zoom controls, the current scale, and fit; close stays in the top corner, and help opens on demand. Keyboard focus cycles through all five buttons. Panzoom supplies pointer, wheel, and pinch interaction. Arrow keys pan in fixed screen distances. Closing restores the entry's focus without scrolling and restores the page's previous overflow setting.
+
+The viewer copies the SVG into a shadow root. Mermaid's embedded selectors and fragment IDs stay local to the copy, so its markers and styles cannot resolve against the original diagram. Panzoom transforms a viewport-sized canvas containing the SVG at its natural viewBox dimensions, so pointer coordinates and the transform origin share the same center; the initial scale and every resize fit the entire diagram without enlarging it beyond its natural size. This preserves vector detail while keeping fit independent of the narrow document column. The canvas has no visible frame; reserved space keeps controls clear of the fitted diagram.
+
+Viewer resources belong to the mounted theme. Route, language, theme, and source-SVG replacement close the active view; asynchronous Mermaid renders receive a fresh entry. The body overflow lock relies on the default theme retaining visible overflow on the HTML element. It avoids mutating HTML attributes, which the Mermaid plugin observes and rerenders in response. The [implementation](../../../../website/.vitepress/theme/mermaid-viewer.ts) leaves Markdown, raw page copies, and `llms.txt` generation with their existing owners.
+
+## Alternatives considered
+
+**Widening the document column.** A wider column cannot provide readable detail for arbitrarily large diagrams, and long diagrams still exceed the viewport.
+
+**A custom overlay with document-wide listeners.** A native dialog already makes the background inert and handles modal dismissal. Theme-owned resources make navigation and teardown explicit; persistent document listeners would require a separate lifetime mechanism.
+
+**A bitmap preview or a same-document SVG clone.** A bitmap loses vector detail at high zoom. A same-document clone duplicates Mermaid's IDs and embedded styles; rewriting all SVG and CSS references would add a parser obligation that a shadow root avoids.
+
+## Consequences
+
+The website gains Panzoom as a direct dependency and uses native dialog, shadow-root, and resize-observer support. Viewer zoom and position are transient: resizing refits the diagram, and navigating or changing the theme closes it. Existing page diagrams remain the reading and link-navigation source.
+
+The [focused tests](../../../../website/tests/mermaid-viewer.spec.ts) run in the root unit-test suite; `docs:check` and `doc-sync` also select them so documentation-only validation exercises the viewer. They cover late rendering, accessible titles, initial and resized fit, control wiring, keyboard cycling, replacement, and resource release.
+
+**CI coverage gap.** The DOM tests mock Panzoom and do not execute browser layout. Native modal behavior, SVG markers, pointer-anchored wheel zoom, canvas dragging, theme colors, and narrow-screen geometry require real-browser verification. The recorded browser demonstration supplies evidence for the current implementation, but it is not an automated regression check.
diff --git a/.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.zh.md b/.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.zh.md
new file mode 100644
index 0000000000..b66f427a48
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.zh.md
@@ -0,0 +1,33 @@
+# Agent Note: 文档站 Mermaid 查看器
+
+Status: implemented
+
+[English](2026-09-14-docs-mermaid-viewer.md) | 中文
+
+## 问题
+
+复杂 Mermaid 图表缩放到文档正文列宽后，细节难以辨认。阅读长时序图需要在保留全图概览的同时放大和平移，以检查交互细节。
+
+## 决策
+
+[VitePress 主题](../../../../website/.vitepress/theme/index.ts) 在每张已渲染的 Mermaid SVG 角落增加全屏图标。原生模态对话框使背景不可交互，并支持 Escape 退出。可见标题也用于辅助技术识别对话框；页面标题缺失或为空白时，使用本地化的查看器标题。浮动工具栏集中显示缩放控件、当前比例和适应窗口操作；关闭按钮位于顶部角落，帮助按需展开。键盘焦点在五个按钮之间循环。Panzoom 提供指针、滚轮和双指交互。方向键按固定的屏幕距离平移。关闭时恢复入口焦点且不滚动页面，并恢复页面原有的 overflow 设置。
+
+查看器将 SVG 复制到 shadow root 中。Mermaid 内嵌的选择器和片段 ID 限定在副本内部，因此副本的标记和样式不会解析到原始图表上。Panzoom 变换与视口等大的画布，其中的 SVG 使用 viewBox 的自然尺寸，使指针坐标与变换原点共享同一个中心；初始缩放以及每次窗口尺寸变化都会适配整张图表，且不会放大到超出自然尺寸。这样既保留矢量细节，也使适配不受文档窄列宽度的影响。画布没有可见边框；预留空间使控件不会遮挡适配后的图表。
+
+查看器资源由已挂载的主题持有。路由、语言、主题和源 SVG 替换都会关闭当前视图；异步渲染的 Mermaid 图表会获得新的入口。body 的 overflow 滚动锁依赖默认主题让 HTML 元素保持 visible overflow。它避免修改 HTML 属性，因为 Mermaid 插件会观察这些属性并重新渲染。[实现](../../../../website/.vitepress/theme/mermaid-viewer.ts) 将 Markdown、原始页面副本和 `llms.txt` 的生成保留在原有归属处。
+
+## 考虑过的替代方案
+
+**加宽文档正文列。** 更宽的正文列无法让任意大小图表的细节都清晰可读，长图仍然会超出视口。
+
+**使用自定义遮罩和文档级监听器。** 原生对话框已经能使背景不可交互，并处理模态退出。由主题持有资源让导航和资源清理的职责明确；持久的文档级监听器则需要单独的生命周期机制。
+
+**位图预览或同文档内的 SVG 副本。** 位图在高倍率缩放下会丢失矢量细节。同文档内的副本会重复 Mermaid 的 ID 和内嵌样式；重写全部 SVG 和 CSS 引用会带来额外的解析职责，而 shadow root 可以避免这项职责。
+
+## 影响
+
+文档站增加了 Panzoom 直接依赖，并使用原生 dialog、shadow root 和 ResizeObserver 支持。查看器的缩放和平移状态是临时的：窗口尺寸变化会重新适配图表，导航或主题变化会关闭视图。原有页面图表仍然是阅读和链接导航的来源。
+
+[定向测试](../../../../website/tests/mermaid-viewer.spec.ts) 属于根单元测试集；`docs:check` 和 `doc-sync`（文档同步门禁）也会选中这些测试，使仅运行文档验证时同样覆盖查看器。它们验证延迟渲染、无障碍标题、初始及窗口变化后的适配、控件连接、键盘焦点循环、图表替换和资源释放。
+
+**CI 覆盖缺口。** DOM 测试模拟了 Panzoom，不执行浏览器布局。原生模态行为、SVG 标记、以指针为锚点的滚轮缩放、画布拖动、主题颜色和窄屏几何布局需要真实浏览器验证。浏览器演示记录提供了当前实现的证据，但不属于自动回归检查。
diff --git a/.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.i18n.yaml b/.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.i18n.yaml
new file mode 100644
index 0000000000..19ee105187
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.md
+2026-09-14-composer-model-and-draft-editor.md: 3f66ab2c73da0a8f66bf43a821cbe5f85363867a
+2026-09-14-composer-model-and-draft-editor.zh.md: aa040b0fa68961d4d5884d73791c4986b8bfab50
diff --git a/.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.md b/.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.md
new file mode 100644
index 0000000000..3f66ab2c73
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.md
@@ -0,0 +1,116 @@
+# Agent Note: Two-stage Composer and DraftEditor isolation
+
+Status: proposed
+
+English | [中文](2026-09-14-composer-model-and-draft-editor.zh.md)
+
+## Problem
+
+One Client needs to edit the same Session's draft and pending attachments in multiple views. A Lexical editor binds only one DOM root; multiple presentation locations need multiple editor instances, but must not own unrelated drafts or upload tasks, or make the Session Controller understand carets, composition, or DOM state.
+
+The current [SessionInputShell](../../../../packages/client/ui-conversation/src/client/input/facade.ts) combines Lexical operations, draft projection, the submission state machine, and failure recovery. [InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx) combines editor presentation, DOM bindings, attachment intake, and submission controls. Implementing multiple instances directly in these files would mix code extraction with behavior changes.
+
+[ConversationController](../../../../packages/client/ui-conversation/src/client/service.ts) already owns attachment entities and upload tasks centrally; the shell retains only ordered attachment IDs. Selecting a skill inserts ordinary `/name` text whose highlighting derives from a lexicon; atomic file and Session references use chips carrying source identity. A shared draft must not lose these references by synchronizing text alone, and does not require copying attachment entities.
+
+This proposal details editor isolation for [#3951](https://github.com/deepseek-ai/deepseek-harness/pull/3951), following [Client Session and UI ownership](../../implemented/architecture/2026-08-20-client-session-conversation-ownership.md). The Session activity view, residency states, and eviction policy are designed independently; [#4138](https://github.com/deepseek-ai/deepseek-harness/pull/4138) is only a Host lifecycle reference. This proposal implements none of those features and does not repeat the Conversation component decomposition in #3984.
+
+## Proposal
+
+Use two independent PRs. Stage one concentrates existing editor implementation into explicit locations for behavior changes; stage two changes behavior only. `DraftEditor` names the draft-editing area, while Composer names the complete writing area including attachments and submission controls. Keep `input/`, `skeleton/`, `InputBar`, `InputHub`, and `SessionInputShell`; directory moves and renames are not refactoring deliverables.
+
+### Stage one: five mechanical responsibility extractions
+
+The ui-conversation paths below are relative to `packages/client/ui-conversation/src/client/`. Every new file must contain logic already executed today, not placeholder interfaces or future features.
+
+| Original location | Extraction destination | Location for later behavior changes |
+|---|---|---|
+| Lexical creation, registration, projection, node operations, and cleanup in `input/facade.ts` | `input/editor/runtime.ts` | One editor's implementation and its creation, binding, and disposal |
+| Text-area JSX in `skeleton/InputBar.tsx` | `input/editor/DraftEditor.tsx` | One editor's presentation, excluding the attachment rail and submission orchestration |
+| Focus, selection reveal, wheel, keymap, and picker binding functions in `InputBar.tsx` | `input/editor/view-binding.ts` | DOM interaction and editor bindings for one mounted view |
+| Range, reference, and keyboard interface types in `contract/input.ts` | `contract/draft-editor.ts` | Editor-facing data and operation types; submission and shared state stay in the original file |
+| Document drop effect implementation in `ui-attachment/src/client/ComposerAttachments.tsx` | `ui-attachment/src/client/drop-events.ts` | Document drag-and-drop registration, routing, and cleanup |
+
+The existing shell creates and delegates to the internal object in `runtime.ts`. That object retains the original editor, NodeKey map, projection, and Lexical registrations; it neither copies those states nor independently decides whether editing or submission is permitted. The shell retains SubmitMachine, draft revision, attachment IDs, notices, attempts, serialization, and success/failure recovery decisions.
+
+Methods combining guards and node operations retain their guards at the original location. For example, beginCommand keeps its span/phase checks, node replacement, and machine dispatch in the same order; failure recovery preserves batch ordering, revision guards, restoration flags, and history cleanup timing. Editor updates still call the shell synchronously at the original publication point, without another Promise, effect, or notification turn.
+
+`DraftEditor.tsx` extracts presentation without adding a DOM wrapper. All existing React hooks, refs, dependency arrays, and relative effect order remain in InputBar; effects delegate to ordinary functions at their original call sites. CSS files, class keys, React keys, placeholder order, and decorator order remain unchanged. The new component does not take over editor creation or hold another draft.
+
+`contract/draft-editor.ts` receives `TokenSpan`, `ReferenceInsert`, `ArbitrateKey`, `ArbitrateOutcome`, `ComposerKeyboard`, `EditSelection`, and `Occurrence`. Names and members remain unchanged, consumers import from the actual declaration owner, and existing public exports retain their names and visibility. `ComposerKeyboard` temporarily still depends on shared `InputState`; this is not an independent controlled-editor protocol.
+
+#### Stage-one invariants
+
+- InputHub still creates one shell and one editor per Session, with unchanged creation, reuse, and disposal timing and counts.
+- Lexical remains the draft authority; Undo/Redo, NodeKey identity, span checks, and revision rules remain unchanged, without a second document or store.
+- `useInput`, `inputActions`, Slots, events, inject declarations, and public APIs retain their names, payloads, and behavior; Host protocols and persistence formats do not change.
+- Attachment selection, upload timing, image previews, submission batches, success clearing, failure restoration, and notice rules remain unchanged.
+- Each original component still registers document drop listeners in the same effect; the single picker, duplicate drop, and single editor/root limitations remain.
+- Tests change only type imports that actually need updating; test filenames, assertions, recorded Sessions, and expected outputs remain unchanged, without snapshot refreshes.
+- No existing file moves, existing private-name changes, CSS changes, new packages, dependencies, renderer scopes, or general state framework.
+
+#### Isolation actually achieved in stage one
+
+| Subject | Result |
+|---|---|
+| Editor implementation | Node and projection operations belong to runtime, presentation to DraftEditor, and DOM bindings to view-binding |
+| Submission and attachment orchestration | Still owned by the original shell and ConversationController, not DraftEditor |
+| State across different Sessions | Remains isolated under existing rules |
+| Shared state within one Session | Still reuses the original shell, without duplicate attachments or uploads |
+| Independent editors within one Session | Not implemented; views still share one Lexical editor |
+| Independent selection, IME, Undo, and menu origins | Not implemented; separating code does not change runtime ownership |
+| Multi-view picker, focus, and document drop routing | Not implemented; binding code has a separate location for modification |
+
+### Stage two: behavior changes only
+
+Stage two implements a shared draft and multiple editors directly in the locations above. It must not move existing files or directories, perform pure renames or helper/class/component extractions, reorder existing tests, or clean up formatting or comments. New types, implementations, and tests required by new behavior may be added, but copying old code into a new file and deleting its original does not evade this restriction.
+
+If behavior implementation still needs structural preparation, complete stage one first: amend its PR before merge, or add a separate mechanical prerequisite PR after merge. The behavior PR uses that mechanical result as its base and cannot include the preparation.
+
+#### Final state ownership
+
+The shared Composer model evolves the responsibilities of the existing SessionInputShell without requiring another rename. The Session Controller continues to own only Session business state and does not import DraftEditor, Lexical, or the shared draft document.
+
+| State | Final owner | Multi-view requirement |
+|---|---|---|
+| Draft text, semantic references, and content revision | Session-associated shared Composer model | Publish edits from either view to every view through one reactive source |
+| Ordered attachment IDs, claims, submission attempts, and failure recovery | Shared Composer model | Settle each submission once; operations in either view affect the same pending input |
+| File, Blob URL, upload tasks, progress, and receipts | Existing attachment owner | Do not copy per view; unmounting one view does not cancel resources used by another |
+| Lexical, DOM, NodeKey mappings, selection, and IME preedit | Each DraftEditor instance | Two independent editors/roots; unmounting one does not detach the other |
+| Menu anchor, file dialog, and focus | Initiating view | Route by operation origin, not a single Session picker |
+| Session history, running, and queue | Session Controller | Keep reading existing sources instead of copying them into the draft model |
+
+The renderer still binds React hooks from bare observables, and business components read and write through existing standard props. The shared model accepts neither DOM, Lexical NodeKeys, nor composition intermediate state; DraftEditor receives neither Session/Context nor upload services, only draft data, presentation data, and editing/intent callbacks.
+
+#### Shared content and synchronization requirements
+
+Draft content must represent ordinary text, newlines, and atomic references with complete `ReferenceInsert` information independently of Lexical. Shared reference identity must not depend on one editor's NodeKey; each instance privately maps it to its own nodes. Skills remain ordinary `/name` text, with both views deriving highlights from the same text and lexicon, without an extra selected-skill list or changes to Host recognition.
+
+Draft text is small, so synchronization may use complete semantic documents without requiring a collaborative-editing algorithm. The shared model accepts edits, assigns revisions, and publishes; editors distinguish local changes from external rendering to avoid feedback loops. Callbacks from stale revisions, prior model lifetimes, or unmounted views must not overwrite current content. Submission freezing, success clearing, failure restoration, and attachment changes must reach all views through the same shared source.
+
+IME preedit belongs to the local instance, and updates from another view must not directly disrupt text under composition. Stage two must define and verify how another view's edits, submission clearing, and model release interact with composition. Undo/Redo must also operate on one logical draft, rather than letting two Lexical histories restore stale whole documents over each other; synchronization and history implementation are outside the mechanical stage.
+
+Programmatic insertion, menu selection, file selection, and focus restoration need the initiating view's temporary identity. Closing that view must not redirect late UI actions into another view of the same Session. Document drop must select one explicit target and process the drop exactly once; origin routing and deduplication are stage-two behavior.
+
+Existing text-draft restoration after refresh must remain, without implicitly promising persistence for structured references, File objects, or cross-browser collaboration. The Session activity view and LRU/timeout policy remain independent of this editing protocol.
+
+## Alternatives considered
+
+**Only rename input or relocate it to composer.** This does not separate Lexical operations, view bindings, and submission decisions; behavior implementation would still need to extract old code from large files, so it is not a stage-one deliverable.
+
+**Bind one Lexical editor to two DOM roots.** This conflicts with Lexical's single-root model; copying React presentation does not create two independently interactive editors.
+
+**Give each Composer an independent draft and attachments.** This fails the same-Session shared-editing requirement and introduces conflicting attachment and submission ownership.
+
+**Implement a shared DraftDocument, Undo, or drop deduplication in the mechanical stage.** This changes authority, lifecycle, or event-processing counts and cannot be reviewed as behavior-preserving preparation.
+
+## Acceptance criteria
+
+Stage one completes the five extractions and required imports, JSDoc, and README updates; review compares original method bodies, branches, callback order, hooks, DOM, and cleanup. Existing editing, reference, claim, attachment, submission, failure-restoration, and unmount tests continue to pass; focused browser regressions run against built artifacts with unchanged expected output. Type and documentation checks cover relocated declarations and bilingual pairs. New dual-instance functionality is not a stage-one acceptance condition.
+
+Stage two uses two genuinely mounted Composers for one Session to verify bidirectional text and chip synchronization, skill highlights, shared attachments and progress, submission clearing/failure restoration, IME/Undo, origin routing, and continued operation after either view unmounts. Its diff contains behavior implementation and corresponding tests only, without mechanical cleanup.
+
+## Risks
+
+Even stateless JSX extraction can alter ref or effect timing; therefore hooks and refs retain their host, and DOM gains no wrapper. Lexical extraction can alter nested updates, projection caching, or history cleanup order; therefore retain original operation bodies and compare execution order instead of rewriting algorithms.
+
+Stage one still cannot mount two editors for one Session and retains the existing picker/drop limitations. Confusing directory isolation with state isolation could cause roots to detach each other, duplicate attachment intake, or misroute focus; stage-two dual-instance behavior tests must close these gaps.
diff --git a/.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.zh.md b/.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.zh.md
new file mode 100644
index 0000000000..aa040b0fa6
--- /dev/null
+++ b/.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.zh.md
@@ -0,0 +1,116 @@
+# Agent Note: Composer 与 DraftEditor 隔离的两阶段重构
+
+Status: proposed
+
+[English](2026-09-14-composer-model-and-draft-editor.md) | 中文
+
+## 问题
+
+同一个 Client 需要在不同视图中编辑同一个 Session 的草稿和待发送附件。Lexical 的一个 editor 只能绑定一个 DOM root；多个呈现位置需要多个编辑实例，但不能各自拥有互不相干的草稿和上传任务，也不能让 Session Controller 理解光标、输入法或 DOM。
+
+当前 [SessionInputShell](../../../../packages/client/ui-conversation/src/client/input/facade.ts) 同时包含 Lexical 操作、草稿投影、提交状态机和失败恢复。[InputBar](../../../../packages/client/ui-conversation/src/client/skeleton/InputBar.tsx) 同时包含编辑区呈现、DOM 绑定、附件入口和发送控件。直接在这两个文件中实现多实例会让代码提取与行为差异混在一起。
+
+附件实体和上传任务已经由 [ConversationController](../../../../packages/client/ui-conversation/src/client/service.ts) 集中管理，shell 只保留有序附件 IDs。skill（技能）选择插入普通 `/name` 文本，高亮由词表派生；文件和 Session 的原子引用则使用带来源身份的 chip。共享草稿不能只同步文字而丢失这些引用，也不需要复制附件实体。
+
+本提案细化 [#3951](https://github.com/deepseek-ai/deepseek-harness/pull/3951) 的编辑器隔离，遵循 [Client Session 与 UI 所有权](../../implemented/architecture/2026-08-20-client-session-conversation-ownership.zh.md)。Session 活跃视图、驻留状态与回收策略独立设计；[#4138](https://github.com/deepseek-ai/deepseek-harness/pull/4138) 仅作为 Host 生命周期参考。本提案不实现这些功能，也不重复 #3984 的 Conversation 组件拆分。
+
+## 提案
+
+采用两个独立 PR（Pull Request）。第一阶段集中既有编辑实现，为行为改动准备明确位置；第二阶段只修改行为。`DraftEditor` 专指草稿编辑区，Composer 指包含附件和发送控件的完整编写区域。保留 `input/`、`skeleton/`、`InputBar`、`InputHub` 和 `SessionInputShell`，不以改目录或改名作为重构成果。
+
+### 第一阶段：五处机械职责提取
+
+以下 ui-conversation 路径相对 `packages/client/ui-conversation/src/client/`。每个新文件必须承载当前已经执行的逻辑，不建立占位接口或未来功能。
+
+| 原位置 | 提取位置 | 后续行为修改的落点 |
+|---|---|---|
+| `input/facade.ts` 的 Lexical 创建、注册、投影、节点操作和清理 | `input/editor/runtime.ts` | 单个 editor 的实现及其创建、绑定和释放 |
+| `skeleton/InputBar.tsx` 的文字区域 JSX | `input/editor/DraftEditor.tsx` | 单份编辑区的呈现，不包含附件栏和提交编排 |
+| `InputBar.tsx` 的 focus、selection reveal、wheel、keymap、picker 绑定函数 | `input/editor/view-binding.ts` | 单个挂载视图的 DOM 交互和编辑器绑定 |
+| `contract/input.ts` 的范围、引用、键盘接口类型 | `contract/draft-editor.ts` | 编辑器对外数据与操作类型；提交和共享状态仍留原文件 |
+| `ui-attachment/src/client/ComposerAttachments.tsx` 的 document drop effect 实现 | `ui-attachment/src/client/drop-events.ts` | document 拖放监听的注册、路由和清理 |
+
+`runtime.ts` 内部对象由现有 shell 创建并委托调用。它保管原 editor、NodeKey 映射、投影和 Lexical 注册；不复制这些状态，也不独立决定能否编辑或提交。shell 继续持有 SubmitMachine、draft revision、附件 IDs、通知、attempt、序列化以及成功/失败恢复决策。
+
+同时涉及判断和节点操作的方法在原位置保留判断。例如 beginCommand 的 span/phase 检查、节点替换、machine dispatch 的顺序不变；失败恢复的批次排序、revision 保护、恢复标志和 history 清理时点不变。editor 更新仍在原同步位置回调 shell 发布状态，不增加 Promise、effect 或通知轮次。
+
+`DraftEditor.tsx` 是无额外 DOM 包装的呈现提取。所有既有 React 钩子、refs、依赖数组和 effect 相对顺序仍留在 InputBar；effect 只在原调用位置委托普通函数。CSS 文件、class keys、React keys、placeholder 与 decorator 顺序均不变。新组件不接管 editor 创建或持有另一份草稿。
+
+`contract/draft-editor.ts` 移入 `TokenSpan`、`ReferenceInsert`、`ArbitrateKey`、`ArbitrateOutcome`、`ComposerKeyboard`、`EditSelection` 和 `Occurrence`。名称和成员不变，所有消费方从实际声明处导入；既有公开出口保持原名称和可见集合。`ComposerKeyboard` 仍暂时依赖共享 `InputState`，这不是独立受控编辑协议。
+
+#### 第一阶段不变项
+
+- InputHub 仍按 Session 创建一个 shell 和一个 editor，创建、复用、dispose（资源释放）的时点及次数不变。
+- 草稿真值仍在 Lexical，Undo/Redo、NodeKey 身份、span 检查和 revision 规则不变；不增加第二份文档或存储。
+- `useInput`、`inputActions`、Slot、事件、inject 及公开 API 的名称、载荷和行为不变；不改 Host 协议和持久化格式。
+- 附件选择、上传时机、图片预览、提交批次、成功清空、失败恢复及通知规则不变。
+- document drop 仍在每个原组件的同一 effect 中注册；单 picker、重复 drop、单 editor/root 的限制原样保留。
+- 测试只修改实际需要的类型导入；不改测试文件名、断言、录制 Session 或预期输出，不刷新快照。
+- 不搬已有文件，不改已有私有名字，不改 CSS，不增包、依赖、renderer scope 或通用状态框架。
+
+#### 第一阶段实际隔离程度
+
+| 内容 | 完成后的状态 |
+|---|---|
+| 编辑器实现 | 节点和投影操作归 runtime，呈现归 DraftEditor，DOM 绑定归 view-binding |
+| 提交与附件编排 | 仍由原 shell 和 ConversationController 管理，不落入 DraftEditor |
+| 不同 Session 的状态 | 继续按原规则隔离 |
+| 同 Session 的共享状态 | 继续复用原 shell；没有双份附件或上传任务 |
+| 同 Session 的独立编辑实例 | 未实现，仍共享一个 Lexical editor |
+| 独立 selection、IME、Undo 和菜单来源 | 未实现；代码位置分开不代表运行时归属已改变 |
+| picker、focus、document drop 的多视图路由 | 未实现；绑定代码已有单独修改位置 |
+
+### 第二阶段：只调整行为
+
+第二阶段直接在上述位置实现共享草稿和多编辑实例。禁止移动已有文件或目录、纯改名、纯提取 helper/class/component、重排已有测试，以及格式或注释清理。新增行为需要的新类型、实现和测试可以增加，但不得复制旧代码到新文件后删除原文来规避约束。
+
+如果行为实现仍需要结构准备，必须先补第一阶段：未合入时修改第一阶段 PR；已合入时单独增加机械前置 PR。行为 PR 以该机械结果为 base，不能夹带机械准备。
+
+#### 最终状态归属
+
+共享 Composer 模型是现有 SessionInputShell 的职责演进，不要求再次改名。Session Controller 继续只管理会话业务，不 import DraftEditor、Lexical 或共享草稿文档。
+
+| 状态 | 最终 owner | 多视图要求 |
+|---|---|---|
+| 草稿正文、语义引用、内容 revision | Session 关联的共享 Composer 模型 | 任一处编辑后，通过同一个响应式来源发布给所有视图 |
+| 有序附件 IDs、认领、提交 attempt 和失败恢复 | 共享 Composer 模型 | 每个提交只结算一次，任一视图的操作作用于同一批输入 |
+| File、Blob URL、上传任务、进度和凭证 | 既有附件管理 owner | 不随视图复制；卸载一个视图不取消其他视图所用资源 |
+| Lexical、DOM、NodeKey 映射、selection、IME preedit | 各 DraftEditor 实例 | 两个独立 editor/root；卸载一处不解绑另一处 |
+| 菜单锚点、文件对话框和焦点 | 发起操作的视图 | 按操作来源路由，不以 Session 唯一 picker 代替来源 |
+| Session 历史、running、queue | Session Controller | 继续读取现有来源，不复制进草稿模型 |
+
+React 钩子仍由 renderer 从裸 observable 绑定，业务组件通过现有标准 props 读写。共享模型不接收 DOM、Lexical NodeKey 或输入法中间态；DraftEditor 不接收 Session/Context 或上传服务，只接收草稿数据、显示数据与编辑/意图回调。
+
+#### 共享内容和同步要求
+
+草稿内容必须能独立于 Lexical 表示普通文本、换行和带完整 `ReferenceInsert` 信息的原子引用。引用的共享身份不能依赖某个 editor 的 NodeKey；各实例私有映射到自己的节点。skill 保持普通 `/name` 文本，两处从同一文本和词表派生高亮，不引入额外的已选 skill 列表或改变 Host 识别规则。
+
+草稿文本量小，可以使用完整语义文档同步，不要求协同编辑算法。共享模型负责接受编辑、分配 revision 和发布，编辑器区分本地产生的变化与外部呈现，避免回声循环。旧 revision、旧模型生命周期和已卸载视图的回调不能覆盖新内容。提交冻结、成功清空、失败恢复和附件变化必须通过同一共享来源到达所有视图。
+
+IME preedit 属于本地实例，远端视图更新不能直接破坏正在组合的文本。来自另一视图的修改、发送清空和模型释放如何与组合态相遇，必须在第二阶段定义并验证。Undo/Redo 也必须作用于同一份逻辑草稿，不能让两份 Lexical history 互相恢复陈旧整篇文档；具体同步与历史实现不属于机械阶段。
+
+程序化插入、菜单选择、文件选择器和焦点恢复要携带发起视图的临时身份。视图关闭后不能把迟到的 UI 操作转发给另一个同 Session 视图。document drop 必须明确一次拖放选哪个目标并保证仅处理一次；来源路由和去重均是第二阶段行为。
+
+刷新后的既有文字草稿恢复应保留，但不默认新增结构化引用、File 或跨浏览器协作的持久化承诺。Session 活跃视图及 LRU/时限策略不与这份编辑协议绑定。
+
+## 考虑过的替代方案
+
+**仅把 input 改名或平移到 composer。** 不能分离 Lexical 操作、视图绑定和提交决策，后续行为实现仍需从大文件中提取旧代码，因此不作为第一阶段成果。
+
+**让一个 Lexical editor 同时挂两个 DOM root。** 与 Lexical 的单 root 模型冲突，不能用 React 复制呈现来获得两个可独立交互的编辑器。
+
+**每个 Composer 独立草稿和附件。** 不满足同一 Session 共享编辑的要求，还会引入附件和提交所有权分歧。
+
+**机械阶段直接实现共享 DraftDocument、Undo 或 drop 去重。** 改变真值、生命周期或事件处理次数，无法作为行为不变的前置改动审查。
+
+## 验收标准
+
+第一阶段必须完成五处提取及必要导入、JSDoc 和 README 更新；逐项核对原方法体、分支、回调次序、Hooks、DOM 和清理。现有编辑、引用、认领、附件、提交、失败恢复和卸载测试继续通过；用构建产物运行针对性浏览器回归，预期输出不变。类型和文档检查覆盖移动后的声明与双语配对。不以新双实例功能作为第一阶段验收条件。
+
+第二阶段必须用同一 Session 的两个真实挂载 Composer 验证双向文字和 chip 同步、skill 高亮、共享附件和进度、发送清空/失败恢复、IME/Undo、来源路由，以及任一视图卸载后另一处继续工作。其差异必须仅包含行为实现及相应测试，不包含机械整理。
+
+## 风险
+
+无状态 JSX 提取仍可能改变 ref 或 effect 时序；因此 Hook 和 ref 的宿主保持不变，DOM 不增加包装。Lexical 提取可能改变嵌套 update、projection 缓存或 history 清理顺序；因此保留原操作体并对照执行次序，而非重写算法。
+
+第一阶段仍不能同时挂载同 Session 的两个编辑器，且保留原 picker/drop 限制。后续若误把目录隔离当成状态隔离，会造成 root 相互解绑、重复附件接收或错误焦点路由；这些限制必须由第二阶段的双实例行为测试关闭。
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 46e3157421..72e4d1807d 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -159,6 +159,7 @@ External packages **directly declared** for development, tests, types, or toolin
 | [`@modelcontextprotocol/server`](https://github.com/modelcontextprotocol/typescript-sdk) | 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 |
+| [`@panzoom/panzoom`](https://github.com/timmywil/panzoom) | MIT |
 | [`@stylistic/eslint-plugin`](https://github.com/eslint-stylistic/eslint-stylistic) | MIT |
 | [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library) | MIT |
 | [`@testing-library/react`](https://github.com/testing-library/react-testing-library) | MIT |
@@ -219,6 +220,7 @@ External packages **directly declared** for development, tests, types, or toolin
 | [`vitepress`](https://github.com/vuejs/vitepress) | MIT |
 | [`vitepress-plugin-mermaid`](https://github.com/emersonbottero/vitepress-plugin-mermaid) | MIT |
 | [`vitest`](https://github.com/vitest-dev/vitest) | MIT |
+| [`vue`](https://github.com/vuejs/core) | MIT |
 
 `eslint-plugin-sonarjs` (LGPL-3.0-only) and `lightningcss` (MPL-2.0) run only as development tooling; their code is not linked into or distributed with any DeepSeek Harness artifact.
 
diff --git a/apps/cli/package.json b/apps/cli/package.json
index f59dfb046b..b5374d67f0 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -99,7 +99,7 @@
     "@deepseek-ai/schemastery": "workspace:^",
     "commander": "^15.0.0",
     "js-yaml": "^4.2.0",
-    "node-addon-require-builtin": "^0.1.4",
+    "node-addon-require-builtin": "^0.1.6",
     "@deepseek-ai/dsh-http-proxy": "workspace:^",
     "@deepseek-ai/dsh-mcp-resources": "workspace:^"
   },
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 2745d4c3b3..cc391cbb4b 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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/reference/README.md
-README.md: 5a92052eb24c8af432c2ede371a2ff2bc84f57c0
-README.zh.md: a9268ad4920a7d5a72a4b0ead9b2672d22e10805
+README.md: b2931e05c1c10c6de13427b2cdaf38a0e78db904
+README.zh.md: 2a9014a5d338c3d81d9976d8cb47474a95c45cb5
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 5a92052eb2..b2931e05c1 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -8,7 +8,7 @@ This reference defines the profile, web-alias, plugin-management, and config-dum
 
 `dsh --profile <name>` boots the profile at `$DSH_HOME/profiles/<name>`. The effective tree is composed over an empty root by applying, in order: each bundle patch named in the profile manifest's `dsh.profile.bundles` list, the profile's own `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml` (machine-local preferences shared by every profile, so it outranks the per-profile layer), and each `--patch <path>` overlay in argv order. Later layers win per row; a patch replaces the targeted row's complete `config` value rather than deep-merging keys, and may insert new rows. `dsh.profile.patchReload` selects `live` patch-file watching or `startup` one-time loading; omission defaults a custom profile to `live`. A parse, schema, resolution, or plugin boot failure is reported and exits nonzero. SIGINT and SIGTERM dispose the mounted root before exit.
 
-Bundle names resolve from the dsh installation first, then from the profile directory. In-box bundles (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`, `@deepseek-ai/dsh-sdk-app`, `@deepseek-ai/dsh-sdk-minimal`, `@deepseek-ai/dsh-acp-app`) therefore always come from the same installation as the running `dsh`; out-of-tree bundles come from the profile's pnpm-managed `node_modules`. A bare plugin `name` in any patch row resolves through the profile directory's Node parent walk, which reaches the maintained installation fallback `$DSH_HOME/profiles/node_modules`. Plain Node installations place one healed symlink there per dependency-closure package. A pkg executable instead places a real ESM proxy that mirrors explicit exports and re-exports the virtual package URL, because operating-system symlinks cannot enter pkg's `/snapshot` filesystem. Every launch also links packages carried only by selected external bundles through a dsh-owned directory into the current profile's `node_modules`; existing pnpm entries win, and each profile owns its links independently.
+Bundle names resolve from the dsh installation first, then from the profile directory. In-box bundles (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`, `@deepseek-ai/dsh-sdk-app`, `@deepseek-ai/dsh-sdk-minimal`, `@deepseek-ai/dsh-acp-app`) therefore always come from the same installation as the running `dsh`; out-of-tree bundles come from the profile's pnpm-managed `node_modules`. Before mounting rows, the launcher traverses the installation and selected bundles in that order and materializes the resulting fallback links. The internal runtime and dual modes consume the same immutable generation in tests without changing the CLI's link-mode behavior. Profile-installed packages keep native priority in every mode.
 
 The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize from shipped templates on first use (`web`: base + web-app with live patches; `headless`: base + headless with startup-only patches; `sdk`: base + sdk-app with startup-only patches; `sdk-minimal`: its standalone bundle with startup-only patches; `acp`: base + acp-app with startup-only patches). Any other missing profile fails loudly with a hint to run `dsh plugin --profile <name> add <package>`.
 
@@ -98,9 +98,9 @@ New sessions in base-backed profiles default to the `workspace-write` permission
 
 ## Shared deployment behavior
 
-The base bundle mounts the native DeepSeek adapter, settings and credential providers, stable `web_search` and `web_fetch`, the public-only HTTP fetch provider, opt-in DeepSeek session-log upload, and feedback-gated OTel upload for all users. Provider credentials resolve from the inherited environment, `$DSH_HOME/.credentials.yaml`, the invoking directory's `.env`, then `$DSH_HOME/.env`; the managed document is never materialized into `process.env`, while both `.env` files are ordinary launch environment layers. Search uses `DEEPSEEK_API_KEY` and accepts `DEEPSEEK_SEARCH_BASE_URL`. Enabled fetch calls run in every sandbox and approval mode without per-call confirmation; the provider rejects non-public destinations before connecting. The Web app disables the base tool row and exposes the same tools through its `cordis`, `ptc`, and `standard` agent presets.
+The base bundle mounts the native DeepSeek adapter, settings and credential providers, stable `web_search` and `web_fetch`, the public-only HTTP fetch provider, default-on DeepSeek session-log upload, and feedback-gated OTel upload for all users. Provider credentials resolve from the inherited environment, `$DSH_HOME/.credentials.yaml`, the invoking directory's `.env`, then `$DSH_HOME/.env`; the managed document is never materialized into `process.env`, while both `.env` files are ordinary launch environment layers. Search uses `DEEPSEEK_API_KEY` and accepts `DEEPSEEK_SEARCH_BASE_URL`. Enabled fetch calls run in every sandbox and approval mode without per-call confirmation; the provider rejects non-public destinations before connecting. The Web app disables the base tool row and exposes the same tools through its `cordis`, `ptc`, and `standard` agent presets.
 
-Feedback is recorded in the Session log without starting model work. Enable the [DeepSeek session-log contributor](../../../packages/session/session-log-deepseek/README.md) to send complete unaccepted log suffixes with subsequent DeepSeek requests, including requests sent through configured gateways. [OTel session upload](../../../packages/session/session-telemetry-otel/README.md) applies to all users and providers, including `deepseek-official`, without requiring a request header. The base defaults to `FEEDBACK_ONLY`: new own text feedback, message ratings, edits, and withdrawals release the complete canonical prefix through that event, including stored context; later records wait for the next explicit feedback. Inherited parent feedback does not authorize a fork. Requests, restoration, mount, and HMR do not trigger capture. SDK batching may finish an authorized upload without further interaction or model work. `DSH_TELEMETRY_MODE=DISABLED` disables OTel delivery; `FULL` is rejected, and any non-empty `DSH_TELEMETRY_DISABLED` disables its row. `DSH_TELEMETRY_OTLP_URL` selects the collector. Handoff is best-effort, not collector acceptance; no durable outbox or retry guarantee is provided. These OTel settings do not enable or disable the DeepSeek contribution. Neither path changes model input, but exports can include message text, tool arguments and results, and workspace paths.
+Feedback is recorded in the Session log without starting model work. The [DeepSeek session-log contributor](../../../packages/session/session-log-deepseek/README.md) sends complete unaccepted log suffixes with subsequent DeepSeek requests by default, including requests sent through configured gateways; set its `enabled` configuration to `false` to opt out. [OTel session upload](../../../packages/session/session-telemetry-otel/README.md) applies to all users and providers, including `deepseek-official`, without requiring a request header. The base defaults to `FEEDBACK_ONLY`: new own text feedback, message ratings, edits, and withdrawals release the complete canonical prefix through that event, including stored context; later records wait for the next explicit feedback. Inherited parent feedback does not authorize a fork. Requests, restoration, mount, and HMR do not trigger capture. SDK batching may finish an authorized upload without further interaction or model work. `DSH_TELEMETRY_MODE=DISABLED` disables OTel delivery; `FULL` is rejected, and any non-empty `DSH_TELEMETRY_DISABLED` disables its row. `DSH_TELEMETRY_OTLP_URL` selects the collector. Handoff is best-effort, not collector acceptance; no durable outbox or retry guarantee is provided. These OTel settings do not enable or disable the DeepSeek contribution. Neither path changes model input, but exports can include message text, tool arguments and results, and workspace paths.
 
 Install external plugin bundles through `dsh plugin --profile <name> add <package-or-git-spec>`. The installed package owns its dependencies and contributes its declared `cordis.patch.yml` layer. The CLI also ships `@deepseek-ai/dsh-mcp-client` as a dependency for patch layers, but no MCP server is enabled by default because each server command is trusted executable code outside the agent sandbox.
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index a9268ad492..2a9014a5d3 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -10,7 +10,7 @@
 
 `dsh --profile <name>` 启动位于 `$DSH_HOME/profiles/<name>` 的 profile。生效配置树以空根节点为起点，依次叠加 profile manifest（元数据清单）的 `dsh.profile.bundles` 列表中指定的各组合包 patch、profile 自身的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml`（这是各 profile 共享的机器本地偏好，因此优先于逐 profile 配置层），以及按 argv 顺序指定的各个 `--patch <path>` 覆盖层。对同一配置行，后应用的层优先。patch 会替换目标行的整个 `config` 值，而不是深度合并其中的键；patch 也可以插入新行。`dsh.profile.patchReload` 可选择 `live` patch 文件监视或 `startup` 单次加载；自定义 profile 省略该值时默认使用 `live`。配置解析、schema 校验、模块解析或插件启动失败时，系统会报告错误并以非零状态退出。收到 SIGINT 或 SIGTERM 时，挂载的根节点会先 dispose（资源释放）再退出。
 
-组合包名称先从 dsh 安装目录解析，再从 profile 目录解析。因此，内置组合包（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`、`@deepseek-ai/dsh-sdk-app`、`@deepseek-ai/dsh-sdk-minimal`、`@deepseek-ai/dsh-acp-app`）始终来自当前运行的 `dsh` 所属的安装；树外组合包则来自 profile 中由 pnpm 管理的 `node_modules`。patch 行中的裸插件 `name` 会从 profile 目录开始，按照 Node 的模块解析规则逐级向父目录查找，直至由 dsh 维护的安装后备目录 `$DSH_HOME/profiles/node_modules`。普通 Node 安装会为依赖闭包中的每个包放置并修复一个符号链接。pkg 可执行程序则放置真实 ESM 代理，镜像显式 exports 并重新导出虚拟包 URL，因为操作系统符号链接无法进入 pkg 的 `/snapshot` 文件系统。每次启动还会把仅由所选外部组合包携带的包经 dsh 自有目录链接到当前 profile 的 `node_modules`；已有 pnpm 条目优先，且每个 profile 独立拥有自己的链接。
+组合包名称先从 dsh 安装目录解析，再从 profile 目录解析。因此，内置组合包（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`、`@deepseek-ai/dsh-sdk-app`、`@deepseek-ai/dsh-sdk-minimal`、`@deepseek-ai/dsh-acp-app`）始终来自当前运行的 `dsh` 所属的安装；树外组合包来自 profile 中由 pnpm 管理的 `node_modules`。挂载配置行前，launcher 会按此顺序遍历安装与所选 bundle，并物化计算出的 fallback 链接。内部 runtime 与 dual 模式会在测试中消费同一份不可变 generation，但不改变 CLI 的 link 模式行为。所有模式都保留 profile 已安装包的原生优先级。
 
 `web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app，实时应用 patch；`headless`：base + headless，只在启动时应用 patch；`sdk`：base + sdk-app，只在启动时应用 patch；`sdk-minimal`：独立组合包，只在启动时应用 patch；`acp`：base + acp-app，只在启动时应用 patch）。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
 
@@ -100,9 +100,9 @@ dsh web --help
 
 ## 共享部署行为
 
-基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search` 和 `web_fetch`、仅限公网的 HTTP fetch 提供方，需主动开启的 DeepSeek 会话日志上传，以及面向所有用户的反馈门控 OTel 上传。提供方凭据依次从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`。已启用的抓取调用会在所有 sandbox 与审批模式下执行，无需逐次确认；提供方会在连接前拒绝非公开目的地址。Web app 会禁用 base 工具配置项，再通过 `cordis`、`ptc` 与 `standard` agent preset 暴露相同工具。
+基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search` 和 `web_fetch`、仅限公网的 HTTP fetch 提供方，默认开启的 DeepSeek 会话日志上传，以及面向所有用户的反馈门控 OTel 上传。提供方凭据依次从继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`。已启用的抓取调用会在所有 sandbox 与审批模式下执行，无需逐次确认；提供方会在连接前拒绝非公开目的地址。Web app 会禁用 base 工具配置项，再通过 `cordis`、`ptc` 与 `standard` agent preset 暴露相同工具。
 
-反馈记录在会话日志中，不会启动模型工作。开启 [DeepSeek 会话日志贡献器](../../../packages/session/session-log-deepseek/README.zh.md)后，后续 DeepSeek 请求会发送尚未确认接收的完整日志后缀，包括经已配置网关发送的请求。[OTel 会话上传](../../../packages/session/session-telemetry-otel/README.zh.md)适用于所有用户和提供方，包括 `deepseek-official`，无需请求头。基础配置默认使用 `FEEDBACK_ONLY`：新的自身文本反馈、消息评分、编辑与撤回会释放截至该事件的完整规范日志前缀，包含存储的上下文；后续记录等待下一次显式反馈。继承的父级反馈不构成 fork 的授权。请求、恢复、挂载和 HMR 不触发捕获。SDK 批处理可完成已授权上传，无需进一步交互或模型工作。`DSH_TELEMETRY_MODE=DISABLED` 禁止 OTel 投递；`FULL` 被拒绝，任何非空的 `DSH_TELEMETRY_DISABLED` 都会禁用其配置行。`DSH_TELEMETRY_OTLP_URL` 选择采集端。交接尽力而为，不代表采集端接受；不提供持久化 outbox 或重试保证。这些 OTel 设置不会开启或关闭 DeepSeek 贡献。两条路径都不改变模型输入，但导出可能包含消息文本、工具参数和结果，以及工作区路径。
+反馈记录在会话日志中，不会启动模型工作。[DeepSeek 会话日志贡献器](../../../packages/session/session-log-deepseek/README.zh.md)默认随后续 DeepSeek 请求发送尚未确认接收的完整日志后缀，包括经已配置网关发送的请求；将其 `enabled` 配置设为 `false` 可关闭上传。[OTel 会话上传](../../../packages/session/session-telemetry-otel/README.zh.md)适用于所有用户和提供方，包括 `deepseek-official`，无需请求头。基础配置默认使用 `FEEDBACK_ONLY`：新的自身文本反馈、消息评分、编辑与撤回会释放截至该事件的完整规范日志前缀，包含存储的上下文；后续记录等待下一次显式反馈。继承的父级反馈不构成 fork 的授权。请求、恢复、挂载和 HMR 不触发捕获。SDK 批处理可完成已授权上传，无需进一步交互或模型工作。`DSH_TELEMETRY_MODE=DISABLED` 禁止 OTel 投递；`FULL` 被拒绝，任何非空的 `DSH_TELEMETRY_DISABLED` 都会禁用其配置行。`DSH_TELEMETRY_OTLP_URL` 选择采集端。交接尽力而为，不代表采集端接受；不提供持久化 outbox 或重试保证。这些 OTel 设置不会开启或关闭 DeepSeek 贡献。两条路径都不改变模型输入，但导出可能包含消息文本、工具参数和结果，以及工作区路径。
 
 通过 `dsh plugin --profile <name> add <package-or-git-spec>` 安装外部插件组合包。安装的包拥有其依赖，并贡献其声明的 `cordis.patch.yml` 层。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent 沙箱之外的受信任可执行代码。
 
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index 56825b8cdc..f4c0999526 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -19,6 +19,10 @@ import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
 import {
   boot,
+  type ProfileResolutionMode,
+  type ProfileResolutionGeneration,
+  PluginPackages,
+  createProfileResolutionGeneration,
   composeEntries,
   healProfilesModuleFallback,
   healIsolatedProfileModuleFallback,
@@ -194,6 +198,7 @@ export function prepareProfile(name: string, userLayer = true, fromDefaultProfil
 
 /** One profile's patch layers, in application order. */
 interface ComposedProfile {
+  resolution: ProfileResolutionGeneration
   profile: Profile
   /** Bundle layers concatenated — the part below the user layers on a live reload. */
   bundlePatches: PatchOptions[]
@@ -229,13 +234,17 @@ function allPatches(composed: ComposedProfile): PatchOptions[] {
 async function composeProfile(
   name: string,
   patchFiles: readonly string[],
+  resolutionMode: ProfileResolutionMode,
   fromDefaultProfile?: string,
   resolvedProfile?: ResolvedProfileRuntime,
 ): Promise<ComposedProfile> {
   const profile = resolvedProfile?.profile ?? prepareProfile(name, true, fromDefaultProfile)
   if (resolvedProfile !== undefined) writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG)
-  if (resolvedProfile === undefined) await healProfilesModuleFallback({ installAnchor: INSTALL_ANCHOR, profile })
-  else healIsolatedProfileModuleFallback(resolvedProfile)
+  const resolutionOptions = { installAnchor: resolvedProfile?.installAnchor ?? INSTALL_ANCHOR, profile }
+  if (resolvedProfile !== undefined && resolutionMode !== 'runtime') healIsolatedProfileModuleFallback(resolvedProfile)
+  const resolution = resolutionMode === 'runtime' || resolvedProfile !== undefined
+    ? await createProfileResolutionGeneration(resolutionOptions)
+    : await healProfilesModuleFallback(resolutionOptions)
   const homePatches = loadOptionalPatches(NAME, homePatchPath()) ?? []
   const overlays = patchFiles.flatMap(file => loadOverlayPatches(NAME, resolve(file)))
   const bundlePatches = profile.layers.flatMap(layer => layer.patches)
@@ -246,7 +255,7 @@ async function composeProfile(
   const composedOverlays = [...overlays]
   const telemetryPatch = resolveTelemetryPatch(process.env.DSH_TELEMETRY_DISABLED, rows.has(TELEMETRY_ROW_ID))
   if (telemetryPatch !== undefined) composedOverlays.push(telemetryPatch)
-  return { profile, bundlePatches, homePatches, overlays: composedOverlays }
+  return { profile, resolution, bundlePatches, homePatches, overlays: composedOverlays }
 }
 
 /** An application-owned profile and its independent installation fallback. */
@@ -259,6 +268,8 @@ export interface ResolvedProfileRuntime {
 
 /** Options for {@link runProfile}. */
 export interface RunProfileOptions {
+  /** Package lookup strategy; packaged executables always use runtime resolution. */
+  resolutionMode?: ProfileResolutionMode
   /** This run's frozen environment snapshot, provided before any entry mounts. */
   environment: LaunchEnvironmentSnapshot
   /** The profile name to boot. */
@@ -306,6 +317,8 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
     (message) => { process.stderr.write(`${NAME}: ${message}\n`) },
   )
 
+  const packaged = (process as NodeJS.Process & { pkg?: unknown }).pkg !== undefined
+  const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'link'
   const app: { current?: Context } = {}
   let disposal: Promise<void> | undefined
   const dispose = (): Promise<void> => disposal ??= (async () => {
@@ -318,7 +331,7 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
   })()
   try {
     const composed = await composeProfile(
-      options.profile, options.patchFiles, options.fromDefaultProfile, options.resolvedProfile,
+      options.profile, options.patchFiles, resolutionMode, options.fromDefaultProfile, options.resolvedProfile,
     )
     const appReady = createAppReady()
     const shutdown = createProcessShutdown(dispose)
@@ -359,11 +372,15 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
     ])
     // Cloned for the same insert-aliasing reason as composeLive: the boot
     // application must not mutate the objects later reloads recompose from.
-    const ctx = await boot(NAME, rootConfig, structuredClone(allPatches(composed)), (hostCtx) => {
+    const ctx = await boot(NAME, rootConfig, structuredClone(allPatches(composed)), async (hostCtx) => {
       app.current = hostCtx
       // Before any config-tree entry mounts, so plugins resolve all launch-time
       // environment values from the same immutable launch snapshot.
       hostCtx.provide(DSH_LAUNCH_ENVIRONMENT_KEY, options.environment)
+      await hostCtx.plugin(PluginPackages, resolutionMode === 'link' ? {} : {
+        generation: composed.resolution,
+        behavior: resolutionMode === 'dual' ? 'verify' : 'enforce',
+      })
       // The command line and bounded exit request are launcher facts available
       // to every app plugin that injects the argument snapshot.
       provideCmdline(hostCtx, {
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index 38afbf37a8..1ca104879d 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -868,6 +868,7 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     try {
       await waitForFile(fixture.ready)
       expect(readFileSync(fixture.echo, 'utf8')).toBe('bundle-default')
+      expect(existsSync(join(fixture.home, 'profiles', 'node_modules'))).toBe(true)
       requestProfileShutdown(child, fixture)
       expect((await child).exitCode).toBe(0)
     } finally {
diff --git a/apps/cli/tests/profiles/headless/goal-snapshot.patch.yml b/apps/cli/tests/profiles/headless/goal-snapshot.patch.yml
index 220969cfef..7db9691a6c 100644
--- a/apps/cli/tests/profiles/headless/goal-snapshot.patch.yml
+++ b/apps/cli/tests/profiles/headless/goal-snapshot.patch.yml
@@ -24,3 +24,7 @@
 - insert:
     - id: llm-replay
       name: '@deepseek-ai/dsh-llm-replay'
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/apps/cli/tests/profiles/headless/semantic-checkpoint-snapshot.patch.yml b/apps/cli/tests/profiles/headless/semantic-checkpoint-snapshot.patch.yml
index 3e637e28aa..0c818b1641 100644
--- a/apps/cli/tests/profiles/headless/semantic-checkpoint-snapshot.patch.yml
+++ b/apps/cli/tests/profiles/headless/semantic-checkpoint-snapshot.patch.yml
@@ -23,3 +23,7 @@
     # Publish the persisted agent before the driver selects the single root.
     - id: resumed-agent
       name: './tests/fixtures/semantic-checkpoint-agent.ts'
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/apps/cli/tests/profiles/headless/subagent-diagnostic-snapshot.patch.yml b/apps/cli/tests/profiles/headless/subagent-diagnostic-snapshot.patch.yml
index ac47e8d5a2..49b42c91e2 100644
--- a/apps/cli/tests/profiles/headless/subagent-diagnostic-snapshot.patch.yml
+++ b/apps/cli/tests/profiles/headless/subagent-diagnostic-snapshot.patch.yml
@@ -26,3 +26,7 @@
     # Publish the persisted agent before the driver selects the single root.
     - id: resumed-agent
       name: './tests/fixtures/subagent-diagnostic-agent.ts'
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/apps/cli/tests/profiles/headless/subagent-inheritance-snapshot.patch.yml b/apps/cli/tests/profiles/headless/subagent-inheritance-snapshot.patch.yml
index 352841f745..e41c1f97f2 100644
--- a/apps/cli/tests/profiles/headless/subagent-inheritance-snapshot.patch.yml
+++ b/apps/cli/tests/profiles/headless/subagent-inheritance-snapshot.patch.yml
@@ -32,3 +32,7 @@
     # Publish the persisted agent before the driver selects the single root.
     - id: resumed-agent
       name: './tests/fixtures/subagent-inheritance-agent.ts'
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/apps/cli/tests/profiles/headless/subagent-settlement-snapshot.patch.yml b/apps/cli/tests/profiles/headless/subagent-settlement-snapshot.patch.yml
index 85a412e994..498c600d7b 100644
--- a/apps/cli/tests/profiles/headless/subagent-settlement-snapshot.patch.yml
+++ b/apps/cli/tests/profiles/headless/subagent-settlement-snapshot.patch.yml
@@ -28,3 +28,7 @@
     # Hold the parent's second step until the manager notice enters its inbox.
     - id: settlement-fence
       name: './tests/fixtures/subagent-settlement-fence.ts'
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/apps/cli/tests/profiles/headless/workspace-context-resume-snapshot.patch.yml b/apps/cli/tests/profiles/headless/workspace-context-resume-snapshot.patch.yml
index 7e8d306cc3..6507b366d6 100644
--- a/apps/cli/tests/profiles/headless/workspace-context-resume-snapshot.patch.yml
+++ b/apps/cli/tests/profiles/headless/workspace-context-resume-snapshot.patch.yml
@@ -28,3 +28,7 @@
     # Publish the persisted agent before the driver selects the single root.
     - id: resumed-agent
       name: './tests/fixtures/workspace-context-resume-agent.ts'
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/apps/cli/tests/resolved-profile-boot.spec.ts b/apps/cli/tests/resolved-profile-boot.spec.ts
index c3daa0be7c..6a25712614 100644
--- a/apps/cli/tests/resolved-profile-boot.spec.ts
+++ b/apps/cli/tests/resolved-profile-boot.spec.ts
@@ -1,5 +1,5 @@
 /** Application-owned profiles share the named profile launch lifecycle. */
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
@@ -30,6 +30,9 @@ describe('runProfile with an application-owned profile', () => {
   it.each(['composition', 'boot', 'watch', 'cleanup', 'tree-cleanup', 'both-cleanups'] as const)('releases startup resources after a %s failure', async (stage) => {
     const home = mkdtempSync(join(tmpdir(), 'dsh-profile-startup-failure-'))
     homes.push(home)
+    mkdirSync(join(home, 'runtime'))
+    writeFileSync(join(home, 'runtime/package.json'), '{"name":"test-runtime","version":"1.0.0"}')
+    writeFileSync(join(home, 'package.json'), '{"name":"test-bundle","version":"1.0.0"}')
     vi.stubEnv('DSH_HOME', home)
     vi.spyOn(process, 'on').mockReturnValue(process)
     const ctx = new Context()
@@ -76,9 +79,12 @@ describe('runProfile with an application-owned profile', () => {
     }
   })
 
-  it.each(['live', 'startup'] as const)('uses shared layers, %s reload, environment, and shutdown', async (patchReload) => {
+  it.each([['live', 'link'], ['startup', 'link'], ['startup', 'runtime']] as const)('uses shared layers, %s reload, %s resolution, and shutdown', async (patchReload, resolutionMode) => {
     const home = mkdtempSync(join(tmpdir(), 'dsh-resolved-profile-'))
     homes.push(home)
+    mkdirSync(join(home, 'runtime'))
+    writeFileSync(join(home, 'runtime/package.json'), '{"name":"test-runtime","version":"1.0.0"}')
+    writeFileSync(join(home, 'package.json'), '{"name":"test-bundle","version":"1.0.0"}')
     vi.stubEnv('DSH_HOME', home)
     vi.stubEnv('DSH_TELEMETRY_DISABLED', '1')
     vi.spyOn(process, 'on').mockReturnValue(process)
@@ -116,13 +122,15 @@ describe('runProfile with an application-owned profile', () => {
     const runtime = { profile, installAnchor: join(home, 'runtime/package.json') }
     try {
       const { shutdown } = await runProfile({
-        environment, profile: 'desktop', resolvedProfile: runtime,
+        environment, profile: 'desktop', resolvedProfile: runtime, resolutionMode,
         patchFiles: [overlay], args: ['--port', '0', '--no-open'],
       })
       expect(installProxyFromEnvironment).toHaveBeenCalledWith(environment, expect.any(Function))
-      expect(healIsolatedProfileModuleFallback).toHaveBeenCalledWith({
-        profile, installAnchor: runtime.installAnchor,
-      })
+      if (resolutionMode === 'link') {
+        expect(healIsolatedProfileModuleFallback).toHaveBeenCalledWith({ profile, installAnchor: runtime.installAnchor })
+      } else {
+        expect(healIsolatedProfileModuleFallback).not.toHaveBeenCalled()
+      }
       expect(readFileSync(join(home, 'cordis.yml'), 'utf8')).not.toContain('stale')
       expect(ctx.cmdlineArgs!.get()).toEqual(['--port', '0', '--no-open'])
       const ready = vi.fn()
diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts
index eca02d1a6d..e60c94f216 100644
--- a/apps/cli/tests/web-agent-presets.e2e.ts
+++ b/apps/cli/tests/web-agent-presets.e2e.ts
@@ -4,7 +4,14 @@ import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
-import { boot, healProfilesModuleFallback, loadOverlayPatches, loadProfile } from '@deepseek-ai/dsh-app-boot'
+import {
+  boot,
+  createProfileResolutionGeneration,
+  loadOverlayPatches,
+  loadProfile,
+  PluginPackages,
+  type Profile,
+} from '@deepseek-ai/dsh-app-boot'
 import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
 import { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -112,12 +119,7 @@ async function bootWeb(
     { id: 'agent-presets', config: { default: 'standard', includeUserRoot: false } },
     ...extra,
   ]
-  // The surface is patch layers over an empty preset root, so the root sits
-  // outside this workspace and bare plugin names cannot resolve by Node's
-  // upward walk. The flat fallback the preset boot maintains is what makes
-  // them resolvable — the same mechanism, not a test-only shim.
   const home = dirname(settingsFile)
-  await healProfilesModuleFallback({ installAnchor: INSTALL_ANCHOR, home })
   const profileDir = join(home, 'profiles', 'spec')
   await mkdir(profileDir, { recursive: true })
   // Product Bundles are installed into the Profile, not the dsh app. Model
@@ -130,6 +132,14 @@ async function bootWeb(
     await mkdir(dirname(link), { recursive: true })
     await symlink(packageDir, link, 'junction')
   }
+  let profile: Profile = {
+    name: 'spec',
+    dir: profileDir,
+    layers: [],
+    patchPath: join(profileDir, 'cordis.patch.yml'),
+    patches: [],
+    patchReload: 'startup',
+  }
   let bundlePatches: PatchOptions[] = [
     ...loadOverlayPatches('dsh-test', BASE_PATCH),
     ...loadOverlayPatches('dsh-test', WEB_PATCH),
@@ -140,12 +150,14 @@ async function bootWeb(
       dependencies: Object.fromEntries(profileBundles.map(name => [name, 'workspace:*'])),
       dsh: { profile: { bundles: profileBundles } },
     }, null, 2) + '\n')
-    const profile = loadProfile('dsh-test', 'spec', INSTALL_ANCHOR, home, { userLayer: false })
+    profile = loadProfile('dsh-test', 'spec', INSTALL_ANCHOR, home, { userLayer: false })
     bundlePatches = profile.layers.flatMap(layer => layer.patches)
   }
+  const resolution = await createProfileResolutionGeneration({ installAnchor: INSTALL_ANCHOR, home, profile })
   const rootConfig = join(profileDir, 'cordis.yml')
   await writeFile(rootConfig, '[]\n')
-  return await boot('dsh-test', rootConfig, [...bundlePatches, ...overrides], (bootCtx) => {
+  return await boot('dsh-test', rootConfig, [...bundlePatches, ...overrides], async (bootCtx) => {
+    await bootCtx.plugin(PluginPackages, { generation: resolution })
     bootCtx.provide('connection', {
       fetch: { register: () => () => {} },
       rpc: { intercept: () => () => {} },
diff --git a/apps/desktop-host/package.json b/apps/desktop-host/package.json
index 35738ed3c7..4b38d0ef45 100644
--- a/apps/desktop-host/package.json
+++ b/apps/desktop-host/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-desktop-host",
-  "description": "Private upstream-Node host process for the Electron desktop application",
+  "description": "Private Node-mode host process for the Electron desktop application",
   "version": "0.1.5-rc.2",
   "private": true,
   "license": "MIT",
diff --git a/apps/desktop-host/src/index.ts b/apps/desktop-host/src/index.ts
index 22cc3d14e9..e36b2e1bcd 100644
--- a/apps/desktop-host/src/index.ts
+++ b/apps/desktop-host/src/index.ts
@@ -16,6 +16,7 @@ async function main(): Promise<void> {
   const application = runProfile({
     environment: loadLayeredEnv('dsh'),
     profile: 'desktop',
+    resolutionMode: process.argv[5] === 'runtime' ? 'runtime' : 'link',
     resolvedProfile: { profile, installAnchor },
     patchFiles: [],
     args: ['--no-open', '--port', '19387'],
diff --git a/apps/desktop/README.i18n.yaml b/apps/desktop/README.i18n.yaml
index f04b189abe..73027bfcbd 100644
--- a/apps/desktop/README.i18n.yaml
+++ b/apps/desktop/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/desktop/README.md
-README.md: a03acd3f4bfc717c6c4daa212d990e635bf15180
-README.zh.md: e0262df89cf36ee60ad801f2b6739d4dc5c97111
+README.md: 7a33d86aaded04a6e79a070a16e2179c9aa09379
+README.zh.md: 0e03bdc501102d34de66fab722fc0a4e84f24f1f
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
index a03acd3f4b..7a33d86aad 100644
--- a/apps/desktop/README.md
+++ b/apps/desktop/README.md
@@ -26,7 +26,7 @@ Node prepares the bundled interpreters and Python libraries without a system Pyt
 |---|---|---|
 | Release identity | The shell API, Web client, backend, and plugin graph are qualified as one combination; independent versions would create untested combinations and ambiguous update availability. | Electron and `@deepseek-ai/dsh` always have the same exact version. A dsh upgrade is a Desktop release, even when the shell code is unchanged. |
 | Runtime | The application must run without a system Node.js or pnpm installation. | dsh runs under Electron with `ELECTRON_RUN_AS_NODE=1` and `--expose-internals` and every package operation uses the bundled pnpm. Package-manager configuration and the Host environment follow the user's settings. Package scripts use a `node` shell launcher that forwards to Electron. |
-| Package sources | Core installation at startup adds work even when offline. | `extraResources/dsh` carries a complete production dependency tree; the profile installs only external plugins. |
+| Package sources | Core installation at startup adds work even when offline. | `app.asar/dsh` carries a complete production dependency tree; the profile installs only external plugins. |
 | Shared modules | Host APIs can depend on module identity. | The shared profile runner projects missing installation and bundle dependencies inside the Desktop profile; pnpm-managed packages take precedence. |
 | State ownership | Sharing executable dependency graphs would let CLI and Desktop change each other's dsh, Cordis, plugin, or native-module versions, while two desktop processes could race on the same profile. | Electron acquires its process-lifetime single-instance lock before any profile access and exclusively owns `$DSH_HOME/profiles/desktop` plus its package-manager state. CLI and Desktop share supported product data under `$DSH_HOME`, but never executable packages, plugin activation, lockfiles, or `node_modules`. |
 | Transport | Reusing Web serving and authentication keeps application behavior in one implementation. | Electron loads the Host’s authenticated HTTP URL directly; child IPC carries lifecycle messages, and the local shell protocol serves startup and management pages. |
@@ -37,7 +37,7 @@ The [thin-wrapper decision](../../.agents/notes/implemented/architecture/2026-09
 
 ## Installation ownership
 
-Electron owns `$DSH_HOME/profiles/desktop`. Its `dependencies` contains packages installed by pnpm; `dsh.profile.bundles` contains the built-in bundles followed by enabled plugins. The signed application supplies dsh, the private Desktop Host, and their production packages from `resources/dsh`. Shared package links resolve to those actual directories. Both host and plugins execute in the same Electron Node-mode process, with normal realpath resolution; Desktop does not enable `--preserve-symlinks`. The CLI cannot boot or mutate this profile.
+Electron owns `$DSH_HOME/profiles/desktop`. Its `dependencies` contains packages installed by pnpm; `dsh.profile.bundles` contains the built-in bundles followed by enabled plugins. The signed application supplies dsh, the private Desktop Host, and their production packages from `resources/app.asar/dsh`. Packaged applications select runtime profile resolution without creating package links; development profiles use filesystem links. Both host and plugins execute in the same Electron Node-mode process; Desktop does not enable `--preserve-symlinks`. The CLI cannot boot or mutate this profile.
 
 The local startup page exposes startup status and available recovery actions. The product renderer uses the Web application’s HTTP APIs. The separate plugin window receives structured list, install, remove, update, and update-check operations; neither renderer receives filesystem access, raw Electron IPC, a shell, or arbitrary pnpm arguments.
 
@@ -49,7 +49,7 @@ Electron's native Edit menu supplies undo, redo, cut, copy, paste, and select-al
 
 ### Runtime and plugin activation
 
-The signed `resources/dsh/desktop-runtime.json` binds the shell version, Electron's Node version, platform, architecture, shared package versions, and final file inventory. Startup reads the metadata and checks shared package records. Release schema, shell version, target compatibility, and file integrity are verified during packaging. Core packages are never copied into profile storage or installed by pnpm at first launch.
+The signed `resources/app.asar/dsh/desktop-runtime.json` binds the shell version, Electron's Node version, platform, architecture, shared package versions, and final file inventory. Startup reads the metadata and checks shared package records. Release schema, shell version, target compatibility, and file integrity are verified during packaging. Core packages are never copied into profile storage or installed by pnpm at first launch.
 
 1. The main window displays a local loading page before profile preparation or backend startup. Shared profile initialization creates missing manifest, empty user patch, and pnpm workspace files without overwriting existing files. The actual Host starts once and supplies missing module links through the shared profile runner.
 2. On application upgrades, the shared profile runner refreshes its owned module links without checking plugin peer requirements. Plugin files, configuration, versions, and lockfile remain in place; pnpm does not run.
@@ -115,7 +115,7 @@ Each target owns its packed package inputs, prepared runtime, package set, dsh t
 
 ### Runtime file selection
 
-Production packages first pass through npm's publication rules and dependency installation. [Desktop's file policy](scripts/runtime-file-policy.ts) then filters the immutable `resources/dsh/node_modules` copy before signing and integrity sealing. It omits TypeScript declarations, recognized JavaScript/CSS/TypeScript source maps, TypeScript build caches, Domino's test directory, selected native compiler outputs, and node-pty prebuilds for other platforms. It preserves runtime JavaScript, native modules and their DLL/EXE helpers, WASM, unknown assets, licenses, and notices. The policy does not alter npm tarballs, the bundled package manager, or user-installed plugin files.
+Production packages first pass through npm's publication rules and dependency installation. [Desktop's file policy](scripts/runtime-file-policy.ts) then filters the immutable `resources/app.asar/dsh/node_modules` copy before signing and integrity sealing. It omits TypeScript declarations, recognized JavaScript/CSS/TypeScript source maps, TypeScript build caches, Domino's test directory, selected native compiler outputs, and node-pty prebuilds for other platforms. It preserves runtime JavaScript, native modules and their DLL/EXE helpers, WASM, unknown assets, licenses, and notices. The policy does not alter npm tarballs, the bundled package manager, or user-installed plugin files.
 
 The packaged application runs compiled JavaScript and pre-generated Typert metadata; it does not compile TypeScript plugins. Source-level debugger navigation and editor declarations remain available in development packages. [Copy-policy tests](tests/runtime-file-policy.spec.ts) cover exclusions and retained assets; `prepare:dsh` runs the [payload smoke](tests/fixtures/runtime-payload-smoke.mjs) under Electron RunAsNode before the Host smoke and final inventory verification.
 
@@ -206,7 +206,7 @@ pnpm run prepare:desktop
 
 This diagnostic command is an alternative stopping point, not the first half of a two-command build. A later `package:desktop*` command repeats the official build and preparation so it cannot consume stale dsh packages, runtime files, or dsh content.
 
-Every package command builds the repository, packs the first-party production closures rooted at dsh and the private Desktop Host, and prepares the target Electron distribution and pnpm CLI. `prepare:dsh` installs the production graph once at build time, copies materialized packages into `extraResources/dsh`, removes package-manager metadata, and writes `desktop-runtime.json` with shared package versions and final file hashes. On macOS it signs and verifies native files before inventory generation; electron-builder excludes this already-signed tree from nested re-signing. Resource mappings explicitly include `dsh/node_modules`, which the default root-directory filter omits; the copied inventory is checked before signing and again after signing. Signed installer, notarization, installed upgrade, and target-specific native-module qualification require the release environment.
+Every package command builds the repository, packs the first-party production closures rooted at dsh and the private Desktop Host, and prepares the target Electron distribution and pnpm CLI. `prepare:dsh` installs the production graph once at build time, prepares materialized packages for electron-builder to archive under `app.asar/dsh`, removes package-manager metadata, and writes `desktop-runtime.json` with shared package versions and final file hashes. On macOS it signs and verifies native files before inventory generation; electron-builder excludes this already-signed tree from nested re-signing. Resource mappings explicitly include `dsh/node_modules`, which the default root-directory filter omits; the prepared runtime inventory is checked after native signing. Native executables and libraries are unpacked beside ASAR; Python, standalone Node and pnpm remain in external runtime resources. Signed installer, notarization, installed upgrade, and target-specific native-module qualification require the release environment.
 
 An unpacked artifact contains Electron, the materialized dsh production tree, pnpm, and the shell application. Installer size and filesystem size differ; release qualification measures both, plus the profile’s plugin storage and first-launch latency. The runtime trades more application files for eliminating core package installation on the user’s machine.
 
diff --git a/apps/desktop/README.zh.md b/apps/desktop/README.zh.md
index e0262df89c..0e03bdc501 100644
--- a/apps/desktop/README.zh.md
+++ b/apps/desktop/README.zh.md
@@ -26,7 +26,7 @@ Node 准备内置解释器和 Python 库，无需系统 Python 或 pip。[下载
 |---|---|---|
 | 发布身份 | 桌面壳 API、Web 客户端、后端与插件依赖图作为一个组合完成验证；独立版本会产生未经验证的组合，并让更新可用性含糊不清。 | Electron 与 `@deepseek-ai/dsh` 始终使用同一精确版本。即使桌面壳代码不变，升级 dsh 也必须发布新 Desktop 版本。 |
 | 运行时 | 应用必须能够在没有系统 Node.js 或 pnpm 的机器上运行。 | dsh 通过设置 `ELECTRON_RUN_AS_NODE=1` 和 `--expose-internals` 的 Electron 运行，所有包操作都使用内置 pnpm。包管理器配置和 Host 环境遵循用户设置。包脚本通过 `node` shell 启动器转发给 Electron。 |
-| 包来源 | 即使离线，启动时安装核心依赖也会增加开销。 | `extraResources/dsh` 携带完整生产依赖树；profile 只安装外部插件。 |
+| 包来源 | 即使离线，启动时安装核心依赖也会增加开销。 | `app.asar/dsh` 携带完整生产依赖树；profile 只安装外部插件。 |
 | 共享模块 | Host API 可能依赖模块身份。 | 共享 profile runner 在 Desktop profile 内补全安装包与 bundle 缺失的依赖；pnpm 管理的包优先。 |
 | 状态归属 | 共享可执行依赖图会让 CLI（命令行界面）与 Desktop 相互改变 dsh、Cordis、插件或原生模块版本，而两个桌面进程还可能争用同一个 profile。 | Electron 在访问任何 profile 前获取进程生命周期单实例锁，并独占 `$DSH_HOME/profiles/desktop` 及其包管理器状态。CLI 与 Desktop 共享 `$DSH_HOME` 下受支持的产品数据，但绝不共享可执行包、插件激活、锁文件或 `node_modules`。 |
 | 传输 | 复用 Web 服务与认证，让应用行为由同一份实现负责。 | Electron 直接加载 Host 的认证 HTTP URL；子进程 IPC 承载生命周期消息，本地壳协议提供启动和管理页面。 |
@@ -37,7 +37,7 @@ Node 准备内置解释器和 Python 库，无需系统 Python 或 pip。[下载
 
 ## 安装归属
 
-Electron 拥有 `$DSH_HOME/profiles/desktop`。其 `dependencies` 包含 pnpm 安装的包；`dsh.profile.bundles` 包含内置 bundle，后接已启用插件。签名应用从 `resources/dsh` 提供 dsh、私有 Desktop Host 及其生产依赖。共享包链接解析到这些实际目录。宿主与插件在同一个 Electron Node 模式进程中执行，使用正常的 realpath 解析；Desktop 不启用 `--preserve-symlinks`。CLI 不能启动或修改此 profile。
+Electron 拥有 `$DSH_HOME/profiles/desktop`。其 `dependencies` 包含 pnpm 安装的包；`dsh.profile.bundles` 包含内置 bundle，后接已启用插件。签名应用从 `resources/app.asar/dsh` 提供 dsh、私有 Desktop Host 及其生产依赖。打包应用选择 runtime profile 解析，不创建包链接；开发 profile 使用文件系统链接。宿主与插件在同一个 Electron Node 模式进程中执行；Desktop 不启用 `--preserve-symlinks`。CLI 不能启动或修改此 profile。
 
 本地启动页面展示启动状态及可用恢复操作。产品渲染进程使用 Web 应用的 HTTP API。独立插件窗口接收结构化的列表、安装、移除、更新和检查更新操作；两个渲染进程都不会获得文件系统、原始 Electron IPC、shell 或任意 pnpm 参数访问权。
 
@@ -49,7 +49,7 @@ Electron 原生“编辑”菜单为当前聚焦窗口提供撤销、重做、
 
 ### 运行时与插件激活
 
-签名资源中的 `resources/dsh/desktop-runtime.json` 绑定 shell 版本、Electron 的 Node 版本、平台、架构、共享包版本和最终文件清单。启动读取元数据，并检查共享包记录。发布 schema、shell 版本、目标兼容性和文件完整性在打包时验证。首次启动不会把核心包复制到 profile 存储或通过 pnpm 安装核心包。
+签名资源中的 `resources/app.asar/dsh/desktop-runtime.json` 绑定 shell 版本、Electron 的 Node 版本、平台、架构、共享包版本和最终文件清单。启动读取元数据，并检查共享包记录。发布 schema、shell 版本、目标兼容性和文件完整性在打包时验证。首次启动不会把核心包复制到 profile 存储或通过 pnpm 安装核心包。
 
 1. 主窗口在 profile 准备或后端启动前显示本地加载页。共享 profile 初始化创建缺失的 manifest、空用户 patch 与 pnpm workspace 文件，不覆盖现有文件。实际 Host 仅启动一次，并通过共享 profile runner 补全缺失的模块链接。
 2. 应用升级时，共享 profile runner 刷新其拥有的模块链接，不检查插件 peer 要求。插件文件、配置、版本与锁文件保留原位；不运行 pnpm。
@@ -115,7 +115,7 @@ macOS arm64 命令要求 Apple Silicon。macOS x64 命令可以在 Intel macOS 
 
 ### 运行时文件筛选
 
-生产包首先经过 npm 发布规则和依赖安装。[桌面文件规则](scripts/runtime-file-policy.ts)随后在签名和完整性封存之前过滤不可变的 `resources/dsh/node_modules` 副本。它排除 TypeScript 声明、明确属于 JavaScript/CSS/TypeScript 的 source map、TypeScript 构建缓存、Domino 测试目录、指定的原生编译产物，以及其他平台的 node-pty 预构建文件。它保留运行时 JavaScript、原生模块及其 DLL/EXE 辅助程序、WASM、未知资源、许可证和声明。规则不会修改 npm tarball、内置包管理器或用户安装的插件文件。
+生产包首先经过 npm 发布规则和依赖安装。[桌面文件规则](scripts/runtime-file-policy.ts)随后在签名和完整性封存之前过滤不可变的 `resources/app.asar/dsh/node_modules` 副本。它排除 TypeScript 声明、明确属于 JavaScript/CSS/TypeScript 的 source map、TypeScript 构建缓存、Domino 测试目录、指定的原生编译产物，以及其他平台的 node-pty 预构建文件。它保留运行时 JavaScript、原生模块及其 DLL/EXE 辅助程序、WASM、未知资源、许可证和声明。规则不会修改 npm tarball、内置包管理器或用户安装的插件文件。
 
 打包应用运行编译后的 JavaScript 和预生成的 Typert 元数据，不编译 TypeScript 插件。源码级调试导航和编辑器声明仍可从开发包中获取。[复制规则测试](tests/runtime-file-policy.spec.ts)覆盖排除项和保留资源；`prepare:dsh` 在 Host smoke 和最终清单验证之前，使用 Electron RunAsNode 执行[产物 smoke](tests/fixtures/runtime-payload-smoke.mjs)。
 
@@ -206,7 +206,7 @@ pnpm run prepare:desktop
 
 这条诊断命令是另一种停止位置，并非两条命令构建流程的前半段。之后执行 `package:desktop*` 时仍会重新完成正式构建与准备，避免使用陈旧的 dsh 包、运行时文件或 dsh 内容。
 
-每条打包命令都会构建仓库，打包以 dsh 和私有 Desktop Host 为根的第一方生产依赖闭包，并准备目标专用的 Electron 分发包与 pnpm CLI。`prepare:dsh` 在构建时安装一次生产依赖图，把物化包复制到 `extraResources/dsh`，移除包管理器元数据，并生成包含共享包版本和最终文件哈希的 `desktop-runtime.json`。在 macOS 上，它先签名并验证原生文件，再生成清单；electron-builder 不对已签名的此目录重复进行嵌套签名。资源映射明确包含默认根目录过滤器会忽略的 `dsh/node_modules`；复制后的清单在签名前及签名后分别验证。签名安装包、公证、已安装应用升级和各目标原生模块的验收需要发布环境。
+每条打包命令都会构建仓库，打包以 dsh 和私有 Desktop Host 为根的第一方生产依赖闭包，并准备目标专用的 Electron 分发包与 pnpm CLI。`prepare:dsh` 在构建时安装一次生产依赖图，准备物化包供 electron-builder 归档到 `app.asar/dsh`，移除包管理器元数据，并生成包含共享包版本和最终文件哈希的 `desktop-runtime.json`。在 macOS 上，它先签名并验证原生文件，再生成清单；electron-builder 不对已签名的此目录重复进行嵌套签名。资源映射明确包含默认根目录过滤器会忽略的 `dsh/node_modules`；准备完成的运行时清单在原生签名后检查。原生可执行文件及库解包到 ASAR 旁；Python、独立 Node 和 pnpm 保留在外部 runtime 资源中。签名安装包、公证、已安装应用升级和各目标原生模块的验收需要发布环境。
 
 未压缩产物包含 Electron、物化后的 dsh 生产依赖树、pnpm，以及壳应用。安装包大小与文件系统占用不同；发布验收需要测量两者，以及 profile 插件存储和首次启动耗时。此布局用更多应用内文件换取消除用户机器上的核心包安装过程。
 
diff --git a/apps/desktop/electron-builder.config.d.mts b/apps/desktop/electron-builder.config.d.mts
index 5fea558f96..3aefaec12f 100644
--- a/apps/desktop/electron-builder.config.d.mts
+++ b/apps/desktop/electron-builder.config.d.mts
@@ -4,11 +4,16 @@ export interface DesktopElectronBuilderConfig {
   readonly directories: {
     readonly output: string
   }
-  readonly extraResources: readonly [
-    { readonly from: string, readonly to: 'runtime' },
-    { readonly from: string, readonly to: 'dsh' },
-    { readonly from: string, readonly to: 'dsh/node_modules' },
+  readonly files: readonly [
+    string,
+    string,
+    string,
+    string,
+    { readonly from: string, readonly to: 'dsh', readonly filter: readonly ['**/*'] },
+    { readonly from: string, readonly to: 'dsh/node_modules', readonly filter: readonly ['**/*'] },
   ]
+  readonly asarUnpack: readonly string[]
+  readonly extraResources: readonly [{ readonly from: string, readonly to: 'runtime' }]
   readonly mac: {
     readonly identity: string | undefined
     readonly forceCodeSigning: boolean
diff --git a/apps/desktop/electron-builder.config.mjs b/apps/desktop/electron-builder.config.mjs
index 2575ce5d51..ca846818b6 100644
--- a/apps/desktop/electron-builder.config.mjs
+++ b/apps/desktop/electron-builder.config.mjs
@@ -83,12 +83,18 @@ export function createElectronBuilderConfig(
       'lib/*.cjs',
       'renderer/**/*',
       'package.json',
+      { from: buildPaths.dsh, to: 'dsh', filter: ['**/*'] },
+      // electron-builder excludes a source directory's root node_modules.
+      { from: join(buildPaths.dsh, 'node_modules'), to: 'dsh/node_modules', filter: ['**/*'] },
+    ],
+    asarUnpack: [
+      '**/*.{node,dylib,dll,so,exe}',
+      '**/*.so.*',
+      '**/spawn-helper',
+      '**/@vscode/ripgrep/bin/rg',
     ],
     extraResources: [
       { from: buildPaths.runtime, to: 'runtime' },
-      { from: buildPaths.dsh, to: 'dsh' },
-      // electron-builder excludes a source directory's root node_modules.
-      { from: join(buildPaths.dsh, 'node_modules'), to: 'dsh/node_modules' },
     ],
     mac: {
       icon: fileURLToPath(new URL('./resources/icon-macos.png', import.meta.url)),
@@ -96,8 +102,8 @@ export function createElectronBuilderConfig(
       identity: macOSSigning?.signingIdentity,
       forceCodeSigning: true,
       hardenedRuntime: true,
-      // Native runtime files are pre-signed; PAK resources are sealed by their enclosing bundle.
-      signIgnore: ['/Contents/Resources/dsh(?:/|$)', '/Contents/Resources/runtime/primary-runtime(?:/|$)', '\\.pak$'],
+      // ASAR-unpacked native runtime files are pre-signed; PAK resources are sealed by their enclosing bundle.
+      signIgnore: ['/Contents/Resources/app\\.asar\\.unpacked/dsh(?:/|$)', '/Contents/Resources/runtime/primary-runtime(?:/|$)', '\\.pak$'],
       notarize: true,
       target: ['dmg', 'zip'],
     },
@@ -105,24 +111,8 @@ export function createElectronBuilderConfig(
       sign: true,
       writeUpdateInfo: false,
     },
-    afterPack: async context => {
-      const { verifyDesktopRuntime, writeDesktopRuntime } = await import('./lib/types/runtime-tree.js')
-      const runtimeRoot = join(context.packager.getResourcesDir(context.appOutDir), 'dsh')
-      if (resolvedPlatform === 'win32' && !unsigned) {
-        // Windows signs copied executable resources before afterPack runs.
-        const prepared = await verifyDesktopRuntime(buildPaths.dsh,
-          context.packager.appInfo.version, { platform: resolvedPlatform, arch: resolvedArch })
-        writeDesktopRuntime(runtimeRoot, prepared.release, prepared.sharedPackages.map(entry => entry.name),
-          { platform: resolvedPlatform, arch: resolvedArch })
-      }
-      await verifyDesktopRuntime(runtimeRoot,
-        context.packager.appInfo.version, { platform: resolvedPlatform, arch: resolvedArch })
-    },
     afterSign: async context => {
       if (context.electronPlatformName !== 'darwin') return
-      const { verifyDesktopRuntime } = await import('./lib/types/runtime-tree.js')
-      await verifyDesktopRuntime(join(context.appOutDir, `${context.packager.appInfo.productFilename}.app`, 'Contents', 'Resources', 'dsh'),
-        context.packager.appInfo.version, { platform: 'darwin', arch: resolvedArch })
       verifyMacOSSignatureAfterSign(context, macOSSigning ?? resolveMacOSSigningEnvironment(env))
     },
     artifactBuildCompleted: artifact => {
diff --git a/apps/desktop/src/host-process.ts b/apps/desktop/src/host-process.ts
index 88319cebfc..25445e3f54 100644
--- a/apps/desktop/src/host-process.ts
+++ b/apps/desktop/src/host-process.ts
@@ -70,7 +70,8 @@ export class DesktopHostProcess {
    * @param inspectPort - Optional loopback inspector port for workspace development.
    * @param environment - Environment inherited by the Host and its plugin subprocesses.
    * @param onFailure - Receives the first unexpected child failure, including after readiness.
-   * @param primaryRuntime - Optional development payload location for bundled script dependencies.
+   * @param primaryRuntime - Optional payload location for bundled script dependencies.
+   * @param profileResolution - Package resolution mode for the application-owned profile.
    */
   constructor(
     private readonly node: string,
@@ -80,6 +81,7 @@ export class DesktopHostProcess {
     private readonly environment: NodeJS.ProcessEnv = process.env,
     private readonly onFailure?: (error: Error) => void,
     private readonly primaryRuntime?: string,
+    private readonly profileResolution: 'link' | 'runtime' = 'link',
   ) {}
 
   /**
@@ -95,7 +97,8 @@ export class DesktopHostProcess {
       entry,
       this.runtimeDir,
       this.projectDir,
-      ...(this.primaryRuntime === undefined ? [] : [this.primaryRuntime]),
+      this.primaryRuntime ?? join(this.runtimeDir, '..', 'runtime', 'primary-runtime'),
+      this.profileResolution,
     ], {
       cwd: this.projectDir,
       env: desktopNodeEnvironment(this.node, undefined, this.environment),
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index ad842460dd..148e334a52 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -79,7 +79,7 @@ function runtimeResources(): RuntimeResources {
     ?? (development ? join(app.getAppPath(), 'node_modules', 'pnpm', 'bin', 'pnpm.mjs')
       : join(process.resourcesPath, 'runtime', 'pnpm', 'bin', 'pnpm.mjs'))
   const dsh = (development ? process.env.DSH_DESKTOP_DSH_DIR : undefined)
-    ?? (development ? join(app.getAppPath(), '.desktop-build', 'development', 'project') : join(process.resourcesPath, 'dsh'))
+    ?? (development ? join(app.getAppPath(), '.desktop-build', 'development', 'project') : join(app.getAppPath(), 'dsh'))
   return { node, nodeBin, pnpm, dsh }
 }
 
@@ -238,7 +238,9 @@ async function main(): Promise<void> {
     const hostInspectPort = developmentHostInspectPort(development)
     const host = new DesktopHostProcess(resources.node, resources.dsh, activeProject,
       hostInspectPort, desktopNodeEnvironment(resources.node, resources.nodeBin, process.env), onFailure,
-      development ? join(app.getAppPath(), '.desktop-build', 'targets', `${process.platform === 'darwin' ? 'mac' : 'win'}-${process.arch}`, 'runtime', 'primary-runtime') : undefined)
+      development ? join(app.getAppPath(), '.desktop-build', 'targets', `${process.platform === 'darwin' ? 'mac' : 'win'}-${process.arch}`, 'runtime', 'primary-runtime')
+        : join(process.resourcesPath, 'runtime', 'primary-runtime'),
+      development ? 'link' : 'runtime')
     return {
       start: async () => {
         const ready = await host.start()
diff --git a/apps/desktop/tests/host-process.spec.ts b/apps/desktop/tests/host-process.spec.ts
index 7c62d8c688..84567c4810 100644
--- a/apps/desktop/tests/host-process.spec.ts
+++ b/apps/desktop/tests/host-process.spec.ts
@@ -77,6 +77,17 @@ describe('desktop host process', () => {
     expect(failure).not.toHaveBeenCalled()
   })
 
+  it('passes external dependencies and runtime profile resolution to the Host', async () => {
+    const runtime = projectWithHost(HTTP_HOST.replace('runtime: process.argv[2]',
+      'primaryRuntime: process.argv[4], profileResolution: process.argv[5], runtime: process.argv[2]'))
+    const primaryRuntime = join(runtime, 'external-primary-runtime')
+    const host = new DesktopHostProcess(process.execPath, runtime, runtime, undefined, process.env,
+      undefined, primaryRuntime, 'runtime')
+    hosts.push(host)
+    const { url } = await host.start()
+    expect(await (await fetch(url)).json()).toMatchObject({ primaryRuntime, profileResolution: 'runtime' })
+  })
+
   it('reports a fatal event after readiness once', async () => {
     const runtime = projectWithHost()
     const failure = vi.fn()
diff --git a/apps/desktop/tests/macos-signature.spec.ts b/apps/desktop/tests/macos-signature.spec.ts
index 97d2b4c54d..3286f23e89 100644
--- a/apps/desktop/tests/macos-signature.spec.ts
+++ b/apps/desktop/tests/macos-signature.spec.ts
@@ -1,10 +1,3 @@
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join, relative } from 'node:path'
-import { createRequire } from 'node:module'
-import { FileMatcher } from 'app-builder-lib/out/fileMatcher.js'
-import { runtimeFixture } from './runtime-fixture.ts'
-import { verifyDesktopRuntime } from '../src/runtime-tree.ts'
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
 import type { NotarizeOptions } from '@electron/notarize'
 import {
@@ -18,11 +11,6 @@ import {
   assertMacOSSignatureDetails,
 } from '../scripts/verify-macos-signature.mjs'
 
-// app-builder-lib omits this internal copier from its declarations; the regression exercises its actual file filter.
-const { copyFiles } = createRequire(import.meta.url)('app-builder-lib/out/fileMatcher.js') as {
-  copyFiles: (matchers: FileMatcher[]) => Promise<void>
-}
-
 const RELEASE_ENVIRONMENT = {
   DSH_DESKTOP_APP_ID: 'com.example.desktop',
   DSH_DESKTOP_TARGET_PLATFORM: 'darwin',
@@ -52,18 +40,28 @@ describe('desktop macOS release signature', () => {
     const { createElectronBuilderConfig } = await import('../electron-builder.config.mjs')
     const config = createElectronBuilderConfig(RELEASE_ENVIRONMENT, 'darwin', 'arm64')
     expect(portablePath(config.directories.output)).toContain('/.desktop-build/targets/mac-arm64/artifacts')
-    expect(config.extraResources).toHaveLength(3)
+    expect(config.extraResources).toHaveLength(1)
     expect(config.extraResources[0]?.to).toBe('runtime')
-    expect(config.extraResources[1]?.to).toBe('dsh')
     expect(portablePath(config.extraResources[0]?.from ?? '')).toContain('/.desktop-build/targets/mac-arm64/runtime')
-    expect(portablePath(config.extraResources[1]?.from ?? '')).toContain('/.desktop-build/targets/mac-arm64/dsh')
+    const [dshFiles, dshNodeModules] = config.files.slice(-2)
+    if (!dshFiles || !dshNodeModules || typeof dshFiles === 'string' || typeof dshNodeModules === 'string') {
+      throw new Error('desktop DSH resources must use electron-builder file mappings')
+    }
+    expect(portablePath(dshFiles.from)).toContain('/.desktop-build/targets/mac-arm64/dsh')
+    expect(dshFiles.to).toBe('dsh')
+    expect(portablePath(dshNodeModules.from)).toContain('/.desktop-build/targets/mac-arm64/dsh/node_modules')
+    expect(dshNodeModules.to).toBe('dsh/node_modules')
+    expect(config.asarUnpack).toEqual(expect.arrayContaining([
+      '**/*.{node,dylib,dll,so,exe}',
+      '**/@vscode/ripgrep/bin/rg',
+    ]))
     expect(config).toMatchObject({
       appId: RELEASE_ENVIRONMENT.DSH_DESKTOP_APP_ID,
       mac: {
         identity: RELEASE_ENVIRONMENT.DSH_DESKTOP_MACOS_SIGNING_IDENTITY,
         forceCodeSigning: true,
         notarize: true,
-        signIgnore: ['/Contents/Resources/dsh(?:/|$)', '/Contents/Resources/runtime/primary-runtime(?:/|$)', '\\.pak$'],
+        signIgnore: ['/Contents/Resources/app\\.asar\\.unpacked/dsh(?:/|$)', '/Contents/Resources/runtime/primary-runtime(?:/|$)', '\\.pak$'],
       },
       dmg: {
         sign: true,
@@ -83,9 +81,8 @@ describe('desktop macOS release signature', () => {
     const ignored = (path: string): boolean => config.mac.signIgnore.some(pattern => new RegExp(pattern).test(path))
     expect(ignored('/App.app/Contents/Frameworks/Electron.framework/Versions/A/Resources/en.lproj/locale.pak')).toBe(true)
     expect(ignored('/App.app/Contents/Frameworks/Electron.framework/Versions/A/Resources/resources.pak')).toBe(true)
-    expect(ignored('/App.app/Contents/Resources/runtime/primary-runtime/dependencies/python/bin/python3')).toBe(true)
     for (const path of [
-      '/App.app/Contents/MacOS/DeepSeek Harness',
+      '/App.app/Contents/Resources/runtime/node/node',
       '/App.app/Contents/Resources/runtime/pnpm/addon.node',
       '/App.app/Contents/Frameworks/Electron.framework/Versions/A/library.dylib',
       '/App.app/Contents/Frameworks/Electron.framework',
@@ -93,26 +90,6 @@ describe('desktop macOS release signature', () => {
     ]) expect(ignored(path)).toBe(false)
   })
 
-  it('copies the complete runtime despite electron-builder excluding root node_modules', async () => {
-    const { createElectronBuilderConfig } = await import('../electron-builder.config.mjs')
-    const config = createElectronBuilderConfig(RELEASE_ENVIRONMENT, 'darwin', 'arm64')
-    const root = mkdtempSync(join(tmpdir(), 'desktop-resource-copy-'))
-    try {
-      const source = join(root, 'source')
-      const destination = join(root, 'resources')
-      runtimeFixture(source)
-      const sourceRoot = config.extraResources[1].from
-      const matchers = config.extraResources.slice(1).map(entry => new FileMatcher(
-        join(source, relative(sourceRoot, entry.from)), join(destination, entry.to), value => value,
-      ))
-      await copyFiles(matchers.slice(0, 1))
-      await expect(verifyDesktopRuntime(join(destination, 'dsh'), '1.0.0')).rejects.toThrow(/ENOENT/u)
-      rmSync(destination, { recursive: true })
-      await copyFiles(matchers)
-      await expect(verifyDesktopRuntime(join(destination, 'dsh'), '1.0.0')).resolves.toMatchObject({ release: { version: '1.0.0' } })
-    } finally { rmSync(root, { recursive: true, force: true }) }
-  })
-
   it('validates Windows signing without requiring macOS identifiers for a Windows target', async () => {
     const { createElectronBuilderConfig } = await import('../electron-builder.config.mjs')
     expect(() => createElectronBuilderConfig({
@@ -121,24 +98,6 @@ describe('desktop macOS release signature', () => {
     }, 'win32')).toThrow(/DSH_DESKTOP_WINDOWS_CER_FILE/u)
   })
 
-  it('copies primary interpreter files and nested pnpm modules through the runtime resource mapping', async () => {
-    const root = mkdtempSync(join(tmpdir(), 'desktop-primary-copy-'))
-    try {
-      const source = join(root, 'source')
-      const destination = join(root, 'runtime')
-      const files = ['primary-runtime/runtime.json', 'primary-runtime/dependencies/python/Lib/site-packages/numpy/native.pyd',
-        'primary-runtime/dependencies/pnpm/dist/node_modules/helper/index.js', 'primary-runtime/dependencies/node/node_modules/README.txt']
-      for (const file of files) {
-        mkdirSync(join(source, file, '..'), { recursive: true })
-        writeFileSync(join(source, file), 'payload')
-      }
-      mkdirSync(join(source, 'primary-runtime/dependencies/node/node_modules'), { recursive: true })
-      await copyFiles([new FileMatcher(source, destination, value => value)])
-      for (const file of files) expect(existsSync(join(destination, file))).toBe(true)
-      expect(existsSync(join(destination, 'primary-runtime/dependencies/node/node_modules'))).toBe(true)
-    } finally { rmSync(root, { recursive: true, force: true }) }
-  })
-
   it('isolates unsigned Windows artifacts and omits updater metadata without release credentials', async () => {
     const { createElectronBuilderConfig } = await import('../electron-builder.config.mjs')
     const config = createElectronBuilderConfig({
@@ -148,11 +107,6 @@ describe('desktop macOS release signature', () => {
     }, 'win32', 'x64')
     expect(portablePath(config.directories.output)).toContain('/targets/win-x64/unsigned-artifacts')
     expect(portablePath(config.nsis.include)).toMatch(/\/scripts\/installer\.nsh$/u)
-    expect(config.nsis).toMatchObject({
-      oneClick: false, perMachine: false, allowElevation: false,
-      allowToChangeInstallationDirectory: false, installerLanguages: ['en_US', 'zh_CN'],
-    })
-    expect(config.nsis).not.toHaveProperty('script')
     expect(config).toMatchObject({
       win: { forceCodeSigning: false, signtoolOptions: { sign: undefined } },
       publish: null,
diff --git a/apps/desktop/tests/main-startup.spec.ts b/apps/desktop/tests/main-startup.spec.ts
index 995f82d570..513e800aff 100644
--- a/apps/desktop/tests/main-startup.spec.ts
+++ b/apps/desktop/tests/main-startup.spec.ts
@@ -58,6 +58,7 @@ const harness = await vi.hoisted(async () => {
     constructor(
       readonly node: string, readonly runtime: string, readonly profile: string,
       readonly inspectPort?: number, readonly environment?: NodeJS.ProcessEnv, readonly onFailure?: (error: Error) => void,
+      readonly primaryRuntime?: string, readonly profileResolution?: string,
     ) { hosts.push(this) }
   }
   const app = Object.assign(new EventEmitter(), {
@@ -386,7 +387,9 @@ describe('desktop main startup', () => {
     expect(harness.applyRelease).toHaveBeenCalledTimes(1)
     expect(harness.hosts[0]).toMatchObject({
       node: process.execPath,
-      runtime: join('desktop-test-resources', 'dsh'),
+      runtime: join(harness.app.getAppPath(), 'dsh'),
+      primaryRuntime: join('desktop-test-resources', 'runtime', 'primary-runtime'),
+      profileResolution: 'runtime',
       profile: 'desktop-test-profile',
     })
     expect(harness.hosts[0]!.start).toHaveBeenCalledTimes(1)
diff --git a/apps/web/tests/diff-context.e2e.ts b/apps/web/tests/diff-context.e2e.ts
new file mode 100644
index 0000000000..cf893ac7ec
--- /dev/null
+++ b/apps/web/tests/diff-context.e2e.ts
@@ -0,0 +1,66 @@
+/** Cold Session rendering covers exact context and bounded whole-fragment replacements. */
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { chromium, type Browser, type Page } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import {
+  assertFixtureInventory, captureStableAria, compareOrRefreshGolden,
+  launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold,
+} from './scaffold.ts'
+import { expandTurnProcesses, newEnglishPage, saveFailureShot } from './support.ts'
+
+const ROOT = fileURLToPath(new URL('../../../snapshots', import.meta.url))
+const MODE = webSnapshotMode()
+
+const CASES = [
+  { name: 'diff-context', source: 'session/fs-edit/session.v3.jsonl', totals: '+1 -1', shared: 'level=info', inventory: ['ui.expected.md'] },
+  { name: 'diff-bounded', source: 'web/diff-bounded/session.v3.jsonl', totals: '+130 -130', shared: 'shared heading', inventory: ['session.v3.jsonl', 'ui.expected.md'] },
+]
+
+describe.skipIf(MODE === 'record').each(CASES)('web e2e: $name', (scenario) => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    await seedSession(scaffold, await readFile(`${ROOT}/${scenario.source}`, 'utf8'), scenario.name)
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' })
+  })
+
+  afterAll(async () => {
+    try {
+      await browser?.close()
+    } finally {
+      await scaffold?.close()
+    }
+  })
+
+  it('keeps collapsed and expanded counts consistent with the displayed diff', async () => {
+    onTestFailed(() => saveFailureShot(page, `web-e2e-${scenario.name}`))
+    const group = page.locator('[role="treeitem"]').first()
+    await group.waitFor({ timeout: 15_000 })
+    await group.click()
+    await page.locator('[role="treeitem"]').nth(1).click()
+    await page.getByText('DONE', { exact: true }).waitFor({ timeout: 15_000 })
+    await expandTurnProcesses(page)
+    const edit = page.locator('[data-variant="edit"]')
+    expect(await edit.textContent()).toContain(scenario.totals)
+    expect(await edit.locator('[data-diff]').count()).toBe(0)
+    await edit.locator('[data-expandable]').click()
+    const card = edit.locator('[data-diff]')
+    await card.waitFor()
+    expect(await card.getByText(scenario.shared, { exact: true }).count()).toBe(1)
+    expect(await card.textContent()).toContain(`${scenario.totals} · 1 file`)
+    const snapshotDir = `${ROOT}/web/${scenario.name}`
+    await compareOrRefreshGolden(`${snapshotDir}/ui.expected.md`,
+      await captureStableAria(page, '[data-variant="edit"]', scaffold.workspaceCwd), MODE)
+    await assertFixtureInventory(snapshotDir, scenario.inventory)
+    expect(tripwire.pageErrors).toEqual([])
+    expect(tripwire.warnings).toEqual([])
+  })
+})
diff --git a/apps/web/tests/document-preview.e2e.ts b/apps/web/tests/document-preview.e2e.ts
index 0e1c570f2a..00fcf849e0 100644
--- a/apps/web/tests/document-preview.e2e.ts
+++ b/apps/web/tests/document-preview.e2e.ts
@@ -80,7 +80,7 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
     }
   })
 
-  it('opens text, isolated HTML, intrinsic images, and rendered PDF from the Session workspace', async () => {
+  it('opens text, isolated HTML, width-fitted images, and rendered PDF from the Session workspace', async () => {
     onTestFailed(async () => {
       await mkdir(SHOT_DIR, { recursive: true })
       await saveFailureShot(page, `screenshots/0908-document-preview/smoke-${process.pid}`)
@@ -130,6 +130,7 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
         '</svg>',
       ].join('')),
       writeFile(join(cwd, 'smoke.pdf'), pdfFixture()),
+      writeFile(join(cwd, 'clip.mp4'), Buffer.from([0x00, 0x00, 0x00, 0x18, 0x66, 0x74, 0x79, 0x70])),
     ])
 
     const column = page.locator('[data-rightbar-col]')
@@ -175,6 +176,7 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
       await column.locator('[data-files-entry="file"]').getByRole('button', { name, exact: true }).click()
       await expect.poll(async () => (await preview.getAttribute('data-textpreview-url'))?.endsWith(`/${name}`)).toBe(true)
     }
+    // Binary suffixes (bitmaps, PDF) drop the plain-text fallback; a single remaining viewer renders no control.
     const viewer = preview.locator('[data-document-viewer-menu]')
     const body = preview.locator('[data-textpreview-body]')
     const sections = ['# Document preview']
@@ -276,9 +278,9 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
     ].join('\n'))
 
     await openFile('smoke.pdf')
-    await expect.poll(() => viewer.innerText()).toBe('PDF')
     const canvas = preview.getByRole('img', { name: 'PDF page 1', exact: true })
     await canvas.waitFor({ state: 'visible', timeout: 30_000 })
+    expect(await viewer.count()).toBe(0)
     expect(await preview.locator('[role="toolbar"]').count()).toBe(0)
     expect(await preview.locator('[data-pdf-page]').count()).toBe(2)
     await expect.poll(() => canvasColor(canvas), { timeout: 30_000 }).toBe('red')
@@ -308,7 +310,7 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
     await successShot(page, 'pdf')
     sections.push([
       '## PDF', '',
-      `- Viewer: ${await viewer.innerText()}`,
+      `- Viewer menu hidden: ${String(await viewer.count() === 0)}`,
       `- Worker: ${workerNames.find(name => name === 'dsh-pdf')}`,
       `- Continuous pages: ${await preview.locator('[data-pdf-page]').count()}`,
       `- Horizontal overflow: ${String(await body.evaluate(node => node.scrollWidth > node.clientWidth))}`,
@@ -317,9 +319,9 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
     ].join('\n'))
 
     await openFile('tiny.png')
-    await expect.poll(() => viewer.innerText()).toBe('Image')
     const tinyImage = preview.getByRole('img', { name: 'Image preview: tiny.png', exact: true })
     await tinyImage.waitFor({ state: 'visible', timeout: 15_000 })
+    expect(await viewer.count()).toBe(0)
     expect(await tinyImage.evaluate(node => ({
       width: (node as HTMLImageElement).naturalWidth,
       height: (node as HTMLImageElement).naturalHeight,
@@ -339,25 +341,35 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
 
     await openFile('large.svg')
     await expect.poll(() => viewer.innerText()).toBe('Image')
+    await viewer.click()
+    await page.getByRole('menuitem', { name: 'Plain text', exact: true }).waitFor({ timeout: 15_000 })
+    await page.keyboard.press('Escape')
     const largeImage = preview.getByRole('img', { name: 'Image preview: large.svg', exact: true })
     await largeImage.waitFor({ state: 'visible', timeout: 15_000 })
-    expect(await largeImage.evaluate(node => ({
-      naturalWidth: (node as HTMLImageElement).naturalWidth,
-      naturalHeight: (node as HTMLImageElement).naturalHeight,
-      width: getComputedStyle(node).width,
-      height: getComputedStyle(node).height,
-    }))).toEqual({ naturalWidth: 1200, naturalHeight: 1600, width: '1200px', height: '1600px' })
-    expect(await body.evaluate(node => ({
-      horizontal: node.scrollWidth > node.clientWidth,
-      vertical: node.scrollHeight > node.clientHeight,
-    }))).toEqual({ horizontal: true, vertical: true })
+    const fitted = await largeImage.evaluate((node) => {
+      const image = node as HTMLImageElement
+      const scroller = image.closest('[data-textpreview-body]')
+      if (scroller === null) throw new Error('image document scroller is unavailable')
+      const rect = image.getBoundingClientRect()
+      return {
+        naturalWidth: image.naturalWidth,
+        naturalHeight: image.naturalHeight,
+        width: rect.width,
+        height: rect.height,
+        paneWidth: scroller.clientWidth,
+        paneHeight: scroller.clientHeight,
+      }
+    })
+    expect(fitted).toMatchObject({ naturalWidth: 1200, naturalHeight: 1600 })
+    expect(fitted.width).toBeLessThan(1200)
+    // Width fit: the image fills the frame's 12px-inset box while the aspect ratio holds.
+    expect(Math.abs((fitted.paneWidth - 24) - fitted.width)).toBeLessThanOrEqual(1)
+    expect(fitted.height / fitted.width).toBeCloseTo(1600 / 1200, 2)
     const scrolled = await body.evaluate((node) => {
       node.scrollLeft = node.scrollWidth
-      node.scrollTop = node.scrollHeight
-      return { left: node.scrollLeft, top: node.scrollTop }
+      return { left: node.scrollLeft, horizontalOverflow: node.scrollWidth > node.clientWidth }
     })
-    expect(scrolled.left).toBeGreaterThan(0)
-    expect(scrolled.top).toBeGreaterThan(0)
+    expect(scrolled).toEqual({ left: 0, horizontalOverflow: false })
     expect(await page.locator('html').getAttribute('data-image-preview-escape')).toBeNull()
 
     const releaseRead = Promise.withResolvers<undefined>()
@@ -450,12 +462,25 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
     ].join('\n'))
 
     await openFile('notes.unknown')
-    await expect.poll(() => viewer.innerText()).toBe('Plain text')
     const plainLines = preview.locator('[data-textpreview-line]')
     await expect.poll(() => plainLines.count()).toBe(2)
+    // Plain text is the only candidate, so no viewer menu renders.
+    expect(await viewer.count()).toBe(0)
     const fallback = (await plainLines.allTextContents()).map(line => line.trim())
     expect(fallback).toEqual(['UNKNOWN_SUFFIX', 'Plain fallback.'])
-    sections.push(['## Unknown suffix', '', `- Viewer: ${await viewer.innerText()}`, `- Text: ${fallback.join(' | ')}`].join('\n'))
+    sections.push(['## Unknown suffix', '', `- Viewer menu hidden: ${String(await viewer.count() === 0)}`, `- Text: ${fallback.join(' | ')}`].join('\n'))
+
+    await filesTab.click()
+    await column.locator('[data-files-entry="file"]').getByRole('button', { name: 'clip.mp4', exact: true }).click()
+    const unsupported = column.locator('[data-textpreview-state="unsupported"]')
+    await unsupported.waitFor({ timeout: 15_000 })
+    const unsupportedLine = await unsupported.locator('[data-textpreview-unsupported]').innerText()
+    expect(unsupportedLine).toContain('Preview is not available for this file type yet.')
+    expect(await unsupported.locator('[data-textpreview-path]').innerText()).toContain('clip.mp4')
+    expect(await unsupported.locator('[data-document-viewer-menu]').count()).toBe(0)
+    expect(await unsupported.locator('[data-textpreview-tool="reload"]').count()).toBe(0)
+    await successShot(page, 'unsupported')
+    sections.push(['## Unviewable binary', '', '- State: unsupported', `- Line: ${unsupportedLine.trim()}`].join('\n'))
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
     await compareOrRefreshGolden(EXPECTED, sections.join('\n\n'), MODE)
diff --git a/apps/web/tests/expected/sidebar-terminal/colors.expected.md b/apps/web/tests/expected/sidebar-terminal/colors.expected.md
new file mode 100644
index 0000000000..a3f4d4521c
--- /dev/null
+++ b/apps/web/tests/expected/sidebar-terminal/colors.expected.md
@@ -0,0 +1,30 @@
+{
+  "lightText": {
+    "foreground": "rgb(111, 111, 110)",
+    "background": "rgba(0, 0, 0, 0)"
+  },
+  "customLight": {
+    "ansi": {
+      "foreground": "rgb(0, 137, 0)",
+      "background": "rgba(0, 0, 0, 0)"
+    },
+    "extended": {
+      "foreground": "rgb(153, 0, 153)",
+      "background": "rgba(0, 0, 0, 0)"
+    }
+  },
+  "ronLight": {
+    "background": "rgb(255, 255, 255)",
+    "foreground": "rgb(0, 0, 0)",
+    "shadow": "none",
+    "border": "rgb(0, 0, 0)",
+    "outline": "rgb(0, 0, 0)"
+  },
+  "whiteInDark": {
+    "background": "rgb(0, 0, 0)",
+    "foreground": "rgb(255, 255, 255)",
+    "shadow": "none",
+    "border": "rgb(255, 255, 255)",
+    "outline": "rgb(255, 255, 255)"
+  }
+}
diff --git a/apps/web/tests/expected/sidebar-terminal/guide.expected.md b/apps/web/tests/expected/sidebar-terminal/guide.expected.md
new file mode 100644
index 0000000000..4c38f09585
--- /dev/null
+++ b/apps/web/tests/expected/sidebar-terminal/guide.expected.md
@@ -0,0 +1,3 @@
+- button "New terminal Run commands in the Session workspace"
+- button "Choose shell" [expanded]:
+  - img
diff --git a/apps/web/tests/expected/sidebar-terminal/selection.expected.md b/apps/web/tests/expected/sidebar-terminal/selection.expected.md
deleted file mode 100644
index 21961c3c4d..0000000000
--- a/apps/web/tests/expected/sidebar-terminal/selection.expected.md
+++ /dev/null
@@ -1,3 +0,0 @@
-- text: Shell
-- button "Shell": bash — /bin/bash
-- button "Start terminal"
diff --git a/apps/web/tests/expected/sidebar-terminal/shell-menu.expected.md b/apps/web/tests/expected/sidebar-terminal/shell-menu.expected.md
index 50be37e43b..8636cb1da0 100644
--- a/apps/web/tests/expected/sidebar-terminal/shell-menu.expected.md
+++ b/apps/web/tests/expected/sidebar-terminal/shell-menu.expected.md
@@ -1,5 +1,5 @@
 - menu:
-  - menuitem "bash — /bin/bash":
-    - text: bash — /bin/bash
+  - menuitem "bash":
+    - text: bash
     - img
-  - menuitem "sh — /bin/sh"
+  - menuitem "sh"
diff --git a/apps/web/tests/expected/sidebar-terminal/theme.expected.md b/apps/web/tests/expected/sidebar-terminal/theme.expected.md
new file mode 100644
index 0000000000..77637291ba
--- /dev/null
+++ b/apps/web/tests/expected/sidebar-terminal/theme.expected.md
@@ -0,0 +1,14 @@
+{
+  "light": {
+    "surface": "rgb(255, 255, 255)",
+    "viewport": "rgb(255, 255, 255)",
+    "underlay": "rgb(255, 255, 255)",
+    "foreground": "rgb(15, 17, 21)"
+  },
+  "dark": {
+    "surface": "rgb(21, 21, 23)",
+    "viewport": "rgb(21, 21, 23)",
+    "underlay": "rgb(21, 21, 23)",
+    "foreground": "rgb(249, 250, 251)"
+  }
+}
diff --git a/apps/web/tests/lifecycle-chrome.e2e.ts b/apps/web/tests/lifecycle-chrome.e2e.ts
index 4af796b3ef..818aa80ba2 100644
--- a/apps/web/tests/lifecycle-chrome.e2e.ts
+++ b/apps/web/tests/lifecycle-chrome.e2e.ts
@@ -23,7 +23,7 @@ import {
   launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import {
-  connectFreshWorkspace, newEnglishPage, saveFailureShot, writeComposerDraft, ZH_BROWSER_LOCALE,
+  connectFreshWorkspace, expandOwningTurnProcess, newEnglishPage, saveFailureShot, writeComposerDraft, ZH_BROWSER_LOCALE,
 } from './support.ts'
 
 const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/lifecycle-chrome', import.meta.url))
@@ -291,10 +291,7 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
         await input.press('Enter')
         if (MODE !== 'record') {
           const thinking = page.locator('[data-variant="think"][data-state="running"]')
-          const disclosure = thinking.getByRole('button')
-          await expect.poll(() => disclosure.getAttribute('aria-expanded')).toBe('true')
-          await disclosure.click()
-          await expect.poll(() => disclosure.getAttribute('aria-expanded')).toBe('false')
+          await expect.poll(() => thinking.getByRole('button').getAttribute('aria-expanded')).toBe('false')
           const liveTail = thinking.locator('[data-follow-end]')
           await expect.poll(async () => {
             if (await liveTail.count() !== 1) return false
@@ -346,6 +343,45 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
     expect((turnEnds[0] as SessionEvent & { data: { reason: { kind: string } } }).data.reason.kind).toBe('completed')
   }, 60_000)
 
+  it.skipIf(MODE === 'record')('pins an open Think header to the conversation scrollport (real layout)', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-think-sticky'))
+    // The settled turn collapses its process row, which hides the Think row.
+    // The fixture's recorded reasoning is one line, too short to overflow the
+    // scrollport, so this case proves the CSS resolves onto the Think header in
+    // a real browser (jsdom computes no sticky layout); the pinned-while-
+    // scrolling and z-rank evidence belongs to the compaction path in
+    // seeded-history.e2e.ts, whose summary length that suite controls.
+    const thinkRow = page.locator('[data-variant="think"]').first()
+    await thinkRow.waitFor({ state: 'attached', timeout: 15_000 })
+    const process = page.locator('[data-turn-process]').first()
+    const processWasOpen = await process.getAttribute('aria-expanded') === 'true'
+    try {
+      await expandOwningTurnProcess(page, thinkRow)
+      const collapsedHeader = thinkRow.locator('[data-disclosure-row]').first()
+      await collapsedHeader.waitFor({ timeout: 10_000 })
+      // Collapsed, the rule's `data-open` gate is absent and the header stays in
+      // flow. It is `relative` here — the row is the sweep-glare overlay anchor
+      // — so the assertion is the absence of `sticky`, not a specific value.
+      expect(await collapsedHeader.evaluate(element => getComputedStyle(element).position)).not.toBe('sticky')
+      await collapsedHeader.click()
+      const openHeader = page.locator('[data-variant="think"] [data-open] [data-disclosure-row]').first()
+      await openHeader.waitFor({ timeout: 10_000 })
+      const openStyle = await openHeader.evaluate((element) => {
+        const style = getComputedStyle(element)
+        return { position: style.position, top: style.top }
+      })
+      expect(openStyle.position).toBe('sticky')
+      expect(openStyle.top).toBe('0px')
+    } finally {
+      // Restore the settled state the reload goldens below are captured in.
+      const openThinkRow = page.locator('[data-variant="think"] [data-open] [data-disclosure-row]')
+      if (await openThinkRow.count() > 0) await openThinkRow.first().click()
+      if (!processWasOpen && await process.getAttribute('aria-expanded') === 'true') await process.click()
+    }
+    await expect.poll(() => page.locator('[data-variant="think"] [data-open]').count(), { timeout: 5_000 }).toBe(0)
+    expect(tripwire.pageErrors).toEqual([])
+  }, 60_000)
+
   it.skipIf(MODE === 'record')('recovers the whole surface across a reload from the log alone', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-lifecycle-reload'))
     const warningStart = tripwire.warnings.length
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index ca4d801569..0532e997ac 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -59,9 +59,12 @@ import {
 import {
   auditStartupEntries,
   composeEntries,
+  createProfileResolutionGeneration,
   healProfilesModuleFallback,
   loadOverlayPatches,
+  PluginPackages,
   type Profile,
+  type ProfileResolutionMode,
 } from '@deepseek-ai/dsh-app-boot'
 import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
 import { LlmAdapter } from '@deepseek-ai/dsh-llm'
@@ -288,6 +291,8 @@ export interface WebScaffold {
 
 /** Options for {@link launchWebScaffold}. */
 export interface LaunchOptions {
+  /** Profile resolver backend used by this test Host; defaults to runtime coverage. */
+  profileResolutionMode?: Extract<ProfileResolutionMode, 'dual' | 'runtime'>
   /** Enable the real Open In rows with deterministic launch-environment facts. */
   openInAppEnvironment?: LaunchEnvironmentSnapshot
   /** Compare the replayed root session with `replayFixture`; defaults on for a manifest-owned canonical recording. */
@@ -521,6 +526,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
   const patches: PatchOptions[] = [
     ...basePatches,
     ...surfacePatches,
+    { id: 'session-log-deepseek', config: { enabled: false } },
     // The historical Messages fixture retains its recorded route during replay;
     // live configuration uses the shared DeepSeek route. Explicit overlays win.
     ...messages
@@ -683,21 +689,19 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
         patches: [],
       }
     }))
-    // Mirror the production launcher: the shared installation closure keeps
-    // its carrier-specific fallback, while private bundle dependencies stay
-    // isolated to this synthetic scaffold profile.
-    await healProfilesModuleFallback({
-      installAnchor: INSTALL_ANCHOR,
-      home: harnessHome,
-      profile: {
-        name: 'scaffold',
-        dir: profileDir,
-        layers: extraLayers,
-        patchPath: join(profileDir, 'cordis.patch.yml'),
-        patches: [],
-        patchReload: 'startup',
-      },
-    })
+    const profile: Profile = {
+      name: 'scaffold',
+      dir: profileDir,
+      layers: extraLayers,
+      patchPath: join(profileDir, 'cordis.patch.yml'),
+      patches: [],
+      patchReload: 'startup',
+    }
+    const profileResolutionMode = options.profileResolutionMode ?? 'runtime'
+    const resolutionOptions = { installAnchor: INSTALL_ANCHOR, home: harnessHome, profile }
+    const resolution = profileResolutionMode === 'runtime'
+      ? await createProfileResolutionGeneration(resolutionOptions)
+      : await healProfilesModuleFallback(resolutionOptions)
     await mkdir(profileDir, { recursive: true })
     const rootConfig = join(profileDir, 'cordis.yml')
     await writeFile(rootConfig, '[]\n')
@@ -714,6 +718,10 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
         throw new Error(`web e2e scaffold: the web app requested exit ${String(code)} with no arguments to reject`)
       },
     })
+    await ctx.plugin(PluginPackages, {
+      generation: resolution,
+      behavior: profileResolutionMode === 'dual' ? 'verify' : 'enforce',
+    })
     await ctx.plugin(Loader)
     ctx.loader.builtins.include = Include
     // `cordis:group` beside it, exactly as `boot()` registers it: a group row is
diff --git a/apps/web/tests/seeded-history.e2e.ts b/apps/web/tests/seeded-history.e2e.ts
index 7729efaf26..cb2dcab569 100644
--- a/apps/web/tests/seeded-history.e2e.ts
+++ b/apps/web/tests/seeded-history.e2e.ts
@@ -39,6 +39,13 @@ const UI_EXPANDED_EXPECTED = fileURLToPath(
 const COMMAND_ROW_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/seeded-history/command-row.expected.md', import.meta.url))
 const FEEDBACK_ROW_EXPECTED = fileURLToPath(new URL('../../../snapshots/web/seeded-history/feedback-row.expected.md', import.meta.url))
 const FILE_PREVIEW_EXPECTED = join(SNAPSHOT_DIR, 'file-preview.expected.md')
+// The pinned-header geometry golden: a pure-CSS, user-visible behavior that
+// changes no DOM and no accessible name, so the aria goldens cannot capture it
+// (docs/testing.md, "when a snapshot test is required", still requires a
+// keyless snapshot). Following composer-draft-scroll's geometry golden, it
+// records platform-independent semantic booleans about the pinned compaction
+// header, no absolute pixels.
+const STICKY_GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'sticky-geometry.expected.md')
 const MODE = webSnapshotMode()
 const SEED_ID = 'seeded-history-web-e2e'
 
@@ -137,7 +144,16 @@ function withCompaction(raw: string, meter: TokenMeter): string {
       sourceCommandId: commandId,
       summary: [{
         type: 'text',
-        text: '## Cold resume compact summary\n\n- The exact summary remains available.',
+        text: '## Cold resume compact summary\n\n- The exact summary remains available.\n\n'
+          // A fenced code block gives the summary body a sticky-bannered
+          // descendant (CodeBlock pins its banner at z-index 6). The block is
+          // long enough that its banner has room to hold below the pinned
+          // header, which is where its Copy control must stay clickable; the
+          // list makes the body overflow the shrunk viewport.
+          + '```ts\nfunction resume(): boolean {\n'
+          + Array.from({ length: 26 }, (_, index) => `  const step${index + 1} = read(${index + 1})`).join('\n')
+          + '\n  return true\n}\n```\n\n'
+          + Array.from({ length: 40 }, (_, index) => `- Retained fact ${index + 1}: the reader still sees the pre-compaction surface.`).join('\n'),
       }],
       shadowedRange: { start: first, end: last },
       shadowedSeqs: surfaceSeqs,
@@ -437,20 +453,193 @@ describe('web e2e: seeded history renders through cold resume', () => {
     await page.getByRole('navigation', { name: 'Turn navigation', exact: true }).waitFor({ state: 'visible' })
   })
 
-  it.skipIf(MODE === 'record')('expands the cold-resumed compact summary', async () => {
+  it.skipIf(MODE === 'record')('expands the cold-resumed compact summary and pins its header while scrolling', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-seeded-compaction'))
     const marker = page.getByRole('button', { name: /compact Compacted \d+ history items/ })
     await marker.waitFor({ timeout: 10_000 })
     expect(await marker.getAttribute('aria-expanded')).toBe('false')
-    await marker.click()
-    await expect.poll(() => marker.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('true')
-    await expect.poll(() => page.getByRole('heading', { name: 'Cold resume compact summary' }).count(), {
-      timeout: 5_000,
-    }).toBe(1)
-    expect(await page.getByText('The exact summary remains available.', { exact: false }).count()).toBeGreaterThan(0)
-    // Restore the shared page state for any later case.
-    await marker.click()
-    await expect.poll(() => marker.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('false')
+    // Collapsed, the marker is not pinned: the sticky rule's `:has()` gate
+    // needs the body sibling, which only exists while open. jsdom computes no
+    // sticky layout, so this real-browser layer proves the CSS resolves.
+    const collapsedPosition = await marker.evaluate(element => getComputedStyle(element).position)
+    expect(collapsedPosition).not.toBe('sticky')
+    const originalViewport = page.viewportSize() ?? { width: 1680, height: 1000 }
+    // Captured so a failure in the cleanup below cannot replace the assertion
+    // that actually failed.
+    let bodyError: unknown
+    try {
+      await marker.click()
+      await expect.poll(() => marker.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('true')
+      await expect.poll(() => page.getByRole('heading', { name: 'Cold resume compact summary' }).count(), {
+        timeout: 5_000,
+      }).toBe(1)
+      expect(await page.getByText('The exact summary remains available.', { exact: false }).count()).toBeGreaterThan(0)
+      // Open, the toggle pins to the scroll container's top.
+      const openStyle = await marker.evaluate((element) => {
+        const style = getComputedStyle(element)
+        return { position: style.position, top: style.top, zIndex: Number.parseInt(style.zIndex, 10) }
+      })
+      expect(openStyle.position).toBe('sticky')
+      expect(openStyle.top).toBe('0px')
+      // The summary body carries a fenced code block whose own banner pins at
+      // z-index 6; the toggle must outrank it, or a code-block summary would
+      // re-bury the toggle. Sample the banner inside THIS summary body, not a
+      // code block elsewhere on the page.
+      const bannerZ = await page.locator('[class*="compactionBody"] [class*="bannerWrap"]').first().evaluate(
+        element => Number.parseInt(getComputedStyle(element).zIndex, 10),
+      )
+      expect(openStyle.zIndex).toBeGreaterThan(bannerZ)
+      // Hovering the open toggle must keep an OPAQUE fill: the default hover
+      // token is translucent and would let the scrolling prose bleed through
+      // the moment the pointer lands to collapse it. The alpha token, if
+      // present, is the fourth comma value (`rgba(r, g, b, a)`) or the value
+      // after `/` in the space form; three channels mean opaque. A color that
+      // parses to neither returns -1, which fails loud instead of passing as
+      // opaque.
+      await marker.hover()
+      const hoverAlpha = await marker.evaluate((element) => {
+        const bg = getComputedStyle(element).backgroundColor
+        const inner = /^rgba?\((.+)\)$/.exec(bg.trim())?.[1]
+        if (inner === undefined) return -1
+        const slashAlpha = inner.split('/')[1]
+        if (slashAlpha !== undefined) return Number.parseFloat(slashAlpha)
+        const channels = inner.split(/[\s,]+/).filter(token => token.length > 0)
+        const commaAlpha = channels[3]
+        if (commaAlpha !== undefined) return Number.parseFloat(commaAlpha)
+        if (channels.length === 3) return 1
+        return -1
+      })
+      expect(hoverAlpha).toBe(1)
+      // Scroll so the summary's code banner reaches its own stuck position.
+      // The banner's sticky offset holds it below the pinned header's band, so
+      // the point this case samples is the banner's Copy control: the header
+      // must not cover it. Shrinking the viewport first forces overflow
+      // regardless of summary length.
+      await page.setViewportSize({ width: originalViewport.width, height: 360 })
+      const geom = await marker.evaluate((button) => {
+        const container = button.closest('[data-conversation-scroll]') as HTMLElement
+        const banner = container.querySelector('[class*="compactionBody"] [class*="bannerWrap"]') as HTMLElement
+        const copy = banner.querySelector('button') as HTMLElement
+        // Both the toggle and the code banner are sticky, so a rect taken while
+        // either is stuck reports the stuck position rather than its content
+        // offset. Measure both unstuck, so the target below does not depend on
+        // where the scrollport happened to be when this case started.
+        const markerInline = button.style.position
+        const bannerInline = banner.style.position
+        const bannerTopInline = banner.style.top
+        button.style.position = 'static'
+        banner.style.position = 'static'
+        banner.style.top = 'auto'
+        const containerTop = container.getBoundingClientRect().top
+        const markerStaticTop = button.getBoundingClientRect().top - containerTop + container.scrollTop
+        const bannerStaticTop = banner.getBoundingClientRect().top - containerTop + container.scrollTop
+        const headerHeight = button.getBoundingClientRect().height
+        button.style.position = markerInline
+        banner.style.position = bannerInline
+        banner.style.top = bannerTopInline
+        // The banner sticks once its static top passes the band the toggle
+        // occupies. Land the static top 8px above the scrollport top: if the
+        // banner still pinned at top 0, 8px of it would sit under the toggle,
+        // so this position distinguishes the offset from the uncovered case.
+        // The banner must hold at the band's bottom edge, and its Copy control
+        // must stay the topmost element at its own center.
+        container.scrollTop = Math.max(0, bannerStaticTop + 8)
+        const markerRect = button.getBoundingClientRect()
+        const bannerRect = banner.getBoundingClientRect()
+        const copyRect = copy.getBoundingClientRect()
+        const currentContainerTop = container.getBoundingClientRect().top
+        const markerProbe = document.elementFromPoint(
+          markerRect.left + markerRect.width / 2,
+          markerRect.top + markerRect.height / 2,
+        )
+        const copyProbe = document.elementFromPoint(
+          copyRect.left + copyRect.width / 2,
+          copyRect.top + copyRect.height / 2,
+        )
+        return {
+          scrollTop: container.scrollTop,
+          // The header's own content offset now lies above the scrollport top,
+          // so its rect top can equal the scrollport top only through stickiness
+          // — this is the precondition that makes the pinning assertion mean
+          // something.
+          staticAboveViewport: container.scrollTop > markerStaticTop,
+          markerTop: markerRect.top,
+          containerTop: currentContainerTop,
+          bannerTop: bannerRect.top,
+          bannerStuck: Math.abs(bannerRect.top - (currentContainerTop + headerHeight)) <= 1,
+          bannerBelowHeader: bannerRect.top >= markerRect.bottom - 1,
+          markerOwnsCenter: button.contains(markerProbe),
+          copyOwnsCenter: copy.contains(copyProbe),
+        }
+      })
+      expect(geom.scrollTop).toBeGreaterThan(0)
+      expect(geom.staticAboveViewport).toBe(true)
+      expect(Math.abs(geom.markerTop - geom.containerTop)).toBeLessThanOrEqual(1)
+      expect(geom.bannerStuck).toBe(true)
+      expect(geom.bannerBelowHeader).toBe(true)
+      expect(geom.markerOwnsCenter).toBe(true)
+      expect(geom.copyOwnsCenter).toBe(true)
+      // Keyless geometry golden for this user-visible, DOM-invariant CSS
+      // behavior: platform-independent semantic facts, no absolute pixels.
+      // Every line is a value asserted just above, so a regression reddens the
+      // expect first; compareOrRefreshGolden writes the file in refresh mode
+      // and byte-compares it in replay.
+      const stickyGolden = [
+        '# Compaction marker sticky header (pinned over a code-block summary)',
+        '',
+        '## Collapsed',
+        '',
+        `- header is not sticky: ${String(collapsedPosition !== 'sticky')}`,
+        '',
+        '## Open, pinned at the scroll container top',
+        '',
+        `- header position is sticky: ${String(openStyle.position === 'sticky')}`,
+        `- header pins to the top edge: ${String(openStyle.top === '0px')}`,
+        `- header outranks the summary code-block banner: ${String(openStyle.zIndex > bannerZ)}`,
+        `- hover fill stays fully opaque: ${String(hoverAlpha === 1)}`,
+        '',
+        '## Scrolled so the summary code banner reaches its sticky offset',
+        '',
+        `- container is scrolled off its top: ${String(geom.scrollTop > 0)}`,
+        `- header's static position sits above the scrollport: ${String(geom.staticAboveViewport)}`,
+        `- header holds at the scrollport top: ${String(Math.abs(geom.markerTop - geom.containerTop) <= 1)}`,
+        `- header owns the center point (toggle stays clickable): ${String(geom.markerOwnsCenter)}`,
+        `- summary code banner holds below the header band: ${String(geom.bannerStuck)}`,
+        `- summary code banner stays clear of the header: ${String(geom.bannerBelowHeader)}`,
+        `- banner Copy control owns its own center: ${String(geom.copyOwnsCenter)}`,
+      ].join('\n').trimEnd()
+      await compareOrRefreshGolden(STICKY_GEOMETRY_EXPECTED, stickyGolden, MODE)
+    } catch (error) {
+      bodyError = error
+    }
+    // Restore the shared page state whether or not the body failed. Order
+    // matters: collapse the marker, restore the viewport, then re-enter
+    // follow-bottom. The control is what clears the off-floor ownership a
+    // programmatic `scrollTop` assignment leaves in ChatView's reader-movement
+    // ledger, so click it when it is there. It appears only after that ledger
+    // settles (`scrollend` or the sampling interval), and it never renders at
+    // all when the collapse's shrink clamp already re-entered follow, so the
+    // assertion is the restored state — no control, and the scrollport on its
+    // floor — rather than the control's presence.
+    try {
+      if (await marker.getAttribute('aria-expanded') === 'true') await marker.click()
+      await expect.poll(() => marker.getAttribute('aria-expanded'), { timeout: 5_000 }).toBe('false')
+      await page.setViewportSize(originalViewport)
+      const scrollport = page.locator('[data-conversation-scroll]')
+      const backToBottom = page.getByRole('button', { name: 'Back to bottom', exact: true })
+      await expect.poll(async () => {
+        if (await backToBottom.count() > 0) await backToBottom.click()
+        const atFloor = await scrollport.evaluate((host: HTMLElement) =>
+          Math.abs(host.scrollHeight - host.clientHeight - host.scrollTop) <= 1)
+        return await backToBottom.count() === 0 && atFloor
+      }, { timeout: 15_000 }).toBe(true)
+    } catch (cleanupError) {
+      // The body's own assertion is the diagnosis; a cleanup failure would
+      // replace it, and the state it failed to restore shows up in the next
+      // case's golden.
+      if (bodyError === undefined) throw cleanupError
+    }
+    if (bodyError !== undefined) throw bodyError
   })
 
   it.skipIf(MODE === 'record')('an Access-chip switch lands one command row: bare name, non-repeating settlement text', async () => {
@@ -546,7 +735,7 @@ describe('web e2e: seeded history renders through cold resume', () => {
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
       'command-row.expected.md', 'feedback-row.expected.md', 'file-preview.expected.md',
-      'session.v3.jsonl', 'ui.expected.md', 'ui-expanded.expected.md',
+      'session.v3.jsonl', 'sticky-geometry.expected.md', 'ui.expected.md', 'ui-expanded.expected.md',
     ])
   })
 })
diff --git a/apps/web/tests/shipped-composition.e2e.ts b/apps/web/tests/shipped-composition.e2e.ts
index 9372b32e61..ac7ec67d49 100644
--- a/apps/web/tests/shipped-composition.e2e.ts
+++ b/apps/web/tests/shipped-composition.e2e.ts
@@ -2,7 +2,7 @@
 // and asserts its catalog, defaults, Loader lifecycle, and one complete Auto
 // producer-to-tool path. Browser scenarios in this lane own visual behavior.
 import { randomUUID } from 'node:crypto'
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -513,6 +513,7 @@ afterEach(async () => {
 
 it('assembles the shipped Web transport, catalog, guidance, and defaults', async () => {
   scaffold = await launchWebScaffold({ deepSeekMissingCredential: true })
+  expect(existsSync(join(scaffold.harnessHome, 'profiles', 'node_modules'))).toBe(false)
   const ctx = scaffold.ctx
   expect(ctx.llm.listProviders().some(provider => provider.id === 'deepseek-messages')).toBe(false)
   expect(ctx.agentDefaultModel.currentSelection()).toEqual({ provider: 'deepseek-official', model: 'deepseek-flash' })
@@ -640,8 +641,9 @@ it('assembles the shipped Web transport, catalog, guidance, and defaults', async
   }
 }, 120_000)
 
-it('ships PTC with run_code but without the general workflow SDK binding', async () => {
-  scaffold = await launchWebScaffold({ deepSeekMissingCredential: true })
+it('ships PTC with run_code but without the general workflow SDK binding under dual resolution', async () => {
+  scaffold = await launchWebScaffold({ deepSeekMissingCredential: true, profileResolutionMode: 'dual' })
+  expect(existsSync(join(scaffold.harnessHome, 'profiles', 'node_modules'))).toBe(true)
   const ctx = scaffold.ctx
   const handle = await ctx.agents.create({
     sessionId: SessionId('shipped-ptc-composition'),
diff --git a/apps/web/tests/sidebar-terminal.e2e.ts b/apps/web/tests/sidebar-terminal.e2e.ts
index ba1ee4ca94..8712d81fb0 100644
--- a/apps/web/tests/sidebar-terminal.e2e.ts
+++ b/apps/web/tests/sidebar-terminal.e2e.ts
@@ -18,8 +18,7 @@ async function openTerminal(page: Page, waitForShell = true): Promise<void> {
   if (await expand.isVisible()) await expand.click()
   const entry = page.locator('[data-sidebar-right-guide-entry="terminal"]')
   if (!await entry.isVisible()) await page.locator('[data-dockkit-add-tab]').click()
-  await entry.click()
-  await page.getByRole('button', { name: 'Start terminal', exact: true }).click()
+  await entry.getByRole('button', { name: /^New terminal/u }).click()
   if (waitForShell) await expect.poll(async () => await page.locator('.xterm-rows:visible').innerText()).toContain('bash-')
 }
 
@@ -29,6 +28,18 @@ async function command(page: Page, text: string): Promise<void> {
   await page.keyboard.press('Enter')
 }
 
+async function selectTerminalTheme(page: Page, name: string): Promise<void> {
+  await page.getByRole('button', { name: 'Settings', exact: true }).click()
+  const dialog = page.getByRole('dialog', { name: 'Settings' })
+  const [response] = await Promise.all([
+    page.waitForResponse(candidate => new URL(candidate.url()).pathname === '/api/settings/mutate' && candidate.request().method() === 'POST'),
+    dialog.getByRole('button', { name, exact: true }).click(),
+  ])
+  expect(response.ok()).toBe(true)
+  await page.keyboard.press('Escape')
+  await dialog.waitFor({ state: 'hidden' })
+}
+
 describe.skipIf(process.platform === 'win32')('Web sidebar terminal', () => {
   let scaffold: WebScaffold
   let browser: Browser
@@ -81,6 +92,139 @@ describe.skipIf(process.platform === 'win32')('Web sidebar terminal', () => {
     }
   })
 
+  it('preserves program palettes and keeps ANSI text and cursors readable across DSH themes', async () => {
+    onTestFailed(() => saveFailureShot(page, 'terminal-colors'))
+    await page.emulateMedia({ colorScheme: 'light' })
+    await openTerminal(page)
+    const terminal = page.locator('[data-sidebar-terminal]')
+    const screen = page.locator('.xterm-rows:visible')
+    await command(page, "PS1=''; printf '\\033c\\033[97mBRIGHT_WHITE\\033[0m\\n'")
+    const colorOf = async (text: string) => {
+      const cell = screen.getByText(text, { exact: true })
+      await cell.waitFor()
+      return cell.evaluate(element => ({
+        foreground: getComputedStyle(element).color, background: getComputedStyle(element).backgroundColor,
+      }))
+    }
+    const lightText = await colorOf('BRIGHT_WHITE')
+    // Compare the rendered glyph with its real surface; the raw ANSI palette remains untouched.
+    expect(contrastRatio(lightText.foreground, 'rgb(255, 255, 255)')).toBeGreaterThanOrEqual(4.5)
+    await command(page, "printf '\\033]4;1;#009900;255;#990099\\007\\033[31mANSI_CUSTOM\\033[38;5;255mEXTENDED_CUSTOM\\033[0m\\n'")
+    const customLight = { ansi: await colorOf('ANSI_CUSTOM'), extended: await colorOf('EXTENDED_CUSTOM') }
+    await selectTerminalTheme(page, 'Dark')
+    await expect.poll(() => screen.evaluate(element => getComputedStyle(element).color)).toBe('rgb(249, 250, 251)')
+    await selectTerminalTheme(page, 'Light')
+    await expect.poll(() => screen.evaluate(element => getComputedStyle(element).color)).toBe('rgb(15, 17, 21)')
+    expect({ ansi: await colorOf('ANSI_CUSTOM'), extended: await colorOf('EXTENDED_CUSTOM') }).toEqual(customLight)
+    await command(page, "printf '\\033]104;1;255\\007'")
+    await expect.poll(async () => (await colorOf('ANSI_CUSTOM')).foreground).not.toBe(customLight.ansi.foreground)
+    await expect.poll(async () => (await colorOf('EXTENDED_CUSTOM')).foreground).not.toBe(customLight.extended.foreground)
+
+    await command(page, "printf '\\033]10;#112233;#ddeeff;#990099\\007'")
+    const defaults = () => terminal.evaluate(root => ({
+      foreground: getComputedStyle(root.querySelector('.xterm-rows')!).color,
+      background: getComputedStyle(root.querySelector('.xterm-scrollable-element')!).backgroundColor,
+    }))
+    const applicationDefaults = { foreground: 'rgb(17, 34, 51)', background: 'rgb(221, 238, 255)' }
+    await expect.poll(defaults).toEqual(applicationDefaults)
+    await selectTerminalTheme(page, 'Dark')
+    await expect.poll(() => terminal.evaluate(root => getComputedStyle(root.querySelector('.xterm')!.parentElement!).backgroundColor))
+      .toBe('rgb(21, 21, 23)')
+    expect(await defaults()).toEqual(applicationDefaults)
+    await command(page, "printf '\\033]110\\007\\033]111\\007\\033]112\\007'")
+    await expect.poll(defaults).toEqual({ foreground: 'rgb(249, 250, 251)', background: 'rgb(21, 21, 23)' })
+    await selectTerminalTheme(page, 'Light')
+    await expect.poll(defaults).toEqual({ foreground: 'rgb(15, 17, 21)', background: 'rgb(255, 255, 255)' })
+
+    const cursorColors = () => screen.locator('.xterm-cursor').evaluate((cursor) => {
+      const style = getComputedStyle(cursor)
+      return {
+        background: style.backgroundColor, foreground: style.color,
+        shadow: style.boxShadow, border: style.borderBottomColor, outline: style.outlineColor,
+      }
+    })
+    const paintCursor = async (sgr: string, shape = 2) => {
+      await command(page, `printf '\\033[0m\\033[2J\\033[H\\033[${sgr}mCURSOR\\033[1G\\033[${shape} q'`)
+      await expect.poll(() => screen.locator('.xterm-cursor').innerText()).toBe('C')
+    }
+    // ron uses foreground 51 and background 16; no installed Vim is required by CI.
+    await paintCursor('38;5;51;48;5;16')
+    await expect.poll(async () => (await cursorColors()).background).toBe('rgb(255, 255, 255)')
+    const ronLight = await cursorColors()
+    expect(ronLight.foreground).toBe('rgb(0, 0, 0)')
+    await terminal.screenshot({ path: `${shots}/ron-light.png`, animations: 'disabled' })
+    await selectTerminalTheme(page, 'Dark')
+    await page.locator('.xterm-helper-textarea:visible').click()
+    await expect.poll(async () => (await cursorColors()).background).toBe('rgb(249, 250, 251)')
+    await paintCursor('38;2;0;0;0;48;2;255;255;255')
+    await expect.poll(async () => (await cursorColors()).background).toBe('rgb(0, 0, 0)')
+    const whiteInDark = await cursorColors()
+    await paintCursor('0;7')
+    await expect.poll(async () => (await cursorColors()).background).toBe('rgb(0, 0, 0)')
+    for (const shape of [4, 6]) {
+      await paintCursor('38;5;51;48;5;16', shape)
+      await expect.poll(async () => shape === 4 ? (await cursorColors()).border : (await cursorColors()).shadow).toContain('rgb(249, 250, 251)')
+    }
+    await paintCursor('38;2;0;0;0;48;2;255;255;255', 1)
+    await page.addStyleTag({ content: '.xterm-cursor { animation-delay: -0.1s !important; animation-play-state: paused !important; }' })
+    await expect.poll(async () => (await cursorColors()).background).toBe('rgb(0, 0, 0)')
+    await page.addStyleTag({ content: '.xterm-cursor { animation-delay: -0.6s !important; }' })
+    await expect.poll(async () => (await cursorColors()).background).toBe('rgb(255, 255, 255)')
+    await page.locator('.xterm-helper-textarea:visible').evaluate((element) =>{  element.blur() })
+    await expect.poll(async () => (await cursorColors()).outline).toBe('rgb(0, 0, 0)')
+    await compareOrRefreshGolden(fileURLToPath(new URL('./expected/sidebar-terminal/colors.expected.md', import.meta.url)),
+      JSON.stringify({ lightText, customLight, ronLight, whiteInDark }, null, 2), webSnapshotMode())
+    expect(handles).toHaveLength(1)
+    expect(tripwire.pageErrors).toEqual([])
+  })
+
+  it('follows light, dark and system themes while preserving the running shell and its output', async () => {
+    await page.emulateMedia({ colorScheme: 'light' })
+    await openTerminal(page)
+    const process = processIdentity(0)
+    const terminal = page.locator('[data-sidebar-terminal]')
+    const screen = page.locator('.xterm-rows:visible')
+    await command(page, "DSH_THEME_PROBE=retained; PS1=''; printf '\\033cTHEME_CONTENT_RETAINED\\n'")
+    await expect.poll(() => screen.innerText()).toContain('THEME_CONTENT_RETAINED')
+    const readColors = () => terminal.evaluate((root) => {
+      const xterm = root.querySelector('.xterm')!
+      const rows = root.querySelector('.xterm-rows')!
+      return {
+        surface: getComputedStyle(xterm.parentElement!).backgroundColor,
+        viewport: getComputedStyle(root.querySelector('.xterm-scrollable-element')!).backgroundColor,
+        underlay: getComputedStyle(root.querySelector('.xterm-viewport')!).backgroundColor,
+        foreground: getComputedStyle(rows).color,
+      }
+    })
+
+    const light = await readColors()
+    expect(light.viewport).toBe(light.surface)
+    expect(light.underlay).toBe(light.surface)
+    await terminal.screenshot({ path: `${shots}/theme-light.png`, animations: 'disabled' })
+    await selectTerminalTheme(page, 'Dark')
+    await expect.poll(async () => (await readColors()).viewport).not.toBe(light.viewport)
+    const dark = await readColors()
+    expect(dark.viewport).toBe(dark.surface)
+    expect(dark.underlay).toBe(dark.surface)
+    expect(dark.foreground).not.toBe(light.foreground)
+    await terminal.screenshot({ path: `${shots}/theme-dark.png`, animations: 'disabled' })
+    await selectTerminalTheme(page, 'Light')
+    await expect.poll(readColors).toEqual(light)
+    await selectTerminalTheme(page, 'System')
+    await page.emulateMedia({ colorScheme: 'dark' })
+    await expect.poll(readColors).toEqual(dark)
+    await page.emulateMedia({ colorScheme: 'light' })
+    await expect.poll(readColors).toEqual(light)
+    await expect.poll(() => screen.innerText()).toContain('THEME_CONTENT_RETAINED')
+    await command(page, 'printf "THEME_STATE:%s\\n" "$DSH_THEME_PROBE"')
+    await expect.poll(() => screen.innerText()).toContain('THEME_STATE:retained')
+    expect(handles).toHaveLength(1)
+    expect(alive(process)).toBe(true)
+    await compareOrRefreshGolden(fileURLToPath(new URL('./expected/sidebar-terminal/theme.expected.md', import.meta.url)),
+      JSON.stringify({ light, dark }, null, 2), webSnapshotMode())
+    expect(tripwire.pageErrors).toEqual([])
+  })
+
   it('completes commands, preserves the process through collapse and reload, resizes, and kills on tab close', async () => {
     onTestFailed(() => saveFailureShot(page, 'sidebar-terminal'))
     await openTerminal(page)
@@ -158,42 +302,43 @@ describe.skipIf(process.platform === 'win32')('Web sidebar terminal', () => {
     expect(tripwire.pageErrors).toEqual([])
   })
 
-  it('offers installed shells, remembers the choice after reload, and restores without a picker', async () => {
+  it('chooses a shell from the guide menu, opens it directly, and remembers it after reload', async () => {
     onTestFailed(() => saveFailureShot(page, 'sidebar-terminal-shell-choice'))
     await page.locator('[data-sidebar-right-expand]').click()
     const entry = page.locator('[data-sidebar-right-guide-entry="terminal"]')
-    expect(await entry.innerText()).toBe('New terminal\nRun commands in the Session workspace')
     await page.locator('[data-sidebar-right-guide]').screenshot({ path: `${shots}/terminal-guide.png`, animations: 'disabled' })
-    await entry.click()
-    const selector = page.getByRole('button', { name: 'Shell', exact: true })
-    await selector.waitFor()
-    expect(await selector.innerText()).toContain('bash — /bin/bash')
-    expect(handles).toHaveLength(0)
-    await compareOrRefreshGolden(fileURLToPath(new URL('./expected/sidebar-terminal/selection.expected.md', import.meta.url)),
-      await page.locator('[data-sidebar-terminal]').ariaSnapshot(), webSnapshotMode())
+    const selector = entry.getByRole('button', { name: 'Choose shell', exact: true })
+    const cardBox = (await entry.boundingBox())!
+    const triggerBox = (await selector.boundingBox())!
+    expect(Math.abs(cardBox.x + cardBox.width - triggerBox.x - triggerBox.width)).toBeLessThanOrEqual(2)
+    await page.emulateMedia({ colorScheme: 'dark' })
     await selector.click()
+    await page.getByRole('menuitem', { name: 'bash', exact: true }).waitFor()
+    expect(handles).toHaveLength(0)
+    await compareOrRefreshGolden(fileURLToPath(new URL('./expected/sidebar-terminal/guide.expected.md', import.meta.url)),
+      await entry.ariaSnapshot(), webSnapshotMode())
     await compareOrRefreshGolden(fileURLToPath(new URL('./expected/sidebar-terminal/shell-menu.expected.md', import.meta.url)),
       await page.getByRole('menu').ariaSnapshot(), webSnapshotMode())
     await page.screenshot({ path: `${shots}/shell-menu.png`, fullPage: true })
-    await page.getByRole('menuitem', { name: 'sh — /bin/sh', exact: true }).click()
+    await page.keyboard.press('Escape')
+    expect(handles).toHaveLength(0)
+    await selector.click()
+    await page.getByRole('menuitem', { name: 'sh', exact: true }).click()
     expect(await page.evaluate(() => localStorage.getItem('dsh.terminal.shell'))).toBe('/bin/sh')
-    await page.screenshot({ path: `${shots}/shell-choice.png`, fullPage: true })
-    await page.getByRole('button', { name: 'Start terminal', exact: true }).click()
+    await page.locator('.xterm-helper-textarea:visible').waitFor()
     await command(page, "printf 'CHOSEN_SHELL:%s\\n' \"$0\"")
     const screen = page.locator('.xterm-rows:visible')
     await expect.poll(() => screen.innerText()).toContain('CHOSEN_SHELL:/bin/sh')
-    expect(await page.evaluate(() => localStorage.getItem('dsh.terminal.shell'))).toBe('/bin/sh')
     const retained = processIdentity(0)
     await page.reload({ waitUntil: 'load' })
     await page.locator('.xterm-helper-textarea:visible').waitFor()
-    expect(await selector.count()).toBe(0)
     expect(alive(retained)).toBe(true)
     await page.locator('[data-dockkit-add-tab]').click()
-    await page.locator('[data-sidebar-right-guide-entry="terminal"]').click()
-    await selector.waitFor()
-    expect(await selector.innerText()).toContain('sh — /bin/sh')
-    expect(handles).toHaveLength(1)
-    await page.getByRole('button', { name: 'Start terminal', exact: true }).click()
+    await selector.click()
+    await page.getByRole('menuitem', { name: 'sh', exact: true }).waitFor()
+    expect(await page.getByRole('menuitem', { name: 'sh', exact: true }).locator('svg').count()).toBe(1)
+    await page.keyboard.press('Escape')
+    await entry.getByRole('button', { name: /^New terminal/u }).click()
     await expect.poll(() => handles.length).toBe(2)
     expect(scaffold.ctx.terminalController.list(scaffold.ctx.agents.list()[0]!.id).map(info => info.shell.path)).toEqual(['/bin/sh', '/bin/sh'])
     expect(tripwire.pageErrors).toEqual([])
@@ -225,3 +370,13 @@ describe.skipIf(process.platform === 'win32')('Web sidebar terminal', () => {
   })
 
 })
+
+function contrastRatio(first: string, second: string): number {
+  const luminance = (color: string) => {
+    const [r, g, b] = color.match(/[\d.]+/gu)!.map(Number).map(channel => channel / 255)
+      .map(value => value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4)
+    return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!
+  }
+  const a = luminance(first), b = luminance(second)
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05)
+}
diff --git a/apps/web/tests/turn-tail-actions.e2e.ts b/apps/web/tests/turn-tail-actions.e2e.ts
index fdc1ef26f5..02f7540aab 100644
--- a/apps/web/tests/turn-tail-actions.e2e.ts
+++ b/apps/web/tests/turn-tail-actions.e2e.ts
@@ -17,7 +17,7 @@ import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
 import type { ReplayOverrideDoc } from '@deepseek-ai/dsh-llm-replay'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import {
-  assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts,
+  acknowledgeReloadConnectionLoss, assertFixtureInventory, captureStableAria, compareOrRefreshGolden, fixtureUserPrompts,
   launchWebScaffold, recordFixture, watchConsole, webSnapshotMode, type WebScaffold,
 } from './scaffold.ts'
 import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
@@ -201,13 +201,22 @@ describe('web e2e: assistant IconActions wait for the turn to end', () => {
     await timeTrigger.click()
     const timeDialog = page.getByRole('dialog', { name: 'Turn time and speed' })
     expect(await timeDialog.count()).toBe(1)
-    expect(await timeDialog.getByText(/tok\/s/).count()).toBeGreaterThan(0)
-    expect(await timeDialog.getByText('Time to first token (TTFT)', { exact: true }).count()).toBe(1)
+    expect(await timeDialog.getByText(/tok\/s/).count()).toBe(0)
+    expect(await timeDialog.getByText('Time to first token (TTFT)', { exact: true }).count()).toBe(0)
     await page.keyboard.press('Escape')
     await trigger.click()
 
     const expanded = await captureStableAria(page, '[class*="centerCol"]', scaffold!.workspaceCwd)
     await compareOrRefreshGolden(USAGE_EXPANDED_EXPECTED, expanded, MODE)
+
+    const warningStart = tripwire.warnings.length
+    await page.reload({ waitUntil: 'load' })
+    await expect.poll(() => timeTrigger.count(), { timeout: 15_000 }).toBe(1)
+    acknowledgeReloadConnectionLoss(tripwire, warningStart)
+    await timeTrigger.click()
+    expect(await timeDialog.count()).toBe(1)
+    expect(await timeDialog.getByText(/tok\/s/).count()).toBe(0)
+    expect(await timeDialog.getByText('Time to first token (TTFT)', { exact: true }).count()).toBe(0)
     expect(tripwire.pageErrors).toEqual([])
     expect(tripwire.warnings).toEqual([])
   }, 120_000)
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index 2c1a38c447..fe609be8c9 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -23,6 +23,7 @@
   // cannot see both sides of the cordis Context merges).
   "exclude": [
     "tests/default-product-isolation.e2e.ts",
+    "tests/diff-context.e2e.ts",
     "tests/scaffold.ts",
     "tests/auto-review-fixture.ts",
     "tests/scaffold-generation.spec.ts",
diff --git a/benchmarks/package.json b/benchmarks/package.json
index cc8c60cf71..3ce60f1d2d 100644
--- a/benchmarks/package.json
+++ b/benchmarks/package.json
@@ -6,6 +6,9 @@
   "type": "module",
   "devDependencies": {
     "playwright": "^1.49.0",
+    "@xterm/headless": "^6.0.0",
+    "@deepseek-ai/dsh-terminal": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
     "@deepseek-ai/dsh-llm-replay": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
diff --git a/benchmarks/terminal-io/session-adapter.ts b/benchmarks/terminal-io/session-adapter.ts
new file mode 100644
index 0000000000..7ed987aabc
--- /dev/null
+++ b/benchmarks/terminal-io/session-adapter.ts
@@ -0,0 +1,2 @@
+/** Private production entry bundled into the plain-Node terminal I/O worker. */
+export { LocalPtySession } from '../../packages/terminal/terminal-bash/src/session.ts'
diff --git a/benchmarks/terminal-io/terminal-io.bench.ts b/benchmarks/terminal-io/terminal-io.bench.ts
new file mode 100644
index 0000000000..631a00a24a
--- /dev/null
+++ b/benchmarks/terminal-io/terminal-io.bench.ts
@@ -0,0 +1,69 @@
+/** Bounded terminal output must not rescan a full retained window on every chunk. */
+import { join } from 'node:path'
+import { expect, it } from 'vitest'
+import { runBuiltBenchmarkWorker } from '../support/built-worker.ts'
+import { ciTimeBudget } from '../support/calibration.ts'
+import type { TerminalIoReport } from './terminal-io.worker.ts'
+
+const MIB = 1024 * 1024
+const ATTEMPTS = 5
+const WORKER = join(import.meta.dirname, '..', '.dsh-build', 'terminal-io', 'terminal-io.worker.js')
+/** M5 Pro / Node 26.5 reference expectations, before shared CI scaling and headroom. */
+const EXPECTED_MS = { steadyIngest: 20, steadyComplete: 50, fullComplete: 120 }
+const MAX_CAPACITY_RATIO = 4
+const MAX_RETAINED_HEAP_BYTES = 16 * MIB
+
+function median(values: readonly number[]): number {
+  return [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)] as number
+}
+
+async function sample(capacity: number, mode: 'steady' | 'full' | 'tiny' | 'filtered'): Promise<TerminalIoReport> {
+  const outcome = await runBuiltBenchmarkWorker<TerminalIoReport>({
+    worker: WORKER, args: [String(capacity), mode], timeoutMs: 120_000, exposeGc: true,
+  })
+  if (outcome.timedOut || outcome.signal !== null || outcome.exitCode !== 0 || outcome.report === undefined) {
+    throw new Error('terminal I/O worker failed: ' + JSON.stringify(outcome))
+  }
+  return outcome.report
+}
+
+it('bounds steady overflow cost as retained terminal capacity grows 32 times', async () => {
+  const small: TerminalIoReport[] = []
+  const large: TerminalIoReport[] = []
+  for (let attempt = 0; attempt < ATTEMPTS; attempt += 1) {
+    small.push(await sample(128 * 1024, 'steady'))
+    large.push(await sample(4 * MIB, 'steady'))
+  }
+  const capacityRatio = median(large.map(row => row.ingestMs)) / median(small.map(row => row.ingestMs))
+  const ingestBudgetMs = ciTimeBudget(EXPECTED_MS.steadyIngest)
+  const completeBudgetMs = ciTimeBudget(EXPECTED_MS.steadyComplete)
+  console.log(JSON.stringify({ scenario: 'terminal-steady', small, large, capacityRatio, ingestBudgetMs, completeBudgetMs }))
+  expect(capacityRatio).toBeLessThanOrEqual(MAX_CAPACITY_RATIO)
+  for (const rows of [small, large]) {
+    expect(median(rows.map(row => row.ingestMs))).toBeLessThanOrEqual(ingestBudgetMs)
+    expect(median(rows.map(row => row.completeMs))).toBeLessThanOrEqual(completeBudgetMs)
+    expect(Math.max(...rows.map(row => row.retainedHeapBytes))).toBeLessThanOrEqual(MAX_RETAINED_HEAP_BYTES)
+  }
+})
+
+it('bounds retained memory when five MiB arrives in sixteen-byte chunks', async () => {
+  const report = await sample(4 * MIB, 'tiny')
+  console.log(JSON.stringify({ scenario: 'terminal-tiny-chunks', report, heapBudgetBytes: MAX_RETAINED_HEAP_BYTES }))
+  expect(report.retainedHeapBytes).toBeLessThanOrEqual(MAX_RETAINED_HEAP_BYTES)
+})
+
+it('releases filtered OSC storage behind retained visible string slices', async () => {
+  const report = await sample(4 * MIB, 'filtered')
+  console.log(JSON.stringify({ scenario: 'terminal-filtered-chunks', report, heapBudgetBytes: MAX_RETAINED_HEAP_BYTES }))
+  expect(report.retainedHeapBytes).toBeLessThanOrEqual(MAX_RETAINED_HEAP_BYTES)
+})
+
+it('completes a five MiB terminal send with bounded retained output', async () => {
+  const samples: TerminalIoReport[] = []
+  for (let attempt = 0; attempt < ATTEMPTS; attempt += 1) samples.push(await sample(4 * MIB, 'full'))
+  const completeMedianMs = median(samples.map(row => row.completeMs))
+  const completeBudgetMs = ciTimeBudget(EXPECTED_MS.fullComplete)
+  console.log(JSON.stringify({ scenario: 'terminal-five-mib', samples, completeMedianMs, completeBudgetMs }))
+  expect(completeMedianMs).toBeLessThanOrEqual(completeBudgetMs)
+  expect(Math.max(...samples.map(row => row.retainedHeapBytes))).toBeLessThanOrEqual(MAX_RETAINED_HEAP_BYTES)
+})
diff --git a/benchmarks/terminal-io/terminal-io.worker.ts b/benchmarks/terminal-io/terminal-io.worker.ts
new file mode 100644
index 0000000000..257381a054
--- /dev/null
+++ b/benchmarks/terminal-io/terminal-io.worker.ts
@@ -0,0 +1,106 @@
+/** Terminal output ingestion and readiness with a deterministic provider boundary. */
+import { Buffer } from 'node:buffer'
+import { performance } from 'node:perf_hooks'
+import { Readable } from 'node:stream'
+import type { SubprocessOutcome, SubprocessTerminalHandle } from '@deepseek-ai/dsh-subprocess'
+import { assertBuiltBenchmarkRuntime } from '../support/built-worker.ts'
+import { LocalPtySession } from './session-adapter.ts'
+
+const MIB = 1024 * 1024
+const CHUNK_BYTES = 16 * 1024
+
+/** One fresh-session sample; retained heap includes the live session and returned output. */
+export interface TerminalIoReport {
+  mode: string
+  capacityBytes: number
+  chunkBytes: number
+  prefillBytes: number
+  timedBytes: number
+  ingestMs: number
+  completeMs: number
+  retainedHeapBytes: number
+  viewportBytes: number
+  readBytes: number
+  truncated: boolean
+}
+
+async function measure(capacityBytes: number, mode: string): Promise<TerminalIoReport> {
+  const chunkBytes = mode === 'filtered' ? 64 * 1024 : mode === 'tiny' ? 16 : CHUNK_BYTES
+  const chunk = Buffer.alloc(chunkBytes, 'x')
+  if (mode === 'filtered') {
+    // Each decoded callback has 56 KiB of discarded OSC followed by an 8 KiB string slice.
+    chunk.write('\x1b]0;', 0)
+    chunk[56 * 1024 - 1] = 7
+  }
+  const prefillBytes = mode === 'steady' ? capacityBytes : 0
+  const timedBytes = mode === 'filtered' ? 513 * chunkBytes : mode === 'steady' ? MIB : 5 * MIB
+  const output = new Readable({ read() {} })
+  const ended = Promise.withResolvers<SubprocessOutcome>()
+  const writeReady = Promise.withResolvers<void>()
+  const terminal: SubprocessTerminalHandle = {
+    pid: 1,
+    output,
+    done: ended.promise,
+    async write() { writeReady.resolve() },
+    async resize() {},
+    async inspectForeground() { return { processGroupId: 1, inputWaiting: false } },
+    async signalForeground() { return 1 },
+    async terminate() {
+      output.emit('end')
+      ended.resolve({ exitCode: 0, signal: null })
+      await ended.promise
+    },
+  }
+  global.gc?.()
+  const heapBefore = process.memoryUsage().heapUsed
+  const session = new LocalPtySession(terminal, {
+    backendType: 'shell', shellDialect: 'bash', shellPath: '/bin/bash', shellArgs: [],
+    rows: 40, cols: 160, scrollbackLines: 10_000, scrollbackMaxBytes: capacityBytes,
+    maxReadBytes: Math.min(256 * 1024, capacityBytes),
+    pollIntervalMs: 1, exactProbeAfterMs: 150, idleSilenceMs: 1,
+    handoffGraceMs: 1, timeoutMs: 120_000, disposeGraceMs: 1,
+  })
+  try {
+    if (prefillBytes > 0) {
+      const prefill = session.startSend({ text: 'prefill', submit: false })
+      await writeReady.promise
+      for (let bytes = 0; bytes < prefillBytes; bytes += chunkBytes) output.emit('data', chunk)
+      const ready = await prefill.done
+      if (ready.waitReason !== 'inferred_idle') throw new Error('prefill did not reach readiness')
+    }
+    const start = performance.now()
+    const operation = session.startSend({ text: '', submit: false })
+    for (let bytes = 0; bytes < timedBytes; bytes += chunkBytes) output.emit('data', chunk)
+    const ingestMs = performance.now() - start
+    const result = await operation.done
+    const read = session.read({ count: 10_000 })
+    const completeMs = performance.now() - start
+    if (result.waitReason !== 'inferred_idle' || !result.truncated || !read.truncated) {
+      throw new Error('output did not reach bounded ready endpoint')
+    }
+    const expectedBytes = Math.min(256 * 1024, capacityBytes)
+    if (Buffer.byteLength(result.viewport) !== expectedBytes || Buffer.byteLength(read.text) !== expectedBytes) {
+      throw new Error('bounded output endpoint has unexpected byte count')
+    }
+    global.gc?.()
+    return {
+      mode, capacityBytes, chunkBytes, prefillBytes, timedBytes, ingestMs, completeMs,
+      retainedHeapBytes: process.memoryUsage().heapUsed - heapBefore,
+      viewportBytes: Buffer.byteLength(result.viewport), readBytes: Buffer.byteLength(read.text),
+      truncated: result.truncated && read.truncated,
+    }
+  } finally {
+    await session.close('benchmark complete')
+    output.destroy()
+  }
+}
+
+assertBuiltBenchmarkRuntime(import.meta.url, {
+  '@deepseek-ai/dsh-terminal': import.meta.resolve('@deepseek-ai/dsh-terminal'),
+})
+const capacityBytes = Number(process.argv[2])
+const mode = process.argv[3]
+if (![128 * 1024, 4 * MIB].includes(capacityBytes) || (mode !== 'steady' && mode !== 'full' && mode !== 'tiny' && mode !== 'filtered')) {
+  throw new Error('usage: terminal-io.worker.js <131072|4194304> <steady|full|tiny|filtered>')
+}
+console.log(JSON.stringify(await measure(capacityBytes, mode)))
diff --git a/benchmarks/tsdown.config.ts b/benchmarks/tsdown.config.ts
index 2b7a7d2bb9..18e2928c0e 100644
--- a/benchmarks/tsdown.config.ts
+++ b/benchmarks/tsdown.config.ts
@@ -14,6 +14,13 @@ const shared = {
 
 /** Compile measured benchmark workers while keeping workspace packages on their built `lib` entries. */
 export default defineConfig([
+  {
+    ...shared,
+    entry: { 'terminal-io.worker': 'terminal-io/terminal-io.worker.ts' },
+    outDir: '.dsh-build/terminal-io',
+    clean: true,
+    tsconfig: 'tsconfig.host.json',
+  },
   {
     ...shared,
     entry: { 'reconnect.worker': 'active-stream-reconnect/reconnect.worker.client.ts' },
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 1ce0de7f1f..e223279d65 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: 134926329e9320e38b6370e45138cbfccb180baa
-config-catalog.zh.md: 60cfa69460173ddfd587a86349280c00486ec80a
+config-catalog.md: ca95f08dc7dd405422edeac13d716f2842d4388f
+config-catalog.zh.md: 91dc6b4e5d47776672f5f89a500460b7ef325b8a
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 134926329e..ca95f08dc7 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -1789,7 +1789,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/llm/plugin-package-inventory-deepseek/src/index.ts:31`](../packages/llm/plugin-package-inventory-deepseek/src/index.ts)
+Source: [`packages/llm/plugin-package-inventory-deepseek/src/index.ts:32`](../packages/llm/plugin-package-inventory-deepseek/src/index.ts)
 
 <a id="deepseek-aidsh-ptc-runtime-node"></a>
 
@@ -2026,7 +2026,7 @@ Requires: `deepseekLlmApiExtensions` · `sessions`
 ```ts config-catalog
 /** Session-log request contribution configuration. */
 export interface Config {
-  /** Contribute `dsh_session_log` to official DeepSeek requests. Defaults to `false`. */
+  /** Contribute `dsh_session_log` to official DeepSeek requests. Defaults to `true`. */
   enabled?: boolean
 }
 ```
@@ -3356,7 +3356,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/typert/loader/src/index.ts:47`](../packages/typert/loader/src/index.ts)
+Source: [`packages/typert/loader/src/index.ts:48`](../packages/typert/loader/src/index.ts)
 
 <a id="deepseek-aidsh-user-approval"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 60cfa69460..91dc6b4e5d 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -1791,7 +1791,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/llm/plugin-package-inventory-deepseek/src/index.ts:31`](../packages/llm/plugin-package-inventory-deepseek/src/index.ts)
+来源：[`packages/llm/plugin-package-inventory-deepseek/src/index.ts:32`](../packages/llm/plugin-package-inventory-deepseek/src/index.ts)
 
 <a id="deepseek-aidsh-ptc-runtime-node"></a>
 
@@ -2028,7 +2028,7 @@ export interface JsonRpcConfig {
 ```ts config-catalog
 /** Session-log request contribution configuration. */
 export interface Config {
-  /** Contribute `dsh_session_log` to official DeepSeek requests. Defaults to `false`. */
+  /** Contribute `dsh_session_log` to official DeepSeek requests. Defaults to `true`. */
   enabled?: boolean
 }
 ```
@@ -3358,7 +3358,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/typert/loader/src/index.ts:47`](../packages/typert/loader/src/index.ts)
+来源：[`packages/typert/loader/src/index.ts:48`](../packages/typert/loader/src/index.ts)
 
 <a id="deepseek-aidsh-user-approval"></a>
 
diff --git a/docs/deepseek-llm-api-wire-extensions.i18n.yaml b/docs/deepseek-llm-api-wire-extensions.i18n.yaml
index 388ee7f27c..7329ae0f17 100644
--- a/docs/deepseek-llm-api-wire-extensions.i18n.yaml
+++ b/docs/deepseek-llm-api-wire-extensions.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 docs/deepseek-llm-api-wire-extensions.md
-deepseek-llm-api-wire-extensions.md: f0262e5577c4500318f6b67d63d752116790fe0b
-deepseek-llm-api-wire-extensions.zh.md: 88091f6a27af2ad7be44fd74280d2f8c71f9e3ca
+deepseek-llm-api-wire-extensions.md: f45508f375d3e624b4d5eded26393a737c3a0907
+deepseek-llm-api-wire-extensions.zh.md: ff72d62a9cdc2a33f6d6fd5fb08975b73839cae7
diff --git a/docs/deepseek-llm-api-wire-extensions.md b/docs/deepseek-llm-api-wire-extensions.md
index f0262e5577..f45508f375 100644
--- a/docs/deepseek-llm-api-wire-extensions.md
+++ b/docs/deepseek-llm-api-wire-extensions.md
@@ -73,7 +73,7 @@ An enabled inventory with no qualifying entries sends `packages: []`; disabling
 
 ## `dsh_session_log`
 
-[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.md) contributes one contiguous suffix of the canonical Session log. The field is disabled by default. When enabled, it applies to a request with a live Session and at least one event; a direct request, a stale Session id, or an empty log omits the field. The examples below use logical Session format 2 only to illustrate the wire fields; they do not identify the [current writer format](session-format-status.md).
+[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.md) contributes one contiguous suffix of the canonical Session log. The field is enabled by default. It applies to a request with a live Session and at least one event; a direct request, a stale Session id, or an empty log omits the field, and a composition disables it with `enabled: false`. The examples below use logical Session format 2 only to illustrate the wire fields; they do not identify the [current writer format](session-format-status.md).
 
 ```json
 {
@@ -157,6 +157,6 @@ Transport and non-2xx failures append no watermark. A crash after endpoint accep
 
 ## Exposure and receiver requirements
 
-The request headers expose the Harness application version, one anonymous Harness-home identity, and an optional Session identity. `dsh_plugin_packages` exposes active npm package names and versions. When enabled, `dsh_session_log` may expose the Session working directory, system-prompt snapshots, user and Assistant content, embedded Assistant streams, failed-attempt output, tool arguments and results, compaction summaries, feedback, and plugin-owned events. Adapter API keys are not Session events and therefore do not enter the field. A gateway selected through `baseURL` receives the same values as the official endpoint.
+The request headers expose the Harness application version, one anonymous Harness-home identity, and an optional Session identity. `dsh_plugin_packages` exposes active npm package names and versions. Unless a composition disables it, `dsh_session_log` may expose the Session working directory, system-prompt snapshots, user and Assistant content, embedded Assistant streams, failed-attempt output, tool arguments and results, compaction summaries, feedback, and plugin-owned events. Adapter API keys are not Session events and therefore do not enter the field. A gateway selected through `baseURL` receives the same values as the official endpoint.
 
 Receivers address extension fields by name, dispatch each field by its own `version`, preserve distinct package versions, and ignore JSON member ordering. A session-log receiver validates the contiguous sequence range before interpreting event types. An unrecognized canonical event without `ignorable: true` prevents lossless reconstruction. The base request remains usable without either the registry or a particular contribution; field absence means that contribution did not apply to that request.
diff --git a/docs/deepseek-llm-api-wire-extensions.zh.md b/docs/deepseek-llm-api-wire-extensions.zh.md
index 88091f6a27..ff72d62a9c 100644
--- a/docs/deepseek-llm-api-wire-extensions.zh.md
+++ b/docs/deepseek-llm-api-wire-extensions.zh.md
@@ -73,7 +73,7 @@
 
 ## `dsh_session_log`
 
-[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.zh.md) 贡献权威会话日志的一段连续后缀。该字段默认禁用。启用后，它适用于携带存活会话且至少存在一个事件的请求；直接请求、陈旧会话 id 或空日志会省略该字段。下方示例使用逻辑 Session 格式 2 仅为说明协议字段，并不标识[当前写入格式](session-format-status.zh.md)。
+[`@deepseek-ai/dsh-session-log-deepseek`](../packages/session/session-log-deepseek/README.zh.md) 贡献权威会话日志的一段连续后缀。该字段默认启用。它适用于携带存活会话且至少存在一个事件的请求；直接请求、陈旧会话 id 或空日志会省略该字段，组合可用 `enabled: false` 禁用它。下方示例使用逻辑 Session 格式 2 仅为说明协议字段，并不标识[当前写入格式](session-format-status.zh.md)。
 
 ```json
 {
@@ -157,6 +157,6 @@
 
 ## 暴露内容与接收方要求
 
-请求标头会暴露 Harness 应用版本、一个匿名 Harness-home 身份和可选的会话身份。`dsh_plugin_packages` 会暴露存活 npm 包的名称与版本。启用后，`dsh_session_log` 可能暴露会话工作目录、系统提示词快照、用户与 Assistant 内容、嵌入式 Assistant stream、失败 attempt 输出、工具参数与结果、压缩摘要、反馈和插件持有的事件。适配器 API key 不是会话事件，因此不会进入该字段。通过 `baseURL` 选择的网关会收到与官方端点相同的值。
+请求标头会暴露 Harness 应用版本、一个匿名 Harness-home 身份和可选的会话身份。`dsh_plugin_packages` 会暴露存活 npm 包的名称与版本。除非组合禁用该字段，`dsh_session_log` 可能暴露会话工作目录、系统提示词快照、用户与 Assistant 内容、嵌入式 Assistant stream、失败 attempt 输出、工具参数与结果、压缩摘要、反馈和插件持有的事件。适配器 API key 不是会话事件，因此不会进入该字段。通过 `baseURL` 选择的网关会收到与官方端点相同的值。
 
 接收方按名称定位扩展字段，按各字段自己的 `version` 分派，保留不同的包版本，并忽略 JSON 成员顺序。会话日志接收方必须先校验连续序号范围，再解释事件类型。遇到不带 `ignorable: true` 的未知权威事件时，接收方无法进行无损重建。即使缺少注册表或某项贡献，基础请求仍然可用；字段缺失表示该项贡献不适用于本次请求。
diff --git a/docs/subsystems/feedback.i18n.yaml b/docs/subsystems/feedback.i18n.yaml
index 621fcf80ff..96cf13ee20 100644
--- a/docs/subsystems/feedback.i18n.yaml
+++ b/docs/subsystems/feedback.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 docs/subsystems/feedback.md
-feedback.md: e153047bcc260bcd06847b42eb6b983ac9247d03
-feedback.zh.md: 60263ea4509c0b10ed9f57d13f1564ced1e066c7
+feedback.md: 1fa8631c2c262351e320d0e8642bdad96474214d
+feedback.zh.md: 2417ade68447a9b4fe08c7433b7ce779044b99c5
diff --git a/docs/subsystems/feedback.md b/docs/subsystems/feedback.md
index e153047bcc..1fa8631c2c 100644
--- a/docs/subsystems/feedback.md
+++ b/docs/subsystems/feedback.md
@@ -290,7 +290,7 @@ Successful message-feedback mutations await canonical persistence: live operatio
 
 Plugin disposal closes operation admission and drains accepted per-Session queue work.
 
-When explicitly enabled, [`session-log-deepseek`](../../packages/session/session-log-deepseek/README.md) carries feedback as part of the ordinary `dsh_session_log` suffix on subsequent eligible DeepSeek requests. Recording feedback does not trigger an LLM request or a separate `dsh_feedback` upload. For non-DeepSeek routes, the [OTel backend](../../packages/session/session-telemetry-otel/README.md) can release the canonical prefix through recorded feedback. The command acknowledgement confirms recording and identifies the Session and anonymous user; it reports neither telemetry policy nor delivery.
+By default, [`session-log-deepseek`](../../packages/session/session-log-deepseek/README.md) carries feedback as part of the ordinary `dsh_session_log` suffix on subsequent eligible DeepSeek requests; a composition disables it with `enabled: false`. Recording feedback does not trigger an LLM request or a separate `dsh_feedback` upload. For non-DeepSeek routes, the [OTel backend](../../packages/session/session-telemetry-otel/README.md) can release the canonical prefix through recorded feedback. The command acknowledgement confirms recording and identifies the Session and anonymous user; it reports neither telemetry policy nor delivery.
 
 ## Web surface
 
diff --git a/docs/subsystems/feedback.zh.md b/docs/subsystems/feedback.zh.md
index 60263ea450..2417ade684 100644
--- a/docs/subsystems/feedback.zh.md
+++ b/docs/subsystems/feedback.zh.md
@@ -290,7 +290,7 @@ fork 种子可以包含父 Session 的反馈事件，但 payload 保留父级 `s
 
 插件释放会关闭操作接纳，并排空已进入各 Session 队列的工作。
 
-显式启用后，[`session-log-deepseek`](../../packages/session/session-log-deepseek/README.zh.md) 会在后续符合条件的 DeepSeek 请求中，把反馈作为普通 `dsh_session_log` 后缀的一部分传送。记录反馈不会触发 LLM 请求，也不会单独上传 `dsh_feedback`。对于非 DeepSeek 路由，[OTel 后端](../../packages/session/session-telemetry-otel/README.zh.md)可以将权威日志前缀释放至已记录的反馈。命令确认文本确认记录并标识 Session 与匿名用户，不报告遥测策略或投递结果。
+默认情况下，[`session-log-deepseek`](../../packages/session/session-log-deepseek/README.zh.md) 会在后续符合条件的 DeepSeek 请求中，把反馈作为普通 `dsh_session_log` 后缀的一部分传送；组合可用 `enabled: false` 禁用它。记录反馈不会触发 LLM 请求，也不会单独上传 `dsh_feedback`。对于非 DeepSeek 路由，[OTel 后端](../../packages/session/session-telemetry-otel/README.zh.md)可以将权威日志前缀释放至已记录的反馈。命令确认文本确认记录并标识 Session 与匿名用户，不报告遥测策略或投递结果。
 
 ## Web 界面
 
diff --git a/docs/subsystems/slots.i18n.yaml b/docs/subsystems/slots.i18n.yaml
index 3032c0e259..31589f7c45 100644
--- a/docs/subsystems/slots.i18n.yaml
+++ b/docs/subsystems/slots.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 docs/subsystems/slots.md
-slots.md: f43262dc586daa5efb5881fff968fc57b9f5f1d5
-slots.zh.md: 7452454b1f6a0645047cf08091b548169e4932d4
+slots.md: be45c83478a198320138040294e0c1e94c9bb013
+slots.zh.md: fe4c6efa806017e38d3d43ad0991a44f8b5dada1
diff --git a/docs/subsystems/slots.md b/docs/subsystems/slots.md
index f43262dc58..be45c83478 100644
--- a/docs/subsystems/slots.md
+++ b/docs/subsystems/slots.md
@@ -166,7 +166,8 @@ root
 ├─ rightbar
 │  └─ rightbar.session
 │     ├─ sidebar.right.pane.tab
-│     │  └─ sidebar.right.tab.guide
+│     │  ├─ sidebar.right.tab.guide
+│     │  └─ sidebar.right.tab.guide.entry
 │     ├─ sidebar.right.pane.tab.title
 │     └─ sidebar.right.tab.menu.item
 └─ shell.overlay
diff --git a/docs/subsystems/slots.zh.md b/docs/subsystems/slots.zh.md
index 7452454b1f..fe4c6efa80 100644
--- a/docs/subsystems/slots.zh.md
+++ b/docs/subsystems/slots.zh.md
@@ -166,7 +166,8 @@ root
 ├─ rightbar
 │  └─ rightbar.session
 │     ├─ sidebar.right.pane.tab
-│     │  └─ sidebar.right.tab.guide
+│     │  ├─ sidebar.right.tab.guide
+│     │  └─ sidebar.right.tab.guide.entry
 │     ├─ sidebar.right.pane.tab.title
 │     └─ sidebar.right.tab.menu.item
 └─ shell.overlay
diff --git a/docs/user/guide/python-sdk.i18n.yaml b/docs/user/guide/python-sdk.i18n.yaml
index 476fb26576..00d2839352 100644
--- a/docs/user/guide/python-sdk.i18n.yaml
+++ b/docs/user/guide/python-sdk.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 docs/user/guide/python-sdk.md
-python-sdk.md: 6fde258d9f4f3e8ba1fd41537129ba5b8f02fd58
-python-sdk.zh.md: f50fd6d2bd37e3dc203b519e07d0df4098cab0c7
+python-sdk.md: 2cb01ffa19d173231902c5c816929fa6b4d499f0
+python-sdk.zh.md: 3db859116530e51a7c7478ab222cbc4d2435dbf2
diff --git a/docs/user/guide/python-sdk.md b/docs/user/guide/python-sdk.md
index 6fde258d9f..2cb01ffa19 100644
--- a/docs/user/guide/python-sdk.md
+++ b/docs/user/guide/python-sdk.md
@@ -157,7 +157,7 @@ Pass `patches=("/absolute/path/to/editor.patch.yml",)` when constructing `DeepSe
 | Runtime context and compaction | Absent |
 | Session persistence | Uncompressed JSONL under `<dsh_home>/sessions` |
 
-The profile's sole bundle inserts the complete tree over an empty root and does not include `dsh-base`; later base-profile tools therefore cannot appear implicitly. It contains the SDK protocol, one environment-configured DeepSeek adapter, local execution, and persistence, while filesystem tools, settings, managed credentials, telemetry, Web tools, subagents, local instruction discovery, and compaction are absent. It pins `danger-full-access`, so the platform-selected persistent shell can modify any path visible to the runtime; use a disposable checkout or container.
+The profile's sole bundle inserts the complete tree over an empty root and does not include `dsh-base`; later base-profile tools therefore cannot appear implicitly. It contains the SDK protocol, one environment-configured DeepSeek adapter, local execution, and persistence, while filesystem tools, settings, managed credentials, OTel telemetry, Web tools, subagents, local instruction discovery, and compaction are absent. The [DeepSeek session-log contributor](../../../packages/session/session-log-deepseek/README.md) uploads complete unaccepted log suffixes with DeepSeek requests by default; set `session-log-deepseek.enabled: false` in a profile patch to disable it. It pins `danger-full-access`, so the platform-selected persistent shell can modify any path visible to the runtime; use a disposable checkout or container.
 
 The installed wheel still packages the full `web` profile and frontend assets. Run `dsh web` against an explicit `DSH_HOME` when a Python SDK deployment also needs the browser application; `web` is a separate CLI application and cannot serve a Python SDK client.
 
diff --git a/docs/user/guide/python-sdk.zh.md b/docs/user/guide/python-sdk.zh.md
index f50fd6d2bd..3db8591165 100644
--- a/docs/user/guide/python-sdk.zh.md
+++ b/docs/user/guide/python-sdk.zh.md
@@ -157,7 +157,7 @@ dsh plugin --profile sdk-minimal add file:C:/work/my-plugin-bundle
 | 运行时上下文与 compaction | 不存在 |
 | 会话持久化 | `<dsh_home>/sessions` 下的未压缩 JSONL |
 
-该 profile 的唯一组合包会在空根之上插入完整配置树，且不包含 `dsh-base`，因此基础 profile 以后新增的工具不会隐式出现。它包含 SDK 协议、一个由环境配置的 DeepSeek 适配器、本地执行与持久化；文件系统工具、settings、托管凭据、遥测、Web 工具、subagent、本地指令发现和 compaction 均不存在。它固定使用 `danger-full-access`，因此按平台选择的持久 shell 可以修改运行时可见的任何路径；应使用一次性 checkout 或容器。
+该 profile 的唯一组合包会在空根之上插入完整配置树，且不包含 `dsh-base`，因此基础 profile 以后新增的工具不会隐式出现。它包含 SDK 协议、一个由环境配置的 DeepSeek 适配器、本地执行与持久化；文件系统工具、settings、托管凭据、OTel 遥测、Web 工具、subagent、本地指令发现和 compaction 均不存在。[DeepSeek 会话日志贡献器](../../../packages/session/session-log-deepseek/README.zh.md)默认随 DeepSeek 请求上传完整的未接受日志后缀；在 profile patch 中设置 `session-log-deepseek.enabled: false` 可将其关闭。它固定使用 `danger-full-access`，因此按平台选择的持久 shell 可以修改运行时可见的任何路径；应使用一次性 checkout 或容器。
 
 已安装 wheel 仍会打包完整 `web` profile 与前端产物。如果 Python SDK 部署还需要浏览器应用，请针对显式 `DSH_HOME` 运行 `dsh web`；`web` 是独立 CLI 应用，不能为 Python SDK client 提供服务。
 
diff --git a/package.json b/package.json
index 15be3993cb..fbedba9f1f 100644
--- a/package.json
+++ b/package.json
@@ -123,7 +123,7 @@
     "docs:build": "tsx website/build.ts && pnpm run verify-doc-site-fragments",
     "docs:build:mpa": "tsx website/build.ts --mpa && pnpm run verify-doc-site-fragments",
     "docs:preview": "pnpm --filter @deepseek-ai/website run preview",
-    "docs:check": "pnpm exec vitest run scripts/project-doc-site.spec.ts scripts/verify-doc-site-fragments.spec.ts && pnpm run docs:build",
+    "docs:check": "pnpm exec vitest run scripts/project-doc-site.spec.ts scripts/verify-doc-site-fragments.spec.ts website/tests/mermaid-viewer.spec.ts && pnpm run docs:build",
     "website:dev": "pnpm run docs:dev",
     "website:build": "pnpm run docs:build",
     "verify-package-readme-limitations": "tsx scripts/verify-package-readme-limitations.ts",
diff --git a/packages/api/terminal-controller/README.i18n.yaml b/packages/api/terminal-controller/README.i18n.yaml
index 77ec50b007..fd27b854f1 100644
--- a/packages/api/terminal-controller/README.i18n.yaml
+++ b/packages/api/terminal-controller/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 packages/api/terminal-controller/README.md
-README.md: 21bcfb335246dc4b95a3cd70993c8444ad7de057
-README.zh.md: 6ba88bcecc55c850cf477257c8055b5babae9b52
+README.md: 7bcd04ad2848b4f263aaff21d0bee5aea2333343
+README.zh.md: 3db761f32c0e7c99fa622dd7adb62f3ac301b766
diff --git a/packages/api/terminal-controller/README.md b/packages/api/terminal-controller/README.md
index 21bcfb3352..7bcd04ad28 100644
--- a/packages/api/terminal-controller/README.md
+++ b/packages/api/terminal-controller/README.md
@@ -52,7 +52,7 @@ The latest attachment owns input and resize. Detachment releases input control w
 
 Client views keep the association between sidebar tabs and terminal identities in memory. Recovery queries the Host for retained terminals; a new view may create a process, while a recovered view reports a missing target without creating a replacement. The Client model acknowledges screen writes after the browser emulator processes them, serializes input and ignores stale attachment responses. Client-owned errors carry locale keys. Plugin disposal awaits active and previously detached output streams without closing Host processes.
 
-New views wait for explicit shell selection and start. The last selected shell path is stored under `dsh.terminal.shell` in origin-scoped localStorage. A saved path is preselected only while Host discovery still lists it; otherwise the current default is selected. Storage failures do not prevent startup. Restoring existing terminals neither reads this preference nor discovers shells.
+New views start automatically, using an explicit guide selection or the remembered available shell. The last selected shell path is stored under `dsh.terminal.shell` in origin-scoped localStorage. Default launches verify the saved path through Host discovery and fall back to the current default when it is absent. The guide records a selection before opening its tab; each new tab retains its own chosen path and allocation identity. Storage failures do not prevent startup. Restoring existing terminals neither reads this preference nor discovers shells.
 
 Closing saves an unfinished cleanup request before releasing the tab, then awaits Host cleanup in the background. A failure exposes a retry notification. Each request has its own terminal-ID localStorage key and is removed after successful cleanup or a definitive `session/not-found` response; startup retries saved requests. Transport failures retain the request. This stores cleanup intent, not sidebar layout, open-tab mappings, selected tabs or process PIDs. If browser storage is unavailable, cleanup remains usable in memory but cannot be recovered after reload.
 
diff --git a/packages/api/terminal-controller/README.zh.md b/packages/api/terminal-controller/README.zh.md
index 6ba88bcecc..3db761f32c 100644
--- a/packages/api/terminal-controller/README.zh.md
+++ b/packages/api/terminal-controller/README.zh.md
@@ -52,7 +52,7 @@ Host 通过 `ctx.subprocess.spawnTerminal` 创建 `TERM=xterm-256color` 的终
 
 Client 视图只在内存中关联侧栏标签页与终端标识。恢复操作查询 Host 保留的终端；新视图可以创建进程，恢复视图在目标缺失时显示错误，不创建替代进程。Client 模型在浏览器完成屏幕解析后确认帧，按序发送输入，并忽略旧连接迟到的响应。 Client 自产错误携带本地化键。插件卸载等待活跃及先前断开的输出流结束，不关闭 Host 进程。
 
-新视图等待用户选择 shell 并启动。上次选择的 shell 路径保存在当前站点 localStorage 的 `dsh.terminal.shell` 中。仅当 Host 探测仍列出该路径时才预选它，否则选择当前默认项。存储失败不影响启动。恢复已有终端既不读取这一偏好，也不探测 shell。
+新视图自动启动，使用开始页明确选中的 shell，或上次选择且仍可用的 shell。上次选择的路径保存在当前站点 localStorage 的 `dsh.terminal.shell` 中。默认启动通过 Host 探测验证保存的路径，不可用时回到当前默认项。开始页在打开标签页前记录选择，每个新标签页保留自己的 shell 路径和分配身份。存储失败不影响启动。恢复已有终端既不读取这一偏好，也不探测 shell。
 
 关闭时先保存未完成的清理请求并释放标签页，再在后台等待 Host 清理。失败时提供重试通知。每个请求使用独立的终端 ID localStorage key，清理成功或收到明确的 `session/not-found` 响应后删除；启动时重试已保存的请求。传输失败时保留请求。保存的是清理意图，不是侧栏布局、打开标签页映射、选中标签页或进程 PID。浏览器存储不可用时，内存中的清理仍可工作，但刷新后无法恢复该请求。
 
diff --git a/packages/api/terminal-controller/src/client/index.ts b/packages/api/terminal-controller/src/client/index.ts
index 1daec7edd8..3094228e88 100644
--- a/packages/api/terminal-controller/src/client/index.ts
+++ b/packages/api/terminal-controller/src/client/index.ts
@@ -6,7 +6,8 @@ import type {} from '@deepseek-ai/dsh-api-gateway/client'
 import { TerminalView, type TerminalRemote } from './model.ts'
 import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { randomUUID } from '@deepseek-ai/dsh-util-crypto'
-import type { WebTerminalId, WebTerminalInfo } from '../types.ts'
+import type { TerminalShell, WebTerminalId, WebTerminalInfo } from '../types.ts'
+import { preferredShell, rememberShell } from './shell-preference.ts'
 import { TerminalCloseRequests, type TerminalCloseRequest } from './close-requests.ts'
 
 export type { TerminalView, TerminalViewState, TerminalViewIssue, TerminalRenderFrame, TerminalRemote } from './model.ts'
@@ -18,6 +19,12 @@ declare module '@deepseek-ai/cordis' {
   }
 }
 
+/** Host-discovered shell menu with the browser's remembered available choice. */
+export interface TerminalLaunchShells {
+  readonly shells: readonly TerminalShell[]
+  readonly selectedShell: string | undefined
+}
+
 /** A failed background close that can be retried without restoring its tab. */
 export interface TerminalCloseFailure {
   readonly id: WebTerminalId
@@ -55,21 +62,41 @@ export class ClientTerminals extends Service {
    * @param sessionId - owning Session.
    * @param key - sidebar occurrence key.
    * @param terminalId - existing Host identity when restoring a listed terminal.
+   * @param shellPath - explicit shell for a new terminal; restored terminals retain their own shell.
    * @returns its observable state and terminal commands.
    */
-  view(sessionId: SessionId, key: string, terminalId?: WebTerminalId): TerminalView {
+  view(sessionId: SessionId, key: string, terminalId?: WebTerminalId, shellPath?: string): TerminalView {
     let views = this.views.get(sessionId)
     if (views === undefined) { views = new Map(); this.views.set(sessionId, views) }
     let view = views.get(key)
     if (view === undefined) {
       const id = terminalId ?? randomUUID() as WebTerminalId
-      view = new TerminalView(sessionId, this.remote, this.ctx.remote, id, terminalId === undefined)
+      view = new TerminalView(sessionId, this.remote, this.ctx.remote, id, terminalId === undefined, shellPath)
       views.set(key, view)
       void view.refresh()
     }
     return view
   }
 
+  /**
+   * Discover available launch choices on demand without allocating a PTY.
+   * @param sessionId - target Session.
+   * @param signal - the menu request lifetime.
+   * @returns installed shells and the currently usable browser preference.
+   */
+  async launchShells(sessionId: SessionId, signal: AbortSignal): Promise<TerminalLaunchShells> {
+    const result = await this.remote.shells(sessionId, signal)
+    if (!result.ok) throw new Error(result.error.message)
+    const previous = preferredShell()
+    return { shells: result.value, selectedShell: result.value.find(shell => shell.path === previous)?.path ?? result.value[0]?.path }
+  }
+
+  /**
+   * Remember the guide selection before allocating its terminal tab.
+   * @param path - shell selected from Host discovery.
+   */
+  selectShell(path: string): void { rememberShell(path) }
+
   /**
    * Save a close intent and release the tab immediately; cleanup outlives DOM unmount and reload.
    * @param sessionId - owning Session.
diff --git a/packages/api/terminal-controller/src/client/model.ts b/packages/api/terminal-controller/src/client/model.ts
index f6c1a350ad..11fcde4ff9 100644
--- a/packages/api/terminal-controller/src/client/model.ts
+++ b/packages/api/terminal-controller/src/client/model.ts
@@ -7,7 +7,7 @@ import { RemoteError, remoteErrorOf, type RemoteResult } from '@deepseek-ai/dsh-
 import type {} from '@deepseek-ai/dsh-api-terminal-controller/remote'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type {
-  TerminalShell, TerminalAttachmentId, TerminalEnvironment, TerminalFrame,
+  TerminalAttachmentId, TerminalEnvironment, TerminalFrame,
   WebTerminalId, WebTerminalInfo,
 } from '../types.ts'
 
@@ -36,9 +36,7 @@ export interface TerminalRenderFrame {
 
 /** Observable state of one sidebar occurrence. */
 export interface TerminalViewState {
-  readonly phase: 'idle' | 'loading' | 'selecting' | 'creating' | 'connecting' | 'connected' | 'disconnected' | 'closing' | 'closed' | 'failed'
-  readonly shells?: readonly TerminalShell[] | undefined
-  readonly selectedShell?: string | undefined
+  readonly phase: 'idle' | 'loading' | 'creating' | 'connecting' | 'connected' | 'disconnected' | 'closing' | 'closed' | 'failed'
   readonly environment?: TerminalEnvironment | undefined
   readonly title?: string | undefined
   readonly info?: WebTerminalInfo | undefined
@@ -71,6 +69,7 @@ export class TerminalView {
    * @param gateway - reconnecting stream factory.
    * @param id - Host terminal identity, reused when recovering an item from its Session list.
    * @param createWhenMissing - allow allocation only for a new tab, never a listed terminal.
+   * @param shellPath - explicit shell chosen at the guide; omission uses the remembered available shell.
    */
   constructor(
     private readonly sessionId: SessionId,
@@ -78,10 +77,11 @@ export class TerminalView {
     private readonly gateway: Pick<ClientRemote, '$stream'>,
     readonly id: WebTerminalId,
     private readonly createWhenMissing = true,
+    private readonly shellPath?: string,
   ) {}
 
   /**
-   * Attach the DOM lifetime, loading shell choices or reconnecting the saved process.
+   * Attach the DOM lifetime, starting the chosen shell or reconnecting the saved process.
    * @returns a detach callback that leaves the terminal process alive.
    */
   mount(): () => void {
@@ -113,49 +113,29 @@ export class TerminalView {
       const info = valueOf(available).find(item => item.id === this.id)
       if (info !== undefined) this.adopt(info)
       else if (this.createWhenMissing) {
-        const shells = valueOf(await this.remote.shells(this.sessionId, this.lifetime.signal))
+        let path = this.shellPath
+        if (path === undefined) {
+          const shells = valueOf(await this.remote.shells(this.sessionId, this.lifetime.signal))
+          const previous = preferredShell()
+          path = shells.find(shell => shell.path === previous)?.path ?? shells[0]?.path
+        }
         if (this.stopped()) return
-        const previous = this.state.getSnapshot().selectedShell ?? preferredShell()
-        const selectedShell = shells.find(shell => shell.path === previous)?.path ?? shells[0]?.path
-        this.patch({ phase: 'selecting', shells, selectedShell })
+        if (path !== undefined) rememberShell(path)
+        await this.create(valueOf(environment), path)
       }
       else throw new TerminalViewError('missingTerminal')
     })().catch((error: unknown) => { this.fail(error) }).finally(() => { this.loading = undefined })
     return this.loading
   }
 
-  /**
-   * Select and remember one verified shell before starting the terminal.
-   * @param path - executable path offered by Host discovery.
-   */
-  selectShell(path: string): void {
-    const state = this.state.getSnapshot()
-    if (state.phase === 'selecting' && state.shells?.some(shell => shell.path === path)) {
-      this.patch({ selectedShell: path })
-      rememberShell(path)
-    }
-  }
-
-  /**
-   * Start the selected shell once; failed attempts retain their selection for retry.
-   * @returns after allocation settles; failures are exposed in observable state.
-   */
-  start(): Promise<void> {
-    if (this.creation !== undefined) return this.creation
-    const state = this.state.getSnapshot()
-    if (state.phase !== 'selecting' || state.environment === undefined || state.selectedShell === undefined
-      || this.closing !== undefined || this.lifetime.signal.aborted) return Promise.resolve()
-    rememberShell(state.selectedShell)
-    return this.create(state.environment, state.selectedShell)
-  }
-
   private stopped(): boolean { return this.lifetime.signal.aborted || this.closing !== undefined }
 
-  private async create(environment: TerminalEnvironment, shellPath: string): Promise<void> {
+  private async create(environment: TerminalEnvironment, shellPath?: string): Promise<void> {
     this.patch({ phase: 'creating', error: undefined, issue: undefined })
     this.creation = (async () => {
       const info = valueOf(await this.remote.create(this.sessionId, {
-        id: this.id, shellPath, cols: Math.min(80, environment.maxCols), rows: Math.min(24, environment.maxRows),
+        id: this.id, ...shellPath === undefined ? {} : { shellPath },
+        cols: Math.min(80, environment.maxCols), rows: Math.min(24, environment.maxRows),
       }, this.lifetime.signal))
       if (!this.lifetime.signal.aborted) {
         this.adopt(info)
diff --git a/packages/api/terminal-controller/tests/model.client.spec.ts b/packages/api/terminal-controller/tests/model.client.spec.ts
index ac1a7243f9..9d1bc27189 100644
--- a/packages/api/terminal-controller/tests/model.client.spec.ts
+++ b/packages/api/terminal-controller/tests/model.client.spec.ts
@@ -62,7 +62,6 @@ function fixture(prepareStream?: <Item>(stream: RemoteStream<Item>) => void) {
 async function mount(model: TerminalView) {
   const detach = model.mount()
   await model.refresh()
-  await model.start()
   return detach
 }
 
@@ -436,7 +435,6 @@ it('classifies a discovery carrier failure as disconnected and supports explicit
   expect(model.state.getSnapshot()).toMatchObject({ phase: 'disconnected', error: 'offline' })
   expect(remote.create).not.toHaveBeenCalled()
   await model.refresh()
-  await model.start()
   expect(model.state.getSnapshot().info?.id).toBe(info.id)
   expect(remote.create).toHaveBeenCalledOnce()
 })
@@ -449,14 +447,12 @@ it('retains state when disposal overtakes successful allocation or a failed disc
     if (operation === 'creation') vi.mocked(remote.create).mockReturnValueOnce(creation.promise)
     else vi.mocked(remote.environment).mockReturnValueOnce(discovery.promise)
     const loading = model.refresh()
-    const starting = operation === 'creation' ? loading.then(() => model.start()) : undefined
     if (operation === 'creation') await expect.poll(() => remote.create).toHaveBeenCalledOnce()
     await model.dispose()
     const before = model.state.getSnapshot()
     if (operation === 'creation') creation.resolve(success(info))
     else discovery.reject(new Error('late discovery failure'))
     await loading
-    await starting
     expect(model.state.getSnapshot()).toBe(before)
     expect(remote.follow).not.toHaveBeenCalled()
   }
@@ -560,7 +556,6 @@ it('exposes a localized quota error and clears it after a successful retry', asy
   const { model, remote } = fixture()
   vi.mocked(remote.create).mockResolvedValueOnce({ ok: false, error: new RemoteError('terminal/limit-reached', 'Session terminal limit reached', { limit: 8 }) })
   await model.refresh()
-  await model.start()
   expect(model.state.getSnapshot()).toMatchObject({ phase: 'failed', issue: 'terminalLimit' })
   await connected(model)
   expect(model.state.getSnapshot()).toMatchObject({ phase: 'connected', issue: undefined, error: undefined })
diff --git a/packages/api/terminal-controller/tests/recovery.client.spec.ts b/packages/api/terminal-controller/tests/recovery.client.spec.ts
index 3839e2024a..888e4ecf0b 100644
--- a/packages/api/terminal-controller/tests/recovery.client.spec.ts
+++ b/packages/api/terminal-controller/tests/recovery.client.spec.ts
@@ -59,7 +59,7 @@ function fixture() {
   return { remote, view, service }
 }
 
-it('waits for shell selection and deduplicates overlapping starts', async () => {
+it('starts automatically and deduplicates overlapping mounts and refreshes', async () => {
   const h = fixture()
   const model = h.view()
   const creation = Promise.withResolvers<RemoteResult<WebTerminalInfo>>()
@@ -67,14 +67,11 @@ it('waits for shell selection and deduplicates overlapping starts', async () =>
   model.mount()
   const loading = model.refresh()
   expect(model.refresh()).toBe(loading)
-  await loading
-  expect(h.remote.create).not.toHaveBeenCalled()
-  const starting = model.start()
+  await expect.poll(() => h.remote.create).toHaveBeenCalledOnce()
   const remounting = model.refresh()
-  void model.start()
   expect(vi.mocked(h.remote.create).mock.calls[0]?.[1]).toEqual({ id: info.id, shellPath: info.shell.path, cols: 80, rows: 24 })
   creation.resolve(success(info))
-  await starting
+  await loading
   await remounting
   await expect.poll(() => model.state.getSnapshot().writable).toBe(true)
   expect(h.remote.create).toHaveBeenCalledOnce()
@@ -111,10 +108,8 @@ it('retries lost create acknowledgements with the saved id and closes after a re
   const model = h.view()
   vi.mocked(h.remote.create).mockResolvedValueOnce(failure('response lost'))
   await model.refresh()
-  await model.start()
   expect(model.state.getSnapshot().error).toBe('response lost')
   await model.refresh()
-  await model.start()
   expect(vi.mocked(h.remote.create).mock.calls.map(call => call[1].id)).toEqual([info.id, info.id])
   await model.close()
   expect(h.remote.close).toHaveBeenCalledWith(sessionId, info.id)
@@ -126,8 +121,7 @@ it('waits for an in-flight creation while close detaches immediately and prevent
   const creation = Promise.withResolvers<RemoteResult<WebTerminalInfo>>()
   vi.mocked(h.remote.create).mockReturnValueOnce(creation.promise)
   const unmount = model.mount()
-  await model.refresh()
-  const starting = model.start()
+  const starting = model.refresh()
   await expect.poll(() => vi.mocked(h.remote.create).mock.calls.length).toBe(1)
   const closing = model.close()
   expect(model.close()).toBe(closing)
@@ -330,14 +324,14 @@ it('saves close intents without persisting any active terminal or sidebar state'
   const model = service.view(sessionId, 'new-tab')
   await model.refresh()
   expect(model.id).toMatch(/^[0-9a-f-]{36}$/)
-  expect(data.size).toBe(0)
+  expect([...data.entries()]).toEqual([['dsh.terminal.shell', info.shell.path]])
   const pending = Promise.withResolvers<RemoteResult<void>>()
   vi.mocked(h.remote.close).mockReturnValueOnce(pending.promise)
   service.close(sessionId, 'new-tab')
-  const request = { sessionId, id: model.id, title: 'new-tab' }
-  expect([...data.entries()]).toEqual([[`dsh.terminal.close.v1.${model.id}`, JSON.stringify(request)]])
+  const request = { sessionId, id: model.id, title: info.title }
+  expect([...data.entries()]).toEqual([['dsh.terminal.shell', info.shell.path], [`dsh.terminal.close.v1.${model.id}`, JSON.stringify(request)]])
   pending.resolve(success(undefined))
-  await expect.poll(() => data.size).toBe(0)
+  await expect.poll(() => [...data.keys()]).toEqual(['dsh.terminal.shell'])
 })
 
 it.each(['{broken', 'null', '{}', '[{}]', '{"sessionId":"s","id":"bad/id","title":"x"}', '{"sessionId":"s","id":"different","title":"x"}'])('discards malformed saved cleanup: %s', (raw) => {
@@ -394,7 +388,7 @@ it.each(['saved', 'view'] as const)('clears a %s close request after the Host co
   }
   await expect.poll(() => vi.mocked(h.remote.close).mock.calls.length).toBe(1)
   await dispose()
-  expect(data.size).toBe(0)
+  expect([...data.entries()]).toEqual(source === 'view' ? [['dsh.terminal.shell', info.shell.path]] : [])
   expect(service.closeFailures.getSnapshot()).toEqual([])
   expect(new TerminalCloseRequests().pending()).toEqual([])
   await h.service()
@@ -426,7 +420,6 @@ it('waits for both active and detached stream finalizers during plugin disposal
   const model = service.view(sessionId, 'tab')
   model.mount()
   await model.refresh()
-  await model.start()
   await expect.poll(() => model.state.getSnapshot().writable).toBe(true)
   model.connect()
   await started[0]!.promise
@@ -445,53 +438,55 @@ it('waits for both active and detached stream finalizers during plugin disposal
   expect(h.remote.close).not.toHaveBeenCalled()
 })
 
-it('remembers a shell choice immediately for new views and falls back when that shell is absent', async () => {
+it('discovers menu choices without creating a process and remembers a choice before opening its tab', async () => {
   const data = storage()
   const h = fixture()
   const alternate = { name: 'bash', path: '/bin/bash', args: ['-i'] }
   vi.mocked(h.remote.shells).mockResolvedValue(success([info.shell, alternate]))
-  vi.mocked(h.remote.create).mockImplementation(async (_sessionId, request) => success({ ...info, shell: alternate, id: request.id }))
-  const first = h.view()
-  await first.start()
-  first.selectShell(alternate.path)
-  await first.refresh()
-  expect(first.state.getSnapshot()).toMatchObject({ phase: 'selecting', selectedShell: info.shell.path })
-  first.selectShell('/not-listed')
-  expect(first.state.getSnapshot().selectedShell).toBe(info.shell.path)
-  first.selectShell(alternate.path)
+  const { service } = await h.service()
+  expect(await service.launchShells(sessionId, new AbortController().signal)).toEqual({
+    shells: [info.shell, alternate], selectedShell: info.shell.path,
+  })
+  service.selectShell(alternate.path)
   expect(data.get('dsh.terminal.shell')).toBe(alternate.path)
-  const beforeLaunch = h.view()
-  await beforeLaunch.refresh()
-  expect(beforeLaunch.state.getSnapshot().selectedShell).toBe(alternate.path)
   expect(h.remote.create).not.toHaveBeenCalled()
-  await first.start()
-  expect(data.get('dsh.terminal.shell')).toBe(alternate.path)
-  expect(h.remote.create).toHaveBeenCalledWith(sessionId, expect.objectContaining({ shellPath: alternate.path }), expect.any(AbortSignal))
-  const second = h.view()
-  await second.refresh()
-  expect(second.state.getSnapshot().selectedShell).toBe(alternate.path)
-  await second.dispose()
-  await second.start()
+  expect((await service.launchShells(sessionId, new AbortController().signal)).selectedShell).toBe(alternate.path)
+  const model = service.view(sessionId, 'chosen', undefined, alternate.path)
+  await model.refresh()
+  expect(h.remote.create).toHaveBeenLastCalledWith(
+    sessionId, expect.objectContaining({ shellPath: alternate.path }), expect.any(AbortSignal),
+  )
+  expect(h.remote.shells).toHaveBeenCalledTimes(2)
+  await h.view().refresh()
+  expect(h.remote.create).toHaveBeenLastCalledWith(
+    sessionId, expect.objectContaining({ shellPath: alternate.path }), expect.any(AbortSignal),
+  )
   vi.mocked(h.remote.shells).mockResolvedValue(success([info.shell]))
-  const third = h.view()
-  await third.refresh()
-  expect(third.state.getSnapshot().selectedShell).toBe(info.shell.path)
-  expect(h.remote.create).toHaveBeenCalledOnce()
+  await h.view().refresh()
+  expect(h.remote.create).toHaveBeenLastCalledWith(
+    sessionId, expect.objectContaining({ shellPath: info.shell.path }), expect.any(AbortSignal),
+  )
+  vi.mocked(h.remote.shells).mockResolvedValueOnce(failure('host offline'))
+  await expect(service.launchShells(sessionId, new AbortController().signal)).rejects.toThrow('host offline')
+  vi.mocked(h.remote.shells).mockResolvedValue(success([]))
+  expect((await service.launchShells(sessionId, new AbortController().signal)).selectedShell).toBeUndefined()
+  await h.view().refresh()
+  expect(vi.mocked(h.remote.create).mock.calls.at(-1)?.[1]).not.toHaveProperty('shellPath')
 })
 
-it('retains the last selection across a failed launch', async () => {
+it('retains the last selection across a failed automatic launch', async () => {
   const data = storage()
   const h = fixture()
   vi.mocked(h.remote.create).mockResolvedValueOnce(failure('shell disappeared'))
   const model = h.view()
   await model.refresh()
-  await model.start()
   expect(data.get('dsh.terminal.shell')).toBe(info.shell.path)
+  expect(model.state.getSnapshot().error).toBe('shell disappeared')
   await model.refresh()
-  expect(model.state.getSnapshot().selectedShell).toBe(info.shell.path)
+  expect(h.remote.create).toHaveBeenCalledTimes(2)
   await model.close()
-  await model.start()
-  expect(h.remote.create).toHaveBeenCalledOnce()
+  await model.refresh()
+  expect(h.remote.create).toHaveBeenCalledTimes(2)
 })
 
 it('keeps launch usable when browser storage is denied and stops late shell discovery after close', async () => {
@@ -500,7 +495,6 @@ it('keeps launch usable when browser storage is denied and stops late shell disc
   const h = fixture()
   const model = h.view()
   await model.refresh()
-  await model.start()
   expect(model.state.getSnapshot().info).toBeDefined()
   const delayed = h.view()
   const shells = Promise.withResolvers<Awaited<ReturnType<TerminalRemote['shells']>>>()
diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml
index e4927f06dd..061f2c220b 100644
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/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 packages/boot/app-boot/README.md
-README.md: 595b0f32cf6b96d13443b9e16616b6e79b2a114d
-README.zh.md: 66932227c1035bb545a4a67ddc6b36a3feaff9b4
+README.md: 8573b3669a7ac033ac8687b0253bd6cc0cad88af
+README.zh.md: 949d4455d28365e130d911a85317a346aab006ad
diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md
index 595b0f32cf..8573b3669a 100644
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -49,8 +49,6 @@ Import profile and bundle declaration types from [`@deepseek-ai/dsh-package-mani
 
 A profile is how one dsh installation ships different app surfaces: `web`, `headless`, `acp`, `sdk`, and `sdk-minimal` start distinct compositions from the same launcher. A profile lives at `$DSH_HOME/profiles/<name>` and combines installable bundles, its own `cordis.patch.yml`, and `patchReload: live | startup`; omitted reload policy keeps the historical `live` default for custom profiles. The shipped `web` template uses live reload, while the other shipped templates apply patches only at startup. `sdk-minimal` names only its standalone bundle; the other templates retain base-plus-mode stacks. `dsh --profile <name> --from-default-profile <template>` creates a custom profile at a new non-shipped name from one shipped template, while `dsh plugin` initializes a base-backed profile and manages its installed bundles. A missing bundle or one without a patch declaration fails startup loudly. Application-owned npm projects, such as Electron's reserved Desktop profile, use `loadProfileDirectory` to load an already initialized directory without exposing it through CLI profile lookup.
 
-`initProfile` creates missing manifest, empty user patch, and pnpm workspace files while preserving existing files. CLI and Desktop share installed-dependency discovery and bundle-list reconciliation: the same installation-first resolver determines bundle declarations, unavailable installed metadata leaves dependencies visible for repair, and ordinary dependencies stay inactive. Callers explicitly choose whether disabled bundles remain disabled; CLI activates installed bundles, while Desktop retains its UI activation choices.
-
 Your machine-local preferences also live in the Harness home:
 
 - **`.env`** — your ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. Variables that decide how the process starts (`PATH`, `DSH_*`, `XDG_*` and similar) are rejected from files: export them instead. The four proxy names (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`) are accepted from the Harness-home file only, never from the invoking directory's, which arrives with a clone. For a non-product bin that just wants one directory's `.env`, a missing file is fine and an unloadable one prints one labelled warning line.
@@ -60,6 +58,8 @@ Profiles with `patchReload: live` watch both user patch files and apply the [rel
 
 Inserted plugin names may be absolute filesystem paths, file URLs, or package specifiers. Patch loading converts absolute paths and patch-relative `./` or `../` paths to file URLs within `insert` rows and their nested groups; existing-entry name assertions and replacement `config` values remain literal.
 
+Before mounting profile rows, the `dsh` launcher computes one immutable package-resolution generation from the installation and ordered bundle dependency graphs. The default link mode materializes the existing shared and profile-owned fallback links, so supported launch behavior stays unchanged. Internal callers and test harnesses can instead install the generation through Node's ESM and CommonJS resolvers in runtime mode, or materialize and verify the same generation in dual mode.
+
 ### Previewing the effective configuration
 
 Before you boot, you can print the exact configuration the app will mount: the dump shows the composed entry list with `!!js` expressions verbatim, grouped under comments naming each source file and the patch layers that changed it, as one loadable YAML document. Patches that match no row are reported with their layer label; a missing, unparsable, or invalid config fails the dump.
@@ -105,14 +105,15 @@ This section explains how the outcomes above are realized and points at the code
 
 ### Design notes
 
-- **Channel-neutral library.** The package carries no loader hooks and no dev-mode surface; the [`dsh` app](../../../apps/cli/README.md) owns its Node source-launch hook and consumes these helpers for the boot sequence, and built consumers use plain Node package resolution.
+- **Process-local module resolution.** Runtime and dual modes install one generation on Node's internal ESM and CommonJS resolvers before profile rows mount; link mode leaves both resolvers unchanged. Node still owns exports, conditions, subpaths, module caches, and error codes; routed ESM failures report the original importer instead of the internal lookup anchor. `ctx.pluginPackages` exposes package metadata from the same generation without recording Entry imports; an installed generation is authoritative even for a miss, while low-level embedders that install the service without one retain native lookup.
 - **Two Loader builtins.** `mountRootInclude` registers `cordis:include` and `cordis:group` as Loader builtins: a group row gives one `isolate` realm to a provider and its consumers together, and an agent preset outside this workspace cannot resolve `@deepseek-ai/cordis-plugin-group` by name. Both load through the ambient module pipeline rather than the included tree's own specifier resolution.
 - **Consumer-owned strictness.** Ordinary Loader groups keep successful siblings. App-boot applies the global required-entry policy after initial settlement; agent presets and dynamic multi-entry compositions own and dispose their separate generation when they require all-or-nothing setup. App-boot reads failed fibers to report their recorded errors and coalesces duplicate Loader rejection notifications through one process checkpoint.
-- **Profile module fallback.** Bare plugin specifiers resolve through the Loader from the config directory. Plain Node maintains one symlink per package in the installation dependency closure. A packaged executable instead reads each installed export map with Node ESM conditions and writes real proxy packages that re-export virtual module URLs, because an operating-system symlink cannot enter pkg's `/snapshot` tree. Missing exports stay unavailable, malformed maps fail startup, and a cross-process writer lock replaces stale entries without exposing partial proxies. A selected external bundle absent from the installation closure receives a profile-local `.dsh-module-fallback` link; existing pnpm entries win, projected links are excluded from later closure discovery, and cleanup removes only dsh-owned links. Application-owned filesystem profiles use the same projection for their installation closure, so missing peers resolve inside their own profile without maintaining a shared fallback directory.
-
-- **Package-operation cleanup.** The shared fallback owner removes only the profile links it created before a package-manager operation. pnpm-managed entries remain untouched, and the profile runner recreates required installation and bundle links at the next boot. Desktop uses this owner without a separate runtime-state or lockfile-hash reconciliation scheme.
+- **One fallback generation.** The installation-first and ordered-bundle breadth-first traversal produces both the runtime table and the retained disk materializer. Runtime mode creates no resolution links and ignores stale projections at their former lookup positions. External bare targets selected by package `imports` use the same package order, while Node retains mapping, conditions, and exact target resolution. Link mode materializes the same table; dual mode also compares Node's disk result with the table. A complete successor may add package names atomically, while changing or removing an existing mapping requires restart.
+- **Application-owned profiles.** Link mode projects missing installation and bundle packages inside the profile without writing a shared Harness-home fallback. Runtime mode supplies the same installation and bundle generation without creating links. Package operations remove only profile links owned by dsh; pnpm-managed entries remain untouched.
+- **Owned Workers.** Worker build banners import `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap` before bundled business code. Each Worker installs the structured-cloned generation in its own isolate. The bootstrap bundle has no static package imports. Source Worker entries retain their self-contained dependency closure, and third-party Workers receive no injection.
 - **Update completion.** App boot observes restart failures through the `internal/update` waterfall. Live patch reloads wait for the tree's fibers before auditing activation; `Fiber.update()` and `Entry.update()` alone do not establish restart success.
-- **Two-stage failure labels.** `boot()` distinguishes `host preparation failed` — `prepare` threw before any config-tree entry mounted — from `plugin tree failed to load`. Plugin diagnostics include original stacks, nested causes, and aggregate member failures. Cyclic causes terminate diagnostic traversal without replacing the original cause.
+- **One rejection checkpoint.** `assertEntriesActivated` keeps the exact reasons it folds into the boot diagnostic visible through the next process rejection checkpoint, so `installFailLoud` coalesces Loader's duplicate notification while unrelated unhandled rejections remain fatal.
+- **Two-stage failure labels.** `boot()` distinguishes `host preparation failed` — `prepare` threw before any config-tree entry mounted — from `plugin tree failed to load`, and appends the deepest plugin error's stack. Plugin diagnostics retain nested causes and aggregate member failures; cyclic causes stop traversal without replacing the original error.
 
 ### Helper behavior
 
@@ -125,7 +126,8 @@ The exports each own one stage of the boot: config resolution and snapshot repla
 | [`src/index.ts`](src/index.ts) | Boot helpers: config resolution, environment loading, fail-loud guard, activation audit, patch parsing, config dump, harness-source section |
 | [`src/profile.ts`](src/profile.ts) | Profile discovery, initialization, bundle resolution, module fallback |
 | [`src/profile-plugins.ts`](src/profile-plugins.ts) | Installed dependencies, bundle activation policy, and manifest updates |
-| — | No runtime invariant companion is published; this presentation adapter owns no durable package-local event stream; boundary and replay tests cover its protocol mapping. |
+| [`src/profile-resolution/`](src/profile-resolution/) | Runtime resolver, package-metadata service, and built Worker bootstrap |
+| — | No runtime invariant companion is published; one registration owns each resolver generation, and dual mode compares the independently materialized result at resolution time. |
 
 </details>
 
@@ -163,7 +165,7 @@ Boot itself changes no request prefix. `addHarnessSourceSection` places its sour
 
 These limits describe when this boot library is a poor fit or needs special care. They are current package constraints, not a task backlog.
 
-- **Bare package specifiers depend on Loader internals** — production bins need Loader's optional native helper; an in-process caller without it must use resolvable relative/file specifiers or provide its own module-resolution hook.
+- **Runtime resolution depends on Node internals** — supported Node versions require the native builtin-access addon and executable compatibility coverage. Only built Harness-owned Workers receive the generation bootstrap; third-party Workers and custom `vm` linkers keep native resolution.
 - **Snapshot replay swapping is basename-specific** — only a config ending in `cordis.yml` or `cordis.yaml` maps to the sibling `cordis.snapshot.yml`; custom config names require caller-managed selection.
 - **Environment discovery is launch-scoped** — `loadLayeredEnv` reads only the invocation directory and Harness home once; it does not search parents or follow a workspace selected later. `loadEnv` remains the one-directory helper for non-product bins.
 - **A user patch replaces the whole matched config** — an id-targeted patch does not deep-merge, so a profile override restates the bundle fields it keeps.
diff --git a/packages/boot/app-boot/README.zh.md b/packages/boot/app-boot/README.zh.md
index 66932227c1..949d4455d2 100644
--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -49,8 +49,6 @@ Profile 与组合包的声明类型从 [`@deepseek-ai/dsh-package-manifest`](../
 
 profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`headless`、`acp`、`sdk` 与 `sdk-minimal` 从同一 launcher 启动不同组合。profile 位于 `$DSH_HOME/profiles/<name>`，由可安装组合包、自身 `cordis.patch.yml` 与 `patchReload: live | startup` 组成；自定义 profile 省略 reload 策略时保留历史 `live` 默认值。随产品交付的 `web` 模板实时重载，其他随附模板只在启动时应用 patch。`sdk-minimal` 只列出自身的独立组合包，其他模板保留 base 加模式的组合包栈。`dsh --profile <name> --from-default-profile <template>` 从一个随附模板，在新的非内置名称处创建自定义 profile；`dsh plugin` 则初始化以 base 为基础的 profile，并管理其中安装的组合包。缺失组合包或未声明 patch 的组合包会让启动明确失败。由应用持有的 npm 项目（例如 Electron 保留的 Desktop profile）通过 `loadProfileDirectory` 加载已经初始化的目录，而不会将它暴露给 CLI profile 查找。
 
-`initProfile` 创建缺失的 manifest、空用户 patch 与 pnpm workspace 文件，同时保留现有文件。CLI 与 Desktop 共用已安装依赖发现及 bundle 列表协调：同一个安装目录优先的解析器判断 bundle 声明，已安装元数据不可用时依赖仍可见以供修复，普通依赖保持未激活。调用者显式选择是否保留禁用的 bundle；CLI 激活已安装 bundle，Desktop 保留 UI 中的启用选择。
-
 你的机器本地偏好同样位于 harness home 中：
 
 - **`.env`**——你的普通环境层：调用目录的文件优先于 harness home 的文件，两者都低于继承环境。在文件中设置的进程启动变量（如 `PATH`、`DSH_*`、`XDG_*`）会被拒绝：请改为导出这些变量。四个代理名（`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`、`NO_PROXY`）只从 harness home 的文件接受，绝不从调用目录的文件接受——后者随 clone 一起到来。对于只想加载某个目录 `.env` 的非产品 bin，文件缺失不影响启动，文件无法加载时输出一行带标签的警告。
@@ -60,6 +58,8 @@ profile 是同一套 dsh 安装提供不同应用界面的方式：`web`、`head
 
 插入条目的插件名可以是绝对文件系统路径、文件 URL 或包标识符。patch 加载会把 `insert` 条目及其嵌套分组中的绝对路径以及相对于 patch 文件的 `./` 或 `../` 路径转换为文件 URL；对已有条目名称的断言及替换用的 `config` 值保持原样。
 
+挂载 profile 条目前，`dsh` launcher 会从安装依赖图与有序 bundle 依赖图计算一份不可变的 package resolution generation。默认 link 模式会物化现有的共享 fallback 链接与 profile 自有 fallback 链接，因此受支持的启动行为保持不变。内部调用方和测试工具可以改用 runtime 模式，把 generation 安装到 Node 的 ESM 与 CommonJS resolver；也可以使用 dual 模式，同时物化并校验同一份 generation。
+
 ### 预览生效配置
 
 启动前，你可以打印应用将挂载的确切配置：dump 会以 `!!js` 表达式原样展示组合后的条目列表，并按注释分组标明每个源文件及其 patch 层，输出是一份可加载的 YAML 文档。未匹配到任何行的 patch 会连同其层标签一起报告；配置缺失、无法解析或字段无效都会使 dump 失败。
@@ -105,14 +105,15 @@ Loader 结算后，app-boot 将 optional 失败报告为警告；若已启用的
 
 ### 设计说明
 
-- **与渠道无关的库。** 此包不包含 loader 钩子，也不提供开发模式接口；[`dsh` 应用](../../../apps/cli/README.zh.md) 持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper，构建后的消费方则使用普通 Node 包解析。
+- **进程内模块解析。** runtime 和 dual 模式会在挂载 profile 条目前，将一份 generation 安装到 Node 的 ESM 与 CommonJS 内部 resolver；link 模式不修改这两个 resolver。exports、conditions、subpath、模块缓存和错误码仍由 Node 负责；路由后的 ESM 失败会报告原始 importer，而不是内部查找锚点。`ctx.pluginPackages` 从同一 generation 提供 package metadata，不记录 Entry import；安装 generation 后，即使查询未命中也以 generation 为准，仅安装服务而未提供 generation 的底层嵌入方仍使用 Node 原生查找。
 - **两个 Loader builtin。** `mountRootInclude` 把 `cordis:include` 与 `cordis:group` 注册为 Loader builtin：group 行能把一个提供方与它的消费方放进同一个 `isolate` realm，而位于本工作区之外的 agent preset 无法按名称解析 `@deepseek-ai/cordis-plugin-group`。两者都通过宿主的模块管线加载，而非被包含树自身的说明符解析。
 - **由 consumer 持有严格语义。** 普通 Loader group 保留成功 sibling。App-boot 在首次结算后应用全局 required-entry policy；agent preset 与动态多 entry 组合在需要 all-or-nothing setup 时，持有并拆卸各自的独立 generation。App-boot 读取 failed fiber 来报告已记录的错误，并在一个进程检查点内合并 Loader 重复的 rejection 通知。
-- **Profile 模块后备机制。** 裸插件 specifier 由 Loader 从配置目录解析。普通 Node 会为安装依赖闭包中的每个包维护一个符号链接。打包可执行文件无法让操作系统符号链接进入 pkg 的 `/snapshot` 树，因此会按 Node ESM 条件读取已安装包的 export map，并写入重新导出虚拟模块 URL 的真实代理包。缺失 export 保持不可用，错误 export map 会让启动失败，跨进程 writer lock 则会在不暴露部分代理的情况下替换陈旧条目。所选外部组合包若不在安装闭包中，则会获得 profile 本地的 `.dsh-module-fallback` 链接；已有 pnpm 条目优先，后续闭包发现会排除投影链接，清理也只删除 dsh 自有链接。应用自有的文件系统 profile 使用同一投影机制补全安装闭包，因此缺失的 peer 可在自己的 profile 内解析，无需维护共享后备目录。
-
-- **包操作清理。** 共享模块补全逻辑在包管理器操作前仅移除自己创建的 profile 链接。pnpm 管理的条目保持不变，profile runner 在下次启动时重新创建所需的安装包及 bundle 链接。Desktop 使用这一归属机制，不维护独立的运行时状态或锁文件哈希协调流程。
+- **唯一 fallback generation。** 安装优先、有序 bundle 逐根 breadth-first 遍历同时生成运行时表和保留的磁盘 materializer。runtime 模式不创建解析链接，并在旧链接原来的查找位置忽略陈旧投影。package `imports` 选中的外部 bare target 使用相同的选包顺序，映射、conditions 和精确 target 解析仍由 Node 负责。link 模式物化同一张表；dual 模式还会比较 Node 的磁盘结果与表。完整后继 generation 可以原子增加 package name，修改或删除既有映射则要求重启。
+- **应用自有 profile。** link 模式在 profile 内投影缺失的安装包及 bundle 包，不写共享的 Harness-home 后备目录。runtime 模式提供相同的安装包及 bundle generation，不创建链接。包操作仅移除 dsh 所有的 profile 链接；pnpm 管理的条目保持不变。
+- **自有 Worker。** Worker 构建 banner 会在业务 bundle 前导入 `@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap`。每个 Worker 在自己的 isolate 中安装结构化克隆的 generation。bootstrap bundle 不静态导入任何包。源码 Worker 入口保留自包含依赖，第三方 Worker 不接受注入。
 - **更新完成。** App boot 通过 `internal/update` waterfall 观察重启失败。实时 patch 重载在检查激活状态前等待配置树中的 fiber；单独调用 `Fiber.update()` 或 `Entry.update()` 不能确定重启成功。
-- **两阶段失败标签。** `boot()` 区分 `host preparation failed`（`prepare` 在任何配置树条目挂载前抛出）与 `plugin tree failed to load`。插件诊断包含原始堆栈、嵌套原因和聚合错误中的各项失败。原因链出现循环时，诊断遍历会终止，不会替换原始原因。
+- **单一 rejection 检查点。** `assertEntriesActivated` 把折入启动诊断的确切原因保持到下一个进程级 rejection 检查点可见，使 `installFailLoud` 能合并 Loader 的重复通知，而所有无关的未处理 rejection 仍然致命。
+- **两阶段失败标签。** `boot()` 区分 `host preparation failed`（`prepare` 在任何配置树条目挂载前抛出）与 `plugin tree failed to load`，并追加最深层插件错误的堆栈。插件诊断保留嵌套原因和聚合错误中的各项失败；原因链出现循环时会停止遍历，但不会替换原始错误。
 
 ### Helper 行为
 
@@ -125,7 +126,8 @@ Loader 结算后，app-boot 将 optional 失败报告为警告；若已启用的
 | [`src/index.ts`](src/index.ts) | 启动 helper：配置解析、环境加载、会明确报错的保护机制、激活审计、patch 解析、配置 dump、harness 源码段落 |
 | [`src/profile.ts`](src/profile.ts) | profile 发现、初始化、组合包解析、模块后备机制 |
 | [`src/profile-plugins.ts`](src/profile-plugins.ts) | 已安装依赖、bundle 启用策略与 manifest 更新 |
-| — | 不发布运行时不变式伴生入口；边界与回放测试覆盖其协议映射。 |
+| [`src/profile-resolution/`](src/profile-resolution/) | 运行时 resolver、package metadata 服务与构建后 Worker bootstrap |
+| — | 不发布运行时不变式伴生入口；每个 resolver generation 只有一个 registration 所有，dual 模式在解析时比较独立物化的结果。 |
 
 </details>
 
@@ -163,7 +165,7 @@ Loader 结算后，app-boot 将 optional 失败报告为警告；若已启用的
 
 这些限制说明此启动库在何时不合适，或何时需要特别注意。它们是当前包约束，不是任务积压。
 
-- **裸包 specifier 依赖 Loader 内部机制**——生产 bin 需要 Loader 的可选原生辅助组件；没有该辅助组件的进程内调用方必须使用可解析的相对／file specifier，或提供自己的模块解析钩子。
+- **运行时解析依赖 Node 内部机制**——受支持的 Node 版本需要 native builtin access addon 和可执行兼容验证。只有构建后的 Harness 自有 Worker 接收 generation bootstrap；第三方 Worker 与自定义 `vm` linker 保持原生解析。
 - **快照回放替换仅识别特定 basename**——只有以 `cordis.yml` 或 `cordis.yaml` 结尾的配置会映射到同级 `cordis.snapshot.yml`；自定义配置名称需要调用方自行选择。
 - **环境发现以启动为界**——`loadLayeredEnv` 只读取一次调用目录与 harness home 中的 `.env`；它不搜索父目录，也不跟随之后选择的 workspace。`loadEnv` 仍是非产品 bin 使用的单目录 helper。
 - **用户 patch 会替换匹配到的整个配置**——按 id 定位的 patch 不做深度合并，因此 profile 覆盖必须重述需要保留的组合包字段。
diff --git a/packages/boot/app-boot/package.json b/packages/boot/app-boot/package.json
index 88ba5d0c10..ff52fed547 100644
--- a/packages/boot/app-boot/package.json
+++ b/packages/boot/app-boot/package.json
@@ -18,11 +18,16 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./worker/profile-resolution-bootstrap": {
+      "types": "./lib/types/profile-resolution/worker-bootstrap.d.ts",
+      "default": "./lib/worker/profile-resolution-bootstrap.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
+    "lib/worker/profile-resolution-bootstrap.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
@@ -31,6 +36,7 @@
     "@deepseek-ai/dsh-package-manifest": "workspace:^",
     "chokidar": "4.0.3",
     "js-yaml": "^4.2.0",
+    "node-addon-require-builtin": "^0.1.6",
     "resolve.exports": "^2.0.3"
   },
   "peerDependencies": {
diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts
index af78b7957d..a31e3c32a1 100644
--- a/packages/boot/app-boot/src/index.ts
+++ b/packages/boot/app-boot/src/index.ts
@@ -35,6 +35,7 @@ declare module '@deepseek-ai/cordis' {
 
 export {
   composeEntries,
+  createProfileResolutionGeneration,
   DEFAULT_PROFILE_BUNDLES,
   DEFAULT_PROFILE_PATCH_RELOAD,
   healProfilesModuleFallback,
@@ -54,8 +55,16 @@ export {
   type ProfileLayer,
   type ProfileManifest,
   type ProfileModuleFallbackOptions,
+  type ProfileResolutionEntry,
+  type ProfileResolutionGeneration,
+  type ProfileResolutionMode,
   type ProfileTemplate,
 } from './profile.ts'
+export {
+  PluginPackages,
+  type PluginPackage,
+  type PluginPackagesConfig,
+} from './profile-resolution/service.ts'
 
 /**
  * Resolve the config to boot. Replay swaps a `cordis.yml` basename for
diff --git a/packages/boot/app-boot/src/profile-resolution/legacy-links.ts b/packages/boot/app-boot/src/profile-resolution/legacy-links.ts
new file mode 100644
index 0000000000..d9eb618d47
--- /dev/null
+++ b/packages/boot/app-boot/src/profile-resolution/legacy-links.ts
@@ -0,0 +1,73 @@
+/** Legacy profile-link inspection shared by the disk materializer and runtime resolver. */
+
+import { lstatSync, readlinkSync, realpathSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+
+/** Profile-private package links projected into its pnpm-managed node_modules. */
+export const PROFILE_MODULE_FALLBACK_DIR = '.dsh-module-fallback'
+
+/**
+ * Return whether the process reads application modules from pkg's virtual filesystem.
+ * @returns whether pkg owns the module filesystem.
+ */
+export function isPackagedExecutable(): boolean {
+  return (process as NodeJS.Process & { pkg?: unknown }).pkg !== undefined
+}
+
+/**
+ * Resolve a directory through the active carrier's filesystem implementation.
+ * @param path - directory path to canonicalize.
+ * @returns the canonical directory path.
+ */
+export function realModuleDirectory(path: string): string {
+  return isPackagedExecutable() ? realpathSync(path) : realpathSync.native(path)
+}
+
+/**
+ * Resolve a link target without following the final path component.
+ * @param path - candidate path whose parent is canonicalized.
+ * @returns the canonical candidate, or undefined when its parent is absent.
+ */
+export function canonicalLinkPath(path: string): string | undefined {
+  try {
+    return join(realModuleDirectory(dirname(path)), basename(path))
+  } catch (error) {
+    // A missing parent means the candidate cannot identify an existing owned link.
+    /* v8 ignore next 2 -- a non-ENOENT realpath failure requires a host filesystem fault */
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    /* v8 ignore next -- see the host-filesystem exception above */
+    throw error
+  }
+}
+
+/**
+ * Return whether a symlink or junction points at the same path as `target`.
+ * @param link - symlink or junction to inspect.
+ * @param target - expected target path.
+ * @returns whether both paths identify the same entry.
+ */
+export function symlinkPointsTo(link: string, target: string): boolean {
+  const actual = resolve(dirname(link), readlinkSync(link))
+  const canonicalActual = canonicalLinkPath(actual)
+  const canonicalTarget = canonicalLinkPath(resolve(target))
+  return canonicalActual !== undefined && canonicalActual === canonicalTarget
+}
+
+/**
+ * Return whether an observed profile package must not claim local precedence.
+ * @param profileDir - profile directory containing the package projection.
+ * @param packageName - bare package name to inspect.
+ * @returns whether the entry is a managed fallback link or disappeared during inspection.
+ */
+export function isProfileModuleFallbackLink(profileDir: string, packageName: string): boolean {
+  const link = join(profileDir, 'node_modules', packageName)
+  const target = join(profileDir, PROFILE_MODULE_FALLBACK_DIR, 'node_modules', packageName)
+  try {
+    return lstatSync(link).isSymbolicLink() && symlinkPointsTo(link, target)
+  } catch (error) {
+    /* v8 ignore next 2 -- a vanished candidate cannot claim local precedence */
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return true
+    /* v8 ignore next -- non-ENOENT lstat/readlink failures require a host filesystem fault */
+    throw error
+  }
+}
diff --git a/packages/boot/app-boot/src/profile-resolution/resolver.ts b/packages/boot/app-boot/src/profile-resolution/resolver.ts
new file mode 100644
index 0000000000..959482c02a
--- /dev/null
+++ b/packages/boot/app-boot/src/profile-resolution/resolver.ts
@@ -0,0 +1,975 @@
+/** In-memory profile package routing for Node's default ESM and CommonJS loaders. */
+
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { createRequire, isBuiltin } from 'node:module'
+import { basename, dirname, join, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { getEnvironmentData, setEnvironmentData } from 'node:worker_threads'
+import type { ModuleLoaderV1, ModuleLoaderV2, ResolveResult } from '@deepseek-ai/cordis-plugin-loader'
+import { imports as resolvePackageImports, type Package as ResolvePackageManifest } from 'resolve.exports'
+import { isProfileModuleFallbackLink } from './legacy-links.ts'
+import type { ProfileResolutionEntry, ProfileResolutionGeneration } from '../profile.ts'
+
+const WORKER_RESOLUTION_KEY = '@deepseek-ai/dsh-app-boot/profile-resolution'
+const EMPTY_ATTRIBUTES: ImportAttributes = Object.freeze({})
+
+interface CommonJsParent {
+  filename?: string | null
+  parent?: CommonJsParent | null
+  paths?: string[]
+}
+
+interface CommonJsOptions {
+  paths?: string[]
+  conditions?: ReadonlySet<string>
+}
+
+interface CommonJsModule {
+  new(id?: string, parent?: CommonJsParent): CommonJsParent
+  _nodeModulePaths(path: string): string[]
+  _resolveFilename(
+    request: string, parent: CommonJsParent | null | undefined, isMain: boolean, options?: CommonJsOptions,
+  ): string
+}
+
+interface InternalModules {
+  esm: ModuleLoaderV1 | ModuleLoaderV2
+  esmDefaultResolve: (
+    specifier: string,
+    context: { parentURL?: string; conditions?: readonly string[] },
+  ) => ResolveResult
+  esmConditions: readonly string[]
+  cjs: CommonJsModule
+  cjsConditions: ReadonlySet<string>
+  modern: boolean
+}
+
+type EsmResolve = (
+  request: string, parent: string | undefined, attributes: ImportAttributes,
+) => ResolveResult | Promise<ResolveResult>
+
+type ResolutionRoute =
+  | { readonly kind: 'fallback'; readonly entry: ProfileResolutionEntry; readonly after: string }
+  | { readonly kind: 'after-fallback'; readonly parent: string }
+  | { readonly kind: 'native'; readonly packageDir?: string }
+
+interface ResolutionRouteState {
+  readonly route: ResolutionRoute
+  packageDir?: string
+  esm?: ResolveResult
+  cjs?: string
+}
+
+interface ParentRoutes {
+  readonly parent: string
+  readonly profilesDir: string
+  readonly activeProfile: boolean
+  readonly requests: Map<string, ResolutionRouteState>
+  selfReferenceName?: string | false | null
+}
+
+type ResolutionRoutes = Map<string, ParentRoutes | false>
+
+interface CompiledGeneration {
+  readonly entries: ReadonlyMap<string, ProfileResolutionEntry>
+  readonly profilesDir: string
+  readonly profileDir: string | undefined
+  readonly profilePaths: readonly string[]
+  readonly profileUrls: readonly string[]
+  readonly profile: readonly string[]
+  readonly activeProfileUrls: readonly string[]
+  readonly localPackageNames: ReadonlySet<string>
+  readonly shared: ReadonlySet<string>
+  readonly esmRoutes: ResolutionRoutes
+  readonly cjsRoutes: ResolutionRoutes
+}
+
+/** Whether runtime resolution redirects requests or verifies the materialized backend. */
+export type ProfileResolutionBehavior = 'enforce' | 'verify'
+
+/** Active resolver registration in one Node isolate. */
+export interface ProfileResolutionRegistration {
+  /**
+   * Locate a bare package without requiring one of its exports.
+   * @param specifier - bare package or package-subpath specifier.
+   * @param parentURL - file URL whose lookup order applies.
+   * @returns selected package directory, or undefined when it is absent.
+   */
+  packageDir(specifier: string, parentURL: string): string | undefined
+  /**
+   * Atomically publish an additive package table and fresh generation-owned caches.
+   * @param generation - fully constructed successor generation.
+   * @throws when the profile scope or an existing package mapping changes.
+   */
+  replace(generation: ProfileResolutionGeneration): void
+  /** Restore the native resolver methods. Registrations dispose in reverse order. */
+  dispose(): void
+}
+
+/**
+ * Split a bare request into its package name without allocating path segments.
+ * @param request - module specifier to classify.
+ * @returns the bare package name, or undefined for non-package requests.
+ */
+export function barePackageName(request: string): string | undefined {
+  if (!request || request[0] === '.' || request[0] === '/' || request[0] === '\\'
+    || request[0] === '#' || request.includes(':') || isBuiltin(request)) return
+  const first = request.indexOf('/')
+  if (request[0] !== '@') return first < 0 ? request : request.slice(0, first)
+  if (first < 0) return
+  const second = request.indexOf('/', first + 1)
+  return second < 0 ? request : request.slice(0, second)
+}
+
+function canonicalPath(path: string): string {
+  try {
+    return realpathSync(path)
+  } catch {
+    // A generation may name a profile scope before that directory is materialized.
+    return resolve(path)
+  }
+}
+
+function prefixes(path: string): readonly string[] {
+  const configured = resolve(path) + sep
+  const canonical = canonicalPath(path) + sep
+  return canonical === configured ? [configured] : [configured, canonical]
+}
+
+function compileGeneration(generation: ProfileResolutionGeneration): CompiledGeneration {
+  const profilePaths = prefixes(generation.profilesDir)
+  const profile = generation.profileDir === undefined ? [] : prefixes(generation.profileDir)
+  return {
+    entries: new Map(generation.entries.map(entry => [entry.name, entry])),
+    profilesDir: generation.profilesDir,
+    profileDir: generation.profileDir,
+    profilePaths,
+    profileUrls: profilePaths.map(path => pathToFileURL(path).href),
+    profile,
+    activeProfileUrls: profile.map(path => pathToFileURL(path).href),
+    localPackageNames: new Set(generation.localPackageNames),
+    shared: new Set(profilePaths.map(prefix => join(prefix, 'node_modules'))),
+    esmRoutes: new Map(),
+    cjsRoutes: new Map(),
+  }
+}
+
+function startsWithin(path: string, roots: readonly string[]): boolean {
+  for (const root of roots) {
+    if (path.startsWith(root)) return true
+  }
+  return false
+}
+
+function nativePackageDir(parent: string, name: string): string | undefined {
+  for (const searchPath of createRequire(parent).resolve.paths(name) as string[]) {
+    const candidate = join(searchPath, name)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+  }
+  return undefined
+}
+
+function localPackageCandidate(
+  searchPath: string, name: string, flavor: 'esm' | 'cjs',
+): { packageDir: string; canBeManagedLink: boolean } | undefined {
+  const candidate = join(searchPath, name)
+  const stat = statSync(candidate, { throwIfNoEntry: false })
+  const found = flavor === 'esm'
+    ? stat?.isDirectory() === true
+    : stat !== undefined
+      || ['.js', '.json', '.node'].some(extension => existsSync(candidate + extension))
+  return found ? { packageDir: candidate, canBeManagedLink: stat !== undefined } : undefined
+}
+
+function selfReferenceName(parent: string): string | false | null {
+  let current = dirname(parent)
+  while (true) {
+    const manifestPath = join(current, 'package.json')
+    if (existsSync(manifestPath)) {
+      let manifest: Record<string, unknown>
+      try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Record<string, unknown>
+      } catch (_error) {
+        // Only Node decides whether this request consumes an invalid package manifest.
+        return null
+      }
+      return typeof manifest.name === 'string' && manifest.exports != null
+        ? manifest.name
+        : false
+    }
+    /* v8 ignore next -- scoped module requests normally find an owning manifest before node_modules. */
+    if (basename(current) === 'node_modules') return false
+    const next = dirname(current)
+    if (next === current) return false
+    current = next
+  }
+}
+
+function packageImportsTarget(
+  parent: string, request: string, conditions: Iterable<string>,
+): { specifier: string; parentURL: string } | undefined {
+  let current = dirname(parent)
+  while (true) {
+    const manifestPath = join(current, 'package.json')
+    if (existsSync(manifestPath)) {
+      let manifest: ResolvePackageManifest
+      try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as ResolvePackageManifest
+      } catch (_error) {
+        // The native resolver retains invalid package-target and manifest diagnostics.
+        /* v8 ignore next -- native resolution cannot report MODULE_NOT_FOUND after an invalid scope manifest */
+        return undefined
+      }
+      try {
+        const target = resolvePackageImports(manifest, request, {
+          conditions: [...conditions],
+          unsafe: true,
+        })?.[0]
+        return target !== undefined && barePackageName(target) !== undefined
+          ? { specifier: target, parentURL: pathToFileURL(manifestPath).href }
+          : undefined
+      } catch (_error) {
+        // The native resolver retains missing mappings and unmatched-condition diagnostics.
+        /* v8 ignore next -- native resolution cannot report MODULE_NOT_FOUND before selecting a valid mapping */
+        return undefined
+      }
+    }
+    if (basename(current) === 'node_modules') return undefined
+    const next = dirname(current)
+    /* v8 ignore next -- a MODULE_NOT_FOUND package-import target always has an owning package scope */
+    if (next === current) return undefined
+    current = next
+  }
+}
+
+function packageSearchPaths(
+  entry: ProfileResolutionEntry, request: string, cjs: CommonJsModule,
+): string[] {
+  const name = barePackageName(request)
+  /* v8 ignore next -- fallback routes are created only for bare package requests */
+  if (name === undefined) return cjs._nodeModulePaths(dirname(entry.declarer))
+  const suffix = sep + name.split('/').join(sep)
+  return entry.packageDir.endsWith(suffix)
+    ? [entry.packageDir.slice(0, -suffix.length)]
+    : cjs._nodeModulePaths(dirname(entry.declarer))
+}
+
+function localCandidateOwnsResolution(candidate: string, resolved: string, request: string, name: string): boolean {
+  if (startsWithin(resolved, prefixes(candidate))) return true
+  if (sameResolution(candidate, resolved)) return true
+  if (['.js', '.json', '.node'].some(extension => sameResolution(candidate + extension, resolved))) return true
+  /* v8 ignore next -- a bounded native lookup can escape a candidate only through its root legacy main */
+  if (request !== name) return false
+  try {
+    const manifest = JSON.parse(readFileSync(join(candidate, 'package.json'), 'utf8')) as Record<string, unknown>
+    /* v8 ignore next -- a bounded native lookup outside the package directory requires a legacy main */
+    if (typeof manifest.main !== 'string') return false
+    const main = createRequire(join(candidate, 'package.json')).resolve(resolve(candidate, manifest.main))
+    return sameResolution(main, resolved)
+  } catch (_error) {
+    // Native resolution already owns malformed manifests and missing legacy entries.
+    /* v8 ignore next -- this helper runs only after the same native resolution succeeded */
+    return false
+  }
+}
+
+function isUnselectedPackageMiss(error: unknown): boolean {
+  const failure = error as NodeJS.ErrnoException & { path?: unknown }
+  return failure.code === 'MODULE_NOT_FOUND' && failure.path === undefined
+}
+
+function sameResolution(left: string, right: string): boolean {
+  if (left === right) return true
+  const leftPath = left.startsWith('file:') ? fileURLToPath(left) : left
+  const rightPath = right.startsWith('file:') ? fileURLToPath(right) : right
+  return canonicalPath(leftPath) === canonicalPath(rightPath)
+}
+
+/** One mutable pointer to immutable generation data. */
+class ResolutionRouter {
+  private current: CompiledGeneration
+
+  constructor(generation: ProfileResolutionGeneration) {
+    this.current = compileGeneration(generation)
+  }
+
+  replace(generation: ProfileResolutionGeneration): void {
+    const entries = new Map(generation.entries.map(entry => [entry.name, entry]))
+    if (generation.profilesDir !== this.current.profilesDir
+      || generation.profileDir !== this.current.profileDir) {
+      throw new Error('profile resolution: a generation cannot change its profile scope')
+    }
+    for (const [name, current] of this.current.entries) {
+      const next = entries.get(name)
+      if (next === undefined
+        || !sameResolution(current.packageDir, next.packageDir)
+        || !sameResolution(current.declarer, next.declarer)
+        || current.version !== next.version
+        || current.scope !== next.scope) {
+        throw new Error(`profile resolution: replacing ${JSON.stringify(name)} requires a process restart`)
+      }
+    }
+    const localPackageNames = new Set(generation.localPackageNames)
+    for (const name of this.current.localPackageNames) {
+      if (!localPackageNames.has(name)) {
+        throw new Error(`profile resolution: removing local package ${JSON.stringify(name)} requires a process restart`)
+      }
+    }
+    for (const name of localPackageNames) {
+      if (!this.current.localPackageNames.has(name) && this.current.entries.has(name)) {
+        throw new Error(`profile resolution: overriding ${JSON.stringify(name)} locally requires a process restart`)
+      }
+    }
+    this.current = compileGeneration(generation)
+  }
+
+  private routeScoped(
+    request: string,
+    parentRoutes: ParentRoutes,
+    generation: CompiledGeneration,
+    flavor: 'esm' | 'cjs',
+    nativeResolve?: (searchPaths: readonly string[]) => string,
+    cacheable = false,
+  ): ResolutionRouteState | undefined {
+    const { parent, profilesDir, requests } = parentRoutes
+    const name = barePackageName(request)
+    if (name === undefined) return undefined
+
+    if (parentRoutes.selfReferenceName === undefined) {
+      parentRoutes.selfReferenceName = selfReferenceName(parent)
+    }
+    if (parentRoutes.selfReferenceName === name || parentRoutes.selfReferenceName === null) {
+      const state = { route: { kind: 'native' as const } }
+      requests.set(request, state)
+      return state
+    }
+
+    const target = generation.entries.get(name)
+    const candidates: Array<{ packageDir: string; canBeManagedLink: boolean }> = []
+    const localSearchPaths: string[] = []
+    for (const searchPath of createRequire(parent).resolve.paths(name) as string[]) {
+      if (generation.shared.has(resolve(searchPath))) break
+      localSearchPaths.push(searchPath)
+      const candidate = localPackageCandidate(searchPath, name, flavor)
+      if (candidate !== undefined) {
+        const legacy = candidate.canBeManagedLink && generation.profile.some(prefix => (
+          candidate.packageDir === join(prefix, 'node_modules', name)
+          && isProfileModuleFallbackLink(prefix.slice(0, -1), name)
+        ))
+        if (!legacy) candidates.push(candidate)
+      }
+    }
+    if (candidates.length > 0) {
+      if (flavor === 'cjs' && nativeResolve !== undefined) {
+        try {
+          const resolved = nativeResolve(localSearchPaths)
+          const selected = candidates.find(candidate => (
+            localCandidateOwnsResolution(candidate.packageDir, resolved, request, name)
+          ))
+          if (selected !== undefined) {
+            const state = {
+              route: { kind: 'native' as const, packageDir: selected.packageDir },
+              packageDir: selected.packageDir,
+              ...(cacheable ? { cjs: resolved } : {}),
+            }
+            requests.set(request, state)
+            return state
+          }
+        } catch (error) {
+          if (!isUnselectedPackageMiss(error)) throw error
+        }
+      } else {
+        const selected = candidates[0] as { packageDir: string }
+        const state = {
+          route: { kind: 'native' as const, packageDir: selected.packageDir },
+          packageDir: selected.packageDir,
+        }
+        requests.set(request, state)
+        return state
+      }
+    }
+
+    const eligible = target?.scope === 'installation'
+      || (target?.scope === 'profile' && parentRoutes.activeProfile)
+    const after = join(dirname(profilesDir), 'package.json')
+    const route: ResolutionRoute = eligible
+      ? { kind: 'fallback', entry: target, after }
+      : { kind: 'after-fallback', parent: after }
+    const state: ResolutionRouteState = { route }
+    if (route.kind === 'fallback') requests.set(request, state)
+    return state
+  }
+
+  private routeLocalPackage(
+    request: string, parentRoutes: ParentRoutes, generation: CompiledGeneration,
+  ): ResolutionRouteState | undefined {
+    const name = barePackageName(request)
+    if (name === undefined || !parentRoutes.activeProfile || !generation.localPackageNames.has(name)) return undefined
+    const state = { route: { kind: 'native' as const } }
+    parentRoutes.requests.set(request, state)
+    return state
+  }
+
+  routeUrl(request: string, parentURL: string): ResolutionRouteState | undefined {
+    const generation = this.current
+    let parentRoutes = generation.esmRoutes.get(parentURL)
+    if (parentRoutes === false) return undefined
+    const cached = parentRoutes?.requests.get(request)
+    if (cached !== undefined) return cached
+    if (parentRoutes === undefined) {
+      const profileIndex = generation.profileUrls.findIndex(prefix => parentURL.startsWith(prefix))
+      const activeProfileIndex = generation.activeProfileUrls.findIndex(prefix => parentURL.startsWith(prefix))
+      if (profileIndex < 0 && activeProfileIndex < 0) {
+        generation.esmRoutes.set(parentURL, false)
+        return undefined
+      }
+      let parent: string
+      try {
+        parent = fileURLToPath(parentURL)
+      } catch {
+        generation.esmRoutes.set(parentURL, false)
+        return undefined
+      }
+      const profileRoot = profileIndex >= 0
+        ? generation.profilePaths[profileIndex]
+        : generation.profile[activeProfileIndex]
+      /* v8 ignore next -- one matching index was established above */
+      if (profileRoot === undefined) return undefined
+      parentRoutes = {
+        parent,
+        profilesDir: profileRoot.slice(0, -1),
+        activeProfile: activeProfileIndex >= 0,
+        requests: new Map(),
+      }
+      generation.esmRoutes.set(parentURL, parentRoutes)
+    }
+    const local = this.routeLocalPackage(request, parentRoutes, generation)
+    if (local !== undefined) return local
+    return this.routeScoped(request, parentRoutes, generation, 'esm')
+  }
+
+  routePath(
+    request: string, parent: string, nativeResolve?: (searchPaths: readonly string[]) => string, cacheable = false,
+  ): ResolutionRouteState | undefined {
+    const generation = this.current
+    let parentRoutes = generation.cjsRoutes.get(parent)
+    if (parentRoutes === false) return undefined
+    const cached = parentRoutes?.requests.get(request)
+    if (cached !== undefined) return cached
+    if (parentRoutes === undefined) {
+      const profilesDir = generation.profilePaths.find(prefix => parent.startsWith(prefix))
+      const activeProfile = generation.profile.find(prefix => parent.startsWith(prefix))
+      if (profilesDir !== undefined || activeProfile !== undefined) {
+        const profileRoot = profilesDir ?? activeProfile
+        /* v8 ignore next -- one matching root was established above */
+        if (profileRoot === undefined) return undefined
+        parentRoutes = {
+          parent,
+          profilesDir: profileRoot.slice(0, -1),
+          activeProfile: activeProfile !== undefined,
+          requests: new Map(),
+        }
+        generation.cjsRoutes.set(parent, parentRoutes)
+      }
+    }
+    if (parentRoutes === undefined) {
+      generation.cjsRoutes.set(parent, false)
+      return undefined
+    }
+    return this.routeScoped(request, parentRoutes, generation, 'cjs', nativeResolve, cacheable)
+  }
+
+  explicitRoute(
+    request: string, paths: readonly string[],
+  ): { index: number; parent: string } | undefined {
+    if (barePackageName(request) === undefined) return undefined
+    for (const [index, path] of paths.entries()) {
+      const parent = join(resolve(path), '.dsh-profile-resolution.cjs')
+      if (startsWithin(parent, this.current.profilePaths) || startsWithin(parent, this.current.profile)) {
+        return { index, parent }
+      }
+    }
+    return undefined
+  }
+
+  nativeSelfReference(request: string, parent: string): boolean {
+    const name = barePackageName(request)
+    if (name === undefined) return false
+    const self = selfReferenceName(parent)
+    return self === name || self === null
+  }
+
+  packageDir(specifier: string, parentURL: string): string | undefined {
+    const name = barePackageName(specifier)
+    if (name === undefined) return undefined
+    const state = this.routeUrl(specifier, parentURL)
+    if (state?.route.kind === 'fallback') return state.route.entry.packageDir
+    if (state?.packageDir !== undefined) return state.packageDir
+    let parent: string
+    try {
+      parent = state?.route.kind === 'after-fallback' ? state.route.parent : fileURLToPath(parentURL)
+    } catch {
+      return undefined
+    }
+    const found = nativePackageDir(parent, name)
+    if (state !== undefined && found !== undefined) state.packageDir = found
+    return found
+  }
+}
+
+function internalModules(): InternalModules {
+  const require = createRequire(import.meta.url)
+  const addon = require('node-addon-require-builtin') as { requireBuiltin(moduleId: string): unknown }
+  const esmModule = addon.requireBuiltin('internal/modules/esm/loader') as {
+    getOrInitializeCascadedLoader(): ModuleLoaderV1 | ModuleLoaderV2
+  }
+  const cjsModule = addon.requireBuiltin('internal/modules/cjs/loader') as { Module: CommonJsModule }
+  const cjsHelpers = addon.requireBuiltin('internal/modules/helpers') as {
+    getCjsConditions(): ReadonlySet<string>
+  }
+  const esmUtils = addon.requireBuiltin('internal/modules/esm/utils') as {
+    getDefaultConditions(): readonly string[]
+  }
+  const esmResolve = addon.requireBuiltin('internal/modules/esm/resolve') as {
+    defaultResolve(
+      specifier: string,
+      context: { parentURL?: string; conditions?: readonly string[] },
+    ): ResolveResult
+  }
+  const esm = esmModule.getOrInitializeCascadedLoader()
+  const modern = 'getOrCreateModuleJob' in esm
+  /* v8 ignore start -- the supported Node 22/24/26 matrix validates each available Internal interface */
+  if (typeof esm.resolveSync !== 'function'
+    || typeof Reflect.get(esm, modern ? 'getOrCreateModuleJob' : 'getModuleJobForImport') !== 'function'
+    || (!modern && typeof Reflect.get(esm, 'resolve') !== 'function')
+    || typeof cjsModule.Module._resolveFilename !== 'function'
+    || typeof cjsHelpers.getCjsConditions !== 'function'
+    || typeof esmUtils.getDefaultConditions !== 'function'
+    || typeof esmResolve.defaultResolve !== 'function') {
+    throw new Error('profile resolution: unsupported Node module loader')
+  }
+  /* v8 ignore stop */
+  return {
+    esm,
+    esmDefaultResolve: (specifier, context) => esmResolve.defaultResolve(specifier, context),
+    esmConditions: esmUtils.getDefaultConditions(),
+    cjs: cjsModule.Module,
+    cjsConditions: cjsHelpers.getCjsConditions(),
+    modern,
+  }
+}
+
+function throwWithImporter(error: unknown, routedParent: string, parent: string): never {
+  const code = (error as NodeJS.ErrnoException).code
+  if (error instanceof Error && (code === 'ERR_MODULE_NOT_FOUND' || code === 'ERR_PACKAGE_PATH_NOT_EXPORTED')) {
+    const routedPath = fileURLToPath(routedParent)
+    const parentPath = fileURLToPath(parent)
+    const originalMessage = error.message
+    const message = originalMessage.replaceAll(routedParent, parent).replaceAll(routedPath, parentPath)
+    const stack = error.stack
+    error.message = message
+    /* v8 ignore next -- Node's resolver errors always carry a stack */
+    if (stack !== undefined) error.stack = stack.replace(originalMessage, message)
+  }
+  throw error
+}
+
+function throwWithoutCjsAnchor(error: unknown, anchor: string): never {
+  const resolved = error as NodeJS.ErrnoException & { requireStack?: string[] }
+  const requireStack = resolved.requireStack
+  if (error instanceof Error
+    && resolved.code === 'MODULE_NOT_FOUND'
+    && requireStack?.[0] !== undefined
+    && sameResolution(requireStack[0], anchor)) {
+    const originalMessage = error.message
+    const originalBlock = `\nRequire stack:\n${requireStack.map(path => `- ${path}`).join('\n')}`
+    const remaining = requireStack.slice(1)
+    /* v8 ignore next -- routed calls always retain the original importing module */
+    const replacement = remaining.length === 0
+      ? ''
+      : `\nRequire stack:\n${remaining.map(path => `- ${path}`).join('\n')}`
+    error.message = originalMessage.replace(originalBlock, replacement)
+    resolved.requireStack = remaining
+    const stack = error.stack
+    /* v8 ignore next -- Node's resolver errors always carry a stack */
+    if (stack !== undefined) error.stack = stack.replace(originalMessage, error.message)
+  }
+  throw error
+}
+
+function assertEquivalent(actual: string, expected: string, request: string, parent: string): void {
+  if (sameResolution(actual, expected)) return
+  throw new Error(
+    `profile resolution mismatch for ${JSON.stringify(request)} from ${parent}: disk resolved ${actual}, generation resolved ${expected}`,
+  )
+}
+
+function assertOptionalEquivalent(
+  actual: string | undefined, expected: string | undefined, request: string, parent: string,
+): void {
+  if (actual === undefined && expected === undefined) return
+  if (actual !== undefined && expected !== undefined && sameResolution(actual, expected)) return
+  throw new Error(
+    `profile resolution mismatch for ${JSON.stringify(request)} from ${parent}: disk selected ${actual ?? 'nothing'}, generation selected ${expected ?? 'nothing'}`,
+  )
+}
+
+/**
+ * Install one profile generation on Node's default ESM and CommonJS resolvers.
+ * @param generation - complete package table and profile scope.
+ * @param behavior - enforce the generation, or verify a materialized generation.
+ * @returns a registration that replaces the generation or restores the native methods.
+ */
+export function installProfileResolution(
+  generation: ProfileResolutionGeneration,
+  behavior: ProfileResolutionBehavior = 'enforce',
+): ProfileResolutionRegistration {
+  const router = new ResolutionRouter(generation)
+  const { esm, esmDefaultResolve, esmConditions, cjs, cjsConditions, modern } = internalModules()
+  const esmScope = new Map<string, boolean>()
+  const profilePaths = [
+    ...prefixes(generation.profilesDir),
+    ...(generation.profileDir === undefined ? [] : prefixes(generation.profileDir)),
+  ]
+  const profileUrls = profilePaths.map(path => pathToFileURL(path).href)
+  let recentEsmParent: string | undefined
+  let recentEsmScoped = false
+  let delegatedEsm: { parent: string | undefined; request: string } | undefined
+
+  const adaptEsm = (native: EsmResolve): EsmResolve => {
+    const adapted: EsmResolve = (request, parent, attributes) => {
+      const delegated = delegatedEsm
+      /* v8 ignore next -- reentry requires a separate synchronous Node hook; supported launches install none */
+      if (delegated !== undefined && delegated.parent === parent && delegated.request === request) {
+        return native(request, parent, attributes)
+      }
+      if (parent === undefined) return native(request, parent, attributes)
+      let scoped = recentEsmParent === parent ? recentEsmScoped : esmScope.get(parent)
+      if (scoped === undefined) {
+        scoped = startsWithin(parent, profileUrls)
+        esmScope.set(parent, scoped)
+      }
+      if (recentEsmParent !== parent) {
+        recentEsmParent = parent
+        recentEsmScoped = scoped
+      }
+      if (!scoped) return native(request, parent, attributes)
+      const state = router.routeUrl(request, parent)
+      if (state === undefined) {
+        const target = request[0] === '#'
+          ? packageImportsTarget(fileURLToPath(parent), request, esmConditions)
+          : undefined
+        if (target === undefined) return native(request, parent, attributes)
+        const restoreImporter = (error: unknown): never => throwWithImporter(error, target.parentURL, parent)
+        let expected: ResolveResult | Promise<ResolveResult>
+        try {
+          expected = adapted(target.specifier, target.parentURL, attributes)
+          /* v8 ignore next -- Node 24+ resolves synchronously; the Node 22 matrix covers its Promise result */
+          if (expected instanceof Promise) expected = expected.catch(restoreImporter)
+        } catch (error) {
+          return restoreImporter(error)
+        }
+        if (behavior === 'enforce') return expected
+        const actual = native(request, parent, attributes)
+        /* v8 ignore start -- Node 22 is the asynchronous adapter and is covered by the external version matrix */
+        if (expected instanceof Promise || actual instanceof Promise) {
+          return Promise.all([actual, expected]).then(([resolved, wanted]) => {
+            assertEquivalent(resolved.url, wanted.url, request, parent)
+            return resolved
+          })
+        }
+        /* v8 ignore stop */
+        assertEquivalent(actual.url, expected.url, request, parent)
+        return actual
+      }
+      const cacheable = attributes === EMPTY_ATTRIBUTES || Object.keys(attributes).length === 0
+      if (cacheable && state.esm !== undefined) return state.esm
+      const route = state.route
+      if (route.kind === 'native') {
+        const result = native(request, parent, attributes)
+        if (cacheable && !(result instanceof Promise)) state.esm = result
+        return result
+      }
+      const routedParent = pathToFileURL(route.kind === 'fallback' ? route.entry.declarer : route.parent).href
+      if (behavior === 'enforce') {
+        const previous = delegatedEsm
+        delegatedEsm = { parent: routedParent, request }
+        const restoreImporter = (error: unknown): never => throwWithImporter(error, routedParent, parent)
+        try {
+          let result: ResolveResult | Promise<ResolveResult>
+          try {
+            result = native(request, routedParent, attributes)
+          } catch (error) {
+            return restoreImporter(error)
+          }
+          /* v8 ignore next -- Node 24+ resolves synchronously; the Node 22 matrix covers its Promise result */
+          if (result instanceof Promise) return result.catch(restoreImporter)
+          if (cacheable) state.esm = result
+          return result
+        } finally {
+          delegatedEsm = previous
+        }
+      }
+      const actual = native(request, parent, attributes)
+      const previous = delegatedEsm
+      delegatedEsm = { parent: routedParent, request }
+      const restoreImporter = (error: unknown): never => throwWithImporter(error, routedParent, parent)
+      try {
+        let expected: ResolveResult | Promise<ResolveResult>
+        try {
+          const result = native(request, routedParent, attributes)
+          expected = result
+          /* v8 ignore next -- Node 24+ resolves synchronously; the Node 22 matrix covers its Promise result */
+          if (result instanceof Promise) expected = result.catch(restoreImporter)
+        } catch (error) {
+          return restoreImporter(error)
+        }
+        /* v8 ignore start -- Node 22 is the asynchronous adapter and is covered by the external version matrix */
+        if (expected instanceof Promise || actual instanceof Promise) {
+          return Promise.all([actual, expected]).then(([resolved, wanted]) => {
+            assertEquivalent(resolved.url, wanted.url, request, parent)
+            if (cacheable) state.esm = resolved
+            return resolved
+          })
+        }
+        /* v8 ignore stop */
+        assertEquivalent(actual.url, expected.url, request, parent)
+        if (cacheable) state.esm = actual
+        return actual
+      } finally {
+        delegatedEsm = previous
+      }
+    }
+    return adapted
+  }
+
+  let restoreEsm: () => void
+  /* v8 ignore else -- CI coverage runs Node 24 v2; the Node 22 matrix exercises the v1 adapter */
+  if (modern) {
+    const loader = esm as ModuleLoaderV2
+    const original = Reflect.get(loader, 'resolveSync')
+    const resolveRequest = adaptEsm((request, parent, attributes) => original.call(
+      loader, parent as string, { specifier: request, attributes },
+    ))
+    // Node 24.12+ adds skipSyncHooks after request. Its presence marks hook
+    // delegation whose outer call already selected a route.
+    const wrapped = (parent: string, request: { specifier: string; attributes?: ImportAttributes }, ...rest: unknown[]): ResolveResult => (
+      rest.length
+        ? Reflect.apply(original, loader, [parent, request, ...rest]) as ResolveResult
+        : resolveRequest(request.specifier, parent, request.attributes ?? EMPTY_ATTRIBUTES) as ResolveResult
+    )
+    loader.resolveSync = wrapped
+    restoreEsm = () => {
+      /* v8 ignore else -- registrations are disposed in reverse installation order */
+      if (loader.resolveSync === wrapped) loader.resolveSync = original
+    }
+  } else {
+    const loader = esm as ModuleLoaderV1
+    const original = Reflect.get(loader, 'resolve')
+    const originalSync = Reflect.get(loader, 'resolveSync')
+    const resolveRequest = adaptEsm((request, parent, attributes) => original.call(loader, request, parent as string, attributes))
+    const resolveRequestSync = adaptEsm((request, parent, attributes) => originalSync.call(loader, request, parent as string, attributes))
+    const wrapped = (request: string, parent: string, attributes: ImportAttributes = EMPTY_ATTRIBUTES): Promise<ResolveResult> => (
+      resolveRequest(request, parent, attributes) as Promise<ResolveResult>
+    )
+    const wrappedSync = (request: string, parent: string, attributes: ImportAttributes = EMPTY_ATTRIBUTES): ResolveResult => (
+      resolveRequestSync(request, parent, attributes) as ResolveResult
+    )
+    loader.resolve = wrapped
+    loader.resolveSync = wrappedSync
+    restoreEsm = () => {
+      if (loader.resolve === wrapped) loader.resolve = original
+      if (loader.resolveSync === wrappedSync) loader.resolveSync = originalSync
+    }
+  }
+
+  const originalFilename = Reflect.get(cjs, '_resolveFilename')
+  let delegatedCjs = 0
+  const resolveRoutedCjs = (
+    request: string, routed: Exclude<ResolutionRoute, { kind: 'native' }>,
+    parent: CommonJsParent, main: boolean, options?: CommonJsOptions,
+  ): string => {
+    const anchor = routed.kind === 'fallback' ? routed.entry.declarer : routed.parent
+    const synthetic = new cjs(anchor)
+    // Late parent assignment preserves Node's require stack without publishing this routing anchor in parent.children.
+    synthetic.parent = parent
+    synthetic.filename = anchor
+    synthetic.paths = routed.kind === 'fallback'
+      ? packageSearchPaths(routed.entry, request, cjs)
+      : cjs._nodeModulePaths(dirname(anchor))
+    try {
+      return originalFilename.call(cjs, request, synthetic, main, options)
+    } catch (error) {
+      return throwWithoutCjsAnchor(error, anchor)
+    }
+  }
+  const resolveNativeCjs = (
+    request: string, searchPaths: readonly string[], parent: CommonJsParent,
+    parentFilename: string, main: boolean, conditions: ReadonlySet<string> | undefined,
+  ): string => {
+    const synthetic = new cjs(parentFilename)
+    synthetic.parent = parent
+    synthetic.filename = parentFilename
+    synthetic.paths = [...searchPaths]
+    const options = conditions === undefined ? undefined : { conditions }
+    return originalFilename.call(cjs, request, synthetic, main, options)
+  }
+  const resolvePackageImportCjs = (
+    target: { specifier: string; parentURL: string }, conditions: Iterable<string>,
+  ): string => {
+    const state = router.routeUrl(target.specifier, target.parentURL)
+    const resolveFrom = (parentURL: string): string => fileURLToPath(esmDefaultResolve(
+      target.specifier, { parentURL, conditions: [...conditions] },
+    ).url)
+    /* v8 ignore next -- the target manifest was found inside the established profile scope */
+    if (state === undefined) return resolveFrom(target.parentURL)
+    if (state.route.kind === 'native') return resolveFrom(target.parentURL)
+    const route = state.route
+    if (route.kind === 'after-fallback') return resolveFrom(pathToFileURL(route.parent).href)
+    return resolveFrom(pathToFileURL(route.entry.declarer).href)
+  }
+  const wrappedFilename: CommonJsModule['_resolveFilename'] = (request, parent, main, options) => {
+    if (delegatedCjs || !parent?.filename) {
+      return originalFilename.call(cjs, request, parent, main, options)
+    }
+    const parentFilename = parent.filename
+    const cacheable = options?.paths === undefined && options?.conditions === undefined
+    const explicitPaths = Array.isArray(options?.paths) ? options.paths : undefined
+    if (explicitPaths !== undefined && router.nativeSelfReference(request, parentFilename)) {
+      return originalFilename.call(cjs, request, parent, main, options)
+    }
+    const explicit = explicitPaths === undefined
+      ? undefined
+      : router.explicitRoute(request, explicitPaths)
+    if (options?.paths !== undefined && explicit === undefined) {
+      return originalFilename.call(cjs, request, parent, main, options)
+    }
+    if (explicit !== undefined && explicitPaths !== undefined && explicit.index > 0) {
+      try {
+        return originalFilename.call(cjs, request, parent, main, {
+          ...options,
+          paths: explicitPaths.slice(0, explicit.index),
+        })
+      } catch (error) {
+        if (!isUnselectedPackageMiss(error)) throw error
+      }
+    }
+    const state = router.routePath(
+      request,
+      explicit?.parent ?? parentFilename,
+      searchPaths => resolveNativeCjs(request, searchPaths, parent, parentFilename, main, options?.conditions),
+      explicit === undefined && cacheable,
+    )
+    if (state === undefined) {
+      const scoped = startsWithin(parentFilename, profilePaths)
+      const conditions = options?.conditions ?? cjsConditions
+      const target = request[0] === '#' && scoped
+        ? packageImportsTarget(parentFilename, request, conditions)
+        : undefined
+      if (target === undefined) return originalFilename.call(cjs, request, parent, main, options)
+      const expected = resolvePackageImportCjs(target, conditions)
+      if (behavior === 'enforce') return expected
+      const actual = originalFilename.call(cjs, request, parent, main, options)
+      assertEquivalent(actual, expected, request, parentFilename)
+      return actual
+    }
+    if (cacheable && state.cjs !== undefined) return state.cjs
+    const route = state.route
+    if (route.kind === 'native') {
+      const result = originalFilename.call(cjs, request, parent, main, options)
+      if (cacheable) state.cjs = result
+      return result
+    }
+    if (route.kind === 'after-fallback' && explicit !== undefined && explicitPaths !== undefined) {
+      try {
+        return originalFilename.call(cjs, request, parent, main, {
+          ...options,
+          paths: [dirname(route.parent)],
+        })
+      } catch (error) {
+        if (!isUnselectedPackageMiss(error)) throw error
+        const remaining = explicitPaths.slice(explicit.index + 1)
+        if (remaining.length === 0) throw error
+        return wrappedFilename(request, parent, main, { ...options, paths: remaining })
+      }
+    }
+    delegatedCjs++
+    try {
+      const routedOptions = options?.conditions === undefined ? undefined : { conditions: options.conditions }
+      let expected: string
+      try {
+        expected = resolveRoutedCjs(request, route, parent, main, routedOptions)
+      } catch (error) {
+        if (route.kind !== 'fallback' || !isUnselectedPackageMiss(error)) throw error
+        try {
+          expected = resolveRoutedCjs(
+            request, { kind: 'after-fallback', parent: route.after }, parent, main, routedOptions,
+          )
+        } catch (afterError) {
+          const remaining = explicit === undefined || explicitPaths === undefined
+            ? []
+            : explicitPaths.slice(explicit.index + 1)
+          if (!isUnselectedPackageMiss(afterError) || remaining.length === 0) {
+            throw afterError
+          }
+          delegatedCjs--
+          try {
+            return wrappedFilename(request, parent, main, { ...options, paths: remaining })
+          } finally {
+            delegatedCjs++
+          }
+        }
+      }
+      if (behavior === 'enforce') {
+        if (cacheable) state.cjs = expected
+        return expected
+      }
+      const actual = originalFilename.call(cjs, request, parent, main, options)
+      assertEquivalent(actual, expected, request, parentFilename)
+      if (cacheable) state.cjs = actual
+      return actual
+    } finally {
+      delegatedCjs--
+    }
+  }
+  cjs._resolveFilename = wrappedFilename
+
+  return {
+    packageDir(specifier, parentURL) {
+      const expected = router.packageDir(specifier, parentURL)
+      if (behavior !== 'verify' || !startsWithin(parentURL, profileUrls)) return expected
+      const name = barePackageName(specifier)
+      if (name === undefined) return expected
+      let parent: string
+      try {
+        parent = fileURLToPath(parentURL)
+      } catch {
+        return expected
+      }
+      const actual = nativePackageDir(parent, name)
+      assertOptionalEquivalent(actual, expected, specifier, parentURL)
+      return expected
+    },
+    replace(next) { router.replace(next) },
+    dispose() {
+      /* v8 ignore else -- registrations are disposed in reverse installation order */
+      if (cjs._resolveFilename === wrappedFilename) cjs._resolveFilename = originalFilename
+      restoreEsm()
+    },
+  }
+}
+
+/**
+ * Publish one generation for Harness-owned Workers.
+ * @param generation - complete package table and profile scope.
+ * @param behavior - enforce or verify the generation in newly created Workers.
+ * @returns a disposer restoring the previous thread environment data.
+ */
+export function registerWorkerResolution(
+  generation: ProfileResolutionGeneration,
+  behavior: ProfileResolutionBehavior = 'enforce',
+): () => void {
+  const previous = getEnvironmentData(WORKER_RESOLUTION_KEY)
+  setEnvironmentData(WORKER_RESOLUTION_KEY, { generation, behavior })
+  return () => { setEnvironmentData(WORKER_RESOLUTION_KEY, previous) }
+}
diff --git a/packages/boot/app-boot/src/profile-resolution/service.ts b/packages/boot/app-boot/src/profile-resolution/service.ts
new file mode 100644
index 0000000000..3281f42ce5
--- /dev/null
+++ b/packages/boot/app-boot/src/profile-resolution/service.ts
@@ -0,0 +1,117 @@
+/** Package metadata resolved through one profile resolution registration. */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { Service, type Context } from '@deepseek-ai/cordis'
+import {
+  barePackageName,
+  installProfileResolution,
+  registerWorkerResolution,
+  type ProfileResolutionBehavior,
+  type ProfileResolutionRegistration,
+} from './resolver.ts'
+import type { ProfileResolutionGeneration } from '../profile.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** Deterministic package lookup for configured plugin specifiers. */
+    pluginPackages: PluginPackages
+  }
+}
+
+/** The package that owns a resolved module. */
+export interface PluginPackage {
+  /** Manifest package name. */
+  name: string
+  /** Manifest version when declared. */
+  version: string | undefined
+  /** Absolute package directory. */
+  dir: string
+  /** Absolute package.json path. */
+  manifestPath: string
+  /** Parsed manifest shared by metadata readers. */
+  manifest: Record<string, unknown>
+}
+
+/** Optional runtime resolver installed and owned by {@link PluginPackages}. */
+export interface PluginPackagesConfig {
+  /** Complete package table; omit it to expose native package lookup only. */
+  generation?: ProfileResolutionGeneration
+  /** Enforce the table or compare it with a materialized fallback. */
+  behavior?: ProfileResolutionBehavior
+}
+
+function readPackage(dir: string, fallbackName: string): PluginPackage | undefined {
+  const manifestPath = join(dir, 'package.json')
+  if (!existsSync(manifestPath)) return undefined
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Record<string, unknown>
+  const name = manifest.name
+  const version = manifest.version
+  return {
+    name: typeof name === 'string' ? name : fallbackName,
+    version: typeof version === 'string' ? version : undefined,
+    dir,
+    manifestPath,
+    manifest,
+  }
+}
+
+/** Package lookup shared by metadata consumers in one profile process. */
+export class PluginPackages extends Service {
+  private packages = new Map<string, PluginPackage | undefined>()
+  private readonly resolver: ProfileResolutionRegistration | undefined
+  private readonly behavior: ProfileResolutionBehavior
+  private disposeWorkerResolution: (() => void) | undefined
+
+  constructor(ctx: Context, config: PluginPackagesConfig = {}) {
+    super(ctx, 'pluginPackages')
+    this.behavior = config.behavior ?? 'enforce'
+    if (config.generation === undefined) return
+    const resolver = installProfileResolution(config.generation, this.behavior)
+    this.disposeWorkerResolution = registerWorkerResolution(config.generation, this.behavior)
+    this.resolver = resolver
+    ctx.effect(() => () => {
+      this.disposeWorkerResolution?.()
+      resolver.dispose()
+    }, 'profile package resolution')
+  }
+
+  /**
+   * Publish an additive generation for this process and subsequently created Workers.
+   * @param generation - fully constructed successor generation.
+   */
+  replace(generation: ProfileResolutionGeneration): void {
+    if (this.resolver === undefined) throw new Error('plugin-packages: runtime resolution is not installed')
+    this.resolver.replace(generation)
+    this.packages = new Map()
+    this.disposeWorkerResolution?.()
+    this.disposeWorkerResolution = registerWorkerResolution(generation, this.behavior)
+  }
+
+  /**
+   * Locate the package named by a specifier without requiring a package export.
+   * @param specifier - module specifier whose package owns the requested module.
+   * @param parentURL - URL whose Node lookup order applies.
+   * @returns the parsed package, or undefined when no package owns the request.
+   */
+  packageOf(specifier: string, parentURL: string): PluginPackage | undefined {
+    const name = barePackageName(specifier)
+    if (name === undefined) return undefined
+    const dir = this.resolver === undefined
+      ? packageDirFromParent(name, parentURL)
+      : this.resolver.packageDir(name, parentURL)
+    if (dir === undefined) return undefined
+    const key = JSON.stringify({ dir, name })
+    if (!this.packages.has(key)) this.packages.set(key, readPackage(dir, name))
+    return this.packages.get(key)
+  }
+}
+
+function packageDirFromParent(name: string, parentURL: string): string | undefined {
+  for (const searchPath of createRequire(parentURL).resolve.paths(name) as string[]) {
+    const candidate = join(searchPath, name)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+  }
+  return undefined
+}
diff --git a/packages/boot/app-boot/src/profile-resolution/worker-bootstrap.ts b/packages/boot/app-boot/src/profile-resolution/worker-bootstrap.ts
new file mode 100644
index 0000000000..f7258d42f3
--- /dev/null
+++ b/packages/boot/app-boot/src/profile-resolution/worker-bootstrap.ts
@@ -0,0 +1,13 @@
+/** Install an inherited profile resolution generation in one Harness-owned Worker. */
+
+import { getEnvironmentData } from 'node:worker_threads'
+import { installProfileResolution, type ProfileResolutionBehavior } from './resolver.ts'
+import type { ProfileResolutionGeneration } from '../profile.ts'
+
+const registration = getEnvironmentData(
+  '@deepseek-ai/dsh-app-boot/profile-resolution',
+) as {
+  generation: ProfileResolutionGeneration
+  behavior: ProfileResolutionBehavior
+} | undefined
+if (registration !== undefined) installProfileResolution(registration.generation, registration.behavior)
diff --git a/packages/boot/app-boot/src/profile.ts b/packages/boot/app-boot/src/profile.ts
index 4ac0e58318..793db681bb 100644
--- a/packages/boot/app-boot/src/profile.ts
+++ b/packages/boot/app-boot/src/profile.ts
@@ -25,7 +25,7 @@
 
 import { createRequire } from 'node:module'
 import {
-  existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync,
+  existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync,
   symlinkSync, unlinkSync, writeFileSync,
 } from 'node:fs'
 import { basename, dirname, join, relative, resolve } from 'node:path'
@@ -37,6 +37,14 @@ import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
 import type { DshPackageManifest, ProfilePatchReload } from '@deepseek-ai/dsh-package-manifest'
 import { resolve as resolvePackage, type Package as ResolvePackageManifest } from 'resolve.exports'
 import { loadOverlayPatches } from './index.ts'
+import {
+  canonicalLinkPath,
+  isPackagedExecutable,
+  isProfileModuleFallbackLink,
+  PROFILE_MODULE_FALLBACK_DIR,
+  realModuleDirectory,
+  symlinkPointsTo,
+} from './profile-resolution/legacy-links.ts'
 
 /** Directory under the Harness home holding every profile. */
 export const PROFILES_DIR = 'profiles'
@@ -44,9 +52,6 @@ export const PROFILES_DIR = 'profiles'
 /** The user patch layer inside a profile directory (hot-reloaded on long-lived surfaces). */
 export const PROFILE_PATCH_FILENAME = 'cordis.patch.yml'
 
-/** Profile-private package links projected into its pnpm-managed node_modules. */
-const PROFILE_MODULE_FALLBACK_DIR = '.dsh-module-fallback'
-
 /** Installation-owned defaults used when a shipped profile is first opened. */
 export interface ProfileTemplate {
   /** Ordered bundle layer list. */
@@ -86,6 +91,35 @@ export interface Profile {
   patchReload: ProfilePatchReload
 }
 
+/** One package selected by the profile module-fallback rules. */
+export interface ProfileResolutionEntry {
+  /** Bare package name. */
+  readonly name: string
+  /** Package directory selected by the existing dependency traversal. */
+  readonly packageDir: string
+  /** Selected package version when its manifest declares one. */
+  readonly version: string | undefined
+  /** Manifest whose dependency edge selected this package. */
+  readonly declarer: string
+  /** Whether every profile or only the active profile receives this fallback. */
+  readonly scope: 'installation' | 'profile'
+}
+
+/** Complete immutable fallback table for one profile launch. */
+export interface ProfileResolutionGeneration {
+  /** Directory containing every profile and the shared fallback position. */
+  readonly profilesDir: string
+  /** Active profile directory, when bundle-only fallbacks were included. */
+  readonly profileDir: string | undefined
+  /** Profile-declared packages already installed before the fallback position. */
+  readonly localPackageNames: readonly string[]
+  /** Installation entries followed by bundle-only entries in precedence order. */
+  readonly entries: readonly ProfileResolutionEntry[]
+}
+
+/** Startup backend selection for one computed profile resolution generation. */
+export type ProfileResolutionMode = 'link' | 'dual' | 'runtime'
+
 /**
  * Resolve a profile's directory under the Harness home.
  * @param name - the profile name (`dsh --profile <name>`).
@@ -234,27 +268,6 @@ function ensureSymlink(link: string, target: string): void {
   }
 }
 
-/** Resolve a link target without following the final path component. */
-function canonicalLinkPath(path: string): string | undefined {
-  try {
-    return join(realpathSync.native(dirname(path)), basename(path))
-  } catch (error) {
-    // A missing parent means the candidate cannot identify an existing owned link.
-    /* v8 ignore next 2 -- a non-ENOENT realpath failure requires a host filesystem fault */
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
-    /* v8 ignore next -- see the host-filesystem exception above */
-    throw error
-  }
-}
-
-/** Return whether a symlink or junction points at the same path as `target`. */
-function symlinkPointsTo(link: string, target: string): boolean {
-  const actual = resolve(dirname(link), readlinkSync(link))
-  const canonicalActual = canonicalLinkPath(actual)
-  const canonicalTarget = canonicalLinkPath(resolve(target))
-  return canonicalActual !== undefined && canonicalActual === canonicalTarget
-}
-
 /** Add one profile-owned fallback link without replacing a pnpm-managed entry. */
 function ensureProfileSymlink(link: string, target: string): void {
   try {
@@ -311,11 +324,6 @@ interface ModuleProxyRecord {
   dsh?: { moduleFallback?: { targets?: unknown } }
 }
 
-/** Return whether the process reads application modules from pkg's virtual filesystem. */
-function isPackagedExecutable(): boolean {
-  return (process as NodeJS.Process & { pkg?: unknown }).pkg !== undefined
-}
-
 /** Resolve one available explicit package export under Node ESM import conditions. */
 function packageEntryFromPackage(
   packageName: string,
@@ -462,11 +470,25 @@ function profileDependencyNames(manifest: ProfileManifest): string[] {
 }
 
 /** Resolve the installation generation that every profile must find through the fallback directory. */
-function resolveInstallationPackageDirectories(installAnchor: string): Map<string, string> {
+function resolveModuleFallbackEntries(
+  installAnchor: string, materialize = true,
+): {
+  entries: ModuleFallbackEntry[]
+  packageNames: ReadonlySet<string>
+  packageDirs: ReadonlyMap<string, string>
+  declarers: ReadonlyMap<string, string>
+  versions: ReadonlyMap<string, string | undefined>
+} {
   const appManifest = readModuleFallbackManifest(installAnchor)
   const links = new Map<string, string>()
+  const declarers = new Map<string, string>()
+  const versions = new Map<string, string | undefined>()
   /* v8 ignore next -- a real app manifest always declares its name */
-  if (appManifest.name !== undefined) links.set(appManifest.name, dirname(installAnchor))
+  if (appManifest.name !== undefined) {
+    links.set(appManifest.name, dirname(installAnchor))
+    declarers.set(appManifest.name, installAnchor)
+    versions.set(appManifest.name, appManifest.version)
+  }
   // BFS over the resolvable dependency graph; the visited set is the link
   // map itself (first resolution wins, matching Node's own nearest-wins).
   const queue: { anchor: string; manifest: ProfileManifest }[] = [{ anchor: installAnchor, manifest: appManifest }]
@@ -482,27 +504,24 @@ function resolveInstallationPackageDirectories(installAnchor: string): Map<strin
       // plugin; skip it rather than fail the whole boot.
       if (dir === undefined) continue
       links.set(dep, dir)
+      declarers.set(dep, next.anchor)
       const manifestPath = join(dir, 'package.json')
-      queue.push({ anchor: manifestPath, manifest: readModuleFallbackManifest(manifestPath) })
+      const manifest = readModuleFallbackManifest(manifestPath)
+      versions.set(dep, manifest.version)
+      queue.push({ anchor: manifestPath, manifest })
     }
   }
-  return links
-}
-
-/** Resolve installation packages as filesystem links or packaged-executable proxies. */
-function resolveModuleFallbackEntries(
-  installAnchor: string,
-): { entries: ModuleFallbackEntry[]; packageNames: ReadonlySet<string> } {
-  const links = resolveInstallationPackageDirectories(installAnchor)
-  const entries = !isPackagedExecutable()
-    ? [...links].map(([packageName, packageDir]) => ({ kind: 'symlink' as const, packageName, packageDir }))
-    : [...links].flatMap(([packageName, packageDir]) => {
-      const source = packageProxySource(packageName, packageDir)
-      return Object.keys(source.targets).length === 0
-        ? []
-        : [{ kind: 'proxy' as const, packageName, version: source.version, targets: source.targets }]
-    })
-  return { entries, packageNames: new Set(links.keys()) }
+  const entries = !materialize
+    ? []
+    : !isPackagedExecutable()
+      ? [...links].map(([packageName, packageDir]) => ({ kind: 'symlink' as const, packageName, packageDir }))
+      : [...links].flatMap(([packageName, packageDir]) => {
+        const source = packageProxySource(packageName, packageDir)
+        return Object.keys(source.targets).length === 0
+          ? []
+          : [{ kind: 'proxy' as const, packageName, version: source.version, targets: source.targets }]
+      })
+  return { entries, packageNames: new Set(links.keys()), packageDirs: links, declarers, versions }
 }
 
 /** Return whether one existing fallback entry already matches its resolved installation generation. */
@@ -536,6 +555,8 @@ export interface ProfileModuleFallbackOptions {
   profile?: Profile
   /** Harness home; defaults to {@link resolveDshHome}. */
   home?: string
+  /** Whether to materialize the computed generation; defaults to true. */
+  materialize?: boolean
 }
 
 /**
@@ -548,21 +569,71 @@ export interface ProfileModuleFallbackOptions {
  * `node_modules`; pnpm-managed entries remain authoritative, and another
  * profile's links cannot change its resolution.
  * @param options - installation anchor, optional loaded profile, and Harness home.
- * @returns settlement after the shared fallback and profile-local links are current.
+ * @returns the computed fallback generation after optional materialization.
  */
-export async function healProfilesModuleFallback(options: ProfileModuleFallbackOptions): Promise<void> {
-  const { installAnchor, profile, home = resolveDshHome() } = options
+export async function healProfilesModuleFallback(
+  options: ProfileModuleFallbackOptions,
+): Promise<ProfileResolutionGeneration> {
+  const { installAnchor, profile, home = resolveDshHome(), materialize = true } = options
   const profilesDir = join(home, PROFILES_DIR)
   const modulesDir = join(profilesDir, 'node_modules')
-  mkdirSync(modulesDir, { recursive: true })
-  const { entries, packageNames } = resolveModuleFallbackEntries(installAnchor)
-  if (!moduleFallbackCurrent(modulesDir, entries)) {
+  if (materialize) mkdirSync(modulesDir, { recursive: true })
+  const { entries, packageNames, packageDirs, declarers, versions } = resolveModuleFallbackEntries(installAnchor, materialize)
+  if (materialize && !moduleFallbackCurrent(modulesDir, entries)) {
     await withFileLock(modulesDir, () => {
       if (!moduleFallbackCurrent(modulesDir, entries)) healProfilesModuleFallbackLocked(entries, modulesDir)
       return Promise.resolve()
     })
   }
-  if (profile !== undefined) healProfileModuleFallback(profile, packageNames)
+  const profileDeclarers = new Map<string, string>()
+  const profileVersions = new Map<string, string | undefined>()
+  const localPackageNames = profile === undefined ? [] : installedProfilePackageNames(profile)
+  const profilePackages: ReadonlyMap<string, string> = profile === undefined
+    ? new Map<string, string>()
+    : healProfileModuleFallback(profile, packageNames, materialize, profileDeclarers, profileVersions)
+  return Object.freeze({
+    profilesDir,
+    profileDir: profile?.dir,
+    localPackageNames: Object.freeze(localPackageNames),
+    entries: Object.freeze([
+      ...[...packageDirs].map(([name, packageDir]) => Object.freeze({
+        name, packageDir, version: versions.get(name),
+        declarer: declarers.get(name) as string, scope: 'installation' as const,
+      })),
+      ...[...profilePackages].map(([name, packageDir]) => Object.freeze({
+        name, packageDir, version: profileVersions.get(name),
+        declarer: profileDeclarers.get(name) as string, scope: 'profile' as const,
+      })),
+    ]),
+  })
+}
+
+/** Return installed direct dependencies that Node resolves before profile fallback. */
+function installedProfilePackageNames(profile: Profile): string[] {
+  let manifest: ProfileManifest
+  try {
+    manifest = readModuleFallbackManifest(join(profile.dir, 'package.json'))
+  } catch (error) {
+    // Direct helper callers can supply a synthetic Profile without its on-disk manifest.
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw error
+  }
+  return profileDependencyNames(manifest).filter((name) => {
+    const candidate = join(profile.dir, 'node_modules', name)
+    if (!existsSync(join(candidate, 'package.json'))) return false
+    return !isProfileModuleFallbackLink(profile.dir, name)
+  })
+}
+
+/**
+ * Compute a profile resolution generation without materializing links or proxies.
+ * @param options - installation anchor, profile, and optional Harness home.
+ * @returns the complete immutable generation.
+ */
+export function createProfileResolutionGeneration(
+  options: Omit<ProfileModuleFallbackOptions, 'materialize'>,
+): Promise<ProfileResolutionGeneration> {
+  return healProfilesModuleFallback({ ...options, materialize: false })
 }
 
 /**
@@ -572,8 +643,8 @@ export async function healProfilesModuleFallback(options: ProfileModuleFallbackO
  * @param options - owning installation package.json and the loaded application profile.
  */
 export function healIsolatedProfileModuleFallback(options: { installAnchor: string; profile: Profile }): void {
-  const installationLinks = resolveInstallationPackageDirectories(options.installAnchor)
-  healProfileModuleFallback(options.profile, new Set(installationLinks.keys()), installationLinks)
+  const installationLinks = resolveModuleFallbackEntries(options.installAnchor, false).packageDirs
+  healProfileModuleFallback(options.profile, new Set(installationLinks.keys()), true, undefined, undefined, installationLinks)
 }
 
 /**
@@ -606,17 +677,21 @@ function healProfilesModuleFallbackLocked(entries: readonly ModuleFallbackEntry[
 function dependencyClosure(
   anchors: readonly string[], reserved: ReadonlySet<string>,
   exclude: (candidate: string, packageName: string) => boolean,
+  declarers?: Map<string, string>,
+  versions?: Map<string, string | undefined>,
 ): Map<string, string> {
   const links = new Map<string, string>()
   const visited = new Set(reserved)
   for (const anchor of anchors) {
-    const canonicalAnchor = realpathSync.native(anchor)
+    const canonicalAnchor = join(realModuleDirectory(dirname(anchor)), basename(anchor))
     const manifest = readModuleFallbackManifest(canonicalAnchor)
     /* v8 ignore next -- an installable package manifest always declares its name */
     if (manifest.name === undefined) continue
     if (!visited.has(manifest.name)) {
       visited.add(manifest.name)
       links.set(manifest.name, dirname(canonicalAnchor))
+      declarers?.set(manifest.name, canonicalAnchor)
+      versions?.set(manifest.name, manifest.version)
     }
     const queue: { anchor: string; manifest: ProfileManifest }[] = [{ anchor: canonicalAnchor, manifest }]
     for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
@@ -629,8 +704,11 @@ function dependencyClosure(
         if (dir === undefined) continue
         visited.add(dep)
         links.set(dep, dir)
+        declarers?.set(dep, next.anchor)
         const manifestPath = join(dir, 'package.json')
-        queue.push({ anchor: manifestPath, manifest: readModuleFallbackManifest(manifestPath) })
+        const dependencyManifest = readModuleFallbackManifest(manifestPath)
+        versions?.set(dep, dependencyManifest.version)
+        queue.push({ anchor: manifestPath, manifest: dependencyManifest })
       }
     }
   }
@@ -639,13 +717,17 @@ function dependencyClosure(
 
 /** Reconcile packages carried only by selected bundles into one profile. */
 function healProfileModuleFallback(
-  profile: Profile, installationPackageNames: ReadonlySet<string>,
+  profile: Profile, installationPackageNames: ReadonlySet<string>, materialize = true,
+  declarers?: Map<string, string>,
+  versions?: Map<string, string | undefined>,
   installationLinks: ReadonlyMap<string, string> = new Map(),
-): void {
+): Map<string, string> {
   const profileModulesDir = join(profile.dir, 'node_modules')
   const ownedModulesDir = join(profile.dir, PROFILE_MODULE_FALLBACK_DIR, 'node_modules')
-  mkdirSync(profileModulesDir, { recursive: true })
-  mkdirSync(ownedModulesDir, { recursive: true })
+  if (materialize) {
+    mkdirSync(profileModulesDir, { recursive: true })
+    mkdirSync(ownedModulesDir, { recursive: true })
+  }
   const bundleAnchors = profile.layers
     .filter(layer => !installationPackageNames.has(layer.packageName))
     .map(layer => join(layer.packageDir, 'package.json'))
@@ -662,9 +744,10 @@ function healProfileModuleFallback(
       /* v8 ignore next -- see the host-filesystem exception above */
       throw error
     }
-  })
+  }, declarers, versions)
   for (const layer of profile.layers) bundleLinks.delete(layer.packageName)
   const links = new Map([...installationLinks, ...bundleLinks])
+  if (!materialize) return links
   for (const packageName of ownedPackageNames(ownedModulesDir)) {
     if (!links.has(packageName)) removeProfileSymlink(profileModulesDir, ownedModulesDir, packageName)
   }
@@ -676,6 +759,7 @@ function healProfileModuleFallback(
     mkdirSync(dirname(profileLink), { recursive: true })
     ensureProfileSymlink(profileLink, ownedLink)
   }
+  return links
 }
 
 /**
diff --git a/packages/boot/app-boot/tests/profile-resolution-service.spec.ts b/packages/boot/app-boot/tests/profile-resolution-service.spec.ts
new file mode 100644
index 0000000000..62ce14795a
--- /dev/null
+++ b/packages/boot/app-boot/tests/profile-resolution-service.spec.ts
@@ -0,0 +1,205 @@
+/** Package metadata queries share the active profile resolution generation. */
+
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { getEnvironmentData } from 'node:worker_threads'
+import { Context } from '@deepseek-ai/cordis'
+import { afterEach, describe, expect, it } from 'vitest'
+import { PluginPackages } from '../src/profile-resolution/service.ts'
+import type { ProfileResolutionGeneration } from '../src/profile.ts'
+
+const roots: string[] = []
+const contexts: Context[] = []
+
+afterEach(async () => {
+  for (const context of contexts.splice(0).reverse()) await context.fiber.dispose()
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function file(path: string, text: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, text)
+}
+
+function pkg(dir: string, version: string, name = 'metadata-lib'): string {
+  file(join(dir, 'package.json'), JSON.stringify({
+    name,
+    version,
+    type: 'module',
+    exports: { import: './index.js', require: './index.cjs' },
+  }))
+  file(join(dir, 'index.js'), `export const version = ${JSON.stringify(version)}\n`)
+  file(join(dir, 'index.cjs'), `exports.version = ${JSON.stringify(version)}\n`)
+  return join(dir, 'package.json')
+}
+
+function generation(
+  profilesDir: string, profileDir: string, packageDir: string, declarer: string, version: string,
+): ProfileResolutionGeneration {
+  return {
+    profilesDir,
+    profileDir,
+    localPackageNames: [],
+    entries: [{ name: 'metadata-lib', packageDir, version, declarer, scope: 'installation' }],
+  }
+}
+
+describe('profile package metadata service', () => {
+  it('resolves module URLs and package metadata through the current generation', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-profile-package-service-'))
+    roots.push(root)
+    const profilesDir = join(root, 'profiles')
+    const profileDir = join(profilesDir, 'test')
+    const first = join(root, 'first')
+    const firstAnchor = pkg(first, '1.0.0')
+    file(join(profileDir, 'entry.mjs'), '')
+    const parentURL = pathToFileURL(join(profileDir, 'entry.mjs')).href
+
+    const ctx = new Context()
+    contexts.push(ctx)
+    ctx.baseUrl = pathToFileURL(profileDir).href + '/'
+    await ctx.plugin(PluginPackages, {
+      generation: generation(profilesDir, profileDir, first, firstAnchor, '1.0.0'),
+    })
+
+    expect(ctx.pluginPackages.packageOf('metadata-lib/private', parentURL)).toMatchObject({
+      name: 'metadata-lib',
+      version: '1.0.0',
+      dir: first,
+    })
+    const require = createRequire(join(profileDir, 'entry.cjs'))
+    expect(require.resolve('metadata-lib')).toBe(realpathSync(join(first, 'index.cjs')))
+    expect(ctx.pluginPackages.packageOf('node:fs', parentURL)).toBeUndefined()
+    expect(ctx.pluginPackages.packageOf('./local.js', parentURL)).toBeUndefined()
+
+    await ctx.fiber.dispose()
+    contexts.pop()
+    expect(() => { require.resolve('metadata-lib') }).toThrow(/Cannot find module/u)
+  })
+
+  it('uses native package lookup without a registration and caches parsed metadata', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-native-package-service-'))
+    roots.push(root)
+    const packageDir = join(root, 'node_modules', '@scope', 'metadata')
+    file(join(packageDir, 'package.json'), JSON.stringify({ name: '@scope/metadata' }))
+    const parentURL = pathToFileURL(join(root, 'entry.mjs')).href
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(PluginPackages)
+
+    const first = ctx.pluginPackages.packageOf('@scope/metadata/subpath', parentURL)
+    expect(first).toMatchObject({ name: '@scope/metadata', version: undefined, dir: packageDir })
+    expect(ctx.pluginPackages.packageOf('@scope/metadata', parentURL)).toBe(first)
+    expect(ctx.pluginPackages.packageOf('missing-package', parentURL)).toBeUndefined()
+    expect(ctx.pluginPackages.packageOf('@scope', parentURL)).toBeUndefined()
+    expect(() => { ctx.pluginPackages.replace({
+      profilesDir: join(root, 'profiles'), profileDir: undefined, localPackageNames: [], entries: [],
+    }) }).toThrow(/runtime resolution is not installed/u)
+  })
+
+  it('rejects malformed package metadata selected by the resolver', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-invalid-package-service-'))
+    roots.push(root)
+    const anonymous = join(root, 'node_modules', 'anonymous')
+    file(join(anonymous, 'package.json'), '{}')
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(PluginPackages)
+    const parentURL = pathToFileURL(join(root, 'entry.mjs')).href
+    expect(ctx.pluginPackages.packageOf('missing', parentURL)).toBeUndefined()
+    expect(ctx.pluginPackages.packageOf('anonymous', parentURL)).toMatchObject({
+      name: 'anonymous',
+      version: undefined,
+      dir: anonymous,
+    })
+  })
+
+  it('returns undefined when a selected package directory has no manifest', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-missing-package-service-'))
+    roots.push(root)
+    const profilesDir = join(root, 'profiles')
+    const profileDir = join(profilesDir, 'test')
+    const missing = join(root, 'missing')
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(PluginPackages, {
+      generation: generation(profilesDir, profileDir, missing, join(root, 'owner.json'), '1.0.0'),
+    })
+    expect(ctx.pluginPackages.packageOf(
+      'metadata-lib', pathToFileURL(join(profileDir, 'entry.mjs')).href,
+    )).toBeUndefined()
+  })
+
+  it('does not revive a stale disk fallback after the runtime generation misses', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-stale-package-service-'))
+    roots.push(root)
+    const profilesDir = join(root, 'profiles')
+    const profileDir = join(profilesDir, 'test')
+    pkg(join(profilesDir, 'node_modules', 'stale-metadata'), '0.9.0', 'stale-metadata')
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(PluginPackages, {
+      generation: { profilesDir, profileDir, localPackageNames: [], entries: [] },
+    })
+
+    expect(ctx.pluginPackages.packageOf(
+      'stale-metadata', pathToFileURL(join(profileDir, 'entry.mjs')).href,
+    )).toBeUndefined()
+  })
+
+  it('publishes additive generations to the process and future Workers', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-package-service-generation-'))
+    roots.push(root)
+    const profilesDir = join(root, 'profiles')
+    const profileDir = join(profilesDir, 'test')
+    const first = join(root, 'first')
+    const firstAnchor = pkg(first, '1.0.0')
+    const initial = generation(profilesDir, profileDir, first, firstAnchor, '1.0.0')
+    mkdirSync(join(profilesDir, 'node_modules'), { recursive: true })
+    symlinkSync(
+      first,
+      join(profilesDir, 'node_modules', 'metadata-lib'),
+      process.platform === 'win32' ? 'junction' : 'dir',
+    )
+    const key = '@deepseek-ai/dsh-app-boot/profile-resolution'
+    const previous = getEnvironmentData(key)
+    const ctx = new Context()
+    contexts.push(ctx)
+    await ctx.plugin(PluginPackages, { generation: initial, behavior: 'verify' })
+    const initialWorkerData = getEnvironmentData(key) as {
+      generation: ProfileResolutionGeneration
+      behavior: string
+    }
+    expect(initialWorkerData).toEqual({ generation: initial, behavior: 'verify' })
+
+    const added = join(root, 'added')
+    const addedAnchor = pkg(added, '2.0.0', 'added-metadata')
+    symlinkSync(
+      added,
+      join(profilesDir, 'node_modules', 'added-metadata'),
+      process.platform === 'win32' ? 'junction' : 'dir',
+    )
+    const next = {
+      ...initial,
+      entries: [...initial.entries, {
+        name: 'added-metadata', packageDir: added, version: '2.0.0',
+        declarer: addedAnchor, scope: 'installation' as const,
+      }],
+    }
+    ctx.pluginPackages.replace(next)
+    expect(getEnvironmentData(key)).toEqual({
+      generation: next,
+      behavior: 'verify',
+    })
+    expect(ctx.pluginPackages.packageOf(
+      'added-metadata', pathToFileURL(join(profileDir, 'entry.mjs')).href,
+    )).toMatchObject({ name: 'added-metadata', version: '2.0.0', dir: added })
+
+    await ctx.fiber.dispose()
+    contexts.pop()
+    expect(getEnvironmentData(key)).toBe(previous)
+  })
+})
diff --git a/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts b/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts
new file mode 100644
index 0000000000..a0ab5a7616
--- /dev/null
+++ b/packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts
@@ -0,0 +1,43 @@
+/** Worker bootstrap installs only the generation inherited from its parent. */
+
+import { beforeEach, expect, it, vi } from 'vitest'
+import type { ProfileResolutionGeneration } from '../src/profile.ts'
+
+const harness = vi.hoisted(() => ({
+  data: undefined as {
+    generation: ProfileResolutionGeneration
+    behavior: 'enforce' | 'verify'
+  } | undefined,
+  install: vi.fn(),
+}))
+
+vi.mock('node:worker_threads', () => ({
+  getEnvironmentData: () => harness.data,
+}))
+
+vi.mock('../src/profile-resolution/resolver.ts', () => ({
+  installProfileResolution: harness.install,
+}))
+
+beforeEach(() => {
+  harness.data = undefined
+  harness.install.mockReset()
+  vi.resetModules()
+})
+
+it('does nothing without inherited profile resolution data', async () => {
+  await import('../src/profile-resolution/worker-bootstrap.ts')
+  expect(harness.install).not.toHaveBeenCalled()
+})
+
+it('installs the inherited generation and behavior', async () => {
+  const generation: ProfileResolutionGeneration = {
+    profilesDir: '/profiles',
+    profileDir: '/profiles/test',
+    localPackageNames: [],
+    entries: [],
+  }
+  harness.data = { generation, behavior: 'verify' }
+  await import('../src/profile-resolution/worker-bootstrap.ts')
+  expect(harness.install).toHaveBeenCalledWith(generation, 'verify')
+})
diff --git a/packages/boot/app-boot/tests/profile-resolution.spec.ts b/packages/boot/app-boot/tests/profile-resolution.spec.ts
new file mode 100644
index 0000000000..8860cc9d40
--- /dev/null
+++ b/packages/boot/app-boot/tests/profile-resolution.spec.ts
@@ -0,0 +1,1518 @@
+/** Runtime profile resolution uses one eager generation for ESM and CommonJS. */
+
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { getEnvironmentData } from 'node:worker_threads'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  installProfileResolution,
+  registerWorkerResolution,
+  type ProfileResolutionRegistration,
+} from '../src/profile-resolution/resolver.ts'
+import {
+  createProfileResolutionGeneration,
+  healProfilesModuleFallback,
+  type Profile,
+  type ProfileResolutionGeneration,
+} from '../src/profile.ts'
+
+const roots: string[] = []
+const registrations: ProfileResolutionRegistration[] = []
+
+afterEach(() => {
+  for (const registration of registrations.splice(0).reverse()) registration.dispose()
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function file(path: string, text: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, text)
+}
+
+function pkg(
+  dir: string,
+  name: string,
+  marker: number,
+  dependencies: Record<string, string> = {},
+  peerDependencies: Record<string, string> = {},
+): string {
+  file(join(dir, 'package.json'), JSON.stringify({
+    name,
+    version: `${String(marker)}.0.0`,
+    type: 'module',
+    exports: { import: './index.js', require: './index.cjs' },
+    dependencies,
+    peerDependencies,
+  }))
+  file(join(dir, 'index.js'), `export const marker = ${String(marker)}\n`)
+  file(join(dir, 'index.cjs'), `module.exports = { marker: ${String(marker)} }\n`)
+  return join(dir, 'package.json')
+}
+
+function conditionalPkg(dir: string, name: string, importMarker: number, requireMarker: number): string {
+  file(join(dir, 'package.json'), JSON.stringify({
+    name,
+    version: '1.0.0',
+    type: 'module',
+    exports: { custom: './custom.cjs', import: './import.js', require: './require.cjs' },
+  }))
+  file(join(dir, 'import.js'), `export const marker = ${String(importMarker)}\n`)
+  file(join(dir, 'require.cjs'), `module.exports = { marker: ${String(requireMarker)} }\n`)
+  file(join(dir, 'custom.cjs'), 'module.exports = { marker: 13 }\n')
+  return join(dir, 'package.json')
+}
+
+async function importFrom(specifier: string, parent: string): Promise<Record<string, unknown>> {
+  const addon = createRequire(import.meta.url)('node-addon-require-builtin') as {
+    requireBuiltin(id: string): unknown
+  }
+  const loader = addon.requireBuiltin('internal/modules/esm/loader') as {
+    getOrInitializeCascadedLoader(): {
+      import(specifier: string, parent: string, attributes: ImportAttributes): Promise<Record<string, unknown>>
+    }
+  }
+  return await loader.getOrInitializeCascadedLoader().import(specifier, parent, {})
+}
+
+function resolveFrom(
+  specifier: string, parent: string | undefined, attributes: ImportAttributes = {}, skipSyncHooks = false,
+): string {
+  const addon = createRequire(import.meta.url)('node-addon-require-builtin') as {
+    requireBuiltin(id: string): unknown
+  }
+  const loader = addon.requireBuiltin('internal/modules/esm/loader') as {
+    getOrInitializeCascadedLoader(): {
+      getOrCreateModuleJob?: unknown
+      resolveSync(
+        first: string | undefined,
+        second: string | undefined | { specifier: string; attributes: ImportAttributes },
+        third?: ImportAttributes | boolean,
+      ): { url: string }
+    }
+  }
+  const internal = loader.getOrInitializeCascadedLoader()
+  if (!('getOrCreateModuleJob' in internal)) return internal.resolveSync(specifier, parent, attributes).url
+  return skipSyncHooks
+    ? internal.resolveSync(parent, { specifier, attributes }, true).url
+    : internal.resolveSync(parent, { specifier, attributes }).url
+}
+
+function thrownMessage(callback: () => unknown): string {
+  try {
+    callback()
+  } catch (error) {
+    return (error as Error).message
+  }
+  throw new Error('expected callback to throw')
+}
+
+function thrownError(callback: () => unknown): Error & {
+  code?: string
+  path?: string
+  requestPath?: string
+  requireStack?: string[]
+} {
+  try {
+    callback()
+  } catch (error) {
+    if (error instanceof Error) return error
+    throw error
+  }
+  throw new Error('expected callback to throw')
+}
+
+function fixture(name = 'resolution-lib'): {
+  root: string
+  installAnchor: string
+  installed: string
+  profile: Profile
+} {
+  // macOS exposes tmpdir through /var while Node returns resolved module paths through /private/var.
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-profile-generation-')))
+  roots.push(root)
+  const installDir = join(root, 'install')
+  const installed = join(installDir, 'node_modules', name)
+  const installAnchor = pkg(installDir, 'test-app', 0, { [name]: '*' })
+  pkg(installed, name, 1)
+  const profileDir = join(root, 'profiles', 'test')
+  file(join(profileDir, 'package.json'), JSON.stringify({
+    name: 'test-profile', private: true, dependencies: { 'missing-local': '*' },
+  }))
+  return {
+    root,
+    installAnchor,
+    installed,
+    profile: {
+      name: 'test',
+      dir: profileDir,
+      layers: [],
+      patchPath: join(profileDir, 'cordis.patch.yml'),
+      patches: [],
+      patchReload: 'startup',
+    },
+  }
+}
+
+async function generationOf(f: ReturnType<typeof fixture>): Promise<ProfileResolutionGeneration> {
+  return await healProfilesModuleFallback({
+    installAnchor: f.installAnchor,
+    profile: f.profile,
+    home: f.root,
+    materialize: false,
+  })
+}
+
+describe('profile resolution generation', { concurrent: false }, () => {
+  it('computes the old fallback graph without materializing it', async () => {
+    const f = fixture()
+    const generation = await generationOf(f)
+    expect(generation.entries.find(entry => entry.name === 'resolution-lib')).toMatchObject({
+      packageDir: f.installed,
+      version: '1.0.0',
+      declarer: f.installAnchor,
+      scope: 'installation',
+    })
+    expect(existsSync(join(generation.profilesDir, 'node_modules'))).toBe(false)
+    expect(existsSync(join(f.profile.dir, '.dsh-module-fallback'))).toBe(false)
+    expect(Object.isFrozen(generation)).toBe(true)
+    expect(Object.isFrozen(generation.entries)).toBe(true)
+    expect(generation.entries.every(Object.isFrozen)).toBe(true)
+
+    const installationOnly = await createProfileResolutionGeneration({
+      installAnchor: f.installAnchor,
+      home: join(f.root, 'installation-only-home'),
+    })
+    expect(installationOnly.profileDir).toBeUndefined()
+    expect(installationOnly.localPackageNames).toEqual([])
+    const registration = installProfileResolution(installationOnly)
+    registrations.push(registration)
+    expect(createRequire(join(installationOnly.profilesDir, 'entry.cjs'))('resolution-lib'))
+      .toEqual({ marker: 1 })
+  })
+
+  it('fails generation construction before writing when the profile manifest is malformed', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), '{')
+    await expect(generationOf(f)).rejects.toThrow(SyntaxError)
+    expect(existsSync(join(f.root, 'profiles', 'node_modules'))).toBe(false)
+  })
+
+  it('materializes exactly the package targets in the computed generation', async () => {
+    const f = fixture()
+    const computed = await generationOf(f)
+    const materialized = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    expect(materialized).toEqual(computed)
+    for (const entry of computed.entries) {
+      const projected = entry.scope === 'installation'
+        ? join(computed.profilesDir, 'node_modules', entry.name)
+        : join(f.profile.dir, '.dsh-module-fallback', 'node_modules', entry.name)
+      expect(realpathSync(projected)).toBe(realpathSync(entry.packageDir))
+    }
+  })
+
+  it('keeps each earlier root complete before considering a later root', async () => {
+    const f = fixture('installation-bridge')
+    const installedBridge = f.installed
+    const installationChoice = join(installedBridge, 'node_modules', 'ordered-choice')
+    pkg(installedBridge, 'installation-bridge', 1, { 'ordered-choice': '*' }, { 'peer-choice': '*' })
+    pkg(installationChoice, 'ordered-choice', 1)
+    const peerChoice = join(installedBridge, 'node_modules', 'peer-choice')
+    pkg(peerChoice, 'peer-choice', 3)
+    const bundleDir = join(f.root, 'bundle')
+    pkg(bundleDir, 'test-bundle', 0, { 'ordered-choice': '*', 'bundle-bridge': '*' })
+    pkg(join(bundleDir, 'node_modules', 'ordered-choice'), 'ordered-choice', 2)
+    const bundleBridge = join(bundleDir, 'node_modules', 'bundle-bridge')
+    pkg(bundleBridge, 'bundle-bridge', 0, { 'bundle-choice': '*' })
+    const firstBundleChoice = join(bundleBridge, 'node_modules', 'bundle-choice')
+    pkg(firstBundleChoice, 'bundle-choice', 1)
+    const laterBundle = join(f.root, 'later-bundle')
+    pkg(laterBundle, 'later-bundle', 0, { 'bundle-choice': '*' })
+    pkg(join(laterBundle, 'node_modules', 'bundle-choice'), 'bundle-choice', 2)
+    f.profile.layers.push({
+      packageName: 'test-bundle',
+      packageDir: bundleDir,
+      patchPath: join(bundleDir, 'cordis.patch.yml'),
+      patches: [],
+    }, {
+      packageName: 'later-bundle',
+      packageDir: laterBundle,
+      patchPath: join(laterBundle, 'cordis.patch.yml'),
+      patches: [],
+    })
+
+    const generation = await generationOf(f)
+    expect(generation.entries.find(entry => entry.name === 'ordered-choice')).toMatchObject({
+      packageDir: installationChoice,
+      scope: 'installation',
+    })
+    const bundleChoice = generation.entries.find(entry => entry.name === 'bundle-choice')
+    if (bundleChoice === undefined) throw new Error('generation omitted bundle-choice')
+    expect(bundleChoice).toMatchObject({ scope: 'profile' })
+    expect(realpathSync.native(bundleChoice.packageDir)).toBe(realpathSync.native(firstBundleChoice))
+    expect(generation.entries.find(entry => entry.name === 'peer-choice')).toMatchObject({
+      packageDir: peerChoice,
+      scope: 'installation',
+    })
+  })
+
+  it('routes ESM and CommonJS through the same installation entry', async () => {
+    const f = fixture()
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require('resolution-lib')).toEqual({ marker: 1 })
+    expect(require.resolve('resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
+    expect(resolveFrom('resolution-lib', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    expect(resolveFrom('resolution-lib', parent, { type: 'javascript' }))
+      .toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    expect(resolveFrom('resolution-lib', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    expect(import.meta.resolve('resolution-lib', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    expect(await importFrom('resolution-lib', parent)).toMatchObject({ marker: 1 })
+  })
+
+  it('routes a scoped CommonJS package through its containing node_modules directory', async () => {
+    const f = fixture('@scope/resolution-lib')
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+
+    expect(require('@scope/resolution-lib')).toEqual({ marker: 1 })
+    expect(require.resolve('@scope/resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+  })
+
+  it('routes a CommonJS npm alias through its declaring package', async () => {
+    const f = fixture('aliased-lib')
+    const target = join(f.root, 'store', 'real-lib')
+    pkg(target, 'real-lib', 5)
+    rmSync(f.installed, { recursive: true })
+    symlinkSync(target, f.installed, process.platform === 'win32' ? 'junction' : 'dir')
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+
+    expect(createRequire(join(f.profile.dir, 'entry.cjs'))('aliased-lib')).toEqual({ marker: 5 })
+  })
+
+  it('verifies a materialized scoped CommonJS package against the generation', async () => {
+    const f = fixture('@scope/resolution-lib')
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const registration = installProfileResolution(generation, 'verify')
+    registrations.push(registration)
+
+    expect(createRequire(join(f.profile.dir, 'dual-entry.cjs')).resolve('@scope/resolution-lib'))
+      .toBe(realpathSync(join(f.installed, 'index.cjs')))
+  })
+
+  it('routes an application-owned profile outside the shared profiles directory', async () => {
+    const f = fixture()
+    const profileDir = join(f.root, 'application-profile')
+    file(join(profileDir, 'package.json'), JSON.stringify({ name: 'application-profile', private: true }))
+    const profile = {
+      ...f.profile,
+      dir: profileDir,
+      patchPath: join(profileDir, 'cordis.patch.yml'),
+    }
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile,
+      home: f.root,
+      materialize: false,
+    })
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    const require = createRequire(join(profileDir, 'entry.cjs'))
+    expect(require('resolution-lib')).toEqual({ marker: 1 })
+    const parent = pathToFileURL(join(profileDir, 'entry.mjs')).href
+    expect(resolveFrom('resolution-lib', parent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    expect(await importFrom('resolution-lib', parent)).toMatchObject({ marker: 1 })
+    expect(() => { createRequire(join(f.root, 'outside.cjs'))('resolution-lib') }).toThrow(/Cannot find module/u)
+  })
+
+  it('does not reuse a default route for explicit CommonJS paths', async () => {
+    const f = fixture()
+    const alternative = join(f.root, 'alternative')
+    const alternativePackage = join(alternative, 'node_modules', 'resolution-lib')
+    pkg(alternativePackage, 'resolution-lib', 2)
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require.resolve('resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    expect(require.resolve('resolution-lib', { paths: [alternative] })).toBe(join(alternativePackage, 'index.cjs'))
+    expect(require.resolve('resolution-lib', { paths: [f.profile.dir] })).toBe(join(f.installed, 'index.cjs'))
+    expect(require.resolve('resolution-lib', { paths: [join(f.root, 'missing'), f.profile.dir] }))
+      .toBe(join(f.installed, 'index.cjs'))
+    const relative = join(f.profile.dir, 'relative.cjs')
+    file(relative, '')
+    expect(require.resolve('./relative.cjs', { paths: [f.profile.dir] })).toBe(relative)
+    const invalid = join(f.root, 'invalid')
+    file(join(invalid, 'node_modules', 'resolution-lib', 'package.json'), '{')
+    expect(() => { require.resolve('resolution-lib', { paths: [invalid, f.profile.dir] }) })
+      .toThrow(/Invalid package config/u)
+  })
+
+  it('keeps earlier explicit CommonJS paths ahead of a managed local failure', async () => {
+    const f = fixture()
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const local = join(f.profile.dir, 'node_modules', 'resolution-lib')
+    file(join(local, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '2.0.0', exports: './missing.cjs',
+    }))
+    const alternative = join(f.root, 'alternative')
+    const selected = join(alternative, 'node_modules', 'resolution-lib', 'index.cjs')
+    pkg(dirname(selected), 'resolution-lib', 3)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    const paths = [alternative, f.profile.dir]
+    expect(require.resolve('resolution-lib', { paths })).toBe(selected)
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    expect(require.resolve('resolution-lib', { paths })).toBe(selected)
+  })
+
+  it('keeps a missing legacy main before a managed explicit CommonJS path', async () => {
+    const f = fixture()
+    const invalid = join(f.root, 'invalid')
+    const selected = join(invalid, 'node_modules', 'resolution-lib')
+    file(join(selected, 'package.json'), JSON.stringify({ name: 'resolution-lib', main: './missing.cjs' }))
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    const paths = [invalid, f.profile.dir]
+    const linkError = thrownError(() => require.resolve('resolution-lib', { paths }))
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const runtimeError = thrownError(() => require.resolve('resolution-lib', { paths }))
+
+    expect(runtimeError).toMatchObject({
+      code: linkError.code,
+      path: linkError.path,
+      requestPath: linkError.requestPath,
+    })
+    expect(runtimeError.message).toBe(linkError.message)
+  })
+
+  it('keeps a missing fallback legacy main before later explicit CommonJS paths', async () => {
+    const f = fixture()
+    const name = 'fallback-invalid-main'
+    const selected = join(f.root, 'node_modules', name)
+    file(join(selected, 'package.json'), JSON.stringify({ name, main: './missing.cjs' }))
+    const alternative = join(f.root, 'alternative')
+    pkg(join(alternative, 'node_modules', name), name, 2)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    const paths = [f.profile.dir, alternative]
+    const linkError = thrownError(() => require.resolve(name, { paths }))
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const runtimeError = thrownError(() => require.resolve(name, { paths }))
+
+    expect(runtimeError).toMatchObject({
+      code: linkError.code,
+      path: linkError.path,
+      requestPath: linkError.requestPath,
+    })
+    expect(runtimeError.message).toBe(linkError.message)
+  })
+
+  it('keeps a missing fallback legacy main after a generation miss', async () => {
+    const f = fixture()
+    const selected = join(f.root, 'node_modules', 'resolution-lib')
+    file(join(selected, 'package.json'), JSON.stringify({ name: 'resolution-lib', main: './missing.cjs' }))
+    const alternative = join(f.root, 'alternative')
+    pkg(join(alternative, 'node_modules', 'resolution-lib'), 'resolution-lib', 2)
+    const generation = await generationOf(f)
+    rmSync(f.installed, { recursive: true })
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    const paths = [f.profile.dir, alternative]
+    const linkError = thrownError(() => require.resolve('resolution-lib', { paths }))
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    const runtimeError = thrownError(() => require.resolve('resolution-lib', { paths }))
+
+    expect(runtimeError).toMatchObject({
+      code: linkError.code,
+      path: linkError.path,
+      requestPath: linkError.requestPath,
+    })
+    expect(runtimeError.message).toBe(linkError.message)
+  })
+
+  it('keeps a profile-local package ahead of the generation', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile',
+      private: true,
+      dependencies: { 'resolution-lib': '*', 'linked-local': '*' },
+    }))
+    const localResolution = join(f.profile.dir, 'node_modules', 'resolution-lib')
+    pkg(localResolution, 'resolution-lib', 2)
+    const linkedLocal = join(f.root, 'linked-local')
+    pkg(linkedLocal, 'linked-local', 3)
+    symlinkSync(
+      linkedLocal,
+      join(f.profile.dir, 'node_modules', 'linked-local'),
+      process.platform === 'win32' ? 'junction' : 'dir',
+    )
+    const generation = await generationOf(f)
+    expect(generation.localPackageNames).toEqual(['resolution-lib', 'linked-local'])
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require('resolution-lib')).toEqual({ marker: 2 })
+    expect(require.resolve('resolution-lib', { paths: [f.profile.dir] }))
+      .toBe(join(localResolution, 'index.cjs'))
+    const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
+    expect(resolveFrom('resolution-lib', parent)).toBe(
+      pathToFileURL(join(f.profile.dir, 'node_modules', 'resolution-lib', 'index.js')).href,
+    )
+  })
+
+  it('preserves an npm alias package self-reference', async () => {
+    const f = fixture()
+    file(f.installAnchor, JSON.stringify({
+      name: 'test-app',
+      version: '0.0.0',
+      type: 'module',
+      exports: { import: './index.js', require: './index.cjs' },
+      dependencies: { 'resolution-lib': '*', 'real-name': '*' },
+    }))
+    const installedRealName = join(dirname(f.installAnchor), 'node_modules', 'real-name')
+    pkg(installedRealName, 'real-name', 7)
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile',
+      private: true,
+      dependencies: { alias: 'npm:real-name' },
+    }))
+    const alias = join(f.profile.dir, 'node_modules', 'alias')
+    pkg(alias, 'real-name', 6)
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    expect(generation.localPackageNames).toEqual(['alias'])
+    const require = createRequire(join(alias, 'inside.cjs'))
+    expect(require.resolve('real-name')).toBe(join(alias, 'index.cjs'))
+    expect(require.resolve('real-name', { paths: [f.profile.dir] })).toBe(join(alias, 'index.cjs'))
+    expect(resolveFrom('real-name', pathToFileURL(join(alias, 'inside-link.mjs')).href)).toBe(
+      pathToFileURL(join(alias, 'index.js')).href,
+    )
+    const invalidScope = join(f.profile.dir, 'node_modules', 'invalid-scope')
+    file(join(invalidScope, 'package.json'), '{')
+    expect(() => createRequire(join(invalidScope, 'inside.cjs')).resolve('resolution-lib'))
+      .toThrow(/Invalid package config/u)
+    expect(() => resolveFrom('resolution-lib', pathToFileURL(join(invalidScope, 'inside.mjs')).href))
+      .toThrow(/Invalid package config/u)
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'real-name'))
+
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    expect(require.resolve('real-name')).toBe(join(alias, 'index.cjs'))
+    expect(require.resolve('real-name', { paths: [f.profile.dir] })).toBe(join(alias, 'index.cjs'))
+    expect(resolveFrom('real-name', pathToFileURL(join(alias, 'inside-runtime.mjs')).href)).toBe(
+      pathToFileURL(join(alias, 'index.js')).href,
+    )
+    expect(() => createRequire(join(invalidScope, 'inside.cjs')).resolve('resolution-lib'))
+      .toThrow(/Invalid package config/u)
+    expect(() => resolveFrom('resolution-lib', pathToFileURL(join(invalidScope, 'inside.mjs')).href))
+      .toThrow(/Invalid package config/u)
+  })
+
+  it('keeps package imports aliases on the generation route', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile',
+      private: true,
+      imports: { '#resolution-lib': 'resolution-lib' },
+    }))
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const nested = join(f.profile.dir, 'nested')
+    const require = createRequire(join(nested, 'entry.cjs'))
+    const linkParent = pathToFileURL(join(nested, 'entry-link.mjs')).href
+    expect(require.resolve('#resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    expect(resolveFrom('#resolution-lib', linkParent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    const runtimeParent = pathToFileURL(join(nested, 'entry-runtime.mjs')).href
+    expect(require.resolve('#resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    expect(resolveFrom('#resolution-lib', runtimeParent)).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+  })
+
+  it('verifies package imports aliases against the generation', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile',
+      private: true,
+      imports: { '#resolution-lib': 'resolution-lib' },
+    }))
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const registration = installProfileResolution(generation, 'verify')
+    registrations.push(registration)
+
+    expect(createRequire(join(f.profile.dir, 'entry.cjs')).resolve('#resolution-lib'))
+      .toBe(realpathSync(join(f.installed, 'index.cjs')))
+    expect(resolveFrom(
+      '#resolution-lib', pathToFileURL(join(f.profile.dir, 'entry-dual.mjs')).href,
+    )).toBe(pathToFileURL(realpathSync(join(f.installed, 'index.js'))).href)
+  })
+
+  it('ignores a stale package imports projection and detects it in dual mode', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile',
+      private: true,
+      imports: { '#resolution-lib': 'resolution-lib' },
+    }))
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const projection = join(generation.profilesDir, 'node_modules', 'resolution-lib')
+    unlinkSync(projection)
+    const stale = join(f.root, 'stale', 'resolution-lib')
+    pkg(stale, 'resolution-lib', 9)
+    symlinkSync(stale, projection, process.platform === 'win32' ? 'junction' : 'dir')
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+
+    const runtime = installProfileResolution(generation)
+    expect(require.resolve('#resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    expect(require.resolve('resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    expect(resolveFrom(
+      '#resolution-lib', pathToFileURL(join(f.profile.dir, 'runtime.mjs')).href,
+    )).toBe(pathToFileURL(join(f.installed, 'index.js')).href)
+    runtime.dispose()
+
+    const dual = installProfileResolution(generation, 'verify')
+    registrations.push(dual)
+    expect(() => require.resolve('#resolution-lib')).toThrow(/profile resolution mismatch/u)
+    expect(() => resolveFrom(
+      '#resolution-lib', pathToFileURL(join(f.profile.dir, 'dual-stale.mjs')).href,
+    )).toThrow(/profile resolution mismatch/u)
+  })
+
+  it('leaves relative package imports targets and their diagnostics to Node', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile',
+      private: true,
+      imports: { '#missing-relative': './missing.cjs' },
+    }))
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
+    const cjsMessage = thrownMessage(() => require.resolve('#missing-relative'))
+    const esmMessage = thrownMessage(() => resolveFrom('#missing-relative', parent))
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    expect(thrownMessage(() => require.resolve('#missing-relative'))).toBe(cjsMessage)
+    expect(thrownMessage(() => resolveFrom('#missing-relative', parent))).toBe(esmMessage)
+  })
+
+  it('keeps local and after-fallback package imports targets in native order', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile',
+      private: true,
+      imports: { '#local': 'local-import', '#ancestor': 'ancestor-import' },
+    }))
+    const local = join(f.profile.dir, 'node_modules', 'local-import')
+    const ancestor = join(f.root, 'node_modules', 'ancestor-import')
+    pkg(local, 'local-import', 4)
+    pkg(ancestor, 'ancestor-import', 5)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require.resolve('#local')).toBe(join(local, 'index.cjs'))
+    expect(require.resolve('#ancestor')).toBe(join(ancestor, 'index.cjs'))
+
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    expect(require.resolve('#local')).toBe(join(local, 'index.cjs'))
+    expect(require.resolve('#ancestor')).toBe(join(ancestor, 'index.cjs'))
+  })
+
+  it('leaves package imports outside the profile scope to Node', async () => {
+    const f = fixture()
+    const outside = join(f.root, 'outside')
+    file(join(outside, 'package.json'), JSON.stringify({
+      name: 'outside', private: true, imports: { '#missing': 'missing-target' },
+    }))
+    const require = createRequire(join(outside, 'entry.cjs'))
+    const linkMessage = thrownMessage(() => require.resolve('#missing'))
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+
+    expect(thrownMessage(() => require.resolve('#missing'))).toBe(linkMessage)
+  })
+
+  it('does not inherit package imports across node_modules', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile', private: true, imports: { '#resolution-lib': 'resolution-lib' },
+    }))
+    const nested = join(f.profile.dir, 'node_modules', 'manifestless', 'entry.cjs')
+    file(nested, '')
+    const require = createRequire(nested)
+    const linkMessage = thrownMessage(() => require.resolve('#resolution-lib'))
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+
+    expect(thrownMessage(() => require.resolve('#resolution-lib'))).toBe(linkMessage)
+  })
+
+  it('falls through a missing local CommonJS subpath to the generation', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile',
+      private: true,
+      dependencies: { 'resolution-lib': '*' },
+    }))
+    file(join(f.installed, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '1.0.0', type: 'module', main: './index.cjs',
+    }))
+    file(join(f.installed, 'only-install.cjs'), 'module.exports = { marker: 8 }\n')
+    file(join(f.installed, 'legacy-install.cjs'), 'module.exports = { marker: 9 }\n')
+    const local = join(f.profile.dir, 'node_modules', 'resolution-lib')
+    file(join(local, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '2.0.0', type: 'module', main: './index.cjs',
+    }))
+    file(join(local, 'index.cjs'), 'module.exports = { marker: 2 }\n')
+    const generation = await generationOf(f)
+    expect(generation.localPackageNames).toEqual(['resolution-lib'])
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+
+    expect(createRequire(join(f.profile.dir, 'entry.cjs')).resolve('resolution-lib/only-install.cjs'))
+      .toBe(join(f.installed, 'only-install.cjs'))
+    rmSync(join(local, 'package.json'))
+    expect(createRequire(join(f.profile.dir, 'entry.cjs')).resolve('resolution-lib/legacy-install.cjs'))
+      .toBe(join(f.installed, 'legacy-install.cjs'))
+  })
+
+  it('treats null exports as legacy CommonJS package resolution', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'package.json'), JSON.stringify({
+      name: 'test-profile',
+      private: true,
+      dependencies: { 'resolution-lib': '*' },
+    }))
+    file(join(f.installed, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '1.0.0', type: 'module', exports: null,
+    }))
+    const installedSubpath = join(f.installed, 'only-install.cjs')
+    file(installedSubpath, 'module.exports = { marker: 8 }\n')
+    const local = join(f.profile.dir, 'node_modules', 'resolution-lib')
+    file(join(local, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '2.0.0', type: 'module', exports: null,
+    }))
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const require = createRequire(join(local, 'entry.cjs'))
+    expect(require.resolve('resolution-lib/only-install.cjs')).toBe(installedSubpath)
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    expect(require.resolve('resolution-lib/only-install.cjs')).toBe(installedSubpath)
+  })
+
+  it('stops a local CommonJS probe before the generation fallback position', async () => {
+    const f = fixture()
+    file(join(f.installed, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '1.0.0', type: 'module', main: './index.cjs',
+    }))
+    const installedSubpath = join(f.installed, 'only-install.cjs')
+    file(installedSubpath, 'module.exports = { marker: 8 }\n')
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    file(join(f.profile.dir, 'node_modules', 'resolution-lib', 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '2.0.0', main: './index.cjs',
+    }))
+    file(join(f.profile.dir, 'node_modules', 'resolution-lib', 'index.cjs'), 'module.exports = {}\n')
+    file(join(f.root, 'node_modules', 'resolution-lib', 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '3.0.0', exports: './index.cjs',
+    }))
+    file(join(f.root, 'node_modules', 'resolution-lib', 'index.cjs'), 'module.exports = {}\n')
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require.resolve('resolution-lib/only-install.cjs')).toBe(installedSubpath)
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    expect(require.resolve('resolution-lib/only-install.cjs')).toBe(installedSubpath)
+  })
+
+  it('observes a profile-local package installed after an earlier miss', async () => {
+    const f = fixture()
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
+    expect(() => { require.resolve('missing-local') }).toThrow(/Cannot find module/u)
+    expect(() => resolveFrom('missing-local', parent)).toThrow(/Cannot find/u)
+    file(join(f.profile.dir, 'node_modules', 'legacy-missing', 'index.js'), 'module.exports = {}\n')
+    expect(() => { require.resolve('legacy-missing/subpath') }).toThrow(/Cannot find module/u)
+
+    const local = join(f.profile.dir, 'node_modules', 'missing-local')
+    pkg(local, 'missing-local', 7)
+    expect(require.resolve('missing-local')).toBe(join(local, 'index.cjs'))
+    expect(resolveFrom('missing-local', parent)).toBe(pathToFileURL(join(local, 'index.js')).href)
+  })
+
+  it('delegates undeclared local packages and non-package specifiers to Node', async () => {
+    const f = fixture()
+    pkg(join(f.profile.dir, 'node_modules', 'undeclared-local'), 'undeclared-local', 6)
+    file(join(f.profile.dir, 'relative.cjs'), 'module.exports = 7\n')
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require('undeclared-local')).toEqual({ marker: 6 })
+    expect(require('./relative.cjs')).toBe(7)
+    expect(require('node:path')).toHaveProperty('join')
+    expect(require('path')).toHaveProperty('join')
+    const parent = pathToFileURL(join(f.profile.dir, 'undeclared-entry.mjs')).href
+    expect(registration.packageDir('undeclared-local', parent))
+      .toBe(join(f.profile.dir, 'node_modules', 'undeclared-local'))
+    expect(registration.packageDir('undeclared-local', parent))
+      .toBe(join(f.profile.dir, 'node_modules', 'undeclared-local'))
+    expect(resolveFrom('undeclared-local', parent)).toBe(
+      pathToFileURL(join(f.profile.dir, 'node_modules', 'undeclared-local', 'index.js')).href,
+    )
+    expect(await importFrom('undeclared-local', parent)).toMatchObject({ marker: 6 })
+    expect(resolveFrom('node:path', undefined)).toBe('node:path')
+    expect(resolveFrom('fs', parent)).toBe('node:fs')
+    expect(resolveFrom('node:path', pathToFileURL(join(f.root, 'outside.mjs')).href, {}, true)).toBe('node:path')
+
+    const addon = createRequire(import.meta.url)('node-addon-require-builtin') as { requireBuiltin(id: string): unknown }
+    const internal = addon.requireBuiltin('internal/modules/cjs/loader') as {
+      Module: {
+        _resolveFilename(
+          request: string, parent: { filename?: string } | undefined, isMain: boolean,
+        ): string
+      }
+    }
+    expect(internal.Module._resolveFilename('node:path', undefined, false)).toBe('node:path')
+  })
+
+  it('keeps a legacy CommonJS package without a manifest ahead of the generation', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'node_modules', 'resolution-lib', 'index.js'), 'module.exports = { marker: 2 }\n')
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    expect(createRequire(join(f.profile.dir, 'entry.cjs'))('resolution-lib')).toEqual({ marker: 2 })
+  })
+
+  it('keeps a manifestless local CommonJS subpath ahead of the generation', async () => {
+    const f = fixture()
+    const localSubpath = join(f.profile.dir, 'node_modules', 'resolution-lib', 'sub.cjs')
+    file(localSubpath, 'module.exports = { marker: 2 }\n')
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require.resolve('resolution-lib/sub.cjs')).toBe(localSubpath)
+
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    expect(require.resolve('resolution-lib/sub.cjs')).toBe(localSubpath)
+  })
+
+  it('keeps a local extensionless CommonJS package ahead of the generation', async () => {
+    const f = fixture()
+    const local = join(f.profile.dir, 'node_modules', 'resolution-lib')
+    file(local, 'module.exports = { marker: 2 }\n')
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require.resolve('resolution-lib')).toBe(local)
+
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    expect(require.resolve('resolution-lib')).toBe(local)
+  })
+
+  it('keeps a local legacy main outside its package directory ahead of the generation', async () => {
+    const f = fixture()
+    const local = join(f.profile.dir, 'node_modules', 'resolution-lib')
+    const outside = join(f.profile.dir, 'node_modules', 'outside.cjs')
+    file(join(local, 'package.json'), JSON.stringify({ name: 'resolution-lib', main: '../outside.cjs' }))
+    file(outside, 'module.exports = { marker: 2 }\n')
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require.resolve('resolution-lib')).toBe(outside)
+
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    expect(require.resolve('resolution-lib')).toBe(outside)
+  })
+
+  it('keeps a missing local legacy main error ahead of the generation', async () => {
+    const f = fixture()
+    const local = join(f.profile.dir, 'node_modules', 'resolution-lib')
+    file(join(local, 'package.json'), JSON.stringify({ name: 'resolution-lib', main: './missing.cjs' }))
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    const linkError = thrownError(() => require.resolve('resolution-lib'))
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const runtimeError = thrownError(() => require.resolve('resolution-lib'))
+
+    expect(runtimeError).toMatchObject({
+      code: linkError.code,
+      path: linkError.path,
+      requestPath: linkError.requestPath,
+    })
+    expect(runtimeError.message).toBe(linkError.message)
+  })
+
+  it('keeps a profile-local CommonJS package file ahead of the generation', async () => {
+    const f = fixture()
+    file(join(f.profile.dir, 'node_modules', 'resolution-lib.js'), 'module.exports = { marker: 2 }\n')
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    expect(createRequire(join(f.profile.dir, 'entry.cjs'))('resolution-lib')).toEqual({ marker: 2 })
+    expect(resolveFrom('resolution-lib', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href)).toBe(
+      pathToFileURL(join(f.installed, 'index.js')).href,
+    )
+  })
+
+  it('preserves the ESM and CommonJS behavior of an empty local package directory', async () => {
+    const f = fixture()
+    mkdirSync(join(f.profile.dir, 'node_modules', 'resolution-lib'), { recursive: true })
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    expect(createRequire(join(f.profile.dir, 'entry.cjs'))('resolution-lib')).toEqual({ marker: 1 })
+    expect(() => resolveFrom(
+      'resolution-lib', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href,
+    )).toThrow(/Cannot find/u)
+  })
+
+  it('limits bundle-only entries to the active profile', async () => {
+    const f = fixture()
+    const bundleDir = join(f.root, 'bundle')
+    pkg(bundleDir, 'test-bundle', 0, { 'bundle-only': '*' })
+    const bundleOnly = join(bundleDir, 'node_modules', 'bundle-only')
+    pkg(bundleOnly, 'bundle-only', 4)
+    f.profile.layers.push({
+      packageName: 'test-bundle',
+      packageDir: bundleDir,
+      patchPath: join(bundleDir, 'cordis.patch.yml'),
+      patches: [],
+    })
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    expect(createRequire(join(f.profile.dir, 'entry.cjs'))('bundle-only')).toEqual({ marker: 4 })
+    const other = join(f.root, 'profiles', 'other', 'entry.cjs')
+    expect(() => { createRequire(other)('bundle-only') }).toThrow(/Cannot find module/u)
+    const resolvedBundleOnly = createRequire(other).resolve('bundle-only', {
+      paths: [dirname(other), f.profile.dir],
+    })
+    expect(realpathSync.native(resolvedBundleOnly)).toBe(realpathSync.native(join(bundleOnly, 'index.cjs')))
+    expect(() => createRequire(other).resolve('bundle-only', { paths: [dirname(other)] }))
+      .toThrow(/Cannot find module/u)
+    expect(() => createRequire(other).resolve('missing-explicit', { paths: [dirname(other)] }))
+      .toThrow(/Cannot find module/u)
+    file(join(f.root, 'node_modules', 'invalid-after-fallback', 'package.json'), '{')
+    expect(() => createRequire(other).resolve('invalid-after-fallback', {
+      paths: [dirname(other), f.profile.dir],
+    })).toThrow(/Invalid package config/u)
+    file(join(f.root, 'node_modules', 'invalid-explicit', 'package.json'), '{')
+    expect(() => createRequire(other).resolve('invalid-explicit', {
+      paths: [dirname(other), f.profile.dir],
+    })).toThrow(/Invalid package config/u)
+  })
+
+  it('keeps the generation ahead of packages above the shared fallback position', async () => {
+    const f = fixture()
+    pkg(join(f.root, 'node_modules', 'resolution-lib'), 'resolution-lib', 2)
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require('resolution-lib')).toEqual({ marker: 1 })
+    expect(await importFrom('resolution-lib', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href))
+      .toMatchObject({ marker: 1 })
+  })
+
+  it('continues the original ancestor lookup after a generation subpath miss', async () => {
+    const f = fixture()
+    const home = join(f.root, 'home')
+    const profileDir = join(home, 'profiles', 'test')
+    const profile = {
+      ...f.profile,
+      dir: profileDir,
+      patchPath: join(profileDir, 'cordis.patch.yml'),
+    }
+    file(join(profileDir, 'package.json'), JSON.stringify({ name: 'test-profile', private: true }))
+    file(join(profileDir, 'node_modules', 'resolution-lib', 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '2.0.0',
+    }))
+    file(join(f.installed, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '1.0.0', type: 'module', main: './index.cjs',
+    }))
+    const ancestorSubpath = join(home, 'node_modules', 'resolution-lib', 'sub.cjs')
+    file(ancestorSubpath, 'module.exports = { marker: 3 }\n')
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile,
+      home,
+    })
+    const require = createRequire(join(profileDir, 'entry.cjs'))
+    expect(require.resolve('resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    expect(require.resolve('resolution-lib/sub.cjs')).toBe(ancestorSubpath)
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    expect(require.resolve('resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    expect(require.resolve('resolution-lib/sub.cjs')).toBe(ancestorSubpath)
+  })
+
+  it('continues explicit CommonJS paths after a generation subpath miss', async () => {
+    const f = fixture()
+    file(join(f.installed, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '1.0.0', type: 'module', main: './index.cjs',
+    }))
+    const alternative = join(f.root, 'alternative')
+    const alternativeSubpath = join(alternative, 'node_modules', 'resolution-lib', 'sub.cjs')
+    file(alternativeSubpath, 'module.exports = { marker: 4 }\n')
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+
+    expect(createRequire(join(f.profile.dir, 'entry.cjs')).resolve('resolution-lib/sub.cjs', {
+      paths: [f.profile.dir, alternative],
+    })).toBe(alternativeSubpath)
+  })
+
+  it('skips stale shared and profile-owned fallback entries when the generation misses', async () => {
+    const f = fixture()
+    pkg(join(f.root, 'profiles', 'node_modules', 'stale-shared'), 'stale-shared', 9)
+    pkg(join(f.root, 'node_modules', 'stale-shared'), 'stale-shared', 3)
+    const target = join(f.root, 'stale-private-target')
+    const owned = join(f.profile.dir, '.dsh-module-fallback', 'node_modules', 'stale-private')
+    const projected = join(f.profile.dir, 'node_modules', 'stale-private')
+    pkg(target, 'stale-private', 9)
+    mkdirSync(dirname(owned), { recursive: true })
+    symlinkSync(target, owned, process.platform === 'win32' ? 'junction' : 'dir')
+    mkdirSync(dirname(projected), { recursive: true })
+    symlinkSync(owned, projected, process.platform === 'win32' ? 'junction' : 'dir')
+    pkg(join(f.root, 'node_modules', 'stale-private'), 'stale-private', 3)
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    for (const name of ['stale-shared', 'stale-private']) {
+      expect(require(name)).toEqual({ marker: 3 })
+      expect(require.resolve(name, { paths: [f.profile.dir] })).toBe(join(f.root, 'node_modules', name, 'index.cjs'))
+      expect(await importFrom(name, pathToFileURL(join(f.profile.dir, `${name}.mjs`)).href))
+        .toMatchObject({ marker: 3 })
+    }
+  })
+
+  it('continues after a canonicalized profiles directory from the matching parent tree', async () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-profile-generation-symlink-')))
+    roots.push(root)
+    const carrier = join(root, 'carrier')
+    const profilesDir = join(root, 'home', 'profiles')
+    const realProfilesDir = join(carrier, 'profiles')
+    const realProfileDir = join(realProfilesDir, 'test')
+    mkdirSync(realProfileDir, { recursive: true })
+    mkdirSync(dirname(profilesDir), { recursive: true })
+    symlinkSync(realProfilesDir, profilesDir, process.platform === 'win32' ? 'junction' : 'dir')
+    pkg(join(realProfilesDir, 'node_modules', 'stale-only'), 'stale-only', 9)
+    pkg(join(carrier, 'node_modules', 'stale-only'), 'stale-only', 3)
+    pkg(join(root, 'home', 'node_modules', 'stale-only'), 'stale-only', 4)
+    const registration = installProfileResolution({
+      profilesDir,
+      profileDir: join(profilesDir, 'test'),
+      localPackageNames: [],
+      entries: [],
+    })
+    registrations.push(registration)
+    expect(createRequire(join(realProfileDir, 'entry.cjs'))('stale-only')).toEqual({ marker: 3 })
+  })
+
+  it('leaves conditional exports to Node', async () => {
+    const f = fixture('conditional-lib')
+    conditionalPkg(f.installed, 'conditional-lib', 11, 12)
+    const local = join(f.profile.dir, 'node_modules', 'conditional-lib')
+    conditionalPkg(local, 'conditional-lib', 21, 22)
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    expect(await importFrom('conditional-lib', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href))
+      .toMatchObject({ marker: 21 })
+    const addon = createRequire(import.meta.url)('node-addon-require-builtin') as { requireBuiltin(id: string): unknown }
+    const internal = addon.requireBuiltin('internal/modules/cjs/loader') as {
+      Module: {
+        new(id?: string): { filename?: string; paths?: string[] }
+        _nodeModulePaths(path: string): string[]
+        _resolveFilename(
+          request: string,
+          parent: { filename?: string; paths?: string[] },
+          isMain: boolean,
+          options: { conditions: Set<string> },
+        ): string
+      }
+    }
+    const parentFile = join(f.profile.dir, 'conditional-entry.cjs')
+    const parent = new internal.Module(parentFile)
+    parent.filename = parentFile
+    parent.paths = internal.Module._nodeModulePaths(f.profile.dir)
+    expect(internal.Module._resolveFilename(
+      'conditional-lib', parent, false, { conditions: new Set(['node', 'require', 'custom']) },
+    )).toBe(join(local, 'custom.cjs'))
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require('conditional-lib')).toEqual({ marker: 22 })
+    expect(require.resolve('conditional-lib')).toBe(join(local, 'require.cjs'))
+  })
+
+  it('passes explicit CommonJS conditions to the generation target', async () => {
+    const f = fixture('conditional-lib')
+    conditionalPkg(f.installed, 'conditional-lib', 11, 12)
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const addon = createRequire(import.meta.url)('node-addon-require-builtin') as { requireBuiltin(id: string): unknown }
+    const internal = addon.requireBuiltin('internal/modules/cjs/loader') as {
+      Module: {
+        new(id?: string): { filename?: string; paths?: string[] }
+        _nodeModulePaths(path: string): string[]
+        _resolveFilename(
+          request: string,
+          parent: { filename?: string; paths?: string[] },
+          isMain: boolean,
+          options: { conditions: Set<string> },
+        ): string
+      }
+    }
+    const parentFile = join(f.profile.dir, 'conditional-entry.cjs')
+    const parent = new internal.Module(parentFile)
+    parent.filename = parentFile
+    parent.paths = internal.Module._nodeModulePaths(f.profile.dir)
+
+    expect(internal.Module._resolveFilename(
+      'conditional-lib', parent, false, { conditions: new Set(['node', 'require', 'custom']) },
+    )).toBe(join(f.installed, 'custom.cjs'))
+  })
+
+  it('does not attach routed CommonJS anchors to the importing module', async () => {
+    const f = fixture()
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const addon = createRequire(import.meta.url)('node-addon-require-builtin') as { requireBuiltin(id: string): unknown }
+    const internal = addon.requireBuiltin('internal/modules/cjs/loader') as {
+      Module: {
+        new(id?: string): { children: unknown[]; filename?: string; paths?: string[] }
+        _nodeModulePaths(path: string): string[]
+        _resolveFilename(
+          request: string,
+          parent: { children: unknown[]; filename?: string; paths?: string[] },
+          isMain: boolean,
+        ): string
+      }
+    }
+    const parentFile = join(f.profile.dir, 'entry.cjs')
+    const parent = new internal.Module(parentFile)
+    parent.filename = parentFile
+    parent.paths = internal.Module._nodeModulePaths(f.profile.dir)
+    const originalChildren = [...parent.children]
+
+    expect(internal.Module._resolveFilename('resolution-lib', parent, false)).toBe(join(f.installed, 'index.cjs'))
+    expect(parent.children).toEqual(originalChildren)
+  })
+
+  it('reports routed CommonJS failures with the native require stack', async () => {
+    const f = fixture()
+    file(join(f.installed, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '1.0.0', type: 'module', main: './index.cjs',
+    }))
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const linkRequire = createRequire(join(f.profile.dir, 'entry-link.cjs'))
+    const linkError = thrownError(() => linkRequire.resolve('resolution-lib/missing.cjs'))
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+    const runtimeRequire = createRequire(join(f.profile.dir, 'entry-runtime.cjs'))
+    const runtimeError = thrownError(() => runtimeRequire.resolve('resolution-lib/missing.cjs'))
+
+    expect(runtimeError.requireStack).toEqual([
+      join(f.profile.dir, 'entry-runtime.cjs'),
+    ])
+    expect(runtimeError.message).not.toContain(f.installAnchor)
+    expect(linkError.requireStack).toEqual([join(f.profile.dir, 'entry-link.cjs')])
+  })
+
+  it('reports routed ESM failures from the original importer', async () => {
+    const f = fixture()
+    const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
+    const linkMessage = thrownMessage(() => resolveFrom('unavailable-lib', parent))
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+
+    expect(thrownMessage(() => resolveFrom('unavailable-lib', parent))).toBe(linkMessage)
+    expect(thrownMessage(() => resolveFrom('resolution-lib/private', parent)))
+      .toContain(` imported from ${fileURLToPath(parent)}`)
+  })
+
+  it('leaves an invalid generation manifest error to Node', async () => {
+    const f = fixture()
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    file(join(f.installed, 'package.json'), '{')
+    const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
+    expect(() => resolveFrom('resolution-lib', parent)).toThrow(/Invalid package config/u)
+    unlinkSync(join(generation.profilesDir, 'node_modules', 'resolution-lib'))
+    const registration = installProfileResolution(generation)
+    registrations.push(registration)
+
+    expect(() => resolveFrom('resolution-lib', parent)).toThrow(/Invalid package config/u)
+  })
+
+  it('does not fall back after Node selects a broken profile-local package', async () => {
+    const f = fixture('broken-lib')
+    file(join(f.profile.dir, 'node_modules', 'broken-lib', 'package.json'), JSON.stringify({
+      name: 'broken-lib',
+      exports: './missing.js',
+    }))
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(() => { require('broken-lib') }).toThrow(/Cannot find module|could not find/u)
+    await expect(importFrom(
+      'broken-lib', pathToFileURL(join(f.profile.dir, 'broken-entry.mjs')).href,
+    )).rejects.toThrow(/Cannot find module|Cannot find package/u)
+  })
+
+  it('does not fall back after the generation selects a missing exports target', async () => {
+    const f = fixture()
+    file(join(f.installed, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '1.0.0', type: 'module', exports: './missing.cjs',
+    }))
+    pkg(join(f.root, 'node_modules', 'resolution-lib'), 'resolution-lib', 2)
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+
+    expect(() => createRequire(join(f.profile.dir, 'entry.cjs')).resolve('resolution-lib'))
+      .toThrow(/Cannot find module/u)
+  })
+
+  it('does not fall back after the generation selects a missing legacy main', async () => {
+    const f = fixture()
+    file(join(f.installed, 'package.json'), JSON.stringify({
+      name: 'resolution-lib', version: '1.0.0', type: 'module', main: './missing.cjs',
+    }))
+    unlinkSync(join(f.installed, 'index.cjs'))
+    unlinkSync(join(f.installed, 'index.js'))
+    pkg(join(f.root, 'node_modules', 'resolution-lib'), 'resolution-lib', 2)
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+
+    expect(() => createRequire(join(f.profile.dir, 'entry.cjs')).resolve('resolution-lib'))
+      .toThrow(/valid "main" entry/u)
+  })
+
+  it('detects a dual-mode mismatch instead of accepting another package', async () => {
+    const f = fixture()
+    const disk = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const second = join(f.root, 'second')
+    pkg(second, 'resolution-lib', 2)
+    const mismatched = {
+      ...disk,
+      entries: disk.entries.map(entry => entry.name === 'resolution-lib'
+        ? { ...entry, packageDir: second, declarer: join(second, 'package.json') }
+        : entry),
+    }
+    const registration = installProfileResolution(mismatched, 'verify')
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(() => { require.resolve('resolution-lib') }).toThrow(/profile resolution mismatch/u)
+    await expect(importFrom(
+      'resolution-lib', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href,
+    )).rejects.toThrow(/profile resolution mismatch/u)
+  })
+
+  it('detects a dual-mode package metadata mismatch before import', async () => {
+    const f = fixture()
+    const disk = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const second = join(f.root, 'second')
+    pkg(second, 'resolution-lib', 2)
+    const mismatched = {
+      ...disk,
+      entries: disk.entries.map(entry => entry.name === 'resolution-lib'
+        ? { ...entry, packageDir: second, declarer: join(second, 'package.json') }
+        : entry),
+    }
+    const registration = installProfileResolution(mismatched, 'verify')
+    registrations.push(registration)
+
+    expect(() => registration.packageDir(
+      'resolution-lib', pathToFileURL(join(f.profile.dir, 'metadata.mjs')).href,
+    )).toThrow(/profile resolution mismatch/u)
+  })
+
+  it('detects a dual-mode package metadata hit present on only one backend', async () => {
+    const f = fixture()
+    const generation = await generationOf(f)
+    const registration = installProfileResolution(generation, 'verify')
+    registrations.push(registration)
+
+    expect(() => registration.packageDir(
+      'resolution-lib', pathToFileURL(join(f.profile.dir, 'metadata.mjs')).href,
+    )).toThrow(/disk selected nothing, generation selected/u)
+  })
+
+  it('detects package metadata present only in the dual-mode disk backend', async () => {
+    const f = fixture()
+    const disk = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const registration = installProfileResolution({
+      ...disk,
+      entries: disk.entries.filter(entry => entry.name !== 'resolution-lib'),
+    }, 'verify')
+    registrations.push(registration)
+
+    expect(() => registration.packageDir(
+      'resolution-lib', pathToFileURL(join(f.profile.dir, 'metadata.mjs')).href,
+    )).toThrow(/disk selected .*generation selected nothing/u)
+  })
+
+  it('reports a missing dual-mode generation target from the original importer', async () => {
+    const f = fixture()
+    const disk = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const missing = join(f.root, 'missing')
+    const mismatched = {
+      ...disk,
+      entries: disk.entries.map(entry => entry.name === 'resolution-lib'
+        ? { ...entry, packageDir: missing, declarer: join(missing, 'package.json') }
+        : entry),
+    }
+    const registration = installProfileResolution(mismatched, 'verify')
+    registrations.push(registration)
+    const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
+
+    expect(thrownMessage(() => resolveFrom('resolution-lib', parent))).toContain(fileURLToPath(parent))
+  })
+
+  it('accepts matching disk and generation targets in dual mode', async () => {
+    const f = fixture()
+    const generation = await healProfilesModuleFallback({
+      installAnchor: f.installAnchor,
+      profile: f.profile,
+      home: f.root,
+    })
+    const registration = installProfileResolution(generation, 'verify')
+    registrations.push(registration)
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require.resolve('resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    expect(await importFrom('resolution-lib', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href))
+      .toMatchObject({ marker: 1 })
+    const parent = pathToFileURL(join(f.profile.dir, 'metadata.mjs')).href
+    expect(registration.packageDir('resolution-lib', parent)).toBe(f.installed)
+    expect(registration.packageDir('missing-metadata', parent)).toBeUndefined()
+    expect(registration.packageDir('node:fs', parent)).toBeUndefined()
+    expect(registration.packageDir(
+      'missing-metadata', `${pathToFileURL(f.profile.dir).href}/%ZZ`,
+    )).toBeUndefined()
+  })
+
+  it('publishes an additive generation and replaces its miss cache atomically', async () => {
+    const f = fixture()
+    const added = join(f.root, 'added')
+    pkg(added, 'added-lib', 2)
+    const first = await generationOf(f)
+    const registration = installProfileResolution(first)
+    registrations.push(registration)
+    const parent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
+    expect(registration.packageDir('added-lib', parent)).toBeUndefined()
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    registration.replace({
+      ...first,
+      entries: [...first.entries, {
+        name: 'added-lib', packageDir: added, version: '2.0.0',
+        declarer: join(added, 'package.json'), scope: 'installation',
+      }],
+    })
+    expect(registration.packageDir('added-lib', parent)).toBe(added)
+    expect(require.resolve('added-lib')).toBe(join(added, 'index.cjs'))
+    expect(resolveFrom('added-lib', parent)).toBe(pathToFileURL(join(added, 'index.js')).href)
+  })
+
+  it('rejects changing an existing package mapping without publishing it', async () => {
+    const f = fixture()
+    const second = join(f.root, 'second')
+    pkg(second, 'resolution-lib', 2)
+    const first = await generationOf(f)
+    const registration = installProfileResolution(first)
+    registrations.push(registration)
+    const alias = join(f.root, 'resolution-lib-alias')
+    symlinkSync(f.installed, alias, process.platform === 'win32' ? 'junction' : 'dir')
+    registration.replace({
+      ...first,
+      entries: first.entries.map(entry => entry.name === 'resolution-lib'
+        ? { ...entry, packageDir: alias }
+        : entry),
+    })
+    const changed = {
+      ...first,
+      entries: first.entries.map(entry => entry.name === 'resolution-lib'
+        ? { ...entry, packageDir: second, version: '2.0.0', declarer: join(second, 'package.json') }
+        : entry),
+    }
+    expect(() => { registration.replace(changed) }).toThrow(/requires a process restart/u)
+    expect(() => {
+      registration.replace({
+        ...first,
+        entries: first.entries.map(entry => entry.name === 'resolution-lib'
+          ? { ...entry, version: '9.0.0' }
+          : entry),
+      })
+    }).toThrow(/requires a process restart/u)
+    expect(() => {
+      registration.replace({ ...first, localPackageNames: ['resolution-lib'] })
+    }).toThrow(/requires a process restart/u)
+    expect(() => {
+      registration.replace({ ...first, entries: first.entries.filter(entry => entry.name !== 'resolution-lib') })
+    }).toThrow(/requires a process restart/u)
+    expect(() => {
+      registration.replace({ ...first, profilesDir: join(f.root, 'other-profiles') })
+    }).toThrow(/cannot change its profile scope/u)
+    registration.replace({ ...first, localPackageNames: ['new-local'] })
+    registration.replace({ ...first, localPackageNames: ['new-local'] })
+    expect(() => { registration.replace(first) }).toThrow(/removing local package/u)
+    expect(registration.packageDir(
+      'resolution-lib', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href,
+    )).toBe(f.installed)
+  })
+
+  it('leaves non-package and out-of-scope metadata lookups to native resolution', async () => {
+    const f = fixture()
+    const outside = join(f.root, 'outside')
+    const outsidePackage = join(outside, 'node_modules', 'outside-lib')
+    pkg(outsidePackage, 'outside-lib', 5)
+    const scopedPackage = join(outside, 'node_modules', '@scope', 'outside')
+    pkg(scopedPackage, '@scope/outside', 6)
+    const ancestorPackage = join(f.root, 'node_modules', 'ancestor-lib')
+    pkg(ancestorPackage, 'ancestor-lib', 7)
+    const registration = installProfileResolution(await generationOf(f))
+    registrations.push(registration)
+    const profileParent = pathToFileURL(join(f.profile.dir, 'entry.mjs')).href
+    const outsideParent = pathToFileURL(join(outside, 'entry.mjs')).href
+    expect(registration.packageDir('', profileParent)).toBeUndefined()
+    expect(registration.packageDir('./local.js', profileParent)).toBeUndefined()
+    expect(registration.packageDir('/absolute.js', profileParent)).toBeUndefined()
+    expect(registration.packageDir('\\server\\share', profileParent)).toBeUndefined()
+    expect(registration.packageDir('#internal', profileParent)).toBeUndefined()
+    expect(registration.packageDir('@scope', profileParent)).toBeUndefined()
+    expect(registration.packageDir('node:fs', profileParent)).toBeUndefined()
+    expect(registration.packageDir('resolution-lib/private', profileParent)).toBe(f.installed)
+    expect(registration.packageDir('outside-lib', outsideParent)).toBe(outsidePackage)
+    expect(registration.packageDir('outside-lib', outsideParent)).toBe(outsidePackage)
+    expect(registration.packageDir('@scope/outside', outsideParent)).toBe(scopedPackage)
+    expect(registration.packageDir('@scope/outside/private', outsideParent)).toBe(scopedPackage)
+    expect(registration.packageDir('ancestor-lib', profileParent)).toBe(ancestorPackage)
+    expect(registration.packageDir('ancestor-lib', profileParent)).toBe(ancestorPackage)
+    expect(resolveFrom('outside-lib', outsideParent)).toBe(pathToFileURL(join(outsidePackage, 'index.js')).href)
+    expect(resolveFrom('outside-lib', outsideParent)).toBe(pathToFileURL(join(outsidePackage, 'index.js')).href)
+    expect(registration.packageDir('missing', `${pathToFileURL(f.profile.dir).href}/%ZZ`)).toBeUndefined()
+  })
+
+  it('leaves the published generation intact when successor construction fails', async () => {
+    const f = fixture()
+    const first = await generationOf(f)
+    const registration = installProfileResolution(first)
+    registrations.push(registration)
+    await expect(createProfileResolutionGeneration({
+      installAnchor: join(f.root, 'missing', 'package.json'),
+      profile: f.profile,
+      home: f.root,
+    })).rejects.toThrow()
+    expect(registration.packageDir(
+      'resolution-lib', pathToFileURL(join(f.profile.dir, 'entry.mjs')).href,
+    )).toBe(f.installed)
+  })
+
+  it('publishes and restores the generation inherited by owned Workers', async () => {
+    const f = fixture()
+    const generation = await generationOf(f)
+    const key = '@deepseek-ai/dsh-app-boot/profile-resolution'
+    const previous = getEnvironmentData(key)
+    const dispose = registerWorkerResolution(generation, 'verify')
+    try {
+      expect(getEnvironmentData(key)).toEqual({ generation, behavior: 'verify' })
+    } finally {
+      dispose()
+    }
+    expect(getEnvironmentData(key)).toBe(previous)
+  })
+
+  it('restores CommonJS resolution when the registration is disposed', async () => {
+    const f = fixture()
+    const registration = installProfileResolution(await generationOf(f))
+    const require = createRequire(join(f.profile.dir, 'entry.cjs'))
+    expect(require.resolve('resolution-lib')).toBe(join(f.installed, 'index.cjs'))
+    registration.dispose()
+    expect(() => { require.resolve('resolution-lib') }).toThrow(/Cannot find module/u)
+  })
+})
diff --git a/packages/boot/app-boot/tsdown.config.ts b/packages/boot/app-boot/tsdown.config.ts
index 12ce019be6..6af29018c2 100644
--- a/packages/boot/app-boot/tsdown.config.ts
+++ b/packages/boot/app-boot/tsdown.config.ts
@@ -4,16 +4,31 @@ import { defineConfig } from 'tsdown'
  * Embed Include while keeping Loader external so the built include tree and
  * app host bind to one Loader peer.
  */
-export default defineConfig({
-  entry: ['lib/types/index.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-  deps: {
-    alwaysBundle: ['@deepseek-ai/cordis-plugin-include'],
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+    deps: {
+      alwaysBundle: ['@deepseek-ai/cordis-plugin-include'],
+    },
   },
-})
+  {
+    entry: { 'worker/profile-resolution-bootstrap': 'lib/types/profile-resolution/worker-bootstrap.js' },
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+    deps: {
+      alwaysBundle: ['resolve.exports'],
+    },
+  },
+])
diff --git a/packages/bundle/base/README.i18n.yaml b/packages/bundle/base/README.i18n.yaml
index fd4137f069..292f948500 100644
--- a/packages/bundle/base/README.i18n.yaml
+++ b/packages/bundle/base/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 packages/bundle/base/README.md
-README.md: fdf2ca4115d87d1ae1ca363468e2140ea4fa896f
-README.zh.md: baaa2047a0e868a66ca8a7669a3a918c3a5b8d4a
+README.md: f9cc3e4d03a0d71d1f598d97633c0f89f7700b42
+README.zh.md: 2e98bb710502b62ad87f04ae768833487b4b5787
diff --git a/packages/bundle/base/README.md b/packages/bundle/base/README.md
index fdf2ca4115..f9cc3e4d03 100644
--- a/packages/bundle/base/README.md
+++ b/packages/bundle/base/README.md
@@ -47,7 +47,7 @@ Run `dsh --profile my-profile "your task"` and you get a working agent with mode
 
 ### What you get
 
-Out of the box, every profile built on this core provides: a DeepSeek model connection (the provider and model are configurable, and you can enable extra providers from your settings), the full tool set — file editing, shell commands, web search, public HTTP(S) fetch, subagents, task and goal tracking — durable sessions that survive restarts, and the default permission policy that confines file writes to your workspace and asks before risky actions. Web fetch runs without per-call approval; its provider rejects non-public destinations. Feedback stays in the Session log. [OTel session upload](../../session/session-telemetry-otel/README.md) defaults to `FEEDBACK_ONLY` for all users, including `deepseek-official`: new text feedback, message ratings, edits, and withdrawals release the complete canonical prefix through that event, including context. Later records wait for the next explicit feedback; sending an authorized batch needs no further interaction or model call. `DISABLED` prevents OTel capture. The opt-in [DeepSeek session-log contributor](../../session/session-log-deepseek/README.md) remains a separate request path.
+Out of the box, every profile built on this core provides: a DeepSeek model connection (the provider and model are configurable, and you can enable extra providers from your settings), the full tool set — file editing, shell commands, web search, public HTTP(S) fetch, subagents, task and goal tracking — durable sessions that survive restarts, and the default permission policy that confines file writes to your workspace and asks before risky actions. Web fetch runs without per-call approval; its provider rejects non-public destinations. Feedback stays in the Session log. [OTel session upload](../../session/session-telemetry-otel/README.md) defaults to `FEEDBACK_ONLY` for all users, including `deepseek-official`: new text feedback, message ratings, edits, and withdrawals release the complete canonical prefix through that event, including context. Later records wait for the next explicit feedback; sending an authorized batch needs no further interaction or model call. `DISABLED` prevents OTel capture. The default-on [DeepSeek session-log contributor](../../session/session-log-deepseek/README.md) remains a separate request path.
 
 Default file editing uses `read`, `write`, and `edit`. The `str_replace_editor` tool remains available as an explicit opt-in. To add it to a base-backed profile, put this entry in the profile, home, or invocation patch:
 
diff --git a/packages/bundle/base/README.zh.md b/packages/bundle/base/README.zh.md
index baaa2047a0..2e98bb7105 100644
--- a/packages/bundle/base/README.zh.md
+++ b/packages/bundle/base/README.zh.md
@@ -47,7 +47,7 @@ kind: "package-bundle"
 
 ### 你得到什么
 
-开箱即用，基于本核心构建的每个 profile 都提供：DeepSeek 模型连接（提供方与模型可配置，你还可以在设置中启用额外提供方）、完整工具集——文件编辑、shell 命令、web 搜索、公开 HTTP(S) 抓取、subagent、任务与目标跟踪——可跨重启存活的持久会话，以及默认权限策略：把文件写入限制在工作区内，危险操作前征询许可。Web 抓取无需逐次审批，其提供方会拒绝非公开目的地址。反馈保存在会话日志中。[OTel 会话上传](../../session/session-telemetry-otel/README.zh.md)对所有用户默认使用 `FEEDBACK_ONLY`，包括 `deepseek-official`：新的文本反馈、消息评分、编辑与撤回会释放截至该事件的完整规范会话日志前缀，包含上下文。后续记录等待下一次显式反馈；发送已授权批次无需进一步交互或模型调用。`DISABLED` 阻止 OTel 捕获。需主动开启的 [DeepSeek 会话日志贡献器](../../session/session-log-deepseek/README.zh.md)仍是独立的请求路径。
+开箱即用，基于本核心构建的每个 profile 都提供：DeepSeek 模型连接（提供方与模型可配置，你还可以在设置中启用额外提供方）、完整工具集——文件编辑、shell 命令、web 搜索、公开 HTTP(S) 抓取、subagent、任务与目标跟踪——可跨重启存活的持久会话，以及默认权限策略：把文件写入限制在工作区内，危险操作前征询许可。Web 抓取无需逐次审批，其提供方会拒绝非公开目的地址。反馈保存在会话日志中。[OTel 会话上传](../../session/session-telemetry-otel/README.zh.md)对所有用户默认使用 `FEEDBACK_ONLY`，包括 `deepseek-official`：新的文本反馈、消息评分、编辑与撤回会释放截至该事件的完整规范会话日志前缀，包含上下文。后续记录等待下一次显式反馈；发送已授权批次无需进一步交互或模型调用。`DISABLED` 阻止 OTel 捕获。默认开启的 [DeepSeek 会话日志贡献器](../../session/session-log-deepseek/README.zh.md)仍是独立的请求路径。
 
 默认文件编辑使用 `read`、`write` 和 `edit`。`str_replace_editor` 工具仍可显式启用。要将它加入基于 base 的 profile，请在 profile、home 或逐次调用 patch 中添加以下条目：
 
diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md
index 6c8b1a54ac..b19c13733a 100644
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -136,7 +136,7 @@ If `test:gui` is red on code you did not touch, neither silently fix nor ignore
 Bringing up a new `packages/client/<name>` plugin package (ui-workspace is a complete example; ui-sidebar/ui-user-questions are minimal skeletons):
 
 1. **Package skeleton**: `package.json` (`@deepseek-ai/dsh-client-<name>`, exports `.`/`./client`/`./src/*`/`./package.json`, optional `./invariant` only for an independent runtime relationship, `dsh.client` manifest, `files` list), `tsconfig.json` (extends `tsconfig.base.client.json`, one `references` entry per workspace dependency), `tsdown.config.ts` (`clientBundle(id, ['lib/types/index.js'])`, plus `lib/types/invariant.js` only when published), `src/index.ts` (empty node-half apply), optional `src/invariant.ts`, `src/css-modules.d.ts` when using CSS Modules, and `README.md` with the Model Experience section and the reason when no invariant is published.
-2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dsh.client` row in `packages/bundle/web-app/cordis.patch.yml`; a `packages/bundle/web-app/package.json` dependency (profile boots resolve bare row names through the healed `$DSH_HOME/profiles/node_modules` fallback, which mirrors the app's and each bundle's declared dependencies — a row whose package no manifest declares fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
+2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dsh.client` row in `packages/bundle/web-app/cordis.patch.yml`; a `packages/bundle/web-app/package.json` dependency (profile boots resolve bare row names through the computed profile resolution generation, which the default link mode materializes on disk — a row whose package no manifest declares fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
 3. **dsh.client manifest semantics**: `platform: 'web'` always, and the declaration requires a `./client` export (the scan throws without one); `immediately: true` only for stage-one-prefetch infrastructure rows. `inject` lists package-name dependency edges — they are **informational only** (preflight display, HMR diffing); they do not sequence entry activation or apply order. Activation order is Cordis fiber inject waiting on *services*, nothing else. A non-baseline `external` request sequences its dynamic supplier ahead of the consumer — see [shared modules](#shared-modules-and-the-module-graph).
 4. **Registering into another package's slot**: apply order is unconstrained, and a business service is not a declaration barrier. Use `ctx.slots.inject(name, () => ctx.slots.register(...))`; it waits on the actual declaration, removes the contribution when that declaration collapses, reruns after redeclaration, and leaves with the caller's plugin fiber. Return a generator yielding each registration when several contributions must install and roll back atomically. A bare `slots.register` into an undeclared slot remains an error; keep service edges only for services the contribution actually reads.
 5. Rebuild the bundle (`pnpm --filter <pkg> bundle`) before probing a live `dsh web` server — the registry serves `lib/client.js`, not sources.
diff --git a/packages/client/ui-attachment/README.i18n.yaml b/packages/client/ui-attachment/README.i18n.yaml
index d573ab686a..8b9ac24565 100644
--- a/packages/client/ui-attachment/README.i18n.yaml
+++ b/packages/client/ui-attachment/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 packages/client/ui-attachment/README.md
-README.md: c2b429b5ea2f190ab113697aa97eb35c7adcaa29
-README.zh.md: e2d6b3d45eaee7d652c33f223cfb8f061c69c72a
+README.md: 3c69b387914c631f50d783c4a35089ab8db1668f
+README.zh.md: c21b2acdbeb7ced6e9a8733a861c5324121ad194
diff --git a/packages/client/ui-attachment/README.md b/packages/client/ui-attachment/README.md
index c2b429b5ea..3c69b38791 100644
--- a/packages/client/ui-attachment/README.md
+++ b/packages/client/ui-attachment/README.md
@@ -52,6 +52,7 @@ The plugin waits for `conversation.input.attachments`, `conversation.message.ima
 | File | Role |
 |---|---|
 | [`src/client/ComposerAttachments.tsx`](src/client/ComposerAttachments.tsx) | Ordered image/file rail + drop overlay assembly |
+| [`src/client/drop-events.ts`](src/client/drop-events.ts) | Document drag-and-drop listeners installed by each mounted attachment view's effect |
 | [`src/AttachmentRail.tsx`](src/AttachmentRail.tsx) | Horizontal attachment overflow, wheel translation, edge arrows |
 | [`src/client/MessageImages.tsx`](src/client/MessageImages.tsx) | Per-message gallery + lightbox assembly |
 | [`src/MessageImage.tsx`](src/MessageImage.tsx) | Single image sizing, load/retry, click-to-open; local submission-echo previews render their object URL directly |
diff --git a/packages/client/ui-attachment/README.zh.md b/packages/client/ui-attachment/README.zh.md
index e2d6b3d45e..c21b2acdbe 100644
--- a/packages/client/ui-attachment/README.zh.md
+++ b/packages/client/ui-attachment/README.zh.md
@@ -52,6 +52,7 @@ Chat 中的一条用户消息把文件与图片放在同一个靠右、可换行
 | 文件 | 职责 |
 |---|---|
 | [`src/client/ComposerAttachments.tsx`](src/client/ComposerAttachments.tsx) | 有序图片／文件栏＋拖放遮罩的组装 |
+| [`src/client/drop-events.ts`](src/client/drop-events.ts) | 每个已挂载附件视图的 effect 安装的 document 拖放监听 |
 | [`src/AttachmentRail.tsx`](src/AttachmentRail.tsx) | 附件横向溢出、滚轮转换、边缘箭头 |
 | [`src/client/MessageImages.tsx`](src/client/MessageImages.tsx) | 每消息画廊＋灯箱的组装 |
 | [`src/MessageImage.tsx`](src/MessageImage.tsx) | 单图尺寸、加载／重试、点击打开；本地提交回显预览直接显示其 object URL |
diff --git a/packages/client/ui-attachment/src/client/ComposerAttachments.tsx b/packages/client/ui-attachment/src/client/ComposerAttachments.tsx
index fd469195bf..ca2e1e1aa7 100644
--- a/packages/client/ui-attachment/src/client/ComposerAttachments.tsx
+++ b/packages/client/ui-attachment/src/client/ComposerAttachments.tsx
@@ -9,6 +9,7 @@ import { DropOverlay } from '../DropOverlay.tsx'
 import { FileCard } from '../FileCard.tsx'
 import { ImageLightbox } from '../ImageLightbox.tsx'
 import { attachmentRailLabels, dropOverlayLabels, fileCardLabels, lightboxLabels } from './labels.ts'
+import { installDocumentDropEvents } from './drop-events.ts'
 import css from './ComposerAttachments.module.css'
 
 /** Rail item retaining its browser-owned attachment for callbacks. */
@@ -29,54 +30,7 @@ export function ComposerAttachments({
   }, [attachments, preview])
 
   useEffect(() => {
-    const fileTransfer = (event: globalThis.DragEvent): DataTransfer | null => {
-      const dataTransfer = event.dataTransfer
-      if (dataTransfer === null || !dataTransfer.types.includes('Files')) return null
-      return dataTransfer
-    }
-    const reset = (): void => {
-      dragDepth.current = 0
-      setDragActive(false)
-    }
-    const onDragEnter = (event: globalThis.DragEvent): void => {
-      if (fileTransfer(event) === null) return
-      event.preventDefault()
-      dragDepth.current += 1
-      setDragActive(true)
-    }
-    const onDragOver = (event: globalThis.DragEvent): void => {
-      const dataTransfer = fileTransfer(event)
-      if (dataTransfer === null) return
-      event.preventDefault()
-      dataTransfer.dropEffect = canAcceptDrop ? 'copy' : 'none'
-    }
-    const onDragLeave = (event: globalThis.DragEvent): void => {
-      if (fileTransfer(event) === null) return
-      dragDepth.current = Math.max(0, dragDepth.current - 1)
-      if (dragDepth.current === 0) setDragActive(false)
-      const leftViewport = event.clientX <= 0 || event.clientY <= 0
-        || event.clientX >= window.innerWidth || event.clientY >= window.innerHeight
-      if ((event.target === document.documentElement || event.target === document.body) && leftViewport) reset()
-    }
-    const onDrop = (event: globalThis.DragEvent): void => {
-      const dataTransfer = fileTransfer(event)
-      if (dataTransfer === null) return
-      event.preventDefault()
-      reset()
-      if (canAcceptDrop) onAddFiles([...dataTransfer.files])
-    }
-    document.addEventListener('dragenter', onDragEnter)
-    document.addEventListener('dragover', onDragOver)
-    document.addEventListener('dragleave', onDragLeave)
-    document.addEventListener('drop', onDrop)
-    window.addEventListener('dragend', reset)
-    return () => {
-      document.removeEventListener('dragenter', onDragEnter)
-      document.removeEventListener('dragover', onDragOver)
-      document.removeEventListener('dragleave', onDragLeave)
-      document.removeEventListener('drop', onDrop)
-      window.removeEventListener('dragend', reset)
-    }
+    return installDocumentDropEvents(canAcceptDrop, onAddFiles, dragDepth, setDragActive)
   }, [canAcceptDrop, onAddFiles])
 
   const railItems = useMemo<ComposerRailItem[]>(() => attachments.map(attachment => ({
diff --git a/packages/client/ui-attachment/src/client/drop-events.ts b/packages/client/ui-attachment/src/client/drop-events.ts
new file mode 100644
index 0000000000..e04cbd43d0
--- /dev/null
+++ b/packages/client/ui-attachment/src/client/drop-events.ts
@@ -0,0 +1,66 @@
+/** Document drag-and-drop listeners owned by one mounted attachment view. */
+import type { ComposerAttachmentsProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+
+/**
+ * Install one attachment view's file-drop listeners.
+ * @param canAcceptDrop - whether this view accepts the dropped files.
+ * @param onAddFiles - attachment intake callback.
+ * @param dragDepth - the view's retained nested-drag counter.
+ * @param setDragActive - publish whether a file drag is active.
+ * @returns cleanup for exactly these listeners.
+ */
+export function installDocumentDropEvents(
+  canAcceptDrop: ComposerAttachmentsProps['canAcceptDrop'],
+  onAddFiles: ComposerAttachmentsProps['onAddFiles'],
+  dragDepth: { current: number },
+  setDragActive: (active: boolean) => void,
+): () => void {
+  const fileTransfer = (event: globalThis.DragEvent): DataTransfer | null => {
+    const dataTransfer = event.dataTransfer
+    if (dataTransfer === null || !dataTransfer.types.includes('Files')) return null
+    return dataTransfer
+  }
+  const reset = (): void => {
+    dragDepth.current = 0
+    setDragActive(false)
+  }
+  const onDragEnter = (event: globalThis.DragEvent): void => {
+    if (fileTransfer(event) === null) return
+    event.preventDefault()
+    dragDepth.current += 1
+    setDragActive(true)
+  }
+  const onDragOver = (event: globalThis.DragEvent): void => {
+    const dataTransfer = fileTransfer(event)
+    if (dataTransfer === null) return
+    event.preventDefault()
+    dataTransfer.dropEffect = canAcceptDrop ? 'copy' : 'none'
+  }
+  const onDragLeave = (event: globalThis.DragEvent): void => {
+    if (fileTransfer(event) === null) return
+    dragDepth.current = Math.max(0, dragDepth.current - 1)
+    if (dragDepth.current === 0) setDragActive(false)
+    const leftViewport = event.clientX <= 0 || event.clientY <= 0
+      || event.clientX >= window.innerWidth || event.clientY >= window.innerHeight
+    if ((event.target === document.documentElement || event.target === document.body) && leftViewport) reset()
+  }
+  const onDrop = (event: globalThis.DragEvent): void => {
+    const dataTransfer = fileTransfer(event)
+    if (dataTransfer === null) return
+    event.preventDefault()
+    reset()
+    if (canAcceptDrop) onAddFiles([...dataTransfer.files])
+  }
+  document.addEventListener('dragenter', onDragEnter)
+  document.addEventListener('dragover', onDragOver)
+  document.addEventListener('dragleave', onDragLeave)
+  document.addEventListener('drop', onDrop)
+  window.addEventListener('dragend', reset)
+  return () => {
+    document.removeEventListener('dragenter', onDragEnter)
+    document.removeEventListener('dragover', onDragOver)
+    document.removeEventListener('dragleave', onDragLeave)
+    document.removeEventListener('drop', onDrop)
+    window.removeEventListener('dragend', reset)
+  }
+}
diff --git a/packages/client/ui-chat/README.i18n.yaml b/packages/client/ui-chat/README.i18n.yaml
index c65f99e1d5..966f603db7 100644
--- a/packages/client/ui-chat/README.i18n.yaml
+++ b/packages/client/ui-chat/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 packages/client/ui-chat/README.md
-README.md: 254c511a023aa8217b73cc0fe3802f13f2a63d80
-README.zh.md: d79f8b5060bd6a452ddaf018074adaea88b85604
+README.md: c7c9fb7cb2a9a149fae9b27db78e019d821dfb95
+README.zh.md: 386d7aae91b157a7b09fcd0515bfd8d075a39638
diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md
index 254c511a02..c7c9fb7cb2 100644
--- a/packages/client/ui-chat/README.md
+++ b/packages/client/ui-chat/README.md
@@ -41,7 +41,7 @@ Each nonempty appended `system/message` owns a collapsed prompt row, including a
 
 A completed Turn shows an expandable usage row only when the loaded window includes `turn/start` and every started model attempt reports safe, exact usage. The row omits unavailable optional buckets. Incomplete or contradictory accounting hides the complete disclosure instead of presenting a partial total.
 
-Reply timing survives reopening history: recorded token timestamps supply first-token latency and generation duration, including the Step's first token from an earlier retry attempt. Missing Step starts or token timestamps leave the affected metrics unavailable.
+After Assistant replies settle, the completed-turn timing dialog omits TTFT and decoding speed, both after live replies and after reopening history. Elapsed turn time remains available. The Session Stats pill reads timing independently from its durable projection.
 
 <a id="completed-turn-footer"></a>
 ## Completed-turn footer
@@ -53,6 +53,8 @@ The completed-turn action footer starts 20px below the preceding prose or extens
 <a id="turn-process-folding"></a>
 ## Turn Process Folding
 
+Each reasoning row starts collapsed, including during streaming and in reasoning-only replies. Clicking the row opens or closes its complete text; incoming answer text, Tool calls, and stream completion preserve that choice. The collapsed summary follows the latest reasoning line while streaming and shows the first line after settlement.
+
 Settings → General exposes a persisted, localized `Normal` / `Compact` conversation-display preference in the `ui-chat` namespace; `Compact` is the default. Normal leaves process rows visible and renders no Turn-process control. In Compact mode, the System prompt remains independently visible before the opening User throughout the Turn. Context injection, reasoning, Assistant material, Tool rows, and Retry rows remain expanded while a Turn is open. At `turn/end`, its latest Step becomes the final-answer boundary only when it contains non-blank text, an image, or an unknown visible block—and no Tool-call block; preceding Context injection, reasoning, earlier Assistant material, Tool rows, and Retry rows then collapse by default. The control reports Turn-wide durable counts for non-subagent Tool calls, reply-bearing Assistant messages before the final answer, and subagent delegation calls; zero-valued segments are omitted, the Tool and subagent figures are mutually exclusive, and neither System prompt nor Context injection contributes a count. When all three counts are zero, the process still folds and the control reads `Thought for a while`. A full-width divider below the summary separates it from the answer or expanded process rows. User and steering messages, System prompt, error, max-token, and turn-tail rows stay outside, and a closed Turn with no final answer keeps all process evidence visible. A newly available process control is inserted without changing the relative order of existing rows: opening human input precedes the control and process rows from their first projection, while System prompt remains above that input. While older history remains available through Load earlier, process controls stay absent and no members are hidden; once history is complete, every eligible closed Turn uses the collapsed default immediately. Stable Chat Node Seats keep every renderer mounted, hidden members add no flow spacing, and a closed control sits 8px above its answer only when no independent input intervenes. Completion collapse does not depend on tail-follow position, so a reader above the tail may see the transcript reflow. An automatic collapse that would hide keyboard focus keeps the group open and leaves focus in place; a manual close focuses the process control before hiding its members. The session-scoped store records only manually expanded Turn-and-answer-Step generations; a different answer generation starts collapsed.
 
 -----
diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md
index d79f8b5060..386d7aae91 100644
--- a/packages/client/ui-chat/README.zh.md
+++ b/packages/client/ui-chat/README.zh.md
@@ -43,7 +43,7 @@ kind: "package-reference"
 
 只有当已加载窗口包含 `turn/start`，且每次已启动的模型尝试都报告安全、精确的用量时，已完成轮次才显示可展开的用量行。该行会省略不可用的可选用量桶。记账不完整或相互矛盾时，整个详情都不显示，避免把部分总量冒充完整结果。
 
-重新打开历史后仍保留回复计时：记录中的 token 时间戳提供首 token 延迟和生成耗时，包括步骤中更早重试尝试的首个 token。缺少步骤起点或 token 时间戳时，受影响的指标保持不可用。
+Assistant 回复结算后，已完成轮次的计时对话框不显示 TTFT 和解码速度，实时回复完成后和重新打开历史后都如此。轮次总耗时仍可用。Session Stats 药丸从其持久化投影独立读取计时。
 
 <a id="completed-turn-footer"></a>
 ## 已完成轮次的页脚
@@ -55,6 +55,8 @@ kind: "package-reference"
 <a id="turn-process-folding"></a>
 ## 轮次过程折叠
 
+每个思考行初始都折叠，包括流式输出期间和仅含思考的回复。点击该行可展开或收起完整文本；后续回答文本、工具调用和流结束都保留用户的选择。折叠摘要在流式输出期间跟随最新思考行，结算后显示第一行。
+
 「设置 → 通用设置」提供持久化到 `ui-chat` 命名空间的「标准」/「紧凑」对话显示偏好，默认使用「紧凑」。标准模式保持所有过程行可见且不渲染轮次过程控件。紧凑模式下，系统提示词在整个轮次中始终独立显示于开场 User 上方。轮次打开期间，上下文注入、推理、Assistant 内容、工具行与重试行始终展开。到 `turn/end` 时，最后一个步骤只有在包含非空文本、图片或未知可见块且不含工具调用块时才成为最终答案边界；边界之前的上下文注入、推理、较早 Assistant 内容、工具行与重试行随后默认收起。控件展示覆盖整个轮次的非 subagent 工具调用数、最终答案之前带回复内容的 Assistant 消息数和 subagent 委派数；值为 0 的分段省略，工具调用与 subagent 两项互斥，系统提示词与上下文注入都不增加计数。三项全为 0 时过程仍会收起，控件标题显示「已思考」（英文为 `Thought for a while`）。摘要下方的通栏分隔线将其与正文或展开后的过程行隔开。用户与 steering 消息、系统提示词、错误、最大 token 与 turn-tail 行留在过程组外；关闭时没有最终答案的轮次保留全部过程证据。新的过程控件插入时不会改变既有行的相对顺序：开场人工输入从首次投影起便位于控件和过程行之前，系统提示词则始终位于该输入上方。只要仍可通过「加载更早」获取历史，过程控件就不出现，也不会隐藏任何成员；历史加载完整后，每个合格的已关闭轮次立即使用默认收起状态。稳定 Chat Node Seat 会让每个 renderer 保持挂载，隐藏成员不产生消息流间距；只有中间没有独立输入时，收起控件才与正文相隔 8px。完成后的收起不依赖是否跟随尾部，因此正在上方阅读的用户可能看到 transcript 重排。若自动收起会隐藏当前键盘焦点，则过程组保持展开且焦点留在原处；手动收起会先把焦点移到过程控件，再隐藏成员。会话作用域存储只记录用户手动展开的「轮次 + 正文步骤」generation；不同正文 generation 默认收起。
 
 -----
diff --git a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
index 51300f6d02..3212801e00 100644
--- a/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-chat/src/client/chat/AssistantMarkdown.tsx
@@ -58,8 +58,6 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
     return { resolve: value => localPathMediaUrl(protocol, origin, value) }
   }, [])
   const last = blocks.length - 1
-  const hasBodyOrToolCall = blocks.some(block => block.kind === 'tool-call'
-    || (block.kind === 'text' && block.text.trim() !== ''))
   // Tool-call heads render as tool rows in the chat view's grouping pass, so
   // a node that is only those heads (or empty) would paint an empty root
   // between tool groups — skip the shell unless something visible remains.
@@ -91,12 +89,7 @@ export const AssistantMarkdown = memo(function AssistantMarkdown({
             hidden={reasoningHidden}
             reveal={revealProcess}
           >
-            <ReasoningRow
-              text={block.text}
-              running={streaming && i === last}
-              defaultExpanded={!hasBodyOrToolCall && block.text.trim() !== ''}
-              t={t}
-            />
+            <ReasoningRow text={block.text} running={streaming && i === last} t={t} />
           </ProcessReasoning>,
         )
         break
diff --git a/packages/client/ui-chat/src/client/chat/MessageItem.module.css b/packages/client/ui-chat/src/client/chat/MessageItem.module.css
index 8507492a70..a8ccc480a8 100644
--- a/packages/client/ui-chat/src/client/chat/MessageItem.module.css
+++ b/packages/client/ui-chat/src/client/chat/MessageItem.module.css
@@ -53,6 +53,10 @@
    hover/focus disclosure for the summary body. Dimmed title (not
    label-primary) — the row is a boundary notice, not conversation content. */
 .compactionRow {
+  /* The toggle's line, and the band a pinned toggle occupies. The button's
+     height and the offset that holds a summary's code banner below that band
+     are the same measurement, so both read it from here. */
+  --dsh-compaction-header-height: calc(24px + var(--dsh-content-font-delta, 0px));
   padding: 2px 0;
 }
 
@@ -60,7 +64,7 @@
   display: flex;
   align-items: center;
   width: 100%;
-  height: calc(24px + var(--dsh-content-font-delta, 0px));
+  height: var(--dsh-compaction-header-height);
   min-width: 0;
   padding: 0;
   border: none;
@@ -71,6 +75,41 @@
   text-align: left;
 }
 
+/* The summary body flows uncapped with the page, so a long checkpoint summary
+   carries this toggle off the top of the viewport. Pin it to the conversation
+   scroll container's top while the row is open (the body is a sibling rendered
+   only when expanded); the base background masks the prose scrolling under it.
+   The square corners apply for as long as the row is open, pinned or not: the
+   fill is what masks the prose, and a 6px radius would leave that prose visible
+   in the corners. z-index outranks the markdown code block's own sticky banner
+   (z-index 6 in CodeBlock.module.css); that banner itself stops below this
+   toggle (rule below), so a summary's fenced code block never puts a control
+   inside the toggle's band. */
+.compactionRow:has(.compactionBody) .compactionButton {
+  position: sticky;
+  top: 0;
+  z-index: 7;
+  border-radius: 0;
+  background: var(--dsw-alias-bg-base);
+}
+
+/* A fenced code block in the summary pins its banner at the scrollport top,
+   where this pinned toggle already sits, and the toggle's band covers the
+   banner's Copy control. Stop the banner below the toggle instead, on the same
+   measurement the toggle's own height uses. This rule beats CodeBlock's
+   `.bannerWrap { top: 0 }` by specificity (0,2,0 against 0,1,0), not by
+   declaration order: the two sheets load in their own packages. */
+.compactionBody :has(> [data-code-block-banner]) {
+  top: var(--dsh-compaction-header-height);
+}
+
+/* Pinned, the toggle needs an opaque hover fill: the default translucent hover
+   token below would let the scrolling prose show through the moment the pointer
+   lands on the toggle to collapse it. */
+.compactionRow:has(.compactionBody) .compactionButton:hover {
+  background: var(--dsw-alias-interactive-bg-hover-solid);
+}
+
 .compactionButton:not(:disabled) {
   cursor: pointer;
 }
diff --git a/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css b/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
index 489d431236..20a786b271 100644
--- a/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
+++ b/packages/client/ui-chat/src/client/chat/ReasoningRow.module.css
@@ -13,6 +13,22 @@
   overflow: hidden;
 }
 
+/* Think's body flows uncapped with the page (unlike the capped tool cards,
+   which scroll inside their own card), so a long reasoning chain carries the
+   disclosure header off the top of the viewport and buries the collapse toggle.
+   Pin the header to the conversation scroll container's top while the row is
+   open so the toggle stays reachable; the base background masks the prose
+   scrolling under it. Gated on DisclosureRow's `data-open` so a collapsed row
+   scrolls away normally. The body is plain text with no sticky descendant, so
+   any positive z-index clears the flow; the compaction marker, whose markdown
+   body can pin a code-block banner, needs a higher rank. */
+.root[data-expanded] [data-open] [data-disclosure-row] {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  background: var(--dsw-alias-bg-base);
+}
+
 .root[data-state='running'] .row::after {
   content: '';
   position: absolute;
diff --git a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
index bb22eea778..59705b2e4c 100644
--- a/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
+++ b/packages/client/ui-chat/src/client/chat/ReasoningRow.tsx
@@ -17,23 +17,16 @@ function latestLine(text: string): string {
 }
 
 /**
- * Render one assistant reasoning block as the Think disclosure row. The
+ * Render one assistant reasoning block collapsed until the reader opens it. The
  * collapsed summary omits double-asterisk markers; expanded content preserves
  * the complete text.
  * @param props.text - complete or streaming reasoning text.
  * @param props.running - whether this block is the streaming tail.
- * @param props.defaultExpanded - expanded state until the reader toggles it.
  * @param props.t - conversation locale seat for the running status.
  * @returns the reasoning disclosure.
  */
-export function ReasoningRow({ text, running, defaultExpanded, t }: {
-  text: string
-  running: boolean
-  defaultExpanded: boolean
-  t: ChatViewSlotProps['t']
-}) {
-  const [expandedOverride, setExpandedOverride] = useState<boolean>()
-  const expanded = expandedOverride ?? defaultExpanded
+export function ReasoningRow({ text, running, t }: { text: string; running: boolean; t: ChatViewSlotProps['t'] }) {
+  const [expanded, setExpanded] = useState(false)
   const summary = (running ? latestLine(text) : firstLine(text)).replaceAll('**', '')
 
   return (
@@ -54,7 +47,7 @@ export function ReasoningRow({ text, running, defaultExpanded, t }: {
         open={expanded}
         expandable
         expandOnRowClick
-        onToggle={() => { setExpandedOverride(!expanded) }}
+        onToggle={() => { setExpanded(value => !value) }}
         collapsedContent={(
           <>
             <span className={css.separator} aria-hidden />
diff --git a/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts b/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts
index aecfa43c5e..41093124a8 100644
--- a/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts
+++ b/packages/client/ui-chat/src/client/conversation-nodes/assistant.ts
@@ -4,7 +4,6 @@ import type {
   ConversationNodeContext, ConversationNodeDefinition,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { StreamChunk } from '@deepseek-ai/dsh-llm'
-import { assistantStreamFirstTokenTime } from '@deepseek-ai/dsh-llm/assistant-stream'
 import type {} from '@deepseek-ai/dsh-llm-retry/types'
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import type { AssistantChatData } from '../contract/chat-nodes.ts'
@@ -162,17 +161,6 @@ function updateChunk(
   }
 }
 
-/** The Step retains its first token across live chunks and settled retry attempts. */
-function settleTiming(
-  state: AssistantState,
-  event: SessionEvent<'assistant/message' | 'assistant/attempt'>,
-): AssistantState {
-  return {
-    ...state,
-    firstTokenTime: state.firstTokenTime ?? assistantStreamFirstTokenTime(event.data.stream),
-  }
-}
-
 function settleMessage(
   state: AssistantState,
   match: ConversationMatch,
@@ -180,7 +168,7 @@ function settleMessage(
 ): AssistantState {
   const blocks = toAssistantBlocks(event.data.message.content)
   return {
-    ...settleTiming(state, event),
+    ...state,
     blocks,
     visibleBlocks: countVisibleBlocks(blocks),
     hidden: false,
@@ -248,11 +236,6 @@ function fallbackState(context: ConversationNodeContext<AssistantState>): Assist
       state = updateChunk(state, match.event.data.chunk, match.event.seq, match.event.time)
       continue
     }
-    if (match.event.type === 'assistant/attempt') {
-      state ??= initialState(match.event.data.turn, match.event.data.step)
-      state = settleTiming(state, match.event)
-      continue
-    }
     if (match.event.type === 'assistant/message') {
       state ??= initialState(match.event.data.turn, match.event.data.step)
       state = settleMessage(state, match, match.event)
@@ -313,7 +296,6 @@ export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
   match: (event) => {
     if (event.type === 'step/start') return { id: `${event.data.turn}:${event.data.step}`, role: 'start' }
     if (event.type === 'assistant/live-chunk'
-      || event.type === 'assistant/attempt'
       || (event.type === 'assistant/message' && event.surfaceOp === 'append')) {
       return { id: `${event.data.turn}:${event.data.step}`, role: 'update' }
     }
@@ -331,14 +313,13 @@ export const assistantDefinition: ConversationNodeDefinition<AssistantState> = {
       return updateChunk(context.state, match.event.data.chunk, match.event.seq, match.event.time)
     }
     if (match.event.type === 'assistant/message') return settleMessage(context.state, match, match.event)
-    if (match.event.type === 'assistant/attempt') return settleTiming(context.state, match.event)
     if (match.event.type === 'llm/retry') {
       return resetForRetry(context.state)
     }
     return context.state
   },
   publication: (match) => {
-    if (match.event.type === 'step/start' || match.event.type === 'assistant/attempt') return 'none'
+    if (match.event.type === 'step/start') return 'none'
     if (match.event.type !== 'assistant/live-chunk') return 'immediate'
     const type = match.event.data.chunk.type
     return type === 'usage' || type === 'finish' ? 'none' : 'animation-frame'
diff --git a/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx b/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx
index 56ed85a3e9..cc447d8ff0 100644
--- a/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx
+++ b/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx
@@ -830,6 +830,24 @@ describe('MessageItem arms', () => {
     expect(row.getAttribute('aria-expanded')).toBe('false')
   })
 
+  it('anchors the sticky-header selector: the compaction body sits under compactionRow only while open', () => {
+    const view = render(
+      <MessageItem t={t} node={{
+        kind: 'compaction', seq: 5, time: 1_000,
+        summary: '## 摘要标题\n\n保留的事实。',
+        summaryEventSeq: 4,
+        shadowedItemCount: 16,
+        shadowedTokenCount: 11_309,
+      }}
+      />,
+    )
+    // Collapsed there is no body sibling, so the rule's `:has(.compactionBody)`
+    // gate never matches.
+    expect(view.container.querySelector('[class*="compactionRow"] [class*="compactionBody"]')).toBeNull()
+    fireEvent.click(view.getByRole('button', { name: /上下文已压缩/ }))
+    expect(view.container.querySelector('[class*="compactionRow"] [class*="compactionBody"]')).not.toBeNull()
+  })
+
   it('a marker whose cited summary event fell outside the window is not expandable', () => {
     const view = render(<MessageItem t={t} node={{
       kind: 'compaction', seq: 6, time: 1_000, summary: null,
diff --git a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
index 8fa1b90d0a..7caa2f8fd9 100644
--- a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
+++ b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts
@@ -13,6 +13,7 @@ import {
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 import { inspectSystemPrompt } from '../../ui-conversation/src/client/contract/system-prompt.ts'
 import { AssistantStreamAccumulator } from '@deepseek-ai/dsh-llm/assistant-stream'
+import { LlmAttemptId } from '@deepseek-ai/dsh-llm/brand'
 import type { StreamChunk } from '@deepseek-ai/dsh-llm'
 import { hasAssistantReplyContent } from '../src/client/contract/assistant-content.ts'
 import { assistantDefinition } from '../src/client/conversation-nodes/assistant.ts'
@@ -941,6 +942,56 @@ describe('built-in conversation node Definitions', () => {
     })
   })
 
+  it('omits first-token metrics after live settlement and after reopening the same history', () => {
+    const attemptId = LlmAttemptId('settled-chat-timing')
+    const starts = [
+      at(1, 'turn/start', { turn: 1 }, { time: 1_000 }),
+      at(2, 'step/start', { turn: 1, step: 1 }, { time: 1_010 }),
+    ]
+    const value = assembler(starts)
+    const chunk = { type: 'text-delta' as const, index: 0, text: 'Answer' }
+    value.append({
+      type: 'transient',
+      event: {
+        type: 'assistant/live-chunk', seq: 2.5, time: 1_030,
+        data: { attemptId, turn: 1, step: 1, chunk },
+      },
+    })
+    value.flush()
+    expect(node(snapshot(value), 'assistant-step')?.data).toMatchObject({
+      status: 'running', time: 1_030, blocks: [{ kind: 'text', text: 'Answer' }],
+    })
+
+    const stream = new AssistantStreamAccumulator()
+    stream.push({ time: 1_030, chunk })
+    const event = at(3, 'assistant/message', {
+      turn: 1, step: 1, message: assistantMessage('settled-timing', 'Answer'),
+      stream: stream.snapshot(), usage: { outputTokens: 10 },
+    }, { surfaceOp: 'append', time: 1_050 }).event
+    if (event.type !== 'assistant/message') throw new Error('expected Assistant settlement')
+    const settlement = { type: 'event' as const, event }
+    value.settleAssistant(attemptId, settlement)
+    const ends = [
+      at(4, 'step/end', { turn: 1, step: 1 }, { time: 1_060 }),
+      at(5, 'turn/end', { turn: 1, reason: { kind: 'completed' } }, { time: 1_070 }),
+    ]
+    for (const end of ends) value.append(end)
+    value.flush()
+
+    const reopened = assembler([...starts, settlement, ...ends])
+    for (const current of [value, reopened]) {
+      const view = snapshot(current)
+      const assistant = (node(view, 'assistant-step')?.data as AssistantChatData).finalNode
+      expect(assistant?.timing).toEqual({
+        stepStartTime: 1_010, firstTokenTime: null, completedTime: 1_050,
+      })
+      const tail = node(view, 'turn-tail')?.data as TurnTailChatData
+      expect(tail.turn).toBe(1)
+      expect(tail.ttftMs).toBeUndefined()
+      expect(tail.tokensPerSecond).toBeUndefined()
+    }
+  })
+
   it('uses live Assistant deltas without replaying settled embedded streams', () => {
     const runningHistory = [
       at(1, 'turn/start', { turn: 1 }),
@@ -1056,16 +1107,9 @@ describe('built-in conversation node Definitions', () => {
     const finalNode = (node(finalizedPacked, 'assistant-step')?.data as AssistantChatData).finalNode
     expect(finalNode).toMatchObject({
       blocks: [{ kind: 'text', text: 'done' }],
-      timing: { firstTokenTime: 1_999 },
+      timing: { firstTokenTime: null },
     })
 
-    const windowed = assembler(finalizedInputs.slice(2), true)
-    const timing = () => (node(snapshot(windowed), 'assistant-step')?.data as AssistantChatData).finalNode?.timing
-    expect(timing()).toMatchObject({ stepStartTime: null, firstTokenTime: 1_999 })
-    windowed.prepend(finalizedInputs.slice(0, 2), false)
-    windowed.flush()
-    expect(timing()).toEqual(finalNode?.timing)
-
     const namedToolHistory = [
       at(40, 'turn/start', { turn: 3 }),
       at(41, 'step/start', { turn: 3, step: 1 }),
@@ -1090,7 +1134,7 @@ describe('built-in conversation node Definitions', () => {
     const namedTool = (node(namedToolPacked, 'assistant-step')?.data as AssistantChatData).finalNode
     expect(namedTool).toMatchObject({
       blocks: [{ kind: 'tool-call', callId: 'call-2', name: 'read', argsRaw: '' }],
-      timing: { firstTokenTime: 4_000 },
+      timing: { firstTokenTime: null },
     })
   })
 
diff --git a/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx b/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
index 0711d89770..79c2ced780 100644
--- a/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
+++ b/packages/client/ui-chat/tests/reasoning-row.client.spec.tsx
@@ -14,24 +14,27 @@ const t = makeTranslate(zh, commonZh)
 const renderMessageImages: AssistantMarkdownProps['renderMessageImages'] = () => null
 
 describe('ReasoningRow', () => {
-  it('collapses when body text arrives and preserves a later manual expansion', () => {
+  it.each([
+    { kind: 'text' as const, text: 'Answer' },
+    { kind: 'tool-call' as const, callId: 'call-1', name: 'read', argsRaw: '{}' },
+  ])('starts collapsed and preserves manual expansion when $kind arrives', (nextBlock) => {
     const reasoning = { kind: 'reasoning' as const, text: 'Inspect the session\nCheck persistence' }
     const view = render(
       <AssistantMarkdown t={t} blocks={[reasoning]} streaming renderMessageImages={renderMessageImages} />,
     )
-    expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('true')
-    view.rerender(
-      <AssistantMarkdown t={t} blocks={[reasoning, { kind: 'text', text: 'Answer' }]}
-        streaming renderMessageImages={renderMessageImages} />,
-    )
     expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('false')
     fireEvent.click(view.getByText('思考'))
     view.rerender(
-      <AssistantMarkdown t={t} blocks={[reasoning, { kind: 'text', text: 'Complete answer' }]}
-        streaming={false} renderMessageImages={renderMessageImages} />,
+      <AssistantMarkdown t={t} blocks={[reasoning, nextBlock]} streaming renderMessageImages={renderMessageImages} />,
+    )
+    expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('true')
+    view.rerender(
+      <AssistantMarkdown t={t} blocks={[reasoning, nextBlock]} streaming={false} renderMessageImages={renderMessageImages} />,
     )
     expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('true')
     expect(view.getByText(/Check persistence/)).toBeTruthy()
+    fireEvent.click(view.getByText('思考'))
+    expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('false')
   })
 
   it('follows the latest streaming line, then restores the settled first line', () => {
@@ -44,8 +47,7 @@ describe('ReasoningRow', () => {
       />,
     )
     expect(view.getByText('运行中')).toBeTruthy()
-    expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('true')
-    fireEvent.click(view.getByText('思考'))
+    expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('false')
     expect(view.getByText('Newest reasoning tokens').parentElement?.getAttribute('data-follow-end'))
       .toBe('true')
 
@@ -69,6 +71,7 @@ describe('ReasoningRow', () => {
       />,
     )
     const settledSummary = view.getByText('Inspect the session')
+    expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('false')
     expect(view.queryByText('运行中')).toBeNull()
     expect(settledSummary.parentElement?.hasAttribute('data-follow-end')).toBe(false)
   })
@@ -84,7 +87,6 @@ describe('ReasoningRow', () => {
     )
     const row = view.getByRole('button')
 
-    fireEvent.click(view.getByText('思考'))
     fireEvent.click(view.getByText('Inspect the session'))
     expect(row.getAttribute('aria-expanded')).toBe('true')
     expect(view.getByText(/Check persistence/)).toBeTruthy()
@@ -114,7 +116,6 @@ describe('ReasoningRow', () => {
       />,
     )
 
-    fireEvent.click(view.getByText('思考'))
     expect(view.getByText('Comparing checkout and merge bases')).toBeTruthy()
     expect(view.queryByText('**Comparing checkout and merge bases**')).toBeNull()
 
@@ -122,7 +123,7 @@ describe('ReasoningRow', () => {
     expect(view.container.querySelector('[class*="thinkBody"]')?.textContent).toBe(text)
   })
 
-  it('opens reasoning-only replies as plain prose and allows manual collapse', () => {
+  it('expanded Think drops the inline summary and renders plain prose, no IN card', () => {
     const view = render(
       <AssistantMarkdown
         t={t}
@@ -131,13 +132,32 @@ describe('ReasoningRow', () => {
         renderMessageImages={renderMessageImages}
       />,
     )
-    expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('true')
+    fireEvent.click(view.getByText('思考'))
     expect(view.getAllByText(/Inspect the session/)).toHaveLength(1)
     expect(view.queryByText('IN')).toBeNull()
     expect(view.container.querySelector('[class*="ioCard"]')).toBeNull()
     expect(view.container.querySelector('[class*="thinkBody"]')).not.toBeNull()
+  })
+
+  it('anchors the sticky-header selector: only an open Think row nests the disclosure row under data-expanded and data-open', () => {
+    const view = render(
+      <AssistantMarkdown
+        t={t}
+        blocks={[
+          { kind: 'reasoning', text: 'Inspect the session\nCheck persistence' },
+          { kind: 'text', text: 'Answer' },
+        ]}
+        streaming={false}
+        renderMessageImages={renderMessageImages}
+      />,
+    )
+    // Collapsed: no `data-open`, so the sticky rule's gate never matches.
+    expect(view.container.querySelector('[data-variant="think"] [data-open]')).toBeNull()
     fireEvent.click(view.getByText('思考'))
-    expect(view.getByRole('button').getAttribute('aria-expanded')).toBe('false')
-    expect(view.queryByText(/Check persistence/)).toBeNull()
+    expect(
+      view.container.querySelector(
+        '[data-variant="think"][data-expanded] [data-open] [data-disclosure-row]',
+      ),
+    ).not.toBeNull()
   })
 })
diff --git a/packages/client/ui-chat/tests/sticky-header-styles.client.spec.ts b/packages/client/ui-chat/tests/sticky-header-styles.client.spec.ts
new file mode 100644
index 0000000000..42f399be9b
--- /dev/null
+++ b/packages/client/ui-chat/tests/sticky-header-styles.client.spec.ts
@@ -0,0 +1,70 @@
+/**
+ * The two pinned collapsible headers as CSS text. jsdom has no layout, so the
+ * rendering specs pin which DOM anchors the selectors key on but cannot show
+ * whether the pinning declarations resolve; these read the declarations the
+ * pinning and the stacking rank depend on.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const read = (name: string): string =>
+  readFileSync(fileURLToPath(new URL(`../src/client/chat/${name}`, import.meta.url)), 'utf8')
+
+function declarationsFrom(source: string, selector: string): string[] {
+  const declarationText = source.replace(/\/\*[\s\S]*?\*\//g, ' ')
+  const rule = new RegExp(`(?:^|[{}])\\s*${selector.replace(/[.[\]():*+^$\\]/g, '\\$&')}\\s*\\{([^{}]*)\\}`).exec(declarationText)
+  if (rule === null) throw new Error(`no \`${selector}\` rule`)
+  return (rule[1] ?? '').split(';').map(part => part.trim()).filter(Boolean)
+}
+
+describe('pinned collapsible headers', () => {
+  it('pins an open Think header to the scrollport top and masks the prose under it', () => {
+    expect(
+      declarationsFrom(read('ReasoningRow.module.css'), '.root[data-expanded] [data-open] [data-disclosure-row]'),
+    ).toEqual(expect.arrayContaining([
+      'position: sticky',
+      'top: 0',
+      'z-index: 1',
+      'background: var(--dsw-alias-bg-base)',
+    ]))
+  })
+
+  it('ranks the pinned compaction header above the code-block banner', () => {
+    expect(
+      declarationsFrom(read('MessageItem.module.css'), '.compactionRow:has(.compactionBody) .compactionButton'),
+    ).toEqual(expect.arrayContaining([
+      'position: sticky',
+      'top: 0',
+      // CodeBlock.module.css pins its banner at 6; a lower rank here would let
+      // a summary's fenced code block cover the toggle.
+      'z-index: 7',
+      // The opaque fill masks the prose only if the box has no rounded corners
+      // for it to show through.
+      'border-radius: 0',
+      'background: var(--dsw-alias-bg-base)',
+    ]))
+  })
+
+  it('holds a summary code banner below the pinned header band, on the toggle\'s own measurement', () => {
+    const css = read('MessageItem.module.css')
+    // One home for the band height: the toggle's height and the offset that
+    // keeps a code banner clear of it must never drift apart, and sticky gives
+    // no error when they do.
+    expect(declarationsFrom(css, '.compactionRow')).toEqual(expect.arrayContaining([
+      '--dsh-compaction-header-height: calc(24px + var(--dsh-content-font-delta, 0px))',
+    ]))
+    expect(declarationsFrom(css, '.compactionButton')).toEqual(expect.arrayContaining([
+      'height: var(--dsh-compaction-header-height)',
+    ]))
+    expect(declarationsFrom(css, '.compactionBody :has(> [data-code-block-banner])')).toEqual(expect.arrayContaining([
+      'top: var(--dsh-compaction-header-height)',
+    ]))
+  })
+
+  it('keeps the pinned compaction header opaque under hover', () => {
+    expect(
+      declarationsFrom(read('MessageItem.module.css'), '.compactionRow:has(.compactionBody) .compactionButton:hover'),
+    ).toEqual(expect.arrayContaining(['background: var(--dsw-alias-interactive-bg-hover-solid)']))
+  })
+})
diff --git a/packages/client/ui-commands/src/client/presentation.ts b/packages/client/ui-commands/src/client/presentation.ts
index 49ffb3da4b..0bcee9cfc9 100644
--- a/packages/client/ui-commands/src/client/presentation.ts
+++ b/packages/client/ui-commands/src/client/presentation.ts
@@ -2,7 +2,7 @@
 import type { ComponentType } from 'react'
 import type { InputTriggerCandidate } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
 import {
-  IconCompactOutline16, IconDownloadOutline16, IconGoalOutline16, IconPlanOutline14, IconSendOutline16,
+  IconCompactOutline16, IconDownloadOutline16, IconGoalOutline16, IconPaperPlaneOutline14, IconPlanOutline14,
   IconShieldOutline16,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { IconProps } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -41,7 +41,7 @@ function hostFace(name: BuiltinCommandName, icon: ComponentType<IconProps>): rea
 const HOST_FACES: ReadonlyMap<BuiltinCommandName, HostFace> = new Map([
   hostFace('goal', IconGoalOutline16),
   hostFace('plan', IconPlanOutline14),
-  hostFace('feedback', IconSendOutline16),
+  hostFace('feedback', IconPaperPlaneOutline14),
   hostFace('compact', IconCompactOutline16),
   hostFace('permission', IconShieldOutline16),
   hostFace('export', IconDownloadOutline16),
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 71555a9632..1f20199505 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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 packages/client/ui-conversation/README.md
-README.md: 8d68dfdb61943c7c45b38d9244134edecc86a593
-README.zh.md: b1d548ba8fc9276a6864548802a45796e74c0c7a
+README.md: 5b94862d830d27ae02e60832294c7595537b47c0
+README.zh.md: 6d7bb72ba582f90356f4bc08a78b2cdfdf211db7
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 8d68dfdb61..5b94862d83 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -38,6 +38,8 @@ Target packages declaration-merge their snapshot and Location data maps, then re
 
 The composer registers the File command action and owns its label, availability, and native file-dialog callback. Menu availability and invocation both consult the mounted composer's current attachment-intake policy. Unmounting or locking the composer disables that action; disposing the plugin removes its registration. The callback binding stays inside the input module.
 
+`SessionInputShell` owns one Lexical editor per Session through its private [DraftEditorRuntime](src/client/input/editor/runtime.ts), while retaining submission, attachment selection, and recovery decisions. [DraftEditor](src/client/input/editor/DraftEditor.tsx) renders the borrowed editor; InputBar retains its Hooks and refs and installs DOM behavior through [view-binding](src/client/input/editor/view-binding.ts). Editor-facing types live in [draft-editor.ts](src/client/contract/draft-editor.ts), with shared input and submission types in [input.ts](src/client/contract/input.ts). This separation does not support simultaneous editable roots for one Session; [the two-stage isolation proposal](../../../.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.md) defines the remaining work.
+
 Claimed commands retain their identity and highlight when only their arguments and trailing separator are deleted; editing the command name releases the claim. The same rules apply to every command and locale, including `/goal`, `/目标`, `/plan`, and `/计划`. Command hints and ordinary placeholders remain hidden throughout IME composition and reappear only after the editor commits the final text and the corresponding input is empty.
 
 Workspace selection uses `uiWorkspace.openWorkspace` to prepare the target and commit navigation. Draft text and attachments move in its synchronous preparation callback only while that request is current; later navigation or owner disposal leaves the original draft intact.
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index b1d548ba8f..6d7bb72ba5 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -38,6 +38,8 @@ target package 通过 declaration merge 扩展 snapshot 与 Location data map，
 
 输入框注册「文件」命令动作，负责其标题、可用性和原生文件选择器回调。菜单可用性与实际调用都读取已挂载输入框当前的附件接收策略。输入框卸载或锁定后该动作不可用，插件 dispose（资源释放）时移除注册。回调绑定留在输入模块内部。
 
+`SessionInputShell` 通过私有 [DraftEditorRuntime](src/client/input/editor/runtime.ts) 为每个 Session 持有一个 Lexical editor，同时保留提交、附件选择和恢复决策。[DraftEditor](src/client/input/editor/DraftEditor.tsx) 呈现借用的 editor；InputBar 保留钩子与 refs，并通过 [view-binding](src/client/input/editor/view-binding.ts) 安装 DOM 行为。编辑器类型位于 [draft-editor.ts](src/client/contract/draft-editor.ts)，共享输入和提交类型位于 [input.ts](src/client/contract/input.ts)。这一拆分不支持同一 Session 同时挂载多个可编辑 root；[两阶段隔离提案](../../../.agents/notes/proposed/architecture/2026-09-14-composer-model-and-draft-editor.zh.md) 定义剩余工作。
+
 已认领的命令在仅删除参数和末尾分隔空格时保留身份与高亮，改动命令名才会释放认领。所有命令和语言使用相同规则，包括 `/goal`、`/目标`、`/plan` 和 `/计划`。输入法组合输入期间，命令提示和普通占位文字持续隐藏，直到编辑器提交最终文字且对应输入为空时才重新显示。
 
 工作区选择使用 `uiWorkspace.openWorkspace` 准备目标并提交导航。草稿文字和附件仅在该请求仍为当前请求时，通过它的同步准备回调搬移；后续导航或所有者释放会保留原草稿。
diff --git a/packages/client/ui-conversation/src/client/contract/draft-editor.ts b/packages/client/ui-conversation/src/client/contract/draft-editor.ts
new file mode 100644
index 0000000000..f4dc49246f
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/contract/draft-editor.ts
@@ -0,0 +1,105 @@
+/** Editor-facing ranges, reference projections, and the composer keyboard interface. */
+import type { LexicalEditor } from 'lexical'
+import type { InputState } from './input.ts'
+import type { InputSubmitMode } from './composer-submission.ts'
+
+/** Pick-time draft span guarded by the input revision. */
+export interface TokenSpan {
+  readonly start: number
+  readonly end: number
+  readonly draftRev: number
+}
+
+/** Structured reference inserted by an input-trigger source. */
+export interface ReferenceInsert {
+  readonly source: string
+  readonly ref: string
+  readonly label: string
+  readonly appearance?: 'session' | 'file' | 'folder'
+  readonly clipboardText: string
+}
+
+/** Keyboard keys intercepted by an open trigger menu. */
+export type ArbitrateKey = 'up' | 'down' | 'enter' | 'escape' | 'tab'
+
+/** Trigger-menu keyboard routing result. */
+export type ArbitrateOutcome = 'consumed' | 'pick-highlighted' | 'pass'
+
+/**
+ * The InputBar-exclusive keyboard/DOM command face: synchronous
+ * returns and event-handler semantics that must not enter the public provide
+ * channel. Handed to the composer-bar entry through its own inject —
+ * package-internal, never across a plugin boundary. The session shell
+ * satisfies it structurally. Text editing itself rides the shell's Lexical
+ * editor (exposed here for the contenteditable binding); the members below
+ * are the submit-plane and trigger-pipeline verbs the editor does not own.
+ */
+export interface ComposerKeyboard {
+  /** Live machine state for event-handler reads (render reads go through useInput). */
+  readonly snapshot: InputState
+  /** The shell-owned Lexical editor the composer binds its contenteditable to. */
+  readonly editor: LexicalEditor
+  /** Submit with an explicit delivery mode resolved by the submission policy (Enter gestures and the primary Send button). */
+  submit(mode: InputSubmitMode): void
+  /**
+   * Steer every still-pending queued message into the running turn (the
+   * empty-draft accelerated-Enter gesture; the queue dock's per-row steer
+   * button is the same operation applied to the whole queue).
+   */
+  steerQueue(): void
+  /** Insert pasted plain text over the current editor selection (reference-placeholder-sanitized). */
+  paste(text: string): void
+  /**
+   * The live selection as a detect-coordinate span (menu-launcher synthetic
+   * hits replace it on pick); an absent selection answers a collapsed span at
+   * the document end.
+   */
+  caretSpan(): EditSelection
+  /** Keyboard arbitration while the menu is open ('pass' when no pipeline). */
+  arbitrate(key: ArbitrateKey, composing: boolean): ArbitrateOutcome
+  /** Space adjudication; true = the input applied a claim — caller preventDefaults. */
+  space(): boolean
+  /** Dismiss the popupSelect shell (any interaction outside the box). */
+  dismissPopup(): void
+  /**
+   * Bind the mounted composer's file action and live intake availability.
+   * @param picker - availability query and native file-dialog opener.
+   * @returns the unbind disposer.
+   */
+  bindFilePicker(picker: { available(): boolean; open(): void }): () => void
+}
+
+/** Half-open [start, end) range/selection in detect-projection coordinates. */
+export interface EditSelection {
+  readonly start: number
+  readonly end: number
+}
+
+/**
+ * One reference occurrence projected from the editor's chip nodes, in
+ * clipboard-text coordinates. Identity is occurrenceId — a stable per-shell
+ * assignment per chip NodeKey, so same-named references stay independently
+ * addressable and survive undo. label/appearance/clipboardText are the
+ * owner's insert-time projections cached on the node (invalid flips instead
+ * of dropping the occurrence).
+ */
+export interface Occurrence {
+  /** Shell-assigned stable identity (monotonic per shell, keyed by NodeKey). */
+  readonly occurrenceId: number
+  /** Owning source name (serializer routing key). */
+  readonly source: string
+  /** Owner-scoped reference id. */
+  readonly ref: string
+  /** Offset in the clipboard-text projection. */
+  readonly offset: number
+  /** Length in the clipboard-text projection; the occurrence occupies exactly [offset, offset+length). */
+  readonly length: number
+  /** Inline display label (insert-time cache). */
+  readonly label: string
+  /** Optional domain glyph (insert-time cache). */
+  readonly appearance?: ReferenceInsert['appearance']
+  /** Clipboard / persistence projection, e.g. `/name` (insert-time cache, never the model form). */
+  readonly clipboardText: string
+  /** Owner-resolution failure flag: the chip renders the failure treatment. */
+  readonly invalid?: boolean
+}
diff --git a/packages/client/ui-conversation/src/client/contract/input.ts b/packages/client/ui-conversation/src/client/contract/input.ts
index e70136736e..c6820f08a0 100644
--- a/packages/client/ui-conversation/src/client/contract/input.ts
+++ b/packages/client/ui-conversation/src/client/contract/input.ts
@@ -9,17 +9,10 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type { ObservableSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import type { Branded } from '@deepseek-ai/dsh-brand'
-import type { LexicalEditor } from 'lexical'
+import type { ArbitrateKey, ArbitrateOutcome, Occurrence, ReferenceInsert, TokenSpan } from './draft-editor.ts'
 import type { QueueRow } from './queue.ts'
 import type { InputSubmitMode } from './composer-submission.ts'
 
-/** Pick-time draft span guarded by the input revision. */
-export interface TokenSpan {
-  readonly start: number
-  readonly end: number
-  readonly draftRev: number
-}
-
 /** Attachment payload passed to a claimed command submission. */
 export type SubmitAttachment =
   | {
@@ -59,15 +52,6 @@ export interface CommandClaim {
   submit(args: string, actx: Context, attachments: readonly SubmitAttachment[]): Promise<SubmitOutcome>
 }
 
-/** Structured reference inserted by an input-trigger source. */
-export interface ReferenceInsert {
-  readonly source: string
-  readonly ref: string
-  readonly label: string
-  readonly appearance?: 'session' | 'file' | 'folder'
-  readonly clipboardText: string
-}
-
 /** Result of trigger-source adjudication. */
 export type PickOutcome =
   | { readonly claim: CommandClaim }
@@ -76,12 +60,6 @@ export type PickOutcome =
   | 'handled'
   | undefined
 
-/** Keyboard keys intercepted by an open trigger menu. */
-export type ArbitrateKey = 'up' | 'down' | 'enter' | 'escape' | 'tab'
-
-/** Trigger-menu keyboard routing result. */
-export type ArbitrateOutcome = 'consumed' | 'pick-highlighted' | 'pass'
-
 /** Scoped request to enter command mode. */
 export interface BeginCommandRequest {
   readonly claim: CommandClaim
@@ -255,91 +233,12 @@ export interface InputNotice {
   readonly seq: number
 }
 
-/**
- * The InputBar-exclusive keyboard/DOM command face: synchronous
- * returns and event-handler semantics that must not enter the public provide
- * channel. Handed to the composer-bar entry through its own inject —
- * package-internal, never across a plugin boundary. The session shell
- * satisfies it structurally. Text editing itself rides the shell's Lexical
- * editor (exposed here for the contenteditable binding); the members below
- * are the submit-plane and trigger-pipeline verbs the editor does not own.
- */
-export interface ComposerKeyboard {
-  /** Live machine state for event-handler reads (render reads go through useInput). */
-  readonly snapshot: InputState
-  /** The shell-owned Lexical editor the composer binds its contenteditable to. */
-  readonly editor: LexicalEditor
-  /** Submit with an explicit delivery mode resolved by the submission policy (Enter gestures and the primary Send button). */
-  submit(mode: InputSubmitMode): void
-  /**
-   * Steer every still-pending queued message into the running turn (the
-   * empty-draft accelerated-Enter gesture; the queue dock's per-row steer
-   * button is the same operation applied to the whole queue).
-   */
-  steerQueue(): void
-  /** Insert pasted plain text over the current editor selection (reference-placeholder-sanitized). */
-  paste(text: string): void
-  /**
-   * The live selection as a detect-coordinate span (menu-launcher synthetic
-   * hits replace it on pick); an absent selection answers a collapsed span at
-   * the document end.
-   */
-  caretSpan(): EditSelection
-  /** Keyboard arbitration while the menu is open ('pass' when no pipeline). */
-  arbitrate(key: ArbitrateKey, composing: boolean): ArbitrateOutcome
-  /** Space adjudication; true = the input applied a claim — caller preventDefaults. */
-  space(): boolean
-  /** Dismiss the popupSelect shell (any interaction outside the box). */
-  dismissPopup(): void
-  /**
-   * Bind the mounted composer's file action and live intake availability.
-   * @param picker - availability query and native file-dialog opener.
-   * @returns the unbind disposer.
-   */
-  bindFilePicker(picker: { available(): boolean; open(): void }): () => void
-}
-
 /** One independently addressable row projected from the transient queue snapshot. */
 export type QueuedMessage = QueueRow
 
 /** Guard union of the scoped consume-token event, checked by the shell. */
 export type ConsumeTokenGuard = ConsumeTokenRequest['guard']
 
-/** Half-open [start, end) range/selection in detect-projection coordinates. */
-export interface EditSelection {
-  readonly start: number
-  readonly end: number
-}
-
-/**
- * One reference occurrence projected from the editor's chip nodes, in
- * clipboard-text coordinates. Identity is occurrenceId — a stable per-shell
- * assignment per chip NodeKey, so same-named references stay independently
- * addressable and survive undo. label/appearance/clipboardText are the
- * owner's insert-time projections cached on the node (invalid flips instead
- * of dropping the occurrence).
- */
-export interface Occurrence {
-  /** Shell-assigned stable identity (monotonic per shell, keyed by NodeKey). */
-  readonly occurrenceId: number
-  /** Owning source name (serializer routing key). */
-  readonly source: string
-  /** Owner-scoped reference id. */
-  readonly ref: string
-  /** Offset in the clipboard-text projection. */
-  readonly offset: number
-  /** Length in the clipboard-text projection; the occurrence occupies exactly [offset, offset+length). */
-  readonly length: number
-  /** Inline display label (insert-time cache). */
-  readonly label: string
-  /** Optional domain glyph (insert-time cache). */
-  readonly appearance?: ReferenceInsert['appearance']
-  /** Clipboard / persistence projection, e.g. `/name` (insert-time cache, never the model form). */
-  readonly clipboardText: string
-  /** Owner-resolution failure flag: the chip renders the failure treatment. */
-  readonly invalid?: boolean
-}
-
 /** Published input state (the currency; per-session). */
 export interface InputState {
   /** Clipboard-text projection of the editor document (chips expanded to their clipboard form). */
diff --git a/packages/client/ui-conversation/src/client/contract/slots.ts b/packages/client/ui-conversation/src/client/contract/slots.ts
index a131b63a0d..20fd568256 100644
--- a/packages/client/ui-conversation/src/client/contract/slots.ts
+++ b/packages/client/ui-conversation/src/client/contract/slots.ts
@@ -15,9 +15,8 @@ import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types'
 import type { ComposerBlock } from './composer-blocks.ts'
-import type {
-  ComposerKeyboard, DraftAttachmentId, EditSelection, InputActions, InputNotice, InputState,
-} from './input.ts'
+import type { DraftAttachmentId, InputActions, InputNotice, InputState } from './input.ts'
+import type { ComposerKeyboard, EditSelection } from './draft-editor.ts'
 import type { createConversationStore } from '../stores.ts'
 import type { BusyEnterBehavior } from './composer-submission.ts'
 import type { ConversationSnapshot } from './snapshot.ts'
diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts
index 2b94139936..5f765b9ada 100644
--- a/packages/client/ui-conversation/src/client/index.ts
+++ b/packages/client/ui-conversation/src/client/index.ts
@@ -62,11 +62,11 @@ export type {
   UseConversationViews,
 } from './contract/slots.ts'
 export type {
-  ArbitrateKey, ArbitrateOutcome, BeginCommandRequest, CommandClaim, ConsumeTokenRequest,
-  DraftAttachmentId, InputActions, InputState, InsertReferenceRequest, InsertTextRequest,
-  PickOutcome, ReferenceInsert, SessionInput, SessionInputResolver, SubmitAttachment,
-  SubmitOutcome, TokenSpan,
+  BeginCommandRequest, CommandClaim, ConsumeTokenRequest, DraftAttachmentId, InputActions,
+  InputState, InsertReferenceRequest, InsertTextRequest, PickOutcome, SessionInput,
+  SessionInputResolver, SubmitAttachment, SubmitOutcome,
 } from './contract/input.ts'
+export type { ArbitrateKey, ArbitrateOutcome, ReferenceInsert, TokenSpan } from './contract/draft-editor.ts'
 export type { ComposerBlock, ComposerBlocks } from './contract/composer-blocks.ts'
 
 declare module '@deepseek-ai/cordis' {
diff --git a/packages/client/ui-conversation/src/client/input/editor/DraftEditor.tsx b/packages/client/ui-conversation/src/client/input/editor/DraftEditor.tsx
new file mode 100644
index 0000000000..d03ff6232c
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/input/editor/DraftEditor.tsx
@@ -0,0 +1,63 @@
+/** Stateless text-area presentation over the InputBar's borrowed editor. */
+import type { CSSProperties, KeyboardEventHandler, ReactNode, RefObject } from 'react'
+import type { LexicalEditor } from 'lexical'
+import clsx from 'clsx'
+import type { InputState } from '../../contract/input.ts'
+import { ComposerContentEditable } from './ComposerContentEditable.tsx'
+import { DecoratorPortals } from './DecoratorPortals.tsx'
+
+/** Text-area values and the scrollport reference retained by InputBar. */
+export interface DraftEditorProps {
+  readonly classNames: Readonly<Record<string, string>>
+  readonly editor: LexicalEditor | null
+  readonly scrollRef: RefObject<HTMLDivElement>
+  readonly editable: boolean
+  readonly editorDisabled: boolean
+  readonly phase: InputState['phase'] | 'inert'
+  readonly placeholderText: string
+  readonly ariaLabel: string
+  readonly workspaceTrigger: boolean
+  readonly workspacePickerOpen: boolean
+  readonly onWorkspaceKeyDown: KeyboardEventHandler<HTMLDivElement>
+  readonly hint: string | null
+  readonly showPlaceholder: boolean
+}
+
+/**
+ * Render the existing scrollport, editable surface, placeholder, and chip portals.
+ * @param props - borrowed editor and presentation values; this component owns no Hooks.
+ * @returns the existing text-area DOM without an additional wrapper.
+ */
+export function DraftEditor({
+  classNames: css, editor, scrollRef, editable, editorDisabled, phase, placeholderText, ariaLabel,
+  workspaceTrigger, workspacePickerOpen, onWorkspaceKeyDown, hint, showPlaceholder,
+}: DraftEditorProps): ReactNode {
+  return (
+    <div ref={scrollRef} className={css.scroll} data-input-scroll>
+      <div className={css.grow}>
+        <ComposerContentEditable
+          editor={workspaceTrigger ? null : editor}
+          editable={editable}
+          className={clsx(css.input, editorDisabled && css.inputDisabled)}
+          data-phase={phase}
+          aria-disabled={editorDisabled || undefined}
+          data-placeholder={placeholderText}
+          // The placeholder was the textarea's accessible name; a div's
+          // data attribute is not, so the label restores it.
+          aria-label={ariaLabel}
+          aria-haspopup={workspaceTrigger ? 'menu' : undefined}
+          aria-expanded={workspaceTrigger ? workspacePickerOpen : undefined}
+          tabIndex={workspaceTrigger ? 0 : undefined}
+          onKeyDown={workspaceTrigger ? onWorkspaceKeyDown : undefined}
+          style={hint === null ? undefined : { '--dsh-composer-hint': JSON.stringify(hint) } as CSSProperties}
+        />
+        {showPlaceholder && (
+          <div aria-hidden className={css.placeholder} data-composer-placeholder>
+            {placeholderText}
+          </div>
+        )}
+        <DecoratorPortals editor={workspaceTrigger ? null : editor} />
+      </div>
+    </div>
+  )
+}
diff --git a/packages/client/ui-conversation/src/client/input/editor/chip-node.tsx b/packages/client/ui-conversation/src/client/input/editor/chip-node.tsx
index 16de06e878..b2abf13158 100644
--- a/packages/client/ui-conversation/src/client/input/editor/chip-node.tsx
+++ b/packages/client/ui-conversation/src/client/input/editor/chip-node.tsx
@@ -12,7 +12,7 @@ import type {
   EditorConfig, LexicalNode, NodeKey, SerializedLexicalNode, Spread,
 } from 'lexical'
 import { DecoratorNode } from 'lexical'
-import type { ReferenceInsert } from '../../contract/input.ts'
+import type { ReferenceInsert } from '../../contract/draft-editor.ts'
 import { ReferenceChip } from './ReferenceChip.tsx'
 
 /** JSON form of one chip (Lexical node serialization contract). */
diff --git a/packages/client/ui-conversation/src/client/input/editor/keymap.ts b/packages/client/ui-conversation/src/client/input/editor/keymap.ts
index f11592ba5a..354de6aba7 100644
--- a/packages/client/ui-conversation/src/client/input/editor/keymap.ts
+++ b/packages/client/ui-conversation/src/client/input/editor/keymap.ts
@@ -20,7 +20,7 @@ import {
   KEY_ESCAPE_COMMAND, KEY_SPACE_COMMAND, KEY_TAB_COMMAND, PASTE_COMMAND,
 } from 'lexical'
 import { mergeRegister } from '@lexical/utils'
-import type { ArbitrateKey, ArbitrateOutcome } from '../../contract/input.ts'
+import type { ArbitrateKey, ArbitrateOutcome } from '../../contract/draft-editor.ts'
 
 /** The bar-supplied behavior behind each intercepted gesture. */
 export interface ComposerKeymapHandlers {
diff --git a/packages/client/ui-conversation/src/client/input/editor/projection.ts b/packages/client/ui-conversation/src/client/input/editor/projection.ts
index 1a25c95884..f48a5b595d 100644
--- a/packages/client/ui-conversation/src/client/input/editor/projection.ts
+++ b/packages/client/ui-conversation/src/client/input/editor/projection.ts
@@ -11,7 +11,7 @@ import type { ElementNode, LexicalNode, NodeKey, Point } from 'lexical'
 import {
   $getRoot, $getSelection, $isElementNode, $isLineBreakNode, $isRangeSelection, $isTextNode,
 } from 'lexical'
-import type { Occurrence } from '../../contract/input.ts'
+import type { Occurrence } from '../../contract/draft-editor.ts'
 import { $isReferenceChipNode } from './chip-node.tsx'
 
 /** The detect-projection stand-in for one chip (object replacement character). */
diff --git a/packages/client/ui-conversation/src/client/input/editor/reference-activation.ts b/packages/client/ui-conversation/src/client/input/editor/reference-activation.ts
index c58cef382a..d1d377e331 100644
--- a/packages/client/ui-conversation/src/client/input/editor/reference-activation.ts
+++ b/packages/client/ui-conversation/src/client/input/editor/reference-activation.ts
@@ -4,7 +4,7 @@ import {
   CLICK_COMMAND, COMMAND_PRIORITY_LOW,
 } from 'lexical'
 import type { LexicalEditor } from 'lexical'
-import type { ReferenceInsert } from '../../contract/input.ts'
+import type { ReferenceInsert } from '../../contract/draft-editor.ts'
 import { $isReferenceChipNode } from './chip-node.tsx'
 import { TextRefNode } from './text-ref.ts'
 
diff --git a/packages/client/ui-conversation/src/client/input/editor/runtime.ts b/packages/client/ui-conversation/src/client/input/editor/runtime.ts
new file mode 100644
index 0000000000..2054624342
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/input/editor/runtime.ts
@@ -0,0 +1,299 @@
+/** The Composer model's private Lexical editor, projections, and node operations. */
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store'
+import type { LexicalEditor, NodeKey } from 'lexical'
+import {
+  $addUpdateTag, $createParagraphNode, $createTextNode, $getRoot, $getSelection, $isRangeSelection,
+  CLEAR_HISTORY_COMMAND, createEditor, HISTORY_MERGE_TAG, PASTE_TAG,
+} from 'lexical'
+import { registerPlainText } from '@lexical/plain-text'
+import { createEmptyHistoryState, registerHistory } from '@lexical/history'
+import { mergeRegister } from '@lexical/utils'
+import type { Occurrence, ReferenceInsert } from '../../contract/draft-editor.ts'
+import { registerReferenceActivation } from './reference-activation.ts'
+import { ReferenceChipNode, $createReferenceChipNode } from './chip-node.tsx'
+import { refreshClaimDecoration, registerClaimDecoration } from './claim-decor.ts'
+import { registerTextRefDecoration, rescanTextRefs, TextRefNode } from './text-ref.ts'
+import type { EditorProjection } from './projection.ts'
+import { $composerLayout, $projectComposer, detectOffsetOfClipboardOffset } from './projection.ts'
+import { $replaceDetectSpanWithNodes, $replaceDetectSpanWithText } from './span-map.ts'
+import type { DetectSpan } from './span-map.ts'
+
+type Lexicon = ReadonlyMap<'/' | '@', readonly string[]>
+
+/** Model callbacks read at the same editor registration and update points. */
+interface DraftEditorRuntimeDeps {
+  readonly onUpdate: () => void
+  readonly openReference: (source: string | undefined, reference: Pick<ReferenceInsert, 'ref' | 'appearance'>) => boolean
+  readonly activeClaimToken: () => string | null
+  readonly lexicon: () => Lexicon
+  readonly resolveLexicon: () => ObservableSnapshot<Lexicon> | undefined
+}
+
+/**
+ * Detect-projection and legacy reference placeholders stripped from every
+ * external text entering the document (paste, persisted-draft seed): a chip
+ * is the only legitimate source of U+FFFC in the detect projection, so a
+ * literal one in text would forge chip positions.
+ */
+const REFERENCE_PLACEHOLDER_RE = /[\uE100-\uE11D\uFFFC]/gu
+
+/** Undo merge window for contiguous typing, in ms (the old machine's mergeWindowMs). */
+const HISTORY_MERGE_DELAY_MS = 1000
+
+/** One model-owned editor; registration and disposal remain with its model. */
+export class DraftEditorRuntime {
+  /** The editor bound by the Composer's contenteditable host. */
+  readonly editor: LexicalEditor
+  private projected: EditorProjection = { detectText: '', clipboardText: '', occurrences: [], selection: null, caret: null }
+  /** Stable occurrence ids per chip NodeKey (undo restores keys, so ids survive it too). */
+  private readonly occurrenceIds = new Map<NodeKey, number>()
+  private occurrenceSeq = 0
+  /** Live lexicon subscription disposer; undefined until the controller resolves. */
+  private lexiconOff: (() => void) | undefined
+
+  /** @param deps - model callbacks used by editor listeners and transforms. */
+  constructor(private readonly deps: DraftEditorRuntimeDeps) {
+    this.editor = createEditor({
+      namespace: 'dsh-composer',
+      nodes: [ReferenceChipNode, TextRefNode],
+      onError: (error) => { throw error },
+    })
+  }
+
+  /**
+   * Install editor behavior after the model holds this runtime.
+   * @returns unregister callback that also detaches the editor root.
+   */
+  register(): () => void {
+    const unregister = mergeRegister(
+      registerPlainText(this.editor),
+      registerReferenceActivation(this.editor, (source, reference) =>
+        this.deps.openReference(source, reference)),
+      registerHistory(this.editor, createEmptyHistoryState(), HISTORY_MERGE_DELAY_MS),
+      this.editor.registerUpdateListener(() => { this.deps.onUpdate() }),
+      registerClaimDecoration(this.editor, () => this.deps.activeClaimToken()),
+      registerTextRefDecoration(this.editor, () => this.deps.lexicon(), () => this.deps.activeClaimToken()),
+      () => { this.lexiconOff?.() },
+    )
+    return () => {
+      unregister()
+      this.editor.setRootElement(null)
+    }
+  }
+
+  /** The latest committed editor projection. */
+  get projection(): EditorProjection {
+    return this.projected
+  }
+
+  /**
+   * Run one editor edit whose result is observable on return. At the top
+   * level this is a discrete update. Inside this editor's own update —
+   * command handlers land here synchronously (space/enter picks, paste) —
+   * $-functions are already legal, and wrapping them in update() would DEFER
+   * them past the synchronous bail answer (and a nested discrete throws);
+   * the body runs directly and the outer update commits it.
+   * @param fn - the $-edit body.
+   */
+  private applyEdit(fn: () => void, tag?: string): void {
+    if (this.editor._updating) {
+      // Nested application joins the enclosing update (the PASTE_COMMAND
+      // dispatch path always lands here), so the tag attaches to that update.
+      if (tag !== undefined) $addUpdateTag(tag)
+      fn()
+      return
+    }
+    this.editor.update(fn, { discrete: true, ...(tag === undefined ? {} : { tag }) })
+  }
+
+  /**
+   * Subscribe the text-ref re-scan to the controller's lexicon once the
+   * controller resolves. The deps thunk cannot resolve at construction (the
+   * shell is created inside the sessions provide materialization), so the
+   * first interactive updates retry until it can.
+   */
+  private ensureLexiconSubscription(): void {
+    if (this.lexiconOff !== undefined) return
+    const lexicon = this.deps.resolveLexicon()
+    if (lexicon === undefined) return
+    this.lexiconOff = lexicon.subscribe(() => { rescanTextRefs(this.editor) })
+  }
+
+  /**
+   * Re-project inside the existing editor update callback.
+   * @returns the projection preceding this read.
+   */
+  refreshProjection(): EditorProjection {
+    this.ensureLexiconSubscription()
+    const prev = this.projected
+    this.projected = this.editor.getEditorState().read(() =>
+      $projectComposer(key => this.occurrenceIdOf(key)))
+    return prev
+  }
+
+  private occurrenceIdOf(key: NodeKey): number {
+    const existing = this.occurrenceIds.get(key)
+    if (existing !== undefined) return existing
+    this.occurrenceSeq += 1
+    this.occurrenceIds.set(key, this.occurrenceSeq)
+    return this.occurrenceSeq
+  }
+
+  /**
+   * Replace the whole draft (persisted-draft seed and programmatic writes).
+   * Placeholder-sanitized; newlines split paragraphs; the caret lands at the
+   * end. Merged into history so a seed is not an undoable step of its own.
+   * @param text - the full next draft.
+   */
+  setDraft(text: string): void {
+    const clean = text.replace(REFERENCE_PLACEHOLDER_RE, '')
+    if (clean === this.projection.clipboardText) return
+    this.editor.update(() => {
+      const root = $getRoot()
+      root.clear()
+      for (const line of clean.split('\n')) {
+        const paragraph = $createParagraphNode()
+        if (line !== '') paragraph.append($createTextNode(line))
+        root.append(paragraph)
+      }
+      root.selectEnd()
+    }, { discrete: true, tag: HISTORY_MERGE_TAG })
+  }
+
+  /**
+   * Insert pasted plain text over the current editor selection
+   * (placeholder-sanitized). The paste event's own default is suppressed by
+   * the caller; PASTE_TAG makes the paste its own history boundary, so one
+   * undo never removes both the paste and typing inside the merge window.
+   * @param text - pasted plain text.
+   */
+  paste(text: string): void {
+    const clean = text.replace(REFERENCE_PLACEHOLDER_RE, '')
+    if (clean === '') return
+    this.applyEdit(() => {
+      const selection = $getSelection()
+      if ($isRangeSelection(selection)) {
+        selection.insertText(clean)
+        return
+      }
+      // No selection yet (never-focused surface): land at the document end,
+      // growing the first paragraph when the tree is empty.
+      const root = $getRoot()
+      if (root.getChildrenSize() === 0) root.append($createParagraphNode())
+      root.selectEnd().insertText(clean)
+    }, PASTE_TAG)
+  }
+
+  /**
+   * The live selection as a detect-coordinate span (menu-launcher synthetic
+   * hits replace it on pick); an absent selection answers a collapsed span at
+   * the document end.
+   * @returns the ordered [start, end) span in detect coordinates.
+   */
+  caretSpan(): { start: number; end: number } {
+    if (this.projection.selection !== null) return this.projection.selection
+    const at = this.projection.detectText.length
+    return { start: at, end: at }
+  }
+
+  /**
+   * Replace a mapped span without applying the model's phase or revision guards.
+   * @param span - detect-coordinate range.
+   * @param text - inserted text.
+   * @returns whether the range mapped and the edit applied.
+   */
+  replaceText(span: DetectSpan, text: string): boolean {
+    let applied = false
+    this.applyEdit(() => {
+      applied = $replaceDetectSpanWithText(span, text)
+    })
+    return applied
+  }
+
+  /**
+   * Insert a reference chip with the existing trailing-space rule.
+   * @param span - detect-coordinate range.
+   * @param ref - reference fields.
+   * @param tail - the character following the range before editing.
+   * @returns whether the range mapped and the edit applied.
+   */
+  insertReference(span: DetectSpan, ref: ReferenceInsert, tail: string): boolean {
+    let applied = false
+    this.applyEdit(() => {
+      const nodes = tail === ' '
+        ? [$createReferenceChipNode(ref)]
+        : [$createReferenceChipNode(ref), $createTextNode(' ')]
+      applied = $replaceDetectSpanWithNodes(span, nodes)
+    })
+    return applied
+  }
+
+  /** Refresh claim-token decoration after the model's claim changes. */
+  refreshClaimDecoration(): void {
+    refreshClaimDecoration(this.editor)
+  }
+
+  /**
+   * Clear committed content using the model's suffix decision inside the editor update.
+   * @param prefixLength - returns the clipboard-prefix length to remove, or null to clear the root.
+   */
+  clearCommittedDraft(prefixLength: (clipboardText: string) => number | null): void {
+    this.editor.update(() => {
+      const layout = $composerLayout()
+      const length = prefixLength(layout.clipboardText)
+      if (length !== null) {
+        $replaceDetectSpanWithText(
+          { start: 0, end: detectOffsetOfClipboardOffset(layout, length) }, '',
+        )
+        return
+      }
+      const root = $getRoot()
+      root.clear()
+      root.selectEnd()
+    }, { discrete: true, tag: HISTORY_MERGE_TAG })
+  }
+
+  /**
+   * Rebuild one model-selected failure snapshot, creating fresh reference nodes.
+   * @param draft - clipboard text.
+   * @param occurrences - reference occurrences in clipboard order.
+   */
+  restoreDraft(draft: string, occurrences: readonly Occurrence[]): void {
+    this.editor.update(() => {
+      const root = $getRoot()
+      root.clear()
+      let paragraph = $createParagraphNode()
+      root.append(paragraph)
+      const appendText = (text: string): void => {
+        const lines = text.split('\n')
+        for (let i = 0; i < lines.length; i += 1) {
+          const line = lines[i]
+          if (line !== '') paragraph.append($createTextNode(line))
+          if (i < lines.length - 1) {
+            paragraph = $createParagraphNode()
+            root.append(paragraph)
+          }
+        }
+      }
+      let cursor = 0
+      for (const occurrence of occurrences) {
+        appendText(draft.slice(cursor, occurrence.offset))
+        paragraph.append(new ReferenceChipNode({
+          source: occurrence.source,
+          ref: occurrence.ref,
+          label: occurrence.label,
+          ...(occurrence.appearance === undefined ? {} : { appearance: occurrence.appearance }),
+          clipboardText: occurrence.clipboardText,
+        }, occurrence.invalid === true))
+        cursor = occurrence.offset + occurrence.length
+      }
+      appendText(draft.slice(cursor))
+      root.selectEnd()
+    }, { discrete: true, tag: HISTORY_MERGE_TAG })
+  }
+
+  /** Cut the editor's undo history after a committed clear or restoration. */
+  clearHistory(): void {
+    this.editor.dispatchCommand(CLEAR_HISTORY_COMMAND, undefined)
+  }
+}
diff --git a/packages/client/ui-conversation/src/client/input/editor/view-binding.ts b/packages/client/ui-conversation/src/client/input/editor/view-binding.ts
new file mode 100644
index 0000000000..8dcd3d8c63
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/input/editor/view-binding.ts
@@ -0,0 +1,155 @@
+/** DOM and keymap bindings installed by the InputBar's existing effects. */
+import type { MouseEvent, MutableRefObject, RefObject } from 'react'
+import type { LexicalEditor } from 'lexical'
+import type { ComposerKeyboard } from '../../contract/draft-editor.ts'
+import type { ComposerBarProps } from '../../contract/slots.ts'
+import type { BusyEnterBehavior } from '../../contract/composer-submission.ts'
+import { resolveSubmitMode } from '../submission-policy.ts'
+import { registerComposerKeymap } from './keymap.ts'
+
+interface DraftViewGate {
+  locked: boolean
+  machineBusy: boolean
+  canSteerQueue: boolean
+  running: boolean
+  steeringAvailable: boolean
+  busyEnter: BusyEnterBehavior
+  intakeFiles: (files: readonly File[]) => void
+  uploadsPending: boolean
+  showToast: (text: string) => void
+  t: ComposerBarProps['t']
+  canAcceptDrop: boolean
+}
+
+/**
+ * Reveal the DOM selection within the draft's own scrollport.
+ * @param scrollRef - the InputBar-owned scrollport reference.
+ */
+export function revealDraftSelection(scrollRef: RefObject<HTMLDivElement>): void {
+  const scrollEl = scrollRef.current
+  if (scrollEl === null || scrollEl.scrollHeight <= scrollEl.clientHeight) return
+  const selection = window.getSelection()
+  if (selection === null || selection.rangeCount === 0) return
+  const range = selection.getRangeAt(0)
+  let rect = range.getBoundingClientRect()
+  if (rect.height === 0 && rect.width === 0) {
+    // A collapsed caret at an empty line reports a zero rect in some
+    // engines; the anchor's element box is the line the caret sits on.
+    const anchor = selection.anchorNode
+    const el = anchor instanceof HTMLElement ? anchor : anchor?.parentElement
+    if (el === undefined || el === null) return
+    rect = el.getBoundingClientRect()
+  }
+  const box = scrollEl.getBoundingClientRect()
+  if (rect.bottom > box.bottom) scrollEl.scrollTop += rect.bottom - box.bottom
+  else if (rect.top < box.top) scrollEl.scrollTop -= box.top - rect.top
+}
+
+/**
+ * Focus the borrowed editor and reveal its restored selection.
+ * @param editor - the Session-owned editor.
+ * @param revealSelection - reveal the selection after Lexical restores it.
+ */
+export function focusDraftEditor(editor: LexicalEditor, revealSelection: () => void): void {
+  // Lexical's focus() restores the editor selection but never calls the DOM
+  // focus itself; preventScroll keeps the conversation scrollport still.
+  editor.getRootElement()?.focus({ preventScroll: true })
+  editor.focus(() => { revealSelection() })
+}
+
+/**
+ * Forward wheel movement at the draft's edge to its conversation scrollport.
+ * @param scrollRef - the InputBar-owned scrollport reference.
+ * @returns the listener cleanup, or undefined when the element is absent.
+ */
+export function installDraftWheel(scrollRef: RefObject<HTMLDivElement>): (() => void) | undefined {
+  const el = scrollRef.current
+  if (el === null) return
+  const onWheel = (e: WheelEvent): void => {
+    const host = el.closest('[data-conversation-scroll]')
+    if (!(host instanceof HTMLElement) || e.deltaY === 0) return
+    const atTop = el.scrollTop <= 0
+    const atEnd = el.scrollTop + el.clientHeight >= el.scrollHeight - 1
+    if ((e.deltaY < 0 && !atTop) || (e.deltaY > 0 && !atEnd)) return
+    e.preventDefault()
+    host.scrollTop += e.deltaY
+  }
+  el.addEventListener('wheel', onWheel, { passive: false })
+  return () => { el.removeEventListener('wheel', onWheel) }
+}
+
+/**
+ * Bind this view's file dialog through the existing keyboard face.
+ * @param keyboard - the Session-owned composer operations.
+ * @param gate - live intake availability retained by InputBar.
+ * @param fileInputRef - the view's native file input.
+ * @returns the picker unbind disposer.
+ */
+export function installDraftFilePicker(
+  keyboard: ComposerKeyboard,
+  gate: MutableRefObject<Pick<DraftViewGate, 'canAcceptDrop'>>,
+  fileInputRef: RefObject<HTMLInputElement>,
+): () => void {
+  return keyboard.bindFilePicker({
+    available: () => gate.current.canAcceptDrop && fileInputRef.current !== null,
+    open: () => { fileInputRef.current?.click() },
+  })
+}
+
+/**
+ * Bind editor gestures to the view's live guards and Session operations.
+ * @param editor - the borrowed Session-owned editor.
+ * @param keyboard - the existing composer keyboard operations.
+ * @param gate - live view values read by the installed handlers.
+ * @returns the keymap disposer.
+ */
+export function installDraftKeymap(
+  editor: LexicalEditor,
+  keyboard: ComposerKeyboard,
+  gate: MutableRefObject<DraftViewGate>,
+): () => void {
+  return registerComposerKeymap(editor, {
+    arbitrate: (key, composing) => keyboard.arbitrate(key, composing),
+    space: () => {
+      if (gate.current.machineBusy || gate.current.locked) return false
+      return keyboard.space()
+    },
+    dismissPopup: () => { keyboard.dismissPopup() },
+    canSubmit: () => !gate.current.locked && !gate.current.machineBusy,
+    submit: (accelerated) => {
+      const g = gate.current
+      // Empty-draft accelerated Enter acts on the queue instead of the
+      // (empty) draft: the machine rejects empty drafts, so the gesture
+      // steers every still-pending queued message into the running turn.
+      if (accelerated && g.canSteerQueue) {
+        keyboard.steerQueue()
+        return
+      }
+      if (g.uploadsPending) {
+        g.showToast(g.t('file.stillUploading'))
+        return
+      }
+      keyboard.submit(resolveSubmitMode(
+        g.busyEnter,
+        g.running,
+        accelerated ? 'accelerated' : 'enter',
+        g.steeringAvailable,
+      ))
+    },
+    intakeFiles: (files) => { gate.current.intakeFiles(files) },
+    pasteText: (text) => {
+      if (gate.current.machineBusy || gate.current.locked) return
+      keyboard.paste(text)
+    },
+  })
+}
+
+/**
+ * Keep a toolbar press from moving focus away from the draft.
+ * @param event - the toolbar button's mouse event.
+ * @param editor - the borrowed editor, absent in the inert view.
+ */
+export function keepDraftFocus(event: MouseEvent<HTMLButtonElement>, editor: LexicalEditor | null): void {
+  event.preventDefault()
+  editor?.getRootElement()?.focus({ preventScroll: true })
+}
diff --git a/packages/client/ui-conversation/src/client/input/facade.ts b/packages/client/ui-conversation/src/client/input/facade.ts
index 80509a6ac7..a30edb016c 100644
--- a/packages/client/ui-conversation/src/client/input/facade.ts
+++ b/packages/client/ui-conversation/src/client/input/facade.ts
@@ -12,29 +12,19 @@ import type { Context } from '@deepseek-ai/cordis'
 import {
   createSnapshotStore, type ObservableSnapshot, type SnapshotStore,
 } from '@deepseek-ai/dsh-client-store'
-import type { LexicalEditor, NodeKey } from 'lexical'
-import {
-  $addUpdateTag, $createParagraphNode, $createTextNode, $getRoot, $getSelection, $isRangeSelection,
-  CLEAR_HISTORY_COMMAND, createEditor, HISTORY_MERGE_TAG, PASTE_TAG,
-} from 'lexical'
-import { registerPlainText } from '@lexical/plain-text'
-import { createEmptyHistoryState, registerHistory } from '@lexical/history'
-import { mergeRegister } from '@lexical/utils'
+import type { LexicalEditor } from 'lexical'
 import type {
-  ArbitrateKey, ArbitrateOutcome, CommandClaim, ComposerKeyboard, ConsumeTokenRequest, DraftAttachmentId,
+  CommandClaim, ConsumeTokenRequest, DraftAttachmentId,
   InputActions, InputEffect, InputNotice, InputState, InputTriggerController, PickOutcome,
-  Occurrence, QueuedMessage, ReferenceInsert, SessionInput, SubmitAttempt, SubmitAttachment,
-  SubmitOutcome, TokenSpan,
+  QueuedMessage, SessionInput, SubmitAttempt, SubmitAttachment, SubmitOutcome,
 } from '../contract/input.ts'
+import type {
+  ArbitrateKey, ArbitrateOutcome, ComposerKeyboard, Occurrence, ReferenceInsert, TokenSpan,
+} from '../contract/draft-editor.ts'
 import type { InputSubmitMode } from '../contract/composer-submission.ts'
 import { SubmitMachine } from './machine.ts'
-import { registerReferenceActivation } from './editor/reference-activation.ts'
-import { ReferenceChipNode, $createReferenceChipNode } from './editor/chip-node.tsx'
-import { refreshClaimDecoration, registerClaimDecoration } from './editor/claim-decor.ts'
-import { registerTextRefDecoration, rescanTextRefs, TextRefNode } from './editor/text-ref.ts'
+import { DraftEditorRuntime } from './editor/runtime.ts'
 import type { EditorProjection } from './editor/projection.ts'
-import { $composerLayout, $projectComposer, detectOffsetOfClipboardOffset } from './editor/projection.ts'
-import { $replaceDetectSpanWithNodes, $replaceDetectSpanWithText } from './editor/span-map.ts'
 
 /** Popup face the shell needs (dismissal only; typed structurally to avoid a value import). */
 export interface PopupDismissFace {
@@ -103,17 +93,6 @@ const EMPTY_QUEUE: readonly QueuedMessage[] = []
 /** No-pipeline lexicon: zero text-ref decorations. */
 const EMPTY_LEXICON: ReadonlyMap<'/' | '@', readonly string[]> = new Map()
 
-/**
- * Detect-projection and legacy reference placeholders stripped from every
- * external text entering the document (paste, persisted-draft seed): a chip
- * is the only legitimate source of U+FFFC in the detect projection, so a
- * literal one in text would forge chip positions.
- */
-const REFERENCE_PLACEHOLDER_RE = /[\uE100-\uE11D\uFFFC]/gu
-
-/** Undo merge window for contiguous typing, in ms (the old machine's mergeWindowMs). */
-const HISTORY_MERGE_DELAY_MS = 1000
-
 /** Editor and attachment snapshot owned by one detached default send. */
 interface DetachedDraft {
   readonly draft: string
@@ -132,7 +111,9 @@ export class SessionInputShell implements SessionInput {
   /** Latest surfaced notice (null after clear); the bar renders errors as banners and information inline. */
   readonly notices: SnapshotStore<InputNotice | null> = createSnapshotStore<InputNotice | null>(null)
   /** The shell-owned editor (text + chip truth); the composer binds its contenteditable to it. */
-  readonly editor: LexicalEditor
+  get editor(): LexicalEditor {
+    return this.draftEditor.editor
+  }
   /** The public provide-channel action face (one stable identity per session). */
   readonly actions: InputActions = {
     setDraft: (text) => { this.setDraft(text) },
@@ -143,11 +124,11 @@ export class SessionInputShell implements SessionInput {
   }
 
   private readonly core = new SubmitMachine()
-  private projection: EditorProjection = { detectText: '', clipboardText: '', occurrences: [], selection: null, caret: null }
+  private readonly draftEditor: DraftEditorRuntime
+  private get projection(): EditorProjection {
+    return this.draftEditor.projection
+  }
   private rev = 0
-  /** Stable occurrence ids per chip NodeKey (undo restores keys, so ids survive it too). */
-  private readonly occurrenceIds = new Map<NodeKey, number>()
-  private occurrenceSeq = 0
   private readonly unregister: () => void
   private noticeSeq = 0
   private lastMirroredDraft = ''
@@ -157,8 +138,6 @@ export class SessionInputShell implements SessionInput {
   private mirrorFn: ((text: string) => void) | undefined
   /** The mounted composer's file-picker opener (scoped pick-files event target). */
   private filePicker: Parameters<ComposerKeyboard['bindFilePicker']>[0] | undefined
-  /** Live lexicon subscription disposer; undefined until the controller resolves. */
-  private lexiconOff: (() => void) | undefined
   /** Default sends retained until admission settles or scope disposal releases their attachments. */
   private readonly detachedDrafts = new Map<number, DetachedDraft>()
   /** Failed default sends waiting to be restored together in submission order. */
@@ -174,67 +153,24 @@ export class SessionInputShell implements SessionInput {
   }>()
 
   constructor(private readonly deps: SessionInputDeps) {
-    this.editor = createEditor({
-      namespace: 'dsh-composer',
-      nodes: [ReferenceChipNode, TextRefNode],
-      onError: (error) => { throw error },
+    this.draftEditor = new DraftEditorRuntime({
+      onUpdate: () => { this.onEditorUpdate() },
+      openReference: (source, reference) =>
+        this.deps.inputTriggers?.()?.openReference(source, reference) ?? false,
+      activeClaimToken: () => this.activeClaimToken(),
+      lexicon: () => this.lexicon.getSnapshot(),
+      resolveLexicon: () => this.deps.inputTriggers?.()?.lexicon,
     })
-    this.unregister = mergeRegister(
-      registerPlainText(this.editor),
-      registerReferenceActivation(this.editor, (source, reference) =>
-        this.deps.inputTriggers?.()?.openReference(source, reference) ?? false),
-      registerHistory(this.editor, createEmptyHistoryState(), HISTORY_MERGE_DELAY_MS),
-      this.editor.registerUpdateListener(() => { this.onEditorUpdate() }),
-      registerClaimDecoration(this.editor, () => this.activeClaimToken()),
-      registerTextRefDecoration(this.editor, () => this.lexicon.getSnapshot(), () => this.activeClaimToken()),
-      () => { this.lexiconOff?.() },
-    )
+    this.unregister = this.draftEditor.register()
     this.state = createSnapshotStore<InputState>(this.compose())
     deps.queue?.subscribe(() => { this.publish() })
   }
 
   // ---- editor plumbing ----
 
-  /**
-   * Run one editor edit whose result is observable on return. At the top
-   * level this is a discrete update. Inside this editor's own update —
-   * command handlers land here synchronously (space/enter picks, paste) —
-   * $-functions are already legal, and wrapping them in update() would DEFER
-   * them past the synchronous bail answer (and a nested discrete throws);
-   * the body runs directly and the outer update commits it.
-   * @param fn - the $-edit body.
-   */
-  private applyEdit(fn: () => void, tag?: string): void {
-    if (this.editor._updating) {
-      // Nested application joins the enclosing update (the PASTE_COMMAND
-      // dispatch path always lands here), so the tag attaches to that update.
-      if (tag !== undefined) $addUpdateTag(tag)
-      fn()
-      return
-    }
-    this.editor.update(fn, { discrete: true, ...(tag === undefined ? {} : { tag }) })
-  }
-
-
-  /**
-   * Subscribe the text-ref re-scan to the controller's lexicon once the
-   * controller resolves. The deps thunk cannot resolve at construction (the
-   * shell is created inside the sessions provide materialization), so the
-   * first interactive updates retry until it can.
-   */
-  private ensureLexiconSubscription(): void {
-    if (this.lexiconOff !== undefined) return
-    const controller = this.deps.inputTriggers?.()
-    if (controller === undefined) return
-    this.lexiconOff = controller.lexicon.subscribe(() => { rescanTextRefs(this.editor) })
-  }
-
   /** Re-project, run the claim watch, publish, and feed trigger tracking after every editor commit. */
   private onEditorUpdate(): void {
-    this.ensureLexiconSubscription()
-    const prev = this.projection
-    this.projection = this.editor.getEditorState().read(() =>
-      $projectComposer(key => this.occurrenceIdOf(key)))
+    const prev = this.draftEditor.refreshProjection()
     // Selection-only commits advance neither the revision nor the published
     // state: menus still track the caret below, while draftRev moves only
     // with content so a snapshot-built span (apply.ts) stays CAS-valid across
@@ -255,14 +191,6 @@ export class SessionInputShell implements SessionInput {
     }
   }
 
-  private occurrenceIdOf(key: NodeKey): number {
-    const existing = this.occurrenceIds.get(key)
-    if (existing !== undefined) return existing
-    this.occurrenceSeq += 1
-    this.occurrenceIds.set(key, this.occurrenceSeq)
-    return this.occurrenceSeq
-  }
-
   // ---- SessionInput face ----
 
   /**
@@ -272,18 +200,7 @@ export class SessionInputShell implements SessionInput {
    * @param text - the full next draft.
    */
   setDraft(text: string): void {
-    const clean = text.replace(REFERENCE_PLACEHOLDER_RE, '')
-    if (clean === this.projection.clipboardText) return
-    this.editor.update(() => {
-      const root = $getRoot()
-      root.clear()
-      for (const line of clean.split('\n')) {
-        const paragraph = $createParagraphNode()
-        if (line !== '') paragraph.append($createTextNode(line))
-        root.append(paragraph)
-      }
-      root.selectEnd()
-    }, { discrete: true, tag: HISTORY_MERGE_TAG })
+    this.draftEditor.setDraft(text)
   }
 
   /** Append ordered attachment ids unless an admission transaction is locked. */
@@ -341,20 +258,7 @@ export class SessionInputShell implements SessionInput {
    * @param text - pasted plain text.
    */
   paste(text: string): void {
-    const clean = text.replace(REFERENCE_PLACEHOLDER_RE, '')
-    if (clean === '') return
-    this.applyEdit(() => {
-      const selection = $getSelection()
-      if ($isRangeSelection(selection)) {
-        selection.insertText(clean)
-        return
-      }
-      // No selection yet (never-focused surface): land at the document end,
-      // growing the first paragraph when the tree is empty.
-      const root = $getRoot()
-      if (root.getChildrenSize() === 0) root.append($createParagraphNode())
-      root.selectEnd().insertText(clean)
-    }, PASTE_TAG)
+    this.draftEditor.paste(text)
   }
 
   /**
@@ -446,9 +350,7 @@ export class SessionInputShell implements SessionInput {
    * @returns the ordered [start, end) span in detect coordinates.
    */
   caretSpan(): { start: number; end: number } {
-    if (this.projection.selection !== null) return this.projection.selection
-    const at = this.projection.detectText.length
-    return { start: at, end: at }
+    return this.draftEditor.caretSpan()
   }
 
   /**
@@ -479,10 +381,7 @@ export class SessionInputShell implements SessionInput {
     // Leading-trigger contract: only whitespace may precede the span; the
     // whitespace prefix is dropped so the claimed watch (startsWith) holds.
     if (this.projection.detectText.slice(0, span.start).trim() !== '') return false
-    let applied = false as boolean
-    this.applyEdit(() => {
-      applied = $replaceDetectSpanWithText({ start: 0, end: span.end }, claim.token)
-    })
+    const applied = this.draftEditor.replaceText({ start: 0, end: span.end }, claim.token)
     if (!applied) return false
     this.dispatchRun(({ type: 'claim', claim }))
     return true
@@ -501,14 +400,7 @@ export class SessionInputShell implements SessionInput {
     if (phase !== 'plain' && phase !== 'claimed') return false
     if (span.draftRev !== this.rev) return false
     const tail = this.projection.detectText.slice(span.end, span.end + 1)
-    let applied = false
-    this.applyEdit(() => {
-      const nodes = tail === ' '
-        ? [$createReferenceChipNode(ref)]
-        : [$createReferenceChipNode(ref), $createTextNode(' ')]
-      applied = $replaceDetectSpanWithNodes(span, nodes)
-    })
-    return applied
+    return this.draftEditor.insertReference(span, ref, tail)
   }
 
   /**
@@ -521,11 +413,7 @@ export class SessionInputShell implements SessionInput {
   consumeToken(guard: ConsumeTokenRequest['guard']): boolean {
     if (guard.kind === 'span') {
       if (guard.span.draftRev !== this.rev || guard.span.start === guard.span.end) return false
-      let applied = false
-      this.applyEdit(() => {
-        applied = $replaceDetectSpanWithText(guard.span, '')
-      })
-      return applied
+      return this.draftEditor.replaceText(guard.span, '')
     }
     if (guard.token === '' || this.projection.clipboardText.trim() !== guard.token) return false
     this.setDraft('')
@@ -548,11 +436,7 @@ export class SessionInputShell implements SessionInput {
   insertText(text: string, span: TokenSpan, keepCompleting = false): boolean {
     void keepCompleting
     if (span.draftRev !== this.rev) return false
-    let applied = false
-    this.applyEdit(() => {
-      applied = $replaceDetectSpanWithText(span, text)
-    })
-    return applied
+    return this.draftEditor.replaceText(span, text)
   }
 
   /**
@@ -585,7 +469,6 @@ export class SessionInputShell implements SessionInput {
     this.disposed = true
     this.dispatchRun(({ type: 'release' }))
     this.unregister()
-    this.editor.setRootElement(null)
     this.detachedDrafts.clear()
     this.failedDetached.clear()
     this.attachmentFlights.clear()
@@ -656,7 +539,7 @@ export class SessionInputShell implements SessionInput {
   private dispatchRun(ev: Parameters<SubmitMachine['dispatch']>[0]): void {
     const beforeToken = this.activeClaimToken()
     this.run(this.core.dispatch(ev))
-    if (this.activeClaimToken() !== beforeToken) refreshClaimDecoration(this.editor)
+    if (this.activeClaimToken() !== beforeToken) this.draftEditor.refreshClaimDecoration()
   }
 
   private run(effects: readonly InputEffect[]): void {
@@ -696,20 +579,13 @@ export class SessionInputShell implements SessionInput {
    * undo history so sent content cannot resurrect.
    */
   private commitDraft(retainSuffixOf: string | null): void {
-    this.editor.update(() => {
-      const layout = $composerLayout()
-      const clip = layout.clipboardText
+    this.draftEditor.clearCommittedDraft((clip) => {
       if (retainSuffixOf !== null && clip !== retainSuffixOf && clip.startsWith(retainSuffixOf)) {
-        $replaceDetectSpanWithText(
-          { start: 0, end: detectOffsetOfClipboardOffset(layout, retainSuffixOf.length) }, '',
-        )
-        return
+        return retainSuffixOf.length
       }
-      const root = $getRoot()
-      root.clear()
-      root.selectEnd()
-    }, { discrete: true, tag: HISTORY_MERGE_TAG })
-    this.editor.dispatchCommand(CLEAR_HISTORY_COMMAND, undefined)
+      return null
+    })
+    this.draftEditor.clearHistory()
   }
 
   /**
@@ -819,38 +695,8 @@ export class SessionInputShell implements SessionInput {
     }
     this.restoringFailures = true
     try {
-      this.editor.update(() => {
-        const root = $getRoot()
-        root.clear()
-        let paragraph = $createParagraphNode()
-        root.append(paragraph)
-        const appendText = (text: string): void => {
-          const lines = text.split('\n')
-          for (let i = 0; i < lines.length; i += 1) {
-            const line = lines[i]
-            if (line !== '') paragraph.append($createTextNode(line))
-            if (i < lines.length - 1) {
-              paragraph = $createParagraphNode()
-              root.append(paragraph)
-            }
-          }
-        }
-        let cursor = 0
-        for (const occurrence of occurrences) {
-          appendText(draft.slice(cursor, occurrence.offset))
-          paragraph.append(new ReferenceChipNode({
-            source: occurrence.source,
-            ref: occurrence.ref,
-            label: occurrence.label,
-            ...(occurrence.appearance === undefined ? {} : { appearance: occurrence.appearance }),
-            clipboardText: occurrence.clipboardText,
-          }, occurrence.invalid === true))
-          cursor = occurrence.offset + occurrence.length
-        }
-        appendText(draft.slice(cursor))
-        root.selectEnd()
-      }, { discrete: true, tag: HISTORY_MERGE_TAG })
-      this.editor.dispatchCommand(CLEAR_HISTORY_COMMAND, undefined)
+      this.draftEditor.restoreDraft(draft, occurrences)
+      this.draftEditor.clearHistory()
       this.failedRestoreRev = this.rev
     } finally {
       this.restoringFailures = false
diff --git a/packages/client/ui-conversation/src/client/input/hub.ts b/packages/client/ui-conversation/src/client/input/hub.ts
index 3a862753e1..b09db9bf60 100644
--- a/packages/client/ui-conversation/src/client/input/hub.ts
+++ b/packages/client/ui-conversation/src/client/input/hub.ts
@@ -15,9 +15,10 @@ import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-locale/client'
 import { queueReadFaceOf } from './queue-store.ts'
 import type {
-  ComposerKeyboard, DraftAttachmentId, DraftAttachmentSerializationResult, InputTriggerController,
+  DraftAttachmentId, DraftAttachmentSerializationResult, InputTriggerController,
   SessionInputResolver, SessionInput, SubmitOutcome,
 } from '../contract/input.ts'
+import type { ComposerKeyboard } from '../contract/draft-editor.ts'
 import type { InputSubmitMode } from '../contract/composer-submission.ts'
 import type { PopupDismissFace } from './facade.ts'
 import { SessionInputShell } from './facade.ts'
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
index 22420cc8d8..4962d24672 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
@@ -370,7 +370,12 @@
   position: sticky;
   bottom: 0;
   /* Above markdown CodeBlock sticky banners (z-index 6) so the footer never
-     paints under a sticking code header while scrolling. */
+     paints under a sticking code header while scrolling. The pinned compaction
+     header (MessageItem.module.css, ui-chat) and the turn-navigation rail slot
+     (TurnNavigator.module.css, ui-chat) also take 7 to clear the same banners.
+     Among elements of equal rank the later one in DOM order wins, so the
+     composer stays above the pinned header on the extreme small-viewport
+     overlap and the pinned header stays above the rail. */
   z-index: 7;
   /* Input mask (figma 1205:27463): transcript fades out under a FIXED 36px
      band at the seat's top (the figma 24% of the resting ~150px composer),
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
index ddc8b665ce..4bae3819a4 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx
@@ -14,7 +14,7 @@
  */
 
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import type { ChangeEvent, CSSProperties, KeyboardEvent, MouseEvent } from 'react'
+import type { ChangeEvent, KeyboardEvent, MouseEvent } from 'react'
 import clsx from 'clsx'
 import {
   IconPlusOutline16, IconWarningOutline16, Toast, Tooltip,
@@ -29,9 +29,11 @@ import type {} from '@deepseek-ai/dsh-goal/client'
 // api-remotes import already places it in every client program.
 import type { Translate } from '@deepseek-ai/dsh-client-ui-slots'
 import type { ComposerBarProps } from '../contract/slots.ts'
-import { ComposerContentEditable } from '../input/editor/ComposerContentEditable.tsx'
-import { DecoratorPortals } from '../input/editor/DecoratorPortals.tsx'
-import { registerComposerKeymap } from '../input/editor/keymap.ts'
+import { DraftEditor } from '../input/editor/DraftEditor.tsx'
+import {
+  focusDraftEditor, installDraftFilePicker, installDraftKeymap, installDraftWheel,
+  keepDraftFocus, revealDraftSelection,
+} from '../input/editor/view-binding.ts'
 import { resolveSubmitMode } from '../input/submission-policy.ts'
 import { attachmentErrorText, imageSizeText } from '../image-labels.ts'
 import { ContextMeter } from './ContextMeter.tsx'
@@ -152,23 +154,7 @@ export const InputBar = memo(function InputBar({
   // session switches that land the caret off screen). The live DOM selection
   // is the ruler; no mirror layer exists to consult.
   const revealSelection = (): void => {
-    const scrollEl = scrollRef.current
-    if (scrollEl === null || scrollEl.scrollHeight <= scrollEl.clientHeight) return
-    const selection = window.getSelection()
-    if (selection === null || selection.rangeCount === 0) return
-    const range = selection.getRangeAt(0)
-    let rect = range.getBoundingClientRect()
-    if (rect.height === 0 && rect.width === 0) {
-      // A collapsed caret at an empty line reports a zero rect in some
-      // engines; the anchor's element box is the line the caret sits on.
-      const anchor = selection.anchorNode
-      const el = anchor instanceof HTMLElement ? anchor : anchor?.parentElement
-      if (el === undefined || el === null) return
-      rect = el.getBoundingClientRect()
-    }
-    const box = scrollEl.getBoundingClientRect()
-    if (rect.bottom > box.bottom) scrollEl.scrollTop += rect.bottom - box.bottom
-    else if (rect.top < box.top) scrollEl.scrollTop -= box.top - rect.top
+    revealDraftSelection(scrollRef)
   }
 
   // Unlock (mount / session switch) returns focus to the box, and owns the
@@ -178,10 +164,7 @@ export const InputBar = memo(function InputBar({
   // caret (restored at the draft's end) off screen.
   useEffect(() => {
     if (locked || editor === null) return
-    // Lexical's focus() restores the editor selection but never calls the DOM
-    // focus itself; preventScroll keeps the conversation scrollport still.
-    editor.getRootElement()?.focus({ preventScroll: true })
-    editor.focus(() => { revealSelection() })
+    focusDraftEditor(editor, revealSelection)
   }, [locked, sessionId, editor])
 
   // A persisted draft arrives AFTER the unlock effect: ConversationSession
@@ -202,19 +185,7 @@ export const InputBar = memo(function InputBar({
   // a short draft never traps the gesture and a long draft stays scrollable.
   // Hero mounts have no host and keep native wheel scrolling.
   useEffect(() => {
-    const el = scrollRef.current
-    if (el === null) return
-    const onWheel = (e: WheelEvent): void => {
-      const host = el.closest('[data-conversation-scroll]')
-      if (!(host instanceof HTMLElement) || e.deltaY === 0) return
-      const atTop = el.scrollTop <= 0
-      const atEnd = el.scrollTop + el.clientHeight >= el.scrollHeight - 1
-      if ((e.deltaY < 0 && !atTop) || (e.deltaY > 0 && !atEnd)) return
-      e.preventDefault()
-      host.scrollTop += e.deltaY
-    }
-    el.addEventListener('wheel', onWheel, { passive: false })
-    return () => { el.removeEventListener('wheel', onWheel) }
+    return installDraftWheel(scrollRef)
   }, [])
 
   // Intake pre-check: an addition that would break a projected image limit is
@@ -270,48 +241,12 @@ export const InputBar = memo(function InputBar({
 
   useEffect(() => {
     if (keyboard === undefined) return
-    return keyboard.bindFilePicker({
-      available: () => gate.current.canAcceptDrop && fileInputRef.current !== null,
-      open: () => { fileInputRef.current?.click() },
-    })
+    return installDraftFilePicker(keyboard, gate, fileInputRef)
   }, [keyboard])
 
   useEffect(() => {
     if (editor === null || keyboard === undefined) return
-    return registerComposerKeymap(editor, {
-      arbitrate: (key, composing) => keyboard.arbitrate(key, composing),
-      space: () => {
-        if (gate.current.machineBusy || gate.current.locked) return false
-        return keyboard.space()
-      },
-      dismissPopup: () => { keyboard.dismissPopup() },
-      canSubmit: () => !gate.current.locked && !gate.current.machineBusy,
-      submit: (accelerated) => {
-        const g = gate.current
-        // Empty-draft accelerated Enter acts on the queue instead of the
-        // (empty) draft: the machine rejects empty drafts, so the gesture
-        // steers every still-pending queued message into the running turn.
-        if (accelerated && g.canSteerQueue) {
-          keyboard.steerQueue()
-          return
-        }
-        if (g.uploadsPending) {
-          g.showToast(g.t('file.stillUploading'))
-          return
-        }
-        keyboard.submit(resolveSubmitMode(
-          g.busyEnter,
-          g.running,
-          accelerated ? 'accelerated' : 'enter',
-          g.steeringAvailable,
-        ))
-      },
-      intakeFiles: (files) => { gate.current.intakeFiles(files) },
-      pasteText: (text) => {
-        if (gate.current.machineBusy || gate.current.locked) return
-        keyboard.paste(text)
-      },
-    })
+    return installDraftKeymap(editor, keyboard, gate)
   }, [editor, keyboard])
 
   // Button presses steal focus from the editor; suppress at mousedown so
@@ -319,8 +254,7 @@ export const InputBar = memo(function InputBar({
   // restores the previous selection, so no reveal is needed: the caret has
   // not moved, and the next keystroke gets the browser's native one.
   const keepFocus = (e: MouseEvent<HTMLButtonElement>): void => {
-    e.preventDefault()
-    editor?.getRootElement()?.focus({ preventScroll: true })
+    keepDraftFocus(e, editor)
   }
 
   const onToggleCommandMenu = (): void => {
@@ -446,32 +380,21 @@ export const InputBar = memo(function InputBar({
             thing that scrolls. Chips are decorator portals inside the same
             surface, so wrapping, caret geometry, and scrolling are the
             browser's own. */}
-        <div ref={scrollRef} className={css.scroll} data-input-scroll>
-          <div className={css.grow}>
-            <ComposerContentEditable
-              editor={workspaceTrigger ? null : editor}
-              editable={editable}
-              className={clsx(css.input, editorDisabled && css.inputDisabled)}
-              data-phase={input?.phase ?? 'inert'}
-              aria-disabled={editorDisabled || undefined}
-              data-placeholder={placeholderText}
-              // The placeholder was the textarea's accessible name; a div's
-              // data attribute is not, so the label restores it.
-              aria-label={workspaceTrigger ? t('hero.chooseWorkspace') : placeholderText}
-              aria-haspopup={workspaceTrigger ? 'menu' : undefined}
-              aria-expanded={workspaceTrigger ? workspacePickerOpen : undefined}
-              tabIndex={workspaceTrigger ? 0 : undefined}
-              onKeyDown={workspaceTrigger ? onWorkspaceKeyDown : undefined}
-              style={hint === null ? undefined : { '--dsh-composer-hint': JSON.stringify(hint) } as CSSProperties}
-            />
-            {draft === '' && attachments.length === 0 && !claimActive && (
-              <div aria-hidden className={css.placeholder} data-composer-placeholder>
-                {placeholderText}
-              </div>
-            )}
-            <DecoratorPortals editor={workspaceTrigger ? null : editor} />
-          </div>
-        </div>
+        <DraftEditor
+          classNames={css}
+          editor={editor}
+          scrollRef={scrollRef}
+          editable={editable}
+          editorDisabled={editorDisabled}
+          phase={input?.phase ?? 'inert'}
+          placeholderText={placeholderText}
+          ariaLabel={workspaceTrigger ? t('hero.chooseWorkspace') : placeholderText}
+          workspaceTrigger={workspaceTrigger}
+          workspacePickerOpen={workspacePickerOpen}
+          onWorkspaceKeyDown={onWorkspaceKeyDown}
+          hint={hint}
+          showPlaceholder={draft === '' && attachments.length === 0 && !claimActive}
+        />
         <div className={css.row}>
           <div className={css.tools}>
             <Tooltip label={t('input.commands')} side="top" delayMs={500}>
diff --git a/packages/client/ui-conversation/tests/lexical-editor-core.client.spec.tsx b/packages/client/ui-conversation/tests/lexical-editor-core.client.spec.tsx
index 92bfa3ce15..2d63aaefa9 100644
--- a/packages/client/ui-conversation/tests/lexical-editor-core.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/lexical-editor-core.client.spec.tsx
@@ -12,7 +12,7 @@ import {
   $createLineBreakNode, $createParagraphNode, $createTextNode, $getRoot, $getSelection,
   $isTextNode, $setSelection,
 } from 'lexical'
-import type { ReferenceInsert } from '../src/client/contract/input.ts'
+import type { ReferenceInsert } from '../src/client/contract/draft-editor.ts'
 import {
   $createReferenceChipNode, $isReferenceChipNode, ReferenceChipNode,
 } from '../src/client/input/editor/chip-node.tsx'
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index ff5374fea9..d24b95aa0c 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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 packages/client/ui-primitives/README.md
-README.md: 07e61be1bb993716c85273aac8ee6e650d221365
-README.zh.md: 194d8e994d82ae167ce2c7af06d9b199ef066b27
+README.md: 631b19de44660c21813bc4f87b7a59dc8dfa6ee3
+README.zh.md: b23c87f7861555625f28a9fd182aa6acb159b21c
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 07e61be1bb..631b19de44 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -73,6 +73,7 @@ The catalog above lists what each export is for; this section covers the behavio
 
 `MarkdownText` renders untrusted GFM and TeX math, blocks unsafe links and images, and can turn resolved file mentions into explicit controls. When the owner passes a `pathImages` vocabulary, image destinations that are local media paths rewrite to displayable URLs on settled renders only (the same streaming gate as file mentions); without a vocabulary, local destinations remain inert alt text. A load or decode failure replaces the image with its authored alt text, or the original destination when alt is empty. Changing the image source permits a fresh load. While a reply streams, it freezes completed blocks, advances a top-level open fence by completed lines, and highlights that fence from saved Shiki grammar state. Completed token lines enter fixed-size React groups, so later chunks reconcile only the growing group; an unchanged fence retains that DOM when the final full parse resolves cross-document syntax. `TerminalBlock`, `ReadBlock`, `DiffBlock`, `SearchBlock`, and `WebBlock` render the matching tool-result intent with copy controls, overflow handling, and ANSI processing where applicable. `JsonTree` and `JsonBlock` inspect JSON values read-only, while `projectUserText` projects sent user text into inline plain runs and reference chips for the message bubble and queue rows. When supplied with `UserTextReferences`, file and skill references become keyboard-accessible preview buttons using the same hover and focus styling as prose file links; the first pointer click can open a preview, while subsequent clicks and existing text selections retain native selection handling. Keyboard activation opens previews even when text is selected.
 
+`DiffBlock` compares the old and new content by line. It shows actual additions and deletions with up to three neutral context lines on each side, separates distant changes with `⋯`, and excludes shared context from both summary and footer totals. Search stops beyond 256 line additions/deletions per fragment; those fragments display and count the complete old and new contents as a coarse replacement, including shared lines. Copy includes the full displayed diff with its prefixes. A final newline is treated as a terminator; differences only in the presence of a final newline are not displayed.
 
 `JsonTree` clamps collapsed strings to `collapsedStringLines` (three by default). Expanded strings show raw text, retain sibling commas, and fit within the window and outer scrolling containers. Resize and ancestor-scroll events update that limit. Row copy feedback updates independently of JSON value rendering; pending clipboard writes cannot update a different row or an unmounted tree.
 
@@ -143,6 +144,7 @@ None; this package neither assembles nor sends a provider request.
 
 These limits define how the atoms behave at the edges; they are current package constraints, not a component roadmap.
 
+- **Diff search is bounded, input processing is linear** — the edit-distance limit trades precise alignment for a coarse replacement on heavily changed fragments. Normalization, fallback rows, and copied output still scale with input size; the height cap limits visible rows, not those allocations.
 - **Streaming defers cross-boundary reference resolution** — a reference-style link or footnote whose definition sits on the other side of the incremental freeze boundary renders as literal text while the reply streams; the settled full parse at finalize resolves it.
 - **A long highlighted fence retains its complete token DOM** — streaming avoids re-parsing, re-tokenizing, and reconciling the completed prefix, but it does not discard old colors or virtualize token spans. Final DOM cardinality therefore still follows the fence's token count; nested/container fences and a pathological single long line remain on the general tail path.
 - **Glyph-level icons are redrawn approximations** — the fish logo and the sparkle mark come from font glyphs whose vector geometry is not exportable from the local design data; hand-authored recreations stand in until an exact export path exists.
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index 194d8e994d..b23c87f786 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -73,6 +73,7 @@ kind: "package-library"
 
 `MarkdownText` 渲染不可信的 GFM 与 TeX 公式、阻止不安全的链接与图片，并可把已解析的文件提及转换为显式控件。当 owner 传入 `pathImages` 词表时，本地媒体路径的图片目标只在落定渲染阶段重写为可展示 URL（与 file mentions 相同的流式门）；不传词表时本地目标保持惰性 alt 文本。加载或解码失败后，图片替换为作者的 alt 文本；alt 为空时显示原始目标路径。图片源变化后可重新加载。回复流式输出时，它冻结已完成的块、按已完成行推进顶层未闭合 fence，并从保存的 Shiki grammar state 为该 fence 增量高亮。已完成的 token 行进入固定大小的 React 分组，后续分片只 reconcile 正在增长的分组；最终全量解析解决跨文档语法时，未变化的 fence 会保留该 DOM。`TerminalBlock`、`ReadBlock`、`DiffBlock`、`SearchBlock` 与 `WebBlock` 把对应的工具结果意图渲染为带复制控件、溢出处理及适用时 ANSI 处理的卡片。`JsonTree` 与 `JsonBlock` 以只读方式检查 JSON 值；`projectUserText` 把已发送的用户文本投影为行内普通文本段与引用 chip，供消息气泡和排队行使用。 传入 `UserTextReferences` 时，文件和 skill 引用成为支持键盘操作的预览按钮，复用正文文件链接的悬停和聚焦样式；第一次指针点击可以打开预览，后续点击和已有选区保留原生选择行为。键盘激活在存在选区时仍可打开预览。
 
+`DiffBlock` 按行比较新旧内容。它显示实际增删行及两侧最多三行中性上下文，用 `⋯` 分隔远距离改动，摘要和底部统计都不计入共享上下文。若一个片段需要超过 256 次行新增或删除，则停止精确比较；该片段按完整新旧内容显示和统计为粗粒度替换，包含共享行。复制包含完整显示 diff 及其前缀。末尾换行视为行终止符；仅末尾换行不同不会显示为改动。
 
 `JsonTree` 把折叠字符串限制为 `collapsedStringLines` 行（默认三行）。展开后显示原始文本、保留同级逗号，并限制在窗口与外层滚动容器内；尺寸变化和祖先滚动事件会更新此限制。行复制反馈独立于 JSON 值渲染更新；尚未完成的剪贴板写入不会更新另一行或已卸载的树。
 
@@ -143,6 +144,7 @@ kind: "package-library"
 
 这些限制说明原子组件在边缘情况下的行为；它们是当前包约束，不是组件路线图。
 
+- **Diff 搜索有上限，输入处理仍为线性**：编辑距离上限使大量改动的片段采用粗粒度替换，不再精确对齐。规范化、回退行及复制内容仍随输入大小增长；高度限制只约束可见行数，不限制这些分配。
 - **流式期间跨边界引用解析被推迟**：定义落在增量冻结边界另一侧的引用式链接或脚注，在回复流式输出期间渲染为字面文本；定稿时的全量解析会将其解析。
 - **长高亮 fence 会保留完整 token DOM**：流式路径避免重新解析、重新 tokenize 和 reconcile 已完成前缀，但不会丢弃旧颜色或虚拟化 token span。因此最终 DOM 数量仍随 fence 的 token 数增长；嵌套／容器内 fence 与病态的单个超长行仍走通用尾部路径。
 - **字形级图标是重新绘制的近似版本**：鱼形标志与闪光标记来自字体字形，而本地设计数据无法导出其矢量几何；在获得精确导出路径前，使用手工重建版本代替。
diff --git a/packages/client/ui-primitives/package.json b/packages/client/ui-primitives/package.json
index 4c02a1ced6..98677069b0 100644
--- a/packages/client/ui-primitives/package.json
+++ b/packages/client/ui-primitives/package.json
@@ -28,6 +28,7 @@
     "@deepseek-ai/cordis": "workspace:^",
     "react": "^18.2.0",
     "clsx": "^2.0.0",
+    "diff": "^9.0.0",
     "react-dom": "^18.2.0",
     "anser": "^2.3.5",
     "katex": "^0.16.47",
diff --git a/packages/client/ui-primitives/src/DiffBlock.module.css b/packages/client/ui-primitives/src/DiffBlock.module.css
index 4f64417d0c..dd1d621aeb 100644
--- a/packages/client/ui-primitives/src/DiffBlock.module.css
+++ b/packages/client/ui-primitives/src/DiffBlock.module.css
@@ -76,6 +76,14 @@
   color: var(--dsw-alias-state-success-primary);
 }
 
+.context {
+  color: var(--dsw-alias-label-secondary);
+}
+
+.context::before {
+  content: '  ';
+}
+
 .expand {
   display: block;
   width: 100%;
diff --git a/packages/client/ui-primitives/src/DiffBlock.tsx b/packages/client/ui-primitives/src/DiffBlock.tsx
index 01a080bbfc..339c4a4af1 100644
--- a/packages/client/ui-primitives/src/DiffBlock.tsx
+++ b/packages/client/ui-primitives/src/DiffBlock.tsx
@@ -1,5 +1,6 @@
 import { useCallback, useMemo, useState } from 'react'
 import clsx from 'clsx'
+import { structuredPatch } from 'diff'
 import { FoldToggle } from './FoldToggle.tsx'
 import { writeClipboard } from './clipboard.ts'
 import css from './DiffBlock.module.css'
@@ -14,9 +15,9 @@ export const DEFAULT_DIFF_MAX_LINES = 16
 export interface DiffHunk {
   /** The changed file's path, drawn verbatim as the hunk's header (the tool's model-facing path). */
   path: string
-  /** Prior content, or `null` for a new file / an overwrite (nothing on the removed side). */
+  /** Prior content including context, or `null` when no prior content is available. */
   oldText: string | null
-  /** Content after the change (the added side). */
+  /** Content after the change, including any shared context. */
   newText: string
 }
 
@@ -44,7 +45,7 @@ export interface DiffBlockLabels {
 
 /** A single rendered body line and its role, so the height cap slices a flat list. */
 interface DiffRow {
-  kind: 'path' | 'del' | 'add' | 'gap'
+  kind: 'path' | 'del' | 'add' | 'context' | 'gap'
   text: string
 }
 
@@ -59,34 +60,48 @@ const ROW_CLASS: Record<DiffRow['kind'], string | undefined> = {
   path: css.path,
   del: css.del,
   add: css.add,
+  context: css.context,
   gap: css.gap,
 }
 
+/** Bound synchronous edit-graph search; one replacement consumes two edits. */
+const MAX_DIFF_EDIT_LENGTH = 256
+
+/** Derive exact local patches or a whole-fragment replacement when search exceeds the limit. */
+function localHunks(diff: DiffHunk) {
+  const oldLines = contentLines(diff.oldText ?? '')
+  const newLines = contentLines(diff.newText)
+  const normalize = (lines: string[]): string => lines.map(line => `${line}\n`).join('')
+  return structuredPatch('', '', normalize(oldLines), normalize(newLines),
+    undefined, undefined, { context: 3, maxEditLength: MAX_DIFF_EDIT_LENGTH })?.hunks
+    ?? [{ lines: [...oldLines.map(line => `-${line}`), ...newLines.map(line => `+${line}`)] }]
+}
+
 /**
- * Total added/removed line counts across hunks — the same numbers the footer
- * prints, exported so a summary row can show them without rebuilding the body.
- * Every old-side line counts toward `removed` and every new-side line toward
- * `added`, under {@link contentLines}'s terminator rule.
+ * Count displayed additions and deletions. Exact patches exclude shared context;
+ * comparisons exceeding the edit limit count both complete fragments as replaced.
+ * Text follows {@link contentLines}'s terminator rule.
  * @param diffs - the hunks to count.
- * @returns the +/- totals.
+ * @returns the +/- totals for summaries and the card footer.
  */
 export function diffTotals(diffs: DiffHunk[]): { added: number; removed: number } {
   let added = 0
   let removed = 0
   for (const diff of diffs) {
-    if (diff.oldText !== null) removed += contentLines(diff.oldText).length
-    added += contentLines(diff.newText).length
+    for (const hunk of localHunks(diff)) {
+      for (const line of hunk.lines) {
+        if (line.startsWith('+')) added++
+        if (line.startsWith('-')) removed++
+      }
+    }
   }
   return { added, removed }
 }
 
 /**
- * Flatten the hunks into the body's rows plus the footer counts. A path header
- * opens each new file; a same-file second hunk (a scattered edit) opens with a
- * `⋯` gap instead of repeating the path. The +/- totals are
- * {@link diffTotals}'s. The file count is of DISTINCT paths, matching the TUI
- * diff card's footer, so two hunks in one file read as `1 file` on both front
- * ends.
+ * Flatten local patches into rows and count only added and removed lines.
+ * A path header opens each new file. A `⋯` gap separates consecutive same-file
+ * fragments and distant patches within a fragment. File counts use distinct paths.
  * @param diffs - the hunks to render.
  * @returns the body rows, the +/- totals, and the distinct-file count.
  */
@@ -99,16 +114,20 @@ function buildRows(diffs: DiffHunk[]): { rows: DiffRow[]; added: number; removed
     if (diff.path !== prevPath) rows.push({ kind: 'path', text: diff.path })
     else rows.push({ kind: 'gap', text: '⋯' })
     prevPath = diff.path
-    if (diff.oldText !== null) {
-      for (const line of contentLines(diff.oldText)) {
-        rows.push({ kind: 'del', text: line })
+    for (const [index, hunk] of localHunks(diff).entries()) {
+      if (index > 0) rows.push({ kind: 'gap', text: '⋯' })
+      for (const line of hunk.lines) {
+        const kind = line.startsWith('-') ? 'del' : line.startsWith('+') ? 'add' : 'context'
+        rows.push({ kind, text: line.slice(1) })
       }
     }
-    for (const line of contentLines(diff.newText)) {
-      rows.push({ kind: 'add', text: line })
-    }
   }
-  return { rows, ...diffTotals(diffs), files: paths.size }
+  return {
+    rows,
+    added: rows.filter(row => row.kind === 'add').length,
+    removed: rows.filter(row => row.kind === 'del').length,
+    files: paths.size,
+  }
 }
 
 /**
@@ -127,9 +146,8 @@ function contentLines(text: string): string[] {
 }
 
 /**
- * The diff text a reader copies: each row's `-`/`+`/path/gap prefix and its
- * content, exactly what the card shows. The removed and added blocks are the
- * change; the path headers keep a multi-file copy attributable.
+ * Copy the full local diff, including folded rows: removed/added lines have
+ * `- `/`+ ` prefixes, context has two spaces, and paths and gaps stay verbatim.
  * @param rows - the flattened body rows.
  * @returns the diff as plain text.
  */
@@ -138,6 +156,7 @@ function copyText(rows: DiffRow[]): string {
     switch (row.kind) {
       case 'del': return `- ${row.text}`
       case 'add': return `+ ${row.text}`
+      case 'context': return `  ${row.text}`
       case 'path': return row.text
       case 'gap': return row.text
       /* v8 ignore next -- closed-union backstop; only reached if a row kind is forged */
diff --git a/packages/client/ui-primitives/src/icons/index.tsx b/packages/client/ui-primitives/src/icons/index.tsx
index a7bf608e47..f0e80410e3 100644
--- a/packages/client/ui-primitives/src/icons/index.tsx
+++ b/packages/client/ui-primitives/src/icons/index.tsx
@@ -518,11 +518,11 @@ export const IconUserOutline16 = ({ size = 16, className }: IconProps) => (
   </svg>
 )
 
-/** ic_ds_send_outline_16 */
-export const IconSendOutline16 = ({ size = 16, className }: IconProps) => (
-  <svg width={size} height={size} className={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+/** ic_ds_paper_plane_outline_14 */
+export const IconPaperPlaneOutline14 = ({ size = 14, className }: IconProps) => (
+  <svg width={size} height={size} className={className} viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
     <path
-      d="M8.3125 0.981587C8.66767 1.0545 8.97902 1.20558 9.2627 1.43374C9.48724 1.61438 9.73029 1.85933 9.97949 2.10854L14.707 6.83608L13.293 8.25014L9 3.95717V15.0431H7V3.95717L2.70703 8.25014L1.29297 6.83608L6.02051 2.10854C6.26971 1.85933 6.51277 1.61438 6.7373 1.43374C6.97662 1.24126 7.28445 1.04542 7.6875 0.981587C7.8973 0.94841 8.1031 0.956564 8.3125 0.981587Z"
+      d="M11.8249 1.11733C12.4401 0.929305 13.0795 1.42149 13.0238 2.08968L12.2321 11.5935C12.1751 12.2735 11.4312 12.6646 10.8386 12.3263L7.99539 10.7011L6.0967 12.7005L6.07413 12.7248L6.04808 12.7465C5.55601 13.1565 4.80867 12.8069 4.80833 12.1665V8.69211C4.80843 8.44469 4.90686 8.20727 5.08181 8.0323L9.79684 3.31641L2.46775 6.6988L4.10251 7.35253L3.67364 8.42559L1.57874 7.5878V7.5852C0.807611 7.2988 0.757207 6.21577 1.5145 5.86622L11.7025 1.16421L11.8249 1.11733ZM5.96474 11.1603L6.9614 10.1107L5.96474 9.54118V11.1603ZM6.32937 8.41864L11.1086 11.149L11.791 2.95698L6.32937 8.41864Z"
       fill="currentColor"
     />
   </svg>
diff --git a/packages/client/ui-primitives/tests/diff-block.client.spec.tsx b/packages/client/ui-primitives/tests/diff-block.client.spec.tsx
index aad3fecf5e..391fbfda51 100644
--- a/packages/client/ui-primitives/tests/diff-block.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/diff-block.client.spec.tsx
@@ -5,6 +5,7 @@ import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { ComponentProps } from 'react'
 import { DEFAULT_DIFF_MAX_LINES, DiffBlock as LocalizedDiffBlock, type DiffHunk } from '../src/index.ts'
 import { diffBlockLabels } from './labels.client.ts'
+import { diffTotals } from '../src/DiffBlock.tsx'
 
 function DiffBlock(props: Omit<ComponentProps<typeof LocalizedDiffBlock>, 'labels'>) {
   return <LocalizedDiffBlock {...props} labels={diffBlockLabels} />
@@ -94,6 +95,80 @@ describe('DiffBlock structure', () => {
   })
 })
 
+describe('DiffBlock local changes', () => {
+  it.each([128, 129])('renders and copies %i replacements with bounded comparison', async (count) => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    const oldLines = ['shared context', ...Array.from({ length: count }, (_, i) => `old ${i}`)]
+    const newLines = ['shared context', ...Array.from({ length: count }, (_, i) => `new ${i}`)]
+    const diffs = [{ path: 'large.txt', oldText: oldLines.join('\n'), newText: newLines.join('\n') }]
+    const total = count === 128 ? count : count + 1
+    render(<DiffBlock diffs={diffs} maxLines={1000} />)
+    expect(diffTotals(diffs)).toEqual({ added: total, removed: total })
+    expect(screen.getByText(`└ +${total} -${total} · 1 file`)).toBeTruthy()
+    await act(async () => { fireEvent.click(screen.getByRole('button', { name: '复制' })) })
+    expect(writeText).toHaveBeenCalledWith(count === 128
+      ? ['large.txt', '  shared context', ...oldLines.slice(1).map(line => `- ${line}`), ...newLines.slice(1).map(line => `+ ${line}`)].join('\n')
+      : ['large.txt', ...oldLines.map(line => `- ${line}`), ...newLines.map(line => `+ ${line}`)].join('\n'))
+  })
+
+  it('keeps a sparse edit exact in a ten-thousand-line fragment', () => {
+    const before = Array.from({ length: 10000 }, (_, i) => `line ${i}`)
+    const after = [...before]
+    after[5000] = 'changed'
+    const diffs = [{ path: 'sparse.txt', oldText: before.join('\n'), newText: after.join('\n') }]
+    const { container } = render(<DiffBlock diffs={diffs} />)
+    expect(diffTotals(diffs)).toEqual({ added: 1, removed: 1 })
+    expect(bodyRows(container)).toEqual([
+      'sparse.txt', 'line 4997', 'line 4998', 'line 4999', 'line 5000', 'changed',
+      'line 5001', 'line 5002', 'line 5003',
+    ])
+  })
+
+  it('copies shared context once and counts only a changed line', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    const diffs = [{ path: 'settings.ts', oldText: 'start\nmode = 1\nend', newText: 'start\nmode = 2\nend' }]
+    render(<DiffBlock diffs={diffs} />)
+    expect(screen.getAllByText('start')).toHaveLength(1)
+    expect(screen.getAllByText('end')).toHaveLength(1)
+    expect(screen.getByText('└ +1 -1 · 1 file')).toBeTruthy()
+    expect(diffTotals(diffs)).toEqual({ added: 1, removed: 1 })
+    await act(async () => { fireEvent.click(screen.getByRole('button', { name: '复制' })) })
+    expect(writeText).toHaveBeenCalledWith('settings.ts\n  start\n- mode = 1\n+ mode = 2\n  end')
+  })
+
+  it('keeps three neutral context lines around distant changes and separates hunks', () => {
+    const before = Array.from({ length: 50 }, (_, i) => `item ${i}`)
+    const after = before.map((line, i) => i === 10 || i === 40 ? `changed ${i}` : line)
+    const { container } = render(<DiffBlock diffs={[{
+      path: 'items.txt', oldText: before.join('\n'), newText: after.join('\n'),
+    }]} maxLines={100} />)
+    expect(bodyRows(container)).toEqual([
+      'items.txt', 'item 7', 'item 8', 'item 9', 'item 10', 'changed 10',
+      'item 11', 'item 12', 'item 13', '⋯', 'item 37', 'item 38', 'item 39',
+      'item 40', 'changed 40', 'item 41', 'item 42', 'item 43',
+    ])
+    expect(changeRows(container)).toEqual(['item 10', 'changed 10', 'item 40', 'changed 40'])
+    expect(screen.getByText('└ +2 -2 · 1 file')).toBeTruthy()
+  })
+
+  it.each([
+    ['a\nx\na\ny\na', 'a\nx\na\nz\na', 1, 1],
+    ['a\nb', 'a\nx\nb', 1, 0],
+    ['a\nx\nb', 'a\nb', 0, 1],
+    ['same\n', 'same', 0, 0],
+    ['same', 'same', 0, 0],
+    ['', '', 0, 0],
+    ['a\n\nb', 'a\nb', 0, 1],
+  ])('counts ordered changes in %j → %j', (oldText, newText, added, removed) => {
+    const diffs = [{ path: 'a.txt', oldText, newText }]
+    render(<DiffBlock diffs={diffs} />)
+    expect(diffTotals(diffs)).toEqual({ added, removed })
+    expect(screen.getByText(`└ +${added} -${removed} · 1 file`)).toBeTruthy()
+  })
+})
+
 describe('DiffBlock footer', () => {
   it('counts added and removed lines and one file', () => {
     const diffs: DiffHunk[] = [{ path: 'a.ts', oldText: 'a\nb', newText: 'c' }]
diff --git a/packages/client/ui-primitives/tests/icons.client.spec.tsx b/packages/client/ui-primitives/tests/icons.client.spec.tsx
index 98f56c5d8f..d380e7e422 100644
--- a/packages/client/ui-primitives/tests/icons.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/icons.client.spec.tsx
@@ -4,7 +4,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 import * as primitives from '@deepseek-ai/dsh-client-ui-primitives'
 import {
   IconAlarmClockOutline16, IconApiOutline14, IconArchiveOutline20, IconFolderClose16,
-  IconGoalOutline16, IconSendOutline16,
+  IconGoalOutline16, IconSendOutline14,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 
 afterEach(cleanup)
@@ -40,7 +40,7 @@ describe('ic_ds_ icon set', () => {
   })
 
   it('size and className props land on the root svg', () => {
-    const { container } = render(<IconSendOutline16 size={20} className="x" />)
+    const { container } = render(<IconSendOutline14 size={20} className="x" />)
     const svg = container.querySelector('svg')!
     expect(svg.getAttribute('width')).toBe('20')
     expect(svg.getAttribute('height')).toBe('20')
diff --git a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml b/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
index 9eab9c47f9..69a59f4317 100644
--- a/packages/client/ui-sidebar-documentpreview/README.i18n.yaml
+++ b/packages/client/ui-sidebar-documentpreview/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 packages/client/ui-sidebar-documentpreview/README.md
-README.md: e3659ed08a7c82f7c5ef314806ea07262f421caa
-README.zh.md: 29393ed6b8694ac8fd8f68f398c12e633e237351
+README.md: 3da629129f36d18a20eef74be8f96a1455d532f3
+README.zh.md: 6f1eb7eef1f690ebdfdf38cfdd1f62b1314d7d66
diff --git a/packages/client/ui-sidebar-documentpreview/README.md b/packages/client/ui-sidebar-documentpreview/README.md
index e3659ed08a..3da629129f 100644
--- a/packages/client/ui-sidebar-documentpreview/README.md
+++ b/packages/client/ui-sidebar-documentpreview/README.md
@@ -27,10 +27,10 @@ Preview readable files in the right Sidebar and choose among registered renderer
 ## What it registers
 
 - **The type** — `ctx.sidebarRightTabs.register(...)` with id `@deepseek-ai/dsh-client-ui-sidebar-documentpreview` (this implementation's identity in the tab system, and the key its body registers under), kind `text`, pattern `dsh-resource://file/**`, band `fallback`. `canOpen` accepts only Session addresses, whose paths may be relative or absolute; bare `absolute` addresses are not claimed. A type registered at the `extension` or `builtin` band for a narrower pattern (say `*.png`) takes those addresses; other supported files land here. The whole address is the content identity, so two files with one name in different directories, or one path under two sessions, are two tabs; the decoded basename is the tab title, and the keyed `sidebar.right.pane.tab.title` seat places its extension-specific `FileTypeIcon` before that title.
-- **The body** — the keyed `sidebar.right.pane.tab` seat under the type's id. Its fixed header shows the Host's absolute path when available, otherwise the requested path; directories use tertiary label colour, the name uses primary label colour, and a clipped path retains and fades toward its final segment while its tooltip exposes the full value. A dropdown selects among matching renderers and plain text. A wrap toggle appears only when the selected renderer declares `wrap: true`; its glyph describes the mode the click selects, and the per-tab preference starts on. Reload stays in this header, not the Sidebar's tab strip. The body reaches every pane edge; each renderer owns its content inset and may own an inner scrollport. This intentionally differs from the Files tab's 2px right-side scrollbar offset: previews keep the full pane width so edge-to-edge HTML and code scrollports end at the pane edge.
+- **The body** — the keyed `sidebar.right.pane.tab` seat under the type's id. Its fixed header shows the Host's absolute path when available, otherwise the requested path; directories use tertiary label colour, the name uses primary label colour, and a clipped path retains and fades toward its final segment while its tooltip exposes the full value. A dropdown selects among matching renderers and plain text; a suffix declared binary (bitmap images, PDF) drops the plain-text fallback, and a single remaining candidate renders no viewer control at all. A known binary container suffix with no registered renderer (audio, video, archives, office documents) shows an unsupported empty state under the path header — the file-type icon and one explanatory line — and never issues a read. A wrap toggle appears only when the selected renderer declares `wrap: true`; its glyph describes the mode the click selects, and the per-tab preference starts on. Reload stays in this header, not the Sidebar's tab strip. The body reaches every pane edge; each renderer owns its content inset and may own an inner scrollport. This intentionally differs from the Files tab's 2px right-side scrollbar offset: previews keep the full pane width so edge-to-edge HTML and code scrollports end at the pane edge.
 - **Shared loading and view state**, session-scoped and bucketed by tab id. The store holds accumulated pages or complete bytes, read and observed versions, loading/failure state, renderer choice, scroll offset, wrap, and the answered navigation revision. The ordinary inject face calls Remote readers and writes through declared store actions. Reloads and loading-mode changes retire older requests; the tab's abort signal forgets its state.
 
-Document implementations register metadata with `ctx.documentPreviews.register({ id, extensions, priority, title, loading, wrap? })` and a body under the same `id` in the keyed, Session-scoped `sidebar.right.tab.document` child slot. Own both registrations with effects and wait for the child slot through `ctx.slots.inject`. Bodies receive `resourceAddress`, prepared `content`, `wrap`, `scrollportRef`, and the standard `useTabInfo`/`useResource` hooks; they do not receive a custom resource loader. A renderer that owns an inner scrolling element attaches `scrollportRef` to it, and the owner returns to the shared body when that element unmounts. Metadata declares `loading: 'text-pages'` or `'bytes-complete'`. The registry retains all matching alternatives: `extension` (the default) ranks above `builtin`, then longer suffixes rank first, then registration order. The dropdown preserves a selected implementation while it remains available; removing it selects the next candidate. Builtin bodies use these same registrations.
+Document implementations register metadata with `ctx.documentPreviews.register({ id, extensions, binaryExtensions?, priority, title, loading, wrap? })` and a body under the same `id` in the keyed, Session-scoped `sidebar.right.tab.document` child slot. `binaryExtensions` names the suffixes among `extensions` whose bytes are not readable text; a file matching one loses the plain-text fallback among its viewer choices. Own both registrations with effects and wait for the child slot through `ctx.slots.inject`. Bodies receive `resourceAddress`, prepared `content`, `wrap`, `scrollportRef`, and the standard `useTabInfo`/`useResource` hooks; they do not receive a custom resource loader. A renderer that owns an inner scrolling element attaches `scrollportRef` to it, and the owner returns to the shared body when that element unmounts. Metadata declares `loading: 'text-pages'` or `'bytes-complete'`. The registry retains all matching alternatives: `extension` (the default) ranks above `builtin`, then longer suffixes rank first, then registration order. The dropdown preserves a selected implementation while it remains available; removing it selects the next candidate. Builtin bodies use these same registrations.
 
 <a id="addresses"></a>
 ## Addresses
@@ -49,11 +49,11 @@ The body reads its record, navigation and lifetime through `useTabInfo().tab`. `
 
 HTML fills the body edge to edge in a Blob iframe with exactly `sandbox="allow-scripts"`, without `allow-same-origin`; scripts cannot access the parent application's origin or file reader. The renderer loads directly declared relative `.js` classic scripts and `.css` stylesheets through its ordinary inject callback to `remote.workspaceFiles.readRelated`, with fixed safety limits of 4 MiB per asset, 32 MiB total, and 64 distinct assets. Host code resolves the related path; `rpc.ts` decodes the returned bytes. Inside the renderer, base64 is used only to embed the iframe bootstrap payload in script text. A `<base href>` leaves dependency resolution to the browser, as do HTTPS resources. Local module imports, CSS `url()`/`@import`, and dynamic `fetch` do not use Host file access. Read failures, invalid UTF-8, or exceeded limits fail the preview rather than publishing a partial asset package. Replacing or unmounting the document releases its Blob URL.
 
-PNG, JPEG, GIF, WebP, BMP, ICO, and SVG render through Blob URLs in an `<img>` static-image context. The image keeps its intrinsic CSS-pixel dimensions; a smaller image centres in the shared scroller, and larger dimensions scroll on either axis. The renderer provides neither zoom nor drag-to-pan. SVG markup never enters the application DOM or an iframe, so its scripts cannot execute or reach the parent page. Replacing or unmounting the image revokes its Blob URL.
+PNG, JPEG, GIF, WebP, BMP, ICO, and SVG render through Blob URLs in an `<img>` static-image context, rounded inside a 12px inset. A wider image scales down to the pane's width at its intrinsic aspect ratio, a smaller image centres at its intrinsic CSS-pixel dimensions, and a taller image scrolls vertically. The renderer provides neither zoom nor drag-to-pan. SVG markup never enters the application DOM or an iframe, so its scripts cannot execute or reach the parent page. Replacing or unmounting the image revokes its Blob URL.
 
 Shared copy comes from `sidebarDocumentPreview`; each builtin renderer owns its localized labels.
 
-Initial reads, additional pages, and HTML/PDF/image preparation share a loading indicator that respects reduced-motion preferences. Loaded pages stay visible while another page loads. PDF pages form one vertical, width-fitted sequence and render lazily near the viewport. Code previews show source line numbers by default without including them in copied text; plain text uses the same font size and line height as code. Code sits on the pane's own background rather than the chat card's fill; its banner is adjacent to a full-height inner scrollport, so both scrollbars begin below the copy control.
+Initial reads, additional pages, and HTML/PDF/image preparation share an icon-only loading spinner that exposes its label to assistive technology and respects reduced-motion preferences; every wait before content exists centres the spinner in the pane, so opening a file shows one spinner in one position until the body appears. Loaded pages stay visible while another page loads. PDF pages fill the pane's width edge to edge as one vertical sequence and render lazily near the viewport; an unrendered page holds its place as a quiet 3:4 placeholder block. Code previews show source line numbers by default without including them in copied text; plain text uses the same font size and line height as code. Code sits on the pane's own background rather than the chat card's fill; its banner is adjacent to a full-height inner scrollport, so both scrollbars begin below the copy control.
 
 <a id="navigation"></a>
 ## Navigation
@@ -74,7 +74,7 @@ No direct effect; what the user reads here never enters a model request.
 <a id="known-limitations-and-deferred-work"></a>
 - **Preview, not editing.** The viewers provide no file editing or shared search interface; a directory address fails with `not-regular-file`. Unknown extensions use the plain-text reader and remain subject to its UTF-8/NUL checks.
 - **Sequential text and bounded complete files.** Deep source lines require the preceding pages; PDF, HTML, and images require a complete result within the Host's `maxFileBytes` cap.
-- **Byte-view scroll state is not restored.** PDF, HTML, and images can return to the top when their renderer remounts or reloads; image horizontal position is never restored, and HTML iframe scrolling belongs to its opaque browsing context.
+- **Byte-view scroll state is not restored.** PDF, HTML, and images can return to the top when their renderer remounts or reloads; images fit the pane's width and never scroll horizontally, and HTML iframe scrolling belongs to its opaque browsing context.
 - **Finite local HTML dependencies.** Only direct classic `.js` and stylesheet `.css` references are packed. Browser-resolved resources retain browser origin and network restrictions; no runtime file-read bridge is exposed to the iframe.
 - **Package-local wrap glyphs.** `IconWrapFill16` and `IconNowrapFill16` live in `src/client/icons.tsx` until the shared icon set carries them; their props already match the shared icon contract.
 - **Scroll writes are unthrottled.** Every scroll event records its offset in the store; the line blocks are memoized so the resulting re-render hands React the same elements back.
diff --git a/packages/client/ui-sidebar-documentpreview/README.zh.md b/packages/client/ui-sidebar-documentpreview/README.zh.md
index 29393ed6b8..6f1eb7eef1 100644
--- a/packages/client/ui-sidebar-documentpreview/README.zh.md
+++ b/packages/client/ui-sidebar-documentpreview/README.zh.md
@@ -27,10 +27,10 @@ kind: "package-reference"
 ## 注册了什么
 
 - **类型** —— `ctx.sidebarRightTabs.register(...)`，id 为 `@deepseek-ai/dsh-client-ui-sidebar-documentpreview`（这个实现在 tab 系统中的身份，也是其正文注册所用的键），kind `text`，pattern `dsh-resource://file/**`，档位 `fallback`。`canOpen` 只接受 Session 地址，其中路径可为相对或绝对路径；不认领裸 `absolute` 地址。在 `extension` 或 `builtin` 档以更窄 pattern（比如 `*.png`）注册的类型接走那些地址；其他受支持文件落到这里。整个地址就是内容身份，所以不同目录下同名的两个文件、或同一路径在两个会话之下，是两个 tab；解码后的 basename 是 tab 标题，keyed slot `sidebar.right.pane.tab.title` 会在标题前放置按扩展名选择的 `FileTypeIcon`。
-- **正文** —— keyed slot `sidebar.right.pane.tab`，键为类型的 id。固定头部在可用时显示 Host 的绝对路径，否则显示请求路径；目录使用三级标签色，文件名使用一级标签色，路径过长时保留末段并向开头淡出，提示中仍提供完整值。下拉菜单可在匹配的渲染器与纯文本间切换。仅当所选渲染器声明 `wrap: true` 时显示换行开关；图标表示点击后切换到的模式，该偏好按 tab 保存，初始开启。重新载入仍在此头部，不放入 Sidebar 的 tab 条。正文贴合格的每条边，各渲染器自行提供内容留白，并可拥有内部滚动区。这与 Files tab 右侧预留 2px 滚动条间距的布局有意不同：Preview 使用格的完整宽度，使贴边 HTML 与代码滚动区终止于格的边缘。
+- **正文** —— keyed slot `sidebar.right.pane.tab`，键为类型的 id。固定头部在可用时显示 Host 的绝对路径，否则显示请求路径；目录使用三级标签色，文件名使用一级标签色，路径过长时保留末段并向开头淡出，提示中仍提供完整值。下拉菜单可在匹配的渲染器与纯文本间切换；声明为二进制的后缀（位图图片、PDF）不提供纯文本兜底，只剩一个候选时完全不渲染查看器控件。已知的二进制容器后缀（音频、视频、压缩包、office 文档）没有注册渲染器时，在路径头部下方显示不支持预览的空态——文件类型图标加一行说明——并且不会发起读取。仅当所选渲染器声明 `wrap: true` 时显示换行开关；图标表示点击后切换到的模式，该偏好按 tab 保存，初始开启。重新载入仍在此头部，不放入 Sidebar 的 tab 条。正文贴合格的每条边，各渲染器自行提供内容留白，并可拥有内部滚动区。这与 Files tab 右侧预留 2px 滚动条间距的布局有意不同：Preview 使用格的完整宽度，使贴边 HTML 与代码滚动区终止于格的边缘。
 - **共享加载与视图状态**，会话作用域、按 tab id 分桶。store 持有累计页或完整字节、读取与观察版本、加载/失败状态、渲染器选择、滚动位置、换行和已响应的导航 revision。普通 inject face 调用 Remote 读取，并经声明的 store action 写入。重新载入和加载模式变化会淘汰旧请求；tab 的中止信号清理其状态。
 
-文档实现在 `ctx.documentPreviews.register({ id, extensions, priority, title, loading, wrap? })` 注册元数据，并以相同 `id` 向 keyed、Session 作用域的子 slot `sidebar.right.tab.document` 注册正文。两处注册都由 effect 持有，通过 `ctx.slots.inject` 等待子 slot。正文接收 `resourceAddress`、准备好的 `content`、`wrap`、`scrollportRef` 和标准 `useTabInfo`/`useResource` 钩子，不接收自定义资源加载器。拥有内部滚动元素的渲染器把 `scrollportRef` 挂到该元素上；该元素卸载后，owner 恢复使用共享正文。元数据声明 `loading: 'text-pages'` 或 `'bytes-complete'`。注册表保留所有匹配备选：`extension`（默认）优先于 `builtin`，随后按更长的后缀、再按注册顺序排列。所选实现仍可用时，下拉选择保持不变；移除后选择下一个候选。内置正文也使用相同注册方式。
+文档实现在 `ctx.documentPreviews.register({ id, extensions, binaryExtensions?, priority, title, loading, wrap? })` 注册元数据，并以相同 `id` 向 keyed、Session 作用域的子 slot `sidebar.right.tab.document` 注册正文。`binaryExtensions` 列出 `extensions` 中字节不可按文本阅读的后缀；匹配这类后缀的文件在其查看器选项中不再提供纯文本兜底。两处注册都由 effect 持有，通过 `ctx.slots.inject` 等待子 slot。正文接收 `resourceAddress`、准备好的 `content`、`wrap`、`scrollportRef` 和标准 `useTabInfo`/`useResource` 钩子，不接收自定义资源加载器。拥有内部滚动元素的渲染器把 `scrollportRef` 挂到该元素上；该元素卸载后，owner 恢复使用共享正文。元数据声明 `loading: 'text-pages'` 或 `'bytes-complete'`。注册表保留所有匹配备选：`extension`（默认）优先于 `builtin`，随后按更长的后缀、再按注册顺序排列。所选实现仍可用时，下拉选择保持不变；移除后选择下一个候选。内置正文也使用相同注册方式。
 
 <a id="addresses"></a>
 ## 地址
@@ -49,11 +49,11 @@ tab 使用 `fileAddressFor` 构造的 Session 地址，携带相对或绝对路
 
 HTML 以贴合正文四边的 Blob iframe 运行，沙箱属性严格为 `sandbox="allow-scripts"`，不含 `allow-same-origin`；脚本无法访问父应用的源或文件读取接口。渲染器通过普通 inject 回调调用 `remote.workspaceFiles.readRelated`，加载直接声明的相对 `.js` 经典脚本和 `.css` 样式表；固定安全上限为单个资源 4 MiB、总计 32 MiB、64 个不同资源。Host 代码解析关联路径，`rpc.ts` 解码返回的字节。在渲染器内部，base64 仅用于把 iframe 引导载荷嵌入脚本文本。`<base href>` 将依赖解析交给浏览器，HTTPS 资源也由浏览器处理。本地模块 import、CSS `url()`/`@import` 和动态 `fetch` 不使用 Host 文件访问。读取失败、无效 UTF-8 或超出上限都使预览失败，不发布部分资源包。替换或卸载文档会释放其 Blob URL。
 
-PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `<img>` 静态图片上下文中渲染。图片保持固有 CSS 像素尺寸；小图在共享滚动区内居中，大图可沿任一轴滚动。渲染器既不提供缩放，也不提供拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此其中的脚本无法执行，也无法访问父页面。替换或卸载图片会撤销其 Blob URL。
+PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `<img>` 静态图片上下文中渲染，带 12px 内边距和圆角。宽图按固有纵横比缩小到面板宽度，小图按固有 CSS 像素尺寸居中，超高图纵向滚动。渲染器既不提供缩放，也不提供拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此其中的脚本无法执行，也无法访问父页面。替换或卸载图片会撤销其 Blob URL。
 
 共享文案来自 `sidebarDocumentPreview`；各内置渲染器拥有自己的本地化标签。
 
-首次读取、追加页及 HTML/PDF/图片准备共用加载指示器，并遵循减少动态效果偏好。下一页加载期间保留已显示的内容。PDF 页面组成一个纵向、适配宽度的连续序列，并在接近视口时惰性渲染。代码预览默认显示源码行号，但复制文本不包含行号；纯文本与代码使用相同字号和行高。代码直接坐在分栏自身的背景上，而不是会话卡片的填充色；复制条与占满剩余高度的内部滚动区相邻，因此横纵滚动条都从复制控件下方开始。
+首次读取、追加页及 HTML/PDF/图片准备共用仅图标的加载 spinner，其标签暴露给辅助技术，并遵循减少动态效果偏好；内容出现前的每个等待都把 spinner 居中在面板中，打开文件到正文出现始终是同一位置的一个 spinner。下一页加载期间保留已显示的内容。PDF 页面贴边占满面板宽度，组成一个纵向连续序列并在接近视口时惰性渲染；未渲染的页以安静的 3:4 占位块保持位置。代码预览默认显示源码行号，但复制文本不包含行号；纯文本与代码使用相同字号和行高。代码直接坐在分栏自身的背景上，而不是会话卡片的填充色；复制条与占满剩余高度的内部滚动区相邻，因此横纵滚动条都从复制控件下方开始。
 
 <a id="navigation"></a>
 ## 导航
@@ -74,7 +74,7 @@ PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 通过 Blob URL 在 `<img>` 静态
 <a id="known-limitations-and-deferred-work"></a>
 - **预览而非编辑。** 查看器不提供文件编辑或共享搜索接口；目录地址以 `not-regular-file` 失败。未知扩展名使用纯文本读取，仍受其 UTF-8/NUL 检查限制。
 - **文本顺序分页，完整文件受限。** 定位到较深处的源码行需要先加载此前各页；PDF、HTML 和图片必须取得 Host `maxFileBytes` 上限内的完整结果。
-- **字节视图不恢复滚动位置。** PDF、HTML 与图片的渲染器重新挂载或重新载入时可能回到顶部；图片的横向位置始终不恢复，HTML iframe 的滚动属于其不透明浏览上下文。
+- **字节视图不恢复滚动位置。** PDF、HTML 与图片的渲染器重新挂载或重新载入时可能回到顶部；图片适配面板宽度、不产生横向滚动，HTML iframe 的滚动属于其不透明浏览上下文。
 - **本地 HTML 依赖集合有限。** 只打包直接引用的经典 `.js` 脚本和 `.css` 样式表。浏览器解析的资源仍受浏览器源与网络规则限制；iframe 不获得运行时文件读取桥接。
 - **换行图标为包内自绘。** `IconWrapFill16` 与 `IconNowrapFill16` 住在 `src/client/icons.tsx`，直到共享图标集提供为止；它们的 props 已与共享图标契约一致。
 - **滚动写入未节流。** 每次滚动事件都把偏移记进 store；行块已 memo 化，于是由此引发的重渲染交还给 React 的是同一批元素。
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/LoadingIndicator.tsx b/packages/client/ui-sidebar-documentpreview/src/client/LoadingIndicator.tsx
index fff0ba2e3a..fd1db1e543 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/LoadingIndicator.tsx
+++ b/packages/client/ui-sidebar-documentpreview/src/client/LoadingIndicator.tsx
@@ -4,10 +4,16 @@ import clsx from 'clsx'
 import { IconLoadingOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import css from './LoadingIndicator.module.css'
 
-/** @param props - localized status label and optional placement style. @returns an animated, accessible loading status. */
-export function LoadingIndicator({ label, className }: { label: string; className?: string | undefined }): ReactNode {
-  return <span className={clsx(css.loading, className)} role="status" data-document-loading>
+/**
+ * @param props - localized status label, carried as the accessible name with
+ * no visible text, and optional placement style.
+ * @returns an animated, accessible loading status.
+ */
+export function LoadingIndicator({ label, className }: {
+  label: string
+  className?: string | undefined
+}): ReactNode {
+  return <span className={clsx(css.loading, className)} role="status" aria-label={label} data-document-loading>
     <span className={css.icon} aria-hidden="true"><IconLoadingOutline16 /></span>
-    <span>{label}</span>
   </span>
 }
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.module.css b/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.module.css
index 1e19b311ac..4c8fd719be 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.module.css
+++ b/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.module.css
@@ -217,14 +217,27 @@
   white-space: normal;
 }
 
+/* The whole pane before any content exists, so the line centres like the
+   empty states below instead of sitting in the corner. */
 .status {
   display: flex;
   flex-direction: column;
   gap: 8px;
-  align-items: flex-start;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  height: 100%;
   padding: 12px 10px;
 }
 
+/* The first read, centred in the still-empty body; loaded content replaces it. */
+.bodyLoading {
+  justify-content: center;
+  box-sizing: border-box;
+  width: 100%;
+  height: 100%;
+}
+
 .action {
   padding: 4px 10px;
   color: var(--dsw-alias-label-primary);
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.tsx b/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.tsx
index 3aaa51e367..9430ec53a8 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.tsx
+++ b/packages/client/ui-sidebar-documentpreview/src/client/TextPreview.tsx
@@ -24,8 +24,9 @@ import { LoadingIndicator } from './LoadingIndicator.tsx'
 import { hostFileOf } from './rpc.ts'
 import type { TextStore } from './store.ts'
 import type { DocumentContent } from './document/contract.ts'
-import { matchingDocumentPreviews } from './document/registry.ts'
+import { binaryDocumentPath, matchingDocumentPreviews } from './document/registry.ts'
 import type { DocumentPreviewDefinition } from './document/registry.ts'
+import { unviewableBinaryPath } from './document/unviewable.ts'
 import { PLAIN_BODY_ID } from './text/index.ts'
 import { loadedPages, lastLineLoaded, scrollToLine } from './text/lines.ts'
 import css from './TextPreview.module.css'
@@ -56,6 +57,23 @@ function usePathClipped(
   }, [box, text, path, shown])
 }
 
+/** The header's path: directories greyed, the final segment in full ink, faded when clipped. */
+function HeaderPath({ pathRef, pathTextRef, path }: {
+  pathRef: RefObject<HTMLDivElement>
+  pathTextRef: RefObject<HTMLSpanElement>
+  path: string
+}): ReactNode {
+  const { directory, name } = pathPartsOf(path)
+  return (
+    <div ref={pathRef} className={css.path} title={path} data-textpreview-path>
+      <span ref={pathTextRef} className={css.pathText}>
+        {directory !== '' && <span className={css.pathDirectory}>{directory}</span>}
+        <span className={css.pathName}>{name}</span>
+      </span>
+    </div>
+  )
+}
+
 /** Private registration inputs; the framework binds the registry source to useDocumentPreviews. */
 export interface TextPreviewInjected extends TextInjected {
   readonly hooks: { readonly documentPreviews: ObservableSnapshot<readonly DocumentPreviewDefinition[]> }
@@ -85,11 +103,14 @@ export function TextPreview({
   const file = useMemo(() => hostFileOf(tab.contentId), [tab.contentId])
   const state = useStore(s => s.byTab[tab.id])
   const definitions = useDocumentPreviews(value => value)
+  const unviewable = useMemo(() => unviewableBinaryPath(file.path), [file.path])
   const candidates = useMemo(() => {
     const matched = matchingDocumentPreviews(definitions, file.path)
+    if (matched.length > 0 && binaryDocumentPath(definitions, file.path)) return matched
+    if (matched.length === 0 && unviewable) return matched
     const fallback = definitions.find(definition => definition.id === PLAIN_BODY_ID)
     return fallback === undefined ? matched : [...matched, fallback]
-  }, [definitions, file.path])
+  }, [definitions, file.path, unviewable])
   const selected = candidates.find(candidate => candidate.id === state?.rendererId) ?? candidates[0]
   const mode = selected?.loading
   const current = (state?.mode ?? 'text-pages') === mode ? state : undefined
@@ -173,6 +194,24 @@ export function TextPreview({
     return { kind: 'text', pages: loaded, text: loaded.filter(page => page.lines > 0).map(page => page.text).join('\n'), eof: current.eof }
   }, [mode, loaded, current?.complete, current?.eof])
 
+  // A known binary suffix with no matching renderer never reads: no plain-text
+  // fallback, no viewer control, only the path and the unsupported line.
+  if (selected === undefined && unviewable) {
+    const { name: unsupportedName } = pathPartsOf(displayPath)
+    return (
+      <div className={css.preview} data-textpreview-state="unsupported" data-textpreview-url={tab.contentId}>
+        <div className={css.header}>
+          <HeaderPath pathRef={pathRef} pathTextRef={pathTextRef} path={displayPath} />
+        </div>
+        <div className={css.body} data-textpreview-body>
+          <div className={css.empty} data-textpreview-unsupported>
+            <FileTypeIcon kind={classifyFileType(unsupportedName)} size={36} className={css.emptyIcon} />
+            <p className={css.emptyLine}>{t('unsupportedFile')}</p>
+          </div>
+        </div>
+      </div>
+    )
+  }
   if (state === undefined || selected === undefined) {
     return (
       <div className={css.status} data-textpreview-state="loading">
@@ -183,7 +222,7 @@ export function TextPreview({
     )
   }
   const next = loadedThrough + 1
-  const { directory, name } = pathPartsOf(displayPath)
+  const { name } = pathPartsOf(displayPath)
   const observedVersion = meta.value?.version
   const changed = current?.version !== undefined && observedVersion !== undefined
     && observedVersion !== current.version && observedVersion !== current.observedVersion
@@ -230,27 +269,25 @@ export function TextPreview({
           </p>
         )}
       <div className={css.header}>
-        <div ref={pathRef} className={css.path} title={displayPath} data-textpreview-path>
-          <span ref={pathTextRef} className={css.pathText}>
-            {directory !== '' && <span className={css.pathDirectory}>{directory}</span>}
-            <span className={css.pathName}>{name}</span>
-          </span>
-        </div>
-        <Menu
-          open={menuOpen}
-          anchor={(
-            <button type="button" className={clsx(css.tool, css.viewerTool)} aria-label={t('openWith')} title={selected.title()} data-document-viewer-menu onClick={() => { setMenuOpen(value => !value) }}>
-              {selected.title()}
-            </button>
+        <HeaderPath pathRef={pathRef} pathTextRef={pathTextRef} path={displayPath} />
+        {candidates.length > 1
+          && (
+            <Menu
+              open={menuOpen}
+              anchor={(
+                <button type="button" className={clsx(css.tool, css.viewerTool)} aria-label={t('openWith')} title={selected.title()} data-document-viewer-menu onClick={() => { setMenuOpen(value => !value) }}>
+                  {selected.title()}
+                </button>
+              )}
+              items={candidates.map(candidate => ({ id: candidate.id, label: candidate.title() }))}
+              selectedId={selected.id}
+              onSelect={(id) => { actions.selected(tab.id, id); setMenuOpen(false) }}
+              onClose={() => { setMenuOpen(false) }}
+              align="end"
+              portal
+              dense
+            />
           )}
-          items={candidates.map(candidate => ({ id: candidate.id, label: candidate.title() }))}
-          selectedId={selected.id}
-          onSelect={(id) => { actions.selected(tab.id, id); setMenuOpen(false) }}
-          onClose={() => { setMenuOpen(false) }}
-          align="end"
-          portal
-          dense
-        />
         {selected.wrap === true && (
           // The tooltip names the action while the stable aria name and
           // `aria-pressed` expose the control and its current state.
@@ -295,7 +332,7 @@ export function TextPreview({
         }}
       >
         {!hasContent && current?.failure === undefined && (
-          <LoadingIndicator className={css.statusLine} label={t('loading')} />
+          <LoadingIndicator className={clsx(css.statusLine, css.bodyLoading)} label={t('loading')} />
         )}
         {content !== undefined && renderSlot('sidebar.right.tab.document', {
           resourceAddress: tab.contentId, content, wrap: state.wrap, scrollportRef: bindScrollport,
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/document/registry.ts b/packages/client/ui-sidebar-documentpreview/src/client/document/registry.ts
index 29c583d17e..ac10289bd1 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/document/registry.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/document/registry.ts
@@ -1,5 +1,6 @@
 /** File-extension preview registrations; component dispatch belongs to the keyed document slot. */
 import { notifySubscribers } from '@deepseek-ai/dsh-client-store'
+import { documentFileName, matchedSuffixLength, normalizeSuffix } from './suffix.ts'
 
 /** How the document owner delivers file contents to a renderer. */
 export type DocumentLoadMode = 'text-pages' | 'bytes-complete'
@@ -10,6 +11,12 @@ export interface DocumentPreviewDefinition {
   readonly id: string
   /** File suffixes without a leading dot; compound suffixes such as tar.gz are accepted. */
   readonly extensions: readonly string[]
+  /**
+   * Suffixes among `extensions` whose bytes are not readable text; a file
+   * matching one loses the plain-text fallback among its viewer choices.
+   * Every entry must appear in `extensions`; `register` rejects strays.
+   */
+  readonly binaryExtensions?: readonly string[]
   /** External implementations win over product implementations; defaults to extension. */
   readonly priority?: 'builtin' | 'extension'
   /** Localized implementation label, evaluated when the toolbar renders. @returns the visible name. */
@@ -30,21 +37,31 @@ export function matchingDocumentPreviews(
   definitions: readonly DocumentPreviewDefinition[],
   path: string,
 ): readonly DocumentPreviewDefinition[] {
-  const normalized = path.replaceAll('\\', '/').toLowerCase()
-  const name = normalized.slice(normalized.lastIndexOf('/') + 1)
+  const name = documentFileName(path)
   return definitions.map((definition, order) => ({
     definition, order,
     rank: definition.priority === 'builtin' ? 0 : 1,
-    length: Math.max(0, ...definition.extensions
-      .map(extension => extension.toLowerCase().replace(/^\./u, ''))
-      .filter(extension => name.endsWith(`.${extension}`))
-      .map(extension => extension.length)),
+    length: matchedSuffixLength(name, definition.extensions),
   }))
     .filter(candidate => candidate.length > 0)
     .sort((left, right) => right.rank - left.rank || right.length - left.length || left.order - right.order)
     .map(candidate => candidate.definition)
 }
 
+/**
+ * Whether any registered implementation declares the filename's suffix binary.
+ * @param definitions - registered implementations.
+ * @param path - decoded filename or file path.
+ * @returns true when a declared binary suffix matches the filename.
+ */
+export function binaryDocumentPath(
+  definitions: readonly DocumentPreviewDefinition[],
+  path: string,
+): boolean {
+  const name = documentFileName(path)
+  return definitions.some(definition => matchedSuffixLength(name, definition.binaryExtensions ?? []) > 0)
+}
+
 /** Observable registry of all live implementations, including lower-priority alternatives. */
 export class DocumentPreviewRegistry {
   private readonly registered = new Map<string, DocumentPreviewDefinition>()
@@ -69,13 +86,21 @@ export class DocumentPreviewRegistry {
 
   /**
    * Register metadata separately from the matching keyed slot component.
-   * @param definition - unique implementation and recognized suffixes.
-   * @returns an idempotent disposer; duplicate live implementation names throw.
+   * @param definition - unique implementation and recognized suffixes; every
+   * `binaryExtensions` entry must appear in `extensions`.
+   * @returns an idempotent disposer; duplicate live implementation names and
+   * binary suffixes outside `extensions` throw.
    */
   register(definition: DocumentPreviewDefinition): () => void {
     if (this.registered.has(definition.id)) {
       throw new Error(`documentPreviews: duplicate implementation "${definition.id}"`)
     }
+    const declared = new Set(definition.extensions.map(normalizeSuffix))
+    for (const extension of definition.binaryExtensions ?? []) {
+      if (!declared.has(normalizeSuffix(extension))) {
+        throw new Error(`documentPreviews: "${definition.id}" declares binary suffix "${extension}" outside its extensions`)
+      }
+    }
     this.registered.set(definition.id, definition)
     this.publish()
     let active = true
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/document/suffix.ts b/packages/client/ui-sidebar-documentpreview/src/client/document/suffix.ts
new file mode 100644
index 0000000000..6af66f295c
--- /dev/null
+++ b/packages/client/ui-sidebar-documentpreview/src/client/document/suffix.ts
@@ -0,0 +1,36 @@
+/**
+ * Filename suffix matching shared by the preview registry and the owner's
+ * unviewable list, so every consumer normalizes paths and suffixes alike.
+ */
+
+/**
+ * Normalize one declared suffix for comparison.
+ * @param extension - declared file suffix, with or without a leading dot.
+ * @returns the suffix lowercased with any leading dot dropped.
+ */
+export function normalizeSuffix(extension: string): string {
+  return extension.toLowerCase().replace(/^\./u, '')
+}
+
+/**
+ * The filename a path's suffixes are matched against.
+ * @param path - decoded filename or file path; `\` is accepted as a separator.
+ * @returns the lowercased final path segment.
+ */
+export function documentFileName(path: string): string {
+  const normalized = path.replaceAll('\\', '/').toLowerCase()
+  return normalized.slice(normalized.lastIndexOf('/') + 1)
+}
+
+/**
+ * The longest declared suffix ending the filename.
+ * @param name - lowercased filename from {@link documentFileName}.
+ * @param extensions - declared suffixes; compound suffixes such as `tar.gz` are accepted.
+ * @returns the matched suffix's normalized length, or 0 when none matches.
+ */
+export function matchedSuffixLength(name: string, extensions: readonly string[]): number {
+  return Math.max(0, ...extensions
+    .map(normalizeSuffix)
+    .filter(extension => name.endsWith(`.${extension}`))
+    .map(extension => extension.length))
+}
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/document/unviewable.ts b/packages/client/ui-sidebar-documentpreview/src/client/document/unviewable.ts
new file mode 100644
index 0000000000..cef3776c04
--- /dev/null
+++ b/packages/client/ui-sidebar-documentpreview/src/client/document/unviewable.ts
@@ -0,0 +1,37 @@
+/**
+ * Known binary container suffixes with no registered renderer. The preview
+ * owner shows these the unsupported empty state instead of the plain-text
+ * fallback; any renderer registration for a suffix takes precedence because
+ * the owner consults this list only when no implementation matches. A suffix
+ * belongs here only when its bytes are never readable text — an uncertain
+ * suffix stays out and keeps the plain-text fallback.
+ */
+import { documentFileName, matchedSuffixLength } from './suffix.ts'
+const UNVIEWABLE_BINARY_EXTENSIONS: readonly string[] = [
+  // video
+  'mp4', 'mov', 'avi', 'mkv', 'webm', 'flv', 'wmv', 'm4v',
+  // audio
+  'mp3', 'wav', 'flac', 'ogg', 'm4a', 'aac', 'wma', 'opus',
+  // archives
+  'zip', 'gz', 'tgz', 'bz2', 'xz', 'zst', '7z', 'rar', 'tar', 'jar',
+  // office documents — `key` stays out: it collides with key/credential files
+  // that are readable text, and the uncertain suffix keeps the plain-text fallback
+  'doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx', 'odt', 'ods', 'odp', 'pages', 'numbers',
+  // executables and compiled objects
+  'exe', 'dll', 'so', 'dylib', 'bin', 'o', 'class', 'pyc', 'wasm',
+  // fonts
+  'ttf', 'otf', 'woff', 'woff2', 'eot',
+  // disk images and databases
+  'dmg', 'iso', 'img', 'sqlite', 'db',
+  // design documents and image formats without a renderer
+  'psd', 'ai', 'sketch', 'tiff', 'tif', 'heic', 'heif', 'avif',
+]
+
+/**
+ * Whether a filename's suffix is a known binary container that no renderer claims.
+ * @param path - decoded filename or file path.
+ * @returns true when the suffix belongs to the unviewable binary list.
+ */
+export function unviewableBinaryPath(path: string): boolean {
+  return matchedSuffixLength(documentFileName(path), UNVIEWABLE_BINARY_EXTENSIONS) > 0
+}
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.module.css b/packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.module.css
index 02f352bb66..8147e1714c 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.module.css
+++ b/packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.module.css
@@ -13,3 +13,12 @@
   color: var(--dsw-alias-label-secondary);
   white-space: normal;
 }
+
+/* The packing wait fills the still-empty body and centres, like the image
+   renderer's status. */
+.opening {
+  justify-content: center;
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 100%;
+}
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.tsx b/packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.tsx
index 34c742786d..3608f57b90 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.tsx
+++ b/packages/client/ui-sidebar-documentpreview/src/client/html/HtmlBody.tsx
@@ -1,6 +1,7 @@
 /** Complete HTML rendered in a script-enabled opaque iframe, without parent application access. */
 import { useEffect, useMemo, useState } from 'react'
 import type { ReactNode } from 'react'
+import clsx from 'clsx'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import type { DocumentPreviewProps } from '../document/contract.ts'
 import { LoadingIndicator } from '../LoadingIndicator.tsx'
@@ -49,7 +50,7 @@ function HtmlFrame({ data, readRelative, t }: FrameInput & { t: HtmlBodyProps['t
   }, [data, readRelative])
 
   if (frame?.data !== data || frame.readRelative !== readRelative) {
-    return <LoadingIndicator className={css.status} label={t('loading')} />
+    return <LoadingIndicator className={clsx(css.status, css.opening)} label={t('loading')} />
   }
   if (frame.url === undefined) return <p className={css.status} role="alert">{t('failed')}</p>
   return <iframe key={frame.url} className={css.frame} src={frame.url} sandbox="allow-scripts" title={t('frame')} data-html-preview />
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/html/locales.ts b/packages/client/ui-sidebar-documentpreview/src/client/html/locales.ts
index b5f05efe3a..437141e8f9 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/html/locales.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/html/locales.ts
@@ -2,8 +2,8 @@
 export const zh = {
   title: 'HTML',
   frame: 'HTML 文档预览',
-  loading: '正在准备 HTML 预览…',
-  failed: '无法预览这份 HTML 文档。',
+  loading: '正在读取…',
+  failed: '无法预览这份 HTML 文档',
 } satisfies Record<string, string>
 
 /** HTML renderer dictionary keys. */
@@ -13,7 +13,7 @@ export type HtmlPreviewKey = keyof typeof zh
 export const en = {
   title: 'HTML',
   frame: 'HTML document preview',
-  loading: 'Preparing HTML preview…',
+  loading: 'Reading…',
   failed: 'This HTML document could not be previewed.',
 } satisfies Record<HtmlPreviewKey, string>
 
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/image/ImageBody.module.css b/packages/client/ui-sidebar-documentpreview/src/client/image/ImageBody.module.css
index 3e45c0eb25..408c298681 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/image/ImageBody.module.css
+++ b/packages/client/ui-sidebar-documentpreview/src/client/image/ImageBody.module.css
@@ -1,23 +1,28 @@
+/* The frame follows the scroller's width, so the image's percentage maximum
+   resolves against the pane and never scrolls horizontally; a taller image
+   grows the frame and scrolls vertically. */
 .frame {
   display: flex;
   box-sizing: border-box;
-  width: max-content;
-  min-width: 100%;
+  width: 100%;
   height: max-content;
   min-height: 100%;
-  padding: 8px;
+  padding: 12px;
   font-family: var(--dsw-font, sans-serif);
   white-space: normal;
 }
 
+/* A wider image shrinks to the pane's width at its aspect ratio; a smaller
+   one keeps its intrinsic size. The auto margins centre it either way. */
 .image {
   display: block;
   flex: none;
   width: auto;
-  max-width: none;
+  max-width: 100%;
   height: auto;
   max-height: none;
   margin: auto;
+  border-radius: 8px;
   user-select: none;
 }
 
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/image/ImageBody.tsx b/packages/client/ui-sidebar-documentpreview/src/client/image/ImageBody.tsx
index f01ec88d1c..2f0ac09119 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/image/ImageBody.tsx
+++ b/packages/client/ui-sidebar-documentpreview/src/client/image/ImageBody.tsx
@@ -1,4 +1,4 @@
-/** Complete image bytes rendered at their intrinsic CSS-pixel dimensions. */
+/** Complete image bytes rendered rounded within an inset frame, scaled down to the pane's width. */
 import { useEffect, useMemo, useState, type ReactNode } from 'react'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
 import { pathPartsOf } from '@deepseek-ai/dsh-util-workspace-path'
@@ -46,9 +46,11 @@ export function imageMediaType(path: string): ImageMediaType | undefined {
 }
 
 /**
- * Present complete image bytes without fitting or scaling them to the pane.
+ * Present complete image bytes fitted to the pane's width.
  * @param props - document bytes, resource identity, and locale.
- * @returns an intrinsic-size image whose containing document body provides scrolling.
+ * @returns a rounded image scaled down to the pane's width at its aspect
+ * ratio — a smaller image centres at its intrinsic size — whose containing
+ * document body provides vertical scrolling.
  */
 export function ImageBody({ content, resourceAddress, t }: ImageBodyProps): ReactNode {
   const path = useMemo(() => hostFileOf(resourceAddress).path, [resourceAddress])
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/image/index.ts b/packages/client/ui-sidebar-documentpreview/src/client/image/index.ts
index 28586d1398..51794da53a 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/image/index.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/image/index.ts
@@ -11,6 +11,9 @@ export const IMAGE_BODY_ID = '@deepseek-ai/dsh-client-ui-sidebar-documentpreview
 /** File suffixes rendered by the builtin image body. */
 export const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'ico', 'svg'] as const
 
+/** Bitmap suffixes whose bytes are unreadable as text; SVG stays out because its XML source is worth reading. */
+export const BINARY_IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'ico'] as const
+
 /**
  * Describe the builtin image renderer independently from its keyed body slot.
  * @param title - locale-owned implementation name.
@@ -20,6 +23,7 @@ export function imageBodyDefinition(title: () => string): DocumentPreviewDefinit
   return {
     id: IMAGE_BODY_ID,
     extensions: IMAGE_EXTENSIONS,
+    binaryExtensions: BINARY_IMAGE_EXTENSIONS,
     priority: 'builtin',
     title,
     loading: 'bytes-complete',
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/image/locales.ts b/packages/client/ui-sidebar-documentpreview/src/client/image/locales.ts
index 9859985ac8..eab44ce0b0 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/image/locales.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/image/locales.ts
@@ -2,9 +2,9 @@
 export const zh = {
   title: '图片',
   preview: '图片预览：{name}',
-  loading: '正在打开图片…',
-  failed: '无法显示这张图片。',
-  unsupported: '图片预览需要完整文件内容。',
+  loading: '正在读取…',
+  failed: '无法显示这张图片',
+  unsupported: '图片预览需要完整文件内容',
 } satisfies Record<string, string>
 
 /** Image renderer dictionary keys. */
@@ -14,7 +14,7 @@ export type ImagePreviewKey = keyof typeof zh
 export const en = {
   title: 'Image',
   preview: 'Image preview: {name}',
-  loading: 'Opening image…',
+  loading: 'Reading…',
   failed: 'This image could not be displayed.',
   unsupported: 'Image preview requires the complete file contents.',
 } satisfies Record<ImagePreviewKey, string>
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/locales.ts b/packages/client/ui-sidebar-documentpreview/src/client/locales.ts
index 545dac98cb..6a8f512596 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/locales.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/locales.ts
@@ -10,7 +10,7 @@
 export const zh = {
   loading: '正在读取…',
   loadMore: '加载更多',
-  changed: '文件已更新，当前显示为旧内容。',
+  changed: '文件已更新，当前显示为旧内容',
   reloadNow: '重新载入',
   reload: '重新读取文件',
   'wrap.enable': '自动换行',
@@ -18,12 +18,13 @@ export const zh = {
   'wrap.aria': '自动换行',
   openWith: '打开方式',
   'viewer.text': '纯文本',
-  resourceUnavailable: '文件资源服务不可用。',
-  rendererUnavailable: '预览器 {name} 不可用。',
-  'error.notFound': '文件不存在，可能已被移动或删除。',
-  'error.tooLarge': '单页内容超过 {limit} 上限，无法读取。',
-  'error.notText': '非文本文件，暂时无法预览。',
-  'error.notRegularFile': '该路径不是普通文件，没有可显示的内容。',
+  resourceUnavailable: '文件资源服务不可用',
+  rendererUnavailable: '预览器 {name} 不可用',
+  unsupportedFile: '该格式文件暂时无法预览',
+  'error.notFound': '文件不存在，可能已被移动或删除',
+  'error.tooLarge': '单页内容超过 {limit} 上限，无法读取',
+  'error.notText': '该格式文件暂时无法预览',
+  'error.notRegularFile': '该路径不是普通文件，没有可显示的内容',
   'error.unavailable': '读取失败：{message}',
   retry: '重试',
 } satisfies Record<string, string>
@@ -45,9 +46,10 @@ export const en = {
   'viewer.text': 'Plain text',
   resourceUnavailable: 'The file resource service is unavailable.',
   rendererUnavailable: 'The {name} preview is unavailable.',
+  unsupportedFile: 'Preview is not available for this file type yet.',
   'error.notFound': 'File not found. It may have been moved or deleted.',
   'error.tooLarge': 'This page exceeds the {limit} limit and cannot be read.',
-  'error.notText': 'Not a text file, preview is unavailable for now.',
+  'error.notText': 'Preview is not available for this file type yet.',
   'error.notRegularFile': 'Not a regular file, nothing to display.',
   'error.unavailable': 'Read failed: {message}',
   retry: 'Retry',
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/pdf/PdfBody.module.css b/packages/client/ui-sidebar-documentpreview/src/client/pdf/PdfBody.module.css
index 38cc231c3c..dcfbad7494 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/pdf/PdfBody.module.css
+++ b/packages/client/ui-sidebar-documentpreview/src/client/pdf/PdfBody.module.css
@@ -4,7 +4,6 @@
   box-sizing: border-box;
   width: 100%;
   min-height: 0;
-  padding: 8px;
   overflow-x: hidden;
   font-family: var(--dsw-font, sans-serif);
   white-space: normal;
@@ -14,16 +13,15 @@
   box-sizing: border-box;
   width: 100%;
   min-width: 0;
-  padding: 12px;
   overflow-x: hidden;
 }
 
+/* An unrendered page holds its place as a quiet block; the block itself is
+   the loading feedback, so no spinner competes with the centred open wait. */
 .placeholder {
-  display: flex;
-  align-items: center;
-  justify-content: center;
   width: 100%;
   aspect-ratio: 3 / 4;
+  background: var(--dsw-alias-bg-skeleton);
 }
 
 .canvas {
@@ -47,3 +45,12 @@
   font-size: 13px;
   line-height: 1.5;
 }
+
+/* The document-open wait fills the still-empty body and centres, matching the
+   owner's read spinner position. */
+.opening {
+  justify-content: center;
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 100%;
+}
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/pdf/PdfBody.tsx b/packages/client/ui-sidebar-documentpreview/src/client/pdf/PdfBody.tsx
index 1c74f2f0f8..44ee433f26 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/pdf/PdfBody.tsx
+++ b/packages/client/ui-sidebar-documentpreview/src/client/pdf/PdfBody.tsx
@@ -1,5 +1,6 @@
 /** PDF page presentation; binary content and tab information come from the document owner. */
 import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
+import clsx from 'clsx'
 import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale, PropsStore } from '@deepseek-ai/dsh-client-ui-slots'
 import type { TabId } from '@deepseek-ai/dsh-client-ui-dockkit'
@@ -64,7 +65,9 @@ export function PdfBody(props: PdfBodyProps): ReactNode {
     }
   }, [data, tab.signal, attempt])
   if (data === undefined) return <p className={css.status} role="alert">{t('unsupported')}</p>
-  if (load?.data !== data) return <LoadingIndicator className={css.status} label={t('loading')} />
+  // The open wait centres like the owner's read spinner before it, so one
+  // spinner position covers everything until the first page block appears.
+  if (load?.data !== data) return <LoadingIndicator className={clsx(css.status, css.opening)} label={t('loading')} />
   if (load.kind === 'failed') {
     return <div className={css.status} role="alert">
       <span>{failureText(load.error, t)}</span>
@@ -126,9 +129,9 @@ function PdfPage({ document, page, requested: initiallyRequested, onVisible, sig
     return () => { lifetime.abort() }
   }, [document, page, requested, signal, attempt])
   return <div ref={host} className={css.page} data-pdf-page={page}>
-    {failure === undefined && state !== 'ready' && <div className={css.placeholder}>
-      {requested && <LoadingIndicator className={css.status} label={t('rendering')} />}
-    </div>}
+    {failure === undefined && state !== 'ready' && (requested
+      ? <div className={css.placeholder} role="status" aria-label={t('rendering')} />
+      : <div className={css.placeholder} />)}
     {failure !== undefined && <div className={css.status} role="alert">
       <span>{failureText(failure.error, t)}</span>
       <Button size="sm" onClick={() => { setAttempt(value => value + 1) }}>{t('retry')}</Button>
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/pdf/index.ts b/packages/client/ui-sidebar-documentpreview/src/client/pdf/index.ts
index 525088c7f6..f75cb36f4f 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/pdf/index.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/pdf/index.ts
@@ -15,7 +15,7 @@ export const PDF_BODY_ID = '@deepseek-ai/dsh-client-ui-sidebar-documentpreview/p
  * @returns the complete-file PDF registration.
  */
 export function pdfBodyDefinition(title: () => string): DocumentPreviewDefinition {
-  return { id: PDF_BODY_ID, extensions: ['pdf'], priority: 'builtin', title, loading: 'bytes-complete', wrap: false }
+  return { id: PDF_BODY_ID, extensions: ['pdf'], binaryExtensions: ['pdf'], priority: 'builtin', title, loading: 'bytes-complete', wrap: false }
 }
 
 /** @param ctx - context carrying the locale, document registry, and slot registry. */
diff --git a/packages/client/ui-sidebar-documentpreview/src/client/pdf/locales.ts b/packages/client/ui-sidebar-documentpreview/src/client/pdf/locales.ts
index f71a98e2bf..2db19c53f6 100644
--- a/packages/client/ui-sidebar-documentpreview/src/client/pdf/locales.ts
+++ b/packages/client/ui-sidebar-documentpreview/src/client/pdf/locales.ts
@@ -2,12 +2,12 @@
 export const zh = {
   title: 'PDF',
   pageImage: 'PDF 第 {page} 页',
-  loading: '正在打开 PDF…',
+  loading: '正在读取…',
   rendering: '正在绘制页面…',
   failed: '无法显示 PDF：{message}',
-  password: '此 PDF 需要密码，暂不支持预览。',
-  workerFailed: 'PDF 渲染进程无法继续，请重试。',
-  unsupported: 'PDF 预览需要完整文件内容。',
+  password: '此 PDF 需要密码，暂不支持预览',
+  workerFailed: 'PDF 渲染进程无法继续，请重试',
+  unsupported: 'PDF 预览需要完整文件内容',
   retry: '重试',
 } satisfies Record<string, string>
 
@@ -18,7 +18,7 @@ export type PdfLocaleKey = keyof typeof zh
 export const en = {
   title: 'PDF',
   pageImage: 'PDF page {page}',
-  loading: 'Opening PDF…',
+  loading: 'Reading…',
   rendering: 'Rendering page…',
   failed: 'Cannot display PDF: {message}',
   password: 'This PDF requires a password; password-protected previews are not supported.',
diff --git a/packages/client/ui-sidebar-documentpreview/tests/document-registry.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/document-registry.client.spec.ts
index c75ad9c0fc..f9afa39a1a 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/document-registry.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/document-registry.client.spec.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { DocumentPreviewRegistry } from '../src/client/document/registry.ts'
+import { binaryDocumentPath, DocumentPreviewRegistry } from '../src/client/document/registry.ts'
 import type { DocumentPreviewDefinition } from '../src/client/document/registry.ts'
 
 function definition(id: string, overrides: Partial<DocumentPreviewDefinition> = {}): DocumentPreviewDefinition {
@@ -58,6 +58,25 @@ describe('document preview implementations', () => {
     expect(listener).toHaveBeenCalledTimes(2)
   })
 
+  it('marks a path binary only for declared binary suffixes, case-insensitively', () => {
+    const image = definition('image', { extensions: ['png', 'svg'], binaryExtensions: ['png'] })
+    const text = definition('text', { extensions: [] })
+    expect(binaryDocumentPath([image, text], '/work/photo.PNG')).toBe(true)
+    expect(binaryDocumentPath([image, text], 'C:\\work\\photo.png')).toBe(true)
+    expect(binaryDocumentPath([image, text], '/work/diagram.svg')).toBe(false)
+    expect(binaryDocumentPath([image, text], '/work.png/plain')).toBe(false)
+    expect(binaryDocumentPath([text], '/work/photo.png')).toBe(false)
+  })
+
+  it('rejects a binary suffix outside the declared extensions without registering', () => {
+    const registry = new DocumentPreviewRegistry()
+    expect(() => registry.register(definition('image', { extensions: ['png', 'svg'], binaryExtensions: ['pdf'] })))
+      .toThrow(/binary suffix "pdf" outside its extensions/u)
+    expect(registry.getSnapshot()).toEqual([])
+    registry.register(definition('image', { extensions: ['PNG', 'svg'], binaryExtensions: ['.png'] }))
+    expect(registry.getSnapshot()).toHaveLength(1)
+  })
+
   it('rejects duplicate ids without replacing the existing registration', () => {
     const registry = new DocumentPreviewRegistry()
     const entry = definition('markdown')
diff --git a/packages/client/ui-sidebar-documentpreview/tests/document-toolbar.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/document-toolbar.client.spec.tsx
index 2a312a65a1..0fa5189b44 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/document-toolbar.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/document-toolbar.client.spec.tsx
@@ -7,6 +7,7 @@ import { TextPreview } from '../src/client/TextPreview.tsx'
 import type { TextPreviewProps } from '../src/client/TextPreview.tsx'
 import type { DocumentPreviewDefinition } from '../src/client/document/registry.ts'
 import { CodeBody } from '../src/client/code/CodeBody.tsx'
+import { PLAIN_BODY_ID } from '../src/client/text/index.ts'
 import { ABSOLUTE_PATH, FILE, harness, page, settle, TAB_ID } from './fixtures.client.ts'
 
 afterEach(cleanup)
@@ -44,7 +45,8 @@ describe('document toolbar', () => {
     const body = view.container.querySelector('[data-textpreview-body]')
     expect(view.container.querySelector('[data-code-preview]')).toBeNull()
     expect(body?.firstElementChild).toBe(view.getByRole('status'))
-    expect(view.getByRole('status').textContent).toBe('loading')
+    expect(view.getByRole('status').getAttribute('aria-label')).toBe('loading')
+    expect(view.getByRole('status').textContent).toBe('')
     expect(view.container.querySelector('[data-textpreview-more]')).toBeNull()
 
     await act(async () => { first.resolve(page(1, ['const prefix = 1;'], false)); await first.promise })
@@ -83,7 +85,7 @@ describe('document toolbar', () => {
     h.read.mockReturnValueOnce(pending.promise)
     const view = render(<TextPreview {...codeProps(h)} />)
     expect(view.container.querySelector('[data-code-preview]')).toBeNull()
-    expect(view.getByRole('status').textContent).toBe('loading')
+    expect(view.getByRole('status').getAttribute('aria-label')).toBe('loading')
     await act(async () => { pending.resolve(page(1, [], true)); await pending.promise })
     expect(view.container.querySelector('[data-code-preview]')).not.toBeNull()
     expect(view.container.querySelector('[data-code-preview] pre')?.textContent).toBe('')
@@ -106,7 +108,7 @@ describe('document toolbar', () => {
     const props: TextPreviewProps = { ...h.props(), useDocumentPreviews: selector => selector([binary]), renderSlot }
     const view = render(<TextPreview {...props} />)
     expect(view.getByRole('status').hasAttribute('data-document-loading')).toBe(true)
-    expect(view.getByRole('status').textContent).toBe('loading')
+    expect(view.getByRole('status').getAttribute('aria-label')).toBe('loading')
     expect(view.container.querySelector('[data-textpreview-body]')?.firstElementChild).toBe(view.getByRole('status'))
     expect(renderSlot).not.toHaveBeenCalled()
     await act(async () => {
@@ -156,9 +158,68 @@ describe('document toolbar', () => {
     h.controller.abort()
   })
 
+  it('drops the plain-text fallback for a declared binary suffix and hides the viewer control entirely', async () => {
+    const h = harness()
+    h.bytes.mockResolvedValue({ ok: true, value: { absolutePath: '/host/project/work/photo.png', version: 'v1', offset: 0, data: btoa('x'), bytes: 1, eof: true } })
+    const image: DocumentPreviewDefinition = {
+      id: 'image', extensions: ['png', 'svg'], binaryExtensions: ['png'], title: () => 'Image', loading: 'bytes-complete',
+    }
+    const plain: DocumentPreviewDefinition = {
+      id: PLAIN_BODY_ID, extensions: [], title: () => 'viewer.text', loading: 'text-pages', wrap: true,
+    }
+    const base = h.props()
+    const info = base.useTabInfo()
+    const address = 'dsh-resource://file/session/s-1/work/photo.png'
+    const props: TextPreviewProps = {
+      ...base,
+      useTabInfo: () => ({ ...info, tab: { ...info.tab, contentId: address, navigation: { ...info.tab.navigation, address } } }),
+      useDocumentPreviews: selector => selector([image, plain]),
+      renderSlot: vi.fn(() => null),
+    } as TextPreviewProps
+    const view = render(<TextPreview {...props} />)
+    await settle()
+    expect(view.container.querySelector('[data-document-viewer-menu]')).toBeNull()
+    expect(view.container.querySelector('[data-textpreview-tool="reload"]')).not.toBeNull()
+    h.controller.abort()
+  })
+
+  it('keeps the plain-text fallback in the picker for a non-binary suffix of the same viewer', async () => {
+    const h = harness()
+    h.bytes.mockResolvedValue({ ok: true, value: { absolutePath: '/host/project/work/logo.svg', version: 'v1', offset: 0, data: btoa('<svg/>'), bytes: 6, eof: true } })
+    const image: DocumentPreviewDefinition = {
+      id: 'image', extensions: ['png', 'svg'], binaryExtensions: ['png'], title: () => 'Image', loading: 'bytes-complete',
+    }
+    const plain: DocumentPreviewDefinition = {
+      id: PLAIN_BODY_ID, extensions: [], title: () => 'viewer.text', loading: 'text-pages', wrap: true,
+    }
+    const base = h.props()
+    const info = base.useTabInfo()
+    const address = 'dsh-resource://file/session/s-1/work/logo.svg'
+    const props: TextPreviewProps = {
+      ...base,
+      useTabInfo: () => ({ ...info, tab: { ...info.tab, contentId: address, navigation: { ...info.tab.navigation, address } } }),
+      useDocumentPreviews: selector => selector([image, plain]),
+      renderSlot: vi.fn(() => null),
+    } as TextPreviewProps
+    const view = render(<TextPreview {...props} />)
+    await settle()
+    fireEvent.click(view.container.querySelector('[data-document-viewer-menu]')!)
+    expect(screen.getByRole('menuitem', { name: 'Image' })).toBeDefined()
+    expect(screen.getByRole('menuitem', { name: 'viewer.text' })).toBeDefined()
+    h.controller.abort()
+  })
+
   it('dismisses the implementation picker with Escape without changing the selected implementation', async () => {
     const h = harness({ 1: page(1, ['held'], true) })
-    const view = render(<TextPreview {...h.props()} />)
+    const base = h.props()
+    const code: DocumentPreviewDefinition = {
+      id: 'code', extensions: ['md'], title: () => 'Code', loading: 'text-pages', wrap: true,
+    }
+    const plain: DocumentPreviewDefinition = {
+      id: PLAIN_BODY_ID, extensions: [], title: () => 'viewer.text', loading: 'text-pages', wrap: true,
+    }
+    const props: TextPreviewProps = { ...base, useDocumentPreviews: selector => selector([code, plain]) }
+    const view = render(<TextPreview {...props} />)
     await settle()
     fireEvent.click(view.container.querySelector('[data-document-viewer-menu]')!)
     expect(screen.getByRole('menuitem', { name: 'viewer.text' })).toBeDefined()
@@ -167,4 +228,42 @@ describe('document toolbar', () => {
     expect(h.instance.getSnapshot().byTab[TAB_ID]?.rendererId).toBeUndefined()
     h.controller.abort()
   })
+
+  it('shows the unsupported empty state for a known binary suffix with no renderer, reading nothing', async () => {
+    const h = harness()
+    const base = h.props()
+    const info = base.useTabInfo()
+    const address = 'dsh-resource://file/session/s-1/work/clip.mp4'
+    const props: TextPreviewProps = {
+      ...base,
+      useTabInfo: () => ({ ...info, tab: { ...info.tab, contentId: address, navigation: { ...info.tab.navigation, address } } }),
+    }
+    const view = render(<TextPreview {...props} />)
+    await settle()
+    expect(view.container.querySelector('[data-textpreview-state="unsupported"]')).not.toBeNull()
+    expect(view.container.querySelector('[data-textpreview-unsupported]')?.textContent).toContain('unsupportedFile')
+    expect(view.container.querySelector('[data-textpreview-path]')).not.toBeNull()
+    expect(view.container.querySelector('[data-document-viewer-menu]')).toBeNull()
+    expect(view.container.querySelector('[data-textpreview-tool="reload"]')).toBeNull()
+    expect(h.read).not.toHaveBeenCalled()
+    expect(h.bytes).not.toHaveBeenCalled()
+    h.controller.abort()
+  })
+
+  it('keeps the plain-text fallback for an unlisted unknown suffix', async () => {
+    const h = harness({ 1: page(1, ['plain line'], true) })
+    const base = h.props()
+    const info = base.useTabInfo()
+    const address = 'dsh-resource://file/session/s-1/work/server.log'
+    const props: TextPreviewProps = {
+      ...base,
+      useTabInfo: () => ({ ...info, tab: { ...info.tab, contentId: address, navigation: { ...info.tab.navigation, address } } }),
+    }
+    const view = render(<TextPreview {...props} />)
+    await settle()
+    expect(view.container.querySelector('[data-textpreview-state="unsupported"]')).toBeNull()
+    expect(h.read).toHaveBeenCalledTimes(1)
+    expect(view.container.textContent).toContain('plain line')
+    h.controller.abort()
+  })
 })
diff --git a/packages/client/ui-sidebar-documentpreview/tests/document-unviewable.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/document-unviewable.client.spec.ts
new file mode 100644
index 0000000000..2a9b3672b1
--- /dev/null
+++ b/packages/client/ui-sidebar-documentpreview/tests/document-unviewable.client.spec.ts
@@ -0,0 +1,25 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import { unviewableBinaryPath } from '../src/client/document/unviewable.ts'
+
+describe('unviewableBinaryPath', () => {
+  it('matches one sample from every listed category', () => {
+    for (const path of [
+      'clip.mp4', 'song.mp3', 'bundle.zip', 'report.docx', 'tool.exe',
+      'face.woff2', 'image.dmg', 'design.psd',
+    ]) expect(unviewableBinaryPath(path), path).toBe(true)
+  })
+
+  it('matches regardless of case, directories, and path separators', () => {
+    expect(unviewableBinaryPath('MOVIE.MP4')).toBe(true)
+    expect(unviewableBinaryPath('work/deep/archive.tar.gz')).toBe(true)
+    expect(unviewableBinaryPath('work\\deep\\notes.docx')).toBe(true)
+  })
+
+  it('leaves renderer-claimed, text, and unknown suffixes to their existing paths', () => {
+    for (const path of [
+      'main.ts', 'README.md', 'photo.png', 'page.html', 'paper.pdf', 'logo.svg',
+      'server.log', 'config.env', 'notes.unknown', 'Makefile', 'mp4', 'private.key',
+    ]) expect(unviewableBinaryPath(path), path).toBe(false)
+  })
+})
diff --git a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
index e6de813602..78eca6a5f2 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/html-body.client.spec.tsx
@@ -129,7 +129,7 @@ describe('HtmlBody', () => {
       readRelated: bytes,
     } as unknown as HtmlBodyProps
     render(<HtmlBody {...initial} />)
-    expect(screen.getByRole('status').textContent).toBe(en.loading)
+    expect(screen.getByRole('status').getAttribute('aria-label')).toBe(en.loading)
     expect(screen.getByRole('status').hasAttribute('data-document-loading')).toBe(true)
     expect(create).not.toHaveBeenCalled()
     expect(await screen.findByTitle(en.frame)).toBeTruthy()
diff --git a/packages/client/ui-sidebar-documentpreview/tests/image-body.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/image-body.client.spec.tsx
index 377f93514a..a1cf84e072 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/image-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/image-body.client.spec.tsx
@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-/** Image Blob ownership, media types, intrinsic rendering, and failure states. */
+/** Image Blob ownership, media types, pane-contained rendering, and failure states. */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
@@ -64,7 +64,7 @@ describe('ImageBody', () => {
     expect(revoke).toHaveBeenCalledExactlyOnceWith('blob:https://preview.invalid/1')
   })
 
-  it('keeps the image unscaled and non-draggable, then shows it after decoding succeeds', async () => {
+  it('keeps the image non-draggable, then shows it after decoding succeeds', async () => {
     render(<ImageBody {...props('photo.svg')} />)
     const image = await screen.findByRole('img', { hidden: true })
     expect(image.getAttribute('alt')).toBe('Image preview: photo.svg')
diff --git a/packages/client/ui-sidebar-documentpreview/tests/image-registration.client.spec.ts b/packages/client/ui-sidebar-documentpreview/tests/image-registration.client.spec.ts
index eb7ac01dd1..af99142277 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/image-registration.client.spec.ts
+++ b/packages/client/ui-sidebar-documentpreview/tests/image-registration.client.spec.ts
@@ -3,7 +3,7 @@ import { Context } from '@deepseek-ai/cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { DocumentPreviewRegistry } from '../src/client/document/registry.ts'
 import { ImageBody } from '../src/client/image/ImageBody.tsx'
-import { apply, IMAGE_BODY_ID, IMAGE_EXTENSIONS, imageBodyDefinition } from '../src/client/image/index.ts'
+import { apply, BINARY_IMAGE_EXTENSIONS, IMAGE_BODY_ID, IMAGE_EXTENSIONS, imageBodyDefinition } from '../src/client/image/index.ts'
 import { en, zh } from '../src/client/image/locales.ts'
 
 let dispose: (() => Promise<void>) | undefined
@@ -16,6 +16,7 @@ describe('image registration', () => {
     expect(definition).toEqual({
       id: IMAGE_BODY_ID,
       extensions: IMAGE_EXTENSIONS,
+      binaryExtensions: BINARY_IMAGE_EXTENSIONS,
       priority: 'builtin',
       title,
       loading: 'bytes-complete',
diff --git a/packages/client/ui-sidebar-documentpreview/tests/loading-indicator.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/loading-indicator.client.spec.tsx
new file mode 100644
index 0000000000..7ffc7aa826
--- /dev/null
+++ b/packages/client/ui-sidebar-documentpreview/tests/loading-indicator.client.spec.tsx
@@ -0,0 +1,16 @@
+// @vitest-environment jsdom
+/** The shared loading status: an icon-only spinner named by its label. */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render } from '@testing-library/react'
+import { LoadingIndicator } from '../src/client/LoadingIndicator.tsx'
+
+afterEach(cleanup)
+
+describe('LoadingIndicator', () => {
+  it('renders no visible text and carries the label as the accessible name', () => {
+    const { getByRole } = render(<LoadingIndicator label="Reading…" />)
+    const status = getByRole('status')
+    expect(status.textContent).toBe('')
+    expect(status.getAttribute('aria-label')).toBe('Reading…')
+  })
+})
diff --git a/packages/client/ui-sidebar-documentpreview/tests/pdf-body.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/pdf-body.client.spec.tsx
index a522312560..75ea244644 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/pdf-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/pdf-body.client.spec.tsx
@@ -99,7 +99,7 @@ describe('PDF body', () => {
   it('shows loading, omits the paging toolbar, and renders a continuous page sequence', async () => {
     const h = harness()
     const view = render(<h.View />)
-    expect(screen.getByRole('status').textContent).toBe('Opening PDF…')
+    expect(screen.getByRole('status').getAttribute('aria-label')).toBe('Reading…')
     expect(screen.getByRole('status').hasAttribute('data-document-loading')).toBe(true)
     await act(async () => { loads[0]!.deferred.resolve(documentOf()) })
     await act(async () => {})
diff --git a/packages/client/ui-sidebar-documentpreview/tests/text-preview.client.spec.tsx b/packages/client/ui-sidebar-documentpreview/tests/text-preview.client.spec.tsx
index 5cebce9fe0..733bc6decc 100644
--- a/packages/client/ui-sidebar-documentpreview/tests/text-preview.client.spec.tsx
+++ b/packages/client/ui-sidebar-documentpreview/tests/text-preview.client.spec.tsx
@@ -245,7 +245,7 @@ describe('TextPreview — pages', () => {
     const next = Promise.withResolvers<Awaited<ReturnType<typeof h.read>>>()
     h.read.mockReturnValueOnce(next.promise)
     click(view.container, '[data-textpreview-more]')
-    expect(view.getByRole('status').textContent).toBe('loading')
+    expect(view.getByRole('status').getAttribute('aria-label')).toBe('loading')
     expect(lines(view.container)).toEqual(['held\n'])
     await act(async () => { next.resolve(page(2, ['tail'], true)); await next.promise })
     expect(view.queryByRole('status')).toBeNull()
diff --git a/packages/client/ui-sidebar-files/README.i18n.yaml b/packages/client/ui-sidebar-files/README.i18n.yaml
index 855bf2710c..fefd4561f0 100644
--- a/packages/client/ui-sidebar-files/README.i18n.yaml
+++ b/packages/client/ui-sidebar-files/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 packages/client/ui-sidebar-files/README.md
-README.md: 28e052b5a6739118c691431aad88964a8f6d19cd
-README.zh.md: fe5a10d19b3957f555c08eeaf6f48ceb44daecaf
+README.md: efaf0a584e0e8617d0cb97442f9ebb5fa1fe7b59
+README.zh.md: a0d0abffcd6e9f4e979d9a6548537745d0a74ba6
diff --git a/packages/client/ui-sidebar-files/README.md b/packages/client/ui-sidebar-files/README.md
index 28e052b5a6..efaf0a584e 100644
--- a/packages/client/ui-sidebar-files/README.md
+++ b/packages/client/ui-sidebar-files/README.md
@@ -43,7 +43,7 @@ The root is the session's working directory, read from `useSessions().byId[sessi
 
 A level cut by the endpoint's entry cap ends with a marker; an empty level says so; a level that failed shows one line per code — `workspace-file/not-found`, `outside-workspace`, `not-directory` — and the transport's own message otherwise. Reload drops every listed level and asks again for the expanded ones; collapsed levels are fetched again when they next open. A session without a working directory shows a single line instead of a tree.
 
-State lives in the type's own store, bucketed by tab id: `root`, `levels` (loading / ready / failed per absolute path), and `expanded`. The owner's `signal` ends a bucket: on abort the tab is forgotten and a listing that settles afterwards writes nothing.
+State lives in the type's own store, bucketed by tab id: `root`, `levels` (loading / ready / failed per absolute path), `expanded`, and `scrollTop`, which the body tracks locally while scrolling and commits once when it unmounts. Because the store outlives the body, switching to another sidebar tab and back remounts the tree with its levels intact and its scroll offset restored. The owner's `signal` ends a bucket: on abort the tab is forgotten, and neither a listing that settles afterwards nor the unmount's offset commit writes anything.
 
 <a id="model-experience"></a>
 ## Model Experience
diff --git a/packages/client/ui-sidebar-files/README.zh.md b/packages/client/ui-sidebar-files/README.zh.md
index fe5a10d19b..a0d0abffcd 100644
--- a/packages/client/ui-sidebar-files/README.zh.md
+++ b/packages/client/ui-sidebar-files/README.zh.md
@@ -43,7 +43,7 @@ kind: "package-reference"
 
 被端点条目上限截断的层以一条标记收尾；空层如实说明；失败的层按错误码各显示一行（`workspace-file/not-found`、`outside-workspace`、`not-directory`），其他情况显示传输层自己的消息。重新读取丢弃所有已列出的层并只对展开中的层重新请求；折叠的层在下次打开时重新拉取。没有工作目录的会话只显示一行说明，而不是树。
 
-状态保存在类型自己的存储里，按 tab id 分桶：`root`、`levels`（每个绝对路径的 loading / ready / failed）与 `expanded`。owner 的 `signal` 终结一个桶：中止时忘掉该 tab，其后才结算的列表什么也不写。
+状态保存在类型自己的存储里，按 tab id 分桶：`root`、`levels`（每个绝对路径的 loading / ready / failed）、`expanded` 与 `scrollTop`——滚动期间偏移由正文自己记录，卸载时一次性写入。存储比 body 活得久，切到其他侧栏 tab 再切回来时树带着已加载的层重新挂载，滚动位置也随之恢复。owner 的 `signal` 终结一个桶：中止时忘掉该 tab，其后才结算的列表与卸载时的偏移提交都什么也不写。
 
 <a id="model-experience"></a>
 ## 模型体验
diff --git a/packages/client/ui-sidebar-files/src/client/FilesBody.tsx b/packages/client/ui-sidebar-files/src/client/FilesBody.tsx
index 07c4b8be65..7a8c70f501 100644
--- a/packages/client/ui-sidebar-files/src/client/FilesBody.tsx
+++ b/packages/client/ui-sidebar-files/src/client/FilesBody.tsx
@@ -176,7 +176,26 @@ export function FilesBody({
   const state = useStore(store => store.byTab[tab.id])
   const pathRef = useRef<HTMLDivElement>(null)
   const pathTextRef = useRef<HTMLSpanElement>(null)
+  const bodyRef = useRef<HTMLDivElement>(null)
+  const scrollTopRef = useRef(0)
   usePathClipped(pathRef, pathTextRef, state?.root)
+  // Come back where the reader was: loaded levels outlive the body in the
+  // store, so a remounted tree lays out at its full height before this runs
+  // and the stored offset re-lands exactly. A fresh tree stores 0.
+  const seeded = state !== undefined
+  useLayoutEffect(() => {
+    const body = bodyRef.current
+    if (seeded && body !== null) {
+      body.scrollTop = state.scrollTop
+      scrollTopRef.current = body.scrollTop
+    }
+  }, [seeded])
+  // Scrolling only moves the ref; the store hears about it once, on unmount,
+  // so a scroll neither re-renders the tree nor writes after the owner's
+  // abort has forgotten the bucket.
+  useEffect(() => () => {
+    if (seeded && !signal.aborted) actions.scrolled(tab.id, scrollTopRef.current)
+  }, [seeded, signal, tab.id, actions])
   useEffect(() => {
     // A bucket gone because the record aborted must not be re-seeded by a
     // component that has not unmounted yet.
@@ -228,7 +247,12 @@ export function FilesBody({
         </button>
       </div>
       {/* jscpd:ignore-end */}
-      <div className={css.body}>
+      <div
+        ref={bodyRef}
+        className={css.body}
+        data-files-body
+        onScroll={(event) => { scrollTopRef.current = event.currentTarget.scrollTop }}
+      >
         <ul className={css.level}><Level path={state.root} tree={tree} /></ul>
       </div>
     </div>
diff --git a/packages/client/ui-sidebar-files/src/client/definition.tsx b/packages/client/ui-sidebar-files/src/client/definition.tsx
index 4397b117e6..f7cc839f80 100644
--- a/packages/client/ui-sidebar-files/src/client/definition.tsx
+++ b/packages/client/ui-sidebar-files/src/client/definition.tsx
@@ -33,6 +33,7 @@ export function filesDefinition(t: TranslateNS<'sidebarFiles'>): SidebarRightTab
     priority: 'builtin',
     title: () => t('type.label'),
     guide: [{
+      id: 'workspace',
       order: 10,
       title: () => t('guide.title'),
       description: () => t('guide.description'),
diff --git a/packages/client/ui-sidebar-files/src/client/store.ts b/packages/client/ui-sidebar-files/src/client/store.ts
index 619ed0ba30..468b8b17de 100644
--- a/packages/client/ui-sidebar-files/src/client/store.ts
+++ b/packages/client/ui-sidebar-files/src/client/store.ts
@@ -1,6 +1,6 @@
 /**
- * The file tree's view state: which directories are expanded, and what each
- * loaded level contains.
+ * The file tree's view state: which directories are expanded, what each
+ * loaded level contains, and where the body is scrolled to.
  *
  * The tree is not one resource. A directory listing per level, expanded lazily,
  * is state the type owns — so it lives in a Slot-standard exclusive store
@@ -47,6 +47,8 @@ export interface FilesTabState {
   levels: Record<string, LevelState>
   /** Expanded absolute directory paths, root included. */
   expanded: string[]
+  /** The body's scroll offset in px, so a remounted tree comes back where the reader was. */
+  scrollTop: number
 }
 
 /** Every tab's tree, keyed by tab id. */
@@ -74,6 +76,7 @@ type FilesActions = {
   loaded: (draft: FilesState, tabId: TabId, path: string, level: DirLevel) => void
   failed: (draft: FilesState, tabId: TabId, path: string, failure: RemoteFailure) => void
   toggled: (draft: FilesState, tabId: TabId, path: string) => void
+  scrolled: (draft: FilesState, tabId: TabId, scrollTop: number) => void
   reset: (draft: FilesState, tabId: TabId) => void
   forget: (draft: FilesState, tabId: TabId) => void
 }
@@ -96,7 +99,7 @@ export function createFilesStore(): EngineStoreHandle<FilesState, FilesActions>
        * @param root - absolute path of the workspace root.
        */
       start: (d, tabId: TabId, root: string) => {
-        d.byTab[tabId] = { root, levels: {}, expanded: [root] }
+        d.byTab[tabId] = { root, levels: {}, expanded: [root], scrollTop: 0 }
       },
       /**
        * Mark one directory as being listed.
@@ -141,6 +144,15 @@ export function createFilesStore(): EngineStoreHandle<FilesState, FilesActions>
         if (at >= 0) state.expanded.splice(at, 1)
         else state.expanded.push(path)
       },
+      /**
+       * Record where one tab's body is scrolled to.
+       * @param d - draft state.
+       * @param tabId - the tab being drawn.
+       * @param scrollTop - the body's scroll offset, in px.
+       */
+      scrolled: (d, tabId: TabId, scrollTop: number) => {
+        bucket(d, tabId).scrollTop = scrollTop
+      },
       /**
        * Drop every loaded level, keeping what is expanded.
        *
diff --git a/packages/client/ui-sidebar-files/tests/files-body.client.spec.tsx b/packages/client/ui-sidebar-files/tests/files-body.client.spec.tsx
index 51bf217312..e8dd9cecd5 100644
--- a/packages/client/ui-sidebar-files/tests/files-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-files/tests/files-body.client.spec.tsx
@@ -184,6 +184,28 @@ describe('FilesBody', () => {
     expect(view.container.querySelector('[data-files-reload]')?.getAttribute('aria-label')).toBe(zh.reload)
   })
 
+  it('captures the body scroll offset on unmount and restores it when a tab switch remounts the tree', async () => {
+    const { view, script, instance, remount } = mountBody()
+    await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
+    const body = view.container.querySelector('[data-files-body]')!
+    fireEvent.scroll(body, { target: { scrollTop: 120 } })
+    // Scrolling writes nothing yet: the store hears the offset once, on unmount.
+    expect(instance.getSnapshot().byTab[TAB]!.scrollTop).toBe(0)
+    view.unmount()
+    expect(instance.getSnapshot().byTab[TAB]!.scrollTop).toBe(120)
+    const back = remount()
+    expect(back.container.querySelector('[data-files-body]')!.scrollTop).toBe(120)
+  })
+
+  it('a scroll before the owner aborts is not written to a forgotten bucket', async () => {
+    const { view, script, controller, instance } = mountBody()
+    await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
+    fireEvent.scroll(view.container.querySelector('[data-files-body]')!, { target: { scrollTop: 80 } })
+    act(() => { controller.abort() })
+    view.unmount()
+    expect(instance.getSnapshot().byTab[TAB]).toBeUndefined()
+  })
+
   it('an aborted record is forgotten and not seeded again while the body is still mounted', async () => {
     const { view, script, controller, instance } = mountBody()
     await act(() => script.settle({ ok: true, value: ROOT_LEVEL }))
diff --git a/packages/client/ui-sidebar-files/tests/mount.client.tsx b/packages/client/ui-sidebar-files/tests/mount.client.tsx
index 389c383a9e..54131b5e31 100644
--- a/packages/client/ui-sidebar-files/tests/mount.client.tsx
+++ b/packages/client/ui-sidebar-files/tests/mount.client.tsx
@@ -53,6 +53,8 @@ export interface Mounted {
   readonly face: FilesInjected
   readonly controller: AbortController
   readonly tabActions: MockedTabActions
+  /** Render a fresh body over the same store and face, as a tab switch remounts it. */
+  readonly remount: () => RenderResult
 }
 
 /** One store instance, one face, one owner share. */
@@ -96,5 +98,5 @@ function harness(cwd: string | null) {
 export function mountBody(cwd: string | null = ROOT): Mounted {
   const { shared, ...hands } = harness(cwd)
   const view = render(<FilesBody {...shared as unknown as FilesBodyProps} />)
-  return { ...hands, view }
+  return { ...hands, view, remount: () => render(<FilesBody {...shared as unknown as FilesBodyProps} />) }
 }
diff --git a/packages/client/ui-sidebar-files/tests/store.client.spec.ts b/packages/client/ui-sidebar-files/tests/store.client.spec.ts
index ea364c564e..c85ec67a9a 100644
--- a/packages/client/ui-sidebar-files/tests/store.client.spec.ts
+++ b/packages/client/ui-sidebar-files/tests/store.client.spec.ts
@@ -33,7 +33,7 @@ describe('createFilesStore', () => {
     const { actions } = store
     const getSnapshot = (): ReturnType<typeof store.getSnapshot> => store.getSnapshot()
     actions.start(TAB, ROOT)
-    expect(getSnapshot().byTab[TAB]).toEqual({ root: ROOT, levels: {}, expanded: [ROOT] })
+    expect(getSnapshot().byTab[TAB]).toEqual({ root: ROOT, levels: {}, expanded: [ROOT], scrollTop: 0 })
   })
 
   it('walks one level through loading, ready, and failed', () => {
@@ -75,7 +75,15 @@ describe('createFilesStore', () => {
     actions.toggled(TAB, child)
     actions.loaded(TAB, child, LEVEL)
     actions.reset(TAB)
-    expect(getSnapshot().byTab[TAB]).toEqual({ root: ROOT, levels: {}, expanded: [ROOT, child] })
+    expect(getSnapshot().byTab[TAB]).toEqual({ root: ROOT, levels: {}, expanded: [ROOT, child], scrollTop: 0 })
+  })
+
+  it('remembers where the body is scrolled to', () => {
+    const store = createFilesStore().create()
+    const { actions } = store
+    actions.start(TAB, ROOT)
+    actions.scrolled(TAB, 120)
+    expect(store.getSnapshot().byTab[TAB]!.scrollTop).toBe(120)
   })
 
   it('refuses to write a level for a tab that was never started', () => {
diff --git a/packages/client/ui-sidebar-right/README.i18n.yaml b/packages/client/ui-sidebar-right/README.i18n.yaml
index 3384df0f37..efdcc2228d 100644
--- a/packages/client/ui-sidebar-right/README.i18n.yaml
+++ b/packages/client/ui-sidebar-right/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 packages/client/ui-sidebar-right/README.md
-README.md: 75c600edf014564894c9299422c840bce15eb8e8
-README.zh.md: 203bc30d0550234e9ed97c1ccac70bed433d0605
+README.md: e5d6e1bef68296e77c6986137bba83ad3f888f8d
+README.zh.md: 75cd092b5cc8602975340b1e434ade2abf7fb442
diff --git a/packages/client/ui-sidebar-right/README.md b/packages/client/ui-sidebar-right/README.md
index 75c600edf0..e5d6e1bef6 100644
--- a/packages/client/ui-sidebar-right/README.md
+++ b/packages/client/ui-sidebar-right/README.md
@@ -98,11 +98,13 @@ Tab owners register `registerCloseHandler(kind, handler)` through an effect. A h
 <a id="the-guide"></a>
 ## The guide
 
+Each `guide` entry has an `id` unique within its provider. The guide renders `sidebar.right.tab.guide.entry` by the active definition id, forwarding the entry id, resolved title and optional description, plus the framework `useTabInfo` hook. A provider can register a custom card under its definition id; otherwise the standard icon/title button renders. The sidebar owns width and placement, while custom components own their markup and interaction. Entry identity remains stable across sorting and unrelated registrations.
+
 A tab type can declare `multiple: true` for independent instances such as terminals. Each open receives a distinct content address, so placement and docking preserve those instances; ordinary pages retain per-pane uniqueness.
 
 Default pages depend on the number of registered guide entries, not the number of tab types or open tabs. Exactly one entry opens its page directly; zero or multiple entries open the guide. Explicitly adding a guide still opens the guide, even with one entry. The sole docked guide is the only tab that cannot close; closing any other sole tab also collapses the column. The chip, context menu, and `close` API apply the same rule.
 
-The guide tab is a muted compass over one entry capsule per `guide` entry the registered types contributed, in `order`, centred in the body; the guide has no words of its own. A capsule shows the entry's glyph — or the guide's quieter cube placeholder when the entry registered none — and its title; while at most four entries are listed, an entry that registered a `description` shows it under the title, and a longer list drops every description. Picking a capsule calls `tab.actions.openTab(entry.kind, { replaceTab: true })`, so the guide gives way to the page it opened. A pane holds at most one guide tab. The strip's add control is drawn only while its pane holds none and opens one there with `openTab('guide', { paneId, revealIfOpened: false })`, so a guide in another pane does not capture the click; opening the guide into a pane that already has one focuses it instead; a guide dragged, dropped, or docked into such a pane merges into it — the arriving guide closes and the pane's own is focused; `duplicateTab` on the guide records nothing. A split, an expanded empty root pane, and the pane a sole tab vacates by dropping on its own edge use the same default-page rule, one tab per new pane; the self-edge drop leaves the dragged tab focused. A plain `openTab('guide')` opens or focuses the guide only within the active or named pane. Splitting an empty pane does nothing and returns no new pane. The product allows two horizontal panes, initially equal, with divider ratios limited to 20%–80%. Insufficient width blocks a new split; with two panes already present, a body drop moves the tab between panes instead of creating a third. At the two-pane limit, split controls are hidden; closing back to one pane restores them.
+The guide tab is a muted compass over one entry capsule per `guide` entry the registered types contributed, in `order`, centred in the body; the guide has no words of its own. A capsule shows the entry's glyph — or the guide's quieter cube placeholder when the entry registered none — and its title; while at most four entries are listed, an entry that registered a `description` shows it under the title, and a longer list drops every description. Picking a default capsule calls `tab.actions.openTab(entry.kind, { replaceTab: true })`, so the guide gives way to the page it opened. A pane holds at most one guide tab. The strip's add control is drawn only while its pane holds none and opens one there with `openTab('guide', { paneId, revealIfOpened: false })`, so a guide in another pane does not capture the click; opening the guide into a pane that already has one focuses it instead; a guide dragged, dropped, or docked into such a pane merges into it — the arriving guide closes and the pane's own is focused; `duplicateTab` on the guide records nothing. A split, an expanded empty root pane, and the pane a sole tab vacates by dropping on its own edge use the same default-page rule, one tab per new pane; the self-edge drop leaves the dragged tab focused. A plain `openTab('guide')` opens or focuses the guide only within the active or named pane. Splitting an empty pane does nothing and returns no new pane. The product allows two horizontal panes, initially equal, with divider ratios limited to 20%–80%. Insufficient width blocks a new split; with two panes already present, a body drop moves the tab between panes instead of creating a third. At the two-pane limit, split controls are hidden; closing back to one pane restores them.
 
 <a id="copy"></a>
 ## Copy
diff --git a/packages/client/ui-sidebar-right/README.zh.md b/packages/client/ui-sidebar-right/README.zh.md
index 203bc30d05..75cd092b5c 100644
--- a/packages/client/ui-sidebar-right/README.zh.md
+++ b/packages/client/ui-sidebar-right/README.zh.md
@@ -98,11 +98,13 @@ Tab域按（Session，Tab id）保留导航、中止信号与绑定动作；私
 <a id="the-guide"></a>
 ## 引导页
 
+每个 `guide` 入口具有 provider 内唯一的 `id`。开始页按当前生效的定义 id 渲染 `sidebar.right.tab.guide.entry`，传入入口 id、解析后的标题、可选描述，以及框架提供的 `useTabInfo` hook。provider 可按自己的定义 id 注册自定义卡片；未注册时使用默认图标与标题按钮。侧栏负责宽度和排列，自定义组件负责内部结构和交互。排序或其他注册变化不会改变入口身份。
+
 终端等需要独立实例的 tab 类型可声明 `multiple: true`。每次打开都会获得独立内容地址，因此移动和停靠会保留这些实例；普通页面仍在每个格内去重。
 
 默认页取决于已注册的引导入口数，不取决于 tab 类型数或已打开的 tab 数。恰好一个入口时直接打开对应页面；没有入口或有多个入口时打开引导页。即使只有一个入口，显式添加引导页仍会打开引导页。只有作为唯一停靠 tab 的引导页不可关闭；关闭其它任何唯一 tab 时会同时收起整列。chip、上下文菜单与 `close` API 使用同一规则。
 
-引导 tab 是一枚弱化的罗盘，下方是各已注册类型贡献的每个 `guide` 条目一个入口胶囊，按 `order` 排列并在正文中居中；引导页自己没有文字。胶囊显示条目的图标——条目没注册图标时用引导页自己更浅的立方体占位符——和标题；列出的条目不超过四个时，注册了 `description` 的条目在标题下显示它，更长的列表则去掉所有描述。选中一个胶囊会调用 `tab.actions.openTab(entry.kind, { replaceTab: true })`，于是引导页让位给它打开的页。一个格最多持有一个引导 tab。tab 条的添加控件只在该格没有引导 tab 时绘制，并以 `openTab('guide', { paneId, revealIfOpened: false })` 在该格打开一个，这样别的格里的引导页不会截走这次点击；把引导页开进已有引导页的格则改为聚焦它；把引导页拖入、放入或收回到这样的格会合并进去——来者关闭，该格自己的被聚焦；对引导页 `duplicateTab` 不记录任何东西。分栏、展开且为空的根格、以及唯一 tab 拖到本格边缘分屏后腾出的格使用相同的默认页规则，每个新格一个 tab；这种本格边缘拖放让被拖的 tab 保持聚焦。普通的 `openTab('guide')` 只在活跃或指定分栏内打开或聚焦引导页。对空分栏执行 split 不产生变化，也不返回新分栏。产品最多保留左右两格，默认均分，分隔条限定在 20%～80%。宽度不足以容纳两格时不允许新分栏；已有两格时，正文拖放用于跨格移动，不再创建第三格。达到两格上限时隐藏分栏控件；关闭回单格后恢复。
+引导 tab 是一枚弱化的罗盘，下方是各已注册类型贡献的每个 `guide` 条目一个入口胶囊，按 `order` 排列并在正文中居中；引导页自己没有文字。胶囊显示条目的图标——条目没注册图标时用引导页自己更浅的立方体占位符——和标题；列出的条目不超过四个时，注册了 `description` 的条目在标题下显示它，更长的列表则去掉所有描述。点击默认胶囊会调用 `tab.actions.openTab(entry.kind, { replaceTab: true })`，于是引导页让位给它打开的页。一个格最多持有一个引导 tab。tab 条的添加控件只在该格没有引导 tab 时绘制，并以 `openTab('guide', { paneId, revealIfOpened: false })` 在该格打开一个，这样别的格里的引导页不会截走这次点击；把引导页开进已有引导页的格则改为聚焦它；把引导页拖入、放入或收回到这样的格会合并进去——来者关闭，该格自己的被聚焦；对引导页 `duplicateTab` 不记录任何东西。分栏、展开且为空的根格、以及唯一 tab 拖到本格边缘分屏后腾出的格使用相同的默认页规则，每个新格一个 tab；这种本格边缘拖放让被拖的 tab 保持聚焦。普通的 `openTab('guide')` 只在活跃或指定分栏内打开或聚焦引导页。对空分栏执行 split 不产生变化，也不返回新分栏。产品最多保留左右两格，默认均分，分隔条限定在 20%～80%。宽度不足以容纳两格时不允许新分栏；已有两格时，正文拖放用于跨格移动，不再创建第三格。达到两格上限时隐藏分栏控件；关闭回单格后恢复。
 
 <a id="copy"></a>
 ## 文案
diff --git a/packages/client/ui-sidebar-right/src/client/contract/slots.ts b/packages/client/ui-sidebar-right/src/client/contract/slots.ts
index f5ee3de8b2..da421aa39f 100644
--- a/packages/client/ui-sidebar-right/src/client/contract/slots.ts
+++ b/packages/client/ui-sidebar-right/src/client/contract/slots.ts
@@ -16,7 +16,7 @@
  *   actions that are gestures on the layout itself; this seat is for actions that
  *   mean something about the tab's content.
  *
- * TYPE HOME RATIONALE: this package declares all four at runtime, and anything
+ * TYPE HOME RATIONALE: this package declares these slots at runtime, and anything
  * registering into one already depends on it for the declaration. The types
  * therefore live with their declarer.
  */
@@ -78,6 +78,14 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
       hookContext: UseSidebarRightTabInfo
       inject: { hooks: { tabInfo: SlotHookFactory<'sidebar.right.tab.guide', UseSidebarRightTabInfo> } }
     }
+    /** One provider's guide card, with the standard card as the owner's fallback. */
+    'sidebar.right.tab.guide.entry': {
+      kind: 'keyed'
+      scope: 'session'
+      owner: SidebarRightGuideEntryOwnerProps
+      hookContext: UseSidebarRightTabInfo
+      inject: { hooks: { tabInfo: SlotHookFactory<'sidebar.right.tab.guide.entry', UseSidebarRightTabInfo> } }
+    }
     /**
      * Extra items at the end of one tab's actions menu, in registration order.
      * Entries decide their own visibility from the tab they are given. Without a
@@ -171,3 +179,11 @@ export interface SidebarRightTabMenuOwnerProps {
    */
   dismiss: () => void
 }
+
+/** Resolved guide copy and entry identity supplied to a provider's card renderer. */
+export interface SidebarRightGuideEntryOwnerProps {
+  readonly entryId: string
+  readonly kind: string
+  readonly title: string
+  readonly description?: string
+}
diff --git a/packages/client/ui-sidebar-right/src/client/index.ts b/packages/client/ui-sidebar-right/src/client/index.ts
index 5ffcbd34e1..b69ee0563c 100644
--- a/packages/client/ui-sidebar-right/src/client/index.ts
+++ b/packages/client/ui-sidebar-right/src/client/index.ts
@@ -57,7 +57,7 @@ export type {
 } from './tab-registry.ts'
 export type {
   SidebarRightTabInfo, SidebarRightTabInjected, UseSidebarRightTabInfo, SidebarRightTabActions,
-  SidebarRightTabMenuOwnerProps, SidebarRightTabNavigation, SidebarRightTabPlacement,
+  SidebarRightTabMenuOwnerProps, SidebarRightTabNavigation, SidebarRightTabPlacement, SidebarRightGuideEntryOwnerProps,
 } from './contract/slots.ts'
 export type {
   SidebarRightNavigationParams, SidebarRightResourceParams, SidebarRightResourceParamsMap,
@@ -189,6 +189,9 @@ export function apply(ctx: ClientContext): void {
       name: 'sidebar.right.pane.tab',
       key: GUIDE_ID,
       children: {
+        'sidebar.right.tab.guide.entry': {
+          kind: 'keyed', scope: 'session', inject: { hooks: { tabInfo: guideTabInfoFactory } },
+        },
         'sidebar.right.tab.guide': {
           kind: 'chain', scope: 'session', inject: { hooks: { tabInfo: guideTabInfoFactory } },
         },
diff --git a/packages/client/ui-sidebar-right/src/client/tab-info.ts b/packages/client/ui-sidebar-right/src/client/tab-info.ts
index 86812e09d1..940b86822a 100644
--- a/packages/client/ui-sidebar-right/src/client/tab-info.ts
+++ b/packages/client/ui-sidebar-right/src/client/tab-info.ts
@@ -51,10 +51,10 @@ export const tabInfoFactory: SlotHookFactory<'sidebar.right.pane.tab', UseSideba
 }
 
 /**
- * Forward the framework-bound tab hook to a guide replacement.
+ * Forward the framework-bound tab hook to guide content.
  * @param _standard - the guide's framework standard props.
  * @param useTabInfo - the enclosing tab's framework-bound reader.
  * @returns the same reader for the replacement.
  */
-export const guideTabInfoFactory: SlotHookFactory<'sidebar.right.tab.guide', UseSidebarRightTabInfo> =
-  (_standard, useTabInfo) => useTabInfo
+export const guideTabInfoFactory =
+  (_standard: unknown, useTabInfo: UseSidebarRightTabInfo): UseSidebarRightTabInfo => useTabInfo
diff --git a/packages/client/ui-sidebar-right/src/client/tab-registry.ts b/packages/client/ui-sidebar-right/src/client/tab-registry.ts
index 88f676a204..7961a5e4ad 100644
--- a/packages/client/ui-sidebar-right/src/client/tab-registry.ts
+++ b/packages/client/ui-sidebar-right/src/client/tab-registry.ts
@@ -59,6 +59,8 @@ const DEFAULT_BAND: SidebarRightTabPriority = 'extension'
 
 /** One entry capsule the guide page offers, contributed by the type it opens (picking it opens that type as a page). */
 export interface SidebarRightGuideEntry {
+  /** Stable entry identity within its provider. */
+  readonly id: string
   /** Ascending position among every registered type's entries. */
   readonly order: number
   /**
@@ -79,6 +81,8 @@ export interface SidebarRightGuideEntry {
 
 /** A guide entry as the registry lists it: with the kind of the type that contributed it, which is what picking it opens. */
 export interface SidebarRightGuideBox extends SidebarRightGuideEntry {
+  /** Active implementation identity used to dispatch the entry renderer. */
+  readonly providerId: string
   readonly kind: string
 }
 
@@ -243,6 +247,8 @@ export class SidebarRightTabRegistry {
    */
   register(definition: SidebarRightTabDefinition): () => void {
     const { id, kind } = definition
+    const entries = definition.guide ?? []
+    if (new Set(entries.map(entry => entry.id)).size !== entries.length) throw new Error(`sidebarRight: duplicate guide entry id in "${id}"`)
     const band = definition.priority ?? DEFAULT_BAND
     if (this.ids.has(id)) throw new Error(`sidebarRight: tab type id "${id}" is already registered`)
     const held = this.kinds.get(kind)
@@ -396,7 +402,7 @@ export class SidebarRightTabRegistry {
   private refresh(): void {
     this.cached = this.active().map(entry => entry.definition)
     this.guideEntries = this.cached
-      .flatMap(definition => (definition.guide ?? []).map(entry => ({ ...entry, kind: definition.kind })))
+      .flatMap(definition => (definition.guide ?? []).map(entry => ({ ...entry, kind: definition.kind, providerId: definition.id })))
       .sort((left, right) => left.order - right.order)
     notifySubscribers(this.listeners, '[ui-sidebar-right] tab registry')
   }
diff --git a/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.module.css b/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.module.css
index 484791f46e..eb4676a3e2 100644
--- a/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.module.css
+++ b/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.module.css
@@ -117,3 +117,5 @@
   flex: none;
   color: var(--dsw-alias-label-tertiary);
 }
+
+.entryCell { width: 380px; max-width: 100%; }
diff --git a/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx b/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx
index dcc46bac8f..db066153fa 100644
--- a/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx
+++ b/packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx
@@ -33,7 +33,7 @@ export interface GuideInjected {
 /** The guide body's composed props: the tab it draws, its chain child, and the entries. */
 export type GuideBodyProps =
   & PropsRuntime<'sidebar.right.pane.tab'>
-  & PropsRenderSlots<'sidebar.right.tab.guide'>
+  & PropsRenderSlots<'sidebar.right.tab.guide' | 'sidebar.right.tab.guide.entry'>
   & InjectFace<GuideInjected>
 
 /** Entry count past which the guide drops the capsules' descriptions to stay light. */
@@ -67,30 +67,36 @@ function EntryBox({ entry, described, onPick }: {
 }
 
 /** The shipped guide: the tab's own compass over the doors out of the column. */
-function ShippedGuide({ entries, onPick }: {
-  entries: readonly SidebarRightGuideBox[]
-  onPick: (entry: SidebarRightGuideBox) => void
-}): ReactNode {
+function ShippedGuide({ children }: { children: ReactNode }): ReactNode {
   return (
     <div className={css.guide} data-sidebar-right-guide>
       <span className={css.hero} aria-hidden="true"><CompassGlyph size={56} /></span>
-      {/* Keyed by position in the ordered list: one type may contribute several capsules, and `order` is not unique. */}
-      {entries.map((entry, index) => (
-        <EntryBox key={`${entry.kind}:${index}`} entry={entry} described={entries.length <= MAX_DESCRIBED_ENTRIES} onPick={onPick} />
-      ))}
+      {children}
     </div>
   )
 }
 
 /** The guide tab's body, replaceable through its chain child. */
-export function GuideBody({ useTabInfo, useGuideEntries, renderSlotChain }: GuideBodyProps): ReactNode {
+export function GuideBody({ useTabInfo, useGuideEntries, renderSlot, renderSlotChain }: GuideBodyProps): ReactNode {
   const { tab } = useTabInfo()
   const entries = useGuideEntries(entries => entries)
   const options = {
     hookContext: useTabInfo,
     fallback: (
-      <ShippedGuide entries={entries}
-        onPick={(entry) => { tab.actions.openTab(entry.kind, { replaceTab: true }) }} />
+      <ShippedGuide>{entries.map((entry) => {
+        const described = entries.length <= MAX_DESCRIBED_ENTRIES
+        const description = described ? entry.description?.() : undefined
+        return <div key={JSON.stringify([entry.providerId, entry.id])} className={css.entryCell}>
+          {renderSlot('sidebar.right.tab.guide.entry', {
+            entryId: entry.id, kind: entry.kind, title: entry.title(),
+            ...description === undefined ? {} : { description },
+          }, {
+            entryKey: entry.providerId, hookContext: useTabInfo,
+            fallback: <EntryBox entry={entry} described={described}
+              onPick={(selected) => { tab.actions.openTab(selected.kind, { replaceTab: true }) }} />,
+          })}
+        </div>
+      })}</ShippedGuide>
     ),
   } satisfies ChainRenderOpts & { hookContext: HookContextOf<'sidebar.right.tab.guide'> }
   return renderSlotChain('sidebar.right.tab.guide', {}, options)
diff --git a/packages/client/ui-sidebar-right/tests/apply.client.spec.ts b/packages/client/ui-sidebar-right/tests/apply.client.spec.ts
index 62617ccca3..72d026afe1 100644
--- a/packages/client/ui-sidebar-right/tests/apply.client.spec.ts
+++ b/packages/client/ui-sidebar-right/tests/apply.client.spec.ts
@@ -179,7 +179,7 @@ describe('ui-sidebar-right apply', () => {
       id: 'spec/files',
       kind: 'files',
       title: () => 'Files',
-      guide: [{ order: 10, title: () => 'Files' }],
+      guide: [{ id: 'default', order: 10, title: () => 'Files' }],
     })
     expect(seen).toHaveBeenCalledOnce()
     expect(guideEntries.getSnapshot().map(entry => entry.kind)).toEqual(['files'])
diff --git a/packages/client/ui-sidebar-right/tests/guide-body.client.spec.tsx b/packages/client/ui-sidebar-right/tests/guide-body.client.spec.tsx
index d809426429..d17314cab2 100644
--- a/packages/client/ui-sidebar-right/tests/guide-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-right/tests/guide-body.client.spec.tsx
@@ -30,7 +30,7 @@ function Glyph({ size }: IconProps): ReactNode {
 /** One entry capsule as the registry lists it. */
 function box(kind: string, order: number, icon?: SidebarRightGuideBox['icon'], description?: string): SidebarRightGuideBox {
   return {
-    kind,
+    kind, providerId: `provider/${kind}`, id: `${kind}-${order}`,
     order,
     title: () => `${kind} title`,
     ...icon === undefined ? {} : { icon },
@@ -42,7 +42,7 @@ function box(kind: string, order: number, icon?: SidebarRightGuideBox['icon'], d
  * Mount the body with the entries observable and a chain that renders its
  * fallback, which is what the chain does with no registrant.
  */
-function mountGuide(entries: readonly SidebarRightGuideBox[]) {
+function mountGuide(entries: readonly SidebarRightGuideBox[], custom?: (key: string) => ReactNode) {
   const guideEntries = createSnapshotStore<readonly SidebarRightGuideBox[]>(entries)
   const openTab = vi.fn()
   const renderSlot = vi.fn((_seat: string, _owner: unknown, options: { fallback: ReactNode }) => options.fallback)
@@ -50,11 +50,13 @@ function mountGuide(entries: readonly SidebarRightGuideBox[]) {
     useTabInfo: () => ({ tab: { ...TAB, actions: { openResource: vi.fn(), openTab, close: vi.fn() } } }),
     useGuideEntries: bindSnapshotSelector(guideEntries),
     renderSlotChain: renderSlot,
+    renderSlot: vi.fn((_slot: string, _owner: unknown, options: { entryKey: string; fallback: ReactNode }) =>
+      custom?.(options.entryKey) ?? options.fallback),
   } as unknown as GuideBodyProps
   const view = render(<GuideBody {...props} />)
   const boxes = (): string[] =>
     [...view.container.querySelectorAll('[data-sidebar-right-guide-entry]')].map(node => node.getAttribute('data-sidebar-right-guide-entry') ?? '')
-  return { view, guideEntries, openTab, renderSlot, boxes, useTabInfo: props.useTabInfo }
+  return { view, guideEntries, openTab, renderSlot, entrySlot: props.renderSlot, boxes, useTabInfo: props.useTabInfo }
 }
 
 describe('GuideBody', () => {
@@ -120,7 +122,10 @@ describe('GuideBody', () => {
   it('keeps two boxes of one type at the same order apart', () => {
     const errors = vi.spyOn(console, 'error').mockImplementation(() => {})
     try {
-      const { boxes } = mountGuide([box('notes', 10), box('notes', 10)])
+      const { boxes } = mountGuide([
+        { ...box('notes', 10), providerId: 'a:b', id: 'c' },
+        { ...box('notes', 10), providerId: 'a', id: 'b:c' },
+      ])
       expect(boxes()).toEqual(['notes', 'notes'])
       // React reports colliding keys through console.error; two boxes rendered
       // without one is the whole assertion.
@@ -131,3 +136,17 @@ describe('GuideBody', () => {
     }
   })
 })
+
+it('dispatches custom guide content by active provider identity and retains the fallback for other entries', () => {
+  const custom = (key: string) => key === 'extension/terminal' ? <button>Choose a shell</button> : undefined
+  const terminal = { ...box('terminal', 20), providerId: 'extension/terminal' }
+  const h = mountGuide([box('files', 10), terminal], custom)
+  expect(h.view.getByText('Choose a shell')).toBeDefined()
+  expect(h.view.getByText('files title')).toBeDefined()
+  expect(h.entrySlot).toHaveBeenCalledWith('sidebar.right.tab.guide.entry', {
+    entryId: terminal.id, kind: 'terminal', title: 'terminal title',
+  }, expect.objectContaining({ entryKey: 'extension/terminal', hookContext: h.useTabInfo }))
+  act(() => { h.guideEntries.set([{ ...terminal, providerId: 'builtin/terminal' }]) })
+  expect(h.view.queryByText('Choose a shell')).toBeNull()
+  expect(h.view.getByText('terminal title')).toBeDefined()
+})
diff --git a/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx b/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx
index 58c0368169..d493ed88ce 100644
--- a/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx
+++ b/packages/client/ui-sidebar-right/tests/seat.client.spec.tsx
@@ -94,7 +94,7 @@ async function mountSeat(viewportWidth = 1440, canShow = true, entryCount = 0) {
     runtime.ctx.sidebarRightTabs.register({
       id: 'test/text', kind: 'text', priority: 'builtin', patterns: ['dsh-resource://file/**'],
       title: address => address.slice(address.lastIndexOf('/') + 1),
-      guide: Array.from({ length: entryCount }, (_, order) => ({ order, title: () => 'Test', description: () => 'Test page' })),
+      guide: Array.from({ length: entryCount }, (_, order) => ({ id: String(order), order, title: () => 'Test', description: () => 'Test page' })),
     })
     runtime.slots.register({ name: 'sidebar.right.pane.tab', key: 'test/text' }, Body)
     runtime.slots.register({ name: 'sidebar.right.pane.tab.title', key: 'test/text' }, Title)
@@ -459,7 +459,7 @@ describe('slot-owned useTabInfo', () => {
     await act(async () => {
       h.runtime.ctx.sidebarRightTabs.register({
         id: 'test/files', kind: 'files', title: () => 'Files',
-        guide: [{ order: 1, title: () => 'Files' }],
+        guide: [{ id: 'default', order: 1, title: () => 'Files' }],
       })
     })
     expect(h.view.container.querySelector('[data-sidebar-right-guide-entry="files"]')).not.toBeNull()
diff --git a/packages/client/ui-sidebar-right/tests/tab-registry.client.spec.ts b/packages/client/ui-sidebar-right/tests/tab-registry.client.spec.ts
index 3cfca82d79..edbe1171b6 100644
--- a/packages/client/ui-sidebar-right/tests/tab-registry.client.spec.ts
+++ b/packages/client/ui-sidebar-right/tests/tab-registry.client.spec.ts
@@ -210,7 +210,7 @@ describe('SidebarRightTabRegistry — ids and page types', () => {
       kind: 'files',
       priority: 'builtin',
       title: () => 'Files',
-      guide: [{ order: 10, title: () => 'Files' }],
+      guide: [{ id: 'default', order: 10, title: () => 'Files' }],
     })
     expect(ranked(registry, 'dsh-resource://file/session/s/a.txt')).toEqual([])
     expect(registry.get('files')?.title('x')).toBe('Files')
@@ -258,7 +258,7 @@ describe('SidebarRightTabRegistry — lifetime', () => {
 
   it('collects every type\'s guide entries in order, reference-stable between changes', () => {
     const registry = new SidebarRightTabRegistry(new Context())
-    const entry = (order: number) => ({ order, title: () => `#${order}` })
+    const entry = (order: number) => ({ id: String(order), order, title: () => `#${order}` })
     registry.register(typeFor('files', [], { guide: [entry(10)] }))
     const first = registry.guide()
     expect(registry.guide()).toBe(first)
@@ -290,3 +290,14 @@ describe('SidebarRightTabRegistry — lifetime', () => {
     expect(registry.entries()).not.toBe(first)
   })
 })
+
+it('uses the active provider id for guide dispatch and refuses duplicate entry identities', () => {
+  const registry = new SidebarRightTabRegistry(new Context())
+  const guide = [{ id: 'new', order: 10, title: () => 'Terminal' }]
+  registry.register(typeFor('terminal', [], { id: 'builtin/terminal', priority: 'builtin', guide }))
+  const remove = registry.register(typeFor('terminal', [], { id: 'extension/terminal', priority: 'extension', guide }))
+  expect(registry.guide()[0]?.providerId).toBe('extension/terminal')
+  remove()
+  expect(registry.guide()[0]?.providerId).toBe('builtin/terminal')
+  expect(() => registry.register(typeFor('duplicate', [], { guide: [guide[0]!, guide[0]!] }))).toThrow('duplicate guide entry id')
+})
diff --git a/packages/client/ui-sidebar-terminal/README.i18n.yaml b/packages/client/ui-sidebar-terminal/README.i18n.yaml
index ad7c48a193..f6fa821c73 100644
--- a/packages/client/ui-sidebar-terminal/README.i18n.yaml
+++ b/packages/client/ui-sidebar-terminal/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 packages/client/ui-sidebar-terminal/README.md
-README.md: dec4c0a88649b74e90afa23ef07d3f11a9dc67cb
-README.zh.md: a10cde602ad4edfd13652a93535c4f5d7fd26b52
+README.md: 8efe326007a816e6cde00942ee8c411c86e82ff6
+README.zh.md: 9f48103b1ebbcbb8507f92214b1499abb42f362a
diff --git a/packages/client/ui-sidebar-terminal/README.md b/packages/client/ui-sidebar-terminal/README.md
index dec4c0a886..8efe326007 100644
--- a/packages/client/ui-sidebar-terminal/README.md
+++ b/packages/client/ui-sidebar-terminal/README.md
@@ -25,7 +25,7 @@ Choose an installed shell from the right sidebar's Start page to run commands in
 <a id="use-this-package"></a>
 ## Use this package
 
-Open the right sidebar and select **New terminal** on the Start page; first select **New tab** when another content tab is open. Choose an installed **Shell** and select **Start terminal**. The last selected shell is preselected from localStorage; first use or an unavailable saved choice selects the current default. Use the sidebar's **New tab** control to open more terminals.
+Open the right sidebar and click **New terminal** to open the remembered available shell immediately. Its adjacent arrow opens the installed-shell menu; selecting an item remembers it and opens that shell directly. Discovery runs when the menu opens and does not allocate a terminal. A failed lookup offers Retry in the menu. Use **New tab** to return to the guide and open another terminal.
 
 Double-click the terminal's tab title to rename it. **Take control** makes the current attachment writable when another page owns input. A failed connection offers **Reconnect**. An exited shell remains visible with its exit code and never restarts automatically. Exited terminals count toward the Session limit; close unused tabs when the limit is reached.
 
@@ -33,6 +33,8 @@ Closing or replacing a terminal tab removes it immediately and ends its process
 
 Displaying a Session after a page reload reopens its retained Host terminals as new tabs. A recovery failure offers **Retry terminal recovery**. A recovered process that disappears reports an error instead of starting another shell. The [sidebar layout remains memory-only](../../client/ui-sidebar-right/README.md#state).
 
+The terminal background, default text, cursor, and selection follow the DSH theme, including system preference and theme-token overrides. Theme changes preserve the running shell, output, and application OSC color overrides. Reset commands restore colors to the current DSH defaults. xterm adjusts text toward 4.5:1 contrast; the cursor keeps at least 3:1 contrast against its cell background, including Vim colorschemes.
+
 <a id="understand-the-implementation"></a>
 ## Understand the implementation
 
@@ -67,6 +69,7 @@ None; terminal output travels only between the browser and Host.
 
 - Shell discovery or native PTY startup can fail. The tab reports the failure without launching a different shell.
 - Completion menus and inline suggestions depend on shell configuration. The Web UI adds no independent completion engine.
+- Application OSC color overrides are retained by the mounted renderer; a newly opened renderer cannot recover them from the Host screen snapshot.
 - Terminal history is bounded. The feature does not send terminal output to the Agent, provide split terminal panes inside a tab, or restore processes after Host restart.
 
 <a id="dev-note"></a>
diff --git a/packages/client/ui-sidebar-terminal/README.zh.md b/packages/client/ui-sidebar-terminal/README.zh.md
index a10cde602a..9f48103b1e 100644
--- a/packages/client/ui-sidebar-terminal/README.zh.md
+++ b/packages/client/ui-sidebar-terminal/README.zh.md
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用此包
 
-展开右侧栏，在开始页选择**新建终端**；已有其他标签页时，先选择**新标签页**。选择已安装的 **Shell**，再点击**启动终端**。localStorage 会记住上次选择的 shell 并预选；首次使用或已保存选项不可用时，预选当前默认项。通过侧栏的**新标签页**控件打开更多终端。
+展开右侧栏，点击**新建终端**即可直接打开上次选择且仍可用的 shell。旁边的箭头展开已安装 shell 菜单；选择后立即记住该项并打开终端。菜单展开时才查询 shell，不分配终端进程；查询失败可在菜单内重试。通过**新标签页**回到开始页并打开更多终端。
 
 双击终端标签页标题即可重命名。另一页面持有输入权时，**接管输入**让当前连接可写。连接失败时可以**重新连接**。shell 退出后仍显示屏幕和退出码，不自动重启。 已退出的终端计入 Session 数量上限；达到上限时请关闭不用的标签页。
 
@@ -33,6 +33,8 @@ kind: "package-reference"
 
 刷新页面后显示某个 Session，会把 Host 保留的终端重新打开为新标签页。恢复失败时可点击**重试恢复终端**。恢复目标进程消失时显示错误，不启动另一个 shell。[侧栏布局仅保存在内存中](../../client/ui-sidebar-right/README.zh.md#state)。
 
+终端背景、默认文字、光标和选区跟随 DSH 主题，包括系统偏好和主题令牌覆盖。切换主题会保留运行中的 shell、输出和应用通过 OSC 设置的颜色。颜色重置命令恢复到当前 DSH 默认值。xterm 将文字对比度调整到 4.5:1；光标与所在单元格背景保持至少 3:1 的对比度，包括 Vim 配色方案。
+
 <a id="understand-the-implementation"></a>
 ## 了解实现
 
@@ -67,6 +69,7 @@ Session header contribution 查询 Host 终端并打开恢复标签页。导航
 
 - 默认 shell 或原生 PTY 可能启动失败。标签页显示错误，不启动其他 shell。
 - 补全菜单和内联建议取决于 shell 配置，Web UI 不提供独立补全引擎。
+- 应用的 OSC 颜色覆盖由已挂载的渲染器保留；新打开的渲染器无法从 Host 屏幕快照恢复这些颜色。
 - 终端历史有上限。此功能不向 Agent 发送终端输出，不在单个标签页内拆分终端，也不在 Host 重启后恢复进程。
 
 <a id="dev-note"></a>
diff --git a/packages/client/ui-sidebar-terminal/package.json b/packages/client/ui-sidebar-terminal/package.json
index 0f7ebb30d0..1d546c4ab9 100644
--- a/packages/client/ui-sidebar-terminal/package.json
+++ b/packages/client/ui-sidebar-terminal/package.json
@@ -30,7 +30,8 @@
       "inject": [
         "@deepseek-ai/dsh-api-terminal-controller",
         "@deepseek-ai/dsh-client-ui-sidebar-right",
-        "@deepseek-ai/dsh-api-remotes"
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-theme"
       ],
       "platform": "web"
     }
@@ -66,7 +67,8 @@
     "@xterm/xterm": "^6.0.0",
     "@xterm/addon-fit": "^0.11.0",
     "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
-    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^"
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-theme": "workspace:^"
   },
   "files": [
     "lib/index.js",
diff --git a/packages/client/ui-sidebar-terminal/src/client/TerminalBody.module.css b/packages/client/ui-sidebar-terminal/src/client/TerminalBody.module.css
index 80fa425b11..5b17dda66f 100644
--- a/packages/client/ui-sidebar-terminal/src/client/TerminalBody.module.css
+++ b/packages/client/ui-sidebar-terminal/src/client/TerminalBody.module.css
@@ -1,14 +1,20 @@
 .root { display: flex; flex: 1; flex-direction: column; box-sizing: border-box; height: 100%; min-height: 0; padding-top: 8px; color: var(--dsw-alias-label-primary); font-size: 13px; }
 .title { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .name { width: 120px; min-width: 48px; max-width: 100%; padding: 0 4px; color: inherit; font: inherit; background: var(--dsw-alias-bg-l1); border: 0.5px solid var(--dsw-alias-border-l3); border-radius: 4px; outline: none; }
-.screen { flex: 1; min-height: 0; min-width: 0; overflow: hidden; padding: 8px; background: #17191d; }
+.screen { flex: 1; min-height: 0; min-width: 0; overflow: hidden; padding: 8px; color: var(--dsw-alias-label-primary); background: var(--dsw-alias-bg-base); }
 .screen :global(.xterm) { height: 100%; }
+.screen :global(.xterm-viewport) { background: var(--dsw-alias-bg-base); }
 .status { display: flex; align-items: center; gap: 8px; padding: 5px 12px; background: var(--dsw-alias-bg-l2); }
 .status button { padding: 6px 10px; border: 0.5px solid var(--dsw-alias-border-l3); border-radius: 6px; color: inherit; background: transparent; cursor: pointer; }
 .status button:hover { background: var(--dsw-alias-bg-l2); }
 .error { margin: 0; padding: 10px 12px; overflow-wrap: anywhere; color: var(--dsw-alias-label-primary); background: var(--dsw-alias-bg-l2); }
-.launch { display: flex; align-items: end; flex-wrap: wrap; gap: 8px; padding: 12px; }
-.shellField { display: flex; flex: 1; flex-direction: column; gap: 6px; min-width: 0; }
-.shellMenu { width: 100%; min-width: 0; }
-.shellTrigger { width: 100%; min-width: 0; justify-content: space-between; gap: 8px; }
-.shellValue { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+/* Cursor colors depend on its cell, so they must not update xterm's shared ANSI theme. */
+.screen :global(.xterm-cursor) { opacity: 1; }
+.screen :global(.xterm .xterm-rows .xterm-cursor.xterm-cursor-block) { background-color: var(--terminal-cursor); color: var(--terminal-cursor-accent); }
+.screen :global(.xterm .xterm-rows .xterm-cursor.xterm-cursor-block:not(.xterm-cursor-blink)) { background-color: var(--terminal-cursor) !important; color: var(--terminal-cursor-accent) !important; }
+.screen :global(.xterm .xterm-rows .xterm-cursor.xterm-cursor-outline) { outline-color: var(--terminal-cursor); }
+.screen :global(.xterm .xterm-rows .xterm-cursor.xterm-cursor-bar) { box-shadow: 1px 0 0 var(--terminal-cursor) inset; }
+.screen :global(.xterm .xterm-rows .xterm-cursor.xterm-cursor-underline) { border-bottom-color: var(--terminal-cursor); }
+.screen :global(.xterm .xterm-rows.xterm-focus .xterm-cursor.xterm-cursor-block.xterm-cursor-blink) { animation: terminal-cursor-blink 1s step-end infinite; }
+@keyframes terminal-cursor-blink { 0% { background-color: var(--terminal-cursor); color: var(--terminal-cursor-accent); } 50% { background-color: var(--terminal-cursor-cell-background); color: var(--terminal-cursor-cell-foreground); } }
diff --git a/packages/client/ui-sidebar-terminal/src/client/TerminalBody.tsx b/packages/client/ui-sidebar-terminal/src/client/TerminalBody.tsx
index d9adf4fae2..2217d85073 100644
--- a/packages/client/ui-sidebar-terminal/src/client/TerminalBody.tsx
+++ b/packages/client/ui-sidebar-terminal/src/client/TerminalBody.tsx
@@ -1,25 +1,28 @@
 /** Sidebar terminal screen and connection recovery. */
-import { useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } from 'react'
-import { Button, Menu, IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { useEffect, useLayoutEffect, useRef, type ReactNode } from 'react'
 import { Terminal } from '@xterm/xterm'
 import { FitAddon } from '@xterm/addon-fit'
 import type { TerminalViewState, TerminalView } from '@deepseek-ai/dsh-api-terminal-controller/client'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import type { TerminalInjected } from './face.ts'
+import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
+import type { TerminalBodyInjected } from './face.ts'
 import type {} from './locales.ts'
 import '@xterm/xterm/css/xterm.css'
 import css from './TerminalBody.module.css'
+import { TerminalTheme } from './terminal-theme.ts'
+import { observeTerminalCursor } from './terminal-cursor.ts'
 
 /** Standard sidebar owner share plus terminal model and localized copy. */
-export type TerminalBodyProps = PropsRuntime<'sidebar.right.pane.tab'> & PropsLocale<'sidebarTerminal'> & InjectFace<TerminalInjected>
+export type TerminalBodyProps = PropsRuntime<'sidebar.right.pane.tab'> & PropsLocale<'sidebarTerminal'> & InjectFace<TerminalBodyInjected>
 
 /**
- * Offer shell selection for a new terminal or mount a restored screen.
+ * Render the retained terminal with the application theme.
  * @param props - sidebar occurrence, model lookup and translated copy.
  * @returns the terminal screen and any pending or exceptional state.
  */
-export function TerminalBody({ useTabInfo, useTerminal, view, t }: TerminalBodyProps): ReactNode {
+export function TerminalBody({ useTabInfo, useTerminal, useTheme, view, t }: TerminalBodyProps): ReactNode {
   const { tab } = useTabInfo()
+  const theme = useTheme(value => value)
   const model = view(tab.id)
   const state = useTerminal(tab.id)
   useEffect(() => model.mount(), [model])
@@ -35,7 +38,6 @@ export function TerminalBody({ useTabInfo, useTerminal, view, t }: TerminalBodyP
   const readOnly = state.phase === 'connected' && state.info?.state === 'running' && !state.writable
   return (
     <section className={css.root} data-sidebar-terminal>
-      {state.phase === 'selecting' && <TerminalLauncher state={state} model={model} t={t} />}
       {(status !== undefined || retry || readOnly) && <div className={css.status} role="status">
         {status}
         {readOnly && <>{t('readonly')} <button type="button" onClick={() => { model.connect() }}>{t('control')}</button></>}
@@ -43,63 +45,37 @@ export function TerminalBody({ useTabInfo, useTerminal, view, t }: TerminalBodyP
           ? <button type="button" onClick={() => { void model.refresh() }}>{t('retry')}</button>
           : <button type="button" onClick={() => { model.connect() }}>{t('reconnect')}</button>)}
       </div>}
-      {state.info !== undefined && <TerminalScreen state={state} model={model} visible={tab.visible} label={t('title')} />}
+      {state.info !== undefined && <TerminalScreen state={state} model={model} visible={tab.visible} label={t('title')} theme={theme} />}
       {error !== undefined && <p className={css.error} role="alert">{t('failed', { message: error })}</p>}
     </section>
   )
 }
 
-function TerminalLauncher({ state, model, t }: {
-  state: TerminalViewState
-  model: TerminalView
-  t: TerminalBodyProps['t']
-}): ReactNode {
-  const [open, setOpen] = useState(false)
-  const selectionId = useId()
-  const selected = state.shells?.find(shell => shell.path === state.selectedShell)
-  return <form className={css.launch} onSubmit={(event) => { event.preventDefault(); void model.start() }}>
-    <div className={css.shellField}>
-      <span>{t('shell')}</span>
-      <Menu
-        open={open} autoFocus portal className={css.shellMenu}
-        items={state.shells?.map(shell => ({ id: shell.path, label: `${shell.name} — ${shell.path}` })) ?? []}
-        selectedId={state.selectedShell}
-        onClose={() => { setOpen(false) }}
-        onSelect={(path) => { model.selectShell(path); setOpen(false) }}
-        anchor={<Button
-          variant="outline" className={css.shellTrigger}
-          aria-label={t('shell')} aria-describedby={selectionId} aria-haspopup="menu" aria-expanded={open}
-          disabled={selected === undefined} onClick={() => { setOpen(value => !value) }}
-        >
-          <span id={selectionId} className={css.shellValue}>{selected === undefined ? t('shell') : `${selected.name} — ${selected.path}`}</span>
-          <span aria-hidden="true"><IconChevronDownOutline14 /></span>
-        </Button>}
-      />
-    </div>
-    <Button type="submit" variant="outline" disabled={selected === undefined}>{t('start')}</Button>
-  </form>
-}
-
 /* oxlint-disable typescript/no-non-null-assertion -- React sets the DOM ref, then these effects initialize and use the emulator. */
-function TerminalScreen({ state, model, visible, label }: {
+function TerminalScreen({ state, model, visible, label, theme }: {
   state: TerminalViewState
   model: TerminalView
   visible: boolean
   label: string
+  theme: ThemeSnapshot
 }): ReactNode {
   const element = useRef<HTMLDivElement>(null)
   const terminal = useRef<Terminal>()
   const fit = useRef<FitAddon>()
+  const colors = useRef<TerminalTheme>()
   const lastRevision = useRef(0)
   const current = useRef({ state, visible })
   current.current = { state, visible }
 
   useLayoutEffect(() => {
     const node = element.current!
-    const xterm = new Terminal({ cursorBlink: true, fontSize: 13, fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace', scrollback: current.current.state.environment?.scrollback ?? 0, theme: { background: '#17191d', foreground: '#e7e9ee' } })
+    const xterm = new Terminal({ minimumContrastRatio: 4.5, cursorBlink: true, fontSize: 13, fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace', scrollback: current.current.state.environment?.scrollback ?? 0 })
     const addon = new FitAddon()
     xterm.loadAddon(addon)
     xterm.open(node)
+    const palette = new TerminalTheme(xterm)
+    colors.current = palette
+    const cursor = observeTerminalCursor(xterm, node, () => palette.cursor)
     xterm.textarea?.setAttribute('aria-label', label)
     terminal.current = xterm
     fit.current = addon
@@ -114,12 +90,19 @@ function TerminalScreen({ state, model, visible, label }: {
     return () => {
       observer.disconnect()
       input.dispose()
+      cursor.dispose()
+      palette.dispose()
       xterm.dispose()
       terminal.current = undefined
       fit.current = undefined
     }
   }, [model])
 
+  useLayoutEffect(() => {
+    const style = getComputedStyle(element.current!)
+    colors.current!.update(style.backgroundColor, style.color)
+  }, [theme, model])
+
   useLayoutEffect(() => {
     const xterm = terminal.current!
     const render = state.render
diff --git a/packages/client/ui-sidebar-terminal/src/client/TerminalGuide.module.css b/packages/client/ui-sidebar-terminal/src/client/TerminalGuide.module.css
new file mode 100644
index 0000000000..3380810d55
--- /dev/null
+++ b/packages/client/ui-sidebar-terminal/src/client/TerminalGuide.module.css
@@ -0,0 +1,8 @@
+.entry { box-sizing: border-box; display: flex; align-items: stretch; width: 100%; overflow: hidden; border: 0.5px solid var(--dsw-alias-border-l4); border-radius: 24px; background: var(--dsw-alias-bg-layer-1); }
+.main { flex: 1; justify-content: flex-start; gap: 14px; min-width: 0; height: auto; min-height: 56px; padding: 14px 20px; border-radius: 24px 0 0 24px; text-align: left; }
+.icon { flex: none; }
+.text { display: flex; flex-direction: column; gap: 3px; min-width: 0; }
+.title { overflow: hidden; color: var(--dsw-alias-label-primary); font-size: 15px; line-height: 1.4; white-space: nowrap; text-overflow: ellipsis; }
+.description { overflow: hidden; color: var(--dsw-alias-label-caption); font-size: 13px; line-height: 1.4; white-space: nowrap; text-overflow: ellipsis; }
+.trigger { align-self: stretch; flex: none; height: auto; width: 44px; padding: 0; border-radius: 0 24px 24px 0; }
+.menu { display: flex; align-self: stretch; flex: none; }
diff --git a/packages/client/ui-sidebar-terminal/src/client/TerminalGuide.tsx b/packages/client/ui-sidebar-terminal/src/client/TerminalGuide.tsx
new file mode 100644
index 0000000000..68fb351686
--- /dev/null
+++ b/packages/client/ui-sidebar-terminal/src/client/TerminalGuide.tsx
@@ -0,0 +1,74 @@
+/** Shell launch menu owned by the terminal provider's guide entry. */
+import { useEffect, useState, type ReactNode } from 'react'
+import { Button, IconChevronDownOutline14, Menu } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { TerminalLaunchShells } from '@deepseek-ai/dsh-api-terminal-controller/client'
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+import type {} from './locales.ts'
+import { TerminalGuideIcon } from './TerminalIcon.tsx'
+import css from './TerminalGuide.module.css'
+
+/** Provider-owned discovery and browser preference writes. */
+export interface TerminalGuideInjected {
+  /** @param signal - open menu lifetime. @returns current Host choices and browser preference. */
+  readonly loadShells: (signal: AbortSignal) => Promise<TerminalLaunchShells>
+  /** @param path - Host-discovered shell selected for the next terminal. */
+  readonly selectShell: (path: string) => void
+}
+
+/** Session guide owner props, framework hooks and terminal actions. */
+export type TerminalGuideProps = PropsRuntime<'sidebar.right.tab.guide.entry'> & PropsLocale<'sidebarTerminal'> & InjectFace<TerminalGuideInjected>
+
+type MenuState = { phase: 'loading' } | { phase: 'ready'; choices: TerminalLaunchShells } | { phase: 'failed'; message: string }
+
+/**
+ * Open the remembered shell from the card or choose another shell from its menu.
+ * @param props - guide copy, enclosing tab actions and cancellable discovery.
+ * @returns separate launch and menu buttons within one guide card.
+ */
+export function TerminalGuide({ title, description, kind, useTabInfo, loadShells, selectShell, t }: TerminalGuideProps): ReactNode {
+  const { tab } = useTabInfo()
+  const [open, setOpen] = useState(false)
+  const [attempt, setAttempt] = useState(0)
+  const [state, setState] = useState<MenuState>({ phase: 'loading' })
+  useEffect(() => {
+    if (!open) return
+    const lifetime = new AbortController()
+    void loadShells(lifetime.signal).then((choices) => {
+      if (!lifetime.signal.aborted) setState({ phase: 'ready', choices })
+    }, (error: unknown) => {
+      if (!lifetime.signal.aborted) setState({ phase: 'failed', message: error instanceof Error ? error.message : String(error) })
+    })
+    return () => { lifetime.abort() }
+  }, [open, attempt, loadShells])
+  const items = state.phase === 'ready'
+    ? state.choices.shells.map(shell => ({ id: shell.path, label: shell.name }))
+    : state.phase === 'loading'
+      ? [{ id: 'loading', label: t('shellLoading'), disabled: true }]
+      : [{ id: 'error', label: t('failed', { message: state.message }), disabled: true }, { id: 'retry', label: t('retry') }]
+  return <div className={css.entry} data-sidebar-right-guide-entry={kind}>
+    <Button variant="ghost" className={css.main} onClick={() => { tab.actions.openTab('terminal', { replaceTab: true }) }}>
+      <TerminalGuideIcon size={description === undefined ? 22 : 26} className={css.icon} />
+      <span className={css.text}>
+        <span className={css.title}>{title}</span>
+        {description !== undefined && <span className={css.description}>{description}</span>}
+      </span>
+    </Button>
+    <Menu
+      open={open} portal autoFocus align="end" className={css.menu}
+      items={items.length === 0 ? [{ id: 'empty', label: t('shellEmpty'), disabled: true }] : items}
+      selectedId={state.phase === 'ready' ? state.choices.selectedShell : undefined}
+      onClose={() => { setOpen(false) }}
+      onSelect={(path) => {
+        if (state.phase === 'failed') { setState({ phase: 'loading' }); setAttempt(value => value + 1); return }
+        selectShell(path)
+        setOpen(false)
+        tab.actions.openTab('terminal', { replaceTab: true, params: { shellPath: path } })
+      }}
+      anchor={<Button variant="ghost" className={css.trigger} aria-label={t('shell')} aria-haspopup="menu" aria-expanded={open}
+        onClick={() => { setState({ phase: 'loading' }); setOpen(value => !value) }}>
+        <IconChevronDownOutline14 />
+      </Button>}
+    />
+  </div>
+}
diff --git a/packages/client/ui-sidebar-terminal/src/client/face.ts b/packages/client/ui-sidebar-terminal/src/client/face.ts
index 95920e23b1..a2be92c73c 100644
--- a/packages/client/ui-sidebar-terminal/src/client/face.ts
+++ b/packages/client/ui-sidebar-terminal/src/client/face.ts
@@ -2,6 +2,7 @@
 import type { WebTerminalId } from '@deepseek-ai/dsh-api-terminal-controller/types'
 import type { TerminalView, TerminalViewState } from '@deepseek-ai/dsh-api-terminal-controller/client'
 import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots'
+import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
 
 /** The terminal's React-free model is resolved by sidebar occurrence. */
 export interface TerminalInjected {
@@ -11,9 +12,14 @@ export interface TerminalInjected {
 }
 
 
+/** The terminal screen follows the resolved application theme through a framework hook. */
+export interface TerminalBodyInjected extends TerminalInjected {
+  readonly hooks: { readonly theme: HostObservable<ThemeSnapshot> }
+}
+
 declare module '@deepseek-ai/dsh-client-ui-sidebar-right/client' {
   interface SidebarRightTabParamsMap {
     /** An existing Host terminal selected from the Session terminal list. */
-    terminal: { terminalId: WebTerminalId }
+    terminal: { terminalId: WebTerminalId } | { shellPath: string }
   }
 }
diff --git a/packages/client/ui-sidebar-terminal/src/client/index.ts b/packages/client/ui-sidebar-terminal/src/client/index.ts
index cf71fb2f87..50c9b642ee 100644
--- a/packages/client/ui-sidebar-terminal/src/client/index.ts
+++ b/packages/client/ui-sidebar-terminal/src/client/index.ts
@@ -1,23 +1,25 @@
 /** Register interactive terminal tabs and explicit process cleanup with the sidebar. */
 import type { Context } from '@deepseek-ai/cordis'
 import type { WebTerminalId } from '@deepseek-ai/dsh-api-terminal-controller/types'
-import type { TabId } from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
+import type { SidebarRightTabParamsMap, TabId } from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
 import type { SessionId } from '@deepseek-ai/dsh-session/types'
 import type {} from '@deepseek-ai/dsh-api-terminal-controller/client'
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
 import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type {} from '@deepseek-ai/dsh-client-ui-session/client'
+import type {} from '@deepseek-ai/dsh-client-ui-theme/client'
 import { TerminalGuideIcon } from './TerminalIcon.tsx'
+import { TerminalGuide, type TerminalGuideInjected } from './TerminalGuide.tsx'
 import { TerminalBody } from './TerminalBody.tsx'
 import { TerminalTitle } from './TerminalTitle.tsx'
 import { TerminalRecovery, type TerminalRecoveryInjected } from './TerminalRecovery.tsx'
 import { TerminalCleanup, type TerminalCleanupInjected } from './TerminalCleanup.tsx'
-import type { TerminalInjected } from './face.ts'
+import type { TerminalBodyInjected, TerminalInjected } from './face.ts'
 import { en, zh } from './locales.ts'
 
 /** Services needed by the terminal's two sidebar seats. */
-export const inject = ['slots', 'locale', 'sidebarRight', 'sidebarRightTabs', 'webTerminals']
+export const inject = ['slots', 'locale', 'sidebarRight', 'sidebarRightTabs', 'webTerminals', 'theme']
 
 /**
  * Register the terminal type, observable views and background process cleanup.
@@ -27,18 +29,24 @@ export function apply(ctx: Context): void {
   let disposed = false
   const recovered = new Map<SessionId, Promise<void>>()
   ctx.effect(() => () => { disposed = true; recovered.clear() }, 'ui-sidebar-terminal.lifetime')
+  const target = (sessionId: SessionId, key: string): SidebarRightTabParamsMap['terminal'] | undefined =>
+    ctx.sidebarRight.tabDomain.occurrence(sessionId, { id: key as TabId }).navigation.getSnapshot().params
   const terminalId = (sessionId: SessionId, key: string): WebTerminalId | undefined => {
-    const params = ctx.sidebarRight.tabDomain.occurrence(sessionId, { id: key as TabId }).navigation.getSnapshot().params
-    return (params as { terminalId?: WebTerminalId } | undefined)?.terminalId
+    const params = target(sessionId, key)
+    return params !== undefined && 'terminalId' in params ? params.terminalId : undefined
+  }
+  const view = (sessionId: SessionId, key: string) => {
+    const params = target(sessionId, key)
+    return ctx.webTerminals.view(sessionId, key, terminalId(sessionId, key),
+      params !== undefined && 'shellPath' in params ? params.shellPath : undefined)
   }
-  const view = (sessionId: SessionId, key: string) => ctx.webTerminals.view(sessionId, key, terminalId(sessionId, key))
   const namespace = 'sidebarTerminal'
   const id = '@deepseek-ai/dsh-client-ui-sidebar-terminal'
   const t = ctx.locale.bind(namespace)
   ctx.effect(() => ctx.locale.register(namespace, { zh, en }), 'ui-sidebar-terminal.copy')
   ctx.effect(() => ctx.sidebarRightTabs.register({
     id, kind: 'terminal', multiple: true, priority: 'builtin', title: () => t('title'),
-    guide: [{ order: 20, title: () => t('new'), description: () => t('description'), icon: TerminalGuideIcon }],
+    guide: [{ id: 'new', order: 20, title: () => t('new'), description: () => t('description'), icon: TerminalGuideIcon }],
   }), 'ui-sidebar-terminal.type')
   ctx.effect(() => ctx.sidebarRight.registerCloseHandler('terminal', (sessionId, tab) => {
     ctx.webTerminals.close(sessionId, tab.id, terminalId(sessionId, tab.id))
@@ -47,8 +55,21 @@ export function apply(ctx: Context): void {
     view: key => view(sessionId, key),
     keyedHooks: { terminal: key => view(sessionId, key).state },
   })
+  const theme: TerminalBodyInjected['hooks']['theme'] = {
+    getSnapshot: () => ctx.theme.getTheme(),
+    subscribe: listener => ctx.on('theme/change', listener),
+  }
+  ctx.effect(() => ctx.slots.inject('sidebar.right.tab.guide.entry', () => ctx.slots.register({
+    name: 'sidebar.right.tab.guide.entry', key: id, locale: namespace,
+    inject: (sessionId): TerminalGuideInjected => ({
+      loadShells: signal => ctx.webTerminals.launchShells(sessionId, signal),
+      selectShell: (path) => { ctx.webTerminals.selectShell(path) },
+    }),
+  }, TerminalGuide)), 'ui-sidebar-terminal.guide')
   ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register(
-    { name: 'sidebar.right.pane.tab', key: id, locale: namespace, inject }, TerminalBody,
+    { name: 'sidebar.right.pane.tab', key: id, locale: namespace,
+      inject: (sessionId): TerminalBodyInjected => ({ ...inject(sessionId), hooks: { theme } }),
+    }, TerminalBody,
   )), 'ui-sidebar-terminal.body')
   ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab.title', () => ctx.slots.register(
     { name: 'sidebar.right.pane.tab.title', key: id, locale: namespace, inject }, TerminalTitle,
diff --git a/packages/client/ui-sidebar-terminal/src/client/locales.ts b/packages/client/ui-sidebar-terminal/src/client/locales.ts
index d6ee5a5d17..52b33bf59e 100644
--- a/packages/client/ui-sidebar-terminal/src/client/locales.ts
+++ b/packages/client/ui-sidebar-terminal/src/client/locales.ts
@@ -10,7 +10,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 /** Simplified Chinese terminal copy. */
 export const zh = {
   recoveryFailed: '恢复终端失败：{message}', retryRecovery: '重试恢复终端',
-  shell: 'Shell', start: '启动终端', description: '在会话工作区运行命令',
+  shell: '选择 Shell', shellLoading: '正在读取 Shell…', shellEmpty: '没有可用的 Shell', description: '在会话工作区运行命令',
   title: '终端', new: '新建终端', loading: '正在读取终端环境…', creating: '正在启动…',
   connecting: '正在连接…', disconnected: '连接已断开。', reconnect: '重新连接',
   readonly: '此页面当前只读。', control: '接管输入',
@@ -27,7 +27,7 @@ export const zh = {
 /** English terminal copy. */
 export const en = {
   recoveryFailed: 'Terminal recovery failed: {message}', retryRecovery: 'Retry terminal recovery',
-  shell: 'Shell', start: 'Start terminal', description: 'Run commands in the Session workspace',
+  shell: 'Choose shell', shellLoading: 'Loading shells…', shellEmpty: 'No shells available', description: 'Run commands in the Session workspace',
   title: 'Terminal', new: 'New terminal', loading: 'Reading terminal environment…', creating: 'Starting…',
   connecting: 'Connecting…', disconnected: 'Disconnected.', reconnect: 'Reconnect',
   readonly: 'This view is read-only.', control: 'Take control',
diff --git a/packages/client/ui-sidebar-terminal/src/client/terminal-cursor.ts b/packages/client/ui-sidebar-terminal/src/client/terminal-cursor.ts
new file mode 100644
index 0000000000..e561361345
--- /dev/null
+++ b/packages/client/ui-sidebar-terminal/src/client/terminal-cursor.ts
@@ -0,0 +1,61 @@
+/** Contrast-aware styling for xterm's DOM cursor, independent of its ANSI palette. */
+import type { IDisposable, Terminal } from '@xterm/xterm'
+
+/* oxlint-disable typescript/no-non-null-assertion -- The mounted xterm DOM supplies elements and sRGB channels. */
+
+/**
+ * Keep the cursor visible on default, indexed, true-color and inverse cell backgrounds.
+ * @param terminal - opened DOM-rendered emulator.
+ * @param node - screen root containing the emulator and scoped cursor CSS variables.
+ * @param preferredCursor - current DSH or application cursor color.
+ * @returns listener disposer; no terminal input or palette changes are emitted.
+ */
+export function observeTerminalCursor(terminal: Terminal, node: HTMLElement, preferredCursor: () => string): IDisposable {
+  return terminal.onRender(() => {
+    const cursor = node.querySelector<HTMLElement>('.xterm-cursor')
+    if (cursor === null) return
+    // Removing only the cursor marker exposes the cell's rendered colors, including reverse video.
+    cursor.classList.remove('xterm-cursor')
+    let background: string
+    let foreground: string
+    try {
+      const style = getComputedStyle(cursor)
+      foreground = style.color
+      background = opaqueColor(style.backgroundColor, () => getComputedStyle(node.querySelector('.xterm-scrollable-element')!).backgroundColor)
+    } finally { cursor.classList.add('xterm-cursor') }
+    const preferred = opaqueColor(preferredCursor(), () => background)
+    const backgroundLuminance = luminance(background)
+    const preferredLuminance = luminance(preferred)
+    // WCAG contrast is 3:1 for the cursor and 4.5:1 for the character inside it.
+    const contrast = (Math.max(backgroundLuminance, preferredLuminance) + 0.05) / (Math.min(backgroundLuminance, preferredLuminance) + 0.05)
+    const fill = contrast >= 3 ? preferred : backgroundLuminance > 0.179 ? '#000000' : '#ffffff'
+    node.style.setProperty('--terminal-cursor', fill)
+    node.style.setProperty('--terminal-cursor-accent', luminance(fill) > 0.179 ? '#000000' : '#ffffff')
+    node.style.setProperty('--terminal-cursor-cell-background', background)
+    node.style.setProperty('--terminal-cursor-cell-foreground', foreground)
+  })
+}
+
+// xterm emits sRGB colors; OSC values are normalized to six-digit hex by TerminalTheme.
+function luminance(color: string): number {
+  const [r, g, b] = colorChannels(color).map((channel) => {
+    const value = channel / 255
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4
+  })
+  return 0.2126 * r! + 0.7152 * g! + 0.0722 * b!
+}
+
+function colorChannels(color: string): number[] {
+  return color.startsWith('#')
+    ? [color.slice(1, 3), color.slice(3, 5), color.slice(5, 7)].map(value => Number.parseInt(value, 16))
+    : color.match(/[\d.]+/gu)!.map(Number)
+}
+
+function opaqueColor(color: string, background: () => string): string {
+  const channels = colorChannels(color)
+  const alpha = channels[3] ?? 1
+  if (alpha === 1) return color
+  const surface = colorChannels(background())
+  const rgb = channels.slice(0, 3).map((channel, index) => Math.round(channel * alpha + surface[index]! * (1 - alpha)))
+  return `rgb(${rgb.join(', ')})`
+}
diff --git a/packages/client/ui-sidebar-terminal/src/client/terminal-theme.ts b/packages/client/ui-sidebar-terminal/src/client/terminal-theme.ts
new file mode 100644
index 0000000000..bf8d38eea6
--- /dev/null
+++ b/packages/client/ui-sidebar-terminal/src/client/terminal-theme.ts
@@ -0,0 +1,104 @@
+/** DSH defaults and application OSC colors for one xterm screen. */
+import type { IDisposable, ITheme, Terminal } from '@xterm/xterm'
+
+/* oxlint-disable typescript/no-non-null-assertion -- OSC widths/indices are checked; DSH defaults precede cursor reads. */
+const ansiKeys = ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white', 'brightBlack', 'brightRed', 'brightGreen', 'brightYellow', 'brightBlue', 'brightMagenta', 'brightCyan', 'brightWhite'] as const
+const specialKeys = ['foreground', 'background', 'cursor'] as const
+
+/** Keep program color overrides separate from the DSH defaults used by OSC resets. */
+export class TerminalTheme implements IDisposable {
+  private defaults: ITheme = {}
+  private readonly indexed = new Map<number, string>()
+  private readonly special = new Map<(typeof specialKeys)[number], string>()
+  private readonly subscriptions: IDisposable[]
+
+  /**
+   * Observe complete OSC commands without consuming xterm's queries or color handling.
+   * @param terminal - opened emulator owned by the mounted screen.
+   */
+  constructor(private readonly terminal: Terminal) {
+    const observe = (code: number, change: (data: string) => void): IDisposable =>
+      terminal.parser.registerOscHandler(code, (data) => { change(data); return false })
+    this.subscriptions = [
+      observe(4, (data) => {
+        const parts = data.split(';')
+        for (let i = 0; i + 1 < parts.length; i += 2) {
+          const index = colorIndex(parts[i]!)
+          const color = oscColor(parts[i + 1]!)
+          if (index !== undefined && color !== undefined) this.indexed.set(index, color)
+        }
+      }),
+      observe(104, (data) => {
+        if (data === '') this.indexed.clear()
+        else for (const part of data.split(';')) {
+          const index = colorIndex(part)
+          if (index !== undefined) this.indexed.delete(index)
+        }
+        this.apply()
+      }),
+      ...specialKeys.flatMap((key, offset) => [
+        observe(10 + offset, (data) => {
+          for (const [i, part] of data.split(';').entries()) {
+            const target = specialKeys[offset + i]
+            const color = oscColor(part)
+            if (target !== undefined && color !== undefined) this.special.set(target, color)
+          }
+        }),
+        observe(110 + offset, () => { this.special.delete(key); this.apply() }),
+      ]),
+    ]
+  }
+
+  /**
+   * Apply changed DSH colors without replacing application-defined palette entries.
+   * @param background - resolved opaque DSH background.
+   * @param foreground - resolved DSH text color.
+   */
+  update(background: string, foreground: string): void {
+    if (this.defaults.background === background && this.defaults.foreground === foreground) return
+    this.defaults = {
+      background, foreground, cursor: foreground, cursorAccent: background,
+      selectionBackground: foreground, selectionForeground: background, selectionInactiveBackground: foreground,
+    }
+    this.apply()
+  }
+
+  /** Preferred cursor color after the initial DSH update, including OSC 12 overrides. */
+  get cursor(): string { return this.special.get('cursor') ?? this.defaults.cursor! }
+
+  /** Remove parser observers before the emulator is disposed. */
+  dispose(): void { for (const subscription of this.subscriptions) subscription.dispose() }
+
+  private apply(): void {
+    const theme: ITheme = { ...this.defaults, ...Object.fromEntries(this.special) }
+    for (const [index, color] of this.indexed) {
+      if (index < ansiKeys.length) theme[ansiKeys[index]!] = color
+      else (theme.extendedAnsi ??= [])[index - ansiKeys.length] = color
+    }
+    this.terminal.options.theme = theme
+  }
+}
+
+function colorIndex(value: string): number | undefined {
+  return /^\d+$/u.test(value) && Number(value) < 256 ? Number(value) : undefined
+}
+
+// XParseColor hashes truncate channels; rgb: channels scale. CSS #rgb has different semantics.
+function oscColor(value: string): string | undefined {
+  const rgb = /^rgb:([\da-f]{1,4})\/([\da-f]{1,4})\/([\da-f]{1,4})$/iu.exec(value)
+  let channels: string[]
+  if (rgb !== null) {
+    channels = rgb.slice(1)
+    if (!channels.every(channel => channel.length === channels[0]!.length)) return
+  } else {
+    if (!/^#(?:[\da-f]{3}){1,4}$/iu.test(value)) return
+    const width = (value.length - 1) / 3
+    channels = [value.slice(1, width + 1), value.slice(width + 1, 2 * width + 1), value.slice(2 * width + 1)]
+  }
+  return `#${channels.map((channel) => {
+    const n = rgb === null
+      ? Number.parseInt(channel.padEnd(2, '0').slice(0, 2), 16)
+      : Math.round(Number.parseInt(channel, 16) * 255 / (16 ** channel.length - 1))
+    return n.toString(16).padStart(2, '0')
+  }).join('')}`
+}
diff --git a/packages/client/ui-sidebar-terminal/tests/apply.client.spec.ts b/packages/client/ui-sidebar-terminal/tests/apply.client.spec.ts
index dbbd4fa040..058f9b8121 100644
--- a/packages/client/ui-sidebar-terminal/tests/apply.client.spec.ts
+++ b/packages/client/ui-sidebar-terminal/tests/apply.client.spec.ts
@@ -10,11 +10,12 @@ import { SidebarRightTabRegistry } from '@deepseek-ai/dsh-client-ui-sidebar-righ
 import type { SidebarRightCloseHandler } from '@deepseek-ai/dsh-client-ui-sidebar-right/client'
 import { apply, inject } from '../src/client/index.ts'
 import { apply as hostApply } from '../src/index.ts'
+import { TerminalGuide, type TerminalGuideInjected } from '../src/client/TerminalGuide.tsx'
 import { TerminalBody } from '../src/client/TerminalBody.tsx'
 import { TerminalTitle } from '../src/client/TerminalTitle.tsx'
 import { TerminalRecovery, type TerminalRecoveryInjected } from '../src/client/TerminalRecovery.tsx'
 import { TerminalCleanup, type TerminalCleanupInjected } from '../src/client/TerminalCleanup.tsx'
-import type { TerminalInjected } from '../src/client/face.ts'
+import type { TerminalBodyInjected } from '../src/client/face.ts'
 import { en, zh } from '../src/client/locales.ts'
 
 vi.mock('@xterm/xterm', () => ({ Terminal: vi.fn() }))
@@ -38,9 +39,10 @@ async function mountPlugin() {
   const model = { state: {} }
   const terminals = {
     view: vi.fn(() => model), close: vi.fn(), closeFailures: {}, retryClose: vi.fn(),
+    launchShells: vi.fn(async () => ({ shells: [], selectedShell: undefined })), selectShell: vi.fn(),
     recover: vi.fn(async (_sessionId: SessionId): Promise<WebTerminalInfo[]> => []),
   }
-  let params: { terminalId: WebTerminalId } | undefined
+  let params: { terminalId: WebTerminalId } | { shellPath: string } | undefined
   const occurrence = vi.fn(() => ({ navigation: { getSnapshot: () => ({ params }) } }))
   const openTabIn = vi.fn()
   ctx.provide('webTerminals', terminals as never)
@@ -56,9 +58,12 @@ async function mountPlugin() {
     bind: () => (key: string) => key,
     register: (name: string, values: unknown) => { dictionaries.set(name, values); return () => { dictionaries.delete(name) } },
   } as never)
+  const theme = { preference: 'light' as const, fontSize: 14, active: { id: 'light', colorScheme: 'light' as const, tokens: {} }, themes: [], revision: 0 }
+  ctx.provide('theme', { getTheme: () => theme } as never)
   const fiber = await ctx.plugin({ inject, apply })
   return {
-    tabs, entries, dictionaries, terminals, model, occurrence, openTabIn,
+    tabs, entries, dictionaries, terminals, model, occurrence, openTabIn, theme,
+    emitTheme() { ctx.emit('theme/change', theme) },
     get closeHandler() { return closeHandler },
     setParams(next: typeof params) { params = next },
     async dispose() { await fiber.dispose(); await ctx.fiber.dispose() },
@@ -79,19 +84,38 @@ it('registers terminal views, recovery and cleanup, then releases every contribu
     expect(definition.multiple).toBe(true)
     expect(h.dictionaries.get('sidebarTerminal')).toEqual({ en, zh })
     expect(h.entries.map(entry => [entry.name, entry.component, entry.locale])).toEqual([
+      ['sidebar.right.tab.guide.entry', TerminalGuide, 'sidebarTerminal'],
       ['sidebar.right.pane.tab', TerminalBody, 'sidebarTerminal'],
       ['sidebar.right.pane.tab.title', TerminalTitle, 'sidebarTerminal'],
       ['conversation.session.header.actions', TerminalRecovery, 'sidebarTerminal'],
       ['shell.overlay', TerminalCleanup, 'sidebarTerminal'],
     ])
     const sessionId = 'session' as SessionId
-    const face = h.entries[0]!.inject(sessionId) as TerminalInjected
+    const launcher = h.entries[0]!.inject(sessionId) as TerminalGuideInjected
+    const signal = new AbortController().signal
+    await launcher.loadShells(signal)
+    expect(h.terminals.launchShells).toHaveBeenCalledWith(sessionId, signal)
+    launcher.selectShell('/bin/bash')
+    expect(h.terminals.selectShell).toHaveBeenCalledWith('/bin/bash')
+    const face = h.entries[1]!.inject(sessionId) as TerminalBodyInjected
+    expect(face.hooks.theme.getSnapshot()).toBe(h.theme)
+    const changed = vi.fn()
+    const unsubscribe = face.hooks.theme.subscribe(changed)
+    h.emitTheme()
+    expect(changed).toHaveBeenCalledOnce()
+    unsubscribe()
+    h.emitTheme()
+    expect(changed).toHaveBeenCalledOnce()
     expect(face.view('tab')).toBe(h.model)
-    expect(h.terminals.view).toHaveBeenLastCalledWith(sessionId, 'tab', undefined)
+    expect(h.terminals.view).toHaveBeenLastCalledWith(sessionId, 'tab', undefined, undefined)
     const terminalId = 'retained' as WebTerminalId
     h.setParams({ terminalId })
+    h.setParams({ shellPath: '/bin/bash' })
+    face.view('tab')
+    expect(h.terminals.view).toHaveBeenLastCalledWith(sessionId, 'tab', undefined, '/bin/bash')
+    h.setParams({ terminalId })
     expect(face.keyedHooks.terminal('tab')).toBe(h.model.state)
-    expect(h.terminals.view).toHaveBeenLastCalledWith(sessionId, 'tab', terminalId)
+    expect(h.terminals.view).toHaveBeenLastCalledWith(sessionId, 'tab', terminalId, undefined)
     expect(h.occurrence).toHaveBeenLastCalledWith(sessionId, { id: 'tab' })
     if (h.closeHandler === undefined) throw new Error('Terminal close handler was not registered')
     h.closeHandler(sessionId, { id: 'tab' } as Parameters<SidebarRightCloseHandler>[1])
@@ -99,7 +123,7 @@ it('registers terminal views, recovery and cleanup, then releases every contribu
     h.setParams(undefined)
     h.closeHandler(sessionId, { id: 'new-tab' } as Parameters<SidebarRightCloseHandler>[1])
     expect(h.terminals.close).toHaveBeenLastCalledWith(sessionId, 'new-tab', undefined)
-    const cleanupFace = h.entries[3]!.inject(sessionId) as TerminalCleanupInjected
+    const cleanupFace = h.entries[4]!.inject(sessionId) as TerminalCleanupInjected
     expect(cleanupFace.hooks.closeFailures).toBe(h.terminals.closeFailures)
     cleanupFace.retryClose('terminal' as Parameters<TerminalCleanupInjected['retryClose']>[0])
     expect(h.terminals.retryClose).toHaveBeenCalledWith('terminal')
@@ -117,8 +141,8 @@ it('shares pending and completed recovery across Session headers and opens each
   const pending = Promise.withResolvers<WebTerminalInfo[]>()
   h.terminals.recover.mockImplementationOnce(() => pending.promise)
   const sessionId = 'session' as SessionId
-  const recovery = h.entries[2]!.inject(sessionId) as TerminalRecoveryInjected
-  const remounted = h.entries[2]!.inject(sessionId) as TerminalRecoveryInjected
+  const recovery = h.entries[3]!.inject(sessionId) as TerminalRecoveryInjected
+  const remounted = h.entries[3]!.inject(sessionId) as TerminalRecoveryInjected
   const completion = recovery.restore()
   try {
     expect(remounted.restore()).toBe(completion)
@@ -134,7 +158,7 @@ it('shares pending and completed recovery across Session headers and opens each
     expect(h.terminals.recover).toHaveBeenCalledTimes(1)
     expect(h.openTabIn).toHaveBeenCalledTimes(2)
     const otherSession = 'other-session' as SessionId
-    await (h.entries[2]!.inject(otherSession) as TerminalRecoveryInjected).restore()
+    await (h.entries[3]!.inject(otherSession) as TerminalRecoveryInjected).restore()
     expect(h.terminals.recover).toHaveBeenLastCalledWith(otherSession)
     expect(h.terminals.recover).toHaveBeenCalledTimes(2)
     expect(h.openTabIn).toHaveBeenCalledTimes(2)
@@ -150,7 +174,7 @@ it('allows a failed Host lookup to be retried without marking the Session recove
   const unavailable = new Error('Host unavailable')
   h.terminals.recover.mockRejectedValueOnce(unavailable)
   const sessionId = 'session' as SessionId
-  const recovery = h.entries[2]!.inject(sessionId) as TerminalRecoveryInjected
+  const recovery = h.entries[3]!.inject(sessionId) as TerminalRecoveryInjected
   try {
     await expect(recovery.restore()).rejects.toBe(unavailable)
     expect(h.openTabIn).not.toHaveBeenCalled()
@@ -166,7 +190,7 @@ it('does not open retained terminals when their lookup completes after plugin un
   const h = await mountPlugin()
   const pending = Promise.withResolvers<WebTerminalInfo[]>()
   h.terminals.recover.mockImplementationOnce(() => pending.promise)
-  const recovery = h.entries[2]!.inject('session' as SessionId) as TerminalRecoveryInjected
+  const recovery = h.entries[3]!.inject('session' as SessionId) as TerminalRecoveryInjected
   const completion = recovery.restore()
   try {
     expect(h.terminals.recover).toHaveBeenCalledOnce()
diff --git a/packages/client/ui-sidebar-terminal/tests/terminal-body.client.spec.tsx b/packages/client/ui-sidebar-terminal/tests/terminal-body.client.spec.tsx
index 7070b43df9..2cd97332f7 100644
--- a/packages/client/ui-sidebar-terminal/tests/terminal-body.client.spec.tsx
+++ b/packages/client/ui-sidebar-terminal/tests/terminal-body.client.spec.tsx
@@ -3,6 +3,8 @@
 import { afterEach, beforeEach, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
 import type { ReactNode } from 'react'
+import type { ITheme } from '@xterm/xterm'
+import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
 import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
 import type { TerminalViewState } from '@deepseek-ai/dsh-api-terminal-controller/client'
 import type { WebTerminalId } from '@deepseek-ai/dsh-api-terminal-controller/types'
@@ -15,10 +17,17 @@ const fake = vi.hoisted(() => ({
   dimensions: { cols: 120, rows: 40 } as { cols: number; rows: number } | undefined,
 }))
 class FakeTerminal {
-  options: { disableStdin?: boolean }
+  options: { disableStdin?: boolean; theme?: ITheme }
   textarea: HTMLTextAreaElement | undefined = document.createElement('textarea')
   input: ((data: string) => void) | undefined
   readonly disposeInput = vi.fn()
+  readonly parser = { registerOscHandler: vi.fn(() => ({ dispose: vi.fn() })) }
+  renderFrame: (() => void) | undefined
+  readonly disposeRender = vi.fn(() => { this.renderFrame = undefined })
+  readonly onRender = vi.fn((listener: () => void) => {
+    this.renderFrame = listener
+    return { dispose: this.disposeRender }
+  })
   readonly resize = vi.fn()
   readonly reset = vi.fn()
   readonly focus = vi.fn()
@@ -63,9 +72,9 @@ const titleSurfaces = [
 function mount(initial: TerminalViewState | undefined = idle, dictionary = en) {
   let state: TerminalViewState | undefined = initial
   let visible = true
+  let theme: ThemeSnapshot = { preference: 'light', fontSize: 14, active: { id: 'light', colorScheme: 'light', tokens: {} }, themes: [], revision: 0 }
   const detach = vi.fn()
   const model = {
-    start: vi.fn(async () => {}), selectShell: vi.fn(),
     mount: vi.fn(() => detach), refresh: vi.fn(async () => {}),
     rename: vi.fn(async () => {}), connect: vi.fn(), write: vi.fn(), resize: vi.fn(), acknowledge: vi.fn(),
   }
@@ -75,11 +84,13 @@ function mount(initial: TerminalViewState | undefined = idle, dictionary = en) {
   const props = {
     view: () => model,
     useTerminal: (_key: string, select?: (value: TerminalViewState | undefined) => unknown) => select === undefined ? state : select(state),
+    useTheme: (select: (value: ThemeSnapshot) => unknown) => select(theme),
     useTabInfo: tab, t: makeTranslate(dictionary),
   } as unknown as TerminalBodyProps
   const view = render(<TerminalBody {...props} />)
   return {
     view, props, model, detach, openTab,
+    changeTheme() { theme = { ...theme, revision: theme.revision + 1 }; view.rerender(<TerminalBody {...props} />) },
     update(next: TerminalViewState | undefined, shown = visible) {
       state = next; visible = shown; view.rerender(<TerminalBody {...props} />)
     },
@@ -172,6 +183,60 @@ it('displays disconnect, close and exit states and offers explicit reconnection
   expect(h.view.getByRole('status').textContent).toBe(en.unavailable)
 })
 
+it('updates screen, cursor and selection colors without replacing the terminal or clearing output', () => {
+  const colors = { backgroundColor: 'rgb(255, 255, 255)', color: 'rgb(23, 25, 29)' }
+  vi.spyOn(window, 'getComputedStyle').mockImplementation(() => colors as CSSStyleDeclaration)
+  const h = mount({ ...idle, info, phase: 'connected', writable: true })
+  const terminal = fake.terminals[0]!
+  expect(terminal.options.theme).toMatchObject({
+    background: colors.backgroundColor, foreground: colors.color, cursor: colors.color, selectionForeground: colors.backgroundColor,
+  })
+  const appliedTheme = terminal.options.theme
+  h.changeTheme()
+  expect(terminal.options.theme).toBe(appliedTheme)
+  colors.backgroundColor = 'rgb(23, 25, 29)'
+  colors.color = 'rgb(231, 233, 238)'
+  h.changeTheme()
+  expect(terminal.options.theme).toEqual({
+    background: colors.backgroundColor, foreground: colors.color, cursor: colors.color, cursorAccent: colors.backgroundColor,
+    selectionBackground: colors.color, selectionForeground: colors.backgroundColor, selectionInactiveBackground: colors.color,
+  })
+  expect(fake.terminals).toEqual([terminal])
+  expect(terminal.reset).not.toHaveBeenCalled()
+  expect(terminal.dispose).not.toHaveBeenCalled()
+  expect(h.model.mount).toHaveBeenCalledOnce()
+  expect(h.detach).not.toHaveBeenCalled()
+})
+
+it('reads the current theme on xterm render and releases the cursor listener on unmount', () => {
+  const colors = { backgroundColor: 'rgb(255, 255, 255)', color: 'rgb(23, 25, 29)' }
+  const cursor = document.createElement('span')
+  cursor.className = 'xterm-cursor'
+  cursor.style.backgroundColor = 'black'
+  cursor.style.color = 'cyan'
+  const readStyle = window.getComputedStyle.bind(window)
+  vi.spyOn(window, 'getComputedStyle').mockImplementation(element => element === cursor ? readStyle(element) : colors as CSSStyleDeclaration)
+  const h = mount({ ...idle, info, phase: 'connected', writable: true })
+  const terminal = fake.terminals[0]!
+  const screen = terminal.textarea!.parentElement!
+  screen.append(cursor)
+  const appliedTheme = terminal.options.theme
+  terminal.renderFrame?.()
+  expect(screen.style.getPropertyValue('--terminal-cursor')).toBe('#ffffff')
+  expect(screen.style.getPropertyValue('--terminal-cursor-accent')).toBe('#000000')
+  expect(terminal.options.theme).toBe(appliedTheme)
+
+  colors.backgroundColor = 'rgb(23, 25, 29)'
+  colors.color = 'rgb(231, 233, 238)'
+  h.changeTheme()
+  terminal.renderFrame?.()
+  expect(screen.style.getPropertyValue('--terminal-cursor')).toBe(colors.color)
+  expect(fake.terminals).toEqual([terminal])
+  h.view.unmount()
+  expect(terminal.disposeRender).toHaveBeenCalledOnce()
+  expect(terminal.renderFrame).toBeUndefined()
+})
+
 it('fits only visible writable terminals with measurable dimensions and clamps the provider limits', () => {
   const state: TerminalViewState = { ...idle, info, phase: 'connected', writable: true }
   const h = mount(state)
@@ -311,23 +376,3 @@ it.each([en, zh])('translates known terminal failures while retaining unknown Ho
   h.update({ ...idle, phase: 'failed', error: 'Host permission denied' })
   expect(h.view.getByRole('alert').textContent).toContain('Host permission denied')
 })
-
-it('lets the user select an installed shell and start it before rendering a screen', () => {
-  const other = { path: '/bin/zsh', name: 'zsh', args: ['-i'] }
-  const h = mount({ phase: 'selecting', writable: false, environment, shells: [info.shell, other], selectedShell: other.path })
-  const selector = h.view.getByRole('button', { name: 'Shell' })
-  expect(selector.textContent).toContain(other.path)
-  expect(fake.terminals).toHaveLength(0)
-  fireEvent.click(selector)
-  expect(h.view.getByRole('menu')).toBeTruthy()
-  fireEvent.keyDown(document, { key: 'Escape' })
-  expect(h.view.queryByRole('menu')).toBeNull()
-  fireEvent.click(selector)
-  fireEvent.click(h.view.getByRole('menuitem', { name: `bash — ${info.shell.path}` }))
-  expect(h.view.queryByRole('menu')).toBeNull()
-  expect(h.model.selectShell).toHaveBeenCalledWith(info.shell.path)
-  fireEvent.click(h.view.getByRole('button', { name: 'Start terminal' }))
-  expect(h.model.start).toHaveBeenCalledOnce()
-  h.update({ phase: 'selecting', writable: false, environment })
-  expect(h.view.getByRole('button', { name: 'Start terminal' })).toHaveProperty('disabled', true)
-})
diff --git a/packages/client/ui-sidebar-terminal/tests/terminal-cursor.client.spec.ts b/packages/client/ui-sidebar-terminal/tests/terminal-cursor.client.spec.ts
new file mode 100644
index 0000000000..e0bb7cd466
--- /dev/null
+++ b/packages/client/ui-sidebar-terminal/tests/terminal-cursor.client.spec.ts
@@ -0,0 +1,51 @@
+// @vitest-environment jsdom
+/** DOM cursor contrast without writing escape sequences or replacing the palette. */
+import { expect, it, vi } from 'vitest'
+import type { Terminal } from '@xterm/xterm'
+import { observeTerminalCursor } from '../src/client/terminal-cursor.ts'
+
+it('tracks actual cell backgrounds and restores the cursor marker after measuring', () => {
+  let update: () => void = () => {}
+  const dispose = vi.fn()
+  const terminal = { onRender: (listener: () => void) => { update = listener; return { dispose } } } as unknown as Terminal
+  const node = document.createElement('div')
+  node.innerHTML = '<div class="xterm-scrollable-element" style="background: white"><span class="xterm-cursor" style="color: cyan"></span></div>'
+  document.body.append(node)
+  try {
+    const cursor = node.querySelector<HTMLElement>('span')!
+    let preferred = 'rgb(0, 0, 0)'
+    const listener = observeTerminalCursor(terminal, node, () => preferred)
+    update()
+    expect(node.style.getPropertyValue('--terminal-cursor')).toBe('rgb(0, 0, 0)')
+    expect(node.style.getPropertyValue('--terminal-cursor-accent')).toBe('#ffffff')
+    cursor.style.backgroundColor = '#000000'
+    update()
+    expect(node.style.getPropertyValue('--terminal-cursor')).toBe('#ffffff')
+    expect(node.style.getPropertyValue('--terminal-cursor-accent')).toBe('#000000')
+    expect(node.style.getPropertyValue('--terminal-cursor-cell-background')).toBe('rgb(0, 0, 0)')
+    expect(node.style.getPropertyValue('--terminal-cursor-cell-foreground')).toBe('rgb(0, 255, 255)')
+    preferred = 'rgba(255, 255, 255, 0)'
+    update()
+    expect(node.style.getPropertyValue('--terminal-cursor')).toBe('#ffffff')
+    preferred = '#00ff00'
+    update()
+    expect(node.style.getPropertyValue('--terminal-cursor')).toBe('#00ff00')
+    preferred = '#ffffff'
+    cursor.style.backgroundColor = '#ffffff'
+    update()
+    expect(node.style.getPropertyValue('--terminal-cursor')).toBe('#000000')
+    cursor.style.backgroundColor = 'rgba(0, 153, 0, 0.5)'
+    update()
+    expect(node.style.getPropertyValue('--terminal-cursor')).toBe('#000000')
+    expect(node.style.getPropertyValue('--terminal-cursor-cell-background')).toBe('rgb(128, 204, 128)')
+    preferred = '#000000'
+    cursor.style.backgroundColor = '#888888'
+    update()
+    expect(node.style.getPropertyValue('--terminal-cursor')).toBe('#000000')
+    expect(cursor.classList.contains('xterm-cursor')).toBe(true)
+    cursor.remove()
+    update()
+    listener.dispose()
+    expect(dispose).toHaveBeenCalledOnce()
+  } finally { node.remove() }
+})
diff --git a/packages/client/ui-sidebar-terminal/tests/terminal-guide.client.spec.tsx b/packages/client/ui-sidebar-terminal/tests/terminal-guide.client.spec.tsx
new file mode 100644
index 0000000000..2af1b6662d
--- /dev/null
+++ b/packages/client/ui-sidebar-terminal/tests/terminal-guide.client.spec.tsx
@@ -0,0 +1,94 @@
+// @vitest-environment jsdom
+/** Guide shell discovery, direct launch and cancellation stay within the entry lifetime. */
+import { act, cleanup, fireEvent, render } from '@testing-library/react'
+import { afterEach, expect, it, vi } from 'vitest'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import type { TerminalLaunchShells } from '@deepseek-ai/dsh-api-terminal-controller/client'
+import { TerminalGuide, type TerminalGuideProps } from '../src/client/TerminalGuide.tsx'
+import { en } from '../src/client/locales.ts'
+
+afterEach(cleanup)
+const choices: TerminalLaunchShells = {
+  shells: [{ name: 'bash', path: '/bin/bash', args: ['-i'] }, { name: 'zsh', path: '/bin/zsh', args: ['-i'] }],
+  selectedShell: '/bin/zsh',
+}
+
+function mount(description: string | undefined = en.description) {
+  const loadShells = vi.fn<TerminalGuideProps['loadShells']>(async () => choices)
+  const selectShell = vi.fn()
+  const openTab = vi.fn()
+  // The fixture supplies only the guide's consumed owner and framework shares.
+  const props = {
+    entryId: 'new', kind: 'terminal', title: en.new, description, t: makeTranslate(en),
+    useTabInfo: () => ({ tab: { actions: { openTab } } }), loadShells, selectShell,
+  } as unknown as TerminalGuideProps
+  const view = render(<TerminalGuide {...props} />)
+  const open = () => fireEvent.click(view.getByRole('button', { name: en.shell }))
+  return { view, props, open, loadShells, selectShell, openTab }
+}
+
+it('opens the default shell from the main button without querying a menu', () => {
+  const h = mount()
+  fireEvent.click(h.view.getByRole('button', { name: /^New terminal/u }))
+  expect(h.openTab).toHaveBeenCalledExactlyOnceWith('terminal', { replaceTab: true })
+  expect(h.loadShells).not.toHaveBeenCalled()
+  expect(h.view.container.querySelector('button button')).toBeNull()
+})
+
+it('loads on demand, remembers a selected shell before opening, and cancels on menu dismissal', async () => {
+  const h = mount()
+  h.open()
+  await h.view.findByRole('menuitem', { name: 'zsh' })
+  const signal = h.loadShells.mock.calls[0]![0]
+  h.selectShell.mockImplementation(() => { expect(h.openTab).not.toHaveBeenCalled() })
+  fireEvent.click(h.view.getByRole('menuitem', { name: 'bash' }))
+  expect(h.selectShell).toHaveBeenCalledExactlyOnceWith('/bin/bash')
+  expect(h.openTab).toHaveBeenCalledExactlyOnceWith('terminal', { replaceTab: true, params: { shellPath: '/bin/bash' } })
+  expect(signal.aborted).toBe(true)
+  h.open()
+  await h.view.findByRole('menuitem', { name: 'bash' })
+  fireEvent.keyDown(h.view.getByRole('menu'), { key: 'Escape' })
+  expect(h.view.queryByRole('menu')).toBeNull()
+  expect(h.loadShells.mock.calls[1]![0].aborted).toBe(true)
+})
+
+it.each([new Error('offline'), 'offline'])('offers an in-place retry after discovery fails: %s', async (error) => {
+  const h = mount()
+  h.loadShells.mockRejectedValueOnce(error)
+  h.open()
+  await h.view.findByText('Terminal error: offline')
+  fireEvent.click(h.view.getByRole('menuitem', { name: en.retry }))
+  await h.view.findByRole('menuitem', { name: 'bash' })
+  expect(h.loadShells).toHaveBeenCalledTimes(2)
+  expect(h.openTab).not.toHaveBeenCalled()
+})
+
+it('shows empty discovery without opening a terminal and supports title-only cards', async () => {
+  const h = mount()
+  const { description: _description, ...titleOnly } = h.props
+  h.view.rerender(<TerminalGuide {...titleOnly} />)
+  h.loadShells.mockResolvedValue({ shells: [], selectedShell: undefined })
+  h.open()
+  await h.view.findByText(en.shellEmpty)
+  expect(h.view.queryByText(en.description)).toBeNull()
+  expect(h.openTab).not.toHaveBeenCalled()
+})
+
+it.each(['resolve', 'reject'] as const)('ignores a late %s after a loading entry unmounts', async (outcome) => {
+  const h = mount()
+  const pending = Promise.withResolvers<TerminalLaunchShells>()
+  h.loadShells.mockReturnValue(pending.promise)
+  h.open()
+  expect(h.view.getByText(en.shellLoading)).toBeDefined()
+  const signal = h.loadShells.mock.calls[0]![0]
+  h.view.unmount()
+  expect(signal.aborted).toBe(true)
+  await act(async () => {
+    if (outcome === 'resolve') pending.resolve(choices)
+    else pending.reject(new Error('late failure'))
+    await pending.promise.catch((_lateDiscoveryFailure: unknown) => {
+      /* The cancelled entry consumes the rejection without publishing it. */
+    })
+  })
+  expect(h.openTab).not.toHaveBeenCalled()
+})
diff --git a/packages/client/ui-sidebar-terminal/tests/terminal-theme.client.spec.ts b/packages/client/ui-sidebar-terminal/tests/terminal-theme.client.spec.ts
new file mode 100644
index 0000000000..8eb1395139
--- /dev/null
+++ b/packages/client/ui-sidebar-terminal/tests/terminal-theme.client.spec.ts
@@ -0,0 +1,85 @@
+/** Program palette retention and XParseColor reset semantics across application themes. */
+import { expect, it, vi } from 'vitest'
+import type { Terminal } from '@xterm/xterm'
+import { TerminalTheme } from '../src/client/terminal-theme.ts'
+
+function harness() {
+  const handlers = new Map<number, (data: string) => boolean>()
+  const dispose = vi.fn()
+  const options: Terminal['options'] = {}
+  const terminal = {
+    options,
+    parser: { registerOscHandler: (code: number, handler: (data: string) => boolean) => {
+      handlers.set(code, handler)
+      return { dispose }
+    } },
+  } as unknown as Terminal
+  const theme = new TerminalTheme(terminal)
+  const send = (code: number, data = '') => { expect(handlers.get(code)!(data)).toBe(false) }
+  theme.update('#ffffff', '#0f1115')
+  return { theme, options, send, dispose }
+}
+
+it('preserves indexed, extended and default application colors while updating DSH selection colors', () => {
+  const h = harness()
+  h.send(4, '1;#00ff00;16;rgb:f/0/0;255;#123456')
+  h.send(10, '#abcdef;#123456;#aa0000;#999999')
+  expect(h.theme.cursor).toBe('#aa0000')
+  h.theme.update('#151517', '#f9fafb')
+  expect(h.options.theme).toMatchObject({
+    red: '#00ff00', foreground: '#abcdef', background: '#123456', cursor: '#aa0000',
+    selectionBackground: '#f9fafb', selectionForeground: '#151517',
+  })
+  expect(h.options.theme?.extendedAnsi?.[0]).toBe('#ff0000')
+  expect(h.options.theme?.extendedAnsi?.[239]).toBe('#123456')
+  const previous = h.options.theme
+  h.theme.update('#151517', '#f9fafb')
+  expect(h.options.theme).toBe(previous)
+  h.theme.dispose()
+  expect(h.dispose).toHaveBeenCalledTimes(8)
+})
+
+it('restores selected entries, all indexed colors and special colors to the current DSH defaults', () => {
+  const h = harness()
+  h.send(4, '1;#00ff00;2;#ff0000;255;#fedcba')
+  h.send(11, '#111111;#222222')
+  h.send(10, '#333333')
+  h.theme.update('#151517', '#f9fafb')
+  h.send(104, '1;255;bad;-1;256')
+  expect(h.options.theme).not.toHaveProperty('red')
+  expect(h.options.theme).not.toHaveProperty('extendedAnsi')
+  expect(h.options.theme?.green).toBe('#ff0000')
+  h.send(104)
+  expect(h.options.theme).not.toHaveProperty('green')
+  for (const code of [110, 111, 112]) h.send(code)
+  expect(h.theme.cursor).toBe('#f9fafb')
+  expect(h.options.theme).toMatchObject({ background: '#151517', foreground: '#f9fafb', cursor: '#f9fafb' })
+})
+
+it.each([
+  ['#f00', '#f00000'], ['#123456', '#123456'], ['#123456789', '#124578'], ['#123456789abc', '#12569a'],
+  ['rgb:f/0/0', '#ff0000'], ['RGB:FF/00/00', '#ff0000'], ['rgb:abc/def/123', '#abde12'],
+  ['rgb:ffff/0000/8080', '#ff0080'],
+])('retains the xterm interpretation of %s', (source, expected) => {
+  const h = harness()
+  h.send(12, source)
+  h.theme.update('#000000', '#ffffff')
+  expect(h.options.theme?.cursor).toBe(expected)
+})
+
+it.each(['?', 'red', '#12', '#zzzzzz', '#12345g', 'rgb:f/00/000', 'rgb:fffff/00000/00000', '', 'rgba:ff/00/00'])('leaves unsupported or query color %s to xterm', (color) => {
+  const h = harness()
+  h.send(4, `1;#00ff00;1;${color};dangling`)
+  h.send(10, color)
+  h.theme.update('#000000', '#ffffff')
+  expect(h.options.theme?.red).toBe('#00ff00')
+  expect(h.options.theme?.foreground).toBe('#ffffff')
+})
+
+it('ignores invalid palette indices without losing valid pairs in the same command', () => {
+  const h = harness()
+  h.send(4, '-1;#ffffff;256;#ffffff;x;#ffffff;1.5;#ffffff;;#ffffff;01;#010203')
+  h.theme.update('#000000', '#ffffff')
+  expect(h.options.theme?.red).toBe('#010203')
+  expect(Object.keys(h.options.theme!)).toHaveLength(8)
+})
diff --git a/packages/client/ui-sidebar-terminal/tsconfig.json b/packages/client/ui-sidebar-terminal/tsconfig.json
index 4e229078ec..1727fed36d 100644
--- a/packages/client/ui-sidebar-terminal/tsconfig.json
+++ b/packages/client/ui-sidebar-terminal/tsconfig.json
@@ -46,6 +46,9 @@
     },
     {
       "path": "../ui-conversation"
+    },
+    {
+      "path": "../ui-theme"
     }
   ]
 }
diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml
index 7ab65bfb45..7a92445368 100644
--- a/packages/client/ui-tool/README.i18n.yaml
+++ b/packages/client/ui-tool/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 packages/client/ui-tool/README.md
-README.md: b7e71ac68090e19b1a87428ed930021d8decd209
-README.zh.md: 33dc7b38f8539de10a45edbe4b8f45c903188c2a
+README.md: 15dffa634660a5cf94081452481399821d09b25b
+README.zh.md: 6f01658e5fea4fefca9eded114971d3e88a13148
diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md
index b7e71ac680..15dffa6346 100644
--- a/packages/client/ui-tool/README.md
+++ b/packages/client/ui-tool/README.md
@@ -64,6 +64,8 @@ The package realizes one dispatch rule: atomic Tool views are keyed by wire Tool
 
 Every card is read in place in the call tree; there is no second, full-height presentation of a selected call. Row renderers share one pure card model for each terminal, read, diff, search, and web card, and the image card's gallery renders through the tool-owned `tool.call.images` slot. These models validate raw call arguments, result content, failure state, persisted metadata, PTC dispatch `parentCallId`, and Session path facts. Unsupported or malformed inputs use flattened Tool result text. A file-path summary opens the file through the owner's `openFile`, which the chat view routes to the right Sidebar's text preview; `inspect` opens the trajectory view. Card-specific limits and fallback rules for the terminal, diff, read, search, and web cards remain in [the ui-primitives README](../ui-primitives/README.md); the image card's model in this package carries its own fallback rules.
 
+Chat diff cards keep nine rows before folding, enough for a file header, one removed/added pair, and three context lines on either side. The collapsed row and expanded footer share the primitive's exact or coarse-replacement counts.
+
 An Auto denial takes precedence over keyed specialized views. Its generic row preserves the call identity, omits raw arguments, and normalizes the stored reason only for display: trim surrounding whitespace and collapse line separators to spaces, with localized fallback for an empty result. Session and SDK error details keep the original reason.
 
 The terminal model uses `hasSpillNotice` from the browser-safe `@deepseek-ai/dsh-spill-policy/notice` entry, not an independent UI pattern. The [spill-policy README](../../spill/spill-policy/README.md#shared-notice-ownership) owns notice formatting and recognition. This check conservatively selects generic output; matching text cannot authenticate its source, and replay leaves recorded result bytes untouched.
diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md
index 33dc7b38f8..6f01658e5f 100644
--- a/packages/client/ui-tool/README.zh.md
+++ b/packages/client/ui-tool/README.zh.md
@@ -64,6 +64,8 @@ owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`
 
 每张卡片都直接在调用树中查看；选中调用后不会再显示第二个全高视图。行 renderer 为 terminal、read、diff、search 和 web 卡片各复用同一个纯 card model，image 卡片的图库经由工具自有 `tool.call.images` slot 渲染。这些 model 校验原始调用参数、结果内容、失败状态、持久 metadata、PTC dispatch 的 `parentCallId` 与会话路径信息。不受支持或格式错误的输入使用压平的工具结果文本。文件路径摘要经属主的 `openFile` 打开文件，chat 视图把它路由到右侧 Sidebar 的文本预览；`inspect` 打开轨迹视图。terminal、diff、read、search 与 web 卡片的上限与 fallback 规则仍由 [ui-primitives README](../ui-primitives/README.zh.md) 负责；image 卡片的 fallback 规则由本包内的 card model 自行承载。
 
+Chat diff 卡片在折叠前保留九行，足以容纳文件标题、一对删除与新增行及两侧各三行上下文。折叠工具行与展开卡片底部采用原语一致的精确或粗粒度替换统计。
+
 Auto 拒绝优先于按工具名选择的专门视图。其通用行保留调用身份、省略原始参数，并且只在显示时归一化存储的理由：去除首尾空白，把行分隔符折叠为空格，结果为空时使用本地化通用理由。Session 与 SDK 错误详情保留原始理由。
 
 terminal model 使用浏览器安全入口 `@deepseek-ai/dsh-spill-policy/notice` 的 `hasSpillNotice`，而非独立的 UI 匹配规则。[spill-policy README](../../spill/spill-policy/README.zh.md#shared-notice-ownership) 负责提示文本的格式化与识别。该检查保守地选择通用输出；匹配的文本无法证明其来源，回放也不改变已记录的结果字节。
diff --git a/packages/client/ui-tool/src/client/tool/models/diff-card-model.ts b/packages/client/ui-tool/src/client/tool/models/diff-card-model.ts
index 03eaf04a3a..5343472cd0 100644
--- a/packages/client/ui-tool/src/client/tool/models/diff-card-model.ts
+++ b/packages/client/ui-tool/src/client/tool/models/diff-card-model.ts
@@ -3,16 +3,8 @@ import type { DiffBlockProps, DiffHunk } from '@deepseek-ai/dsh-client-ui-primit
 import type { ToolCallBlock } from './tool-call-model.ts'
 import { parsedToolCall, validEscalationFields } from './raw-tool-call.ts'
 
-/**
- * Diff-body lines the chat row shows before collapsing the middle — half the
- * primitive's own default, which the details panel keeps. A chat row is a
- * summary surface inside the message flow: the flow must stay scannable across
- * many calls, while the details panel is the single-call reading surface. The
- * same split {@link CHAT_TERMINAL_MAX_LINES} draws for a terminal card, so the
- * two card kinds cap a long body at the same place in the flow. A design
- * constant of this UI's row geometry, not a deployment choice.
- */
-export const CHAT_DIFF_MAX_LINES = 8
+/** Room for a path, one removed/added pair, and three context lines on each side. */
+export const CHAT_DIFF_MAX_LINES = 9
 
 /**
  * The {@link DiffBlock} props this derivation owns. Picked off the primitive's
diff --git a/packages/client/ui-tool/tests/tool-row.client.spec.tsx b/packages/client/ui-tool/tests/tool-row.client.spec.tsx
index c98f4dee8c..9a616aaecc 100644
--- a/packages/client/ui-tool/tests/tool-row.client.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.client.spec.tsx
@@ -299,6 +299,25 @@ describe('ToolRow', () => {
     expect(view.getByText('List files')).toBeTruthy()
   })
 
+  it('excludes shared context from collapsed edit totals and the expanded card', () => {
+    const view = render(<ToolRow {...rowProps} variant="edit" title="Edit" summary="settings.ts" diff={{
+      card: { diffs: [{
+        path: 'settings.ts',
+        oldText: 'start\nsecond\nthird\nold\nfourth\nfifth\nend',
+        newText: 'start\nsecond\nthird\nnew\nfourth\nfifth\nend',
+      }] },
+    }} />)
+    expect(view.getByText('+1 -1')).toBeTruthy()
+    expect(view.container.querySelector('[data-diff]')).toBeNull()
+    fireEvent.click(view.getByRole('button'))
+    expect(view.getByText(/└ \+1 -1/)).toBeTruthy()
+    expect(view.getAllByText('start')).toHaveLength(1)
+    expect(view.getAllByText('end')).toHaveLength(1)
+    expect(view.getByText('old', { exact: true })).toBeTruthy()
+    expect(view.getByText('new', { exact: true })).toBeTruthy()
+    expect(view.queryByRole('button', { name: /展开其余/ })).toBeNull()
+  })
+
   it('formats the argument body only while expanding it', () => {
     const stringify = vi.spyOn(JSON, 'stringify')
     const bodyFormatCalls = () => stringify.mock.calls.filter(
diff --git a/packages/experimental/inspector/package.json b/packages/experimental/inspector/package.json
index d5b2bce284..6e3f65cd6e 100644
--- a/packages/experimental/inspector/package.json
+++ b/packages/experimental/inspector/package.json
@@ -40,6 +40,7 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
     "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-util-crypto": "workspace:^",
     "@deepseek-ai/schemastery": "workspace:^",
diff --git a/packages/experimental/inspector/tsdown.config.ts b/packages/experimental/inspector/tsdown.config.ts
index 1265536bd7..53917a1ea2 100644
--- a/packages/experimental/inspector/tsdown.config.ts
+++ b/packages/experimental/inspector/tsdown.config.ts
@@ -1,17 +1,21 @@
 import type { UserConfig } from 'tsdown'
 import { clientBundle } from '../../client/tsdown.client.ts'
+import { profileWorkerBanner } from '../../tsdown.worker.ts'
 
 const worker: UserConfig = {
   entry: { worker: 'lib/types/worker/entry.js' },
   outDir: 'lib',
   format: ['esm'],
+  banner: profileWorkerBanner('esm'),
   platform: 'node',
   target: 'es2024',
   fixedExtension: false,
   dts: false,
   clean: false,
   outputOptions: { inlineDynamicImports: true },
-  deps: { neverBundle: specifier => specifier === 'ws' },
+  deps: { neverBundle: specifier => (
+    specifier === 'ws' || specifier === '@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap'
+  ) },
 }
 
 /** Build the Host plugin and Worker during the Host pass, and the dynamic Client plugin during the Client pass. */
diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
index ea086375d7..66c1f295eb 100644
--- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
+++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts
@@ -387,7 +387,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.composer\', () => ctx.slots.register(\n      { name: \'conversation.composer\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:158',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:157',
   },
   {
     key: 'conversation.composer.bar',
@@ -425,7 +425,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.composer.bar\', () => ctx.slots.register(\n      { name: \'conversation.composer.bar\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:176',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:175',
   },
   {
     key: 'conversation.composer.dock',
@@ -480,7 +480,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.composer.dock\', () => ctx.slots.register(\n      { name: \'conversation.composer.dock\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:170',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:169',
   },
   {
     key: 'conversation.hero.agentPreset',
@@ -510,7 +510,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.agentPreset\', () => ctx.slots.register(\n      { name: \'conversation.hero.agentPreset\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:164',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:163',
   },
   {
     key: 'conversation.hero.brand.mark',
@@ -538,7 +538,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.brand.mark\', () => ctx.slots.register(\n      { name: \'conversation.hero.brand.mark\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:162',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:161',
   },
   {
     key: 'conversation.hero.workspace',
@@ -570,7 +570,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.hero.workspace\', () => ctx.slots.register(\n      { name: \'conversation.hero.workspace\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:160',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:159',
   },
   {
     key: 'conversation.hero.workspace.directoryFlow',
@@ -641,7 +641,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.attachments\', () => ctx.slots.register(\n      { name: \'conversation.input.attachments\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:178',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:177',
   },
   {
     key: 'conversation.input.dock',
@@ -703,7 +703,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.dock\', () => ctx.slots.register(\n      { name: \'conversation.input.dock\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:166',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:165',
   },
   {
     key: 'conversation.input.left',
@@ -756,7 +756,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.left\', () => ctx.slots.register(\n      { name: \'conversation.input.left\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:172',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:171',
   },
   {
     key: 'conversation.input.model',
@@ -794,7 +794,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.model\', () => ctx.slots.register(\n      { name: \'conversation.input.model\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:188',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:187',
   },
   {
     key: 'conversation.input.overlay',
@@ -851,7 +851,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.overlay\', () => ctx.slots.register(\n      { name: \'conversation.input.overlay\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:168',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:167',
   },
   {
     key: 'conversation.input.permission',
@@ -889,7 +889,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.permission\', () => ctx.slots.register(\n      { name: \'conversation.input.permission\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:186',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:185',
   },
   {
     key: 'conversation.input.plan',
@@ -927,7 +927,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.plan\', () => ctx.slots.register(\n      { name: \'conversation.input.plan\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:184',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:183',
   },
   {
     key: 'conversation.input.right',
@@ -980,7 +980,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.input.right\', () => ctx.slots.register(\n      { name: \'conversation.input.right\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:174',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:173',
   },
   {
     key: 'conversation.message.images',
@@ -1058,7 +1058,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session\', () => ctx.slots.register(\n      { name: \'conversation.session\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:123',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:122',
   },
   {
     key: 'conversation.session.header',
@@ -1094,7 +1094,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header\', () => ctx.slots.register(\n      { name: \'conversation.session.header\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:125',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:124',
   },
   {
     key: 'conversation.session.header.actions',
@@ -1155,7 +1155,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.actions\', () => ctx.slots.register(\n      { name: \'conversation.session.header.actions\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:133',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:132',
   },
   {
     key: 'conversation.session.header.corner',
@@ -1193,7 +1193,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.corner\', () => ctx.slots.register(\n      { name: \'conversation.session.header.corner\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:150',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:149',
   },
   {
     key: 'conversation.session.header.lineage',
@@ -1233,7 +1233,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.lineage\', () => ctx.slots.register(\n      { name: \'conversation.session.header.lineage\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:127',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:126',
   },
   {
     key: 'conversation.session.header.utilities',
@@ -1291,7 +1291,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.session.header.utilities\', () => ctx.slots.register(\n      { name: \'conversation.session.header.utilities\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:139',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:138',
   },
   {
     key: 'conversation.trajectory.images',
@@ -1393,7 +1393,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'conversation.view\', () => ctx.slots.register(\n      { name: \'conversation.view\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:156',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:155',
   },
   {
     key: 'main',
@@ -1462,7 +1462,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     ],
     replaceRisk: 'shadows-shipped-ui',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'main.conversation\', () => ctx.slots.register(\n      { name: \'main.conversation\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:121',
+    source: 'packages/client/ui-conversation/src/client/contract/slots.ts:120',
   },
   {
     key: 'rightbar',
@@ -2450,6 +2450,51 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.tab.guide\', () => ctx.slots.register(\n      { name: \'sidebar.right.tab.guide\', select: owner => null },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
     source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:75',
   },
+  {
+    key: 'sidebar.right.tab.guide.entry',
+    kind: 'keyed',
+    scope: 'session',
+    summary: 'One provider\'s guide card, with the standard card as the owner\'s fallback.',
+    doc: 'One provider\'s guide card, with the standard card as the owner\'s fallback.',
+    registerOptions: [
+      {
+        name: 'key',
+        requirement: 'required',
+        type: 'string',
+        doc: 'Your cell key: the entry renders where the owner dispatches this exact key. Registering an already-occupied key replaces that occupant.',
+      },
+    ],
+    ownerProps: [
+      '/** Resolved guide copy and entry identity supplied to a provider\'s card renderer. */\nexport interface SidebarRightGuideEntryOwnerProps {\n  readonly entryId: string\n  readonly kind: string\n  readonly title: string\n  readonly description?: string\n}',
+    ],
+    ownerPropsReferences: [],
+    standardProps: [
+      'useResource: UseResource',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'usePanelInfo: UsePanelInfo',
+      'useSessions: UseSessions',
+      'useSessionPendingInteraction: UseSessionPendingInteraction',
+      'useWorkspaces: SnapshotSelectorHook<WorkspaceSnapshot>',
+      'useChat: UseChat',
+      'useConversation: UseConversation',
+      'useInput: SnapshotSelectorHook<InputState>',
+      'inputActions: InputActions',
+      'useSession: SessionSnapshotSelector',
+      'sessionId: SessionId',
+      'useProjection: UseProjection',
+      'useTrajectory: UseTrajectory',
+    ],
+    keyDomain: 'open: any string the owner dispatches (no compile-time key set), none are taken yet',
+    hookContext: 'UseSidebarRightTabInfo',
+    slotInject: '{ hooks: { tabInfo: SlotHookFactory<\'sidebar.right.tab.guide.entry\', UseSidebarRightTabInfo> } }',
+    declaredBy: 'an entry in \'sidebar.right.pane.tab\' (client-ui-sidebar-right), so it exists while that entry is mounted',
+    occupants: [
+      'client-ui-sidebar-terminal TerminalGuide',
+    ],
+    replaceRisk: 'none',
+    example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.tab.guide.entry\', () => ctx.slots.register(\n      { name: \'sidebar.right.tab.guide.entry\', key: \'<one key the owner dispatches>\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:82',
+  },
   {
     key: 'sidebar.right.tab.menu.item',
     kind: 'list',
@@ -2505,7 +2550,7 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [
     occupants: [],
     replaceRisk: 'none',
     example: 'return {\n  inject: [\'slots\'],\n  apply(ctx) {\n    ctx.slots.inject(\'sidebar.right.tab.menu.item\', () => ctx.slots.register(\n      { name: \'sidebar.right.tab.menu.item\', id: \'my-entry\', order: 100, label: \'My entry\' },\n      () => React.createElement(\'div\', null, \'hello\'),\n    ))\n  },\n}',
-    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:86',
+    source: 'packages/client/ui-sidebar-right/src/client/contract/slots.ts:94',
   },
   {
     key: 'sidebar.settings',
diff --git a/packages/fs/tool-fs-search/src/search-core.ts b/packages/fs/tool-fs-search/src/search-core.ts
index acdca37c00..f503439527 100644
--- a/packages/fs/tool-fs-search/src/search-core.ts
+++ b/packages/fs/tool-fs-search/src/search-core.ts
@@ -175,7 +175,10 @@ export function resolveRgPath(): Promise<string> {
       ? join(executable.dir, `${executable.name}-rg.exe`)
       : `${process.execPath}-rg`
     if ('pkg' in process && existsSync(executableSidecar)) return executableSidecar
-    return (await import('@vscode/ripgrep')).rgPath
+    const dependency = (await import('@vscode/ripgrep')).rgPath
+    return process.versions.electron === undefined
+      ? dependency
+      : dependency.replace(/\.asar(?=[\\/])/u, '.asar.unpacked')
   })
   return rgPathPromise
 }
diff --git a/packages/fs/tool-fs-search/tests/rg-sidecar.spec.ts b/packages/fs/tool-fs-search/tests/rg-sidecar.spec.ts
index d3a6b5e188..9afb0cef58 100644
--- a/packages/fs/tool-fs-search/tests/rg-sidecar.spec.ts
+++ b/packages/fs/tool-fs-search/tests/rg-sidecar.spec.ts
@@ -1,8 +1,8 @@
 import { join, parse } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-const { dependencyRgPath, existsSync } = vi.hoisted(() => ({
-  dependencyRgPath: '/node_modules/@vscode/ripgrep/bin/rg',
+const { dependency, existsSync } = vi.hoisted(() => ({
+  dependency: { rgPath: '/node_modules/@vscode/ripgrep/bin/rg' },
   existsSync: vi.fn(),
 }))
 const originalPlatform = process.platform
@@ -13,18 +13,21 @@ vi.mock('node:fs', async (importOriginal) => {
   return { ...actual, existsSync }
 })
 
-vi.mock('@vscode/ripgrep', () => ({ rgPath: dependencyRgPath }))
+vi.mock('@vscode/ripgrep', () => ({ get rgPath() { return dependency.rgPath } }))
 
 beforeEach(() => {
   vi.resetModules()
   existsSync.mockReset()
+  dependency.rgPath = '/node_modules/@vscode/ripgrep/bin/rg'
   Reflect.deleteProperty(process, 'pkg')
+  Reflect.deleteProperty(process.versions, 'electron')
   Reflect.defineProperty(process, 'platform', { configurable: true, enumerable: true, value: originalPlatform })
   process.execPath = originalExecPath
 })
 
 afterEach(() => {
   Reflect.deleteProperty(process, 'pkg')
+  Reflect.deleteProperty(process.versions, 'electron')
   Reflect.defineProperty(process, 'platform', { configurable: true, enumerable: true, value: originalPlatform })
   process.execPath = originalExecPath
 })
@@ -58,7 +61,7 @@ describe('ripgrep resolution', () => {
     existsSync.mockReturnValue(true)
     const { resolveRgPath } = await import('@deepseek-ai/dsh-tool-fs-search')
 
-    await expect(resolveRgPath()).resolves.toBe(dependencyRgPath)
+    await expect(resolveRgPath()).resolves.toBe(dependency.rgPath)
     expect(existsSync).not.toHaveBeenCalled()
   })
 
@@ -67,11 +70,21 @@ describe('ripgrep resolution', () => {
     existsSync.mockReturnValue(false)
     const { resolveRgPath } = await import('@deepseek-ai/dsh-tool-fs-search')
 
-    await expect(resolveRgPath()).resolves.toBe(dependencyRgPath)
+    await expect(resolveRgPath()).resolves.toBe(dependency.rgPath)
     const executable = parse(process.execPath)
     const sidecar = process.platform === 'win32'
       ? join(executable.dir, `${executable.name}-rg.exe`)
       : `${process.execPath}-rg`
     expect(existsSync).toHaveBeenCalledWith(sidecar)
   })
+
+  it('uses the unpacked executable path for an Electron ASAR dependency', async () => {
+    Reflect.defineProperty(process.versions, 'electron', { configurable: true, value: '44.0.0' })
+    dependency.rgPath = '/Applications/DeepSeek Harness.app/Contents/Resources/app.asar/dsh/node_modules/@vscode/ripgrep/bin/rg'
+    const { resolveRgPath } = await import('@deepseek-ai/dsh-tool-fs-search')
+
+    await expect(resolveRgPath()).resolves.toBe(
+      '/Applications/DeepSeek Harness.app/Contents/Resources/app.asar.unpacked/dsh/node_modules/@vscode/ripgrep/bin/rg',
+    )
+  })
 })
diff --git a/packages/llm/llm-deepseek/README.i18n.yaml b/packages/llm/llm-deepseek/README.i18n.yaml
index 9f9e1c3aa9..0ab12d4703 100644
--- a/packages/llm/llm-deepseek/README.i18n.yaml
+++ b/packages/llm/llm-deepseek/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 packages/llm/llm-deepseek/README.md
-README.md: bfa56e9b10772cd98bab934b75f32c7d651a57e3
-README.zh.md: 395b0106a920a4e31b98588d0e5a06ac19a9b745
+README.md: 48df51396e60f071503e5babd721bca0dcd18249
+README.zh.md: 9fe86f7ea6b93de847247d4a8f8434930d7d664e
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index bfa56e9b10..48df51396e 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -105,7 +105,7 @@ Connection facts are re-read once per operation through the optional settings an
 
 ### Provider-specific request fields
 
-For either protocol, when `ctx.deepseekLlmApiExtensions` is present, the adapter prepares its registered top-level fields from the exact serialized base request before `fetch`. Preparation or field collisions fail before HTTP; after a 2xx response, the adapter accepts every captured contribution before consuming SSE. Transport and non-2xx failures do not accept them. Shipped compositions use this for the optional incremental `dsh_session_log` field and the default-on active `dsh_plugin_packages` inventory; both stay outside model input.
+For either protocol, when `ctx.deepseekLlmApiExtensions` is present, the adapter prepares its registered top-level fields from the exact serialized base request before `fetch`. Preparation or field collisions fail before HTTP; after a 2xx response, the adapter accepts every captured contribution before consuming SSE. Transport and non-2xx failures do not accept them. Shipped compositions use this for the default-on incremental `dsh_session_log` field and the default-on active `dsh_plugin_packages` inventory; both stay outside model input.
 
 ### Failures and recovery
 
@@ -157,7 +157,7 @@ Read these pages when the package-level contract is not enough. They move from t
 - [LLM streaming subsystem](../../../docs/subsystems/llm-streaming.md) — the `StreamChunk` protocol and adapter contract.
 - [llm-retry](../llm-retry/README.md) — the retry executor that applies this adapter's `retryPolicy`.
 - [DeepSeek request extensions](../deepseek-llm-api-extensions/README.md) — lifecycle and acceptance semantics for provider-specific top-level fields.
-- [Session-log upload](../../session/session-log-deepseek/README.md) — the opt-in incremental `dsh_session_log` contribution.
+- [Session-log upload](../../session/session-log-deepseek/README.md) — the default-on incremental `dsh_session_log` contribution.
 - [Plugin package inventory](../plugin-package-inventory-deepseek/README.md) — the default-on `dsh_plugin_packages` contribution.
 - [Twin LLM adapters](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) — why DeepSeek ships two structurally different adapters.
 - [Mandatory app attribution headers](../../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md) — the identity every provider request carries.
diff --git a/packages/llm/llm-deepseek/README.zh.md b/packages/llm/llm-deepseek/README.zh.md
index 395b0106a9..9fe86f7ea6 100644
--- a/packages/llm/llm-deepseek/README.zh.md
+++ b/packages/llm/llm-deepseek/README.zh.md
@@ -105,7 +105,7 @@ Files 模式通过 `maxRequestFilesBytes` 与 `maxImagesPerRequest` 限制保留
 
 ### 提供方专用请求字段
 
-两种协议中，存在 `ctx.deepseekLlmApiExtensions` 时，适配器都会在 `fetch` 前根据确切序列化基础请求准备已注册顶层字段。准备或字段冲突在 HTTP 前失败；2xx 响应后，适配器会在消费 SSE（Server-Sent Events）前接受每项已捕获贡献。传输与非 2xx 失败不会接受它们。随产品交付的组合用它提供可选增量 `dsh_session_log` 字段和默认启用的活跃 `dsh_plugin_packages` 清单；两者都留在模型输入之外。
+两种协议中，存在 `ctx.deepseekLlmApiExtensions` 时，适配器都会在 `fetch` 前根据确切序列化基础请求准备已注册顶层字段。准备或字段冲突在 HTTP 前失败；2xx 响应后，适配器会在消费 SSE（Server-Sent Events）前接受每项已捕获贡献。传输与非 2xx 失败不会接受它们。随产品交付的组合用它提供默认启用的增量 `dsh_session_log` 字段和默认启用的活跃 `dsh_plugin_packages` 清单；两者都留在模型输入之外。
 
 ### 失败与恢复
 
@@ -157,7 +157,7 @@ Files 模式通过 `maxRequestFilesBytes` 与 `maxImagesPerRequest` 限制保留
 - [LLM 流式子系统](../../../docs/subsystems/llm-streaming.zh.md)——`StreamChunk` 协议与适配器约定。
 - [llm-retry](../llm-retry/README.zh.md)——应用本适配器 `retryPolicy` 的重试执行器。
 - [DeepSeek 请求扩展](../deepseek-llm-api-extensions/README.zh.md)——提供方专用顶层字段的生命周期与接受语义。
-- [会话日志上传](../../session/session-log-deepseek/README.zh.md)——可选的增量 `dsh_session_log` 贡献。
+- [会话日志上传](../../session/session-log-deepseek/README.zh.md)——默认启用的增量 `dsh_session_log` 贡献。
 - [插件包清单](../plugin-package-inventory-deepseek/README.zh.md)——默认启用的 `dsh_plugin_packages` 贡献。
 - [孪生 LLM 适配器](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md)——为什么 DeepSeek 交付两个结构不同的适配器。
 - [强制应用归因标头](../../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md)——每个提供方请求携带的身份。
diff --git a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
index 929591aabd..146fd111d4 100644
--- a/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
+++ b/packages/llm/llm-deepseek/tests/loader-composition.spec.ts
@@ -75,8 +75,8 @@ async function loadComposition(
     "  name: '@deepseek-ai/dsh-deepseek-llm-api-extensions'",
     '- id: session-log-deepseek',
     "  name: '@deepseek-ai/dsh-session-log-deepseek'",
-    ...options.enableSessionLog === true
-      ? ['  config:', '    enabled: true']
+    ...options.enableSessionLog !== undefined
+      ? ['  config:', `    enabled: ${String(options.enableSessionLog)}`]
       : [],
     '- id: plugin-package-inventory-deepseek',
     "  name: '@deepseek-ai/dsh-plugin-package-inventory-deepseek'",
@@ -152,10 +152,10 @@ async function extensionServer(protocol: 'chat-completions' | 'messages') {
 }
 
 describe('llm-deepseek real dynamic composition', () => {
-  it.each(['chat-completions', 'messages'] as const)('keeps session upload off and package inventory on by default through %s Loader composition', async (protocol) => {
+  it.each(['chat-completions', 'messages'] as const)('keeps package inventory on when the %s Loader composition disables session upload', async (protocol) => {
     vi.stubEnv('DEEPSEEK_API_KEY', 'entry-key')
     const server = await extensionServer(protocol)
-    const { ctx } = await loadComposition({ withDynamic: false, baseURL: server.url, protocol })
+    const { ctx } = await loadComposition({ withDynamic: false, baseURL: server.url, protocol, enableSessionLog: false })
     const session = ctx.sessions.create(SessionId('extension-composition'))
     session.append('turn/start', { turn: 1 })
 
@@ -171,13 +171,12 @@ describe('llm-deepseek real dynamic composition', () => {
     expect(SessionLogDeepSeek.acceptedThrough(session)).toBe(-1)
   })
 
-  it.each(['chat-completions', 'messages'] as const)('sends the canonical session suffix when the %s Loader composition explicitly enables upload', async (protocol) => {
+  it.each(['chat-completions', 'messages'] as const)('sends the canonical session suffix by default through %s Loader composition', async (protocol) => {
     vi.stubEnv('DEEPSEEK_API_KEY', 'entry-key')
     const server = await extensionServer(protocol)
     const { ctx } = await loadComposition({
       withDynamic: false,
       baseURL: server.url,
-      enableSessionLog: true,
       protocol,
     })
     const session = ctx.sessions.create(SessionId('extension-composition-enabled'))
diff --git a/packages/llm/llm-deepseek/tests/messages/adapter.e2e.ts b/packages/llm/llm-deepseek/tests/messages/adapter.e2e.ts
index 72e3ed6d53..c293dc69eb 100644
--- a/packages/llm/llm-deepseek/tests/messages/adapter.e2e.ts
+++ b/packages/llm/llm-deepseek/tests/messages/adapter.e2e.ts
@@ -139,7 +139,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('DeepSeek Messages real API', ()
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(SessionStore)
     await ctx.plugin(DeepSeekLlmApiExtensionRegistry)
-    await ctx.plugin(SessionLogDeepSeek, enabled ? { enabled: true } : {})
+    await ctx.plugin(SessionLogDeepSeek, enabled ? {} : { enabled: false })
     ctx.baseUrl = import.meta.url
     // Select the source module while Loader owns its active package entry.
     ctx.loader.internal = {
diff --git a/packages/llm/plugin-package-inventory-deepseek/README.i18n.yaml b/packages/llm/plugin-package-inventory-deepseek/README.i18n.yaml
index 63b0ceb3ac..894ccfeb5b 100644
--- a/packages/llm/plugin-package-inventory-deepseek/README.i18n.yaml
+++ b/packages/llm/plugin-package-inventory-deepseek/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 packages/llm/plugin-package-inventory-deepseek/README.md
-README.md: fd574c6526a759ecad7872bc89e3436927c21815
-README.zh.md: 5c333cef4b5ba12485bb28db7780b1f19b59bb7f
+README.md: 4da84873844722aa4fb2ec2ed28984cfe8ec4c88
+README.zh.md: 69d2717c0e44c65754e3c05bb6f89f9c7d9a3060
diff --git a/packages/llm/plugin-package-inventory-deepseek/README.md b/packages/llm/plugin-package-inventory-deepseek/README.md
index fd574c6526..4da8487384 100644
--- a/packages/llm/plugin-package-inventory-deepseek/README.md
+++ b/packages/llm/plugin-package-inventory-deepseek/README.md
@@ -35,7 +35,9 @@ Shipped profiles use the default, so every official DeepSeek request carries the
 
 Every request re-reads active non-group entries from the host Loader tree. When optional `ctx.agentPresets` is present and `sessionId` resolves to a live Agent joined to a standing preset, that preset's separate Loader tree joins the same collection; deployments without the service report the host tree only. Entries are included only while their root fiber is `ACTIVE` and their effective Loader state is enabled.
 
-Bare package and package-subpath specifiers resolve through Node's package search paths without requiring a `./package.json` export. Each ordinary entry uses its owning Loader tree base. A standing preset's root entries use the harness base, matching the preset Loader's deliberate bare-package override; nested includes retain their own bases. Relative and absolute modules walk to their nearest manifest; a manifest without `name` marks a loose module and contributes no package identity. A named package manifest must also declare a non-empty `version`, and malformed package metadata fails request preparation. Exact name/version pairs are deduplicated and sorted with a locale-independent comparison, while simultaneously active different versions remain separate.
+At activation, the plugin samples the optional `ctx.pluginPackages` service. Shipped app boot mounts that service before profile Loader entries, so bare package and package-subpath identities use the same authoritative generation as their imports, including generation misses, without requiring a `./package.json` export. If the service is absent, the plugin retains native Node package-search lookup for its lifetime and does not switch an existing inventory when a resolver mounts later. A low-level embedder that wants runtime-generation identities must therefore mount `PluginPackages` before both the Loader entries and this plugin.
+
+Each ordinary entry uses its owning Loader tree base. A standing preset's root entries use the harness base, matching the preset Loader's deliberate bare-package override; nested includes retain their own bases. Relative and absolute modules walk to their nearest manifest; a manifest without `name` marks a loose module and contributes no package identity. A named package manifest must also declare a non-empty `version`, and malformed package metadata fails request preparation. Exact name/version pairs are deduplicated and sorted with a locale-independent comparison, while simultaneously active different versions remain separate.
 
 The version-1 `dsh_plugin_packages` field contains only `{ name, version }` pairs. Disabled, pending, failed, disposed, unloading, structural `cordis:` rows, ordinary dependencies, loose files without an owning package identity, programmatically mounted child fibers, and in-memory dynamic plugins are excluded.
 
diff --git a/packages/llm/plugin-package-inventory-deepseek/README.zh.md b/packages/llm/plugin-package-inventory-deepseek/README.zh.md
index 5c333cef4b..69d2717c0e 100644
--- a/packages/llm/plugin-package-inventory-deepseek/README.zh.md
+++ b/packages/llm/plugin-package-inventory-deepseek/README.zh.md
@@ -35,7 +35,9 @@ kind: "package-reference"
 
 每次请求都会重读宿主 Loader 树中的活跃非 group 配置项。存在可选 `ctx.agentPresets` 且 `sessionId` 解析到已加入 standing preset 的存活 Agent 时，该 preset 的独立 Loader 树也会加入同一次收集；未挂载该服务的部署只报告宿主树。只有根 fiber 处于 `ACTIVE` 且 Loader 有效状态为启用的配置项才会纳入。
 
-裸包与包子路径 specifier 通过 Node 包搜索路径解析，无需包导出 `./package.json`。每个普通配置项使用其所属 Loader 树的基址。standing preset 的根配置项使用宿主基址，与 preset Loader 对裸包的显式覆写保持一致；嵌套 include 仍使用自身基址。相对与绝对模块会向上查找最近的 manifest（元数据清单）；没有 `name` 的 manifest 只标记松散模块，不贡献包身份。具名包 manifest 还必须声明非空 `version`，格式错误的包元数据会使请求准备失败。系统使用与 locale 无关的比较按确切名称／版本对去重并排序，同时存活的不同版本仍会分开保留。
+插件在激活时读取一次可选的 `ctx.pluginPackages` 服务。随附 app boot 会在 profile Loader 配置项之前挂载该服务，因此裸包和包子路径的身份使用与其 import 相同的权威 generation，包括 generation 未命中，并且无需包导出 `./package.json`。若该服务不存在，插件会在整个生命周期中保留 Node 原生包搜索，之后再挂载 resolver 也不会切换既有清单。因此，希望使用 runtime generation 身份的底层嵌入方必须先挂载 `PluginPackages`，再挂载 Loader 配置项和本插件。
+
+每个普通配置项使用其所属 Loader 树的基址。standing preset 的根配置项使用宿主基址，与 preset Loader 对裸包的显式覆写保持一致；嵌套 include 仍使用自身基址。相对与绝对模块会向上查找最近的 manifest（元数据清单）；没有 `name` 的 manifest 只标记松散模块，不贡献包身份。具名包 manifest 还必须声明非空 `version`，格式错误的包元数据会使请求准备失败。系统使用与 locale 无关的比较按确切名称／版本对去重并排序，同时存活的不同版本仍会分开保留。
 
 版本 1 的 `dsh_plugin_packages` 字段只包含 `{ name, version }` 对。系统会排除禁用、pending、failed、disposed、unloading 状态，结构性 `cordis:` 配置项，普通依赖，没有所属包身份的松散文件，以编程方式挂载的子 fiber，以及内存动态插件。
 
diff --git a/packages/llm/plugin-package-inventory-deepseek/package.json b/packages/llm/plugin-package-inventory-deepseek/package.json
index f04bbc0539..7b94b7dc81 100644
--- a/packages/llm/plugin-package-inventory-deepseek/package.json
+++ b/packages/llm/plugin-package-inventory-deepseek/package.json
@@ -49,6 +49,7 @@
     }
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^",
     "@deepseek-ai/cordis-plugin-include": "workspace:^",
     "@deepseek-ai/cordis-plugin-loader": "workspace:^",
diff --git a/packages/llm/plugin-package-inventory-deepseek/src/index.ts b/packages/llm/plugin-package-inventory-deepseek/src/index.ts
index b373a76040..83068d9d61 100644
--- a/packages/llm/plugin-package-inventory-deepseek/src/index.ts
+++ b/packages/llm/plugin-package-inventory-deepseek/src/index.ts
@@ -17,6 +17,7 @@ import type {} from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
 import type { SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-agent-presets'
+import type {} from '@deepseek-ai/dsh-app-boot'
 import type { DeepSeekPluginPackageIdentity, DeepSeekPluginPackageInventoryExtension } from './types.ts'
 import type {} from './types.ts'
 
@@ -69,12 +70,14 @@ function identityFromManifest(path: string, allowAnonymous: boolean): DeepSeekPl
 }
 
 /** Resolve a bare package without requiring it to export `./package.json`. */
-function barePackageManifest(packageName: string, anchors: readonly string[]): string | undefined {
+function barePackageManifest(
+  packageName: string, anchors: readonly string[], packages: Context['pluginPackages'] | undefined,
+): string | undefined {
   for (const anchor of anchors) {
-    const searchPaths = createRequire(anchor).resolve.paths(packageName)
-    /* v8 ignore next -- active non-builtin package entries always have Node package search paths */
-    if (searchPaths === null) continue
-    for (const searchPath of searchPaths) {
+    const pkg = packages?.packageOf(packageName, anchor)
+    if (pkg !== undefined) return pkg.manifestPath
+    if (packages !== undefined) continue
+    for (const searchPath of createRequire(anchor).resolve.paths(packageName) as string[]) {
       const manifest = join(searchPath, packageName, 'package.json')
       if (existsSync(manifest)) return manifest
     }
@@ -99,7 +102,10 @@ class PackageIdentityResolver {
   // TODO: Invalidate manifest identities if in-process package-version replacement becomes a supported upgrade path.
   private readonly cache = new Map<string, DeepSeekPluginPackageIdentity | undefined>()
 
-  constructor(private readonly hostBaseUrl: string) {}
+  constructor(
+    private readonly hostBaseUrl: string,
+    private readonly packages: Context['pluginPackages'] | undefined,
+  ) {}
 
   /** Resolve one Loader entry's owning package, or absence for a non-package loose module. */
   resolve({ entry, bareBaseUrl }: ActiveEntry): DeepSeekPluginPackageIdentity | undefined {
@@ -112,7 +118,7 @@ class PackageIdentityResolver {
     const packageName = barePackageName(entry.options.name)
     let manifest: string | undefined
     if (packageName !== undefined) {
-      manifest = barePackageManifest(packageName, anchors)
+      manifest = barePackageManifest(packageName, anchors, this.packages)
       if (manifest === undefined) {
         throw new Error(`plugin-package-inventory-deepseek: cannot resolve active package ${JSON.stringify(packageName)}`)
       }
@@ -186,7 +192,7 @@ async function collectActivePluginPackages(
 export function apply(ctx: Context, config: Config): void {
   if (config.enabled === false) return
   const hostBaseUrl = ctx.baseUrl ?? import.meta.url
-  const resolver = new PackageIdentityResolver(hostBaseUrl)
+  const resolver = new PackageIdentityResolver(hostBaseUrl, ctx.get('pluginPackages'))
   ctx.deepseekLlmApiExtensions.register('dsh_plugin_packages', {
     prepare: async (request) => {
       const value: DeepSeekPluginPackageInventoryExtension = {
diff --git a/packages/llm/plugin-package-inventory-deepseek/tests/inventory.spec.ts b/packages/llm/plugin-package-inventory-deepseek/tests/inventory.spec.ts
index 1faf55e7a6..ef42c27139 100644
--- a/packages/llm/plugin-package-inventory-deepseek/tests/inventory.spec.ts
+++ b/packages/llm/plugin-package-inventory-deepseek/tests/inventory.spec.ts
@@ -11,6 +11,7 @@ import { SessionId } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import { createScope } from '@deepseek-ai/dsh-scope'
 import AgentPresets, { mountPreset } from '@deepseek-ai/dsh-agent-presets'
+import { PluginPackages } from '@deepseek-ai/dsh-app-boot'
 import DeepSeekLlmApiExtensionRegistry from '@deepseek-ai/dsh-deepseek-llm-api-extensions'
 import * as PluginInventory from '../src/index.ts'
 
@@ -36,13 +37,16 @@ async function packagePlugin(
   return `./${dir}/plugin.mjs`
 }
 
-async function harness(enabled?: boolean): Promise<{ ctx: Context; root: string; disposeInventory: () => Promise<void> }> {
+async function harness(
+  enabled?: boolean, packageService = false,
+): Promise<{ ctx: Context; root: string; disposeInventory: () => Promise<void> }> {
   const root = await mkdtemp(join(tmpdir(), 'dsh-plugin-packages-'))
   roots.push(root)
   const ctx = new Context()
   contexts.push(ctx)
   ctx.baseUrl = pathToFileURL(join(root, 'cordis.yml')).href
   await ctx.plugin(Loader)
+  if (packageService) await ctx.plugin(PluginPackages)
   ctx.loader.builtins.include = Include
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(SessionProjectionRegistry)
@@ -125,7 +129,7 @@ describe('DeepSeek plugin package inventory', () => {
   })
 
   it('resolves scoped and unscoped bare subpaths, absolute/file modules, and skips URL or Cordis modules', async () => {
-    const { ctx, root } = await harness()
+    const { ctx, root } = await harness(undefined, true)
     await packagePlugin(root, 'node_modules/plain-package', { name: 'plain-package', version: '1.0.0' })
     await packagePlugin(root, 'node_modules/@scope/scoped-package', { name: '@scope/scoped-package', version: '2.0.0' })
     await packagePlugin(root, 'absolute-package', { name: 'absolute-package', version: '3.0.0' })
@@ -169,6 +173,18 @@ describe('DeepSeek plugin package inventory', () => {
       .rejects.toThrow(/cannot resolve active package/)
   })
 
+  it('does not bypass the profile package service for a missing bare package', async () => {
+    const { ctx } = await harness(undefined, true)
+    ctx.loader.internal = {
+      version: 'v2',
+      import: async () => ({ default: () => {} }),
+    } as unknown as NonNullable<typeof ctx.loader.internal>
+    await ctx.loader.create({ name: 'missing-profile-package' })
+
+    await expect(ctx.deepseekLlmApiExtensions.prepare({ body: { messages: [] }, signal: SIGNAL }))
+      .rejects.toThrow(/cannot resolve active package/)
+  })
+
   it('supports a direct embedding whose context has no base URL', async () => {
     const ctx = new Context()
     contexts.push(ctx)
diff --git a/packages/llm/plugin-package-inventory-deepseek/tsconfig.json b/packages/llm/plugin-package-inventory-deepseek/tsconfig.json
index 939e130d32..76699c3da7 100644
--- a/packages/llm/plugin-package-inventory-deepseek/tsconfig.json
+++ b/packages/llm/plugin-package-inventory-deepseek/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../boot/app-boot"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/packages/preset/agent-presets/README.i18n.yaml b/packages/preset/agent-presets/README.i18n.yaml
index af5b82eef3..c21f9f13b5 100644
--- a/packages/preset/agent-presets/README.i18n.yaml
+++ b/packages/preset/agent-presets/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 packages/preset/agent-presets/README.md
-README.md: 07691afa0b0c37327e553df8e55d221bbb9a8bcf
-README.zh.md: 3fa2d633c0ffae84d843795a42ff6d3a5adcc39f
+README.md: d0eb1c108eaef091c776992c144ba389be2cf6c0
+README.zh.md: e9c1a35b22a1764e444c5757a1e34761bdc24fdf
diff --git a/packages/preset/agent-presets/README.md b/packages/preset/agent-presets/README.md
index 07691afa0b..d0eb1c108e 100644
--- a/packages/preset/agent-presets/README.md
+++ b/packages/preset/agent-presets/README.md
@@ -83,7 +83,7 @@ A session can switch to a different preset only while it has produced nothing 
 
 ### Failures and recovery
 
-A preset whose composition is missing, unparsable, not a list of named plugin rows, or naming a module that cannot be resolved is listed as broken with a reason naming the rows at fault; composing such a preset is refused up front, so a session never starts half-composed. What survives to session creation is a row whose module loads and then refuses — a plugin that throws, or one waiting for a service the composition never supplies — which fails the creation and rolls it back, naming every failed row including those inside a group. Fix the preset's file or delete it, then retry.
+A preset whose composition is missing, unparsable, not a list of named plugin rows, or naming a module that cannot be resolved is listed as broken with a reason naming the rows at fault; a package-lookup failure marks only the preset being checked as broken, while the rest of the roster remains available. Composing a broken preset is refused up front, so a session never starts half-composed. What survives to session creation is a row whose module loads and then refuses — a plugin that throws, or one waiting for a service the composition never supplies — which fails the creation and rolls it back, naming every failed row including those inside a group. Fix the preset's file or delete it, then retry.
 
 -----
 
diff --git a/packages/preset/agent-presets/README.zh.md b/packages/preset/agent-presets/README.zh.md
index 3fa2d633c0..e9c1a35b22 100644
--- a/packages/preset/agent-presets/README.zh.md
+++ b/packages/preset/agent-presets/README.zh.md
@@ -83,7 +83,7 @@ agent-presets:
 
 ### 失败与恢复
 
-组装缺失、无法解析、不是具名插件行列表，或者引用了无法解析的模块的 preset 会被列为 broken，原因会指名出问题的行；组装此类 preset 会被提前拒绝，因此会话绝不会以半组装状态启动。能活到会话创建的，是模块能加载但随后拒绝的行——抛错的插件，或等待组装从未提供的服务的插件——它会让创建失败并回滚，且会指名每一个失败的行，包括组内的行。修复 preset 的文件或删除它，然后重试。
+组装缺失、无法解析、不是具名插件行列表，或者引用了无法解析的模块的 preset 会被列为 broken，原因会指名出问题的行；包查询失败只会把正在检查的 preset 标为 broken，名单中的其他 preset 仍然可用。组装 broken preset 会被提前拒绝，因此会话绝不会以半组装状态启动。能活到会话创建的，是模块能加载但随后拒绝的行——抛错的插件，或等待组装从未提供的服务的插件——它会让创建失败并回滚，且会指名每一个失败的行，包括组内的行。修复 preset 的文件或删除它，然后重试。
 
 -----
 
diff --git a/packages/preset/agent-presets/package.json b/packages/preset/agent-presets/package.json
index 61a2ad9f75..587b47f1c7 100644
--- a/packages/preset/agent-presets/package.json
+++ b/packages/preset/agent-presets/package.json
@@ -75,6 +75,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
     "@deepseek-ai/cordis-plugin-group": "workspace:^",
     "@deepseek-ai/cordis-plugin-include": "workspace:^",
     "@deepseek-ai/cordis-plugin-loader": "workspace:^",
diff --git a/packages/preset/agent-presets/src/discovery.ts b/packages/preset/agent-presets/src/discovery.ts
index 8d39410b00..30daf0221e 100644
--- a/packages/preset/agent-presets/src/discovery.ts
+++ b/packages/preset/agent-presets/src/discovery.ts
@@ -97,25 +97,19 @@ export function entryListProblem(rows: unknown, at = ''): string | undefined {
   return undefined
 }
 
+/** Package lookup injected into preset discovery. */
+type PackageResolves = (specifier: string, base: string) => boolean
+
 /**
- * Whether a package name is installed anywhere above `base`.
+ * Whether a package specifier is installed above `base` without importing it.
  *
- * Node's own upward `node_modules` walk, stopping at the package directory:
- * the question is whether the package is there at all, which is what a row
- * naming a package a rename or an uninstall took away gets wrong. A pnpm
- * store link answers through the symlink, and a link left dangling by a
- * deleted checkout answers false — the shape a stale profile install leaves.
- *
- * `existsSync` rather than the async `stat`: the walk is a handful of lookups
- * per package and runs on every roster read, where 150 promise round-trips
- * cost more than the lookups they wrap.
- * @param name - the package specifier, possibly carrying a subpath.
- * @param base - the URL to walk up from.
- * @returns true when the package directory is installed above `base`.
+ * The direct disk walk accepts unexported subpaths and rejects stale links
+ * whose package directory no longer exists.
+ * @param name - package specifier, possibly carrying a subpath.
+ * @param base - directory URL whose ancestors contain candidate `node_modules` directories.
+ * @returns true when the package is installed.
  */
 function packageInstalled(name: string, base: string): boolean {
-  // A scoped name spends two segments on the package; anything after either
-  // form is a subpath export, which lives inside the package directory.
   const pkg = name.split('/').slice(0, name.startsWith('@') ? 2 : 1).join('/')
   let dir = fileURLToPath(base)
   for (;;) {
@@ -129,35 +123,19 @@ function packageInstalled(name: string, base: string): boolean {
 /**
  * Whether one classified row names a module that exists, importing nothing.
  *
- * Each kind is checked by what actually answers it. A package name is looked
- * up on disk — the same upward walk Node's own resolver starts with — and a
- * relative or `file:` specifier is statted, because both name one file.
- * Nothing is evaluated either way, so a row is judged without its plugin
- * observing that discovery looked.
- *
- * `import.meta.resolve` is deliberately not the fallback for a name the disk
- * lookup misses. Its `parentURL` argument only takes effect under
- * `--experimental-import-meta-resolve`, which no launch passes, so it would
- * resolve from THIS module rather than from the harness — reporting a
- * dependency visible only to this package as healthy, and a plugin the mount
- * can import as broken. The resolver that does honour an explicit parent is
- * the Loader's internal one, whose `resolveSync` signature differs between
- * Node 22 and 24 (`ModuleLoader.fromInternal` tags the raw object rather than
- * normalising it); reaching into that for a case the walk already covers buys
- * nothing a supported deployment needs, because every plugin a preset names
- * is installed beside the roster.
- *
- * What that gives up: a package resolvable ONLY through a loader hook — an
- * import map, or a tree with no `node_modules` at all — is reported broken.
- * No supported install produces one.
+ * Package rows delegate to the injected lookup. Relative and `file:` rows use
+ * file metadata. No check evaluates the named module.
  * @param row - the classified specifier, from {@link classifyRowSpecifier}.
  * @param presetBase - directory URL a preset-relative specifier resolves against.
  * @param harnessBase - base URL a package name resolves against.
+ * @param resolves - package lookup selected by the owning caller.
  * @returns true when the row names something that can be imported.
  */
-async function rowResolves(row: RowSpecifier, presetBase: string, harnessBase: string): Promise<boolean> {
+async function rowResolves(
+  row: RowSpecifier, presetBase: string, harnessBase: string, resolves: PackageResolves,
+): Promise<boolean> {
   if (row.kind === 'builtin') return true
-  if (row.kind === 'package') return isBuiltin(row.specifier) || packageInstalled(row.specifier, harnessBase)
+  if (row.kind === 'package') return isBuiltin(row.specifier) || resolves(row.specifier, harnessBase)
   const url = row.kind === 'file' ? new URL(row.specifier) : new URL(row.specifier, presetBase)
   return await isFile(fileURLToPath(url))
 }
@@ -195,6 +173,7 @@ async function unresolvableRows(
   rows: readonly unknown[],
   presetBase: string,
   harnessBase: string,
+  resolves: PackageResolves,
   at = '',
 ): Promise<UnresolvableRow[]> {
   const found: UnresolvableRow[] = []
@@ -203,10 +182,10 @@ async function unresolvableRows(
     if (Boolean(row.disabled)) continue
     const positional = at === '' ? `row ${String(index + 1)}` : `${at} row ${String(index + 1)}`
     if (row.group === true) {
-      found.push(...await unresolvableRows(row.config as readonly unknown[], presetBase, harnessBase, positional))
+      found.push(...await unresolvableRows(row.config as readonly unknown[], presetBase, harnessBase, resolves, positional))
       continue
     }
-    if (await rowResolves(classifyRowSpecifier(row.name), presetBase, harnessBase)) continue
+    if (await rowResolves(classifyRowSpecifier(row.name), presetBase, harnessBase, resolves)) continue
     const label = typeof row.id === 'string' && row.id !== '' ? `row "${row.id}"` : positional
     found.push({ label, name: row.name })
   }
@@ -218,11 +197,15 @@ async function unresolvableRows(
  * loadable. Parsed with the loader's own YAML dialect ({@link entryListSchema},
  * the one carrying `!!js`), so health can never call a composition broken
  * that the loader would accept.
+ * A package-lookup failure becomes this composition's broken reason, so one
+ * preset cannot abort discovery of the rest of the roster.
  * @param path - absolute path of the composition file.
  * @param harnessBase - base URL a row's package name resolves against.
  * @returns one human-readable reason, or undefined when the file is loadable.
  */
-async function compositionProblem(path: string, harnessBase: string): Promise<string | undefined> {
+async function compositionProblem(
+  path: string, harnessBase: string, resolves: PackageResolves,
+): Promise<string | undefined> {
   let content: string
   try {
     content = await readFile(path, 'utf8')
@@ -246,7 +229,13 @@ async function compositionProblem(path: string, harnessBase: string): Promise<st
   // The composition's own directory, exactly as `Include` derives it, so a
   // row naming a file the preset ships resolves the way the mount will.
   const presetBase = new URL('.', pathToFileURL(path)).href
-  const unresolvable = await unresolvableRows(rows as readonly unknown[], presetBase, harnessBase)
+  let unresolvable: UnresolvableRow[]
+  try {
+    unresolvable = await unresolvableRows(rows as readonly unknown[], presetBase, harnessBase, resolves)
+  } catch (error) {
+    const full = error instanceof Error ? error.message : String(error)
+    return `the composition's plugins cannot be checked: ${full.replace(/\n[\s\S]*$/, '')}`
+  }
   const [first] = unresolvable
   if (first === undefined) return undefined
   if (unresolvable.length === 1) {
@@ -287,9 +276,12 @@ async function isFile(path: string): Promise<boolean> {
  * @param root - the directory and the trust its presets inherit.
  * @param harnessBase - base URL a row's package name resolves against; the
  * caller's own `ctx.baseUrl`, which is where the installed harness lives.
+ * @param resolves - package-presence lookup for the active runtime.
  * @returns the root's presets ordered by id.
  */
-export async function scanRoot(root: PresetRoot, harnessBase: string): Promise<AgentPreset[]> {
+export async function scanRoot(
+  root: PresetRoot, harnessBase: string, resolves: PackageResolves = packageInstalled,
+): Promise<AgentPreset[]> {
   const dir = resolve(expandHomePath(root.path))
   let children
   try {
@@ -304,7 +296,7 @@ export async function scanRoot(root: PresetRoot, harnessBase: string): Promise<A
     const directory = join(dir, child.name)
     const path = join(directory, COMPOSITION_FILE)
     const broken = await isFile(path)
-      ? await compositionProblem(path, harnessBase)
+      ? await compositionProblem(path, harnessBase, resolves)
       : `the composition file ${COMPOSITION_FILE} is missing — the directory still occupies the id; delete it or restore the file`
     // Display text only, and never fatal: a preset with unreadable metadata
     // still mounts, it just shows its id.
@@ -326,15 +318,17 @@ export async function scanRoot(root: PresetRoot, harnessBase: string): Promise<A
  * Scan every root in precedence order.
  * @param roots - roots in precedence order; an earlier root wins a duplicate id.
  * @param harnessBase - base URL a row's package name resolves against.
+ * @param resolves - package-presence lookup for the active runtime.
  * @returns every discovered preset, first-root-wins per id.
  */
 export async function discoverPresets(
   roots: readonly PresetRoot[],
   harnessBase: string,
+  resolves: PackageResolves = packageInstalled,
 ): Promise<AgentPreset[]> {
   const byId = new Map<string, AgentPreset>()
   for (const root of roots) {
-    for (const preset of await scanRoot(root, harnessBase)) {
+    for (const preset of await scanRoot(root, harnessBase, resolves)) {
       if (byId.has(preset.id)) continue
       byId.set(preset.id, preset)
     }
diff --git a/packages/preset/agent-presets/src/index.ts b/packages/preset/agent-presets/src/index.ts
index 5c0875bfab..270cc43082 100644
--- a/packages/preset/agent-presets/src/index.ts
+++ b/packages/preset/agent-presets/src/index.ts
@@ -29,6 +29,7 @@ import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typer
 import { bindScopeParent, createScope, scopeOf, type Scope, type ScopeKey, type ScopeParentBinding } from '@deepseek-ai/dsh-scope'
 // Type-only: resolves the `agent/created` lifecycle event this service watches.
 import type {} from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-app-boot'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { AgentPresetDocument, AgentPresetRoster } from './types.ts'
 import type {} from '@deepseek-ai/dsh-session-projection'
@@ -139,7 +140,6 @@ export class AgentPresets extends TypertRemoteService {
    * base here is what lets health answer the question before a session does.
    */
   private readonly harnessBase: string
-
   /**
    * The user layer over `config.default`, present only while a settings
    * provider is composed. Held rather than snapshotted so a hot-reloaded
@@ -263,7 +263,14 @@ export class AgentPresets extends TypertRemoteService {
    * @returns the presets, first-root-wins per id.
    */
   async list(): Promise<AgentPreset[]> {
-    return await discoverPresets(this.resolvedRoots, this.harnessBase)
+    const packages = this.ctx.get('pluginPackages')
+    return packages === undefined
+      ? await discoverPresets(this.resolvedRoots, this.harnessBase)
+      : await discoverPresets(
+        this.resolvedRoots,
+        this.harnessBase,
+        (specifier, base) => packages.packageOf(specifier, base) !== undefined,
+      )
   }
 
   /**
diff --git a/packages/preset/agent-presets/tests/mount.spec.ts b/packages/preset/agent-presets/tests/mount.spec.ts
index 660fdcdecd..417aaa1d1d 100644
--- a/packages/preset/agent-presets/tests/mount.spec.ts
+++ b/packages/preset/agent-presets/tests/mount.spec.ts
@@ -6,6 +6,7 @@ import { Context } from '@deepseek-ai/cordis'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
 import Include from '@deepseek-ai/cordis-plugin-include'
 import Group from '@deepseek-ai/cordis-plugin-group'
+import { PluginPackages } from '@deepseek-ai/dsh-app-boot'
 import LlmRuntime from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
@@ -44,6 +45,7 @@ async function harness(roster: Config = { default: 'standard', roots: ROOTS, inc
   const ctx = new Context()
   ctx.baseUrl = pathToFileURL(FIXTURES).href + '/'
   await ctx.plugin(Loader)
+  await ctx.plugin(PluginPackages)
   ctx.loader.builtins.include = Include
   // A preset outside this workspace cannot resolve `cordis-plugin-group` by
   // name, so the app registers it as a builtin; the fixtures compose the same
@@ -373,6 +375,59 @@ describe('the preset roster', () => {
     expect(listed.find(preset => preset.id === 'not-a-preset')?.broken).toMatch(/is missing/)
   })
 
+  it('uses the profile package service when checking bare package rows', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-preset-profile-package-'))
+    roots.push(root)
+    const presetDir = join(root, 'profile-package')
+    await mkdir(presetDir)
+    await writeFile(join(presetDir, COMPOSITION_FILE), '- id: package\n  name: profile-package/plugin.js\n')
+    const scoped = await harness({
+      default: 'profile-package', roots: [{ path: root, trust: 'user' }],
+      includeShippedRoot: false, includeUserRoot: false,
+    })
+    const packageOf = vi.spyOn(scoped.pluginPackages, 'packageOf').mockReturnValue({
+      name: 'profile-package', version: '1.0.0', dir: presetDir,
+      manifestPath: join(presetDir, 'package.json'), manifest: {},
+    })
+
+    const [listed] = await scoped.agentPresets.list()
+    expect(listed).toMatchObject({ id: 'profile-package', trust: 'user' })
+    expect(listed?.broken).toBeUndefined()
+    expect(packageOf).toHaveBeenCalledWith('profile-package/plugin.js', pathToFileURL(FIXTURES).href + '/')
+  })
+
+  it('isolates a package lookup failure to the preset being checked', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-preset-package-failure-'))
+    roots.push(root)
+    await mkdir(join(root, 'healthy'))
+    await writeFile(join(root, 'healthy', COMPOSITION_FILE), '[]\n')
+    await mkdir(join(root, 'lookup-failure'))
+    await writeFile(
+      join(root, 'lookup-failure', COMPOSITION_FILE),
+      '- id: package\n  name: profile-package/plugin.js\n',
+    )
+    const scoped = await harness({
+      default: 'healthy', roots: [{ path: root, trust: 'user' }],
+      includeShippedRoot: false, includeUserRoot: false,
+    })
+    const packageOf = vi.spyOn(scoped.pluginPackages, 'packageOf').mockImplementation(() => {
+      throw new Error('profile package lookup failed')
+    })
+
+    const listed = await scoped.agentPresets.list()
+    expect(listed.find(preset => preset.id === 'lookup-failure')?.broken)
+      .toBe("the composition's plugins cannot be checked: profile package lookup failed")
+    expect(listed.find(preset => preset.id === 'healthy')?.broken).toBeUndefined()
+    await expect(agentOn(scoped, 'sess-after-package-failure')).resolves.toBeDefined()
+
+    packageOf.mockImplementation(() => {
+      throw 'raw profile package lookup failed'
+    })
+    const rawListed = await scoped.agentPresets.list()
+    expect(rawListed.find(preset => preset.id === 'lookup-failure')?.broken)
+      .toBe("the composition's plugins cannot be checked: raw profile package lookup failed")
+  })
+
   it('exposes the configured default id', () => {
     expect(ctx.agentPresets.defaultId).toBe('standard')
   })
diff --git a/packages/preset/agent-presets/tsconfig.json b/packages/preset/agent-presets/tsconfig.json
index c357b1f257..f21a5996f9 100644
--- a/packages/preset/agent-presets/tsconfig.json
+++ b/packages/preset/agent-presets/tsconfig.json
@@ -6,6 +6,9 @@
   },
   "include": ["src"],
   "references": [
+    {
+      "path": "../../boot/app-boot"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/packages/session/session-log-deepseek/README.i18n.yaml b/packages/session/session-log-deepseek/README.i18n.yaml
index e4454a89b6..cf0a308cb4 100644
--- a/packages/session/session-log-deepseek/README.i18n.yaml
+++ b/packages/session/session-log-deepseek/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 packages/session/session-log-deepseek/README.md
-README.md: 29252c974d465b769922742510d597bc4d6c8553
-README.zh.md: 7aad6382dd0102c77530336d1d235f161dd2a221
+README.md: 27396f96191e0f88268558a1426b28e0b7dc6f12
+README.zh.md: a2840223f043283b0f7f0176108d23a5c94213ef
diff --git a/packages/session/session-log-deepseek/README.md b/packages/session/session-log-deepseek/README.md
index 29252c974d..27396f9619 100644
--- a/packages/session/session-log-deepseek/README.md
+++ b/packages/session/session-log-deepseek/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Incremental canonical session-log upload for official DeepSeek LLM API requests. This function plugin injects `ctx.sessions` and `ctx.deepseekLlmApiExtensions`, then owns the `dsh_session_log` request field and the durable `session-log-deepseek/delivery-accepted` event from which it derives the acceptance watermark. Enable it only when the official API should receive a Session-log suffix.
+Incremental canonical session-log upload for official DeepSeek LLM API requests. This function plugin injects `ctx.sessions` and `ctx.deepseekLlmApiExtensions`, then owns the `dsh_session_log` request field and the durable `session-log-deepseek/delivery-accepted` event from which it derives the acceptance watermark. Disable it only when the official API must not receive a Session-log suffix.
 
 ## Table of Contents
 
@@ -27,9 +27,9 @@ Incremental canonical session-log upload for official DeepSeek LLM API requests.
 
 | Key | Default | Meaning |
 |---|---:|---|
-| `enabled` | `false` | Register the `dsh_session_log` contribution. Set it to `true` to opt into Session-log upload. |
+| `enabled` | `true` | Register the `dsh_session_log` contribution. Set it to `false` to stop Session-log upload. |
 
-Shipped profiles mount the plugin so an overlay can enable it, but the default configuration registers no request field and appends no acceptance watermark.
+Shipped profiles mount the plugin, so the default configuration registers the request field and appends the acceptance watermark; an overlay opts out with `enabled: false`.
 
 <a id="request-field"></a>
 ## Request field
@@ -70,7 +70,6 @@ None; the model-visible request prefix remains unchanged.
 - **No live Session means no field** — direct or stale-session calls have no canonical log to snapshot; explicit absence semantics remain deferred.
 - **No independent request-size cap** — complete delivery is fail-closed; provider rejection leaves the cursor unchanged instead of truncating the log.
 
-
 <a id="dev-note"></a>
 ### Dev Note
 
diff --git a/packages/session/session-log-deepseek/README.zh.md b/packages/session/session-log-deepseek/README.zh.md
index 7aad6382dd..a2840223f0 100644
--- a/packages/session/session-log-deepseek/README.zh.md
+++ b/packages/session/session-log-deepseek/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-用于 DeepSeek 官方 LLM（大语言模型）API 请求的增量规范会话日志上传。该函数插件注入 `ctx.sessions` 与 `ctx.deepseekLlmApiExtensions`，并拥有 `dsh_session_log` 请求字段以及用于派生接受水位的持久 `session-log-deepseek/delivery-accepted` 事件。仅当官方 API 需要接收会话日志后缀时才启用它。
+用于 DeepSeek 官方 LLM（大语言模型）API 请求的增量规范会话日志上传。该函数插件注入 `ctx.sessions` 与 `ctx.deepseekLlmApiExtensions`，并拥有 `dsh_session_log` 请求字段以及用于派生接受水位的持久 `session-log-deepseek/delivery-accepted` 事件。仅当官方 API 不得接收会话日志后缀时才禁用它。
 
 ## 目录
 
@@ -27,9 +27,9 @@ kind: "package-reference"
 
 | 配置键 | 默认值 | 含义 |
 |---|---:|---|
-| `enabled` | `false` | 注册 `dsh_session_log` 贡献。将其设为 `true` 可选择启用会话日志上传。 |
+| `enabled` | `true` | 注册 `dsh_session_log` 贡献。将其设为 `false` 可停止会话日志上传。 |
 
-随附 profile 会挂载该插件，让 overlay 可以启用它；默认配置不会注册请求字段，也不会追加接受水位。
+随附 profile 会挂载该插件，因此默认配置会注册请求字段并追加接受水位；overlay 可用 `enabled: false` 选择退出。
 
 <a id="request-field"></a>
 ## 请求字段
@@ -70,7 +70,6 @@ DeepSeek 适配器会在 HTTP 2xx 后、消费 SSE（Server-Sent Events）正文
 - **缺少存活会话就没有字段**——直接调用或陈旧会话调用没有可供快照的规范日志；显式缺失语义仍暂缓处理。
 - **没有独立请求大小上限**——完整交付采用 fail-closed 策略；提供方拒绝会保持游标不变，而非截断日志。
 
-
 <a id="dev-note"></a>
 ### 开发备注
 
diff --git a/packages/session/session-log-deepseek/src/index.ts b/packages/session/session-log-deepseek/src/index.ts
index 1147927bd5..2e48cf6b52 100644
--- a/packages/session/session-log-deepseek/src/index.ts
+++ b/packages/session/session-log-deepseek/src/index.ts
@@ -36,13 +36,13 @@ export const inject = ['deepseekLlmApiExtensions', 'sessions']
 
 /** Session-log request contribution configuration. */
 export interface Config {
-  /** Contribute `dsh_session_log` to official DeepSeek requests. Defaults to `false`. */
+  /** Contribute `dsh_session_log` to official DeepSeek requests. Defaults to `true`. */
   enabled?: boolean
 }
 
 /** Validated Session-log request contribution configuration. */
 export const Config: z<Config> = z.object({
-  enabled: z.boolean().default(false),
+  enabled: z.boolean().default(true),
 })
 
 interface AcceptanceFold {
@@ -153,7 +153,7 @@ export function acceptedThrough(session: Session): SessionSeqCursor {
 /**
  * Register the incremental `dsh_session_log` request contribution when enabled.
  * @param ctx - plugin context carrying Sessions and the DeepSeek request-extension registry.
- * @param config - validated opt-in configuration.
+ * @param config - validated configuration.
  */
 export function apply(ctx: Context, config: Config): void {
   if (config.enabled !== true) return
diff --git a/packages/session/session-log-deepseek/tests/config.spec.ts b/packages/session/session-log-deepseek/tests/config.spec.ts
new file mode 100644
index 0000000000..d331ccf465
--- /dev/null
+++ b/packages/session/session-log-deepseek/tests/config.spec.ts
@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+  vi.resetModules()
+})
+
+describe('session-log upload configuration', () => {
+  it.each([
+    { lane: 'ordinary process', vitest: undefined, snapshot: undefined, enabled: true },
+    { lane: 'Vitest', vitest: 'true', snapshot: undefined, enabled: true },
+    { lane: 'snapshot process', vitest: undefined, snapshot: '1', enabled: true },
+    { lane: 'Vitest snapshot', vitest: 'true', snapshot: '1', enabled: true },
+    { lane: 'empty Vitest marker', vitest: '', snapshot: undefined, enabled: true },
+    { lane: 'empty snapshot marker', vitest: undefined, snapshot: '', enabled: true },
+  ])('defaults upload for $lane and honors explicit overrides', async ({ vitest, snapshot, enabled }) => {
+    vi.stubEnv('VITEST', vitest)
+    vi.stubEnv('DSH_SNAPSHOT', snapshot)
+    try {
+      // Import under each environment to catch environment-dependent schema defaults.
+      vi.resetModules()
+      const { Config } = await import('../src/index.ts')
+      expect(Config({}).enabled).toBe(enabled)
+      expect(Config({ enabled: true }).enabled).toBe(true)
+      expect(Config({ enabled: false }).enabled).toBe(false)
+    } finally {
+      vi.unstubAllEnvs()
+      vi.resetModules()
+    }
+  })
+})
diff --git a/packages/session/session-log-deepseek/tests/upload.spec.ts b/packages/session/session-log-deepseek/tests/upload.spec.ts
index 7527b8b92a..abd4fafc67 100644
--- a/packages/session/session-log-deepseek/tests/upload.spec.ts
+++ b/packages/session/session-log-deepseek/tests/upload.spec.ts
@@ -146,13 +146,13 @@ describe('incremental DeepSeek session-log upload', () => {
     }
   })
 
-  it('does not contribute the session log under its default configuration', async () => {
+  it('does not contribute the session log when explicitly disabled', async () => {
     const ctx = new Context()
     contexts.push(ctx)
     await ctx.plugin(SessionStore)
     await ctx.plugin(DeepSeekLlmApiExtensionRegistry)
-    await ctx.plugin(SessionLogDeepSeek)
-    const session = ctx.sessions.create(SessionId('default-off'))
+    await ctx.plugin(SessionLogDeepSeek, { enabled: false })
+    const session = ctx.sessions.create(SessionId('explicit-off'))
     session.append('turn/start', { turn: 1 })
 
     const prepared = await ctx.deepseekLlmApiExtensions.prepare({
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index 877cf6a778..d57e66a6cd 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -136,7 +136,8 @@ async function waitGone(pid: number, timeoutMs = 5_000): Promise<void> {
         const state = stat.slice(stat.lastIndexOf(')') + 2, stat.lastIndexOf(')') + 3)
         if (state === 'Z' || state === 'X') return
       } catch (error: unknown) {
-        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+        const code = (error as NodeJS.ErrnoException).code
+        if (code === 'ENOENT' || code === 'ESRCH') return
         throw error
       }
     }
diff --git a/packages/terminal/terminal-bash/README.i18n.yaml b/packages/terminal/terminal-bash/README.i18n.yaml
index bca3a7a14f..39eb44a0cc 100644
--- a/packages/terminal/terminal-bash/README.i18n.yaml
+++ b/packages/terminal/terminal-bash/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 packages/terminal/terminal-bash/README.md
-README.md: 465eb2dbe195d5129c5545fa2a91ab001cd4e08e
-README.zh.md: 256a68e0b640947567c0c2c356afbedb96934e72
+README.md: 466a42f46844d16b85d8754df0bd910361e2e401
+README.zh.md: 7ca41883f6c807102c75b25e531187a7ab148cbf
diff --git a/packages/terminal/terminal-bash/README.md b/packages/terminal/terminal-bash/README.md
index 465eb2dbe1..466a42f468 100644
--- a/packages/terminal/terminal-bash/README.md
+++ b/packages/terminal/terminal-bash/README.md
@@ -85,6 +85,8 @@ This section explains the design behind the backend and points at the code that
 
 One backend serves both dialects: bash and pwsh share the same session machinery — sanitizer, bounded buffers, readiness polling, cancellation, and teardown — and differ only in argv, environment, and prompt installation. Bash receives a private marker through `PS1` plus `PROMPT_COMMAND`. Pwsh writes a prompt function, pins UTF-8 console encoding, and publishes startup only after the backend reports `stdin_read`; echoed setup text cannot publish the shell. A zero-scrollback `@xterm/headless` instance consumes raw PTY data and returns terminal-protocol replies through the same handle, while the line sanitizer remains the only output projection.
 
+Scrollback and unread send output retain independently owned strings with incremental byte and newline counts, so sanitized slices cannot retain discarded control sequences. Appending and evicting text takes amortized time proportional to incoming text; reads assemble the retained chunks. Retention preserves code-point boundaries and counts the empty line after a trailing newline. The [retention decision](../../../.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.md) owns the complexity and measurement rationale.
+
 ### Source map
 
 | File | Role |
diff --git a/packages/terminal/terminal-bash/README.zh.md b/packages/terminal/terminal-bash/README.zh.md
index 256a68e0b6..7ca41883f6 100644
--- a/packages/terminal/terminal-bash/README.zh.md
+++ b/packages/terminal/terminal-bash/README.zh.md
@@ -85,6 +85,8 @@ shell 在整个生命周期内运行在有效的沙箱边界之下。当所有
 
 一个后端服务两种方言：bash 与 pwsh 共享同一套会话机制——清理器、有界缓冲区、就绪轮询、取消与关闭——只在 argv、环境与提示符安装方式上不同。bash 通过 `PS1` 加 `PROMPT_COMMAND` 接收私有标记。pwsh 会写入提示符函数、固定 UTF-8 控制台编码，并只在后端报告 `stdin_read` 后发布启动；回显的设置文本不能发布 shell。一个不保留 scrollback 的 `@xterm/headless` 实例会消费原始 PTY 数据，并通过同一句柄返回终端协议响应；逐行 sanitizer 仍是唯一输出投影。
 
+Scrollback 和尚未读取的发送输出保留独立拥有的字符串，并增量维护字节数与换行符数，因此清理后的切片不会保留已丢弃的控制序列。追加与淘汰文本的摊还耗时与输入文本量成正比；读取时才拼接保留的分片。保留策略维持码点边界，并将末尾换行符之后的空行计入行数。[保留策略决策](../../../.agents/notes/implemented/bug-fix/2026-09-11-incremental-terminal-retention.zh.md)记录复杂度与测量依据。
+
 ### 源码地图
 
 | 文件 | 职责 |
diff --git a/packages/terminal/terminal-bash/src/session.ts b/packages/terminal/terminal-bash/src/session.ts
index d40db28c10..7b43087855 100644
--- a/packages/terminal/terminal-bash/src/session.ts
+++ b/packages/terminal/terminal-bash/src/session.ts
@@ -42,8 +42,22 @@ function utf8Tail(text: string, maxBytes: number): { text: string; truncated: bo
   return { text: chars.slice(start).join(''), truncated: true }
 }
 
+// Bound pending string fragments independently of deployment retention limits.
+const COALESCED_CHUNK_UNITS = 4096
+
+interface TextChunk {
+  text: string
+  start: number
+  next: TextChunk | undefined
+}
+
+/** Retention work is amortized over appended text; reads assemble the retained chunks. */
 class BoundedTextBuffer {
-  private value = ''
+  private head: TextChunk | undefined
+  private tail: TextChunk | undefined
+  private bytes = 0
+  private newlines = 0
+  private lastCodeUnit = 0
   private dropped = false
 
   constructor(
@@ -51,31 +65,94 @@ class BoundedTextBuffer {
     private readonly maxLines?: number,
   ) {}
 
+  get truncated(): boolean {
+    return this.dropped
+  }
+
+  get isEmpty(): boolean {
+    return this.head === undefined
+  }
+
   append(text: string): void {
     if (text.length === 0) return
-    this.value += text
-    if (this.maxLines !== undefined) {
-      const lines = this.value.split('\n')
-      if (lines.length > this.maxLines) {
-        this.value = lines.slice(lines.length - this.maxLines).join('\n')
-        this.dropped = true
-      }
+    // Sanitized text can be a slice retaining discarded controls; copy UTF-16 without replacing lone surrogates.
+    text = Buffer.from(text, 'utf16le').toString('utf16le')
+    this.bytes += Buffer.byteLength(text)
+    const tail = this.tail
+    if (tail !== undefined) {
+      const last = this.lastCodeUnit
+      const first = text.charCodeAt(0)
+      // Concatenation can turn two three-byte lone surrogates into one four-byte code point.
+      if (last >= 0xd800 && last <= 0xdbff && first >= 0xdc00 && first <= 0xdfff) this.bytes -= 2
     }
-    const tail = utf8Tail(this.value, this.maxBytes)
-    this.value = tail.text
-    this.dropped ||= tail.truncated
+    for (let index = text.indexOf('\n'); index !== -1; index = text.indexOf('\n', index + 1)) {
+      this.newlines += 1
+    }
+    this.lastCodeUnit = text.charCodeAt(text.length - 1)
+    // The head never grows, so eviction never rescans a growing string.
+    if (tail !== undefined && tail !== this.head && tail.text.length + text.length <= COALESCED_CHUNK_UNITS) {
+      tail.text += text
+    } else {
+      if (tail !== undefined && tail.text.length <= COALESCED_CHUNK_UNITS) {
+        // Copy coalesced fragments into one string; large tails already own their storage.
+        tail.text = Buffer.from(tail.text, 'utf16le').toString('utf16le')
+      }
+      const chunk: TextChunk = { text, start: 0, next: undefined }
+      if (tail === undefined) this.head = chunk
+      else tail.next = chunk
+      this.tail = chunk
+    }
+
+    while (this.head !== undefined
+      && (this.bytes > this.maxBytes || (this.maxLines !== undefined && this.newlines >= this.maxLines))) {
+      const head = this.head
+      const first = head.text.charCodeAt(head.start)
+      const second = head.start + 1 < head.text.length
+        ? head.text.charCodeAt(head.start + 1)
+        : head.next?.text.charCodeAt(0)
+      const paired = first >= 0xd800 && first <= 0xdbff
+        && second !== undefined && second >= 0xdc00 && second <= 0xdfff
+      this.bytes -= paired ? 4 : first < 0x80 ? 1 : first < 0x800 ? 2 : 3
+      if (first === 10) this.newlines -= 1
+      this.advance(paired ? 2 : 1)
+      this.dropped = true
+    }
+    const head = this.head
+    if (head !== undefined && head.start >= head.text.length / 2) {
+      // Copy UTF-16 verbatim so a small suffix cannot retain an oversized input's backing store.
+      // Copying only after discarding at least half keeps this work amortized over discarded text.
+      head.text = Buffer.from(head.text.slice(head.start), 'utf16le').toString('utf16le')
+      head.start = 0
+    }
+  }
+
+  private advance(units: number): void {
+    while (units > 0 && this.head !== undefined) {
+      const head = this.head
+      const count = Math.min(units, head.text.length - head.start)
+      head.start += count
+      units -= count
+      if (head.start === head.text.length) this.head = head.next
+    }
+    if (this.head === undefined) this.tail = undefined
   }
 
   consume(): TerminalSendRead {
-    const delta = this.value
-    const truncated = this.dropped
-    this.value = ''
+    const { text: delta, truncated } = this.snapshot()
+    this.head = undefined
+    this.tail = undefined
+    this.bytes = 0
+    this.newlines = 0
     this.dropped = false
     return { delta, truncated }
   }
 
   snapshot(): { text: string; truncated: boolean } {
-    return { text: this.value, truncated: this.dropped }
+    const chunks: string[] = []
+    for (let chunk = this.head; chunk !== undefined; chunk = chunk.next) {
+      chunks.push(chunk.text.slice(chunk.start))
+    }
+    return { text: chunks.join(''), truncated: this.dropped }
   }
 }
 
@@ -495,7 +572,7 @@ export class LocalPtySession implements TerminalBackendSession {
         return
       }
       const elapsed = Date.now() - operation.startedAt
-      const startupHasOutput = !this.initializing || this.scrollback.snapshot().text.length > 0
+      const startupHasOutput = !this.initializing || !this.scrollback.isEmpty
       const acceptsStdinWait = startupHasOutput && foreground !== undefined
         && operation.acceptsStdinWait(foreground.processGroupId, foreground.inputWaiting)
       if (elapsed >= this.config.exactProbeAfterMs && acceptsStdinWait) {
@@ -620,7 +697,7 @@ export class LocalPtySession implements TerminalBackendSession {
   private settleActive(waitReason: TerminalWaitReason, retainOwnership = false): void {
     const operation = this.active
     if (operation === undefined) return
-    const scrollbackTruncated = this.scrollback.snapshot().truncated
+    const scrollbackTruncated = this.scrollback.truncated
     if (retainOwnership) {
       this.stopPolling()
       this.activeAbort?.()
diff --git a/packages/terminal/terminal-bash/tests/session-buffer.spec.ts b/packages/terminal/terminal-bash/tests/session-buffer.spec.ts
new file mode 100644
index 0000000000..bf27615069
--- /dev/null
+++ b/packages/terminal/terminal-bash/tests/session-buffer.spec.ts
@@ -0,0 +1,295 @@
+import { Buffer } from 'node:buffer'
+import { PassThrough } from 'node:stream'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { SubprocessOutcome, SubprocessTerminalHandle } from '@deepseek-ai/dsh-subprocess'
+import type { TerminalReadRequest } from '@deepseek-ai/dsh-terminal'
+import type { ResolvedConfig } from '../src/config.ts'
+import { LocalPtySession } from '../src/session.ts'
+
+class OutputProducer implements SubprocessTerminalHandle {
+  readonly pid = 123
+  readonly output = new PassThrough()
+  private readonly outcome = Promise.withResolvers<SubprocessOutcome>()
+  readonly done = this.outcome.promise
+
+  emit(text: string | Uint8Array): void {
+    this.output.write(typeof text === 'string' ? Buffer.from(text) : text)
+  }
+
+  exit(): void {
+    this.output.end()
+    this.outcome.resolve({ exitCode: 0, signal: null })
+  }
+
+  async write(): Promise<void> {}
+  async resize(): Promise<void> {}
+  async inspectForeground() { return undefined }
+  async signalForeground(): Promise<number> { return this.pid }
+  async terminate(): Promise<void> {
+    this.exit()
+    await this.done
+  }
+}
+
+const sessions: LocalPtySession[] = []
+
+afterEach(async () => {
+  await Promise.all(sessions.splice(0).map(session => session.close('buffer test cleanup')))
+})
+
+function fixture(overrides: Partial<ResolvedConfig> = {}) {
+  const config: ResolvedConfig = {
+    backendType: 'shell', shellDialect: 'bash', shellPath: '/bin/bash', shellArgs: [], rows: 24, cols: 80,
+    scrollbackLines: 10_000, scrollbackMaxBytes: 4 * 1024 * 1024, maxReadBytes: 256 * 1024,
+    pollIntervalMs: 60_000, exactProbeAfterMs: 60_000, idleSilenceMs: 60_000,
+    handoffGraceMs: 60_000, timeoutMs: 60_000, disposeGraceMs: 60_000,
+    ...overrides,
+  }
+  const producer = new OutputProducer()
+  const session = new LocalPtySession(producer, config)
+  sessions.push(session)
+  return { producer, session }
+}
+
+// The reference deliberately retains the eager line-first, then UTF-8-tail algorithm.
+function referenceTail(text: string, maxBytes: number) {
+  if (Buffer.byteLength(text) <= maxBytes) return { text, truncated: false }
+  const chars = Array.from(text)
+  let bytes = 0
+  let start = chars.length
+  while (start > 0) {
+    const size = Buffer.byteLength(chars[start - 1] as string)
+    if (bytes + size > maxBytes) break
+    bytes += size
+    start -= 1
+  }
+  return { text: chars.slice(start).join(''), truncated: true }
+}
+
+class ReferenceBuffer {
+  private text = ''
+  private truncated = false
+
+  constructor(private readonly maxBytes: number, private readonly maxLines?: number) {}
+
+  append(chunk: string): void {
+    if (chunk.length === 0) return
+    this.text += chunk
+    if (this.maxLines !== undefined) {
+      const lines = this.text.split('\n')
+      if (lines.length > this.maxLines) {
+        this.text = lines.slice(-this.maxLines).join('\n')
+        this.truncated = true
+      }
+    }
+    const bounded = referenceTail(this.text, this.maxBytes)
+    this.text = bounded.text
+    this.truncated ||= bounded.truncated
+  }
+
+  snapshot() { return { text: this.text, truncated: this.truncated } }
+
+  consume() {
+    const result = { delta: this.text, truncated: this.truncated }
+    this.text = ''
+    this.truncated = false
+    return result
+  }
+}
+
+function referenceRead(buffer: ReferenceBuffer, maxBytes: number, request: TerminalReadRequest = {}) {
+  const snapshot = buffer.snapshot()
+  const lines = snapshot.text.split('\n')
+  const totalLines = snapshot.text.length === 0 ? 0 : lines.length
+  const offset = request.offset ?? 0
+  if (offset >= totalLines) {
+    return { text: '', totalLines, lineBegin: offset, lineEnd: offset, truncated: snapshot.truncated }
+  }
+  const end = totalLines - offset
+  const bounded = referenceTail(lines.slice(Math.max(0, end - (request.count ?? 500)), end).join('\n'), maxBytes)
+  const returnedLines = bounded.text.length === 0 ? 0 : bounded.text.split('\n').length
+  return {
+    text: bounded.text, totalLines, lineBegin: offset, lineEnd: offset + returnedLines,
+    truncated: snapshot.truncated || bounded.truncated,
+  }
+}
+
+function deterministicChunks(alphabet: readonly string[], count: number): string[] {
+  let state = 0x12345678
+  return Array.from({ length: count }, () => {
+    state = (Math.imul(state, 1664525) + 1013904223) >>> 0
+    return alphabet[state % alphabet.length] as string
+  })
+}
+
+describe('LocalPtySession incremental output compatibility', () => {
+  it('retains the exact tail across the default 4 MiB scrollback limit while consuming active output', async () => {
+    const limit = 4 * 1024 * 1024
+    const { producer, session } = fixture({ maxReadBytes: limit })
+    const operation = session.startSend({ text: '', submit: false })
+    const chunk = 'a'.repeat(4096)
+    for (let index = 0; index < limit / chunk.length; index += 1) producer.emit(chunk)
+    expect(session.read({})).toEqual({
+      text: 'a'.repeat(limit), totalLines: 1, lineBegin: 0, lineEnd: 1, truncated: false,
+    })
+
+    producer.emit('界😀TAIL')
+    const retained = `${'a'.repeat(limit - 11)}界😀TAIL`
+    expect(session.read({})).toEqual({
+      text: retained, totalLines: 1, lineBegin: 0, lineEnd: 1, truncated: true,
+    })
+    expect(operation.readOutput()).toEqual({ delta: retained, truncated: true })
+    expect(operation.readOutput()).toEqual({ delta: '', truncated: false })
+    producer.emit('é')
+    expect(operation.readOutput()).toEqual({ delta: 'é', truncated: false })
+    producer.emit('done')
+    producer.exit()
+    await expect(operation.done).resolves.toEqual({
+      viewport: 'done', waitReason: 'session_exit',
+      sessionStatus: { kind: 'exited', exitCode: 0, signal: null }, truncated: true,
+    })
+    expect(operation.readOutput()).toEqual({ delta: 'done', truncated: false })
+    expect(operation.readOutput()).toEqual({ delta: '', truncated: false })
+  })
+
+  it('counts trailing empty lines and keeps scrollback truncation sticky after empty reads', () => {
+    const { producer, session } = fixture({ scrollbackLines: 3, scrollbackMaxBytes: 64, maxReadBytes: 64 })
+    producer.emit('a\nb\n')
+    expect(session.read({})).toEqual({ text: 'a\nb\n', totalLines: 3, lineBegin: 0, lineEnd: 3, truncated: false })
+    producer.emit('\n')
+    expect(session.read({})).toEqual({ text: 'b\n\n', totalLines: 3, lineBegin: 0, lineEnd: 3, truncated: true })
+    expect(session.read({ count: 1 })).toEqual({ text: '', totalLines: 3, lineBegin: 0, lineEnd: 0, truncated: true })
+    expect(session.read({ offset: 2, count: 1 }).text).toBe('b')
+    expect(session.read({ offset: 3 }).truncated).toBe(true)
+    producer.emit('')
+    producer.emit('c')
+    expect(session.read({}).text).toBe('b\n\nc')
+    expect(session.read({}).truncated).toBe(true)
+  })
+
+  it('decodes split UTF-8 before byte eviction and bounds an oversized multibyte chunk', async () => {
+    const { producer, session } = fixture({ scrollbackMaxBytes: 11, maxReadBytes: 11 })
+    const operation = session.startSend({ text: '', submit: false })
+    producer.emit('abc')
+    const encoded = Buffer.from('界😀éz')
+    producer.emit(encoded.subarray(0, 5))
+    producer.emit(encoded.subarray(5, 7))
+    producer.emit(encoded.subarray(7))
+    expect(session.read({}).text).toBe('c界😀éz')
+    expect(operation.readOutput()).toEqual({ delta: 'c界😀éz', truncated: true })
+    producer.emit('界😀'.repeat(1000) + 'éEND')
+    expect(session.read({}).text).toBe('😀éEND')
+    expect(operation.readOutput()).toEqual({ delta: '😀éEND', truncated: true })
+    expect(operation.readOutput()).toEqual({ delta: '', truncated: false })
+    producer.emit('ok')
+    producer.exit()
+    expect((await operation.done).viewport).toBe('ok')
+  })
+
+  it('resets operation truncation independently of retained scrollback', async () => {
+    const { producer, session } = fixture({ scrollbackMaxBytes: 128, maxReadBytes: 5 })
+    const operation = session.startSend({ text: '', submit: false })
+    for (let index = 0; index < 4; index += 1) {
+      producer.emit('123456')
+      expect(operation.readOutput()).toEqual({ delta: '23456', truncated: true })
+      expect(operation.readOutput()).toEqual({ delta: '', truncated: false })
+      producer.emit('é')
+      expect(operation.readOutput()).toEqual({ delta: 'é', truncated: false })
+    }
+    producer.exit()
+    expect(await operation.done).toMatchObject({ viewport: '', truncated: false, waitReason: 'session_exit' })
+    expect(operation.readOutput()).toEqual({ delta: '', truncated: false })
+  })
+
+  it.each([[1, 1, 1], [17, 7, 3], [64, 13, 5]])(
+    'matches eager reads and active output with byte caps %i/%i and %i lines',
+    async (scrollbackMaxBytes, maxReadBytes, scrollbackLines) => {
+      const { producer, session } = fixture({ scrollbackMaxBytes, maxReadBytes, scrollbackLines })
+      const scrollback = new ReferenceBuffer(scrollbackMaxBytes, scrollbackLines)
+      const output = new ReferenceBuffer(maxReadBytes)
+      const operation = session.startSend({ text: '', submit: false })
+      const chunks = deterministicChunks(['a', 'bc', '\n', '\n\n', '界', '😀', 'éz', '', 'long line\nend\n'], 120)
+      for (const [index, chunk] of chunks.entries()) {
+        producer.emit(chunk)
+        scrollback.append(chunk)
+        output.append(chunk)
+        for (const request of [{}, { offset: 1, count: 2 }, { offset: 9, count: 1 }]) {
+          expect(session.read(request)).toEqual(referenceRead(scrollback, maxReadBytes, request))
+        }
+        if (index % 7 === 0) expect(operation.readOutput()).toEqual(output.consume())
+      }
+      producer.exit()
+      const expected = output.snapshot()
+      expect(await operation.done).toMatchObject({
+        viewport: expected.text, truncated: expected.truncated || scrollback.snapshot().truncated,
+        waitReason: 'session_exit',
+      })
+      expect(operation.readOutput()).toEqual(output.consume())
+      expect(operation.readOutput()).toEqual(output.consume())
+    },
+  )
+
+  it('retains tiny producer chunks through multiple coalesced-node rollovers', async () => {
+    const limit = 5000
+    const { producer, session } = fixture({ scrollbackMaxBytes: limit, maxReadBytes: limit })
+    const operation = session.startSend({ text: '', submit: false })
+    const text = '0123456789'.repeat(1000)
+    const checkpoints = new Set([1, 4096, 4097, 5000, 5001, 8193, text.length])
+    for (let index = 0; index < text.length; index += 1) {
+      producer.emit(text[index] as string)
+      if (checkpoints.has(index + 1)) {
+        expect(session.read({})).toEqual({
+          text: text.slice(Math.max(0, index + 1 - limit), index + 1),
+          totalLines: 1, lineBegin: 0, lineEnd: 1, truncated: index + 1 > limit,
+        })
+      }
+    }
+    expect(operation.readOutput()).toEqual({ delta: text.slice(-limit), truncated: true })
+    expect(operation.readOutput()).toEqual({ delta: '', truncated: false })
+    producer.emit('fresh')
+    producer.exit()
+    expect(await operation.done).toMatchObject({ viewport: 'fresh', truncated: true, waitReason: 'session_exit' })
+  })
+
+  it('preserves split surrogate pairs when copied coalesced text reaches the eviction head', () => {
+    const limit = 4100
+    const { session } = fixture({ scrollbackMaxBytes: limit, maxReadBytes: limit })
+    // Lone UTF-16 halves cannot pass through the session's TextDecoder unchanged.
+    const buffer = session['scrollback']
+    const reference = new ReferenceBuffer(limit, 10_000)
+    const chunks = ['H', 'a'.repeat(4095), '\ud83d', '\ude00', 'xy', 'b'.repeat(4094), 'z', '\ud800', '\udfff']
+    for (const chunk of chunks) {
+      buffer.append(chunk)
+      reference.append(chunk)
+      expect(buffer.snapshot()).toEqual(reference.snapshot())
+    }
+    expect(buffer.snapshot()).toEqual({ text: `y${'b'.repeat(4094)}z\ud800\udfff`, truncated: true })
+    expect(buffer.consume()).toEqual(reference.consume())
+    expect(buffer.consume()).toEqual(reference.consume())
+  })
+
+  it.each([1, 2, 3, 4, 5, 8, 17])('preserves lone and split surrogates with a %i-byte limit', (maxBytes) => {
+    const { session } = fixture({ scrollbackMaxBytes: maxBytes, maxReadBytes: maxBytes, scrollbackLines: 3 })
+    // TextDecoder replaces lone surrogates; only these UTF-16 cases use the private buffer.
+    const buffer = session['scrollback']
+    const reference = new ReferenceBuffer(maxBytes, 3)
+    const chunks = [
+      '\ud83d', '\ude00', 'x', '\ud83d', '', '\ude00', '\n', '\ud800', 'abc', '\udfff',
+      'prefix'.repeat(20) + '\ud800', '\udfff', '\n\n\n',
+      ...deterministicChunks(['a', '\ud800', '\udfff', '\ud83d\ude00', '\n', 'é', '界', '', '\n\n'], 150),
+    ]
+    for (const [index, chunk] of chunks.entries()) {
+      buffer.append(chunk)
+      reference.append(chunk)
+      expect(buffer.snapshot()).toEqual(reference.snapshot())
+      if (index % 19 === 18) {
+        expect(buffer.consume()).toEqual(reference.consume())
+        expect(buffer.consume()).toEqual(reference.consume())
+      }
+    }
+    expect(buffer.consume()).toEqual(reference.consume())
+    buffer.append('x')
+    reference.append('x')
+    expect(buffer.snapshot()).toEqual(reference.snapshot())
+  })
+})
diff --git a/packages/terminal/terminal-bash/tests/session.spec.ts b/packages/terminal/terminal-bash/tests/session.spec.ts
index d8051db3b6..7bb43a46fe 100644
--- a/packages/terminal/terminal-bash/tests/session.spec.ts
+++ b/packages/terminal/terminal-bash/tests/session.spec.ts
@@ -155,6 +155,27 @@ async function initialize(session: LocalPtySession, terminal: FakeTerminal): Pro
 }
 
 describe('LocalPtySession readiness and output', () => {
+  it('polls startup and settles sends without assembling scrollback for status checks', async () => {
+    vi.useFakeTimers()
+    const terminal = new FakeTerminal()
+    const session = new LocalPtySession(terminal, config())
+    const snapshot = vi.spyOn(session['scrollback'], 'snapshot')
+    try {
+      const pending = session.initialize()
+      await vi.advanceTimersByTimeAsync(20)
+      expect(snapshot).not.toHaveBeenCalled()
+      terminal.emitData('x'.repeat(200) + '\x1b]133;D;0\x07dsh> ')
+      await vi.advanceTimersByTimeAsync(20)
+      await pending
+      expect(snapshot).not.toHaveBeenCalled()
+      expect(session.read({})).toMatchObject({ text: 'x'.repeat(59) + 'dsh> ', truncated: true })
+      expect(snapshot).toHaveBeenCalledTimes(1)
+    } finally {
+      snapshot.mockRestore()
+      await session.close('status check cleanup')
+    }
+  })
+
   it('answers split cursor-position queries before publishing prompt readiness', async () => {
     vi.useFakeTimers()
     const terminal = new FakeTerminal()
diff --git a/packages/test-support/loader-smoke/README.i18n.yaml b/packages/test-support/loader-smoke/README.i18n.yaml
index c8e0cfb370..82590e7575 100644
--- a/packages/test-support/loader-smoke/README.i18n.yaml
+++ b/packages/test-support/loader-smoke/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 packages/test-support/loader-smoke/README.md
-README.md: 4365cc16beadc517390dd4ce8616cdfb6ec9e7be
-README.zh.md: 3d9659acf7b845bab11be3a5f6c0ff37e15b8988
+README.md: 2b903a1a4ecd558b8839dba082b9c3ee0b9fdaa4
+README.zh.md: a207804e158745adcc5b2a41fa0892b60ad33d84
diff --git a/packages/test-support/loader-smoke/README.md b/packages/test-support/loader-smoke/README.md
index 4365cc16be..2b903a1a4e 100644
--- a/packages/test-support/loader-smoke/README.md
+++ b/packages/test-support/loader-smoke/README.md
@@ -45,7 +45,7 @@ Set `expectedExitCode` when the scenario pins a designed failure surface — a o
 
 ### Testing a shipped profile
 
-Profile integration drivers use the repository-only `tests/fixtures/production-profile.ts` helper. It loads the named shipped profile and its bundle patches through `loadProfile`, reconciles the profile's module fallback, and passes the bundle patches followed by the test's `*.patch.yml` files to the root `cordis:include` mounted by `boot`. Those patches should contain only the test provider or model, isolated persistence paths, and subject-specific changes. Package-level unit tests that need an agent loop without profile integration mount `dsh-agent-loop-testkit` locally instead.
+Profile integration drivers use the repository-only `tests/fixtures/production-profile.ts` helper. It loads the named shipped profile and its bundle patches through `loadProfile`, materializes the retained link-mode fallback, mounts `PluginPackages` with native lookup as the link-mode launcher does, and passes the bundle patches followed by the test's `*.patch.yml` files to the root `cordis:include` mounted by `boot`. Those patches should contain only the test provider or model, isolated persistence paths, and subject-specific changes. Package-level unit tests that need an agent loop without profile integration mount `dsh-agent-loop-testkit` locally instead.
 
 ### Driving a fixture turn
 
diff --git a/packages/test-support/loader-smoke/README.zh.md b/packages/test-support/loader-smoke/README.zh.md
index 3d9659acf7..a207804e15 100644
--- a/packages/test-support/loader-smoke/README.zh.md
+++ b/packages/test-support/loader-smoke/README.zh.md
@@ -45,7 +45,7 @@ const result = await runLoaderSmoke({
 
 ### 测试交付 profile
 
-Profile 集成 driver 使用仅限仓库内部的 `tests/fixtures/production-profile.ts` helper。它通过 `loadProfile` 加载指定的已交付 profile 及其组合包 patch，协调处理 profile 的模块回退，然后把组合包 patch 与测试 `*.patch.yml` 文件依次交给 `boot` 挂载的根 `cordis:include`。这些 patch 应只包含测试提供方或模型、隔离持久化路径及被测对象专用变更。只需要 agent loop（智能体循环）而不测试 profile 集成的包级单元测试改为在本地挂载 `dsh-agent-loop-testkit`。
+Profile 集成 driver 使用仅限仓库内部的 `tests/fixtures/production-profile.ts` helper。它通过 `loadProfile` 加载指定的已交付 profile 及其组合包 patch，物化保留的 link-mode fallback，并像 link-mode launcher 一样挂载使用原生查询的 `PluginPackages`，然后把组合包 patch 与测试 `*.patch.yml` 文件依次交给 `boot` 挂载的根 `cordis:include`。这些 patch 应只包含测试提供方或模型、隔离持久化路径及被测对象专用变更。只需要 agent loop 而不测试 profile 集成的包级单元测试改为在本地挂载 `dsh-agent-loop-testkit`。
 
 ### 驱动 fixture 轮次
 
diff --git a/packages/test-support/loader-smoke/tests/fixtures/production-profile.ts b/packages/test-support/loader-smoke/tests/fixtures/production-profile.ts
index 7db8b1fcc6..dabe5bd735 100644
--- a/packages/test-support/loader-smoke/tests/fixtures/production-profile.ts
+++ b/packages/test-support/loader-smoke/tests/fixtures/production-profile.ts
@@ -12,6 +12,7 @@ import {
   healProfilesModuleFallback,
   loadOverlayPatches,
   loadProfile,
+  PluginPackages,
   type ProfileLayer,
 } from '@deepseek-ai/dsh-app-boot'
 
@@ -96,6 +97,9 @@ export async function bootProductionProfile(options: ProductionProfileOptions):
       ...profile.layers.flatMap(layer => layer.patches),
       ...overlays.flat(),
     ],
-    options.prepare,
+    async (ctx) => {
+      await ctx.plugin(PluginPackages, {})
+      await options.prepare?.(ctx)
+    },
   )
 }
diff --git a/packages/test-support/session-snapshot/src/launcher.ts b/packages/test-support/session-snapshot/src/launcher.ts
index 821c4e3e6e..a99ecac2c0 100644
--- a/packages/test-support/session-snapshot/src/launcher.ts
+++ b/packages/test-support/session-snapshot/src/launcher.ts
@@ -358,7 +358,7 @@ function profileArgs(
   const materializedRoot = join(cwd, '.dsh-profile-patches')
   mkdirSync(materializedRoot, { recursive: true })
   const materializedDir = mkdtempSync(join(materializedRoot, 'launch-'))
-  const materialized = patches.map((file, index) => materializeProfilePatch(file, cwd, materializedDir, index))
+  const materialized = patches.map((file, index) => materializeProfilePatch(file, cwd, profile, materializedDir, index))
   return ['--profile', profile, ...materialized.flatMap(file => ['--patch', file])]
 }
 
@@ -386,14 +386,14 @@ function packageDirFromPatch(source: string, packageName: string): string | unde
 
 /**
  * Install an authored patch's resolvable bare package into the temporary
- * profile fallback. This mirrors `dsh plugin` while retaining the bare entry
+ * profile. This mirrors `dsh plugin` while retaining the bare entry
  * name and package identity used by request metadata.
  */
-function linkProfilePackage(source: string, cwd: string, packageName: string): void {
+function linkProfilePackage(source: string, cwd: string, profile: string, packageName: string): void {
   const packageDir = packageDirFromPatch(source, packageName)
   // The package may instead belong to the dsh installation; profile boot heals those links.
   if (packageDir === undefined) return
-  const link = join(cwd, '.dsh', 'profiles', 'node_modules', packageName)
+  const link = join(cwd, '.dsh', 'profiles', profile, 'node_modules', packageName)
   mkdirSync(dirname(link), { recursive: true })
   if (existsSync(link)) {
     if (realpathSync(link) !== packageDir) {
@@ -408,19 +408,22 @@ function linkProfilePackage(source: string, cwd: string, packageName: string): v
 /**
  * Copy one authored patch into the launch cwd with relative plugin names made absolute.
  * @param source - authored profile patch path.
- * @param cwd - isolated process cwd whose profile fallback receives package links.
+ * @param cwd - isolated process cwd whose profile receives package links.
+ * @param profile - profile whose local package lookup receives the test links.
  * @param targetDir - existing directory that owns the materialized patch.
  * @param index - stable patch ordinal used in the output filename.
  * @returns absolute materialized patch path.
  */
-export function materializeProfilePatch(source: string, cwd: string, targetDir: string, index: number): string {
+export function materializeProfilePatch(
+  source: string, cwd: string, profile: string, targetDir: string, index: number,
+): string {
   const parsed = yaml.load(readFileSync(source, 'utf8'), { schema: entryListSchema })
   if (!Array.isArray(parsed)) throw new Error(`snapshot profile patch must be a top-level array: ${source}`)
   const patches = parsed as PatchOptions[]
   const baseDir = dirname(source)
   const resolveName = (value: string): string => {
     const packageName = barePackageName(value)
-    if (packageName !== undefined) linkProfilePackage(source, cwd, packageName)
+    if (packageName !== undefined) linkProfilePackage(source, cwd, profile, packageName)
     return value.startsWith('./') || value.startsWith('../')
       ? pathToFileURL(resolve(baseDir, value)).href
       : value
diff --git a/packages/test-support/session-snapshot/tests/harness.spec.ts b/packages/test-support/session-snapshot/tests/harness.spec.ts
index 2fc5cd5438..ea23566825 100644
--- a/packages/test-support/session-snapshot/tests/harness.spec.ts
+++ b/packages/test-support/session-snapshot/tests/harness.spec.ts
@@ -233,9 +233,9 @@ describe('runScenario', () => {
     expect(materialized).toContain(pathToFileURL(join(patchDir, 'plugin.mjs')).href)
     expect(materialized).toContain(pathToFileURL(join(dir, 'nested.mjs')).href)
     expect(materialized).toContain('example-package')
-    expect(await realpath(join(dir, '.dsh', 'profiles', 'node_modules', 'example-package')))
+    expect(await realpath(join(dir, '.dsh', 'profiles', 'acp', 'node_modules', 'example-package')))
       .toBe(await realpath(packageDir))
-    expect(await realpath(join(dir, '.dsh', 'profiles', 'node_modules', '@fixture', 'example-package')))
+    expect(await realpath(join(dir, '.dsh', 'profiles', 'acp', 'node_modules', '@fixture', 'example-package')))
       .toBe(await realpath(scopedPackageDir))
     expect(await readFile(await materializedPatch(materializedRoot, '1-selected.cordis.yml'), 'utf8')).toContain('[]')
 
@@ -255,7 +255,7 @@ describe('runScenario', () => {
     const conflictPatch = join(dir, 'conflict.cordis.yml')
     const conflictPackage = join(dir, 'node_modules', 'conflict-package')
     const otherPackage = join(dir, 'other-conflict-package')
-    const conflictLink = join(dir, '.dsh', 'profiles', 'node_modules', 'conflict-package')
+    const conflictLink = join(dir, '.dsh', 'profiles', 'acp', 'node_modules', 'conflict-package')
     await Promise.all([
       mkdir(conflictPackage, { recursive: true }),
       mkdir(otherPackage, { recursive: true }),
diff --git a/packages/tsdown.worker.ts b/packages/tsdown.worker.ts
new file mode 100644
index 0000000000..c5d957b6b3
--- /dev/null
+++ b/packages/tsdown.worker.ts
@@ -0,0 +1,13 @@
+/** Fixed startup code for Node Worker bundles, after the executable's VFS bootstrap. */
+
+/**
+ * Load the parent's profile resolver before Worker business code executes.
+ * ESM static dependencies must resolve without the profile resolver.
+ * @param format - emitted Worker module format.
+ * @returns a tsdown banner that loads the shared native Worker bootstrap.
+ */
+export function profileWorkerBanner(format: 'cjs' | 'esm'): string {
+  return format === 'cjs'
+    ? '"use strict";\nrequire("@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap");'
+    : 'import "@deepseek-ai/dsh-app-boot/worker/profile-resolution-bootstrap";'
+}
diff --git a/packages/typert/loader/package.json b/packages/typert/loader/package.json
index d0873289e6..74cd3b8aaf 100644
--- a/packages/typert/loader/package.json
+++ b/packages/typert/loader/package.json
@@ -35,6 +35,7 @@
     "@deepseek-ai/schemastery": "workspace:^"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
     "@deepseek-ai/cordis-plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-typert-registry": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^",
diff --git a/packages/typert/loader/src/index.ts b/packages/typert/loader/src/index.ts
index ce5aa0d54f..5dfad5787b 100644
--- a/packages/typert/loader/src/index.ts
+++ b/packages/typert/loader/src/index.ts
@@ -32,6 +32,7 @@ import { pathToFileURL } from 'node:url'
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import type {} from '@deepseek-ai/cordis-plugin-loader'
+import type {} from '@deepseek-ai/dsh-app-boot'
 import type {} from '@deepseek-ai/dsh-typert-registry'
 import type { TypertContribution } from '@deepseek-ai/dsh-typert-registry/types'
 
@@ -56,6 +57,11 @@ export const Config: z<Config> = z.object({
 
 type ResolvedConfig = Required<Config>
 
+interface TypertArtifact {
+  packageName: string
+  path: string
+}
+
 const MEMBER_KINDS = new Set(['property', 'method', 'getter', 'setter', 'call', 'construct', 'index'])
 
 /** Resolve the `./typert` export to a relative path, accepting the string and one-level conditional forms. */
@@ -289,7 +295,8 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   if (ctx.baseUrl === undefined) {
     throw new Error('typert-loader: ctx.baseUrl is unset — the loader needs the config-tree anchor to resolve plugin packages')
   }
-  const require = createRequire(ctx.baseUrl)
+  const baseUrl = ctx.baseUrl
+  const require = createRequire(baseUrl)
   const configured = new Set((config as ResolvedConfig).packages)
 
   // Registered contributions by entry name; the disposer withdraws the entry's registration.
@@ -297,9 +304,9 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   // In-flight import/register tasks by entry name.
   const pending = new Map<string, Promise<void>>()
   // Artifact paths by package name. Negative verdicts (unresolvable specifier —
-  // loader builtins, subpath rows — or no typert export) are cached as null and
-  // never expire: plugin-set changes take effect on restart.
-  const artifactPath = new Map<string, string | null>()
+  // unconfigured loader builtins and subpath rows — or no typert export) are
+  // cached as null and never expire: plugin-set changes take effect on restart.
+  const artifactPath = new Map<string, TypertArtifact | null>()
   // Imported+validated manifests by package name (one import per package per process).
   const manifests = new Map<string, Promise<TypertContribution>>()
   const dirty = new Set<string>()
@@ -312,12 +319,29 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
     }
   }, 'typert loader lifetime')
 
-  const resolveArtifact = (pkgName: string): string | null => {
+  const resolveArtifact = (pkgName: string): TypertArtifact | null => {
     const cached = artifactPath.get(pkgName)
     if (cached !== undefined) return cached
+    const firstSlash = pkgName.indexOf('/')
+    if (firstSlash >= 0 && (pkgName[0] !== '@' || pkgName.indexOf('/', firstSlash + 1) >= 0)) {
+      if (configured.has(pkgName)) {
+        throw new Error(
+          `typert-loader: configured package "${pkgName}" cannot be resolved from the config tree — add it to the composition package dependencies or remove it from packages`,
+        )
+      }
+      artifactPath.set(pkgName, null)
+      return null
+    }
     let pkgPath: string
+    let pkg: Record<string, unknown> | undefined
     try {
-      pkgPath = require.resolve(`${pkgName}/package.json`)
+      const packages = ctx.get('pluginPackages')
+      const resolvedPackage = packages?.packageOf(pkgName, baseUrl)
+      if (packages !== undefined && resolvedPackage === undefined) throw new Error('package is absent from the active resolver')
+      pkgPath = resolvedPackage === undefined
+        ? require.resolve(`${pkgName}/package.json`)
+        : resolvedPackage.manifestPath
+      pkg = resolvedPackage?.manifest
     } catch (cause) {
       if (configured.has(pkgName)) {
         throw new Error(
@@ -330,12 +354,13 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
       artifactPath.set(pkgName, null)
       return null
     }
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>
-    const rel = typertExportOf(pkgName, pkg.exports)
+    pkg ??= JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>
+    const manifestName = typeof pkg.name === 'string' ? pkg.name : pkgName
+    const rel = typertExportOf(manifestName, pkg.exports)
     if (rel === undefined && configured.has(pkgName)) {
       throw new Error(`typert-loader: configured package "${pkgName}" does not export "${TYPERT_HOST_EXPORT}"`)
     }
-    const resolved = rel === undefined ? null : join(dirname(pkgPath), rel)
+    const resolved = rel === undefined ? null : { packageName: manifestName, path: join(dirname(pkgPath), rel) }
     artifactPath.set(pkgName, resolved)
     return resolved
   }
@@ -375,9 +400,9 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
       return undefined
     }
     if (registered.has(entryName) || pending.has(entryName)) return undefined
-    const path = resolveArtifact(entryName)
-    if (path === null) return undefined
-    const task = loadManifest(entryName, path).then((manifest) => {
+    const artifact = resolveArtifact(entryName)
+    if (artifact === null) return undefined
+    const task = loadManifest(artifact.packageName, artifact.path).then((manifest) => {
       // The entry may have unmounted (or already re-registered) while the import was in flight.
       if (!active || !qualifies(entryName) || registered.has(entryName)) return
       registered.set(entryName, ctx.typert.register(manifest))
diff --git a/packages/typert/loader/tests/loader.spec.ts b/packages/typert/loader/tests/loader.spec.ts
index 979b5b535b..09a626d341 100644
--- a/packages/typert/loader/tests/loader.spec.ts
+++ b/packages/typert/loader/tests/loader.spec.ts
@@ -6,6 +6,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
+import { PluginPackages } from '@deepseek-ai/dsh-app-boot'
 import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import * as typertLoader from '@deepseek-ai/dsh-typert-loader'
 import { validateTypertManifest } from '@deepseek-ai/dsh-typert-loader'
@@ -27,11 +28,13 @@ async function writePackage(
   base: string,
   pkgName: string,
   options: {
+    manifestName?: string
     typertExport?: boolean
     typertTarget?: unknown
     typertSource?: string
     pluginSource?: string
     omitExports?: boolean
+    pluginSubpath?: string
   } = {},
 ): Promise<void> {
   const dir = join(base, 'node_modules', ...pkgName.split('/'))
@@ -40,8 +43,9 @@ async function writePackage(
   if (options.typertExport !== false && options.typertSource !== undefined) {
     exportsField['./typert'] = options.typertTarget ?? './typert.host.js'
   }
+  if (options.pluginSubpath !== undefined) exportsField[options.pluginSubpath] = './index.js'
   await writeFile(join(dir, 'package.json'), JSON.stringify({
-    name: pkgName,
+    name: options.manifestName ?? pkgName,
     type: 'module',
     ...(options.omitExports ? { main: './index.js' } : { exports: exportsField }),
   }))
@@ -106,6 +110,7 @@ async function boot(): Promise<Context> {
       return module
     },
   } as unknown as NonNullable<typeof context.loader.internal>
+  await context.plugin(PluginPackages)
   // zod must be resolvable from the fixture packages; link the workspace copy.
   await mkdir(join(root as string, 'node_modules'), { recursive: true })
   return context
@@ -177,13 +182,16 @@ describe('typert loader', () => {
 
     let failure: unknown
     try {
-      await mountTypertLoader(ctx, { packages: ['@fixture/missing', '@fixture/plain'] })
+      await mountTypertLoader(ctx, {
+        packages: ['@fixture/missing', '@fixture/plain', '@fixture/subpath/plugin'],
+      })
     } catch (error) {
       failure = error
     }
     expect(failure).toBeInstanceOf(AggregateError)
     expect((failure as Error).message).toContain('configured package "@fixture/missing" cannot be resolved')
     expect((failure as Error).message).toContain('configured package "@fixture/plain" does not export "./typert"')
+    expect((failure as Error).message).toContain('configured package "@fixture/subpath/plugin" cannot be resolved')
   })
 
   it('auto-registers a mounted package exporting ./typert and withdraws it on unmount', LOADER_TEST_TIMEOUT, async () => {
@@ -227,6 +235,28 @@ describe('typert loader', () => {
     expect(ctx.typert.get('@fixture/with-typert#Thing')).toBeDefined()
   })
 
+  it('skips package-subpath rows and validates npm aliases against the manifest owner', LOADER_TEST_TIMEOUT, async () => {
+    root = await mkdtemp(join(tmpdir(), 'dsh-typert-loader-'))
+    await linkZod(root)
+    await writePackage(root, '@fixture/subpath', {
+      pluginSubpath: './plugin',
+      typertSource: typertSource('@fixture/subpath', 'Subpath'),
+    })
+    await writePackage(root, 'fixture-alias', {
+      manifestName: '@fixture/actual',
+      typertSource: typertSource('@fixture/actual', 'Aliased'),
+    })
+    const ctx = await boot()
+    await ctx.loader.create({ name: '@fixture/subpath/plugin' })
+    await ctx.loader.create({ name: 'fixture-alias' })
+    await ctx.loader.await()
+
+    await mountTypertLoader(ctx)
+
+    expect(ctx.typert.getPackage('@fixture/subpath')).toBeUndefined()
+    expect(ctx.typert.get('@fixture/actual#Aliased')).toBeDefined()
+  })
+
   it('follows entries mounted after activation', LOADER_TEST_TIMEOUT, async () => {
     root = await mkdtemp(join(tmpdir(), 'dsh-typert-loader-'))
     await linkZod(root)
diff --git a/packages/typert/loader/tsconfig.json b/packages/typert/loader/tsconfig.json
index 28dbbd9aa6..d179cb0e8d 100644
--- a/packages/typert/loader/tsconfig.json
+++ b/packages/typert/loader/tsconfig.json
@@ -8,6 +8,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../../boot/app-boot"
+    },
     {
       "path": "../../../vendor/cosmokit"
     },
diff --git a/patches/@yao-pkg__pkg@6.21.0.patch b/patches/@yao-pkg__pkg@6.21.0.patch
index 238a9296dd..9f0aa5919d 100644
--- a/patches/@yao-pkg__pkg@6.21.0.patch
+++ b/patches/@yao-pkg__pkg@6.21.0.patch
@@ -1,8 +1,82 @@
 diff --git a/prelude/sea-bootstrap.bundle.js b/prelude/sea-bootstrap.bundle.js
-index ac14980e953134f2285e326a5111cf52de717cf5..6b0c9d5b5063f447cb8aa3e0fc9d342729f29989 100644
+index ac14980e953134f2285e326a5111cf52de717cf5..19465f8004dcd7f75bc7459de2055546f232fd23 100644
 --- a/prelude/sea-bootstrap.bundle.js
 +++ b/prelude/sea-bootstrap.bundle.js
-@@ -5560,7 +5560,6 @@ var require_sea_bootstrap_core = __commonJS({
+@@ -5356,6 +5356,39 @@ var require_sea_vfs_setup = __commonJS({
+         }
+       };
+     }
++    var DIRENT_UNKNOWN = 0;
++    var DIRENT_FILE = 1;
++    var DIRENT_DIRECTORY = 2;
++    var DIRENT_SYMLINK = 3;
++    var SEADirent = class {
++      constructor(name, type, parentPath) {
++        this.name = name;
++        this.parentPath = parentPath;
++        this.path = parentPath;
++        this._type = type;
++      }
++      isFile() {
++        return this._type === DIRENT_FILE;
++      }
++      isDirectory() {
++        return this._type === DIRENT_DIRECTORY;
++      }
++      isSymbolicLink() {
++        return this._type === DIRENT_SYMLINK;
++      }
++      isBlockDevice() {
++        return false;
++      }
++      isCharacterDevice() {
++        return false;
++      }
++      isFIFO() {
++        return false;
++      }
++      isSocket() {
++        return false;
++      }
++    };
+     var SEAProvider = class extends MemoryProvider {
+       constructor(seaManifest) {
+         super();
+@@ -5465,12 +5498,21 @@ var require_sea_vfs_setup = __commonJS({
+         }
+         return -2;
+       }
+-      readdirSync(dirPath) {
++      readdirSync(dirPath, options) {
+         perf2.count("readdirSync calls");
+         var p = this._resolveSymlink(toManifestKey(dirPath));
+         var entries = this._manifest.directories[p];
+-        if (entries) return entries.slice();
+-        return super.readdirSync(p);
++        if (entries) {
++          if (!options || !options.withFileTypes) return entries.slice();
++          var manifest3 = this._manifest;
++          return entries.map(function(name) {
++            var childPath = p === "/" ? "/" + name : p + "/" + name;
++            var meta = manifest3.stats[childPath];
++            var type = manifest3.symlinks[childPath] !== void 0 ? DIRENT_SYMLINK : meta && meta.isDirectory ? DIRENT_DIRECTORY : meta && meta.isFile ? DIRENT_FILE : DIRENT_UNKNOWN;
++            return new SEADirent(name, type, p);
++          });
++        }
++        return super.readdirSync(p, options);
+       }
+       existsSync(filePath) {
+         perf2.count("existsSync calls");
+@@ -5542,7 +5584,7 @@ var require_sea_vfs_setup = __commonJS({
+ var require_worker_bootstrap_string = __commonJS({
+   "prelude/_worker-bootstrap-string.js"(exports2, module2) {
+     "use strict";
+-    module2.exports = '"use strict";\nvar __getOwnPropNames = Object.getOwnPropertyNames;\nvar __commonJS = (cb, mod) => function __require() {\n  try {\n    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;\n  } catch (e) {\n    throw mod = 0, e;\n  }\n};\n\n// prelude/bootstrap-shared.js\nvar require_bootstrap_shared = __commonJS({\n  "prelude/bootstrap-shared.js"(exports2, module2) {\n    "use strict";\n    var childProcess = require("child_process");\n    var { createHash } = require("crypto");\n    var fs = require("fs");\n    var path = require("path");\n    var zlib = require("zlib");\n    var { homedir } = require("os");\n    var COMPRESS_NONE = 0;\n    var COMPRESS_GZIP = 1;\n    var COMPRESS_BROTLI = 2;\n    var COMPRESS_ZSTD = 3;\n    function zstdMissingError(symbol) {\n      return new Error(\n        "pkg: Zstd compression requires Node.js >= 22.15 (runtime missing zlib." + symbol + "). Re-package this binary with pkg >= the version that embeds Node 22.15+, or contact the distributor for a --compress Brotli/GZip build."\n      );\n    }\n    function pickDecompressorSync(compression) {\n      switch (compression) {\n        case COMPRESS_NONE:\n          return null;\n        case COMPRESS_GZIP:\n          return zlib.gunzipSync;\n        case COMPRESS_BROTLI:\n          return zlib.brotliDecompressSync;\n        case COMPRESS_ZSTD:\n          if (typeof zlib.zstdDecompressSync !== "function") {\n            throw zstdMissingError("zstdDecompressSync");\n          }\n          return zlib.zstdDecompressSync;\n        default:\n          throw new Error(\n            "pkg: unknown compression codec id " + compression + " in manifest"\n          );\n      }\n    }\n    function pickDecompressorAsync(compression) {\n      switch (compression) {\n        case COMPRESS_NONE:\n          return null;\n        case COMPRESS_GZIP:\n          return zlib.gunzip;\n        case COMPRESS_BROTLI:\n          return zlib.brotliDecompress;\n        case COMPRESS_ZSTD:\n          if (typeof zlib.zstdDecompress !== "function") {\n            throw zstdMissingError("zstdDecompress");\n          }\n          return zlib.zstdDecompress;\n        default:\n          throw new Error("pkg: unknown compression codec id " + compression);\n      }\n    }\n    function cpRecursive(src, dest) {\n      var st = fs.lstatSync(src);\n      if (st.isSymbolicLink()) {\n        var target = fs.readlinkSync(src);\n        try {\n          fs.unlinkSync(dest);\n        } catch (_) {\n        }\n        try {\n          fs.symlinkSync(target, dest);\n          return;\n        } catch (e) {\n          if (e && (e.code === "EPERM" || e.code === "EACCES")) {\n            var resolved = path.isAbsolute(target) ? target : path.join(path.dirname(src), target);\n            cpRecursive(resolved, dest);\n            return;\n          }\n          throw e;\n        }\n      }\n      if (st.isDirectory()) {\n        fs.mkdirSync(dest, { recursive: true });\n        var entries = fs.readdirSync(src);\n        for (var i = 0; i < entries.length; i++) {\n          cpRecursive(path.join(src, entries[i]), path.join(dest, entries[i]));\n        }\n        return;\n      }\n      var srcContent = fs.readFileSync(src);\n      if (fs.existsSync(dest)) {\n        var destContent = fs.readFileSync(dest);\n        var srcHash = createHash("sha256").update(srcContent).digest("hex");\n        var destHash = createHash("sha256").update(destContent).digest("hex");\n        if (srcHash === destHash) {\n          return;\n        }\n      }\n      fs.writeFileSync(dest, srcContent);\n    }\n    function patchDlopen(insideSnapshot) {\n      var ancestor = process.dlopen;\n      var PKG_NATIVE_CACHE_BASE = process.env.PKG_NATIVE_CACHE_PATH || path.join(homedir(), ".cache");\n      function revertMakingLong(f) {\n        if (/^\\\\\\\\\\?\\\\/.test(f)) return f.slice(4);\n        return f;\n      }\n      process.dlopen = function dlopen() {\n        var args = Array.prototype.slice.call(arguments);\n        var modulePath = revertMakingLong(args[1]);\n        var moduleBaseName = path.basename(modulePath);\n        var moduleFolder = path.dirname(modulePath);\n        if (insideSnapshot(modulePath)) {\n          var moduleContent = fs.readFileSync(modulePath);\n          var hash = createHash("sha256").update(moduleContent).digest("hex");\n          var tmpFolder = path.join(PKG_NATIVE_CACHE_BASE, "pkg", hash);\n          fs.mkdirSync(tmpFolder, { recursive: true });\n          var parts = moduleFolder.split(path.sep);\n          var mIndex = parts.lastIndexOf("node_modules") + 1;\n          var newPath;\n          if (mIndex > 0) {\n            var modulePackagePath = parts.slice(mIndex).join(path.sep);\n            var modulePkgFolder = parts.slice(0, mIndex + 1).join(path.sep);\n            var destFolder = path.join(tmpFolder, path.basename(modulePkgFolder));\n            cpRecursive(modulePkgFolder, destFolder);\n            newPath = path.join(tmpFolder, modulePackagePath, moduleBaseName);\n          } else {\n            var tmpModulePath = path.join(tmpFolder, moduleBaseName);\n            if (fs.existsSync(tmpModulePath)) {\n              var dContent = fs.readFileSync(tmpModulePath);\n              var dHash = createHash("sha256").update(dContent).digest("hex");\n              if (hash !== dHash) {\n                fs.writeFileSync(tmpModulePath, moduleContent);\n              }\n            } else {\n              fs.writeFileSync(tmpModulePath, moduleContent);\n            }\n            newPath = tmpModulePath;\n          }\n          args[1] = newPath;\n        }\n        return ancestor.apply(process, args);\n      };\n    }\n    function patchChildProcess(entrypoint) {\n      var EXECPATH = process.execPath;\n      var ARGV0 = process.argv[0];\n      var ancestor = {\n        spawn: childProcess.spawn,\n        spawnSync: childProcess.spawnSync,\n        execFile: childProcess.execFile,\n        execFileSync: childProcess.execFileSync,\n        exec: childProcess.exec,\n        execSync: childProcess.execSync\n      };\n      function cloneArgs(args_) {\n        return Array.prototype.slice.call(args_);\n      }\n      function setOptsEnv(args) {\n        var pos = args.length - 1;\n        if (typeof args[pos] === "function") pos -= 1;\n        if (typeof args[pos] !== "object" || Array.isArray(args[pos])) {\n          pos += 1;\n          args.splice(pos, 0, {});\n        }\n        var opts = args[pos];\n        if (!opts.env) opts.env = Object.assign({}, process.env);\n        if (opts.env.PKG_EXECPATH !== void 0) return;\n        opts.env.PKG_EXECPATH = EXECPATH;\n      }\n      function startsWith2(args, index, name, impostor) {\n        var qsName = \'"\' + name + " ";\n        if (args[index].slice(0, qsName.length) === qsName) {\n          args[index] = \'"\' + impostor + " " + args[index].slice(qsName.length);\n          return true;\n        }\n        var sName = name + " ";\n        if (args[index].slice(0, sName.length) === sName) {\n          args[index] = impostor + " " + args[index].slice(sName.length);\n          return true;\n        }\n        if (args[index] === name) {\n          args[index] = impostor;\n          return true;\n        }\n        return false;\n      }\n      function startsWith(args, index, name) {\n        var qName = \'"\' + name + \'"\';\n        var qEXECPATH = \'"\' + EXECPATH + \'"\';\n        var jsName = JSON.stringify(name);\n        var jsEXECPATH = JSON.stringify(EXECPATH);\n        return startsWith2(args, index, name, EXECPATH) || startsWith2(args, index, qName, qEXECPATH) || startsWith2(args, index, jsName, jsEXECPATH);\n      }\n      function modifyLong(args, index) {\n        if (!args[index]) return;\n        return startsWith(args, index, "node") || startsWith(args, index, ARGV0) || startsWith(args, index, entrypoint) || startsWith(args, index, EXECPATH);\n      }\n      function modifyShort(args) {\n        if (!args[0]) return;\n        if (!Array.isArray(args[1])) {\n          args.splice(1, 0, []);\n        }\n        if (args[0] === "node" || args[0] === ARGV0 || args[0] === entrypoint || args[0] === EXECPATH) {\n          args[0] = EXECPATH;\n        } else {\n          for (var i = 1; i < args[1].length; i += 1) {\n            var mbc = args[1][i - 1];\n            if (mbc === "-c" || mbc === "/c") {\n              modifyLong(args[1], i);\n            }\n          }\n        }\n      }\n      childProcess.spawn = function spawn() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyShort(args);\n        return ancestor.spawn.apply(childProcess, args);\n      };\n      childProcess.spawnSync = function spawnSync() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyShort(args);\n        return ancestor.spawnSync.apply(childProcess, args);\n      };\n      childProcess.execFile = function execFile() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyShort(args);\n        return ancestor.execFile.apply(childProcess, args);\n      };\n      childProcess.execFileSync = function execFileSync() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyShort(args);\n        return ancestor.execFileSync.apply(childProcess, args);\n      };\n      childProcess.exec = function exec() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyLong(args, 0);\n        return ancestor.exec.apply(childProcess, args);\n      };\n      childProcess.execSync = function execSync() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyLong(args, 0);\n        return ancestor.execSync.apply(childProcess, args);\n      };\n    }\n    function setupProcessPkg(entrypoint, defaultEntrypoint) {\n      process.pkg = {\n        entrypoint,\n        defaultEntrypoint: defaultEntrypoint !== void 0 ? defaultEntrypoint : entrypoint,\n        path: {\n          resolve: function() {\n            var args = [path.dirname(entrypoint)];\n            for (var i = 0; i < arguments.length; i++) {\n              args.push(arguments[i]);\n            }\n            return path.resolve.apply(path, args);\n          }\n        }\n      };\n    }\n    function humanSize(bytes) {\n      var sizes = ["Bytes", "KB", "MB", "GB", "TB"];\n      if (bytes === 0) return "n/a";\n      var i = Math.floor(Math.log(bytes) / Math.log(1024));\n      if (i === 0) return bytes + " " + sizes[i];\n      return (bytes / Math.pow(1024, i)).toFixed(1) + " " + sizes[i];\n    }\n    function installDiagnostic(snapshotPrefix) {\n      if (!process.env.DEBUG_PKG) return;\n      var sizeLimit = process.env.SIZE_LIMIT_PKG ? parseInt(process.env.SIZE_LIMIT_PKG, 10) : 5 * 1024 * 1024;\n      var folderLimit = process.env.FOLDER_LIMIT_PKG ? parseInt(process.env.FOLDER_LIMIT_PKG, 10) : 10 * 1024 * 1024;\n      var overSized = [];\n      function dumpLevel(filename, level, tree2) {\n        var totalSize2 = 0;\n        var d = fs.readdirSync(filename);\n        for (var j = 0; j < d.length; j += 1) {\n          var f = path.join(filename, d[j]);\n          var realPath;\n          try {\n            realPath = fs.realpathSync(f);\n          } catch (_) {\n            realPath = f;\n          }\n          var isSymbolicLink = f !== realPath;\n          var s = fs.statSync(f);\n          if (s.isDirectory() && !isSymbolicLink) {\n            var tree1 = [];\n            var startIndex = overSized.length;\n            var folderSize = dumpLevel(f, level + 1, tree1);\n            totalSize2 += folderSize;\n            var str = (" ".padStart(level * 2, " ") + d[j]).padEnd(40, " ") + (humanSize(folderSize).padStart(10, " ") + (isSymbolicLink ? "=> " + realPath : " "));\n            tree2.push(str);\n            tree1.forEach(function(x) {\n              tree2.push(x);\n            });\n            if (folderSize > folderLimit) {\n              overSized.splice(startIndex, 0, str);\n            }\n          } else {\n            totalSize2 += s.size;\n            var str2 = (" ".padStart(level * 2, " ") + d[j]).padEnd(40, " ") + (humanSize(s.size).padStart(10, " ") + (isSymbolicLink ? "=> " + realPath : " "));\n            if (s.size > sizeLimit) {\n              overSized.push(str2);\n            }\n            tree2.push(str2);\n          }\n        }\n        return totalSize2;\n      }\n      function wrap(obj, name) {\n        var f = obj[name];\n        if (typeof f !== "function") return;\n        obj[name] = function() {\n          var args1 = Array.prototype.slice.call(arguments);\n          console.log(\n            "fs." + name,\n            args1.filter(function(x) {\n              return typeof x === "string";\n            })\n          );\n          return f.apply(this, args1);\n        };\n      }\n      console.log("------------------------------- virtual file system");\n      console.log(snapshotPrefix);\n      var tree = [];\n      var totalSize = dumpLevel(snapshotPrefix, 1, tree);\n      console.log(tree.join("\\n"));\n      console.log("Total size = ", humanSize(totalSize));\n      if (overSized.length > 0) {\n        console.log("------------------------------- oversized files");\n        console.log(overSized.join("\\n"));\n      }\n      if (process.env.DEBUG_PKG === "2") {\n        wrap(fs, "openSync");\n        wrap(fs, "open");\n        wrap(fs, "readSync");\n        wrap(fs, "read");\n        wrap(fs, "readFile");\n        wrap(fs, "writeSync");\n        wrap(fs, "write");\n        wrap(fs, "closeSync");\n        wrap(fs, "readFileSync");\n        wrap(fs, "close");\n        wrap(fs, "readdirSync");\n        wrap(fs, "readdir");\n        wrap(fs, "realpathSync");\n        wrap(fs, "realpath");\n        wrap(fs, "statSync");\n        wrap(fs, "stat");\n        wrap(fs, "lstatSync");\n        wrap(fs, "lstat");\n        wrap(fs, "fstatSync");\n        wrap(fs, "fstat");\n        wrap(fs, "existsSync");\n        wrap(fs, "exists");\n        wrap(fs, "accessSync");\n        wrap(fs, "access");\n        if (fs.promises) {\n          wrap(fs.promises, "open");\n          wrap(fs.promises, "read");\n          wrap(fs.promises, "readFile");\n          wrap(fs.promises, "write");\n          wrap(fs.promises, "readdir");\n          wrap(fs.promises, "realpath");\n          wrap(fs.promises, "stat");\n          wrap(fs.promises, "lstat");\n          wrap(fs.promises, "access");\n          wrap(fs.promises, "copyFile");\n        }\n      }\n    }\n    module2.exports = {\n      patchDlopen,\n      patchChildProcess,\n      setupProcessPkg,\n      installDiagnostic,\n      COMPRESS_NONE,\n      pickDecompressorSync,\n      pickDecompressorAsync\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/errors.js\nvar require_errors = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/errors.js"(exports2, module2) {\n    "use strict";\n    function createFsError(code, syscall, path, message) {\n      const msg = message || `${code}: ${getErrorDescription(code)}, ${syscall}${path ? ` \'${path}\'` : ""}`;\n      const err = new Error(msg);\n      err.code = code;\n      err.syscall = syscall;\n      if (path !== void 0) {\n        err.path = path;\n      }\n      Error.captureStackTrace(err, createFsError);\n      return err;\n    }\n    function getErrorDescription(code) {\n      switch (code) {\n        case "ENOENT":\n          return "no such file or directory";\n        case "ENOTDIR":\n          return "not a directory";\n        case "ENOTEMPTY":\n          return "directory not empty";\n        case "EISDIR":\n          return "illegal operation on a directory";\n        case "EBADF":\n          return "bad file descriptor";\n        case "EEXIST":\n          return "file already exists";\n        case "EROFS":\n          return "read-only file system";\n        case "EINVAL":\n          return "invalid argument";\n        case "ELOOP":\n          return "too many levels of symbolic links";\n        default:\n          return "unknown error";\n      }\n    }\n    function createENOENT(syscall, path) {\n      const err = createFsError("ENOENT", syscall, path);\n      Error.captureStackTrace(err, createENOENT);\n      return err;\n    }\n    function createENOTDIR(syscall, path) {\n      const err = createFsError("ENOTDIR", syscall, path);\n      Error.captureStackTrace(err, createENOTDIR);\n      return err;\n    }\n    function createENOTEMPTY(syscall, path) {\n      const err = createFsError("ENOTEMPTY", syscall, path);\n      Error.captureStackTrace(err, createENOTEMPTY);\n      return err;\n    }\n    function createEISDIR(syscall, path) {\n      const err = createFsError("EISDIR", syscall, path);\n      Error.captureStackTrace(err, createEISDIR);\n      return err;\n    }\n    function createEBADF(syscall) {\n      const err = createFsError("EBADF", syscall);\n      Error.captureStackTrace(err, createEBADF);\n      return err;\n    }\n    function createEEXIST(syscall, path) {\n      const err = createFsError("EEXIST", syscall, path);\n      Error.captureStackTrace(err, createEEXIST);\n      return err;\n    }\n    function createEROFS(syscall, path) {\n      const err = createFsError("EROFS", syscall, path);\n      Error.captureStackTrace(err, createEROFS);\n      return err;\n    }\n    function createEINVAL(syscall, path) {\n      const err = createFsError("EINVAL", syscall, path);\n      Error.captureStackTrace(err, createEINVAL);\n      return err;\n    }\n    function createELOOP(syscall, path) {\n      const err = createFsError("ELOOP", syscall, path);\n      Error.captureStackTrace(err, createELOOP);\n      return err;\n    }\n    var ERR_METHOD_NOT_IMPLEMENTED = class extends Error {\n      constructor(method) {\n        super(`The ${method} method is not implemented`);\n        this.code = "ERR_METHOD_NOT_IMPLEMENTED";\n      }\n    };\n    var ERR_INVALID_STATE = class extends Error {\n      constructor(message) {\n        super(`Invalid state: ${message}`);\n        this.code = "ERR_INVALID_STATE";\n      }\n    };\n    var ERR_INVALID_ARG_VALUE = class extends TypeError {\n      constructor(name, value, reason) {\n        super(`The argument \'${name}\' ${reason}. Received ${typeof value === "string" ? `\'${value}\'` : String(value)}`);\n        this.code = "ERR_INVALID_ARG_VALUE";\n      }\n    };\n    module2.exports = {\n      createENOENT,\n      createENOTDIR,\n      createENOTEMPTY,\n      createEISDIR,\n      createEBADF,\n      createEEXIST,\n      createEROFS,\n      createEINVAL,\n      createELOOP,\n      ERR_METHOD_NOT_IMPLEMENTED,\n      ERR_INVALID_STATE,\n      ERR_INVALID_ARG_VALUE\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/provider.js\nvar require_provider = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/provider.js"(exports2, module2) {\n    "use strict";\n    var {\n      ERR_METHOD_NOT_IMPLEMENTED,\n      createEROFS\n    } = require_errors();\n    var VirtualProvider = class {\n      get readonly() {\n        return false;\n      }\n      get supportsSymlinks() {\n        return false;\n      }\n      get supportsWatch() {\n        return false;\n      }\n      // === ESSENTIAL PRIMITIVES ===\n      async open(path, flags, mode) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("open");\n      }\n      openSync(path, flags, mode) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("openSync");\n      }\n      async stat(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("stat");\n      }\n      statSync(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("statSync");\n      }\n      async lstat(path, options) {\n        return this.stat(path, options);\n      }\n      lstatSync(path, options) {\n        return this.statSync(path, options);\n      }\n      async readdir(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readdir");\n      }\n      readdirSync(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readdirSync");\n      }\n      async mkdir(path, options) {\n        if (this.readonly) {\n          throw createEROFS("mkdir", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("mkdir");\n      }\n      mkdirSync(path, options) {\n        if (this.readonly) {\n          throw createEROFS("mkdir", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("mkdirSync");\n      }\n      async rmdir(path) {\n        if (this.readonly) {\n          throw createEROFS("rmdir", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("rmdir");\n      }\n      rmdirSync(path) {\n        if (this.readonly) {\n          throw createEROFS("rmdir", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("rmdirSync");\n      }\n      async unlink(path) {\n        if (this.readonly) {\n          throw createEROFS("unlink", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("unlink");\n      }\n      unlinkSync(path) {\n        if (this.readonly) {\n          throw createEROFS("unlink", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("unlinkSync");\n      }\n      async rename(oldPath, newPath) {\n        if (this.readonly) {\n          throw createEROFS("rename", oldPath);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("rename");\n      }\n      renameSync(oldPath, newPath) {\n        if (this.readonly) {\n          throw createEROFS("rename", oldPath);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("renameSync");\n      }\n      // === DEFAULT IMPLEMENTATIONS ===\n      async readFile(path, options) {\n        const handle = await this.open(path, "r");\n        try {\n          return await handle.readFile(options);\n        } finally {\n          await handle.close();\n        }\n      }\n      readFileSync(path, options) {\n        const handle = this.openSync(path, "r");\n        try {\n          return handle.readFileSync(options);\n        } finally {\n          handle.closeSync();\n        }\n      }\n      async writeFile(path, data, options) {\n        if (this.readonly) {\n          throw createEROFS("open", path);\n        }\n        const handle = await this.open(path, "w", options?.mode);\n        try {\n          await handle.writeFile(data, options);\n        } finally {\n          await handle.close();\n        }\n      }\n      writeFileSync(path, data, options) {\n        if (this.readonly) {\n          throw createEROFS("open", path);\n        }\n        const handle = this.openSync(path, "w", options?.mode);\n        try {\n          handle.writeFileSync(data, options);\n        } finally {\n          handle.closeSync();\n        }\n      }\n      async appendFile(path, data, options) {\n        if (this.readonly) {\n          throw createEROFS("open", path);\n        }\n        const handle = await this.open(path, "a", options?.mode);\n        try {\n          await handle.writeFile(data, options);\n        } finally {\n          await handle.close();\n        }\n      }\n      appendFileSync(path, data, options) {\n        if (this.readonly) {\n          throw createEROFS("open", path);\n        }\n        const handle = this.openSync(path, "a", options?.mode);\n        try {\n          handle.writeFileSync(data, options);\n        } finally {\n          handle.closeSync();\n        }\n      }\n      async exists(path) {\n        try {\n          await this.stat(path);\n          return true;\n        } catch {\n          return false;\n        }\n      }\n      existsSync(path) {\n        try {\n          this.statSync(path);\n          return true;\n        } catch {\n          return false;\n        }\n      }\n      async copyFile(src, dest, mode) {\n        if (this.readonly) {\n          throw createEROFS("copyfile", dest);\n        }\n        const content = await this.readFile(src);\n        await this.writeFile(dest, content);\n      }\n      copyFileSync(src, dest, mode) {\n        if (this.readonly) {\n          throw createEROFS("copyfile", dest);\n        }\n        const content = this.readFileSync(src);\n        this.writeFileSync(dest, content);\n      }\n      internalModuleStat(path) {\n        try {\n          const stats = this.statSync(path);\n          if (stats.isDirectory()) {\n            return 1;\n          }\n          return 0;\n        } catch {\n          return -2;\n        }\n      }\n      async realpath(path, options) {\n        await this.stat(path);\n        return path;\n      }\n      realpathSync(path, options) {\n        this.statSync(path);\n        return path;\n      }\n      async access(path, mode) {\n        await this.stat(path);\n      }\n      accessSync(path, mode) {\n        this.statSync(path);\n      }\n      // === SYMLINK OPERATIONS ===\n      async readlink(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readlink");\n      }\n      readlinkSync(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readlinkSync");\n      }\n      async symlink(target, path, type) {\n        if (this.readonly) {\n          throw createEROFS("symlink", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("symlink");\n      }\n      symlinkSync(target, path, type) {\n        if (this.readonly) {\n          throw createEROFS("symlink", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("symlinkSync");\n      }\n      // === WATCH OPERATIONS ===\n      watch(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("watch");\n      }\n      watchAsync(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("watchAsync");\n      }\n      watchFile(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("watchFile");\n      }\n      unwatchFile(path, listener) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("unwatchFile");\n      }\n    };\n    module2.exports = {\n      VirtualProvider\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/file_handle.js\nvar require_file_handle = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/file_handle.js"(exports2, module2) {\n    "use strict";\n    var { Buffer: Buffer2 } = require("node:buffer");\n    var {\n      createEBADF,\n      ERR_METHOD_NOT_IMPLEMENTED,\n      ERR_INVALID_STATE\n    } = require_errors();\n    var kPath = /* @__PURE__ */ Symbol("kPath");\n    var kFlags = /* @__PURE__ */ Symbol("kFlags");\n    var kMode = /* @__PURE__ */ Symbol("kMode");\n    var kPosition = /* @__PURE__ */ Symbol("kPosition");\n    var kClosed = /* @__PURE__ */ Symbol("kClosed");\n    var VirtualFileHandle = class {\n      constructor(path, flags, mode) {\n        this[kPath] = path;\n        this[kFlags] = flags;\n        this[kMode] = mode ?? 420;\n        this[kPosition] = 0;\n        this[kClosed] = false;\n      }\n      get path() {\n        return this[kPath];\n      }\n      get flags() {\n        return this[kFlags];\n      }\n      get mode() {\n        return this[kMode];\n      }\n      get position() {\n        return this[kPosition];\n      }\n      set position(pos) {\n        this[kPosition] = pos;\n      }\n      get closed() {\n        return this[kClosed];\n      }\n      #checkClosed() {\n        if (this[kClosed]) {\n          throw createEBADF("read");\n        }\n      }\n      async read(buffer, offset, length, position) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("read");\n      }\n      readSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readSync");\n      }\n      async write(buffer, offset, length, position) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("write");\n      }\n      writeSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("writeSync");\n      }\n      async readFile(options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readFile");\n      }\n      readFileSync(options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readFileSync");\n      }\n      async writeFile(data, options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("writeFile");\n      }\n      writeFileSync(data, options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("writeFileSync");\n      }\n      async stat(options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("stat");\n      }\n      statSync(options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("statSync");\n      }\n      async truncate(len) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("truncate");\n      }\n      truncateSync(len) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("truncateSync");\n      }\n      async close() {\n        this[kClosed] = true;\n      }\n      closeSync() {\n        this[kClosed] = true;\n      }\n    };\n    var MemoryFileHandle = class extends VirtualFileHandle {\n      #content;\n      #entry;\n      #getStats;\n      #checkClosed() {\n        if (this.closed) {\n          throw createEBADF("read");\n        }\n      }\n      constructor(path, flags, mode, content, entry, getStats) {\n        super(path, flags, mode);\n        this.#content = content;\n        this.#entry = entry;\n        this.#getStats = getStats;\n        if (flags === "w" || flags === "w+") {\n          this.#content = Buffer2.alloc(0);\n          if (entry) {\n            entry.content = this.#content;\n          }\n        } else if (flags === "a" || flags === "a+") {\n          this.position = this.#content.length;\n        }\n      }\n      get content() {\n        if (this.#entry?.isDynamic && this.#entry.isDynamic()) {\n          return this.#entry.getContentSync();\n        }\n        return this.#content;\n      }\n      async getContentAsync() {\n        if (this.#entry?.getContentAsync) {\n          return this.#entry.getContentAsync();\n        }\n        return this.#content;\n      }\n      readSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        const content = this.content;\n        const readPos = position !== null && position !== void 0 ? position : this.position;\n        const available = content.length - readPos;\n        if (available <= 0) {\n          return 0;\n        }\n        const bytesToRead = Math.min(length, available);\n        content.copy(buffer, offset, readPos, readPos + bytesToRead);\n        if (position === null || position === void 0) {\n          this.position = readPos + bytesToRead;\n        }\n        return bytesToRead;\n      }\n      async read(buffer, offset, length, position) {\n        const bytesRead = this.readSync(buffer, offset, length, position);\n        return { bytesRead, buffer };\n      }\n      writeSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        const writePos = position !== null && position !== void 0 ? position : this.position;\n        const data = buffer.subarray(offset, offset + length);\n        if (writePos + length > this.#content.length) {\n          const newContent = Buffer2.alloc(writePos + length);\n          this.#content.copy(newContent, 0, 0, this.#content.length);\n          this.#content = newContent;\n        }\n        data.copy(this.#content, writePos);\n        if (this.#entry) {\n          this.#entry.content = this.#content;\n          this.#entry.mtime = Date.now();\n        }\n        if (position === null || position === void 0) {\n          this.position = writePos + length;\n        }\n        return length;\n      }\n      async write(buffer, offset, length, position) {\n        const bytesWritten = this.writeSync(buffer, offset, length, position);\n        return { bytesWritten, buffer };\n      }\n      readFileSync(options) {\n        this.#checkClosed();\n        const content = this.content;\n        const encoding = typeof options === "string" ? options : options?.encoding;\n        if (encoding) {\n          return content.toString(encoding);\n        }\n        return Buffer2.from(content);\n      }\n      async readFile(options) {\n        this.#checkClosed();\n        const content = await this.getContentAsync();\n        const encoding = typeof options === "string" ? options : options?.encoding;\n        if (encoding) {\n          return content.toString(encoding);\n        }\n        return Buffer2.from(content);\n      }\n      writeFileSync(data, options) {\n        this.#checkClosed();\n        const buffer = typeof data === "string" ? Buffer2.from(data, options?.encoding) : data;\n        if (this.flags === "a" || this.flags === "a+") {\n          const newContent = Buffer2.alloc(this.#content.length + buffer.length);\n          this.#content.copy(newContent, 0);\n          buffer.copy(newContent, this.#content.length);\n          this.#content = newContent;\n        } else {\n          this.#content = Buffer2.from(buffer);\n        }\n        if (this.#entry) {\n          this.#entry.content = this.#content;\n          this.#entry.mtime = Date.now();\n        }\n        this.position = this.#content.length;\n      }\n      async writeFile(data, options) {\n        this.writeFileSync(data, options);\n      }\n      statSync(options) {\n        this.#checkClosed();\n        if (this.#getStats) {\n          return this.#getStats(this.#content.length);\n        }\n        throw new ERR_INVALID_STATE("stats not available");\n      }\n      async stat(options) {\n        return this.statSync(options);\n      }\n      truncateSync(len = 0) {\n        this.#checkClosed();\n        if (len < this.#content.length) {\n          this.#content = this.#content.subarray(0, len);\n        } else if (len > this.#content.length) {\n          const newContent = Buffer2.alloc(len);\n          this.#content.copy(newContent, 0, 0, this.#content.length);\n          this.#content = newContent;\n        }\n        if (this.#entry) {\n          this.#entry.content = this.#content;\n          this.#entry.mtime = Date.now();\n        }\n      }\n      async truncate(len) {\n        this.truncateSync(len);\n      }\n    };\n    module2.exports = {\n      VirtualFileHandle,\n      MemoryFileHandle\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/stats.js\nvar require_stats = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/stats.js"(exports2, module2) {\n    "use strict";\n    var S_IFMT = 61440;\n    var S_IFREG = 32768;\n    var S_IFDIR = 16384;\n    var S_IFLNK = 40960;\n    var kDefaultBlockSize = 4096;\n    var VirtualStats = class {\n      constructor(props) {\n        this.dev = props.dev ?? 0;\n        this.mode = props.mode;\n        this.nlink = props.nlink ?? 1;\n        this.uid = props.uid ?? (process.getuid?.() ?? 0);\n        this.gid = props.gid ?? (process.getgid?.() ?? 0);\n        this.rdev = props.rdev ?? 0;\n        this.blksize = props.blksize ?? kDefaultBlockSize;\n        this.ino = props.ino ?? 0;\n        this.size = props.size;\n        this.blocks = props.blocks ?? Math.ceil(props.size / 512);\n        this.atimeMs = props.atimeMs;\n        this.mtimeMs = props.mtimeMs;\n        this.ctimeMs = props.ctimeMs;\n        this.birthtimeMs = props.birthtimeMs;\n        this.atime = new Date(this.atimeMs);\n        this.mtime = new Date(this.mtimeMs);\n        this.ctime = new Date(this.ctimeMs);\n        this.birthtime = new Date(this.birthtimeMs);\n      }\n      isFile() {\n        return (this.mode & S_IFMT) === S_IFREG;\n      }\n      isDirectory() {\n        return (this.mode & S_IFMT) === S_IFDIR;\n      }\n      isSymbolicLink() {\n        return (this.mode & S_IFMT) === S_IFLNK;\n      }\n      isBlockDevice() {\n        return false;\n      }\n      isCharacterDevice() {\n        return false;\n      }\n      isFIFO() {\n        return false;\n      }\n      isSocket() {\n        return false;\n      }\n    };\n    function createFileStats(size, options = {}) {\n      const now = Date.now();\n      return new VirtualStats({\n        mode: (options.mode ?? 420) | S_IFREG,\n        size,\n        atimeMs: options.atimeMs ?? now,\n        mtimeMs: options.mtimeMs ?? now,\n        ctimeMs: options.ctimeMs ?? now,\n        birthtimeMs: options.birthtimeMs ?? now\n      });\n    }\n    function createDirectoryStats(options = {}) {\n      const now = Date.now();\n      return new VirtualStats({\n        mode: (options.mode ?? 493) | S_IFDIR,\n        size: kDefaultBlockSize,\n        blocks: 8,\n        atimeMs: options.atimeMs ?? now,\n        mtimeMs: options.mtimeMs ?? now,\n        ctimeMs: options.ctimeMs ?? now,\n        birthtimeMs: options.birthtimeMs ?? now\n      });\n    }\n    function createSymlinkStats(size, options = {}) {\n      const now = Date.now();\n      return new VirtualStats({\n        mode: (options.mode ?? 511) | S_IFLNK,\n        size,\n        atimeMs: options.atimeMs ?? now,\n        mtimeMs: options.mtimeMs ?? now,\n        ctimeMs: options.ctimeMs ?? now,\n        birthtimeMs: options.birthtimeMs ?? now\n      });\n    }\n    module2.exports = {\n      VirtualStats,\n      createFileStats,\n      createDirectoryStats,\n      createSymlinkStats,\n      S_IFMT,\n      S_IFREG,\n      S_IFDIR,\n      S_IFLNK\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/watcher.js\nvar require_watcher = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/watcher.js"(exports2, module2) {\n    "use strict";\n    var { EventEmitter } = require("node:events");\n    var { basename, join } = require("node:path");\n    var VFSWatcher = class extends EventEmitter {\n      #vfs;\n      #path;\n      #interval;\n      #timer = null;\n      #lastStats;\n      #closed = false;\n      #persistent;\n      #recursive;\n      #trackedFiles;\n      #signal;\n      #abortHandler = null;\n      constructor(provider, path, options = {}) {\n        super();\n        this.#vfs = provider;\n        this.#path = path;\n        this.#interval = options.interval ?? 100;\n        this.#persistent = options.persistent !== false;\n        this.#recursive = options.recursive === true;\n        this.#trackedFiles = /* @__PURE__ */ new Map();\n        this.#signal = options.signal;\n        if (this.#signal) {\n          if (this.#signal.aborted) {\n            this.close();\n            return;\n          }\n          this.#abortHandler = () => this.close();\n          this.#signal.addEventListener("abort", this.#abortHandler, { once: true });\n        }\n        this.#lastStats = this.#getStats();\n        if (this.#recursive && this.#lastStats?.isDirectory()) {\n          this.#buildFileList(this.#path, "");\n        }\n        this.#startPolling();\n      }\n      #getStats() {\n        try {\n          return this.#vfs.statSync(this.#path);\n        } catch {\n          return null;\n        }\n      }\n      #startPolling() {\n        if (this.#closed) return;\n        this.#timer = setInterval(() => this.#poll(), this.#interval);\n        if (!this.#persistent && this.#timer.unref) {\n          this.#timer.unref();\n        }\n      }\n      #poll() {\n        if (this.#closed) return;\n        if (this.#recursive && this.#trackedFiles.size > 0) {\n          for (const [filePath, info] of this.#trackedFiles) {\n            const newStats2 = this.#getStatsFor(filePath);\n            if (this.#statsChanged(info.stats, newStats2)) {\n              const eventType = this.#determineEventType(info.stats, newStats2);\n              this.emit("change", eventType, info.relativePath);\n              info.stats = newStats2;\n            }\n          }\n          return;\n        }\n        const newStats = this.#getStats();\n        if (this.#statsChanged(this.#lastStats, newStats)) {\n          const eventType = this.#determineEventType(this.#lastStats, newStats);\n          const filename = basename(this.#path);\n          this.emit("change", eventType, filename);\n        }\n        this.#lastStats = newStats;\n      }\n      #getStatsFor(filePath) {\n        try {\n          return this.#vfs.statSync(filePath);\n        } catch {\n          return null;\n        }\n      }\n      #buildFileList(dirPath, relativePath) {\n        try {\n          const entries = this.#vfs.readdirSync(dirPath, { withFileTypes: true });\n          for (const entry of entries) {\n            const fullPath = join(dirPath, entry.name);\n            const relPath = relativePath ? join(relativePath, entry.name) : entry.name;\n            if (entry.isDirectory()) {\n              this.#buildFileList(fullPath, relPath);\n            } else {\n              const stats = this.#getStatsFor(fullPath);\n              this.#trackedFiles.set(fullPath, {\n                stats,\n                relativePath: relPath\n              });\n            }\n          }\n        } catch {\n        }\n      }\n      #statsChanged(oldStats, newStats) {\n        if (oldStats === null !== (newStats === null)) {\n          return true;\n        }\n        if (oldStats === null && newStats === null) {\n          return false;\n        }\n        if (oldStats.mtimeMs !== newStats.mtimeMs) {\n          return true;\n        }\n        if (oldStats.size !== newStats.size) {\n          return true;\n        }\n        return false;\n      }\n      #determineEventType(oldStats, newStats) {\n        if (oldStats === null !== (newStats === null)) {\n          return "rename";\n        }\n        return "change";\n      }\n      close() {\n        if (this.#closed) return;\n        this.#closed = true;\n        if (this.#timer) {\n          clearInterval(this.#timer);\n          this.#timer = null;\n        }\n        this.#trackedFiles.clear();\n        if (this.#signal && this.#abortHandler) {\n          this.#signal.removeEventListener("abort", this.#abortHandler);\n        }\n        this.emit("close");\n      }\n      unref() {\n        this.#timer?.unref?.();\n        return this;\n      }\n      ref() {\n        this.#timer?.ref?.();\n        return this;\n      }\n    };\n    var VFSStatWatcher = class extends EventEmitter {\n      #vfs;\n      #path;\n      #interval;\n      #persistent;\n      #closed = false;\n      #timer = null;\n      #lastStats;\n      #listeners;\n      constructor(provider, path, options = {}) {\n        super();\n        this.#vfs = provider;\n        this.#path = path;\n        this.#interval = options.interval ?? 5007;\n        this.#persistent = options.persistent !== false;\n        this.#listeners = /* @__PURE__ */ new Set();\n        this.#lastStats = this.#getStats();\n        this.#startPolling();\n      }\n      #getStats() {\n        try {\n          return this.#vfs.statSync(this.#path);\n        } catch {\n          const { createFileStats } = require_stats();\n          return createFileStats(0, {\n            mode: 0,\n            mtimeMs: 0,\n            ctimeMs: 0,\n            birthtimeMs: 0\n          });\n        }\n      }\n      #startPolling() {\n        if (this.#closed) return;\n        this.#timer = setInterval(() => this.#poll(), this.#interval);\n        if (!this.#persistent && this.#timer.unref) {\n          this.#timer.unref();\n        }\n      }\n      #poll() {\n        if (this.#closed) return;\n        const newStats = this.#getStats();\n        if (this.#statsChanged(this.#lastStats, newStats)) {\n          const prevStats = this.#lastStats;\n          this.#lastStats = newStats;\n          this.emit("change", newStats, prevStats);\n        }\n      }\n      #statsChanged(oldStats, newStats) {\n        if (oldStats.mtimeMs !== newStats.mtimeMs) {\n          return true;\n        }\n        if (oldStats.ctimeMs !== newStats.ctimeMs) {\n          return true;\n        }\n        if (oldStats.size !== newStats.size) {\n          return true;\n        }\n        return false;\n      }\n      addListener(listener) {\n        this.#listeners.add(listener);\n        this.on("change", listener);\n      }\n      removeListener(listener) {\n        const had = this.#listeners.has(listener);\n        this.#listeners.delete(listener);\n        super.removeListener("change", listener);\n        return had;\n      }\n      hasNoListeners() {\n        return this.#listeners.size === 0;\n      }\n      stop() {\n        if (this.#closed) return;\n        this.#closed = true;\n        if (this.#timer) {\n          clearInterval(this.#timer);\n          this.#timer = null;\n        }\n        this.emit("stop");\n      }\n      unref() {\n        this.#timer?.unref?.();\n        return this;\n      }\n      ref() {\n        this.#timer?.ref?.();\n        return this;\n      }\n    };\n    var VFSWatchAsyncIterable = class {\n      #watcher;\n      #closed = false;\n      #pendingEvents = [];\n      #pendingResolvers = [];\n      constructor(provider, path, options = {}) {\n        this.#watcher = new VFSWatcher(provider, path, options);\n        this.#watcher.on("change", (eventType, filename) => {\n          const event = { eventType, filename };\n          if (this.#pendingResolvers.length > 0) {\n            const resolve = this.#pendingResolvers.shift();\n            resolve({ value: event, done: false });\n          } else {\n            this.#pendingEvents.push(event);\n          }\n        });\n        this.#watcher.on("close", () => {\n          this.#closed = true;\n          while (this.#pendingResolvers.length > 0) {\n            const resolve = this.#pendingResolvers.shift();\n            resolve({ value: void 0, done: true });\n          }\n        });\n      }\n      [Symbol.asyncIterator]() {\n        return this;\n      }\n      next() {\n        if (this.#closed) {\n          return Promise.resolve({ value: void 0, done: true });\n        }\n        if (this.#pendingEvents.length > 0) {\n          const event = this.#pendingEvents.shift();\n          return Promise.resolve({ value: event, done: false });\n        }\n        return new Promise((resolve) => {\n          this.#pendingResolvers.push(resolve);\n        });\n      }\n      return() {\n        this.#watcher.close();\n        return Promise.resolve({ value: void 0, done: true });\n      }\n      throw(error) {\n        this.#watcher.close();\n        return Promise.resolve({ value: void 0, done: true });\n      }\n    };\n    module2.exports = {\n      VFSWatcher,\n      VFSStatWatcher,\n      VFSWatchAsyncIterable\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/providers/memory.js\nvar require_memory = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/providers/memory.js"(exports2, module2) {\n    "use strict";\n    var { Buffer: Buffer2 } = require("node:buffer");\n    var { posix: pathPosix } = require("node:path");\n    var { VirtualProvider } = require_provider();\n    var { MemoryFileHandle } = require_file_handle();\n    var {\n      VFSWatcher,\n      VFSStatWatcher,\n      VFSWatchAsyncIterable\n    } = require_watcher();\n    var {\n      ERR_INVALID_STATE\n    } = require_errors();\n    var {\n      createENOENT,\n      createENOTDIR,\n      createENOTEMPTY,\n      createEISDIR,\n      createEEXIST,\n      createEINVAL,\n      createELOOP,\n      createEROFS\n    } = require_errors();\n    var {\n      createFileStats,\n      createDirectoryStats,\n      createSymlinkStats\n    } = require_stats();\n    var UV_DIRENT_FILE = 1;\n    var UV_DIRENT_DIR = 2;\n    var UV_DIRENT_LINK = 3;\n    var VirtualDirent = class {\n      #name;\n      #type;\n      #parentPath;\n      constructor(name, type, parentPath) {\n        this.#name = name;\n        this.#type = type;\n        this.#parentPath = parentPath;\n      }\n      get name() {\n        return this.#name;\n      }\n      get parentPath() {\n        return this.#parentPath;\n      }\n      get path() {\n        return this.#parentPath;\n      }\n      isFile() {\n        return this.#type === UV_DIRENT_FILE;\n      }\n      isDirectory() {\n        return this.#type === UV_DIRENT_DIR;\n      }\n      isSymbolicLink() {\n        return this.#type === UV_DIRENT_LINK;\n      }\n      isBlockDevice() {\n        return false;\n      }\n      isCharacterDevice() {\n        return false;\n      }\n      isFIFO() {\n        return false;\n      }\n      isSocket() {\n        return false;\n      }\n    };\n    var kRoot = /* @__PURE__ */ Symbol("kRoot");\n    var kReadonly = /* @__PURE__ */ Symbol("kReadonly");\n    var kStatWatchers = /* @__PURE__ */ Symbol("kStatWatchers");\n    var TYPE_FILE = 0;\n    var TYPE_DIR = 1;\n    var TYPE_SYMLINK = 2;\n    var kMaxSymlinkDepth = 40;\n    var MemoryEntry = class {\n      constructor(type, options = {}) {\n        this.type = type;\n        this.mode = options.mode ?? (type === TYPE_DIR ? 493 : 420);\n        this.content = null;\n        this.contentProvider = null;\n        this.target = null;\n        this.children = null;\n        this.populate = null;\n        this.populated = true;\n        const now = Date.now();\n        this.mtime = now;\n        this.ctime = now;\n        this.birthtime = now;\n      }\n      getContentSync() {\n        if (this.contentProvider !== null) {\n          const result = this.contentProvider();\n          if (result && typeof result.then === "function") {\n            throw new ERR_INVALID_STATE("cannot use sync API with async content provider");\n          }\n          return typeof result === "string" ? Buffer2.from(result) : result;\n        }\n        return this.content;\n      }\n      async getContentAsync() {\n        if (this.contentProvider !== null) {\n          const result = await this.contentProvider();\n          return typeof result === "string" ? Buffer2.from(result) : result;\n        }\n        return this.content;\n      }\n      isDynamic() {\n        return this.contentProvider !== null;\n      }\n      isFile() {\n        return this.type === TYPE_FILE;\n      }\n      isDirectory() {\n        return this.type === TYPE_DIR;\n      }\n      isSymbolicLink() {\n        return this.type === TYPE_SYMLINK;\n      }\n    };\n    var MemoryProvider = class extends VirtualProvider {\n      constructor() {\n        super();\n        this[kRoot] = new MemoryEntry(TYPE_DIR);\n        this[kRoot].children = /* @__PURE__ */ new Map();\n        this[kReadonly] = false;\n        this[kStatWatchers] = /* @__PURE__ */ new Map();\n      }\n      get readonly() {\n        return this[kReadonly];\n      }\n      get supportsWatch() {\n        return true;\n      }\n      setReadOnly() {\n        this[kReadonly] = true;\n      }\n      get supportsSymlinks() {\n        return true;\n      }\n      #normalizePath(path) {\n        let normalized = path.replace(/\\\\/g, "/");\n        if (!normalized.startsWith("/")) {\n          normalized = "/" + normalized;\n        }\n        return pathPosix.normalize(normalized);\n      }\n      #splitPath(path) {\n        if (path === "/") {\n          return [];\n        }\n        return path.slice(1).split("/");\n      }\n      #getParentPath(path) {\n        if (path === "/") {\n          return null;\n        }\n        return pathPosix.dirname(path);\n      }\n      #getBaseName(path) {\n        return pathPosix.basename(path);\n      }\n      #resolveSymlinkTarget(symlinkPath, target) {\n        if (target.startsWith("/")) {\n          return this.#normalizePath(target);\n        }\n        const parentPath = this.#getParentPath(symlinkPath) || "/";\n        return this.#normalizePath(pathPosix.join(parentPath, target));\n      }\n      #lookupEntry(path, followSymlinks = true, depth = 0) {\n        const normalized = this.#normalizePath(path);\n        if (normalized === "/") {\n          return { entry: this[kRoot], resolvedPath: "/" };\n        }\n        const segments = this.#splitPath(normalized);\n        let current = this[kRoot];\n        let currentPath = "/";\n        for (let i = 0; i < segments.length; i++) {\n          const segment = segments[i];\n          if (current.isSymbolicLink() && followSymlinks) {\n            if (depth >= kMaxSymlinkDepth) {\n              return { entry: null, resolvedPath: null, eloop: true };\n            }\n            const targetPath = this.#resolveSymlinkTarget(currentPath, current.target);\n            const result = this.#lookupEntry(targetPath, true, depth + 1);\n            if (result.eloop) {\n              return result;\n            }\n            if (!result.entry) {\n              return { entry: null, resolvedPath: null };\n            }\n            current = result.entry;\n            currentPath = result.resolvedPath;\n          }\n          if (!current.isDirectory()) {\n            return { entry: null, resolvedPath: null };\n          }\n          this.#ensurePopulated(current, currentPath);\n          const entry = current.children.get(segment);\n          if (!entry) {\n            return { entry: null, resolvedPath: null };\n          }\n          currentPath = pathPosix.join(currentPath, segment);\n          current = entry;\n        }\n        if (current.isSymbolicLink() && followSymlinks) {\n          if (depth >= kMaxSymlinkDepth) {\n            return { entry: null, resolvedPath: null, eloop: true };\n          }\n          const targetPath = this.#resolveSymlinkTarget(currentPath, current.target);\n          return this.#lookupEntry(targetPath, true, depth + 1);\n        }\n        return { entry: current, resolvedPath: currentPath };\n      }\n      #getEntry(path, syscall, followSymlinks = true) {\n        const result = this.#lookupEntry(path, followSymlinks);\n        if (result.eloop) {\n          throw createELOOP(syscall, path);\n        }\n        if (!result.entry) {\n          throw createENOENT(syscall, path);\n        }\n        return result.entry;\n      }\n      #ensureParent(path, create, syscall) {\n        const parentPath = this.#getParentPath(path);\n        if (parentPath === null) {\n          return this[kRoot];\n        }\n        const segments = this.#splitPath(parentPath);\n        let current = this[kRoot];\n        for (let i = 0; i < segments.length; i++) {\n          const segment = segments[i];\n          if (current.isSymbolicLink()) {\n            const currentPath2 = pathPosix.join("/", ...segments.slice(0, i));\n            const targetPath = this.#resolveSymlinkTarget(currentPath2, current.target);\n            const result = this.#lookupEntry(targetPath, true, 0);\n            if (!result.entry) {\n              throw createENOENT(syscall, path);\n            }\n            current = result.entry;\n          }\n          if (!current.isDirectory()) {\n            throw createENOTDIR(syscall, path);\n          }\n          const currentPath = pathPosix.join("/", ...segments.slice(0, i));\n          this.#ensurePopulated(current, currentPath);\n          let entry = current.children.get(segment);\n          if (!entry) {\n            if (create) {\n              entry = new MemoryEntry(TYPE_DIR);\n              entry.children = /* @__PURE__ */ new Map();\n              current.children.set(segment, entry);\n            } else {\n              throw createENOENT(syscall, path);\n            }\n          }\n          current = entry;\n        }\n        if (!current.isDirectory()) {\n          throw createENOTDIR(syscall, path);\n        }\n        const finalPath = pathPosix.join("/", ...segments);\n        this.#ensurePopulated(current, finalPath);\n        return current;\n      }\n      #createStats(entry, size) {\n        const options = {\n          mode: entry.mode,\n          mtimeMs: entry.mtime,\n          ctimeMs: entry.ctime,\n          birthtimeMs: entry.birthtime\n        };\n        if (entry.isFile()) {\n          return createFileStats(size !== void 0 ? size : entry.content.length, options);\n        } else if (entry.isDirectory()) {\n          return createDirectoryStats(options);\n        } else if (entry.isSymbolicLink()) {\n          return createSymlinkStats(entry.target.length, options);\n        }\n        throw new ERR_INVALID_STATE("Unknown entry type");\n      }\n      #ensurePopulated(entry, path) {\n        if (entry.isDirectory() && !entry.populated && entry.populate) {\n          const scopedVfs = {\n            addFile: (name, content, opts) => {\n              const fileEntry = new MemoryEntry(TYPE_FILE, opts);\n              if (typeof content === "function") {\n                fileEntry.content = Buffer2.alloc(0);\n                fileEntry.contentProvider = content;\n              } else {\n                fileEntry.content = typeof content === "string" ? Buffer2.from(content) : content;\n              }\n              entry.children.set(name, fileEntry);\n            },\n            addDirectory: (name, populate, opts) => {\n              const dirEntry = new MemoryEntry(TYPE_DIR, opts);\n              dirEntry.children = /* @__PURE__ */ new Map();\n              if (typeof populate === "function") {\n                dirEntry.populate = populate;\n                dirEntry.populated = false;\n              }\n              entry.children.set(name, dirEntry);\n            },\n            addSymlink: (name, target, opts) => {\n              const symlinkEntry = new MemoryEntry(TYPE_SYMLINK, opts);\n              symlinkEntry.target = target;\n              entry.children.set(name, symlinkEntry);\n            }\n          };\n          entry.populate(scopedVfs);\n          entry.populated = true;\n        }\n      }\n      openSync(path, flags, mode) {\n        const normalized = this.#normalizePath(path);\n        const isCreate = flags === "w" || flags === "w+" || flags === "a" || flags === "a+";\n        if (this.readonly && isCreate) {\n          throw createEROFS("open", path);\n        }\n        let entry;\n        try {\n          entry = this.#getEntry(normalized, "open");\n        } catch (err) {\n          if (err.code === "ENOENT" && isCreate) {\n            const parent = this.#ensureParent(normalized, true, "open");\n            const name = this.#getBaseName(normalized);\n            entry = new MemoryEntry(TYPE_FILE, { mode });\n            entry.content = Buffer2.alloc(0);\n            parent.children.set(name, entry);\n          } else {\n            throw err;\n          }\n        }\n        if (entry.isDirectory()) {\n          throw createEISDIR("open", path);\n        }\n        if (entry.isSymbolicLink()) {\n          throw createEINVAL("open", path);\n        }\n        const getStats = (size) => this.#createStats(entry, size);\n        return new MemoryFileHandle(normalized, flags, mode ?? entry.mode, entry.content, entry, getStats);\n      }\n      async open(path, flags, mode) {\n        return this.openSync(path, flags, mode);\n      }\n      statSync(path, options) {\n        const entry = this.#getEntry(path, "stat", true);\n        return this.#createStats(entry);\n      }\n      async stat(path, options) {\n        return this.statSync(path, options);\n      }\n      lstatSync(path, options) {\n        const entry = this.#getEntry(path, "lstat", false);\n        return this.#createStats(entry);\n      }\n      async lstat(path, options) {\n        return this.lstatSync(path, options);\n      }\n      readdirSync(path, options) {\n        const entry = this.#getEntry(path, "scandir", true);\n        if (!entry.isDirectory()) {\n          throw createENOTDIR("scandir", path);\n        }\n        this.#ensurePopulated(entry, path);\n        const names = [...entry.children.keys()];\n        if (options?.withFileTypes) {\n          const normalized = this.#normalizePath(path);\n          const dirents = [];\n          for (const name of names) {\n            const childEntry = entry.children.get(name);\n            let type;\n            if (childEntry.isSymbolicLink()) {\n              type = UV_DIRENT_LINK;\n            } else if (childEntry.isDirectory()) {\n              type = UV_DIRENT_DIR;\n            } else {\n              type = UV_DIRENT_FILE;\n            }\n            dirents.push(new VirtualDirent(name, type, normalized));\n          }\n          return dirents;\n        }\n        return names;\n      }\n      async readdir(path, options) {\n        return this.readdirSync(path, options);\n      }\n      mkdirSync(path, options) {\n        if (this.readonly) {\n          throw createEROFS("mkdir", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const recursive = options?.recursive === true;\n        const existing = this.#lookupEntry(normalized, true);\n        if (existing.entry) {\n          if (existing.entry.isDirectory() && recursive) {\n            return void 0;\n          }\n          throw createEEXIST("mkdir", path);\n        }\n        if (recursive) {\n          const segments = this.#splitPath(normalized);\n          let current = this[kRoot];\n          for (const segment of segments) {\n            let entry = current.children.get(segment);\n            if (!entry) {\n              entry = new MemoryEntry(TYPE_DIR, { mode: options?.mode });\n              entry.children = /* @__PURE__ */ new Map();\n              current.children.set(segment, entry);\n            } else if (!entry.isDirectory()) {\n              throw createENOTDIR("mkdir", path);\n            }\n            current = entry;\n          }\n        } else {\n          const parent = this.#ensureParent(normalized, false, "mkdir");\n          const name = this.#getBaseName(normalized);\n          const entry = new MemoryEntry(TYPE_DIR, { mode: options?.mode });\n          entry.children = /* @__PURE__ */ new Map();\n          parent.children.set(name, entry);\n        }\n        return recursive ? normalized : void 0;\n      }\n      async mkdir(path, options) {\n        return this.mkdirSync(path, options);\n      }\n      rmdirSync(path) {\n        if (this.readonly) {\n          throw createEROFS("rmdir", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const entry = this.#getEntry(normalized, "rmdir", true);\n        if (!entry.isDirectory()) {\n          throw createENOTDIR("rmdir", path);\n        }\n        if (entry.children.size > 0) {\n          throw createENOTEMPTY("rmdir", path);\n        }\n        const parent = this.#ensureParent(normalized, false, "rmdir");\n        const name = this.#getBaseName(normalized);\n        parent.children.delete(name);\n      }\n      async rmdir(path) {\n        this.rmdirSync(path);\n      }\n      unlinkSync(path) {\n        if (this.readonly) {\n          throw createEROFS("unlink", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const entry = this.#getEntry(normalized, "unlink", false);\n        if (entry.isDirectory()) {\n          throw createEISDIR("unlink", path);\n        }\n        const parent = this.#ensureParent(normalized, false, "unlink");\n        const name = this.#getBaseName(normalized);\n        parent.children.delete(name);\n      }\n      async unlink(path) {\n        this.unlinkSync(path);\n      }\n      renameSync(oldPath, newPath) {\n        if (this.readonly) {\n          throw createEROFS("rename", oldPath);\n        }\n        const normalizedOld = this.#normalizePath(oldPath);\n        const normalizedNew = this.#normalizePath(newPath);\n        const entry = this.#getEntry(normalizedOld, "rename", false);\n        const oldParent = this.#ensureParent(normalizedOld, false, "rename");\n        const oldName = this.#getBaseName(normalizedOld);\n        oldParent.children.delete(oldName);\n        const newParent = this.#ensureParent(normalizedNew, true, "rename");\n        const newName = this.#getBaseName(normalizedNew);\n        newParent.children.set(newName, entry);\n      }\n      async rename(oldPath, newPath) {\n        this.renameSync(oldPath, newPath);\n      }\n      readlinkSync(path, options) {\n        const normalized = this.#normalizePath(path);\n        const entry = this.#getEntry(normalized, "readlink", false);\n        if (!entry.isSymbolicLink()) {\n          throw createEINVAL("readlink", path);\n        }\n        return entry.target;\n      }\n      async readlink(path, options) {\n        return this.readlinkSync(path, options);\n      }\n      symlinkSync(target, path, type) {\n        if (this.readonly) {\n          throw createEROFS("symlink", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const existing = this.#lookupEntry(normalized, false);\n        if (existing.entry) {\n          throw createEEXIST("symlink", path);\n        }\n        const parent = this.#ensureParent(normalized, true, "symlink");\n        const name = this.#getBaseName(normalized);\n        const entry = new MemoryEntry(TYPE_SYMLINK);\n        entry.target = target;\n        parent.children.set(name, entry);\n      }\n      async symlink(target, path, type) {\n        this.symlinkSync(target, path, type);\n      }\n      realpathSync(path, options) {\n        const result = this.#lookupEntry(path, true, 0);\n        if (result.eloop) {\n          throw createELOOP("realpath", path);\n        }\n        if (!result.entry) {\n          throw createENOENT("realpath", path);\n        }\n        return result.resolvedPath;\n      }\n      async realpath(path, options) {\n        return this.realpathSync(path, options);\n      }\n      // === WATCH OPERATIONS ===\n      watch(path, options) {\n        const normalized = this.#normalizePath(path);\n        return new VFSWatcher(this, normalized, options);\n      }\n      watchAsync(path, options) {\n        const normalized = this.#normalizePath(path);\n        return new VFSWatchAsyncIterable(this, normalized, options);\n      }\n      watchFile(path, options, listener) {\n        const normalized = this.#normalizePath(path);\n        let watcher = this[kStatWatchers].get(normalized);\n        if (!watcher) {\n          watcher = new VFSStatWatcher(this, normalized, options);\n          this[kStatWatchers].set(normalized, watcher);\n        }\n        if (listener) {\n          watcher.addListener(listener);\n        }\n        return watcher;\n      }\n      unwatchFile(path, listener) {\n        const normalized = this.#normalizePath(path);\n        const watcher = this[kStatWatchers].get(normalized);\n        if (!watcher) {\n          return;\n        }\n        if (listener) {\n          watcher.removeListener(listener);\n        } else {\n          watcher.removeAllListeners("change");\n        }\n        if (watcher.hasNoListeners()) {\n          watcher.stop();\n          this[kStatWatchers].delete(normalized);\n        }\n      }\n    };\n    module2.exports = {\n      MemoryProvider\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/router.js\nvar require_router = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/router.js"(exports2, module2) {\n    "use strict";\n    var { isAbsolute, posix: pathPosix } = require("node:path");\n    function splitPath(normalizedPath) {\n      if (normalizedPath === "/") {\n        return [];\n      }\n      return normalizedPath.slice(1).split("/");\n    }\n    function getParentPath(normalizedPath) {\n      if (normalizedPath === "/") {\n        return null;\n      }\n      return pathPosix.dirname(normalizedPath);\n    }\n    function getBaseName(normalizedPath) {\n      return pathPosix.basename(normalizedPath);\n    }\n    function isUnderMountPoint(normalizedPath, mountPoint) {\n      if (normalizedPath === mountPoint) {\n        return true;\n      }\n      if (mountPoint === "/") {\n        return normalizedPath.startsWith("/");\n      }\n      return normalizedPath.startsWith(mountPoint + "/");\n    }\n    function getRelativePath(normalizedPath, mountPoint) {\n      if (normalizedPath === mountPoint) {\n        return "/";\n      }\n      if (mountPoint === "/") {\n        return normalizedPath;\n      }\n      return normalizedPath.slice(mountPoint.length);\n    }\n    module2.exports = {\n      splitPath,\n      getParentPath,\n      getBaseName,\n      isUnderMountPoint,\n      getRelativePath,\n      isAbsolutePath: isAbsolute\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/fd.js\nvar require_fd = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/fd.js"(exports2, module2) {\n    "use strict";\n    var kFd = /* @__PURE__ */ Symbol("kFd");\n    var kEntry = /* @__PURE__ */ Symbol("kEntry");\n    var nextFd = 1e4;\n    var openFDs = /* @__PURE__ */ new Map();\n    var VirtualFD = class {\n      constructor(fd, entry) {\n        this[kFd] = fd;\n        this[kEntry] = entry;\n      }\n      get fd() {\n        return this[kFd];\n      }\n      get entry() {\n        return this[kEntry];\n      }\n    };\n    function openVirtualFd(entry) {\n      const fd = nextFd++;\n      const vfd = new VirtualFD(fd, entry);\n      openFDs.set(fd, vfd);\n      return fd;\n    }\n    function getVirtualFd(fd) {\n      return openFDs.get(fd);\n    }\n    function closeVirtualFd(fd) {\n      return openFDs.delete(fd);\n    }\n    module2.exports = {\n      VirtualFD,\n      openVirtualFd,\n      getVirtualFd,\n      closeVirtualFd\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/streams.js\nvar require_streams = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/streams.js"(exports2, module2) {\n    "use strict";\n    var { Readable } = require("node:stream");\n    var { createEBADF } = require_errors();\n    var { getVirtualFd } = require_fd();\n    var VirtualReadStream = class extends Readable {\n      #vfs;\n      #path;\n      #fd = null;\n      #end;\n      #pos;\n      #content = null;\n      #destroyed = false;\n      #autoClose;\n      constructor(vfs2, filePath, options = {}) {\n        const {\n          start = 0,\n          end = Infinity,\n          highWaterMark = 64 * 1024,\n          encoding,\n          ...streamOptions\n        } = options;\n        super({ ...streamOptions, highWaterMark, encoding });\n        this.#vfs = vfs2;\n        this.#path = filePath;\n        this.#end = end;\n        this.#pos = start;\n        this.#autoClose = options.autoClose !== false;\n        process.nextTick(() => this.#openFile());\n      }\n      get path() {\n        return this.#path;\n      }\n      #openFile() {\n        try {\n          this.#fd = this.#vfs.openSync(this.#path);\n          this.emit("open", this.#fd);\n          this.emit("ready");\n        } catch (err) {\n          this.destroy(err);\n        }\n      }\n      _read(size) {\n        if (this.#destroyed || this.#fd === null) {\n          return;\n        }\n        if (this.#content === null) {\n          try {\n            const vfd = getVirtualFd(this.#fd);\n            if (!vfd) {\n              this.destroy(createEBADF("read"));\n              return;\n            }\n            this.#content = vfd.entry.readFileSync();\n          } catch (err) {\n            this.destroy(err);\n            return;\n          }\n        }\n        const endPos = this.#end === Infinity ? this.#content.length : this.#end + 1;\n        const remaining = Math.min(endPos, this.#content.length) - this.#pos;\n        if (remaining <= 0) {\n          this.push(null);\n          return;\n        }\n        const bytesToRead = Math.min(size, remaining);\n        const chunk = this.#content.subarray(this.#pos, this.#pos + bytesToRead);\n        this.#pos += bytesToRead;\n        this.push(chunk);\n        if (this.#pos >= endPos || this.#pos >= this.#content.length) {\n          this.push(null);\n        }\n      }\n      #close() {\n        if (this.#fd !== null) {\n          try {\n            this.#vfs.closeSync(this.#fd);\n          } catch {\n          }\n          this.#fd = null;\n        }\n      }\n      _destroy(err, callback) {\n        this.#destroyed = true;\n        if (this.#autoClose) {\n          this.#close();\n        }\n        callback(err);\n      }\n    };\n    module2.exports = {\n      VirtualReadStream\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/module_hooks.js\nvar require_module_hooks = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/module_hooks.js"(exports2, module2) {\n    "use strict";\n    var path = require("node:path");\n    var { dirname, extname, isAbsolute, resolve } = path;\n    var pathPosix = path.posix;\n    var { pathToFileURL, fileURLToPath } = require("node:url");\n    var { createENOENT } = require_errors();\n    var kEmptyObject = Object.freeze(/* @__PURE__ */ Object.create(null));\n    var NodeModule = require("node:module");\n    var builtinSet = new Set(NodeModule.builtinModules);\n    var ESM_EXTENSIONS = [".js", ".json", ".node", ".mjs", ".cjs"];\n    var CJS_EXTENSIONS = [".js", ".json", ".node"];\n    var ESM_INDEX_FILES = ["index.js", "index.mjs", "index.cjs", "index.json"];\n    var CJS_INDEX_FILES = ["index.js", "index.json", "index.node"];\n    var CJS_CONDITIONS = ["require", "node", "default"];\n    function isNodeBuiltin(name) {\n      if (typeof NodeModule.isBuiltin === "function") {\n        return NodeModule.isBuiltin(name);\n      }\n      const bare = name.startsWith("node:") ? name.slice(5) : name;\n      return builtinSet.has(bare);\n    }\n    function normalizeVFSPath(inputPath) {\n      if (process.platform === "win32" && /^V:[/\\\\]/.test(inputPath)) {\n        inputPath = "/" + inputPath.slice(3).replace(/\\\\/g, "/");\n      }\n      if (inputPath.startsWith("/")) {\n        return pathPosix.normalize(inputPath);\n      }\n      return path.normalize(inputPath);\n    }\n    function joinVFSParts(...parts) {\n      if (parts[0]?.startsWith("/")) {\n        return pathPosix.resolve(...parts);\n      }\n      return resolve(...parts);\n    }\n    function dirnameVFS(p) {\n      if (p.startsWith("/")) {\n        return pathPosix.dirname(p);\n      }\n      return dirname(p);\n    }\n    function vfsPathToURL(vfsPath) {\n      if (vfsPath.startsWith("/") && process.platform === "win32") {\n        return "file:///V:" + encodeURI(vfsPath);\n      }\n      return pathToFileURL(vfsPath).href;\n    }\n    function urlToVFSPath(url) {\n      const parsed = new URL(url);\n      const pathname = decodeURIComponent(parsed.pathname);\n      if (process.platform === "win32" && pathname.startsWith("/V:/")) {\n        return pathname.slice(3);\n      }\n      if (process.platform === "win32" && pathname.startsWith("/") && !/^\\/[A-Za-z]:/.test(pathname)) {\n        return pathname;\n      }\n      return fileURLToPath(url);\n    }\n    var activeVFSList = [];\n    var originalReadFileSync = null;\n    var originalRealpathSync = null;\n    var originalLstatSync = null;\n    var originalStatSync = null;\n    var originalReaddirSync = null;\n    var originalExistsSync = null;\n    var originalWatch = null;\n    var originalWatchFile = null;\n    var originalUnwatchFile = null;\n    var hooksInstalled = false;\n    function registerVFS(vfs2) {\n      if (activeVFSList.indexOf(vfs2) === -1) {\n        activeVFSList.push(vfs2);\n        if (!hooksInstalled) {\n          installHooks();\n        }\n      }\n    }\n    function deregisterVFS(vfs2) {\n      const index = activeVFSList.indexOf(vfs2);\n      if (index !== -1) {\n        activeVFSList.splice(index, 1);\n      }\n    }\n    function findVFSForStat(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          const result = vfs2.internalModuleStat(normalized);\n          if (vfs2.mounted || result >= 0) {\n            return { vfs: vfs2, result };\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForRead(filename, options) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.existsSync(normalized)) {\n            const statResult = vfs2.internalModuleStat(normalized);\n            if (statResult !== 0) {\n              return null;\n            }\n            try {\n              const content = vfs2.readFileSync(normalized, options);\n              return { vfs: vfs2, content };\n            } catch (e) {\n              if (vfs2.mounted) {\n                throw e;\n              }\n            }\n          } else if (vfs2.mounted) {\n            throw createENOENT("open", filename);\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForExists(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          const exists = vfs2.existsSync(normalized);\n          if (vfs2.mounted || exists) {\n            return { vfs: vfs2, exists };\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForRealpath(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.existsSync(normalized)) {\n            try {\n              const realpath = vfs2.realpathSync(normalized);\n              return { vfs: vfs2, realpath };\n            } catch (e) {\n              if (vfs2.mounted) {\n                throw e;\n              }\n            }\n          } else if (vfs2.mounted) {\n            throw createENOENT("realpath", filename);\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForFsStat(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.existsSync(normalized)) {\n            try {\n              const stats = vfs2.statSync(normalized);\n              return { vfs: vfs2, stats };\n            } catch (e) {\n              if (vfs2.mounted) {\n                throw e;\n              }\n            }\n          } else if (vfs2.mounted) {\n            throw createENOENT("stat", filename);\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForReaddir(dirname2, options) {\n      const normalized = normalizeVFSPath(dirname2);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.existsSync(normalized)) {\n            try {\n              const entries = vfs2.readdirSync(normalized, options);\n              return { vfs: vfs2, entries };\n            } catch (e) {\n              if (vfs2.mounted) {\n                throw e;\n              }\n            }\n          } else if (vfs2.mounted) {\n            throw createENOENT("scandir", dirname2);\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForWatch(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.overlay) {\n            if (vfs2.existsSync(normalized)) {\n              return { vfs: vfs2 };\n            }\n            continue;\n          }\n          return { vfs: vfs2 };\n        }\n      }\n      return null;\n    }\n    var VFS_FORMAT_MAP = {\n      "__proto__": null,\n      ".cjs": "commonjs",\n      ".js": null,\n      ".json": "json",\n      ".mjs": "module",\n      ".node": "addon",\n      ".wasm": "wasm"\n    };\n    function getVFSPackageType(vfs2, filePath) {\n      let currentDir = dirnameVFS(filePath);\n      let lastDir;\n      while (currentDir !== lastDir) {\n        if (currentDir.endsWith("/node_modules") || currentDir.endsWith("\\\\node_modules")) {\n          break;\n        }\n        const pjsonPath = normalizeVFSPath(joinVFSParts(currentDir, "package.json"));\n        if (vfs2.shouldHandle(pjsonPath) && vfs2.internalModuleStat(pjsonPath) === 0) {\n          try {\n            const content = vfs2.readFileSync(pjsonPath, "utf8");\n            const parsed = JSON.parse(content);\n            if (parsed.type === "module" || parsed.type === "commonjs") {\n              return parsed.type;\n            }\n            return "none";\n          } catch {\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return "none";\n    }\n    function getVFSFormat(vfs2, filePath) {\n      const ext = extname(filePath);\n      if (ext === ".js") {\n        return getVFSPackageType(vfs2, filePath) === "module" ? "module" : "commonjs";\n      }\n      return VFS_FORMAT_MAP[ext] ?? "commonjs";\n    }\n    function matchWildcardPattern(keys, subpath) {\n      for (let i = 0; i < keys.length; i++) {\n        const key = keys[i];\n        const starIdx = key.indexOf("*");\n        if (starIdx === -1) continue;\n        const prefix = key.slice(0, starIdx);\n        const suffix = key.slice(starIdx + 1);\n        if (subpath.startsWith(prefix) && (suffix === "" || subpath.endsWith(suffix)) && subpath.length >= prefix.length + suffix.length) {\n          return {\n            key,\n            patternMatch: subpath.slice(\n              prefix.length,\n              suffix.length > 0 ? -suffix.length : void 0\n            )\n          };\n        }\n      }\n      return null;\n    }\n    function expandPattern(value, patternMatch) {\n      return patternMatch !== null ? value.replace(/\\*/g, patternMatch) : value;\n    }\n    function findVFSForPath(normalizedPath) {\n      for (let i = 0; i < activeVFSList.length; i++) {\n        if (activeVFSList[i].shouldHandle(normalizedPath)) {\n          return activeVFSList[i];\n        }\n      }\n      return null;\n    }\n    function makeResolveResult(vfs2, filePath) {\n      return {\n        url: vfsPathToURL(filePath),\n        format: getVFSFormat(vfs2, filePath),\n        shortCircuit: true\n      };\n    }\n    function tryExtensions(vfs2, basePath, extensions) {\n      for (let i = 0; i < extensions.length; i++) {\n        const candidate = basePath + extensions[i];\n        if (vfs2.internalModuleStat(candidate) === 0) {\n          return candidate;\n        }\n      }\n      return null;\n    }\n    function tryIndexFiles(vfs2, dirPath, indexFiles) {\n      for (let i = 0; i < indexFiles.length; i++) {\n        const candidate = normalizeVFSPath(joinVFSParts(dirPath, indexFiles[i]));\n        if (vfs2.internalModuleStat(candidate) === 0) {\n          return candidate;\n        }\n      }\n      return null;\n    }\n    function resolveMainField(vfs2, dirPath, main, extensions, indexFiles) {\n      const mainPath = normalizeVFSPath(joinVFSParts(dirPath, main));\n      const mainStat = vfs2.internalModuleStat(mainPath);\n      if (mainStat === 0) return mainPath;\n      const withExt = tryExtensions(vfs2, mainPath, extensions);\n      if (withExt) return withExt;\n      if (mainStat === 1) return tryIndexFiles(vfs2, mainPath, indexFiles);\n      return null;\n    }\n    function resolveExportTarget(vfs2, pkgDir, target, patternMatch, extensions) {\n      if (typeof target !== "string") return null;\n      const expanded = expandPattern(target, patternMatch);\n      const resolved = normalizeVFSPath(joinVFSParts(pkgDir, expanded));\n      if (vfs2.internalModuleStat(resolved) === 0) return resolved;\n      return extensions ? tryExtensions(vfs2, resolved, extensions) : null;\n    }\n    function resolveConditionsToPath(vfs2, pkgDir, condMap, conditions, patternMatch, extensions) {\n      const keys = Object.getOwnPropertyNames(condMap);\n      for (let i = 0; i < keys.length; i++) {\n        const key = keys[i];\n        if (key === "default" || conditions.indexOf(key) !== -1) {\n          const value = condMap[key];\n          if (typeof value === "string") {\n            const result = resolveExportTarget(vfs2, pkgDir, value, patternMatch, extensions);\n            if (result) return result;\n            continue;\n          }\n          if (typeof value === "object" && value !== null && !Array.isArray(value)) {\n            const result = resolveConditionsToPath(vfs2, pkgDir, value, conditions, patternMatch, extensions);\n            if (result) return result;\n            continue;\n          }\n        }\n      }\n      return null;\n    }\n    function resolveExportsToPath(vfs2, pkgDir, packageSubpath, exports3, conditions, extensions) {\n      if (typeof exports3 === "string") {\n        if (packageSubpath === ".") {\n          return resolveExportTarget(vfs2, pkgDir, exports3, null, extensions);\n        }\n        return null;\n      }\n      if (typeof exports3 !== "object" || exports3 === null) return null;\n      const keys = Object.getOwnPropertyNames(exports3);\n      if (keys.length === 0) return null;\n      const isConditional = keys[0] !== "" && keys[0][0] !== ".";\n      if (isConditional) {\n        if (packageSubpath !== ".") return null;\n        return resolveConditionsToPath(vfs2, pkgDir, exports3, conditions, null, extensions);\n      }\n      let target = exports3[packageSubpath];\n      let patternMatch = null;\n      if (target === void 0) {\n        const match = matchWildcardPattern(keys, packageSubpath);\n        if (match) {\n          patternMatch = match.patternMatch;\n          target = exports3[match.key];\n        }\n      }\n      if (target === void 0) return null;\n      if (typeof target === "string") {\n        return resolveExportTarget(vfs2, pkgDir, target, patternMatch, extensions);\n      }\n      if (typeof target === "object" && target !== null && !Array.isArray(target)) {\n        return resolveConditionsToPath(vfs2, pkgDir, target, conditions, patternMatch, extensions);\n      }\n      return null;\n    }\n    function resolveDirectoryEntry(vfs2, dirPath, context) {\n      const pjsonPath = normalizeVFSPath(joinVFSParts(dirPath, "package.json"));\n      if (vfs2.internalModuleStat(pjsonPath) === 0) {\n        try {\n          const content = vfs2.readFileSync(pjsonPath, "utf8");\n          const parsed = JSON.parse(content);\n          if (parsed.exports != null) {\n            const resolved = resolveExportsToPath(\n              vfs2,\n              dirPath,\n              ".",\n              parsed.exports,\n              context.conditions || [],\n              null\n            );\n            if (resolved) return makeResolveResult(vfs2, resolved);\n          }\n          if (parsed.main) {\n            const mainResult = resolveMainField(\n              vfs2,\n              dirPath,\n              parsed.main,\n              ESM_EXTENSIONS,\n              ESM_INDEX_FILES\n            );\n            if (mainResult) return makeResolveResult(vfs2, mainResult);\n          }\n        } catch {\n        }\n      }\n      const indexResult = tryIndexFiles(vfs2, dirPath, ESM_INDEX_FILES);\n      return indexResult ? makeResolveResult(vfs2, indexResult) : null;\n    }\n    function parsePackageName(specifier) {\n      let separatorIndex = specifier.indexOf("/");\n      if (specifier[0] === "@") {\n        if (separatorIndex === -1) {\n          return { packageName: specifier, packageSubpath: "." };\n        }\n        separatorIndex = specifier.indexOf("/", separatorIndex + 1);\n      }\n      const packageName = separatorIndex === -1 ? specifier : specifier.slice(0, separatorIndex);\n      let packageSubpath = separatorIndex === -1 ? "." : "." + specifier.slice(separatorIndex);\n      if (packageSubpath === "./") packageSubpath = ".";\n      return { packageName, packageSubpath };\n    }\n    function urlToPath(urlOrPath) {\n      if (urlOrPath.startsWith("file:")) {\n        return fileURLToPath(urlOrPath);\n      }\n      return urlOrPath;\n    }\n    function resolveVFSPath(checkPath, context, nextResolve, specifier) {\n      const normalized = normalizeVFSPath(checkPath);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (!vfs2.shouldHandle(normalized)) continue;\n        const stat = vfs2.internalModuleStat(normalized);\n        if (stat === 0) {\n          return makeResolveResult(vfs2, normalized);\n        }\n        const withExt = tryExtensions(vfs2, normalized, ESM_EXTENSIONS);\n        if (withExt) return makeResolveResult(vfs2, withExt);\n        if (stat === 1) {\n          const resolved = resolveDirectoryEntry(vfs2, normalized, context);\n          if (resolved) return resolved;\n        }\n      }\n      return nextResolve(specifier, context);\n    }\n    function resolvePackageInVFS(vfs2, startDir, packageName, packageSubpath, context) {\n      let currentDir = startDir;\n      let lastDir;\n      const conditions = context.conditions || [];\n      while (currentDir !== lastDir) {\n        const pkgDir = normalizeVFSPath(\n          joinVFSParts(currentDir, "node_modules", packageName)\n        );\n        if (vfs2.shouldHandle(pkgDir) && vfs2.internalModuleStat(pkgDir) === 1) {\n          const pjsonPath = normalizeVFSPath(\n            joinVFSParts(pkgDir, "package.json")\n          );\n          if (vfs2.internalModuleStat(pjsonPath) === 0) {\n            try {\n              const parsed = JSON.parse(vfs2.readFileSync(pjsonPath, "utf8"));\n              if (parsed.exports != null) {\n                const resolved = resolveExportsToPath(\n                  vfs2,\n                  pkgDir,\n                  packageSubpath,\n                  parsed.exports,\n                  conditions,\n                  null\n                );\n                if (resolved) return makeResolveResult(vfs2, resolved);\n              }\n              if (packageSubpath === ".") {\n                if (parsed.main) {\n                  const mainResult = resolveMainField(\n                    vfs2,\n                    pkgDir,\n                    parsed.main,\n                    ESM_EXTENSIONS,\n                    ESM_INDEX_FILES\n                  );\n                  if (mainResult) return makeResolveResult(vfs2, mainResult);\n                }\n                const indexResult = tryIndexFiles(vfs2, pkgDir, ESM_INDEX_FILES);\n                if (indexResult) return makeResolveResult(vfs2, indexResult);\n              } else {\n                const subResolved = normalizeVFSPath(\n                  joinVFSParts(pkgDir, packageSubpath)\n                );\n                if (vfs2.internalModuleStat(subResolved) === 0) {\n                  return makeResolveResult(vfs2, subResolved);\n                }\n                const withExt = tryExtensions(vfs2, subResolved, ESM_EXTENSIONS);\n                if (withExt) return makeResolveResult(vfs2, withExt);\n              }\n            } catch {\n            }\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return null;\n    }\n    function resolveCJSPackageInVFS(vfs2, startDir, packageName, packageSubpath) {\n      let currentDir = startDir;\n      let lastDir;\n      while (currentDir !== lastDir) {\n        const pkgDir = normalizeVFSPath(\n          joinVFSParts(currentDir, "node_modules", packageName)\n        );\n        if (vfs2.shouldHandle(pkgDir) && vfs2.internalModuleStat(pkgDir) === 1) {\n          const pjsonPath = normalizeVFSPath(\n            joinVFSParts(pkgDir, "package.json")\n          );\n          let parsed = null;\n          if (vfs2.internalModuleStat(pjsonPath) === 0) {\n            try {\n              parsed = JSON.parse(vfs2.readFileSync(pjsonPath, "utf8"));\n            } catch {\n            }\n          }\n          if (parsed?.exports != null) {\n            const exportsResult = resolveExportsToPath(\n              vfs2,\n              pkgDir,\n              packageSubpath,\n              parsed.exports,\n              CJS_CONDITIONS,\n              CJS_EXTENSIONS\n            );\n            if (exportsResult) return exportsResult;\n          }\n          if (packageSubpath === ".") {\n            if (parsed?.main) {\n              const mainResult = resolveMainField(\n                vfs2,\n                pkgDir,\n                parsed.main,\n                CJS_EXTENSIONS,\n                CJS_INDEX_FILES\n              );\n              if (mainResult) return mainResult;\n            }\n            const idxResult = tryIndexFiles(vfs2, pkgDir, CJS_INDEX_FILES);\n            if (idxResult) return idxResult;\n          } else {\n            const subResolved = normalizeVFSPath(\n              joinVFSParts(pkgDir, packageSubpath)\n            );\n            const subStat = vfs2.internalModuleStat(subResolved);\n            if (subStat === 0) {\n              return subResolved;\n            }\n            const withExt = tryExtensions(vfs2, subResolved, CJS_EXTENSIONS);\n            if (withExt) return withExt;\n            if (subStat === 1) {\n              const subPjsonPath = normalizeVFSPath(\n                joinVFSParts(subResolved, "package.json")\n              );\n              if (vfs2.internalModuleStat(subPjsonPath) === 0) {\n                try {\n                  const subParsed = JSON.parse(vfs2.readFileSync(subPjsonPath, "utf8"));\n                  if (subParsed.main) {\n                    const mainResult = resolveMainField(\n                      vfs2,\n                      subResolved,\n                      subParsed.main,\n                      CJS_EXTENSIONS,\n                      CJS_INDEX_FILES\n                    );\n                    if (mainResult) return mainResult;\n                  }\n                } catch {\n                }\n              }\n              const subIdx = tryIndexFiles(vfs2, subResolved, CJS_INDEX_FILES);\n              if (subIdx) return subIdx;\n            }\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return null;\n    }\n    function resolveImportTarget(vfs2, baseDir, value, patternMatch, context, nextResolve) {\n      const expanded = expandPattern(value, patternMatch);\n      if (!expanded.startsWith(".") && !expanded.startsWith("/")) {\n        return resolveBareSpecifier(expanded, context, nextResolve);\n      }\n      const resolved = normalizeVFSPath(joinVFSParts(baseDir, expanded));\n      if (vfs2.internalModuleStat(resolved) === 0) {\n        return makeResolveResult(vfs2, resolved);\n      }\n      return null;\n    }\n    function resolveImportConditions(vfs2, baseDir, condMap, conditions, patternMatch, context, nextResolve) {\n      const keys = Object.getOwnPropertyNames(condMap);\n      for (let i = 0; i < keys.length; i++) {\n        const key = keys[i];\n        if (key === "default" || conditions.indexOf(key) !== -1) {\n          const value = condMap[key];\n          if (typeof value === "string") {\n            const result = resolveImportTarget(vfs2, baseDir, value, patternMatch, context, nextResolve);\n            if (result) return result;\n            continue;\n          }\n          if (typeof value === "object" && value !== null && !Array.isArray(value)) {\n            const result = resolveImportConditions(vfs2, baseDir, value, conditions, patternMatch, context, nextResolve);\n            if (result) return result;\n            continue;\n          }\n        }\n      }\n      return null;\n    }\n    function resolveHashImport(specifier, context, nextResolve) {\n      if (!context.parentURL) {\n        return nextResolve(specifier, context);\n      }\n      let parentPath;\n      try {\n        parentPath = urlToPath(context.parentURL);\n      } catch {\n        return nextResolve(specifier, context);\n      }\n      const parentNorm = normalizeVFSPath(parentPath);\n      const parentVfs = findVFSForPath(parentNorm);\n      if (!parentVfs) {\n        return nextResolve(specifier, context);\n      }\n      const conditions = context.conditions || [];\n      let currentDir = dirnameVFS(parentNorm);\n      let lastDir;\n      while (currentDir !== lastDir) {\n        const pjsonPath = normalizeVFSPath(\n          joinVFSParts(currentDir, "package.json")\n        );\n        if (parentVfs.shouldHandle(pjsonPath) && parentVfs.internalModuleStat(pjsonPath) === 0) {\n          try {\n            const parsed = JSON.parse(parentVfs.readFileSync(pjsonPath, "utf8"));\n            if (parsed.imports) {\n              let target = parsed.imports[specifier];\n              let patternMatch = null;\n              if (target === void 0) {\n                const impKeys = Object.getOwnPropertyNames(parsed.imports);\n                const match = matchWildcardPattern(impKeys, specifier);\n                if (match) {\n                  patternMatch = match.patternMatch;\n                  target = parsed.imports[match.key];\n                }\n              }\n              if (target !== void 0) {\n                if (typeof target === "string") {\n                  const result = resolveImportTarget(\n                    parentVfs,\n                    currentDir,\n                    target,\n                    patternMatch,\n                    context,\n                    nextResolve\n                  );\n                  if (result) return result;\n                }\n                if (typeof target === "object" && target !== null && !Array.isArray(target)) {\n                  const result = resolveImportConditions(\n                    parentVfs,\n                    currentDir,\n                    target,\n                    conditions,\n                    patternMatch,\n                    context,\n                    nextResolve\n                  );\n                  if (result) return result;\n                }\n              }\n              break;\n            }\n          } catch {\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return nextResolve(specifier, context);\n    }\n    function resolveCJSImportTarget(vfs2, startDir, baseDir, value, patternMatch) {\n      const expanded = expandPattern(value, patternMatch);\n      if (!expanded.startsWith(".") && !expanded.startsWith("/")) {\n        const { packageName, packageSubpath } = parsePackageName(expanded);\n        return resolveCJSPackageInVFS(vfs2, startDir, packageName, packageSubpath);\n      }\n      const resolved = normalizeVFSPath(joinVFSParts(baseDir, expanded));\n      if (vfs2.internalModuleStat(resolved) === 0) return resolved;\n      return tryExtensions(vfs2, resolved, CJS_EXTENSIONS);\n    }\n    function resolveCJSImportConditions(vfs2, startDir, baseDir, condMap, patternMatch) {\n      const keys = Object.getOwnPropertyNames(condMap);\n      for (let i = 0; i < keys.length; i++) {\n        const key = keys[i];\n        if (key === "default" || CJS_CONDITIONS.indexOf(key) !== -1) {\n          const value = condMap[key];\n          if (typeof value === "string") {\n            const result = resolveCJSImportTarget(vfs2, startDir, baseDir, value, patternMatch);\n            if (result) return result;\n            continue;\n          }\n          if (typeof value === "object" && value !== null && !Array.isArray(value)) {\n            const result = resolveCJSImportConditions(vfs2, startDir, baseDir, value, patternMatch);\n            if (result) return result;\n            continue;\n          }\n        }\n      }\n      return null;\n    }\n    function resolveCJSHashImport(specifier, parentDir) {\n      const parentNorm = normalizeVFSPath(parentDir);\n      const parentVfs = findVFSForPath(parentNorm);\n      if (!parentVfs) return null;\n      let currentDir = parentNorm;\n      let lastDir;\n      while (currentDir !== lastDir) {\n        const pjsonPath = normalizeVFSPath(\n          joinVFSParts(currentDir, "package.json")\n        );\n        if (parentVfs.shouldHandle(pjsonPath) && parentVfs.internalModuleStat(pjsonPath) === 0) {\n          try {\n            const parsed = JSON.parse(parentVfs.readFileSync(pjsonPath, "utf8"));\n            if (parsed.imports) {\n              let target = parsed.imports[specifier];\n              let patternMatch = null;\n              if (target === void 0) {\n                const impKeys = Object.getOwnPropertyNames(parsed.imports);\n                const match = matchWildcardPattern(impKeys, specifier);\n                if (match) {\n                  patternMatch = match.patternMatch;\n                  target = parsed.imports[match.key];\n                }\n              }\n              if (target !== void 0) {\n                if (typeof target === "string") {\n                  return resolveCJSImportTarget(\n                    parentVfs,\n                    parentNorm,\n                    currentDir,\n                    target,\n                    patternMatch\n                  );\n                }\n                if (typeof target === "object" && target !== null && !Array.isArray(target)) {\n                  return resolveCJSImportConditions(\n                    parentVfs,\n                    parentNorm,\n                    currentDir,\n                    target,\n                    patternMatch\n                  );\n                }\n              }\n              break;\n            }\n          } catch {\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return null;\n    }\n    function resolveBareSpecifier(specifier, context, nextResolve) {\n      if (isNodeBuiltin(specifier)) {\n        return nextResolve(specifier, context);\n      }\n      if (specifier[0] === "#") {\n        return resolveHashImport(specifier, context, nextResolve);\n      }\n      if (!context.parentURL) {\n        return nextResolve(specifier, context);\n      }\n      let parentPath;\n      try {\n        parentPath = urlToPath(context.parentURL);\n      } catch {\n        return nextResolve(specifier, context);\n      }\n      const parentNorm = normalizeVFSPath(parentPath);\n      const parentVfs = findVFSForPath(parentNorm);\n      const { packageName, packageSubpath } = parsePackageName(specifier);\n      if (parentVfs) {\n        const result = resolvePackageInVFS(\n          parentVfs,\n          dirnameVFS(parentNorm),\n          packageName,\n          packageSubpath,\n          context\n        );\n        if (result) return result;\n      } else {\n        for (let i = 0; i < activeVFSList.length; i++) {\n          const vfs2 = activeVFSList[i];\n          const mp = vfs2.mountPoint;\n          if (!mp) continue;\n          const result = resolvePackageInVFS(\n            vfs2,\n            mp,\n            packageName,\n            packageSubpath,\n            context\n          );\n          if (result) return result;\n        }\n      }\n      return nextResolve(specifier, context);\n    }\n    function vfsResolveHook(specifier, context, nextResolve) {\n      if (isNodeBuiltin(specifier)) {\n        return nextResolve(specifier, context);\n      }\n      let checkPath;\n      if (specifier.startsWith("file:")) {\n        checkPath = urlToVFSPath(specifier);\n      } else if (isAbsolute(specifier)) {\n        checkPath = specifier;\n      } else if (specifier[0] === ".") {\n        if (context.parentURL) {\n          const parentPath = urlToPath(context.parentURL);\n          const parentDir = dirname(parentPath);\n          checkPath = resolve(parentDir, specifier);\n        } else {\n          return nextResolve(specifier, context);\n        }\n      } else {\n        return resolveBareSpecifier(specifier, context, nextResolve);\n      }\n      return resolveVFSPath(checkPath, context, nextResolve, specifier);\n    }\n    function vfsLoadHook(url, context, nextLoad) {\n      if (url.startsWith("node:")) {\n        return nextLoad(url, context);\n      }\n      if (!url.startsWith("file:")) {\n        return nextLoad(url, context);\n      }\n      const filePath = urlToVFSPath(url);\n      const normalized = normalizeVFSPath(filePath);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized) && vfs2.existsSync(normalized)) {\n          const statResult = vfs2.internalModuleStat(normalized);\n          if (statResult !== 0) {\n            return nextLoad(url, context);\n          }\n          try {\n            const content = vfs2.readFileSync(normalized, "utf8");\n            const format = context.format || getVFSFormat(vfs2, normalized);\n            return {\n              format,\n              source: content,\n              shortCircuit: true\n            };\n          } catch (e) {\n            if (vfs2.mounted) {\n              throw e;\n            }\n          }\n        }\n      }\n      return nextLoad(url, context);\n    }\n    function installModuleHooks() {\n      if (typeof NodeModule.registerHooks === "function") {\n        NodeModule.registerHooks({\n          resolve: vfsResolveHook,\n          load: vfsLoadHook\n        });\n      }\n      const origResolveFilename = NodeModule._resolveFilename;\n      NodeModule._resolveFilename = function(request, parent, isMain, options) {\n        if (request.startsWith("node:")) {\n          return origResolveFilename.call(this, request, parent, isMain, options);\n        }\n        let checkPath;\n        if (isAbsolute(request)) {\n          checkPath = request;\n        } else if (request[0] === ".") {\n          if (parent?.filename) {\n            checkPath = resolve(dirname(parent.filename), request);\n          }\n        }\n        if (checkPath) {\n          const normalized = normalizeVFSPath(checkPath);\n          for (let i = 0; i < activeVFSList.length; i++) {\n            const vfs2 = activeVFSList[i];\n            if (!vfs2.shouldHandle(normalized)) continue;\n            const stat = vfs2.internalModuleStat(normalized);\n            if (stat === 0) return normalized;\n            const withExt = tryExtensions(vfs2, normalized, CJS_EXTENSIONS);\n            if (withExt) return withExt;\n            if (stat === 1) {\n              const pjsonPath = normalizeVFSPath(resolve(normalized, "package.json"));\n              if (vfs2.internalModuleStat(pjsonPath) === 0) {\n                try {\n                  const parsed = JSON.parse(vfs2.readFileSync(pjsonPath, "utf8"));\n                  if (parsed.main) {\n                    const mainResult = resolveMainField(\n                      vfs2,\n                      normalized,\n                      parsed.main,\n                      CJS_EXTENSIONS,\n                      CJS_INDEX_FILES\n                    );\n                    if (mainResult) return mainResult;\n                  }\n                } catch {\n                }\n              }\n              const idxResult = tryIndexFiles(vfs2, normalized, CJS_INDEX_FILES);\n              if (idxResult) return idxResult;\n            }\n          }\n        }\n        if (request[0] === "#") {\n          const parentDir = parent?.filename ? dirname(parent.filename) : process.cwd();\n          const found = resolveCJSHashImport(request, parentDir);\n          if (found) return found;\n        }\n        if (!isAbsolute(request) && request[0] !== "." && request[0] !== "#" && !isNodeBuiltin(request)) {\n          const parentDir = parent?.filename ? dirname(parent.filename) : process.cwd();\n          const parentNorm = normalizeVFSPath(parentDir);\n          const { packageName, packageSubpath } = parsePackageName(request);\n          let matched = false;\n          for (let i = 0; i < activeVFSList.length; i++) {\n            const vfs2 = activeVFSList[i];\n            if (!vfs2.shouldHandle(parentNorm)) continue;\n            matched = true;\n            const found = resolveCJSPackageInVFS(\n              vfs2,\n              parentNorm,\n              packageName,\n              packageSubpath\n            );\n            if (found) return found;\n          }\n          if (!matched) {\n            for (let i = 0; i < activeVFSList.length; i++) {\n              const vfs2 = activeVFSList[i];\n              const mp = vfs2.mountPoint;\n              if (!mp) continue;\n              const found = resolveCJSPackageInVFS(\n                vfs2,\n                mp,\n                packageName,\n                packageSubpath\n              );\n              if (found) return found;\n            }\n          }\n        }\n        return origResolveFilename.call(this, request, parent, isMain, options);\n      };\n      const origJsHandler = NodeModule._extensions[".js"];\n      NodeModule._extensions[".js"] = function(module3, filename) {\n        const normalized = normalizeVFSPath(filename);\n        for (let i = 0; i < activeVFSList.length; i++) {\n          const vfs2 = activeVFSList[i];\n          if (vfs2.shouldHandle(normalized) && vfs2.existsSync(normalized)) {\n            const content = vfs2.readFileSync(normalized, "utf8");\n            module3._compile(content, filename);\n            return;\n          }\n        }\n        return origJsHandler.call(this, module3, filename);\n      };\n      const origJsonHandler = NodeModule._extensions[".json"];\n      NodeModule._extensions[".json"] = function(module3, filename) {\n        const normalized = normalizeVFSPath(filename);\n        for (let i = 0; i < activeVFSList.length; i++) {\n          const vfs2 = activeVFSList[i];\n          if (vfs2.shouldHandle(normalized) && vfs2.existsSync(normalized)) {\n            const content = vfs2.readFileSync(normalized, "utf8");\n            module3.exports = JSON.parse(content);\n            return;\n          }\n        }\n        return origJsonHandler.call(this, module3, filename);\n      };\n    }\n    function installFsPatches() {\n      const fs = require("node:fs");\n      originalReadFileSync = fs.readFileSync;\n      originalRealpathSync = fs.realpathSync;\n      originalLstatSync = fs.lstatSync;\n      originalStatSync = fs.statSync;\n      fs.readFileSync = function readFileSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRead(path2, options);\n          if (vfsResult !== null) {\n            return vfsResult.content;\n          }\n        }\n        return originalReadFileSync.call(fs, path2, options);\n      };\n      fs.realpathSync = function realpathSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRealpath(path2);\n          if (vfsResult !== null) {\n            return vfsResult.realpath;\n          }\n        }\n        return originalRealpathSync.call(fs, path2, options);\n      };\n      if (originalRealpathSync.native) {\n        fs.realpathSync.native = originalRealpathSync.native;\n      }\n      fs.lstatSync = function lstatSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForFsStat(path2);\n          if (vfsResult !== null) {\n            return vfsResult.stats;\n          }\n        }\n        return originalLstatSync.call(fs, path2, options);\n      };\n      fs.statSync = function statSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForFsStat(path2);\n          if (vfsResult !== null) {\n            return vfsResult.stats;\n          }\n        }\n        return originalStatSync.call(fs, path2, options);\n      };\n      originalReaddirSync = fs.readdirSync;\n      fs.readdirSync = function readdirSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForReaddir(path2, options);\n          if (vfsResult !== null) {\n            return vfsResult.entries;\n          }\n        }\n        return originalReaddirSync.call(fs, path2, options);\n      };\n      originalExistsSync = fs.existsSync;\n      fs.existsSync = function existsSync(path2) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForExists(path2);\n          if (vfsResult !== null) {\n            return vfsResult.exists;\n          }\n        }\n        return originalExistsSync.call(fs, path2);\n      };\n      const originalReadlinkSync = fs.readlinkSync;\n      fs.readlinkSync = function readlinkSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRealpath(path2);\n          if (vfsResult !== null) {\n            return vfsResult.realpath;\n          }\n        }\n        return originalReadlinkSync.call(fs, path2, options);\n      };\n      const originalAccessSync = fs.accessSync;\n      fs.accessSync = function accessSync(path2, mode) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForExists(path2);\n          if (vfsResult !== null) {\n            if (!vfsResult.exists) {\n              throw createENOENT("access", path2);\n            }\n            return;\n          }\n        }\n        return originalAccessSync.call(fs, path2, mode);\n      };\n      const originalAccess = fs.access;\n      fs.access = function access(path2, mode, callback) {\n        if (typeof mode === "function") {\n          callback = mode;\n          mode = fs.constants.F_OK;\n        }\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForExists(path2);\n          if (vfsResult !== null) {\n            const err = vfsResult.exists ? null : createENOENT("access", path2);\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalAccess.call(fs, path2, mode, callback);\n      };\n      const originalStat = fs.stat;\n      fs.stat = function stat(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForFsStat(path2);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.stats);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalStat.call(fs, path2, options, callback);\n      };\n      const originalLstat = fs.lstat;\n      fs.lstat = function lstat(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForFsStat(path2);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.stats);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalLstat.call(fs, path2, options, callback);\n      };\n      const originalReadFile = fs.readFile;\n      fs.readFile = function readFile(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForRead(path2, options);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.content);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalReadFile.call(fs, path2, options, callback);\n      };\n      const originalCreateReadStream = fs.createReadStream;\n      fs.createReadStream = function createReadStream(path2, options) {\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForRead(path2, options);\n            if (vfsResult !== null) {\n              const { Readable } = require("node:stream");\n              const stream = new Readable({ read() {\n              } });\n              stream.push(vfsResult.content);\n              stream.push(null);\n              return stream;\n            }\n          } catch (err) {\n            const { Readable } = require("node:stream");\n            const stream = new Readable({ read() {\n            } });\n            process.nextTick(() => stream.destroy(err));\n            return stream;\n          }\n        }\n        return originalCreateReadStream.call(fs, path2, options);\n      };\n      const originalReaddir = fs.readdir;\n      fs.readdir = function readdir(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForReaddir(path2, options);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.entries);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalReaddir.call(fs, path2, options, callback);\n      };\n      const originalReadlink = fs.readlink;\n      fs.readlink = function readlink(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForRealpath(path2);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.realpath);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalReadlink.call(fs, path2, options, callback);\n      };\n      const originalRealpath = fs.realpath;\n      fs.realpath = function realpath(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForRealpath(path2);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.realpath);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalRealpath.call(fs, path2, options, callback);\n      };\n      if (originalRealpath.native) {\n        fs.realpath.native = originalRealpath.native;\n      }\n      const origPAccess = fs.promises.access;\n      fs.promises.access = async function access(path2, mode) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForExists(path2);\n          if (vfsResult !== null) {\n            if (!vfsResult.exists) {\n              throw createENOENT("access", path2);\n            }\n            return;\n          }\n        }\n        return origPAccess.call(fs.promises, path2, mode);\n      };\n      const origPReadFile = fs.promises.readFile;\n      fs.promises.readFile = async function readFile(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRead(path2, options);\n          if (vfsResult !== null) {\n            return vfsResult.content;\n          }\n        }\n        return origPReadFile.call(fs.promises, path2, options);\n      };\n      const origPStat = fs.promises.stat;\n      fs.promises.stat = async function stat(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForFsStat(path2);\n          if (vfsResult !== null) {\n            return vfsResult.stats;\n          }\n        }\n        return origPStat.call(fs.promises, path2, options);\n      };\n      const origPLstat = fs.promises.lstat;\n      fs.promises.lstat = async function lstat(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForFsStat(path2);\n          if (vfsResult !== null) {\n            return vfsResult.stats;\n          }\n        }\n        return origPLstat.call(fs.promises, path2, options);\n      };\n      const origPReaddir = fs.promises.readdir;\n      fs.promises.readdir = async function readdir(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForReaddir(path2, options);\n          if (vfsResult !== null) {\n            return vfsResult.entries;\n          }\n        }\n        return origPReaddir.call(fs.promises, path2, options);\n      };\n      const origPReadlink = fs.promises.readlink;\n      fs.promises.readlink = async function readlink(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRealpath(path2);\n          if (vfsResult !== null) {\n            return vfsResult.realpath;\n          }\n        }\n        return origPReadlink.call(fs.promises, path2, options);\n      };\n      const origPRealpath = fs.promises.realpath;\n      fs.promises.realpath = async function realpath(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRealpath(path2);\n          if (vfsResult !== null) {\n            return vfsResult.realpath;\n          }\n        }\n        return origPRealpath.call(fs.promises, path2, options);\n      };\n      originalWatch = fs.watch;\n      fs.watch = function watch(filename, options, listener) {\n        if (typeof options === "function") {\n          listener = options;\n          options = kEmptyObject;\n        } else options ??= kEmptyObject;\n        if (typeof filename === "string") {\n          const vfsResult = findVFSForWatch(filename);\n          if (vfsResult !== null) {\n            return vfsResult.vfs.watch(filename, options, listener);\n          }\n        }\n        return originalWatch.call(fs, filename, options, listener);\n      };\n      originalWatchFile = fs.watchFile;\n      fs.watchFile = function watchFile(filename, options, listener) {\n        if (typeof options === "function") {\n          listener = options;\n          options = kEmptyObject;\n        } else options ??= kEmptyObject;\n        if (typeof filename === "string") {\n          const vfsResult = findVFSForWatch(filename);\n          if (vfsResult !== null) {\n            return vfsResult.vfs.watchFile(filename, options, listener);\n          }\n        }\n        return originalWatchFile.call(fs, filename, options, listener);\n      };\n      originalUnwatchFile = fs.unwatchFile;\n      fs.unwatchFile = function unwatchFile(filename, listener) {\n        if (typeof filename === "string") {\n          const vfsResult = findVFSForWatch(filename);\n          if (vfsResult !== null) {\n            vfsResult.vfs.unwatchFile(filename, listener);\n            return;\n          }\n        }\n        return originalUnwatchFile.call(fs, filename, listener);\n      };\n    }\n    function installHooks() {\n      if (hooksInstalled) {\n        return;\n      }\n      installModuleHooks();\n      installFsPatches();\n      hooksInstalled = true;\n    }\n    module2.exports = {\n      registerVFS,\n      deregisterVFS,\n      findVFSForStat,\n      findVFSForRead\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/file_system.js\nvar require_file_system = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/file_system.js"(exports2, module2) {\n    "use strict";\n    var path = require("node:path");\n    var pathPosix = path.posix;\n    var { isAbsolute, resolve: resolvePath } = path;\n    var { MemoryProvider } = require_memory();\n    var {\n      isUnderMountPoint,\n      getRelativePath\n    } = require_router();\n    var {\n      openVirtualFd,\n      getVirtualFd,\n      closeVirtualFd\n    } = require_fd();\n    var {\n      createENOENT,\n      createENOTDIR,\n      createEBADF,\n      ERR_INVALID_STATE\n    } = require_errors();\n    var { VirtualReadStream } = require_streams();\n    var kEmptyObject = Object.freeze(/* @__PURE__ */ Object.create(null));\n    function normalizeVFSPath(inputPath) {\n      if (inputPath.startsWith("/")) {\n        return pathPosix.normalize(inputPath);\n      }\n      return path.normalize(inputPath);\n    }\n    function joinVFSPath(base, part) {\n      if (base.startsWith("/")) {\n        return pathPosix.join(base, part);\n      }\n      return path.join(base, part);\n    }\n    var kProvider = /* @__PURE__ */ Symbol("kProvider");\n    var kMountPoint = /* @__PURE__ */ Symbol("kMountPoint");\n    var kMounted = /* @__PURE__ */ Symbol("kMounted");\n    var kOverlay = /* @__PURE__ */ Symbol("kOverlay");\n    var kModuleHooks = /* @__PURE__ */ Symbol("kModuleHooks");\n    var kPromises = /* @__PURE__ */ Symbol("kPromises");\n    var kVirtualCwd = /* @__PURE__ */ Symbol("kVirtualCwd");\n    var kVirtualCwdEnabled = /* @__PURE__ */ Symbol("kVirtualCwdEnabled");\n    var kOriginalChdir = /* @__PURE__ */ Symbol("kOriginalChdir");\n    var kOriginalCwd = /* @__PURE__ */ Symbol("kOriginalCwd");\n    var registerVFS;\n    var deregisterVFS;\n    function loadModuleHooks() {\n      if (!registerVFS) {\n        const hooks = require_module_hooks();\n        registerVFS = hooks.registerVFS;\n        deregisterVFS = hooks.deregisterVFS;\n      }\n    }\n    var VirtualFileSystem = class {\n      constructor(providerOrOptions, options = kEmptyObject) {\n        let provider = null;\n        if (providerOrOptions !== void 0 && providerOrOptions !== null) {\n          if (typeof providerOrOptions.openSync === "function") {\n            provider = providerOrOptions;\n          } else if (typeof providerOrOptions === "object") {\n            options = providerOrOptions;\n            provider = null;\n          }\n        }\n        if (options.moduleHooks !== void 0 && typeof options.moduleHooks !== "boolean") {\n          throw new TypeError("options.moduleHooks must be a boolean");\n        }\n        if (options.virtualCwd !== void 0 && typeof options.virtualCwd !== "boolean") {\n          throw new TypeError("options.virtualCwd must be a boolean");\n        }\n        if (options.overlay !== void 0 && typeof options.overlay !== "boolean") {\n          throw new TypeError("options.overlay must be a boolean");\n        }\n        this[kProvider] = provider ?? new MemoryProvider();\n        this[kMountPoint] = null;\n        this[kMounted] = false;\n        this[kOverlay] = options.overlay === true;\n        this[kModuleHooks] = options.moduleHooks !== false;\n        this[kPromises] = null;\n        this[kVirtualCwdEnabled] = options.virtualCwd === true;\n        this[kVirtualCwd] = null;\n        this[kOriginalChdir] = null;\n        this[kOriginalCwd] = null;\n      }\n      get provider() {\n        return this[kProvider];\n      }\n      get mountPoint() {\n        return this[kMountPoint];\n      }\n      get mounted() {\n        return this[kMounted];\n      }\n      get readonly() {\n        return this[kProvider].readonly;\n      }\n      get overlay() {\n        return this[kOverlay];\n      }\n      get virtualCwdEnabled() {\n        return this[kVirtualCwdEnabled];\n      }\n      // ==================== Virtual Working Directory ====================\n      cwd() {\n        if (!this[kVirtualCwdEnabled]) {\n          throw new ERR_INVALID_STATE("virtual cwd is not enabled");\n        }\n        return this[kVirtualCwd];\n      }\n      chdir(dirPath) {\n        if (!this[kVirtualCwdEnabled]) {\n          throw new ERR_INVALID_STATE("virtual cwd is not enabled");\n        }\n        const providerPath = this.#toProviderPath(dirPath);\n        const stats = this[kProvider].statSync(providerPath);\n        if (!stats.isDirectory()) {\n          throw createENOTDIR("chdir", dirPath);\n        }\n        this[kVirtualCwd] = this.#toMountedPath(providerPath);\n      }\n      resolvePath(inputPath) {\n        if (isAbsolute(inputPath)) {\n          return normalizeVFSPath(inputPath);\n        }\n        if (this[kVirtualCwdEnabled] && this[kVirtualCwd] !== null) {\n          const resolved = `${this[kVirtualCwd]}/${inputPath}`;\n          return normalizeVFSPath(resolved);\n        }\n        return resolvePath(inputPath);\n      }\n      // ==================== Mount ====================\n      mount(prefix) {\n        if (this[kMounted]) {\n          throw new ERR_INVALID_STATE("VFS is already mounted");\n        }\n        this[kMountPoint] = normalizeVFSPath(prefix);\n        this[kMounted] = true;\n        if (this[kModuleHooks]) {\n          loadModuleHooks();\n          registerVFS(this);\n        }\n        if (this[kVirtualCwdEnabled]) {\n          this.#hookProcessCwd();\n        }\n        process.emit("vfs-mount", {\n          mountPoint: this[kMountPoint],\n          overlay: this[kOverlay],\n          readonly: this[kProvider].readonly\n        });\n        return this;\n      }\n      unmount() {\n        if (this[kMounted]) {\n          process.emit("vfs-unmount", {\n            mountPoint: this[kMountPoint],\n            overlay: this[kOverlay],\n            readonly: this[kProvider].readonly\n          });\n        }\n        this.#unhookProcessCwd();\n        if (this[kModuleHooks]) {\n          loadModuleHooks();\n          deregisterVFS(this);\n        }\n        this[kMountPoint] = null;\n        this[kMounted] = false;\n        this[kVirtualCwd] = null;\n      }\n      [Symbol.dispose]() {\n        if (this[kMounted]) {\n          this.unmount();\n        }\n      }\n      #hookProcessCwd() {\n        if (this[kOriginalChdir] !== null) {\n          return;\n        }\n        const vfs2 = this;\n        this[kOriginalChdir] = process.chdir;\n        this[kOriginalCwd] = process.cwd;\n        process.chdir = function chdir(directory) {\n          const normalized = isAbsolute(directory) ? normalizeVFSPath(directory) : resolvePath(directory);\n          if (vfs2.shouldHandle(normalized)) {\n            vfs2.chdir(normalized);\n            return;\n          }\n          return vfs2[kOriginalChdir].call(process, directory);\n        };\n        process.cwd = function cwd() {\n          if (vfs2[kVirtualCwd] !== null) {\n            return vfs2[kVirtualCwd];\n          }\n          return vfs2[kOriginalCwd].call(process);\n        };\n      }\n      #unhookProcessCwd() {\n        if (this[kOriginalChdir] === null) {\n          return;\n        }\n        process.chdir = this[kOriginalChdir];\n        process.cwd = this[kOriginalCwd];\n        this[kOriginalChdir] = null;\n        this[kOriginalCwd] = null;\n      }\n      // ==================== Path Resolution ====================\n      #toProviderPath(inputPath) {\n        const resolved = this.resolvePath(inputPath);\n        if (this[kMounted] && this[kMountPoint]) {\n          if (!isUnderMountPoint(resolved, this[kMountPoint])) {\n            throw createENOENT("open", inputPath);\n          }\n          return getRelativePath(resolved, this[kMountPoint]);\n        }\n        return resolved;\n      }\n      #toMountedPath(providerPath) {\n        if (this[kMounted] && this[kMountPoint]) {\n          return joinVFSPath(this[kMountPoint], providerPath);\n        }\n        return providerPath;\n      }\n      shouldHandle(inputPath) {\n        if (!this[kMounted] || !this[kMountPoint]) {\n          return false;\n        }\n        const normalized = normalizeVFSPath(inputPath);\n        if (!isUnderMountPoint(normalized, this[kMountPoint])) {\n          return false;\n        }\n        if (this[kOverlay]) {\n          try {\n            const providerPath = getRelativePath(normalized, this[kMountPoint]);\n            return this[kProvider].existsSync(providerPath);\n          } catch {\n            return false;\n          }\n        }\n        return true;\n      }\n      // ==================== FS Operations (Sync) ====================\n      existsSync(filePath) {\n        try {\n          const providerPath = this.#toProviderPath(filePath);\n          return this[kProvider].existsSync(providerPath);\n        } catch {\n          return false;\n        }\n      }\n      statSync(filePath, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        return this[kProvider].statSync(providerPath, options);\n      }\n      lstatSync(filePath, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        return this[kProvider].lstatSync(providerPath, options);\n      }\n      readFileSync(filePath, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        return this[kProvider].readFileSync(providerPath, options);\n      }\n      writeFileSync(filePath, data, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].writeFileSync(providerPath, data, options);\n      }\n      appendFileSync(filePath, data, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].appendFileSync(providerPath, data, options);\n      }\n      readdirSync(dirPath, options) {\n        const providerPath = this.#toProviderPath(dirPath);\n        return this[kProvider].readdirSync(providerPath, options);\n      }\n      mkdirSync(dirPath, options) {\n        const providerPath = this.#toProviderPath(dirPath);\n        const result = this[kProvider].mkdirSync(providerPath, options);\n        if (result !== void 0) {\n          return this.#toMountedPath(result);\n        }\n        return void 0;\n      }\n      rmdirSync(dirPath) {\n        const providerPath = this.#toProviderPath(dirPath);\n        this[kProvider].rmdirSync(providerPath);\n      }\n      unlinkSync(filePath) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].unlinkSync(providerPath);\n      }\n      renameSync(oldPath, newPath) {\n        const oldProviderPath = this.#toProviderPath(oldPath);\n        const newProviderPath = this.#toProviderPath(newPath);\n        this[kProvider].renameSync(oldProviderPath, newProviderPath);\n      }\n      copyFileSync(src, dest, mode) {\n        const srcProviderPath = this.#toProviderPath(src);\n        const destProviderPath = this.#toProviderPath(dest);\n        this[kProvider].copyFileSync(srcProviderPath, destProviderPath, mode);\n      }\n      realpathSync(filePath, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        const realProviderPath = this[kProvider].realpathSync(providerPath, options);\n        return this.#toMountedPath(realProviderPath);\n      }\n      readlinkSync(linkPath, options) {\n        const providerPath = this.#toProviderPath(linkPath);\n        return this[kProvider].readlinkSync(providerPath, options);\n      }\n      symlinkSync(target, path2, type) {\n        const providerPath = this.#toProviderPath(path2);\n        this[kProvider].symlinkSync(target, providerPath, type);\n      }\n      accessSync(filePath, mode) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].accessSync(providerPath, mode);\n      }\n      internalModuleStat(filePath) {\n        try {\n          const providerPath = this.#toProviderPath(filePath);\n          return this[kProvider].internalModuleStat(providerPath);\n        } catch {\n          return -2;\n        }\n      }\n      // ==================== File Descriptor Operations ====================\n      openSync(filePath, flags = "r", mode) {\n        const providerPath = this.#toProviderPath(filePath);\n        const handle = this[kProvider].openSync(providerPath, flags, mode);\n        return openVirtualFd(handle);\n      }\n      closeSync(fd) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          throw createEBADF("close");\n        }\n        vfd.entry.closeSync();\n        closeVirtualFd(fd);\n      }\n      readSync(fd, buffer, offset, length, position) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          throw createEBADF("read");\n        }\n        return vfd.entry.readSync(buffer, offset, length, position);\n      }\n      fstatSync(fd, options) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          throw createEBADF("fstat");\n        }\n        return vfd.entry.statSync(options);\n      }\n      // ==================== FS Operations (Async with Callbacks) ====================\n      readFile(filePath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].readFile(this.#toProviderPath(filePath), options).then((data) => callback(null, data), (err) => callback(err));\n      }\n      writeFile(filePath, data, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].writeFile(this.#toProviderPath(filePath), data, options).then(() => callback(null), (err) => callback(err));\n      }\n      stat(filePath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].stat(this.#toProviderPath(filePath), options).then((stats) => callback(null, stats), (err) => callback(err));\n      }\n      lstat(filePath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].lstat(this.#toProviderPath(filePath), options).then((stats) => callback(null, stats), (err) => callback(err));\n      }\n      readdir(dirPath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].readdir(this.#toProviderPath(dirPath), options).then((entries) => callback(null, entries), (err) => callback(err));\n      }\n      realpath(filePath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].realpath(this.#toProviderPath(filePath), options).then((realPath) => callback(null, this.#toMountedPath(realPath)), (err) => callback(err));\n      }\n      readlink(linkPath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].readlink(this.#toProviderPath(linkPath), options).then((target) => callback(null, target), (err) => callback(err));\n      }\n      access(filePath, mode, callback) {\n        if (typeof mode === "function") {\n          callback = mode;\n          mode = void 0;\n        }\n        this[kProvider].access(this.#toProviderPath(filePath), mode).then(() => callback(null), (err) => callback(err));\n      }\n      open(filePath, flags, mode, callback) {\n        if (typeof flags === "function") {\n          callback = flags;\n          flags = "r";\n          mode = void 0;\n        } else if (typeof mode === "function") {\n          callback = mode;\n          mode = void 0;\n        }\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].open(providerPath, flags, mode).then((handle) => {\n          const fd = openVirtualFd(handle);\n          callback(null, fd);\n        }, (err) => callback(err));\n      }\n      close(fd, callback) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          process.nextTick(callback, createEBADF("close"));\n          return;\n        }\n        vfd.entry.close().then(() => {\n          closeVirtualFd(fd);\n          callback(null);\n        }, (err) => callback(err));\n      }\n      read(fd, buffer, offset, length, position, callback) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          process.nextTick(callback, createEBADF("read"));\n          return;\n        }\n        vfd.entry.read(buffer, offset, length, position).then(({ bytesRead }) => callback(null, bytesRead, buffer), (err) => callback(err));\n      }\n      fstat(fd, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          process.nextTick(callback, createEBADF("fstat"));\n          return;\n        }\n        vfd.entry.stat(options).then((stats) => callback(null, stats), (err) => callback(err));\n      }\n      // ==================== Stream Operations ====================\n      createReadStream(filePath, options) {\n        return new VirtualReadStream(this, filePath, options);\n      }\n      // ==================== Watch Operations ====================\n      watch(filePath, options, listener) {\n        if (typeof options === "function") {\n          listener = options;\n          options = {};\n        }\n        const providerPath = this.#toProviderPath(filePath);\n        const watcher = this[kProvider].watch(providerPath, options);\n        if (listener) {\n          watcher.on("change", listener);\n        }\n        return watcher;\n      }\n      watchFile(filePath, options, listener) {\n        if (typeof options === "function") {\n          listener = options;\n          options = {};\n        }\n        const providerPath = this.#toProviderPath(filePath);\n        return this[kProvider].watchFile(providerPath, options, listener);\n      }\n      unwatchFile(filePath, listener) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].unwatchFile(providerPath, listener);\n      }\n      // ==================== Promise API ====================\n      get promises() {\n        if (this[kPromises] === null) {\n          this[kPromises] = this.#createPromisesAPI();\n        }\n        return this[kPromises];\n      }\n      #createPromisesAPI() {\n        const provider = this[kProvider];\n        const toProviderPath = (p) => this.#toProviderPath(p);\n        const toMountedPath = (p) => this.#toMountedPath(p);\n        return Object.freeze({\n          async readFile(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.readFile(providerPath, options);\n          },\n          async writeFile(filePath, data, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.writeFile(providerPath, data, options);\n          },\n          async appendFile(filePath, data, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.appendFile(providerPath, data, options);\n          },\n          async stat(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.stat(providerPath, options);\n          },\n          async lstat(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.lstat(providerPath, options);\n          },\n          async readdir(dirPath, options) {\n            const providerPath = toProviderPath(dirPath);\n            return provider.readdir(providerPath, options);\n          },\n          async mkdir(dirPath, options) {\n            const providerPath = toProviderPath(dirPath);\n            const result = await provider.mkdir(providerPath, options);\n            if (result !== void 0) {\n              return toMountedPath(result);\n            }\n            return void 0;\n          },\n          async rmdir(dirPath) {\n            const providerPath = toProviderPath(dirPath);\n            return provider.rmdir(providerPath);\n          },\n          async unlink(filePath) {\n            const providerPath = toProviderPath(filePath);\n            return provider.unlink(providerPath);\n          },\n          async rename(oldPath, newPath) {\n            const oldProviderPath = toProviderPath(oldPath);\n            const newProviderPath = toProviderPath(newPath);\n            return provider.rename(oldProviderPath, newProviderPath);\n          },\n          async copyFile(src, dest, mode) {\n            const srcProviderPath = toProviderPath(src);\n            const destProviderPath = toProviderPath(dest);\n            return provider.copyFile(srcProviderPath, destProviderPath, mode);\n          },\n          async realpath(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            const realPath = await provider.realpath(providerPath, options);\n            return toMountedPath(realPath);\n          },\n          async readlink(linkPath, options) {\n            const providerPath = toProviderPath(linkPath);\n            return provider.readlink(providerPath, options);\n          },\n          async symlink(target, path2, type) {\n            const providerPath = toProviderPath(path2);\n            return provider.symlink(target, providerPath, type);\n          },\n          async access(filePath, mode) {\n            const providerPath = toProviderPath(filePath);\n            return provider.access(providerPath, mode);\n          },\n          watch(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.watchAsync(providerPath, options);\n          }\n        });\n      }\n    };\n    module2.exports = {\n      VirtualFileSystem\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/providers/real.js\nvar require_real = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/providers/real.js"(exports2, module2) {\n    "use strict";\n    var fs = require("node:fs");\n    var path = require("node:path");\n    var { VirtualProvider } = require_provider();\n    var { VirtualFileHandle } = require_file_handle();\n    var {\n      createEBADF,\n      createENOENT,\n      ERR_INVALID_ARG_VALUE\n    } = require_errors();\n    var RealFileHandle = class extends VirtualFileHandle {\n      #fd;\n      #realPath;\n      #checkClosed() {\n        if (this.closed) {\n          throw createEBADF("read");\n        }\n      }\n      constructor(path2, flags, mode, fd, realPath) {\n        super(path2, flags, mode);\n        this.#fd = fd;\n        this.#realPath = realPath;\n      }\n      get fd() {\n        return this.#fd;\n      }\n      readSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        return fs.readSync(this.#fd, buffer, offset, length, position);\n      }\n      async read(buffer, offset, length, position) {\n        this.#checkClosed();\n        return new Promise((resolve, reject) => {\n          fs.read(this.#fd, buffer, offset, length, position, (err, bytesRead) => {\n            if (err) reject(err);\n            else resolve({ bytesRead, buffer });\n          });\n        });\n      }\n      writeSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        return fs.writeSync(this.#fd, buffer, offset, length, position);\n      }\n      async write(buffer, offset, length, position) {\n        this.#checkClosed();\n        return new Promise((resolve, reject) => {\n          fs.write(this.#fd, buffer, offset, length, position, (err, bytesWritten) => {\n            if (err) reject(err);\n            else resolve({ bytesWritten, buffer });\n          });\n        });\n      }\n      readFileSync(options) {\n        this.#checkClosed();\n        return fs.readFileSync(this.#realPath, options);\n      }\n      async readFile(options) {\n        this.#checkClosed();\n        return fs.promises.readFile(this.#realPath, options);\n      }\n      writeFileSync(data, options) {\n        this.#checkClosed();\n        fs.writeFileSync(this.#realPath, data, options);\n      }\n      async writeFile(data, options) {\n        this.#checkClosed();\n        return fs.promises.writeFile(this.#realPath, data, options);\n      }\n      statSync(options) {\n        this.#checkClosed();\n        return fs.fstatSync(this.#fd, options);\n      }\n      async stat(options) {\n        this.#checkClosed();\n        return new Promise((resolve, reject) => {\n          fs.fstat(this.#fd, options, (err, stats) => {\n            if (err) reject(err);\n            else resolve(stats);\n          });\n        });\n      }\n      truncateSync(len = 0) {\n        this.#checkClosed();\n        fs.ftruncateSync(this.#fd, len);\n      }\n      async truncate(len = 0) {\n        this.#checkClosed();\n        return new Promise((resolve, reject) => {\n          fs.ftruncate(this.#fd, len, (err) => {\n            if (err) reject(err);\n            else resolve();\n          });\n        });\n      }\n      closeSync() {\n        if (!this.closed) {\n          fs.closeSync(this.#fd);\n          super.closeSync();\n        }\n      }\n      async close() {\n        if (!this.closed) {\n          return new Promise((resolve, reject) => {\n            fs.close(this.#fd, (err) => {\n              if (err) reject(err);\n              else {\n                super.closeSync();\n                resolve();\n              }\n            });\n          });\n        }\n      }\n    };\n    var RealFSProvider = class extends VirtualProvider {\n      #rootPath;\n      constructor(rootPath) {\n        super();\n        if (typeof rootPath !== "string" || rootPath === "") {\n          throw new ERR_INVALID_ARG_VALUE("rootPath", rootPath, "must be a non-empty string");\n        }\n        this.#rootPath = path.resolve(rootPath);\n      }\n      get rootPath() {\n        return this.#rootPath;\n      }\n      get readonly() {\n        return false;\n      }\n      get supportsSymlinks() {\n        return true;\n      }\n      #resolvePath(vfsPath) {\n        let normalized = vfsPath;\n        if (normalized.startsWith("/")) {\n          normalized = normalized.slice(1);\n        }\n        const realPath = path.resolve(this.#rootPath, normalized);\n        const rootWithSep = this.#rootPath.endsWith(path.sep) ? this.#rootPath : this.#rootPath + path.sep;\n        if (realPath !== this.#rootPath && !realPath.startsWith(rootWithSep)) {\n          throw createENOENT("open", vfsPath);\n        }\n        return realPath;\n      }\n      openSync(vfsPath, flags, mode) {\n        const realPath = this.#resolvePath(vfsPath);\n        const fd = fs.openSync(realPath, flags, mode);\n        return new RealFileHandle(vfsPath, flags, mode ?? 420, fd, realPath);\n      }\n      async open(vfsPath, flags, mode) {\n        const realPath = this.#resolvePath(vfsPath);\n        return new Promise((resolve, reject) => {\n          fs.open(realPath, flags, mode, (err, fd) => {\n            if (err) reject(err);\n            else resolve(new RealFileHandle(vfsPath, flags, mode ?? 420, fd, realPath));\n          });\n        });\n      }\n      statSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.statSync(realPath, options);\n      }\n      async stat(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.stat(realPath, options);\n      }\n      lstatSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.lstatSync(realPath, options);\n      }\n      async lstat(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.lstat(realPath, options);\n      }\n      readdirSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.readdirSync(realPath, options);\n      }\n      async readdir(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.readdir(realPath, options);\n      }\n      mkdirSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.mkdirSync(realPath, options);\n      }\n      async mkdir(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.mkdir(realPath, options);\n      }\n      rmdirSync(vfsPath) {\n        const realPath = this.#resolvePath(vfsPath);\n        fs.rmdirSync(realPath);\n      }\n      async rmdir(vfsPath) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.rmdir(realPath);\n      }\n      unlinkSync(vfsPath) {\n        const realPath = this.#resolvePath(vfsPath);\n        fs.unlinkSync(realPath);\n      }\n      async unlink(vfsPath) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.unlink(realPath);\n      }\n      renameSync(oldVfsPath, newVfsPath) {\n        const oldRealPath = this.#resolvePath(oldVfsPath);\n        const newRealPath = this.#resolvePath(newVfsPath);\n        fs.renameSync(oldRealPath, newRealPath);\n      }\n      async rename(oldVfsPath, newVfsPath) {\n        const oldRealPath = this.#resolvePath(oldVfsPath);\n        const newRealPath = this.#resolvePath(newVfsPath);\n        return fs.promises.rename(oldRealPath, newRealPath);\n      }\n      readlinkSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.readlinkSync(realPath, options);\n      }\n      async readlink(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.readlink(realPath, options);\n      }\n      symlinkSync(target, vfsPath, type) {\n        const realPath = this.#resolvePath(vfsPath);\n        fs.symlinkSync(target, realPath, type);\n      }\n      async symlink(target, vfsPath, type) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.symlink(target, realPath, type);\n      }\n      realpathSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        const resolved = fs.realpathSync(realPath, options);\n        if (resolved === this.#rootPath) {\n          return "/";\n        }\n        const rootWithSep = this.#rootPath + path.sep;\n        if (resolved.startsWith(rootWithSep)) {\n          return "/" + resolved.slice(rootWithSep.length).replace(/\\\\/g, "/");\n        }\n        return vfsPath;\n      }\n      async realpath(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        const resolved = await fs.promises.realpath(realPath, options);\n        if (resolved === this.#rootPath) {\n          return "/";\n        }\n        const rootWithSep = this.#rootPath + path.sep;\n        if (resolved.startsWith(rootWithSep)) {\n          return "/" + resolved.slice(rootWithSep.length).replace(/\\\\/g, "/");\n        }\n        return vfsPath;\n      }\n      accessSync(vfsPath, mode) {\n        const realPath = this.#resolvePath(vfsPath);\n        fs.accessSync(realPath, mode);\n      }\n      async access(vfsPath, mode) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.access(realPath, mode);\n      }\n      copyFileSync(srcVfsPath, destVfsPath, mode) {\n        const srcRealPath = this.#resolvePath(srcVfsPath);\n        const destRealPath = this.#resolvePath(destVfsPath);\n        fs.copyFileSync(srcRealPath, destRealPath, mode);\n      }\n      async copyFile(srcVfsPath, destVfsPath, mode) {\n        const srcRealPath = this.#resolvePath(srcVfsPath);\n        const destRealPath = this.#resolvePath(destVfsPath);\n        return fs.promises.copyFile(srcRealPath, destRealPath, mode);\n      }\n    };\n    module2.exports = {\n      RealFSProvider,\n      RealFileHandle\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/providers/sqlite.js\nvar require_sqlite = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/providers/sqlite.js"(exports2, module2) {\n    "use strict";\n    var { Buffer: Buffer2 } = require("node:buffer");\n    var { posix: pathPosix } = require("node:path");\n    var { DatabaseSync } = require("node:sqlite");\n    var { VirtualProvider } = require_provider();\n    var { VirtualFileHandle } = require_file_handle();\n    var {\n      VFSWatcher,\n      VFSStatWatcher,\n      VFSWatchAsyncIterable\n    } = require_watcher();\n    var {\n      createENOENT,\n      createENOTDIR,\n      createENOTEMPTY,\n      createEISDIR,\n      createEEXIST,\n      createEINVAL,\n      createELOOP,\n      createEROFS\n    } = require_errors();\n    var {\n      createFileStats,\n      createDirectoryStats,\n      createSymlinkStats\n    } = require_stats();\n    var UV_DIRENT_FILE = 1;\n    var UV_DIRENT_DIR = 2;\n    var UV_DIRENT_LINK = 3;\n    var VirtualDirent = class {\n      #name;\n      #type;\n      #parentPath;\n      constructor(name, type, parentPath) {\n        this.#name = name;\n        this.#type = type;\n        this.#parentPath = parentPath;\n      }\n      get name() {\n        return this.#name;\n      }\n      get parentPath() {\n        return this.#parentPath;\n      }\n      get path() {\n        return this.#parentPath;\n      }\n      isFile() {\n        return this.#type === UV_DIRENT_FILE;\n      }\n      isDirectory() {\n        return this.#type === UV_DIRENT_DIR;\n      }\n      isSymbolicLink() {\n        return this.#type === UV_DIRENT_LINK;\n      }\n      isBlockDevice() {\n        return false;\n      }\n      isCharacterDevice() {\n        return false;\n      }\n      isFIFO() {\n        return false;\n      }\n      isSocket() {\n        return false;\n      }\n    };\n    var TYPE_FILE = 0;\n    var TYPE_DIR = 1;\n    var TYPE_SYMLINK = 2;\n    var kMaxSymlinkDepth = 40;\n    var SqliteFileHandle = class extends VirtualFileHandle {\n      #content;\n      #updateStmt;\n      #path;\n      #getStats;\n      #checkClosed() {\n        if (this.closed) {\n          const { createEBADF } = require_errors();\n          throw createEBADF("read");\n        }\n      }\n      constructor(path, flags, mode, content, updateStmt, getStats) {\n        super(path, flags, mode);\n        this.#content = content;\n        this.#updateStmt = updateStmt;\n        this.#path = path;\n        this.#getStats = getStats;\n        if (flags === "w" || flags === "w+") {\n          this.#content = Buffer2.alloc(0);\n          this.#flush();\n        } else if (flags === "a" || flags === "a+") {\n          this.position = this.#content.length;\n        }\n      }\n      #flush() {\n        const now = Date.now();\n        this.#updateStmt.run(this.#content, now, this.#path);\n      }\n      get content() {\n        return this.#content;\n      }\n      readSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        const content = this.#content;\n        const readPos = position !== null && position !== void 0 ? position : this.position;\n        const available = content.length - readPos;\n        if (available <= 0) {\n          return 0;\n        }\n        const bytesToRead = Math.min(length, available);\n        content.copy(buffer, offset, readPos, readPos + bytesToRead);\n        if (position === null || position === void 0) {\n          this.position = readPos + bytesToRead;\n        }\n        return bytesToRead;\n      }\n      async read(buffer, offset, length, position) {\n        const bytesRead = this.readSync(buffer, offset, length, position);\n        return { bytesRead, buffer };\n      }\n      writeSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        const writePos = position !== null && position !== void 0 ? position : this.position;\n        const data = buffer.subarray(offset, offset + length);\n        if (writePos + length > this.#content.length) {\n          const newContent = Buffer2.alloc(writePos + length);\n          this.#content.copy(newContent, 0, 0, this.#content.length);\n          this.#content = newContent;\n        }\n        data.copy(this.#content, writePos);\n        this.#flush();\n        if (position === null || position === void 0) {\n          this.position = writePos + length;\n        }\n        return length;\n      }\n      async write(buffer, offset, length, position) {\n        const bytesWritten = this.writeSync(buffer, offset, length, position);\n        return { bytesWritten, buffer };\n      }\n      readFileSync(options) {\n        this.#checkClosed();\n        const content = this.#content;\n        const encoding = typeof options === "string" ? options : options?.encoding;\n        if (encoding) {\n          return content.toString(encoding);\n        }\n        return Buffer2.from(content);\n      }\n      async readFile(options) {\n        return this.readFileSync(options);\n      }\n      writeFileSync(data, options) {\n        this.#checkClosed();\n        const buffer = typeof data === "string" ? Buffer2.from(data, options?.encoding) : data;\n        if (this.flags === "a" || this.flags === "a+") {\n          const newContent = Buffer2.alloc(this.#content.length + buffer.length);\n          this.#content.copy(newContent, 0);\n          buffer.copy(newContent, this.#content.length);\n          this.#content = newContent;\n        } else {\n          this.#content = Buffer2.from(buffer);\n        }\n        this.#flush();\n        this.position = this.#content.length;\n      }\n      async writeFile(data, options) {\n        this.writeFileSync(data, options);\n      }\n      statSync(options) {\n        this.#checkClosed();\n        if (this.#getStats) {\n          return this.#getStats(this.#content.length);\n        }\n        const { ERR_INVALID_STATE } = require_errors();\n        throw new ERR_INVALID_STATE("stats not available");\n      }\n      async stat(options) {\n        return this.statSync(options);\n      }\n      truncateSync(len = 0) {\n        this.#checkClosed();\n        if (len < this.#content.length) {\n          this.#content = this.#content.subarray(0, len);\n        } else if (len > this.#content.length) {\n          const newContent = Buffer2.alloc(len);\n          this.#content.copy(newContent, 0, 0, this.#content.length);\n          this.#content = newContent;\n        }\n        this.#flush();\n      }\n      async truncate(len) {\n        this.truncateSync(len);\n      }\n    };\n    var SqliteProvider = class extends VirtualProvider {\n      #db;\n      #readonly;\n      #statWatchers;\n      // Prepared statements\n      #stmtGet;\n      #stmtInsert;\n      #stmtUpdateContent;\n      #stmtDelete;\n      #stmtChildren;\n      #stmtDescendants;\n      constructor(pathOrMemory) {\n        super();\n        this.#readonly = false;\n        this.#statWatchers = /* @__PURE__ */ new Map();\n        this.#db = new DatabaseSync(pathOrMemory ?? ":memory:");\n        this.#db.exec(`\n      CREATE TABLE IF NOT EXISTS entries (\n        path        TEXT PRIMARY KEY,\n        parent_path TEXT,\n        name        TEXT,\n        type        INTEGER NOT NULL,\n        content     BLOB,\n        target      TEXT,\n        mode        INTEGER NOT NULL,\n        mtime       REAL NOT NULL,\n        ctime       REAL NOT NULL,\n        birthtime   REAL NOT NULL\n      );\n      CREATE INDEX IF NOT EXISTS idx_parent ON entries(parent_path);\n    `);\n        const root = this.#db.prepare(\n          "SELECT path FROM entries WHERE path = ?"\n        ).get("/");\n        if (!root) {\n          const now = Date.now();\n          this.#db.prepare(\n            "INSERT INTO entries (path, parent_path, name, type, content, target, mode, mtime, ctime, birthtime) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"\n          ).run("/", null, "", TYPE_DIR, null, null, 493, now, now, now);\n        }\n        this.#stmtGet = this.#db.prepare(\n          "SELECT * FROM entries WHERE path = ?"\n        );\n        this.#stmtInsert = this.#db.prepare(\n          "INSERT INTO entries (path, parent_path, name, type, content, target, mode, mtime, ctime, birthtime) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"\n        );\n        this.#stmtUpdateContent = this.#db.prepare(\n          "UPDATE entries SET content=?, mtime=? WHERE path=?"\n        );\n        this.#stmtDelete = this.#db.prepare(\n          "DELETE FROM entries WHERE path = ?"\n        );\n        this.#stmtChildren = this.#db.prepare(\n          "SELECT * FROM entries WHERE parent_path = ?"\n        );\n        this.#stmtDescendants = this.#db.prepare(\n          "SELECT * FROM entries WHERE path LIKE ? AND path != ?"\n        );\n      }\n      get readonly() {\n        return this.#readonly;\n      }\n      get supportsWatch() {\n        return true;\n      }\n      get supportsSymlinks() {\n        return true;\n      }\n      setReadOnly() {\n        this.#readonly = true;\n      }\n      close() {\n        for (const watcher of this.#statWatchers.values()) {\n          watcher.stop();\n        }\n        this.#statWatchers.clear();\n        this.#db.close();\n      }\n      #normalizePath(path) {\n        let normalized = path.replace(/\\\\/g, "/");\n        if (!normalized.startsWith("/")) {\n          normalized = "/" + normalized;\n        }\n        return pathPosix.normalize(normalized);\n      }\n      #getParentPath(path) {\n        if (path === "/") {\n          return null;\n        }\n        return pathPosix.dirname(path);\n      }\n      #getBaseName(path) {\n        return pathPosix.basename(path);\n      }\n      #resolveSymlinkTarget(symlinkPath, target) {\n        if (target.startsWith("/")) {\n          return this.#normalizePath(target);\n        }\n        const parentPath = this.#getParentPath(symlinkPath) || "/";\n        return this.#normalizePath(pathPosix.join(parentPath, target));\n      }\n      #getRow(path) {\n        return this.#stmtGet.get(path);\n      }\n      #lookupEntry(path, followSymlinks = true, depth = 0) {\n        const normalized = this.#normalizePath(path);\n        if (normalized === "/") {\n          const row2 = this.#getRow("/");\n          return { row: row2, resolvedPath: "/" };\n        }\n        const segments = normalized.slice(1).split("/");\n        let currentPath = "/";\n        for (let i = 0; i < segments.length; i++) {\n          const segment = segments[i];\n          const nextPath = currentPath === "/" ? "/" + segment : currentPath + "/" + segment;\n          const currentRow = this.#getRow(currentPath);\n          if (!currentRow) {\n            return { row: null, resolvedPath: null };\n          }\n          if (currentRow.type === TYPE_SYMLINK) {\n            if (depth >= kMaxSymlinkDepth) {\n              return { row: null, resolvedPath: null, eloop: true };\n            }\n            const targetPath = this.#resolveSymlinkTarget(currentPath, currentRow.target);\n            const result = this.#lookupEntry(targetPath, true, depth + 1);\n            if (result.eloop) {\n              return result;\n            }\n            if (!result.row) {\n              return { row: null, resolvedPath: null };\n            }\n            const remaining = segments.slice(i).join("/");\n            const fullPath = result.resolvedPath === "/" ? "/" + remaining : result.resolvedPath + "/" + remaining;\n            return this.#lookupEntry(fullPath, followSymlinks, depth + 1);\n          }\n          if (currentRow.type !== TYPE_DIR) {\n            return { row: null, resolvedPath: null };\n          }\n          currentPath = nextPath;\n        }\n        const row = this.#getRow(currentPath);\n        if (!row) {\n          return { row: null, resolvedPath: null };\n        }\n        if (row.type === TYPE_SYMLINK && followSymlinks) {\n          if (depth >= kMaxSymlinkDepth) {\n            return { row: null, resolvedPath: null, eloop: true };\n          }\n          const targetPath = this.#resolveSymlinkTarget(currentPath, row.target);\n          return this.#lookupEntry(targetPath, true, depth + 1);\n        }\n        return { row, resolvedPath: currentPath };\n      }\n      #getEntry(path, syscall, followSymlinks = true) {\n        const result = this.#lookupEntry(path, followSymlinks);\n        if (result.eloop) {\n          throw createELOOP(syscall, path);\n        }\n        if (!result.row) {\n          throw createENOENT(syscall, path);\n        }\n        return result.row;\n      }\n      #ensureParent(path, create, syscall) {\n        const parentPath = this.#getParentPath(path);\n        if (parentPath === null) {\n          return this.#getRow("/");\n        }\n        const result = this.#lookupEntry(parentPath, true);\n        if (result.row) {\n          if (result.row.type !== TYPE_DIR) {\n            throw createENOTDIR(syscall, path);\n          }\n          return result.row;\n        }\n        if (create) {\n          const segments = parentPath.slice(1).split("/");\n          let currentPath = "";\n          for (const segment of segments) {\n            currentPath += "/" + segment;\n            const existing = this.#getRow(currentPath);\n            if (!existing) {\n              const now = Date.now();\n              const pp = this.#getParentPath(currentPath);\n              this.#stmtInsert.run(currentPath, pp, segment, TYPE_DIR, null, null, 493, now, now, now);\n            } else if (existing.type !== TYPE_DIR) {\n              throw createENOTDIR(syscall, path);\n            }\n          }\n          return this.#getRow(parentPath);\n        }\n        throw createENOENT(syscall, path);\n      }\n      #createStats(row, size) {\n        const options = {\n          mode: row.mode,\n          mtimeMs: row.mtime,\n          ctimeMs: row.ctime,\n          birthtimeMs: row.birthtime\n        };\n        if (row.type === TYPE_FILE) {\n          const content = row.content;\n          const fileSize = size !== void 0 ? size : content ? content.byteLength : 0;\n          return createFileStats(fileSize, options);\n        } else if (row.type === TYPE_DIR) {\n          return createDirectoryStats(options);\n        } else if (row.type === TYPE_SYMLINK) {\n          return createSymlinkStats(row.target.length, options);\n        }\n        const { ERR_INVALID_STATE } = require_errors();\n        throw new ERR_INVALID_STATE("Unknown entry type");\n      }\n      openSync(path, flags, mode) {\n        const normalized = this.#normalizePath(path);\n        const isCreate = flags === "w" || flags === "w+" || flags === "a" || flags === "a+";\n        if (this.readonly && isCreate) {\n          throw createEROFS("open", path);\n        }\n        let row;\n        try {\n          row = this.#getEntry(normalized, "open");\n        } catch (err) {\n          if (err.code === "ENOENT" && isCreate) {\n            this.#ensureParent(normalized, true, "open");\n            const name = this.#getBaseName(normalized);\n            const parentPath = this.#getParentPath(normalized);\n            const now = Date.now();\n            const fileMode = mode ?? 420;\n            this.#stmtInsert.run(normalized, parentPath, name, TYPE_FILE, Buffer2.alloc(0), null, fileMode, now, now, now);\n            row = this.#getRow(normalized);\n          } else {\n            throw err;\n          }\n        }\n        if (row.type === TYPE_DIR) {\n          throw createEISDIR("open", path);\n        }\n        if (row.type === TYPE_SYMLINK) {\n          throw createEINVAL("open", path);\n        }\n        const content = row.content ? Buffer2.from(row.content) : Buffer2.alloc(0);\n        const getStats = (size) => this.#createStats(this.#getRow(normalized) || row, size);\n        return new SqliteFileHandle(normalized, flags, mode ?? row.mode, content, this.#stmtUpdateContent, getStats);\n      }\n      async open(path, flags, mode) {\n        return this.openSync(path, flags, mode);\n      }\n      statSync(path, options) {\n        const row = this.#getEntry(path, "stat", true);\n        return this.#createStats(row);\n      }\n      async stat(path, options) {\n        return this.statSync(path, options);\n      }\n      lstatSync(path, options) {\n        const row = this.#getEntry(path, "lstat", false);\n        return this.#createStats(row);\n      }\n      async lstat(path, options) {\n        return this.lstatSync(path, options);\n      }\n      readdirSync(path, options) {\n        const result = this.#lookupEntry(path, true);\n        if (result.eloop) {\n          throw createELOOP("scandir", path);\n        }\n        if (!result.row) {\n          throw createENOENT("scandir", path);\n        }\n        if (result.row.type !== TYPE_DIR) {\n          throw createENOTDIR("scandir", path);\n        }\n        const children = this.#stmtChildren.all(result.resolvedPath);\n        if (options?.withFileTypes) {\n          const normalized = this.#normalizePath(path);\n          return children.map((child) => {\n            let type;\n            if (child.type === TYPE_SYMLINK) {\n              type = UV_DIRENT_LINK;\n            } else if (child.type === TYPE_DIR) {\n              type = UV_DIRENT_DIR;\n            } else {\n              type = UV_DIRENT_FILE;\n            }\n            return new VirtualDirent(child.name, type, normalized);\n          });\n        }\n        return children.map((child) => child.name);\n      }\n      async readdir(path, options) {\n        return this.readdirSync(path, options);\n      }\n      mkdirSync(path, options) {\n        if (this.readonly) {\n          throw createEROFS("mkdir", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const recursive = options?.recursive === true;\n        const existing = this.#lookupEntry(normalized, true);\n        if (existing.row) {\n          if (existing.row.type === TYPE_DIR && recursive) {\n            return void 0;\n          }\n          throw createEEXIST("mkdir", path);\n        }\n        if (recursive) {\n          const segments = normalized.slice(1).split("/");\n          let currentPath = "";\n          for (const segment of segments) {\n            currentPath += "/" + segment;\n            const row = this.#getRow(currentPath);\n            if (!row) {\n              const now = Date.now();\n              const pp = this.#getParentPath(currentPath);\n              this.#stmtInsert.run(currentPath, pp, segment, TYPE_DIR, null, null, options?.mode ?? 493, now, now, now);\n            } else if (row.type !== TYPE_DIR) {\n              throw createENOTDIR("mkdir", path);\n            }\n          }\n        } else {\n          this.#ensureParent(normalized, false, "mkdir");\n          const name = this.#getBaseName(normalized);\n          const parentPath = this.#getParentPath(normalized);\n          const now = Date.now();\n          this.#stmtInsert.run(normalized, parentPath, name, TYPE_DIR, null, null, options?.mode ?? 493, now, now, now);\n        }\n        return recursive ? normalized : void 0;\n      }\n      async mkdir(path, options) {\n        return this.mkdirSync(path, options);\n      }\n      rmdirSync(path) {\n        if (this.readonly) {\n          throw createEROFS("rmdir", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const row = this.#getEntry(normalized, "rmdir", true);\n        if (row.type !== TYPE_DIR) {\n          throw createENOTDIR("rmdir", path);\n        }\n        const children = this.#stmtChildren.all(normalized);\n        if (children.length > 0) {\n          throw createENOTEMPTY("rmdir", path);\n        }\n        this.#stmtDelete.run(normalized);\n      }\n      async rmdir(path) {\n        this.rmdirSync(path);\n      }\n      unlinkSync(path) {\n        if (this.readonly) {\n          throw createEROFS("unlink", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const row = this.#getEntry(normalized, "unlink", false);\n        if (row.type === TYPE_DIR) {\n          throw createEISDIR("unlink", path);\n        }\n        this.#stmtDelete.run(normalized);\n      }\n      async unlink(path) {\n        this.unlinkSync(path);\n      }\n      renameSync(oldPath, newPath) {\n        if (this.readonly) {\n          throw createEROFS("rename", oldPath);\n        }\n        const normalizedOld = this.#normalizePath(oldPath);\n        const normalizedNew = this.#normalizePath(newPath);\n        const row = this.#getEntry(normalizedOld, "rename", false);\n        this.#ensureParent(normalizedNew, true, "rename");\n        const newName = this.#getBaseName(normalizedNew);\n        const newParentPath = this.#getParentPath(normalizedNew);\n        if (row.type === TYPE_DIR) {\n          this.#db.exec("BEGIN");\n          try {\n            this.#stmtDelete.run(normalizedOld);\n            const now = Date.now();\n            this.#stmtDelete.run(normalizedNew);\n            this.#stmtInsert.run(\n              normalizedNew,\n              newParentPath,\n              newName,\n              row.type,\n              row.content,\n              row.target,\n              row.mode,\n              now,\n              row.ctime,\n              row.birthtime\n            );\n            const prefix = normalizedOld + "/";\n            const descendants = this.#stmtDescendants.all(\n              prefix + "%",\n              normalizedOld\n            );\n            for (const desc of descendants) {\n              const suffix = desc.path.slice(normalizedOld.length);\n              const newDescPath = normalizedNew + suffix;\n              const newDescParent = this.#getParentPath(newDescPath);\n              const descName = this.#getBaseName(newDescPath);\n              this.#stmtDelete.run(desc.path);\n              this.#stmtInsert.run(\n                newDescPath,\n                newDescParent,\n                descName,\n                desc.type,\n                desc.content,\n                desc.target,\n                desc.mode,\n                desc.mtime,\n                desc.ctime,\n                desc.birthtime\n              );\n            }\n            this.#db.exec("COMMIT");\n          } catch (err) {\n            this.#db.exec("ROLLBACK");\n            throw err;\n          }\n        } else {\n          this.#stmtDelete.run(normalizedOld);\n          const now = Date.now();\n          this.#stmtDelete.run(normalizedNew);\n          this.#stmtInsert.run(\n            normalizedNew,\n            newParentPath,\n            newName,\n            row.type,\n            row.content,\n            row.target,\n            row.mode,\n            now,\n            row.ctime,\n            row.birthtime\n          );\n        }\n      }\n      async rename(oldPath, newPath) {\n        this.renameSync(oldPath, newPath);\n      }\n      readlinkSync(path, options) {\n        const normalized = this.#normalizePath(path);\n        const row = this.#getEntry(normalized, "readlink", false);\n        if (row.type !== TYPE_SYMLINK) {\n          throw createEINVAL("readlink", path);\n        }\n        return row.target;\n      }\n      async readlink(path, options) {\n        return this.readlinkSync(path, options);\n      }\n      symlinkSync(target, path, type) {\n        if (this.readonly) {\n          throw createEROFS("symlink", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const existing = this.#lookupEntry(normalized, false);\n        if (existing.row) {\n          throw createEEXIST("symlink", path);\n        }\n        this.#ensureParent(normalized, true, "symlink");\n        const name = this.#getBaseName(normalized);\n        const parentPath = this.#getParentPath(normalized);\n        const now = Date.now();\n        this.#stmtInsert.run(normalized, parentPath, name, TYPE_SYMLINK, null, target, 511, now, now, now);\n      }\n      async symlink(target, path, type) {\n        this.symlinkSync(target, path, type);\n      }\n      realpathSync(path, options) {\n        const result = this.#lookupEntry(path, true, 0);\n        if (result.eloop) {\n          throw createELOOP("realpath", path);\n        }\n        if (!result.row) {\n          throw createENOENT("realpath", path);\n        }\n        return result.resolvedPath;\n      }\n      async realpath(path, options) {\n        return this.realpathSync(path, options);\n      }\n      // === WATCH OPERATIONS ===\n      watch(path, options) {\n        const normalized = this.#normalizePath(path);\n        return new VFSWatcher(this, normalized, options);\n      }\n      watchAsync(path, options) {\n        const normalized = this.#normalizePath(path);\n        return new VFSWatchAsyncIterable(this, normalized, options);\n      }\n      watchFile(path, options, listener) {\n        const normalized = this.#normalizePath(path);\n        let watcher = this.#statWatchers.get(normalized);\n        if (!watcher) {\n          watcher = new VFSStatWatcher(this, normalized, options);\n          this.#statWatchers.set(normalized, watcher);\n        }\n        if (listener) {\n          watcher.addListener(listener);\n        }\n        return watcher;\n      }\n      unwatchFile(path, listener) {\n        const normalized = this.#normalizePath(path);\n        const watcher = this.#statWatchers.get(normalized);\n        if (!watcher) {\n          return;\n        }\n        if (listener) {\n          watcher.removeListener(listener);\n        } else {\n          watcher.removeAllListeners("change");\n        }\n        if (watcher.hasNoListeners()) {\n          watcher.stop();\n          this.#statWatchers.delete(normalized);\n        }\n      }\n    };\n    module2.exports = {\n      SqliteProvider\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/index.js\nvar require_vfs = __commonJS({\n  "node_modules/@roberts_lando/vfs/index.js"(exports2, module2) {\n    "use strict";\n    var { VirtualFileSystem } = require_file_system();\n    var { VirtualProvider } = require_provider();\n    var { MemoryProvider } = require_memory();\n    var { RealFSProvider } = require_real();\n    function create(provider, options) {\n      if (provider != null && !(provider instanceof VirtualProvider) && typeof provider === "object") {\n        options = provider;\n        provider = void 0;\n      }\n      return new VirtualFileSystem(provider, options);\n    }\n    module2.exports = {\n      create,\n      VirtualFileSystem,\n      VirtualProvider,\n      MemoryProvider,\n      RealFSProvider\n    };\n    Object.defineProperty(module2.exports, "SqliteProvider", {\n      enumerable: true,\n      configurable: true,\n      get() {\n        const { SqliteProvider } = require_sqlite();\n        Object.defineProperty(module2.exports, "SqliteProvider", {\n          value: SqliteProvider,\n          enumerable: true,\n          configurable: true,\n          writable: true\n        });\n        return SqliteProvider;\n      }\n    });\n  }\n});\n\n// prelude/sea-vfs-setup.js\nvar require_sea_vfs_setup = __commonJS({\n  "prelude/sea-vfs-setup.js"(exports2, module2) {\n    "use strict";\n    var sea = require("node:sea");\n    var shared2 = require_bootstrap_shared();\n    var COMPRESS_NONE = shared2.COMPRESS_NONE;\n    var vfsModule;\n    try {\n      vfsModule = require("node:vfs");\n    } catch (_) {\n      try {\n        vfsModule = require_vfs();\n      } catch (e) {\n        throw new Error(\n          "pkg: VFS polyfill (@roberts_lando/vfs) is not available: " + e.message\n        );\n      }\n    }\n    var VirtualFileSystem = vfsModule.VirtualFileSystem;\n    var MemoryProvider = vfsModule.MemoryProvider;\n    var MAX_SYMLINK_DEPTH = 40;\n    var perf = {\n      enabled: !!process.env.DEBUG_PKG_PERF,\n      // Phase timers (high-resolution)\n      _timers: {},\n      // Cumulative counters\n      _counters: {},\n      // Cumulative durations (BigInt nanoseconds)\n      _durations: {},\n      /** Mark the start of a named phase. */\n      start: function(label) {\n        if (!this.enabled) return;\n        this._timers[label] = process.hrtime.bigint();\n      },\n      /** End a named phase and record its duration. */\n      end: function(label) {\n        if (!this.enabled || !this._timers[label]) return;\n        var ns = process.hrtime.bigint() - this._timers[label];\n        this._durations[label] = (this._durations[label] || 0n) + ns;\n      },\n      /** Increment a named counter by n (default 1). */\n      count: function(label, n) {\n        if (!this.enabled) return;\n        this._counters[label] = (this._counters[label] || 0) + (n !== void 0 ? n : 1);\n      },\n      /** Add nanoseconds to a cumulative duration counter. */\n      addNs: function(label, ns) {\n        if (!this.enabled) return;\n        this._durations[label] = (this._durations[label] || 0n) + ns;\n      },\n      /** Format milliseconds from a BigInt nanosecond duration. */\n      _ms: function(ns) {\n        return (Number(ns) / 1e6).toFixed(1) + "ms";\n      },\n      /**\n       * Finalize perf tracking: end the `module loading` phase, aggregate\n       * the `vfs setup total`, capture the file-cache-entries counter from\n       * the provider, and print the report.  Called by each bootstrap\n       * dispatcher at the appropriate point so the module-loading phase\n       * timing reflects actual entrypoint completion.\n       */\n      finalize: function() {\n        if (!this.enabled) return;\n        this.end("module loading");\n        this._durations["vfs setup total"] = (this._durations["manifest parse"] || 0n) + (this._durations["archive load"] || 0n) + (this._durations["directory tree init"] || 0n) + (this._durations["vfs mount + hooks"] || 0n);\n        if (this._provider) {\n          this._counters["file cache entries"] = this._provider.fileCacheSize;\n        }\n        this.report();\n      },\n      /** Print the final performance report. */\n      report: function() {\n        if (!this.enabled) return;\n        var self = this;\n        var P = "[pkg:perf] ";\n        var SEP = P + "\\u2500".repeat(30);\n        console.log("");\n        console.log(P + "phase                 time");\n        console.log(SEP);\n        var phaseOrder = [\n          "manifest parse",\n          "archive load",\n          "directory tree init",\n          "vfs mount + hooks",\n          "vfs setup total",\n          "module loading"\n        ];\n        phaseOrder.forEach(function(label) {\n          var d = self._durations[label];\n          if (d !== void 0) {\n            console.log(P + label.padEnd(22) + self._ms(d));\n          }\n        });\n        console.log(P);\n        console.log(P + "counter                  value");\n        console.log(SEP);\n        var counterOrder = [\n          "files loaded",\n          "file cache entries",\n          "statSync calls",\n          "existsSync calls",\n          "readdirSync calls"\n        ];\n        counterOrder.forEach(function(label) {\n          var v = self._counters[label];\n          var d = self._durations[label];\n          if (v !== void 0) {\n            console.log(P + label.padEnd(22) + String(v).padStart(8));\n          } else if (d !== void 0) {\n            console.log(P + label.padEnd(22) + self._ms(d).padStart(8));\n          } else {\n            console.log(P + label.padEnd(22) + String(0).padStart(8));\n          }\n        });\n        console.log("");\n      }\n    };\n    perf.start("manifest parse");\n    var manifest;\n    try {\n      manifest = JSON.parse(sea.getAsset("__pkg_manifest__", "utf8"));\n    } catch (e) {\n      throw new Error(\n        "pkg: Failed to load VFS manifest from SEA assets: " + e.message\n      );\n    }\n    perf.end("manifest parse");\n    function _stripTrailingSeps(p) {\n      var i = p.length;\n      while (i > 1 && p.charCodeAt(i - 1) === 47) i--;\n      return i === p.length ? p : p.slice(0, i);\n    }\n    var toManifestKey = process.platform === "win32" ? function(p) {\n      return _stripTrailingSeps(p.replace(/\\\\/g, "/"));\n    } : function(p) {\n      return _stripTrailingSeps(p);\n    };\n    function _enoent(syscall, filePath) {\n      var err = new Error(\n        "ENOENT: no such file or directory, " + syscall + " \'" + filePath + "\'"\n      );\n      err.code = "ENOENT";\n      err.errno = -2;\n      err.syscall = syscall;\n      err.path = filePath;\n      return err;\n    }\n    var _now = Date.now();\n    function _makeStats(meta) {\n      return {\n        dev: 0,\n        ino: 0,\n        nlink: 1,\n        uid: 0,\n        gid: 0,\n        rdev: 0,\n        blksize: 4096,\n        mode: meta.isDirectory ? 16877 : 33188,\n        size: meta.size || 0,\n        blocks: Math.ceil((meta.size || 0) / 512),\n        atimeMs: _now,\n        mtimeMs: _now,\n        ctimeMs: _now,\n        birthtimeMs: _now,\n        atime: new Date(_now),\n        mtime: new Date(_now),\n        ctime: new Date(_now),\n        birthtime: new Date(_now),\n        isFile: function() {\n          return meta.isFile;\n        },\n        isDirectory: function() {\n          return meta.isDirectory;\n        },\n        isSymbolicLink: function() {\n          return false;\n        },\n        isBlockDevice: function() {\n          return false;\n        },\n        isCharacterDevice: function() {\n          return false;\n        },\n        isFIFO: function() {\n          return false;\n        },\n        isSocket: function() {\n          return false;\n        }\n      };\n    }\n    var SEAProvider = class extends MemoryProvider {\n      constructor(seaManifest) {\n        super();\n        this._manifest = seaManifest;\n        this._fileCache = /* @__PURE__ */ new Map();\n        this._compression = seaManifest.compression || COMPRESS_NONE;\n        this._decompress = shared2.pickDecompressorSync(this._compression);\n        perf.start("archive load");\n        try {\n          this._archive = Buffer.from(sea.getRawAsset("__pkg_archive__"));\n        } catch (e) {\n          throw new Error(\n            "pkg: Failed to load archive from SEA assets: " + e.message\n          );\n        }\n        perf.end("archive load");\n        perf.start("directory tree init");\n        for (var dir of Object.keys(seaManifest.directories)) {\n          super.mkdirSync(dir, { recursive: true });\n        }\n        perf.end("directory tree init");\n      }\n      _resolveSymlink(p) {\n        var symlinks = this._manifest.symlinks;\n        if (symlinks[p] === void 0) return p;\n        var original = p;\n        for (var i = 0; i < MAX_SYMLINK_DEPTH; i++) {\n          var target = symlinks[p];\n          if (!target) return p;\n          p = target;\n        }\n        var err = new Error(\n          "ELOOP: too many symbolic links encountered, \'" + original + "\'"\n        );\n        err.code = "ELOOP";\n        err.errno = -40;\n        err.syscall = "stat";\n        err.path = original;\n        throw err;\n      }\n      get fileCacheSize() {\n        return this._fileCache.size;\n      }\n      readFileSync(filePath, options) {\n        var p = this._resolveSymlink(toManifestKey(filePath));\n        var cached = this._decompress ? this._fileCache.get(p) : void 0;\n        var buf;\n        if (cached !== void 0) {\n          buf = cached;\n        } else {\n          var entry = this._manifest.offsets[p];\n          if (!entry) throw _enoent("open", filePath);\n          var off = entry[0];\n          var len = entry[1];\n          if (!Number.isInteger(off) || !Number.isInteger(len) || off < 0 || len < 0 || off + len > this._archive.length) {\n            throw new Error(\n              "pkg: corrupt SEA manifest \\u2014 entry [" + off + "," + len + "] out of bounds for archive of " + this._archive.length + " bytes (file: " + filePath + ")"\n            );\n          }\n          var slice = this._archive.subarray(off, off + len);\n          if (this._decompress) {\n            var meta = this._manifest.stats[p];\n            var maxOutputLength = meta && Number.isInteger(meta.size) && meta.size >= 0 ? meta.size : null;\n            if (maxOutputLength === null) {\n              throw new Error(\n                "pkg: corrupt SEA manifest \\u2014 missing or invalid stats.size for " + filePath\n              );\n            }\n            buf = this._decompress(slice, { maxOutputLength });\n            this._fileCache.set(p, buf);\n          } else {\n            buf = slice;\n          }\n          perf.count("files loaded");\n        }\n        var encoding = typeof options === "string" ? options : options && options.encoding;\n        if (encoding) return buf.toString(encoding);\n        var copy = Buffer.allocUnsafe(buf.length);\n        buf.copy(copy);\n        return copy;\n      }\n      readlinkSync(filePath) {\n        var p = toManifestKey(filePath);\n        var target = this._manifest.symlinks[p];\n        if (target) return target;\n        return super.readlinkSync(p);\n      }\n      statSync(filePath) {\n        perf.count("statSync calls");\n        var p = this._resolveSymlink(toManifestKey(filePath));\n        var meta = this._manifest.stats[p];\n        if (meta) {\n          return _makeStats(meta);\n        }\n        throw _enoent("stat", filePath);\n      }\n      /**\n       * Fast module resolution stat \u2014 returns 0 (file), 1 (directory), or -2\n       * (not found) directly from the manifest.  This is the hottest path during\n       * startup (~30K calls for large projects) so it must be as lean as possible.\n       */\n      internalModuleStat(filePath) {\n        var p = this._resolveSymlink(toManifestKey(filePath));\n        var meta = this._manifest.stats[p];\n        if (meta) {\n          return meta.isDirectory ? 1 : 0;\n        }\n        return -2;\n      }\n      readdirSync(dirPath) {\n        perf.count("readdirSync calls");\n        var p = this._resolveSymlink(toManifestKey(dirPath));\n        var entries = this._manifest.directories[p];\n        if (entries) return entries.slice();\n        return super.readdirSync(p);\n      }\n      existsSync(filePath) {\n        perf.count("existsSync calls");\n        var p = this._resolveSymlink(toManifestKey(filePath));\n        return p in this._manifest.stats;\n      }\n    };\n    perf.start("vfs mount + hooks");\n    var provider = new SEAProvider(manifest);\n    perf._provider = provider;\n    var virtualFs = new VirtualFileSystem(provider);\n    var SNAPSHOT_PREFIX = "/snapshot";\n    if (process.platform === "win32") {\n      _winToVFS = function(p) {\n        if (typeof p !== "string" || p.startsWith("/")) return p;\n        if (/^[A-Za-z]:/.test(p)) p = p.slice(2);\n        return p.replace(/\\\\/g, "/");\n      };\n      _origShouldHandle = VirtualFileSystem.prototype.shouldHandle;\n      VirtualFileSystem.prototype.shouldHandle = function(inputPath) {\n        return _origShouldHandle.call(this, _winToVFS(inputPath));\n      };\n      _origResolvePath = VirtualFileSystem.prototype.resolvePath;\n      VirtualFileSystem.prototype.resolvePath = function(inputPath) {\n        return _origResolvePath.call(this, _winToVFS(inputPath));\n      };\n    }\n    var _winToVFS;\n    var _origShouldHandle;\n    var _origResolvePath;\n    virtualFs.mount(SNAPSHOT_PREFIX, { overlay: true });\n    perf.end("vfs mount + hooks");\n    function toPlatformPath(p) {\n      if (process.platform !== "win32") return p;\n      if (p.startsWith("/snapshot")) {\n        return "C:" + p.replace(/\\//g, "\\\\");\n      }\n      return p.replace(/\\//g, "\\\\");\n    }\n    var SNAPSHOT_PREFIXES_POSIX = [{ prefix: "/snapshot", sep: "/" }];\n    var SNAPSHOT_PREFIXES_WIN = [\n      { prefix: "V:\\\\snapshot", sep: "\\\\" },\n      { prefix: "V:/snapshot", sep: "/" },\n      { prefix: "C:\\\\snapshot", sep: "\\\\" },\n      { prefix: "C:/snapshot", sep: "/" }\n    ];\n    function insideSnapshot(f) {\n      if (typeof f !== "string") return false;\n      var prefixes = process.platform === "win32" ? SNAPSHOT_PREFIXES_POSIX.concat(SNAPSHOT_PREFIXES_WIN) : SNAPSHOT_PREFIXES_POSIX;\n      for (var i = 0; i < prefixes.length; i++) {\n        var p = prefixes[i].prefix;\n        if (f === p || f.startsWith(p + prefixes[i].sep)) return true;\n      }\n      return false;\n    }\n    module2.exports = {\n      manifest,\n      virtualFs,\n      provider,\n      perf,\n      SNAPSHOT_PREFIX,\n      insideSnapshot,\n      toPlatformPath\n    };\n  }\n});\n\n// prelude/sea-worker-entry.js\nvar vfs = require_sea_vfs_setup();\nvar shared = require_bootstrap_shared();\nshared.setupProcessPkg(\n  vfs.toPlatformPath(vfs.manifest.entrypoint),\n  vfs.manifest.entrypoint\n);\n';
++    module2.exports = '"use strict";\nvar __getOwnPropNames = Object.getOwnPropertyNames;\nvar __commonJS = (cb, mod) => function __require() {\n  try {\n    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;\n  } catch (e) {\n    throw mod = 0, e;\n  }\n};\n\n// prelude/bootstrap-shared.js\nvar require_bootstrap_shared = __commonJS({\n  "prelude/bootstrap-shared.js"(exports2, module2) {\n    "use strict";\n    var childProcess = require("child_process");\n    var { createHash } = require("crypto");\n    var fs = require("fs");\n    var path = require("path");\n    var zlib = require("zlib");\n    var { homedir } = require("os");\n    var COMPRESS_NONE = 0;\n    var COMPRESS_GZIP = 1;\n    var COMPRESS_BROTLI = 2;\n    var COMPRESS_ZSTD = 3;\n    function zstdMissingError(symbol) {\n      return new Error(\n        "pkg: Zstd compression requires Node.js >= 22.15 (runtime missing zlib." + symbol + "). Re-package this binary with pkg >= the version that embeds Node 22.15+, or contact the distributor for a --compress Brotli/GZip build."\n      );\n    }\n    function pickDecompressorSync(compression) {\n      switch (compression) {\n        case COMPRESS_NONE:\n          return null;\n        case COMPRESS_GZIP:\n          return zlib.gunzipSync;\n        case COMPRESS_BROTLI:\n          return zlib.brotliDecompressSync;\n        case COMPRESS_ZSTD:\n          if (typeof zlib.zstdDecompressSync !== "function") {\n            throw zstdMissingError("zstdDecompressSync");\n          }\n          return zlib.zstdDecompressSync;\n        default:\n          throw new Error(\n            "pkg: unknown compression codec id " + compression + " in manifest"\n          );\n      }\n    }\n    function pickDecompressorAsync(compression) {\n      switch (compression) {\n        case COMPRESS_NONE:\n          return null;\n        case COMPRESS_GZIP:\n          return zlib.gunzip;\n        case COMPRESS_BROTLI:\n          return zlib.brotliDecompress;\n        case COMPRESS_ZSTD:\n          if (typeof zlib.zstdDecompress !== "function") {\n            throw zstdMissingError("zstdDecompress");\n          }\n          return zlib.zstdDecompress;\n        default:\n          throw new Error("pkg: unknown compression codec id " + compression);\n      }\n    }\n    function cpRecursive(src, dest) {\n      var st = fs.lstatSync(src);\n      if (st.isSymbolicLink()) {\n        var target = fs.readlinkSync(src);\n        try {\n          fs.unlinkSync(dest);\n        } catch (_) {\n        }\n        try {\n          fs.symlinkSync(target, dest);\n          return;\n        } catch (e) {\n          if (e && (e.code === "EPERM" || e.code === "EACCES")) {\n            var resolved = path.isAbsolute(target) ? target : path.join(path.dirname(src), target);\n            cpRecursive(resolved, dest);\n            return;\n          }\n          throw e;\n        }\n      }\n      if (st.isDirectory()) {\n        fs.mkdirSync(dest, { recursive: true });\n        var entries = fs.readdirSync(src);\n        for (var i = 0; i < entries.length; i++) {\n          cpRecursive(path.join(src, entries[i]), path.join(dest, entries[i]));\n        }\n        return;\n      }\n      var srcContent = fs.readFileSync(src);\n      if (fs.existsSync(dest)) {\n        var destContent = fs.readFileSync(dest);\n        var srcHash = createHash("sha256").update(srcContent).digest("hex");\n        var destHash = createHash("sha256").update(destContent).digest("hex");\n        if (srcHash === destHash) {\n          return;\n        }\n      }\n      fs.writeFileSync(dest, srcContent);\n    }\n    function patchDlopen(insideSnapshot) {\n      var ancestor = process.dlopen;\n      var PKG_NATIVE_CACHE_BASE = process.env.PKG_NATIVE_CACHE_PATH || path.join(homedir(), ".cache");\n      function revertMakingLong(f) {\n        if (/^\\\\\\\\\\?\\\\/.test(f)) return f.slice(4);\n        return f;\n      }\n      process.dlopen = function dlopen() {\n        var args = Array.prototype.slice.call(arguments);\n        var modulePath = revertMakingLong(args[1]);\n        var moduleBaseName = path.basename(modulePath);\n        var moduleFolder = path.dirname(modulePath);\n        if (insideSnapshot(modulePath)) {\n          var moduleContent = fs.readFileSync(modulePath);\n          var hash = createHash("sha256").update(moduleContent).digest("hex");\n          var tmpFolder = path.join(PKG_NATIVE_CACHE_BASE, "pkg", hash);\n          fs.mkdirSync(tmpFolder, { recursive: true });\n          var parts = moduleFolder.split(path.sep);\n          var mIndex = parts.lastIndexOf("node_modules") + 1;\n          var newPath;\n          if (mIndex > 0) {\n            var modulePackagePath = parts.slice(mIndex).join(path.sep);\n            var modulePkgFolder = parts.slice(0, mIndex + 1).join(path.sep);\n            var destFolder = path.join(tmpFolder, path.basename(modulePkgFolder));\n            cpRecursive(modulePkgFolder, destFolder);\n            newPath = path.join(tmpFolder, modulePackagePath, moduleBaseName);\n          } else {\n            var tmpModulePath = path.join(tmpFolder, moduleBaseName);\n            if (fs.existsSync(tmpModulePath)) {\n              var dContent = fs.readFileSync(tmpModulePath);\n              var dHash = createHash("sha256").update(dContent).digest("hex");\n              if (hash !== dHash) {\n                fs.writeFileSync(tmpModulePath, moduleContent);\n              }\n            } else {\n              fs.writeFileSync(tmpModulePath, moduleContent);\n            }\n            newPath = tmpModulePath;\n          }\n          args[1] = newPath;\n        }\n        return ancestor.apply(process, args);\n      };\n    }\n    function patchChildProcess(entrypoint) {\n      var EXECPATH = process.execPath;\n      var ARGV0 = process.argv[0];\n      var ancestor = {\n        spawn: childProcess.spawn,\n        spawnSync: childProcess.spawnSync,\n        execFile: childProcess.execFile,\n        execFileSync: childProcess.execFileSync,\n        exec: childProcess.exec,\n        execSync: childProcess.execSync\n      };\n      function cloneArgs(args_) {\n        return Array.prototype.slice.call(args_);\n      }\n      function setOptsEnv(args) {\n        var pos = args.length - 1;\n        if (typeof args[pos] === "function") pos -= 1;\n        if (typeof args[pos] !== "object" || Array.isArray(args[pos])) {\n          pos += 1;\n          args.splice(pos, 0, {});\n        }\n        var opts = args[pos];\n        if (!opts.env) opts.env = Object.assign({}, process.env);\n        if (opts.env.PKG_EXECPATH !== void 0) return;\n        opts.env.PKG_EXECPATH = EXECPATH;\n      }\n      function startsWith2(args, index, name, impostor) {\n        var qsName = \'"\' + name + " ";\n        if (args[index].slice(0, qsName.length) === qsName) {\n          args[index] = \'"\' + impostor + " " + args[index].slice(qsName.length);\n          return true;\n        }\n        var sName = name + " ";\n        if (args[index].slice(0, sName.length) === sName) {\n          args[index] = impostor + " " + args[index].slice(sName.length);\n          return true;\n        }\n        if (args[index] === name) {\n          args[index] = impostor;\n          return true;\n        }\n        return false;\n      }\n      function startsWith(args, index, name) {\n        var qName = \'"\' + name + \'"\';\n        var qEXECPATH = \'"\' + EXECPATH + \'"\';\n        var jsName = JSON.stringify(name);\n        var jsEXECPATH = JSON.stringify(EXECPATH);\n        return startsWith2(args, index, name, EXECPATH) || startsWith2(args, index, qName, qEXECPATH) || startsWith2(args, index, jsName, jsEXECPATH);\n      }\n      function modifyLong(args, index) {\n        if (!args[index]) return;\n        return startsWith(args, index, "node") || startsWith(args, index, ARGV0) || startsWith(args, index, entrypoint) || startsWith(args, index, EXECPATH);\n      }\n      function modifyShort(args) {\n        if (!args[0]) return;\n        if (!Array.isArray(args[1])) {\n          args.splice(1, 0, []);\n        }\n        if (args[0] === "node" || args[0] === ARGV0 || args[0] === entrypoint || args[0] === EXECPATH) {\n          args[0] = EXECPATH;\n        } else {\n          for (var i = 1; i < args[1].length; i += 1) {\n            var mbc = args[1][i - 1];\n            if (mbc === "-c" || mbc === "/c") {\n              modifyLong(args[1], i);\n            }\n          }\n        }\n      }\n      childProcess.spawn = function spawn() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyShort(args);\n        return ancestor.spawn.apply(childProcess, args);\n      };\n      childProcess.spawnSync = function spawnSync() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyShort(args);\n        return ancestor.spawnSync.apply(childProcess, args);\n      };\n      childProcess.execFile = function execFile() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyShort(args);\n        return ancestor.execFile.apply(childProcess, args);\n      };\n      childProcess.execFileSync = function execFileSync() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyShort(args);\n        return ancestor.execFileSync.apply(childProcess, args);\n      };\n      childProcess.exec = function exec() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyLong(args, 0);\n        return ancestor.exec.apply(childProcess, args);\n      };\n      childProcess.execSync = function execSync() {\n        var args = cloneArgs(arguments);\n        setOptsEnv(args);\n        modifyLong(args, 0);\n        return ancestor.execSync.apply(childProcess, args);\n      };\n    }\n    function setupProcessPkg(entrypoint, defaultEntrypoint) {\n      process.pkg = {\n        entrypoint,\n        defaultEntrypoint: defaultEntrypoint !== void 0 ? defaultEntrypoint : entrypoint,\n        path: {\n          resolve: function() {\n            var args = [path.dirname(entrypoint)];\n            for (var i = 0; i < arguments.length; i++) {\n              args.push(arguments[i]);\n            }\n            return path.resolve.apply(path, args);\n          }\n        }\n      };\n    }\n    function humanSize(bytes) {\n      var sizes = ["Bytes", "KB", "MB", "GB", "TB"];\n      if (bytes === 0) return "n/a";\n      var i = Math.floor(Math.log(bytes) / Math.log(1024));\n      if (i === 0) return bytes + " " + sizes[i];\n      return (bytes / Math.pow(1024, i)).toFixed(1) + " " + sizes[i];\n    }\n    function installDiagnostic(snapshotPrefix) {\n      if (!process.env.DEBUG_PKG) return;\n      var sizeLimit = process.env.SIZE_LIMIT_PKG ? parseInt(process.env.SIZE_LIMIT_PKG, 10) : 5 * 1024 * 1024;\n      var folderLimit = process.env.FOLDER_LIMIT_PKG ? parseInt(process.env.FOLDER_LIMIT_PKG, 10) : 10 * 1024 * 1024;\n      var overSized = [];\n      function dumpLevel(filename, level, tree2) {\n        var totalSize2 = 0;\n        var d = fs.readdirSync(filename);\n        for (var j = 0; j < d.length; j += 1) {\n          var f = path.join(filename, d[j]);\n          var realPath;\n          try {\n            realPath = fs.realpathSync(f);\n          } catch (_) {\n            realPath = f;\n          }\n          var isSymbolicLink = f !== realPath;\n          var s = fs.statSync(f);\n          if (s.isDirectory() && !isSymbolicLink) {\n            var tree1 = [];\n            var startIndex = overSized.length;\n            var folderSize = dumpLevel(f, level + 1, tree1);\n            totalSize2 += folderSize;\n            var str = (" ".padStart(level * 2, " ") + d[j]).padEnd(40, " ") + (humanSize(folderSize).padStart(10, " ") + (isSymbolicLink ? "=> " + realPath : " "));\n            tree2.push(str);\n            tree1.forEach(function(x) {\n              tree2.push(x);\n            });\n            if (folderSize > folderLimit) {\n              overSized.splice(startIndex, 0, str);\n            }\n          } else {\n            totalSize2 += s.size;\n            var str2 = (" ".padStart(level * 2, " ") + d[j]).padEnd(40, " ") + (humanSize(s.size).padStart(10, " ") + (isSymbolicLink ? "=> " + realPath : " "));\n            if (s.size > sizeLimit) {\n              overSized.push(str2);\n            }\n            tree2.push(str2);\n          }\n        }\n        return totalSize2;\n      }\n      function wrap(obj, name) {\n        var f = obj[name];\n        if (typeof f !== "function") return;\n        obj[name] = function() {\n          var args1 = Array.prototype.slice.call(arguments);\n          console.log(\n            "fs." + name,\n            args1.filter(function(x) {\n              return typeof x === "string";\n            })\n          );\n          return f.apply(this, args1);\n        };\n      }\n      console.log("------------------------------- virtual file system");\n      console.log(snapshotPrefix);\n      var tree = [];\n      var totalSize = dumpLevel(snapshotPrefix, 1, tree);\n      console.log(tree.join("\\n"));\n      console.log("Total size = ", humanSize(totalSize));\n      if (overSized.length > 0) {\n        console.log("------------------------------- oversized files");\n        console.log(overSized.join("\\n"));\n      }\n      if (process.env.DEBUG_PKG === "2") {\n        wrap(fs, "openSync");\n        wrap(fs, "open");\n        wrap(fs, "readSync");\n        wrap(fs, "read");\n        wrap(fs, "readFile");\n        wrap(fs, "writeSync");\n        wrap(fs, "write");\n        wrap(fs, "closeSync");\n        wrap(fs, "readFileSync");\n        wrap(fs, "close");\n        wrap(fs, "readdirSync");\n        wrap(fs, "readdir");\n        wrap(fs, "realpathSync");\n        wrap(fs, "realpath");\n        wrap(fs, "statSync");\n        wrap(fs, "stat");\n        wrap(fs, "lstatSync");\n        wrap(fs, "lstat");\n        wrap(fs, "fstatSync");\n        wrap(fs, "fstat");\n        wrap(fs, "existsSync");\n        wrap(fs, "exists");\n        wrap(fs, "accessSync");\n        wrap(fs, "access");\n        if (fs.promises) {\n          wrap(fs.promises, "open");\n          wrap(fs.promises, "read");\n          wrap(fs.promises, "readFile");\n          wrap(fs.promises, "write");\n          wrap(fs.promises, "readdir");\n          wrap(fs.promises, "realpath");\n          wrap(fs.promises, "stat");\n          wrap(fs.promises, "lstat");\n          wrap(fs.promises, "access");\n          wrap(fs.promises, "copyFile");\n        }\n      }\n    }\n    module2.exports = {\n      patchDlopen,\n      patchChildProcess,\n      setupProcessPkg,\n      installDiagnostic,\n      COMPRESS_NONE,\n      pickDecompressorSync,\n      pickDecompressorAsync\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/errors.js\nvar require_errors = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/errors.js"(exports2, module2) {\n    "use strict";\n    function createFsError(code, syscall, path, message) {\n      const msg = message || `${code}: ${getErrorDescription(code)}, ${syscall}${path ? ` \'${path}\'` : ""}`;\n      const err = new Error(msg);\n      err.code = code;\n      err.syscall = syscall;\n      if (path !== void 0) {\n        err.path = path;\n      }\n      Error.captureStackTrace(err, createFsError);\n      return err;\n    }\n    function getErrorDescription(code) {\n      switch (code) {\n        case "ENOENT":\n          return "no such file or directory";\n        case "ENOTDIR":\n          return "not a directory";\n        case "ENOTEMPTY":\n          return "directory not empty";\n        case "EISDIR":\n          return "illegal operation on a directory";\n        case "EBADF":\n          return "bad file descriptor";\n        case "EEXIST":\n          return "file already exists";\n        case "EROFS":\n          return "read-only file system";\n        case "EINVAL":\n          return "invalid argument";\n        case "ELOOP":\n          return "too many levels of symbolic links";\n        default:\n          return "unknown error";\n      }\n    }\n    function createENOENT(syscall, path) {\n      const err = createFsError("ENOENT", syscall, path);\n      Error.captureStackTrace(err, createENOENT);\n      return err;\n    }\n    function createENOTDIR(syscall, path) {\n      const err = createFsError("ENOTDIR", syscall, path);\n      Error.captureStackTrace(err, createENOTDIR);\n      return err;\n    }\n    function createENOTEMPTY(syscall, path) {\n      const err = createFsError("ENOTEMPTY", syscall, path);\n      Error.captureStackTrace(err, createENOTEMPTY);\n      return err;\n    }\n    function createEISDIR(syscall, path) {\n      const err = createFsError("EISDIR", syscall, path);\n      Error.captureStackTrace(err, createEISDIR);\n      return err;\n    }\n    function createEBADF(syscall) {\n      const err = createFsError("EBADF", syscall);\n      Error.captureStackTrace(err, createEBADF);\n      return err;\n    }\n    function createEEXIST(syscall, path) {\n      const err = createFsError("EEXIST", syscall, path);\n      Error.captureStackTrace(err, createEEXIST);\n      return err;\n    }\n    function createEROFS(syscall, path) {\n      const err = createFsError("EROFS", syscall, path);\n      Error.captureStackTrace(err, createEROFS);\n      return err;\n    }\n    function createEINVAL(syscall, path) {\n      const err = createFsError("EINVAL", syscall, path);\n      Error.captureStackTrace(err, createEINVAL);\n      return err;\n    }\n    function createELOOP(syscall, path) {\n      const err = createFsError("ELOOP", syscall, path);\n      Error.captureStackTrace(err, createELOOP);\n      return err;\n    }\n    var ERR_METHOD_NOT_IMPLEMENTED = class extends Error {\n      constructor(method) {\n        super(`The ${method} method is not implemented`);\n        this.code = "ERR_METHOD_NOT_IMPLEMENTED";\n      }\n    };\n    var ERR_INVALID_STATE = class extends Error {\n      constructor(message) {\n        super(`Invalid state: ${message}`);\n        this.code = "ERR_INVALID_STATE";\n      }\n    };\n    var ERR_INVALID_ARG_VALUE = class extends TypeError {\n      constructor(name, value, reason) {\n        super(`The argument \'${name}\' ${reason}. Received ${typeof value === "string" ? `\'${value}\'` : String(value)}`);\n        this.code = "ERR_INVALID_ARG_VALUE";\n      }\n    };\n    module2.exports = {\n      createENOENT,\n      createENOTDIR,\n      createENOTEMPTY,\n      createEISDIR,\n      createEBADF,\n      createEEXIST,\n      createEROFS,\n      createEINVAL,\n      createELOOP,\n      ERR_METHOD_NOT_IMPLEMENTED,\n      ERR_INVALID_STATE,\n      ERR_INVALID_ARG_VALUE\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/provider.js\nvar require_provider = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/provider.js"(exports2, module2) {\n    "use strict";\n    var {\n      ERR_METHOD_NOT_IMPLEMENTED,\n      createEROFS\n    } = require_errors();\n    var VirtualProvider = class {\n      get readonly() {\n        return false;\n      }\n      get supportsSymlinks() {\n        return false;\n      }\n      get supportsWatch() {\n        return false;\n      }\n      // === ESSENTIAL PRIMITIVES ===\n      async open(path, flags, mode) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("open");\n      }\n      openSync(path, flags, mode) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("openSync");\n      }\n      async stat(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("stat");\n      }\n      statSync(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("statSync");\n      }\n      async lstat(path, options) {\n        return this.stat(path, options);\n      }\n      lstatSync(path, options) {\n        return this.statSync(path, options);\n      }\n      async readdir(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readdir");\n      }\n      readdirSync(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readdirSync");\n      }\n      async mkdir(path, options) {\n        if (this.readonly) {\n          throw createEROFS("mkdir", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("mkdir");\n      }\n      mkdirSync(path, options) {\n        if (this.readonly) {\n          throw createEROFS("mkdir", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("mkdirSync");\n      }\n      async rmdir(path) {\n        if (this.readonly) {\n          throw createEROFS("rmdir", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("rmdir");\n      }\n      rmdirSync(path) {\n        if (this.readonly) {\n          throw createEROFS("rmdir", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("rmdirSync");\n      }\n      async unlink(path) {\n        if (this.readonly) {\n          throw createEROFS("unlink", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("unlink");\n      }\n      unlinkSync(path) {\n        if (this.readonly) {\n          throw createEROFS("unlink", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("unlinkSync");\n      }\n      async rename(oldPath, newPath) {\n        if (this.readonly) {\n          throw createEROFS("rename", oldPath);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("rename");\n      }\n      renameSync(oldPath, newPath) {\n        if (this.readonly) {\n          throw createEROFS("rename", oldPath);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("renameSync");\n      }\n      // === DEFAULT IMPLEMENTATIONS ===\n      async readFile(path, options) {\n        const handle = await this.open(path, "r");\n        try {\n          return await handle.readFile(options);\n        } finally {\n          await handle.close();\n        }\n      }\n      readFileSync(path, options) {\n        const handle = this.openSync(path, "r");\n        try {\n          return handle.readFileSync(options);\n        } finally {\n          handle.closeSync();\n        }\n      }\n      async writeFile(path, data, options) {\n        if (this.readonly) {\n          throw createEROFS("open", path);\n        }\n        const handle = await this.open(path, "w", options?.mode);\n        try {\n          await handle.writeFile(data, options);\n        } finally {\n          await handle.close();\n        }\n      }\n      writeFileSync(path, data, options) {\n        if (this.readonly) {\n          throw createEROFS("open", path);\n        }\n        const handle = this.openSync(path, "w", options?.mode);\n        try {\n          handle.writeFileSync(data, options);\n        } finally {\n          handle.closeSync();\n        }\n      }\n      async appendFile(path, data, options) {\n        if (this.readonly) {\n          throw createEROFS("open", path);\n        }\n        const handle = await this.open(path, "a", options?.mode);\n        try {\n          await handle.writeFile(data, options);\n        } finally {\n          await handle.close();\n        }\n      }\n      appendFileSync(path, data, options) {\n        if (this.readonly) {\n          throw createEROFS("open", path);\n        }\n        const handle = this.openSync(path, "a", options?.mode);\n        try {\n          handle.writeFileSync(data, options);\n        } finally {\n          handle.closeSync();\n        }\n      }\n      async exists(path) {\n        try {\n          await this.stat(path);\n          return true;\n        } catch {\n          return false;\n        }\n      }\n      existsSync(path) {\n        try {\n          this.statSync(path);\n          return true;\n        } catch {\n          return false;\n        }\n      }\n      async copyFile(src, dest, mode) {\n        if (this.readonly) {\n          throw createEROFS("copyfile", dest);\n        }\n        const content = await this.readFile(src);\n        await this.writeFile(dest, content);\n      }\n      copyFileSync(src, dest, mode) {\n        if (this.readonly) {\n          throw createEROFS("copyfile", dest);\n        }\n        const content = this.readFileSync(src);\n        this.writeFileSync(dest, content);\n      }\n      internalModuleStat(path) {\n        try {\n          const stats = this.statSync(path);\n          if (stats.isDirectory()) {\n            return 1;\n          }\n          return 0;\n        } catch {\n          return -2;\n        }\n      }\n      async realpath(path, options) {\n        await this.stat(path);\n        return path;\n      }\n      realpathSync(path, options) {\n        this.statSync(path);\n        return path;\n      }\n      async access(path, mode) {\n        await this.stat(path);\n      }\n      accessSync(path, mode) {\n        this.statSync(path);\n      }\n      // === SYMLINK OPERATIONS ===\n      async readlink(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readlink");\n      }\n      readlinkSync(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readlinkSync");\n      }\n      async symlink(target, path, type) {\n        if (this.readonly) {\n          throw createEROFS("symlink", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("symlink");\n      }\n      symlinkSync(target, path, type) {\n        if (this.readonly) {\n          throw createEROFS("symlink", path);\n        }\n        throw new ERR_METHOD_NOT_IMPLEMENTED("symlinkSync");\n      }\n      // === WATCH OPERATIONS ===\n      watch(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("watch");\n      }\n      watchAsync(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("watchAsync");\n      }\n      watchFile(path, options) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("watchFile");\n      }\n      unwatchFile(path, listener) {\n        throw new ERR_METHOD_NOT_IMPLEMENTED("unwatchFile");\n      }\n    };\n    module2.exports = {\n      VirtualProvider\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/file_handle.js\nvar require_file_handle = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/file_handle.js"(exports2, module2) {\n    "use strict";\n    var { Buffer: Buffer2 } = require("node:buffer");\n    var {\n      createEBADF,\n      ERR_METHOD_NOT_IMPLEMENTED,\n      ERR_INVALID_STATE\n    } = require_errors();\n    var kPath = /* @__PURE__ */ Symbol("kPath");\n    var kFlags = /* @__PURE__ */ Symbol("kFlags");\n    var kMode = /* @__PURE__ */ Symbol("kMode");\n    var kPosition = /* @__PURE__ */ Symbol("kPosition");\n    var kClosed = /* @__PURE__ */ Symbol("kClosed");\n    var VirtualFileHandle = class {\n      constructor(path, flags, mode) {\n        this[kPath] = path;\n        this[kFlags] = flags;\n        this[kMode] = mode ?? 420;\n        this[kPosition] = 0;\n        this[kClosed] = false;\n      }\n      get path() {\n        return this[kPath];\n      }\n      get flags() {\n        return this[kFlags];\n      }\n      get mode() {\n        return this[kMode];\n      }\n      get position() {\n        return this[kPosition];\n      }\n      set position(pos) {\n        this[kPosition] = pos;\n      }\n      get closed() {\n        return this[kClosed];\n      }\n      #checkClosed() {\n        if (this[kClosed]) {\n          throw createEBADF("read");\n        }\n      }\n      async read(buffer, offset, length, position) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("read");\n      }\n      readSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readSync");\n      }\n      async write(buffer, offset, length, position) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("write");\n      }\n      writeSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("writeSync");\n      }\n      async readFile(options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readFile");\n      }\n      readFileSync(options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("readFileSync");\n      }\n      async writeFile(data, options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("writeFile");\n      }\n      writeFileSync(data, options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("writeFileSync");\n      }\n      async stat(options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("stat");\n      }\n      statSync(options) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("statSync");\n      }\n      async truncate(len) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("truncate");\n      }\n      truncateSync(len) {\n        this.#checkClosed();\n        throw new ERR_METHOD_NOT_IMPLEMENTED("truncateSync");\n      }\n      async close() {\n        this[kClosed] = true;\n      }\n      closeSync() {\n        this[kClosed] = true;\n      }\n    };\n    var MemoryFileHandle = class extends VirtualFileHandle {\n      #content;\n      #entry;\n      #getStats;\n      #checkClosed() {\n        if (this.closed) {\n          throw createEBADF("read");\n        }\n      }\n      constructor(path, flags, mode, content, entry, getStats) {\n        super(path, flags, mode);\n        this.#content = content;\n        this.#entry = entry;\n        this.#getStats = getStats;\n        if (flags === "w" || flags === "w+") {\n          this.#content = Buffer2.alloc(0);\n          if (entry) {\n            entry.content = this.#content;\n          }\n        } else if (flags === "a" || flags === "a+") {\n          this.position = this.#content.length;\n        }\n      }\n      get content() {\n        if (this.#entry?.isDynamic && this.#entry.isDynamic()) {\n          return this.#entry.getContentSync();\n        }\n        return this.#content;\n      }\n      async getContentAsync() {\n        if (this.#entry?.getContentAsync) {\n          return this.#entry.getContentAsync();\n        }\n        return this.#content;\n      }\n      readSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        const content = this.content;\n        const readPos = position !== null && position !== void 0 ? position : this.position;\n        const available = content.length - readPos;\n        if (available <= 0) {\n          return 0;\n        }\n        const bytesToRead = Math.min(length, available);\n        content.copy(buffer, offset, readPos, readPos + bytesToRead);\n        if (position === null || position === void 0) {\n          this.position = readPos + bytesToRead;\n        }\n        return bytesToRead;\n      }\n      async read(buffer, offset, length, position) {\n        const bytesRead = this.readSync(buffer, offset, length, position);\n        return { bytesRead, buffer };\n      }\n      writeSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        const writePos = position !== null && position !== void 0 ? position : this.position;\n        const data = buffer.subarray(offset, offset + length);\n        if (writePos + length > this.#content.length) {\n          const newContent = Buffer2.alloc(writePos + length);\n          this.#content.copy(newContent, 0, 0, this.#content.length);\n          this.#content = newContent;\n        }\n        data.copy(this.#content, writePos);\n        if (this.#entry) {\n          this.#entry.content = this.#content;\n          this.#entry.mtime = Date.now();\n        }\n        if (position === null || position === void 0) {\n          this.position = writePos + length;\n        }\n        return length;\n      }\n      async write(buffer, offset, length, position) {\n        const bytesWritten = this.writeSync(buffer, offset, length, position);\n        return { bytesWritten, buffer };\n      }\n      readFileSync(options) {\n        this.#checkClosed();\n        const content = this.content;\n        const encoding = typeof options === "string" ? options : options?.encoding;\n        if (encoding) {\n          return content.toString(encoding);\n        }\n        return Buffer2.from(content);\n      }\n      async readFile(options) {\n        this.#checkClosed();\n        const content = await this.getContentAsync();\n        const encoding = typeof options === "string" ? options : options?.encoding;\n        if (encoding) {\n          return content.toString(encoding);\n        }\n        return Buffer2.from(content);\n      }\n      writeFileSync(data, options) {\n        this.#checkClosed();\n        const buffer = typeof data === "string" ? Buffer2.from(data, options?.encoding) : data;\n        if (this.flags === "a" || this.flags === "a+") {\n          const newContent = Buffer2.alloc(this.#content.length + buffer.length);\n          this.#content.copy(newContent, 0);\n          buffer.copy(newContent, this.#content.length);\n          this.#content = newContent;\n        } else {\n          this.#content = Buffer2.from(buffer);\n        }\n        if (this.#entry) {\n          this.#entry.content = this.#content;\n          this.#entry.mtime = Date.now();\n        }\n        this.position = this.#content.length;\n      }\n      async writeFile(data, options) {\n        this.writeFileSync(data, options);\n      }\n      statSync(options) {\n        this.#checkClosed();\n        if (this.#getStats) {\n          return this.#getStats(this.#content.length);\n        }\n        throw new ERR_INVALID_STATE("stats not available");\n      }\n      async stat(options) {\n        return this.statSync(options);\n      }\n      truncateSync(len = 0) {\n        this.#checkClosed();\n        if (len < this.#content.length) {\n          this.#content = this.#content.subarray(0, len);\n        } else if (len > this.#content.length) {\n          const newContent = Buffer2.alloc(len);\n          this.#content.copy(newContent, 0, 0, this.#content.length);\n          this.#content = newContent;\n        }\n        if (this.#entry) {\n          this.#entry.content = this.#content;\n          this.#entry.mtime = Date.now();\n        }\n      }\n      async truncate(len) {\n        this.truncateSync(len);\n      }\n    };\n    module2.exports = {\n      VirtualFileHandle,\n      MemoryFileHandle\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/stats.js\nvar require_stats = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/stats.js"(exports2, module2) {\n    "use strict";\n    var S_IFMT = 61440;\n    var S_IFREG = 32768;\n    var S_IFDIR = 16384;\n    var S_IFLNK = 40960;\n    var kDefaultBlockSize = 4096;\n    var VirtualStats = class {\n      constructor(props) {\n        this.dev = props.dev ?? 0;\n        this.mode = props.mode;\n        this.nlink = props.nlink ?? 1;\n        this.uid = props.uid ?? (process.getuid?.() ?? 0);\n        this.gid = props.gid ?? (process.getgid?.() ?? 0);\n        this.rdev = props.rdev ?? 0;\n        this.blksize = props.blksize ?? kDefaultBlockSize;\n        this.ino = props.ino ?? 0;\n        this.size = props.size;\n        this.blocks = props.blocks ?? Math.ceil(props.size / 512);\n        this.atimeMs = props.atimeMs;\n        this.mtimeMs = props.mtimeMs;\n        this.ctimeMs = props.ctimeMs;\n        this.birthtimeMs = props.birthtimeMs;\n        this.atime = new Date(this.atimeMs);\n        this.mtime = new Date(this.mtimeMs);\n        this.ctime = new Date(this.ctimeMs);\n        this.birthtime = new Date(this.birthtimeMs);\n      }\n      isFile() {\n        return (this.mode & S_IFMT) === S_IFREG;\n      }\n      isDirectory() {\n        return (this.mode & S_IFMT) === S_IFDIR;\n      }\n      isSymbolicLink() {\n        return (this.mode & S_IFMT) === S_IFLNK;\n      }\n      isBlockDevice() {\n        return false;\n      }\n      isCharacterDevice() {\n        return false;\n      }\n      isFIFO() {\n        return false;\n      }\n      isSocket() {\n        return false;\n      }\n    };\n    function createFileStats(size, options = {}) {\n      const now = Date.now();\n      return new VirtualStats({\n        mode: (options.mode ?? 420) | S_IFREG,\n        size,\n        atimeMs: options.atimeMs ?? now,\n        mtimeMs: options.mtimeMs ?? now,\n        ctimeMs: options.ctimeMs ?? now,\n        birthtimeMs: options.birthtimeMs ?? now\n      });\n    }\n    function createDirectoryStats(options = {}) {\n      const now = Date.now();\n      return new VirtualStats({\n        mode: (options.mode ?? 493) | S_IFDIR,\n        size: kDefaultBlockSize,\n        blocks: 8,\n        atimeMs: options.atimeMs ?? now,\n        mtimeMs: options.mtimeMs ?? now,\n        ctimeMs: options.ctimeMs ?? now,\n        birthtimeMs: options.birthtimeMs ?? now\n      });\n    }\n    function createSymlinkStats(size, options = {}) {\n      const now = Date.now();\n      return new VirtualStats({\n        mode: (options.mode ?? 511) | S_IFLNK,\n        size,\n        atimeMs: options.atimeMs ?? now,\n        mtimeMs: options.mtimeMs ?? now,\n        ctimeMs: options.ctimeMs ?? now,\n        birthtimeMs: options.birthtimeMs ?? now\n      });\n    }\n    module2.exports = {\n      VirtualStats,\n      createFileStats,\n      createDirectoryStats,\n      createSymlinkStats,\n      S_IFMT,\n      S_IFREG,\n      S_IFDIR,\n      S_IFLNK\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/watcher.js\nvar require_watcher = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/watcher.js"(exports2, module2) {\n    "use strict";\n    var { EventEmitter } = require("node:events");\n    var { basename, join } = require("node:path");\n    var VFSWatcher = class extends EventEmitter {\n      #vfs;\n      #path;\n      #interval;\n      #timer = null;\n      #lastStats;\n      #closed = false;\n      #persistent;\n      #recursive;\n      #trackedFiles;\n      #signal;\n      #abortHandler = null;\n      constructor(provider, path, options = {}) {\n        super();\n        this.#vfs = provider;\n        this.#path = path;\n        this.#interval = options.interval ?? 100;\n        this.#persistent = options.persistent !== false;\n        this.#recursive = options.recursive === true;\n        this.#trackedFiles = /* @__PURE__ */ new Map();\n        this.#signal = options.signal;\n        if (this.#signal) {\n          if (this.#signal.aborted) {\n            this.close();\n            return;\n          }\n          this.#abortHandler = () => this.close();\n          this.#signal.addEventListener("abort", this.#abortHandler, { once: true });\n        }\n        this.#lastStats = this.#getStats();\n        if (this.#recursive && this.#lastStats?.isDirectory()) {\n          this.#buildFileList(this.#path, "");\n        }\n        this.#startPolling();\n      }\n      #getStats() {\n        try {\n          return this.#vfs.statSync(this.#path);\n        } catch {\n          return null;\n        }\n      }\n      #startPolling() {\n        if (this.#closed) return;\n        this.#timer = setInterval(() => this.#poll(), this.#interval);\n        if (!this.#persistent && this.#timer.unref) {\n          this.#timer.unref();\n        }\n      }\n      #poll() {\n        if (this.#closed) return;\n        if (this.#recursive && this.#trackedFiles.size > 0) {\n          for (const [filePath, info] of this.#trackedFiles) {\n            const newStats2 = this.#getStatsFor(filePath);\n            if (this.#statsChanged(info.stats, newStats2)) {\n              const eventType = this.#determineEventType(info.stats, newStats2);\n              this.emit("change", eventType, info.relativePath);\n              info.stats = newStats2;\n            }\n          }\n          return;\n        }\n        const newStats = this.#getStats();\n        if (this.#statsChanged(this.#lastStats, newStats)) {\n          const eventType = this.#determineEventType(this.#lastStats, newStats);\n          const filename = basename(this.#path);\n          this.emit("change", eventType, filename);\n        }\n        this.#lastStats = newStats;\n      }\n      #getStatsFor(filePath) {\n        try {\n          return this.#vfs.statSync(filePath);\n        } catch {\n          return null;\n        }\n      }\n      #buildFileList(dirPath, relativePath) {\n        try {\n          const entries = this.#vfs.readdirSync(dirPath, { withFileTypes: true });\n          for (const entry of entries) {\n            const fullPath = join(dirPath, entry.name);\n            const relPath = relativePath ? join(relativePath, entry.name) : entry.name;\n            if (entry.isDirectory()) {\n              this.#buildFileList(fullPath, relPath);\n            } else {\n              const stats = this.#getStatsFor(fullPath);\n              this.#trackedFiles.set(fullPath, {\n                stats,\n                relativePath: relPath\n              });\n            }\n          }\n        } catch {\n        }\n      }\n      #statsChanged(oldStats, newStats) {\n        if (oldStats === null !== (newStats === null)) {\n          return true;\n        }\n        if (oldStats === null && newStats === null) {\n          return false;\n        }\n        if (oldStats.mtimeMs !== newStats.mtimeMs) {\n          return true;\n        }\n        if (oldStats.size !== newStats.size) {\n          return true;\n        }\n        return false;\n      }\n      #determineEventType(oldStats, newStats) {\n        if (oldStats === null !== (newStats === null)) {\n          return "rename";\n        }\n        return "change";\n      }\n      close() {\n        if (this.#closed) return;\n        this.#closed = true;\n        if (this.#timer) {\n          clearInterval(this.#timer);\n          this.#timer = null;\n        }\n        this.#trackedFiles.clear();\n        if (this.#signal && this.#abortHandler) {\n          this.#signal.removeEventListener("abort", this.#abortHandler);\n        }\n        this.emit("close");\n      }\n      unref() {\n        this.#timer?.unref?.();\n        return this;\n      }\n      ref() {\n        this.#timer?.ref?.();\n        return this;\n      }\n    };\n    var VFSStatWatcher = class extends EventEmitter {\n      #vfs;\n      #path;\n      #interval;\n      #persistent;\n      #closed = false;\n      #timer = null;\n      #lastStats;\n      #listeners;\n      constructor(provider, path, options = {}) {\n        super();\n        this.#vfs = provider;\n        this.#path = path;\n        this.#interval = options.interval ?? 5007;\n        this.#persistent = options.persistent !== false;\n        this.#listeners = /* @__PURE__ */ new Set();\n        this.#lastStats = this.#getStats();\n        this.#startPolling();\n      }\n      #getStats() {\n        try {\n          return this.#vfs.statSync(this.#path);\n        } catch {\n          const { createFileStats } = require_stats();\n          return createFileStats(0, {\n            mode: 0,\n            mtimeMs: 0,\n            ctimeMs: 0,\n            birthtimeMs: 0\n          });\n        }\n      }\n      #startPolling() {\n        if (this.#closed) return;\n        this.#timer = setInterval(() => this.#poll(), this.#interval);\n        if (!this.#persistent && this.#timer.unref) {\n          this.#timer.unref();\n        }\n      }\n      #poll() {\n        if (this.#closed) return;\n        const newStats = this.#getStats();\n        if (this.#statsChanged(this.#lastStats, newStats)) {\n          const prevStats = this.#lastStats;\n          this.#lastStats = newStats;\n          this.emit("change", newStats, prevStats);\n        }\n      }\n      #statsChanged(oldStats, newStats) {\n        if (oldStats.mtimeMs !== newStats.mtimeMs) {\n          return true;\n        }\n        if (oldStats.ctimeMs !== newStats.ctimeMs) {\n          return true;\n        }\n        if (oldStats.size !== newStats.size) {\n          return true;\n        }\n        return false;\n      }\n      addListener(listener) {\n        this.#listeners.add(listener);\n        this.on("change", listener);\n      }\n      removeListener(listener) {\n        const had = this.#listeners.has(listener);\n        this.#listeners.delete(listener);\n        super.removeListener("change", listener);\n        return had;\n      }\n      hasNoListeners() {\n        return this.#listeners.size === 0;\n      }\n      stop() {\n        if (this.#closed) return;\n        this.#closed = true;\n        if (this.#timer) {\n          clearInterval(this.#timer);\n          this.#timer = null;\n        }\n        this.emit("stop");\n      }\n      unref() {\n        this.#timer?.unref?.();\n        return this;\n      }\n      ref() {\n        this.#timer?.ref?.();\n        return this;\n      }\n    };\n    var VFSWatchAsyncIterable = class {\n      #watcher;\n      #closed = false;\n      #pendingEvents = [];\n      #pendingResolvers = [];\n      constructor(provider, path, options = {}) {\n        this.#watcher = new VFSWatcher(provider, path, options);\n        this.#watcher.on("change", (eventType, filename) => {\n          const event = { eventType, filename };\n          if (this.#pendingResolvers.length > 0) {\n            const resolve = this.#pendingResolvers.shift();\n            resolve({ value: event, done: false });\n          } else {\n            this.#pendingEvents.push(event);\n          }\n        });\n        this.#watcher.on("close", () => {\n          this.#closed = true;\n          while (this.#pendingResolvers.length > 0) {\n            const resolve = this.#pendingResolvers.shift();\n            resolve({ value: void 0, done: true });\n          }\n        });\n      }\n      [Symbol.asyncIterator]() {\n        return this;\n      }\n      next() {\n        if (this.#closed) {\n          return Promise.resolve({ value: void 0, done: true });\n        }\n        if (this.#pendingEvents.length > 0) {\n          const event = this.#pendingEvents.shift();\n          return Promise.resolve({ value: event, done: false });\n        }\n        return new Promise((resolve) => {\n          this.#pendingResolvers.push(resolve);\n        });\n      }\n      return() {\n        this.#watcher.close();\n        return Promise.resolve({ value: void 0, done: true });\n      }\n      throw(error) {\n        this.#watcher.close();\n        return Promise.resolve({ value: void 0, done: true });\n      }\n    };\n    module2.exports = {\n      VFSWatcher,\n      VFSStatWatcher,\n      VFSWatchAsyncIterable\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/providers/memory.js\nvar require_memory = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/providers/memory.js"(exports2, module2) {\n    "use strict";\n    var { Buffer: Buffer2 } = require("node:buffer");\n    var { posix: pathPosix } = require("node:path");\n    var { VirtualProvider } = require_provider();\n    var { MemoryFileHandle } = require_file_handle();\n    var {\n      VFSWatcher,\n      VFSStatWatcher,\n      VFSWatchAsyncIterable\n    } = require_watcher();\n    var {\n      ERR_INVALID_STATE\n    } = require_errors();\n    var {\n      createENOENT,\n      createENOTDIR,\n      createENOTEMPTY,\n      createEISDIR,\n      createEEXIST,\n      createEINVAL,\n      createELOOP,\n      createEROFS\n    } = require_errors();\n    var {\n      createFileStats,\n      createDirectoryStats,\n      createSymlinkStats\n    } = require_stats();\n    var UV_DIRENT_FILE = 1;\n    var UV_DIRENT_DIR = 2;\n    var UV_DIRENT_LINK = 3;\n    var VirtualDirent = class {\n      #name;\n      #type;\n      #parentPath;\n      constructor(name, type, parentPath) {\n        this.#name = name;\n        this.#type = type;\n        this.#parentPath = parentPath;\n      }\n      get name() {\n        return this.#name;\n      }\n      get parentPath() {\n        return this.#parentPath;\n      }\n      get path() {\n        return this.#parentPath;\n      }\n      isFile() {\n        return this.#type === UV_DIRENT_FILE;\n      }\n      isDirectory() {\n        return this.#type === UV_DIRENT_DIR;\n      }\n      isSymbolicLink() {\n        return this.#type === UV_DIRENT_LINK;\n      }\n      isBlockDevice() {\n        return false;\n      }\n      isCharacterDevice() {\n        return false;\n      }\n      isFIFO() {\n        return false;\n      }\n      isSocket() {\n        return false;\n      }\n    };\n    var kRoot = /* @__PURE__ */ Symbol("kRoot");\n    var kReadonly = /* @__PURE__ */ Symbol("kReadonly");\n    var kStatWatchers = /* @__PURE__ */ Symbol("kStatWatchers");\n    var TYPE_FILE = 0;\n    var TYPE_DIR = 1;\n    var TYPE_SYMLINK = 2;\n    var kMaxSymlinkDepth = 40;\n    var MemoryEntry = class {\n      constructor(type, options = {}) {\n        this.type = type;\n        this.mode = options.mode ?? (type === TYPE_DIR ? 493 : 420);\n        this.content = null;\n        this.contentProvider = null;\n        this.target = null;\n        this.children = null;\n        this.populate = null;\n        this.populated = true;\n        const now = Date.now();\n        this.mtime = now;\n        this.ctime = now;\n        this.birthtime = now;\n      }\n      getContentSync() {\n        if (this.contentProvider !== null) {\n          const result = this.contentProvider();\n          if (result && typeof result.then === "function") {\n            throw new ERR_INVALID_STATE("cannot use sync API with async content provider");\n          }\n          return typeof result === "string" ? Buffer2.from(result) : result;\n        }\n        return this.content;\n      }\n      async getContentAsync() {\n        if (this.contentProvider !== null) {\n          const result = await this.contentProvider();\n          return typeof result === "string" ? Buffer2.from(result) : result;\n        }\n        return this.content;\n      }\n      isDynamic() {\n        return this.contentProvider !== null;\n      }\n      isFile() {\n        return this.type === TYPE_FILE;\n      }\n      isDirectory() {\n        return this.type === TYPE_DIR;\n      }\n      isSymbolicLink() {\n        return this.type === TYPE_SYMLINK;\n      }\n    };\n    var MemoryProvider = class extends VirtualProvider {\n      constructor() {\n        super();\n        this[kRoot] = new MemoryEntry(TYPE_DIR);\n        this[kRoot].children = /* @__PURE__ */ new Map();\n        this[kReadonly] = false;\n        this[kStatWatchers] = /* @__PURE__ */ new Map();\n      }\n      get readonly() {\n        return this[kReadonly];\n      }\n      get supportsWatch() {\n        return true;\n      }\n      setReadOnly() {\n        this[kReadonly] = true;\n      }\n      get supportsSymlinks() {\n        return true;\n      }\n      #normalizePath(path) {\n        let normalized = path.replace(/\\\\/g, "/");\n        if (!normalized.startsWith("/")) {\n          normalized = "/" + normalized;\n        }\n        return pathPosix.normalize(normalized);\n      }\n      #splitPath(path) {\n        if (path === "/") {\n          return [];\n        }\n        return path.slice(1).split("/");\n      }\n      #getParentPath(path) {\n        if (path === "/") {\n          return null;\n        }\n        return pathPosix.dirname(path);\n      }\n      #getBaseName(path) {\n        return pathPosix.basename(path);\n      }\n      #resolveSymlinkTarget(symlinkPath, target) {\n        if (target.startsWith("/")) {\n          return this.#normalizePath(target);\n        }\n        const parentPath = this.#getParentPath(symlinkPath) || "/";\n        return this.#normalizePath(pathPosix.join(parentPath, target));\n      }\n      #lookupEntry(path, followSymlinks = true, depth = 0) {\n        const normalized = this.#normalizePath(path);\n        if (normalized === "/") {\n          return { entry: this[kRoot], resolvedPath: "/" };\n        }\n        const segments = this.#splitPath(normalized);\n        let current = this[kRoot];\n        let currentPath = "/";\n        for (let i = 0; i < segments.length; i++) {\n          const segment = segments[i];\n          if (current.isSymbolicLink() && followSymlinks) {\n            if (depth >= kMaxSymlinkDepth) {\n              return { entry: null, resolvedPath: null, eloop: true };\n            }\n            const targetPath = this.#resolveSymlinkTarget(currentPath, current.target);\n            const result = this.#lookupEntry(targetPath, true, depth + 1);\n            if (result.eloop) {\n              return result;\n            }\n            if (!result.entry) {\n              return { entry: null, resolvedPath: null };\n            }\n            current = result.entry;\n            currentPath = result.resolvedPath;\n          }\n          if (!current.isDirectory()) {\n            return { entry: null, resolvedPath: null };\n          }\n          this.#ensurePopulated(current, currentPath);\n          const entry = current.children.get(segment);\n          if (!entry) {\n            return { entry: null, resolvedPath: null };\n          }\n          currentPath = pathPosix.join(currentPath, segment);\n          current = entry;\n        }\n        if (current.isSymbolicLink() && followSymlinks) {\n          if (depth >= kMaxSymlinkDepth) {\n            return { entry: null, resolvedPath: null, eloop: true };\n          }\n          const targetPath = this.#resolveSymlinkTarget(currentPath, current.target);\n          return this.#lookupEntry(targetPath, true, depth + 1);\n        }\n        return { entry: current, resolvedPath: currentPath };\n      }\n      #getEntry(path, syscall, followSymlinks = true) {\n        const result = this.#lookupEntry(path, followSymlinks);\n        if (result.eloop) {\n          throw createELOOP(syscall, path);\n        }\n        if (!result.entry) {\n          throw createENOENT(syscall, path);\n        }\n        return result.entry;\n      }\n      #ensureParent(path, create, syscall) {\n        const parentPath = this.#getParentPath(path);\n        if (parentPath === null) {\n          return this[kRoot];\n        }\n        const segments = this.#splitPath(parentPath);\n        let current = this[kRoot];\n        for (let i = 0; i < segments.length; i++) {\n          const segment = segments[i];\n          if (current.isSymbolicLink()) {\n            const currentPath2 = pathPosix.join("/", ...segments.slice(0, i));\n            const targetPath = this.#resolveSymlinkTarget(currentPath2, current.target);\n            const result = this.#lookupEntry(targetPath, true, 0);\n            if (!result.entry) {\n              throw createENOENT(syscall, path);\n            }\n            current = result.entry;\n          }\n          if (!current.isDirectory()) {\n            throw createENOTDIR(syscall, path);\n          }\n          const currentPath = pathPosix.join("/", ...segments.slice(0, i));\n          this.#ensurePopulated(current, currentPath);\n          let entry = current.children.get(segment);\n          if (!entry) {\n            if (create) {\n              entry = new MemoryEntry(TYPE_DIR);\n              entry.children = /* @__PURE__ */ new Map();\n              current.children.set(segment, entry);\n            } else {\n              throw createENOENT(syscall, path);\n            }\n          }\n          current = entry;\n        }\n        if (!current.isDirectory()) {\n          throw createENOTDIR(syscall, path);\n        }\n        const finalPath = pathPosix.join("/", ...segments);\n        this.#ensurePopulated(current, finalPath);\n        return current;\n      }\n      #createStats(entry, size) {\n        const options = {\n          mode: entry.mode,\n          mtimeMs: entry.mtime,\n          ctimeMs: entry.ctime,\n          birthtimeMs: entry.birthtime\n        };\n        if (entry.isFile()) {\n          return createFileStats(size !== void 0 ? size : entry.content.length, options);\n        } else if (entry.isDirectory()) {\n          return createDirectoryStats(options);\n        } else if (entry.isSymbolicLink()) {\n          return createSymlinkStats(entry.target.length, options);\n        }\n        throw new ERR_INVALID_STATE("Unknown entry type");\n      }\n      #ensurePopulated(entry, path) {\n        if (entry.isDirectory() && !entry.populated && entry.populate) {\n          const scopedVfs = {\n            addFile: (name, content, opts) => {\n              const fileEntry = new MemoryEntry(TYPE_FILE, opts);\n              if (typeof content === "function") {\n                fileEntry.content = Buffer2.alloc(0);\n                fileEntry.contentProvider = content;\n              } else {\n                fileEntry.content = typeof content === "string" ? Buffer2.from(content) : content;\n              }\n              entry.children.set(name, fileEntry);\n            },\n            addDirectory: (name, populate, opts) => {\n              const dirEntry = new MemoryEntry(TYPE_DIR, opts);\n              dirEntry.children = /* @__PURE__ */ new Map();\n              if (typeof populate === "function") {\n                dirEntry.populate = populate;\n                dirEntry.populated = false;\n              }\n              entry.children.set(name, dirEntry);\n            },\n            addSymlink: (name, target, opts) => {\n              const symlinkEntry = new MemoryEntry(TYPE_SYMLINK, opts);\n              symlinkEntry.target = target;\n              entry.children.set(name, symlinkEntry);\n            }\n          };\n          entry.populate(scopedVfs);\n          entry.populated = true;\n        }\n      }\n      openSync(path, flags, mode) {\n        const normalized = this.#normalizePath(path);\n        const isCreate = flags === "w" || flags === "w+" || flags === "a" || flags === "a+";\n        if (this.readonly && isCreate) {\n          throw createEROFS("open", path);\n        }\n        let entry;\n        try {\n          entry = this.#getEntry(normalized, "open");\n        } catch (err) {\n          if (err.code === "ENOENT" && isCreate) {\n            const parent = this.#ensureParent(normalized, true, "open");\n            const name = this.#getBaseName(normalized);\n            entry = new MemoryEntry(TYPE_FILE, { mode });\n            entry.content = Buffer2.alloc(0);\n            parent.children.set(name, entry);\n          } else {\n            throw err;\n          }\n        }\n        if (entry.isDirectory()) {\n          throw createEISDIR("open", path);\n        }\n        if (entry.isSymbolicLink()) {\n          throw createEINVAL("open", path);\n        }\n        const getStats = (size) => this.#createStats(entry, size);\n        return new MemoryFileHandle(normalized, flags, mode ?? entry.mode, entry.content, entry, getStats);\n      }\n      async open(path, flags, mode) {\n        return this.openSync(path, flags, mode);\n      }\n      statSync(path, options) {\n        const entry = this.#getEntry(path, "stat", true);\n        return this.#createStats(entry);\n      }\n      async stat(path, options) {\n        return this.statSync(path, options);\n      }\n      lstatSync(path, options) {\n        const entry = this.#getEntry(path, "lstat", false);\n        return this.#createStats(entry);\n      }\n      async lstat(path, options) {\n        return this.lstatSync(path, options);\n      }\n      readdirSync(path, options) {\n        const entry = this.#getEntry(path, "scandir", true);\n        if (!entry.isDirectory()) {\n          throw createENOTDIR("scandir", path);\n        }\n        this.#ensurePopulated(entry, path);\n        const names = [...entry.children.keys()];\n        if (options?.withFileTypes) {\n          const normalized = this.#normalizePath(path);\n          const dirents = [];\n          for (const name of names) {\n            const childEntry = entry.children.get(name);\n            let type;\n            if (childEntry.isSymbolicLink()) {\n              type = UV_DIRENT_LINK;\n            } else if (childEntry.isDirectory()) {\n              type = UV_DIRENT_DIR;\n            } else {\n              type = UV_DIRENT_FILE;\n            }\n            dirents.push(new VirtualDirent(name, type, normalized));\n          }\n          return dirents;\n        }\n        return names;\n      }\n      async readdir(path, options) {\n        return this.readdirSync(path, options);\n      }\n      mkdirSync(path, options) {\n        if (this.readonly) {\n          throw createEROFS("mkdir", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const recursive = options?.recursive === true;\n        const existing = this.#lookupEntry(normalized, true);\n        if (existing.entry) {\n          if (existing.entry.isDirectory() && recursive) {\n            return void 0;\n          }\n          throw createEEXIST("mkdir", path);\n        }\n        if (recursive) {\n          const segments = this.#splitPath(normalized);\n          let current = this[kRoot];\n          for (const segment of segments) {\n            let entry = current.children.get(segment);\n            if (!entry) {\n              entry = new MemoryEntry(TYPE_DIR, { mode: options?.mode });\n              entry.children = /* @__PURE__ */ new Map();\n              current.children.set(segment, entry);\n            } else if (!entry.isDirectory()) {\n              throw createENOTDIR("mkdir", path);\n            }\n            current = entry;\n          }\n        } else {\n          const parent = this.#ensureParent(normalized, false, "mkdir");\n          const name = this.#getBaseName(normalized);\n          const entry = new MemoryEntry(TYPE_DIR, { mode: options?.mode });\n          entry.children = /* @__PURE__ */ new Map();\n          parent.children.set(name, entry);\n        }\n        return recursive ? normalized : void 0;\n      }\n      async mkdir(path, options) {\n        return this.mkdirSync(path, options);\n      }\n      rmdirSync(path) {\n        if (this.readonly) {\n          throw createEROFS("rmdir", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const entry = this.#getEntry(normalized, "rmdir", true);\n        if (!entry.isDirectory()) {\n          throw createENOTDIR("rmdir", path);\n        }\n        if (entry.children.size > 0) {\n          throw createENOTEMPTY("rmdir", path);\n        }\n        const parent = this.#ensureParent(normalized, false, "rmdir");\n        const name = this.#getBaseName(normalized);\n        parent.children.delete(name);\n      }\n      async rmdir(path) {\n        this.rmdirSync(path);\n      }\n      unlinkSync(path) {\n        if (this.readonly) {\n          throw createEROFS("unlink", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const entry = this.#getEntry(normalized, "unlink", false);\n        if (entry.isDirectory()) {\n          throw createEISDIR("unlink", path);\n        }\n        const parent = this.#ensureParent(normalized, false, "unlink");\n        const name = this.#getBaseName(normalized);\n        parent.children.delete(name);\n      }\n      async unlink(path) {\n        this.unlinkSync(path);\n      }\n      renameSync(oldPath, newPath) {\n        if (this.readonly) {\n          throw createEROFS("rename", oldPath);\n        }\n        const normalizedOld = this.#normalizePath(oldPath);\n        const normalizedNew = this.#normalizePath(newPath);\n        const entry = this.#getEntry(normalizedOld, "rename", false);\n        const oldParent = this.#ensureParent(normalizedOld, false, "rename");\n        const oldName = this.#getBaseName(normalizedOld);\n        oldParent.children.delete(oldName);\n        const newParent = this.#ensureParent(normalizedNew, true, "rename");\n        const newName = this.#getBaseName(normalizedNew);\n        newParent.children.set(newName, entry);\n      }\n      async rename(oldPath, newPath) {\n        this.renameSync(oldPath, newPath);\n      }\n      readlinkSync(path, options) {\n        const normalized = this.#normalizePath(path);\n        const entry = this.#getEntry(normalized, "readlink", false);\n        if (!entry.isSymbolicLink()) {\n          throw createEINVAL("readlink", path);\n        }\n        return entry.target;\n      }\n      async readlink(path, options) {\n        return this.readlinkSync(path, options);\n      }\n      symlinkSync(target, path, type) {\n        if (this.readonly) {\n          throw createEROFS("symlink", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const existing = this.#lookupEntry(normalized, false);\n        if (existing.entry) {\n          throw createEEXIST("symlink", path);\n        }\n        const parent = this.#ensureParent(normalized, true, "symlink");\n        const name = this.#getBaseName(normalized);\n        const entry = new MemoryEntry(TYPE_SYMLINK);\n        entry.target = target;\n        parent.children.set(name, entry);\n      }\n      async symlink(target, path, type) {\n        this.symlinkSync(target, path, type);\n      }\n      realpathSync(path, options) {\n        const result = this.#lookupEntry(path, true, 0);\n        if (result.eloop) {\n          throw createELOOP("realpath", path);\n        }\n        if (!result.entry) {\n          throw createENOENT("realpath", path);\n        }\n        return result.resolvedPath;\n      }\n      async realpath(path, options) {\n        return this.realpathSync(path, options);\n      }\n      // === WATCH OPERATIONS ===\n      watch(path, options) {\n        const normalized = this.#normalizePath(path);\n        return new VFSWatcher(this, normalized, options);\n      }\n      watchAsync(path, options) {\n        const normalized = this.#normalizePath(path);\n        return new VFSWatchAsyncIterable(this, normalized, options);\n      }\n      watchFile(path, options, listener) {\n        const normalized = this.#normalizePath(path);\n        let watcher = this[kStatWatchers].get(normalized);\n        if (!watcher) {\n          watcher = new VFSStatWatcher(this, normalized, options);\n          this[kStatWatchers].set(normalized, watcher);\n        }\n        if (listener) {\n          watcher.addListener(listener);\n        }\n        return watcher;\n      }\n      unwatchFile(path, listener) {\n        const normalized = this.#normalizePath(path);\n        const watcher = this[kStatWatchers].get(normalized);\n        if (!watcher) {\n          return;\n        }\n        if (listener) {\n          watcher.removeListener(listener);\n        } else {\n          watcher.removeAllListeners("change");\n        }\n        if (watcher.hasNoListeners()) {\n          watcher.stop();\n          this[kStatWatchers].delete(normalized);\n        }\n      }\n    };\n    module2.exports = {\n      MemoryProvider\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/router.js\nvar require_router = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/router.js"(exports2, module2) {\n    "use strict";\n    var { isAbsolute, posix: pathPosix } = require("node:path");\n    function splitPath(normalizedPath) {\n      if (normalizedPath === "/") {\n        return [];\n      }\n      return normalizedPath.slice(1).split("/");\n    }\n    function getParentPath(normalizedPath) {\n      if (normalizedPath === "/") {\n        return null;\n      }\n      return pathPosix.dirname(normalizedPath);\n    }\n    function getBaseName(normalizedPath) {\n      return pathPosix.basename(normalizedPath);\n    }\n    function isUnderMountPoint(normalizedPath, mountPoint) {\n      if (normalizedPath === mountPoint) {\n        return true;\n      }\n      if (mountPoint === "/") {\n        return normalizedPath.startsWith("/");\n      }\n      return normalizedPath.startsWith(mountPoint + "/");\n    }\n    function getRelativePath(normalizedPath, mountPoint) {\n      if (normalizedPath === mountPoint) {\n        return "/";\n      }\n      if (mountPoint === "/") {\n        return normalizedPath;\n      }\n      return normalizedPath.slice(mountPoint.length);\n    }\n    module2.exports = {\n      splitPath,\n      getParentPath,\n      getBaseName,\n      isUnderMountPoint,\n      getRelativePath,\n      isAbsolutePath: isAbsolute\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/fd.js\nvar require_fd = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/fd.js"(exports2, module2) {\n    "use strict";\n    var kFd = /* @__PURE__ */ Symbol("kFd");\n    var kEntry = /* @__PURE__ */ Symbol("kEntry");\n    var nextFd = 1e4;\n    var openFDs = /* @__PURE__ */ new Map();\n    var VirtualFD = class {\n      constructor(fd, entry) {\n        this[kFd] = fd;\n        this[kEntry] = entry;\n      }\n      get fd() {\n        return this[kFd];\n      }\n      get entry() {\n        return this[kEntry];\n      }\n    };\n    function openVirtualFd(entry) {\n      const fd = nextFd++;\n      const vfd = new VirtualFD(fd, entry);\n      openFDs.set(fd, vfd);\n      return fd;\n    }\n    function getVirtualFd(fd) {\n      return openFDs.get(fd);\n    }\n    function closeVirtualFd(fd) {\n      return openFDs.delete(fd);\n    }\n    module2.exports = {\n      VirtualFD,\n      openVirtualFd,\n      getVirtualFd,\n      closeVirtualFd\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/streams.js\nvar require_streams = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/streams.js"(exports2, module2) {\n    "use strict";\n    var { Readable } = require("node:stream");\n    var { createEBADF } = require_errors();\n    var { getVirtualFd } = require_fd();\n    var VirtualReadStream = class extends Readable {\n      #vfs;\n      #path;\n      #fd = null;\n      #end;\n      #pos;\n      #content = null;\n      #destroyed = false;\n      #autoClose;\n      constructor(vfs2, filePath, options = {}) {\n        const {\n          start = 0,\n          end = Infinity,\n          highWaterMark = 64 * 1024,\n          encoding,\n          ...streamOptions\n        } = options;\n        super({ ...streamOptions, highWaterMark, encoding });\n        this.#vfs = vfs2;\n        this.#path = filePath;\n        this.#end = end;\n        this.#pos = start;\n        this.#autoClose = options.autoClose !== false;\n        process.nextTick(() => this.#openFile());\n      }\n      get path() {\n        return this.#path;\n      }\n      #openFile() {\n        try {\n          this.#fd = this.#vfs.openSync(this.#path);\n          this.emit("open", this.#fd);\n          this.emit("ready");\n        } catch (err) {\n          this.destroy(err);\n        }\n      }\n      _read(size) {\n        if (this.#destroyed || this.#fd === null) {\n          return;\n        }\n        if (this.#content === null) {\n          try {\n            const vfd = getVirtualFd(this.#fd);\n            if (!vfd) {\n              this.destroy(createEBADF("read"));\n              return;\n            }\n            this.#content = vfd.entry.readFileSync();\n          } catch (err) {\n            this.destroy(err);\n            return;\n          }\n        }\n        const endPos = this.#end === Infinity ? this.#content.length : this.#end + 1;\n        const remaining = Math.min(endPos, this.#content.length) - this.#pos;\n        if (remaining <= 0) {\n          this.push(null);\n          return;\n        }\n        const bytesToRead = Math.min(size, remaining);\n        const chunk = this.#content.subarray(this.#pos, this.#pos + bytesToRead);\n        this.#pos += bytesToRead;\n        this.push(chunk);\n        if (this.#pos >= endPos || this.#pos >= this.#content.length) {\n          this.push(null);\n        }\n      }\n      #close() {\n        if (this.#fd !== null) {\n          try {\n            this.#vfs.closeSync(this.#fd);\n          } catch {\n          }\n          this.#fd = null;\n        }\n      }\n      _destroy(err, callback) {\n        this.#destroyed = true;\n        if (this.#autoClose) {\n          this.#close();\n        }\n        callback(err);\n      }\n    };\n    module2.exports = {\n      VirtualReadStream\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/module_hooks.js\nvar require_module_hooks = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/module_hooks.js"(exports2, module2) {\n    "use strict";\n    var path = require("node:path");\n    var { dirname, extname, isAbsolute, resolve } = path;\n    var pathPosix = path.posix;\n    var { pathToFileURL, fileURLToPath } = require("node:url");\n    var { createENOENT } = require_errors();\n    var kEmptyObject = Object.freeze(/* @__PURE__ */ Object.create(null));\n    var NodeModule = require("node:module");\n    var builtinSet = new Set(NodeModule.builtinModules);\n    var ESM_EXTENSIONS = [".js", ".json", ".node", ".mjs", ".cjs"];\n    var CJS_EXTENSIONS = [".js", ".json", ".node"];\n    var ESM_INDEX_FILES = ["index.js", "index.mjs", "index.cjs", "index.json"];\n    var CJS_INDEX_FILES = ["index.js", "index.json", "index.node"];\n    var CJS_CONDITIONS = ["require", "node", "default"];\n    function isNodeBuiltin(name) {\n      if (typeof NodeModule.isBuiltin === "function") {\n        return NodeModule.isBuiltin(name);\n      }\n      const bare = name.startsWith("node:") ? name.slice(5) : name;\n      return builtinSet.has(bare);\n    }\n    function normalizeVFSPath(inputPath) {\n      if (process.platform === "win32" && /^V:[/\\\\]/.test(inputPath)) {\n        inputPath = "/" + inputPath.slice(3).replace(/\\\\/g, "/");\n      }\n      if (inputPath.startsWith("/")) {\n        return pathPosix.normalize(inputPath);\n      }\n      return path.normalize(inputPath);\n    }\n    function joinVFSParts(...parts) {\n      if (parts[0]?.startsWith("/")) {\n        return pathPosix.resolve(...parts);\n      }\n      return resolve(...parts);\n    }\n    function dirnameVFS(p) {\n      if (p.startsWith("/")) {\n        return pathPosix.dirname(p);\n      }\n      return dirname(p);\n    }\n    function vfsPathToURL(vfsPath) {\n      if (vfsPath.startsWith("/") && process.platform === "win32") {\n        return "file:///V:" + encodeURI(vfsPath);\n      }\n      return pathToFileURL(vfsPath).href;\n    }\n    function urlToVFSPath(url) {\n      const parsed = new URL(url);\n      const pathname = decodeURIComponent(parsed.pathname);\n      if (process.platform === "win32" && pathname.startsWith("/V:/")) {\n        return pathname.slice(3);\n      }\n      if (process.platform === "win32" && pathname.startsWith("/") && !/^\\/[A-Za-z]:/.test(pathname)) {\n        return pathname;\n      }\n      return fileURLToPath(url);\n    }\n    var activeVFSList = [];\n    var originalReadFileSync = null;\n    var originalRealpathSync = null;\n    var originalLstatSync = null;\n    var originalStatSync = null;\n    var originalReaddirSync = null;\n    var originalExistsSync = null;\n    var originalWatch = null;\n    var originalWatchFile = null;\n    var originalUnwatchFile = null;\n    var hooksInstalled = false;\n    function registerVFS(vfs2) {\n      if (activeVFSList.indexOf(vfs2) === -1) {\n        activeVFSList.push(vfs2);\n        if (!hooksInstalled) {\n          installHooks();\n        }\n      }\n    }\n    function deregisterVFS(vfs2) {\n      const index = activeVFSList.indexOf(vfs2);\n      if (index !== -1) {\n        activeVFSList.splice(index, 1);\n      }\n    }\n    function findVFSForStat(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          const result = vfs2.internalModuleStat(normalized);\n          if (vfs2.mounted || result >= 0) {\n            return { vfs: vfs2, result };\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForRead(filename, options) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.existsSync(normalized)) {\n            const statResult = vfs2.internalModuleStat(normalized);\n            if (statResult !== 0) {\n              return null;\n            }\n            try {\n              const content = vfs2.readFileSync(normalized, options);\n              return { vfs: vfs2, content };\n            } catch (e) {\n              if (vfs2.mounted) {\n                throw e;\n              }\n            }\n          } else if (vfs2.mounted) {\n            throw createENOENT("open", filename);\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForExists(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          const exists = vfs2.existsSync(normalized);\n          if (vfs2.mounted || exists) {\n            return { vfs: vfs2, exists };\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForRealpath(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.existsSync(normalized)) {\n            try {\n              const realpath = vfs2.realpathSync(normalized);\n              return { vfs: vfs2, realpath };\n            } catch (e) {\n              if (vfs2.mounted) {\n                throw e;\n              }\n            }\n          } else if (vfs2.mounted) {\n            throw createENOENT("realpath", filename);\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForFsStat(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.existsSync(normalized)) {\n            try {\n              const stats = vfs2.statSync(normalized);\n              return { vfs: vfs2, stats };\n            } catch (e) {\n              if (vfs2.mounted) {\n                throw e;\n              }\n            }\n          } else if (vfs2.mounted) {\n            throw createENOENT("stat", filename);\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForReaddir(dirname2, options) {\n      const normalized = normalizeVFSPath(dirname2);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.existsSync(normalized)) {\n            try {\n              const entries = vfs2.readdirSync(normalized, options);\n              return { vfs: vfs2, entries };\n            } catch (e) {\n              if (vfs2.mounted) {\n                throw e;\n              }\n            }\n          } else if (vfs2.mounted) {\n            throw createENOENT("scandir", dirname2);\n          }\n        }\n      }\n      return null;\n    }\n    function findVFSForWatch(filename) {\n      const normalized = normalizeVFSPath(filename);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized)) {\n          if (vfs2.overlay) {\n            if (vfs2.existsSync(normalized)) {\n              return { vfs: vfs2 };\n            }\n            continue;\n          }\n          return { vfs: vfs2 };\n        }\n      }\n      return null;\n    }\n    var VFS_FORMAT_MAP = {\n      "__proto__": null,\n      ".cjs": "commonjs",\n      ".js": null,\n      ".json": "json",\n      ".mjs": "module",\n      ".node": "addon",\n      ".wasm": "wasm"\n    };\n    function getVFSPackageType(vfs2, filePath) {\n      let currentDir = dirnameVFS(filePath);\n      let lastDir;\n      while (currentDir !== lastDir) {\n        if (currentDir.endsWith("/node_modules") || currentDir.endsWith("\\\\node_modules")) {\n          break;\n        }\n        const pjsonPath = normalizeVFSPath(joinVFSParts(currentDir, "package.json"));\n        if (vfs2.shouldHandle(pjsonPath) && vfs2.internalModuleStat(pjsonPath) === 0) {\n          try {\n            const content = vfs2.readFileSync(pjsonPath, "utf8");\n            const parsed = JSON.parse(content);\n            if (parsed.type === "module" || parsed.type === "commonjs") {\n              return parsed.type;\n            }\n            return "none";\n          } catch {\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return "none";\n    }\n    function getVFSFormat(vfs2, filePath) {\n      const ext = extname(filePath);\n      if (ext === ".js") {\n        return getVFSPackageType(vfs2, filePath) === "module" ? "module" : "commonjs";\n      }\n      return VFS_FORMAT_MAP[ext] ?? "commonjs";\n    }\n    function matchWildcardPattern(keys, subpath) {\n      for (let i = 0; i < keys.length; i++) {\n        const key = keys[i];\n        const starIdx = key.indexOf("*");\n        if (starIdx === -1) continue;\n        const prefix = key.slice(0, starIdx);\n        const suffix = key.slice(starIdx + 1);\n        if (subpath.startsWith(prefix) && (suffix === "" || subpath.endsWith(suffix)) && subpath.length >= prefix.length + suffix.length) {\n          return {\n            key,\n            patternMatch: subpath.slice(\n              prefix.length,\n              suffix.length > 0 ? -suffix.length : void 0\n            )\n          };\n        }\n      }\n      return null;\n    }\n    function expandPattern(value, patternMatch) {\n      return patternMatch !== null ? value.replace(/\\*/g, patternMatch) : value;\n    }\n    function findVFSForPath(normalizedPath) {\n      for (let i = 0; i < activeVFSList.length; i++) {\n        if (activeVFSList[i].shouldHandle(normalizedPath)) {\n          return activeVFSList[i];\n        }\n      }\n      return null;\n    }\n    function makeResolveResult(vfs2, filePath) {\n      return {\n        url: vfsPathToURL(filePath),\n        format: getVFSFormat(vfs2, filePath),\n        shortCircuit: true\n      };\n    }\n    function tryExtensions(vfs2, basePath, extensions) {\n      for (let i = 0; i < extensions.length; i++) {\n        const candidate = basePath + extensions[i];\n        if (vfs2.internalModuleStat(candidate) === 0) {\n          return candidate;\n        }\n      }\n      return null;\n    }\n    function tryIndexFiles(vfs2, dirPath, indexFiles) {\n      for (let i = 0; i < indexFiles.length; i++) {\n        const candidate = normalizeVFSPath(joinVFSParts(dirPath, indexFiles[i]));\n        if (vfs2.internalModuleStat(candidate) === 0) {\n          return candidate;\n        }\n      }\n      return null;\n    }\n    function resolveMainField(vfs2, dirPath, main, extensions, indexFiles) {\n      const mainPath = normalizeVFSPath(joinVFSParts(dirPath, main));\n      const mainStat = vfs2.internalModuleStat(mainPath);\n      if (mainStat === 0) return mainPath;\n      const withExt = tryExtensions(vfs2, mainPath, extensions);\n      if (withExt) return withExt;\n      if (mainStat === 1) return tryIndexFiles(vfs2, mainPath, indexFiles);\n      return null;\n    }\n    function resolveExportTarget(vfs2, pkgDir, target, patternMatch, extensions) {\n      if (typeof target !== "string") return null;\n      const expanded = expandPattern(target, patternMatch);\n      const resolved = normalizeVFSPath(joinVFSParts(pkgDir, expanded));\n      if (vfs2.internalModuleStat(resolved) === 0) return resolved;\n      return extensions ? tryExtensions(vfs2, resolved, extensions) : null;\n    }\n    function resolveConditionsToPath(vfs2, pkgDir, condMap, conditions, patternMatch, extensions) {\n      const keys = Object.getOwnPropertyNames(condMap);\n      for (let i = 0; i < keys.length; i++) {\n        const key = keys[i];\n        if (key === "default" || conditions.indexOf(key) !== -1) {\n          const value = condMap[key];\n          if (typeof value === "string") {\n            const result = resolveExportTarget(vfs2, pkgDir, value, patternMatch, extensions);\n            if (result) return result;\n            continue;\n          }\n          if (typeof value === "object" && value !== null && !Array.isArray(value)) {\n            const result = resolveConditionsToPath(vfs2, pkgDir, value, conditions, patternMatch, extensions);\n            if (result) return result;\n            continue;\n          }\n        }\n      }\n      return null;\n    }\n    function resolveExportsToPath(vfs2, pkgDir, packageSubpath, exports3, conditions, extensions) {\n      if (typeof exports3 === "string") {\n        if (packageSubpath === ".") {\n          return resolveExportTarget(vfs2, pkgDir, exports3, null, extensions);\n        }\n        return null;\n      }\n      if (typeof exports3 !== "object" || exports3 === null) return null;\n      const keys = Object.getOwnPropertyNames(exports3);\n      if (keys.length === 0) return null;\n      const isConditional = keys[0] !== "" && keys[0][0] !== ".";\n      if (isConditional) {\n        if (packageSubpath !== ".") return null;\n        return resolveConditionsToPath(vfs2, pkgDir, exports3, conditions, null, extensions);\n      }\n      let target = exports3[packageSubpath];\n      let patternMatch = null;\n      if (target === void 0) {\n        const match = matchWildcardPattern(keys, packageSubpath);\n        if (match) {\n          patternMatch = match.patternMatch;\n          target = exports3[match.key];\n        }\n      }\n      if (target === void 0) return null;\n      if (typeof target === "string") {\n        return resolveExportTarget(vfs2, pkgDir, target, patternMatch, extensions);\n      }\n      if (typeof target === "object" && target !== null && !Array.isArray(target)) {\n        return resolveConditionsToPath(vfs2, pkgDir, target, conditions, patternMatch, extensions);\n      }\n      return null;\n    }\n    function resolveDirectoryEntry(vfs2, dirPath, context) {\n      const pjsonPath = normalizeVFSPath(joinVFSParts(dirPath, "package.json"));\n      if (vfs2.internalModuleStat(pjsonPath) === 0) {\n        try {\n          const content = vfs2.readFileSync(pjsonPath, "utf8");\n          const parsed = JSON.parse(content);\n          if (parsed.exports != null) {\n            const resolved = resolveExportsToPath(\n              vfs2,\n              dirPath,\n              ".",\n              parsed.exports,\n              context.conditions || [],\n              null\n            );\n            if (resolved) return makeResolveResult(vfs2, resolved);\n          }\n          if (parsed.main) {\n            const mainResult = resolveMainField(\n              vfs2,\n              dirPath,\n              parsed.main,\n              ESM_EXTENSIONS,\n              ESM_INDEX_FILES\n            );\n            if (mainResult) return makeResolveResult(vfs2, mainResult);\n          }\n        } catch {\n        }\n      }\n      const indexResult = tryIndexFiles(vfs2, dirPath, ESM_INDEX_FILES);\n      return indexResult ? makeResolveResult(vfs2, indexResult) : null;\n    }\n    function parsePackageName(specifier) {\n      let separatorIndex = specifier.indexOf("/");\n      if (specifier[0] === "@") {\n        if (separatorIndex === -1) {\n          return { packageName: specifier, packageSubpath: "." };\n        }\n        separatorIndex = specifier.indexOf("/", separatorIndex + 1);\n      }\n      const packageName = separatorIndex === -1 ? specifier : specifier.slice(0, separatorIndex);\n      let packageSubpath = separatorIndex === -1 ? "." : "." + specifier.slice(separatorIndex);\n      if (packageSubpath === "./") packageSubpath = ".";\n      return { packageName, packageSubpath };\n    }\n    function urlToPath(urlOrPath) {\n      if (urlOrPath.startsWith("file:")) {\n        return fileURLToPath(urlOrPath);\n      }\n      return urlOrPath;\n    }\n    function resolveVFSPath(checkPath, context, nextResolve, specifier) {\n      const normalized = normalizeVFSPath(checkPath);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (!vfs2.shouldHandle(normalized)) continue;\n        const stat = vfs2.internalModuleStat(normalized);\n        if (stat === 0) {\n          return makeResolveResult(vfs2, normalized);\n        }\n        const withExt = tryExtensions(vfs2, normalized, ESM_EXTENSIONS);\n        if (withExt) return makeResolveResult(vfs2, withExt);\n        if (stat === 1) {\n          const resolved = resolveDirectoryEntry(vfs2, normalized, context);\n          if (resolved) return resolved;\n        }\n      }\n      return nextResolve(specifier, context);\n    }\n    function resolvePackageInVFS(vfs2, startDir, packageName, packageSubpath, context) {\n      let currentDir = startDir;\n      let lastDir;\n      const conditions = context.conditions || [];\n      while (currentDir !== lastDir) {\n        const pkgDir = normalizeVFSPath(\n          joinVFSParts(currentDir, "node_modules", packageName)\n        );\n        if (vfs2.shouldHandle(pkgDir) && vfs2.internalModuleStat(pkgDir) === 1) {\n          const pjsonPath = normalizeVFSPath(\n            joinVFSParts(pkgDir, "package.json")\n          );\n          if (vfs2.internalModuleStat(pjsonPath) === 0) {\n            try {\n              const parsed = JSON.parse(vfs2.readFileSync(pjsonPath, "utf8"));\n              if (parsed.exports != null) {\n                const resolved = resolveExportsToPath(\n                  vfs2,\n                  pkgDir,\n                  packageSubpath,\n                  parsed.exports,\n                  conditions,\n                  null\n                );\n                if (resolved) return makeResolveResult(vfs2, resolved);\n              }\n              if (packageSubpath === ".") {\n                if (parsed.main) {\n                  const mainResult = resolveMainField(\n                    vfs2,\n                    pkgDir,\n                    parsed.main,\n                    ESM_EXTENSIONS,\n                    ESM_INDEX_FILES\n                  );\n                  if (mainResult) return makeResolveResult(vfs2, mainResult);\n                }\n                const indexResult = tryIndexFiles(vfs2, pkgDir, ESM_INDEX_FILES);\n                if (indexResult) return makeResolveResult(vfs2, indexResult);\n              } else {\n                const subResolved = normalizeVFSPath(\n                  joinVFSParts(pkgDir, packageSubpath)\n                );\n                if (vfs2.internalModuleStat(subResolved) === 0) {\n                  return makeResolveResult(vfs2, subResolved);\n                }\n                const withExt = tryExtensions(vfs2, subResolved, ESM_EXTENSIONS);\n                if (withExt) return makeResolveResult(vfs2, withExt);\n              }\n            } catch {\n            }\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return null;\n    }\n    function resolveCJSPackageInVFS(vfs2, startDir, packageName, packageSubpath) {\n      let currentDir = startDir;\n      let lastDir;\n      while (currentDir !== lastDir) {\n        const pkgDir = normalizeVFSPath(\n          joinVFSParts(currentDir, "node_modules", packageName)\n        );\n        if (vfs2.shouldHandle(pkgDir) && vfs2.internalModuleStat(pkgDir) === 1) {\n          const pjsonPath = normalizeVFSPath(\n            joinVFSParts(pkgDir, "package.json")\n          );\n          let parsed = null;\n          if (vfs2.internalModuleStat(pjsonPath) === 0) {\n            try {\n              parsed = JSON.parse(vfs2.readFileSync(pjsonPath, "utf8"));\n            } catch {\n            }\n          }\n          if (parsed?.exports != null) {\n            const exportsResult = resolveExportsToPath(\n              vfs2,\n              pkgDir,\n              packageSubpath,\n              parsed.exports,\n              CJS_CONDITIONS,\n              CJS_EXTENSIONS\n            );\n            if (exportsResult) return exportsResult;\n          }\n          if (packageSubpath === ".") {\n            if (parsed?.main) {\n              const mainResult = resolveMainField(\n                vfs2,\n                pkgDir,\n                parsed.main,\n                CJS_EXTENSIONS,\n                CJS_INDEX_FILES\n              );\n              if (mainResult) return mainResult;\n            }\n            const idxResult = tryIndexFiles(vfs2, pkgDir, CJS_INDEX_FILES);\n            if (idxResult) return idxResult;\n          } else {\n            const subResolved = normalizeVFSPath(\n              joinVFSParts(pkgDir, packageSubpath)\n            );\n            const subStat = vfs2.internalModuleStat(subResolved);\n            if (subStat === 0) {\n              return subResolved;\n            }\n            const withExt = tryExtensions(vfs2, subResolved, CJS_EXTENSIONS);\n            if (withExt) return withExt;\n            if (subStat === 1) {\n              const subPjsonPath = normalizeVFSPath(\n                joinVFSParts(subResolved, "package.json")\n              );\n              if (vfs2.internalModuleStat(subPjsonPath) === 0) {\n                try {\n                  const subParsed = JSON.parse(vfs2.readFileSync(subPjsonPath, "utf8"));\n                  if (subParsed.main) {\n                    const mainResult = resolveMainField(\n                      vfs2,\n                      subResolved,\n                      subParsed.main,\n                      CJS_EXTENSIONS,\n                      CJS_INDEX_FILES\n                    );\n                    if (mainResult) return mainResult;\n                  }\n                } catch {\n                }\n              }\n              const subIdx = tryIndexFiles(vfs2, subResolved, CJS_INDEX_FILES);\n              if (subIdx) return subIdx;\n            }\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return null;\n    }\n    function resolveImportTarget(vfs2, baseDir, value, patternMatch, context, nextResolve) {\n      const expanded = expandPattern(value, patternMatch);\n      if (!expanded.startsWith(".") && !expanded.startsWith("/")) {\n        return resolveBareSpecifier(expanded, context, nextResolve);\n      }\n      const resolved = normalizeVFSPath(joinVFSParts(baseDir, expanded));\n      if (vfs2.internalModuleStat(resolved) === 0) {\n        return makeResolveResult(vfs2, resolved);\n      }\n      return null;\n    }\n    function resolveImportConditions(vfs2, baseDir, condMap, conditions, patternMatch, context, nextResolve) {\n      const keys = Object.getOwnPropertyNames(condMap);\n      for (let i = 0; i < keys.length; i++) {\n        const key = keys[i];\n        if (key === "default" || conditions.indexOf(key) !== -1) {\n          const value = condMap[key];\n          if (typeof value === "string") {\n            const result = resolveImportTarget(vfs2, baseDir, value, patternMatch, context, nextResolve);\n            if (result) return result;\n            continue;\n          }\n          if (typeof value === "object" && value !== null && !Array.isArray(value)) {\n            const result = resolveImportConditions(vfs2, baseDir, value, conditions, patternMatch, context, nextResolve);\n            if (result) return result;\n            continue;\n          }\n        }\n      }\n      return null;\n    }\n    function resolveHashImport(specifier, context, nextResolve) {\n      if (!context.parentURL) {\n        return nextResolve(specifier, context);\n      }\n      let parentPath;\n      try {\n        parentPath = urlToPath(context.parentURL);\n      } catch {\n        return nextResolve(specifier, context);\n      }\n      const parentNorm = normalizeVFSPath(parentPath);\n      const parentVfs = findVFSForPath(parentNorm);\n      if (!parentVfs) {\n        return nextResolve(specifier, context);\n      }\n      const conditions = context.conditions || [];\n      let currentDir = dirnameVFS(parentNorm);\n      let lastDir;\n      while (currentDir !== lastDir) {\n        const pjsonPath = normalizeVFSPath(\n          joinVFSParts(currentDir, "package.json")\n        );\n        if (parentVfs.shouldHandle(pjsonPath) && parentVfs.internalModuleStat(pjsonPath) === 0) {\n          try {\n            const parsed = JSON.parse(parentVfs.readFileSync(pjsonPath, "utf8"));\n            if (parsed.imports) {\n              let target = parsed.imports[specifier];\n              let patternMatch = null;\n              if (target === void 0) {\n                const impKeys = Object.getOwnPropertyNames(parsed.imports);\n                const match = matchWildcardPattern(impKeys, specifier);\n                if (match) {\n                  patternMatch = match.patternMatch;\n                  target = parsed.imports[match.key];\n                }\n              }\n              if (target !== void 0) {\n                if (typeof target === "string") {\n                  const result = resolveImportTarget(\n                    parentVfs,\n                    currentDir,\n                    target,\n                    patternMatch,\n                    context,\n                    nextResolve\n                  );\n                  if (result) return result;\n                }\n                if (typeof target === "object" && target !== null && !Array.isArray(target)) {\n                  const result = resolveImportConditions(\n                    parentVfs,\n                    currentDir,\n                    target,\n                    conditions,\n                    patternMatch,\n                    context,\n                    nextResolve\n                  );\n                  if (result) return result;\n                }\n              }\n              break;\n            }\n          } catch {\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return nextResolve(specifier, context);\n    }\n    function resolveCJSImportTarget(vfs2, startDir, baseDir, value, patternMatch) {\n      const expanded = expandPattern(value, patternMatch);\n      if (!expanded.startsWith(".") && !expanded.startsWith("/")) {\n        const { packageName, packageSubpath } = parsePackageName(expanded);\n        return resolveCJSPackageInVFS(vfs2, startDir, packageName, packageSubpath);\n      }\n      const resolved = normalizeVFSPath(joinVFSParts(baseDir, expanded));\n      if (vfs2.internalModuleStat(resolved) === 0) return resolved;\n      return tryExtensions(vfs2, resolved, CJS_EXTENSIONS);\n    }\n    function resolveCJSImportConditions(vfs2, startDir, baseDir, condMap, patternMatch) {\n      const keys = Object.getOwnPropertyNames(condMap);\n      for (let i = 0; i < keys.length; i++) {\n        const key = keys[i];\n        if (key === "default" || CJS_CONDITIONS.indexOf(key) !== -1) {\n          const value = condMap[key];\n          if (typeof value === "string") {\n            const result = resolveCJSImportTarget(vfs2, startDir, baseDir, value, patternMatch);\n            if (result) return result;\n            continue;\n          }\n          if (typeof value === "object" && value !== null && !Array.isArray(value)) {\n            const result = resolveCJSImportConditions(vfs2, startDir, baseDir, value, patternMatch);\n            if (result) return result;\n            continue;\n          }\n        }\n      }\n      return null;\n    }\n    function resolveCJSHashImport(specifier, parentDir) {\n      const parentNorm = normalizeVFSPath(parentDir);\n      const parentVfs = findVFSForPath(parentNorm);\n      if (!parentVfs) return null;\n      let currentDir = parentNorm;\n      let lastDir;\n      while (currentDir !== lastDir) {\n        const pjsonPath = normalizeVFSPath(\n          joinVFSParts(currentDir, "package.json")\n        );\n        if (parentVfs.shouldHandle(pjsonPath) && parentVfs.internalModuleStat(pjsonPath) === 0) {\n          try {\n            const parsed = JSON.parse(parentVfs.readFileSync(pjsonPath, "utf8"));\n            if (parsed.imports) {\n              let target = parsed.imports[specifier];\n              let patternMatch = null;\n              if (target === void 0) {\n                const impKeys = Object.getOwnPropertyNames(parsed.imports);\n                const match = matchWildcardPattern(impKeys, specifier);\n                if (match) {\n                  patternMatch = match.patternMatch;\n                  target = parsed.imports[match.key];\n                }\n              }\n              if (target !== void 0) {\n                if (typeof target === "string") {\n                  return resolveCJSImportTarget(\n                    parentVfs,\n                    parentNorm,\n                    currentDir,\n                    target,\n                    patternMatch\n                  );\n                }\n                if (typeof target === "object" && target !== null && !Array.isArray(target)) {\n                  return resolveCJSImportConditions(\n                    parentVfs,\n                    parentNorm,\n                    currentDir,\n                    target,\n                    patternMatch\n                  );\n                }\n              }\n              break;\n            }\n          } catch {\n          }\n        }\n        lastDir = currentDir;\n        currentDir = dirnameVFS(currentDir);\n      }\n      return null;\n    }\n    function resolveBareSpecifier(specifier, context, nextResolve) {\n      if (isNodeBuiltin(specifier)) {\n        return nextResolve(specifier, context);\n      }\n      if (specifier[0] === "#") {\n        return resolveHashImport(specifier, context, nextResolve);\n      }\n      if (!context.parentURL) {\n        return nextResolve(specifier, context);\n      }\n      let parentPath;\n      try {\n        parentPath = urlToPath(context.parentURL);\n      } catch {\n        return nextResolve(specifier, context);\n      }\n      const parentNorm = normalizeVFSPath(parentPath);\n      const parentVfs = findVFSForPath(parentNorm);\n      const { packageName, packageSubpath } = parsePackageName(specifier);\n      if (parentVfs) {\n        const result = resolvePackageInVFS(\n          parentVfs,\n          dirnameVFS(parentNorm),\n          packageName,\n          packageSubpath,\n          context\n        );\n        if (result) return result;\n      } else {\n        for (let i = 0; i < activeVFSList.length; i++) {\n          const vfs2 = activeVFSList[i];\n          const mp = vfs2.mountPoint;\n          if (!mp) continue;\n          const result = resolvePackageInVFS(\n            vfs2,\n            mp,\n            packageName,\n            packageSubpath,\n            context\n          );\n          if (result) return result;\n        }\n      }\n      return nextResolve(specifier, context);\n    }\n    function vfsResolveHook(specifier, context, nextResolve) {\n      if (isNodeBuiltin(specifier)) {\n        return nextResolve(specifier, context);\n      }\n      let checkPath;\n      if (specifier.startsWith("file:")) {\n        checkPath = urlToVFSPath(specifier);\n      } else if (isAbsolute(specifier)) {\n        checkPath = specifier;\n      } else if (specifier[0] === ".") {\n        if (context.parentURL) {\n          const parentPath = urlToPath(context.parentURL);\n          const parentDir = dirname(parentPath);\n          checkPath = resolve(parentDir, specifier);\n        } else {\n          return nextResolve(specifier, context);\n        }\n      } else {\n        return resolveBareSpecifier(specifier, context, nextResolve);\n      }\n      return resolveVFSPath(checkPath, context, nextResolve, specifier);\n    }\n    function vfsLoadHook(url, context, nextLoad) {\n      if (url.startsWith("node:")) {\n        return nextLoad(url, context);\n      }\n      if (!url.startsWith("file:")) {\n        return nextLoad(url, context);\n      }\n      const filePath = urlToVFSPath(url);\n      const normalized = normalizeVFSPath(filePath);\n      for (let i = 0; i < activeVFSList.length; i++) {\n        const vfs2 = activeVFSList[i];\n        if (vfs2.shouldHandle(normalized) && vfs2.existsSync(normalized)) {\n          const statResult = vfs2.internalModuleStat(normalized);\n          if (statResult !== 0) {\n            return nextLoad(url, context);\n          }\n          try {\n            const content = vfs2.readFileSync(normalized, "utf8");\n            const format = context.format || getVFSFormat(vfs2, normalized);\n            return {\n              format,\n              source: content,\n              shortCircuit: true\n            };\n          } catch (e) {\n            if (vfs2.mounted) {\n              throw e;\n            }\n          }\n        }\n      }\n      return nextLoad(url, context);\n    }\n    function installModuleHooks() {\n      if (typeof NodeModule.registerHooks === "function") {\n        NodeModule.registerHooks({\n          resolve: vfsResolveHook,\n          load: vfsLoadHook\n        });\n      }\n      const origResolveFilename = NodeModule._resolveFilename;\n      NodeModule._resolveFilename = function(request, parent, isMain, options) {\n        if (request.startsWith("node:")) {\n          return origResolveFilename.call(this, request, parent, isMain, options);\n        }\n        let checkPath;\n        if (isAbsolute(request)) {\n          checkPath = request;\n        } else if (request[0] === ".") {\n          if (parent?.filename) {\n            checkPath = resolve(dirname(parent.filename), request);\n          }\n        }\n        if (checkPath) {\n          const normalized = normalizeVFSPath(checkPath);\n          for (let i = 0; i < activeVFSList.length; i++) {\n            const vfs2 = activeVFSList[i];\n            if (!vfs2.shouldHandle(normalized)) continue;\n            const stat = vfs2.internalModuleStat(normalized);\n            if (stat === 0) return normalized;\n            const withExt = tryExtensions(vfs2, normalized, CJS_EXTENSIONS);\n            if (withExt) return withExt;\n            if (stat === 1) {\n              const pjsonPath = normalizeVFSPath(resolve(normalized, "package.json"));\n              if (vfs2.internalModuleStat(pjsonPath) === 0) {\n                try {\n                  const parsed = JSON.parse(vfs2.readFileSync(pjsonPath, "utf8"));\n                  if (parsed.main) {\n                    const mainResult = resolveMainField(\n                      vfs2,\n                      normalized,\n                      parsed.main,\n                      CJS_EXTENSIONS,\n                      CJS_INDEX_FILES\n                    );\n                    if (mainResult) return mainResult;\n                  }\n                } catch {\n                }\n              }\n              const idxResult = tryIndexFiles(vfs2, normalized, CJS_INDEX_FILES);\n              if (idxResult) return idxResult;\n            }\n          }\n        }\n        if (request[0] === "#") {\n          const parentDir = parent?.filename ? dirname(parent.filename) : process.cwd();\n          const found = resolveCJSHashImport(request, parentDir);\n          if (found) return found;\n        }\n        if (!isAbsolute(request) && request[0] !== "." && request[0] !== "#" && !isNodeBuiltin(request)) {\n          const parentDir = parent?.filename ? dirname(parent.filename) : process.cwd();\n          const parentNorm = normalizeVFSPath(parentDir);\n          const { packageName, packageSubpath } = parsePackageName(request);\n          let matched = false;\n          for (let i = 0; i < activeVFSList.length; i++) {\n            const vfs2 = activeVFSList[i];\n            if (!vfs2.shouldHandle(parentNorm)) continue;\n            matched = true;\n            const found = resolveCJSPackageInVFS(\n              vfs2,\n              parentNorm,\n              packageName,\n              packageSubpath\n            );\n            if (found) return found;\n          }\n          if (!matched) {\n            for (let i = 0; i < activeVFSList.length; i++) {\n              const vfs2 = activeVFSList[i];\n              const mp = vfs2.mountPoint;\n              if (!mp) continue;\n              const found = resolveCJSPackageInVFS(\n                vfs2,\n                mp,\n                packageName,\n                packageSubpath\n              );\n              if (found) return found;\n            }\n          }\n        }\n        return origResolveFilename.call(this, request, parent, isMain, options);\n      };\n      const origJsHandler = NodeModule._extensions[".js"];\n      NodeModule._extensions[".js"] = function(module3, filename) {\n        const normalized = normalizeVFSPath(filename);\n        for (let i = 0; i < activeVFSList.length; i++) {\n          const vfs2 = activeVFSList[i];\n          if (vfs2.shouldHandle(normalized) && vfs2.existsSync(normalized)) {\n            const content = vfs2.readFileSync(normalized, "utf8");\n            module3._compile(content, filename);\n            return;\n          }\n        }\n        return origJsHandler.call(this, module3, filename);\n      };\n      const origJsonHandler = NodeModule._extensions[".json"];\n      NodeModule._extensions[".json"] = function(module3, filename) {\n        const normalized = normalizeVFSPath(filename);\n        for (let i = 0; i < activeVFSList.length; i++) {\n          const vfs2 = activeVFSList[i];\n          if (vfs2.shouldHandle(normalized) && vfs2.existsSync(normalized)) {\n            const content = vfs2.readFileSync(normalized, "utf8");\n            module3.exports = JSON.parse(content);\n            return;\n          }\n        }\n        return origJsonHandler.call(this, module3, filename);\n      };\n    }\n    function installFsPatches() {\n      const fs = require("node:fs");\n      originalReadFileSync = fs.readFileSync;\n      originalRealpathSync = fs.realpathSync;\n      originalLstatSync = fs.lstatSync;\n      originalStatSync = fs.statSync;\n      fs.readFileSync = function readFileSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRead(path2, options);\n          if (vfsResult !== null) {\n            return vfsResult.content;\n          }\n        }\n        return originalReadFileSync.call(fs, path2, options);\n      };\n      fs.realpathSync = function realpathSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRealpath(path2);\n          if (vfsResult !== null) {\n            return vfsResult.realpath;\n          }\n        }\n        return originalRealpathSync.call(fs, path2, options);\n      };\n      if (originalRealpathSync.native) {\n        fs.realpathSync.native = originalRealpathSync.native;\n      }\n      fs.lstatSync = function lstatSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForFsStat(path2);\n          if (vfsResult !== null) {\n            return vfsResult.stats;\n          }\n        }\n        return originalLstatSync.call(fs, path2, options);\n      };\n      fs.statSync = function statSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForFsStat(path2);\n          if (vfsResult !== null) {\n            return vfsResult.stats;\n          }\n        }\n        return originalStatSync.call(fs, path2, options);\n      };\n      originalReaddirSync = fs.readdirSync;\n      fs.readdirSync = function readdirSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForReaddir(path2, options);\n          if (vfsResult !== null) {\n            return vfsResult.entries;\n          }\n        }\n        return originalReaddirSync.call(fs, path2, options);\n      };\n      originalExistsSync = fs.existsSync;\n      fs.existsSync = function existsSync(path2) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForExists(path2);\n          if (vfsResult !== null) {\n            return vfsResult.exists;\n          }\n        }\n        return originalExistsSync.call(fs, path2);\n      };\n      const originalReadlinkSync = fs.readlinkSync;\n      fs.readlinkSync = function readlinkSync(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRealpath(path2);\n          if (vfsResult !== null) {\n            return vfsResult.realpath;\n          }\n        }\n        return originalReadlinkSync.call(fs, path2, options);\n      };\n      const originalAccessSync = fs.accessSync;\n      fs.accessSync = function accessSync(path2, mode) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForExists(path2);\n          if (vfsResult !== null) {\n            if (!vfsResult.exists) {\n              throw createENOENT("access", path2);\n            }\n            return;\n          }\n        }\n        return originalAccessSync.call(fs, path2, mode);\n      };\n      const originalAccess = fs.access;\n      fs.access = function access(path2, mode, callback) {\n        if (typeof mode === "function") {\n          callback = mode;\n          mode = fs.constants.F_OK;\n        }\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForExists(path2);\n          if (vfsResult !== null) {\n            const err = vfsResult.exists ? null : createENOENT("access", path2);\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalAccess.call(fs, path2, mode, callback);\n      };\n      const originalStat = fs.stat;\n      fs.stat = function stat(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForFsStat(path2);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.stats);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalStat.call(fs, path2, options, callback);\n      };\n      const originalLstat = fs.lstat;\n      fs.lstat = function lstat(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForFsStat(path2);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.stats);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalLstat.call(fs, path2, options, callback);\n      };\n      const originalReadFile = fs.readFile;\n      fs.readFile = function readFile(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForRead(path2, options);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.content);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalReadFile.call(fs, path2, options, callback);\n      };\n      const originalCreateReadStream = fs.createReadStream;\n      fs.createReadStream = function createReadStream(path2, options) {\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForRead(path2, options);\n            if (vfsResult !== null) {\n              const { Readable } = require("node:stream");\n              const stream = new Readable({ read() {\n              } });\n              stream.push(vfsResult.content);\n              stream.push(null);\n              return stream;\n            }\n          } catch (err) {\n            const { Readable } = require("node:stream");\n            const stream = new Readable({ read() {\n            } });\n            process.nextTick(() => stream.destroy(err));\n            return stream;\n          }\n        }\n        return originalCreateReadStream.call(fs, path2, options);\n      };\n      const originalReaddir = fs.readdir;\n      fs.readdir = function readdir(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForReaddir(path2, options);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.entries);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalReaddir.call(fs, path2, options, callback);\n      };\n      const originalReadlink = fs.readlink;\n      fs.readlink = function readlink(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForRealpath(path2);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.realpath);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalReadlink.call(fs, path2, options, callback);\n      };\n      const originalRealpath = fs.realpath;\n      fs.realpath = function realpath(path2, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        if (typeof path2 === "string") {\n          try {\n            const vfsResult = findVFSForRealpath(path2);\n            if (vfsResult !== null) {\n              if (callback) process.nextTick(callback, null, vfsResult.realpath);\n              return;\n            }\n          } catch (err) {\n            if (callback) process.nextTick(callback, err);\n            return;\n          }\n        }\n        return originalRealpath.call(fs, path2, options, callback);\n      };\n      if (originalRealpath.native) {\n        fs.realpath.native = originalRealpath.native;\n      }\n      const origPAccess = fs.promises.access;\n      fs.promises.access = async function access(path2, mode) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForExists(path2);\n          if (vfsResult !== null) {\n            if (!vfsResult.exists) {\n              throw createENOENT("access", path2);\n            }\n            return;\n          }\n        }\n        return origPAccess.call(fs.promises, path2, mode);\n      };\n      const origPReadFile = fs.promises.readFile;\n      fs.promises.readFile = async function readFile(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRead(path2, options);\n          if (vfsResult !== null) {\n            return vfsResult.content;\n          }\n        }\n        return origPReadFile.call(fs.promises, path2, options);\n      };\n      const origPStat = fs.promises.stat;\n      fs.promises.stat = async function stat(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForFsStat(path2);\n          if (vfsResult !== null) {\n            return vfsResult.stats;\n          }\n        }\n        return origPStat.call(fs.promises, path2, options);\n      };\n      const origPLstat = fs.promises.lstat;\n      fs.promises.lstat = async function lstat(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForFsStat(path2);\n          if (vfsResult !== null) {\n            return vfsResult.stats;\n          }\n        }\n        return origPLstat.call(fs.promises, path2, options);\n      };\n      const origPReaddir = fs.promises.readdir;\n      fs.promises.readdir = async function readdir(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForReaddir(path2, options);\n          if (vfsResult !== null) {\n            return vfsResult.entries;\n          }\n        }\n        return origPReaddir.call(fs.promises, path2, options);\n      };\n      const origPReadlink = fs.promises.readlink;\n      fs.promises.readlink = async function readlink(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRealpath(path2);\n          if (vfsResult !== null) {\n            return vfsResult.realpath;\n          }\n        }\n        return origPReadlink.call(fs.promises, path2, options);\n      };\n      const origPRealpath = fs.promises.realpath;\n      fs.promises.realpath = async function realpath(path2, options) {\n        if (typeof path2 === "string") {\n          const vfsResult = findVFSForRealpath(path2);\n          if (vfsResult !== null) {\n            return vfsResult.realpath;\n          }\n        }\n        return origPRealpath.call(fs.promises, path2, options);\n      };\n      originalWatch = fs.watch;\n      fs.watch = function watch(filename, options, listener) {\n        if (typeof options === "function") {\n          listener = options;\n          options = kEmptyObject;\n        } else options ??= kEmptyObject;\n        if (typeof filename === "string") {\n          const vfsResult = findVFSForWatch(filename);\n          if (vfsResult !== null) {\n            return vfsResult.vfs.watch(filename, options, listener);\n          }\n        }\n        return originalWatch.call(fs, filename, options, listener);\n      };\n      originalWatchFile = fs.watchFile;\n      fs.watchFile = function watchFile(filename, options, listener) {\n        if (typeof options === "function") {\n          listener = options;\n          options = kEmptyObject;\n        } else options ??= kEmptyObject;\n        if (typeof filename === "string") {\n          const vfsResult = findVFSForWatch(filename);\n          if (vfsResult !== null) {\n            return vfsResult.vfs.watchFile(filename, options, listener);\n          }\n        }\n        return originalWatchFile.call(fs, filename, options, listener);\n      };\n      originalUnwatchFile = fs.unwatchFile;\n      fs.unwatchFile = function unwatchFile(filename, listener) {\n        if (typeof filename === "string") {\n          const vfsResult = findVFSForWatch(filename);\n          if (vfsResult !== null) {\n            vfsResult.vfs.unwatchFile(filename, listener);\n            return;\n          }\n        }\n        return originalUnwatchFile.call(fs, filename, listener);\n      };\n    }\n    function installHooks() {\n      if (hooksInstalled) {\n        return;\n      }\n      installModuleHooks();\n      installFsPatches();\n      hooksInstalled = true;\n    }\n    module2.exports = {\n      registerVFS,\n      deregisterVFS,\n      findVFSForStat,\n      findVFSForRead\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/file_system.js\nvar require_file_system = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/file_system.js"(exports2, module2) {\n    "use strict";\n    var path = require("node:path");\n    var pathPosix = path.posix;\n    var { isAbsolute, resolve: resolvePath } = path;\n    var { MemoryProvider } = require_memory();\n    var {\n      isUnderMountPoint,\n      getRelativePath\n    } = require_router();\n    var {\n      openVirtualFd,\n      getVirtualFd,\n      closeVirtualFd\n    } = require_fd();\n    var {\n      createENOENT,\n      createENOTDIR,\n      createEBADF,\n      ERR_INVALID_STATE\n    } = require_errors();\n    var { VirtualReadStream } = require_streams();\n    var kEmptyObject = Object.freeze(/* @__PURE__ */ Object.create(null));\n    function normalizeVFSPath(inputPath) {\n      if (inputPath.startsWith("/")) {\n        return pathPosix.normalize(inputPath);\n      }\n      return path.normalize(inputPath);\n    }\n    function joinVFSPath(base, part) {\n      if (base.startsWith("/")) {\n        return pathPosix.join(base, part);\n      }\n      return path.join(base, part);\n    }\n    var kProvider = /* @__PURE__ */ Symbol("kProvider");\n    var kMountPoint = /* @__PURE__ */ Symbol("kMountPoint");\n    var kMounted = /* @__PURE__ */ Symbol("kMounted");\n    var kOverlay = /* @__PURE__ */ Symbol("kOverlay");\n    var kModuleHooks = /* @__PURE__ */ Symbol("kModuleHooks");\n    var kPromises = /* @__PURE__ */ Symbol("kPromises");\n    var kVirtualCwd = /* @__PURE__ */ Symbol("kVirtualCwd");\n    var kVirtualCwdEnabled = /* @__PURE__ */ Symbol("kVirtualCwdEnabled");\n    var kOriginalChdir = /* @__PURE__ */ Symbol("kOriginalChdir");\n    var kOriginalCwd = /* @__PURE__ */ Symbol("kOriginalCwd");\n    var registerVFS;\n    var deregisterVFS;\n    function loadModuleHooks() {\n      if (!registerVFS) {\n        const hooks = require_module_hooks();\n        registerVFS = hooks.registerVFS;\n        deregisterVFS = hooks.deregisterVFS;\n      }\n    }\n    var VirtualFileSystem = class {\n      constructor(providerOrOptions, options = kEmptyObject) {\n        let provider = null;\n        if (providerOrOptions !== void 0 && providerOrOptions !== null) {\n          if (typeof providerOrOptions.openSync === "function") {\n            provider = providerOrOptions;\n          } else if (typeof providerOrOptions === "object") {\n            options = providerOrOptions;\n            provider = null;\n          }\n        }\n        if (options.moduleHooks !== void 0 && typeof options.moduleHooks !== "boolean") {\n          throw new TypeError("options.moduleHooks must be a boolean");\n        }\n        if (options.virtualCwd !== void 0 && typeof options.virtualCwd !== "boolean") {\n          throw new TypeError("options.virtualCwd must be a boolean");\n        }\n        if (options.overlay !== void 0 && typeof options.overlay !== "boolean") {\n          throw new TypeError("options.overlay must be a boolean");\n        }\n        this[kProvider] = provider ?? new MemoryProvider();\n        this[kMountPoint] = null;\n        this[kMounted] = false;\n        this[kOverlay] = options.overlay === true;\n        this[kModuleHooks] = options.moduleHooks !== false;\n        this[kPromises] = null;\n        this[kVirtualCwdEnabled] = options.virtualCwd === true;\n        this[kVirtualCwd] = null;\n        this[kOriginalChdir] = null;\n        this[kOriginalCwd] = null;\n      }\n      get provider() {\n        return this[kProvider];\n      }\n      get mountPoint() {\n        return this[kMountPoint];\n      }\n      get mounted() {\n        return this[kMounted];\n      }\n      get readonly() {\n        return this[kProvider].readonly;\n      }\n      get overlay() {\n        return this[kOverlay];\n      }\n      get virtualCwdEnabled() {\n        return this[kVirtualCwdEnabled];\n      }\n      // ==================== Virtual Working Directory ====================\n      cwd() {\n        if (!this[kVirtualCwdEnabled]) {\n          throw new ERR_INVALID_STATE("virtual cwd is not enabled");\n        }\n        return this[kVirtualCwd];\n      }\n      chdir(dirPath) {\n        if (!this[kVirtualCwdEnabled]) {\n          throw new ERR_INVALID_STATE("virtual cwd is not enabled");\n        }\n        const providerPath = this.#toProviderPath(dirPath);\n        const stats = this[kProvider].statSync(providerPath);\n        if (!stats.isDirectory()) {\n          throw createENOTDIR("chdir", dirPath);\n        }\n        this[kVirtualCwd] = this.#toMountedPath(providerPath);\n      }\n      resolvePath(inputPath) {\n        if (isAbsolute(inputPath)) {\n          return normalizeVFSPath(inputPath);\n        }\n        if (this[kVirtualCwdEnabled] && this[kVirtualCwd] !== null) {\n          const resolved = `${this[kVirtualCwd]}/${inputPath}`;\n          return normalizeVFSPath(resolved);\n        }\n        return resolvePath(inputPath);\n      }\n      // ==================== Mount ====================\n      mount(prefix) {\n        if (this[kMounted]) {\n          throw new ERR_INVALID_STATE("VFS is already mounted");\n        }\n        this[kMountPoint] = normalizeVFSPath(prefix);\n        this[kMounted] = true;\n        if (this[kModuleHooks]) {\n          loadModuleHooks();\n          registerVFS(this);\n        }\n        if (this[kVirtualCwdEnabled]) {\n          this.#hookProcessCwd();\n        }\n        process.emit("vfs-mount", {\n          mountPoint: this[kMountPoint],\n          overlay: this[kOverlay],\n          readonly: this[kProvider].readonly\n        });\n        return this;\n      }\n      unmount() {\n        if (this[kMounted]) {\n          process.emit("vfs-unmount", {\n            mountPoint: this[kMountPoint],\n            overlay: this[kOverlay],\n            readonly: this[kProvider].readonly\n          });\n        }\n        this.#unhookProcessCwd();\n        if (this[kModuleHooks]) {\n          loadModuleHooks();\n          deregisterVFS(this);\n        }\n        this[kMountPoint] = null;\n        this[kMounted] = false;\n        this[kVirtualCwd] = null;\n      }\n      [Symbol.dispose]() {\n        if (this[kMounted]) {\n          this.unmount();\n        }\n      }\n      #hookProcessCwd() {\n        if (this[kOriginalChdir] !== null) {\n          return;\n        }\n        const vfs2 = this;\n        this[kOriginalChdir] = process.chdir;\n        this[kOriginalCwd] = process.cwd;\n        process.chdir = function chdir(directory) {\n          const normalized = isAbsolute(directory) ? normalizeVFSPath(directory) : resolvePath(directory);\n          if (vfs2.shouldHandle(normalized)) {\n            vfs2.chdir(normalized);\n            return;\n          }\n          return vfs2[kOriginalChdir].call(process, directory);\n        };\n        process.cwd = function cwd() {\n          if (vfs2[kVirtualCwd] !== null) {\n            return vfs2[kVirtualCwd];\n          }\n          return vfs2[kOriginalCwd].call(process);\n        };\n      }\n      #unhookProcessCwd() {\n        if (this[kOriginalChdir] === null) {\n          return;\n        }\n        process.chdir = this[kOriginalChdir];\n        process.cwd = this[kOriginalCwd];\n        this[kOriginalChdir] = null;\n        this[kOriginalCwd] = null;\n      }\n      // ==================== Path Resolution ====================\n      #toProviderPath(inputPath) {\n        const resolved = this.resolvePath(inputPath);\n        if (this[kMounted] && this[kMountPoint]) {\n          if (!isUnderMountPoint(resolved, this[kMountPoint])) {\n            throw createENOENT("open", inputPath);\n          }\n          return getRelativePath(resolved, this[kMountPoint]);\n        }\n        return resolved;\n      }\n      #toMountedPath(providerPath) {\n        if (this[kMounted] && this[kMountPoint]) {\n          return joinVFSPath(this[kMountPoint], providerPath);\n        }\n        return providerPath;\n      }\n      shouldHandle(inputPath) {\n        if (!this[kMounted] || !this[kMountPoint]) {\n          return false;\n        }\n        const normalized = normalizeVFSPath(inputPath);\n        if (!isUnderMountPoint(normalized, this[kMountPoint])) {\n          return false;\n        }\n        if (this[kOverlay]) {\n          try {\n            const providerPath = getRelativePath(normalized, this[kMountPoint]);\n            return this[kProvider].existsSync(providerPath);\n          } catch {\n            return false;\n          }\n        }\n        return true;\n      }\n      // ==================== FS Operations (Sync) ====================\n      existsSync(filePath) {\n        try {\n          const providerPath = this.#toProviderPath(filePath);\n          return this[kProvider].existsSync(providerPath);\n        } catch {\n          return false;\n        }\n      }\n      statSync(filePath, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        return this[kProvider].statSync(providerPath, options);\n      }\n      lstatSync(filePath, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        return this[kProvider].lstatSync(providerPath, options);\n      }\n      readFileSync(filePath, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        return this[kProvider].readFileSync(providerPath, options);\n      }\n      writeFileSync(filePath, data, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].writeFileSync(providerPath, data, options);\n      }\n      appendFileSync(filePath, data, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].appendFileSync(providerPath, data, options);\n      }\n      readdirSync(dirPath, options) {\n        const providerPath = this.#toProviderPath(dirPath);\n        return this[kProvider].readdirSync(providerPath, options);\n      }\n      mkdirSync(dirPath, options) {\n        const providerPath = this.#toProviderPath(dirPath);\n        const result = this[kProvider].mkdirSync(providerPath, options);\n        if (result !== void 0) {\n          return this.#toMountedPath(result);\n        }\n        return void 0;\n      }\n      rmdirSync(dirPath) {\n        const providerPath = this.#toProviderPath(dirPath);\n        this[kProvider].rmdirSync(providerPath);\n      }\n      unlinkSync(filePath) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].unlinkSync(providerPath);\n      }\n      renameSync(oldPath, newPath) {\n        const oldProviderPath = this.#toProviderPath(oldPath);\n        const newProviderPath = this.#toProviderPath(newPath);\n        this[kProvider].renameSync(oldProviderPath, newProviderPath);\n      }\n      copyFileSync(src, dest, mode) {\n        const srcProviderPath = this.#toProviderPath(src);\n        const destProviderPath = this.#toProviderPath(dest);\n        this[kProvider].copyFileSync(srcProviderPath, destProviderPath, mode);\n      }\n      realpathSync(filePath, options) {\n        const providerPath = this.#toProviderPath(filePath);\n        const realProviderPath = this[kProvider].realpathSync(providerPath, options);\n        return this.#toMountedPath(realProviderPath);\n      }\n      readlinkSync(linkPath, options) {\n        const providerPath = this.#toProviderPath(linkPath);\n        return this[kProvider].readlinkSync(providerPath, options);\n      }\n      symlinkSync(target, path2, type) {\n        const providerPath = this.#toProviderPath(path2);\n        this[kProvider].symlinkSync(target, providerPath, type);\n      }\n      accessSync(filePath, mode) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].accessSync(providerPath, mode);\n      }\n      internalModuleStat(filePath) {\n        try {\n          const providerPath = this.#toProviderPath(filePath);\n          return this[kProvider].internalModuleStat(providerPath);\n        } catch {\n          return -2;\n        }\n      }\n      // ==================== File Descriptor Operations ====================\n      openSync(filePath, flags = "r", mode) {\n        const providerPath = this.#toProviderPath(filePath);\n        const handle = this[kProvider].openSync(providerPath, flags, mode);\n        return openVirtualFd(handle);\n      }\n      closeSync(fd) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          throw createEBADF("close");\n        }\n        vfd.entry.closeSync();\n        closeVirtualFd(fd);\n      }\n      readSync(fd, buffer, offset, length, position) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          throw createEBADF("read");\n        }\n        return vfd.entry.readSync(buffer, offset, length, position);\n      }\n      fstatSync(fd, options) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          throw createEBADF("fstat");\n        }\n        return vfd.entry.statSync(options);\n      }\n      // ==================== FS Operations (Async with Callbacks) ====================\n      readFile(filePath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].readFile(this.#toProviderPath(filePath), options).then((data) => callback(null, data), (err) => callback(err));\n      }\n      writeFile(filePath, data, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].writeFile(this.#toProviderPath(filePath), data, options).then(() => callback(null), (err) => callback(err));\n      }\n      stat(filePath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].stat(this.#toProviderPath(filePath), options).then((stats) => callback(null, stats), (err) => callback(err));\n      }\n      lstat(filePath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].lstat(this.#toProviderPath(filePath), options).then((stats) => callback(null, stats), (err) => callback(err));\n      }\n      readdir(dirPath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].readdir(this.#toProviderPath(dirPath), options).then((entries) => callback(null, entries), (err) => callback(err));\n      }\n      realpath(filePath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].realpath(this.#toProviderPath(filePath), options).then((realPath) => callback(null, this.#toMountedPath(realPath)), (err) => callback(err));\n      }\n      readlink(linkPath, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        this[kProvider].readlink(this.#toProviderPath(linkPath), options).then((target) => callback(null, target), (err) => callback(err));\n      }\n      access(filePath, mode, callback) {\n        if (typeof mode === "function") {\n          callback = mode;\n          mode = void 0;\n        }\n        this[kProvider].access(this.#toProviderPath(filePath), mode).then(() => callback(null), (err) => callback(err));\n      }\n      open(filePath, flags, mode, callback) {\n        if (typeof flags === "function") {\n          callback = flags;\n          flags = "r";\n          mode = void 0;\n        } else if (typeof mode === "function") {\n          callback = mode;\n          mode = void 0;\n        }\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].open(providerPath, flags, mode).then((handle) => {\n          const fd = openVirtualFd(handle);\n          callback(null, fd);\n        }, (err) => callback(err));\n      }\n      close(fd, callback) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          process.nextTick(callback, createEBADF("close"));\n          return;\n        }\n        vfd.entry.close().then(() => {\n          closeVirtualFd(fd);\n          callback(null);\n        }, (err) => callback(err));\n      }\n      read(fd, buffer, offset, length, position, callback) {\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          process.nextTick(callback, createEBADF("read"));\n          return;\n        }\n        vfd.entry.read(buffer, offset, length, position).then(({ bytesRead }) => callback(null, bytesRead, buffer), (err) => callback(err));\n      }\n      fstat(fd, options, callback) {\n        if (typeof options === "function") {\n          callback = options;\n          options = void 0;\n        }\n        const vfd = getVirtualFd(fd);\n        if (!vfd) {\n          process.nextTick(callback, createEBADF("fstat"));\n          return;\n        }\n        vfd.entry.stat(options).then((stats) => callback(null, stats), (err) => callback(err));\n      }\n      // ==================== Stream Operations ====================\n      createReadStream(filePath, options) {\n        return new VirtualReadStream(this, filePath, options);\n      }\n      // ==================== Watch Operations ====================\n      watch(filePath, options, listener) {\n        if (typeof options === "function") {\n          listener = options;\n          options = {};\n        }\n        const providerPath = this.#toProviderPath(filePath);\n        const watcher = this[kProvider].watch(providerPath, options);\n        if (listener) {\n          watcher.on("change", listener);\n        }\n        return watcher;\n      }\n      watchFile(filePath, options, listener) {\n        if (typeof options === "function") {\n          listener = options;\n          options = {};\n        }\n        const providerPath = this.#toProviderPath(filePath);\n        return this[kProvider].watchFile(providerPath, options, listener);\n      }\n      unwatchFile(filePath, listener) {\n        const providerPath = this.#toProviderPath(filePath);\n        this[kProvider].unwatchFile(providerPath, listener);\n      }\n      // ==================== Promise API ====================\n      get promises() {\n        if (this[kPromises] === null) {\n          this[kPromises] = this.#createPromisesAPI();\n        }\n        return this[kPromises];\n      }\n      #createPromisesAPI() {\n        const provider = this[kProvider];\n        const toProviderPath = (p) => this.#toProviderPath(p);\n        const toMountedPath = (p) => this.#toMountedPath(p);\n        return Object.freeze({\n          async readFile(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.readFile(providerPath, options);\n          },\n          async writeFile(filePath, data, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.writeFile(providerPath, data, options);\n          },\n          async appendFile(filePath, data, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.appendFile(providerPath, data, options);\n          },\n          async stat(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.stat(providerPath, options);\n          },\n          async lstat(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.lstat(providerPath, options);\n          },\n          async readdir(dirPath, options) {\n            const providerPath = toProviderPath(dirPath);\n            return provider.readdir(providerPath, options);\n          },\n          async mkdir(dirPath, options) {\n            const providerPath = toProviderPath(dirPath);\n            const result = await provider.mkdir(providerPath, options);\n            if (result !== void 0) {\n              return toMountedPath(result);\n            }\n            return void 0;\n          },\n          async rmdir(dirPath) {\n            const providerPath = toProviderPath(dirPath);\n            return provider.rmdir(providerPath);\n          },\n          async unlink(filePath) {\n            const providerPath = toProviderPath(filePath);\n            return provider.unlink(providerPath);\n          },\n          async rename(oldPath, newPath) {\n            const oldProviderPath = toProviderPath(oldPath);\n            const newProviderPath = toProviderPath(newPath);\n            return provider.rename(oldProviderPath, newProviderPath);\n          },\n          async copyFile(src, dest, mode) {\n            const srcProviderPath = toProviderPath(src);\n            const destProviderPath = toProviderPath(dest);\n            return provider.copyFile(srcProviderPath, destProviderPath, mode);\n          },\n          async realpath(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            const realPath = await provider.realpath(providerPath, options);\n            return toMountedPath(realPath);\n          },\n          async readlink(linkPath, options) {\n            const providerPath = toProviderPath(linkPath);\n            return provider.readlink(providerPath, options);\n          },\n          async symlink(target, path2, type) {\n            const providerPath = toProviderPath(path2);\n            return provider.symlink(target, providerPath, type);\n          },\n          async access(filePath, mode) {\n            const providerPath = toProviderPath(filePath);\n            return provider.access(providerPath, mode);\n          },\n          watch(filePath, options) {\n            const providerPath = toProviderPath(filePath);\n            return provider.watchAsync(providerPath, options);\n          }\n        });\n      }\n    };\n    module2.exports = {\n      VirtualFileSystem\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/providers/real.js\nvar require_real = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/providers/real.js"(exports2, module2) {\n    "use strict";\n    var fs = require("node:fs");\n    var path = require("node:path");\n    var { VirtualProvider } = require_provider();\n    var { VirtualFileHandle } = require_file_handle();\n    var {\n      createEBADF,\n      createENOENT,\n      ERR_INVALID_ARG_VALUE\n    } = require_errors();\n    var RealFileHandle = class extends VirtualFileHandle {\n      #fd;\n      #realPath;\n      #checkClosed() {\n        if (this.closed) {\n          throw createEBADF("read");\n        }\n      }\n      constructor(path2, flags, mode, fd, realPath) {\n        super(path2, flags, mode);\n        this.#fd = fd;\n        this.#realPath = realPath;\n      }\n      get fd() {\n        return this.#fd;\n      }\n      readSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        return fs.readSync(this.#fd, buffer, offset, length, position);\n      }\n      async read(buffer, offset, length, position) {\n        this.#checkClosed();\n        return new Promise((resolve, reject) => {\n          fs.read(this.#fd, buffer, offset, length, position, (err, bytesRead) => {\n            if (err) reject(err);\n            else resolve({ bytesRead, buffer });\n          });\n        });\n      }\n      writeSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        return fs.writeSync(this.#fd, buffer, offset, length, position);\n      }\n      async write(buffer, offset, length, position) {\n        this.#checkClosed();\n        return new Promise((resolve, reject) => {\n          fs.write(this.#fd, buffer, offset, length, position, (err, bytesWritten) => {\n            if (err) reject(err);\n            else resolve({ bytesWritten, buffer });\n          });\n        });\n      }\n      readFileSync(options) {\n        this.#checkClosed();\n        return fs.readFileSync(this.#realPath, options);\n      }\n      async readFile(options) {\n        this.#checkClosed();\n        return fs.promises.readFile(this.#realPath, options);\n      }\n      writeFileSync(data, options) {\n        this.#checkClosed();\n        fs.writeFileSync(this.#realPath, data, options);\n      }\n      async writeFile(data, options) {\n        this.#checkClosed();\n        return fs.promises.writeFile(this.#realPath, data, options);\n      }\n      statSync(options) {\n        this.#checkClosed();\n        return fs.fstatSync(this.#fd, options);\n      }\n      async stat(options) {\n        this.#checkClosed();\n        return new Promise((resolve, reject) => {\n          fs.fstat(this.#fd, options, (err, stats) => {\n            if (err) reject(err);\n            else resolve(stats);\n          });\n        });\n      }\n      truncateSync(len = 0) {\n        this.#checkClosed();\n        fs.ftruncateSync(this.#fd, len);\n      }\n      async truncate(len = 0) {\n        this.#checkClosed();\n        return new Promise((resolve, reject) => {\n          fs.ftruncate(this.#fd, len, (err) => {\n            if (err) reject(err);\n            else resolve();\n          });\n        });\n      }\n      closeSync() {\n        if (!this.closed) {\n          fs.closeSync(this.#fd);\n          super.closeSync();\n        }\n      }\n      async close() {\n        if (!this.closed) {\n          return new Promise((resolve, reject) => {\n            fs.close(this.#fd, (err) => {\n              if (err) reject(err);\n              else {\n                super.closeSync();\n                resolve();\n              }\n            });\n          });\n        }\n      }\n    };\n    var RealFSProvider = class extends VirtualProvider {\n      #rootPath;\n      constructor(rootPath) {\n        super();\n        if (typeof rootPath !== "string" || rootPath === "") {\n          throw new ERR_INVALID_ARG_VALUE("rootPath", rootPath, "must be a non-empty string");\n        }\n        this.#rootPath = path.resolve(rootPath);\n      }\n      get rootPath() {\n        return this.#rootPath;\n      }\n      get readonly() {\n        return false;\n      }\n      get supportsSymlinks() {\n        return true;\n      }\n      #resolvePath(vfsPath) {\n        let normalized = vfsPath;\n        if (normalized.startsWith("/")) {\n          normalized = normalized.slice(1);\n        }\n        const realPath = path.resolve(this.#rootPath, normalized);\n        const rootWithSep = this.#rootPath.endsWith(path.sep) ? this.#rootPath : this.#rootPath + path.sep;\n        if (realPath !== this.#rootPath && !realPath.startsWith(rootWithSep)) {\n          throw createENOENT("open", vfsPath);\n        }\n        return realPath;\n      }\n      openSync(vfsPath, flags, mode) {\n        const realPath = this.#resolvePath(vfsPath);\n        const fd = fs.openSync(realPath, flags, mode);\n        return new RealFileHandle(vfsPath, flags, mode ?? 420, fd, realPath);\n      }\n      async open(vfsPath, flags, mode) {\n        const realPath = this.#resolvePath(vfsPath);\n        return new Promise((resolve, reject) => {\n          fs.open(realPath, flags, mode, (err, fd) => {\n            if (err) reject(err);\n            else resolve(new RealFileHandle(vfsPath, flags, mode ?? 420, fd, realPath));\n          });\n        });\n      }\n      statSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.statSync(realPath, options);\n      }\n      async stat(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.stat(realPath, options);\n      }\n      lstatSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.lstatSync(realPath, options);\n      }\n      async lstat(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.lstat(realPath, options);\n      }\n      readdirSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.readdirSync(realPath, options);\n      }\n      async readdir(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.readdir(realPath, options);\n      }\n      mkdirSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.mkdirSync(realPath, options);\n      }\n      async mkdir(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.mkdir(realPath, options);\n      }\n      rmdirSync(vfsPath) {\n        const realPath = this.#resolvePath(vfsPath);\n        fs.rmdirSync(realPath);\n      }\n      async rmdir(vfsPath) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.rmdir(realPath);\n      }\n      unlinkSync(vfsPath) {\n        const realPath = this.#resolvePath(vfsPath);\n        fs.unlinkSync(realPath);\n      }\n      async unlink(vfsPath) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.unlink(realPath);\n      }\n      renameSync(oldVfsPath, newVfsPath) {\n        const oldRealPath = this.#resolvePath(oldVfsPath);\n        const newRealPath = this.#resolvePath(newVfsPath);\n        fs.renameSync(oldRealPath, newRealPath);\n      }\n      async rename(oldVfsPath, newVfsPath) {\n        const oldRealPath = this.#resolvePath(oldVfsPath);\n        const newRealPath = this.#resolvePath(newVfsPath);\n        return fs.promises.rename(oldRealPath, newRealPath);\n      }\n      readlinkSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.readlinkSync(realPath, options);\n      }\n      async readlink(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.readlink(realPath, options);\n      }\n      symlinkSync(target, vfsPath, type) {\n        const realPath = this.#resolvePath(vfsPath);\n        fs.symlinkSync(target, realPath, type);\n      }\n      async symlink(target, vfsPath, type) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.symlink(target, realPath, type);\n      }\n      realpathSync(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        const resolved = fs.realpathSync(realPath, options);\n        if (resolved === this.#rootPath) {\n          return "/";\n        }\n        const rootWithSep = this.#rootPath + path.sep;\n        if (resolved.startsWith(rootWithSep)) {\n          return "/" + resolved.slice(rootWithSep.length).replace(/\\\\/g, "/");\n        }\n        return vfsPath;\n      }\n      async realpath(vfsPath, options) {\n        const realPath = this.#resolvePath(vfsPath);\n        const resolved = await fs.promises.realpath(realPath, options);\n        if (resolved === this.#rootPath) {\n          return "/";\n        }\n        const rootWithSep = this.#rootPath + path.sep;\n        if (resolved.startsWith(rootWithSep)) {\n          return "/" + resolved.slice(rootWithSep.length).replace(/\\\\/g, "/");\n        }\n        return vfsPath;\n      }\n      accessSync(vfsPath, mode) {\n        const realPath = this.#resolvePath(vfsPath);\n        fs.accessSync(realPath, mode);\n      }\n      async access(vfsPath, mode) {\n        const realPath = this.#resolvePath(vfsPath);\n        return fs.promises.access(realPath, mode);\n      }\n      copyFileSync(srcVfsPath, destVfsPath, mode) {\n        const srcRealPath = this.#resolvePath(srcVfsPath);\n        const destRealPath = this.#resolvePath(destVfsPath);\n        fs.copyFileSync(srcRealPath, destRealPath, mode);\n      }\n      async copyFile(srcVfsPath, destVfsPath, mode) {\n        const srcRealPath = this.#resolvePath(srcVfsPath);\n        const destRealPath = this.#resolvePath(destVfsPath);\n        return fs.promises.copyFile(srcRealPath, destRealPath, mode);\n      }\n    };\n    module2.exports = {\n      RealFSProvider,\n      RealFileHandle\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/lib/providers/sqlite.js\nvar require_sqlite = __commonJS({\n  "node_modules/@roberts_lando/vfs/lib/providers/sqlite.js"(exports2, module2) {\n    "use strict";\n    var { Buffer: Buffer2 } = require("node:buffer");\n    var { posix: pathPosix } = require("node:path");\n    var { DatabaseSync } = require("node:sqlite");\n    var { VirtualProvider } = require_provider();\n    var { VirtualFileHandle } = require_file_handle();\n    var {\n      VFSWatcher,\n      VFSStatWatcher,\n      VFSWatchAsyncIterable\n    } = require_watcher();\n    var {\n      createENOENT,\n      createENOTDIR,\n      createENOTEMPTY,\n      createEISDIR,\n      createEEXIST,\n      createEINVAL,\n      createELOOP,\n      createEROFS\n    } = require_errors();\n    var {\n      createFileStats,\n      createDirectoryStats,\n      createSymlinkStats\n    } = require_stats();\n    var UV_DIRENT_FILE = 1;\n    var UV_DIRENT_DIR = 2;\n    var UV_DIRENT_LINK = 3;\n    var VirtualDirent = class {\n      #name;\n      #type;\n      #parentPath;\n      constructor(name, type, parentPath) {\n        this.#name = name;\n        this.#type = type;\n        this.#parentPath = parentPath;\n      }\n      get name() {\n        return this.#name;\n      }\n      get parentPath() {\n        return this.#parentPath;\n      }\n      get path() {\n        return this.#parentPath;\n      }\n      isFile() {\n        return this.#type === UV_DIRENT_FILE;\n      }\n      isDirectory() {\n        return this.#type === UV_DIRENT_DIR;\n      }\n      isSymbolicLink() {\n        return this.#type === UV_DIRENT_LINK;\n      }\n      isBlockDevice() {\n        return false;\n      }\n      isCharacterDevice() {\n        return false;\n      }\n      isFIFO() {\n        return false;\n      }\n      isSocket() {\n        return false;\n      }\n    };\n    var TYPE_FILE = 0;\n    var TYPE_DIR = 1;\n    var TYPE_SYMLINK = 2;\n    var kMaxSymlinkDepth = 40;\n    var SqliteFileHandle = class extends VirtualFileHandle {\n      #content;\n      #updateStmt;\n      #path;\n      #getStats;\n      #checkClosed() {\n        if (this.closed) {\n          const { createEBADF } = require_errors();\n          throw createEBADF("read");\n        }\n      }\n      constructor(path, flags, mode, content, updateStmt, getStats) {\n        super(path, flags, mode);\n        this.#content = content;\n        this.#updateStmt = updateStmt;\n        this.#path = path;\n        this.#getStats = getStats;\n        if (flags === "w" || flags === "w+") {\n          this.#content = Buffer2.alloc(0);\n          this.#flush();\n        } else if (flags === "a" || flags === "a+") {\n          this.position = this.#content.length;\n        }\n      }\n      #flush() {\n        const now = Date.now();\n        this.#updateStmt.run(this.#content, now, this.#path);\n      }\n      get content() {\n        return this.#content;\n      }\n      readSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        const content = this.#content;\n        const readPos = position !== null && position !== void 0 ? position : this.position;\n        const available = content.length - readPos;\n        if (available <= 0) {\n          return 0;\n        }\n        const bytesToRead = Math.min(length, available);\n        content.copy(buffer, offset, readPos, readPos + bytesToRead);\n        if (position === null || position === void 0) {\n          this.position = readPos + bytesToRead;\n        }\n        return bytesToRead;\n      }\n      async read(buffer, offset, length, position) {\n        const bytesRead = this.readSync(buffer, offset, length, position);\n        return { bytesRead, buffer };\n      }\n      writeSync(buffer, offset, length, position) {\n        this.#checkClosed();\n        const writePos = position !== null && position !== void 0 ? position : this.position;\n        const data = buffer.subarray(offset, offset + length);\n        if (writePos + length > this.#content.length) {\n          const newContent = Buffer2.alloc(writePos + length);\n          this.#content.copy(newContent, 0, 0, this.#content.length);\n          this.#content = newContent;\n        }\n        data.copy(this.#content, writePos);\n        this.#flush();\n        if (position === null || position === void 0) {\n          this.position = writePos + length;\n        }\n        return length;\n      }\n      async write(buffer, offset, length, position) {\n        const bytesWritten = this.writeSync(buffer, offset, length, position);\n        return { bytesWritten, buffer };\n      }\n      readFileSync(options) {\n        this.#checkClosed();\n        const content = this.#content;\n        const encoding = typeof options === "string" ? options : options?.encoding;\n        if (encoding) {\n          return content.toString(encoding);\n        }\n        return Buffer2.from(content);\n      }\n      async readFile(options) {\n        return this.readFileSync(options);\n      }\n      writeFileSync(data, options) {\n        this.#checkClosed();\n        const buffer = typeof data === "string" ? Buffer2.from(data, options?.encoding) : data;\n        if (this.flags === "a" || this.flags === "a+") {\n          const newContent = Buffer2.alloc(this.#content.length + buffer.length);\n          this.#content.copy(newContent, 0);\n          buffer.copy(newContent, this.#content.length);\n          this.#content = newContent;\n        } else {\n          this.#content = Buffer2.from(buffer);\n        }\n        this.#flush();\n        this.position = this.#content.length;\n      }\n      async writeFile(data, options) {\n        this.writeFileSync(data, options);\n      }\n      statSync(options) {\n        this.#checkClosed();\n        if (this.#getStats) {\n          return this.#getStats(this.#content.length);\n        }\n        const { ERR_INVALID_STATE } = require_errors();\n        throw new ERR_INVALID_STATE("stats not available");\n      }\n      async stat(options) {\n        return this.statSync(options);\n      }\n      truncateSync(len = 0) {\n        this.#checkClosed();\n        if (len < this.#content.length) {\n          this.#content = this.#content.subarray(0, len);\n        } else if (len > this.#content.length) {\n          const newContent = Buffer2.alloc(len);\n          this.#content.copy(newContent, 0, 0, this.#content.length);\n          this.#content = newContent;\n        }\n        this.#flush();\n      }\n      async truncate(len) {\n        this.truncateSync(len);\n      }\n    };\n    var SqliteProvider = class extends VirtualProvider {\n      #db;\n      #readonly;\n      #statWatchers;\n      // Prepared statements\n      #stmtGet;\n      #stmtInsert;\n      #stmtUpdateContent;\n      #stmtDelete;\n      #stmtChildren;\n      #stmtDescendants;\n      constructor(pathOrMemory) {\n        super();\n        this.#readonly = false;\n        this.#statWatchers = /* @__PURE__ */ new Map();\n        this.#db = new DatabaseSync(pathOrMemory ?? ":memory:");\n        this.#db.exec(`\n      CREATE TABLE IF NOT EXISTS entries (\n        path        TEXT PRIMARY KEY,\n        parent_path TEXT,\n        name        TEXT,\n        type        INTEGER NOT NULL,\n        content     BLOB,\n        target      TEXT,\n        mode        INTEGER NOT NULL,\n        mtime       REAL NOT NULL,\n        ctime       REAL NOT NULL,\n        birthtime   REAL NOT NULL\n      );\n      CREATE INDEX IF NOT EXISTS idx_parent ON entries(parent_path);\n    `);\n        const root = this.#db.prepare(\n          "SELECT path FROM entries WHERE path = ?"\n        ).get("/");\n        if (!root) {\n          const now = Date.now();\n          this.#db.prepare(\n            "INSERT INTO entries (path, parent_path, name, type, content, target, mode, mtime, ctime, birthtime) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"\n          ).run("/", null, "", TYPE_DIR, null, null, 493, now, now, now);\n        }\n        this.#stmtGet = this.#db.prepare(\n          "SELECT * FROM entries WHERE path = ?"\n        );\n        this.#stmtInsert = this.#db.prepare(\n          "INSERT INTO entries (path, parent_path, name, type, content, target, mode, mtime, ctime, birthtime) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"\n        );\n        this.#stmtUpdateContent = this.#db.prepare(\n          "UPDATE entries SET content=?, mtime=? WHERE path=?"\n        );\n        this.#stmtDelete = this.#db.prepare(\n          "DELETE FROM entries WHERE path = ?"\n        );\n        this.#stmtChildren = this.#db.prepare(\n          "SELECT * FROM entries WHERE parent_path = ?"\n        );\n        this.#stmtDescendants = this.#db.prepare(\n          "SELECT * FROM entries WHERE path LIKE ? AND path != ?"\n        );\n      }\n      get readonly() {\n        return this.#readonly;\n      }\n      get supportsWatch() {\n        return true;\n      }\n      get supportsSymlinks() {\n        return true;\n      }\n      setReadOnly() {\n        this.#readonly = true;\n      }\n      close() {\n        for (const watcher of this.#statWatchers.values()) {\n          watcher.stop();\n        }\n        this.#statWatchers.clear();\n        this.#db.close();\n      }\n      #normalizePath(path) {\n        let normalized = path.replace(/\\\\/g, "/");\n        if (!normalized.startsWith("/")) {\n          normalized = "/" + normalized;\n        }\n        return pathPosix.normalize(normalized);\n      }\n      #getParentPath(path) {\n        if (path === "/") {\n          return null;\n        }\n        return pathPosix.dirname(path);\n      }\n      #getBaseName(path) {\n        return pathPosix.basename(path);\n      }\n      #resolveSymlinkTarget(symlinkPath, target) {\n        if (target.startsWith("/")) {\n          return this.#normalizePath(target);\n        }\n        const parentPath = this.#getParentPath(symlinkPath) || "/";\n        return this.#normalizePath(pathPosix.join(parentPath, target));\n      }\n      #getRow(path) {\n        return this.#stmtGet.get(path);\n      }\n      #lookupEntry(path, followSymlinks = true, depth = 0) {\n        const normalized = this.#normalizePath(path);\n        if (normalized === "/") {\n          const row2 = this.#getRow("/");\n          return { row: row2, resolvedPath: "/" };\n        }\n        const segments = normalized.slice(1).split("/");\n        let currentPath = "/";\n        for (let i = 0; i < segments.length; i++) {\n          const segment = segments[i];\n          const nextPath = currentPath === "/" ? "/" + segment : currentPath + "/" + segment;\n          const currentRow = this.#getRow(currentPath);\n          if (!currentRow) {\n            return { row: null, resolvedPath: null };\n          }\n          if (currentRow.type === TYPE_SYMLINK) {\n            if (depth >= kMaxSymlinkDepth) {\n              return { row: null, resolvedPath: null, eloop: true };\n            }\n            const targetPath = this.#resolveSymlinkTarget(currentPath, currentRow.target);\n            const result = this.#lookupEntry(targetPath, true, depth + 1);\n            if (result.eloop) {\n              return result;\n            }\n            if (!result.row) {\n              return { row: null, resolvedPath: null };\n            }\n            const remaining = segments.slice(i).join("/");\n            const fullPath = result.resolvedPath === "/" ? "/" + remaining : result.resolvedPath + "/" + remaining;\n            return this.#lookupEntry(fullPath, followSymlinks, depth + 1);\n          }\n          if (currentRow.type !== TYPE_DIR) {\n            return { row: null, resolvedPath: null };\n          }\n          currentPath = nextPath;\n        }\n        const row = this.#getRow(currentPath);\n        if (!row) {\n          return { row: null, resolvedPath: null };\n        }\n        if (row.type === TYPE_SYMLINK && followSymlinks) {\n          if (depth >= kMaxSymlinkDepth) {\n            return { row: null, resolvedPath: null, eloop: true };\n          }\n          const targetPath = this.#resolveSymlinkTarget(currentPath, row.target);\n          return this.#lookupEntry(targetPath, true, depth + 1);\n        }\n        return { row, resolvedPath: currentPath };\n      }\n      #getEntry(path, syscall, followSymlinks = true) {\n        const result = this.#lookupEntry(path, followSymlinks);\n        if (result.eloop) {\n          throw createELOOP(syscall, path);\n        }\n        if (!result.row) {\n          throw createENOENT(syscall, path);\n        }\n        return result.row;\n      }\n      #ensureParent(path, create, syscall) {\n        const parentPath = this.#getParentPath(path);\n        if (parentPath === null) {\n          return this.#getRow("/");\n        }\n        const result = this.#lookupEntry(parentPath, true);\n        if (result.row) {\n          if (result.row.type !== TYPE_DIR) {\n            throw createENOTDIR(syscall, path);\n          }\n          return result.row;\n        }\n        if (create) {\n          const segments = parentPath.slice(1).split("/");\n          let currentPath = "";\n          for (const segment of segments) {\n            currentPath += "/" + segment;\n            const existing = this.#getRow(currentPath);\n            if (!existing) {\n              const now = Date.now();\n              const pp = this.#getParentPath(currentPath);\n              this.#stmtInsert.run(currentPath, pp, segment, TYPE_DIR, null, null, 493, now, now, now);\n            } else if (existing.type !== TYPE_DIR) {\n              throw createENOTDIR(syscall, path);\n            }\n          }\n          return this.#getRow(parentPath);\n        }\n        throw createENOENT(syscall, path);\n      }\n      #createStats(row, size) {\n        const options = {\n          mode: row.mode,\n          mtimeMs: row.mtime,\n          ctimeMs: row.ctime,\n          birthtimeMs: row.birthtime\n        };\n        if (row.type === TYPE_FILE) {\n          const content = row.content;\n          const fileSize = size !== void 0 ? size : content ? content.byteLength : 0;\n          return createFileStats(fileSize, options);\n        } else if (row.type === TYPE_DIR) {\n          return createDirectoryStats(options);\n        } else if (row.type === TYPE_SYMLINK) {\n          return createSymlinkStats(row.target.length, options);\n        }\n        const { ERR_INVALID_STATE } = require_errors();\n        throw new ERR_INVALID_STATE("Unknown entry type");\n      }\n      openSync(path, flags, mode) {\n        const normalized = this.#normalizePath(path);\n        const isCreate = flags === "w" || flags === "w+" || flags === "a" || flags === "a+";\n        if (this.readonly && isCreate) {\n          throw createEROFS("open", path);\n        }\n        let row;\n        try {\n          row = this.#getEntry(normalized, "open");\n        } catch (err) {\n          if (err.code === "ENOENT" && isCreate) {\n            this.#ensureParent(normalized, true, "open");\n            const name = this.#getBaseName(normalized);\n            const parentPath = this.#getParentPath(normalized);\n            const now = Date.now();\n            const fileMode = mode ?? 420;\n            this.#stmtInsert.run(normalized, parentPath, name, TYPE_FILE, Buffer2.alloc(0), null, fileMode, now, now, now);\n            row = this.#getRow(normalized);\n          } else {\n            throw err;\n          }\n        }\n        if (row.type === TYPE_DIR) {\n          throw createEISDIR("open", path);\n        }\n        if (row.type === TYPE_SYMLINK) {\n          throw createEINVAL("open", path);\n        }\n        const content = row.content ? Buffer2.from(row.content) : Buffer2.alloc(0);\n        const getStats = (size) => this.#createStats(this.#getRow(normalized) || row, size);\n        return new SqliteFileHandle(normalized, flags, mode ?? row.mode, content, this.#stmtUpdateContent, getStats);\n      }\n      async open(path, flags, mode) {\n        return this.openSync(path, flags, mode);\n      }\n      statSync(path, options) {\n        const row = this.#getEntry(path, "stat", true);\n        return this.#createStats(row);\n      }\n      async stat(path, options) {\n        return this.statSync(path, options);\n      }\n      lstatSync(path, options) {\n        const row = this.#getEntry(path, "lstat", false);\n        return this.#createStats(row);\n      }\n      async lstat(path, options) {\n        return this.lstatSync(path, options);\n      }\n      readdirSync(path, options) {\n        const result = this.#lookupEntry(path, true);\n        if (result.eloop) {\n          throw createELOOP("scandir", path);\n        }\n        if (!result.row) {\n          throw createENOENT("scandir", path);\n        }\n        if (result.row.type !== TYPE_DIR) {\n          throw createENOTDIR("scandir", path);\n        }\n        const children = this.#stmtChildren.all(result.resolvedPath);\n        if (options?.withFileTypes) {\n          const normalized = this.#normalizePath(path);\n          return children.map((child) => {\n            let type;\n            if (child.type === TYPE_SYMLINK) {\n              type = UV_DIRENT_LINK;\n            } else if (child.type === TYPE_DIR) {\n              type = UV_DIRENT_DIR;\n            } else {\n              type = UV_DIRENT_FILE;\n            }\n            return new VirtualDirent(child.name, type, normalized);\n          });\n        }\n        return children.map((child) => child.name);\n      }\n      async readdir(path, options) {\n        return this.readdirSync(path, options);\n      }\n      mkdirSync(path, options) {\n        if (this.readonly) {\n          throw createEROFS("mkdir", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const recursive = options?.recursive === true;\n        const existing = this.#lookupEntry(normalized, true);\n        if (existing.row) {\n          if (existing.row.type === TYPE_DIR && recursive) {\n            return void 0;\n          }\n          throw createEEXIST("mkdir", path);\n        }\n        if (recursive) {\n          const segments = normalized.slice(1).split("/");\n          let currentPath = "";\n          for (const segment of segments) {\n            currentPath += "/" + segment;\n            const row = this.#getRow(currentPath);\n            if (!row) {\n              const now = Date.now();\n              const pp = this.#getParentPath(currentPath);\n              this.#stmtInsert.run(currentPath, pp, segment, TYPE_DIR, null, null, options?.mode ?? 493, now, now, now);\n            } else if (row.type !== TYPE_DIR) {\n              throw createENOTDIR("mkdir", path);\n            }\n          }\n        } else {\n          this.#ensureParent(normalized, false, "mkdir");\n          const name = this.#getBaseName(normalized);\n          const parentPath = this.#getParentPath(normalized);\n          const now = Date.now();\n          this.#stmtInsert.run(normalized, parentPath, name, TYPE_DIR, null, null, options?.mode ?? 493, now, now, now);\n        }\n        return recursive ? normalized : void 0;\n      }\n      async mkdir(path, options) {\n        return this.mkdirSync(path, options);\n      }\n      rmdirSync(path) {\n        if (this.readonly) {\n          throw createEROFS("rmdir", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const row = this.#getEntry(normalized, "rmdir", true);\n        if (row.type !== TYPE_DIR) {\n          throw createENOTDIR("rmdir", path);\n        }\n        const children = this.#stmtChildren.all(normalized);\n        if (children.length > 0) {\n          throw createENOTEMPTY("rmdir", path);\n        }\n        this.#stmtDelete.run(normalized);\n      }\n      async rmdir(path) {\n        this.rmdirSync(path);\n      }\n      unlinkSync(path) {\n        if (this.readonly) {\n          throw createEROFS("unlink", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const row = this.#getEntry(normalized, "unlink", false);\n        if (row.type === TYPE_DIR) {\n          throw createEISDIR("unlink", path);\n        }\n        this.#stmtDelete.run(normalized);\n      }\n      async unlink(path) {\n        this.unlinkSync(path);\n      }\n      renameSync(oldPath, newPath) {\n        if (this.readonly) {\n          throw createEROFS("rename", oldPath);\n        }\n        const normalizedOld = this.#normalizePath(oldPath);\n        const normalizedNew = this.#normalizePath(newPath);\n        const row = this.#getEntry(normalizedOld, "rename", false);\n        this.#ensureParent(normalizedNew, true, "rename");\n        const newName = this.#getBaseName(normalizedNew);\n        const newParentPath = this.#getParentPath(normalizedNew);\n        if (row.type === TYPE_DIR) {\n          this.#db.exec("BEGIN");\n          try {\n            this.#stmtDelete.run(normalizedOld);\n            const now = Date.now();\n            this.#stmtDelete.run(normalizedNew);\n            this.#stmtInsert.run(\n              normalizedNew,\n              newParentPath,\n              newName,\n              row.type,\n              row.content,\n              row.target,\n              row.mode,\n              now,\n              row.ctime,\n              row.birthtime\n            );\n            const prefix = normalizedOld + "/";\n            const descendants = this.#stmtDescendants.all(\n              prefix + "%",\n              normalizedOld\n            );\n            for (const desc of descendants) {\n              const suffix = desc.path.slice(normalizedOld.length);\n              const newDescPath = normalizedNew + suffix;\n              const newDescParent = this.#getParentPath(newDescPath);\n              const descName = this.#getBaseName(newDescPath);\n              this.#stmtDelete.run(desc.path);\n              this.#stmtInsert.run(\n                newDescPath,\n                newDescParent,\n                descName,\n                desc.type,\n                desc.content,\n                desc.target,\n                desc.mode,\n                desc.mtime,\n                desc.ctime,\n                desc.birthtime\n              );\n            }\n            this.#db.exec("COMMIT");\n          } catch (err) {\n            this.#db.exec("ROLLBACK");\n            throw err;\n          }\n        } else {\n          this.#stmtDelete.run(normalizedOld);\n          const now = Date.now();\n          this.#stmtDelete.run(normalizedNew);\n          this.#stmtInsert.run(\n            normalizedNew,\n            newParentPath,\n            newName,\n            row.type,\n            row.content,\n            row.target,\n            row.mode,\n            now,\n            row.ctime,\n            row.birthtime\n          );\n        }\n      }\n      async rename(oldPath, newPath) {\n        this.renameSync(oldPath, newPath);\n      }\n      readlinkSync(path, options) {\n        const normalized = this.#normalizePath(path);\n        const row = this.#getEntry(normalized, "readlink", false);\n        if (row.type !== TYPE_SYMLINK) {\n          throw createEINVAL("readlink", path);\n        }\n        return row.target;\n      }\n      async readlink(path, options) {\n        return this.readlinkSync(path, options);\n      }\n      symlinkSync(target, path, type) {\n        if (this.readonly) {\n          throw createEROFS("symlink", path);\n        }\n        const normalized = this.#normalizePath(path);\n        const existing = this.#lookupEntry(normalized, false);\n        if (existing.row) {\n          throw createEEXIST("symlink", path);\n        }\n        this.#ensureParent(normalized, true, "symlink");\n        const name = this.#getBaseName(normalized);\n        const parentPath = this.#getParentPath(normalized);\n        const now = Date.now();\n        this.#stmtInsert.run(normalized, parentPath, name, TYPE_SYMLINK, null, target, 511, now, now, now);\n      }\n      async symlink(target, path, type) {\n        this.symlinkSync(target, path, type);\n      }\n      realpathSync(path, options) {\n        const result = this.#lookupEntry(path, true, 0);\n        if (result.eloop) {\n          throw createELOOP("realpath", path);\n        }\n        if (!result.row) {\n          throw createENOENT("realpath", path);\n        }\n        return result.resolvedPath;\n      }\n      async realpath(path, options) {\n        return this.realpathSync(path, options);\n      }\n      // === WATCH OPERATIONS ===\n      watch(path, options) {\n        const normalized = this.#normalizePath(path);\n        return new VFSWatcher(this, normalized, options);\n      }\n      watchAsync(path, options) {\n        const normalized = this.#normalizePath(path);\n        return new VFSWatchAsyncIterable(this, normalized, options);\n      }\n      watchFile(path, options, listener) {\n        const normalized = this.#normalizePath(path);\n        let watcher = this.#statWatchers.get(normalized);\n        if (!watcher) {\n          watcher = new VFSStatWatcher(this, normalized, options);\n          this.#statWatchers.set(normalized, watcher);\n        }\n        if (listener) {\n          watcher.addListener(listener);\n        }\n        return watcher;\n      }\n      unwatchFile(path, listener) {\n        const normalized = this.#normalizePath(path);\n        const watcher = this.#statWatchers.get(normalized);\n        if (!watcher) {\n          return;\n        }\n        if (listener) {\n          watcher.removeListener(listener);\n        } else {\n          watcher.removeAllListeners("change");\n        }\n        if (watcher.hasNoListeners()) {\n          watcher.stop();\n          this.#statWatchers.delete(normalized);\n        }\n      }\n    };\n    module2.exports = {\n      SqliteProvider\n    };\n  }\n});\n\n// node_modules/@roberts_lando/vfs/index.js\nvar require_vfs = __commonJS({\n  "node_modules/@roberts_lando/vfs/index.js"(exports2, module2) {\n    "use strict";\n    var { VirtualFileSystem } = require_file_system();\n    var { VirtualProvider } = require_provider();\n    var { MemoryProvider } = require_memory();\n    var { RealFSProvider } = require_real();\n    function create(provider, options) {\n      if (provider != null && !(provider instanceof VirtualProvider) && typeof provider === "object") {\n        options = provider;\n        provider = void 0;\n      }\n      return new VirtualFileSystem(provider, options);\n    }\n    module2.exports = {\n      create,\n      VirtualFileSystem,\n      VirtualProvider,\n      MemoryProvider,\n      RealFSProvider\n    };\n    Object.defineProperty(module2.exports, "SqliteProvider", {\n      enumerable: true,\n      configurable: true,\n      get() {\n        const { SqliteProvider } = require_sqlite();\n        Object.defineProperty(module2.exports, "SqliteProvider", {\n          value: SqliteProvider,\n          enumerable: true,\n          configurable: true,\n          writable: true\n        });\n        return SqliteProvider;\n      }\n    });\n  }\n});\n\n// prelude/sea-vfs-setup.js\nvar require_sea_vfs_setup = __commonJS({\n  "prelude/sea-vfs-setup.js"(exports2, module2) {\n    "use strict";\n    var sea = require("node:sea");\n    var shared2 = require_bootstrap_shared();\n    var COMPRESS_NONE = shared2.COMPRESS_NONE;\n    var vfsModule;\n    try {\n      vfsModule = require("node:vfs");\n    } catch (_) {\n      try {\n        vfsModule = require_vfs();\n      } catch (e) {\n        throw new Error(\n          "pkg: VFS polyfill (@roberts_lando/vfs) is not available: " + e.message\n        );\n      }\n    }\n    var VirtualFileSystem = vfsModule.VirtualFileSystem;\n    var MemoryProvider = vfsModule.MemoryProvider;\n    var MAX_SYMLINK_DEPTH = 40;\n    var perf = {\n      enabled: !!process.env.DEBUG_PKG_PERF,\n      // Phase timers (high-resolution)\n      _timers: {},\n      // Cumulative counters\n      _counters: {},\n      // Cumulative durations (BigInt nanoseconds)\n      _durations: {},\n      /** Mark the start of a named phase. */\n      start: function(label) {\n        if (!this.enabled) return;\n        this._timers[label] = process.hrtime.bigint();\n      },\n      /** End a named phase and record its duration. */\n      end: function(label) {\n        if (!this.enabled || !this._timers[label]) return;\n        var ns = process.hrtime.bigint() - this._timers[label];\n        this._durations[label] = (this._durations[label] || 0n) + ns;\n      },\n      /** Increment a named counter by n (default 1). */\n      count: function(label, n) {\n        if (!this.enabled) return;\n        this._counters[label] = (this._counters[label] || 0) + (n !== void 0 ? n : 1);\n      },\n      /** Add nanoseconds to a cumulative duration counter. */\n      addNs: function(label, ns) {\n        if (!this.enabled) return;\n        this._durations[label] = (this._durations[label] || 0n) + ns;\n      },\n      /** Format milliseconds from a BigInt nanosecond duration. */\n      _ms: function(ns) {\n        return (Number(ns) / 1e6).toFixed(1) + "ms";\n      },\n      /**\n       * Finalize perf tracking: end the `module loading` phase, aggregate\n       * the `vfs setup total`, capture the file-cache-entries counter from\n       * the provider, and print the report.  Called by each bootstrap\n       * dispatcher at the appropriate point so the module-loading phase\n       * timing reflects actual entrypoint completion.\n       */\n      finalize: function() {\n        if (!this.enabled) return;\n        this.end("module loading");\n        this._durations["vfs setup total"] = (this._durations["manifest parse"] || 0n) + (this._durations["archive load"] || 0n) + (this._durations["directory tree init"] || 0n) + (this._durations["vfs mount + hooks"] || 0n);\n        if (this._provider) {\n          this._counters["file cache entries"] = this._provider.fileCacheSize;\n        }\n        this.report();\n      },\n      /** Print the final performance report. */\n      report: function() {\n        if (!this.enabled) return;\n        var self = this;\n        var P = "[pkg:perf] ";\n        var SEP = P + "\\u2500".repeat(30);\n        console.log("");\n        console.log(P + "phase                 time");\n        console.log(SEP);\n        var phaseOrder = [\n          "manifest parse",\n          "archive load",\n          "directory tree init",\n          "vfs mount + hooks",\n          "vfs setup total",\n          "module loading"\n        ];\n        phaseOrder.forEach(function(label) {\n          var d = self._durations[label];\n          if (d !== void 0) {\n            console.log(P + label.padEnd(22) + self._ms(d));\n          }\n        });\n        console.log(P);\n        console.log(P + "counter                  value");\n        console.log(SEP);\n        var counterOrder = [\n          "files loaded",\n          "file cache entries",\n          "statSync calls",\n          "existsSync calls",\n          "readdirSync calls"\n        ];\n        counterOrder.forEach(function(label) {\n          var v = self._counters[label];\n          var d = self._durations[label];\n          if (v !== void 0) {\n            console.log(P + label.padEnd(22) + String(v).padStart(8));\n          } else if (d !== void 0) {\n            console.log(P + label.padEnd(22) + self._ms(d).padStart(8));\n          } else {\n            console.log(P + label.padEnd(22) + String(0).padStart(8));\n          }\n        });\n        console.log("");\n      }\n    };\n    perf.start("manifest parse");\n    var manifest;\n    try {\n      manifest = JSON.parse(sea.getAsset("__pkg_manifest__", "utf8"));\n    } catch (e) {\n      throw new Error(\n        "pkg: Failed to load VFS manifest from SEA assets: " + e.message\n      );\n    }\n    perf.end("manifest parse");\n    function _stripTrailingSeps(p) {\n      var i = p.length;\n      while (i > 1 && p.charCodeAt(i - 1) === 47) i--;\n      return i === p.length ? p : p.slice(0, i);\n    }\n    var toManifestKey = process.platform === "win32" ? function(p) {\n      return _stripTrailingSeps(p.replace(/\\\\/g, "/"));\n    } : function(p) {\n      return _stripTrailingSeps(p);\n    };\n    function _enoent(syscall, filePath) {\n      var err = new Error(\n        "ENOENT: no such file or directory, " + syscall + " \'" + filePath + "\'"\n      );\n      err.code = "ENOENT";\n      err.errno = -2;\n      err.syscall = syscall;\n      err.path = filePath;\n      return err;\n    }\n    var _now = Date.now();\n    function _makeStats(meta) {\n      return {\n        dev: 0,\n        ino: 0,\n        nlink: 1,\n        uid: 0,\n        gid: 0,\n        rdev: 0,\n        blksize: 4096,\n        mode: meta.isDirectory ? 16877 : 33188,\n        size: meta.size || 0,\n        blocks: Math.ceil((meta.size || 0) / 512),\n        atimeMs: _now,\n        mtimeMs: _now,\n        ctimeMs: _now,\n        birthtimeMs: _now,\n        atime: new Date(_now),\n        mtime: new Date(_now),\n        ctime: new Date(_now),\n        birthtime: new Date(_now),\n        isFile: function() {\n          return meta.isFile;\n        },\n        isDirectory: function() {\n          return meta.isDirectory;\n        },\n        isSymbolicLink: function() {\n          return false;\n        },\n        isBlockDevice: function() {\n          return false;\n        },\n        isCharacterDevice: function() {\n          return false;\n        },\n        isFIFO: function() {\n          return false;\n        },\n        isSocket: function() {\n          return false;\n        }\n      };\n    }\n    var DIRENT_UNKNOWN = 0;\n    var DIRENT_FILE = 1;\n    var DIRENT_DIRECTORY = 2;\n    var DIRENT_SYMLINK = 3;\n    var SEADirent = class {\n      constructor(name, type, parentPath) {\n        this.name = name;\n        this.parentPath = parentPath;\n        this.path = parentPath;\n        this._type = type;\n      }\n      isFile() {\n        return this._type === DIRENT_FILE;\n      }\n      isDirectory() {\n        return this._type === DIRENT_DIRECTORY;\n      }\n      isSymbolicLink() {\n        return this._type === DIRENT_SYMLINK;\n      }\n      isBlockDevice() {\n        return false;\n      }\n      isCharacterDevice() {\n        return false;\n      }\n      isFIFO() {\n        return false;\n      }\n      isSocket() {\n        return false;\n      }\n    };\n    var SEAProvider = class extends MemoryProvider {\n      constructor(seaManifest) {\n        super();\n        this._manifest = seaManifest;\n        this._fileCache = /* @__PURE__ */ new Map();\n        this._compression = seaManifest.compression || COMPRESS_NONE;\n        this._decompress = shared2.pickDecompressorSync(this._compression);\n        perf.start("archive load");\n        try {\n          this._archive = Buffer.from(sea.getRawAsset("__pkg_archive__"));\n        } catch (e) {\n          throw new Error(\n            "pkg: Failed to load archive from SEA assets: " + e.message\n          );\n        }\n        perf.end("archive load");\n        perf.start("directory tree init");\n        for (var dir of Object.keys(seaManifest.directories)) {\n          super.mkdirSync(dir, { recursive: true });\n        }\n        perf.end("directory tree init");\n      }\n      _resolveSymlink(p) {\n        var symlinks = this._manifest.symlinks;\n        if (symlinks[p] === void 0) return p;\n        var original = p;\n        for (var i = 0; i < MAX_SYMLINK_DEPTH; i++) {\n          var target = symlinks[p];\n          if (!target) return p;\n          p = target;\n        }\n        var err = new Error(\n          "ELOOP: too many symbolic links encountered, \'" + original + "\'"\n        );\n        err.code = "ELOOP";\n        err.errno = -40;\n        err.syscall = "stat";\n        err.path = original;\n        throw err;\n      }\n      get fileCacheSize() {\n        return this._fileCache.size;\n      }\n      readFileSync(filePath, options) {\n        var p = this._resolveSymlink(toManifestKey(filePath));\n        var cached = this._decompress ? this._fileCache.get(p) : void 0;\n        var buf;\n        if (cached !== void 0) {\n          buf = cached;\n        } else {\n          var entry = this._manifest.offsets[p];\n          if (!entry) throw _enoent("open", filePath);\n          var off = entry[0];\n          var len = entry[1];\n          if (!Number.isInteger(off) || !Number.isInteger(len) || off < 0 || len < 0 || off + len > this._archive.length) {\n            throw new Error(\n              "pkg: corrupt SEA manifest \\u2014 entry [" + off + "," + len + "] out of bounds for archive of " + this._archive.length + " bytes (file: " + filePath + ")"\n            );\n          }\n          var slice = this._archive.subarray(off, off + len);\n          if (this._decompress) {\n            var meta = this._manifest.stats[p];\n            var maxOutputLength = meta && Number.isInteger(meta.size) && meta.size >= 0 ? meta.size : null;\n            if (maxOutputLength === null) {\n              throw new Error(\n                "pkg: corrupt SEA manifest \\u2014 missing or invalid stats.size for " + filePath\n              );\n            }\n            buf = this._decompress(slice, { maxOutputLength });\n            this._fileCache.set(p, buf);\n          } else {\n            buf = slice;\n          }\n          perf.count("files loaded");\n        }\n        var encoding = typeof options === "string" ? options : options && options.encoding;\n        if (encoding) return buf.toString(encoding);\n        var copy = Buffer.allocUnsafe(buf.length);\n        buf.copy(copy);\n        return copy;\n      }\n      readlinkSync(filePath) {\n        var p = toManifestKey(filePath);\n        var target = this._manifest.symlinks[p];\n        if (target) return target;\n        return super.readlinkSync(p);\n      }\n      statSync(filePath) {\n        perf.count("statSync calls");\n        var p = this._resolveSymlink(toManifestKey(filePath));\n        var meta = this._manifest.stats[p];\n        if (meta) {\n          return _makeStats(meta);\n        }\n        throw _enoent("stat", filePath);\n      }\n      /**\n       * Fast module resolution stat \u2014 returns 0 (file), 1 (directory), or -2\n       * (not found) directly from the manifest.  This is the hottest path during\n       * startup (~30K calls for large projects) so it must be as lean as possible.\n       */\n      internalModuleStat(filePath) {\n        var p = this._resolveSymlink(toManifestKey(filePath));\n        var meta = this._manifest.stats[p];\n        if (meta) {\n          return meta.isDirectory ? 1 : 0;\n        }\n        return -2;\n      }\n      readdirSync(dirPath, options) {\n        perf.count("readdirSync calls");\n        var p = this._resolveSymlink(toManifestKey(dirPath));\n        var entries = this._manifest.directories[p];\n        if (entries) {\n          if (!options || !options.withFileTypes) return entries.slice();\n          var manifest2 = this._manifest;\n          return entries.map(function(name) {\n            var childPath = p === "/" ? "/" + name : p + "/" + name;\n            var meta = manifest2.stats[childPath];\n            var type = manifest2.symlinks[childPath] !== void 0 ? DIRENT_SYMLINK : meta && meta.isDirectory ? DIRENT_DIRECTORY : meta && meta.isFile ? DIRENT_FILE : DIRENT_UNKNOWN;\n            return new SEADirent(name, type, p);\n          });\n        }\n        return super.readdirSync(p, options);\n      }\n      existsSync(filePath) {\n        perf.count("existsSync calls");\n        var p = this._resolveSymlink(toManifestKey(filePath));\n        return p in this._manifest.stats;\n      }\n    };\n    perf.start("vfs mount + hooks");\n    var provider = new SEAProvider(manifest);\n    perf._provider = provider;\n    var virtualFs = new VirtualFileSystem(provider);\n    var SNAPSHOT_PREFIX = "/snapshot";\n    if (process.platform === "win32") {\n      _winToVFS = function(p) {\n        if (typeof p !== "string" || p.startsWith("/")) return p;\n        if (/^[A-Za-z]:/.test(p)) p = p.slice(2);\n        return p.replace(/\\\\/g, "/");\n      };\n      _origShouldHandle = VirtualFileSystem.prototype.shouldHandle;\n      VirtualFileSystem.prototype.shouldHandle = function(inputPath) {\n        return _origShouldHandle.call(this, _winToVFS(inputPath));\n      };\n      _origResolvePath = VirtualFileSystem.prototype.resolvePath;\n      VirtualFileSystem.prototype.resolvePath = function(inputPath) {\n        return _origResolvePath.call(this, _winToVFS(inputPath));\n      };\n    }\n    var _winToVFS;\n    var _origShouldHandle;\n    var _origResolvePath;\n    virtualFs.mount(SNAPSHOT_PREFIX, { overlay: true });\n    perf.end("vfs mount + hooks");\n    function toPlatformPath(p) {\n      if (process.platform !== "win32") return p;\n      if (p.startsWith("/snapshot")) {\n        return "C:" + p.replace(/\\//g, "\\\\");\n      }\n      return p.replace(/\\//g, "\\\\");\n    }\n    var SNAPSHOT_PREFIXES_POSIX = [{ prefix: "/snapshot", sep: "/" }];\n    var SNAPSHOT_PREFIXES_WIN = [\n      { prefix: "V:\\\\snapshot", sep: "\\\\" },\n      { prefix: "V:/snapshot", sep: "/" },\n      { prefix: "C:\\\\snapshot", sep: "\\\\" },\n      { prefix: "C:/snapshot", sep: "/" }\n    ];\n    function insideSnapshot(f) {\n      if (typeof f !== "string") return false;\n      var prefixes = process.platform === "win32" ? SNAPSHOT_PREFIXES_POSIX.concat(SNAPSHOT_PREFIXES_WIN) : SNAPSHOT_PREFIXES_POSIX;\n      for (var i = 0; i < prefixes.length; i++) {\n        var p = prefixes[i].prefix;\n        if (f === p || f.startsWith(p + prefixes[i].sep)) return true;\n      }\n      return false;\n    }\n    module2.exports = {\n      manifest,\n      virtualFs,\n      provider,\n      perf,\n      SNAPSHOT_PREFIX,\n      insideSnapshot,\n      toPlatformPath\n    };\n  }\n});\n\n// prelude/sea-worker-entry.js\nvar vfs = require_sea_vfs_setup();\nvar shared = require_bootstrap_shared();\nshared.setupProcessPkg(\n  vfs.toPlatformPath(vfs.manifest.entrypoint),\n  vfs.manifest.entrypoint\n);\n';
+   }
+ });
+
+@@ -5560,7 +5602,6 @@ var require_sea_bootstrap_core = __commonJS({
      var insideSnapshot = vfs.insideSnapshot;
      var SNAPSHOT_PREFIX = vfs.SNAPSHOT_PREFIX;
      shared.patchDlopen(insideSnapshot);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index d3d7e1d00b..5e11b66d5e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -10,7 +10,7 @@ overrides:
 
 patchedDependencies:
   '@electron/osx-sign@1.3.3': 280e7b2816caf01423097d24e79107a66afeb563a348630ce9928ae8499a5861
-  '@yao-pkg/pkg@6.21.0': 28edd2180c36691c481522ef81f6f6614505f45e491aad542ac4663d4e6b3ff8
+  '@yao-pkg/pkg@6.21.0': 07f08c630d0d3886d81fd4600116d07e4871ddcd57f92cb22746b6d246cdc337
   node-pty@1.2.0-beta.15: b40ae545608897914bd25fb009c97eeac478c34e8a910298ddcb01b746534bb0
 
 importers:
@@ -82,7 +82,7 @@ importers:
         version: 4.1.8(vitest@4.1.8)
       '@yao-pkg/pkg':
         specifier: 6.21.0
-        version: 6.21.0(patch_hash=28edd2180c36691c481522ef81f6f6614505f45e491aad542ac4663d4e6b3ff8)(supports-color@9.4.0)
+        version: 6.21.0(patch_hash=07f08c630d0d3886d81fd4600116d07e4871ddcd57f92cb22746b6d246cdc337)(supports-color@9.4.0)
       '@yarnpkg/cli-dist':
         specifier: 4.17.1
         version: 4.17.1
@@ -375,8 +375,8 @@ importers:
         specifier: ^4.2.0
         version: 4.2.0
       node-addon-require-builtin:
-        specifier: ^0.1.4
-        version: 0.1.4
+        specifier: ^0.1.6
+        version: 0.1.6
     devDependencies:
       '@agentclientprotocol/sdk':
         specifier: 1.4.0
@@ -640,12 +640,12 @@ importers:
       '@deepseek-ai/dsh-pwsh-local':
         specifier: workspace:^
         version: link:../../packages/shell/pwsh-local
-      '@deepseek-ai/dsh-subprocess-local':
-        specifier: workspace:^
-        version: link:../../packages/subprocess/subprocess-local
       '@deepseek-ai/dsh-remote-mock':
         specifier: workspace:^
         version: link:../../packages/test-support/remote-mock
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../packages/subprocess/subprocess-local
       '@types/node':
         specifier: ^22.0.0
         version: 22.20.0
@@ -754,6 +754,12 @@ importers:
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../packages/subagent/subagent
+      '@deepseek-ai/dsh-subprocess':
+        specifier: workspace:^
+        version: link:../packages/subprocess/subprocess
+      '@deepseek-ai/dsh-terminal':
+        specifier: workspace:^
+        version: link:../packages/terminal/terminal
       '@deepseek-ai/dsh-token-meter':
         specifier: workspace:^
         version: link:../packages/llm/token-meter
@@ -763,6 +769,9 @@ importers:
       '@deepseek-ai/dsh-typert-protocol':
         specifier: workspace:^
         version: link:../packages/typert/protocol
+      '@xterm/headless':
+        specifier: ^6.0.0
+        version: 6.0.0
       playwright:
         specifier: ^1.49.0
         version: 1.61.1
@@ -1368,6 +1377,9 @@ importers:
       js-yaml:
         specifier: ^4.2.0
         version: 4.2.0
+      node-addon-require-builtin:
+        specifier: ^0.1.6
+        version: 0.1.6
       resolve.exports:
         specifier: ^2.0.3
         version: 2.0.3
@@ -3467,6 +3479,9 @@ importers:
       clsx:
         specifier: ^2.0.0
         version: 2.1.1
+      diff:
+        specifier: ^9.0.0
+        version: 9.0.0
       katex:
         specifier: ^0.16.47
         version: 0.16.47
@@ -4236,6 +4251,9 @@ importers:
       '@deepseek-ai/dsh-client-ui-slots':
         specifier: workspace:^
         version: link:../ui-slots
+      '@deepseek-ai/dsh-client-ui-theme':
+        specifier: workspace:^
+        version: link:../ui-theme
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
@@ -6142,6 +6160,9 @@ importers:
 
   packages/experimental/inspector:
     dependencies:
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:^
+        version: link:../../boot/app-boot
       '@deepseek-ai/dsh-brand':
         specifier: workspace:^
         version: link:../../util/brand
@@ -7872,6 +7893,9 @@ importers:
       '@deepseek-ai/dsh-agent-presets':
         specifier: workspace:^
         version: link:../../preset/agent-presets
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:^
+        version: link:../../boot/app-boot
       '@deepseek-ai/dsh-deepseek-llm-api-extensions':
         specifier: workspace:^
         version: link:../deepseek-llm-api-extensions
@@ -8185,6 +8209,9 @@ importers:
       '@deepseek-ai/dsh-agent-loop':
         specifier: workspace:^
         version: link:../../core/agent-loop
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:^
+        version: link:../../boot/app-boot
       '@deepseek-ai/dsh-atomic-write':
         specifier: workspace:^
         version: link:../../util/atomic-write
@@ -11241,6 +11268,9 @@ importers:
       '@deepseek-ai/cordis-plugin-loader':
         specifier: workspace:^
         version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:^
+        version: link:../../boot/app-boot
       '@deepseek-ai/dsh-typert-registry':
         specifier: workspace:^
         version: link:../registry
@@ -12069,6 +12099,9 @@ importers:
       '@deepseek-ai/dsh-session-title':
         specifier: workspace:^
         version: link:../../packages/session/session-title
+      '@deepseek-ai/dsh-session-title-llm':
+        specifier: workspace:^
+        version: link:../../packages/session/session-title-llm
       '@deepseek-ai/dsh-settings':
         specifier: workspace:^
         version: link:../../packages/settings/settings
@@ -12310,8 +12343,8 @@ importers:
         specifier: link:../cosmokit
         version: link:../cosmokit
       node-addon-require-builtin:
-        specifier: ^0.1.4
-        version: 0.1.4
+        specifier: ^0.1.6
+        version: 0.1.6
 
   vendor/logger-console:
     dependencies:
@@ -12351,6 +12384,9 @@ importers:
       '@braintree/sanitize-url':
         specifier: 7.1.2
         version: 7.1.2
+      '@panzoom/panzoom':
+        specifier: 4.6.2
+        version: 4.6.2
       cytoscape:
         specifier: 3.34.0
         version: 3.34.0
@@ -12375,6 +12411,9 @@ importers:
       vitepress-plugin-mermaid:
         specifier: ^2.0.17
         version: 2.0.17(mermaid@11.16.0)(vitepress@1.6.4(@algolia/client-search@5.55.2)(@types/node@25.9.3)(@types/react@18.3.31)(lightningcss@1.32.0)(postcss@8.5.15)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(search-insights@2.17.3)(typescript@6.0.3))
+      vue:
+        specifier: 3.5.39
+        version: 3.5.39(typescript@6.0.3)
 
 packages:
 
@@ -14389,6 +14428,9 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@panzoom/panzoom@4.6.2':
+    resolution: {integrity: sha512-Zn3B5/hwa6eYIPRSKX0xf2clv8nviTX8AnAU5kU/EugiTDhG41ya2wlBqYrZJYCWQROr/5XkWObZhIkepi89qw==}
+
   '@peculiar/asn1-schema@2.9.4':
     resolution: {integrity: sha512-GjzePcT9Iw8NzeOPf73iNS9xM+TBhd/FilAfP+RQGkTMQJTVWtytN3JHJACCjf/ABNau5S7mS3g+DcuxmRgYEg==}
     engines: {node: '>=14'}
@@ -17755,56 +17797,56 @@ packages:
   node-addon-api@7.1.1:
     resolution: {integrity: sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==}
 
-  node-addon-native-custom-loader@0.1.4:
-    resolution: {integrity: sha512-DreegO6EoC1JHWYBv3j8Miwp2Zl/CyBeNyoeyCbnEdjyYFEulR4Gcb3wj9fXF7KMDY0ZJ5MWwHcXP8GVNyScnA==}
+  node-addon-native-custom-loader@0.1.6:
+    resolution: {integrity: sha512-QaW7d8lTcGCXrpNVyFDtID3vrpa7vFdpcY9pql2/9FGFSe7tcSnhQOKZX+1aOWq+pB1d2ZwNnKAdQI5nD9wAXA==}
     engines: {node: '>=20'}
 
-  node-addon-require-builtin-darwin-arm64@0.1.4:
-    resolution: {integrity: sha512-pqiTPbqlDKRIo8YKoWMjuFge4kyHbsdYkAcGW5MAVcJSCyU0M1hhpiLdWlvX753XKL3xlGeuPmv2NqTNRV0/hw==}
+  node-addon-require-builtin-darwin-arm64@0.1.6:
+    resolution: {integrity: sha512-KpaAh0mDcIScoJs7gD/mjXREcENJ023/DgWW3GrlLXFVzCE6bK6wFrTFpNfnkxZZP8yWsEWOg1o5T+uQ7olgTQ==}
     engines: {node: '>=20'}
     cpu: [arm64]
     os: [darwin]
 
-  node-addon-require-builtin-darwin-x64@0.1.4:
-    resolution: {integrity: sha512-i9oThh+w6d+H79YQuc3d3MZCx4YZ6aMWlQ0HYMgOTWvSRzppXmksa/xPV8O20G1gjpq5do/9/hgImixj3XIcjQ==}
+  node-addon-require-builtin-darwin-x64@0.1.6:
+    resolution: {integrity: sha512-lh9o5rCvmkH8MZgBBmhyKzJRc1M1hJzgXLTFzB6iomRXNH9P1DKjN2nAJLmvGrdTij47Wcch1JVnlV5AG0cRCQ==}
     engines: {node: '>=20'}
     cpu: [x64]
     os: [darwin]
 
-  node-addon-require-builtin-linux-arm64-gnu@0.1.4:
-    resolution: {integrity: sha512-qbmYtkiIFp7h1ZvYYHH0MGFQbc03OyvplkeS90j+t3VMomkRc/YwZ140WzVM3eYJYZ7XHq+s1GL5ZdFQFPUXBQ==}
+  node-addon-require-builtin-linux-arm64-gnu@0.1.6:
+    resolution: {integrity: sha512-DrQA3aS1LBn4NgrewbZkzSAWdSSRPD/fYO5AkQfvriQ/TQD3E2adB012sZ5eac6p9TAcTjUIYhk395AYVxo4Zw==}
     engines: {node: '>=20'}
     cpu: [arm64]
     os: [linux]
     libc: [glibc]
 
-  node-addon-require-builtin-linux-x64-gnu@0.1.4:
-    resolution: {integrity: sha512-4jC617+yOrYYuKgNmN2KMD722G6BICpjEzAcmzA3j5tt+zmey5M/c/z9JxqdjnNmU9CQWseBaJu/fGdbHZXSOg==}
+  node-addon-require-builtin-linux-x64-gnu@0.1.6:
+    resolution: {integrity: sha512-8wCxrFlB2Ld5DhxIm2P+nNFnQ0wjzDE5sXF68EUhLH0X+z313B07TUQFMBKCOkyhZIIBh590dBmhHCuA43No2A==}
     engines: {node: '>=20'}
     cpu: [x64]
     os: [linux]
     libc: [glibc]
 
-  node-addon-require-builtin-win32-arm64-msvc@0.1.4:
-    resolution: {integrity: sha512-4TW96aPR108R3RxJbUNLXU6FLTZ7n8fWtSpPbPtvYWXa9cXojvCMdH4BvrHM6W2M+Iu42nqMxRyylP3PeTjOmA==}
+  node-addon-require-builtin-win32-arm64-msvc@0.1.6:
+    resolution: {integrity: sha512-NET6DiLnKrK2DHuO4NNN+zJz0CFas+RwpJlGY0d3A3A3tc5dJQqZXgw8DzLOn4cSTAQCaDq6+LbPyYX7jE2F3Q==}
     engines: {node: '>=20'}
     cpu: [arm64]
     os: [win32]
 
-  node-addon-require-builtin-win32-ia32-msvc@0.1.4:
-    resolution: {integrity: sha512-a3ZRkiMKaE7uRjI+H+Ic7dvhPIk0rW9mHV47IEiqJzoRZqnDp5JPjQfAnngu979HR59Ghy+mfexJ/kStBlP3eQ==}
+  node-addon-require-builtin-win32-ia32-msvc@0.1.6:
+    resolution: {integrity: sha512-oj4G51r81kJ3E2t5KknKhBNb8TmTWzc/t9x7jkBF9JeRd+1a0kr99mVJVYwJNxq9d3jpt7dgBdI8mxaomuXOEQ==}
     engines: {node: '>=20 <23'}
     cpu: [ia32]
     os: [win32]
 
-  node-addon-require-builtin-win32-x64-msvc@0.1.4:
-    resolution: {integrity: sha512-EGx7AcJKB7fNxo/YHV32JTUg1Hetbdnh6uPaqPhklhyRSMM13/7hZK1pTACqMS9dwnR3Lakxl9HKG9/eAoIyyg==}
+  node-addon-require-builtin-win32-x64-msvc@0.1.6:
+    resolution: {integrity: sha512-ZQ+6thVzQBOFamW7s3t2YqHsw99EEPBNH1uAjvCx4QfnjFJTsu6I/H3prpN8i6cSt6gjnQtArfWc2LXN2ufcJQ==}
     engines: {node: '>=20'}
     cpu: [x64]
     os: [win32]
 
-  node-addon-require-builtin@0.1.4:
-    resolution: {integrity: sha512-yuXz43GmtQyMrO75u2Z8KZAafMhnMH8RTOZBJWGDU9HoD2QxT6q4PF28iLNm/OS9BkS8MHwCKpgTk3d6qW584A==}
+  node-addon-require-builtin@0.1.6:
+    resolution: {integrity: sha512-P9ZGMDkloktirLJSggfpxsJ9jog5FItE1Omxpj50UBn3LhD6TS6/yx0jEBXsCGK3P9EtW1EpQVA1QL5gb11GaQ==}
     engines: {node: '>=20'}
 
   node-api-version@0.2.1:
@@ -21218,6 +21260,8 @@ snapshots:
   '@oxlint/binding-win32-x64-msvc@1.76.0':
     optional: true
 
+  '@panzoom/panzoom@4.6.2': {}
+
   '@peculiar/asn1-schema@2.9.4':
     dependencies:
       '@peculiar/utils': 2.0.3
@@ -22337,7 +22381,7 @@ snapshots:
       - bare-buffer
       - react-native-b4a
 
-  '@yao-pkg/pkg@6.21.0(patch_hash=28edd2180c36691c481522ef81f6f6614505f45e491aad542ac4663d4e6b3ff8)(supports-color@9.4.0)':
+  '@yao-pkg/pkg@6.21.0(patch_hash=07f08c630d0d3886d81fd4600116d07e4871ddcd57f92cb22746b6d246cdc337)(supports-color@9.4.0)':
     dependencies:
       '@babel/generator': 7.29.7
       '@babel/parser': 7.29.7
@@ -24911,54 +24955,54 @@ snapshots:
 
   node-addon-api@7.1.1: {}
 
-  node-addon-native-custom-loader@0.1.4: {}
+  node-addon-native-custom-loader@0.1.6: {}
 
-  node-addon-require-builtin-darwin-arm64@0.1.4:
+  node-addon-require-builtin-darwin-arm64@0.1.6:
     dependencies:
-      node-addon-native-custom-loader: 0.1.4
+      node-addon-native-custom-loader: 0.1.6
     optional: true
 
-  node-addon-require-builtin-darwin-x64@0.1.4:
+  node-addon-require-builtin-darwin-x64@0.1.6:
     dependencies:
-      node-addon-native-custom-loader: 0.1.4
+      node-addon-native-custom-loader: 0.1.6
     optional: true
 
-  node-addon-require-builtin-linux-arm64-gnu@0.1.4:
+  node-addon-require-builtin-linux-arm64-gnu@0.1.6:
     dependencies:
-      node-addon-native-custom-loader: 0.1.4
+      node-addon-native-custom-loader: 0.1.6
     optional: true
 
-  node-addon-require-builtin-linux-x64-gnu@0.1.4:
+  node-addon-require-builtin-linux-x64-gnu@0.1.6:
     dependencies:
-      node-addon-native-custom-loader: 0.1.4
+      node-addon-native-custom-loader: 0.1.6
     optional: true
 
-  node-addon-require-builtin-win32-arm64-msvc@0.1.4:
+  node-addon-require-builtin-win32-arm64-msvc@0.1.6:
     dependencies:
-      node-addon-native-custom-loader: 0.1.4
+      node-addon-native-custom-loader: 0.1.6
     optional: true
 
-  node-addon-require-builtin-win32-ia32-msvc@0.1.4:
+  node-addon-require-builtin-win32-ia32-msvc@0.1.6:
     dependencies:
-      node-addon-native-custom-loader: 0.1.4
+      node-addon-native-custom-loader: 0.1.6
     optional: true
 
-  node-addon-require-builtin-win32-x64-msvc@0.1.4:
+  node-addon-require-builtin-win32-x64-msvc@0.1.6:
     dependencies:
-      node-addon-native-custom-loader: 0.1.4
+      node-addon-native-custom-loader: 0.1.6
     optional: true
 
-  node-addon-require-builtin@0.1.4:
+  node-addon-require-builtin@0.1.6:
     dependencies:
-      node-addon-native-custom-loader: 0.1.4
+      node-addon-native-custom-loader: 0.1.6
     optionalDependencies:
-      node-addon-require-builtin-darwin-arm64: 0.1.4
-      node-addon-require-builtin-darwin-x64: 0.1.4
-      node-addon-require-builtin-linux-arm64-gnu: 0.1.4
-      node-addon-require-builtin-linux-x64-gnu: 0.1.4
-      node-addon-require-builtin-win32-arm64-msvc: 0.1.4
-      node-addon-require-builtin-win32-ia32-msvc: 0.1.4
-      node-addon-require-builtin-win32-x64-msvc: 0.1.4
+      node-addon-require-builtin-darwin-arm64: 0.1.6
+      node-addon-require-builtin-darwin-x64: 0.1.6
+      node-addon-require-builtin-linux-arm64-gnu: 0.1.6
+      node-addon-require-builtin-linux-x64-gnu: 0.1.6
+      node-addon-require-builtin-win32-arm64-msvc: 0.1.6
+      node-addon-require-builtin-win32-ia32-msvc: 0.1.6
+      node-addon-require-builtin-win32-x64-msvc: 0.1.6
 
   node-api-version@0.2.1:
     dependencies:
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 041439731b..03d829ec4f 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -55,15 +55,15 @@ minimumReleaseAgeExclude:
   # point of bumping it; waiting out the release age would defeat that.
   - '@earendil-works/pi-ai@0.85.1'
   - '@earendil-works/pi-telemetry@0.85.1'
-  - node-addon-native-custom-loader@0.1.4
-  - node-addon-require-builtin-darwin-arm64@0.1.4
-  - node-addon-require-builtin-darwin-x64@0.1.4
-  - node-addon-require-builtin-linux-arm64-gnu@0.1.4
-  - node-addon-require-builtin-linux-x64-gnu@0.1.4
-  - node-addon-require-builtin-win32-arm64-msvc@0.1.4
-  - node-addon-require-builtin-win32-ia32-msvc@0.1.4
-  - node-addon-require-builtin-win32-x64-msvc@0.1.4
-  - node-addon-require-builtin@0.1.4
+  - node-addon-native-custom-loader@0.1.6
+  - node-addon-require-builtin-darwin-arm64@0.1.6
+  - node-addon-require-builtin-darwin-x64@0.1.6
+  - node-addon-require-builtin-linux-arm64-gnu@0.1.6
+  - node-addon-require-builtin-linux-x64-gnu@0.1.6
+  - node-addon-require-builtin-win32-arm64-msvc@0.1.6
+  - node-addon-require-builtin-win32-ia32-msvc@0.1.6
+  - node-addon-require-builtin-win32-x64-msvc@0.1.6
+  - node-addon-require-builtin@0.1.6
   # The active pnpm supply-chain policy blocks this reviewed runtime closure
   # until its release-age window expires unless every exact package is exempt.
   - '@anthropic-ai/claude-agent-sdk-darwin-arm64@0.3.263'
@@ -86,7 +86,6 @@ minimumReleaseAgeExclude:
   - '@trycua/cua-driver-win32-arm64-msvc@0.28.0'
   - '@trycua/cua-driver-win32-x64-msvc@0.28.0'
   - '@trycua/cua-driver@0.28.0'
-
 patchedDependencies:
   '@electron/osx-sign@1.3.3': patches/@electron__osx-sign@1.3.3.patch
   '@yao-pkg/pkg@6.21.0': patches/@yao-pkg__pkg@6.21.0.patch
diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json
index 0307f96e86..e975b3e2c9 100644
--- a/python/sdk-runtime/package.json
+++ b/python/sdk-runtime/package.json
@@ -80,6 +80,7 @@
     "@deepseek-ai/dsh-session-reference": "workspace:^",
     "@deepseek-ai/dsh-session-telemetry": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-session-title-llm": "workspace:^",
     "@deepseek-ai/dsh-settings": "workspace:^",
     "@deepseek-ai/dsh-shell": "workspace:^",
     "@deepseek-ai/dsh-shell-env": "workspace:^",
diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts
index c4b9fd6789..b73febb124 100644
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -147,6 +147,8 @@ function workspaceManifests(): WorkspaceManifest[] {
 }
 
 const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
+  // Owned Worker bundles import this public bootstrap before their business entry.
+  '@deepseek-ai/dsh-app-boot': ['lib/worker/profile-resolution-bootstrap.js'],
   // Statically linked client libraries keep their stylesheets next to the emitted
   // JavaScript, which imports them by relative path: the compile shell runs
   // them through its own CSS pipeline, so the sheets are published artifacts.
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 973ddc9a2a..0adbfa8145 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -159,6 +159,7 @@ export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
   launcherSessionQueryPath: 'not a service: launcher-provided boot-context value (string | undefined) — packages/session-query/session-query-sqlite/README.md owns this launcher contract',
   dshHomePath: 'not a service: boot-provided root accessor function (typeof dshHomePath | undefined) for Loader !!js config expressions — packages/boot/app-boot/README.md owns the boot contract',
   launchEnvironment: 'not a service: launcher-provided root accessor value (LaunchEnvironmentSnapshot | undefined) — packages/util/launch-environment/README.md owns this launcher contract',
+  pluginPackages: 'profile-boot-owned package resolver service used by optional consumers — packages/boot/app-boot/README.md owns this internal API',
   connection: 'interface-typed (HostConnectionHandle); implementing class HostConnectionService is declared in rpc-host.ts — packages/client/connection/README.md owns the API',
   fileUpload: 'client-side browser upload service — packages/client/file-upload/README.md owns the API',
   uiRenderer: 'client-side interface-typed browser service — packages/client/ui-renderer/README.md owns the API',
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index a8c0b4e027..367a5bd67d 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -386,6 +386,13 @@ function nodeCompatSmokeGates(options: { cliSmoke?: boolean } = {}): Gate[] {
       'run',
       'scripts/vitest-environment.compat.spec.ts',
     ], { label: 'Vitest jsdom smoke' }),
+    pnpmExec('profile-resolution-smoke', [
+      'vitest',
+      'run',
+      'packages/boot/app-boot/tests/profile-resolution.spec.ts',
+      'packages/boot/app-boot/tests/profile-resolution-service.spec.ts',
+      'packages/boot/app-boot/tests/profile-resolution-worker-bootstrap.spec.ts',
+    ], { label: 'profile resolution smoke' }),
   ]
   if (options.cliSmoke) {
     gates.push(
@@ -769,7 +776,10 @@ function docSyncLeafGates(options: {
       label: 'documentation standard tests',
       quick: true,
     }),
-    pnpmExec('docs-site-projection', ['vitest', 'run', 'scripts/project-doc-site.spec.ts', 'scripts/verify-doc-site-fragments.spec.ts'], {
+    pnpmExec('docs-site-projection', [
+      'vitest', 'run', 'scripts/project-doc-site.spec.ts', 'scripts/verify-doc-site-fragments.spec.ts',
+      'website/tests/mermaid-viewer.spec.ts',
+    ], {
       label: 'documentation site checks',
     }),
     pnpmScript('package-readme-limitations', 'verify-package-readme-limitations', { label: 'package README limitations', quick: true }),
diff --git a/snapshots/acp/escalation-approved/cordis.yml b/snapshots/acp/escalation-approved/cordis.yml
index 85fca86823..07aa7f1760 100644
--- a/snapshots/acp/escalation-approved/cordis.yml
+++ b/snapshots/acp/escalation-approved/cordis.yml
@@ -88,3 +88,7 @@
       name: '@deepseek-ai/dsh-hooks-codex'
       config:
         configPath: ./codex-hooks.json
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/snapshots/sdk/bash-tool/cordis.snapshot.yml b/snapshots/sdk/bash-tool/cordis.snapshot.yml
index 64b6112404..ed8a7c245d 100644
--- a/snapshots/sdk/bash-tool/cordis.snapshot.yml
+++ b/snapshots/sdk/bash-tool/cordis.snapshot.yml
@@ -13,3 +13,7 @@
             name: DeepSeek
             models:
               - id: deepseek-v4-flash
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/snapshots/sdk/bash-tool/cordis.yml b/snapshots/sdk/bash-tool/cordis.yml
index 2ebc9c14c3..20cade7db1 100644
--- a/snapshots/sdk/bash-tool/cordis.yml
+++ b/snapshots/sdk/bash-tool/cordis.yml
@@ -25,3 +25,7 @@
     backgroundMode: one-shot
     enableRunInBackground: false
     maxDepth: 1
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/snapshots/sdk/persistent-tools/cordis.snapshot.yml b/snapshots/sdk/persistent-tools/cordis.snapshot.yml
index 0579e3881d..2578e9565a 100644
--- a/snapshots/sdk/persistent-tools/cordis.snapshot.yml
+++ b/snapshots/sdk/persistent-tools/cordis.snapshot.yml
@@ -13,3 +13,7 @@
             name: DeepSeek
             models:
               - id: deepseek-v4-flash
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/snapshots/sdk/persistent-tools/cordis.yml b/snapshots/sdk/persistent-tools/cordis.yml
index 78a1579766..a8b572904f 100644
--- a/snapshots/sdk/persistent-tools/cordis.yml
+++ b/snapshots/sdk/persistent-tools/cordis.yml
@@ -162,3 +162,7 @@
           * To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.
           * Please avoid commands that may produce a very large amount of output.
           * Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/snapshots/sdk/sdk.snapshot.ts b/snapshots/sdk/sdk.snapshot.ts
index a4580498d3..159dc328fb 100644
--- a/snapshots/sdk/sdk.snapshot.ts
+++ b/snapshots/sdk/sdk.snapshot.ts
@@ -543,12 +543,12 @@ async function runScenario(scenario: CorpusScenario): Promise<{
   await mkdir(patchRoot, { recursive: true })
   const assertions = SDK_ASSERTIONS[scenario.name] ?? {}
   const patches = [...authoredPatches(scenario, !recording), ...assertions.patches ?? []]
-    .map((patch, index) => materializeProfilePatch(patch, cwd, patchRoot, index))
+    .map((patch, index) => materializeProfilePatch(patch, cwd, 'sdk', patchRoot, index))
   let childSessionsRoot: string | undefined
   let childEnvironment: Record<string, string> = {}
   if (assertions.dshSdkChild !== undefined) {
     const childHome = join(cwd, '.child-dsh')
-    const childPatch = materializeProfilePatch(assertions.dshSdkChild.config, cwd, patchRoot, patches.length)
+    const childPatch = materializeProfilePatch(assertions.dshSdkChild.config, cwd, 'sdk', patchRoot, patches.length)
     await mkdir(childHome, { recursive: true })
     childSessionsRoot = join(childHome, 'sessions')
     childEnvironment = {
diff --git a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/cordis.snapshot.yml b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/cordis.snapshot.yml
index e2dbe842b0..1ed42a1a29 100644
--- a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/cordis.snapshot.yml
+++ b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/cordis.snapshot.yml
@@ -20,3 +20,7 @@
       inject: [sdkAppStartup, loader]
       config:
         maxTokensAsSuccess: true
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/cordis.yml b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/cordis.yml
index 4b6e415081..a58d08433d 100644
--- a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/cordis.yml
+++ b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/cordis.yml
@@ -59,3 +59,7 @@
       disabled: !!js process.env.DSH_SNAPSHOT !== 'record'
       config:
         maxTokensAsSuccess: true
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/snapshots/sdk/text-turn/cordis.snapshot.yml b/snapshots/sdk/text-turn/cordis.snapshot.yml
index c5741704cc..5cda6a0976 100644
--- a/snapshots/sdk/text-turn/cordis.snapshot.yml
+++ b/snapshots/sdk/text-turn/cordis.snapshot.yml
@@ -13,8 +13,3 @@
             name: DeepSeek
             models:
               - id: deepseek-v4-flash
-
-- id: session-log-deepseek
-  name: '@deepseek-ai/dsh-session-log-deepseek'
-  config:
-    enabled: true
diff --git a/snapshots/sdk/text-turn/cordis.yml b/snapshots/sdk/text-turn/cordis.yml
index d3111e59ad..c40d286c07 100644
--- a/snapshots/sdk/text-turn/cordis.yml
+++ b/snapshots/sdk/text-turn/cordis.yml
@@ -28,11 +28,6 @@
     enableRunInBackground: false
     maxDepth: 1
 
-- id: session-log-deepseek
-  name: '@deepseek-ai/dsh-session-log-deepseek'
-  config:
-    enabled: true
-
 - insert:
     - id: snapshot-message-feedback
       name: '@deepseek-ai/dsh-message-feedback'
diff --git a/snapshots/session/headless.snapshot.ts b/snapshots/session/headless.snapshot.ts
index 6fcd4e0081..f072ebc1fa 100644
--- a/snapshots/session/headless.snapshot.ts
+++ b/snapshots/session/headless.snapshot.ts
@@ -1085,7 +1085,7 @@ describe('headless recorded-session snapshots', () => {
             await mkdir(join(cwd, patchRoot), { recursive: true })
             patchSources.forEach((source, index) => {
               if (source.endsWith('.snapshot.yml')) {
-                materializeProfilePatch(source, cwd, join(cwd, patchRoot), index)
+                materializeProfilePatch(source, cwd, 'headless', join(cwd, patchRoot), index)
               }
             })
             await seedWorkspace(scenario, cwd)
diff --git a/snapshots/session/text-turn/cordis.yml b/snapshots/session/text-turn/cordis.yml
index e98b2f8b1b..01637104ad 100644
--- a/snapshots/session/text-turn/cordis.yml
+++ b/snapshots/session/text-turn/cordis.yml
@@ -78,3 +78,7 @@
       name: '@deepseek-ai/dsh-hooks-codex'
       config:
         configPath: ./codex-hooks.json
+
+- id: session-log-deepseek
+  config:
+    enabled: false
diff --git a/snapshots/web/diff-bounded/session.v3.jsonl b/snapshots/web/diff-bounded/session.v3.jsonl
new file mode 100644
index 0000000000..8a2e69ac74
--- /dev/null
+++ b/snapshots/web/diff-bounded/session.v3.jsonl
@@ -0,0 +1,27 @@
+{"type":"session","version":3,"id":"{{session:1}}","createdAt":1783352084735,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0}
+{"type":"permission/preset","data":{"preset":"danger-full-access"}}
+{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
+{"type":"approval/policy","data":{"policy":"never"}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Read large.txt, replace all 129 old settings with the corresponding new settings, preserve the shared heading, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
+{"type":"turn/start","data":{"turn":1}}
+{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","data":{"turn":1,"step":1}}
+{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Read large.txt, replace all 129 old settings with the corresponding new settings, preserve the shared heading, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
+{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
+{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"session/title","data":{"title":"Bounded diff example","messageSeqs":[8],"source":{"kind":"fallback"}}}
+{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"fs-edit-read","name":"read","arguments":"{\"file_path\":\"large.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788699361025,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788699361025,"index":0,"dt":[],"id":"fs-edit-read","name":"read","args":["{\"file_path\":\"large.txt\"}"]},{"type":"chunk","time":1788699361025,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"fs-edit-read","name":"read","arguments":"{\"file_path\":\"large.txt\"}"}}},{"type":"chunk","time":1788699361025,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788699361025,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":1,"callId":"fs-edit-read","name":"read","arguments":"{\"file_path\":\"large.txt\"}"}}
+{"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"fs-edit-read"},"content":[{"type":"tool-result","toolCallId":"fs-edit-read","content":[{"type":"text","text":"<path>{{cwd}}/large.txt</path>\n<type>file</type>\n<content>\n1: shared heading\n2: old setting 0\n3: old setting 1\n4: old setting 2\n5: old setting 3\n6: old setting 4\n7: old setting 5\n8: old setting 6\n9: old setting 7\n10: old setting 8\n11: old setting 9\n12: old setting 10\n13: old setting 11\n14: old setting 12\n15: old setting 13\n16: old setting 14\n17: old setting 15\n18: old setting 16\n19: old setting 17\n20: old setting 18\n21: old setting 19\n22: old setting 20\n23: old setting 21\n24: old setting 22\n25: old setting 23\n26: old setting 24\n27: old setting 25\n28: old setting 26\n29: old setting 27\n30: old setting 28\n31: old setting 29\n32: old setting 30\n33: old setting 31\n34: old setting 32\n35: old setting 33\n36: old setting 34\n37: old setting 35\n38: old setting 36\n39: old setting 37\n40: old setting 38\n41: old setting 39\n42: old setting 40\n43: old setting 41\n44: old setting 42\n45: old setting 43\n46: old setting 44\n47: old setting 45\n48: old setting 46\n49: old setting 47\n50: old setting 48\n51: old setting 49\n52: old setting 50\n53: old setting 51\n54: old setting 52\n55: old setting 53\n56: old setting 54\n57: old setting 55\n58: old setting 56\n59: old setting 57\n60: old setting 58\n61: old setting 59\n62: old setting 60\n63: old setting 61\n64: old setting 62\n65: old setting 63\n66: old setting 64\n67: old setting 65\n68: old setting 66\n69: old setting 67\n70: old setting 68\n71: old setting 69\n72: old setting 70\n73: old setting 71\n74: old setting 72\n75: old setting 73\n76: old setting 74\n77: old setting 75\n78: old setting 76\n79: old setting 77\n80: old setting 78\n81: old setting 79\n82: old setting 80\n83: old setting 81\n84: old setting 82\n85: old setting 83\n86: old setting 84\n87: old setting 85\n88: old setting 86\n89: old setting 87\n90: old setting 88\n91: old setting 89\n92: old setting 90\n93: old setting 91\n94: old setting 92\n95: old setting 93\n96: old setting 94\n97: old setting 95\n98: old setting 96\n99: old setting 97\n100: old setting 98\n101: old setting 99\n102: old setting 100\n103: old setting 101\n104: old setting 102\n105: old setting 103\n106: old setting 104\n107: old setting 105\n108: old setting 106\n109: old setting 107\n110: old setting 108\n111: old setting 109\n112: old setting 110\n113: old setting 111\n114: old setting 112\n115: old setting 113\n116: old setting 114\n117: old setting 115\n118: old setting 116\n119: old setting 117\n120: old setting 118\n121: old setting 119\n122: old setting 120\n123: old setting 121\n124: old setting 122\n125: old setting 123\n126: old setting 124\n127: old setting 125\n128: old setting 126\n129: old setting 127\n130: old setting 128\n\n(End of file - total 130 lines)\n</content>"}],"isError":false}],"role":"user","id":"{{message:5}}"},"meta":{"path":"{{cwd}}/large.txt","offset":1,"lines":[{"number":1,"text":"shared heading"},{"number":2,"text":"old setting 0"},{"number":3,"text":"old setting 1"},{"number":4,"text":"old setting 2"},{"number":5,"text":"old setting 3"},{"number":6,"text":"old setting 4"},{"number":7,"text":"old setting 5"},{"number":8,"text":"old setting 6"},{"number":9,"text":"old setting 7"},{"number":10,"text":"old setting 8"},{"number":11,"text":"old setting 9"},{"number":12,"text":"old setting 10"},{"number":13,"text":"old setting 11"},{"number":14,"text":"old setting 12"},{"number":15,"text":"old setting 13"},{"number":16,"text":"old setting 14"},{"number":17,"text":"old setting 15"},{"number":18,"text":"old setting 16"},{"number":19,"text":"old setting 17"},{"number":20,"text":"old setting 18"},{"number":21,"text":"old setting 19"},{"number":22,"text":"old setting 20"},{"number":23,"text":"old setting 21"},{"number":24,"text":"old setting 22"},{"number":25,"text":"old setting 23"},{"number":26,"text":"old setting 24"},{"number":27,"text":"old setting 25"},{"number":28,"text":"old setting 26"},{"number":29,"text":"old setting 27"},{"number":30,"text":"old setting 28"},{"number":31,"text":"old setting 29"},{"number":32,"text":"old setting 30"},{"number":33,"text":"old setting 31"},{"number":34,"text":"old setting 32"},{"number":35,"text":"old setting 33"},{"number":36,"text":"old setting 34"},{"number":37,"text":"old setting 35"},{"number":38,"text":"old setting 36"},{"number":39,"text":"old setting 37"},{"number":40,"text":"old setting 38"},{"number":41,"text":"old setting 39"},{"number":42,"text":"old setting 40"},{"number":43,"text":"old setting 41"},{"number":44,"text":"old setting 42"},{"number":45,"text":"old setting 43"},{"number":46,"text":"old setting 44"},{"number":47,"text":"old setting 45"},{"number":48,"text":"old setting 46"},{"number":49,"text":"old setting 47"},{"number":50,"text":"old setting 48"},{"number":51,"text":"old setting 49"},{"number":52,"text":"old setting 50"},{"number":53,"text":"old setting 51"},{"number":54,"text":"old setting 52"},{"number":55,"text":"old setting 53"},{"number":56,"text":"old setting 54"},{"number":57,"text":"old setting 55"},{"number":58,"text":"old setting 56"},{"number":59,"text":"old setting 57"},{"number":60,"text":"old setting 58"},{"number":61,"text":"old setting 59"},{"number":62,"text":"old setting 60"},{"number":63,"text":"old setting 61"},{"number":64,"text":"old setting 62"},{"number":65,"text":"old setting 63"},{"number":66,"text":"old setting 64"},{"number":67,"text":"old setting 65"},{"number":68,"text":"old setting 66"},{"number":69,"text":"old setting 67"},{"number":70,"text":"old setting 68"},{"number":71,"text":"old setting 69"},{"number":72,"text":"old setting 70"},{"number":73,"text":"old setting 71"},{"number":74,"text":"old setting 72"},{"number":75,"text":"old setting 73"},{"number":76,"text":"old setting 74"},{"number":77,"text":"old setting 75"},{"number":78,"text":"old setting 76"},{"number":79,"text":"old setting 77"},{"number":80,"text":"old setting 78"},{"number":81,"text":"old setting 79"},{"number":82,"text":"old setting 80"},{"number":83,"text":"old setting 81"},{"number":84,"text":"old setting 82"},{"number":85,"text":"old setting 83"},{"number":86,"text":"old setting 84"},{"number":87,"text":"old setting 85"},{"number":88,"text":"old setting 86"},{"number":89,"text":"old setting 87"},{"number":90,"text":"old setting 88"},{"number":91,"text":"old setting 89"},{"number":92,"text":"old setting 90"},{"number":93,"text":"old setting 91"},{"number":94,"text":"old setting 92"},{"number":95,"text":"old setting 93"},{"number":96,"text":"old setting 94"},{"number":97,"text":"old setting 95"},{"number":98,"text":"old setting 96"},{"number":99,"text":"old setting 97"},{"number":100,"text":"old setting 98"},{"number":101,"text":"old setting 99"},{"number":102,"text":"old setting 100"},{"number":103,"text":"old setting 101"},{"number":104,"text":"old setting 102"},{"number":105,"text":"old setting 103"},{"number":106,"text":"old setting 104"},{"number":107,"text":"old setting 105"},{"number":108,"text":"old setting 106"},{"number":109,"text":"old setting 107"},{"number":110,"text":"old setting 108"},{"number":111,"text":"old setting 109"},{"number":112,"text":"old setting 110"},{"number":113,"text":"old setting 111"},{"number":114,"text":"old setting 112"},{"number":115,"text":"old setting 113"},{"number":116,"text":"old setting 114"},{"number":117,"text":"old setting 115"},{"number":118,"text":"old setting 116"},{"number":119,"text":"old setting 117"},{"number":120,"text":"old setting 118"},{"number":121,"text":"old setting 119"},{"number":122,"text":"old setting 120"},{"number":123,"text":"old setting 121"},{"number":124,"text":"old setting 122"},{"number":125,"text":"old setting 123"},{"number":126,"text":"old setting 124"},{"number":127,"text":"old setting 125"},{"number":128,"text":"old setting 126"},{"number":129,"text":"old setting 127"},{"number":130,"text":"old setting 128"}],"totalLines":130}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":1}}
+{"type":"step/start","data":{"turn":1,"step":2}}
+{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"fs-edit-replace","name":"edit","arguments":"{\"file_path\":\"large.txt\",\"old_string\":\"shared heading\\nold setting 0\\nold setting 1\\nold setting 2\\nold setting 3\\nold setting 4\\nold setting 5\\nold setting 6\\nold setting 7\\nold setting 8\\nold setting 9\\nold setting 10\\nold setting 11\\nold setting 12\\nold setting 13\\nold setting 14\\nold setting 15\\nold setting 16\\nold setting 17\\nold setting 18\\nold setting 19\\nold setting 20\\nold setting 21\\nold setting 22\\nold setting 23\\nold setting 24\\nold setting 25\\nold setting 26\\nold setting 27\\nold setting 28\\nold setting 29\\nold setting 30\\nold setting 31\\nold setting 32\\nold setting 33\\nold setting 34\\nold setting 35\\nold setting 36\\nold setting 37\\nold setting 38\\nold setting 39\\nold setting 40\\nold setting 41\\nold setting 42\\nold setting 43\\nold setting 44\\nold setting 45\\nold setting 46\\nold setting 47\\nold setting 48\\nold setting 49\\nold setting 50\\nold setting 51\\nold setting 52\\nold setting 53\\nold setting 54\\nold setting 55\\nold setting 56\\nold setting 57\\nold setting 58\\nold setting 59\\nold setting 60\\nold setting 61\\nold setting 62\\nold setting 63\\nold setting 64\\nold setting 65\\nold setting 66\\nold setting 67\\nold setting 68\\nold setting 69\\nold setting 70\\nold setting 71\\nold setting 72\\nold setting 73\\nold setting 74\\nold setting 75\\nold setting 76\\nold setting 77\\nold setting 78\\nold setting 79\\nold setting 80\\nold setting 81\\nold setting 82\\nold setting 83\\nold setting 84\\nold setting 85\\nold setting 86\\nold setting 87\\nold setting 88\\nold setting 89\\nold setting 90\\nold setting 91\\nold setting 92\\nold setting 93\\nold setting 94\\nold setting 95\\nold setting 96\\nold setting 97\\nold setting 98\\nold setting 99\\nold setting 100\\nold setting 101\\nold setting 102\\nold setting 103\\nold setting 104\\nold setting 105\\nold setting 106\\nold setting 107\\nold setting 108\\nold setting 109\\nold setting 110\\nold setting 111\\nold setting 112\\nold setting 113\\nold setting 114\\nold setting 115\\nold setting 116\\nold setting 117\\nold setting 118\\nold setting 119\\nold setting 120\\nold setting 121\\nold setting 122\\nold setting 123\\nold setting 124\\nold setting 125\\nold setting 126\\nold setting 127\\nold setting 128\",\"new_string\":\"shared heading\\nnew setting 0\\nnew setting 1\\nnew setting 2\\nnew setting 3\\nnew setting 4\\nnew setting 5\\nnew setting 6\\nnew setting 7\\nnew setting 8\\nnew setting 9\\nnew setting 10\\nnew setting 11\\nnew setting 12\\nnew setting 13\\nnew setting 14\\nnew setting 15\\nnew setting 16\\nnew setting 17\\nnew setting 18\\nnew setting 19\\nnew setting 20\\nnew setting 21\\nnew setting 22\\nnew setting 23\\nnew setting 24\\nnew setting 25\\nnew setting 26\\nnew setting 27\\nnew setting 28\\nnew setting 29\\nnew setting 30\\nnew setting 31\\nnew setting 32\\nnew setting 33\\nnew setting 34\\nnew setting 35\\nnew setting 36\\nnew setting 37\\nnew setting 38\\nnew setting 39\\nnew setting 40\\nnew setting 41\\nnew setting 42\\nnew setting 43\\nnew setting 44\\nnew setting 45\\nnew setting 46\\nnew setting 47\\nnew setting 48\\nnew setting 49\\nnew setting 50\\nnew setting 51\\nnew setting 52\\nnew setting 53\\nnew setting 54\\nnew setting 55\\nnew setting 56\\nnew setting 57\\nnew setting 58\\nnew setting 59\\nnew setting 60\\nnew setting 61\\nnew setting 62\\nnew setting 63\\nnew setting 64\\nnew setting 65\\nnew setting 66\\nnew setting 67\\nnew setting 68\\nnew setting 69\\nnew setting 70\\nnew setting 71\\nnew setting 72\\nnew setting 73\\nnew setting 74\\nnew setting 75\\nnew setting 76\\nnew setting 77\\nnew setting 78\\nnew setting 79\\nnew setting 80\\nnew setting 81\\nnew setting 82\\nnew setting 83\\nnew setting 84\\nnew setting 85\\nnew setting 86\\nnew setting 87\\nnew setting 88\\nnew setting 89\\nnew setting 90\\nnew setting 91\\nnew setting 92\\nnew setting 93\\nnew setting 94\\nnew setting 95\\nnew setting 96\\nnew setting 97\\nnew setting 98\\nnew setting 99\\nnew setting 100\\nnew setting 101\\nnew setting 102\\nnew setting 103\\nnew setting 104\\nnew setting 105\\nnew setting 106\\nnew setting 107\\nnew setting 108\\nnew setting 109\\nnew setting 110\\nnew setting 111\\nnew setting 112\\nnew setting 113\\nnew setting 114\\nnew setting 115\\nnew setting 116\\nnew setting 117\\nnew setting 118\\nnew setting 119\\nnew setting 120\\nnew setting 121\\nnew setting 122\\nnew setting 123\\nnew setting 124\\nnew setting 125\\nnew setting 126\\nnew setting 127\\nnew setting 128\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:6}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1788699361045,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788699361045,"index":0,"dt":[],"id":"fs-edit-replace","name":"edit","args":["{\"file_path\":\"large.txt\",\"old_string\":\"shared heading\\nold setting 0\\nold setting 1\\nold setting 2\\nold setting 3\\nold setting 4\\nold setting 5\\nold setting 6\\nold setting 7\\nold setting 8\\nold setting 9\\nold setting 10\\nold setting 11\\nold setting 12\\nold setting 13\\nold setting 14\\nold setting 15\\nold setting 16\\nold setting 17\\nold setting 18\\nold setting 19\\nold setting 20\\nold setting 21\\nold setting 22\\nold setting 23\\nold setting 24\\nold setting 25\\nold setting 26\\nold setting 27\\nold setting 28\\nold setting 29\\nold setting 30\\nold setting 31\\nold setting 32\\nold setting 33\\nold setting 34\\nold setting 35\\nold setting 36\\nold setting 37\\nold setting 38\\nold setting 39\\nold setting 40\\nold setting 41\\nold setting 42\\nold setting 43\\nold setting 44\\nold setting 45\\nold setting 46\\nold setting 47\\nold setting 48\\nold setting 49\\nold setting 50\\nold setting 51\\nold setting 52\\nold setting 53\\nold setting 54\\nold setting 55\\nold setting 56\\nold setting 57\\nold setting 58\\nold setting 59\\nold setting 60\\nold setting 61\\nold setting 62\\nold setting 63\\nold setting 64\\nold setting 65\\nold setting 66\\nold setting 67\\nold setting 68\\nold setting 69\\nold setting 70\\nold setting 71\\nold setting 72\\nold setting 73\\nold setting 74\\nold setting 75\\nold setting 76\\nold setting 77\\nold setting 78\\nold setting 79\\nold setting 80\\nold setting 81\\nold setting 82\\nold setting 83\\nold setting 84\\nold setting 85\\nold setting 86\\nold setting 87\\nold setting 88\\nold setting 89\\nold setting 90\\nold setting 91\\nold setting 92\\nold setting 93\\nold setting 94\\nold setting 95\\nold setting 96\\nold setting 97\\nold setting 98\\nold setting 99\\nold setting 100\\nold setting 101\\nold setting 102\\nold setting 103\\nold setting 104\\nold setting 105\\nold setting 106\\nold setting 107\\nold setting 108\\nold setting 109\\nold setting 110\\nold setting 111\\nold setting 112\\nold setting 113\\nold setting 114\\nold setting 115\\nold setting 116\\nold setting 117\\nold setting 118\\nold setting 119\\nold setting 120\\nold setting 121\\nold setting 122\\nold setting 123\\nold setting 124\\nold setting 125\\nold setting 126\\nold setting 127\\nold setting 128\",\"new_string\":\"shared heading\\nnew setting 0\\nnew setting 1\\nnew setting 2\\nnew setting 3\\nnew setting 4\\nnew setting 5\\nnew setting 6\\nnew setting 7\\nnew setting 8\\nnew setting 9\\nnew setting 10\\nnew setting 11\\nnew setting 12\\nnew setting 13\\nnew setting 14\\nnew setting 15\\nnew setting 16\\nnew setting 17\\nnew setting 18\\nnew setting 19\\nnew setting 20\\nnew setting 21\\nnew setting 22\\nnew setting 23\\nnew setting 24\\nnew setting 25\\nnew setting 26\\nnew setting 27\\nnew setting 28\\nnew setting 29\\nnew setting 30\\nnew setting 31\\nnew setting 32\\nnew setting 33\\nnew setting 34\\nnew setting 35\\nnew setting 36\\nnew setting 37\\nnew setting 38\\nnew setting 39\\nnew setting 40\\nnew setting 41\\nnew setting 42\\nnew setting 43\\nnew setting 44\\nnew setting 45\\nnew setting 46\\nnew setting 47\\nnew setting 48\\nnew setting 49\\nnew setting 50\\nnew setting 51\\nnew setting 52\\nnew setting 53\\nnew setting 54\\nnew setting 55\\nnew setting 56\\nnew setting 57\\nnew setting 58\\nnew setting 59\\nnew setting 60\\nnew setting 61\\nnew setting 62\\nnew setting 63\\nnew setting 64\\nnew setting 65\\nnew setting 66\\nnew setting 67\\nnew setting 68\\nnew setting 69\\nnew setting 70\\nnew setting 71\\nnew setting 72\\nnew setting 73\\nnew setting 74\\nnew setting 75\\nnew setting 76\\nnew setting 77\\nnew setting 78\\nnew setting 79\\nnew setting 80\\nnew setting 81\\nnew setting 82\\nnew setting 83\\nnew setting 84\\nnew setting 85\\nnew setting 86\\nnew setting 87\\nnew setting 88\\nnew setting 89\\nnew setting 90\\nnew setting 91\\nnew setting 92\\nnew setting 93\\nnew setting 94\\nnew setting 95\\nnew setting 96\\nnew setting 97\\nnew setting 98\\nnew setting 99\\nnew setting 100\\nnew setting 101\\nnew setting 102\\nnew setting 103\\nnew setting 104\\nnew setting 105\\nnew setting 106\\nnew setting 107\\nnew setting 108\\nnew setting 109\\nnew setting 110\\nnew setting 111\\nnew setting 112\\nnew setting 113\\nnew setting 114\\nnew setting 115\\nnew setting 116\\nnew setting 117\\nnew setting 118\\nnew setting 119\\nnew setting 120\\nnew setting 121\\nnew setting 122\\nnew setting 123\\nnew setting 124\\nnew setting 125\\nnew setting 126\\nnew setting 127\\nnew setting 128\"}"]},{"type":"chunk","time":1788699361045,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"fs-edit-replace","name":"edit","arguments":"{\"file_path\":\"large.txt\",\"old_string\":\"shared heading\\nold setting 0\\nold setting 1\\nold setting 2\\nold setting 3\\nold setting 4\\nold setting 5\\nold setting 6\\nold setting 7\\nold setting 8\\nold setting 9\\nold setting 10\\nold setting 11\\nold setting 12\\nold setting 13\\nold setting 14\\nold setting 15\\nold setting 16\\nold setting 17\\nold setting 18\\nold setting 19\\nold setting 20\\nold setting 21\\nold setting 22\\nold setting 23\\nold setting 24\\nold setting 25\\nold setting 26\\nold setting 27\\nold setting 28\\nold setting 29\\nold setting 30\\nold setting 31\\nold setting 32\\nold setting 33\\nold setting 34\\nold setting 35\\nold setting 36\\nold setting 37\\nold setting 38\\nold setting 39\\nold setting 40\\nold setting 41\\nold setting 42\\nold setting 43\\nold setting 44\\nold setting 45\\nold setting 46\\nold setting 47\\nold setting 48\\nold setting 49\\nold setting 50\\nold setting 51\\nold setting 52\\nold setting 53\\nold setting 54\\nold setting 55\\nold setting 56\\nold setting 57\\nold setting 58\\nold setting 59\\nold setting 60\\nold setting 61\\nold setting 62\\nold setting 63\\nold setting 64\\nold setting 65\\nold setting 66\\nold setting 67\\nold setting 68\\nold setting 69\\nold setting 70\\nold setting 71\\nold setting 72\\nold setting 73\\nold setting 74\\nold setting 75\\nold setting 76\\nold setting 77\\nold setting 78\\nold setting 79\\nold setting 80\\nold setting 81\\nold setting 82\\nold setting 83\\nold setting 84\\nold setting 85\\nold setting 86\\nold setting 87\\nold setting 88\\nold setting 89\\nold setting 90\\nold setting 91\\nold setting 92\\nold setting 93\\nold setting 94\\nold setting 95\\nold setting 96\\nold setting 97\\nold setting 98\\nold setting 99\\nold setting 100\\nold setting 101\\nold setting 102\\nold setting 103\\nold setting 104\\nold setting 105\\nold setting 106\\nold setting 107\\nold setting 108\\nold setting 109\\nold setting 110\\nold setting 111\\nold setting 112\\nold setting 113\\nold setting 114\\nold setting 115\\nold setting 116\\nold setting 117\\nold setting 118\\nold setting 119\\nold setting 120\\nold setting 121\\nold setting 122\\nold setting 123\\nold setting 124\\nold setting 125\\nold setting 126\\nold setting 127\\nold setting 128\",\"new_string\":\"shared heading\\nnew setting 0\\nnew setting 1\\nnew setting 2\\nnew setting 3\\nnew setting 4\\nnew setting 5\\nnew setting 6\\nnew setting 7\\nnew setting 8\\nnew setting 9\\nnew setting 10\\nnew setting 11\\nnew setting 12\\nnew setting 13\\nnew setting 14\\nnew setting 15\\nnew setting 16\\nnew setting 17\\nnew setting 18\\nnew setting 19\\nnew setting 20\\nnew setting 21\\nnew setting 22\\nnew setting 23\\nnew setting 24\\nnew setting 25\\nnew setting 26\\nnew setting 27\\nnew setting 28\\nnew setting 29\\nnew setting 30\\nnew setting 31\\nnew setting 32\\nnew setting 33\\nnew setting 34\\nnew setting 35\\nnew setting 36\\nnew setting 37\\nnew setting 38\\nnew setting 39\\nnew setting 40\\nnew setting 41\\nnew setting 42\\nnew setting 43\\nnew setting 44\\nnew setting 45\\nnew setting 46\\nnew setting 47\\nnew setting 48\\nnew setting 49\\nnew setting 50\\nnew setting 51\\nnew setting 52\\nnew setting 53\\nnew setting 54\\nnew setting 55\\nnew setting 56\\nnew setting 57\\nnew setting 58\\nnew setting 59\\nnew setting 60\\nnew setting 61\\nnew setting 62\\nnew setting 63\\nnew setting 64\\nnew setting 65\\nnew setting 66\\nnew setting 67\\nnew setting 68\\nnew setting 69\\nnew setting 70\\nnew setting 71\\nnew setting 72\\nnew setting 73\\nnew setting 74\\nnew setting 75\\nnew setting 76\\nnew setting 77\\nnew setting 78\\nnew setting 79\\nnew setting 80\\nnew setting 81\\nnew setting 82\\nnew setting 83\\nnew setting 84\\nnew setting 85\\nnew setting 86\\nnew setting 87\\nnew setting 88\\nnew setting 89\\nnew setting 90\\nnew setting 91\\nnew setting 92\\nnew setting 93\\nnew setting 94\\nnew setting 95\\nnew setting 96\\nnew setting 97\\nnew setting 98\\nnew setting 99\\nnew setting 100\\nnew setting 101\\nnew setting 102\\nnew setting 103\\nnew setting 104\\nnew setting 105\\nnew setting 106\\nnew setting 107\\nnew setting 108\\nnew setting 109\\nnew setting 110\\nnew setting 111\\nnew setting 112\\nnew setting 113\\nnew setting 114\\nnew setting 115\\nnew setting 116\\nnew setting 117\\nnew setting 118\\nnew setting 119\\nnew setting 120\\nnew setting 121\\nnew setting 122\\nnew setting 123\\nnew setting 124\\nnew setting 125\\nnew setting 126\\nnew setting 127\\nnew setting 128\"}"}}},{"type":"chunk","time":1788699361045,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1788699361045,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
+{"type":"tool/call","data":{"turn":1,"step":2,"callId":"fs-edit-replace","name":"edit","arguments":"{\"file_path\":\"large.txt\",\"old_string\":\"shared heading\\nold setting 0\\nold setting 1\\nold setting 2\\nold setting 3\\nold setting 4\\nold setting 5\\nold setting 6\\nold setting 7\\nold setting 8\\nold setting 9\\nold setting 10\\nold setting 11\\nold setting 12\\nold setting 13\\nold setting 14\\nold setting 15\\nold setting 16\\nold setting 17\\nold setting 18\\nold setting 19\\nold setting 20\\nold setting 21\\nold setting 22\\nold setting 23\\nold setting 24\\nold setting 25\\nold setting 26\\nold setting 27\\nold setting 28\\nold setting 29\\nold setting 30\\nold setting 31\\nold setting 32\\nold setting 33\\nold setting 34\\nold setting 35\\nold setting 36\\nold setting 37\\nold setting 38\\nold setting 39\\nold setting 40\\nold setting 41\\nold setting 42\\nold setting 43\\nold setting 44\\nold setting 45\\nold setting 46\\nold setting 47\\nold setting 48\\nold setting 49\\nold setting 50\\nold setting 51\\nold setting 52\\nold setting 53\\nold setting 54\\nold setting 55\\nold setting 56\\nold setting 57\\nold setting 58\\nold setting 59\\nold setting 60\\nold setting 61\\nold setting 62\\nold setting 63\\nold setting 64\\nold setting 65\\nold setting 66\\nold setting 67\\nold setting 68\\nold setting 69\\nold setting 70\\nold setting 71\\nold setting 72\\nold setting 73\\nold setting 74\\nold setting 75\\nold setting 76\\nold setting 77\\nold setting 78\\nold setting 79\\nold setting 80\\nold setting 81\\nold setting 82\\nold setting 83\\nold setting 84\\nold setting 85\\nold setting 86\\nold setting 87\\nold setting 88\\nold setting 89\\nold setting 90\\nold setting 91\\nold setting 92\\nold setting 93\\nold setting 94\\nold setting 95\\nold setting 96\\nold setting 97\\nold setting 98\\nold setting 99\\nold setting 100\\nold setting 101\\nold setting 102\\nold setting 103\\nold setting 104\\nold setting 105\\nold setting 106\\nold setting 107\\nold setting 108\\nold setting 109\\nold setting 110\\nold setting 111\\nold setting 112\\nold setting 113\\nold setting 114\\nold setting 115\\nold setting 116\\nold setting 117\\nold setting 118\\nold setting 119\\nold setting 120\\nold setting 121\\nold setting 122\\nold setting 123\\nold setting 124\\nold setting 125\\nold setting 126\\nold setting 127\\nold setting 128\",\"new_string\":\"shared heading\\nnew setting 0\\nnew setting 1\\nnew setting 2\\nnew setting 3\\nnew setting 4\\nnew setting 5\\nnew setting 6\\nnew setting 7\\nnew setting 8\\nnew setting 9\\nnew setting 10\\nnew setting 11\\nnew setting 12\\nnew setting 13\\nnew setting 14\\nnew setting 15\\nnew setting 16\\nnew setting 17\\nnew setting 18\\nnew setting 19\\nnew setting 20\\nnew setting 21\\nnew setting 22\\nnew setting 23\\nnew setting 24\\nnew setting 25\\nnew setting 26\\nnew setting 27\\nnew setting 28\\nnew setting 29\\nnew setting 30\\nnew setting 31\\nnew setting 32\\nnew setting 33\\nnew setting 34\\nnew setting 35\\nnew setting 36\\nnew setting 37\\nnew setting 38\\nnew setting 39\\nnew setting 40\\nnew setting 41\\nnew setting 42\\nnew setting 43\\nnew setting 44\\nnew setting 45\\nnew setting 46\\nnew setting 47\\nnew setting 48\\nnew setting 49\\nnew setting 50\\nnew setting 51\\nnew setting 52\\nnew setting 53\\nnew setting 54\\nnew setting 55\\nnew setting 56\\nnew setting 57\\nnew setting 58\\nnew setting 59\\nnew setting 60\\nnew setting 61\\nnew setting 62\\nnew setting 63\\nnew setting 64\\nnew setting 65\\nnew setting 66\\nnew setting 67\\nnew setting 68\\nnew setting 69\\nnew setting 70\\nnew setting 71\\nnew setting 72\\nnew setting 73\\nnew setting 74\\nnew setting 75\\nnew setting 76\\nnew setting 77\\nnew setting 78\\nnew setting 79\\nnew setting 80\\nnew setting 81\\nnew setting 82\\nnew setting 83\\nnew setting 84\\nnew setting 85\\nnew setting 86\\nnew setting 87\\nnew setting 88\\nnew setting 89\\nnew setting 90\\nnew setting 91\\nnew setting 92\\nnew setting 93\\nnew setting 94\\nnew setting 95\\nnew setting 96\\nnew setting 97\\nnew setting 98\\nnew setting 99\\nnew setting 100\\nnew setting 101\\nnew setting 102\\nnew setting 103\\nnew setting 104\\nnew setting 105\\nnew setting 106\\nnew setting 107\\nnew setting 108\\nnew setting 109\\nnew setting 110\\nnew setting 111\\nnew setting 112\\nnew setting 113\\nnew setting 114\\nnew setting 115\\nnew setting 116\\nnew setting 117\\nnew setting 118\\nnew setting 119\\nnew setting 120\\nnew setting 121\\nnew setting 122\\nnew setting 123\\nnew setting 124\\nnew setting 125\\nnew setting 126\\nnew setting 127\\nnew setting 128\"}"}}
+{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"fs-edit-replace"},"content":[{"type":"tool-result","toolCallId":"fs-edit-replace","content":[{"type":"text","text":"The file {{cwd}}/large.txt has been updated successfully."}],"isError":false}],"role":"user","id":"{{message:7}}"},"meta":{"diffs":[{"path":"large.txt","oldText":"shared heading\nold setting 0\nold setting 1\nold setting 2\nold setting 3\nold setting 4\nold setting 5\nold setting 6\nold setting 7\nold setting 8\nold setting 9\nold setting 10\nold setting 11\nold setting 12\nold setting 13\nold setting 14\nold setting 15\nold setting 16\nold setting 17\nold setting 18\nold setting 19\nold setting 20\nold setting 21\nold setting 22\nold setting 23\nold setting 24\nold setting 25\nold setting 26\nold setting 27\nold setting 28\nold setting 29\nold setting 30\nold setting 31\nold setting 32\nold setting 33\nold setting 34\nold setting 35\nold setting 36\nold setting 37\nold setting 38\nold setting 39\nold setting 40\nold setting 41\nold setting 42\nold setting 43\nold setting 44\nold setting 45\nold setting 46\nold setting 47\nold setting 48\nold setting 49\nold setting 50\nold setting 51\nold setting 52\nold setting 53\nold setting 54\nold setting 55\nold setting 56\nold setting 57\nold setting 58\nold setting 59\nold setting 60\nold setting 61\nold setting 62\nold setting 63\nold setting 64\nold setting 65\nold setting 66\nold setting 67\nold setting 68\nold setting 69\nold setting 70\nold setting 71\nold setting 72\nold setting 73\nold setting 74\nold setting 75\nold setting 76\nold setting 77\nold setting 78\nold setting 79\nold setting 80\nold setting 81\nold setting 82\nold setting 83\nold setting 84\nold setting 85\nold setting 86\nold setting 87\nold setting 88\nold setting 89\nold setting 90\nold setting 91\nold setting 92\nold setting 93\nold setting 94\nold setting 95\nold setting 96\nold setting 97\nold setting 98\nold setting 99\nold setting 100\nold setting 101\nold setting 102\nold setting 103\nold setting 104\nold setting 105\nold setting 106\nold setting 107\nold setting 108\nold setting 109\nold setting 110\nold setting 111\nold setting 112\nold setting 113\nold setting 114\nold setting 115\nold setting 116\nold setting 117\nold setting 118\nold setting 119\nold setting 120\nold setting 121\nold setting 122\nold setting 123\nold setting 124\nold setting 125\nold setting 126\nold setting 127\nold setting 128","newText":"shared heading\nnew setting 0\nnew setting 1\nnew setting 2\nnew setting 3\nnew setting 4\nnew setting 5\nnew setting 6\nnew setting 7\nnew setting 8\nnew setting 9\nnew setting 10\nnew setting 11\nnew setting 12\nnew setting 13\nnew setting 14\nnew setting 15\nnew setting 16\nnew setting 17\nnew setting 18\nnew setting 19\nnew setting 20\nnew setting 21\nnew setting 22\nnew setting 23\nnew setting 24\nnew setting 25\nnew setting 26\nnew setting 27\nnew setting 28\nnew setting 29\nnew setting 30\nnew setting 31\nnew setting 32\nnew setting 33\nnew setting 34\nnew setting 35\nnew setting 36\nnew setting 37\nnew setting 38\nnew setting 39\nnew setting 40\nnew setting 41\nnew setting 42\nnew setting 43\nnew setting 44\nnew setting 45\nnew setting 46\nnew setting 47\nnew setting 48\nnew setting 49\nnew setting 50\nnew setting 51\nnew setting 52\nnew setting 53\nnew setting 54\nnew setting 55\nnew setting 56\nnew setting 57\nnew setting 58\nnew setting 59\nnew setting 60\nnew setting 61\nnew setting 62\nnew setting 63\nnew setting 64\nnew setting 65\nnew setting 66\nnew setting 67\nnew setting 68\nnew setting 69\nnew setting 70\nnew setting 71\nnew setting 72\nnew setting 73\nnew setting 74\nnew setting 75\nnew setting 76\nnew setting 77\nnew setting 78\nnew setting 79\nnew setting 80\nnew setting 81\nnew setting 82\nnew setting 83\nnew setting 84\nnew setting 85\nnew setting 86\nnew setting 87\nnew setting 88\nnew setting 89\nnew setting 90\nnew setting 91\nnew setting 92\nnew setting 93\nnew setting 94\nnew setting 95\nnew setting 96\nnew setting 97\nnew setting 98\nnew setting 99\nnew setting 100\nnew setting 101\nnew setting 102\nnew setting 103\nnew setting 104\nnew setting 105\nnew setting 106\nnew setting 107\nnew setting 108\nnew setting 109\nnew setting 110\nnew setting 111\nnew setting 112\nnew setting 113\nnew setting 114\nnew setting 115\nnew setting 116\nnew setting 117\nnew setting 118\nnew setting 119\nnew setting 120\nnew setting 121\nnew setting 122\nnew setting 123\nnew setting 124\nnew setting 125\nnew setting 126\nnew setting 127\nnew setting 128"}]}},"sourceEventSeqs":[19],"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":2}}
+{"type":"step/start","data":{"turn":1,"step":3}}
+{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:8}}"},"usage":{"inputTokens":10,"outputTokens":2},"stream":[{"type":"chunk","time":1788699361070,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1788699361070,"index":0,"dt":[],"texts":["DONE"]},{"type":"chunk","time":1788699361070,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}},{"type":"chunk","time":1788699361070,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}},{"type":"chunk","time":1788699361070,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
+{"type":"step/end","data":{"turn":1,"step":3}}
+{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/snapshots/web/diff-bounded/snapshot.yml b/snapshots/web/diff-bounded/snapshot.yml
new file mode 100644
index 0000000000..689475afa1
--- /dev/null
+++ b/snapshots/web/diff-bounded/snapshot.yml
@@ -0,0 +1,7 @@
+version: 1
+scenario: diff-bounded
+profile: web
+composition: default
+recording: authored
+header:
+  class: default
diff --git a/snapshots/web/diff-bounded/ui.expected.md b/snapshots/web/diff-bounded/ui.expected.md
new file mode 100644
index 0000000000..bc413d74a5
--- /dev/null
+++ b/snapshots/web/diff-bounded/ui.expected.md
@@ -0,0 +1,10 @@
+- button "Edit large.txt +130 -130" [expanded]:
+  - img
+  - text: Edit
+  - button "large.txt"
+  - text: +130 -130
+- button "Copy"
+- text: large.txt - shared heading - old setting 0 - old setting 1 - old setting 2
+- button "Expand 252 more diff lines": … 252 more lines
+- text: + new setting 125 + new setting 126 + new setting 127 + new setting 128 └ +130 -130 · 1 file
+- button "Inspect"
diff --git a/snapshots/web/diff-context/snapshot.yml b/snapshots/web/diff-context/snapshot.yml
new file mode 100644
index 0000000000..bbf913c8e1
--- /dev/null
+++ b/snapshots/web/diff-context/snapshot.yml
@@ -0,0 +1,9 @@
+version: 1
+scenario: diff-context
+profile: web
+composition: default
+recording: authored
+header:
+  class: default
+session:
+  source: ../../session/fs-edit/session.v3.jsonl
diff --git a/snapshots/web/diff-context/ui.expected.md b/snapshots/web/diff-context/ui.expected.md
new file mode 100644
index 0000000000..8f2068d63e
--- /dev/null
+++ b/snapshots/web/diff-context/ui.expected.md
@@ -0,0 +1,8 @@
+- button "Edit config.txt +1 -1" [expanded]:
+  - img
+  - text: Edit
+  - button "config.txt"
+  - text: +1 -1
+- button "Copy"
+- text: config.txt - mode=DEBUG + mode=RELEASE level=info └ +1 -1 · 1 file
+- button "Inspect"
diff --git a/snapshots/web/document-preview/document.expected.md b/snapshots/web/document-preview/document.expected.md
index ee31777a15..03286e76b8 100644
--- a/snapshots/web/document-preview/document.expected.md
+++ b/snapshots/web/document-preview/document.expected.md
@@ -27,7 +27,7 @@
 
 ## PDF
 
-- Viewer: PDF
+- Viewer menu hidden: true
 - Worker: dsh-pdf
 - Continuous pages: 2
 - Horizontal overflow: false
@@ -44,5 +44,10 @@
 
 ## Unknown suffix
 
-- Viewer: Plain text
+- Viewer menu hidden: true
 - Text: UNKNOWN_SUFFIX | Plain fallback.
+
+## Unviewable binary
+
+- State: unsupported
+- Line: Preview is not available for this file type yet.
diff --git a/snapshots/web/seeded-history/file-preview.expected.md b/snapshots/web/seeded-history/file-preview.expected.md
index 9cc9064145..d11b2479b2 100644
--- a/snapshots/web/seeded-history/file-preview.expected.md
+++ b/snapshots/web/seeded-history/file-preview.expected.md
@@ -1,5 +1,4 @@
 - text: {{cwd}}/a.txt
-- button "Open with": Plain text
 - button "Line wrap" [pressed]:
   - img
 - button "Read the file again":
diff --git a/snapshots/web/seeded-history/sticky-geometry.expected.md b/snapshots/web/seeded-history/sticky-geometry.expected.md
new file mode 100644
index 0000000000..9cc0c8709c
--- /dev/null
+++ b/snapshots/web/seeded-history/sticky-geometry.expected.md
@@ -0,0 +1,22 @@
+# Compaction marker sticky header (pinned over a code-block summary)
+
+## Collapsed
+
+- header is not sticky: true
+
+## Open, pinned at the scroll container top
+
+- header position is sticky: true
+- header pins to the top edge: true
+- header outranks the summary code-block banner: true
+- hover fill stays fully opaque: true
+
+## Scrolled so the summary code banner reaches its sticky offset
+
+- container is scrolled off its top: true
+- header's static position sits above the scrollport: true
+- header holds at the scrollport top: true
+- header owns the center point (toggle stays clickable): true
+- summary code banner holds below the header band: true
+- summary code banner stays clear of the header: true
+- banner Copy control owns its own center: true
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 31f3654b1c..13687a1a3e 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -10,6 +10,7 @@
   "include": [
     "apps/web/product-isolation.ts",
     "apps/web/tests/default-product-isolation.e2e.ts",
+    "apps/web/tests/diff-context.e2e.ts",
     "apps/web/tests/scaffold.ts",
     "apps/web/tests/auto-review-fixture.ts",
     "apps/web/tests/auto-review-denial.e2e.ts",
diff --git a/vendor/loader/package.json b/vendor/loader/package.json
index b738e05f26..c8ad7bcd98 100644
--- a/vendor/loader/package.json
+++ b/vendor/loader/package.json
@@ -31,7 +31,7 @@
   "license": "MIT",
   "peerDependencies": {
     "@deepseek-ai/cordis": "workspace:^",
-    "node-addon-require-builtin": "^0.1.4"
+    "node-addon-require-builtin": "^0.1.6"
   },
   "peerDependenciesMeta": {
     "node-addon-require-builtin": {
diff --git a/vitest.config.ts b/vitest.config.ts
index cd6752424c..6dcb040917 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -124,6 +124,7 @@ const testIncludes = [
   'packages/*/*/tests/**/*.spec.{ts,tsx}',
   'apps/*/tests/**/*.spec.ts',
   'scripts/**/*.spec.ts',
+  'website/tests/**/*.spec.ts',
 ]
 
 // The instrumented coverage gate sets this env; the exempt heavy suites then
diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts
index 07fc6bad92..b63ba59a2f 100644
--- a/website/.vitepress/config.ts
+++ b/website/.vitepress/config.ts
@@ -218,8 +218,7 @@ const wordmark = readFileSync(resolve(import.meta.dirname, '../public/wordmark.s
   .replace('<svg ', '<svg class="dsh-wordmark" ')
 
 /**
- * Styles the default theme does not provide, carried inline because the site
- * runs the stock theme with no theme directory of its own.
+ * Head-injected styles for the site identity and sidebar scrollbar.
  *
  * The navigation-bar lockup pairs with `siteTitle`. The scrollbar rules replace
  * the sidebar's platform bar, which reserves 15px of a 265px column and draws a
diff --git a/website/.vitepress/theme/css.d.ts b/website/.vitepress/theme/css.d.ts
new file mode 100644
index 0000000000..080be4b4e2
--- /dev/null
+++ b/website/.vitepress/theme/css.d.ts
@@ -0,0 +1,2 @@
+/** Documentation styles are loaded by Vite. */
+declare module '*.css'
diff --git a/website/.vitepress/theme/index.ts b/website/.vitepress/theme/index.ts
new file mode 100644
index 0000000000..10f67bbdca
--- /dev/null
+++ b/website/.vitepress/theme/index.ts
@@ -0,0 +1,29 @@
+/** Default documentation theme with a client-only Mermaid viewer. */
+import DefaultTheme from 'vitepress/theme'
+import { useData, useRoute, type Theme } from 'vitepress'
+import { defineComponent, h, onBeforeUnmount, onMounted, watch } from 'vue'
+import type { MermaidViewer } from './mermaid-viewer.ts'
+import './mermaid-viewer.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout: defineComponent({
+    name: 'DocsLayout',
+    setup() {
+      const { lang, isDark } = useData()
+      const route = useRoute()
+      let viewer: MermaidViewer | undefined
+      let disposed = false
+      onMounted(async () => {
+        const { installMermaidViewer } = await import('./mermaid-viewer.ts')
+        if (!disposed) viewer = installMermaidViewer(document, () => lang.value)
+      })
+      watch([() => route.path, lang, isDark], () => viewer?.refresh(), { flush: 'post' })
+      onBeforeUnmount(() => {
+        disposed = true
+        viewer?.dispose()
+      })
+      return () => h(DefaultTheme.Layout)
+    },
+  }),
+} satisfies Theme
diff --git a/website/.vitepress/theme/mermaid-viewer.css b/website/.vitepress/theme/mermaid-viewer.css
new file mode 100644
index 0000000000..e98be69ca9
--- /dev/null
+++ b/website/.vitepress/theme/mermaid-viewer.css
@@ -0,0 +1,142 @@
+.vp-doc .mermaid:has(.dsh-diagram-open) {
+  position: relative;
+  padding-top: 48px;
+}
+
+.vp-doc .dsh-diagram-open,
+.dsh-diagram-viewer button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 44px;
+  height: 44px;
+  padding: 0;
+  flex: none;
+  border: 0;
+  border-radius: 8px;
+  color: var(--vp-c-text-2);
+  background: var(--vp-c-bg);
+  cursor: pointer;
+}
+
+.vp-doc .dsh-diagram-open {
+  position: absolute;
+  top: 0;
+  right: 0;
+}
+
+.dsh-diagram-icon {
+  width: 20px;
+  height: 20px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.7;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.dsh-diagram-open:hover,
+.dsh-diagram-viewer button:hover,
+.dsh-diagram-viewer button[aria-expanded="true"] {
+  color: var(--vp-c-brand-1);
+  background: var(--vp-c-bg-soft);
+}
+
+.dsh-diagram-open:focus-visible,
+.dsh-diagram-viewer button:focus-visible {
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 2px;
+}
+
+.dsh-diagram-viewer {
+  position: fixed;
+  inset: 0;
+  width: 100%;
+  height: 100dvh;
+  max-width: none;
+  max-height: none;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  color: var(--vp-c-text-1);
+  background: var(--vp-c-bg);
+  box-sizing: border-box;
+}
+
+.dsh-diagram-title {
+  position: absolute;
+  top: 24px;
+  left: 24px;
+  max-width: calc(100% - 104px);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--vp-c-text-2);
+  font-size: 13px;
+}
+
+.dsh-diagram-close { position: absolute; top: 12px; right: 16px; }
+
+.dsh-diagram-toolbar {
+  position: absolute;
+  bottom: 20px;
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 4px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  background: var(--vp-c-bg);
+  box-shadow: 0 3px 12px #0000000a;
+}
+
+.dsh-diagram-scale {
+  min-width: 48px;
+  text-align: center;
+  color: var(--vp-c-text-2);
+  font-size: 13px;
+  font-variant-numeric: tabular-nums;
+}
+
+.dsh-diagram-toolbar .dsh-diagram-fit {
+  margin-left: 6px;
+  border-left: 1px solid var(--vp-c-divider);
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+}
+
+.dsh-diagram-help-toggle { position: absolute; bottom: 25px; right: 16px; }
+
+.dsh-diagram-help {
+  position: absolute;
+  right: 16px;
+  bottom: 80px;
+  max-width: min(360px, calc(100% - 32px));
+  margin: 0;
+  padding: 12px 16px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg);
+  box-shadow: 0 3px 12px #0000000a;
+  font-size: 13px;
+}
+
+.dsh-diagram-viewport {
+  position: absolute;
+  inset: 64px 16px 88px;
+  overflow: hidden;
+  overscroll-behavior: contain;
+}
+
+.dsh-diagram-paper { position: absolute; inset: 0; }
+
+@media (max-width: 600px) {
+  .dsh-diagram-title { top: 20px; left: 16px; }
+  .dsh-diagram-close { top: 8px; right: 8px; }
+  .dsh-diagram-viewport { inset: 56px 8px 80px; }
+  .dsh-diagram-toolbar { bottom: 12px; }
+  .dsh-diagram-help-toggle { right: 8px; bottom: 17px; }
+}
diff --git a/website/.vitepress/theme/mermaid-viewer.ts b/website/.vitepress/theme/mermaid-viewer.ts
new file mode 100644
index 0000000000..4a7b63ad98
--- /dev/null
+++ b/website/.vitepress/theme/mermaid-viewer.ts
@@ -0,0 +1,259 @@
+/** Full-viewport viewing of asynchronously rendered documentation diagrams. */
+import Panzoom from '@panzoom/panzoom'
+
+const messages = {
+  en: {
+    open: 'View diagram fullscreen', title: 'Diagram viewer',
+    zoomIn: 'Zoom in', zoomOut: 'Zoom out', fit: 'Fit view', close: 'Close', helpLabel: 'Viewer help',
+    help: 'Scroll or pinch to zoom · Drag or use arrow keys to pan · Esc to close',
+  },
+  zh: {
+    open: '全屏查看图表', title: '图表查看器',
+    zoomIn: '放大', zoomOut: '缩小', fit: '适应窗口', close: '关闭', helpLabel: '查看器帮助',
+    help: '滚轮或双指缩放 · 拖动或方向键平移 · Esc 关闭',
+  },
+} satisfies Record<string, Record<string, string>>
+
+const icons = {
+  open: 'M14 4h6v6M20 4l-7 7M10 20H4v-6M4 20l7-7',
+  zoomIn: 'M5 12h14M12 5v14', zoomOut: 'M5 12h14',
+  fit: 'M9 4H4v5M15 4h5v5M4 15v5h5M20 15v5h-5',
+  close: 'M6 6l12 12M18 6 6 18',
+  help: 'M9.1 8a3 3 0 0 1 5.8 1c0 2-3 2-3 4M12 17v.1',
+}
+
+/** Theme-owned resources; source SVG replacement automatically closes the current view. */
+export interface MermaidViewer {
+  /** Close the view and update entries after a route, language, or theme change. */
+  refresh(): void
+  /** Remove entries, observers, listeners, the dialog, and the page scroll lock. */
+  dispose(): void
+}
+
+function labelButton(element: HTMLButtonElement, label: string): void {
+  element.setAttribute('aria-label', label)
+  element.title = label
+}
+
+function button(doc: Document, label: string, icon: keyof typeof icons): HTMLButtonElement {
+  const element = doc.createElement('button')
+  element.type = 'button'
+  labelButton(element, label)
+  const svg = doc.createElementNS('http://www.w3.org/2000/svg', 'svg')
+  svg.classList.add('dsh-diagram-icon')
+  svg.setAttribute('viewBox', '0 0 24 24')
+  svg.setAttribute('aria-hidden', 'true')
+  svg.setAttribute('focusable', 'false')
+  const path = doc.createElementNS(svg.namespaceURI, 'path')
+  path.setAttribute('d', icons[icon])
+  svg.append(path)
+  element.append(svg)
+  return element
+}
+
+function dimensions(svg: SVGSVGElement): { width: number; height: number } | undefined {
+  const { width, height } = svg.viewBox.baseVal
+  if (Number.isFinite(width) && width > 0 && Number.isFinite(height) && height > 0) {
+    return { width, height }
+  }
+  return undefined
+}
+
+function openDiagram(
+  svg: SVGSVGElement, trigger: HTMLButtonElement, copy: typeof messages.en, onClose: () => void,
+): () => void {
+  const size = dimensions(svg)
+  if (!size) return () => {}
+  const doc = svg.ownerDocument
+  const dialog = doc.createElement('dialog')
+  dialog.className = 'dsh-diagram-viewer'
+  dialog.setAttribute('aria-labelledby', 'dsh-diagram-title')
+  const toolbar = doc.createElement('div')
+  toolbar.className = 'dsh-diagram-toolbar'
+  const title = doc.createElement('span')
+  title.className = 'dsh-diagram-title'
+  title.id = 'dsh-diagram-title'
+  title.textContent = doc.querySelector('.vp-doc h1')?.textContent.trim() || copy.title
+  const zoomOut = button(doc, copy.zoomOut, 'zoomOut')
+  const zoomIn = button(doc, copy.zoomIn, 'zoomIn')
+  const scaleLabel = doc.createElement('span')
+  scaleLabel.className = 'dsh-diagram-scale'
+  const fit = button(doc, copy.fit, 'fit')
+  fit.className = 'dsh-diagram-fit'
+  const close = button(doc, copy.close, 'close')
+  close.className = 'dsh-diagram-close'
+  close.autofocus = true
+  toolbar.append(zoomOut, scaleLabel, zoomIn, fit)
+  const helpToggle = button(doc, copy.helpLabel, 'help')
+  helpToggle.className = 'dsh-diagram-help-toggle'
+  helpToggle.setAttribute('aria-expanded', 'false')
+  helpToggle.setAttribute('aria-controls', 'dsh-diagram-help-text')
+  const help = doc.createElement('p')
+  help.className = 'dsh-diagram-help'
+  help.id = 'dsh-diagram-help-text'
+  help.hidden = true
+  help.textContent = copy.help
+  const viewport = doc.createElement('div')
+  viewport.className = 'dsh-diagram-viewport'
+  const paper = doc.createElement('div')
+  paper.className = 'dsh-diagram-paper'
+  // Each Mermaid SVG embeds ID-scoped styles and fragment references. A shadow root
+  // keeps the enlarged copy's IDs and styles separate from the original diagram.
+  const shadow = paper.attachShadow({ mode: 'open' })
+  const clone = svg.cloneNode(true) as SVGSVGElement
+  Object.assign(clone.style, {
+    position: 'absolute', left: '50%', top: '50%', transform: 'translate(-50%, -50%)',
+    width: `${size.width}px`, height: `${size.height}px`, maxWidth: 'none', display: 'block',
+  })
+  shadow.append(clone)
+  viewport.append(paper)
+  dialog.append(viewport, title, close, toolbar, helpToggle, help)
+  doc.body.append(dialog)
+
+  const overflow = doc.body.style.overflow
+  const listeners = new AbortController()
+  let panzoom: ReturnType<typeof Panzoom> | undefined
+  let resize: ResizeObserver | undefined
+  let closed = false
+  function cleanup(): void {
+    if (closed) return
+    closed = true
+    listeners.abort()
+    resize?.disconnect()
+    panzoom?.destroy()
+    dialog.close()
+    dialog.remove()
+    doc.body.style.overflow = overflow
+    if (trigger.isConnected) trigger.focus({ preventScroll: true })
+    onClose()
+  }
+  try {
+    dialog.showModal()
+    doc.body.style.overflow = 'hidden'
+    const fitScale = (): number => Math.min(
+      1, Math.max(1, viewport.clientWidth - 32) / size.width,
+      Math.max(1, viewport.clientHeight - 32) / size.height,
+    )
+    const controller = Panzoom(paper, {
+      canvas: true, startScale: fitScale(), minScale: fitScale() / 2,
+      maxScale: 8, animate: false, pinchAndPan: true,
+    })
+    panzoom = controller
+    const refit = (): void => {
+      const scale = fitScale()
+      controller.setOptions({ minScale: scale / 2 })
+      controller.zoom(scale, { animate: false })
+      controller.pan(0, 0, { animate: false })
+    }
+    const options = { signal: listeners.signal }
+    const updateScale = (): void => { scaleLabel.textContent = `${Math.round(controller.getScale() * 100)}%` }
+    updateScale()
+    paper.addEventListener('panzoomchange', updateScale, options)
+    helpToggle.addEventListener('click', () => {
+      help.hidden = !help.hidden
+      helpToggle.setAttribute('aria-expanded', String(!help.hidden))
+    }, options)
+    close.addEventListener('click', cleanup, options)
+    dialog.addEventListener('close', cleanup, options)
+    dialog.addEventListener('cancel', (event) => {
+      event.preventDefault()
+      cleanup()
+    }, options)
+    zoomIn.addEventListener('click', () => controller.zoomIn({ animate: false }), options)
+    zoomOut.addEventListener('click', () => controller.zoomOut({ animate: false }), options)
+    fit.addEventListener('click', refit, options)
+    viewport.addEventListener('wheel', event => controller.zoomWithWheel(event), { ...options, passive: false })
+    dialog.addEventListener('keydown', (event) => {
+      if (event.key === 'Tab') {
+        const controls = [close, zoomOut, zoomIn, fit, helpToggle]
+        const current = controls.indexOf(doc.activeElement as HTMLButtonElement)
+        const next = current < 0 ? (event.shiftKey ? controls.length - 1 : 0)
+          : (current + (event.shiftKey ? -1 : 1) + controls.length) % controls.length
+        event.preventDefault()
+        controls[next]?.focus()
+        return
+      }
+      const distance = 64 / controller.getScale()
+      const offsets: Record<string, [number, number]> = {
+        ArrowLeft: [distance, 0], ArrowRight: [-distance, 0],
+        ArrowUp: [0, distance], ArrowDown: [0, -distance],
+      }
+      const offset = offsets[event.key]
+      if (offset && !event.altKey && !event.ctrlKey && !event.metaKey) {
+        event.preventDefault()
+        controller.pan(...offset, { relative: true, animate: false })
+      }
+    }, options)
+    resize = new ResizeObserver(refit)
+    resize.observe(viewport)
+    return cleanup
+  } catch (error) {
+    cleanup()
+    throw error
+  }
+}
+
+/**
+ * Enhance rendered Mermaid SVGs without modifying the canonical Markdown or renderer.
+ * @param doc Browser document containing VitePress content.
+ * @param language Current VitePress language, read again when entries refresh.
+ * @returns Resources owned by the mounted theme.
+ */
+export function installMermaidViewer(doc: Document, language: () => string): MermaidViewer {
+  const entries = new Map<Element, { svg: SVGSVGElement; button: HTMLButtonElement }>()
+  let active: SVGSVGElement | undefined
+  let close: (() => void) | undefined
+  const closeActive = (): void => {
+    close?.()
+    close = undefined
+    active = undefined
+  }
+  const scan = (): void => {
+    const copy = language().startsWith('zh') ? messages.zh : messages.en
+    const containers = new Set(doc.querySelectorAll('.vp-doc .mermaid'))
+    for (const [container, entry] of entries) {
+      if (!containers.has(container) || container.querySelector('svg:not(.dsh-diagram-icon)') !== entry.svg || !entry.button.isConnected) {
+        if (entry.svg === active) closeActive()
+        entry.button.remove()
+        entries.delete(container)
+      }
+    }
+    for (const container of containers) {
+      const existing = entries.get(container)
+      if (existing) {
+        if (existing.button.getAttribute('aria-label') !== copy.open) labelButton(existing.button, copy.open)
+        continue
+      }
+      const svg = container.querySelector<SVGSVGElement>('svg:not(.dsh-diagram-icon)')
+      if (!svg || !dimensions(svg)) continue
+      const trigger = button(doc, copy.open, 'open')
+      trigger.className = 'dsh-diagram-open'
+      trigger.setAttribute('aria-haspopup', 'dialog')
+      trigger.addEventListener('click', () => {
+        closeActive()
+        close = openDiagram(svg, trigger, language().startsWith('zh') ? messages.zh : messages.en, () => {
+          close = undefined
+          active = undefined
+        })
+        active = svg
+      })
+      container.prepend(trigger)
+      entries.set(container, { svg, button: trigger })
+    }
+  }
+  const observer = new MutationObserver(scan)
+  observer.observe(doc.querySelector('#VPContent') ?? doc.body, { childList: true, subtree: true })
+  scan()
+  return {
+    refresh() {
+      closeActive()
+      scan()
+    },
+    dispose() {
+      observer.disconnect()
+      closeActive()
+      for (const entry of entries.values()) entry.button.remove()
+      entries.clear()
+    },
+  }
+}
diff --git a/website/AGENTS.md b/website/AGENTS.md
index fce0b95e93..da755ec3c2 100644
--- a/website/AGENTS.md
+++ b/website/AGENTS.md
@@ -15,3 +15,5 @@ Production builds remove the configured output directory after VitePress resolve
 The build also emits each route's raw-Markdown twin (with a parent-level alias per index route) and a root `llms.txt` index into `.dist/`, so a page's URL, minus any trailing slash, plus `.md` serves it as plain Markdown. Both derive from the publication manifest at build time; neither is ever a file in this tree.
 
 Run `pnpm docs:check` after changing this subtree; the gate rejects additional non-ignored Markdown under `website/`.
+
+The default-theme extension owns the Mermaid fullscreen viewer. Keep its enhancements separate from Markdown projection and preserve the original SVG. Route, language, theme, and rendered-SVG changes close the active view; theme disposal releases every observer, listener, and scroll lock. The [viewer decision](../.agents/notes/implemented/feature/2026-09-14-docs-mermaid-viewer.md) explains SVG isolation and verification.
diff --git a/website/package.json b/website/package.json
index 3040893a55..4e7ea25e8f 100644
--- a/website/package.json
+++ b/website/package.json
@@ -10,6 +10,7 @@
   },
   "devDependencies": {
     "@braintree/sanitize-url": "7.1.2",
+    "@panzoom/panzoom": "4.6.2",
     "cytoscape": "3.34.0",
     "cytoscape-cose-bilkent": "4.1.0",
     "dayjs": "1.11.21",
@@ -17,6 +18,7 @@
     "mermaid": "11.16.0",
     "vite": "^5.4.14",
     "vitepress": "^1.6.4",
-    "vitepress-plugin-mermaid": "^2.0.17"
+    "vitepress-plugin-mermaid": "^2.0.17",
+    "vue": "3.5.39"
   }
 }
diff --git a/website/tests/mermaid-viewer.spec.ts b/website/tests/mermaid-viewer.spec.ts
new file mode 100644
index 0000000000..5d3710c46c
--- /dev/null
+++ b/website/tests/mermaid-viewer.spec.ts
@@ -0,0 +1,268 @@
+/** @vitest-environment jsdom */
+/** Viewer ownership and interaction tests; browser checks cover native modal focus and SVG layout. */
+import assert from 'node:assert/strict'
+import type { PanzoomOptions } from '@panzoom/panzoom'
+import { getByRole, queryAllByRole, queryByRole, waitFor } from '@testing-library/dom'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { installMermaidViewer, type MermaidViewer } from '../.vitepress/theme/mermaid-viewer.ts'
+
+const panzoom = vi.hoisted(() => ({
+  create: vi.fn<(element: HTMLElement, options: PanzoomOptions) => unknown>(),
+  destroy: vi.fn(), setOptions: vi.fn(), zoom: vi.fn(), pan: vi.fn(),
+  zoomIn: vi.fn(), zoomOut: vi.fn(), zoomWithWheel: vi.fn(), getScale: vi.fn<() => number>(),
+}))
+vi.mock('@panzoom/panzoom', () => ({ default: panzoom.create }))
+
+let viewer: MermaidViewer | undefined
+let resize: (() => void) | undefined
+let viewportWidth = 1032
+let viewportHeight = 632
+const disconnect = vi.fn()
+const dialogMethods = new Map(['showModal', 'close'].map(name => [
+  name, Object.getOwnPropertyDescriptor(HTMLDialogElement.prototype, name),
+]))
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  panzoom.create.mockImplementation((_element, options) => {
+    panzoom.getScale.mockReturnValue(options.startScale ?? 1)
+    return panzoom
+  })
+  viewportWidth = 1032
+  viewportHeight = 632
+  document.body.innerHTML = '<main id="VPContent" class="vp-doc"><div class="mermaid"></div></main>'
+  document.body.style.overflow = 'auto'
+  vi.spyOn(SVGSVGElement.prototype, 'viewBox', 'get').mockImplementation(function (this: SVGSVGElement) {
+    const [x, y, width, height] = (this.getAttribute('viewBox') ?? '0 0 0 0').split(' ').map(Number)
+    return { baseVal: { x, y, width, height } } as SVGAnimatedRect
+  })
+  vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockImplementation(() => viewportWidth)
+  vi.spyOn(HTMLElement.prototype, 'clientHeight', 'get').mockImplementation(() => viewportHeight)
+  Object.defineProperty(HTMLDialogElement.prototype, 'showModal', { configurable: true, value: function (this: HTMLDialogElement) {
+    this.open = true
+    this.querySelector<HTMLButtonElement>('[autofocus]')?.focus()
+  } })
+  Object.defineProperty(HTMLDialogElement.prototype, 'close', { configurable: true, value: function (this: HTMLDialogElement) {
+    this.open = false
+    this.dispatchEvent(new Event('close'))
+  } })
+  vi.stubGlobal('ResizeObserver', class {
+    constructor(callback: () => void) { resize = callback }
+    observe(): void {}
+    disconnect = disconnect
+  })
+})
+
+afterEach(() => {
+  viewer?.dispose()
+  viewer = undefined
+  resize = undefined
+  document.body.replaceChildren()
+  document.body.style.overflow = ''
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+  for (const [name, descriptor] of dialogMethods) {
+    if (descriptor) Object.defineProperty(HTMLDialogElement.prototype, name, descriptor)
+    else Reflect.deleteProperty(HTMLDialogElement.prototype, name)
+  }
+})
+
+function required<T>(value: T | null | undefined): T {
+  assert(value != null)
+  return value
+}
+
+function render(viewBox = '0 0 2000 3000'): SVGSVGElement {
+  const container = required(document.querySelector('.mermaid'))
+  container.innerHTML = `<svg id="diagram" viewBox="${viewBox}" xmlns="http://www.w3.org/2000/svg"><defs><marker id="arrow"/></defs><path marker-end="url(#arrow)"/></svg>`
+  return required(container.querySelector('svg'))
+}
+
+function open(): HTMLDialogElement {
+  getByRole(document.body, 'button', { name: 'View diagram fullscreen' }).click()
+  return getByRole(document.body, 'dialog', { name: 'Diagram viewer' }) as HTMLDialogElement
+}
+
+describe('documentation Mermaid viewer', () => {
+  it.each([
+    { heading: 'Agent lifecycle', language: 'en-US', expected: 'Agent lifecycle' },
+    { heading: '  \n  ', language: 'zh-CN', expected: '图表查看器' },
+    { heading: null, language: 'en-US', expected: 'Diagram viewer' },
+  ])('uses the visible title as the dialog name for $heading', ({ heading, language, expected }) => {
+    render()
+    if (heading !== null) {
+      const h1 = document.createElement('h1')
+      h1.textContent = heading
+      required(document.querySelector('.vp-doc')).prepend(h1)
+    }
+    viewer = installMermaidViewer(document, () => language)
+    getByRole(document.body, 'button').click()
+    const dialog = getByRole(document.body, 'dialog', { name: expected })
+    const title = required(document.getElementById(required(dialog.getAttribute('aria-labelledby'))))
+    expect(title.textContent).toBe(expected)
+  })
+
+  it('adds one entry only after an SVG with usable dimensions renders', async () => {
+    viewer = installMermaidViewer(document, () => 'en-US')
+    expect(queryAllByRole(document.body, 'button')).toHaveLength(0)
+    render('0 0 0 3000')
+    viewer.refresh()
+    expect(queryAllByRole(document.body, 'button')).toHaveLength(0)
+    render()
+    await waitFor(() => {
+      expect(queryAllByRole(document.body, 'button')).toHaveLength(1)
+    })
+    viewer.refresh()
+    expect(queryAllByRole(document.body, 'button')).toHaveLength(1)
+    expect(required(document.querySelector('.mermaid')).firstElementChild?.tagName).toBe('BUTTON')
+    const trigger = getByRole(document.body, 'button', { name: 'View diagram fullscreen' })
+    expect(trigger.querySelector('svg')?.getAttribute('aria-hidden')).toBe('true')
+    await new Promise<void>((resolve) => { queueMicrotask(resolve) })
+    expect(getByRole(document.body, 'button', { name: 'View diagram fullscreen' })).toBe(trigger)
+  })
+
+  it('fits the natural SVG into the viewport and isolates copied styles and fragment IDs', () => {
+    const source = render()
+    const original = source.outerHTML
+    viewer = installMermaidViewer(document, () => 'en-US')
+    const dialog = open()
+    expect(panzoom.create.mock.calls[0]?.[1]).toMatchObject({ startScale: 0.2, minScale: 0.1 })
+    const paper = required(dialog.querySelector<HTMLElement>('.dsh-diagram-paper'))
+    const clone = required(paper.shadowRoot?.querySelector('svg'))
+    expect(clone.style.width).toBe('2000px')
+    expect(clone.style.height).toBe('3000px')
+    expect(paper.shadowRoot?.querySelector('path')?.getAttribute('marker-end')).toBe('url(#arrow)')
+    expect(document.querySelectorAll('#diagram')).toHaveLength(1)
+    expect(source.outerHTML).toBe(original)
+    expect(document.body.style.overflow).toBe('hidden')
+    expect(document.documentElement.style.overflow).toBe('')
+    required(resize)()
+    expect(panzoom.zoom).toHaveBeenLastCalledWith(0.2, { animate: false })
+    expect(panzoom.pan).toHaveBeenLastCalledWith(0, 0, { animate: false })
+    viewportWidth = 332
+    viewportHeight = 932
+    required(resize)()
+    expect(panzoom.zoom).toHaveBeenLastCalledWith(0.15, { animate: false })
+    expect(panzoom.pan).toHaveBeenLastCalledWith(0, 0, { animate: false })
+  })
+
+  it('connects zoom, wheel, keyboard panning and fit without dismissing a canvas click', () => {
+    render()
+    viewer = installMermaidViewer(document, () => 'en-US')
+    const dialog = open()
+    getByRole(dialog, 'button', { name: 'Zoom in' }).click()
+    getByRole(dialog, 'button', { name: 'Zoom out' }).click()
+    expect(panzoom.zoomIn).toHaveBeenCalledOnce()
+    expect(panzoom.zoomOut).toHaveBeenCalledOnce()
+    const viewport = required(dialog.querySelector<HTMLElement>('.dsh-diagram-viewport'))
+    const wheel = new WheelEvent('wheel', { deltaY: -100 })
+    viewport.dispatchEvent(wheel)
+    expect(panzoom.zoomWithWheel).toHaveBeenCalledWith(wheel)
+    panzoom.getScale.mockReturnValue(2)
+    dialog.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight' }))
+    expect(panzoom.pan).toHaveBeenLastCalledWith(-32, 0, { relative: true, animate: false })
+    getByRole(dialog, 'button', { name: 'Fit view' }).click()
+    expect(panzoom.zoom).toHaveBeenLastCalledWith(0.2, { animate: false })
+    expect(panzoom.pan).toHaveBeenLastCalledWith(0, 0, { animate: false })
+    viewport.click()
+    expect(dialog.open).toBe(true)
+  })
+
+  it('wraps keyboard focus through the viewer controls in both directions', () => {
+    render()
+    viewer = installMermaidViewer(document, () => 'en-US')
+    const dialog = open()
+    const close = getByRole(dialog, 'button', { name: 'Close' })
+    const zoomOut = getByRole(dialog, 'button', { name: 'Zoom out' })
+    close.focus()
+    dialog.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', cancelable: true }))
+    expect(document.activeElement).toBe(zoomOut)
+    dialog.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', shiftKey: true, cancelable: true }))
+    expect(document.activeElement).toBe(close)
+    dialog.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', shiftKey: true, cancelable: true }))
+    expect(document.activeElement).toBe(getByRole(dialog, 'button', { name: 'Viewer help' }))
+    dialog.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', cancelable: true }))
+    expect(document.activeElement).toBe(close)
+  })
+
+  it('shows zoom changes and reveals help on demand without retaining listeners after close', () => {
+    render()
+    viewer = installMermaidViewer(document, () => 'en-US')
+    const dialog = open()
+    const scale = required(dialog.querySelector('.dsh-diagram-scale'))
+    const paper = required(dialog.querySelector('.dsh-diagram-paper'))
+    expect(scale.textContent).toBe('20%')
+    panzoom.getScale.mockReturnValue(0.75)
+    paper.dispatchEvent(new Event('panzoomchange'))
+    expect(scale.textContent).toBe('75%')
+    const toggle = getByRole(dialog, 'button', { name: 'Viewer help' })
+    const help = required(document.getElementById(required(toggle.getAttribute('aria-controls'))))
+    expect(help.hidden).toBe(true)
+    toggle.click()
+    expect(help.hidden).toBe(false)
+    expect(toggle.getAttribute('aria-expanded')).toBe('true')
+    toggle.click()
+    expect(help.hidden).toBe(true)
+    getByRole(dialog, 'button', { name: 'Close' }).click()
+    toggle.click()
+    expect(help.hidden).toBe(true)
+    panzoom.getScale.mockReturnValue(1.5)
+    paper.dispatchEvent(new Event('panzoomchange'))
+    expect(scale.textContent).toBe('75%')
+  })
+
+  it.each(['button', 'cancel', 'refresh', 'dispose'] as const)('releases resources on %s and restores focus and scrolling', (method) => {
+    render()
+    viewer = installMermaidViewer(document, () => 'en-US')
+    const trigger = getByRole(document.body, 'button')
+    const dialog = open()
+    const zoom = getByRole(dialog, 'button', { name: 'Zoom in' })
+    if (method === 'button') getByRole(dialog, 'button', { name: 'Close' }).click()
+    else if (method === 'cancel') dialog.dispatchEvent(new Event('cancel', { cancelable: true }))
+    else viewer[method]()
+    expect(queryByRole(document.body, 'dialog')).toBeNull()
+    expect(document.body.style.overflow).toBe('auto')
+    expect(panzoom.destroy).toHaveBeenCalledOnce()
+    expect(disconnect).toHaveBeenCalledOnce()
+    zoom.click()
+    expect(panzoom.zoomIn).not.toHaveBeenCalled()
+    if (method !== 'dispose') expect(document.activeElement).toBe(trigger)
+    viewer.dispose()
+    expect(panzoom.destroy).toHaveBeenCalledOnce()
+  })
+
+  it('closes a replaced diagram and permits repeated opens with the updated locale', async () => {
+    render()
+    let locale = 'en-US'
+    viewer = installMermaidViewer(document, () => locale)
+    open()
+    render('0 0 400 200')
+    await waitFor(() => {
+      expect(queryByRole(document.body, 'dialog')).toBeNull()
+    })
+    expect(panzoom.destroy).toHaveBeenCalledOnce()
+    open()
+    locale = 'zh-CN'
+    viewer.refresh()
+    getByRole(document.body, 'button', { name: '全屏查看图表' }).click()
+    expect(getByRole(document.body, 'dialog', { name: '图表查看器' })).toBeTruthy()
+    getByRole(document.body, 'button', { name: '关闭' }).click()
+    expect(panzoom.destroy).toHaveBeenCalledTimes(3)
+  })
+
+  it('closes when route content is removed and stops enhancing after disposal', async () => {
+    render()
+    viewer = installMermaidViewer(document, () => 'en-US')
+    open()
+    required(document.querySelector('.mermaid')).remove()
+    await waitFor(() => {
+      expect(queryByRole(document.body, 'dialog')).toBeNull()
+    })
+    expect(document.body.style.overflow).toBe('auto')
+    viewer.dispose()
+    required(document.querySelector('main')).innerHTML = '<div class="mermaid"></div>'
+    render()
+    await new Promise<void>((resolve) => { queueMicrotask(resolve) })
+    expect(queryAllByRole(document.body, 'button')).toHaveLength(0)
+  })
+})