dsh-wsl-desktop 0.3.6 → 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/index.js

@@ -14,7 +14,7 @@
  */
 
 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'
@@ -27,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'
@@ -634,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')

package/lib/wsl/confinement.js

@@ -176,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

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'])
@@ -233,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.

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/package.json

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