dsh-plugin-wsl-env 0.14.0 → 0.16.0

package/lib/agent.js

@@ -41,7 +41,7 @@
  */
 import { spawn } from "node:child_process";
 import { AgentUnavailableError, BASH_TIMEOUT_REASON, CwdError, SpawnError } from "./agent-errors.js";
-import { AGENT_NAME, MAX_FRAME_BYTES, PROTOCOL_VERSION, encodeExecFrame, encodeFsFrame, encodeKill, encodeSetEnv, parseAgentLine } from "./agent-protocol.js";
+import { AGENT_NAME, MAX_FRAME_BYTES, PROTOCOL_VERSION, encodeExecFrame, encodeFsFrame, encodeKill, parseAgentLine } from "./agent-protocol.js";
 /**
  * A zeroed per-kind metrics record.
  * @returns the record.
@@ -172,6 +172,7 @@ export class WslAgent {
         this.wslPath = config.wslPath ?? "wsl.exe";
         this.argvPrefix = config.argvPrefix ?? [];
         this.signalable = config.signalable ?? this.argvPrefix.length === 0;
+        this.serialRequests = config.serialRequests ?? true;
         this.idleMs = config.idleMs ?? 600000;
         this.expectedDigest = config.expectedDigest;
         this.frameCapBytes = config.frameCapBytes ?? MAX_FRAME_BYTES;
@@ -294,6 +295,8 @@ export class WslAgent {
         this.expectedDigest = entry.expectedDigest;
         if (entry.signalable !== undefined)
             this.signalable = entry.signalable;
+        if (entry.serialRequests !== undefined)
+            this.serialRequests = entry.serialRequests;
         if (entry.spawnTransport !== undefined)
             this.configuredSpawn = entry.spawnTransport;
     }
@@ -472,6 +475,7 @@ export class WslAgent {
                 this.clearPending(pending);
                 this.pending.delete(message.id);
                 this.rearmIdleTimer();
+                this.dispatchQueued();
                 // A cancelled request keeps its entry only until this answer arrives.
                 if (pending.settled)
                     break;
@@ -487,6 +491,7 @@ export class WslAgent {
                 this.clearPending(pending);
                 this.pending.delete(message.id);
                 this.rearmIdleTimer();
+                this.dispatchQueued();
                 if (pending.settled)
                     break;
                 pending.settled = true;
@@ -554,7 +559,14 @@ export class WslAgent {
                     this.clearPending(pending);
                     continue;
                 }
-                if (isReplayableFrame(pending.lines)) {
+                if (!pending.sent) {
+                    this.clearPending(pending);
+                    if (pending.settled)
+                        continue;
+                    pending.settled = true;
+                    pending.reject(new AgentUnavailableError(`agent exited before request ${pending.id} was sent; it never ran`));
+                }
+                else if (isReplayableFrame(pending.lines)) {
                     if (pending.watchdog) {
                         clearTimeout(pending.watchdog);
                         pending.watchdog = null;
@@ -572,12 +584,18 @@ export class WslAgent {
             this.start()
                 .then(() => {
                 for (const pending of relayable) {
+                    if (pending.settled || pending.signal?.aborted)
+                        continue;
                     const id = `r${this.nextRequestId++}`;
                     pending.id = id;
+                    pending.seq = Number(id.slice(1));
+                    pending.lines = relabelFrame(pending.lines, id);
+                    pending.sent = false;
+                    pending.started = false;
                     this.pending.set(id, pending);
                     // The rebuilt transport can itself be gone by now; a frame that
                     // cannot be written must fail its caller, not strand the entry.
-                    if (!this.writeLines(relabelFrame(pending.lines, id))) {
+                    if (!this.serialRequests && !this.sendPending(pending)) {
                         this.clearPending(pending);
                         this.pending.delete(id);
                         if (pending.settled)
@@ -586,6 +604,7 @@ export class WslAgent {
                         pending.reject(new AgentUnavailableError(`agent exited before request ${id} could be re-sent; its state is unknown`));
                     }
                 }
+                this.dispatchQueued();
             })
                 .catch((error) => {
                 for (const pending of relayable) {
@@ -645,6 +664,7 @@ export class WslAgent {
             signal: signal ?? null,
             onAbort: null,
             started: false,
+            sent: false,
             cancelled: false,
             settled: false,
             answered: false,
@@ -681,6 +701,14 @@ export class WslAgent {
             }
             pending.onAbort = () => {
                 pending.cancelled = true;
+                if (!pending.sent) {
+                    this.pending.delete(pending.id);
+                    this.clearPending(pending);
+                    pending.settled = true;
+                    pending.reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+                    this.rearmIdleTimer();
+                    return;
+                }
                 // The frame is the fallback for an agent that cannot be signalled (a
                 // confined resident, a build without the USR1 trap); the signal is what
                 // interrupts the command the agent is blocked on right now.
@@ -709,7 +737,10 @@ export class WslAgent {
         // dropping it used to strand the request: nothing would ever answer, the
         // watchdog (armed on an ACK that will not come) had no process to kill,
         // and with no timeout the caller waited forever.
-        if (!this.writeLines(lines)) {
+        if (this.serialRequests) {
+            this.dispatchQueued();
+        }
+        else if (!this.sendPending(pending)) {
             this.clearPending(pending);
             this.pending.delete(pending.id);
             this.noteRejected(kind);
@@ -718,6 +749,30 @@ export class WslAgent {
         }
         this.rearmIdleTimer();
     }
+    /** Send a tracked request, recording dispatch before synchronous responses. */
+    sendPending(pending) {
+        pending.sent = true;
+        return this.writeLines(pending.lines);
+    }
+    /** Dispatch the next shell request only after the preceding answer. */
+    dispatchQueued() {
+        if (!this.serialRequests || [...this.pending.values()].some((pending) => pending.sent))
+            return;
+        const pending = this.pending.values().next().value;
+        if (pending === undefined)
+            return;
+        if (this.sendPending(pending))
+            return;
+        this.clearPending(pending);
+        this.pending.delete(pending.id);
+        if (!pending.settled) {
+            pending.settled = true;
+            pending.measured = true;
+            this.noteRejected(pending.kind);
+            pending.reject(new AgentUnavailableError("the agent exited before the request could be sent; it never ran"));
+        }
+        this.dispatchQueued();
+    }
     /**
      * Run one command inside the distro through the agent.
      *
@@ -726,12 +781,19 @@ export class WslAgent {
      * @throws {AgentUnavailableError} when the agent is out for this process.
      */
     async exec({ cwd, argv, timeoutMs = 0, maxOutputBytes = 0, env, signal }) {
+        const assignments = Object.entries(env ?? {}).map(([key, value]) => {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || value.includes("\0")) {
+                throw new Error(`invalid environment variable: ${key}`);
+            }
+            return `${key}=${value}`;
+        });
+        if (assignments.length > 0 && argv.length === 0)
+            throw new Error("cannot execute an empty command");
         await this.start();
         const id = `r${this.nextRequestId++}`;
-        const lines = [
-            ...(env ? Object.entries(env).map(([key, value]) => encodeSetEnv(key, value)) : []),
-            ...encodeExecFrame({ id, cwd, argv, timeoutMs, maxOutputBytes }),
-        ];
+        const commandArgv = argv[0]?.includes("=") ? ["/bin/sh", "-c", "exec \"$@\"", "env", ...argv] : argv;
+        const requestArgv = assignments.length > 0 ? ["env", "--", ...assignments, ...commandArgv] : argv;
+        const lines = encodeExecFrame({ id, cwd, argv: requestArgv, timeoutMs, maxOutputBytes });
         return new Promise((resolve, reject) => {
             this.track({ id, kind: "exec", lines, resolve, reject, timeoutMs, signal });
         });
@@ -786,7 +848,7 @@ export class WslAgent {
      * @param signal - the signal to deliver (`SIGUSR1` is the cancel trap).
      */
     /**
-     * The cumulative request metrics: queue wait (sent -> ACK) and execution
+     * The cumulative request metrics: queue wait (submission -> ACK) and execution
      * time (ACK -> settle) per request kind, plus the peak in-flight count.
      *
      * @returns a snapshot the caller can keep.
@@ -1024,8 +1086,7 @@ const REPLAYABLE_FS_OPS = new Set(["stat", "lstat", "list", "realpath", "read"])
  * Whether a stored request frame's first execution provably had no side
  * effects, so the frame may ride the one permitted rebuild. An EXEC never
  * qualifies — a command's effects are unknowable after the agent died — and
- * neither does an FS `write`. (A SETENV prefix line never decides: the frame
- * header sits at `lines[0]` only for FS frames, which carry no SETENV.)
+ * neither does an FS `write`.
  *
  * @param lines - the stored frame.
  * @returns true when the frame may be replayed.
@@ -1039,8 +1100,7 @@ function isReplayableFrame(lines) {
 }
 /**
  * Rewrite the request id inside a stored frame so a resent request does not
- * collide with ids the new process has already seen. SETENV lines pass
- * through unchanged (they are id-less and idempotent).
+ * collide with ids the new process has already seen.
  *
  * @param lines - the stored frame.
  * @param newId - the new request id.

package/lib/fs-routing.d.ts

@@ -30,6 +30,7 @@
  *
  * @module dsh-plugin-wsl/fs-routing
  */
+import z from "@deepseek-ai/schemastery";
 import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
 import { WslFileSystem } from "./index.js";
 import type { Context } from "@deepseek-ai/cordis";
@@ -91,7 +92,7 @@ export declare function inputIsDistro(value: string | undefined): boolean;
  * mode the distro side reports through `sandboxMode`).
  */
 export declare class WslRoutingFileSystem extends LocalFileSystem {
-    static Config: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/dsh-fs-local").Config>;
+    static Config: z<RoutingConfig>;
     /**
      * The routed backend's constructor reads the deployment default mode from
      * `ctx.sandboxPolicy`, exactly as the shipped `fs-sandbox` row this class

package/lib/fs-routing.js

@@ -31,6 +31,7 @@
  * @module dsh-plugin-wsl/fs-routing
  */
 import { isWslUnc, uncToPosix } from "./paths.js";
+import z from "@deepseek-ai/schemastery";
 import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
 import { WslFileSystem } from "./index.js";
 /**
@@ -101,7 +102,18 @@ export function inputIsDistro(value) {
  * mode the distro side reports through `sandboxMode`).
  */
 export class WslRoutingFileSystem extends LocalFileSystem {
-    static Config = LocalFileSystem.Config;
+    static Config = z.intersect([
+        LocalFileSystem.Config,
+        z.object({
+            distro: z.string().default(""),
+            wslPath: z.string().default("wsl.exe"),
+            distroCwd: z.string().default(""),
+            sandbox: z.boolean().default(true),
+            maskWindowsDrive: z.boolean().default(false),
+            restrictToDistro: z.boolean().default(true),
+            watchMaxDepth: z.natural().default(0),
+        }),
+    ]);
     /**
      * The routed backend's constructor reads the deployment default mode from
      * `ctx.sandboxPolicy`, exactly as the shipped `fs-sandbox` row this class

package/lib/fs-substrate.d.ts

@@ -13,12 +13,9 @@
  *    create publishes with the distro-side no-replace link, a real atomic
  *    primitive that refuses to replace. An overwrite or edit carries the
  *    version it was based on INTO the write op, and the agent re-verifies it
- *    with a fresh stat one syscall before the rename: a concurrent writer
- *    (an editor save, `git stash`, another session) wins, and the stale
- *    write refuses with `FS_STALE_VERSION` instead of clobbering. That
- *    narrows the share backend's check-then-write window from a host round
- *    trip to kernel-adjacent — the honest wording; "closed" was true only
- *    for the create case.
+ *    with a fresh stat before the rename: an earlier conflicting write is
+ *    refused with `FS_STALE_VERSION`. A writer between that stat and the
+ *    rename can still be overwritten; only guarded create is atomic.
  * 2. A symlink needs no retry machinery: every identity is resolved where the
  *    symlinks live.
  *
@@ -59,6 +56,7 @@ export declare class AgentSubstrate {
     agentFor: ((policy: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined) => Promise<WslAgent>) | undefined;
     /** The distro-side filesystem face. */
     fs: DistroFs;
@@ -83,6 +81,7 @@ export declare class AgentSubstrate {
         agentFor?: (policy: {
             mode: string;
             workspaceRoot: string;
+            sessionId?: string;
         } | undefined) => Promise<WslAgent>;
     });
     /**
@@ -95,6 +94,7 @@ export declare class AgentSubstrate {
     mutationAgent(policy: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined): Promise<WslAgent>;
     /**
      * Run `op` with exclusive access to `targetKey` (FIFO per key).
@@ -204,7 +204,7 @@ export declare class AgentSubstrate {
      * guard, best-effort diff basis, atomic publication, outcome shape. The
      * guard is FORWARDED — a guarded create publishes with the distro-side
      * no-replace link (atomic), and a `replaceIfVersion` write carries its
-     * version into the op, where the agent re-verifies it one syscall before
+     * version into the op, where the agent re-verifies it before
      * the rename and refuses with `FS_STALE_VERSION` on a mismatch.
      *
      * @param target - the resolved target.
@@ -220,6 +220,7 @@ export declare class AgentSubstrate {
     } | undefined, signal?: AbortSignal, policy?: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined): Promise<{
         operation: string;
         version: string;
@@ -230,8 +231,8 @@ export declare class AgentSubstrate {
      * Edit a text file with the host backend's orchestration: probe, version
      * guard, LF-normalized read, literal replacement, line-ending restore,
      * atomic publication, outcome shape. The version the edit was based on
-     * rides the write op and is re-verified distro-side one syscall before the
-     * rename, so a concurrent writer wins instead of being clobbered.
+     * rides the write op and is re-verified distro-side before the
+     * rename, narrowing but not eliminating the concurrent-write race.
      *
      * @param target - the resolved target.
      * @param edit - the literal request.
@@ -249,6 +250,7 @@ export declare class AgentSubstrate {
     } | undefined, signal?: AbortSignal, policy?: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined): Promise<{
         version: string;
         before: string;

package/lib/fs-substrate.js

@@ -13,12 +13,9 @@
  *    create publishes with the distro-side no-replace link, a real atomic
  *    primitive that refuses to replace. An overwrite or edit carries the
  *    version it was based on INTO the write op, and the agent re-verifies it
- *    with a fresh stat one syscall before the rename: a concurrent writer
- *    (an editor save, `git stash`, another session) wins, and the stale
- *    write refuses with `FS_STALE_VERSION` instead of clobbering. That
- *    narrows the share backend's check-then-write window from a host round
- *    trip to kernel-adjacent — the honest wording; "closed" was true only
- *    for the create case.
+ *    with a fresh stat before the rename: an earlier conflicting write is
+ *    refused with `FS_STALE_VERSION`. A writer between that stat and the
+ *    rename can still be overwritten; only guarded create is atomic.
  * 2. A symlink needs no retry machinery: every identity is resolved where the
  *    symlinks live.
  *
@@ -196,7 +193,7 @@ export class AgentSubstrate {
      * guard, best-effort diff basis, atomic publication, outcome shape. The
      * guard is FORWARDED — a guarded create publishes with the distro-side
      * no-replace link (atomic), and a `replaceIfVersion` write carries its
-     * version into the op, where the agent re-verifies it one syscall before
+     * version into the op, where the agent re-verifies it before
      * the rename and refuses with `FS_STALE_VERSION` on a mismatch.
      *
      * @param target - the resolved target.
@@ -247,8 +244,8 @@ export class AgentSubstrate {
      * Edit a text file with the host backend's orchestration: probe, version
      * guard, LF-normalized read, literal replacement, line-ending restore,
      * atomic publication, outcome shape. The version the edit was based on
-     * rides the write op and is re-verified distro-side one syscall before the
-     * rename, so a concurrent writer wins instead of being clobbered.
+     * rides the write op and is re-verified distro-side before the
+     * rename, narrowing but not eliminating the concurrent-write race.
      *
      * @param target - the resolved target.
      * @param edit - the literal request.

package/lib/fsio-agent.d.ts

@@ -244,9 +244,8 @@ export declare class DistroFs {
      * Publish `content` over `linuxPath` the POSIX way: the agent stages into a
      * private 0700 sibling, fsyncs, chmods, and renames — or hard links for a
      * guarded create. A `replace` publish carrying `expectedVersion` is
-     * re-verified by the agent against a fresh stat one syscall before the
-     * rename: a concurrent writer (an editor save, a `git stash`) wins, and the
-     * stale write refuses with `FS_STALE_VERSION` instead of landing.
+     * re-verified by the agent against a fresh stat before the rename. A change
+     * after that check can still be overwritten by the rename.
      *
      * @param linuxPath - the target path inside the distro.
      * @param content - the full new content.

package/lib/fsio-agent.js

@@ -407,9 +407,8 @@ export class DistroFs {
      * Publish `content` over `linuxPath` the POSIX way: the agent stages into a
      * private 0700 sibling, fsyncs, chmods, and renames — or hard links for a
      * guarded create. A `replace` publish carrying `expectedVersion` is
-     * re-verified by the agent against a fresh stat one syscall before the
-     * rename: a concurrent writer (an editor save, a `git stash`) wins, and the
-     * stale write refuses with `FS_STALE_VERSION` instead of landing.
+     * re-verified by the agent against a fresh stat before the rename. A change
+     * after that check can still be overwritten by the rename.
      *
      * @param linuxPath - the target path inside the distro.
      * @param content - the full new content.

package/lib/index.d.ts

@@ -83,6 +83,21 @@ export type WslExecSpec = ShellExecSpec & {
  * wrappers, so they are spelled as their `.get()` shape (the reading
  * {@link configuredCwd} and `hostCwd` perform).
  */
+/**
+ * The effective `/mnt` mask for a config: `interopVisibility` is the stance
+ * key (WSL-314) and takes precedence whenever it names a stance; the legacy
+ * `maskWindowsDrive` boolean answers only when the stance key is left at its
+ * `visible` default. `disabled` masks in-session — the belt — while the
+ * distro-level closure (`[interop] enabled=false` + `wsl --shutdown`)
+ * remains a documented, user-applied step a config key must not perform.
+ *
+ * @param config - anything carrying the two keys.
+ * @returns whether confined profiles shadow `/mnt`.
+ */
+export declare function effectiveMaskWindowsDrive(config: {
+    interopVisibility?: "visible" | "masked" | "disabled";
+    maskWindowsDrive?: boolean;
+}): boolean;
 export interface WslShellExecutorConfig {
     /** The pinned distro; empty means WSL's default. */
     distro: string;
@@ -96,6 +111,8 @@ export interface WslShellExecutorConfig {
     sandbox: boolean;
     /** Whether confined profiles mask `/mnt`. */
     maskWindowsDrive: boolean;
+    /** The interop stance; set at all, it takes precedence over `maskWindowsDrive`. */
+    interopVisibility?: "visible" | "masked" | "disabled";
     /** The volatile default workdir. */
     cwd: {
         get(): string | undefined;
@@ -218,6 +235,26 @@ export declare class WslShellExecutor extends LocalBashExecutor {
          * complete closure is distro-level: `[interop] enabled=false` in
          * `wsl.conf`.
          */
+        /**
+         * The interop stance in one key (WSL-314), expanding to the per-key
+         * values the measured matrix documents:
+         *
+         * - `visible` (default) — nothing masked; a confined command can read
+         *   `/mnt` and launch Windows executables through interop, which escapes
+         *   the Linux sandbox entirely.
+         * - `masked` — `maskWindowsDrive: true`: `/mnt` is shadowed with an empty
+         *   tmpfs; the drive's files and executables are unreachable (binfmt can
+         *   still run a workspace-written .exe, so enforcement stays `partial`).
+         * - `disabled` — `masked`, plus the distro-level closure: `[interop]
+         *   enabled=false` in `/etc/wsl.conf` + `wsl --shutdown`, which the
+         *   doctor's remedy prints as copy-paste (a config key does not write
+         *   distro config; enforcement is the kernel's, not the schema's).
+         *
+         * When set at all it takes precedence over the legacy
+         * `maskWindowsDrive` boolean below (unset — the default — lets that
+         * boolean answer); the boolean remains for existing profiles.
+         */
+        interopVisibility: z<"masked" | "visible" | "disabled", "masked" | "visible" | "disabled", "plain">;
         maskWindowsDrive: z<boolean, boolean, "defined">;
         /**
          * Default workdir for a request that names none; accepts `/home/andy/proj`,
@@ -296,6 +333,26 @@ export declare class WslShellExecutor extends LocalBashExecutor {
          * complete closure is distro-level: `[interop] enabled=false` in
          * `wsl.conf`.
          */
+        /**
+         * The interop stance in one key (WSL-314), expanding to the per-key
+         * values the measured matrix documents:
+         *
+         * - `visible` (default) — nothing masked; a confined command can read
+         *   `/mnt` and launch Windows executables through interop, which escapes
+         *   the Linux sandbox entirely.
+         * - `masked` — `maskWindowsDrive: true`: `/mnt` is shadowed with an empty
+         *   tmpfs; the drive's files and executables are unreachable (binfmt can
+         *   still run a workspace-written .exe, so enforcement stays `partial`).
+         * - `disabled` — `masked`, plus the distro-level closure: `[interop]
+         *   enabled=false` in `/etc/wsl.conf` + `wsl --shutdown`, which the
+         *   doctor's remedy prints as copy-paste (a config key does not write
+         *   distro config; enforcement is the kernel's, not the schema's).
+         *
+         * When set at all it takes precedence over the legacy
+         * `maskWindowsDrive` boolean below (unset — the default — lets that
+         * boolean answer); the boolean remains for existing profiles.
+         */
+        interopVisibility: z<"masked" | "visible" | "disabled", "masked" | "visible" | "disabled", "plain">;
         maskWindowsDrive: z<boolean, boolean, "defined">;
         /**
          * Default workdir for a request that names none; accepts `/home/andy/proj`,
@@ -350,6 +407,8 @@ export declare class WslShellExecutor extends LocalBashExecutor {
     sessionRuntimes: SessionRuntimes;
     /** The runtimes this executor holds, by registry key. */
     sessionRuntimeEntries: Map<string, SessionRuntimeEntry>;
+    /** Isolates calls that have no session identity. */
+    sessionRuntimeOwner: string;
     /** The preflight's host runner; tests substitute it. */
     sessionScopeProbe: (argv: string[]) => Promise<string>;
     /** Distros whose session-runtime preflight has succeeded. */
@@ -434,7 +493,7 @@ export declare class WslShellExecutor extends LocalBashExecutor {
     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
+     * on. The executor holds one reference per `(session, distro, workspace, policy)` and
      * releases them when the session's scope disposes.
      *
      * @param policy - the resolved file-effect policy, when the executor has one.
@@ -445,6 +504,7 @@ export declare class WslShellExecutor extends LocalBashExecutor {
     sessionRuntimeFor(policy: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined, resolved: WslExecSpec, distro: string): SessionRuntimeEntry | undefined;
     /**
      * Run the session runtime's preflight once per executor. A failure is a
@@ -758,11 +818,11 @@ export declare class WslFileSystem extends LocalFileSystem {
         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
+         * runtime the shell executor acquires for the same session, distro,
+         * workspace and policy — instead of a per-policy confined resident. A
+         * missing session ID keeps the providers separate. The kernel enforcement
+         * is the runtime's mount profile; the scope stops when its 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.
          */
@@ -833,11 +893,11 @@ export declare class WslFileSystem extends LocalFileSystem {
         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
+         * runtime the shell executor acquires for the same session, distro,
+         * workspace and policy — instead of a per-policy confined resident. A
+         * missing session ID keeps the providers separate. The kernel enforcement
+         * is the runtime's mount profile; the scope stops when its 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.
          */
@@ -905,6 +965,8 @@ export declare class WslFileSystem extends LocalFileSystem {
     sessionRuntimes: SessionRuntimes;
     /** The runtimes this provider holds, by registry key. */
     sessionRuntimeEntries: Map<string, SessionRuntimeEntry>;
+    /** Isolates calls that have no session identity. */
+    sessionRuntimeOwner: string;
     /** The preflight's host runner; tests substitute it. */
     sessionScopeProbe: (argv: string[]) => Promise<string>;
     /** Distros whose session-runtime preflight has succeeded. */
@@ -981,6 +1043,7 @@ export declare class WslFileSystem extends LocalFileSystem {
     sessionRuntimeFor(policy: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     }, distro: string): SessionRuntimeEntry | undefined;
     /**
      * Run the session runtime's preflight once per provider. Only success is
@@ -1025,6 +1088,7 @@ export declare class WslFileSystem extends LocalFileSystem {
     mutationAgent(policy: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined, forDistro?: string): Promise<WslAgent>;
     /**
      * Map a substrate error onto the peer's `FsError`, so the tool layer reads
@@ -1235,8 +1299,8 @@ export declare class WslFileSystem extends LocalFileSystem {
      * Fence the write by the per-call policy, then publish through the
      * substrate. The fence's fresh target is the one checked and written, so a
      * refusal costs no I/O and cannot be raced by a swapped symlink; the guard
-     * rides the write op, where the agent re-verifies it one syscall before the
-     * rename and the confined resident enforces it in the kernel.
+     * rides the write op, where the agent re-verifies it before the rename;
+     * the confined resident enforces the mount boundary in the kernel.
      *
      * @param target - the resolved target.
      * @param content - the full new file content.