dsh-plugin-wsl-env 0.11.0 → 0.13.0

package/lib/agent.js

@@ -10,11 +10,13 @@
  *    command or a write that was in flight has UNKNOWN state — replaying it
  *    would run non-idempotent work twice or report a create that actually
  *    succeeded as a refusal — so it fails instead, and the caller re-reads
- *    before retrying. A second failure marks the agent permanently dead and
- *    every future call rejects with {@link AgentUnavailableError} — the
- *    executor's cue to fall back to the one-shot `wsl.exe` path it shipped
- *    with, so the worst case of the agent is "today's behaviour, plus one
- *    failed round trip".
+ *    before retrying. A failure that spends the rebuild leaves the agent
+ *    `dead` with a bounded revival: the next call after a 2/4/8-second backoff
+ *    gets a fresh transport and its own single rebuild; after three deaths the
+ *    state is permanent and every call rejects with a restart remedy. While
+ *    dead, calls reject with {@link AgentUnavailableError} — the executor's cue
+ *    to fall back to the one-shot `wsl.exe` path it shipped with, so the worst
+ *    case of the agent is "today's behaviour, plus one failed round trip".
  * 2. **The in-distro timeout is the real one.** The EXEC frame carries the
  *    timeout in whole seconds and the agent SIGTERMs the child itself, so a
  *    timed-out command dies where it lives instead of leaving an orphan
@@ -38,7 +40,7 @@
  * @module dsh-plugin-wsl/agent
  */
 import { spawn } from "node:child_process";
-import { AgentUnavailableError, CwdError } from "./agent-errors.js";
+import { AgentUnavailableError, BASH_TIMEOUT_REASON, CwdError, SpawnError } 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.
@@ -58,6 +60,19 @@ function emptyAgentMetrics() {
 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 times a resident that reached `dead` may be revived before the
+ * failure becomes permanent. Each revival gets the one permitted rebuild.
+ */
+const MAX_REVIVALS = 3;
+/** The first revival delay; doubles per death, capped at 30 s. */
+const DEFAULT_REVIVAL_BACKOFF_MS = 2000;
+/**
+ * How long a cancel waits before the out-of-band USR1. Long enough for the
+ * agent's own timeout kill to answer, short enough that a killed command still
+ * dies promptly.
+ */
+const CANCEL_SIGNAL_GRACE_MS = 60;
 /**
  * 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
@@ -171,7 +186,11 @@ export class WslAgent {
         this.startSettler = null;
         this.nextRequestId = 0;
         this.pending = new Map();
+        this.lastAckedSeq = 0;
         this.rebuildUsed = false;
+        this.deaths = 0;
+        this.deadUntil = 0;
+        this.revivalBackoffMs = config.revivalBackoffMs ?? DEFAULT_REVIVAL_BACKOFF_MS;
         this.idleTimer = null;
         this.lastError = "";
         this.requestMetrics = emptyAgentMetrics();
@@ -189,6 +208,42 @@ export class WslAgent {
     get unavailableReason() {
         return this.lastError;
     }
+    /**
+     * Enter the dead state and schedule the next bounded revival attempt.
+     *
+     * The delay doubles per death (2 s, 4 s, 8 s, … capped at 30 s). After
+     * {@link MAX_REVIVALS} deaths the state stays permanent and the refusal
+     * carries the restart remedy.
+     */
+    markDead() {
+        this.deaths += 1;
+        this.state = "dead";
+        const delay = Math.min(this.revivalBackoffMs * 2 ** Math.max(0, this.deaths - 1), 30_000);
+        this.deadUntil = this.deaths > MAX_REVIVALS ? 0 : Date.now() + delay;
+        if (this.deaths > MAX_REVIVALS) {
+            this.lastError = `${this.lastError}; permanently out after ${this.deaths} deaths — restart the DSH app`;
+        }
+        else {
+            this.lastError = `${this.lastError}; reviving in ${Math.round(delay / 1000)}s (attempt ${this.deaths}/${MAX_REVIVALS})`;
+        }
+    }
+    /**
+     * A read-only lifecycle snapshot for diagnostics. Includes the live pid, the
+     * last failure and the remaining revival budget; it never starts or stops
+     * anything.
+     *
+     * @returns the status snapshot.
+     */
+    status() {
+        return {
+            distro: this.distro,
+            state: this.state,
+            pid: this.agentPid,
+            lastError: this.lastError,
+            deaths: this.deaths,
+            pending: this.pending.size,
+        };
+    }
     /**
      * Start the process and wait for the handshake. Re-entrant: concurrent
      * callers share the one start.
@@ -197,7 +252,19 @@ export class WslAgent {
      */
     start() {
         if (this.state === "dead") {
-            return Promise.reject(new AgentUnavailableError(this.lastError));
+            if (this.deaths > MAX_REVIVALS) {
+                return Promise.reject(new AgentUnavailableError(`agent is permanently out after ${this.deaths} deaths (${this.lastError}); restart the DSH app, and delete ~/.cache/dsh-wsl/agent inside the distro if a stale binary is suspected`));
+            }
+            const wait = this.deadUntil - Date.now();
+            if (wait > 0) {
+                return Promise.reject(new AgentUnavailableError(`agent is down (${this.lastError}); reviving in ${Math.ceil(wait / 1000)}s, attempt ${this.deaths}/${MAX_REVIVALS}`));
+            }
+            // Bounded revival: the next call gets a fresh transport and its own
+            // single rebuild. Frames from the dead generation were settled in
+            // handleProcessExit; nothing is replayed here.
+            this.state = "idle";
+            this.rebuildUsed = false;
+            this.deadUntil = 0;
         }
         if (this.state === "ready")
             return Promise.resolve();
@@ -381,9 +448,10 @@ export class WslAgent {
                 const pending = this.pending.get(message.id);
                 if (pending) {
                     pending.started = true;
+                    this.lastAckedSeq = pending.seq;
                     this.recordAck(pending);
                     if (pending.cancelled)
-                        this.signalAgent("SIGUSR1");
+                        this.armCancelSignal(pending);
                     pending.armWatchdog?.();
                 }
                 break;
@@ -392,6 +460,7 @@ export class WslAgent {
                 const pending = this.pending.get(message.id);
                 if (!pending)
                     break; // answered after its caller gave up — noise
+                pending.answered = true;
                 this.clearPending(pending);
                 this.pending.delete(message.id);
                 this.rearmIdleTimer();
@@ -406,6 +475,7 @@ export class WslAgent {
                 const pending = this.pending.get(message.id);
                 if (!pending)
                     break;
+                pending.answered = true;
                 this.clearPending(pending);
                 this.pending.delete(message.id);
                 this.rearmIdleTimer();
@@ -414,10 +484,16 @@ export class WslAgent {
                 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.
+                // the one-shot path's relay text. A `spawn` rejection is the same
+                // class of failure on the native agent (it cannot distinguish a
+                // missing workdir), so it gets its own class and the executor retries
+                // it one-shot.
                 if (message.reason === "cwd") {
                     pending.reject(new CwdError(message.message));
                 }
+                else if (message.reason === "spawn") {
+                    pending.reject(new SpawnError(message.message));
+                }
                 else {
                     pending.reject(new AgentUnavailableError(`agent rejected request ${message.id} (${message.reason}): ${message.message}`));
                 }
@@ -511,12 +587,12 @@ export class WslAgent {
                     pending.settled = true;
                     pending.reject(error);
                 }
-                this.state = "dead";
+                this.markDead();
             });
             return;
         }
-        this.lastError = `agent exited again (code=${code} signal=${signalName ?? "none"}); falling back permanently`;
-        this.state = "dead";
+        this.lastError = `agent exited again (code=${code} signal=${signalName ?? "none"})`;
+        this.markDead();
         for (const pending of this.pending.values()) {
             this.clearPending(pending);
             if (pending.settled)
@@ -544,6 +620,7 @@ export class WslAgent {
         }
         const pending = {
             id,
+            seq: Number(id.slice(1)),
             kind,
             sentAt: performance.now(),
             measured: false,
@@ -562,6 +639,8 @@ export class WslAgent {
             started: false,
             cancelled: false,
             settled: false,
+            answered: false,
+            signalTimer: null,
             armWatchdog: timeoutMs > 0
                 ? () => {
                     if (pending.watchdog)
@@ -598,8 +677,6 @@ export class WslAgent {
                 // 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;
@@ -608,6 +685,15 @@ export class WslAgent {
                 // cleans the map.
                 this.clearPending(pending);
                 pending.reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+                // Arm AFTER clearPending: the clear releases the per-request timers,
+                // and the signal is the one timer that must outlive this rejection.
+                // A host timeout is excluded: the distro-side watcher already kills
+                // that command, and a USR1 delivered after it settled would hit the
+                // request that took its place (observed as an exit-138 "completed").
+                const reason = pending.signal?.reason;
+                const timedOut = reason instanceof Error && reason.message === BASH_TIMEOUT_REASON;
+                if (pending.started && !timedOut)
+                    this.armCancelSignal(pending);
             };
             signal.addEventListener("abort", pending.onAbort, { once: true });
         }
@@ -632,9 +718,6 @@ export class WslAgent {
      * @throws {AgentUnavailableError} when the agent is out for this process.
      */
     async exec({ cwd, argv, timeoutMs = 0, maxOutputBytes = 0, env, signal }) {
-        if (this.state === "dead") {
-            throw new AgentUnavailableError(this.lastError);
-        }
         await this.start();
         const id = `r${this.nextRequestId++}`;
         const lines = [
@@ -657,9 +740,6 @@ export class WslAgent {
      * @throws {AgentUnavailableError} when the agent is out for this process.
      */
     async fs({ op, args, timeoutMs = 0, signal }) {
-        if (this.state === "dead") {
-            throw new AgentUnavailableError(this.lastError);
-        }
         await this.start();
         const id = `r${this.nextRequestId++}`;
         const lines = encodeFsFrame({ id, op, args, timeoutMs });
@@ -674,8 +754,6 @@ export class WslAgent {
      * @returns resolved on PONG.
      */
     async ping(signal) {
-        if (this.state === "dead")
-            throw new AgentUnavailableError(this.lastError);
         await this.start();
         if (signal?.aborted)
             throw signal.reason instanceof Error ? signal.reason : new Error("aborted");
@@ -899,9 +977,38 @@ export class WslAgent {
     clearPending(pending) {
         if (pending.watchdog)
             clearTimeout(pending.watchdog);
+        if (pending.signalTimer)
+            clearTimeout(pending.signalTimer);
+        pending.signalTimer = null;
         if (pending.signal && pending.onAbort)
             pending.signal.removeEventListener("abort", pending.onAbort);
     }
+    /**
+     * Deliver the out-of-band cancel signal after a short grace, and only while
+     * the request it was meant for is still the agent's current one.
+     *
+     * The signal has no request id: it interrupts whatever command the agent is
+     * blocked in. A timeout request is usually already being killed by the
+     * in-distro watcher, so an immediate signal can land after the agent moved
+     * on — the next request then dies with exit 138 (SIGUSR1) and looks
+     * `completed`. A newer ACK means the agent has answered the old request, so
+     * the signal is dropped; an answered request is dropped too.
+     *
+     * @param pending - the cancelled request.
+     */
+    armCancelSignal(pending) {
+        if (pending.signalTimer !== null)
+            return;
+        pending.signalTimer = setTimeout(() => {
+            pending.signalTimer = null;
+            if (pending.answered || this.pending.get(pending.id) !== pending)
+                return;
+            if (this.lastAckedSeq > pending.seq)
+                return;
+            this.signalAgent("SIGUSR1");
+        }, CANCEL_SIGNAL_GRACE_MS);
+        pending.signalTimer.unref?.();
+    }
 }
 /** The read-only FS ops: replaying them across a rebuild changes nothing. */
 const REPLAYABLE_FS_OPS = new Set(["stat", "lstat", "list", "realpath", "read"]);

package/lib/distro-route.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Which distro an operation belongs to.
+ *
+ * The pinned name has three spellings: an explicit distro wins, `"default"`
+ * forces WSL's own default, and the empty string or `"auto"` follows the
+ * workspace coordinate when the caller has one. The workspace coordinate is a
+ * `\\wsl.localhost\<distro>\...` path; a Linux, drive-letter or relative path
+ * carries no distro evidence and falls back to WSL's default.
+ *
+ * Pure by construction: the caller resolves the default distro once and the
+ * selection stays unit-testable without `wsl.exe`.
+ *
+ * This is a TypeScript source built to `lib/distro-route.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/distro-route
+ */
+/** Why a distro was selected, for diagnostics and for the docs. */
+export type DistroSource = "pinned" | "workspace" | "default";
+/** One distro selection. */
+export interface DistroChoice {
+    /** The distro name to use. */
+    distro: string;
+    /** Whether the name came from the config, the path, or WSL's default. */
+    source: DistroSource;
+}
+/**
+ * The distro a UNC path names.
+ *
+ * @param value - any path spelling.
+ * @returns the distro name, or undefined for a non-WSL path.
+ */
+export declare function distroOfUnc(value: string | undefined): string | undefined;
+/**
+ * The explicit `distro` config value, or undefined for `""`, `"auto"` and
+ * `"default"`.
+ *
+ * @param configured - the row's `distro` value.
+ * @returns the pinned distro, or undefined when the value is a mode.
+ */
+export declare function pinnedDistro(configured: string | undefined): string | undefined;
+/**
+ * Whether `distro: ""`/`"auto"` asks the workspace coordinate to decide.
+ *
+ * @param configured - the row's `distro` value.
+ * @returns true for the automatic modes.
+ */
+export declare function isAutoDistro(configured: string | undefined): boolean;
+/**
+ * Whether `distro: "default"` forces WSL's own default.
+ *
+ * @param configured - the row's `distro` value.
+ * @returns true for the explicit default mode.
+ */
+export declare function isDefaultDistro(configured: string | undefined): boolean;
+/**
+ * Select the distro for one operation.
+ *
+ * Order: an explicit distro wins; `"default"` takes the fallback; otherwise the
+ * first candidate that names a UNC distro wins, and the fallback closes the
+ * list. The candidate order matters — a request's workdir is stronger evidence
+ * than the configured default cwd.
+ *
+ * @param input - the configured value, the path candidates, and WSL's default.
+ * @returns the distro and why it was chosen.
+ */
+export declare function selectDistro({ configured, candidates, fallback }: {
+    /** The row's `distro` value. */
+    configured: string | undefined;
+    /** Paths in any coordinate system, strongest evidence first. */
+    candidates: ReadonlyArray<string | undefined>;
+    /** WSL's default distro, already resolved by the caller. */
+    fallback: string;
+}): DistroChoice;

package/lib/distro-route.js

@@ -0,0 +1,86 @@
+/**
+ * Which distro an operation belongs to.
+ *
+ * The pinned name has three spellings: an explicit distro wins, `"default"`
+ * forces WSL's own default, and the empty string or `"auto"` follows the
+ * workspace coordinate when the caller has one. The workspace coordinate is a
+ * `\\wsl.localhost\<distro>\...` path; a Linux, drive-letter or relative path
+ * carries no distro evidence and falls back to WSL's default.
+ *
+ * Pure by construction: the caller resolves the default distro once and the
+ * selection stays unit-testable without `wsl.exe`.
+ *
+ * This is a TypeScript source built to `lib/distro-route.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/distro-route
+ */
+import { uncToPosix } from "./paths.js";
+/**
+ * The distro a UNC path names.
+ *
+ * @param value - any path spelling.
+ * @returns the distro name, or undefined for a non-WSL path.
+ */
+export function distroOfUnc(value) {
+    const text = String(value ?? "").trim();
+    return text.length === 0 ? undefined : uncToPosix(text)?.distro;
+}
+/**
+ * The explicit `distro` config value, or undefined for `""`, `"auto"` and
+ * `"default"`.
+ *
+ * @param configured - the row's `distro` value.
+ * @returns the pinned distro, or undefined when the value is a mode.
+ */
+export function pinnedDistro(configured) {
+    const text = String(configured ?? "").trim();
+    if (text.length === 0)
+        return undefined;
+    const mode = text.toLowerCase();
+    return mode === "auto" || mode === "default" ? undefined : text;
+}
+/**
+ * Whether `distro: ""`/`"auto"` asks the workspace coordinate to decide.
+ *
+ * @param configured - the row's `distro` value.
+ * @returns true for the automatic modes.
+ */
+export function isAutoDistro(configured) {
+    const text = String(configured ?? "").trim().toLowerCase();
+    return text.length === 0 || text === "auto";
+}
+/**
+ * Whether `distro: "default"` forces WSL's own default.
+ *
+ * @param configured - the row's `distro` value.
+ * @returns true for the explicit default mode.
+ */
+export function isDefaultDistro(configured) {
+    return String(configured ?? "").trim().toLowerCase() === "default";
+}
+/**
+ * Select the distro for one operation.
+ *
+ * Order: an explicit distro wins; `"default"` takes the fallback; otherwise the
+ * first candidate that names a UNC distro wins, and the fallback closes the
+ * list. The candidate order matters — a request's workdir is stronger evidence
+ * than the configured default cwd.
+ *
+ * @param input - the configured value, the path candidates, and WSL's default.
+ * @returns the distro and why it was chosen.
+ */
+export function selectDistro({ configured, candidates, fallback }) {
+    const pinned = pinnedDistro(configured);
+    if (pinned !== undefined)
+        return { distro: pinned, source: "pinned" };
+    if (isDefaultDistro(configured))
+        return { distro: fallback, source: "default" };
+    for (const candidate of candidates) {
+        const named = distroOfUnc(candidate);
+        if (named !== undefined)
+            return { distro: named, source: "workspace" };
+    }
+    return { distro: fallback, source: "default" };
+}

package/lib/fs-routing.d.ts

@@ -45,7 +45,10 @@ export interface RoutingConfig {
     cwd?: string;
     /** The host backend's overwrite-diff byte bound. */
     diffBasisMaxBytes?: number;
-    /** The pinned distro for routed targets; empty resolves WSL's default. */
+    /**
+     * The distro mode for routed targets: empty/`"auto"` follows each target's
+     * UNC distro, `"default"` forces WSL's default, and an explicit name pins.
+     */
     distro?: string;
     /** The `wsl.exe` path, used only to resolve the default distro. */
     wslPath?: string;