dsh-plugin-wsl-env — run a DSH session against a WSL distro, with the sandbox moved inside the distro

[Big-Dao]

What it is: not a new tool set — three seam providers, so the model's existing bash/read/write/edit/glob/grep tools run against a WSL distro:

• ctx.shell — every command runs as wsl.exe -d <distro> --cd <linux dir> --exec <login shell> -lc <cmd>
• ctx.fs — Linux paths map onto the distro's UNC share, so the host fs stack (and the packaged ripgrep) operates on real distro files
• ctx.subprocess — the GUI terminal window opens inside the distro, in the Session workspace

Install

dsh wsl --from-default-profile web --dump-config
dsh plugin --profile wsl add dsh-plugin-wsl-env
dsh --profile wsl

It ships as a DSH bundle (dsh.bundle.patch), so the layer is applied by dsh plugin add.

The sandbox is the interesting part. DSH's Windows ACL runner cannot reach WSL at all (its restricted token fails wsl.exe with Wsl/E_ACCESSDENIED), so the execution world used to run unconfined and say so. It now gets the Linux sandbox instead: the plugin builds a bubblewrap profile on the host and executes it inside the distro —

wsl.exe -d <distro> --cd <dir> --exec bwrap --ro-bind / / --dev /dev   --unshare-pid --proc /proc --die-with-parent   [--tmpfs /tmp --bind <workspace> <workspace>] -- <shell> -lc <cmd>

— using the same profile arguments, denial dialect and runner-failure rules as dsh-sandbox-local's Linux rung. ctx.fs fences its mutations by the same per-call policy, so "bash can write /tmp but the write tool cannot" asymmetries don't arise, and the Permissions selector plus the denied/escalate flow come back.

Reported honestly: enforcement is partial, not full. A distro process can still execute a Windows binary through interop (/mnt/c/.../*.exe), and that process runs outside bubblewrap under your ordinary Windows token. pnpm run probe:sandbox demonstrates it. Also: bubblewrap must be installed in the distro (sudo apt install bubblewrap); without it the providers fail closed (SANDBOX_UNAVAILABLE) rather than silently running unconfined.

Verified (current state, v0.14.0): 41/41 unit tests on CI (node 22/24, Linux and Windows); coverage 97%+; a six-distro real WSL2 compatibility matrix (Ubuntu, Debian, Fedora, openSUSE Tumbleweed, Arch, Alpine-musl — systemd and non-systemd); the aarch64 native agent executes its 18-check suite under qemu on every push; the shell agent passes 7 checks in each of five non-Ubuntu container families; twelve real-machine probes (sandbox semantics, FS mutations, terminal routing, picker, both agent paths) run nightly on a self-hosted runner; and in daily GUI use, an agent write outside the Session workspace is refused inside the distro, with the escalation flow that follows succeeding.

Requires Windows + WSL2, DSH 0.2.1-rc.3 (peer floor — newer harness releases install the plugin unchanged).

• Repo: https://github.com/Big-Dao/dsh-plugin-wsl-env
• npm: https://www.npmjs.com/package/dsh-plugin-wsl-env
• Release: https://github.com/Big-Dao/dsh-plugin-wsl-env/releases/tag/v0.14.0
• Compatibility matrix: https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/COMPATIBILITY.md
• 中文版见下方回复 / Chinese version below.

[Big-Dao]

中文版（内容已更新至 v0.14.0）

这是什么： 不是一套新工具——三个 seam provider，让模型现有的 bash / read / write / edit / glob / grep 直接作用于一个 WSL 发行版：

• ctx.shell —— 每条命令都以 wsl.exe -d <distro> --cd <linux 目录> --exec <登录 shell> -lc <命令> 在 distro 内执行
• ctx.fs —— Linux 路径映射到 distro 的 UNC 共享，宿主 fs 栈（包括打包的 ripgrep）操作的是真实的 distro 文件
• ctx.subprocess —— GUI 终端窗口直接开在 distro 里，落在 Session 工作区

安装

dsh wsl --from-default-profile web --dump-config
dsh plugin --profile wsl add dsh-plugin-wsl-env
dsh --profile wsl

以 DSH bundle（dsh.bundle.patch）交付，dsh plugin add 即完成层应用。

沙箱是最有意思的部分。 DSH 的 Windows ACL runner 完全够不到 WSL（受限令牌调 wsl.exe 会得到 Wsl/E_ACCESSDENIED），所以执行环境过去只能无围栏运行并如实声明。现在它改用 Linux 沙箱：插件在宿主侧构建 bubblewrap profile，在 distro 内执行——

wsl.exe -d <distro> --cd <dir> --exec bwrap --ro-bind / / --dev /dev   --unshare-pid --proc /proc --die-with-parent   [--tmpfs /tmp --bind <workspace> <workspace>] -- <shell> -lc <cmd>

——使用与 dsh-sandbox-local Linux 档位相同的 profile 参数、拒绝方言与 runner 失败规则。ctx.fs 的每次变更都受同一策略围栏约束，"bash 能写 /tmp 而写工具不能"的不对称不会出现；Permissions 选择器与拒绝/提权流程因此回归。

如实声明： enforcement 是 partial 而非 full。distro 内进程仍可通过 interop 执行 Windows 二进制（/mnt/c/.../*.exe），该进程运行在 bubblewrap 之外、你的普通 Windows 令牌之下。pnpm run probe:sandbox 演示了这条逃逸。此外 bubblewrap 必须装在 distro 里（sudo apt install bubblewrap）；缺它时 provider fail closed（SANDBOX_UNAVAILABLE），绝不静默无围栏运行。

验证（v0.14.0 现状）： 单元测试 41/41（Node 22/24 × Linux/Windows CI）；覆盖 97%+；六个真实 WSL2 发行版的兼容性矩阵（Ubuntu/Debian/Fedora/openSUSE Tumbleweed/Arch/Alpine-musl，含 systemd 与非 systemd）；aarch64 原生代理在 qemu 下每次推送执行 18 项检查；shell agent 在五个非 Ubuntu 容器家族中各通过 7 项检查；12 项真机探针（沙箱语义、FS 变更、终端路由、picker、agent 双路径对拍等）每晚在自托管 runner 上运行；GUI 日常使用中，agent 越界写入在 distro 内被内核拒绝、随后的提权流程可用。

需要 Windows + WSL2，DSH 0.2.1-rc.3（peer 下限，后续版本免升级安装）。

• 仓库：https://github.com/Big-Dao/dsh-plugin-wsl-env
• npm：https://www.npmjs.com/package/dsh-plugin-wsl-env
• Release：https://github.com/Big-Dao/dsh-plugin-wsl-env/releases/tag/v0.14.0
• 兼容性矩阵：https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/COMPATIBILITY.md
• 中文 README：https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/README.zh.md

[Big-Dao]

v0.15.0 更新（2026-10-28）

兼容性矩阵发布版 —— 把“支持哪些环境”从口头承诺变成实测证据：

• 六个真实 WSL2 发行版的兼容性矩阵（Ubuntu/Debian 13.5/Fedora 44/openSUSE Tumbleweed/Arch/Alpine 3.22，systemd 与非 systemd、glibc 与 musl），探针套件全部实测，含每家的导入陷阱清单：docs/COMPATIBILITY.md
• aarch64 原生代理在 CI 的 qemu 下执行完整 18 项检查（每次推送）；shell agent 在 五个非 Ubuntu 容器家族（debian/alpine/fedora/opensuse/arch）各通过 7 项检查——CI 每次推送验证
• nightly 真机探针：自托管 runner 每晚运行全套探针（Tier 1 指标的采集机制）

两个修复（都来自矩阵运行时踩到的首跑陷阱）：

• WSL-306：目录名含换行时，picker 不再把它拆成两行或丢掉（ls -1ALp 行解析 → find -print0 NUL 分隔）
• WSL-307：全新 distro 的首次受限写入不再神秘失败——spawn 前的自愈清单（workspace root / sh / base64 / sha256sum），失败会报出具体是哪一步

新特性：

• WSL-310 bootstrap-import：一条命令把 rootfs tarball 变成插件就绪的 distro（架构探测、导入、OOBE 解卡、wsl.conf、建用户、装 bubblewrap、Linger、doctor 终验）——六个发行版的导入陷阱已产品化
• WSL-314 interopVisibility：visible / masked / disabled 一键选择 interop 姿态（不改变 enforcement 声明，仍是 partial）

安装 / 升级：dsh plugin --profile <profile> add dsh-plugin-wsl-env（peer 下限 0.2.1-rc.3，新版 harness 免升级安装）

• Release：https://github.com/Big-Dao/dsh-plugin-wsl-env/releases/tag/v0.15.0
• npm：https://www.npmjs.com/package/dsh-plugin-wsl-env
• 快速上手：https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/QUICKSTART.md（现已含四张运行截图）
• 兼容性矩阵：https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/COMPATIBILITY.md