@openagents-org/agent-launcher 0.2.132 → 0.2.134

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagents-org/agent-launcher",
-  "version": "0.2.132",
+  "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/base.js

@@ -230,9 +230,109 @@ class BaseAdapter {
       await this._postStatusReport(payload);
     } else if (action === 'routines') {
       await this._postRoutinesReport(payload);
+    } else if (action === 'skill.install') {
+      await this._handleSkillInstall(payload);
+    } else if (action === 'skill.uninstall') {
+      await this._handleSkillUninstall(payload);
     }
   }
 
+  /**
+   * Install a Skill Hub catalog skill into this agent's local skills
+   * directory, then report the result back to the workspace so the UI can
+   * show installing → installed / failed. Errors are logged loudly and
+   * surfaced as a `failed` status — never swallowed.
+   *
+   * payload: { action: "skill.install", skill: { id, name, source_repo, source_path } }
+   */
+  async _handleSkillInstall(payload) {
+    const installer = require('../skill-installer');
+    const skill = (payload && payload.skill) || null;
+    const skillId = skill && (skill.id || skill.skill_id);
+    if (!skillId) {
+      this._log('skill.install: missing skill metadata in payload — ignoring');
+      return;
+    }
+    this._log(`skill.install: starting install of "${skillId}" (type=${this.agentType}, dir=${this.workingDir || process.cwd()})`);
+
+    // Best-effort "installing" ping so the UI flips immediately even if the
+    // initial DB write from the request hasn't propagated to this client.
+    try {
+      await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
+        skillId, state: 'installing',
+      });
+    } catch (e) {
+      this._log(`skill.install: could not report 'installing' (non-fatal): ${e && e.message ? e.message : e}`);
+    }
+
+    try {
+      const result = installer.installSkill({
+        skill,
+        agentType: this.agentType,
+        workingDir: this.workingDir,
+        log: (m) => this._log(`skill.install: ${m}`),
+      });
+      try {
+        await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
+          skillId, state: 'installed', path: result.path, partial: result.partial === true,
+        });
+      } catch (e) {
+        this._log(`skill.install: installed on disk but failed to report 'installed': ${e && e.message ? e.message : e}`);
+      }
+      this._log(`skill.install: SUCCESS "${skillId}" → ${result.path}${result.partial ? ' (partial)' : ''}`);
+      await this._onSkillsChanged();
+    } catch (e) {
+      const msg = e && e.message ? e.message : String(e);
+      this._log(`skill.install: FAILED "${skillId}": ${msg}`);
+      try {
+        await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
+          skillId, state: 'failed', error: msg,
+        });
+      } catch (e2) {
+        this._log(`skill.install: also failed to report 'failed': ${e2 && e2.message ? e2.message : e2}`);
+      }
+    }
+  }
+
+  /**
+   * Remove a previously-installed skill from disk and report `uninstalled`.
+   */
+  async _handleSkillUninstall(payload) {
+    const installer = require('../skill-installer');
+    const skill = (payload && payload.skill) || null;
+    const skillId = skill && (skill.id || skill.skill_id);
+    if (!skillId) {
+      this._log('skill.uninstall: missing skill metadata in payload — ignoring');
+      return;
+    }
+    try {
+      const result = installer.uninstallSkill({
+        skill,
+        agentType: this.agentType,
+        workingDir: this.workingDir,
+        log: (m) => this._log(`skill.uninstall: ${m}`),
+      });
+      this._log(`skill.uninstall: "${skillId}" removed=${result.removed}`);
+      try {
+        await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
+          skillId, state: 'uninstalled',
+        });
+      } catch (e) {
+        this._log(`skill.uninstall: failed to report status: ${e && e.message ? e.message : e}`);
+      }
+      await this._onSkillsChanged();
+    } catch (e) {
+      const msg = e && e.message ? e.message : String(e);
+      this._log(`skill.uninstall: FAILED "${skillId}": ${msg}`);
+    }
+  }
+
+  /**
+   * Hook for subclasses to react to a change in the installed-skills set
+   * (e.g. rebuild prompt context). Default: no-op.
+   */
+  async _onSkillsChanged() {}
+
   /**
    * Post a chat message back to the requesting channel summarizing agent
    * name, type, agent-launcher version, uptime, and network. Used by the

package/src/adapters/codex.js

@@ -168,7 +168,7 @@ class CodexAdapter extends BaseAdapter {
   }
 
   _buildSystemContext(channelName) {
-    return buildOpenclawSystemPrompt({
+    const base = buildOpenclawSystemPrompt({
       agentName: this.agentName,
       workspaceId: this.workspaceId,
       channelName,
@@ -177,6 +177,38 @@ class CodexAdapter extends BaseAdapter {
       mode: this._mode,
       disabledModules: this.disabledModules,
     });
+    const skillsSection = this._buildInstalledSkillsSection();
+    return skillsSection ? `${base}\n\n${skillsSection}` : base;
+  }
+
+  /**
+   * Codex has no native skills-directory discovery (unlike Claude Code), so
+   * we inject installed Skill Hub skills directly into its context. Each
+   * skill's SKILL.md lives at <workingDir>/.codex/skills/<id>/SKILL.md and
+   * Codex (running with cwd=workingDir, full file access) can read it.
+   */
+  _buildInstalledSkillsSection() {
+    let skills = [];
+    try {
+      const installer = require('../skill-installer');
+      skills = installer.listInstalledSkills({
+        agentType: this.agentType || 'codex',
+        workingDir: this.workingDir,
+      });
+    } catch {
+      return '';
+    }
+    if (!skills.length) return '';
+    const lines = skills.map((s) => {
+      const desc = s.description ? ` — ${s.description}` : '';
+      return `- **${s.name}** (\`${s.id}\`)${desc}\n  Read its instructions: \`cat ${s.skillMd}\``;
+    });
+    return (
+      '## Installed Skills\n' +
+      'You have the following skills installed. When a task matches a skill, ' +
+      'read its `SKILL.md` (via the `cat` command shown) and follow it:\n' +
+      lines.join('\n')
+    );
   }
 
   // ------------------------------------------------------------------
@@ -205,14 +237,17 @@ class CodexAdapter extends BaseAdapter {
     } catch {}
   }
 
-  async _onControlAction(action, _payload) {
+  async _onControlAction(action, payload) {
     if (action === 'stop') {
       for (const [channel, proc] of Object.entries(this._channelProcesses)) {
         await this._stopProcess(proc);
         delete this._channelProcesses[channel];
         try { await this.sendStatus(channel, 'Execution stopped by user'); } catch {}
       }
+      return;
     }
+    // Shared actions (status, routines, skill.install, skill.uninstall).
+    await super._onControlAction(action, payload);
   }
 
   // ------------------------------------------------------------------

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,11 +123,24 @@ 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 {}
 
+    // Newly created agents are local-only until connected to a workspace.
+    // 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('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)) {
       if (!flags.install) {
         print(`Runtime '${type}' is not installed. Run: agn install ${type}`);
@@ -278,9 +291,29 @@ async function cmdRuntimes(connector) {
 
 async function cmdConnect(connector, flags, positional) {
   const name = positional[0];
-  const token = positional[1] || flags.token;
-  if (!name || !token) {
+  // Token resolution order: positional arg / --token flag, then env vars.
+  // OPENAGENTS_WORKSPACE_TOKEN is preferred; OA_WORKSPACE_TOKEN is supported
+  // for compatibility with the existing mcp-server env var.
+  const token = positional[1]
+    || flags.token
+    || process.env.OPENAGENTS_WORKSPACE_TOKEN
+    || process.env.OA_WORKSPACE_TOKEN;
+
+  if (!name) {
     print('Usage: agn connect <agent-name> <token>');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!token) {
+    // 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('Workspace token is required.');
+    print('Local-only agents do not appear in Workspace Dashboard until connected.');
+    print('Run:');
+    print(`  agn connect ${name} <workspace-token>`);
+    process.exitCode = 1;
     return;
   }
 

package/src/installer.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execSync, exec } = require('child_process');
-const { whichBinary, getEnhancedEnv, getRuntimePrefix } = require('./paths');
+const { whichBinary, getEnhancedEnv, getRuntimePrefix, clearBinaryLookupCache } = require('./paths');
 const { EnvManager } = require('./env');
 
 const STATUS_CACHE_TTL_MS = 10000;
@@ -90,7 +90,15 @@ class Installer {
     // Fallback: check if binary exists on PATH (system install)
     const binaryPath = this._whichBinary(agentType);
     if (!binaryPath) {
-      try { fs.unlinkSync(path.join(this.markersDir, agentType)); } catch {}
+      // 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
+      // marker is the ground truth of what we just installed; UI was
+      // silently showing "not installed" right after a successful install
+      // because earlier code aggressively deleted the marker here.
+      if (this._hasMarker(agentType)) {
+        return { installed: true, managed: true, location: 'marker' };
+      }
       return { installed: false, managed: false, location: null };
     }
 
@@ -406,29 +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;
     }
 
-    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');
@@ -448,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
@@ -463,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));
         }
@@ -579,6 +630,8 @@ class Installer {
       cmd = this._resolveNpmCommand(args);
     }
 
+    cmd = this._wrapForWindowsShell(cmd);
+
     if (onData) onData(`$ ${cmd}\n\n`);
 
     const env = this._buildShellEnv();
@@ -587,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');
@@ -708,6 +761,12 @@ class Installer {
       fs.mkdirSync(this.markersDir, { recursive: true });
       fs.writeFileSync(path.join(this.markersDir, agentType), '', 'utf-8');
     } catch {}
+
+    // 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.
+    try { clearBinaryLookupCache(); } catch {}
   }
 
   _markUninstalled(agentType) {
@@ -727,6 +786,9 @@ class Installer {
       const markerFile = path.join(this.markersDir, agentType);
       if (fs.existsSync(markerFile)) fs.unlinkSync(markerFile);
     } catch {}
+
+    // Symmetric with _markInstalled: invalidate so detection re-runs cleanly.
+    try { clearBinaryLookupCache(); } catch {}
   }
 
   // -- Shell env + exec --
@@ -790,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;
@@ -897,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);
@@ -1018,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.
    */
@@ -1040,6 +1155,24 @@ class Installer {
     return `${npmBin} ${args}`;
   }
 
+  /**
+   * Wrap a command in `powershell.exe -Command "..."` when (a) we're on Windows
+   * and (b) the command uses PowerShell-only tokens like `irm`, `iex`,
+   * `Invoke-RestMethod`, etc. The launcher's install shell is cmd.exe, which
+   * doesn't recognize these aliases — without wrapping, e.g. Cursor's
+   * `irm '…' | iex` exits 255. Skips commands already prefixed with
+   * `powershell`/`powershell.exe` so we don't double-wrap.
+   */
+  _wrapForWindowsShell(cmd) {
+    if (!cmd || process.platform !== 'win32') return cmd;
+    const trimmed = cmd.trimStart();
+    if (/^("[^"]*\\)?powershell(\.exe)?["']?\s/i.test(trimmed)) return cmd;
+    const psTokens = /\b(irm|iwr|iex|Invoke-RestMethod|Invoke-WebRequest|Invoke-Expression|Expand-Archive|Get-[A-Z]\w*|Set-[A-Z]\w*)\b/;
+    if (!psTokens.test(cmd)) return cmd;
+    const escaped = cmd.replace(/"/g, '\\"');
+    return `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "${escaped}"`;
+  }
+
   _execShell(cmd, timeoutMs = 300000) {
     return new Promise((resolve, reject) => {
       const env = this._buildShellEnv();
@@ -1049,7 +1182,8 @@ class Installer {
         shell = env.ComSpec || 'C:\\Windows\\System32\\cmd.exe';
       }
 
-      exec(cmd, {
+      const finalCmd = this._wrapForWindowsShell(cmd);
+      exec(finalCmd, {
         encoding: 'utf-8',
         timeout: timeoutMs,
         shell,

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'));
@@ -264,6 +278,9 @@ function _addUnixPaths(dirs) {
 
   // cargo
   _push(dirs, path.join(HOME, '.cargo', 'bin'));
+
+  // Cursor CLI native installer (curl https://cursor.com/install | bash)
+  _push(dirs, path.join(HOME, '.cursor', 'bin'));
 }
 
 // ---- macOS-specific ----
@@ -336,11 +353,23 @@ function getCorePrefix() {
   return path.join(HOME, '.openagents', 'core');
 }
 
+/**
+ * Reset the two 30s caches that back binary detection. Call this after
+ * install / uninstall so a freshly-created bin dir (e.g. ~/.cursor/bin)
+ * isn't masked by a pre-install snapshot of getExtraBinDirs(), and so a
+ * `whichBinary(name) === null` cached before install doesn't survive.
+ */
+function clearBinaryLookupCache() {
+  extraBinDirsCache = { value: null, at: 0, path: '' };
+  whichBinaryCache.clear();
+}
+
 module.exports = {
   getExtraBinDirs,
   getEnhancedPATH,
   getEnhancedEnv,
   whichBinary,
+  clearBinaryLookupCache,
   getRuntimePrefix,
   getCorePrefix,
   IS_WINDOWS,

package/src/skill-installer.js

@@ -0,0 +1,382 @@
+'use strict';
+
+/**
+ * Skill installer — installs third-party Agent Skills (Skill Hub catalog
+ * entries) into a local agent's skills directory.
+ *
+ * Responsibilities (all independently testable):
+ *  - Resolve the per-agent-type skills directory.
+ *  - Fetch the skill's files from its source repo into that directory.
+ *  - Verify a SKILL.md actually landed (no silent success).
+ *  - Enumerate already-installed skills (used to inject context for agents,
+ *    like Codex, that don't auto-discover a skills directory).
+ *
+ * The "how bytes arrive" step is injected via a `fetcher` so production can
+ * use git/https while tests use a local fixture copier. The directory
+ * resolution, file verification, and error handling — the parts that decide
+ * end-to-end correctness — are exercised directly.
+ *
+ * A catalog skill is identified by `source_repo` + `source_path`
+ * (e.g. "anthropics/skills" + "skills/claude-api"), mirroring the Skill Hub
+ * catalog in workspace/backend/app/skill_catalog.py.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Resolve the skills directory for a given agent type, rooted at the agent's
+ * working directory. Different runtimes look in different places:
+ *  - claude  → <workingDir>/.claude/skills   (Claude Code auto-discovers here)
+ *  - cursor  → <workingDir>/.cursor/skills   (Cursor auto-discovers here)
+ *  - codex   → <workingDir>/.codex/skills    (no native discovery; the Codex
+ *              adapter injects these into the prompt — see codex.js)
+ *  - default → <workingDir>/.agent/skills
+ *
+ * @param {string} agentType
+ * @param {string} [workingDir]
+ * @returns {string} absolute path to the skills directory
+ */
+function skillsDirForAgentType(agentType, workingDir) {
+  const base = workingDir || process.cwd();
+  switch ((agentType || '').toLowerCase()) {
+    case 'claude':
+      return path.join(base, '.claude', 'skills');
+    case 'cursor':
+      return path.join(base, '.cursor', 'skills');
+    case 'codex':
+      return path.join(base, '.codex', 'skills');
+    default:
+      return path.join(base, '.agent', 'skills');
+  }
+}
+
+/**
+ * Normalize a catalog skill object (snake_case from backend / camelCase from
+ * UI) to a stable shape.
+ */
+// Validation patterns. The skill metadata comes from a workspace.agent.control
+// event, which any holder of the workspace token could craft — so the launcher
+// does NOT trust it blindly even though the backend only emits catalog entries.
+// These guards prevent path traversal (a malicious id/source_path escaping the
+// skills dir) and argument injection (a value starting with "-" being read as a
+// git/curl flag).
+const _ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;          // no leading dash, no slashes/dots-only
+const _REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;  // owner/repo
+const _PATH_SEG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;    // each path segment
+
+function _assertSafeId(id) {
+  if (typeof id !== 'string' || id === '.' || id === '..' || !_ID_RE.test(id)) {
+    throw new Error(`unsafe skill id "${id}" (must match ${_ID_RE})`);
+  }
+}
+
+function _assertSafeSourceRepo(repo) {
+  if (repo && !_REPO_RE.test(repo)) {
+    throw new Error(`unsafe source_repo "${repo}" (expected owner/repo)`);
+  }
+}
+
+function _assertSafeSourcePath(sp) {
+  if (!sp) return;
+  const segs = sp.replace(/^\/+|\/+$/g, '').split('/');
+  for (const seg of segs) {
+    if (seg === '..' || !_PATH_SEG_RE.test(seg)) {
+      throw new Error(`unsafe source_path "${sp}" (segment "${seg}")`);
+    }
+  }
+}
+
+function normalizeSkill(skill) {
+  if (!skill || typeof skill !== 'object') {
+    throw new Error('skill metadata missing');
+  }
+  const id = skill.id || skill.skill_id || skill.skillId;
+  if (!id) throw new Error('skill metadata missing id');
+  _assertSafeId(id);
+  const sourceRepo = skill.source_repo || skill.sourceRepo || '';
+  const sourcePath = skill.source_path || skill.sourcePath || '';
+  _assertSafeSourceRepo(sourceRepo);
+  _assertSafeSourcePath(sourcePath);
+  return {
+    id,
+    name: skill.name || id,
+    description: skill.description || '',
+    sourceRepo,
+    sourcePath,
+  };
+}
+
+/**
+ * Resolve <skillsDir>/<id> and assert it stays inside <skillsDir>. Belt-and-
+ * suspenders on top of _assertSafeId so we never read/write/delete outside the
+ * agent's skills directory.
+ */
+function _safeSkillDir(skillsDir, id) {
+  const dest = path.resolve(skillsDir, id);
+  const root = path.resolve(skillsDir);
+  if (dest !== path.join(root, id) || !dest.startsWith(root + path.sep)) {
+    throw new Error(`refusing to operate on "${dest}" outside skills dir "${root}"`);
+  }
+  return dest;
+}
+
+/**
+ * Default fetcher: download the skill's files from GitHub into `destDir`.
+ *
+ * Strategy, in order of preference:
+ *   1. git sparse-checkout of `<source_repo>` limited to `<source_path>`
+ *      (gets the full skill directory — scripts, references, assets).
+ *   2. Fallback: fetch just `SKILL.md` over HTTPS from raw.githubusercontent.
+ *
+ * Throws if neither strategy produces a SKILL.md. Never silently no-ops.
+ *
+ * @param {{skill: object, destDir: string, log?: function}} args
+ */
+function defaultFetcher({ skill, destDir, log }) {
+  const { sourceRepo, sourcePath } = skill;
+  if (!sourceRepo) {
+    throw new Error(`skill "${skill.id}" has no source_repo; cannot fetch`);
+  }
+  const _log = log || (() => {});
+
+  // ── Strategy 1: git sparse-checkout ──
+  if (_gitAvailable()) {
+    let tmp;
+    try {
+      tmp = fs.mkdtempSync(path.join(os.tmpdir(), `skill-${skill.id}-`));
+      const repoUrl = `https://github.com/${sourceRepo}.git`;
+      const sp = sourcePath || '.';
+      execFileSync('git', ['clone', '--depth', '1', '--filter=blob:none', '--sparse', repoUrl, tmp],
+        { stdio: 'pipe', timeout: 120000 });
+      execFileSync('git', ['-C', tmp, 'sparse-checkout', 'set', sp],
+        { stdio: 'pipe', timeout: 60000 });
+      const srcDir = path.join(tmp, sp);
+      if (!fs.existsSync(srcDir)) {
+        throw new Error(`source path "${sp}" not found in ${sourceRepo}`);
+      }
+      _copyDir(srcDir, destDir);
+      _log(`Fetched ${sourceRepo}/${sp} via git sparse-checkout`);
+      return { partial: false };
+    } catch (e) {
+      _log(`git fetch failed (${e && e.message ? e.message : e}); trying raw SKILL.md`);
+    } finally {
+      if (tmp) { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch {} }
+    }
+  }
+
+  // ── Strategy 2: raw SKILL.md over HTTPS ──
+  const sp = (sourcePath || '').replace(/^\/+|\/+$/g, '');
+  for (const branch of ['main', 'master']) {
+    const rawUrl = `https://raw.githubusercontent.com/${sourceRepo}/${branch}/${sp ? sp + '/' : ''}SKILL.md`;
+    try {
+      const body = _httpGetSync(rawUrl);
+      if (body && body.trim()) {
+        fs.mkdirSync(destDir, { recursive: true });
+        fs.writeFileSync(path.join(destDir, 'SKILL.md'), body, 'utf-8');
+        _log(`Fetched SKILL.md via HTTPS (${branch})`);
+        // Only the SKILL.md was retrieved — any bundled scripts/references the
+        // skill ships were NOT fetched. Signal "partial" so installSkill can
+        // warn; skills that depend on those files may not be fully functional.
+        return { partial: true };
+      }
+    } catch {
+      // try next branch
+    }
+  }
+
+  throw new Error(`could not fetch skill "${skill.id}" from ${sourceRepo}/${sourcePath}`);
+}
+
+/**
+ * Install a catalog skill into the agent's skills directory.
+ *
+ * @param {object} args
+ * @param {object} args.skill        catalog entry (id, name, source_repo, source_path)
+ * @param {string} args.agentType    e.g. "claude", "codex"
+ * @param {string} [args.workingDir] agent working dir; defaults to cwd
+ * @param {function} [args.fetcher]  ({skill, destDir, log}) => void; defaults to git/https
+ * @param {function} [args.log]
+ * @returns {{path: string, skillId: string}}
+ * @throws {Error} with a clear, surfaceable message on any failure
+ */
+function installSkill({ skill, agentType, workingDir, fetcher, log }) {
+  const norm = normalizeSkill(skill);
+  const _log = log || (() => {});
+  const skillsDir = skillsDirForAgentType(agentType, workingDir);
+  const destDir = _safeSkillDir(skillsDir, norm.id);
+
+  // Ensure the parent skills directory exists / is writable. A clear error
+  // here distinguishes "no permission / bad working dir" from fetch failures.
+  try {
+    fs.mkdirSync(destDir, { recursive: true });
+  } catch (e) {
+    throw new Error(
+      `cannot create skills directory "${destDir}" for agent type "${agentType}": ` +
+      `${e && e.message ? e.message : e}`
+    );
+  }
+
+  // Re-installing: start clean so stale files from a prior version don't linger.
+  try {
+    for (const entry of fs.readdirSync(destDir)) {
+      fs.rmSync(path.join(destDir, entry), { recursive: true, force: true });
+    }
+  } catch {}
+
+  const doFetch = fetcher || defaultFetcher;
+  const fetchResult = doFetch({ skill: norm, destDir, log: _log }) || {};
+
+  // No silent success: a real install must produce a SKILL.md.
+  const skillMd = _findSkillMd(destDir);
+  if (!skillMd) {
+    throw new Error(
+      `install of "${norm.id}" produced no SKILL.md in ${destDir} ` +
+      `(fetched from ${norm.sourceRepo}/${norm.sourcePath})`
+    );
+  }
+
+  // A partial fetch (SKILL.md only, bundled scripts/references missing) is a
+  // known degraded state — succeed but WARN loudly so it isn't mistaken for a
+  // fully-functional install.
+  const partial = fetchResult.partial === true;
+  if (partial) {
+    _log(
+      `WARNING: only SKILL.md was fetched for "${norm.id}" — bundled files ` +
+      `(scripts/references) were NOT installed; skills that need them may not work fully`
+    );
+  }
+
+  _log(`Installed skill "${norm.id}" → ${destDir}${partial ? ' (partial: SKILL.md only)' : ''}`);
+  return { path: destDir, skillId: norm.id, partial };
+}
+
+/**
+ * Remove an installed skill directory. Idempotent.
+ *
+ * @returns {{path: string, removed: boolean, skillId: string}}
+ */
+function uninstallSkill({ skill, agentType, workingDir, log }) {
+  const norm = normalizeSkill(skill);
+  const _log = log || (() => {});
+  const destDir = _safeSkillDir(skillsDirForAgentType(agentType, workingDir), norm.id);
+  let removed = false;
+  if (fs.existsSync(destDir)) {
+    fs.rmSync(destDir, { recursive: true, force: true });
+    removed = true;
+    _log(`Uninstalled skill "${norm.id}" from ${destDir}`);
+  }
+  return { path: destDir, removed, skillId: norm.id };
+}
+
+/**
+ * Enumerate installed third-party skills under the agent's skills directory.
+ * Each returned entry parses the SKILL.md frontmatter for name/description.
+ * Used by adapters (e.g. Codex) that must inject skill availability into the
+ * model context because the runtime doesn't auto-discover skills.
+ *
+ * @returns {Array<{id: string, name: string, description: string, path: string, skillMd: string}>}
+ */
+function listInstalledSkills({ agentType, workingDir }) {
+  const skillsDir = skillsDirForAgentType(agentType, workingDir);
+  let entries;
+  try {
+    entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const dir = path.join(skillsDir, ent.name);
+    const skillMd = _findSkillMd(dir);
+    if (!skillMd) continue;
+    const meta = _parseSkillFrontmatter(skillMd);
+    out.push({
+      id: ent.name,
+      name: meta.name || ent.name,
+      description: meta.description || '',
+      path: dir,
+      skillMd,
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function _gitAvailable() {
+  try {
+    execFileSync('git', ['--version'], { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function _findSkillMd(dir) {
+  // Prefer a top-level SKILL.md; fall back to any *.md so single-file skills
+  // (e.g. fetched as openagents-workspace.md) still count as installed.
+  const candidates = ['SKILL.md', 'skill.md', 'Skill.md'];
+  for (const c of candidates) {
+    const p = path.join(dir, c);
+    if (fs.existsSync(p)) return p;
+  }
+  try {
+    const md = fs.readdirSync(dir).find((f) => f.toLowerCase().endsWith('.md'));
+    if (md) return path.join(dir, md);
+  } catch {}
+  return null;
+}
+
+function _parseSkillFrontmatter(skillMdPath) {
+  try {
+    const text = fs.readFileSync(skillMdPath, 'utf-8');
+    const m = text.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!m) return {};
+    const out = {};
+    for (const line of m[1].split('\n')) {
+      const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+      if (kv) out[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+function _copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const ent of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, ent.name);
+    const d = path.join(dest, ent.name);
+    if (ent.isDirectory()) _copyDir(s, d);
+    else if (ent.isFile()) fs.copyFileSync(s, d);
+  }
+}
+
+// Blocking GET used only by defaultFetcher's HTTPS fallback (which runs off
+// the hot path inside a try/catch). Uses curl for redirect handling; returns
+// the body string or throws. git sparse-checkout is the primary strategy, so
+// this only matters on hosts that have curl but not git.
+function _httpGetSync(url) {
+  try {
+    const body = execFileSync('curl', ['-fsSL', url], { timeout: 60000, maxBuffer: 10 * 1024 * 1024 });
+    return body.toString('utf-8');
+  } catch (e) {
+    throw new Error(`HTTPS fetch failed for ${url}: ${e && e.message ? e.message : e}`);
+  }
+}
+
+module.exports = {
+  skillsDirForAgentType,
+  installSkill,
+  uninstallSkill,
+  listInstalledSkills,
+  normalizeSkill,
+  defaultFetcher,
+};

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,
 };

package/src/workspace-client.js

@@ -357,6 +357,30 @@ class WorkspaceClient {
     }
   }
 
+  /**
+   * Report skill-install progress/result back to the workspace.
+   *
+   * POST /v1/workspaces/{id}/members/{agentName}/skills/status
+   * Body: { skill_id, state: "installing"|"installed"|"failed"|"uninstalled",
+   *         path?, error? }
+   *
+   * The backend updates WorkspaceMember.enabled_skills.skill_status so the
+   * Skill Hub UI can render installing / installed / failed states. Best
+   * effort — returns the updated payload or throws (caller decides).
+   */
+  async reportSkillStatus(workspaceId, agentName, token, { skillId, state, path: installPath, error, partial } = {}) {
+    const body = { skill_id: skillId, state };
+    if (installPath) body.path = installPath;
+    if (error) body.error = String(error).slice(0, 2000);
+    if (partial) body.partial = true;
+    const data = await this._post(
+      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(agentName)}/skills/status`,
+      body,
+      this._wsHeaders(token),
+    );
+    return data.data || data;
+  }
+
   /**
    * Get session/channel info via GET /v1/workspaces/{id}/channels/{name}.
    */