dsh-plugin-wsl-env 0.16.0 → 0.17.1

package/CHANGELOG.md

@@ -14,7 +14,63 @@ document: the 0.1.0 entry's `design-history §` references are to
 keeps the superseded designs under the section numbers they had while they
 were part of the record.
 
-## [Unreleased]
+## [0.17.0] - 2026-11-01
+
+### Changed
+
+- **Git snapshot spawns are now agent-first with a one-shot fallback.**
+  Protocol v6 adds a stdin payload to the EXEC frame (a seventh header field
+  flagging one trailing base64 line), which is what lets `workspace-changes`'
+  snapshot calls — including `check-ignore -z --stdin` — run on the warm
+  resident agent instead of a one-shot `wsl.exe`. Measured on `ubuntu`
+  (2026-11-01): ~232 ms per one-shot git call (nearly all `wsl.exe` process
+  startup) against ~1.6 ms on the resident — a 6-8 call snapshot saves well
+  over a second. The per-stream caps map onto the agent's single wire cap with
+  a client-side per-stream slice (`lib/git-exec.js`), and the environment
+  rides the agent's per-request `env` (`env --` argv prefix, no `SETENV`
+  pollution) carrying only the translated `GIT_*` names. Both agents speak v6
+  (the shell agent decodes the payload through command substitution, which
+  strips trailing newlines — NUL separators survive; the native binary
+  delivers bytes verbatim), so host library and shipped binaries upgrade
+  together; the doctor's handshake reports any mismatch.
+
+- **WSL change review no longer requires Windows git.** When
+  `resolveExecutable('git')` fails on the host, the provider answers with a
+  distro sentinel (`/usr/bin/git`); every workspace-changes spawn — the
+  `rev-parse` discovery included — then routes into the distro, and the
+  snapshot facade translates the discovery call's absolute-path output lines
+  into UNC form (`translateDiscoveryOutput`). A machine with Windows git is
+  unchanged (host discovery + `safe.directory` whitelist). The
+  `resolveExecutable` override is scoped to the one name and only fires on
+  the super's failure.
+
+- **The doctor probes the Windows git trust.** A new `git.win-safe` check
+  reports the `safe.directory` whitelist state through interop `git.exe`:
+  `ok` when the `\\wsl.localhost` share is whitelisted, a warn with the
+  copy-paste remedy when Windows git does not trust it, and an info (nothing
+  to do) when there is no Windows git — the distro fallback covers WSL change
+  review entirely.
+
+### Documentation
+
+- The architecture and upstream-promotion documents reflect the v6 protocol
+  and the shell-menu candidates; the promotion map records the measurement
+  that superseded the git one-shot decision.
+- The full real-machine suite re-ran 15/0 on 2026-11-01 after the protocol
+  change landed, and again after the documentation refresh. The safe.directory
+  prerequisite for WSL change review is now documented with its one-time
+  remedy.
+
+- **The shell menu now offers host shells instead of a single entry.**
+  `terminal-controller`'s `shellCandidates` grows from `[]` to
+  `[wsl.exe, powershell, cmd]` while the default profile stays
+  `shell: { path: wsl.exe, name: WSL }`. `wsl.exe` dedupes into the default's
+  `wsl` kind; `powershell` and `cmd` are launches this terminal really starts —
+  host sessions already run PowerShell outright (`hostSessions`), and a manually
+  selected shell is titled after itself, which moves the tab-title workaround
+  from a user-layer edit into the plugin's own composition
+  ([#8769](https://github.com/deepseek-ai/deepseek-harness/discussions/8769)
+  remains the real fix for the default entry's title).
 
 ## [0.16.0] - 2026-10-31
 

package/agent/wsl-agent.sh

@@ -24,8 +24,12 @@
 #   SETENV|<key>|<b64 value>      -> export the variable for later requests;
 #                                    <key> must be a POSIX identifier, else
 #                                    ERR|protocol
-#   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>|<output cap bytes|0>
-#       followed by <n args> lines of base64, one argv word each
+#   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>|<output cap bytes|0>|<stdin flag|0>
+#       followed by <n args> lines of base64, one argv word each, and — when
+#       the stdin flag is 1 — one more base64 line: the child's entire stdin.
+#       The agent feeds those bytes to the child and closes its stdin, so the
+#       child sees EOF at the payload's end. Absent or 0 means the child reads
+#       an empty stdin and immediate EOF (the v5 shape).
 #       -> ACK|<id> the moment the request is dequeued for execution — the host
 #          arms its stuck-request watchdog on this line, so time spent queued
 #          behind an earlier request never counts against a budget
@@ -62,7 +66,14 @@
 
 set -u
 
-PROTO_VERSION=5
+# v6: EXEC gains an optional seventh header field flagging one stdin payload
+# line after the argv words. One documented limitation, the same one SETENV
+# and every argv word already carry: command substitution strips TRAILING
+# NEWLINES from the decoded payload, so a stdin feed ending in `\n` reaches
+# the child without it (NUL bytes — `check-ignore -z` separators — survive).
+# Every known consumer parses line-oriented stdin that tolerates a missing
+# final newline.
+PROTO_VERSION=6
 TMPDIR_AGENT=$(mktemp -d "${TMPDIR:-/tmp}/wsl-agent.XXXXXX")
 OUT_FILE="$TMPDIR_AGENT/out"
 ERR_FILE="$TMPDIR_AGENT/err"
@@ -254,16 +265,23 @@ run_capture() {
     fi
   fi
   CURRENT_ID=$req_id
+  # Protocol v6 stdin: when the EXEC dispatch staged a payload file, the child
+  # reads its bytes and sees EOF at the file's end; otherwise /dev/null keeps
+  # the child off the agent's own stdin (the host pipe).
+  spawn_in=/dev/null
+  if [ -n "${EXEC_STDIN:-}" ]; then
+    spawn_in=$EXEC_STDIN
+  fi
   # The inflight marker pauses the lease watchdog for this request and
   # refreshes the temp dir's mtime for the boot sweep; removing it after the
   # answer re-arms both.
   : >"$TMPDIR_AGENT/inflight"
   if [ "$mode" = subshell ]; then
-    ( "$@" ) >"$spawn_out" 2>"$spawn_err" &
+    ( "$@" ) >"$spawn_out" 2>"$spawn_err" <"$spawn_in" &
   elif [ -n "$SETSID" ]; then
-    ( exec setsid "$@" ) >"$spawn_out" 2>"$spawn_err" &
+    ( exec setsid "$@" ) >"$spawn_out" 2>"$spawn_err" <"$spawn_in" &
   else
-    "$@" >"$spawn_out" 2>"$spawn_err" &
+    "$@" >"$spawn_out" 2>"$spawn_err" <"$spawn_in" &
   fi
   CURRENT_PID=$!
   # Dispatched: the child exists now, so the host may arm its execution
@@ -675,7 +693,18 @@ while IFS= read -r line; do
       timeout_s=${rest%%|*}
       rest=${rest#*|}
       nargs=${rest%%|*}
-      maxout=${rest#*|}
+      rest=${rest#*|}
+      maxout=${rest%%|*}
+      # Protocol v6: an optional seventh field flags one stdin payload line
+      # after the argv words. Absent (a stale peer) or 0 keeps the v5 shape —
+      # the child reads an empty stdin and immediate EOF.
+      stdin_flag=0
+      case $rest in
+        *\|*) stdin_flag=${rest#*|} ;;
+        *) stdin_flag=0 ;;
+      esac
+      case $stdin_flag in ''|*[!01]*) stdin_flag=0 ;; esac
+      EXEC_STDIN=
       cwd=$(b64dec "$cwd_b64")
       if ! cd "$cwd" 2>/dev/null; then
         printf 'ERR|%s|cwd|%s\n' "$req_id" "$(printf '%s' "$cwd" | base64 | tr -d '\n')"
@@ -704,9 +733,20 @@ while IFS= read -r line; do
         printf 'ERR|%s|protocol|%s\n' "$req_id" "$(printf '%s' "an argv payload failed to decode" | base64 | tr -d '\n')"
         continue
       fi
+      if [ "$stdin_flag" = 1 ]; then
+        IFS= read -r stdin_b64 || exit 0
+        if ! b64dec_strict "$stdin_b64"; then
+          printf 'ERR|%s|protocol|%s\n' "$req_id" "$(printf '%s' "the stdin payload failed to decode" | base64 | tr -d '\n')"
+          continue
+        fi
+        EXEC_STDIN="$TMPDIR_AGENT/stdin.$req_id"
+        printf '%s' "$DEC" >"$EXEC_STDIN"
+      fi
       # Dispatched: run_capture prints the ACK once the child exists, so the
       # host's watchdog and USR1 cancel both target a real process.
       run_capture "$req_id" "$timeout_s" "$maxout" exec "$@"
+      [ -n "$EXEC_STDIN" ] && rm -f -- "$EXEC_STDIN"
+      EXEC_STDIN=
       ;;
     FS\|*)
       header=${line#FS|}

package/cordis.patch.yml

@@ -36,17 +36,20 @@
 #      `wsl.exe -d <distro> --cd <linux dir>` for the directory the Session
 #      supplies. Ordinary `spawn()` — every command, the host ripgrep search,
 #      every other consumer — reaches the shipped implementation untouched;
-#   2. the controller is given the one shell profile it should resolve, so the
-#      window's default is a distro shell rather than `cmd.exe` inside a UNC
-#      workspace. Its shell menu is reduced to that single entry on purpose:
-#      shell discovery also runs against the root provider and receives no
-#      directory, so offering host executables there would advertise shells this
-#      terminal never starts.
+#   2. the controller is given the composition's default shell profile (the
+#      distro shell, so a directory-less launch lands in the distro rather than
+#      `cmd.exe` inside a UNC workspace) plus host candidates. The default must
+#      stay static — the controller resolves it without a Session — but the
+#      candidates make the shell menu honest: `wsl.exe` dedupes into the
+#      default's `wsl` kind, and `powershell`/`cmd` are launches this terminal
+#      really starts (host sessions run PowerShell outright, and a manually
+#      selected shell is titled after itself — the sanctioned bridge over the
+#      fixed tab title, see docs/UPSTREAM-TERMINAL-TITLE.md).
 #
 # Consequence: a terminal's EXECUTION WORLD follows the Session — a WSL-folder
 # session runs the distro's shell, a Windows-folder session runs PowerShell in
-# its own directory (`hostSessions` on `subprocess-wsl`) — while the shell menu
-# and the tab title stay the composition's single `WSL` profile, which no
+# its own directory (`hostSessions` on `subprocess-wsl`) — while the DEFAULT
+# entry and its title stay the composition's single `WSL` profile, which no
 # Session identity reaches. The title that implies is documented in
 # docs/LIMITATIONS.md and bridged upstream in docs/UPSTREAM-TERMINAL-TITLE.md.
 # ═════════════════════════════════════════════════════════════════════════════
@@ -60,7 +63,10 @@
       path: wsl.exe
       name: WSL
       args: []
-    shellCandidates: []
+    shellCandidates:
+      - wsl.exe
+      - powershell
+      - cmd
 
 - insert:
     - id: subprocess-wsl

package/docs/ARCHITECTURE.md

@@ -109,9 +109,15 @@ So the layer disables the shipped `subprocess` row and inserts
 `dsh-plugin-wsl-env/subprocess` in its place at the app level. The subclass
 overrides two methods: `spawnTerminal` rewrites a `wsl.exe` launch into
 `wsl.exe -d <distro> --cd <linux dir>`, and `spawn()` rewrites two kinds of
-launches into the distro — the file-search tool's packaged ripgrep (agent-first,
-with the one-shot `wsl.exe --exec` handle as the fallback when the agent is out)
-and git snapshot commands. Both spawn decisions are pure coordinate functions
+launches into the distro — the file-search tool's packaged ripgrep and git
+snapshot commands (each agent-first on the warm resident — protocol v6 carries
+a git call's stdin, and a one-shot call costs ~230 ms of `wsl.exe` startup
+against the resident's ~2 ms — with the one-shot `wsl.exe --exec` handle as
+the fallback when the agent is out). When the HOST has no git,
+`resolveExecutable` answers git with a distro sentinel path, and the snapshot
+command's discovery call (`rev-parse --show-toplevel ...`) routes too, its
+absolute-path output translated back into UNC form — so full WSL change review
+works without Windows git. Both spawn decisions are pure coordinate functions
 (`lib/search-route.js`, `lib/git-route.js`); every other `spawn()` — including
 the one-shot fallback's own `wsl.exe -lc <command>` (the default agent path
 carries the command over the resident instead of spawning) — reaches the shipped
@@ -120,9 +126,11 @@ implementation untouched, as do the pwsh executor and the LSP host.
 The terminal's execution world follows the session (`hostSessions`, default on):
 a WSL-folder session runs the distro shell, a Windows-folder session runs
 `powershell.exe` in its own directory. What still follows the app configuration
-is the shell menu and the tab title, both derived from the composition's single
-`WSL` shell profile — so a host session's tab reads `WSL` over a PowerShell
-process. See [LIMITATIONS.md](LIMITATIONS.md) and
+is the shell menu's DEFAULT entry and its title, both derived from the
+composition's single `WSL` shell profile — so a new tab reads `WSL` whatever it
+runs, including a host session's PowerShell. The menu also lists host
+candidates (`powershell`, `cmd`; `wsl.exe` dedupes into the default), and a
+manually selected shell is titled after itself. See [LIMITATIONS.md](LIMITATIONS.md) and
 [UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md).
 
 ## Path coordinates

package/docs/CONFIGURATION.md

@@ -1,5 +1,7 @@
 # Configuration
 
+*A Chinese translation lives at [CONFIGURATION.zh](CONFIGURATION.zh.md); the English version is authoritative.*
+
 ## Profile patches
 
 Store profile settings in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. Use
@@ -154,6 +156,27 @@ With `agent: true`, captured output is limited inside the distro and no spill
 file is written. `maxSpillBytes` and `graceMs` apply when `agent: false` or
 when the resident agent is unavailable and execution uses one-shot `wsl.exe`.
 
+### zsh/fnm recipe for model-run commands
+
+Commands run as `<shell> -lc`, so `~/.zshrc` is never read — see
+[LIMITATIONS](LIMITATIONS.md#shell-startup-semantics-wsl-shell) for why. Put
+fnm's hook in `~/.zprofile` instead, with a fallback for the sandbox, where
+`/run` is read-only and fnm cannot create its multishell symlink directory:
+
+```zsh
+# ~/.zprofile — fnm for non-interactive login shells (mirrors the ~/.zshrc hook)
+path=("$HOME/.local/share/fnm" $path)  # the fnm binary itself
+_fnm_env="$(command -v fnm &>/dev/null && fnm env --shell zsh 2>/dev/null)" && eval "$_fnm_env"
+if [[ -z "${FNM_MULTISHELL_PATH:-}" || ! -e "${FNM_MULTISHELL_PATH}/bin/node" ]]; then
+  path=("$HOME/.local/share/fnm/aliases/default/bin" $path)  # sandbox fallback
+fi
+unset _fnm_env
+```
+
+Interactive terminals keep the hook in `~/.zshrc` and are unaffected; the
+`aliases/default` fallback only takes over where the multishell link cannot
+exist.
+
 ## Environment forwarding
 
 WSL imports a host environment variable only when its name is listed in

package/docs/CONFIGURATION.zh.md

@@ -0,0 +1,288 @@
+# Configuration
+
+_本文是 [CONFIGURATION](CONFIGURATION.md) 的中文译本，以英文版为准。_
+
+## Profile patch
+
+profile 设置存放在 `$DSH_HOME/profiles/<name>/cordis.patch.yml`。可以用
+[`examples/profile.cordis.patch.yml`](../examples/profile.cordis.patch.yml)
+作为起点。随包的
+[`cordis.patch.yml`](../cordis.patch.yml) 列出了本插件附带的行和值。
+
+profile 层可以按 `id` 指向顶层行。这一层的插件行包括 `fs-routing`、
+`directory-picker-wsl`、`subprocess-wsl`、`wsl-shell-env`、`wsl-preflight`、
+`auto-preset` 和 `preset-wsl`。`wsl-shell` 和 `wsl-fs`
+两行嵌套在 `preset-wsl.config.plugins` 内；直接按这两个 id 配置的
+profile 条目会被忽略，并产生 `patch: entry <id> not found` 警告。
+
+一行的 `config` 是整体替换。如果你想保留随包行中的非默认值，
+必须把它们一并写入。这对 `preset-wsl` 尤其重要：
+它的 config 包含完整的 preset 及其嵌套插件。
+
+在下表中，**shipped** 表示该值在随包行中被显式设置。
+其他值是 schema 默认值。省略的键使用 schema 默认值。
+
+## 配置 `wsl-shell` 和 `wsl-fs`
+
+这两行嵌套在 `preset-wsl` 内。使用辅助脚本修改它们的设置：
+
+```bash
+pnpm run preset --distro Ubuntu --session-sandbox false
+```
+
+支持的修改是 `--distro`、`--session-sandbox`、`--sandbox`、
+`--mask-windows-drive` 和 `--agent-backend`。不带 `--out` 时，辅助脚本
+把完整的 `preset-wsl` 块打印出来，供你手动合并进 profile。
+使用 `pnpm run preset --check <file>` 可以检测直接指向嵌套行的
+profile 层；检测到时会打印应使用的块。`--out` 会整体替换目标文件，
+包括其中的其他覆盖，即使它已经包含 `preset-wsl` 行。
+在不包含该行的文件已存在时，替换会被拒绝，除非传入 `--force`。
+对已有 profile 建议手动合并。
+
+要手动编辑 preset，需替换整个 `preset-wsl` 行。它的 config
+不做深度合并：保留 `id`、`order` 以及 `plugins` 中的每一项。
+从 `cordis.patch.yml` 或 `dsh --profile <name> --dump-config`
+复制当前块，再修改嵌套的值。插件升级改变了 preset 后要重新复制。
+
+### `wsl-shell`
+
+| 键 | 默认 / shipped 值 | 说明 |
+|---|---|---|
+| `distro` | `''`（shipped） | 空或 `auto` 跟随请求工作目录所属的发行版。`default` 选择 WSL 默认发行版；给出名字则把命令固定到该发行版。 |
+| `shell` | `''` | 空则解析发行版用户的登录 shell。设置绝对 Linux 路径可固定一个 shell。 |
+| `loginShell` | `true`（shipped） | 对 POSIX shell 使用登录语义。非 POSIX shell 使用各自的命令形式。 |
+| `agent` | `true` | 使用常驻 agent。不可用时，命令走一次性的 `wsl.exe` 路径。设为 `false` 则总是走该路径。Cwd 与沙箱拒绝会被直接返回。 |
+| `agentBackend` | `auto`（shipped） | `auto` 选择包内 `agent/native/linux-<arch>/dsh-wsl-agent` 的静态 musl 二进制或 `DSH_WSL_AGENT_NATIVE` 覆盖；否则使用 shell agent。`native` 在准备失败时报错；`shell` 强制使用 shell agent。适用于命令、受限写入和共享读取。 |
+| `sessionSandbox` | `false`；shipped 为 `true` | `true` 把会话跑在一个持久的 systemd user scope 中。要求 `agent: true`、systemd 为 PID 1（`/etc/wsl.conf` 中 `[boot] systemd=true`）、一个 user manager、`systemd-run` 和 Linger（`loginctl enable-linger <user>`）。`false` 使用按命令的沙箱。`auto` 在可用时使用 scope，否则按命令约束。结果会报告 `sessionScope: 'session'` 或 `'per-command'`。 |
+| `sandbox` | `true` | 用 `bwrap` 约束命令。`bwrap` 缺失或不可用时关闭（fail closed）。`false` 则不加约束地运行命令。 |
+| `interopVisibility` | 未设置；有效默认值为 `visible` | `visible`、`masked` 或 `disabled`。设置后优先于 `maskWindowsDrive`。见 [Windows interop](#windows-interop)。 |
+| `maskWindowsDrive` | `false` | 对受限命令，在 `/mnt` 上挂载空的 tmpfs。见 [Windows interop](#windows-interop)。 |
+| `cwd` | `''` | 默认工作目录。空则使用发行版用户家目录。 |
+| `timeoutMs` / `maxTimeoutMs` | `120000` / `600000`（shipped） | 默认的单次调用超时，以及一次调用可请求的最大超时。 |
+| `wslPath` | `wsl.exe` | `wsl.exe` 的路径。 |
+| `hostCwd` | 未设置 | `wsl.exe` 进程的 Windows 工作目录。可用时默认为 `%SystemRoot%`。 |
+| `forwardEnv` | `[]` | 额外通过 `WSLENV` 转发的宿主环境变量名。见 [环境变量转发](#environment-forwarding)。 |
+
+### `wsl-fs`
+
+| 键 | 默认 / shipped 值 | 说明 |
+|---|---|---|
+| `distro` | `''`（shipped） | 空或 `auto` 跟随目标路径所属的发行版。`default` 选择 WSL 默认发行版；给出名字则固定文件系统。 |
+| `restrictToDistro` | `true`（shipped） | 固定发行版时，以 `FS_OUTSIDE_DISTRO` 拒绝属于其他发行版共享的路径。 |
+| `sandbox` | `true` | 按沙箱策略检查写入。`bwrap` 不可用时，受限写入关闭（fail closed）。 |
+| `sessionSandbox` | `false`；shipped 为 `true` | 使用与 `wsl-shell` 相同的会话 runtime。`auto` 在会话 runtime 不可用时回退到按策略约束的常驻 agent。 |
+| `maskWindowsDrive` | `false` | 对受限变更隐藏 `/mnt`。读取不受影响。 |
+| `substrate` | `agent`（shipped） | 文件操作使用发行版内 agent。旧值 `share` 在启动时被拒绝。 |
+| `cwd` | `''` | 相对路径的基准目录。空则使用发行版用户家目录。 |
+| `watchMaxDepth` | `0` | 监视整棵树。正值深度使用有界轮询，可能遗漏边界以下的变更，直到边界之上发生变更触发回调。 |
+| `wslPath` | `wsl.exe` | `wsl.exe` 的路径。 |
+| `diffBasisMaxBytes` | `10485760` | 覆盖写入 diff 每一侧的 UTF-8 字节上限。更大的文件不带 diff 直接写入。 |
+
+### `fs-routing`
+
+这个顶层行为根级 `ctx.fs` 调用提供服务。它把发行版 UNC 路径
+路由到 agent 支撑的文件系统，把盘符路径路由到宿主文件系统。它的
+发行版设置独立于 `wsl-fs`。
+Loader 在挂载该行之前会校验宿主和发行版设置；
+被 schema 拒绝的值会阻止路由器启动。字段值为 `null`
+时使用其 schema 默认值。
+
+| 键 | 默认 / shipped 值 | 说明 |
+|---|---|---|
+| `distro` | `''`（shipped） | 空或 `auto` 把每条 UNC 路径路由到其命名的发行版。`default` 选择 WSL 默认发行版；给出名字则固定路由。 |
+| `wslPath` | `wsl.exe`（shipped） | `wsl.exe` 的路径，用于解析默认发行版。 |
+| `sandbox` | `true`（shipped） | 按 `ctx.sandboxPolicy` 检查被路由的变更；`bwrap` 不可用时关闭（fail closed）。无论该围栏启用与否，该行都报告 `sandboxMode: undefined`。 |
+| `maskWindowsDrive` | `false`（shipped） | 对受限的被路由变更隐藏 `/mnt`。 |
+| `restrictToDistro` | `true`（shipped） | `distro` 被固定时，拒绝属于其他发行版共享的路径。 |
+| `watchMaxDepth` | `0`（shipped） | 监视整棵树。正值深度使用有界轮询。 |
+| `distroCwd` | `''` | 默认发行版工作目录；空则使用发行版用户家目录。 |
+| `cwd` | `process.cwd()` | 宿主文件系统后端的工作目录。 |
+| `diffBasisMaxBytes` | `10485760` | 宿主与被路由后端共享的覆盖写入 diff 上限。 |
+
+根路由器是应用层的，不属于会话，因此不使用
+`sessionSandbox`。
+
+### 选择器与终端行
+
+| 行 | 键 | 默认 / shipped 值 | 说明 |
+|---|---|---|---|
+| `directory-picker-wsl` | `preferredDistro` | `''`（shipped） | 首位展示的发行版，也是 Home 位置使用的发行版。 |
+| | `includeHostHome` | `true`（shipped） | 包含 Windows 家目录。 |
+| | `maxEntries` | `1000`（shipped） | 单个目录返回的最大条目数。 |
+| | `wslPath` | `wsl.exe` | `wsl.exe` 的路径。 |
+| | `distroCacheMs` | `5000` | 发行版列表的缓存时长。 |
+| `subprocess-wsl` | `distro` | `''`（shipped） | 空或 `auto` 跟随启动目录所属的发行版。`default` 选择 WSL 默认；给出名字则固定发行版。 |
+| | `shell` | `''` | 在发行版内固定的 shell。空则由 `wsl.exe` 选择登录 shell。 |
+| | `loginShell` | `true` | 固定 shell 时的登录语义。 |
+| | `hostSessions` | `true` | 在 Windows 文件夹上打开的会话，会在该文件夹中获得宿主 PowerShell。WSL 文件夹会话使用发行版 shell。设为 `false` 则所有会话都使用 composition 拥有的终端。 |
+| | `terminalIdleReclaim` | `true` | 依据被标记的进程回收空闲的发行版终端。活动状态未知时暂停回收。 |
+| | `cwd` | `''` | 未提供启动目录时的回退目录。 |
+| | `wslPath` | `wsl.exe` | `wsl.exe` 的路径。 |
+| | `hostCwd` | 未设置 | `wsl.exe` 进程的 Windows 工作目录。可用时默认为 `%SystemRoot%`。 |
+| | `forwardEnv` | `[]` | 额外通过 `WSLENV` 转发的宿主环境变量名。 |
+
+### 其他顶层行
+
+| 行 | 键 | 默认值 | 说明 |
+|---|---|---|---|
+| `auto-preset` | `preset` | `wsl` | 会话工作区位于发行版内时绑定的 preset。操作者的显式选择会被保留。 |
+| | `attempts` | `6` | 绑定 preset 的尝试次数。 |
+| | `retryMs` | `150` | 两次尝试之间的延迟，单位毫秒。 |
+| `wsl-preflight` | `distro` | `''` | 要检查的发行版。空或 `auto` 跟随会话工作区。 |
+| | `wslPath` | `wsl.exe` | `wsl.exe` 的路径。 |
+| | `sandbox` | `true` | 运行会话启动时的 `bwrap` 检查。 |
+| | `sessionSandbox` | `true` | 同时检查 systemd、user manager、`systemd-run` 和 Linger。profile 不使用会话 runtime 时设为 false。 |
+| `wsl-shell-env` | `distro` | `''` | 用于填充 `DSH_WSL_*` 环境事实的发行版。 |
+| | `portsRefreshMs` | `10000` | 监听端口快照的刷新间隔，单位毫秒。 |
+
+GUI 文件树和预览通过 `fs-routing` 使用随包的 `workspace-files` 行；
+它们不使用单独的 WSL 提供者行。要修改其 peer 定义的限额，
+在 profile 层按 id 覆盖 `workspace-files`。
+
+## 共享的命令设置
+
+shell 行从 `@deepseek-ai/dsh-bash-local` 继承输出与进程设置：
+
+| 键 | 默认值 | 说明 |
+|---|---|---|
+| `maxOutputBytes` | `64000` | 每条流的捕获输出上限。agent 在发行版内执行该限制，并标记被截断的结果。 |
+| `maxSpillBytes` | `67108864` | 一次性路径上每条流的 spill 文件上限。 |
+| `graceMs` | `3000` | SIGTERM 与 SIGKILL 之间的宽限期。 |
+
+`agent: true` 时，输出在发行版内被限制，且不写 spill 文件。
+`maxSpillBytes` 和 `graceMs` 适用于 `agent: false`，或常驻 agent
+不可用而改走一次性 `wsl.exe` 的情况。
+
+### 模型运行命令的 zsh/fnm 配方
+
+命令以 `<shell> -lc` 运行，因此 `~/.zshrc` 永远不会被读取——原因见
+[LIMITATIONS](LIMITATIONS.md#shell-startup-semantics-wsl-shell)。把 fnm 的
+hook 放进 `~/.zprofile`，并为沙箱准备一个回退——沙箱中 `/run` 是只读的，
+fnm 无法创建它的 multishell 符号链接目录：
+
+```zsh
+# ~/.zprofile — fnm for non-interactive login shells (mirrors the ~/.zshrc hook)
+path=("$HOME/.local/share/fnm" $path)  # the fnm binary itself
+_fnm_env="$(command -v fnm &>/dev/null && fnm env --shell zsh 2>/dev/null)" && eval "$_fnm_env"
+if [[ -z "${FNM_MULTISHELL_PATH:-}" || ! -e "${FNM_MULTISHELL_PATH}/bin/node" ]]; then
+  path=("$HOME/.local/share/fnm/aliases/default/bin" $path)  # sandbox fallback
+fi
+unset _fnm_env
+```
+
+交互式终端仍使用 `~/.zshrc` 中的 hook，不受影响；
+`aliases/default` 回退只在 multishell 链接无法存在时接管。
+
+## 环境变量转发
+
+只有名字列在 `WSLENV` 中的宿主环境变量才会被 WSL 导入。各提供者
+默认转发 `NO_COLOR`、`TERM`、`PAGER`、`GIT_PAGER`、`LANG`、`LC_ALL`
+以及托管的 `DSH_*` 名字。`forwardEnv` 向该列表追加名字；
+`PATH` 永远不会被转发。
+
+对 `wsl-shell` 而言，`forwardEnv` 只作用于一次性 `wsl.exe` 路径。
+常驻 agent 只接收托管的 `DSH_*` 环境，因此 `forwardEnv` 里的自定义名字
+不会到达经由该 agent 运行的命令。`subprocess-wsl` 的设置
+作用于它的 WSL 启动。
+
+## 发行版选择
+
+对命令与终端行而言，空的 `distro` 或 `distro: auto` 跟随
+请求的 UNC 工作目录。当请求未指明发行版时，使用 WSL 的
+默认发行版。对 `wsl-fs`，`auto` 跟随每个目标路径。对
+`fs-routing`，每条 UNC 目标各自选择自己的发行版。
+
+`distro: default` 总是选择 WSL 的默认发行版。给出发行版名字则把该行
+固定到那个发行版。`restrictToDistro: true` 时，属于其他发行版共享的路径
+会被以 `FS_OUTSIDE_DISTRO` 拒绝。挂载在 `/mnt/c` 的 Windows 盘
+位于所选发行版之内，不会被这个围栏拒绝。
+
+## Windows interop
+
+`interopVisibility` 控制是否对受限命令遮蔽 `/mnt`；
+它本身不会禁用 Windows interop。未设置时，`maskWindowsDrive: false`
+给出 `visible` 行为。
+
+| 值 | 效果 |
+|---|---|
+| `visible` | 保持 `/mnt` 可见。受限命令可以读取 Windows 文件，并通过 WSL interop 启动 Windows 可执行文件。 |
+| `masked` | 在受限 profile 中，把空的 tmpfs 挂载到 `/mnt` 上。命令无法访问 `/mnt` 下的路径；其他挂载与不受限的文件读取不在覆盖范围内。 |
+| `disabled` | 施加与 `masked` 相同的 `/mnt` 遮蔽；它不会禁用 interop，也不会修改 `wsl.conf`。请按下文单独配置发行版。 |
+
+`maskWindowsDrive: true` 等价于 `interopVisibility: masked`。
+设置了 `interopVisibility` 时，它优先于
+`maskWindowsDrive`。
+
+遮蔽只是收窄访问，并不关闭 interop。WSL 仍能运行被写入工作区的
+Windows 可执行文件，因为 `binfmt_misc` 按文件内容分发。
+因此强制级别仍是 `partial`，结果会报告 `windowsDrive: 'masked'`。
+要在该发行版上禁用 interop，把下面这段加进 `/etc/wsl.conf`：
+
+```ini
+[interop]
+enabled=false
+```
+
+然后运行 `wsl.exe --shutdown`。要关闭 interop，必须做这一发行版级修改。
+
+要对两个嵌套行都应用 masked profile：
+
+```bash
+pnpm run preset --sandbox true --mask-windows-drive true
+```
+
+把打印出的块合并进 profile。`visible` 与 `masked` 的行为
+由 `test/probe/interop-shell.sh` 对常驻与一次性两种命令都有覆盖。
+发行版级的 disabled 状态需要手动检查，因为它会改动 WSL 配置。
+
+## 沙箱与预检
+
+`wsl-shell`、`wsl-fs` 和 `fs-routing` 的默认值都是 `sandbox: true`。
+受限命令与变更要求发行版内有可用的 `bwrap`。缺失或不可用时，
+命令以 `SANDBOX_UNAVAILABLE` 失败，写入以 `FS_IO_ERROR` 失败；
+两种操作都不会回退到无约束运行。错误信息会区分
+包缺失与 `bwrap` 存在但不可用两种情况。
+
+用 bootstrap 辅助脚本安装该前置依赖：
+
+```bash
+scripts/bootstrap.sh <distro> --install
+```
+
+不带 `--install` 时，辅助脚本只做只读检查。在基于 apt 的
+发行版上，直接安装命令是：
+
+```bash
+wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap
+```
+
+会话打开时，`wsl-preflight` 行会运行这些检查。
+`sessionSandbox: true` 时，它还会检查会话 runtime 的前置条件。
+该警告仅供参考：它不会安装软件包，也不会改变提供者关闭（fail-closed）
+的行为。在该行设置 `sandbox: false` 或移除该行可让沙箱警告静音。
+profile 不使用会话 runtime 时，设置 `sessionSandbox: false`。
+
+在 `wsl-shell` 或 `wsl-fs` 上设置 `sandbox: false` 后，命令或写入
+将无约束地运行；其 `sandboxMode` 变为 `undefined`。工具层
+会报告没有沙箱生效。在 `fs-routing` 上，该设置会禁用变更围栏；
+无论开关如何，该行都报告 `sandboxMode: undefined`。
+
+## 诊断配置问题与拒绝
+
+使用 `dsh --profile <name> --dump-config` 检查合成后的 profile，
+无需真正启动。输出会显示某行的覆盖是否生效。
+使用 `scripts/bootstrap.sh <distro>` 检查发行版前置依赖。
+
+| 现象 | 结果 | 处理 |
+|---|---|---|
+| 命令沙箱不可用 | `SANDBOX_UNAVAILABLE`；消息区分 `bwrap` 缺失或不可用。 | 安装 `bubblewrap`、修复用户命名空间，或在 `wsl-shell` 上设置 `sandbox: false`。 |
+| 受限写入不可用 | `FS_IO_ERROR`，附带 `bwrap` 补救方法。 | 安装或修复 `bubblewrap`；要禁用围栏，在 `wsl-fs` 或 `fs-routing` 上设置 `sandbox: false`。 |
+| 发行版已停止时文件操作失败 | `FS_IO_ERROR`：发行版 substrate 不可用。 | 启动该发行版。若 agent 仍不可用，重启会话。 |
+| 命令无法在所选发行版中启动 | `WSL_E_*` 错误码，指明发行版。 | 启动该发行版或修改 `distro`。更宽的权限无法解决发行版已停止的问题。 |
+| `wsl.exe` 无法启动 | 错误指明可执行文件与该行的 `wslPath`。 | 修正 `wslPath`，并确认已安装 WSL。 |
+| 命令执行中 WSL 挂起 | 命令到达截止时间仍未完成。 | 重试一次；仍不行则运行 `wsl.exe --shutdown` 并重新打开会话。 |
+| 被监视的变更没有通知 | 轮询可能遗漏保留所观察元数据的变更；不保证报错。 | 查看 [LIMITATIONS.md](LIMITATIONS.md) 中的监视器限制。 |
+| 其他发行版的路径被拒绝 | `FS_OUTSIDE_DISTRO`。 | 使用 `distro: ''` 或 `auto` 跟随工作区，或在目标发行版中打开会话。 |
+
+完整错误参考见 [ARCHITECTURE.md — Error codes](ARCHITECTURE.md#error-codes)，
+设计边界见 [LIMITATIONS.md](LIMITATIONS.md)。