dsh-plugin-wsl-env 0.6.0 → 0.7.2

package/lib/terminal-activity.js

@@ -0,0 +1,121 @@
+/**
+ * The distro-side activity observation for GUI distro terminals, and the
+ * handle wrapper that installs it.
+ *
+ * ## The gap this closes
+ *
+ * The terminal controller reclaims unattended terminals after
+ * `unattendedTimeoutMs` of observed idleness, but its observation is
+ * host-side: `dsh-subprocess-local`'s shell-activity integration is gated to
+ * interactive `bash`/`zsh` launched directly on a POSIX host, and a distro
+ * terminal is `wsl.exe` on win32. Every branch of the shipped
+ * `inspectActivity` therefore settles on `unknown` for these terminals, and
+ * `unknown` never accumulates idle — a distro terminal had to be closed by
+ * hand.
+ *
+ * ## The observation
+ *
+ * The terminal is MARKED at launch: a per-terminal `DSH_TERMINAL_ID` rides
+ * the `WSLENV` forwarding this provider already does, so the distro shell —
+ * and every process it spawns — carries it in `/proc/<pid>/environ`. The
+ * controller's 30 s retention poll then asks the resident agent to count the
+ * marked processes: exactly one (the shell alone, at its prompt) is IDLE;
+ * more than one (a command, a pipeline, a nested shell is running) is BUSY;
+ * none at all defers to the shipped handle (the shell has exited; its own
+ * exit bookkeeping is more precise than this scan). The agent being out
+ * yields `unknown` — the same never-reclaim posture as before, which is the
+ * safe direction: a probe that cannot answer must not authorize a close.
+ *
+ * Pure builders and a transparent proxy here; the agent wiring lives in the
+ * subprocess provider.
+ *
+ * @module dsh-plugin-wsl/terminal-activity
+ */
+
+/** The env name that marks one terminal's process tree inside the distro. */
+export const TERMINAL_ID_ENV = "DSH_TERMINAL_ID";
+
+/**
+ * The seam's activity observation — structurally the upstream
+ * `SubprocessTerminalActivity` (`subprocess-local/src/terminal.ts`): `state`
+ * is `'idle' | 'busy' | 'unknown'` and `revision` is a counter that changes
+ * when the reported state changes, which is what the controller's retention
+ * loop keys its idle accumulation on.
+ *
+ * @typedef {Object} SubprocessTerminalActivity
+ * @property {'idle' | 'busy' | 'unknown'} state
+ * @property {number} revision
+ */
+
+/**
+ * The probe: count the `/proc` processes carrying the terminal marker.
+ *
+ * POSIX sh on purpose (the distro's `sh` is the only guaranteed interpreter).
+ * The count is the whole decision: the terminal's login shell is exec'd WITH
+ * the marker (wsl.exe imports it into the session before `--exec`), so an
+ * idle-at-prompt shell is exactly one marked process, and anything the shell
+ * runs — a command, a pipeline, a nested shell — is exec'd with the marker
+ * inherited, pushing the count past one. `/proc/<pid>/environ` shows the
+ * exec-time environment, which is precisely why the count works: runtime
+ * exports would be invisible, and exec-time inheritance is the signal.
+ *
+ * The marker check reads the NUL-separated environ through `tr`, which is why
+ * the id is passed as `$1` rather than interpolated into the script.
+ *
+ * @param terminalId - the `DSH_TERMINAL_ID` value one terminal was launched with.
+ * @returns the agent `exec` target: the probe script with the id as `$1`.
+ */
+export function terminalActivityProbe(terminalId) {
+  const script = [
+    "id=$1",
+    "count=0",
+    'for d in /proc/[0-9]*; do',
+    '  [ -r "$d/environ" ] || continue',
+    '  if tr "\\000" "\\n" < "$d/environ" 2>/dev/null | grep -qx "DSH_TERMINAL_ID=$id"; then',
+    "    count=$((count+1))",
+    '    [ "$count" -gt 1 ] && { echo busy; exit 0; }',
+    "  fi",
+    "done",
+    "echo idle",
+  ].join("\n");
+  return { cwd: "/", argv: ["sh", "-c", script, "sh", terminalId] };
+}
+
+/**
+ * Parse the probe's stdout into an activity state.
+ *
+ * @param stdout - the probe's raw stdout.
+ * @returns `"busy"` or `"idle"` as the probe reported, or undefined when the
+ *   output is anything else (the caller answers `unknown`).
+ */
+export function parseTerminalActivity(stdout) {
+  const text = String(stdout).trim();
+  if (text === "busy" || text === "idle") return text;
+  return undefined;
+}
+
+/**
+ * Wrap a terminal handle so its activity is observed inside the distro.
+ *
+ * Everything except `inspectActivity` forwards to the wrapped handle
+ * transparently — methods stay bound to the real handle, so the controller's
+ * `write`/`resize`/`signalForeground`/stream access behave exactly as on the
+ * shipped object. `inspectActivity` is replaced wholesale: the shipped
+ * implementation can only answer `unknown` for a distro terminal, and the
+ * replacement answers from the marker scan (or `unknown` itself, when the
+ * probe cannot answer).
+ *
+ * @param handle - the handle `spawnTerminal` returned.
+ * @param inspectActivity - the replacement observation, matching the seam's
+ *   `() => Promise<SubprocessTerminalActivity>` shape.
+ * @returns the transparent proxy handle.
+ */
+export function wrapTerminalHandle(handle, inspectActivity) {
+  return new Proxy(handle, {
+    get(target, prop) {
+      if (prop === "inspectActivity") return inspectActivity;
+      const value = Reflect.get(target, prop);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}

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;