npm - dsh-wsl-desktop - Versions diffs - 0.5.0 → 0.5.1 - Mend

dsh-wsl-desktop 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.en.md CHANGED Viewed

@@ -2,137 +2,176 @@
 English | [简体中文](README.md)
-Turns a WSL distribution into a **first-class execution world** inside DSH Desktop: a workspace can live inside the distro, and shell, file tools, subprocess and terminal then all run inside the distro — while Windows workspaces in the same instance keep using the host's own sandbox backends. The two coexist.
+## What this is
+A plugin for DSH Desktop. It turns your WSL distribution into a place where work actually happens:
+put a workspace inside the distro and the AI's shell commands, file reads and writes, searches and
+terminals all run inside the distribution instead of on Windows.
+## Why you would want it
+The plugin gives every WSL session a "preset" — the set of tools a session gets when it starts. That
+preset points the shell, file reading and writing, search and terminal at the distribution. So:
+- **Your Linux tools really work.** With the workspace inside the distro, the AI uses the distro's
+  own `bash`, `grep`, `find`, interpreters and packages.
+- **Calls stop being strangers to each other.** The model's `bash` is a persistent shell, so the
+  directory and environment variables left by one call are still visible to the next.
+- **Two kinds of workspace can be open at once.** In the same window, Windows workspaces keep
+  running on the host's own sandbox backends while WSL workspaces run inside the distro, without
+  interfering with each other.
+- **You can still reach the Windows side.** From inside the distro you can invoke host commands; WSL
+  calls this feature interop, and it is on by default.
+## What you need first
+- **WSL2.** Not WSL1.
+- **A supported distribution.** Debian, Ubuntu, Fedora/RHEL and Arch are measured and pass; Alpine
+  works once `bash` and `util-linux-misc` are installed. The list and each distro's install commands
+  are in the [distro support matrix](docs/DISTRO-SUPPORT.md).
+- **DSH Desktop 0.1.7 or newer.** An older host rejects the plugin at activation.
+- **Passwordless sudo for the session user, plus `bash` and `python3`.** This is the one people trip
+  on. Confined mode builds a mount namespace — a Linux mechanism that gives a process its own view of
+  the mount table — and makes the file system read-only inside it. The WSL kernel refuses bind mounts
+  inside a user namespace, so this needs `sudo -n`. Without passwordless sudo, confined mode **fails
+  explicitly** instead of falling back to running bare.
+- **A helper is recommended.** The helper is a small script installed inside the distro,
+  `dsh-wsl-confine`, that closes the "retained sudo grant" boundary. Install commands are in
+  [Confinement](docs/CONFINEMENT.md). It is optional, but recommended.
+## How to install it
+**Plugin market / plugin manager (recommended)**: install `dsh-wsl-desktop@<version>`. The desktop
+wires the package into pnpm and mounts its bundle patch — the configuration that hooks a plugin into
+the desktop — automatically; restart and it works.
+**CLI equivalent**:
-> **Production status: usable in production under controlled single-machine operation** (see the scope boundaries below). Requires **DSH Desktop 0.1.7+** (presets are registered at runtime rather than loaded from directories; an outdated host explicitly rejects at activation). Core capabilities have passed live acceptance; security audits run-1 (5 candidates, closed loop) and run-2 (4 confirmed fixed + 1 rejected, converted to hardening) are complete, with reports in `security-audit-skill/dsh-wsl-desktop/run-{1,2}/`. Per-item evidence strength is annotated in the capability table below.
->
-> **Scope boundaries**:
-> - ✅ **Suitable**: the plugin author themselves or operators of the same trust level, for long-term use on explicitly supported distros (see the [distro support matrix](docs/DISTRO-SUPPORT.md)) and a 0.1.7+ desktop.
-> - ⚠️ **Conditional**: the confined-mode trust boundary depends on NO_NEW_PRIVS (modern debian-family setpriv satisfies it; where setpriv has no `--no-new-privs`, confined mode does NOT run at all — the direct runner refuses once it measures `false`, and the helper's drop passes the same flag and fails closed, see [Security and trust boundaries](SECURITY.md)).
-> - ❌ **Not yet suitable**: distribution to third-party users (missing desktop version gating and distro matrix), or unattended high-value environments (the unconfined subprocess surface is a disclosed design; the two API proposals to the harness upstream are in [docs/UPSTREAM-PROPOSALS.md](docs/UPSTREAM-PROPOSALS.md)).
-## Contents
-- **This page**: [Target capabilities](#target-capabilities) · [Install / Update / Uninstall](#install--update--uninstall) · [Quick start](#quick-start) · [Desktop update discipline](#desktop-update-discipline-mandatory) · [Security and trust boundaries](#security-and-trust-boundaries) · [Known limitations](#known-limitations) · [Verification](#verification) · [Development](#development) · [Release](#release)
-- **In-depth material**: [Security and trust boundaries](SECURITY.md) · [Architecture and the execution world](docs/ARCHITECTURE.en.md) · [Confinement (Linux side)](docs/CONFINEMENT.en.md) · [The fs fence](docs/FS-FENCE.en.md) · [Terminal (PTY bridge)](docs/PTY-BRIDGE.en.md) · [WSL file watching](docs/WATCH.en.md) · [Verification and the SKIP ruling](docs/VERIFICATION.en.md) · [Engineering notes](docs/ENGINEERING-NOTES.en.md) · [Distro support matrix](docs/DISTRO-SUPPORT.md) · [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) · [Architecture and flow diagrams](docs/diagrams.md)
-> The bilingual documents linked above (their file names carry an `.en` marker) are enforced as pairs rather than trusted. The three older documents — the distro support matrix, the upstream proposals and the diagram index — are **Chinese-only**, because no English text for them exists: translating them is a separate piece of work, not a rename.
-## Target capabilities
-**Honest state after live acceptance** (`verify-post-restart.mjs`, latest real run: **58 PASS / 0 FAIL**, tail `NO AUTOMATED FAILURES; 3 manual step(s) pending`, `EXIT=0` — including the two live search rows and the persistent-shell rows; **3 browser-only manual steps remain**, listed in [The persistent shell](docs/PERSISTENT-SHELL.en.md#manual-verification-checklist-browser-only-not-automatable) — plus 20 offline suites; each item below notes its evidence strength):
-| # | Capability | Status |
-|---|---|---|
-| ① | The workspace can pick a Linux directory inside a WSL distro | Dialog and host calls implemented and live-verified (listDir/checkPath/resolveHome/workspace registration and cleanup); **in-browser interaction manually confirmed by the operator** (gating flow, directory browsing, and terminal panel all normal) |
-| ② | shell / file tools / subprocess / terminal inside that workspace work in WSL, and host commands can be invoked from WSL | **Live acceptance PASS**: binding (the create request names the preset), shell inside the distro, fs tools addressing Linux paths, out-of-bounds write rejection, subprocess POSIX environment, bash tool, tool-layer constraints; terminal transport covered by the PTY suite. **The model's `bash` is a persistent PTY shell inside the distribution, keeping cwd and environment variables across calls** (live-verified: two calls read back the same state; the gap list is in [The persistent shell](docs/PERSISTENT-SHELL.en.md)) |
-| ③ | Windows and WSL workspaces coexist in the same instance | **Live acceptance PASS**: Windows workspaces stay on the host preset (PowerShell available, no bash); WSL sessions run the confined realm in parallel |
-| ④ | Linux-side sandbox constraints on the WSL side | **Shell side fixed and live-verified**: at runtime, all `rw` mounts are enumerated and remounted read-only one by one (observed `/mnt/c`, `/dev/shm`, `/run/user/<uid>` going WRITABLE → READONLY); any failure rejects (exit code 97 preserved); `enforcement` honestly reports `partial`. **fs-side fence implemented and live-verified** (out-of-bounds write rejected, PASS — see [The fs tool fence](docs/FS-FENCE.md)) |
-**Which capabilities are qualified**: the evidence strength is the wording of the status column above. The terminal has no `stdio.control` — it is stated under "Known limitations" rather than left out. The persistent shell's gaps are stated there too, with the authoritative list in [The persistent shell](docs/PERSISTENT-SHELL.en.md).
-## Install / Update / Uninstall
-**User install (production channel)**: this plugin ships as an npm package, shaped like mature plugins such as dsh-better-sidebar (an exact `files` manifest + `cordis.patch.yml` bundle patch + `dsh.client.inject` client wiring + `manifestVersion`).
-- Plugin market / plugin manager: install `dsh-wsl-desktop@<version>` — the desktop automatically completes the pnpm wiring and the bundle patch mount; restart and it works.
-- CLI equivalent: `plugin_manager install_bundle dsh-wsl-desktop@<version>`.
-- **Install prerequisites**: WSL2 + the target distro meeting the [support matrix](docs/DISTRO-SUPPORT.md) — NOPASSWD sudo for the session user, bash, python3; installing the dsh-wsl-confine helper to close the fence boundary is recommended (install commands in [docs/CONFINEMENT.md](docs/CONFINEMENT.md)).
-- **Update**: installing a new version number is enough; after a desktop major update, run `verify-post-restart.mjs` first per "Desktop update discipline".
-- **Uninstall**: uninstalling via the plugin manager also withdraws the wsl-* presets registered by this plugin (guaranteed by the disposer lifecycle).
-> **Version correspondence**: the current `0.3.x` line requires DSH Desktop **0.1.7+**. See "Release" for what the semantic version means — `minor` is precisely "adapted to a new desktop major", so **when the desktop major changes, check here first for the matching minor**.
-## Quick start
-In the sidebar workspace title bar, to the right of the built-in "+" (add workspace), there is an extra **W** button. It opens this plugin's workspace dialog; the order is: pick a distro → enter the user to enter that distro with (**leave empty = the distro's default user**) → browse or type a Linux directory → create and open a session.
-Once inside browse mode the path lands directly in that user's home directory (the host resolves the user database inside the distro with `getent passwd`). If the entered user does not exist, the error is shown in place in the popup and browse mode is not entered. Switching distros — **including re-clicking the currently selected one** — re-prompts for the user, prefilled with the previously confirmed name. While a session creation is in flight, distro buttons are temporarily unclickable.
-To be precise about the boundary: this step only decides "whose home gets browsed", **not the session identity** — the session always executes inside the distro as the distro's default user (`username` is plugin configuration and is not passed along with session creation).
-In the sidebar workspace list, **a workspace whose path is under a WSL UNC root shows a ☁️ icon instead of the folder**. "+" keeps the deployment's own behavior (the Electron directory picker on Desktop); this plugin does not override it.
-Why the UI and its DOM layer work this way (measured conclusions such as "hiding must use `display`, never `remove()`" and "never use a timer as a fallback") is in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
-## Desktop update discipline (mandatory)
-After every DSH Desktop update, the plugin may break because of harness internal API changes (0.1.6→0.1.7 broke four places at once). **Discipline: update the desktop → run `node scripts/verify-post-restart.mjs` → only keep going when everything is green; any red gets fixed before anything else.** That suite covers preset registration, the execution world, session binding, Windows isolation, and dialog contracts; breakage from a new host shows up on these assertions instead of silently degrading into the host world.
-## Security and trust boundaries
-- **Host side**: Windows workspaces keep running in DSH's own sandbox backends; this plugin does not replace them.
-- **Shell side inside the distro**: `/` is made read-only inside a mount namespace, leaving only the workspace and a private `/tmp` writable; **a fence that cannot be established refuses to execute** — it never runs bare. Mechanism and measured preconditions: [docs/CONFINEMENT.md](docs/CONFINEMENT.md).
-- **fs side inside the distro**: `WslFileSystem` carries its own fence, both mutation entries go through `checkedTarget`, and an out-of-bounds target is rejected with structured `FS_SANDBOX_DENIED`. See [The fs tool fence](docs/FS-FENCE.md).
-**Disclosed unconfined surface**: the host subprocess surface being unconfined is a design decision, not an omission. **Known boundary of the fence**: the session user's retained passwordless sudo grant can be re-invoked to bypass the file fence; the two closing paths and their real reachability are in [SECURITY.md](SECURITY.md).
-## Known limitations
-**The grep / glob tools are available in a WSL session, backed by the distribution's own `grep` / `find`.** The host's two rows are still removed, for the two measured facts: `tool-fs-search` is launched via `ctx.subprocess.spawn()` (`search-core.ts:238`), but its `argv[0]` is the **bundled Windows rg.exe** from `@vscode/ripgrep` (`search-core.ts:174-178`) — it does not exist inside the distro and cannot work with Linux arguments; the distro, meanwhile, ships `/usr/bin/grep` and `/usr/bin/find` (measured: `command -v rg` inside the distro answers nothing). So the `wsl-world` group mounts the two names back onto this plugin's own implementation (`lib/wsl/search-tool.js`), and the model calls `grep` / `glob` in a WSL session as usual — **with the distribution's semantics**: POSIX ERE (no `\d`, no `(?i)`) · `.gitignore` not parsed (only the six VCS directories are skipped) · dotted directories searched · `include` matching the base name only and without brace expansion · patterns interpreted relative to the search root, with `*` and `**/` crossing `/` · a record whose path contains `:` possibly dropped or silently mis-attributed · binary files never matched · a capped result not saved anywhere. **That list is a summary; the document is authoritative for the eight gaps** (gaps 5 and 6 are merged into one item here, and the last item, "a capped result not saved anywhere", is a limit rather than a gap). The eight gaps, the limits, what was not measured and how to verify it yourself are in [Search inside the distribution](docs/SEARCH.en.md).
-**The terminal goes through the PTY bridge, and PTC's `stdio.control` (fd channel) stays explicitly rejected** — `wsl.exe` cannot forward arbitrary descriptors. How the bridge is driven, and its measured preconditions, are in [docs/PTY-BRIDGE.md](docs/PTY-BRIDGE.md).
-**The persistent shell's gap summary**: the model's `bash` is a persistent PTY shell inside the distribution, but it carries two load-bearing boundaries — **(1) the host's `ctx.sandbox` wraps the `wsl.exe` argv**, and this repository's own judgement is that the host sandbox **cannot confine** it (measured: it still runs after the wrapping, which is why the realm provides its own `sandbox` provider and turns that layer into an in-distro fence); **(2) the terminal path has no PID namespace**, and the GUI's web terminal is **unfenced by design** — what is confined is the model's `bash`, not what the user types in the terminal panel. **That list is a summary; the document is authoritative for the gaps**: the nine gaps, the limits, what was not measured, the 3-step manual checklist and how to verify it yourself are in [The persistent shell](docs/PERSISTENT-SHELL.en.md).
-**Confinement does not cover `/dev`, `/proc`, `/sys` or interop**, which is reported honestly in `enforcement: 'partial'`; and the session user's retained passwordless sudo grant can bypass the file fence — see [SECURITY.md](SECURITY.md).
-**File-change tracking inside a WSL workspace polls; it is not event-driven.** `fs.watch` throws `EISDIR` on the distribution's 9P share (for a file target as well as a directory one), so the host backend's chokidar watcher cannot initialize for any WSL target. The plugin polls on the host side instead: a directory compares its entry set (one `readdir` per 300ms; measured 0ms CPU per 3s and 2-3ms latency in this process) and a file — or a path that does not exist yet — watches its stat (`fs.watchFile`, measured 0ms CPU per 3s and 52ms). **A directory target is invalidated by entry-set changes only**: adds, removes and renames are seen; the CONTENT change of a file inside it is not — watch that file's own path to follow it. Mechanisms, measurements and what was not measured are in [WSL file watching](docs/WATCH.en.md).
-## Verification
-```powershell
-node scripts/verify-all.mjs          # all offline suites (20)
-node scripts/verify-all.mjs --live   # additionally the suites needing the installed plugin + a running host
 ```
-Per-suite responsibilities, the single-suite commands, and **how the aggregate reads a SKIP** (exit code 2 is a suite's own SKIP; only a skip `DECLARED_SKIPS` names counts, and it prints the precondition it declared; an undeclared skip fails, and a dead declaration fails before any suite runs) are in [docs/VERIFICATION.md](docs/VERIFICATION.md).
-Distro and user are no longer hardcoded: `DSH_WSL_DISTRO` / `DSH_WSL_USER` / `DSH_WSL_HOME` can override, with defaults read live from `wsl.exe`.
-## Development
-```bash
-git clone https://github.com/zcluo/dsh-wsl-desktop.git
-cd dsh-wsl-desktop
-node scripts/verify-all.mjs        # full offline run
-.\scripts\sync.ps1                 # stage into the profile and re-point (developer mode: developerTools enabled; a first install needs the wiring first)
-# restart DSH Desktop → verify-post-restart.mjs
-```
-Repository layout:
+plugin_manager install_bundle dsh-wsl-desktop@<version>
 ```
-lib/index.js            Host: routes, preset generation, session preset binding
-lib/client.js           Browser: the W button next to the sidebar "+" + the add-WSL-workspace dialog
-lib/wsl/paths.js        UNC ↔ Linux ↔ drive-letter translation (pure functions)
-lib/wsl/world.js        Distro discovery, the wsl.exe execution core, directory facts
-lib/wsl/shell.js        ShellExecutor implementation (WSL bash + confinement hookup)
-lib/wsl/fs.js           LocalFileSystem subclass (9P backend + path dialects)
-lib/wsl/publish.js      The overwrite publication's wait bound (retry + measured tail; pure module, independently testable)
-lib/wsl/watch.js        Polling strategies for file watching (pure module, independently testable)
-lib/wsl/subprocess.js   SubprocessRuntime implementation (pipes + terminal; delegates to the host subprocess)
-lib/wsl/pty.js          Terminal handle: two processes driving the in-distro PTY bridge
-lib/wsl/terminal-bridge.py  The PTY bridge running inside the distro (python3 stdlib, zero install)
-lib/wsl/host-refs.js    Cross-module references to the host subprocess provider (required after realm isolation)
-lib/wsl/confinement.js  Mount-namespace confinement (pure functions + probing, independently testable)
-lib/wsl/fence.js        Containment comparison and writable-root derivation for the fs fence (pure functions, independently testable)
-lib/wsl/preset.js       Preset rewriting (pure text, independently testable)
-scripts/sync.ps1        Stages the plugin into the profile (then installed by plugin_manager)
-scripts/env.mjs         Distro/user/home resolution for verification (no hardcoded machine identity)
-scripts/verify-*.mjs    Standalone verification (no harness needed)
-scripts/verify-all.mjs  Aggregates and runs all suites (--live adds the suites needing a running host)
-```
-Host-code changes require **restarting DSH Desktop** to load; after a restart, run `verify-post-restart.mjs` first — when old modules are still in effect it reports "please restart" directly instead of giving a false green. **Browser-half changes need no restart**, but "the file changed" is not "the served bytes changed" — the full boundary of hot reload, together with `sync.ps1`'s "keep the two newest" retention rule, is in [docs/ENGINEERING-NOTES.md](docs/ENGINEERING-NOTES.md).
-How the execution world is decided by the session's agent preset, where the session-binding seam is, and the DOM-layer implementation of the UI entry point are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
-## Release
-**Maintainer release**: semantic versioning — patch = defect fixes; minor = compatible desktop-major adaptation (each harness break adaptation bumps minor, e.g. the 0.1.7 adaptation in 0.1.x); major = boundary semantics or support-matrix changes. Flow: bump the `package.json` version → full suites + `verify-post-restart.mjs` all green → `npm publish --access public` → git tag. The `files` manifest already includes `lib/wsl/dsh-wsl-confine.sh` (the helper ships with the package).
-> ⚠️ **`exports["./client"]` is a hard contract and the easiest thing to delete while editing metadata.** One package that declares `dsh.client` without `exports["./client"]` refuses to compose, and the **whole desktop fails to start** (not just this plugin) — which is why 0.2.0 and 0.2.1 **cannot start at all once installed**. `scripts/verify-modules.mjs` now pins this, so running it before a release catches the regression; the incident is recorded in [docs/ENGINEERING-NOTES.md](docs/ENGINEERING-NOTES.md).
+**Update**: install a new version number. After a desktop-major update, run `verify-post-restart.mjs`
+once first; the "what will surprise you" section says why.
+**Uninstall**: uninstall through the plugin manager. The `wsl-*` presets this plugin registers are
+withdrawn with it, so no workspace is left pointing at a plugin that no longer exists.
+## How to use it
+In the sidebar workspace title bar there is an extra **W** button to the right of the built-in "+"
+(add workspace). Click it, then go in order:
+1. **Pick a distribution.** The installed WSL distributions are listed.
+2. **Enter a user.** This is the user to enter that distro with, and it decides whose home you browse.
+   **Leave it empty for the distro's default user.** If the user does not exist, the error appears in
+   place in the popup and browse mode is not entered.
+3. **Pick a directory.** Browse, or type a Linux path. You land in that user's home directory; the
+   host resolves the user database inside the distro with `getent passwd`.
+4. **Create and open the session.**
+A few details you will run into:
+- **Switching distributions asks for the user again**, including re-clicking the one already selected;
+  the field starts from the name you confirmed last time.
+- **While a session creation is in flight, the distribution buttons are unclickable**, so a submission
+  cannot change target halfway.
+- **This step only decides whose home is browsed, not the session identity.** The session always runs
+  inside the distro as the distro's default user; the plugin's configured `username` is not passed
+  along with session creation.
+- In the sidebar workspace list, **a workspace whose path is under a WSL UNC root shows a ☁️ icon
+  instead of a folder**. UNC is Windows' spelling for a subsystem or network path, of the form
+  `\\wsl.localhost\<distro>\home\...`.
+- The built-in "+" keeps the deployment's own behaviour (the Electron directory picker on Desktop);
+  this plugin does not override it.
+- Inside an open WSL workspace, the file list and the terminal are the distro's. PowerShell in Windows
+  workspaces is unaffected.
+## What will surprise you
+These are real boundaries, not a disclaimer list. Each one tells you where to read further.
+- **The search tools behave differently from the host.** `grep` / `glob` in a WSL session use the
+  distro's own `grep` / `find`, so: the regex dialect is POSIX ERE, which means `\d` and `(?i)` do
+  not work · `.gitignore` is not parsed, only the six VCS directories are skipped · dotted
+  directories are searched · `include` matches the base name only and has no brace expansion · a
+  record whose path contains `:` may be dropped or mis-attributed · binary files never match · a
+  capped result is not saved anywhere. The eight differences and the limits are in
+  [Search inside the distribution](docs/SEARCH.md).
+- **The terminal goes through a PTY bridge and does not support `stdio.control`.** A terminal needs a
+  real pseudo-terminal (PTY) inside the distro, but `wsl.exe` only carries three pipes, so the plugin
+  runs a small bridge inside the distro and drives it from two host-side processes. The terminal's
+  `stdio.control` fd channel is explicitly rejected because `wsl.exe` cannot forward arbitrary
+  descriptors. How the bridge is driven is in [Terminal (PTY bridge)](docs/PTY-BRIDGE.md).
+- **The file fence governs the model, not you.** The GUI's web terminal is **unfenced by design** —
+  what you type in the terminal panel is the same as opening a shell in the distro yourself; what is
+  confined is the model's `bash`. Also, **the terminal path has no PID namespace** — the Linux
+  mechanism that lets a group of processes see only themselves and not the rest of the system —
+  while the one-shot command path keeps it. Both boundaries are written out in
+  [The persistent shell](docs/PERSISTENT-SHELL.md).
+- **`/dev`, `/proc`, `/sys` and interop are outside the fence.** They are not file storage, so the
+  plugin reports its own `enforcement` field as `partial` (partial coverage) instead of calling it
+  "sandboxed".
+- **The subprocess surface is not fenced.** The host's own subprocess surface — terminating managed
+  processes, output overflow, reclaiming them — is not bound by the file fence; that is a design
+  decision, not an omission. See [Security and trust boundaries](SECURITY.md).
+- **The retained passwordless sudo grant can bypass the file fence.** The session user keeps the grant
+  the plugin itself needs to build the fence, so a confined command can re-invoke it. There are two
+  closing paths — the helper, and NO_NEW_PRIVS, a kernel flag that stops a process from ever gaining
+  privileges — and their real reachability is in [Security and trust boundaries](SECURITY.md).
+- **File-change watching polls; it is not event-driven.** 9P is the share WSL uses to expose the
+  distro's files to Windows, and `fs.watch` throws `EISDIR` on it. So the plugin polls on the host
+  side: a directory checks its entry set every 300ms, a file gets a `stat` every 300ms. **A directory
+  target is invalidated by entry changes only** — adds, removes and renames are seen, a content change
+  of a file inside it is not; watch that file's own path to follow content. Mechanisms and
+  measurements are in [WSL file watching](docs/WATCH.md).
+- **A desktop update can break the plugin.** The plugin depends on the desktop framework's APIs — the
+  harness — and changes to them interrupt it (0.1.6 → 0.1.7 broke four places in one go). So after
+  updating the desktop, run `node scripts/verify-post-restart.mjs` once and only keep going when
+  everything is green.
+- **Who it is for.** For now it suits the plugin author or an operator of the same trust level, for
+  long-term use. Distribution to third-party users, or unattended high-value environments, are not
+  suitable yet — the reasoning is in [SECURITY.md](SECURITY.md).
+## Where to read more
+- [Security and trust boundaries](SECURITY.md) — trust boundaries, disclosed unconfined surfaces, audit results
+- [Architecture and the execution world](docs/ARCHITECTURE.md) — how a session binds its execution world, and why the UI does what it does
+- [Confinement (Linux side)](docs/CONFINEMENT.md) — the mount-namespace fence, the helper, measured preconditions
+- [The fs tool fence](docs/FS-FENCE.md) — how out-of-bounds file access is decided
+- [Terminal (PTY bridge)](docs/PTY-BRIDGE.md) — how the terminal gets inside the distro
+- [The persistent shell](docs/PERSISTENT-SHELL.md) — the model's `bash`: gap list, limits, manual checklist
+- [Search inside the distribution](docs/SEARCH.md) — the eight semantic differences, the limits, how to verify yourself
+- [WSL file watching](docs/WATCH.md) — the polling strategy and its boundaries
+- [Verification](docs/VERIFICATION.md) — what each suite is responsible for, and how a SKIP is ruled
+- [Engineering notes](docs/ENGINEERING-NOTES.md) — measured constraints, repository layout, release flow, install shape
+- [Distro support matrix](docs/DISTRO-SUPPORT.md) — which distros were verified, and what each one needs
+- [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) — the two proposals to the harness upstream
+- [Architecture and flow diagrams](docs/diagrams.md) — interactive architecture, sequence and lifecycle diagrams
+Three of the linked documents — the distro support matrix, the upstream proposals and the diagram
+index — are **Chinese-only**, because no English text for them exists. Translating them is a separate
+piece of work, not a rename.
+## For maintainers
+This section is for people changing this repository; if you only want to use the plugin, the above is
+enough.
+- `README.md` and this file are a declared bilingual pair: `scripts/verify-docs.mjs` requires both
+  sides to name the same repository artifacts.
+- Self-check: `node scripts/verify-all.mjs` runs every offline suite; add `--live` for the suites that
+  need the installed plugin and a running host. Per-suite responsibilities and the SKIP ruling are in
+  [Verification](docs/VERIFICATION.md).
+- The repository layout, the install shape and the release flow are in
+  [Engineering notes](docs/ENGINEERING-NOTES.md). What semantic versions mean in this repository,
+  and the `npm publish` steps, are documented there too.
+- ⚠️ **`exports["./client"]` is a hard contract.** One package that declares `dsh.client` without
+  `exports["./client"]` makes the host refuse to compose, and the **whole desktop fails to start**.
+  `scripts/verify-modules.mjs` pins this, so running it before a release catches the regression. The
+  incident is in [Engineering notes](docs/ENGINEERING-NOTES.md).
+- Distribution and user are not hardcoded: `DSH_WSL_DISTRO` / `DSH_WSL_USER` / `DSH_WSL_HOME` can
+  override, with defaults read live from `wsl.exe`.
 ## License

package/README.md CHANGED Viewed

@@ -2,135 +2,145 @@
 简体中文 | [English](README.en.md)
-把 WSL 发行版变成 DSH Desktop 里的**一等执行世界**：工作区可以落在发行版内，shell、文件工具、subprocess 与终端随之全部在发行版里运行——而同一实例里的 Windows 工作区仍走宿主自己的沙箱后端，两者并存。
+## 这是什么
-> **生产状态：受控单机生产可用**（见下方边界定义）。需要 **DSH Desktop 0.1.7+**（预设通过运行时注册而非目录加载，旧版宿主会在激活时明确拒绝）。核心能力已活体验收；安全审计 run-1（5 候选闭环）与 run-2（4 confirmed 已修复 + 1 rejected 转加固）均完成，报告见 `security-audit-skill/dsh-wsl-desktop/run-{1,2}/`。逐项证据强度见下方能力表。
->
-> **边界定义**：
-> - ✅ **适合**：插件作者本人或同信任级别操作者，在明确支持的发行版（见 [发行版支持矩阵](docs/DISTRO-SUPPORT.md)）与 0.1.7+ 桌面上长期使用。
-> - ⚠️ **条件**：confined 模式的信任边界依赖 NO_NEW_PRIVS（debian 系现代 setpriv 满足；setpriv 不认 `--no-new-privs` 时 confined 模式**根本不运行**——direct runner 在测到 `false` 时拒绝，helper 的降权用同一个标志、同样失败关闭，见 [安全与信任边界](SECURITY.md)）。
-> - ❌ **尚不适合**：分发给第三方用户（缺桌面版本门控与发行版矩阵）、无人值守高价值环境（subprocess 面不设防为已披露设计；对 harness 上游的两项 API 提案见 [docs/UPSTREAM-PROPOSALS.md](docs/UPSTREAM-PROPOSALS.md)）。
+一个 DSH Desktop 插件。它让你的 WSL 发行版变成可以直接干活的地方：把工作区建在发行版里，AI 的
+shell 命令、文件读写、搜索和终端就都跑在发行版内，而不是跑在 Windows 上。
-## 目录
+## 为什么你会想要它
-- **本页**：[目标能力](#目标能力) · [安装 / 更新 / 卸载](#安装--更新--卸载) · [快速开始](#快速开始) · [桌面更新纪律](#桌面更新纪律强制) · [安全与信任边界](#安全与信任边界) · [已知限制](#已知限制) · [校验](#校验) · [开发](#开发) · [发版](#发版)
-- **深入材料**：[安全与信任边界](SECURITY.md) · [架构与执行世界](docs/ARCHITECTURE.md) · [Linux 侧约束](docs/CONFINEMENT.md) · [fs 工具的围栏](docs/FS-FENCE.md) · [终端 PTY 桥](docs/PTY-BRIDGE.md) · [WSL 文件变更监听](docs/WATCH.md) · [校验与 SKIP 裁定](docs/VERIFICATION.md) · [工程笔记](docs/ENGINEERING-NOTES.md) · [发行版支持矩阵](docs/DISTRO-SUPPORT.md) · [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) · [架构与流程图](docs/diagrams.md)
+插件给每个 WSL 会话配一套"预设"，预设就是会话启动时拿到的那一整套工具配置。这套配置把 shell、
+文件读写、搜索、终端都指向发行版，所以：
-## 目标能力
+- **你的 Linux 工具真的能用。** 工作区放在发行版里，AI 用的是发行版自己的 `bash`、`grep`、`find`、
+  解释器和包。
+- **命令之间不再各过各的。** 模型侧的 `bash` 是一条常驻 shell，上一次调用留下的当前目录和环境变量，
+  下一次调用还看得见。
+- **两种工作区可以同时开着。** 同一个窗口里，Windows 工作区照旧跑在宿主自己的沙箱后端上，WSL 工作区
+  跑在发行版里，互不干扰。
+- **可以顺手用到 Windows 那边的东西。** 在发行版里能调用宿主机的命令；WSL 把这项功能叫 interop，
+  它在发行版里默认开着。
-**活体验收通过后的诚实状态**（`verify-post-restart.mjs` 最近一次实跑：**58 PASS / 0 FAIL**、尾部 `NO AUTOMATED FAILURES; 3 manual step(s) pending`、`EXIT=0`——包括搜索的两条活体行与常驻 shell 的那几条；**剩 3 条浏览器专属的人工项**，清单见 [常驻 shell](docs/PERSISTENT-SHELL.md#人工核验清单浏览器专属不可自动化)，加离线 20 套件；下面每条都注明证据强度）：
+## 装之前要有什么
-| # | 能力 | 状态 |
-|---|---|---|
-| ① | 工作区可选择 WSL 发行版里的 Linux 目录 | 对话框与宿主调用已实现并活体通过（listDir/checkPath/resolveHome/工作区注册与清理）；**浏览器内交互已由操作者人工确认**（门控流、目录浏览、终端面板均正常） |
-| ② | 该工作区内的 shell / 文件工具 / subprocess / 终端 在 WSL 里工作，且可从 WSL 调用宿主机命令 | **活体验收 PASS**：绑定（创建请求命名 preset）、shell 进发行版、fs 工具 Linux 寻址、越界写拒绝、subprocess POSIX 环境、bash 工具、工具层约束；终端传输由 PTY 套件覆盖。**模型侧的 `bash` 是发行版内的常驻 PTY shell，cwd 与环境变量跨调用保留**（活体验证：两次调用读数一致；缺口清单见 [常驻 shell](docs/PERSISTENT-SHELL.md)） |
-| ③ | 同一实例里 Windows 与 WSL 工作区并存 | **活体验收 PASS**：Windows 工作区停留在宿主 preset（PowerShell 可用、无 bash），WSL 会话并行运行 confined realm |
-| ④ | WSL 侧的 Linux 沙箱约束 | **shell 侧已修并活体验证**：运行时枚举所有 `rw` 挂载逐个改只读（实测 `/mnt/c`、`/dev/shm`、`/run/user/<uid>` 从 WRITABLE 变 READONLY）、失败即拒（保留退出码 97）、`enforcement` 如实报 `partial`。**fs 侧围栏已实现并活体验证**（越界写拒绝 PASS，见 [fs 工具的围栏](docs/FS-FENCE.md)）|
+- **WSL2**。不是 WSL1。
+- **一个受支持的发行版。** Debian、Ubuntu、Fedora/RHEL、Arch 已实测通过，Alpine 装上
+  `bash` 与 `util-linux-misc` 后也可以。清单与每种发行版的安装命令见
+  [发行版支持矩阵](docs/DISTRO-SUPPORT.md)。
+- **DSH Desktop 0.1.7 或更高。** 旧版宿主在激活时会明确拒绝。
+- **会话用户能免密 sudo，并且有 `bash` 和 `python3`。** 这一条最容易卡住。受限模式要在发行版内部
+  搭一个 mount namespace（让进程看到一份独立挂载表的 Linux 机制），把文件系统改成只读，而 WSL 内核
+  不允许在 user namespace 里做 bind mount，所以只能用 `sudo -n`。没有免密 sudo 时受限模式会
+  **明确失败**，不会退回去裸跑。
+- **建议再装一个 helper。** helper 是装在发行版里的一份小脚本 `dsh-wsl-confine`，用来闭合"用户保留的
+  sudo 授权"这条边界。安装命令见 [Linux 侧约束](docs/CONFINEMENT.md)。它是可选的，但推荐。
-**哪些能力有保留**（证据强度就是上表状态列的措辞）：终端不支持 `stdio.control`——写在「已知限制」里，不藏。常驻 shell 的缺口同样写在「已知限制」里，权威清单在 [常驻 shell](docs/PERSISTENT-SHELL.md)。
+## 怎么装
-## 安装 / 更新 / 卸载
+**插件市场 / 插件管理器（推荐）**：安装 `dsh-wsl-desktop@<version>`。桌面会自动把包装进 pnpm 工作区，
+并把 bundle patch（插件挂进桌面的那份配置）挂上，重启即用。
-**用户安装（生产通道）**：本插件以 npm 包形式发布，形态对齐 dsh-better-sidebar 等成熟插件（`files` 精确清单 + `cordis.patch.yml` bundle patch + `dsh.client.inject` 客户端接线 + `manifestVersion`）。
-- 插件市场 / 插件管理器：安装 `dsh-wsl-desktop@<version>`——桌面自动完成 pnpm 接线与 bundle patch 挂载，重启即用。
-- 命令行等价：`plugin_manager install_bundle dsh-wsl-desktop@<version>`。
-- **安装前提**：WSL2 + 目标发行版满足[支持矩阵](docs/DISTRO-SUPPORT.md)——会话用户 NOPASSWD sudo、bash、python3；推荐同时安装 dsh-wsl-confine helper 闭合围栏边界（安装命令见 [docs/CONFINEMENT.md](docs/CONFINEMENT.md)）。
-- **更新**：安装新版本号即可；桌面大版本更新后按「桌面更新纪律」先跑 `verify-post-restart.mjs`。
-- **卸载**：插件管理器卸载即同时撤回本插件注册的 wsl-* 预设（disposer 生命周期保证）。
-> **版本对应关系**：当前 `0.3.x` 系列要求 DSH Desktop **0.1.7+**。语义化版本的含义见「发版」——`minor` 就是"适配了某个新的桌面大版本"，所以**桌面大版本变了要先看这里有没有对应的 minor**。
-## 快速开始
-侧栏工作区标题栏里，自带的"+"（添加工作区）右边多一个 **W** 按钮。点开是本插件的工作区对话框，顺序是：选发行版 → 输入要进入该发行版的用户（**留空 = 发行版默认用户**）→ 浏览或输入 Linux 目录 → 创建并打开会话。
-进入浏览后，路径直接落在该用户的主目录（宿主在发行版内用 `getent passwd` 解析用户数据库）。输入的用户不存在时，错误就地显示在弹层里，不会进入浏览。切换发行版——**包括重新点击当前已选中的那个**——都会重新弹出用户输入框，并带上一次确认过的用户名作为起点。创建会话进行中时发行版按钮暂时不可点。
-边界要说清楚：这一步只决定"浏览谁的 home"，**不决定会话身份**——会话在发行版里始终以发行版默认用户执行（`username` 是插件配置，不随会话创建传递）。
-侧栏工作区列表里，**路径落在 WSL UNC 下的工作区，行首图标是 ☁️ 而不是文件夹**。"+" 保持部署自带的行为（Desktop 上是 Electron 目录选择器），本插件不改写它。
-界面与 DOM 层为什么这么做（"隐藏必须用 `display`、不能用 `remove()`"、"不要用定时器兜底"这类实测结论），见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
-## 桌面更新纪律（强制）
-每次 DSH Desktop 更新后，插件可能因 harness 内部 API 变化而失效（0.1.6→0.1.7 即断裂四处）。**纪律：更新桌面 → 跑 `node scripts/verify-post-restart.mjs` → 全绿才继续使用；任何一次红都先修再干。** 该套件覆盖预设注册、执行世界、会话绑定、Windows 隔离与对话框契约；新宿主的破坏会在这些断言上现形，而不是静默降级成宿主世界。
-## 安全与信任边界
-- **宿主侧**：Windows 工作区会话仍跑在 DSH 自带的沙箱后端里，本插件不替换它们。
-- **发行版内 shell 侧**：在 mount namespace 里把 `/` 改只读，只留工作区与一个私有 `/tmp` 可写；**约束建立失败即拒绝执行**，不裸跑。机制与实测前提见 [docs/CONFINEMENT.md](docs/CONFINEMENT.md)。
-- **发行版内 fs 侧**：`WslFileSystem` 自带围栏，两个变更入口都先过 `checkedTarget`，越界抛结构化 `FS_SANDBOX_DENIED`。见 [fs 工具的围栏](docs/FS-FENCE.md)。
-**已披露的不设防面**：宿主 subprocess 面不设防是设计取舍，不是遗漏。**围栏的已知边界**：会话用户保留的免密 sudo 授权可以重新调用它绕过文件围栏，两条闭合路径与它们的实际可达性见 [SECURITY.md](SECURITY.md)。
-## 已知限制
-**grep / glob 工具在 WSL 会话里可用，后端是发行版自己的 `grep` / `find`。** 宿主那两行依然被移除，理由是实测的两件事：`tool-fs-search` 虽然通过 `ctx.subprocess.spawn()` 启动（`search-core.ts:238`），但它的 `argv[0]` 是 `@vscode/ripgrep` 提供的**打包 Windows rg.exe**（`search-core.ts:174-178`）——在发行版里既不存在、也无法用 Linux 参数工作；而发行版自带 `/usr/bin/grep` 与 `/usr/bin/find`（实测：发行版里 `command -v rg` 回答为空）。所以 `wsl-world` 组把这两个名字挂回本插件自己的实现（`lib/wsl/search-tool.js`），模型在 WSL 会话里照常调用 `grep` / `glob`——**但语义是发行版工具的**：POSIX ERE（没有 `\d`、`(?i)`）· 不解析 `.gitignore`（只排除六个 VCS 目录）· 点目录会被搜到 · `include` 只匹配 basename 且没有花括号 · 模式按搜索根相对解释、`*` 与 `**/` 跨 `/` · 路径含 `:` 的记录可能被丢弃或被静默错配 · 二进制文件永不被匹配 · 达到上限的截断不落盘。**这串要点是摘要，缺口的权威清单在文档里**（文档八条中第 5、6 条在这里并成了一条；末条「截断不落盘」是限额，不是缺口）。八条缺口、限额、未测项与怎么自己验，见 [发行版内搜索](docs/SEARCH.md)。
-**终端走 PTY 桥，PTC 的 `stdio.control`（fd 通道）明确拒绝**——`wsl.exe` 无法转发任意描述符。桥的驱动方式与实测前提见 [docs/PTY-BRIDGE.md](docs/PTY-BRIDGE.md)。
-**常驻 shell 的缺口摘要**：模型侧的 `bash` 是发行版内的常驻 PTY shell，但它有两条要命的边界——**（1）宿主 `ctx.sandbox` 会包一层 `wsl.exe` 的 argv**，而本仓自己判定宿主沙箱对它**无法约束**（实测：包装之后仍然跑得起来，所以 realm 里自建了 `sandbox` 提供者，把这一层变成发行版内的约束）；**（2）终端这条路没有 PID namespace**，而 GUI 的网页终端按设计**不受 fence 约束**——受约束的是模型的 `bash`，不是用户在终端面板里敲的那条。**这串只是摘要，缺口的权威清单在文档里**：九条缺口、限额、未测项、3 条人工核验清单与怎么自己验，见 [常驻 shell](docs/PERSISTENT-SHELL.md)。
-**约束覆盖不到 `/dev`、`/proc`、`/sys` 与 interop**，如实报在 `enforcement: 'partial'` 里；而会话用户保留的免密 sudo 授权可绕过文件围栏，闭合路径见 [SECURITY.md](SECURITY.md)。
-**WSL 工作区里的文件变更跟踪是轮询的，不是事件驱动的。** 发行版的 9P 共享上 `fs.watch` 会抛 `EISDIR`（文件与目录目标都抛），宿主后端的 chokidar 监听因此在 WSL 目标上根本无法初始化；插件改为在宿主侧轮询——目录看条目集合（每 300ms 一次 `readdir`，实测本进程 0ms CPU/3s、延迟 2–3ms），文件与尚不存在的路径走 `fs.watchFile`（每 300ms 一次 `stat`，实测 0ms CPU/3s、延迟 52ms）。**目录目标只对条目集合变化失效**：新增、删除、改名可见，目录内某个文件的**内容**变化不可见——要盯着某个文件，就按文件路径监听它。机制、实测与未测项见 [WSL 文件变更监听](docs/WATCH.md)。
-## 校验
-```powershell
-node scripts/verify-all.mjs          # 全部离线套件（20 个）
-node scripts/verify-all.mjs --live   # 追加需要已安装插件 + 运行中宿主的套件
-```
-逐套件职责、单跑命令、以及**聚合器怎么读 SKIP**（退出码 2 是套件自己的 SKIP；只有 `DECLARED_SKIPS` 点名的跳过才算数并打印它的前提，未声明的跳过判红，失效的声明在任何套件运行之前先判红），见 [docs/VERIFICATION.md](docs/VERIFICATION.md)。
-发行版与用户不再硬编码：`DSH_WSL_DISTRO` / `DSH_WSL_USER` / `DSH_WSL_HOME` 可覆盖，默认从 `wsl.exe` 现读。
-## 开发
-```bash
-git clone https://github.com/zcluo/dsh-wsl-desktop.git
-cd dsh-wsl-desktop
-node scripts/verify-all.mjs        # 离线全量
-.\scripts\sync.ps1                 # stage 进 profile 并重指向（开发者模式：developerTools 开启；首次安装需先接线）
-# 重启 DSH Desktop → verify-post-restart.mjs
-```
-仓库布局：
+**命令行等价**：
 ```
-lib/index.js            Host：路由、预设生成、会话预设绑定
-lib/client.js           浏览器：侧栏"+"旁的 W 按钮 + 添加 WSL 工作区对话框
-lib/wsl/paths.js        UNC ↔ Linux ↔ 盘符 互译（纯函数）
-lib/wsl/world.js        发行版发现、wsl.exe 执行核、目录事实
-lib/wsl/shell.js        ShellExecutor 实现（WSL bash + 约束接入）
-lib/wsl/fs.js           LocalFileSystem 子类（9P 后端 + 路径方言）
-lib/wsl/publish.js      覆盖发布的等待边界（重试 + 实测尾部；纯模块，可独立测试）
-lib/wsl/watch.js        文件变更监听的轮询策略（纯模块，可独立测试）
-lib/wsl/subprocess.js  SubprocessRuntime 实现（管道 + 终端；委托宿主 subprocess）
-lib/wsl/pty.js         终端句柄：两个进程驱动发行版内的 PTY 桥
-lib/wsl/terminal-bridge.py 发行版内运行的 PTY 桥（python3 标准库，零安装）
-lib/wsl/host-refs.js    宿主 subprocess provider 的跨模块引用（realm 隔离后必需）
-lib/wsl/confinement.js  mount namespace 约束（纯函数 + 探测，可独立测试）
-lib/wsl/fence.js        fs 围栏的包含性比较与可写根推导（纯函数，可独立测试）
-lib/wsl/preset.js       预设重写（纯文本，可独立测试）
-scripts/sync.ps1        把插件 stage 进 profile（随后由 plugin_manager 安装）
-scripts/env.mjs         校验用的发行版/用户/home 解析（不硬编码机器身份）
-scripts/verify-*.mjs    独立校验（不需要 harness）
-scripts/verify-all.mjs  聚合运行全部套件（--live 追加需要运行中宿主的套件）
+plugin_manager install_bundle dsh-wsl-desktop@<version>
 ```
-宿主代码改动需要**重启 DSH Desktop** 才会加载，重启后先跑 `verify-post-restart.mjs`（它会在旧模块仍生效时直接报「请重启」而不是给假绿）。**浏览器半边改动不需要重启**，但"文件已改"不等于"投放已变"——热更新的完整边界、以及 `sync.ps1` 的"保留最新两代"规则，见 [docs/ENGINEERING-NOTES.md](docs/ENGINEERING-NOTES.md)。
-执行世界由会话的 agent preset 决定、会话绑定的接缝在哪、界面入口的 DOM 层实现，见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
-## 发版
-**维护者发版**：语义化版本——patch = 缺陷修复；minor = 兼容的桌面大版本适配（每次 harness 断裂适配后升 minor，如 0.1.x 的 0.1.7 适配）；major = 边界语义或支持矩阵变化。流程：改 `package.json` version → 全量套件 + `verify-post-restart.mjs` 全绿 → `npm publish --access public` → 打 git tag。`files` 清单已含 `lib/wsl/dsh-wsl-confine.sh`（helper 随包分发）。
-> ⚠️ **`exports["./client"]` 是硬性契约，改元数据时最容易误删。** 只要有一个包声明了 `dsh.client` 却没有 `exports["./client"]`，宿主就直接拒绝组合，**整张桌面启动失败**（不是本插件单独失效）——v0.2.0 与 0.2.1 因此装上去就起不来。`scripts/verify-modules.mjs` 现在钉住这条，发版前跑它即可拦住；事故经过见 [docs/ENGINEERING-NOTES.md](docs/ENGINEERING-NOTES.md)。
+**更新**：装一个新版本号就行。桌面大版本更新之后，先跑一次 `verify-post-restart.mjs`
+（见「会意外的地方」里桌面更新那一条）。
+**卸载**：用插件管理器卸载即可。本插件注册的 `wsl-*` 预设会一起撤回，不会留下指向不存在插件的工作区。
+## 怎么用
+侧栏工作区标题栏里，自带的「+」（添加工作区）右边多出一个 **W** 按钮。点它，然后按顺序走：
+1. **选发行版。** 已安装的 WSL 发行版会列出来。
+2. **输入用户。** 这是要进入该发行版的用户，用来决定"浏览谁的 home"。**留空 = 发行版默认用户。**
+   用户名不存在时，错误就地显示在弹层里，不会进入浏览。
+3. **选目录。** 浏览或直接输入 Linux 路径。进来时路径落在上一步那个用户的主目录，
+   宿主在发行版内用 `getent passwd` 解析用户数据库。
+4. **创建并打开会话。**
+几个会碰到的细节：
+- **切换发行版会重新问用户**，包括重新点当前已选中的那个；输入框会带上一次确认过的名字作为起点。
+- **创建会话进行中时，发行版按钮暂时点不动**，避免提交到一半换了目标。
+- **这一步只决定浏览谁的 home，不决定会话身份。** 会话在发行版里始终以发行版的默认用户执行；
+  插件配置里的 `username` 不随会话创建传递。
+- 侧栏工作区列表里，**路径落在 WSL UNC 下的工作区，行首图标是 ☁️ 而不是文件夹**。UNC 是 Windows
+  表示网络/子系统路径的写法，形如 `\\wsl.localhost\<发行版>\home\...`。
+- 自带的「+」保持部署原本的行为（桌面上是 Electron 的目录选择器），本插件不改写它。
+- 已经打开的 WSL 工作区里，文件列表和终端都是发行版内的。Windows 工作区里的 PowerShell 不受影响。
+## 会意外的地方
+这些都是真的边界，不是缺陷清单的免责声明。每条都给了读下去的地方。
+- **搜索工具的语义和宿主不一样。** WSL 会话里的 `grep` / `glob` 用的是发行版自己的
+  `grep` / `find`。所以正则方言是 Linux 上 grep 的标准方言 POSIX ERE，`\d` 与 `(?i)` 都不可用。
+  它也不解析 `.gitignore`，只排除六个 VCS 目录。点目录会被搜到；`include` 只匹配
+  basename 且不支持花括号；路径含 `:` 的记录可能被丢弃或错配；二进制文件永远不匹配；
+  到上限的结果不落盘。完整八条与限额见 [发行版内搜索](docs/SEARCH.md)。
+- **终端走 PTY 桥，不支持 `stdio.control`。** 终端要在发行版里真的开出一个伪终端（PTY），
+  而 `wsl.exe` 只有三条管道，所以插件在发行版里跑一个小桥，由宿主侧两个进程驱动它。终端的
+  `stdio.control` 那条 fd 通道明确拒绝，因为 `wsl.exe` 无法转发任意描述符。桥怎么驱动见
+  [终端（PTY 桥）](docs/PTY-BRIDGE.md)。
+- **文件围栏管的是模型，不是你。** GUI 的网页终端按设计**不受围栏约束**——你在终端面板里敲的命令
+  和在发行版里直接开一个 shell 一样；受约束的是模型侧那条 `bash`。另外**终端这条路没有
+  PID namespace**：PID namespace 是让一组进程只看得见自己那棵进程树的 Linux 机制，而终端这条路
+  没有它，一次性命令路径则有。两条边界的完整说明见 [常驻 shell](docs/PERSISTENT-SHELL.md)。
+- **`/dev`、`/proc`、`/sys` 和 interop 在围栏之外。** 它们不是文件存储，所以插件把自我报告的
+  `enforcement` 字段报成 `partial`（部分覆盖），而不是说成"已沙箱化"。
+- **subprocess 这一面不设防。** 托管进程的终止、输出溢出与回收，都仍归宿主自己的 subprocess
+  provider，不受文件围栏约束。这是设计取舍，不是遗漏。见 [安全与信任边界](SECURITY.md)。
+- **保留的免密 sudo 能绕过文件围栏。** 会话用户保留着插件建立围栏时自己要用的那份授权，所以被约束
+  的命令可以重新调用它。两条闭合路径是 helper 与 NO_NEW_PRIVS。后者是内核标志，让进程再也拿不到
+  提权。两条路径的实际可达性见 [安全与信任边界](SECURITY.md)。
+- **文件变更监听是轮询的，不是事件驱动的。** 9P 是 WSL 把发行版文件暴露给 Windows 的那套共享，
+  在它上面 `fs.watch` 会抛 `EISDIR`。所以插件改为在宿主侧轮询：目录每 300ms 看一次条目集合，
+  文件每 300ms `stat` 一次。**目录目标只对条目变化生效**——新增、删除、改名可见，目录里某个文件的
+  内容变化不可见；要盯内容就按文件路径监听它。机制与实测见
+  [WSL 文件变更监听](docs/WATCH.md)。
+- **桌面更新后插件可能失效。** 插件依赖桌面内部的框架（harness）的 API，这些 API 变化会打断它
+  （0.1.6 → 0.1.7 一次断了四处）。所以更新桌面之后先跑一次
+  `node scripts/verify-post-restart.mjs`，全绿再继续用。
+- **适合谁用。** 目前适合插件作者本人或同信任级别的操作者长期使用。分发给第三方用户、或放进
+  无人值守的高价值环境，都还不适合——理由写在 [SECURITY.md](SECURITY.md)。
+## 想读更多
+- [安全与信任边界](SECURITY.md) — 信任边界、已披露的不设防面、审计结论
+- [执行世界与架构](docs/ARCHITECTURE.md) — 会话怎么绑定执行世界，界面为什么这样做
+- [Linux 侧约束](docs/CONFINEMENT.md) — mount namespace 围栏、helper、实测前提
+- [fs 工具的围栏](docs/FS-FENCE.md) — 文件读写的越界判定
+- [终端（PTY 桥）](docs/PTY-BRIDGE.md) — 终端是怎么跑进发行版的
+- [常驻 shell](docs/PERSISTENT-SHELL.md) — 模型侧 `bash` 的缺口清单、限额、人工核验清单
+- [发行版内搜索](docs/SEARCH.md) — 八条语义差异、限额、怎么自己验
+- [WSL 文件变更监听](docs/WATCH.md) — 轮询策略与它的边界
+- [校验](docs/VERIFICATION.md) — 每个套件管什么，以及跳过（SKIP）怎么裁定
+- [工程笔记](docs/ENGINEERING-NOTES.md) — 实测约束、仓库布局、发版流程、安装形态
+- [发行版支持矩阵](docs/DISTRO-SUPPORT.md) — 哪些发行版验证过，每种缺什么
+- [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的两项提案
+- [架构与流程图](docs/diagrams.md) — 可交互的架构、时序与生命周期图
+其中三份——发行版支持矩阵、上游 API 提案、架构与流程图索引——**只有中文版**，因为目前没有对应的
+英文文本。把它们翻成英文是一件独立的工作，不是改个文件名。
+## 给维护者
+这一节是给要改这个仓库的人看的；只想用插件的话，上面已经够了。
+- `README.en.md` 与本文件是一对声明过的双语版：`scripts/verify-docs.mjs` 要求两边命名同一批仓库文件。
+- 自检：`node scripts/verify-all.mjs` 跑全部离线套件；加 `--live` 追加需要已安装插件与运行中宿主的
+  套件。逐套件职责与 SKIP 裁定见 [校验](docs/VERIFICATION.md)。
+- 仓库布局、安装形态与发版流程见 [工程笔记](docs/ENGINEERING-NOTES.md)。语义化版本在这个仓库里的
+  具体含义、以及 `npm publish` 的步骤都在那里。
+- ⚠️ **`exports["./client"]` 是硬性契约。** 一个包声明了 `dsh.client` 却没有
+  `exports["./client"]`，宿主会直接拒绝组合，**整张桌面启动失败**。`scripts/verify-modules.mjs`
+  钉住这条，发版前跑它就能拦住。事故经过见 [工程笔记](docs/ENGINEERING-NOTES.md)。
+- 发行版与用户不硬编码：`DSH_WSL_DISTRO` / `DSH_WSL_USER` / `DSH_WSL_HOME` 可覆盖，
+  默认从 `wsl.exe` 现读。
 ## 许可证

package/lib/wsl/search.js CHANGED Viewed

@@ -13,10 +13,10 @@
  * filtering happen in Node, on the parsed output.
  *
  * The other half of the job is what comes BACK. The distribution's tools print formats of
- * their own (`path:line:text` with no escaping, `%T@ %p` NUL-separated), and the parsers
- * below turn that print into the host tool's shape, applying the caps there — in Node,
- * because the vectors ask for everything and only the consumer can stop. The sort is Node's
- * too: a realm has no shell to pipe into `sort`.
+ * their own (`path:line:text` with no escaping; an mtime line followed by the NUL-terminated
+ * path), and the parsers below turn that print into the host tool's shape, applying the caps
+ * there — in Node, because the vectors ask for everything and only the consumer can stop. The
+ * sort is Node's too: a realm has no shell to pipe into `sort`.
  *
  * What a FAILED run means is decided here as well (`searchFailure`), in the host's own two
  * names, so the tool that raises the failure does not get to invent a vocabulary of its
@@ -80,8 +80,46 @@ export function grepArgv(input, caps) {
 }
 /**
- * One `find` argv vector: VCS pruned by -prune, the pattern anchored to the root, mtime
- * printed for the sort in Node.
+ * One `find` argv vector: VCS pruned by -prune, the pattern anchored to the root, and each hit
+ * paired with its mtime so the sort can happen in Node.
+ *
+ * PORTABLE ON PURPOSE, for the reason `pty.js`'s sweep already records: the mtime used to come
+ * from `-printf '%T@ %p\0'`, which is a GNU EXTENSION. On a busybox `find` (Alpine, many minimal
+ * distributions) that predicate is rejected, the refusal lands on stderr, and the empty stdout
+ * parses as "no files match" — a silent empty answer, the one outcome a listing must never
+ * produce. What the vector asks for instead is the pair every `find` carries: `-print0` (the
+ * NUL-terminated listing) and `-exec … ;` (busybox's `FEATURE_FIND_EXEC` and
+ * `FEATURE_FIND_PRINT0` are both default-on), with the distribution's own `stat` printing the
+ * mtime in front of each path. That is ONE spawn, not two — find runs the stat itself, per
+ * match, so the two halves of a record always describe the same hit.
+ *
+ * Why `stat` and not a shell loop: this module has no shell by construction (see the module
+ * docblock), so `stat` has to be executed BY find. Why the bare name: no absolute spelling is
+ * portable — coreutils ships `/usr/bin/stat` (Debian, Fedora) while busybox installs its applet
+ * at `/bin/stat` (Alpine) — so a hardcoded path would break exactly the distributions this
+ * change exists for; `-exec stat` is resolved by find's own `execvp` against the distribution's
+ * PATH.
+ *
+ * The parenthesised `-o -print0` is NOT decoration, it is MEASURED defence: `-exec stat … ;`
+ * and a following `-print0` are joined by an implicit AND, so when `stat` cannot be run the
+ * `-print0` is never reached — and GNU find reports that on stderr while still exiting **0**
+ * (measured: exit 0, empty stdout, two `<find>: 'stat': No such file or directory` lines). A
+ * reader that takes stdout alone would see the SAME silent empty listing this change exists to
+ * remove, one layer down. With the fallback group the paths are printed either way: the mtime
+ * first when `stat` answers, bare NUL-framed paths when it does not — and a bare path is not a
+ * readable record (`stat -c` always ends its line, so the parser needs that newline), which
+ * leaves a NON-EMPTY print that parses to NO path. That is exactly the shape `search-tool.js`'s
+ * own damage guard already raises on ("its output could not be read as path records"), so a
+ * `stat`-less distribution fails LOUDLY through the existing boundary instead of answering an
+ * empty listing. The group also means one unreadable file (a `stat` that fails per hit) only
+ * costs that record, not the whole listing.
+ *
+ * `%.9Y` is the mtime in seconds: GNU coreutils answers fractional seconds (what `%T@` gave the
+ * sort), busybox's format engine pads the same integer to nine digits instead, which parses back
+ * to the identical whole second — so sub-second precision degrades on busybox and the ORDER, the
+ * documented contract, does not. `-print0` rather than `-print` keeps the path in a NUL-framed
+ * record, so a path containing a newline survives; `stat -c` always terminates its own line, and
+ * the parser splits on that FIRST newline (a path may contain more).
  * @param {{ pattern: string, path: string }} input - the model's request.
  * @param {{ maxResults: number }} caps - the caller's cap; not consumed by the vector
  *   (the cap is applied where the output is parsed, not on the command line).
@@ -106,7 +144,17 @@ export function globArgv(input, caps) {
   const argv = ['/usr/bin/find', '--', input.path]
   for (const name of VCS_EXCLUDES) argv.push('-name', name, '-prune', '-o')
   // -path matches the whole printed path, so the model's root-relative pattern is anchored here.
-  argv.push('-path', `${root}/${translateGlob(input.pattern)}`, '-type', 'f', '-printf', '%T@ %p\\0')
+  // The mtime rides on -exec (see the docblock): it prints BEFORE the path, and its own newline is
+  // the record's field separator — MEASURED on GNU find 4.10.0 + coreutils stat, where the output
+  // per hit is `<mtime>\n<path>\0`. `;` and not `+`: with `+` find batches the names and runs stat
+  // at flush points, so the printed mtimes would no longer line up with the paths -print0 streams
+  // out; one stat per hit keeps the two halves interleaved. The trailing `-o -print0` is the
+  // measured fallback for a distribution whose `stat` is missing (see the docblock): it keeps the
+  // listing NON-EMPTY so the stat-less case fails loudly at the tool's damage guard instead of
+  // silently answering "no files match". The parentheses are REQUIRED — find's implicit AND binds
+  // tighter than `-o`, so without them the fallback would not attach to the -path/-type test.
+  argv.push('-path', `${root}/${translateGlob(input.pattern)}`, '-type', 'f',
+    '(', '-exec', 'stat', '-c', '%.9Y', '{}', ';', '-print0', '-o', '-print0', ')')
   return argv
 }
@@ -208,25 +256,28 @@ export function parseGrepOutput(stdout, caps) {
 }
 /**
- * Parse `find -printf '%T@ %p\0'` and order by mtime ASCENDING, in Node (no shell sort).
+ * Parse the glob listing `<mtime>\n<path>\0` and order by mtime ASCENDING, in Node (no shell sort).
  *
  * The record format is the vector's, and both halves of it are load-bearing: the mtime ends at
- * the FIRST space (a path may contain one), and the NUL is the separator because a path may
- * contain a newline — a line-based record would split one path in two. The order is the host's
- * MEASURED one rather than the natural-looking one: the host sorts by mtime ascending (oldest
- * first), so a descender here would be a silent disagreement with it. The cap is applied AFTER
- * the sort, which is what makes "the first N" mean the N oldest rather than whichever N find
- * happened to print first.
+ * the FIRST newline and the NUL is the record separator, because a path may contain both a
+ * newline and a space — a line-based record would split one path in two, and a space-based
+ * field split would cut one at its first space. `stat -c` always terminates its line, so the
+ * newline is the field boundary; the path starts right after it and runs to the NUL. The order
+ * is the host's MEASURED one rather than the natural-looking one: the host sorts by mtime
+ * ascending (oldest first), so a descender here would be a silent disagreement with it. The cap
+ * is applied AFTER the sort, which is what makes "the first N" mean the N oldest rather than
+ * whichever N find happened to print first.
  *
  * A record that cannot be read at all is DROPPED, symmetrically with the grep side (which drops a
  * line without a second colon, and one whose line-number field is not a finite integer — the two
- * tests differ only because the fields do: a count, an mtime). The vector's own `-printf` always
- * emits the space, so a record without one means the print was cut short, and a non-finite mtime
- * means a value this parser cannot order by — a phantom path, or an order that depends on where a
- * NaN landed in V8's sort, would be an answer nobody decided. The drop is deliberately silent
- * (`truncated` is about the CAP, not about damage): for a broken record, no path is the better
- * answer.
- * @param {string} stdout - find's stdout, `%T@ %p` records separated by NUL.
+ * tests differ only because the fields do: a count, an mtime). The vector's own `stat` always
+ * emits the newline, so a record without one means the print was cut short (or `stat` failed for
+ * that hit — find reports that on stderr and exits nonzero, which the tool raises), and a
+ * non-finite mtime means a value this parser cannot order by — a phantom path, or an order that
+ * depends on where a NaN landed in V8's sort, would be an answer nobody decided. The drop is
+ * deliberately silent (`truncated` is about the CAP, not about damage): for a broken record, no
+ * path is the better answer.
+ * @param {string} stdout - find's stdout, `<mtime>\n<path>` records separated by NUL.
  * @param {{ maxResults: number }} caps - the caller's cap.
  * @returns {{ paths: string[], truncated: boolean }} the paths, oldest first, and whether the CAP
  *   left at least one further record out. (The caller's `root` is the tool's own: it fills it
@@ -235,13 +286,14 @@ export function parseGrepOutput(stdout, caps) {
 export function parseGlobOutput(stdout, caps) {
   const entries = stdout.split('\0').filter(entry => entry !== '')
     .map((entry) => {
-      const space = entry.indexOf(' ')
-      // No space means this is not a record the vector could have printed: skip it (never a path
-      // built out of the damage). Not seen: a finite-looking prefix — a record cut before its space
-      // — would pass the mtime check below, so the space itself is what says the record is whole.
-      if (space === -1) return null
-      const mtime = Number(entry.slice(0, space))
-      return Number.isFinite(mtime) ? { mtime, path: entry.slice(space + 1) } : null
+      const newline = entry.indexOf('\n')
+      // No newline means this is not a record the vector could have printed: skip it (never a path
+      // built out of the damage). Not seen: a finite-looking prefix — a record cut before its
+      // newline — would pass the mtime check below, so the newline itself is what says the record
+      // is whole.
+      if (newline === -1) return null
+      const mtime = Number(entry.slice(0, newline))
+      return Number.isFinite(mtime) ? { mtime, path: entry.slice(newline + 1) } : null
     })
     .filter(entry => entry !== null)
     .sort((a, b) => a.mtime - b.mtime)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-desktop",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./lib/icon.svg",