@openagents-org/agent-launcher 0.2.186 → 0.2.187

package/src/adapters/hermes.js

@@ -25,6 +25,7 @@ const { spawn, bridgeSpawn } = require('../wsl');
 
 const BaseAdapter = require('./base');
 const { buildOpenclawSystemPrompt } = require('./workspace-prompt');
+const { REASON } = require('./health-status');
 const { whichBinary, whereBinary } = require('../paths');
 
 const IS_WINDOWS = process.platform === 'win32';
@@ -123,6 +124,34 @@ class HermesAdapter extends BaseAdapter {
     return null;
   }
 
+  /**
+   * Preflight gate (run by the daemon before join). Hermes can do nothing
+   * without its CLI, so when none can be resolved we surface a precise
+   * 'runtime_missing' reason and skip the workspace join — instead of joining,
+   * reporting "online" and then failing every message. That contradiction is
+   * exactly what users hit: the workspace showed a green hermes and "all set"
+   * while the smoke test on the same screen said "Not installed", because
+   * `create_agent --install` treats a failed third-party install script as a
+   * warning and connects the agent anyway.
+   *
+   * Re-resolves rather than trusting the constructor's lookup: an install that
+   * landed after the daemon started must not need a restart to be seen. NOTE:
+   * 'runtime_missing' (binary gone/never landed at run time), NOT
+   * 'not_installed' — install detection lives in the installer.
+   */
+  preflight() {
+    if (!this._hermesBin) this._hermesBin = this._findHermesBinary();
+    if (!this._hermesBin) {
+      return {
+        ok: false,
+        reason: REASON.RUNTIME_MISSING,
+        message: `Hermes CLI not found — install with: ${HERMES_INSTALL_HINT}`,
+      };
+    }
+    this._log(`Hermes CLI resolved: ${this._hermesBin}`);
+    return { ok: true };
+  }
+
   _resolveProfile(explicit, agentName) {
     if (explicit && explicit !== '' && explicit !== 'auto') return explicit;
     // Match agent name to an existing ~/.hermes/profiles/<name> if present
@@ -371,6 +400,17 @@ class HermesAdapter extends BaseAdapter {
     const sender = msg.senderName || msg.senderType || 'user';
     this._log(`Processing workspace message from ${sender} in ${msgChannel}`);
 
+    // Re-resolve per message: the constructor's lookup is a snapshot, and an
+    // agent that was created before its CLI finished installing would
+    // otherwise stay broken until the daemon restarts.
+    if (!this._hermesBin) this._hermesBin = this._findHermesBinary();
+    if (!this._hermesBin) {
+      const message = `Hermes CLI not found — install with: ${HERMES_INSTALL_HINT}`;
+      this._reportStatus(REASON.RUNTIME_MISSING, message);
+      await this.sendError(msgChannel, message);
+      return;
+    }
+
     await this._autoTitleChannel(msgChannel, content);
     await this.sendStatus(msgChannel, 'thinking...');
 

package/src/adapters/llm-direct.js

@@ -158,7 +158,8 @@ class LlmDirectAdapter extends BaseAdapter {
       'Authorization': `Bearer ${this._apiKey}`,
     };
     const payload = JSON.stringify({
-      model: this._model || 'gpt-4o',
+      // The model picked in the workspace, which modelLabel() reports, wins.
+      model: this.modelLabel() || 'gpt-4o',
       messages,
       stream: true,
     });

package/src/adapters/utils.js

@@ -88,19 +88,22 @@ function formatAttachmentsForPrompt(
       const url = att.url || `${base}/v1/files/${fileId}`;
       const curl = isWindows ? 'curl.exe' : 'curl';
       const tmpDir = isWindows ? '$env:TEMP' : '/tmp';
+      // A web upload's filename is its workspace path (uploaded_files/<stamp>_<name>)
+      // and curl -o does not create folders, so that download failed with exit 23.
+      const localName = filename.split(/[\\/]/).pop() || fileId || 'attachment';
       if (contentType.startsWith('image/')) {
         lines.push(
           `- Image: ${filename} (file_id: ${fileId}) — ` +
           `download with curl, then use your Read tool on the local file to view it:\n` +
-          `  Step 1: ${curl} -s -H "X-Workspace-Token: ${tokenExpr}" "${url}" -o ${tmpDir}/${filename}\n` +
-          `  Step 2: Use the Read tool on ${tmpDir}/${filename} to see the image`
+          `  Step 1: ${curl} -s -H "X-Workspace-Token: ${tokenExpr}" "${url}" -o ${tmpDir}/${localName}\n` +
+          `  Step 2: Use the Read tool on ${tmpDir}/${localName} to see the image`
         );
       } else {
         lines.push(
           `- File: ${filename} (file_id: ${fileId}, type: ${contentType}) — ` +
           `download with curl, then use your Read tool on the local file:\n` +
-          `  Step 1: ${curl} -s -H "X-Workspace-Token: ${tokenExpr}" "${url}" -o ${tmpDir}/${filename}\n` +
-          `  Step 2: Use the Read tool on ${tmpDir}/${filename} to read the file`
+          `  Step 1: ${curl} -s -H "X-Workspace-Token: ${tokenExpr}" "${url}" -o ${tmpDir}/${localName}\n` +
+          `  Step 2: Use the Read tool on ${tmpDir}/${localName} to read the file`
         );
       }
     } else {

package/src/daemon.js

@@ -9,6 +9,7 @@ const { execSync, execFileSync } = require('child_process');
 const { spawn } = require('./wsl');
 const os = require('os');
 const { WorkspaceClient } = require('./workspace-client');
+const { listEndpointModels } = require('./model-list');
 const { getEnhancedEnv, whichBinary, IS_WINDOWS, defaultAgentWorkdir } = require('./paths');
 
 /**
@@ -44,6 +45,23 @@ function filesystemRoots(platform = os.platform(), exists = fs.existsSync) {
   return roots;
 }
 
+/**
+ * Hostname of a configured base URL, or null when there is none. The roster
+ * carries only this: a relay URL can hold a credential in its userinfo or
+ * path. A value written without a scheme (`localhost:4000`) still names a host.
+ */
+function endpointHost(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  for (const candidate of [raw, `http://${raw}`]) {
+    try {
+      const host = new URL(candidate).hostname.toLowerCase();
+      if (host) return host;
+    } catch {}
+  }
+  return null;
+}
+
 /**
  * Agent process lifecycle manager.
  *
@@ -326,7 +344,8 @@ class Daemon {
         // Model/key: per-agent env override, else the type-level saved env.
         // Both power the workspace agent cards; the key goes out MASKED only,
         // so the edit form can show a key is configured without the secret
-        // ever leaving the device.
+        // ever leaving the device. The endpoint goes out as a hostname, so
+        // the workspace can tell a relay from the vendor its model list is for.
         let typeEnv = {};
         try { typeEnv = this.envManager.load(a.type) || {}; } catch {}
         const model = (a.env && a.env.LLM_MODEL) || typeEnv.LLM_MODEL || null;
@@ -338,6 +357,7 @@ class Daemon {
           model: model || null,
           workingDir: a.path || null,
           apiKeyMasked: apiKey ? maskApiKey(apiKey) : null,
+          baseUrlHost: endpointHost(this._configuredBaseUrl(a, typeEnv)),
           probe: this._probes[a.name] || null,
         });
       }
@@ -347,6 +367,52 @@ class Daemon {
     return roster;
   }
 
+  /**
+   * The base URL this agent's CLI is pointed at, found the way _buildAgentEnv
+   * builds its env: LLM_BASE_URL or a provider variable (OPENAI_BASE_URL,
+   * ANTHROPIC_BASE_URL, …) saved for it or mapped by resolve_env, and failing
+   * those, the daemon's own environment for the provider variable this type's
+   * LLM_BASE_URL maps to, which the spawned CLI inherits.
+   */
+  _configuredBaseUrl(a, typeEnv) {
+    const saved = { ...typeEnv, ...(a.env || {}) };
+    let env = saved;
+    try { env = { ...saved, ...this.envManager.resolve(a.type, saved, this.registry) }; } catch {}
+    const set = (v) => String(v || '').trim();
+    if (set(env.LLM_BASE_URL)) return env.LLM_BASE_URL;
+    const key = Object.keys(env).find((k) => /_BASE_URL$/.test(k) && set(env[k]));
+    if (key) return env[key];
+    let rules = [];
+    try { rules = (this.registry && this.registry.getResolveRules(a.type)) || []; } catch {}
+    const inherited = rules.find((r) => r && r.from === 'LLM_BASE_URL' && r.to && set(process.env[r.to]));
+    return inherited ? process.env[inherited.to] : null;
+  }
+
+  /**
+   * Where this agent's CLI sends requests and with which key, for listing that
+   * endpoint's models. The key is looked up the way the CLI would find it: the
+   * protocol's own variables for an Anthropic-protocol agent, else LLM_API_KEY
+   * or the variable resolve_env maps it to, inherited from the daemon or not.
+   */
+  _agentEndpoint(a) {
+    let typeEnv = {};
+    try { typeEnv = this.envManager.load(a.type) || {}; } catch {}
+    const env = this._buildAgentEnv(a);
+    let entry = null;
+    try { entry = this.registry.getEntry(a.type); } catch {}
+    const protocol = (entry && entry.protocol) || 'openai';
+    const rules = (entry && entry.resolve_env && entry.resolve_env.rules) || [];
+    const keyVars = protocol === 'anthropic'
+      ? ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY', 'LLM_API_KEY']
+      : ['LLM_API_KEY', ...rules.filter((r) => r && r.from === 'LLM_API_KEY').map((r) => r.to), 'OPENAI_API_KEY'];
+    const keyVar = keyVars.find((k) => k && String(env[k] || '').trim());
+    return {
+      baseUrl: this._configuredBaseUrl(a, typeEnv),
+      apiKey: keyVar ? String(env[keyVar]).trim() : '',
+      protocol,
+    };
+  }
+
   /**
    * Filesystem hint for the working-directory picker: home, its immediate
    * (non-hidden) subfolders, and the device's filesystem roots. Roots let a
@@ -606,6 +672,20 @@ async _runNodeCommand(n, cmd) {
         this._nodeHeartbeat();
         ok = true;
         message = `Detected ${this._runtimes.length} runtime(s)`;
+      } else if (action === 'list_models') {
+        // The model picker asks what the agent's own endpoint serves. The
+        // request needs the key, which is why it runs here.
+        if (!name) throw new Error('Missing agent name');
+        const agent = this.config.getAgent(name);
+        if (!agent || !this._agentOnNodeWorkspace(agent, n)) {
+          throw new Error(`Agent '${name}' is not managed by this workspace`);
+        }
+        const endpoint = this._agentEndpoint(agent);
+        if (!endpoint.baseUrl) throw new Error(`Agent '${name}' uses its CLI's default endpoint`);
+        const listed = await listEndpointModels(endpoint);
+        ok = listed.models.length > 0;
+        message = ok ? `Listed ${listed.models.length} model(s)` : listed.error;
+        data = { models: listed.models };
       } else if (action === 'list_dir') {
         data = this._listDir(args.path);
         ok = true;

package/src/installer.js

@@ -4,7 +4,17 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execSync, exec } = require('child_process');
-const { whichBinary, getEnhancedEnv, getRuntimePrefix, clearBinaryLookupCache, aiderBinDirs, resolveBinaryInKnownDirs } = require('./paths');
+const {
+  whichBinary,
+  getEnhancedEnv,
+  getRuntimePrefix,
+  clearBinaryLookupCache,
+  aiderBinDirs,
+  resolveBinaryInKnownDirs,
+  resolveManagedNpmBinary,
+  resolveManagedNpmPackageBin,
+  isNodeShebangScript,
+} = require('./paths');
 const { isWslBinary, bridgedCommandString, wslHomeUnc } = require('./wsl');
 const { canBlock } = require('./probe-mode');
 const { EnvManager } = require('./env');
@@ -610,6 +620,14 @@ class Installer {
     if (/\.(mjs|cjs|js)$/i.test(binary)) {
       return `"${this._nodeBinary()}" "${binary}" --version`;
     }
+    // Same problem, no extension to spot it by: npm's package bin is often an
+    // extensionless `#!/usr/bin/env node` script (node_modules/cline/bin/cline),
+    // which is what we resolve whenever npm wrote no .cmd shim. cmd.exe cannot
+    // run it — the probe dies with "is not recognized as an internal or external
+    // command" — and the agent then shows up in the app with no version at all.
+    if (isNodeShebangScript(binary)) {
+      return `"${this._nodeBinary()}" "${binary}" --version`;
+    }
     return `"${binary}" --version`;
   }
 
@@ -1083,6 +1101,19 @@ class Installer {
       throw new Error(`No install command for ${agentType} on ${Installer.platform()}`);
     }
 
+    let bootstrapEnv = this._buildShellEnv();
+    let installEnv;
+    if (agentType === 'hermes' && process.platform === 'win32') {
+      const prepared = this._prepareWindowsPowerShellInstall(cmd, bootstrapEnv);
+      cmd = prepared.command;
+      bootstrapEnv = prepared.env;
+      installEnv = prepared.env;
+    }
+
+    // Same uv bootstrap the streaming path does — `agn install hermes` and the
+    // workspace's remote create must not behave differently from the button.
+    await this._bootstrapManagedUv(agentType, bootstrapEnv, null);
+
     // Use bundled node/npm if system npm not available
     if (cmd.startsWith('npm install')) {
       const prefixDir = getRuntimePrefix(agentType);
@@ -1091,7 +1122,7 @@ class Installer {
       cmd = this._resolveNpmCommand(args);
     }
 
-    const output = await this._execShell(cmd);
+    const output = await this._execShell(cmd, 300000, installEnv);
 
     // Aider-only: the curl/uv/pipx installer can exit 0 without landing a
     // runnable (or genuine) binary, so verify the real CLI exists BEFORE
@@ -1159,9 +1190,23 @@ class Installer {
       await this.installNodejs(onData);
     }
 
-    const env = this._buildShellEnv();
+    let env = this._buildShellEnv();
     const isWin = process.platform === 'win32';
 
+    // Hermes's registry command names the inbox Windows PowerShell host for
+    // compatibility, but some Windows environments expose only PowerShell 7.
+    // Resolve the host that actually exists and keep module paths from the
+    // launcher's own PowerShell runtime out of both installer processes.
+    if (agentType === 'hermes' && isWin) {
+      const prepared = this._prepareWindowsPowerShellInstall(rawCmd, env);
+      rawCmd = prepared.command;
+      env = prepared.env;
+    }
+
+    // Hand the installer a uv it can use, so its own fragile bootstrap is
+    // never reached. No-op for every agent but hermes on Windows.
+    await this._bootstrapManagedUv(agentType, env, onData);
+
     // 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).
@@ -1297,15 +1342,27 @@ class Installer {
         // The watchdog already rejected; this close is the kill it performed.
         if (stalled) return;
         if (code === 0) {
+          // An installer that exits 0 without leaving a runnable binary is
+          // the class below (aider/amp/hermes/cursor). The "…could not be
+          // found" sentence alone says nothing about WHY, and the reason is
+          // sitting in the output we just captured — hermes's install.ps1, for
+          // one, prints "[X] Installation failed: uv installation failed" and
+          // exits 0, and without the tail the launcher could only shrug
+          // ("The installer stopped before it could finish"). Carry the tail
+          // into the rejection so the message the user sees, and the copy that
+          // classifies it, both have the real error in them.
+          const failVerify = (message) => {
+            const tail = outputTail.trim();
+            if (onData) onData(`\n${message}\n`);
+            reject(new Error(tail ? `${message}\n\nInstaller output:\n${tail}` : message));
+          };
           // Aider-only: confirm a real, genuine binary exists before recording
           // the install (verify-before-mark; never writes a marker on
           // failure). Other agent types are unaffected.
           if (agentType === 'aider') {
             const aider = this._verifyAiderBinary();
             if (!aider) {
-              const msg = this._aiderBinaryNotFoundMessage();
-              if (onData) onData(`\n${msg}\n`);
-              reject(new Error(msg));
+              failVerify(this._aiderBinaryNotFoundMessage());
               return;
             }
             if (onData) onData(`\nAider CLI resolved: ${aider.path}${aider.version ? ` (${aider.version})` : ''}\n`);
@@ -1315,9 +1372,7 @@ class Installer {
           if (agentType === 'amp') {
             const amp = this._verifyAmpBinary();
             if (!amp) {
-              const msg = this._ampBinaryNotFoundMessage();
-              if (onData) onData(`\n${msg}\n`);
-              reject(new Error(msg));
+              failVerify(this._ampBinaryNotFoundMessage());
               return;
             }
             if (onData) onData(`\nAmp CLI resolved: ${amp.path}${amp.version ? ` (${amp.version})` : ''}\n`);
@@ -1327,9 +1382,7 @@ class Installer {
           if (agentType === 'hermes') {
             const hermes = this._verifyHermesBinary();
             if (!hermes) {
-              const msg = this._hermesBinaryNotFoundMessage();
-              if (onData) onData(`\n${msg}\n`);
-              reject(new Error(msg));
+              failVerify(this._hermesBinaryNotFoundMessage());
               return;
             }
             if (onData) onData(`\nHermes CLI resolved: ${hermes.path}\n`);
@@ -1346,9 +1399,7 @@ class Installer {
           if (agentType === 'cursor') {
             const cursor = this._verifyCursorBinary();
             if (!cursor) {
-              const msg = this._cursorBinaryNotFoundMessage();
-              if (onData) onData(`\n${msg}\n`);
-              reject(new Error(msg));
+              failVerify(this._cursorBinaryNotFoundMessage());
               return;
             }
             if (onData) onData(`\nCursor CLI resolved: ${cursor.path}\n`);
@@ -1683,29 +1734,7 @@ class Installer {
     const pkgName = npmPkg || npmPkgFromCmd;
     if (!pkgName) return null; // script-installed agent: nothing of ours to prefer
 
-    const prefixes = [
-      path.join(getRuntimePrefix(agentType), 'node_modules'),
-      path.join(os.homedir(), '.openagents', 'nodejs', 'node_modules'),
-    ];
-    const exts = process.platform === 'win32' ? ['.cmd', '.exe', '.bat', ''] : [''];
-    for (const modules of prefixes) {
-      try {
-        if (!fs.existsSync(path.join(modules, pkgName, 'package.json'))) continue;
-      } catch { continue; }
-      for (const name of [binary, ...aliases]) {
-        for (const ext of exts) {
-          const candidate = path.join(modules, '.bin', `${name}${ext}`);
-          try {
-            if (fs.existsSync(candidate)) return candidate;
-          } catch {}
-        }
-      }
-      // npm does not always link the root package's own bin — same case
-      // _resolvePackageBin exists for.
-      const own = this._resolvePackageBin(agentType, entry, binary);
-      if (own) return own;
-    }
-    return null;
+    return resolveManagedNpmBinary(agentType, pkgName, [binary, ...aliases]);
   }
 
   /**
@@ -1723,25 +1752,7 @@ class Installer {
       if (m) npmPkgFromCmd = m[1];
     }
     const pkgName = npmPkg || npmPkgFromCmd || binary;
-    const prefixes = [
-      path.join(getRuntimePrefix(agentType), 'node_modules'),
-      path.join(os.homedir(), '.openagents', 'nodejs', 'node_modules'),
-    ];
-    for (const modules of prefixes) {
-      const pkgDir = path.join(modules, pkgName);
-      const pkgJsonPath = path.join(pkgDir, 'package.json');
-      try {
-        if (!fs.existsSync(pkgJsonPath)) continue;
-        const bin = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).bin;
-        let rel = null;
-        if (typeof bin === 'string') rel = bin;
-        else if (bin && typeof bin === 'object') rel = bin[binary] || bin[pkgName] || Object.values(bin)[0];
-        if (!rel) continue;
-        const abs = path.join(pkgDir, rel);
-        if (fs.existsSync(abs)) return abs;
-      } catch {}
-    }
-    return null;
+    return resolveManagedNpmPackageBin(agentType, pkgName, binary);
   }
 
   // -- Markers --
@@ -1907,6 +1918,168 @@ class Installer {
     return env;
   }
 
+  /**
+   * Build an isolated environment for a PowerShell child process.
+   *
+   * PowerShell constructs PSModulePath for the host that is starting. Passing
+   * through a value created by another host (for example pwsh -> powershell)
+   * can make it load binary modules from the wrong runtime. Remove every
+   * casing of the key and let the child rebuild its own defaults.
+   */
+  _powerShellChildEnv(env) {
+    const childEnv = { ...env };
+    for (const key of Object.keys(childEnv)) {
+      if (key.toLowerCase() === 'psmodulepath') delete childEnv[key];
+    }
+    return childEnv;
+  }
+
+  /**
+   * Resolve a PowerShell host without assuming Windows PowerShell 5.1 exists.
+   * Prefer the Windows inbox host for compatibility with existing installer
+   * scripts, then fall back to pwsh from PATH or its standard install folder.
+   *
+   * `platform` and `exists` are seams so the Windows rules run on every CI
+   * platform without touching the real machine.
+   */
+  _resolveWindowsPowerShellHost(
+    env,
+    platform = process.platform,
+    exists = fs.existsSync,
+  ) {
+    if (platform !== 'win32') return null;
+    const value = (name) => {
+      const key = Object.keys(env).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+      return key ? env[key] : '';
+    };
+    const systemRoot = value('SystemRoot') || 'C:\\Windows';
+    const windowsPowerShell = path.win32.join(
+      systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe',
+    );
+    if (exists(windowsPowerShell)) return windowsPowerShell;
+
+    for (const rawDir of (value('Path') || '').split(';')) {
+      const dir = rawDir.trim().replace(/^"|"$/g, '');
+      if (!dir) continue;
+      const candidate = path.win32.join(dir, 'pwsh.exe');
+      if (exists(candidate)) return candidate;
+    }
+
+    const programFiles = value('ProgramFiles') || 'C:\\Program Files';
+    const standardPwsh = path.win32.join(programFiles, 'PowerShell', '7', 'pwsh.exe');
+    return exists(standardPwsh) ? standardPwsh : null;
+  }
+
+  /** Replace only the leading PowerShell executable in an install command. */
+  _retargetPowerShellCommand(command, executable) {
+    const hostPrefix = /^(\s*)(?:"[^"]*\\(?:powershell|pwsh)(?:\.exe)?"|(?:powershell|pwsh)(?:\.exe)?)\s+/i;
+    return command.replace(hostPrefix, `$1"${executable}" `);
+  }
+
+  /** Prepare a Windows PowerShell install without leaking another host's modules. */
+  _prepareWindowsPowerShellInstall(
+    command,
+    env,
+    platform = process.platform,
+    exists = fs.existsSync,
+  ) {
+    const host = this._resolveWindowsPowerShellHost(env, platform, exists);
+    if (!host) {
+      throw new Error('Windows PowerShell or PowerShell 7 is required for this installer.');
+    }
+    return {
+      command: this._retargetPowerShellCommand(command, host),
+      env: this._powerShellChildEnv(env),
+      host,
+    };
+  }
+
+  /**
+   * Put uv where hermes's installer looks for it, before that installer runs.
+   *
+   * hermes's Install-Uv bootstraps its OWN copy at <HERMES_HOME>\bin\uv.exe
+   * ("no PATH probing, no conda guards" — a uv already on the machine is not
+   * used), and it does that by spawning a child PowerShell for the astral
+   * installer WITHOUT -NoProfile. When that child cannot run — a profile that
+   * throws, a PSModulePath that cannot load built-in modules — uv never lands,
+   * and hermes prints "Installation failed: uv installation failed" and exits
+   * 0 anyway, leaving a half-installed agent.
+   *
+   * Doing the same download ourselves, from an environment we control, takes
+   * that fragile hop out of the install. Its early
+   * `if (Test-Path $managedUv) { return $true }` then short-circuits the whole
+   * step. Best-effort by design: any failure here is logged and the install
+   * proceeds exactly as it does today, so this can only add successes.
+   *
+   * Windows-only. The Unix install.sh runs the uv installer through `sh`,
+   * which reads no profile and has never shown this failure.
+   *
+   * `platform` and `exists` are seams for tests; production passes neither.
+   * They must be threaded into the host lookup below — without them it falls
+   * back to the real filesystem and can never resolve a Windows path on a
+   * Linux or macOS CI runner, which silently turned every assertion about the
+   * spawn into a no-op.
+   */
+  async _bootstrapManagedUv(
+    agentType,
+    env,
+    onData,
+    platform = process.platform,
+    exists = fs.existsSync,
+  ) {
+    if (agentType !== 'hermes' || platform !== 'win32') return;
+    const home = os.homedir();
+    const hermesHome = env.HERMES_HOME
+      || path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'hermes');
+    const binDir = path.join(hermesHome, 'bin');
+    const managedUv = path.join(binDir, 'uv.exe');
+    try { if (exists(managedUv)) return; } catch { return; }
+
+    if (onData) onData(`\nProvisioning uv for Hermes into ${binDir} ...\n`);
+    try {
+      const psExe = this._resolveWindowsPowerShellHost(env, platform, exists);
+      if (!psExe) throw new Error('no Windows PowerShell or PowerShell 7 host found');
+      fs.mkdirSync(binDir, { recursive: true });
+      await new Promise((resolve, reject) => {
+        // `_spawnForTest` is a seam so a test can inspect the environment this
+        // child is given; production never sets it.
+        const spawnFn = this._spawnForTest || require('child_process').spawn;
+        const child = spawnFn(
+          psExe,
+          [
+            '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+            // Force UTF-8 out of the child before it prints anything. A
+            // Chinese-locale Windows emits GBK, which reaches the install log
+            // as mojibake — the user saw a wall of "??" where the error was.
+            '-Command',
+            '[Console]::OutputEncoding=[Text.Encoding]::UTF8; irm https://astral.sh/uv/install.ps1 | iex',
+          ],
+          {
+            // UV_INSTALL_DIR is what the astral script honours; it is the same
+            // variable hermes sets for its own attempt.
+            env: this._powerShellChildEnv({ ...env, UV_INSTALL_DIR: binDir }),
+            cwd: home,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+          },
+        );
+        const relay = (d) => { if (onData) onData(String(d)); };
+        if (child.stdout) child.stdout.on('data', relay);
+        if (child.stderr) child.stderr.on('data', relay);
+        child.on('error', reject);
+        child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`exit code ${code}`))));
+      });
+    } catch (e) {
+      if (onData) onData(`\nCould not provision uv ahead of the installer (${e.message}); letting Hermes try its own.\n`);
+      return;
+    }
+    if (onData) {
+      onData(fs.existsSync(managedUv)
+        ? `uv ready at ${managedUv}\n`
+        : `uv installer finished but ${managedUv} is absent; letting Hermes try its own.\n`);
+    }
+  }
+
   /**
    * True if `node` exists outside the bundled launcher directory. Uses raw
    * process.env.PATH (no enhancement) so we don't accidentally detect the
@@ -2276,9 +2449,9 @@ class Installer {
     return `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "${escaped}"`;
   }
 
-  _execShell(cmd, timeoutMs = 300000) {
+  _execShell(cmd, timeoutMs = 300000, envOverride = null) {
     return new Promise((resolve, reject) => {
-      const env = this._buildShellEnv();
+      const env = envOverride || this._buildShellEnv();
 
       let shell = true;
       if (process.platform === 'win32') {