@openagents-org/agent-launcher 0.2.133 → 0.2.134

package/package.json

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

package/src/adapters/cursor.js

@@ -205,7 +205,13 @@ class CursorAdapter extends BaseAdapter {
     }
 
     // Tier 3: Common install locations
+    const localAppData = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
     const candidates = IS_WINDOWS ? [
+      // Windows native installer (install?win32=true) drops the CLI here.
+      path.join(localAppData, 'cursor-agent', 'cursor-agent.cmd'),
+      path.join(localAppData, 'cursor-agent', 'cursor-agent.exe'),
+      path.join(localAppData, 'cursor-agent', 'agent.cmd'),
+      path.join(localAppData, 'cursor-agent', 'agent.exe'),
       path.join(home, '.cursor', 'bin', 'cursor-agent.cmd'),
       path.join(home, '.cursor', 'bin', 'cursor-agent.exe'),
       path.join(home, '.cursor', 'bin', 'cursor-agent'),

package/src/adapters/gemini.js

@@ -195,6 +195,12 @@ class GeminiAdapter extends BaseAdapter {
 
     const cmd = [geminiBin, '-p', fullPrompt, '-y', '-o', 'stream-json'];
 
+    // Honor a user-configured model (e.g. when pointing at a relay/proxy whose
+    // channels don't match the CLI default). Set via GEMINI_MODEL in env_config.
+    const env = this.agentEnv || process.env;
+    const model = (env.GEMINI_MODEL || env.GOOGLE_GEMINI_MODEL || '').trim();
+    if (model) cmd.push('-m', model);
+
     const sessionId = this._channelSessions[channelName];
     if (sessionId && !skipResume) {
       cmd.push('-r', sessionId);

package/src/agent-rows.js

@@ -0,0 +1,73 @@
+/**
+ * Pure data helpers for the agent list, shared by the TUI (tui.js) and tests.
+ *
+ * Kept free of any UI/blessed dependency so the list-rendering logic — in
+ * particular the "(local)" labelling and Connect gating — can be unit-tested.
+ */
+
+'use strict';
+
+/**
+ * Build one display row per configured agent from a connector.
+ *
+ * `workspace` holds the resolved workspace URL (or '' when the agent is not
+ * connected). `workspaceLabel` is what the WORKSPACE column shows: the URL when
+ * connected, otherwise "(local)" — matching `agn list` so local-only agents are
+ * always visible rather than rendered as a blank cell.
+ */
+function loadAgentRows(connector) {
+  const config = connector.config.load();
+  const agents = config.agents || [];
+  const agentStatuses = connector.getDaemonStatus() || {};
+  const pid = connector.getDaemonPid();
+  const networks = config.networks || [];
+  return agents.map(agent => {
+    const info = agentStatuses[agent.name] || {};
+    const state = pid ? (info.state || 'stopped') : 'stopped';
+    let workspace = '';
+    if (agent.network) {
+      const net = networks.find(n => n.slug === agent.network || n.id === agent.network);
+      if (net) {
+        const slug = net.slug || net.id;
+        const isLocal = (net.endpoint || '').includes('localhost') || (net.endpoint || '').includes('127.0.0.1');
+        if (isLocal) workspace = `${net.endpoint}/${slug}`;
+        else workspace = `workspace.openagents.org/${slug}`;
+      } else {
+        workspace = agent.network;
+      }
+    }
+    let notReadyMsg = '';
+    let health = null;
+    try {
+      health = connector.healthCheck(agent.type || 'openclaw');
+      if (health && !health.ready) notReadyMsg = health.message || 'Not configured';
+    } catch {}
+
+    return {
+      name: agent.name,
+      type: agent.type || 'openclaw',
+      state,
+      workspace,
+      // "(local)" when there's no workspace connection; URL otherwise. `workspace`
+      // stays empty for local-only agents so Connect gating still treats them as
+      // connectable (see connectAvailable).
+      workspaceLabel: workspace || '(local)',
+      path: agent.path || '',
+      network: agent.network || '',
+      lastError: info.last_error || '',
+      notReadyMsg,
+      health,
+      configured: true,
+    };
+  });
+}
+
+/**
+ * An agent can be connected to a workspace when it's configured and not already
+ * bound to one. Mirrors the footer/menu gating so it can be unit-tested.
+ */
+function connectAvailable(row) {
+  return !!(row && row.configured && !row.workspace);
+}
+
+module.exports = { loadAgentRows, connectAvailable };

package/src/cli.js

@@ -123,7 +123,6 @@ async function cmdCreate(connector, flags, positional) {
 
   try {
     connector.addAgent({ name, type, role, path: flags.path || process.cwd() });
-    print(`Agent '${name}' created (type: ${type})`);
 
     // Signal daemon to pick up the new agent
     try { connector.sendDaemonCommand('reload'); } catch {}
@@ -132,10 +131,14 @@ async function cmdCreate(connector, flags, positional) {
     // Without a workspace connection they will not appear in the Workspace Dashboard.
     const created = connector.config.getAgent(name);
     if (created && !created.network) {
+      print(`Created local agent: ${name} (type: ${type})`);
       print('');
-      print(`Note: '${name}' is local-only and will not appear in the Workspace Dashboard.`);
-      print(`To make it visible, connect it to a workspace:`);
+      print('This agent is local-only and will not appear in Workspace Dashboard yet.');
+      print('');
+      print('To connect it to a Workspace, run:');
       print(`  agn connect ${name} <workspace-token>`);
+    } else {
+      print(`Agent '${name}' created (type: ${type})`);
     }
 
     if (!connector.isInstalled(type)) {
@@ -306,11 +309,10 @@ async function cmdConnect(connector, flags, positional) {
     // No token supplied and none in the environment. Never prompt — keep
     // CI / non-interactive environments from hanging. Print a helpful error
     // explaining why the agent stays invisible and how to fix it.
-    print(`Error: no workspace token provided for '${name}'.`);
-    print(`Without a token, '${name}' stays local-only and will not appear in the Workspace Dashboard.`);
-    print('Provide a token in one of these ways:');
+    print('Workspace token is required.');
+    print('Local-only agents do not appear in Workspace Dashboard until connected.');
+    print('Run:');
     print(`  agn connect ${name} <workspace-token>`);
-    print(`  OPENAGENTS_WORKSPACE_TOKEN=<workspace-token> agn connect ${name}`);
     process.exitCode = 1;
     return;
   }

package/src/installer.js

@@ -414,31 +414,72 @@ class Installer {
       await this.installNodejs(onData);
     }
 
-    // Resolve npm command
-    let cmd = rawCmd;
+    const env = this._buildShellEnv();
+    const isWin = process.platform === 'win32';
+
+    // Build the spawn invocation. Three shapes:
+    //   1. npm install via bundled `node npm-cli.js` — argv array, no shell.
+    //      Path-safe under non-ASCII home dirs on Windows (preferred).
+    //   2. npm install via legacy shell string (npm.cmd / npm) — fallback only
+    //      when no node + npm-cli.js layout is found; OEM-codepage corruption
+    //      means this breaks on non-ASCII paths, but still works for ASCII.
+    //   3. pip / curl / powershell — keep the legacy shell-string behaviour.
+    let spawnFile;
+    let spawnArgs = [];
+    let useShell;
+    let installCwd;
+    let displayCmd;
+
     if (rawCmd.startsWith('npm install')) {
       const prefixDir = getRuntimePrefix(agentType);
       fs.mkdirSync(prefixDir, { recursive: true });
-      // Use --save so npm tracks the package in package.json (prevents pruning on next install)
-      const args = rawCmd.replace('npm install', 'install --loglevel=verbose --save').replace(' -g ', ` --prefix "${prefixDir}" `);
-      cmd = this._resolveNpmCommand(args);
-    } else if (rawCmd.startsWith('pip install') || rawCmd.startsWith('pipx install')) {
-      cmd = rawCmd; // pip commands stay as-is
+      installCwd = prefixDir;
+
+      // `npm install [-g] <pkg…>` → install --save --prefix <dir> <pkg…>
+      const pkgArgs = rawCmd
+        .replace(/^npm install\s*/, '')
+        .replace(/(^|\s)-g(\s|$)/, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+      // Use --save so npm tracks the package in package.json (prevents pruning
+      // on next install).
+      const npmArgs = ['install', '--loglevel=verbose', '--save', '--prefix', prefixDir, ...pkgArgs];
+      displayCmd = `npm ${npmArgs.join(' ')}`;
+
+      const direct = this._resolveNodeNpmCli();
+      if (direct) {
+        spawnFile = direct.node;
+        spawnArgs = [direct.npmCli, ...npmArgs];
+        useShell = false;
+        // Ensure npm's own `node` child lookups (postinstall scripts) resolve
+        // to this same runtime by putting its dir first on PATH.
+        const pathKey = Object.keys(env).find(k => k.toLowerCase() === 'path') || 'PATH';
+        const nodeDir = path.dirname(direct.node);
+        if (!(env[pathKey] || '').includes(nodeDir)) {
+          env[pathKey] = nodeDir + (isWin ? ';' : ':') + (env[pathKey] || '');
+        }
+      } else {
+        // Legacy fallback: quoted prefix inside a shell string.
+        const args = `install --loglevel=verbose --save --prefix "${prefixDir}" ${pkgArgs.join(' ')}`;
+        spawnFile = this._wrapForWindowsShell(this._resolveNpmCommand(args));
+        useShell = isWin ? (env.ComSpec || 'C:\\Windows\\System32\\cmd.exe') : true;
+        displayCmd = spawnFile;
+      }
+    } else {
+      // pip / curl / powershell — unchanged shell-string behaviour.
+      spawnFile = this._wrapForWindowsShell(rawCmd);
+      useShell = isWin ? (env.ComSpec || 'C:\\Windows\\System32\\cmd.exe') : true;
+      // Set cwd outside System32 on Windows.
+      installCwd = os.homedir();
+      displayCmd = spawnFile;
     }
 
-    cmd = this._wrapForWindowsShell(cmd);
-
-    if (onData) onData(`$ ${cmd}\n\n`);
-
-    const env = this._buildShellEnv();
-    const shell = process.platform === 'win32'
-      ? (process.env.ComSpec || 'C:\\Windows\\System32\\cmd.exe')
-      : true;
-    // Set cwd to runtime prefix dir (avoids running from System32 on Windows)
-    const installCwd = rawCmd.startsWith('npm install') ? getRuntimePrefix(agentType) : os.homedir();
+    if (onData) onData(`$ ${displayCmd}\n\n`);
 
     return new Promise((resolve, reject) => {
-      const proc = spawn(cmd, [], { shell, env, cwd: installCwd, stdio: ['ignore', 'pipe', 'pipe'] });
+      // 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 });
 
       if (proc.stdout) proc.stdout.setEncoding('utf-8');
       if (proc.stderr) proc.stderr.setEncoding('utf-8');
@@ -458,7 +499,7 @@ class Installer {
         if (code === 0) {
           this._markInstalled(agentType);
           if (onData) onData(`\nDone! ${agentType} is now installed.\n`);
-          resolve({ success: true, command: cmd });
+          resolve({ success: true, command: displayCmd });
         } else {
           // A partial install can leave a placeholder stub at
           // bin/<binary>.exe and npm-generated cmd-shims under
@@ -473,8 +514,8 @@ class Installer {
           } catch {}
           const tail = outputTail.trim();
           const msg = tail
-            ? `Install failed with exit code ${code}\nCommand: ${cmd}\n\n${tail}`
-            : `Install failed with exit code ${code}\nCommand: ${cmd}`;
+            ? `Install failed with exit code ${code}\nCommand: ${displayCmd}\n\n${tail}`
+            : `Install failed with exit code ${code}\nCommand: ${displayCmd}`;
           if (onData) onData(`\n${msg}\n`);
           reject(new Error(msg));
         }
@@ -599,7 +640,7 @@ class Installer {
       : true;
 
     return new Promise((resolve, reject) => {
-      const proc = spawn(cmd, [], { shell, env, stdio: ['ignore', 'pipe', 'pipe'] });
+      const proc = spawn(cmd, [], { shell, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
 
       if (proc.stdout) proc.stdout.setEncoding('utf-8');
       if (proc.stderr) proc.stderr.setEncoding('utf-8');
@@ -811,9 +852,14 @@ class Installer {
         } catch {}
       }
     }
+    // On Windows the spread above yields a "Path" key, not "PATH". Writing
+    // `env.PATH` would create a duplicate key holding only extraDirs and drop
+    // everything else; libuv then resolves spawned binaries against the wrong,
+    // truncated value. Update the existing case-insensitive key in place.
+    const pathKey = Object.keys(env).find(k => k.toLowerCase() === 'path') || 'PATH';
     for (const d of extraDirs) {
-      if (d && !(env.PATH || '').includes(d)) {
-        env.PATH = d + sep + (env.PATH || '');
+      if (d && !(env[pathKey] || '').includes(d)) {
+        env[pathKey] = d + sep + (env[pathKey] || '');
       }
     }
     return env;
@@ -918,7 +964,7 @@ class Installer {
         const proc = spawnProc('powershell', [
           '-NoProfile', '-Command',
           `Expand-Archive -Path '${zipPath}' -DestinationPath '${nodejsDir}' -Force`
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
+        ], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
         if (proc.stdout) proc.stdout.on('data', (d) => { if (onData) onData(d.toString()); });
         if (proc.stderr) proc.stderr.on('data', (d) => { if (onData) onData(d.toString()); });
         proc.on('error', reject);
@@ -1039,6 +1085,54 @@ class Installer {
     });
   }
 
+  /**
+   * Locate a `node` binary plus its `npm-cli.js` so npm can be invoked as
+   * `node npm-cli.js …` with argv passed array-style and NO shell. On Windows
+   * that goes through CreateProcessW (UTF-16), so an install prefix under a
+   * non-ASCII home dir (e.g. `C:\Users\用户名\.openagents\runtimes\…`) is
+   * preserved exactly. The legacy `npm.cmd` shell shim instead has cmd.exe
+   * decode the path bytes with the OEM code page (936/GBK on zh-CN), corrupting
+   * it and silently breaking every install. Returns { node, npmCli } or null
+   * when no usable layout is found (caller falls back to the legacy shell
+   * command, which still works for ASCII paths).
+   */
+  _resolveNodeNpmCli() {
+    const exists = (p) => { try { return fs.existsSync(p); } catch { return false; } };
+    const isWin = process.platform === 'win32';
+    const nodeName = isWin ? 'node.exe' : 'node';
+
+    const nodeCandidates = [];
+    // Bundled portable node (~/.openagents/nodejs, plus nested node-* layouts)
+    const bundledDir = path.join(this.configDir, 'nodejs');
+    nodeCandidates.push(path.join(bundledDir, nodeName));
+    nodeCandidates.push(path.join(bundledDir, 'bin', 'node'));
+    try {
+      for (const e of fs.readdirSync(bundledDir)) {
+        if (e.startsWith('node-')) {
+          nodeCandidates.push(path.join(bundledDir, e, nodeName));
+          nodeCandidates.push(path.join(bundledDir, e, 'bin', 'node'));
+        }
+      }
+    } catch {}
+    // System node — its npm-cli.js lives next to (or one level above) it.
+    try {
+      const sys = whichBinary('node');
+      if (sys) nodeCandidates.push(sys);
+    } catch {}
+
+    for (const node of nodeCandidates) {
+      if (!node || !exists(node)) continue;
+      const dir = path.dirname(node);
+      const npmCli = [
+        path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        path.join(dir, 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+        path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+      ].find(exists);
+      if (npmCli && this._canExecute(node)) return { node, npmCli };
+    }
+    return null;
+  }
+
   /**
    * Resolve the npm CLI command. Uses system npm if available.
    */

package/src/paths.js

@@ -107,7 +107,13 @@ function getEnhancedEnv(baseEnv) {
   const env = { ...(baseEnv || process.env) };
   const extra = getExtraBinDirs();
   if (extra.length > 0) {
-    env.PATH = extra.join(SEP) + SEP + (env.PATH || '');
+    // Spreading process.env on Windows yields a "Path" key (not "PATH"), so a
+    // bare `env.PATH = …` would create a SECOND key holding only the extra dirs
+    // — no System32 — and libuv picks that truncated one when resolving spawned
+    // executables (cmd.exe / where.exe become unfindable). Update the existing
+    // case-insensitive path key in place instead.
+    const pathKey = Object.keys(env).find((k) => k.toLowerCase() === 'path') || 'PATH';
+    env[pathKey] = extra.join(SEP) + SEP + (env[pathKey] || '');
   }
   if (IS_WINDOWS) {
     // Force UTF-8 output from child processes on non-English Windows locales
@@ -179,8 +185,16 @@ function _addWindowsPaths(dirs) {
   // Portable Node.js installed by OpenAgents Launcher
   _push(dirs, path.join(HOME, '.openagents', 'nodejs'));
 
-  // Cursor CLI native installer
+  // Cursor CLI native installer.
+  //   - ~/.cursor/bin            : the curl|bash layout (also used by some setups)
+  //   - %LOCALAPPDATA%\cursor-agent : where the Windows installer
+  //     (irm 'https://cursor.com/install?win32=true' | iex) actually drops
+  //     cursor-agent.cmd / agent.cmd. The installer edits the *registry* PATH,
+  //     so an already-running launcher/daemon process never sees it via `where`
+  //     unless we add the dir here explicitly.
   _push(dirs, path.join(HOME, '.cursor', 'bin'));
+  if (localAppData) _push(dirs, path.join(localAppData, 'cursor-agent'));
+  _push(dirs, path.join(HOME, '.local', 'bin'));
 
   // Node.js install
   _push(dirs, path.join(programFiles, 'nodejs'));

package/src/tui.js

@@ -8,6 +8,7 @@
 
 const blessed = require('blessed');
 const { AgentConnector } = require('./index');
+const { loadAgentRows, connectAvailable } = require('./agent-rows');
 const path = require('path');
 const fs = require('fs');
 const { spawn } = require('child_process');
@@ -64,49 +65,6 @@ function getConnector() {
   return new AgentConnector({ configDir });
 }
 
-function loadAgentRows(connector) {
-  const config = connector.config.load();
-  const agents = config.agents || [];
-  const agentStatuses = connector.getDaemonStatus() || {};
-  const pid = connector.getDaemonPid();
-  const networks = config.networks || [];
-  return agents.map(agent => {
-    const info = agentStatuses[agent.name] || {};
-    const state = pid ? (info.state || 'stopped') : 'stopped';
-    let workspace = '';
-    if (agent.network) {
-      const net = networks.find(n => n.slug === agent.network || n.id === agent.network);
-      if (net) {
-        const slug = net.slug || net.id;
-        const isLocal = (net.endpoint || '').includes('localhost') || (net.endpoint || '').includes('127.0.0.1');
-        if (isLocal) workspace = `${net.endpoint}/${slug}`;
-        else workspace = `workspace.openagents.org/${slug}`;
-      } else {
-        workspace = agent.network;
-      }
-    }
-    let notReadyMsg = '';
-    let health = null;
-    try {
-      health = connector.healthCheck(agent.type || 'openclaw');
-      if (health && !health.ready) notReadyMsg = health.message || 'Not configured';
-    } catch {}
-
-    return {
-      name: agent.name,
-      type: agent.type || 'openclaw',
-      state,
-      workspace,
-      path: agent.path || '',
-      network: agent.network || '',
-      lastError: info.last_error || '',
-      notReadyMsg,
-      health,
-      configured: true,
-    };
-  });
-}
-
 function describeHealth(health) {
   if (!health) return '';
   if (!health.ready) return health.message || 'Not configured';
@@ -271,7 +229,7 @@ function createTUI() {
       const envFields = connector.registry.getEnvFields(agent.type);
       if (envFields && envFields.length > 0) items.push({ key: 'e', label: 'Configure' });
 
-      if (!agent.workspace) items.push({ key: 'c', label: 'Connect' });
+      if (connectAvailable(agent)) items.push({ key: 'c', label: 'Connect' });
       if (agent.workspace) items.push({ key: 'd', label: 'Disconnect' });
       if (agent.workspace) items.push({ key: 'w', label: 'Workspace' });
 
@@ -322,7 +280,8 @@ function createTUI() {
       const items = [];
       for (const r of agentRows) {
         const state = stateMarkup(r.state, !!r.workspace);
-        const ws = r.workspace || '';
+        // Local-only agents (no workspace) show a dimmed "(local)" marker.
+        const ws = r.workspace || `{gray-fg}${r.workspaceLabel}{/gray-fg}`;
         items.push(`  ${r.name.padEnd(22)} ${r.type.padEnd(14)} ${state.padEnd(30)} ${ws}`);
         // Detail row: working dir + config warning
         const details = [];
@@ -418,7 +377,7 @@ function createTUI() {
     if (isStopped) actions.push({ label: 'Start', key: 'start' });
     if (isRunning) actions.push({ label: 'Stop', key: 'stop' });
     if (agent.workspace) actions.push({ label: 'Open Workspace', key: 'open_workspace' });
-    if (!agent.workspace) actions.push({ label: 'Connect to Workspace', key: 'connect' });
+    if (connectAvailable(agent)) actions.push({ label: 'Connect to Workspace', key: 'connect' });
     if (agent.workspace) actions.push({ label: 'Disconnect from Workspace', key: 'disconnect' });
     actions.push({ label: 'Remove', key: 'remove' });
 
@@ -1403,7 +1362,7 @@ function createTUI() {
     Connect() {
       if (currentView !== 'main' || !selectedAgent()) return;
       const a = selectedAgent();
-      if (a.configured && !a.workspace) showConnectWorkspaceScreen(a.name);
+      if (connectAvailable(a)) showConnectWorkspaceScreen(a.name);
     },
     Disconnect() {
       if (currentView !== 'main' || !selectedAgent()) return;
@@ -1492,4 +1451,4 @@ function createTUI() {
 }
 
 function run() { createTUI(); }
-module.exports = { run };
+module.exports = { run, loadAgentRows, connectAvailable };

package/src/update-check.js

@@ -104,32 +104,75 @@ function detectInstallPrefix() {
   return null;
 }
 
-function findNpmBin() {
-  const nodeDir = path.dirname(process.execPath);
-  for (const name of ['npm', 'npm.cmd']) {
+/**
+ * Locate the npm executable next to the running node binary, falling back to
+ * a PATH lookup. On Windows the runnable file is `npm.cmd`; the extensionless
+ * `npm` shipped alongside it is a Unix shell script that cmd.exe / PowerShell
+ * cannot execute, so it must be checked AFTER `npm.cmd`. The opts are injectable
+ * to keep this testable across platforms.
+ */
+function findNpmBin(opts = {}) {
+  const platform = opts.platform || process.platform;
+  const nodeDir = opts.nodeDir || path.dirname(process.execPath);
+  const exists = opts.exists || fs.existsSync;
+  const names = platform === 'win32' ? ['npm.cmd', 'npm'] : ['npm'];
+  for (const name of names) {
     const candidate = path.join(nodeDir, name);
-    if (fs.existsSync(candidate)) return candidate;
+    if (exists(candidate)) return candidate;
   }
-  try {
-    return execSync(process.platform === 'win32' ? 'where npm' : 'which npm', {
+  // PATH fallback (injectable so tests can exercise the hard fallback
+  // deterministically regardless of the host OS).
+  const lookup = opts.lookup || (() =>
+    execSync(platform === 'win32' ? 'where npm' : 'which npm', {
       encoding: 'utf-8', timeout: 3000,
-    }).trim().split(/\r?\n/)[0];
-  } catch { return 'npm'; }
+    }).trim().split(/\r?\n/)[0]);
+  try {
+    return lookup() || (platform === 'win32' ? 'npm.cmd' : 'npm');
+  } catch { return platform === 'win32' ? 'npm.cmd' : 'npm'; }
 }
 
 /**
  * Run npm install to update to the latest version. Blocking.
- * Returns true on success.
+ * Returns true on success. `opts` are injectable for testing.
  */
-function runUpdate() {
-  const prefix = detectInstallPrefix();
-  const npmBin = findNpmBin();
+function runUpdate(opts = {}) {
+  const platform = opts.platform || process.platform;
+  const spawn = opts.spawn || spawnSync;
+  const npmBin = opts.npmBin || findNpmBin({ platform });
+  const prefix = opts.prefix !== undefined ? opts.prefix : detectInstallPrefix();
   const args = ['install', '--no-save', `${PKG_NAME}@latest`];
   if (prefix) args.push('--prefix', prefix);
   else args.push('-g');
+
+  // On Windows, npm.cmd is a batch file and must be invoked through cmd.exe.
+  // Passing the args via cmd.exe with shell:false lets Node quote paths that
+  // contain spaces (e.g. C:\Program Files\nodejs\npm.cmd) correctly.
+  let cmd, cmdArgs;
+  if (platform === 'win32') {
+    cmd = process.env.ComSpec || 'cmd.exe';
+    cmdArgs = ['/d', '/s', '/c', npmBin, ...args];
+  } else {
+    cmd = npmBin;
+    cmdArgs = args;
+  }
+
   process.stderr.write(`[launcher] Running: ${npmBin} ${args.join(' ')}\n`);
-  const r = spawnSync(npmBin, args, { stdio: 'inherit' });
-  return r.status === 0;
+  const r = spawn(cmd, cmdArgs, { stdio: 'inherit' });
+
+  // spawn failed to even start the process (ENOENT / EINVAL / EACCES ...).
+  if (r && r.error) {
+    process.stderr.write(`[launcher] Failed to run npm (${cmd}): ${r.error.message}\n`);
+    return false;
+  }
+  // npm started but exited non-zero. Its own stderr was already streamed via
+  // stdio:'inherit'; surface the exit code so the failure isn't silent.
+  if (!r || r.status !== 0) {
+    const code = r ? r.status : 'unknown';
+    const sig = r && r.signal ? ` (signal ${r.signal})` : '';
+    process.stderr.write(`[launcher] npm exited with code ${code}${sig}\n`);
+    return false;
+  }
+  return true;
 }
 
 /**
@@ -179,5 +222,6 @@ module.exports = {
   checkForUpdate,
   notifyAndMaybeUpdate,
   runUpdate,
+  findNpmBin,
   currentVersion,
 };