dsh-wsl-desktop 0.3.1 → 0.3.3
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.
- package/README.en.md +56 -183
- package/README.md +54 -344
- package/lib/wsl/confinement.js +23 -7
- package/lib/wsl/fence.js +3 -3
- package/lib/wsl/preset.js +1 -1
- package/lib/wsl/subprocess.js +59 -6
- package/lib/wsl/world.js +90 -8
- package/package.json +1 -1
package/README.en.md
CHANGED
|
@@ -2,147 +2,101 @@
|
|
|
2
2
|
|
|
3
3
|
English | [简体中文](README.md)
|
|
4
4
|
|
|
5
|
+
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.
|
|
6
|
+
|
|
5
7
|
> **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.
|
|
6
8
|
>
|
|
7
9
|
> **Scope boundaries**:
|
|
8
|
-
> - ✅ **Suitable**: the plugin author themselves or operators of the same trust level, for long-term use on explicitly supported distros (see
|
|
9
|
-
> - ⚠️ **Conditional**: the confined-mode trust boundary depends on NO_NEW_PRIVS (modern debian-family setpriv satisfies it;
|
|
10
|
-
> - ❌ **Not yet suitable**: distribution to third-party users (missing desktop version gating and distro matrix
|
|
10
|
+
> - ✅ **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.
|
|
11
|
+
> - ⚠️ **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)).
|
|
12
|
+
> - ❌ **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)).
|
|
11
13
|
|
|
12
|
-
##
|
|
14
|
+
## Contents
|
|
13
15
|
|
|
14
|
-
|
|
16
|
+
- **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)
|
|
17
|
+
- **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) · [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)
|
|
18
|
+
|
|
19
|
+
> The six documents this restructure created have an English edition (linked above; the file names carry an `.en` marker) and the pair is enforced 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.
|
|
15
20
|
|
|
16
21
|
## Target capabilities
|
|
17
22
|
|
|
18
|
-
**Honest state after live acceptance** (`verify-post-restart.mjs` all green +
|
|
23
|
+
**Honest state after live acceptance** (`verify-post-restart.mjs` all green + 18 offline suites; each item below notes its evidence strength):
|
|
19
24
|
|
|
20
25
|
| # | Capability | Status |
|
|
21
26
|
|---|---|---|
|
|
22
27
|
| ① | 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) |
|
|
23
28
|
| ② | 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 |
|
|
24
29
|
| ③ | 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 |
|
|
25
|
-
| ④ | 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
|
|
26
|
-
|
|
27
|
-
## Session binding: name the execution world in the create request
|
|
30
|
+
| ④ | 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)) |
|
|
28
31
|
|
|
29
|
-
|
|
32
|
+
**Which capabilities are qualified**: the evidence strength is the wording of the status column above. The `grep` / `glob` tools do not exist in a WSL session and the terminal has no `stdio.control` — both are stated under "Known limitations" rather than left out.
|
|
30
33
|
|
|
31
|
-
|
|
34
|
+
## Install / Update / Uninstall
|
|
32
35
|
|
|
33
|
-
|
|
34
|
-
- **That field crosses two API layers, and one of them drops it.** The host's `SessionCreateRequest.agentPreset` is a real contract, but the client service wrapper `ctx.sessions.create` rebuilds its payload from `workspaceId | cwd | sessionId` alone — `agentPreset` is silently discarded, the session lands on the default preset, and only the fallback below rescues it. Creation therefore goes through the **generated remote contract** `ctx.remote.session.create({ workspaceId, agentPreset })` (with `remote` / `remote.session` injected to match), and `ctx.sessions.create` is kept only as the retreat for a host whose remote surface is unavailable. `scripts/verify-client-ui.mjs` pins both halves.
|
|
35
|
-
- The host half keeps an `api-session/added` listener (`bindWslSession` in `lib/index.js`) as a **fallback**: it only handles sessions whose "cwd is a WSL path but the creation carried no preset" (for example, sessions created from another entry point). It attempts a post-hoc `select`; on success it binds retroactively, on failure it writes `bindingLog` and warns in the host log — such entries are now **anomaly signals**, no longer part of the normal path.
|
|
36
|
-
- The binding section of `verify-post-restart.mjs` therefore reads: a non-selftest `bindingLog` entry = someone created a WSL session while bypassing the creation seam; zero entries = every session bound through the create request is fine. Final GUI-side confirmation has been done by the operator (session preset shows WSL · PTC mode; tools execute inside the distro).
|
|
37
|
-
|
|
38
|
-
## UI entry point
|
|
39
|
-
|
|
40
|
-
In the sidebar workspace title bar, to the right of the built-in "+" (add workspace), there is an extra **W** button; clicking it opens this plugin's workspace dialog: pick a distro → enter the user → browse or type a Linux directory → create and open a session.
|
|
36
|
+
**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`).
|
|
41
37
|
|
|
42
|
-
|
|
38
|
+
- 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.
|
|
39
|
+
- CLI equivalent: `plugin_manager install_bundle dsh-wsl-desktop@<version>`.
|
|
40
|
+
- **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)).
|
|
41
|
+
- **Update**: installing a new version number is enough; after a desktop major update, run `verify-post-restart.mjs` first per "Desktop update discipline".
|
|
42
|
+
- **Uninstall**: uninstalling via the plugin manager also withdraws the wsl-* presets registered by this plugin (guaranteed by the disposer lifecycle).
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
> **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**.
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
## Quick start
|
|
47
47
|
|
|
48
|
-
"+"
|
|
48
|
+
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.
|
|
49
49
|
|
|
50
|
-
|
|
51
|
-
- The sidebar title bar has no extension point, so the W button attaches as a companion node right after the "+" button: it locates itself by the SVG path geometry of the "add workspace" icon (language-independent; this icon is rendered in exactly one place in the app) and reuses that button's class to inherit the same size and hover states. The desktop once rebuilt that icon (`IconProjectAddOutline16` → `ProjectAddOutlineArtwork`, geometry completely changed), so the trigger carries a **known list of both old and new geometry generations** and prefix-matches either one — a desktop update will not make W silently disappear. When React replaces that subtree, a MutationObserver re-attaches W.
|
|
52
|
-
- **Hiding must use `display`, never `remove()`.** The observer watches `childList`, and `remove()` is itself the next trigger; the two feed each other at refresh rate (measured: 52 times in 2.6s, each with two forced layouts). When there is no room, set `display: none` — it is not a childList mutation, so it converges.
|
|
53
|
-
- **Never use a timer as a fallback.** A past `setInterval(sync, 2000)` was the seed of exactly this loop; remounts/portals are childList mutations on the observed subtree, and a timer solves no real situation.
|
|
54
|
-
- The companion button only shows while "+" is visible (when inline search expands, it hides together with the official action cluster); when a second control carries the same icon geometry, the one inside the `*_headerActions` cluster wins; when nothing can be recognized, the button stands down entirely rather than guessing.
|
|
50
|
+
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.
|
|
55
51
|
|
|
56
|
-
|
|
52
|
+
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).
|
|
57
53
|
|
|
58
|
-
|
|
54
|
+
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.
|
|
59
55
|
|
|
60
|
-
|
|
61
|
-
data process wsl.exe -e python3 -c <bridge> <fifo> <cols> <rows> <shell…>
|
|
62
|
-
stdin/stdout = terminal bytes stderr = one JSON control reply per line
|
|
63
|
-
control process wsl.exe -e bash -c 'exec 3>"$fifo"; while read -r l; do printf "%s\n" "$l" >&3; done'
|
|
64
|
-
```
|
|
56
|
+
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).
|
|
65
57
|
|
|
66
|
-
|
|
58
|
+
## Desktop update discipline (mandatory)
|
|
67
59
|
|
|
68
|
-
|
|
60
|
+
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.
|
|
69
61
|
|
|
70
|
-
|
|
62
|
+
## Security and trust boundaries
|
|
71
63
|
|
|
72
|
-
- **
|
|
73
|
-
- **
|
|
64
|
+
- **Host side**: Windows workspaces keep running in DSH's own sandbox backends; this plugin does not replace them.
|
|
65
|
+
- **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).
|
|
66
|
+
- **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).
|
|
74
67
|
|
|
75
|
-
|
|
68
|
+
**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).
|
|
76
69
|
|
|
77
|
-
## Known
|
|
70
|
+
## Known limitations
|
|
78
71
|
|
|
79
|
-
`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. So the WSL preset removes it from the execution world, and the model in a WSL session can only use bash's `grep` / `find` (both present in the distro). This is a capability regression, not an omission — making it equivalent would require giving the WSL world its own search implementation.
|
|
72
|
+
**The grep / glob tools do not exist in a WSL session.** `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. So the WSL preset removes it from the execution world, and the model in a WSL session can only use bash's `grep` / `find` (both present in the distro). This is a capability regression, not an omission — making it equivalent would require giving the WSL world its own search implementation.
|
|
80
73
|
|
|
81
|
-
**The
|
|
74
|
+
**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).
|
|
82
75
|
|
|
83
|
-
|
|
76
|
+
**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).
|
|
84
77
|
|
|
85
|
-
|
|
78
|
+
## Verification
|
|
86
79
|
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
ctx.shell = pwsh-sandbox (host) isolate: { shell, fs, subprocess }
|
|
91
|
-
ctx.fs = fs-sandbox (host) ├─ shell-wsl → ctx.shell
|
|
92
|
-
├─ fs-wsl → ctx.fs
|
|
93
|
-
├─ subprocess-wsl → ctx.subprocess
|
|
94
|
-
└─ tool-bash / tool-fs
|
|
80
|
+
```powershell
|
|
81
|
+
node scripts/verify-all.mjs # all offline suites (18)
|
|
82
|
+
node scripts/verify-all.mjs --live # additionally the suites needing the installed plugin + a running host
|
|
95
83
|
```
|
|
96
84
|
|
|
97
|
-
|
|
85
|
+
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).
|
|
98
86
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
## Confinement (Linux side, M2)
|
|
87
|
+
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`.
|
|
102
88
|
|
|
103
|
-
|
|
89
|
+
## Development
|
|
104
90
|
|
|
91
|
+
```bash
|
|
92
|
+
git clone https://github.com/zcluo/dsh-wsl-desktop.git
|
|
93
|
+
cd dsh-wsl-desktop
|
|
94
|
+
node scripts/verify-all.mjs # full offline run
|
|
95
|
+
.\scripts\sync.ps1 # stage into the profile and re-point (developer mode: developerTools enabled; a first install needs the wiring first)
|
|
96
|
+
# restart DSH Desktop → verify-post-restart.mjs
|
|
105
97
|
```
|
|
106
|
-
workspace-write: bind <workspace> → tmpfs /tmp → remount,ro,bind /
|
|
107
|
-
read-only: tmpfs /tmp → remount,ro,bind /
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
The order is load-bearing: **bind the writable paths first, then remount the root read-only**. The other way around, new binds inherit the read-only state (verified: workspace writes fail).
|
|
111
98
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
- **Must be root.** The WSL kernel refuses bind mounts inside a user namespace: `unshare -Ur --mount` starts, but `mount --bind` reports "wrong fs type". So `sudo -n unshare …` is used; without passwordless sudo, confined mode **fails explicitly** (`SandboxUnavailableError`) instead of running bare.
|
|
115
|
-
- **sudo grants retained after dropping privileges are a known boundary of the fence — two closing paths.** The session user keeps the passwordless sudo grant that the runner itself depends on — a confined command can re-invoke it (open a fresh `sudo -n unshare --mount` without the fence script, or run `sudo -n mount -o remount,rw /` inside the fence), thereby bypassing the file fence. Closing paths (by priority):
|
|
116
|
-
1. **Dedicated helper (recommended; installed once, but re-installed after every plugin upgrade)**:
|
|
117
|
-
```bash
|
|
118
|
-
# run as root inside the distro (adjust the path to the actual install location)
|
|
119
|
-
install -m 0755 -o root -g root /mnt/c/Users/<you>/.dsh/profiles/desktop/plugins/dsh-wsl-desktop-*/lib/wsl/dsh-wsl-confine.sh /usr/local/sbin/dsh-wsl-confine
|
|
120
|
-
echo "$USER ALL=(root) NOPASSWD: /usr/local/sbin/dsh-wsl-confine *" > /etc/sudoers.d/dsh-wsl-confine && chmod 0440 /etc/sudoers.d/dsh-wsl-confine
|
|
121
|
-
```
|
|
122
|
-
As root, the helper **always applies the full fence first**, then drops privileges and executes the command — re-invocation just re-fences from an already-fenced context, and parameter games (workspace='/') are defeated by the `/ is not read-only` postcondition. The plugin auto-detects and prefers the helper (the sudoers file authorizes only this one file), but **accepts only the exact version this plugin requires (currently v1.2)**: v1.1 did not escape its exemption pattern, so a workspace path containing a metacharacter was swept read-only and a path containing `|` could make `/mnt/c` an exempt target (leaving the Windows filesystem writable inside a confined session). **Re-run the install above after upgrading the plugin**; a mismatched helper is simply not selected, and the plugin falls back to the direct sudo-unshare runner (whose in-process builder always escaped correctly) rather than silently keeping the old fence. The requirement is an **exact match, not a minimum**, so a future helper version bump must move `HELPER_VERSION` in `confinement.js` with it — `verify-confinement.mjs` pins the two together, so a mismatch goes red.
|
|
123
|
-
|
|
124
|
-
**The helper pins its own PATH and does not depend on sudoers.** As root it calls twelve tools by bare name (getent/cut/sed/tr/mount/findmnt/grep/mountpoint/setpriv/env/bash/unshare); `env_reset` does not save it — `secure_path` replaces only the PATH the caller **exports**, while a PATH passed as a `sudo PATH=… <helper>` command-line assignment still reaches the helper when the policy permits it (measured on debian, debian-dev and arch; whether it is permitted at all is the sudoers `SETENV`/`ALL` decision — this deployment is `NOPASSWD: ALL`, for which sudo implies SETENV — which is exactly why the helper must not rely on it), and the NOPASSWD grant is argument-wildcarded. The identity gate is the worst case: it trusts the getent/cut output resolved through that PATH, so a forged answer satisfied `--uid 0 --gid 0`. The helper therefore pins PATH to `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` and `export`s it, as the **first statement it executes** (before the argument parse and the identity gate); keep your distribution's own `secure_path` as it is — the pin is the helper's own guarantee, not a replacement for it. The pin has **no fallback**: the twelve tools must resolve in those six directories, and if one does not, the helper **fails closed** (a missing getent leaves the caller record empty and the gate refuses it; a missing cut fails the pipeline under pipefail with 127, so the fence is never established; the `command -v` preflights exit 97 with the setup-failure marker). It never falls back to the caller's PATH — a fallback would restore exactly this hole.
|
|
125
|
-
|
|
126
|
-
**The helper drops a caller-supplied BASH_ENV before it starts, and does not import functions from the environment.** bash sources a caller-supplied `BASH_ENV` file BEFORE the script's first line — as root, ahead of every control in the file (the PATH pin included, which is why the pin cannot close it). Measured (bash 5.2.37): `bash script`, a `#!/bin/bash` shebang under exec and `bash -c` all source it, while `bash -p script`, a `#!/bin/bash -p` shebang and `bash -p -c` do not. Three edits follow from that measurement. The shebang is `#!/bin/bash -p`. `-p` does not remove the variable, and every descendant inherits it — the drop-side `bash -lc` is not privileged and does process it (measured: it sourced the caller's file as the session user, inside the fence) — so the exec tail drops it with `env -u BASH_ENV`, one removal on the one invocation every root-phase descendant hangs off. And because `-p` is a property of the SHELL, the fence body — a separate `bash -c` — still imported caller-exported functions: with a coordinated `mount`/`findmnt`/`mountpoint` override the sweep reported a confined system while `/mnt/c` stayed writable (measured: a silent fence bypass; faking `mount()` alone only failed closed at the postcondition by luck), so the fence body is launched with `-p` too, which makes such an override inert. `-p` on the helper's own bash also closes a second forging route that bypasses the PATH pin (measured: a forged `getent()` function made the identity gate accept `--uid 0 --gid 0`, running the command as uid 0 inside the fence; with `-p` the gate refuses it, exit 2). Severity: this is unconfined root code execution before line 1, ahead of the fence — it exceeds the root-inside-the-fence access the PATH pin closes (and root there is not a reader either — see the identity-gate paragraph below) — but its reachability is the sudoers policy's: a strictly NARROW rule does NOT imply SETENV, and an EXPORTED BASH_ENV is stripped by sudo's env_reset (measured), so the route needs the command-line-assignment spelling, which SETENV permits and an ALL match implies. The helper-side fix is unconditional on purpose: it must not depend on the deployment's sudoers either way. `HELPER_VERSION` stays v1.2, so **an un-reinstalled helper is still selected by the probe** — re-run the install above after upgrading the plugin, this time especially.
|
|
127
|
-
|
|
128
|
-
**The identity gate is fail-closed, and it is a boundary only where the deployment's sudoers does not grant SETENV.** The gate judges the caller by SUDO_USER; an empty or unset value used to **skip the check**, and the caller controls that variable: measured, `sudo -n SUDO_USER= <helper> --uid 0 --gid 0 --home /root --cwd / -- '…'` and `sudo -n env -u SUDO_USER` both ran the command as uid 0 inside the fence with `/etc/shadow` readable. An empty or unset SUDO_USER is now **refused** (exit 2; root's own direct invocation passes `SUDO_USER=root` explicitly). The gate cannot stop **forgery**: `sudo SUDO_USER=root <helper> --uid 0 --gid 0 …` is still accepted — the variable is the only identity the gate has, and `SUDO_UID` is forgeable through the same route, so a cross-check buys nothing. The gate is therefore a boundary **only where the sudoers policy does not grant SETENV** (no `ALL` match, no command-line-assignment form); where SETENV is granted it stops unintentional misuse, not forgery, and the fence drops to the **forged uid** — root **write**, not a read primitive: the read-only state is a per-mount bind remount inside the private namespace, so the forged uid 0 can `mount -o remount,rw /` and `mount -o remount,rw /mnt/c` (both measured, and a write lands on each filesystem: a root-only path, and a file created under /mnt/c) and write to the distribution's filesystem and to the Windows filesystem; only the namespace and NO_NEW_PRIVS still apply — the file fence does not.
|
|
129
|
-
2. **NO_NEW_PRIVS (automatic; the mitigation when no helper exists)**: when dropping privileges, the runtime probes for `setpriv --no-new-privs` support (modern debian-family setpriv satisfies it; verified `noNewPrivs: true` active) — setuid escalation inside the fence fails loudly. On old setpriv builds without that flag, this boundary still exists — honestly recorded in the `enforcement: 'partial'` caveats.
|
|
130
|
-
- **The `\xNN` escapes from `findmnt` are decoded.** `findmnt -r` encodes spaces/tabs/newlines/backslashes in TARGET as `\x20` etc. — before the fix, the sweep remounted the literal escaped name (ENOENT swallowed by `|| true`) and the postcondition tested a fake name, so mount points containing spaces stayed writable under read-only mode and exit code 97 never triggered. Both pipelines now decode before matching, with a regression that asserts read-only on a real bind target containing spaces (verify-confinement).
|
|
131
|
-
- **After entering the namespace, drop back to the original user.** Entering via `sudo` leaves euid as root; using it directly would leave root-owned files in the workspace; `setpriv --reuid --regid --init-groups` drops back to the session user (ownership covered by an assertion).
|
|
132
|
-
- **Every probe whose output gets parsed is non-login.** `resolveIdentity` / `detectRunner` / `listLinuxDir` / `checkLinuxPath` / `resolveDistroHome` / `resolveExecutable`, and the pty's python3 probe, all use `loginShell: false` — a login shell's rc prints before the probe command's output, and positional parsing would treat whatever the profile printed as uid/gid/home (with model-writable dotfiles, that equals handing setpriv's uid to an attacker). `resolveIdentity` additionally brackets the output with a `__DSH_IDENTITY__` sentinel line + an exact four-line check; a parse failure throws an error **carrying the probe's actual output** (no more silent null). Probe timeout is 60s + one transparent retry after timeout: the first cold start of wsl.exe after a desktop restart can exceed a short limit.
|
|
133
|
-
- **wsl.exe option values pass syntax validation before spawn.** At the top of `runWslShell` / `buildWslExecArgv`, distro (`DISTRO_NAME`) and username (`LINUX_USER`) reject separator characters — the safety of the exec path does not depend on wsl.exe's external, undocumented tokenization rules; checkPath also does UNC validation before any wsl.exe side effect (regression pinned in verify-world).
|
|
134
|
-
|
|
135
|
-
## Key constraints (all measured, none inferred)
|
|
136
|
-
|
|
137
|
-
1. **Workspace paths must be in UNC spelling.** `packages/workspace/workspace/src/paths.ts:16-23` rejects POSIX paths `/home/...` as illegal on win32 (root === '/'); only `C:\…` and `\\server\share` pass.
|
|
138
|
-
2. **The plugin must live inside the profile directory.** The profile's module resolver routes `@deepseek-ai/*` to the installed generation only for modules inside the profile prefix; with `link:` outside the profile, all 7 harness packages report `Cannot find package`.
|
|
139
|
-
3. **Host plugin code cannot hot-reload.** Node caches modules by URL; reinstalling into the same directory still serves old code; hence the core logic is written as pure modules independent of the harness, verified by standalone Node scripts.
|
|
140
|
-
4. **9P sharing has no hard links.** `link()` reports `ENOTSUP`; `ReplaceFileW` / `SetFileSecurityW` are local-volume Win32 APIs, meaningless on a network share — all three are covered by `WslFileSystem`.
|
|
141
|
-
5. **`appendWindowsPath = false` is a common default.** Host programs are not on PATH; absolute `/mnt/c/Windows/System32/*.exe` paths are required (`hostExecutable()`).
|
|
142
|
-
6. **At client-plugin apply time, `<body>` may not exist yet.** The client half applies during document parsing, where `document.body` is `null`; `MutationObserver.observe(document.body, …)` then throws outright and the whole apply fails, leaving the UI silently unresponsive (the first W-button version tripped exactly here). The observation root must be `document.documentElement`, with a timer fallback in addition — relying on the observer alone assumes "there will always be a childList mutation", an assumption that does not hold.
|
|
143
|
-
7. **Client-half changes hot-update; host-half changes do not.** Rewriting the currently deployed generation's `lib/client.js` in place changes the delivery rev and pushes it to the page via `/plugins/events`, **no restart needed**; changing `lib/index.js` requires a restart. `scripts/inspect-live-client.mjs` reads the bundle the host actually delivers (in-memory cache; the on-disk file is not evidence).
|
|
144
|
-
|
|
145
|
-
## Layout
|
|
99
|
+
Repository layout:
|
|
146
100
|
|
|
147
101
|
```
|
|
148
102
|
lib/index.js Host: routes, preset generation, session preset binding
|
|
@@ -165,96 +119,15 @@ scripts/verify-*.mjs Standalone verification (no harness needed)
|
|
|
165
119
|
scripts/verify-all.mjs Aggregates and runs all suites (--live adds the suites needing a running host)
|
|
166
120
|
```
|
|
167
121
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
```powershell
|
|
171
|
-
node scripts/verify-all.mjs # all offline suites (equivalent to the ones below)
|
|
172
|
-
node scripts/verify-all.mjs --live # additionally the suites needing the installed plugin + a running host
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
**How the aggregate reads a SKIP (commit `2d44dd6`)**: a suite's exit code 2 is its own SKIP (a check it could not evaluate on this machine), and the aggregate reads exit codes — it cannot see the suite's own `SKIP` block — so a skip counts **only** where `scripts/verify-all.mjs`'s `DECLARED_SKIPS` names the suite together with the **precondition** that allows it. The summary therefore reads `N/M suites passed (K declared skip: <name>)`, and each `SKIP` prints the precondition it declared; an **undeclared** skip fails the aggregate (`FAIL (undeclared skip) <suite>`, plus the block naming the fix — add an entry to `DECLARED_SKIPS`, or remove the precondition that forced the skip) and the run exits 1 — so exit 0 can no longer coexist with "one suite never ran". A declaration whose precondition does not hold here is **dormant**: the suite runs, one extra `NOTICE` line is printed, nothing reddens. A **dead** declaration (the suite was renamed / its source no longer has an exit-2 branch / it is not in the suite list) fails **before any suite runs**, because that rot is the repository's own and an operator can clear it on the spot. The whole ruling is pinned by `scripts/verify-all-skip.mjs`, which builds copies of the aggregate over fixture suites (outside the repository) and reads real processes' real exit codes and summaries. It also re-derives both directions of the table from the real `STANDALONE` list and the suites' own exit-2 **shape**: a suite that can skip without a declaration is named, and so is a declaration whose suite no longer carries that shape.
|
|
176
|
-
|
|
177
|
-
Run a single item:
|
|
178
|
-
|
|
179
|
-
```powershell
|
|
180
|
-
node scripts/verify-world.mjs # path translation + executing commands in the distro + directory facts + exec boundary rejection
|
|
181
|
-
node scripts/verify-preset.mjs # preset rewriting (run against the bundled standard preset)
|
|
182
|
-
node scripts/verify-fs-fence.mjs # fs fence pure logic: containment, cross-distro, writable-root derivation
|
|
183
|
-
node scripts/verify-fs-fence-skip.mjs # the fence suite’s report when the machine has one distribution: the precondition, every unevaluated assertion, the remedy, exit 2 — and all four assertions still run with a second
|
|
184
|
-
node scripts/verify-9p.mjs # 9P sharing primitive profiling + identity mapping (a load-bearing fence assumption)
|
|
185
|
-
node scripts/verify-9p-skip.mjs # the 9P probe's report when the machine has one distribution: its content, exit 2, and that it does not skip early
|
|
186
|
-
node scripts/verify-confinement.mjs # confinement fence: workspace writable, outside rejected, ownership correct, spaces in paths
|
|
187
|
-
node scripts/verify-terminal.mjs # PTY bridge: resize / foreground process group / signals / terminate
|
|
188
|
-
node scripts/verify-pty-handle.mjs # the JS terminal handle (run against the real bridge)
|
|
189
|
-
node scripts/verify-client-ui.mjs # browser-half static checks (no slot registration, locator geometry, host calls)
|
|
190
|
-
node scripts/verify-client-dom.mjs # browser-half behavior checks: the real factory run in jsdom (mount location / convergence when out of room / hiding follows)
|
|
191
|
-
node scripts/verify-modules.mjs # host-half structural pins: the distro seam + the `exports` map (`./client` is a hard contract)
|
|
192
|
-
node scripts/verify-sync.mjs # runs the real sync.ps1 against a disposable profile: four generation-retention scenarios (link resolves / dangling / no link / never staged into)
|
|
193
|
-
node scripts/verify-all-skip.mjs # the aggregate's ruling on a SKIP: an undeclared skip fails / a declared one is reported with its precondition / a dead declaration fails before any suite runs
|
|
194
|
-
node scripts/verify-route.mjs # live: the acceptance route (needs a running host)
|
|
195
|
-
node scripts/inspect-live-client.mjs # reads the client bundle the host actually delivers (accepts marker strings)
|
|
196
|
-
.\scripts\sync.ps1 # stage into the profile; an already-installed profile also gets its link re-pointed (a first install is still wired by plugin_manager)
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
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`.
|
|
200
|
-
|
|
201
|
-
## Install / Update / Release
|
|
122
|
+
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).
|
|
202
123
|
|
|
203
|
-
|
|
124
|
+
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).
|
|
204
125
|
|
|
205
|
-
|
|
206
|
-
- CLI equivalent: `plugin_manager install_bundle dsh-wsl-desktop@<version>`.
|
|
207
|
-
- **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 per the "Confinement" section is recommended (closes the retained-grant boundary).
|
|
208
|
-
- **Update**: installing a new version number is enough; after a desktop major update, run `verify-post-restart.mjs` first per "Desktop update discipline".
|
|
209
|
-
- **Uninstall**: uninstalling via the plugin manager also withdraws the wsl-* presets registered by this plugin (guaranteed by the disposer lifecycle).
|
|
126
|
+
## Release
|
|
210
127
|
|
|
211
128
|
**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).
|
|
212
129
|
|
|
213
|
-
> ⚠️ **`exports["./client"]` is a hard contract and the easiest thing to delete while editing metadata.**
|
|
214
|
-
> ```
|
|
215
|
-
> DesktopHostFatalError: dsh: startup failed: 1 required plugin did not activate
|
|
216
|
-
> client-modules: dsh-wsl-desktop declares dsh.client but exports no "./client" bundle
|
|
217
|
-
> ```
|
|
218
|
-
> The v0.2.0 "release readiness" metadata rewrite (`38e6356`) deleted the whole `exports` block, which is why 0.2.0 and 0.2.1 **cannot start at all once installed**; `main` is not a substitute — Node ignores it when resolving the `./client` subpath. `scripts/verify-modules.mjs` now pins this (`./client` and `.` both present, client entry distinct from the host entry, file present on disk, platform web), so running it before a release catches the regression. **`package.json` is part of the deployed surface** alongside `cordis.patch.yml` and `lib/`: `verify-post-restart.mjs` compares the running manifest against the checkout byte for byte.
|
|
219
|
-
|
|
220
|
-
**Code install (development mode)**:
|
|
221
|
-
|
|
222
|
-
```bash
|
|
223
|
-
git clone https://github.com/zcluo/dsh-wsl-desktop.git
|
|
224
|
-
cd dsh-wsl-desktop
|
|
225
|
-
node scripts/verify-all.mjs # full offline run
|
|
226
|
-
.\scripts\sync.ps1 # stage into the profile and re-point (developer mode: developerTools enabled; a first install needs the wiring first)
|
|
227
|
-
# restart DSH Desktop → verify-post-restart.mjs
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
**Previously flaky → fixed, stable across many rounds**: `verify-terminal.mjs` used to fail intermittently (measured 1 in 6). The root cause was host-side `lib/wsl/pty.js`, not the bridge: the allocation-failure path did not terminate the already-spawned data process, and the leaked bridge interfered with later runs; control replies carried no request id, so after one timeout a late reply was consumed by the next request and the whole control channel misaligned from then on. Fix: the failure path terminates and waits for both processes to exit; every request carries an id, the bridge echoes the same id, timeout removes the entry first, and late replies are dropped outright. After the fix, a dozen-plus full-suite rounds today (including several back-to-back) reproduced nothing; the conclusion is stable.
|
|
231
|
-
|
|
232
|
-
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**: rewriting the current generation's `lib/client.js` in place changes the delivery rev, and the change is pushed to open pages via `/plugins/events` (`patchReload: live`). `verify-post-restart.mjs` reads the live module graph from `/plugins/events` and fetches back the bundle actually delivered, to assert exactly this. **The rev is not updated instantly, though**: the host rebuilds a client bundle lazily, so reading `/plugins/events` immediately after an in-place rewrite still returns the OLD rev (measured: it changes a few seconds later). "The file changed" is therefore not "the served bytes changed" — a verification has to wait for the new rev, or it reaches the wrong "already deployed" conclusion.
|
|
233
|
-
|
|
234
|
-
`sync.ps1` stages into a fresh timestamped directory each time (Node caches modules by URL; reinstalling into the same directory still serves old code; the stamp is second-resolution, so a second run inside the same second is bumped to a free name — the loader silently ignores a row id it has already mounted), and it **re-points the profile link at the generation it just staged**, rewriting the profile's `package.json` and `pnpm-lock.yaml` with it — otherwise the next `pnpm install` reconciles the link back to the manifest and "already staged" becomes a fiction. **The retention rule is "keep the two newest"**: the moment the link moves, "the linked generation" is the one nobody is running, while the running host resolves the one staged before it; keeping only the link would delete the generation in use on the next stage and break every WSL session until the next restart. When the link **cannot identify a generation** (the profile has no link at all, or its target is already gone) `sync.ps1` **keeps every generation and warns**, and a profile that has **never been staged into** (no `plugins/` directory at all) gets the same warning — with the link path spelled out, because that path is the only fact the reader needs. In that case it has merely put the files in place: nothing takes effect until the profile has this plugin installed (a first install is wired up by plugin_manager). The link is deleted through .NET rather than `Remove-Item`: Windows PowerShell 5.1 throws NullReferenceException on a junction, which aborted the re-point midway with the old generation still linked. `scripts/verify-sync.mjs` exercises all of this by running the real script against a throwaway profile (four scenarios: a link that resolves, a dangling link, no link, and never staged into — the last pinning that the warning names the link path).
|
|
235
|
-
|
|
236
|
-
## The fs tool fence
|
|
237
|
-
|
|
238
|
-
`WslFileSystem` carries its own fence: it declares `sandboxMode`, and both mutation entries, `writeText`/`editText`, go through `checkedTarget` first (rejections throw structured `FS_SANDBOX_DENIED`, which the tool layer maps into a model-visible `[sandbox: …]` marker plus an escalation hint); the containment comparison and writable-root derivation are pure functions in `lib/wsl/fence.js`. It does **not** inherit the official sandbox backend — the official backend would wrap this class inside a second backend, adding a layer of composition dependency for nothing, while the fence is, at bottom, "a policy check inside trusted code" and belongs in this class. (The original attribution — "the realm cannot see `sandboxPolicy`, so it cannot inherit" — was wrong; see lesson 1 below: `shell.js` in the same realm had been injecting that service all along.)
|
|
239
|
-
|
|
240
|
-
**Writable roots and the comparison namespace**: the `workspace-write` allow set = the session cwd (the workspace root) + **the distro's** `/tmp` (on the 9P share, `\\wsl.localhost\<distro>\tmp` — where a Linux-side `/tmp/…` request resolves in this world; the host POSIX `/tmp` from the official derivation is meaningless on Windows) + the Windows temp directory (reachable via `/mnt/<drive>`). The comparison happens in the **host namespace**: targetKey is in Windows spelling, and the UNC prefix carries the distro identity, so "a Linux path that happens to spell the same in another distro" cannot escape the boundary; unknown modes get an empty allow set, i.e. deny (fail-closed). `checkedTarget`'s re-normalization also starts from **targetKey**, not displayPath — displayPath is in Linux spelling without a distro, and re-resolving from it pins the path onto this class's fixed distro, silently rewriting cross-distro UNC requests (live-tripped: written into debian-dev, read from debian reported not found); now cross-distro requests get `FS_SANDBOX_DENIED` directly.
|
|
241
|
-
|
|
242
|
-
**Why the fence must exist**: `LocalFileSystem` never overrides `FileSystem.sandboxMode`. A backend that claims nothing leaves `tool-fs`'s `FsSandboxController` unable to resolve a policy for every call (`tool-fs/src/sandbox.ts:43-50`: `defaultMode === undefined` ⇒ `escalationModes = []`, `policy = undefined`), so `write`/`edit` are entirely unmanaged and can write anywhere the share reaches — including `/mnt/c` — and `toHostPath` also accepts direct `C:\…` spelling, so the actual exposure while unfenced is the entire Windows filesystem, not just the share.
|
|
243
|
-
|
|
244
|
-
**Lessons from two failed attempts** (recorded here to avoid repeating them):
|
|
245
|
-
|
|
246
|
-
1. Inheriting the official backend → the whole class never activated. At the time I attributed it to "the realm cannot see `sandboxPolicy`", **but the real cause was that I had deleted the `LocalFileSystem` import** (`node --check` parses syntax only; it cannot see undefined identifiers). Symptom matching is not attribution.
|
|
247
|
-
2. The first version of the built-in fence **denied everything** when it "could not get the workspace root", including the plugin's own `/tmp` writes. Only after tracing the mechanism did it become clear: the official backend's fallback is the same `sandboxPolicy.resolve()` (no arguments), **which itself cannot produce the workspace root either** — the root is always passed in by `tool-fs` on every call (`resolvePolicy` stamps it with the calling session's cwd).
|
|
248
|
-
|
|
249
|
-
**The selftest changed accordingly**: it now passes the policy explicitly, like a real caller: `{ mode: 'workspace-write', workspaceRoot: <session cwd> }`. It previously passed nothing — "calling fs in a way no real caller would ever use" — which is why it got rejected last time, not because the fence was too strict.
|
|
250
|
-
|
|
251
|
-
**The canonicalization rule (Task 2)**: the containment verdict also refuses a target whose path traverses a component that EXISTS but cannot be canonicalized. Measured on this share: `realpathSync.native` — the fence's canonicalizer, and the call `resolveLocalTarget` makes (`fs-local/src/fsio.ts:161-210`) — answers ENOENT for a Linux symlink entry, while `lstat` answers EISDIR and `readdir` lists the entry; the share's own `mkdir(directory, {recursive:true})` (`fs-local/src/fsio.ts:598`) *does* resolve that spelling and creates the missing level AT THE LINK'S TARGET, outside the writable root. The rule: every component strictly between the writable root and the target's own name must either not exist (`lstat` ENOENT/ENOTDIR) or canonicalize. The target's own name is exempt — a final-component link is measured safe (the publication's rename replaces the link entry inside the root and the link's target file is untouched) and it works today, and a rule that refuses legitimate same-root writes is worse than the gap it closes. The rule lives in `lib/wsl/fence.js` (`isUnderHost`, through the new `canonicalizationOf` / `componentsCanonicalize`), on BOTH the lexical fast path and the identity walk, so the `wsl$` alias spelling cannot bypass it; `checkedTarget` and the two mutation entries are unchanged. The measured cost is zero: a write through either kind of link cannot publish on this share at all (the recursive `mkdir` reports ENOENT for a path through a link, even when the intermediate directories exist), so the refusal replaces a stray out-of-bounds directory followed by ENOENT with a refusal BEFORE anything is created. What remains is the check-to-publication race: a link planted between `checkedTarget` and that `mkdir` is invisible to any check, because the canonicalizer is blind to it.
|
|
252
|
-
|
|
253
|
-
**Two arms, and neither may be reddened**: what the fence answers depends on what its canonicalizer can DO with the link, so the blind-arm expectations are written as relations against the measured blindness (`=== !blind`, the shape the case-variant pin already used) rather than as constants. The resolving arm is pinned too: an NTFS directory junction is a reparse point `realpathSync.native` RESOLVES (measured), needs no privilege, and the suite removes it without following it (measured). The world-independent subject is the **WRITE KEY** — the key a write actually hands the fence, produced by fs-local's own resolution walk (`resolveLocalTarget`, mirrored in the suite as `writeTargetKey`); `canonicalHostPath` is NOT that key (it realpaths the whole path and falls back to the input, so a missing tail makes it return its own spelling on any share — using it as the write's key is what made a first-round claim unsound).
|
|
254
|
-
|
|
255
|
-
**Two pins + live acceptance**: `scripts/verify-modules.mjs` pins the fence's existence (declares `sandboxMode`, both mutation entries go through `checkedTarget`, rejections use `FS_SANDBOX_DENIED`, the containment comparison has separator boundaries); `scripts/verify-fs-fence.mjs` verifies the pure logic offline (separator boundaries, casing, **same-spelling cross-distro paths rejected**, **components that exist but cannot be canonicalized refused** (Task 2: a self-built link fixture plus five controls that must stay authorized, the write key as the world-independent subject, and an NTFS-junction arm so the blind-arm expectations are not constants), writable-root derivation, unknown modes fail-closed); `verify-9p.mjs` gained identity-mapping probes (distinct files have distinct (dev,ino); the wsl.localhost/wsl$ spellings are stable — the fence's identity fallback is load-bearing on this) and now ASSERTS the fence's refusal of the escaping spelling where it used to record a HAZARD. The zero-cost half of the rule is pinned STRUCTURALLY against the harness checkout's `packages/fs/fs-local/src/fsio.ts`: the call must be a BARE AWAITED statement — `await` immediately before it, nothing but blank (or `;`) after it on its line, no try/catch between the function's opening and the call (so a guard opened earlier cannot slip through), and none between the call and the next `try {` — and the guarded region must be the staging one. Six mutations run on copies redden it (the unmutated file must stay green) and the checkout is never touched; an unreadable checkout is a counted SKIP and the suite exits 2, so `verify-all` shows SKIP — the suite is declared in `DECLARED_SKIPS` with that precondition, which the summary prints — instead of a green suite with an unrun pin. The class wiring is live-accepted by `verify-post-restart.mjs` (out-of-bounds write rejected, PASS). And `verify-9p.mjs` SKIPS its three cross-share identity rows when the machine has only ONE distribution — the owner's ruling: a missing precondition, not a broken profile. The SKIP names the missing second share, the three facts that therefore went unmeasured and the remedy, and the suite exits 2, so `verify-all` reports SKIP (declared in `DECLARED_SKIPS` with that precondition, which is printed) instead of a pass: a green aggregate cannot imply those facts were established. Only that family is skipped (the symlink and case facts need no second share and are still measured and printed). The report's CONTENT is pinned by `scripts/verify-9p-skip.mjs`, which forces the precondition through the probe's own override and reads the real child's stdout and exit code, so its assertions run on every machine — and it pins the control too: with a second distribution present the probe still measures all three rows and exits 0. The one other family it SKIPs is the link fixture: when it cannot be built (a failed or timed-out `wsl.exe`) the run loses not only the three symlink facts but the assertion that fixture EXISTS for — the fence's refusal of the spelling its own canonicalization produces, which no other check covers — so those are counted too (3 facts + 4 checks) and the suite exits 2.
|
|
256
|
-
|
|
257
|
-
**The fence suite has the same family.** `scripts/verify-fs-fence.mjs` carries **four cross-distribution assertions** that need the same second share: three with across-share subjects plus a **control** (a case-variant spelling of the SAME distribution must stay contained — a binding that compared the distribution segment case-SENSITIVELY would refuse a legitimate target, which is worse than the defect it closes). On a one-distribution machine none of them can be evaluated, and the precondition used to FAIL the suite (exit 1); the owner ruled for a SKIP: a `SKIP` line names the precondition (no second distribution installed / the override pointed at the selected distribution / an empty override / a resolved share that does not answer), **every unevaluated assertion by its own label**, what is therefore unestablished, and the remedy — counted (4) and ending in exit 2, so `verify-all` reports SKIP (the suite is declared in `DECLARED_SKIPS` with that precondition, which is printed) instead of PASS. The labels are not prose any more: the checks PRINT them and the SKIP prints them from ONE list, `CROSS_DISTRO_CHECKS`, so the words inside the SKIP cannot drift from what actually did not run (the old text, "the two cross-distribution assertions", counted them wrongly and named none of them). That family's content, and both machine classes, are pinned by `scripts/verify-fs-fence-skip.mjs` (in `STANDALONE`, so it runs on every aggregate): it forces the precondition through the suite's own override (pointed at the selected distribution, and empty), simulates the owner's machine with a copy of the tree whose `listDistros()` reports one distribution, and reads a real child's stdout and exit code. The **control** proves the skip is conditional — with a second distribution present the suite still exits 0, prints no SKIP of this family, and runs all four assertions (each label printed PASS) — and a copy whose `lib/wsl/fence.js` has the **distribution binding removed** must redden the shared-identity assertion, so "they still run" is proven rather than claimed.
|
|
130
|
+
> ⚠️ **`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).
|
|
258
131
|
|
|
259
132
|
## License
|
|
260
133
|
|