dsh-multi-folder 0.3.2 → 0.3.3

package/README.md

@@ -50,7 +50,8 @@ A Multi-folder button appears in the session header, and a second entry appears
 
 | Action | Behavior |
 | ------ | -------- |
-| Add directory | Opens the plugin's own directory browser (path field, one level of child directories, optional new folder) |
+| Add directory | Uses the host's native picker, then its OS dialog on failure; a `browse` capability opens the client browser directly (path field, one level of child directories, optional new folder) |
+| Open in file manager | Opens the host's file manager (Explorer / Finder) at a configured directory |
 | Remove / refresh | Applies immediately |
 | Switch session | The panel auto-switches to that session's directories |
 | Reopen panel | Uses the per-session cache — no redundant command rows |
@@ -98,8 +99,8 @@ When a shell run ends in such a denial and references a configured secondary dir
 - **Prompt injection** — one ordered `systemPrompt` section with a text provider evaluated per assembly, rendering only for sessions whose workspace has configured directories.
 - **Notifications** — a pending notice armed by the command handler (only on actual change) is consumed at the next boundary by either the `agent/pre-step` waterfall (prepend into the entering message batch) or the `tools/post-execute` waterfall (attach as `additionalContexts`), whichever fires first — the framework's native plugin-sourced `notice` context.
 - **Configuration & security boundary** — per-workspace config lives in a host-owned store outside every agent sandbox root (`<DSH_HOME>/storages/multi-folder/<workspace-key>.json`). Direct `write`/`edit` attempts against the config file are rejected with an explicit message — **the agent can never self-grant directories; configuration is user-managed by design**. See [SECURITY.md](SECURITY.md).
-- **Sessionless remote API** — a `multiFolder` namespace registered through `ctx.typert.register` (hand-written `src-json` descriptors) plus a plain-object service provided as `multiFolder`. Its `list`/`add`/`remove`/`set` methods are keyed by workspace **path** and share one validated core with the `/multi-folder` command, so the creation page can configure directories before any session exists. `browse`/`makeDir` ride the same namespace: they serve the plugin's own directory browser and never touch the configuration store.
-- **Owned directory browser** — "Add directory" is drawn by this plugin and served by `browse`/`makeDir`, so it behaves identically in every deployment: the host's native chooser composition, the browse composition (LAN or remote clients, desktop shells) and shells that compose no picker at all. Listing rides the host `fs` seam (`fs.resolve` + `fs.listDir`).
+- **Sessionless remote API** — a `multiFolder` namespace registered through `ctx.typert.register` (hand-written `src-json` descriptors) plus a plain-object service provided as `multiFolder`. Its `list`/`add`/`remove`/`set` methods are keyed by workspace **path** and share one validated core with the `/multi-folder` command, so the creation page can configure directories before any session exists. `browse`/`makeDir` serve the plugin's directory browser; `pick`/`reveal` select or open a host directory.
+- **Directory picking** — `multiFolder/pick` uses the host's `native` picker, then the OS dialog if it fails. A `browse` capability opens the client browser directly. Closing the panel cancels the request; cancelling a dialog adds nothing. The Windows helper is `lib/native-picker.ps1`.
 - **`@` discovery** — a second reader of that same `fs` seam: `multiFolder/listFiles` indexes the configured directories (breadth-first, canonical-path deduplicated so a junction cannot re-enter the walk, generated/vendor basenames excluded, capped and cached per workspace with a short TTL) and the client half registers a companion `@` source over it. The shipped single-root provider is not modified, and the shipped files/sessions group is not disturbed: the trigger registry keys sources by `(trigger, name)` and renders one group each.
 - **Client** — a hand-maintained factory bundle (`window.__ModuleLoader__.load`), no build toolchain required. The panel drives the host through two channels: the Remote BFF (`ctx.remote.commands.execute`) for sessions, and the shared `/api` RPC channel (`ctx.connection.rpc.call`) for the sessionless endpoints.
 
@@ -108,8 +109,9 @@ When a shell run ends in such a denial and references a configured secondary dir
 | Path | Purpose |
 | ---- | ------- |
 | `cordis.patch.yml` | Profile patch layer inserting the `dsh-multi-folder` row |
-| `lib/index.js` | Host plugin: config store, tool-pipeline interception, prompt injection, dual-channel notifications, `/multi-folder` command, sessionless `multiFolder/*` remote API (configuration, the owned browser's `browse`/`makeDir`, and `listFiles` for the `@` menu) |
-| `lib/client.js` | Client plugin (factory bundle): session-header button + overlay panel + session-creation page entry (input-dock chip / upstream hero chip / fixed fallback launcher) + the owned directory browser behind "Add directory" + the companion `@` source |
+| `lib/index.js` | Host plugin: configuration, tool interception, remote API, directory picker and file manager |
+| `lib/client.js` | Client panel, directory browser and companion `@` source |
+| `lib/native-picker.ps1` | Windows folder-dialog helper |
 | `test/` | Runtime-free behavior tests (see Development) |
 | `docs/` | Design and analysis documents |
 

package/README.zh.md

@@ -50,7 +50,8 @@ dsh plugin --profile web add dsh-multi-folder
 
 | 操作 | 行为 |
 | ---- | ---- |
-| 添加目录 | 打开插件自带的目录浏览器（路径输入框 + 一级子目录列表 + 可新建文件夹） |
+| 添加目录 | `native` 使用系统文件夹对话框，失败后尝试宿主对话框；`browse` 直接打开插件自带浏览器（路径输入框 + 一级子目录列表 + 可新建文件夹） |
+| 在文件管理器中打开 | 在宿主机器的文件管理器（资源管理器 / Finder）中打开某个已配置目录 |
 | 移除 / 刷新 | 立即生效 |
 | 切换会话 | 面板自动切换为该会话的副工作目录 |
 | 重新打开面板 | 使用会话级缓存，不产生冗余命令行 |
@@ -98,8 +99,8 @@ Agent 无需任何额外操作：`read` / `glob` / `grep` 随处可用；`write`
 - **提示词注入**——一个有序 `systemPrompt` 段落，text provider 每次组装按会话求值，仅为配置了副目录的会话渲染。
 - **通知**——命令处理器仅在目录集合实际变化时置位 pending notice；`agent/pre-step`（前置注入进入批次）与 `tools/post-execute`（附加为 `additionalContexts`）两个通道中先触发者消费——均使用框架原生的插件来源 `notice` 上下文。
 - **配置与安全边界**——per-workspace 配置存储于 Agent 沙箱之外的宿主自有目录（`<DSH_HOME>/storages/multi-folder/<workspace-key>.json`）。对配置文件的任何直接 `write`/`edit` 都会收到显式拒绝——**Agent 永远无法自我授予目录，配置权仅属于用户**。详见 [SECURITY.md](SECURITY.md)。
-- **无会话远程 API**——经 `ctx.typert.register` 注册 `multiFolder` 命名空间（手写 `src-json` 描述符），并以普通对象服务 `multiFolder` 提供；`list`/`add`/`remove`/`set` 以工作区**路径**为键，与 `/multi-folder` 命令共享同一套校验核心，因此会话尚未建立时创建页也能直接配置。`browse`/`makeDir` 属于同一命名空间：它们只服务插件自带的目录浏览器，不触碰配置存储。
-- **自带目录浏览器**——「添加目录」由插件自己绘制、经 `browse`/`makeDir` 提供服务，因此在任何部署下行为一致：宿主使用原生选择器的组合、使用 browse 后端的组合（局域网/远程客户端、桌面壳），以及完全没有选择器的壳。列目录走宿主 `fs` seam（`fs.resolve` + `fs.listDir`）。
+- **无会话远程 API**——经 `ctx.typert.register` 注册 `multiFolder` 命名空间（手写 `src-json` 描述符），并以普通对象服务 `multiFolder` 提供；`list`/`add`/`remove`/`set` 以工作区**路径**为键，与 `/multi-folder` 命令共享同一套校验核心，因此会话尚未建立时创建页也能直接配置。`browse`/`makeDir` 服务于自带浏览器；`pick`/`reveal` 负责选择或打开宿主目录。
+- **目录选择**——`multiFolder/pick` 先调用宿主的 `native` 选择器，失败后尝试系统对话框；`browse` 能力直接打开客户端浏览器。关闭面板会取消请求；取消系统对话框不会添加目录。Windows 助手为 `lib/native-picker.ps1`。
 - **`@` 发现**——同一 `fs` seam 的第二种用法：`multiFolder/listFiles` 为已配置目录建立索引（广度优先、按规范化路径去重以免 junction 绕回、排除生成物/依赖目录名、按工作区限量并短 TTL 缓存），客户端再据此注册一个并列的 `@` source。自带 provider 不做任何修改，自带分组也不受影响：触发器注册表以 `(trigger, name)` 为键，每个 source 各渲染一个分组。
 - **客户端**——手写维护的 factory bundle（`window.__ModuleLoader__.load`），无需构建工具链；面板经两条通道驱动宿主：会话内走 Remote BFF（`ctx.remote.commands.execute`），无会话端点走共享 `/api` RPC 通道（`ctx.connection.rpc.call`）。
 
@@ -108,8 +109,9 @@ Agent 无需任何额外操作：`read` / `glob` / `grep` 随处可用；`write`
 | 路径 | 作用 |
 | ---- | ---- |
 | `cordis.patch.yml` | profile patch 层，插入 `dsh-multi-folder` 行 |
-| `lib/index.js` | 宿主插件：配置存储、工具流水线拦截、提示词注入、双通道通知、`/multi-folder` 命令、无会话 `multiFolder/*` 远程 API（配置端点 + 自带浏览器用的 `browse`/`makeDir` + `@` 菜单用的 `listFiles`） |
-| `lib/client.js` | 客户端插件（factory bundle）：会话头部按钮 + 覆盖层面板 + 会话创建页入口（输入框上方的 dock 胶囊 / 上游 hero chip / 右下角兜底浮动按钮）+「添加目录」背后的自带目录浏览器 + 并列的 `@` source |
+| `lib/index.js` | 宿主插件：配置、工具拦截、远程 API、目录选择器和文件管理器 |
+| `lib/client.js` | 客户端面板、自带浏览器和并列 `@` 来源 |
+| `lib/native-picker.ps1` | Windows 文件夹选择器助手 |
 | `test/` | 免 DSH 运行时的行为测试（见开发） |
 | `docs/` | 设计与分析文档 |
 

package/SECURITY.md

@@ -32,6 +32,27 @@ granted the session. The design enforces four boundaries:
    bypasses confinement (as it already does for the primary workspace, by the user's
    explicit choice).
 
+### Host-side UI actions (`pick` / `reveal`)
+
+Two sessionless endpoints ask the **host machine** to show UI instead of reading or
+writing a path:
+
+- `multiFolder/pick` asks the host's composed directory picker first, and only a
+  `native` composition (a loopback, attended, non-SSH host — the framework's own
+  `directory-picker-auto` decision) may fall back to this plugin's own OS dialog:
+  `lib/native-picker.ps1` on Windows, `osascript` on macOS. A `browse` composition
+  never reaches a dialog — the client is sent to the browser this plugin draws.
+- `multiFolder/reveal` opens one **existing directory** in the host file manager
+  (`explorer.exe` / `open` / `xdg-open`). It refuses anything that is not an existing
+  directory, so a stale entry cannot launch a file.
+
+Both ride the same trusted browser→host RPC channel as every other `multiFolder/*`
+endpoint (the `connection` Host/Origin fence plus browser authentication) and are
+never exposed as agent tools. They act on the host by design — the host owns the
+filesystem the session is configured against — which is exactly why a remote client
+must never be routed to them: the UI would appear on a display nobody clicked from.
+The `native`-only gate above is what enforces that.
+
 ### What is deliberately out of scope
 
 - In a `danger-full-access` session the agent can already touch the whole filesystem;
@@ -39,22 +60,3 @@ granted the session. The design enforces four boundaries:
 - The agent can *read* the configuration file (reads are not policy-fenced in the DSH
   filesystem backend). Reading reveals nothing the system prompt does not already list
   for that session.
-
-## Reporting a vulnerability
-
-If you believe you have found a security issue in this plugin, please report it
-privately by opening a GitHub Security Advisory on the repository instead of a public
-issue. Please include:
-
-- the affected version,
-- a minimal reproduction,
-- the expected vs. observed behavior.
-
-We will acknowledge the report within 7 days and aim to publish a fix (or a
-documented mitigation) before public disclosure.
-
-## Supported versions
-
-| Version | Supported |
-| ------- | --------- |
-| 0.1.x   | ✅        |

package/docs/design.md

@@ -140,7 +140,7 @@ opens its own **sessionless** endpoints on the shared `/api` RPC channel:
   `ctx.inject(['typert'], (t) => t.typert.register(REMOTE_CONTRIBUTION))` —
   the sanctioned manual path documented by `dsh-typert-loader` ("Manual
   `ctx.typert.register()` remains available for contributions that do not use
-  a `./typert` artifact"). All six descriptors use `src-json` codecs (no zod
+  a `./typert` artifact"). All nine descriptors use `src-json` codecs (no zod
   schemas needed) with `invocation: { kind: 'direct' }`:
 
   | Endpoint | Parameters (wire) | Result |
@@ -152,6 +152,8 @@ opens its own **sessionless** endpoints on the shared `/api` RPC channel:
   | `multiFolder/browse` | `path` | `{ path, parent, home, entries, truncated }` |
   | `multiFolder/makeDir` | `parent`, `name` | `{ path, parent }` |
   | `multiFolder/listFiles` | `workspace`, `query` | `{ workspace, dirs, candidates, truncated }` |
+  | `multiFolder/pick` | `cwd` (plus transport cancellation) | `{ path, via }` |
+  | `multiFolder/reveal` | `path` | `{ path, via }` |
 
   The four configuration endpoints are keyed by workspace; `browse`/`makeDir`
   serve the plugin's own directory browser and are keyed by path instead;
@@ -330,25 +332,26 @@ window.__ModuleLoader__.load({
     'multiFolder/<op>', { args })` against the sessionless remote endpoints.
     The panel runs in either mode according to how it was opened; mutations
     and refreshes route per mode, and both modes share the same row/error UI.
-- Owned directory browser ("Add directory"): the plugin draws the picking
-  interaction itself and serves it from `multiFolder/browse` +
-  `multiFolder/makeDir` over the shared RPC channel, instead of asking the host
-  for a picker. One interaction therefore covers every deployment, which no
-  host picker does: `uiWorkspace.pickDirectory()` is native-only (the host
-  answers `directory-picker/unavailable` when it composed the browse backend —
-  a LAN bind, a remote client, a desktop shell), its
-  `listDirectory`/`createDirectory` twins are refused under the native
-  composition, and the shipped in-app browser is reachable only by the shell's
-  own workspace surfaces (its `directoryFlow` holes are declared and driven by
-  ui-workspace, not by plugins). Listing rides the **`fs` seam**
-  (`fs.resolve` + `fs.listDir`), which every composition provides; only
-  directories are returned, hidden entries are flagged, the level is capped at
-  1000 with a `truncated` flag, and paths must be fully qualified. Creation
-  mirrors the shipped browse backend (`dsh-host-directory-picker-browse`) by
-  calling Node's `mkdir` on a validated single segment, because the `fs` seam
-  exposes no creation primitive. Neither endpoint touches the configuration
-  store: choosing a level still commits through the mode's own channel
-  (`/multi-folder add` in a session, `multiFolder/add` on the creation page).
+- Directory picking: `multiFolder/pick` calls the host's `native` picker with
+  the RPC abort signal, then tries a host OS dialog if that picker fails.
+  A `browse` capability returns `unavailable` immediately, so remote clients
+  open the plugin's browser instead of a dialog on the host. A completed dialog
+  returns a path or `null` on cancellation; closing the panel aborts the request.
+- The owned browser's listing rides the **`fs` seam** (`fs.resolve` +
+  `fs.listDir`), which every composition provides; only directories are
+  returned, hidden entries are flagged, the level is capped at 1000 with a
+  `truncated` flag, and paths must be fully qualified. Creation mirrors the
+  shipped browse backend (`dsh-host-directory-picker-browse`) by calling Node's
+  `mkdir` on a validated single segment, because the `fs` seam exposes no
+  creation primitive. Neither endpoint touches the configuration store: choosing
+  a level still commits through the mode's own channel (`/multi-folder add` in a
+  session, `multiFolder/add` on the creation page).
+- On Windows, `lib/native-picker.ps1` uses `IFileOpenDialog` on an STA thread,
+  sets per-monitor DPI awareness (a build without that thread API still shows the
+  dialog), assists it to the foreground for a few seconds, and closes an
+  unanswered dialog on a deadline. It exits 0 for a selection or dismissal and
+  nonzero when `Show()` fails. `multiFolder/reveal` checks `fs.stat` before
+  opening an existing directory with the host file manager.
 - `@` source: registered through `ctx.inject(['inputTriggers'], …)` (see the
   `@` discovery section for the full decision table). It resolves the addressed
   session's workspace from the `sessions` snapshot (`byId[sessionId].cwd`), calls

package/lib/client.js

@@ -27,17 +27,14 @@
  * (`ctx.connection.rpc.call('/api', endpoint, { args })`), keyed by workspace
  * path instead of sessionId.
  *
- * "Add directory" never asks the host for a picker: the plugin draws its own
- * browser (an editable path field, one level of child directories, an optional
- * "new folder") on the `multiFolder/browse` + `multiFolder/makeDir` endpoints
- * over the shared RPC channel. One interaction serves every deployment, which
- * the host's own picker cannot: `uiWorkspace.pickDirectory()` is native-only
- * (it answers `directory-picker/unavailable` whenever the host composed the
- * browse backend — a LAN bind, a remote client, a desktop shell), while its
- * `listDirectory`/`createDirectory` twins are refused under the native
- * composition. Listing this way also stays clear of the DSH Windows native
- * chooser worker, whose crash surfaces as `directory picker failed: … worker
- * exited …`.
+ * "Add directory" calls `multiFolder/pick`. A `native` host picker may fall back
+ * to an OS dialog; a `browse` capability opens this plugin's browser through
+ * `multiFolder/browse` and `multiFolder/makeDir`. Closing the panel cancels a
+ * pending pick. Dismissing a system dialog adds nothing.
+ *
+ * Every configured row also carries "open in the host file manager"
+ * (`multiFolder/reveal`), which puts the directory in Explorer/Finder where the
+ * user's own shell integrations live.
  *
  * `@` discovery for the configured directories. The shipped `@` menu is
  * SINGLE-ROOT: `ui-reference` feeds it from `remote.fileReferences.list`, whose
@@ -107,6 +104,10 @@ window.__ModuleLoader__.load({
       browseDraft: '',
       /** "new folder" name draft. */
       newDirName: '',
+      /** A system pick is in flight. */
+      pickBusy: false,
+      /** Muted reason shown when the system picker FAILED and the browser took over. */
+      notice: null,
       /** Bumped on every workspaceCache write so chips re-read their count. */
       cacheRev: 0,
     };
@@ -232,6 +233,10 @@ window.__ModuleLoader__.load({
       'browse.newDirPlaceholder': '新建文件夹名称',
       'browse.newDirCreate': '创建',
       'browse.hint': '浏览宿主机文件系统；选中的目录将作为副工作目录添加。',
+      'panel.addBusy': '等待系统对话框…',
+      'panel.addBrowse': '改用内置浏览器选择…',
+      'panel.reveal': '在资源管理器中打开（宿主机）',
+      'panel.pickFailed': '系统目录选择器调用失败，已改用内置浏览器：{message}',
     };
     /** English dictionary — checked complete against the zh key set. */
     var enDict = {
@@ -269,6 +274,10 @@ window.__ModuleLoader__.load({
       'browse.newDirPlaceholder': 'New folder name',
       'browse.newDirCreate': 'Create',
       'browse.hint': 'Browses the host filesystem; the chosen directory is added as a secondary working directory.',
+      'panel.addBusy': 'Waiting for the system dialog…',
+      'panel.addBrowse': 'Use the built-in browser instead…',
+      'panel.reveal': 'Open in the host file manager',
+      'panel.pickFailed': 'The system picker failed; using the built-in browser: {message}',
     };
 
     // ------------------------------------------------------------- plugin
@@ -297,16 +306,37 @@ window.__ModuleLoader__.load({
        *  the `t` seat the renderer synthesizes from the declared
        *  `locale:` namespace (which also re-renders them on locale switch). */
       var t = locale.bind(NS);
+      var activePick = null;
+
+      function cancelPick() {
+        if (!activePick) return;
+        activePick.abort();
+        activePick = null;
+        patch({ pickBusy: false });
+      }
+
+      function closePanel() {
+        cancelPick();
+        patch({ open: false });
+      }
+
+      ctx.effect(function () {
+        return function () {
+          var controller = activePick;
+          activePick = null;
+          if (controller) controller.abort();
+        };
+      }, 'dsh-multi-folder: cancel picker on unload');
 
       // -------------------------------------------------- sessionless RPC
       /** Call one `multiFolder/*` endpoint over the shared /api channel.
        *  The Host gateway answers with the same `{ ok, value }` envelope as
        *  the command remote; business errors surface as thrown Errors. */
-      function remoteCall(endpoint, args) {
+      function remoteCall(endpoint, args, signal) {
         if (!connection || !connection.rpc || typeof connection.rpc.call !== 'function') {
           return Promise.reject(new Error('multi-folder: the shared RPC channel (connection service) is unavailable'));
         }
-        return connection.rpc.call('/api', endpoint, { args: args }).then(function (envelope) {
+        return connection.rpc.call('/api', endpoint, { args: args }, signal).then(function (envelope) {
           if (!envelope || envelope.ok !== true) {
             var message = envelope && envelope.error !== undefined
               ? String(envelope.error.message !== undefined ? envelope.error.message : envelope.error)
@@ -382,6 +412,7 @@ window.__ModuleLoader__.load({
        *  renders it as its own popover, everything else uses the overlay. */
       function openForWorkspace(workspacePath, anchor) {
         var seat = anchor || 'overlay';
+        cancelPick();
         patch(browserReset());
         if (!workspacePath) {
           patch({ open: true, mode: 'workspace', sessionId: null, workspace: null, dirs: [], error: null, anchor: seat });
@@ -458,11 +489,8 @@ window.__ModuleLoader__.load({
       }
 
       // -------------------------------------------- owned directory browser
-      // "Add directory" is served entirely by this plugin (host item 8): the
-      // browser reads levels over `multiFolder/browse` and may create one child
-      // through `multiFolder/makeDir`, so the interaction never depends on the
-      // host's composed directory picker — the native chooser, the browse
-      // backend and a shell with no picker at all all behave the same here.
+      // The owned browser reads levels over `multiFolder/browse` and creates
+      // directories through `multiFolder/makeDir`.
 
       /** Read one level into the store. A blank path asks the host for its
        *  home directory, so the browser always has somewhere to start. */
@@ -486,9 +514,11 @@ window.__ModuleLoader__.load({
         });
       }
 
-      /** Open the browser at the panel's workspace (or the host home when the
-       *  panel has no workspace path yet) and read its first level. */
-      function addDirectory() {
+      /** Open the OWNED browser at the panel's workspace (or the host home when
+       *  the panel has no workspace path yet) and read its first level. Reachable
+       *  from the panel at all times, and the automatic destination whenever the
+       *  system picker cannot answer. */
+      function openOwnedBrowser() {
         var snapshot = getSnapshot();
         patch({
           browseOpen: true,
@@ -501,6 +531,35 @@ window.__ModuleLoader__.load({
         browseTo(snapshot.workspace || '');
       }
 
+      /** Pick a directory, or open the owned browser when no system picker answers. */
+      function addDirectory() {
+        var snapshot = getSnapshot();
+        if (snapshot.pickBusy) return Promise.resolve();
+        var controller = new AbortController();
+        activePick = controller;
+        patch({ pickBusy: true, error: null, notice: null });
+        return remoteCall('multiFolder/pick', { cwd: snapshot.workspace || '' }, controller.signal).then(
+          function (value) {
+            if (activePick !== controller) return undefined;
+            activePick = null;
+            patch({ pickBusy: false });
+            var picked = value && typeof value.path === 'string' && value.path !== '' ? value.path : null;
+            if (picked) return commitBrowsePath(picked);
+            if (value && (value.via === 'host-native' || value.via === 'os-dialog')) return undefined;
+            return openOwnedBrowser();
+          },
+          function (error) {
+            if (activePick !== controller) return undefined;
+            activePick = null;
+            patch({
+              pickBusy: false,
+              notice: t('panel.pickFailed', { message: String(error && error.message ? error.message : error) }),
+            });
+            return openOwnedBrowser();
+          },
+        );
+      }
+
       /** Leave the browser without adding anything. */
       function closeBrowser() {
         patch(browserReset());
@@ -510,7 +569,7 @@ window.__ModuleLoader__.load({
        *  fresh open of the panel (header button, chip, launcher) starts there,
        *  so a browser left open by a dismissed panel never comes back stale. */
       function browserReset() {
-        return { browseOpen: false, browse: null, browseBusy: false, browseError: null, newDirName: '' };
+        return { browseOpen: false, browse: null, browseBusy: false, browseError: null, newDirName: '', notice: null };
       }
 
       /** Adopt one path as a secondary working directory through the channel
@@ -553,6 +612,7 @@ window.__ModuleLoader__.load({
       function openFor(sessionId) {
         if (!sessionId) return;
         var cached = sessionCache[sessionId];
+        cancelPick();
         patch(browserReset());
         patch({
           open: true,
@@ -594,7 +654,7 @@ window.__ModuleLoader__.load({
               var current = getSnapshot();
               var isOpen = current.open && current.sessionId === sessionId;
               if (isOpen) {
-                patch({ open: false });
+                closePanel();
               } else {
                 openFor(sessionId);
               }
@@ -688,7 +748,7 @@ window.__ModuleLoader__.load({
               {
                 type: 'button',
                 title: t('title.close'),
-                onClick: function () { closeBrowser(); patch({ open: false }); },
+                onClick: function () { closePanel(); },
                 style: { padding: '2px 8px', borderRadius: 6, border: '1px solid transparent', background: 'transparent', color: TOKEN.inkMuted, cursor: 'pointer' },
               },
               '✕',
@@ -753,6 +813,9 @@ window.__ModuleLoader__.load({
           store.browseError
             ? React.createElement('div', { style: { marginBottom: 8, color: TOKEN.danger, whiteSpace: 'pre-wrap', fontSize: 12 } }, String(store.browseError))
             : null,
+          store.notice
+            ? React.createElement('div', { style: { marginBottom: 8, color: TOKEN.inkMuted, whiteSpace: 'pre-wrap', fontSize: 11 } }, String(store.notice))
+            : null,
           React.createElement(
             'div',
             { style: { maxHeight: 200, overflowY: 'auto', marginBottom: 6 } },
@@ -835,6 +898,22 @@ window.__ModuleLoader__.load({
               },
               dir,
             ),
+            React.createElement(
+              'button',
+              {
+                type: 'button',
+                title: t('panel.reveal'),
+                disabled: !usable,
+                onClick: function () {
+                  patch({ error: null });
+                  remoteCall('multiFolder/reveal', { path: dir }).catch(function (e) {
+                    patch({ error: String(e && e.message ? e.message : e) });
+                  });
+                },
+                style: { padding: '2px 6px', borderRadius: 6, border: '1px solid transparent', background: 'transparent', color: TOKEN.inkMuted, cursor: 'pointer' },
+              },
+              '📂',
+            ),
             React.createElement(
               'button',
               {
@@ -864,7 +943,7 @@ window.__ModuleLoader__.load({
               {
                 type: 'button',
                 title: t('title.close'),
-                onClick: function () { patch({ open: false }); },
+                onClick: function () { closePanel(); },
                 style: { padding: '2px 8px', borderRadius: 6, border: '1px solid transparent', background: 'transparent', color: TOKEN.inkMuted, cursor: 'pointer' },
               },
               '✕',
@@ -896,7 +975,7 @@ window.__ModuleLoader__.load({
               'button',
               {
                 type: 'button',
-                disabled: !!store.busy || !usable,
+                disabled: !!store.busy || !!store.pickBusy || !usable,
                 onClick: function () { addDirectory(); },
                 style: {
                   flex: 1,
@@ -905,11 +984,11 @@ window.__ModuleLoader__.load({
                   border: '1px solid ' + TOKEN.border,
                   background: TOKEN.fill,
                   color: TOKEN.ink,
-                  cursor: store.busy || !usable ? 'default' : 'pointer',
-                  opacity: store.busy || !usable ? 0.6 : 1,
+                  cursor: store.busy || store.pickBusy || !usable ? 'default' : 'pointer',
+                  opacity: store.busy || store.pickBusy || !usable ? 0.6 : 1,
                 },
               },
-              store.busy ? t('panel.adding') : t('panel.add'),
+              store.busy ? t('panel.adding') : (store.pickBusy ? t('panel.addBusy') : t('panel.add')),
             ),
             React.createElement(
               'button',
@@ -936,6 +1015,26 @@ window.__ModuleLoader__.load({
               t('panel.refresh'),
             ),
           ),
+          React.createElement(
+            'button',
+            {
+              type: 'button',
+              disabled: !!store.busy || !!store.pickBusy || !usable,
+              onClick: function () { openOwnedBrowser(); },
+              style: {
+                marginBottom: 6,
+                padding: 0,
+                border: '1px solid transparent',
+                background: 'transparent',
+                color: TOKEN.inkMuted,
+                fontSize: 11,
+                textAlign: 'left',
+                cursor: store.busy || store.pickBusy || !usable ? 'default' : 'pointer',
+                opacity: store.busy || store.pickBusy || !usable ? 0.5 : 1,
+              },
+            },
+            t('panel.addBrowse'),
+          ),
           React.createElement(
             'div',
             {
@@ -1030,7 +1129,7 @@ window.__ModuleLoader__.load({
       /** Click-outside catcher for an open popover. */
       function Backdrop() {
         return React.createElement('div', {
-          onClick: function () { patch({ open: false }); },
+          onClick: function () { closePanel(); },
           style: { position: 'fixed', inset: 0, zIndex: 30 },
         });
       }
@@ -1201,7 +1300,7 @@ window.__ModuleLoader__.load({
               label: count !== null && count > 0 ? t('label.withCount', { count: count }) : t('label'),
               onClick: function () {
                 if (open) {
-                  patch({ open: false });
+                  closePanel();
                 } else {
                   openForWorkspace(workspacePath, 'dock');
                 }
@@ -1315,7 +1414,7 @@ window.__ModuleLoader__.load({
             label: count !== null && count > 0 ? t('label.withCount', { count: count }) : t('label'),
             onClick: function () {
               if (open) {
-                patch({ open: false });
+                closePanel();
               } else {
                 openForWorkspace(workspacePath, 'extras');
               }

package/lib/index.js

@@ -68,19 +68,10 @@
  *    <secondary>` launched from the primary workspace cannot write the
  *    repo) gets a workdir-fix hint attached as an additional context at
  *    the `tools/post-execute` boundary.
- * 8. Owned directory browser: "Add directory" opens a browser drawn by the
- *    client half and served by `browse`/`makeDir` above. Listing rides the
- *    `fs` seam (`fs.listDir`), which — unlike the host's directory-picker
- *    seam — is composed in EVERY deployment, so one interaction covers the
- *    native-chooser composition, the browse composition (LAN / remote
- *    clients / desktop shells) and shells that compose no picker at all.
- *    The framework offers no plugin-facing alternative: `uiWorkspace`'s
- *    `pickDirectory()` is native-only (it answers `directory-picker/unavailable`
- *    under the browse composition), its `listDirectory`/`createDirectory`
- *    twins are browse-only, and the shipped in-app browser is reachable only
- *    by the shell's own workspace surfaces. Directory creation mirrors the
- *    shipped browse backend, which uses Node's `mkdir` (the fs seam has no
- *    creation primitive).
+ * 8. Directory picking: `pick` uses the host's `native` capability, then an
+ *    OS dialog on failure. A `browse` capability goes straight to the client
+ *    browser served by `browse`/`makeDir`; panel closure cancels the request.
+ *    `reveal` opens an existing directory in the host file manager.
  * 9. `@` file discovery for the configured directories (see the
  *    "secondary-directory file discovery" section). The shipped `@`
  *    file-reference menu is single-root — its provider walks the session cwd
@@ -92,7 +83,9 @@
  */
 
 import { mkdir } from 'node:fs/promises'
-import { join, posix, win32 } from 'node:path'
+import { spawn } from 'node:child_process'
+import { join, dirname, posix, win32 } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import os from 'node:os'
 
 export const name = 'dsh-multi-folder'
@@ -395,6 +388,238 @@ export function apply(ctx) {
     return { path: target, parent }
   }
 
+  // ---------------------------------------------------- native folder picker
+
+  /** How long one native selection may stay open before it is dismissed. */
+  const NATIVE_PICK_TIMEOUT_MS = 5 * 60 * 1000
+  const pickerScript = () => join(dirname(fileURLToPath(import.meta.url)), 'native-picker.ps1')
+
+  /**
+   * Ask the host's composed `directoryPicker` service — and only when it
+   * composed the NATIVE backend.
+   * @returns { path, via: 'host-native' } with a null path when the user
+   *   cancelled, `{ path: null, via: 'unavailable' }` whenever the host must not
+   *   be shown an OS chooser (the browse backend, an unknown kind, a capability
+   *   that cannot even be read), or null when no picker is composed at all — the
+   *   caller may then try the OS dialog of the host machine.
+   */
+  const pickViaHostService = async (signal) => {
+    let picker
+    try {
+      picker = ctx.get('directoryPicker')
+    } catch {
+      picker = undefined
+    }
+    if (!picker || typeof picker.capability !== 'function') return null
+    let capability
+    try {
+      capability = picker.capability()
+    } catch {
+      return { path: null, via: 'unavailable' }
+    }
+    if (!capability || capability.kind !== 'native') return { path: null, via: 'unavailable' }
+    if (typeof capability.pick !== 'function') return null
+    const selected = await capability.pick(signal)
+    return { path: typeof selected === 'string' && fullyQualified(selected) ? selected : null, via: 'host-native' }
+  }
+
+  /**
+   * Run one helper process to completion.
+   * @returns { code, stdout, stderr }, { spawnError } when it never started, or
+   *   { aborted } when the caller's signal stopped it.
+   */
+  const runPickerProcess = (command, args, timeoutMs, stopWhen, signal) =>
+    new Promise((resolve) => {
+      if (signal?.aborted) {
+        resolve({ aborted: true })
+        return
+      }
+      let child
+      try {
+        child = spawn(command, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+      } catch (e) {
+        resolve({ spawnError: e })
+        return
+      }
+      let stdout = ''
+      let stderr = ''
+      let settled = false
+      const done = (outcome) => {
+        if (settled) return
+        settled = true
+        clearTimeout(killer)
+        signal?.removeEventListener('abort', abort)
+        resolve(outcome)
+      }
+      const abort = () => {
+        try { child.kill() } catch { /* already gone */ }
+        done({ aborted: true })
+      }
+      const killer = setTimeout(() => {
+        try { child.kill() } catch { /* already gone */ }
+        done({ killed: true, stdout, stderr })
+      }, timeoutMs + 5000)
+      if (typeof killer.unref === 'function') killer.unref()
+      signal?.addEventListener('abort', abort, { once: true })
+      if (signal?.aborted) abort()
+      child.stdout?.setEncoding('utf8')
+      child.stderr?.setEncoding('utf8')
+      const consume = (chunk) => {
+        stdout += chunk
+        if (stopWhen && !settled && stopWhen(stdout)) {
+          try { child.kill() } catch { /* already gone */ }
+          done({ code: null, stdout, stderr, early: true })
+        }
+      }
+      if (child.stdout) child.stdout.on('data', consume)
+      if (child.stderr) child.stderr.on('data', (chunk) => { stderr += chunk })
+      child.on('error', (error) => done({ spawnError: error }))
+      child.on('close', (code) => done({ code, stdout, stderr }))
+    })
+
+  /** The last non-empty line of one helper's output, trimmed, or ''. */
+  const lastLine = (text) => {
+    const lines = String(text || '').split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0)
+    return lines.length > 0 ? lines[lines.length - 1] : ''
+  }
+
+  const printedPath = (output) => {
+    if (!/\r?\n$/.test(String(output))) return null
+    const last = lastLine(output)
+    return last !== '' && fullyQualified(last) ? last : null
+  }
+
+  /**
+   * The path a helper had printed by the time it exited — the same read as
+   * `printedPath`, without the demand that the line had already ended: a helper
+   * stopped right after writing its answer still selected something, and reading
+   * that as a dismissal would add nothing, silently.
+   */
+  const pickerResultPath = (outcome) => {
+    if (!outcome || outcome.spawnError) return null
+    const last = lastLine(outcome.stdout)
+    return last !== '' && fullyQualified(last) ? last : null
+  }
+
+  /**
+   * Re-raise the caller's abort reason when the helper was stopped by it — an
+   * aborted outcome carries no exit code, and reading that absence as a helper
+   * failure would report a cancelled dialog as a broken one.
+   */
+  const raiseIfAborted = (outcome, signal) => {
+    if (!outcome.aborted) return
+    signal?.throwIfAborted()
+    throw new Error('the folder dialog was cancelled')
+  }
+
+  /**
+   * Open the HOST machine's own folder chooser. Windows drives the shipped
+   * `native-picker.ps1` — the Vista+ common item dialog with FOS_PICKFOLDERS,
+   * i.e. the same dialog other applications show, which shell integrations hook
+   * (the legacy `FolderBrowserDialog` tree is a different control that they do
+   * not) — and macOS asks Finder through `osascript`.
+   * @returns { path, via: 'os-dialog' }, or null on a platform with no OS
+   *   dialog to open — the caller then keeps the plugin's own browser.
+   */
+  const pickViaOsDialog = async (initial, signal) => {
+    const start = typeof initial === 'string' && fullyQualified(initial) ? initial : ''
+    if (process.platform === 'win32') {
+      const args = [
+        '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+        '-File', pickerScript(),
+        '-TimeoutMs', String(NATIVE_PICK_TIMEOUT_MS),
+      ]
+      if (start !== '') args.push('-InitialDirectory', start)
+      let outcome = await runPickerProcess('pwsh', args, NATIVE_PICK_TIMEOUT_MS, printedPath, signal)
+      if (outcome.spawnError && outcome.spawnError.code === 'ENOENT') {
+        // Windows PowerShell is always present; pwsh is only usually present.
+        outcome = await runPickerProcess('powershell.exe', args, NATIVE_PICK_TIMEOUT_MS, printedPath, signal)
+      }
+      raiseIfAborted(outcome, signal)
+      signal?.throwIfAborted()
+      if (outcome.spawnError) throw outcome.spawnError
+      const selected = printedPath(outcome.stdout) || pickerResultPath(outcome)
+      const settled = { path: typeof selected === 'string' && fullyQualified(selected) ? selected : null, via: 'os-dialog' }
+      // `early` = the answer arrived and the helper is merely shutting down;
+      // `killed` = its own deadline dismissed the dialog and the process
+      // outlived the grace period. Neither is a failure, and NEITHER carries an
+      // exit code to judge (both report `code: null`).
+      if (outcome.early || outcome.killed) return settled
+      // The helper exits 0 for BOTH "selected" and "dismissed" (it prints a path
+      // or nothing), so any other exit means the dialog never ran — an
+      // ExecutionPolicy block, a failed Add-Type. Reporting that as a plain
+      // cancellation would leave the user watching nothing happen at all, which
+      // is why it is raised for the caller to fall back on.
+      if (outcome.code !== 0) {
+        const why = lastLine(outcome.stderr)
+        throw new Error('the folder dialog helper failed (exit ' + outcome.code + ')' + (why ? ': ' + why : ''))
+      }
+      return settled
+    }
+    if (process.platform === 'darwin') {
+      // No prompt: Finder supplies its own localized one, exactly like the
+      // Windows dialog supplies its own localized title.
+      const outcome = await runPickerProcess('osascript', ['-e', 'POSIX path of (choose folder)'], NATIVE_PICK_TIMEOUT_MS, printedPath, signal)
+      raiseIfAborted(outcome, signal)
+      signal?.throwIfAborted()
+      if (outcome.spawnError) throw outcome.spawnError
+      const selected = printedPath(outcome.stdout) || pickerResultPath(outcome)
+      const settled = { path: typeof selected === 'string' && fullyQualified(selected) ? selected : null, via: 'os-dialog' }
+      // An early or killed outcome carries no exit code of its own, and a
+      // dismissal is the ordinary result in both cases.
+      if (outcome.early || outcome.killed) return settled
+      // AppleScript reports a user cancellation as execution error -128; every
+      // other non-zero exit is a real failure and must not be mistaken for one.
+      if (outcome.code !== 0 && !/-128|User canceled/i.test(String(outcome.stderr || ''))) {
+        const why = lastLine(outcome.stderr)
+        throw new Error('the macOS folder chooser failed (exit ' + outcome.code + ')' + (why ? ': ' + why : ''))
+      }
+      return settled
+    }
+    return null
+  }
+
+  /**
+   * Open the host machine's file manager at one existing directory — one click from the
+   * panel to the shell integrations the user already has (Listary, QuickLook, a
+   * terminal "open here"). Detached by design: the file manager outlives this
+   * call, so there is no exit status to report and no error to invent.
+   * @param path - fully qualified directory on the host.
+   * @returns the canonical path and the helper that was asked to show it.
+   */
+  const coreReveal = async (path) => {
+    if (typeof path !== 'string' || !fullyQualified(path)) {
+      throw new Error('reveal requires a fully qualified path, got "' + String(path) + '"')
+    }
+    const target = await fs.resolve(path)
+    const info = await fs.stat(target)
+    if (!info || info.type !== 'directory') throw new Error('reveal requires an existing directory: "' + path + '"')
+    const absolute = fs.processPath(target)
+    const command = process.platform === 'win32' ? 'explorer.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open'
+    let child
+    try {
+      child = spawn(command, [absolute], { detached: true, stdio: 'ignore' })
+    } catch (e) {
+      throw new Error('cannot open "' + absolute + '": ' + String(e && e.message ? e.message : e))
+    }
+    // A detached spawn reports a missing executable asynchronously, so wait for
+    // 'spawn' before claiming success: otherwise a host without `xdg-open` would
+    // report an opened file manager that never appeared. After that the process
+    // is on its own — detached, unreferenced, and with a listener so a later
+    // failure cannot surface as an unhandled 'error' event on the plugin.
+    try {
+      await new Promise((resolve, reject) => {
+        child.once('spawn', resolve)
+        child.once('error', reject)
+      })
+    } catch (e) {
+      throw new Error('cannot open "' + absolute + '": ' + String(e && e.message ? e.message : e))
+    }
+    child.on('error', () => {})
+    child.unref()
+    return { path: absolute, via: command }
+  }
+
   // ------------------------------------- secondary-directory file discovery
   // The shipped `@` file-reference menu is SINGLE-ROOT by construction: its
   // provider (`dsh-file-reference-local`) builds one `WorkspaceFileSearch` per
@@ -688,6 +913,9 @@ export function apply(ctx) {
   const remoteErrorMessage = (e) =>
     'multi-folder: ' + String(e && e.message ? e.message : e).replace(/^multi-folder:\s*/, '')
 
+  /** One failure's message, for composing a diagnostic without nesting prefixes. */
+  const reasonOf = (e) => String(e && e.message ? e.message : e)
+
   const multiFolderApi = {
     async list(workspace) {
       try {
@@ -738,7 +966,48 @@ export function apply(ctx) {
         throw new Error(remoteErrorMessage(e))
       }
     },
+    /**
+     * Open the system folder chooser on the host machine and report what came
+     * back. `via` tells the client half apart the three outcomes it must
+     * distinguish: a completed system dialog (`host-native` / `os-dialog` —
+     * a null path means the user cancelled, so nothing must be opened), and
+     * `unavailable`, where NO system picker could answer and the client should
+     * keep using the plugin's own browser.
+     */
+    async pick(cwd, signal) {
+      try {
+        signal?.throwIfAborted()
+        let native = null
+        let nativeFailure = null
+        try {
+          native = await pickViaHostService(signal)
+        } catch (e) {
+          // A composed chooser that refuses or crashes must not take the session
+          // down with it — the OS dialog below is exactly the second attempt.
+          // The reason is still kept and logged, because a downgrade nobody can
+          // explain afterwards is the failure mode this fallback exists to avoid.
+          nativeFailure = e
+          ctx.logger?.warn?.('multi-folder: the host directory picker failed: ' + reasonOf(nativeFailure))
+        }
+        signal?.throwIfAborted()
+        if (native) return native
+        const os = await pickViaOsDialog(cwd, signal)
+        if (os) return os
+        if (nativeFailure) throw new Error('the host directory picker failed: ' + reasonOf(nativeFailure))
+        return { path: null, via: 'unavailable' }
+      } catch (e) {
+        throw new Error(remoteErrorMessage(e))
+      }
+    },
+    async reveal(path) {
+      try {
+        return await coreReveal(path)
+      } catch (e) {
+        throw new Error(remoteErrorMessage(e))
+      }
+    },
   }
+
   Object.defineProperty(multiFolderApi, 'typertRemote', {
     value: Object.freeze({
       service: multiFolderApi,
@@ -770,6 +1039,8 @@ export function apply(ctx) {
       remoteInvocation('browse', ['path']),
       remoteInvocation('makeDir', ['parent', 'name']),
       remoteInvocation('listFiles', ['workspace', 'query']),
+      { ...remoteInvocation('pick', ['cwd']), cancellation: { parameter: 'signal' } },
+      remoteInvocation('reveal', ['path']),
     ],
   }
 

package/lib/native-picker.ps1

@@ -0,0 +1,290 @@
+#requires -Version 5.1
+<#
+  native-picker.ps1 -- a modern Windows folder chooser for non-GUI processes.
+
+  Why this exists: `System.Windows.Forms.FolderBrowserDialog` is the LEGACY
+  tree-view dialog (SHBrowseForFolder) and `System.Windows.Forms.OpenFolderDialog`
+  (.NET 8+) is not present in every PowerShell build, so neither can be relied on
+  when the goal is the SAME dialog Explorer and other apps show -- the Vista+
+  common item dialog (`IFileOpenDialog` with `FOS_PICKFOLDERS`). Shell helpers
+  such as Listary hook that dialog, not the legacy tree.
+
+  The dialog runs on a dedicated STA thread (PowerShell 7 starts MTA, where the
+  common dialog is not guaranteed to work), gets a bounded foreground assist
+  (the caller is usually a background host process, so a fresh window would
+  otherwise open behind the user's windows), and can auto-close after a timeout
+  so a request can never be blocked forever by an unanswered dialog.
+
+  Output: the selected absolute path on stdout, or NOTHING when the user
+  cancelled or the timeout dismissed the dialog; both of those exit 0, so the
+  caller can tell them from a helper that never ran. A non-zero exit therefore
+  means the helper itself failed (an ExecutionPolicy block, a failed Add-Type)
+  and must be reported instead of read as a cancellation.
+#>
+[CmdletBinding()]
+param(
+  [string]$InitialDirectory = '',
+  [int]$TimeoutMs = 0,
+  [switch]$DryRun
+)
+
+$ErrorActionPreference = 'Stop'
+
+$source = @'
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+
+public static class DshFolderPicker
+{
+    [ComImport, Guid("DC1C5A9C-E88A-4DDE-A5A1-60F82A20AEF7")]
+    private class FileOpenDialogRCW
+    {
+    }
+
+    [ComImport, Guid("D57C7288-D4AD-4768-BE02-9D969532D960"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    private interface IFileOpenDialog
+    {
+        [PreserveSig]
+        int Show(IntPtr hwndParent);
+        void SetFileTypes(uint cFileTypes, IntPtr rgFilterSpec);
+        void SetFileTypeIndex(uint iFileType);
+        void GetFileTypeIndex(out uint piFileType);
+        void Advise(IntPtr pfde, out uint pdwCookie);
+        void Unadvise(uint dwCookie);
+        void SetOptions(uint fos);
+        void GetOptions(out uint pfos);
+        void SetDefaultFolder(IShellItem psi);
+        void SetFolder(IShellItem psi);
+        void GetFolder(out IShellItem ppsi);
+        void GetCurrentSelection(out IShellItem ppsi);
+        void SetFileName([MarshalAs(UnmanagedType.LPWStr)] string pszName);
+        void GetFileName([MarshalAs(UnmanagedType.LPWStr)] out string pszName);
+        void SetTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle);
+        void SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszText);
+        void SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string pszLabel);
+        void GetResult(out IShellItem ppsi);
+        void AddPlace(IShellItem psi, int fdap);
+        void SetDefaultExtension([MarshalAs(UnmanagedType.LPWStr)] string pszDefaultExtension);
+        void Close([MarshalAs(UnmanagedType.Error)] int hr);
+        void SetClientGuid(ref Guid guid);
+        void ClearClientData();
+        void SetFilter(IntPtr pFilter);
+        void GetResults(out IntPtr ppenum);
+        void GetSelectedItems(out IntPtr ppsai);
+    }
+
+    [ComImport, Guid("43826D1E-E718-42EE-BC55-A1E261C37BFE"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    private interface IShellItem
+    {
+        void BindToHandler(IntPtr pbc, ref Guid bhid, ref Guid riid, out IntPtr ppv);
+        void GetParent(out IShellItem ppsi);
+        void GetDisplayName(uint sigdnName, [MarshalAs(UnmanagedType.LPWStr)] out string ppszName);
+        void GetAttributes(uint sfgaoMask, out uint psfgaoAttribs);
+        void Compare(IShellItem psi, uint hint, out int piOrder);
+    }
+
+    [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+    private static extern void SHCreateItemFromParsingName(
+        [MarshalAs(UnmanagedType.LPWStr)] string pszPath,
+        IntPtr pbc,
+        ref Guid riid,
+        [MarshalAs(UnmanagedType.Interface)] out IShellItem ppv);
+
+    private delegate bool EnumProc(IntPtr hWnd, IntPtr param);
+
+    [DllImport("kernel32.dll")]
+    private static extern uint GetCurrentProcessId();
+
+    [DllImport("user32.dll")]
+    private static extern bool EnumWindows(EnumProc callback, IntPtr param);
+
+    [DllImport("user32.dll")]
+    private static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint pid);
+
+    [DllImport("user32.dll", CharSet = CharSet.Unicode)]
+    private static extern int GetClassName(IntPtr hWnd, StringBuilder text, int count);
+
+    [DllImport("user32.dll")]
+    private static extern bool SetForegroundWindow(IntPtr hWnd);
+
+    [DllImport("user32.dll")]
+    private static extern bool BringWindowToTop(IntPtr hWnd);
+
+    [DllImport("user32.dll", CharSet = CharSet.Unicode)]
+    private static extern bool PostMessage(IntPtr hWnd, uint msg, IntPtr wParam, IntPtr lParam);
+
+    [DllImport("user32.dll")]
+    private static extern IntPtr SetThreadDpiAwarenessContext(IntPtr context);
+
+    private const uint FOS_PICKFOLDERS = 0x00000020;
+    private const uint FOS_FORCEFILESYSTEM = 0x00000040;
+    private const uint FOS_PATHMUSTEXIST = 0x00000800;
+    private const uint SIGDN_FILESYSPATH = 0x80058000;
+    private const uint WM_CLOSE = 0x0010;
+    /** DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 / _PER_MONITOR_AWARE. */
+    private static readonly IntPtr PER_MONITOR_AWARE_V2 = new IntPtr(-4);
+    private static readonly IntPtr PER_MONITOR_AWARE = new IntPtr(-3);
+
+    /// The folder dialog is a plain #32770 window created BY THIS PROCESS, so it
+    /// is found by pid + class rather than by its title: a title is optional
+    /// (Windows then supplies its own localized one), and matching on one could
+    /// pick up a window that is not ours.
+    private static IntPtr FindOwnDialog()
+    {
+        uint me = GetCurrentProcessId();
+        IntPtr found = IntPtr.Zero;
+        EnumWindows(delegate(IntPtr hWnd, IntPtr param)
+        {
+            uint pid;
+            GetWindowThreadProcessId(hWnd, out pid);
+            if (pid != me) return true;
+            StringBuilder cls = new StringBuilder(64);
+            GetClassName(hWnd, cls, cls.Capacity);
+            if (cls.ToString() != "#32770") return true;
+            found = hWnd;
+            return false;
+        }, IntPtr.Zero);
+        return found;
+    }
+
+    public static string Pick(string initial, int timeoutMs)
+    {
+        string result = null;
+        Exception failure = null;
+        Thread thread = new Thread(delegate()
+        {
+            IntPtr previous = IntPtr.Zero;
+            try
+            {
+                // Render at the monitor's REAL DPI. The PowerShell host is
+                // DPI-UNAWARE, so an untouched dialog is drawn at 96 DPI and then
+                // BITMAP-STRETCHED by Windows to the display scaling (150% on the
+                // machine this was written on) — which is exactly the soft, fuzzy
+                // text users notice. Thread-level awareness is the fix that always
+                // applies: a process manifest may already have fixed the PROCESS
+                // context (SetProcessDpiAwarenessContext would then be refused), but
+                // a thread context may be set at any time, and the dialog is created
+                // on this thread.
+                previous = SetThreadDpiAwarenessContext(PER_MONITOR_AWARE_V2);
+                if (previous == IntPtr.Zero) previous = SetThreadDpiAwarenessContext(PER_MONITOR_AWARE);
+            }
+            catch
+            {
+                // A Windows build without the thread-scoped DPI API still shows the
+                // dialog, only bitmap-stretched at the process DPI — not worth
+                // failing the pick over, and an exception here would have escaped
+                // this thread and killed the helper outright.
+            }
+            try { result = Show(initial, timeoutMs); }
+            catch (Exception error) { failure = error; }
+            finally
+            {
+                if (previous != IntPtr.Zero) SetThreadDpiAwarenessContext(previous);
+            }
+        });
+        thread.SetApartmentState(ApartmentState.STA);
+        thread.IsBackground = true;
+        thread.Start();
+        bool finished = timeoutMs > 0
+            ? thread.Join(timeoutMs + 5000)
+            : thread.Join(Timeout.Infinite);
+        if (failure != null) throw failure;
+        return finished ? result : null;
+    }
+
+    private static string Show(string initial, int timeoutMs)
+    {
+        IFileOpenDialog dialog = (IFileOpenDialog)new FileOpenDialogRCW();
+        uint options;
+        dialog.GetOptions(out options);
+        dialog.SetOptions(options | FOS_PICKFOLDERS | FOS_FORCEFILESYSTEM | FOS_PATHMUSTEXIST);
+        if (!String.IsNullOrEmpty(initial))
+        {
+            try
+            {
+                Guid iid = typeof(IShellItem).GUID;
+                IShellItem folder;
+                SHCreateItemFromParsingName(initial, IntPtr.Zero, ref iid, out folder);
+                dialog.SetFolder(folder);
+            }
+            catch
+            {
+                // An unusable start directory is not worth failing the pick over.
+            }
+        }
+        // One watchdog owns both jobs, because they need the same window handle
+        // but NOT the same apartment: `IFileDialog::Close` cannot be called on
+        // the dialog from another thread (COM refuses the cross-apartment call
+        // and the dialog simply stayed on screen until the process died), while
+        // the plain Win32 calls below work from any thread. WM_CLOSE is what the
+        // dialog's own X button sends, so Show() returns the ordinary cancel
+        // HRESULT afterwards.
+        // `watchdog` is declared first and assigned second on purpose: a lambda
+        // that captures a local must find it definitely assigned when the
+        // delegate is created, so the single-statement form does not compile.
+        Timer watchdog = null;
+        DateTime deadline = timeoutMs > 0 ? DateTime.UtcNow.AddMilliseconds(timeoutMs) : DateTime.MinValue;
+        // The foreground assist is BOUNDED: it exists to bring a fresh dialog in
+        // front of a user whose host process is in the background, not to fight
+        // that user for the foreground for the dialog's whole life. Roughly three
+        // seconds of nudges, after which this timer only watches the deadline.
+        int assistTicks = 12;
+        int windowWaits = 240;
+        watchdog = new Timer(delegate(object state)
+        {
+            IntPtr window = FindOwnDialog();
+            if (window == IntPtr.Zero)
+            {
+                // A dialog that never appears leaves nothing to watch.
+                if (--windowWaits <= 0 && watchdog != null) watchdog.Dispose();
+                return;
+            }
+            if (deadline != DateTime.MinValue && DateTime.UtcNow >= deadline)
+            {
+                PostMessage(window, WM_CLOSE, IntPtr.Zero, IntPtr.Zero);
+                if (watchdog != null) watchdog.Dispose();
+                return;
+            }
+            if (assistTicks > 0)
+            {
+                SetForegroundWindow(window);
+                BringWindowToTop(window);
+                assistTicks--;
+            }
+        }, null, 250, 250);
+        int hr;
+        try { hr = dialog.Show(IntPtr.Zero); }
+        finally
+        {
+            if (watchdog != null) watchdog.Dispose();
+        }
+        if (hr != 0)
+        {
+            // 0x800704C7 (HRESULT_FROM_WIN32(ERROR_CANCELLED)) is the ordinary
+            // dismiss path; every other HRESULT means the dialog could not be
+            // shown at all, which the caller needs to hear about.
+            if (hr == unchecked((int)0x800704C7)) return null;
+            throw new COMException("dsh-native-picker: dialog returned 0x" + hr.ToString("X8"), hr);
+        }
+        IShellItem item;
+        dialog.GetResult(out item);
+        string path;
+        item.GetDisplayName(SIGDN_FILESYSPATH, out path);
+        return path;
+    }
+}
+'@
+
+if ($DryRun) {
+  # Compile only: proves the helper builds in this PowerShell without showing UI.
+  if (-not ('DshFolderPicker' -as [type])) { Add-Type -TypeDefinition $source -Language CSharp }
+  Write-Output 'compiled'
+  exit 0
+}
+
+if (-not ('DshFolderPicker' -as [type])) { Add-Type -TypeDefinition $source -Language CSharp }
+$selected = [DshFolderPicker]::Pick($InitialDirectory, $TimeoutMs)
+if ($selected) { Write-Output $selected }
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-multi-folder",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "DeepSeek Harness plugin: secondary working directories for a project. The agent keeps the primary workspace as cwd, gains equal write/exec permissions on configured secondary directories under workspace-write mode, and is notified of configuration changes at the next message boundary. Configurable from the session header AND from the session-creation page (before the first message) through a sessionless multiFolder remote API.",
   "keywords": [
     "dsh-plugin",
@@ -42,6 +42,8 @@
     "compatibility": {
       "node": ">=20",
       "dshReleases": {
+        "0.2.1-alpha.2": "compatible",
+        "0.2.1-alpha.1": "compatible",
         "0.2.0-rc.1": "compatible",
         "0.1.7-rc.2": "compatible",
         "0.1.6-alpha.1": "compatible",