dsh-plugin-wsl-env 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -16,6 +16,187 @@ were part of the record.
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-10-19
+
+This release ships the P0/P1 hardening batch: session-scoped `auto`
+sandboxing, resident-agent recovery with doctor coverage, the packed-install
+E2E, measured GUI-preview and `@`-reference probes, and the docs/community
+entry points.
+
+### Added
+
+- **`pnpm run preset` — the `preset-wsl` override helper.** `wsl-shell` and
+  `wsl-fs` sit inside `preset-wsl`'s `config.plugins`, so a patch that targets
+  them by id is ignored with only a loader warning. The helper prints the
+  complete `preset-wsl` block, applies `distro`/`sessionSandbox`/`sandbox`/
+  `maskWindowsDrive`/`agentBackend`, and `--check` fails loudly with the exact
+  block to paste when a layer carries the nested id patch. See
+  [docs/CONFIGURATION.md](docs/CONFIGURATION.md#overriding-the-rows-inside-preset-wsl).
+
+- **Session-notice upstream payload ready.** The exact title, body and `gh`
+  command for the session-visible notice proposal are in
+  `docs/upstream/proposal-session-notice.md`; it remains unfiled (a maintainer
+  action).
+
+- **Configuration stability and migration policy.** `docs/MIGRATION.md` records
+  the below-1.0 freeze (new keys preserve behavior, removals refuse at boot with
+  a migration, meaning changes get a note), the deprecation path with the
+  `substrate: "share"` and `distro: ''` cases, and the release-gate table with
+  the manual legs (probe suite, clean machine, aarch64) marked unrun.
+  RELEASING and SUPPORT link it.
+
+- **Upstream promotion pack documented.** `docs/upstream/promotion-pack.md`
+  records the `packages/wsl/*` layout (ten capability packages plus an
+  integration package), the seam/RFC index, what the composition boot test
+  covers and its gaps, and the install proof. Promotion stays packaging and
+  proof, not a dependency.
+
+- **`@`-reference traversal cost measured; seam deferred.** The Windows walk
+  over the WSL share is ~56× the ext4 walk on a 520-entry tree (84.7 ms vs
+  1.5 ms) and is now reproducible with `pnpm run probe:file-reference`.
+  `docs/UPSTREAM-FILE-REFERENCE-SEAM.md` records the three-function seam, the
+  ready (unwired) plugin consumer, and the decision to keep the 9p walk until
+  upstream exposes the funnel.
+
+- **Community loop: issue forms, triage targets and a contributor path.**
+  Feature-request and setup-report forms (the setup form requires
+  `doctor --json`), a chooser that disables blank issues, SUPPORT's P1
+  three-business-day target and two-to-four-week cadence, and a
+  `good first issue` path in CONTRIBUTING.
+
+- **Quickstart and performance entry pages.** `docs/QUICKSTART.md` is the
+  five-minute path (prerequisites, install, first session, Node/Python/Rust/Go
+  and monorepo recipes, honest Tier 1/Tier 2 table); `docs/PERFORMANCE.md`
+  records the 9p-vs-agent numbers and the GUI-preview baseline with reproduction
+  commands. The visual demo is explicitly still missing.
+
+- **GUI-preview latency has a measured baseline.** `pnpm run probe:gui-preview`
+  drives the routed backend's `stat`, `listDir` and 1 MiB `readByteRange` with
+  p50/p95 budgets (stat 100 ms, listing 500 ms, page 1 s/MiB). On this machine:
+  p95 2.7 ms / 5.1 ms / 63.5 ms per MiB. No optimization follows; the
+  `workspace-files` row is untouched.
+
+- **LSP seam researched and deferred.** `docs/UPSTREAM-LSP-SEAM.md` records that
+  the harness ships `dsh-lsp`/`dsh-lsp-stdio`/`dsh-tool-lsp` but the 0.2.1-rc.2
+  base composition mounts none of them, and that a WSL provider needs a
+  preset-scoped subprocess provider plus URI translation. The prototype is
+  deferred behind an explicit trigger; no LSP claim is made in the README.
+
+- **Peer-upgrade canary.** A weekly workflow resolves the `next` dist-tag of
+  every pinned peer, tests that line in a scratch copy (`pnpm test` + the
+  composition boot test), and publishes the exact version delta in the run
+  summary; a moved line that fails fails the run. `pnpm run canary:peers`
+  performs the check locally.
+
+- **The strict profile is documented and probed.** `maskWindowsDrive: true` with
+  `sandbox: true` hides `/mnt` from confined profiles; CONFIGURATION describes
+  the trade-offs and the visible/masked/disabled interop matrix, and
+  `probe:sandbox` now asserts the masked leg (empty `/mnt`, unreachable Windows
+  binary, writable workspace). Enforcement stays `partial`; the binfmt content
+  escape and the distro-level closure are stated.
+
+- **Install/upgrade/uninstall E2E.** `pnpm run e2e:install` packs the tree,
+  installs it into a fresh `%TEMP%` `DSH_HOME`, composes `--dump-config`, removes
+  it, and upgrades from the previous minor with a marker proving the profile
+  layer survived. `test/packaging.test.mjs` keeps the packed file list honest in
+  `pnpm test`.
+
+- **The doctor probes the resident agent.** `agent.handshake` starts the
+  shipped shell agent in the distro, reads its HELLO (pid, protocol, script
+  digest) and stops it, so a missing or stale agent script is a named check
+  instead of a first-command failure. It also reports the agent cache and the
+  live/stale `dsh-wsl-*.scope` counts.
+
+- **`pnpm run doctor` — one command for the environment prerequisites.** Reports
+  Windows/WSL versions, the distro and its login shell, bubblewrap usability,
+  systemd / the user manager / `systemd-run` / Linger, the optional tools, peer
+  versions, the native-agent cache, stale `dsh-wsl-*.scope` units and the
+  profile-patch trap that silently ignores `wsl-shell`/`wsl-fs` overrides. Each
+  failure carries one copy-paste remedy; `--json` is the machine shape, and
+  `--fix` only sweeps stale scopes unless `--install` plus a confirmation allows
+  a package install. `diagnose` is now the read-only alias.
+
+### Changed
+
+- **`sessionSandbox: auto` — the session runtime is an optimization, not a
+  prerequisite.** `wsl-shell` and `wsl-fs` accept `true`, `false` or `"auto"`;
+  `auto` uses the systemd user scope when it is available and otherwise falls
+  back to the per-command `bwrap` profile — still confined, never unconfined —
+  reporting `sessionScope: "session" | "per-command"` in the command result.
+  A failed verdict is re-probed at most once a minute, so installing systemd or
+  enabling Linger upgrades without an app restart. `true` keeps refusing with
+  the existing remedy; `false` is unchanged.
+
+- **The session preflight also checks the session-runtime prerequisites.** It
+  now probes systemd as PID 1, the user manager, `systemd-run` and Linger —
+  not only `bubblewrap` — when a distro session opens, and publishes the same
+  advisory to the session's runtime context as well as the log. `sessionSandbox:
+  false` on the `wsl-preflight` row skips the session half. DSH 0.2.1 has no
+  session-notice seam; the ask is recorded in
+  [docs/UPSTREAM-SESSION-NOTICE.md](docs/UPSTREAM-SESSION-NOTICE.md) and the
+  boundary in [docs/LIMITATIONS.md](docs/LIMITATIONS.md#session-start-advisories).
+  Advisory only: nothing is installed and fail-closed behavior is unchanged.
+
+- **The distro follows the workspace.** `distro: ''`/`'auto'` now selects the
+  distro from the request workdir or target UNC; `'default'` forces WSL's
+  default, and an explicit name still pins. Shell, files, root-plane routing,
+  the GUI terminal and `shell-env` all use the same rule, and the shared agent,
+  substrate, home and session-runtime state are cached per distro. A pinned
+  profile still refuses a foreign UNC with `FS_OUTSIDE_DISTRO`. This changes the
+  previous meaning of `distro: ''` (WSL's default): set `'default'` to keep that
+  posture.
+
+### Fixed
+
+- **A dead resident revives with bounded backoff instead of staying dead for
+  the process lifetime.** A failure that spends the one permitted rebuild now
+  leaves the agent `dead` with a revival scheduled (2 s, 4 s, 8 s); the next
+  call after the delay gets a fresh transport and its own single rebuild, and
+  nothing from the dead generation is replayed. After three deaths the state is
+  permanent and the refusal names the restart remedy. `status()` exposes the
+  live state, pid, last error and pending count for diagnostics.
+
+- **A cancelled command's signal can no longer kill the next one.** The
+  out-of-band USR1 carries no request id: a signal meant for a timed-out
+  command could land after the agent had moved on, and the next command then
+  died with exit 138 but reported `completed`. A host timeout no longer sends
+  the signal at all (the in-distro watcher is the one that kills that
+  command), and an explicit cancel now waits briefly and is dropped once the
+  request answered or a newer request is running.
+
+- **A missing workdir is reported with its path on the native agent.** The
+  native agent reports the failed spawn as reason `spawn`, without naming the
+  directory; the executor now treats that as its own error class and retries
+  the command on the one-shot path, whose `chdir(<path>) failed` warning names
+  the directory.
+
+## [0.12.0] - 2026-10-19
+
+The GUI file service keeps the shipped `workspace-files` row: its server-only
+replacement dropped the browser `file` resource provider and broke Sidebar
+previews. The shipped row now serves WSL paths through `fs-routing`. The
+`wsl-shell.maskWindowsDrive` wiring fix ships with it.
+
+### Fixed
+
+- **`wsl-shell.maskWindowsDrive` reaches the per-command sandbox.** The shell
+  executor built its `WslSandbox` without the configured key. With
+  `sessionSandbox: false` the per-command profile therefore left `/mnt`
+  visible after the operator asked for the mask; with `sessionSandbox: true`
+  the runtime still masked the drive, but the decorated result reported
+  `windowsDrive: "visible"`. The executor now passes the value, matching
+  `wsl-fs` and `fs-routing`.
+
+- **Sidebar previews work: the GUI file service keeps the shipped
+  `workspace-files` row.** The former `workspace-files-wsl` takeover replaced
+  that row with a server-only subclass, which dropped the browser `file`
+  resource provider and made every Sidebar preview report "The file resource
+  service is unavailable." The shipped row now serves WSL paths through
+  `fs-routing`, so the server and client halves stay paired. The trade-off is
+  GUI-only: a listing, `stat` or page read takes roughly four to six agent round
+  trips instead of one, and a deep page read streams the preceding lines through
+  the pipe. The model's file tools, search and `@` references are unaffected.
+
 ## [0.11.0] - 2026-10-18
 
 The shared read agent is the native binary (A7): unconfined reads now use the

package/CONTRIBUTING.md

@@ -172,11 +172,14 @@ terminal if you would rather not see the prompt.
 
 | Command | Covers | Needs a harness |
 |---|---|---|
-| `pnpm test` | style checks, syntax pass, build consistency, type check, and unit tests | no |
+| `pnpm test` | style checks, relative links, syntax pass, build consistency, type check, and unit tests | no |
+| `pnpm run lint:links` | relative Markdown links in README, CONTRIBUTING, AGENTS and `docs/**` | no |
 | `pnpm run test:coverage` | unit tests with coverage | no |
 | `pnpm run lint:style` | style and lint rules | no |
 | `pnpm run lint:build` | the build-freshness check: every source has its artifacts and the committed bytes match a real build | no |
 | `pnpm run lint:types` | the TypeScript check over `test/**` and the ambient types (`tsc --noEmit`) | no |
+| `pnpm run e2e:install` | packed-tarball install/upgrade/uninstall into a temporary `DSH_HOME` | yes; Windows + WSL |
+| `pnpm run doctor` | the environment prerequisites, peers and caches (`--json` for scripts; `diagnose` is the read-only alias) | no; inside the distro |
 | `pnpm run probe` | filesystem behaviour against a real distro | yes |
 | `pnpm run probe:sandbox` | what bubblewrap confines and what it does not | no |
 | `pnpm run probe:sandbox-shell` | the confined executor through a real boot | yes |
@@ -187,11 +190,14 @@ terminal if you would rather not see the prompt.
 | `pnpm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | no; inside the distro |
 | `pnpm run probe:missing-wsl` | how a `wslPath` that cannot start is reported | yes |
 | `pnpm run probe:picker` | the picker's root level, its refusals and its cap | yes |
+| `pnpm run probe:gui-preview` | the routed backend's stat/listing/1 MiB page-read latency (p50/p95 budgets) | no; inside the distro |
+| `pnpm run probe:file-reference` | the `@`-reference traversal: 9p walk vs the distro's ext4 | no; inside the distro |
+| `pnpm run probe:fs-routing` | the root-plane router: distro coordinate, host plane, cross-distro fence | yes |
 | `pnpm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node |
 | `pnpm run probe:sandbox-off` | the documented opt-out on both providers | yes |
 
 Every script above is wired in `package.json`. `pnpm test` runs `lint:style`,
-`test:syntax`, `lint:build`, `lint:types` and `test:unit` in that order.
+`lint:links`, `test:syntax`, `lint:build`, `lint:types` and `test:unit` in that order.
 `prepublishOnly` runs `pnpm test` again at publish time, so a broken gate stops a
 release before the upload.
 
@@ -253,10 +259,10 @@ must skip itself — print a `SKIP` line and exit 0 — the way that file does o
 
 Probes are shell scripts, plus the small plugin files they load: the `*-probe.mjs`
 and `*-probe.yml` files in the same directory. Two shapes. The harness probes
-(`run.sh`, `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `missing-wsl.sh`,
-`sandbox-off.sh`) boot a throwaway profile whose setup steps are in the header of
-`test/probe/run.sh`; the five others reuse the profile `run.sh` creates rather
-than making their own. The distro probes (`substrate.sh`, `watch.sh`, `agent.sh`,
+(`run.sh`, `terminal.sh`, `sandbox-shell.sh`, `picker.sh`, `fs-routing.sh`,
+`missing-wsl.sh`, `sandbox-off.sh`) boot a throwaway profile whose setup steps
+are in the header of `test/probe/run.sh`; the six others reuse the profile
+`run.sh` creates rather than making their own. The distro probes (`substrate.sh`, `watch.sh`, `agent.sh`,
 `exec.sh`) boot nothing: they run from a distro terminal and drive the resident
 agent through the `wsl.exe` interop transport. `sandbox.sh` and `mode.sh` sit
 outside both groups — no harness boot, no profile.
@@ -304,13 +310,29 @@ On Windows 11 + WSL2 (Ubuntu 26.04) the following has been verified:
   outside the session workspace is refused inside the distro and the following
   wider-permission request succeeds.
 
-Counts: 28 unit test files under `test/` — 27 of them registered in the
+Counts: 33 unit test files under `test/` — 32 of them registered in the
 `test:unit` list, see the OI-7 note above — which need the pinned packages
 installed, and over 1000 `assert` call sites across them; 19 filesystem-probe
 assertions; 15 shell-probe checks; 9 picker checks; 6 missing-executable checks;
 5 mode checks; 5 opt-out checks and 10 sandbox expectations plus the recorded
 escape; and 3 terminal assertions.
 
+## Good first issues and the contributor path
+
+The repository labels self-contained changes `good first issue`. Typical shapes:
+
+- a recipe or troubleshooting row in `README.md` or `docs/QUICKSTART.md`
+  (the link check gates it; one commit);
+- a probe report fixture under `test/probe/` that follows an existing
+  `*-report.txt` shape;
+- an issue-template wording fix, a cross-reference, or a missing error-code row
+  in `docs/ARCHITECTURE.md`.
+
+To claim one, comment on the issue. Before opening a PR run `pnpm test` (and
+`pnpm run test:coverage` for a `lib/` change), then make one logical commit whose
+body records the check results — the conventions below. Probes need a real
+Windows + WSL machine; unit tests, docs and packaging changes do not.
+
 ## Commit and pull request conventions
 
 - Write an imperative subject line: `Fix the npm readme`, not `Fixed` or `Fixes`.