dsh-plugin-wsl-env 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -12,6 +12,61 @@ reference below points at that record's numbering.
 
 ## [Unreleased]
 
+## [0.1.8] - 2026-10-02
+
+A probe assertion for the one item the closure review had to record as unverifiable.
+No runtime change.
+
+### Added
+
+- `npm run probe:sandbox-shell` asserts that a command past its deadline is reported as
+  timed out **and leaves no process behind in the distro** (15 checks, up from 13). The
+  escalated path is used on purpose: a confined command also dies with its `bwrap`
+  parent, so only the unconfined path shows whether the subprocess service's kill
+  actually reaches the distro. It does — measured through `ctx.shell` here, and
+  directly by killing a `wsl.exe` relay and watching the distro-side `sleep` disappear
+  with it (1 process before, 0 after).
+
+### Documentation
+
+- The review's "unverified: orphaned processes after a timeout" item is closed. The
+  earlier attempt could not see the process at all, and said so: the agent's own shell
+  ran in a separate PID namespace, where `ps` cannot see the distro's processes.
+
+
+## [0.1.7] - 2026-10-02
+
+One correctness fix and the error-code reference the closure review asked for.
+
+### Fixed
+
+- A command whose working directory could not be entered was reported as a success.
+  `wsl.exe --cd <missing>` does not fail: it writes a relay error to stderr, runs the
+  command in `/`, and exits 0 — measured directly, and visible in the shell probe's own
+  transcript. A build or a write could therefore act on the wrong tree while every
+  signal said it worked. `WslShellExecutor` now matches that relay line and fails with
+  the directory and the fallback. Both markers are required (the relay prefix and
+  `CreateProcessCommon`), so a command printing its own `chdir(...)` message cannot be
+  mistaken for it; the matcher also finds the line when it arrives UTF-16 encoded.
+  `npm run probe:sandbox-shell` asserts the behaviour end to end, and
+  `test/shell.test.mjs` covers the matcher, including a false-positive case.
+- The shell probe's own setup ran into this on the first run: it created the workspace
+  root while that not-yet-existing root was its workdir, which had "worked" only because
+  `mkdir -p` takes an absolute path. The setup now runs from the distro home, and the
+  new assertion pins the failure it used to hide.
+
+### Documentation
+
+- `docs/ARCHITECTURE.md` gains an **Error codes** table: what raises each `FS_*` code
+  and `SANDBOX_UNAVAILABLE`, what each one means, and what clears it — including that
+  `FS_OUTSIDE_DISTRO` cannot be lifted by a wider permission. It also documents the two
+  failures that come from `wsl.exe` itself: a missing, stopped or unregistered distro (a
+  `WSL_E_*` code on stdout, UTF-16 on some builds, with an empty stderr) and an
+  unenterable working directory. Both READMEs' troubleshooting tables now point at it.
+- `docs/LIMITATIONS.md` separates the two workdir cases a deleted directory can produce:
+  the bind that bubblewrap refuses, and the directory that cannot be entered.
+
+
 ## [0.1.6] - 2026-10-02
 
 Three probes that close coverage gaps a closure review named, the documentation of a

package/CONTRIBUTING.md

@@ -147,11 +147,11 @@ On Windows 11 + WSL2 (Ubuntu 26.04) the following has been verified:
   outside the session workspace is refused inside the distro and the following
   wider-permission request succeeds.
 
-Counts: 55 unit assertions on a bare checkout (50 plus the 5 preset-decision
-checks), plus 5 in `test/sandbox.test.mjs` which need the `dsh-sandbox` peer and skip
-themselves without it; 19 filesystem-probe assertions; 12 shell-probe checks; 9 picker
-checks; 6 missing-executable checks; 5 mode checks and 10 sandbox expectations plus the
-recorded escape; and 3 terminal assertions.
+Counts: 57 unit assertions on a bare checkout, plus 5 in `test/sandbox.test.mjs` which
+need the `dsh-sandbox` peer and skip themselves without it; 19 filesystem-probe
+assertions; 15 shell-probe checks; 9 picker checks; 6 missing-executable checks; 5 mode
+checks and 10 sandbox expectations plus the recorded escape; and 3 terminal
+assertions.
 
 ## Commit and pull request conventions
 

package/README.md

@@ -90,6 +90,7 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#sandbox) for the design, and [do
 | `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 | the Windows-side ripgrep walks the 9p share | expected; narrow the path, or use `bash` to call tools inside the distro |
 | the terminal reports `unknown` activity | shell integration only covers `bash`/`zsh` started directly on a POSIX host | close the tab to release the process; idle reclamation does not run for these terminals |
+| 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
 

package/docs/ARCHITECTURE.md

@@ -165,6 +165,30 @@ code, because a wider permission cannot create a distro.
 Set `sandbox: false` on either provider to opt out. Commands then run unconfined,
 and `sandboxMode` returns `undefined`.
 
+## Error codes
+
+The plugin raises `FsError`s with a code the tool layer maps, and `wsl.exe`'s own
+failures are named as well. A model sees the code; a reader asking what refused them
+finds it here.
+
+| Code | Raised by | Meaning | What clears it |
+|---|---|---|---|
+| `SANDBOX_UNAVAILABLE` | `WslSandbox.confine` | the requested mode cannot be enforced: no usable `bwrap` in the distro | install `bubblewrap` there (a failed probe is re-run, so no restart is needed), or set `sandbox: false` |
+| `FS_SANDBOX_DENIED` | `WslFileSystem.checkedTarget` | the file-effect policy refused the write: `read-only`, or a target outside the writable roots | a wider permission for that one call, or a session workspace that contains the target |
+| `FS_OUTSIDE_DISTRO` | `WslFileSystem.worldPath` | `restrictToDistro` is on and the path names **another distro**'s share — a configuration fence, not a sandbox decision | open a session in that distro, or set `restrictToDistro: false`. A wider permission does **not** lift it |
+| `FS_NOT_OBSERVED` | `WslFileSystem.assertGuard` | a guarded create (`createIfAbsent`) targeted a file that exists and had not been read first | read the file, then overwrite with the version guard or edit it |
+| `FS_STALE_VERSION` | `WslFileSystem.assertGuard` | the version the caller holds no longer matches: the file changed, or is gone | read it again and retry with the fresh version |
+| `FS_IO_ERROR` | `WslFileSystem.watch` | `watch()` is refused, because a 9p share cannot be watched reliably | poll, or watch from inside the distro |
+| `FS_NOT_FOUND` | the host filesystem stack | the path does not exist — the ordinary answer, passed through | — |
+
+Two failures come from `wsl.exe` itself rather than from a code of ours, and both used
+to be invisible:
+
+| Failure | How it arrives | What the plugin does |
+|---|---|---|
+| the distro is missing, stopped or unregistered | a `Wsl/Service/WSL_E_*` code on **stdout**, UTF-16 on some builds, with an empty stderr and exit 255 | `WslShellExecutor` reads the code with the NULs stripped and fails with the distro name and the remedy. Deliberately not a sandbox code: a wider permission cannot create a distro |
+| the working directory cannot be entered | a relay line on stderr, exit **0**, and the command runs in `/` | `WslShellExecutor` fails with the directory and the fallback, instead of reporting a success that acted on the wrong tree |
+
 ## The runtime mirror
 
 The checkout lives inside the distro. A DSH profile can only link a Windows path,

package/docs/LIMITATIONS.md

@@ -19,9 +19,11 @@ boundary; one that is not is a bug report waiting to happen.
   the file tools can only report a file-level error, because the share itself is
   gone.
 - `workspace-write` binds the workspace root as writable, and bubblewrap refuses a
-  bind whose source directory does not exist. If a session's workspace directory is
-  deleted, commands fail with a runner error; the plugin does not recreate the
-  directory.
+  bind whose source directory does not exist, so a session whose workspace directory was
+  deleted fails with a runner error; the plugin does not recreate it. A workdir that
+  does not exist — a configured `cwd` pointing at a deleted directory, for instance — is
+  a separate case and is now reported as an error naming that directory, because
+  `wsl.exe` would otherwise run the command in `/` and exit 0.
 - New files get the distro's umask default (0644). A `chmod` from the Windows side on
   a share path is silently ignored; overwrites and edits keep the original permission
   bits. Run `chmod +x` inside the distro when you need an executable.

package/docs/README.zh.md

@@ -90,6 +90,7 @@ dsh --profile wsl                                  # 4. 启动
 | 用 `link:\\wsl.localhost\...` 安装后符号链接是坏的 | pnpm 无法链接 UNC 路径 | 改成链接 Windows 路径；在发行版内开发时用运行时镜像，见[开发](#开发) |
 | `glob`/`grep` 很慢 | Windows 侧的 ripgrep 在 9p 共享上遍历 | 属于预期，收窄搜索路径，或改用 `bash` 调用发行版内的工具 |
 | 终端活动显示 `unknown` | 官方 shell 集成只对 POSIX 主机上直接启动的 `bash`/`zsh` 生效 | 关闭标签页以释放进程；空闲回收不会对它触发 |
+| 结果里出现 `FS_*` 码 | 码本身说明了是谁拒绝的、以及怎样解除 | 见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#error-codes) 的错误码表 |
 
 ## 开发
 

package/lib/index.js

@@ -46,7 +46,7 @@ import { isRelativeWorldPath, isWorldPathUnder, isWslUnc, isUnderDistro, posixTo
 import { WslSandbox } from "./sandbox.js";
 // `runCapture` and distro discovery live in ./wsl.js so the directory picker
 // can use them without pulling this file's executor and filesystem peers in.
-import { canonicalLinuxPath, copyModeInDistro, defaultDistro, defaultShell, linuxHomePath, shellArgs, wslErrorCode } from "./wsl.js";
+import { canonicalLinuxPath, copyModeInDistro, defaultDistro, defaultShell, linuxHomePath, shellArgs, workdirFailure, wslErrorCode } from "./wsl.js";
 
 /**
  * Every model shell call gets a rebuilt managed `DSH_*` namespace (see
@@ -467,6 +467,27 @@ export class WslShellExecutor extends LocalBashExecutor {
     );
   }
 
+  /**
+   * Reject a command that ran in the wrong directory.
+   *
+   * `wsl.exe --cd <path>` does not fail on a missing directory: it warns on stderr,
+   * runs the command in `/`, and exits 0. Reporting that as success would let a write
+   * or a build act on the wrong tree while every signal says it worked, so it becomes
+   * an error naming the directory that could not be entered.
+   *
+   * @param result - the settled shell result.
+   * @param workdir - the Linux directory the request asked for.
+   * @throws Error naming the directory and the fallback that happened.
+   */
+  throwIfWorkdirMissing(result, workdir) {
+    const missing = workdirFailure(result?.stdout?.text, result?.stderr?.text);
+    if (missing === undefined) return;
+    throw new Error(
+      `wsl.exe could not enter the working directory "${missing}" inside the distro, so the command ran from "/" instead. ` +
+        `Create it, or point \`cwd\` (or the request's \`workdir\`) at a directory that exists.`,
+    );
+  }
+
   async execute(spec) {
     const distro = await this.distro();
     const shell = await this.shell();
@@ -480,6 +501,7 @@ export class WslShellExecutor extends LocalBashExecutor {
         execution,
         (result) => {
           this.throwIfDistroUnavailable(result, distro);
+          this.throwIfWorkdirMissing(result, resolved.workdir);
           return result;
         },
         (error) => {
@@ -512,6 +534,7 @@ export class WslShellExecutor extends LocalBashExecutor {
     );
     return WslShellExecutor.decorateResult(execution, (result) => {
       this.throwIfDistroUnavailable(result, distro);
+      this.throwIfWorkdirMissing(result, resolved.workdir);
       if (confined === undefined) return { ...result, sandbox: { mode, denied: false } };
       const { enforcement, denialSignatures, runnerFailureRules } = confined;
       // Runner failure outranks denial because the command did not run at all.

package/lib/wsl.js

@@ -194,6 +194,29 @@ const POSIX_LOGIN_SHELLS = new Set(["sh", "bash", "dash", "zsh", "ksh", "ksh93",
  * @param login - whether login-shell semantics were requested.
  * @returns the flags to place before the command string.
  */
+/**
+ * The working directory `wsl.exe` could not enter, when its relay said so.
+ *
+ * `wsl.exe --cd <path>` does not fail when `<path>` is missing. It writes a relay
+ * error to STDERR, runs the command in `/` anyway, and exits 0 — so a caller would see
+ * a successful command that ran somewhere else. The shape is matched here for the
+ * callers to turn into a failure.
+ *
+ * Both markers are required: the relay prefix and `CreateProcessCommon`. A command is
+ * free to print "chdir(...) failed" itself, and a false positive would turn a correct
+ * run into an error. Verified against `wsl.exe -d <distro> --cd /missing --exec sh`:
+ * exit 0, `hi` on stdout, this shape on stderr.
+ *
+ * @param stdout - a command's captured stdout.
+ * @param stderr - its captured stderr.
+ * @returns the directory that could not be entered, or undefined.
+ */
+export function workdirFailure(stdout, stderr) {
+  const text = `${stdout ?? ""}\n${stderr ?? ""}`.replace(/\0/g, "");
+  const match = /<3>WSL[^\n]*CreateProcessCommon[^\n]*chdir\(([^)]*)\) failed/.exec(text);
+  return match?.[1];
+}
+
 export function shellArgs(shellPath, login) {
   const name = String(shellPath).slice(String(shellPath).lastIndexOf("/") + 1).toLowerCase();
   if (!POSIX_LOGIN_SHELLS.has(name)) return ["-c"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Run a DeepSeek Harness session against a WSL distro: a ctx.shell executor that runs commands inside the distro and a ctx.fs backend over its UNC share",
   "keywords": [
     "deepseek-harness",