dsh-plugin-wsl-env 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -16,6 +16,45 @@ were part of the record.
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-10-18
+
+The shared read agent is the native binary (A7): unconfined reads now use the
+packaged static-musl agent with the shell as the fallback, cutting 16
+concurrent reads from 342-614 ms to 2.4-8.2 ms. The A6 FS measurement and
+metrics ship with it.
+
+### Added
+
+- **The shared read agent is native (A7).** `WslAgent` gained an async
+  `prepare()` hook; `sharedAgent` uses it to select the packaged native binary
+  through `agentBackend` (`auto`/`native`), with the shell as the fallback
+  (`shell`, a failed preparation, or a native HELLO/runtime failure; the reads
+  never fail closed). The A6 probe measures 16 concurrent shared reads at
+  2.4-8.2 ms, down from 342-614 ms on the shell. The native shared agent also
+  serves the picker, the subprocess activity probes and the non-session
+  command path, so those inherit EXEC concurrency.
+
+- **`WslAgent.metrics()`.** Per-kind queue wait (sent -> ACK), execution time
+  (ACK -> settle), in-flight peak, rejected and cancelled counters; the
+  47-check lifecycle suite covers the counters and the reset.
+
+- **`test/probe/fs-queue.mjs`.** A live measurement of both FS agents. The A6
+  run showed the shared shell reads were the batch bottleneck (16 concurrent
+  `stat`/`read`/`list` at 342-614 ms, queue up to 583 ms) while native FS ops
+  execute in 0.2-0.3 ms; the A7 run measures the native shared reads at
+  2.4-8.2 ms. v6's lock removal only takes 16 native writes from 7.7 ms to
+  ~5 ms, so it stays deferred.
+
+### Changed
+
+- **The plan after the A6 measurement: A7 (native shared reads) landed, v6
+  deferred.** [`docs/ROADMAP.md`](docs/ROADMAP.md) records the done, next and
+  deferred steps; ADR 0002, LIMITATIONS and the READMEs describe the native
+  shared reads and the v6 deferral.
+
+- `test/probe/fs-queue.mjs` and the README/LIMITATIONS/ROADMAP describe the
+  native shared reads; `test/agent-shared.test.mjs` covers the shell selection.
+
 ## [0.10.0] - 2026-10-18
 
 The native in-distro agent is the default session-runtime backend: `agentBackend: auto`

package/README.md

@@ -124,7 +124,7 @@ preset-wsl (the wsl agent preset; its settings are separate from the app's)
 
 **How a command runs.** A session gets one resident agent inside a systemd user scope. By default that agent is the native `dsh-wsl-agent` — the packaged static-musl binary for the distro's architecture, selected by `agentBackend: auto`; the runtime's shell agent is the fallback when the binary is missing or fails its copy/digest/exec check, and `agentBackend: shell` forces it while `native` refuses instead of falling back. The agent executes each command in your login shell under a bubblewrap mount profile. Because the scope outlives the command, a background dev server survives, `/tmp` is the distro's real `/tmp`, and `ps` sees the whole session. With `sessionSandbox: false`, the agent stays per distro, each command gets its own bwrap profile (`--unshare-pid`, a fresh `/tmp`), background processes do not survive, and the native backend is not used. If the agent is unavailable (or you set `agent: false`), the one-shot `wsl.exe` path runs the command instead — same result, slightly slower, and per-command isolation.
 
-**How file operations run.** Reads, writes and searches also happen inside the distro, on its own filesystem, with the distro's own tools. A search over a distro workspace runs the distro's `rg`, never the Windows binary over the 9p share. File writes are checked against the same policy the command sandbox enforces; with `wsl-fs` `sessionSandbox` on (the shipped preset), a confined write runs in the same session runtime as the commands — the same native/shell agent — so it sees the same `/tmp` and workspace mounts. Reads use the shared shell agent.
+**How file operations run.** Reads, writes and searches also happen inside the distro, on its own filesystem, with the distro's own tools. A search over a distro workspace runs the distro's `rg`, never the Windows binary over the 9p share. File writes are checked against the same policy the command sandbox enforces; with `wsl-fs` `sessionSandbox` on (the shipped preset), a confined write runs in the same session runtime as the commands — the same native/shell agent — so it sees the same `/tmp` and workspace mounts. Reads use the shared native read agent (A7; the packaged binary, shell fallback): 16 concurrent reads measure ~2.4 ms, down from 342-614 ms on the shell.
 
 ## Sandbox
 
@@ -192,6 +192,7 @@ Run `pnpm install` once to get the development dependencies. The tests use the p
 |---|---|
 | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | every configuration key, and how to override it |
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | the plugin's parts and how they attach, path coordinates, the sandbox, testing, file layout |
+| [docs/ROADMAP.md](docs/ROADMAP.md) | the plan: done, next (A7 native shared reads, A8 aarch64), deferred (v6) |
 | [docs/LIMITATIONS.md](docs/LIMITATIONS.md) | what the plugin does not do, and why |
 | [docs/VALUE.zh.md](docs/VALUE.zh.md) | the plugin's value in Chinese: what it is worth, what it costs, and when not to use it |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | the development loop, gates, conventions, verification |

package/docs/CONFIGURATION.md

@@ -27,7 +27,7 @@ has its own table at the end of this page.
 | | `loginShell` | `true` *(shipped)* | use `<shell> -lc`, which sources your profile, instead of a bare `-c`. Applies only to the POSIX family; a non-POSIX shell (fish, csh) still gets a bare `-c` |
 | | `agent` | `true` | run commands over the resident in-distro agent (one long-lived process; in-distro timeout); the one-shot `wsl.exe` path is fallen back to only when the agent is out of service. Anything else — a cwd refusal, a sandbox refusal — is the command's own verdict and is raised, not retried on the other path |
 | | `sessionSandbox` | `true` *(shipped)* | run this session's commands in one persistent systemd user scope (ADR 0001): a background dev server survives the command that started it, `/tmp` is the distro's real `/tmp` under `workspace-write`, and `ps` sees the session. The executor holds the runtime for the session and stops the scope from the preset's disposer, which reaps the cgroup. Requires `agent: true`, systemd as PID 1, a reachable user manager and `Linger` (`loginctl enable-linger <user>`); the preflight refuses with the remedy when systemd, the user manager, `systemd-run` or `Linger` is missing (a success is cached; a failure is re-probed, so following the remedy needs no app restart). On in the shipped preset; set `false` for the per-command shape |
-| | `agentBackend` | `auto` | the session runtime's in-distro agent. `auto` uses the native agent when a verified source is available — the packaged per-arch static-musl binary at `agent/native/linux-<arch>/dsh-wsl-agent` (x86_64 and aarch64; runs on glibc and musl distros), or the `DSH_WSL_AGENT_NATIVE` development override — and otherwise the shipped shell agent; `native` fails the first command when it cannot prepare instead of silently falling back; `shell` forces the shell agent. Confined writes share the runtime, so they follow the same selection. The native backend is the default (static musl x86_64/aarch64); the shell agent is the fallback, and `native` refuses instead of falling back |
+| | `agentBackend` | `auto` | the session runtime's in-distro agent. `auto` uses the native agent when a verified source is available — the packaged per-arch static-musl binary at `agent/native/linux-<arch>/dsh-wsl-agent` (x86_64 and aarch64; runs on glibc and musl distros), or the `DSH_WSL_AGENT_NATIVE` development override — and otherwise the shipped shell agent; `native` fails the first command when it cannot prepare instead of silently falling back; `shell` forces the shell agent. Confined writes share the runtime, so they follow the same selection. The native backend is the default (static musl x86_64/aarch64); the shell agent is the fallback, and `native` refuses instead of falling back. This key covers the session runtime (commands and confined writes) and, since A7, the shared read agent (unconfined reads), which also follows this selection with the shell fallback |
 | | `sandbox` | `true` | confine commands with `bubblewrap`; `false` disables the sandbox. Needs a usable `bwrap` inside the distro and fails closed without one (`SANDBOX_UNAVAILABLE`, never an unconfined run) — see [Turning the sandbox off](#turning-the-sandbox-off) |
 | | `maskWindowsDrive` | `false` | shadow `/mnt` with an empty tmpfs in every confined profile: the Windows drive's files cannot be read or exfiltrated and its executables cannot be launched through interop — the hole that lets a "sandboxed" command reach your full Windows token. A narrowing, not a closure (a command can still write an executable into the workspace and run it — binfmt dispatches on content, not location), so enforcement stays `partial` and the result's sandbox fact reports `windowsDrive: "masked"`. The complete closure is distro-level: `[interop] enabled=false` in `wsl.conf` |
 | | `cwd` | `''` | default working directory; empty means the distro user's home |

package/docs/LIMITATIONS.md

@@ -119,6 +119,12 @@ crosses the 9p share. What to know about the one substrate there is:
   call. The session runtime path — the shipped default — is cleaned by its
   scope. A systemd-scoped one-shot (with explicit environment pass-through) is
   not shipped; prefer `agent: true` and the session runtime for long commands.
+- **Batch file reads share one agent per distro.** Since A7 the shared read
+  agent is the native binary, so 16 concurrent `stat`/`read`/`list` calls
+  complete in 2.4-4.1 ms (A6 measured 342-614 ms on the shell). The first call
+  pays the native preparation/cache cost (~70 ms once); `agentBackend: shell`
+  forces the shell reads. v6's FS concurrency would only shave the native
+  runtime's 7.7 ms/16 writes and is deferred.
 - **The native backend is the default; aarch64 is build-tested only.** The
   packaged x86_64 musl binary runs the 18-check suite in CI. The same job
   builds the aarch64 binary, but the runner cannot execute it, so its

package/docs/README.zh.md

@@ -125,7 +125,7 @@ preset-wsl（wsl agent preset；这个环境里的服务相互独立）
 
 **命令的执行路径。** 一个会话有一个常驻 agent，运行在 systemd user scope 内。默认它是 native `dsh-wsl-agent`——按 distro 架构选择的包内静态 musl 二进制，由 `agentBackend: auto` 选中；二进制缺失或 copy/digest/exec 校验失败时回退到 runtime 的 shell agent，`agentBackend: shell` 强制 shell，`native` 则拒绝回退。agent 在你的登录 shell 中、bubblewrap mount profile 内执行每条命令。scope 比命令活得久，所以后台 dev server 存活、`/tmp` 是子系统真实 `/tmp`、`ps` 能看到整个会话。设 `sessionSandbox: false` 时，agent 仍是每子系统一个、每条命令一套 bwrap profile（`--unshare-pid`、临时 `/tmp`），后台进程不存活，且不使用 native 后端。agent 不可用时（或 `agent: false`），改走一次性 `wsl.exe`——结果一致、略慢、仍是每命令隔离。
 
-**文件操作的执行路径。** 读、写、搜索同样发生在子系统内部：使用子系统自己的磁盘与工具。子系统工作区的搜索运行子系统内的 `rg`，不使用 Windows 侧副本走 9p 共享。文件写入与命令沙箱使用同一份策略检查；`wsl-fs` 的 `sessionSandbox` 打开时（默认），受限写入跑在与命令相同的会话 runtime 里（同一个 native/shell agent），看到相同的 `/tmp` 与 workspace mount。读操作走共享的 shell agent。
+**文件操作的执行路径。** 读、写、搜索同样发生在子系统内部：使用子系统自己的磁盘与工具。子系统工作区的搜索运行子系统内的 `rg`，不使用 Windows 侧副本走 9p 共享。文件写入与命令沙箱使用同一份策略检查；`wsl-fs` 的 `sessionSandbox` 打开时（默认），受限写入跑在与命令相同的会话 runtime 里（同一个 native/shell agent），看到相同的 `/tmp` 与 workspace mount。读操作走共享的 native 读 agent（A7；包内二进制，shell 回退）：16 个并发读实测约 2.4 ms，此前 shell 为 342–614 ms。
 
 ## 沙箱
 
@@ -193,6 +193,7 @@ pnpm run probe:sandbox-off    # 验证 sandbox: false 确实关掉两侧沙箱
 |---|---|
 | [docs/CONFIGURATION.md](CONFIGURATION.md) | 每个配置键，以及如何覆盖 |
 | [docs/ARCHITECTURE.md](ARCHITECTURE.md) | provider、挂载方式、路径坐标、沙箱、测试分层、文件布局 |
+| [docs/ROADMAP.md](ROADMAP.md) | 路线图：已完成、下一步（A7 native 共享读、A8 aarch64）、已推迟（v6） |
 | [docs/LIMITATIONS.md](LIMITATIONS.md) | 插件不做的事情，以及原因 |
 | [docs/VALUE.zh.md](VALUE.zh.md) | 本插件的价值、代价，以及什么情况下不该用它 |
 | [CONTRIBUTING.md](../CONTRIBUTING.md) | 开发循环、质量门、约定、已验证内容 |

package/docs/ROADMAP.md

@@ -0,0 +1,79 @@
+# Roadmap
+
+The native in-distro agent is the default session-runtime backend since 0.10.0
+([ADR 0002](adr/0002-native-agent.md)). This plan was updated after the A6 FS
+measurement; the numbers are in the ADR's
+[FS queue measurement](adr/0002-native-agent.md#fs-queue-measurement-a6-2026-10-18)
+section.
+
+## Done
+
+| Step | Outcome |
+|---|---|
+| A1 | `wsl-shell.agentBackend` (`auto`/`native`/`shell`): the native session-runtime agent, the shell fallback, the strict `native` mode |
+| A2 | packaged static-musl `agent/native/linux-x86_64` and `linux-aarch64` binaries, selected by the distro's `uname -m`; the dev override |
+| A3 | the native HELLO carries `/proc/self/exe`'s sha256; the host binds it with `expectedDigest` |
+| A4 | the native-session probe (scope, EXEC, FS, KILL, digest, teardown, 8/8) in the real-machine suite; the warm-cache and stdin-EPIPE fixes |
+| A5 | the native agent is the documented default; 0.10.0 published (npm + GitHub Release) |
+| A6 | `WslAgent.metrics()` and `test/probe/fs-queue.mjs`; the shared shell read agent is the measured batch bottleneck |
+
+## Next
+
+### A7 — native shared read agent (v5) — done
+
+The shared unconfined read agent was the only remaining measured bottleneck
+(16 concurrent reads 342-614 ms, queue up to 583 ms, versus native FS execution
+0.2-0.3 ms). A7 swaps its shell for the native binary (v5) while keeping the
+shell as the fallback:
+
+- **selection:** the same `agentBackend` semantics — `auto` prepares the
+  packaged binary for the distro's architecture, `native` refuses instead of
+  falling back, `shell` forces the shell; the dev override still wins;
+- **preparation:** `ensureNativeBackend` once per distro (cache/digest/exec
+  probe); the `WslAgent` with `expectedDigest` and `signalable: false`; on a
+  preparation or HELLO failure the shell agent serves the reads — fail-open to
+  the shell, never fail-closed;
+- **surface:** the same six v5 FS ops and `dsh-fs` side channel; the
+  `fs-substrate`/`DistroFs` parse is unchanged; the A2 differential covers the
+  records;
+- **result:** `WslAgent` gained a `prepare()` hook and the shared agent now
+  selects the native entry through it. `test/probe/fs-queue.mjs` measures 16
+  concurrent shared reads at **2.4-4.1 ms** (from 342-614 ms); the first start
+  pays the ensure/cache cost (~70 ms once). The shell still serves the reads
+  under `agentBackend: shell` and after a native failure.
+
+### A8 — aarch64 functional validation
+
+The aarch64 binary is built by CI but never executed there. Run the 18-check
+spike suite and the native-session probe on real aarch64 WSL or qemu; record
+the result in the ADR.
+
+### A9 — maintenance
+
+- Release A7 as a minor (0.11.0) through the tag workflow — done;
+- `pnpm run sync:windows` after each release, then restart the app;
+- keep the probes and the documentation current.
+
+## Deferred
+
+- **v6 (FS concurrency / ERR frames / per-request env).** The A6 measurement
+  shows the lock-removal gain is marginal (~7.7 -> ~5 ms per 16 writes, ~12.2
+  -> ~8 ms per 16 reads). Revisit only if the native shared v5 still queues
+  measurably or the ERR/env framing is needed for another reason.
+- **Event stream.** No current consumer: the `fs.watch` contract is coarse and
+  the inotify watcher satisfies it; terminal activity and ports poll.
+- **Shell retirement.** Not planned. The shell agent remains the fallback and
+  the shared read path until A7 lands, and the protocol/script stays supported.
+
+## Not planned
+
+- Streaming command output (the harness has no consumer for it).
+- A per-subagent agent: subagents share the session runtime by workspace and
+  policy; separate runtimes only if a measurable need appears.
+
+## Decision rules
+
+A step moves out of Deferred only with a measurement or a concrete consumer,
+not because the protocol makes it possible. A7 itself is conditional on the
+batch-read demand (the GUI file tree, parallel subagents) being real; the
+single-op latency is the ~22 ms host round trip, not the FS backend.

package/lib/agent-shared.js

@@ -14,10 +14,12 @@
  * @module dsh-plugin-wsl/agent-shared
  */
 import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { toLinuxPath } from "./paths.js";
-import { WslAgent } from "./agent.js";
+import { pinnedWindowsEnv, WslAgent } from "./agent.js";
+import { configuredAgentBackend, ensureNativeBackend, NATIVE_AGENT_ENV } from "./native-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
@@ -25,6 +27,9 @@ const AGENT_SCRIPT_PATH = fileURLToPath(new URL("../agent/wsl-agent.sh", import.
 // 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();
+// Distros where the native shared agent failed at runtime; the reads fail open
+// to the shell instead of retrying the same broken binary on every call.
+const nativeFailed = new Set();
 /** 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. */
@@ -37,9 +42,32 @@ export const agentScriptDigest = AGENT_SCRIPT_DIGEST;
  */
 export function sharedAgent(distro) {
     let agent = sharedAgents.get(distro);
-    if (agent === undefined) {
-        agent = new WslAgent({ distro, scriptPath: toLinuxPath(AGENT_SCRIPT_PATH), expectedDigest: AGENT_SCRIPT_DIGEST });
-        sharedAgents.set(distro, agent);
-    }
+    if (agent !== undefined && !agent.unavailable)
+        return agent;
+    if (agent !== undefined)
+        nativeFailed.add(distro);
+    agent = new WslAgent({
+        distro,
+        scriptPath: toLinuxPath(AGENT_SCRIPT_PATH),
+        expectedDigest: AGENT_SCRIPT_DIGEST,
+        prepare: async () => {
+            if (configuredAgentBackend() === "shell" || nativeFailed.has(distro))
+                return undefined;
+            const prepared = await ensureNativeBackend({ wslPath: "wsl.exe", distro, source: process.env[NATIVE_AGENT_ENV] ?? "" });
+            if (prepared === undefined)
+                return undefined;
+            return {
+                scriptPath: prepared.path,
+                expectedDigest: prepared.digest,
+                signalable: false,
+                spawnTransport: ({ wslPath, distro: target, argvPrefix }) => spawn(wslPath, ["-d", target, "--exec", ...argvPrefix, prepared.path], {
+                    stdio: ["pipe", "pipe", "pipe"],
+                    windowsHide: true,
+                    env: pinnedWindowsEnv(process.env),
+                }),
+            };
+        },
+    });
+    sharedAgents.set(distro, agent);
     return agent;
 }

package/lib/agent.d.ts

@@ -59,6 +59,14 @@ export interface ExecResult {
 export interface PendingRequest {
     /** The request id, as the agent echoes it. */
     id: string;
+    /** Which metric bucket this request belongs to. */
+    kind: "fs" | "exec";
+    /** When the frame was written, for the queue measurement. */
+    sentAt: number;
+    /** When the agent ACKed it, for the execution measurement. */
+    ackedAt?: number;
+    /** Whether the metrics recorded this request's settle. */
+    measured: boolean;
     /** The frame lines (kept so a rebuild can re-send). */
     lines: string[];
     /** Settles a RES. */
@@ -80,6 +88,51 @@ export interface PendingRequest {
     /** The caller was already settled; a late answer only cleans up. */
     settled: boolean;
 }
+/** Per-kind request metrics. */
+export interface RequestMetrics {
+    /** Requests that settled (successful, failed or cancelled). */
+    requests: number;
+    /** Total queue wait (sent -> ACK), ms. */
+    queueMs: number;
+    /** Largest single queue wait, ms. */
+    queueMaxMs: number;
+    /** Total execution time (ACK -> settle), ms. */
+    execMs: number;
+    /** Largest single execution time, ms. */
+    execMaxMs: number;
+    /** Settled with an error (not cancellation). */
+    failed: number;
+    /** Cancelled by the caller. */
+    cancelled: number;
+    /** Rejected before tracking: queue full, already aborted, or send failed. */
+    rejected: number;
+}
+/** The agent's cumulative request metrics. */
+export interface AgentMetrics {
+    /** FS frames. */
+    fs: RequestMetrics;
+    /** EXEC frames (commands, ping). */
+    exec: RequestMetrics;
+    /** Peak number of pending requests. */
+    inFlightMax: number;
+}
+/** The entry an async preparation may select before the first spawn. */
+export interface WslAgentPrepared {
+    /** The agent entrypoint (the shell script or the native cache path). */
+    scriptPath: string;
+    /** The HELLO digest to verify. */
+    expectedDigest?: string;
+    /** Whether USR1 can reach the agent (false for the native KILL-frame path). */
+    signalable?: boolean;
+    /** The process factory for this entry. */
+    spawnTransport?: (options: {
+        wslPath: string;
+        distro: string;
+        scriptPath: string;
+        argvPrefix: string[];
+        leaseMs: number;
+    }) => ChildProcess;
+}
 /**
  * The Windows environment the transport starts from, pinned.
  *
@@ -180,6 +233,10 @@ export declare class WslAgent {
     idleTimer: NodeJS.Timeout | null;
     /** The last failure, for `unavailableReason` and log messages. */
     lastError: string;
+    /** Cumulative request metrics; see {@link metrics}. */
+    requestMetrics: AgentMetrics;
+    /** The optional async preparation hook. */
+    prepare: (() => Promise<WslAgentPrepared | undefined>) | undefined;
     /**
      * @param config - the agent configuration.
      */
@@ -248,6 +305,8 @@ export declare class WslAgent {
          * refused instead of growing the request map without bound.
          */
         maxPending?: number;
+        /** Optional async preparation selecting the entry before the first spawn. */
+        prepare?: () => Promise<WslAgentPrepared | undefined>;
     });
     /**
      * Whether the agent is permanently out — the executor's fallback cue.
@@ -264,6 +323,18 @@ export declare class WslAgent {
      * @returns resolved once the state is `ready`.
      */
     start(): Promise<void>;
+    /**
+     * Apply an async preparation entry to this agent before the first spawn.
+     *
+     * @param entry - the selected entry.
+     */
+    private applyPrepared;
+    /**
+     * Spawn the process and run the handshake.
+     *
+     * @returns resolved once the state is `ready`.
+     */
+    private beginStart;
     /**
      * One stdout line from the agent. The first must be a matching HELLO.
      *
@@ -384,6 +455,38 @@ export declare class WslAgent {
      *
      * @param signal - the signal to deliver (`SIGUSR1` is the cancel trap).
      */
+    /**
+     * The cumulative request metrics: queue wait (sent -> ACK) and execution
+     * time (ACK -> settle) per request kind, plus the peak in-flight count.
+     *
+     * @returns a snapshot the caller can keep.
+     */
+    metrics(): AgentMetrics;
+    /** Reset the cumulative metrics (diagnostics/probes). */
+    resetMetrics(): void;
+    /**
+     * The metric bucket for a request kind.
+     * @param kind - fs or exec.
+     * @returns the bucket.
+     */
+    private kindMetrics;
+    /**
+     * Record a request that never entered the pending map.
+     * @param kind - the bucket.
+     */
+    private noteRejected;
+    /**
+     * Record the dequeue ACK: the request's queue wait.
+     * @param pending - the request.
+     */
+    private recordAck;
+    /**
+     * Record a settle: the requests count, the execution time (or the queue wait
+     * for a request that never ACKed), and the outcome.
+     * @param pending - the request.
+     * @param error - the failure, when any.
+     */
+    private recordSettle;
     private signalAgent;
     /**
      * Shut the agent down: SHUTDOWN first, then kill after a short grace. The

package/lib/agent.js

@@ -40,6 +40,20 @@
 import { spawn } from "node:child_process";
 import { AgentUnavailableError, CwdError } from "./agent-errors.js";
 import { AGENT_NAME, MAX_FRAME_BYTES, PROTOCOL_VERSION, encodeExecFrame, encodeFsFrame, encodeKill, encodeSetEnv, parseAgentLine } from "./agent-protocol.js";
+/**
+ * A zeroed per-kind metrics record.
+ * @returns the record.
+ */
+function emptyRequestMetrics() {
+    return { requests: 0, queueMs: 0, queueMaxMs: 0, execMs: 0, execMaxMs: 0, failed: 0, cancelled: 0, rejected: 0 };
+}
+/**
+ * A zeroed metrics snapshot.
+ * @returns the snapshot.
+ */
+function emptyAgentMetrics() {
+    return { fs: emptyRequestMetrics(), exec: emptyRequestMetrics(), inFlightMax: 0 };
+}
 /** How long a rebuilt agent has to re-answer the handshake before giving up. */
 const HANDSHAKE_TIMEOUT_MS = 15000;
 /** Extra time the host watchdog waits past the request's own in-distro timeout. */
@@ -160,6 +174,8 @@ export class WslAgent {
         this.rebuildUsed = false;
         this.idleTimer = null;
         this.lastError = "";
+        this.requestMetrics = emptyAgentMetrics();
+        this.prepare = config.prepare;
     }
     /**
      * Whether the agent is permanently out — the executor's fallback cue.
@@ -187,9 +203,42 @@ export class WslAgent {
             return Promise.resolve();
         if (this.startPromise)
             return this.startPromise;
+        const prepared = this.prepare?.();
+        if (prepared === undefined) {
+            const started = this.beginStart();
+            this.startPromise = started;
+            return started;
+        }
+        const started = prepared.then((entry) => {
+            if (entry !== undefined)
+                this.applyPrepared(entry);
+            return this.beginStart();
+        });
+        this.startPromise = started;
+        return started;
+    }
+    /**
+     * Apply an async preparation entry to this agent before the first spawn.
+     *
+     * @param entry - the selected entry.
+     */
+    applyPrepared(entry) {
+        this.scriptPath = entry.scriptPath;
+        this.expectedDigest = entry.expectedDigest;
+        if (entry.signalable !== undefined)
+            this.signalable = entry.signalable;
+        if (entry.spawnTransport !== undefined)
+            this.configuredSpawn = entry.spawnTransport;
+    }
+    /**
+     * Spawn the process and run the handshake.
+     *
+     * @returns resolved once the state is `ready`.
+     */
+    beginStart() {
         this.state = "starting";
         this.agentPid = undefined;
-        this.startPromise = new Promise((resolve, reject) => {
+        return new Promise((resolve, reject) => {
             // stdio is all-pipe (the spawn options above), so every standard stream
             // exists; the broad ChildProcess type models them as nullable.
             const child = (this.process = (this.configuredSpawn ?? spawnDefault)({
@@ -286,7 +335,6 @@ export class WslAgent {
                 this.lastError = String(chunk).trim().slice(0, 2000) || this.lastError;
             });
         });
-        return this.startPromise;
     }
     /**
      * One stdout line from the agent. The first must be a matching HELLO.
@@ -333,6 +381,7 @@ export class WslAgent {
                 const pending = this.pending.get(message.id);
                 if (pending) {
                     pending.started = true;
+                    this.recordAck(pending);
                     if (pending.cancelled)
                         this.signalAgent("SIGUSR1");
                     pending.armWatchdog?.();
@@ -487,16 +536,26 @@ export class WslAgent {
      *
      * @param request - the request to register.
      */
-    track({ id, lines, resolve, reject, timeoutMs, signal }) {
+    track({ id, kind = "exec", lines, resolve, reject, timeoutMs, signal }) {
         if (this.pending.size >= this.maxPending) {
+            this.noteRejected(kind);
             reject(new Error(`the resident agent has ${this.pending.size} requests in flight (max ${this.maxPending}); retry when the queue drains`));
             return;
         }
         const pending = {
             id,
+            kind,
+            sentAt: performance.now(),
+            measured: false,
             lines,
-            resolve,
-            reject,
+            resolve: (result) => {
+                this.recordSettle(pending, undefined);
+                resolve(result);
+            },
+            reject: (error) => {
+                this.recordSettle(pending, error);
+                reject(error);
+            },
             watchdog: null,
             signal: signal ?? null,
             onAbort: null,
@@ -525,9 +584,11 @@ export class WslAgent {
                 : null,
         };
         this.pending.set(id, pending);
+        this.requestMetrics.inFlightMax = Math.max(this.requestMetrics.inFlightMax, this.pending.size);
         if (signal) {
             if (signal.aborted) {
                 this.pending.delete(id);
+                this.noteRejected(kind);
                 reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
                 return;
             }
@@ -557,6 +618,7 @@ export class WslAgent {
         if (!this.writeLines(lines)) {
             this.clearPending(pending);
             this.pending.delete(pending.id);
+            this.noteRejected(kind);
             reject(new AgentUnavailableError("the agent exited before the request could be sent; it never ran"));
             return;
         }
@@ -580,7 +642,7 @@ export class WslAgent {
             ...encodeExecFrame({ id, cwd, argv, timeoutMs, maxOutputBytes }),
         ];
         return new Promise((resolve, reject) => {
-            this.track({ id, lines, resolve, reject, timeoutMs, signal });
+            this.track({ id, kind: "exec", lines, resolve, reject, timeoutMs, signal });
         });
     }
     /**
@@ -602,7 +664,7 @@ export class WslAgent {
         const id = `r${this.nextRequestId++}`;
         const lines = encodeFsFrame({ id, op, args, timeoutMs });
         return new Promise((resolve, reject) => {
-            this.track({ id, lines, resolve, reject, timeoutMs, signal });
+            this.track({ id, kind: "fs", lines, resolve, reject, timeoutMs, signal });
         });
     }
     /**
@@ -620,7 +682,7 @@ export class WslAgent {
         return new Promise((resolve, reject) => {
             const id = `r${this.nextRequestId++}`;
             const lines = encodeExecFrame({ id, cwd: "/", argv: ["true"], timeoutMs: 0 });
-            this.track({ id, lines, resolve: () => resolve(), reject, timeoutMs: HANDSHAKE_TIMEOUT_MS, signal });
+            this.track({ id, kind: "exec", lines, resolve: () => resolve(), reject, timeoutMs: HANDSHAKE_TIMEOUT_MS, signal });
         });
     }
     /**
@@ -637,6 +699,80 @@ export class WslAgent {
      *
      * @param signal - the signal to deliver (`SIGUSR1` is the cancel trap).
      */
+    /**
+     * The cumulative request metrics: queue wait (sent -> ACK) and execution
+     * time (ACK -> settle) per request kind, plus the peak in-flight count.
+     *
+     * @returns a snapshot the caller can keep.
+     */
+    metrics() {
+        return {
+            fs: { ...this.requestMetrics.fs },
+            exec: { ...this.requestMetrics.exec },
+            inFlightMax: this.requestMetrics.inFlightMax,
+        };
+    }
+    /** Reset the cumulative metrics (diagnostics/probes). */
+    resetMetrics() {
+        this.requestMetrics = emptyAgentMetrics();
+    }
+    /**
+     * The metric bucket for a request kind.
+     * @param kind - fs or exec.
+     * @returns the bucket.
+     */
+    kindMetrics(kind) {
+        return kind === "fs" ? this.requestMetrics.fs : this.requestMetrics.exec;
+    }
+    /**
+     * Record a request that never entered the pending map.
+     * @param kind - the bucket.
+     */
+    noteRejected(kind) {
+        this.kindMetrics(kind).rejected += 1;
+    }
+    /**
+     * Record the dequeue ACK: the request's queue wait.
+     * @param pending - the request.
+     */
+    recordAck(pending) {
+        if (pending.ackedAt !== undefined)
+            return;
+        const now = performance.now();
+        pending.ackedAt = now;
+        const stats = this.kindMetrics(pending.kind);
+        const wait = now - pending.sentAt;
+        stats.queueMs += wait;
+        stats.queueMaxMs = Math.max(stats.queueMaxMs, wait);
+    }
+    /**
+     * Record a settle: the requests count, the execution time (or the queue wait
+     * for a request that never ACKed), and the outcome.
+     * @param pending - the request.
+     * @param error - the failure, when any.
+     */
+    recordSettle(pending, error) {
+        if (pending.measured)
+            return;
+        pending.measured = true;
+        const now = performance.now();
+        const stats = this.kindMetrics(pending.kind);
+        stats.requests += 1;
+        if (pending.ackedAt !== undefined) {
+            const exec = now - pending.ackedAt;
+            stats.execMs += exec;
+            stats.execMaxMs = Math.max(stats.execMaxMs, exec);
+        }
+        else {
+            const wait = now - pending.sentAt;
+            stats.queueMs += wait;
+            stats.queueMaxMs = Math.max(stats.queueMaxMs, wait);
+        }
+        if (pending.cancelled)
+            stats.cancelled += 1;
+        else if (error !== undefined)
+            stats.failed += 1;
+    }
     signalAgent(signal) {
         const pid = this.agentPid;
         if (pid === undefined || !this.signalable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wsl-env",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "\u8ba9 DeepSeek Harness \u4ee5 WSL \u5b50\u7cfb\u7edf\u4f5c\u4e3a\u4f1a\u8bdd\u7684\u6267\u884c\u73af\u5883\uff1ashell\u3001\u6587\u4ef6\u8bfb\u5199\u4e0e\u547d\u4ee4\u6267\u884c\u5747\u5728\u5b50\u7cfb\u7edf\u5185\u5b8c\u6210\uff0c\u76ee\u5f55\u9009\u62e9\u5668\u4e0e GUI \u7ec8\u7aef\u540c\u6837\u5b9a\u4f4d\u5230\u5b50\u7cfb\u7edf\u8def\u5f84\uff0c\u5e76\u901a\u8fc7\u5b50\u7cfb\u7edf\u5185\u7684 bubblewrap \u5bf9\u547d\u4ee4\u8fdb\u884c\u6c99\u7bb1\u9694\u79bb",
   "keywords": [
     "deepseek-harness",
@@ -106,6 +106,7 @@
     "docs/UPSTREAM-FSIO-EXPORT.md",
     "docs/UPSTREAM-TERMINAL-TITLE.md",
     "docs/ARCHITECTURE.md",
+    "docs/ROADMAP.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
@@ -119,9 +120,9 @@
     "lint:types": "tsc --noEmit",
     "build": "node scripts/build.mjs",
     "lint:build": "node test/build-freshness.mjs",
-    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=84 --test-coverage-functions=70 test/agent-exec.test.mjs test/agent-fs-script.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-substrate.test.mjs test/fs.boot.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/fsio-agent.test.mjs test/fsio-text.test.mjs test/git-route.test.mjs test/listing.test.mjs test/paths.test.mjs test/ports.test.mjs test/preset-choice.test.mjs test/probe-cache.test.mjs test/preflight.test.mjs test/sandbox.test.mjs test/search-exec.test.mjs test/search-route.test.mjs test/shell.test.mjs test/terminal-activity.test.mjs test/terminal.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/session-scope.test.mjs test/session-runtime.test.mjs test/native-agent.test.mjs test/peers.test.mjs",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=85 --test-coverage-branches=84 --test-coverage-functions=70 test/agent-exec.test.mjs test/agent-fs-script.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/fs-substrate.test.mjs test/fs.boot.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/fsio-agent.test.mjs test/fsio-text.test.mjs test/git-route.test.mjs test/listing.test.mjs test/paths.test.mjs test/ports.test.mjs test/preset-choice.test.mjs test/probe-cache.test.mjs test/preflight.test.mjs test/sandbox.test.mjs test/search-exec.test.mjs test/search-route.test.mjs test/shell.test.mjs test/terminal-activity.test.mjs test/terminal.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/session-scope.test.mjs test/session-runtime.test.mjs test/native-agent.test.mjs test/peers.test.mjs test/agent-shared.test.mjs",
     "test:syntax": "node test/syntax.mjs",
-    "test:unit": "node --test test/fs.boot.test.mjs test/fsio-text.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preflight.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/git-route.test.mjs test/fsio-text.test.mjs test/search-route.test.mjs test/search-exec.test.mjs test/terminal-activity.test.mjs test/session-scope.test.mjs test/session-runtime.test.mjs test/native-agent.test.mjs test/peers.test.mjs",
+    "test:unit": "node --test test/fs.boot.test.mjs test/fsio-text.test.mjs test/workspace-files-wsl.test.mjs test/composition.test.mjs test/provider.test.mjs test/file-reference-wsl.test.mjs test/paths.test.mjs test/listing.test.mjs test/shell.test.mjs test/terminal.test.mjs test/probe-cache.test.mjs test/preflight.test.mjs test/preset-choice.test.mjs test/sandbox.test.mjs test/agent-protocol.test.mjs test/agent.test.mjs test/agent-fs-script.test.mjs test/fsio-agent.test.mjs test/fs-substrate.test.mjs test/agent-exec.test.mjs test/ports.test.mjs test/watcher.test.mjs test/wsl.test.mjs test/fs-decisions.test.mjs test/git-route.test.mjs test/fsio-text.test.mjs test/search-route.test.mjs test/search-exec.test.mjs test/terminal-activity.test.mjs test/session-scope.test.mjs test/session-runtime.test.mjs test/native-agent.test.mjs test/peers.test.mjs test/agent-shared.test.mjs",
     "lint:style": "node test/style.mjs",
     "prepublishOnly": "pnpm test",
     "probe": "bash test/probe/run.sh",