dsh-plugin-wsl-env 0.9.0 → 0.11.0

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[];

package/lib/session-scope.js

@@ -0,0 +1,191 @@
+/**
+ * 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
+ */
+/** The longest piece of a unit name this builder emits, per component. */
+const MAX_COMPONENT = 64;
+/**
+ * Characters systemd accepts in a unit name; everything else is folded to `_`.
+ * The allowed set is `[A-Za-z0-9:_.\-]`; `:` is legal in unit names but not
+ * useful here, so it is folded too, keeping the name easy to copy into a
+ * shell.
+ */
+const UNIT_CHARS = /[^A-Za-z0-9_.-]/gu;
+/**
+ * Sanitize one component of a unit name.
+ *
+ * @param value - the raw component.
+ * @param fallback - the component to use when nothing survives.
+ * @returns the sanitized, length-capped component.
+ */
+function component(value, fallback) {
+    const clean = value.replace(UNIT_CHARS, "_").slice(0, MAX_COMPONENT);
+    return clean.length > 0 ? clean : fallback;
+}
+/**
+ * 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 function sessionScopeUnit(distro, token) {
+    return `dsh-wsl-${component(distro, "distro")}-${component(token, "session")}`;
+}
+/**
+ * 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 function sessionScopePrefix(unit) {
+    return ["systemd-run", "--user", "--scope", "--quiet", "--unit", unit, "--"];
+}
+/**
+ * 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 function sessionScopeStopArgv({ wslPath, distro, unit }) {
+    return [
+        wslPath,
+        ...(distro.length > 0 ? ["-d", distro] : []),
+        "--exec",
+        "systemctl",
+        "--user",
+        "stop",
+        unit,
+    ];
+}
+/**
+ * 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 function sessionScopeProbeScript() {
+    return [
+        '[ -d /run/systemd/system ] || { echo no-systemd; exit 0; }',
+        'state=$(systemctl --user is-system-running 2>/dev/null || true)',
+        'case "$state" in running|degraded) ;; *) echo no-user-manager; exit 0;; esac',
+        'command -v systemd-run >/dev/null 2>&1 || { echo no-systemd-run; exit 0; }',
+        'loginctl show-user "$(id -un)" -p Linger 2>/dev/null | grep -q "^Linger=yes$" || { echo no-linger; exit 0; }',
+        "echo ok",
+    ].join("\n");
+}
+/**
+ * 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 function sessionScopeSweepScript() {
+    return [
+        // Without a user manager there is nothing to list.
+        'systemctl --user is-system-running >/dev/null 2>&1 || exit 0',
+        "systemctl --user list-units 'dsh-wsl-*.scope' --all --plain --no-legend --no-pager 2>/dev/null | while read -r unit _; do",
+        '  [ -n "$unit" ] || continue',
+        '  cg=$(systemctl --user show -p ControlGroup --value "$unit" 2>/dev/null)',
+        '  [ -n "$cg" ] || continue',
+        '  alive=0',
+        '  if [ -r "/sys/fs/cgroup$cg/cgroup.procs" ]; then',
+        '    while read -r pid; do',
+        '      [ -n "$pid" ] || continue',
+        "      if tr '\\0' ' ' < \"/proc/$pid/cmdline\" 2>/dev/null | grep -q -e 'wsl-agent.sh' -e 'dsh-wsl-agent'; then alive=1; break; fi",
+        '    done < "/sys/fs/cgroup$cg/cgroup.procs"',
+        '  fi',
+        '  [ "$alive" -eq 1 ] || systemctl --user stop "$unit" >/dev/null 2>&1 || true',
+        'done',
+        'exit 0',
+    ].join("\n");
+}
+/**
+ * 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 function sessionScopeProblem({ output, distro }) {
+    const word = output.stdout.trim().split(/\r?\n/u)[0]?.trim() ?? "";
+    switch (word) {
+        case "ok":
+            return null;
+        case "no-systemd":
+            return `sessionSandbox needs systemd as PID 1 in "${distro}": set [boot] systemd=true in /etc/wsl.conf, run "wsl --shutdown", and reopen the session.`;
+        case "no-user-manager":
+            return `sessionSandbox needs a reachable systemd user manager in "${distro}": log in to the distro once, or enable lingering (see the next refusal).`;
+        case "no-systemd-run":
+            return `sessionSandbox needs "systemd-run" in "${distro}"; the distro's systemd package is incomplete or missing.`;
+        case "no-linger":
+            return `sessionSandbox needs the user manager to outlive a login session: run "loginctl enable-linger $USER" in "${distro}" and retry.`;
+        default:
+            return `the sessionSandbox preflight in "${distro}" answered ${word === "" ? "(nothing)" : `"${word}"`}${output.error === undefined ? "" : `: ${output.error}`}; see docs/adr/0001-session-scoped-sandbox.md.`;
+    }
+}
+/**
+ * The host argv for the preflight probe.
+ *
+ * @param options - the transport path and distro.
+ * @returns the `wsl.exe --exec sh -c <script>` argv.
+ */
+export function sessionScopeProbeArgv({ wslPath, distro }) {
+    return [
+        wslPath,
+        ...(distro.length > 0 ? ["-d", distro] : []),
+        "--exec",
+        "sh",
+        "-c",
+        sessionScopeProbeScript(),
+    ];
+}

package/lib/shell-env.js

@@ -30,7 +30,7 @@ import z from "@deepseek-ai/schemastery";
 import { isAnotherDistrosUnc, isWslUnc } from "./paths.js";
 import { defaultDistro, defaultShell, linuxHomePath } from "./wsl.js";
 import { sharedAgent } from "./agent-shared.js";
-import { listeningPorts } from "./ports.js";
+import { scanListeningPorts } from "./ports.js";
 export const name = "wsl-shell-env";
 export const inject = ["shellEnv"];
 export const Config = z.object({
@@ -68,7 +68,7 @@ export async function apply(ctx, config = {}) {
             description: `Home directory of the user model shell calls run as inside ${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 scan.`,
+            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.`,
         },
     };
     // The port snapshot refreshes on a timer and is served synchronously: the
@@ -76,7 +76,14 @@ export async function apply(ctx, config = {}) {
     // the timer bounds staleness instead (see lib/ports.js).
     let ports = [];
     const refreshPorts = async () => {
-        ports = await listeningPorts(sharedAgent(distro), 8000);
+        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 = next;
     };
     void refreshPorts();
     const portsTimer = setInterval(() => void refreshPorts(), config.portsRefreshMs);

package/lib/watcher.d.ts

@@ -8,21 +8,33 @@
  * whenever something under `target` may have changed. That is cheap to honor
  * from inside the distro, where the kernel does know.
  *
- * The watcher is a long-lived `wsl.exe` shell loop: periodically
+ * When `inotifywait` is installed and the target is an unbounded directory,
+ * the watcher uses inotify: recursive kernel watches, one `C` per 0.5s of
+ * events (a build's event storm is coalesced, the first event is immediate).
+ * Otherwise it falls back to the long-lived polling loop: every cadence,
  * `find <dir> -newer <stamp>` — the directory itself is in the scan, so
  * creations AND deletions (which bump the parent's mtime) are both seen — and
- * one `C` line per hit. No `inotifywait` dependency; the mtime walk is exact
- * for interactive-paced edits, which is the only pace a session watch serves.
+ * one `C` line per hit. A FILE target uses the `mtime:size` fingerprint (so a
+ * rename-over or an in-place write is seen), and a positive `maxDepth` keeps
+ * the polling scan because inotify cannot bound its own walk.
  *
  * The loop speaks three one-letter lines, the watcher protocol:
  *
  *   - `R` — READY: the activation barrier; the host resolves the watch promise
  *     on it, never before.
- *   - `C` — CHANGED: something under the target may have changed.
- *   - `E` — ERROR: the watched directory no longer exists, and the loop has
+ *   - `C` — CHANGED: the target may have changed.
+ *   - `E` — ERROR: the watched path no longer exists, and the loop has
  *     exited. Without it a vanished target would sit armed forever — `find`
  *     over a missing directory prints nothing, indistinguishable from "no
  *     changes" — so the loop says so and the host reports it.
+ *   - `P <pid>` — the loop shell's PID, sent before READY. The host uses it to
+ *     stop the loop with a second `wsl.exe` on close: killing the transport
+ *     alone does not reliably close the distro-side pipe.
+ *   - `H` — HEARTBEAT: liveness only, ignored by the host. It exists so the
+ *     loop notices a closed stdout pipe: the host's close kills `wsl.exe` but
+ *     cannot signal the distro-side shell, and without a write that shell
+ *     would sleep and poll forever. The `PIPE` trap turns that write's
+ *     SIGPIPE into a clean exit through the stamp-removing EXIT trap.
  *
  * Known blind spot, accepted and documented: a file created with an mtime
  * older than the stamp (`cp -p`, `tar -x`) is not seen until something else
@@ -37,19 +49,20 @@
 import type { ChildProcess } from "node:child_process";
 /**
  * The shell loop the watcher runs, parameterised by argv so no path can break
- * quoting: `$1` is the Linux directory, `$2` the poll interval in seconds.
- * Pure text, so it is unit-testable.
+ * quoting: `$1` is the Linux path (a directory or a file), `$2` the poll
+ * interval in seconds. Pure text, so it is unit-testable.
  *
  * @param intervalSeconds - poll cadence; must be >= 1.
- * @param maxDepth - bound the scan's depth, 1 = the directory
- *   itself and its direct children; 0 (the default) scans the whole tree,
- *   which is the contract's semantics but a real cost over a tree with a
- *   `node_modules` in it.
+ * @param maxDepth - bound the scan's depth for a DIRECTORY target, 1 = the
+ *   directory itself and its direct children; 0 (the default) scans the whole
+ *   tree, which is the contract's semantics. Positive values select the
+ *   polling scan (inotify is used only for the unbounded walk). A file target
+ *   ignores it.
  * @returns the `sh -c` script body.
  */
 export declare function watchLoopScript(intervalSeconds?: number, maxDepth?: number): string;
 /**
- * Arm one in-distro watcher over a Linux directory.
+ * Arm one in-distro watcher over a Linux directory or file.
  *
  * @param options - the watch request.
  * @returns resolves once observation is active, with the async close function