dsh-plugin-wsl-env 0.8.0 → 0.10.0

package/lib/session-runtime.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The session-scoped runtime registry (ADR 0001).
+ *
+ * One long-lived agent per `(distro, workspaceRoot, policy)`, shared by the
+ * providers that need it and refcounted: the first `acquire` spawns the agent
+ * inside a systemd user scope, the last `release` closes the agent and stops
+ * the scope (the cgroup then reaps any background dev server a command left
+ * behind). The agent runs with no idle close — its lifetime is the session's —
+ * but an explicit client lease still catches a wedged host.
+ *
+ * The confinement here is the agent's own bwrap mount profile, WITHOUT a PID
+ * namespace: commands are the agent's children, so a background process
+ * survives the command, `/tmp` is the distro's real `/tmp` under
+ * `workspace-write`, and `ps` sees the session. `danger-full-access` gets the
+ * scope but no mounts.
+ *
+ * Nothing in this module touches `wsl.exe` by default except through the
+ * injectable factories; `test/session-runtime.test.mjs` drives the refcount,
+ * the prefix composition and the stop ordering without systemd.
+ *
+ * This is a TypeScript source built to `lib/session-runtime.js`; edit THIS
+ * file and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/session-runtime
+ */
+import { WslAgent } from "./agent.js";
+/**
+ * Run the session runtime's preflight through an injected host runner and map
+ * the answer to a refusal. Shared by the shell executor and the filesystem
+ * provider, so both gate the runtime on the same four requirements.
+ *
+ * @param options - the transport, distro and runner.
+ * @returns the remedy-bearing refusal, or null when the platform is usable.
+ */
+export declare function probeSessionRuntime({ wslPath, distro, run }: {
+    /** The `wsl.exe` path. */
+    wslPath: string;
+    /** The distro name. */
+    distro: string;
+    /** The host runner; throws when the probe could not run. */
+    run: (argv: string[]) => Promise<string>;
+}): Promise<string | null>;
+/** One request for a session runtime. */
+export interface SessionRuntimeRequest {
+    /** The distro the runtime lives in. */
+    distro: string;
+    /** The `wsl.exe` path; defaults to `wsl.exe`. */
+    wslPath?: string;
+    /** The session workspace root, in any coordinate system. */
+    workspaceRoot: string;
+    /** The resolved file-effect mode (`read-only`, `workspace-write`, `danger-full-access`). */
+    mode: string;
+    /** Shadow `/mnt` in the runtime's mount profile. */
+    maskWindowsDrive?: boolean;
+    /** The agent's client lease; 0 disables. */
+    leaseMs?: number;
+}
+/** One live runtime and its refcount. */
+export interface SessionRuntimeEntry {
+    /** The registry key (`distro`, workspace, mode, mask). */
+    key: string;
+    /** The systemd user unit name. */
+    unit: string;
+    /** The resident agent. */
+    agent: WslAgent;
+    /** The distro, for the stop command. */
+    distro: string;
+    /** The `wsl.exe` path, for the stop command. */
+    wslPath: string;
+    /** How many providers hold the runtime. */
+    refs: number;
+}
+/** The injectable edges, so the registry is testable without systemd. */
+export interface SessionRuntimeOptions {
+    /** Create the agent; tests substitute a fake. */
+    spawnAgent?: (options: {
+        /** The distro. */
+        distro: string;
+        /** The `wsl.exe` path. */
+        wslPath: string;
+        /** The scope + mount prefix. */
+        argvPrefix: string[];
+        /** No idle close: the runtime lives for the session. */
+        idleMs: number;
+        /** The explicit client lease. */
+        leaseMs: number;
+        /** The prefix has no PID namespace, so USR1 can reach the agent. */
+        signalable: boolean;
+    }) => WslAgent;
+    /** Stop the scope; tests record it. */
+    stopScope?: (options: {
+        wslPath: string;
+        distro: string;
+        unit: string;
+    }) => void;
+    /** The unique token in the unit name; tests pin it. */
+    token?: () => string;
+}
+/**
+ * Set (or clear) the native binary the session runtime should spawn for one
+ * distro. The host calls this after the copy/verify step; an empty path
+ * clears it and restores the shell agent.
+ *
+ * @param distro - the distro.
+ * @param path - the Linux binary path, or empty to clear.
+ * @param digest - the binary's sha256, which the HELLO must present.
+ */
+export declare function setSessionNativeAgent(distro: string, path: string, digest?: string): void;
+/**
+ * The refcounted registry. One instance lives for the process; providers share
+ * it so the shell and filesystem sides address the same runtime for a session.
+ */
+export declare class SessionRuntimes {
+    /** The live runtimes, by key. */
+    private readonly runtimes;
+    /** The agent factory. */
+    private readonly spawnAgent;
+    /** The scope stopper. */
+    private readonly stopScope;
+    /** The unit-token generator. */
+    private readonly token;
+    /**
+     * @param options - the injectable edges; production passes none.
+     */
+    constructor(options?: SessionRuntimeOptions);
+    /**
+     * The key a request addresses: distro, workspace, mode and mask. A policy
+     * change is a different runtime, because the mount profile is fixed for the
+     * agent's lifetime.
+     *
+     * @param request - the runtime request.
+     * @returns the registry key.
+     */
+    static key(request: Pick<SessionRuntimeRequest, "distro" | "workspaceRoot" | "mode" | "maskWindowsDrive">): string;
+    /**
+     * Acquire the runtime for one key, creating it on first use.
+     *
+     * @param request - the runtime request.
+     * @returns the live entry; the caller holds one reference.
+     */
+    acquire(request: SessionRuntimeRequest): SessionRuntimeEntry;
+    /**
+     * Release one reference. The last release closes the agent and stops the
+     * scope, in that order: the agent's exit ends the protocol, the stop reaps
+     * whatever the session left running.
+     *
+     * @param key - the entry's key.
+     * @returns resolved once the last holder's teardown finished.
+     */
+    release(key: string): Promise<void>;
+    /**
+     * Release every runtime, for a host shutdown or a test. Sequential on
+     * purpose: concurrent closes would race the shared agent's state.
+     *
+     * @returns resolved once every runtime is torn down.
+     */
+    disposeAll(): Promise<void>;
+}
+/** The process-wide registry the providers will share. */
+export declare const sessionRuntimes: SessionRuntimes;

package/lib/session-runtime.js

@@ -0,0 +1,220 @@
+/**
+ * The session-scoped runtime registry (ADR 0001).
+ *
+ * One long-lived agent per `(distro, workspaceRoot, policy)`, shared by the
+ * providers that need it and refcounted: the first `acquire` spawns the agent
+ * inside a systemd user scope, the last `release` closes the agent and stops
+ * the scope (the cgroup then reaps any background dev server a command left
+ * behind). The agent runs with no idle close — its lifetime is the session's —
+ * but an explicit client lease still catches a wedged host.
+ *
+ * The confinement here is the agent's own bwrap mount profile, WITHOUT a PID
+ * namespace: commands are the agent's children, so a background process
+ * survives the command, `/tmp` is the distro's real `/tmp` under
+ * `workspace-write`, and `ps` sees the session. `danger-full-access` gets the
+ * scope but no mounts.
+ *
+ * Nothing in this module touches `wsl.exe` by default except through the
+ * injectable factories; `test/session-runtime.test.mjs` drives the refcount,
+ * the prefix composition and the stop ordering without systemd.
+ *
+ * This is a TypeScript source built to `lib/session-runtime.js`; edit THIS
+ * file and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/session-runtime
+ */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { WslAgent, pinnedWindowsEnv } from "./agent.js";
+import { agentScriptDigest, agentScriptPath } from "./agent-shared.js";
+import { bwrapArgvPrefix } from "./bwrap.js";
+import { toLinuxPath } from "./paths.js";
+import { sessionScopePrefix, sessionScopeProblem, sessionScopeProbeArgv, sessionScopeStopArgv, sessionScopeUnit } from "./session-scope.js";
+/**
+ * Run the session runtime's preflight through an injected host runner and map
+ * the answer to a refusal. Shared by the shell executor and the filesystem
+ * provider, so both gate the runtime on the same four requirements.
+ *
+ * @param options - the transport, distro and runner.
+ * @returns the remedy-bearing refusal, or null when the platform is usable.
+ */
+export async function probeSessionRuntime({ wslPath, distro, run }) {
+    /** @type {{ stdout: string, error?: string }} */
+    let output;
+    try {
+        output = { stdout: await run(sessionScopeProbeArgv({ wslPath, distro })) };
+    }
+    catch (error) {
+        output = { stdout: "", error: String(error) };
+    }
+    return sessionScopeProblem({ output, distro });
+}
+/** The native binary path and HELLO digest per distro, when opted in. */
+const NATIVE_AGENTS = new Map();
+/**
+ * Set (or clear) the native binary the session runtime should spawn for one
+ * distro. The host calls this after the copy/verify step; an empty path
+ * clears it and restores the shell agent.
+ *
+ * @param distro - the distro.
+ * @param path - the Linux binary path, or empty to clear.
+ * @param digest - the binary's sha256, which the HELLO must present.
+ */
+export function setSessionNativeAgent(distro, path, digest = "") {
+    if (path.length === 0)
+        NATIVE_AGENTS.delete(distro);
+    else
+        NATIVE_AGENTS.set(distro, { path, digest });
+}
+/** The default agent factory: the same script/digest the shared resident pins. */
+const spawnSessionAgent = (options) => {
+    const native = NATIVE_AGENTS.get(options.distro);
+    if (native !== undefined) {
+        // The native agent reads its own KILL frame while a command runs, so USR1
+        // is both unnecessary and fatal (it has no handler); cancellation is the
+        // frame path. The HELLO digest binds the process to the copied binary.
+        return new WslAgent({
+            distro: options.distro,
+            wslPath: options.wslPath,
+            scriptPath: native.path,
+            expectedDigest: native.digest,
+            argvPrefix: options.argvPrefix,
+            idleMs: options.idleMs,
+            leaseMs: options.leaseMs,
+            signalable: false,
+            spawnTransport: ({ wslPath, distro, argvPrefix }) => spawn(wslPath, ["-d", distro, "--exec", ...argvPrefix, native.path], {
+                stdio: ["pipe", "pipe", "pipe"],
+                windowsHide: true,
+                env: pinnedWindowsEnv(process.env),
+            }),
+        });
+    }
+    return new WslAgent({
+        distro: options.distro,
+        wslPath: options.wslPath,
+        scriptPath: toLinuxPath(agentScriptPath),
+        expectedDigest: agentScriptDigest,
+        argvPrefix: options.argvPrefix,
+        idleMs: options.idleMs,
+        leaseMs: options.leaseMs,
+        signalable: options.signalable,
+    });
+};
+/** The default stop: a second `wsl.exe` asks the user manager to stop the unit. */
+const stopSessionScope = ({ wslPath, distro, unit }) => {
+    const argv = sessionScopeStopArgv({ wslPath, distro, unit });
+    const child = spawn(argv[0] ?? wslPath, argv.slice(1), {
+        stdio: "ignore",
+        windowsHide: true,
+        env: pinnedWindowsEnv(process.env),
+    });
+    // The scope may already be gone (the agent's exit, a restart). The stop is
+    // best effort; a stale unit is visible to `systemctl --user list-units`.
+    child.on("error", () => { });
+};
+/** The default token: short, unique, and sanitized by {@link sessionScopeUnit}. */
+const defaultToken = () => randomUUID().replace(/-/gu, "").slice(0, 12);
+/**
+ * The refcounted registry. One instance lives for the process; providers share
+ * it so the shell and filesystem sides address the same runtime for a session.
+ */
+export class SessionRuntimes {
+    /** The live runtimes, by key. */
+    runtimes = new Map();
+    /** The agent factory. */
+    spawnAgent;
+    /** The scope stopper. */
+    stopScope;
+    /** The unit-token generator. */
+    token;
+    /**
+     * @param options - the injectable edges; production passes none.
+     */
+    constructor(options = {}) {
+        this.spawnAgent = options.spawnAgent ?? spawnSessionAgent;
+        this.stopScope = options.stopScope ?? stopSessionScope;
+        this.token = options.token ?? defaultToken;
+    }
+    /**
+     * The key a request addresses: distro, workspace, mode and mask. A policy
+     * change is a different runtime, because the mount profile is fixed for the
+     * agent's lifetime.
+     *
+     * @param request - the runtime request.
+     * @returns the registry key.
+     */
+    static key(request) {
+        return [request.distro, request.workspaceRoot, request.mode, request.maskWindowsDrive === true ? "masked" : "visible"].join("\u0000");
+    }
+    /**
+     * Acquire the runtime for one key, creating it on first use.
+     *
+     * @param request - the runtime request.
+     * @returns the live entry; the caller holds one reference.
+     */
+    acquire(request) {
+        const key = SessionRuntimes.key(request);
+        const existing = this.runtimes.get(key);
+        if (existing !== undefined) {
+            existing.refs += 1;
+            return existing;
+        }
+        const wslPath = request.wslPath ?? "wsl.exe";
+        const unit = sessionScopeUnit(request.distro, this.token());
+        const prefix = sessionScopePrefix(unit);
+        if (request.mode !== "danger-full-access") {
+            prefix.push(...bwrapArgvPrefix({ mode: request.mode, workspaceRoot: toLinuxPath(request.workspaceRoot, { distro: request.distro }) }, { maskWindowsDrive: request.maskWindowsDrive, realTmp: true, pidNamespace: false }));
+        }
+        const agent = this.spawnAgent({
+            distro: request.distro,
+            wslPath,
+            argvPrefix: prefix,
+            idleMs: 0,
+            leaseMs: request.leaseMs ?? 0,
+            signalable: true,
+        });
+        const entry = { key, unit, agent, distro: request.distro, wslPath, refs: 1 };
+        this.runtimes.set(key, entry);
+        return entry;
+    }
+    /**
+     * Release one reference. The last release closes the agent and stops the
+     * scope, in that order: the agent's exit ends the protocol, the stop reaps
+     * whatever the session left running.
+     *
+     * @param key - the entry's key.
+     * @returns resolved once the last holder's teardown finished.
+     */
+    async release(key) {
+        const entry = this.runtimes.get(key);
+        if (entry === undefined)
+            return;
+        entry.refs -= 1;
+        if (entry.refs > 0)
+            return;
+        this.runtimes.delete(key);
+        try {
+            await entry.agent.close();
+        }
+        finally {
+            this.stopScope({ wslPath: entry.wslPath, distro: entry.distro, unit: entry.unit });
+        }
+    }
+    /**
+     * Release every runtime, for a host shutdown or a test. Sequential on
+     * purpose: concurrent closes would race the shared agent's state.
+     *
+     * @returns resolved once every runtime is torn down.
+     */
+    async disposeAll() {
+        for (const key of [...this.runtimes.keys()]) {
+            const entry = this.runtimes.get(key);
+            if (entry !== undefined)
+                entry.refs = 1;
+            await this.release(key);
+        }
+    }
+}
+/** The process-wide registry the providers will share. */
+export const sessionRuntimes = new SessionRuntimes();

package/lib/session-scope.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Pure builders for the session-scoped sandbox launcher (ADR 0001).
+ *
+ * The runtime is one transient systemd **user scope** per session, running the
+ * agent as its main process; commands are the agent's children, so a
+ * background dev server stays in the scope's cgroup, `/tmp` is the distro's
+ * real `/tmp`, and `ps` sees the session. Session end stops the scope and the
+ * cgroup reaps everything.
+ *
+ * Nothing here spawns: the host inserts {@link sessionScopePrefix} between
+ * `wsl.exe --exec` and the agent's own argv, runs
+ * {@link sessionScopeProbeArgv} before enabling the mode, and runs
+ * {@link sessionScopeStopArgv} when the session ends. Keeping the shapes pure
+ * is what lets the launcher be tested without systemd.
+ *
+ * This is a TypeScript source built to `lib/session-scope.js`; edit THIS file
+ * and run `pnpm run build` — the artifact under `lib/` is generated, and
+ * `pnpm test` fails when it drifts.
+ *
+ * @module dsh-plugin-wsl/session-scope
+ */
+/**
+ * Build the systemd user unit name for one session runtime.
+ *
+ * The caller supplies a token that is unique for the session (a random hex
+ * string, a session id); the distro name is part of the name so two distros'
+ * runtimes are never confused in `systemctl --user list-units`. The result is
+ * deterministic for the pair, which is what lets the host stop the unit later
+ * without keeping a map.
+ *
+ * @param distro - the distro name.
+ * @param token - the per-session unique token.
+ * @returns a unit name safe for `systemd-run --unit`.
+ */
+export declare function sessionScopeUnit(distro: string, token: string): string;
+/**
+ * The arguments inserted after `wsl.exe --exec` to run the agent in a
+ * transient user scope. The agent's own argv (its confinement prefix, the
+ * shell and the script) follows the `--` terminator.
+ *
+ * `--scope` is deliberate: a scope's stdio is inherited, so the protocol's
+ * pipes stay the transport's; a transient *service* would need `--pipe` and a
+ * fresh verification of its EOF/exit-code semantics (ADR open question).
+ *
+ * @param unit - the unit name from {@link sessionScopeUnit}.
+ * @returns the argv fragment, ending with `--`.
+ */
+export declare function sessionScopePrefix(unit: string): string[];
+/**
+ * The host argv that stops one session runtime. Stopping the scope is the
+ * cleanup step that replaces the per-command PID namespace: the cgroup kills
+ * every descendant, including a background dev server a command left behind.
+ *
+ * @param options - the transport path, distro and unit name.
+ * @returns the `wsl.exe --exec systemctl --user stop` argv.
+ */
+export declare function sessionScopeStopArgv({ wslPath, distro, unit }: {
+    /** The `wsl.exe` path. */
+    wslPath: string;
+    /** The distro name; empty means the default distro. */
+    distro: string;
+    /** The unit name from {@link sessionScopeUnit}. */
+    unit: string;
+}): string[];
+/**
+ * The script the preflight runs inside the distro before the session runtime
+ * is enabled. It answers one word so the host can map the answer to a remedy:
+ *
+ * - `ok` — systemd is PID 1, the user manager answers, `systemd-run` exists
+ *   and the user lingers (a headless `wsl.exe --exec` has no login session).
+ * - `no-systemd` — `/run/systemd/system` is absent (systemd is not PID 1).
+ * - `no-user-manager` — `systemctl --user` does not report running/degraded.
+ * - `no-systemd-run` — the `systemd-run` binary is missing.
+ * - `no-linger` — the user manager would stop with the last session; the
+ *   remedy is `loginctl enable-linger <user>`.
+ *
+ * `degraded` is accepted: a partially failed unit elsewhere does not make the
+ * user manager unable to create a scope.
+ *
+ * @returns the shell script.
+ */
+export declare function sessionScopeProbeScript(): string;
+/**
+ * The script the session preflight runs to stop scopes a crashed app left
+ * behind. A scope is stale when its cgroup has no agent process: the shell
+ * `wsl-agent.sh` or the native `dsh-wsl-agent` is the liveness marker. A live
+ * agent means another session still owns it, so it must not be stopped.
+ * The script only lists `dsh-wsl-*.scope` units and only stops the ones it
+ * can prove stale; if there is no user manager it exits 0 (the session
+ * preflight reports that condition separately).
+ *
+ * @returns the shell script.
+ */
+export declare function sessionScopeSweepScript(): string;
+/**
+ * Map the preflight's answer to a user-facing refusal, or `null` when the
+ * platform can host a session runtime. The probe prints one word (it always
+ * exits 0 so the host reads a verdict, not a spawn error); an empty or unknown
+ * answer is reported with whatever diagnostic the host captured.
+ *
+ * @param options - the probe output and the distro it ran in.
+ * @returns the refusal with a remedy, or null.
+ */
+export declare function sessionScopeProblem({ output, distro }: {
+    /** The probe's stdout, or the host error when it could not run. */
+    output: {
+        stdout: string;
+        error?: string;
+    };
+    /** The distro the probe ran in. */
+    distro: string;
+}): string | null;
+/**
+ * The host argv for the preflight probe.
+ *
+ * @param options - the transport path and distro.
+ * @returns the `wsl.exe --exec sh -c <script>` argv.
+ */
+export declare function sessionScopeProbeArgv({ wslPath, distro }: {
+    /** The `wsl.exe` path. */
+    wslPath: string;
+    /** The distro name; empty means the default distro. */
+    distro: string;
+}): string[];