dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/lib/ports.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Listening-port visibility for the distro, the Remote-WSL port-forwarding
+ * parity row's DSH-side half.
+ *
+ * There is no DSH channel that streams live facts to the model; the sanctioned
+ * one is the managed `DSH_*` namespace (`ctx.shellEnv`), whose `resolve` is
+ * SYNCHRONOUS. So the snapshot is refreshed on a timer and served stale-but-
+ * recent: `DSH_WSL_PORTS` names the ports with a listener inside the distro,
+ * at most `refreshMs` old. A dev server the model starts shows up on the next
+ * refresh, which is the granularity that matters at conversational pace.
+ *
+ * The scan reads `/proc/net/tcp` and `/proc/net/tcp6` directly — no `ss`, no
+ * `netstat`, nothing to install — and keeps sockets in state `0A` (LISTEN).
+ * Pure parser, unit-testable without a distro.
+ *
+ * This is a TypeScript source built to `lib/ports.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/ports
+ */
+import type { AgentExecRunner } from "./agent-exec.js";
+/**
+ * Parse one `/proc/net/tcp{,6}` body into listening ports.
+ *
+ * @param text - the file's content.
+ * @returns deduplicated listening ports, ascending.
+ */
+export declare function parseListeningPorts(text: string): number[];
+/**
+ * The shell script that prints both proc files' contents.
+ *
+ * @returns the `sh -c` body.
+ */
+export declare function procNetScript(): string;
+/**
+ * Snapshot the distro's listening ports through the agent.
+ *
+ * @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.
+ */
+export declare function listeningPorts(runner: AgentExecRunner, timeoutMs?: number): Promise<number[]>;

package/lib/ports.js

@@ -13,49 +13,59 @@
  * `netstat`, nothing to install — and keeps sockets in state `0A` (LISTEN).
  * Pure parser, unit-testable without a distro.
  *
+ * This is a TypeScript source built to `lib/ports.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/ports
  */
-
 /**
  * Parse one `/proc/net/tcp{,6}` body into listening ports.
- * @param {string} text - the file's content.
- * @returns {number[]} deduplicated listening ports, ascending.
+ *
+ * @param text - the file's content.
+ * @returns deduplicated listening ports, ascending.
  */
 export function parseListeningPorts(text) {
-  const ports = new Set();
-  for (const line of text.split("\n").slice(1)) {
-    const columns = line.trim().split(/\s+/);
-    // sl, local_address, rem_address, st, ... — st 0A is LISTEN.
-    if (columns.length < 4 || columns[3] !== "0A") continue;
-    const portHex = columns[1].split(":")[1];
-    if (portHex === undefined) continue;
-    const port = Number.parseInt(portHex, 16);
-    if (Number.isFinite(port) && port > 0) ports.add(port);
-  }
-  return [...ports].sort((a, b) => a - b);
+    const ports = new Set();
+    for (const line of text.split("\n").slice(1)) {
+        const columns = line.trim().split(/\s+/);
+        // sl, local_address, rem_address, st, ... — st 0A is LISTEN.
+        const localAddress = columns[1];
+        if (columns.length < 4 || localAddress === undefined || columns[3] !== "0A")
+            continue;
+        const portHex = localAddress.split(":")[1];
+        if (portHex === undefined)
+            continue;
+        const port = Number.parseInt(portHex, 16);
+        if (Number.isFinite(port) && port > 0)
+            ports.add(port);
+    }
+    return [...ports].sort((a, b) => a - b);
 }
-
 /**
  * The shell script that prints both proc files' contents.
- * @returns {string} the `sh -c` body.
+ *
+ * @returns the `sh -c` body.
  */
 export function procNetScript() {
-  return "cat /proc/net/tcp /proc/net/tcp6 2>/dev/null";
+    return "cat /proc/net/tcp /proc/net/tcp6 2>/dev/null";
 }
-
 /**
  * Snapshot the distro's listening ports through the agent.
- * @param {object} runner - the {@link WslAgent}-like runner.
- * @param {number} [timeoutMs] - the exec budget.
- * @returns {Promise<number[]>} listening ports, ascending; [] on any failure —
- *   a snapshot is a convenience, never an error the session should see.
+ *
+ * @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.
  */
 export async function listeningPorts(runner, timeoutMs = 10000) {
-  try {
-    const result = await runner.exec({ cwd: "/", argv: ["sh", "-c", procNetScript(), "ports"], timeoutMs });
-    if (result.exitCode !== 0) return [];
-    return parseListeningPorts(result.stdout.toString("utf8"));
-  } catch {
-    return [];
-  }
+    try {
+        const result = await runner.exec({ cwd: "/", argv: ["sh", "-c", procNetScript(), "ports"], timeoutMs });
+        if (result.exitCode !== 0)
+            return [];
+        return parseListeningPorts(result.stdout.toString("utf8"));
+    }
+    catch {
+        return [];
+    }
 }

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,94 @@
+/**
+ * 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 } from "./wsl.js";
+import { bwrapFailure, bwrapUsable, missingBwrapRemedy } from "./sandbox-core.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),
+});
+/**
+ * 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.
+        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/preset-choice.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether a newly created session should adopt the WSL preset.
+ *
+ * The rule is deliberately narrow, and it is the whole of "a session whose workspace
+ * is inside a distro gets the distro environment automatically":
+ *
+ *   - the workspace must be a WSL UNC path, so a Windows folder keeps its own
+ *     environment;
+ *   - the session must not already carry an explicit choice. `undefined` counts as
+ *     "no choice", because a caller that mounts nothing at all (the headless runner)
+ *     is not asking for the host environment either; anything else must equal the
+ *     registry's default id, which is what "the operator did not pick one" looks like
+ *     after composition.
+ *
+ * Pure, so the decision is unit-testable without a boot — the frame timing that
+ * applies it still needs the harness.
+ *
+ * This is a TypeScript source built to `lib/preset-choice.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ */
+/**
+ * The adoption decision.
+ *
+ * @param input - the new session's workspace, the preset it currently has, and
+ *   the registry default.
+ * @returns true when the WSL preset should be selected for this session.
+ */
+export declare function shouldAdoptWslPreset({ cwd, current, fallback }?: {
+    cwd?: string;
+    current?: string;
+    fallback?: string;
+}): boolean;

package/lib/preset-choice.js

@@ -15,14 +15,22 @@
  * Pure, so the decision is unit-testable without a boot — the frame timing that
  * applies it still needs the harness.
  *
- * @param {{ cwd?: string, current?: string, fallback?: string }} input - the new
- *   session's workspace, the preset it currently has, and the registry default.
- * @returns true when the WSL preset should be selected for this session.
+ * This is a TypeScript source built to `lib/preset-choice.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
  */
 import { isWslUnc } from "./paths.js";
-
+/**
+ * The adoption decision.
+ *
+ * @param input - the new session's workspace, the preset it currently has, and
+ *   the registry default.
+ * @returns true when the WSL preset should be selected for this session.
+ */
 export function shouldAdoptWslPreset({ cwd, current, fallback } = {}) {
-  if (!isWslUnc(cwd)) return false;
-  if (current === void 0) return true;
-  return current === fallback;
+    if (cwd === undefined || !isWslUnc(cwd))
+        return false;
+    if (current === void 0)
+        return true;
+    return current === fallback;
 }

package/lib/probe-cache.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The caching policy for a functional probe: which verdicts may be remembered.
+ *
+ * A SUCCESS is durable — if `bwrap` created a profile a minute ago it will create
+ * one now. A FAILURE is not: it describes the machine as it is at that moment, and
+ * the common case is a package that is not installed *yet*. Remembering a failure
+ * would make the documented remedy (`sudo apt install bubblewrap`) silently
+ * ineffective until the app restarts, while the error message tells the user to
+ * install exactly that. So a failure is dropped and the next call probes again.
+ *
+ * Probes are I/O, and concurrent first calls would otherwise each pay for one.
+ * Storing the in-flight promise makes them share a single probe.
+ *
+ * Pure by construction — no Node API, no clock — so the policy is unit-testable
+ * without the peers `lib/sandbox.js` needs.
+ *
+ * This is a TypeScript source built to `lib/probe-cache.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ */
+/** One probe cache's surface. */
+export interface ProbeCache {
+    /**
+     * Run one probe under the policy.
+     *
+     * @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; 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;
+}
+/**
+ * Build one probe cache.
+ *
+ * @returns the policy object `lib/sandbox-core.js` holds per provider.
+ */
+export declare function createProbeCache(): ProbeCache;

package/lib/probe-cache.js

@@ -14,35 +14,49 @@
  * Pure by construction — no Node API, no clock — so the policy is unit-testable
  * without the peers `lib/sandbox.js` needs.
  *
- * @param {() => Promise<boolean>|boolean} probe - the probe to run on a miss. A
- *   throw is a failed probe, never a propagated error.
- * @returns {{ run: (key: string, probe: () => Promise<boolean>|boolean) => Promise<boolean>, size: number }}
+ * This is a TypeScript source built to `lib/probe-cache.js`; edit THIS file and
+ * run `pnpm run build` — the artifact under `lib/` is generated, and `pnpm test`
+ * fails when it drifts.
+ */
+/**
+ * Build one probe cache.
+ *
+ * @returns the policy object `lib/sandbox-core.js` holds per provider.
  */
 export function createProbeCache() {
-  /** @type {Map<string, true|Promise<boolean>>} */
-  const verdicts = new Map();
-  return {
-    async run(key, probe) {
-      const cached = verdicts.get(key);
-      if (cached !== undefined) return cached;
-
-      const pending = (async () => {
-        try {
-          return await probe();
-        } catch {
-          return false;
-        }
-      })();
-      verdicts.set(key, pending);
-
-      const verdict = await pending;
-      if (verdict) verdicts.set(key, true);
-      else verdicts.delete(key);
-      return verdict;
-    },
-    /** Remembered successes, for tests and diagnostics. */
-    get size() {
-      return verdicts.size;
-    },
-  };
+    const verdicts = new Map();
+    const failures = new Map();
+    return {
+        async run(key, probe) {
+            const cached = verdicts.get(key);
+            if (cached !== undefined)
+                return cached;
+            const pending = (async () => {
+                try {
+                    return await probe();
+                }
+                catch (error) {
+                    failures.set(key, error instanceof Error ? error.message : String(error));
+                    return false;
+                }
+            })();
+            verdicts.set(key, pending);
+            const verdict = await pending;
+            if (verdict) {
+                verdicts.set(key, true);
+                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

@@ -0,0 +1,149 @@
+/**
+ * The sandbox's probe and confinement logic, free of DSH peers.
+ *
+ * `lib/sandbox.js` binds this core to the peer's `SandboxUnavailableError` —
+ * the class identity `instanceof` consumers match — which is the ONLY thing
+ * that kept the whole policy out of unit tests: a checkout without the peers
+ * could not even import the module, so CI skipped every check of the probe
+ * caching policy and the argv composition. The core takes the error class as
+ * the one injected dependency; the tests inject a stand-in with the same
+ * contract (`code: "SANDBOX_UNAVAILABLE"`), and what CI runs is the code that
+ * ships.
+ *
+ * This is a TypeScript source built to `lib/sandbox-core.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/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.
+ */
+export interface WslConfined {
+    /** The wrapped argv (bwrap prefix, separator, the caller's argv). */
+    argv: string[];
+    /**
+     * How completely the profile enforces the policy's file effects. Typed as
+     * the seam's union (upstream `SandboxEnforcement`) while this core always
+     * reports `partial` (see the `ENFORCEMENT` doc above): the value an executor
+     * passes through is the seam's, wherever it came from.
+     */
+    enforcement: "full" | "partial";
+    /** The case-insensitive stderr substrings a bwrap denial produces. */
+    denialSignatures: string[];
+    /** Structured runner-failure evidence rules. */
+    runnerFailureRules: Array<{
+        fatalSignatures: string[];
+        allowedExitCodes?: number[];
+        informationalLines?: string[];
+    }>;
+    /** Whether the profile masks the Windows drive at `/mnt`. */
+    windowsDrive: "masked" | "visible";
+}
+/**
+ * The sandbox class `createSandboxCore` builds, as its consumers see it.
+ */
+export interface WslSandboxCoreInstance {
+    /** The `wsl.exe` path this instance spawns. */
+    wslPath: string;
+    /** Whether every profile masks `/mnt`. */
+    maskWindowsDrive: boolean;
+    /** Probe the distro's `bwrap`. */
+    usable: (distro: string, signal?: AbortSignal | undefined) => Promise<boolean>;
+    /** Wrap one argv in the profile. */
+    confine: (argv: string[], policy: {
+        mode: "read-only" | "workspace-write";
+        workspaceRoot: string;
+    }, options: {
+        distro: string;
+        signal?: AbortSignal | undefined;
+    }) => Promise<WslConfined>;
+}
+/**
+ * Build the sandbox class, bound to one unavailable-error implementation.
+ *
+ * @param deps - the injected peer surface.
+ * @returns the sandbox class (see `lib/sandbox.js` for the shipped binding).
+ */
+export declare function createSandboxCore({ SandboxUnavailableError }: {
+    /**
+     * The failure type `confine` throws; production binds the peer's class so
+     * `instanceof` consumers keep matching, tests bind a stand-in with the same
+     * `code`.
+     */
+    SandboxUnavailableError: new (mode: "read-only" | "workspace-write", detail?: string) => Error;
+}): new (config?: {
+    wslPath?: string;
+    maskWindowsDrive?: boolean;
+} | undefined) => WslSandboxCoreInstance;