dsh-plugin-wsl-env 0.6.0 → 0.7.3

package/docs/LIMITATIONS.md

@@ -3,35 +3,31 @@
 What the plugin does not do, and why. A limitation that is documented is a design
 boundary; one that is not is a bug report waiting to happen.
 
-## The filesystem substrate (`wsl-fs` `substrate`)
+## The filesystem substrate (`wsl-fs`)
 
-`substrate: "agent"` (the default) serves the file tools through the resident
-in-distro agent, on ext4. `substrate: "share"` is the opt-out: the Windows-side
-host stack over the distro's 9p share. What differs:
+The file tools run on one substrate: the resident in-distro agent, on ext4 —
+reads, writes and identities happen where the files live. The former
+Windows-side share backend (`substrate: "share"`) is retired: a profile still
+carrying the value is refused at boot with the migration, and no file tool
+crosses the 9p share. What to know about the one substrate there is:
 
-- **A new file publishes with mode 0600 on the agent substrate.** That is the
-  host backend's own POSIX publication semantics (a private 0600 staging file,
-  renamed into place), which a Linux-host DSH session has always had. The share
-  substrate was the outlier: the share drops mode sets, so new files took the
-  distro's umask default (0644). Overwrites and edits keep the original bits on
-  both substrates. Run `chmod` (or ask the model to) when a new file must be
-  executable.
-- **There is no silent fallback to the share.** When the agent substrate's
-  resident process is out — the distro stopped, or the agent crashed past its
-  one rebuild — file operations fail with `FS_IO_ERROR` naming the substrate,
-  rather than quietly degrading to share semantics that cannot follow symlinks
-  or keep mode bits. The share substrate dies with the distro anyway; the
-  agent only adds its own failure mode, which is the one honest way to fail.
-  The failure message names the opt-out: set `substrate: "share"` in the
-  provider config to keep working on the Windows-side share while the agent
-  is out.
+- **A new file publishes with mode 0600.** That is the host backend's own POSIX
+  publication semantics (a private 0600 staging file, renamed into place), which
+  a Linux-host DSH session has always had; the share dropped mode sets and took
+  the umask default instead, and that behaviour is gone with the share.
+  Overwrites and edits keep the original bits. Run `chmod` (or ask the model to)
+  when a new file must be executable.
+- **When the agent is out, file operations fail closed.** The distro stopped, or
+  the resident crashed past its one rebuild: `FS_IO_ERROR` naming the substrate,
+  with the recovery path in the message. There is no fallback I/O to degrade
+  into — deliberately; the old failure message pointed at the share, and the
+  share is what this plugin exists to keep the model off.
 - **The mutation guard survives to the write.** `createIfAbsent` publishes with
   a no-replace link inside the distro, which closes the check-then-write window
   for creates outright. An overwrite or edit carries the version it was based
   on into the write op, and the agent re-verifies it against a fresh stat one
   syscall before the rename: a concurrent writer wins and the stale write
-  refuses with `FS_STALE_VERSION`. That narrows the share's window from a host
-  round trip to kernel-adjacent — the residual stat-then-rename pair is the
+  refuses with `FS_STALE_VERSION`. The residual stat-then-rename pair is the
   same sliver a Linux-host session's own rename has.
 - **Stage two routes mutations through a confined resident.** A write or edit
   under a confined policy runs on its own long-lived agent, spawned inside the
@@ -45,19 +41,15 @@ host stack over the distro's 9p share. What differs:
   the distro's `/tmp` lands in the confined mount's tmpfs, not the real `/tmp`
   — the same hand-off rule as the commands' `/tmp`: pass files through the
   session workspace.
-- **`resolveSymlinks` is not consulted.** The share cannot traverse Linux
-  symlinks, so the share substrate retries missing reads through the distro's
-  canonical path; the agent substrate never misses them, so the config key has
-  no effect there.
-- **`glob` and `grep` are unchanged on both substrates.** They are tool-layer
-  searches running the packaged Windows ripgrep against the share — correct
-  results, slow, and `.gitignore` interpreted with Windows rules. Bringing them
-  in-distro is future work, not part of the substrate switch.
-- **`watch()` is the same poll loop on both substrates** (a `find -newer` scan
-  inside the distro), so the coarse-invalidation caveats below apply equally.
-  An inotify backend is planned, not shipped.
-
-Everything below applies to the share substrate unless it says otherwise.
+- **`glob` and `grep` run the distro's own rg** (`lib/search-route.js`): the
+  tool's arguments are forwarded verbatim, so results, output format and exit
+  codes are rg's own — at ext4 speed, with the distro's `.gitignore` rules.
+  A distro without rg surfaces rg's own "command not found" (exit 127);
+  `npm run bootstrap -- <distro> --install` installs it. A search whose
+  directory is a Windows folder keeps the host binary, which is native there.
+- **`watch()` is one poll loop** (a `find -newer` scan inside the distro), so
+  the coarse-invalidation caveats below apply. An inotify backend is planned,
+  not shipped.
 
 - **The sandbox does not govern WSL interop.** A confined command can still run a
   Windows program, which escapes the Linux-side boundary. The plugin reports this as
@@ -77,35 +69,27 @@ Everything below applies to the share substrate unless it says otherwise.
   while the file tools' fence grants the distro's *real* `/tmp`. Both are writable, so
   neither side is refused, but a file the write tool puts in `/tmp` is invisible to
   `bash` and vice versa. Hand a file between them through the session workspace.
-- A distro that is stopped or unregistered while the app runs leaves the UNC share
-  unreachable: the shell tools report `wsl.exe`'s `WSL_E_*` code with the reason, but
-  the file tools can only report a file-level error, because the share itself is
-  gone.
+- A distro that is stopped or unregistered while the app runs takes the file
+  tools' substrate with it: reads and writes report the substrate-unavailable
+  error naming the cause, and recover on the next call once the distro starts.
 - `workspace-write` binds the workspace root as writable, and bubblewrap refuses a
   bind whose source directory does not exist, so a session whose workspace directory was
   deleted fails with a runner error; the plugin does not recreate it. A workdir that
   does not exist — a configured `cwd` pointing at a deleted directory, for instance — is
   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.
-- New files get the distro's umask default (0644). A `chmod` from the Windows side on
-  a share path is silently ignored; overwrites and edits keep the original permission
-  bits. Run `chmod +x` inside the distro when you need an executable.
-- The check before a write is "check, then write", which is not atomic. This backend
-  checks the caller's guard itself, because the Windows backend publishes a guarded
-  new file with a hard link, and the share does not support hard links. This is the
-  race that `dsh-fs-sandbox` already documents — and one reason the share substrate
-  is the documented FALLBACK rather than the main path: its publication rides the
-  unconfined agent, so it never receives the confined resident's kernel-enforced
-  containment. The agent substrate does.
 - `watch()` observes from inside the distro (a `find -newer` poll loop, see
   `lib/watcher.js`), so events are coarse invalidation, not per-file notifications,
   and they arrive on the poll cadence, not instantly. A file created with an mtime
   older than the watcher's stamp (`cp -p`, `tar -x`) is not seen until something
   else touches the tree. Watching a 9p share from the Windows side remains
   unsupported — the loop runs where the kernel can actually report change.
-- `glob` and `grep` use the Windows-side ripgrep over the share: correct results, but
-  not fast, and `.gitignore` is interpreted with Windows rules. `editText` reads the
-  whole file into memory before writing it back.
+- `editText` reads the whole file into memory before writing it back.
+- The directory picker lists distro levels from inside the distro — the
+  resident's `ls -1ALp` in one round trip, a one-shot `wsl.exe --exec ls` when
+  it is out, never the 9p walk the host used to pay per entry. The listing is
+  line-parsed, so a filename containing a newline would render as two rows;
+  `/` cannot appear in a name, so nothing else can split one.
 - 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
@@ -120,5 +104,19 @@ Everything below applies to the share substrate unless it says otherwise.
   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.
-- Terminal activity reporting stops at `wsl.exe`, so the controller never reclaims
-  these terminals when they are idle.
+- 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
+  (`lib/terminal-activity.js`). Exactly one (the shell at its prompt) is
+  `idle`; more than one (a command, a pipeline, a nested shell) is `busy`;
+  `unknown` — the agent out, the distro stopped — pauses reclamation, because
+  a probe that cannot answer must not authorize a close. Consequences to
+  know: a nested shell keeps the terminal busy by design (closing it would
+  lose that shell), so does any process the shell's startup files spawn with
+  the inherited marker (an `ssh-agent` launched in `.bashrc` reads as busy);
+  the idle threshold is the controller's `unattendedTimeoutMs` (2 h by
+  default); and the host-side shell-activity integration is still not armed
+  for these launches — `wsl.exe` on win32 fails its gate — which is why the
+  observation is a scan rather than shell cooperation.
+- Windows-folder host terminals (the `powershell.exe` branch) keep the shipped
+  behaviour: `unknown` activity, no reclamation.

package/docs/PARITY.md

@@ -21,6 +21,13 @@ Not applicable, recorded so the gap is a decision and not an omission:
 - Settings Sync, Remote-SSH tunnel chaining, Codespaces: composition-layer
   responsibilities, not this plugin's.
 
+> **Update (2026-10-04).** The plan's transitional invariant — `wsl.agent:
+> false` must equal the pre-agent share-backed behaviour — is superseded: the
+> share substrate is refused at construction, and the search spawn rides the
+> distro's rg. The share is no longer a fallback path of this plugin; the
+> only fallbacks left are transport-level (one-shot `wsl.exe` where the
+> resident agent is out), never share I/O.
+
 ## Contract audit (Phase 0)
 
 Findings from reading the harness packages inside the app bundle; each one
@@ -40,10 +47,17 @@ shaped a phase of the plan.
    distro's share, rewrite the spawn to run a distro-side `rg` (falling back
    to `grep -rE` + `find` when absent) with identical stdout conventions.
    Under the agent, that exec rides the agent's `exec` capability.
-   **Not implemented, and recorded so the gap is a decision, not an
-   omission:** search still runs the packaged Windows rg over the share. The
-   interception was designed (above) but never landed; nothing in the phase
-   table below delivers it, and no phase claims it.
+   **LANDED (2026-10-04), as the design above has it:** `WslSubprocessRuntime`
+   .`spawn` performs the rewrite, the decision living in `lib/search-route.js`,
+   and the exec rides the agent's `exec` capability — Phase 1's resident —
+   through the minimal handle facade of `lib/search-exec.js` (the spawn seam
+   returns its handle synchronously, so the facade degrades inside `done`),
+   with the one-shot `wsl.exe --exec` handle as the fallback when the agent is
+   out. The `grep -rE` fallback is NOT implemented — grep does not read
+   `.gitignore`, so it is not an rg substitute; a missing distro rg surfaces
+   rg's own exit 127 with a bootstrap pointer instead. With the share
+   substrate retired the same day, no model-facing search crosses the 9p
+   share at all.
 3. **`dsh-fs-local` watches with chokidar over the share** — the behaviour
    this plugin replaces: chokidar on 9p is the unreliability that made
    `WslFileSystem.watch` refuse. The in-distro watcher replaces it wholesale.

package/docs/README.zh.md

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

package/lib/agent-confined.js

@@ -27,12 +27,11 @@
  *
  * @module dsh-plugin-wsl/agent-confined
  */
-import { fileURLToPath } from "node:url";
 import { bwrapArgvPrefix } from "./bwrap.js";
 import { toLinuxPath } from "./paths.js";
+import { agentScriptDigest, agentScriptPath } from "./agent-shared.js";
 import { WslAgent } from "./agent.js";
 
-const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.meta.url));
 const confinedAgents = new Map();
 
 /**
@@ -63,7 +62,8 @@ export function confinedAgent({ distro, wslPath = "wsl.exe", policy, maskWindows
     agent = new WslAgent({
       distro,
       wslPath,
-      scriptPath: toLinuxPath(AGENT_SCRIPT_PATH),
+      scriptPath: toLinuxPath(agentScriptPath),
+      expectedDigest: agentScriptDigest,
       // The prefix is a whole command from the distro's point of view — program,
       // profile, `--` — because the transport inserts it between
       // `wsl.exe --exec` and the `sh <script>` pair (`lib/agent.js`'s

package/lib/agent-protocol.js

@@ -11,7 +11,7 @@
  */
 
 /** The protocol version this host side speaks; the agent must match. */
-export const PROTOCOL_VERSION = 3;
+export const PROTOCOL_VERSION = 4;
 
 /**
  * Upper bound on one `read` op's payload, set by the HOST looping over windowed
@@ -133,7 +133,9 @@ export function encodeFsFrame({ id, op, args, timeoutMs = 0 }) {
  * Parse one line of the agent's stdout.
  * @param {string} line - a line without its terminator.
  * @returns {object} one of:
- *   - `{ type: "hello", name, version }`
+ *   - `{ type: "hello", name, version, digest }` — `digest` is the sha256 of
+ *     the script file the agent is executing (empty when it could not hash
+ *     it); the host compares it against its own shipped copy
  *   - `{ type: "pong" }`
  *   - `{ type: "ack", id }` — the agent dequeued the request for execution;
  *     the host arms its stuck-request watchdog here, so queue time never
@@ -148,8 +150,8 @@ export function encodeFsFrame({ id, op, args, timeoutMs = 0 }) {
  */
 export function parseAgentLine(line) {
   if (line.startsWith("HELLO|")) {
-    const [, name, version] = line.split("|");
-    return { type: "hello", name, version: Number(version) };
+    const [, name, version, digest] = line.split("|");
+    return { type: "hello", name, version: Number(version), digest: digest ?? "" };
   }
   if (line === "PONG") return { type: "pong" };
   if (line.startsWith("ACK|")) return { type: "ack", id: line.slice(4) };

package/lib/agent-shared.js

@@ -10,13 +10,26 @@
  * @module dsh-plugin-wsl/agent-shared
  */
 
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { toLinuxPath } from "./paths.js";
 import { WslAgent } from "./agent.js";
 
 const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.meta.url));
+// The script the distro reads must be byte-identical to the copy this
+// package shipped: the deployed layout reads it from the /mnt/c mirror, and
+// the handshake digest is what catches a stale or half-synced runtime copy.
+// Both resident factories (plain and confined) pin it.
+const AGENT_SCRIPT_DIGEST = createHash("sha256").update(readFileSync(AGENT_SCRIPT_PATH)).digest("hex");
 const sharedAgents = new Map();
 
+/** The agent script as a host-side path, for factories that need both spellings. */
+export const agentScriptPath = AGENT_SCRIPT_PATH;
+
+/** The sha256 of the shipped agent script; every resident verifies its HELLO against it. */
+export const agentScriptDigest = AGENT_SCRIPT_DIGEST;
+
 /**
  * The shared agent for one distro, created on first use.
  * @param distro - the distro name.
@@ -25,7 +38,7 @@ const sharedAgents = new Map();
 export function sharedAgent(distro) {
   let agent = sharedAgents.get(distro);
   if (agent === undefined) {
-    agent = new WslAgent({ distro, scriptPath: toLinuxPath(AGENT_SCRIPT_PATH) });
+    agent = new WslAgent({ distro, scriptPath: toLinuxPath(AGENT_SCRIPT_PATH), expectedDigest: AGENT_SCRIPT_DIGEST });
     sharedAgents.set(distro, agent);
   }
   return agent;

package/lib/agent.js

@@ -44,6 +44,11 @@ const HANDSHAKE_TIMEOUT_MS = 15000;
 /** Extra time the host watchdog waits past the request's own in-distro timeout. */
 const WATCHDOG_GRACE_MS = 13000;
 
+/** How far past its host's idle shutdown the agent's own lease runs. The
+ * lease fires only when the host is gone in every way that matters (a wedged
+ * relay that never delivers EOF); the host's close() normally wins the race. */
+const LEASE_GRACE_MS = 120000;
+
 /** The Windows essentials `wsl.exe` itself needs to start and report cleanly. */
 const WINDOWS_ESSENTIALS = /^(systemroot|systemdrive|windir|path|pathext|comspec|os|computername)$/i;
 
@@ -95,11 +100,34 @@ export function pinnedWindowsEnv(parent) {
  * @param {string} options.scriptPath - the agent script as a Linux path inside
  *   the distro (a `/mnt/<drive>/...` translation of the package's
  *   `agent/wsl-agent.sh`).
+ * @param {number} [options.leaseMs] - the agent's own client lease, forwarded
+ *   through the managed `DSH_` namespace so the script can self-terminate
+ *   when a wedged relay stops carrying traffic without ever delivering EOF.
  * @returns {import("node:child_process").ChildProcess} the spawned process.
  */
-function spawnDefault({ wslPath, distro, scriptPath, argvPrefix = [] }) {
+/**
+ * The spawn environment for one resident, with the client lease folded in.
+ * The pinned environment forwards only the managed `DSH_` namespace, and it
+ * forwards exactly the names the parent `WSLENV` lists — so the lease rides
+ * both: the value on the variable, the name on `WSLENV`. A non-positive
+ * lease leaves the environment as the pin built it (the script treats an
+ * unset variable as no lease).
+ * @param {Record<string, string>} env - the pinned environment.
+ * @param {number} leaseMs - the agent's client lease in ms; 0 disables.
+ * @returns {Record<string, string>} the environment to spawn with.
+ */
+export function agentLeaseEnv(env, leaseMs) {
+  if (!(leaseMs > 0)) return env;
+  return {
+    ...env,
+    DSH_AGENT_LEASE_MS: String(leaseMs),
+    WSLENV: [env.WSLENV, "DSH_AGENT_LEASE_MS"].filter(Boolean).join(":"),
+  };
+}
+
+function spawnDefault({ wslPath, distro, scriptPath, argvPrefix = [], leaseMs = 0 }) {
   return spawn(wslPath, ["-d", distro, "--exec", ...argvPrefix, "sh", scriptPath], {
-    env: pinnedWindowsEnv(process.env),
+    env: agentLeaseEnv(pinnedWindowsEnv(process.env), leaseMs),
     stdio: ["pipe", "pipe", "pipe"],
     windowsHide: true,
   });
@@ -114,9 +142,13 @@ export class WslAgent {
    * @param {string} config.distro - the distro this agent serves.
    * @param {string} config.scriptPath - the agent script as a Linux path
    *   inside the distro (see {@link spawnDefault}).
-   * @param {string} [config.wslPath] - the `wsl.exe` path.
-   * @param {number} [config.idleMs] - idle shutdown delay; 0 disables.
-   * @param {string[]} [config.argvPrefix] - arguments inserted between
+ * @param {string} [config.wslPath] - the `wsl.exe` path.
+ * @param {number} [config.idleMs] - idle shutdown delay; 0 disables.
+ * @param {string} [config.expectedDigest] - the sha256 of the agent script
+ *   as this package shipped it; a HELLO whose digest differs is refused the
+ *   same way a version mismatch is (the script is read in place, so a stale
+ *   or half-synced runtime copy is the failure this catches).
+ * @param {string[]} [config.argvPrefix] - arguments inserted between
    *   `wsl.exe --exec` and the `sh script` pair — the confinement wrapper
    *   (`bwrap … --`) a confined agent runs its whole lifetime under, so every
    *   filesystem op it performs is kernel-enforced. Empty for the plain agent.
@@ -129,6 +161,7 @@ export class WslAgent {
     this.wslPath = config.wslPath ?? "wsl.exe";
     this.argvPrefix = config.argvPrefix ?? [];
     this.idleMs = config.idleMs ?? 600000;
+    this.expectedDigest = config.expectedDigest;
     /** Hard ceiling on one stdout protocol line; a longer line is a broken or
      * hostile agent, not data to hold — readline used to accumulate it all. */
     this.frameCapBytes = config.frameCapBytes ?? MAX_FRAME_BYTES;
@@ -179,6 +212,7 @@ export class WslAgent {
         distro: this.distro,
         scriptPath: this.scriptPath,
         argvPrefix: this.argvPrefix,
+        leaseMs: this.idleMs > 0 ? this.idleMs + LEASE_GRACE_MS : 0,
       }));
       const handshakeTimer = setTimeout(() => {
         this.lastError = `agent handshake timed out after ${HANDSHAKE_TIMEOUT_MS}ms`;
@@ -252,9 +286,22 @@ export class WslAgent {
     switch (message.type) {
       case "hello": {
         if (message.name !== AGENT_NAME || message.version !== PROTOCOL_VERSION) {
+          // Settle BEFORE killing: the exit event must not overwrite the real
+          // reason with the generic handshake message (the fake transports
+          // emit exit synchronously inside kill(); a real wsl.exe races it).
           this.lastError = `agent handshake mismatch: got ${message.name}@${message.version}, want ${AGENT_NAME}@${PROTOCOL_VERSION}`;
+          settleStart(new Error(this.lastError));
           this.process?.kill();
+          return;
+        }
+        if (this.expectedDigest !== undefined && message.digest !== this.expectedDigest) {
+          // The script is read in place from the distro-visible path — in the
+          // deployed layout a /mnt/c mirror — so a digest that differs from
+          // the copy this package shipped means the runtime copy is stale,
+          // half-synced, or edited. Fail closed with the fix in the message.
+          this.lastError = `agent script digest mismatch: the file the distro read at ${this.scriptPath} hashes to ${message.digest || "(nothing)"}, but this package shipped ${this.expectedDigest} — resync the runtime copy (npm run sync:windows) or reinstall the plugin`;
           settleStart(new Error(this.lastError));
+          this.process?.kill();
           return;
         }
         clearTimeout(handshakeTimer);