dsh-plugin-wsl-env 0.12.0 → 0.13.0

package/lib/index.js

@@ -46,10 +46,11 @@ import { FsError } from "@deepseek-ai/dsh-fs";
 import { canonicalPath, classifyRunnerFailure, isRunnerSpawnFailure, matchesSignature, SandboxUnavailableError, writableRoots } from "@deepseek-ai/dsh-sandbox";
 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 { distroOfUnc, isDefaultDistro, pinnedDistro, selectDistro } from "./distro-route.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 { AgentUnavailableError, SpawnError } from "./agent-errors.js";
 import { agentExecutionHandle } from "./agent-exec.js";
 import { sharedAgent } from "./agent-shared.js";
 import { AgentSubstrate } from "./fs-substrate.js";
@@ -102,20 +103,32 @@ function configuredCwd(config) {
  * An empty `cwd` cannot mean the shipped default (`process.cwd()`, a Windows
  * directory no `wsl.exe --cd` accepts) and it must not mean a hardcoded author
  * path either, so both providers agree on this instead: the distro's own home,
- * asked of the distro once per instance.
+ * asked of the distro once per (provider, distro) pair.
  *
  * @param owner - a WslShellExecutor or WslFileSystem.
+ * @param distro - the distro whose home is wanted.
  * @returns an absolute Linux path.
  */
-async function distroHome(owner) {
-    if (owner.resolvedHome === undefined) {
-        // Both providers carry `wslPath` in their own config; the base classes'
-        // `config` types do not know the key, so the shape is asserted here.
-        const config = owner.config;
-        const distro = await owner.distro();
-        owner.resolvedHome = await linuxHomePath(distro, { wslPath: config.wslPath });
-    }
-    return owner.resolvedHome;
+async function distroHome(owner, distro) {
+    const cached = owner.resolvedHomes.get(distro);
+    if (cached !== undefined)
+        return cached;
+    // The single-home field predates the per-distro map and is still the test
+    // substitute for "a home is already known"; honour it before spawning.
+    if (owner.resolvedHome !== undefined && owner.resolvedDistro.length > 0 && distro === owner.resolvedDistro) {
+        owner.resolvedHomes.set(distro, owner.resolvedHome);
+        return owner.resolvedHome;
+    }
+    // Both providers carry `wslPath` in their own config; the base classes'
+    // `config` types do not know the key, so the shape is asserted here.
+    const config = owner.config;
+    const home = await linuxHomePath(distro, { wslPath: config.wslPath });
+    owner.resolvedHomes.set(distro, home);
+    // The legacy single-home cache is still what `processPathFromHostPath` and
+    // the existing tests read; keep it warm for the resolved default/pin.
+    if (owner.resolvedDistro.length > 0 && distro === owner.resolvedDistro)
+        owner.resolvedHome = home;
+    return home;
 }
 /**
  * The roots a `workspace-write` policy may write under, in the vocabulary this
@@ -147,6 +160,48 @@ function wslWritableRoots(policy, distro) {
     return [...roots];
 }
 const inheritedSpawnSpec = LocalBashExecutor.prototype.spawnSpec;
+/**
+ * How long an `auto` distro that could not host a session runtime stays
+ * downgraded before the probe is retried.
+ */
+const AUTO_SCOPE_RECHECK_MS = 60_000;
+/**
+ * Whether a provider should use the session runtime for one distro.
+ *
+ * - `false` is off;
+ * - `true` refuses with the preflight remedy when the platform cannot host it;
+ * - `"auto"` downgrades to the per-command sandbox and reports that narrower
+ *   scope in the result, re-probing a failed verdict at most once a minute so
+ *   following the remedy (systemd, Linger) upgrades without an app restart.
+ *
+ * @param value - the configured `sessionSandbox` value.
+ * @param distro - the resolved distro.
+ * @param ensure - the provider's preflight, which throws the remedy on failure.
+ * @param cache - the provider's per-distro `auto` verdicts.
+ * @returns whether the session runtime should be used.
+ */
+async function sessionRuntimeWanted(value, distro, ensure, cache) {
+    if (value === false)
+        return false;
+    if (value === true) {
+        await ensure();
+        return true;
+    }
+    const cached = cache.get(distro);
+    if (cached?.usable === true)
+        return true;
+    if (cached !== undefined && Date.now() - cached.checkedAt < AUTO_SCOPE_RECHECK_MS)
+        return false;
+    try {
+        await ensure();
+        cache.set(distro, { usable: true, checkedAt: Date.now() });
+        return true;
+    }
+    catch {
+        cache.set(distro, { usable: false, checkedAt: Date.now() });
+        return false;
+    }
+}
 /**
  * Bash executor that runs every command inside a WSL distro.
  *
@@ -160,7 +215,10 @@ const inheritedSpawnSpec = LocalBashExecutor.prototype.spawnSpec;
 export class WslShellExecutor extends LocalBashExecutor {
     static inject = ["subprocess", "sandboxPolicy"];
     static Config = z.object({
-        /** Distro name; empty means WSL's own default distro. */
+        /**
+         * Distro mode: empty/`"auto"` follows the request workdir, `"default"`
+         * forces WSL's default, and an explicit name pins every command.
+         */
         distro: z.string().default(""),
         /** Path to `wsl.exe`; overridable for a non-standard install. */
         wslPath: z.string().default("wsl.exe"),
@@ -233,7 +291,7 @@ export class WslShellExecutor extends LocalBashExecutor {
          * `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),
+        sessionSandbox: z.union([z.boolean(), z.const("auto")]).default(false),
     });
     /**
      * @param ctx - the composition context.
@@ -242,9 +300,11 @@ export class WslShellExecutor extends LocalBashExecutor {
     constructor(ctx, config) {
         super(ctx, config);
         configureAgentBackend(config.agentBackend ?? "auto");
-        this.resolvedDistro = config.distro;
+        this.resolvedDistro = pinnedDistro(config.distro) ?? "";
         this.resolvedShell = config.shell;
+        this.resolvedShells = new Map();
         this.resolvedHome = undefined;
+        this.resolvedHomes = new Map();
         this.mode = config.sandbox ? ctx.sandboxPolicy.defaultMode : undefined;
         this.sandbox = config.sandbox
             ? new WslSandbox({ wslPath: config.wslPath, maskWindowsDrive: config.maskWindowsDrive })
@@ -253,7 +313,8 @@ export class WslShellExecutor extends LocalBashExecutor {
         this.sessionRuntimes = sessionRuntimes;
         this.sessionRuntimeEntries = new Map();
         this.sessionScopeProbe = (argv) => runCapture(argv);
-        this.sessionRuntimePreflight = "unknown";
+        this.sessionRuntimePreflight = new Set();
+        this.autoSessionScope = new Map();
         // 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");
@@ -270,7 +331,8 @@ export class WslShellExecutor extends LocalBashExecutor {
         return this.mode;
     }
     /**
-     * The distro every command runs in, resolving WSL's default on first use.
+     * The distro used when no path supplies evidence: the pinned name, WSL's
+     * default, or the default for the automatic modes.
      *
      * @returns the distro name.
      */
@@ -281,10 +343,33 @@ export class WslShellExecutor extends LocalBashExecutor {
         return this.resolvedDistro;
     }
     /**
-     * The shell every command runs in: the configured one, else the login shell of
-     * the distro user, resolved once and cached.
+     * The distro one command belongs to: an explicit pin wins; otherwise the
+     * request workdir, then the configured `cwd`, may name a distro; both
+     * absent falls back to WSL's default.
      *
-     * @returns an absolute path to the shell inside the distro.
+     * @param workdir - the request's workdir, in any coordinate system.
+     * @param cwd - the configured default workdir, when the caller has it.
+     * @returns the distro name.
+     */
+    async distroFor(workdir, cwd) {
+        const config = this.config;
+        const pinned = pinnedDistro(config.distro);
+        if (pinned !== undefined)
+            return pinned;
+        if (!isDefaultDistro(config.distro)) {
+            for (const candidate of [workdir, cwd ?? configuredCwd(this.config)]) {
+                const named = distroOfUnc(candidate);
+                if (named !== undefined)
+                    return named;
+            }
+        }
+        return this.distro();
+    }
+    /**
+     * The shell name for the default/pinned distro, as the shell tool presents
+     * it.
+     *
+     * @returns the basename of the shell, or `bash` when it cannot be named.
      */
     async shellName() {
         // Consumed by the shell tool after upstream change A: it names and describes
@@ -295,8 +380,30 @@ export class WslShellExecutor extends LocalBashExecutor {
         return /^[a-z0-9_+-]+$/i.test(name) ? name : "bash";
     }
     /**
-     * The shell every command runs in, resolving the distro login shell on
-     * first use.
+     * The shell for one distro: the configured shell, else that distro's login
+     * shell. The default/pinned distro keeps the legacy {@link resolvedShell}
+     * cache; every other distro gets an entry in {@link resolvedShells}.
+     *
+     * @param distro - the distro name.
+     * @returns an absolute path to the shell inside the distro.
+     */
+    async shellFor(distro) {
+        const config = this.config;
+        if (config.shell.length > 0)
+            return config.shell;
+        if (this.resolvedDistro.length > 0 && distro === this.resolvedDistro)
+            return this.shell();
+        const cached = this.resolvedShells.get(distro);
+        if (cached !== undefined)
+            return cached;
+        const resolved = await defaultShell(distro, { wslPath: config.wslPath });
+        if (resolved !== undefined)
+            this.resolvedShells.set(distro, resolved);
+        return resolved ?? "bash";
+    }
+    /**
+     * The shell for the default/pinned distro: the configured one, else the
+     * login shell, resolved once and cached.
      *
      * @returns an absolute path to the shell inside the distro.
      */
@@ -376,14 +483,26 @@ export class WslShellExecutor extends LocalBashExecutor {
      * @throws {Error} with the remedy when it cannot.
      */
     async ensureSessionRuntimeUsable(distro) {
-        if (this.sessionRuntimePreflight === "ready")
+        if (this.sessionRuntimePreflight.has(distro))
             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";
+        this.sessionRuntimePreflight.add(distro);
+    }
+    /**
+     * Whether this executor should use the session runtime for one distro, with
+     * the `auto` downgrade and its bounded re-probe. `true` keeps the refusing
+     * behavior; `false` stays off.
+     *
+     * @param distro - the resolved distro.
+     * @returns whether to acquire the per-session scope.
+     */
+    async wantsSessionRuntime(distro) {
+        const config = this.config;
+        return sessionRuntimeWanted(config.sessionSandbox, distro, () => this.ensureSessionRuntimeUsable(distro), this.autoSessionScope);
     }
     /**
      * Release every runtime this executor holds, stopping each scope. Called
@@ -532,10 +651,11 @@ export class WslShellExecutor extends LocalBashExecutor {
         const tail = typeof spec?.relativeWorkdir === "string" ? spec.relativeWorkdir : undefined;
         if (String(spec?.workdir ?? "").trim().length > 0 && tail === undefined)
             return spec;
-        const home = await distroHome(this);
+        const distro = await this.distroFor(spec.workdir, configuredCwd(this.config));
+        const home = await distroHome(this, distro);
         if (tail === undefined || tail.length === 0)
             return { ...spec, workdir: home };
-        return { ...spec, workdir: toLinuxPath(tail, { distro: await this.distro(), cwd: home }) };
+        return { ...spec, workdir: toLinuxPath(tail, { distro, cwd: home }) };
     }
     /**
      * Decorate a handle's foreground projection in place, memoized once. The
@@ -584,6 +704,7 @@ export class WslShellExecutor extends LocalBashExecutor {
                 denied: !runnerFailed && matchesSignature(proc.exitCode, stderr, facts.denialSignatures),
                 enforcement: facts.enforcement,
                 ...(facts.windowsDrive ? { windowsDrive: facts.windowsDrive } : {}),
+                sessionScope: facts.sessionScope,
                 ...(runnerFailed ? { runnerFailed } : {}),
             };
         }
@@ -647,9 +768,9 @@ export class WslShellExecutor extends LocalBashExecutor {
      */
     async execute(spec) {
         const config = this.config;
-        const distro = await this.distro();
-        const shell = await this.shell();
         const resolved = await this.withDefaultWorkdir(spec);
+        const distro = await this.distroFor(resolved.workdir, configuredCwd(config));
+        const shell = await this.shellFor(distro);
         this.throwIfWorkdirInAnotherDistro(resolved.workdir, distro);
         if (config.agent) {
             try {
@@ -700,9 +821,8 @@ 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 useScope = await this.wantsSessionRuntime(distro);
+        const runtime = useScope ? this.sessionRuntimeFor(policy, resolved, distro) : undefined;
         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
@@ -742,6 +862,7 @@ export class WslShellExecutor extends LocalBashExecutor {
                         runnerProgram: profile.argv[0] ?? "",
                         workdir: resolved.workdir,
                         windowsDrive: profile.windowsDrive,
+                        sessionScope: useScope ? "session" : "per-command",
                     });
                 }
                 : undefined,
@@ -752,7 +873,7 @@ export class WslShellExecutor extends LocalBashExecutor {
             if (this.sandbox === undefined)
                 return result;
             if (confined === undefined) {
-                return ({ ...result, sandbox: { mode, denied: false } });
+                return ({ ...result, sandbox: { mode, denied: false, sessionScope: useScope ? "session" : "per-command" } });
             }
             const { enforcement, denialSignatures, runnerFailureRules, windowsDrive } = confined;
             const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, runnerFailureRules);
@@ -769,11 +890,19 @@ export class WslShellExecutor extends LocalBashExecutor {
                     denied: matchesSignature(result.exitCode, result.stderr.text, denialSignatures),
                     enforcement,
                     windowsDrive,
+                    sessionScope: useScope ? "session" : "per-command",
                 },
             });
         }, (error) => {
             if (resolved.signal?.aborted === true)
                 resolved.signal.throwIfAborted();
+            // The native agent reports a missing workdir as a spawn failure without
+            // naming it. Retry that command on the one-shot path, whose `--cd`
+            // warning names the directory — the failure path pays the extra spawn,
+            // the hot path does not.
+            if (error instanceof SpawnError) {
+                return this.executeOneShot(resolved, distro, shell).then((fallback) => fallback.result());
+            }
             throw error;
         });
         // The agent handle IS the upstream execution shape at runtime; its typedef
@@ -831,13 +960,14 @@ export class WslShellExecutor extends LocalBashExecutor {
                 runnerProgram: profile.argv[0] ?? "",
                 workdir: resolved.workdir,
                 windowsDrive: profile.windowsDrive,
+                sessionScope: "per-command",
             });
         });
         return WslShellExecutor.decorateResult(execution, (result) => {
             this.throwIfDistroUnavailable(result, distro);
             this.throwIfWorkdirMissing(result, resolved.workdir);
             if (confined === undefined) {
-                return ({ ...result, sandbox: { mode, denied: false } });
+                return ({ ...result, sandbox: { mode, denied: false, sessionScope: "per-command" } });
             }
             const { enforcement, denialSignatures, runnerFailureRules, windowsDrive } = confined;
             // Runner failure outranks denial because the command did not run at all.
@@ -851,6 +981,7 @@ export class WslShellExecutor extends LocalBashExecutor {
                     denied: matchesSignature(result.exitCode, result.stderr.text, denialSignatures),
                     enforcement,
                     windowsDrive,
+                    sessionScope: "per-command",
                 },
             });
         }, (error) => {
@@ -867,7 +998,10 @@ export class WslShellExecutor extends LocalBashExecutor {
 export class WslFileSystem extends LocalFileSystem {
     static inject = ["sandboxPolicy"];
     static Config = z.object({
-        /** Distro name; empty resolves WSL's default on first use. */
+        /**
+         * Distro mode: empty/`"auto"` follows the target path, `"default"` forces
+         * WSL's default, and an explicit name pins the filesystem.
+         */
         distro: z.string().default(""),
         /**
          * Default workdir for relative input; accepts a Linux path, a UNC path, or
@@ -897,7 +1031,7 @@ export class WslFileSystem extends LocalFileSystem {
          * `sessionSandbox`; the preflight refuses with the remedy. Off for direct
          * constructions; on in the shipped preset.
          */
-        sessionSandbox: z.boolean().default(false),
+        sessionSandbox: z.union([z.boolean(), z.const("auto")]).default(false),
         /**
          * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
          * Windows drive from confined commands — same meaning and same honest
@@ -951,16 +1085,20 @@ export class WslFileSystem extends LocalFileSystem {
         if (refusal !== null)
             throw new Error(refusal.message);
         super(ctx, config);
-        this.resolvedDistro = config.distro;
+        this.resolvedDistro = pinnedDistro(config.distro) ?? "";
         this.resolvedHome = undefined;
+        this.resolvedHomes = new Map();
         this.defaultMode = ctx.sandboxPolicy.defaultMode;
         this.agentSubstrateInstance = undefined;
+        this.agentSubstrates = new Map();
         this.sandbox = new WslSandbox({ wslPath: config.wslPath, maskWindowsDrive: config.maskWindowsDrive });
         this.agentInstance = undefined;
+        this.agentInstances = new Map();
         this.sessionRuntimes = sessionRuntimes;
         this.sessionRuntimeEntries = new Map();
         this.sessionScopeProbe = (argv) => runCapture(argv);
-        this.sessionRuntimePreflight = "unknown";
+        this.sessionRuntimePreflight = new Set();
+        this.autoSessionScope = new Map();
         // 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");
@@ -978,11 +1116,10 @@ export class WslFileSystem extends LocalFileSystem {
         return config.sandbox ? this.defaultMode : undefined;
     }
     /**
-     * The resident agent serving this filesystem's in-distro side work, created
-     * on first use and kept for the provider's lifetime (its own idle timer
-     * retires the process; a later call starts a fresh one).
+     * The resident agent serving the default/pinned distro's in-distro side
+     * work, created on first use and kept for the provider's lifetime.
      *
-     * @returns the agent for the pinned distro.
+     * @returns the agent for the default/pinned distro.
      */
     async publicationAgent() {
         if (this.agentInstance === undefined) {
@@ -991,8 +1128,26 @@ export class WslFileSystem extends LocalFileSystem {
         return this.agentInstance;
     }
     /**
-     * The agent-backed substrate, built on first use over the same resident
-     * agent every other distro side work shares.
+     * The resident agent for one distro. The default/pinned distro keeps the
+     * legacy {@link publicationAgent} cache; every other distro gets its own
+     * entry, because the shared agent is a per-distro process singleton.
+     *
+     * @param distro - the distro name.
+     * @returns the agent for that distro.
+     */
+    async publicationAgentFor(distro) {
+        if (this.resolvedDistro.length > 0 && distro === this.resolvedDistro)
+            return this.publicationAgent();
+        const cached = this.agentInstances.get(distro);
+        if (cached !== undefined)
+            return cached;
+        const agent = sharedAgent(distro);
+        this.agentInstances.set(distro, agent);
+        return agent;
+    }
+    /**
+     * The agent-backed substrate for the default/pinned distro, built on first
+     * use over the shared resident agent.
      *
      * @returns the substrate.
      */
@@ -1008,6 +1163,40 @@ export class WslFileSystem extends LocalFileSystem {
         }
         return this.agentSubstrateInstance;
     }
+    /**
+     * The agent-backed substrate for one distro. The default/pinned distro keeps
+     * the legacy {@link agentSubstrate} accessor (and its test override); every
+     * other distro gets a substrate that mints its own UNC identities and
+     * addresses its own resident.
+     *
+     * @param distro - the distro name.
+     * @returns the substrate for that distro.
+     */
+    async agentSubstrateFor(distro) {
+        if (this.resolvedDistro.length > 0 && distro === this.resolvedDistro)
+            return this.agentSubstrate();
+        const cached = this.agentSubstrates.get(distro);
+        if (cached !== undefined)
+            return cached;
+        const config = this.config;
+        const substrate = new AgentSubstrate({
+            agent: await this.publicationAgentFor(distro),
+            distro,
+            diffBasisMaxBytes: config.diffBasisMaxBytes,
+            agentFor: (policy) => this.mutationAgent(policy, distro),
+        });
+        this.agentSubstrates.set(distro, substrate);
+        return substrate;
+    }
+    /**
+     * The substrate for one resolved target, following the target's UNC identity.
+     *
+     * @param target - the resolved target.
+     * @returns the substrate for the target's distro.
+     */
+    async substrateForTarget(target) {
+        return this.agentSubstrateFor(await this.distroForTarget(target));
+    }
     /**
      * The persistent session runtime for one confined mutation, when
      * `sessionSandbox` is on. The key is the shell executor's key for the same
@@ -1046,14 +1235,26 @@ export class WslFileSystem extends LocalFileSystem {
      * @throws {Error} with the remedy when it cannot.
      */
     async ensureSessionRuntimeUsable(distro) {
-        if (this.sessionRuntimePreflight === "ready")
+        if (this.sessionRuntimePreflight.has(distro))
             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";
+        this.sessionRuntimePreflight.add(distro);
+    }
+    /**
+     * Whether this provider should use the session runtime for one distro, with
+     * the `auto` downgrade and its bounded re-probe. `true` keeps the refusing
+     * behavior; `false` stays off.
+     *
+     * @param distro - the resolved distro.
+     * @returns whether to acquire the per-session scope.
+     */
+    async wantsSessionRuntime(distro) {
+        const config = this.config;
+        return sessionRuntimeWanted(config.sessionSandbox, distro, () => this.ensureSessionRuntimeUsable(distro), this.autoSessionScope);
     }
     /**
      * Release every runtime this provider holds. Called from the preset's
@@ -1078,26 +1279,27 @@ export class WslFileSystem extends LocalFileSystem {
      *
      * @param policy - the resolved file-effect policy, or undefined when the
      *   caller pre-checked.
+     * @param forDistro - the distro the mutation belongs to; derived from the
+     *   policy when the caller does not know it.
      * @returns the agent to publish through.
      */
-    async mutationAgent(policy) {
+    async mutationAgent(policy, forDistro) {
         const config = this.config;
+        const distro = forDistro ?? await this.distroForPolicy(policy);
         if (!isConfinedMutation({ policy, sandboxEnabled: config.sandbox })) {
-            return this.publicationAgent();
+            return this.publicationAgentFor(distro);
         }
         // The untyped guard decided this is a confined policy but cannot narrow
         // the parameter, so the confined shape is asserted once here (type-level
         // only; `confinedPolicy` is the same value as `policy`).
         const confinedPolicy = policy;
-        const distro = await this.distro();
         if (!(await this.sandbox.usable(distro))) {
             // 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);
+        if (await this.wantsSessionRuntime(distro)) {
             const runtime = this.sessionRuntimeFor(confinedPolicy, distro);
             if (runtime !== undefined)
                 return runtime.agent;
@@ -1133,7 +1335,8 @@ export class WslFileSystem extends LocalFileSystem {
         return uncToPosix(target.targetKey)?.linuxPath ?? target.displayPath;
     }
     /**
-     * The pinned distro, resolving WSL's default on first use.
+     * The distro used when no path supplies evidence: the pinned name, WSL's
+     * default, or the default for the automatic modes.
      *
      * @returns the distro name.
      */
@@ -1143,6 +1346,60 @@ export class WslFileSystem extends LocalFileSystem {
             this.resolvedDistro = await defaultDistro({ wslPath: config.wslPath });
         return this.resolvedDistro;
     }
+    /**
+     * The distro one path belongs to: an explicit pin wins; otherwise the path
+     * itself, then the cwd or configured cwd, may name a distro; both absent
+     * falls back to WSL's default.
+     *
+     * @param path - the caller path, in any coordinate system.
+     * @param cwd - the caller's optional cwd override.
+     * @returns the distro name.
+     */
+    async distroForPath(path, cwd) {
+        const config = this.config;
+        const pinned = pinnedDistro(config.distro);
+        if (pinned !== undefined)
+            return pinned;
+        if (!isDefaultDistro(config.distro)) {
+            for (const candidate of [path, cwd ?? config.cwd]) {
+                const named = distroOfUnc(candidate);
+                if (named !== undefined)
+                    return named;
+            }
+        }
+        return this.distro();
+    }
+    /**
+     * The distro a resolved target belongs to. A UNC identity names it outright;
+     * a host-coordinate target falls back to the configured/default distro.
+     *
+     * @param target - the resolved target.
+     * @returns the distro name.
+     */
+    async distroForTarget(target) {
+        return uncToPosix(target.targetKey)?.distro ?? this.distroForPath(target.displayPath);
+    }
+    /**
+     * The distro a mutation's policy belongs to: the workspace root is the
+     * strongest evidence, then the configured cwd, then the default.
+     *
+     * @param policy - the resolved policy, when the caller has one.
+     * @returns the distro name.
+     */
+    async distroForPolicy(policy) {
+        const config = this.config;
+        const pinned = pinnedDistro(config.distro);
+        if (pinned !== undefined)
+            return pinned;
+        if (!isDefaultDistro(config.distro)) {
+            for (const candidate of [policy?.workspaceRoot, config.cwd]) {
+                const named = distroOfUnc(candidate);
+                if (named !== undefined)
+                    return named;
+            }
+        }
+        return this.distro();
+    }
     /**
      * Translate one caller path into the world path, enforcing the distro fence.
      *
@@ -1152,13 +1409,13 @@ export class WslFileSystem extends LocalFileSystem {
      */
     async worldPath(path, cwd) {
         const config = this.config;
-        const distro = await this.distro();
+        const distro = await this.distroForPath(path, cwd);
         let base = cwd ?? config.cwd;
         if (String(base ?? "").trim().length === 0 && isRelativeWorldPath(path)) {
             // An empty `cwd` means the distro user's home. Only relative input
             // consults the base at all, which is also the only case that has to pay
             // for the `wsl.exe` query — an absolute path never does.
-            base = await distroHome(this);
+            base = await distroHome(this, distro);
         }
         const world = toWorldPath(path, { distro, cwd: base });
         const refusal = outsideDistroRefusal({ path, world, distro, restrictToDistro: config.restrictToDistro });
@@ -1183,10 +1440,11 @@ export class WslFileSystem extends LocalFileSystem {
         const linux = uncToPosix(world)?.linuxPath ?? windowsToLinuxMount(world);
         if (linux === undefined)
             throw new FsError(`cannot serve "${path}" from inside the distro`, "FS_IO_ERROR");
+        const distro = uncToPosix(world)?.distro ?? await this.distroForPath(path, opts?.cwd);
         try {
             // The substrate's resolved shape carries plain-string keys; the seam's
             // branded tokens ride one type-level cast (runtime shape unchanged).
-            return (await (await this.agentSubstrate()).resolve(linux, opts?.signal));
+            return (await (await this.agentSubstrateFor(distro)).resolve(linux, opts?.signal));
         }
         catch (error) {
             throw this.peerError(error);
@@ -1222,8 +1480,8 @@ export class WslFileSystem extends LocalFileSystem {
         }
         if (policy.mode !== "workspace-write")
             return target;
-        const fresh = await this.resolve(target.displayPath);
-        const distro = await this.distro();
+        const distro = await this.distroForTarget(target);
+        const fresh = await this.resolve(target.targetKey);
         for (const root of wslWritableRoots(policy, distro)) {
             if (isWorldPathUnder(fresh.targetKey, root, { distro }))
                 return fresh;
@@ -1240,7 +1498,7 @@ export class WslFileSystem extends LocalFileSystem {
      */
     async stat(target, signal) {
         try {
-            return (await (await this.agentSubstrate()).stat(target, signal));
+            return (await (await this.substrateForTarget(target)).stat(target, signal));
         }
         catch (error) {
             throw this.peerError(error);
@@ -1260,8 +1518,9 @@ export class WslFileSystem extends LocalFileSystem {
         const linux = uncToPosix(world)?.linuxPath ?? windowsToLinuxMount(world);
         if (linux === undefined)
             throw new FsError(`cannot inspect "${path}" from inside the distro`, "FS_IO_ERROR");
+        const distro = uncToPosix(world)?.distro ?? await this.distroForPath(path, opts?.cwd);
         try {
-            return (await (await this.agentSubstrate()).lstat(linux, signal));
+            return (await (await this.agentSubstrateFor(distro)).lstat(linux, signal));
         }
         catch (error) {
             throw this.peerError(error);
@@ -1276,7 +1535,7 @@ export class WslFileSystem extends LocalFileSystem {
      */
     async readText(target, signal) {
         try {
-            return await (await this.agentSubstrate()).readText(target, signal);
+            return await (await this.substrateForTarget(target)).readText(target, signal);
         }
         catch (error) {
             throw this.peerError(error);
@@ -1291,7 +1550,7 @@ export class WslFileSystem extends LocalFileSystem {
      */
     async streamText(target, signal) {
         try {
-            return await (await this.agentSubstrate()).streamText(target, signal);
+            return await (await this.substrateForTarget(target)).streamText(target, signal);
         }
         catch (error) {
             throw this.peerError(error);
@@ -1307,7 +1566,7 @@ export class WslFileSystem extends LocalFileSystem {
      */
     async readBytes(target, signal, maxBytes) {
         try {
-            return await (await this.agentSubstrate()).readBytes(target, signal, maxBytes);
+            return await (await this.substrateForTarget(target)).readBytes(target, signal, maxBytes);
         }
         catch (error) {
             throw this.peerError(error);
@@ -1323,7 +1582,7 @@ export class WslFileSystem extends LocalFileSystem {
      */
     async readByteRange(target, range, signal) {
         try {
-            return await (await this.agentSubstrate()).readByteRange(target, range, signal);
+            return await (await this.substrateForTarget(target)).readByteRange(target, range, signal);
         }
         catch (error) {
             throw this.peerError(error);
@@ -1339,7 +1598,7 @@ export class WslFileSystem extends LocalFileSystem {
      */
     async listDir(target, signal) {
         try {
-            return (await (await this.agentSubstrate()).listDir(target, signal));
+            return (await (await this.substrateForTarget(target)).listDir(target, signal));
         }
         catch (error) {
             throw this.peerError(error);
@@ -1352,10 +1611,10 @@ export class WslFileSystem extends LocalFileSystem {
      * plain callback over image attachments, and `packages/api/session-controller`
      * plus the UI's open/reveal path compare the return value against `undefined`
      * without awaiting. The mapping is therefore built from facts that are already
-     * known — the distro, once `distro()` has resolved it (the pinned config, or
-     * the default `wsl.exe` answered earlier: the first filesystem operation
-     * resolves it), and the configured `cwd`, or the resolved home for a relative
-     * path. A call that would have to ask `wsl.exe` — a cold default distro, or a
+     * known — a UNC host path names its own distro outright; a non-UNC path uses
+     * the pinned/config default once `distro()` has resolved it, and the
+     * configured `cwd`, or the resolved home for a relative path. A call that
+     * would have to ask `wsl.exe` — a cold default distro with no UNC, or a
      * relative path before the home is known — answers `undefined`, which every
      * consumer reads as "no mapping", the same answer the ssh provider gives for
      * a path it cannot map.
@@ -1373,16 +1632,21 @@ export class WslFileSystem extends LocalFileSystem {
      */
     processPathFromHostPath(hostPath) {
         const config = this.config;
-        if (this.resolvedDistro.length === 0)
+        const choice = selectDistro({
+            configured: config.distro,
+            candidates: [hostPath, config.cwd],
+            fallback: this.resolvedDistro,
+        });
+        if (choice.distro.length === 0)
             return undefined;
         let base = config.cwd;
         if (String(base ?? "").trim().length === 0 && isRelativeWorldPath(hostPath)) {
-            if (this.resolvedHome === undefined)
+            base = this.resolvedHomes.get(choice.distro) ?? (choice.distro === this.resolvedDistro ? this.resolvedHome : undefined);
+            if (base === undefined)
                 return undefined;
-            base = this.resolvedHome;
         }
-        const world = toWorldPath(hostPath, { distro: this.resolvedDistro, cwd: base });
-        const refusal = outsideDistroRefusal({ path: hostPath, world, distro: this.resolvedDistro, restrictToDistro: config.restrictToDistro });
+        const world = toWorldPath(hostPath, { distro: choice.distro, cwd: base });
+        const refusal = outsideDistroRefusal({ path: hostPath, world, distro: choice.distro, restrictToDistro: config.restrictToDistro });
         return refusal === null ? world : undefined;
     }
     /**
@@ -1409,7 +1673,19 @@ export class WslFileSystem extends LocalFileSystem {
         if (parsed === undefined) {
             throw new FsError(`cannot watch "${target.displayPath}": not a path inside the distro`, "FS_IO_ERROR");
         }
-        const distro = await this.distro();
+        const pinned = pinnedDistro(config.distro);
+        const configuredName = pinned ?? (isDefaultDistro(config.distro) ? await this.distro() : undefined);
+        if (configuredName !== undefined) {
+            const refusal = outsideDistroRefusal({
+                path: target.displayPath,
+                world: target.targetKey,
+                distro: configuredName,
+                restrictToDistro: config.restrictToDistro,
+            });
+            if (refusal !== null)
+                throw new FsError(refusal.message, refusal.code);
+        }
+        const distro = parsed.distro;
         return armDistroWatcher({
             wslPath: config.wslPath,
             distro,
@@ -1439,7 +1715,7 @@ export class WslFileSystem extends LocalFileSystem {
         const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
         const fenced = await this.checkedTarget(target, policy);
         try {
-            return (await (await this.agentSubstrate()).writeText(fenced, content, expected, signal, policy));
+            return (await (await this.substrateForTarget(fenced)).writeText(fenced, content, expected, signal, policy));
         }
         catch (error) {
             throw this.peerError(error);
@@ -1461,7 +1737,7 @@ export class WslFileSystem extends LocalFileSystem {
         const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
         const fenced = await this.checkedTarget(target, policy);
         try {
-            return (await (await this.agentSubstrate()).editText(fenced, edit, expected, signal, policy));
+            return (await (await this.substrateForTarget(fenced)).editText(fenced, edit, expected, signal, policy));
         }
         catch (error) {
             throw this.peerError(error);