mixdog 0.8.0 → 0.9.0

package/src/standalone/explore-tool.mjs

@@ -1,38 +1,25 @@
 import { isAbsolute, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import {
-  TOOL_ASYNC_EXECUTION_CONTRACT,
-  TOOL_SYNC_EXECUTION_CONTRACT,
-  cancelBackgroundTask,
-  executionModeSchemaDescription,
-  getBackgroundTask,
-  renderBackgroundTask,
-  renderBackgroundTaskList,
-  resolveExecutionMode,
-  startBackgroundTask,
-  taskIdFromArgs,
-} from '../runtime/shared/background-tasks.mjs';
-import { makeBridgeLlm } from '../runtime/agent/orchestrator/smart-bridge/bridge-llm.mjs';
+import { makeAgentDispatch } from '../runtime/agent/orchestrator/agent-runtime/agent-dispatch.mjs';
+import { loadConfig } from '../runtime/agent/orchestrator/config.mjs';
+import { initProviders } from '../runtime/agent/orchestrator/providers/registry.mjs';
+import { presentErrorText } from '../runtime/shared/err-text.mjs';
 
 // Ported from the original mixdog tool-defs.mjs `explore` entry.
 // `aiWrapped` is dropped: in the standalone build there is no aiWrapped
 // dispatch hub — execution is wired directly in the runtime executor below
-// via makeBridgeLlm. The standalone surface is synchronous: it returns a
+// via makeAgentDispatch. The standalone surface is synchronous: it returns a
 // bounded locator result in this tool call.
 export const EXPLORE_TOOL = {
   name: 'explore',
   title: 'Explore',
   annotations: { title: 'Explore', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-  description: `Broad-scope locator only; returns unverified leads. Prefer mode=async for broad exploration that can continue in parallel; use sync only when the next step must block on this locator result. ${TOOL_SYNC_EXECUTION_CONTRACT} ${TOOL_ASYNC_EXECUTION_CONTRACT} Use code_graph/grep/glob first when any symbol, term, file kind, or config clue exists. Use explore only after direct narrowing fails or topics are unrelated. One short location question.`,
+  description: 'Repo anchor locator. Use for broad/uncertain paths. Array only for independent targets.',
   inputSchema: {
     type: 'object',
     properties: {
-      query: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'One short location question, or an array only for unrelated topics. Do not use for a known symbol/term/config key; use code_graph/grep first. Never pass a whole brief/context dump.' },
-      cwd: { type: 'string', description: 'Project/root directory to explore; narrow to the relevant repo or subtree.' },
-      mode: { type: 'string', enum: ['async', 'sync'], description: `${executionModeSchemaDescription('sync')} Prefer async for non-trivial exploration; choose sync only for an explicit blocking lookup.` },
-      action: { type: 'string', enum: ['run', 'list', 'status', 'read', 'cancel'], description: 'Default run. list/status/read/cancel are manual recovery controls for async explore tasks.' },
-      task_id: { type: 'string', description: 'Shared background task id for manual status/read/cancel recovery.' },
-      background: { type: 'boolean', description: 'Legacy alias for mode=async.' },
+        query: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Narrow locator query; array only for independent targets.' },
+      cwd: { type: 'string', description: 'Project/root directory.' },
     },
     required: [],
     additionalProperties: false,
@@ -46,6 +33,12 @@ export const EXPLORE_OUTPUT_CHAR_CAP = 24_000;
 const EXPLORE_TRUNCATION_MARKER = '\n\n[explore: output truncated; narrow cwd or split queries to see more]';
 // Bound fan-out so a hostile/poisoned query array cannot spawn unbounded subs.
 export const MAX_FANOUT_QUERIES = 8;
+const EXPLORE_RESULT_CACHE_MAX_ENTRIES = 64;
+const EXPLORE_RESULT_CACHE_TTL_MS = (() => {
+  const raw = Number(process.env.MIXDOG_EXPLORE_RESULT_CACHE_TTL_MS);
+  return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : 5 * 60_000;
+})();
+const EXPLORE_RESULT_CACHE = new Map(); // key -> { ts, value?, promise? }
 
 function escapeXml(str) {
   return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -54,9 +47,9 @@ function escapeXml(str) {
 // Mirrors buildExplorerPrompt from the original ai-wrapped-dispatch: each
 // explorer receives ONLY its own query, with a trailing descriptive-only
 // reminder. The full no-verdict contract lives at system level
-// (rules/bridge/30-explorer.md).
+// (rules/agent/30-explorer.md).
 export function buildExplorerPrompt(query) {
-  return `<query>${escapeXml(query)}</query>\nReminder: describe with file:line evidence; no verdicts, ratings, or recommendations.`;
+  return `<query>${escapeXml(query)}</query>\nReminder: output only anchor lines formatted as path:line — symbol/name — short reason, or EXPLORATION_FAILED. No preamble, bullets, numbering, headings, summary, code quotes, analysis, verdicts, ratings, or recommendations.`;
 }
 
 export function normalizeExploreQueries(rawQuery) {
@@ -91,11 +84,28 @@ function settledExplorerResult(result) {
   if (result?.status !== 'fulfilled') {
     return { ok: false, text: `[explorer error] ${result?.reason?.message || String(result?.reason)}` };
   }
-  const text = typeof result.value === 'string' ? result.value.trim() : responseText(result.value).trim();
+  const text = cleanExplorerText(typeof result.value === 'string' ? result.value : responseText(result.value));
   if (!text) return { ok: false, text: '[explorer error] empty response' };
   return { ok: true, text };
 }
 
+function isFatalExploreError(error) {
+  if (!error) return false;
+  const status = Number(error.httpStatus || error.status || error.response?.status || 0) || 0;
+  if (status === 401 || status === 403 || status === 429) return true;
+  if (error.providerQuota === true || error.quotaExceeded === true) return true;
+  const code = String(error.code || '').toUpperCase();
+  if (code === 'PROVIDER_QUOTA' || code === 'EACCES' || code === 'EAUTH') return true;
+  const name = String(error.name || '');
+  if (/ProviderQuotaError|Auth|Authentication|Permission/i.test(name)) return true;
+  const text = String(error.message || error.reason || error || '');
+  return /\b(?:quota|quota_exceeded|insufficient_quota|rate[_ -]?limit|too many requests|resource exhausted|unauthorized|authentication|forbidden|permission denied|invalid api key|token expired)\b/i.test(text);
+}
+
+function fatalExploreError(settled) {
+  return (settled || []).find((r) => r?.status === 'rejected' && isFatalExploreError(r.reason))?.reason || null;
+}
+
 function mergeSettled(settled, queries) {
   const single = queries.length === 1;
   if (single) {
@@ -109,7 +119,7 @@ function mergeSettled(settled, queries) {
   const sep = '\n\n';
   let truncated = false;
   for (let i = 0; i < settled.length; i++) {
-    const header = `## Q${i + 1}: ${String(queries[i] ?? '').replace(/\s+/g, ' ').slice(0, 60)}`;
+    const header = `Q${i + 1}: ${String(queries[i] ?? '').replace(/\s+/g, ' ').slice(0, 60)}`;
     const { text: body } = settledExplorerResult(settled[i]);
     const piece = `${header}\n${body}`;
     const addLen = (parts.length === 0 ? 0 : sep.length) + piece.length;
@@ -138,6 +148,90 @@ function clean(value) {
   return String(value ?? '').trim();
 }
 
+function exploreResultCacheEnabled() {
+  return EXPLORE_RESULT_CACHE_TTL_MS > 0
+    && !/^(?:0|false|off|no)$/i.test(String(process.env.MIXDOG_EXPLORE_RESULT_CACHE || '1'));
+}
+
+function exploreResultCacheKey({ cwd, presetName, query }) {
+  return JSON.stringify({
+    cwd: String(cwd || ''),
+    presetName: String(presetName || ''),
+    query: String(query || ''),
+  });
+}
+
+function findConfigPreset(config, presetName) {
+  const wanted = clean(presetName);
+  if (!wanted) return null;
+  return (Array.isArray(config?.presets) ? config.presets : [])
+    .find((preset) => clean(preset?.id) === wanted || clean(preset?.name) === wanted)
+    || null;
+}
+
+async function ensureExploreProviderReady(config) {
+  const preset = findConfigPreset(config, config?.maintenance?.explore);
+  const provider = clean(preset?.provider);
+  if (!provider) return;
+  const providers = { ...(config?.providers || {}) };
+  providers[provider] = { ...(providers[provider] || {}), enabled: true };
+  await initProviders(providers);
+}
+
+function scheduleExploreCodeGraphPrewarm(cwd) {
+  if (/^(?:1|true|on|yes)$/i.test(String(process.env.MIXDOG_DISABLE_EXPLORE_CODE_GRAPH_PREWARM || ''))) return;
+  void import('../runtime/agent/orchestrator/tools/code-graph.mjs')
+    .then((mod) => mod?.prewarmCodeGraphIfProject?.(cwd))
+    .catch(() => { /* best-effort */ });
+}
+
+function getCachedExploreResult(key) {
+  if (!exploreResultCacheEnabled()) return null;
+  const entry = EXPLORE_RESULT_CACHE.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.ts > EXPLORE_RESULT_CACHE_TTL_MS) {
+    EXPLORE_RESULT_CACHE.delete(key);
+    return null;
+  }
+  if (typeof entry.value === 'string') {
+    EXPLORE_RESULT_CACHE.delete(key);
+    EXPLORE_RESULT_CACHE.set(key, entry);
+    return entry.value;
+  }
+  return null;
+}
+
+async function runExploreCached(key, compute) {
+  const cached = getCachedExploreResult(key);
+  if (cached !== null) return cached;
+  if (!exploreResultCacheEnabled()) return await compute();
+  const pending = EXPLORE_RESULT_CACHE.get(key)?.promise;
+  if (pending) return await pending;
+  const promise = Promise.resolve()
+    .then(() => compute())
+    .then((value) => {
+      const text = typeof value === 'string' ? value : responseText(value);
+      const cleaned = cleanExplorerText(text);
+      if (cleaned && cleaned !== 'EXPLORATION_FAILED') {
+        EXPLORE_RESULT_CACHE.set(key, { ts: Date.now(), value: text });
+        while (EXPLORE_RESULT_CACHE.size > EXPLORE_RESULT_CACHE_MAX_ENTRIES) {
+          const oldest = EXPLORE_RESULT_CACHE.keys().next().value;
+          if (!oldest) break;
+          EXPLORE_RESULT_CACHE.delete(oldest);
+        }
+      } else {
+        EXPLORE_RESULT_CACHE.delete(key);
+      }
+      return value;
+    })
+    .catch((err) => {
+      EXPLORE_RESULT_CACHE.delete(key);
+      throw err;
+    });
+  EXPLORE_RESULT_CACHE.set(key, { ts: Date.now(), promise });
+  return await promise;
+}
+
 function responseText(response) {
   if (typeof response === 'string') return response;
   const parts = Array.isArray(response?.content) ? response.content : [];
@@ -148,57 +242,49 @@ function responseText(response) {
   return text || JSON.stringify(response, null, 2);
 }
 
-function controlExploreTask(action, args, ctx = {}) {
-  if (action === 'list') return ok(renderBackgroundTaskList({ surface: 'explore', context: ctx }));
-  const taskId = taskIdFromArgs(args);
-  if (!taskId) return fail('task_id is required');
-  const task = getBackgroundTask(taskId, { surface: 'explore', context: ctx });
-  if (!task) return fail(`task not found: ${taskId}`);
-  if (action === 'cancel') {
-    cancelBackgroundTask(taskId, 'cancelled by explore control');
-    return ok(renderBackgroundTask(task, { includeResult: true }));
+const ANCHOR_LINE_RE = /(?:^|\s)(?:[A-Za-z]:[\\/][^:\n]+|\.{0,2}[\\/][^:\n]+|src[\\/][^:\n]+|[\w.-]+[\\/][^:\n]+):\d+\b/;
+const FAILED_RE = /\b(?:EXPLORATION_FAILED|exploration failed|no credible (?:anchor|location)|no relevant (?:anchor|location)|not found|could(?: not|n't) find)\b/i;
+
+function normalizeExplorerLine(line) {
+  return String(line || '')
+    .trim()
+    .replace(/^[-*•]\s+/, '')
+    .replace(/^\d+[.)]\s+/, '')
+    .replace(/^>\s*/, '')
+    .replace(/`/g, '')
+    .replace(/\*\*/g, '')
+    .trim();
+}
+
+function cleanExplorerText(text) {
+  const raw = String(text || '').trim();
+  if (!raw) return '';
+  const anchors = [];
+  for (const sourceLine of raw.split(/\r?\n/)) {
+    const line = normalizeExplorerLine(sourceLine);
+    if (!line || /^-{3,}$/.test(line) || /^#+\s+/.test(line)) continue;
+    if (/^EXPLORATION_FAILED\b/i.test(line)) return 'EXPLORATION_FAILED';
+    if (ANCHOR_LINE_RE.test(line)) anchors.push(line);
   }
-  return ok(renderBackgroundTask(task, { includeResult: action === 'read' }));
+  if (anchors.length) return anchors.join('\n');
+  if (FAILED_RE.test(raw)) return 'EXPLORATION_FAILED';
+  return raw;
 }
 
 /**
  * Standalone explore executor.
  *
  * Dispatches the hidden `explorer` read-only filesystem role (one ephemeral
- * sub-session per query) via makeBridgeLlm — the same path recall/search-style
+ * sub-session per query) via makeAgentDispatch — the same path recall/search-style
  * hidden roles use. Runs query items concurrently (Promise.allSettled), then
  * aggregates the findings into one bounded text result.
  *
- * Runs synchronously by default. With mode=async/background:true, registers a
- * shared background task and delivers completion to the owner session.
+ * Runs synchronously and returns the bounded locator result in this tool call.
  *
- * @param {object} args         — tool args ({ query, cwd, background }).
+ * @param {object} args         — tool args ({ query, cwd }).
  * @param {object} ctx          — { callerCwd, callerSessionId }.
  */
 export async function runExplore(args = {}, ctx = {}) {
-  const action = clean(args.action || 'run').toLowerCase();
-  if (['list', 'status', 'read', 'cancel'].includes(action)) return controlExploreTask(action, args, ctx);
-
-  const mode = resolveExecutionMode(args, 'sync');
-  if (mode === 'async') {
-    const queries = normalizeExploreQueries(args.query);
-    if (queries.length === 0) return fail('query is required (one or more non-empty strings)');
-    const task = startBackgroundTask({
-      surface: 'explore',
-      operation: 'explore',
-      label: queries[0].replace(/\s+/g, ' ').slice(0, 120),
-      input: { query: args.query, cwd: args.cwd || null },
-      context: ctx,
-      resultType: 'explore_task_result',
-      renderResult: responseText,
-      run: async () => {
-        const response = await runExploreSync(args, ctx);
-        if (response?.isError) throw new Error(responseText(response));
-        return response;
-      },
-    });
-    return ok(renderBackgroundTask(task));
-  }
   return runExploreSync(args, ctx);
 }
 
@@ -214,18 +300,27 @@ async function runExploreSync(args = {}, ctx = {}) {
   }
 
   const resolvedCwd = resolveExploreCwd(args.cwd, ctx.callerCwd);
+  scheduleExploreCodeGraphPrewarm(resolvedCwd);
+  const config = loadConfig();
+  await ensureExploreProviderReady(config);
+  const presetName = config?.maintenance?.explore || '';
+  const llm = makeAgentDispatch({
+    role: 'explorer',
+    cwd: resolvedCwd,
+    brief: true,
+    parentSessionId: ctx.callerSessionId || null,
+    clientHostPid: ctx.clientHostPid || null,
+    config,
+  });
 
   const settled = await Promise.allSettled(working.map((q) => {
-    const llm = makeBridgeLlm({
-      role: 'explorer',
-      cwd: resolvedCwd,
-      brief: true,
-      parentSessionId: ctx.callerSessionId || null,
-      clientHostPid: ctx.clientHostPid || null,
-    });
-    return llm({ prompt: buildExplorerPrompt(q) });
+    const key = exploreResultCacheKey({ cwd: resolvedCwd, presetName, query: q });
+    return runExploreCached(key, () => llm({ prompt: buildExplorerPrompt(q) }));
   }));
 
+  const fatal = fatalExploreError(settled);
+  if (fatal) return fail(presentErrorText(fatal, { surface: 'explore' }));
+
   const merged = mergeSettled(settled, working);
   const allFailed = settled.every((r) => !settledExplorerResult(r).ok);
   const out = capNotice + merged;

package/src/standalone/folder-dialog.mjs

@@ -0,0 +1,314 @@
+/**
+ * standalone/folder-dialog.mjs — cross-platform native "choose folder" dialog.
+ *
+ * Spawns the OS-native directory picker and resolves with the selected absolute
+ * path, or null when the user cancels / no dialog tool is available. The TUI
+ * falls back to manual path typing when this returns { available:false }.
+ *
+ *   Windows : PowerShell IFileOpenDialog (Explorer-style folder picker)
+ *   macOS   : osascript `choose folder`
+ *   Linux   : zenity --file-selection --directory  (fallback: kdialog)
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+const DIALOG_TIMEOUT_MS = 5 * 60 * 1000;
+
+/** Run a command, capture stdout, resolve { code, stdout }. Never rejects. */
+function runCapture(cmd, args, { timeoutMs = DIALOG_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+    } catch (error) {
+      resolve({ ok: false, code: -1, stdout: '', error });
+      return;
+    }
+    let stdout = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try { child.kill(); } catch { /* ignore */ }
+      resolve({ ok: false, code: -1, stdout: '', error: new Error('dialog timed out') });
+    }, timeoutMs);
+    timer.unref?.();
+    child.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+    child.on('error', (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: false, code: -1, stdout: '', error });
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: code === 0, code, stdout });
+    });
+  });
+}
+
+// Sentinel: runCapture sets code === -1 ONLY for spawn failures and timeouts
+// (the dialog tool could not actually run). A clean non-zero exit (e.g. the
+// user cancelling) keeps the real exit code, so callers can distinguish
+// "tool unavailable / broken" from "user cancelled".
+function spawnFailed(result) {
+  return !!result && result.code === -1;
+}
+
+/** Whether a command exists on PATH (best-effort, non-blocking spawn probe). */
+function commandExists(cmd) {
+  return new Promise((resolve) => {
+    const probe = process.platform === 'win32'
+      ? spawn('where', [cmd], { stdio: 'ignore', windowsHide: true })
+      : spawn('which', [cmd], { stdio: 'ignore' });
+    probe.on('error', () => resolve(false));
+    probe.on('close', (code) => resolve(code === 0));
+  });
+}
+
+function psSingleQuoted(value) {
+  return String(value ?? '').replace(/'/g, "''");
+}
+
+/** Absolute directory path for the Windows picker initial folder (best-effort). */
+function resolveInitialPath(initialPath) {
+  const trimmed = String(initialPath ?? '').trim();
+  try {
+    return path.win32.resolve(trimmed || process.cwd());
+  } catch {
+    return trimmed || process.cwd();
+  }
+}
+
+function powershellScript(title, initialPath) {
+  // Run STA so the COM file dialog works; print the selected path or nothing.
+  const safeTitle = psSingleQuoted(title || 'Select a project folder');
+  const safeInitialPath = psSingleQuoted(initialPath || '');
+  return [
+    // Force UTF-8 stdout so non-ASCII selected paths are not mangled by the
+    // console's default code page (PowerShell 5.1 is not UTF-8 by default).
+    '$ErrorActionPreference = "Stop"',
+    '[Console]::OutputEncoding = [Text.Encoding]::UTF8',
+    'Add-Type -AssemblyName System.Windows.Forms | Out-Null',
+    `$code = @'
+using System;
+using System.Runtime.InteropServices;
+
+namespace Mixdog {
+  public static class ExplorerFolderPicker {
+    private const int ERROR_CANCELLED = unchecked((int)0x800704C7);
+
+    [Flags]
+    private enum FOS : uint {
+      NOCHANGEDIR = 0x00000008,
+      PICKFOLDERS = 0x00000020,
+      FORCEFILESYSTEM = 0x00000040,
+      PATHMUSTEXIST = 0x00000800,
+      FILEMUSTEXIST = 0x00001000
+    }
+
+    private enum SIGDN : uint {
+      FILESYSPATH = 0x80058000
+    }
+
+    [ComImport, Guid("DC1C5A9C-E88A-4DDE-A5A1-60F82A20AEF7")]
+    private class FileOpenDialog {}
+
+    [ComImport, Guid("42f85136-db7e-439c-85f1-e4075d135fc8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    private interface IFileDialog {
+      [PreserveSig] int Show(IntPtr parent);
+      [PreserveSig] int SetFileTypes(uint cFileTypes, IntPtr rgFilterSpec);
+      [PreserveSig] int SetFileTypeIndex(uint iFileType);
+      [PreserveSig] int GetFileTypeIndex(out uint piFileType);
+      [PreserveSig] int Advise(IntPtr pfde, out uint pdwCookie);
+      [PreserveSig] int Unadvise(uint dwCookie);
+      [PreserveSig] int SetOptions(FOS fos);
+      [PreserveSig] int GetOptions(out FOS pfos);
+      [PreserveSig] int SetDefaultFolder(IShellItem psi);
+      [PreserveSig] int SetFolder(IShellItem psi);
+      [PreserveSig] int GetFolder(out IShellItem ppsi);
+      [PreserveSig] int GetCurrentSelection(out IShellItem ppsi);
+      [PreserveSig] int SetFileName([MarshalAs(UnmanagedType.LPWStr)] string pszName);
+      [PreserveSig] int GetFileName([MarshalAs(UnmanagedType.LPWStr)] out string pszName);
+      [PreserveSig] int SetTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle);
+      [PreserveSig] int SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszText);
+      [PreserveSig] int SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string pszLabel);
+      [PreserveSig] int GetResult(out IShellItem ppsi);
+      [PreserveSig] int AddPlace(IShellItem psi, int fdap);
+      [PreserveSig] int SetDefaultExtension([MarshalAs(UnmanagedType.LPWStr)] string pszDefaultExtension);
+      [PreserveSig] int Close(int hr);
+      [PreserveSig] int SetClientGuid(ref Guid guid);
+      [PreserveSig] int ClearClientData();
+      [PreserveSig] int SetFilter(IntPtr pFilter);
+    }
+
+    [ComImport, Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    private interface IShellItem {
+      [PreserveSig] int BindToHandler(IntPtr pbc, ref Guid bhid, ref Guid riid, out IntPtr ppv);
+      [PreserveSig] int GetParent(out IShellItem ppsi);
+      [PreserveSig] int GetDisplayName(SIGDN sigdnName, out IntPtr ppszName);
+      [PreserveSig] int GetAttributes(uint sfgaoMask, out uint psfgaoAttribs);
+      [PreserveSig] int Compare(IShellItem psi, uint hint, out int piOrder);
+    }
+
+    [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+    private static extern void SHCreateItemFromParsingName(
+      [MarshalAs(UnmanagedType.LPWStr)] string pszPath,
+      IntPtr pbc,
+      ref Guid riid,
+      out IShellItem ppv
+    );
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct RECT {
+      public int Left;
+      public int Top;
+      public int Right;
+      public int Bottom;
+    }
+
+    [DllImport("user32.dll")]
+    private static extern IntPtr GetForegroundWindow();
+
+    [DllImport("kernel32.dll")]
+    private static extern IntPtr GetConsoleWindow();
+
+    [DllImport("user32.dll", SetLastError = true)]
+    private static extern bool GetWindowRect(IntPtr hWnd, out RECT lpRect);
+
+    public static int[] GetDialogOwnerCenter() {
+      IntPtr hwnd = GetConsoleWindow();
+      if (hwnd == IntPtr.Zero) hwnd = GetForegroundWindow();
+      RECT rect;
+      if (hwnd != IntPtr.Zero && GetWindowRect(hwnd, out rect)) {
+        return new int[] { (rect.Left + rect.Right) / 2, (rect.Top + rect.Bottom) / 2 };
+      }
+      var area = System.Windows.Forms.Screen.PrimaryScreen.WorkingArea;
+      return new int[] { area.Left + (area.Width / 2), area.Top + (area.Height / 2) };
+    }
+
+    public static string Pick(string title, string initialPath, IntPtr owner) {
+      IFileDialog dialog = null;
+      IShellItem item = null;
+      IShellItem initialItem = null;
+      IntPtr pathPtr = IntPtr.Zero;
+      try {
+        dialog = (IFileDialog)new FileOpenDialog();
+        FOS options;
+        ThrowIfFailed(dialog.GetOptions(out options));
+        ThrowIfFailed(dialog.SetOptions(options | FOS.PICKFOLDERS | FOS.FORCEFILESYSTEM | FOS.PATHMUSTEXIST | FOS.FILEMUSTEXIST | FOS.NOCHANGEDIR));
+        if (!String.IsNullOrEmpty(title)) ThrowIfFailed(dialog.SetTitle(title));
+        if (!String.IsNullOrEmpty(initialPath) && System.IO.Directory.Exists(initialPath)) {
+          try {
+            Guid shellItemId = new Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe");
+            SHCreateItemFromParsingName(initialPath, IntPtr.Zero, ref shellItemId, out initialItem);
+            if (initialItem != null) {
+              ThrowIfFailed(dialog.SetDefaultFolder(initialItem));
+              ThrowIfFailed(dialog.SetFolder(initialItem));
+            }
+          } catch {
+            // Initial folder is a convenience only; still show the picker.
+          }
+        }
+        int hr = dialog.Show(owner);
+        if (hr == ERROR_CANCELLED) return null;
+        ThrowIfFailed(hr);
+        ThrowIfFailed(dialog.GetResult(out item));
+        ThrowIfFailed(item.GetDisplayName(SIGDN.FILESYSPATH, out pathPtr));
+        return Marshal.PtrToStringUni(pathPtr);
+      } finally {
+        if (pathPtr != IntPtr.Zero) Marshal.FreeCoTaskMem(pathPtr);
+        if (initialItem != null) Marshal.ReleaseComObject(initialItem);
+        if (item != null) Marshal.ReleaseComObject(item);
+        if (dialog != null) Marshal.ReleaseComObject(dialog);
+      }
+    }
+
+    private static void ThrowIfFailed(int hr) {
+      if (hr < 0) Marshal.ThrowExceptionForHR(hr);
+    }
+  }
+}
+'@`,
+    'Add-Type -TypeDefinition $code -ReferencedAssemblies System.Windows.Forms | Out-Null',
+    // Invisible TopMost owner anchored to the TUI console (or foreground window)
+    // so IFileOpenDialog is modal, centered, and not detached on another monitor.
+    '$owner = New-Object System.Windows.Forms.Form',
+    '$owner.TopMost = $true',
+    '$owner.ShowInTaskbar = $false',
+    '$owner.FormBorderStyle = "None"',
+    '$owner.StartPosition = "Manual"',
+    '$owner.Width = 1',
+    '$owner.Height = 1',
+    '$owner.Opacity = 0',
+    '$ownerCenter = [Mixdog.ExplorerFolderPicker]::GetDialogOwnerCenter()',
+    '$owner.Left = [int]$ownerCenter[0]',
+    '$owner.Top = [int]$ownerCenter[1]',
+    '$owner.Show()',
+    '$owner.Activate()',
+    'try {',
+    `  $path = [Mixdog.ExplorerFolderPicker]::Pick('${safeTitle}', '${safeInitialPath}', $owner.Handle)`,
+    '  if ($path) { [Console]::Out.Write($path) }',
+    '} finally {',
+    '  $owner.Dispose()',
+    '}',
+  ].join('\n');
+}
+
+/**
+ * Open the native folder picker.
+ * @returns {Promise<{ available: boolean, path: string|null }>}
+ *   available=false → no usable dialog tool; caller should fall back to typing.
+ *   path=null with available=true → the user cancelled.
+ */
+export async function pickFolder({ title = 'Select a project folder', initialPath = '' } = {}) {
+  const platform = process.platform;
+
+  if (platform === 'win32') {
+    const resolvedInitial = resolveInitialPath(initialPath);
+    const result = await runCapture('powershell.exe', [
+      '-NoLogo', '-NoProfile', '-NonInteractive', '-STA',
+      '-Command', powershellScript(title, resolvedInitial),
+    ]);
+    // Could not run PowerShell / Common File Dialog → fall back to manual typing.
+    if (spawnFailed(result)) return { available: false, path: null };
+    const path = String(result.stdout || '').trim();
+    if (!result.ok && !path) return { available: false, path: null };
+    return { available: true, path: path || null };
+  }
+
+  if (platform === 'darwin') {
+    const safeTitle = String(title).replace(/"/g, '\\"');
+    const script = `set f to choose folder with prompt "${safeTitle}"\nPOSIX path of f`;
+    const result = await runCapture('osascript', ['-e', script]);
+    // Could not run osascript (spawn failure / timeout) → manual fallback.
+    if (spawnFailed(result)) return { available: false, path: null };
+    // osascript exits non-zero (code 1) on user cancel; treat as cancel.
+    const path = String(result.stdout || '').trim();
+    return { available: true, path: path || null };
+  }
+
+  // Linux / other unix: prefer zenity, then kdialog.
+  if (await commandExists('zenity')) {
+    const result = await runCapture('zenity', [
+      '--file-selection', '--directory', `--title=${title}`,
+    ]);
+    // Spawn failure / timeout (broken display, missing portal, etc.) → manual
+    // fallback rather than silently looping back to the picker.
+    if (spawnFailed(result)) return { available: false, path: null };
+    const path = String(result.stdout || '').trim();
+    if (!result.ok && !path) return { available: true, path: null }; // cancel
+    return { available: true, path: path || null };
+  }
+  if (await commandExists('kdialog')) {
+    const result = await runCapture('kdialog', ['--getexistingdirectory', '.']);
+    if (spawnFailed(result)) return { available: false, path: null };
+    const path = String(result.stdout || '').trim();
+    if (!result.ok && !path) return { available: true, path: null };
+    return { available: true, path: path || null };
+  }
+
+  return { available: false, path: null };
+}