dsh-wsl-desktop 0.7.6 → 0.8.1

package/README.en.md

@@ -86,6 +86,14 @@ A few details you will run into:
   this plugin does not override it.
 - Inside an open WSL workspace, the file list and the terminal are the distro's. PowerShell in Windows
   workspaces is unaffected.
+- **The W button has its own shortcut, and its hint follows a rebind.** The Windows desktop default is
+  `Ctrl+Alt+W` (the web profile declares none: the sidebar page-close command's web binding is the
+  same combination, and registration validates every profile's defaults, so declaring it would refuse
+  the command on the desktop too); hovering or focusing W shows the action name and keycaps the same way the
+  adjacent "+" does. The command is registered in Keyboard shortcuts, so rebinding or clearing it
+  updates the keycaps and `aria-keyshortcuts` immediately. When another command already owns the
+  default combination and registration is refused, the W button still works and merely omits the
+  keycaps; the shortcut service itself is a desktop dependency present since 0.1.7.
 
 ## What will surprise you
 
@@ -125,10 +133,19 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
   target is invalidated by entry changes only** — adds, removes and renames are seen, a content change
   of a file inside it is not; watch that file's own path to follow content. Mechanisms and
   measurements are in [WSL file watching](docs/WATCH.md).
+- **Confined mode needs passwordless sudo; without it there is no fence, and it fails loudly.** The
+  default permission mode is `workspace-write`, which has to build a mount namespace inside the
+  distro — and the WSL kernel does not allow bind mounts in a user namespace, so `sudo -n` is the only
+  way. Without that grant a confined command **fails outright** (with a structured error code, never a
+  silent unfenced run). Two ways out: give the session user NOPASSWD sudo, or switch the permission
+  mode to full access, which needs no sudo at all. See
+  [Linux-side confinement](docs/CONFINEMENT.md).
 - **A desktop update can break the plugin.** The plugin depends on the desktop framework's APIs — the
   harness — and changes to them interrupt it (0.1.6 → 0.1.7 broke four places in one go). So after
-  updating the desktop, run `node scripts/verify-post-restart.mjs` once and only keep going when
-  everything is green.
+  updating the desktop, open the W dialog once and confirm it lists your distributions, that
+  `bootstrap` reports the `pluginVersion` you just installed, and that `capabilities.status` is not
+  `degraded`; if any of those is wrong, take the desktop and the plugin back to a matching pair — the
+  order is in [Compatibility and upgrades](docs/COMPATIBILITY.md).
 - **Failures now carry a code, so you can diagnose first.** The browser receives a stable code and
   the whitelisted params, never the host message, stderr or resolved paths; after the user is
   confirmed, the W dialog shows an advisory health check whose failed rows carry the fix. Codes,
@@ -156,9 +173,10 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
 - [Engineering notes](docs/ENGINEERING-NOTES.md) — measured constraints, repository layout, release flow, install shape
 - [Distro support matrix](docs/DISTRO-SUPPORT.md) — which distros were verified, and what each one needs
 - [Compatibility and upgrades](docs/COMPATIBILITY.md) — plugin/desktop version relation, upgrade order, rollback steps
-- [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) — the two proposals to the harness upstream
+- [Upstream API proposals](docs/UPSTREAM-PROPOSALS.md) — the proposals to the harness upstream, including the record that an execution-world plugin cannot declare its session's initial permission posture
 - [Upstream defect reports](issues/README.md) — the harness issues filed, their measured evidence, and how the local workarounds relate
 - [Architecture and flow diagrams](docs/diagrams.md) — interactive architecture, sequence and lifecycle diagrams
+- [Real-machine acceptance runbook](docs/ACCEPTANCE-RUNBOOK.md) — the checks that only run on Windows + WSL2, their expected output, and the misjudgement list (Chinese only)
 
 Three of the linked 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

package/README.md

@@ -72,6 +72,11 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
   表示网络/子系统路径的写法，形如 `\\wsl.localhost\<发行版>\home\...`。
 - 自带的「+」保持部署原本的行为（桌面上是 Electron 的目录选择器），本插件不改写它。
 - 已经打开的 WSL 工作区里，文件列表和终端都是发行版内的。Windows 工作区里的 PowerShell 不受影响。
+- **W 按钮有自己的快捷键，提示会跟着改绑走。** Windows 桌面的默认是 `Ctrl+Alt+W`（Web 端不声明默认：
+  侧栏页面关闭（`page.close`）的 Web 组合也是它，而快捷键注册会校验所有平台的默认值，声明它会让命令在桌面端也注册失败）；
+  悬停或聚焦 W 时，提示会和左边的「+」一样显示动作名与键帽。命令登记在「快捷键」设置里，
+  改绑或清除后键帽与 `aria-keyshortcuts` 随即更新。默认组合被别的命令占用、导致注册被拒时，
+  W 按钮照常工作，只是不显示键帽；快捷键服务本身是 0.1.7 起桌面自带的依赖。
 
 ## 会意外的地方
 
@@ -102,9 +107,16 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
   文件每 300ms `stat` 一次。**目录目标只对条目变化生效**——新增、删除、改名可见，目录里某个文件的
   内容变化不可见；要盯内容就按文件路径监听它。机制与实测见
   [WSL 文件变更监听](docs/WATCH.md)。
+- **受限模式要免密 sudo；没有就当不了围栏，而且会明确失败。** 默认权限模式是
+  `workspace-write`，它要求在发行版里搭 mount namespace，而 WSL 内核不允许在 user namespace
+  里做 bind mount，所以只能用 `sudo -n`。缺这份授权时受限命令**直接失败**（结构化错误码，
+  不是静默裸跑）。两条出路：给会话用户配 NOPASSWD sudo，或者把权限模式切到「完全权限」——
+  后者不需要任何 sudo。详见 [Linux 侧约束](docs/CONFINEMENT.md)。
 - **桌面更新后插件可能失效。** 插件依赖桌面内部的框架（harness）的 API，这些 API 变化会打断它
-  （0.1.6 → 0.1.7 一次断了四处）。所以更新桌面之后先跑一次
-  `node scripts/verify-post-restart.mjs`，全绿再继续用。
+  （0.1.6 → 0.1.7 一次断了四处）。所以更新桌面之后，先打开一次 W 对话框确认它能列出你的
+  发行版、`bootstrap` 里的 `pluginVersion` 是你刚装的版本、`capabilities.status` 不是
+  `degraded`；任何一项不对就把桌面和插件退回彼此匹配的版本，
+  顺序见 [兼容性与升级](docs/COMPATIBILITY.md)。
 - **失败现在带 code，可以先自己诊断。** 浏览器侧的错误只回稳定 code 与允许的 params，
   宿主 message、stderr 与解析后的路径不会过线；W 对话框在确认用户后会显示一条建议性的
   「环境检查」，失败项带修复命令。错误码、检查项与降级行为见 [诊断](docs/DIAGNOSTICS.md)。
@@ -129,9 +141,10 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
 - [工程笔记](docs/ENGINEERING-NOTES.md) — 实测约束、仓库布局、发版流程、安装形态
 - [发行版支持矩阵](docs/DISTRO-SUPPORT.md) — 哪些发行版验证过，每种缺什么
 - [兼容性与升级](docs/COMPATIBILITY.md) — 插件与桌面的版本关系、升级顺序、回退步骤
-- [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的两项提案
+- [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的提案（含执行世界类插件无法声明初始权限姿态的记录）
 - [上游缺陷记录](issues/README.md) — 已上报 harness 的问题、实测证据与本地规避的关系
 - [架构与流程图](docs/diagrams.md) — 可交互的架构、时序与生命周期图
+- [真实机器验收手册](docs/ACCEPTANCE-RUNBOOK.md) — 只能在 Windows + WSL2 上跑的检查项、期望输出与误判清单
 
 其中三份——发行版支持矩阵、上游 API 提案、架构与流程图索引——**只有中文版**，因为目前没有对应的
 英文文本。把它们翻成英文是一件独立的工作，不是改个文件名。

package/lib/client.js

@@ -3,6 +3,10 @@
  *
  * Adds one control beside the shipped "add workspace" button in the sidebar
  * section header: a `W` button opening this plugin's WSL workspace picker.
+ * The button carries the same kind of shortcut hint the shipped trigger does:
+ * its tooltip shows the effective keys from the shell's shortcut catalog, and
+ * the registered command opens the picker from anywhere the page owns the
+ * keyboard.
  *
  * The shipped button keeps its own behaviour: this half registers no slot
  * occupant, because `sidebar.workspaces.directoryFlow` is `kind: 'single'` and
@@ -71,6 +75,28 @@ window.__ModuleLoader__.load({
     /** Sprite symbol id shape, as `iconSymbolId` composes it: `dsw-icon-<glyph>-<weight>`. */
     const SPRITE_ICON_ID = /^#?dsw-icon-(.+)-(?:regular|medium)$/
 
+    /**
+     * Stable command identity of the W button's keyboard action.
+     *
+     * The id is the plugin's public shortcut identity: it travels through the
+     * shell's command catalog, appears in the Keyboard shortcuts reference, and
+     * survives user rebinds. Renaming it orphans every saved override, so it
+     * names the action rather than the button's ever-changing presentation.
+     */
+    const SHORTCUT_ID = 'wsl.workspace.open'
+
+    /**
+     * The add-workspace trigger's own tooltip delay, mirrored so the two
+     * controls beside each other reveal their shortcut hints together.
+     */
+    const TOOLTIP_HOVER_DELAY_MS = 500
+
+    /** Gap between the W button and its shortcut tooltip, in CSS pixels. */
+    const TOOLTIP_GAP = 8
+
+    /** Minimum distance the shortcut tooltip keeps from the viewport edges. */
+    const TOOLTIP_MARGIN = 12
+
     /**
      * The row glyphs whose artwork is FILL-only, as sprite names.
      *
@@ -336,9 +362,24 @@ window.__ModuleLoader__.load({
     function routeFailure(method, status, envelope) {
       const error = new Error(envelope?.error ?? `${method} failed (HTTP ${status})`)
       error.code = typeof envelope?.code === 'string' ? envelope.code : status === 0 ? 'transport' : 'internal'
-      error.params = envelope !== null && typeof envelope?.params === 'object' && envelope?.params !== null
-        ? envelope.params
-        : {}
+      // A refusal the route never answered carries no envelope — the transport
+      // fence answers an empty-bodied 401/403, and the webserver's own admission
+      // answers 401/403/503 the same way. Without the status this collapsed to a
+      // bare `internal` with empty params, which is what a real GUI check hit on
+      // Desktop 0.2.2-rc.3: every method failed and the diagnostic said nothing.
+      // The status is the ONE fact that separates "not authenticated" from
+      // "not permitted" from "host has no admission provider", so it is carried
+      // in the params the copyable report prints. It is produced locally, so it
+      // is not subject to the wire param allowlist.
+      const carried = envelope !== null && typeof envelope?.params === 'object' && envelope?.params !== null
+      if (carried) {
+        error.params = envelope.params
+      } else {
+        // No envelope means the route never answered in its own vocabulary; the
+        // HTTP status is then the only fact that separates "not authenticated"
+        // from "not permitted" from "the host has no admission provider".
+        error.params = status === 0 ? {} : { status }
+      }
       return error
     }
 
@@ -1518,7 +1559,15 @@ window.__ModuleLoader__.load({
 
     /** The injected services the picker and its trigger read. */
     // ── 5. the companion button and workspace rows ─────────────────────────────
-    const companion = { button: null, fallback: null, trigger: null, observer: null, scheduled: false, disposed: false }
+    const companion = {
+      button: null,
+      fallback: null,
+      hideHint: null,
+      trigger: null,
+      observer: null,
+      scheduled: false,
+      disposed: false,
+    }
 
     /** Whether the missing-workspace-source warning was already printed. */
     let warnedWorkspaceSource = false
@@ -1876,6 +1925,10 @@ window.__ModuleLoader__.load({
         companion.trigger = trigger
       }
       if (trigger === null) {
+        // React took the anchor away, so the companion leaves too. The tooltip
+        // is a fixed portal with no pointer to leave; withdraw it explicitly or
+        // it outlives the control it describes.
+        companion.hideHint?.()
         if (button.isConnected) button.remove()
         return
       }
@@ -1896,7 +1949,13 @@ window.__ModuleLoader__.load({
       const box = button.getBoundingClientRect()
       const fits = row === undefined || box.right <= row.right + 1
       const triggerVisible = getComputedStyle(trigger).visibility !== 'hidden'
-      button.style.display = fits && triggerVisible ? '' : 'none'
+      const shown = fits && triggerVisible
+      button.style.display = shown ? '' : 'none'
+      // The shipped cluster hides itself (inline search, narrow rail) by
+      // visibility and the companion follows via display; a visible tooltip must
+      // follow too, because no pointerleave fires for a control that left the
+      // hit-test tree.
+      if (!shown) companion.hideHint?.()
     }
 
     /**
@@ -1911,6 +1970,362 @@ window.__ModuleLoader__.load({
       return document.body ?? document.documentElement
     }
 
+    /**
+     * The effective catalog row for the W shortcut, or null when the shell has
+     * no shortcut service or has not published the command yet.
+     *
+     * The row is the SINGLE source of the hint: `keys` are the platform-formatted
+     * labels the shortcut service presents, and `aria` is the same binding in
+     * `aria-keyshortcuts` spelling. A rebind replaces the row, so the tooltip
+     * follows the user's setting instead of the default first seen.
+     * @param {object} ctx - the client plugin context.
+     * @returns {object | null} the row for `SHORTCUT_ID`, or null.
+     */
+    function shortcutRowOf(ctx) {
+      const catalog = ctx.shortcuts?.catalog
+      if (typeof catalog?.getSnapshot !== 'function') return null
+      const rows = catalog.getSnapshot()
+      if (!Array.isArray(rows)) return null
+      return rows.find((row) => row.id === SHORTCUT_ID) ?? null
+    }
+
+    /**
+     * Publish or withdraw the accessible shortcut claim on one control.
+     * @param {HTMLElement | null} node - the control, or null when it is absent.
+     * @param {object | null} row - the effective catalog row.
+     */
+    function setKeyshortcuts(node, row) {
+      if (node === null) return
+      if (typeof row?.aria === 'string' && row.aria !== '') node.setAttribute('aria-keyshortcuts', row.aria)
+      else node.removeAttribute('aria-keyshortcuts')
+    }
+
+    /** Tooltip bubble styling, mirrored from the shipped tooltip's semantic tokens. */
+    const SHORTCUT_TOOLTIP_STYLE = {
+      position: 'fixed',
+      zIndex: '1100',
+      display: 'none',
+      alignItems: 'center',
+      gap: '8px',
+      width: 'max-content',
+      maxWidth: 'min(50vw, calc(100vw - 24px))',
+      boxSizing: 'border-box',
+      padding: '3px 7px',
+      borderRadius: 'var(--dsw-radius-sm, 8px)',
+      background: 'var(--dsw-alias-tooltip-bg, #3a3a3a)',
+      color: 'var(--dsw-static-neutral-bluish-00, #ffffff)',
+      fontSize: '13px',
+      lineHeight: '20px',
+      whiteSpace: 'pre-line',
+      overflowWrap: 'break-word',
+      pointerEvents: 'none',
+    }
+
+    /** The keycap strip's layout inside a tooltip. */
+    const SHORTCUT_KEYS_STYLE = {
+      display: 'inline-flex',
+      flex: 'none',
+      alignItems: 'center',
+      gap: '2px',
+      color: 'inherit',
+      fontSize: '11px',
+      lineHeight: '14px',
+      whiteSpace: 'nowrap',
+    }
+
+    /** One keycap: the shipped tooltip's 16px badge. */
+    const SHORTCUT_KEY_STYLE = {
+      boxSizing: 'border-box',
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      font: 'inherit',
+    }
+
+    /**
+     * One shortcut tooltip attached to a plain DOM control.
+     *
+     * The shipped "add workspace" button gets this from the React Tooltip in
+     * `ui-primitives`; this half is a hand-written factory with no module graph,
+     * and a feature plugin may not reach into another feature's values, so the
+     * same presentation is rebuilt here on the shared semantic tokens. The
+     * bubble is portaled to the body and positioned fixed, so the sidebar's
+     * clipping and stacking contexts cannot hide it.
+     * @param {HTMLElement} anchor - the control the tooltip belongs to.
+     * @param {string} label - the action name shown before the keycaps.
+     * @returns {{ setKeys: (keys: readonly string[]) => void, dismiss: () => void, dispose: () => void }}
+     *   the key publisher, the layout-driven dismissal, and the disposer.
+     */
+    function createShortcutHint(anchor, label) {
+      let bubble = null
+      let keys = []
+      let showTimer = null
+      let visible = false
+      // The shipped Tooltip keeps hover and focus as INDEPENDENT triggers and
+      // withdraws the bubble only after BOTH clear: hovering away from a focused
+      // anchor must not drop it, and blurring while the pointer is still over
+      // the anchor must not drop it either.
+      let hovered = false
+      let focused = false
+
+      function clearShowTimer() {
+        if (showTimer === null) return
+        clearTimeout(showTimer)
+        showTimer = null
+      }
+
+      /**
+       * Render the current keycap labels into the bubble, or hide the strip.
+       *
+       * Windows presents a combination as one plus-separated run in a single
+       * pill; a modifier set without a separator (macOS symbols) gets one cap
+       * per key. Both shapes are built from the catalog's labels, never from a
+       * key spelling written in this file.
+       */
+      function renderKeys() {
+        if (bubble === null) return
+        const strip = bubble.querySelector('[data-wsl-tooltip-keys]')
+        if (strip === null) return
+        strip.replaceChildren()
+        if (keys.length === 0) {
+          strip.style.display = 'none'
+          bubble.style.paddingInlineEnd = '7px'
+          return
+        }
+        strip.style.display = 'inline-flex'
+        bubble.style.paddingInlineEnd = '5px'
+        const joined = keys.includes('+')
+        strip.style.background = joined
+          ? 'var(--dsw-alias-tooltip-key-bg, rgba(255,255,255,0.18))'
+          : 'transparent'
+        strip.style.height = joined ? '16px' : ''
+        strip.style.padding = joined ? '0 4px' : '0'
+        strip.style.borderRadius = joined ? '4px' : ''
+        for (const token of keys) {
+          const key = document.createElement('kbd')
+          key.textContent = token
+          Object.assign(key.style, SHORTCUT_KEY_STYLE)
+          if (!joined) {
+            key.style.minWidth = '16px'
+            key.style.height = '16px'
+            key.style.padding = '0 2px'
+            key.style.borderRadius = '4px'
+            key.style.background = 'var(--dsw-alias-tooltip-key-bg, rgba(255,255,255,0.18))'
+          }
+          strip.append(key)
+        }
+      }
+
+      /** Build the bubble once: a label span and a keycap strip. */
+      function ensureBubble() {
+        if (bubble !== null) return bubble
+        bubble = el('span', SHORTCUT_TOOLTIP_STYLE)
+        bubble.setAttribute('role', 'tooltip')
+        bubble.setAttribute('aria-hidden', 'true')
+        bubble.setAttribute('data-wsl-shortcut-tooltip', '')
+        const text = el('span', { minWidth: '0' }, label)
+        text.setAttribute('data-wsl-tooltip-label', '')
+        const strip = el('span', SHORTCUT_KEYS_STYLE)
+        strip.setAttribute('data-wsl-tooltip-keys', '')
+        bubble.append(text, strip)
+        renderKeys()
+        return bubble
+      }
+
+      /** Place the bubble below the anchor, clamped to the viewport. */
+      function position() {
+        if (bubble === null) return
+        const anchorBox = anchor.getBoundingClientRect()
+        // A media query or an ancestor class can collapse the header on resize
+        // without any DOM mutation, so no layout pass reaches the hint. A zero
+        // box means the tooltip has no anchor left to describe: withdraw it
+        // instead of placing it from (0, 0).
+        if (anchorBox.width <= 0 && anchorBox.height <= 0) {
+          hide()
+          return
+        }
+        const bubbleBox = bubble.getBoundingClientRect()
+        const centered = anchorBox.left + anchorBox.width / 2 - bubbleBox.width / 2
+        const left = Math.min(
+          Math.max(TOOLTIP_MARGIN, centered),
+          Math.max(TOOLTIP_MARGIN, window.innerWidth - bubbleBox.width - TOOLTIP_MARGIN),
+        )
+        let top = anchorBox.bottom + TOOLTIP_GAP
+        // The sidebar header sits near the top edge, but a short window or a
+        // moved trigger still has to get a readable bubble: flip above the
+        // anchor when the space below cannot hold it.
+        if (top + bubbleBox.height > window.innerHeight - TOOLTIP_MARGIN) {
+          top = Math.max(TOOLTIP_MARGIN, anchorBox.top - bubbleBox.height - TOOLTIP_GAP)
+        }
+        bubble.style.left = `${left}px`
+        bubble.style.top = `${top}px`
+        bubble.style.visibility = 'visible'
+      }
+
+      function show() {
+        if (!anchor.isConnected || anchor.style.display === 'none') return
+        // Closing the picker refocuses its opener. When that opener already sits
+        // in a hidden subtree its box is zero; placing a fixed bubble from that
+        // box would paint it at the viewport origin.
+        const anchorBox = anchor.getBoundingClientRect()
+        if (anchorBox.width <= 0 && anchorBox.height <= 0) return
+        const node = ensureBubble()
+        if (!node.isConnected) hostElement().append(node)
+        visible = true
+        node.style.display = 'inline-flex'
+        node.style.visibility = 'hidden'
+        position()
+      }
+
+      function hide() {
+        clearShowTimer()
+        visible = false
+        if (bubble !== null) bubble.style.display = 'none'
+      }
+
+      /**
+       * Withdraw the bubble AND clear both triggers.
+       *
+       * The layout pass calls this when the anchor leaves the layout, mirroring
+       * the shipped Tooltip's disabled effect: without the reset, a hover that
+       * was live when the header hid survives the withdrawal, and a later
+       * focus/blur can keep a bubble on screen with no pointer over the anchor.
+       */
+      function dismiss() {
+        hovered = false
+        focused = false
+        hide()
+      }
+
+      function reveal(delay) {
+        clearShowTimer()
+        if (delay <= 0) {
+          show()
+          return
+        }
+        showTimer = setTimeout(() => {
+          showTimer = null
+          show()
+        }, delay)
+      }
+
+      const onPointerEnter = (event) => {
+        // Touch has no hover state; tapping still invokes the button.
+        if (event.pointerType === 'touch') return
+        hovered = true
+        reveal(TOOLTIP_HOVER_DELAY_MS)
+      }
+      const onPointerLeave = () => {
+        hovered = false
+        // A pending hover reveal is cancelled even when focus holds the bubble
+        // open; otherwise it would reappear after the pointer has left.
+        clearShowTimer()
+        if (!focused) hide()
+      }
+      const onFocus = () => {
+        // The shared input-modality attribute is how the shell publishes
+        // pointer-acquired focus; a picker closing back onto its trigger must
+        // not flash the shortcut bubble after a click.
+        if (document.documentElement.getAttribute('data-input-modality') === 'pointer') return
+        focused = true
+        reveal(0)
+      }
+      const onBlur = () => {
+        focused = false
+        clearShowTimer()
+        if (!hovered) hide()
+      }
+      const onClick = () => {
+        // Activating the button dismisses the bubble even though the pointer
+        // stays over it; the shipped tooltip clears its focus trigger here too.
+        focused = false
+        hide()
+      }
+      const onResize = () => { if (visible) position() }
+      anchor.addEventListener('pointerenter', onPointerEnter)
+      anchor.addEventListener('pointerleave', onPointerLeave)
+      anchor.addEventListener('focus', onFocus)
+      anchor.addEventListener('blur', onBlur)
+      anchor.addEventListener('click', onClick)
+      window.addEventListener('resize', onResize)
+
+      return {
+        /**
+         * Publish the effective keys to the (possibly not yet built) bubble.
+         * @param {readonly string[]} nextKeys - the catalog's presented labels.
+         */
+        setKeys(nextKeys) {
+          const normalized = Array.isArray(nextKeys) ? nextKeys.map(String) : []
+          if (normalized.join('\u0000') === keys.join('\u0000')) return
+          keys = normalized
+          if (bubble === null) return
+          renderKeys()
+          if (visible) position()
+        },
+        /** Withdraw the bubble and clear both triggers when its anchor leaves the layout. */
+        dismiss,
+        /** Release the bubble and every listener it installed. */
+        dispose() {
+          clearShowTimer()
+          visible = false
+          hovered = false
+          focused = false
+          anchor.removeEventListener('pointerenter', onPointerEnter)
+          anchor.removeEventListener('pointerleave', onPointerLeave)
+          anchor.removeEventListener('focus', onFocus)
+          anchor.removeEventListener('blur', onBlur)
+          anchor.removeEventListener('click', onClick)
+          window.removeEventListener('resize', onResize)
+          if (bubble !== null) {
+            bubble.remove()
+            bubble = null
+          }
+          keys = []
+        },
+      }
+    }
+
+    /**
+     * Register the W button's keyboard command, tolerating a host without the
+     * shortcut service or a catalog that refuses the default.
+     *
+     * Registration is deliberately outside the button's click path: the command
+     * resolves to the same `openPicker` the click calls, so the two entries cannot
+     * drift. A refused registration (another command already owns the same
+     * default on one of this command's profiles) is logged and leaves the
+     * button usable; the hint then carries the label alone.
+     * @param {object} ctx - the client plugin context.
+     * @returns {() => void} the registration's disposer, or a no-op.
+     */
+    function installShortcut(ctx) {
+      try {
+        // The access itself is inside the guard: a context whose service getter
+        // throws must degrade the hint, not abort the install that owns W.
+        const shortcuts = ctx.shortcuts
+        if (typeof shortcuts?.register !== 'function') return () => {}
+        return shortcuts.register({
+          id: SHORTCUT_ID,
+          label: () => BUTTON_LABEL,
+          aliases: ['wsl', 'wsl workspace', 'open wsl workspace'],
+          defaults: {
+            // Desktop only. On the Web profile the shell's page.close command
+            // already owns KeyW+primary+alt, and the shortcut registry
+            // validates EVERY profile's defaults at registration:
+            // declaring the Web default here makes this command throw even on
+            // a desktop runtime, so the hint loses its keys and the key does
+            // nothing. Web users can bind the command themselves.
+            'desktop:windows': { code: 'KeyW', modifiers: ['primary', 'alt'] },
+          },
+          regions: ['page', 'editable'],
+          modals: ['sidebar'],
+          resolve: () => ({ status: 'handled', run: () => openPicker(ctx) }),
+        })
+      } catch (error) {
+        console.warn('dsh-wsl-desktop: W 快捷键注册失败，W 按钮仍然可用', error)
+        return () => {}
+      }
+    }
+
     /**
      * Install the companion button and keep it attached.
      * @param {object} ctx - the client plugin context.
@@ -1923,19 +2338,22 @@ window.__ModuleLoader__.load({
       button.setAttribute('aria-label', BUTTON_LABEL)
       button.setAttribute('aria-haspopup', 'dialog')
       button.setAttribute('aria-expanded', 'false')
-      button.title = BUTTON_LABEL
       button.append(el('span', {
         fontWeight: '600',
         fontSize: '13px',
         lineHeight: '1',
         letterSpacing: '0.02em',
       }, 'W'))
+      // The hint replaces the native title: it carries the SAME action name plus
+      // the effective keycaps, and a title would show a second, stale tooltip.
+      const hint = createShortcutHint(button, BUTTON_LABEL)
       button.addEventListener('click', (event) => {
         event.preventDefault()
         event.stopPropagation()
         openPicker(ctx)
       })
       companion.button = button
+      companion.hideHint = hint.dismiss
 
       /** The degraded entry shown when the sidebar anchor is missing. */
       let fallbackEntry = null
@@ -1994,7 +2412,45 @@ window.__ModuleLoader__.load({
         hostElement().append(entry)
         fallbackEntry = entry
         companion.fallback = open
+        // The fallback is the W button's only visible entry in this phase, so
+        // the shortcut claim belongs on it too; the visual bubble stays with the
+        // real button to keep the failure path minimal.
+        applyShortcut()
+      }
+
+      /**
+       * Publish the effective shortcut row to the button, hint, and fallback.
+       *
+       * Called once at install and again for every catalog change (a rebind, a
+       * clear, another command's registration). The row is read from the live
+       * catalog rather than remembered, so a rebind cannot leave the hint
+       * claiming keys the command no longer owns.
+       */
+      function applyShortcut() {
+        let row = null
+        try {
+          row = shortcutRowOf(ctx)
+        } catch (error) {
+          // A throwing catalog is a shell fault, not a reason to lose the W
+          // button: the hint is peripheral and degrades to its label.
+          console.warn('dsh-wsl-desktop: W 快捷键目录读取失败，W 按钮仍然可用', error)
+        }
+        setKeyshortcuts(button, row)
+        hint.setKeys(row?.keys ?? [])
+        setKeyshortcuts(fallbackEntry?.querySelector('[data-wsl-fallback-entry]') ?? null, row)
+      }
+
+      const disposeShortcut = installShortcut(ctx)
+      let disposeCatalog = null
+      try {
+        const catalog = ctx.shortcuts?.catalog
+        disposeCatalog = typeof catalog?.subscribe === 'function'
+          ? catalog.subscribe(applyShortcut)
+          : null
+      } catch (error) {
+        console.warn('dsh-wsl-desktop: W 快捷键目录订阅失败，W 按钮仍然可用', error)
       }
+      applyShortcut()
 
       // `sync` is idempotent and never removes the node it manages, so its own
       // work cannot re-trigger the observer it runs from.
@@ -2049,6 +2505,12 @@ window.__ModuleLoader__.load({
       return () => {
         clearTimeout(warning)
         removeFallback()
+        // Unsubscribe BEFORE the command leaves the catalog: removing it makes
+        // the service publish a fresh snapshot, and a listener still attached
+        // would rebuild the bubble this teardown is about to delete.
+        if (disposeCatalog !== null) disposeCatalog()
+        disposeShortcut()
+        hint.dispose()
         observer.disconnect()
         unsubscribe?.()
         // disconnect() does not cancel a callback already handed to
@@ -2066,6 +2528,7 @@ window.__ModuleLoader__.load({
         }
         button.remove()
         companion.button = null
+        companion.hideHint = null
         companion.trigger = null
         companion.observer = null
         teardown?.()
@@ -2078,7 +2541,7 @@ window.__ModuleLoader__.load({
       // `remote.session` is the namespace the create request travels through
       // (see `createBoundSession`); the harness's own client plugins inject it
       // the same way.
-      inject: ['workspaces', 'uiWorkspace', 'sessions', 'remote', 'remote.session'],
+      inject: ['workspaces', 'uiWorkspace', 'sessions', 'remote', 'remote.session', 'shortcuts'],
       apply(ctx) {
         ctx.effect(() => install(ctx), 'wsl-desktop: sidebar WSL workspace trigger')
       },

package/lib/host/http.js

@@ -9,11 +9,14 @@
  */
 
 import { randomBytes, timingSafeEqual } from 'node:crypto'
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { MAX_BODY_BYTES, DEV_TOKEN_HEADER, tokenMatches } from '../http-admission.js'
 
+/** Ceiling for the route-failure log, so a repeated failure cannot fill the disk. */
+const ROUTE_LOG_MAX_BYTES = 256 * 1024
+
 /**
  * The harness home that holds the user preset root.
  * @returns {string} the resolved `$DSH_HOME`.
@@ -67,11 +70,62 @@ export function sendRejection(res, rejection) {
   sendJson(res, rejection.status, { ok: false, code: rejection.code, error: rejection.message })
 }
 
-/** Trust surface consumed here; the browser-side connection package owns the full type. */
+/**
+ * Trust surface consumed here; the browser-side connection package owns the full type.
+ *
+ * `ctx.connection` is the only spelling that works, and it works because this
+ * plugin declares `connection` in its `inject` list. There is deliberately NO
+ * `ctx.get` fallback: Cordis resolves a service property against the CALLING
+ * context and THROWS for a service the caller never injected (`cannot get
+ * property "connection" without inject`) rather than returning `undefined`, so a
+ * fallback could not rescue that case — and when the service is genuinely
+ * unprovided, `ctx.get` returns `undefined` too, which the caller already
+ * handles. A fallback here would suggest a protection that does not exist.
+ * @param {object} ctx - the plugin context.
+ * @returns {object | undefined} the connection handle, when this composition has one.
+ */
 export function connectionOf(ctx) {
   return Reflect.get(ctx, 'connection')
 }
 
+/**
+ * Append one route failure to a log the operator can read.
+ *
+ * The route answers the browser with a code and nothing else — deliberately, so
+ * a host path or a wsl.exe stderr never crosses the wire. That is right for
+ * production and useless when the ROUTE ITSELF throws before it can name a
+ * reason: the browser shows `internal`, the host logs through a channel the
+ * desktop does not surface, and the only remaining evidence is this file. It is
+ * written on the operator's own disk, never sent anywhere.
+ * @param {string} step - the admission step that failed.
+ * @param {unknown} error - the thrown value.
+ * @returns {Promise<void>} settlement; a logging failure never masks the refusal.
+ */
+export async function logRouteFailure(step, error) {
+  try {
+    const path = join(dshHome(), 'wsl-desktop-route-error.log')
+    const detail = error instanceof Error ? (error.stack ?? error.message) : String(error)
+    const line = `${new Date().toISOString()} [${step}] ${detail}\n`
+    await mkdir(dirname(path), { recursive: true })
+    // Bounded, because a route that fails on every request would otherwise fill
+    // the operator's disk. Crossing the cap restarts the file with a note, so
+    // the NEWEST failure is always present and the file never grows without
+    // limit. A silently truncated diagnostic is worse than a fresh one.
+    let size = 0
+    try {
+      size = (await stat(path)).size
+    } catch {
+      size = 0
+    }
+    if (size + Buffer.byteLength(line) > ROUTE_LOG_MAX_BYTES) {
+      await writeFile(path, `[truncated above ${ROUTE_LOG_MAX_BYTES} bytes]\n`, 'utf8')
+    }
+    await writeFile(path, line, { flag: 'a' })
+  } catch {
+    // A diagnostic that throws must not change the response the caller gets.
+  }
+}
+
 /**
  * This installation's development token, minted on first use.
  *

package/lib/host/state.js

@@ -56,3 +56,37 @@ export const bindingTape = (() => {
     },
   }
 })()
+
+/**
+ * Wait briefly for a session's agent to appear in the registry.
+ *
+ * `api-session/added` fires BEFORE the harness registers the session's agent, so
+ * the post-hoc preset fallback raced it: `agents.get(sessionId)` was `undefined`,
+ * the fallback recorded "agent not registered" and returned — leaving a session
+ * whose cwd is a WSL path running in the WINDOWS world, permanently, because the
+ * harness fixes a preset at creation and refuses a later select. Measured on
+ * Desktop 0.2.2-rc.3 (a session in a WSL-UNC workspace, `ok:false` in the binding
+ * log). A bounded wait turns a guaranteed loss into a wait the registry wins.
+ *
+ * `now` and `sleep` are injectable so the wait is testable without real time.
+ * @param {{ get: (sessionId: unknown) => unknown }} agents - the agents registry.
+ * @param {unknown} sessionId - the session whose agent is wanted.
+ * @param {{ deadlineMs?: number, pollMs?: number, now?: () => number, sleep?: (ms: number) => Promise<void> }} [options] -
+ *   the bound, the poll interval, and the clock/sleeper (defaults are real).
+ * @returns {Promise<unknown>} the agent, or `undefined` when the bound expires.
+ */
+export async function waitForAgent(agents, sessionId, options = {}) {
+  const deadlineMs = options.deadlineMs ?? 2_000
+  const pollMs = options.pollMs ?? 50
+  const now = options.now ?? Date.now
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => { setTimeout(resolve, ms) }))
+  const startedAt = now()
+  for (;;) {
+    const agent = agents.get(sessionId)
+    if (agent !== undefined) return agent
+    // Checked AFTER a read so an already-registered agent never waits at all, and
+    // so the deadline is a bound on waiting rather than on attempts.
+    if (now() - startedAt >= deadlineMs) return undefined
+    await sleep(pollMs)
+  }
+}

package/lib/index.js

@@ -22,12 +22,12 @@ import {
   MAX_BODY_BYTES, DEV_TOKEN_HEADER, bodyAdmission, dispatchAdmission, fenceRejection, methodAdmission, preflight, tokenMatches,
 } from './http-admission.js'
 import {
-  connectionOf, devToken, isDeveloperCaller, readJsonBody, sendJson, sendRejection,
+  connectionOf, devToken, isDeveloperCaller, logRouteFailure, readJsonBody, sendJson, sendRejection,
 } from './host/http.js'
 import {
   GENERATED_PREFIX, basePluginsOf, runShellSpec, sourceDirFor, variantIdFor,
 } from './host/presets.js'
-import { bindingTape, hostSession, presetRun } from './host/state.js'
+import { bindingTape, hostSession, presetRun, waitForAgent } from './host/state.js'
 import { buildVariantPlugins } from './wsl/preset.js'
 import { setLocalSubprocess } from './wsl/host-refs.js'
 import { checkLinuxPath, defaultWorkspaceUnc, listLinuxDir, resolveDistroHome, runWslShell } from './wsl/world.js'
@@ -49,8 +49,17 @@ export const name = 'wsl-desktop'
  * carries the composition's trust fence: its Host/Origin check defeats DNS
  * rebinding, and its browser authentication (the login-token cookie) gates every
  * caller before any method runs.
+ *
+ * `connection.authentication` is a SERVICE IN ITS OWN RIGHT (`super(ctx,
+ * 'connection.authentication')`), and `connection.admit` reads it internally.
+ * Cordis resolves that read against the CALLING context, so a plugin that calls
+ * `admit` must inject it too — otherwise the call dies with `cannot get property
+ * "connection.authentication" without inject`, thrown from inside `admit`
+ * itself. That is exactly how the whole W dialog broke on Desktop 0.2.2-rc.3:
+ * the route was reachable, admission threw, and the host's last-resort listener
+ * answered an empty-bodied 400 that the browser could only call `internal`.
  */
-export const inject = ['webServer', 'connection']
+export const inject = ['webServer', 'connection', 'connection.authentication']
 
 /** Plugin config. */
 export const Config = z.object({
@@ -1484,6 +1493,17 @@ export function apply(ctx, config) {
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: config.routePath,
+    // Admission is this handler's job, so the route must not also be gated by
+    // the webserver. Harness 0.2.2-rc.3 (commit 71753fdf91, "centralize route
+    // admission with required policy") added this field and defaults an omitted
+    // one to `required` — which refuses the request BEFORE this handler runs.
+    // The observable result was a silent total failure: the W dialog rendered,
+    // every method answered an empty-bodied 401, and the browser half could only
+    // report it as `internal`. Declaring `anonymous` hands admission back to the
+    // fence below, which applies the same two arms and additionally lets a
+    // development token replace the 401 (a script cannot present a browser
+    // cookie). The host still applies its Host/Origin check to anonymous routes.
+    auth: 'anonymous',
     handler: async (req, res) => {
       // The fence first, exactly as every shipped host route does it: without
       // this, a cross-site `text/plain` POST is a CORS-simple request with no
@@ -1493,14 +1513,66 @@ export function apply(ctx, config) {
       // replaces the SECOND arm only — a local script cannot present a browser
       // cookie — and never the first: a token holder gains nothing from a
       // trusted Host, but a foreign Host must stay refused for every caller.
-      const developer = await isDeveloperCaller(req, config)
-      const rejection = fenceRejection({
-        rejection: connectionOf(ctx).requestRejection(req),
-        developer,
-      })
-      if (rejection !== undefined) {
-        res.writeHead(rejection, { 'content-type': 'text/plain; charset=utf-8' })
-        res.end()
+      //
+      // `admit` is the accessor to use: `requestRejection` was the same two arms
+      // and was REMOVED in the same 0.2.2-rc.3 commit. `admit` predates it and
+      // survives it, so this call site works on both generations.
+      // EVERYTHING from here to the response is inside one guard, because the
+      // host's last-resort listener turns an escaping throw into an EMPTY-bodied
+      // 400 (`webserver/src/index.ts`: `dispatch().catch(() => res.writeHead(400)`).
+      // That answer is indistinguishable, at the browser, from a transport
+      // refusal: the client's `json()` throws and the dialog shows only
+      // `internal`. Measured on Desktop 0.2.2-rc.3, where admission threw and the
+      // whole W dialog became an opaque "plugin internal error" — the single
+      // hardest failure to diagnose this route has produced. A JSON answer keeps
+      // the code, the ref and (for a developer caller) the message.
+      let developer = false
+      // The step is tracked so the refusal can NAME where admission broke. A
+      // browser cannot present the development token (it is a header a page
+      // never sends), so `developer` is false for every real page and the
+      // response can carry nothing about the cause — the file log is the only
+      // channel left. `step` itself is a fixed vocabulary word, not host data,
+      // so it is safe to return.
+      let step = 'developer'
+      try {
+        developer = await isDeveloperCaller(req, config)
+        step = 'connection'
+        const connection = connectionOf(ctx)
+        if (connection === undefined || typeof connection.admit !== 'function') {
+          throw new Error(`the composition exposes no connection admission (got ${connection === undefined ? 'undefined' : typeof connection})`)
+        }
+        step = 'admit'
+        const admission = connection.admit(req)
+        step = 'fence'
+        const rejection = fenceRejection({
+          rejection: 'rejection' in admission ? admission.rejection : undefined,
+          developer,
+        })
+        if (rejection !== undefined) {
+          res.writeHead(rejection, { 'content-type': 'text/plain; charset=utf-8' })
+          res.end()
+          return
+        }
+      } catch (error) {
+        // The stack goes to the operator's disk; the browser gets the shared
+        // classifier's envelope. The `step` is carried INSIDE a WslRouteError so
+        // it passes through `browserFailure`'s SAFE_PARAMS filter like every
+        // other param — appending it afterwards would make the allowlist entry
+        // decorative and the filter a lie. The constructor also supplies the
+        // correlation `ref` that `internal` always carries. The message itself
+        // is never sent — that is where host paths live — which is why the file
+        // log above exists.
+        //
+        // `internal` is stated rather than inferred, because the four steps above
+        // are admission plumbing: they raise TypeErrors and plain Errors, never a
+        // WslDomainError whose code would mean something to the browser. Passing
+        // the original as `cause` keeps it attached for anything that inspects the
+        // error object, without letting it change the wire code.
+        void logRouteFailure(step, error)
+        sendJson(res, 500, {
+          ok: false,
+          ...browserFailure(new WslRouteError('internal', { step }, { cause: error }), { discovery: false }),
+        })
         return
       }
       const early = preflight({ httpMethod: req.method, contentType: req.headers['content-type'] })
@@ -1643,9 +1715,15 @@ async function bindWslSession(ctx, summary) {
   if (parseWslUnc(cwd) === null) return
   const agents = ctx.get('agents')
   if (agents === undefined) return
-  const agent = agents.get(summary?.sessionId)
+  // WAIT, do not give up. `api-session/added` fires before the agent is
+  // registered, so the immediate `agents.get` below used to lose that race EVERY
+  // time: the fallback recorded "agent not registered" and returned, and the
+  // session stayed in the Windows world for good (the harness fixes a preset at
+  // creation). A bounded wait is the difference between a guaranteed loss and a
+  // wait the registry wins.
+  const agent = await waitForAgent(agents, summary?.sessionId)
   if (agent === undefined) {
-    recordBinding({ sessionId: String(summary?.sessionId), cwd, ok: false, error: 'agent 尚未注册' })
+    recordBinding({ sessionId: String(summary?.sessionId), cwd, ok: false, error: 'agent 尚未注册（已等待注册上限）' })
     return
   }
   await bindWslPreset(ctx, agent, cwd, String(summary?.sessionId))

package/lib/protocol.js

@@ -197,8 +197,8 @@ export const CHECK_REMEDIES = deepFreeze({
   },
   runner: {
     kind: 'text',
-    zh: '受限模式需要免密 sudo + unshare/setpriv，或安装 dsh-wsl-confine helper；danger-full-access 不受影响。',
-    en: 'Restricted mode needs passwordless sudo plus unshare/setpriv, or the dsh-wsl-confine helper; danger-full-access is unaffected.',
+    zh: '受限模式需要免密 sudo + unshare/setpriv，或安装 dsh-wsl-confine helper。两条出路：给会话用户配 NOPASSWD sudo，或在权限菜单里选「完全权限」（后者不需要任何 sudo，也不再受文件围栏约束）。',
+    en: 'Restricted mode needs passwordless sudo plus unshare/setpriv, or the dsh-wsl-confine helper. Two ways out: give the session user NOPASSWD sudo, or pick full access in the permission menu — that needs no sudo at all, and is no longer governed by the file fence.',
   },
   helper: {
     kind: 'text',
@@ -236,7 +236,12 @@ export const SAFE_PARAMS = deepFreeze({
   'host-capability-missing': ['feature'],
   'host-plugin-stale': ['method'],
   'too-busy': [],
-  internal: ['ref'],
+  // `step` names WHICH admission step refused the request (a fixed vocabulary:
+  // developer / connection / admit / fence). It exists because the route can
+  // throw before it has any other way to say where — and a browser caller can
+  // never be told the message, since that is where host paths live. It is a
+  // vocabulary word, not host data, which is what makes it safe to send.
+  internal: ['ref', 'step'],
   transport: [],
   'catalog-unavailable': [],
 })

package/lib/release-check.js

@@ -67,3 +67,80 @@ export function installWindow({ publishedAt, minimumReleaseAgeMinutes, now = new
       : `inside the minimumReleaseAge window until ${readyAt.toISOString()}`,
   }
 }
+
+/** The receipt schema this check knows how to read. */
+const RECEIPT_VERSION = 1
+
+/**
+ * The one suite that reaches the route handler, and therefore the only evidence
+ * that the seam works on the installed plugin. Its admitted `bootstrap` check is
+ * what failed to run before 2026-11-14 while the offline gate stayed green.
+ */
+const COVERING_SUITE = 'verify-route.mjs'
+
+/**
+ * Decide whether a recorded gate run may vouch for this release.
+ *
+ * The route-admission seam is covered ONLY by the live suites: an offline run
+ * cannot execute the handler at all, because reaching it needs a browser cookie
+ * or the development token. On 2026-11-14 a host change broke every route call
+ * while the offline gate stayed green at 25/27 — `verify-route.mjs` already
+ * asserted the admitted `bootstrap`, it simply never ran, because it sits in the
+ * LIVE list. The test was there; the release path never demanded it.
+ *
+ * So the release path now demands the receipt of a run that INCLUDED the live
+ * suites, describes the version being released, and failed nothing. The version
+ * comparison is what stops a receipt from an older build vouching for this one.
+ *
+ * `receipt.version` is read from the REPOSITORY manifest, while the live suites
+ * exercise the INSTALLED plugin — so the two could describe different code. They
+ * cannot here, and the reason is transitive: `verify-live-env.mjs` compares the
+ * running host's reported `pluginVersion` against that same manifest and turns a
+ * mismatch into a FAILED check, which lands in `counts.failed` and trips the
+ * rule above. A stale install therefore cannot produce a usable receipt; it
+ * produces a red one.
+ * @param {{ receipt: object|null, target: string }} input - the parsed receipt, or null when absent.
+ * @returns {{ ready: boolean, blockers: string[] }} the verdict.
+ */
+export function liveGateEvidence({ receipt, target }) {
+  if (receipt === null || typeof receipt !== 'object') {
+    return {
+      ready: false,
+      blockers: ['no gate receipt: run `node scripts/verify-all.mjs --live --receipt` before releasing'],
+    }
+  }
+  const blockers = []
+  // The schema version is checked FIRST because every rule below reads fields this
+  // function assumes it understands. A future receipt that redefines `counts` or
+  // `liveRan` would otherwise be interpreted as if it still meant the old thing.
+  if (receipt.receiptVersion !== RECEIPT_VERSION) {
+    blockers.push(`the receipt is schema version ${String(receipt.receiptVersion)}, and this check understands ${RECEIPT_VERSION}`)
+    return { ready: false, blockers }
+  }
+  if (receipt.liveRan !== true) {
+    blockers.push('the recorded gate run did NOT include the live suites (--live), and those are the only cover for the route-admission seam')
+  }
+  const failed = receipt?.counts?.failed
+  if (typeof failed !== 'number' || failed > 0) {
+    blockers.push(`the recorded gate run reported ${typeof failed === 'number' ? failed : 'an unreadable number of'} failure(s)`)
+  }
+  if (receipt.version !== target) {
+    blockers.push(`the receipt describes version ${String(receipt.version)}, not the target ${target} — re-run the gate after the version bump`)
+  }
+  // `liveRan` records the FLAG, not that anything ran. Without this the gate would
+  // accept a receipt whose live suites all skipped — a run that never reached the
+  // host — which is the "a green summary hides what did not run" failure this
+  // whole artefact exists to prevent, reintroduced one layer up.
+  const rows = Array.isArray(receipt.rows) ? receipt.rows : null
+  if (rows === null) {
+    blockers.push('the receipt carries no per-suite rows, so it cannot show that the suite covering the route-admission seam passed')
+  } else {
+    const covering = rows.find((row) => row?.suite === COVERING_SUITE)
+    if (covering === undefined) {
+      blockers.push(`the receipt has no row for ${COVERING_SUITE}, the only suite that reaches the route handler`)
+    } else if (covering.outcome !== 'passed') {
+      blockers.push(`${COVERING_SUITE} is recorded as ${String(covering.outcome)}${covering.reason === undefined || covering.reason === '' ? '' : ` (${covering.reason})`}, and it is the only suite that reaches the route handler`)
+    }
+  }
+  return { ready: blockers.length === 0, blockers }
+}

package/lib/wsl/preset.js

@@ -97,6 +97,14 @@ export const VERDICTED_KEPT_MODULES = new Set([
   '@deepseek-ai/dsh-tool-web',
   '@deepseek-ai/dsh-tool-cordis',
   '@deepseek-ai/dsh-tool-present',
+  // Added when harness 0.2.2-rc.3 shipped it (measured 2026-11-15: a `wsl-standard`
+  // and a `wsl-ptc` row survived unclassified). KEPT, and the reason is its inject
+  // list: `['tools', 'fs', 'workingDirectory', 'agents']` — it reaches files through
+  // the `fs` SERVICE, which a WSL preset mounts from this plugin, and its source
+  // carries no `node:fs`, no `spawn` and no `execFile`. So it neither runs a host
+  // command nor touches host files behind the model's back: it is world-agnostic,
+  // unlike `dsh-tool-executor-ptc`, which injects a host runtime and is removed.
+  '@deepseek-ai/dsh-tool-office',
 ])
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-wsl-desktop",
-  "version": "0.7.6",
+  "version": "0.8.1",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./lib/icon.svg",
@@ -13,8 +13,19 @@
     "prepack": "node -e \"const fs=require('node:fs'),p=require('node:path');(function w(d){for(const e of fs.readdirSync(d,{withFileTypes:true})){if(e.isDirectory()){const f=p.join(d,e.name);if(e.name==='__pycache__'){fs.rmSync(f,{recursive:true,force:true})}else{w(f)}}}})('lib')\""
   },
   "engines": {
-    "node": ">=22.19"
+    "node": ">=22.19",
+    "dsh": ">=0.1.7-0"
   },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "wsl",
+    "wsl2",
+    "workspace",
+    "execution-world",
+    "windows"
+  ],
   "files": [
     "lib",
     "cordis.patch.yml",