dsh-multi-folder 0.3.1 → 0.3.2

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
@@ -65,6 +66,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:
@@ -84,6 +100,7 @@ When a shell run ends in such a denial and references a configured secondary dir
 - **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`).
+- **`@` 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 +108,8 @@ 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: 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 |
 | `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 级（会话级头部入口）。
 
 ## 环境要求
@@ -65,6 +66,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）。由此：
@@ -84,6 +100,7 @@ Agent 无需任何额外操作：`read` / `glob` / `grep` 随处可用；`write`
 - **配置与安全边界**——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`）。
+- **`@` 发现**——同一 `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 +108,8 @@ 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` | 宿主插件：配置存储、工具流水线拦截、提示词注入、双通道通知、`/multi-folder` 命令、无会话 `multiFolder/*` 远程 API（配置端点 + 自带浏览器用的 `browse`/`makeDir` + `@` 菜单用的 `listFiles`） |
+| `lib/client.js` | 客户端插件（factory bundle）：会话头部按钮 + 覆盖层面板 + 会话创建页入口（输入框上方的 dock 胶囊 / 上游 hero chip / 右下角兜底浮动按钮）+「添加目录」背后的自带目录浏览器 + 并列的 `@` source |
 | `test/` | 免 DSH 运行时的行为测试（见开发） |
 | `docs/` | 设计与分析文档 |
 

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
@@ -131,9 +151,12 @@ 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 }` |
 
-  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 +178,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 +294,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
@@ -243,6 +349,13 @@ window.__ModuleLoader__.load({
   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).
+- `@` 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 +488,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 +538,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.

package/lib/client.js

@@ -39,6 +39,17 @@
  * chooser worker, whose crash surfaces as `directory picker failed: … worker
  * exited …`.
  *
+ * `@` discovery for the configured directories. The shipped `@` menu is
+ * SINGLE-ROOT: `ui-reference` feeds it from `remote.fileReferences.list`, whose
+ * provider walks the addressed session's cwd and refuses every candidate
+ * outside that root, so a secondary directory can never appear there. This
+ * bundle therefore registers a COMPANION source on the same trigger (see "@
+ * discovery for secondaries" in `apply`) and answers it from
+ * `multiFolder/listFiles`. Sources are keyed by `(trigger, name)` and rendered
+ * one group each, so the shipped files/sessions group is untouched. The
+ * registration rides `ctx.inject` — a shell composing no input-trigger service
+ * keeps every panel surface and simply gains no `@` group.
+ *
  * Layout shape: an entry in the session header action row, one chip row above
  * the composer card on the session-creation page, and a frame-wide overlay
  * panel. Every surface reads one tiny module-scoped store; opening the panel
@@ -1361,6 +1372,154 @@ window.__ModuleLoader__.load({
           release();
         };
       });
+
+      // ------------------------------------- @ discovery for secondaries
+      // The shipped `@` menu is SINGLE-ROOT: `ui-reference` feeds it from
+      // `remote.fileReferences.list`, whose provider walks the addressed
+      // session's cwd and refuses any candidate outside that root. A configured
+      // secondary directory is by definition outside it, so this plugin
+      // registers a COMPANION source on the same trigger and answers it from
+      // `multiFolder/listFiles`.
+      //
+      // The trigger registry keys sources by `(trigger, name)` and renders one
+      // group per source, so the shipped files/sessions group is untouched and
+      // this group appears beside it (order 10 = below the shipped group, which
+      // defaults to 0). `showGroupTitle: false` is deliberate: 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 a group whose query found
+      // nothing would otherwise render that heading over an empty list. Every
+      // row instead carries a `section`, which heads the rows by directory.
+      //
+      // `ctx.inject` rather than a hard `inject` entry: a shell that composes
+      // no input-trigger service must keep its panel, and on such a shell this
+      // contribution simply never activates.
+
+      /** Last path segment, tolerant of either separator. */
+      function lastSegment(path) {
+        var parts = String(path).replace(/[\\/]+$/, '').split(/[\\/]/);
+        return parts.length === 0 ? '' : parts[parts.length - 1];
+      }
+
+      /** Drop the host home prefix from a heading when the path sits under it. */
+      function abbreviate(path) {
+        var home = remote && remote.$host ? remote.$host.home : undefined;
+        if (!home) return path;
+        var flat = String(path).replace(/\\/g, '/');
+        var prefix = String(home).replace(/\\/g, '/');
+        if (flat.toLowerCase().indexOf(prefix.toLowerCase()) !== 0) return path;
+        return '~' + flat.slice(prefix.length);
+      }
+
+      /** Mention text for one discovered path. Mirrors the shipped
+       *  `formatFileMention` grammar — whitespace quotes the path, a quoted
+       *  directory keeps its quote open so completion can descend, and a path
+       *  with control characters or an embedded quote is unrepresentable.
+       *  Reimplemented here because this bundle is standalone (no build step)
+       *  and cannot import that package's module. */
+      function formatMention(path, kind, preserveQuote) {
+        var text = kind === 'directory' ? path + '/' : path;
+        if (/[\u0000-\u001f\u007f-\u009f"]/.test(text)) return undefined;
+        if (!preserveQuote && !/\s/.test(text)) return '@' + text;
+        return kind === 'directory' ? '@"' + text : '@"' + text + '"';
+      }
+
+      /** The source-owned payload one menu row carries. */
+      function rowValue(value) {
+        if (typeof value !== 'string') return undefined;
+        try {
+          var parsed = JSON.parse(value);
+          return parsed && typeof parsed.mention === 'string' ? parsed : undefined;
+        } catch (e) {
+          return undefined;
+        }
+      }
+
+      /** Project one host candidate onto a menu row (or nothing when the path
+       *  cannot be written back as mention text). */
+      function fileRow(candidate, preserveQuote, heading) {
+        var path = String(candidate.path || '').replace(/\\/g, '/');
+        var kind = candidate.kind === 'directory' ? 'directory' : 'file';
+        var mention = formatMention(path, kind, preserveQuote);
+        if (mention === undefined) return [];
+        var rel = String(candidate.rel || '');
+        var name = rel === '' ? lastSegment(path) : lastSegment(rel);
+        var slash = rel.lastIndexOf('/');
+        var parent = slash < 0 ? '' : rel.slice(0, slash);
+        return [{
+          name: kind === 'directory' ? name + '/' : name,
+          // The in-directory location only: the heading above the row already
+          // names the directory, so repeating it there says nothing.
+          ...(parent === '' ? {} : { description: parent }),
+          icon: kind === 'directory' ? 'folder' : 'file',
+          section: heading,
+          value: JSON.stringify({ kind: kind, path: path, mention: mention }),
+          ...(kind === 'directory' ? { drill: true } : {}),
+        }];
+      }
+
+      ctx.inject(['inputTriggers'], function (scope) {
+        var registry = scope.inputTriggers;
+        if (!registry || typeof registry.registerSource !== 'function') return;
+        scope.effect(function () {
+          return registry.registerSource({
+            trigger: '@',
+            name: NS,
+            order: 10,
+            // The menu titles a group from its source name via its OWN
+            // dictionary (an unknown key renders verbatim), so the title row is
+            // switched off: rows are headed by their directory section instead,
+            // and an empty result renders nothing at all.
+            showGroupTitle: false,
+            candidates: function (session, request) {
+              var summary = sessions.list.getSnapshot().byId[session.sessionId];
+              var workspace = summary && summary.cwd;
+              if (!workspace) return Promise.resolve([]);
+              var preserveQuote = request.quoted === true;
+              return remoteCall('multiFolder/listFiles', { workspace: workspace, query: request.query }).then(
+                function (value) {
+                  var items = value && Array.isArray(value.candidates) ? value.candidates : [];
+                  var rows = [];
+                  for (var i = 0; i < items.length; i += 1) {
+                    var item = items[i];
+                    rows = rows.concat(fileRow(item, preserveQuote, abbreviate(String(item.dir || ''))));
+                  }
+                  return rows;
+                },
+                // Autocomplete is advisory: a discovery failure is an empty
+                // group, never a broken composer and never a failed send.
+                function () { return []; },
+              );
+            },
+            onPick: function (pick) {
+              var chosen = rowValue(pick.candidate.value);
+              if (chosen === undefined) return undefined;
+              var name = lastSegment(chosen.path);
+              // Tab / the row chevron refines the query in place instead of
+              // settling the pick, so a directory descends one level: the
+              // mention text becomes the live query, and the host resolves the
+              // absolute spelling it just produced.
+              if (chosen.kind === 'directory' && pick.action === 'drill') {
+                return { text: chosen.mention, continue: true };
+              }
+              return {
+                insert: {
+                  source: NS,
+                  ref: chosen.mention,
+                  label: chosen.kind === 'directory' ? name + '/' : name,
+                  appearance: chosen.kind === 'directory' ? 'folder' : 'file',
+                  clipboardText: chosen.mention,
+                },
+              };
+            },
+            // The mention IS the model form (an `@path` token the prompt
+            // grammar already defines), so serialization is the identity.
+            codec: {
+              clipboardText: function (ref) { return ref; },
+              serialize: function (ref) { return Promise.resolve(ref); },
+            },
+          });
+        }, 'dsh-multi-folder: @ discovery source');
+      });
     }
 
     exports.name = name;

package/lib/index.js

@@ -32,13 +32,16 @@
  *    Background shell runs (`run_in_background: true`) register with the
  *    generic jobs runtime (`ctx.jobs`) under the same re-rooted policy,
  *    mirroring the shipped pwsh/bash tools so `job_output` / `job_kill` and
- *    finish notices keep working. `shell.start` is ASYNC (it publishes the
- *    handle only once launch preparation, Windows ACL grants included,
- *    succeeded), so the launcher is adapted to the jobs runtime's synchronous
- *    hooks contract exactly like the shipped tools' `processJob`: the job-owned
- *    AbortSignal drives preparation cancellation and a rejected preparation
- *    settles the job as `failed`. Reads (read/glob/grep) are unfenced and
- *    already work.
+ *    finish notices keep working. The launch is ASYNC (the handle is published
+ *    only once launch preparation, Windows ACL grants included, succeeded), so
+ *    the launcher is adapted to the jobs runtime's synchronous hooks contract
+ *    exactly like the shipped tools' `processJob`: the job-owned AbortSignal
+ *    drives preparation cancellation and a rejected preparation settles the job
+ *    as `failed`. Reads (read/glob/grep) are unfenced and already work.
+ *    Both shell paths are addressed through the version-adaptive seam
+ *    {@link shellUsesExecute}: DSH 0.1.7-alpha.1 retired `shell.run` /
+ *    `shell.start` in favour of a single `execute()`, and turned
+ *    `JobSpec.owner` from the calling Agent into its SessionId.
  * 3. Prompt injection: one ordered system-prompt section rendered per
  *    assembly from the configured directories of the assembling session.
  * 4. Non-interrupting change notification: configuration changes made via
@@ -78,6 +81,14 @@
  *    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).
+ * 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
+ *    only and refuses candidates outside it — so secondary directories are
+ *    invisible to it. `multiFolder/listFiles` indexes them over the `fs` seam
+ *    instead, and the client half registers a companion `@` group fed by that
+ *    endpoint. The shipped provider is untouched: with no secondary
+ *    directories configured, behavior is exactly upstream's.
  */
 
 import { mkdir } from 'node:fs/promises'
@@ -102,6 +113,35 @@ const CONFIG_GUARD_TEXT =
   'This file is managed by the dsh-multi-folder plugin. Secondary working directories may only be ' +
   'configured by the user through the UI (session header or session-creation page) or the /multi-folder command; direct edits are rejected.'
 
+/**
+ * Which `ctx.shell` seam shape this DSH release exposes.
+ *
+ * DSH 0.1.7-alpha.1 (commit `d6bebc5783`, "converge on execute()") deleted BOTH
+ * `ShellExecutor.run` and `ShellExecutor.start` and replaced them with one
+ * `execute(spec): Promise<ShellExecution>`. `ShellExecution` extends
+ * `ShellProcess` (status/exitCode/signal/done/kill/readOutput/sandbox) and adds
+ * the foreground projection `result(): Promise<ShellRunResult>`, so the two old
+ * entry points map onto it exactly:
+ *
+ *   old `await shell.run(spec)`          -> `await (await shell.execute(spec)).result()`
+ *   old `proc = await shell.start(spec)` -> `proc = await shell.execute({ ...spec, onExpiry: 'none' })`
+ *                                           (the retired `start` armed no deadline,
+ *                                            while `resolve()` defaults `onExpiry` to `'kill'`)
+ *
+ * The same release changed `JobSpec.owner` from the calling `Agent` to its
+ * `SessionId`, and `jobs-local` now resolves that id through `agents.get(id)`
+ * (`session "[object Object]" has no live agent`). One probe therefore decides
+ * both shapes: an executor old enough to still require `run`/`start` also
+ * expects the Agent owner. The probe is the PRESENCE of `execute` — that method
+ * was introduced by the same commit that retired the other two, so it can never
+ * mean anything else — never the ABSENCE of `run`, so a release that keeps the
+ * retired methods as deprecated shims would still take the modern path.
+ *
+ * @param shell - the resolved `ctx.shell` service, or undefined without one.
+ * @returns true when the seam is the post-0.1.7 `execute()` contract.
+ */
+const shellUsesExecute = (shell) => shell !== undefined && typeof shell.execute === 'function'
+
 export function apply(ctx) {
   const { fs, sandboxPolicy, systemPrompt } = ctx
   // NOTE: shell, shellEnv, and commands are deliberately NOT captured here.
@@ -355,6 +395,289 @@ export function apply(ctx) {
     return { path: target, parent }
   }
 
+  // ------------------------------------- secondary-directory file discovery
+  // The shipped `@` file-reference menu is SINGLE-ROOT by construction: its
+  // provider (`dsh-file-reference-local`) builds one `WorkspaceFileSearch` per
+  // agent from `agent.session.header.cwd` and refuses every candidate outside
+  // that root (`resolveDisplayDirectory` answers undefined for a path that
+  // escapes it). A configured secondary directory is by definition outside the
+  // primary workspace, so the shipped menu cannot reach it — no upstream
+  // incompatibility, simply a scope the provider does not cover.
+  //
+  // This plugin therefore publishes its own discovery endpoint over the files
+  // it already has read access to (`fs.listDir`, the same seam the owned
+  // directory browser uses) and the client half registers a companion `@`
+  // group fed by it. Nothing here alters the shipped provider: a workspace with
+  // no secondary directories keeps exactly the upstream behavior, and the
+  // shipped group keeps answering on its own.
+
+  /**
+   * Directory basenames never traversed. Mirrors the shipped provider's
+   * defaults (`dsh-file-reference-local`): version-control and dependency
+   * stores plus build-output names whose generated files would otherwise
+   * spend the entry budget twice and rank beside their own sources. `lib` is
+   * deliberately absent there and therefore here.
+   */
+  const INDEX_EXCLUDED = new Set([
+    '.git', 'node_modules', 'dist', 'build', 'out', 'coverage', 'target',
+    '.next', '.nuxt', '.turbo', '.venv', '__pycache__', '.pytest_cache',
+    '.mypy_cache', '.gradle',
+  ])
+  /** Entries retained per workspace across every configured directory. */
+  const MAX_INDEX_ENTRIES = 20000
+  /** Entries retained for one level listing. */
+  const MAX_LEVEL_ENTRIES = 500
+  /** Candidates one query returns. */
+  const MAX_FILE_RESULTS = 30
+  /**
+   * How long one workspace's index answers before the next query rebuilds it.
+   * Autocomplete is advisory, so a few seconds of staleness is invisible while
+   * it bounds rebuild cost to one traversal per window — a config change is
+   * caught immediately instead, by the directory signature.
+   */
+  const FILE_INDEX_TTL_MS = 4000
+  /** wsKey(workspace) -> { sig, builtAt, entries } */
+  const filesCache = new Map()
+
+  const lastSegment = (p) => {
+    const parts = String(p).replace(/[\\/]+$/, '').split(/[\\/]/)
+    return parts.length === 0 ? '' : parts[parts.length - 1]
+  }
+  /** Absolute path in the forward-slash spelling the mention grammar carries. */
+  const slashed = (p) => String(p).replace(/\\/g, '/')
+
+  /**
+   * Index one workspace's secondary directories: breadth-first, canonical-path
+   * deduplicated (a junction/symlink pointing back up the tree cannot re-enter
+   * the walk), excluding `INDEX_EXCLUDED` basenames, bounded by
+   * `MAX_INDEX_ENTRIES` across all directories.
+   * @param dirs - configured secondary directories.
+   * @returns entries as `{ dir, rel, kind }`, `rel` forward-slashed inside `dir`.
+   */
+  const scanFiles = async (dirs) => {
+    const entries = []
+    const visited = new Set()
+    for (const dir of dirs) {
+      const queue = [{ abs: dir, rel: '' }]
+      for (let cursor = 0; cursor < queue.length && entries.length < MAX_INDEX_ENTRIES; cursor += 1) {
+        const level = queue[cursor]
+        let target
+        let absolute
+        try {
+          target = await fs.resolve(level.abs)
+          absolute = fs.processPath(target)
+        } catch {
+          continue // an unresolvable level contributes nothing
+        }
+        const canonical = wsKey(absolute)
+        if (visited.has(canonical)) continue
+        visited.add(canonical)
+        let children
+        try {
+          children = await fs.listDir(target)
+        } catch {
+          continue // an unreadable branch costs its own entries; the rest stay useful
+        }
+        const api = pathApiFor(absolute)
+        for (const child of children ?? []) {
+          if (child === null || child === undefined) continue
+          const childName = String(child.name)
+          const rel = level.rel === '' ? childName : level.rel + '/' + childName
+          if (child.type === 'directory') {
+            if (INDEX_EXCLUDED.has(childName)) continue
+            entries.push({ dir, rel, kind: 'directory' })
+            queue.push({ abs: api.join(absolute, childName), rel })
+          } else if (child.type === 'file') {
+            entries.push({ dir, rel, kind: 'file' })
+          }
+          if (entries.length >= MAX_INDEX_ENTRIES) break
+        }
+      }
+    }
+    return entries
+  }
+
+  /** One workspace's index, rebuilt when its directory set changes or the TTL lapses. */
+  const indexFor = async (ws, dirs) => {
+    const key = wsKey(ws)
+    const sig = dirs.map(wsKey).join('|')
+    const cached = filesCache.get(key)
+    if (cached !== undefined && cached.sig === sig && Date.now() - cached.builtAt < FILE_INDEX_TTL_MS) {
+      return cached.entries
+    }
+    const entries = await scanFiles(dirs)
+    filesCache.set(key, { sig, builtAt: Date.now(), entries })
+    return entries
+  }
+
+  /** Longest common subsequence gap score, mirroring the shipped provider. */
+  const subsequenceScore = (target, needle) => {
+    let at = 0
+    let gap = 0
+    for (const character of needle) {
+      const found = target.indexOf(character, at)
+      if (found < 0) return undefined
+      gap += found - at
+      at = found + 1
+    }
+    return Math.max(0, 100 - gap)
+  }
+
+  /**
+   * Score one entry against a query. Ranking mirrors the shipped provider
+   * (name beat path, directories win ties) with ONE deliberate deviation: the
+   * path/path-subsequence rules read the IN-DIRECTORY relative path, never the
+   * absolute one. Every absolute path shares the host prefix (`D:/…`), so
+   * scoring it would make a one-character query match every candidate. The
+   * directory's own basename stays searchable at the lowest precedence, which
+   * is what lets `@secondary-spike` narrow to that directory.
+   */
+  const scoreEntry = (entry, needle) => {
+    if (needle === '') return 0
+    const rel = entry.rel.toLowerCase()
+    const name = lastSegment(rel).toLowerCase()
+    const bonus = entry.kind === 'directory' ? 25 : 0
+    if (name === needle) return 1000 + bonus
+    if (name.startsWith(needle)) return 900 + bonus
+    if (name.includes(needle)) return 700 + bonus
+    if (rel.includes(needle)) return 500 + bonus
+    const sub = subsequenceScore(rel, needle)
+    if (sub !== undefined) return 300 + sub + bonus
+    if (lastSegment(entry.dir).toLowerCase().includes(needle)) return 200 + bonus
+    return undefined
+  }
+
+  /** Rank entries deterministically and project the wire shape. */
+  const rankEntries = (entries, query) => {
+    const needle = query.toLowerCase()
+    const ranked = []
+    for (const entry of entries) {
+      const score = scoreEntry(entry, needle)
+      if (score !== undefined) ranked.push({ entry, score })
+    }
+    ranked.sort((left, right) =>
+      right.score - left.score
+      || (left.entry.kind === right.entry.kind ? 0 : left.entry.kind === 'directory' ? -1 : 1)
+      || (needle === '' ? 0 : left.entry.rel.length - right.entry.rel.length)
+      || (left.entry.rel < right.entry.rel ? -1 : left.entry.rel > right.entry.rel ? 1 : 0))
+    return ranked.slice(0, MAX_FILE_RESULTS).map(({ entry }) => ({
+      path: entry.rel === '' ? slashed(entry.dir) : slashed(entry.dir) + '/' + entry.rel,
+      kind: entry.kind,
+      dir: entry.dir,
+      rel: entry.rel,
+    }))
+  }
+
+  /**
+   * Decode the in-directory part of a level query into a normalized relative
+   * path, or reject it. `.` and empty segments are normalized away, and ANY
+   * `..` segment is refused: without that, `@secondary/../../etc/` would list a
+   * directory outside every configured root while still claiming the configured
+   * directory as its owner — a candidate whose `dir` field lies, and a level
+   * listing that escaped the set the user actually granted. The shipped
+   * provider refuses the same escape for the same reason.
+   * @returns the normalized relative path, or null when the query escapes.
+   */
+  const decodeInside = (inside) => {
+    const segments = String(inside).split('/').filter((segment) => segment !== '' && segment !== '.')
+    return segments.includes('..') ? null : segments.join('/')
+  }
+
+  /**
+   * Resolve the directory part of a query to `(configured dir, in-dir path)`.
+   * Two spellings are accepted: a fully qualified path inside a configured
+   * directory (what a drill inserts), and a path whose first segment names a
+   * configured directory by basename (`@secondary-spike/src/`). An ambiguous
+   * basename (two configured directories sharing one) is refused, never
+   * guessed.
+   * @returns the resolved level, or null when the query names no configured directory.
+   */
+  const resolveLevel = (dirs, directory) => {
+    const trimmed = String(directory).replace(/\/+$/, '')
+    if (trimmed === '') return null
+    const query = slashed(trimmed).toLowerCase()
+    if (fullyQualified(trimmed)) {
+      for (const dir of longestRootFirst(dirs)) {
+        const root = slashed(dir).toLowerCase()
+        if (query === root) return { dir, inside: '' }
+        if (query.startsWith(root + '/')) {
+          const inside = decodeInside(slashed(trimmed).slice(slashed(dir).length + 1))
+          return inside === null ? null : { dir, inside }
+        }
+      }
+      return null
+    }
+    const cut = trimmed.indexOf('/')
+    const head = cut < 0 ? trimmed : trimmed.slice(0, cut)
+    const inside = decodeInside(cut < 0 ? '' : trimmed.slice(cut + 1))
+    if (inside === null) return null
+    const matches = dirs.filter((dir) => lastSegment(dir).toLowerCase() === head.toLowerCase())
+    if (matches.length !== 1) return null
+    return { dir: matches[0], inside }
+  }
+
+  /** List one level of a configured secondary directory (files and directories). */
+  const listLevel = async (dirs, directory, fragment) => {
+    const empty = { candidates: [], truncated: false }
+    const level = resolveLevel(dirs, directory)
+    if (level === null) return empty
+    const absolute = level.inside === '' ? level.dir : pathApiFor(level.dir).join(level.dir, ...level.inside.split('/'))
+    let children
+    try {
+      children = await fs.listDir(await fs.resolve(absolute))
+    } catch {
+      return empty
+    }
+    const shown = []
+    for (const child of children ?? []) {
+      if (child === null || child === undefined) continue
+      const childName = String(child.name)
+      const kind = child.type === 'directory' ? 'directory' : child.type === 'file' ? 'file' : null
+      if (kind === null) continue
+      if (kind === 'directory' && INDEX_EXCLUDED.has(childName)) continue
+      // Hidden entries stay reachable by asking for them explicitly, exactly
+      // like the shipped provider (and this plugin's own directory browser).
+      if (childName.startsWith('.') && !fragment.startsWith('.')) continue
+      shown.push({ dir: level.dir, rel: level.inside === '' ? childName : level.inside + '/' + childName, kind })
+    }
+    const truncated = shown.length > MAX_LEVEL_ENTRIES
+    if (truncated) shown.length = MAX_LEVEL_ENTRIES
+    return { candidates: rankEntries(shown, fragment), truncated }
+  }
+
+  /**
+   * Discover candidates for one `@` query across a workspace's configured
+   * secondary directories. An empty query yields the directories themselves
+   * (the menu's entry points); a query carrying a separator lists that level;
+   * a bare fragment fuzzy-ranks the index.
+   * @param ws - primary workspace path (configuration key).
+   * @param query - path text following `@` or `@"`.
+   * @returns the workspace, its configured directories, and the ranked candidates.
+   */
+  const coreListFiles = async (ws, query) => {
+    ws = requireWorkspace(ws)
+    const entry = await loadDirs(ws)
+    const dirs = [...entry.dirs]
+    const out = { workspace: ws, dirs, candidates: [], truncated: false }
+    if (dirs.length === 0) return out
+    const q = typeof query === 'string' ? query.replace(/\\/g, '/') : ''
+    if (q === '') {
+      out.candidates = dirs.map((dir) => ({ path: slashed(dir), kind: 'directory', dir, rel: '' }))
+      return out
+    }
+    const slash = q.lastIndexOf('/')
+    if (slash >= 0) {
+      const level = await listLevel(dirs, q.slice(0, slash + 1), q.slice(slash + 1))
+      out.candidates = level.candidates
+      out.truncated = level.truncated
+      return out
+    }
+    const index = await indexFor(ws, dirs)
+    const visible = q.startsWith('.') ? index : index.filter((item) => !item.rel.split('/').some((segment) => segment.startsWith('.')))
+    out.candidates = rankEntries(visible, q)
+    return out
+  }
+
   // ----------------------------------------------- sessionless remote API
   // `multiFolder/*` endpoints over the Typert gateway. Hand-written
   // `src-json` descriptors registered through ctx.typert.register (the
@@ -408,6 +731,13 @@ export function apply(ctx) {
         throw new Error(remoteErrorMessage(e))
       }
     },
+    async listFiles(workspace, query) {
+      try {
+        return await coreListFiles(workspace, query)
+      } catch (e) {
+        throw new Error(remoteErrorMessage(e))
+      }
+    },
   }
   Object.defineProperty(multiFolderApi, 'typertRemote', {
     value: Object.freeze({
@@ -439,6 +769,7 @@ export function apply(ctx) {
       remoteInvocation('set', ['workspace', 'dirs']),
       remoteInvocation('browse', ['path']),
       remoteInvocation('makeDir', ['parent', 'name']),
+      remoteInvocation('listFiles', ['workspace', 'query']),
     ],
   }
 
@@ -665,24 +996,34 @@ export function apply(ctx) {
    * Adapt one asynchronous background launch to the jobs runtime's SYNCHRONOUS
    * hooks contract, mirroring the shipped pwsh/bash tools' `processJob`.
    *
-   * `shell.start` is ASYNC — it resolves the process handle only after launch
-   * preparation (Windows ACL grants included) and rejects when preparation is
-   * cancelled or fails — so the handle can never be dereferenced from `run()`.
-   * Calling it as if it returned a process made every background run in a
-   * secondary directory fail immediately with
+   * The launch is ASYNC in every supported release — it resolves the process
+   * handle only after launch preparation (Windows ACL grants included) and
+   * rejects when preparation is cancelled or fails — so the handle can never be
+   * dereferenced from `run()`. Treating it as synchronous made every background
+   * run in a secondary directory fail immediately with
    * `Cannot read properties of undefined (reading 'then')` (`proc.done` read
    * off the un-awaited promise). The job-owned AbortSignal travels into
    * `shell.resolve`, so `cancel` stops a launch that has not published a handle
    * yet, and a rejected preparation settles the job as `failed` instead of
    * leaving it running forever. A background process outlives the tool call, so
-   * no CALLER signal is forwarded; `shell.start` ignores `timeoutMs` by design.
+   * no CALLER signal is forwarded, and it must not inherit a deadline:
+   * `onExpiry: 'none'` is what makes the post-0.1.7 `execute()` path ignore
+   * `timeoutMs`, which the retired `start()` did by construction. Without it a
+   * background command would be killed at the executor's default timeout — a
+   * silent behavior regression the shipped tools avoid the same way.
    */
   const startBackgroundJob = (shell, request) => {
     const controller = new AbortController()
+    const modern = shellUsesExecute(shell)
     let proc
     const done = (async () => {
       try {
-        proc = await shell.start(shell.resolve({ ...request, signal: controller.signal }))
+        const spec = shell.resolve({
+          ...request,
+          signal: controller.signal,
+          ...(modern ? { onExpiry: 'none' } : {}),
+        })
+        proc = modern ? await shell.execute(spec) : await shell.start(spec)
         try {
           if (controller.signal.aborted) proc.kill()
         } finally {
@@ -889,6 +1230,7 @@ export function apply(ctx) {
       if (exec.name === 'pwsh' || exec.name === 'bash') {
         const shell = ctx.get('shell')
         if (shell === undefined) return next()
+        const modernShell = shellUsesExecute(shell)
         if (dirs === null) return next()
         const rawWorkdir = args && typeof args.workdir === 'string' ? args.workdir : null
         const joined = rawWorkdir === null
@@ -923,10 +1265,16 @@ export function apply(ctx) {
           const jobs = ctx.get('jobs')
           if (jobs === undefined) return next()
           owned = { policy }
+          // `JobSpec.owner` is the owner's SessionId since 0.1.7-alpha.1
+          // (`jobs-local` resolves it through `agents.get(id)`); the older seam
+          // took the Agent itself. Passing the wrong shape throws
+          // `session "[object Object]" has no live agent` and the background run
+          // never starts. `Agent.id` IS the session id, which is the spelling
+          // the shipped pwsh/bash tools register with.
           const jobId = jobs.start({
             kind: exec.name,
             label: String(args.command),
-            ...(exec.agent ? { owner: exec.agent } : {}),
+            ...(exec.agent ? { owner: modernShell ? exec.agent.id : exec.agent } : {}),
             run: () => startBackgroundJob(shell, request),
           })
           return {
@@ -937,7 +1285,12 @@ export function apply(ctx) {
         }
 
         owned = { policy }
-        const result = await shell.run(shell.resolve({ ...request, signal: exec.signal }))
+        // One call site, two release shapes: 0.1.7-alpha.1 replaced
+        // `shell.run(spec)` with `execute(spec)` + the handle's foreground
+        // projection `result()`. See {@link shellUsesExecute}.
+        const result = modernShell
+          ? await (await shell.execute(shell.resolve({ ...request, signal: exec.signal }))).result()
+          : await shell.run(shell.resolve({ ...request, signal: exec.signal }))
         if (result.aborted) {
           return {
             isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-multi-folder",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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",
@@ -62,7 +62,8 @@
         "@deepseek-ai/dsh-api-gateway",
         "@deepseek-ai/dsh-api-remotes",
         "@deepseek-ai/dsh-client-connection",
-        "@deepseek-ai/dsh-client-locale"
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-input-trigger"
       ]
     }
   },