@openagents-org/agent-connector 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagents-org/agent-connector",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Agent management CLI and library for OpenAgents — install, configure, and run AI coding agents",
   "main": "src/index.js",
   "bin": {
@@ -11,7 +11,13 @@
     "build:registry": "node scripts/build-registry.js",
     "lint": "eslint src/"
   },
-  "keywords": ["openagents", "ai", "agent", "coding", "cli"],
+  "keywords": [
+    "openagents",
+    "ai",
+    "agent",
+    "coding",
+    "cli"
+  ],
   "author": "OpenAgents",
   "license": "MIT",
   "repository": {

package/src/autostart.js

@@ -0,0 +1,178 @@
+/**
+ * Autostart — register agent-connector daemon as a system service.
+ *
+ * - macOS: launchd plist
+ * - Linux: systemd user unit
+ * - Windows: Task Scheduler XML
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { whichBinary, IS_WINDOWS } = require('./paths');
+
+const IS_MACOS = process.platform === 'darwin';
+const IS_LINUX = process.platform === 'linux' && !IS_MACOS;
+const HOME = process.env.HOME || process.env.USERPROFILE || '';
+
+const SERVICE_LABEL = 'org.openagents.connector';
+
+/**
+ * Enable autostart on login.
+ */
+function enable(configDir) {
+  const nodeBin = whichBinary('node') || process.execPath;
+  const cliPath = path.resolve(__dirname, '..', 'bin', 'agent-connector.js');
+
+  if (IS_MACOS) return _enableMacOS(nodeBin, cliPath, configDir);
+  if (IS_LINUX) return _enableLinux(nodeBin, cliPath, configDir);
+  if (IS_WINDOWS) return _enableWindows(nodeBin, cliPath, configDir);
+  throw new Error(`Autostart not supported on ${process.platform}`);
+}
+
+/**
+ * Disable autostart.
+ */
+function disable() {
+  if (IS_MACOS) return _disableMacOS();
+  if (IS_LINUX) return _disableLinux();
+  if (IS_WINDOWS) return _disableWindows();
+  throw new Error(`Autostart not supported on ${process.platform}`);
+}
+
+/**
+ * Check if autostart is enabled.
+ */
+function isEnabled() {
+  if (IS_MACOS) {
+    const plistPath = path.join(HOME, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+    return fs.existsSync(plistPath);
+  }
+  if (IS_LINUX) {
+    const unitPath = path.join(HOME, '.config', 'systemd', 'user', 'openagents-connector.service');
+    return fs.existsSync(unitPath);
+  }
+  if (IS_WINDOWS) {
+    try {
+      execSync(`schtasks /Query /TN "OpenAgents Connector"`, { stdio: 'pipe', timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+// ---- macOS: launchd ----
+
+function _enableMacOS(nodeBin, cliPath, configDir) {
+  const plistDir = path.join(HOME, 'Library', 'LaunchAgents');
+  fs.mkdirSync(plistDir, { recursive: true });
+
+  const plistPath = path.join(plistDir, `${SERVICE_LABEL}.plist`);
+  const logPath = path.join(configDir, 'daemon.log');
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${nodeBin}</string>
+    <string>${cliPath}</string>
+    <string>up</string>
+    <string>--foreground</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${logPath}</string>
+  <key>StandardErrorPath</key>
+  <string>${logPath}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+  </dict>
+</dict>
+</plist>`;
+
+  fs.writeFileSync(plistPath, plist, 'utf-8');
+  execSync(`launchctl load -w "${plistPath}"`, { stdio: 'pipe', timeout: 5000 });
+  return { enabled: true, path: plistPath };
+}
+
+function _disableMacOS() {
+  const plistPath = path.join(HOME, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+  try {
+    execSync(`launchctl unload "${plistPath}"`, { stdio: 'pipe', timeout: 5000 });
+  } catch {}
+  try { fs.unlinkSync(plistPath); } catch {}
+  return { enabled: false };
+}
+
+// ---- Linux: systemd user unit ----
+
+function _enableLinux(nodeBin, cliPath, configDir) {
+  const unitDir = path.join(HOME, '.config', 'systemd', 'user');
+  fs.mkdirSync(unitDir, { recursive: true });
+
+  const unitPath = path.join(unitDir, 'openagents-connector.service');
+
+  const unit = `[Unit]
+Description=OpenAgents Connector Daemon
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${nodeBin} ${cliPath} up --foreground
+Restart=on-failure
+RestartSec=10
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+
+[Install]
+WantedBy=default.target
+`;
+
+  fs.writeFileSync(unitPath, unit, 'utf-8');
+  execSync('systemctl --user daemon-reload', { stdio: 'pipe', timeout: 5000 });
+  execSync('systemctl --user enable openagents-connector.service', { stdio: 'pipe', timeout: 5000 });
+  execSync('systemctl --user start openagents-connector.service', { stdio: 'pipe', timeout: 5000 });
+  return { enabled: true, path: unitPath };
+}
+
+function _disableLinux() {
+  try {
+    execSync('systemctl --user stop openagents-connector.service', { stdio: 'pipe', timeout: 5000 });
+  } catch {}
+  try {
+    execSync('systemctl --user disable openagents-connector.service', { stdio: 'pipe', timeout: 5000 });
+  } catch {}
+  const unitPath = path.join(HOME, '.config', 'systemd', 'user', 'openagents-connector.service');
+  try { fs.unlinkSync(unitPath); } catch {}
+  return { enabled: false };
+}
+
+// ---- Windows: Task Scheduler ----
+
+function _enableWindows(nodeBin, cliPath, configDir) {
+  const taskName = 'OpenAgents Connector';
+  const cmd = `schtasks /Create /SC ONLOGON /TN "${taskName}" /TR "\\"${nodeBin}\\" \\"${cliPath}\\" up --foreground" /RL HIGHEST /F`;
+  execSync(cmd, { stdio: 'pipe', timeout: 10000 });
+  return { enabled: true, method: 'Task Scheduler' };
+}
+
+function _disableWindows() {
+  try {
+    execSync('schtasks /Delete /TN "OpenAgents Connector" /F', { stdio: 'pipe', timeout: 5000 });
+  } catch {}
+  return { enabled: false };
+}
+
+module.exports = { enable, disable, isEnabled };

package/src/cli.js

@@ -327,6 +327,17 @@ async function cmdLogs(connector, flags, positional) {
   }
 }
 
+async function cmdAutostart(connector, flags) {
+  const autostart = require('./autostart');
+  if (flags.disable) {
+    autostart.disable();
+    print('Autostart disabled.');
+  } else {
+    const result = autostart.enable(connector._config ? connector._config.configDir : require('path').join(require('os').homedir(), '.openagents'));
+    print(`Autostart enabled.${result.path ? ` Config: ${result.path}` : ''}`);
+  }
+}
+
 async function cmdWorkspace(connector, flags, positional) {
   const sub = positional[0] || 'list';
   const subArgs = positional.slice(1);
@@ -461,6 +472,7 @@ Commands:
   connect <agent> <token>     Connect agent to workspace
   disconnect <agent>          Disconnect agent from workspace
   env <type> [--set K=V]      View/set env vars for agent type
+  autostart [--disable]       Enable/disable auto-start on login
   test-llm <type>             Test LLM connection
   logs [agent] [--lines N]    View daemon logs
   workspace create [name]     Create a new workspace
@@ -502,6 +514,7 @@ async function main() {
     connect: () => cmdConnect(connector, flags, positional),
     disconnect: () => cmdDisconnect(connector, flags, positional),
     logs: () => cmdLogs(connector, flags, positional),
+    autostart: () => cmdAutostart(connector, flags),
     workspace: () => cmdWorkspace(connector, flags, positional),
     env: () => cmdEnv(connector, flags, positional),
     'test-llm': () => cmdTestLLM(connector, flags, positional),

package/src/config.js

@@ -149,7 +149,7 @@ class Config {
     try {
       if (!fs.existsSync(this.logFile)) return [];
       const content = fs.readFileSync(this.logFile, 'utf-8');
-      let allLines = content.split('\n');
+      let allLines = content.split('\n').filter(Boolean);
       if (agentName) {
         allLines = allLines.filter(
           (l) => l.includes(agentName) || l.includes('daemon') || l.includes('Daemon')
@@ -160,6 +160,37 @@ class Config {
       return [];
     }
   }
+
+  /**
+   * Tail log file with optional filter. Returns { lines, size }.
+   * @param {Object} opts - { agent, lines, offset }
+   * @param {string} [opts.agent] - Filter by agent name
+   * @param {number} [opts.lines=100] - Number of lines to return
+   * @param {number} [opts.offset=0] - Byte offset for incremental reads (0 = from end)
+   */
+  tailLogs(opts = {}) {
+    const { agent, lines = 100, offset = 0 } = opts;
+    try {
+      if (!fs.existsSync(this.logFile)) return { lines: [], size: 0 };
+      const stat = fs.statSync(this.logFile);
+      if (offset > 0 && offset < stat.size) {
+        // Incremental read from offset
+        const fd = fs.openSync(this.logFile, 'r');
+        const buf = Buffer.alloc(stat.size - offset);
+        fs.readSync(fd, buf, 0, buf.length, offset);
+        fs.closeSync(fd);
+        let newLines = buf.toString('utf-8').split('\n').filter(Boolean);
+        if (agent) {
+          newLines = newLines.filter(l => l.includes(agent) || l.includes('Daemon'));
+        }
+        return { lines: newLines, size: stat.size };
+      }
+      // Full read, return last N
+      return { lines: this.getLogs(agent, lines), size: stat.size };
+    } catch {
+      return { lines: [], size: 0 };
+    }
+  }
 }
 
 // -- YAML parser (compatible with Python SDK's daemon.yaml format) --

package/src/daemon.js

@@ -5,8 +5,7 @@ const path = require('path');
 const { spawn, execSync, execFileSync } = require('child_process');
 const os = require('os');
 const { WorkspaceClient } = require('./workspace-client');
-
-const IS_WINDOWS = process.platform === 'win32';
+const { getEnhancedEnv, whichBinary, IS_WINDOWS } = require('./paths');
 
 /**
  * Agent process lifecycle manager.
@@ -63,7 +62,11 @@ class Daemon {
       this._processCommands();
     }, 5000);
 
+    // Watch config file for hot-reload
+    this._watchConfig();
+
     this._writeStatus();
+    this._cachedAgentNames = new Set(agents.map(a => a.name));
     this._log(`Daemon started with ${agents.length} agent(s)`);
 
     // Block until shutdown
@@ -82,6 +85,7 @@ class Daemon {
 
     if (this._statusInterval) clearInterval(this._statusInterval);
     if (this._cmdInterval) clearInterval(this._cmdInterval);
+    if (this._configWatcher) { try { this._configWatcher.close(); } catch {} }
 
     // Kill all child processes
     const kills = Object.keys(this._processes).map((name) =>
@@ -418,22 +422,22 @@ class Daemon {
     const [binary, ...args] = cmd;
     const spawnOpts = {
       stdio: ['ignore', 'pipe', 'pipe'],
-      env: opts.env,
+      env: getEnhancedEnv(opts.env),
       cwd: opts.cwd,
     };
 
     if (IS_WINDOWS) {
       // On Windows, always use shell so .cmd/.ps1 shims on PATH are found
+      // Use cmd /c with chcp 65001 to force UTF-8 output (fixes GBK garbled text)
       spawnOpts.shell = true;
-      // Ensure npm global bin is on PATH
-      const npmBin = path.join(process.env.APPDATA || '', 'npm');
-      if (npmBin && !(process.env.PATH || '').includes(npmBin)) {
-        spawnOpts.env = { ...spawnOpts.env, PATH: npmBin + ';' + (spawnOpts.env.PATH || process.env.PATH || '') };
-      }
     }
 
     const proc = spawn(binary, args, spawnOpts);
 
+    // Force UTF-8 decoding on stdout/stderr
+    if (proc.stdout) proc.stdout.setEncoding('utf-8');
+    if (proc.stderr) proc.stderr.setEncoding('utf-8');
+
     // Merge stderr into stdout handler
     if (proc.stderr) {
       proc.stderr.on('data', (chunk) => {
@@ -555,28 +559,41 @@ class Daemon {
     } catch {}
   }
 
+  _watchConfig() {
+    try {
+      let debounce = null;
+      this._configWatcher = fs.watch(this.config.configFile, () => {
+        if (debounce) clearTimeout(debounce);
+        debounce = setTimeout(() => this._reload(), 1000);
+      });
+      this._configWatcher.on('error', () => {});
+    } catch {}
+  }
+
   _reload() {
     this._log('Reloading config...');
-    const oldAgents = new Map(this.config.getAgents().map((a) => [a.name, a]));
-    // Re-read config from disk (Config reads fresh on each call)
-    const newAgents = new Map(this.config.getAgents().map((a) => [a.name, a]));
+    const oldNames = this._cachedAgentNames || new Set();
+    // Re-read config from disk
+    const newAgents = this.config.getAgents();
+    const newNames = new Set(newAgents.map(a => a.name));
 
     // Stop removed agents
-    for (const name of oldAgents.keys()) {
-      if (!newAgents.has(name)) {
+    for (const name of oldNames) {
+      if (!newNames.has(name)) {
         this.stopAgent(name);
         this._log(`Reload: stopped removed agent '${name}'`);
       }
     }
 
     // Start new agents
-    for (const [name, agent] of newAgents) {
-      if (!oldAgents.has(name)) {
+    for (const agent of newAgents) {
+      if (!oldNames.has(agent.name)) {
         this._launchAgent(agent);
-        this._log(`Reload: started new agent '${name}'`);
+        this._log(`Reload: started new agent '${agent.name}'`);
       }
     }
 
+    this._cachedAgentNames = newNames;
     this._writeStatus();
   }
 
@@ -596,13 +613,26 @@ class Daemon {
     const line = `${ts} INFO daemon: ${msg}`;
     try {
       fs.appendFileSync(this.config.logFile, line + '\n', 'utf-8');
+      this._maybeRotateLog();
     } catch {}
     if (!this._shuttingDown) {
-      // Also log to console when running in foreground
       console.log(line);
     }
   }
 
+  _maybeRotateLog() {
+    // Rotate at 10MB, keep 1 backup
+    const MAX_SIZE = 10 * 1024 * 1024;
+    try {
+      const stat = fs.statSync(this.config.logFile);
+      if (stat.size > MAX_SIZE) {
+        const backup = this.config.logFile + '.1';
+        try { fs.unlinkSync(backup); } catch {}
+        fs.renameSync(this.config.logFile, backup);
+      }
+    } catch {}
+  }
+
   _sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }

package/src/index.js

@@ -56,6 +56,10 @@ class AgentConnector {
     return this.installer.isInstalled(agentType);
   }
 
+  healthCheck(agentType) {
+    return this.installer.healthCheck(agentType);
+  }
+
   // -- Agent CRUD --
 
   listAgents() {
@@ -197,4 +201,5 @@ class AgentConnector {
 
 const adapters = require('./adapters');
 
-module.exports = { AgentConnector, Daemon, WorkspaceClient, adapters };
+const paths = require('./paths');
+module.exports = { AgentConnector, Daemon, WorkspaceClient, adapters, paths };

package/src/installer.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync, exec } = require('child_process');
+const { whichBinary, getEnhancedEnv } = require('./paths');
 
 /**
  * Manages installation and uninstallation of agent runtimes.
@@ -45,6 +46,34 @@ class Installer {
     return this._whichBinary(agentType);
   }
 
+  /**
+   * Health check — binary existence + version.
+   * @returns {{ installed: boolean, binary: string|null, version: string|null }}
+   */
+  healthCheck(agentType) {
+    const binary = this._whichBinary(agentType);
+    if (!binary) return { installed: false, binary: null, version: null };
+
+    const entry = this.registry.getEntry(agentType);
+    const checkCmd = entry && entry.install ? entry.install.check_command : null;
+    const versionCmd = checkCmd || `${entry && entry.install && entry.install.binary || agentType} --version`;
+
+    let version = null;
+    try {
+      const raw = execSync(versionCmd, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        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];
+    } catch {}
+
+    return { installed: true, binary, version };
+  }
+
   /**
    * Install an agent runtime.
    * @returns {Promise<{success: boolean, output: string}>}
@@ -125,32 +154,12 @@ class Installer {
   }
 
   /**
-   * Find a binary on PATH.
+   * Find a binary on PATH (delegates to paths.js for cross-platform detection).
    */
   _whichBinary(agentType) {
     const entry = this.registry.getEntry(agentType);
     const binary = entry && entry.install ? entry.install.binary : agentType;
-    if (!binary) return null;
-
-    try {
-      const cmd = process.platform === 'win32' ? `where ${binary}` : `which ${binary}`;
-      const env = { ...process.env };
-      const extraPaths = ['/usr/local/bin', '/opt/homebrew/bin'];
-      if (process.platform === 'win32') {
-        const npmBin = path.join(process.env.APPDATA || '', 'npm');
-        if (npmBin) extraPaths.push(npmBin);
-        extraPaths.push('C:\\Program Files\\nodejs');
-      }
-      for (const p of extraPaths) {
-        if (p && !(env.PATH || '').includes(p)) {
-          env.PATH = p + (process.platform === 'win32' ? ';' : ':') + (env.PATH || '');
-        }
-      }
-      const result = execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], env }).trim();
-      return result.split('\n')[0] || null;
-    } catch {
-      return null;
-    }
+    return whichBinary(binary);
   }
 
   // -- Markers --
@@ -218,38 +227,26 @@ class Installer {
 
   _execShell(cmd, timeoutMs = 300000) {
     return new Promise((resolve, reject) => {
-      // Ensure common binary paths are available (Electron may not inherit full PATH)
-      const env = { ...process.env };
-      const extraPaths = [
-        '/usr/local/bin', '/opt/homebrew/bin',
-        path.dirname(process.execPath),
-      ];
-      if (process.platform === 'win32') {
-        const npmBin = path.join(process.env.APPDATA || '', 'npm');
-        if (npmBin) extraPaths.push(npmBin);
-        // Common binary locations on Windows
-        extraPaths.push('C:\\Program Files\\nodejs');
-        extraPaths.push('C:\\Program Files (x86)\\nodejs');
-        extraPaths.push('C:\\Program Files\\Git\\cmd');
-        extraPaths.push('C:\\Program Files (x86)\\Git\\cmd');
-        // Also try to find node/git via where
-        for (const bin of ['node', 'git']) {
-          try {
-            const p = execSync(`where ${bin}`, { encoding: 'utf-8', timeout: 3000 }).split(/\r?\n/)[0].trim();
-            if (p) extraPaths.push(path.dirname(p));
-          } catch {}
-        }
+      const env = getEnhancedEnv();
+      // Also include Electron's own binary dir
+      const execDir = path.dirname(process.execPath);
+      if (execDir && !(env.PATH || '').includes(execDir)) {
+        const sep = process.platform === 'win32' ? ';' : ':';
+        env.PATH = execDir + sep + (env.PATH || '');
       }
-      for (const p of extraPaths) {
-        if (p && !(env.PATH || '').includes(p)) {
-          env.PATH = p + (process.platform === 'win32' ? ';' : ':') + (env.PATH || '');
-        }
+
+      // On Windows, use cmd.exe explicitly with UTF-8 codepage
+      let shellCmd = cmd;
+      let shellOpt = true;
+      if (process.platform === 'win32') {
+        shellCmd = `cmd.exe /C "chcp 65001 >nul & ${cmd}"`;
+        shellOpt = false; // we're specifying the shell ourselves
       }
 
-      exec(cmd, {
+      exec(shellCmd, {
         encoding: 'utf-8',
         timeout: timeoutMs,
-        shell: true,
+        shell: shellOpt,
         env,
       }, (error, stdout, stderr) => {
         const output = ((stdout || '') + '\n' + (stderr || '')).trim();

package/src/paths.js

@@ -0,0 +1,259 @@
+/**
+ * Cross-platform PATH detection.
+ *
+ * Finds binary directories for Node.js version managers (nvm, fnm, volta),
+ * package managers (npm, Homebrew, pip), and standard system locations.
+ * Used by installer.js (binary detection) and daemon.js (agent spawning).
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+
+const IS_WINDOWS = process.platform === 'win32';
+const IS_MACOS = process.platform === 'darwin';
+const SEP = IS_WINDOWS ? ';' : ':';
+const HOME = process.env.HOME || process.env.USERPROFILE || '';
+
+/**
+ * Get all extra binary directories that should be checked beyond process.env.PATH.
+ * Returns deduplicated list of existing directories.
+ */
+function getExtraBinDirs() {
+  const dirs = [];
+
+  if (IS_WINDOWS) {
+    _addWindowsPaths(dirs);
+  } else {
+    _addUnixPaths(dirs);
+    if (IS_MACOS) {
+      _addMacPaths(dirs);
+    }
+  }
+
+  // Common: ~/.local/bin (pipx, user installs)
+  _push(dirs, path.join(HOME, '.local', 'bin'));
+
+  // Filter to existing directories only, deduplicate
+  const seen = new Set();
+  const currentPATH = process.env.PATH || '';
+  return dirs.filter(d => {
+    if (!d || seen.has(d) || currentPATH.includes(d)) return false;
+    seen.add(d);
+    try {
+      return fs.statSync(d).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * Build a full PATH string that includes all extra bin dirs prepended.
+ */
+function getEnhancedPATH() {
+  const extra = getExtraBinDirs();
+  const current = process.env.PATH || '';
+  if (extra.length === 0) return current;
+  return extra.join(SEP) + SEP + current;
+}
+
+/**
+ * Build an env object with enhanced PATH for spawning subprocesses.
+ */
+function getEnhancedEnv(baseEnv) {
+  const env = { ...(baseEnv || process.env) };
+  const extra = getExtraBinDirs();
+  if (extra.length > 0) {
+    env.PATH = extra.join(SEP) + SEP + (env.PATH || '');
+  }
+  if (IS_WINDOWS) {
+    // Force UTF-8 output from child processes on non-English Windows locales
+    // (prevents GBK/Shift-JIS garbled text in error messages)
+    env.PYTHONIOENCODING = env.PYTHONIOENCODING || 'utf-8';
+    env.PYTHONUTF8 = env.PYTHONUTF8 || '1';
+    env.LANG = env.LANG || 'en_US.UTF-8';
+  }
+  return env;
+}
+
+/**
+ * Find a binary by name. Returns full path or null.
+ */
+function whichBinary(name) {
+  if (!name) return null;
+  const cmd = IS_WINDOWS ? `where ${name}` : `which ${name}`;
+  try {
+    const result = execSync(cmd, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, PATH: getEnhancedPATH() },
+      timeout: 5000,
+    }).trim();
+    return result.split(/\r?\n/)[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+// ---- Windows paths ----
+
+function _addWindowsPaths(dirs) {
+  const appData = process.env.APPDATA || '';
+  const localAppData = process.env.LOCALAPPDATA || '';
+  const programFiles = process.env.ProgramFiles || 'C:\\Program Files';
+
+  // npm global bin
+  if (appData) _push(dirs, path.join(appData, 'npm'));
+
+  // Node.js install
+  _push(dirs, path.join(programFiles, 'nodejs'));
+
+  // nvm for Windows
+  const nvmHome = process.env.NVM_HOME;
+  if (nvmHome) {
+    _push(dirs, nvmHome);
+    // nvm symlink dir
+    const nvmSymlink = process.env.NVM_SYMLINK || path.join(programFiles, 'nodejs');
+    _push(dirs, nvmSymlink);
+  }
+
+  // fnm
+  if (localAppData) _push(dirs, path.join(localAppData, 'fnm_multishells'));
+  const fnmDir = process.env.FNM_DIR || path.join(appData, 'fnm');
+  if (fnmDir) {
+    // fnm aliases — current version
+    try {
+      const defaultDir = path.join(fnmDir, 'aliases', 'default');
+      if (fs.existsSync(defaultDir)) _push(dirs, defaultDir);
+    } catch {}
+  }
+
+  // volta
+  const voltaHome = process.env.VOLTA_HOME || path.join(localAppData, 'Volta');
+  _push(dirs, path.join(voltaHome, 'bin'));
+
+  // Git (needed for some installers)
+  _push(dirs, path.join(programFiles, 'Git', 'cmd'));
+  _push(dirs, path.join(programFiles, 'Git', 'bin'));
+
+  // Python/pip
+  if (localAppData) {
+    _push(dirs, path.join(localAppData, 'Programs', 'Python', 'Python312', 'Scripts'));
+    _push(dirs, path.join(localAppData, 'Programs', 'Python', 'Python311', 'Scripts'));
+    _push(dirs, path.join(localAppData, 'Programs', 'Python', 'Python310', 'Scripts'));
+  }
+}
+
+// ---- Unix paths ----
+
+function _addUnixPaths(dirs) {
+  // Standard
+  _push(dirs, '/usr/local/bin');
+  _push(dirs, '/usr/bin');
+
+  // npm global (varies by install method)
+  _push(dirs, path.join(HOME, '.npm-global', 'bin'));
+
+  // nvm
+  const nvmDir = process.env.NVM_DIR || path.join(HOME, '.nvm');
+  try {
+    // Find current nvm version
+    const defaultPath = path.join(nvmDir, 'alias', 'default');
+    if (fs.existsSync(defaultPath)) {
+      const version = fs.readFileSync(defaultPath, 'utf-8').trim();
+      // Resolve alias like 'lts/*' or version number
+      const resolved = _resolveNvmVersion(nvmDir, version);
+      if (resolved) _push(dirs, path.join(nvmDir, 'versions', 'node', resolved, 'bin'));
+    }
+    // Also try current symlink
+    _push(dirs, path.join(nvmDir, 'current', 'bin'));
+  } catch {}
+
+  // fnm
+  const fnmDir = process.env.FNM_DIR || path.join(HOME, '.fnm');
+  try {
+    const defaultDir = path.join(fnmDir, 'aliases', 'default');
+    if (fs.existsSync(defaultDir)) {
+      const target = fs.realpathSync(defaultDir);
+      _push(dirs, path.join(target, 'bin'));
+    }
+  } catch {}
+
+  // volta
+  const voltaHome = process.env.VOLTA_HOME || path.join(HOME, '.volta');
+  _push(dirs, path.join(voltaHome, 'bin'));
+
+  // pip/pipx user installs
+  _push(dirs, path.join(HOME, '.local', 'bin'));
+
+  // cargo
+  _push(dirs, path.join(HOME, '.cargo', 'bin'));
+}
+
+// ---- macOS-specific ----
+
+function _addMacPaths(dirs) {
+  // Homebrew (Apple Silicon + Intel)
+  _push(dirs, '/opt/homebrew/bin');
+  _push(dirs, '/opt/homebrew/sbin');
+  _push(dirs, '/usr/local/bin');
+  _push(dirs, '/usr/local/sbin');
+
+  // MacPorts
+  _push(dirs, '/opt/local/bin');
+
+  // pkgx
+  _push(dirs, path.join(HOME, '.pkgx', 'bin'));
+}
+
+// ---- Helpers ----
+
+function _push(arr, dir) {
+  if (dir) arr.push(dir);
+}
+
+function _resolveNvmVersion(nvmDir, alias) {
+  // Handle direct version like 'v22.14.0'
+  if (alias.startsWith('v')) {
+    return alias;
+  }
+  // Handle aliases like 'lts/*', 'lts/jod', 'default', numeric '22'
+  try {
+    // Try reading alias file
+    const aliasFile = path.join(nvmDir, 'alias', alias.replace('/', path.sep));
+    if (fs.existsSync(aliasFile)) {
+      const target = fs.readFileSync(aliasFile, 'utf-8').trim();
+      return _resolveNvmVersion(nvmDir, target);
+    }
+  } catch {}
+
+  // Try finding latest matching version in versions dir
+  try {
+    const versionsDir = path.join(nvmDir, 'versions', 'node');
+    if (fs.existsSync(versionsDir)) {
+      const versions = fs.readdirSync(versionsDir)
+        .filter(v => v.startsWith('v'))
+        .sort()
+        .reverse();
+      const match = versions.find(v => v.startsWith('v' + alias));
+      if (match) return match;
+      // Just return the latest
+      if (versions.length > 0) return versions[0];
+    }
+  } catch {}
+
+  return null;
+}
+
+module.exports = {
+  getExtraBinDirs,
+  getEnhancedPATH,
+  getEnhancedEnv,
+  whichBinary,
+  IS_WINDOWS,
+  IS_MACOS,
+  SEP,
+};