dsh-plugin-wsl-env 0.5.0 → 0.7.2

package/lib/workspace-files-route.js

@@ -0,0 +1,205 @@
+/**
+ * Pure builders and parsers for the distro-routed `workspace-files` service —
+ * the GUI file tree and previews for a `\\wsl.localhost\<distro>` workspace,
+ * served from inside the distro instead of Windows-side 9P walks.
+ *
+ * Peer-free by construction (no DSH imports): the service subclass imports
+ * this alongside the shipped `dsh-api-workspace-files` base class, and the
+ * unit tests import it standalone.
+ *
+ * @module dsh-plugin-wsl/workspace-files-route
+ */
+
+import { isWslUnc, uncToPosix, windowsToLinuxMount } from "./paths.js";
+
+/**
+ * Translate one path-shaped value into distro coordinates: UNC identities map
+ * onto their Linux paths, drive-letter paths onto their `/mnt/<drive>` mounts,
+ * everything else passes through verbatim.
+ *
+ * @param value - the value to translate.
+ * @returns the distro-side spelling.
+ */
+export function distroPath(value) {
+  if (typeof value !== "string") return value;
+  if (isWslUnc(value)) {
+    const parsed = uncToPosix(value);
+    return parsed === undefined ? value : parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+  }
+  const mounted = windowsToLinuxMount(value);
+  return mounted === undefined ? value : mounted;
+}
+
+/**
+ * Whether a workspace root belongs to a distro (and therefore routes
+ * distro-side).
+ *
+ * @param workspaceRoot - the scope's workspace root, any coordinate system.
+ * @returns true for a `\\wsl.localhost\<distro>` UNC root.
+ */
+export function isDistroWorkspace(workspaceRoot) {
+  return isWslUnc(workspaceRoot);
+}
+
+/**
+ * The Linux working path for one request: UNC absolutes map onto their Linux
+ * paths, POSIX absolutes and relative paths join onto the root.
+ *
+ * @param linuxRoot - the workspace root in Linux form.
+ * @param path - the requested path, any coordinate system.
+ * @returns the absolute Linux path.
+ */
+export function linuxJoin(linuxRoot, path) {
+  // The UNC check runs on the RAW spelling: the backslash-to-slash rewrite
+  // below would leave `//wsl.localhost/...`, which the identity regex cannot
+  // see.
+  const parsed = uncToPosix(path);
+  if (parsed !== undefined) return parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+  const text = String(path).replaceAll("\\", "/");
+  if (text.startsWith("/")) return text.length > 1 ? text.replace(/\/+$/, "") : "/";
+  const base = linuxRoot === "/" ? "" : linuxRoot;
+  const joined = text.length === 0 ? base : `${base}/${text}`.replace(/\/\.(?=\/|$)/gu, "");
+  return joined.length === 0 ? "/" : joined;
+}
+
+/** The `stat` format string: kind, size, device, inode, mtimes — tab-joined. */
+const STAT_FORMAT = "%F\t%s\t%D\t%i\t%Y\t%Z";
+
+/**
+ * The record invocation for one path: line 1 is the no-follow kind (the
+ * upstream lstat gate), line 2 the follow-stat fields (the upstream final
+ * stat), tab-joined.
+ *
+ * @param file - absolute Linux path.
+ * @returns the agent argv.
+ */
+export function statRecordArgv(file) {
+  const script = [
+    'k=$(stat -c %F -- "$1") || exit 2',
+    's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
+    "printf '%s\\t%s\\n' \"$k\" \"$s\"",
+  ].join("\n");
+  return ["sh", "-c", script, "sh", file];
+}
+
+/**
+ * Parse one stat record (kind + follow fields, tab-joined).
+ *
+ * @param line - the record line.
+ * @returns the upstream kind spelling, the byte size, and the synthesized
+ *   opaque version.
+ */
+export function parseStatRecord(line) {
+  const [kind, size, dev, ino, mtime, ctime] = String(line).trim().split("\t");
+  return {
+    kind,
+    type: wireKind(kind),
+    size: Number(size),
+    version: `${dev}:${ino}:${size}:${mtime}:${ctime}`,
+  };
+}
+
+/**
+ * Map a `stat` kind onto the wire's kind token.
+ *
+ * @param kind - the `stat -c %F` spelling.
+ * @returns the wire kind token.
+ */
+export function wireKind(kind) {
+  const mapped = { "regular file": "file", directory: "directory", "symbolic link": "symlink" };
+  return mapped[kind] ?? kind;
+}
+
+/**
+ * The read invocation for one line-paged text read: the stat record rides
+ * stderr (the caller builds the stat half of the response), the page rides
+ * stdout — one line beyond the page, so EOF is decidable from the yield.
+ * `$1` is the file, `$2` the 1-based first line, `$3` the line count.
+ *
+ * @param file - absolute Linux path.
+ * @param offset - first line to return (1-based).
+ * @param limit - maximum lines to return.
+ * @returns the agent argv.
+ */
+export function pageArgv(file, offset, limit) {
+  const script = [
+    'k=$(stat -c %F -- "$1") || exit 2',
+    's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
+    "printf '%s\\t%s\\n' \"$k\" \"$s\" >&2",
+    'sed -n "${2},$(( $2 + $3 ))p" -- "$1"',
+  ].join("\n");
+  return ["sh", "-c", script, "sh", file, String(offset), String(limit)];
+}
+
+/**
+ * The byte-window invocation: the stat record rides stderr, the window rides
+ * stdout. `$1` is the file, `$2` the byte offset, `$3` the byte count.
+ *
+ * @param file - absolute Linux path.
+ * @param offset - byte offset (0-based).
+ * @param length - byte count.
+ * @returns the agent argv.
+ */
+export function bytesArgv(file, offset, length) {
+  const script = [
+    's=$(stat -L -c %s\\t%D\\t%i\\t%Y\\t%Z -- "$1") || exit 2',
+    "printf '%s\\n' \"$s\" >&2",
+    'tail -c "+$(( $2 + 1 ))" -- "$1" | head -c "$3"',
+  ].join("\n");
+  return ["sh", "-c", script, "sh", file, String(offset), String(length)];
+}
+
+/**
+ * Parse the stat record a read or byte-window relayed on stderr.
+ *
+ * @param stderr - the relay's raw stderr.
+ * @returns the parsed stat record, or undefined when stderr carries none.
+ */
+export function parseStatRecordFromStderr(stderr) {
+  const line = String(stderr)
+    .split("\n")
+    .find((candidate) => candidate.includes("\t"));
+  return line === undefined ? undefined : parseStatRecord(line);
+}
+
+/**
+ * The listing invocation for one directory: resolve the final component
+ * through symlinks, refuse paths outside the root and non-directories, then
+ * list one more entry than the cap so truncation is decidable from the yield.
+ * `-L` matches the upstream child semantics (a symlink to a directory lists
+ * as a directory, a broken link drops out); `-p` marks directories with the
+ * trailing `/` the parser keys on.
+ *
+ * @param linuxRoot - the workspace root in Linux form (containment boundary).
+ * @param linuxDir - the directory to list.
+ * @param maxEntries - the caller's entry cap.
+ * @returns the agent argv.
+ */
+export function listDistroArgv(linuxRoot, linuxDir, maxEntries) {
+  const script = [
+    "root=$1 dir=$2 max=$3",
+    'real=$(realpath -L -- "$dir") || exit 2',
+    'case "$real" in "$root") ;; "$root"/*) ;; *) echo "OUTSIDE:$real" >&2; exit 3;; esac',
+    '[ -d "$real" ] || { echo "NOTDIR:$real" >&2; exit 4; }',
+    'ls -1ALp -- "$real" | head -n "$max"',
+  ].join("\n");
+  return ["sh", "-c", script, "sh", linuxRoot, linuxDir, maxEntries + 1];
+}
+
+/**
+ * Parse one capped `ls -1ALp` listing into wire entries.
+ *
+ * @param stdout - the listing's raw stdout.
+ * @param maxEntries - the entry cap the caller configured.
+ * @returns at most `maxEntries` entries and whether the level had more.
+ */
+export function parseDirListing(stdout, maxEntries) {
+  const lines = String(stdout).split("\n").filter((line) => line.length > 0);
+  const truncated = lines.length > maxEntries;
+  const entries = lines.slice(0, maxEntries).map((line) => {
+    const directory = line.endsWith("/");
+    const name = directory ? line.slice(0, -1) : line;
+    return { name, type: directory ? "directory" : "file" };
+  });
+  return { entries, truncated };
+}

package/lib/workspace-files-wsl.js

@@ -0,0 +1,341 @@
+/**
+ * The distro-routed `workspace-files` service: the GUI file tree and previews
+ * for a `\\wsl.localhost\<distro>` workspace are served from inside the distro
+ * through the resident agent, instead of Windows-side 9P walks.
+ *
+ * ## Route predicate
+ *
+ * Every override checks `scope.workspaceRoot` — a distro UNC routes
+ * distro-side, a drive path calls `super` (host native, unchanged).
+ * `changes` (the watch stream) always delegates to `super`: its feed rides
+ * `ctx.fs.watch`, whose behaviour is today's on both workspace kinds.
+ *
+ * ## What the distro side reproduces
+ *
+ * The wire shapes of `dsh-api-workspace-files`: listings capped with a
+ * `truncated` flag, stats of `{absolutePath, version, bytes?}`, line-paged
+ * text with NUL and UTF-8 refusal and the byte-cap error, and byte windows
+ * with EOF markers. Versions are synthesized from `stat` fields — opaque to
+ * the client, which only compares them. `absolutePath` is synthesized in the
+ * UNC form so the GUI's path display stays what it was on the host fs. Read
+ * refuses a final-component symlink exactly like the upstream `locateFile`
+ * lstat gate does; `list` follows one (matching its own symlink-through
+ * rule).
+ *
+ * The distro operations are standalone functions over an injected runner, so
+ * they are unit-testable with a fake agent; the class methods are thin
+ * coordinate guards around them.
+ *
+ * @module dsh-plugin-wsl/workspace-files-wsl
+ */
+
+import { RemoteError } from "@deepseek-ai/dsh-typert-protocol";
+import { WorkspaceFiles } from "@deepseek-ai/dsh-api-workspace-files";
+import { isDistroWorkspace, linuxJoin, listDistroArgv, parseDirListing, parseStatRecord, parseStatRecordFromStderr, pageArgv, statRecordArgv, bytesArgv } from "./workspace-files-route.js";
+import { posixToUnc, uncToPosix } from "./paths.js";
+import { sharedAgent } from "./agent-shared.js";
+
+/** Throw the wire's not-found refusal. */
+function notFound(path) {
+  return new RemoteError("workspace-file/not-found", `no entry at "${path}"`, { path });
+}
+
+/** Throw the wire's outside-workspace refusal. */
+function outsideWorkspace(path) {
+  return new RemoteError("workspace-file/outside-workspace", `"${path}" is outside the workspace`, { path });
+}
+
+/** Throw the wire's not-directory refusal. */
+function notDirectory(path, kind) {
+  return new RemoteError("workspace-file/not-directory", `"${path}" is a ${kind}`, { path, kind });
+}
+
+/** Throw the wire's not-regular-file refusal. */
+function notRegularFile(path, kind) {
+  return new RemoteError("workspace-file/not-regular-file", `"${path}" is a ${kind}`, { path, kind });
+}
+
+/** Throw the wire's too-large refusal. */
+function tooLarge(path, limit) {
+  return new RemoteError("workspace-file/too-large", `"${path}" exceeds the ${limit} byte full-file cap`, { path, limit });
+}
+
+/** Throw the wire's not-text refusal. */
+function notText(path) {
+  return new RemoteError("workspace-file/not-text", `"${path}" is not UTF-8 text`, { path });
+}
+
+/**
+ * List one distro directory through the runner.
+ *
+ * The agent argv confines the directory under the workspace root, refuses
+ * non-directories, and emits one line per child — a trailing `/` marks a
+ * directory (symlinks resolve through, broken links drop out, matching the
+ * upstream child semantics).
+ *
+ * @param object - the listing's inputs.
+ * @param {object} object.runner - the agent-like runner (`exec`).
+ * @param {string} object.distro - the distro name.
+ * @param {string} object.linuxRoot - the workspace root in Linux form.
+ * @param {string} object.path - the requested directory, any coordinate system.
+ * @param {number} object.maxEntries - the entry cap.
+ * @param {AbortSignal} [object.signal] - caller cancellation.
+ * @returns {Promise<{path: string, entries: {name: string, type: string}[], truncated: boolean}>}
+ *   the listing, with `path` relative to the workspace root (empty for it).
+ */
+export async function distroList({ runner, distro, linuxRoot, path, maxEntries, signal }) {
+  const linuxDir = linuxJoin(linuxRoot, path);
+  const result = await runner.exec({
+    cwd: "/",
+    argv: listDistroArgv(linuxRoot, linuxDir, maxEntries),
+    maxOutputBytes: 4_000_000,
+    timeoutMs: 30_000,
+    signal,
+  });
+  if (result.exitCode === 3) throw outsideWorkspace(path);
+  if (result.exitCode === 4) throw notDirectory(path, "directory");
+  if (result.exitCode === 2) throw notFound(path);
+  if (result.exitCode !== 0) throw new Error(`listing "${linuxDir}" failed: ${String(result.stderr).trim() || `exit ${result.exitCode}`}`);
+  const { entries, truncated } = parseDirListing(result.stdout, maxEntries);
+  const relative = linuxDir === linuxRoot ? "" : linuxDir.slice(linuxRoot.length + 1);
+  return { path: relative, entries, truncated };
+}
+
+/**
+ * Stat one distro path through the runner.
+ *
+ * @param object - the stat's inputs.
+ * @param {object} object.runner - the agent-like runner (`exec`).
+ * @param {string} object.distro - the distro name.
+ * @param {string} object.linuxRoot - the workspace root in Linux form.
+ * @param {string} object.path - the requested path, any coordinate system.
+ * @param {string} object.distroWorkspaceRoot - the UNC workspace root, for the
+ *   absolutePath display form.
+ * @param {AbortSignal} [object.signal] - caller cancellation.
+ * @returns {Promise<{absolutePath: string, version: string, bytes?: number}>}
+ */
+export async function distroStat({ runner, distro, linuxRoot, path, distroWorkspaceRoot, signal }) {
+  const linuxFile = linuxJoin(linuxRoot, path);
+  const result = await runner.exec({
+    cwd: "/",
+    argv: statRecordArgv(linuxFile),
+    maxOutputBytes: 4096,
+    timeoutMs: 30_000,
+    signal,
+  });
+  if (result.exitCode !== 0) throw notFound(path);
+  const record = parseStatRecord(result.stdout);
+  const stat = { absolutePath: posixToUnc(distro, linuxFile), version: record.version };
+  return record.size === undefined || Number.isNaN(record.size) ? stat : { ...stat, bytes: record.size };
+}
+
+/**
+ * Read one line-paged UTF-8 window through the runner, mirroring the
+ * upstream `cutPage` semantics: a NUL byte marks the page binary, a page
+ * above the byte cap is refused (never shortened), and `eof` is false exactly
+ * when a character exists past the page.
+ *
+ * @param object - the read's inputs.
+ * @param {object} object.runner - the agent-like runner (`exec`).
+ * @param {string} object.distro - the distro name.
+ * @param {string} object.linuxRoot - the workspace root in Linux form.
+ * @param {string} object.path - the requested path, any coordinate system.
+ * @param {number} object.offset - first line to return (1-based).
+ * @param {number} object.limit - maximum lines to return.
+ * @param {number} object.maxBytes - the page's byte cap.
+ * @param {string} object.distroWorkspaceRoot - the UNC workspace root, for the
+ *   absolutePath display form.
+ * @param {AbortSignal} [object.signal] - caller cancellation.
+ * @returns {Promise<{absolutePath: string, version: string, bytes?: number, offset: number, text: string, lines: number, eof: boolean}>}
+ */
+export async function distroRead({ runner, distro, linuxRoot, path, offset, limit, maxBytes, distroWorkspaceRoot, signal }) {
+  const linuxFile = linuxJoin(linuxRoot, path);
+  const result = await runner.exec({
+    cwd: "/",
+    argv: pageArgv(linuxFile, offset, limit),
+    maxOutputBytes: (maxBytes + 1) * 4,
+    timeoutMs: 60_000,
+    signal,
+  });
+  if (result.exitCode === 2) throw notFound(path);
+  if (result.exitCode !== 0 && result.exitCode !== 1) {
+    throw new Error(`reading "${linuxFile}" failed: ${String(result.stderr).trim() || `exit ${result.exitCode}`}`);
+  }
+  const record = parseStatRecordFromStderr(result.stderr);
+  if (record === undefined) throw notFound(path);
+  if (record.type !== "file") throw notRegularFile(path, record.type);
+  const raw = Buffer.from(result.stdout);
+  const strict = new TextDecoder("utf-8", { fatal: true });
+  let text;
+  try {
+    text = strict.decode(raw);
+  } catch {
+    throw notText(path);
+  }
+  const lines = text.length === 0 ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+  const bytes = Buffer.byteLength(text, "utf8") + lines;
+  if (bytes > maxBytes) {
+    throw new RemoteError(
+      "workspace-file/too-large",
+      `lines ${offset}-${offset + limit - 1} of "${path}" exceed the ${maxBytes} byte cap`,
+      { path, limit: maxBytes },
+    );
+  }
+  if (text.includes(String.fromCharCode(0))) throw notText(path);
+  const eof = lines < limit;
+  const stat = { absolutePath: posixToUnc(distro, linuxFile), version: record.version };
+  return { ...stat, offset, text, lines, eof };
+}
+
+/**
+ * Read one byte window (or the capped whole file) through the runner.
+ *
+ * @param object - the read's inputs.
+ * @param {object} object.runner - the agent-like runner (`exec`).
+ * @param {string} object.distro - the distro name.
+ * @param {string} object.linuxRoot - the workspace root in Linux form.
+ * @param {string} object.path - the requested path, any coordinate system.
+ * @param {number|undefined} object.offset - byte offset (0-based).
+ * @param {number|undefined} object.length - byte count.
+ * @param {number} object.maxBytes - the window cap.
+ * @param {number} object.maxFileBytes - the complete-file cap.
+ * @param {string} object.distroWorkspaceRoot - the UNC workspace root, for the
+ *   absolutePath display form.
+ * @param {AbortSignal} [object.signal] - caller cancellation.
+ * @returns {Promise<{absolutePath: string, version: string, bytes?: number, offset: number, data: Uint8Array, eof: boolean}>}
+ */
+export async function distroReadBytes({ runner, distro, linuxRoot, path, offset, length, maxFileBytes, distroWorkspaceRoot, signal }) {
+  const linuxFile = linuxJoin(linuxRoot, path);
+  // One exec carries both halves: the stat record on stderr (for the version,
+  // the size, and the whole-file refusal), the window on stdout.
+  const window = offset === undefined && length === undefined
+    ? { offset: 0, length: maxFileBytes }
+    : { offset: offset ?? 0, length: length ?? maxFileBytes };
+  const result = await runner.exec({
+    cwd: "/",
+    argv: bytesArgv(linuxFile, window.offset, window.length),
+    maxOutputBytes: window.length + 1024,
+    timeoutMs: 60_000,
+    signal,
+  });
+  const record = parseStatRecordFromStderr(result.stderr);
+  if (record === undefined) throw notFound(path);
+  if (record.type !== "file") throw notRegularFile(path, record.type);
+  const data = new Uint8Array(Buffer.from(result.stdout).subarray(0, window.length));
+  // The whole-file form mirrors the upstream refusal: a file bigger than the
+  // cap is refused, never silently truncated (the stderr record names the
+  // real size even though head capped the stdout).
+  if (offset === undefined && length === undefined && record.size > maxFileBytes) {
+    throw tooLarge(path, maxFileBytes);
+  }
+  return {
+    absolutePath: posixToUnc(distro, linuxFile),
+    version: record.version,
+    offset: window.offset,
+    data,
+    eof: window.offset + data.length >= record.size,
+  };
+}
+
+/**
+ * The distro-routed `workspace-files` service.
+ */
+export class WorkspaceFilesWsl extends WorkspaceFiles {
+  static Config = WorkspaceFiles.Config;
+
+  /** The agent runner for one distro; a hook tests substitute. */
+  runnerFor(distro) {
+    return sharedAgent(distro);
+  }
+
+  /** The distro coordinates of one workspace scope. */
+  coords(workspaceRoot) {
+    const parsed = uncToPosix(workspaceRoot);
+    return { distro: parsed.distro, linuxRoot: parsed.linuxPath.length > 0 ? parsed.linuxPath : "/" };
+  }
+
+  async list(workspaceFileScope, path, signal) {
+    if (!isDistroWorkspace(workspaceFileScope.workspaceRoot)) return super.list(workspaceFileScope, path, signal);
+    const { distro, linuxRoot } = this.coords(workspaceFileScope.workspaceRoot);
+    const { path: relative, entries, truncated } = await distroList({
+      runner: this.runnerFor(distro),
+      distro,
+      linuxRoot,
+      path,
+      maxEntries: this.config.maxEntries,
+      signal,
+    });
+    return {
+      path: relative,
+      entries: entries.map((entry) => entry.size === undefined ? entry : { ...entry, size: entry.size }),
+      truncated,
+    };
+  }
+
+  async stat(workspaceFileScope, path, signal) {
+    if (!isDistroWorkspace(workspaceFileScope.workspaceRoot)) return super.stat(workspaceFileScope, path, signal);
+    const { distro, linuxRoot } = this.coords(workspaceFileScope.workspaceRoot);
+    return distroStat({ runner: this.runnerFor(distro), distro, linuxRoot, path, distroWorkspaceRoot: workspaceFileScope.workspaceRoot, signal });
+  }
+
+  async read(workspaceFileScope, path, range, signal) {
+    if (!isDistroWorkspace(workspaceFileScope.workspaceRoot)) return super.read(workspaceFileScope, path, range, signal);
+    const { distro, linuxRoot } = this.coords(workspaceFileScope.workspaceRoot);
+    const offset = range.offset === undefined ? 1 : range.offset;
+    const limit = range.limit === undefined ? this.config.maxLines : range.limit;
+    if (!Number.isSafeInteger(offset) || offset < 1) {
+      throw new RemoteError("gateway/bad-request", "offset must be a safe integer of at least 1", {});
+    }
+    if (limit > this.config.maxLines) {
+      throw new RemoteError("gateway/bad-request", `limit must be at most ${this.config.maxLines}`, {});
+    }
+    return distroRead({
+      runner: this.runnerFor(distro),
+      distro,
+      linuxRoot,
+      path,
+      offset,
+      limit,
+      maxBytes: this.config.maxBytes,
+      distroWorkspaceRoot: workspaceFileScope.workspaceRoot,
+      signal,
+    });
+  }
+
+  async readBytes(workspaceFileScope, path, options, signal) {
+    if (!isDistroWorkspace(workspaceFileScope.workspaceRoot)) return super.readBytes(workspaceFileScope, path, options, signal);
+    const { distro, linuxRoot } = this.coords(workspaceFileScope.workspaceRoot);
+    return distroReadBytes({
+      runner: this.runnerFor(distro),
+      distro,
+      linuxRoot,
+      path,
+      offset: options.range?.offset,
+      length: options.range?.length,
+      maxBytes: this.config.maxBytes,
+      maxFileBytes: this.config.maxFileBytes,
+      path,
+      distroWorkspaceRoot: workspaceFileScope.workspaceRoot,
+      signal,
+    });
+  }
+
+  async readByteRange(workspaceFileScope, path, offset, length, signal) {
+    if (!isDistroWorkspace(workspaceFileScope.workspaceRoot)) return super.readByteRange(workspaceFileScope, path, offset, length, signal);
+    const { distro, linuxRoot } = this.coords(workspaceFileScope.workspaceRoot);
+    return distroReadBytes({
+      runner: this.runnerFor(distro),
+      distro,
+      linuxRoot,
+      path,
+      offset,
+      length,
+      maxBytes: length,
+      maxFileBytes: Number.MAX_SAFE_INTEGER,
+      distroWorkspaceRoot: workspaceFileScope.workspaceRoot,
+      signal,
+    });
+  }
+}
+
+export default WorkspaceFilesWsl;

package/lib/wsl.js

@@ -15,6 +15,18 @@ import { posixToUnc } from "./paths.js";
 /** Default executable name; resolution is left to PATH. */
 export const DEFAULT_WSL_PATH = "wsl.exe";
 
+/**
+ * The deadline every `wsl.exe` call runs under, when the caller names none.
+ *
+ * A resolution call that never returns is worse than a failed one: `wsl.exe`
+ * talks to the vmcompute service, and a wedged service would hang the tool
+ * call forever — no timeout, no error, a silent dead session. Every call now
+ * dies loudly instead. The bound is deliberately generous (a cold distro boot
+ * on a slow disk is tens of seconds), and `0` disables it for a caller that
+ * genuinely wants to wait forever.
+ */
+export const DEFAULT_WSL_DEADLINE_MS = 60_000;
+
 /**
  * Run one host command and capture UTF-8 output.
  *
@@ -24,16 +36,18 @@ export const DEFAULT_WSL_PATH = "wsl.exe";
  *
  * @param argv - executable plus arguments, spawned without a shell.
  * @param signal - optional cancellation.
+ * @param deadlineMs - kill the call after this many milliseconds; the default
+ *   is {@link DEFAULT_WSL_DEADLINE_MS}, and `0` waits forever.
  * @returns captured stdout.
  * @throws the execFile error, with a hint attached when the cause is the sandbox.
  */
-export function runCapture(argv, signal) {
+export function runCapture(argv, signal, deadlineMs = DEFAULT_WSL_DEADLINE_MS) {
   const [file, ...args] = argv;
   return new Promise((resolve, reject) => {
     execFile(
       file,
       args,
-      { env: { ...process.env, WSL_UTF8: "1" }, windowsHide: true, signal, encoding: "utf8" },
+      { env: { ...process.env, WSL_UTF8: "1" }, windowsHide: true, signal, encoding: "utf8", timeout: deadlineMs },
       (error, stdout, stderr) => {
         if (error) {
           // A denied WSL call is the likeliest failure here and its own message
@@ -41,6 +55,10 @@ export function runCapture(argv, signal) {
           const detail = `${stdout ?? ""}${stderr ?? ""}`.replace(/\u0000/g, "").trim();
           const denied = /E_ACCESSDENIED/i.test(detail) || error.code === "EACCES";
           const missing = error.code === "ENOENT";
+          // The deadline kill arrives as a SIGTERM with no WSL diagnostic, so
+          // it must be named for what it is — not left looking like WSL's own
+          // failure. An abort is cancellation, not a deadline.
+          const stuck = error.killed === true && error.name !== "AbortError";
           error.message = `${file} failed: ${detail || error.message}${
             denied
               ? " (WSL is unreachable from a sandboxed process: DSH's Windows ACL sandbox runs commands under a restricted low-integrity token. Compose the non-sandboxing providers.)"
@@ -49,6 +67,10 @@ export function runCapture(argv, signal) {
             missing
               ? ` (the executable "${file}" could not be started: check \`wslPath\` in this row, and that WSL is installed)`
               : ""
+          }${
+            stuck
+              ? ` (no completion within ${deadlineMs}ms — the WSL service may be wedged; retry once, then \`wsl.exe --shutdown\` and reopen)`
+              : ""
           }`;
           reject(error);
           return;
@@ -136,45 +158,6 @@ export async function linuxHome(distro, options = {}) {
  * @returns the canonical absolute Linux path, or undefined when it cannot be
  *   determined (missing file, broken link, or a failed query).
  */
-export async function canonicalLinuxPath(distro, linuxPath, options = {}) {
-  try {
-    const stdout = await runCapture(
-      [options.wslPath ?? DEFAULT_WSL_PATH, "-d", distro, "--exec", "readlink", "-f", linuxPath],
-      options.signal,
-    );
-    const resolved = stdout.trim();
-    return resolved.startsWith("/") ? resolved : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Give `targetLinux` the same POSIX mode `sourceLinux` has, inside the distro.
- *
- * The UNC share does not carry POSIX modes to the host: a host-side `chmod` on a
- * share path is silently ignored, and a host-side `stat` reports 0666 no matter
- * what the distro sees. The distro itself has the real mode, so the mode has to
- * be applied there — and because a rename preserves the inode's mode, applying
- * it to a staged temp file *before* publication is enough for the published file
- * to come out with the right bits.
- *
- * `stat` + `chmod` rather than `chmod --reference` keeps this working on distros
- * whose chmod is busybox's.
- *
- * @param distro - distro name.
- * @param sourceLinux - absolute Linux path whose mode is copied.
- * @param targetLinux - absolute Linux path that receives the mode.
- * @param options - the `wsl.exe` path and optional cancellation.
- * @throws when the mode cannot be applied.
- */
-export async function copyModeInDistro(distro, sourceLinux, targetLinux, options = {}) {
-  const script = 'if [ -e "$1" ]; then mode=$(stat -c %a "$1") && chmod "$mode" "$2"; fi';
-  await runCapture(
-    [options.wslPath ?? DEFAULT_WSL_PATH, "-d", distro, "--exec", "sh", "-c", script, "sh", sourceLinux, targetLinux],
-    options.signal,
-  );
-}
 
 /**
  * Shells known to accept the combined POSIX `-lc` login-plus-command form.