@openagents-org/agent-launcher 0.2.169 → 0.2.170

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagents-org/agent-launcher",
-  "version": "0.2.169",
+  "version": "0.2.170",
   "description": "OpenAgents Launcher \u2014 install, configure, and run AI coding agents from your terminal",
   "main": "src/index.js",
   "bin": {

package/registry.json

@@ -450,7 +450,8 @@
       ]
     },
     "check_ready": {
-      "creds_file": "~/.gemini/oauth_creds.json",
+      "creds_file": "~/.gemini/google_accounts.json",
+      "creds_key": "active",
       "creds_no_parse": true,
       "creds_path_env": [
         "GOOGLE_APPLICATION_CREDENTIALS"
@@ -821,7 +822,7 @@
     "builtin": true,
     "install": {
       "binary": "hermes",
-      "requires": ["python3"],
+      "requires": ["python3", "git"],
       "macos": "curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup",
       "linux": "curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup",
       "windows": "\"%SystemRoot%\\System32\\WindowsPowerShell\\v1.0\\powershell.exe\" -NoProfile -ExecutionPolicy Bypass -Command \"Invoke-RestMethod -UseBasicParsing 'https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1' | Invoke-Expression\""
@@ -831,6 +832,7 @@
     },
     "check_ready": {
       "creds_file": "~/.hermes/config.yaml",
+      "creds_no_parse": true,
       "status_command": "hermes status",
       "login_command": "hermes setup",
       "not_ready_message": "Hermes not configured — run: hermes setup"

package/src/daemon.js

@@ -7,6 +7,18 @@ const os = require('os');
 const { WorkspaceClient } = require('./workspace-client');
 const { getEnhancedEnv, whichBinary, IS_WINDOWS, defaultAgentWorkdir } = require('./paths');
 
+/**
+ * Mask an API key for display (same shape the workspace backend uses for
+ * cloud agents): enough to recognize which key it is, never enough to use it.
+ * The partial reveal needs a real remainder to hide: first4+last4 of a
+ * 9-to-12-char key would expose most of it, so anything that short is
+ * fully masked.
+ */
+function maskApiKey(key) {
+  if (!key || key.length <= 12) return '****';
+  return key.slice(0, 4) + '...' + key.slice(-4);
+}
+
 /**
  * Agent process lifecycle manager.
  *
@@ -131,18 +143,21 @@ class Daemon {
       for (const a of this.config.getAgents()) {
         if (!this._agentOnNodeWorkspace(a, node)) continue;
         const proc = this._processes[a.name];
-        // Model: per-agent env override, else the type-level saved model. Working
-        // dir: the agent's configured path. Both power the workspace agent cards.
-        let model = (a.env && a.env.LLM_MODEL) || null;
-        if (!model) {
-          try { model = (this.envManager.load(a.type) || {}).LLM_MODEL || null; } catch { model = null; }
-        }
+        // Model/key: per-agent env override, else the type-level saved env.
+        // Both power the workspace agent cards; the key goes out MASKED only,
+        // so the edit form can show a key is configured without the secret
+        // ever leaving the device.
+        let typeEnv = {};
+        try { typeEnv = this.envManager.load(a.type) || {}; } catch {}
+        const model = (a.env && a.env.LLM_MODEL) || typeEnv.LLM_MODEL || null;
+        const apiKey = (a.env && a.env.LLM_API_KEY) || typeEnv.LLM_API_KEY || null;
         roster.push({
           name: a.name,
           type: a.type || 'unknown',
           status: (proc && proc.state) || 'stopped',
           model: model || null,
           workingDir: a.path || null,
+          apiKeyMasked: apiKey ? maskApiKey(apiKey) : null,
         });
       }
     } catch {

package/src/install-preflight.js

@@ -0,0 +1,233 @@
+/**
+ * Pre-flight checks for install commands that shell out to a third-party script.
+ *
+ * `curl … | bash` installers are black boxes: whatever they decide to do about a
+ * missing dependency happens with no way for us to explain it, cancel it, or
+ * even show a useful progress line. Hermes is the case that forced this file to
+ * exist. Its install.sh needs git to clone the repo, and on a mac with no
+ * developer tools it:
+ *   1. runs `git --version`, which on macOS is a SHIM that opens the system
+ *      "The 'git' command requires the command line developer tools" dialog —
+ *      a dialog with no OpenAgents branding, appearing seconds after the user
+ *      pressed Install in our marketplace;
+ *   2. calls `xcode-select --install`, opening it a second time;
+ *   3. sleeps in a 5-second poll loop for up to 900 SECONDS waiting for git to
+ *      appear, printing one line per minute.
+ * In the launcher that reads as a progress bar frozen on "downloading" for a
+ * quarter of an hour, so users retry, which starts the whole thing again.
+ *
+ * Catching the missing dependency BEFORE spawning the installer turns all of
+ * that into one actionable message.
+ *
+ * Only dependencies with a probe below are enforced. `install.requires` is
+ * hand-maintained and partly aspirational — hermes lists python3 even though
+ * its installer provisions Python through uv when none is found — so an unknown
+ * entry is left to the installer rather than blocking an install that would
+ * have worked.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const IS_MACOS = process.platform === 'darwin';
+
+/** Directories on PATH, minus any the caller wants skipped. */
+function pathDirs(exclude = []) {
+  const raw = process.env.PATH || '';
+  return raw
+    .split(path.delimiter)
+    .map((d) => d.trim())
+    .filter((d) => d && !exclude.includes(d));
+}
+
+function existsIn(dirs, name, exists, isWindows) {
+  const names = isWindows ? [`${name}.exe`, `${name}.cmd`, name] : [name];
+  for (const dir of dirs) {
+    for (const n of names) {
+      const full = path.join(dir, n);
+      try {
+        if (exists(full)) return full;
+      } catch {
+        /* unreadable dir on PATH — skip */
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The active developer directory, or null when none is selected. `xcode-select
+ * -p` is safe to run with no tools installed: it exits 2 and prints to stderr
+ * WITHOUT opening the install dialog. Running `git` is what opens it.
+ */
+function activeDeveloperDir() {
+  try {
+    return (
+      execFileSync('xcode-select', ['-p'], {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim() || null
+    );
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is a REAL git available?
+ *
+ * The hard constraint on macOS: never execute `git`, and never execute
+ * `/usr/bin/git` in particular. That file exists on every mac whether or not
+ * the Command Line Tools are installed, and running it is precisely what opens
+ * the install dialog we are trying to get ahead of. So this probe only ever
+ * touches the filesystem plus `xcode-select -p`, which reports the active
+ * developer directory (exit code 2, no dialog, when there is none).
+ *
+ * Two platforms are deliberately exempt, because on them a missing git is
+ * something the installer genuinely recovers from:
+ *
+ * - **Windows.** install.ps1's Install-Git downloads PortableGit from
+ *   github.com into %LOCALAPPDATA%\hermes\git — no admin rights, no dialog, no
+ *   winget. It is slow (the script's own comment budgets five minutes) and it
+ *   can fail on a restricted network, but blocking the install would break the
+ *   many machines where it works. What Windows needs from us is a readable
+ *   error when that download fails, not a refusal — see userFacingInstallError
+ *   in the launcher.
+ * - **Linux as root.** install.sh shells out to apt/dnf/pacman, which succeeds
+ *   without a password prompt when we are already root. As a normal user the
+ *   sudo call has no tty to ask on and fails, so the refusal stands there.
+ *
+ * @param {object} [deps] - seams for tests; production passes nothing.
+ */
+function probeGit(deps = {}) {
+  const platform = deps.platform || process.platform;
+  const exists = deps.exists || ((p) => fs.existsSync(p));
+  const dirs = deps.dirs || null;
+
+  if (platform === 'win32') {
+    return { ok: true, detail: 'installer provisions PortableGit itself' };
+  }
+
+  if (platform !== 'darwin') {
+    const search = dirs || [...pathDirs(), '/usr/bin', '/usr/local/bin'];
+    const found = existsIn(search, 'git', exists, false);
+    if (found) return { ok: true, detail: found };
+    const uid = deps.uid !== undefined ? deps.uid : (process.getuid ? process.getuid() : null);
+    if (uid === 0) return { ok: true, detail: 'root can install git unattended' };
+    return { ok: false };
+  }
+
+  // A git outside /usr/bin (Homebrew, MacPorts, a manual install) is a real
+  // binary and safe to trust without running it.
+  const search = dirs || [
+    ...pathDirs(['/usr/bin']),
+    '/opt/homebrew/bin',
+    '/usr/local/bin',
+  ];
+  const found = existsIn(search, 'git', exists, false);
+  if (found) return { ok: true, detail: found };
+
+  // Otherwise the only candidate left is the /usr/bin shim, which forwards to
+  // the active developer directory. Resolve that directory and look for the git
+  // it would forward to: present means the shim works, absent means running it
+  // would open the dialog — which is exactly the case we refuse to walk into.
+  const developerDir =
+    'developerDir' in deps ? deps.developerDir : activeDeveloperDir();
+
+  const candidates = [];
+  if (developerDir) candidates.push(path.join(developerDir, 'usr', 'bin', 'git'));
+  candidates.push('/Library/Developer/CommandLineTools/usr/bin/git');
+  for (const c of candidates) {
+    try {
+      if (exists(c)) return { ok: true, detail: c };
+    } catch {
+      /* ignore */
+    }
+  }
+
+  return { ok: false };
+}
+
+/**
+ * How the user fixes each missing dependency, phrased for the install screen.
+ * `action` is a hint the launcher UI can turn into a button; everything else
+ * degrades to plain text.
+ */
+function gitRemedy() {
+  if (IS_MACOS) {
+    return {
+      name: 'git',
+      action: 'install-xcode-clt',
+      summary: 'Git is required, and it comes with the Xcode Command Line Tools.',
+      command: 'xcode-select --install',
+      alternative: 'brew install git',
+    };
+  }
+  return {
+    name: 'git',
+    action: null,
+    summary: 'Git is required to download this agent.',
+    command: 'sudo apt install git   # or dnf / pacman, per your distro',
+    alternative: null,
+  };
+}
+
+const PROBES = {
+  git: { probe: probeGit, remedy: gitRemedy },
+};
+
+/**
+ * Check a registry entry's `install.requires` against the machine.
+ * @returns {{ ok: boolean, missing: Array<{name: string, action: string|null, summary: string, command: string, alternative: string|null}> }}
+ */
+function checkInstallPrereqs(entry) {
+  const requires = entry && entry.install ? entry.install.requires : null;
+  if (!Array.isArray(requires) || requires.length === 0) return { ok: true, missing: [] };
+
+  const missing = [];
+  for (const name of requires) {
+    const spec = PROBES[String(name || '').toLowerCase()];
+    if (!spec) continue; // no probe → the installer's problem, not ours
+    let result;
+    try {
+      result = spec.probe();
+    } catch {
+      continue; // a probe that throws must never block an install
+    }
+    if (!result || !result.ok) missing.push(spec.remedy());
+  }
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * The error thrown in place of running the installer. Carries `code` and
+ * `missing` so the launcher can render buttons instead of parsing prose, and a
+ * message that stands on its own for the CLI and the log.
+ */
+function missingPrereqError(agentLabel, missing) {
+  const lines = [
+    `${agentLabel} cannot be installed yet — a required tool is missing.`,
+    '',
+  ];
+  for (const item of missing) {
+    lines.push(`• ${item.summary}`);
+    lines.push(`  Install it with:  ${item.command}`);
+    if (item.alternative) lines.push(`  Or:               ${item.alternative}`);
+  }
+  lines.push('', 'Once it is installed, come back and press Install again.');
+
+  const err = new Error(lines.join('\n'));
+  err.code = 'MISSING_PREREQ';
+  err.missing = missing;
+  return err;
+}
+
+module.exports = {
+  checkInstallPrereqs,
+  missingPrereqError,
+  probeGit,
+};

package/src/installer.js

@@ -8,10 +8,32 @@ const { whichBinary, getEnhancedEnv, getRuntimePrefix, clearBinaryLookupCache, a
 const { EnvManager } = require('./env');
 const { nodeDistUrls, installRegistry } = require('./mirrors');
 const { readinessReason, REASON } = require('./adapters/health-status');
+const { checkInstallPrereqs, missingPrereqError } = require('./install-preflight');
+const { detectShadowedNodeShims, shadowedNodeWarning } = require('./node-shims');
 
 const STATUS_CACHE_TTL_MS = 10000;
 const statusCache = new Map();
 
+/**
+ * How long a streaming install may produce NO output before it is treated as
+ * hung and killed. Generous on purpose: a slow npm postinstall or a large
+ * extraction can legitimately go quiet for a while, and killing a working
+ * install is worse than waiting. Set OPENAGENTS_INSTALL_STALL_MS=0 to disable.
+ */
+const INSTALL_STALL_MS = (() => {
+  const raw = process.env.OPENAGENTS_INSTALL_STALL_MS;
+  if (raw === undefined || raw === '') return 10 * 60 * 1000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 10 * 60 * 1000;
+})();
+
+/**
+ * How often the stall watchdog checks. Capped at half the stall budget so the
+ * poll granularity never dominates the deadline (matters for a short budget in
+ * tests; in production the 15s ceiling applies).
+ */
+const STALL_POLL_MS = Math.max(50, Math.min(15000, Math.floor(INSTALL_STALL_MS / 2) || 15000));
+
 // Version detection is comparatively expensive (spawns `<bin> --version`), so
 // results are cached briefly and invalidated on install/uninstall.
 const VERSION_CACHE_TTL_MS = 60000;
@@ -868,6 +890,17 @@ class Installer {
         }
         return 'absent';
       }
+      // A named field, for a file that exists in both states. Gemini's
+      // google_accounts.json is written on install and records a signed-OUT
+      // account as `active: null`, so its existence proves nothing — only the
+      // field does. Still content-free: the value is tested for emptiness, never
+      // read out, logged or returned.
+      if (checkReady.creds_key) {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        const value = parsed && typeof parsed === 'object' ? parsed[checkReady.creds_key] : null;
+        const filled = typeof value === 'string' ? !!value.trim() : !!value;
+        return filled ? 'present' : 'absent';
+      }
       return st.size > 0 ? 'present' : 'absent';
     } catch {
       return 'unreadable';
@@ -965,6 +998,8 @@ class Installer {
       return { success: true, output: `${entry.label || agentType} uses direct API mode; no binary install needed.` };
     }
 
+    this._assertPrereqs(agentType, entry);
+
     let cmd = this._getInstallCommand(entry.install);
     if (!cmd) {
       throw new Error(`No install command for ${agentType} on ${Installer.platform()}`);
@@ -1034,6 +1069,8 @@ class Installer {
       return { success: true, command: 'api-only' };
     }
 
+    this._assertPrereqs(agentType, entry, onData);
+
     let rawCmd = this._getInstallCommand(entry.install);
     if (!rawCmd) {
       throw new Error(`No install command for ${agentType} on ${Installer.platform()}`);
@@ -1116,14 +1153,30 @@ class Installer {
 
     return new Promise((resolve, reject) => {
       // windowsHide stops a console window from flashing up on every install.
-      const proc = spawn(spawnFile, spawnArgs, { shell: useShell, env, cwd: installCwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+      //
+      // detached (Unix): puts the installer in its own process group, which is
+      // what makes the stall watchdog able to stop the WHOLE tree. Without it
+      // the direct child is a shell and the actual work — curl, git, uv — runs
+      // in grandchildren that survive a signal aimed at the shell. It does not
+      // change lifetime semantics: an install was never killed by the launcher
+      // exiting, before or after this.
+      const proc = spawn(spawnFile, spawnArgs, {
+        shell: useShell,
+        env,
+        cwd: installCwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        detached: process.platform !== 'win32',
+      });
 
       if (proc.stdout) proc.stdout.setEncoding('utf-8');
       if (proc.stderr) proc.stderr.setEncoding('utf-8');
 
       let outputTail = '';
+      let lastOutputAt = Date.now();
       const captureOutput = (d) => {
         const text = String(d);
+        lastOutputAt = Date.now();
         outputTail = (outputTail + text).slice(-4000);
         if (onData) onData(text);
       };
@@ -1131,8 +1184,40 @@ class Installer {
       if (proc.stdout) proc.stdout.on('data', captureOutput);
       if (proc.stderr) proc.stderr.on('data', captureOutput);
 
-      proc.on('error', (err) => reject(err));
+      // Stall watchdog. A third-party installer that decides to wait — hermes's
+      // install.sh polls for up to 900s after asking macOS for the developer
+      // tools — otherwise hangs this promise indefinitely, and the only visible
+      // symptom is a progress bar that stopped moving. The preflight now
+      // prevents that specific case, but the general shape (a download that
+      // never returns, a prompt on a stdin nobody is reading) is not specific
+      // to any one installer, so time is bounded here for all of them.
+      let stallTimer = null;
+      let stalled = false;
+      const clearStallTimer = () => {
+        if (stallTimer) { clearInterval(stallTimer); stallTimer = null; }
+      };
+      if (INSTALL_STALL_MS > 0) {
+        stallTimer = setInterval(() => {
+          if (Date.now() - lastOutputAt < INSTALL_STALL_MS) return;
+          stalled = true;
+          clearStallTimer();
+          const minutes = Math.round(INSTALL_STALL_MS / 60000);
+          const msg = `Install stalled: no output for ${minutes} minutes. `
+            + 'The installer was stopped. It may be waiting on a prompt, or on a '
+            + 'download that never returns.';
+          if (onData) onData(`\n${msg}\n`);
+          this._killProcessTree(proc);
+          reject(new Error(msg));
+        }, STALL_POLL_MS);
+        // Never hold the event loop open for the watchdog alone.
+        if (typeof stallTimer.unref === 'function') stallTimer.unref();
+      }
+
+      proc.on('error', (err) => { clearStallTimer(); reject(err); });
       proc.on('close', (code) => {
+        clearStallTimer();
+        // The watchdog already rejected; this close is the kill it performed.
+        if (stalled) return;
         if (code === 0) {
           // Aider-only: confirm a real, genuine binary exists before recording
           // the install (verify-before-mark; never writes a marker on
@@ -1170,6 +1255,13 @@ class Installer {
               return;
             }
             if (onData) onData(`\nHermes CLI resolved: ${hermes.path}\n`);
+            // Its installer may have repointed the machine's node/npm/npx at
+            // its own Node. See node-shims.js — we report, never rewrite.
+            const shimWarning = shadowedNodeWarning(
+              entry.label || agentType,
+              detectShadowedNodeShims(),
+            );
+            if (shimWarning && onData) onData(`${shimWarning}\n`);
           }
           // Cursor-only: same failure shape as hermes above — its installer
           // exits 0 after a failed download. See _verifyCursorBinary.
@@ -1350,6 +1442,51 @@ class Installer {
     });
   }
 
+  /**
+   * Refuse to run a third-party installer whose hard dependencies are missing.
+   *
+   * See install-preflight.js for why this is worth doing before the spawn: the
+   * scripts we shell out to handle a missing dependency by opening OS dialogs
+   * and sleeping for minutes, which the launcher can only render as a frozen
+   * progress bar.
+   */
+  _assertPrereqs(agentType, entry, onData, check = checkInstallPrereqs) {
+    const { ok, missing } = check(entry);
+    if (ok) return;
+    const err = missingPrereqError(entry.label || agentType, missing);
+    if (onData) onData(`${err.message}\n`);
+    throw err;
+  }
+
+  /**
+   * Stop a spawned installer and everything it started.
+   *
+   * The child is usually a shell (`curl … | bash`, powershell) whose real work
+   * happens in grandchildren, so signalling the direct child alone leaves the
+   * download running. On Unix the process group is signalled; on Windows
+   * taskkill /T walks the tree.
+   */
+  _killProcessTree(proc) {
+    if (!proc || proc.exitCode !== null) return;
+    try {
+      if (process.platform === 'win32') {
+        try {
+          execSync(`taskkill /F /T /PID ${proc.pid}`, {
+            stdio: 'ignore', timeout: 5000, windowsHide: true,
+          });
+        } catch { proc.kill(); }
+        return;
+      }
+      try { process.kill(-proc.pid, 'SIGTERM'); } catch { proc.kill('SIGTERM'); }
+      setTimeout(() => {
+        if (proc.exitCode !== null) return;
+        try { process.kill(-proc.pid, 'SIGKILL'); } catch { proc.kill('SIGKILL'); }
+      }, 5000).unref();
+    } catch {
+      /* the process is already gone */
+    }
+  }
+
   /**
    * Get install command for current platform.
    */

package/src/node-shims.js

@@ -0,0 +1,103 @@
+/**
+ * Detecting an agent installer that has taken over the machine's `node`.
+ *
+ * Hermes's install.sh, when it decides the system Node is too old, downloads
+ * its own and then does this:
+ *
+ *   ln -sf "$HERMES_HOME/node/bin/node" "$HOME/.local/bin/node"
+ *   ln -sf "$HERMES_HOME/node/bin/npm"  "$HOME/.local/bin/npm"
+ *   ln -sf "$HERMES_HOME/node/bin/npx"  "$HOME/.local/bin/npx"
+ *
+ * `ln -sf` overwrites. On a machine where ~/.local/bin comes before nvm or
+ * Homebrew on PATH — a very common layout — the user's default `node` silently
+ * becomes the agent's, for every shell and every unrelated project, and npm's
+ * global prefix is rewritten to ~/.local along with it. Nothing announces this,
+ * and nothing connects a project that suddenly builds differently back to
+ * having installed an agent.
+ *
+ * This module only looks and reports. Rewriting a user's PATH or deleting their
+ * symlinks would be a second uninvited change on top of the first, and the
+ * agent's Node may be exactly what they want. Telling them precisely what
+ * happened, and how to undo it, is the part that was missing.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * node/npm/npx under `linkDir` that are symlinks into `ownerDir`, together with
+ * whether they shadow another installation the user already had.
+ *
+ * @param {object} [deps] - seams for tests; production passes nothing.
+ * @returns {{ shims: Array<{name: string, link: string, target: string}>, shadowed: string|null }}
+ */
+function detectShadowedNodeShims(deps = {}) {
+  const home = deps.home || os.homedir();
+  const linkDir = deps.linkDir || path.join(home, '.local', 'bin');
+  const ownerDir = deps.ownerDir || path.join(home, '.hermes', 'node', 'bin');
+  const readLink = deps.readLink || defaultReadLink;
+  const exists = deps.exists || ((p) => fs.existsSync(p));
+  const entries = deps.pathEntries || (process.env.PATH || '').split(path.delimiter);
+
+  const shims = [];
+  for (const name of ['node', 'npm', 'npx']) {
+    const link = path.join(linkDir, name);
+    const target = readLink(link);
+    if (!target) continue;
+    const resolved = path.resolve(linkDir, target);
+    if (resolved === path.join(ownerDir, name) || resolved.startsWith(ownerDir + path.sep)) {
+      shims.push({ name, link, target: resolved });
+    }
+  }
+  if (shims.length === 0) return { shims: [], shadowed: null };
+
+  // Only a problem if the user HAD another node. On a machine with none, these
+  // symlinks are the installer doing something useful.
+  const normalized = entries.map((d) => d.trim()).filter(Boolean);
+  const linkIndex = normalized.indexOf(linkDir);
+  const after = linkIndex === -1 ? normalized : normalized.slice(linkIndex + 1);
+  for (const dir of after) {
+    if (dir === linkDir) continue;
+    const candidate = path.join(dir, 'node');
+    try {
+      if (exists(candidate)) return { shims, shadowed: candidate };
+    } catch {
+      /* unreadable dir on PATH — skip */
+    }
+  }
+  return { shims, shadowed: null };
+}
+
+/** lstat + readlink, or null when the path is absent or not a symlink. */
+function defaultReadLink(p) {
+  try {
+    if (!fs.lstatSync(p).isSymbolicLink()) return null;
+    return fs.readlinkSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The warning text, or null when there is nothing worth saying. Written to be
+ * read in an install log by someone who did not expect any of this.
+ */
+function shadowedNodeWarning(agentLabel, detection) {
+  if (!detection || detection.shims.length === 0 || !detection.shadowed) return null;
+  const names = detection.shims.map((s) => s.name).join(', ');
+  const dir = path.dirname(detection.shims[0].link);
+  return [
+    '',
+    `Note: the ${agentLabel} installer replaced ${names} in ${dir} with links to its own Node.`,
+    `That now takes precedence over ${detection.shadowed} for every shell on this machine,`,
+    'so other projects will build with the agent\'s Node version from here on.',
+    '',
+    'To put your own Node back, remove the links (this does not affect the agent):',
+    `  rm -f ${detection.shims.map((s) => s.link).join(' ')}`,
+  ].join('\n');
+}
+
+module.exports = { detectShadowedNodeShims, shadowedNodeWarning };