dsh-wsl-bridge 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-## 0.4.6 — 2026-10-19 (unreleased)
+## 0.4.7 — 2026-10-19
+
+- A new conversation that selects WSL lists the current distribution's
+  folders, starting at `$HOME`, and asks which folder should become the
+  workspace. The folder control opens that directory instead of DSH's
+  `default-workspace`. The Windows path is whatever `wslpath -w` prints on
+  that computer. Esc closes the visit; choosing WSL again after leaving the
+  mode asks once more. Host-wide `wsl_*` tools still use the Windows session
+  directory.
+- The picker keeps an opaque surface when a skin makes the app background
+  translucent.
+- The WSL preset description is Chinese.
+
+## 0.4.6 — 2026-10-19
 
 - A `WSL` session now uses the current distribution's `$HOME` as its default
   workspace. The first bash command, relative paths, and grep/glob without a

package/README.en.md

@@ -4,17 +4,17 @@
 
 A native WSL (Linux) execution surface for [DSH](https://github.com/deepseek-ai/DeepSeek-Harness) on Windows. It starts no extra web server and installs nothing inside the distribution. Windows sessions and WSL sessions share one desktop app.
 
-Version **0.4.6**. Requires **Windows**, a working WSL distribution, and **DSH `>= 0.2.1-rc.2`**. Source: <https://github.com/TGWgulugu/dsh-wsl-bridge>
+Version **0.4.7**. Requires **Windows**, a working WSL distribution, and **DSH `>= 0.2.1-rc.2`**. Source: <https://github.com/TGWgulugu/dsh-wsl-bridge>
 
 ## Install
 
-Run this in a normal terminal, not inside a DSH tool sandbox. If `dsh` is not on `PATH`, use the full path to the `dsh.cmd` that ships with DSH Desktop.
+The plugin is published on npm as [dsh-wsl-bridge](https://www.npmjs.com/package/dsh-wsl-bridge). Run this in a normal terminal, not inside a DSH tool sandbox. DSH installs that npm package. If `dsh` is not on `PATH`, use the full path to the `dsh.cmd` that ships with DSH Desktop.
 
 ```powershell
 dsh plugin --profile desktop add dsh-wsl-bridge
 ```
 
-Before the package is published, or to install the checkout you have open:
+To install the source in this repository instead of the npm release:
 
 ```powershell
 dsh plugin --profile desktop add .
@@ -58,17 +58,21 @@ A routing note is on by default: for Linux work, prefer `wsl_bash` and Linux pat
 
 Choose **WSL** when creating a session. In that session, `bash`, `read`, `write`, `edit`, `grep`, and `glob` run inside Linux and take Linux paths. Persona, skills, goals, plan mode, compaction, subagents, todos, web, and present stay the standard DSH set.
 
-**The default workspace is the current distribution's home directory (`$HOME`).** The first `bash` starts there. Relative paths resolve there. `grep` and `glob` search there when `path` is omitted. Pass `/mnt/<drive>/...` when the search should cover a Windows directory.
+**You choose the workspace inside the current distribution.** On a new conversation, selecting WSL lists that distribution's folders, starting at `$HOME`. Open a subfolder or go up a level, then confirm with "Use this folder". The chosen directory is whatever `wslpath -w` prints on that computer. No distribution name or username is built into the plugin. The folder control opens that directory instead of DSH's `default-workspace`.
+
+Esc or Cancel closes the window for this visit only. Switch the mode away from WSL and back to WSL, and the window asks again. After the first message, DSH no longer allows a mode change, so the window does not return in that conversation.
+
+The first `bash`, relative paths, and `grep` / `glob` without a `path` start in the folder you chose. Pass `/mnt/<drive>/...` when the search should cover a Windows directory. The `wsl_*` tools above do not use this window; they keep using the current Windows session directory.
 
 | Tool | What it does |
 |---|---|
 | `bash` | Persistent bash in the distribution. The syntax is bash, not PowerShell |
-| `read` / `write` / `edit` | Linux paths. Relative paths are relative to `$HOME` |
-| `grep` | GNU grep in the distribution. Rows look like `path:line: text`. Omitting `path` searches `$HOME` |
-| `glob` | Lists files matching a glob, oldest first. Omitting `path` lists `$HOME` |
+| `read` / `write` / `edit` | Linux paths. Relative paths are relative to the folder you chose |
+| `grep` | GNU grep in the distribution. Rows look like `path:line: text`. Omitting `path` searches the folder you chose |
+| `glob` | Lists files matching a glob, oldest first. Omitting `path` lists the folder you chose |
 | `wsl_env` | Distribution facts |
 
-`$HOME` is resolved once. Text that a login profile prints is not treated as the path. If the lookup fails, search does not fall back to the Windows session directory.
+The folder list starts at `$HOME` and shows one level of directories. Text that a login profile prints is not treated as a path. If the lookup fails, the Windows session directory is not opened instead. The picker uses an opaque surface, so a skin that makes the app background translucent does not show through it.
 
 ## Configuration
 
@@ -80,7 +84,7 @@ Set these on the plugin row `config` (`cordis.patch.yml`, or a profile patch tha
 | `timeoutMs` | `120000` | Default deadline for `bash` / `wsl_bash`, in milliseconds |
 | `fileTimeoutMs` | `30000` | Deadline for one read, write, or search |
 | `maxFileBytes` | `2097152` | Maximum bytes `read` / `edit` will load |
-| `defaultWorkdir` | `session` for host tools; `home` for WSL mode | `session` translates the Windows session directory to `/mnt/...`. `home` uses the distribution's `$HOME`. An absolute Linux path is also accepted |
+| `defaultWorkdir` | `session` | For the host `wsl_*` tools, `session` is the current Windows session directory. In WSL mode, `session` is the folder you chose. `home` uses the distribution's `$HOME`. An absolute Linux path is also accepted |
 | `dangerGuard` | `true` | Refuses obviously destructive commands unless that call passes `allowDangerous: true` |
 | `backgroundJobs` | `true` | Allows `runInBackground`. Refuses clearly when the host has no job registry |
 | `promptSection` | `true` | Adds the routing note to host sessions |
@@ -96,7 +100,7 @@ The refusal list covers recursive deletes, block-device writes, power control, `
 - Windows only. Both rows disable themselves on any other host.
 - The tools run through `wsl.exe` and are **not** inside DSH's Windows file sandbox. Treat them as able to write anything that WSL user can write, including Windows paths reached through `/mnt/<drive>`. See [docs/SECURITY.md](docs/SECURITY.md).
 - `grep` / `glob` use GNU grep and find. They do not read `.gitignore`. Hidden files, `node_modules`, and VCS metadata are skipped.
-- The folder selected in the desktop UI stays that UI's workspace. WSL-mode tools no longer search it by default. Skill directories and UI file references still use Windows paths.
+- On a new conversation, WSL mode asks which folder inside the distribution should be the workspace. The folder control opens that directory. Skills and file references follow it. Esc closes that visit; leaving WSL mode and choosing it again asks once more. A conversation that has already started cannot change mode.
 - The first call waits for the distribution to start and can take several seconds. `timeoutMs` defaults to 120 seconds.
 - This plugin does not install Node or any other toolchain inside the distribution.
 

package/README.md

@@ -4,17 +4,17 @@
 
 在 Windows 上给 [DSH](https://github.com/deepseek-ai/DeepSeek-Harness) 一个原生的 WSL（Linux）执行面。不额外启动 web 服务，也不在 WSL 里安装 dsh。Windows 会话和 WSL 会话在同一个桌面端里使用。
 
-当前版本 **0.4.6**。需要 **Windows**、一个可用的 WSL 发行版，以及 **DSH `>= 0.2.1-rc.2`**。源码：<https://github.com/TGWgulugu/dsh-wsl-bridge>
+当前版本 **0.4.7**。需要 **Windows**、一个可用的 WSL 发行版，以及 **DSH `>= 0.2.1-rc.2`**。源码：<https://github.com/TGWgulugu/dsh-wsl-bridge>
 
 ## 安装
 
-在普通终端里执行（不要在 DSH 会话的工具沙箱里跑）。`dsh` 不在 PATH 上时，换成 Desktop 自带的 `dsh.cmd` 完整路径。
+插件已发布到 npm：[dsh-wsl-bridge](https://www.npmjs.com/package/dsh-wsl-bridge)。在普通终端里执行下面的命令，DSH 会从 npm 安装这个包。不要在 DSH 会话的工具沙箱里跑。`dsh` 不在 PATH 上时，换成 Desktop 自带的 `dsh.cmd` 完整路径。
 
 ```powershell
 dsh plugin --profile desktop add dsh-wsl-bridge
 ```
 
-尚未发布、或要装当前目录的源码时：
+要装本仓库里的源码，而不是 npm 上的版本时：
 
 ```powershell
 dsh plugin --profile desktop add .
@@ -58,17 +58,21 @@ dsh plugin --profile desktop remove dsh-wsl-bridge
 
 新建会话时选择 **WSL**。这一会话里的 `bash`、`read`、`write`、`edit`、`grep`、`glob` 都在 Linux 里执行，参数是 Linux 路径。persona、skill、goal、plan、compaction、subagent、todo、web、present 仍用 DSH 标准会话的那一套。
 
-**默认工作区是当前发行版的家目录（`$HOME`）。** 第一次 `bash` 从家目录开始；相对路径按家目录解析；`grep` 和 `glob` 不传 `path` 时也搜索家目录。要搜 Windows 目录时，显式传入 `/mnt/<盘符>/...`。
+**工作区由你在当前发行版里选定。** 新建对话并选中 WSL 后，窗口从 `$HOME` 列出该发行版的文件夹。可以进入子文件夹，也可以回到上一级，然后用「使用此文件夹」确认。选中的目录用这台电脑上的 `wslpath -w` 现查，不写死发行版名或用户名。右上角的文件夹按钮打开这个目录，而不是 DSH 自带的 `default-workspace`。
+
+按 Esc 或「取消」只关掉这一次。把模式从 WSL 换走，再选回 WSL，窗口会再出现。对话一旦发出第一条消息，DSH 就不再允许更换模式，这个窗口也不会在那条对话里再次出现。
+
+第一次 `bash`、相对路径，以及不传 `path` 的 `grep` / `glob`，都从你选的目录开始。要搜 Windows 目录时，显式传入 `/mnt/<盘符>/...`。上面的 `wsl_*` 工具不走这个窗口，仍使用当前 Windows 会话目录。
 
 | 工具 | 作用 |
 |---|---|
 | `bash` | 发行版里的持久 bash，语法是 bash，不是 PowerShell |
-| `read` / `write` / `edit` | 读写 Linux 路径。相对路径相对 `$HOME` |
-| `grep` | 发行版内的 GNU grep。结果是 `path:line: text`。不传 `path` 时搜 `$HOME` |
-| `glob` | 按 glob 列出文件，旧文件在前。不传 `path` 时列 `$HOME` |
+| `read` / `write` / `edit` | 读写 Linux 路径。相对路径相对你选的工作区 |
+| `grep` | 发行版内的 GNU grep。结果是 `path:line: text`。不传 `path` 时搜你选的工作区 |
+| `glob` | 按 glob 列出文件，旧文件在前。不传 `path` 时列你选的工作区 |
 | `wsl_env` | 发行版信息 |
 
-家目录只查询一次。登录脚本如果往标准输出打字，不会被当成路径。查询失败时，搜索不会退回 Windows 会话目录。
+目录列表从 `$HOME` 开始，只列出这一层的文件夹。登录脚本如果往标准输出打字，不会被当成路径。查不到目录时，不会改去打开 Windows 会话目录。选择窗口使用不透明底色，不跟随会把背景透出来的皮肤。
 
 ## 配置
 
@@ -80,7 +84,7 @@ dsh plugin --profile desktop remove dsh-wsl-bridge
 | `timeoutMs` | `120000` | `bash` / `wsl_bash` 的默认时限（毫秒） |
 | `fileTimeoutMs` | `30000` | 读、写、搜索的单次时限（毫秒） |
 | `maxFileBytes` | `2097152` | `read` / `edit` 最多读取的字节数 |
-| `defaultWorkdir` | 宿主工具是 `session`；WSL 模式是 `home` | `session` 把 Windows 会话目录译成 `/mnt/...`。`home` 使用当前发行版的 `$HOME`。也可以填绝对 Linux 路径 |
+| `defaultWorkdir` | `session` | 宿主 `wsl_*` 工具的 `session` 是当前 Windows 会话目录。WSL 模式的 `session` 是你选的工作区。`home` 使用当前发行版的 `$HOME`。也可以填绝对 Linux 路径 |
 | `dangerGuard` | `true` | 拒绝明显的破坏性命令，除非该次调用带 `allowDangerous: true` |
 | `backgroundJobs` | `true` | 是否允许 `runInBackground`。宿主没有任务注册表时会明确拒绝 |
 | `promptSection` | `true` | 是否加入宿主会话的路由提示 |
@@ -96,7 +100,7 @@ dsh plugin --profile desktop remove dsh-wsl-bridge
 - 只支持 Windows。其他系统上这两行配置会禁用。
 - 工具通过 `wsl.exe` 执行，**不受** DSH 的 Windows 文件沙箱约束。把它看成：发行版里该用户能写的路径，以及通过 `/mnt/<盘符>` 能碰到的 Windows 路径，都可以写。详见 [docs/SECURITY.md](docs/SECURITY.md)。
 - `grep` / `glob` 使用 GNU grep 和 find，不读 `.gitignore`。隐藏文件、`node_modules` 和版本库元数据会跳过。
-- 桌面端选中的 Windows 文件夹仍然是界面上的工作区。WSL 模式的工具默认不再搜那个目录。技能目录和界面上的文件引用仍按 Windows 路径解析。
+- 新建对话选中 WSL 后，从当前发行版里选工作区。右上角的文件夹按钮打开这个目录。技能和文件引用跟着这个工作区走。Esc 只关闭这一次；换走模式再选回 WSL 会再问一次。已开始的对话不能再改模式。
 - 第一次调用要等发行版冷启动，可能要数秒。`timeoutMs` 默认 120 秒。
 - 本插件不在发行版里安装 Node 或其他工具链。
 

package/client.js

@@ -0,0 +1,299 @@
+window.__ModuleLoader__.load({
+  id: 'dsh-wsl-bridge',
+  factory: (require) => {
+    const DIRS_ROUTE_PATH = '/api/dsh-wsl-bridge/dirs'
+
+    function apply(ctx) {
+      let React
+      try {
+        React = require('react')
+      } catch (error) {
+        ctx.logger?.warn?.('dsh-wsl-bridge: folder picker skipped: ' + messageOf(error))
+        return
+      }
+      const sessions = readService(ctx, 'sessions')
+      const workspaces = readService(ctx, 'workspaces')
+      const ui = readService(ctx, 'uiWorkspace')
+      const slots = readService(ctx, 'slots')
+      if (sessions?.list?.subscribe === undefined || typeof workspaces?.create !== 'function'
+        || typeof ui?.openWorkspace !== 'function' || typeof slots?.inject !== 'function') {
+        ctx.logger?.info?.('dsh-wsl-bridge: folder picker left inactive')
+        return
+      }
+      const store = createPickerStore()
+      const pickerState = new Map()
+      slots.inject('shell.overlay', () => slots.register({
+        name: 'shell.overlay',
+        id: 'dsh-wsl-bridge-folder',
+        order: 40,
+      }, () => React.createElement(FolderPicker, { React, store, workspaces, ui })))
+      const sync = () => {
+        const sessionList = sessions.list.getSnapshot()
+        if (sessionList?.phase !== 'ready') return
+        const sessionId = mainViewSessionId(sessionList.byId)
+        if (sessionId === undefined) return
+        const summary = sessionList.byId?.[sessionId]
+        const preset = presetOf(summary, sessionList.projectionsBySession?.[sessionId])
+        const decision = nextPickerState(pickerState.get(sessionId), preset, summary?.cwd)
+        pickerState.set(sessionId, decision.state)
+        if (decision.open && !store.isOpen()) store.open()
+      }
+      ctx.effect(() => sessions.list.subscribe(sync))
+      sync()
+    }
+
+    function FolderPicker({ React, store, workspaces, ui }) {
+      const snap = React.useSyncExternalStore(store.subscribe, store.getSnapshot)
+      React.useEffect(() => {
+        if (!snap.open) return undefined
+        const onKey = (event) => {
+          if (event.key === 'Escape') store.dismiss()
+        }
+        window.addEventListener('keydown', onKey)
+        return () => window.removeEventListener('keydown', onKey)
+      }, [snap.open, store])
+      if (!snap.open) return null
+      const h = React.createElement
+      const listing = snap.listing
+      return h('div', { style: backdropStyle },
+        h('div', {
+          role: 'dialog',
+          'aria-modal': 'true',
+          'aria-labelledby': 'dsh-wsl-bridge-title',
+          style: panelStyle,
+        },
+        h('h2', { id: 'dsh-wsl-bridge-title', style: titleStyle }, '选择 WSL 工作区'),
+        h('p', { style: hintStyle }, '从当前发行版里选一个文件夹。右上角的文件夹按钮会打开这里，不再打开 default-workspace。'),
+        h('div', { style: pathStyle }, listing?.path ?? '正在读取目录…'),
+        snap.error === '' ? null : h('p', { style: errorStyle }, snap.error),
+        h('div', { style: listStyle },
+          listing?.parent ? h('button', {
+            type: 'button',
+            style: rowStyle,
+            onClick: () => store.load(listing.parent.path),
+          }, '上一级') : null,
+          ...(listing?.entries ?? []).map((entry) => h('button', {
+            key: entry.path,
+            type: 'button',
+            style: rowStyle,
+            onClick: () => store.load(entry.path),
+          }, entry.name + '/')),
+          listing && listing.entries.length === 0
+            ? h('p', { style: hintStyle }, '没有子文件夹，可以直接使用当前目录。')
+            : null,
+        ),
+        h('div', { style: actionStyle },
+          h('button', { type: 'button', style: secondaryStyle, onClick: () => store.dismiss() }, '取消'),
+          h('button', {
+            type: 'button',
+            style: primaryStyle,
+            disabled: listing?.windows === undefined || snap.creating,
+            onClick: () => store.confirm(workspaces, ui),
+          }, snap.creating ? '正在创建…' : '使用此文件夹'),
+        ),
+        ),
+      )
+    }
+
+    function createPickerStore() {
+      let snap = { open: false, listing: null, error: '', creating: false }
+      let loadTicket = 0
+      const listeners = new Set()
+      const publish = (next) => {
+        snap = next
+        for (const listener of listeners) listener()
+      }
+      return {
+        subscribe(listener) {
+          listeners.add(listener)
+          return () => listeners.delete(listener)
+        },
+        getSnapshot() {
+          return snap
+        },
+        isOpen() {
+          return snap.open
+        },
+        open() {
+          publish({ open: true, listing: null, error: '', creating: false })
+          void this.load('')
+        },
+        dismiss() {
+          publish({ open: false, listing: null, error: '', creating: false })
+        },
+        async load(linuxPath) {
+          const ticket = ++loadTicket
+          publish({ ...snap, error: '', creating: false })
+          try {
+            const listing = await readDirectory(linuxPath)
+            if (!snap.open || ticket !== loadTicket) return
+            publish({ open: true, listing, error: '', creating: false })
+          } catch (error) {
+            if (!snap.open || ticket !== loadTicket) return
+            publish({ ...snap, error: '读不到这个目录：' + messageOf(error), creating: false })
+          }
+        },
+        async confirm(workspaces, ui) {
+          const windowsPath = snap.listing?.windows
+          if (typeof windowsPath !== 'string' || snap.creating) return
+          publish({ ...snap, creating: true, error: '' })
+          try {
+            await openChosenWorkspace(workspaces, ui, windowsPath)
+            publish({ open: false, listing: null, error: '', creating: false })
+          } catch (error) {
+            publish({ ...snap, creating: false, error: '没能创建工作区：' + messageOf(error) })
+          }
+        },
+      }
+    }
+
+    async function readDirectory(linuxPath) {
+      const url = linuxPath === undefined || linuxPath === ''
+        ? DIRS_ROUTE_PATH
+        : DIRS_ROUTE_PATH + '?path=' + encodeURIComponent(linuxPath)
+      const response = await fetch(url)
+      const body = await response.json().catch(() => null)
+      if (!response.ok || typeof body?.path !== 'string' || typeof body?.windows !== 'string') {
+        throw new Error(typeof body?.error === 'string' ? body.error : 'HTTP ' + response.status)
+      }
+      return body
+    }
+
+    async function openChosenWorkspace(workspaces, ui, windowsPath) {
+      const created = await workspaces.create({ path: windowsPath })
+      const workspace = created?.workspace ?? created?.value?.workspace ?? created
+      const id = typeof workspace?.workspaceId === 'string' ? workspace.workspaceId : ''
+      if (id === '') throw new Error('WSL workspace was not created')
+      await ui.openWorkspace(id, undefined, { agentPreset: 'wsl' })
+    }
+
+    function shouldOfferFolderPicker(preset, cwd) {
+      return preset === 'wsl' && !isDistributionWorkspacePath(cwd)
+    }
+
+    function nextPickerState(previous, preset, cwd) {
+      if (preset !== 'wsl') return { state: 'other', open: false }
+      if (!shouldOfferFolderPicker(preset, cwd)) return { state: 'wsl', open: false }
+      if (previous === 'shown' || previous === 'wsl') return { state: previous, open: false }
+      return { state: 'shown', open: true }
+    }
+
+    function isDistributionWorkspacePath(value) {
+      return /^\\\\wsl(?:\.localhost|\$)\\/iu.test(normalize(value))
+    }
+
+    function presetOf(summary, projections) {
+      const values = summary?.projectionValues ?? projections?.values
+      const preset = values?.agentPreset
+      return typeof preset === 'string' ? preset : ''
+    }
+
+    function mainViewSessionId(byId) {
+      if (byId === undefined || byId === null) return undefined
+      for (const row of Object.values(byId)) {
+        if (row !== undefined && (row.retainedBy?.mainView ?? 0) > 0) {
+          return typeof row.id === 'string' ? row.id : undefined
+        }
+      }
+      return undefined
+    }
+
+    function normalize(value) {
+      return String(value ?? '').replace(/\//gu, '\\').replace(/\\+$/u, '')
+    }
+
+    function readService(ctx, name) {
+      try {
+        if (ctx?.[name] !== undefined) return ctx[name]
+        return typeof ctx.get === 'function' ? ctx.get(name) : undefined
+      } catch {
+        return undefined
+      }
+    }
+
+    function messageOf(error) {
+      return error instanceof Error ? error.message : String(error)
+    }
+
+    const backdropStyle = {
+      position: 'fixed',
+      inset: 0,
+      zIndex: 40,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      background: 'rgba(0, 0, 0, 0.62)',
+      padding: 24,
+    }
+    const panelStyle = {
+      width: 'min(520px, 100%)',
+      maxHeight: 'min(640px, 100%)',
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 12,
+      padding: 20,
+      borderRadius: 12,
+      backgroundColor: 'Canvas',
+      color: 'CanvasText',
+      border: '1px solid color-mix(in srgb, CanvasText 18%, Canvas)',
+      boxShadow: '0 18px 50px rgba(0, 0, 0, 0.35)',
+      boxSizing: 'border-box',
+    }
+    const titleStyle = { margin: 0, fontSize: 18, fontWeight: 600 }
+    const hintStyle = { margin: 0, fontSize: 13, lineHeight: 1.5, color: 'color-mix(in srgb, CanvasText 78%, Canvas)' }
+    const pathStyle = {
+      fontFamily: 'ui-monospace, monospace',
+      fontSize: 13,
+      padding: '8px 10px',
+      borderRadius: 8,
+      backgroundColor: 'color-mix(in srgb, CanvasText 8%, Canvas)',
+      color: 'CanvasText',
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+      whiteSpace: 'nowrap',
+    }
+    const errorStyle = { margin: 0, fontSize: 13, color: '#b42318' }
+    const listStyle = {
+      display: 'flex',
+      flexDirection: 'column',
+      gap: 4,
+      minHeight: 160,
+      maxHeight: 320,
+      overflow: 'auto',
+    }
+    const rowStyle = {
+      textAlign: 'left',
+      border: '1px solid color-mix(in srgb, CanvasText 16%, Canvas)',
+      backgroundColor: 'color-mix(in srgb, CanvasText 6%, Canvas)',
+      color: 'CanvasText',
+      borderRadius: 8,
+      padding: '8px 10px',
+      cursor: 'pointer',
+      font: 'inherit',
+    }
+    const actionStyle = { display: 'flex', justifyContent: 'flex-end', gap: 8 }
+    const secondaryStyle = {
+      font: 'inherit',
+      padding: '8px 14px',
+      borderRadius: 8,
+      border: '1px solid color-mix(in srgb, CanvasText 22%, Canvas)',
+      backgroundColor: 'Canvas',
+      color: 'CanvasText',
+      cursor: 'pointer',
+    }
+    const primaryStyle = {
+      font: 'inherit',
+      padding: '8px 14px',
+      borderRadius: 8,
+      border: 0,
+      backgroundColor: '#247bbf',
+      color: '#fff',
+      cursor: 'pointer',
+    }
+
+    return {
+      inject: ['slots', 'sessions', 'workspaces', 'uiWorkspace'],
+      apply,
+    }
+  },
+})

package/cordis.patch.yml

@@ -22,7 +22,7 @@
       config:
         id: wsl
         name: WSL
-        description: 'Linux paths inside WSL. The default workspace is that distribution home directory.'
+        description: '在当前 WSL 发行版里使用 Linux 路径。新建对话并选中后，从该发行版的文件夹里指定工作区。'
         order: 2
         plugins:
           - id: persona
@@ -30,11 +30,12 @@
             config:
               prefix: >-
                 You are a coding agent powered by the {{model}} model. Your working
-                directory is the home directory of the current WSL distribution.
-                bash, read, write, edit, grep and glob take Linux paths. grep and
-                glob search that home directory unless you pass another path.
-                The Windows filesystem is reachable as /mnt/<drive>. Use bash
-                syntax for commands, not PowerShell.
+                directory is the folder chosen as this session's workspace inside
+                the current WSL distribution. When asked for the current workspace,
+                name that folder. bash, read, write, edit, grep and glob take Linux
+                paths. grep and glob search that folder unless you pass another
+                path. The Windows filesystem is reachable as /mnt/<drive>. Use
+                bash syntax for commands, not PowerShell.
           - id: agent-instructions
             name: '@deepseek-ai/dsh-agent-instructions'
             config:
@@ -46,7 +47,7 @@
             config:
               distro: ''
               timeoutMs: 120000
-              defaultWorkdir: home
+              defaultWorkdir: session
           - id: tool-jobs
             name: '@deepseek-ai/dsh-tool-jobs'
           - id: tool-schedule

package/docs/ARCHITECTURE.md

@@ -53,9 +53,10 @@ model tool call
   ACLs and extended attributes are not copied from the old inode.
 - **Paths**: Windows drive paths map to `/mnt/<drive>`. Host `wsl_*` tools still
   translate the session directory into the default workdir. A `WSL` session
-  (`defaultWorkdir: home`) reads the distribution's `$HOME` once and uses that
-  path for the initial shell, relative paths, and grep/glob. `wsl_path` prefers
-  the distribution's own `wslpath` and falls back to the host-side mapping.
+  asks for a folder inside the distribution and opens that directory as the
+  workspace (`wslpath -w` of the chosen path). Relative paths and grep/glob
+  follow that workspace. `wsl_path` prefers the distribution's own `wslpath`
+  and falls back to the host-side mapping.
 - **grep/glob** run GNU grep/find inside the distribution (the host search suite
   ships a Windows ripgrep, which cannot see Linux paths). They prune hidden
   entries and `node_modules`/VCS metadata; `.gitignore` is not read (documented).

package/index.js

@@ -29,6 +29,9 @@ import { appendFileSync } from 'node:fs'
 import { resolveConfig } from './src/config.js'
 import { registerPromptSection } from './src/prompt.js'
 import { runSelfCheck } from './src/self-check.js'
+import { registerHomeRoute } from './src/home-route.js'
+import { registerDirRoute } from './src/dir-route.js'
+import { createHomeLookup, ensureWslHomeWorkspace } from './src/session-home.js'
 import { createShellPool } from './src/shell.js'
 import { buildTools } from './src/tools.js'
 
@@ -76,6 +79,18 @@ export function apply(ctx, rawConfig) {
   ctx.on('agent/disposed', ({ agent }) => {
     pool.dispose(agent, 'agent disposed')
   })
+  const homeWindows = createHomeLookup(pool, config)
+  // Routes stay unwired until the desktop web server exists. Reading it
+  // without inject throws, and the page then gets the app shell instead of JSON.
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['webServer'], (inner) => {
+      registerHomeRoute(inner, homeWindows)
+      registerDirRoute(inner, pool, config)
+    })
+  }
+  void ensureWslHomeWorkspace(ctx, { pool, config, homeWindows }).catch((error) => {
+    ctx.logger?.warn?.('dsh-wsl-bridge: WSL home workspace not registered: ' + messageOf(error))
+  })
 
   const tools = buildTools({ pool, config, subprocess, jobs })
   for (const tool of tools) {

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "WSL Bridge",
-    "description": "Native WSL execution for DSH on Windows: persistent Linux bash, Linux-path file and search tools, and a WSL session mode — no extra web server, nothing to install inside the distribution."
+    "description": "Native WSL execution for DSH on Windows: persistent Linux bash, Linux-path file and search tools, and a WSL session mode. A new conversation in WSL mode asks which folder inside the current distribution should be the workspace. No extra web server, nothing to install inside the distribution."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "WSL 桥",
-    "description": "在 Windows 上给 DSH 原生 WSL 执行面：持久 Linux bash、Linux 路径的文件与搜索工具，以及 WSL 会话模式——不额外起 web 服务，WSL 内无需安装任何东西。"
+    "description": "在 Windows 上给 DSH 原生 WSL 执行面：持久 Linux bash、Linux 路径的文件与搜索工具，以及 WSL 会话模式。新建对话选中 WSL 后，从当前发行版的文件夹里指定工作区。不额外起 web 服务，WSL 内无需安装任何东西。"
   }
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "dsh-wsl-bridge",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "type": "module",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
     "./wsl-world": "./wsl-world.js",
+    "./client": "./client.js",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg"
   },
@@ -18,6 +19,14 @@
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-api-workspace-controller",
+        "@deepseek-ai/dsh-client-ui-workspace"
+      ],
+      "platform": "web"
     }
   },
   "peerDependencies": {
@@ -26,6 +35,7 @@
   "files": [
     "index.js",
     "wsl-world.js",
+    "client.js",
     "src/**/*.js",
     "cordis.patch.yml",
     "locale/*.json",
@@ -48,7 +58,7 @@
     "url": "https://github.com/TGWgulugu/dsh-wsl-bridge/issues"
   },
   "homepage": "https://github.com/TGWgulugu/dsh-wsl-bridge#readme",
-  "description": "Native WSL execution for DeepSeek Harness on Windows: persistent Linux bash, Linux-path file and search tools, and a declarative WSL session mode. No extra web server and nothing to install inside the distribution.",
+  "description": "Native WSL execution for DeepSeek Harness on Windows: persistent Linux bash, Linux-path file and search tools, and a WSL session mode that asks which distribution folder to use as the workspace. No extra web server and nothing to install inside the distribution.",
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -60,7 +70,7 @@
     "workspace"
   ],
   "scripts": {
-    "test": "node test/protocol.test.js && node test/shell.test.js && node test/tools.test.js && node test/world-tools.test.js && node test/guard.test.js && node test/jobs.test.js && node test/fsops.test.js",
+    "test": "node test/protocol.test.js && node test/shell.test.js && node test/tools.test.js && node test/world-tools.test.js && node test/session-home.test.js && node test/dir-list.test.js && node test/client-workspace.test.js && node test/guard.test.js && node test/jobs.test.js && node test/fsops.test.js",
     "test:integration": "node test/integration.test.js"
   }
 }

package/src/client-workspace.js

@@ -0,0 +1,111 @@
+/**
+ * Decide when the WSL folder picker should open, and open the folder the
+ * user picked. The browser entry cannot import this file.
+ *
+ * @module dsh-wsl-bridge/client-workspace
+ */
+
+/**
+ * A workspace already lives inside a distribution when its Windows path is
+ * `\\wsl.localhost\...` or `\\wsl$\...`. Drive letters are Windows folders.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isDistributionWorkspacePath(value) {
+  return /^\\\\wsl(?:\.localhost|\$)\\/iu.test(normalize(value))
+}
+
+/**
+ * Offer the picker when this session is in WSL mode and its folder is still
+ * a Windows directory, including DSH's first-use `default-workspace`.
+ *
+ * @param {unknown} preset
+ * @param {unknown} cwd
+ * @returns {boolean}
+ */
+export function shouldOfferFolderPicker(preset, cwd) {
+  return preset === 'wsl' && !isDistributionWorkspacePath(cwd)
+}
+
+/**
+ * Decide whether this snapshot should open the folder picker.
+ *
+ * `shown` means this visit to WSL mode already opened the window. Leaving
+ * WSL mode records `other`, so choosing WSL again asks one more time.
+ * Esc does not lock the session permanently.
+ *
+ * @param {string|undefined} previous
+ * @param {string} preset
+ * @param {unknown} cwd
+ * @returns {{state: string, open: boolean}}
+ */
+export function nextPickerState(previous, preset, cwd) {
+  if (preset !== 'wsl') return { state: 'other', open: false }
+  if (!shouldOfferFolderPicker(preset, cwd)) return { state: 'wsl', open: false }
+  if (previous === 'shown' || previous === 'wsl') return { state: previous, open: false }
+  return { state: 'shown', open: true }
+}
+
+/**
+ * @param {object|undefined} summary
+ * @param {object|undefined} projections
+ * @returns {string}
+ */
+export function presetOf(summary, projections) {
+  const values = summary?.projectionValues ?? projections?.values
+  const preset = values?.agentPreset
+  return typeof preset === 'string' ? preset : ''
+}
+
+/**
+ * @param {Record<string, {id?: string, retainedBy?: {mainView?: number}}>|undefined} byId
+ * @returns {string|undefined}
+ */
+export function mainViewSessionId(byId) {
+  if (byId === undefined || byId === null) return undefined
+  for (const row of Object.values(byId)) {
+    if (row !== undefined && (row.retainedBy?.mainView ?? 0) > 0) {
+      return typeof row.id === 'string' ? row.id : undefined
+    }
+  }
+  return undefined
+}
+
+/**
+ * @param {object|undefined} created
+ * @returns {string|undefined}
+ */
+export function workspaceIdFromCreate(created) {
+  const workspace = created?.workspace ?? created?.value?.workspace ?? created
+  return typeof workspace?.workspaceId === 'string' ? workspace.workspaceId : undefined
+}
+
+/**
+ * Register the picked Windows path and open it as a WSL session.
+ * The path is whatever `wslpath -w` printed for the folder the user chose.
+ *
+ * @param {object} workspaces
+ * @param {object} ui
+ * @param {string} windowsPath
+ * @returns {Promise<string>}
+ */
+export async function openChosenWorkspace(workspaces, ui, windowsPath) {
+  if (typeof windowsPath !== 'string' || windowsPath === '') throw new Error('WSL folder is missing')
+  if (typeof workspaces?.create !== 'function' || typeof ui?.openWorkspace !== 'function') {
+    throw new Error('workspace services are unavailable')
+  }
+  const created = await workspaces.create({ path: windowsPath })
+  const id = workspaceIdFromCreate(created)
+  if (id === undefined) throw new Error('WSL workspace was not created')
+  await ui.openWorkspace(id, undefined, { agentPreset: 'wsl' })
+  return id
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function normalize(value) {
+  return String(value ?? '').replace(/\//gu, '\\').replace(/\\+$/u, '')
+}

package/src/dir-list.js

@@ -0,0 +1,120 @@
+/**
+ * List one directory inside the current WSL distribution.
+ * The path is passed as base64 so a name cannot change the command.
+ *
+ * @module dsh-wsl-bridge/dir-list
+ */
+import { isWindowsPath } from './paths.js'
+
+const MAX_ENTRIES = 400
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isListedLinuxPath(value) {
+  return typeof value === 'string'
+    && value.startsWith('/')
+    && !value.includes('\0')
+    && !/[\r\n]/u.test(value)
+}
+
+/**
+ * @param {string} [linuxPath] absolute Linux directory, or empty to start at `$HOME`
+ * @returns {string}
+ */
+export function directoryListCommand(linuxPath) {
+  const assignment = linuxPath === undefined || linuxPath === null || linuxPath === ''
+    ? 'dir=$HOME'
+    : 'dir=$(printf %s ' + quoteBase64(linuxPath) + ' | base64 -d)'
+  return [
+    assignment,
+    'case $dir in /*) ;; *) exit 2 ;; esac',
+    'dir=${dir%/}',
+    '[ -n "$dir" ] || dir=/',
+    '[ -d "$dir" ] || exit 3',
+    'win=$(wslpath -w "$dir") || exit 4',
+    "printf '\\n__WSL_CWD__%s\\n' \"$(printf %s \"$dir\" | base64 | tr -d '\\n')\"",
+    "printf '__WSL_CWDWIN__%s\\n' \"$(printf %s \"$win\" | base64 | tr -d '\\n')\"",
+    'parent=$(dirname -- "$dir")',
+    'if [ "$parent" != "$dir" ]; then',
+    '  pwin=$(wslpath -w "$parent") || exit 4',
+    "  printf '__WSL_PARENT__%s\\n' \"$(printf %s \"$parent\" | base64 | tr -d '\\n')\"",
+    "  printf '__WSL_PARENTWIN__%s\\n' \"$(printf %s \"$pwin\" | base64 | tr -d '\\n')\"",
+    'fi',
+    'find "$dir" -mindepth 1 -maxdepth 1 -type d -printf \'%f\\n\' 2>/dev/null | sort | while IFS= read -r name; do',
+    '  [ -n "$name" ] || continue',
+    "  printf '__WSL_NAME__%s\\n' \"$(printf %s \"$name\" | base64 | tr -d '\\n')\"",
+    'done',
+  ].join('\n')
+}
+
+/**
+ * @param {string} stdout
+ * @returns {{path: string, windows: string, parent: {path: string, windows: string}|null, entries: {name: string, path: string, windows: string}[]}|null}
+ */
+export function parseDirectoryListing(stdout) {
+  const path = decodeMarker(stdout, 'WSL_CWD')
+  const windows = normalizeWindows(decodeMarker(stdout, 'WSL_CWDWIN'))
+  if (!path.startsWith('/') || !isWindowsPath(windows)) return null
+  const parentPath = decodeMarker(stdout, 'WSL_PARENT')
+  const parentWindows = normalizeWindows(decodeMarker(stdout, 'WSL_PARENTWIN'))
+  const parent = parentPath.startsWith('/') && isWindowsPath(parentWindows)
+    ? { path: parentPath, windows: parentWindows }
+    : null
+  /** @type {{name: string, path: string, windows: string}[]} */
+  const entries = []
+  const linuxRoot = path.replace(/\/+$/u, '') || '/'
+  const windowsRoot = windows.replace(/\\+$/u, '')
+  for (const match of String(stdout ?? '').matchAll(/__WSL_NAME__([^\r\n]*)/gu)) {
+    if (entries.length >= MAX_ENTRIES) break
+    const name = decodeBase64(match[1].trim())
+    if (name === '' || name === '.' || name === '..' || name.includes('/') || name.includes('\\') || name.includes('\0')) continue
+    const childPath = (linuxRoot === '/' ? '' : linuxRoot) + '/' + name
+    const windowsPath = windowsRoot + '\\' + name
+    if (!isWindowsPath(windowsPath)) continue
+    entries.push({ name, path: childPath, windows: windowsPath })
+  }
+  entries.sort((left, right) => left.name.localeCompare(right.name))
+  return { path, windows, parent, entries }
+}
+
+/**
+ * @param {string} linuxPath
+ * @returns {string}
+ */
+function quoteBase64(linuxPath) {
+  if (!isListedLinuxPath(linuxPath)) throw new Error('path rejected')
+  const encoded = Buffer.from(linuxPath, 'utf8').toString('base64')
+  if (!/^[A-Za-z0-9+/=]+$/u.test(encoded)) throw new Error('path rejected')
+  return "'" + encoded + "'"
+}
+
+/**
+ * @param {string} stdout
+ * @param {string} name
+ * @returns {string}
+ */
+function decodeMarker(stdout, name) {
+  const matches = [...String(stdout ?? '').matchAll(new RegExp('__' + name + '__([^\\r\\n]*)', 'gu'))]
+  if (matches.length === 0) return ''
+  return decodeBase64(matches[matches.length - 1][1].trim())
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function decodeBase64(value) {
+  if (value === '' || !/^[A-Za-z0-9+/=]+$/u.test(value)) return ''
+  const text = Buffer.from(value, 'base64').toString('utf8')
+  return text.includes('\0') ? '' : text
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeWindows(value) {
+  return String(value ?? '').replace(/\//gu, '\\')
+}

package/src/dir-route.js

@@ -0,0 +1,104 @@
+/**
+ * List one WSL directory for the folder picker.
+ * Answers only on loopback. An omitted path starts at `$HOME`.
+ *
+ * @module dsh-wsl-bridge/dir-route
+ */
+import { directoryListCommand, isListedLinuxPath, parseDirectoryListing } from './dir-list.js'
+import { isLoopback } from './home-route.js'
+
+export const DIRS_ROUTE_PATH = '/api/dsh-wsl-bridge/dirs'
+
+/**
+ * @param {object} ctx
+ * @param {object} pool
+ * @param {object} config
+ */
+export function registerDirRoute(ctx, pool, config) {
+  const webServer = readService(ctx, 'webServer')
+  if (webServer === undefined || typeof webServer.register !== 'function') return
+  ctx.effect(() => webServer.register(dirRoute(pool, config)), 'dsh-wsl-bridge: directory route')
+}
+
+/**
+ * @param {object} pool
+ * @param {object} config
+ * @returns {{kind: string, path: string, handler: Function}}
+ */
+export function dirRoute(pool, config) {
+  return {
+    kind: 'prefix',
+    path: DIRS_ROUTE_PATH,
+    async handler(req, res) {
+      try {
+        if (!isLoopback(req)) {
+          writeJson(res, 403, { error: 'forbidden' })
+          return
+        }
+        if (req?.method !== 'GET') {
+          writeJson(res, 405, { error: 'method-not-allowed' })
+          return
+        }
+        const url = new URL(req?.url ?? '/', 'http://127.0.0.1')
+        if (url.pathname !== DIRS_ROUTE_PATH) {
+          writeJson(res, 404, { error: 'not-found' })
+          return
+        }
+        const requested = url.searchParams.get('path') ?? ''
+        if (requested !== '' && !isListedLinuxPath(requested)) {
+          writeJson(res, 400, { error: 'path rejected' })
+          return
+        }
+        const result = await pool.runOnce({
+          command: directoryListCommand(requested),
+          timeoutMs: config?.fileTimeoutMs,
+        })
+        const listing = result?.exitCode === 0 && result?.timedOut !== true && result?.aborted !== true
+          ? parseDirectoryListing(result.stdout)
+          : null
+        if (listing === null) {
+          const detail = String(result?.stderr ?? '').trim()
+          writeJson(res, 503, { error: detail === '' ? 'could not list the WSL directory' : detail })
+          return
+        }
+        writeJson(res, 200, listing)
+      } catch (error) {
+        if (res.headersSent) return
+        writeJson(res, 503, { error: messageOf(error) })
+      }
+    },
+  }
+}
+
+/**
+ * @param {object} res
+ * @param {number} status
+ * @param {object} body
+ */
+function writeJson(res, status, body) {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(payload),
+  })
+  res.end(payload)
+}
+
+/**
+ * @param {object} ctx
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+function readService(ctx, name) {
+  try {
+    return typeof ctx.get === 'function' ? ctx.get(name) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** @param {unknown} error @returns {string} */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/home-route.js

@@ -0,0 +1,86 @@
+/**
+ * Tell the desktop page which directory `wslpath -w "$HOME"` returned.
+ * The path is computed on the host that is running the plugin. The route
+ * answers only on loopback.
+ *
+ * @module dsh-wsl-bridge/home-route
+ */
+
+export const HOME_ROUTE_PATH = '/api/dsh-wsl-bridge/home'
+
+/**
+ * @param {object} ctx
+ * @param {() => Promise<string>} homeWindows
+ */
+export function registerHomeRoute(ctx, homeWindows) {
+  const webServer = readService(ctx, 'webServer')
+  if (webServer === undefined || typeof webServer.register !== 'function') return
+  ctx.effect(() => webServer.register(homeRoute(homeWindows)), 'dsh-wsl-bridge: home route')
+}
+
+/**
+ * @param {() => Promise<string>} homeWindows
+ * @returns {{kind: string, path: string, handler: Function}}
+ */
+export function homeRoute(homeWindows) {
+  return {
+    kind: 'exact',
+    path: HOME_ROUTE_PATH,
+    handler(req, res) {
+      if (!isLoopback(req)) {
+        writeJson(res, 403, { error: 'forbidden' })
+        return
+      }
+      if (req?.method !== 'GET') {
+        writeJson(res, 405, { error: 'method-not-allowed' })
+        return
+      }
+      Promise.resolve(homeWindows()).then(
+        (path) => writeJson(res, 200, { path }),
+        (error) => writeJson(res, 503, { error: messageOf(error) }),
+      )
+    },
+  }
+}
+
+/**
+ * @param {object|undefined} req
+ * @returns {boolean}
+ */
+export function isLoopback(req) {
+  const address = String(req?.socket?.remoteAddress ?? '')
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1'
+}
+
+/**
+ * @param {object} res
+ * @param {number} status
+ * @param {object} body
+ */
+function writeJson(res, status, body) {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(payload),
+  })
+  res.end(payload)
+}
+
+/**
+ * @param {object} ctx
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+function readService(ctx, name) {
+  try {
+    return typeof ctx.get === 'function' ? ctx.get(name) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** @param {unknown} error @returns {string} */
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/session-home.js

@@ -0,0 +1,107 @@
+/**
+ * Resolve this computer's WSL home (`wslpath -w "$HOME"`) and register it.
+ * The folder the session actually uses is chosen in the desktop picker.
+ *
+ * @module dsh-wsl-bridge/session-home
+ */
+import { isWindowsPath } from './paths.js'
+
+/** One-shot probe. Login noise may precede the markers; the last one wins. */
+export const HOME_PROBE_COMMAND = "printf '\\n__WSL_HOME__%s\\n__WSL_WINHOME__%s\\n' \"$HOME\" \"$(wslpath -w \"$HOME\")\""
+
+/**
+ * @param {string} stdout
+ * @returns {{linux: string, windows: string}|null}
+ */
+export function parseHomeProbe(stdout) {
+  const linux = lastMarker(stdout, 'WSL_HOME')
+  const windows = lastMarker(stdout, 'WSL_WINHOME').replace(/\//gu, '\\')
+  if (!linux.startsWith('/') || linux.includes('\0') || !isWindowsPath(windows)) return null
+  return { linux, windows }
+}
+
+/**
+ * @param {unknown} left
+ * @param {unknown} right
+ * @returns {boolean}
+ */
+export function sameWindowsDirectory(left, right) {
+  const norm = (value) => String(value ?? '').replace(/\//gu, '\\').replace(/\\+$/u, '').toLowerCase()
+  return norm(left) !== '' && norm(left) === norm(right)
+}
+
+/**
+ * Read `$HOME` through `wslpath -w` once and reuse that Windows path.
+ * Nothing here names a distribution or a user.
+ *
+ * @param {object} pool
+ * @param {object} config
+ * @returns {() => Promise<string>}
+ */
+export function createHomeLookup(pool, config) {
+  /** @type {Promise<string>|undefined} */
+  let pending
+  return function homeWindows() {
+    pending ??= readHomeWindows(pool, config).catch((error) => {
+      pending = undefined
+      throw error
+    })
+    return pending
+  }
+}
+
+/**
+ * Register the probed home as a workspace. An existing registration is reused.
+ *
+ * @param {object} ctx
+ * @param {{pool: object, config: object, homeWindows?: () => Promise<string>}} options
+ */
+export async function ensureWslHomeWorkspace(ctx, { pool, config, homeWindows }) {
+  const registry = readService(ctx, 'workspaceRegistry')
+  if (registry === undefined || typeof registry.create !== 'function') return
+  const lookup = homeWindows ?? createHomeLookup(pool, config)
+  await registry.create(await lookup())
+}
+
+/**
+ * @param {object} pool
+ * @param {object} config
+ * @returns {Promise<string>}
+ */
+async function readHomeWindows(pool, config) {
+  const result = await pool.runOnce({
+    command: HOME_PROBE_COMMAND,
+    timeoutMs: config.fileTimeoutMs,
+  })
+  const parsed = result?.exitCode === 0 && result?.timedOut !== true && result?.aborted !== true
+    ? parseHomeProbe(result.stdout)
+    : null
+  if (parsed === null) {
+    const detail = String(result?.stderr ?? '').trim()
+    throw new Error('could not resolve the WSL home directory' + (detail === '' ? '' : ': ' + detail))
+  }
+  return parsed.windows
+}
+
+/**
+ * @param {object} ctx
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+function readService(ctx, name) {
+  try {
+    return typeof ctx.get === 'function' ? ctx.get(name) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * @param {string} text
+ * @param {string} name
+ * @returns {string}
+ */
+function lastMarker(text, name) {
+  const matches = [...String(text ?? '').matchAll(new RegExp('__' + name + '__([^\\r\\n]*)', 'gu'))]
+  return matches.length === 0 ? '' : matches[matches.length - 1][1].trim()
+}