dsh-plugin-wsl-env 0.15.0 → 0.17.0

package/docs/ROADMAP-1.0.md

@@ -1,11 +1,21 @@
 # Roadmap 1.0: the WSL plugin the DSH ecosystem should have
 
-Status: working plan, 2026-10-19. Baseline: `0.12.0`.
+Status: working plan, last refreshed 2026-10-31 against `0.15.0`.
+The 0.12.0 baseline that motivated the plan is kept below as history.
 Audience: maintainers and contributors. This is a plan, not a release promise.
 The short version: **from "the only WSL plugin" to "the default WSL plugin"** —
 first run works, every distro and workspace is served by its own environment,
 every DSH surface has a story, and every claim has a test or a probe.
 
+## 0. 核心价值（需求裁决标准）
+
+本插件只做两件事，其余一切都是为这两件事服务的适配：
+
+1. **原生 Linux 工具链，LLM 生成的质量更高。** 模型在正确的生态里生成与执行——bash 而非 PowerShell、GNU 工具链、项目真实的构建系统。凡能让 distro 内工具链更完整、对模型更可见的，直接服务此价值（doctor 工具链检查、bootstrap-import、六发行版矩阵）。
+2. **避开 Windows 与 WSL 的跨环境文件操作，大幅提升性能。** 每一次跨 9p/UNC 边界的文件操作都是性能税。凡消除或减少跨界往返的，直接服务此价值（picker 的 agent 化、#31 批量读、workspace-changes 的 git 经 `ctx.subprocess` 在 distro 内原生运行——已与上游实现对账）。
+
+任何新提案先用这两条裁决：不服务者不进路线图。
+
 ## 1. What "must-have" means
 
 "Best" is not "most features". It is five acceptance lines:
@@ -34,25 +44,41 @@ North-star metrics:
 | Real-machine probe suite | 100% on Tier 1, nightly |
 | Known documentation drift | 0 |
 
-## 2. Where 0.12.0 stands
+## 2. Where 0.15.0 stands
+
+> WSL-101 landed on 2026-10-19: the distro follows the workspace and the
+> per-distro caches are in place. 0.15.0 (2026-10-27) shipped the compatibility
+> matrix, container legs, qemu aarch64, doctor, preset helper, and
+> `interopVisibility`. The table that *motivated* the plan is frozen as the
+> 0.12.0 baseline; the 0.15.0 row is what a reader should act on.
 
-> WSL-101 is implemented in the working tree (2026-10-19): the distro follows the
-> workspace and the per-distro caches are in place. The table below records the
-> 0.12.0 baseline that motivated the plan.
+### 0.15.0 (current)
 
-| Area | Strong today | Gap to "must-have" |
+| Area | Strong today | Remaining gap |
 |---|---|---|
-| Execution | Native agent is the default; systemd session scope; background processes survive | The distro is pinned by configuration. The picker lists every distro, but a workspace in a non-default distro hits the cross-distro guard ([`src/index.ts:838`](../src/index.ts), [`src/paths.ts:227`](../src/paths.ts)) |
-| Files | ext4 substrate, root-plane `fs-routing`, kernel-enforced confined writes | GUI previews take roughly four to six agent round trips ([`LIMITATIONS.md:122`](LIMITATIONS.md)); `@` completion still reads through 9p |
-| Sandbox | `bubblewrap`, fail-closed, honest `enforcement: partial`, `maskWindowsDrive` | systemd and Linger are default prerequisites, but neither `diagnose` nor `bootstrap` checks them |
-| Onboarding | `bootstrap`, `diagnose`, session-start preflight, package-family install commands | No single "check and fix" command; the preflight only probes bwrap; the preset override is a trap |
-| Configuration | Every shipped key is documented | `wsl-shell` and `wsl-fs` are nested in `preset-wsl`; an id patch only logs a warning and changes nothing ([`CONFIGURATION.md:64`](CONFIGURATION.md)) |
-| Quality | 33 unit-test files, 12 real-machine probes, build/type/coverage gates | Probes are manual; aarch64 is build-only ([`ROADMAP.md:45`](ROADMAP.md)); `fs-routing` is outside `test:unit`/`test:coverage` ([`REQUIREMENTS.zh.md:72`](REQUIREMENTS.zh.md)) |
-| Ecosystem | npm package, bundle patch, bilingual locale, substantial docs | The upstream seams are fragile: the `ensureSession` monkey patch, argv-shape search interception, and the missing `FileReferenceTraversal` seam ([`upstream/promotion-map.md`](upstream/promotion-map.md)) |
-
-The engineering base is already in the top tier of comparable projects. The
-remaining gap is productization: **multi-distro correctness, first-run
-friction, configuration ergonomics, and ecosystem presence**.
+| Execution | Native agent default; systemd session scope; `distro: auto` coordinate routing; concurrent distros | Physical aarch64 WSL (out of scope); non-systemd real-machine session probe unrun |
+| Files | in-distro agent substrate, root-plane `fs-routing` in unit+coverage, kernel-enforced confined writes | GUI previews still extra agent round trips (measured, deferred); `@` completion still 9p until the upstream seam |
+| Sandbox | `bubblewrap`, fail-closed, `enforcement: partial`, `interopVisibility` / `maskWindowsDrive` | Plugin keys do not disable WSL interop; distro `[interop] enabled=false` must be configured separately |
+| Onboarding | `doctor`, `bootstrap` / `bootstrap-import`, session preflight, `profile-preset` helper | Clean-machine first-run timing still unmeasured; session UI has no toast seam |
+| Configuration | Every shipped key documented; nested `preset-wsl` rows edited through the helper | An id patch of `wsl-shell` / `wsl-fs` still only warns |
+| Quality | Unit files including `fs-routing`; coverage 85/84/70; qemu aarch64 18-check; five-family container agent; COMPATIBILITY.md | Nightly `probes` job is GitHub-hosted `windows-latest` (skips without WSL); physical aarch64 out of scope |
+| Ecosystem | npm package, bundle patch, bilingual locale, issue templates | Upstream seams remain: `ensureSession` monkey patch, argv-shape search interception, missing `FileReferenceTraversal` |
+
+### 0.12.0 baseline (historical)
+
+| Area | Strong then | Gap that motivated the plan |
+|---|---|---|
+| Execution | Native agent is the default; systemd session scope; background processes survive | Distro pinned by configuration; non-default workspace hit the cross-distro guard |
+| Files | ext4 substrate, root-plane `fs-routing`, kernel-enforced confined writes | GUI extra round trips; `@` completion through 9p |
+| Sandbox | `bubblewrap`, fail-closed, honest `enforcement: partial`, `maskWindowsDrive` | systemd and Linger unchecked by diagnose/bootstrap |
+| Onboarding | `bootstrap`, `diagnose`, session-start preflight | No single doctor; preflight only probed bwrap; preset override trap |
+| Configuration | Every shipped key documented | Nested `preset-wsl` rows; an id patch warned and changed nothing |
+| Quality | 33 unit-test files, 12 real-machine probes, build/type/coverage gates | Probes manual; aarch64 build-only; `fs-routing` outside `test:unit` / `test:coverage` |
+| Ecosystem | npm package, bundle patch, bilingual locale | Fragile upstream seams (same three as today) |
+
+The remaining gap after 0.15.0 is **upstream seams, honest probe collection,
+and 1.0 empirical legs** (clean-machine timing, 30 days without a P0) — not
+the 0.12.0 productization list.
 
 ## 3. Design principles
 
@@ -141,12 +167,12 @@ may move if the compatibility matrix exposes a higher-severity failure.
 |---|---|---|---|
 | Time to first command | Not systematically measured | p50 <= 5 min, p90 <= 15 min | Ten clean-machine runs |
 | Tier 1 first-run success | Not measured | >= 95% | Compatibility matrix |
-| Real-machine probes | 14, manual | 100%, nightly | Self-hosted Windows runner |
+| Real-machine probes | 15 with `--include-fs` (14 base scripts incl. `fs-routing.sh`, plus `run.sh`); nightly job on hosted `windows-latest` skips without WSL | 100% on a Windows+WSL runner | Dispatch or a self-hosted runner that actually has WSL |
 | FS single-op p95 | ~22ms host round trip | <= 30ms | `fs-queue.mjs` |
 | 16 concurrent reads p95 | 2.4-8.2ms | <= 20ms | `fs-queue.mjs` |
 | GUI preview p95 | Backend 63.5 ms/MiB (service round trips on top) | <= 1s/MiB | `probe:gui-preview` |
 | Agent recovery | One rebuild | < 2s | Fault injection |
-| Documentation drift | Three known | 0 | Release checklist |
+| Documentation drift | Closed 2026-10-30 (aarch64 qemu, 0.15 baseline, WSL-202 boxes) | 0 | Release checklist |
 | Release cadence | Ad hoc | Every 2-4 weeks | Calendar |
 | Adoption (lagging) | Not established | +50% per quarter | npm download stats |
 
@@ -187,8 +213,13 @@ acceptance list in each issue is the contract; filter by priority:
 
 ### WSL-101 — Multi-distro coordinate routing
 
-**Status:** implemented in the working tree (2026-10-19); unit-covered, with the
-real-machine two-distro probe still to run.
+**Status:** shipped in 0.13.0 (2026-10-19), unit-covered. The
+`fs-routing.sh` probe (added with P0.4) runs on the real machine: it serves a
+workspace in its own distro, reads a drive-letter path on the host plane, and
+refuses another distro's UNC — one leg of the acceptance below has real-machine
+evidence (a 2026-10-31 run passed all 15 probes on one machine; not a matrix
+result). The concurrent two-distro leg still has no dedicated probe and has
+not been run; the checkboxes stay unchecked until that leg exists.
 
 **Priority:** P0 · **Size:** L · **Labels:** `area:multi-distro`,
 `type:feature`, `priority:P0`
@@ -245,7 +276,7 @@ current diagnostics do not cover the second.
       run on this single configured machine).
 
 **Tests/probes:** process-level tests against fake `wsl.exe` outputs
-([`test/doctor.test.mjs`](../test/doctor.test.mjs)); real-machine run on the
+([`test/doctor.test.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/doctor.test.mjs)); real-machine run on the
 Tier 1 image; `diagnose` remains a read-only alias.
 
 **Depends on:** none.
@@ -279,7 +310,7 @@ failure.
 
 **Tests/probes:** generated YAML compared byte-for-byte against the shipped
 block (the row the real composition loads); the CLI's print/write/check paths
-run in [`test/profile-preset.test.mjs`](../test/profile-preset.test.mjs).
+run in [`test/profile-preset.test.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/profile-preset.test.mjs).
 
 **Depends on:** none.
 
@@ -288,8 +319,10 @@ run in [`test/profile-preset.test.mjs`](../test/profile-preset.test.mjs).
 **Status:** implemented (2026-10-19): the three drifts are fixed, `fs-routing`
 and `distro-route` are in both test lists, `scripts/check-links.mjs` gates
 relative links from `pnpm test`, and `probe:fs-routing` is written and wired
-into the real-machine suite. The routing probe has not been executed yet (it
-needs the app closed); its first run stays on the release checklist.
+into the real-machine suite. The routing probe's first real-machine run
+happened by 2026-10-31 (a user-supplied log shows the full `--include-fs`
+suite, 15 probes, 0 failures on one machine — an environment-specific result,
+not a matrix).
 
 **Priority:** P0 · **Size:** S · **Labels:** `area:docs`, `area:quality`,
 `priority:P0`
@@ -323,15 +356,15 @@ remedy for `no-systemd`, `no-user-manager`, `no-systemd-run` and `no-linger`
 (`sessionSandbox: false` on the row skips the session half). The advisory is
 logged **and** published as a session-scoped `wsl-preflight` runtime-context
 entry, so it is visible in the session transcript rather than only in the app
-log. DSH 0.2.1 has no toast/banner seam; the exact ask is written up (not yet
-filed — no issue channel here) in
+log. DSH 0.2.1 has no toast/banner seam; the exact ask was filed as
+[#10263](https://github.com/deepseek-ai/deepseek-harness/discussions/10263) and is recorded in
 [UPSTREAM-SESSION-NOTICE.md](UPSTREAM-SESSION-NOTICE.md), and
 [LIMITATIONS.md](LIMITATIONS.md#session-start-advisories) records the boundary.
 Unit coverage drives every probe verdict through a fake `wsl.exe`; the
 real-machine missing-bwrap and non-systemd legs are still manual.
 
-**Why:** The session-start preflight currently only probes bwrap and writes to
-`logger.warn`; the other default prerequisite is discovered at the first
+**Why:** Before this work, session-start preflight only probed bwrap and wrote
+to `logger.warn`; the other default prerequisite was discovered at the first
 command.
 
 **Acceptance:**
@@ -391,20 +424,30 @@ probe remains unrun (no non-systemd distro here).
 **Priority:** P1 · **Size:** L · **Labels:** `area:compatibility`,
 `area:quality`, `priority:P1`
 
-**Why:** The support matrix is prose, and the aarch64 binary is built but never
-executed.
+**Status:** implemented (0.15.0 / 2026-10-27) except the scope decisions in
+[COMPATIBILITY.md](COMPATIBILITY.md#scope-decisions): physical aarch64 WSL and
+a separate Windows 10 matrix are out of scope; the non-systemd real WSL
+terminal-session legs remain unrun (Alpine is covered for the in-distro
+suite and `sessionSandbox: auto`).
+
+**Why:** The support matrix used to be prose, and the aarch64 binary was built
+but never executed.
 
 **Acceptance:**
 
-- [ ] Tier 1 and Tier 2 are defined and tested: Ubuntu LTS, Debian stable,
-      Fedora, Arch, Alpine (musl), openSUSE; systemd and non-systemd;
-      x86_64 and aarch64; Windows 10/11; current WSL.
-- [ ] The native 18-check suite runs for aarch64 under qemu in CI.
-- [ ] The shell agent runs in Linux containers for the non-Ubuntu families.
-- [ ] The support table states "supported", "partial" and "unsupported" with
-      evidence.
+- [x] Tier 1 and Tier 2 are defined and tested on x86_64 WSL2 / Windows 11:
+      Ubuntu, Debian stable, Fedora, Arch, Alpine (musl), openSUSE; systemd
+      and non-systemd (Alpine). Evidence: [COMPATIBILITY.md](COMPATIBILITY.md).
+- [x] The native 18-check suite runs for aarch64 under qemu in CI (built
+      artifact and committed `linux-aarch64` binary).
+- [x] The shell agent runs in Linux containers for the non-Ubuntu families
+      (`agent-containers` job, 35/35).
+- [x] The support table states "supported", "partial" and "unsupported" with
+      evidence (COMPATIBILITY.md). Physical aarch64 and Windows 10 are
+      documented as out of scope rather than untested claims.
 
-**Tests/probes:** container matrix, qemu spike, self-hosted nightly.
+**Tests/probes:** container matrix, qemu spike, COMPATIBILITY.md; nightly
+`probes` job is GitHub-hosted `windows-latest` and skips without WSL.
 
 **Depends on:** WSL-201 for non-systemd; WSL-203 for packaging.
 
@@ -413,7 +456,7 @@ executed.
 **Priority:** P1 · **Size:** M · **Labels:** `area:release`,
 `area:quality`, `priority:P1`
 
-**Status:** implemented (2026-10-19): [`test/e2e/install.sh`](../test/e2e/install.sh)
+**Status:** implemented (2026-10-19): [`test/e2e/install.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/e2e/install.sh)
 (`pnpm run e2e:install`) packs the tree, creates a fresh `DSH_HOME` under
 `%TEMP%`, initializes a profile from the shipped `web` template, installs the
 tarball, asserts `--dump-config` composes the plugin rows with no skipped-patch
@@ -422,7 +465,7 @@ installs the previous minor (0.11.0), plants a marker in the profile layer,
 upgrades to the packed version, and asserts the marker survives, the installed
 version is current, and the installed CHANGELOG carries the migration note.
 The run passed 10/10 on this machine (the app may stay running: plugin
-management is local). [`test/packaging.test.mjs`](../test/packaging.test.mjs)
+management is local). [`test/packaging.test.mjs`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/packaging.test.mjs)
 guards the packed file list in `pnpm test`. A self-hosted Windows runner job is
 still unconfigured; the local command is the documented path.
 
@@ -453,8 +496,8 @@ silently leave an obsolete workaround behind.
 cost (20 dirs / 520 files: 9p walk median 84.7 ms vs ext4 1.5 ms, ~56×; 9p
 samples 63–192 ms) measured by `pnpm run probe:file-reference`. The seam
 contract (three functions, Dirent/error/coordinate semantics) is already
-written in [rfc-wsl-workspaces.md](upstream/rfc-wsl-workspaces.md); the
-consumer [`src/file-reference-wsl.ts`](../src/file-reference-wsl.ts) is built
+written in [rfc-wsl-workspaces.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/upstream/rfc-wsl-workspaces.md); the
+consumer [`src/file-reference-wsl.ts`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/src/file-reference-wsl.ts) is built
 and unit-tested but deliberately unwired. The fallback is to keep the 9p walk
 until upstream exposes the funnel; the trigger and the follow-up probe are
 recorded.
@@ -511,7 +554,7 @@ no prototype while the trigger is unmet.
 **Priority:** P1 · **Size:** M · **Labels:** `area:performance`,
 `area:gui`, `priority:P1`
 
-**Status:** implemented (2026-10-19): [`test/probe/gui-preview.sh`](../test/probe/gui-preview.sh)
+**Status:** implemented (2026-10-19): [`test/probe/gui-preview.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/gui-preview.sh)
 (`pnpm run probe:gui-preview`) measures the three routed backend operations a
 preview pays — `stat`, `listDir`, and a 1 MiB `readByteRange` — with p50/p95 and
 budgets (stat 100 ms, listing 500 ms, page 1 s/MiB). Measured on this machine
@@ -578,7 +621,7 @@ mismatch); a real-machine kill/restart probe is still unrun.
 `area:docs`, `priority:P1`
 
 **Status:** implemented except the distro-disabled leg (2026-10-19):
-[CONFIGURATION](../docs/CONFIGURATION.md#the-strict-profile) documents the strict
+[CONFIGURATION](../docs/CONFIGURATION.md#windows-interop) documents the strict
 profile, its trade-offs and the visible/masked/disabled matrix;
 `pnpm run probe:sandbox` now also runs the masked profile (14 expectations:
 `/mnt` hidden, the Windows binary unreachable, the workspace still writable). The
@@ -620,8 +663,8 @@ workflow itself has not run in this environment (no Actions runner here), and
 opening an issue on a red run was left out because the workflow has no issue
 permission — the failing run plus its delta is the signal.
 
-**Why:** The peer pins are exact; a DSH release can break the plugin before a
-user reports it.
+**Why:** The development peer pins are exact, while accepted peer ranges can
+admit newer releases; a DSH release can break the plugin before a user reports it.
 
 **Acceptance:**
 
@@ -647,7 +690,7 @@ user reports it.
 fragile parts.
 
 **Status:** packaging plan written (2026-10-19):
-[docs/upstream/promotion-pack.md](upstream/promotion-pack.md) records the
+[docs/upstream/promotion-pack.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/upstream/promotion-pack.md) records the
 `packages/wsl/*` layout (ten capability packages plus a thin integration
 package, each with its existing tests), the seam/RFC index with the current
 state of each seam, what `test/composition.test.mjs` boots today and the gaps a
@@ -683,18 +726,17 @@ install, first session, recipes for Node/Python/Rust/Go and a monorepo, an
 honest Tier 1/Tier 2 table); [docs/PERFORMANCE.md](PERFORMANCE.md) is the
 9p-vs-agent page with the A6/A7 numbers and the GUI-preview baseline, and
 `pnpm run probe:gui-preview` / `fs-queue.mjs` reproduce the latter. No GIF or
-screenshot exists yet (capturing the GUI is not something this repository has
-recorded), so that acceptance item is explicitly open. No DSH plugin
+screenshot existed on 2026-10-19. Four screenshots were added on 2026-10-27;
+a GIF remains open. No DSH plugin
 marketplace was identified, so nothing was submitted.
 
 **Why:** "Best" also means easy to find and evaluate.
 
 **Acceptance:**
 
-- [x] A one-page entry with a five-minute quickstart, compatibility table and
-      screenshots (text only; screenshots are the open item).
-- [ ] A demo or GIF showing the picker, terminal, preview and sandbox fact
-      (not produced; recorded here and in QUICKSTART).
+- [x] A one-page entry with a quickstart, compatibility table and screenshots.
+      The five-minute clean-machine target remains unmeasured.
+- [ ] A GIF showing the picker, terminal, preview and sandbox fact.
 - [x] Recipes for Node, Python, Rust/Go and a monorepo; a 9p-vs-plugin
       benchmark page.
 - [ ] The DSH plugin directory/marketplace is updated if one exists (none
@@ -741,17 +783,19 @@ removals need a boot-time refusal, meaning changes need a migration note; exact
 peer pins are tested by the canary), the deprecation path with the
 `substrate: "share"` and `distro: ''` cases, and the release-gate table with the
 manual legs marked unrun. RELEASING and SUPPORT link it. The empirical legs
-(Tier 1 matrix, aarch64 execution, 30 days without a P0) and the final `1.0.0`
-release notes remain open.
+(clean-machine first-run timing, 30 days without a P0) and the final `1.0.0`
+release notes remain open. The Tier 1 matrix and aarch64 qemu execution
+closed in 0.15.0.
 
 **Acceptance:**
 
 - [x] Configuration schema frozen; new keys require a minor.
 - [x] Migration and deprecation policy documented.
-- [ ] Tier 1 green, aarch64 executed, install E2E green, no P0 bugs for 30
-      days (install E2E is 10/10; the other three are open/unrun).
+- [x] Tier 1 matrix green and aarch64 executed under qemu (0.15.0);
+      install E2E is 10/10. Physical aarch64 WSL is out of scope.
+- [ ] No P0 bugs for 30 days; clean-machine first-run timing still unrun.
 - [ ] `1.0.0` release notes list the supported matrix and the known
-      limitations (draft waits for the matrix).
+      limitations (COMPATIBILITY.md + LIMITATIONS.md are the draft).
 
 **Tests/probes:** [MIGRATION.md](MIGRATION.md#gates-a-release-must-clear);
 release gate; full probe suite.
@@ -776,5 +820,5 @@ A 1.0 release additionally requires the WSL-304 checklist.
 - Known boundaries: [LIMITATIONS.md](LIMITATIONS.md)
 - Current technical roadmap: [ROADMAP.md](ROADMAP.md)
 - Requirements traceability: [REQUIREMENTS.zh.md](REQUIREMENTS.zh.md)
-- Upstream mapping: [upstream/promotion-map.md](upstream/promotion-map.md)
-- Real-machine suite: [`test/probe/run-all-when-closed.sh`](../test/probe/run-all-when-closed.sh)
+- Upstream mapping: [upstream/promotion-map.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/upstream/promotion-map.md)
+- Real-machine suite: [`test/probe/run-all-when-closed.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/run-all-when-closed.sh)

package/docs/ROADMAP.md

@@ -20,6 +20,8 @@ section.
 | A4 | the native-session probe (scope, EXEC, FS, KILL, digest, teardown, 8/8) in the real-machine suite; the warm-cache and stdin-EPIPE fixes |
 | A5 | the native agent is the documented default; 0.10.0 published (npm + GitHub Release) |
 | A6 | `WslAgent.metrics()` and `test/probe/fs-queue.mjs`; the shared shell read agent is the measured batch bottleneck |
+| A7 | native shared read agent (v5); 16 concurrent shared reads 2.4–4.1 ms; shell remains the fallback |
+| A8 | aarch64 18-check under qemu-user in CI (built binary and committed `linux-aarch64` artifact); physical aarch64 WSL out of scope, see COMPATIBILITY.md |
 
 ## Next
 
@@ -30,9 +32,10 @@ The shared unconfined read agent was the only remaining measured bottleneck
 0.2-0.3 ms). A7 swaps its shell for the native binary (v5) while keeping the
 shell as the fallback:
 
-- **selection:** the same `agentBackend` semantics — `auto` prepares the
-  packaged binary for the distro's architecture, `native` refuses instead of
-  falling back, `shell` forces the shell; the dev override still wins;
+- **selection:** `shell` forces the shell; otherwise the shared agent tries
+  the packaged binary for the distro's architecture (or the dev override).
+  Unlike session-runtime preparation with `agentBackend: native`, shared reads
+  fall back to the shell when native preparation fails;
 - **preparation:** `ensureNativeBackend` once per distro (cache/digest/exec
   probe); the `WslAgent` with `expectedDigest` and `signalable: false`; on a
   preparation or HELLO failure the shell agent serves the reads — fail-open to
@@ -46,11 +49,13 @@ shell as the fallback:
   pays the ensure/cache cost (~70 ms once). The shell still serves the reads
   under `agentBackend: shell` and after a native failure.
 
-### A8 — aarch64 functional validation
+### A8 — aarch64 functional validation — done
 
-The aarch64 binary is built by CI but never executed there. Run the 18-check
-spike suite and the native-session probe on real aarch64 WSL or qemu; record
-the result in the ADR.
+The `native packages` job in CI builds static-musl aarch64 and runs the
+18-check spike suite under qemu-user against both the freshly built binary
+and the committed `agent/native/linux-aarch64/dsh-wsl-agent`. Physical
+aarch64 WSL is out of scope (COMPATIBILITY.md). The native-session probe on
+real aarch64 hardware is not planned.
 
 ### A9 — maintenance
 
@@ -66,8 +71,9 @@ the result in the ADR.
   measurably or the ERR/env framing is needed for another reason.
 - **Event stream.** No current consumer: the `fs.watch` contract is coarse and
   the inotify watcher satisfies it; terminal activity and ports poll.
-- **Shell retirement.** Not planned. The shell agent remains the fallback and
-  the shared read path until A7 lands, and the protocol/script stays supported.
+- **Shell retirement.** Not planned. The shell agent remains the fallback
+  (`agentBackend: shell`, and after a native HELLO/prepare failure) and the
+  protocol/script stays supported.
 
 ## Not planned
 

package/docs/UPSTREAM-FILE-REFERENCE-SEAM.md

@@ -10,7 +10,7 @@ decision.
 
 ## The measured cost
 
-Probe: [`test/probe/file-reference-9p.sh`](../test/probe/file-reference-9p.sh)
+Probe: [`test/probe/file-reference-9p.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/file-reference-9p.sh)
 (three runs, `node:fs` readdir walk, no ranking engine). Tree: 20 directories,
 520 files, one level of subdirectories; the same tree walked from Windows over
 `\\wsl.localhost\<distro>` and from inside the distro on ext4.
@@ -31,7 +31,7 @@ seam must keep.
 
 ## The seam
 
-RFC addendum ① (in [rfc-wsl-workspaces.md](upstream/rfc-wsl-workspaces.md))
+RFC addendum ① (in [rfc-wsl-workspaces.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/upstream/rfc-wsl-workspaces.md))
 proposes exposing the three module-internal funnels as an injectable strategy:
 
 ```ts
@@ -55,7 +55,7 @@ with three semantics that matter for a remote world:
 
 ## The plugin side is ready
 
-[`src/file-reference-wsl.ts`](../src/file-reference-wsl.ts) implements that
+[`src/file-reference-wsl.ts`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/src/file-reference-wsl.ts) implements that
 interface over the resident agent: one `find -printf` per directory, a
 single-exec segment walk for `resolveDisplayDirectory` (instead of N sequential
 `lstat`s), and the UNC/POSIX conversions. It is unit-tested against a fake

package/docs/UPSTREAM-FSIO-EXPORT.md

@@ -3,9 +3,9 @@
 Status: filed upstream as
 [deepseek-ai/deepseek-harness#10262](https://github.com/deepseek-ai/deepseek-harness/discussions/10262)
 (Ideas); the filing convention is [UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md).
-Targeting `deepseek-harness` @ `packages/fs/fs-local`, the `0.2.1-rc.x` line
-this plugin pins exactly (`@deepseek-ai/dsh-fs-local@0.2.1-rc.2`, in both the
-dev and peer dependency blocks of `package.json`). This is the Shape-A
+Targeting `deepseek-harness` @ `packages/fs/fs-local`, the `0.2.1-rc.x` line.
+The proposal was measured against `@deepseek-ai/dsh-fs-local@0.2.1-rc.2`;
+the current development pin and peer range are in `package.json`. This is the Shape-A
 upstream half of the in-distro I/O refactor: with the fsio text mechanics
 importable, `dsh-plugin-wsl-env` deletes its copies of them.
 
@@ -146,13 +146,13 @@ import("koffi")`, `:25`), so no native dependency is evaluated at import time.
   layer maps the `code` token and the message, not the error class.
 - Semver: an additive export. On the `0.2.0-rc.x` line it ships in the next
   pre-release — the `0.2` position does not move, so this is not a minor bump
-  of a released line; and because the consuming plugin pins the exact version,
-  adoption is an explicit pin bump, never an automatic upgrade.
+  of a released line. Adoption by the plugin requires an explicitly verified
+  development pin and a peer minimum that includes the export.
 
 ## Landing it (consumer side)
 
-1. Bump both pins in `package.json` (`devDependencies` and `peerDependencies`)
-   to the peer that carries the export.
+1. Update the development pin and peer minimum in `package.json` to a verified
+   version that carries the export.
 2. `pnpm run build` — `lib/` is committed, and `test/build-freshness.mjs`
    enforces that it is a byte-identical, closed image of `src/`.
 3. Re-run the comparison in [PEER-PARITY.md](PEER-PARITY.md) (its Maintenance

package/docs/UPSTREAM-OPEN-IN-APP.md

@@ -0,0 +1,57 @@
+# Upstream: Host "Open in app" inherits `ELECTRON_RUN_AS_NODE`
+
+Status: observed on DSH Desktop `0.2.1-rc.3` (Windows x64, 2026-10-30);
+**not a defect of this plugin.** The Host process's open-in-app launcher
+inherits `ELECTRON_RUN_AS_NODE=1`, so Electron editors (VS Code, Cursor)
+start as Node, exit 1, and the UI reports launch-failed. File Explorer and
+other non-Electron launchers work. The failure is the same on a Windows
+folder and on a WSL UNC workspace.
+
+User-facing note: [LIMITATIONS.md](LIMITATIONS.md#host-open-in-app).
+
+## Environment
+
+- DSH Desktop 0.2.1-rc.3, Windows 11
+- Reproduced on both `\\wsl.localhost\...` workspaces and plain Windows
+  paths; 100% of VS Code launches failed
+
+## What happens
+
+The desktop window's overflow menu "Open in app" → VS Code shows an "打开失败"
+/ launch-failed toast. VS Code never opens.
+
+## Cause
+
+1. The desktop app starts the backend Host through
+   `desktopNodeEnvironment()` (`lib/main.js`) with
+   `ELECTRON_RUN_AS_NODE: "1"`.
+2. Open-in-app's `launchDetachedApp()` (`@deepseek-ai/dsh-host-open-in-app`)
+   builds the child environment with `scrubbedParentEnv()`, which strips
+   keys matching `/KEY|PASSWORD|SECRET|TOKEN/i` and `DSH_*`.
+   `ELECTRON_RUN_AS_NODE` is left in place.
+3. Host then spawn's `Code.exe <workspace>`. VS Code (Electron) sees
+   `ELECTRON_RUN_AS_NODE=1`, runs as plain Node, opens no window, and
+   exits 1 inside the launch watch window → `POST /open-in-app/open`
+   returns 502 `launch-failed`.
+
+`dsh-subprocess-local` already clears `ELECTRON_RUN_AS_NODE` when it
+spawns the PTC runtime, so the Host carrying that variable is a known
+fact; open-in-app's scrub list does not follow it.
+
+## Reproduction
+
+Using the app's bundled `node.exe`, spawn `Code.exe` detached with stdio
+ignored and a scrubbed parent env:
+
+- without `ELECTRON_RUN_AS_NODE`: `Code.exe` stays running → launched
+- with `ELECTRON_RUN_AS_NODE=1`: process exits quickly, code 1 → 502
+
+## Ask
+
+Drop `ELECTRON_RUN_AS_NODE` in `launchDetachedApp()` (or in the shared
+`scrubbedParentEnv()`), matching `dsh-subprocess-local`. Any Electron
+target (VS Code, Cursor, …) hits the same path.
+
+This repository will not work around the Host spawn: the plugin does not
+own that launcher, and a WSL-specific env filter would not help Windows
+workspaces.

package/docs/UPSTREAM-SESSION-NOTICE.md

@@ -1,10 +1,10 @@
 # Upstream proposal: a session-visible notice seam for plugin advisories
 
-Status: proposed upstream; **not filed yet** — this environment has no issue
-channel, so the text below is ready for the maintainers to file against
-`deepseek-ai/deepseek-harness` (version line `0.2.1-rc.x`; the gap was checked
+Status: filed upstream as
+[deepseek-ai/deepseek-harness#10263](https://github.com/deepseek-ai/deepseek-harness/discussions/10263)
+(version line `0.2.1-rc.x`; the gap was checked
 against `dsh-v0.2.1-rc.2` on 2026-10-19). The exact filing payload (title, body,
-command) is [proposal-session-notice.md](upstream/proposal-session-notice.md). The plugin ships the workaround
+command) is [proposal-session-notice.md](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/docs/upstream/proposal-session-notice.md). The plugin ships the workaround
 described at the end: the advisory goes to the log **and** into the session's
 runtime context, which is model-visible and appears in the session transcript,
 but is not a dedicated banner.

package/docs/UPSTREAM-TERMINAL-TITLE.md

@@ -107,17 +107,15 @@ next touched:
 
 ## Workarounds until then
 
+- The plugin now ships the candidate list itself: `shellCandidates` is
+  `[wsl.exe, powershell, cmd]` in [`cordis.patch.yml`](../cordis.patch.yml),
+  with the `shell` block kept verbatim. `wsl.exe` dedupes into the default's
+  `wsl` kind; selecting `powershell` or `cmd` starts a shell the terminal
+  really launches (host sessions do outright) and titles the tab after itself.
+  Nothing remains for a user layer to add unless it wants different entries.
 - Double-click a tab's title to rename it (a shipped client feature; the
   controller's `rename` Remote API accepts 1–120 characters).
-- Re-declare the `terminal-controller` row in a user layer with a non-empty
-  `shellCandidates`: a manually selected shell is titled after itself. A patch
-  config replaces the whole config rather than deep-merging it
-  (`packages/boot/app-boot/src/config-schema/document.ts`), so the override has
-  to carry this plugin's `shell` block verbatim — `path: wsl.exe`, `name: WSL`,
-  `args: []` — or the terminal stops being a distro terminal. Expect the menu
-  to grow the host shells discovery finds on the root provider, which receives
-  no directory: executables this terminal never starts (the second bullet of
-  the GUI-terminal comment in [`cordis.patch.yml`](../cordis.patch.yml)).
-  [LIMITATIONS.md](LIMITATIONS.md) still carries the older one-line form of
-  this tip, which drops the `shell` block; the version above is the one that
-  works.
+
+Both cover only manually selected shells. The DEFAULT entry — what a new tab
+gets before anyone chooses — is still titled from the static profile, which is
+exactly the gap the upstream change closes.