dsh-plugin-wsl-env 0.1.10 → 0.3.0

package/CHANGELOG.md

@@ -12,6 +12,274 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+### Added
+
+- **`maskWindowsDrive` on `wsl-shell` and `wsl-fs`** — the mitigation knob for
+  the interop hole the sandbox has always documented. The confined profile
+  mounts an empty tmpfs over `/mnt`, so the Windows drive's files cannot be
+  read or exfiltrated by a "sandboxed" command and its executables cannot be
+  launched through interop (the path by which such a command reaches your full
+  Windows token). Honest limits, stated wherever the key is: binfmt interop
+  dispatches on file content, so a command that can write the workspace can
+  still write an executable there and run it — enforcement stays `partial`,
+  the result's sandbox fact now carries `windowsDrive: "masked" | "visible"`
+  so the model can see which posture it runs under, and the only complete
+  closure is distro-level (`[interop] enabled=false` in `wsl.conf`). Default
+  `false`: the drive stays visible unless you ask for the mask.
+
+## [0.3.0] - 2026-10-03
+
+One theme: the file tools move into the distro. The `substrate: "agent"` I/O
+substrate and its kernel-enforced confined writes land together with the
+enterprise review that hardened them — the watchdog that killed the shared
+agent for a queue it never chose to join, the output captures nothing bounded,
+a root listing that sheared the first character off every child's name, and an
+overwrite guard that stopped at the host.
+
+### Fixed
+
+- **One file carries one version string, whichever op answered.** `stat` and
+  `list` built their versions from different producers: the stat op used the
+  distro's `stat` directives (uutils `stat` rounds timestamps to microseconds)
+  while the list walk used `find -printf` (nanosecond-exact), so the same file
+  yielded two different version strings and a list-derived guard failed
+  against its own stat. `fs_stat` now reads through the same `find -printf`
+  the list walk uses — one producer, one string — and `find -L`'s habit of
+  reporting a dangling link as the link itself is refused the way the `stat`
+  it replaced was, so a dangling link still stats to null like the peer's.
+
+- **An overwrite or edit now re-verifies its version distro-side, one syscall
+  before the rename.** The module header claimed the mutation guard "survives
+  to the write", but the no-replace link guarded only `createIfAbsent`: an
+  overwrite or edit checked the version host-side and then published with an
+  unconditional `mv -f`, so a concurrent writer (an editor save, `git stash`,
+  another session) that landed between the model's stat and the publish was
+  silently clobbered with no `FS_STALE_VERSION`. The `write` op now carries
+  the version the write was based on (a `replaceIfVersion` guard's version,
+  or the stat an edit was read against), and the agent re-verifies it with a
+  fresh stat from the SAME producer `fs_stat` uses — refusing with
+  `FS_STALE_VERSION` ("file changed since it was read", or "file no longer
+  exists") while the concurrent writer's content stays untouched and no
+  staging debris is left behind. The window narrows from a host round trip to
+  kernel-adjacent — the honest wording, here and in the module headers,
+  LIMITATIONS.md and ARCHITECTURE.md, is that only the create case is closed
+  outright.
+
+- **The agent command path now enforces the output budget it always
+  advertised.** `maxOutputBytes` rode the config schema but nothing else: the
+  agent captured a command's whole stdout and stderr and base64ed both into
+  one RES line — multi-gigabyte output meant multi-gigabyte dash command
+  substitutions in the distro and a multi-gigabyte host line, with the result
+  claiming `truncated: false` all the way. The EXEC frame now carries the
+  caller's per-stream budget (`wsl-shell`'s `maxOutputBytes`, wired from the
+  agent execution path); the agent cuts each stream at it — only the first
+  bytes are encoded, so distro AND host memory are bounded — and the RES line
+  reports which streams were cut, which the handle surfaces as honest
+  per-stream `truncated` flags (a guarded-create synthesis and frames without
+  a budget still read `false`). The host also defends itself against a broken
+  or hostile agent: the unbounded readline accumulator is replaced with a
+  bounded line splitter that kills the transport when one stdout line exceeds
+  the protocol cap instead of buffering it whole.
+
+- **A short-budget request queued behind a long one no longer kills the shared
+  agent — and an in-flight command is never silently re-run.** Two defects
+  shared one root: the host armed each request's watchdog at SUBMISSION and
+  let it kill the one `wsl.exe` carrying every pending request, and the
+  rebuild relay then replayed all carried frames verbatim. In the default
+  configuration the 10 s `DSH_WSL_PORTS` poller (8 s budget, shared agent) did
+  exactly this against any command longer than ~21 s: the poll's watchdog
+  killed the transport, the command died mid-flight, and the rebuild
+  **re-executed it from scratch** — both callers seeing success (measured: a
+  killed `sleep 40` ran twice). Three changes close it: the agent answers
+  `ACK|<id>` when it dequeues a request and the host arms the watchdog there,
+  so queue time never spends a budget (wire protocol v3 — sync the runtime
+  copy and restart the app, an old agent fails the handshake loudly instead of
+  misbehaving quietly); the rebuild relays only provably read-only FS frames
+  (`stat`/`lstat`/`list`/`realpath`/`read`), failing an in-flight EXEC or
+  `write` with "its state is unknown — inspect the distro before retrying"
+  instead of re-running it; and an abort now addresses the request's CURRENT
+  id, so a relayed request's KILL (and map cleanup) can no longer miss. The
+  watchdog-vs-queue experiment now ends with the long command executed exactly
+  once and the transport alive.
+- **A root listing kept every child's name whole.** `listChildren` sliced each
+  `find` record at `parent.length + 1`, which against the bare `/` parent
+  sheared the first character off every name (`/etc` → `tc`), and a write to a
+  listed child then created `/tc`. The exact prefix is stripped instead, and
+  the child join owes its own slash, so `listDir` on
+  `\\wsl.localhost\<distro>\` names `/etc`, `/home`, `/usr` correctly.
+
+### Added
+
+- **`substrate: "agent"` — the filesystem's in-distro I/O substrate.** `wsl-fs`
+  gains a `substrate` key, default `agent`: the file tools are served through
+  the resident in-distro agent instead of the 9p share — identities are
+  distro-side `realpath`s, symlinks resolve where they live (no retry
+  machinery, `/etc/os-release` just works), mode bits are native, and a
+  mutation guard survives to the write's no-replace publication — the
+  check-then-write window the share documents closes, exactly as on a Linux
+  host. `substrate: "share"` is the opt-out that keeps the previous behaviour
+  byte for byte. Both substrates fence writes with the same host-side policy
+  check, so this changes fidelity and posture, not enforcement. Known
+  differences are in LIMITATIONS.md (notably: new files publish at 0600, the
+  peer's own POSIX semantics, where the share took the umask 0644), and an
+  agent outage fails with `FS_IO_ERROR` naming the substrate rather than
+  degrading to share semantics. Layers: FS operation frames on the agent wire
+  protocol (v3, `agent/wsl-agent.sh`), fsio-over-agent mechanics
+  (`lib/fsio-agent.js`), provider-shaped orchestration (`lib/fs-substrate.js`),
+  and the provider branch (`lib/index.js`). The pure text mechanics are
+  replicated from upstream pending the fsio export proposed in
+  docs/UPSTREAM-FSIO-EXPORT.md. Probed live: `npm run probe:substrate`.
+- **Stage two: kernel-enforced confined writes.** On the agent substrate, a
+  mutation under a confined policy rides its own long-lived resident — one
+  agent per (distro, mode, workspace), spawned inside the bwrap profile that
+  binds exactly what the mode grants (`lib/agent-confined.js`, `argvPrefix` on
+  the agent wire). The kernel now refuses what the host-side check would have,
+  so a check bug cannot become a write outside the workspace; a mount-table
+  refusal surfaces as `FS_SANDBOX_DENIED`, the command path's dialect, and a
+  distro without usable bwrap refuses confined writes with the bootstrap
+  command instead of downgrading. Escalated (`danger-full-access`) writes ride
+  the plain resident, and a policy change simply addresses a different key —
+  the previous resident retires through its idle timer. Probed live: the
+  confined write inside the workspace lands, and the one outside it is refused
+  by the kernel (`probe:substrate`).
+
+### Fixed
+
+- **Every mutation on the agent substrate failed: the confined resident's command
+  had no program** — `confinedAgent()` built the resident's `argvPrefix` from the
+  raw profile arguments, so the transport handed `wsl.exe` a command beginning at
+  `--ro-bind` instead of `bwrap --ro-bind`. The resident exited 1 during its
+  handshake, and every write, edit and guarded create on `substrate: "agent"`
+  failed with `FS_IO_ERROR: the distro file substrate is unavailable: agent exited
+  during handshake (code=1 signal=none)` while reads kept working. Both confinement
+  sites now assemble the command through the import-free `lib/bwrap.js`, which is
+  what `test/agent.test.mjs` asserts; the same bug stayed invisible because
+  `test/probe/substrate.sh` inlined a *third*, correct copy of those arguments —
+  it now imports the production builder, so the probe fails with the provider.
+- **`WslFileSystem` could not build its agent substrate at all: a constructor
+  field shadowed the method of the same name** — the constructor's
+  `this.agentSubstrate = undefined` (the cache) overwrote the prototype's
+  `async agentSubstrate()` (the accessor), so the first file operation that needed
+  the agent threw `this.agentSubstrate is not a function`, which is how a GUI
+  session failed its turn in the Desktop app. The cache is now
+  `this.agentSubstrateInstance`, named after the sibling `this.agentInstance`, and
+  `lib/index.js`'s instance fields no longer collide with any class member.
+- **A schemastery member the pinned peer does not publish took the `wsl` preset
+  down in the Desktop app** — `WslFileSystem.Config` declared
+  `substrate: z.enum(["share", "agent"])`, and `@deepseek-ai/schemastery` 3.18.4
+  (what every `@deepseek-ai/dsh-*` peer pins as `~3.18.4`) publishes no `enum`. A
+  Config schema is a class field, so the call ran while `lib/index.js` was still
+  being imported: the loader logs the `TypeError` and leaves that row with no
+  fiber, which the preset audit renders as `never started` — naming neither the
+  member nor the file, and only for `wsl-shell` and `wsl-fs`, the two rows that
+  load `lib/index.js`. The preset therefore failed to activate, so the app
+  reported `2 row(s) did not activate` for those two ids. Now
+  `z.union(["share", "agent"])`: same `agent` default, and a bad value still
+  fails with `expected "share" | "agent" but got "bogus"`. Measured against the
+  app's own runtime, both entries import; `test/syntax.mjs` now checks every
+  `z.<member>` in `lib/` against the pinned peer's surface, which fails on
+  `z.enum` and passes on `z.union`.
+- **`truncated` missing from the agent path's output streams** — the bash tool's
+  canonical result copies the field unconditionally (`canonicalBashResult`), so an
+  `undefined` failed the wire's lossless-JSON snapshot and EVERY shell tool call
+  returned "tool bash returned invalid output: value is not lossless JSON". The
+  agent path now always reports `truncated: false` (it never truncates; there are
+  no spill files). Regression assertion in `test/agent-exec.test.mjs`.
+- **The agent execution path failed every shell call whose request carried an
+  absolute UNC workdir** — which is every call a GUI session makes, so the
+  harness's own agent session lost its bash tool until the fix. The one-shot
+  path converts the spec's workdir inside `argv()` (`toLinuxPath`); the agent
+  path carried the workdir as a raw frame field, so the raw UNC reached the
+  in-distro `chdir`, the synthesized relay text fired `throwIfWorkdirMissing`,
+  and the call died with "could not enter the working directory". The conversion
+  now happens at the call site (regression test in `test/shell.test.mjs`).
+
+### Added
+
+- **Phase 5: per-session terminal routing.** `spawnTerminal` now routes on the
+  request's directory coordinates (`lib/terminal-route.js`, `subprocess-wsl.hostSessions`,
+  default on): a WSL-folder session gets the distro shell, a Windows-folder session gets
+  a host `powershell.exe` in its own directory — no more distro terminal at
+  `/mnt/<drive>/…` for host sessions. The shell menu stays the single configured profile,
+  and every non-`wsl.exe` consumer is untouched. Still limited (LIMITATIONS.md): the
+  shell menu is one entry, and directory-less launches land in the distro.
+- **Phase 7: developer-loop recipes.** Both READMEs gain a Recipes section: Git
+  credential sharing through the Windows Credential Manager, `/mnt/c` 9p
+  performance guidance, and the `WSLENV` passthrough policy (prefix-admitted
+  `DSH_*`, `/p` translation, `PATH` deliberately excluded).
+- **Phase 6: listening-port visibility.** `DSH_WSL_PORTS` joins the managed
+  `DSH_*` facts: the ports with a listener inside the distro, comma-separated,
+  refreshed every `portsRefreshMs` (default 10s) through the resident agent by
+  reading `/proc/net/tcp{,6}` directly — no `ss`, nothing to install. The
+  registry's resolve is synchronous by contract, so the snapshot is served
+  stale-but-recent; a dev server started moments ago appears on the next
+  refresh. Scoped as before: only sessions whose workspace is inside a distro
+  see it. Probed live: a real HTTP server appears in the next snapshot.
+- **Phase 4: bootstrap.** `npm run bootstrap -- [distro] [--install]` checks the
+  distro for bubblewrap (required) plus ripgrep and inotifywait (the optional
+  backends later phases prefer), prints the exact copy-paste install command for
+  the distro's package family (apt/dnf/pacman/zypper), and with `--install` runs
+  it as the distro's root through `wsl.exe -u root` — no sudo prompt inside the
+  distro, nothing touches the Windows side. The `SANDBOX_UNAVAILABLE` message now
+  names the same command instead of a bare `sudo apt install`. Probed live:
+  detect mode on a distro that already has bubblewrap.
+- **Phase 3: shell execution through the agent.** `WslShellExecutor` now runs commands
+  over the resident agent when it is up (`wsl-shell.agent`, default on): one long-lived
+  in-distro process instead of a `wsl.exe` per command, with the timeout enforced
+  INSIDE the distro (TERM, then KILL after the grace) instead of against the Windows
+  process tree. The confinement argv, the execution-handle shape, the result
+  decoration (runner failures, denials, `enforcement: partial`) and the workdir
+  failure are all identical to the one-shot path — an out-of-service agent falls back
+  to it per call, permanently after the agent's rebuild budget. Probed end-to-end:
+  `npm run probe:exec` (confined completion, verbatim shell parsing, in-distro
+  timeout, relay-shaped cwd failure, kill). Documented deviation: the agent path has
+  no live output streaming — reads after settlement carry the whole stream, and no
+  spill files (the protocol line already holds it in memory).
+- **Phase 2 (second half, first slice): in-distro publication through the agent.**
+  `WslFileSystem` now carries an optional resident agent (`wsl-fs.agent`, default on):
+  when available, publication — the replaced file's mode copied onto the staged temp,
+  then the atomic rename — is ONE `exec` inside the distro (`lib/fs-publish.js`)
+  instead of a `wsl.exe` chmod plus a 9p rename. Any agent failure falls back to the
+  legacy two-step path for that call; the flag changes round trips, never what is
+  published. Probed: the publication script's mode preservation and creation
+  behaviour run in `test/probe/agent.sh` (now 10 checks).
+- **Phase 2 (first half): real `watch()`.** `WslFileSystem.watch` now observes from
+  inside the distro — a long-lived `wsl.exe` `find -newer` poll loop (`lib/watcher.js`)
+  firing the seam's coarse invalidation callback — instead of refusing with
+  `FS_IO_ERROR`. Activates on a READY barrier from the loop (a write racing the first
+  tick is never invisible), sees creations and deletions (both bump the parent's
+  mtime), and cleans up on close. Documented blind spot: files created with an
+  mtime older than the stamp (`cp -p`, `tar -x`). Probed end-to-end:
+  `npm run probe:watch`. The native-ext4 migration of the remaining fs operations
+  stays with Phase 3 of the plan.
+- **Phase 1 of the Remote-WSL parity plan (`docs/PARITY.md`): the resident in-distro
+  agent.** `agent/wsl-agent.sh` is a dependency-free POSIX shell peer spawned once per
+  distro; `lib/agent.js` owns the lifecycle (handshake, lazy start, idle shutdown, one
+  rebuild, permanent fallback to the shipped one-shot `wsl.exe` path) and
+  `lib/agent-protocol.js` the line protocol (base64 payloads, NUL-safe argv). Not wired
+  into the seams yet — the executor and filesystem migrations are the next phases.
+  Probed end-to-end against a real distro: `test/probe/agent.sh` (8 checks, including
+  binary-safe payloads, an in-distro timeout kill, and a 2 MB single-line response).
+  Unit tests cover the codecs and the lifecycle state machine with a fake transport.
+
+### Added
+
+- `docs/PARITY.md`: the plan to reach VS Code Remote-WSL-grade experience — a resident
+  in-distro agent as the core, with the `fs` and `shell` seams migrated onto it and the
+  current 9p/one-shot paths kept as the documented fallback — plus the Phase-0 contract
+  audit that shaped it (watch is a coarse invalidation callback; search spawns the
+  packaged ripgrep through `ctx.subprocess`, so the interception point is the
+  `subprocess-wsl` subclass).
+
+### Changed
+
+- The package description is rewritten in Chinese to state what the plugin does first —
+  it makes a WSL distro the session's execution environment — then covers the execution,
+  UI, and sandbox aspects in one clause each.
+- Chinese text now says “WSL 子系统” instead of “WSL 发行版”, the phrasing Chinese readers
+  more commonly use for a WSL distro (`docs/README.zh.md` and the two archived Chinese
+  documents; 99 occurrences).
+
 ## [0.1.10] - 2026-10-02
 
 Metadata and one documentation addition. No behaviour change.

package/README.md

@@ -28,7 +28,7 @@ Step 3 should print a layer named `# == dsh-plugin-wsl-env`, and `- id: terminal
 
 Then open a folder under `\\wsl.localhost\<distro>\...` in the GUI. The picker lists every installed distro at its root level, and **New terminal** opens a shell in the distro.
 
-You also need **bubblewrap inside the distro**: `sudo apt install bubblewrap`. Without it every command fails closed, see [Sandbox](#sandbox).
+You also need **bubblewrap inside the distro**: run `npm run bootstrap -- <distro> --install` (drop `--install` for a read-only check), or paste `wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap`. Without it every command fails closed, see [Sandbox](#sandbox).
 
 Uninstall: `dsh plugin --profile wsl remove dsh-plugin-wsl-env`. Upgrade: run the same `add` command again.
 
@@ -56,6 +56,7 @@ Override a row by id in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. The keys w
 | `wsl-fs` | `distro` | `''` | as above |
 | | `restrictToDistro` | `true` | refuse a path in **another distro**'s share; `/mnt/c` is inside this distro and is not affected. Refused with `FS_OUTSIDE_DISTRO`, which is not a sandbox denial and cannot be lifted by wider permissions |
 | | `sandbox` | `true` | check `writeText` and `editText` against the policy |
+| | `substrate` | `agent` | which I/O substrate serves the file tools: `agent` — the resident in-distro agent, where reads, writes and identities run on ext4 (native symlinks and mode bits; the write guard survives to publication, kernel-enforced under a confined policy); `share` — the opt-out: the Windows-side host stack over the 9p share. Both fence writes with the same policy; see [LIMITATIONS.md](docs/LIMITATIONS.md) for what changes |
 | `directory-picker-wsl` | `includeHostHome` | `true` | also list the Windows home directory |
 | `subprocess-wsl` | `distro` | `''` | which distro the GUI terminal opens in |
 
@@ -77,11 +78,28 @@ Commands are confined by `bubblewrap` inside the distro, and file writes are che
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [docs/LIMITATIONS.md](docs/LIMITATIONS.md) for everything the plugin does not do.
 
+## Recipes
+
+- **Git credential sharing**: let git inside the distro use the Windows-side Git
+  Credential Manager — `git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"`
+  (adjust the path to your Windows Git install; WSL2's localhost forwarding is
+  platform behaviour, so ports a dev server listens on inside the distro are
+  reachable from Windows directly).
+- **Paths and performance**: the model sees and operates on Linux paths
+  (`/home/...`) on the distro's own ext4. `/mnt/c` reaches the Windows disk over
+  9p — noticeably slow for many small files; keep heavy-IO projects on the
+  distro filesystem. `npm run bootstrap -- <distro>` also reports whether
+  ripgrep and inotifywait (the search and watch backends) are in place.
+- **WSLENV passthrough**: WSL imports only the variables listed in `WSLENV`.
+  This plugin admits the managed `DSH_*` namespace by prefix, translating the
+  two Windows-path ones (`DSH_HOME`, `DSH_PROFILE_DIR`) with `/p`. `PATH` is
+  deliberately never forwarded — it would shadow the distro's own PATH.
+
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| every command reports `SANDBOX_UNAVAILABLE` | `bubblewrap` is not installed in the distro | run `sudo apt install bubblewrap`, or set `sandbox: false` on both providers |
+| every command reports `SANDBOX_UNAVAILABLE` | `bubblewrap` is not installed in the distro | run `npm run bootstrap -- <distro> --install`, or set `sandbox: false` on both providers |
 | a command or write is refused outside the session folder | expected behaviour of `workspace-write` | accept the wider-permission offer, or open a session on the folder you need |
 | writes are refused even inside the workspace | the session is in `read-only` mode | switch the Permissions selector |
 | `dsh plugin add` warns that no layer was activated | the dependency was already installed, so `add` had nothing to record | run `dsh plugin --profile wsl remove dsh-plugin-wsl-env`, then add it again |
@@ -101,6 +119,7 @@ npm run probe:sandbox        # measure inside the distro what bubblewrap does an
 npm run probe                # filesystem probe against a real distro (Windows + WSL only)
 npm run probe:sandbox-shell  # boot a real harness and drive the confined executor
 npm run probe:terminal       # open a PTY through the terminal provider
+npm run probe:substrate      # drive the agent filesystem substrate over a real wsl.exe transport (from inside the distro)
 npm run probe:missing-wsl    # boot a profile whose wslPath cannot start (Windows + WSL only)
 npm run probe:picker         # list the picker's root level, refusals and its cap (Windows + WSL only)
 npm run probe:mode           # which POSIX-mode facts survive the share (Windows node only)