dsh-plugin-wsl-env 0.11.0 → 0.13.0

package/lib/paths.d.ts

@@ -138,6 +138,21 @@ export declare function windowsToLinuxMount(winPath: string): string | undefined
  * @returns an absolute Linux path, or the input unchanged when it cannot be mapped.
  */
 export declare function toLinuxPath(value: string, options?: WorldPathOptions): string;
+/**
+ * Join a requested path onto a workspace root in the distro's Linux
+ * coordinate system: UNC absolutes map to their Linux paths, POSIX absolutes
+ * win over the root, and relative paths join onto it.
+ *
+ * This is the path half of the shipped `workspace-files` service's `ctx.fs`
+ * calls: the routed backend receives the same path/`cwd` pairs a host
+ * workspace would, so the stock service can serve a distro workspace without a
+ * second implementation.
+ *
+ * @param linuxRoot - the workspace root in Linux form.
+ * @param path - the requested path, in any coordinate system.
+ * @returns the absolute Linux path.
+ */
+export declare function linuxJoin(linuxRoot: string, path: string): string;
 /**
  * Resolve a caller-supplied path into the UNC coordinate system the host's fs
  * calls use. Linux paths from the model, UNC paths from the harness, and

package/lib/paths.js

@@ -238,6 +238,34 @@ export function toLinuxPath(value, options) {
     const baseLinux = toLinuxPath(base, { distro: options?.distro });
     return `${baseLinux.replace(/\/+$/, "")}/${text.replace(/^\.\//, "")}`;
 }
+/**
+ * Join a requested path onto a workspace root in the distro's Linux
+ * coordinate system: UNC absolutes map to their Linux paths, POSIX absolutes
+ * win over the root, and relative paths join onto it.
+ *
+ * This is the path half of the shipped `workspace-files` service's `ctx.fs`
+ * calls: the routed backend receives the same path/`cwd` pairs a host
+ * workspace would, so the stock service can serve a distro workspace without a
+ * second implementation.
+ *
+ * @param linuxRoot - the workspace root in Linux form.
+ * @param path - the requested path, in any coordinate system.
+ * @returns the absolute Linux path.
+ */
+export function linuxJoin(linuxRoot, path) {
+    // The UNC check runs on the RAW spelling: the backslash-to-slash rewrite
+    // below would leave `//wsl.localhost/...`, which the identity regex cannot
+    // see.
+    const parsed = uncToPosix(path);
+    if (parsed !== undefined)
+        return parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+    const text = String(path).replaceAll("\\", "/");
+    if (text.startsWith("/"))
+        return text.length > 1 ? text.replace(/\/+$/, "") : "/";
+    const base = linuxRoot === "/" ? "" : linuxRoot;
+    const joined = text.length === 0 ? base : `${base}/${text}`.replace(/\/\.(?=\/|$)/gu, "");
+    return joined.length === 0 ? "/" : joined;
+}
 /**
  * Resolve a caller-supplied path into the UNC coordinate system the host's fs
  * calls use. Linux paths from the model, UNC paths from the harness, and

package/lib/preflight.d.ts

@@ -27,28 +27,52 @@ import z from "@deepseek-ai/schemastery";
 import type { Context } from "@deepseek-ai/cordis";
 export declare const name = "wsl-preflight";
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
-    /** Distro to preflight; empty means this machine's default distro. */
+    /**
+     * Distro to preflight. Empty/`"auto"` follows the session workspace; an
+     * explicit name pins; `"default"` forces WSL's default.
+     */
     distro: z<string, string, "defined">;
     /** The `wsl.exe` path the probe spawns; keep in step with the providers' `wslPath`. */
     wslPath: z<string, string, "defined">;
     /** Whether the session-start sandbox preflight runs at all. */
     sandbox: z<boolean, boolean, "defined">;
+    /**
+     * Whether the preflight also checks the session-runtime prerequisites
+     * (systemd PID 1, the user manager, `systemd-run`, Linger). On by default,
+     * matching the shipped `sessionSandbox: true`; turn it off when the profile
+     * opts out of the session runtime, or the warning would name a prerequisite
+     * that profile does not use.
+     */
+    sessionSandbox: z<boolean, boolean, "defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
-    /** Distro to preflight; empty means this machine's default distro. */
+    /**
+     * Distro to preflight. Empty/`"auto"` follows the session workspace; an
+     * explicit name pins; `"default"` forces WSL's default.
+     */
     distro: z<string, string, "defined">;
     /** The `wsl.exe` path the probe spawns; keep in step with the providers' `wslPath`. */
     wslPath: z<string, string, "defined">;
     /** Whether the session-start sandbox preflight runs at all. */
     sandbox: z<boolean, boolean, "defined">;
+    /**
+     * Whether the preflight also checks the session-runtime prerequisites
+     * (systemd PID 1, the user manager, `systemd-run`, Linger). On by default,
+     * matching the shipped `sessionSandbox: true`; turn it off when the profile
+     * opts out of the session runtime, or the warning would name a prerequisite
+     * that profile does not use.
+     */
+    sessionSandbox: z<boolean, boolean, "defined">;
 }>>, "plain">;
 /** The config schema's validated output. */
 export interface PreflightConfig {
-    /** Distro to preflight; empty means this machine's default distro. */
+    /** The distro mode: empty/`auto`, an explicit name, or `default`. */
     distro?: string;
     /** The `wsl.exe` path the probe spawns. */
     wslPath?: string;
     /** Whether the session-start sandbox preflight runs at all. */
     sandbox?: boolean;
+    /** Whether the session-runtime prerequisites are preflighted too. */
+    sessionSandbox?: boolean;
 }
 /**
  * The slice of a created agent this service inspects; the harness's agent
@@ -63,6 +87,25 @@ export interface PreflightAgent {
             cwd?: string | undefined;
         };
     } | undefined;
+    /**
+     * The agent's own context, when the harness exposes it. Used to publish the
+     * advisory into the session's runtime context; absent in the unit tests and
+     * on a harness without the `systemPrompt` seam, where the log line stands
+     * alone.
+     */
+    ctx?: {
+        inject?: (names: string[], install: (scope: PreflightPromptScope) => void) => unknown;
+    } | undefined;
+}
+/** The slice of a session context that can carry the advisory. */
+export interface PreflightPromptScope {
+    systemPrompt: {
+        context: (entry: {
+            name: string;
+            order: number;
+            text: () => string;
+        }) => unknown;
+    };
 }
 /**
  * The cordis context extended with the slices this service consumes. `logger`

package/lib/preflight.js

@@ -26,16 +26,28 @@
 import z from "@deepseek-ai/schemastery";
 import { isWslUnc } from "./paths.js";
 import { defaultDistro, runCapture } from "./wsl.js";
+import { distroOfUnc, isDefaultDistro, pinnedDistro } from "./distro-route.js";
 import { bwrapFailure, bwrapUsable, missingBwrapRemedy } from "./sandbox-core.js";
-import { sessionScopeSweepScript } from "./session-scope.js";
+import { sessionScopeProblem, sessionScopeProbeScript, sessionScopeSweepScript } from "./session-scope.js";
 export const name = "wsl-preflight";
 export const Config = z.object({
-    /** Distro to preflight; empty means this machine's default distro. */
+    /**
+     * Distro to preflight. Empty/`"auto"` follows the session workspace; an
+     * explicit name pins; `"default"` forces WSL's default.
+     */
     distro: z.string().default(""),
     /** The `wsl.exe` path the probe spawns; keep in step with the providers' `wslPath`. */
     wslPath: z.string().default("wsl.exe"),
     /** Whether the session-start sandbox preflight runs at all. */
     sandbox: z.boolean().default(true),
+    /**
+     * Whether the preflight also checks the session-runtime prerequisites
+     * (systemd PID 1, the user manager, `systemd-run`, Linger). On by default,
+     * matching the shipped `sessionSandbox: true`; turn it off when the profile
+     * opts out of the session runtime, or the warning would name a prerequisite
+     * that profile does not use.
+     */
+    sessionSandbox: z.boolean().default(true),
 });
 /** Distros whose stale-scope sweep has already run in this process. */
 const sweptDistros = new Set();
@@ -67,6 +79,52 @@ export async function apply(ctx, config = {}) {
         return;
     const wslPath = config.wslPath ?? "wsl.exe";
     const warn = (message) => ctx.logger?.warn?.(message);
+    /**
+     * Publish one advisory: the log line always, plus — when the harness exposes
+     * the agent's `systemPrompt` — a session-scoped runtime-context entry, so the
+     * warning is visible to the session instead of only in the app log. DSH
+     * 0.2.1 has no toast/notice seam; docs/UPSTREAM-SESSION-NOTICE.md records the
+     * ask, and the runtime context is the available visible channel today.
+     *
+     * @param agent - the session that just opened.
+     * @param message - the advisory, remedy included.
+     */
+    const announce = (agent, message) => {
+        warn(message);
+        const agentCtx = agent.ctx;
+        if (agentCtx === undefined || typeof agentCtx.inject !== "function")
+            return;
+        try {
+            agentCtx.inject(["systemPrompt"], (scope) => {
+                scope.systemPrompt.context({ name: "wsl-preflight", order: 200, text: () => message });
+            });
+        }
+        catch (error) {
+            ctx.logger?.debug?.(`wsl-preflight: could not publish the notice to the session (${error?.message ?? error})`);
+        }
+    };
+    /**
+     * Ask the distro's session-runtime probe. Only a recognized refusal is a
+     * verdict: an empty or unfamiliar answer means "cannot tell" (a fixture, an
+     * old image, a wedged shell) and stays at debug level — the preflight is
+     * advisory and must not invent a prerequisite from silence.
+     *
+     * @param distro - the resolved distro.
+     * @returns the remedy, or undefined when the session runtime is usable or unknown.
+     */
+    const probeSession = async (distro) => {
+        try {
+            const output = await runCapture([wslPath, "-d", distro, "--exec", "sh", "-c", sessionScopeProbeScript()]);
+            const word = output.trim().split(/\r?\n/u)[0]?.trim() ?? "";
+            if (!["no-systemd", "no-user-manager", "no-systemd-run", "no-linger"].includes(word))
+                return undefined;
+            return sessionScopeProblem({ output: { stdout: word }, distro }) ?? undefined;
+        }
+        catch (error) {
+            ctx.logger?.debug?.(`wsl-preflight: the session probe could not run (${error?.message ?? error})`);
+            return undefined;
+        }
+    };
     /**
      * Probe the distro once and surface an unusable `bwrap` as a warning.
      *
@@ -76,18 +134,24 @@ export async function apply(ctx, config = {}) {
         // Only a distro workspace has commands that confine: a host session would
         // warn about a sandbox it never uses.
         const cwd = agent?.session?.header?.cwd;
-        if (cwd === undefined || !isWslUnc(cwd))
+        if (agent === undefined || cwd === undefined || !isWslUnc(cwd))
             return;
-        let distro = config.distro ?? "";
+        const pinned = pinnedDistro(config.distro);
+        let distro = pinned ?? "";
         if (distro.length === 0) {
-            try {
-                distro = await defaultDistro({ wslPath });
+            if (!isDefaultDistro(config.distro)) {
+                distro = distroOfUnc(cwd) ?? "";
             }
-            catch (error) {
-                // No WSL at all is the missing-wsl probe's territory; the first
-                // command's own error is the precise one. Stay quiet at warn level.
-                ctx.logger?.debug?.(`wsl-preflight: no default distro to preflight (${error?.message ?? error})`);
-                return;
+            if (distro.length === 0) {
+                try {
+                    distro = await defaultDistro({ wslPath });
+                }
+                catch (error) {
+                    // No WSL at all is the missing-wsl probe's territory; the first
+                    // command's own error is the precise one. Stay quiet at warn level.
+                    ctx.logger?.debug?.(`wsl-preflight: no default distro to preflight (${error?.message ?? error})`);
+                    return;
+                }
             }
         }
         // bwrapUsable answers false on a failed probe — it never rejects — so
@@ -97,11 +161,16 @@ export async function apply(ctx, config = {}) {
         // runtime; a live agent in another session's cgroup makes its scope safe.
         sweepStaleScopes(wslPath, distro);
         const usable = await bwrapUsable({ wslPath, distro });
-        if (usable) {
-            ctx.logger?.debug?.(`wsl-preflight: bwrap is usable inside distro "${distro}"`);
+        if (!usable) {
+            announce(agent, `wsl-preflight: ${bwrapFailure(wslPath, distro) ?? missingBwrapRemedy(distro)}`);
             return;
         }
-        warn(`wsl-preflight: ${bwrapFailure(wslPath, distro) ?? missingBwrapRemedy(distro)}`);
+        ctx.logger?.debug?.(`wsl-preflight: bwrap is usable inside distro "${distro}"`);
+        if (!(config.sessionSandbox ?? true))
+            return;
+        const sessionProblem = await probeSession(distro);
+        if (sessionProblem !== undefined)
+            announce(agent, `wsl-preflight: ${sessionProblem}`);
     };
     ctx.on("agent/created", (payload) => void check(payload?.agent));
     // Mount order is not a guarantee: a session created during startup can finish

package/lib/shell-env.d.ts

@@ -31,19 +31,25 @@ import type { Context } from "@deepseek-ai/cordis";
 export declare const name = "wsl-shell-env";
 export declare const inject: string[];
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
-    /** Distro these facts describe; empty means this machine's default distro. */
+    /**
+     * Distro these facts describe. Empty/`"auto"` follows each session's
+     * workspace; an explicit name pins; `"default"` forces WSL's default.
+     */
     distro: z<string, string, "defined">;
     /** How often the listening-port snapshot refreshes, in milliseconds. */
     portsRefreshMs: z<number, number, "defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
-    /** Distro these facts describe; empty means this machine's default distro. */
+    /**
+     * Distro these facts describe. Empty/`"auto"` follows each session's
+     * workspace; an explicit name pins; `"default"` forces WSL's default.
+     */
     distro: z<string, string, "defined">;
     /** How often the listening-port snapshot refreshes, in milliseconds. */
     portsRefreshMs: z<number, number, "defined">;
 }>>, "plain">;
 /** The config schema's validated output. */
 export interface ShellEnvConfig {
-    /** Distro these facts describe; empty means this machine's default distro. */
+    /** The distro mode: empty/`auto`, an explicit name, or `default`. */
     distro?: string;
     /** How often the listening-port snapshot refreshes, in milliseconds. */
     portsRefreshMs?: number;

package/lib/shell-env.js

@@ -27,14 +27,18 @@
  * @module dsh-plugin-wsl/shell-env
  */
 import z from "@deepseek-ai/schemastery";
-import { isAnotherDistrosUnc, isWslUnc } from "./paths.js";
-import { defaultDistro, defaultShell, linuxHomePath } from "./wsl.js";
+import { uncToPosix } from "./paths.js";
+import { defaultDistro, defaultShell, linuxHomePath, listDistros } from "./wsl.js";
+import { isDefaultDistro, pinnedDistro } from "./distro-route.js";
 import { sharedAgent } from "./agent-shared.js";
 import { scanListeningPorts } from "./ports.js";
 export const name = "wsl-shell-env";
 export const inject = ["shellEnv"];
 export const Config = z.object({
-    /** Distro these facts describe; empty means this machine's default distro. */
+    /**
+     * Distro these facts describe. Empty/`"auto"` follows each session's
+     * workspace; an explicit name pins; `"default"` forces WSL's default.
+     */
     distro: z.string().default(""),
     /** How often the listening-port snapshot refreshes, in milliseconds. */
     portsRefreshMs: z.number().default(10 * 1000),
@@ -47,74 +51,148 @@ export const Config = z.object({
  */
 export async function apply(ctx, config = {}) {
     // `resolve` is called synchronously by the registry (`Object.entries` of its
-    // result), so every fact has to be resolved up front, not per call.
+    // result), so a fact that needs `wsl.exe` cannot be fetched there. The
+    // default/pinned distro is probed once at mount; every other distro is
+    // probed when a session created in it appears, so a machine with several
+    // stopped distros does not boot them all at application start.
     const configured = config.distro ?? "";
-    const distro = configured.length > 0 ? configured : await defaultDistro();
-    // undefined when both probes failed (a cold distro): the fact is then
-    // simply absent, which beats presenting the "bash" placeholder as the
-    // distro's login shell for this process's lifetime.
-    const shell = await defaultShell(distro);
-    // The consumer is a shell running INSIDE the distro, so the fact is the POSIX
-    // path, not the host-side world path.
-    const home = await linuxHomePath(distro);
+    const portsRefreshMs = config.portsRefreshMs ?? 10_000;
+    const pinned = pinnedDistro(configured);
+    let distros;
+    if (pinned !== undefined) {
+        distros = [pinned];
+    }
+    else {
+        try {
+            distros = await listDistros();
+        }
+        catch {
+            distros = [];
+        }
+        if (distros.length === 0) {
+            try {
+                distros = [await defaultDistro()];
+            }
+            catch {
+                distros = [];
+            }
+        }
+    }
+    const defaultName = distros[0];
+    /** The facts one distro can answer; a failed probe leaves its key absent. */
+    const facts = new Map();
+    const inflight = new Set();
+    const ensureFacts = async (distro) => {
+        if (facts.has(distro) || inflight.has(distro))
+            return;
+        inflight.add(distro);
+        try {
+            const [shell, home] = await Promise.all([
+                defaultShell(distro),
+                linuxHomePath(distro).catch(() => undefined),
+            ]);
+            facts.set(distro, { shell, home });
+        }
+        finally {
+            inflight.delete(distro);
+        }
+    };
+    const initial = pinned ?? defaultName;
+    if (initial !== undefined)
+        await ensureFacts(initial);
     const variables = {
         DSH_WSL_DISTRO: {
-            description: `Name of the WSL distro this workspace lives in (${distro}).`,
+            description: "Name of the WSL distro this session's workspace lives in.",
         },
         DSH_WSL_SHELL: {
-            description: `Absolute path of the login shell that model shell calls run in inside ${distro}. Commands are executed by this shell, not by bash.`,
+            description: "Absolute path of the login shell that model shell calls run in inside that distro. Commands are executed by this shell, not by bash.",
         },
         DSH_WSL_HOME: {
-            description: `Home directory of the user model shell calls run as inside ${distro}.`,
+            description: "Home directory of the user model shell calls run as inside that distro.",
         },
         DSH_WSL_PORTS: {
-            description: `Ports with a listener inside ${distro} (comma-separated, ascending), as of the last snapshot — refreshed every ${Math.round(config.portsRefreshMs / 1000)}s, so a dev server started moments ago may not be listed yet. Empty means none were listening at the last successful scan (or no scan has succeeded yet); a failed scan keeps the last successful list.`,
+            description: `Ports with a listener inside that distro (comma-separated, ascending), as of the last snapshot — refreshed every ${Math.round(portsRefreshMs / 1000)}s, so a dev server started moments ago may not be listed yet. Empty means none were listening at the last successful scan (or no scan has succeeded yet); a failed scan keeps the last successful list.`,
         },
     };
     // The port snapshot refreshes on a timer and is served synchronously: the
     // registry's resolve is sync by contract, so live reads are impossible —
-    // the timer bounds staleness instead (see lib/ports.js).
-    let ports = [];
-    const refreshPorts = async () => {
-        const next = await scanListeningPorts(sharedAgent(distro), 8000);
-        if (next === undefined) {
-            // A transient agent outage must not read as "no ports": keep the last
-            // successful snapshot and leave a debug breadcrumb.
-            ctx.logger?.debug?.("wsl-shell-env: port snapshot failed; keeping the last known list");
-            return;
+    // the timer bounds staleness instead (see lib/ports.js). A timer starts only
+    // for a distro a session actually uses, so multi-distro users do not keep
+    // every distro's resident agent warm.
+    const ports = new Map();
+    const timers = new Map();
+    const refreshPorts = async (distro) => {
+        try {
+            const next = await scanListeningPorts(sharedAgent(distro), 8000);
+            if (next === undefined) {
+                // A transient agent outage must not read as "no ports": keep the last
+                // successful snapshot and leave a debug breadcrumb.
+                ctx.logger?.debug?.("wsl-shell-env: port snapshot failed; keeping the last known list");
+                return;
+            }
+            ports.set(distro, next);
         }
-        ports = next;
+        catch {
+            // Same posture as a failed scan: keep the last successful list.
+        }
+    };
+    const ensurePorts = (distro) => {
+        if (timers.has(distro))
+            return;
+        void refreshPorts(distro);
+        const timer = setInterval(() => void refreshPorts(distro), portsRefreshMs);
+        timer.unref?.();
+        timers.set(distro, timer);
+    };
+    const lifecycle = ctx;
+    const consider = (agent) => {
+        const parsed = uncToPosix(String(agent?.session?.header?.cwd ?? ""));
+        if (parsed === undefined)
+            return;
+        if (pinned !== undefined && parsed.distro.toLowerCase() !== pinned.toLowerCase())
+            return;
+        if (isDefaultDistro(configured) && defaultName !== undefined && parsed.distro.toLowerCase() !== defaultName.toLowerCase())
+            return;
+        void ensureFacts(parsed.distro);
+        ensurePorts(parsed.distro);
     };
-    void refreshPorts();
-    const portsTimer = setInterval(() => void refreshPorts(), config.portsRefreshMs);
-    portsTimer.unref?.();
+    const off = lifecycle.on?.("agent/created", (payload) => consider(payload?.agent));
+    for (const agent of lifecycle.agents?.list?.() ?? [])
+        consider(agent);
     const dispose = ctx.shellEnv.register({
         name: "dsh-plugin-wsl-env",
         variables,
         resolve: (execution) => {
             const cwd = execution?.agent?.session?.header?.cwd;
-            if (cwd === undefined || !isWslUnc(cwd))
+            const parsed = uncToPosix(String(cwd ?? ""));
+            if (parsed === undefined)
+                return {};
+            const named = parsed.distro;
+            if (pinned !== undefined && named.toLowerCase() !== pinned.toLowerCase())
                 return {};
-            // The facts describe ONE distro. A workspace under another distro's UNC
-            // is not that distro — the shell refuses its commands outright (the
-            // cross-distro guard) — so the honest resolution is no facts at all,
-            // not another distro's home and shell presented as this session's.
-            if (isAnotherDistrosUnc(cwd, distro))
+            if (isDefaultDistro(configured) && defaultName !== undefined && named.toLowerCase() !== defaultName.toLowerCase())
                 return {};
-            const facts = {
-                DSH_WSL_DISTRO: distro,
-                DSH_WSL_HOME: home,
-                DSH_WSL_PORTS: ports.join(","),
+            const canonical = [...facts.keys()].find((distro) => distro.toLowerCase() === named.toLowerCase()) ?? named;
+            const known = facts.get(canonical);
+            ensurePorts(canonical);
+            const resolved = {
+                DSH_WSL_DISTRO: canonical,
+                DSH_WSL_PORTS: (ports.get(canonical) ?? []).join(","),
             };
-            if (shell !== undefined)
-                facts.DSH_WSL_SHELL = shell;
-            return facts;
+            if (known?.home !== undefined)
+                resolved.DSH_WSL_HOME = known.home;
+            if (known?.shell !== undefined)
+                resolved.DSH_WSL_SHELL = known.shell;
+            return resolved;
         },
     });
     // Disposing matters: a config hot-reload re-runs apply(), and the registry
     // rejects a second contributor claiming the same keys.
     ctx.effect(() => () => {
-        clearInterval(portsTimer);
+        off?.();
+        for (const timer of timers.values())
+            clearInterval(timer);
+        timers.clear();
         dispose();
     });
 }

package/lib/subprocess.d.ts

@@ -89,7 +89,10 @@ import type { SubprocessTerminalActivity } from "./terminal-activity.js";
  * builds.
  */
 export interface WslSubprocessConfig {
-    /** Distro name; empty means WSL's own default distro. */
+    /**
+     * Distro mode: empty/`"auto"` follows the launch directory, `"default"`
+     * forces WSL's default, and an explicit name pins.
+     */
     distro: string;
     /** Path to `wsl.exe`. */
     wslPath: string;
@@ -121,7 +124,10 @@ export interface WslSubprocessConfig {
  */
 export declare class WslSubprocessRuntime extends LocalSubprocessRuntime {
     static Config: z<Schemastery.ObjectS<NoInfer<{
-        /** Distro name; empty means WSL's own default distro. */
+        /**
+         * Distro mode: empty/`"auto"` follows the launch directory, `"default"`
+         * forces WSL's default, and an explicit name pins.
+         */
         distro: z<string, string, "defined">;
         /** Path to `wsl.exe`; overridable for a non-standard install. */
         wslPath: z<string, string, "defined">;
@@ -163,7 +169,10 @@ export declare class WslSubprocessRuntime extends LocalSubprocessRuntime {
          */
         terminalIdleReclaim: z<boolean, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
-        /** Distro name; empty means WSL's own default distro. */
+        /**
+         * Distro mode: empty/`"auto"` follows the launch directory, `"default"`
+         * forces WSL's default, and an explicit name pins.
+         */
         distro: z<string, string, "defined">;
         /** Path to `wsl.exe`; overridable for a non-standard install. */
         wslPath: z<string, string, "defined">;

package/lib/subprocess.js

@@ -90,6 +90,7 @@ import { sharedAgent } from "./agent-shared.js";
 import { parseTerminalActivity, TERMINAL_ID_ENV, terminalActivityProbe, wrapTerminalHandle } from "./terminal-activity.js";
 import { AgentUnavailableError } from "./agent-errors.js";
 import { terminalRoute } from "./terminal-route.js";
+import { pinnedDistro, isDefaultDistro } from "./distro-route.js";
 /**
  * Env names a terminal launch keeps for the distro. `TERM` rides along because
  * the PTY consumer sets it for the host process, and WSL imports no name that
@@ -111,7 +112,10 @@ const WSL_PROGRAM = "wsl";
  */
 export class WslSubprocessRuntime extends LocalSubprocessRuntime {
     static Config = z.object({
-        /** Distro name; empty means WSL's own default distro. */
+        /**
+         * Distro mode: empty/`"auto"` follows the launch directory, `"default"`
+         * forces WSL's default, and an explicit name pins.
+         */
         distro: z.string().default(""),
         /** Path to `wsl.exe`; overridable for a non-standard install. */
         wslPath: z.string().default(DEFAULT_WSL_PATH),
@@ -160,7 +164,7 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
     constructor(ctx, config) {
         super(ctx);
         this.config = config;
-        this.resolvedDistro = config.distro;
+        this.resolvedDistro = pinnedDistro(config.distro) ?? "";
     }
     /**
      * The distro a launch uses when the request's directory does not name one,
@@ -192,8 +196,22 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
     async terminalTarget(cwd) {
         const text = String(cwd ?? "").trim();
         const named = uncToPosix(text);
-        if (named !== undefined)
+        if (named !== undefined) {
+            const pinned = pinnedDistro(this.config.distro);
+            if (pinned !== undefined && named.distro.toLowerCase() !== pinned.toLowerCase()) {
+                throw new Error(`"${text}" names a workspace in another WSL distro, and this profile pins its terminal to "${pinned}". ` +
+                    `Open a session in that distro, or set this row's distro to ''/auto.`);
+            }
+            if (isDefaultDistro(this.config.distro)) {
+                const fallback = await this.distro();
+                if (named.distro.toLowerCase() !== fallback.toLowerCase()) {
+                    throw new Error(`"${text}" names a workspace in another WSL distro, and this profile forces WSL's default ("${fallback}"). ` +
+                        `Open a session in that distro, or set this row's distro to ''/auto.`);
+                }
+                return { distro: fallback, linuxCwd: named.linuxPath };
+            }
             return { distro: named.distro, linuxCwd: named.linuxPath };
+        }
         const distro = await this.distro();
         if (isPosixAbsolute(text))
             return { distro, linuxCwd: text };