dsh-plugin-wsl-env 0.15.0 → 0.17.0

package/lib/fs-routing.js

@@ -31,6 +31,7 @@
  * @module dsh-plugin-wsl/fs-routing
  */
 import { isWslUnc, uncToPosix } from "./paths.js";
+import z from "@deepseek-ai/schemastery";
 import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
 import { WslFileSystem } from "./index.js";
 /**
@@ -101,7 +102,18 @@ export function inputIsDistro(value) {
  * mode the distro side reports through `sandboxMode`).
  */
 export class WslRoutingFileSystem extends LocalFileSystem {
-    static Config = LocalFileSystem.Config;
+    static Config = z.intersect([
+        LocalFileSystem.Config,
+        z.object({
+            distro: z.string().default(""),
+            wslPath: z.string().default("wsl.exe"),
+            distroCwd: z.string().default(""),
+            sandbox: z.boolean().default(true),
+            maskWindowsDrive: z.boolean().default(false),
+            restrictToDistro: z.boolean().default(true),
+            watchMaxDepth: z.natural().default(0),
+        }),
+    ]);
     /**
      * The routed backend's constructor reads the deployment default mode from
      * `ctx.sandboxPolicy`, exactly as the shipped `fs-sandbox` row this class

package/lib/fs-substrate.d.ts

@@ -13,12 +13,9 @@
  *    create publishes with the distro-side no-replace link, a real atomic
  *    primitive that refuses to replace. An overwrite or edit carries the
  *    version it was based on INTO the write op, and the agent re-verifies it
- *    with a fresh stat one syscall before the rename: a concurrent writer
- *    (an editor save, `git stash`, another session) wins, and the stale
- *    write refuses with `FS_STALE_VERSION` instead of clobbering. That
- *    narrows the share backend's check-then-write window from a host round
- *    trip to kernel-adjacent — the honest wording; "closed" was true only
- *    for the create case.
+ *    with a fresh stat before the rename: an earlier conflicting write is
+ *    refused with `FS_STALE_VERSION`. A writer between that stat and the
+ *    rename can still be overwritten; only guarded create is atomic.
  * 2. A symlink needs no retry machinery: every identity is resolved where the
  *    symlinks live.
  *
@@ -59,6 +56,7 @@ export declare class AgentSubstrate {
     agentFor: ((policy: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined) => Promise<WslAgent>) | undefined;
     /** The distro-side filesystem face. */
     fs: DistroFs;
@@ -83,6 +81,7 @@ export declare class AgentSubstrate {
         agentFor?: (policy: {
             mode: string;
             workspaceRoot: string;
+            sessionId?: string;
         } | undefined) => Promise<WslAgent>;
     });
     /**
@@ -95,6 +94,7 @@ export declare class AgentSubstrate {
     mutationAgent(policy: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined): Promise<WslAgent>;
     /**
      * Run `op` with exclusive access to `targetKey` (FIFO per key).
@@ -204,7 +204,7 @@ export declare class AgentSubstrate {
      * guard, best-effort diff basis, atomic publication, outcome shape. The
      * guard is FORWARDED — a guarded create publishes with the distro-side
      * no-replace link (atomic), and a `replaceIfVersion` write carries its
-     * version into the op, where the agent re-verifies it one syscall before
+     * version into the op, where the agent re-verifies it before
      * the rename and refuses with `FS_STALE_VERSION` on a mismatch.
      *
      * @param target - the resolved target.
@@ -220,6 +220,7 @@ export declare class AgentSubstrate {
     } | undefined, signal?: AbortSignal, policy?: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined): Promise<{
         operation: string;
         version: string;
@@ -230,8 +231,8 @@ export declare class AgentSubstrate {
      * Edit a text file with the host backend's orchestration: probe, version
      * guard, LF-normalized read, literal replacement, line-ending restore,
      * atomic publication, outcome shape. The version the edit was based on
-     * rides the write op and is re-verified distro-side one syscall before the
-     * rename, so a concurrent writer wins instead of being clobbered.
+     * rides the write op and is re-verified distro-side before the
+     * rename, narrowing but not eliminating the concurrent-write race.
      *
      * @param target - the resolved target.
      * @param edit - the literal request.
@@ -249,6 +250,7 @@ export declare class AgentSubstrate {
     } | undefined, signal?: AbortSignal, policy?: {
         mode: string;
         workspaceRoot: string;
+        sessionId?: string;
     } | undefined): Promise<{
         version: string;
         before: string;

package/lib/fs-substrate.js

@@ -13,12 +13,9 @@
  *    create publishes with the distro-side no-replace link, a real atomic
  *    primitive that refuses to replace. An overwrite or edit carries the
  *    version it was based on INTO the write op, and the agent re-verifies it
- *    with a fresh stat one syscall before the rename: a concurrent writer
- *    (an editor save, `git stash`, another session) wins, and the stale
- *    write refuses with `FS_STALE_VERSION` instead of clobbering. That
- *    narrows the share backend's check-then-write window from a host round
- *    trip to kernel-adjacent — the honest wording; "closed" was true only
- *    for the create case.
+ *    with a fresh stat before the rename: an earlier conflicting write is
+ *    refused with `FS_STALE_VERSION`. A writer between that stat and the
+ *    rename can still be overwritten; only guarded create is atomic.
  * 2. A symlink needs no retry machinery: every identity is resolved where the
  *    symlinks live.
  *
@@ -196,7 +193,7 @@ export class AgentSubstrate {
      * guard, best-effort diff basis, atomic publication, outcome shape. The
      * guard is FORWARDED — a guarded create publishes with the distro-side
      * no-replace link (atomic), and a `replaceIfVersion` write carries its
-     * version into the op, where the agent re-verifies it one syscall before
+     * version into the op, where the agent re-verifies it before
      * the rename and refuses with `FS_STALE_VERSION` on a mismatch.
      *
      * @param target - the resolved target.
@@ -247,8 +244,8 @@ export class AgentSubstrate {
      * Edit a text file with the host backend's orchestration: probe, version
      * guard, LF-normalized read, literal replacement, line-ending restore,
      * atomic publication, outcome shape. The version the edit was based on
-     * rides the write op and is re-verified distro-side one syscall before the
-     * rename, so a concurrent writer wins instead of being clobbered.
+     * rides the write op and is re-verified distro-side before the
+     * rename, narrowing but not eliminating the concurrent-write race.
      *
      * @param target - the resolved target.
      * @param edit - the literal request.

package/lib/fsio-agent.d.ts

@@ -244,9 +244,8 @@ export declare class DistroFs {
      * Publish `content` over `linuxPath` the POSIX way: the agent stages into a
      * private 0700 sibling, fsyncs, chmods, and renames — or hard links for a
      * guarded create. A `replace` publish carrying `expectedVersion` is
-     * re-verified by the agent against a fresh stat one syscall before the
-     * rename: a concurrent writer (an editor save, a `git stash`) wins, and the
-     * stale write refuses with `FS_STALE_VERSION` instead of landing.
+     * re-verified by the agent against a fresh stat before the rename. A change
+     * after that check can still be overwritten by the rename.
      *
      * @param linuxPath - the target path inside the distro.
      * @param content - the full new content.

package/lib/fsio-agent.js

@@ -407,9 +407,8 @@ export class DistroFs {
      * Publish `content` over `linuxPath` the POSIX way: the agent stages into a
      * private 0700 sibling, fsyncs, chmods, and renames — or hard links for a
      * guarded create. A `replace` publish carrying `expectedVersion` is
-     * re-verified by the agent against a fresh stat one syscall before the
-     * rename: a concurrent writer (an editor save, a `git stash`) wins, and the
-     * stale write refuses with `FS_STALE_VERSION` instead of landing.
+     * re-verified by the agent against a fresh stat before the rename. A change
+     * after that check can still be overwritten by the rename.
      *
      * @param linuxPath - the target path inside the distro.
      * @param content - the full new content.

package/lib/git-exec.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 type { AgentExecRunner } from "./agent-exec.js";
+/** One collected-stream reader with the seam's standard shape. */
+export interface GitStreamReader {
+    /** Read the stream from a byte offset; `lossy` says the cap cut it. */
+    readFrom: (from: number) => {
+        text: string;
+        lossy: boolean;
+        nextOffset: number;
+    };
+}
+/**
+ * The slice of the subprocess handle `GitRunner` consumes: settle on `done`,
+ * then read the collected streams.
+ */
+export interface GitExecutionHandle {
+    /** Settles with the exit code and signal; rejects on a genuine failure. */
+    done: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    /** The collected stream readers; a delegated handle's own on fallback. */
+    collected: {
+        stdout?: GitStreamReader | undefined;
+        stderr?: GitStreamReader | undefined;
+    };
+    /** Cooperative kill; the runner relies on its `signal` for cancellation. */
+    kill?: () => boolean | void;
+}
+/** Per-stream capture budgets the caller declared on its `stdio` spec. */
+export interface GitStreamCaps {
+    /** The stdout budget in bytes; the snapshot's `outputMaxBytes`. */
+    stdout: number;
+    /** The stderr tail budget in bytes. */
+    stderr: number;
+}
+/**
+ * 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 declare function gitExecutionHandle({ agent, cwd, argv, env, stdin, caps, distro, discovery, signal, spawnFallback }: {
+    /** The {@link WslAgent}-like runner; throws `AgentUnavailableError` when out. */
+    agent: AgentExecRunner;
+    /** The Linux working directory to snapshot from. */
+    cwd: string;
+    /** The distro-side argv (`git` and its arguments). */
+    argv: string[];
+    /**
+     * The distro name; required when `discovery` is set (absolute path lines
+     * become `\\wsl.localhost\<distro><path>`).
+     */
+    distro?: string;
+    /**
+     * True for a SENTINEL discovery call (`--show-toplevel` /
+     * `--absolute-git-dir` / `--git-path` answered by the distro git): the
+     * captured stdout's absolute Linux path lines are translated into UNC form
+     * before the caller reads them. Snapshot calls leave this unset.
+     */
+    discovery?: boolean;
+    /**
+     * Per-request environment: the caller's entries with path-shaped values
+     * translated into distro form. Empty entries are dropped; nothing but
+     * `GIT_*` names should reach here.
+     */
+    env: Record<string, string>;
+    /** The child's entire stdin, or undefined for an empty one. */
+    stdin?: Uint8Array;
+    /** Per-stream capture budgets from the caller's `stdio` spec. */
+    caps: GitStreamCaps;
+    /** The caller's cancellation (its own timeout races in through `AbortSignal.any`). */
+    signal?: AbortSignal;
+    /**
+     * Builds the one-shot handle the facade delegates to when the agent is out;
+     * called at most once, lazily.
+     */
+    spawnFallback: () => GitExecutionHandle;
+}): GitExecutionHandle;

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");
+}