@openagents-org/agent-launcher 0.2.178 → 0.2.180

package/package.json

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

package/src/adapters/base.js

@@ -20,6 +20,9 @@
 const { WorkspaceClient, SessionRevokedError } = require('../workspace-client');
 const { generateSessionTitle, SESSION_DEFAULT_RE } = require('./utils');
 const { defaultAgentWorkdir } = require('../paths');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const {
   decisionLogTitle,
   glossaryTitle,
@@ -35,6 +38,21 @@ const {
 
 const DEFAULT_ENDPOINT = 'https://workspace-endpoint.openagents.org';
 
+// ── Poll-cursor persistence ──
+// An adapter that starts by jumping to the head of the event stream silently
+// drops every message that arrived while it was down (crash, update, user
+// bounce). Users see that as "I said 继续 and the agent never answered". The
+// cursor is therefore persisted after every poll and resumed on start.
+//
+// Replay is bounded: on the first poll after a resume, messages older than
+// STALE_MESSAGE_MAX_AGE_MS are skipped (and the channel told), so a launcher
+// that was off for a day does not act on hours-old instructions unannounced.
+// This also covers a backend that ignores an unknown/deleted cursor and
+// returns history from the start. A persisted cursor older than
+// CURSOR_RESUME_MAX_AGE_MS is ignored altogether (jump to head as before).
+const STALE_MESSAGE_MAX_AGE_MS = 60 * 60 * 1000;
+const CURSOR_RESUME_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
 // Heartbeat runs every 30s. A SINGLE failure is usually a transient blip (brief
 // network hiccup, server redeploy) that the next tick recovers from — surfacing
 // it as a hard 'error' would make the agent flap red for no real reason. Only
@@ -77,6 +95,9 @@ class BaseAdapter {
     this._stopRequested = false;
     this.client = new WorkspaceClient(this.endpoint);
     this._lastEventId = null;
+    this._cursorFile = this._cursorFilePath();
+    this._lastPersistedCursor = null;
+    this._resumedFromCursor = false;
     this._running = false;
     this._sessionId = null;  // issued by server on /v1/join; used to prove liveness
     this._processedIds = new Set();
@@ -263,7 +284,64 @@ class BaseAdapter {
   // Event cursor / skip existing
   // ------------------------------------------------------------------
 
+  /** Where this agent's poll cursor lives between runs (per workspace+agent). */
+  _cursorFilePath() {
+    const safe = (v) => String(v || 'unknown').replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80);
+    return path.join(os.homedir(), '.openagents', 'cursors', `${safe(this.workspaceId)}__${safe(this.agentName)}.json`);
+  }
+
+  /** The cursor saved by the previous run, or null when absent/stale/foreign. */
+  _loadPersistedCursor() {
+    try {
+      const raw = JSON.parse(fs.readFileSync(this._cursorFile, 'utf-8'));
+      if (!raw || typeof raw.cursor !== 'string' || !raw.cursor) return null;
+      if (raw.workspaceId !== this.workspaceId || raw.agentName !== this.agentName) return null;
+      const age = Date.now() - (Number(raw.savedAt) || 0);
+      if (!(age >= 0 && age <= CURSOR_RESUME_MAX_AGE_MS)) return null;
+      return raw.cursor;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Persist the poll cursor (no-op when unchanged; never throws). */
+  _persistCursor(cursor) {
+    if (!cursor || cursor === this._lastPersistedCursor) return;
+    this._lastPersistedCursor = cursor;
+    try {
+      fs.mkdirSync(path.dirname(this._cursorFile), { recursive: true });
+      const tmp = `${this._cursorFile}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify({
+        cursor, savedAt: Date.now(), workspaceId: this.workspaceId, agentName: this.agentName,
+      }));
+      fs.renameSync(tmp, this._cursorFile);
+    } catch (e) {
+      if (!this._warnedCursorPersist) {
+        this._warnedCursorPersist = true;
+        this._log(`Could not persist poll cursor (${e.message}) — a restart will skip messages that arrive while offline`);
+      }
+    }
+  }
+
+  /** True when a replayed message is too old to act on (see STALE_MESSAGE_MAX_AGE_MS). */
+  _isStaleMessage(msg) {
+    if (!msg || !msg.createdAt) return false;
+    const t = Date.parse(msg.createdAt);
+    if (!Number.isFinite(t)) return false;
+    return Date.now() - t > STALE_MESSAGE_MAX_AGE_MS;
+  }
+
   async _skipExistingEvents() {
+    // Prefer the cursor the previous run persisted: a restart must not drop the
+    // messages that arrived in between (bounded by the stale filter in the
+    // poll loop).
+    const persisted = this._loadPersistedCursor();
+    if (persisted) {
+      this._lastEventId = persisted;
+      this._resumedFromCursor = true;
+      this._log(`Resuming from persisted cursor ${persisted}`);
+      return;
+    }
     // Jump straight to the head with one server call. Pagination from the
     // start was slow and brittle: on a busy workspace it could take many
     // minutes to chew through historical events 200 at a time, leaving the
@@ -272,6 +350,7 @@ class BaseAdapter {
     const head = await this.client.getHeadEventId(this.workspaceId, this.token);
     if (head) {
       this._lastEventId = head;
+      this._persistCursor(head);
       this._log(`Skipped existing events, cursor at ${head}`);
     }
   }
@@ -689,7 +768,16 @@ class BaseAdapter {
         continue;
       }
 
-      if (rawCursor) this._lastEventId = rawCursor;
+      if (rawCursor) {
+        this._lastEventId = rawCursor;
+        this._persistCursor(rawCursor);
+      }
+      // Only the first poll after resuming from a persisted cursor is a
+      // replay; later polls carry live traffic and are never age-filtered
+      // (a skewed local clock must not make a live agent go deaf).
+      const isReplay = this._resumedFromCursor;
+      this._resumedFromCursor = false;
+      const staleByChannel = {};
 
       // Deduplicate
       const incoming = [];
@@ -697,6 +785,12 @@ class BaseAdapter {
         const msgId = msg.id || msg.messageId;
         if (msgId && this._processedIds.has(msgId)) continue;
         if (msg.messageType === 'status') continue;
+        if (isReplay && this._isStaleMessage(msg)) {
+          if (msgId) this._processedIds.add(msgId);
+          const ch = msg.sessionId || this.channelName || 'general';
+          staleByChannel[ch] = (staleByChannel[ch] || 0) + 1;
+          continue;
+        }
         // Handle queue cancellation signals from frontend
         if (msg.messageType === 'queue_cancel') {
           if (msgId) this._processedIds.add(msgId);
@@ -708,6 +802,17 @@ class BaseAdapter {
         incoming.push(msg);
       }
 
+      for (const [ch, n] of Object.entries(staleByChannel)) {
+        const mins = Math.round(STALE_MESSAGE_MAX_AGE_MS / 60000);
+        this._log(`Skipped ${n} stale message(s) in ${ch} (older than ${mins} min, arrived while this agent was offline)`);
+        try {
+          await this.sendStatus(ch, `Skipped ${n} message(s) sent more than ${mins} minutes ago while this agent was offline — resend if still needed.`);
+        } catch {}
+      }
+      if (isReplay && incoming.length > 0) {
+        this._log(`Replaying ${incoming.length} message(s) that arrived while this agent was offline`);
+      }
+
       if (incoming.length > 0) {
         idleCount = 0;
         for (const msg of incoming) {
@@ -1231,3 +1336,5 @@ class BaseAdapter {
 }
 
 module.exports = BaseAdapter;
+module.exports.STALE_MESSAGE_MAX_AGE_MS = STALE_MESSAGE_MAX_AGE_MS;
+module.exports.CURSOR_RESUME_MAX_AGE_MS = CURSOR_RESUME_MAX_AGE_MS;

package/src/adapters/opencode.js

@@ -74,6 +74,7 @@ const FAILURE_MESSAGES = {
   timeout: 'OpenCode timed out before producing a reply. Retry; if it persists, check the model and provider configuration.',
   stream_parse_error: 'OpenCode produced output this version could not parse. Update to a supported OpenCode version, or open diagnostics.',
   empty_response: 'OpenCode finished without producing a final reply. Retry; if it persists, open diagnostics.',
+  incomplete_run: 'OpenCode stopped mid-task right after a tool call and never produced a final reply — its progress notes are shown above. Send "continue" to pick up where it left off. If this keeps happening, that tool call itself is failing (on Windows, prefer single-line commands over multi-line PowerShell).',
   process_crashed: 'OpenCode exited unexpectedly. Open diagnostics or retry.',
   cwd_unavailable: "OpenCode's working directory is not accessible. Check the agent's configured path (or agent home) permissions.",
   unknown_error: 'OpenCode failed for an undetermined reason. Open diagnostics or retry.',
@@ -449,6 +450,13 @@ class OpenCodeAdapter extends BaseAdapter {
     return text || null;
   }
 
+  /** Tool name from a tool event (null for non-tool events). */
+  static _toolNameFromEvent(event) {
+    if (!OpenCodeAdapter._isToolEvent(event)) return null;
+    const item = event.item || event.part || event.tool || event;
+    return OpenCodeAdapter._safeToolName(item.name || item.tool || item.toolName || item.id || 'tool');
+  }
+
   static _toolStatusFromEvent(event) {
     if (!OpenCodeAdapter._isToolEvent(event)) return null;
 
@@ -502,11 +510,13 @@ class OpenCodeAdapter extends BaseAdapter {
     const status = OpenCodeAdapter._toolStatusFromEvent(event);
     if (status) {
       // A tool call resets `finalText` (the "text since the last tool"), so the
-      // final answer is the text emitted AFTER the last tool. But we keep
-      // `allText` intact: if the run ends on a tool with no closing text, the
-      // earlier assistant text is still recoverable instead of being reported
-      // as an empty response (see _finalTextFromStdout).
-      if (responseState) responseState.finalText = '';
+      // final answer is the text emitted AFTER the last tool. `allText` stays
+      // intact for diagnostics, and `lastTool` lets the exit handler tell a
+      // finished answer from a run that died on its last tool call.
+      if (responseState) {
+        responseState.finalText = '';
+        responseState.lastTool = OpenCodeAdapter._toolNameFromEvent(event);
+      }
       await this.sendStatus(msgChannel, status);
       return;
     }
@@ -906,24 +916,75 @@ class OpenCodeAdapter extends BaseAdapter {
 
         // Exit 0.
         if (stdout) this._persistSessionId(msgChannel, stdout);
-        const text = stdout ? OpenCodeAdapter._finalTextFromStdout(stdout, responseState) : '';
-        if (text) return finish(resolve, text);
-
-        // Exit 0 with no final assistant text. This is NOT proof of a missing
-        // provider — it can be a structured error on stdout, an incomplete
-        // stream, or a genuinely empty completion. Classify rather than guess.
-        if (stdoutErr) {
-          const cls = OpenCodeAdapter._classifyFailure({ code, signal, stdout, stderr, stdoutErr });
-          this._log(`opencode exit 0 with error event → [${cls.category}]: ${OpenCodeAdapter._redact(cls.diagnostic).slice(0, 300)}`);
-          return finish(reject, this._failure(cls.category, cls.diagnostic, cls.detail));
-        }
-        const emptyCat = OpenCodeAdapter._emptyExitCategory(stdout);
-        this._log(`opencode exit 0, no final text → [${emptyCat}]. stdout head: ${OpenCodeAdapter._redact(stdout).slice(0, 200)}`);
-        return finish(reject, this._failure(emptyCat, `exit 0, no final assistant text; stdout head: ${stdout.slice(0, 200)}`));
+        const outcome = OpenCodeAdapter._outcomeForCleanExit({ stdout, stderr, stdoutErr, responseState });
+        if (outcome.text) return finish(resolve, outcome.text);
+        const f = outcome.failure;
+        this._log(`opencode exit 0 → [${f.category}]: ${OpenCodeAdapter._redact(f.diagnostic).slice(0, 300)}`);
+        return finish(reject, this._failure(f.category, f.diagnostic, f.detail));
       });
     });
   }
 
+  /**
+   * Decide what an exit-0 run means. Returns `{ text }` for a real reply or
+   * `{ failure: { category, diagnostic, detail } }`.
+   *
+   * A run that ends on a tool call with no text after it is NOT a finished
+   * answer: opencode stopped right as (or because) that tool ran. Field
+   * reports (Windows, multi-line PowerShell through the `bash` tool) showed
+   * the streamed reasoning being posted as the reply, which reads as the agent
+   * "going silent mid-task". Report it as a failure instead — preferring the
+   * structured error event when opencode emitted one — so the user gets a
+   * clear "stopped after `bash`" plus a way forward. Exit 0 with no text at
+   * all is likewise classified rather than guessed at.
+   */
+  static _outcomeForCleanExit({ stdout = '', stderr = '', stdoutErr = null, responseState = null } = {}) {
+    stdout = String(stdout || '').trim();
+    const state = responseState || {};
+    const lastTool = state.lastTool || null;
+    const endedOnTool = !!lastTool && !(state.finalText || '').trim();
+
+    if (endedOnTool) {
+      if (stdoutErr) {
+        const cls = OpenCodeAdapter._classifyFailure({ code: 0, signal: null, stdout, stderr, stdoutErr });
+        const vague = ['unknown_error', 'process_crashed', 'empty_response'].includes(cls.category);
+        return {
+          failure: {
+            category: vague ? 'incomplete_run' : cls.category,
+            diagnostic: `exit 0 after tool ${lastTool} with error event: ${cls.diagnostic || ''}`,
+            detail: cls.detail || `Last tool call: \`${lastTool}\``,
+          },
+        };
+      }
+      return {
+        failure: {
+          category: 'incomplete_run',
+          diagnostic: `exit 0 right after tool ${lastTool}, no final assistant text`,
+          detail: `Last tool call: \`${lastTool}\``,
+        },
+      };
+    }
+
+    const text = stdout ? OpenCodeAdapter._finalTextFromStdout(stdout, responseState) : '';
+    if (text) return { text };
+
+    // Exit 0 with no final assistant text. This is NOT proof of a missing
+    // provider — it can be a structured error on stdout, an incomplete
+    // stream, or a genuinely empty completion. Classify rather than guess.
+    if (stdoutErr) {
+      const cls = OpenCodeAdapter._classifyFailure({ code: 0, signal: null, stdout, stderr, stdoutErr });
+      return { failure: { category: cls.category, diagnostic: `exit 0 with error event: ${cls.diagnostic || ''}`, detail: cls.detail } };
+    }
+    const emptyCat = OpenCodeAdapter._emptyExitCategory(stdout);
+    return {
+      failure: {
+        category: emptyCat,
+        diagnostic: `exit 0, no final assistant text; stdout head: ${stdout.slice(0, 200)}`,
+        detail: '',
+      },
+    };
+  }
+
   // ------------------------------------------------------------------
   // Preflight (deterministic, no model call) + failure classification
   // ------------------------------------------------------------------
@@ -1069,7 +1130,8 @@ class OpenCodeAdapter extends BaseAdapter {
     const base = FAILURE_MESSAGES[category] || FAILURE_MESSAGES.unknown_error;
     const safe = detail ? OpenCodeAdapter._redact(detail).trim() : '';
     const body = safe ? `${base}\n\n> ${safe}` : base;
-    const content = `⚠️ **OpenCode couldn't run** — ${body}`;
+    const headline = category === 'incomplete_run' ? 'OpenCode stopped mid-task' : "OpenCode couldn't run";
+    const content = `⚠️ **${headline}** — ${body}`;
     try {
       await this.client.sendMessage(this.workspaceId, channel, this.token, content, {
         senderType: 'agent',

package/src/adapters/workspace-prompt.js

@@ -178,6 +178,25 @@ function buildCollaborationPrompt(toolMode = 'mcp', skillName = 'openagents-work
   );
 }
 
+/**
+ * Windows-only shell guidance for CLIs whose shell tool is named `bash`.
+ * Field reports (2026-09) show OpenCode runs on Windows ending the moment the
+ * model sends multi-line PowerShell (here-strings, hash-table literals,
+ * `$var = ...` blocks) through that tool: the turn stops with no reply and no
+ * error. Steering the model to single-line commands and the file tools avoids
+ * the failure at the source.
+ */
+function buildWindowsShellHint(isWindows = process.platform === 'win32') {
+  if (!isWindows) return '';
+  return (
+    '\n## Shell on Windows\n' +
+    'This machine runs Windows. When you run shell commands:\n' +
+    '- Keep every command on ONE line. Never send multi-line scripts, PowerShell here-strings (@"..."@), hash-table literals (@{...}) or `$var = ...` blocks through the shell tool — the run will abort.\n' +
+    '- To create or change files with multi-line content, use the file write/edit tools, not shell redirection or here-strings.\n' +
+    '- Prefer simple one-line commands (`dir`, `type`, `findstr`, `curl.exe`, version-control commands), or one short `powershell -Command "..."` per call.\n'
+  );
+}
+
 /**
  * Build mode-specific instructions.
  */
@@ -990,11 +1009,11 @@ function buildOpenclawSkillMd({ endpoint, workspaceId, token, agentName, channel
  * `decisionLog` / `glossary` opt in to knowledge pinning exactly as in
  * buildOpenclawSystemPrompt.
  */
-function buildOpenCodeSystemPrompt({ agentName, workspaceId, channelName, endpoint, token, mode = 'execute', disabledModules, browserEnabled = false, decisionLog = null, glossary = null }) {
+function buildOpenCodeSystemPrompt({ agentName, workspaceId, channelName, endpoint, token, mode = 'execute', disabledModules, browserEnabled = false, decisionLog = null, glossary = null, isWindows = process.platform === 'win32' }) {
   const identity = buildWorkspaceIdentity(agentName, workspaceId, channelName, mode, 'skills');
   const directive = buildBrowserDirective(browserEnabled);
   const collab = buildCollaborationPrompt('skills', workspaceSkillName(agentName));
-  const modePrompt = buildModePrompt(mode);
+  const modePrompt = buildModePrompt(mode) + buildWindowsShellHint(isWindows);
   const pinned = buildPinnedSections({ toolMode: 'skills', channelName, mode, decisionLog, glossary })
     .map((s) => '\n' + s).join('');
   const api = buildApiSkillsPrompt({ endpoint, workspaceId, token, agentName, channelName, disabledModules, mode });
@@ -1241,6 +1260,7 @@ module.exports = {
   buildBrowserDirective,
   buildCollaborationPrompt,
   buildModePrompt,
+  buildWindowsShellHint,
   buildGuardrails,
   buildApiSkillsPrompt,
   buildClaudeMcpToolBlock,

package/src/paths.js

@@ -19,21 +19,27 @@ const SEP = IS_WINDOWS ? ';' : ':';
 const HOME = process.env.HOME || process.env.USERPROFILE || '';
 const PATH_LOOKUP_CACHE_TTL_MS = 30 * 1000;
 
+let knownBinDirsCache = { value: null, at: 0 };
 let extraBinDirsCache = { value: null, at: 0, path: '' };
 const whichBinaryCache = new Map();
 
 /**
- * Get all extra binary directories that should be checked beyond process.env.PATH.
- * Returns deduplicated list of existing directories.
+ * Every directory an agent CLI is known to land in, filtered to the ones that
+ * exist on this machine. Ranked: a copy the launcher installed outranks a copy
+ * the user installed, which outranks whatever the login shell happens to add.
+ *
+ * This is the whole curated set, INCLUDING dirs that are already on PATH —
+ * which is what separates it from getExtraBinDirs(). Anything resolving a
+ * binary off the filesystem wants this one: that lookup exists precisely for
+ * the cases where asking the shell failed, and a dir being on PATH is no
+ * evidence at all that `where`/`which` succeeded (see resolveBinaryInKnownDirs).
  */
-function getExtraBinDirs() {
-  const currentPATH = process.env.PATH || '';
+function getKnownBinDirs() {
   if (
-    extraBinDirsCache.value &&
-    extraBinDirsCache.path === currentPATH &&
-    Date.now() - extraBinDirsCache.at < PATH_LOOKUP_CACHE_TTL_MS
+    knownBinDirsCache.value &&
+    Date.now() - knownBinDirsCache.at < PATH_LOOKUP_CACHE_TTL_MS
   ) {
-    return [...extraBinDirsCache.value];
+    return [...knownBinDirsCache.value];
   }
 
   const dirs = [];
@@ -99,8 +105,6 @@ function getExtraBinDirs() {
   const seen = new Set();
   const value = dirs.filter(d => {
     if (!d || seen.has(d)) return false;
-    // Skip if already in PATH (case-insensitive on Windows)
-    if (IS_WINDOWS ? currentPATH.toLowerCase().includes(d.toLowerCase()) : currentPATH.includes(d)) return false;
     seen.add(d);
     try {
       return fs.statSync(d).isDirectory();
@@ -108,6 +112,32 @@ function getExtraBinDirs() {
       return false;
     }
   });
+  knownBinDirsCache = { value, at: Date.now() };
+  return [...value];
+}
+
+/**
+ * The known bin dirs that are NOT already on PATH — i.e. what has to be
+ * PREPENDED to build an environment in which every agent CLI resolves.
+ *
+ * Only ever use this to build a PATH. It is a strict subset of
+ * getKnownBinDirs(), and the dirs it drops (%APPDATA%\npm, /usr/local/bin, …)
+ * are the most common install locations there are, so using it as "the dirs to
+ * search" hides exactly the agents a user installed themselves.
+ */
+function getExtraBinDirs() {
+  const currentPATH = process.env.PATH || '';
+  if (
+    extraBinDirsCache.value &&
+    extraBinDirsCache.path === currentPATH &&
+    Date.now() - extraBinDirsCache.at < PATH_LOOKUP_CACHE_TTL_MS
+  ) {
+    return [...extraBinDirsCache.value];
+  }
+  const value = getKnownBinDirs().filter((d) =>
+    // Case-insensitive on Windows.
+    IS_WINDOWS ? !currentPATH.toLowerCase().includes(d.toLowerCase()) : !currentPATH.includes(d),
+  );
   extraBinDirsCache = { value, at: Date.now(), path: currentPATH };
   return [...value];
 }
@@ -176,7 +206,13 @@ function whichBinary(name) {
     const result = execSync(cmd, {
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...process.env, PATH: getEnhancedPATH() },
+      // getEnhancedEnv(), never `{...process.env, PATH}`: spreading process.env
+      // on Windows yields a "Path" key, so assigning PATH creates a SECOND path
+      // variable and which of the two the child reads is undefined. It also
+      // supplies ComSpec, without which execSync's shell cannot even start in an
+      // Electron process that has no cmd.exe on PATH — and a `where` that never
+      // ran looks exactly like a CLI that isn't installed.
+      env: getEnhancedEnv(),
       timeout: 5000,
       windowsHide: true,
     });
@@ -335,10 +371,11 @@ function _addPackageManagerPaths(dirs) {
  * reasons; anything added here is picked up on both.
  */
 function _addAgentInstallerPaths(dirs) {
-  // opencode — `curl -fsSL https://opencode.ai/install | bash` defaults to
-  // ~/.opencode/bin and honours OPENCODE_INSTALL_DIR. Reported as
-  // "launcher can't see my opencode" (#648).
-  _push(dirs, process.env.OPENCODE_INSTALL_DIR || path.join(HOME, '.opencode', 'bin'));
+  // opencode — `curl -fsSL https://opencode.ai/install | bash` is the route
+  // opencode.ai leads with, and its INSTALL_DIR is ~/.opencode/bin, reached
+  // through a shell rc edit. Reported as "launcher can't see my opencode"
+  // (#648, and again on launcher 0.9.27).
+  _push(dirs, path.join(HOME, '.opencode', 'bin'));
 
   // kimi — the npm package (@moonshot-ai/kimi-code) declares a real `kimi` bin,
   // but its postinstall ALSO drops a native build in ~/.kimi-code/bin and puts
@@ -354,6 +391,61 @@ function _addAgentInstallerPaths(dirs) {
   _push(dirs, path.join(HOME, '.npm-global', 'bin'));
   _push(dirs, path.join(HOME, '.openagents', 'npm-global', 'bin'));
 
+  // codebuddy — the npm package drops the usual global shim, but CodeBuddy also
+  // ships a native build (the engine behind the WorkBuddy desktop app) that
+  // installs to its own directory. The codebuddy adapter has always searched
+  // these; the installer that decides whether it EXISTS had not.
+  _push(dirs, path.join(HOME, '.codebuddy', 'bin'));
+
+  // claude — `claude install` (the native, non-npm build) relocates the CLI to
+  // ~/.claude/local and reaches it through a shell alias, which a GUI process
+  // inherits no more than it inherits an rc-file PATH edit.
+  _push(dirs, path.join(HOME, '.claude', 'local'));
+
+  // hermes — the Unix installer's own bin dir. Its Windows counterparts are in
+  // _addWindowsPaths; this is the half nothing covered.
+  _push(dirs, path.join(HOME, '.hermes', 'bin'));
+
+  // Installers that let the user choose the install dir. Each of these CLIs
+  // reads an env var for its target, and a user who set one has their ONLY copy
+  // there — every hardcoded default above then finds nothing. Added rather than
+  // substituted: the default dir usually still holds an older copy, and which
+  // of the two is on the user's PATH is not ours to guess.
+  if (process.env.OPENCODE_INSTALL_DIR) _push(dirs, process.env.OPENCODE_INSTALL_DIR);
+  if (process.env.AMP_HOME) _push(dirs, path.join(process.env.AMP_HOME, 'bin'));
+  if (process.env.GOOSE_BIN_DIR) _push(dirs, process.env.GOOSE_BIN_DIR);
+  if (process.env.HERMES_INSTALL_DIR) _push(dirs, process.env.HERMES_INSTALL_DIR);
+  if (process.env.HERMES_HOME) _push(dirs, path.join(process.env.HERMES_HOME, 'bin'));
+
+  // uv — `uv tool install X` builds a venv at <uv tool dir>/X and only COPIES
+  // the executable into uv's bin dir, which reaches PATH through a shell rc
+  // edit a GUI launch never sees. Enumerated rather than named, for the same
+  // reason as pipx below: aider, mini-swe-agent and openworker all arrive this
+  // way today — `uv tool install mini-swe-agent` is the route mini's own docs
+  // give, and the mini adapter already searched here while the detection that
+  // decides whether mini EXISTS did not — and so will the next Python agent.
+  for (const root of _uvToolRoots()) {
+    try {
+      for (const d of fs.readdirSync(root, { withFileTypes: true })) {
+        if (d.isDirectory()) _push(dirs, path.join(root, d.name, IS_WINDOWS ? 'Scripts' : 'bin'));
+      }
+    } catch {}
+  }
+
+  // pipx — `pipx install X` puts the executable in <PIPX_HOME>/venvs/X/bin and
+  // only SYMLINKS it into PIPX_BIN_DIR. When that link step is skipped, or its
+  // dir is one a GUI launch can't see, the venv copy is the only one there is.
+  // Enumerated rather than listed by name: aider, mini-swe-agent and openworker
+  // are all installable this way, and so is the next Python agent.
+  for (const root of _pipxHomes()) {
+    try {
+      const venvs = path.join(root, 'venvs');
+      for (const d of fs.readdirSync(venvs, { withFileTypes: true })) {
+        if (d.isDirectory()) _push(dirs, path.join(venvs, d.name, IS_WINDOWS ? 'Scripts' : 'bin'));
+      }
+    } catch {}
+  }
+
   // The plain ~/bin some installers fall back to when ~/.local/bin is absent.
   _push(dirs, path.join(HOME, 'bin'));
 
@@ -365,7 +457,50 @@ function _addAgentInstallerPaths(dirs) {
     // cursor-agent also ships under Programs\ on some Windows installs — the
     // cursor adapter checks both, the installer only knew one.
     _push(dirs, path.join(lad, 'Programs', 'cursor-agent'));
+    // codebuddy's native Windows install.
+    _push(dirs, path.join(lad, 'CodeBuddy', 'bin'));
+    // winget's shim dir — how GitHub Copilot CLI arrives on Windows for anyone
+    // who didn't take the npm route. The copilot adapter knew it; nothing else did.
+    _push(dirs, path.join(lad, 'Microsoft', 'WinGet', 'Links'));
+  }
+}
+
+/**
+ * Roots uv keeps its tool venvs under. UV_TOOL_DIR wins when exported;
+ * otherwise it is the XDG data dir on Unix — macOS included, uv does NOT use
+ * ~/Library/Application Support for this — and %APPDATA%\uv\tools on Windows.
+ */
+function _uvToolRoots() {
+  if (process.env.UV_TOOL_DIR) return [process.env.UV_TOOL_DIR];
+  // os.homedir(), not the module-level HOME: uvToolBinDirs() is also called by
+  // the adapters and the post-install verifier at arbitrary times, and that
+  // constant is frozen at require time — which resolved to the developer's real
+  // home in a test that had moved $HOME.
+  const home = os.homedir();
+  if (IS_WINDOWS) {
+    const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    return [path.join(appData, 'uv', 'tools')];
   }
+  const dataHome = process.env.XDG_DATA_HOME || path.join(home, '.local', 'share');
+  return [path.join(dataHome, 'uv', 'tools')];
+}
+
+/**
+ * Roots pipx may keep its venvs under. PIPX_HOME wins when exported; otherwise
+ * pipx has moved its default once (~/.local/pipx → the platform user-data dir),
+ * so both layouts are still in the field.
+ */
+function _pipxHomes() {
+  if (process.env.PIPX_HOME) return [process.env.PIPX_HOME];
+  const roots = [path.join(HOME, '.local', 'pipx')];
+  if (IS_WINDOWS) {
+    if (process.env.LOCALAPPDATA) roots.push(path.join(process.env.LOCALAPPDATA, 'pipx', 'pipx'));
+  } else if (IS_MACOS) {
+    roots.push(path.join(HOME, 'Library', 'Application Support', 'pipx'));
+  } else {
+    roots.push(path.join(process.env.XDG_DATA_HOME || path.join(HOME, '.local', 'share'), 'pipx'));
+  }
+  return roots;
 }
 
 let npmPrefixCache;
@@ -594,6 +729,17 @@ function _addUnixPaths(dirs) {
   _push(dirs, '/usr/local/bin');
   _push(dirs, '/usr/bin');
 
+  // Homebrew on Linux. macOS gets /opt/homebrew and /usr/local from
+  // _addMacPaths; Linuxbrew's prefix is in neither list, and `brew install` is
+  // a real route for goose, opencode, gemini and codex. Its PATH entry comes
+  // from `brew shellenv` in a shell rc file — invisible to a GUI launch, the
+  // same reason every other dir here is listed explicitly.
+  if (!IS_MACOS) {
+    if (process.env.HOMEBREW_PREFIX) _push(dirs, path.join(process.env.HOMEBREW_PREFIX, 'bin'));
+    _push(dirs, '/home/linuxbrew/.linuxbrew/bin');
+    _push(dirs, path.join(HOME, '.linuxbrew', 'bin'));
+  }
+
   // npm agents install to isolated prefixes: ~/.openagents/runtimes/<type>/
 
   // nvm
@@ -767,6 +913,7 @@ function defaultAgentWorkdir(agentName) {
  * `whichBinary(name) === null` cached before install doesn't survive.
  */
 function clearBinaryLookupCache() {
+  knownBinDirsCache = { value: null, at: 0 };
   extraBinDirsCache = { value: null, at: 0, path: '' };
   whichBinaryCache.clear();
   // The login-shell / npm-prefix probes are deliberately NOT cleared: they each
@@ -785,7 +932,7 @@ function clearBinaryLookupCache() {
 function primeBinaryLookup() {
   try { loginShellDirs(); } catch {}
   try { _npmPrefix(); } catch {}
-  try { getExtraBinDirs(); } catch {}
+  try { getKnownBinDirs(); } catch {}
 }
 
 /**
@@ -811,15 +958,12 @@ function uvToolBinDirs(pkg) {
   if (process.env.XDG_BIN_HOME) dirs.push(process.env.XDG_BIN_HOME);
   if (process.env.XDG_DATA_HOME) dirs.push(path.join(process.env.XDG_DATA_HOME, '..', 'bin'));
   dirs.push(path.join(home, '.local', 'bin'));
+  for (const root of _uvToolRoots()) {
+    dirs.push(path.join(root, pkg, IS_WINDOWS ? 'Scripts' : 'bin'));
+  }
   if (IS_WINDOWS) {
-    const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
-    const uvTools = process.env.UV_TOOL_DIR || path.join(appData, 'uv', 'tools');
-    dirs.push(path.join(uvTools, pkg, 'Scripts'));
     dirs.push(path.join(home, 'bin'));
   } else {
-    const uvTools = process.env.UV_TOOL_DIR
-      || path.join(home, '.local', 'share', 'uv', 'tools');
-    dirs.push(path.join(uvTools, pkg, 'bin'));
     dirs.push(path.join(home, 'bin'), '/usr/local/bin', '/opt/homebrew/bin');
   }
   return dirs;
@@ -845,10 +989,19 @@ const BIN_EXTS = IS_WINDOWS ? ['.cmd', '.exe', '.bat', ''] : [''];
  * find it" and then opened a terminal running a bare command that could only
  * fail with "'cursor-agent' is not recognized".
  *
- * Deliberately reuses getExtraBinDirs() rather than a second hardcoded list:
+ * Deliberately reuses getKnownBinDirs() rather than a second hardcoded list:
  * that list already IS the curated set, and a copy of it is exactly how the
  * launcher and the adapters drifted apart in the first place.
  *
+ * It has to be the KNOWN dirs, not the extra ones. getExtraBinDirs() drops
+ * everything already on PATH, on the reasoning that PATH covers it — but the
+ * only way execution gets here is a `where`/`which` that ALREADY failed, and it
+ * fails wholesale on Windows (mangled OEM-codepage output on a non-English
+ * install, a 5s timeout, a cmd.exe that isn't resolvable from an Electron
+ * process). With the filter in place that failure erased every agent installed
+ * to a normal location — %APPDATA%\npm and friends — and the marketplace
+ * offered to install CodeBuddy/opencode/dsh over the copies already there.
+ *
  * Runs only after a PATH lookup has already missed, so it can add resolutions
  * but never change one that already works.
  *
@@ -868,7 +1021,7 @@ function resolveBinaryInKnownDirs(names, agentType) {
   if (agentType) push(path.join(getRuntimePrefix(agentType), 'node_modules', '.bin'));
   push(path.join(HOME, '.openagents', 'nodejs', 'node_modules', '.bin'));
   try { push(path.dirname(process.execPath)); } catch {}
-  for (const d of getExtraBinDirs()) push(d);
+  for (const d of getKnownBinDirs()) push(d);
 
   for (const dir of dirs) {
     for (const name of list) {
@@ -887,6 +1040,7 @@ function resolveBinaryInKnownDirs(names, agentType) {
 
 
 module.exports = {
+  getKnownBinDirs,
   getExtraBinDirs,
   getEnhancedPATH,
   getEnhancedEnv,