dsh-plugin-wsl-env 0.9.0 → 0.10.0

package/lib/fs-routing.js

@@ -39,6 +39,47 @@ import { WslFileSystem } from "./index.js";
  * @param targetKey - the target's identity (a UNC for distro paths).
  * @returns true when the target lives inside a WSL distro.
  */
+/**
+ * Lexically normalize a Linux path (`/a/./b/../c` → `/a/c`). The resolver
+ * canonicalizes real paths, so this is a guard for target keys that did not
+ * come through it; it cannot follow symlinks, and does not pretend to.
+ *
+ * @param path - the Linux path.
+ * @returns the normalized absolute path.
+ */
+function normalizeLinuxPath(path) {
+    const segments = [];
+    for (const segment of path.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..")
+            segments.pop();
+        else
+            segments.push(segment);
+    }
+    return `/${segments.join("/")}`;
+}
+/**
+ * Whether a distro target contains another, comparing BOTH the distro
+ * coordinate and the normalized Linux path. A child in another distro's
+ * share is never contained, even when its Linux spelling is a prefix match —
+ * the textual check this replaces said yes there.
+ *
+ * @param parentKey - the parent's UNC identity.
+ * @param childKey - the child's UNC identity.
+ * @returns true when the child is the parent or lies under it in the same distro.
+ */
+export function distroContains(parentKey, childKey) {
+    const parent = uncToPosix(parentKey);
+    const child = uncToPosix(childKey);
+    if (parent === undefined || child === undefined)
+        return false;
+    if (parent.distro.toLowerCase() !== child.distro.toLowerCase())
+        return false;
+    const base = normalizeLinuxPath(parent.linuxPath);
+    const full = normalizeLinuxPath(child.linuxPath);
+    return full === base || full.startsWith(base.endsWith("/") ? base : `${base}/`);
+}
 export function targetIsDistro(targetKey) {
     return isWslUnc(targetKey);
 }
@@ -61,23 +102,46 @@ export function inputIsDistro(value) {
  */
 export class WslRoutingFileSystem extends LocalFileSystem {
     static Config = LocalFileSystem.Config;
+    /**
+     * The routed backend's constructor reads the deployment default mode from
+     * `ctx.sandboxPolicy`, exactly as the shipped `fs-sandbox` row this class
+     * replaces does. The service is provided by a sibling row, not an ancestor,
+     * so the fiber must declare the dependency; without it the lazy backend
+     * construction fails with "cannot get property sandboxPolicy without inject".
+     */
+    static inject = ["sandboxPolicy"];
     /**
      * The lazy distro backend, built on first routed use, typed as the concrete
      * class: these routing calls are that class's own surface, and the
      * `processPathFromHostPath` seam it once could not satisfy (async against the
      * peer interface's synchronous contract) is closed — the backend maps
      * synchronously now, from what it already knows.
+     *
+     * Plain fields on purpose: cordis invokes a service method with a shadow
+     * receiver (the traceable proxy `ReflectService` builds), and `#private`
+     * members do not cross it — every routed root call then fails with "Cannot
+     * read private member #distro from an object whose class did not declare it".
+     * The host backend this class extends keeps its own state plain (`config`,
+     * `locks`) for the same reason.
      */
-    #distro;
+    distroBackend;
     /** The distro knobs, verbatim from the row config. */
-    #distroConfig;
+    distroConfig;
+    /**
+     * The context this router was constructed with. `this.ctx` inside a method is
+     * the CALLER's context (cordis re-binds it for dependency tracing), so the
+     * backend's scope must not be derived from it: the first routed call may come
+     * from any consumer fiber.
+     */
+    routeContext;
     /**
      * @param ctx - the cordis context.
      * @param config - the row config, host knobs plus distro knobs.
      */
     constructor(ctx, config) {
         super(ctx, config);
-        this.#distroConfig = {
+        this.routeContext = ctx;
+        this.distroConfig = {
             distro: config.distro ?? "",
             wslPath: config.wslPath ?? "wsl.exe",
             cwd: config.distroCwd ?? "",
@@ -86,11 +150,21 @@ export class WslRoutingFileSystem extends LocalFileSystem {
             maskWindowsDrive: config.maskWindowsDrive ?? false,
             restrictToDistro: config.restrictToDistro ?? true,
             watchMaxDepth: config.watchMaxDepth ?? 0,
+            // The root router is app-level, not session-owned: its backend must not
+            // acquire a session runtime (that would live for the app, not the
+            // session). Preset-scoped `wsl-fs` is the owner of the session runtime.
+            sessionSandbox: false,
         };
     }
     /** The distro backend for routed targets, built on first use. */
     distro() {
-        return (this.#distro ??= new WslFileSystem(this.ctx, this.#distroConfig));
+        // The backend is a `Service` that registers itself as `fs`. Constructing it
+        // with this router's own context would collide with the router's
+        // registration ("service fs has been registered"), so it gets a scope of its
+        // own: the backend is used directly through this field, never resolved as
+        // the context's `fs`. Isolation re-keys only `fs`; `sandboxPolicy`, which
+        // the backend reads, still resolves from the parent scope.
+        return (this.distroBackend ??= new WslFileSystem(this.routeContext.isolate("fs"), this.distroConfig));
     }
     /**
      * @param path - the requested path.
@@ -210,14 +284,8 @@ export class WslRoutingFileSystem extends LocalFileSystem {
      * @param child - the contained candidate.
      */
     contains(parent, child) {
-        if (targetIsDistro(parent.targetKey)) {
-            // Both targets came from this router's distro resolve, so the plain
-            // POSIX containment over their process paths is the same check the
-            // distro substrate performs for its own guarded writes.
-            const base = this.processPath(parent);
-            const full = this.processPath(child);
-            return full === base || full.startsWith(base.endsWith("/") ? base : `${base}/`);
-        }
+        if (targetIsDistro(parent.targetKey))
+            return distroContains(parent.targetKey, child.targetKey);
         return super.contains(parent, child);
     }
     /**

package/lib/fsio-agent.js

@@ -72,7 +72,7 @@ export function parseStatRecord(stdout) {
 }
 const REASON_CODES = {
     notfound: "FS_NOT_FOUND",
-    notdir: "FS_NOT_FOUND",
+    notdir: "FS_NOT_DIRECTORY",
     perm: "FS_IO_ERROR",
     loop: "FS_IO_ERROR",
     exists: "FS_NOT_OBSERVED",

package/lib/index.d.ts

@@ -46,6 +46,9 @@ import { FsError } from "@deepseek-ai/dsh-fs";
 import { WslSandbox } from "./sandbox.js";
 import type { WslAgent } from "./agent.js";
 import { AgentSubstrate } from "./fs-substrate.js";
+import { SessionRuntimes } from "./session-runtime.js";
+import type { AgentBackend } from "./native-agent.js";
+import type { SessionRuntimeEntry } from "./session-runtime.js";
 import type { Context } from "@deepseek-ai/cordis";
 import type { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsTarget, FsVersion, FsWriteIntent, FsWriteOutcome } from "@deepseek-ai/dsh-fs";
 import type { SandboxExecutionPolicy, SandboxMode } from "@deepseek-ai/dsh-sandbox";
@@ -125,6 +128,10 @@ export interface WslShellExecutorConfig {
     };
     /** Whether execution prefers the resident agent. */
     agent: boolean;
+    /** Whether commands run in one persistent session scope (ADR 0001). */
+    sessionSandbox: boolean;
+    /** The session runtime's agent backend; `auto` when omitted. */
+    agentBackend?: AgentBackend;
 }
 /**
  * The upstream executor's spawn-spec builder, re-opened for this subclass —
@@ -230,6 +237,17 @@ export declare class WslShellExecutor extends LocalBashExecutor {
          * decoration are identical on both paths.
          */
         agent: z<boolean, boolean, "defined">;
+        agentBackend: z<"auto" | "native" | "shell", "auto" | "native" | "shell", "defined">;
+        /**
+         * 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, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
         /** Distro name; empty means WSL's own default distro. */
         distro: z<string, string, "defined">;
@@ -294,6 +312,17 @@ export declare class WslShellExecutor extends LocalBashExecutor {
          * decoration are identical on both paths.
          */
         agent: z<boolean, boolean, "defined">;
+        agentBackend: z<"auto" | "native" | "shell", "auto" | "native" | "shell", "defined">;
+        /**
+         * 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, boolean, "defined">;
     }>>, "plain">;
     /** Cached default distro, resolved once from `wsl.exe -l -q`. */
     resolvedDistro: string;
@@ -305,6 +334,14 @@ export declare class WslShellExecutor extends LocalBashExecutor {
     mode: SandboxMode | undefined;
     /** The distro-side confinement, or nothing when the operator opted out. */
     sandbox: InstanceType<typeof WslSandbox> | undefined;
+    /** The session-runtime registry; tests substitute it. */
+    sessionRuntimes: SessionRuntimes;
+    /** The runtimes this executor holds, by registry key. */
+    sessionRuntimeEntries: Map<string, SessionRuntimeEntry>;
+    /** The preflight's host runner; tests substitute it. */
+    sessionScopeProbe: (argv: string[]) => Promise<string>;
+    /** The last preflight verdict; only a success is cached. */
+    sessionRuntimePreflight: "unknown" | "ready";
     /**
      * Per-process confinement facts retained until settlement. Overlapping calls
      * can carry different policies, so a shared latest-wrap value would classify
@@ -358,6 +395,41 @@ export declare class WslShellExecutor extends LocalBashExecutor {
      * @returns the shared agent.
      */
     executionAgent(distro: string): WslAgent;
+    /**
+     * 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: {
+        mode: string;
+        workspaceRoot: string;
+    } | undefined, resolved: WslExecSpec, distro: string): SessionRuntimeEntry | undefined;
+    /**
+     * 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.
+     */
+    ensureSessionRuntimeUsable(distro: string): Promise<void>;
+    /**
+     * 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.
+     */
+    disposeSessionRuntimes(): Promise<void>;
     /**
      * 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
@@ -597,6 +669,8 @@ export interface WslFileSystemConfig {
     diffBasisMaxBytes?: number;
     /** Whether mutations are fenced by the policy. */
     sandbox: boolean;
+    /** Whether confined mutations run in the session runtime (ADR 0001). */
+    sessionSandbox: boolean;
     /** Whether confined profiles mask `/mnt`. */
     maskWindowsDrive: boolean;
     /** Whether paths leaving the distro are refused. */
@@ -633,6 +707,17 @@ export declare class WslFileSystem extends LocalFileSystem {
          * operations are unconfined.
          */
         sandbox: z<boolean, boolean, "defined">;
+        /**
+         * 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, boolean, "defined">;
         /**
          * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
          * Windows drive from confined commands — same meaning and same honest
@@ -694,6 +779,17 @@ export declare class WslFileSystem extends LocalFileSystem {
          * operations are unconfined.
          */
         sandbox: z<boolean, boolean, "defined">;
+        /**
+         * 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, boolean, "defined">;
         /**
          * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
          * Windows drive from confined commands — same meaning and same honest
@@ -747,6 +843,14 @@ export declare class WslFileSystem extends LocalFileSystem {
     sandbox: InstanceType<typeof WslSandbox>;
     /** The resident agent serving publication (see `publicationAgent`). */
     agentInstance: WslAgent | undefined;
+    /** The session-runtime registry; tests substitute it. */
+    sessionRuntimes: SessionRuntimes;
+    /** The runtimes this provider holds, by registry key. */
+    sessionRuntimeEntries: Map<string, SessionRuntimeEntry>;
+    /** The preflight's host runner; tests substitute it. */
+    sessionScopeProbe: (argv: string[]) => Promise<string>;
+    /** The last preflight verdict; only a success is cached. */
+    sessionRuntimePreflight: "unknown" | "ready";
     /**
      * @param ctx - the composition context.
      * @param config - the validated plugin config.
@@ -776,6 +880,36 @@ export declare class WslFileSystem extends LocalFileSystem {
      * @returns the substrate.
      */
     agentSubstrate(): Promise<AgentSubstrate>;
+    /**
+     * 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: {
+        mode: string;
+        workspaceRoot: string;
+    }, distro: string): SessionRuntimeEntry | undefined;
+    /**
+     * 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.
+     */
+    ensureSessionRuntimeUsable(distro: string): Promise<void>;
+    /**
+     * 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.
+     */
+    disposeSessionRuntimes(): Promise<void>;
     /**
      * The agent a MUTATION runs on under this resolved policy — stage-two
      * routing. A confined policy addresses the confined resident whose bwrap

package/lib/index.js

@@ -55,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
@@ -82,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();
 }
@@ -213,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.
@@ -220,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
@@ -302,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
@@ -604,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
@@ -780,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
@@ -839,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
@@ -883,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
@@ -912,6 +1094,12 @@ export class WslFileSystem extends LocalFileSystem {
             // 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 });
     }
     /**