dsh-plugin-wsl-env 0.15.0 → 0.16.0

package/docs/LIMITATIONS.md

@@ -5,11 +5,12 @@ boundary; one that is not is a bug report waiting to happen.
 
 ## The filesystem substrate (`wsl-fs`)
 
-The file tools run on one substrate: the resident in-distro agent, on ext4 —
-reads, writes and identities happen where the files live. The former
+The WSL-routed file tools use one substrate: the resident in-distro agent —
+reads, writes and identities happen on the filesystem backing the target path
+(typically ext4 for a distro's own files, but other mounts are possible). The former
 Windows-side share backend (`substrate: "share"`) is retired: a profile still
-carrying the value is refused at boot with the migration, and no file tool
-crosses the 9p share. What to know about the one substrate there is:
+carrying the value is refused at boot with the migration, and WSL-routed file
+operations do not use the Windows-side 9p share. What to know about the substrate:
 
 - **A new file publishes with mode 0600.** That is the host backend's own POSIX
   publication semantics (a private 0600 staging file, renamed into place), which
@@ -27,17 +28,22 @@ crosses the 9p share. What to know about the one substrate there is:
 - **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`. The residual stat-then-rename pair is the
-  same sliver a Linux-host session's own rename has.
-- **A write is durable against process death, not machine death.** The
-  publication fsyncs the staged file before its atomic rename, but the
-  containing directory is not fsynced afterwards: a kernel panic or power loss
-  immediately after a successful write can lose the rename, and the file
-  reverts to its pre-write content. The peer backend fsyncs its staged file the
-  same way, but neither fsyncs the containing directory — the exposure is the
-  peer's too, and it stays short of a crash-consistent store.
+  on into the write op, and the agent re-verifies it against a fresh stat before
+  the rename. A mismatch returns `FS_STALE_VERSION`, but a change between the
+  check and rename can still be overwritten; this is not an atomic
+  compare-and-swap.
+- **A cancelled write can have an unknown outcome.** Cancellation is reported
+  before the agent necessarily finishes. A write already being published may
+  still take effect; inspect the file before retrying. The native agent refuses
+  queued writes when it processes their cancellation before they start. The
+  serial shell fallback removes requests cancelled while waiting on the host;
+  a request already sent to the agent may still take effect even if it has not
+  yet acknowledged the request.
+- **A successful write is not guaranteed durable across a crash.** The native
+  agent syncs the staged file before publication; the shell agent attempts
+  `sync -f` but ignores failure. Neither syncs the containing directory after
+  the rename or link. A kernel panic or power loss can therefore lose data or
+  the published directory entry; the operation is not a crash-consistent store.
 - **A Linux filename containing a backslash cannot be addressed.** The UNC
   display form (`\\wsl.localhost\<distro>\...`) is the file's identity
   everywhere - the session header, the GUI, the caches - and the backslash is
@@ -128,7 +134,7 @@ crosses the 9p share. What to know about the one substrate there is:
   slower than a direct agent call, especially on large files; the model's own
   file operations are unaffected — they use the preset filesystem and the
   resident agent directly. Measured 2026-10-19 with
-  [`test/probe/gui-preview.sh`](../test/probe/gui-preview.sh) (20 iterations on
+  [`test/probe/gui-preview.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/gui-preview.sh) (20 iterations on
   this machine): the routed backend's `stat` p95 2.7 ms, `listDir` p95 5.1 ms,
   and a 1 MiB `readByteRange` p95 **63.5 ms/MiB** — the service's own round
   trips sit on top of those, and the 1 s/MiB budget has a wide margin. No
@@ -143,6 +149,20 @@ crosses the 9p share. What to know about the one substrate there is:
   shipped row's own caps (`maxBytes`, `maxFileBytes`, `maxLines`, `maxEntries`)
   can be overridden on the `workspace-files` row.
 
+## `@` completion
+
+- **`@` references still walk the 9p share.** The shipped
+  `file-reference-local` service uses `node:fs/promises` from the Windows
+  harness process, so a WSL workspace pays a 9p `readdir`/`lstat` per
+  directory. On a 20-directory / 520-file tree the walk was **84.7 ms**
+  median over 9p versus **1.5 ms** on ext4 (~56×;
+  [`probe:file-reference`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/file-reference-9p.sh), 2026-10-19).
+  [`src/file-reference-wsl.ts`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/src/file-reference-wsl.ts) is the distro-side
+  traversal (built and unit-tested) but is **not** in `cordis.patch.yml`: the
+  funnels it would replace are module-internal. The fallback is the 9p walk
+  until upstream exposes `FileReferenceTraversal`. Cost, seam and wire
+  trigger: [UPSTREAM-FILE-REFERENCE-SEAM.md](UPSTREAM-FILE-REFERENCE-SEAM.md).
+
 ## The sandbox
 
 - **The one-shot fallback has only the host deadline.** With `agent: false`, or
@@ -158,12 +178,14 @@ crosses the 9p share. What to know about the one substrate there is:
   pays the native preparation/cache cost (~70 ms once); `agentBackend: shell`
   forces the shell reads. v6's FS concurrency would only shave the native
   runtime's 7.7 ms/16 writes and is deferred.
-- **The native backend is the default; aarch64 is build-tested only.** The
-  packaged x86_64 musl binary runs the 18-check suite in CI. The same job
-  builds the aarch64 binary, but the runner cannot execute it, so its
-  functional validation on real aarch64 hardware (or qemu) is still pending.
-  `agentBackend: auto` still selects it on an aarch64 distro; `native` refuses
-  if preparation fails, and `shell` forces the shell agent.
+- **The native backend is the default; aarch64 is executed under qemu in CI.**
+  The `native packages` job builds static-musl x86_64 and aarch64 binaries and
+  runs the 18-check suite against both the freshly built aarch64 artifact and
+  the committed `agent/native/linux-aarch64/dsh-wsl-agent` under qemu-user.
+  Physical aarch64 WSL is out of scope (no Windows-on-ARM machine in reach);
+  see [COMPATIBILITY.md](COMPATIBILITY.md#scope-decisions).
+  `agentBackend: auto` still selects the packaged binary on an aarch64 distro;
+  `native` refuses if preparation fails, and `shell` forces the shell agent.
 - **The session runtime needs systemd and a lingering user manager.** The
   shipped preset sets `sessionSandbox: true`; a distro without systemd as PID 1,
   a reachable `systemd --user`, `systemd-run`, or `Linger` is refused on the
@@ -179,13 +201,15 @@ crosses the 9p share. What to know about the one substrate there is:
   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`, `wsl-fs` and `fs-routing` 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
+  hole: the confined profile shadows `/mnt` with an empty tmpfs, so files and
+  executables at paths under `/mnt` are hidden. Other mounts, alternate access
+  paths and unrestricted file reads are not covered by this mask. 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`).
+  distro-level disabling of WSL interop (`[interop] enabled=false` in
+  `wsl.conf`) must be configured separately. On `wsl-shell`, an explicitly set
+  `interopVisibility` takes precedence over `maskWindowsDrive`.
 - **`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. The refusal
@@ -299,3 +323,14 @@ crosses the 9p share. What to know about the one substrate there is:
   `unknown` activity, which never accumulates idle.
 - Windows-folder host terminals (the `powershell.exe` branch) keep the shipped
   behaviour: `unknown` activity, no reclamation.
+
+## Host "Open in app"
+
+- **Opening VS Code (or another Electron editor) from the host "Open in app"
+  menu can fail independently of this plugin.** The DSH Host process runs with
+  `ELECTRON_RUN_AS_NODE=1`. The open-in-app launcher inherits that variable, so
+  `Code.exe` starts as Node, exits 1, and the UI reports launch-failed. File
+  Explorer and other non-Electron launchers are unaffected; the failure is the
+  same on a Windows folder and on a WSL UNC workspace. This repository does
+  not own that spawn path. The record and the upstream fix are in
+  [UPSTREAM-OPEN-IN-APP.md](UPSTREAM-OPEN-IN-APP.md).

package/docs/MIGRATION.md

@@ -20,10 +20,10 @@ still move in a **minor**. Within that freedom:
 - **Changing a key's meaning is a minor with a migration note**, because a profile
   written for the old meaning keeps booting. The note must say what changed, how
   to keep the old posture, and where the behavior differs.
-- **Peer pins are exact.** A new upstream peer line is tested by the
-  [peer canary](../.github/workflows/peer-canary.yml) and lands as a minor with
-  the delta in the release note (or as a patch if the plugin code needs no
-  change).
+- **Peer compatibility is ranged.** DSH peer dependencies declare a minimum;
+  development dependencies are pinned exactly. A new upstream peer line is
+  tested by the [peer canary](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/.github/workflows/peer-canary.yml); changes to
+  the tested baseline or supported range belong in the release note.
 - **Tool names and error codes are API.** `FS_OUTSIDE_DISTRO`,
   `SANDBOX_UNAVAILABLE`, `FS_STALE_VERSION` and the diagnostic scripts
   (`doctor`, `diagnose`, `preset`, `bootstrap`) keep their names and contracts;
@@ -62,7 +62,9 @@ the old meaning keeps booting, but now behaves differently. The migration:
           distro: default
 ```
 
-`pnpm run preset -- --distro default --out …` writes that block. The CHANGELOG
+`pnpm run preset --distro default` prints that block for manual merging.
+`--out` replaces the whole destination file, including unrelated overrides;
+see [CONFIGURATION.md](CONFIGURATION.md#configure-wsl-shell-and-wsl-fs). The CHANGELOG
 entry for 0.12.0 states the change; this page is the durable copy. `doctor`
 reports the effective distro mode in its host/distro rows, and `--dump-config`
 shows the composed value.
@@ -76,21 +78,22 @@ shows the composed value.
 | `pnpm run test:coverage` | lines 85 / branches 84 / functions 70 | CI (Node 24, Ubuntu) |
 | Peer line tested | `peer-canary` workflow resolves `next` and runs the scratch upgrade | CI schedule/manual |
 | Packed install/upgrade/uninstall | `pnpm run e2e:install` (temp `DSH_HOME`, 0.11.0 → current, marker) | manual, this machine (10/10 on 2026-10-19) |
-| Real-machine probe suite | `test/probe/run-all-when-closed.sh` (needs the app closed) | manual; **not run in this environment** since the last batch's targeted probes |
+| Real-machine probe suite | `test/probe/run-all-when-closed.sh --include-fs` (needs the app closed) | manual; 15 probes passed on this Windows/WSL machine on 2026-10-31 |
 | Clean Win11 + Ubuntu first run ≤ 5 min | a clean machine, a stopwatch | **not run** (the project's machine is already configured) |
-| aarch64 executed | the native suite on aarch64 WSL or qemu | **not run** (CI builds the binary only) |
+| aarch64 executed | the native 18-check suite under qemu in CI | **run in CI** (physical aarch64 WSL is out of scope; see COMPATIBILITY.md) |
 | No open P0 bug for 30 days | issue tracker | time-based; cannot be asserted from a checkout |
 
-The last four rows are deliberately marked as unrun rather than assumed: a
-release note must not claim them, and [ROADMAP-1.0.md](ROADMAP-1.0.md#wsl-304--10-readiness)
-tracks them. A release that skips the manual rows still ships through the tag
-workflow, but its notes say which gates were executed.
+The clean-machine first-run timing and the 30-day P0 window stay unrun until
+someone measures them; aarch64 qemu is a CI gate. A release note must not
+claim an unrun row, and [ROADMAP-1.0.md](ROADMAP-1.0.md#wsl-304--10-readiness)
+tracks the 1.0 leftovers. A release that skips the remaining manual rows still
+ships through the tag workflow, but its notes say which gates were executed.
 
 ## Verifying a migration locally
 
 ```bash
-pnpm run preset -- --distro default --check <profile>/cordis.patch.yml  # no nested-row trap
-pnpm run doctor -- --json                                               # effective environment facts
+pnpm run preset --distro default --check <profile>/cordis.patch.yml  # no nested-row trap
+pnpm run doctor --json                                               # effective environment facts
 dsh --profile <name> --dump-config                                      # composed rows
 ```
 

package/docs/PARITY.md

@@ -5,9 +5,10 @@ against, and the phase checklist with each phase's current status. The plan
 has landed; the rows below record where each phase ended up and what
 deviation, if any, still stands.
 
-Verified against: `dsh-plugin-wsl-env@0.8.0` / peer `0.2.0-rc.2` / agent
-protocol v4, 2026-10-06. Update this line when the peer pin or the agent
-protocol moves. The peer pin moved to `0.2.1-rc.2` on 2026-10-17 with every
+Historical verification: `dsh-plugin-wsl-env@0.8.0` / peer `0.2.0-rc.2` / agent
+protocol v4, 2026-10-06. These rows are not a fresh verification of the current
+release or protocol; see [PEER-PARITY.md](PEER-PARITY.md) for the peer
+comparison. The peer pin moved to `0.2.1-rc.2` on 2026-10-17 with every
 seam package's shipped artifact byte-identical to the ones these rows were
 measured against; the real-machine probes were not re-run in that move.
 

package/docs/PERFORMANCE.md

@@ -9,8 +9,8 @@ and how to reproduce them; it does not extrapolate beyond them.
 
 | | 9p share (`\\wsl.localhost\...`) | This plugin |
 |---|---|---|
-| File I/O | host stack crosses the VM boundary per operation | resident agent serves reads/writes on ext4 inside the distro |
-| Change feed | polling the share | inotify inside the distro (`watchMaxDepth: 0`) |
+| File I/O | host stack crosses the VM boundary per operation | resident agent serves reads/writes inside the distro, on the target's backing filesystem |
+| Change feed | polling the share | inotify for unbounded directories when available, polling otherwise |
 | Commands | host process | distro login shell through `wsl.exe` |
 
 The plugin's root filesystem routes every WSL path to the distro backend
@@ -26,7 +26,7 @@ Absolute numbers are machine-dependent; the ratio and the budgets are the point.
 
 | Scenario | 9p share | Agent (ext4) | Source |
 |---|---|---|---|
-| 16 concurrent shared reads | 342–614 ms (queue up to 583 ms) | **2.4–4.1 ms** after A7, first start ~70 ms once | [ADR 0002 fs queue](adr/0002-native-agent.md#fs-queue-measurement-a6-2026-10-18) |
+| 16 concurrent shared reads, shell agent vs native agent | — | shell: 342–614 ms (queue up to 583 ms); native: **2.4–4.1 ms** after A7, first start ~70 ms once | [ADR 0002 fs queue](adr/0002-native-agent.md#fs-queue-measurement-a6-2026-10-18) |
 | Single FS op (host round trip) | — | p95 ≈ 22 ms | [ROADMAP-1.0.md](ROADMAP-1.0.md#7-metrics) |
 | GUI-preview backend: `stat` | — | p95 **2.7 ms** | `pnpm run probe:gui-preview` (20 iterations, 2026-10-19) |
 | GUI-preview backend: listing | — | p95 **5.1 ms** | same |
@@ -47,14 +47,16 @@ pnpm run probe:gui-preview        # stat / listDir / 1 MiB page read, p50/p95
 node test/probe/fs-queue.mjs      # the agent queue, sequential vs concurrent, with per-op latency
 ```
 
-Both need a working distro and Node; neither boots the harness. The probes print
-the raw samples' p50/p95/max and fail when a budget is exceeded, so a regression
-is a red probe rather than a claim in prose.
+Both need WSL interop, a working distro and Node; neither boots the harness.
+The queue measurement also needs systemd and a usable native binary; it prints
+wall times and queue metrics but does not enforce latency budgets. The GUI-preview
+probe reports p50/p95/max and fails when its budgets are exceeded.
 
 ## What is not measured
 
 - End-to-end GUI paint time (the browser and the service's own work are out of
   scope for these probes).
-- 9p numbers for large files or many small files beyond the A6 sample above;
-  the A6 measurement is the recorded baseline, not a re-runnable benchmark.
-- aarch64; the binary is built but not executed in CI.
+- 9p numbers for large files or many small files; A6 compared shell and native
+  agents, not the Windows-side 9p share.
+- Physical aarch64 WSL latency (the native 18-check suite runs under qemu in
+  CI; that is functional correctness, not a host-round-trip measurement).

package/docs/QUICKSTART.md

@@ -1,6 +1,6 @@
 # Quickstart
 
-Five minutes from a clean Windows + WSL 2 machine to a working WSL session.
+Steps from a Windows + WSL 2 machine to a working WSL session.
 This page is the entry point; every claim links to the document that owns it.
 
 ## 1. Prerequisites
@@ -11,10 +11,11 @@ This page is the entry point; every claim links to the document that owns it.
 | A distro | one line in the list above | `wsl.exe --install -d Ubuntu` |
 | `bubblewrap` | `wsl.exe -d <distro> -- which bwrap` | `wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap` |
 | systemd + Linger (for the session runtime) | `node <plugin>/scripts/doctor.mjs` (installed) or `pnpm run doctor` (checkout) | `[boot] systemd=true` in `/etc/wsl.conf`, `wsl --shutdown`, then `loginctl enable-linger "$USER"`; or set `sessionSandbox: auto`/`false` |
-| Node 22.19+ or 24 | only needed for source/development work | not needed to use the published plugin |
+| Node `^22.19.0` or `>=24.0.0` | only needed for source/development work | not needed inside the distro to use the published plugin |
 
-The doctor (`scripts/doctor.mjs`, or `pnpm run doctor` from a checkout) covers all
-of the above in one pass and prints a copy-paste remedy per failure. It is read-only unless you pass `--fix` (stale scopes) or
+The doctor (`scripts/doctor.mjs`, or `pnpm run doctor` from a checkout) checks
+the environment and prints remedies for detected failures. Confirm the distro's
+WSL version separately with `wsl.exe -l -v`. Doctor is read-only unless you pass `--fix` (stale scopes) or
 `--fix --install` (packages, after a confirmation).
 
 ## 2. Install
@@ -23,6 +24,8 @@ From a Windows PowerShell where the DSH CLI is available:
 
 ```powershell
 dsh plugin --profile <profile> add dsh-plugin-wsl-env
+# 若解析到旧版本（发布当天的元数据缓存），显式指定：
+# dsh plugin --profile <profile> add dsh-plugin-wsl-env@<latest>
 dsh --profile <profile> --dump-config      # the plugin rows must be there
 ```
 
@@ -37,6 +40,23 @@ or an UNC path directly. The session's commands, file tools, terminal and previe
 all run in that distro; a Windows folder keeps the normal Windows environment.
 Two distros can be open at once, each with its own environment.
 
+### Open the workspace in VS Code (Remote-WSL)
+
+Opening the WSL folder as a Windows UNC share works but is the degraded mode:
+files cross 9p, the terminal is PowerShell, extensions run on Windows. The full
+integration is VS Code's Remote-WSL — the server runs inside the distro, the
+integrated terminal is the distro shell, and file operations are local ext4:
+
+```powershell
+# from the plugin checkout:
+scripts/open-wsl-vscode.ps1 -Path "\\wsl.localhost\ubuntu\home\me\proj"
+# or by hand:
+code --folder-uri "vscode-remote://wsl+ubuntu/home/me/proj"
+```
+
+Requires the `code` shim on PATH (VS Code installer adds it) and the
+Remote-WSL extension.
+
 ![The directory picker listing a WSL distro's folders](screenshots/picker.png)
 
 The terminal panel runs in the same distro — `uname -a` answers with the
@@ -55,10 +75,13 @@ distro kernel. If the first command fails, the error names the remedy; the
 [doctor](CONFIGURATION.md) and the [Troubleshooting table](../README.md#troubleshooting)
 cover the common cases.
 
-The sandbox is enforced by the kernel, not a promise: the probe below runs the
-shipped bwrap profiles live — writes inside the workspace land, writes outside
-are refused with `EROFS`, and the strict profile hides `/mnt` entirely
-([`test/probe/sandbox.sh`](../test/probe/sandbox.sh)):
+The probe below runs the shipped kernel-enforced bwrap profiles live — writes
+inside the workspace land, tested writes outside are refused with `EROFS`, and
+the strict profile hides `/mnt` entirely
+([`test/probe/sandbox.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/sandbox.sh)):
+
+This is partial isolation, not a Windows security boundary: Windows interop
+can still launch executables outside `/mnt`. See [LIMITATIONS.md](LIMITATIONS.md).
 
 ![The sandbox probe: every expectation holds, the kernel refuses what the profile does not grant](screenshots/sandbox.png)
 
@@ -75,8 +98,9 @@ pnpm test
 pnpm dev            # a dev server survives the command that started it with sessionSandbox: true
 ```
 
-The server's port appears in `DSH_WSL_PORTS` on the next snapshot (10 s by
-default); open it from Windows at `http://localhost:<port>`.
+The server's port can appear in `DSH_WSL_PORTS` after a successful snapshot
+(refreshed every 10 s by default); open a forwarded port from Windows at
+`http://localhost:<port>`.
 
 ### Python
 
@@ -106,14 +130,16 @@ go build ./...
 go test ./...
 ```
 
-The module cache lives in the distro's `$GOPATH`, so builds stay on ext4.
+The module cache normally lives under the distro user's `$GOPATH`; its actual
+location and backing filesystem depend on the Go environment and mounts.
 
 ### Monorepo
 
 Open the repository root as the workspace. Each package's commands run from the
 same distro; `pnpm -r`, `turbo`, `nx` and `make` see one Linux filesystem. The
-file watcher uses inotify inside the distro (`watchMaxDepth: 0`). If a change is
-missed, see the watcher bounds in [CONFIGURATION.md](CONFIGURATION.md).
+file watcher uses inotify for unbounded directories when `inotifywait` is
+available; otherwise it falls back to polling. If a change is missed, see the
+watcher bounds in [CONFIGURATION.md](CONFIGURATION.md).
 
 ## Compatibility
 
@@ -123,21 +149,20 @@ executed here.
 
 | Tier | Configuration | Status |
 |---|---|---|
-| 1 | Ubuntu 24.04 or Debian 12, systemd, x86_64 | Probed on Ubuntu (the project's development machine; the real-machine suite is manual). Debian is a Tier 1 target, probe pending |
-| 2 | Other systemd distros, aarch64 | The aarch64 native binary is built by CI but not executed here; aarch64 WSL or qemu is the pending leg |
+| 1 | Ubuntu / Debian, systemd, x86_64 | Probed. Debian harness-level probes pass against a `wslfs-debian` profile (2026-10-26). |
+| 2 | Fedora, openSUSE, Arch, Alpine; aarch64 native agent | Distro matrix in [COMPATIBILITY.md](COMPATIBILITY.md). aarch64 18-check runs under qemu in CI; physical aarch64 WSL is out of scope. |
 | Unsupported | WSL 1, Linux/macOS hosts, Windows without WSL 2 | Not supported; the plugin attaches to `wsl.exe` |
 
 With `sessionSandbox: auto` a distro without systemd/Linger still gets the
 per-command `bubblewrap` sandbox and the result reports the narrower scope;
-`true` refuses. See [CONFIGURATION.md](CONFIGURATION.md#the-strict-profile) for
+`true` refuses. See [CONFIGURATION.md](CONFIGURATION.md#sandbox-and-preflight) for
 the sandbox trade-offs and [PERFORMANCE.md](PERFORMANCE.md) for the measured
 latency.
 
 ## Demo
 
-There is no GIF or screenshot in this repository yet: producing one needs a
-capture of the GUI, which this project has not recorded. The
-[Troubleshooting table](../README.md#troubleshooting) and the probe output
-(`pnpm run probe:sandbox`, `pnpm run probe:gui-preview`) are the reproducible
-evidence in the meantime; the absence is recorded in
+The screenshots above show the picker, terminal, preview and sandbox probe.
+There is no GIF yet. The [Troubleshooting table](../README.md#troubleshooting)
+and the probe output (`pnpm run probe:sandbox`, `pnpm run probe:gui-preview`)
+provide reproducible evidence; the remaining demo work is tracked in
 [ROADMAP-1.0.md](ROADMAP-1.0.md#wsl-302--discoverability-and-docs-entry).

package/docs/README.zh.md

@@ -6,9 +6,9 @@
 [![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) 插件，让会话在 Windows 的 WSL 2 发行版中运行。
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件，在 Windows 的 WSL 2 发行版中打开项目工作区。
 
-Harness 进程仍在 Windows 上。命令、文件操作、文件夹选择器和 GUI 终端都使用发行版环境。发行版内不安装辅助服务或守护进程，也不开放端口，受限命令在 `bubblewrap` 中运行。
+Harness 进程仍在 Windows 上。命令执行、shell 脚本和文件访问都在发行版的 Linux 空间内完成，以获得全套 Linux shell 工具链。发行版内不安装辅助服务或守护进程，也不开放端口，受限命令在 `bubblewrap` 中运行。
 
 仅支持 Windows + WSL 2。
 
@@ -16,7 +16,7 @@ Harness 进程仍在 Windows 上。命令、文件操作、文件夹选择器和
 
 Windows 上的编程工具要在 WSL 项目中工作，有三条路：把整个工具装进发行版、连接发行版内的辅助服务，或由插件直接提供发行版环境。本插件是第三条。两类会话共用一套流程，同时保留发行版的真实工具和命令沙箱。
 
-- **真实的 Linux 环境。** 命令在发行版自己的登录 shell 中运行，`PATH`、`nvm`、`cargo`、`pyenv` 和 rc 文件都生效。文件工具直接读写发行版 ext4 上的真实文件。
+- **真实的 Linux 环境。** 命令在发行版自己的登录 shell 中运行，`PATH`、`nvm`、`cargo`、`pyenv` 和 rc 文件都生效。文件工具通过发行版内的 agent 访问发行版路径，底层文件系统取决于路径。
 - **发行版内没有服务。** 没有辅助服务、没有守护进程、没有监听端口。唯一持久化的内容是 `~/.cache/dsh-wsl/agent/` 下按内容寻址的原生 agent 副本。
 - **默认有沙箱。** 受限命令在发行版内的 `bubblewrap` 中运行。缺少 `bubblewrap` 时命令直接失败，不会脱箱运行。
 - **按会话生效。** 打开发行版文件夹的会话获得发行版环境；打开 Windows 文件夹的会话保留 Windows 工具。两者可同时运行在一个 harness 进程中。
@@ -72,7 +72,7 @@ dsh --profile wsl                                  # 启动
 wsl.exe -d <发行版> -u root -- apt-get install -y bubblewrap
 ```
 
-在插件检出目录中，`pnpm run bootstrap -- <发行版>` 检查四个发行版工具，并按包管理器打印安装命令；加 `--install` 直接执行。
+在插件检出目录中，`pnpm run bootstrap <发行版>` 检查四个发行版工具，并按包管理器打印安装命令；加 `--install` 仅在缺少 bubblewrap 时执行该命令。若只缺少其他工具，请自行执行打印的命令。
 
 升级：再次执行 `add` 命令。卸载：`dsh plugin --profile wsl remove dsh-plugin-wsl-env`；之后可删除 `~/.cache/dsh-wsl`。如果你为了恢复预览在 profile 里加过 `workspace-files-wsl` 的临时覆盖，升级后请删掉：插件不再挂载该行。
 
@@ -135,11 +135,11 @@ wsl preset（每个会话）
 | `workspace-write` | 上面的权限，加上会话工作区；会话 runtime 下 `/tmp` 是发行版真实 `/tmp` |
 | `danger-full-access` | 不经过沙箱 |
 
-设置 `sessionSandbox: false` 时，每条命令使用私有的 `/tmp`，而不是发行版的真实 `/tmp`。
+设置 `sessionSandbox: false` 时，`workspace-write` 命令使用私有的 `/tmp`，而不是发行版的真实 `/tmp`；`read-only` 不挂载可写的 `/tmp`。
 
 `bubblewrap` 是必需项。缺失或损坏时，受限命令报 `SANDBOX_UNAVAILABLE`，不会运行。在对应的行设置 `sandbox: false` 可关闭沙箱；模型会收到"该操作无沙箱"的说明。
 
-隔离上报为 `partial`。发行版内的命令仍可通过 `/mnt/c` 启动 Windows 程序，`bubblewrap` 无法控制 Windows 进程。`maskWindowsDrive: true` 让受限视图看不到 `/mnt`，能收窄这个洞但不能关死。彻底关闭要在发行版层面设置 `[interop] enabled=false`（`/etc/wsl.conf`）。见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#sandbox) 和 [SECURITY.md](../SECURITY.md)。
+隔离上报为 `partial`。发行版内的命令仍可通过 `/mnt/c` 启动 Windows 程序，`bubblewrap` 无法控制 Windows 进程。`maskWindowsDrive: true` 让受限视图看不到 `/mnt`，但会被 `interopVisibility: visible` 覆盖；遮罩只能收窄这个洞，不能关死。关闭 WSL interop 需要另行在发行版的 `/etc/wsl.conf` 中设置 `[interop] enabled=false`。见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#sandbox) 和 [SECURITY.md](../SECURITY.md)。
 
 ## 常见问题
 
@@ -147,7 +147,7 @@ wsl preset（每个会话）
 |---|---|
 | 每条命令都报 `SANDBOX_UNAVAILABLE` | 在发行版内安装 `bubblewrap`，或设置 `sandbox: false` |
 | 会话在第一条命令前就被拒绝 | 启用 systemd 和 linger，或在 `wsl-shell`、`wsl-fs` 上设置 `sessionSandbox: false` |
-| 发行版内 `glob`、`grep` 很慢 | 运行 `pnpm run bootstrap -- <发行版> --install` 安装 `ripgrep` |
+| 发行版内 `glob`、`grep` 很慢 | 运行 `pnpm run bootstrap <发行版>`，使用打印的安装命令安装 `ripgrep` |
 | `dsh plugin add` 没有输出 | 插件已安装；这是成功 |
 | 改了 `lib/` 但不生效 | 运行 `pnpm run sync:windows`，然后重启应用 |