@empir3/empir3-bridge 0.3.21

package/src/config.ts

@@ -0,0 +1,199 @@
+/**
+ * Bridge config — BYO-key (Anthropic API) or BYO-CLI (claude binary).
+ *
+ * Persisted at ~/.empir3-bridge/config.json. Created on first read with
+ * sensible defaults so a fresh user never sees a "config missing" error.
+ *
+ * Default mode = 'cli' if `claude` is on PATH, else 'api'. Either mode is
+ * fine; the chat loop branches on `mode` and the unused field stays empty.
+ *
+ * Secrets (anthropicApiKey) live in this file. chmod 600 on write best-effort
+ * — Windows ignores POSIX modes, but per-user data dir already gates access.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { execSync } from 'child_process';
+import { defaultEnabledTools, ALL_TOOL_NAMES } from './tool-defaults.js';
+
+export type ChatMode = 'api' | 'cli';
+
+export interface BridgeConfig {
+  mode: ChatMode;
+  anthropicApiKey: string;       // empty when not set — legacy field, mirrored into apiKeys.anthropic
+  claudeCliPath: string;          // empty = let cli-runner auto-detect
+  model: string;                  // claude-opus-4-7 | claude-sonnet-4-6 | claude-haiku-4-5
+  maxTokens: number;
+  systemPrompt: string;           // empty = use built-in
+  enabledTools: Record<string, boolean>;
+  maxLoopIterations: number;      // safety cap on tool-use loop
+  // Provider API keys. Each empty when unset. The legacy `anthropicApiKey`
+  // field stays for backward-compat with older configs + the API-mode chat
+  // path; new providers (openai, google, xai) only flow through here.
+  apiKeys: {
+    anthropic: string;
+    openai: string;
+    google: string;
+    xai: string;
+  };
+}
+
+const CONFIG_DIR = join(homedir(), '.empir3-bridge');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const LEGACY_CONFIG_FILE = join(homedir(), '.claude-bridge', 'config.json');
+
+// Sonnet by default — it's the right cost/quality tradeoff for browser
+// automation chat. Users pick Opus in /settings when they want it.
+const DEFAULT_MODEL = 'claude-sonnet-4-6';
+const DEFAULT_MAX_TOKENS = 8192;
+const DEFAULT_LOOP_CAP = 20;
+
+function detectClaudeOnPath(): string | null {
+  try {
+    const cmd = process.platform === 'win32' ? 'where claude' : 'which claude';
+    const out = execSync(cmd, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
+    const lines = out.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+    if (lines.length === 0) return null;
+    // On Windows, `where` returns both the unix shim (`claude`) and the
+    // batch shim (`claude.cmd`). Node's spawn can only run `.cmd` directly
+    // — the bare unix file is a shell script and ENOENTs. Prefer `.cmd`.
+    if (process.platform === 'win32') {
+      const cmdShim = lines.find(l => l.toLowerCase().endsWith('.cmd'));
+      if (cmdShim) return cmdShim;
+    }
+    return lines[0];
+  } catch {
+    return null;
+  }
+}
+
+function defaultConfig(): BridgeConfig {
+  const cliPath = detectClaudeOnPath();
+  return {
+    mode: cliPath ? 'cli' : 'api',
+    anthropicApiKey: '',
+    claudeCliPath: cliPath || '',
+    model: DEFAULT_MODEL,
+    maxTokens: DEFAULT_MAX_TOKENS,
+    systemPrompt: '',
+    enabledTools: defaultEnabledTools(),
+    maxLoopIterations: DEFAULT_LOOP_CAP,
+    apiKeys: { anthropic: '', openai: '', google: '', xai: '' },
+  };
+}
+
+/**
+ * Merge persisted config over defaults so fields added in newer versions
+ * always have a value, and per-tool toggles for tools the user has never
+ * seen pick up the default (rather than being silently disabled because
+ * the JSON is missing the key).
+ */
+function hydrate(raw: Partial<BridgeConfig>): BridgeConfig {
+  const base = defaultConfig();
+  const enabled = { ...base.enabledTools };
+  if (raw.enabledTools && typeof raw.enabledTools === 'object') {
+    // Migration: openai_chat → custom_llm (renamed pre-public-launch to
+    // avoid collision with OpenAI Codex CLI, which is unrelated). If the
+    // old key is present and the new key has not been explicitly set,
+    // carry the user's prior choice forward. The old key falls out
+    // automatically — it's not in ALL_TOOL_NAMES anymore.
+    const legacy: any = raw.enabledTools;
+    if (typeof legacy.openai_chat === 'boolean' && typeof legacy.custom_llm !== 'boolean') {
+      legacy.custom_llm = legacy.openai_chat;
+    }
+    for (const k of ALL_TOOL_NAMES) {
+      if (typeof raw.enabledTools[k] === 'boolean') enabled[k] = raw.enabledTools[k];
+    }
+  }
+  const rawKeys: any = (raw as any).apiKeys || {};
+  const legacyAnthropic = typeof raw.anthropicApiKey === 'string' ? raw.anthropicApiKey : '';
+  const apiKeys = {
+    // Legacy field wins if the new field is empty — keeps old configs working.
+    anthropic: typeof rawKeys.anthropic === 'string' && rawKeys.anthropic ? rawKeys.anthropic : legacyAnthropic,
+    openai: typeof rawKeys.openai === 'string' ? rawKeys.openai : '',
+    google: typeof rawKeys.google === 'string' ? rawKeys.google : '',
+    xai: typeof rawKeys.xai === 'string' ? rawKeys.xai : '',
+  };
+  return {
+    mode: raw.mode === 'api' || raw.mode === 'cli' ? raw.mode : base.mode,
+    anthropicApiKey: apiKeys.anthropic,
+    claudeCliPath: typeof raw.claudeCliPath === 'string' && raw.claudeCliPath ? raw.claudeCliPath : base.claudeCliPath,
+    model: typeof raw.model === 'string' && raw.model ? raw.model : base.model,
+    maxTokens: typeof raw.maxTokens === 'number' && raw.maxTokens > 0 ? raw.maxTokens : base.maxTokens,
+    systemPrompt: typeof raw.systemPrompt === 'string' ? raw.systemPrompt : '',
+    enabledTools: enabled,
+    maxLoopIterations: typeof raw.maxLoopIterations === 'number' && raw.maxLoopIterations > 0
+      ? raw.maxLoopIterations : base.maxLoopIterations,
+    apiKeys,
+  };
+}
+
+export function loadConfig(): BridgeConfig {
+  try {
+    const file = existsSync(CONFIG_FILE)
+      ? CONFIG_FILE
+      : existsSync(LEGACY_CONFIG_FILE)
+        ? LEGACY_CONFIG_FILE
+        : '';
+    if (!file) return defaultConfig();
+    const raw = JSON.parse(readFileSync(file, 'utf-8'));
+    return hydrate(raw);
+  } catch {
+    return defaultConfig();
+  }
+}
+
+export function saveConfig(patch: Partial<BridgeConfig>): BridgeConfig {
+  const current = loadConfig();
+  const mergedKeys = { ...current.apiKeys, ...((patch as any).apiKeys || {}) };
+  const next: BridgeConfig = {
+    ...current,
+    ...patch,
+    enabledTools: { ...current.enabledTools, ...(patch.enabledTools || {}) },
+    apiKeys: mergedKeys,
+    // Keep the legacy field in sync with the new one so any consumer still
+    // reading anthropicApiKey directly continues to work.
+    anthropicApiKey: mergedKeys.anthropic,
+  };
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2));
+  try { chmodSync(CONFIG_FILE, 0o600); } catch { /* Windows; best-effort */ }
+  return next;
+}
+
+/**
+ * Sanitized config for the /api/config GET response — NEVER returns the raw
+ * API key, just whether one is set. Settings UI uses this to render a
+ * masked field that re-asks for the key only when the user wants to change it.
+ */
+export function publicConfig(c: BridgeConfig = loadConfig()) {
+  return {
+    mode: c.mode,
+    anthropicApiKeySet: c.apiKeys.anthropic.length > 0,
+    claudeCliPath: c.claudeCliPath,
+    model: c.model,
+    maxTokens: c.maxTokens,
+    systemPrompt: c.systemPrompt,
+    enabledTools: c.enabledTools,
+    maxLoopIterations: c.maxLoopIterations,
+    apiKeysSet: {
+      anthropic: c.apiKeys.anthropic.length > 0,
+      openai: c.apiKeys.openai.length > 0,
+      google: c.apiKeys.google.length > 0,
+      xai: c.apiKeys.xai.length > 0,
+    },
+  };
+}
+
+export function configReady(c: BridgeConfig = loadConfig()): { ready: boolean; reason?: string } {
+  if (c.mode === 'api') {
+    if (!c.anthropicApiKey) return { ready: false, reason: 'Anthropic API key not set. Open localhost:3006/settings to configure.' };
+    return { ready: true };
+  }
+  if (c.mode === 'cli') {
+    if (!c.claudeCliPath) return { ready: false, reason: '`claude` CLI not found on PATH. Install Claude Code or switch to API mode at localhost:3006/settings.' };
+    return { ready: true };
+  }
+  return { ready: false, reason: `Unknown mode: ${c.mode}` };
+}

package/src/desktop-overlay.ps1

@@ -0,0 +1,121 @@
+param(
+  [Parameter(Mandatory=$true)] [string]$SnapshotPath
+)
+
+$ErrorActionPreference = 'Continue'
+
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public static class Empir3OverlayDpi {
+  [DllImport("user32.dll")] public static extern bool SetProcessDpiAwarenessContext(IntPtr value);
+  [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
+  [DllImport("user32.dll")] public static extern int SetWindowLong(IntPtr hWnd, int nIndex, int dwNewLong);
+  [DllImport("user32.dll")] public static extern int GetWindowLong(IntPtr hWnd, int nIndex);
+}
+"@
+try { [Empir3OverlayDpi]::SetProcessDpiAwarenessContext([IntPtr](-4)) | Out-Null } catch {
+  try { [Empir3OverlayDpi]::SetProcessDPIAware() | Out-Null } catch {}
+}
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+# Calculate union of all screens for fullscreen overlay across multi-monitor
+$screens = [System.Windows.Forms.Screen]::AllScreens
+$minX = ($screens | ForEach-Object { $_.Bounds.Left } | Measure-Object -Minimum).Minimum
+$minY = ($screens | ForEach-Object { $_.Bounds.Top } | Measure-Object -Minimum).Minimum
+$maxX = ($screens | ForEach-Object { $_.Bounds.Right } | Measure-Object -Maximum).Maximum
+$maxY = ($screens | ForEach-Object { $_.Bounds.Bottom } | Measure-Object -Maximum).Maximum
+$vWidth = $maxX - $minX
+$vHeight = $maxY - $minY
+
+$script:elements = @()
+$script:lastMTime = $null
+
+function Load-Snapshot {
+  if (-not (Test-Path $SnapshotPath)) { return $false }
+  try {
+    $mtime = (Get-Item $SnapshotPath).LastWriteTime
+    if ($script:lastMTime -and $mtime -eq $script:lastMTime) { return $false }
+    $script:lastMTime = $mtime
+    $raw = Get-Content $SnapshotPath -Raw
+    $data = $raw | ConvertFrom-Json
+    $script:elements = $data.elements
+    return $true
+  } catch { return $false }
+}
+
+Load-Snapshot | Out-Null
+
+$form = New-Object System.Windows.Forms.Form
+$form.FormBorderStyle = 'None'
+$form.StartPosition = 'Manual'
+$form.Location = New-Object System.Drawing.Point($minX, $minY)
+$form.Size = New-Object System.Drawing.Size($vWidth, $vHeight)
+$form.TopMost = $true
+$form.ShowInTaskbar = $false
+$form.BackColor = [System.Drawing.Color]::Magenta
+$form.TransparencyKey = [System.Drawing.Color]::Magenta
+# Opacity 1.0: rely purely on the TransparencyKey for see-through. Box interiors
+# are left transparent (no fill) so the user can read the UI behind them; only
+# the borders + number labels are painted opaque.
+$form.Opacity = 1.0
+
+$form.Add_Shown({
+  $hwnd = $form.Handle
+  $GWL_EXSTYLE = -20
+  $WS_EX_TRANSPARENT = 0x20
+  $WS_EX_LAYERED = 0x80000
+  $WS_EX_NOACTIVATE = 0x08000000
+  $WS_EX_TOOLWINDOW = 0x80
+  $current = [Empir3OverlayDpi]::GetWindowLong($hwnd, $GWL_EXSTYLE)
+  $new = $current -bor $WS_EX_TRANSPARENT -bor $WS_EX_LAYERED -bor $WS_EX_NOACTIVATE -bor $WS_EX_TOOLWINDOW
+  [Empir3OverlayDpi]::SetWindowLong($hwnd, $GWL_EXSTYLE, $new) | Out-Null
+})
+
+$form.Add_Paint({
+  param($sender, $e)
+  $g = $e.Graphics
+  $g.SmoothingMode = 'AntiAlias'
+  $g.TextRenderingHint = 'ClearTypeGridFit'
+
+  $boxColor = [System.Drawing.Color]::FromArgb(255, 32, 220, 120)
+  $labelBg = [System.Drawing.Color]::FromArgb(255, 18, 18, 28)
+  $labelFg = [System.Drawing.Color]::FromArgb(255, 240, 255, 240)
+  $boxPen = New-Object System.Drawing.Pen($boxColor, 3)
+  $labelBgBrush = New-Object System.Drawing.SolidBrush($labelBg)
+  $labelFgBrush = New-Object System.Drawing.SolidBrush($labelFg)
+  $font = New-Object System.Drawing.Font('Segoe UI', 9, [System.Drawing.FontStyle]::Bold)
+
+  foreach ($el in $script:elements) {
+    if (-not $el.bounds) { continue }
+    $x = [int]$el.bounds.x - $minX
+    $y = [int]$el.bounds.y - $minY
+    $w = [int]$el.bounds.width
+    $h = [int]$el.bounds.height
+    if ($w -le 0 -or $h -le 0) { continue }
+
+    $rect = New-Object System.Drawing.Rectangle($x, $y, $w, $h)
+    # No interior fill — keep it see-through. Border + label only.
+    $g.DrawRectangle($boxPen, $rect)
+
+    # Label "d0" in a chip at top-left of the box
+    $label = $el.ref
+    $textSize = $g.MeasureString($label, $font)
+    $labelRect = New-Object System.Drawing.Rectangle($x, ($y - [int]$textSize.Height - 2), ([int]$textSize.Width + 10), ([int]$textSize.Height + 2))
+    if ($labelRect.Y -lt 0) { $labelRect.Y = $y + 1 }
+    $g.FillRectangle($labelBgBrush, $labelRect)
+    $g.DrawString($label, $font, $labelFgBrush, ($labelRect.X + 5), $labelRect.Y)
+  }
+})
+
+# Watcher: poll snapshot file every 750ms; re-paint if changed
+$timer = New-Object System.Windows.Forms.Timer
+$timer.Interval = 750
+$timer.Add_Tick({
+  if (Load-Snapshot) { $form.Invalidate() }
+})
+$timer.Start()
+
+[System.Windows.Forms.Application]::Run($form)

package/src/executable-resolver.ts

@@ -0,0 +1,330 @@
+/**
+ * In-process executable resolution — the single source of truth for "where is
+ * CLI <x> installed".
+ *
+ * Why not just `where.exe` / `which`? Those run with the *daemon's* PATH, which
+ * a tray / GUI-launched process inherits in a stripped, stale form: winget edits
+ * the user PATH after the daemon already started, node-version-managers expose
+ * their bins only in the interactive shell's PATH, etc. The symptom is a CLI
+ * that resolves fine from the user's terminal but reads NOT INSTALLED in the
+ * bridge (real incident: a winget-installed `gh`).
+ *
+ * The fix (mirrors open-design's runtimes/executables.ts): never shell out.
+ * Split `process.env.PATH` in-process, walk `PATHEXT`, and *augment* the search
+ * with a list of well-known user-toolchain dirs where global CLIs actually land
+ * — plus a per-CLI env override (`CLAUDE_BIN`, `GH_BIN`, …) as an escape hatch.
+ * One resolver, used by every CLI, so no detection path can drift again.
+ */
+import { existsSync, readdirSync, statSync } from 'fs';
+import { delimiter, join, extname } from 'path';
+import { homedir } from 'os';
+
+// Per-CLI explicit override: point detection at an exact binary when the
+// conventional locations miss. Keyed by the bare CLI name we probe for.
+const BIN_ENV_OVERRIDE: Record<string, string> = {
+  claude: 'CLAUDE_BIN',
+  codex: 'CODEX_BIN',
+  gemini: 'GEMINI_BIN',
+  grok: 'GROK_BIN',
+  gh: 'GH_BIN',
+  higgsfield: 'HIGGSFIELD_BIN',
+  agy: 'AGY_BIN',
+};
+
+function pathExts(): string[] {
+  if (process.platform !== 'win32') return [''];
+  // Append '' so an extensionless native-installer binary (e.g. a unix-style
+  // `claude` shim) is still found on Windows.
+  const fromEnv = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').map(s => s.trim()).filter(Boolean);
+  return [...fromEnv, ''];
+}
+
+function pathDirs(): string[] {
+  return (process.env.PATH || '').split(delimiter).map(s => s.trim()).filter(Boolean);
+}
+
+// ── Well-known user-toolchain bin dirs ──────────────────────────────
+// Cross-platform list of places a user-installed global CLI lands beyond the
+// daemon's PATH. Cached briefly — the node-version-manager enumeration touches
+// the filesystem, and detection runs on every settings-state load.
+const TOOLCHAIN_CACHE_TTL_MS = 5000;
+let cachedDirs: string[] | null = null;
+let cachedHome: string | null = null;
+let cachedAt = 0;
+
+export function wellKnownToolchainDirs(): string[] {
+  const home = homedir();
+  const now = Date.now();
+  if (cachedDirs && cachedHome === home && now - cachedAt < TOOLCHAIN_CACHE_TTL_MS) {
+    return cachedDirs;
+  }
+  const env = process.env;
+  const localAppData = env.LOCALAPPDATA || join(home, 'AppData', 'Local');
+  const roamingAppData = env.APPDATA || join(home, 'AppData', 'Roaming');
+  const dirs: string[] = [];
+
+  // Explicit npm prefix wins — matches npm's own resolution (env > .npmrc >
+  // default). On Windows the global shims sit directly in <prefix>; on POSIX
+  // they live in <prefix>/bin, so push both.
+  const npmPrefix = (env.NPM_CONFIG_PREFIX || env.npm_config_prefix || '').trim();
+  if (npmPrefix) dirs.push(npmPrefix, join(npmPrefix, 'bin'));
+
+  // Windows global package-manager + shim locations.
+  dirs.push(
+    join(roamingAppData, 'npm'),                              // npm global (default)
+    join(localAppData, 'Microsoft', 'WinGet', 'Links'),       // winget shims
+    join(localAppData, 'Volta', 'bin'),                       // Volta (Windows)
+    join(localAppData, 'Yarn', 'bin'),                        // Yarn classic (Windows)
+    join(home, 'scoop', 'shims'),                             // Scoop
+  );
+  if (env.PNPM_HOME) dirs.push(env.PNPM_HOME);                // pnpm
+
+  // Cross-platform home-relative toolchains.
+  dirs.push(
+    join(home, '.local', 'bin'),                              // native installers (e.g. Claude)
+    // Claude Code "local installer" target (`claude migrate-installer`, also
+    // what the VS Code extension can set up). NOT on PATH — `where claude`
+    // misses it, but the extension spawns it by absolute path, so it works in
+    // VS Code yet read NOT INSTALLED in the bridge until we scan here.
+    join(home, '.claude', 'local'),
+    join(home, '.claude', 'local', 'node_modules', '.bin'),
+    join(home, '.bun', 'bin'),                                // bun
+    join(home, '.deno', 'bin'),                               // deno
+    join(home, '.cargo', 'bin'),                              // cargo
+    join(home, '.volta', 'bin'),                              // Volta (POSIX)
+    join(home, '.yarn', 'bin'),                               // Yarn (POSIX)
+    join(home, '.npm-global', 'bin'),                         // common sudo-free npm prefix
+    join(home, '.npm-packages', 'bin'),                       // ditto, second variant
+  );
+
+  // POSIX system bins (a GUI app's PATH often lacks these).
+  if (process.platform !== 'win32') {
+    dirs.push('/opt/homebrew/bin', '/usr/local/bin');
+  }
+
+  // Per-version Node toolchains — npm-global CLIs hide inside the *active*
+  // node version's bin dir, which never makes it into a GUI app's PATH.
+  for (const { root, segments } of [
+    { root: join(home, '.nvm', 'versions', 'node'), segments: ['bin'] },
+    { root: join(home, '.fnm', 'node-versions'), segments: ['installation', 'bin'] },
+    { root: join(home, '.local', 'share', 'fnm', 'node-versions'), segments: ['installation', 'bin'] },
+    { root: join(localAppData, 'fnm_multishells'), segments: [] },
+  ]) {
+    try {
+      for (const entry of readdirSync(root)) {
+        dirs.push(join(root, entry, ...segments));
+      }
+    } catch { /* root absent — contributes nothing */ }
+  }
+
+  cachedDirs = dirs;
+  cachedHome = home;
+  cachedAt = now;
+  return dirs;
+}
+
+// ── Name-specific install locations ─────────────────────────────────
+// A few CLIs land somewhere no generic toolchain-dir scan would reach. Kept
+// name-keyed so the generic resolver stays clean.
+
+// Scan the winget Packages tree (%LOCALAPPDATA%\Microsoft\WinGet\Packages\
+// <id>\(bin\)?<exe>). The package-id dir rarely matches the binary name, so
+// probe each package's root + bin. The daemon's PATH usually lacks this dir.
+function wingetPackageCandidates(baseName: string): string[] {
+  if (process.platform !== 'win32') return [];
+  const localAppData = process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+  const packages = join(localAppData, 'Microsoft', 'WinGet', 'Packages');
+  const out: string[] = [];
+  try {
+    for (const dir of readdirSync(packages)) {
+      for (const exe of [`${baseName}.exe`, `${baseName}.cmd`]) {
+        out.push(join(packages, dir, 'bin', exe), join(packages, dir, exe));
+      }
+    }
+  } catch { /* no winget Packages dir */ }
+  return out;
+}
+
+// Candidates that must be tried BEFORE PATH (the Microsoft Store Codex app
+// exposes a WindowsApps PATH alias that throws EPERM when spawned by Node, so
+// the real per-user binary has to win).
+function priorityCandidates(baseName: string): string[] {
+  if (process.platform !== 'win32') return [];
+  const localAppData = process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+  if (baseName === 'codex') {
+    const out = [
+      join(localAppData, 'OpenAI', 'Codex', 'bin', 'codex.cmd'),
+      join(localAppData, 'OpenAI', 'Codex', 'bin', 'codex.exe'),
+    ];
+    const packagesDir = join(localAppData, 'Packages');
+    try {
+      for (const dir of readdirSync(packagesDir)) {
+        if (/^OpenAI\.Codex_/i.test(dir)) {
+          out.push(
+            join(packagesDir, dir, 'LocalCache', 'Local', 'OpenAI', 'Codex', 'bin', 'codex.cmd'),
+            join(packagesDir, dir, 'LocalCache', 'Local', 'OpenAI', 'Codex', 'bin', 'codex.exe'),
+          );
+        }
+      }
+    } catch {}
+    const windowsApps = join(process.env.ProgramFiles || 'C:\\Program Files', 'WindowsApps');
+    try {
+      for (const dir of readdirSync(windowsApps)) {
+        if (/^OpenAI\.Codex_/i.test(dir)) {
+          out.push(
+            join(windowsApps, dir, 'app', 'resources', 'codex.cmd'),
+            join(windowsApps, dir, 'app', 'resources', 'codex.exe'),
+            join(windowsApps, dir, 'app', 'resources', 'codex'),
+          );
+        }
+      }
+    } catch {}
+    return out;
+  }
+  return [];
+}
+
+// Candidates tried AFTER PATH + toolchain dirs — installer-specific homes and
+// winget Packages.
+function fallbackCandidates(baseName: string): string[] {
+  const home = homedir();
+  const out: string[] = [];
+  if (baseName === 'grok') {
+    // xAI installer drops grok at ~/.grok/bin/grok[.exe] (not an npm package).
+    for (const f of ['grok.exe', 'grok.cmd', 'grok']) out.push(join(home, '.grok', 'bin', f));
+  }
+  if (baseName === 'gh') {
+    out.push(
+      join(process.env['ProgramFiles'] || 'C:\\Program Files', 'GitHub CLI', 'gh.exe'),
+      join(process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)', 'GitHub CLI', 'gh.exe'),
+      join(process.env['LOCALAPPDATA'] || '', 'GitHub CLI', 'gh.exe'),
+    );
+  }
+  if (baseName === 'agy') {
+    // Antigravity's headless CLI installs to %LOCALAPPDATA%\agy\bin (Windows)
+    // or ~/.local/bin (POSIX) and is not added to PATH.
+    const lad = process.env.LOCALAPPDATA || join(home, 'AppData', 'Local');
+    out.push(join(lad, 'agy', 'bin', 'agy.exe'), join(home, '.local', 'bin', 'agy'));
+  }
+  if (baseName === 'claude') {
+    out.push(...editorBundledClaudeCandidates(home));
+  }
+  out.push(...wingetPackageCandidates(baseName));
+  return out;
+}
+
+// The Claude Code VS Code / Cursor extension bundles a full, headless-capable
+// native `claude` (verified: `--version` → "2.1.x (Claude Code)") at
+// <ext>/resources/native-binary/claude[.exe], but never adds it to PATH — so
+// `where claude` misses it even though Claude works in the editor. Detected as
+// a last resort (a real standalone install ranks ahead via PATH / npm). Newest
+// extension version wins.
+function editorBundledClaudeCandidates(home: string): string[] {
+  const exe = process.platform === 'win32' ? 'claude.exe' : 'claude';
+  const roots = [
+    join(home, '.vscode', 'extensions'),
+    join(home, '.vscode-insiders', 'extensions'),
+    join(home, '.cursor', 'extensions'),
+    join(home, '.windsurf', 'extensions'),
+  ];
+  const extDirs: string[] = [];
+  for (const root of roots) {
+    try {
+      for (const d of readdirSync(root)) {
+        if (/^anthropic\.claude-code-/i.test(d)) extDirs.push(join(root, d));
+      }
+    } catch { /* no such editor / extensions dir */ }
+  }
+  extDirs.sort(compareExtDirVersionDesc);
+  return extDirs.map(d => join(d, 'resources', 'native-binary', exe));
+}
+
+// Sort `anthropic.claude-code-2.1.161-win32-x64` dirs newest-first by their
+// x.y.z version; fall back to reverse string order when no version parses.
+function compareExtDirVersionDesc(a: string, b: string): number {
+  const parse = (s: string): number[] => {
+    const m = /claude-code-(\d+)\.(\d+)\.(\d+)/i.exec(s);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : [];
+  };
+  const va = parse(a), vb = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (vb[i] ?? -1) - (va[i] ?? -1);
+    if (d !== 0) return d;
+  }
+  return b.localeCompare(a);
+}
+
+function looksExecutableOnWindows(filePath: string): boolean {
+  const ext = extname(filePath).trim().toUpperCase();
+  if (!ext) return false;
+  const exts = (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';').map(s => s.trim().toUpperCase()).filter(Boolean);
+  return exts.includes(ext);
+}
+
+// Resolve a per-CLI env override (CLAUDE_BIN, GH_BIN, …) to an absolute,
+// existing, executable file. Returns null when unset/invalid.
+function envOverridePath(baseName: string): string | null {
+  const key = BIN_ENV_OVERRIDE[baseName];
+  if (!key) return null;
+  const raw = (process.env[key] || '').trim();
+  if (!raw) return null;
+  try {
+    if (!statSync(raw).isFile()) return null;
+    if (process.platform === 'win32' && !looksExecutableOnWindows(raw)) return null;
+  } catch {
+    return null;
+  }
+  return raw;
+}
+
+/**
+ * Ordered, de-duplicated list of existing executable paths for `name`. Order:
+ *   1. env override (e.g. CLAUDE_BIN)
+ *   2. name-specific priority dirs (codex real binary before its PATH alias)
+ *   3. PATH × PATHEXT (in-process — no `where.exe` / `which`)
+ *   4. well-known user-toolchain dirs × PATHEXT
+ *   5. name-specific fallbacks (installer homes, winget Packages)
+ */
+export function resolveExecutableCandidates(name: string): string[] {
+  const baseName = name.replace(/\.(exe|cmd|bat)$/i, '').toLowerCase();
+  const exts = pathExts();
+  const candidates: string[] = [];
+
+  const override = envOverridePath(baseName);
+  if (override) candidates.push(override);
+
+  candidates.push(...priorityCandidates(baseName));
+
+  for (const dir of pathDirs()) {
+    for (const ext of exts) candidates.push(join(dir, baseName + ext));
+  }
+  for (const dir of wellKnownToolchainDirs()) {
+    for (const ext of exts) candidates.push(join(dir, baseName + ext));
+  }
+
+  candidates.push(...fallbackCandidates(baseName));
+
+  const seen = new Set<string>();
+  return candidates.filter((c) => {
+    const key = c.toLowerCase();
+    if (seen.has(key) || !existsSync(c)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * Single best executable path for `name`, preferring a `.cmd` shim over `.exe`
+ * on Windows (the .cmd wrapper sets up the right interpreter), else the first
+ * resolved candidate. Null when nothing is found.
+ */
+export function resolveExecutable(name: string): string | null {
+  const candidates = resolveExecutableCandidates(name);
+  if (!candidates.length) return null;
+  if (process.platform === 'win32') {
+    return candidates.find(p => p.toLowerCase().endsWith('.cmd'))
+      || candidates.find(p => p.toLowerCase().endsWith('.exe'))
+      || candidates[0];
+  }
+  return candidates[0];
+}