dsh-plugin-wsl-env 0.6.0 → 0.7.2

package/docs/README.zh.md

@@ -57,18 +57,18 @@ dsh --profile wsl                                  # 4. 启动
 | `wsl-fs` | `distro` | `''` | 同上 |
 | | `restrictToDistro` | `true` | 拒绝指向**其它子系统**共享的路径；`/mnt/c` 属于本子系统内部，不受影响。拒绝码为 `FS_OUTSIDE_DISTRO`，它不是沙箱拒绝，放宽权限也无法解除 |
 | | `sandbox` | `true` | 写入时按策略检查 `writeText` 和 `editText` |
-| | `substrate` | `agent` | 文件工具使用哪种 I/O 基座：`agent` —— 常驻子系统内代理，读写与路径解析直接在 ext4 上完成（原生符号链接、原生权限位，写入 guard 存活到发布时刻，受限策略下由内核强制）；`share` —— 退出项：Windows 侧宿主文件栈走 9p 共享。两种基座使用同一策略围栏；差异详见 [LIMITATIONS.md](LIMITATIONS.md) |
+| | `substrate` | `agent` | 文件工具使用哪种 I/O 基座。只剩常驻子系统内代理一种：读写与路径解析直接在 ext4 上完成（原生符号链接、原生权限位，写入 guard 存活到发布时刻，受限策略下由内核强制）。原 `"share"` 退出项——Windows 侧宿主文件栈走 9p 共享——已在启动时拒绝，文件工具不再经过共享 |
 | `directory-picker-wsl` | `includeHostHome` | `true` | 同时列出 Windows 家目录 |
 | `subprocess-wsl` | `distro` | `''` | GUI 终端开在哪个子系统 |
 
-[`cordis.patch.yml`](../cordis.patch.yml) 是每个随包值的注释参考。[docs/CONFIGURATION.md](CONFIGURATION.md) 列出其余键，包括 `shell`、`loginShell`、`cwd`、`timeoutMs`、`resolveSymlinks`、`preferredDistro` 和 `maxEntries`；[examples/profile.cordis.patch.yml](../examples/profile.cordis.patch.yml) 是一份可照抄的本机层。
+[`cordis.patch.yml`](../cordis.patch.yml) 是每个随包值的注释参考。[docs/CONFIGURATION.md](CONFIGURATION.md) 列出其余键，包括 `shell`、`loginShell`、`cwd`、`timeoutMs`、`preferredDistro` 和 `maxEntries`；[examples/profile.cordis.patch.yml](../examples/profile.cordis.patch.yml) 是一份可照抄的本机层。
 
 ## 配方
 
 - **Git 凭据共享**：让子系统里的 git 使用 Windows 侧的 Git Credential Manager，避免每次输密码：
   `git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"`
   （路径按 Windows 侧 Git 的安装位置调整；WSL2 的 localhost 转发是平台行为，子系统内监听的端口 Windows 直接可达。）
-- **路径与性能**：模型看到并操作的是子系统内的 Linux 路径（`/home/...`），写入子系统自身的 ext4；`/mnt/c` 通向 Windows 磁盘但走 9p，大批量小文件操作明显慢——重 IO 的项目请放在子系统文件系统内。`npm run bootstrap -- <子系统>` 会一并报告 ripgrep / inotifywait（搜索与监视的后端）是否就位。
+- **路径与性能**：模型看到并操作的是子系统内的 Linux 路径（`/home/...`），写入子系统自身的 ext4；`/mnt/c` 通向 Windows 磁盘但走 9p，大批量小文件操作明显慢——重 IO 的项目请放在子系统文件系统内。`npm run bootstrap -- <子系统>` 会一并报告 ripgrep、git、inotifywait（搜索、快照与监视的后端）是否就位。
 - **WSLENV 透传**：WSL 只导入 `WSLENV` 中列出的变量。本插件按前缀放行托管的 `DSH_*` 命名空间，其中带 Windows 路径的两个（`DSH_HOME`、`DSH_PROFILE_DIR`）加 `/p` 让 WSL 翻译成 `/mnt/c/...`。`PATH` 故意不透传——否则 Windows 的 PATH 会覆盖子系统自身的 PATH。
 
 ## 架构
@@ -86,12 +86,12 @@ dsh --profile wsl                                  # 4. 启动
 
 preset-wsl（wsl agent preset；其服务运行在 isolate realm 内）
 ├─ wsl-shell   ctx.shell — wsl.exe --exec <登录 shell>，在子系统内经 bubblewrap 约束
-└─ wsl-fs      ctx.fs    — 子系统的真实文件；agent 基座落在 ext4，或走 9p 共享
+└─ wsl-fs      ctx.fs    — 子系统的真实文件；常驻代理基座落在 ext4
 ```
 
 **为什么分两层。** `wsl-shell` 和 `wsl-fs` 位于 `wsl` agent preset 内，`auto-preset` 在会话工作区位于子系统内时自动绑定它：Windows 目录的会话继续使用原生 provider，子系统会话拿到 WSL provider——环境是会话的属性，而不是进程的。终端控制器是例外：它经根上下文解析执行世界，永远看不到 preset 的 isolate realm，所以 `subprocess-wsl` 必须挂在组合层。
 
-**命令与文件。** 命令以 `wsl.exe -d <子系统> --cd <Linux 目录> --exec <登录 shell> -lc <命令>` 执行，外层是子系统内的 bubblewrap profile，参数与 DSH 自家 Linux runner 完全一致——约束语义与报错文案都和 Linux 主机相同。文件工具读写子系统的真实文件，基座二选一：默认 `agent`——常驻子系统内的进程，读写与路径解析落在 ext4，原生符号链接与权限位；或 `share`——退出项：Windows 侧宿主文件栈走 9p 共享。两个基座与命令沙箱使用同一份策略检查写入。
+**命令与文件。** 命令以 `wsl.exe -d <子系统> --cd <Linux 目录> --exec <登录 shell> -lc <命令>` 执行，外层是子系统内的 bubblewrap profile，参数与 DSH 自家 Linux runner 完全一致——约束语义与报错文案都和 Linux 主机相同。文件工具读写子系统的真实文件，基座只有常驻子系统内代理一种——读写与路径解析落在 ext4，原生符号链接与权限位；文件搜索的 spawn 以同样的方式改写：子系统工作区的搜索跑子系统自己的 `rg`（`wsl.exe --exec`），绝不让 Windows 侧二进制走 9p 共享。写入与命令沙箱使用同一份策略检查。
 
 ## 沙箱
 
@@ -120,8 +120,8 @@ preset-wsl（wsl agent preset；其服务运行在 isolate realm 内）
 | 终端打开后仍然是 `cmd.exe` | 这一层里的 `terminal-controller` 行没有生效 | 用 `dsh --profile wsl --dump-config` 确认能看到 `shell: { path: wsl.exe, name: WSL }` |
 | 改了 `lib/` 但不生效 | ES module 缓存 | 重启应用 |
 | 用 `link:\\wsl.localhost\...` 安装后符号链接是坏的 | pnpm 无法链接 UNC 路径 | 改成链接 Windows 路径；在子系统内开发时用运行时镜像，见[开发](#开发) |
-| `glob`/`grep` 很慢 | Windows 侧的 ripgrep 在 9p 共享上遍历 | 属于预期，收窄搜索路径，或改用 `bash` 调用子系统内的工具 |
-| 终端活动显示 `unknown` | 官方 shell 集成只对 POSIX 主机上直接启动的 `bash`/`zsh` 生效 | 关闭标签页以释放进程；空闲回收不会对它触发 |
+| `glob`/`grep` 很慢 | 子系统内没有 rg 时，搜索只能报 rg 自己的 "command not found"；Windows 目录的搜索走宿主原生 rg，不受影响 | 运行 `npm run bootstrap -- <子系统> --install`（安装 ripgrep）；子系统工作区的搜索始终跑子系统内的 rg，绝不遍历 9p 共享 |
+| 终端活动显示 `unknown` | 仅在常驻代理不可用时出现——distro 终端从子系统内部观测（`/proc` 中扫描 `DSH_TERMINAL_ID` 标记：shell 独处为 `idle`，运行任何命令为 `busy`） | 确认子系统在运行；空闲终端会在控制器的无人值守超时（默认 2 小时）后自动回收，`terminalIdleReclaim: false` 恢复手动关闭 |
 | 结果里出现 `FS_*` 码 | 码本身说明了是谁拒绝的、以及怎样解除 | 见 [docs/ARCHITECTURE.md](ARCHITECTURE.md#error-codes) 的错误码表 |
 
 ## 开发

package/lib/fs-decisions.js

@@ -79,37 +79,33 @@ export function workspaceWriteDenial(displayPath) {
 }
 
 /**
- * The write/edit guard: compare the intent (`expected`) with what is on disk
- * NOW (`existing`, a stat row or `undefined`) and refuse the stale or
- * unobserved intent. The peer's dialect, byte for byte.
- * @param {object|undefined} expected - the write intent (`replaceIfVersion`
- *   with a `version`, or `createIfAbsent`), or `undefined` for an unguarded write.
- * @param {{version: string}|undefined} existing - what stat found, or undefined.
- * @param {string} displayPath - the caller-facing path for the message.
- * @returns {{message: string, code: string}|null} the refusal, or null to proceed.
+ * The substrate configuration decision: the Windows-side share no longer
+ * serves the file tools. Every distro read and write runs on the resident
+ * agent, so no model-facing I/O crosses the 9p share at all — the share
+ * backend it replaces was the one path that still could. The provider throws
+ * this at construction time, before any session forms, so a profile carrying
+ * the old value fails loudly with the migration instead of silently serving
+ * I/O the configuration did not mean to allow.
+ * @param {string} substrate - the configured substrate value.
+ * @returns {{message: string}|null} the refusal, or null to proceed.
  */
-export function guardRefusal(expected, existing, displayPath) {
-  if (expected === undefined) return null;
-  if (expected.kind === "replaceIfVersion") {
-    if (existing === undefined) return refusal(`cannot write "${displayPath}": file no longer exists`, "FS_STALE_VERSION");
-    if (existing.version !== expected.version) {
-      return refusal(`cannot write "${displayPath}": file changed since it was read`, "FS_STALE_VERSION");
-    }
-    return null;
-  }
-  if (expected.kind === "createIfAbsent" && existing !== undefined) {
-    return refusal(`cannot overwrite existing "${displayPath}" without reading it first`, "FS_NOT_OBSERVED");
-  }
-  return null;
+export function shareSubstrateRefusal(substrate) {
+  if (substrate !== "share") return null;
+  return {
+    message:
+      'wsl-fs: substrate "share" is no longer available — the resident agent serves every ' +
+      "distro read and write, and no file tool crosses the 9p share. Delete the substrate " +
+      'line from the provider config, or set it to "agent".',
+  };
 }
 
 /**
  * The substrate failure mapping: what the tool layer should surface for an
  * error that crossed the `ctx.fs` seam. A coded refusal keeps its code and
  * message byte-for-byte; anything else is the substrate being UNAVAILABLE —
- * the share backend's "distro is gone" case wearing the agent substrate's
- * wording — and the message names the documented opt-out, so an operator hit
- * by the fail-closed posture can reach the old behaviour without a doc trip.
+ * the resident agent that serves every distro read and write is out — and the
+ * message names the recovery path, because there is no fallback I/O for it to
+ * point at.
  * @param {unknown} error - what the substrate raised.
  * @returns {{message: string, code: string, cause: unknown}} the refusal the
  *   provider wraps in `FsError`.
@@ -120,7 +116,8 @@ export function substrateFailure(error) {
   return {
     message:
       `the distro file substrate is unavailable: ${message}. ` +
-      `Set "substrate: \\"share\\"" in the provider config to work on the Windows-side share while the agent is out.`,
+      `The resident agent serves every distro read and write; check the distro is running ` +
+      `("wsl.exe -l -v") and restart the session if it stays out.`,
     code: "FS_IO_ERROR",
     cause: error instanceof Error ? error : undefined,
   };

package/lib/fs-routing.js

@@ -0,0 +1,176 @@
+/**
+ * The root-plane filesystem with coordinate routing: targets under a
+ * `\\wsl.localhost\<distro>` identity are served by the distro substrate
+ * (the resident agent, on ext4); every other target — drive-letter paths,
+ * the deployment cwd — is served by the host `LocalFileSystem` this class
+ * extends, unchanged.
+ *
+ * ## Why a router, and why here
+ *
+ * The root `ctx.fs` is session-less: it cannot be switched per session the
+ * way a preset's isolated `fs` can, so the two workspace kinds share one
+ * backend — and the stock backend serves the distro workspace across the 9p
+ * share, in its slow direction, with no usable change notifications. Routing
+ * by coordinate makes every root consumer (the workspace-files change feed
+ * among them) correct on both workspace kinds without per-consumer patches.
+ *
+ * The design note is `docs/root-fs-routing.md` (the operation routing table,
+ * the intended behavior differences, and the dormant-root-fence rationale).
+ *
+ * ## What is intentionally not here
+ *
+ * No write fence: the root plane has no write consumers (the model's writes
+ * ride the per-session preset filesystems, which enforce their own
+ * containment — the distro side kernel-enforced). If a root-plane write
+ * consumer appears, its fence rides with that consumer.
+ *
+ * @module dsh-plugin-wsl/fs-routing
+ */
+
+import { isWslUnc, uncToPosix, windowsToLinuxMount } from "./paths.js";
+import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
+import { linuxJoin } from "./workspace-files-route.js";
+import { WslFileSystem } from "./index.js";
+
+/**
+ * Whether a resolved target identity belongs to the distro.
+ *
+ * @param targetKey - the target's identity (a UNC for distro paths).
+ * @returns true when the target lives inside a WSL distro.
+ */
+export function targetIsDistro(targetKey) {
+  return isWslUnc(targetKey);
+}
+
+/**
+ * Whether a raw path-or-cwd input names the distro (used by the operations
+ * that take paths before a target exists: resolve, lstat).
+ *
+ * @param value - a path in any coordinate system, or undefined.
+ * @returns true when the input names a distro UNC.
+ */
+export function inputIsDistro(value) {
+  return value !== undefined && isWslUnc(value);
+}
+
+/**
+ * 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.
+ */
+/**
+ * The root-plane filesystem with coordinate routing.
+ *
+ * The distro backend is built lazily on the first routed target, sharing this
+ * context (the root `sandboxPolicy` service provides the deployment default
+ * mode the distro side reports through `sandboxMode`).
+ */
+export class WslRoutingFileSystem extends LocalFileSystem {
+  static Config = LocalFileSystem.Config;
+
+  /** The lazy distro backend, built on first routed use. */
+  #distro;
+  /** The distro knobs, verbatim from the row config. */
+  #distroConfig;
+
+  constructor(ctx, config) {
+    super(ctx, config);
+    this.#distroConfig = {
+      distro: config.distro ?? "",
+      wslPath: config.wslPath ?? "wsl.exe",
+      cwd: config.distroCwd ?? "",
+      diffBasisMaxBytes: config.diffBasisMaxBytes,
+      sandbox: config.sandbox ?? true,
+      maskWindowsDrive: config.maskWindowsDrive ?? false,
+      restrictToDistro: config.restrictToDistro ?? true,
+      watchMaxDepth: config.watchMaxDepth ?? 0,
+    };
+  }
+
+  /** The distro backend for routed targets, built on first use. */
+  distro() {
+    return (this.#distro ??= new WslFileSystem(this.ctx, this.#distroConfig));
+  }
+
+  async resolve(path, opts) {
+    if (inputIsDistro(path) || inputIsDistro(opts?.cwd)) return (await this.distro()).resolve(path, opts);
+    return super.resolve(path, opts);
+  }
+
+  async lstat(path, opts, signal) {
+    if (inputIsDistro(path) || inputIsDistro(opts?.cwd)) return (await this.distro()).lstat(path, opts, signal);
+    return super.lstat(path, opts, signal);
+  }
+
+  async stat(target, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).stat(target, signal);
+    return super.stat(target, signal);
+  }
+
+  async readText(target, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).readText(target, signal);
+    return super.readText(target, signal);
+  }
+
+  async streamText(target, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).streamText(target, signal);
+    return super.streamText(target, signal);
+  }
+
+  async readBytes(target, signal, maxBytes) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).readBytes(target, signal, maxBytes);
+    return super.readBytes(target, signal, maxBytes);
+  }
+
+  async readByteRange(target, range, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).readByteRange(target, range, signal);
+    return super.readByteRange(target, range, signal);
+  }
+
+  async listDir(target, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).listDir(target, signal);
+    return super.listDir(target, signal);
+  }
+
+  async writeText(target, content, expected, signal, sandboxPolicy) {
+    if (targetIsDistro(target.targetKey)) {
+      return (await this.distro()).writeText(target, content, expected, signal, sandboxPolicy);
+    }
+    return super.writeText(target, content, expected, signal, sandboxPolicy);
+  }
+
+  async editText(target, edit, expected, signal, sandboxPolicy) {
+    if (targetIsDistro(target.targetKey)) {
+      return (await this.distro()).editText(target, edit, expected, signal, sandboxPolicy);
+    }
+    return super.editText(target, edit, expected, signal, sandboxPolicy);
+  }
+
+  async watch(target, changed, signal) {
+    if (targetIsDistro(target.targetKey)) return (await this.distro()).watch(target, changed, signal);
+    return super.watch(target, changed, signal);
+  }
+
+  contains(parent, child) {
+    if (targetIsDistro(parent.targetKey)) {
+      // Both targets came from this router's distro resolve, so the plain
+      // POSIX containment over their process paths is the same check the
+      // distro substrate performs for its own guarded writes.
+      const base = this.processPath(parent);
+      const full = this.processPath(child);
+      return full === base || full.startsWith(base.endsWith("/") ? base : `${base}/`);
+    }
+    return super.contains(parent, child);
+  }
+
+  processPath(target) {
+    const parsed = uncToPosix(target.targetKey);
+    if (parsed !== undefined) return parsed.linuxPath.length > 0 ? parsed.linuxPath : "/";
+    return super.processPath(target);
+  }
+}
+
+export default WslRoutingFileSystem;

package/lib/git-route.js

@@ -0,0 +1,142 @@
+/**
+ * Which git spawns belong inside the distro, and the `wsl.exe` argv they
+ * become there.
+ *
+ * `workspace-changes` snapshots a workspace's git state by spawning the host
+ * git through `ctx.subprocess` with the workspace as the working directory.
+ * On a distro workspace that spawn runs Windows git against the 9P share —
+ * the same slow direction as the search path, and the snapshot's
+ * `git add --all` is a full work-tree scan, the most metadata-heavy operation
+ * there is. The interception point is the same `spawn` override; the decision
+ * lives here, pure and unit-testable, mirroring `search-route.js`.
+ *
+ * ## What is routed, and what deliberately is not
+ *
+ * A spawn is routed only when the working directory names the distro (a
+ * `\\wsl.localhost\<distro>` UNC) and the argv carries none of the discovery
+ * flags (`--show-toplevel`, `--absolute-git-dir`, `--git-path`). Those three
+ * print **absolute paths**, which `workspace-changes` resolves against the
+ * UNC workspace (`git.ts` `resolve(cwd, line)`) — a distro git would answer
+ * in Linux paths and corrupt that resolution. Host git answers in UNC form,
+ * which is exactly what the caller wants, and the discovery call is one
+ * cheap command rather than a work-tree scan. Everything else — `add`,
+ * `write-tree`, `ls-tree`, `cat-file`, `diff-tree`, `ls-files`,
+ * `check-ignore` — is safe to route: snapshot calls run in an environment
+ * fully isolated from the user's git state (`GIT_INDEX_FILE` /
+ * `GIT_OBJECT_DIRECTORY` / `GIT_ALTERNATE_OBJECT_DIRECTORIES` pointing at the
+ * tool's private scratch), so the distro git mutates scratch, never the
+ * repository.
+ *
+ * ## Environment translation
+ *
+ * The routed spawn must forward the caller's `GIT_*` environment into the
+ * distro, and its values are paths in Windows form (`\\wsl.localhost\...`
+ * identities and drive-letter scratch dirs). `translateGitEnv` rewrites those
+ * two shapes into distro paths with the same pure translations the fs seam
+ * uses, forwards every other value verbatim (`GIT_CONFIG_COUNT=0` and
+ * friends), and returns the names that must ride `WSLENV`. One documented
+ * limit: a colon-separated multi-directory value (none of the current
+ * callers set one) passes through untranslated.
+ *
+ * @module dsh-plugin-wsl/git-route
+ */
+
+import { isWslUnc, uncToPosix, windowsToLinuxMount } from "./paths.js";
+
+/** The one program this rewrite passes through to the distro. */
+const GIT_PROGRAM = "git";
+
+/** Discovery flags print absolute paths — host git keeps that contract. */
+const DISCOVERY_FLAGS = ["--show-toplevel", "--absolute-git-dir", "--git-path"];
+
+/**
+ * Whether a spawn's program is git.
+ * @param unknown - the spawn's `argv[0]`.
+ * @returns true when the spawn is a git launch.
+ */
+export function isGitProgram(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, "") === GIT_PROGRAM;
+}
+
+/**
+ * Whether a git argv carries the discovery flags whose absolute output the
+ * caller resolves against the UNC world.
+ * @param {unknown[]} argv - the spawn's argv; `argv[0]` is the program.
+ * @returns true when the spawn must stay on host git.
+ */
+function namesDiscoveryPaths(argv) {
+  return argv.some((arg) => typeof arg === "string" && DISCOVERY_FLAGS.includes(arg));
+}
+
+/**
+ * Translate one `GIT_*` value into the distro's coordinate system.
+ *
+ * UNC identities (`\\wsl.localhost\<distro>\...`) map onto their Linux paths;
+ * drive-letter paths map onto their `/mnt/<drive>` mounts; anything else is
+ * not a path we can name and passes through verbatim.
+ *
+ * @param value - the env value.
+ * @returns the distro-side spelling of the value.
+ */
+export function translateGitEnvValue(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;
+}
+
+/**
+ * Translate a git spawn's environment for the distro and name the keys that
+ * must ride `WSLENV`.
+ *
+ * @param env - the spawn's environment, or undefined.
+ * @returns the environment to forward (every key, path-shaped values
+ *   translated) and the `WSLENV` names.
+ */
+export function translateGitEnv(env) {
+  const translated = {};
+  const names = [];
+  for (const [name, value] of Object.entries(env ?? {})) {
+    translated[name] = name.startsWith("GIT_") ? translateGitEnvValue(value) : value;
+    names.push(name);
+  }
+  return { env: translated, wslenv: names };
+}
+
+/**
+ * The distro-side rewrite of one git spawn, when it belongs in the distro.
+ *
+ * `gitArgv` is the distro command itself; `wslArgv` is the same command
+ * wrapped for a one-shot `wsl.exe --exec` launch — git snapshot operations
+ * are not latency-sensitive, so the routing stays on the simple transport
+ * and does not need the resident agent. `wsl.exe` itself must start in a
+ * Windows directory, so the caller supplies its own host cwd.
+ *
+ * @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, gitArgv: string[], wslArgv: string[]}|undefined} the
+ *   rewrite, or undefined when the spawn is not a routable distro git launch
+ *   (non-git programs, host directories, and the absolute-output discovery
+ *   flags all keep the shipped spawn).
+ */
+export function gitSpawnRewrite({ argv, cwd, wslPath }) {
+  if (!Array.isArray(argv) || !isGitProgram(argv[0])) return undefined;
+  if (namesDiscoveryPaths(argv)) return undefined;
+  const named = uncToPosix(cwd);
+  if (named === undefined) return undefined;
+  const linuxCwd = named.linuxPath.length > 0 ? named.linuxPath : "/";
+  const gitArgv = [GIT_PROGRAM, ...argv.slice(1)];
+  return {
+    distro: named.distro,
+    linuxCwd,
+    gitArgv,
+    wslArgv: [wslPath, "-d", named.distro, "--cd", linuxCwd, "--exec", ...gitArgv],
+  };
+}