dsh-plugin-wsl-env 0.8.0 → 0.9.0

package/lib/sandbox-core.js

@@ -65,6 +65,188 @@ const ENFORCEMENT = "partial";
  * where it is unit-testable without the peers this module needs.
  */
 const probeVerdicts = createProbeCache();
+/** The cache key one (wsl.exe, distro) pair's bwrap verdict lives under. */
+const probeKey = (wslPath, distro) => `${wslPath}\u0000${distro}`;
+/**
+ * The direct install command each detected package family gets in the remedy.
+ * The bootstrap script remains the first-choice path — it detects the family
+ * itself — but a user pasting the message on a dnf or pacman distro must not
+ * be handed an `apt-get` line.
+ */
+const FAMILY_INSTALL = {
+    apt: "apt-get install -y bubblewrap",
+    dnf: "dnf install -y bubblewrap",
+    pacman: "pacman -S --noconfirm bubblewrap",
+    zypper: "zypper --non-interactive install bubblewrap",
+};
+/** How many characters of the failed probe's output the remedy quotes. */
+const PROBE_OUTPUT_CAP = 300;
+/**
+ * Classify one failed probe's output. `bwrap: ` on the output means the binary
+ * RAN and refused — a present-but-unusable bwrap (an old build, a kernel
+ * without unprivileged user namespaces), which no reinstall fixes. wsl.exe's
+ * own relay for a missing `--exec` binary names the exec instead, which is the
+ * install case. Anything else is unclassified and gets the install remedy with
+ * the raw output quoted, so neither reading is lost.
+ *
+ * @param output - the failed probe's combined stdout+stderr, NULs stripped.
+ * @returns why the probe failed, as the remedy needs it.
+ */
+function classifyProbeOutput(output) {
+    if (/\bbwrap: /i.test(output))
+        return "broken";
+    if (/no such file|execv|not found|cannot run|could not be started/i.test(output))
+        return "missing";
+    return "unknown";
+}
+/**
+ * The package manager the distro offers, for the remedy's direct command. Only
+ * consulted on a FAILED probe, so a healthy distro never pays for it; a probe
+ * that cannot answer leaves the remedy with the package-manager-agnostic line.
+ *
+ * @param wslPath - the `wsl.exe` path the failed probe used.
+ * @param distro - the distro the failed probe ran in.
+ * @param signal - optional cancellation shared with the probe.
+ * @returns the first family whose manager exists, or undefined.
+ */
+async function detectPackageFamily(wslPath, distro, signal) {
+    try {
+        const script = "for m in apt-get dnf pacman zypper; do command -v $m && break; done";
+        // `command -v` answers with the PATH-resolved path, so matching on the
+        // trailing name is exact — a bare manager name never comes back.
+        const manager = (await runCapture([wslPath, "-d", distro, "--exec", "sh", "-c", script], signal)).trim().split("\n")[0]?.trim() ?? "";
+        if (manager.endsWith("/apt-get"))
+            return "apt";
+        if (manager.endsWith("/dnf"))
+            return "dnf";
+        if (manager.endsWith("/pacman"))
+            return "pacman";
+        if (manager.endsWith("/zypper"))
+            return "zypper";
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compose the remedy one failed probe reports. Pure apart from the optional
+ * family probe it may issue (a failed probe only), so the text is unit-testable
+ * through a fake `wsl.exe`.
+ *
+ * @param wslPath - the `wsl.exe` path the probe used.
+ * @param distro - the distro the probe ran in.
+ * @param cause - the raw probe failure.
+ * @param signal - optional cancellation shared with the probe.
+ * @returns the operator-facing remedy text.
+ */
+async function composeBwrapFailure(wslPath, distro, cause, signal) {
+    const output = String(cause?.message ?? cause ?? "").slice(0, PROBE_OUTPUT_CAP).trim();
+    const kind = classifyProbeOutput(output);
+    if (kind === "broken") {
+        // A broken verdict requires the bwrap banner, so the output is never empty here.
+        return (`bwrap is installed inside distro "${distro}" but failed the usability probe: ${output}. ` +
+            `This is usually the kernel (unprivileged user namespaces disabled) or an unusable bwrap build rather than a missing package, so reinstalling will not help. ` +
+            `Check \`wsl.exe -d ${distro} --exec bwrap --version\` inside the distro, or set \`sandbox: false\` on the wsl-shell and wsl-fs rows to run unconfined.`);
+    }
+    const remedy = missingBwrapRemedy(distro, await detectPackageFamily(wslPath, distro, signal));
+    return kind === "unknown" && output.length > 0 ? `${remedy} The probe failed with: ${output}` : remedy;
+}
+/**
+ * The canonical remedy for a distro whose `bwrap` is missing — also the
+ * fallback for callers that know only "the probe failed", without a classified
+ * reason. The direct command is family-aware when the caller knows the family;
+ * the bootstrap script is always the first-choice path because it detects the
+ * family itself.
+ *
+ * @param distro - the distro to install into.
+ * @param family - the detected package family, when known.
+ * @returns the operator-facing remedy text.
+ */
+export function missingBwrapRemedy(distro, family) {
+    const direct = family === undefined ? undefined : FAMILY_INSTALL[family];
+    if (direct === undefined) {
+        return (`bwrap is not usable inside distro "${distro}". Install it with ` +
+            `"scripts/bootstrap.sh ${distro} --install" (from the package), or install the ` +
+            `"bubblewrap" package with the distro's package manager.`);
+    }
+    return (`bwrap is not usable inside distro "${distro}". Install it with ` +
+        `"scripts/bootstrap.sh ${distro} --install" (from the package), or directly: ` +
+        `wsl.exe -d ${distro} -u root -- ${direct}`);
+}
+/**
+ * The remedy for a bwrap that PROBED healthy but failed a run — the runtime
+ * twin of {@link missingBwrapRemedy}. No family knowledge exists on this path
+ * (the probe succeeded, so no family probe ever ran), and reinstalling is only
+ * one of the plausible fixes, so the hint leads with diagnosis.
+ *
+ * @param distro - the distro whose bwrap failed at run time.
+ * @returns the operator-facing hint text.
+ */
+export function bwrapInstallHint(distro) {
+    return (`bwrap failed at run time inside distro "${distro}". Check \`bwrap --version\` there, ` +
+        `or reinstall it: "scripts/bootstrap.sh ${distro} --install".`);
+}
+/**
+ * Append {@link bwrapInstallHint} to a runner-failure detail that names bwrap.
+ * A probe-time failure composes its own classified remedy; this covers the
+ * OTHER order — bwrap probed healthy, then failed a real command — where no
+ * probe failure is on record and the raw `bwrap: …` line is all the model
+ * would see. Details that do not name bwrap pass through untouched: the
+ * runner-failure rules match the confinement runner, and the confinement
+ * runner is always bwrap here, but the wording stays the decider so a future
+ * rule change cannot attach a bwrap remedy to a foreign failure.
+ *
+ * @param detail - the classified runner-failure detail.
+ * @param distro - the distro the command ran in.
+ * @returns the detail, with the remedy appended when it names bwrap.
+ */
+export function withBwrapHint(detail, distro) {
+    return /\bbwrap\b/i.test(detail) ? `${detail} — ${bwrapInstallHint(distro)}` : detail;
+}
+/**
+ * Probe one distro's `bwrap` under the shared verdict cache. The probe mirrors
+ * upstream's: apply the real read-only profile around `true`, and treat a zero
+ * exit as the kernel having accepted and enforced it. A missing `bwrap` fails
+ * the spawn and probes unusable, which is what makes the providers fail closed
+ * rather than silently run unconfined.
+ *
+ * A success is remembered for the process lifetime; a failure is not, so a
+ * `bubblewrap` installed while the app is running is believed on the next
+ * command. The failure's composed remedy stays readable through
+ * {@link bwrapFailure}, which is how every refusal and the preflight surface it.
+ *
+ * @param options - the `wsl.exe` path and the distro to probe.
+ * @param options.wslPath - the `wsl.exe` path.
+ * @param options.distro - the distro to probe.
+ * @param options.signal - optional cancellation.
+ * @returns true when a confined command can run there.
+ */
+export async function bwrapUsable(options) {
+    const { wslPath, distro, signal } = options;
+    return probeVerdicts.run(probeKey(wslPath, distro), async () => {
+        const prefix = bwrapArgvPrefix({ mode: "read-only", workspaceRoot: "/" });
+        try {
+            await runCapture([wslPath, "-d", distro, "--exec", ...prefix, "true"], signal);
+            return true;
+        }
+        catch (cause) {
+            throw new Error(await composeBwrapFailure(wslPath, distro, cause, signal));
+        }
+    });
+}
+/**
+ * The remedy text of a key's last failed probe, as {@link bwrapUsable} composed
+ * it — the same string the providers' refusals carry. Undefined while the probe
+ * never failed (or last succeeded).
+ *
+ * @param wslPath - the `wsl.exe` path the probe used.
+ * @param distro - the distro the probe ran in.
+ * @returns the composed remedy, or undefined.
+ */
+export function bwrapFailure(wslPath, distro) {
+    return probeVerdicts.failure(probeKey(wslPath, distro));
+}
 /**
  * Build the sandbox class, bound to one unavailable-error implementation.
  *
@@ -81,27 +263,16 @@ export function createSandboxCore({ SandboxUnavailableError }) {
             this.maskWindowsDrive = config.maskWindowsDrive ?? false;
         }
         /**
-         * Whether `bwrap` can create a profile inside this distro. The probe mirrors
-         * upstream's: apply the real read-only profile around `true`, and treat a zero
-         * exit as the kernel having accepted and enforced it. A missing `bwrap` fails the
-         * spawn and probes unusable, which is what makes the provider fail closed rather
-         * than silently run unconfined.
-         *
-         * A success is remembered for the process lifetime; a failure is not, so a
-         * `bubblewrap` installed while the app is running is believed on the next
-         * command.
+         * Whether `bwrap` can create a profile inside this distro. Delegates to the
+         * shared free probe — the same cache the preflight service and every other
+         * instance instance read, so a verdict paid once is paid once per process.
          *
          * @param distro - the distro to probe.
          * @param signal - optional cancellation.
          * @returns true when a confined command can run there.
          */
         async usable(distro, signal) {
-            const key = `${this.wslPath}\u0000${distro}`;
-            return probeVerdicts.run(key, async () => {
-                const prefix = bwrapArgvPrefix({ mode: "read-only", workspaceRoot: "/" });
-                await runCapture([this.wslPath, "-d", distro, "--exec", ...prefix, "true"], signal);
-                return true;
-            });
+            return bwrapUsable({ wslPath: this.wslPath, distro, signal });
         }
         /**
          * Wrap one distro-side argv in the bwrap profile the policy asks for.
@@ -122,9 +293,7 @@ export function createSandboxCore({ SandboxUnavailableError }) {
         async confine(argv, policy, options) {
             const { distro, signal } = options;
             if (!(await this.usable(distro, signal))) {
-                throw new SandboxUnavailableError(policy.mode, `bwrap is not usable inside distro "${distro}". Install it with ` +
-                    `"scripts/bootstrap.sh ${distro} --install" (from the package), or directly: ` +
-                    `wsl.exe -d ${distro} -u root -- apt-get install -y bubblewrap`);
+                throw new SandboxUnavailableError(policy.mode, bwrapFailure(this.wslPath, distro) ?? missingBwrapRemedy(distro));
             }
             const workspaceRoot = toLinuxPath(policy.workspaceRoot, { distro });
             const prefix = bwrapArgvPrefix({ ...policy, workspaceRoot }, { maskWindowsDrive: this.maskWindowsDrive });

package/lib/wsl.js

@@ -104,8 +104,11 @@ export function parseDistroList(stdout) {
  */
 export async function defaultDistro(options = {}) {
     const [first] = await listDistros(options);
-    if (first === undefined)
-        throw new Error("dsh-plugin-wsl: no WSL distro is installed (`wsl.exe -l -q` returned nothing)");
+    if (first === undefined) {
+        throw new Error("dsh-plugin-wsl: no WSL distro is installed (`wsl.exe -l -q` returned nothing). " +
+            "Install one: `wsl.exe --list --online` lists the available names, then `wsl --install -d <name>`, " +
+            "or point this row's `distro` at an existing one.");
+    }
     return first;
 }
 /**
@@ -134,7 +137,8 @@ export async function linuxHomePath(distro, options = {}) {
 export function parseHomePath(distro, stdout) {
     const home = String(stdout).trim();
     if (home.length === 0 || !home.startsWith("/")) {
-        throw new Error(`dsh-plugin-wsl: distro "${distro}" reported no usable $HOME (got "${home}")`);
+        throw new Error(`dsh-plugin-wsl: distro "${distro}" reported no usable $HOME (got "${home}"). ` +
+            `Check the distro's default user in /etc/wsl.conf, and that the user's /etc/passwd entry carries a home directory.`);
     }
     return home;
 }
@@ -337,7 +341,9 @@ export async function defaultShell(distro, options = {}) {
 export async function runInDistro(distro, command, options = {}) {
     const shell = options.shell ?? (await defaultShell(distro, options));
     if (shell === undefined) {
-        throw new Error(`dsh-plugin-wsl: distro "${distro}" named no usable shell (passwd probe and $SHELL both failed)`);
+        throw new Error(`dsh-plugin-wsl: distro "${distro}" named no usable shell (passwd probe and $SHELL both failed). ` +
+            `Check the user's login shell in /etc/passwd (\`getent passwd "$(id -u)"\` inside the distro), ` +
+            `or point this row's \`shell\` at an existing absolute path.`);
     }
     return runCapture([options.wslPath ?? DEFAULT_WSL_PATH, "-d", distro, "--exec", shell, ...shellArgs(shell, options.loginShell !== false), command], options.signal);
 }

package/locale/preflight/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL sandbox preflight",
+    "description": "Probes bubblewrap when a distro session opens and surfaces a missing or unusable bwrap as a warning with the exact remedy — instead of the first command's fail-closed error being the discovery moment. Advisory only; never installs anything."
+  }
+}

package/locale/preflight/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "WSL 沙箱预检",
+    "description": "发行版会话打开时探测 bubblewrap，把缺失或不可用的 bwrap 连同确切的修复指引作为警告提前给出——而不是让第一条命令的 fail-closed 报错充当发现时刻。纯建议性，绝不安装任何东西。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "让 DeepSeek Harness 以 WSL 子系统作为会话的执行环境：shell、文件读写与命令执行均在子系统内完成，目录选择器与 GUI 终端同样定位到子系统路径，并通过子系统内的 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
@@ -47,12 +47,18 @@
       "types": "./lib/paths.d.ts",
       "default": "./lib/paths.js"
     },
+    "./preflight": {
+      "types": "./lib/preflight.d.ts",
+      "default": "./lib/preflight.js"
+    },
     "./picker": {
       "types": "./lib/picker.d.ts",
       "default": "./lib/picker.js"
     },
     "./picker/locale/en.json": "./locale/picker/en.json",
     "./picker/locale/zh.json": "./locale/picker/zh.json",
+    "./preflight/locale/en.json": "./locale/preflight/en.json",
+    "./preflight/locale/zh.json": "./locale/preflight/zh.json",
     "./shell": {
       "types": "./lib/shell.d.ts",
       "default": "./lib/shell.js"
@@ -104,16 +110,17 @@
     "SECURITY.md",
     "SUPPORT.md",
     "LICENSE",
-    "scripts/bootstrap.sh"
+    "scripts/bootstrap.sh",
+    "scripts/diagnose.sh"
   ],
   "scripts": {
     "test": "pnpm run lint:style && pnpm run test:syntax && pnpm run lint:build && pnpm run lint:types && pnpm run test:unit",
     "lint:types": "tsc --noEmit",
     "build": "node scripts/build.mjs",
     "lint:build": "node test/build-freshness.mjs",
-    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=84 --test-coverage-functions=70 test/agent-exec.test.mjs test/agent-fs-script.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-substrate.test.mjs test/fs.boot.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/fsio-agent.test.mjs test/fsio-text.test.mjs test/git-route.test.mjs test/listing.test.mjs test/paths.test.mjs test/ports.test.mjs test/preset-choice.test.mjs test/probe-cache.test.mjs test/sandbox.test.mjs test/search-exec.test.mjs test/search-route.test.mjs test/fs.boot.test.mjs test/shell.test.mjs test/terminal-activity.test.mjs test/terminal.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=84 --test-coverage-functions=70 test/agent-exec.test.mjs test/agent-fs-script.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-substrate.test.mjs test/fs.boot.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/fsio-agent.test.mjs test/fsio-text.test.mjs test/git-route.test.mjs test/listing.test.mjs test/paths.test.mjs test/ports.test.mjs test/preset-choice.test.mjs test/probe-cache.test.mjs test/preflight.test.mjs test/sandbox.test.mjs test/search-exec.test.mjs test/search-route.test.mjs test/shell.test.mjs test/terminal-activity.test.mjs test/terminal.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs",
     "test:syntax": "node test/syntax.mjs",
-    "test:unit": "node --test test/fs.boot.test.mjs test/fsio-text.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/git-route.test.mjs test/fsio-text.test.mjs test/search-route.test.mjs test/search-exec.test.mjs test/terminal-activity.test.mjs",
+    "test:unit": "node --test test/fs.boot.test.mjs test/fsio-text.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preflight.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/git-route.test.mjs test/fsio-text.test.mjs test/search-route.test.mjs test/search-exec.test.mjs test/terminal-activity.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "pnpm test",
     "probe": "bash test/probe/run.sh",
@@ -129,7 +136,8 @@
     "probe:agent": "bash test/probe/agent.sh",
     "probe:substrate": "bash test/probe/substrate.sh",
     "probe:exec": "bash test/probe/exec.sh",
-    "bootstrap": "bash scripts/bootstrap.sh"
+    "bootstrap": "bash scripts/bootstrap.sh",
+    "diagnose": "bash scripts/diagnose.sh"
   },
   "packageManager": "pnpm@11.7.0",
   "engines": {

package/scripts/diagnose.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Collect a read-only diagnostic report for a bug report, in one command:
+#
+#     pnpm run diagnose -- [distro]     # distro optional; default distro otherwise
+#
+# Prints versions and probe verdicts as plain text that can be pasted into an
+# issue as-is. It runs NO installation, changes nothing in the distro, and reads
+# nothing secret: the report is tool versions, a kernel release and probe
+# verdicts. Exit code is always 0 — the report is informational; the verdict
+# lines carry the failures.
+#
+# Deeper sandbox probing lives in `npm run probe:sandbox` (run inside the
+# distro); this script answers "what is installed and does bwrap run at all".
+
+set -u
+export WSL_UTF8=1 # wsl.exe writes UTF-16LE without it; read as UTF-8 that is mojibake
+
+DISTRO="${1:-}"
+
+ok()    { printf 'ok        %s\n' "$1"; }
+miss()  { printf 'MISSING   %s\n' "$1"; }
+info()  { printf 'info      %s\n' "$1"; }
+header(){ printf '\n== %s ==\n' "$1"; }
+
+echo "# dsh-plugin-wsl-env diagnose report"
+
+header "host"
+winver="$(cmd.exe /c ver 2>/dev/null | tr -d '\r' | grep -o '[0-9][0-9.]*' | head -1)"
+if [ -n "$winver" ]; then ok "windows build $winver"; else info "windows build unknown (cmd.exe not reachable through interop)"; fi
+wsl_ver="$(wsl.exe --version 2>/dev/null | tr -d '\0\r' | head -2 | tr '\n' ' ')"
+if [ -n "$wsl_ver" ]; then ok "wsl: $wsl_ver"; else info "wsl --version unsupported on this WSL build"; fi
+wsl_status="$(wsl.exe --status 2>/dev/null | tr -d '\0\r' | tr '\n' ' ')"
+[ -n "$wsl_status" ] && info "wsl status: $wsl_status"
+wsl.exe -l -v 2>/dev/null | tr -d '\0\r' | grep -v '^$' | sed 's/^/          /'
+
+header "plugin"
+echo "          plugin version: $(node -p "require('./package.json').version" 2>/dev/null || echo unknown)"
+echo "          dsh version: $(dsh --version 2>/dev/null || echo unknown)"
+
+if [ -z "$DISTRO" ]; then
+  DISTRO="$(wsl.exe -l -q 2>/dev/null | tr -d '\0\r' | grep -v '^$' | head -1)"
+fi
+if [ -z "$DISTRO" ]; then
+  header "distro"
+  miss "no distro installed — 'wsl.exe --list --online' lists names, 'wsl --install -d <name>' installs one"
+  exit 0
+fi
+
+header "distro: $DISTRO"
+in_distro() { wsl.exe -d "$DISTRO" --exec sh -c "$1" 2>/dev/null; }
+
+info "kernel: $(in_distro 'uname -r')"
+family="$(in_distro 'for m in apt-get dnf pacman zypper; do command -v $m && break; done' | tr -d '\r')"
+case "$family" in
+  *apt-get) info "package family: apt" ;;
+  *dnf)     info "package family: dnf" ;;
+  *pacman)  info "package family: pacman" ;;
+  *zypper)  info "package family: zypper" ;;
+  *)        info "package family: unknown" ;;
+esac
+
+for tool in bwrap rg git inotifywait; do
+  if in_distro "command -v $tool" | grep -q .; then
+    case "$tool" in
+      bwrap)       ver="$(in_distro 'bwrap --version' | tr -d '\r' | head -1)" ;;
+      rg)          ver="$(in_distro 'rg --version' | tr -d '\r' | head -1)" ;;
+      git)         ver="$(in_distro 'git --version' | tr -d '\r' | head -1)" ;;
+      inotifywait) ver="inotifywait (no version flag)" ;;
+    esac
+    ok "$ver"
+  else
+    case "$tool" in
+      bwrap)       miss "bwrap — REQUIRED; every confined command fails closed without it. Install: wsl.exe -d $DISTRO -u root -- apt-get install -y bubblewrap (or: pnpm run bootstrap -- $DISTRO --install)" ;;
+      rg)          miss "ripgrep — the search tool falls back to slower matching without it" ;;
+      git)         miss "git — snapshot and diff baselines degrade without it" ;;
+      inotifywait) miss "inotify-tools — file watching falls back to polling without it" ;;
+    esac
+  fi
+done
+
+if in_distro 'command -v bwrap' | grep -q .; then
+  if in_distro 'bwrap --ro-bind / / -- true'; then
+    ok "bwrap runs a read-only profile (the usability probe passes)"
+  else
+    miss "bwrap is installed but FAILED the read-only profile probe — likely the kernel (unprivileged user namespaces disabled) or an unusable build; reinstalling will not help"
+  fi
+fi
+
+header "notes"
+info "trace file: set DSH_WSL_TRACE=<path> to record the auto-preset decisions, then re-run the scenario"
+info "paste this report into the issue's Output section; redact anything you would rather not publish"
+exit 0