dsh-plugin-wsl-env 0.16.0 → 0.17.1

package/docs/LIMITATIONS.zh.md

@@ -0,0 +1,161 @@
+# Limitations
+
+_本文是 [LIMITATIONS](LIMITATIONS.md) 的中文译本，以英文版为准。_
+
+插件不做什么，以及为什么。写进文档的限制是设计边界；
+没写进文档的迟早会变成 bug 报告。每一条都说明限制本身和补救方法；
+推理过程在 [ARCHITECTURE.md](ARCHITECTURE.md) 及其链接的文档中。
+
+## 文件系统 substrate（`wsl-fs`）
+
+只有一个 substrate：发行版内的常驻 agent（发行版文件用 ext4）。已退役的
+Windows 侧 share 后端（`substrate: "share"`）在启动时被拒绝；WSL 路由的
+操作永远不会走 9p 共享。
+
+- **新建文件以 0600 权限发布。** 覆盖与编辑保留原有权限位；
+  新文件需要可执行时请 `chmod`。
+- **agent 不在时，文件操作关闭（fail closed）** —— 报 `FS_IO_ERROR`，指明
+  substrate，并附带恢复路径。一次崩溃可用一次重建；重建耗尽后进入有界复活
+  （2/4/8 s）；三次死亡则永久退出，直到应用重启。没有回退 I/O——这是有意为之。
+- **变更守卫不是原子的比较并交换。** 创建使用不可替换的 link；覆盖在 rename 前
+  会重新校验版本。不匹配时返回 `FS_STALE_VERSION`，但检查与 rename 之间发生的
+  变更仍可能被覆盖。
+- **被取消的写入结果可能是未知的** —— 重试前先检查文件。
+- **写入成功不等于崩溃持久。** 被暂存的文件会 sync，但所在目录不会：
+  断电可能丢失该目录项。
+- **含反斜杠的 Linux 文件名无法被寻址** —— 反斜杠是 UNC 分隔符，
+  `a\b.ts` 会往返成 `a/b.ts`。请把文件名改掉，不要用反斜杠；
+  这是坐标系自身的限制。
+- **受限写入运行在各自的 bwrap 约束常驻 agent 上** —— 由内核强制，
+  工作区之外以 `FS_SANDBOX_DENIED` 拒绝。代价：需要 `bubblewrap`；
+  策略变更要付出一次 agent 启动；授予 `/tmp` 的写入落在发行版真实的
+  `/tmp` 中。
+- **`glob`/`grep` 使用发行版的 rg**；没有 rg 的发行版搜索失败
+  （退出码 127）。安装：`wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap
+  git ripgrep inotify-tools`（或检测到的包管理族对应的写法）。`--install` 只在
+  缺少 `bubblewrap` 时才执行安装。
+- **`watch()` 是粗粒度失效，不是逐文件通知**：inotify 事件合并到 0.5 s，
+  否则使用 `find -newer` 轮询循环。轮询路径会遗漏原地的 `cp -p`，以及恢复
+  较旧 mtime 的 `tar -x`；FILE 目标监视的是 `mtime:size` 指纹。从 Windows
+  侧做 9p 监视仍然不支持。
+- **`sessionSandbox: false` 时，受限命令的 `/tmp` 与写入工具的 `/tmp`
+  不同** —— 请通过会话工作区交接文件。随包 preset（`sessionSandbox: true`）
+  共享同一个真实 `/tmp`，不存在这种分裂。
+- `editText` 在写回之前把整个文件读进内存。
+- 发行版在请求进行中死亡，会耗尽常驻 agent 的唯一一次重建；
+  仍未恢复时，常驻 agent 将保持不可用，直到应用重启。
+
+## GUI 的 workspace-files 服务
+
+- GUI 文件树和预览使用随包的 `workspace-files` 行，通过被路由的根文件系统
+  读取 WSL 路径——这是有意不替换的（服务端单方面接管会丢掉侧边栏预览
+  所依赖的浏览器 `file` 资源提供者）。
+- **预期多出几轮往返**（每次 listDir/stat/分页约 4-6 次；实测 p95：
+  `stat` 2.7 ms、`listDir` 5.1 ms、1 MiB 读取 63.5 ms/MiB —— 2026-10-19，
+  [探针](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/gui-preview.sh)）。
+  模型自己的文件操作不受影响。
+- `fs-routing` 是接缝：禁用它即可恢复宿主 9p 支撑的根文件系统。
+  随包行的上限可以在 `workspace-files` 行上覆盖。
+
+## `@` 补全
+
+- **`@` 引用走 9p 共享**（在已探针的目录树上比 ext4 慢约 56 倍，
+  2026-10-19）。发行版侧的遍历已经写好，但尚未挂载——它需要上游的
+  `FileReferenceTraversal` 接缝：
+  [UPSTREAM-FILE-REFERENCE-SEAM.md](UPSTREAM-FILE-REFERENCE-SEAM.md)。
+
+## 沙箱
+
+- **一次性回退路径只有宿主截止时间** —— `wsl.exe` 被杀时不会把 kill 传进
+  发行版，因此 Linux 进程树可能比调用活得更久。长命令建议
+  `agent: true` 并使用会话 runtime。
+- **批量读取按发行版共享一个原生 agent**（16 个并发调用 2.4-4.1 ms；
+  第一次调用要付出约 70 ms 的准备）。
+- **aarch64 只在 CI 中于 qemu 下运行**（身边没有 Windows-on-ARM 机器——
+  [COMPATIBILITY.md](COMPATIBILITY.md#scope-decisions)）。`auto` 仍会选择
+  包内二进制；`native` 在准备失败时拒绝；`shell` 强制使用 shell agent。
+- **会话 runtime 需要 systemd 和带 linger 的 user manager** —— 否则在
+  第一条命令时被拒绝并给出补救方法；`sessionSandbox: false` 保留旧的
+  按命令形态。应用硬崩溃可能留下过期的 `dsh-wsl-*.scope`；预检会在下一个
+  WSL 会话时清扫过期 scope（从不清扫其他活跃会话的）。
+- **沙箱不管辖 WSL interop** —— 上报为 `enforcement: partial`。
+  `maskWindowsDrive` 收窄 `/mnt` 但不是关闭；发行版级 `wsl.conf` 中的
+  `[interop] enabled=false` 需要另行配置。
+  [ARCHITECTURE.md](ARCHITECTURE.md#reported-enforcement)。
+- **必须安装 `bubblewrap`**，否则两个提供者都会带着安装命令失败；
+  会话启动预检会以建议性警告的形式给出同样的文本。
+- 会话中途被删除的工作区目录会以 runner 错误失败；插件不会重建它。
+  配置的 `cwd` 不存在时，报错会指明该目录。
+
+## shell 启动语义（`wsl-shell`）
+
+命令以 `<shell> -lc <command>` 运行——登录 shell（会 source profile 脚本，
+因此版本管理器可用）且**非交互**（模型的输出流中没有提示符/插件输出）。
+
+- **`~/.zshrc` / `~/.bashrc` 永远不会被读取。** 把机器级的 PATH 设置
+  （`fnm`、nvm、cargo）移进 `~/.zprofile` 或 `~/.zshenv`；提示符和补全
+  留在 rc 文件里。
+- **fnm 的 multishell PATH 在沙箱内无法形成**（`/run` 只读）——
+  使用 [Configuration](CONFIGURATION.md#zshfnm-recipe-for-model-run-commands)
+  中的回退配方。
+
+## Agent 诊断
+
+- **doctor 的 `agent.handshake` 探测的是一个新起的常驻 agent**，而不是
+  在跑的那个——运行中常驻 agent 的 `lastError` 留在应用日志里
+  （进程内可通过 `WslAgent.status()` 查看）。
+- **`dsh-wsl-*.scope` 计数是某一时刻的快照**；`--fix` 会执行预检的清扫。
+- **doctor 的 `git.win-safe` 探针通过 interop 的 `git.exe` 报告 Windows git
+  的信任状态** —— 装了 Windows git 时，WSL 变更审查需要那份
+  `safe.directory` 白名单（见下文"终端"）。
+
+## 会话启动建议
+
+- **DSH 0.2.1 没有会话 UI 通知接缝。** `wsl-preflight` 的失败进入宿主日志
+  和会话的 runtime context（下次组装时对模型可见）——仅供参考，从不安装、
+  从不取消。对上游的请求见：
+  [UPSTREAM-SESSION-NOTICE.md](UPSTREAM-SESSION-NOTICE.md)。
+- **runtime context 条目是重复的快照，不是可关闭的通知。**
+  移除 `wsl-preflight` 行即可让该探针完全静音。
+
+## 端口
+
+- **端口轮询让常驻 agent 在每个活跃发行版上永久保温**
+  （10 s 刷新）。把 `portsRefreshMs` 调到超过 agent 的空闲超时即可恢复
+  空闲关停，代价是端口事实更陈旧。
+
+## 目录选择器
+
+- 发行版层级从发行版内部一次往返完成列举（NUL 分隔，因此含换行的
+  目录名也能精确列出——WSL-306）；常驻 agent 不在时用一次性的
+  `wsl.exe --exec find`。
+
+## 终端
+
+- 终端路由按会话的工作区坐标进行：WSL 文件夹会话获得发行版 shell，
+  Windows 文件夹会话在其自身目录获得 `powershell.exe`。shell 菜单的
+  默认条目保持为配置的 profile；不带目录的启动落在发行版内。
+- **Windows git 必须信任该共享**（`safe.directory`），否则 WSL 工作区的
+  changed-files 卡片会无声消失（发现调用返回 `detected dubious ownership`）。
+  Windows 上的一次性补救：
+  `git config --global --add safe.directory "//wsl.localhost/*"`，然后重启
+  应用。两个替代方案：doctor 的 `git.win-safe` 探针可报告该状态；而
+  **没有** Windows git 的机器什么都不用做——提供者把发现请求路由进
+  发行版，并把输出转写成 UNC 形式。
+- **NEW 标签页的标题显示 `WSL`**，无论它实际运行什么——控制器在提供者
+  改写启动命令之前就按 composition 的 profile 命名了，而插件无法纠正
+  这个默认值（[UPSTREAM-TERMINAL-TITLE.md](UPSTREAM-TERMINAL-TITLE.md)）。
+  菜单附带宿主候选（`powershell`、`cmd`）：手动选择的 shell 会以自身命名；
+  双击重命名也可行。
+- **发行版终端空闲时确实会被回收** —— 通过常驻 agent 对被标记的进程计数
+  （提示符处恰好一个进程 = `idle`；嵌套 shell 或启动文件拉起的
+  `ssh-agent` 按设计读作 `busy`）。阈值是控制器的
+  `unattendedTimeoutMs`（2 h）。`terminalIdleReclaim: false` 恢复手动关闭。
+  Windows 文件夹的宿主终端保持随包的不回收行为。
+
+## 宿主的"在应用中打开"
+
+- **从"在应用中打开"启动 VS Code 可能独立于本插件而失败** ——
+  宿主带着 `ELECTRON_RUN_AS_NODE=1` 运行，启动器会继承它，于是
+  `Code.exe` 以 Node 身份启动并以退出码 1 结束。不属于本仓库管：
+  [UPSTREAM-OPEN-IN-APP.md](UPSTREAM-OPEN-IN-APP.md)。

package/docs/QUICKSTART.md

@@ -1,5 +1,7 @@
 # Quickstart
 
+*A Chinese translation lives at [QUICKSTART.zh](QUICKSTART.zh.md); the English version is authoritative.*
+
 Steps from a Windows + WSL 2 machine to a working WSL session.
 This page is the entry point; every claim links to the document that owns it.
 

package/docs/QUICKSTART.zh.md

@@ -0,0 +1,168 @@
+# Quickstart
+
+_本文是 [QUICKSTART](QUICKSTART.md) 的中文译本，以英文版为准。_
+
+从一台 Windows + WSL 2 机器到可用的 WSL 会话，只需以下步骤。
+本页是入口；每条说明都链接到负责该主题的文档。
+
+## 1. 前置条件
+
+| 需求 | 如何检查 | 缺失时 |
+|---|---|---|
+| Windows 10/11，启用 WSL 2 | `wsl.exe -l -v` 显示 `VERSION 2` | `wsl.exe --install` |
+| 一个发行版 | 上面列表中有一行 | `wsl.exe --install -d Ubuntu` |
+| `bubblewrap` | `wsl.exe -d <distro> -- which bwrap` | `wsl.exe -d <distro> -u root -- apt-get install -y bubblewrap` |
+| systemd + Linger（会话 runtime 需要） | `node <plugin>/scripts/doctor.mjs`（已安装）或 `pnpm run doctor`（检出目录） | 在 `/etc/wsl.conf` 设置 `[boot] systemd=true`，`wsl --shutdown`，然后 `loginctl enable-linger "$USER"`；或设置 `sessionSandbox: auto`/`false` |
+| Node `^22.19.0` 或 `>=24.0.0` | 仅源码/开发工作需要 | 使用已发布的插件时，发行版内不需要 Node |
+
+doctor（`scripts/doctor.mjs`，或在检出目录中运行 `pnpm run doctor`）会检查
+环境并针对检测到的失败打印补救方法。发行版的 WSL 版本请单独用
+`wsl.exe -l -v` 确认。doctor 默认只读，除非传入 `--fix`（清理过期 scope）或
+`--fix --install`（安装软件包，需确认）。
+
+## 2. 安装
+
+在一个可以使用 DSH CLI 的 Windows PowerShell 中：
+
+```powershell
+dsh plugin --profile <profile> add dsh-plugin-wsl-env
+# 若解析到旧版本（发布当天的元数据缓存），显式指定：
+# dsh plugin --profile <profile> add dsh-plugin-wsl-env@<latest>
+dsh --profile <profile> --dump-config      # 输出中必须包含插件的行
+```
+
+如果 profile 已覆盖 preset，请保持覆盖为完整的
+`preset-wsl` 块——当某个层直接按 id 指向 `wsl-shell`/`wsl-fs` 时，
+`pnpm run preset --check <patch>` 会明确报错。
+
+## 3. 打开 WSL 工作区
+
+在 GUI 中，通过选择器打开文件夹（`\\wsl.localhost\<distro>\home\<you>\proj`），
+或直接打开 UNC 路径。会话的命令、文件工具、终端和预览
+都在该发行版中运行；打开 Windows 文件夹则保留正常的 Windows 环境。
+两个发行版可以同时打开，各自拥有自己的环境。
+
+### 在 VS Code 中打开工作区（Remote-WSL）
+
+把 WSL 文件夹当作 Windows UNC 共享打开也可行，但属于降级模式：
+文件走 9p，终端是 PowerShell，扩展运行在 Windows 上。完整的
+集成方式是 VS Code 的 Remote-WSL——server 运行在发行版内，集成终端
+是发行版的 shell，文件操作直接落在本地 ext4 上：
+
+```powershell
+# from the plugin checkout:
+scripts/open-wsl-vscode.ps1 -Path "\\wsl.localhost\ubuntu\home\me\proj"
+# or by hand:
+code --folder-uri "vscode-remote://wsl+ubuntu/home/me/proj"
+```
+
+要求 PATH 上有 `code` shim（VS Code 安装器会添加），以及
+Remote-WSL 扩展。
+
+![The directory picker listing a WSL distro's folders](screenshots/picker.png)
+
+终端面板运行在同一个发行版中——`uname -a` 返回的是
+发行版的内核，而不是 Windows 的：
+
+![The GUI terminal running inside the distro](screenshots/terminal.png)
+
+侧边栏的预览也能就地渲染 WSL 文件：
+
+![The GUI preview rendering a WSL file](screenshots/preview.png)
+
+## 4. 验证
+
+让模型执行一条命令，例如 `pwd && uname -a`。预期结果：Linux 路径和
+发行版内核。如果第一条命令失败，错误信息会给出补救方法；
+[doctor](CONFIGURATION.md) 和[故障排查表](../README.md#troubleshooting)
+覆盖了常见情况。
+
+下面的探针会实时运行随包的、由内核强制的 bwrap profile——
+工作区内的写入生效，测试性的区外写入被以 `EROFS` 拒绝，
+严格 profile 则把 `/mnt` 完全隐藏
+（[`test/probe/sandbox.sh`](https://github.com/Big-Dao/dsh-plugin-wsl-env/blob/main/test/probe/sandbox.sh)）：
+
+这是部分隔离，不是 Windows 安全边界：Windows interop
+仍可启动 `/mnt` 之外的可执行文件。见 [LIMITATIONS.md](LIMITATIONS.md)。
+
+![The sandbox probe: every expectation holds, the kernel refuses what the profile does not grant](screenshots/sandbox.png)
+
+## 配方
+
+命令在模型的会话中运行，位于发行版内，从工作区根目录出发。
+
+### Node / TypeScript
+
+```bash
+node -v && pnpm -v
+pnpm install
+pnpm test
+pnpm dev            # a dev server survives the command that started it with sessionSandbox: true
+```
+
+快照成功后（默认每 10 s 刷新一次），server 的端口可能出现在 `DSH_WSL_PORTS`
+中；从 Windows 通过 `http://localhost:<port>` 访问转发的端口。
+
+### Python
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+python -m pytest
+```
+
+使用发行版的解释器，而不是 Windows 的：会话的 `python3` 是
+发行版 `PATH` 上的那个（包括 pyenv/conda shim）。
+
+### Rust
+
+```bash
+cargo build --release
+cargo test
+```
+
+target 会针对发行版的架构（x86_64 或 aarch64）原生编译；
+不要复用 Windows 的 `target/` 目录。
+
+### Go
+
+```bash
+go build ./...
+go test ./...
+```
+
+模块缓存通常位于发行版用户的 `$GOPATH` 下；其实际位置和底层文件系统
+取决于 Go 环境和挂载情况。
+
+### Monorepo
+
+把仓库根目录作为工作区打开。每个包的命令都在同一个发行版中运行；
+`pnpm -r`、`turbo`、`nx` 和 `make` 看到的是同一个 Linux 文件系统。
+当 `inotifywait` 可用时，无上限目录的文件监视使用 inotify；
+否则回退到轮询。如果遗漏了某次变更，见
+[CONFIGURATION.md](CONFIGURATION.md) 中的监视器边界。
+
+## 兼容性
+
+诚实的现状，不是承诺。"已探针"指本仓库记录了一次真机运行；
+"目标"指设计上支持，但这条腿尚未在这里执行过。
+
+| 层级 | 配置 | 状态 |
+|---|---|---|
+| 1 | Ubuntu / Debian，systemd，x86_64 | 已探针。Debian 的 harness 级探针针对 `wslfs-debian` profile 通过（2026-10-26）。 |
+| 2 | Fedora、openSUSE、Arch、Alpine；aarch64 原生 agent | 发行版矩阵见 [COMPATIBILITY.md](COMPATIBILITY.md)。aarch64 的 18 项检查在 CI 中于 qemu 下运行；物理 aarch64 WSL 不在范围内。 |
+| 不支持 | WSL 1、Linux/macOS 宿主、无 WSL 2 的 Windows | 不支持；插件依附于 `wsl.exe` |
+
+设置 `sessionSandbox: auto` 时，没有 systemd/Linger 的发行版仍能获得
+按命令的 `bubblewrap` 沙箱，且结果会报告更窄的 scope；
+`true` 则直接拒绝。沙箱取舍见
+[CONFIGURATION.md](CONFIGURATION.md#sandbox-and-preflight)，实测延迟见
+[PERFORMANCE.md](PERFORMANCE.md)。
+
+## 演示
+
+上面的截图展示了选择器、终端、预览和沙箱探针。
+目前还没有 GIF。[故障排查表](../README.md#troubleshooting)
+和探针输出（`pnpm run probe:sandbox`、`pnpm run probe:gui-preview`）
+提供了可复现的证据；其余演示工作在
+[ROADMAP-1.0.md](ROADMAP-1.0.md#wsl-302--discoverability-and-docs-entry) 中跟踪。

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;