dsh-plugin-wsl-env 0.7.5 → 0.9.0

package/lib/search-exec.js

@@ -23,92 +23,65 @@
  * Pure shaping over injected collaborators, so the handle semantics are
  * unit-testable without a distro.
  *
+ * This is a TypeScript source built to `lib/search-exec.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/search-exec
  */
-
 import { AgentUnavailableError } from "./agent-errors.js";
-
-/**
- * The output-stream reader the search tool consumes: `handle.collected.stdout`
- * / `stderr` expose `readFrom(offset)` with the seam's standard shape.
- *
- * @typedef {Object} SearchCollectedReader
- * @property {(from: number) => {text: string, lossy: boolean, nextOffset: number}} readFrom
- */
-
-/**
- * The slice of the subprocess handle the file-search tool consumes
- * (`dsh-tool-fs-search` `runRipgrep`): settle on `done`, then read the
- * collected streams. Nothing else of the handle is contract.
- *
- * @typedef {Object} SearchExecutionHandle
- * @property {Promise<{exitCode: number|null, signal: string|null}>} done
- * @property {{stdout: SearchCollectedReader, stderr: SearchCollectedReader}} collected
- * @property {() => boolean|void} [kill] - optional cooperative kill; the tool
- *   relies on its `signal` for cancellation instead.
- */
-
 /**
  * Run one search command through the agent and present it as a search handle.
  *
  * @param object - the handle's collaborators.
- * @param {object} object.agent - the {@link WslAgent}-like runner: `exec`
- *   accepting `{cwd, argv, maxOutputBytes, signal}` and resolving
- *   `{exitCode, stdout, stderr}`; throws `AgentUnavailableError` when out.
- * @param {string} object.cwd - the Linux working directory to search from.
- * @param {string[]} object.argv - the distro-side argv (`rg` and its arguments).
- * @param {number} [object.maxOutputBytes] - per-stream capture ceiling the
- *   agent enforces; the tool's own raw-output budget rides here.
- * @param {AbortSignal} [object.signal] - the caller's cancellation.
- * @param {() => object} object.spawnFallback - builds the one-shot handle the
- *   facade delegates to when the agent is out; called at most once, lazily.
- * @returns {object} the search handle (`done`, `collected`, `kill`).
+ * @returns the search handle (`done`, `collected`, `kill`).
  */
 export function searchExecutionHandle({ agent, cwd, argv, maxOutputBytes = 0, signal, spawnFallback }) {
-  const state = { delegate: undefined, stdout: undefined, stderr: undefined };
-  const controller = new AbortController();
-  if (signal?.aborted) controller.abort(signal.reason);
-  else signal?.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
-
-  const reader = (slot) => ({
-    readFrom(from) {
-      const buffer = state[slot] ?? Buffer.alloc(0);
-      const start = Math.min(from, buffer.length);
-      return { text: buffer.subarray(start).toString("utf8"), lossy: false, nextOffset: buffer.length };
-    },
-  });
-
-  /** @type {object} */
-  const handle = {
-    get collected() {
-      if (state.delegate !== undefined) return state.delegate.collected;
-      return { stdout: reader("stdout"), stderr: reader("stderr") };
-    },
-    done: (async () => {
-      let result;
-      try {
-        result = await agent.exec({ cwd, argv, maxOutputBytes, signal: controller.signal });
-        state.stdout = result.stdout;
-        state.stderr = result.stderr;
-      } catch (error) {
-        if (!(error instanceof AgentUnavailableError)) {
-          if (controller.signal.aborted) {
-            // Our kill() or the caller's cancellation: the killed outcome the
-            // one-shot path reports, not a failure.
-            return { exitCode: null, signal: "SIGTERM" };
-          }
-          throw error;
-        }
-        const delegate = spawnFallback();
-        state.delegate = delegate;
-        return delegate.done;
-      }
-      return { exitCode: result.exitCode, signal: null };
-    })(),
-    kill() {
-      controller.abort(new Error("killed"));
-      state.delegate?.kill?.();
-    },
-  };
-  return handle;
+    const state = { delegate: undefined, stdout: undefined, stderr: undefined };
+    const controller = new AbortController();
+    if (signal?.aborted)
+        controller.abort(signal.reason);
+    else
+        signal?.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+    const reader = (slot) => ({
+        readFrom(from) {
+            const buffer = state[slot] ?? Buffer.alloc(0);
+            const start = Math.min(from, buffer.length);
+            return { text: buffer.subarray(start).toString("utf8"), lossy: false, nextOffset: buffer.length };
+        },
+    });
+    const handle = {
+        get collected() {
+            if (state.delegate !== undefined)
+                return state.delegate.collected;
+            return { stdout: reader("stdout"), stderr: reader("stderr") };
+        },
+        done: (async () => {
+            let result;
+            try {
+                result = await agent.exec({ cwd, argv, maxOutputBytes, signal: controller.signal });
+                state.stdout = result.stdout;
+                state.stderr = result.stderr;
+            }
+            catch (error) {
+                if (!(error instanceof AgentUnavailableError)) {
+                    if (controller.signal.aborted) {
+                        // Our kill() or the caller's cancellation: the killed outcome the
+                        // one-shot path reports, not a failure.
+                        return { exitCode: null, signal: "SIGTERM" };
+                    }
+                    throw error;
+                }
+                const delegate = spawnFallback();
+                state.delegate = delegate;
+                return delegate.done;
+            }
+            return { exitCode: result.exitCode, signal: null };
+        })(),
+        kill() {
+            controller.abort(new Error("killed"));
+            state.delegate?.kill?.();
+        },
+    };
+    return handle;
 }

package/lib/search-route.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Which execution world a file-search spawn belongs to, and the `wsl.exe`
+ * argv it becomes there.
+ *
+ * `dsh-tool-fs-search` spawns the packaged ripgrep binary through
+ * `ctx.subprocess` with the session workspace as the working directory. Left
+ * alone, that spawn runs the Windows binary over the distro's 9p share — the
+ * one model-facing I/O path that still crossed the share, and in the slow
+ * direction: measured at ~17 ms per file of metadata round trips where the
+ * distro's own ext4 answers in microseconds. The interception point is the
+ * subprocess provider's `spawn`, and the decision lives here — pure,
+ * peer-free, and unit-testable, mirroring `terminal-route.js`.
+ *
+ * The rewrite is deliberately narrow. A spawn is intercepted only when the
+ * working directory NAMES the distro outright — a `\\wsl.localhost\<distro>`
+ * UNC — because that is the form a distro session's search carries and the
+ * only one that resolves without an async distro query: `spawn` hands back
+ * its handle synchronously, so the override must stay synchronous. A Windows
+ * drive directory keeps the host binary, which is native there and touches
+ * no share; anything else passes through untouched, exactly as before.
+ *
+ * The rewritten argv forwards every rg argument verbatim, so the tool reads
+ * the output format and exit codes of the distro's own rg. One addition is
+ * made: when the tool named no search path — its pattern rides `--regexp=`,
+ * and a bare `--` separator is exactly how it spells an explicit path — the
+ * rewrite appends `-- .`. Reason: `wsl.exe --exec` hands the distro-side rg a
+ * relay FIFO for stdin, and rg's readable-stdin heuristic then searches stdin
+ * (instantly empty) instead of walking the working directory; the packaged
+ * binary under the old path saw a non-readable NUL stdin and walked it. An
+ * explicit path makes the search deterministic on either transport.
+ *
+ * The distro-side binary must therefore exist — `scripts/bootstrap.sh` reports
+ * it — and a distro without one surfaces rg's own "command not found" instead
+ * of a silent fall-back to the share.
+ *
+ * This is a TypeScript source built to `lib/search-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/search-route
+ */
+/**
+ * Whether a spawn's program is the ripgrep binary.
+ *
+ * A bare `argv[0]` is judged by its own name, so the packaged binary's
+ * absolute path and any other spelling of `rg` match alike.
+ *
+ * @param program - the spawn's `argv[0]`.
+ * @returns true when the spawn is a ripgrep launch.
+ */
+export declare function isSearchProgram(program: unknown): boolean;
+/**
+ * The distro-side rewrite of one search spawn, when it belongs in the distro.
+ *
+ * Two argv forms come back for one decision. `rgArgv` is the distro command
+ * itself (`rg` and its arguments) — what the resident agent execs. `wslArgv`
+ * is the same command wrapped for a one-shot `wsl.exe --exec` launch — the
+ * fallback transport for when the agent is out. The working directory becomes
+ * the `--cd` the distro starts in; `wsl.exe` itself must start in a Windows
+ * directory, so the caller supplies its own host cwd when applying `wslArgv`.
+ *
+ * @param object - the spawn's inputs.
+ * @returns the rewrite, or undefined when the spawn is not a distro search and
+ *   must run exactly as the shipped implementation would run it.
+ */
+export declare function searchSpawnRewrite({ argv, cwd, wslPath }: {
+    argv: readonly string[];
+    cwd: string;
+    wslPath: string;
+}): {
+    distro: string;
+    linuxCwd: string;
+    rgArgv: string[];
+    wslArgv: string[];
+} | undefined;

package/lib/search-route.js

@@ -33,29 +33,30 @@
  * it — and a distro without one surfaces rg's own "command not found" instead
  * of a silent fall-back to the share.
  *
+ * This is a TypeScript source built to `lib/search-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/search-route
  */
-
 import { uncToPosix } from "./paths.js";
-
 /** The one program this rewrite passes through to the distro. */
 const SEARCH_PROGRAM = "rg";
-
 /**
  * Whether a spawn's program is the ripgrep binary.
  *
  * A bare `argv[0]` is judged by its own name, so the packaged binary's
  * absolute path and any other spelling of `rg` match alike.
  *
- * @param unknown - the spawn's `argv[0]`.
+ * @param program - the spawn's `argv[0]`.
  * @returns true when the spawn is a ripgrep launch.
  */
 export function isSearchProgram(program) {
-  if (typeof program !== "string" || program.length === 0) return false;
-  const base = program.slice(Math.max(program.lastIndexOf("/"), program.lastIndexOf("\\")) + 1);
-  return base.toLowerCase().replace(/\.exe$/u, "") === SEARCH_PROGRAM;
+    if (typeof program !== "string" || program.length === 0)
+        return false;
+    const base = program.slice(Math.max(program.lastIndexOf("/"), program.lastIndexOf("\\")) + 1);
+    return base.toLowerCase().replace(/\.exe$/u, "") === SEARCH_PROGRAM;
 }
-
 /**
  * The distro-side rewrite of one search spawn, when it belongs in the distro.
  *
@@ -67,29 +68,27 @@ export function isSearchProgram(program) {
  * directory, so the caller supplies its own host cwd when applying `wslArgv`.
  *
  * @param object - the spawn's inputs.
- * @param {unknown[]} object.argv - the spawn's argv; `argv[0]` is the program.
- * @param {unknown} object.cwd - the spawn's working directory, any coordinate system.
- * @param {string} object.wslPath - path to `wsl.exe`.
- * @returns {{distro: string, linuxCwd: string, rgArgv: string[], wslArgv: string[]}|undefined} the
- *   rewrite, or undefined when the spawn is not a distro search and must run
- *   exactly as the shipped implementation would run it.
+ * @returns the rewrite, or undefined when the spawn is not a distro search and
+ *   must run exactly as the shipped implementation would run it.
  */
 export function searchSpawnRewrite({ argv, cwd, wslPath }) {
-  if (!Array.isArray(argv) || !isSearchProgram(argv[0])) return undefined;
-  const named = uncToPosix(cwd);
-  if (named === undefined) return undefined;
-  const linuxCwd = named.linuxPath.length > 0 ? named.linuxPath : "/";
-  // No bare `--` means the tool named no search path; without one, distro-side
-  // rg reads the relay fifo on stdin (rg's readable-stdin heuristic) instead of
-  // walking the directory. `.` is the working directory — the same directory
-  // the packaged binary walked when the host spawned it directly.
-  const forwarded = argv.slice(1);
-  const tool = forwarded.includes("--") ? forwarded : [...forwarded, "--", "."];
-  const rgArgv = [SEARCH_PROGRAM, ...tool];
-  return {
-    distro: named.distro,
-    linuxCwd,
-    rgArgv,
-    wslArgv: [wslPath, "-d", named.distro, "--cd", linuxCwd, "--exec", ...rgArgv],
-  };
+    if (!Array.isArray(argv) || !isSearchProgram(argv[0]))
+        return undefined;
+    const named = uncToPosix(cwd);
+    if (named === undefined)
+        return undefined;
+    const linuxCwd = named.linuxPath.length > 0 ? named.linuxPath : "/";
+    // No bare `--` means the tool named no search path; without one, distro-side
+    // rg reads the relay fifo on stdin (rg's readable-stdin heuristic) instead of
+    // walking the directory. `.` is the working directory — the same directory
+    // the packaged binary walked when the host spawned it directly.
+    const forwarded = argv.slice(1);
+    const tool = forwarded.includes("--") ? forwarded : [...forwarded, "--", "."];
+    const rgArgv = [SEARCH_PROGRAM, ...tool];
+    return {
+        distro: named.distro,
+        linuxCwd,
+        rgArgv,
+        wslArgv: [wslPath, "-d", named.distro, "--cd", linuxCwd, "--exec", ...rgArgv],
+    };
 }

package/lib/shell-env.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Contribute the WSL environment's facts to the managed `DSH_*` namespace.
+ *
+ * `dsh-shell-env` owns `ctx.shellEnv`, the registry that rebuilds the trusted
+ * `DSH_*` variables injected into every model shell call. That is DSH's sanctioned
+ * channel for telling a model what its shell environment actually is — the shell
+ * tool's own description points the model at it ("Managed `$DSH_*` variables
+ * expose current harness environment facts").
+ *
+ * It has one built-in key that looks like it should carry this, and does not:
+ *
+ *     collect() { const values = { [DSH_HOME_ENV]: this.dshHome, [DSH_SHELL_KEY]: "1" } }
+ *
+ * `DSH_SHELL` is a marker FLAG (`=1`) meaning "a DSH-managed shell call", not the
+ * shell path, and it is in `RESERVED_BASH_ENV_KEYS`, so a contributor may not own
+ * it. The supported way to convey the real shell is a `DSH_`-prefixed key of our
+ * own, declared with a description and resolved synchronously.
+ *
+ * Scoping uses the same test as `auto-preset`: the agent's recorded workspace
+ * directory. A session whose workspace is inside a distro is exactly a session
+ * whose shell calls run in that distro — so a host session sees none of these.
+ *
+ * This is a TypeScript source built to `lib/shell-env.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/shell-env
+ */
+import z from "@deepseek-ai/schemastery";
+import type { Context } from "@deepseek-ai/cordis";
+export declare const name = "wsl-shell-env";
+export declare const inject: string[];
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    /** Distro these facts describe; empty means this machine's default distro. */
+    distro: z<string, string, "defined">;
+    /** How often the listening-port snapshot refreshes, in milliseconds. */
+    portsRefreshMs: z<number, number, "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    /** Distro these facts describe; empty means this machine's default distro. */
+    distro: z<string, string, "defined">;
+    /** How often the listening-port snapshot refreshes, in milliseconds. */
+    portsRefreshMs: z<number, number, "defined">;
+}>>, "plain">;
+/** The config schema's validated output. */
+export interface ShellEnvConfig {
+    /** Distro these facts describe; empty means this machine's default distro. */
+    distro?: string;
+    /** How often the listening-port snapshot refreshes, in milliseconds. */
+    portsRefreshMs?: number;
+}
+/**
+ * The execution slice the shell-env registry hands a contributor's `resolve`;
+ * the harness's execution object is structural here.
+ */
+export interface ShellEnvExecution {
+    /** The executing session's agent stub. */
+    agent?: {
+        session?: {
+            header?: {
+                cwd?: string | undefined;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}
+/**
+ * The cordis context extended with the `shellEnv` registry slice this plugin
+ * contributes through. The registry belongs to the harness and its
+ * declaration is not visible to this plugin, so it is spelled structurally on
+ * top of the framework's {@link Context}.
+ */
+export type ShellEnvContext = Context & {
+    shellEnv: {
+        register: (contributor: {
+            name: string;
+            variables: Record<string, {
+                description: string;
+            }>;
+            resolve: (execution: ShellEnvExecution | undefined) => Record<string, string>;
+        }) => () => void;
+    };
+};
+/**
+ * Contribute the WSL environment's facts to the shell-env registry.
+ *
+ * @param ctx - the cordis context.
+ * @param config - the schema-validated plugin config.
+ */
+export declare function apply(ctx: ShellEnvContext, config?: ShellEnvConfig): Promise<void>;

package/lib/shell-env.js

@@ -20,90 +20,94 @@
  * directory. A session whose workspace is inside a distro is exactly a session
  * whose shell calls run in that distro — so a host session sees none of these.
  *
+ * This is a TypeScript source built to `lib/shell-env.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/shell-env
  */
-
 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";
-
 export const name = "wsl-shell-env";
-
 export const inject = ["shellEnv"];
-
 export const Config = z.object({
-  /** Distro these facts describe; empty means this machine's default distro. */
-  distro: z.string().default(""),
-  /** How often the listening-port snapshot refreshes, in milliseconds. */
-  portsRefreshMs: z.number().default(10 * 1000),
+    /** Distro these facts describe; empty means this machine's default distro. */
+    distro: z.string().default(""),
+    /** How often the listening-port snapshot refreshes, in milliseconds. */
+    portsRefreshMs: z.number().default(10 * 1000),
 });
-
+/**
+ * Contribute the WSL environment's facts to the shell-env registry.
+ *
+ * @param ctx - the cordis context.
+ * @param config - the schema-validated plugin config.
+ */
 export async function apply(ctx, config = {}) {
-  // `resolve` is called synchronously by the registry (`Object.entries` of its
-  // result), so every fact has to be resolved up front, not per call.
-  const configured = config.distro ?? "";
-  const distro = configured.length > 0 ? configured : await defaultDistro();
-  // undefined when both probes failed (a cold distro): the fact is then
-  // simply absent, which beats presenting the "bash" placeholder as the
-  // distro's login shell for this process's lifetime.
-  const shell = await defaultShell(distro);
-  // The consumer is a shell running INSIDE the distro, so the fact is the POSIX
-  // path, not the host-side world path.
-  const home = await linuxHomePath(distro);
-
-  const variables = {
-    DSH_WSL_DISTRO: {
-      description: `Name of the WSL distro this workspace lives in (${distro}).`,
-    },
-    DSH_WSL_SHELL: {
-      description: `Absolute path of the login shell that model shell calls run in inside ${distro}. Commands are executed by this shell, not by bash.`,
-    },
-    DSH_WSL_HOME: {
-      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.`,
-    },
-  };
-
-  // The port snapshot refreshes on a timer and is served synchronously: the
-  // registry's resolve is sync by contract, so live reads are impossible —
-  // the timer bounds staleness instead (see lib/ports.js).
-  let ports = [];
-  const refreshPorts = async () => {
-    ports = await listeningPorts(sharedAgent(distro), 8000);
-  };
-  void refreshPorts();
-  const portsTimer = setInterval(() => void refreshPorts(), config.portsRefreshMs);
-  portsTimer.unref?.();
-
-  const dispose = ctx.shellEnv.register({
-    name: "dsh-plugin-wsl-env",
-    variables,
-    resolve: (execution) => {
-      const cwd = execution?.agent?.session?.header?.cwd;
-      if (!isWslUnc(cwd)) return {};
-      // The facts describe ONE distro. A workspace under another distro's UNC
-      // is not that distro — the shell refuses its commands outright (the
-      // cross-distro guard) — so the honest resolution is no facts at all,
-      // not another distro's home and shell presented as this session's.
-      if (isAnotherDistrosUnc(cwd, distro)) return {};
-      const facts = {
-        DSH_WSL_DISTRO: distro,
-        DSH_WSL_HOME: home,
-        DSH_WSL_PORTS: ports.join(","),
-      };
-      if (shell !== undefined) facts.DSH_WSL_SHELL = shell;
-      return facts;
-    },
-  });
-
-  // Disposing matters: a config hot-reload re-runs apply(), and the registry
-  // rejects a second contributor claiming the same keys.
-  ctx.effect(() => {
-    clearInterval(portsTimer);
-    dispose();
-  });
+    // `resolve` is called synchronously by the registry (`Object.entries` of its
+    // result), so every fact has to be resolved up front, not per call.
+    const configured = config.distro ?? "";
+    const distro = configured.length > 0 ? configured : await defaultDistro();
+    // undefined when both probes failed (a cold distro): the fact is then
+    // simply absent, which beats presenting the "bash" placeholder as the
+    // distro's login shell for this process's lifetime.
+    const shell = await defaultShell(distro);
+    // The consumer is a shell running INSIDE the distro, so the fact is the POSIX
+    // path, not the host-side world path.
+    const home = await linuxHomePath(distro);
+    const variables = {
+        DSH_WSL_DISTRO: {
+            description: `Name of the WSL distro this workspace lives in (${distro}).`,
+        },
+        DSH_WSL_SHELL: {
+            description: `Absolute path of the login shell that model shell calls run in inside ${distro}. Commands are executed by this shell, not by bash.`,
+        },
+        DSH_WSL_HOME: {
+            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.`,
+        },
+    };
+    // The port snapshot refreshes on a timer and is served synchronously: the
+    // registry's resolve is sync by contract, so live reads are impossible —
+    // the timer bounds staleness instead (see lib/ports.js).
+    let ports = [];
+    const refreshPorts = async () => {
+        ports = await listeningPorts(sharedAgent(distro), 8000);
+    };
+    void refreshPorts();
+    const portsTimer = setInterval(() => void refreshPorts(), config.portsRefreshMs);
+    portsTimer.unref?.();
+    const dispose = ctx.shellEnv.register({
+        name: "dsh-plugin-wsl-env",
+        variables,
+        resolve: (execution) => {
+            const cwd = execution?.agent?.session?.header?.cwd;
+            if (cwd === undefined || !isWslUnc(cwd))
+                return {};
+            // The facts describe ONE distro. A workspace under another distro's UNC
+            // is not that distro — the shell refuses its commands outright (the
+            // cross-distro guard) — so the honest resolution is no facts at all,
+            // not another distro's home and shell presented as this session's.
+            if (isAnotherDistrosUnc(cwd, distro))
+                return {};
+            const facts = {
+                DSH_WSL_DISTRO: distro,
+                DSH_WSL_HOME: home,
+                DSH_WSL_PORTS: ports.join(","),
+            };
+            if (shell !== undefined)
+                facts.DSH_WSL_SHELL = shell;
+            return facts;
+        },
+    });
+    // Disposing matters: a config hot-reload re-runs apply(), and the registry
+    // rejects a second contributor claiming the same keys.
+    ctx.effect(() => () => {
+        clearInterval(portsTimer);
+        dispose();
+    });
 }

package/lib/shell.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `ctx.shell` entrypoint — load as `dsh-plugin-wsl` in a profile patch.
+ *
+ * This is a TypeScript source built to `lib/shell.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/shell
+ */
+export { WslShellExecutor as default, WslShellExecutor } from "./index.js";

package/lib/shell.js

@@ -1,5 +1,10 @@
 /**
  * `ctx.shell` entrypoint — load as `dsh-plugin-wsl` in a profile patch.
+ *
+ * This is a TypeScript source built to `lib/shell.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/shell
  */
 export { WslShellExecutor as default, WslShellExecutor } from "./index.js";