dsh-plugin-wsl-env 0.16.0 → 0.17.1

package/lib/git-exec.js

@@ -0,0 +1,105 @@
+/**
+ * The agent-backed execution handle for the git-snapshot spawn.
+ *
+ * `workspace-changes`' `GitRunner` consumes a small slice of the subprocess
+ * handle: `handle.done` for `{exitCode, signal}`, then
+ * `handle.collected.stdout/stderr.readFrom(0)` for `{text, lossy}` — with
+ * per-stream caps applied by the caller's `stdio` spec (a generous stdout
+ * budget and a 16 KiB stderr tail). This module builds exactly that surface
+ * around one resident-agent `exec`, so a distro snapshot pays the warm agent's
+ * ~2 ms round trip per git call instead of the one-shot `wsl.exe`'s ~230 ms
+ * process startup — measured 2026-11-01 on `ubuntu`; a full snapshot's 6-8
+ * calls (plus per-file `cat-file`) used to spend over a second inside
+ * `wsl.exe` alone.
+ *
+ * The caps map onto the agent's single per-request capture ceiling as the
+ * larger of the two stream budgets; the reader then slices each stream to its
+ * own budget and reports `lossy` from that slice, so the caller's contract
+ * (per-stream cut flags) holds even though the wire carries one cap.
+ *
+ * Environment rides the agent's per-request `env` (an `env --` argv prefix —
+ * no `SETENV` global pollution), holding only the translated `GIT_*` names:
+ * the one-shot path forwards exactly those through `WSLENV`, and forwarding a
+ * host `PATH` into the distro would be wrong, not just different.
+ *
+ * The agent being out is the fallback cue, exactly as `search-exec.ts`:
+ * `spawnFallback` (the caller's one-shot `wsl.exe` handle) is consulted
+ * lazily inside `done`, and from that point the facade proxies the delegate
+ * verbatim. Cancellation shares one channel: the caller's `signal` and
+ * `kill()` abort the agent exec, settling `done` as killed.
+ *
+ * Pure shaping over injected collaborators, unit-testable without a distro.
+ *
+ * This is a TypeScript source built to `lib/git-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/git-exec
+ */
+import { AgentUnavailableError } from "./agent-errors.js";
+import { translateDiscoveryOutput } from "./git-route.js";
+/**
+ * Run one git command through the agent and present it as a git-snapshot
+ * handle.
+ *
+ * @param object - the handle's collaborators.
+ * @returns the snapshot handle (`done`, `collected`, `kill`).
+ */
+export function gitExecutionHandle({ agent, cwd, argv, env, stdin, caps, distro, discovery, 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 });
+    // The agent enforces ONE cap per request; declare the larger budget on the
+    // wire and cut each stream to its own budget here, so the caller's
+    // per-stream contract holds and a stream under its cap is never flagged.
+    const wireCap = Math.max(caps.stdout, caps.stderr);
+    const reader = (slot) => {
+        const cap = slot === "stdout" ? caps.stdout : caps.stderr;
+        return {
+            readFrom(from) {
+                const buffer = state[slot] ?? Buffer.alloc(0);
+                const lossy = buffer.length > cap;
+                const visible = lossy ? buffer.subarray(0, cap) : buffer;
+                const start = Math.min(from, visible.length);
+                return { text: visible.subarray(start).toString("utf8"), lossy, nextOffset: visible.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, env, stdin, maxOutputBytes: wireCap, signal: controller.signal });
+                state.stdout = discovery ? translateDiscoveryOutput(distro ?? "", result.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/git-route.d.ts

@@ -13,19 +13,28 @@
  * ## 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.
+ * `\\wsl.localhost\\<distro>` UNC). Inside that, two cases:
+ *
+ * - **Snapshot calls** (`add`, `write-tree`, `ls-tree`, `cat-file`,
+ *   `diff-tree`, `ls-files`, `check-ignore`) route whenever the program is
+ *   git — the runs are 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.
+ * - **Discovery calls** (`--show-toplevel`, `--absolute-git-dir`, `--git-path`)
+ *   print absolute paths that the caller resolves against the UNC workspace,
+ *   so a distro answer in Linux paths would corrupt that resolution. They
+ *   route only when the program is the SENTINEL path `DISTRO_GIT_SENTINEL` —
+ *   the guard `resolveExecutable` returns when the HOST has no git — and the
+ *   facade translates the output lines into UNC form before the caller sees
+ *   them (`translateDiscoveryOutput`). A host-resolved git keeps the shipped
+ *   host-side discovery, which answers UNC natively (and needs the documented
+ *   `safe.directory` whitelist for WSL shares).
+ *
+ * The split means a machine without Windows git still gets full WSL change
+ * review: the sentinel resolves, every spawn routes, nothing touches the
+ * host. See `lib/git-exec.js` for the facade side.
+ *
  *
  * ## Environment translation
  *
@@ -44,6 +53,14 @@
  *
  * @module dsh-plugin-wsl/git-route
  */
+/**
+ * The program path `resolveExecutable` returns for git when the HOST has no
+ * git: a Linux absolute path that only makes sense inside the distro, so any
+ * spawn carrying it must route (and a discovery spawn's output must come back
+ * translated). Chosen to match a standard distro install so the argv stays
+ * honest even where it is read verbatim.
+ */
+export declare const DISTRO_GIT_SENTINEL = "/usr/bin/git";
 /**
  * Whether a spawn's program is git.
  *
@@ -97,4 +114,17 @@ export declare function gitSpawnRewrite({ argv, cwd, wslPath }: {
     linuxCwd: string;
     gitArgv: string[];
     wslArgv: string[];
+    discovery?: boolean;
 } | undefined;
+/**
+ * Translate one routed discovery call's stdout into the caller's UNC
+ * coordinate system: every absolute Linux path line becomes
+ * `\\wsl.localhost\<distro><path>`; relative lines (`--git-path` answers
+ * `.git/objects` when the repository is not bare) pass through untouched,
+ * because the caller resolves them against the UNC cwd natively.
+ *
+ * @param distro - the distro the discovery ran in.
+ * @param stdout - the distro git's captured stdout.
+ * @returns the stdout with absolute path lines rewritten.
+ */
+export declare function translateDiscoveryOutput(distro: string, stdout: Buffer): Buffer;

package/lib/git-route.js

@@ -13,19 +13,28 @@
  * ## 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.
+ * `\\wsl.localhost\\<distro>` UNC). Inside that, two cases:
+ *
+ * - **Snapshot calls** (`add`, `write-tree`, `ls-tree`, `cat-file`,
+ *   `diff-tree`, `ls-files`, `check-ignore`) route whenever the program is
+ *   git — the runs are 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.
+ * - **Discovery calls** (`--show-toplevel`, `--absolute-git-dir`, `--git-path`)
+ *   print absolute paths that the caller resolves against the UNC workspace,
+ *   so a distro answer in Linux paths would corrupt that resolution. They
+ *   route only when the program is the SENTINEL path `DISTRO_GIT_SENTINEL` —
+ *   the guard `resolveExecutable` returns when the HOST has no git — and the
+ *   facade translates the output lines into UNC form before the caller sees
+ *   them (`translateDiscoveryOutput`). A host-resolved git keeps the shipped
+ *   host-side discovery, which answers UNC natively (and needs the documented
+ *   `safe.directory` whitelist for WSL shares).
+ *
+ * The split means a machine without Windows git still gets full WSL change
+ * review: the sentinel resolves, every spawn routes, nothing touches the
+ * host. See `lib/git-exec.js` for the facade side.
+ *
  *
  * ## Environment translation
  *
@@ -47,7 +56,15 @@
 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. */
+/**
+ * The program path `resolveExecutable` returns for git when the HOST has no
+ * git: a Linux absolute path that only makes sense inside the distro, so any
+ * spawn carrying it must route (and a discovery spawn's output must come back
+ * translated). Chosen to match a standard distro install so the argv stays
+ * honest even where it is read verbatim.
+ */
+export const DISTRO_GIT_SENTINEL = "/usr/bin/git";
+/** Discovery flags print absolute paths — the caller resolves them. */
 const DISCOVERY_FLAGS = ["--show-toplevel", "--absolute-git-dir", "--git-path"];
 /**
  * Whether a spawn's program is git.
@@ -125,7 +142,8 @@ export function translateGitEnv(env) {
 export function gitSpawnRewrite({ argv, cwd, wslPath }) {
     if (!Array.isArray(argv) || !isGitProgram(argv[0]))
         return undefined;
-    if (namesDiscoveryPaths(argv))
+    const sentinel = argv[0] === DISTRO_GIT_SENTINEL;
+    if (namesDiscoveryPaths(argv) && !sentinel)
         return undefined;
     const named = uncToPosix(cwd);
     if (named === undefined)
@@ -137,5 +155,26 @@ export function gitSpawnRewrite({ argv, cwd, wslPath }) {
         linuxCwd,
         gitArgv,
         wslArgv: [wslPath, "-d", named.distro, "--cd", linuxCwd, "--exec", ...gitArgv],
+        discovery: sentinel && namesDiscoveryPaths(argv),
     };
 }
+/**
+ * Translate one routed discovery call's stdout into the caller's UNC
+ * coordinate system: every absolute Linux path line becomes
+ * `\\wsl.localhost\<distro><path>`; relative lines (`--git-path` answers
+ * `.git/objects` when the repository is not bare) pass through untouched,
+ * because the caller resolves them against the UNC cwd natively.
+ *
+ * @param distro - the distro the discovery ran in.
+ * @param stdout - the distro git's captured stdout.
+ * @returns the stdout with absolute path lines rewritten.
+ */
+export function translateDiscoveryOutput(distro, stdout) {
+    const text = stdout.toString("utf8");
+    if (!text.includes("\n") && !text.startsWith("/"))
+        return stdout;
+    const translated = text.split("\n").map((line) => line.startsWith("/")
+        ? `\\\\wsl.localhost\\${distro}${line.replaceAll("/", "\\")}`
+        : line);
+    return Buffer.from(translated.join("\n"), "utf8");
+}

package/lib/subprocess.d.ts

@@ -60,13 +60,17 @@
  *
  * ## What the operator must pair it with
  *
- * `terminalEnvironment()` and `resolveExecutable()` are also resolved from the
- * root realm, and neither receives a Session or a directory, so this provider
- * deliberately leaves them alone: rewriting them would change executable lookup
- * for every other root consumer (the pwsh executor, the LSP host, the file
- * search) to make the *shell menu* of one window prettier. The profile instead
- * configures the terminal controller with the single shell profile that matters:
- * `shell: { path: wsl.exe, name: WSL }` and `shellCandidates: []`.
+ * `terminalEnvironment()` is also resolved from the root realm and receives no
+ * Session or directory, so this provider deliberately leaves it alone:
+ * rewriting it would change environment lookup for every other root consumer
+ * to make the *shell menu* of one window prettier. `resolveExecutable()` gets
+ * ONE scoped exception — a git fallback when the host has none (see the
+ * override below); every other name's lookup is untouched. The profile also
+ * configures the terminal controller with the distro shell as the default
+ * profile plus deliberate host candidates: `shell: { path: wsl.exe, name: WSL }`
+ * and `shellCandidates: [wsl.exe, powershell, cmd]` — the first dedupes into
+ * the default's `wsl` kind, and the other two are launches this terminal really
+ * starts (host sessions, or an explicit user selection, titled after itself).
  *
  * Consequence worth stating plainly: the terminal is a property of the
  * composition, not of the Session. A Session whose workspace is a Windows folder
@@ -297,6 +301,16 @@ export declare class WslSubprocessRuntime extends LocalSubprocessRuntime {
      * @returns the live search handle.
      */
     spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+    /**
+     * Guarded git fallback: when the HOST has no git, resolve the name to the
+     * distro sentinel so the change-review pipeline's every spawn (discovery
+     * included) routes into the distro instead of dying at the executable
+     * lookup. Scoped to the one name — every other consumer's lookup (pwsh,
+     * LSP, ripgrep) is untouched — and only on the super's failure, so a
+     * machine with Windows git behaves exactly as shipped. See
+     * `git-route.ts`'s `DISTRO_GIT_SENTINEL` for the routing side.
+     */
+    resolveExecutable(command: string, env: Record<string, string> | undefined, signal: AbortSignal | undefined): Promise<string>;
     /**
      * The environment one `wsl.exe` launch forwards: the safe list plus every
      * managed `DSH_*` name, admitted through `WSLENV` and never `PATH` — see the

package/lib/subprocess.js

@@ -60,13 +60,17 @@
  *
  * ## What the operator must pair it with
  *
- * `terminalEnvironment()` and `resolveExecutable()` are also resolved from the
- * root realm, and neither receives a Session or a directory, so this provider
- * deliberately leaves them alone: rewriting them would change executable lookup
- * for every other root consumer (the pwsh executor, the LSP host, the file
- * search) to make the *shell menu* of one window prettier. The profile instead
- * configures the terminal controller with the single shell profile that matters:
- * `shell: { path: wsl.exe, name: WSL }` and `shellCandidates: []`.
+ * `terminalEnvironment()` is also resolved from the root realm and receives no
+ * Session or directory, so this provider deliberately leaves it alone:
+ * rewriting it would change environment lookup for every other root consumer
+ * to make the *shell menu* of one window prettier. `resolveExecutable()` gets
+ * ONE scoped exception — a git fallback when the host has none (see the
+ * override below); every other name's lookup is untouched. The profile also
+ * configures the terminal controller with the distro shell as the default
+ * profile plus deliberate host candidates: `shell: { path: wsl.exe, name: WSL }`
+ * and `shellCandidates: [wsl.exe, powershell, cmd]` — the first dedupes into
+ * the default's `wsl` kind, and the other two are launches this terminal really
+ * starts (host sessions, or an explicit user selection, titled after itself).
  *
  * Consequence worth stating plainly: the terminal is a property of the
  * composition, not of the Session. A Session whose workspace is a Windows folder
@@ -79,13 +83,15 @@
  * @module dsh-plugin-wsl/subprocess
  */
 import { randomUUID } from "node:crypto";
+import { Buffer } from "node:buffer";
 import z from "@deepseek-ai/schemastery";
 import { LocalSubprocessRuntime } from "@deepseek-ai/dsh-subprocess-local";
 import { isPosixAbsolute, toLinuxPath, uncToPosix, windowsToLinuxMount } from "./paths.js";
 import { DEFAULT_WSL_PATH, defaultDistro, wslEnvValue, wslTerminalArgv } from "./wsl.js";
 import { searchSpawnRewrite } from "./search-route.js";
-import { gitSpawnRewrite, translateGitEnv } from "./git-route.js";
+import { DISTRO_GIT_SENTINEL, gitSpawnRewrite, translateGitEnv } from "./git-route.js";
 import { searchExecutionHandle } from "./search-exec.js";
+import { gitExecutionHandle } from "./git-exec.js";
 import { sharedAgent } from "./agent-shared.js";
 import { parseTerminalActivity, TERMINAL_ID_ENV, terminalActivityProbe, wrapTerminalHandle } from "./terminal-activity.js";
 import { AgentUnavailableError } from "./agent-errors.js";
@@ -341,12 +347,40 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
             // object store, work tree, and refs stay untouched by design — the
             // snapshot runs in the tool's private scratch.
             const { env, wslenv } = translateGitEnv(spec.env);
-            return super.spawn({
+            const oneShot = () => super.spawn({
                 ...spec,
                 argv: gitRewrite.wslArgv,
                 cwd: this.hostCwd(),
                 env: wslenv.length > 0 ? { ...env, WSLENV: wslEnvValue(wslenv) } : env,
             });
+            // Agent-first: the warm resident answers a git call in ~2 ms where a
+            // one-shot `wsl.exe` spends ~230 ms of process startup, and a snapshot
+            // makes 6-8 of those calls plus per-file `cat-file`. Only the translated
+            // GIT_* names ride the agent's per-request environment — a host PATH
+            // must not leak into the distro, and the one-shot forwards exactly those
+            // names through WSLENV too. The agent being out falls back to the
+            // one-shot handle lazily (see git-exec.ts).
+            const agentEnv = {};
+            for (const [name, value] of Object.entries(env)) {
+                if (name.startsWith("GIT_") && typeof value === "string")
+                    agentEnv[name] = value;
+            }
+            const stdinSpec = spec.stdio.stdin;
+            const stdinData = typeof stdinSpec === "object" && stdinSpec !== null && typeof stdinSpec.data === "string" ? stdinSpec.data : undefined;
+            const stdoutCap = spec.stdio.stdout?.maxBytes ?? 0;
+            const stderrCap = spec.stdio.stderr?.maxBytes ?? 0;
+            return gitExecutionHandle({
+                agent: sharedAgent(gitRewrite.distro),
+                cwd: gitRewrite.linuxCwd,
+                argv: gitRewrite.gitArgv,
+                env: agentEnv,
+                stdin: stdinData === undefined ? undefined : Buffer.from(stdinData, "utf8"),
+                caps: { stdout: stdoutCap, stderr: stderrCap },
+                distro: gitRewrite.distro,
+                discovery: gitRewrite.discovery === true,
+                signal: spec.signal,
+                spawnFallback: oneShot,
+            });
         }
         const rewrite = searchSpawnRewrite({ argv: spec.argv, cwd: spec.cwd, wslPath: this.config.wslPath });
         if (rewrite === undefined)
@@ -372,6 +406,26 @@ export class WslSubprocessRuntime extends LocalSubprocessRuntime {
             }),
         });
     }
+    /**
+     * Guarded git fallback: when the HOST has no git, resolve the name to the
+     * distro sentinel so the change-review pipeline's every spawn (discovery
+     * included) routes into the distro instead of dying at the executable
+     * lookup. Scoped to the one name — every other consumer's lookup (pwsh,
+     * LSP, ripgrep) is untouched — and only on the super's failure, so a
+     * machine with Windows git behaves exactly as shipped. See
+     * `git-route.ts`'s `DISTRO_GIT_SENTINEL` for the routing side.
+     */
+    async resolveExecutable(command, env, signal) {
+        try {
+            return await super.resolveExecutable(command, env, signal);
+        }
+        catch (error) {
+            const base = command.slice(Math.max(command.lastIndexOf("/"), command.lastIndexOf("\\")) + 1).toLowerCase().replace(/\.exe$/u, "");
+            if (base === "git")
+                return DISTRO_GIT_SENTINEL;
+            throw error;
+        }
+    }
     /**
      * The environment one `wsl.exe` launch forwards: the safe list plus every
      * managed `DSH_*` name, admitted through `WSLENV` and never `PATH` — see the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "在 WSL 的 Linux 实例中打开项目工作区，在对应 Linux 空间中进行命令执行、运行 shell 脚本和文件访问，以获得全套 Linux Shell 工具链收益，并通过 bubblewrap 对命令进行沙箱隔离",
   "keywords": [
     "deepseek-harness",
@@ -100,6 +100,9 @@
     "docs/PERFORMANCE.md",
     "docs/COMPATIBILITY.md",
     "docs/CONFIGURATION.md",
+    "docs/LIMITATIONS.zh.md",
+    "docs/CONFIGURATION.zh.md",
+    "docs/QUICKSTART.zh.md",
     "docs/LIMITATIONS.md",
     "docs/RELEASING.md",
     "docs/REQUIREMENTS.zh.md",

package/scripts/doctor.mjs

@@ -394,6 +394,26 @@ async function main(options) {
     if (m === null) return [];
     return (m[1] ?? "").trim().split(/\s+/).filter((p) => p.length > 0);
   });
+  // ---- Windows git trust (WSL change review) ------------------------------
+  // The change-review pipeline's discovery call runs the WINDOWS git against
+  // a \\wsl.localhost UNC when Windows git is installed; git's
+  // dubious-ownership check refuses the share unless it is whitelisted, and
+  // the pipeline silently degrades to "git is unavailable" (no diff cards for
+  // WSL workspaces). A machine without Windows git is fine too — the provider
+  // resolves git to a distro sentinel and routes everything. What the doctor
+  // can probe cheaply from here is interop git.exe and its whitelist.
+  const winGitVersion = await run(["git.exe", "--version"]);
+  if (!winGitVersion.ok) {
+    check("git.win-safe", "info", "Windows git trust", "Windows git not found through interop — WSL change review uses the distro fallback; host (C:\\...) workspaces would need git for their own review");
+  } else {
+    const entries = (await run(["git.exe", "config", "--global", "--get-all", "safe.directory"])).stdout.split(/\r?\n/).filter(Boolean);
+    const whitelisted = entries.some((entry) => /wsl\.localhost/i.test(entry));
+    check("git.win-safe", whitelisted ? "ok" : "warn", "Windows git trust",
+      whitelisted ? `the \\\\wsl.localhost share is whitelisted (${entries.length} entr${entries.length === 1 ? "y" : "ies"})`
+        : "Windows git does not trust the \\\\wsl.localhost share; WSL workspaces' change review silently degrades to file-tool edits",
+      whitelisted ? undefined : 'on Windows: git config --global --add safe.directory "//wsl.localhost/*", then restart the app');
+  }
+
   // ---- resident handshake --------------------------------------------------
   const agentScript = join(ROOT, "agent", "wsl-agent.sh");
   if (!agentScript.startsWith("/")) {