dsh-wsl-desktop 0.7.0 → 0.7.2

package/README.en.md

@@ -155,6 +155,7 @@ These are real boundaries, not a disclaimer list. Each one tells you where to re
 - [Diagnostics](docs/DIAGNOSTICS.md) — error codes, the health check, degradation and the privacy boundary
 - [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
 - [Architecture and flow diagrams](docs/diagrams.md) — interactive architecture, sequence and lifecycle diagrams
 

package/README.md

@@ -128,6 +128,7 @@ plugin_manager install_bundle dsh-wsl-desktop@<version>
 - [诊断](docs/DIAGNOSTICS.md) — 错误码、环境检查、宿主能力缺失时的降级与隐私边界
 - [工程笔记](docs/ENGINEERING-NOTES.md) — 实测约束、仓库布局、发版流程、安装形态
 - [发行版支持矩阵](docs/DISTRO-SUPPORT.md) — 哪些发行版验证过，每种缺什么
+- [兼容性与升级](docs/COMPATIBILITY.md) — 插件与桌面的版本关系、升级顺序、回退步骤
 - [上游 API 提案](docs/UPSTREAM-PROPOSALS.md) — 对 harness 上游的两项提案
 - [架构与流程图](docs/diagrams.md) — 可交互的架构、时序与生命周期图
 

package/lib/client.js

@@ -38,6 +38,34 @@ window.__ModuleLoader__.load({
       'M5.54492 2.06738',           // post-refactor ProjectAddOutlineArtwork
     ]
 
+    /**
+     * The same trigger, named by sprite symbol instead of path data.
+     *
+     * Desktop 0.2.1-rc3 (ui-primitives `c3eead771d`) moved every product icon
+     * into the document icon sprite: the header button now renders
+     * `<svg data-icon="dsw-icon-project-add-outline-regular"><use href="#…"/></svg>`
+     * with NO `<path>` child anywhere. The geometry scan above therefore matched
+     * nothing, the anchor read as absent, and the W button stood down on every
+     * 0.2.1-rc3 desktop. The glyph name is the locale-independent identity in
+     * that generation, exactly as the path prefix was in the previous one, and a
+     * theme may replace the artwork without renaming the symbol — so the name
+     * survives the change that broke the geometry.
+     */
+    const TRIGGER_ICON_GLYPHS = ['project-add-outline']
+
+    /** Sprite symbol id shape, as `iconSymbolId` composes it: `dsw-icon-<glyph>-<weight>`. */
+    const SPRITE_ICON_ID = /^#?dsw-icon-(.+)-(?:regular|medium)$/
+
+    /**
+     * The row glyphs whose artwork is FILL-only, as sprite names.
+     *
+     * Only the fallback for a sprite symbol that is not in the document yet; the
+     * live read (`isSolidIcon`) prefers the symbol's own geometry. Versions
+     * qualify the id (`symbolId(glyph, weight)`), so the suffix is not part of a
+     * glyph name and the match is on the glyph alone.
+     */
+    const SOLID_GLYPHS = ['folder-open']
+
     /** Namespace of every SVG node this half creates. */
     const SVG_NS = 'http://www.w3.org/2000/svg'
 
@@ -119,6 +147,10 @@ window.__ModuleLoader__.load({
       healthWarn: { zh: '，{count} 项建议处理', en: ', {count} advisory' },
       healthFail: { zh: '，{count} 项失败', en: ', {count} failed' },
       dialogDescription: { zh: '从 WSL 发行版目录创建工作区。', en: 'Create a workspace from a WSL distribution directory.' },
+      filterPlaceholder: { zh: '过滤当前目录…', en: 'Filter this directory…' },
+      filterLabel: { zh: '按名称过滤目录', en: 'Filter directories by name' },
+      filterEmpty: { zh: '没有匹配的子目录', en: 'No matching subdirectories' },
+      retryList: { zh: '重试读取', en: 'Try again' },
     }
 
     /**
@@ -524,7 +556,7 @@ window.__ModuleLoader__.load({
      * @param {object|null} bootstrap - the bootstrap result.
      * @returns {HTMLElement|null} the node.
      */
-    function renderFailureNode(failure, bootstrap) {
+    function renderFailureNode(failure, bootstrap, state = null) {
       if (failure === null) return null
       const catalog = bootstrap?.ok === true ? bootstrap.value?.catalog : null
       const entry = catalog?.codes?.[failure.code]
@@ -570,9 +602,64 @@ window.__ModuleLoader__.load({
         box.append(link)
       }
       box.append(el('div', { fontSize: '11px', color: T.dim }, failure.code))
+      if (state !== null) {
+        // A failed browse or commit used to offer no report at all; only the
+        // degraded card did. The same report is now one click away on every
+        // failure, with the same redaction rules.
+        const copyAll = el('button', { ...BUTTON_STYLE, padding: '2px 8px', fontSize: '11px', alignSelf: 'flex-start' },
+          t('复制诊断', 'Copy diagnostics'))
+        copyAll.type = 'button'
+        copyAll.setAttribute('data-wsl-diagnostics', '')
+        copyAll.addEventListener('click', () => {
+          void navigator.clipboard?.writeText?.(buildDiagnostics(state, failure))
+          copyAll.textContent = t('已复制', 'Copied')
+          announce(t('已复制', 'Copied'))
+        })
+        box.append(copyAll)
+      }
       return box
     }
 
+    /**
+     * Build the copyable diagnostic report.
+     *
+     * Deliberately excludes the host message, stderr, resolved paths and the raw
+     * failure text: it carries only what the catalog already exposes plus the
+     * doctor's path-free facts. A failure is described by its code and params.
+     * @param {object} state - the open picker's state.
+     * @param {object|null} [failure] - the failure to include, if any.
+     * @returns {string} pretty JSON.
+     */
+    function buildDiagnostics(state, failure = null) {
+      const bootstrap = state.bootstrap
+      const value = bootstrap?.ok === true ? bootstrap.value : null
+      const health = state.health?.status === 'ready'
+        ? {
+          distro: state.health.distro ?? state.distro,
+          user: state.health.user ?? state.user,
+          family: state.health.family ?? null,
+          runner: state.health.runner ?? null,
+          restricted: state.health.restricted ?? null,
+          checks: (state.health.checks ?? []).map((entry) => ({
+            id: entry.id,
+            status: entry.status,
+            ...(typeof entry.detail === 'string' ? { detail: entry.detail } : {}),
+          })),
+        }
+        : null
+      return JSON.stringify({
+        schema: 1,
+        locale: LOCALE,
+        pluginVersion: value?.pluginVersion ?? 'unknown',
+        catalog: value === null ? 'unavailable' : 'loaded',
+        capabilities: value?.capabilities ?? null,
+        features: state.features,
+        missing: state.missing,
+        health,
+        error: failure === null ? null : { code: failure.code, params: failure.params ?? {} },
+      }, null, 2)
+    }
+
     /**
      * The degraded card: what is missing, what to do, and a copyable report.
      * @param {object[]} body - the card's child list.
@@ -603,11 +690,7 @@ window.__ModuleLoader__.load({
       const entry = catalog?.codes?.['host-capability-missing']
       const remedy = entry === undefined ? null : renderRemedy(entry.remedy)
       if (remedy !== null) panel.append(remedy)
-      const diagnostics = JSON.stringify({
-        pluginVersion: state.bootstrap?.ok === true ? state.bootstrap.value?.pluginVersion ?? 'unknown' : 'unknown',
-        features: state.features,
-        missing: state.missing,
-      }, null, 2)
+      const diagnostics = buildDiagnostics(state)
       panel.append(el('pre', {
         margin: '0',
         padding: '8px',
@@ -720,6 +803,8 @@ window.__ModuleLoader__.load({
         home: null,
         path: '/',
         draft: '/',
+        /** Case-insensitive substring filter for the current directory. */
+        filter: '',
         listing: null,
         /** `{code, params}` or null; the raw host message is never rendered. */
         error: null,
@@ -933,7 +1018,7 @@ window.__ModuleLoader__.load({
         }
         if (state.health.status === 'error') {
           strip.setAttribute('data-wsl-health', 'error')
-          const failure = renderFailureNode(state.health.failure, state.bootstrap)
+          const failure = renderFailureNode(state.health.failure, state.bootstrap, state)
           if (failure !== null) strip.append(failure)
           const retry = el('button', {
             ...BUTTON_STYLE,
@@ -1176,7 +1261,7 @@ window.__ModuleLoader__.load({
           renderDegraded(body, state, close, retryDegraded)
         } else {
           if (state.bootstrapError !== null) {
-            const failure = renderFailureNode(state.bootstrapError, state.bootstrap)
+            const failure = renderFailureNode(state.bootstrapError, state.bootstrap, state)
             if (failure !== null) body.push(failure)
           }
 
@@ -1214,7 +1299,7 @@ window.__ModuleLoader__.load({
           body.push(el('div', { display: 'flex', gap: '8px' }, userField, enter))
 
           if (state.error !== null) {
-            const failure = renderFailureNode(state.error, state.bootstrap)
+            const failure = renderFailureNode(state.error, state.bootstrap, state)
             if (failure !== null) body.push(failure)
           }
 
@@ -1263,15 +1348,45 @@ window.__ModuleLoader__.load({
             border: `1px solid ${T.border}`,
             background: T.layer,
           })
-          const directories = (state.listing?.entries ?? []).filter((entry) => entry.kind === 'directory')
+          const allDirectories = (state.listing?.entries ?? []).filter((entry) => entry.kind === 'directory')
+          // Filtering updates the rendered rows in place instead of repainting the
+          // card: a paint per keystroke replaces the input and steals focus (and
+          // breaks IME composition). The initial paint applies the stored filter.
+          const matchesFilter = (name) => state.filter === ''
+            || name.toLowerCase().includes(state.filter.toLowerCase())
+          const empty = el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('filterEmpty'))
+          empty.style.display = 'none'
+          const applyFilter = () => {
+            let visible = 0
+            for (const node of list.querySelectorAll('[data-wsl-entry]')) {
+              const shown = matchesFilter(node.getAttribute('data-name') ?? '')
+              node.style.display = shown ? 'block' : 'none'
+              if (shown) visible += 1
+            }
+            empty.style.display = visible === 0 ? 'block' : 'none'
+            if (state.filter !== '') empty.setAttribute('data-wsl-filter-empty', '')
+            else empty.removeAttribute('data-wsl-filter-empty')
+          }
+          if (state.listing !== null) {
+            const filter = el('input', FIELD_STYLE)
+            filter.value = state.filter
+            filter.placeholder = copy('filterPlaceholder')
+            filter.setAttribute('data-wsl-filter', '')
+            filter.setAttribute('aria-label', copy('filterLabel'))
+            filter.addEventListener('input', () => {
+              state.filter = filter.value
+              applyFilter()
+            })
+            body.push(filter)
+          }
           if (state.listing === null) {
             list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('readingDir')))
-          } else if (directories.length === 0) {
+          } else if (allDirectories.length === 0) {
             list.append(el('div', { fontSize: '12px', color: T.dim, padding: '6px' }, copy('noSubdirs')))
           } else {
-            for (const entry of directories) {
+            for (const entry of allDirectories) {
               const item = el('button', {
-                display: 'block',
+                display: matchesFilter(entry.name) ? 'block' : 'none',
                 width: '100%',
                 textAlign: 'left',
                 border: 'none',
@@ -1284,11 +1399,16 @@ window.__ModuleLoader__.load({
                 cursor: 'pointer',
               }, `📁 ${entry.name}`)
               item.type = 'button'
+              item.setAttribute('data-wsl-entry', '')
+              item.setAttribute('data-name', entry.name)
               item.addEventListener('mouseenter', () => { item.style.background = T.hover })
               item.addEventListener('mouseleave', () => { item.style.background = 'transparent' })
               item.addEventListener('click', () => { go(joinLinux(state.path, entry.name)) })
               list.append(item)
             }
+            list.append(empty)
+            if (state.filter !== '') empty.setAttribute('data-wsl-filter-empty', '')
+            applyFilter()
           }
           body.push(list)
           if (typeof state.listing?.hidden === 'number' && state.listing.hidden > 0) {
@@ -1308,8 +1428,19 @@ window.__ModuleLoader__.load({
           }
 
           if (state.error !== null) {
-            const failure = renderFailureNode(state.error, state.bootstrap)
+            const failure = renderFailureNode(state.error, state.bootstrap, state)
             if (failure !== null) body.push(failure)
+            // A failed listing left the operator with an error and no way back to
+            // the directory they were reading. Retrying the same load is safe; a
+            // failed commit is deliberately excluded because it may have created
+            // the workspace before the error.
+            if (state.listing === null && !state.working) {
+              const retryList = el('button', BUTTON_STYLE, copy('retryList'))
+              retryList.type = 'button'
+              retryList.setAttribute('data-wsl-list-retry', '')
+              retryList.addEventListener('click', () => { void load() })
+              body.push(el('div', { display: 'flex', justifyContent: 'flex-start' }, retryList))
+            }
           }
 
           const cancel = el('button', BUTTON_STYLE, copy('cancel'))
@@ -1373,15 +1504,68 @@ window.__ModuleLoader__.load({
     /** Whether the missing-workspace-source warning was already printed. */
     let warnedWorkspaceSource = false
 
-    /** Find the shipped "add workspace" trigger by its icon geometry. */
-    function findTrigger() {
+    /**
+     * The sprite glyph one `<use>` reference names, or null.
+     *
+     * Accepts both the bare symbol id and the `#`-prefixed href form, and both
+     * `href` and the legacy `xlink:href` spelling, because an icon may render
+     * either. Returning the GLYPH (not the whole id) lets the trigger list stay
+     * a list of glyph names, which is what a desktop generation actually fixes.
+     * @param {Element} node - a `<use>` element.
+     * @returns {string | null} the glyph name, or null when it is not a sprite ref.
+     */
+    function spriteGlyphOf(node) {
+      const ref = node.getAttribute('href')
+        ?? node.getAttributeNS('http://www.w3.org/1999/xlink', 'href')
+      if (ref === null) return null
+      return SPRITE_ICON_ID.exec(ref)?.[1] ?? null
+    }
+
+    /**
+     * The candidate trigger buttons carrying one generation's icon identity.
+     *
+     * Each generation is ONE document-level selector rather than a walk over
+     * every button: `findTrigger` re-runs on every animation frame whenever the
+     * anchor is missing, so a per-button subtree query would turn a single scan
+     * into N of them exactly when the header is already in trouble.
+     * @param {string} selector - the icon nodes this generation renders.
+     * @param {(node: Element) => boolean} identifies - whether one icon is the trigger's.
+     * @returns {HTMLElement[]} the distinct buttons owning a matching icon.
+     */
+    function triggerCandidates(selector, identifies) {
       const matches = []
-      for (const path of document.querySelectorAll('svg > path[d]')) {
-        const d = path.getAttribute('d')
-        if (!TRIGGER_ICON_PATHS.some((geometry) => d.startsWith(geometry))) continue
-        const trigger = path.closest('button')
+      for (const icon of document.querySelectorAll(selector)) {
+        if (!identifies(icon)) continue
+        const trigger = icon.closest('button')
         if (trigger !== null && !matches.includes(trigger)) matches.push(trigger)
       }
+      return matches
+    }
+
+    /** Whether one inline path carries the add-workspace geometry. */
+    function isTriggerPath(path) {
+      const d = path.getAttribute('d')
+      return TRIGGER_ICON_PATHS.some((geometry) => d.startsWith(geometry))
+    }
+
+    /**
+     * Whether one icon node is the add-workspace artwork, in either generation.
+     *
+     * A sprite icon is identified by `data-icon` (the id the component was
+     * CONSTRUCTED with, which a theme replacement does not change) and, failing
+     * that, by the `<use>` reference it renders.
+     * @param {Element} icon - an inline path or a sprite `<svg>`/`<use>`.
+     * @returns {boolean} true when it is the trigger's artwork.
+     */
+    function isTriggerIcon(icon) {
+      if (icon.tagName === 'path') return isTriggerPath(icon)
+      const declared = icon.tagName === 'svg' ? icon.getAttribute('data-icon') : null
+      const glyph = declared !== null ? SPRITE_ICON_ID.exec(declared)?.[1] : spriteGlyphOf(icon)
+      return glyph !== undefined && glyph !== null && TRIGGER_ICON_GLYPHS.includes(glyph)
+    }
+
+    /** Pick the trigger out of one generation's candidates, or null. */
+    function pickTrigger(matches) {
       if (matches.length <= 1) return matches[0] ?? null
       // More than one control carries the geometry. The shipped trigger is the
       // one inside a `*_headerActions` cluster — the CSS-module local name is
@@ -1391,6 +1575,24 @@ window.__ModuleLoader__.load({
       return matches.find((trigger) => hasHeaderActionsParent(trigger)) ?? null
     }
 
+    /**
+     * Find the shipped "add workspace" trigger in either desktop generation.
+     *
+     * The sprite generation is scanned FIRST because it is the newer one: on a
+     * desktop that renders it, that single scan is the whole cost. Only a
+     * desktop with no sprite icon anywhere falls through to the geometry scan,
+     * which is what every release before 0.2.1-rc3 needed.
+     * @returns {HTMLElement | null} the anchor, or null when this desktop has none.
+     */
+    function findTrigger() {
+      const sprite = triggerCandidates('svg[data-icon], use', isTriggerIcon)
+      // A non-empty sprite result is this desktop's answer even when it is
+      // ambiguous: `pickTrigger` returns null there to mean "stand down", and
+      // falling through would let an unrelated inline icon pick the anchor.
+      if (sprite.length > 0) return pickTrigger(sprite)
+      return pickTrigger(triggerCandidates('svg > path[d]', isTriggerIcon))
+    }
+
     /**
      * Whether one trigger sits in the shipped trailing action cluster.
      * @param {HTMLElement} trigger - a candidate trigger button.
@@ -1534,7 +1736,7 @@ window.__ModuleLoader__.load({
         // artwork fills its paths, the collapsed one strokes them. A rebuild is
         // owed whenever that flips, which is exactly what expanding a workspace
         // does to this span.
-        const solid = shipped !== null && shipped.querySelector('path[stroke]') === null
+        const solid = isSolidIcon(shipped)
         const weight = solid ? 'solid' : 'outline'
         if (mine !== null && mine.dataset.wslCloudWeight !== weight) {
           mine.remove()
@@ -1545,6 +1747,56 @@ window.__ModuleLoader__.load({
       }
     }
 
+    /**
+     * The sprite symbol an icon element references, as a bare symbol id.
+     *
+     * `data-icon` is the id the icon COMPONENT was built with, so it keeps the
+     * shipped symbol even when a theme points the `<use>` href at its own
+     * artwork; the href is the fallback for markup that omits `data-icon`.
+     * @param {Element} icon - one icon `<svg>`.
+     * @returns {string | null} the symbol id without `#`, or null.
+     */
+    function spriteSymbolOf(icon) {
+      const declared = icon.getAttribute('data-icon')
+      if (typeof declared === 'string' && declared !== '') return declared.replace(/^#/, '')
+      for (const use of icon.querySelectorAll('use')) {
+        const ref = use.getAttribute('href')
+          ?? use.getAttributeNS('http://www.w3.org/1999/xlink', 'href')
+        if (typeof ref === 'string' && ref !== '') return ref.replace(/^#/, '')
+      }
+      return null
+    }
+
+    /**
+     * Whether one workspace row icon renders the FILL-only artwork.
+     *
+     * The collapsed row strokes its folder outline and the expanded one fills
+     * it, and the cloud has to match whichever is showing. Up to 0.2.1-rc2 the
+     * artwork was inline, so a stroked `<path>` was the tell. From 0.2.1-rc3 the
+     * icon is a sprite reference with NO path child anywhere: the weight then
+     * belongs to the SYMBOL in the document sprite, not to the `<svg>` naming
+     * it. Reading only the inline shape (as this did) made every sprite row look
+     * fill-only, so a collapsed row got the solid cloud.
+     * @param {Element | null} icon - the shipped folder icon, if the row renders one.
+     * @returns {boolean} true when the icon is the fill-only artwork.
+     */
+    function isSolidIcon(icon) {
+      if (icon === null) return false
+      // Inline generation: the artwork declares its own weight.
+      if (icon.querySelector('path[d]') !== null) return icon.querySelector('path[stroke]') === null
+      const symbolId = spriteSymbolOf(icon)
+      if (symbolId === null) return false
+      const symbol = document.getElementById(symbolId)
+      // Sprite generation, symbol present: judge the artwork the browser paints,
+      // so a theme's own geometry is measured rather than assumed.
+      if (symbol !== null) return symbol.querySelector('path[stroke]') === null
+      // Sprite generation, symbol not in the document (a theme may mount its
+      // own sprite later): fall back to the glyph name, which is the fill-only
+      // identity in the shipped table.
+      const glyph = SPRITE_ICON_ID.exec(`#${symbolId}`)?.[1]
+      return glyph !== undefined && glyph !== null && SOLID_GLYPHS.includes(glyph)
+    }
+
     /**
      * Whether one observed mutation could have changed a workspace row's markup.
      *

package/lib/index.js

@@ -25,7 +25,7 @@ import {
 } from './http-admission.js'
 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 { checkLinuxPath, defaultDistro, defaultWorkspaceUnc, listDistros, listLinuxDir, resolveDistroHome, runWslShell, wslMajorVersion } from './wsl/world.js'
 import { joinWslUnc, parseWslUnc, shellQuote, windowsToMntPath } from './wsl/paths.js'
 import { WslRouteError, browserFailure, routeErrorFor } from './route-errors.js'
 import { CHECK_IDS, CHECK_LABELS, CHECK_REMEDIES, DOCS, ERROR_CODES, FEATURE_IDS, FEATURE_LABELS } from './protocol.js'
@@ -506,7 +506,13 @@ const METHODS = {
   health: async ({ distro, username }) => {
     assertDistro(distro)
     assertUser(username)
-    return healthFor({ distro, username, wslPath: routeWslPath })
+    // Host-side: the distribution cannot report its own WSL generation.
+    return healthFor({
+      distro,
+      username,
+      wslPath: routeWslPath,
+      wslVersionProbe: ({ distro: name }) => wslMajorVersion(name, { wslPath: routeWslPath }),
+    })
   },
 
   /**

package/lib/protocol.js

@@ -141,7 +141,7 @@ export const FEATURE_LABELS = deepFreeze({
 })
 
 /** Health-check ids, in display order. */
-export const CHECK_IDS = deepFreeze(['bash', 'python3', 'util-linux', 'getent', 'runner', 'helper', 'nnp'])
+export const CHECK_IDS = deepFreeze(['bash', 'python3', 'util-linux', 'getent', 'runner', 'helper', 'nnp', 'wsl2'])
 
 /** Human-readable check names. */
 export const CHECK_LABELS = deepFreeze({
@@ -152,6 +152,7 @@ export const CHECK_LABELS = deepFreeze({
   runner: { zh: '受限模式 runner', en: 'Confinement runner' },
   helper: { zh: 'dsh-wsl-confine helper', en: 'dsh-wsl-confine helper' },
   nnp: { zh: 'NO_NEW_PRIVS', en: 'NO_NEW_PRIVS' },
+  wsl2: { zh: 'WSL2', en: 'WSL2' },
 })
 
 /** The fix for one failed check, keyed by check id. */
@@ -209,6 +210,11 @@ export const CHECK_REMEDIES = deepFreeze({
     zh: 'setpriv 不支持 --no-new-privs，受限模式不会运行；升级发行版的 util-linux。',
     en: 'setpriv lacks --no-new-privs, so restricted mode refuses to run; upgrade the distribution util-linux.',
   },
+  wsl2: {
+    kind: 'text',
+    zh: 'WSL1 不支持：在 Windows 侧运行 `wsl.exe --set-version <发行版> 2` 升级到 WSL2 后再试。',
+    en: 'WSL1 is unsupported: run `wsl.exe --set-version <distro> 2` on Windows to upgrade it to WSL2 first.',
+  },
 })
 
 /**

package/lib/release-check.js

@@ -0,0 +1,69 @@
+/**
+ * Pure publish-readiness rules.
+ *
+ * The 0.7.0 release learned two preconditions the hard way: an expired npm token
+ * (checked by the caller, not here) and pnpm's `minimumReleaseAge` refusing a
+ * just-published version during `install_bundle`. These rules are pure so the
+ * release runbook and the offline suite can pin them without a registry.
+ * @module dsh-wsl-desktop/release-check
+ */
+
+/**
+ * Compare two dotted numeric versions.
+ * @param {string} a - the left version.
+ * @param {string} b - the right version.
+ * @returns {number} -1, 0 or 1.
+ */
+export function compareVersions(a, b) {
+  const left = String(a).split('.').map((part) => Number.parseInt(part, 10) || 0)
+  const right = String(b).split('.').map((part) => Number.parseInt(part, 10) || 0)
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0) - (right[index] ?? 0)
+    if (difference !== 0) return difference > 0 ? 1 : -1
+  }
+  return 0
+}
+
+/**
+ * Decide whether a version can be published.
+ * @param {{ target: string, latest: string|null, published?: boolean, localTag?: boolean, remoteTag?: boolean, dirty?: boolean }} input -
+ *   the target and the facts gathered by the caller.
+ * @returns {{ ready: boolean, blockers: string[] }} the verdict.
+ */
+export function classifyPublish({ target, latest, published = false, localTag = false, remoteTag = false, dirty = false }) {
+  const blockers = []
+  if (latest === null || latest === undefined) {
+    blockers.push('the registry latest version is unknown (npm view failed)')
+  } else if (compareVersions(target, latest) <= 0) {
+    blockers.push(`target ${target} is not newer than the registry latest ${latest}`)
+  }
+  if (published === true) blockers.push(`target ${target} is already published`)
+  if (localTag === true) blockers.push(`a local tag v${target} already exists`)
+  if (remoteTag === true) blockers.push(`a remote tag v${target} already exists`)
+  if (dirty === true) blockers.push('the working tree carries tracked changes')
+  return { ready: blockers.length === 0, blockers }
+}
+
+/**
+ * When a freshly published version becomes installable under pnpm's minimum age.
+ * @param {{ publishedAt: string|null, minimumReleaseAgeMinutes: number, now: Date }} input -
+ *   the registry publish time, the configured window and the current time.
+ * @returns {{ ready: boolean|null, readyAt: Date|null, detail: string }} the verdict.
+ */
+export function installWindow({ publishedAt, minimumReleaseAgeMinutes, now = new Date() }) {
+  if (publishedAt === null || publishedAt === undefined || publishedAt === '') {
+    return { ready: null, readyAt: null, detail: 'the registry publish time is unreadable; wait one full window before retrying' }
+  }
+  const published = new Date(publishedAt)
+  if (Number.isNaN(published.getTime()) || !Number.isFinite(minimumReleaseAgeMinutes)) {
+    return { ready: null, readyAt: null, detail: 'the publish time or the minimum age is unreadable' }
+  }
+  const readyAt = new Date(published.getTime() + minimumReleaseAgeMinutes * 60_000)
+  return {
+    ready: now.getTime() >= readyAt.getTime(),
+    readyAt,
+    detail: now.getTime() >= readyAt.getTime()
+      ? 'outside the minimumReleaseAge window'
+      : `inside the minimumReleaseAge window until ${readyAt.toISOString()}`,
+  }
+}

package/lib/wsl/doctor.js

@@ -192,7 +192,7 @@ async function probeHelperVersion({ distro, username, run, wslPath }) {
  * @param {object} options - probe inputs.
  * @returns {Promise<object>} the health answer.
  */
-async function computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe }) {
+async function computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe, wslVersionProbe }) {
   // The cached probes call `run` themselves and do not know about the plugin's
   // configured wsl.exe path, so the doctor binds it once for every probe it hands
   // them. Without this they silently fall back to the bare `wsl.exe`.
@@ -206,11 +206,16 @@ async function computeHealth({ distro, username, run, wslPath, now, runnerProbe,
     run: probeRun,
     cacheKey: typeof wslPath === 'string' ? wslPath : '',
   }
-  const [values, runnerOutcome, nnpOutcome] = await Promise.all([
+  const [values, runnerOutcome, nnpOutcome, wslVersionOutcome] = await Promise.all([
     runBatch({ distro, username, run, wslPath }),
     bounded(Promise.resolve().then(() => runnerProbe(probeOptions)), PROBE_RACE_MS),
     bounded(Promise.resolve().then(() => nnpProbe(probeOptions)), PROBE_RACE_MS),
+    // Host-side, not in-distro: a WSL1 distribution's mount-namespace semantics
+    // are not visible from inside it. The route passes a real probe; the suite
+    // injects one, so no new spawn leaks into the existing cases.
+    bounded(Promise.resolve().then(() => wslVersionProbe({ distro, wslPath })), PROBE_RACE_MS),
   ])
+  const wslVersion = wslVersionOutcome?.value ?? null
 
   const measured = Object.keys(values).length > 0
   const family = distroFamily(values)
@@ -290,6 +295,13 @@ async function computeHealth({ distro, username, run, wslPath, now, runnerProbe,
     } else {
       add('nnp', 'unknown', 'unmeasured')
     }
+    if (wslVersion === '1') {
+      add('wsl2', 'fail', 'WSL1 distribution; the mount-namespace boundary needs WSL2')
+    } else if (wslVersion === '2') {
+      add('wsl2', 'pass', 'WSL2')
+    } else {
+      add('wsl2', 'unknown', 'not measured')
+    }
   }
 
   const statusOf = (id) => checks.find((entry) => entry.id === id)?.status
@@ -320,6 +332,7 @@ export async function healthFor({
   runnerProbe = detectRunner,
   nnpProbe = detectNoNewPrivs,
   helperProbe = probeHelperVersion,
+  wslVersionProbe = async () => null,
 }) {
   const key = `${distro}\0${username ?? ''}\0${wslPath ?? ''}`
   const cached = healthCache.get(key)
@@ -328,7 +341,7 @@ export async function healthFor({
   }
   const inflight = healthInflight.get(key)
   if (inflight !== undefined) return inflight
-  const pending = computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe })
+  const pending = computeHealth({ distro, username, run, wslPath, now, runnerProbe, nnpProbe, helperProbe, wslVersionProbe })
     .then((result) => {
       healthCache.set(key, { at: now(), result })
       // The key carries a browser-supplied user; a page could churn spellings to

package/lib/wsl/paths.js

@@ -20,8 +20,19 @@ const UNC_HOSTS = new Set(['wsl.localhost', 'wsl$'])
  * directory, so `\\wsl.localhost\..\<path>` would hand the share a traversal
  * spelling. No real distribution name is all dots, and `wsl.exe -d ..` cannot be
  * a legal invocation, so the lookahead costs nothing legitimate.
+ *
+ * A LEADING HYPHEN is refused for a different reason: the value becomes the token
+ * after `wsl.exe -d`, and an argv element that begins with `-` is not a provably
+ * safe option VALUE. Measured on wsl.exe: `-d --cd --cd /x` and `-d -dfoo` both
+ * fail with WSL_E_DISTRO_NOT_FOUND rather than re-reading the token as an option,
+ * so the practical outcome is a clean refusal and no command — but the invariant
+ * `buildWslExecArgv` states (option values validated against our own grammars, so
+ * exec-path safety never depends on wsl.exe's undocumented tokenization) was not
+ * actually enforced for this value. The sibling grammar LINUX_USER below already
+ * forces a safe first character, so `-u` was refused while `-d` was not; this
+ * lookahead makes the pair agree. No real distribution name begins with `-`.
  */
-export const DISTRO_NAME = /^(?!\.+$)[A-Za-z0-9._-]+$/
+export const DISTRO_NAME = /^(?!-)(?!\.+$)[A-Za-z0-9._-]+$/
 
 /** A Linux user name that is safe to pass as a single wsl.exe -u option value. */
 export const LINUX_USER = /^[A-Za-z0-9._][A-Za-z0-9._-]*\$?$/

package/lib/wsl/pty.js

@@ -15,7 +15,7 @@
  * @module dsh-wsl-desktop/wsl/pty
  */
 
-import { appendFileSync } from 'node:fs'
+import { appendFileSync, renameSync, statSync } from 'node:fs'
 import { randomUUID } from 'node:crypto'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
@@ -48,9 +48,25 @@ const DEFAULT_ROWS = 24
 const verifiedDistros = new Set()
 
 /**
- * Append one diagnostic line to the terminal debug log (bounded). Temporary
- * instrumentation for the live GUI-path terminal failure; harmless if the
- * file cannot be written.
+ * Ceiling for the opt-in terminal debug log, and the size at which it rotates.
+ *
+ * The doc comment on `termLog` used to call the sink "bounded" while the body was a
+ * bare `appendFileSync` with no cap, no rotation and no redaction: a host that left
+ * `WSL_DESKTOP_TERMINAL_DEBUG=1` set grew the file without limit. Rotation is
+ * one-generation (`.1`), which bounds the pair at ~2x this figure and needs no
+ * bookkeeping beyond a `statSync`.
+ */
+const TERMINAL_LOG_MAX_BYTES = 5 * 1024 * 1024
+
+/**
+ * Append one diagnostic line to the terminal debug log (bounded and rotated).
+ * Temporary instrumentation for the live GUI-path terminal failure; harmless if
+ * the file cannot be written.
+ *
+ * Callers must NOT hand this full argv vectors. A command line can carry a secret
+ * (`tool --token=…`), and this file is plaintext under `$DSH_HOME`, readable by any
+ * host-side reader of the profile. Describe the argv by its length and program
+ * name instead — see `describeArgv`.
  * @param {string} message - the diagnostic line.
  */
 export function termLog(message) {
@@ -58,12 +74,40 @@ export function termLog(message) {
   // without bound on every terminal allocation.
   if (process.env.WSL_DESKTOP_TERMINAL_DEBUG !== '1') return
   try {
-    appendFileSync(join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'wsl-desktop-terminal-debug.log'), `${new Date().toISOString()} ${message}\n`)
+    const path = join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'wsl-desktop-terminal-debug.log')
+    // Rotate BEFORE appending, so the file cannot cross the ceiling even by one
+    // line: the check is "would this write exceed it", not "has it already".
+    try {
+      const { size } = statSync(path)
+      if (size >= TERMINAL_LOG_MAX_BYTES) renameSync(path, `${path}.1`)
+    } catch {
+      // Absent (first write) or unreadable: appending is still safe.
+    }
+    appendFileSync(path, `${new Date().toISOString()} ${message}\n`)
   } catch {
     // Diagnostics must never break allocation.
   }
 }
 
+/**
+ * Describe an argv vector without reproducing it.
+ *
+ * The program name (argv[0]) and the element count are enough to tell "the bridge
+ * got the right shape" from "it got a different one", which is what these log lines
+ * exist for. The remaining elements are where secrets live, so they are never
+ * written: the count preserves the shape evidence and nothing else is lost that the
+ * log was actually used for.
+ * @param {readonly string[] | undefined} argv - the vector to describe.
+ * @returns {string} a redacted description, e.g. `bash (3 args)`.
+ */
+export function describeArgv(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) return '(no argv)'
+  const program = String(argv[0])
+  // The program itself may be a full path; its basename is the informative part.
+  const name = program.split(/[\\/]/).pop() ?? program
+  return `${name} (${argv.length - 1} args)`
+}
+
 /**
  * Report a diagnostic that must be VISIBLE without the opt-in debug log.
  *
@@ -782,7 +826,7 @@ export async function spawnWslTerminal({
       return false
     },
   ))
-  termLog(`allocate: distro=${plan.distro} linuxCwd=${JSON.stringify(plan.linuxCwd)} windowsCwd=${JSON.stringify(plan.windowsCwd)} argv0=${JSON.stringify(argv[0])} cols=${String(size.cols)} rows=${String(size.rows)} fifo=${fifo}`)
+  termLog(`allocate: distro=${plan.distro} linuxCwd=${JSON.stringify(plan.linuxCwd)} windowsCwd=${JSON.stringify(plan.windowsCwd)} argv=${describeArgv(argv)} cols=${String(size.cols)} rows=${String(size.rows)} fifo=${fifo}`)
   await requireBridgeRuntime(plan, select)
   termLog('allocate: bridge runtime ok')
   // The other generation's orphans, swept at the one moment this process can classify them:
@@ -943,10 +987,46 @@ export async function spawnWslTerminal({
     termLog(`announce ok: pid=${String(announce.pid)} pgrp=${String(announce.pgrp)} fifo=${fifo}`)
 
     control = local.spawn({
+      // The writer must NOT be able to outlive the reader it exists for.
+      //
+      // Measured defect (2026-10-24, twice on one host): when the bridge died, the
+      // data-done handler below called `control.terminate()`, which kills this
+      // wsl.exe CLIENT — but the writer runs inside the distribution and was
+      // reparented to /init, where its blocking `exec 3>"$1"` never returned. It
+      // then held the FIFO forever, and because every allocation mints a fresh
+      // random name no later session could reclaim it. The next terminal send
+      // waited for a readiness signal that never came and surfaced as
+      // `PTY send aborted before write`.
+      //
+      // A `bash` formulation CANNOT fix this, and that was measured rather than
+      // assumed: `test -w` on a FIFO reports the permission BITS, not a live
+      // reader, so a `[ -w ]` liveness loop passes immediately and then blocks
+      // forever in `exec 3>"$fifo"` (measured: hung until an outer timeout at
+      // 12004ms). Shell has no non-blocking open.
+      //
+      // So the open goes through python3, which IS already a hard prerequisite of
+      // this path — requireBridgeRuntime refuses an allocation without it, so
+      // using it here adds no new dependency. O_WRONLY|O_NONBLOCK turns "no reader
+      // yet" and "no reader any more" into an ENXIO/CleanIO failure instead of an
+      // indefinite block, which is exactly the property the orphan lacked.
+      //
+      // Measured on the shipped formulation: no reader -> exits in 15ms; live
+      // reader -> both control lines delivered; reader vanishing mid-stream ->
+      // exits within ~3.5s. The FIFO is also 0600 and created before the announce,
+      // so a reader normally exists before this process starts.
       argv: buildWslExecArgv(plan, [
-        'bash', '-c',
-        'exec 3>"$1" || exit 1; while IFS= read -r line; do printf \'%s\\n\' "$line" >&3; done',
-        'bash', fifo,
+        'python3', '-c',
+        'import os,sys\n'
+          + 'try:\n'
+          + '    fd=os.open(sys.argv[1],os.O_WRONLY|os.O_NONBLOCK)\n'
+          + 'except OSError:\n'
+          + '    sys.exit(0)\n'
+          + 'try:\n'
+          + '    for line in sys.stdin:\n'
+          + '        os.write(fd,line.encode())\n'
+          + 'finally:\n'
+          + '    os.close(fd)\n',
+        fifo,
       ], select),
       cwd: plan.windowsCwd,
       stdio: { stdin: 'pipe', stdout: 'ignore', stderr: 'pipe' },

package/lib/wsl/subprocess.js

@@ -29,7 +29,7 @@ import { SubprocessExecutableNotFoundError, SubprocessRuntime } from '@deepseek-
 import z from '@deepseek-ai/schemastery'
 import { requireLocalSubprocess } from './host-refs.js'
 import { shellQuote } from './paths.js'
-import { spawnWslTerminal, termLog } from './pty.js'
+import { describeArgv, spawnWslTerminal, termLog } from './pty.js'
 import { LoginShellUnresolvedError, WSL_CHILD_ENV, buildWslExecArgv, planWsl, resolveLoginShell, runWslShell, withWslEnvFlags } from './world.js'
 
 /**
@@ -287,7 +287,7 @@ export class WslSubprocessRuntime extends SubprocessRuntime {
       const terminalArgv = WINDOWS_SHELLS.has(base0)
         ? [await resolveLoginShell(plan.distro, this.config.username, { wslPath: this.config.wslPath })]
         : spec.argv
-      termLog(`spawnTerminal: distro=${plan.distro} linuxCwd=${JSON.stringify(plan.linuxCwd)} terminalArgv=${JSON.stringify(terminalArgv)} terminalType=${String(spec.terminalType)} username=${JSON.stringify(this.config.username ?? null)}`)
+      termLog(`spawnTerminal: distro=${plan.distro} linuxCwd=${JSON.stringify(plan.linuxCwd)} terminalArgv=${describeArgv(terminalArgv)} terminalType=${String(spec.terminalType)} username=${JSON.stringify(this.config.username ?? null)}`)
       const handle = await spawnWslTerminal({
         local: requireLocalSubprocess(),
         plan,

package/lib/wsl/world.js

@@ -231,6 +231,59 @@ export async function listDistros({ wslPath = 'wsl.exe' } = {}) {
     .filter((line) => line.length > 0)
 }
 
+/**
+ * The WSL major version of one distribution, from `wsl.exe -l -v`.
+ *
+ * WSL1 is explicitly unsupported (its syscall translation layer has no mount
+ * namespace), but until now nothing in the product asked the host which version a
+ * distribution runs. The output is a table:
+ *
+ *   `  NAME      STATE           VERSION`
+ *   `* debian    Running         2`
+ *
+ * The active marker is optional; the version is the last column. A table that
+ * cannot be parsed answers `null` — an unmeasured fact is not a failure.
+ * @param {string} distro - the distribution name.
+ * @param {{ wslPath?: string }} [options] - the configured `wsl.exe` path.
+ * @returns {Promise<'1'|'2'|null>} the major version, or null when unreadable.
+ */
+export async function wslMajorVersion(distro, { wslPath = 'wsl.exe' } = {}) {
+  let stdout
+  try {
+    ({ stdout } = await execFileAsync(wslPath, ['-l', '-v'], {
+      encoding: 'buffer',
+      timeout: DISCOVERY_TIMEOUT_MS,
+      env: { ...process.env, ...WSL_CHILD_ENV },
+    }))
+  } catch {
+    return null
+  }
+  return parseWslVersionTable(decodeWslOutput(stdout), distro)
+}
+
+/**
+ * Pick one distribution's major version out of a `wsl.exe -l -v` table.
+ *
+ * Kept pure and exported so the table's spacing variants are testable without a
+ * real WSL host. The active marker (`*`) is optional; the last column is VERSION.
+ * @param {unknown} text - the decoded table.
+ * @param {string} distro - the distribution name.
+ * @returns {'1'|'2'|null} the major version, or null when the row is absent.
+ */
+export function parseWslVersionTable(text, distro) {
+  const lines = String(text ?? '').split(/\r?\n/)
+  for (const raw of lines) {
+    const line = raw.replace(/\0/g, '').trim()
+    if (line === '') continue
+    const cells = line.replace(/^\*\s*/, '').split(/\s{2,}|\t/).filter((cell) => cell !== '')
+    if (cells.length < 2) continue
+    if (cells[0] !== distro) continue
+    const version = cells[cells.length - 1]
+    return version === '1' || version === '2' ? version : null
+  }
+  return null
+}
+
 /**
  * The Lxss registry values and the two REG_SZ lines the default-distribution read needs.
  *

package/package.json

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