@openagents-org/agent-launcher 0.2.173 → 0.2.176

package/src/daemon.js

@@ -55,10 +55,11 @@ class Daemon {
   }
 
   // ── Agent smoke tests (probes) ─────────────────────────────────────────
-  // A probe runs one tiny end-to-end prompt through an agent type (see
-  // probe.js) — the check that catches "connected but never answers".
-  // Results are persisted so a daemon restart doesn't re-spend LLM calls,
-  // and are reported to every paired workspace on the node heartbeat.
+  // A probe runs one tiny end-to-end prompt through an AGENT (see probe.js)
+  // — the check that catches "connected but never answers". Results are
+  // keyed by agent name (a probe belongs to a configured agent, never to a
+  // bare agent type), persisted so a daemon restart doesn't re-spend LLM
+  // calls, and reported per agent on the node heartbeat's roster.
 
   _probesFile() {
     return path.join(os.homedir(), '.openagents', 'probes.json');
@@ -67,24 +68,32 @@ class Daemon {
   _loadProbes() {
     try {
       const data = JSON.parse(fs.readFileSync(this._probesFile(), 'utf-8'));
-      return data && typeof data === 'object' ? data : {};
+      // v2 shape: { agents: { <name>: result } }. The v1 file was keyed by
+      // type — discard it rather than misattribute results to agents.
+      if (data && typeof data.agents === 'object') return data.agents;
+      return {};
     } catch { return {}; }
   }
 
   _saveProbes() {
     try {
       fs.mkdirSync(path.dirname(this._probesFile()), { recursive: true });
-      fs.writeFileSync(this._probesFile(), JSON.stringify(this._probes, null, 2), 'utf-8');
+      fs.writeFileSync(this._probesFile(), JSON.stringify({ agents: this._probes }, null, 2), 'utf-8');
     } catch {}
   }
 
   /**
-   * Probe one type via a child `agn probe --json` (same off-event-loop
-   * pattern as _refreshRuntimes; a probe can block for its full timeout).
+   * Probe one configured agent via a child `agn probe <type> --json` (same
+   * off-event-loop pattern as _refreshRuntimes; a probe can block for its
+   * full timeout). The check exercises the agent's type runtime with the
+   * same env the agent runs with; the result is stored under the agent name.
    */
-  async _probeType(type) {
-    if (this._probeInFlight.has(type)) return this._probes[type] || null;
-    this._probeInFlight.add(type);
+  async _probeAgent(name) {
+    if (this._probeInFlight.has(name)) return this._probes[name] || null;
+    const agent = this.config.getAgent(name);
+    if (!agent) return null;
+    const type = agent.type || 'openclaw';
+    this._probeInFlight.add(name);
     try {
       const r = await this._runAgn(['probe', type, '--json']);
       let parsed = null;
@@ -96,37 +105,30 @@ class Daemon {
           guidance: [], at: new Date().toISOString(),
         };
       }
-      this._probes[type] = parsed;
+      parsed.agent = name;
+      this._probes[name] = parsed;
       this._saveProbes();
       return parsed;
     } finally {
-      this._probeInFlight.delete(type);
+      this._probeInFlight.delete(name);
     }
   }
 
   /**
-   * Periodic sweep: probe each type that has a configured agent and whose
-   * last result is missing or stale. Sequential on purpose — probes cost a
-   * (tiny) model call each; there is no hurry.
+   * Periodic sweep: probe each configured agent whose last result is missing
+   * or stale. Sequential on purpose — probes cost a (tiny) model call each;
+   * there is no hurry.
    */
-  async _probeConfiguredTypes(maxAgeMs) {
-    const types = [...new Set(this.config.getAgents().map((a) => a.type || 'openclaw'))];
-    for (const type of types) {
-      const last = this._probes[type];
+  async _probeConfiguredAgents(maxAgeMs) {
+    for (const a of this.config.getAgents()) {
+      const last = this._probes[a.name];
       const age = last && last.at ? Date.now() - Date.parse(last.at) : Infinity;
       if (age < maxAgeMs) continue;
-      try { await this._probeType(type); } catch {}
+      try { await this._probeAgent(a.name); } catch {}
     }
     this._nodeHeartbeat();
   }
 
-  /** Runtimes annotated with each type's last probe, for the heartbeat. */
-  _runtimesWithProbes() {
-    return (this._runtimes || []).map((r) =>
-      this._probes[r.type] ? { ...r, probe: this._probes[r.type] } : r
-    );
-  }
-
   /**
    * Heartbeat this device (node) to EVERY workspace it is paired to,
    * independent of any agent, so each workspace's "connected devices" view
@@ -144,10 +146,41 @@ class Daemon {
     const nodeCfg = require('./node-config');
     const pairings = nodeCfg.listPairings().filter((p) => p && p.node_id && p.token);
     if (!pairings.length) return;  // no node connected
-    const info = { ...nodeCfg.gatherDeviceInfo(), runtimes: this._runtimesWithProbes(), fs: this._buildFs() };
+    const info = { ...nodeCfg.gatherDeviceInfo(), runtimes: this._runtimes || [], fs: this._buildFs() };
     await Promise.all(pairings.map((p) => this._nodeHeartbeatOne(nodeCfg, p, info)));
   }
 
+  /**
+   * Restart any adapter whose workspace credential has rotated on disk.
+   *
+   * Re-pairing a device (launcher, CLI, or the workspace's own reconnect flow)
+   * writes a fresh token to node.json / daemon.yaml and the server revokes the
+   * old one. An adapter launched before that keeps its stale token in memory
+   * and every join/poll/heartbeat 401s until someone manually restarts it —
+   * the dashboard meanwhile shows the agent stuck on "Spinning up…". This
+   * watch closes that gap: credentials are re-resolved from disk (pairing
+   * first, saved network as fallback — same order as launch) and a changed
+   * token triggers an in-process restart, which picks the new credential up.
+   */
+  _reconcileAdapterCredentials() {
+    if (this._shuttingDown) return;
+    for (const [name, info] of Object.entries(this._processes || {})) {
+      if (!info || !info.networkRef || info._credRestartPending) continue;
+      if (!this._adapters || !this._adapters[name]) continue;
+      let fresh = null;
+      try { fresh = this._resolveAgentNetwork(info.networkRef); } catch { /* keep running on the current token */ }
+      if (!fresh || !fresh.token || fresh.token === info.credentialToken) continue;
+      // Flag on the CURRENT info object: restartAgent replaces it with a fresh
+      // one on relaunch, so the flag cannot wedge the watch permanently.
+      info._credRestartPending = true;
+      this._log(`${name}: workspace credential for '${info.networkRef}' rotated (device re-paired) — restarting to pick up the new token`);
+      this.restartAgent(name).catch((e) => {
+        info._credRestartPending = false;
+        this._log(`${name}: credential-rotation restart failed: ${e.message}`);
+      });
+    }
+  }
+
   /** The WorkspaceClient for one pairing, created on first use and reused. */
   _nodeClientFor(n) {
     let client = this._nodeClients.get(n.workspace_id);
@@ -235,6 +268,7 @@ class Daemon {
           model: model || null,
           workingDir: a.path || null,
           apiKeyMasked: apiKey ? maskApiKey(apiKey) : null,
+          probe: this._probes[a.name] || null,
         });
       }
     } catch {
@@ -308,7 +342,35 @@ class Daemon {
    * all of create/install/connect/start/stop/remove reuses the exact code path a
    * local `agn` invocation would — then report the outcome back to the workspace.
    */
-  async _runNodeCommand(n, cmd) {
+    /**
+   * Apply a workspace-sent config map, ALLOWLISTED to the agent type's own
+   * registry env_config keys. Arbitrary env is refused — a workspace admin
+   * must not be able to push NODE_OPTIONS-class variables onto a device.
+   * (Credential contract: config flows down transiently, secrets persist
+   * only here, in the device's env store.)
+   */
+  async _applyConfigMap(type, config) {
+    if (!config || typeof config !== 'object') return;
+    let allowed = null;
+    try {
+      const entry = this.registry.getEntry(type);
+      allowed = new Set(
+        ((entry && entry.env_config) || []).map((f) => f.name).filter(Boolean)
+      );
+    } catch {
+      return; // no registry entry — refuse everything rather than guess
+    }
+    for (const [key, value] of Object.entries(config)) {
+      if (!allowed.has(key)) {
+        this._log(`config for '${type}': refused non-env_config key '${key}'`);
+        continue;
+      }
+      if (value === null || value === undefined) continue;
+      await this._runAgn(['env', type, '--set', `${key}=${String(value)}`]);
+    }
+  }
+
+async _runNodeCommand(n, cmd) {
     const action = cmd.action;
     const args = cmd.args || {};
     const name = (args.name || '').trim();
@@ -338,19 +400,27 @@ class Daemon {
         const r1 = await this._runAgn(['create', name, '--type', type, '--install', '--path', workingDir]);
         if (r1.code !== 0) throw new Error(r1.stderr || r1.stdout || 'create failed');
         // Optional credentials for API-key agents (generic → provider mapping
-        // happens in env resolution).
-        if (args.apiKey) await this._runAgn(['env', type, '--set', `LLM_API_KEY=${args.apiKey}`]);
+        // happens in env resolution). `useDeviceCredentials` means the device
+        // already holds them — nothing to write.
+        if (args.apiKey && !args.useDeviceCredentials)
+          await this._runAgn(['env', type, '--set', `LLM_API_KEY=${args.apiKey}`]);
         if (args.model) await this._setModelEnv(type, args.model);
         if (args.baseUrl) await this._runAgn(['env', type, '--set', `LLM_BASE_URL=${args.baseUrl}`]);
-        // Attach to this node's workspace so the agent shows up as a member.
-        const r2 = await this._runAgn(['connect', name, n.token, '--endpoint', n.endpoint]);
+        await this._applyConfigMap(type, args.config);
+        // Attach to this node's workspace BY SLUG: the daemon already knows
+        // which workspace this command came from, so there is no token to
+        // pass and no /v1/token/resolve round-trip to fail (the outage class
+        // that used to break remote installs).
+        const r2 = await this._runAgn([
+          'connect', name, '--workspace', n.workspace_slug || n.workspace_id,
+        ]);
         if (r2.code !== 0) throw new Error(r2.stderr || r2.stdout || 'connect failed');
         ok = true;
         message = `Agent '${name}' created`;
         // First-connect smoke test, in the background (a probe can take its
         // full timeout — never hold the create result hostage). The outcome
-        // reaches the workspace via the heartbeat's runtimes[].probe.
-        this._probeType(type).then(() => this._nodeHeartbeat()).catch(() => {});
+        // reaches the workspace via the heartbeat's agents[].probe.
+        this._probeAgent(name).then(() => this._nodeHeartbeat()).catch(() => {});
       } else if (action === 'start_agent') {
         const r = await this._runAgn(['start', name]);
         ok = r.code === 0;
@@ -368,36 +438,42 @@ class Daemon {
         // restart it so the change takes effect. Working-dir changes require a
         // recreate (agn has no in-place path change) at the new path.
         const type = (args.type || '').trim();
-        if (args.apiKey) await this._runAgn(['env', type, '--set', `LLM_API_KEY=${args.apiKey}`]);
+        if (args.apiKey && !args.useDeviceCredentials)
+          await this._runAgn(['env', type, '--set', `LLM_API_KEY=${args.apiKey}`]);
         if (args.model !== undefined) await this._setModelEnv(type, args.model);
         if (args.baseUrl !== undefined) await this._runAgn(['env', type, '--set', `LLM_BASE_URL=${args.baseUrl}`]);
+        await this._applyConfigMap(type, args.config);
         const newDir = (args.workingDir || '').trim();
         if (newDir && newDir !== (args.currentWorkingDir || '')) {
           try { fs.mkdirSync(newDir, { recursive: true }); } catch {}
           await this._runAgn(['remove', name]);
           const rc = await this._runAgn(['create', name, '--type', type, '--install', '--path', newDir]);
           if (rc.code !== 0) throw new Error(rc.stderr || rc.stdout || 'recreate failed');
-          const rc2 = await this._runAgn(['connect', name, n.token, '--endpoint', n.endpoint]);
+          const rc2 = await this._runAgn([
+            'connect', name, '--workspace', n.workspace_slug || n.workspace_id,
+          ]);
           if (rc2.code !== 0) throw new Error(rc2.stderr || rc2.stdout || 'connect failed');
         } else {
-          await this._runAgn(['stop', name]);
-          await this._runAgn(['start', name]);
+          // Restart in-process. `agn stop` + `agn start` both round-trip
+          // through daemon.cmd, and writeCommand() OVERWRITES that file — the
+          // start could clobber the unread stop (agent keeps the stale env) or
+          // interleave with the poll so the agent stops and never restarts.
+          await this.restartAgent(name);
         }
         ok = true;
         message = `Agent '${name}' reconfigured`;
+        // A reconfigure changes credentials/model — re-verify in the
+        // background so the workspace sees the new state without a manual test.
+        this._probeAgent(name).then(() => this._nodeHeartbeat()).catch(() => {});
       } else if (action === 'probe_agent') {
-        // Smoke-test on demand ("Test agent" in the workspace). Accepts a
-        // type directly, or an agent name (must belong to this workspace).
-        let type = (args.type || '').trim();
-        if (!type && name) {
-          const agent = this.config.getAgent(name);
-          if (!agent || !this._agentOnNodeWorkspace(agent, n)) {
-            throw new Error(`Agent '${name}' is not managed by this workspace`);
-          }
-          type = agent.type || 'openclaw';
+        // Smoke-test on demand ("Re-test" in the workspace). Probes belong to
+        // configured agents (by name); the result rides agents[].probe.
+        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`);
         }
-        if (!type) throw new Error('Missing agent type');
-        const probe = await this._probeType(type);
+        const probe = await this._probeAgent(name);
         ok = !!(probe && probe.ok);
         message = (probe && probe.message) || (ok ? 'Smoke test passed' : 'Smoke test failed');
         data = { probe };
@@ -522,6 +598,16 @@ class Daemon {
     this._nodeHeartbeat();
     this._nodeHeartbeatInterval = setInterval(() => this._nodeHeartbeat(), 10000);
 
+    // Credential-rotation watch. Re-pairing a device rotates the workspace
+    // token (and revokes the old one) while adapters holding the old token
+    // keep 401-ing forever — the "agent stuck spinning up after re-pair"
+    // failure. Pairings are re-read from disk on every pass, so a re-pair done
+    // by the launcher, the CLI or a remote command is picked up within a tick.
+    this._credReconcileInterval = setInterval(
+      () => this._reconcileAdapterCredentials(),
+      15000,
+    );
+
     // Detect installed/logged-in agent runtimes for the Add-agent gallery. Runs
     // in a child process (off the event loop), refreshed periodically.
     this._refreshRuntimes();
@@ -531,14 +617,17 @@ class Daemon {
     // tiny model call, so: only types with agents, only when the last result
     // is a day old, and a few minutes after startup so install/login churn
     // settles first). Persisted results keep restarts from re-spending calls.
-    const PROBE_MAX_AGE_MS = 24 * 3600 * 1000;
+    // Hourly per-agent sweep — a stale/broken key should surface within the
+    // hour, not the day. Create/reconfigure probe immediately, so the sweep
+    // only tops up agents whose last result has aged out.
+    const PROBE_MAX_AGE_MS = 3600 * 1000;
     this._probeStartupTimer = setTimeout(
-      () => this._probeConfiguredTypes(PROBE_MAX_AGE_MS).catch(() => {}),
+      () => this._probeConfiguredAgents(PROBE_MAX_AGE_MS).catch(() => {}),
       3 * 60 * 1000,
     );
     this._probeInterval = setInterval(
-      () => this._probeConfiguredTypes(PROBE_MAX_AGE_MS).catch(() => {}),
-      6 * 3600 * 1000,
+      () => this._probeConfiguredAgents(PROBE_MAX_AGE_MS).catch(() => {}),
+      3600 * 1000,
     );
 
     // Watch config file for hot-reload
@@ -567,6 +656,7 @@ class Daemon {
     if (this._statusInterval) clearInterval(this._statusInterval);
     if (this._cmdInterval) clearInterval(this._cmdInterval);
     if (this._nodeHeartbeatInterval) clearInterval(this._nodeHeartbeatInterval);
+    if (this._credReconcileInterval) clearInterval(this._credReconcileInterval);
     if (this._runtimesInterval) clearInterval(this._runtimesInterval);
     if (this._probeStartupTimer) clearTimeout(this._probeStartupTimer);
     if (this._probeInterval) clearInterval(this._probeInterval);
@@ -817,6 +907,35 @@ class Daemon {
   // Internal — agent launch
   // ---------------------------------------------------------------------------
 
+  /**
+   * The workspace record an agent joins with. The device pairing (node.json)
+   * is the authoritative credential — it is refreshed by every re-pair —
+   * with the saved network entry (daemon.yaml) as the manual-connection
+   * fallback. Fields from the network entry win for display (name), the
+   * pairing wins for credentials (token/endpoint).
+   */
+  _resolveAgentNetwork(ref) {
+    const network =
+      this.config.getNetworks().find((n) => n.slug === ref || n.id === ref) ||
+      null;
+    let pairing = null;
+    try {
+      pairing = require('./node-config')
+        .listPairings()
+        .find((p) => p.workspace_slug === ref || p.workspace_id === ref) || null;
+    } catch {}
+    if (!network && !pairing) return null;
+    return {
+      id: (network && network.id) || (pairing && pairing.workspace_id) || null,
+      slug: (network && network.slug) || (pairing && pairing.workspace_slug) || ref,
+      name:
+        (network && network.name) || (pairing && pairing.workspace_name) || ref,
+      endpoint:
+        (pairing && pairing.endpoint) || (network && network.endpoint) || null,
+      token: (pairing && pairing.token) || (network && network.token) || null,
+    };
+  }
+
   _launchAgent(agentCfg) {
     const name = agentCfg.name;
     const type = agentCfg.type || 'openclaw';
@@ -847,12 +966,26 @@ class Daemon {
     // Workspace-connected agents use the adapter loop (poll + CLI per message).
     // Local-only agents use the spawn loop (long-running child process).
     const network = agentCfg.network
-      ? this.config.getNetworks().find(
-          (n) => n.slug === agentCfg.network || n.id === agentCfg.network
-        )
+      ? this._resolveAgentNetwork(agentCfg.network)
       : null;
 
-    if (network) {
+    if (network && !network.token) {
+      // A known workspace with no credential anywhere: the device was
+      // unpaired (or a future token-free entry has no pairing behind it).
+      // Say so instead of letting the join fail with a bare 401.
+      info.state = 'error';
+      info.network = agentCfg.network;
+      info.lastError =
+        'workspace credentials missing — re-pair this device with the workspace';
+      this._writeStatus();
+      this._log(
+        `${name} cannot join '${agentCfg.network}': no pairing and no saved token — re-pair the device`
+      );
+    } else if (network) {
+      // Remember which credential this adapter runs with, so the rotation
+      // watch can restart it when a re-pair hands the workspace a new token.
+      info.networkRef = agentCfg.network;
+      info.credentialToken = network.token;
       this._adapterLoop(name, agentCfg, info, network);
     } else {
       // No workspace connected — agent is running locally

package/src/env.js

@@ -81,7 +81,7 @@ class EnvManager {
     for (const rule of rules) {
       const src = rule.from || '';
       const dst = rule.to || '';
-      const srcVal = saved[src];
+      let srcVal = saved[src];
       if (!srcVal || !dst) continue;
 
       // Conditional rules based on base URL
@@ -92,6 +92,7 @@ class EnvManager {
         if (baseUrl.includes(rule.unless_base_url_contains.toLowerCase())) continue;
       }
 
+      if (dst === 'ANTHROPIC_BASE_URL') srcVal = normalizeAnthropicBase(srcVal);
       resolved[dst] = srcVal;
     }
 
@@ -102,10 +103,29 @@ class EnvManager {
    * Get the full effective env for an agent: saved + resolved.
    */
   getEffective(agentType, registry) {
-    const saved = this.load(agentType);
+    const saved = { ...this.load(agentType) };
+    // Same normalization as resolve(), for a base saved under the provider
+    // key directly (agn env --set ANTHROPIC_BASE_URL=…, hand-edited files).
+    if (saved.ANTHROPIC_BASE_URL) {
+      saved.ANTHROPIC_BASE_URL = normalizeAnthropicBase(saved.ANTHROPIC_BASE_URL);
+    }
     const resolved = this.resolve(agentType, saved, registry);
     return { ...saved, ...resolved };
   }
 }
 
+/**
+ * Anthropic's SDK appends the `/v1` segment itself: a base saved as
+ * `https://relay.example/v1` makes the claude CLI call `…/v1/v1/messages`,
+ * a 404 it mis-reports as "there's an issue with the selected model". The
+ * launcher already strips the suffix for env saved through its UI
+ * (env-normalize.ts); this is the same rule at the resolution layer, so env
+ * written by ANY path — `agn env --set`, the workspace's remote
+ * configure_agent command, a hand-edited file — is covered too. OpenAI-style
+ * bases legitimately carry `/v1` and are left alone.
+ */
+function normalizeAnthropicBase(url) {
+  return String(url || '').trim().replace(/\/+$/, '').replace(/\/v1$/i, '');
+}
+
 module.exports = { EnvManager };

package/src/index.js

@@ -126,6 +126,14 @@ class AgentConnector {
         const saved = this.env.load(agentType);
         OpenClawAdapter.configureNativeAuth(saved);
       }
+      // Hermes reads a custom endpoint only from its own config.yaml, so the
+      // saved LLM_* values must be pushed through `hermes config set` — the
+      // env file alone leaves it "No inference provider configured".
+      if (agentType === 'hermes') {
+        const HermesAdapter = require('./adapters/hermes');
+        const saved = this.env.load(agentType);
+        HermesAdapter.configureNativeAuth(saved);
+      }
     } catch {}
     return { success: true };
   }
@@ -154,6 +162,11 @@ class AgentConnector {
         const typeEnv = this.env.load(agent.type || 'openclaw');
         OpenClawAdapter.configureNativeAuth({ ...typeEnv, ...saved });
       }
+      if (agent.type === 'hermes') {
+        const HermesAdapter = require('./adapters/hermes');
+        const typeEnv = this.env.load('hermes');
+        HermesAdapter.configureNativeAuth({ ...typeEnv, ...saved });
+      }
     } catch {}
 
     return { success: true };

package/src/installer.js

@@ -728,7 +728,16 @@ class Installer {
     const directEnv = this._hasAllValues(process.env, checkReady.env_all);
     const directSaved = this._hasAllValues(savedEnv, checkReady.saved_env_all || checkReady.env_all);
     const directReady = directEnv || directSaved;
-    const envAnyReady = this._hasAnyValue(process.env, checkReady.env_vars);
+    // env_vars must be satisfiable by the SAVED (and resolved) per-agent env,
+    // not only the daemon's own process env. The workspace configure flow
+    // saves LLM_API_KEY, which resolve rules map to e.g. ANTHROPIC_AUTH_TOKEN
+    // — the exact var the adapter launches the CLI with. Checking process.env
+    // alone made a perfectly working key-configured agent read "Not logged
+    // in" (health banner + failed smoke test) while chat answered fine, with
+    // guidance telling the user to configure the very key they had saved.
+    const envAnyReady =
+      this._hasAnyValue(process.env, checkReady.env_vars) ||
+      this._hasAnyValue(savedEnv, checkReady.env_vars);
     const savedAnyReady = !!(checkReady.saved_env_key && savedEnv[checkReady.saved_env_key]);
     // A registry entry may require a non-empty JSON object rather than mere
     // parseability. In that mode the stricter _evaluateCredsFile path below is
@@ -1544,6 +1553,21 @@ class Installer {
     const aliases = entry && entry.install && Array.isArray(entry.install.binary_aliases)
       ? entry.install.binary_aliases
       : [];
+    // Tier 0: the copy THIS launcher installed, when there really is one.
+    //
+    // getInstallInfo() checks the isolated runtime prefix before anything else,
+    // so an agent with a managed install reports location:'runtime' and shows
+    // that copy's version. A PATH lookup, though, hits the user's own global
+    // copy first — /usr/local/bin and the node-manager bins all rank above
+    // ~/.openagents/runtimes/*/node_modules/.bin. The two then disagree about
+    // which binary is in play: the marketplace said "opencode 1.18.25,
+    // managed" while every run spawned the 1.17 the user had installed
+    // themselves, and pressing Update changed the number without changing the
+    // program. Gated on the package actually being present so a stale shim
+    // still falls through to a working global install.
+    const managed = this._resolveManagedBinary(agentType, entry, binary, aliases);
+    if (managed) return managed;
+
     for (const candidate of [binary, ...aliases]) {
       const found = whichBinary(candidate);
       if (found) return found;
@@ -1567,6 +1591,50 @@ class Installer {
     return resolveBinaryInKnownDirs([binary, ...aliases], agentType);
   }
 
+  /**
+   * The launcher-installed copy of an agent's CLI, or null.
+   *
+   * Only answers when the agent's npm package is really unpacked in one of our
+   * prefixes — an orphaned `.bin` shim is not a managed install, and treating
+   * it as one would shadow a perfectly good global CLI with something that
+   * cannot run.
+   */
+  _resolveManagedBinary(agentType, entry, binary, aliases) {
+    const npmPkg = entry && entry.install ? entry.install.npm_package : null;
+    const installCmd = entry && entry.install ? this._getInstallCommand(entry.install) : null;
+    let npmPkgFromCmd = null;
+    if (!npmPkg && installCmd && installCmd.includes('npm install')) {
+      const m = installCmd.match(/npm install\s+(?:-g\s+)?(@?[\w-]+(?:\/[\w-]+)?)(?:@\S*)?$/);
+      if (m) npmPkgFromCmd = m[1];
+    }
+    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;
+  }
+
   /**
    * Resolve the absolute path to a package's own executable from its
    * package.json `bin` field, searched in the runtime and legacy prefixes.