dsh-plugin-wsl-env 0.9.0 → 0.10.0

package/lib/agent.d.ts

@@ -73,6 +73,12 @@ export interface PendingRequest {
     onAbort: (() => void) | null;
     /** Arms `watchdog`; null when the request carries no timeout. */
     armWatchdog: (() => void) | null;
+    /** Whether the agent has ACKed this request (it is the running one). */
+    started: boolean;
+    /** The caller cancelled it; the entry stays until the agent answers. */
+    cancelled: boolean;
+    /** The caller was already settled; a late answer only cleans up. */
+    settled: boolean;
 }
 /**
  * The Windows environment the transport starts from, pinned.
@@ -134,13 +140,36 @@ export declare class WslAgent {
         distro: string;
         scriptPath: string;
         argvPrefix: string[];
+        leaseMs: number;
     }) => ChildProcess) | undefined;
+    /** The explicit lease, when the caller supplied one (independent of idleMs). */
+    configuredLease: number | undefined;
+    /** The injectable signal sender, when the caller supplied one. */
+    configuredSignal: ((options: {
+        wslPath: string;
+        distro: string;
+        pid: number;
+        signal: NodeJS.Signals;
+    }) => void) | undefined;
+    /** The agent shell's PID from its HELLO, when a second wsl.exe can address it. */
+    agentPid: number | undefined;
+    /**
+     * Whether a second `wsl.exe` can deliver `USR1` to the agent's HELLO pid.
+     * True for the plain agent; false for a resident inside a PID namespace. A
+     * session runtime has a prefix (scope + mounts) but no PID namespace, so it
+     * opts in explicitly.
+     */
+    signalable: boolean;
+    /** The maximum requests allowed in flight on this resident. */
+    maxPending: number;
     /** The live resident process, when any. */
     process: ChildProcess | null;
     /** The lifecycle state. */
     state: "idle" | "starting" | "ready" | "dead";
     /** The in-flight start, shared by concurrent callers. */
     startPromise: Promise<void> | null;
+    /** The in-flight start's settler, so close() can fail a start it interrupts. */
+    startSettler: ((error?: unknown) => void) | null;
     /** The next request id. */
     nextRequestId: number;
     /** The requests in flight, keyed by their current id. */
@@ -166,6 +195,13 @@ export declare class WslAgent {
         wslPath?: string;
         /** Idle shutdown delay; 0 disables. */
         idleMs?: number;
+        /**
+         * The client lease in ms, independent of `idleMs`. A session runtime holds
+         * the agent for the session's lifetime (no idle close) but still wants the
+         * lease's last-resort self-termination; a positive value here overrides the
+         * idle-derived lease.
+         */
+        leaseMs?: number;
         /**
          * The sha256 of the agent script as this package shipped it; a HELLO whose
          * digest differs is refused the same way a version mismatch is (the script
@@ -180,6 +216,13 @@ export declare class WslAgent {
          * Empty for the plain agent.
          */
         argvPrefix?: string[];
+        /**
+         * Whether a second `wsl.exe` can signal the agent's pid. Defaults to
+         * "true when the argv prefix is empty": the plain agent shares the distro's
+         * PID namespace, a confined resident does not, and a session runtime has a
+         * prefix but no PID namespace and must opt in.
+         */
+        signalable?: boolean;
         /** Hard ceiling in bytes on one stdout protocol line; defaults to {@link MAX_FRAME_BYTES}. */
         frameCapBytes?: number;
         /** Injectable process factory for tests. */
@@ -188,7 +231,23 @@ export declare class WslAgent {
             distro: string;
             scriptPath: string;
             argvPrefix: string[];
+            leaseMs: number;
         }) => ChildProcess;
+        /**
+         * Injectable out-of-band signal delivery for tests. The real path spawns a
+         * second `wsl.exe` to send USR1 to the agent's PID.
+         */
+        signalTransport?: (options: {
+            wslPath: string;
+            distro: string;
+            pid: number;
+            signal: NodeJS.Signals;
+        }) => void;
+        /**
+         * Maximum requests in flight on one resident; a submission past it is
+         * refused instead of growing the request map without bound.
+         */
+        maxPending?: number;
     });
     /**
      * Whether the agent is permanently out — the executor's fallback cue.
@@ -217,6 +276,7 @@ export declare 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.
      */
@@ -310,6 +370,21 @@ export declare class WslAgent {
      * @returns resolved on PONG.
      */
     ping(signal?: AbortSignal): Promise<void>;
+    /**
+     * 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).
+     */
+    private signalAgent;
     /**
      * Shut the agent down: SHUTDOWN first, then kill after a short grace. The
      * agent becomes reusable — a later `exec` starts a fresh process.
@@ -317,6 +392,15 @@ export declare class WslAgent {
      * @returns resolved once the process is gone.
      */
     close(): Promise<void>;
+    /**
+     * 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.
+     */
+    private teardownStreams;
     /**
      * Write one frame to the live process.
      *

package/lib/agent.js

@@ -44,6 +44,13 @@ import { AGENT_NAME, MAX_FRAME_BYTES, PROTOCOL_VERSION, encodeExecFrame, encodeF
 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,13 +142,19 @@ 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;
@@ -175,6 +188,7 @@ export class WslAgent {
         if (this.startPromise)
             return this.startPromise;
         this.state = "starting";
+        this.agentPid = undefined;
         this.startPromise = 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.
@@ -183,14 +197,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 +224,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 +255,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 +264,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,13 +273,15 @@ 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;
             });
@@ -274,12 +313,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 +327,16 @@ 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;
+                    if (pending.cancelled)
+                        this.signalAgent("SIGUSR1");
+                    pending.armWatchdog?.();
+                }
                 break;
             }
             case "result": {
@@ -299,6 +346,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 +360,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 +384,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 +430,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 +447,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 +457,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 +470,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();
@@ -417,6 +488,10 @@ export class WslAgent {
      * @param request - the request to register.
      */
     track({ id, lines, resolve, reject, timeoutMs, signal }) {
+        if (this.pending.size >= this.maxPending) {
+            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,
             lines,
@@ -425,16 +500,26 @@ export class WslAgent {
             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,
@@ -447,14 +532,21 @@ export class WslAgent {
                 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 });
         }
@@ -531,6 +623,33 @@ export class WslAgent {
             this.track({ id, 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).
+     */
+    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 +663,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 +693,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.