dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/CHANGELOG.md

@@ -7,11 +7,340 @@ All notable changes to this project are documented here. The format follows
 The reasoning and the measurements behind each entry are in the archived
 engineering record,
 [docs/archive/engineering-record.zh.md](docs/archive/engineering-record.zh.md)
-(Chinese, repository only — it is history, never a second README). Every `§`
-reference below points at that record's numbering.
+(Chinese, repository only — it is history, never a second README). A `§`
+reference below points at that record's numbering unless it names another
+document: the 0.1.0 entry's `design-history §` references are to
+[docs/archive/design-history.zh.md](docs/archive/design-history.zh.md), which
+keeps the superseded designs under the section numbers they had while they
+were part of the record.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-06
+
+A usability round over the sandbox failure path: the failure stops being a
+wall the first command walks into, and becomes a message that arrives early
+and says how to fix it.
+
+The bwrap refusal now classifies its cause — missing versus
+present-but-failing — and prints the direct install command in the distro's
+own package family (apt/dnf/pacman/zypper) instead of a hardcoded `apt-get`
+line; every consumer composes it from one place. A new `wsl-preflight`
+service runs the same shared probe when a distro session opens and surfaces
+an unusable bwrap as a warning with the full remedy, moving the discovery
+moment ahead of the first failed command — advisory only, never installing.
+`pnpm run diagnose` collects a read-only, paste-ready diagnostic report for
+issues, and the three bare wsl-probe failures (no distro, no `$HOME`, no
+shell) now carry their next steps. The agent probe's parity legs classify
+the nested-interop service timeout (`Wsl/Service/WSAETIMEDOUT`, observed on
+WSL 3.0.1.0) as SKIP with the evidence attached, so an environment failure
+that prevents the comparison reads as what it is instead of a parity
+violation.
+
+## [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.
+
+The unit suite also takes on the integration layer. `test/provider.test.mjs`
+boots the REAL `WslShellExecutor` and `WslFileSystem` with substitutes only at
+the seams that would reach `wsl.exe` — the agent, the substrate, the
+confinement — so the guard chain, the mutation routing, the agent execution
+path with its result decoration, the one-shot fallback and the runner-failure
+remap are measured: `lib/index.js` goes from 60% lines / 9% functions covered
+to 97%/90% when it joins, and measures 97.49% lines / 95.16% functions in the
+released tree. The coverage gate's branch threshold moves with it, 85 to 84 —
+the newly measured layer's uncovered tail is the distro-resolution branches
+(`defaultDistro`'s no-distro throw, `linuxHomePath`'s refusals, the watcher's
+real spawn internals) that need a live `wsl.exe`, and RELEASING.md records
+the bar for raising it again: cover that tail on the Windows CI legs, or move
+the coverage job to `windows-latest`. And the probes join CI: a
+`workflow_dispatch` job — named for the self-hosted Windows runner, though it
+carries the hosted `windows-latest` label — runs five of them: `sandbox`
+unconditionally, since it needs only bubblewrap in the default distro, then
+`mode`, `terminal`, `picker` and `missing-wsl` where the harness app is
+present. The `sandbox` leg fails, not skips, where bubblewrap is absent, so a
+dispatch to a hosted runner is no green no-op. Separately,
+`test/probe/run-all-when-closed.sh`'s suite gains the four probes it was
+missing — `agent`, `watch`, `substrate`, `exec`.
+
+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 — a scope that narrows to what is
+NOT generated once the migration completes, `lib/**` leaving the gate for the
+build program below — 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 — the `exclude` step lasts only while the tree is
+mixed; the finished checklist ends at write, build and test, with no list to
+maintain.
+
+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 35-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
@@ -717,6 +1046,17 @@ overwrite guard that stopped at the host.
   app's own runtime, both entries import; `test/syntax.mjs` now checks every
   `z.<member>` in `lib/` against the pinned peer's surface, which fails on
   `z.enum` and passes on `z.union`.
+
+## [0.2.0] - 2026-10-03
+
+One theme: the Remote-WSL parity plan (`docs/PARITY.md`) lands, Phases 0–7 —
+a resident in-distro agent plus the shell-execution, watch, publication,
+ports, terminal-routing and bootstrap work that migrates the seams onto it.
+The release closes with the two agent-path breaks that took down every GUI
+shell call, both surfacing only through the GUI's wire protocol.
+
+### Fixed
+
 - **`truncated` missing from the agent path's output streams** — the bash tool's
   canonical result copies the field unconditionally (`canonicalBashResult`), so an
   `undefined` failed the wire's lossless-JSON snapshot and EVERY shell tool call
@@ -799,9 +1139,6 @@ overwrite guard that stopped at the host.
   Probed end-to-end against a real distro: `test/probe/agent.sh` (8 checks, including
   binary-safe payloads, an in-distro timeout kill, and a 2 MB single-line response).
   Unit tests cover the codecs and the lifecycle state machine with a fake transport.
-
-### Added
-
 - `docs/PARITY.md`: the plan to reach VS Code Remote-WSL-grade experience — a resident
   in-distro agent as the core, with the `fs` and `shell` seams migrated onto it and the
   current 9p/one-shot paths kept as the documented fallback — plus the Phase-0 contract
@@ -1343,9 +1680,9 @@ freshly created files.
 - Three peer declarations this plugin neither imports nor injects:
   `@deepseek-ai/dsh-sandbox`, `@deepseek-ai/dsh-shell` and
   `@deepseek-ai/dsh-tools`. They were required by the abandoned tool-renaming
-  designs (archive §15/§18), which could only stub the sandbox symbols locally
-  (archive §15.5). The remaining set is checkable in one command —
-  `grep -rho 'from "@deepseek-ai/[^"]*"' lib/ | sort -u` — plus
+  designs (design-history §15/§18), which could only stub the sandbox symbols
+  locally (design-history §15.5). The remaining set is checkable in one
+  command — `grep -rho 'from "@deepseek-ai/[^"]*"' lib/ | sort -u` — plus
   `@deepseek-ai/dsh-subprocess` (the service `static inject` requires) and
   `@deepseek-ai/cordis`, which every DSH plugin declares.
   (`@deepseek-ai/dsh-sandbox` came back in this same release: the distro-side