@openagents-org/agent-launcher 0.2.179 → 0.2.181

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagents-org/agent-launcher",
-  "version": "0.2.179",
+  "version": "0.2.181",
   "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/copilot-stream-parser.js

@@ -168,17 +168,50 @@ function parseLine(line) {
  * When real samples are available, extend THIS table only.
  */
 const EVENT_KIND_BY_TYPE = {
-  // session lifecycle / identity (kind only mapped when an id is also present)
+  // ── CAPTURED from a real authenticated run (CLI v1.0.83) ────────────────
+  // Every name in this block was read off a live JSONL stream, not inferred.
+  // The payload of each sits under `data` (see the `data` unwrap in
+  // classifyEvent) — except `result`, which is flat.
+  //
+  // The full type list observed in one turn: assistant.turn_start,
+  // assistant.reasoning_delta, assistant.reasoning, assistant.message_start,
+  // assistant.message_delta, assistant.turn_end, assistant.idle,
+  // model.call_start, model.call_finished, session.auto_mode_resolved,
+  // session.usage_checkpoint, session.tools_updated, session.skills_loaded,
+  // session.mcp_servers_loaded, session.mcp_server_status_changed,
+  // session.custom_agents_updated, user.message, result.
+  //
+  // The ones with no entry here are deliberate: they carry no content the
+  // workspace shows (lifecycle bookkeeping, or `user.message`, which is our
+  // own prompt echoed back). They degrade to `unknown`, which is logged and
+  // ignored — mapping them would put noise in the chat.
+  'assistant.message_delta': 'text_delta',   // data.deltaContent — THE answer
+  'assistant.reasoning': 'reasoning',        // data.content — ONE whole block
+  result: 'done',                            // flat: sessionId, exitCode, usage
+  // NOT mapped on purpose: `assistant.reasoning_delta`. Copilot streams at
+  // TOKEN granularity — 81 deltas for one short thought in the captured turn —
+  // and every adapter here narrates progress in whole blocks (claude sends
+  // `block.text`, codex `item.text`). Mapping the deltas posted one chat
+  // message per token: a column of "How" / "can" / "I" / "help" / "?" in the
+  // workspace. `assistant.reasoning` carries the same content as a single
+  // block afterwards, so that is what gets narrated.
+  'session.usage_checkpoint': 'usage',
+  'session.auto_mode_resolved': 'usage',     // data.chosenModel under Auto
+  'model.call_finished': 'usage',
+
+  // ── INFERRED — no live sample yet ───────────────────────────────────────
+  // The captured turn was a plain greeting, so no tool/file/shell/permission
+  // event appeared in it. The names below predate that capture and are kept
+  // as a net: they cost nothing (the real names above are matched first) and
+  // an unrecognized event is logged, never rendered. Replace them the moment
+  // a tool-using turn is captured — do not add more guesses.
   session: 'session', 'session.created': 'session', 'session.started': 'session',
   session_started: 'session', thread: 'session', 'thread.started': 'session',
-  // streaming assistant text (qualified names only — no bare 'delta'/'token')
   'text.delta': 'text_delta', text_delta: 'text_delta',
   'message.delta': 'text_delta', 'assistant.delta': 'text_delta',
   content_block_delta: 'text_delta',
-  // final assistant text (qualified/explicit names only — no bare 'message')
   text: 'text', 'message.completed': 'text', 'assistant.message': 'text',
   assistant: 'text', completion: 'text', agent_message: 'text',
-  // reasoning / status narration
   reasoning: 'reasoning', thinking: 'reasoning', thought: 'reasoning',
   status: 'reasoning', progress: 'reasoning',
   // tool calls
@@ -250,7 +283,14 @@ function classifyEvent(obj) {
     const itemKind = itemType ? EVENT_KIND_BY_TYPE[itemType.toLowerCase()] : undefined;
     if (itemKind) kind = itemKind;
   }
-  const src = item || obj;
+  // Copilot puts every event's payload under `data`, with the envelope
+  // (type/id/timestamp/parentId) on the outside — so reading fields off the
+  // top level found nothing and the answer came back empty. `result` is the
+  // one exception: it is flat, and falls through to `obj` here.
+  const data = (obj.data && typeof obj.data === 'object' && !Array.isArray(obj.data))
+    ? obj.data
+    : null;
+  const src = item || data || obj;
 
   switch (kind) {
     case 'session': {
@@ -261,7 +301,9 @@ function classifyEvent(obj) {
       return { kind: 'session', sessionId };
     }
     case 'text_delta': {
-      const text = _coerceText(src.delta) ?? _coerceText(src.text) ?? _coerceText(src.content) ?? _coerceText(src);
+      // `deltaContent` is Copilot's own field name, verified on v1.0.83.
+      const text = _coerceText(src.deltaContent) ?? _coerceText(src.delta)
+        ?? _coerceText(src.text) ?? _coerceText(src.content) ?? _coerceText(src);
       return { kind: 'text_delta', text: text || '' };
     }
     case 'text': {
@@ -269,7 +311,8 @@ function classifyEvent(obj) {
       return { kind: 'text', text: text || '' };
     }
     case 'reasoning': {
-      const text = _coerceText(src.text) ?? _coerceText(src.reasoning) ?? _coerceText(src.message)
+      const text = _coerceText(src.deltaContent) ?? _coerceText(src.text)
+        ?? _coerceText(src.reasoning) ?? _coerceText(src.message)
         ?? _coerceText(src.content) ?? _firstString(src, ['status', 'label', 'title']) ?? '';
       return { kind: 'reasoning', text };
     }
@@ -313,7 +356,14 @@ function classifyEvent(obj) {
     }
     case 'done': {
       const status = _firstString(src, ['status', 'reason', 'result']) || 'completed';
-      return { kind: 'done', status };
+      // The `result` frame is also where the real session id finally shows up
+      // — there is no session event earlier in the stream. Carrying it here is
+      // what lets the next turn resume instead of starting over. Read from the
+      // top level too: `result` is flat, so `src` is already `obj`, but an
+      // `item`-wrapped variant would not be.
+      const sessionId = _firstString(src, ['sessionId', 'session_id'])
+        ?? _firstString(obj, ['sessionId', 'session_id']);
+      return sessionId ? { kind: 'done', status, sessionId } : { kind: 'done', status };
     }
     case 'error': {
       const err = (src.error && typeof src.error === 'object') ? src.error : src;

package/src/adapters/copilot.js

@@ -606,10 +606,14 @@ class CopilotAdapter extends BaseAdapter {
             }
             break;
           case 'text_delta':
-            // Streamed interim text is shown live as `thinking`; the final
-            // `text` event (if any) is the authoritative answer.
+            // Accumulate only — never narrate. These deltas ARE the final
+            // answer being streamed a token at a time (Copilot's
+            // `assistant.message_delta`), and the answer is posted in full
+            // when the turn ends. Sending each one as `thinking` published the
+            // reply twice: once as a column of one-word messages, then again
+            // whole.
             if (sawToolSinceText) { finalParts.length = 0; deltaBuf = ''; sawToolSinceText = false; }
-            if (ev.text) { deltaBuf += ev.text; try { await this.sendThinking(channel, ev.text); } catch {} }
+            if (ev.text) deltaBuf += ev.text;
             break;
           case 'text':
             // A complete message supersedes the deltas streamed for this block.
@@ -655,6 +659,13 @@ class CopilotAdapter extends BaseAdapter {
             errorEvent = errorEvent || { message: ev.message, code: ev.code };
             break;
           case 'done':
+            // Copilot reports its session id only in the terminal `result`
+            // frame — no session event precedes it — so this is the one place
+            // a resumable id can be captured.
+            if (ev.sessionId && this._channelSessions[channel] !== ev.sessionId) {
+              this._channelSessions[channel] = ev.sessionId;
+              this._saveSessions();
+            }
             break;
           case 'unknown':
             // Preserve a redacted diagnostic; never crash the task.

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/daemon.js

@@ -43,6 +43,7 @@ class Daemon {
     this._statusInterval = null;
     this._cmdInterval = null;
     this._nodeHeartbeatInterval = null;  // device-level heartbeat (connect-a-node)
+    this._displayNameInterval = null;    // pulls workspace-side renames back
     this._nodeClients = new Map();       // workspace_id -> WorkspaceClient, one per pairing
     this._runningCommands = new Set();   // node-command ids currently executing
     this._runtimes = [];                 // detected agent runtimes for the node view
@@ -225,6 +226,50 @@ class Daemon {
     }
   }
 
+  /**
+   * Reflect workspace-side renames back onto this device.
+   *
+   * The workspace is treated as authoritative for the label, which needs no
+   * timestamps to be correct: a rename started on the device writes to the
+   * workspace FIRST and only then to local config (see
+   * AgentConnector.setAgentDisplayName), so by the time this reads, the
+   * workspace already holds whatever the device just set. Anything different
+   * from local therefore came from the workspace and should win.
+   *
+   * Never throws — a workspace that is unreachable simply leaves the labels
+   * as they are until the next pass.
+   */
+  async _syncDisplayNames() {
+    let pairings = [];
+    try {
+      pairings = require('./node-config').listPairings();
+    } catch { return; }
+
+    for (const n of pairings) {
+      if (!n.workspace_id || !n.token) continue;
+      let members = [];
+      try {
+        members = await this._nodeClientFor(n).getAgents(n.workspace_id, n.token);
+      } catch { continue; }
+
+      const byName = new Map(members.map((m) => [m.agentName, m]));
+      for (const a of this.config.getAgents()) {
+        // Scoped to this pairing's workspace, like _buildRoster: an agent in
+        // another workspace must never be relabelled from this one.
+        if (!this._agentOnNodeWorkspace(a, n)) continue;
+        const remote = byName.get(a.name);
+        if (!remote) continue;
+        const local = a.display_name || null;
+        const wanted = remote.displayName || null;
+        if (local === wanted) continue;
+        try {
+          this.config.updateAgent(a.name, { display_name: wanted || undefined });
+          this._log(`display name for ${a.name} updated from workspace`);
+        } catch {}
+      }
+    }
+  }
+
   /**
    * True if agent `a` is bound to the node's currently-connected workspace.
    * A missing network never matches (guards against undefined === undefined
@@ -608,6 +653,15 @@ async _runNodeCommand(n, cmd) {
       15000,
     );
 
+    // Pull display-name renames made in the workspace back onto the device, so
+    // the two sides agree whichever one the user typed into. Separate from the
+    // 10s heartbeat on purpose: a label changes rarely and this is an extra
+    // request per paired workspace, so it runs a sixth as often.
+    this._displayNameInterval = setInterval(
+      () => this._syncDisplayNames(),
+      60000,
+    );
+
     // Detect installed/logged-in agent runtimes for the Add-agent gallery. Runs
     // in a child process (off the event loop), refreshed periodically.
     this._refreshRuntimes();
@@ -658,6 +712,7 @@ async _runNodeCommand(n, cmd) {
     if (this._nodeHeartbeatInterval) clearInterval(this._nodeHeartbeatInterval);
     if (this._credReconcileInterval) clearInterval(this._credReconcileInterval);
     if (this._runtimesInterval) clearInterval(this._runtimesInterval);
+    if (this._displayNameInterval) clearInterval(this._displayNameInterval);
     if (this._probeStartupTimer) clearTimeout(this._probeStartupTimer);
     if (this._probeInterval) clearInterval(this._probeInterval);
     if (this._configWatcher) { try { this._configWatcher.close(); } catch {} }

package/src/index.js

@@ -84,6 +84,10 @@ class AgentConnector {
       const network = networks.find((n) => n.slug === a.network || n.id === a.network);
       return {
         name: a.name,
+        // The label to show. `name` stays the identity — callers that key on
+        // it (sessions, working dirs, workspace membership) must keep using
+        // `name`, never this.
+        displayName: a.display_name || null,
         type,
         role: a.role || 'worker',
         network: a.network || null,
@@ -100,6 +104,95 @@ class AgentConnector {
     return { success: true };
   }
 
+  /**
+   * The workspace an agent is bound to, as a ready-to-use client — or null
+   * when it is local-only or its network is no longer configured.
+   *
+   * Each network carries its own endpoint (a self-hosted workspace is not the
+   * official one), so the client is built per call rather than reusing
+   * `this.workspace`, the same way removeWorkspace does.
+   */
+  _workspaceClientFor(agentName) {
+    const agent = this.config.getAgent(agentName);
+    if (!agent || !agent.network) return null;
+    const network = this.config
+      .getNetworks()
+      .find((n) => n.slug === agent.network || n.id === agent.network);
+    if (!network || !network.id) return null;
+    const endpoint = network.endpoint || (this.workspace && this.workspace.endpoint);
+    const { WorkspaceClient } = require('./workspace-client');
+    return { client: new WorkspaceClient(endpoint), network };
+  }
+
+  /**
+   * Set (or clear, with an empty value) an agent's display label.
+   *
+   * The agent's `name` is its identity — it keys daemon.yaml, the working
+   * directory under ~/.openagents/agents, its sessions and its workspace
+   * membership — so renaming NEVER touches it. What changes is the label the
+   * launcher and the workspace show, which is precisely what the workspace
+   * already models as `display_name` next to `agent_name`.
+   *
+   * When the agent is in a workspace the new label is pushed there too, so the
+   * two sides agree. A workspace that rejects it (a name another member
+   * already answers to) fails the whole call rather than leaving the label
+   * changed on one side only.
+   */
+  async setAgentDisplayName(name, displayName) {
+    const agent = this.config.getAgent(name);
+    if (!agent) throw new Error(`Agent '${name}' not found`);
+    const label = (displayName || '').trim();
+
+    const bound = this._workspaceClientFor(name);
+    if (bound) {
+      await bound.client.setMemberDisplayName(
+        bound.network.id,
+        bound.network.token || '',
+        name,
+        label,
+      );
+    }
+    // Local write comes second: if the workspace refused the label, nothing
+    // here has changed and the two sides are still in agreement.
+    this.config.updateAgent(name, { display_name: label || undefined });
+    return { success: true, displayName: label || null };
+  }
+
+  /**
+   * Drop an agent's member row from the workspace it joined.
+   *
+   * Deliberately SEPARATE from removeAgent rather than a flag on it. Removing
+   * an agent is a synchronous local edit that `agn remove` and the TUI call
+   * without awaiting, inside a try/catch — making it async would turn a thrown
+   * error into an unhandled rejection those callers can no longer see. So the
+   * network half lives here, and a caller that wants both awaits this first:
+   * failing to reach the workspace then leaves the agent intact locally, which
+   * is the recoverable order.
+   *
+   * A local-only agent is a no-op success — there is nothing over there.
+   */
+  async removeAgentFromWorkspace(name) {
+    const bound = this._workspaceClientFor(name);
+    if (!bound) return { success: true, skipped: true };
+    try {
+      await bound.client.removeMember(
+        bound.network.id,
+        bound.network.token || '',
+        name,
+      );
+    } catch (e) {
+      // 404 is the goal state, reached by someone else: the member row is
+      // already gone, or the whole workspace is. Treating it as a failure
+      // would strand the agent on this device — removal happens local-last, so
+      // an error here means it cannot be removed at all. Anything else (a
+      // network blip, an auth failure) is real and must stop the removal so
+      // the user can retry rather than lose track of a live membership.
+      if (!e || e.status !== 404) throw e;
+      return { success: true, alreadyGone: true };
+    }
+    return { success: true };
+  }
+
   removeAgent(name) {
     this.config.removeAgent(name);
     return { success: true };
@@ -193,11 +286,38 @@ class AgentConnector {
     return { success: true };
   }
 
+  /**
+   * Local half of leaving a workspace: forget the binding, keep the agent.
+   *
+   * Synchronous, and deliberately still local-only — `agn disconnect` and the
+   * TUI call it without awaiting, inside a try/catch, so an async version
+   * would turn a throw into an unhandled rejection they can no longer see.
+   * Callers that want the membership dropped too use leaveWorkspace below.
+   */
   disconnectWorkspace(agentName) {
     this.config.setAgentNetwork(agentName, null);
     return { success: true };
   }
 
+  /**
+   * Leave a workspace properly: drop the member row over there, and unbind
+   * here — the agent itself stays, with its config, credentials and working
+   * directory, ready to join another workspace.
+   *
+   * Leaving only the local half is the bug this replaces. The device stopped
+   * showing the agent as connected while the workspace went on listing it as a
+   * member, and nothing in the launcher could reach that row any more. The
+   * workspace-level "remove a workspace" action learned this same lesson
+   * already (see removeWorkspace) — this is the agent-level equivalent.
+   *
+   * Workspace first, local second: a failure there leaves the agent bound and
+   * retryable rather than orphaning a membership.
+   */
+  async leaveWorkspace(agentName) {
+    await this.removeAgentFromWorkspace(agentName);
+    return this.disconnectWorkspace(agentName);
+  }
+
   async removeWorkspace(slug) {
     const networks = this.config.getNetworks();
     const network = networks.find(n => n.slug === slug || n.id === slug);

package/src/paths.js

@@ -371,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
@@ -405,6 +406,32 @@ function _addAgentInstallerPaths(dirs) {
   // _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.
@@ -438,6 +465,26 @@ function _addAgentInstallerPaths(dirs) {
   }
 }
 
+/**
+ * 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),
@@ -682,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
@@ -900,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;

package/src/workspace-client.js

@@ -84,6 +84,40 @@ class WorkspaceClient {
     }
   }
 
+  /**
+   * Remove one agent from a workspace via
+   * DELETE /v1/workspaces/{workspaceId}/members/{agentName}.
+   *
+   * Unlike deleteWorkspace above this is NOT best-effort: the caller offered
+   * the user a choice ("also remove it from the workspace"), so a failure has
+   * to be reported rather than swallowed — silently leaving the member behind
+   * is the exact problem this exists to fix.
+   */
+  async removeMember(workspaceId, token, agentName) {
+    await this._delete(
+      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(agentName)}`,
+      this._wsHeaders(token),
+    );
+  }
+
+  /**
+   * Rename one agent's DISPLAY name in a workspace, via
+   * PATCH /v1/workspaces/{workspaceId}/members/{agentName}.
+   *
+   * The agent's identity (`agent_name`) is untouched — this is the label the
+   * workspace shows and accepts as an @-mention alias, which is why the server
+   * rejects one that clashes with another member. An empty string clears the
+   * label there, falling back to `agent_name`, which is exactly what clearing
+   * the display name on this side means too.
+   */
+  async setMemberDisplayName(workspaceId, token, agentName, displayName) {
+    return this._patch(
+      `/v1/workspaces/${workspaceId}/members/${encodeURIComponent(agentName)}`,
+      { display_name: displayName || '' },
+      this._wsHeaders(token),
+    );
+  }
+
   /**
    * Join a workspace via POST /v1/join.
    */
@@ -514,6 +548,10 @@ class WorkspaceClient {
     const agents = (result && result.agents) || [];
     return agents.map((a) => ({
       agentName: (a.address || '').replace('openagents:', ''),
+      // The workspace's label for this agent, or null when it has none and
+      // falls back to agentName. Carried so a rename made in the workspace can
+      // be reflected back on the device.
+      displayName: a.display_name || null,
       role: a.role || 'member',
       status: a.status || 'offline',
       enabledSkills: a.enabled_skills || null,