dsh-wsl-desktop 0.3.5 → 0.3.7

package/README.en.md

@@ -14,13 +14,13 @@ Turns a WSL distribution into a **first-class execution world** inside DSH Deskt
 ## Contents
 
 - **This page**: [Target capabilities](#target-capabilities) · [Install / Update / Uninstall](#install--update--uninstall) · [Quick start](#quick-start) · [Desktop update discipline](#desktop-update-discipline-mandatory) · [Security and trust boundaries](#security-and-trust-boundaries) · [Known limitations](#known-limitations) · [Verification](#verification) · [Development](#development) · [Release](#release)
-- **In-depth material**: [Security and trust boundaries](SECURITY.md) · [Architecture and the execution world](docs/ARCHITECTURE.en.md) · [Confinement (Linux side)](docs/CONFINEMENT.en.md) · [The fs fence](docs/FS-FENCE.en.md) · [Terminal (PTY bridge)](docs/PTY-BRIDGE.en.md) · [Verification and the SKIP ruling](docs/VERIFICATION.en.md) · [Engineering notes](docs/ENGINEERING-NOTES.en.md) · [Distro support matrix](docs/DISTRO-SUPPORT.md) · [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) · [Architecture and flow diagrams](docs/diagrams.md)
+- **In-depth material**: [Security and trust boundaries](SECURITY.md) · [Architecture and the execution world](docs/ARCHITECTURE.en.md) · [Confinement (Linux side)](docs/CONFINEMENT.en.md) · [The fs fence](docs/FS-FENCE.en.md) · [Terminal (PTY bridge)](docs/PTY-BRIDGE.en.md) · [WSL file watching](docs/WATCH.en.md) · [Verification and the SKIP ruling](docs/VERIFICATION.en.md) · [Engineering notes](docs/ENGINEERING-NOTES.en.md) · [Distro support matrix](docs/DISTRO-SUPPORT.md) · [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) · [Architecture and flow diagrams](docs/diagrams.md)
 
-> The six documents this restructure created have an English edition (linked above; the file names carry an `.en` marker) and the pair is enforced rather than trusted. The three older documents — the distro support matrix, the upstream proposals and the diagram index — are **Chinese-only**, because no English text for them exists: translating them is a separate piece of work, not a rename.
+> The bilingual documents linked above (their file names carry an `.en` marker) are enforced as pairs rather than trusted. The three older documents — the distro support matrix, the upstream proposals and the diagram index — are **Chinese-only**, because no English text for them exists: translating them is a separate piece of work, not a rename.
 
 ## Target capabilities
 
-**Honest state after live acceptance** (`verify-post-restart.mjs` all green + 18 offline suites; each item below notes its evidence strength):
+**Honest state after live acceptance** (`verify-post-restart.mjs` all green + 19 offline suites; each item below notes its evidence strength):
 
 | # | Capability | Status |
 |---|---|---|
@@ -75,10 +75,12 @@ After every DSH Desktop update, the plugin may break because of harness internal
 
 **Confinement does not cover `/dev`, `/proc`, `/sys` or interop**, which is reported honestly in `enforcement: 'partial'`; and the session user's retained passwordless sudo grant can bypass the file fence — see [SECURITY.md](SECURITY.md).
 
+**File-change tracking inside a WSL workspace polls; it is not event-driven.** `fs.watch` throws `EISDIR` on the distribution's 9P share (for a file target as well as a directory one), so the host backend's chokidar watcher cannot initialize for any WSL target. The plugin polls on the host side instead: a directory compares its entry set (one `readdir` per 300ms; measured 0ms CPU per 3s and 2-3ms latency in this process) and a file — or a path that does not exist yet — watches its stat (`fs.watchFile`, measured 0ms CPU per 3s and 52ms). **A directory target is invalidated by entry-set changes only**: adds, removes and renames are seen; the CONTENT change of a file inside it is not — watch that file's own path to follow it. Mechanisms, measurements and what was not measured are in [WSL file watching](docs/WATCH.en.md).
+
 ## Verification
 
 ```powershell
-node scripts/verify-all.mjs          # all offline suites (18)
+node scripts/verify-all.mjs          # all offline suites (19)
 node scripts/verify-all.mjs --live   # additionally the suites needing the installed plugin + a running host
 ```
 
@@ -106,6 +108,7 @@ lib/wsl/world.js        Distro discovery, the wsl.exe execution core, directory
 lib/wsl/shell.js        ShellExecutor implementation (WSL bash + confinement hookup)
 lib/wsl/fs.js           LocalFileSystem subclass (9P backend + path dialects)
 lib/wsl/publish.js      The overwrite publication's wait bound (retry + measured tail; pure module, independently testable)
+lib/wsl/watch.js        Polling strategies for file watching (pure module, independently testable)
 lib/wsl/subprocess.js   SubprocessRuntime implementation (pipes + terminal; delegates to the host subprocess)
 lib/wsl/pty.js          Terminal handle: two processes driving the in-distro PTY bridge
 lib/wsl/terminal-bridge.py  The PTY bridge running inside the distro (python3 stdlib, zero install)

package/README.md

@@ -14,11 +14,11 @@
 ## 目录
 
 - **本页**：[目标能力](#目标能力) · [安装 / 更新 / 卸载](#安装--更新--卸载) · [快速开始](#快速开始) · [桌面更新纪律](#桌面更新纪律强制) · [安全与信任边界](#安全与信任边界) · [已知限制](#已知限制) · [校验](#校验) · [开发](#开发) · [发版](#发版)
-- **深入材料**：[安全与信任边界](SECURITY.md) · [架构与执行世界](docs/ARCHITECTURE.md) · [Linux 侧约束](docs/CONFINEMENT.md) · [fs 工具的围栏](docs/FS-FENCE.md) · [终端 PTY 桥](docs/PTY-BRIDGE.md) · [校验与 SKIP 裁定](docs/VERIFICATION.md) · [工程笔记](docs/ENGINEERING-NOTES.md) · [发行版支持矩阵](docs/DISTRO-SUPPORT.md) · [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) · [架构与流程图](docs/diagrams.md)
+- **深入材料**：[安全与信任边界](SECURITY.md) · [架构与执行世界](docs/ARCHITECTURE.md) · [Linux 侧约束](docs/CONFINEMENT.md) · [fs 工具的围栏](docs/FS-FENCE.md) · [终端 PTY 桥](docs/PTY-BRIDGE.md) · [WSL 文件变更监听](docs/WATCH.md) · [校验与 SKIP 裁定](docs/VERIFICATION.md) · [工程笔记](docs/ENGINEERING-NOTES.md) · [发行版支持矩阵](docs/DISTRO-SUPPORT.md) · [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) · [架构与流程图](docs/diagrams.md)
 
 ## 目标能力
 
-**活体验收通过后的诚实状态**（`verify-post-restart.mjs` 全绿 + 离线 18 套件；下面每条都注明证据强度）：
+**活体验收通过后的诚实状态**（`verify-post-restart.mjs` 全绿 + 离线 19 套件；下面每条都注明证据强度）：
 
 | # | 能力 | 状态 |
 |---|---|---|
@@ -73,10 +73,12 @@
 
 **约束覆盖不到 `/dev`、`/proc`、`/sys` 与 interop**，如实报在 `enforcement: 'partial'` 里；而会话用户保留的免密 sudo 授权可绕过文件围栏，闭合路径见 [SECURITY.md](SECURITY.md)。
 
+**WSL 工作区里的文件变更跟踪是轮询的，不是事件驱动的。** 发行版的 9P 共享上 `fs.watch` 会抛 `EISDIR`（文件与目录目标都抛），宿主后端的 chokidar 监听因此在 WSL 目标上根本无法初始化；插件改为在宿主侧轮询——目录看条目集合（每 300ms 一次 `readdir`，实测本进程 0ms CPU/3s、延迟 2–3ms），文件与尚不存在的路径走 `fs.watchFile`（每 300ms 一次 `stat`，实测 0ms CPU/3s、延迟 52ms）。**目录目标只对条目集合变化失效**：新增、删除、改名可见，目录内某个文件的**内容**变化不可见——要盯着某个文件，就按文件路径监听它。机制、实测与未测项见 [WSL 文件变更监听](docs/WATCH.md)。
+
 ## 校验
 
 ```powershell
-node scripts/verify-all.mjs          # 全部离线套件（18 个）
+node scripts/verify-all.mjs          # 全部离线套件（19 个）
 node scripts/verify-all.mjs --live   # 追加需要已安装插件 + 运行中宿主的套件
 ```
 
@@ -104,6 +106,7 @@ lib/wsl/world.js        发行版发现、wsl.exe 执行核、目录事实
 lib/wsl/shell.js        ShellExecutor 实现（WSL bash + 约束接入）
 lib/wsl/fs.js           LocalFileSystem 子类（9P 后端 + 路径方言）
 lib/wsl/publish.js      覆盖发布的等待边界（重试 + 实测尾部；纯模块，可独立测试）
+lib/wsl/watch.js        文件变更监听的轮询策略（纯模块，可独立测试）
 lib/wsl/subprocess.js  SubprocessRuntime 实现（管道 + 终端；委托宿主 subprocess）
 lib/wsl/pty.js         终端句柄：两个进程驱动发行版内的 PTY 桥
 lib/wsl/terminal-bridge.py 发行版内运行的 PTY 桥（python3 标准库，零安装）

package/lib/client.js

@@ -20,6 +20,9 @@
 window.__ModuleLoader__.load({
   id: 'dsh-wsl-desktop',
   factory() {
+    // MUST stay equal to the host half's Config.routePath default (lib/index.js).
+    // Nothing derives one from the other: a deployment that mounts the route
+    // elsewhere loses the picker silently.
     const ENDPOINT = '/wsl-desktop/api'
 
     /**
@@ -268,12 +271,10 @@ window.__ModuleLoader__.load({
        * workspace be created and a session opened after the operator cancelled.
        */
       function close() {
+        // The guard is the ONLY difference from forceClose(); the teardown itself is
+        // that function's, so the two cannot drift apart.
         if (state.closed || state.working) return
-        state.closed = true
-        state.token += 1
-        document.removeEventListener('keydown', onKey)
-        overlay.remove()
-        teardown = null
+        forceClose()
       }
 
       /** Close the picker regardless of an in-flight commit, once it settles. */

package/lib/index.js

@@ -5,14 +5,16 @@
  *
  * 1. Answer the browser's WSL questions over the same-origin route — the
  *    browser cannot run `wsl.exe`.
- * 2. Materialize the WSL agent presets into the user preset root. A session's
- *    execution world is chosen by its preset, so this is what lets one Desktop
- *    instance run Windows workspaces and WSL workspaces side by side.
+ * 2. Derive and register the WSL agent presets in the runtime preset registry. A
+ *    session's execution world is chosen by its preset, so this is what lets one
+ *    Desktop instance run Windows workspaces and WSL workspaces side by side.
+ *    (Before 0.1.7 this half MATERIALIZED them into the user preset root; the
+ *    registry owns them now, and nothing under $DSH_HOME is written.)
  * @module dsh-wsl-desktop
  */
 
 import { randomBytes, timingSafeEqual } from 'node:crypto'
-import { existsSync } from 'node:fs'
+import { existsSync, watch as nativeFsWatch } from 'node:fs'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -25,6 +27,7 @@ import { buildVariantPlugins } from './wsl/preset.js'
 import { setLocalSubprocess } from './wsl/host-refs.js'
 import { checkLinuxPath, defaultDistro, defaultWorkspaceUnc, listDistros, listLinuxDir, resolveDistroHome, runWslShell } from './wsl/world.js'
 import { joinWslUnc, parseWslUnc, windowsToMntPath } from './wsl/paths.js'
+import { WATCH_INTERVAL_MS } from './wsl/watch.js'
 
 /** Loader row identity, also used in diagnostics. */
 export const name = 'wsl-desktop'
@@ -44,6 +47,9 @@ export const Config = z.object({
    * generation can be mounted beside a running one, which is how the host half
    * is exercised without restarting the application.
    */
+  // MUST stay equal to the browser half's ENDPOINT (lib/client.js): nothing derives
+  // one from the other, and a deployment that mounts the route elsewhere loses the
+  // picker silently — the failure this default is the only record of.
   routePath: z.string().default('/wsl-desktop/api'),
   /**
    * Path to `wsl.exe`. Every probe this half runs spawns it — discovery, directory
@@ -78,6 +84,20 @@ const SELF_MODULE = fileURLToPath(import.meta.url)
 /** Prefix of every preset this plugin owns; its own outputs are never sources. */
 const GENERATED_PREFIX = 'wsl-'
 
+/**
+ * The generated variant id for a resolved base preset.
+ *
+ * A preset that is already a variant keeps its id; anything else gets the prefix. The
+ * selftest and createWorkspace both derived it this way — the second site's own comment
+ * admitted it resolved exactly like the first — so a change to the prefix rule had two
+ * homes.
+ * @param {{ id: string }} preset - the resolved base preset.
+ * @returns {string} the variant id.
+ */
+function variantIdFor(preset) {
+  return preset.id.startsWith(GENERATED_PREFIX) ? preset.id : `${GENERATED_PREFIX}${preset.id}`
+}
+
 /**
  * Module specifiers of the WSL providers, as the preset rows must name them.
  * The 0.1.7 loader imports row names via `new URL(name, baseUrl)` or a bare
@@ -203,6 +223,24 @@ function basePluginsOf(presets, id) {
  *   refuses duplicates).
  * @returns {Promise<object>} the registration outcome for the route.
  */
+/**
+ * Run a shell spec through whichever seam the host exposes, and always hand back a
+ * handle whose `result()` is awaitable.
+ *
+ * 0.1.7 hosts expose `execute`, which resolves with a live handle; older ones have
+ * only `run`, whose settled result carries no `result()` projection. Both selftest
+ * steps used to spell that dual dispatch themselves, and the second one called
+ * `.result()` on `run`'s settled result — a TypeError on exactly the hosts that
+ * branch exists to support. One owner, so the two steps cannot drift again.
+ * @param {object} shell - the realm's shell service.
+ * @param {object} spec - the resolved spec to run.
+ * @returns {Promise<{ result: () => Promise<object> }>} a result()-able handle.
+ */
+function runShellSpec(shell, spec) {
+  if (typeof shell.execute === 'function') return shell.execute(spec)
+  return shell.run(spec).then((settled) => ({ result: async () => settled }))
+}
+
 async function materializePresets(ctx, distro, generation, previous) {
   const presets = ctx.get('agentPresets')
   if (presets === undefined) throw new Error('agentPresets 服务不可用')
@@ -213,9 +251,16 @@ async function materializePresets(ctx, distro, generation, previous) {
   if (hostCompat.registry07 !== true) {
     throw new Error('需要 DSH Desktop 0.1.7+：当前宿主的 agentPresets 缺少 readDocument（0.1.6 及以下不受支持）。请升级桌面，或使用 0.1.6 兼容的插件版本。')
   }
-  if (generation?.disposed) return { status: 'ready', hostCompat, written: [], skipped: [{ id: '-', reason: '插件已卸载，放弃本轮注册' }] }
+  /**
+   * The answer a round gives when its generation was torn down mid-flight: the preset
+   * surface stays READY (the previous generation is still registered), nothing is
+   * written, and the skip says why. Spelled once — it stood three times, so the
+   * wording and the shape each had three homes.
+   */
+  const abandonedRound = () => ({ status: 'ready', hostCompat, written: [], skipped: [{ id: '-', reason: '插件已卸载，放弃本轮注册' }] })
+  if (generation?.disposed) return abandonedRound()
   const roster = await presets.list()
-  if (generation?.disposed) return { status: 'ready', hostCompat, written: [], skipped: [{ id: '-', reason: '插件已卸载，放弃本轮注册' }] }
+  if (generation?.disposed) return abandonedRound()
   const written = []
   const skipped = []
 
@@ -223,7 +268,7 @@ async function materializePresets(ctx, distro, generation, previous) {
   for (const [id, dispose] of previous?.disposers ?? []) {
     try { await dispose() } catch { /* already gone */ }
     previous?.disposers.delete(id)
-    if (generation?.disposed) return { status: 'ready', hostCompat, written: [], skipped: [{ id: '-', reason: '插件已卸载，放弃本轮注册' }] }
+    if (generation?.disposed) return abandonedRound()
   }
 
   for (const preset of roster) {
@@ -410,9 +455,7 @@ const METHODS = {
     const presets = hostCtx?.get('agentPresets')
     if (presets === undefined) throw new Error('agent presets 尚不可用')
     const resolved = await presets.resolve(base)
-    const agentPreset = resolved.id.startsWith(GENERATED_PREFIX)
-      ? resolved.id
-      : `${GENERATED_PREFIX}${resolved.id}`
+    const agentPreset = variantIdFor(resolved)
     const roster = await presets.list()
     const variant = roster.find((preset) => preset.id === agentPreset)
     if (variant === undefined) throw new Error(`WSL 预设 ${agentPreset} 尚未生成`)
@@ -550,8 +593,9 @@ const METHODS = {
         // failure would abort the whole selftest.
         const spec = shell.resolve({ command: 'uname -s; pwd; id -un; echo "$WSL_DISTRO_NAME"', workdir: workspaceCwd })
         // 0.1.7: execute resolves with a live handle; the settled result is
-        // its memoized result() projection. Dual-dispatch for older hosts.
-        const execution = await (typeof shell.execute === 'function' ? shell.execute(spec) : (async () => { const r = await shell.run(spec); return { result: async () => r } })())
+        // its memoized result() projection. Dual-dispatch for older hosts — one
+        // owner, runShellSpec, shared with the confined step below.
+        const execution = await runShellSpec(shell, spec)
         const result = await execution.result()
         record('shell.run', {
           exitCode: result?.exitCode,
@@ -591,6 +635,108 @@ const METHODS = {
         } catch (error) {
           record('fs.roundtrip', { error: error instanceof Error ? error.message : String(error) })
         }
+
+        // Watch rows: the strategy the provider installs, driven the way a consumer
+        // drives it, and mutated from INSIDE the distribution — the case the rows are
+        // about. No model-facing tool reaches `fs.watch`, so the provider's own entry
+        // is the only place this can be observed.
+        if (fs !== undefined && shell !== undefined && typeof workspaceCwd === 'string' && workspaceCwd.startsWith('\\\\wsl.localhost\\')) {
+          /**
+           * The policy every mutation below carries. A request that omits `sandboxPolicy`
+           * makes `bash-sandbox`'s `resolve()` substitute the session-less default, and the
+           * confinement then binds a root that does NOT contain this scratch workspace —
+           * measured: every mutation failed EROFS ("Read-only file system"). The fallback is
+           * not a MISSING root: `lib/wsl/confinement.js` binds the command's cwd when a policy
+           * carries none. It is a root from the deployment's own world, which
+           * `lib/wsl/paths.js` maps to `/mnt/<drive>/…`. The tool layer never meets this
+           * because `tool-bash` stamps the resolved policy into its request; a direct
+           * provider call has to stamp it itself.
+           */
+          const workspaceWritePolicy = { mode: 'workspace-write', workspaceRoot: workspaceCwd }
+
+          /**
+           * Arm one watch, mutate the target from the distribution, report what arrived.
+           * @param {{ targetKey: string }} target - the resolved watch target.
+           * @param {string} command - the shell command that changes it.
+           * @returns {Promise<object>} the observation row.
+           */
+          const observeWatch = async (target, command) => {
+            const controller = new AbortController()
+            const linuxPath = fs.processPath(target)
+            let notified = 0
+            let watchError = null
+            let unwatch
+            try {
+              unwatch = await fs.watch(target, (error) => {
+                if (error === undefined) notified += 1
+                else watchError = String(error?.message ?? error)
+              }, controller.signal)
+              const execution = await runShellSpec(shell, shell.resolve({ command, workdir: workspaceCwd, sandboxPolicy: workspaceWritePolicy }))
+              // The mutation's outcome is REPORTED, not assumed. A refused write otherwise
+              // leaves `notified: 0` with a null `watchError`, which reads exactly like a
+              // watcher that armed and observed nothing — two different facts this row must
+              // not conflate.
+              const result = await execution.result()
+              if (result.exitCode !== 0) {
+                const failure = `the mutation failed: exit ${result.exitCode ?? 'null'} ${(result.stderr?.text ?? '').slice(0, 200)}`.trim()
+                // Both facts survive: a watcher error and a failed mutation can coexist, and
+                // reporting only one of them drops the other from the row.
+                watchError = watchError === null ? failure : `${watchError}; ${failure}`
+              }
+              // The window is 5 polling periods: measured latency is 2-52ms, so 1500ms is
+              // ~29x the slowest measured case, and a poll that never runs still reddens.
+              await new Promise((resolve) => setTimeout(resolve, 5 * WATCH_INTERVAL_MS))
+            } catch (error) {
+              watchError = error instanceof Error ? error.message : String(error)
+            } finally {
+              controller.abort()
+              if (unwatch !== undefined) await unwatch().catch(() => {})
+            }
+            return { notified, watchError, linuxPath }
+          }
+
+          // The probe file EXISTS before the watch is armed — that is the point of the row.
+          // `fs.watchFile` on an ABSENT path notifies once immediately at arming (measured
+          // Node semantics, pinned offline in scripts/verify-watch.mjs, because an injected
+          // io can never fire by itself: only the default seam shows the baseline is real).
+          // With the file absent, `notified > 0` would be satisfied by that arming baseline
+          // alone — even if the in-distribution append below were never observed. An
+          // existing file is silent until it changes, so a notification here can only be
+          // the append.
+          const fileTarget = await fs.resolve('dsh-wsl-watch-probe.txt', { cwd: workspaceCwd })
+          // Created through the shell this block already runs its mutations with. A create
+          // that FAILED must not read as a false green, so its outcome is reported in the
+          // row: an absent path would notify from its arming baseline and pass on nothing.
+          const probeCreated = await runShellSpec(shell, shell.resolve({ command: `printf 'x\\n' > '${fs.processPath(fileTarget)}'`, workdir: workspaceCwd, sandboxPolicy: workspaceWritePolicy }))
+            .then((execution) => execution.result())
+            .catch((error) => ({ exitCode: null, stderr: { text: String(error?.message ?? error) } }))
+          record('fs.watch.file', probeCreated.exitCode === 0
+            ? await observeWatch(fileTarget, `printf 'x\\n' >> '${fs.processPath(fileTarget)}'`)
+            : {
+              notified: 0,
+              watchError: `the probe file could not be created: exit ${probeCreated.exitCode ?? 'null'} ${probeCreated.stderr?.text?.slice(0, 200) ?? ''}`.trim(),
+              linuxPath: fs.processPath(fileTarget),
+            })
+
+          const dirTarget = await fs.resolve('.', { cwd: workspaceCwd })
+          const dirCommand = `printf 'x\\n' > '${fs.processPath(dirTarget)}/dsh-wsl-watch-entry.txt'`
+          record('fs.watch.dir', await observeWatch(dirTarget, dirCommand))
+          await runShellSpec(shell, shell.resolve({ command: `rm -f '${fs.processPath(dirTarget)}/dsh-wsl-watch-entry.txt'`, workdir: workspaceCwd, sandboxPolicy: workspaceWritePolicy }))
+            .then((execution) => execution.result()).catch(() => {})
+
+          // Why the override exists, recorded rather than assumed: if a future host or
+          // WSL release makes this work, this row says so and the override can go.
+          let nativeThrew = false
+          let nativeCode = null
+          try {
+            const probe = nativeFsWatch(fileTarget.targetKey, () => {})
+            probe.close()
+          } catch (error) {
+            nativeThrew = true
+            nativeCode = error?.code ?? null
+          }
+          record('fs.watch.native', { threw: nativeThrew, code: nativeCode, path: fileTarget.targetKey })
+        }
       }
 
       const subprocess = realmService('subprocess')
@@ -609,8 +755,8 @@ const METHODS = {
       }
 
       if (shell !== undefined) {
-        const exec = typeof shell.execute === 'function' ? shell.execute.bind(shell) : shell.run.bind(shell)
-        const execution = await exec(
+        const execution = await runShellSpec(
+          shell,
           shell.resolve({ command: 'echo blocked > /dsh-wsl-forbidden.txt', workdir: workspaceCwd }),
         ).catch((error) => ({ result: async () => ({ exitCode: null, stderr: { text: String(error?.message ?? error) }, sandbox: null }) }))
         const confined = await execution.result()
@@ -816,9 +962,7 @@ const METHODS = {
       const presets = hostCtx.get('agentPresets')
       if (presets !== undefined) {
         const resolved = await presets.resolve()
-        const candidate = resolved.id.startsWith(GENERATED_PREFIX)
-          ? resolved.id
-          : `${GENERATED_PREFIX}${resolved.id}`
+        const candidate = variantIdFor(resolved)
         const roster = await presets.list()
         if (roster.some((preset) => preset.id === candidate && preset.broken === undefined)) presetId = candidate
       }
@@ -961,7 +1105,7 @@ async function isDeveloperCaller(req, config) {
 /**
  * Register the WSL route and generate the WSL presets.
  * @param {import('@deepseek-ai/cordis').Context} ctx - the plugin context.
- * @param {{ routePath: string, developerTools: boolean }} config - resolved plugin config.
+ * @param {{ routePath: string, developerTools: boolean, wslPath?: string }} config - resolved plugin config.
  */
 export function apply(ctx, config) {
   hostCtx = ctx

package/lib/wsl/confinement.js

@@ -20,11 +20,6 @@
  */
 
 import { shellQuote } from './paths.js'
-import { fileURLToPath } from 'node:url'
-import { dirname, join } from 'node:path'
-
-/** Shipped helper script, installed by the operator (see docs/CONFINEMENT.md). */
-export const HELPER_SOURCE = join(dirname(fileURLToPath(import.meta.url)), 'dsh-wsl-confine.sh')
 
 /** The direct runner: sudo-wrapped unshare with the fence built in-process. */
 export const RUNNER_SUDO_UNSHARE = 'sudo-unshare'
@@ -181,10 +176,11 @@ function helperGateScript(helperPath) {
     'ok=yes',
     // TYPE FIRST, and by an explicit test rather than by 'test -x': a root:root
     // 0755 DIRECTORY satisfies -x, uid 0, no write bits and every ancestor test,
-    // so the ownership predicate answered yes for a directory — measured, as
-    // zcluo, with /opt/.../dir-helper (drwxr-xr-x root root). Only the version
-    // half refused it, and only because sudo cannot exec a directory. The gate
-    // claims to require an executable FILE; this is where it measures that.
+    // so the ownership predicate answered yes for a directory — measured, as an
+    // ordinary (non-root) user, with /opt/.../dir-helper (drwxr-xr-x root root).
+    // Only the version half refused it, and only because sudo cannot exec a
+    // directory. The gate claims to require an executable FILE; this is where it
+    // measures that.
     '[ -f "$f" ] || ok=no',
     // A symlink is REFUSED, not resolved. The grant names a PATH, so the link
     // and its target are both part of the trust decision: resolving would have
@@ -207,9 +203,9 @@ function helperGateScript(helperPath) {
     'u=$(stat -c %u "$f" 2>/dev/null) || u=',
     'm=$(stat -c %a "$f" 2>/dev/null) || m=',
     '[ "$u" = 0 ] || ok=no',
-    '[ -n "$m" ] || ok=no',
     // A mode stat cannot report (or one that is not octal) must refuse, not
-    // error out silently: the arithmetic parse is guarded by the non-empty test.
+    // error out silently: the arithmetic parse is guarded by its own non-empty
+    // test, which is why no separate [ -n "$m" ] refusal stands above it.
     '[ -n "$m" ] && (( (8#$m & 022) == 0 )) || ok=no',
     '[ -w "$f" ] && ok=no',
     'd=$(dirname "$f")',
@@ -317,7 +313,9 @@ export async function detectRunner({ distro, username, run }) {
 }
 
 /**
- * Forget cached probe results. Used by tests and by a settings change.
+ * Forget cached probe results. Used by the verification suites — no settings change
+ * calls it (the doc claimed one did; the only caller in the tree is
+ * scripts/verify-confinement.mjs).
  */
 export function resetConfinementCache() {
   identityCache.clear()
@@ -421,7 +419,7 @@ export async function detectNoNewPrivs({ distro, username, run }) {
  * unconditionally (dsh-wsl-confine.sh), so on a setpriv without the flag setpriv
  * rejects the unknown option and exits 1 — the confined command simply does not
  * run, and that is an ordinary COMMAND failure, not the setup-failure marker
- * that reports an unavailable runner. docs/CONFINEMENT.md:33 records the measured exit 1;
+ * that reports an unavailable runner. docs/CONFINEMENT.md:31 records the measured exit 1;
  * this text previously contradicted it by recommending the helper as a remedy.
  *
  * The remedy names the PROBEABLE requirement, not a version: the util-linux release
@@ -668,7 +666,10 @@ function postConditions(keep) {
  * @param {string} options.linuxCwd - absolute Linux working directory.
  * @param {'read-only' | 'workspace-write'} options.mode - the confined mode.
  * @param {string | undefined} options.workspaceLinuxRoot - writable root for `workspace-write`.
- * @param {{ uid: string, gid: string }} options.identity - identity to drop back to.
+ * @param {{ uid: string, gid: string, home: string, name?: string }} options.identity -
+ *   identity to drop back to; `home` and `name` are read for the environment.
+ * @param {boolean | undefined} options.noNewPrivs - whether the runner supports
+ *   `setpriv --no-new-privs`; adds the flag to the drop-back when true.
  * @returns {string} the script to run inside the namespace.
  */
 export function buildNamespaceScript({ command, linuxCwd, mode, workspaceLinuxRoot, identity, noNewPrivs }) {
@@ -726,7 +727,8 @@ export function buildNamespaceScript({ command, linuxCwd, mode, workspaceLinuxRo
  * @param {string} options.linuxCwd - absolute Linux working directory.
  * @param {'read-only' | 'workspace-write'} options.mode - the confined mode.
  * @param {string | undefined} options.workspaceLinuxRoot - writable root for `workspace-write`.
- * @param {{ uid: string, gid: string }} options.identity - identity to drop back to.
+ * @param {{ uid: string, gid: string, home: string, name?: string }} options.identity -
+ *   identity to drop back to; `home` and `name` are read for the environment.
  * @param {boolean} [options.noNewPrivs] - set NO_NEW_PRIVS on the drop when the
  *   distro's setpriv supports it (blocks setuid elevation inside the fence).
  * @param {string} [options.runner] - the resolved runner: 'helper' routes the

package/lib/wsl/fs.js

@@ -26,6 +26,7 @@ import z from '@deepseek-ai/schemastery'
 import { crossDistroUnc, isUnderHost, writableHostRootsFor } from './fence.js'
 import { isWindowsPathShaped, joinWslUnc, mntToWindowsPath, parseWslUnc, windowsToMntPath } from './paths.js'
 import { publishReplace } from './publish.js'
+import { startWatch, watchStrategyFor } from './watch.js'
 
 /** Share-level errors that mean "this primitive is unavailable", not "the operation failed". */
 const PRIMITIVE_UNAVAILABLE = new Set(['ENOTSUP', 'EOPNOTSUPP', 'EPERM', 'EINVAL'])
@@ -83,11 +84,24 @@ export function toHostPath(value, cwd, fallbackDistro) {
  * @returns {string} the Linux spelling when one exists, else the input.
  */
 export function toLinuxPath(value) {
+  return toLinuxPathOrNull(value) ?? value
+}
+
+/**
+ * The Linux spelling of a host path, or undefined when one does not exist.
+ *
+ * The ONE place the UNC/drive translation is written: `toLinuxPath` and the fs
+ * backend's `processPathFromHostPath` differ only in the sentinel they answer for an
+ * unrepresentable path (the input vs undefined), and spelling the translation twice
+ * meant a fix could land in one copy only.
+ * @param {string} value - a host path on the share or a drive path.
+ * @returns {string | undefined} the normalized Linux path, or undefined.
+ */
+function toLinuxPathOrNull(value) {
   const unc = parseWslUnc(value)
   if (unc !== null) return posix.normalize(unc.linuxPath)
   const drive = windowsToMntPath(value)
-  if (drive !== null) return posix.normalize(drive)
-  return value
+  return drive === null ? undefined : posix.normalize(drive)
 }
 
 /**
@@ -220,6 +234,33 @@ export class WslFileSystem extends LocalFileSystem {
     throw new FsError(`cannot write "${target.displayPath}": file access denied under ${deniedUnder}`, 'FS_SANDBOX_DENIED')
   }
 
+  /**
+   * Observe one target through a strategy this share supports.
+   *
+   * Overridden because the inherited implementation cannot initialize here: it
+   * watches a DIRECTORY in both branches (the target, or a file target's `dirname`)
+   * and its primitive, `fs.watch`, throws `EISDIR` on `\\wsl.localhost\…` — for a
+   * file target as well as a directory one (measured; docs/WATCH.md). Unoverridden,
+   * `ctx.fs.watch` rejects for every WSL target and the workspace file tree keeps
+   * only manual refresh.
+   *
+   * The host path comes from the TARGET KEY, never from `processPath`: that returns
+   * the LINUX spelling for the model and for subprocesses, so resolving it on this
+   * side would put a watcher on `E:\home\…` for `/home/…` — observing something else
+   * entirely, and silently, since the wrong path usually does not exist.
+   * @param {{ targetKey: string }} target - the resolved target.
+   * @param {(error?: Error) => void} changed - invalidation callback.
+   * @param {AbortSignal} signal - cancels watcher initialization.
+   * @returns {Promise<() => Promise<void>>} the disposer once observation is active.
+   */
+  async watch(target, changed, signal) {
+    signal.throwIfAborted()
+    const info = await this.stat(target, signal)
+    signal.throwIfAborted()
+    const kind = info?.type === 'directory' ? 'directory' : info === undefined ? 'absent' : 'file'
+    return startWatch({ hostPath: target.targetKey, strategy: watchStrategyFor(kind), changed, signal })
+  }
+
   /**
    * Fence the write by the per-call policy, then delegate to the inherited
    * atomic write with the checked target.
@@ -288,10 +329,7 @@ export class WslFileSystem extends LocalFileSystem {
    */
   processPathFromHostPath(hostPath) {
     if (typeof hostPath !== 'string' || hostPath.length === 0) return undefined
-    const unc = parseWslUnc(hostPath)
-    if (unc !== null) return posix.normalize(unc.linuxPath)
-    const drive = windowsToMntPath(hostPath)
-    return drive === null ? undefined : posix.normalize(drive)
+    return toLinuxPathOrNull(hostPath)
   }
 
   /**

package/lib/wsl/preset.js

@@ -259,18 +259,20 @@ export const WSL_PERSONA_SENTENCE = 'Paths under \\\\wsl.localhost\\<distro> are
 /**
  * Append the WSL path-dialect sentence to a persona row OBJECT.
  * @param {object} row - the persona entry.
- * @returns {boolean} whether the row was amended.
+ *
+ * The row is ALWAYS amended — a string field is extended when one exists and `suffix`
+ * is created when none does — so this returns nothing. It used to document and return
+ * "whether the row was amended" (always true, and its only caller discards it).
  */
 function appendPersonaSuffixObject(row) {
   const config = row.config ?? (row.config = {})
   for (const field of ['suffix', 'text', 'prefix']) {
     if (typeof config[field] === 'string' && config[field].length > 0) {
       config[field] = `${config[field]} ${WSL_PERSONA_SENTENCE}`
-      return true
+      return
     }
   }
   config.suffix = WSL_PERSONA_SENTENCE
-  return true
 }
 
 /**
@@ -344,8 +346,11 @@ export function buildVariantPlugins(basePlugins, { subprocessPath, shellPath, fs
       unclassified.push({ id: row.id ?? null, name: row.name ?? null })
     } else if (isHostWorldModule(row.name)) {
       removed.push(row.id ?? row.name)
-      if (row.name.includes('str-replace-editor')) includeEditor = true
-      if (row.name.includes('str-replace-editor') && row.config !== undefined) {
+      // One evaluation, two uses: the predicate stood on adjacent lines, so a future
+      // edit to one of them would silently leave the other behind.
+      const isEditor = row.name.includes('str-replace-editor')
+      if (isEditor) includeEditor = true
+      if (isEditor && row.config !== undefined) {
         toolConfig.set('str-replace-editor', cloneRow({ config: row.config }).config)
       }
       return null

package/lib/wsl/pty.js

@@ -318,7 +318,22 @@ export async function spawnWslTerminal({
   }
 
   const stderr = data.stderr
-  if (stderr === undefined) throw new Error('wsl-pty: 数据进程没有 stderr，无法承载控制应答')
+  if (stderr === undefined) {
+    // This guard throws BEFORE the allocation try below, so it used to escape with
+    // the data process still running — the very leak that try's catch exists to
+    // prevent. Same cleanup, minus `control`: it is not spawned yet at this point,
+    // and `control` is not even in scope here.
+    try {
+      data.terminate()
+    } catch {
+      // Already gone.
+    }
+    await Promise.allSettled([waitForHandle(data)])
+    // The bridge may already have created its FIFO before this check; rm -f is a
+    // no-op when it did not.
+    await cleanupFifo()
+    throw new Error('wsl-pty: 数据进程没有 stderr，无法承载控制应答')
+  }
   stderr.setEncoding('utf8')
   stderr.on('data', (chunk) => {
     replyBuffer += chunk
@@ -481,7 +496,7 @@ export async function spawnWslTerminal({
         control.terminate()
         data.terminate()
         failPending('wsl-pty: 会话已终止')
-        await Promise.allSettled([data.waitForExit?.() ?? waitForHandle(data), waitForHandle(control)])
+        await Promise.allSettled([waitForHandle(data), waitForHandle(control)])
         // AFTER both processes have settled, from the host side: the bridge's
         // own finally lost this race often enough to leave orphans behind.
         await cleanupFifo()

package/lib/wsl/shell.js

@@ -428,10 +428,13 @@ export class WslShellExecutor extends ShellExecutor {
       }
     }
     const emptyReader = { readFrom: () => ({ text: '', lossy: false, nextOffset: 0 }) }
-    /** The failure note the READ PATH must serve; filled in when a spawn fails. */
-    const spawnFailure = {
-      note: spawnError === undefined ? undefined : `subprocess failed before reporting an outcome: ${String(spawnError)}`,
-    }
+    /**
+     * The failure note the READ PATH must serve; assigned by settle() when a spawn
+     * fails. The holder starts bare on purpose: servesNote stays false until settle()
+     * has written note, so an initializer here could never reach a reader — the
+     * ternary that stood here built a string no branch could observe.
+     */
+    const spawnFailure = { note: undefined }
     const providerReaders = handle === undefined ? undefined : WslShellExecutor.readers(handle)
     const stdout = providerReaders?.stdout ?? emptyReader
     const baseStderr = providerReaders?.stderr ?? emptyReader

package/lib/wsl/subprocess.js

@@ -34,7 +34,7 @@ import { LoginShellUnresolvedError, WSL_CHILD_ENV, buildWslExecArgv, planWsl, re
 /**
  * The executable lookup's ceiling, on the documented probe policy.
  *
- * Was 15s and the shortest ceiling in the plugin. docs/CONFINEMENT.md:36 names
+ * Was 15s and the shortest ceiling in the plugin. docs/CONFINEMENT.md:34 names
  * `resolveExecutable` in the same sentence as 探针超时 60s + 超时后一次透明重试, and it is an
  * output-parsed probe like the siblings that sentence lists (the comment on the probe below
  * says so), so it gets the same 60s as `listLinuxDir`/`checkLinuxPath`/`resolveDistroHome`
@@ -46,6 +46,20 @@ const LOOKUP_TIMEOUT_MS = 60_000
 /** Windows shells whose names the terminal controller may probe inside the distribution. */
 const WINDOWS_SHELLS = new Set(['powershell', 'pwsh', 'cmd'])
 
+/**
+ * The basename a Windows-shell test compares: directories stripped, lowercased, a
+ * trailing `.exe` removed.
+ *
+ * ONE owner: the candidate lookup and the terminal-argv translation each spelled this
+ * pipeline, so a fix to either (a Windows path separator, a new extension) could land in
+ * one copy only. `value ?? ''` because one caller passes an optional argv element.
+ * @param {unknown} value - a program spelling.
+ * @returns {string} the comparable basename, or '' when there is nothing to compare.
+ */
+function shellBaseName(value) {
+  return String(value ?? '').split(/[\\/]/).pop()?.toLowerCase().replace(/\.exe$/, '') ?? ''
+}
+
 /** The PTY bridge shipped beside this module. */
 const BRIDGE_PATH = join(dirname(fileURLToPath(import.meta.url)), 'terminal-bridge.py')
 
@@ -167,7 +181,7 @@ export class WslSubprocessRuntime extends SubprocessRuntime {
       // shell (PowerShell on a Windows deployment) through THIS provider; in
       // the distribution that dialect-translates to the session user's login
       // shell. Absent any Windows shell, the login shell is the honest answer.
-      const base = String(command).split(/[\\/]/).pop()?.toLowerCase().replace(/\.exe$/, '') ?? ''
+      const base = shellBaseName(command)
       if (WINDOWS_SHELLS.has(base)) {
         try {
           return await resolveLoginShell(plan.distro, this.config.username, { wslPath: this.config.wslPath })
@@ -261,7 +275,7 @@ export class WslSubprocessRuntime extends SubprocessRuntime {
       // (PowerShell on Windows) through THIS provider; in the distribution
       // that dialect-translates to the session user's login shell — a lone
       // '-NoLogo' arg would kill bash, so the whole argv is translated.
-      const base0 = String(spec.argv?.[0] ?? '').split(/[\\/]/).pop()?.toLowerCase().replace(/\.exe$/, '') ?? ''
+      const base0 = shellBaseName(spec.argv?.[0])
       // Deliberately NOT translated into SubprocessExecutableNotFoundError the
       // way the candidate lookup above is. There is no candidate list here to
       // skip down — this spec named exactly ONE program — so the translation

package/lib/wsl/terminal-bridge.py

@@ -200,7 +200,12 @@ class Bridge:
     def activity(self):
         """Report busy when the foreground group is not the shell itself."""
         pgrp = self.foreground_pgrp()
-        state = "unknown" if pgrp is None else ("idle" if pgrp == self.shell_pgrp else "busy")
+        if pgrp is None:
+            state = "unknown"
+        elif pgrp == self.shell_pgrp:
+            state = "idle"
+        else:
+            state = "busy"
         if state != self.last_state:
             self.last_state = state
             self.revision += 1

package/lib/wsl/watch.js

@@ -0,0 +1,212 @@
+/**
+ * File watching for the distribution's 9P share.
+ *
+ * The share does not support the primitive the host backend is built on: `fs.watch`
+ * throws `EISDIR` on `\\wsl.localhost\…` for a DIRECTORY target and for a FILE target
+ * alike (measured; docs/WATCH.md). `LocalFileSystem.watch` watches a directory in
+ * both branches — the target, or a file target's `dirname` — so it cannot initialize
+ * here at all, and `ctx.fs.watch` rejects for every WSL target: the workspace's file
+ * tree loses its live refresh and keeps manual refresh only.
+ *
+ * This module is the strategy that does work over the share: user-space polling on
+ * `node:fs` alone. (chokidar is not importable: it is a transitive dependency of the
+ * host's fs-local, and this plugin declares no dependencies.)
+ *
+ * - `dir-entries` — one readdir per tick, comparing the entry-name set. Measured ~0ms
+ *   CPU per 3s and 2-3ms latency at 200 entries. Blind to a child's CONTENT change,
+ *   which is not what a consumer of a directory target asks for.
+ * - `path-stat` — `fs.watchFile` on one path. Measured ~0ms CPU per 3s and 52ms. Also
+ *   covers a file target and an absent path observed for creation.
+ * @module dsh-wsl-desktop/wsl/watch
+ */
+
+// `readdir` comes from the PROMISE surface, because the io seam calls it promise-style
+// (`await io.readdir(path)`) and the injected fake is async: the callback-style
+// `fs.readdir` throws ERR_INVALID_ARG_TYPE the moment it is handed no callback
+// (measured), so the same call that passes the suite would refuse every WSL target.
+// The stat poller's two calls are the callback surface's own and stay on `node:fs`.
+import { unwatchFile as nodeUnwatchFile, watchFile as nodeWatchFile } from 'node:fs'
+import { readdir as nodeReaddir } from 'node:fs/promises'
+
+/**
+ * The polling period of both strategies.
+ *
+ * A constant, not a config field: both strategies measured ~0ms CPU per 3s at 200
+ * entries, so there is no lever to hand an operator. If a deployment ever measures
+ * cost, this is the single place it would be turned.
+ */
+export const WATCH_INTERVAL_MS = 300
+
+/**
+ * The strategy for a target.
+ * @param {'directory' | 'file' | 'absent'} kind - what the target is right now.
+ * @returns {'dir-entries' | 'path-stat'} the strategy name.
+ */
+export function watchStrategyFor(kind) {
+  return kind === 'directory' ? 'dir-entries' : 'path-stat'
+}
+
+/**
+ * The comparison key of one directory reading.
+ * @param {readonly string[]} names - entry names, in any order.
+ * @returns {string} the key: sorted and NUL-joined.
+ */
+export function entrySetKey(names) {
+  return [...names].sort().join('\0')
+}
+
+/**
+ * Whether a directory reading differs from the previous one.
+ * @param {string | undefined} previousKey - the previous key; undefined before the first reading.
+ * @param {string} nextKey - this reading's key.
+ * @returns {boolean} true only when a baseline exists AND differs — the first reading
+ *   establishes the baseline silently, mirroring fs-local's `ignoreInitial: true`.
+ *   Without it every watch would report a change the moment it opens.
+ */
+export function entrySetChanged(previousKey, nextKey) {
+  return previousKey !== undefined && previousKey !== nextKey
+}
+
+/**
+ * The io and timer surface this module uses.
+ *
+ * NOT all of it is `node:fs`: `readdir` is the `node:fs/promises` surface, for the reason
+ * the import note above records, so "the default is node:fs" would name the wrong module
+ * for one of the three calls.
+ *
+ * Injectable so the suite drives ticks and IO by hand: with the real timers a check
+ * would have to sleep and race the poll it is measuring.
+ */
+const NODE_IO = {
+  readdir: nodeReaddir,
+  watchFile: nodeWatchFile,
+  unwatchFile: nodeUnwatchFile,
+  setInterval: globalThis.setInterval,
+  clearInterval: globalThis.clearInterval,
+}
+
+/**
+ * Read one directory reading as a key, answering an absent directory with the empty set.
+ *
+ * The contract observes a path for CREATION as well as for change, so a directory that
+ * is not there is an empty entry set rather than a failure — its deletion and its
+ * reappearance are both changes. One qualification: an EMPTY directory produces this same
+ * key, so an empty directory being created or removed notifies nobody (the limitation
+ * `docs/WATCH.md` states). Every other error belongs to the caller.
+ * @param {string} hostPath - the target's host path.
+ * @param {object} io - the io seam.
+ * @returns {Promise<string>} the entry-set key.
+ */
+async function readEntryKey(hostPath, io) {
+  try {
+    return entrySetKey(await io.readdir(hostPath))
+  } catch (error) {
+    if (error?.code === 'ENOENT') return ''
+    throw error
+  }
+}
+
+/**
+ * One close path for both strategies: idempotent, stops the strategy, detaches the
+ * abort listener it added.
+ *
+ * The base contract uses `signal` to cancel INITIALIZATION only — the caller closes an
+ * initialized watcher. Stopping an active poll on a later abort as well is a deliberate
+ * superset: a leaked poller costs a syscall every interval forever, and the disposer is
+ * idempotent, so honouring a late abort cannot double-close.
+ * @param {() => void} stop - the strategy's own teardown.
+ * @param {AbortSignal} signal - the signal the caller passed.
+ * @returns {() => Promise<void>} the disposer.
+ */
+function makeDisposer(stop, signal) {
+  let stopped = false
+  const onAbort = () => { void dispose() }
+  /**
+   * Stop observing.
+   * @returns {Promise<void>} once stopped.
+   */
+  function dispose() {
+    if (stopped) return Promise.resolve()
+    stopped = true
+    stop()
+    signal.removeEventListener('abort', onAbort)
+    return Promise.resolve()
+  }
+  signal.addEventListener('abort', onAbort, { once: true })
+  return dispose
+}
+
+/**
+ * Poll one directory's direct entries.
+ * @param {object} options - as {@link startWatch}.
+ * @returns {Promise<() => Promise<void>>} the disposer once the baseline is read.
+ */
+async function startDirEntries({ hostPath, changed, signal, intervalMs, io }) {
+  let previousKey
+  let ticking = false
+  let stopped = false
+
+  /**
+   * One poll: read the entries, compare, notify at most once.
+   * @returns {Promise<void>} once this tick has settled.
+   */
+  const tick = async () => {
+    if (ticking || stopped) return
+    ticking = true
+    try {
+      const key = await readEntryKey(hostPath, io)
+      const previous = previousKey
+      previousKey = key
+      if (entrySetChanged(previous, key)) changed()
+    } catch (error) {
+      changed(error instanceof Error ? error : new Error(String(error)))
+    } finally {
+      ticking = false
+    }
+  }
+
+  // The baseline is read BEFORE the watch reports itself active: a change landing
+  // between the call and the first tick must be a change, not the baseline. It also
+  // makes initialization fail loudly for a path that can never be read, which is what
+  // the base contract's `@throws cannot initialize` asks for.
+  previousKey = await readEntryKey(hostPath, io)
+  signal.throwIfAborted()
+  // The callback RETURNS the tick's promise rather than discarding it (`void tick()`):
+  // the real `setInterval` ignores a callback's return value, while the injected seam
+  // hands it back, and only a poll the seam hands back can be awaited. `tick` reports
+  // every failure through `changed`, so nothing is left unhandled either way.
+  const timer = io.setInterval(() => tick(), intervalMs)
+  return makeDisposer(() => { stopped = true; io.clearInterval(timer) }, signal)
+}
+
+/**
+ * Watch one path's stat.
+ * @param {object} options - as {@link startWatch}.
+ * @returns {() => Promise<void>} the disposer.
+ */
+function startPathStat({ hostPath, changed, signal, intervalMs, io }) {
+  const listener = () => { changed() }
+  io.watchFile(hostPath, { interval: intervalMs, persistent: true }, listener)
+  // The listener goes to `unwatchFile` so only THIS registration is removed: Node
+  // refcounts one StatWatcher per path, and `unwatchFile(path)` without a listener
+  // would drop every consumer watching that same path.
+  return makeDisposer(() => io.unwatchFile(hostPath, listener), signal)
+}
+
+/**
+ * Observe one target through a strategy the share supports.
+ * @param {object} options - the watch request.
+ * @param {string} options.hostPath - the target's HOST path (a UNC spelling for WSL).
+ * @param {'dir-entries' | 'path-stat'} options.strategy - from {@link watchStrategyFor}.
+ * @param {(error?: Error) => void} options.changed - the invalidation callback.
+ * @param {AbortSignal} options.signal - cancels initialization.
+ * @param {number} [options.intervalMs] - the polling period.
+ * @param {object} [options.io] - the io seam; defaults to `NODE_IO` — `readdir` from
+ *   `node:fs/promises`, the stat poller from `node:fs`, and the real timers.
+ * @returns {Promise<() => Promise<void>>} the disposer once observation is active.
+ */
+export async function startWatch({ hostPath, strategy, changed, signal, intervalMs = WATCH_INTERVAL_MS, io = NODE_IO }) {
+  signal.throwIfAborted()
+  if (strategy === 'path-stat') return startPathStat({ hostPath, changed, signal, intervalMs, io })
+  return startDirEntries({ hostPath, changed, signal, intervalMs, io })
+}

package/lib/wsl/world.js

@@ -225,6 +225,37 @@ export async function listDistros({ wslPath = 'wsl.exe' } = {}) {
     .filter((line) => line.length > 0)
 }
 
+/**
+ * The Lxss registry values and the two REG_SZ lines the default-distribution read needs.
+ *
+ * The patterns live HERE, once, because the async and the sync reader each carried their
+ * own copy: a registry-format change had two homes, and only one of them was exercised by
+ * whichever caller the operator happened to hit.
+ */
+const DEFAULT_DISTRIBUTION_VALUE = 'DefaultDistribution'
+const DISTRIBUTION_NAME_VALUE = 'DistributionName'
+const GUID_PATTERN = /DefaultDistribution\s+REG_SZ\s+(\{[0-9a-fA-F-]+\})/iu
+const NAME_PATTERN = /DistributionName\s+REG_SZ\s+(.+)/iu
+
+/**
+ * The distribution a `DistributionName` line names.
+ * @param {unknown} output - the registry query's stdout.
+ * @returns {string | undefined} the name, or undefined when the line names none.
+ */
+function distroFromRegistryOutput(output) {
+  const distro = NAME_PATTERN.exec(String(output))?.[1]?.trim()
+  return distro === undefined || distro === '' ? undefined : distro
+}
+
+/**
+ * The Lxss subkey a `DefaultDistribution` line names.
+ * @param {unknown} output - the registry query's stdout.
+ * @returns {string | undefined} the GUID, or undefined when the line names none.
+ */
+function guidFromRegistryOutput(output) {
+  return GUID_PATTERN.exec(String(output))?.[1]
+}
+
 /**
  * Read the user's default distribution from the Lxss registry. Non-fatal:
  * `undefined` when the value is absent or unreadable.
@@ -232,16 +263,15 @@ export async function listDistros({ wslPath = 'wsl.exe' } = {}) {
  */
 export async function defaultDistro() {
   try {
-    const value = await execFileAsync('reg.exe', ['query', LXSS_KEY, '/v', 'DefaultDistribution'], {
+    const value = await execFileAsync('reg.exe', ['query', LXSS_KEY, '/v', DEFAULT_DISTRIBUTION_VALUE], {
       timeout: DISCOVERY_TIMEOUT_MS,
     })
-    const guid = /DefaultDistribution\s+REG_SZ\s+(\{[0-9a-fA-F-]+\})/i.exec(String(value.stdout))?.[1]
+    const guid = guidFromRegistryOutput(value.stdout)
     if (guid === undefined) return undefined
-    const name = await execFileAsync('reg.exe', ['query', `${LXSS_KEY}\\${guid}`, '/v', 'DistributionName'], {
+    const name = await execFileAsync('reg.exe', ['query', `${LXSS_KEY}\\${guid}`, '/v', DISTRIBUTION_NAME_VALUE], {
       timeout: DISCOVERY_TIMEOUT_MS,
     })
-    const distro = /DistributionName\s+REG_SZ\s+(.+)/i.exec(String(name.stdout))?.[1]?.trim()
-    return distro === undefined || distro === '' ? undefined : distro
+    return distroFromRegistryOutput(name.stdout)
   } catch {
     // A missing or unreadable registry value leaves the caller its own fallback.
     return undefined
@@ -261,16 +291,15 @@ export function defaultDistroSync() {
   if (syncDefaultResolved) return syncDefault
   syncDefaultResolved = true
   try {
-    const value = execFileSync('reg.exe', ['query', LXSS_KEY, '/v', 'DefaultDistribution'], {
+    const value = execFileSync('reg.exe', ['query', LXSS_KEY, '/v', DEFAULT_DISTRIBUTION_VALUE], {
       timeout: DISCOVERY_TIMEOUT_MS,
     })
-    const guid = /DefaultDistribution\s+REG_SZ\s+(\{[0-9a-fA-F-]+\})/i.exec(String(value))?.[1]
+    const guid = guidFromRegistryOutput(value)
     if (guid === undefined) return undefined
-    const name = execFileSync('reg.exe', ['query', `${LXSS_KEY}\\${guid}`, '/v', 'DistributionName'], {
+    const name = execFileSync('reg.exe', ['query', `${LXSS_KEY}\\${guid}`, '/v', DISTRIBUTION_NAME_VALUE], {
       timeout: DISCOVERY_TIMEOUT_MS,
     })
-    const distro = /DistributionName\s+REG_SZ\s+(.+)/i.exec(String(name))?.[1]?.trim()
-    syncDefault = distro === undefined || distro === '' ? undefined : distro
+    syncDefault = distroFromRegistryOutput(name)
   } catch {
     // An unreadable registry leaves the caller its own fail-loud path.
     syncDefault = undefined
@@ -353,15 +382,31 @@ function bridgeEnv(extra) {
  * @returns {{ distro: string, linuxCwd: string, windowsCwd: string }} the execution plan.
  * @throws Error when the directory belongs to neither world.
  */
+/**
+ * The distribution a plan runs in: the caller's fallback, else the machine default.
+ * @param {string} workdir - the directory being planned, named in the failure.
+ * @param {string|undefined} fallbackDistro - the configured distro, when there is one.
+ * @returns {string} the distribution name.
+ * @throws {Error} when neither source names one.
+ */
+function wslUserOption(username) {
+  return username !== undefined && username !== '' ? ['-u', username] : []
+}
+
+function planDistro(workdir, fallbackDistro) {
+  const distro = fallbackDistro ?? defaultDistroSync()
+  if (distro === undefined) {
+    throw new Error(`wsl: 无法确定 "${workdir}" 所属的发行版，请配置 distro`)
+  }
+  return distro
+}
+
 export function planWsl(workdir, fallbackDistro) {
   const windowsCwd = process.env.SystemRoot ?? process.cwd()
   const unc = parseWslUnc(workdir)
   if (unc !== null) return { distro: unc.distro, linuxCwd: unc.linuxPath, windowsCwd }
   if (workdir.startsWith('/')) {
-    const distro = fallbackDistro ?? defaultDistroSync()
-    if (distro === undefined) {
-      throw new Error(`wsl: 无法确定 "${workdir}" 所属的发行版，请配置 distro`)
-    }
+    const distro = planDistro(workdir, fallbackDistro)
     // A drive mount is also addressable from the Windows side; keep that as the
     // spawn directory so a failure still names a real path.
     return { distro, linuxCwd: workdir, windowsCwd: mntToWindowsPath(workdir) ?? windowsCwd }
@@ -370,10 +415,7 @@ export function planWsl(workdir, fallbackDistro) {
   if (mnt === null) {
     throw new Error(`wsl: 工作目录 "${workdir}" 不在 WSL 执行世界里`)
   }
-  const distro = fallbackDistro ?? defaultDistroSync()
-  if (distro === undefined) {
-    throw new Error(`wsl: 无法确定 "${workdir}" 所属的发行版，请配置 distro`)
-  }
+  const distro = planDistro(workdir, fallbackDistro)
   return { distro, linuxCwd: mnt, windowsCwd }
 }
 
@@ -399,7 +441,7 @@ export function buildWslExecArgv(plan, argv, options = {}) {
   return [
     options.wslPath ?? 'wsl.exe',
     '-d', plan.distro,
-    ...(options.username !== undefined && options.username !== '' ? ['-u', options.username] : []),
+    ...wslUserOption(options.username),
     '--cd', plan.linuxCwd,
     '-e',
     ...argv,
@@ -486,7 +528,7 @@ export function runWslShell({ distro, linuxCwd, command, username, loginShell =
   const script = loginShell ? `cd ${shellQuote(linuxCwd)} && ${command}` : command
   const argv = [
     '-d', distro,
-    ...(username !== undefined && username !== '' ? ['-u', username] : []),
+    ...wslUserOption(username),
     '--cd', linuxCwd,
     '-e', 'bash', loginShell ? '-lc' : '-c', script,
   ]
@@ -592,12 +634,14 @@ const PROBE_TIMEOUT_MS = 60_000
  * probe follows: repeat the SAME probe once, immediately, and let a persistent stall
  * still fail loudly with the second attempt's evidence.
  *
- * Retrying is safe here because all three probes are READS: the listing protocol frames
+ * Retrying is safe here because all FOUR probes are READS: the listing protocol frames
  * its own output and the check prints one of three tokens, so a repeat cannot duplicate
- * a side effect. The trigger is deliberately `timedOut` alone and not "any bad answer":
- * a non-zero exit from the listing script is the ordinary answer for a directory that is
- * not there, and doubling the latency of that case would slow the interactive picker for
- * no measured benefit.
+ * a side effect; `resolveLoginShell` runs a read-only `getent` and answers the same way.
+ * (This comment said "three" while four probes already consumed the runner — scripts/
+ * wsl-probe.mjs counts the same four.) The trigger is deliberately `timedOut` alone and
+ * not "any bad answer": a non-zero exit from the listing script is the ordinary answer
+ * for a directory that is not there, and doubling the latency of that case would slow
+ * the interactive picker for no measured benefit.
  * @param {(request: object) => Promise<object>} run - the probe runner.
  * @param {object} request - the probe, without its ceiling.
  * @returns {Promise<object>} the first conclusive attempt, or the second after a timeout.
@@ -612,7 +656,7 @@ async function probeWithRetry(run, request) {
  * List one directory inside a distribution.
  * @param {string} distro - distribution name.
  * @param {string} linuxPath - absolute Linux directory.
- * @param {{ wslPath?: string, run?: (options: object) => Promise<object> }} [options] - the configured `wsl.exe` path, and the probe runner (injectable so the retry policy below can be driven without a distribution — the same seam `resolveIdentity`/`detectRunner` expose).
+ * @param {{ wslPath?: string, run?: (options: object) => Promise<object> }} [options] - the configured `wsl.exe` path, and the probe runner (injectable so the retry policy above can be driven without a distribution — the same seam `resolveIdentity`/`detectRunner` expose).
  * @returns {Promise<{ path: string, parent: string | null, entries: Array<{ name: string, kind: 'directory' | 'file' }> }>} the listing.
  */
 export async function listLinuxDir(distro, linuxPath, { wslPath, run = runWslShell } = {}) {
@@ -651,7 +695,7 @@ export async function listLinuxDir(distro, linuxPath, { wslPath, run = runWslShe
  * Check whether one Linux path exists.
  * @param {string} distro - distribution name.
  * @param {string} linuxPath - absolute Linux path.
- * @param {{ wslPath?: string, run?: (options: object) => Promise<object> }} [options] - the configured `wsl.exe` path, and the probe runner (injectable so the retry policy below can be driven without a distribution).
+ * @param {{ wslPath?: string, run?: (options: object) => Promise<object> }} [options] - the configured `wsl.exe` path, and the probe runner (injectable so the retry policy above can be driven without a distribution).
  * @returns {Promise<{ exists: boolean, isDirectory: boolean }>} existence facts.
  */
 export async function checkLinuxPath(distro, linuxPath, { wslPath, run = runWslShell } = {}) {
@@ -707,7 +751,7 @@ export function probeEvidence(entry) {
  * exactly one path.
  * @param {string} distro - distribution name.
  * @param {string} [username] - user to resolve; absent resolves the default user.
- * @param {{ wslPath?: string, run?: (options: object) => Promise<object> }} [options] - the configured `wsl.exe` path, and the probe runner (injectable so the retry policy below can be driven without a distribution).
+ * @param {{ wslPath?: string, run?: (options: object) => Promise<object> }} [options] - the configured `wsl.exe` path, and the probe runner (injectable so the retry policy above can be driven without a distribution).
  * @returns {Promise<{ user: string, home: string }>} the user and their home.
  * @throws Error when the user or a usable home cannot be resolved.
  */
@@ -842,7 +886,7 @@ export class LoginShellUnresolvedError extends Error {
  * own evidence instead of answering.
  * @param {string} distro - distribution name.
  * @param {string} [username] - Linux user; omitted uses the distribution default.
- * @param {{ wslPath?: string, run?: (options: object) => Promise<object> }} [options] - the configured `wsl.exe` path, and the probe runner (injectable so the retry policy below can be driven without a distribution — the same seam the sibling probes expose).
+ * @param {{ wslPath?: string, run?: (options: object) => Promise<object> }} [options] - the configured `wsl.exe` path, and the probe runner (injectable so the retry policy above can be driven without a distribution — the same seam the sibling probes expose).
  * @returns {Promise<string>} the login shell path.
  * @throws {LoginShellUnresolvedError} when the probe timed out twice, could not
  *   run, or `getent` did not answer. The one value returned without the probe (an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-desktop",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./lib/icon.svg",