dsh-multi-folder 0.3.1 → 0.3.3

package/README.md

@@ -17,6 +17,7 @@ A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin bun
 - The directory list is **injected into the system prompt** and re-rendered per session assembly.
 - Configuration changes notify the agent through a **non-interrupting message queue** — delivered at the next message boundary (user send or tool-call end), and **only when the directory set actually changed**.
 - Configurable **before the session starts**: the session-creation page (new-session screen) offers a Multi-folder entry that reads and edits the same per-workspace configuration through a **sessionless remote API** (`multiFolder/*` endpoints) — no session id required.
+- The **`@` file menu finds files in the configured directories**. The shipped `@` menu only ever searches the primary workspace, so this plugin contributes its own `@` group listing the secondary directories — headed by each directory.
 - **No new tools.** Everything is a framework-level change (tool-pipeline interception) plus a UI-level change (a session-scoped header entry).
 
 ## Requirements
@@ -49,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 |
@@ -65,6 +67,21 @@ Equivalent slash command for the user:
 
 The agent needs nothing extra: `read` / `glob` / `grep` work everywhere, and `write` / `edit` / `pwsh` / `bash` are intercepted and re-rooted automatically when the target path (or `workdir`) falls inside a configured secondary directory.
 
+### Finding secondary files with `@`
+
+Typing `@` in the composer offers the usual primary-workspace files **and** a group per configured secondary directory, fed by the plugin's own `multiFolder/listFiles` endpoint:
+
+| You type | You get |
+| -------- | ------- |
+| `@` | one row per configured directory — the entry points |
+| `@probe` | any matching file or directory across every configured directory, headed by its directory |
+| `@secondary-spike/src/` | that level, listed (directories first) |
+| `@D:/repos/other/src/` | the same level by its absolute spelling |
+
+Picking a row inserts an **absolute-path** mention (`@D:/repos/other/src/main.ts`), because a secondary directory lies outside the primary workspace and no relative path from it can reach one. Directory rows offer the usual `Tab` drill to descend.
+
+This is a **companion group, not a change to the shipped menu**: DSH's own `@` provider searches the session workspace only, and it is left exactly as it is. A workspace with no secondary directories configured behaves precisely as before.
+
 ## Permission model
 
 Each confined command runs under **exactly ONE writable root** — the workspace root the call is re-rooted to (the Windows ACL runner grants a single workspace write SID per process tree). Consequences:
@@ -82,8 +99,9 @@ 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.
 
 ## Project layout
@@ -91,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 plus `browse`/`makeDir` for the owned browser) |
-| `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" |
+| `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

@@ -17,6 +17,7 @@
 - 目录列表**注入系统提示词**，每次组装按会话求值；
 - 配置变更通过**不打断的消息队列**通知 Agent——在下一次消息边界（用户发送或工具调用结束）送达，且**仅在目录集合实际变化时**发送；
 - **会话开始前即可配置**：会话创建页（新会话界面）提供「多工作目录」入口（英文界面显示 "Multi-folder"），通过**无会话远程 API**（`multiFolder/*` 端点）读写同一份 per-workspace 配置——无需 session id；
+- **`@` 文件菜单能搜到副目录里的文件**：DSH 自带的 `@` 菜单只在主工作区内检索，因此本插件额外贡献自己的 `@` 分组，按目录成组列出副工作目录中的文件；
 - **不新增任何工具**：改动全部位于框架级（工具流水线拦截）与 UI 级（会话级头部入口）。
 
 ## 环境要求
@@ -49,7 +50,8 @@ dsh plugin --profile web add dsh-multi-folder
 
 | 操作 | 行为 |
 | ---- | ---- |
-| 添加目录 | 打开插件自带的目录浏览器（路径输入框 + 一级子目录列表 + 可新建文件夹） |
+| 添加目录 | `native` 使用系统文件夹对话框，失败后尝试宿主对话框；`browse` 直接打开插件自带浏览器（路径输入框 + 一级子目录列表 + 可新建文件夹） |
+| 在文件管理器中打开 | 在宿主机器的文件管理器（资源管理器 / Finder）中打开某个已配置目录 |
 | 移除 / 刷新 | 立即生效 |
 | 切换会话 | 面板自动切换为该会话的副工作目录 |
 | 重新打开面板 | 使用会话级缓存，不产生冗余命令行 |
@@ -65,6 +67,21 @@ dsh plugin --profile web add dsh-multi-folder
 
 Agent 无需任何额外操作：`read` / `glob` / `grep` 随处可用；`write` / `edit` / `pwsh` / `bash` 在路径（或 `workdir`）落入副目录时自动拦截并以该目录为沙箱根执行。
 
+### 用 `@` 查找副目录文件
+
+在输入框输入 `@`，除主工作区文件外，还会按每个已配置的副工作目录显示一个分组——数据来自插件自己的 `multiFolder/listFiles` 端点：
+
+| 输入 | 结果 |
+| ---- | ---- |
+| `@` | 每个已配置目录一行——即入口 |
+| `@probe` | 所有副目录中匹配的文件与目录，按其所在目录分组显示 |
+| `@secondary-spike/src/` | 列出该层级（目录优先） |
+| `@D:/repos/other/src/` | 用绝对路径写出同一层级 |
+
+选中一行会插入**绝对路径**引用（`@D:/repos/other/src/main.ts`）——因为副目录位于主工作区之外，从主工作区出发的任何相对路径都无法到达。目录行同样支持 `Tab` 逐层下钻。
+
+这是一个**并列分组，而不是对自带菜单的改动**：DSH 自己的 `@` provider 只检索会话工作区，本插件完全不改它。未配置任何副目录的工作区行为与从前完全一致。
+
 ## 权限模型
 
 每条受沙箱约束的命令只拥有**唯一一个可写根**——即本次调用被换根到的那个目录（Windows ACL runner 为每个进程树只授予一个工作区写 SID）。由此：
@@ -82,8 +99,9 @@ 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`）。
 
 ## 目录结构
@@ -91,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`） |
-| `lib/client.js` | 客户端插件（factory bundle）：会话头部按钮 + 覆盖层面板 + 会话创建页入口（输入框上方的 dock 胶囊 / 上游 hero chip / 右下角兜底浮动按钮）+「添加目录」背后的自带目录浏览器 |
+| `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

@@ -14,8 +14,8 @@ agent informed. No new tools are added.
 
 | Half | File | Role |
 | ---- | ---- | ---- |
-| Host | `lib/index.js` | Config store, tool-pipeline interception, prompt section, notifications, `/multi-folder` command, sessionless `multiFolder/*` remote API (configuration plus the browser's `browse`/`makeDir`) |
-| Client | `lib/client.js` | Session-header button + overlay panel; session-creation page entry (input-dock chip, upstream hero chip, or fixed fallback launcher — one at a time), all driving the host through the Remote BFF / shared RPC channel; the owned directory browser behind "Add directory" |
+| Host | `lib/index.js` | Config store, tool-pipeline interception, prompt section, notifications, `/multi-folder` command, sessionless `multiFolder/*` remote API (configuration, the browser's `browse`/`makeDir`, and the `@` menu's `listFiles`) |
+| Client | `lib/client.js` | Session-header button + overlay panel; session-creation page entry (input-dock chip, upstream hero chip, or fixed fallback launcher — one at a time), all driving the host through the Remote BFF / shared RPC channel; the owned directory browser behind "Add directory"; the companion `@` source |
 
 The package declares both faces: `dsh.bundle.patch` (the host row inserted by
 `cordis.patch.yml`) and `dsh.client` (the web bundle at `exports["./client"]`).
@@ -36,13 +36,15 @@ A listener on the `tools/execute` around-dispatch waterfall handles `write`, `ed
    operation directly with `{ ...standingPolicy, workspaceRoot: <secondary dir> }`:
    - `write`/`edit` → `fs.writeText` / `fs.editText`;
    - `pwsh`/`bash`, foreground → `shell.resolve({ command, workdir, dshEnv,
-     sandboxPolicy })` + `shell.run`, with the canonical workdir so the confinement
-     root and the process cwd agree exactly;
+     sandboxPolicy })` + the seam's foreground call — `shell.run(spec)` up to
+     0.1.6-alpha.1, `(await shell.execute(spec)).result()` from 0.1.7-alpha.1 on —
+     with the canonical workdir so the confinement root and the process cwd agree
+     exactly;
    - `pwsh`/`bash`, background (`run_in_background: true`) → the same re-rooted
      request registered through the generic jobs runtime (`ctx.jobs`) exactly like
-     the shipped shell tools (`kind` = tool name, `owner` = calling agent, streamed
+     the shipped shell tools (`kind` = tool name, `owner` = the calling session's id, streamed
      reads shaped for `job_output` with sandbox markers, terminal outcome in the
-     `completed`/`killed`/`failed` vocabulary). `shell.start` is **async** (it
+     `completed`/`killed`/`failed` vocabulary). The launch is **async** (it
      publishes the handle only once launch preparation — Windows ACL grants
      included — succeeded, and rejects when preparation is cancelled or fails), so
      the launch is adapted to the jobs runtime's synchronous `run(): JobHooks`
@@ -52,6 +54,24 @@ A listener on the `tools/execute` around-dispatch waterfall handles `write`, `ed
      preparation settles the job as `failed` with the real cause, and a read before
      publication is empty. A caller-aborted call falls through to the
      default pipeline, which raises the canonical abort error.
+   - Both shell paths ride one version-adaptive seam (`shellUsesExecute`). DSH
+     **0.1.7-alpha.1** (commit `d6bebc5783`, "converge on execute()") deleted
+     `ShellExecutor.run` and `ShellExecutor.start` in favour of a single
+     `execute(spec): Promise<ShellExecution>`, and turned `JobSpec.owner` from the
+     calling `Agent` into its `SessionId` — `jobs-local` resolves that id through
+     `agents.get(id)`, so an Agent object throws
+     `session "[object Object]" has no live agent`. The retired calls map onto the
+     new seam exactly: `await shell.run(spec)` becomes
+     `await (await shell.execute(spec)).result()`, and `await shell.start(spec)`
+     becomes `await shell.execute({ ...spec, onExpiry: 'none' })` — the retired
+     `start` armed no deadline at all, while `resolve()` defaults `onExpiry` to
+     `'kill'`, so a background run that inherited the default would be killed at
+     the executor's timeout. One probe on the **presence of `execute`** selects the
+     shape (never the absence of `run`, so a release that keeps the retired methods
+     as shims still takes the modern path), which is what keeps every release from
+     0.1.2-alpha through 0.2.0-rc.1+ served by the same code. A `ShellExecution`
+     *is* the `ShellProcess` the background path already consumed, so the jobs
+     adaptation itself needed no change.
    The result carries the same canonical value/content shapes as the shipped tools, so
    downstream presentation keeps working.
 5. Anything else — unknown tools, paths outside every secondary directory, missing
@@ -120,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 |
@@ -131,9 +151,14 @@ opens its own **sessionless** endpoints on the shared `/api` RPC channel:
   | `multiFolder/set` | `workspace`, `dirs` | `{ workspace, dirs, changed }` |
   | `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; the last two serve
-  the plugin's own directory browser and are keyed by path instead.
+  The four configuration endpoints are keyed by workspace; `browse`/`makeDir`
+  serve the plugin's own directory browser and are keyed by path instead;
+  `listFiles` serves the `@` menu (see its own section below) and is keyed by
+  workspace plus the live query.
 
   The workspace argument is a **path**, not a session id; the client derives
   it from the workspaces store (`WorkspaceView.path`). Business errors throw
@@ -155,6 +180,85 @@ opens its own **sessionless** endpoints on the shared `/api` RPC channel:
   does (type checks, absolute-path requirement, canonicalization, sanitization,
   primary-workspace exclusion).
 
+## Host: `@` discovery for secondary directories
+
+### Why this exists
+
+DSH's `@` file menu is **single-root by construction**, not by omission. Its
+provider (`@deepseek-ai/dsh-file-reference-local`) builds exactly one
+`WorkspaceFileSearch` per agent from `agent.session.header.cwd`, and that
+searcher refuses every candidate outside its root — a directory query resolves
+against the root and answers `undefined` for a path that escapes it (`..`
+check). Browser-side, `@deepseek-ai/dsh-client-ui-reference` registers the only
+`@` source and forwards each query to `remote.fileReferences.list`. A configured
+secondary directory is by definition outside the primary workspace, so no
+amount of typing can make the shipped menu offer one.
+
+The plugin therefore does not touch that provider at all. It publishes its own
+discovery endpoint over the files it already has read access to and contributes
+a companion menu group, which keeps both failure modes separate: a broken
+discovery path degrades to an empty group and can never affect the shipped
+files/sessions group.
+
+### Index and query rules
+
+`multiFolder/listFiles(workspace, query)` rides the same sessionless remote
+namespace as the browser endpoints and the same `fs` seam (`fs.resolve` +
+`fs.listDir`), so it needs no session and no new capability:
+
+| Rule | Why |
+| ---- | --- |
+| Breadth-first, bounded by `MAX_INDEX_ENTRIES` across all directories | one workspace's index cannot grow without limit |
+| Canonical-path deduplication (`fs.resolve` + `fs.processPath` per level) | a junction/symlink pointing back up the tree cannot re-enter the walk |
+| `INDEX_EXCLUDED` basenames never traversed | mirrors the shipped provider's defaults (`.git`, `node_modules`, build output); `lib` is deliberately absent there and therefore here |
+| Hidden entries indexed but invisible to a global query | parity with the shipped provider: `.foo` needs an explicit `.` query |
+| Per-workspace index cached with `FILE_INDEX_TTL_MS` (4 s) and a directory signature | config changes invalidate immediately; on-disk changes are caught within the TTL. Autocomplete is advisory, so staleness is invisible while rebuild cost stays bounded to one traversal per window |
+| An empty query yields the configured directories themselves | the menu's entry points; `@` alone stays cheap and does not list 30 files |
+
+Ranking mirrors the shipped provider (name beat path, directories win ties,
+then shorter paths, then name order) with **one deliberate deviation**: the
+path and subsequence rules read the *in-directory relative* path, never the
+absolute one. Every absolute path on a host shares its prefix (`D:/…`), so
+scoring it would make a one-character query match literally every candidate.
+The configured directory's own basename stays searchable at the lowest rank,
+which is what lets `@secondary-spike` narrow to that directory.
+
+A query carrying `/` lists a level instead of ranking one, and accepts two
+spellings — the absolute path a drill inserted, and a leading basename segment
+(`@secondary-spike/src/`). An ambiguous basename (two configured directories
+sharing one) resolves to nothing rather than to a guess. The decoded
+in-directory path is normalized (redundant separators and `.` segments drop)
+but **any `..` segment is refused**: without that, `@secondary/../../etc/` would
+list a directory outside every configured root while still claiming the
+configured directory as the candidates' owner — a listing that escaped the set
+the user granted, wearing a name that lies about it. The shipped provider
+refuses the same escape for the same reason.
+
+### Mention semantics
+
+A secondary directory lies outside the workspace root, so no relative path from
+that root can reach one: candidates are **absolute** paths (forward-slashed,
+which is the spelling the mention grammar and the prompt guidance already use
+for host paths). `formatMention` in the client half re-implements the shipped
+grammar — whitespace quotes the path, a quoted directory keeps its quote open
+so completion can descend, and control characters or an embedded quote make a
+path unrepresentable, so that row is dropped rather than inserted broken. The
+bundle is standalone (no build step) and cannot import that package's module,
+hence the re-implementation.
+
+### Client contribution
+
+| Decision | Reason |
+| -------- | ------ |
+| A **companion source** (`trigger: '@'`, `name: 'multi-folder'`), not a replacement | the registry keys sources by `(trigger, name)` and throws on a duplicate; the shipped `reference` source keeps answering untouched |
+| `order: 10` | the shipped group declares no order and defaults to `0`, so the secondary group sits below it |
+| `showGroupTitle: false` | the menu derives a group's title by looking its **source name** up in its own dictionary, so a visible title would read `multi-folder` — and an empty result would render that heading over an empty list |
+| A `section` on every row = the directory | rows are headed by the directory they came from, and the abbreviation of a path under the host home (`~`) keeps that heading readable |
+| `ctx.inject(['inputTriggers'], …)`, not a hard `inject` entry | a shell composing no trigger service must keep every panel surface; this contribution then simply never activates |
+| Own `codec` (identity) | `serializeReference` resolves the owner by **source name** and rejects a codec-less owner, so the source must own one even though the mention IS the model form |
+| Failures resolve to `[]` | discovery is advisory: it must never break the composer or the groups beside it |
+| Queries are per keystroke, like the shipped source | the host index makes each call an in-memory rank |
+
 ## Host: prompt injection and notifications
 
 - One global `systemPrompt.section` (`multi-folder:secondary-dirs`, order 160) whose
@@ -192,7 +296,11 @@ window.__ModuleLoader__.load({
 - `inject: ['remote', 'remote.commands', 'slots', 'workspaces', 'connection', 'sessions', 'locale']`; the package's
   `dsh.client.inject` lists the packages providing them
   (`@deepseek-ai/dsh-api-gateway`, `@deepseek-ai/dsh-api-remotes`,
-  `@deepseek-ai/dsh-client-connection`, `@deepseek-ai/dsh-client-locale`).
+  `@deepseek-ai/dsh-client-connection`, `@deepseek-ai/dsh-client-locale`,
+  `@deepseek-ai/dsh-client-ui-input-trigger`). The trigger registry is
+  deliberately **not** in that hard list: the `@` source is contributed through
+  `ctx.inject(['inputTriggers'], …)`, so shells without that service keep every
+  panel surface (see the `@` discovery section).
 - UI registrations: `conversation.session.header.actions` (session-scoped button),
   `shell.overlay` panel, `conversation.input.dock` chip row (session-scoped
   list entry above the composer card — the session-creation page's shipped
@@ -224,25 +332,33 @@ 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
+  `multiFolder/listFiles` over the shared RPC channel, and projects each
+  candidate onto a row — a `section` naming its directory, an in-directory
+  `description`, and a `value` carrying the mention the pick inserts. Directory
+  rows set `drill`, so the shipped drill gesture descends a level.
 - Session switch: a `React.useEffect` on `sessionId` re-points the open panel
   to the current session (reusing the per-session cache) — this also folds a
   workspace-mode panel back into session mode once the first message creates
@@ -375,6 +491,34 @@ window.__ModuleLoader__.load({
   business validation server-side. DSH versions that change the Typert
   registry contract would need this contribution revisited (the tests assert
   the descriptor shape).
+- `@` discovery is a **companion group, never a merged list**. The shipped
+  provider stays single-root, so a secondary file appears under the plugin's
+  own group and its mention is an ABSOLUTE path — a relative one could not
+  reach outside the workspace root. Consequences worth knowing: the workspace
+  file list and the secondary list are ranked separately (the shipped group's
+  relevance order never mixes with ours, and only the first 30 secondary
+  candidates of a query are offered), a session whose workspace has no
+  configured directories gains an empty group that renders nothing, and the
+  index is advisory by design — it is rebuilt lazily (4 s TTL) rather than
+  invalidated on every tool result, so a file created in a secondary directory
+  can take a few seconds to appear in the menu.
+- A **symlinked or junctioned level inside a configured directory is indexed and
+  listed through the link**, where the shipped provider skips symlinked
+  directories. The fs seam's `listDir` reports only an entry's `type`, so a link
+  is not distinguishable from a directory without a second canonicalization per
+  child — and rejecting on that basis would also reject junctions that are
+  ordinary project structure (and a secondary directory reached through a
+  junctioned ancestor). The walk stays bounded regardless: canonical-path
+  deduplication prevents a link from re-entering it, and `MAX_INDEX_ENTRIES`
+  caps it. Reads are unfenced in DSH, so this grants no access the plugin's own
+  directory browser does not already have.
+- The `@` group depends on the trigger registry's source contract
+  (`trigger`/`name`/`order`/`showGroupTitle`, `candidates`/`onPick`/`codec`,
+  candidate `section`/`icon`/`drill`, and the `(trigger, name)` uniqueness key).
+  A DSH release that changes that contract would need this contribution
+  revisited; because the registration rides `ctx.inject`, a release that drops
+  the service entirely degrades to "no `@` group" instead of breaking the
+  plugin's panel.
 
 ## Tests
 
@@ -397,3 +541,14 @@ shape, in-flow row, hero-only visibility, RPC routing, anchored popover), the
 upstream hero chip taking over the moment its slot is declared, and the fixed
 launcher returning once both declarations collapse — asserting at each step that
 the other two surfaces stand down.
+
+`@` discovery is covered on both halves against a fake secondary tree behind the
+`fs` seam: the host test asserts the empty-query entry points, bare-fragment
+ranking, directory-basename narrowing, level listing by both spellings,
+recursion, hidden-entry visibility, `node_modules` exclusion, index caching
+inside the TTL, the workspace fence, config-store isolation, and that clearing
+the configuration withdraws the surface; the client test asserts the source's
+identity/order/`showGroupTitle`, its RPC routing and keying, row projection
+(section heading, `~` abbreviation, in-directory description, drill flag,
+folder icon), quote handling, the pick inserts, the identity codec, and that
+both an unrepresentable path and an RPC failure degrade quietly.