dsh-plugin-wsl-env 0.7.5 → 0.8.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/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,40 @@
+/**
+ * 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.
+     * @returns the verdict; a success is remembered, a failure is not.
+     */
+    run(key: string, probe: () => Promise<boolean> | boolean): Promise<boolean>;
+    /** 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,41 @@
  * 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();
+    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;
+        },
+    };
 }

package/lib/sandbox-core.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 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;

package/lib/sandbox-core.js

@@ -10,20 +10,21 @@
  * 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
  */
-
 import { createProbeCache } from "./probe-cache.js";
 import { toLinuxPath } from "./paths.js";
 import { runCapture } from "./wsl.js";
 import { bwrapArgvPrefix } from "./bwrap.js";
-
 /**
  * bwrap's denial dialect: a write outside the granted mounts fails with EROFS,
  * whose message is "Read-only file system". Classified case-insensitively.
  */
 const DENIAL_SIGNATURES = ["read-only file system"];
-
 /**
  * Runner-side diagnostics. Bubblewrap reports its own failures with a `bwrap: `
  * prefix and exits 1; exit status alone never proves runner failure (the
@@ -31,7 +32,6 @@ const DENIAL_SIGNATURES = ["read-only file system"];
  * command that merely prints the signature is not misread as "never ran".
  */
 const RUNNER_FAILURE_RULES = [{ fatalSignatures: ["bwrap: "] }];
-
 /**
  * Enforcement is **partial**, not `full` like upstream's Linux rung.
  *
@@ -44,7 +44,6 @@ const RUNNER_FAILURE_RULES = [{ fatalSignatures: ["bwrap: "] }];
  * the honest `partial` and README states where the hole is.
  */
 const ENFORCEMENT = "partial";
-
 /**
  * The one mitigation the profile can offer, and its honest ceiling.
  *
@@ -60,98 +59,82 @@ const ENFORCEMENT = "partial";
  * either way, and the mask is a decision an operator makes to shrink the hole,
  * recorded as the `windowsDrive: "masked"` fact the model can see.
  */
-
 /**
  * Probe verdicts, keyed by `wslPath\0distro`. The policy — a success is durable, a
  * failure is re-probed, concurrent probes are shared — lives in `probe-cache.js`,
  * where it is unit-testable without the peers this module needs.
  */
 const probeVerdicts = createProbeCache();
-
 /**
  * Build the sandbox class, bound to one unavailable-error implementation.
  *
- * @param {object} deps - the injected peer surface.
- * @param {new (mode: string, detail: string) => Error} deps.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`.
- * @returns {typeof WslSandboxCore} the sandbox class (see `lib/sandbox.js` for
- *   the shipped binding).
+ * @param deps - the injected peer surface.
+ * @returns the sandbox class (see `lib/sandbox.js` for the shipped binding).
  */
 export function createSandboxCore({ SandboxUnavailableError }) {
-  return class WslSandboxCore {
-    /**
-     * @param config - the `wsl.exe` path, overridable for a non-standard install.
-     * @param config.maskWindowsDrive - shadow `/mnt` with an empty tmpfs in every
-     *   profile this sandbox builds, hiding the Windows drive from confined
-     *   commands (see the module doc above {@link ENFORCEMENT} for what that
-     *   does and does not close).
-     */
-    constructor(config = {}) {
-      this.wslPath = config.wslPath ?? "wsl.exe";
-      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.
-     *
-     * @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;
-      });
-    }
-
-    /**
-     * Wrap one distro-side argv in the bwrap profile the policy asks for.
-     *
-     * The policy's `workspaceRoot` arrives in whichever coordinate system the
-     * caller speaks — a session workspace is a UNC path — and is translated into the
-     * Linux path `bwrap` must bind inside the distro.
-     *
-     * @param argv - the argv to run INSIDE the distro (shell, its flags, command).
-     * @param policy - the resolved confined policy (`mode` is never
-     *   `danger-full-access`; the caller does not confine that case at all).
-     * @param options - the distro to run in and optional cancellation.
-     * @returns the wrapped argv plus the settlement-classification facts, in the
-     *   seam's `ConfinedArgv` shape.
-     * @throws SandboxUnavailableError when the distro has no usable `bwrap`, so a
-     *   requested confinement never degrades into an unconfined run.
-     */
-    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`,
-        );
-      }
-      const workspaceRoot = toLinuxPath(policy.workspaceRoot, { distro });
-      const prefix = bwrapArgvPrefix({ ...policy, workspaceRoot }, { maskWindowsDrive: this.maskWindowsDrive });
-      return {
-        argv: [...prefix, ...argv],
-        enforcement: ENFORCEMENT,
-        denialSignatures: DENIAL_SIGNATURES,
-        runnerFailureRules: RUNNER_FAILURE_RULES,
-        windowsDrive: this.maskWindowsDrive ? "masked" : "visible",
-      };
-    }
-  };
+    return class WslSandboxCore {
+        /**
+         * @param config - the `wsl.exe` path, overridable for a non-standard install.
+         */
+        constructor(config = {}) {
+            this.wslPath = config.wslPath ?? "wsl.exe";
+            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.
+         *
+         * @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;
+            });
+        }
+        /**
+         * Wrap one distro-side argv in the bwrap profile the policy asks for.
+         *
+         * The policy's `workspaceRoot` arrives in whichever coordinate system the
+         * caller speaks — a session workspace is a UNC path — and is translated into the
+         * Linux path `bwrap` must bind inside the distro.
+         *
+         * @param argv - the argv to run INSIDE the distro (shell, its flags, command).
+         * @param policy - the resolved confined policy (`mode` is never
+         *   `danger-full-access`; the caller does not confine that case at all).
+         * @param options - the distro to run in and optional cancellation.
+         * @returns the wrapped argv plus the settlement-classification facts, in the
+         *   seam's `ConfinedArgv` shape.
+         * @throws SandboxUnavailableError when the distro has no usable `bwrap`, so a
+         *   requested confinement never degrades into an unconfined run.
+         */
+        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`);
+            }
+            const workspaceRoot = toLinuxPath(policy.workspaceRoot, { distro });
+            const prefix = bwrapArgvPrefix({ ...policy, workspaceRoot }, { maskWindowsDrive: this.maskWindowsDrive });
+            return {
+                argv: [...prefix, ...argv],
+                enforcement: ENFORCEMENT,
+                denialSignatures: DENIAL_SIGNATURES,
+                runnerFailureRules: RUNNER_FAILURE_RULES,
+                windowsDrive: this.maskWindowsDrive ? "masked" : "visible",
+            };
+        }
+    };
 }

package/lib/sandbox.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The Linux-side confinement this plugin applies to commands that run inside a
+ * distro.
+ *
+ * ## Why this is not `ctx.sandbox`
+ *
+ * DSH's local sandbox provider selects its runner chain by `process.platform`.
+ * This harness process is Windows, so it selects the windows-acl runner — and
+ * that runner's restricted, low-integrity token **cannot reach WSL at all**
+ * (`wsl.exe` fails with `Wsl/E_ACCESSDENIED`). The confinement that governs a
+ * distro command therefore has to be *built* on the host and *executed* inside
+ * the distro, which is what this module produces: an argv whose program is
+ * `bwrap`, handed to `wsl.exe --exec` like any other distro command.
+ *
+ * Consuming the seam is deliberately not part of this: `dsh-tool-bash` reads
+ * `ctx.shell.sandboxMode` (the executor's capability fact) plus
+ * `ctx.sandboxPolicy`, and never asks `ctx.sandbox` for anything. A WSL
+ * executor can therefore own its confinement without shadowing the
+ * composition-level provider that host sessions still need.
+ *
+ * ## Fidelity to the upstream Linux rung
+ *
+ * The profile arguments, the denial dialect and the runner-failure rules mirror
+ * `@deepseek-ai/dsh-sandbox-local`'s `bwrap` rung, so a denial reads the same to
+ * the tool layer whether the command ran on a Linux host or inside a distro.
+ * The one deliberate difference is the core's `partial` enforcement: see
+ * `lib/sandbox-core.js` for what it reports and why.
+ *
+ * The class itself lives in `lib/sandbox-core.js`, free of DSH peers — this
+ * module is the shipped binding that hands it the peer's `SandboxUnavailableError`,
+ * so `instanceof` consumers keep matching the class their composition knows.
+ *
+ * This is a TypeScript source built to `lib/sandbox.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
+ */
+export { bwrapProfileArgs } from "./bwrap.js";
+/**
+ * The confinement over WSL: the probe-then-confine class bound to the peer's
+ * failure type. See the core module for the probe policy and the profile.
+ */
+export declare const WslSandbox: new (config?: {
+    wslPath?: string;
+    maskWindowsDrive?: boolean;
+} | undefined) => import("./sandbox-core.js").WslSandboxCoreInstance;
+export default WslSandbox;