dsh-plugin-wsl-env 0.15.0 → 0.17.0

package/docs/VALUE.zh.md

@@ -0,0 +1,144 @@
+# dsh-plugin-wsl-env 价值说明
+
+本文只回答一个问题：**在 Windows 上用 DeepSeek Harness 做 WSL 项目，为什么值得装这个插件。**
+功能、安装与逐项行为见 [README](../README.md) 和 [ARCHITECTURE.md](ARCHITECTURE.md)，这里谈收益、代价与适用边界。
+文中每条主张都指向仓库内可复核的证据；基线为 v0.9.0（2026-10-17）。
+
+> **一句话**：它把 WSL 发行版变成 DSH 会话真正的执行环境——命令、文件、终端、目录选择器都在发行版内完成，
+> 同时保留 DSH 的权限模型和发行版内的 bubblewrap 沙箱；不往发行版里装自己的服务，也不开端口。
+
+## 1. 没有它时，三处错位
+
+DSH 是 Windows 桌面应用，项目在 WSL 的 ext4 里。不做集成，三件事会同时错位：
+
+| 错位 | 具体表现 | 后果 |
+|---|---|---|
+| 位置 | 应用只认 `\\wsl.localhost\<distro>\...`，工具却期待 `/home/...` | 路径要来回翻译；9p 共享在大量小文件时明显慢；符号链接与权限位经过共享层后不再保真 |
+| 环境 | 命令在 Windows 侧执行 | 发行版的 `PATH`、`nvm`、`cargo`、`pyenv`、rc 配置、原生 `rg` 都用不上；脚本要么找不到解释器，要么静默用了另一个二进制 |
+| 安全 | Windows 沙箱的受限令牌到不了 WSL（`wsl.exe` 返回 `Wsl/E_ACCESSDENIED`） | 「能操作 WSL」和「命令有边界」通常只能二选一 |
+
+现成的选择各有代价：把 CLI 整个装进 WSL 最干净，但 DSH 是桌面应用，搬不进去；桌面远程（VS Code Remote-WSL、ZCode 一类）成熟，但要在发行版里放一个服务目录、开一个端口，且命令没有沙箱；什么都不做，就是上面三处错位。
+本插件补的是这三者之外的组合：**应用留在 Windows，执行世界放进发行版，边界留在命令外面。**
+
+## 2. 六条价值
+
+### 价值一：第一条命令就在正确的环境里
+
+**机制。** 会话打开发行版目录时，`auto-preset` 自动绑上 `wsl` preset；`wsl-shell` 用发行版配置的登录 shell（不写死 bash）执行 `wsl.exe --exec <shell> -lc <cmd>`。`PATH`、版本管理器、rc 文件因此全部生效。
+
+**可感知的差别。** 不需要先 `source` 什么，也不需要把 `nvm`/`pyenv` 的路径手工告诉模型。模型说「跑一下测试」，用的就是你在那个终端里会用的 `node`、`pnpm`、`cargo`。第一条命令已经是对的，不存在「先热身一条命令把环境带起来」。
+
+**证据。** [README「Using it」](../README.md#using-it)；`test/shell.test.mjs`、`test/preset-choice.test.mjs`；`pnpm run probe:sandbox-shell`。
+
+### 价值二：文件是发行版的真实文件
+
+**机制。** 读、写、搜索都经常驻 agent 落在 ext4 上：原生符号链接、原生 mode 位、发行版自己的 `rg`。GUI 文件树与预览同样由发行版内部提供。搜索参数逐字转发给发行版的 `rg`，结果、输出格式、退出码都是 rg 自己的，且遵守该目录的 `.gitignore`。
+
+**可感知的差别。** `chmod +x`、`ln -s`、git hook、按内容分发的工具，行为与 Linux 主机一致；`glob`/`grep` 不再跨 9p 慢桥，也不再用 Windows 侧那份 rg 去读 Linux 目录。文件夹里的 `/home/you/x` 与 GUI 里的 `\\wsl.localhost\ubuntu\home\you\x` 是同一个文件，不是副本。
+
+**证据。** [ARCHITECTURE「The filesystem substrate」](ARCHITECTURE.md#the-filesystem-substrate)、[LIMITATIONS](LIMITATIONS.md)；`test/search-route.test.mjs`、`test/search-exec.test.mjs`、`test/fs-substrate.test.mjs`；`pnpm run probe:substrate`（8/8）。已知极限见第 4 节：新文件 0600、含反斜杠的文件名、watch 为轮询。
+
+### 价值三：沙箱是默认，失败是响亮的
+
+**机制。** 一个会话的受限命令在同一个 systemd user scope 内经 `bubblewrap` mount profile 执行（后台进程、真实 `/tmp`、`ps` 可见），scope 随会话结束停止；三档权限（`read-only` / `workspace-write` / `danger-full-access`）逐档生效；文件写入按同一份策略检查，受限策略下的写入还由内核在 bwrap 配置内二次拒绝。没有可用的 bwrap 时，命令报 `SANDBOX_UNAVAILABLE` 而不是脱箱运行。
+
+**可感知的差别。** 受限命令和写入受到工作区策略约束，但这不是完整隔离：Windows interop 等途径仍可能越过 Linux 侧的写入边界。被拒绝时，模型收到一次「用刚好够用的权限重试」的提议，而不是直接要 `danger-full-access`。审计时能拿到当时实际执行的模式和拒绝原因；在显式 pin 发行版的配置里，文件工具遇到跨发行版路径时由 `FS_OUTSIDE_DISTRO` 拒绝，且放宽权限也解不开。
+
+**诚实边界。** 上报是 `enforcement: partial`，因为发行版内的进程仍可通过 interop 启动 Windows 程序；`maskWindowsDrive` 收窄这个洞（`/mnt` 在受限视图里消失），但 binfmt 按内容分发，所以它仍不是闭合；完全关闭要在发行版层面设 `[interop] enabled=false`。插件不把 partial 说成 full。
+
+**证据。** [ARCHITECTURE「Sandbox」](ARCHITECTURE.md#sandbox)、[SECURITY](../SECURITY.md)；`test/sandbox.test.mjs`、`test/fs-decisions.test.mjs`；`pnpm run probe:sandbox`、`pnpm run probe:sandbox-off`。
+
+### 价值四：一个进程，两种会话，工具箱不变
+
+**机制。** 组合层按路径坐标路由：发行版 UNC 路径交给 agent 实现，盘符路径留给宿主后端；GUI 终端按会话路由，WSL 目录会话得到发行版 shell，Windows 目录会话仍是 PowerShell；`wsl-shell`/`wsl-fs` 挂在 preset 层，所以环境按会话生效。
+
+**可感知的差别。** 不需要为 WSL 单开一个应用或 profile，也不需要把整个应用切成「WSL 模式」。同一个窗口里，开 Windows 文件夹的会话不受影响，开 `\\wsl.localhost\...` 的会话自动进入发行版。换项目只是换一个打开的文件夹。模型侧尤其重要：插件不新增任何模型工具，现有工具的名字、参数、返回语义不变，变的只是它们实际作用的世界。
+
+**证据。** [README「Architecture」](../README.md#architecture)、[docs/root-fs-routing.md](root-fs-routing.md)；`test/composition.test.mjs`、`test/terminal.test.mjs`、`test/fs.boot.test.mjs`。
+
+### 价值五：不装服务、不开端口、没有残留
+
+**机制。** 发行版里没有安装任何服务，也没有监听端口；插件只替换 DSH 的服务实现。文件操作与命令走发行版内按 distro 缓存的常驻 agent——它是传输层，不注册系统服务，agent 脚本在握手时校验 sha256。
+
+**可感知的差别。** 不会多出 `~/.vscode-server` 这类目录，不会和本机端口冲突，卸载后发行版里没有需要手动清理的服务端目录。WSL 升级或发行版重启后，下一次调用重建传输；只有 agent 在「有请求在飞」时死亡才可能耗尽它的一次重建额度（见 [LIMITATIONS](LIMITATIONS.md)），这是已声明的边界，不是日常路径。
+
+**注意区分。** 「不装服务」不等于「零依赖」：bubblewrap 是默认路径的硬依赖；会话 runtime 还需要 systemd 为 PID 1 且 user manager 已 `enable-linger`（临时 scope，不是安装的常驻服务）。ripgrep、git、inotify-tools 由 `pnpm run bootstrap` 体检。插件不把这些工具打包进来，也不在发行版里安装常驻服务。
+
+**证据。** [README「How it compares」](../README.md#how-it-compares)；`agent/wsl-agent.sh`、`test/agent.test.mjs`；`scripts/bootstrap.sh`。
+
+### 价值六：模型拿到事实，不用猜
+
+**机制。** 会话环境向模型暴露 `DSH_WSL_DISTRO`、`DSH_WSL_SHELL`、`DSH_WSL_HOME`、`DSH_WSL_PORTS`；端口按约 10 秒的节奏刷新。错误码按抛出者分门别类（`FS_OUTSIDE_DISTRO`、`SANDBOX_UNAVAILABLE`、`FS_STALE_VERSION` 等），每条都说明谁拒绝、怎么解除。会话打开时若缺工具，直接给出该发行版的安装命令。
+
+**可感知的差别。** 模型能说出它启动的 dev server 的确切地址（WSL2 把 localhost 转发给 Windows，浏览器可直接打开）；路径拒绝、沙箱缺失、文件过期各有各的码，排错不用从「命令失败了」开始猜。这减少的是往返次数，不只是错误信息的好看程度。
+
+**证据。** [ARCHITECTURE「Error codes」](ARCHITECTURE.md#error-codes)、[README「Troubleshooting」](../README.md#troubleshooting)；`test/ports.test.mjs`、`test/preflight.test.mjs`、`test/terminal.test.mjs`。
+
+## 3. 和替代方案的价值对照
+
+| | 不做集成（Windows 侧开 UNC） | 桌面远程（VS Code Remote-WSL 等） | 把 CLI 装进 WSL | 本插件 |
+|---|---|---|---|---|
+| 命令环境 | Windows | 发行版 | 发行版 | 发行版 |
+| 文件语义 | 9p 共享，慢且丢 POSIX 细节 | 发行版内，原生 | 发行版内，原生 | 发行版内，原生（ext4） |
+| 命令沙箱 | Windows 沙箱到不了 WSL | 无 | 取决于 CLI | 发行版内 bubblewrap + systemd 会话 scope |
+| 发行版内安装 | 无 | 一个服务目录 | 整个工具 | 无自有服务（依赖系统工具） |
+| 端口 | 无 | 监听一个端口 | 无 | 无 |
+| 卸载残留 | 无 | 手动删服务目录 | 删工具 | 无 |
+| 适用前提 | 能接受慢与语义丢失 | 用 VS Code / 对应桌面端 | 工具能整个搬进 WSL | Windows + DSH GUI + WSL2 |
+
+**别人更强的地方要直说。** 桌面远程重开工作区是即时的，服务常驻；VS Code 的远程有多年生产打磨。CLI 装进 WSL 则完全不需要桥接。本插件不试图在这些维度取胜，它只解决一个组合：**DSH 在 Windows 上，项目在 WSL 里，命令要有沙箱。**
+
+## 4. 代价、边界与不适用
+
+价值是收益减代价。下面这些是安装前就该知道的：
+
+- **bubblewrap 是硬依赖。** 默认路径没有它，每条受限命令都失败（这是有意的 fail-closed）；受限的文件写入同样需要它。会话 runtime 还要求 systemd 为 PID 1、user manager 已 `enable-linger`；预检失败会带修复命令拒绝。`pnpm run bootstrap <distro>` 会体检并给出安装命令。
+- **enforcement 是 partial。** interop 让发行版内的进程仍能启动 Windows 程序。`maskWindowsDrive` 只是收窄；完全关闭要靠 `wsl.conf` 的 `[interop] enabled=false`。需要「对 Windows 侧也绝对隔离」的场景，本插件给不了。
+- **两套 `/tmp`。** `workspace-write` 下，会话 runtime 中的命令与文件工具使用发行版真实的 `/tmp`；关闭会话 runtime 后，命令使用私有 tmpfs，文件工具仍使用真实 `/tmp`，两者互相看不见。跨边界的文件要走会话工作区。
+- **watch 优先 inotify，轮询回退。** 无界目录且装了 `inotify-tools` 时用递归 inotify，按 0.5s 合并为粗粒度失效；文件目标、限深目录或缺少工具时回退轮询，原地 `cp -p`、恢复目录 mtime 的解包等极端情形仍可能漏报。
+- **文件名含反斜杠无法寻址**，因为 UNC 显示形式就是身份。改名是唯一工作法。
+- **新文件发布为 0600**（宿主后端的发布语义）；需要可执行时自己 `chmod`。写入的发布对进程死亡持久，但不 fsync 父目录，机器崩溃可能丢 rename。
+- **平台与版本。** 仅 Windows + WSL2；Node `^22.19.0 || >=24.0.0`；DSH peer 声明版本下限，开发依赖精确钉版，升级须重新验证。
+- **不适合的情况。** 工作流本来就能整个装进 WSL 的 CLI；需要 VS Code 远程的编辑器能力（IntelliSense、调试器、扩展）；需要企业级强隔离或多租户；项目主要在 Windows 盘上（插件能用，但价值不在这里）。
+
+这些不是「以后会修」的清单，而是设计边界：每一条都在 [LIMITATIONS.md](LIMITATIONS.md) 里写明原因。**把边界写清楚本身也是价值**——它让「没做到」不被误读成「已经做到」。
+
+## 5. 价值如何被证明
+
+| 层面 | 证据 |
+|---|---|
+| 每次提交 | `pnpm test`：风格、语法、构建逐字节一致、`tsc --noEmit`、单测全过 |
+| 覆盖率 | `pnpm run test:coverage`，门限 85/84/70（行/分支/函数） |
+| 真机 | 探针套件（`test/probe/run-all-when-closed.sh --include-fs`），含沙箱边界演示、agent/one-shot 双路径对拍、文件基座、终端、选择器 |
+| CI | Node 22 / 24 × Linux / Windows 跑 `pnpm test`；覆盖率在 Node 24 |
+| 上游接缝 | peer 钉版逐字节比对，[PEER-PARITY.md](PEER-PARITY.md)、[upstream/promotion-map.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/upstream/promotion-map.md) |
+| 行为承诺 | [REQUIREMENTS.zh.md](REQUIREMENTS.zh.md) 的 24 条登记与追溯矩阵 |
+
+真机探针是手动步骤（托管 runner 没有 WSL 发行版），这是已记录的验证缺口（REQUIREMENTS 的 OI-2），不是隐性遗漏。
+
+## 6. 决策规则
+
+**装它，如果同时满足：**
+
+1. 你在 Windows 上用 DeepSeek Harness 的 GUI；
+2. 项目在 WSL2 发行版的 ext4 上，且你希望模型用 Linux 路径工作；
+3. 你希望命令有边界，并且接受为它安装 bubblewrap。
+
+**别装它，如果满足任意一条：**
+
+- 你的工作流是一款能整个装进 WSL 的 CLI——直接装进去更简单；
+- 你需要编辑器级远程能力（调试、IntelliSense、扩展）；
+- 你需要对 Windows interop 也绝对隔离；
+- 你的项目主要在 Windows 盘上，且不需要 Linux 工具链。
+
+## 7. 证据索引
+
+| 想知道 | 看 |
+|---|---|
+| 功能、安装、配置 | [README](../README.md) / [中文 README](README.zh.md) |
+| 部件如何挂载、路径坐标、沙箱设计 | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| 不做什么、为什么 | [LIMITATIONS.md](LIMITATIONS.md) |
+| 每个配置键 | [CONFIGURATION.md](CONFIGURATION.md) |
+| 与 VS Code Remote-WSL 的 parity 审计 | [PARITY.md](PARITY.md) |
+| 与上游 fsio 的逐字节合同 | [PEER-PARITY.md](PEER-PARITY.md) |
+| 安全边界与上报渠道 | [SECURITY.md](../SECURITY.md) |

package/docs/adr/0002-native-agent.md

@@ -0,0 +1,348 @@
+# ADR 0002 — Native in-distro agent (design)
+
+- **Status:** accepted — the native agent is the default session-runtime
+  backend (`agentBackend: auto` + the packaged static-musl binary for the
+  distro's architecture), with the shipped shell agent as the fallback and the
+  `native`/`shell` overrides. The concurrency/KILL/FS surface, the copy/verify,
+  the HELLO digest, the packaged x86_64/aarch64 binaries and the real-machine
+  probe are in place. **A7 is in place** (the shared reads are native); **A8
+  is in place** (aarch64 18-check under qemu-user in CI; physical aarch64 WSL
+  is out of scope); **v6 is deferred** — the measured lock-removal gain is
+  marginal, and A7 removed the shared-shell batch bottleneck
+- **Date:** 2026-10-18
+- **Related:** [ADR 0001](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/adr/0001-session-scoped-sandbox.md) (session runtime),
+  `agent/wsl-agent.sh`, `src/agent.ts`, `src/agent-protocol.ts`
+
+## Context
+
+This section records the shell-only baseline and original design motivation.
+The status and migration sections describe what was subsequently shipped;
+v6 structured errors and concurrent FS remain deferred.
+
+The resident peer inside the distro is a POSIX shell script,
+`agent/wsl-agent.sh`. It speaks protocol v5 over the `wsl.exe` stdio pipe:
+line-oriented, `|`-separated, base64 payloads, `HELLO`/`PING`/`SHUTDOWN`/
+`KILL`/`SETENV`/`EXEC`/`FS`. It is the single owner of commands and the
+filesystem substrate; the session runtime (ADR 0001) runs one instance per
+session/policy under a systemd user scope.
+
+The script has served well and is covered by `agent.test.mjs`, the protocol
+tests, and the real-machine probes. Its hard edges are real though:
+
+1. **Serial requests.** The stdin loop reads one frame, runs it to completion,
+   then reads the next. Commands and confined file writes share the session
+   runtime agent, so an `npm run build` blocks an editor save on the same
+   session. Reads use the separate plain agent, but writes do not.
+2. **Cancellation needs a second transport.** While the shell is blocked in
+   `wait`, a `KILL` line sits in the pipe. The host spawns a second `wsl.exe`
+   and sends `USR1` to the `HELLO` pid; inside a PID namespace that is
+   impossible, so confined residents are not signalable at all.
+3. **Capture is shell machinery.** Bounded capture is a FIFO plus a `dd`
+   reader, a one-second kill grace, and a watchdog; it works, but it is the
+   least obvious code in the repository and every edge case costs a probe.
+4. **Protocol evolution is constrained.** FS failures ride a `dsh-fs|reason|
+   base64` line on stderr, because a POSIX sh response line has no structured
+   error slot. New features (event streaming, concurrent FS, per-request
+   environment) would stretch base64-over-sh further.
+5. **Lockstep releases.** Host and script must ship the same v5. A stale
+   deployed script is refused by digest, which is correct but means every
+   protocol change is a synchronized deploy and an app restart.
+
+The original design deferred implementation because a binary adds build,
+distribution, architecture and supply-chain costs. Subsequent measurements
+justified shipping the native agent as described below.
+
+## Goals
+
+- **Concurrency.** Multiple `EXEC`/`FS` requests in flight, each with its own
+  id, output buffers, deadline and process group; a long command no longer
+  blocks a write.
+- **Precise cancellation.** `KILL` is read by the event loop while the command
+  runs; the request's process group is signalled directly. No `USR1`, no second
+  `wsl.exe`, no `signalable` special case.
+- **Native capture.** `pipe` + bounded buffers per request; no FIFO, no `dd`,
+  no kill grace. Truncation is a byte count, not a shell heuristic.
+- **Structured errors.** FS refusals become `ERR|id|reason|message` frames; the
+  stderr side channel is retired in the protocol version that introduces them.
+- **A path to events.** A native agent can host inotify and stream watch
+  events to the host later, instead of the separate watcher process.
+- **Same security boundary.** The agent still executes exactly the argv the
+  host wrapped in `bwrap`; confinement, the session scope and the FS fence are
+  unchanged.
+
+## Non-goals
+
+- Replacing `wsl.exe` as the transport, `bwrap` as the sandbox, the systemd
+  user scope as the session lifetime, or the host-side FS fence.
+- A Windows-side native component. The host remains Node.
+- Building the agent from source on the user's machine. The distro is not
+  required to have a compiler.
+- Retiring the shell agent. It remains the portable fallback (and the only
+  agent on architectures without a shipped binary).
+- File watching, port scanning or terminal streaming in the first native
+  version; those stay where they are until the event path exists.
+
+## Options
+
+### Language
+
+| Option | Strengths | Costs |
+|---|---|---|
+| **Rust** (recommended) | static musl binary, no GC, strong parsing, precise process-group/timer control; the host protocol is simple to mirror | cross-compile toolchain in CI; slightly slower iteration |
+| **Go** | easiest cross-compilation, static binary, simple concurrency | larger binary, GC pauses (irrelevant at this scale), fewer compile-time guarantees for the parser |
+| **C** | smallest, universally available | no memory safety; the parser and frame lifetimes become manual; not worth it for this project |
+
+The recommendation is Rust with `x86_64-unknown-linux-musl` and
+`aarch64-unknown-linux-musl`, built in CI from a committed `Cargo.lock`.
+
+### Distribution
+
+| Option | Verdict |
+|---|---|
+| **Prebuilt binaries in the npm package**, one per Linux arch (recommended) | no network at runtime, pinned by the host, offline-installable; the package grows by a few MB per arch |
+| Download on first use | rejected: a plugin install must not fetch and execute a remote binary |
+| Build on first use in the distro | rejected: requires a compiler and network; the plugin's premise is no in-distro install |
+| Ship only the shell | current state; acceptable until a trigger fires |
+
+The binary runs from a **copy in the distro**, not from `/mnt/c`: DrvFs is
+often mounted `noexec`, and executing from the share couples the agent's
+lifetime to the Windows path. The host copies
+`agent/native/linux-<arch>/dsh-wsl-agent` from the plugin package to
+`~/.cache/dsh-wsl/agent/<sha256>/dsh-wsl-agent`, verifies the digest, marks it
+executable, and caches per digest. The session runtime's `--ro-bind /` makes
+the copy readable; `temp` is not used, so the binary survives scope restarts.
+
+### Protocol
+
+Start from **v5 compatibility for the spike**, then introduce **v6** for the
+features that require it:
+
+- **v5 native** (spike): the same `HELLO|wsl-agent|5|<digest>|<pid>` and the
+  same frames; the host's existing codecs and the existing `agent.test.mjs`
+  run unchanged. This proves the parser, exec, capture and FS ops. The digest
+  is the binary's sha256.
+- **v6** (the concurrency release):
+  - `HELLO|wsl-agent|6|<sha256>|<pid>|<impl>` with `impl = native|shell`.
+  - FS errors in `ERR|id|reason|b64 message`; the `dsh-fs|` stderr line is no
+    longer produced by the native agent.
+  - Drop `SETENV` as a sticky global (or keep it only for the single-request
+    compatibility path): with concurrent requests a sticky environment is a
+    race. Environment travels on the request (a count + base64 key/value
+    lines) or is fixed by the `HELLO` process environment plus the host's
+    bwrap wrapper.
+  - `KILL|id` is handled by the event loop; the host stops spawning the
+    `USR1` helper for native agents.
+  - Optional `ACK`/`RES` streaming for large outputs is a later revision; the
+    first v6 keeps one RES per request.
+- Concurrency limits: a small per-agent cap (e.g. 8 in flight), a queue, and
+  per-path serialization for FS writes so two writers do not race inside the
+  agent. The host's per-target substrate lock already serializes its own
+  operations; the agent's lock is defense in depth.
+
+Handshake identity: the host accepts `wsl-agent|5` for the shell and
+`wsl-agent|6|native` for the binary; the digest is checked against the file
+the host shipped (script or binary). A mismatch refuses with the existing
+"resync" remedy, never silently runs a stale peer.
+
+## Process model
+
+One process per agent, an event loop over stdin plus child pipes and timers:
+
+- `EXEC`/`FS` frames are decoded, validated and queued; the event loop
+  acknowledges them (`ACK|id`) and spawns each request's process group (or
+  performs the FS syscalls directly for `stat`/`read`/`write`).
+- `KILL|id` and the per-request deadline signal the group: `TERM`, then
+  `KILL` after a fixed grace; the event loop keeps serving other requests.
+- stdout/stderr pipes are drained into per-request bounded buffers; the RES
+  line carries the exit code, both buffers and the cut flags.
+- stdin EOF, `SHUTDOWN` or a fatal IO error runs the same cleanup as today:
+  kill in-flight groups, remove staging directories, exit 0.
+- The agent is the session scope's main process. The scope's cgroup still
+  reaps background processes at session end; the agent adds no new lifecycle.
+- FS operations use syscalls (stat/lstat/readlink/read/write, atomic rename);
+  no `sh`, `base64`, `stat`, `find` subprocesses. The write path keeps the
+  no-replace and expected-version semantics the host fence relies on, and the
+  same staging-directory cleanup for killed writes.
+
+## Host integration
+
+- `agent-shared.ts` / the session runtime's factory chooses the backend:
+  - native when a binary for the distro architecture is present in the
+    package and the copy/verify succeeds;
+  - the shell otherwise.
+- A config key (`agentBackend?: "auto" | "native" | "shell"`, default `auto`)
+  keeps a one-session escape hatch during rollout.
+- The copy/verify step is host-side JavaScript over `wsl.exe --exec` (read the
+  Windows file through `/mnt/c`, write with `dd`/`cat` to the cache path,
+  sha256sum, chmod); it is cached by digest, so the cost is once per version
+  per distro user.
+- `WslAgent` already carries ids, pending requests, `HELLO` digest checks and
+  the lease; the native agent reuses that surface. The `USR1`/`signalable`
+  path becomes a shell-only detail; native agents are cancelled by frame.
+- The FS substrate's `DistroFs` maps `ERR|id|reason` to `FsCodedError` for
+  v6; v5 native keeps the stderr path so the existing tests are unchanged.
+
+## Security
+
+- The binary is committed/built by CI, baked into the npm package, and pinned
+  by sha256 in the host; it is never downloaded at runtime.
+- The protocol parser is fuzzed (frames, base64, path lengths, counts) and
+  never invokes a shell for request content. `EXEC` argv is the host's argv;
+  the agent does not interpret it.
+- The agent runs as the distro user, inside the same bwrap mount profile and
+  systemd scope; it has no privilege the shell agent did not have.
+- The copy path is the user's cache, owned by the user; a world-writable
+  directory is refused; the digest is re-checked before exec.
+
+## Testing
+
+- **Protocol suite**: the existing `agent-protocol` unit tests stay authoritative
+  for both codecs; v6 adds error/env/encoding cases.
+- **Agent suite**: `agent.test.mjs` parameterized over `{ shell, native }`.
+  The shell tests already drive the real script on Linux; the native tests do
+  the same with the built binary.
+- **Differential matrix**: every frame shape and failure mode run against both
+  agents, comparing exit codes, stdout/stderr bytes, cut flags and FS errors
+  (allowing the v5→v6 error-channel difference where expected).
+- **Concurrency suite** (new): two EXECs; EXEC + FS write; KILL one request
+  while another runs; timeout one; verify the untouched request's result.
+- **Probes**: the real-machine suite and the session runtime; the FS-first
+  session; a long command with a concurrent write (the shell's known stall is
+  the native agent's acceptance test).
+- **Fuzzing**: the frame decoder and the path/args validation.
+
+## Migration
+
+1. **Design (this ADR).** No code.
+2. **Spike (partial).** HELLO/PING/SETENV/EXEC/KILL, per-request process
+   groups, the FS surface and the expected-version/mode matrix are done in
+   `agent/native/spike` (18/18 manual checks, ~673 KB release binary). The
+   host wiring, the packaged static-musl x86_64/aarch64 binaries and the
+   default rollout are in place; v6 remains deferred. aarch64 runs under
+   qemu in CI (A8).
+3. **v6 (deferred).** The A6 measurement shows the lock-removal gain is
+   marginal (~2-3 ms per 16 ops) and the shared shell read agent is the batch
+   bottleneck. v6 stays unimplemented; A7 addresses the measured bottleneck
+   instead. Revisit v6 only if the native shared v5 still queues measurably or
+   the ERR/env framing is needed for another reason.
+4. **Host integration (partial).** The copy/verify, the session-runtime factory,
+   the `wsl-shell.agentBackend` selection, the packaged static-musl x86_64 and
+   aarch64 binaries (`agent/native/linux-<arch>/dsh-wsl-agent`, selected by the
+   distro's `uname -m`) and the running-binary HELLO digest are in place. The
+   native-session probe (8/8: scope, EXEC, FS, KILL, digest, teardown) is in
+   the real-machine suite; the default rollout is 0.10.0.
+5. **Enabled by default** on x86_64 and aarch64 (0.10.0); the shell fallback
+   and the flag stay. Retiring the shell is not planned; the shell remains the
+   fallback and the shared read path until A7.
+6. **Native shared read agent (A7, done).** The shared unconfined read agent
+   selects the native binary (v5) with the shell as fallback; the A6 probe is
+   the acceptance measurement (~30x on batch reads).
+7. **aarch64 functional validation (A8, done).** The CI `native packages` job
+   runs the 18-check suite under qemu-user against the freshly built aarch64
+   musl binary and the committed `agent/native/linux-aarch64/dsh-wsl-agent`.
+   Physical aarch64 WSL is out of scope ([COMPATIBILITY.md](../COMPATIBILITY.md)).
+
+## Spike result (stage 2, partial)
+
+`agent/native/spike/` is a std-only Rust crate that implements `HELLO`,
+`PING`, `SHUTDOWN`, `SETENV`, `EXEC` and `KILL` with per-request process
+groups and bounded capture, plus `FS` `stat`/`lstat`/`read`/`write` (mode,
+no-replace, replace, expected-version re-check, staging + fsync + atomic
+publication) and `list`/`realpath` (nearest-existing-ancestor walk, dot-dot
+refusal). The `dsh-fs` side channel rides the RES stderr. FS operations are
+serialized inside the agent for the v5 error channel; EXECs run concurrently
+with them.
+
+`agent/native/spike/test.mjs` (run manually against the built binary) passes
+18/18: HELLO with the running binary's sha256; PING; EXEC exit/streams; SETENV; two concurrent EXECs with the
+short one settling first; KILL without a second `wsl.exe`; a 200 ms timeout
+killing the group promptly; the EXEC timeout unit (a 2 s budget does not kill
+a 300 ms command — an earlier millisecond reading killed every longer
+command); a capped output that is cut while the pipe is still drained; FS
+stat/lstat/read matching the shell agent; a no-replace write and its refusal;
+the missing-path side channel; FS list/realpath matching the shell; the
+dot-dot refusal; the expected-version replace/stale path; a setuid mode; and a
+shell-agent differential for the EXEC shape. The release binary is ~673 KB on
+x86_64-unknown-linux-gnu and builds in ~2 s with no dependencies.
+
+What this proves: the event loop removes the shell's serial-request stall and
+the `USR1`/second-transport cancellation shape is unnecessary, and the core
+FS surface (stat/lstat/read/write/list/realpath, version re-check, modes) can
+be reproduced in the native process. What it does not prove: a native-session
+probe on physical aarch64 WSL (qemu covers the 18-check suite in CI), v6
+concurrency/env framing, or the event stream. The host copy/verify, the
+session-runtime factory, the packaged binaries and the default are in place;
+the shell agent remains the fallback and the shipped peer.
+
+## FS queue measurement (A6, 2026-10-18)
+
+`test/probe/fs-queue.mjs` measures both FS agents on the live machine
+(x86_64, 16 concurrent requests per row):
+
+| path | wall | queue max | per-op exec |
+|---|---|---|---|
+| shared shell `stat` | 342 ms | 324 ms | ~20 ms |
+| shared shell `read` | 418 ms | 387 ms | ~25 ms |
+| shared shell `list` | 614 ms | 583 ms | ~37 ms |
+| native `write` | 7.7 ms | 6.6 ms | 0.3 ms |
+| native `read` | 12.2 ms | 9.4 ms | 0.2 ms |
+| native `EXEC` (50 ms each) | 88 ms | 7.5 ms | 5.5 ms |
+
+The **shared shell read agent is the batch-read bottleneck**: its serial loop
+turns 16 concurrent reads into 342-614 ms with queue waits up to 583 ms. Native
+FS execution is 0.2-0.3 ms; the sequential per-op is dominated by the ~22 ms
+host round trip (the shell's sequential stat is 37.5 ms, the native's 22 ms).
+
+**v6's lock removal is marginal**: it would take 16 native writes from 7.7 ms
+to roughly 5 ms and 16 reads from 12.2 ms to roughly 8 ms. The high-value next
+step is the **native shared read agent (v5)** — same packaged binary and
+protocol, the shell as fallback, roughly 30x on batch reads — not v6. The
+single-op latency (~22 ms) is the transport, not the FS backend.
+
+## Why it was built
+
+Built in 0.10.0. The triggers that fired were the long-build/FS-serialization
+pressure and the opportunity to make the session runtime native without
+changing the shipped shell contract; the shell agent remains the fallback. The
+conditions below are kept as the record of the decision:
+
+- A long build reliably blocks model file writes often enough to be a reported
+  problem (the shell's serial loop).
+- A feature genuinely needs the event loop: in-agent inotify/event streaming,
+  concurrent FS, per-request environment, output streaming.
+- The shell agent causes a second maintenance incident (a capture/cancel edge
+  the probes did not cover).
+- The distribution cost falls (e.g. the release pipeline already ships
+  per-arch binaries and provenance).
+
+Until then the shell agent is the honest, dependency-free choice; the
+limitations in `docs/LIMITATIONS.md` remain the declared boundary.
+
+## Consequences
+
+- **Staying with the shell:** no binary supply chain; the serial write stall,
+  the `USR1` cancellation shape and the shell capture machinery remain; every
+  protocol change stays a lockstep host+script release.
+- **Going native:** concurrency and precise cancellation, simpler capture and
+  structured errors; in exchange for per-arch binaries, a copy/verify step, a
+  v6 protocol migration, a dual-implementation test matrix, and a larger
+  security review surface.
+
+## Open questions
+
+- v6 JSON instead of line/base64? The line protocol is proven and the host
+  parser is small; JSON would need a sh-free host but is easier to extend.
+  The spike should decide after measuring the v5-native parser work.
+- Per-request environment: the v5 host prefixes each command with `env`, so
+  its variables do not mutate the agent. The low-level `SETENV` frame remains
+  sticky for protocol compatibility; a future v6 can remove it.
+- FS path locking and concurrent write semantics (same path, two requests):
+  the host's per-target lock is the current answer; does the agent need its
+  own?
+- Output streaming for very large captures: RES-only keeps MAX_FRAME_BYTES;
+  a chunked revision is later.
+- ARM64 CI capacity; the aarch64 binary could ship after the x64 default.
+- Whether the native agent hosts the watcher/inotify and the port scan, or
+  keeps those as separate host-driven paths.
+- Binary size/package impact; whether both arches ship in one npm tarball or
+  the package selects at install.