dsh-wsl-bridge 0.0.0-stage → 0.4.6

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+## 0.4.6 — 2026-10-19 (unreleased)
+
+- A `WSL` session now uses the current distribution's `$HOME` as its default
+  workspace. The first bash command, relative paths, and grep/glob without a
+  path all start there instead of the Windows session directory. The home path
+  is read once; an explicit absolute path does not trigger the lookup. Host-wide
+  `wsl_*` tools still default to the session directory.
+
+## 0.4.5 — 2026-10-19 (unreleased)
+
+- Fail reads when `head` fails; reject incomplete transport and invalid UTF-8
+  edits instead of silently changing file data. Base edit guards on the exact
+  bytes read and check just before rename, including deletion detection.
+- Keep replacement dollar sequences literal, preserve existing file modes,
+  and refuse directory targets without leaving a temporary file inside them.
+- Stop every command line when the requested working directory cannot be used.
+  Background jobs use the session directory even after a persistent shell exists.
+- Search prunes hidden entries and dependency trees before scanning, preserves
+  single-file grep paths, anchors its status marker, reports failures, and marks
+  the glob scan ceiling as truncated.
+- Make release dry-runs independent of login, check official-registry auth and
+  a clean working tree for publication, publish the packed tarball, and fail if
+  version verification fails. Include installation/release scripts in the pack.
+- Add regression coverage and opt-in real WSL tests; fix the CI mount test's
+  hard-coded local path.
+
+## 0.4.4 — 2026-10-19
+
+- **Fix the `WSL` preset failing to load**: the `plan-mode` row was copied
+  without its required `config.section`, so
+  `@deepseek-ai/dsh-plan-mode` refused activation and the preset showed
+  "load failed" in the mode picker while the rest of the plugin worked. The
+  shipped standard preset's section text is now carried verbatim; the roster
+  probe reports `wsl: broken=null`.
+- Add the preset-roster diagnostic recipe used to find it (see docs/TROUBLESHOOTING.md).
+
+## 0.4.3 — 2026-10-19
+
+- Self-check wording: a probe has no live agent, so the job registry's refusal
+  now reads as "registry reachable" instead of an error line.
+
+## 0.4.2 — 2026-10-19
+
+- **Fix persistent `cd`**: the bash tools passed the session directory as the
+  working directory on every call, which reset the persistent shell's cwd. The
+  default workdir is now only the shell's initial directory; an explicit
+  `workdir` still changes it for this and later calls. Verified in a real
+  desktop session (env vars persisted, cwd now does too) and pinned by the
+  integration self-check (`tool cd persistence=OK`).
+
+## 0.4.1 — 2026-10-19
+
+- Opt-in real background-job self-check (registers a job with the host registry
+  and verifies the command actually wrote its file inside the distribution).
+
+## 0.4.0 — 2026-10-19
+
+- Add `runInBackground` to `wsl_bash` and the WSL preset's `bash`: the command is
+  registered with the host job registry (`job_output` / `job_kill`) and owns its
+  own `wsl.exe` process, so the persistent shell's lifecycle cannot kill it.
+  Controlled by `backgroundJobs` (default on); refuses clearly when the
+  deployment composes no job registry.
+- The destructive guard runs before a background registration.
+- Tests: 87 cases total.
+
+## 0.3.0 — 2026-10-19
+
+- Add a deterministic destructive-command guard (`dangerGuard`, default on):
+  recursive deletes, block-device writes, power control, `find -delete` and
+  `git clean -f/-d/-x` are refused unless the call passes `allowDangerous: true`.
+  Applied to both `wsl_bash` and the WSL preset's `bash`.
+- Add `docs/ARCHITECTURE.md`, `docs/SECURITY.md`, `docs/TROUBLESHOOTING.md`.
+- Add `npm test` (78 cases), a CI workflow (Windows, Node 22/24), and
+  `scripts/install-desktop.ps1`.
+- Desktop-composition smoke test: an isolated profile replicating the desktop
+  bundle set (web-all / market / better-sidebar) boots with both bridge layers
+  active.
+
+## 0.2.3 — 2026-10-19
+
+- Packaging for publish: MIT LICENSE, bilingual `locale/*.json` display metadata,
+  SVG icon, CHANGELOG, and a publish-shaped `files` list; `npm pack` yields 20
+  files / ~37 KB with no build step.
+- Fix the integration-test hooks: environment variables (`DSH_WSL_BRIDGE_SELFCHECK`,
+  `DSH_WSL_BRIDGE_MARKER`, `DSH_WSL_BRIDGE_WORLD_*`) now override the shipped row
+  config instead of being overridden by it.
+- Dispose the shells the self-checks open, so a probe run leaves no `wsl.exe`
+  processes behind.
+- Verified a **packed** install (tarball into a fresh isolated profile, not a
+  link): host tools mount, the `WSL` preset mounts, and bash/grep/glob execute in
+  the distribution.
+
+## 0.2.0 — 2026-10-19
+
+- Add the declarative `WSL` agent preset: a session created in this mode mounts
+  `dsh-wsl-bridge/wsl-world`, so `bash`, `read`, `write`, `edit`, `grep` and
+  `glob` all operate on Linux paths inside the distribution.
+- Add in-distribution `grep` (GNU grep -E) and `glob` (find + glob matching),
+  pruning hidden entries and `node_modules`/VCS metadata.
+- Capture the `subprocess` service during `apply()`: a preset mount context is
+  inactive after activation, so a late `ctx.subprocess` lookup now never throws.
+- Persona sentence tells the model its working directory is inside WSL and that
+  Windows files live under `/mnt/<drive>`.
+
+## 0.1.0 — 2026-10-19
+
+- First host-only build: persistent `wsl_bash` (one shell per session, `cd`
+  survives between calls), binary-safe `wsl_read`/`wsl_write`, sha256-fenced
+  `wsl_edit`, `wsl_path`, `wsl_env`, and a default-on routing prompt section.
+- Zero dependencies, no build step; opt-in self-check for integration testing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-wsl-bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,124 @@
+# dsh-wsl-bridge
+
+[中文](README.md)
+
+A native WSL (Linux) execution surface for [DSH](https://github.com/deepseek-ai/DeepSeek-Harness) on Windows. It starts no extra web server and installs nothing inside the distribution. Windows sessions and WSL sessions share one desktop app.
+
+Version **0.4.6**. Requires **Windows**, a working WSL distribution, and **DSH `>= 0.2.1-rc.2`**. Source: <https://github.com/TGWgulugu/dsh-wsl-bridge>
+
+## Install
+
+Run this in a normal terminal, not inside a DSH tool sandbox. If `dsh` is not on `PATH`, use the full path to the `dsh.cmd` that ships with DSH Desktop.
+
+```powershell
+dsh plugin --profile desktop add dsh-wsl-bridge
+```
+
+Before the package is published, or to install the checkout you have open:
+
+```powershell
+dsh plugin --profile desktop add .
+```
+
+From the repository root, `pwsh -File scripts/install-desktop.ps1` does the same. Quit DSH Desktop from the tray and open it again. A page refresh does not load the plugin.
+
+After the restart:
+
+- Every session gains `wsl_bash`, `wsl_read`, `wsl_write`, `wsl_edit`, `wsl_path`, and `wsl_env`.
+- The new-session mode picker has a **WSL** entry.
+
+Uninstall:
+
+```powershell
+dsh plugin --profile desktop remove dsh-wsl-bridge
+```
+
+If the app then fails to start, run `pnpm install` in that profile directory.
+
+## Two ways to use it
+
+### WSL tools in any session
+
+These tools are added beside the Windows shell and file tools. They do not replace them.
+
+| Tool | What it does |
+|---|---|
+| `wsl_bash` | Runs bash in WSL. One persistent shell per session, so `cd` and `export` survive. Output ends with `[exit code: N]` |
+| `wsl_read` | Reads a Linux path, with optional line `offset` / `limit` |
+| `wsl_write` | Atomically writes a Linux path. `expectedSha256` refuses the write when the file changed after you read it |
+| `wsl_edit` | Replaces a string. A sha256 check ties the write to the bytes that were read |
+| `wsl_path` | Converts Windows paths to Linux paths and back. Uses the distribution's `wslpath` when it can |
+| `wsl_env` | Reports the distribution, kernel, user, and whether node / python3 / git are present |
+
+A routing note is on by default: for Linux work, prefer `wsl_bash` and Linux paths; Windows files are at `/mnt/<drive>`. It does not hide or disable the host tools.
+
+`wsl_bash` accepts `runInBackground: true`. The command is registered as a host job (`job_output` to read it, `job_kill` to stop it) and owns a separate WSL process. It does not inherit the persistent shell's `cd` or `export`, and it is not killed when that shell exits.
+
+### WSL session mode
+
+Choose **WSL** when creating a session. In that session, `bash`, `read`, `write`, `edit`, `grep`, and `glob` run inside Linux and take Linux paths. Persona, skills, goals, plan mode, compaction, subagents, todos, web, and present stay the standard DSH set.
+
+**The default workspace is the current distribution's home directory (`$HOME`).** The first `bash` starts there. Relative paths resolve there. `grep` and `glob` search there when `path` is omitted. Pass `/mnt/<drive>/...` when the search should cover a Windows directory.
+
+| Tool | What it does |
+|---|---|
+| `bash` | Persistent bash in the distribution. The syntax is bash, not PowerShell |
+| `read` / `write` / `edit` | Linux paths. Relative paths are relative to `$HOME` |
+| `grep` | GNU grep in the distribution. Rows look like `path:line: text`. Omitting `path` searches `$HOME` |
+| `glob` | Lists files matching a glob, oldest first. Omitting `path` lists `$HOME` |
+| `wsl_env` | Distribution facts |
+
+`$HOME` is resolved once. Text that a login profile prints is not treated as the path. If the lookup fails, search does not fall back to the Windows session directory.
+
+## Configuration
+
+Set these on the plugin row `config` (`cordis.patch.yml`, or a profile patch that overrides it). Every field is optional.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `distro` | `''` | Distribution name. An empty string uses the system default |
+| `timeoutMs` | `120000` | Default deadline for `bash` / `wsl_bash`, in milliseconds |
+| `fileTimeoutMs` | `30000` | Deadline for one read, write, or search |
+| `maxFileBytes` | `2097152` | Maximum bytes `read` / `edit` will load |
+| `defaultWorkdir` | `session` for host tools; `home` for WSL mode | `session` translates the Windows session directory to `/mnt/...`. `home` uses the distribution's `$HOME`. An absolute Linux path is also accepted |
+| `dangerGuard` | `true` | Refuses obviously destructive commands unless that call passes `allowDangerous: true` |
+| `backgroundJobs` | `true` | Allows `runInBackground`. Refuses clearly when the host has no job registry |
+| `promptSection` | `true` | Adds the routing note to host sessions |
+| `promptOrder` | `3260` | Sort order of that note |
+| `promptText` | `''` | Replaces the built-in routing note. Empty keeps the built-in text |
+| `selfCheck` | `false` | Probes WSL once on mount. `DSH_WSL_BRIDGE_SELFCHECK=1` does the same |
+| `selfCheckMarker` | `''` | Appends the probe result to this file. Or set `DSH_WSL_BRIDGE_MARKER` |
+
+The refusal list covers recursive deletes, block-device writes, power control, `find -delete`, and `git clean -fdx`. It is a fixed list, not a kernel boundary. A different spelling can still get through.
+
+## Limits
+
+- Windows only. Both rows disable themselves on any other host.
+- The tools run through `wsl.exe` and are **not** inside DSH's Windows file sandbox. Treat them as able to write anything that WSL user can write, including Windows paths reached through `/mnt/<drive>`. See [docs/SECURITY.md](docs/SECURITY.md).
+- `grep` / `glob` use GNU grep and find. They do not read `.gitignore`. Hidden files, `node_modules`, and VCS metadata are skipped.
+- The folder selected in the desktop UI stays that UI's workspace. WSL-mode tools no longer search it by default. Skill directories and UI file references still use Windows paths.
+- The first call waits for the distribution to start and can take several seconds. `timeoutMs` defaults to 120 seconds.
+- This plugin does not install Node or any other toolchain inside the distribution.
+
+## Docs
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): how the host tools and the WSL mode are split, and why shell / fs services are left alone.
+- [docs/SECURITY.md](docs/SECURITY.md): the sandbox boundary, and what the destructive-command guard does not promise.
+- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md): nothing showed up, `EPERM`, a missing mode, cold start, uninstall.
+
+## Development
+
+```powershell
+npm test
+npm run test:integration
+pwsh -NoProfile -File test/release.test.ps1
+pwsh -File scripts/release.ps1 -DryRun
+```
+
+`npm test` does not need WSL. `npm run test:integration` runs inside a real distribution and deletes its own temporary directory. The release-script check does not publish. A real publish needs a clean git tree, then `pwsh -File scripts/release.ps1`.
+
+The code is plain ESM with no build. `index.js` registers the host tools, `wsl-world.js` registers WSL session mode, and the implementation is in `src/`.
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-wsl-bridge
+
+[English](README.en.md)
+
+在 Windows 上给 [DSH](https://github.com/deepseek-ai/DeepSeek-Harness) 一个原生的 WSL（Linux）执行面。不额外启动 web 服务，也不在 WSL 里安装 dsh。Windows 会话和 WSL 会话在同一个桌面端里使用。
+
+当前版本 **0.4.6**。需要 **Windows**、一个可用的 WSL 发行版，以及 **DSH `>= 0.2.1-rc.2`**。源码：<https://github.com/TGWgulugu/dsh-wsl-bridge>
+
+## 安装
+
+在普通终端里执行（不要在 DSH 会话的工具沙箱里跑）。`dsh` 不在 PATH 上时，换成 Desktop 自带的 `dsh.cmd` 完整路径。
+
+```powershell
+dsh plugin --profile desktop add dsh-wsl-bridge
+```
+
+尚未发布、或要装当前目录的源码时：
+
+```powershell
+dsh plugin --profile desktop add .
+```
+
+也可以在仓库根目录运行 `pwsh -File scripts/install-desktop.ps1`。装完后从托盘**完全退出** DSH Desktop，再打开。刷新页面不够。
+
+重启后：
+
+- 任意会话里出现 `wsl_bash`、`wsl_read`、`wsl_write`、`wsl_edit`、`wsl_path`、`wsl_env`。
+- 新建会话的模式选择器里出现 **WSL**。
+
+卸载：
+
+```powershell
+dsh plugin --profile desktop remove dsh-wsl-bridge
+```
+
+如果卸载后应用起不来，在该 profile 目录里执行一次 `pnpm install`。
+
+## 两种用法
+
+### 任意会话里的 WSL 工具
+
+这些工具加在现有会话上，不替换 Windows 自己的 shell 和文件工具。
+
+| 工具 | 作用 |
+|---|---|
+| `wsl_bash` | 在 WSL 里执行 bash。每个会话一个持久 shell，`cd` 和 `export` 会保留。输出以 `[exit code: N]` 结尾 |
+| `wsl_read` | 读 Linux 路径，支持按行 `offset` / `limit` |
+| `wsl_write` | 原子写入 Linux 路径。可带 `expectedSha256`，文件在你读过之后被改过就拒绝写入 |
+| `wsl_edit` | 按字符串替换。读和写之间用 sha256 核对内容 |
+| `wsl_path` | Windows 路径和 Linux 路径互转。优先用发行版里的 `wslpath` |
+| `wsl_env` | 查看发行版、内核、用户和是否有 node / python3 / git |
+
+默认有一段路由提示：Linux 上的工作优先用 `wsl_bash` 和 Linux 路径，Windows 文件在 `/mnt/<盘符>`。它不隐藏、也不禁用宿主工具。
+
+`wsl_bash` 可以传 `runInBackground: true`。命令会登记成宿主后台任务，用 `job_output` 看输出、用 `job_kill` 停止。这个任务独占一个 WSL 进程：不继承持久 shell 的 `cd` / `export`，会话 shell 退出时也不会把它杀掉。
+
+### WSL 会话模式
+
+新建会话时选择 **WSL**。这一会话里的 `bash`、`read`、`write`、`edit`、`grep`、`glob` 都在 Linux 里执行，参数是 Linux 路径。persona、skill、goal、plan、compaction、subagent、todo、web、present 仍用 DSH 标准会话的那一套。
+
+**默认工作区是当前发行版的家目录（`$HOME`）。** 第一次 `bash` 从家目录开始；相对路径按家目录解析；`grep` 和 `glob` 不传 `path` 时也搜索家目录。要搜 Windows 目录时，显式传入 `/mnt/<盘符>/...`。
+
+| 工具 | 作用 |
+|---|---|
+| `bash` | 发行版里的持久 bash，语法是 bash，不是 PowerShell |
+| `read` / `write` / `edit` | 读写 Linux 路径。相对路径相对 `$HOME` |
+| `grep` | 发行版内的 GNU grep。结果是 `path:line: text`。不传 `path` 时搜 `$HOME` |
+| `glob` | 按 glob 列出文件，旧文件在前。不传 `path` 时列 `$HOME` |
+| `wsl_env` | 发行版信息 |
+
+家目录只查询一次。登录脚本如果往标准输出打字，不会被当成路径。查询失败时，搜索不会退回 Windows 会话目录。
+
+## 配置
+
+改插件行的 `config`（`cordis.patch.yml`，或 profile 里覆盖它的补丁）。字段都可以省略。
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `distro` | `''` | 发行版名。空字符串表示系统默认发行版 |
+| `timeoutMs` | `120000` | `bash` / `wsl_bash` 的默认时限（毫秒） |
+| `fileTimeoutMs` | `30000` | 读、写、搜索的单次时限（毫秒） |
+| `maxFileBytes` | `2097152` | `read` / `edit` 最多读取的字节数 |
+| `defaultWorkdir` | 宿主工具是 `session`；WSL 模式是 `home` | `session` 把 Windows 会话目录译成 `/mnt/...`。`home` 使用当前发行版的 `$HOME`。也可以填绝对 Linux 路径 |
+| `dangerGuard` | `true` | 拒绝明显的破坏性命令，除非该次调用带 `allowDangerous: true` |
+| `backgroundJobs` | `true` | 是否允许 `runInBackground`。宿主没有任务注册表时会明确拒绝 |
+| `promptSection` | `true` | 是否加入宿主会话的路由提示 |
+| `promptOrder` | `3260` | 这段提示的排序 |
+| `promptText` | `''` | 用来替换内置路由提示。空字符串表示用内置文本 |
+| `selfCheck` | `false` | 挂载时探测一次 WSL。也可以设环境变量 `DSH_WSL_BRIDGE_SELFCHECK=1` |
+| `selfCheckMarker` | `''` | 把探测结果追加到这个文件。也可以设 `DSH_WSL_BRIDGE_MARKER` |
+
+破坏性命令清单包括递归删除、写块设备、关机、`find -delete`、`git clean -fdx`。这是固定名单，不是内核隔离；换一种写法仍可能绕过。
+
+## 边界
+
+- 只支持 Windows。其他系统上这两行配置会禁用。
+- 工具通过 `wsl.exe` 执行，**不受** DSH 的 Windows 文件沙箱约束。把它看成：发行版里该用户能写的路径，以及通过 `/mnt/<盘符>` 能碰到的 Windows 路径，都可以写。详见 [docs/SECURITY.md](docs/SECURITY.md)。
+- `grep` / `glob` 使用 GNU grep 和 find，不读 `.gitignore`。隐藏文件、`node_modules` 和版本库元数据会跳过。
+- 桌面端选中的 Windows 文件夹仍然是界面上的工作区。WSL 模式的工具默认不再搜那个目录。技能目录和界面上的文件引用仍按 Windows 路径解析。
+- 第一次调用要等发行版冷启动，可能要数秒。`timeoutMs` 默认 120 秒。
+- 本插件不在发行版里安装 Node 或其他工具链。
+
+## 文档
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)：宿主工具和 WSL 模式怎么分层，以及为什么不替换 shell / fs 服务。
+- [docs/SECURITY.md](docs/SECURITY.md)：沙箱边界和危险命令守卫做不到什么。
+- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)：装完没出现、`EPERM`、模式缺失、冷启动、卸载。
+
+## 开发
+
+```powershell
+npm test
+npm run test:integration
+pwsh -NoProfile -File test/release.test.ps1
+pwsh -File scripts/release.ps1 -DryRun
+```
+
+`npm test` 不需要 WSL。`npm run test:integration` 会在真实 WSL 里跑，并删掉自己的临时目录。发布脚本的检查不会真的发布。正式发布要先提交干净的工作区，再执行 `pwsh -File scripts/release.ps1`。
+
+代码是纯 ESM，没有构建步骤。`index.js` 注册宿主工具，`wsl-world.js` 注册 WSL 会话模式，实现在 `src/`。
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,146 @@
+# Bundle layer for dsh-wsl-bridge.
+#
+# Two rows:
+#   1. `wsl-bridge`  — the host-wide bridge (wsl_* tools + routing prompt).
+#   2. `preset-wsl`  — the declarative `WSL` agent preset: a session created in
+#      this mode works with Linux paths (`bash`/`read`/`write`/`edit`/`grep`/
+#      `glob` are the WSL variants mounted from `dsh-wsl-bridge/wsl-world`).
+#
+# Both are disabled outside Windows: the bridge spawns `wsl.exe` and the preset
+# cannot work where WSL does not exist.
+- insert:
+    - id: wsl-bridge
+      name: 'dsh-wsl-bridge'
+      config:
+        distro: ''
+        timeoutMs: 120000
+        promptSection: true
+        selfCheck: false
+      disabled: !!js process.platform !== 'win32'
+    - id: preset-wsl
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: wsl
+        name: WSL
+        description: 'Linux paths inside WSL. The default workspace is that distribution home directory.'
+        order: 2
+        plugins:
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              prefix: >-
+                You are a coding agent powered by the {{model}} model. Your working
+                directory is the home directory of the current WSL distribution.
+                bash, read, write, edit, grep and glob take Linux paths. grep and
+                glob search that home directory unless you pass another path.
+                The Windows filesystem is reachable as /mnt/<drive>. Use bash
+                syntax for commands, not PowerShell.
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+          - id: wsl-world
+            name: 'dsh-wsl-bridge/wsl-world'
+            config:
+              distro: ''
+              timeoutMs: 120000
+              defaultWorkdir: home
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+          - id: tool-schedule
+            name: '@deepseek-ai/dsh-tool-schedule'
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+          - id: command-goal
+            name: '@deepseek-ai/dsh-command-goal'
+          - id: tool-goal
+            name: '@deepseek-ai/dsh-tool-goal'
+          - id: planning
+            name: cordis:group
+            group: true
+            isolate:
+              planMode: true
+            config:
+              - id: plan-mode
+                name: '@deepseek-ai/dsh-plan-mode'
+                config:
+                  section: |
+                    You are in plan mode. Stay in plan mode until the user approves your plan through exit_plan_mode or switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+                    Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+                    The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+                    Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+                    Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+                    When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: compaction-basic
+                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 8192
+                  headChars: 4096
+                  tailChars: 1024
+          - id: delegation
+            name: cordis:group
+            group: true
+            isolate:
+              workflowEngine: true
+            config:
+              - id: tool-subagent-control
+                name: '@deepseek-ai/dsh-tool-subagent-control'
+              - id: tool-subagent-list-agents
+                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+              - id: tool-subagent
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: spawn
+                  toolName: subagent
+                  modelSelectionSettings: true
+              - id: tool-subagent-fork
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: fork
+                  toolName: subagent_fork
+              - id: workflow-ptc
+                name: '@deepseek-ai/dsh-workflow-ptc'
+                config:
+                  provider: spawn
+              - id: tool-workflow
+                name: '@deepseek-ai/dsh-tool-workflow'
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+          - id: present
+            name: '@deepseek-ai/dsh-tool-present'
+          - id: tool-plugin-manager
+            name: '@deepseek-ai/dsh-plugin-manager/tools'
+            disabled: true
+          - id: tool-plugin-market
+            name: '@deepseek-ai/dsh-plugin-market/tools'
+            disabled: true
+      disabled: !!js process.platform !== 'win32'

package/docs/ARCHITECTURE.md

@@ -0,0 +1,73 @@
+# Architecture
+
+`dsh-wsl-bridge` gives DSH on Windows a native Linux execution surface without a
+second web server and without installing anything inside WSL.
+
+## Two layers
+
+| Layer | Entry | Rows | What it does |
+|---|---|---|---|
+| Host bridge | `index.js` | `wsl-bridge` | Registers `wsl_bash`/`wsl_read`/`wsl_write`/`wsl_edit`/`wsl_path`/`wsl_env` for **every** session and publishes a routing prompt section. |
+| WSL preset | `wsl-world.js` | `preset-wsl` → `wsl-world` | Declares an agent preset `WSL`; a session created in that mode gets `bash`/`read`/`write`/`edit`/`grep`/`glob`/`wsl_env` whose world is the distribution. |
+
+The preset row is a plain `@deepseek-ai/dsh-agent-preset` declaration. Its
+`plugins` list is the shipped `standard` preset with three substitutions:
+
+- `tool-bash` / `tool-pwsh` removed (they are the Windows shells);
+- `tool-fs` / `tool-fs-search` removed (host-path file tools and Windows ripgrep);
+- `wsl-world` inserted.
+
+Everything else (persona, instructions, skills, goals, plan mode, compaction,
+subagents, todo, web, present) is the shipped set, so a WSL session is a normal
+DSH session whose shell and file world happen to be Linux.
+
+## Why no service replacement
+
+DSH exposes `ctx.shell` and `ctx.fs` services, but a composition allows exactly
+one implementation of each. Replacing them would change every session, and a
+preset-scope provider would need an isolate realm to avoid leaking. Instead the
+preset mounts **tools**, which are scoped: the host's tools stay untouched and
+the WSL session's tools shadow nothing globally.
+
+## Execution path
+
+```
+model tool call
+  → tool.execute(args, exec)
+  → shell pool (one persistent `wsl.exe … bash -l -s` per agent; one-shots for files)
+  → ctx.subprocess.spawn({ argv, stdio })
+  → wsl.exe → bash inside the distribution
+```
+
+- **Persistent shell**: one frame per call (nonce begin/end markers, `$?`
+  captured, stdout/stderr kept separate). `cd` and exports survive; a dead shell
+  is reported with `shellRestarted` and rebuilt on the next call.
+- **One-shot calls** (`read`/`write`/`edit`/`grep`/`glob`): `wsl.exe --cd <dir> -e
+  bash -lc <command>`. Payloads travel as base64 on stdin, so quoting and binary
+  bytes can never change the command; writes go through a sibling temp file and
+  `mv -T`, and existing file modes are preserved. Edits hash the exact bytes read
+  and recheck the hash just before rename. This is a best-effort stale check,
+  not atomic compare-and-swap: an external writer can still race the final
+  check/rename. Atomic replacement replaces a target symlink rather than its
+  referent; use the resolved file path if the link must be preserved. Ownership,
+  ACLs and extended attributes are not copied from the old inode.
+- **Paths**: Windows drive paths map to `/mnt/<drive>`. Host `wsl_*` tools still
+  translate the session directory into the default workdir. A `WSL` session
+  (`defaultWorkdir: home`) reads the distribution's `$HOME` once and uses that
+  path for the initial shell, relative paths, and grep/glob. `wsl_path` prefers
+  the distribution's own `wslpath` and falls back to the host-side mapping.
+- **grep/glob** run GNU grep/find inside the distribution (the host search suite
+  ships a Windows ripgrep, which cannot see Linux paths). They prune hidden
+  entries and `node_modules`/VCS metadata; `.gitignore` is not read (documented).
+
+## Platform and compatibility gates
+
+- Windows only: both rows carry `disabled: !!js process.platform !== 'win32'`.
+- `engines.dsh: ">=0.2.1-rc.2"` is the install-time gate the Desktop plugin
+  manager reads; the loader itself only composes bundles listed in
+  `dsh.profile.bundles`.
+- Zero dependencies and no build step. This is deliberate: on DSH 0.2.1 a preset
+  row spelled as a `file:` URL cannot resolve bare `@deepseek-ai/*` imports (the
+  module interception layer is keyed on the importer's path), so a package-name
+  row from the profile's `node_modules` is the only reliable shape. The bundle
+  therefore imports nothing outside `node:` built-ins.

package/docs/SECURITY.md

@@ -0,0 +1,33 @@
+# Security and boundaries
+
+## What the bridge can touch
+
+The bridge spawns `wsl.exe` through the host `subprocess` service. That path is
+**below** DSH's file sandbox: on Windows the sandbox wraps shell executors and the
+filesystem mutations with an ACL/restricted-token runner, but the Linux side of a
+`wsl.exe` child runs on the Linux kernel and cannot be fenced by a Windows token.
+
+Consequences, stated rather than hidden:
+
+- A WSL-side write through these tools is not constrained by the session's
+  `workspace-write` policy. Treat the bridge as able to write anything the WSL
+  user can write, plus whatever the Windows user can reach through `/mnt/<drive>`.
+- The destructive-command guard is a **deterministic refusal list**, not a kernel
+  boundary: it stops obvious irreversible commands (`rm -r`, device writes,
+  power control, `find -delete`, `git clean -fdx`) unless the call passes
+  `allowDangerous: true`. A differently spelled command can still do damage.
+- `distro` is a caller-visible string; no shell interpolation happens on the host
+  side (argv arrays only), and paths/payloads are quoted or base64-encoded.
+
+## What it does not do
+
+- It opens no network listener and starts no server.
+- It installs nothing in the distribution and asks for no credentials.
+- It does not read the host environment into the distribution: `ctx.subprocess`
+  already scrubs `*KEY*`/`*SECRET*`/`*TOKEN*` and `DSH_*` from child environments.
+
+## Reporting
+
+This is a community plugin. Report security-relevant issues through
+https://github.com/TGWgulugu/dsh-wsl-bridge/issues and include the minimum
+reproduction, without credentials or personal paths.