dsh-plugin-wsl-env 0.13.2 → 0.14.0

package/CHANGELOG.md

@@ -16,6 +16,68 @@ were part of the record.
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-10-27
+
+This release fixes the first-run trap the compatibility-matrix run found on a
+freshly imported distro, and ships the measured support table the run produced.
+
+### Fixed
+
+- **WSL-305: the confined resident now creates the workspace root before its
+  first spawn.** The bwrap profile binds the workspace root and bwrap refuses
+  a missing bind source, so on a freshly imported distro the first confined
+  write failed with a bare `FS_IO_ERROR: agent exited during handshake
+  (code=1)` and a misleading remedy. `agent-confined.js` gained a `prepare`
+  hook (workspace-write only — the only mode that binds the root) that runs
+  `mkdir -p` on the Linux-spelled root before bwrap runs, idempotently and
+  ignoring its own outcome: bwrap stays the authority, and a refusal still
+  reaches the caller. That refusal now carries evidence: the handshake
+  failure's message includes a bounded tail of the resident's stderr (the
+  half-day of diagnosis this cost came from it being swallowed). Three new
+  checks cover the prepare hook, its argv, and the stderr ride-on; a
+  fresh-root leg in `substrate.sh` exercises the absent-root spawn end to
+  end on a real distro.
+
+### Changed
+
+- **Debian is verified end to end, and the run found a first-run trap.**
+  The four harness-level probes pass against a `wslfs-debian` profile on a
+  freshly imported Debian 13.5, completing the full stack on top of the
+  distro-internal suite (`docs/COMPATIBILITY.md`). Getting there surfaced one
+  real finding: the confined resident refuses to start when the workspace
+  root does not exist yet — the bwrap profile binds the root, bwrap requires
+  the bind source to exist, and a fresh distro has nothing to bind. Creating
+  the root first turns all ten failing steps green; prior Ubuntu runs had it
+  left over from earlier probes. The finding is documented in the matrix page
+  with the suggested spawn-preparation fix.
+
+- **The compatibility matrix moves from prose to a measured page.**
+  `docs/COMPATIBILITY.md` records the WSL-202 evidence: six real WSL2 distros
+  (Ubuntu, Debian 13.5, Fedora 44, openSUSE Tumbleweed, Arch, Alpine 3.22)
+  executed the distro-internal probe suite on one machine on 2026-10-26, and
+  the page explains the two observed differences instead of hiding them — the
+  `session-sandbox` background-survival leg races WSL session teardown on
+  three systemd distros (probe artifact, not a plugin claim), and on Alpine
+  the same leg fails by declaration, because non-systemd distros get the
+  narrower `sessionSandbox: auto` scope exactly as P1.1/WSL-201 promises. The
+  page also records the per-distro import traps (Debian OOBE wedge, Alpine
+  minirootfs defaulting to root, busybox mktemp, zypper's interactive prompt)
+  and the reproduction commands. Not yet measured: real aarch64 hardware, the
+  container-image matrix.
+
+- **The aarch64 native agent is executed in CI, not only built.** The
+  `native packages` job installs qemu's user-mode emulator and binfmt
+  registration (`qemu-user` + `qemu-user-binfmt`; noble has no real
+  `qemu-user-static` package) and runs the full
+  18-check spike suite under qemu-user against both the freshly built aarch64
+  musl binary and the committed `agent/native/linux-aarch64/dsh-wsl-agent` —
+  the binary a Windows-on-ARM session would load. User-mode emulation
+  exercises every check (the static musl binary and the v5 frames are
+  host-OS-free), verified locally first: 18/18 under `qemu-aarch64`, with
+  `/proc/self/exe` resolving to the target so the HELLO digest binding holds
+  unchanged. This closes the "build-tested only" gap on WSL-202; a run on
+  real aarch64 hardware remains open.
+
 ## [0.13.2] - 2026-10-26
 
 This release tracks DeepSeek Harness `0.2.1-rc.3`: the peer declarations become

package/lib/agent-confined.d.ts

@@ -1,4 +1,36 @@
 import { WslAgent } from "./agent.js";
+/**
+ * The spawn function `ensureWorkspaceRoot` uses; injectable so a unit test can
+ * observe the argv without a real `wsl.exe`.
+ */
+type SpawnLike = (file: string, args: string[], options: {
+    stdio: "ignore";
+    windowsHide: boolean;
+    env: NodeJS.ProcessEnv;
+}) => {
+    on: (event: string, handler: (...args: unknown[]) => void) => void;
+};
+/**
+ * Make sure the workspace root exists in the distro before the confined
+ * resident's first spawn: the bwrap profile binds the root
+ * (`--bind <root> <root>`) and bwrap refuses a missing bind source — on a
+ * freshly imported distro the first write's workspace may not exist yet, and
+ * the resident would exit during its handshake with a bare code 1 and no
+ * hint (WSL-305). Idempotent (`mkdir -p`), and its outcome is deliberately
+ * ignored here: bwrap remains the authority on whether the profile can be
+ * built, and its refusal now reaches the caller through the handshake
+ * error's stderr tail.
+ *
+ * @param options - the transport, distro, root, and an injectable spawn.
+ * @returns resolves once the `mkdir -p` has been issued (settled, whatever
+ * its result — bwrap decides).
+ */
+export declare function ensureWorkspaceRoot({ wslPath, distro, root, spawnFn }: {
+    wslPath: string;
+    distro: string;
+    root: string;
+    spawnFn?: SpawnLike;
+}): Promise<void>;
 /** One confinement request. */
 export interface ConfinedAgentRequest {
     /** The distro to run in. */

package/lib/agent-confined.js

@@ -31,11 +31,39 @@
  *
  * @module dsh-plugin-wsl/agent-confined
  */
+import { spawn } from "node:child_process";
 import { bwrapArgvPrefix } from "./bwrap.js";
 import { toLinuxPath } from "./paths.js";
 import { agentScriptDigest, agentScriptPath } from "./agent-shared.js";
-import { WslAgent } from "./agent.js";
+import { pinnedWindowsEnv, WslAgent } from "./agent.js";
 const confinedAgents = new Map();
+/**
+ * Make sure the workspace root exists in the distro before the confined
+ * resident's first spawn: the bwrap profile binds the root
+ * (`--bind <root> <root>`) and bwrap refuses a missing bind source — on a
+ * freshly imported distro the first write's workspace may not exist yet, and
+ * the resident would exit during its handshake with a bare code 1 and no
+ * hint (WSL-305). Idempotent (`mkdir -p`), and its outcome is deliberately
+ * ignored here: bwrap remains the authority on whether the profile can be
+ * built, and its refusal now reaches the caller through the handshake
+ * error's stderr tail.
+ *
+ * @param options - the transport, distro, root, and an injectable spawn.
+ * @returns resolves once the `mkdir -p` has been issued (settled, whatever
+ * its result — bwrap decides).
+ */
+export function ensureWorkspaceRoot({ wslPath, distro, root, spawnFn }) {
+    return new Promise((resolve) => {
+        const doSpawn = spawnFn ?? ((file, args, options) => spawn(file, args, options));
+        const child = doSpawn(wslPath, ["-d", distro, "--exec", "mkdir", "-p", root], {
+            stdio: "ignore",
+            windowsHide: true,
+            env: pinnedWindowsEnv(process.env),
+        });
+        child.on("error", () => resolve());
+        child.on("exit", () => resolve());
+    });
+}
 /**
  * The confined agent for one distro and one resolved policy, created on first
  * use and shared for the process lifetime. A success is remembered; a failed
@@ -48,6 +76,7 @@ export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindows
     const key = `${wslPath}\0${distro}\0${policy.mode}\0${policy.workspaceRoot}\0${maskWindowsDrive ? "masked" : "visible"}\0${realTmp ? "real" : "ephemeral"}`;
     let agent = confinedAgents.get(key);
     if (agent === undefined) {
+        const linuxRoot = toLinuxPath(policy.workspaceRoot, { distro });
         agent = new WslAgent({
             distro,
             wslPath,
@@ -58,7 +87,15 @@ export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindows
             // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s
             // `spawnDefault`). Both confinement sites share that assembly in
             // `lib/bwrap.js`, whose module doc records what happened when they did not.
-            argvPrefix: bwrapArgvPrefix({ mode: policy.mode, workspaceRoot: toLinuxPath(policy.workspaceRoot, { distro }) }, { maskWindowsDrive, realTmp }),
+            argvPrefix: bwrapArgvPrefix({ mode: policy.mode, workspaceRoot: linuxRoot }, { maskWindowsDrive, realTmp }),
+            // workspace-write is the only mode that binds the workspace root, and
+            // bwrap refuses a missing bind source (WSL-305): on a freshly imported
+            // distro the first write's workspace may not exist yet, and the resident
+            // used to exit during its handshake with a bare code 1. Create the root
+            // before the first spawn; every later start re-runs it harmlessly.
+            prepare: policy.mode === "workspace-write"
+                ? () => ensureWorkspaceRoot({ wslPath, distro, root: linuxRoot }).then(() => undefined)
+                : undefined,
         });
         confinedAgents.set(key, agent);
     }

package/lib/agent.js

@@ -352,6 +352,14 @@ export class WslAgent {
             // reflected in the state/pending requests; an unhandled stream error
             // would crash the host process instead.
             child.stdin?.on("error", () => { });
+            // The resident's own stderr is the only diagnostic a handshake failure
+            // carries (bwrap's refusal names the missing bind source, a libc
+            // mismatch names itself); surface a bounded tail on the lastError
+            // instead of leaving the caller a bare exit code.
+            let hsErr = "";
+            child.stderr?.on("data", (chunk) => {
+                hsErr += String(chunk);
+            });
             child.on("exit", (code, signalName) => {
                 if (!current()) {
                     // A stale child's exit: release its pipes, but never touch the
@@ -360,7 +368,7 @@ export class WslAgent {
                     return;
                 }
                 if (this.state === "starting") {
-                    this.lastError = `agent exited during handshake (code=${code} signal=${signalName ?? "none"})`;
+                    this.lastError = `agent exited during handshake (code=${code} signal=${signalName ?? "none"})${hsErr ? ` stderr=${hsErr.trim().slice(-400)}` : ""}`;
                     settleStart(new Error(this.lastError));
                 }
                 this.handleProcessExit(child, code, signalName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",