dsh-plugin-wsl-env 0.7.4 → 0.8.0

package/CHANGELOG.md

@@ -12,6 +12,304 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-06
+
+The toolchain's TypeScript story completes (pnpm, a checkJs gate, and 36 of 36
+modules with their declarations shipped), and with it three behaviour fixes
+land: the byte-window cap is enforced, the agent path's EXEC capture budget is
+honoured, and the filesystem's host-path mapping speaks its synchronous
+contract.
+
+One theme: the toolchain moves from npm to pnpm. `pnpm-lock.yaml` replaces
+`package-lock.json`, CI installs through corepack with
+`pnpm install --frozen-lockfile` (the `packageManager` field pins pnpm 11.7.0,
+matching the harness repository), and the three dependencies with install
+scripts (`@deepseek-ai/dsh-subprocess-local`, `koffi`, `node-pty`) are
+allow-listed in `pnpm-workspace.yaml` — pnpm 11 blocks dependency build
+scripts by default. With it: `engines` and the CI matrix align with the harness
+host's own floor (`^22.19.0 || >=24.0.0`), so the Node 20 legs are gone, and
+the per-target lock test drops its unused `withResolvers` gate, a Node 22+ API
+that hung those legs on every push.
+
+One more theme: the whole repository comes under a TypeScript check gate.
+`tsc --noEmit` under `strict`/`checkJs` now runs as part of `pnpm test` over
+`lib/**`, `test/**` and the probe scripts, with the types taken from the peer
+packages' own declarations and the service augmentations loaded through
+`types/dsh-services.d.ts`. The gate's first pass surfaced the seam work this
+package already carries: the private `spawnSpec` the WSL spawn directory needs
+(`docs/UPSTREAM-SPAWN-SEAM.md` bridges it) and a synchronous-contract violation
+in `processPathFromHostPath`, pending a design decision.
+
+Extending the gate to the tests found real defects the untyped corners had
+been hiding: `distroReadBytes` accepted the byte-window cap (both call sites
+pass it) but neither documented nor enforced it, so a ranged `readBytes`
+asking past the page cap was served instead of refused — upstream refuses a
+window the same way it refuses a page. Fixed against the upstream wording and
+arithmetic (`lib/workspace-files-wsl.js`), with an absent length now
+defaulting to the window cap rather than the whole-file cap, as upstream's
+`resolveWindow` defaults it; the refusal is pinned in
+`test/workspace-files-wsl.test.mjs`. Two hand-written JSDoc contracts wider
+than their code (`gitSpawnRewrite`'s `argv`/`cwd`, `wslErrorCode`'s
+`stdout`/`stderr` — both tolerate absence at runtime) and one narrower than
+its caller (`uncToPosix`'s path) were corrected to what the functions actually
+take. Test doubles are typed as the slice of the seam they script, reaching
+the seam's declared type through one documented cast at the injection point —
+no `any` and no new `@ts-expect-error` anywhere in the suite.
+
+And the migration's third step opens: `src/agent-protocol.ts` is the first
+module whose source is TypeScript. `pnpm run build` (`tsconfig.build.json`)
+emits `lib/agent-protocol.js` plus `lib/agent-protocol.d.ts` under the same
+export paths, and the artifacts stay committed so a bare checkout remains
+loadable and the tarball needs no build step; the new `lint:build` gate
+(`test/build-freshness.mjs`) makes `pnpm test` fail the moment a committed
+artifact drifts from its source. Generated files are excluded from the
+`checkJs` gate — their TypeScript sources are type-checked with
+`noEmitOnError` instead, which is strictly stronger. The protocol message
+union now has one home: `lib/agent.js` and the script-driven tests import
+`AgentMessage` and friends from the protocol module's declarations instead of
+restating them.
+
+And the declarations land for every module. A second, declaration-only pass
+(`tsconfig.dts.json`, driven by `scripts/build.mjs`) emits `.d.ts` for the
+hand-written, JSDoc-typed JavaScript, and every export subpath now carries its
+`types` condition — downstream finally sees this plugin's types, verified end
+to end (a consumer's wrong call is rejected with the precise signature). The
+declaration pass must run against a clean tree: a stale `.d.ts` is resolved as
+an input exactly where `./x.js` would be, and re-emitting through it silently
+degrades the result — a precise type in `index.d.ts` collapsed to `any` that
+way during the migration — so the build deletes the declarations its first
+pass does not own before re-emitting, and `lint:build` snapshots the
+artifacts, runs the real build, byte-compares and restores the tree.
+`lint:style` gained the invariant that keeps the surface from rotting: a
+JavaScript export without its `types` sibling fails the gate.
+
+`lib/paths.js` follows as the second migrated module — the path algebra every
+other module imports, plus `DistroPath`/`WorldPathOptions`, which consumers
+reference through `import("./paths.js").DistroPath`; the TypeScript source
+keeps those names, so nothing downstream changes except that they now come
+from a checked source. CONTRIBUTING records the per-module checklist this
+settled into: write `src/<name>.ts`, add the generated JavaScript to the two
+`exclude` lists, build, and let the suite verify the artifact is
+behaviourally identical.
+
+Three leaf modules then follow in one pass — `agent-errors` (the two error
+classes the executor switches on), `probe-cache` (the verdict policy that
+remembers successes and re-probes failures) and `listing` (the picker's pure
+helpers, `boundedInsert`'s generic included). Each was verified export-for-
+export against its predecessor, and the whitespace-normalized code diff is
+tsc's statement reflow and nothing else; every source keeps its module doc
+plus a note naming the generated artifact.
+
+The next four carry the decision layer: `fsio-text` (the byte-for-byte
+replication of the peer's text mechanics — `FsCodedError` gained a declared
+`code` field, and the stream decoder is typed through `node:util`, since
+Node's global `TextDecoder` is a value, not a type), `fs-decisions` (the
+refusal descriptors, with `Refusal` as an exported interface and `isCoded` as
+a real type predicate), and `git-route`/`search-route` (the two spawn
+rewrites; their generated artifacts are byte-identical modulo whitespace).
+Nine of the thirty-six modules now have TypeScript sources.
+
+Six more follow — `terminal-route`, `preset-choice`, `ports`, `bwrap`,
+`agent-confined` and `agent-shared` — and they cross a structural line: a
+source may now import a module that is not migrated yet. `rootDirs` merges
+`src/` and `lib/` for resolution, so `./agent.js` resolves through the
+generated `lib/agent.d.ts` while the emitted specifier stays `./agent.js`;
+because that merge also pulls declarations in as program inputs, pass 1 now
+emits into a scratch directory the build script copies from, keeping inputs
+and outputs disjoint (TS5055 otherwise). `agent-shared`'s generated artifact
+is byte-identical even after whitespace normalization; the rest differ only
+by tsc's statement reflow. Fifteen of the thirty-six modules are TypeScript.
+
+The mid-size tier follows: `wsl` (the `wsl.exe` interop primitives — its four
+option shapes are exported interfaces now), `agent-exec` (the agent-backed
+execution handle, whose request/result/runner/handle typedefs the tests and
+`search-exec` already imported by name) and `shell-env` (the `DSH_*` fact
+contributor, typing the harness registry it contributes through structurally,
+as its JSDoc always did). `agent-exec` surfaced one Node typing fact worth
+knowing: `Buffer.alloc(0)` infers `Buffer<ArrayBuffer>` while an incoming
+`Buffer` is `Buffer<ArrayBufferLike>`, so the accumulators are annotated
+`Buffer`. Eighteen of the thirty-six modules are TypeScript now.
+
+Seven small modules follow — `watcher` (the in-distro mtime watch loop and its
+protocol, `ChildProcess` and options typed), `sandbox-core`/`sandbox` (the
+bwrap probe-and-confine pair; `WslConfined`/`WslSandboxCoreInstance` are
+exported interfaces and the two class fields are `declare` so the emitted
+JavaScript stays byte-identical), `terminal-activity`, `search-exec`, and the
+two entry re-exports `shell`/`fs` (whose artifacts are byte-identical). At
+twenty-five of thirty-six, the remaining modules are the large ones: `agent`,
+`fs-substrate`, `fsio-agent`, `picker`, `subprocess`, `auto-preset`,
+`workspace-files-*`, `file-reference-wsl`, `fs-routing`, and finally `index`.
+
+The route layer follows — `workspace-files-route` (the pure build/parse pairs
+for the distro-routed file service), `file-reference-wsl` (the `@`-completion
+traversal strategy, with `TraversalDirent`/`FileReferenceTraversal` as
+exported interfaces) and `fs-routing` (the root-plane coordinate router).
+`fs-routing` is where the compiler re-met the documented upstream seam:
+`WslFileSystem.processPathFromHostPath` is async against the `FileSystem`
+interface's synchronous contract, so the router's lazy backend is typed as the
+concrete class rather than casting the mismatch away — the seam keeps its one
+visible `@ts-expect-error` in `index.js`. The port also dropped two dead
+imports `fs-routing` had carried since a refactor (`windowsToLinuxMount`,
+`linuxJoin`), which the emitted artifact no longer contains. The orphaned
+`linuxJoin` doc block above the class — a leftover of that same refactor — is
+gone too. Twenty-eight of the thirty-six modules are TypeScript.
+
+`fs-substrate` and `auto-preset` follow — the agent-backed filesystem face
+(`ResolvedTarget` exported as an interface, its six instance fields declared
+with `declare` so the emitted JavaScript stays byte-identical) and the
+preset-adoption plugin (whose harness service slices stay spelled
+structurally, and whose `ensureSession` patch carries the `this: unknown`
+parameter the JSDoc already documented). Thirty of the thirty-six modules
+are TypeScript; the remaining six are `agent`, `fsio-agent`, `picker`,
+`subprocess`, `workspace-files-wsl` and `index`.
+
+`picker` follows — the biggest single module migrated so far after the
+protocol file itself (494 lines). Its config, the cached distro listing and
+the per-distro home map are `declare`d so the emitted JavaScript stays
+byte-identical, and the browse capability object stays an inline class field,
+which is how the original script wrote it. Thirty-one of the thirty-six
+modules are TypeScript.
+
+`subprocess` follows — the composition-level provider behind the GUI's
+terminal window, and the last module that overrides a shipped peer class for
+the terminal/search routing. Its `spawnTerminal`/`spawn` overrides are checked
+against the peer's declared signatures (they pass without a new assertion),
+and the two JSDoc casts the script carried (`env`, the stdout collect budget)
+are absorbed into the types. Thirty-two of the thirty-six modules are
+TypeScript; the last four are `agent`, `fsio-agent`, `workspace-files-wsl`
+and `index`.
+
+`agent` follows — the resident in-distro agent's whole lifecycle (756 lines).
+Its seven internal methods stay `private`, which surfaced the migration's one
+structural seam: a class with private members is nominal, so the declaration
+generated for the still-un-migrated `fsio-agent` and the one this source emits
+are not interchangeable even though the runtime object is the same class. The
+one boundary (`fs-substrate` handing agents to `DistroFs`) crosses it through a
+single documented assertion naming the lib-side type; it disappears when
+`fsio-agent` migrates. Thirty-three of the thirty-six modules are TypeScript.
+
+`fsio-agent` follows, and with it that seam closes: the lib-side declaration
+it used to drag in is gone, so the boundary assertion in `fs-substrate` is
+deleted in the same commit — the class is declared once now, and the private
+members it keeps are nominal against nothing else. Thirty-four of the
+thirty-six modules are TypeScript; `workspace-files-wsl` and `index` remain.
+
+`workspace-files-wsl` follows — the distro-routed GUI file service, with
+`WorkspaceFilesWslConfig`/`DistroListing` exported, the row-config read kept
+as its one documented double cast (the base class keeps `config` private), and
+the `readByteRange` expect-error left exactly where it was: that one is an
+open design decision, not a migration artifact. Thirty-five of the thirty-six
+modules are TypeScript; `index` is the last one.
+
+`index` closes the migration — the integration layer's two providers, 1400
+lines, with both documented upstream seams intact: the private `spawnSpec` a
+`wsl.exe` spawn needs, and the `processPathFromHostPath` contract violation,
+keep their `@ts-expect-error` carrying the reason. The generated artifact is
+proven structurally identical to the hand-written module: an AST comparison
+that treats the erased type wrappers (`as`, `@type` casts, parentheses) as
+transparent reports only the imports the source no longer needs — a never-used
+`fileURLToPath`, the dead `isUnderDistro`, and the type-only `WslAgent` (which
+tsc elides; the module still loads through its other edges) — plus tsc's
+reflow and one internal rename in `decorateResult`, whose result row now
+derives from the handle type instead of a second type parameter. `resolve()`
+returns the precise `WslExecSpec` where the JSDoc declared the wider
+`ShellExecSpec`. Thirty-six of thirty-six modules are TypeScript.
+
+The transitional scaffolding then retires, nothing left for it to do:
+`rootDirs` and the scratch declaration emission existed for a mixed tree
+(`src/` sources importing un-migrated `lib/*.js` neighbours), and the
+declaration-only second pass (`tsconfig.dts.json`) existed to give the
+hand-written JavaScript its `.d.ts`. `pnpm run build` is one `tsc` pass
+emitting JavaScript and declarations straight into `lib/`, pruning
+declarations no source owns; the `checkJs` gate drops its 36-entry exclude
+list and states what is NOT generated — `test/**` and the ambient service
+types, with `src/` checked by the build program (`noEmitOnError`); and
+`lint:build` enforces the closed corpus (every `lib/*.js` has its
+`src/<name>.ts`, every source has both artifacts), so "`lib/` is entirely
+generated" is a checked property rather than a convention.
+
+The real-machine probes then re-ran green on the migrated tree — 12 of 12, the
+one verification face CI cannot cover (its self-hosted leg is skipped):
+filesystem mutation through the throwaway wslfs profile, terminal, mode,
+missing-wsl, bwrap, the shell confinement wiring, sandbox-off, picker, agent
+protocol, watch, substrate and exec. The run surfaced two defects in the probe
+harness itself. `ELECTRON_RUN_AS_NODE` — the flag that boots the harness CLI in
+node mode — never crossed the WSL interop boundary: interop hands a Windows
+process only the variables `WSLENV` lists, so the inline assignment was dropped
+and the app booted as its GUI self, leaving the probe waiting on a process that
+would never run; `test/probe/env.sh` lists the flag now, composed with any
+`WSLENV` the caller had. And the kill-cleanup check counted every `sleep` in
+the distro, which the resident agent's lease watchdog — introduced after the
+probes last ran — makes non-zero by construction, alongside in-flight timeout
+watchers; the check counts its own command line now, so a kill that really
+leaked still fails it. And the suite's live log sits inside the checkout,
+where the mirror sync's `tar` read it while it grew — `file changed as we read
+it`, exit 1, `set -e` failing the probe before it ran; the sync excludes
+`test/probe/.scratch` now, which is run scratch nothing at runtime reads.
+
+One real defect fell out of the type gate's migration notes and closes here:
+the agent execution path handed the EXEC frame the volatile wrapper object
+where a byte budget belongs. `encodeExecFrame`'s `> 0` test was false on an
+object, the frame carried 0, and 0 is the agent's "uncapped" — so the cut at
+the caller's per-stream budget that `agent-exec` documents never ran, and a
+chatty command cost unbounded distro memory. `src/index.ts` now reads
+`config.maxOutputBytes.get()` like every other volatile field, and
+`test/provider.test.mjs` pins the resolved number in the frame (the check
+fails against the previous artifact). The one-shot path was always correct —
+it reads the same field through the upstream executor's own `.get()`.
+
+The second pending seam closes the same way — with an implementation instead
+of a note. `WslFileSystem.processPathFromHostPath` was `async` against the
+peer interface's synchronous contract, so the consumers that read it without
+awaiting (spill-policy's attachment mapping, the session controller's and the
+UI's path verification) received a Promise — always truthy, never the
+`undefined` they test for — and mapped nothing. It is synchronous now, built
+from what is already known: the distro once `distro()` has resolved it (the
+pinned config, or the default `wsl.exe` answered by an earlier operation) and
+the configured `cwd`, or the resolved home for a relative path. A call that
+would have to ask `wsl.exe` — a cold default distro, a relative path before
+the home is known — answers `undefined`, the same "no mapping" the ssh
+provider gives, so the consumers take their documented refusal path instead of
+receiving a bogus value. The value keeps the world spelling the backend keys
+on, so their map → resolve → processPath round trip closes exactly as it does
+for the host backend. `test/provider.test.mjs` pins the sync value, the round
+trip, and both `undefined` cases (the checks fail against the previous
+artifact). The `@ts-expect-error` count drops to three: the two remaining
+design decisions and the upstream spawn seam.
+
+The last in-code seam note closes by deletion rather than repair. The GUI file
+service's `readByteRange` — a method older than the migration, which the type
+gate flagged with an expect-error because its host-workspace branch called a
+base method that does not exist — turned out to be unreachable: the remote
+layer registers exactly the methods a decorated class declares (typert writes
+its markers per instance, from the class that carries the decorators), the
+base service has no such method, and nothing in the plugin or in the harness
+calls it. Ranged reads already go through the wire op they always did —
+`readBytes` with `options.range`, which the distro branch serves and the host
+branch delegates. The method and its one test line are gone (the range case
+stays covered through `readBytes`), and one more expect-error goes with it:
+two remain, the exit-4 kind and the upstream spawn seam.
+
+## [0.7.5] - 2026-10-05
+
+One theme: a failed environment probe retries instead of being trusted
+forever - the shell placeholder that used to pin bash onto every later
+command, and the hardcoded distro name that minted UNC identities.
+
+### Fixed
+
+- **A failed shell probe no longer pins `bash` for the executor's
+  lifetime.** `defaultShell` reported the literal `"bash"` when both probes
+  failed - a cold distro, a flaky first `wsl.exe` call - and the executor
+  cached that placeholder permanently: every later command ran bash on a
+  zsh distro, and the shell tool introduced itself as bash. The probes now
+  answer `undefined`; the executor caches only a real resolution and falls
+  back to bash per call, so the next command retries. `shell-env` follows:
+  an unresolved shell simply omits the `DSH_WSL_SHELL` fact instead of
+  presenting a guess as the distro's login shell. Alongside, `toWorldPath`
+  no longer mints UNC identities under the hardcoded `"Ubuntu"` fallback -
+  the pinned distro is a required option now, and every caller passes it.
+
 ## [0.7.4] - 2026-10-05
 
 One theme: the 0.2.0 review's engineering debt closes out - the five

package/CONTRIBUTING.md

@@ -10,26 +10,115 @@ the conventions this repository uses.
 | Windows 10 or 11 | the plugin targets Windows only |
 | WSL2 with at least one distro | `wsl.exe -l -v` lists the installed distros |
 | `bubblewrap` in the distro | `sudo apt install bubblewrap`. The sandbox fails closed without it. |
-| Node 20, 22, or 24 | the versions CI runs. `engines` requires `>=20`. |
+| Node 22.19+, or 24 | the versions CI runs. `engines` requires `^22.19.0 \|\| >=24.0.0`, the harness host's own floor. |
 
 ## Toolchain
 
-The package has no dependencies, so there is no install step. Run the scripts
-straight from a checkout.
-
-`npm` runs the scripts in this repository, and CI uses npm. Treat
-`npm run <script>` as the reference toolchain.
-
-Do not add a runtime dependency. The package ships an empty `dependencies` object
-on purpose, because it is loaded into the DSH process and everything it needs
-arrives as a peer package.
-
-Style tooling is kept out for the same reason. There is no ESLint, no Prettier, and
-no `devDependencies` at all. The checks that would normally need them are built
-from Node builtins instead. `test/style.mjs` verifies the rules `.editorconfig`
-states, and it checks that every `files` entry still matches tracked content and
-every `exports` target still exists. The syntax pass inside `npm test` uses Node's
-own parser.
+The runtime package ships an empty `dependencies` object on purpose: it is
+loaded into the DSH process and everything it needs arrives as a peer package.
+Running the plugin from a checkout has no install step.
+
+Developing and running the gates do have dependencies. The 0.7.x tests import
+pinned `@deepseek-ai/*` packages — the composition and boot tests run the
+loader's real patch algorithm — so a fresh checkout needs one `pnpm install`
+before the gates pass.
+
+pnpm runs the scripts in this repository, pinned through the `packageManager`
+field (corepack resolves it). Treat `pnpm run <script>` as the reference
+toolchain.
+
+Do not add a runtime dependency — see above. Style tooling is kept out for the
+same reason: there is no ESLint and no Prettier. The checks that would normally
+need them are built from Node builtins instead. `test/style.mjs` verifies the
+rules `.editorconfig` states, and it checks that every `files` entry still
+matches tracked content and every `exports` target still exists. The syntax pass
+inside `pnpm test` uses Node's own parser.
+
+Exactly three dependencies run install scripts (`@deepseek-ai/dsh-subprocess-local`,
+`koffi`, `node-pty` — the native pieces); they are allow-listed in
+`pnpm-workspace.yaml` and everything else builds nothing.
+
+## The type gate
+
+`lint:types` runs `tsc --noEmit` under `strict` with `checkJs`: the JavaScript
+in `lib/` is fully type-checked, and the types come from the peer packages'
+own `.d.ts` — nothing is invented twice. `types/dsh-services.d.ts` pulls in the
+`declare module '@deepseek-ai/cordis'` augmentations the service packages ship,
+so `ctx.fs`, `ctx.shell`, `ctx.sandboxPolicy` and friends are typed; it declares
+nothing itself and ships nowhere.
+
+The gate's scope is what is NOT generated: `test/**` (the probe scripts
+included) and the ambient service types the build shares. The sources under
+`src/` are checked by the build program itself (`strict`, `noEmitOnError`),
+which is strictly stronger than checking their emitted JavaScript. The shipped
+artifact was checked first because it is where protocol drift with the pinned
+peers hurts; the tests and probes came next, and the errors they surfaced were
+real — a test that pinned a raw number into an argv, a couple of hand-written
+JSDoc contracts wider than the code (`wslErrorCode`, `gitSpawnRewrite`) and
+narrower than their seams, and one accepted-but-never-enforced byte-window cap
+in the distro-routed file service, found because a fake hands the confinement
+seam an `"full"` enforcement the core itself never reports.
+
+Three patterns keep the check honest:
+
+- A subclass's own config keys are declared as a type mirroring its
+  `static Config` schema and read through one explicit cast — the schema and
+  the type can then only drift apart visibly.
+- A test double is typed as the slice of the seam it scripts (a duck
+  `@typedef`) and reaches the seam's declared type through one documented cast
+  at the injection point — the cast states which contract the double stands in
+  for, instead of silencing the mismatch with `any`.
+- `@ts-expect-error` is allowed exactly when the suppressed error names a real
+  upstream seam gap, carries the reason inline, and the gap is written up in
+  `docs/UPSTREAM-*.md`. It is a published finding with a tracking doc, not a
+  silencer.
+
+## The build
+
+The plugin must be loadable from a bare checkout: the harness has no
+transpilation layer, the Windows runtime mirror is a copy of the tree, and the
+tests exercise `lib/*.js` — the published artifact — rather than the sources.
+Sources live in `src/`, built JavaScript and declarations in `lib/`, and the
+artifacts stay COMMITTED. `pnpm run build` (`scripts/build.mjs`) runs one pass —
+`tsc -p tsconfig.build.json` — emitting every `src/*.ts` as JavaScript plus its
+declaration under the same export paths as the hand-written modules it
+replaced. Imports name the artifact (`./x.js`); `nodenext` resolves that
+through the TypeScript source. The build then prunes declarations no source
+owns (a rename leftover), so `lib/` is exactly the artifacts of `src/`.
+
+Rules that keep this honest:
+
+- Never edit a generated file under `lib/` — its module doc names the source
+  to edit and `lint:build` fails the moment the two drift. Generated artifacts
+  keep tsc's canonical formatting (four-space, compacted); review `src/` for
+  every module.
+- `lint:build` (`test/build-freshness.mjs`) enforces that the corpus is closed
+  — every `lib/*.js` has its `src/<name>.ts`, every source has both artifacts —
+  then snapshots every generated file, runs the real build, byte-compares and
+  RESTORES the snapshot: a check, not a rebuild; the remedy for drift is
+  `pnpm run build` plus a commit. It is part of the gate chain after
+  `test:syntax`.
+- Generated files are not in the `checkJs` gate at all (`tsconfig.json` covers
+  `test/**` and the ambient types); their sources are type-checked by the build
+  program with `noEmitOnError`, so a broken build never overwrites `lib/`.
+- Every JavaScript export carries its `types` condition (enforced by
+  `lint:style`), so downstream resolves these declarations; there is no
+  second, hand-written type surface.
+- The protocol message union and friends are the single home now: consumers
+  import them (`@typedef {import("./agent-protocol.js").AgentMessage}
+  AgentMessage`) instead of restating them, which is how `lib/agent.js` and
+  the script-driven tests read them.
+
+### Adding a module
+
+1. Write `src/<name>.ts`; imports name the artifact (`./x.js`), which
+   `nodenext` resolves through the TypeScript source. Move every type into the
+   signature, keep the prose, and keep every exported NAME — types included,
+   since consumers import them (`import("./paths.js").DistroPath`). Close the
+   module doc with the note that names the generated artifact.
+2. `pnpm run build`, then `pnpm test`. There is no exclude list to maintain and
+   no registration step: the build and `lint:build` derive everything from
+   `src/`, and `lib/` is generated output — never edit it by hand.
 
 ## The development loop
 
@@ -50,7 +139,7 @@ The Windows copy under `default-workspace/dsh-plugin-wsl` is a runtime mirror. S
 it before launching the app:
 
 ```bash
-npm run sync:windows
+pnpm run sync:windows
 ```
 
 The mirror destination sits outside a session workspace. An agent that runs the
@@ -62,28 +151,29 @@ terminal if you would rather not see the prompt.
 
 | Command | Covers | Needs a harness |
 |---|---|---|
-| `npm test` | style checks, syntax pass, and unit tests | no |
-| `npm run test:coverage` | unit tests with coverage | no |
-| `npm run lint:style` | style and lint rules | no |
-| `npm run probe` | filesystem behaviour against a real distro | yes |
-| `npm run probe:sandbox` | what bubblewrap confines and what it does not | no |
-| `npm run probe:sandbox-shell` | the confined executor through a real boot | yes |
-| `npm run probe:terminal` | the terminal provider | yes |
-| `npm run probe:substrate` | the agent filesystem substrate over a real `wsl.exe` transport | yes; inside the distro |
-| `npm run probe:watch` | the in-distro watcher over a real directory | yes; inside the distro |
-| `npm run probe:agent` | the resident-vs-one-shot fallback parity legs | yes; inside the distro |
-| `npm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | yes; inside the distro |
-| `npm run probe:missing-wsl` | how a `wslPath` that cannot start is reported | yes |
-| `npm run probe:picker` | the picker's root level, its refusals and its cap | yes |
-| `npm run probe:mode` | which POSIX-mode facts survive the share | no; Windows Node |
-| `npm run probe:sandbox-off` | the documented opt-out on both providers | yes |
-
-Every script above is wired in `package.json`. `npm test` runs `lint:style`,
-`test:syntax` and `test:unit` in that order. `prepublishOnly` runs `npm test` again
+| `pnpm test` | style checks, syntax pass, type check, and unit tests | no |
+| `pnpm run test:coverage` | unit tests with coverage | no |
+| `pnpm run lint:style` | style and lint rules | no |
+| `pnpm run lint:types` | the TypeScript check over `lib/` (`tsc --noEmit`) | no |
+| `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 |
+| `pnpm run probe:terminal` | the terminal provider | yes |
+| `pnpm run probe:substrate` | the agent filesystem substrate over a real `wsl.exe` transport | yes; inside the distro |
+| `pnpm run probe:watch` | the in-distro watcher over a real directory | yes; inside the distro |
+| `pnpm run probe:agent` | the resident-vs-one-shot fallback parity legs | yes; inside the distro |
+| `pnpm run probe:exec` | the agent-backed execution handle: timeout, kill, cwd failure | yes; 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: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: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.
 
-CI runs `npm test` on Node 20, 22 and 24, on both `ubuntu-latest` and
-`windows-latest`, and `npm run test:coverage` on Node 24. The Windows runners are
+CI runs `pnpm test` on Node 22 and 24, on both `ubuntu-latest` and
+`windows-latest`, and `pnpm run test:coverage` on Node 24. The Windows runners are
 there because the plugin targets Windows; the coverage thresholds need Node 22.8 or
 newer, which is why that job runs on one version.
 
@@ -117,7 +207,7 @@ start, because a leftover file from an earlier run changes the result.
 
 ## What has been verified
 
-`npm test` covers the pure modules and runs a `--check` pass over every shipped
+`pnpm test` covers the pure modules and runs a `--check` pass over every shipped
 module. It cannot import the service modules, because those need DSH peer packages
 that a bare checkout does not have. Only booting the harness closes that gap, which
 is why the probes exist; the archived record's §15.4 documents the five rounds of

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**: 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).
+You also need **bubblewrap inside the distro**: run `pnpm 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.
 
@@ -73,7 +73,7 @@ Override a row by id in `$DSH_HOME/profiles/<name>/cordis.patch.yml`. The keys w
 - **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
+  distro filesystem. `pnpm run bootstrap -- <distro>` also reports whether
   ripgrep, git and inotifywait (the search, snapshot 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
@@ -114,7 +114,7 @@ Commands are confined by `bubblewrap` inside the distro, and file writes are che
 
 **`bubblewrap` is required, and it fails closed.** Without it every confined command reports `SANDBOX_UNAVAILABLE` instead of running unconfined. Set `sandbox: false` on either provider to opt out; the tool layer then tells the model these operations have no sandbox.
 
-**The reported enforcement is `partial`, not `full`.** A process inside the distro can still run a Windows program through WSL interop, for example `/mnt/c/.../*.exe`, and bubblewrap does not govern it. `npm run probe:sandbox` demonstrates the boundary on your machine.
+**The reported enforcement is `partial`, not `full`.** A process inside the distro can still run a Windows program through WSL interop, for example `/mnt/c/.../*.exe`, and bubblewrap does not govern it. `pnpm run probe:sandbox` demonstrates the boundary on your machine.
 
 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.
 
@@ -122,37 +122,37 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [do
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| 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 |
+| every command reports `SANDBOX_UNAVAILABLE` | `bubblewrap` is not installed in the distro | run `pnpm 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 |
 | the terminal still opens `cmd.exe` | the `terminal-controller` row from the layer did not apply | check that `dsh --profile wsl --dump-config` shows `shell: { path: wsl.exe, name: WSL }` |
 | changes to `lib/` have no effect | ES module cache | restart the app |
 | `link:\\wsl.localhost\...` leaves a broken symlink | pnpm cannot link a UNC path | link a Windows path instead; developing inside the distro needs the runtime mirror, see [Development](#development) |
-| `glob` and `grep` are slow | a distro search without rg inside the distro falls back to rg's own "command not found"; a Windows-folder search is native and unaffected | run `npm run bootstrap -- <distro> --install` (installs ripgrep); distro searches always run the distro's rg — they never walk the 9p share |
+| `glob` and `grep` are slow | a distro search without rg inside the distro falls back to rg's own "command not found"; a Windows-folder search is native and unaffected | run `pnpm run bootstrap -- <distro> --install` (installs ripgrep); distro searches always run the distro's rg — they never walk the 9p share |
 | the terminal reports `unknown` activity | only while the resident agent is out — distro terminals are observed from inside the distro (a `DSH_TERMINAL_ID` marker scanned in `/proc`: a shell alone is `idle`, a shell running anything is `busy`) | check the distro is running; idle terminals are reclaimed automatically after the controller's unattended timeout (2 h by default), and `terminalIdleReclaim: false` restores the close-by-hand posture |
 | a result names an `FS_*` code | the code says what refused it, and what clears it | see the error-code table in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#error-codes) |
 
 ## Development
 
 ```bash
-npm test                     # style and packaging checks, syntax check, unit tests
-npm run test:coverage        # the unit tests with coverage thresholds (Node 22.8+)
-npm run probe:sandbox        # measure inside the distro what bubblewrap does and does not confine
-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:watch          # arm the in-distro watcher over a real directory (from inside the distro)
-npm run probe:agent          # the resident-vs-one-shot fallback parity legs (from inside the distro)
-npm run probe:exec           # the agent-backed execution handle: timeout, kill, cwd failure (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)
-npm run probe:sandbox-off    # prove sandbox: false unconfines both providers (Windows + WSL only)
+pnpm test                     # style and packaging checks, syntax check, unit tests
+pnpm run test:coverage        # the unit tests with coverage thresholds (Node 22.8+)
+pnpm run probe:sandbox        # measure inside the distro what bubblewrap does and does not confine
+pnpm run probe                # filesystem probe against a real distro (Windows + WSL only)
+pnpm run probe:sandbox-shell  # boot a real harness and drive the confined executor
+pnpm run probe:terminal       # open a PTY through the terminal provider
+pnpm run probe:substrate      # drive the agent filesystem substrate over a real wsl.exe transport (from inside the distro)
+pnpm run probe:watch          # arm the in-distro watcher over a real directory (from inside the distro)
+pnpm run probe:agent          # the resident-vs-one-shot fallback parity legs (from inside the distro)
+pnpm run probe:exec           # the agent-backed execution handle: timeout, kill, cwd failure (from inside the distro)
+pnpm run probe:missing-wsl    # boot a profile whose wslPath cannot start (Windows + WSL only)
+pnpm run probe:picker         # list the picker's root level, refusals and its cap (Windows + WSL only)
+pnpm run probe:mode           # which POSIX-mode facts survive the share (Windows node only)
+pnpm run probe:sandbox-off    # prove sandbox: false unconfines both providers (Windows + WSL only)
 ```
 
-There is nothing to install first: the package has no dependencies, and every module under test imports only Node builtins. CI runs `npm test` on Node 20, 22 and 24, on Linux and Windows, and `npm run test:coverage` on Node 24.
+One `pnpm install` reproduces the pinned development dependencies before the first run: the 0.7.x tests import pinned `@deepseek-ai/*` packages (the composition and boot tests exercise the loader's real patch algorithm), while the runtime package itself still ships zero dependencies. pnpm is resolved through the `packageManager` field, so any corepack-enabled Node works. CI runs `pnpm test` on Node 22 and 24, on Linux and Windows, and `pnpm run test:coverage` on Node 24; `engines` matches the harness host's own floor (`^22.19.0 || >=24.0.0`).
 
 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) has the file layout, the mounting, and the sandbox design. [CONTRIBUTING.md](CONTRIBUTING.md) has the development loop, the full gate list, and what has been verified.
 

package/docs/ARCHITECTURE.md

@@ -185,7 +185,7 @@ selector read that value.
 distro can still run a Windows program through WSL interop, for example
 `/mnt/c/.../*.exe`. Bubblewrap does not govern that process.
 
-`npm run probe:sandbox` demonstrates the boundary on your machine and records it as
+`pnpm run probe:sandbox` demonstrates the boundary on your machine and records it as
 `INFO`.
 
 ### Failure mode
@@ -250,7 +250,7 @@ distro checkout.
 
 The Windows copy at `default-workspace/dsh-plugin-wsl` is a runtime mirror.
 [`test/probe/sync-to-windows.sh`](../test/probe/sync-to-windows.sh) keeps it in
-step with the checkout, and `npm run sync:windows` runs that script.
+step with the checkout, and `pnpm run sync:windows` runs that script.
 
 ## Test layers
 
@@ -306,12 +306,15 @@ docs/               this file, the configuration and limitation references, the
 ```
 
 `package.json` publishes a subset of this tree: the `files` list is the contract, and
-`npm run lint:style` fails if an entry stops matching tracked content.
+`pnpm run lint:style` fails if an entry stops matching tracked content.
 
 ## Where the reasoning lives
 
 - [`CHANGELOG.md`](../CHANGELOG.md) records what changed in each release. It also
   names the documentation a reader would have acted on that is no longer true.
+- [`REQUIREMENTS.zh.md`](REQUIREMENTS.zh.md) is the requirements register: every
+  documented behaviour commitment numbered, with where it is specified and what
+  verifies it, plus the open items (Chinese, maintainer-facing, not packaged).
 - [`archive/engineering-record.zh.md`](archive/engineering-record.zh.md) is the
   full engineering record, in Chinese: measured contracts, debugging rounds, and
   the conclusions as they stood then.