dsh-multi-folder 0.3.1 → 0.3.3

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