dsh-plugin-wsl-env 0.8.0 → 0.10.0

package/lib/fs-routing.js

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

package/lib/fsio-agent.js

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

package/lib/index.d.ts

@@ -46,6 +46,9 @@ import { FsError } from "@deepseek-ai/dsh-fs";
 import { WslSandbox } from "./sandbox.js";
 import type { WslAgent } from "./agent.js";
 import { AgentSubstrate } from "./fs-substrate.js";
+import { SessionRuntimes } from "./session-runtime.js";
+import type { AgentBackend } from "./native-agent.js";
+import type { SessionRuntimeEntry } from "./session-runtime.js";
 import type { Context } from "@deepseek-ai/cordis";
 import type { FsDirEntry, FsEditOutcome, FsEditRequest, FsInfo, FsPathInfo, FsTarget, FsVersion, FsWriteIntent, FsWriteOutcome } from "@deepseek-ai/dsh-fs";
 import type { SandboxExecutionPolicy, SandboxMode } from "@deepseek-ai/dsh-sandbox";
@@ -125,6 +128,10 @@ export interface WslShellExecutorConfig {
     };
     /** Whether execution prefers the resident agent. */
     agent: boolean;
+    /** Whether commands run in one persistent session scope (ADR 0001). */
+    sessionSandbox: boolean;
+    /** The session runtime's agent backend; `auto` when omitted. */
+    agentBackend?: AgentBackend;
 }
 /**
  * The upstream executor's spawn-spec builder, re-opened for this subclass —
@@ -230,6 +237,17 @@ export declare class WslShellExecutor extends LocalBashExecutor {
          * decoration are identical on both paths.
          */
         agent: z<boolean, boolean, "defined">;
+        agentBackend: z<"auto" | "native" | "shell", "auto" | "native" | "shell", "defined">;
+        /**
+         * Run this session's commands in one persistent systemd user scope (ADR
+         * 0001): background processes survive the command that started them, `/tmp`
+         * is the distro's real `/tmp` under workspace-write, and `ps` sees the
+         * session. The executor holds the runtime until the session's scope
+         * disposes, then stops it. Requires systemd, a reachable user manager and
+         * `Linger`; the preflight refuses with the remedy when one is missing, and
+         * only a success is cached. Off by default; requires `agent: true`.
+         */
+        sessionSandbox: z<boolean, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
         /** Distro name; empty means WSL's own default distro. */
         distro: z<string, string, "defined">;
@@ -294,6 +312,17 @@ export declare class WslShellExecutor extends LocalBashExecutor {
          * decoration are identical on both paths.
          */
         agent: z<boolean, boolean, "defined">;
+        agentBackend: z<"auto" | "native" | "shell", "auto" | "native" | "shell", "defined">;
+        /**
+         * Run this session's commands in one persistent systemd user scope (ADR
+         * 0001): background processes survive the command that started them, `/tmp`
+         * is the distro's real `/tmp` under workspace-write, and `ps` sees the
+         * session. The executor holds the runtime until the session's scope
+         * disposes, then stops it. Requires systemd, a reachable user manager and
+         * `Linger`; the preflight refuses with the remedy when one is missing, and
+         * only a success is cached. Off by default; requires `agent: true`.
+         */
+        sessionSandbox: z<boolean, boolean, "defined">;
     }>>, "plain">;
     /** Cached default distro, resolved once from `wsl.exe -l -q`. */
     resolvedDistro: string;
@@ -305,6 +334,14 @@ export declare class WslShellExecutor extends LocalBashExecutor {
     mode: SandboxMode | undefined;
     /** The distro-side confinement, or nothing when the operator opted out. */
     sandbox: InstanceType<typeof WslSandbox> | undefined;
+    /** The session-runtime registry; tests substitute it. */
+    sessionRuntimes: SessionRuntimes;
+    /** The runtimes this executor holds, by registry key. */
+    sessionRuntimeEntries: Map<string, SessionRuntimeEntry>;
+    /** The preflight's host runner; tests substitute it. */
+    sessionScopeProbe: (argv: string[]) => Promise<string>;
+    /** The last preflight verdict; only a success is cached. */
+    sessionRuntimePreflight: "unknown" | "ready";
     /**
      * Per-process confinement facts retained until settlement. Overlapping calls
      * can carry different policies, so a shared latest-wrap value would classify
@@ -358,6 +395,41 @@ export declare class WslShellExecutor extends LocalBashExecutor {
      * @returns the shared agent.
      */
     executionAgent(distro: string): WslAgent;
+    /**
+     * The persistent session runtime for one policy, when `sessionSandbox` is
+     * on. The executor holds one reference per `(distro, workspace, policy)` and
+     * releases them when the session's scope disposes.
+     *
+     * @param policy - the resolved file-effect policy, when the executor has one.
+     * @param resolved - the resolved spec, for the fallback workspace.
+     * @param distro - the resolved distro name.
+     * @returns the runtime entry, or undefined when the mode is off.
+     */
+    sessionRuntimeFor(policy: {
+        mode: string;
+        workspaceRoot: string;
+    } | undefined, resolved: WslExecSpec, distro: string): SessionRuntimeEntry | undefined;
+    /**
+     * Run the session runtime's preflight once per executor. A failure is a
+     * configuration verdict, not an agent outage: it is raised as an Error with
+     * the remedy, so the command fails closed instead of falling back to the
+     * per-command sandbox. Only success is cached, so a user who follows the
+     * remedy (`loginctl enable-linger`, `[boot] systemd=true`) does not need to
+     * restart the app.
+     *
+     * @param distro - the resolved distro name.
+     * @returns resolved once the platform can host a session runtime.
+     * @throws {Error} with the remedy when it cannot.
+     */
+    ensureSessionRuntimeUsable(distro: string): Promise<void>;
+    /**
+     * Release every runtime this executor holds, stopping each scope. Called
+     * from the session's dispose hook; public so tests and shutdown paths can
+     * await it.
+     *
+     * @returns resolved once every runtime is torn down.
+     */
+    disposeSessionRuntimes(): Promise<void>;
     /**
      * The argv that runs INSIDE the distro for one spec: the resolved shell, its
      * login/command flags, and the command string. This is the argv a
@@ -597,6 +669,8 @@ export interface WslFileSystemConfig {
     diffBasisMaxBytes?: number;
     /** Whether mutations are fenced by the policy. */
     sandbox: boolean;
+    /** Whether confined mutations run in the session runtime (ADR 0001). */
+    sessionSandbox: boolean;
     /** Whether confined profiles mask `/mnt`. */
     maskWindowsDrive: boolean;
     /** Whether paths leaving the distro are refused. */
@@ -633,6 +707,17 @@ export declare class WslFileSystem extends LocalFileSystem {
          * operations are unconfined.
          */
         sandbox: z<boolean, boolean, "defined">;
+        /**
+         * Run confined mutations in the session's systemd user scope — the same
+         * runtime the shell executor acquires for the same (distro, workspace,
+         * policy) — instead of a per-policy confined resident. The kernel
+         * enforcement is the runtime's mount profile, so commands and writes see
+         * the same `/tmp` and workspace; the scope stops when the session's
+         * providers release it. Requires systemd + `Linger`, like `wsl-shell`'s
+         * `sessionSandbox`; the preflight refuses with the remedy. Off for direct
+         * constructions; on in the shipped preset.
+         */
+        sessionSandbox: z<boolean, boolean, "defined">;
         /**
          * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
          * Windows drive from confined commands — same meaning and same honest
@@ -694,6 +779,17 @@ export declare class WslFileSystem extends LocalFileSystem {
          * operations are unconfined.
          */
         sandbox: z<boolean, boolean, "defined">;
+        /**
+         * Run confined mutations in the session's systemd user scope — the same
+         * runtime the shell executor acquires for the same (distro, workspace,
+         * policy) — instead of a per-policy confined resident. The kernel
+         * enforcement is the runtime's mount profile, so commands and writes see
+         * the same `/tmp` and workspace; the scope stops when the session's
+         * providers release it. Requires systemd + `Linger`, like `wsl-shell`'s
+         * `sessionSandbox`; the preflight refuses with the remedy. Off for direct
+         * constructions; on in the shipped preset.
+         */
+        sessionSandbox: z<boolean, boolean, "defined">;
         /**
          * Shadow `/mnt` with an empty tmpfs in every confined profile, hiding the
          * Windows drive from confined commands — same meaning and same honest
@@ -747,6 +843,14 @@ export declare class WslFileSystem extends LocalFileSystem {
     sandbox: InstanceType<typeof WslSandbox>;
     /** The resident agent serving publication (see `publicationAgent`). */
     agentInstance: WslAgent | undefined;
+    /** The session-runtime registry; tests substitute it. */
+    sessionRuntimes: SessionRuntimes;
+    /** The runtimes this provider holds, by registry key. */
+    sessionRuntimeEntries: Map<string, SessionRuntimeEntry>;
+    /** The preflight's host runner; tests substitute it. */
+    sessionScopeProbe: (argv: string[]) => Promise<string>;
+    /** The last preflight verdict; only a success is cached. */
+    sessionRuntimePreflight: "unknown" | "ready";
     /**
      * @param ctx - the composition context.
      * @param config - the validated plugin config.
@@ -776,6 +880,36 @@ export declare class WslFileSystem extends LocalFileSystem {
      * @returns the substrate.
      */
     agentSubstrate(): Promise<AgentSubstrate>;
+    /**
+     * The persistent session runtime for one confined mutation, when
+     * `sessionSandbox` is on. The key is the shell executor's key for the same
+     * session/policy, so the write and the commands share one agent, one mount
+     * view and one scope; the provider holds a reference until the session ends.
+     *
+     * @param policy - the resolved confined policy.
+     * @param distro - the resolved distro name.
+     * @returns the runtime entry, or undefined when the mode is off.
+     */
+    sessionRuntimeFor(policy: {
+        mode: string;
+        workspaceRoot: string;
+    }, distro: string): SessionRuntimeEntry | undefined;
+    /**
+     * Run the session runtime's preflight once per provider. Only success is
+     * cached, so following the remedy does not need an app restart.
+     *
+     * @param distro - the resolved distro name.
+     * @returns resolved once the platform can host the runtime.
+     * @throws {Error} with the remedy when it cannot.
+     */
+    ensureSessionRuntimeUsable(distro: string): Promise<void>;
+    /**
+     * Release every runtime this provider holds. Called from the preset's
+     * dispose effect; public so tests and shutdown paths can await it.
+     *
+     * @returns resolved once every reference is released.
+     */
+    disposeSessionRuntimes(): Promise<void>;
     /**
      * The agent a MUTATION runs on under this resolved policy — stage-two
      * routing. A confined policy addresses the confined resident whose bwrap