@openagents-org/agent-launcher 0.2.143 → 0.2.146

package/src/installer.js

@@ -4,12 +4,46 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execSync, exec } = require('child_process');
-const { whichBinary, getEnhancedEnv, getRuntimePrefix, clearBinaryLookupCache } = require('./paths');
+const { whichBinary, getEnhancedEnv, getRuntimePrefix, clearBinaryLookupCache, aiderBinDirs } = require('./paths');
 const { EnvManager } = require('./env');
+const { readinessReason, REASON } = require('./adapters/health-status');
 
 const STATUS_CACHE_TTL_MS = 10000;
 const statusCache = new Map();
 
+// Version detection is comparatively expensive (spawns `<bin> --version`), so
+// results are cached briefly and invalidated on install/uninstall.
+const VERSION_CACHE_TTL_MS = 60000;
+const versionCache = new Map();
+
+/**
+ * Compare two dotted version strings numerically, ignoring any pre-release /
+ * build suffix (e.g. "1.2.3-beta.1" → 1.2.3). Returns -1, 0, or 1.
+ * Returns null when either side has no extractable numeric version.
+ */
+function compareVersions(a, b) {
+  const norm = (v) => {
+    const m = String(v == null ? '' : v).match(/\d+(?:\.\d+)*/);
+    return m ? m[0].split('.').map((n) => parseInt(n, 10)) : null;
+  };
+  const pa = norm(a);
+  const pb = norm(b);
+  if (!pa || !pb) return null;
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+/** Drop the version cache (called on install/uninstall). */
+function clearVersionCache() {
+  versionCache.clear();
+}
+
 /**
  * Manages installation and uninstallation of agent runtimes.
  *
@@ -90,6 +124,20 @@ class Installer {
     // Fallback: check if binary exists on PATH (system install)
     const binaryPath = this._whichBinary(agentType);
     if (!binaryPath) {
+      // Aider/Amp-only: a marker alone is NOT sufficient evidence of an install.
+      // Their CLIs live outside any npm package (aider: curl/uv/pipx → ~/.local/bin;
+      // amp: curl/ps1 installer → ~/.amp/bin), so a historical "installed" marker
+      // can outlive a missing/never-landed binary. Require a real resolvable
+      // binary; when only a stale marker remains, report not-installed with a
+      // 'cli-missing' diagnostic (carried by the existing `location` field — no
+      // new field/enum). The marker itself is left untouched.
+      if (agentType === 'aider' || agentType === 'amp') {
+        return {
+          installed: false,
+          managed: false,
+          location: this._hasMarker(agentType) ? 'cli-missing' : null,
+        };
+      }
       // If a successful install wrote a marker, surface installed=true even
       // when binary detection can't (yet) see the freshly-installed CLI —
       // e.g. PATH caches not yet picking up a brand-new ~/.cursor/bin. The
@@ -144,6 +192,221 @@ class Installer {
     return this.isInstalled(agentType);
   }
 
+  /**
+   * Aider-only post-install verification.
+   *
+   * Confirms a REAL aider binary exists on disk — AND that it is actually the
+   * Aider CLI rather than a same-named unrelated executable — before the
+   * install is recorded. The curl/uv/pipx installer can exit 0 without landing
+   * a runnable binary (blocked download, wrong $HOME, custom bin dir), which
+   * would otherwise leave a "marker says installed but CLI missing" state.
+   * Deliberately does NOT consult the install marker, so it can't be satisfied
+   * by its own about-to-be-written record.
+   *
+   * Hard condition: an absolute path resolves AND the file exists. `aider
+   * --version` is best-effort: a flaky/blocked probe does NOT fail the install,
+   * but a version string that is clearly NOT Aider (wrong same-named package)
+   * does — that is the whole point of the check.
+   *
+   * Scoped to Aider; never called for any other agent type.
+   *
+   * @returns {{ path: string, version: string|null } | null}
+   */
+  _verifyAiderBinary() {
+    try { clearBinaryLookupCache(); } catch {}
+
+    const isWin = process.platform === 'win32';
+    const names = isWin ? ['aider.exe', 'aider.cmd', 'aider'] : ['aider'];
+    const candidates = [];
+    // 1) Whatever the enhanced-PATH resolver finds (now includes the XDG and
+    //    uv-tools dirs added to paths.js).
+    const resolved = this._whichBinary('aider');
+    if (resolved) candidates.push(resolved);
+    // 2) Every real install dir the official installer can target — XDG bin,
+    //    XDG_DATA_HOME/../bin, ~/.local/bin, and the uv tools venv. This is the
+    //    fix for "install succeeded but landed outside ~/.local/bin" (e.g. the
+    //    user has XDG_* set, or only the uv-tools venv copy exists).
+    for (const dir of aiderBinDirs()) {
+      for (const name of names) candidates.push(path.join(dir, name));
+    }
+
+    let found = null;
+    for (const c of candidates) {
+      try { if (c && fs.existsSync(c)) { found = c; break; } } catch {}
+    }
+    if (!found) return null;
+
+    let version = null;
+    try {
+      const raw = require('child_process').execSync(`"${found}" --version`, {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 8000,
+        env: getEnhancedEnv(),
+        windowsHide: true,
+        encoding: 'utf-8',
+      }).trim();
+      if (raw) {
+        // A confident mismatch means this `aider` is the wrong package.
+        if (!/aider/i.test(raw)) return null;
+        version = raw;
+      }
+    } catch {
+      // Best-effort only — file existence above is the hard condition.
+    }
+    return { path: found, version };
+  }
+
+  /**
+   * Aider-only: actionable message when the install command exits 0 but no
+   * runnable (and verified) aider binary can be found anywhere we look. The most
+   * common real cause is the underlying `uv` step failing to download a Python
+   * runtime on a restricted network — so we point at both the PATH/new-terminal
+   * case and a pip fallback.
+   */
+  _aiderBinaryNotFoundMessage() {
+    const isWin = process.platform === 'win32';
+    const name = isWin ? 'aider.exe' : 'aider';
+    const looked = aiderBinDirs().map((d) => `  ${path.join(d, name)}`).join('\n');
+    return (
+      'Aider install command completed, but the Aider CLI could not be located ' +
+      'afterward. The underlying installer (uv) most likely could not finish — ' +
+      'often it cannot download a Python runtime on a restricted network/proxy.\n\n' +
+      `Looked in:\n${looked}\n\n` +
+      'Try one of:\n' +
+      '  1) Open a NEW terminal and run:  aider --version\n' +
+      '     (the install dir may simply not be on this process’s PATH yet)\n' +
+      '  2) Install with pip instead, then re-run detection:\n' +
+      '       python -m pip install --upgrade aider-chat'
+    );
+  }
+
+  /**
+   * Amp-only post-install verification.
+   *
+   * Confirms a REAL amp binary exists on disk before the install is recorded.
+   * The Amp install script can exit 0 without landing a runnable binary (wrong
+   * $HOME, blocked download, custom AMP_HOME), which would otherwise leave a
+   * "marker says installed but CLI missing" state. Deliberately does NOT consult
+   * the installed marker (unlike verifyInstalled()->isInstalled()), so it can't
+   * be satisfied by its own about-to-be-written record.
+   *
+   * Hard condition for success: an absolute path resolves AND the file exists.
+   * `amp --version` is a best-effort enhancement used only for logging — a flaky
+   * or non-interactive `--version` failure does NOT fail the install.
+   *
+   * Scoped to Amp; never called for any other agent type.
+   *
+   * @returns {{ path: string, version: string|null } | null}
+   */
+  _verifyAmpBinary() {
+    // Drop the 30s PATH/whichBinary cache so we see the freshly-installed dir
+    // (e.g. ~/.amp/bin) instead of the pre-install snapshot.
+    try { clearBinaryLookupCache(); } catch {}
+
+    const isWin = process.platform === 'win32';
+    const names = isWin ? ['amp.exe', 'amp.cmd', 'amp'] : ['amp'];
+    const candidates = [];
+    // 1) Whatever the shared cross-platform resolver finds on the enhanced PATH
+    //    (already includes ~/.amp/bin).
+    const resolved = this._whichBinary('amp');
+    if (resolved) candidates.push(resolved);
+    // 2) Honor a custom AMP_HOME, then the installer's default ~/.amp/bin —
+    //    covers a binary that exists but whose dir isn't on PATH yet.
+    const binDirs = [];
+    if (process.env.AMP_HOME) binDirs.push(path.join(process.env.AMP_HOME, 'bin'));
+    binDirs.push(path.join(os.homedir(), '.amp', 'bin'));
+    for (const dir of binDirs) {
+      for (const name of names) candidates.push(path.join(dir, name));
+    }
+
+    let found = null;
+    for (const c of candidates) {
+      try { if (c && fs.existsSync(c)) { found = c; break; } } catch {}
+    }
+    if (!found) return null;
+
+    let version = null;
+    try {
+      version = require('child_process').execSync(`"${found}" --version`, {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 8000,
+        env: getEnhancedEnv(),
+        windowsHide: true,
+        encoding: 'utf-8',
+      }).trim() || null;
+    } catch {
+      // Best-effort only — file existence above is the hard condition.
+    }
+    return { path: found, version };
+  }
+
+  /**
+   * Amp-only: message shown when the install command exits 0 but no runnable
+   * amp binary can be found. Points at the canonical (or AMP_HOME) location.
+   */
+  _ampBinaryNotFoundMessage() {
+    const isWin = process.platform === 'win32';
+    const baseDir = process.env.AMP_HOME
+      ? path.join(process.env.AMP_HOME, 'bin')
+      : path.join(os.homedir(), '.amp', 'bin');
+    const expected = path.join(baseDir, isWin ? 'amp.exe' : 'amp');
+    return (
+      'Amp install command completed, but the Amp CLI binary could not be found.\n\n' +
+      `Expected path:\n${expected}`
+    );
+  }
+
+  // Hermes's install.ps1 can print "[X] Installation failed" (e.g. its bundled
+  // `uv` step fails) yet still exit 0, so exit-code-only success is unreliable.
+  // Confirm a real hermes binary exists before recording the install. Mirrors
+  // the paths the HermesAdapter._findHermesBinary() searches.
+  _verifyHermesBinary() {
+    try { clearBinaryLookupCache(); } catch {}
+    const isWin = process.platform === 'win32';
+    const home = os.homedir();
+    const localAppData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+    const candidates = [];
+    const resolved = this._whichBinary('hermes');
+    if (resolved) candidates.push(resolved);
+    if (isWin) {
+      candidates.push(
+        path.join(localAppData, 'hermes', 'hermes-agent', 'venv', 'Scripts', 'hermes.exe'),
+        path.join(localAppData, 'hermes', 'hermes-agent', 'venv', 'Scripts', 'hermes.cmd'),
+        path.join(localAppData, 'hermes', 'bin', 'hermes.exe'),
+        path.join(localAppData, 'hermes', 'bin', 'hermes.cmd'),
+        path.join(home, '.hermes', 'bin', 'hermes.exe'),
+        path.join(home, '.hermes', 'bin', 'hermes.cmd'),
+        path.join(home, '.local', 'bin', 'hermes.exe'),
+        path.join(home, '.local', 'bin', 'hermes.cmd'),
+      );
+    } else {
+      candidates.push(
+        path.join(home, '.hermes', 'bin', 'hermes'),
+        path.join(home, '.local', 'bin', 'hermes'),
+        '/opt/homebrew/bin/hermes',
+        '/usr/local/bin/hermes',
+      );
+    }
+    let found = null;
+    for (const c of candidates) {
+      try { if (c && fs.existsSync(c)) { found = c; break; } } catch {}
+    }
+    return found ? { path: found } : null;
+  }
+
+  _hermesBinaryNotFoundMessage() {
+    const isWin = process.platform === 'win32';
+    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    const expected = isWin
+      ? path.join(localAppData, 'hermes', 'hermes-agent', 'venv', 'Scripts', 'hermes.exe')
+      : path.join(os.homedir(), '.hermes', 'bin', 'hermes');
+    return (
+      'Hermes install command completed, but the Hermes CLI binary could not be found\n' +
+      "(its installer can report a uv/setup failure yet still exit 0).\n\n" +
+      `Expected path:\n${expected}`
+    );
+  }
+
   /**
    * Find the binary path for an agent type.
    */
@@ -164,18 +427,26 @@ class Installer {
           installed: false,
           binary: null,
           version: null,
+          compatible: null,
+          min_version: null,
           ready: false,
           auth_mode: null,
+          auth_status: null,
           execution_mode: 'unavailable',
+          reason: REASON.NOT_INSTALLED,
           message: 'Not installed',
         };
       }
 
+      const apiReadiness = this._evaluateReadiness(agentType, entry, null);
       return {
         installed: true,
         binary: null,
         version: null,
-        ...this._evaluateReadiness(agentType, entry, null),
+        compatible: true,
+        min_version: null,
+        reason: readinessReason(true, apiReadiness.ready),
+        ...apiReadiness,
       };
     }
 
@@ -185,15 +456,61 @@ class Installer {
         installed: false,
         binary: null,
         version: null,
+        compatible: null,
+        min_version: null,
         ready: false,
         auth_mode: null,
+        auth_status: null,
         execution_mode: 'unavailable',
+        reason: REASON.NOT_INSTALLED,
         message: 'Not installed',
       };
     }
 
     const checkCmd = entry && entry.install ? entry.install.check_command : null;
-    const versionCmd = checkCmd || `${entry && entry.install && entry.install.binary || agentType} --version`;
+    // Prefer the resolved absolute binary path (quoted) over the bare name:
+    // it's unambiguous and lets `--version` succeed for binaries resolved via
+    // the package-bin fallback (which are not on PATH).
+    const versionCmd = checkCmd || `"${binary}" --version`;
+
+    const version = this._detectVersion(binary, versionCmd);
+    const readiness = this._evaluateReadiness(agentType, entry, binary);
+
+    // Generic minimum-version gate (no per-agent special-casing). An entry opts
+    // in by declaring `install.min_version`. Below the floor we keep
+    // installed=true but force compatible=false + ready=false so the launcher
+    // blocks the run and prompts an upgrade (never shows "not installed"). When
+    // the version can't be parsed we report compatible=null ("unknown") rather
+    // than falsely passing the gate, and do NOT hard-block readiness.
+    const gate = this._evaluateCompatibility(entry, version);
+    if (gate.compatible === false) {
+      readiness.ready = false;
+      readiness.message = gate.message;
+    }
+
+    return {
+      installed: true,
+      binary,
+      version,
+      compatible: gate.compatible,
+      min_version: gate.minVersion,
+      // Installed is proven (binary resolved). A not-ready installed agent is a
+      // login/config state, never "not installed" — version mismatch aside.
+      reason:
+        gate.compatible === false
+          ? REASON.VERSION_INCOMPATIBLE
+          : readinessReason(true, readiness.ready),
+      ...readiness,
+    };
+  }
+
+  /**
+   * Detect a binary's version string, cached briefly. Returns null on failure.
+   */
+  _detectVersion(binary, versionCmd) {
+    const key = `${binary}\0${versionCmd}`;
+    const cached = versionCache.get(key);
+    if (cached && (Date.now() - cached.ts) < VERSION_CACHE_TTL_MS) return cached.version;
 
     let version = null;
     try {
@@ -203,13 +520,42 @@ class Installer {
         env: getEnhancedEnv(),
         timeout: 10000,
       }).trim();
-      // Extract version number (e.g. "openclaw 2024.1.5" → "2024.1.5")
       const match = raw.match(/(\d+[\d.]+\d+)/);
-      version = match ? match[1] : raw.split('\n')[0];
+      version = match ? match[1] : (raw.split('\n')[0] || null);
     } catch {}
 
-    const readiness = this._evaluateReadiness(agentType, entry, binary);
-    return { installed: true, binary, version, ...readiness };
+    versionCache.set(key, { version, ts: Date.now() });
+    return version;
+  }
+
+  /**
+   * Evaluate `install.min_version` against a detected version. Generic for any
+   * agent. Returns { compatible: true|false|null, minVersion, message }.
+   *   • no min_version declared → compatible:true (gate disabled)
+   *   • version unparseable      → compatible:null  ("unknown", don't false-pass)
+   *   • version < min_version    → compatible:false (block + upgrade hint)
+   *   • version >= min_version   → compatible:true
+   */
+  _evaluateCompatibility(entry, version) {
+    // Opt-in floor declared under either install.min_version or
+    // check_ready.min_version (e.g. cline pins check_ready.min_version).
+    const minVersion = (entry && (
+      (entry.install && entry.install.min_version) ||
+      (entry.check_ready && entry.check_ready.min_version)
+    )) || null;
+    if (!minVersion) return { compatible: true, minVersion: null, message: null };
+    const cmp = compareVersions(version, minVersion);
+    if (cmp === null) {
+      return { compatible: null, minVersion, message: `Version unknown (requires >= ${minVersion})` };
+    }
+    if (cmp < 0) {
+      return {
+        compatible: false,
+        minVersion,
+        message: `${(entry.label || entry.name || 'This agent')} ${version} is too old — upgrade to ${minVersion} or newer.`,
+      };
+    }
+    return { compatible: true, minVersion, message: null };
   }
 
   _evaluateReadiness(agentType, entry, binary) {
@@ -218,6 +564,7 @@ class Installer {
       return {
         ready: true,
         auth_mode: null,
+        auth_status: 'ready',
         execution_mode: 'unavailable',
         message: 'Ready',
       };
@@ -230,6 +577,13 @@ class Installer {
     const envAnyReady = this._hasAnyValue(process.env, checkReady.env_vars);
     const savedAnyReady = !!(checkReady.saved_env_key && savedEnv[checkReady.saved_env_key]);
     const credsReady = this._checkCredsReady(checkReady);
+    // Content-free credential probes (opt-in via check_ready). Detect agents
+    // whose sign-in is a local OAuth/credential FILE (e.g. Gemini's
+    // ~/.gemini/oauth_creds.json) or a service-account file path, WITHOUT
+    // parsing or logging the token. Additive: agents that don't declare
+    // creds_no_parse / creds_path_env get identical behavior to before.
+    const credsFile = this._evaluateCredsFile(checkReady);
+    const credsPathReady = this._checkCredsPathEnv(checkReady, savedEnv);
 
     let cliReady = false;
     if (checkReady.status_command && binary) {
@@ -240,6 +594,7 @@ class Installer {
       return {
         ready: true,
         auth_mode: 'api_key',
+        auth_status: 'ready',
         execution_mode: 'direct',
         message: 'Ready',
       };
@@ -249,6 +604,7 @@ class Installer {
       return {
         ready: true,
         auth_mode: 'cli_login',
+        auth_status: 'ready',
         execution_mode: 'subprocess',
         message: 'Ready',
       };
@@ -261,23 +617,45 @@ class Installer {
       return {
         ready: true,
         auth_mode: 'api_key',
+        auth_status: 'ready',
         execution_mode: 'direct',
         message: 'Ready',
       };
     }
 
-    if (credsReady) {
+    if (credsReady || credsFile.ready || credsPathReady) {
       return {
         ready: true,
         auth_mode: 'cli_login',
+        auth_status: 'ready',
         execution_mode: 'subprocess',
         message: 'Ready',
       };
     }
 
+    // A credential file was found but could not be read (e.g. permissions).
+    // That is NOT "no credentials" — report it as 'unknown' with a distinct
+    // message so the UI never mislabels a real (if unreadable) login as
+    // "Not logged in". Only reachable for agents that opt into creds_no_parse.
+    if (credsFile.unreadable) {
+      return {
+        ready: false,
+        auth_mode: null,
+        auth_status: 'unknown',
+        execution_mode: 'unavailable',
+        message: checkReady.unreadable_message || 'Credentials were found but could not be read.',
+      };
+    }
+
+    // No positive signal. For agents whose auth cannot be reliably probed
+    // without running them (generic `check_ready.unverifiable`), this is
+    // 'unknown' — they may already be signed in via a CLI login / keychain /
+    // gh — NOT a definitive 'no_credentials'. The launcher can show "unknown"
+    // and still allow a launch attempt; the real run is the final authority.
     return {
       ready: false,
       auth_mode: null,
+      auth_status: checkReady.unverifiable ? 'unknown' : 'no_credentials',
       execution_mode: 'unavailable',
       message: checkReady.not_ready_message || 'Not configured',
     };
@@ -316,6 +694,74 @@ class Installer {
     return false;
   }
 
+  /** Expand a leading "~" to the running user's home directory. */
+  _expandHome(p) {
+    if (typeof p !== 'string' || !p) return p;
+    if (p === '~') return os.homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(os.homedir(), p.slice(2));
+    return p;
+  }
+
+  /**
+   * Existence/readability of a credential file WITHOUT reading its contents —
+   * never loads a token/key into memory. Returns 'present' | 'unreadable' |
+   * 'absent'. A non-empty readable file (or a non-empty directory) is 'present';
+   * a path that exists but cannot be statted/read is 'unreadable'. Resolves "~"
+   * against the running user's home (the daemon/launcher user), not the
+   * renderer/browser user.
+   */
+  _credsFileState(checkReady) {
+    if (!checkReady || !checkReady.creds_file) return 'absent';
+    const p = this._expandHome(checkReady.creds_file);
+    let exists = false;
+    try { exists = fs.existsSync(p); } catch { return 'unreadable'; }
+    if (!exists) return 'absent';
+    try {
+      const st = fs.statSync(p);
+      if (st.isDirectory()) return fs.readdirSync(p).length > 0 ? 'present' : 'absent';
+      fs.accessSync(p, fs.constants.R_OK);
+      return st.size > 0 ? 'present' : 'absent';
+    } catch {
+      return 'unreadable';
+    }
+  }
+
+  /**
+   * Opt-in, content-free creds-file readiness. Active ONLY when
+   * `check_ready.creds_no_parse` is set, so existing creds_file agents (which
+   * parse + match `creds_key` via _checkCredsReady) keep their exact behavior.
+   * Returns { ready, unreadable }.
+   */
+  _evaluateCredsFile(checkReady) {
+    if (!checkReady || !checkReady.creds_file || !checkReady.creds_no_parse) {
+      return { ready: false, unreadable: false };
+    }
+    const state = this._credsFileState(checkReady);
+    return { ready: state === 'present', unreadable: state === 'unreadable' };
+  }
+
+  /**
+   * Treat the named env vars as paths to a credential FILE (e.g.
+   * GOOGLE_APPLICATION_CREDENTIALS) and count one as ready only when its target
+   * exists and is a readable file — a non-empty value alone is NOT enough.
+   * Checks both the process env and the agent's saved env.
+   */
+  _checkCredsPathEnv(checkReady, savedEnv) {
+    const names = checkReady && checkReady.creds_path_env;
+    if (!Array.isArray(names) || !names.length) return false;
+    for (const name of names) {
+      const raw = ((process.env[name] || (savedEnv && savedEnv[name]) || '') + '').trim();
+      if (!raw) continue;
+      try {
+        const p = this._expandHome(raw);
+        if (!fs.existsSync(p)) continue;
+        fs.accessSync(p, fs.constants.R_OK);
+        if (fs.statSync(p).isFile()) return true;
+      } catch { /* unreadable / bad path → not a usable credential */ }
+    }
+    return false;
+  }
+
   /**
    * Check a macOS Keychain generic-password entry. If creds_key is provided the
    * stored value is parsed as JSON and required to contain that key; otherwise any
@@ -385,6 +831,37 @@ class Installer {
     }
 
     const output = await this._execShell(cmd);
+
+    // Aider-only: the curl/uv/pipx installer can exit 0 without landing a
+    // runnable (or genuine) binary, so verify the real CLI exists BEFORE
+    // recording the install. Other agent types keep the original
+    // "exit 0 → mark installed" behavior.
+    if (agentType === 'aider') {
+      const aider = this._verifyAiderBinary();
+      if (!aider) {
+        throw new Error(this._aiderBinaryNotFoundMessage());
+      }
+      this._markInstalled(agentType);
+      return {
+        success: true,
+        output: `${output}\nAider CLI resolved: ${aider.path}${aider.version ? ` (${aider.version})` : ''}`,
+      };
+    }
+
+    // Amp-only: the install script can exit 0 without landing a runnable
+    // binary, so verify the real CLI exists BEFORE recording the install.
+    if (agentType === 'amp') {
+      const amp = this._verifyAmpBinary();
+      if (!amp) {
+        throw new Error(this._ampBinaryNotFoundMessage());
+      }
+      this._markInstalled(agentType);
+      return {
+        success: true,
+        output: `${output}\nAmp CLI resolved: ${amp.path}${amp.version ? ` (${amp.version})` : ''}`,
+      };
+    }
+
     this._markInstalled(agentType);
     return { success: true, output };
   }
@@ -502,6 +979,43 @@ class Installer {
       proc.on('error', (err) => reject(err));
       proc.on('close', (code) => {
         if (code === 0) {
+          // Aider-only: confirm a real, genuine binary exists before recording
+          // the install (verify-before-mark; never writes a marker on
+          // failure). Other agent types are unaffected.
+          if (agentType === 'aider') {
+            const aider = this._verifyAiderBinary();
+            if (!aider) {
+              const msg = this._aiderBinaryNotFoundMessage();
+              if (onData) onData(`\n${msg}\n`);
+              reject(new Error(msg));
+              return;
+            }
+            if (onData) onData(`\nAider CLI resolved: ${aider.path}${aider.version ? ` (${aider.version})` : ''}\n`);
+          }
+          // Amp-only: confirm a real binary exists before recording the
+          // install (verify-before-mark; never writes a marker on failure).
+          if (agentType === 'amp') {
+            const amp = this._verifyAmpBinary();
+            if (!amp) {
+              const msg = this._ampBinaryNotFoundMessage();
+              if (onData) onData(`\n${msg}\n`);
+              reject(new Error(msg));
+              return;
+            }
+            if (onData) onData(`\nAmp CLI resolved: ${amp.path}${amp.version ? ` (${amp.version})` : ''}\n`);
+          }
+          // Hermes-only: its install.ps1 can exit 0 after a failed uv/setup step,
+          // so verify a real binary exists before recording the install.
+          if (agentType === 'hermes') {
+            const hermes = this._verifyHermesBinary();
+            if (!hermes) {
+              const msg = this._hermesBinaryNotFoundMessage();
+              if (onData) onData(`\n${msg}\n`);
+              reject(new Error(msg));
+              return;
+            }
+            if (onData) onData(`\nHermes CLI resolved: ${hermes.path}\n`);
+          }
           this._markInstalled(agentType);
           if (onData) onData(`\nDone! ${agentType} is now installed.\n`);
           resolve({ success: true, command: displayCmd });
@@ -723,6 +1237,51 @@ class Installer {
       const found = whichBinary(candidate);
       if (found) return found;
     }
+    // Fallback: resolve the installed package's OWN bin from its package.json
+    // when npm did not create a node_modules/.bin/<binary> shim for the
+    // top-level package. This happens for packages whose `bin` path is
+    // declared as "./bin/x" (e.g. Cline): a local `npm install --prefix DIR`
+    // links dependency bins but not the explicitly-installed root package's,
+    // so a PATH lookup finds nothing even though the CLI is present and
+    // runnable. Generic and backward-compatible — only runs after PATH misses.
+    const pkgBin = this._resolvePackageBin(agentType, entry, binary);
+    if (pkgBin) return pkgBin;
+    return null;
+  }
+
+  /**
+   * Resolve the absolute path to a package's own executable from its
+   * package.json `bin` field, searched in the runtime and legacy prefixes.
+   * Returns null when not installed there or the bin file is missing.
+   */
+  _resolvePackageBin(agentType, entry, binary) {
+    // Derive the npm package name the same way getInstallInfo does.
+    const npmPkg = entry && entry.install ? entry.install.npm_package : null;
+    const installCmd = entry && entry.install ? this._getInstallCommand(entry.install) : null;
+    let npmPkgFromCmd = null;
+    if (!npmPkg && installCmd && installCmd.includes('npm install')) {
+      const m = installCmd.match(/npm install\s+(?:-g\s+)?(@?[\w-]+(?:\/[\w-]+)?)(?:@\S*)?$/);
+      if (m) npmPkgFromCmd = m[1];
+    }
+    const pkgName = npmPkg || npmPkgFromCmd || binary;
+    const prefixes = [
+      path.join(getRuntimePrefix(agentType), 'node_modules'),
+      path.join(os.homedir(), '.openagents', 'nodejs', 'node_modules'),
+    ];
+    for (const modules of prefixes) {
+      const pkgDir = path.join(modules, pkgName);
+      const pkgJsonPath = path.join(pkgDir, 'package.json');
+      try {
+        if (!fs.existsSync(pkgJsonPath)) continue;
+        const bin = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).bin;
+        let rel = null;
+        if (typeof bin === 'string') rel = bin;
+        else if (bin && typeof bin === 'object') rel = bin[binary] || bin[pkgName] || Object.values(bin)[0];
+        if (!rel) continue;
+        const abs = path.join(pkgDir, rel);
+        if (fs.existsSync(abs)) return abs;
+      } catch {}
+    }
     return null;
   }
 
@@ -770,8 +1329,10 @@ class Installer {
     // Drop the 30s PATH/whichBinary caches so the very next getInstallInfo
     // sees the freshly-created bin dir (e.g. ~/.cursor/bin) instead of the
     // pre-install snapshot. Without this, install completes but UI keeps
-    // showing "not installed" until the cache expires.
+    // showing "not installed" until the cache expires. Also drop the version
+    // cache so an upgrade's new version is reflected immediately.
     try { clearBinaryLookupCache(); } catch {}
+    try { clearVersionCache(); } catch {}
   }
 
   _markUninstalled(agentType) {
@@ -794,6 +1355,7 @@ class Installer {
 
     // Symmetric with _markInstalled: invalidate so detection re-runs cleanly.
     try { clearBinaryLookupCache(); } catch {}
+    try { clearVersionCache(); } catch {}
   }
 
   // -- Shell env + exec --
@@ -1207,4 +1769,4 @@ class Installer {
   }
 }
 
-module.exports = { Installer };
+module.exports = { Installer, compareVersions, clearVersionCache };