dsh-plugin-wsl-env 0.8.0 → 0.10.0

package/lib/index.js

@@ -47,6 +47,7 @@ import { canonicalPath, classifyRunnerFailure, isRunnerSpawnFailure, matchesSign
 import { isAnotherDistrosUnc, isRelativeWorldPath, isWorldPathUnder, isWslUnc, posixToUnc, toLinuxPath, toWorldPath, uncToPosix, windowsToLinuxMount } from "./paths.js";
 import { isConfinedMutation, mutationModeRefusal, outsideDistroRefusal, shareSubstrateRefusal, substrateFailure, workspaceWriteDenial } from "./fs-decisions.js";
 import { WslSandbox } from "./sandbox.js";
+import { bwrapFailure, missingBwrapRemedy, withBwrapHint } from "./sandbox-core.js";
 import { armDistroWatcher } from "./watcher.js";
 import { AgentUnavailableError } from "./agent-errors.js";
 import { agentExecutionHandle } from "./agent-exec.js";
@@ -54,9 +55,11 @@ import { sharedAgent } from "./agent-shared.js";
 import { AgentSubstrate } from "./fs-substrate.js";
 import { FsCodedError } from "./fsio-text.js";
 import { confinedAgent } from "./agent-confined.js";
+import { SessionRuntimes, probeSessionRuntime, sessionRuntimes, setSessionNativeAgent } from "./session-runtime.js";
+import { configureAgentBackend, ensureNativeSessionAgent } from "./native-agent.js";
 // `runCapture` and distro discovery live in ./wsl.js so the directory picker
 // can use them without pulling this file's executor and filesystem peers in.
-import { defaultDistro, defaultShell, linuxHomePath, shellArgs, workdirFailure, wslErrorCode } from "./wsl.js";
+import { defaultDistro, defaultShell, linuxHomePath, runCapture, shellArgs, workdirFailure, wslErrorCode } from "./wsl.js";
 /**
  * Every model shell call gets a rebuilt managed `DSH_*` namespace (see
  * `dsh-shell-env` / `ctx.shellEnv`). Those names exist only in the Windows-side
@@ -81,6 +84,14 @@ const SAFE_FORWARD = ["NO_COLOR", "TERM", "PAGER", "GIT_PAGER", "LANG", "LC_ALL"
  * @param config - a provider's config.
  * @returns the configured directory, trimmed, or `""`.
  */
+/**
+ * Opt into the native agent for one distro when `DSH_WSL_AGENT_NATIVE` names a
+ * host binary. The copy/verify is cached in `native-agent.ts`; a failure (or
+ * an unset variable) leaves the shell agent in place.
+ *
+ * @param wslPath - the `wsl.exe` path.
+ * @param distro - the resolved distro.
+ */
 function configuredCwd(config) {
     return String(config.cwd?.get?.() ?? "").trim();
 }
@@ -212,6 +223,17 @@ export class WslShellExecutor extends LocalBashExecutor {
          * decoration are identical on both paths.
          */
         agent: z.boolean().default(true),
+        agentBackend: z.union(["auto", "native", "shell"]).default("auto"),
+        /**
+         * Run this session's commands in one persistent systemd user scope (ADR
+         * 0001): background processes survive the command that started them, `/tmp`
+         * is the distro's real `/tmp` under workspace-write, and `ps` sees the
+         * session. The executor holds the runtime until the session's scope
+         * disposes, then stops it. Requires systemd, a reachable user manager and
+         * `Linger`; the preflight refuses with the remedy when one is missing, and
+         * only a success is cached. Off by default; requires `agent: true`.
+         */
+        sessionSandbox: z.boolean().default(false),
     });
     /**
      * @param ctx - the composition context.
@@ -219,12 +241,20 @@ export class WslShellExecutor extends LocalBashExecutor {
      */
     constructor(ctx, config) {
         super(ctx, config);
+        configureAgentBackend(config.agentBackend ?? "auto");
         this.resolvedDistro = config.distro;
         this.resolvedShell = config.shell;
         this.resolvedHome = undefined;
         this.mode = config.sandbox ? ctx.sandboxPolicy.defaultMode : undefined;
         this.sandbox = config.sandbox ? new WslSandbox({ wslPath: config.wslPath }) : undefined;
         this.processFacts = new Map();
+        this.sessionRuntimes = sessionRuntimes;
+        this.sessionRuntimeEntries = new Map();
+        this.sessionScopeProbe = (argv) => runCapture(argv);
+        this.sessionRuntimePreflight = "unknown";
+        // The preset realm disposes when the session ends; the scope must go with
+        // it, or a dev server outlives the session that started it.
+        ctx.effect(() => () => this.disposeSessionRuntimes().catch(() => { }), "wsl session runtimes");
     }
     /**
      * The mode this executor confines with, or `undefined` when it does not
@@ -301,6 +331,71 @@ export class WslShellExecutor extends LocalBashExecutor {
     executionAgent(distro) {
         return sharedAgent(distro);
     }
+    /**
+     * The persistent session runtime for one policy, when `sessionSandbox` is
+     * on. The executor holds one reference per `(distro, workspace, policy)` and
+     * releases them when the session's scope disposes.
+     *
+     * @param policy - the resolved file-effect policy, when the executor has one.
+     * @param resolved - the resolved spec, for the fallback workspace.
+     * @param distro - the resolved distro name.
+     * @returns the runtime entry, or undefined when the mode is off.
+     */
+    sessionRuntimeFor(policy, resolved, distro) {
+        const config = this.config;
+        if (!config.sessionSandbox)
+            return undefined;
+        const mode = policy?.mode ?? "danger-full-access";
+        const workspaceRoot = policy?.workspaceRoot ?? (configuredCwd(this.config) || resolved.workdir);
+        const key = SessionRuntimes.key({ distro, workspaceRoot, mode, maskWindowsDrive: config.maskWindowsDrive });
+        const held = this.sessionRuntimeEntries.get(key);
+        if (held !== undefined)
+            return held;
+        const entry = this.sessionRuntimes.acquire({
+            distro,
+            wslPath: config.wslPath,
+            workspaceRoot,
+            mode,
+            maskWindowsDrive: config.maskWindowsDrive,
+        });
+        this.sessionRuntimeEntries.set(key, entry);
+        return entry;
+    }
+    /**
+     * Run the session runtime's preflight once per executor. A failure is a
+     * configuration verdict, not an agent outage: it is raised as an Error with
+     * the remedy, so the command fails closed instead of falling back to the
+     * per-command sandbox. Only success is cached, so a user who follows the
+     * remedy (`loginctl enable-linger`, `[boot] systemd=true`) does not need to
+     * restart the app.
+     *
+     * @param distro - the resolved distro name.
+     * @returns resolved once the platform can host a session runtime.
+     * @throws {Error} with the remedy when it cannot.
+     */
+    async ensureSessionRuntimeUsable(distro) {
+        if (this.sessionRuntimePreflight === "ready")
+            return;
+        const config = this.config;
+        const problem = await probeSessionRuntime({ wslPath: config.wslPath, distro, run: this.sessionScopeProbe });
+        if (problem !== null)
+            throw new Error(problem);
+        await ensureNativeSessionAgent({ wslPath: config.wslPath, distro, setNative: setSessionNativeAgent });
+        this.sessionRuntimePreflight = "ready";
+    }
+    /**
+     * Release every runtime this executor holds, stopping each scope. Called
+     * from the session's dispose hook; public so tests and shutdown paths can
+     * await it.
+     *
+     * @returns resolved once every runtime is torn down.
+     */
+    async disposeSessionRuntimes() {
+        const entries = [...this.sessionRuntimeEntries.values()];
+        this.sessionRuntimeEntries.clear();
+        for (const entry of entries)
+            await this.sessionRuntimes.release(entry.key);
+    }
     /**
      * The argv that runs INSIDE the distro for one spec: the resolved shell, its
      * login/command flags, and the command string. This is the argv a
@@ -603,14 +698,25 @@ export class WslShellExecutor extends LocalBashExecutor {
             ? await this.sandbox.confine(this.distroArgv(resolved, shell), { ...policy, mode: policy.mode }, { distro, signal: resolved.signal })
             : undefined;
         const mode = policy?.mode;
+        if (config.sessionSandbox)
+            await this.ensureSessionRuntimeUsable(distro);
+        const runtime = this.sessionRuntimeFor(policy, resolved, distro);
+        const agent = runtime !== undefined ? runtime.agent : await this.executionAgent(distro);
+        // A session runtime's own bwrap profile applies the mounts, so the
+        // command must NOT be wrapped a second time: the per-command probe still
+        // runs (it is the bwrap availability check and the denial facts), but its
+        // argv is discarded.
+        const argv = runtime !== undefined
+            ? this.distroArgv(resolved, shell)
+            : confined !== undefined ? confined.argv : this.distroArgv(resolved, shell);
         const execution = agentExecutionHandle({
-            agent: await this.executionAgent(distro),
+            agent,
             // The one-shot path converts the spec's workdir into the distro's
             // coordinate system inside argv(); the agent carries the cwd as a frame
             // field, so the SAME conversion happens here — a raw UNC must never
             // reach `chdir` (that is the bug this line fixes).
             cwd: toLinuxPath(resolved.workdir, { distro }),
-            argv: confined !== undefined ? confined.argv : this.distroArgv(resolved, shell),
+            argv,
             timeoutMs: resolved.timeoutMs,
             // The agent enforces the collect budget distro-side (the EXEC frame
             // carries it); `maxSpillBytes` stays one-shot-only — the agent path has
@@ -649,7 +755,10 @@ export class WslShellExecutor extends LocalBashExecutor {
             const { enforcement, denialSignatures, runnerFailureRules, windowsDrive } = confined;
             const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
             if (runnerFailure !== undefined) {
-                throw new SandboxUnavailableError(mode, runnerFailure.detail);
+                // This path computes `mode` as `policy?.mode`, which the seam spells as
+                // the wider union: a runner failure is only ever thrown under a
+                // confinement, and there the mode is one of the two confined ones.
+                throw new SandboxUnavailableError(mode, withBwrapHint(runnerFailure.detail, distro));
             }
             return ({
                 ...result,
@@ -732,7 +841,7 @@ export class WslShellExecutor extends LocalBashExecutor {
             // Runner failure outranks denial because the command did not run at all.
             const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
             if (runnerFailure !== undefined)
-                throw new SandboxUnavailableError(mode, runnerFailure.detail);
+                throw new SandboxUnavailableError(mode, withBwrapHint(runnerFailure.detail, distro));
             return ({
                 ...result,
                 sandbox: {
@@ -747,7 +856,7 @@ export class WslShellExecutor extends LocalBashExecutor {
             if (resolved.signal?.aborted === true)
                 resolved.signal.throwIfAborted();
             if (confined !== undefined && isRunnerSpawnFailure(error, confined.argv[0], resolved.workdir)) {
-                throw new SandboxUnavailableError(mode, String(error));
+                throw new SandboxUnavailableError(mode, withBwrapHint(String(error), distro));
             }
             throw error;
         });
@@ -776,6 +885,17 @@ export class WslFileSystem extends LocalFileSystem {
          * operations are unconfined.
          */
         sandbox: z.boolean().default(true),
+        /**
+         * Run confined mutations in the session's systemd user scope — the same
+         * runtime the shell executor acquires for the same (distro, workspace,
+         * policy) — instead of a per-policy confined resident. The kernel
+         * enforcement is the runtime's mount profile, so commands and writes see
+         * the same `/tmp` and workspace; the scope stops when the session's
+         * providers release it. Requires systemd + `Linger`, like `wsl-shell`'s
+         * `sessionSandbox`; the preflight refuses with the remedy. Off for direct
+         * constructions; on in the shipped preset.
+         */
+        sessionSandbox: z.boolean().default(false),
         /**
          * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
          * Windows drive from confined commands — same meaning and same honest
@@ -835,6 +955,13 @@ export class WslFileSystem extends LocalFileSystem {
         this.agentSubstrateInstance = undefined;
         this.sandbox = new WslSandbox({ wslPath: config.wslPath, maskWindowsDrive: config.maskWindowsDrive });
         this.agentInstance = undefined;
+        this.sessionRuntimes = sessionRuntimes;
+        this.sessionRuntimeEntries = new Map();
+        this.sessionScopeProbe = (argv) => runCapture(argv);
+        this.sessionRuntimePreflight = "unknown";
+        // The preset's disposer releases the runtime; the shell executor's effect
+        // releases its own reference, so the scope stops after the last one.
+        ctx.effect(() => () => this.disposeSessionRuntimes().catch(() => { }), "wsl fs session runtimes");
     }
     /**
      * The mode this backend fences mutations with, or `undefined` when the
@@ -879,6 +1006,65 @@ export class WslFileSystem extends LocalFileSystem {
         }
         return this.agentSubstrateInstance;
     }
+    /**
+     * The persistent session runtime for one confined mutation, when
+     * `sessionSandbox` is on. The key is the shell executor's key for the same
+     * session/policy, so the write and the commands share one agent, one mount
+     * view and one scope; the provider holds a reference until the session ends.
+     *
+     * @param policy - the resolved confined policy.
+     * @param distro - the resolved distro name.
+     * @returns the runtime entry, or undefined when the mode is off.
+     */
+    sessionRuntimeFor(policy, distro) {
+        const config = this.config;
+        if (!config.sessionSandbox)
+            return undefined;
+        const workspaceRoot = policy.workspaceRoot || config.cwd;
+        const key = SessionRuntimes.key({ distro, workspaceRoot, mode: policy.mode, maskWindowsDrive: config.maskWindowsDrive });
+        const held = this.sessionRuntimeEntries.get(key);
+        if (held !== undefined)
+            return held;
+        const entry = this.sessionRuntimes.acquire({
+            distro,
+            wslPath: config.wslPath,
+            workspaceRoot,
+            mode: policy.mode,
+            maskWindowsDrive: config.maskWindowsDrive,
+        });
+        this.sessionRuntimeEntries.set(key, entry);
+        return entry;
+    }
+    /**
+     * Run the session runtime's preflight once per provider. Only success is
+     * cached, so following the remedy does not need an app restart.
+     *
+     * @param distro - the resolved distro name.
+     * @returns resolved once the platform can host the runtime.
+     * @throws {Error} with the remedy when it cannot.
+     */
+    async ensureSessionRuntimeUsable(distro) {
+        if (this.sessionRuntimePreflight === "ready")
+            return;
+        const config = this.config;
+        const problem = await probeSessionRuntime({ wslPath: config.wslPath, distro, run: this.sessionScopeProbe });
+        if (problem !== null)
+            throw new Error(problem);
+        await ensureNativeSessionAgent({ wslPath: config.wslPath, distro, setNative: setSessionNativeAgent });
+        this.sessionRuntimePreflight = "ready";
+    }
+    /**
+     * Release every runtime this provider holds. Called from the preset's
+     * dispose effect; public so tests and shutdown paths can await it.
+     *
+     * @returns resolved once every reference is released.
+     */
+    async disposeSessionRuntimes() {
+        const entries = [...this.sessionRuntimeEntries.values()];
+        this.sessionRuntimeEntries.clear();
+        for (const entry of entries)
+            await this.sessionRuntimes.release(entry.key);
+    }
     /**
      * The agent a MUTATION runs on under this resolved policy — stage-two
      * routing. A confined policy addresses the confined resident whose bwrap
@@ -903,9 +1089,16 @@ export class WslFileSystem extends LocalFileSystem {
         const confinedPolicy = policy;
         const distro = await this.distro();
         if (!(await this.sandbox.usable(distro))) {
-            throw new SandboxUnavailableError(confinedPolicy.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`);
+            // The probe's classified remedy — missing vs present-but-broken, with the
+            // distro's own package family — is what every other refusal surfaces;
+            // this path has the same failure, so it carries the same text.
+            throw new SandboxUnavailableError(confinedPolicy.mode, bwrapFailure(config.wslPath, distro) ?? missingBwrapRemedy(distro));
+        }
+        if (config.sessionSandbox) {
+            await this.ensureSessionRuntimeUsable(distro);
+            const runtime = this.sessionRuntimeFor(confinedPolicy, distro);
+            if (runtime !== undefined)
+                return runtime.agent;
         }
         return confinedAgent({ distro, wslPath: config.wslPath, policy: confinedPolicy, maskWindowsDrive: config.maskWindowsDrive });
     }

package/lib/native-agent.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Host-side plumbing for the optional native in-distro agent (ADR 0002).
+ *
+ * The shell agent is the shipped peer. This module is the opt-in path that
+ * lets the host run the spike/native binary instead, for the session runtime
+ * only:
+ *
+ *   1. read the binary from a host path (`DSH_WSL_AGENT_NATIVE`);
+ *   2. sha256 it and refuse an architecture the binary was not built for;
+ *   3. stream it into `~/.cache/dsh-wsl/agent/<sha>/dsh-wsl-agent` inside the
+ *      distro, chmod 0755, and verify the distro-side digest;
+ *   4. hand the resulting Linux path to the session-runtime factory.
+ *
+ * The binary is never executed from `/mnt/c` (DrvFs is often `noexec`), and a
+ * failed copy falls back to the shell agent — this module never throws to the
+ * command path.
+ *
+ * This is a TypeScript source built to `lib/native-agent.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/native-agent
+ */
+/** The host environment variable naming the native binary to opt in. */
+export declare const NATIVE_AGENT_ENV = "DSH_WSL_AGENT_NATIVE";
+/**
+ * The in-distro copy/verify script. The digest is embedded so `sh` needs no
+ * second argument and the cache path is derived from the content; stdout is
+ * the final Linux path the session runtime should execute.
+ *
+ * @param digest - lowercase hex sha256 of the binary.
+ * @returns the `sh -c` body (binary on stdin).
+ */
+export declare function nativeCacheScript(digest: string): string;
+/** The injectable edges. */
+export interface NativeBackendOptions {
+    /** The `wsl.exe` path. */
+    wslPath: string;
+    /** The distro. */
+    distro: string;
+    /**
+     * The host path override (the development variable); empty resolves the
+     * packaged binary for the distro's architecture.
+     */
+    source: string;
+    /** The plugin package root; tests and non-standard layouts substitute it. */
+    packageRoot?: string;
+    /** Read the binary (tests substitute). */
+    readSource?: (path: string) => Promise<Buffer>;
+    /** Run a host command and return stdout (tests substitute). */
+    run?: (argv: string[]) => Promise<string>;
+    /** Copy the binary and return the Linux path (tests substitute). */
+    copy?: (script: string, binary: Buffer) => Promise<string>;
+}
+/** A prepared native binary: its in-distro path and the sha256 of its bytes. */
+export interface NativeBackendResult {
+    /** The Linux path the session runtime spawns. */
+    path: string;
+    /** Lowercase hex sha256; the agent's HELLO digest must match it. */
+    digest: string;
+}
+/**
+ * Copy the binary into the distro and verify it. The result is cached per
+ * `(wslPath, distro, source)`; a failure is cached as `undefined` for this
+ * process (the caller falls back to the shell agent).
+ *
+ * @param options - the transport, distro, source and injectables.
+ * @returns the Linux binary path and digest, or undefined when unusable.
+ */
+export declare function ensureNativeBackend({ wslPath, distro, source, packageRoot, readSource, run, copy, }: NativeBackendOptions): Promise<NativeBackendResult | undefined>;
+/**
+ * Forget the cache; tests only.
+ */
+export declare function clearNativeBackendCache(): void;
+/**
+ * Stream the binary to the distro on stdin, run the copy/verify script and
+ * return its stdout (the cache path).
+ *
+ * Exported for its regression check; the copy path is injectable in
+ * {@link ensureNativeBackend}.
+ *
+ * @param wslPath - the `wsl.exe` path.
+ * @param distro - the distro.
+ * @param script - the copy/verify script.
+ * @param binary - the binary bytes.
+ * @returns the Linux path printed by the script.
+ */
+export declare function copyBinary(wslPath: string, distro: string, script: string, binary: Buffer): Promise<string>;
+/** The session runtime's agent backend, from `wsl-shell.agentBackend`. */
+export type AgentBackend = "auto" | "native" | "shell";
+/**
+ * Record the selected backend. The session runtime is shared by the shell and
+ * filesystem providers, so this one process-wide value is what both read when
+ * they prepare their runtime; it is set from the `wsl-shell` config.
+ *
+ * @param mode - the selected backend.
+ */
+export declare function configureAgentBackend(mode: AgentBackend): void;
+/** @returns the configured backend (for diagnostics and tests). */
+export declare function configuredAgentBackend(): AgentBackend;
+/**
+ * Select the native binary for a distro when the backend allows it.
+ *
+ * - `shell`: clear any native entry and use the shipped shell agent.
+ * - `auto`: use the native binary when a source exists and copy/verify
+ *   succeeds; otherwise stay on the shell agent.
+ * - `native`: same preparation, but a missing source or a failed preparation
+ *   throws a remedy instead of silently falling back.
+ *
+ * The source is the development override `DSH_WSL_AGENT_NATIVE`; the packaged
+ * per-arch binary will be added by the packaging task and preferred over it.
+ *
+ * @param options - the transport, distro, setter and injectable prepare step.
+ */
+export declare function ensureNativeSessionAgent({ wslPath, distro, setNative, ensure, }: {
+    /** The `wsl.exe` path. */
+    wslPath: string;
+    /** The resolved distro. */
+    distro: string;
+    /** Store (or clear, with an empty path) the distro's native entrypoint. */
+    setNative: (distro: string, path: string, digest: string) => void;
+    /** Prepare the binary; tests substitute. */
+    ensure?: (options: NativeBackendOptions) => Promise<NativeBackendResult | undefined>;
+}): Promise<void>;

package/lib/native-agent.js

@@ -0,0 +1,198 @@
+/**
+ * Host-side plumbing for the optional native in-distro agent (ADR 0002).
+ *
+ * The shell agent is the shipped peer. This module is the opt-in path that
+ * lets the host run the spike/native binary instead, for the session runtime
+ * only:
+ *
+ *   1. read the binary from a host path (`DSH_WSL_AGENT_NATIVE`);
+ *   2. sha256 it and refuse an architecture the binary was not built for;
+ *   3. stream it into `~/.cache/dsh-wsl/agent/<sha>/dsh-wsl-agent` inside the
+ *      distro, chmod 0755, and verify the distro-side digest;
+ *   4. hand the resulting Linux path to the session-runtime factory.
+ *
+ * The binary is never executed from `/mnt/c` (DrvFs is often `noexec`), and a
+ * failed copy falls back to the shell agent — this module never throws to the
+ * command path.
+ *
+ * This is a TypeScript source built to `lib/native-agent.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/native-agent
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pinnedWindowsEnv } from "./agent.js";
+import { runCapture } from "./wsl.js";
+/** The host environment variable naming the native binary to opt in. */
+export const NATIVE_AGENT_ENV = "DSH_WSL_AGENT_NATIVE";
+/** Distro `uname -m` values mapped to the packaged directory names. */
+const ARCHS = new Map([
+    ["x86_64", "x86_64"],
+    ["amd64", "x86_64"],
+    ["aarch64", "aarch64"],
+    ["arm64", "aarch64"],
+]);
+/** The plugin package root: `lib/native-agent.js` -> `<root>`. */
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+/**
+ * The in-distro copy/verify script. The digest is embedded so `sh` needs no
+ * second argument and the cache path is derived from the content; stdout is
+ * the final Linux path the session runtime should execute.
+ *
+ * @param digest - lowercase hex sha256 of the binary.
+ * @returns the `sh -c` body (binary on stdin).
+ */
+export function nativeCacheScript(digest) {
+    return [
+        "set -e",
+        "umask 077",
+        `dir="$HOME/.cache/dsh-wsl/agent/${digest}"`,
+        'target="$dir/dsh-wsl-agent"',
+        // A live session already runs this exact binary; rewriting it would fail
+        // with ETXTBSY. A valid cache is the same verified artifact, so reuse it.
+        `if [ -x "$target" ] && [ "$(sha256sum "$target" | cut -d' ' -f1)" = "${digest}" ]; then printf '%s' "$target"; exit 0; fi`,
+        'mkdir -p "$dir"',
+        'cat > "$target"',
+        'chmod 0755 "$target"',
+        "got=$(sha256sum \"$target\" | cut -d' ' -f1)",
+        `[ "$got" = "${digest}" ] || { echo digest-mismatch >&2; exit 1; }`,
+        '"$target" </dev/null >/dev/null 2>&1 || { echo cannot-execute >&2; exit 1; }',
+        'printf "%s" "$target"',
+    ].join("\n");
+}
+/**
+ * Copy the binary into the distro and verify it. The result is cached per
+ * `(wslPath, distro, source)`; a failure is cached as `undefined` for this
+ * process (the caller falls back to the shell agent).
+ *
+ * @param options - the transport, distro, source and injectables.
+ * @returns the Linux binary path and digest, or undefined when unusable.
+ */
+export async function ensureNativeBackend({ wslPath, distro, source, packageRoot = PACKAGE_ROOT, readSource = readFile, run = (argv) => runCapture(argv), copy, }) {
+    const key = `${wslPath}\u0000${distro}\u0000${source}\u0000${packageRoot}`;
+    const cached = NATIVE_CACHE.get(key);
+    if (cached !== undefined)
+        return cached;
+    const pending = (async () => {
+        const arch = (await run([wslPath, "-d", distro, "--exec", "uname", "-m"])).trim();
+        const normalized = ARCHS.get(arch);
+        if (normalized === undefined)
+            return undefined;
+        const hostPath = source.length > 0 ? source : join(packageRoot, "agent", "native", `linux-${normalized}`, "dsh-wsl-agent");
+        const binary = await readSource(hostPath);
+        const digest = createHash("sha256").update(binary).digest("hex");
+        const install = copy ?? ((script, bytes) => copyBinary(wslPath, distro, script, bytes));
+        const path = await install(nativeCacheScript(digest), binary);
+        return path.length > 0 ? { path, digest } : undefined;
+    })().catch(() => undefined);
+    NATIVE_CACHE.set(key, pending);
+    return pending;
+}
+/** The per-process cache; a failure is remembered as undefined. */
+const NATIVE_CACHE = new Map();
+/**
+ * Forget the cache; tests only.
+ */
+export function clearNativeBackendCache() {
+    NATIVE_CACHE.clear();
+}
+/**
+ * Stream the binary to the distro on stdin, run the copy/verify script and
+ * return its stdout (the cache path).
+ *
+ * Exported for its regression check; the copy path is injectable in
+ * {@link ensureNativeBackend}.
+ *
+ * @param wslPath - the `wsl.exe` path.
+ * @param distro - the distro.
+ * @param script - the copy/verify script.
+ * @param binary - the binary bytes.
+ * @returns the Linux path printed by the script.
+ */
+export function copyBinary(wslPath, distro, script, binary) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(wslPath, ["-d", distro, "--exec", "sh", "-c", script, "sh"], {
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+            env: pinnedWindowsEnv(process.env),
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolve(stdout.trim());
+            else
+                reject(new Error(stderr.trim() || `native agent copy exited with ${code}`));
+        });
+        // The script prints the cached path and exits WITHOUT reading stdin when
+        // the in-distro digest already matches. On Windows, finishing the binary
+        // write against that closed pipe surfaces as `write EOF` on stdin, and an
+        // unhandled stream error would take down the host process. The exit code
+        // and stdout above already decide the result, so absorb the write error.
+        child.stdin?.on("error", () => { });
+        try {
+            child.stdin?.end(binary);
+        }
+        catch {
+            // A pipe that is already gone is the same warm-cache case.
+        }
+    });
+}
+/** The process-wide mode; the shell executor's constructor owns it. */
+let backend = "auto";
+/**
+ * Record the selected backend. The session runtime is shared by the shell and
+ * filesystem providers, so this one process-wide value is what both read when
+ * they prepare their runtime; it is set from the `wsl-shell` config.
+ *
+ * @param mode - the selected backend.
+ */
+export function configureAgentBackend(mode) {
+    backend = mode;
+}
+/** @returns the configured backend (for diagnostics and tests). */
+export function configuredAgentBackend() {
+    return backend;
+}
+/**
+ * Select the native binary for a distro when the backend allows it.
+ *
+ * - `shell`: clear any native entry and use the shipped shell agent.
+ * - `auto`: use the native binary when a source exists and copy/verify
+ *   succeeds; otherwise stay on the shell agent.
+ * - `native`: same preparation, but a missing source or a failed preparation
+ *   throws a remedy instead of silently falling back.
+ *
+ * The source is the development override `DSH_WSL_AGENT_NATIVE`; the packaged
+ * per-arch binary will be added by the packaging task and preferred over it.
+ *
+ * @param options - the transport, distro, setter and injectable prepare step.
+ */
+export async function ensureNativeSessionAgent({ wslPath, distro, setNative, ensure = ensureNativeBackend, }) {
+    if (backend === "shell") {
+        setNative(distro, "", "");
+        return;
+    }
+    const result = await ensure({ wslPath, distro, source: process.env[NATIVE_AGENT_ENV] ?? "" });
+    if (result === undefined) {
+        if (backend === "native") {
+            throw new Error(`agentBackend: "native" could not prepare a native binary: the packaged binary for this architecture is missing or failed the copy/digest/execute check, and ${NATIVE_AGENT_ENV} is unset or unusable; set a valid ${NATIVE_AGENT_ENV}, or use "auto"/"shell".`);
+        }
+        return;
+    }
+    setNative(distro, result.path, result.digest);
+}

package/lib/ports.d.ts

@@ -38,7 +38,18 @@ export declare function procNetScript(): string;
  *
  * @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 declare function scanListeningPorts(runner: AgentExecRunner, timeoutMs?: number): Promise<number[] | 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 declare function listeningPorts(runner: AgentExecRunner, timeoutMs?: number): Promise<number[]>;