dsh-plugin-wsl-env 0.8.0 → 0.10.0

package/lib/ports.js

@@ -55,17 +55,30 @@ export function procNetScript() {
  *
  * @param runner - the {@link WslAgent}-like runner.
  * @param timeoutMs - the exec budget.
- * @returns listening ports, ascending; [] on any failure — a snapshot is a
- *   convenience, never an error the session should see.
+ * @returns listening ports, ascending; undefined when the scan could not
+ *   answer (agent out, non-zero exit), so a caller can keep the last snapshot.
  */
-export async function listeningPorts(runner, timeoutMs = 10000) {
+export async function scanListeningPorts(runner, timeoutMs = 10000) {
     try {
         const result = await runner.exec({ cwd: "/", argv: ["sh", "-c", procNetScript(), "ports"], timeoutMs });
         if (result.exitCode !== 0)
-            return [];
+            return undefined;
         return parseListeningPorts(result.stdout.toString("utf8"));
     }
     catch {
-        return [];
+        return undefined;
     }
 }
+/**
+ * Snapshot the distro's listening ports, collapsing a failed scan to an empty
+ * list. New callers that must distinguish "none listening" from "the scan
+ * failed" should use {@linkcode scanListeningPorts}; this wrapper exists for
+ * the probe/test shape that only needs the list.
+ *
+ * @param runner - the agent-like runner.
+ * @param timeoutMs - the exec budget.
+ * @returns listening ports, ascending; [] on a failed scan.
+ */
+export async function listeningPorts(runner, timeoutMs = 10000) {
+    return (await scanListeningPorts(runner, timeoutMs)) ?? [];
+}

package/lib/preflight.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Session-start sandbox preflight: surface a missing or broken `bwrap` when a
+ * distro session OPENS, not when its first command fails closed.
+ *
+ * Without this the discovery moment is the model's first command, whose
+ * `SANDBOX_UNAVAILABLE` error scrolls past as one tool failure among many; the
+ * operator may not read it until several commands have failed the same way.
+ * The probe itself is not new — it is the providers' own usability probe, run
+ * through the same shared cache (`lib/sandbox-core.js`), so a session-start
+ * check costs a real probe only once per process, and the first confined
+ * command after it pays nothing. Nothing else changes: the failure semantics
+ * stay exactly as fail-closed as before, this service only MOVES THE NEWS.
+ *
+ * Advisory by construction. A preflight that cannot run (no WSL, a wedged
+ * `wsl.exe`) degrades to a log line; it must never fail a session that has not
+ * even asked for confinement yet. It also never installs anything: the remedy
+ * it prints is the same one the refusals carry, and running an installer under
+ * root uninvited would be a posture this plugin explicitly rejects.
+ *
+ * This is a TypeScript source built to `lib/preflight.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/preflight
+ */
+import z from "@deepseek-ai/schemastery";
+import type { Context } from "@deepseek-ai/cordis";
+export declare const name = "wsl-preflight";
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    /** Distro to preflight; empty means this machine's default distro. */
+    distro: z<string, string, "defined">;
+    /** The `wsl.exe` path the probe spawns; keep in step with the providers' `wslPath`. */
+    wslPath: z<string, string, "defined">;
+    /** Whether the session-start sandbox preflight runs at all. */
+    sandbox: z<boolean, boolean, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    /** Distro to preflight; empty means this machine's default distro. */
+    distro: z<string, string, "defined">;
+    /** The `wsl.exe` path the probe spawns; keep in step with the providers' `wslPath`. */
+    wslPath: z<string, string, "defined">;
+    /** Whether the session-start sandbox preflight runs at all. */
+    sandbox: z<boolean, boolean, "defined">;
+}>>, "plain">;
+/** The config schema's validated output. */
+export interface PreflightConfig {
+    /** Distro to preflight; empty means this machine's default distro. */
+    distro?: string;
+    /** The `wsl.exe` path the probe spawns. */
+    wslPath?: string;
+    /** Whether the session-start sandbox preflight runs at all. */
+    sandbox?: boolean;
+}
+/**
+ * The slice of a created agent this service inspects; the harness's agent
+ * object is structural here, the same view `auto-preset` uses.
+ */
+export interface PreflightAgent {
+    /** The agent's id. */
+    id: string;
+    /** The session stub, when mounted. */
+    session?: {
+        header?: {
+            cwd?: string | undefined;
+        };
+    } | undefined;
+}
+/**
+ * The cordis context extended with the slices this service consumes. `logger`
+ * and the agent service belong to the harness, whose declarations are not
+ * visible to this plugin, so they are spelled structurally on top of the
+ * framework's {@link Context}.
+ */
+export type PreflightContext = Context & {
+    logger?: {
+        debug?: (message: string) => void;
+        warn?: (message: string) => void;
+    };
+    agents?: {
+        list: () => PreflightAgent[];
+    };
+    on: (event: "agent/created", listener: (payload: {
+        agent?: PreflightAgent;
+    } | undefined) => void) => () => boolean;
+};
+/**
+ * Mount the preflight service.
+ *
+ * @param ctx - the cordis context.
+ * @param config - the schema-validated plugin config.
+ */
+export declare function apply(ctx: PreflightContext, config?: PreflightConfig): Promise<void>;

package/lib/preflight.js

@@ -0,0 +1,117 @@
+/**
+ * Session-start sandbox preflight: surface a missing or broken `bwrap` when a
+ * distro session OPENS, not when its first command fails closed.
+ *
+ * Without this the discovery moment is the model's first command, whose
+ * `SANDBOX_UNAVAILABLE` error scrolls past as one tool failure among many; the
+ * operator may not read it until several commands have failed the same way.
+ * The probe itself is not new — it is the providers' own usability probe, run
+ * through the same shared cache (`lib/sandbox-core.js`), so a session-start
+ * check costs a real probe only once per process, and the first confined
+ * command after it pays nothing. Nothing else changes: the failure semantics
+ * stay exactly as fail-closed as before, this service only MOVES THE NEWS.
+ *
+ * Advisory by construction. A preflight that cannot run (no WSL, a wedged
+ * `wsl.exe`) degrades to a log line; it must never fail a session that has not
+ * even asked for confinement yet. It also never installs anything: the remedy
+ * it prints is the same one the refusals carry, and running an installer under
+ * root uninvited would be a posture this plugin explicitly rejects.
+ *
+ * This is a TypeScript source built to `lib/preflight.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/preflight
+ */
+import z from "@deepseek-ai/schemastery";
+import { isWslUnc } from "./paths.js";
+import { defaultDistro, runCapture } from "./wsl.js";
+import { bwrapFailure, bwrapUsable, missingBwrapRemedy } from "./sandbox-core.js";
+import { sessionScopeSweepScript } from "./session-scope.js";
+export const name = "wsl-preflight";
+export const Config = z.object({
+    /** Distro to preflight; empty means this machine's default distro. */
+    distro: z.string().default(""),
+    /** The `wsl.exe` path the probe spawns; keep in step with the providers' `wslPath`. */
+    wslPath: z.string().default("wsl.exe"),
+    /** Whether the session-start sandbox preflight runs at all. */
+    sandbox: z.boolean().default(true),
+});
+/** Distros whose stale-scope sweep has already run in this process. */
+const sweptDistros = new Set();
+/**
+ * Stop `dsh-wsl-*.scope` units a crashed app left behind. A scope is stale
+ * when its cgroup has no `wsl-agent.sh`; a live agent means another session
+ * still owns it. Advisory: a failed spawn re-arms the distro for the next
+ * session, and the once-per-distro cache keeps the cost off the normal path.
+ *
+ * @param wslPath - the `wsl.exe` path.
+ * @param distro - the resolved distro.
+ */
+const sweepStaleScopes = (wslPath, distro) => {
+    if (sweptDistros.has(distro))
+        return;
+    sweptDistros.add(distro);
+    void runCapture([wslPath, "-d", distro, "--exec", "sh", "-c", sessionScopeSweepScript()]).catch(() => {
+        sweptDistros.delete(distro);
+    });
+};
+/**
+ * Mount the preflight service.
+ *
+ * @param ctx - the cordis context.
+ * @param config - the schema-validated plugin config.
+ */
+export async function apply(ctx, config = {}) {
+    if (!(config.sandbox ?? true))
+        return;
+    const wslPath = config.wslPath ?? "wsl.exe";
+    const warn = (message) => ctx.logger?.warn?.(message);
+    /**
+     * Probe the distro once and surface an unusable `bwrap` as a warning.
+     *
+     * @param agent - the session that just opened, for the workspace scope.
+     */
+    const check = async (agent) => {
+        // Only a distro workspace has commands that confine: a host session would
+        // warn about a sandbox it never uses.
+        const cwd = agent?.session?.header?.cwd;
+        if (cwd === undefined || !isWslUnc(cwd))
+            return;
+        let distro = config.distro ?? "";
+        if (distro.length === 0) {
+            try {
+                distro = await defaultDistro({ wslPath });
+            }
+            catch (error) {
+                // No WSL at all is the missing-wsl probe's territory; the first
+                // command's own error is the precise one. Stay quiet at warn level.
+                ctx.logger?.debug?.(`wsl-preflight: no default distro to preflight (${error?.message ?? error})`);
+                return;
+            }
+        }
+        // bwrapUsable answers false on a failed probe — it never rejects — so
+        // nothing here can throw except a broken context, which is the caller's
+        // bug, not the session's.
+        // Clean up what a hard crash left behind before this session creates its
+        // runtime; a live agent in another session's cgroup makes its scope safe.
+        sweepStaleScopes(wslPath, distro);
+        const usable = await bwrapUsable({ wslPath, distro });
+        if (usable) {
+            ctx.logger?.debug?.(`wsl-preflight: bwrap is usable inside distro "${distro}"`);
+            return;
+        }
+        warn(`wsl-preflight: ${bwrapFailure(wslPath, distro) ?? missingBwrapRemedy(distro)}`);
+    };
+    ctx.on("agent/created", (payload) => void check(payload?.agent));
+    // Mount order is not a guarantee: a session created during startup can finish
+    // before this service mounts and miss the event entirely (dsh-headless does
+    // exactly that, and auto-preset sweeps for the same reason).
+    try {
+        for (const agent of ctx.agents?.list() ?? [])
+            void check(agent);
+    }
+    catch (error) {
+        ctx.logger?.debug?.(`wsl-preflight: could not sweep already-live agents: ${error?.message ?? error}`);
+    }
+}

package/lib/probe-cache.d.ts

@@ -25,10 +25,21 @@ export interface ProbeCache {
      *
      * @param key - the probe's cache key.
      * @param probe - the probe to run on a miss. A throw is a failed probe, never
-     *   a propagated error.
+     *   a propagated error; its message is remembered for {@link failure}.
      * @returns the verdict; a success is remembered, a failure is not.
      */
     run(key: string, probe: () => Promise<boolean> | boolean): Promise<boolean>;
+    /**
+     * The message of the probe failure the key last recorded, if any. A failed
+     * verdict is not remembered as a verdict, but its reason outlives the miss:
+     * the remedy a caller prints is composed from WHY the probe failed, and the
+     * next caller — often the very next command — must still see it.
+     *
+     * @param key - the probe's cache key.
+     * @returns the thrown error's message, or undefined while no failure is
+     *   recorded; cleared on the key's next success.
+     */
+    failure(key: string): string | undefined;
     /** Remembered successes, for tests and diagnostics. */
     readonly size: number;
 }

package/lib/probe-cache.js

@@ -25,6 +25,7 @@
  */
 export function createProbeCache() {
     const verdicts = new Map();
+    const failures = new Map();
     return {
         async run(key, probe) {
             const cached = verdicts.get(key);
@@ -34,18 +35,25 @@ export function createProbeCache() {
                 try {
                     return await probe();
                 }
-                catch {
+                catch (error) {
+                    failures.set(key, error instanceof Error ? error.message : String(error));
                     return false;
                 }
             })();
             verdicts.set(key, pending);
             const verdict = await pending;
-            if (verdict)
+            if (verdict) {
                 verdicts.set(key, true);
-            else
+                failures.delete(key);
+            }
+            else {
                 verdicts.delete(key);
+            }
             return verdict;
         },
+        failure(key) {
+            return failures.get(key);
+        },
         /** Remembered successes, for tests and diagnostics. */
         get size() {
             return verdicts.size;

package/lib/sandbox-core.d.ts

@@ -16,6 +16,76 @@
  *
  * @module dsh-plugin-wsl/sandbox-core
  */
+/**
+ * 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 declare function missingBwrapRemedy(distro: string, family?: string): string;
+/**
+ * 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 declare function bwrapInstallHint(distro: string): string;
+/**
+ * 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 declare function withBwrapHint(detail: string, distro: string): string;
+/**
+ * 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 declare function bwrapUsable(options: {
+    wslPath: string;
+    distro: string;
+    signal?: AbortSignal | undefined;
+}): Promise<boolean>;
+/**
+ * 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 declare function bwrapFailure(wslPath: string, distro: string): string | undefined;
 /**
  * The seam's `ConfinedArgv` settlement facts, plus this core's `windowsDrive`
  * mitigation flag.

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 });