@tiphareth/dsh-hardssh 0.1.2 → 0.2.3

package/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, tiphareth0
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,50 +1,77 @@
-# dsh-hardssh — SSH 远程工作区 + SSH 运维插件
-
-在 DSH Web GUI 中提供两块能力（原 `dsh-ssh` 插件已整体并入本包并删除，单包单引擎）：
-
-1. **SSH 运维**：侧边栏「SSH」入口 → 主机管理面板（增删改查 / `~/.ssh/config` 导入 / 连接测试）、Web 终端（xterm + WebSocket PTY）、文件上传下载、本地端口转发隧道、集群并发执行；`ssh_list` / `ssh_exec` / `ssh_upload` / `ssh_download` / `ssh_tunnel` / `ssh_cluster` 六个 Agent 工具；主机配置存 `~/.dsh/dsh-ssh.json`。
-2. **SSH 工作区**：会话头部按钮进入 SSH 模式，左侧出现远程文件树面板；本地 harness 的 fs/subprocess 经接缝门面透明路由到远程主机执行（read/write/edit/bash 在 SSH 模式下即远程操作）；`remote_*` 九个 Agent 工具用于显式操作。
-
-## 架构
-
-- **单一共享实例**：`HostStore` + `SshEngine`（ssh2 连接池）在 `src/index.ts` 创建一次，SSH 运维与 SSH 工作区共用同一引擎 —— 配置变更（PATCH/DELETE）同时失效所有连接，无双池问题。
-- **接缝切换**：`cordis.patch.yml` 禁用部署自带的 `fs-sandbox` / `subprocess` 行，由 `dsh-hardssh/fs`、`dsh-hardssh/subprocess` 提供模式路由门面（本地 = 沙箱化原实现；远程 = SFTP/SSH 实现）。
-- **REST**：`/api/dsh-ssh`（运维路由，loopback-only）+ `/api/dsh-hardssh`（工作区路由，loopback-only）。兼容协议名（`/api/dsh-ssh`、`dsh-ssh` settings namespace、`plugin:dsh-ssh` 提示词段）刻意保留，不改名。
-- **工作区核心服务**：`ctx.hardsshCore` / `ctx.sshWorkspaceCore` 指向同一 core（ledger + engine + runner），供 `dsh-workbench-tiphareth`（四列 IDE）消费。
-
-## 安装
-
-```sh
-# profile 机制，热插拔；需重启 dsh
-dsh plugin --profile <name> add link:<repo>/packages/dsh-hardssh
-```
-
-## 开发
-
-```sh
-# 改码后一键同步 + 验证（build → 同步 profile 插件快照 → 独立实例启动验证）
-pwsh scripts/sync-verify.ps1
-# 单测 / 类型 / 构建
-pnpm --filter dsh-hardssh typecheck
-pnpm --filter dsh-hardssh test
-pnpm --filter dsh-hardssh build
-```
-
-> 注意：profile 的插件依赖是 `file:` 安装副本，pnpm install 会把它重建为指向源码的
-> junction（会让 DSH 平台 peer 解析断链）。日常改码后**只跑 sync-verify.ps1**（复制快照 +
-> 验证），不要跑 pnpm install；仅当 profile package.json 依赖声明变化时才 install，
-> 之后必须重跑 sync-verify 恢复快照。
-
-## 安全模型
-
-- `/api/dsh-ssh/*` 与 `/api/dsh-hardssh/*` 仅限 loopback（含同源校验）。
-- 认证材料沿用 `~/.dsh/dsh-ssh.json`（0600 / 0700），不新增存储。
-- 路径 gate：远程操作 root 必须等于 resolved remoteRoot；相对路径禁止 `..`。
-- 远程操作消耗真实远程资源：工具描述与宣告段明确「先确认再执行」；grep/glob 限深限条数。
-- SSH 模式下本机沙箱不对远程执行生效（远程进程无法被本地内核沙箱约束）——门面的 `sandboxMode` 在远程模式报告 `undefined`。
-
-## 已知限制
-
-- SSH 模式下 `pwsh` 工具在 POSIX 远程主机上不可用（请用 bash 语义命令或 `ssh_exec`）。
-- 远程 grep/glob/realpath 依赖 GNU find/grep/coreutils（-printf / -mz / base64 -w0）；限深 4~6 层、限 200 条。
-- 断线重连沿用引擎语义；传输/执行消耗真实远程资源，先确认再操作。
+# dsh-hardssh — SSH 远程工作区 + SSH 运维插件
+
+已适配 DSH **0.1.5**（实测内核 `0.1.5-rc.1`；本包版本 `0.2.3`）。在 DSH Web GUI 中提供两块能力（单包单引擎）：
+
+1. **SSH 运维**：右侧栏「SSH」Tab（从右侧栏标签条的「+」或右侧栏引导页入口打开）→ Web 终端（xterm + WebSocket PTY）、文件上传下载、本地端口转发隧道、当前服务器的远端命令；`ssh_list` / `ssh_exec` / `ssh_upload` / `ssh_download` / `ssh_tunnel` / `ssh_cluster` 六个 Agent 工具；主机配置存 `~/.dsh/dsh-ssh.json`。
+2. **SSH 工作区**：左侧侧栏的全局入口行 → 中央面板管理服务器与工作区（增删改查 / `~/.ssh/config` 导入）；绑定后本地 harness 的 fs/subprocess 经接缝门面透明路由到远程主机执行（read/write/edit/bash 在绑定会话中即远程操作）；`remote_*` 三个 Agent 工具（`remote_ls` / `remote_search` / `remote_status`）用于显式操作远端工作区。
+
+## 核心优势
+
+- **对插件零改动**：`cordis.patch.yml` 禁用部署自带的 `fs-sandbox` / `subprocess` 行，由本包提供路由门面。任何走标准 `ctx.fs` / `ctx.subprocess` 的插件与标准工具，在 SSH 工作区会话里自动运行在远端。
+- **通用工作区底座**：`WorkspaceRecord` / `Provider` / `Connection` / 能力契约 + Registry / Ledger / Router，与 SSH 解耦。SSH 只是一个 provider（如 `ssh`、`local`），可继续接 docker / wsl / 云 devbox，上层插件与 UI 不改；单一运行时，全链路读同一个台账。
+- **少数插件只需改几处接口**：给 agent 的执行手册见 [`SKILLS.md`](./SKILLS.md)——判定命令、接口对照表、可照抄代码与自检清单。
+
+## 架构
+
+- **单一共享实例**：`HostStore` + `SshEngine`（ssh2 连接池）在 `src/index.ts` 创建一次，SSH 运维与 SSH 工作区共用同一引擎 —— 配置变更（PATCH/DELETE）同时失效所有连接，无双池问题。
+- **接缝切换**：`cordis.patch.yml` 禁用部署自带的 `fs-sandbox` / `subprocess` 行，由 `dsh-hardssh/fs`、`dsh-hardssh/subprocess` 提供 provider 路由门面（本地 = 沙箱化原实现；远端 = 该 workspace 连接上的 `workspace.fs` / `workspace.process` capability）。
+- **REST**：`/api/dsh-ssh`（运维路由，loopback-only）+ `/api/dsh-hardssh`（工作区路由，loopback-only）。
+- **工作区核心服务**：`ctx.workspaceCore`（通用 WorkspaceCore：台账 + provider 路由 + capability 连接）是**唯一**的工作区运行时；`ctx.hardsshCore` 只保留 `hosts` + `engine` 供 SSH 专用集成消费（如四列 IDE 形态的 `dsh-workbench-tiphareth`）。
+- **公开入口**：`@tiphareth/dsh-hardssh/base`（通用底座实现）、`@tiphareth/dsh-hardssh/workspace`（平台无关类型面）。
+
+## 界面入口（全部走标准插件扩展点）
+
+插件不使用任何 DOM 注入；两个界面都是内核公开的槽位注册：
+
+| 界面 | 入口 | 槽位 |
+|---|---|---|
+| **SSH 工作区管理**（服务器 + 工作区增删改查，服务器行带已连接/未连接徽章） | 左侧侧栏「新会话」与「工作区」之间的全局入口行 → 中央面板 | `sidebar.panellist`（行）+ `main`（面板，key 同为 `dsh-hardssh-workspaces`） |
+| **SSH 运维**（终端 / 传输 / 隧道 / 当前服务器命令） | 右侧栏标签条的「+」或右侧栏引导页入口 | `ctx.sidebarRightTabs.register`（类型）+ `sidebar.right.pane.tab`（正文）+ `sidebar.right.pane.tab.title`（标签文字） |
+
+右侧栏 Tab 是 **page 类型**（不声明 `patterns`），只按 kind 打开，由用户从右侧栏自己的入口打开；插件不会强制展开右侧栏。右侧栏 Tab 实例是**每会话独立**的（内核的会话作用域语义），因此切换会话后需要重新打开该 Tab。
+
+## 会话绑定语义（操作台不选服务器）
+
+- 操作台的 SSH 目标由**当前会话的 `cwd`** 决定：最长匹配的 SSH 工作区锚点胜出，取该工作区的 `alias` 与 `remoteRoot`。终端 / 传输 / 隧道 / 命令四个子页都强制使用它，**不提供服务器下拉框**。
+- 会话在本地工作区（或未绑定任何 SSH 工作区）时，操作台不挂载任何操作组件，改为渲染**模糊蒙版**并提示「SSH 操作台仅适用于 SSH 工作区会话」。
+- 切换会话时操作台随 `Session → alias` 自动切换，并重置子页状态。
+- 数据源是公开的 `ctx.sessions.list`（`current` + `byId[id].cwd`）+ `WorkspaceManager` 快照，两者都可订阅，不存在第二份工作区句柄。
+
+## 连接行为
+
+- **启动/刷新只连接当前会话的服务器**：连接闸门在 `ctx.sessions.list` 的 `phase === 'ready'` 之前不建立基准，避免历史会话被误判为「新建会话」而逐台探测；本地会话不触发任何连接。
+- **非交互失败可见**：探测失败（网络不可达、认证失败、主机密钥异常、重试耗尽）会弹出「无法连接服务器」对话框并显示具体原因；用户主动取消密码/指纹弹窗不算失败。
+- **状态徽章只读**：左侧面板每 3 秒读取 `/api/dsh-ssh/connections`（连接池 live alias 列表）刷新「已连接 / 未连接」徽章，**不会**主动拨号。
+
+## 安装
+
+```sh
+# 已发布 npm（当前 0.2.3）：profile 机制，热插拔，需重启 dsh
+dsh plugin --profile <name> add @tiphareth/dsh-hardssh
+
+# 开发/迭代：源码链接（改码重建 lib/ 后重启即生效）
+dsh plugin --profile <name> add link:<repo>/packages/dsh-hardssh
+```
+
+## 开发
+
+在仓库根目录执行：
+
+```sh
+pnpm --filter dsh-hardssh typecheck   # 类型检查
+pnpm test                             # 默认测试套件（vault 加密用例已移出，约 12s）
+pnpm test:vault                       # 只跑 vault 用例（约 21s，scrypt 派生故意慢）
+pnpm --filter dsh-hardssh build       # 产出 lib/（构建前先清空，避免陈旧产物）
+```
+
+> profile 通过 `link:` 指向本包源码目录，因此改码后只需重新 `build`（产出 `lib/`）并重启
+> `dsh web` 即生效；不要把依赖改成 `file:` 安装副本，那会让 profile 加载一份快照而不是源码。
+
+## 安全模型
+
+- `/api/dsh-ssh/*` 与 `/api/dsh-hardssh/*` 仅限 loopback（含同源校验）。
+- 认证材料沿用 `~/.dsh/dsh-ssh.json`（0600 / 0700），不新增存储。
+- 路径 gate：远程操作 root 必须等于 resolved remoteRoot；相对路径禁止 `..`；`workspace.fs` / `workspace.process` capability 在解析后的 canonical 路径上再做一次 root 收敛（symlink 逃逸 fail closed）。
+- 远程操作消耗真实远程资源：工具描述与宣告段明确「先确认再执行」；`remote_search` 有深度与条数上限；`glob` / `grep` 在 SSH 会话里会被**显式拒绝**（本机 ripgrep 读不到服务器内容）并指向 `remote_search`。
+- SSH 模式下本机沙箱不对远程执行生效（远程进程无法被本地内核沙箱约束）：门面的 `sandboxMode` 委托本地后端的真实模式（`write` / `edit` 的沙箱升级入口据此注册），而远端世界的升级策略在门面处**显式丢弃**。
+- 凭据默认不落盘；`secretStorage: vault` 时以 AES-256-GCM + scrypt 加密存储于 `~/.dsh/ssh-secrets/dsh-ssh-vault.json`（被 fs seam 拒绝访问），且 `DSH_CREDENTIAL_PASSWORD` 自动解锁默认关闭（需 `vaultAutoUnlock: env`）。会话密码按**连接存活期**复用，连接池回收即失效。

package/SKILLS.md

@@ -0,0 +1,140 @@
+# SKILLS — 把任意 DSH 插件适配到 SSH 工作区
+
+> 写给 agent 的执行手册。目标：用**最少的接口替换**，让一个插件在 SSH 工作区及其 session 下正常工作。
+> 底座包：`@tiphareth/dsh-hardssh`（本包）。参考实现：`src/client/session-connect-gate.ts`、`src/client/ssh/session-target.ts`、`src/providers/ssh/provider.ts`。
+
+## 0. 先判断属于哪一类（决定要不要改）
+
+| 插件的做法 | 结论 |
+|---|---|
+| 通过 `ctx.fs` / `ctx.subprocess`（DSH 标准服务）或标准工具（read / write / edit / bash / pwsh…）访问文件与进程 | **0 改动**。seam 已被替换，路由自动生效 |
+| 依赖 **glob / grep** 做检索 | 这两个工具走**本机打包的 ripgrep**（不经 `ctx.fs`），在远端会话里读不到服务器内容、会被**显式拒绝**；远端检索改用 `remote_search`（`mode="glob"` / `mode="grep"`）、`remote_ls`、`ssh_exec` |
+| 直接 `import 'node:fs'` / `node:child_process`，或自建「本地/远端」状态、自建 workspace 句柄 | 需要改接口，按第 1～3 节替换 |
+
+判定命令（在插件源码根执行）：
+
+```sh
+rg -n "node:fs|node:child_process|from 'fs'|from 'child_process'|spawn\(|execFile\(" src
+rg -n "remote|isRemote|mode\s*[:=].*local" src
+```
+
+命中即按对应小节替换。
+
+## 1. 文件 / 进程：改用底座已替换的 seam
+
+**把** 直接的 Node 文件与进程调用 **改为** DSH 标准服务：
+
+| 现在 | 改为 | 导入 |
+|---|---|---|
+| `node:fs`、`node:fs/promises` | `ctx.fs`（`FileSystem`） | `@deepseek-ai/dsh-fs` |
+| `node:child_process`、`spawn`、`exec` | `ctx.subprocess`（`SubprocessRuntime`） | `@deepseek-ai/dsh-subprocess` |
+
+改完后 **不需要**任何 SSH / 远端分支：`dsh-hardssh` 已通过 `cordis.patch.yml` 把这两个 seam 替换为路由门面，按 session 的 cwd 决定本机还是远端。
+
+```ts
+// before
+import { readFile } from 'node:fs/promises'
+const text = await readFile(target, 'utf8')
+
+// after —— ctx.fs 是 DSH FileSystem：先 resolve 得到 FsTarget，再读写
+const file = await ctx.fs.resolve(target)      // 远端会话自动解析到远端
+const text = await ctx.fs.readText(file)
+await ctx.fs.writeText(file, next)
+
+// before
+import { execFile } from 'node:child_process'
+
+// after —— ctx.subprocess 是 DSH SubprocessRuntime：spawn 同步返回句柄，done 给结果
+const handle = ctx.subprocess.spawn({ argv: ['bash', '-lc', cmd], cwd })
+const outcome = await handle.done
+```
+
+## 2. 工作区身份：改用 `workspaceCore`，不要自建映射
+
+**把** 插件自己的「路径 → 远端 / 模式」映射与自建 workspace 句柄 **改为** 通用底座的查询接口：
+
+| 现在 | 改为 | 位置 |
+|---|---|---|
+| 自己维护 path→远端映射 | `ctx.workspaceCore.findByAnchor(path)` / `openByAnchor(path)` | 底座公开面 |
+| 需要「这个 cwd 属于哪个工作区」的连接 | `ctx.workspaceCore.openByAnchor(cwd)` → `WorkspaceConnection` | 同上 |
+| 自己的 workspace 句柄类型 | `WorkspaceCore` / `WorkspaceConnection` / `WorkspaceRecord` | `@tiphareth/dsh-hardssh/workspace` |
+| 自己实现的文件/进程能力契约 | `connection.get('workspace.fs' \| 'workspace.process' \| 'workspace.search')` | 同上 |
+
+```ts
+export const inject = ['workspaceCore']            // 声明依赖
+
+const record = await ctx.workspaceCore.findByAnchor(cwd)   // 未命中 → 本地
+if (record !== undefined) {
+  const connection = await ctx.workspaceCore.openByAnchor(cwd)
+  const remoteRoot = record.location.root                  // 远端根
+  const fs = connection?.get('workspace.fs')               // DSH FileSystem
+}
+```
+
+要点：
+
+- `findByAnchor` / `openByAnchor` 会先等待运行时就绪，是**首选**读写路径。
+- 已经持有连接时，用 `record.id` 走 `openById(record.id)` 复用同一条连接，不要重新按路径解析。
+- 需要在渲染热路径上做**同步**判断时，底座内部用的是 `core.router.fromAnchor(cwd)`（seam 门面即如此）。
+  该属性在 `WorkspaceCore` 上标注为**内部兼容面**（`@deprecated`），插件应优先用异步高阶层；
+  确实需要同步判定（例如渲染期不能 await）才使用它，并集中封装在一个适配函数里。
+- 未就绪或未命中时**不要**猜测：未命中即当本地处理；锚点目录下未注册的路径应 fail closed。
+- `WorkspaceRecord.provider.id` 是 provider 类型（`ssh` / `local` / …），用它做能力判断，**不要**用 alias 当身份。
+- SSH 工作区的服务器别名在 `record.provider.connectionRef.id`（`alias` 只是展示用）；远端根在 `record.location.root`。
+
+## 3. 注册新 provider（只有要接新后端时才做）
+
+**把** 自建的后端注册 **改为** 底座的 provider 契约：
+
+```ts
+const provider: WorkspaceProvider = {
+  manifest: {
+    id: 'docker', version: '1.0.0',
+    apiVersion: WORKSPACE_PROVIDER_API_VERSION,   // 当前 = 2
+    displayName: 'Docker',
+    capabilities: ['workspace.fs', 'workspace.process', 'workspace.search'],
+  },
+  validate(record) { /* 校验 root / ref 可解析，不碰网络 */ },
+  async open(record, context) { /* 返回 WorkspaceConnection：get()/status()/close() */ },
+}
+
+const dispose = ctx.workspaceCore.registerProvider(provider)
+```
+
+`get()` 的返回值必须直接用 DSH 官方类型（`FileSystem` / `SubprocessRuntime`）或底座能力类型（`WorkspaceSearchService`），这样所有消费方无需分支。
+
+## 4. 客户端（浏览器侧）：按 session 取远端身份
+
+**把** 自建的「当前是否远端 / 当前连哪台」状态 **改为** 从公开的 session 列表 + 工作区快照推导：
+
+| 现在 | 改为 |
+|---|---|
+| 全局的 local/remote 开关 | `ctx.sessions.list.getSnapshot()` 的 `current` + `byId[id].cwd` |
+| 自建的 alias / 远端选择器 | 最长匹配的 workspace anchor → `workspace.alias` / `workspace.remoteRoot` |
+| 各自轮询工作区列表 | 共享一个 `WorkspaceManager` 快照（订阅即可，不要二次拉取） |
+
+参考实现（照抄这两个文件即可）：
+
+- `src/client/session-connect-gate.ts` — `SessionGateList` 适配层 + `makeAnchorWorkspaceResolver()`（最长锚点匹配、Windows 大小写折叠）+ 打开会话时探测服务器。
+- `src/client/ssh/session-target.ts` — `createSessionSshTargetSource()`：`Session → 固定远端目标` 的可订阅数据源（`useSyncExternalStore` 友好，快照引用稳定）。
+
+约定：
+
+- 面板 / Tab 的目标**跟随 session**，不要在面板里放服务器下拉框（切换服务器 = 切换 session）。
+- session 未绑定工作区时，渲染明确的不可用状态（例如模糊蒙版），不要静默失败或回退到本机操作。
+
+## 5. 自检清单
+
+1. `rg "node:fs|node:child_process" src` 无生产命中（测试除外）。
+2. 不再存在自建的 path→远端映射或 local/remote 全局状态。
+3. 所有工作区查询都经 `ctx.workspaceCore`；provider 身份判断用 `record.provider.id`。
+4. 在 SSH 工作区 session 中执行插件核心功能 → 落在远端（用 `remote_*` 工具或远端 `pwd` 复核）。
+5. 在本地 session 中执行同一功能 → 行为与改造前一致。
+6. 单元测试里用假 `WorkspaceCore` 注入即可，无需真实 SSH。
+
+## 6. 不要做
+
+- 不要在插件里直接建 SSH 连接 —— 连接、凭据、TOFU 都由底座的引擎统一管理。
+- 不要缓存 `WorkspaceRecord` 当作长期身份 —— 用 `id` + `findByAnchor()` 重新解析。
+- 不要用本机 `realpath` 解析远端路径 —— 交给 `workspace.fs` capability。
+- 不要假设锚点目录存在或可写 —— 它只是 session cwd 的占位锚点。

package/lib/base/index.js

@@ -0,0 +1,95 @@
+import { a as normalizeAnchorPath, i as isPathUnderAnchor, n as WorkspaceLedger, r as assertValidRecords, t as WORKSPACE_LEDGER_SCHEMA_VERSION } from "../ledger-D2ezq1iW.js";
+import { a as decodeLegacySshKey, c as defaultNamespaceCodec, i as WFS_SCHEME, l as encodeRoute, n as WorkspaceProviderRegistry, o as decodeWfsKey, r as LedgerWorkspaceRouter, s as decodeWorkspaceId, t as ProviderRegistrationError, u as encodeWorkspaceId } from "../registry-CViuzKYI.js";
+import { t as WORKSPACE_PROVIDER_API_VERSION } from "../model-Cp7f70Mb.js";
+//#region src/base/plugin.ts
+/**
+* Registry of loaded plugins (provider + feature plugins together). Keeps
+* the workspace registry and plugin lifecycle in one place.
+*
+* NOT WIRED INTO PRODUCTION YET: the DSH runtime registers the builtin
+* providers directly (`runtime/workspace-core.ts`) and no third-party plugin
+* loads through this host — only tests do. It is kept because it is the
+* documented distribution contract for out-of-tree providers (see SKILLS.md);
+* provider teardown stays ownership-correct for when it is wired up: each
+* registration releases the disposer that `register()` returned for THAT call,
+* so a duplicate (same id+version) registration never unregisters a provider it
+* does not own.
+*
+* @internal Not reachable from any production assembly today.
+*/
+var WorkspacePluginHost = class {
+	registries;
+	plugins = /* @__PURE__ */ new Map();
+	features = /* @__PURE__ */ new Set();
+	/** Per-plugin disposers collected from activate (provider/feature/workspace listeners). */
+	pluginDisposers = /* @__PURE__ */ new Map();
+	constructor(registries) {
+		this.registries = registries;
+	}
+	/** Load a plugin: validate manifest, run activate. Throws on failure. */
+	async load(plugin) {
+		if (this.plugins.has(plugin.manifest.id)) throw new Error(`plugin '${plugin.manifest.id}' already loaded`);
+		if (plugin.manifest.apiVersion !== 1) throw new Error(`plugin '${plugin.manifest.id}' apiVersion ${plugin.manifest.apiVersion} is not supported (need 1)`);
+		const disposers = [];
+		await plugin.activate({
+			registerProvider: (provider) => {
+				const disposer = this.registerProvider(provider);
+				disposers.push(disposer);
+				return { dispose: disposer };
+			},
+			registerFeature: (feature) => {
+				const disposer = () => {
+					this.features.delete(feature);
+				};
+				disposers.push(disposer);
+				this.features.add(feature);
+				return { dispose: disposer };
+			},
+			workspaces: this.registries.workspaces,
+			onWorkspaceChange: (listener) => {
+				const disposer = this.registries.workspaces.subscribe(listener);
+				disposers.push(disposer);
+				return { dispose: disposer };
+			}
+		});
+		this.pluginDisposers.set(plugin.manifest.id, disposers);
+		this.plugins.set(plugin.manifest.id, plugin);
+	}
+	/** Unload a plugin, disposing every contribution (providers, features, listeners). */
+	async unload(id) {
+		const plugin = this.plugins.get(id);
+		if (plugin === void 0) return;
+		await plugin.deactivate?.();
+		const disposers = this.pluginDisposers.get(id) ?? [];
+		for (const dispose of disposers) try {
+			dispose();
+		} catch {}
+		this.pluginDisposers.delete(id);
+		this.plugins.delete(id);
+	}
+	registerProvider(provider) {
+		const disposeRegistration = this.registries.workspaces.register(provider);
+		let disposed = false;
+		return () => {
+			if (disposed) return;
+			disposed = true;
+			disposeRegistration();
+		};
+	}
+	/** Active features (for a runtime to wire up per-workspace surfaces). */
+	featuresFor(workspace, capabilities) {
+		return [...this.features].filter((feature) => feature.supports({
+			workspace,
+			capabilities
+		}));
+	}
+};
+/**
+* Minimal capability set surface used by the DSH runtime to decide which
+* features apply to a workspace. Computed from the provider manifest.
+*/
+function capabilitiesOf(provider) {
+	return new Set(provider.manifest.capabilities);
+}
+//#endregion
+export { LedgerWorkspaceRouter, ProviderRegistrationError, WFS_SCHEME, WORKSPACE_LEDGER_SCHEMA_VERSION, WORKSPACE_PROVIDER_API_VERSION, WorkspaceLedger, WorkspacePluginHost, WorkspaceProviderRegistry, assertValidRecords, capabilitiesOf, decodeLegacySshKey, decodeWfsKey, decodeWorkspaceId, defaultNamespaceCodec, encodeRoute, encodeWorkspaceId, isPathUnderAnchor, normalizeAnchorPath };