dsh-plugin-wsl-env 0.9.0 → 0.11.0

package/lib/agent.js

@@ -40,10 +40,31 @@
 import { spawn } from "node:child_process";
 import { AgentUnavailableError, CwdError } from "./agent-errors.js";
 import { AGENT_NAME, MAX_FRAME_BYTES, PROTOCOL_VERSION, encodeExecFrame, encodeFsFrame, encodeKill, encodeSetEnv, parseAgentLine } from "./agent-protocol.js";
+/**
+ * A zeroed per-kind metrics record.
+ * @returns the record.
+ */
+function emptyRequestMetrics() {
+    return { requests: 0, queueMs: 0, queueMaxMs: 0, execMs: 0, execMaxMs: 0, failed: 0, cancelled: 0, rejected: 0 };
+}
+/**
+ * A zeroed metrics snapshot.
+ * @returns the snapshot.
+ */
+function emptyAgentMetrics() {
+    return { fs: emptyRequestMetrics(), exec: emptyRequestMetrics(), inFlightMax: 0 };
+}
 /** How long a rebuilt agent has to re-answer the handshake before giving up. */
 const HANDSHAKE_TIMEOUT_MS = 15000;
 /** Extra time the host watchdog waits past the request's own in-distro timeout. */
 const WATCHDOG_GRACE_MS = 13000;
+/**
+ * How many requests one resident may hold in flight before refusing more. The
+ * agent is serial, so a large queue only delays every entry; the cap keeps a
+ * burst from growing the pending map (and the retained frame lines) without
+ * bound.
+ */
+const MAX_PENDING_REQUESTS = 64;
 /** How far past its host's idle shutdown the agent's own lease runs. The
  * lease fires only when the host is gone in every way that matters (a wedged
  * relay that never delivers EOF); the host's close() normally wins the race. */
@@ -135,18 +156,26 @@ export class WslAgent {
         this.scriptPath = config.scriptPath;
         this.wslPath = config.wslPath ?? "wsl.exe";
         this.argvPrefix = config.argvPrefix ?? [];
+        this.signalable = config.signalable ?? this.argvPrefix.length === 0;
         this.idleMs = config.idleMs ?? 600000;
         this.expectedDigest = config.expectedDigest;
         this.frameCapBytes = config.frameCapBytes ?? MAX_FRAME_BYTES;
         this.configuredSpawn = config.spawnTransport;
+        this.configuredSignal = config.signalTransport;
+        this.configuredLease = config.leaseMs;
+        this.maxPending = config.maxPending ?? MAX_PENDING_REQUESTS;
+        this.agentPid = undefined;
         this.process = null;
         this.state = "idle";
         this.startPromise = null;
+        this.startSettler = null;
         this.nextRequestId = 0;
         this.pending = new Map();
         this.rebuildUsed = false;
         this.idleTimer = null;
         this.lastError = "";
+        this.requestMetrics = emptyAgentMetrics();
+        this.prepare = config.prepare;
     }
     /**
      * Whether the agent is permanently out — the executor's fallback cue.
@@ -174,8 +203,42 @@ export class WslAgent {
             return Promise.resolve();
         if (this.startPromise)
             return this.startPromise;
+        const prepared = this.prepare?.();
+        if (prepared === undefined) {
+            const started = this.beginStart();
+            this.startPromise = started;
+            return started;
+        }
+        const started = prepared.then((entry) => {
+            if (entry !== undefined)
+                this.applyPrepared(entry);
+            return this.beginStart();
+        });
+        this.startPromise = started;
+        return started;
+    }
+    /**
+     * Apply an async preparation entry to this agent before the first spawn.
+     *
+     * @param entry - the selected entry.
+     */
+    applyPrepared(entry) {
+        this.scriptPath = entry.scriptPath;
+        this.expectedDigest = entry.expectedDigest;
+        if (entry.signalable !== undefined)
+            this.signalable = entry.signalable;
+        if (entry.spawnTransport !== undefined)
+            this.configuredSpawn = entry.spawnTransport;
+    }
+    /**
+     * Spawn the process and run the handshake.
+     *
+     * @returns resolved once the state is `ready`.
+     */
+    beginStart() {
         this.state = "starting";
-        this.startPromise = new Promise((resolve, reject) => {
+        this.agentPid = undefined;
+        return new Promise((resolve, reject) => {
             // stdio is all-pipe (the spawn options above), so every standard stream
             // exists; the broad ChildProcess type models them as nullable.
             const child = (this.process = (this.configuredSpawn ?? spawnDefault)({
@@ -183,14 +246,21 @@ export class WslAgent {
                 distro: this.distro,
                 scriptPath: this.scriptPath,
                 argvPrefix: this.argvPrefix,
-                leaseMs: this.idleMs > 0 ? this.idleMs + LEASE_GRACE_MS : 0,
+                leaseMs: this.configuredLease ?? (this.idleMs > 0 ? this.idleMs + LEASE_GRACE_MS : 0),
             }));
+            // One generation, one owner: every closure below belongs to THIS child.
+            // A stale child's exit must not settle a newer start, null a newer
+            // transport, or answer a newer request.
+            const current = () => this.process === child;
             const handshakeTimer = setTimeout(() => {
+                if (!current())
+                    return;
                 this.lastError = `agent handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms`;
                 child.kill();
             }, HANDSHAKE_TIMEOUT_MS);
             const settleStart = (error) => {
                 clearTimeout(handshakeTimer);
+                this.startSettler = null;
                 this.startPromise = null;
                 if (error) {
                     this.state = this.rebuildUsed ? "dead" : "idle";
@@ -203,16 +273,30 @@ export class WslAgent {
                     resolve();
                 }
             };
+            this.startSettler = settleStart;
             child.on("error", (error) => {
+                if (!current())
+                    return;
                 this.lastError = String(error);
                 settleStart(error);
             });
+            // The write side can hit EPIPE after the child exits — a failed
+            // handshake followed by close(), or a scope stop. The failure is already
+            // reflected in the state/pending requests; an unhandled stream error
+            // would crash the host process instead.
+            child.stdin?.on("error", () => { });
             child.on("exit", (code, signalName) => {
+                if (!current()) {
+                    // A stale child's exit: release its pipes, but never touch the
+                    // generation that replaced it.
+                    this.teardownStreams(child);
+                    return;
+                }
                 if (this.state === "starting") {
                     this.lastError = `agent exited during handshake (code=${code} signal=${signalName ?? "none"})`;
                     settleStart(new Error(this.lastError));
                 }
-                this.handleProcessExit(code, signalName);
+                this.handleProcessExit(child, code, signalName);
             });
             // A bounded line splitter instead of readline: readline accumulates an
             // over-long line whole before anyone can object, which is exactly the
@@ -220,6 +304,8 @@ export class WslAgent {
             // (ids, numbers, base64), so chunk-boundary decoding is not a concern.
             let buffered = "";
             child.stdout.on("data", (chunk) => {
+                if (!current())
+                    return;
                 buffered += chunk.toString("utf8");
                 for (;;) {
                     const newline = buffered.indexOf("\n");
@@ -227,7 +313,7 @@ export class WslAgent {
                         if (buffered.length > this.frameCapBytes) {
                             this.lastError = `agent frame of ${buffered.length} bytes exceeded the ${this.frameCapBytes}-byte protocol cap`;
                             buffered = "";
-                            this.process?.kill();
+                            child.kill();
                         }
                         return;
                     }
@@ -236,18 +322,19 @@ export class WslAgent {
                     if (line.length > this.frameCapBytes) {
                         this.lastError = `agent frame of ${line.length} bytes exceeded the ${this.frameCapBytes}-byte protocol cap`;
                         buffered = "";
-                        this.process?.kill();
+                        child.kill();
                         return;
                     }
                     this.handleLine(line, settleStart, handshakeTimer);
                 }
             });
             child.stderr?.on("data", (chunk) => {
+                if (!current())
+                    return;
                 // Diagnostics only; `wsl.exe` and the shell chatter here on failure.
                 this.lastError = String(chunk).trim().slice(0, 2000) || this.lastError;
             });
         });
-        return this.startPromise;
     }
     /**
      * One stdout line from the agent. The first must be a matching HELLO.
@@ -274,12 +361,13 @@ export class WslAgent {
                     // deployed layout a /mnt/c mirror — so a digest that differs from
                     // the copy this package shipped means the runtime copy is stale,
                     // half-synced, or edited. Fail closed with the fix in the message.
-                    this.lastError = `agent script digest mismatch: the file the distro read at ${this.scriptPath} hashes to ${message.digest || "(nothing)"}, but this package shipped ${this.expectedDigest} — resync the runtime copy (npm run sync:windows) or reinstall the plugin`;
+                    this.lastError = `agent digest mismatch: the file the distro read at ${this.scriptPath} hashes to ${message.digest || "(nothing)"}, but this package shipped ${this.expectedDigest} — resync the runtime copy (npm run sync:windows) or reinstall the plugin`;
                     settleStart(new Error(this.lastError));
                     this.process?.kill();
                     return;
                 }
                 clearTimeout(handshakeTimer);
+                this.agentPid = message.pid;
                 settleStart();
                 break;
             }
@@ -287,9 +375,17 @@ export class WslAgent {
                 // Dequeue signal: start this request's own budget clock NOW. Armed
                 // here instead of at submission, a queued request can no longer time
                 // out on a queue it never chose to join — and its watchdog can never
-                // kill the shared transport for a stall that was never its own.
+                // kill the shared transport for a stall that was never its own. A
+                // request cancelled while it was queued is killed only now, when it is
+                // the one running.
                 const pending = this.pending.get(message.id);
-                pending?.armWatchdog?.();
+                if (pending) {
+                    pending.started = true;
+                    this.recordAck(pending);
+                    if (pending.cancelled)
+                        this.signalAgent("SIGUSR1");
+                    pending.armWatchdog?.();
+                }
                 break;
             }
             case "result": {
@@ -299,6 +395,10 @@ export class WslAgent {
                 this.clearPending(pending);
                 this.pending.delete(message.id);
                 this.rearmIdleTimer();
+                // A cancelled request keeps its entry only until this answer arrives.
+                if (pending.settled)
+                    break;
+                pending.settled = true;
                 pending.resolve({ exitCode: message.exitCode, stdout: message.stdout, stderr: message.stderr, truncated: message.truncated });
                 break;
             }
@@ -309,6 +409,9 @@ export class WslAgent {
                 this.clearPending(pending);
                 this.pending.delete(message.id);
                 this.rearmIdleTimer();
+                if (pending.settled)
+                    break;
+                pending.settled = true;
                 // A cwd rejection is the command's own failure, not the agent's — it
                 // becomes a CwdError so the execution layer can report it exactly like
                 // the one-shot path's relay text.
@@ -330,11 +433,16 @@ export class WslAgent {
      * The process died. Requests in flight ride exactly one rebuild; a second
      * death is permanent.
      *
+     * @param child - the process that exited.
      * @param code - the exit code, null when killed by a signal.
      * @param signalName - the killing signal, null on a normal exit.
      */
-    handleProcessExit(code, signalName) {
+    handleProcessExit(child, code, signalName) {
+        // The exit handler has already proved this child is the current generation;
+        // that check is the one place a stale exit can be rejected.
         this.process = null;
+        this.agentPid = undefined;
+        this.teardownStreams(child);
         if (this.pending.size === 0) {
             if (this.state !== "dead")
                 this.state = "idle";
@@ -371,6 +479,9 @@ export class WslAgent {
                 }
                 else {
                     this.clearPending(pending);
+                    if (pending.settled)
+                        continue;
+                    pending.settled = true;
                     pending.reject(new AgentUnavailableError(`agent exited while request ${pending.id} was in flight; its state is unknown — inspect the distro before retrying`));
                 }
             }
@@ -385,6 +496,9 @@ export class WslAgent {
                     if (!this.writeLines(relabelFrame(pending.lines, id))) {
                         this.clearPending(pending);
                         this.pending.delete(id);
+                        if (pending.settled)
+                            continue;
+                        pending.settled = true;
                         pending.reject(new AgentUnavailableError(`agent exited before request ${id} could be re-sent; its state is unknown`));
                     }
                 }
@@ -392,6 +506,9 @@ export class WslAgent {
                 .catch((error) => {
                 for (const pending of relayable) {
                     this.clearPending(pending);
+                    if (pending.settled)
+                        continue;
+                    pending.settled = true;
                     pending.reject(error);
                 }
                 this.state = "dead";
@@ -402,6 +519,9 @@ export class WslAgent {
         this.state = "dead";
         for (const pending of this.pending.values()) {
             this.clearPending(pending);
+            if (pending.settled)
+                continue;
+            pending.settled = true;
             pending.reject(new AgentUnavailableError(this.lastError));
         }
         this.pending.clear();
@@ -416,45 +536,78 @@ export class WslAgent {
      *
      * @param request - the request to register.
      */
-    track({ id, lines, resolve, reject, timeoutMs, signal }) {
+    track({ id, kind = "exec", lines, resolve, reject, timeoutMs, signal }) {
+        if (this.pending.size >= this.maxPending) {
+            this.noteRejected(kind);
+            reject(new Error(`the resident agent has ${this.pending.size} requests in flight (max ${this.maxPending}); retry when the queue drains`));
+            return;
+        }
         const pending = {
             id,
+            kind,
+            sentAt: performance.now(),
+            measured: false,
             lines,
-            resolve,
-            reject,
+            resolve: (result) => {
+                this.recordSettle(pending, undefined);
+                resolve(result);
+            },
+            reject: (error) => {
+                this.recordSettle(pending, error);
+                reject(error);
+            },
             watchdog: null,
             signal: signal ?? null,
             onAbort: null,
+            started: false,
+            cancelled: false,
+            settled: false,
             armWatchdog: timeoutMs > 0
                 ? () => {
                     if (pending.watchdog)
                         return;
+                    // Bind the watchdog to the generation it was armed on: a rebuild
+                    // must not let a stale timer kill the new transport.
+                    const child = this.process;
+                    if (!child)
+                        return;
                     // The in-distro timeout does the killing; this only catches an
                     // agent that accepted the request and then stopped answering
                     // even to its own timer.
                     pending.watchdog = setTimeout(() => {
+                        if (this.process !== child)
+                            return;
                         this.lastError = `agent did not answer request ${pending.id} within ${timeoutMs + WATCHDOG_GRACE_MS}ms of its dispatch`;
-                        this.process?.kill();
+                        child.kill();
                     }, timeoutMs + WATCHDOG_GRACE_MS);
                 }
                 : null,
         };
         this.pending.set(id, pending);
+        this.requestMetrics.inFlightMax = Math.max(this.requestMetrics.inFlightMax, this.pending.size);
         if (signal) {
             if (signal.aborted) {
                 this.pending.delete(id);
+                this.noteRejected(kind);
                 reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
                 return;
             }
             pending.onAbort = () => {
-                // Address by the entry's CURRENT id: a request relayed across a
-                // rebuild was re-registered under a fresh one, and a stale KILL (or a
-                // stale map delete) would strand the entry and leave the command
-                // running to its own timeout.
+                pending.cancelled = true;
+                // The frame is the fallback for an agent that cannot be signalled (a
+                // confined resident, a build without the USR1 trap); the signal is what
+                // interrupts the command the agent is blocked on right now.
                 this.writeLines([encodeKill(pending.id)]);
+                if (pending.started)
+                    this.signalAgent("SIGUSR1");
+                if (pending.settled)
+                    return;
+                pending.settled = true;
+                // Keep the entry until the agent answers: a request cancelled while it
+                // was QUEUED is killed when its ACK arrives, and its late RES only
+                // cleans the map.
                 this.clearPending(pending);
-                this.pending.delete(pending.id);
-                reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+                pending.reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
             };
             signal.addEventListener("abort", pending.onAbort, { once: true });
         }
@@ -465,6 +618,7 @@ export class WslAgent {
         if (!this.writeLines(lines)) {
             this.clearPending(pending);
             this.pending.delete(pending.id);
+            this.noteRejected(kind);
             reject(new AgentUnavailableError("the agent exited before the request could be sent; it never ran"));
             return;
         }
@@ -488,7 +642,7 @@ export class WslAgent {
             ...encodeExecFrame({ id, cwd, argv, timeoutMs, maxOutputBytes }),
         ];
         return new Promise((resolve, reject) => {
-            this.track({ id, lines, resolve, reject, timeoutMs, signal });
+            this.track({ id, kind: "exec", lines, resolve, reject, timeoutMs, signal });
         });
     }
     /**
@@ -510,7 +664,7 @@ export class WslAgent {
         const id = `r${this.nextRequestId++}`;
         const lines = encodeFsFrame({ id, op, args, timeoutMs });
         return new Promise((resolve, reject) => {
-            this.track({ id, lines, resolve, reject, timeoutMs, signal });
+            this.track({ id, kind: "fs", lines, resolve, reject, timeoutMs, signal });
         });
     }
     /**
@@ -528,9 +682,110 @@ export class WslAgent {
         return new Promise((resolve, reject) => {
             const id = `r${this.nextRequestId++}`;
             const lines = encodeExecFrame({ id, cwd: "/", argv: ["true"], timeoutMs: 0 });
-            this.track({ id, lines, resolve: () => resolve(), reject, timeoutMs: HANDSHAKE_TIMEOUT_MS, signal });
+            this.track({ id, kind: "exec", lines, resolve: () => resolve(), reject, timeoutMs: HANDSHAKE_TIMEOUT_MS, signal });
         });
     }
+    /**
+     * Deliver an out-of-band signal to the resident shell. The serial stdin loop
+     * cannot consume a frame while a command runs, so cancellation is a signal;
+     * a second `wsl.exe` is the only channel that reaches the agent while it is
+     * blocked in `wait`.
+     *
+     * Only an agent that shares the distro's PID namespace is addressable: the
+     * plain agent, or a session runtime (its prefix is a scope plus mounts, but
+     * no PID namespace). A confined resident runs inside a PID namespace whose
+     * PIDs do not exist in the distro, so signalling its HELLO PID could hit an
+     * unrelated process; there the KILL frame remains the (delayed) fallback.
+     *
+     * @param signal - the signal to deliver (`SIGUSR1` is the cancel trap).
+     */
+    /**
+     * The cumulative request metrics: queue wait (sent -> ACK) and execution
+     * time (ACK -> settle) per request kind, plus the peak in-flight count.
+     *
+     * @returns a snapshot the caller can keep.
+     */
+    metrics() {
+        return {
+            fs: { ...this.requestMetrics.fs },
+            exec: { ...this.requestMetrics.exec },
+            inFlightMax: this.requestMetrics.inFlightMax,
+        };
+    }
+    /** Reset the cumulative metrics (diagnostics/probes). */
+    resetMetrics() {
+        this.requestMetrics = emptyAgentMetrics();
+    }
+    /**
+     * The metric bucket for a request kind.
+     * @param kind - fs or exec.
+     * @returns the bucket.
+     */
+    kindMetrics(kind) {
+        return kind === "fs" ? this.requestMetrics.fs : this.requestMetrics.exec;
+    }
+    /**
+     * Record a request that never entered the pending map.
+     * @param kind - the bucket.
+     */
+    noteRejected(kind) {
+        this.kindMetrics(kind).rejected += 1;
+    }
+    /**
+     * Record the dequeue ACK: the request's queue wait.
+     * @param pending - the request.
+     */
+    recordAck(pending) {
+        if (pending.ackedAt !== undefined)
+            return;
+        const now = performance.now();
+        pending.ackedAt = now;
+        const stats = this.kindMetrics(pending.kind);
+        const wait = now - pending.sentAt;
+        stats.queueMs += wait;
+        stats.queueMaxMs = Math.max(stats.queueMaxMs, wait);
+    }
+    /**
+     * Record a settle: the requests count, the execution time (or the queue wait
+     * for a request that never ACKed), and the outcome.
+     * @param pending - the request.
+     * @param error - the failure, when any.
+     */
+    recordSettle(pending, error) {
+        if (pending.measured)
+            return;
+        pending.measured = true;
+        const now = performance.now();
+        const stats = this.kindMetrics(pending.kind);
+        stats.requests += 1;
+        if (pending.ackedAt !== undefined) {
+            const exec = now - pending.ackedAt;
+            stats.execMs += exec;
+            stats.execMaxMs = Math.max(stats.execMaxMs, exec);
+        }
+        else {
+            const wait = now - pending.sentAt;
+            stats.queueMs += wait;
+            stats.queueMaxMs = Math.max(stats.queueMaxMs, wait);
+        }
+        if (pending.cancelled)
+            stats.cancelled += 1;
+        else if (error !== undefined)
+            stats.failed += 1;
+    }
+    signalAgent(signal) {
+        const pid = this.agentPid;
+        if (pid === undefined || !this.signalable)
+            return;
+        if (this.configuredSignal) {
+            this.configuredSignal({ wslPath: this.wslPath, distro: this.distro, pid, signal });
+            return;
+        }
+        const distroArgs = this.distro.length > 0 ? ["-d", this.distro] : [];
+        const child = spawn(this.wslPath, [...distroArgs, "--exec", "sh", "-c", 'kill -s "$1" "$2" 2>/dev/null', "sh", signal.replace(/^SIG/, ""), String(pid)], { stdio: "ignore", windowsHide: true, env: pinnedWindowsEnv(process.env) });
+        // The agent may already be gone; the KILL frame remains the fallback.
+        child.on("error", () => { });
+    }
     /**
      * Shut the agent down: SHUTDOWN first, then kill after a short grace. The
      * agent becomes reusable — a later `exec` starts a fresh process.
@@ -544,8 +799,25 @@ export class WslAgent {
         const child = this.process;
         if (!child)
             return;
+        // A close during a start must settle that start: the handshake will never
+        // complete once the process is being shut down, and the caller would wait
+        // for it forever.
+        if (this.state === "starting")
+            this.startSettler?.(new AgentUnavailableError("the agent was closed during start"));
         this.state = "idle";
         this.process = null;
+        this.agentPid = undefined;
+        if (this.pending.size > 0) {
+            const reason = new AgentUnavailableError("the agent was closed before this request answered");
+            for (const pending of this.pending.values()) {
+                this.clearPending(pending);
+                if (pending.settled)
+                    continue;
+                pending.settled = true;
+                pending.reject(reason);
+            }
+            this.pending.clear();
+        }
         this.writeLinesSafe(child, ["SHUTDOWN"]);
         await new Promise((resolve) => {
             const timer = setTimeout(() => {
@@ -557,6 +829,22 @@ export class WslAgent {
                 resolve();
             });
         });
+        // The transport is always spawned with pipes, so the streams exist; the
+        // field's broader type is Node's, not the spawn's.
+        this.teardownStreams(child);
+    }
+    /**
+     * Release the host's ends of a dead child's stdio. A descendant that
+     * inherited a pipe's write end would otherwise keep the read side — and the
+     * fd — open until that descendant exits; the agent's own helpers are
+     * redirected at their spawn sites, but the host must not depend on it.
+     *
+     * @param child - the process whose streams are being released.
+     */
+    teardownStreams(child) {
+        child.stdin.destroy();
+        child.stdout.destroy();
+        child.stderr?.destroy();
     }
     /**
      * Write one frame to the live process.

package/lib/bwrap.d.ts

@@ -32,6 +32,14 @@ export interface BwrapProfileOptions {
      * ephemeral tmpfs over it.
      */
     realTmp?: boolean;
+    /**
+     * Create a PID namespace (`--unshare-pid`). Defaults to true: a COMMAND's
+     * background descendants die with it, which is the per-command shape. A
+     * session runtime sets this to false so a background dev server survives the
+     * command that started it — the systemd scope's cgroup, not the namespace,
+     * is then the cleanup boundary (ADR 0001).
+     */
+    pidNamespace?: boolean;
 }
 /**
  * Build the bwrap profile arguments for one file-effect policy, exactly as

package/lib/bwrap.js

@@ -59,7 +59,10 @@
  * @returns profile arguments, before the `--` separator and the command argv.
  */
 export function bwrapProfileArgs(policy, options = {}) {
-    const args = ["--ro-bind", "/", "/", "--dev", "/dev", "--unshare-pid", "--proc", "/proc", "--die-with-parent"];
+    const args = ["--ro-bind", "/", "/", "--dev", "/dev"];
+    if (options.pidNamespace !== false)
+        args.push("--unshare-pid");
+    args.push("--proc", "/proc", "--die-with-parent");
     if (policy.mode === "workspace-write") {
         if (options.realTmp) {
             args.push("--bind", "/tmp", "/tmp");

package/lib/fs-routing.d.ts

@@ -61,11 +61,16 @@ export interface RoutingConfig {
     watchMaxDepth?: number;
 }
 /**
- * Whether a resolved target identity belongs to the distro.
+ * 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 targetKey - the target's identity (a UNC for distro paths).
- * @returns true when the target lives inside a WSL distro.
+ * @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 declare function distroContains(parentKey: string, childKey: string): boolean;
 export declare function targetIsDistro(targetKey: string): boolean;
 /**
  * Whether a raw path-or-cwd input names the distro (used by the operations
@@ -83,8 +88,39 @@ export declare function inputIsDistro(value: string | undefined): boolean;
  * mode the distro side reports through `sandboxMode`).
  */
 export declare class WslRoutingFileSystem extends LocalFileSystem {
-    #private;
     static Config: import("@deepseek-ai/schemastery").default<import("@deepseek-ai/dsh-fs-local").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: string[];
+    /**
+     * 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.
+     */
+    private distroBackend;
+    /** The distro knobs, verbatim from the row config. */
+    private 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.
+     */
+    private routeContext;
     /**
      * @param ctx - the cordis context.
      * @param config - the row config, host knobs plus distro knobs.