dsh-plugin-wsl-env 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -14,7 +14,63 @@ document: the 0.1.0 entry's `design-history §` references are to
 keeps the superseded designs under the section numbers they had while they
 were part of the record.
 
-## [Unreleased]
+## [0.17.0] - 2026-11-01
+
+### Changed
+
+- **Git snapshot spawns are now agent-first with a one-shot fallback.**
+  Protocol v6 adds a stdin payload to the EXEC frame (a seventh header field
+  flagging one trailing base64 line), which is what lets `workspace-changes`'
+  snapshot calls — including `check-ignore -z --stdin` — run on the warm
+  resident agent instead of a one-shot `wsl.exe`. Measured on `ubuntu`
+  (2026-11-01): ~232 ms per one-shot git call (nearly all `wsl.exe` process
+  startup) against ~1.6 ms on the resident — a 6-8 call snapshot saves well
+  over a second. The per-stream caps map onto the agent's single wire cap with
+  a client-side per-stream slice (`lib/git-exec.js`), and the environment
+  rides the agent's per-request `env` (`env --` argv prefix, no `SETENV`
+  pollution) carrying only the translated `GIT_*` names. Both agents speak v6
+  (the shell agent decodes the payload through command substitution, which
+  strips trailing newlines — NUL separators survive; the native binary
+  delivers bytes verbatim), so host library and shipped binaries upgrade
+  together; the doctor's handshake reports any mismatch.
+
+- **WSL change review no longer requires Windows git.** When
+  `resolveExecutable('git')` fails on the host, the provider answers with a
+  distro sentinel (`/usr/bin/git`); every workspace-changes spawn — the
+  `rev-parse` discovery included — then routes into the distro, and the
+  snapshot facade translates the discovery call's absolute-path output lines
+  into UNC form (`translateDiscoveryOutput`). A machine with Windows git is
+  unchanged (host discovery + `safe.directory` whitelist). The
+  `resolveExecutable` override is scoped to the one name and only fires on
+  the super's failure.
+
+- **The doctor probes the Windows git trust.** A new `git.win-safe` check
+  reports the `safe.directory` whitelist state through interop `git.exe`:
+  `ok` when the `\\wsl.localhost` share is whitelisted, a warn with the
+  copy-paste remedy when Windows git does not trust it, and an info (nothing
+  to do) when there is no Windows git — the distro fallback covers WSL change
+  review entirely.
+
+### Documentation
+
+- The architecture and upstream-promotion documents reflect the v6 protocol
+  and the shell-menu candidates; the promotion map records the measurement
+  that superseded the git one-shot decision.
+- The full real-machine suite re-ran 15/0 on 2026-11-01 after the protocol
+  change landed, and again after the documentation refresh. The safe.directory
+  prerequisite for WSL change review is now documented with its one-time
+  remedy.
+
+- **The shell menu now offers host shells instead of a single entry.**
+  `terminal-controller`'s `shellCandidates` grows from `[]` to
+  `[wsl.exe, powershell, cmd]` while the default profile stays
+  `shell: { path: wsl.exe, name: WSL }`. `wsl.exe` dedupes into the default's
+  `wsl` kind; `powershell` and `cmd` are launches this terminal really starts —
+  host sessions already run PowerShell outright (`hostSessions`), and a manually
+  selected shell is titled after itself, which moves the tab-title workaround
+  from a user-layer edit into the plugin's own composition
+  ([#8769](https://github.com/deepseek-ai/deepseek-harness/discussions/8769)
+  remains the real fix for the default entry's title).
 
 ## [0.16.0] - 2026-10-31
 

package/agent/wsl-agent.sh

@@ -24,8 +24,12 @@
 #   SETENV|<key>|<b64 value>      -> export the variable for later requests;
 #                                    <key> must be a POSIX identifier, else
 #                                    ERR|protocol
-#   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>|<output cap bytes|0>
-#       followed by <n args> lines of base64, one argv word each
+#   EXEC|<id>|<b64 cwd>|<timeout seconds|0>|<n args>|<output cap bytes|0>|<stdin flag|0>
+#       followed by <n args> lines of base64, one argv word each, and — when
+#       the stdin flag is 1 — one more base64 line: the child's entire stdin.
+#       The agent feeds those bytes to the child and closes its stdin, so the
+#       child sees EOF at the payload's end. Absent or 0 means the child reads
+#       an empty stdin and immediate EOF (the v5 shape).
 #       -> ACK|<id> the moment the request is dequeued for execution — the host
 #          arms its stuck-request watchdog on this line, so time spent queued
 #          behind an earlier request never counts against a budget
@@ -62,7 +66,14 @@
 
 set -u
 
-PROTO_VERSION=5
+# v6: EXEC gains an optional seventh header field flagging one stdin payload
+# line after the argv words. One documented limitation, the same one SETENV
+# and every argv word already carry: command substitution strips TRAILING
+# NEWLINES from the decoded payload, so a stdin feed ending in `\n` reaches
+# the child without it (NUL bytes — `check-ignore -z` separators — survive).
+# Every known consumer parses line-oriented stdin that tolerates a missing
+# final newline.
+PROTO_VERSION=6
 TMPDIR_AGENT=$(mktemp -d "${TMPDIR:-/tmp}/wsl-agent.XXXXXX")
 OUT_FILE="$TMPDIR_AGENT/out"
 ERR_FILE="$TMPDIR_AGENT/err"
@@ -254,16 +265,23 @@ run_capture() {
     fi
   fi
   CURRENT_ID=$req_id
+  # Protocol v6 stdin: when the EXEC dispatch staged a payload file, the child
+  # reads its bytes and sees EOF at the file's end; otherwise /dev/null keeps
+  # the child off the agent's own stdin (the host pipe).
+  spawn_in=/dev/null
+  if [ -n "${EXEC_STDIN:-}" ]; then
+    spawn_in=$EXEC_STDIN
+  fi
   # The inflight marker pauses the lease watchdog for this request and
   # refreshes the temp dir's mtime for the boot sweep; removing it after the
   # answer re-arms both.
   : >"$TMPDIR_AGENT/inflight"
   if [ "$mode" = subshell ]; then
-    ( "$@" ) >"$spawn_out" 2>"$spawn_err" &
+    ( "$@" ) >"$spawn_out" 2>"$spawn_err" <"$spawn_in" &
   elif [ -n "$SETSID" ]; then
-    ( exec setsid "$@" ) >"$spawn_out" 2>"$spawn_err" &
+    ( exec setsid "$@" ) >"$spawn_out" 2>"$spawn_err" <"$spawn_in" &
   else
-    "$@" >"$spawn_out" 2>"$spawn_err" &
+    "$@" >"$spawn_out" 2>"$spawn_err" <"$spawn_in" &
   fi
   CURRENT_PID=$!
   # Dispatched: the child exists now, so the host may arm its execution
@@ -675,7 +693,18 @@ while IFS= read -r line; do
       timeout_s=${rest%%|*}
       rest=${rest#*|}
       nargs=${rest%%|*}
-      maxout=${rest#*|}
+      rest=${rest#*|}
+      maxout=${rest%%|*}
+      # Protocol v6: an optional seventh field flags one stdin payload line
+      # after the argv words. Absent (a stale peer) or 0 keeps the v5 shape —
+      # the child reads an empty stdin and immediate EOF.
+      stdin_flag=0
+      case $rest in
+        *\|*) stdin_flag=${rest#*|} ;;
+        *) stdin_flag=0 ;;
+      esac
+      case $stdin_flag in ''|*[!01]*) stdin_flag=0 ;; esac
+      EXEC_STDIN=
       cwd=$(b64dec "$cwd_b64")
       if ! cd "$cwd" 2>/dev/null; then
         printf 'ERR|%s|cwd|%s\n' "$req_id" "$(printf '%s' "$cwd" | base64 | tr -d '\n')"
@@ -704,9 +733,20 @@ while IFS= read -r line; do
         printf 'ERR|%s|protocol|%s\n' "$req_id" "$(printf '%s' "an argv payload failed to decode" | base64 | tr -d '\n')"
         continue
       fi
+      if [ "$stdin_flag" = 1 ]; then
+        IFS= read -r stdin_b64 || exit 0
+        if ! b64dec_strict "$stdin_b64"; then
+          printf 'ERR|%s|protocol|%s\n' "$req_id" "$(printf '%s' "the stdin payload failed to decode" | base64 | tr -d '\n')"
+          continue
+        fi
+        EXEC_STDIN="$TMPDIR_AGENT/stdin.$req_id"
+        printf '%s' "$DEC" >"$EXEC_STDIN"
+      fi
       # Dispatched: run_capture prints the ACK once the child exists, so the
       # host's watchdog and USR1 cancel both target a real process.
       run_capture "$req_id" "$timeout_s" "$maxout" exec "$@"
+      [ -n "$EXEC_STDIN" ] && rm -f -- "$EXEC_STDIN"
+      EXEC_STDIN=
       ;;
     FS\|*)
       header=${line#FS|}

package/cordis.patch.yml

@@ -36,17 +36,20 @@
 #      `wsl.exe -d <distro> --cd <linux dir>` for the directory the Session
 #      supplies. Ordinary `spawn()` — every command, the host ripgrep search,
 #      every other consumer — reaches the shipped implementation untouched;
-#   2. the controller is given the one shell profile it should resolve, so the
-#      window's default is a distro shell rather than `cmd.exe` inside a UNC
-#      workspace. Its shell menu is reduced to that single entry on purpose:
-#      shell discovery also runs against the root provider and receives no
-#      directory, so offering host executables there would advertise shells this
-#      terminal never starts.
+#   2. the controller is given the composition's default shell profile (the
+#      distro shell, so a directory-less launch lands in the distro rather than
+#      `cmd.exe` inside a UNC workspace) plus host candidates. The default must
+#      stay static — the controller resolves it without a Session — but the
+#      candidates make the shell menu honest: `wsl.exe` dedupes into the
+#      default's `wsl` kind, and `powershell`/`cmd` are launches this terminal
+#      really starts (host sessions run PowerShell outright, and a manually
+#      selected shell is titled after itself — the sanctioned bridge over the
+#      fixed tab title, see docs/UPSTREAM-TERMINAL-TITLE.md).
 #
 # Consequence: a terminal's EXECUTION WORLD follows the Session — a WSL-folder
 # session runs the distro's shell, a Windows-folder session runs PowerShell in
-# its own directory (`hostSessions` on `subprocess-wsl`) — while the shell menu
-# and the tab title stay the composition's single `WSL` profile, which no
+# its own directory (`hostSessions` on `subprocess-wsl`) — while the DEFAULT
+# entry and its title stay the composition's single `WSL` profile, which no
 # Session identity reaches. The title that implies is documented in
 # docs/LIMITATIONS.md and bridged upstream in docs/UPSTREAM-TERMINAL-TITLE.md.
 # ═════════════════════════════════════════════════════════════════════════════
@@ -60,7 +63,10 @@
       path: wsl.exe
       name: WSL
       args: []
-    shellCandidates: []
+    shellCandidates:
+      - wsl.exe
+      - powershell
+      - cmd
 
 - insert:
     - id: subprocess-wsl

package/docs/ARCHITECTURE.md

@@ -109,9 +109,15 @@ So the layer disables the shipped `subprocess` row and inserts
 `dsh-plugin-wsl-env/subprocess` in its place at the app level. The subclass
 overrides two methods: `spawnTerminal` rewrites a `wsl.exe` launch into
 `wsl.exe -d <distro> --cd <linux dir>`, and `spawn()` rewrites two kinds of
-launches into the distro — the file-search tool's packaged ripgrep (agent-first,
-with the one-shot `wsl.exe --exec` handle as the fallback when the agent is out)
-and git snapshot commands. Both spawn decisions are pure coordinate functions
+launches into the distro — the file-search tool's packaged ripgrep and git
+snapshot commands (each agent-first on the warm resident — protocol v6 carries
+a git call's stdin, and a one-shot call costs ~230 ms of `wsl.exe` startup
+against the resident's ~2 ms — with the one-shot `wsl.exe --exec` handle as
+the fallback when the agent is out). When the HOST has no git,
+`resolveExecutable` answers git with a distro sentinel path, and the snapshot
+command's discovery call (`rev-parse --show-toplevel ...`) routes too, its
+absolute-path output translated back into UNC form — so full WSL change review
+works without Windows git. Both spawn decisions are pure coordinate functions
 (`lib/search-route.js`, `lib/git-route.js`); every other `spawn()` — including
 the one-shot fallback's own `wsl.exe -lc <command>` (the default agent path
 carries the command over the resident instead of spawning) — reaches the shipped
@@ -120,9 +126,11 @@ implementation untouched, as do the pwsh executor and the LSP host.
 The terminal's execution world follows the session (`hostSessions`, default on):
 a WSL-folder session runs the distro shell, a Windows-folder session runs
 `powershell.exe` in its own directory. What still follows the app configuration
-is the shell menu and the tab title, both derived from the composition's single
-`WSL` shell profile — so a host session's tab reads `WSL` over a PowerShell
-process. See [LIMITATIONS.md](LIMITATIONS.md) and
+is the shell menu's DEFAULT entry and its title, both derived from the
+composition's single `WSL` shell profile — so a new tab reads `WSL` whatever it
+runs, including a host session's PowerShell. The menu also lists host
+candidates (`powershell`, `cmd`; `wsl.exe` dedupes into the default), and a
+manually selected shell is titled after itself. See [LIMITATIONS.md](LIMITATIONS.md) and
 [UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md).
 
 ## Path coordinates

package/docs/CONFIGURATION.md

@@ -154,6 +154,27 @@ With `agent: true`, captured output is limited inside the distro and no spill
 file is written. `maxSpillBytes` and `graceMs` apply when `agent: false` or
 when the resident agent is unavailable and execution uses one-shot `wsl.exe`.
 
+### zsh/fnm recipe for model-run commands
+
+Commands run as `<shell> -lc`, so `~/.zshrc` is never read — see
+[LIMITATIONS](LIMITATIONS.md#shell-startup-semantics-wsl-shell) for why. Put
+fnm's hook in `~/.zprofile` instead, with a fallback for the sandbox, where
+`/run` is read-only and fnm cannot create its multishell symlink directory:
+
+```zsh
+# ~/.zprofile — fnm for non-interactive login shells (mirrors the ~/.zshrc hook)
+path=("$HOME/.local/share/fnm" $path)  # the fnm binary itself
+_fnm_env="$(command -v fnm &>/dev/null && fnm env --shell zsh 2>/dev/null)" && eval "$_fnm_env"
+if [[ -z "${FNM_MULTISHELL_PATH:-}" || ! -e "${FNM_MULTISHELL_PATH}/bin/node" ]]; then
+  path=("$HOME/.local/share/fnm/aliases/default/bin" $path)  # sandbox fallback
+fi
+unset _fnm_env
+```
+
+Interactive terminals keep the hook in `~/.zshrc` and are unaffected; the
+`aliases/default` fallback only takes over where the multishell link cannot
+exist.
+
 ## Environment forwarding
 
 WSL imports a host environment variable only when its name is listed in

package/docs/LIMITATIONS.md

@@ -225,6 +225,34 @@ operations do not use the Windows-side 9p share. What to know about the substrat
   a separate case and is now reported as an error naming that directory, because
   `wsl.exe` would otherwise run the command in `/` and exit 0.
 
+## Shell startup semantics (`wsl-shell`)
+
+Commands run as `<shell> -lc <command>` — a login, **non-interactive** shell.
+The login flag is deliberate: it sources the profile scripts, which is what
+makes a version manager's PATH (nvm, cargo, pyenv) visible to model-run
+commands. Non-interactivity is equally deliberate: interactive startup files
+print prompts and plugin output into the streams the model reads, define
+aliases that shadow real executables, and can keep the shell alive after the
+command finishes. What follows from that split:
+
+- **`~/.zshrc` and `~/.bashrc` are never read.** A login shell sources
+  `/etc/profile` and the user's profile file — `~/.profile` or `~/.zprofile`
+  for bash and zsh — and nothing else. zsh's ecosystem convention of putting
+  every hook in `.zshrc` therefore leaves model-run commands without it: a
+  tool installed through an interactive-only hook exists in the user's
+  terminal and does not exist in the model's. Move machine-level PATH setup
+  (`eval "$(fnm env)"`, nvm, cargo) into `~/.zprofile` or `~/.zshenv`, which
+  login shells do read; keep prompt and completion plugins in `.zshrc`.
+- **The confined sandbox mounts `/run` read-only, so fnm's multishell PATH
+  cannot form there.** `fnm env` works by creating a per-shell symlink
+  directory under `/run/user/<uid>/fnm_multishells/`; inside `bwrap` that
+  creation fails, and with it the PATH entry `fnm env` exists to provide.
+  A profile that must work in both worlds should fall back to fnm's stable
+  alias directory when the multishell link did not materialize — see the
+  recipe in [Configuration](CONFIGURATION.md#zshfnm-recipe-for-model-run-commands).
+  The plugin does not relax the sandbox for this: a writable `/run` inside the
+  fence would be a real weakening of it, traded for one tool's convenience.
+
 ## Agent diagnostics
 
 - **The doctor's `agent.handshake` check probes a fresh resident, not the live
@@ -292,18 +320,31 @@ operations do not use the Windows-side 9p share. What to know about the substrat
 
 - Terminal routing is per-session by workspace coordinates (`subprocess-wsl.hostSessions`,
   default on): a WSL-folder session gets the distro shell, a Windows-folder session gets
-  `powershell.exe` in its own directory. The shell MENU remains the single configured
-  profile, and a directory-less launch still lands in the distro.
-- A host session's TAB TITLE still reads `WSL`, the composition's shell profile
-  name, over a PowerShell process. The controller titles a tab from that profile
-  before the provider rewrites the launch, and a plugin cannot correct it: a
-  patch layer asserts rather than renames a row's module, and the row's id is
-  load-bearing for the web composition (disabling it fails web boot with
-  "waiting for service: webTerminals"). The full account and the proposed
-  upstream change are in [UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md).
-  Meanwhile, double-click a tab's title to rename it, or add `shellCandidates`
-  to the `terminal-controller` row in your own profile layer — a manually
-  selected shell is titled after itself.
+  `powershell.exe` in its own directory. The shell MENU's default entry remains the
+  configured profile, and a directory-less launch still lands in the distro.
+- **The Windows-side git must trust the `\\wsl.localhost` share** (`safe.directory`),
+  or the change-review pipeline silently degrades: the discovery call answers
+  `fatal: detected dubious ownership`, the recorder falls back to
+  "git is unavailable", and changed-files cards never list a WSL workspace's
+  diffs. Remedy (one-time, Windows side):
+  `git config --global --add safe.directory "//wsl.localhost/*"`, then restart
+  the app (the resolution is memoized for the process lifetime). Host-side
+  (`C:\...`) workspaces are unaffected. A future doctor check could probe this
+  directly. The prerequisite is also OPTIONAL: on a machine without Windows
+  git the plugin resolves git to a distro sentinel and routes the discovery
+  call too, translating its output into UNC form — full WSL change review
+  with no Windows git and no whitelist.
+- A NEW tab's title still reads `WSL`, the composition's shell profile name, whatever
+  it runs — including a host session's PowerShell. The controller titles a tab from
+  that profile before the provider rewrites the launch, and a plugin cannot correct
+  the default: a patch layer asserts rather than renames a row's module, and the
+  row's id is load-bearing for the web composition (disabling it fails web boot with
+  "waiting for service: webTerminals"). The full account and the proposed upstream
+  change are in [UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md).
+  The plugin now ships host `shellCandidates` (`wsl.exe` dedupes into the default's
+  kind; `powershell`/`cmd` appear as themselves), and a manually selected shell is
+  titled after itself — pick PowerShell from the shell menu and the tab reads
+  `powershell`. Double-clicking a title to rename also works.
 - Distro terminals ARE reclaimed when idle — the observation is distro-side:
   each terminal is launched with a `DSH_TERMINAL_ID` marker, and the handle's
   `inspectActivity` counts the marked processes through the resident agent

package/docs/UPSTREAM-TERMINAL-TITLE.md

@@ -107,17 +107,15 @@ next touched:
 
 ## Workarounds until then
 
+- The plugin now ships the candidate list itself: `shellCandidates` is
+  `[wsl.exe, powershell, cmd]` in [`cordis.patch.yml`](../cordis.patch.yml),
+  with the `shell` block kept verbatim. `wsl.exe` dedupes into the default's
+  `wsl` kind; selecting `powershell` or `cmd` starts a shell the terminal
+  really launches (host sessions do outright) and titles the tab after itself.
+  Nothing remains for a user layer to add unless it wants different entries.
 - Double-click a tab's title to rename it (a shipped client feature; the
   controller's `rename` Remote API accepts 1–120 characters).
-- Re-declare the `terminal-controller` row in a user layer with a non-empty
-  `shellCandidates`: a manually selected shell is titled after itself. A patch
-  config replaces the whole config rather than deep-merging it
-  (`packages/boot/app-boot/src/config-schema/document.ts`), so the override has
-  to carry this plugin's `shell` block verbatim — `path: wsl.exe`, `name: WSL`,
-  `args: []` — or the terminal stops being a distro terminal. Expect the menu
-  to grow the host shells discovery finds on the root provider, which receives
-  no directory: executables this terminal never starts (the second bullet of
-  the GUI-terminal comment in [`cordis.patch.yml`](../cordis.patch.yml)).
-  [LIMITATIONS.md](LIMITATIONS.md) still carries the older one-line form of
-  this tip, which drops the `shell` block; the version above is the one that
-  works.
+
+Both cover only manually selected shells. The DEFAULT entry — what a new tab
+gets before anyone chooses — is still titled from the static profile, which is
+exactly the gap the upstream change closes.

package/lib/agent-exec.d.ts

@@ -40,6 +40,11 @@ export interface AgentExecRequest {
     env?: Record<string, string>;
     /** Per-stream capture ceiling. */
     maxOutputBytes?: number;
+    /**
+     * The child's entire stdin (protocol v6); the child sees EOF at the
+     * payload's end. Omitted or empty keeps the v5 shape.
+     */
+    stdin?: Uint8Array;
     /** The caller's cancellation. */
     signal?: AbortSignal;
 }

package/lib/agent-protocol.d.ts

@@ -14,7 +14,7 @@
  * @module dsh-plugin-wsl/agent-protocol
  */
 /** The protocol version this host side speaks; the agent must match. */
-export declare const PROTOCOL_VERSION = 5;
+export declare const PROTOCOL_VERSION = 6;
 /**
  * Upper bound on one `read` op's payload, set by the HOST looping over windowed
  * requests. Keeping each frame's decoded payload here means the agent's RES
@@ -65,17 +65,30 @@ export interface ExecFrameRequest {
      * default) keeps the historical unbounded capture.
      */
     maxOutputBytes?: number;
+    /**
+     * The child's entire stdin, delivered before the first read. Protocol v6:
+     * when present the EXEC header gains a `1` seventh field and one extra
+     * base64 line follows the argv words; the agent feeds those bytes to the
+     * child and closes its stdin (the child sees EOF at the payload's end). The
+     * payload rides one protocol line, so it is bounded by `MAX_FRAME_BYTES` —
+     * the shape of every known consumer (`git check-ignore --stdin` pathspecs),
+     * none of which streams an unbounded feed. Absent or empty means the child
+     * reads an empty stdin and immediate EOF, exactly the v5 behaviour.
+     */
+    stdin?: Uint8Array;
 }
 /**
  * Build the request lines for one EXEC frame: a header line naming the cwd,
- * the whole-request timeout in whole seconds (0 = none), the argv word count
- * and the per-stream output capture budget in bytes (0 = unlimited), followed
- * by one base64 line per argv word.
+ * the whole-request timeout in whole seconds (0 = none), the argv word count,
+ * the per-stream output capture budget in bytes (0 = unlimited) and — since
+ * protocol v6 — the stdin flag (1 when a payload line follows the argv
+ * words), followed by one base64 line per argv word and, when flagged, one
+ * base64 stdin payload line.
  *
  * @param request - the execution request.
  * @returns the lines to write to the agent's stdin, in order.
  */
-export declare function encodeExecFrame({ id, cwd, argv, timeoutMs, maxOutputBytes }: ExecFrameRequest): string[];
+export declare function encodeExecFrame({ id, cwd, argv, timeoutMs, maxOutputBytes, stdin }: ExecFrameRequest): string[];
 /**
  * Build a SETENV request line. Note the agent's decode strips trailing
  * newlines from the value — the same leniency the shell itself applies.

package/lib/agent-protocol.js

@@ -14,7 +14,7 @@
  * @module dsh-plugin-wsl/agent-protocol
  */
 /** The protocol version this host side speaks; the agent must match. */
-export const PROTOCOL_VERSION = 5;
+export const PROTOCOL_VERSION = 6;
 /**
  * Upper bound on one `read` op's payload, set by the HOST looping over windowed
  * requests. Keeping each frame's decoded payload here means the agent's RES
@@ -54,20 +54,25 @@ export function decodeB64(value) {
 }
 /**
  * Build the request lines for one EXEC frame: a header line naming the cwd,
- * the whole-request timeout in whole seconds (0 = none), the argv word count
- * and the per-stream output capture budget in bytes (0 = unlimited), followed
- * by one base64 line per argv word.
+ * the whole-request timeout in whole seconds (0 = none), the argv word count,
+ * the per-stream output capture budget in bytes (0 = unlimited) and — since
+ * protocol v6 — the stdin flag (1 when a payload line follows the argv
+ * words), followed by one base64 line per argv word and, when flagged, one
+ * base64 stdin payload line.
  *
  * @param request - the execution request.
  * @returns the lines to write to the agent's stdin, in order.
  */
-export function encodeExecFrame({ id, cwd, argv, timeoutMs = 0, maxOutputBytes = 0 }) {
+export function encodeExecFrame({ id, cwd, argv, timeoutMs = 0, maxOutputBytes = 0, stdin }) {
     const timeoutSeconds = timeoutMs > 0 ? Math.ceil(timeoutMs / 1000) : 0;
     const cap = maxOutputBytes > 0 ? Math.floor(maxOutputBytes) : 0;
+    const hasStdin = stdin !== undefined && stdin.length > 0;
     const lines = [
-        `EXEC|${id}|${encodeB64(cwd)}|${timeoutSeconds}|${argv.length}|${cap}`,
+        `EXEC|${id}|${encodeB64(cwd)}|${timeoutSeconds}|${argv.length}|${cap}|${hasStdin ? 1 : 0}`,
         ...argv.map((word) => encodeB64(word)),
     ];
+    if (hasStdin)
+        lines.push(encodeB64(stdin));
     return lines;
 }
 /**

package/lib/agent.d.ts

@@ -431,7 +431,7 @@ export declare class WslAgent {
      * @returns the settled result.
      * @throws {AgentUnavailableError} when the agent is out for this process.
      */
-    exec({ cwd, argv, timeoutMs, maxOutputBytes, env, signal }: {
+    exec({ cwd, argv, timeoutMs, maxOutputBytes, env, stdin, signal }: {
         /** Linux path to run in. */
         cwd: string;
         /** The argv, already bwrap-wrapped when the caller confines. */
@@ -453,6 +453,14 @@ export declare class WslAgent {
          * keeps the unbounded capture.
          */
         maxOutputBytes?: number;
+        /**
+         * The child's entire stdin, delivered before its first read (protocol
+         * v6); the child sees EOF at the payload's end. Omitted or empty keeps
+         * the v5 shape — an empty stdin and immediate EOF. Note the shell agent
+         * decodes the payload through command substitution, which strips
+         * trailing newlines; the native agent delivers the bytes verbatim.
+         */
+        stdin?: Uint8Array;
         /** Cancels the request, sending KILL if it was already dispatched. */
         signal?: AbortSignal;
     }): Promise<{

package/lib/agent.js

@@ -780,7 +780,7 @@ export class WslAgent {
      * @returns the settled result.
      * @throws {AgentUnavailableError} when the agent is out for this process.
      */
-    async exec({ cwd, argv, timeoutMs = 0, maxOutputBytes = 0, env, signal }) {
+    async exec({ cwd, argv, timeoutMs = 0, maxOutputBytes = 0, env, stdin, signal }) {
         const assignments = Object.entries(env ?? {}).map(([key, value]) => {
             if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || value.includes("\0")) {
                 throw new Error(`invalid environment variable: ${key}`);
@@ -793,7 +793,7 @@ export class WslAgent {
         const id = `r${this.nextRequestId++}`;
         const commandArgv = argv[0]?.includes("=") ? ["/bin/sh", "-c", "exec \"$@\"", "env", ...argv] : argv;
         const requestArgv = assignments.length > 0 ? ["env", "--", ...assignments, ...commandArgv] : argv;
-        const lines = encodeExecFrame({ id, cwd, argv: requestArgv, timeoutMs, maxOutputBytes });
+        const lines = encodeExecFrame({ id, cwd, argv: requestArgv, timeoutMs, maxOutputBytes, stdin });
         return new Promise((resolve, reject) => {
             this.track({ id, kind: "exec", lines, resolve, reject, timeoutMs, signal });
         });

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

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,7 +1,7 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.16.0",
-  "description": "在 WSL 的 Linux 实例中打开项目工作区，在对应 Linux 空间中进行命令执行、运行 shell 脚本和文件访问，以获得全套 Linux Shell 工具链收益，并通过 bubblewrap 对命令进行沙箱隔离",
+  "version": "0.17.0",
+  "description": "\u5728 WSL \u7684 Linux \u5b9e\u4f8b\u4e2d\u6253\u5f00\u9879\u76ee\u5de5\u4f5c\u533a\uff0c\u5728\u5bf9\u5e94 Linux \u7a7a\u95f4\u4e2d\u8fdb\u884c\u547d\u4ee4\u6267\u884c\u3001\u8fd0\u884c shell \u811a\u672c\u548c\u6587\u4ef6\u8bbf\u95ee\uff0c\u4ee5\u83b7\u5f97\u5168\u5957 Linux Shell \u5de5\u5177\u94fe\u6536\u76ca\uff0c\u5e76\u901a\u8fc7 bubblewrap \u5bf9\u547d\u4ee4\u8fdb\u884c\u6c99\u7bb1\u9694\u79bb",
   "keywords": [
     "deepseek-harness",
     "dsh",

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("/")) {