@openagents-org/agent-launcher 0.2.143 → 0.2.146

package/src/adapters/workspace-prompt.js

@@ -462,7 +462,6 @@ function buildClaudeSystemPrompt({ agentName, workspaceId, channelName, mode = '
   );
   parts.push(buildBrowserDirective(browserEnabled));
   parts.push(buildCollaborationPrompt());
-  parts.push(buildA2UIPrompt());
 
   if (mode === 'plan') {
     parts.push(
@@ -476,83 +475,6 @@ function buildClaudeSystemPrompt({ agentName, workspaceId, channelName, mode = '
   return parts.join('\n');
 }
 
-/**
- * Teach the LLM how to emit interactive UI alongside its text response.
- * The frontend (OpenAgents Go) renders any A2UI-shaped JSON spec inline
- * in the chat bubble; the agent-connector strips the fenced block before
- * posting and ferries the spec via payload.spec.
- */
-function buildA2UIPrompt() {
-  return (
-    '\n## Rendering interactive UI\n' +
-    'When you want the user to interact with structured UI (a button choice, ' +
-    'a form, a chart, a table, a confirmation dialog) instead of just reading ' +
-    'text, emit a fenced code block tagged `a2ui` containing a JSON spec. The ' +
-    "frontend renders it inline below any markdown narration you write.\n\n" +
-    "The spec is a tree of `{ type, props, children?, action? }` nodes. " +
-    'Supported component types include `Stack`, `Heading`, `Text`, `Image`, ' +
-    '`Icon`, `Button`, `ChoiceList`, `ConfirmDialog`, `AmountInput`, `Card`, ' +
-    '`Divider`, `Spacer`, `Alert`, `LineChart`, `PieChart`, `AssetPrice`, ' +
-    '`BalanceCard`, `TransactionList`, `TransactionRow`. Unknown types render ' +
-    'as a placeholder chip, so feel free to compose freely.\n\n' +
-    'Interactive components attach an `action` object with a `name` field you ' +
-    'choose. Example:\n\n' +
-    '```a2ui\n' +
-    '{\n' +
-    '  "type": "Stack",\n' +
-    '  "props": { "direction": "vertical", "spacing": 12 },\n' +
-    '  "children": [\n' +
-    '    { "type": "Heading", "props": { "text": "Pick a time", "level": 2 } },\n' +
-    '    { "type": "Button", "props": { "label": "Morning", "action": { "name": "pick_morning" } } },\n' +
-    '    { "type": "Button", "props": { "label": "Evening", "action": { "name": "pick_evening" } } }\n' +
-    '  ]\n' +
-    '}\n' +
-    '```\n\n' +
-    '### Exact prop names (these are checked verbatim — guessing will render "No data")\n\n' +
-    'Layout / content:\n' +
-    '- `Stack` — props: `direction` ("vertical"|"horizontal"), `spacing`, `alignment`\n' +
-    '- `Card` — props: `title`, `padding`, `cornerRadius`\n' +
-    '- `Divider`, `Spacer` — props: `size`, `orientation`\n' +
-    '- `Heading` — props: `text`, `level` (1–4)\n' +
-    '- `Text` — props: `content` **(NOT `text`)**, `style`, `weight`, `color`\n' +
-    '- `Image` — props: `url`, `name`, `contentMode`, `width`, `height`\n' +
-    '- `Icon` — props: `name`, `size`, `color`\n\n' +
-    'Interactive:\n' +
-    '- `Button` — props: `label`, `style` ("primary"|"secondary"|"destructive"), `icon`, `disabled`, `action: {name, params?}`\n' +
-    '- `ConfirmDialog` — props: `title`, `message`, `confirmLabel`, `cancelLabel`, `triggerLabel`, `action`\n' +
-    '- `ChoiceList` — props: `question`, `options: [{id, label}]`, `action`\n' +
-    '- `AmountInput` — props: `label`, `placeholder`, `currency`, `action`\n' +
-    '- `input` (lowercase) — props: `inputType` ("text"|"choice"|"number"|"date"), `id`, `label`, `placeholder`, `options`\n\n' +
-    'Feedback:\n' +
-    '- `Alert` — props: `title`, `message`, `severity` ("info"|"success"|"warning"|"error"), `dismissible`, `action`\n\n' +
-    'Charts (Swift Charts under the hood — needs **non-empty** data with the right key):\n' +
-    '- `LineChart` — props: `title`, `color`, `points: [{x, y}]` **(NOT `data`)**\n' +
-    '- `PieChart` — props: `title`, `segments: [{label, value, color?}]` **(NOT `slices`)**, `showLegend`\n' +
-    '- `chart` (lowercase) — simple sparkline/bar: props: `style` ("sparkline"|"bar"), `data: [number, ...]`, `labels`, `color`\n\n' +
-    'Data display:\n' +
-    '- `metric` (lowercase) — props: `label`, `value`, `caption`, `captionColor`, `icon`\n' +
-    '- `list` (lowercase) — props: `items: [{title, subtitle, trailing, icon}]`, `maxVisible`, `expandLabel`\n' +
-    '- `table` (lowercase) — **key-value rows only, not multi-column**: props: `rows: [{label, value}]`, `maxVisible`\n\n' +
-    'There is no multi-column data table in the catalog. For tabular data with ' +
-    'columns you have two choices: (a) use `list` with title/subtitle/trailing ' +
-    'mapped to your columns, or (b) compose a Stack of horizontal Stacks of Text ' +
-    'manually. Pick whichever reads better.\n\n' +
-    'If your data is empty or you can\'t fit it into the available primitives, ' +
-    'fall back to plain markdown — don\'t emit a spec just to wrap text in a card.\n\n' +
-    'When the user interacts with a rendered component, you will receive a ' +
-    "user message shaped like `[ui_action] action=pick_morning tool_call_id=... value=...`. " +
-    "Use the `action` name (which you chose) to decide what to do next; the " +
-    "spec you emitted earlier is in your conversation history for context.\n\n" +
-    'Use a spec when:\n' +
-    '- The user needs to make a discrete choice (offer buttons rather than ' +
-    'asking them to type a free-form answer).\n' +
-    '- Structured data is easier to scan as a chart or table than as prose.\n' +
-    '- You need explicit confirmation before a destructive action.\n' +
-    "- A form would gather several fields faster than back-and-forth chat.\n\n" +
-    "Don't emit a spec for ordinary prose answers — narration alone is fine.\n"
-  );
-}
-
 /**
  * Build the full system prompt for OpenClaw/non-MCP agents.
  */
@@ -561,7 +483,6 @@ function buildOpenclawSystemPrompt({ agentName, workspaceId, channelName, endpoi
   parts.push(buildWorkspaceIdentity(agentName, workspaceId, channelName, mode));
   parts.push(buildBrowserDirective(browserEnabled));
   parts.push(buildCollaborationPrompt());
-  parts.push(buildA2UIPrompt());
   parts.push(buildModePrompt(mode));
   parts.push(buildApiSkillsPrompt({
     endpoint, workspaceId, token, agentName, channelName, disabledModules, mode,

package/src/agent-rows.js

@@ -40,7 +40,16 @@ function loadAgentRows(connector) {
     let health = null;
     try {
       health = connector.healthCheck(agent.type || 'openclaw');
-      if (health && !health.ready) notReadyMsg = health.message || 'Not configured';
+      if (health && !health.ready) {
+        // "Not installed" only when the executable is genuinely missing; an
+        // installed-but-signed-out agent shows its login/config message, never
+        // "Not installed". Mirrors the launcher's formatHealthLabel rule.
+        const notInstalled =
+          health.reason === 'not_installed' || health.installed === false;
+        notReadyMsg = notInstalled
+          ? 'Not installed'
+          : health.message || 'Not configured';
+      }
     } catch {}
 
     return {
@@ -55,6 +64,9 @@ function loadAgentRows(connector) {
       path: agent.path || '',
       network: agent.network || '',
       lastError: info.last_error || '',
+      // Structured daemon failure reason (spawn_failed / workspace_join_failed /
+      // heartbeat_failed / runtime_missing / …) paired with lastError.
+      errorReason: info.error_reason || '',
       notReadyMsg,
       health,
       configured: true,

package/src/auth-guidance.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * Pure, content-free helpers that turn an agent's registry `check_ready` plus a
+ * health-check result into human-readable authentication guidance.
+ *
+ * Used by the connector TUI (`showConfigureScreen`) and CLI (`agn env`) so an
+ * agent whose sign-in is an OAuth/credential FILE (e.g. Gemini's
+ * ~/.gemini/oauth_creds.json) is guided to authenticate instead of being
+ * mislabeled "No configuration required for this agent type".
+ *
+ * These helpers NEVER read, parse, copy, or print credential CONTENTS. They use
+ * only the agent's DECLARED metadata — the login command and env-var NAMES from
+ * `check_ready`, and the already-computed (non-sensitive) `message` / status
+ * fields the installer's health check returns. No token, key, email, or file
+ * path is ever emitted.
+ */
+
+/**
+ * True when an agent declares any credential / sign-in capability in
+ * `check_ready` — an OAuth/credential file, API-key env vars, a service-account
+ * path env, or a login command. This is the OPT-IN gate: agents WITHOUT any of
+ * these are left exactly as before (the caller keeps showing "No configuration
+ * required"), so other agents are never polluted by Gemini's guidance.
+ *
+ * @param {object|null|undefined} checkReady
+ * @returns {boolean}
+ */
+function hasCredentialMetadata(checkReady) {
+  if (!checkReady || typeof checkReady !== 'object') return false;
+  return !!(
+    checkReady.creds_file ||
+    (Array.isArray(checkReady.env_vars) && checkReady.env_vars.length) ||
+    (Array.isArray(checkReady.creds_path_env) && checkReady.creds_path_env.length) ||
+    checkReady.login_command
+  );
+}
+
+/**
+ * A short, NON-sensitive label for a ready auth_mode. Registry-overridable via
+ * `check_ready.auth_detected_labels` (e.g. Gemini maps cli_login → "Google
+ * account sign-in detected"). Falls back to a generic, agent-agnostic phrase so
+ * any future credential-file agent reads sensibly without extra config.
+ *
+ * @param {object} checkReady
+ * @param {string|null|undefined} authMode  'cli_login' | 'api_key' | other
+ * @returns {string}
+ */
+function readyLabel(checkReady, authMode) {
+  const labels = (checkReady && checkReady.auth_detected_labels) || {};
+  if (authMode === 'cli_login') return labels.cli_login || 'CLI sign-in detected';
+  if (authMode === 'api_key') return labels.api_key || 'API key detected';
+  return labels[authMode] || 'authenticated';
+}
+
+/**
+ * Build display lines (plain text, no markup, no secrets) describing an agent's
+ * authentication state and the concrete next step. The caller is responsible
+ * for any terminal styling.
+ *
+ * @param {object} entry   Registry catalog entry (has .label/.name/.check_ready)
+ * @param {object|null} health  Result of installer.healthCheck(type)
+ * @returns {{ ready: boolean, status: string, lines: string[] }}
+ */
+function formatAuthGuidance(entry, health) {
+  const checkReady = (entry && entry.check_ready) || {};
+  const label = (entry && (entry.label || entry.name)) || 'This agent';
+  const h = health || {};
+  const lines = [];
+
+  if (h.installed === false) {
+    lines.push(`${label} is not installed yet.`);
+    return { ready: false, status: 'not_installed', lines };
+  }
+
+  if (h.ready) {
+    lines.push(`Ready — ${readyLabel(checkReady, h.auth_mode)}.`);
+    return { ready: true, status: h.auth_status || 'ready', lines };
+  }
+
+  // Not ready: lead with the registry's own (non-sensitive) reason, then the
+  // concrete next steps derived from the DECLARED login command + env-var names.
+  if (h.message) lines.push(h.message);
+  const loginCmd = checkReady.login_command;
+  if (loginCmd) {
+    lines.push(
+      `Run \`${loginCmd}\` in your terminal and complete sign-in, then return here and refresh the agent status.`,
+    );
+  }
+  const envVars = Array.isArray(checkReady.env_vars) ? checkReady.env_vars : [];
+  if (envVars.length) {
+    lines.push(`Alternatively, configure ${envVars.join(' or ')}.`);
+  }
+  if (!lines.length) lines.push(`${label} requires authentication before use.`);
+  return { ready: false, status: h.auth_status || 'no_credentials', lines };
+}
+
+module.exports = { hasCredentialMetadata, readyLabel, formatAuthGuidance };

package/src/cli.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { AgentConnector, Daemon } = require('./index');
+const { hasCredentialMetadata, formatAuthGuidance } = require('./auth-guidance');
 
 // ---------------------------------------------------------------------------
 // Arg parsing
@@ -133,6 +134,18 @@ async function cmdCreate(connector, flags, positional) {
   const type = flags.type || 'openclaw';
   const role = flags.role || 'worker';
 
+  // Validate the runtime type BEFORE creating any local entry. A typo'd or
+  // otherwise unknown type (e.g. "calude") must not leave a broken agent in
+  // config — an uninstalled-but-valid type is fine and handled further down.
+  if (!connector.registry.getEntry(type)) {
+    const known = connector.registry.getCatalogSync().map((e) => e.name).sort();
+    print(`Error: unknown agent type '${type}'.`);
+    print(`Supported types: ${known.join(', ')}`);
+    print('Run `agn search` to browse available agent types.');
+    process.exitCode = 1;
+    return;
+  }
+
   try {
     connector.addAgent({ name, type, role, path: flags.path || process.cwd() });
 
@@ -483,14 +496,30 @@ async function cmdEnv(connector, flags, positional) {
       const display = field.password && val ? '***' : (val || '(not set)');
       print(`  ${field.name}: ${display}  ${field.required ? '(required)' : ''}`);
     }
+    return;
+  }
+
+  // No env_config, but the agent may still require a sign-in/credential (e.g.
+  // Gemini's OAuth login). Surface readiness + login guidance from the registry
+  // check_ready rather than a misleading "No env vars configured". Gated on
+  // credential metadata so plain no-config agents keep their existing output.
+  const entry = connector.registry.getEntry(type);
+  if (hasCredentialMetadata(entry && entry.check_ready)) {
+    let health = null;
+    try { health = connector.healthCheck(type); } catch {}
+    const g = formatAuthGuidance(entry, health);
+    print(`${entry.label || type} authentication status: ${g.ready ? 'Ready' : 'Not ready'}`);
+    print('');
+    for (const line of g.lines) print(line);
+    return;
+  }
+
+  const entries = Object.entries(env);
+  if (entries.length === 0) {
+    print(`No env vars configured for ${type}`);
   } else {
-    const entries = Object.entries(env);
-    if (entries.length === 0) {
-      print(`No env vars configured for ${type}`);
-    } else {
-      for (const [k, v] of entries) {
-        print(`  ${k}: ${v}`);
-      }
+    for (const [k, v] of entries) {
+      print(`  ${k}: ${v}`);
     }
   }
 }

package/src/config.js

@@ -426,8 +426,14 @@ function parseYamlValue(val) {
   if (val === 'true') return true;
   if (val === 'false') return false;
   if (/^\d+$/.test(val)) return parseInt(val, 10);
-  if ((val.startsWith("'") && val.endsWith("'")) ||
-      (val.startsWith('"') && val.endsWith('"'))) {
+  if (val.startsWith('"') && val.endsWith('"')) {
+    // Reverse serializeYamlValue's escaping (\\ → \, \" → "). Without this a
+    // double-quoted Windows path like "D:\重要资料" (quoted because of the drive
+    // colon) round-trips to D:\\重要资料 and accumulates an extra backslash on
+    // every save/load cycle, corrupting the agent's working dir.
+    return val.slice(1, -1).replace(/\\(["\\])/g, '$1');
+  }
+  if (val.startsWith("'") && val.endsWith("'")) {
     return val.slice(1, -1);
   }
   if (val.startsWith('{') || val.startsWith('[')) {

package/src/daemon.js

@@ -210,6 +210,7 @@ class Daemon {
         restarts: info.restarts,
         started_at: info.startedAt || null,
         last_error: info.lastError || null,
+        error_reason: info.errorReason || null,
       };
     }
     return result;
@@ -234,15 +235,17 @@ class Daemon {
     // Refuse to start if an existing daemon is already running.
     // Without this check, repeated `agn up` invocations would spawn
     // multiple daemons that each process the same message → duplicate
-    // bot replies.
-    const existingPid = Daemon._readPid(pidFile);
-    if (existingPid && Daemon._isAlive(existingPid)) {
+    // bot replies. Check BOTH the pid file and the status file (a live daemon
+    // rewrites the latter every 5s with its own pid): a clobbered/stale pid
+    // file must not let a duplicate slip past this guard.
+    const existingPid = Daemon.runningDaemonPid(configDir);
+    if (existingPid) {
       console.error(`Daemon already running (PID ${existingPid}).`);
       console.error(`Run 'agn down' first, or 'agn status' to check.`);
       process.exit(1);
     }
     // Stale pid file — clean up before spawning fresh
-    if (existingPid) {
+    if (Daemon._readPid(pidFile)) {
       try { fs.unlinkSync(pidFile); } catch {}
     }
 
@@ -286,41 +289,53 @@ class Daemon {
     const pidFile = path.join(configDir, 'daemon.pid');
     const statusFile = path.join(configDir, 'daemon.status.json');
 
-    const pid = Daemon._readPid(pidFile);
-    if (!pid) return false;
-
-    try {
-      if (IS_WINDOWS) {
-        execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore', timeout: 5000 });
-      } else {
-        process.kill(pid, 'SIGTERM');
-      }
-    } catch {}
-
-    // Always clean up PID and status files after kill attempt
-    try { fs.unlinkSync(pidFile); } catch {}
-    try { fs.unlinkSync(statusFile); } catch {}
-
-    // Wait briefly for process to die
-    for (let i = 0; i < 5; i++) {
-      if (!Daemon._isAlive(pid)) return true;
-      execSync(IS_WINDOWS ? 'ping -n 2 127.0.0.1 >nul' : 'sleep 0.5', {
-        stdio: 'ignore', timeout: 5000,
-      });
+    // Resolve the REAL running daemon(s) from BOTH the pid file and the status
+    // file. A live daemon rewrites the status file every 5s with its own pid,
+    // so when the pid file is stale/clobbered the status file is the only
+    // record of the actual process. The old code trusted only the pid file:
+    // `agn down` would signal a dead pid, delete the files, report "Daemon
+    // stopped", and leave the real daemon orphaned — which then blocked every
+    // subsequent `agn up` ("already running") and kept its agents wedged.
+    const pids = Daemon._liveDaemonPids(configDir);
+
+    // SIGTERM every distinct live pid.
+    for (const pid of pids) {
+      try {
+        if (IS_WINDOWS) {
+          execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore', timeout: 5000 });
+        } else {
+          process.kill(pid, 'SIGTERM');
+        }
+      } catch {}
     }
 
-    // Force kill
-    try {
-      if (IS_WINDOWS) {
-        execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore', timeout: 5000 });
-      } else {
-        process.kill(pid, 'SIGKILL');
+    // Wait briefly, then SIGKILL any survivor that ignored SIGTERM (this is
+    // what today's zombie required — a foreground daemon that didn't exit on
+    // SIGTERM).
+    for (const pid of pids) {
+      let alive = Daemon._isAlive(pid);
+      for (let i = 0; alive && i < 5; i++) {
+        execSync(IS_WINDOWS ? 'ping -n 2 127.0.0.1 >nul' : 'sleep 0.5', {
+          stdio: 'ignore', timeout: 5000,
+        });
+        alive = Daemon._isAlive(pid);
       }
-    } catch {}
+      if (alive) {
+        try {
+          if (IS_WINDOWS) {
+            execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore', timeout: 5000 });
+          } else {
+            process.kill(pid, 'SIGKILL');
+          }
+        } catch {}
+      }
+    }
 
+    // Always clear BOTH sources of truth so a fresh `agn up` starts clean.
     try { fs.unlinkSync(pidFile); } catch {}
     try { fs.unlinkSync(statusFile); } catch {}
-    return true;
+
+    return pids.length > 0;
   }
 
   /**
@@ -330,14 +345,18 @@ class Daemon {
     const pidFile = path.join(configDir, 'daemon.pid');
     const statusFile = path.join(configDir, 'daemon.status.json');
     const pid = Daemon._readPid(pidFile);
-    if (!pid) return null;
+    if (pid && Daemon._isAlive(pid)) return pid;
 
-    if (!Daemon._isAlive(pid)) {
-      Daemon._cleanupStaleDaemonFiles(pidFile, statusFile);
-      return null;
-    }
+    // pid file missing or stale — fall back to the status file so `agn status`
+    // reports the SAME live daemon the `agn up` singleton guard detects.
+    // Otherwise status says "not running" (dead pid file) while up refuses
+    // ("already running", from the status file) — the exact contradiction that
+    // hid today's orphaned daemon.
+    const live = Daemon.runningDaemonPid(configDir);
+    if (live) return live;
 
-    return pid;
+    Daemon._cleanupStaleDaemonFiles(pidFile, statusFile);
+    return null;
   }
 
   // ---------------------------------------------------------------------------
@@ -363,6 +382,9 @@ class Daemon {
       restarts: 0,
       startedAt: null,
       lastError: null,
+      // Structured failure reason (health-status REASON) paired with lastError,
+      // so the UI/TUI can classify "why" without parsing the message.
+      errorReason: null,
       proc: null,
       _backoff: 2,
     };
@@ -472,9 +494,33 @@ class Daemon {
   // Internal — adapter loop (workspace-connected agents)
   // ---------------------------------------------------------------------------
 
+  /**
+   * Apply a live status update reported by a running adapter (join/heartbeat
+   * health). A genuine failure reason → state 'error' + redacted last_error so
+   * the Agents list / TUI show the real cause; a null reason → recovered, clear
+   * the error. Ignored once the agent is stopping (a user stop must win).
+   */
+  _applyAdapterStatus(name, info, update) {
+    if (!update || this._shuttingDown || this._stoppedAgents.has(name)) return;
+    const { isErrorReason, redactDiagnostic } = require('./adapters/health-status');
+    const reason = update.reason || null;
+    if (reason && isErrorReason(reason)) {
+      info.state = 'error';
+      info.errorReason = reason;
+      info.lastError = redactDiagnostic(update.message || reason);
+    } else {
+      // Recovered / healthy again — clear any prior connectivity error.
+      if (info.state === 'error') info.state = 'running';
+      info.errorReason = null;
+      info.lastError = null;
+    }
+    this._writeStatus();
+  }
+
   async _adapterLoop(name, agentCfg, info, network) {
     const { createAdapter } = require('./adapters');
     const { skillsToDisabledModules } = require('./skill-catalog');
+    const { redactDiagnostic } = require('./adapters/health-status');
     const agentType = agentCfg.type || 'openclaw';
     const endpoint = network.endpoint || 'https://workspace-endpoint.openagents.org';
 
@@ -501,20 +547,46 @@ class Daemon {
         // .claude/skills there failed with EPERM. Root it under ~/.openagents.
         workingDir: agentCfg.path || defaultAgentWorkdir(name),
         toolMode: agentCfg.tool_mode || 'skills',
+        // Live runtime/connectivity status → daemon.status.json (Agents list/TUI).
+        onStatus: (update) => this._applyAdapterStatus(name, info, update),
       });
     } catch (e) {
-      this._log(`${name} failed to create ${agentType} adapter: ${e.message}`);
+      // A construction failure (e.g. unknown agent type in this core) is a hard
+      // error with a real cause — surface it (redacted), do not pretend stopped.
       info.state = 'error';
-      info.lastError = e.message;
+      info.errorReason = 'adapter_crashed';
+      info.lastError = redactDiagnostic(e.message || String(e));
+      this._log(`${name} failed to create ${agentType} adapter: ${info.lastError}`);
       this._writeStatus();
       return;
     }
 
+    // Preflight: when the agent's runtime binary is genuinely missing, surface a
+    // precise reason ('runtime_missing') and DO NOT join the workspace — there is
+    // no point spinning a join/poll loop that can never run the CLI. Adapters
+    // that don't override preflight() always pass.
+    try {
+      const pf =
+        typeof adapter.preflight === 'function' ? adapter.preflight() : null;
+      if (pf && pf.ok === false) {
+        info.state = 'error';
+        info.errorReason = pf.reason || 'runtime_missing';
+        info.lastError = redactDiagnostic(pf.message || 'runtime not available');
+        this._writeStatus();
+        this._log(`${name} preflight failed (${info.errorReason}): ${info.lastError}`);
+        return;
+      }
+    } catch (e) {
+      this._log(`${name} preflight error (ignored, continuing): ${e.message}`);
+    }
+
     // Store adapter reference for stop and duplicate detection
     this._adapters[name] = adapter;
 
     info.state = 'running';
     info.startedAt = new Date().toISOString();
+    info.lastError = null;
+    info.errorReason = null;
     this._writeStatus();
     this._log(`${name} adapter online → ${network.slug} (type: ${agentType})`);
 
@@ -531,14 +603,41 @@ class Daemon {
       await adapter.run();
       clearInterval(checkStop);
     } catch (e) {
-      info.lastError = (e.message || String(e)).slice(0, 200);
+      info.errorReason = info.errorReason || 'adapter_crashed';
+      info.lastError = redactDiagnostic((e.message || String(e)).slice(0, 200));
       this._log(`${name} adapter error: ${info.lastError}`);
     }
 
     delete this._adapters[name];
-    info.state = 'stopped';
+
+    // Final state: a clean stop (user stop / daemon shutdown) is NEVER an error.
+    // A terminal failure recorded by the adapter (join/heartbeat/session-revoked)
+    // or a crash surfaces as 'error' with its classified, redacted reason.
+    const userStopped =
+      this._shuttingDown ||
+      this._stoppedAgents.has(name) ||
+      (typeof adapter.wasStopRequested === 'function' && adapter.wasStopRequested());
+    if (userStopped) {
+      info.state = 'stopped';
+      info.lastError = null;
+      info.errorReason = null;
+    } else {
+      const exit =
+        (typeof adapter.getExitInfo === 'function' && adapter.getExitInfo()) ||
+        null;
+      if (exit && exit.reason) {
+        info.state = 'error';
+        info.errorReason = exit.reason;
+        info.lastError = redactDiagnostic(exit.message || exit.reason);
+      } else if (info.errorReason) {
+        // A crash, or a live error report that never recovered — keep it visible.
+        info.state = 'error';
+      } else {
+        info.state = 'stopped';
+      }
+    }
     this._writeStatus();
-    this._log(`${name} adapter stopped`);
+    this._log(`${name} adapter stopped (state: ${info.state})`);
   }
 
   // NOTE: Adapter-specific message handling (openclaw, claude, codex)
@@ -916,12 +1015,27 @@ class Daemon {
    * stopped for a legitimate restart doesn't block the replacement.
    */
   static runningDaemonPid(configDir) {
+    return Daemon._liveDaemonPids(configDir)[0] || null;
+  }
+
+  /**
+   * Return all distinct live daemon PIDs for this configDir (never including
+   * the calling process), gathered from BOTH the pid file and the status file.
+   * The pid file is considered first so its PID sorts ahead of the status
+   * file's. Used by the singleton guard, `agn status`, and `agn down` so every
+   * command agrees on which process(es) are the daemon — the divergence that
+   * let a stale pid file orphan a running daemon.
+   */
+  static _liveDaemonPids(configDir) {
     const self = process.pid;
-    const isOtherAlive = (pid) =>
-      pid && pid !== self && Daemon._isAlive(pid);
+    const pids = [];
+    const consider = (pid) => {
+      if (pid && pid !== self && Daemon._isAlive(pid) && !pids.includes(pid)) {
+        pids.push(pid);
+      }
+    };
 
-    const pidFromFile = Daemon._readPid(path.join(configDir, 'daemon.pid'));
-    if (isOtherAlive(pidFromFile)) return pidFromFile;
+    consider(Daemon._readPid(path.join(configDir, 'daemon.pid')));
 
     try {
       const statusFile = path.join(configDir, 'daemon.status.json');
@@ -930,11 +1044,11 @@ class Daemon {
       // unrelated process can't masquerade as a live daemon.
       if (age < 30000) {
         const raw = JSON.parse(fs.readFileSync(statusFile, 'utf-8'));
-        const pid = raw && raw.pid;
-        if (isOtherAlive(pid)) return pid;
+        consider(raw && raw.pid);
       }
     } catch {}
-    return null;
+
+    return pids;
   }
 }