@dsh-electron/dsh-plugin-multi-root-workspace 0.1.6 → 0.1.8

package/CHANGELOG.en.md

@@ -8,6 +8,54 @@ This file records the user-visible changes of every **released** version.
 - For installation sources, the supported upstream runtimes, and known limitations, see the [README](./README.en.md).
 - The evidence, numbering, and release state of each version live in the [roadmap progress ledger](./docs/plans/active/2026-09-12-multi-root-workspace.md#进度总账). The body of each GitHub Release is generated from the commit history by `scripts/release-notes.mjs` and is the complete raw list behind this file.
 
+## [0.1.8] - 2026-10-18
+
+### Fixed
+
+- **Permission settings page unavailable on DSH 0.2.0**: when installed via `link:`, the plugin resolved optional packages it never loads — packages consumed only as mounted host services (`dsh-lsp` / `dsh-lsp-stdio` / `dsh-working-directory`, among others) — to the checkout's own devDependencies, so a uniformly-versioned host was misjudged as `mixed`; and because the two replacement provider rows injected the compatibility gate while upstream `fs-sandbox` / `sandbox` were already disabled unconditionally, a refused gate removed `ctx.fs` / `ctx.sandbox`, taking down `ctx.shell` and `permissionPresets` with it (`permissionPresets/catalog` reported `service-unavailable`). Optional packages are now classified by who loads the resolved copy and through which anchor — runtime-loaded, host-service, or runner-anchored — so host-service copies inside the plugin root no longer testify, and the Windows ACL package is inspected from the `dsh-sandbox-local` anchor; the two provider rows no longer inject the gate and degrade to upstream-equivalent behavior on a refused installation, while every widened-authority row stays gated (see [ADR-0009 amendment](./docs/decisions/ADR-0009-dsh-compat-contract.md#修订2026-10-18permissionpresetscatalog-事故误报检测--被门禁的-provider)).
+
+## [0.1.7] - 2026-10-17
+
+### Added
+
+- **Browse additional roots inside the Files tab**: a root switcher sits in the file-tree header (a menu entry disguised as the path label, listing the primary root plus every additional root and its state); picking an additional root hands the tree area to a byte-for-byte fork of the upstream Files tree — row height, icons, indent, and the empty state match natively item by item, the native reload is replaced by an identical icon button at the header's original spot, and switching back to the primary root restores everything. The native open-in-app button is replaced by a fork that retargets to the selected root ([ADR-0015](./docs/decisions/ADR-0015-files-tab-plugin-owned-browsing.md), [ADR-0016](./docs/decisions/ADR-0016-files-tab-native-tree-fork.md)). Panel rows carry an access badge, every path copies through the same `PathCopy` control in one tap, read-only → read-write promotion goes through a confirmation layer, and the add-row access picker is an anchored dropdown.
+- **Per-root access levels are now three-state**: `add [--inherit|--read-only|--read-write]` (or the panel's add-row selector). `inherit` follows the session mode — it is the default for new registrations, and writable records stored by older plugin versions migrate to it; `read-only` stays readable, browsable, and part of LSP and instruction delivery but grants no write authority in any mode, including `danger-full-access`; a fixed `read-write` stays writable even in a globally read-only session. `/workspace-folders access <ref> inherit|read-only|read-write` and the panel switch access per root (widening requires the root to be available and never re-authorizes its path). The persistence layout stays downgrade-safe: an older plugin reads a read-only record as invalid rather than upgrading it to writable ([ADR-0013](./docs/decisions/ADR-0013-per-root-and-per-tool-access.md), [ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)).
+- **Full-access now enforces deny boundaries too**: the shell / pwsh executors, `run_code` (PTC), and agent PTYs all bypass `confine` in `danger-full-access`, so a process fence puts them under a restricted kernel profile (macOS Seatbelt, Linux bwrap — a host where upstream selected Landlock uses bubblewrap the same way, and refuses the combination at launch when bwrap is unusable); explicit read-only roots and tool-capped members stay denied in that mode, and the fs fence reads the same deny set ([ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)).
+- **A restricted Full-access also protects `$DSH_HOME`**: whenever any deny boundary exists (a read-only root, a tool-capped member, or an unavailable registry authority), the home directory joins the deny set — the durable store, the registry lease, and user profiles live there; with zero additional roots and a healthy authority Full-access stays byte-identical to upstream ([ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)).
+- **Your panel terminals are never confined**: the process fence only prefixes spawns whose env carries `DSH_PTY_SESSION_ID` (stamped by the terminal-bash backend for agent PTYs); a terminal you open from the panel is user behavior and passes through in every mode ([ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)).
+- **Selective read-only under Windows Full-access**: an opt-in, administrator-installed per-user privileged broker ships with the package — the installer grants a fixed set of LSA rights (`SeServiceLogonRight`, `SeCreateTokenPrivilege`, `SeAssignPrimaryTokenPrivilege`, `SeTcbPrivilege`, `SeDebugPrivilege`, `SeImpersonatePrivilege`) to the dedicated virtual service account `NT SERVICE\DshMultiRootBroker-<install hash>` only and never elevates the host user; the broker builds a normal deny-only group token for the restricted child, which the runner reads back and verifies before letting it run. Without the broker the combination refuses to launch; Windows enforcement still honestly reports its partial boundary ([ADR-0020](./docs/decisions/ADR-0020-windows-normal-deny-groups.md)).
+- **Per-tool write caps**: configuring `toolAccess: { <tool>: 'read-only' }` on the `multi-root-scope` row makes that tool permanently unable to write any additional root (the primary root is unaffected); enforcement rides the real `tools/execute` dispatch context, and invalid configuration fails closed ([ADR-0013](./docs/decisions/ADR-0013-per-root-and-per-tool-access.md)).
+- **Additional-root limit**: each primary root stores at most 16 additional-root records by default (`maxAdditionalRoots`, up to 64); new additions past the limit are refused while over-limit history keeps granting. `list` prints `N of LIMIT` honestly ([ADR-0014](./docs/decisions/ADR-0014-root-limit-and-provider-conflict.md)).
+- **Provider-conflict detection**: when another plugin also replaces `ctx.fs` / `ctx.sandbox`, the multi-root rows fail loudly and grant nothing instead of depending on load order ([ADR-0014](./docs/decisions/ADR-0014-root-limit-and-provider-conflict.md)).
+- **Exact support for DSH `0.2.1-alpha.3`, `0.2.1-alpha.4`, `0.2.1-alpha.5`, `0.2.1-rc.1`, and `0.2.1-rc.2`**. Since `alpha.3`, upstream `dsh-storage-domain` pins `zod` at `4.4.3`, and the two resolved zod copies' types are mutually incompatible, so the domain schemas are now built by the zod the storage domain itself resolves. Since `alpha.4`, upstream version requirements prefer `engines.dsh`; this plugin still keeps `peerDependencies` as its single version contract. The dev pin moves to `0.2.1-rc.2` (cordis `4.0.5`; `alpha.3`–`alpha.5` use cordis `4.0.5-alpha.2`).
+
+### Changed
+
+- **Model-facing topology rewritten**: the prompt states authority truthfully per mode and platform — writable and read-only roots listed separately, cd/worktree switches do not change grants, grant changes constrain only later operations and new processes, capped tools are named, and Windows adds the restricted-token partial-enforcement caveat plus the note that reads are not confined by it ([ADR-0013](./docs/decisions/ADR-0013-per-root-and-per-tool-access.md)).
+
+### Fixed
+
+- **An unavailable registry authority no longer reads as "no restrictions"**: a process that read an empty root table (contended, storage failure, invalid configuration) used to let Full-access write anywhere; `danger-full-access` and `workspace-write` now grant writes only to the primary root (the shared platform temp areas are no longer writable), explicit deny boundaries still win, and the real scope returns once the lease is taken over ([ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)).
+- **Renaming an ancestor can no longer lift a read-only boundary**: renaming a denied root's parent used to move the tree outside its path-based restriction. Seatbelt now also denies writes to each ancestor directory itself (`(literal …)`), and bwrap self-binds ancestors into mountpoints so rename fails with EBUSY. Windows pins the root and its ancestors with directory handles that disallow delete sharing until the restricted Job's descendants have drained, preventing a shell rename followed by a host file-tool bypass. These mechanisms constrain ancestor renames or metadata operations ([ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md), [ADR-0020](./docs/decisions/ADR-0020-windows-normal-deny-groups.md)).
+- **Negative authorization survives reordering, disappearance, and conflicts**: overlapping stored registrations both lose membership grants while retaining their trusted deny boundaries. New registrations also check the reserved boundaries of missing or redirected roots. Globally read-only sessions apply denies after adding fixed read-write roots; backends that cannot express subtree subtraction refuse to launch.
+- **Windows checks every deny root for hardlinks before ACL changes**: any multi-link file or uninspectable node refuses startup before any ACL write, avoiding changes to shared objects in the pnpm store or other link locations. The host maintenance command `/workspace-folders isolate-profiles [--apply]` inspects by default; explicit apply only sets profile imports to copy. Existing dependencies still require the reported reinstall steps, and historical ACLs are not repaired ([ADR-0020](./docs/decisions/ADR-0020-windows-normal-deny-groups.md)).
+- **A deny root that vanished on Linux fails closed instead of opening up**: the root's bwrap mount is mandatory again — when the directory disappears after registration or after the profile is built, namespace setup fails and the command never runs, instead of the path becoming recreatable under a writable parent mount ([ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)).
+- **Re-registering roots preserves their access**: the command and panel omit access unless explicitly chosen, so reviving a read-only registration cannot silently upgrade it; the panel keeps re-registration available for existing unavailable entries at the root limit.
+- **The panel accepts older hosts' root lists**: responses without `limit` / `count` remain usable, while explicitly malformed values are still rejected.
+- **Invalid toolAccess is reflected in the topology prompt**: the model sees that all additional-root writes are refused instead of being told read-write registrations are writable; a `null` root-limit configuration also fails closed.
+- **Confined shell commands work again for installed copies on Windows (DSH 0.1.7-alpha.1+)**: with the published v0.1.6 installed from npm/tarball, the standalone Windows runner died before its first line with `ERR_MODULE_NOT_FOUND` — its static module graph imported upstream packages that cannot be resolved from the plugin's install directory, so every confined command in a session with additional roots failed on the affected releases. The runner's static graph is now `node:` builtins only, and it loads the upstream ACL package by self-reference from the upstream runner's own location.
+- **Network and device roots are rejected on Windows**: UNC (`\\server\share`), `\\?\`, `\\.\`, and mapped network drives were previously accepted as ordinary additional roots; they are now rejected lexically as `unsupported-path` before any filesystem access, stored records are marked `invalid`, and the confined-execution side fails closed (`SandboxUnavailableError` / exit 127) rather than silently running unconfined ([ADR-0011 amendment](./docs/decisions/ADR-0011-multi-root-workspace-consumers.md)).
+- **The Windows runner re-verifies roots before spawn**: after the ACL grant and before the child starts, every root must still exist and resolve to the same canonical directory, and `--temp` must be an existing directory; anything else exits 127 without launching an unconfined process.
+- **"Reveal in file manager" no longer reports failure on Windows**: `explorer.exe` returns 1 on success, so exit codes 0 and 1 are both accepted on win32.
+- **Panel file endpoints reject backslash paths**: on POSIX, `..\..\x` previously resolved inside the selected root; backslashes are now rejected lexically.
+- **The Windows broker accepts UAC-filtered callers and diagnoses packaged children**: restricted commands launched by a non-elevated UAC administrator were previously refused for not being an "unrestricted identity"; only callers carrying restricting SIDs or an AppContainer are refused now, and a Store/MSIX child (such as `pwsh.exe` under the WindowsApps alias) gets a diagnostic pointing at the MSI/ZIP build before launch. After upgrading, reinstall the broker once with `install.ps1` for this to take effect ([ADR-0020 amendment](./docs/decisions/ADR-0020-windows-normal-deny-groups.md)).
+- **Panel file-tree calls are abortable**: in-flight `files` / `readFile` calls are cancelled on unmount, path, or session change, so stale responses no longer render as errors.
+
+### Changed
+
+- **Confined Windows shell behavior, documented**: the confined shell is pwsh (Git Bash/MSYS cannot start under the restricted token, identically to the upstream runner); under the plugin runner a confined child receives Ctrl+C and the runner mirrors its exit code, while an upstream-confined child inherits the runner's ignore-Ctrl+C flag and cannot receive it — both are established behavior ([ADR-0011 amendment](./docs/decisions/ADR-0011-multi-root-workspace-consumers.md)).
+- Install note added: if the first install was interrupted by the `koffi` build approval, a successful follow-up `add` may still leave the plugin absent from `dsh.profile.bundles`; one `remove` + `add` activates it ([troubleshooting](./docs/troubleshooting/install-stops-at-build-approval.md)).
+
 ## [0.1.6] - 2026-10-11
 
 ### Added
@@ -114,7 +162,9 @@ The first release: the three MVP milestones (M1–M3).
 
 - All eight findings of the pre-release external review (three of them release-blocking) are fixed, each with a regression test: a registered directory replaced by a symlink transplanting its authority (which introduced `recordedPath` — **re-resolving a path is not re-authorizing it**), concurrent registry mutations losing a write or reviving a revoked grant (per-primary-root mutations are serialized), a refresh not re-checking directories, a typed path being overwritten by the directory picker, the `reveal` response contract and failure code, duplicate ids not validated, the primary root missing from nesting validation, and CI testing before building.
 
-[Unreleased]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.6...HEAD
+[Unreleased]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.8...HEAD
+[0.1.8]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.7...v0.1.8
+[0.1.7]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.3...v0.1.4

package/CHANGELOG.md

@@ -8,6 +8,54 @@ English: [CHANGELOG.en.md](./CHANGELOG.en.md)
 - 安装方式、受支持的上游运行时与已知限制见 [README](./README.md)。
 - 每个版本的实施证据、编号口径与发布状态见[路线图 §进度总账](./docs/plans/active/2026-09-12-multi-root-workspace.md#进度总账)；GitHub Release 的正文由 `scripts/release-notes.mjs` 从 commit 历史生成，是本文件之外的完整原始清单。
 
+## [0.1.8] - 2026-10-18
+
+### Fixed
+
+- **DSH 0.2.0 上权限设置页不可用**：以 `link:` 方式安装时，插件把只作为宿主服务消费、自身从不加载的可选包（`dsh-lsp` / `dsh-lsp-stdio` / `dsh-working-directory` 等）解析到检出目录自己的 devDependencies，版本统一的宿主被误判为 `mixed`；同时两个 provider 替身行 inject 兼容门禁而上游 `fs-sandbox` / `sandbox` 已被无条件禁用，门禁一旦拒绝，`ctx.fs` / `ctx.sandbox` 消失并连带 `ctx.shell` 与 `permissionPresets` 瘫痪（`permissionPresets/catalog` 报 `service-unavailable`）。可选包现按"谁加载副本、经哪个锚点"分为运行时加载、宿主服务与 runner 锚定三类——插件根内的宿主服务副本不再作证，Windows ACL 包改从 `dsh-sandbox-local` 锚点取证；两个 provider 行不再 inject 门禁，在被拒安装上退化为上游等价行为，宽授权行的门禁不变（[ADR-0009 修订](./docs/decisions/ADR-0009-dsh-compat-contract.md#修订2026-10-18permissionpresetscatalog-事故误报检测--被门禁的-provider)）。
+
+## [0.1.7] - 2026-10-17
+
+### Added
+
+- **Files 页签内浏览附加根**：文件树 header 新增根切换器（伪装成路径标签的菜单入口，列出主根与全部附加根及其状态）；选中附加根时由逐字节复刻的上游 Files 树接管树区——行高、图标、缩进、空态与原生逐项一致，原生 reload 由 header 原位同款图标钮顶替，切回主根即完整还原。原生 open-in-app 按钮由复刻件顶替并把目标换成选中根（[ADR-0015](./docs/decisions/ADR-0015-files-tab-plugin-owned-browsing.md)、[ADR-0016](./docs/decisions/ADR-0016-files-tab-native-tree-fork.md)）。面板行带访问级别徽标，所有路径用同一 `PathCopy` 控件一点即复制；只读 → 读写升级经确认层；添加行的权限选择器为锚定下拉。
+- **附加根访问级别升级为三态**：`add [--inherit|--read-only|--read-write]`（或面板添加行选择）。`inherit` 跟随会话模式——新登记的默认值，旧版插件登记的可写记录也迁移为 `inherit`；`read-only` 可读、可浏览、参与 LSP 与指令注入，但任何模式（包括 `danger-full-access`）都不授予写权限；`read-write` 固定在全局只读会话里仍可写。`/workspace-folders access <ref> inherit|read-only|read-write` 与面板按根切换（扩权要求该根此刻可用且不重新授权路径）。持久化布局向下兼容：旧版本插件把只读记录判为无效而非升级为可写（[ADR-0013](./docs/decisions/ADR-0013-per-root-and-per-tool-access.md)、[ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)）。
+- **Full-access 也强制执行拒写边界**：shell / pwsh 执行器、`run_code`（PTC）与 agent PTY 在 `danger-full-access` 下绕过 `confine`，进程围栏为它们统一套用受限内核 profile（macOS Seatbelt、Linux bwrap——上游选定 Landlock 的主机同样改走 bubblewrap，bwrap 不可用时该组合在启动前拒绝），显式只读根与被工具封顶的根在该模式下依旧拒写；fs fence 读取同一份 deny 集（[ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)）。
+- **受限 Full-access 保护 `$DSH_HOME`**：只要存在任何拒写边界（只读根、工具封顶成员或注册表权限不可用），home 目录就进入 deny 集——存根存储、注册表 lease 与用户 profile 都在其中；零附加根且注册表健康时 Full-access 与上游逐字节一致（[ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)）。
+- **面板用户终端不受约束**：进程围栏只对 env 带 `DSH_PTY_SESSION_ID` 的 spawn 生效（agent PTY 由 terminal-bash backend 盖章）；你在面板打开的终端属于用户行为，任何模式直通（[ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)）。
+- **Windows 上 Full-access 的局部拒写**：随包提供需管理员安装的每用户特权 broker——安装器只向专用虚拟服务账户 `NT SERVICE\DshMultiRootBroker-<安装哈希>` 授予固定 LSA 权限（`SeServiceLogonRight`、`SeCreateTokenPrivilege`、`SeAssignPrimaryTokenPrivilege`、`SeTcbPrivilege`、`SeDebugPrivilege`、`SeImpersonatePrivilege`），不为宿主用户提权；broker 为受限子进程构造普通 deny-only 组 token，runner 读回验证后才放行。未安装 broker 时该组合拒绝启动；Windows 执行仍如实报告 partial 边界（[ADR-0020](./docs/decisions/ADR-0020-windows-normal-deny-groups.md)）。
+- **per-tool 写权限封顶**：`multi-root-scope` 行配置 `toolAccess: { <工具名>: 'read-only' }` 后，该工具永远不能写任何附加根（主根不受影响）；封顶经 `tools/execute` 的真实 dispatch 上下文执行，非法配置 fail closed（[ADR-0013](./docs/decisions/ADR-0013-per-root-and-per-tool-access.md)）。
+- **附加根数量上限**：每个主根默认最多登记 16 条附加根记录（`maxAdditionalRoots` 可调至 64）；超限的新增被拒绝，历史超限记录照常授予。列表如实显示 `N of LIMIT`（[ADR-0014](./docs/decisions/ADR-0014-root-limit-and-provider-conflict.md)）。
+- **Provider 冲突检测**：另一插件也替换 `ctx.fs` / `ctx.sandbox` 时，多根行响亮失败并拒绝一切授予，而不是依赖装载顺序（[ADR-0014](./docs/decisions/ADR-0014-root-limit-and-provider-conflict.md)）。
+- **精确支持 DSH `0.2.1-alpha.3`、`0.2.1-alpha.4`、`0.2.1-alpha.5`、`0.2.1-rc.1` 与 `0.2.1-rc.2`**。上游 `alpha.3` 起 `dsh-storage-domain` 把 `zod` 固定为 `4.4.3`，两个 zod 副本的类型互不兼容，域 schema 改由存储域自身解析的 zod 构建；`alpha.4` 起上游版本需求优先读 `engines.dsh`，本插件仍以 `peerDependencies` 为唯一版本契约。开发 pin 提升到 `0.2.1-rc.2`（cordis `4.0.5`；`alpha.3`–`alpha.5` 的 cordis 为 `4.0.5-alpha.2`）。
+
+### Changed
+
+- **模型侧拓扑文案重写**：按当前模式与平台如实陈述授权——可写与只读根分组列出，声明 cwd/worktree 切换不改变授权、授权变化只约束后续操作与新进程；配置封顶工具时点名；Windows 附带 restricted-token partial-enforcement 与读不受其 confine 的说明（[ADR-0013](./docs/decisions/ADR-0013-per-root-and-per-tool-access.md)）。
+
+### Fixed
+
+- **注册表权限不可用不再读作「没有限制」**：读到空根表的进程（争用、存储故障、配置非法）曾在 Full-access 下放行一切写；现在 `danger-full-access` 与 `workspace-write` 都只授予主根写权限（共享平台临时区不再可写），显式拒写边界仍优先，接管 lease 后恢复（[ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)）。
+- **改名祖先目录不能再解除只读边界**：此前把被拒根的父目录改名即可把整棵树搬出路径拒写边界；现在 Seatbelt 同时拒写被拒根的每个祖先目录本身（`(literal …)`），bwrap 把祖先自绑为挂接点使 rename 返回 EBUSY；Windows 用不共享删除的目录句柄钉住根及祖先，直到受限 Job 后代排空，防止 shell 搬走目录后经宿主文件工具绕过。祖先目录的元数据或改名操作会受相应机制限制（[ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)、[ADR-0020](./docs/decisions/ADR-0020-windows-normal-deny-groups.md)）。
+- **负授权不随排序、消失或冲突丢失**：存量重叠登记双方撤销成员授权，但可信记录的拒写边界仍保留；新增根也检查 missing / redirected 根的保留边界。全局只读会话追加固定读写根后统一应用 deny，无法表达子树减法的后端在启动前拒绝。
+- **Windows 拒写前检查全部根的硬链接**：任一根存在多链接文件或不可检查节点时，在任何 ACL 写入前拒绝启动，避免改写 pnpm store 或其他链接的共享对象。新增宿主维护命令 `/workspace-folders isolate-profiles [--apply]`：默认只读检查，显式 apply 仅将 profile 导入配置设为 copy；存量依赖仍需按报告重装，不修复历史 ACL（[ADR-0020](./docs/decisions/ADR-0020-windows-normal-deny-groups.md)）。
+- **Linux 上消失的拒写根失败关闭而非放行**：deny 根的 bwrap 挂载恢复为强制项——目录在登记后或 profile 构造后被删除时命名空间搭建失败、命令不会执行，不再出现在可写父挂载下被重建写入的缺口（[ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)）。
+- **附加根重新登记保留原权限**：命令与面板在未显式选择访问级别时不发送默认值，避免 revive 把只读登记静默升级；达到根上限时仍可从面板重新登记既有的不可用项。
+- **面板兼容旧宿主的根列表**：旧响应缺少 `limit` / `count` 时仍可显示和操作，显式非法值仍拒绝。
+- **非法 toolAccess 的拓扑文案与执行一致**：模型明确看到所有附加根写被拒，不再被告知 read-write 登记可写；根上限配置 `null` 同样 fail closed。
+- **安装副本在 Windows（DSH 0.1.7-alpha.1+）上的受限命令恢复可用**：发布的 v0.1.6 从 npm/tarball 安装后，独立 Windows runner 在首行之前就死于 `ERR_MODULE_NOT_FOUND`——它的静态模块图 import 的上游包无法从插件安装目录解析，受影响版本上配置了附加根的会话里每条受限命令都会失败。runner 的静态图现在只含 `node:` 内置，上游 ACL 包改为从上游 runner 自身位置按包自引用加载。
+- **Windows 上的网络与设备根被拒绝**：UNC（`\\server\share`）、`\\?\`、`\\.\` 与映射网络盘此前会被当成普通附加根登记；现在在任何文件系统触碰之前以 `unsupported-path` 词法拒绝，存量记录标记为 `invalid`，受限执行侧 fail closed（`SandboxUnavailableError` / 退出 127），绝不静默放开（[ADR-0011 修订](./docs/decisions/ADR-0011-multi-root-workspace-consumers.md)）。
+- **Windows runner 在 spawn 前重新验证根**：授权 ACL 之后、启动子进程之前重新确认每个根仍存在且是同一 canonical 目录，并要求 `--temp` 已存在；不满足即退出 127，不启动无约束进程。
+- **Windows 上「在文件管理器中显示」不再误报失败**：`explorer.exe` 成功时也返回 1，win32 现在接受退出码 0/1。
+- **面板文件端点拒绝反斜杠路径**：POSIX 上 `..\..\x` 此前会解析到所选根内部；现在词法拒绝。
+- **Windows broker 放行 UAC 过滤调用方并诊断打包子进程**：非提权 UAC 管理员发起的受限命令此前被 broker 以「unrestricted 身份」拒绝；现在只拒绝携带 restricting SID 或 AppContainer 的调用方，Store/MSIX 版子进程（如 WindowsApps 别名的 `pwsh.exe`）在启动前给出指向 MSI/ZIP 版的诊断。升级后需用 `install.ps1` 重装一次 broker 才会生效（[ADR-0020 修订](./docs/decisions/ADR-0020-windows-normal-deny-groups.md)）。
+- **面板文件树调用可中止**：组件卸载、路径或会话变化时取消在飞的 `files` / `readFile` 调用，过期响应不再渲染为错误。
+
+### Changed
+
+- **Windows 受限 shell 行为说明**：受限 shell 是 pwsh（Git Bash/MSYS 在 restricted token 下无法启动，与上游 runner 一致）；在插件 runner 下 confined 子进程能收到 Ctrl+C 且 runner 镜像其退出码，而上游 runner 的子进程因继承 ignore-Ctrl+C 标志收不到（两者均为既成事实，见 [ADR-0011 修订](./docs/decisions/ADR-0011-multi-root-workspace-consumers.md)）。
+- 安装提示补充：被 `koffi` 构建授权打断的首次安装，在授权后若插件未进 `dsh.profile.bundles`，需一次 `remove` + `add` 完成激活（[故障排查](./docs/troubleshooting/install-stops-at-build-approval.md)）。
+
 ## [0.1.6] - 2026-10-11
 
 ### Added
@@ -114,7 +162,9 @@ English: [CHANGELOG.en.md](./CHANGELOG.en.md)
 
 - 发布前外部评审提出的 8 项发现（其中 3 项发布阻断）全部修复，每项各带一个回归测试：登记目录被替换为符号链接后授权转移（引入 `recordedPath`，**重新解析路径不等于重新授权**）、并发修改注册表丢写或复活已撤销的授权（每个主根的变更串行）、刷新不重新检查目录、手输路径被目录选择器覆盖、`reveal` 的应答契约与失败码、重复 id 未校验、主根未纳入嵌套校验、CI 先测后构建。
 
-[Unreleased]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.6...HEAD
+[Unreleased]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.8...HEAD
+[0.1.8]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.7...v0.1.8
+[0.1.7]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/cherrchen/dsh-plugin-multi-root-workspace/compare/v0.1.3...v0.1.4

package/README.en.md

@@ -1,59 +1,58 @@
+<div align="center">
+
 # dsh-plugin-multi-root-workspace
 
 [中文](./README.md) | English
 
-## What & Why
-
-An out-of-tree plugin bundle for DSH (DeepSeek Harness) that widens the Workspace write scope from a single canonical directory to "**one primary root + N additional roots**" — **without modifying any package in the upstream repository**.
-
-The problem it solves: a real development project is usually several independent Git repositories, while DSH natively treats only the session origin as the writable root, so working across repositories means juggling sessions.
-
-Three things make this plugin worth looking at:
-
-- **Zero learning cost for the agent**: it keeps using the native `read` / `write` / `edit` / `bash` tools. The plugin adds no `workspace_*` tools at all; it only widens the answer to the one question "which directories belong to this workspace".
-- **Security does not degrade**: the additional roots are granted through the same mechanisms the harness already uses — the in-process fs fence plus kernel-level runners (Seatbelt on macOS, bwrap / Landlock on Linux) — with the fs side and bash/PTY sharing one and the same scope. It never degenerates into danger-full-access or prompt-level constraints.
-- **Absent when absent**: it replaces the upstream `fs-sandbox` and `sandbox` provider rows through a bundle patch; with no additional root configured its behavior is item-for-item identical to an uninstalled harness, and every misconfiguration fails loudly instead of silently degrading.
+</div>
 
-**Done and released: the MVP `v0.1.0` (milestones M1–M3)** — composition and empty-root pass-through, multi-root capability and dialect grants, the root registry / the `/workspace-folders` command / the Workspace Folders panel / a cross-repository journey e2e.
-
-**Done and released: the `v0.1.1` hardening batch (H1–H4)** — a cross-process Registry Authority Lease (when two DSH processes share one `$DSH_HOME`, only the lease holder grants additional roots; the other fails closed and takes over once the holder exits), panel primary-root authority derived from the host session (a client-named root is no longer accepted), DSH compatibility turned from a documented agreement into a **code contract enforced at startup** (an exact allowlist, mixed-install detection, a `src/compat/` adapter layer — see the "Upgrade Notes" in the [CHANGELOG](./CHANGELOG.en.md)), and **an additional root's own `AGENTS.md` / `CLAUDE.md` reaching the model** — native instruction discovery walks upward from the session cwd, so it can never reach an additional root.
-
-**Done and released: `v0.1.2`** — with the `v0.1.1` contract unchanged, the supported upstream runtimes grow to `0.1.6-alpha.2` and `0.1.7-alpha.1` (the latter needs adapters for session format 4, in-process `PluginPackages`, bash `execute().result()`, and more); it also fixes the Workspace Folders panel on `0.1.6-alpha.2`, where dropping `current` from the Session catalog wrongly showed "No active session". See the [CHANGELOG](./CHANGELOG.en.md).
+## What & Why
 
-**Done and released: `v0.1.3`** — with the `v0.1.2` contract unchanged, the supported upstream runtimes grow to `0.1.7-alpha.2` and `0.1.7-rc.1` (same shapes as `0.1.7-alpha.1`, no new adapter branch; from `rc.1`, install time enforces an exact `peerDependencies` match against the host runtime). See the [CHANGELOG](./CHANGELOG.en.md).
+DSH (DeepSeek Harness) natively treats only the directory a session starts in as the agent's sole writable root; this plugin is an out-of-tree extension that modifies no upstream code and widens that scope to "**one primary root + N additional roots**".
 
-**Done and released: `v0.1.4`** — with the `v0.1.3` contract unchanged, the supported upstream runtimes grow to `0.1.7-rc.2` (same shapes as `0.1.7-rc.1`, no new adapter branch; cordis stays at `~4.0.4`). See the [CHANGELOG](./CHANGELOG.en.md).
+A real development project is usually several independent Git repositories, and working across them meant juggling sessions. Peer harnesses already treat this as standard: Codex offers `--add-dir`, and Cursor lets you add folders to a workspace. This plugin brings the same capability to DSH — register the other repositories as additional roots, and the agent can read and write them directly.
 
-**`v0.1.5` is released**. This development branch contains unreleased support for DSH `0.2.1-alpha.1` / `0.2.1-alpha.2`, separation of dynamic cwd from Session origin, and LSP, Windows ACL, additional-root file browsing, and Worktree capabilities. These changes are proposed for `v0.1.6`; see the [roadmap ledger](./docs/plans/active/2026-09-12-multi-root-workspace.md) for release status.
+- **Zero learning cost for the agent**: it keeps using the native `read` / `write` / `edit` / `bash` tools — the plugin adds no new tools at all, it only grants more directories.
+- **Security does not degrade**: additional roots are authorized through the same mechanism the harness already uses — an in-process filesystem fence plus kernel-level sandboxes (macOS Seatbelt / Linux bwrap / Landlock / Windows ACL), with files and bash sharing one and the same scope. It never degenerates into full access or prompt-level constraints.
+- **Absent when absent**: with no additional root configured, its behavior is item-for-item identical to an uninstalled harness; every misconfiguration fails loudly instead of silently degrading.
 
-The single source of truth for progress, numbering, and release state is the [roadmap progress ledger](./docs/plans/active/2026-09-12-multi-root-workspace.md#进度总账) (M1–M4 are the MVP milestone numbers, H1–H4 are the `v0.1.1` batch numbers, and H1 is M4); per-item evidence lives in the [completed plans](./docs/plans/README.md), and the user-visible changes of each version are in the [CHANGELOG](./CHANGELOG.en.md).
+Current released version: `v0.1.8`. The user-visible changes of each version live in the [CHANGELOG](./CHANGELOG.en.md); progress and release state live in the [roadmap progress ledger](./docs/plans/active/2026-09-12-multi-root-workspace.md#进度总账).
 
 ## Quick Start
 
-With a DSH runtime at hand (web / Electron desktop / headless all work), the shortest path is two commands — the plugin is published on [npm](https://www.npmjs.com/package/@dsh-electron/dsh-plugin-multi-root-workspace):
+The plugin is published on [npm](https://www.npmjs.com/package/@dsh-electron/dsh-plugin-multi-root-workspace). You can paste the package name `@dsh-electron/dsh-plugin-multi-root-workspace` into DSH's plugin install page, or install it in two commands:
 
 ```sh
 dsh plugin --profile web add @dsh-electron/dsh-plugin-multi-root-workspace
 dsh --profile web
+# pick the --profile for how you launch DSH; see its docs for the values
 ```
 
 Once it is up, the **Folders** action (`🗂`) appears at the sidebar foot — or, straight in a session:
 
 ```text
-/workspace-folders add ~/code/another-repo
+/workspace-folders add ~/code/another-repo [--inherit|--read-only|--read-write]
 ```
 
-The agent can now read, write, and run bash in that directory, with the same rights as this session's workspace. Other install sources (the GitHub repository / a local clone) and the command differences of running DSH from a source checkout are covered under [Installation](#installation).
+The agent can now read, write, and run bash in that directory — the default is `inherit`, so the access level follows the session mode. Other install options (tarball, GitHub, a local clone) are covered under [Installation](#installation).
 
 ## Requirements
 
-- **Using a plugin built from this checkout**: you need a *supported* DSH runtime — currently **`0.1.5-rc.2`, `0.1.6-alpha.1`, `0.1.6-alpha.2`, `0.1.7-alpha.1`, `0.1.7-alpha.2`, `0.1.7-rc.1`, `0.1.7-rc.2`, `0.2.0-rc.1`, `0.2.0-rc.2`, `0.2.1-alpha.1`, and `0.2.1-alpha.2`**, and nothing else will install or run (see below). `dsh plugin` installs the package into the matching profile, and no local Node toolchain is required
-- **Building from source / contributing**: **Node.js** `^22.19.0 || >=24` (pinned by the repository's `engines`), **Git**, and **pnpm 11** (`packageManager` pins `pnpm@11.25.0`; corepack recommended)
-- **DSH runtime**: the dev pin is exactly `0.2.1-alpha.2`, the baseline among the supported releases; the upgrade procedure lives in the [development workflow](./docs/development/plugin-development-workflow.md)
-- **Platforms**: macOS Seatbelt and Linux bwrap/Landlock; the development branch also implements a Windows root-set ACL runner. Platform validation is recorded in the [roadmap](./docs/plans/active/2026-09-12-multi-root-workspace.md#b1b3第二期-p12026-10-02).
-- Running the smoke tests needs **no model credentials**: the e2e model turns are served by an inline scripted model endpoint
+**Using the plugin**: a DSH runtime at exactly one of the versions below — an exact match, not a range. `dsh plugin` handles the install; no local Node toolchain is needed.
+
+| DSH line | Supported releases |
+| --- | --- |
+| `0.1.5` | `0.1.5-rc.2` |
+| `0.1.6` | `0.1.6-alpha.1`, `0.1.6-alpha.2` |
+| `0.1.7` | `0.1.7-alpha.1`, `0.1.7-alpha.2`, `0.1.7-rc.1`, `0.1.7-rc.2` |
+| `0.2.0` | `0.2.0-rc.1`, `0.2.0-rc.2` |
+| `0.2.1` | `0.2.1-alpha.1`, `0.2.1-alpha.2`, `0.2.1-alpha.3`, `0.2.1-alpha.4`, `0.2.1-alpha.5`, `0.2.1-rc.1`, `0.2.1-rc.2` |
+
+The plugin does not start — as if it were not installed — when the DSH release is not in the table or the `@deepseek-ai/dsh-*` packages disagree on a version.
 
-**The supported DSH versions are an exact list, not a range.** This plugin replaces `ctx.fs` and `ctx.sandbox` — the security boundary itself — and it recognizes kernel sandbox dialects from argv shapes measured against specific upstream releases. So `peerDependencies` names only the releases that have actually been through the full verification, and startup checks again: if the host's release is not on the list, or several `@deepseek-ai/dsh-*` packages disagree about which release they are, the fs / sandbox / registry / instructions / lsp / workspace-files rows **do not start**, the composition degrades to "this plugin is not installed", and one explanatory line is logged. To diagnose, see [troubleshooting: unsupported DSH release](./docs/troubleshooting/unsupported-dsh-release.md); for the reasoning, [ADR-0009](./docs/decisions/ADR-0009-dsh-compat-contract.md).
+**Building from source / contributing**: Node.js `^22.19.0 || >=24`, pnpm `11.25.0` (enable via corepack); the dev-pinned DSH is `0.2.1-rc.2`.
+
+**Platforms**: macOS (Seatbelt), Linux (bwrap / Landlock), Windows (root-set ACL runner).
 
 ## Installation
 
@@ -61,19 +60,19 @@ The agent can now read, write, and run bash in that directory, with the same rig
 
 | Source | Command | Notes |
 | --- | --- | --- |
-| npm registry (recommended) | `dsh plugin --profile web add @dsh-electron/dsh-plugin-multi-root-workspace` | Pre-built artifacts, ready to use; the first `add` needs one `allowBuilds` answer (below) |
-| tarball | `dsh plugin --profile web add ./dsh-electron-dsh-plugin-multi-root-workspace-<version>.tgz` | Pre-built offline package, handy for air-gapped or offline delivery — with the same one-time `allowBuilds` answer |
-| local path | `dsh plugin --profile web add /path/to/package/dsh-plugin-multi-root-workspace` | pnpm `link:` to a local checkout; its dependencies are already installed in this repository — best for development |
-| GitHub / git | `dsh plugin --profile web add github:cherrchen/dsh-plugin-multi-root-workspace` | Pulls source and builds it on the spot through `prepare`; needs **two** `allowBuilds` answers (this package plus `koffi`); pin a tag |
+| npm registry (recommended) | `dsh plugin --profile web add @dsh-electron/dsh-plugin-multi-root-workspace` | Pre-built artifacts, ready to use |
+| GitHub | `dsh plugin --profile web add github:cherrchen/dsh-plugin-multi-root-workspace` | Builds automatically from source on install; `allowBuilds` must name this package too — pin a version |
+| tarball | `dsh plugin --profile web add ./dsh-electron-dsh-plugin-multi-root-workspace-<version>.tgz` | Pre-built offline package, handy for air-gapped or offline delivery |
+| From source | `dsh plugin --profile web add /path/to/package/dsh-plugin-multi-root-workspace` | pnpm `link:` to a local checkout — best for development; no `allowBuilds` needed |
 
-**Every install source needs one `allowBuilds` answer the first time.** The plugin carries a native dependency that must be built, `koffi` (the FFI wrapper behind Registry Authority on Windows; installed but unused elsewhere), and pnpm ≥10 runs no dependency lifecycle script by default. So the first `dsh plugin add` fails with `[ERR_PNPM_IGNORED_BUILDS]` and leaves the pending decision in that profile's `pnpm-workspace.yaml`:
+**The first `dsh plugin add` fails with `[ERR_PNPM_IGNORED_BUILDS]`**: add the following line to that profile's `pnpm-workspace.yaml`, then run `add` again:
 
 ```yaml
 allowBuilds:
-  koffi: true          # the placeholder dsh leaves is "set this to true or false"
+  koffi: true
 ```
 
-Set it to `true` and run `add` again. Read that line as **letting the dependency's install script run on your machine** (outside any sandbox the agent runs in) — `koffi`'s script only precompiles locally. Diagnosis steps: [Troubleshooting: the install stops at build approval](./docs/troubleshooting/install-stops-at-build-approval.md).
+If the retry exits 0 but the plugin never lands in `dsh.profile.bundles`, do a `remove` + `add`. Further diagnosis: [troubleshooting](./docs/troubleshooting/install-stops-at-build-approval.md).
 
 ### Install from npm (recommended)
 
@@ -81,18 +80,18 @@ Set it to `true` and run `add` again. Read that line as **letting the dependency
 dsh plugin --profile web add @dsh-electron/dsh-plugin-multi-root-workspace
 ```
 
-This installs pre-built artifacts (the plugin itself is never compiled), but the first install still needs the `allowBuilds` answer above.
+This installs pre-built artifacts; the first install needs the `allowBuilds` addition described above.
 
 ### Install from a tarball
 
 ```sh
 pnpm pack @dsh-electron/dsh-plugin-multi-root-workspace
 # or download the tgz from the GitHub Release assets, e.g.:
-# https://github.com/cherrchen/dsh-plugin-multi-root-workspace/releases/download/v0.1.5/dsh-electron-dsh-plugin-multi-root-workspace-0.1.5.tgz
-dsh plugin --profile web add ./dsh-electron-dsh-plugin-multi-root-workspace-0.1.5.tgz
+# https://github.com/cherrchen/dsh-plugin-multi-root-workspace/releases/download/v0.1.8/dsh-electron-dsh-plugin-multi-root-workspace-0.1.8.tgz
+dsh plugin --profile web add ./dsh-electron-dsh-plugin-multi-root-workspace-0.1.8.tgz
 ```
 
-Also pre-built (the plugin itself is never compiled here), handy for air-gapped or offline delivery — and the first `add` needs the same `allowBuilds` answer.
+Also pre-built, handy for air-gapped or offline delivery; the first install needs the same `allowBuilds` addition.
 
 ### Install from GitHub
 
@@ -100,7 +99,7 @@ Also pre-built (the plugin itself is never compiled here), handy for air-gapped
 dsh plugin --profile web add github:cherrchen/dsh-plugin-multi-root-workspace
 ```
 
-With pnpm ≥10 the first `add` fails: a git install pulls **source code rather than build artifacts**, so the package's self-contained `prepare` script must build it on the spot (a direct transpile of `src/`, no type-checking). Follow `dsh`'s guidance and copy the exact package keys pnpm prints into the profile's `pnpm-workspace.yaml` — this source has **two** pending decisions:
+A GitHub install fetches source code and builds it automatically during `add` — no manual build needed — but `allowBuilds` has to cover two entries, this package itself and `koffi`:
 
 ```yaml
 allowBuilds:
@@ -108,93 +107,155 @@ allowBuilds:
   koffi: true
 ```
 
-Then run `add` again. Pinning a tag (e.g. `#v0.1.5`) is recommended so a later push cannot silently change what actually runs:
+Pinning a version (e.g. `#v0.1.8`) is recommended so a later push cannot silently change what actually runs:
 
 ```sh
-dsh plugin --profile web add github:cherrchen/dsh-plugin-multi-root-workspace#v0.1.5
+dsh plugin --profile web add github:cherrchen/dsh-plugin-multi-root-workspace#v0.1.8
 ```
 
-### Install from a local clone (development & debugging)
+### Install from a local clone
 
 ```sh
 git clone https://github.com/cherrchen/dsh-plugin-multi-root-workspace.git
 cd dsh-plugin-multi-root-workspace
-export CI=true    # without a TTY, pnpm's dependency self-check aborts; see the development workflow §8
+export CI=true
 pnpm install
-pnpm build        # produces lib/ (not tracked by Git); the artifact test and installation both need it
-dsh plugin --profile web add "$PWD"
+pnpm build
+dsh plugin --profile web add /path/to/repo
 ```
 
-> **Tip**: if your DSH comes from a source checkout (rather than `npm install -g @deepseek-ai/deepseek-harness`), the `dsh` binary is not on the global PATH — replace `dsh` with `pnpm dsh` in the commands above, e.g. `pnpm dsh plugin --profile web add ...` and `pnpm dsh --profile web`.
+> [!TIP]
+> If `dsh` is not on your PATH (e.g. you run DSH from a source checkout), use `pnpm dsh` instead.
 
 ## Running
 
-Development gates, with the result each step should produce:
+Development gates:
 
 ```sh
-pnpm lint && pnpm typecheck   # expect: 0 warnings, 0 errors; both tsconfigs pass
-pnpm test                     # expect: all pass; dialect cases without a local kernel runner skip explicitly, with a reason
-pnpm kernel:probe             # expect: reports the kernel runners this host has (seatbelt / bwrap / landlock)
-pnpm smoke                    # expect: compose 40/40, behavior 99/99, journey 55/55
-pnpm docs:check               # expect: 0 errors, 0 warnings
+pnpm lint && pnpm typecheck
+pnpm test
+pnpm kernel:probe
+pnpm smoke
+pnpm docs:check
 ```
 
 Install into a DSH runtime and verify the composition:
 
 ```sh
-dsh plugin --profile web add "$PWD"
-dsh --profile web --dump-config
+dsh plugin --profile web add /path/to/repo
+dsh --profile web --dump-config | grep -A3 'multi-root'
+```
+
+Expected output:
+
+```text
+# == @deepseek-ai/dsh-base, patched by @dsh-electron/dsh-plugin-multi-root-workspace
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'
+  disabled: true
+--
+# == @deepseek-ai/dsh-base, patched by @dsh-electron/dsh-plugin-multi-root-workspace
+- id: fs-sandbox
+  name: '@deepseek-ai/dsh-fs-sandbox'
+  disabled: true
+--
+# == @dsh-electron/dsh-plugin-multi-root-workspace
+- id: multi-root-compat
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/compat'
+- id: multi-root-fs
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/fs'
+- id: multi-root-sandbox
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/sandbox'
+- id: multi-root-providers
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/providers'
+- id: multi-root-scope
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/scope'
+  config:
+    toolAccess: {}
+- id: multi-root-registry
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/registry'
+  config:
+    leasePath: !!js dshHomePath('storages/multi_root_workspace.lock')
+    maxAdditionalRoots: 16
+- id: multi-root-instructions
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/instructions'
+  config:
+    maxBytes: 65536
+- id: multi-root-lsp
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/lsp'
+- id: multi-root-workspace-files
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/workspace-files'
+- id: multi-root-command
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace/command'
+- id: multi-root-client
+  name: '@dsh-electron/dsh-plugin-multi-root-workspace'
 ```
 
-Expected: **only** the `fs-sandbox` and `sandbox` rows are replaced by the plugin's `multi-root-fs` / `multi-root-sandbox`, with ten rows inserted (`multi-root-compat` / `fs` / `sandbox` / `scope` / `registry` / `instructions` / `lsp` / `workspace-files` / `command`, plus the client carrier row `multi-root-client`); `bash-sandbox` stays upstream (bash and the PTY backend take their roots from `ctx.sandbox`). After starting `dsh --profile web`, the Folders action appears at the sidebar foot.
+The upstream `fs-sandbox` and `sandbox` rows are disabled and taken over by the plugin's same-named services, and all the plugin's `multi-root-*` rows are mounted. After startup, a **Folders** action appears at the sidebar foot.
 
 ## Usage
 
-**The command** (the text entry point; also available headless):
+### Command
 
 ```text
-/workspace-folders                       # list the primary root and the additional roots
-/workspace-folders add <absolute path>   # with no path, opens the OS directory chooser
-/workspace-folders alias 1 payments      # name the first additional root
-/workspace-folders remove 1              # by ordinal or by path
-/workspace-folders reveal 1              # show it in the file manager
+/workspace-folders [list]                                                    # list the primary root and the additional roots (access and state included)
+/workspace-folders add <absolute path> [--inherit|--read-only|--read-write]  # no path opens the OS directory picker; new registrations default to inherit
+/workspace-folders access <n|path> inherit|read-only|read-write              # switch access (widening requires the root to be available right now)
+/workspace-folders alias <n|path> [name]                                     # omitting the name clears the alias
+/workspace-folders remove <n|path>                                           # n is the number list prints
+/workspace-folders reveal <n|path>                                           # show it in the file manager
+/workspace-folders isolate-profiles [--apply]                                # inspect profile import method and multi-link files under $DSH_HOME; --apply writes copy config
+/workspace-folders help                                                      # show the command help
 ```
 
-After an `add`, `list` prints:
+Paths may be quoted; a path that duplicates an existing root, nests inside one, or is the workspace root itself is rejected.
+
+Access is three-state ([ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md); the [usage guide](./docs/guide/README.en.md#access-levels-the-root-limit-and-per-tool-caps) has the exact semantics): `inherit` follows the session mode — writable under `workspace-write`, refused under `read-only`, unrestricted under `danger-full-access`; `read-only` refuses writes in every mode, including Full-access; a fixed `read-write` root stays writable even in a read-only session. Writable records registered by older plugin versions read back as `inherit`. A primary root accepts at most 16 additional roots (`maxAdditionalRoots` can raise it to 64). A host may also cap a tool for all additional roots via `toolAccess` on the `multi-root-scope` row — e.g. `{ bash: 'read-only' }` keeps bash from ever writing an additional root (it can still write the primary root).
+
+After an `add`, `list` prints (a `workspace-write` session, with `website` registered read-only):
 
 ```text
 Workspace root (primary; access follows the current sandbox mode): /home/me/monorepo
-  1 /home/me/payments-service [payments]
-  2 /home/me/website
-Writable additional roots: 2 of 2.
+  1 /home/me/payments-service [payments] (inherit)
+  2 /home/me/website (read-only)
+2 of 16 additional roots.
+Writable additional roots under the current mode: 1 of 2.
 ```
 
-**The panel** (Web GUI): the **Folders** dialog at the sidebar foot lists the primary root and the additional roots, and offers add (through the composed directory picker or a typed path), remove, alias, copy path, reveal in the file manager, and move up/down. Its copy is bilingual and follows the interface language. A root's state is shown honestly: `missing` (absent right now) and `redirected` (replaced by a symlink pointing elsewhere) keep their registration but are **not granted**; once the directory is back, a `list` or a panel refresh grants it again — no restart.
+### Panel
+
+The **Folders** dialog at the sidebar foot lists the primary root and the additional roots, and offers add, remove, alias, read-only/read-write switching, copy path, reveal in the file manager, and move up/down.
 
-**The model side**: the additional-root topology reaches the model through a `systemPrompt.context` snapshot attached to every request (same workspace, cwd unchanged) — no introspection tool needed. The full authorization semantics (canonicalization, `recordedPath` against symlink transplants, conflict rejection) live in the [architecture document](./docs/architecture/multi-root-workspace.md).
+### Model side
+
+The additional-root topology is injected into the system prompt so the model knows which directories are available, and the information updates when grants change. No new tool needs to be exposed to the model.
 
 ## Project Structure
 
 ```text
-src/
-  roots.ts        pure rules: canonicalization, conflict validation, record classification (available/missing/redirected/invalid)
-  registry.ts     the root registry: dsh-storage-domain persistence, mutations of one primary root serialized in one queue
-  registry-lease.ts / registry-lease-win32.ts
-                  cross-process Registry Authority: POSIX flock and a Windows named semaphore (the kernel releases it on process death)
-  scope.ts        ctx.multiRootScope: the single authorization source, plus the model-visible topology snapshot
-  fs.ts           the multi-root filesystem provider (in-process fence, extends the upstream LocalFileSystem)
-  sandbox.ts      the multi-root kernel-sandbox provider (extends the upstream LocalSandboxProvider)
-  dialects.ts     Seatbelt / bwrap / Landlock profile recognition and additional-grant assembly (unrecognized shapes fail loudly)
-  containment.ts  path containment (lexical fast path plus a dev/ino alias fallback)
-  instructions.ts discovery, incremental delivery, budget and revocation for an additional root's AGENTS.md / CLAUDE.md (top level plus the subdirectories this session touched, injected from agent/pre-step)
-  compat.ts       the multi-root-compat startup gate (version allowlist and mixed-install detection)
-  compat/         the version-difference adapters: dsh-version / sandbox-confine / agent-instructions / llm-message (optional peers loaded on demand)
-  command.ts      the /workspace-folders command and the host half of the panel RPC
-  contract.ts     the panel wire protocol (zod-validated on both ends, inlinable into the browser bundle)
-  client/         the browser half: sidebar action, dialog, bilingual dictionaries
-tests/            differential parity, real-execution dialect matrix, contract round-trips, component and locale gates, cross-process lease e2e, instruction injection
-scripts/          smoke batteries (compose / behavior / journey) plus the docs, kernel-runner, compatibility-contract and upgrade checks
-docs/             requirements, architecture, decision records (ADRs), plans, development workflow
+.
+├── src/
+│   ├── roots.ts                      pure rules: canonicalization, conflict validation, record classification (available/missing/redirected/invalid)
+│   ├── registry.ts                   the root registry: dsh-storage-domain persistence, mutations of one primary root serialized in one queue
+│   ├── registry-lease.ts             cross-process Registry Authority: POSIX flock (the kernel releases it on process death)
+│   ├── registry-lease-win32.ts       ditto, the Windows named-semaphore implementation
+│   ├── scope.ts                      ctx.multiRootScope: the single authorization source, plus the model-visible topology snapshot
+│   ├── fs.ts                         the multi-root filesystem provider (in-process fence, extends the upstream LocalFileSystem)
+│   ├── sandbox.ts                    the multi-root kernel-sandbox provider (extends the upstream LocalSandboxProvider)
+│   ├── dialects.ts                   Seatbelt / bwrap / Landlock profile recognition and additional-grant assembly (unrecognized shapes fail loudly)
+│   ├── windows-*.ts                  the Windows root-set ACL runner and restricted-token execution
+│   ├── containment.ts                path containment (lexical fast path plus a dev/ino alias fallback)
+│   ├── instructions.ts               discovery, incremental delivery, budget and revocation for an additional root's AGENTS.md / CLAUDE.md (top level plus the subdirectories this session touched, injected from agent/pre-step)
+│   ├── lsp.ts                        a separate LSP workspace initialized per additional root
+│   ├── workspace-files.ts            host-side routing and confinement for additional-root file browsing in the Files tab
+│   ├── compat.ts                     the multi-root-compat startup gate (version allowlist and mixed-install detection)
+│   ├── compat/                       the version-difference adapters: dsh-version / sandbox-confine / agent-instructions / llm-message, etc. (optional peers loaded on demand)
+│   ├── command.ts                    the /workspace-folders command and the host half of the panel RPC
+│   ├── contract.ts                   the panel wire protocol (zod-validated on both ends, inlinable into the browser bundle)
+│   └── client/                       the browser half: sidebar action, the Folders dialog, the Files-tab root switcher, bilingual dictionaries
+├── tests/                            differential parity, real-execution dialect matrix, contract round-trips, component and locale gates, cross-process lease e2e, instruction injection
+├── scripts/                          smoke batteries (compose / behavior / journey) plus the docs, kernel-runner, compatibility-contract and upgrade checks
+└── docs/                             requirements, architecture, decision records (ADRs), plans, development workflow
 ```
 
 ## Contributing
@@ -213,8 +274,11 @@ Issues and PRs are welcome:
 - Single writer per store: only one DSH process at a time may hold the root registry for a given `$DSH_HOME`; another process reports the registry as unavailable (`registry-contended`) and takes over on refresh once the holder exits or crashes. That is deliberate fail-closed behavior, not a race waiting to be fixed ([ADR-0007](./docs/decisions/ADR-0007-registry-authority-lease.md)).
 - The supported matrix is an exact-version allowlist: on a host whose release is not on the list, or whose core packages disagree about the release, the `fs` / `sandbox` / `registry` / `instructions` / `lsp` / `workspace-files` rows **do not start** and the composition degrades to "the plugin is not installed" ([ADR-0009](./docs/decisions/ADR-0009-dsh-compat-contract.md)).
 - The Windows multi-root runner inherits upstream partial enforcement, caller-owned directory requirements, and private-temp isolation. Running processes retain their initial roots; later processes use the updated set ([ADR-0011](./docs/decisions/ADR-0011-multi-root-workspace-consumers.md)).
-- An additional root has the same rights as the primary root (no per-root read-only), and cannot become the default working directory of bash/PTY (session cwd semantics are unchanged).
-- Browse additional roots in the Workspace Folders dialog with manual refresh, expandable directories, and previews of up to 200 text lines. The native primary-root Files tab remains and offers a dialog action where supported. LSP uses the containing additional root as its own workspace; the host must configure the relevant language server ([ADR-0011](./docs/decisions/ADR-0011-multi-root-workspace-consumers.md)).
+- **Network and device paths cannot be additional roots on Windows**: UNC (`\\server\share`), `\\?\`, `\\.\`, and mapped network drives are rejected at registration with `unsupported-path` — the restricted token's capability SID cannot be shown to bind SMB access ([ADR-0011 amendment](./docs/decisions/ADR-0011-multi-root-workspace-consumers.md)).
+- **The confined Windows shell is pwsh; Git Bash is not available**: MSYS cannot start under the write-restricted Low-integrity token (identically under the upstream and plugin runners — an upstream limitation). An upstream-confined child also cannot receive Ctrl+C (it inherits the runner's ignore flag); under the plugin runner Ctrl+C reaches the child and the runner mirrors its exit code.
+- Additional-root access is three-state: new registrations default to `inherit` (they follow the session mode), `--read-only` refuses writes in every mode (including Full-access), and a fixed `--read-write` stays writable even in a read-only session — it is a question of write authority, never read confinement ([ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)). A running process or persistent terminal keeps the deny set it was started with — a terminal started before a root turned read-only stays unrestricted until restarted; cap and access changes constrain only later calls and new processes ([ADR-0013](./docs/decisions/ADR-0013-per-root-and-per-tool-access.md)); hosts with workingDirectory may use an additional root as the execution directory for later tools, while the session origin and registry identity stay unchanged ([ADR-0012](./docs/decisions/ADR-0012-session-origin-and-effective-cwd.md)).
+- **On Linux hosts where upstream selected Landlock, a restricted Full-access needs bubblewrap**: Landlock's allowlist cannot express "everything writable except these roots", so that combination selects bwrap to spell the deny boundary; on a host without a usable bwrap (not installed, or unprivileged user namespaces disabled), a Full-access command that carries any deny boundary (a read-only root, or the protected `$DSH_HOME`) fails closed at launch. Enable bwrap there, or avoid explicit read-only roots under Full-access on such hosts ([ADR-0017](./docs/decisions/ADR-0017-three-state-root-access-and-sandbox-modes.md)).
+- Browse additional roots from the **Files tab's root switcher**: the header entry lists the primary root and every additional root, with the selected root's full path still shown beside it; selecting one lets a byte-for-byte fork of the upstream Files tree take over the tree area (lazy-loaded directories, native rows and icons, watch-driven auto-refresh, file clicks opening in the host viewer, plus a manual refresh in the header's reload spot), and the header's open-in-app button is simultaneously replaced by a byte-for-byte fork of the upstream control that opens the selected root instead of the primary one; switching back to the primary root restores the native view. The dialog is management-only again. The takeover relies on upstream `data-*` DOM hooks and degrades silently to the native look when they stop matching ([ADR-0015](./docs/decisions/ADR-0015-files-tab-plugin-owned-browsing.md), [ADR-0016](./docs/decisions/ADR-0016-files-tab-native-tree-fork.md)). LSP uses the containing additional root as its own workspace; the host must configure the relevant language server ([ADR-0011](./docs/decisions/ADR-0011-multi-root-workspace-consumers.md)).
 - The command's own output text is English (a host-side handler has no active locale to consult); the panel is bilingual.
 - The Workspace Folders panel is a sidebar footer action plus a dialog rather than a full panel: `sidebar.footer.action` is offered by every supported release, whereas `sidebar.panellist` / `main` are not.
 
@@ -223,6 +287,7 @@ Issues and PRs are welcome:
 Long-term project documentation lives in [`docs/`](./docs/README.md):
 
 - [Changelog](./CHANGELOG.en.md)
+- [User guide](./docs/guide/README.en.md)
 - [Requirements](./docs/requirements/multi-root-workspace.md)
 - [Target architecture](./docs/architecture/multi-root-workspace.md)
 - [Upstream research](./docs/reference/multi-root-workspace-research.md)
@@ -236,5 +301,3 @@ Repository-wide rules for Coding Agents are defined in [`AGENTS.md`](./AGENTS.md
 ## License
 
 [MIT](./LICENSE)
-
-Dynamic working directories affect relative path resolution and new processes. They do not grant access or change the session origin that owns the root registry. See [ADR-0012](./docs/decisions/ADR-0012-session-origin-and-effective-cwd.md).