dsh-plugin-wsl-env 0.1.10 → 0.3.0

package/docs/LIMITATIONS.md

@@ -3,9 +3,69 @@
 What the plugin does not do, and why. A limitation that is documented is a design
 boundary; one that is not is a bug report waiting to happen.
 
+## The filesystem substrate (`wsl-fs` `substrate`)
+
+`substrate: "agent"` (the default) serves the file tools through the resident
+in-distro agent, on ext4. `substrate: "share"` is the opt-out: the Windows-side
+host stack over the distro's 9p share. What differs:
+
+- **A new file publishes with mode 0600 on the agent substrate.** That is the
+  host backend's own POSIX publication semantics (a private 0600 staging file,
+  renamed into place), which a Linux-host DSH session has always had. The share
+  substrate was the outlier: the share drops mode sets, so new files took the
+  distro's umask default (0644). Overwrites and edits keep the original bits on
+  both substrates. Run `chmod` (or ask the model to) when a new file must be
+  executable.
+- **There is no silent fallback to the share.** When the agent substrate's
+  resident process is out — the distro stopped, or the agent crashed past its
+  one rebuild — file operations fail with `FS_IO_ERROR` naming the substrate,
+  rather than quietly degrading to share semantics that cannot follow symlinks
+  or keep mode bits. The share substrate dies with the distro anyway; the
+  agent only adds its own failure mode, which is the one honest way to fail.
+- **The mutation guard survives to the write.** `createIfAbsent` publishes with
+  a no-replace link inside the distro, which closes the check-then-write window
+  for creates outright. An overwrite or edit carries the version it was based
+  on into the write op, and the agent re-verifies it against a fresh stat one
+  syscall before the rename: a concurrent writer wins and the stale write
+  refuses with `FS_STALE_VERSION`. That narrows the share's window from a host
+  round trip to kernel-adjacent — the residual stat-then-rename pair is the
+  same sliver a Linux-host session's own rename has.
+- **Stage two routes mutations through a confined resident.** A write or edit
+  under a confined policy runs on its own long-lived agent, spawned inside the
+  bwrap profile that binds exactly what the mode grants — so the kernel, not
+  just the host-side check, refuses a write outside the workspace, and the
+  refusal carries `FS_SANDBOX_DENIED` (the command path's dialect). Costs to
+  know: `bubblewrap` becomes required for confined writes (a distro without it
+  refuses them with the bootstrap command, rather than downgrading); a policy
+  change addresses a different resident, so the first write after switching the
+  Permissions selector pays one agent startup; and a write the policy grants to
+  the distro's `/tmp` lands in the confined mount's tmpfs, not the real `/tmp`
+  — the same hand-off rule as the commands' `/tmp`: pass files through the
+  session workspace.
+- **`resolveSymlinks` is not consulted.** The share cannot traverse Linux
+  symlinks, so the share substrate retries missing reads through the distro's
+  canonical path; the agent substrate never misses them, so the config key has
+  no effect there.
+- **`glob` and `grep` are unchanged on both substrates.** They are tool-layer
+  searches running the packaged Windows ripgrep against the share — correct
+  results, slow, and `.gitignore` interpreted with Windows rules. Bringing them
+  in-distro is future work, not part of the substrate switch.
+- **`watch()` is the same poll loop on both substrates** (a `find -newer` scan
+  inside the distro), so the coarse-invalidation caveats below apply equally.
+  An inotify backend is planned, not shipped.
+
+Everything below applies to the share substrate unless it says otherwise.
+
 - **The sandbox does not govern WSL interop.** A confined command can still run a
   Windows program, which escapes the Linux-side boundary. The plugin reports this as
   `enforcement: partial`. See [ARCHITECTURE.md](ARCHITECTURE.md#reported-enforcement).
+  The `maskWindowsDrive` key on `wsl-shell` and `wsl-fs` narrows the hole: the
+  confined profile shadows `/mnt` with an empty tmpfs, so the drive's files cannot be
+  read or exfiltrated and its executables cannot be launched. It is not a closure — a
+  command that can write the workspace can write an executable there and run it
+  (binfmt interop dispatches on file content, not location) — so enforcement stays
+  `partial`, the result's sandbox fact reports `windowsDrive: "masked"`, and the only
+  complete closure remains distro-level (`[interop] enabled=false` in `wsl.conf`).
 - **`bubblewrap` must be installed**, or both providers fail immediately. The
   usability probe re-runs after a failure, so installing bubblewrap while the app
   runs is believed on the next command; only a success is cached.
@@ -31,13 +91,18 @@ boundary; one that is not is a bug report waiting to happen.
   checks the caller's guard itself, because the Windows backend publishes a guarded
   new file with a hard link, and the share does not support hard links. This is the
   race that `dsh-fs-sandbox` already documents.
-- `watch()` (file change monitoring) is not provided. Watching a 9p share is
-  unreliable, so the plugin refuses instead of arming it.
+- `watch()` observes from inside the distro (a `find -newer` poll loop, see
+  `lib/watcher.js`), so events are coarse invalidation, not per-file notifications,
+  and they arrive on the poll cadence, not instantly. A file created with an mtime
+  older than the watcher's stamp (`cp -p`, `tar -x`) is not seen until something
+  else touches the tree. Watching a 9p share from the Windows side remains
+  unsupported — the loop runs where the kernel can actually report change.
 - `glob` and `grep` use the Windows-side ripgrep over the share: correct results, but
   not fast, and `.gitignore` is interpreted with Windows rules. `editText` reads the
   whole file into memory before writing it back.
-- The terminal belongs to the whole app, not to one session. A session opened on a
-  Windows folder still gets the distro terminal, starting in `/mnt/<drive>/...`, and
-  its shell menu is deliberately reduced to the one configured profile.
+- Terminal routing is per-session by workspace coordinates (`subprocess-wsl.hostSessions`,
+  default on): a WSL-folder session gets the distro shell, a Windows-folder session gets
+  `powershell.exe` in its own directory. The shell MENU remains the single configured
+  profile, and a directory-less launch still lands in the distro.
 - Terminal activity reporting stops at `wsl.exe`, so the controller never reclaims
   these terminals when they are idle.

package/docs/PARITY.md

@@ -0,0 +1,70 @@
+# Parity with VS Code Remote-WSL
+
+What parity means for this plugin, the seam contracts the plan was audited
+against, and the phase checklist. Every phase below ends with rows of this
+table ticked and this document updated in the same change.
+
+## What parity means here
+
+Remote-WSL's experience rests on one thing: a resident server inside the
+distro. Everything users love — native ext4 semantics, inotify, native
+`rg`, low latency — is a derivative. This plugin's 9p-UNC plus one-shot
+`wsl.exe` model can only approach it. The plan therefore lands a resident
+in-distro agent and migrates the `fs` and `shell` seams onto it, keeping the
+current paths as the documented fallback (`wsl.agent: 'off'` must equal
+today's behaviour byte for byte).
+
+Not applicable, recorded so the gap is a decision and not an omission:
+
+- IntelliSense, debuggers, the extension marketplace: editor features. The
+  DSH analogue is tool latency and correctness (Phases 1–3).
+- Settings Sync, Remote-SSH tunnel chaining, Codespaces: composition-layer
+  responsibilities, not this plugin's.
+
+## Contract audit (Phase 0)
+
+Findings from reading the harness packages inside the app bundle; each one
+shaped a phase of the plan.
+
+1. **`ctx.fs.watch` is a coarse invalidation callback, not an event stream.**
+   `FileSystem.watch(target, changed, signal)` (dsh-fs) resolves once
+   observation is active and returns an async close function; `changed` takes
+   no event payload. So the in-distro watcher does not need to classify
+   rename vs. modify — any inotify (or polling) hit may call `changed()`.
+   Phase 1's watcher is accordingly simpler than planned.
+2. **Search is not an `fs` seam.** `dsh-tool-fs-search` spawns the PACKAGED
+   ripgrep binary (`@vscode/ripgrep`) through `ctx.subprocess` with a plain
+   argv vector and no shell; raw stdout is parsed by the tool. The correct
+   interception point is therefore the plugin's `subprocess-wsl` subclass:
+   when `argv[0]` is the packaged rg binary and the spec's cwd is inside this
+   distro's share, rewrite the spawn to run a distro-side `rg` (falling back
+   to `grep -rE` + `find` when absent) with identical stdout conventions.
+   Under the agent, that exec rides the agent's `exec` capability.
+3. **`dsh-fs-local` watches with chokidar over the share** — the behaviour
+   this plugin replaces: chokidar on 9p is the unreliability that made
+   `WslFileSystem.watch` refuse. The in-distro watcher replaces it wholesale.
+4. **`dsh-bash-local` carries the timeout machinery** (`clampTimeout`,
+   `deadline`, `timeoutOf`, `BASH_TIMEOUT`), which the WSL executor already
+   inherits. Migrating exec onto the agent keeps that shape: the deadline
+   arms on the host as today, but the SIGTERM→SIGKILL grace fires inside the
+   distro via the agent instead of against the Windows process tree.
+
+## Phase checklist
+
+| Phase | Deliverable | Parity row |
+| --- | --- | --- |
+| 0 | This document; contract audit above | baseline recorded |
+| 1 | `lib/agent/` + `wsl-agent` resident process: NDJSON-over-stdio protocol, capability handshake, lazy start, idle shutdown, crash-rebuild-once, permanent fallback | resident server |
+| 2 | real `watch()` SHIPPED (in-distro poll, `lib/watcher.js`); the native-ext4 migration of the remaining fs operations (and with it the workaround deletions) continues alongside Phase 3 | native file semantics, inotify — watch + publication done |
+| 3 | DONE — `WslShellExecutor` exec via agent; in-distro TERM→KILL; handle shape preserved (deviation: no streaming, no spill files) | native exec latency |
+| 4 | DONE (except the agent/plugin version handshake, which lands with the first agent-behaviour change after release) — `npm run bootstrap`, family-aware install command, `SANDBOX_UNAVAILABLE` names it | open-and-it-works |
+| 5 | DONE (routing half) — per-session routing by workspace coordinates (`terminal-route.js`, `hostSessions`); activity-based idle reclaim of distro terminals remains a documented limitation (PTY activity stops at `wsl.exe`) | terminal per window/session — routing done |
+| 6 | DONE — `DSH_WSL_PORTS` (agent-scanned `/proc/net/tcp{,6}`, timer-refreshed); localhost reachability (WSL2 localhost forwarding is platform behaviour) documented in README | port forwarding visibility |
+| 7 | DONE — recipes section in both READMEs: credential sharing, `/mnt/c` guidance, `WSLENV` policy | developer-loop odds and ends |
+
+## Fallback invariant
+
+Every phase must keep `wsl.agent: 'off'` (and, per capability, any runtime
+fallback) behaviourally identical to the pre-phase release. Probes assert
+this: `agent.sh` runs the same operation with the agent off and on and
+compares outcomes, not internals.

package/docs/PEER-PARITY.md

@@ -0,0 +1,60 @@
+# Peer parity — the fsio replication, verified
+
+The agent substrate's text mechanics (`lib/fsio-text.js`) and its provider
+orchestration messages (`lib/fs-substrate.js`, `lib/fsio-agent.js`) are a
+deliberate replica of the pinned peer's fsio module, so the model reads the
+same refusal dialect on both substrates. This file records the verification of
+that claim against the real peers, which are not imported at build time.
+
+- Peer: `@deepseek-ai/dsh-fs-local@0.2.0-rc.2` (the exact version
+  `package.json` pins), plus `@deepseek-ai/dsh-fs@0.2.0-rc.2` for the
+  `FsVersion` brand the local package imports.
+- Method: `npm pack` both pins, extract, and compare the shipped
+  `lib/index.js` (unminified ESM) function-by-function and string-by-string
+  against this repository. Verified 2026-10-03.
+
+## Verdict
+
+**The replication is faithful.** Every load-bearing line matches the peer's
+shipped code; the differences are the substrate's declared extensions, listed
+at the end.
+
+## Verified identical
+
+| Item | Evidence (peer `lib/index.js`) | Ours |
+|---|---|---|
+| `normalizeLineEndings` | `content.replaceAll("\r\n", "\n")` | identical |
+| `detectLineEndings` | 4096-char sample; `crlf > lf - crlf` | identical |
+| `restoreLineEndings` | LF unchanged; CRLF re-normalizes then `\n` → `\r\n` | identical (`replaceAll` vs `split/join` — equivalent) |
+| occurrence counting | non-overlapping left-to-right | `split(needle).length - 1` — equivalent |
+| `applyLiteralEdit` | empty needle, not-found, and ambiguous refusals; single-pass `split/join` without rescanning | identical |
+| edit refusal strings | `old_string must be a non-empty string` (`FS_EDIT_NOT_FOUND`); ``old_string was not found in "${displayPath}"``; ``old_string matched ${n} times in "${displayPath}"; provide a more specific old_string or set replace_all to true`` (`FS_AMBIGUOUS_EDIT`) | identical |
+| invalid UTF-8 | ``cannot ${verb} "${displayPath}": invalid UTF-8 text`` (`FS_NOT_TEXT`) | identical |
+| binary detection | 8192-byte sample, NUL check; ``cannot read "${displayPath}": binary file`` (`FS_NOT_TEXT`) | identical |
+| size caps | ``cannot read "${displayPath}": ${size} bytes exceeds the ${maxBytes}-byte limit`` and ``content exceeds the ${maxBytes}-byte limit`` (`FS_TOO_LARGE`) | identical |
+| `writeText` guards | not-regular (`FS_NOT_REGULAR_FILE`), `file no longer exists` / `file changed since it was read` (`FS_STALE_VERSION`), ``cannot overwrite existing "${displayPath}" without reading it first`` (`FS_NOT_OBSERVED`) | identical |
+| `editText` guards | missing file refuses with `FS_STALE_VERSION` "file changed since it was read" (NOT `FS_NOT_FOUND`); not-regular; stale-version | identical — an earlier draft of this audit suspected a divergence here; the peer matches us |
+| `listDir` refusal | ``cannot list "${displayPath}": not a directory`` (`FS_NOT_DIRECTORY`) | identical |
+| diff-basis gate | `existing !== null && Buffer.byteLength(content) < diffBasisMaxBytes` — keyed on the NEW content's size, `null` above the cap | identical — the gate's new-size keying is inherited by design, not a divergence |
+| outcome shapes | `operation: "update" \| "create"`, the `missing:${targetKey}` sentinel version, `before`/`after` | identical |
+| version join | `` `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}` `` (local `index.js:146`, branded by `dsh-fs`'s `FsVersion`) | `versionOf` — identical shape |
+
+## Deliberate divergences (declared, not drift)
+
+1. **Distro-side version re-verification.** A `replace` write carrying an
+   expected version is re-checked by the agent against a fresh stat one
+   syscall before the rename (`FS_STALE_VERSION` on mismatch). The peer's
+   check-then-write window stops at the host; ours narrows to kernel-adjacent.
+2. **Per-stream truncation flags.** The EXEC frame carries an output budget;
+   the RES line reports which streams the agent cut, surfaced as honest
+   `truncated` flags. The peer's collect-budget machinery is the spill-file
+   path we deliberately do not run.
+3. **The transport around the ops** (ACK, KILL, the confined resident) is
+   protocol this package owns; the peer has no agent.
+
+## Maintenance
+
+When `package.json` bumps the peer pins, re-run this comparison — extract the
+new tarballs and diff the regions above. The fastest canary: stat a file, list
+its directory, and compare the versions (`test/fsio-agent.test.mjs` asserts the
+intra-distro half of this); the strings above are the other half.

package/docs/README.zh.md

@@ -6,7 +6,7 @@
 [![npm](https://img.shields.io/npm/v/dsh-plugin-wsl-env)](https://www.npmjs.com/package/dsh-plugin-wsl-env)
 [![license](https://img.shields.io/npm/l/dsh-plugin-wsl-env)](../LICENSE)
 
-这个插件让 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 把 WSL 发行版当作工作环境：命令在发行版里执行，模型的文件工具读写发行版里的真实文件，文件夹选择器可以直接打开发行版目录，GUI 终端也开在发行版里。
+这个插件让 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 把 WSL 子系统当作工作环境：命令在子系统里执行，模型的文件工具读写子系统里的真实文件，文件夹选择器可以直接打开子系统目录，GUI 终端也开在子系统里。
 
 **只支持 Windows + WSL2。** 安装只需一条命令，插件自身没有依赖。环境按会话生效：打开 Windows 文件夹的会话继续使用原来的 Windows 环境。
 
@@ -26,9 +26,9 @@ dsh --profile wsl                                  # 4. 启动
 
 第 3 步应该打印出名为 `# == dsh-plugin-wsl-env` 的层，并且 `- id: terminal-controller` 上应出现 `shell: { path: wsl.exe, name: WSL }`。这个包是 DSH bundle，所以第 2 步会把 [`cordis.patch.yml`](../cordis.patch.yml) 作为配置层施加进去，没有任何需要手工合并的补丁。
 
-然后在 GUI 里打开 `\\wsl.localhost\<发行版>\...` 下的文件夹。选择器会在根一级列出每个已安装的发行版，**New terminal** 会在发行版里打开 shell。
+然后在 GUI 里打开 `\\wsl.localhost\<子系统>\...` 下的文件夹。选择器会在根一级列出每个已安装的子系统，**New terminal** 会在子系统里打开 shell。
 
-还需要在发行版里安装 **bubblewrap**：`sudo apt install bubblewrap`。没有它每条命令都会失败关闭，见[沙箱](#沙箱)。
+还需要在子系统里安装 **bubblewrap**：运行 `npm run bootstrap -- <子系统> --install`（只读检测去掉 `--install`），或直接执行 `wsl.exe -d <子系统> -u root -- apt-get install -y bubblewrap`。没有它每条命令都会失败关闭，见[沙箱](#沙箱)。
 
 卸载：`dsh plugin --profile wsl remove dsh-plugin-wsl-env`。升级：再执行一次同样的 `add` 命令。
 
@@ -36,12 +36,13 @@ dsh --profile wsl                                  # 4. 启动
 
 ## 使用
 
-把 `\\wsl.localhost\ubuntu\home\you\project` 作为工作区打开，然后问模型"我在什么内核上，`/etc/os-release` 里有什么"。它会在发行版里执行 `uname -r` 并读取该文件，不经过 `/mnt/c`，也不复制文件。
+把 `\\wsl.localhost\ubuntu\home\you\project` 作为工作区打开，然后问模型"我在什么内核上，`/etc/os-release` 里有什么"。它会在子系统里执行 `uname -r` 并读取该文件，不经过 `/mnt/c`，也不复制文件。
 
-- **发行版文件夹自动获得发行版环境。** 创建会话时就会绑定 `wsl` preset，所以第一次工具调用就已经正确。
-- **命令**以 `wsl.exe -d <发行版> --cd <Linux 目录> --exec <你的登录 shell> -lc <命令>` 执行，所以你的 `PATH`、`nvm`、`cargo`、`pyenv` 和 rc 配置都生效。shell 不是硬编码的 bash。
-- **文件就是发行版的真实文件。** `/home/you/x` 与 `\\wsl.localhost\ubuntu\home\you\x` 是同一个文件，`/mnt/c/...` 通向 Windows 磁盘。
-- **终端**（右侧栏 → *New terminal*）在发行版里打开会话目录下的 shell。
+- **子系统文件夹自动获得子系统环境。** 创建会话时就会绑定 `wsl` preset，所以第一次工具调用就已经正确。
+- **命令**以 `wsl.exe -d <子系统> --cd <Linux 目录> --exec <你的登录 shell> -lc <命令>` 执行，所以你的 `PATH`、`nvm`、`cargo`、`pyenv` 和 rc 配置都生效。shell 不是硬编码的 bash。
+- **文件就是子系统的真实文件。** `/home/you/x` 与 `\\wsl.localhost\ubuntu\home\you\x` 是同一个文件，`/mnt/c/...` 通向 Windows 磁盘。
+- **终端**（右侧栏 → *New terminal*）在子系统里打开会话目录下的 shell。
+- **端口可见性**：子系统里监听中的端口经 `DSH_WSL_PORTS` 暴露给模型（约每 10 秒刷新）；子系统内启动的 dev server 可由模型直接告知确切 URL（WSL2 的 localhost 转发是平台行为，Windows 侧直接可达）。
 - **模型能看到自己的 shell 环境。** 插件向受管的 `DSH_*` 命名空间注册 `DSH_WSL_DISTRO`、`DSH_WSL_SHELL` 和 `DSH_WSL_HOME`。
 - **权限与 Linux 主机一致。** 权限选择器在 `read-only`、`workspace-write`（默认）和 `danger-full-access` 之间切换。被拒绝的命令或写入会带回"放宽权限"的提议；批准后，这一次调用不加沙箱执行。
 
@@ -51,44 +52,53 @@ dsh --profile wsl                                  # 4. 启动
 
 | 行 | 键 | 默认值 | 说明 |
 |---|---|---|---|
-| `wsl-shell` | `distro` | `''` | 发行版名；空表示用 WSL 的默认发行版 |
+| `wsl-shell` | `distro` | `''` | 子系统名；空表示用 WSL 的默认子系统 |
 | | `sandbox` | `true` | 用 `bubblewrap` 约束命令；`false` 表示不用沙箱 |
 | `wsl-fs` | `distro` | `''` | 同上 |
-| | `restrictToDistro` | `true` | 拒绝指向**其它发行版**共享的路径；`/mnt/c` 属于本发行版内部，不受影响。拒绝码为 `FS_OUTSIDE_DISTRO`，它不是沙箱拒绝，放宽权限也无法解除 |
+| | `restrictToDistro` | `true` | 拒绝指向**其它子系统**共享的路径；`/mnt/c` 属于本子系统内部，不受影响。拒绝码为 `FS_OUTSIDE_DISTRO`，它不是沙箱拒绝，放宽权限也无法解除 |
 | | `sandbox` | `true` | 写入时按策略检查 `writeText` 和 `editText` |
+| | `substrate` | `agent` | 文件工具使用哪种 I/O 基座：`agent` —— 常驻子系统内代理，读写与路径解析直接在 ext4 上完成（原生符号链接、原生权限位，写入 guard 存活到发布时刻，受限策略下由内核强制）；`share` —— 退出项：Windows 侧宿主文件栈走 9p 共享。两种基座使用同一策略围栏；差异详见 [LIMITATIONS.md](LIMITATIONS.md) |
 | `directory-picker-wsl` | `includeHostHome` | `true` | 同时列出 Windows 家目录 |
-| `subprocess-wsl` | `distro` | `''` | GUI 终端开在哪个发行版 |
+| `subprocess-wsl` | `distro` | `''` | GUI 终端开在哪个子系统 |
 
 [`cordis.patch.yml`](../cordis.patch.yml) 是每个随包值的注释参考。[docs/CONFIGURATION.md](CONFIGURATION.md) 列出其余键，包括 `shell`、`loginShell`、`cwd`、`timeoutMs`、`resolveSymlinks`、`preferredDistro` 和 `maxEntries`；[examples/profile.cordis.patch.yml](../examples/profile.cordis.patch.yml) 是一份可照抄的本机层。
 
 ## 沙箱
 
-命令由**发行版内的 `bubblewrap`** 约束，文件写入按同一份策略检查。Windows ACL 沙箱在这里用不了：它的受限令牌完全到不了 WSL。
+命令由**子系统内的 `bubblewrap`** 约束，文件写入按同一份策略检查。Windows ACL 沙箱在这里用不了：它的受限令牌完全到不了 WSL。
 
-| 模式 | 发行版里的命令可以做什么 |
+| 模式 | 子系统里的命令可以做什么 |
 |---|---|
-| `read-only` | 整个发行版只读；`/dev` 是新建的可写挂载（`/dev/null` 与 `/dev/shm` 可用），其余不可写 |
+| `read-only` | 整个子系统只读；`/dev` 是新建的可写挂载（`/dev/null` 与 `/dev/shm` 可用），其余不可写 |
 | `workspace-write` | 在上一行基础上，把会话工作区绑定为可写，并把 `/tmp` 挂成临时目录 |
 | `danger-full-access` | 不加沙箱；用于批准后的放宽权限请求 |
 
 **bubblewrap 是必需项，而且失败是关闭的。** 没有它时，每条受限命令都报 `SANDBOX_UNAVAILABLE`，而不是不受约束地运行。要退出约束就在任一 provider 上设 `sandbox: false`，工具层会如实告诉模型这些操作没有沙箱。
 
-**上报的强制程度是 `partial` 而不是 `full`。** 发行版里的进程仍可经 WSL interop 执行 Windows 程序（例如 `/mnt/c/.../*.exe`），bubblewrap 管不到它。`npm run probe:sandbox` 会在你的机器上演示这条边界。
+**上报的强制程度是 `partial` 而不是 `full`。** 子系统里的进程仍可经 WSL interop 执行 Windows 程序（例如 `/mnt/c/.../*.exe`），bubblewrap 管不到它。`npm run probe:sandbox` 会在你的机器上演示这条边界。
 
 设计见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#sandbox)，插件不做的事情见 [docs/LIMITATIONS.md](LIMITATIONS.md)。
 
+## 配方
+
+- **Git 凭据共享**：让子系统里的 git 使用 Windows 侧的 Git Credential Manager，避免每次输密码：
+  `git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"`
+  （路径按 Windows 侧 Git 的安装位置调整；WSL2 的 localhost 转发是平台行为，子系统内监听的端口 Windows 直接可达。）
+- **路径与性能**：模型看到并操作的是子系统内的 Linux 路径（`/home/...`），写入子系统自身的 ext4；`/mnt/c` 通向 Windows 磁盘但走 9p，大批量小文件操作明显慢——重 IO 的项目请放在子系统文件系统内。`npm run bootstrap -- <子系统>` 会一并报告 ripgrep / inotifywait（搜索与监视的后端）是否就位。
+- **WSLENV 透传**：WSL 只导入 `WSLENV` 中列出的变量。本插件按前缀放行托管的 `DSH_*` 命名空间，其中带 Windows 路径的两个（`DSH_HOME`、`DSH_PROFILE_DIR`）加 `/p` 让 WSL 翻译成 `/mnt/c/...`。`PATH` 故意不透传——否则 Windows 的 PATH 会覆盖子系统自身的 PATH。
+
 ## 常见问题
 
 | 现象 | 原因 | 处理 |
 |---|---|---|
-| 每条命令都报 `SANDBOX_UNAVAILABLE` | 发行版里没有 `bubblewrap` | 执行 `sudo apt install bubblewrap`，或在两个 provider 上都设 `sandbox: false` |
+| 每条命令都报 `SANDBOX_UNAVAILABLE` | 子系统里没有 `bubblewrap` | 执行 `npm run bootstrap -- <子系统> --install`，或在两个 provider 上都设 `sandbox: false` |
 | 命令或写入在会话目录之外被拒绝 | `workspace-write` 的预期行为 | 接受工具给出的放宽权限提示，或把会话直接开在需要的目录上 |
 | 连工作区内的写入也被拒绝 | 会处在 `read-only` 模式 | 切换权限选择器 |
 | `dsh plugin add` 提示"没有激活任何层" | 依赖之前已经装过，`add` 没有需要记录的内容 | 先执行 `dsh plugin --profile wsl remove dsh-plugin-wsl-env`，再装一次 |
 | 终端打开后仍然是 `cmd.exe` | 这一层里的 `terminal-controller` 行没有生效 | 用 `dsh --profile wsl --dump-config` 确认能看到 `shell: { path: wsl.exe, name: WSL }` |
 | 改了 `lib/` 但不生效 | ES module 缓存 | 重启应用 |
-| 用 `link:\\wsl.localhost\...` 安装后符号链接是坏的 | pnpm 无法链接 UNC 路径 | 改成链接 Windows 路径；在发行版内开发时用运行时镜像，见[开发](#开发) |
-| `glob`/`grep` 很慢 | Windows 侧的 ripgrep 在 9p 共享上遍历 | 属于预期，收窄搜索路径，或改用 `bash` 调用发行版内的工具 |
+| 用 `link:\\wsl.localhost\...` 安装后符号链接是坏的 | pnpm 无法链接 UNC 路径 | 改成链接 Windows 路径；在子系统内开发时用运行时镜像，见[开发](#开发) |
+| `glob`/`grep` 很慢 | Windows 侧的 ripgrep 在 9p 共享上遍历 | 属于预期，收窄搜索路径，或改用 `bash` 调用子系统内的工具 |
 | 终端活动显示 `unknown` | 官方 shell 集成只对 POSIX 主机上直接启动的 `bash`/`zsh` 生效 | 关闭标签页以释放进程；空闲回收不会对它触发 |
 | 结果里出现 `FS_*` 码 | 码本身说明了是谁拒绝的、以及怎样解除 | 见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#error-codes) 的错误码表 |
 
@@ -97,10 +107,11 @@ dsh --profile wsl                                  # 4. 启动
 ```bash
 npm test                     # 风格与打包检查、语法检查、单元测试
 npm run test:coverage        # 带覆盖率阈值的单元测试（需 Node 22.8+）
-npm run probe:sandbox        # 在发行版里实测 bubblewrap 能约束什么、不能约束什么
-npm run probe                # 文件系统探针，需要真实发行版（仅 Windows + WSL）
+npm run probe:sandbox        # 在子系统里实测 bubblewrap 能约束什么、不能约束什么
+npm run probe                # 文件系统探针，需要真实子系统（仅 Windows + WSL）
 npm run probe:sandbox-shell  # 启动真实 harness，驱动受限执行器
 npm run probe:terminal       # 通过终端 provider 打开一个 PTY
+npm run probe:substrate      # 用真实 wsl.exe 传输驱动 agent 文件基座（在子系统内运行）
 npm run probe:missing-wsl    # 启动一个 wslPath 无法启动的 profile（仅 Windows + WSL）
 npm run probe:picker         # 列出选择器的根级、拒绝路径与上限（仅 Windows + WSL）
 npm run probe:mode           # 哪些 POSIX 权限事实能穿过共享层（仅需 Windows node）

package/docs/UPSTREAM-FSIO-EXPORT.md

@@ -0,0 +1,87 @@
+# Upstream proposal: export the fsio module from `dsh-fs-local`
+
+Status: draft, targeting `deepseek-harness` @ `packages/fs/fs-local` (version
+line `0.2.0-rc.x`). This is the Shape-A upstream half of the in-distro I/O
+refactor: with the fsio module exported, `dsh-plugin-wsl-env` deletes its
+in-plugin replicas (`lib/fsio-text.js`) and imports the originals.
+
+## The change
+
+The fsio module already exists, is fully documented, and is pure (no peers
+beyond types). It is only not reachable: `package.json` exports `"."` and
+`"./package.json"`, and `lib/index.js` does not re-export the helpers. Two
+lines of surface, no behaviour change:
+
+```diff
+--- a/packages/fs/fs-local/package.json
++++ b/packages/fs/fs-local/package.json
+@@
+   "exports": {
+     ".": {
+       "types": "./lib/types/index.d.ts",
+       "default": "./lib/index.js"
+     },
++    "./fsio": {
++      "types": "./lib/types/fsio.d.ts",
++      "default": "./lib/fsio.js"
++    },
+     "./src/*": "./src/*",
+     "./package.json": "./package.json"
+   },
+```
+
+```diff
+--- a/packages/fs/fs-local/lib/index.js
++++ b/packages/fs/fs-local/lib/index.js
+@@
+-export { LocalFileSystem, LocalFileSystem as default };
++export {
++  LocalFileSystem,
++  LocalFileSystem as default,
++  applyLiteralEdit,
++  detectLineEndings,
++  normalizeLineEndings,
++  restoreLineEndings,
++};
+```
+
+(The module layout differs between the repo's `src/` and the built `lib/`;
+the export list is what matters. `readForEdit` and `readTextForDiff` stay
+internal — they are I/O orchestration, which the plugin drives against its own
+substrate — only the pure text mechanics are needed.)
+
+## Why the plugin needs it
+
+`dsh-plugin-wsl-env`'s agent substrate (`lib/fsio-agent.js`,
+`lib/fs-substrate.js`) re-runs fsio's orchestration inside a WSL distro: reads,
+writes, identities and edits execute where the files live, and the host side
+keeps only the validation and edit mechanics. Those mechanics —
+`applyLiteralEdit`, the line-ending trio, the binary NUL sample, the fatal UTF-8
+decode — are replicated today (`lib/fsio-text.js`) because the package does not
+export them. The replica is byte-for-byte faithful, including error messages,
+because the tool layer matches on both the code and the text the model reads;
+but a replica is a fork surface: every upstream change to the edit algorithm
+has to be re-ported by hand.
+
+With the export in place the plugin deletes `lib/fsio-text.js` and imports:
+
+```js
+import { applyLiteralEdit, detectLineEndings, normalizeLineEndings, restoreLineEndings } from "@deepseek-ai/dsh-fs-local/fsio";
+```
+
+## Why this is safe upstream
+
+- No new API surface beyond re-exporting functions that already exist and are
+  documented in `lib/types/fsio.d.ts`.
+- No behaviour change: the class's own call sites are untouched.
+- The functions are pure (text in, text out, structured errors), so exporting
+  them cannot widen the I/O contract.
+- Semver: additive export, a minor bump.
+
+## Follow-up (separate proposal, not required)
+
+A larger seam — parameterizing `LocalFileSystem`'s fsio call sites so a
+subclass can substitute an I/O substrate — would let integrations inherit the
+whole backend instead of re-running its orchestration. The export above is the
+prerequisite and is sufficient on its own; the parameterization is worth
+discussing only after a consumer exists in the wild.

package/lib/agent-confined.js

@@ -0,0 +1,81 @@
+/**
+ * Confined residents: one long-lived agent per (distro, policy) pair, running
+ * its WHOLE lifetime inside the bwrap profile that policy asks for — so every
+ * filesystem op it performs is enforced by the kernel's mount table, not just
+ * by the host-side check that chose it.
+ *
+ * This is stage two of the substrate's enforcement story. Stage one routed
+ * every op through the plain agent with the policy check deciding what may
+ * pass; stage two routes *mutations* to a confined resident whose view of the
+ * filesystem already matches the granted rights, so a bug in the check cannot
+ * become a write outside the workspace — the kernel refuses it.
+ *
+ * Keying is the whole design: the profile is fixed for an agent's lifetime,
+ * so a change in the policy (the Permissions selector, a session move) simply
+ * addresses a different key, and the previous resident retires through its own
+ * idle timer. Escalated writes (`danger-full-access`) keep addressing the
+ * plain agent, which is what an approved escalation means.
+ *
+ * The argv it hands the transport is a whole command — program, profile, `--` —
+ * assembled by the peer-free `lib/bwrap.js`, which both confinement sites share.
+ * That import is why this module needs no DSH peer either: a bare checkout can
+ * construct the factory and assert the command it produces, which is what
+ * `test/agent.test.mjs` does. It used to import the sandbox's own profile
+ * builder and assemble the prefix itself, missing the program; the probe inlined
+ * a third copy, so nothing compared production's command with a working one and
+ * every confined mutation failed the resident's handshake.
+ *
+ * @module dsh-plugin-wsl/agent-confined
+ */
+import { fileURLToPath } from "node:url";
+import { bwrapArgvPrefix } from "./bwrap.js";
+import { toLinuxPath } from "./paths.js";
+import { WslAgent } from "./agent.js";
+
+const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.meta.url));
+const confinedAgents = new Map();
+
+/**
+ * The confined agent for one distro and one resolved policy, created on first
+ * use and shared for the process lifetime. A success is remembered; a failed
+ * start is not (the agent's own rebuild rules take over from there).
+ *
+ * @param {object} request - the confinement request.
+ * @param {string} request.distro - the distro to run in.
+ * @param {string} [request.wslPath] - the `wsl.exe` path.
+ * @param {{mode: string, workspaceRoot: string}} request.policy - the RESOLVED
+ *   file-effect policy: the profile binds exactly what the mode grants.
+ * @param {boolean} [request.maskWindowsDrive] - shadow `/mnt` with an empty
+ *   tmpfs in the resident's profile; part of the cache key, since it changes
+ *   the mount table the resident lives under.
+ * @returns {WslAgent} the confined resident for this key.
+ */
+export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindowsDrive = false }) {
+  const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}`;
+  let agent = confinedAgents.get(key);
+  if (agent === undefined) {
+    agent = new WslAgent({
+      distro,
+      wslPath,
+      scriptPath: toLinuxPath(AGENT_SCRIPT_PATH),
+      // The prefix is a whole command from the distro's point of view — program,
+      // profile, `--` — because the transport inserts it between
+      // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s
+      // `spawnDefault`). Both confinement sites share that assembly in
+      // `lib/bwrap.js`, whose module doc records what happened when they did not.
+      argvPrefix: bwrapArgvPrefix(
+        { mode: policy.mode, workspaceRoot: toLinuxPath(policy.workspaceRoot, { distro }) },
+        { maskWindowsDrive },
+      ),
+    });
+    confinedAgents.set(key, agent);
+  }
+  return agent;
+}
+
+/** Test hook: forget every confined resident (the plain agent has no factory state). */
+export function resetConfinedAgents() {
+  confinedAgents.clear();
+}
+
+export default confinedAgent;

package/lib/agent-errors.js

@@ -0,0 +1,33 @@
+/**
+ * The error a {@link WslAgent} rejects with when the resident process is out
+ * for this host process — the executor's cue to fall back to the one-shot
+ * `wsl.exe` path. Deliberately its own class: callers must not confuse
+ * "the agent cannot serve" with a failure of the command itself.
+ *
+ * @module dsh-plugin-wsl/agent-errors
+ */
+export class AgentUnavailableError extends Error {
+  /**
+   * @param {string} message - why the agent is out, for the log.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "AgentUnavailableError";
+  }
+}
+
+/**
+ * The request's workdir could not be entered inside the distro. Carries the
+ * Linux path so a caller can synthesize the same diagnostic the one-shot
+ * `wsl.exe` path produces from the relay's `chdir(...) failed` text.
+ */
+export class CwdError extends Error {
+  /**
+   * @param {string} linuxPath - the path that could not be entered.
+   */
+  constructor(linuxPath) {
+    super(`could not enter working directory "${linuxPath}"`);
+    this.name = "CwdError";
+    this.linuxPath = linuxPath;
+  }
+}