dsh-plugin-wsl-env 0.8.0 → 0.10.0

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

package/lib/watcher.js

@@ -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
@@ -38,14 +50,15 @@ import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 /**
  * 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 function watchLoopScript(intervalSeconds = 2, maxDepth = 0) {
@@ -56,37 +69,90 @@ export function watchLoopScript(intervalSeconds = 2, maxDepth = 0) {
     const depthArgs = depth > 0 ? ` -maxdepth ${depth}` : "";
     // `find` lists the directory itself first: a child's creation or deletion
     // bumps the parent's mtime, so both edges are seen, not just modifications.
+    // A FILE target has no tree to walk; its `mtime:size` fingerprint answers the
+    // same one-way question ("may have changed") and covers a rename-over too,
+    // since the path is re-stat'ed each tick.
     return [
         'D="$1"',
         'S="${TMPDIR:-/tmp}/wsl-watch.$$.stamp"',
+        'FIFO="${TMPDIR:-/tmp}/wsl-watch.$$.fifo"',
+        'IW=""',
         'touch "$S"',
-        // The stamp is the loop's private state, so every way out removes it. The
-        // EXIT trap covers plain exits; a signal alone would end the shell WITHOUT
-        // running it, so TERM/INT/HUP are trapped to a plain exit first.
-        "trap 'rm -f \"$S\"' EXIT",
-        "trap 'exit 0' TERM INT HUP",
-        // The READY line is the activation barrier: everything changed BEFORE it
-        // predates the stamp, so the host must not resolve the watch promise until
-        // it arrives — otherwise a write racing the first tick is invisible forever.
+        // The stamp/FIFO are the loop's private state, so every way out removes
+        // them. The EXIT trap covers plain exits; a signal alone would end the
+        // shell WITHOUT running it, so TERM/INT/HUP/PIPE are trapped to a plain
+        // exit first. `pkill -P $$` also reaps inotifywait/sleep/find.
+        "trap 'kill \"$IW\" 2>/dev/null; pkill -P $$ 2>/dev/null; exec 3>&- 2>/dev/null; rm -f \"$FIFO\" \"$S\" 2>/dev/null' EXIT",
+        "trap 'exit 0' TERM INT HUP PIPE",
+        'F=""',
+        '[ -f "$D" ] && F=$(stat -c "%Y:%s" -- "$D" 2>/dev/null || :)',
+        // Prefer inotify for an unbounded DIRECTORY watch: events are immediate and
+        // the kernel does the walking. A file target uses the fingerprint loop
+        // (it also reports a removal as E), and a bounded scan (maxDepth > 0)
+        // keeps the polling loop, which honors the bound.
+        `if [ -d "$D" ] && [ ${depth} -eq 0 ] && command -v inotifywait >/dev/null 2>&1; then`,
+        '  if mkfifo "$FIFO" 2>/dev/null; then',
+        '    exec 3<>"$FIFO"',
+        '    inotifywait -m -q -r -e create,delete,modify,move,attrib --format "%e" "$D" >"$FIFO" 2>/dev/null &',
+        '    IW=$!',
+        '  fi',
+        'fi',
+        // The PID precedes READY so a close can stop the loop even if the pipe
+        // stays open; killing wsl.exe alone does not close it reliably.
+        "printf 'P %s\\n' \"$$\"",
         "printf 'R\\n'",
-        // Check first, sleep second: a change made right after activation is seen
-        // on the first cadence, not one cadence later.
+        // One C per half second: a build's event storm becomes a coarse
+        // invalidation, while the first event is immediate. A quiet tree blocks
+        // in read; the close stops the shell through the P line, not the pipe.
+        'if [ -n "$IW" ]; then',
+        // A one-second marker on the same FIFO wakes the blocking read so the
+        // TERM trap and the vanished-target check run even on a quiet tree. The
+        // marker is not an event: it is skipped, and only checked against the
+        // target's existence.
+        '  ( while :; do sleep 1; printf \'H\\n\' >"$FIFO" 2>/dev/null; done ) &',
+        '  while read -r ev <&3; do',
+        '    if [ "$ev" = "H" ]; then',
+        '      [ -d "$D" ] || { printf \'E\\n\'; exit 1; }',
+        '      continue',
+        '    fi',
+        '    [ -d "$D" ] || { printf \'E\\n\'; exit 1; }',
+        "    printf 'C\\n'",
+        '    sleep 0.5',
+        '  done',
+        '  exec 3>&-',
+        'fi',
+        // Polling fallback: no inotifywait, a bounded scan, or inotifywait exited
+        // (a vanished target or an inotify limit). The stamp is the baseline.
         "while :; do",
-        '  if [ ! -d "$D" ]; then',
-        // Say so and die: silence here is the armed-forever, fires-never trap.
+        '  if [ -d "$D" ]; then',
+        `    if [ -n "$(find "$D"${depthArgs} -newer "$S" -print -quit 2>/dev/null)" ]; then`,
+        '      touch "$S"',
+        "      printf 'C\\n'",
+        '    fi',
+        '  elif [ -f "$D" ]; then',
+        '    cur=$(stat -c "%Y:%s" -- "$D" 2>/dev/null || :)',
+        '    if [ -z "$cur" ]; then',
+        // The file was removed (or became unreadable): the target is gone.
+        "      printf 'E\\n'",
+        '      exit 1',
+        '    fi',
+        '    if [ "$cur" != "$F" ]; then',
+        '      F="$cur"',
+        "      printf 'C\\n'",
+        '    fi',
+        '  else',
+        // Neither a directory nor a file: say so and die, rather than spin.
         "    printf 'E\\n'",
-        "    exit 1",
-        "  fi",
-        `  if [ -n "$(find "$D"${depthArgs} -newer "$S" -print -quit 2>/dev/null)" ]; then`,
-        '    touch "$S"',
-        "    printf 'C\\n'",
-        "  fi",
+        '    exit 1',
+        '  fi',
+        // Liveness: the host ignores H; the write dies with the pipe.
+        "  printf 'H\\n'",
         `  sleep ${seconds}`,
-        "done",
+        'done',
     ].join("\n");
 }
 /**
- * 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
@@ -118,8 +184,15 @@ export function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError
             const detail = stderrTail.trim();
             return detail.length > 0 ? `${message}: ${detail}` : message;
         };
+        let loopPid;
         const lines = createInterface({ input: child.stdout });
         lines.on("line", (line) => {
+            if (line.startsWith("P ")) {
+                const pid = Number.parseInt(line.slice(2), 10);
+                if (Number.isInteger(pid) && pid > 0)
+                    loopPid = pid;
+                return;
+            }
             if (line === "R") {
                 if (!settled && !signal?.aborted) {
                     settled = true;
@@ -128,7 +201,7 @@ export function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError
                 return;
             }
             if (line === "E") {
-                fail(new Error(describe(`the watched directory "${linuxPath}" no longer exists inside "${distro}", so the watch has ended`)));
+                fail(new Error(describe(`the watched path "${linuxPath}" no longer exists inside "${distro}", so the watch has ended`)));
                 return;
             }
             if (line === "C") {
@@ -139,10 +212,25 @@ export function armDistroWatcher({ wslPath, distro, linuxPath, onChange, onError
             if (closed)
                 return;
             closed = true;
+            const pid = loopPid;
             child.removeAllListeners("exit");
             lines.close();
             child.stdout?.destroy();
             child.kill();
+            if (pid !== undefined) {
+                // A second wsl.exe reaches the same distro namespace; the loop's TERM
+                // trap exits through the EXIT cleanup, which removes the stamp.
+                try {
+                    const stopper = doSpawn(wslPath, ["-d", distro, "--exec", "sh", "-c", 'kill -TERM "$1" 2>/dev/null', "sh", String(pid)]);
+                    stopper.stdout?.destroy();
+                    stopper.stderr?.destroy();
+                    stopper.on("error", () => { });
+                    stopper.unref?.();
+                }
+                catch {
+                    // Best effort: the transport kill already happened.
+                }
+            }
             await new Promise((resolveClose) => {
                 if (child.exitCode !== null || child.signalCode !== null)
                     return resolveClose();

package/lib/workspace-files-route.d.ts

@@ -42,12 +42,14 @@ export declare function linuxJoin(linuxRoot: string, path: string): string;
 /**
  * The record invocation for one path: line 1 is the no-follow kind (the
  * upstream lstat gate), line 2 the follow-stat fields (the upstream final
- * stat), tab-joined.
+ * stat), tab-joined. The path is resolved and contained first — the GUI's
+ * workspace is a boundary for every read, not just for listings.
  *
  * @param file - absolute Linux path.
+ * @param root - the workspace root in Linux form (containment boundary).
  * @returns the agent argv.
  */
-export declare function statRecordArgv(file: string): string[];
+export declare function statRecordArgv(file: string, root: string): string[];
 /**
  * Parse one stat record (kind + follow fields, tab-joined).
  *
@@ -77,9 +79,10 @@ export declare function wireKind(kind: string): string;
  * @param file - absolute Linux path.
  * @param offset - first line to return (1-based).
  * @param limit - maximum lines to return.
+ * @param root - the workspace root in Linux form (containment boundary).
  * @returns the agent argv.
  */
-export declare function pageArgv(file: string, offset: number, limit: number): string[];
+export declare function pageArgv(file: string, offset: number, limit: number, root: string): string[];
 /**
  * The byte-window invocation: the stat record rides stderr, the window rides
  * stdout. `$1` is the file, `$2` the byte offset, `$3` the byte count.
@@ -87,9 +90,10 @@ export declare function pageArgv(file: string, offset: number, limit: number): s
  * @param file - absolute Linux path.
  * @param offset - byte offset (0-based).
  * @param length - byte count.
+ * @param root - the workspace root in Linux form (containment boundary).
  * @returns the agent argv.
  */
-export declare function bytesArgv(file: string, offset: number, length: number): string[];
+export declare function bytesArgv(file: string, offset: number, length: number, root: string): string[];
 /**
  * Parse the stat record a read or byte-window relayed on stderr.
  *

package/lib/workspace-files-route.js

@@ -64,21 +64,43 @@ export function linuxJoin(linuxRoot, path) {
     const joined = text.length === 0 ? base : `${base}/${text}`.replace(/\/\.(?=\/|$)/gu, "");
     return joined.length === 0 ? "/" : joined;
 }
+/**
+ * The containment guard every distro-side workspace read shares. `$1` is the
+ * requested file, `$2` the workspace root; both are canonicalized with
+ * `realpath -L`, and a target that is neither the root itself nor below it is
+ * refused with exit 3 (the `workspace-file/outside-workspace` refusal). The
+ * resolved file is left in `real` for the rest of the script.
+ *
+ * A root of `/` admits every absolute path: the workspace IS the distro. The
+ * `-L` spelling matches the listing guard's, so symlinked workspace roots and
+ * `..` segments resolve the same way on both sides.
+ */
+const CONTAIN_FN = [
+    'contain() {',
+    '  real=$(realpath -L -- "$1") || exit 2',
+    '  root=$(realpath -L -- "$2") || exit 2',
+    '  case "$root" in /) ;; *) case "$real" in "$root"|"$root"/*) ;; *) echo "OUTSIDE:$real" >&2; exit 3;; esac;; esac',
+    '}',
+].join("\n");
 /**
  * The record invocation for one path: line 1 is the no-follow kind (the
  * upstream lstat gate), line 2 the follow-stat fields (the upstream final
- * stat), tab-joined.
+ * stat), tab-joined. The path is resolved and contained first — the GUI's
+ * workspace is a boundary for every read, not just for listings.
  *
  * @param file - absolute Linux path.
+ * @param root - the workspace root in Linux form (containment boundary).
  * @returns the agent argv.
  */
-export function statRecordArgv(file) {
+export function statRecordArgv(file, root) {
     const script = [
-        'k=$(stat -c %F -- "$1") || exit 2',
-        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
+        CONTAIN_FN,
+        'contain "$1" "$2"',
+        'k=$(stat -c %F -- "$real") || exit 2',
+        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$real") || exit 2',
         "printf '%s\\t%s\\n' \"$k\" \"$s\"",
     ].join("\n");
-    return ["sh", "-c", script, "sh", file];
+    return ["sh", "-c", script, "sh", file, root];
 }
 /**
  * Parse one stat record (kind + follow fields, tab-joined).
@@ -115,16 +137,19 @@ export function wireKind(kind) {
  * @param file - absolute Linux path.
  * @param offset - first line to return (1-based).
  * @param limit - maximum lines to return.
+ * @param root - the workspace root in Linux form (containment boundary).
  * @returns the agent argv.
  */
-export function pageArgv(file, offset, limit) {
+export function pageArgv(file, offset, limit, root) {
     const script = [
-        'k=$(stat -c %F -- "$1") || exit 2',
-        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
+        CONTAIN_FN,
+        'contain "$1" "$4"',
+        'k=$(stat -c %F -- "$real") || exit 2',
+        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$real") || exit 2',
         "printf '%s\\t%s\\n' \"$k\" \"$s\" >&2",
-        'sed -n "${2},$(( $2 + $3 ))p" -- "$1"',
+        'sed -n "${2},$(( $2 + $3 ))p" -- "$real"',
     ].join("\n");
-    return ["sh", "-c", script, "sh", file, String(offset), String(limit)];
+    return ["sh", "-c", script, "sh", file, String(offset), String(limit), root];
 }
 /**
  * The byte-window invocation: the stat record rides stderr, the window rides
@@ -133,15 +158,18 @@ export function pageArgv(file, offset, limit) {
  * @param file - absolute Linux path.
  * @param offset - byte offset (0-based).
  * @param length - byte count.
+ * @param root - the workspace root in Linux form (containment boundary).
  * @returns the agent argv.
  */
-export function bytesArgv(file, offset, length) {
+export function bytesArgv(file, offset, length, root) {
     const script = [
-        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
+        CONTAIN_FN,
+        'contain "$1" "$4"',
+        's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$real") || exit 2',
         "printf '%s\\n' \"$s\" >&2",
-        'tail -c "+$(( $2 + 1 ))" -- "$1" | head -c "$3"',
+        'tail -c "+$(( $2 + 1 ))" -- "$real" | head -c "$3"',
     ].join("\n");
-    return ["sh", "-c", script, "sh", file, String(offset), String(length)];
+    return ["sh", "-c", script, "sh", file, String(offset), String(length), root];
 }
 /**
  * Parse the stat record a read or byte-window relayed on stderr.