@botcord/daemon 0.2.8 → 0.2.10

package/dist/control-channel.js

@@ -9,7 +9,7 @@
 import WebSocket from "ws";
 import { buildDaemonWebSocketUrl, CONTROL_FRAME_TYPES, jcsCanonicalize, resolveHubControlPublicKey, verifyEd25519, } from "@botcord/protocol-core";
 import { log as daemonLog } from "./log.js";
-import { writeAuthExpiredFlag, } from "./user-auth.js";
+import { AuthRefreshRejectedError, writeAuthExpiredFlag, } from "./user-auth.js";
 /** Exponential backoff plan for transient disconnects. */
 const RECONNECT_BACKOFF_MS = [1000, 2000, 4000, 8000, 16000, 30000];
 const KEEPALIVE_INTERVAL_MS = 25_000;
@@ -91,8 +91,18 @@ export class ControlChannel {
         });
         this.connectInflight = this.connect().catch((err) => {
             // Initial connect failure surfaces to the caller; subsequent
-            // reconnects are handled opaquely inside onClose.
-            this.scheduleReconnect(err);
+            // reconnects are handled opaquely inside onClose. A refresh-rejected
+            // error means the refresh token itself is dead — no point retrying;
+            // writeAuthExpiredFlag was already called in user-auth.refresh().
+            if (err instanceof AuthRefreshRejectedError) {
+                this.stopRequested = true;
+                daemonLog.warn("control-channel: refresh rejected; stopping (re-login required)", {
+                    status: err.status,
+                });
+            }
+            else {
+                this.scheduleReconnect(err);
+            }
             throw err;
         });
         try {
@@ -223,6 +233,13 @@ export class ControlChannel {
     scheduleReconnect(err) {
         if (this.stopRequested)
             return;
+        if (err instanceof AuthRefreshRejectedError) {
+            this.stopRequested = true;
+            daemonLog.warn("control-channel: refresh rejected; halting reconnect (re-login required)", {
+                status: err.status,
+            });
+            return;
+        }
         const attempt = this.reconnectAttempts;
         this.reconnectAttempts = attempt + 1;
         const delay = this.backoff[Math.min(attempt, this.backoff.length - 1)];

package/dist/doctor.js

@@ -156,6 +156,9 @@ export function renderDoctor(input) {
         const r = rows[i];
         const e = input.runtimes[i];
         lines.push(`${pad(r.runtime, widths.runtime)}  ${pad(r.name, widths.name)}  ${pad(r.status, widths.status)}  ${pad(r.version, widths.version)}  ${r.path}`);
+        if (!e.result.available && e.installHint) {
+            lines.push(`    → ${e.installHint}`);
+        }
         if (e.endpoints && e.endpoints.length > 0) {
             for (const ep of e.endpoints) {
                 const mark = ep.reachable ? "✓" : "✗";

package/dist/gateway/runtimes/hermes-agent.d.ts

@@ -1,7 +1,11 @@
 import { AcpRuntimeAdapter, type AcpPermissionRequest, type AcpPermissionResponse, type AcpUpdateCtx, type AcpUpdateParams } from "./acp-stream.js";
 import { type ProbeDeps } from "./probe.js";
 import type { RuntimeProbeResult, RuntimeRunOptions } from "../types.js";
-/** Resolve the `hermes-acp` executable on PATH. */
+/**
+ * Resolve the `hermes-acp` executable. Tries PATH first, then falls back to
+ * the upstream install.sh's private venv location (`~/.hermes/...`) before
+ * giving up. `BOTCORD_HERMES_AGENT_BIN` always wins via the adapter override.
+ */
 export declare function resolveHermesAcpCommand(deps?: ProbeDeps): string | null;
 /** Probe whether `hermes-acp` is installed and report its version. */
 export declare function probeHermesAgent(deps?: ProbeDeps): RuntimeProbeResult;

package/dist/gateway/runtimes/hermes-agent.js

@@ -3,10 +3,34 @@ import path from "node:path";
 import { agentHermesHomeDir, agentHermesWorkspaceDir, ensureAgentHermesWorkspace, } from "../../agent-workspace.js";
 import { buildCliEnv } from "../cli-resolver.js";
 import { AcpRuntimeAdapter, } from "./acp-stream.js";
-import { readCommandVersion, resolveCommandOnPath } from "./probe.js";
-/** Resolve the `hermes-acp` executable on PATH. */
+import { firstExistingPath, readCommandVersion, resolveCommandOnPath, resolveHomePath, } from "./probe.js";
+/**
+ * Known absolute locations of the `hermes-acp` entry point when it is not on
+ * PATH. The upstream `scripts/install.sh` (curl|bash installer) installs a
+ * private virtualenv under `~/.hermes/hermes-agent/venv/` and only symlinks
+ * the user-facing `hermes` command into `~/.local/bin/` — the `hermes-acp`
+ * entry point stays inside the venv. Without a fallback, daemon's PATH-only
+ * probe misses every user who installed via the README-recommended script.
+ */
+const HERMES_ACP_FALLBACK_RELATIVE_PATHS = [
+    path.join(".hermes", "hermes-agent", "venv", "bin", "hermes-acp"),
+];
+const HERMES_ACP_FALLBACK_SYSTEM_PATHS = [
+    "/opt/hermes/hermes-agent/venv/bin/hermes-acp",
+];
+/**
+ * Resolve the `hermes-acp` executable. Tries PATH first, then falls back to
+ * the upstream install.sh's private venv location (`~/.hermes/...`) before
+ * giving up. `BOTCORD_HERMES_AGENT_BIN` always wins via the adapter override.
+ */
 export function resolveHermesAcpCommand(deps = {}) {
-    return resolveCommandOnPath("hermes-acp", deps);
+    const onPath = resolveCommandOnPath("hermes-acp", deps);
+    if (onPath)
+        return onPath;
+    return firstExistingPath([
+        ...HERMES_ACP_FALLBACK_RELATIVE_PATHS.map((p) => resolveHomePath(p, deps)),
+        ...HERMES_ACP_FALLBACK_SYSTEM_PATHS,
+    ], deps);
 }
 /** Probe whether `hermes-acp` is installed and report its version. */
 export function probeHermesAgent(deps = {}) {

package/dist/gateway/runtimes/registry.d.ts

@@ -23,6 +23,11 @@ export interface RuntimeModule {
      * config loader rejects routing turns to this adapter.
      */
     supportsRun?: boolean;
+    /**
+     * Short, single-line install hint shown by `doctor` when the runtime
+     * probes as unavailable. Helps users recover without reading source.
+     */
+    installHint?: string;
 }
 /** Built-in runtime module entry for Claude Code. */
 export declare const claudeCodeModule: RuntimeModule;
@@ -58,6 +63,7 @@ export interface RuntimeProbeEntry {
     binary: string;
     supportsRun: boolean;
     result: RuntimeProbeResult;
+    installHint?: string;
 }
 /** Probe every registered runtime and report installation status. */
 export declare function detectRuntimes(): RuntimeProbeEntry[];

package/dist/gateway/runtimes/registry.js

@@ -28,6 +28,7 @@ export const hermesAgentModule = {
     envVar: "BOTCORD_HERMES_AGENT_BIN",
     probe: () => probeHermesAgent(),
     create: () => new HermesAgentAdapter(),
+    installHint: 'Install: pip install "hermes-agent[acp]"  (or set BOTCORD_HERMES_AGENT_BIN to the absolute path of hermes-acp)',
 };
 /** Built-in runtime module entry for Gemini (probe-only stub). */
 export const geminiModule = {
@@ -110,6 +111,7 @@ export function detectRuntimes() {
             binary: m.binary,
             supportsRun: m.supportsRun !== false,
             result,
+            installHint: m.installHint,
         });
     }
     return out;

package/dist/openclaw-discovery.js

@@ -46,13 +46,31 @@ export async function discoverLocalOpenclawGateways(opts = {}) {
 }
 export function mergeOpenclawGateways(cfg, found) {
     const existing = cfg.openclawGateways ?? [];
-    const existingUrls = new Set(existing.map((g) => normalizeUrlKey(g.url)));
+    const byUrl = new Map();
+    existing.forEach((g, i) => byUrl.set(normalizeUrlKey(g.url), i));
     const existingNames = new Set(existing.map((g) => g.name));
+    const merged = existing.map((g) => ({ ...g }));
     const added = [];
+    let mutated = false;
     for (const item of found) {
         const key = normalizeUrlKey(item.url);
-        if (existingUrls.has(key))
+        const idx = byUrl.get(key);
+        if (idx !== undefined) {
+            // Same URL already configured — only fill in auth that the user is
+            // missing, never overwrite an existing token / tokenFile.
+            const cur = merged[idx];
+            if (!cur.token && !cur.tokenFile) {
+                if (item.token) {
+                    cur.token = item.token;
+                    mutated = true;
+                }
+                else if (item.tokenFile) {
+                    cur.tokenFile = item.tokenFile;
+                    mutated = true;
+                }
+            }
             continue;
+        }
         const profile = {
             name: uniqueName(item.name, existingNames),
             url: item.url,
@@ -61,14 +79,15 @@ export function mergeOpenclawGateways(cfg, found) {
             profile.token = item.token;
         else if (item.tokenFile)
             profile.tokenFile = item.tokenFile;
-        existingUrls.add(key);
+        byUrl.set(key, merged.length);
         existingNames.add(profile.name);
+        merged.push(profile);
         added.push(profile);
     }
-    if (added.length === 0)
+    if (added.length === 0 && !mutated)
         return { cfg, changed: false, added };
     return {
-        cfg: { ...cfg, openclawGateways: [...existing, ...added] },
+        cfg: { ...cfg, openclawGateways: merged },
         changed: true,
         added,
     };
@@ -117,9 +136,34 @@ function discoverFromConfigDir(root) {
 }
 function parseJsonConfig(raw) {
     const obj = JSON.parse(raw);
+    // Prefer OpenClaw's native shape: `gateway.port` + `gateway.auth.token`.
+    // The legacy `acp.url` shape is also supported for explicit user-authored configs.
+    const native = pickOpenclawGatewayValues(obj?.gateway);
+    if (native)
+        return native;
     const acp = obj?.acp ?? obj?.gateway?.acp ?? obj?.gateway ?? obj;
     return pickConfigValues(acp);
 }
+function pickOpenclawGatewayValues(gw) {
+    if (!gw || typeof gw !== "object")
+        return null;
+    const port = typeof gw.port === "number" ? gw.port : undefined;
+    if (!port)
+        return null;
+    // Local discovery always targets the loopback interface, regardless of how
+    // the gateway is bound — the daemon is on the same machine.
+    const url = `ws://127.0.0.1:${port}`;
+    const auth = gw.auth;
+    const out = { url };
+    if (auth && typeof auth === "object" && auth.mode === "token") {
+        if (typeof auth.token === "string" && auth.token.trim())
+            out.token = auth.token.trim();
+        else if (typeof auth.tokenFile === "string" && auth.tokenFile.trim()) {
+            out.tokenFile = auth.tokenFile.trim();
+        }
+    }
+    return out;
+}
 function parseTomlConfig(raw) {
     let inAcp = false;
     const values = {};

package/dist/provision.js

@@ -4,7 +4,7 @@
  * side effects (register agent, write credentials, load route, add/remove
  * gateway channel) and return an ack payload.
  */
-import { existsSync, rmSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { BotCordClient, CONTROL_FRAME_TYPES, defaultCredentialsFile, derivePublicKey, loadStoredCredentials, writeCredentialsFile, } from "@botcord/protocol-core";
@@ -801,16 +801,22 @@ export function collectRuntimeSnapshot() {
 /** Maximum number of `endpoints[]` entries persisted per runtime (RFC §3.8.2). */
 export const RUNTIME_ENDPOINTS_CAP = 32;
 /**
- * Default L2 + L3 probe — opens a WS handshake against the OpenClaw gateway
- * and, when the connection is up, issues a JSON-RPC `agents.list` request to
- * enumerate configured agent profiles. Best-effort: a successful WS open with
- * a failed `agents.list` still reports `ok: true` (just without `agents`),
- * matching the RFC's "agents populated only when listing succeeded" rule.
+ * Default L2 + L3 probe — speaks OpenClaw's WS frame protocol against the
+ * gateway and enumerates agent profiles via `agents.list`.
  *
- * Method name and result shape follow OpenClaw:
- *   `~/claws/openclaw/src/gateway/server-methods/agents.ts:416` and
- *   `~/claws/openclaw/src/gateway/session-utils.ts:783` —
- *   `{ defaultId, mainKey, scope, agents: [{ id, name?, identity?, workspace, model? }] }`.
+ * Wire flow (see `~/claws/openclaw/src/gateway/server/ws-connection/message-handler.ts`
+ * and `~/claws/openclaw/src/gateway/protocol/schema/frames.ts`):
+ *   1. WS upgrade (no auth required at the HTTP layer).
+ *   2. Server emits `{type:"event", event:"connect.challenge", payload:{nonce}}`.
+ *   3. Client sends `{type:"req", id, method:"connect", params:{minProtocol, maxProtocol,
+ *      client:{id:"openclaw-probe", mode:"probe", ...}, auth:{token}}}`.
+ *   4. Server responds `{type:"res", id, ok:true, payload:{type:"hello-ok", server:{version}, ...}}`.
+ *   5. Client sends `{type:"req", id, method:"agents.list", params:{}}`.
+ *   6. Server responds with `{payload: { defaultId, mainKey, scope, agents:[{id, name?, workspace?, model?}] }}`.
+ *
+ * Best-effort: a successful WS open with a failed handshake / `agents.list`
+ * still reports `ok: true` (just without `agents`), matching the RFC's
+ * "agents populated only when listing succeeded" rule.
  */
 async function defaultWsProbe(args) {
     const { default: WebSocket } = await import("ws");
@@ -818,6 +824,9 @@ async function defaultWsProbe(args) {
         let settled = false;
         let ws;
         let timer;
+        let serverVersion;
+        const CONNECT_ID = "probe-connect";
+        let connectSent = false;
         const settle = (v) => {
             if (settled)
                 return;
@@ -834,6 +843,8 @@ async function defaultWsProbe(args) {
         };
         try {
             const headers = {};
+            // Some deployments gate the WS upgrade on Authorization too; harmless
+            // when not enforced — auth is also re-asserted in the connect frame.
             if (args.token)
                 headers["Authorization"] = `Bearer ${args.token}`;
             ws = new WebSocket(args.url, { headers });
@@ -843,65 +854,81 @@ async function defaultWsProbe(args) {
             return;
         }
         timer = setTimeout(() => settle({ ok: false, error: "timeout" }), args.timeoutMs);
-        const requestId = "probe-agents-list";
-        ws.on("open", () => {
-            // L3: enumerate agent profiles. We don't fail the L2 result if this
-            // call fails — the gateway is reachable either way.
+        const sendConnect = () => {
+            if (connectSent)
+                return;
+            connectSent = true;
+            const params = {
+                minProtocol: 3,
+                maxProtocol: 3,
+                client: {
+                    id: "openclaw-probe",
+                    version: "0.1.0",
+                    platform: process.platform || "node",
+                    mode: "probe",
+                },
+                role: "operator",
+                scopes: ["operator.read"],
+            };
+            if (args.token)
+                params.auth = { token: args.token };
             try {
-                ws.send(JSON.stringify({
-                    jsonrpc: "2.0",
-                    id: requestId,
-                    method: "agents.list",
-                    params: {},
-                }));
+                ws.send(JSON.stringify({ type: "req", id: CONNECT_ID, method: "connect", params }));
             }
             catch (err) {
-                settle({ ok: true, error: `agents.list send failed: ${err.message}` });
+                settle({ ok: true, error: `connect send failed: ${err.message}` });
             }
+        };
+        ws.on("open", () => {
+            // Some servers send `connect.challenge` before the socket is fully
+            // wired; if it never arrives we still try a best-effort connect after
+            // a short delay so the probe doesn't stall on legacy gateways.
+            setTimeout(() => {
+                if (!connectSent && !settled)
+                    sendConnect();
+            }, 250);
         });
         ws.on("message", (raw) => {
+            let msg;
             try {
-                const msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
-                if (msg?.id !== requestId)
-                    return; // ignore unrelated frames
-                if (msg.error) {
-                    settle({ ok: true, error: String(msg.error?.message ?? "agents.list error") });
+                msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
+            }
+            catch {
+                return;
+            }
+            if (!msg || typeof msg !== "object")
+                return;
+            if (msg.type === "event" && msg.event === "connect.challenge") {
+                // Nonce only matters for device-pairing flows; token-only auth ignores it.
+                sendConnect();
+                return;
+            }
+            if (msg.type !== "res" || typeof msg.id !== "string")
+                return;
+            if (msg.id === CONNECT_ID) {
+                if (!msg.ok) {
+                    const errMsg = msg.error?.message ? String(msg.error.message) : "connect rejected";
+                    settle({ ok: true, error: errMsg });
                     return;
                 }
-                const list = Array.isArray(msg.result?.agents) ? msg.result.agents : [];
-                const agents = [];
-                for (const a of list) {
-                    if (!a || typeof a.id !== "string" || a.id.length === 0)
-                        continue;
-                    const row = { id: a.id };
-                    if (typeof a.name === "string")
-                        row.name = a.name;
-                    if (typeof a.workspace === "string")
-                        row.workspace = a.workspace;
-                    if (a.model && typeof a.model === "object") {
-                        const model = {};
-                        if (typeof a.model.name === "string")
-                            model.name = a.model.name;
-                        if (typeof a.model.provider === "string")
-                            model.provider = a.model.provider;
-                        if (model.name || model.provider)
-                            row.model = model;
-                    }
-                    agents.push(row);
-                }
-                settle({ ok: true, agents });
-            }
-            catch (err) {
-                settle({ ok: true, error: `agents.list parse failed: ${err.message}` });
+                const v = msg.payload?.server?.version;
+                if (typeof v === "string" && v)
+                    serverVersion = v;
+                // We don't fetch agents.list over the wire: it requires `operator.read`
+                // which the gateway only grants to clients that present a paired device
+                // identity (see message-handler.ts:478 — self-declared scopes are
+                // cleared without device pairing). For local OpenClaw the agent list
+                // is sourced directly from disk by `probeOpenclawAgents`.
+                settle({ ok: true, version: serverVersion });
             }
         });
         ws.on("error", (err) => {
             settle({ ok: false, error: err.message });
         });
         ws.on("close", () => {
-            // If the socket closes before `agents.list` resolved we still treat
-            // L2 as ok (open fired) and emit no agents.
-            settle({ ok: true });
+            // If the socket closes before we got our agents.list response, treat
+            // L2 as ok (the upgrade succeeded) and emit no agents.
+            settle({ ok: true, version: serverVersion });
         });
     });
 }
@@ -913,11 +940,74 @@ export async function probeOpenclawAgents(profile, opts = {}) {
         ...(profile.token ? { token: profile.token } : {}),
         ...(profile.tokenFile ? { tokenFile: profile.tokenFile } : {}),
     });
-    return probe({
+    const result = await probe({
         url: profile.url,
         token: prepared.resolvedToken,
         timeoutMs: opts.timeoutMs ?? 3000,
     });
+    // For loopback gateways the agent roster lives in `~/.openclaw/openclaw.json`
+    // and is the source of truth — listing it over the wire would require a
+    // paired device identity (operator.read scope). When the WS probe is the
+    // default (i.e. no test injection) we enrich the result from disk.
+    if (result.ok && !result.agents && !opts.probe && isLoopbackUrl(profile.url)) {
+        const local = readLocalOpenclawAgents();
+        if (local && local.length > 0)
+            result.agents = local;
+    }
+    return result;
+}
+function isLoopbackUrl(raw) {
+    try {
+        const u = new URL(raw);
+        return u.hostname === "127.0.0.1" || u.hostname === "::1" || u.hostname === "localhost";
+    }
+    catch {
+        return false;
+    }
+}
+function readLocalOpenclawAgents() {
+    try {
+        const file = path.join(homedir(), ".openclaw", "openclaw.json");
+        if (!existsSync(file))
+            return null;
+        const cfg = JSON.parse(readFileSync(file, "utf8"));
+        const list = Array.isArray(cfg?.agents?.list) ? cfg.agents.list : [];
+        const defaultId = typeof cfg?.agents?.defaults?.id === "string" ? cfg.agents.defaults.id : "default";
+        const seen = new Set();
+        const out = [];
+        const push = (raw, fallbackId) => {
+            const id = typeof raw?.id === "string" && raw.id ? raw.id : fallbackId;
+            if (!id || seen.has(id))
+                return;
+            seen.add(id);
+            const row = { id };
+            if (typeof raw?.name === "string")
+                row.name = raw.name;
+            if (typeof raw?.workspace === "string")
+                row.workspace = raw.workspace;
+            const m = raw?.model;
+            if (m && typeof m === "object") {
+                const model = {};
+                if (typeof m.primary === "string")
+                    model.name = m.primary;
+                else if (typeof m.name === "string")
+                    model.name = m.name;
+                if (typeof m.provider === "string")
+                    model.provider = m.provider;
+                if (model.name || model.provider)
+                    row.model = model;
+            }
+            out.push(row);
+        };
+        // Default agent first so it surfaces at the top of the dropdown.
+        push({ id: defaultId, workspace: cfg?.agents?.defaults?.workspace, model: cfg?.agents?.defaults?.model }, defaultId);
+        for (const entry of list)
+            push(entry);
+        return out;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Async variant that includes L2 (gateway reachability) and L3 (agent listing)

package/dist/user-auth.d.ts

@@ -40,6 +40,15 @@ export declare function writeAuthExpiredFlag(file?: string): void;
 export declare function clearAuthExpiredFlag(file?: string): void;
 /** Returns true if the stored access token is within `windowMs` of expiry. */
 export declare function isTokenNearExpiry(record: UserAuthRecord, windowMs?: number): boolean;
+/**
+ * Thrown when the Hub rejects a refresh token (401/403). Signals that the
+ * user must re-login — reconnect loops should stop instead of hammering
+ * the refresh endpoint forever with a known-bad token.
+ */
+export declare class AuthRefreshRejectedError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
 /**
  * Stateful helper that owns the in-memory copy of user-auth and knows how
  * to refresh it. Used by the control channel so reconnects always carry

package/dist/user-auth.js

@@ -144,6 +144,19 @@ export function clearAuthExpiredFlag(file = AUTH_EXPIRED_FLAG_PATH) {
 export function isTokenNearExpiry(record, windowMs = 60_000) {
     return record.expiresAt - Date.now() <= windowMs;
 }
+/**
+ * Thrown when the Hub rejects a refresh token (401/403). Signals that the
+ * user must re-login — reconnect loops should stop instead of hammering
+ * the refresh endpoint forever with a known-bad token.
+ */
+export class AuthRefreshRejectedError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "AuthRefreshRejectedError";
+        this.status = status;
+    }
+}
 /**
  * Stateful helper that owns the in-memory copy of user-auth and knows how
  * to refresh it. Used by the control channel so reconnects always carry
@@ -197,13 +210,37 @@ export class UserAuthManager {
             expiresInMs: current.expiresAt - Date.now(),
         });
         this.refreshInflight = (async () => {
-            const tok = await refreshDaemonToken(current.hubUrl, current.refreshToken);
+            // Refresh tokens rotate server-side. If another local process (e.g. a
+            // second daemon racing on the same user-auth.json) refreshed in the
+            // meantime, the on-disk refreshToken now differs from our in-memory
+            // copy — using the in-memory one would 401 because the server already
+            // invalidated it. Re-read disk first and adopt any newer record.
+            let basis = current;
+            try {
+                const onDisk = loadUserAuth(this.file);
+                if (onDisk && onDisk.refreshToken !== current.refreshToken) {
+                    daemonLog.info("user-auth refresh: adopting newer on-disk token", {
+                        userId: onDisk.userId,
+                        expiresAt: onDisk.expiresAt,
+                    });
+                    this.record = onDisk;
+                    if (!isTokenNearExpiry(onDisk))
+                        return onDisk;
+                    basis = onDisk;
+                }
+            }
+            catch (err) {
+                daemonLog.debug("user-auth refresh: disk reread failed (ignored)", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            const tok = await refreshDaemonToken(basis.hubUrl, basis.refreshToken);
             const next = {
-                ...current,
+                ...basis,
                 accessToken: tok.accessToken,
                 refreshToken: tok.refreshToken,
                 expiresAt: Date.now() + tok.expiresIn * 1000,
-                hubUrl: tok.hubUrl || current.hubUrl,
+                hubUrl: tok.hubUrl || basis.hubUrl,
             };
             saveUserAuth(next, this.file);
             this.record = next;
@@ -213,10 +250,22 @@ export class UserAuthManager {
             });
             return next;
         })().catch((err) => {
+            const status = typeof err.status === "number"
+                ? (err.status)
+                : null;
+            const message = err instanceof Error ? err.message : String(err);
             daemonLog.warn("user-auth refresh: failed", {
                 userId: current.userId,
-                error: err instanceof Error ? err.message : String(err),
+                status,
+                error: message,
             });
+            if (status === 401 || status === 403) {
+                // Refresh token is permanently dead — write the expired flag so
+                // `status` surfaces it and re-throw a typed error so the control
+                // channel can stop reconnect loops instead of hammering the Hub.
+                writeAuthExpiredFlag();
+                throw new AuthRefreshRejectedError(status, message);
+            }
             throw err;
         }).finally(() => {
             this.refreshInflight = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/daemon",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "BotCord local daemon — bridges Hub inbox push to local Claude Code / Codex / Gemini CLIs",
   "type": "module",
   "bin": {

package/src/__tests__/openclaw-discovery.test.ts

@@ -62,6 +62,33 @@ describe("discoverLocalOpenclawGateways", () => {
     );
   });
 
+  it("parses OpenClaw's native gateway.port + auth.token shape", async () => {
+    const dir = tempDir();
+    writeFileSync(
+      path.join(dir, "openclaw.json"),
+      JSON.stringify({
+        gateway: {
+          port: 18789,
+          bind: "loopback",
+          auth: { mode: "token", token: "native-token" },
+        },
+      }),
+    );
+
+    const found = await discoverLocalOpenclawGateways({
+      searchPaths: [dir],
+      defaultPorts: [],
+    });
+
+    expect(found).toEqual([
+      expect.objectContaining({
+        url: "ws://127.0.0.1:18789",
+        token: "native-token",
+        source: "config-file",
+      }),
+    ]);
+  });
+
   it("uses OPENCLAW_ACP_URL and token env vars", async () => {
     const found = await discoverLocalOpenclawGateways({
       searchPaths: [],
@@ -124,6 +151,27 @@ describe("discoverLocalOpenclawGateways", () => {
 });
 
 describe("mergeOpenclawGateways", () => {
+  it("backfills token onto an existing profile that lacks one", () => {
+    const cfg = baseConfig();
+    cfg.openclawGateways = [
+      { name: "openclaw-127-0-0-1-18789", url: "ws://127.0.0.1:18789" },
+    ];
+    const merged = mergeOpenclawGateways(cfg, [
+      {
+        name: "openclaw-127-0-0-1-18789",
+        url: "ws://127.0.0.1:18789",
+        token: "discovered",
+        source: "config-file",
+      },
+    ]);
+
+    expect(merged.changed).toBe(true);
+    expect(merged.added).toEqual([]);
+    expect(merged.cfg.openclawGateways).toEqual([
+      { name: "openclaw-127-0-0-1-18789", url: "ws://127.0.0.1:18789", token: "discovered" },
+    ]);
+  });
+
   it("appends new URLs and keeps existing profiles untouched", () => {
     const cfg = baseConfig();
     cfg.openclawGateways = [{ name: "local", url: "ws://127.0.0.1:18789/acp", token: "user-token" }];

package/src/control-channel.ts

@@ -18,6 +18,7 @@ import {
 } from "@botcord/protocol-core";
 import { log as daemonLog } from "./log.js";
 import {
+  AuthRefreshRejectedError,
   writeAuthExpiredFlag,
   type UserAuthManager,
 } from "./user-auth.js";
@@ -142,8 +143,17 @@ export class ControlChannel {
     });
     this.connectInflight = this.connect().catch((err) => {
       // Initial connect failure surfaces to the caller; subsequent
-      // reconnects are handled opaquely inside onClose.
-      this.scheduleReconnect(err);
+      // reconnects are handled opaquely inside onClose. A refresh-rejected
+      // error means the refresh token itself is dead — no point retrying;
+      // writeAuthExpiredFlag was already called in user-auth.refresh().
+      if (err instanceof AuthRefreshRejectedError) {
+        this.stopRequested = true;
+        daemonLog.warn("control-channel: refresh rejected; stopping (re-login required)", {
+          status: err.status,
+        });
+      } else {
+        this.scheduleReconnect(err);
+      }
       throw err;
     });
     try {
@@ -285,6 +295,13 @@ export class ControlChannel {
 
   private scheduleReconnect(err?: unknown): void {
     if (this.stopRequested) return;
+    if (err instanceof AuthRefreshRejectedError) {
+      this.stopRequested = true;
+      daemonLog.warn("control-channel: refresh rejected; halting reconnect (re-login required)", {
+        status: err.status,
+      });
+      return;
+    }
     const attempt = this.reconnectAttempts;
     this.reconnectAttempts = attempt + 1;
     const delay = this.backoff[Math.min(attempt, this.backoff.length - 1)];

package/src/doctor.ts

@@ -257,6 +257,9 @@ export function renderDoctor(input: DoctorInput): string {
     lines.push(
       `${pad(r.runtime, widths.runtime)}  ${pad(r.name, widths.name)}  ${pad(r.status, widths.status)}  ${pad(r.version, widths.version)}  ${r.path}`,
     );
+    if (!e.result.available && e.installHint) {
+      lines.push(`    → ${e.installHint}`);
+    }
     if (e.endpoints && e.endpoints.length > 0) {
       for (const ep of e.endpoints) {
         const mark = ep.reachable ? "✓" : "✗";

package/src/gateway/__tests__/hermes-agent-adapter.test.ts

@@ -2,6 +2,7 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import {
   chmodSync,
   existsSync,
+  mkdirSync,
   mkdtempSync,
   readFileSync,
   rmSync,
@@ -9,7 +10,10 @@ import {
 } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { HermesAgentAdapter } from "../runtimes/hermes-agent.js";
+import {
+  HermesAgentAdapter,
+  resolveHermesAcpCommand,
+} from "../runtimes/hermes-agent.js";
 import { agentHermesWorkspaceDir } from "../../agent-workspace.js";
 
 // Spawn a tiny Node "ACP server" we control instead of the real hermes-acp.
@@ -288,6 +292,30 @@ describe("HermesAgentAdapter", () => {
     expect(res.error).toMatch(/aborted before spawn/);
   });
 
+  it("resolveHermesAcpCommand falls back to ~/.hermes venv when PATH lookup fails", () => {
+    // Upstream `scripts/install.sh` puts hermes-acp at
+    // ~/.hermes/hermes-agent/venv/bin/hermes-acp and only symlinks `hermes`
+    // into ~/.local/bin. Simulate that layout: `which hermes-acp` fails,
+    // but the venv path exists on disk.
+    const fakeHome = mkdtempSync(path.join(os.tmpdir(), "hermes-fallback-"));
+    const venvBin = path.join(fakeHome, ".hermes", "hermes-agent", "venv", "bin");
+    const target = path.join(venvBin, "hermes-acp");
+    mkdirSync(venvBin, { recursive: true });
+    writeFileSync(target, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    chmodSync(target, 0o755);
+
+    const resolved = resolveHermesAcpCommand({
+      env: { PATH: "/nonexistent" },
+      homeDir: fakeHome,
+      execFileSyncFn: (() => {
+        throw new Error("which: not found");
+      }) as never,
+    });
+    expect(resolved).toBe(target);
+
+    rmSync(fakeHome, { recursive: true, force: true });
+  });
+
   it("surfaces non-zero exit with stderr snippet", async () => {
     const p = path.join(tmpRoot, "boom.js");
     writeFileSync(

package/src/gateway/runtimes/hermes-agent.ts

@@ -13,12 +13,45 @@ import {
   type AcpUpdateCtx,
   type AcpUpdateParams,
 } from "./acp-stream.js";
-import { readCommandVersion, resolveCommandOnPath, type ProbeDeps } from "./probe.js";
+import {
+  firstExistingPath,
+  readCommandVersion,
+  resolveCommandOnPath,
+  resolveHomePath,
+  type ProbeDeps,
+} from "./probe.js";
 import type { RuntimeProbeResult, RuntimeRunOptions, StreamBlock } from "../types.js";
 
-/** Resolve the `hermes-acp` executable on PATH. */
+/**
+ * Known absolute locations of the `hermes-acp` entry point when it is not on
+ * PATH. The upstream `scripts/install.sh` (curl|bash installer) installs a
+ * private virtualenv under `~/.hermes/hermes-agent/venv/` and only symlinks
+ * the user-facing `hermes` command into `~/.local/bin/` — the `hermes-acp`
+ * entry point stays inside the venv. Without a fallback, daemon's PATH-only
+ * probe misses every user who installed via the README-recommended script.
+ */
+const HERMES_ACP_FALLBACK_RELATIVE_PATHS = [
+  path.join(".hermes", "hermes-agent", "venv", "bin", "hermes-acp"),
+];
+const HERMES_ACP_FALLBACK_SYSTEM_PATHS = [
+  "/opt/hermes/hermes-agent/venv/bin/hermes-acp",
+];
+
+/**
+ * Resolve the `hermes-acp` executable. Tries PATH first, then falls back to
+ * the upstream install.sh's private venv location (`~/.hermes/...`) before
+ * giving up. `BOTCORD_HERMES_AGENT_BIN` always wins via the adapter override.
+ */
 export function resolveHermesAcpCommand(deps: ProbeDeps = {}): string | null {
-  return resolveCommandOnPath("hermes-acp", deps);
+  const onPath = resolveCommandOnPath("hermes-acp", deps);
+  if (onPath) return onPath;
+  return firstExistingPath(
+    [
+      ...HERMES_ACP_FALLBACK_RELATIVE_PATHS.map((p) => resolveHomePath(p, deps)),
+      ...HERMES_ACP_FALLBACK_SYSTEM_PATHS,
+    ],
+    deps,
+  );
 }
 
 /** Probe whether `hermes-acp` is installed and report its version. */

package/src/gateway/runtimes/registry.ts

@@ -29,6 +29,11 @@ export interface RuntimeModule {
    * config loader rejects routing turns to this adapter.
    */
   supportsRun?: boolean;
+  /**
+   * Short, single-line install hint shown by `doctor` when the runtime
+   * probes as unavailable. Helps users recover without reading source.
+   */
+  installHint?: string;
 }
 
 /** Built-in runtime module entry for Claude Code. */
@@ -58,6 +63,8 @@ export const hermesAgentModule: RuntimeModule = {
   envVar: "BOTCORD_HERMES_AGENT_BIN",
   probe: () => probeHermesAgent(),
   create: () => new HermesAgentAdapter(),
+  installHint:
+    'Install: pip install "hermes-agent[acp]"  (or set BOTCORD_HERMES_AGENT_BIN to the absolute path of hermes-acp)',
 };
 
 /** Built-in runtime module entry for Gemini (probe-only stub). */
@@ -143,6 +150,7 @@ export interface RuntimeProbeEntry {
   binary: string;
   supportsRun: boolean;
   result: RuntimeProbeResult;
+  installHint?: string;
 }
 
 /** Probe every registered runtime and report installation status. */
@@ -161,6 +169,7 @@ export function detectRuntimes(): RuntimeProbeEntry[] {
       binary: m.binary,
       supportsRun: m.supportsRun !== false,
       result,
+      installHint: m.installHint,
     });
   }
   return out;

package/src/openclaw-discovery.ts

@@ -84,27 +84,46 @@ export function mergeOpenclawGateways(
   found: DiscoveredOpenclawGateway[],
 ): MergeOpenclawGatewayResult {
   const existing = cfg.openclawGateways ?? [];
-  const existingUrls = new Set(existing.map((g) => normalizeUrlKey(g.url)));
+  const byUrl = new Map<string, number>();
+  existing.forEach((g, i) => byUrl.set(normalizeUrlKey(g.url), i));
   const existingNames = new Set(existing.map((g) => g.name));
+  const merged = existing.map((g) => ({ ...g }));
   const added: OpenclawGatewayProfile[] = [];
+  let mutated = false;
 
   for (const item of found) {
     const key = normalizeUrlKey(item.url);
-    if (existingUrls.has(key)) continue;
+    const idx = byUrl.get(key);
+    if (idx !== undefined) {
+      // Same URL already configured — only fill in auth that the user is
+      // missing, never overwrite an existing token / tokenFile.
+      const cur = merged[idx];
+      if (!cur.token && !cur.tokenFile) {
+        if (item.token) {
+          cur.token = item.token;
+          mutated = true;
+        } else if (item.tokenFile) {
+          cur.tokenFile = item.tokenFile;
+          mutated = true;
+        }
+      }
+      continue;
+    }
     const profile: OpenclawGatewayProfile = {
       name: uniqueName(item.name, existingNames),
       url: item.url,
     };
     if (item.token) profile.token = item.token;
     else if (item.tokenFile) profile.tokenFile = item.tokenFile;
-    existingUrls.add(key);
+    byUrl.set(key, merged.length);
     existingNames.add(profile.name);
+    merged.push(profile);
     added.push(profile);
   }
 
-  if (added.length === 0) return { cfg, changed: false, added };
+  if (added.length === 0 && !mutated) return { cfg, changed: false, added };
   return {
-    cfg: { ...cfg, openclawGateways: [...existing, ...added] },
+    cfg: { ...cfg, openclawGateways: merged },
     changed: true,
     added,
   };
@@ -148,10 +167,34 @@ function discoverFromConfigDir(root: string): DiscoveredOpenclawGateway[] {
 
 function parseJsonConfig(raw: string): { url?: string; token?: string; tokenFile?: string } | null {
   const obj = JSON.parse(raw) as any;
+  // Prefer OpenClaw's native shape: `gateway.port` + `gateway.auth.token`.
+  // The legacy `acp.url` shape is also supported for explicit user-authored configs.
+  const native = pickOpenclawGatewayValues(obj?.gateway);
+  if (native) return native;
   const acp = obj?.acp ?? obj?.gateway?.acp ?? obj?.gateway ?? obj;
   return pickConfigValues(acp);
 }
 
+function pickOpenclawGatewayValues(
+  gw: any,
+): { url?: string; token?: string; tokenFile?: string } | null {
+  if (!gw || typeof gw !== "object") return null;
+  const port = typeof gw.port === "number" ? gw.port : undefined;
+  if (!port) return null;
+  // Local discovery always targets the loopback interface, regardless of how
+  // the gateway is bound — the daemon is on the same machine.
+  const url = `ws://127.0.0.1:${port}`;
+  const auth = gw.auth;
+  const out: { url: string; token?: string; tokenFile?: string } = { url };
+  if (auth && typeof auth === "object" && auth.mode === "token") {
+    if (typeof auth.token === "string" && auth.token.trim()) out.token = auth.token.trim();
+    else if (typeof auth.tokenFile === "string" && auth.tokenFile.trim()) {
+      out.tokenFile = auth.tokenFile.trim();
+    }
+  }
+  return out;
+}
+
 function parseTomlConfig(raw: string): { url?: string; token?: string; tokenFile?: string } | null {
   let inAcp = false;
   const values: Record<string, string> = {};

package/src/provision.ts

@@ -4,7 +4,7 @@
  * side effects (register agent, write credentials, load route, add/remove
  * gateway channel) and return an ack payload.
  */
-import { existsSync, rmSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import {
@@ -957,16 +957,22 @@ export type WsEndpointProbeFn = (args: {
 }>;
 
 /**
- * Default L2 + L3 probe — opens a WS handshake against the OpenClaw gateway
- * and, when the connection is up, issues a JSON-RPC `agents.list` request to
- * enumerate configured agent profiles. Best-effort: a successful WS open with
- * a failed `agents.list` still reports `ok: true` (just without `agents`),
- * matching the RFC's "agents populated only when listing succeeded" rule.
+ * Default L2 + L3 probe — speaks OpenClaw's WS frame protocol against the
+ * gateway and enumerates agent profiles via `agents.list`.
  *
- * Method name and result shape follow OpenClaw:
- *   `~/claws/openclaw/src/gateway/server-methods/agents.ts:416` and
- *   `~/claws/openclaw/src/gateway/session-utils.ts:783` —
- *   `{ defaultId, mainKey, scope, agents: [{ id, name?, identity?, workspace, model? }] }`.
+ * Wire flow (see `~/claws/openclaw/src/gateway/server/ws-connection/message-handler.ts`
+ * and `~/claws/openclaw/src/gateway/protocol/schema/frames.ts`):
+ *   1. WS upgrade (no auth required at the HTTP layer).
+ *   2. Server emits `{type:"event", event:"connect.challenge", payload:{nonce}}`.
+ *   3. Client sends `{type:"req", id, method:"connect", params:{minProtocol, maxProtocol,
+ *      client:{id:"openclaw-probe", mode:"probe", ...}, auth:{token}}}`.
+ *   4. Server responds `{type:"res", id, ok:true, payload:{type:"hello-ok", server:{version}, ...}}`.
+ *   5. Client sends `{type:"req", id, method:"agents.list", params:{}}`.
+ *   6. Server responds with `{payload: { defaultId, mainKey, scope, agents:[{id, name?, workspace?, model?}] }}`.
+ *
+ * Best-effort: a successful WS open with a failed handshake / `agents.list`
+ * still reports `ok: true` (just without `agents`), matching the RFC's
+ * "agents populated only when listing succeeded" rule.
  */
 async function defaultWsProbe(args: {
   url: string;
@@ -1000,6 +1006,9 @@ async function defaultWsProbe(args: {
     let settled = false;
     let ws: any;
     let timer: ReturnType<typeof setTimeout> | undefined;
+    let serverVersion: string | undefined;
+    const CONNECT_ID = "probe-connect";
+    let connectSent = false;
     const settle = (v: ProbeResult): void => {
       if (settled) return;
       settled = true;
@@ -1013,6 +1022,8 @@ async function defaultWsProbe(args: {
     };
     try {
       const headers: Record<string, string> = {};
+      // Some deployments gate the WS upgrade on Authorization too; harmless
+      // when not enforced — auth is also re-asserted in the connect frame.
       if (args.token) headers["Authorization"] = `Bearer ${args.token}`;
       ws = new WebSocket(args.url, { headers });
     } catch (err) {
@@ -1020,58 +1031,75 @@ async function defaultWsProbe(args: {
       return;
     }
     timer = setTimeout(() => settle({ ok: false, error: "timeout" }), args.timeoutMs);
-    const requestId = "probe-agents-list";
-    ws.on("open", () => {
-      // L3: enumerate agent profiles. We don't fail the L2 result if this
-      // call fails — the gateway is reachable either way.
+
+    const sendConnect = (): void => {
+      if (connectSent) return;
+      connectSent = true;
+      const params: any = {
+        minProtocol: 3,
+        maxProtocol: 3,
+        client: {
+          id: "openclaw-probe",
+          version: "0.1.0",
+          platform: process.platform || "node",
+          mode: "probe",
+        },
+        role: "operator",
+        scopes: ["operator.read"],
+      };
+      if (args.token) params.auth = { token: args.token };
       try {
-        ws.send(
-          JSON.stringify({
-            jsonrpc: "2.0",
-            id: requestId,
-            method: "agents.list",
-            params: {},
-          }),
-        );
+        ws.send(JSON.stringify({ type: "req", id: CONNECT_ID, method: "connect", params }));
       } catch (err) {
-        settle({ ok: true, error: `agents.list send failed: ${(err as Error).message}` });
+        settle({ ok: true, error: `connect send failed: ${(err as Error).message}` });
       }
+    };
+
+    ws.on("open", () => {
+      // Some servers send `connect.challenge` before the socket is fully
+      // wired; if it never arrives we still try a best-effort connect after
+      // a short delay so the probe doesn't stall on legacy gateways.
+      setTimeout(() => {
+        if (!connectSent && !settled) sendConnect();
+      }, 250);
     });
     ws.on("message", (raw: Buffer | string) => {
+      let msg: any;
       try {
-        const msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
-        if (msg?.id !== requestId) return; // ignore unrelated frames
-        if (msg.error) {
-          settle({ ok: true, error: String(msg.error?.message ?? "agents.list error") });
+        msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
+      } catch {
+        return;
+      }
+      if (!msg || typeof msg !== "object") return;
+      if (msg.type === "event" && msg.event === "connect.challenge") {
+        // Nonce only matters for device-pairing flows; token-only auth ignores it.
+        sendConnect();
+        return;
+      }
+      if (msg.type !== "res" || typeof msg.id !== "string") return;
+      if (msg.id === CONNECT_ID) {
+        if (!msg.ok) {
+          const errMsg = msg.error?.message ? String(msg.error.message) : "connect rejected";
+          settle({ ok: true, error: errMsg });
           return;
         }
-        const list = Array.isArray(msg.result?.agents) ? msg.result.agents : [];
-        const agents: AgentRow[] = [];
-        for (const a of list) {
-          if (!a || typeof a.id !== "string" || a.id.length === 0) continue;
-          const row: AgentRow = { id: a.id };
-          if (typeof a.name === "string") row.name = a.name;
-          if (typeof a.workspace === "string") row.workspace = a.workspace;
-          if (a.model && typeof a.model === "object") {
-            const model: { name?: string; provider?: string } = {};
-            if (typeof a.model.name === "string") model.name = a.model.name;
-            if (typeof a.model.provider === "string") model.provider = a.model.provider;
-            if (model.name || model.provider) row.model = model;
-          }
-          agents.push(row);
-        }
-        settle({ ok: true, agents });
-      } catch (err) {
-        settle({ ok: true, error: `agents.list parse failed: ${(err as Error).message}` });
+        const v = msg.payload?.server?.version;
+        if (typeof v === "string" && v) serverVersion = v;
+        // We don't fetch agents.list over the wire: it requires `operator.read`
+        // which the gateway only grants to clients that present a paired device
+        // identity (see message-handler.ts:478 — self-declared scopes are
+        // cleared without device pairing). For local OpenClaw the agent list
+        // is sourced directly from disk by `probeOpenclawAgents`.
+        settle({ ok: true, version: serverVersion });
       }
     });
     ws.on("error", (err: Error) => {
       settle({ ok: false, error: err.message });
     });
     ws.on("close", () => {
-      // If the socket closes before `agents.list` resolved we still treat
-      // L2 as ok (open fired) and emit no agents.
-      settle({ ok: true });
+      // If the socket closes before we got our agents.list response, treat
+      // L2 as ok (the upgrade succeeded) and emit no agents.
+      settle({ ok: true, version: serverVersion });
     });
   });
 }
@@ -1097,11 +1125,69 @@ export async function probeOpenclawAgents(
     ...(profile.token ? { token: profile.token } : {}),
     ...(profile.tokenFile ? { tokenFile: profile.tokenFile } : {}),
   });
-  return probe({
+  const result = await probe({
     url: profile.url,
     token: prepared.resolvedToken,
     timeoutMs: opts.timeoutMs ?? 3000,
   });
+  // For loopback gateways the agent roster lives in `~/.openclaw/openclaw.json`
+  // and is the source of truth — listing it over the wire would require a
+  // paired device identity (operator.read scope). When the WS probe is the
+  // default (i.e. no test injection) we enrich the result from disk.
+  if (result.ok && !result.agents && !opts.probe && isLoopbackUrl(profile.url)) {
+    const local = readLocalOpenclawAgents();
+    if (local && local.length > 0) result.agents = local;
+  }
+  return result;
+}
+
+function isLoopbackUrl(raw: string): boolean {
+  try {
+    const u = new URL(raw);
+    return u.hostname === "127.0.0.1" || u.hostname === "::1" || u.hostname === "localhost";
+  } catch {
+    return false;
+  }
+}
+
+function readLocalOpenclawAgents(): Array<{
+  id: string;
+  name?: string;
+  workspace?: string;
+  model?: { name?: string; provider?: string };
+}> | null {
+  try {
+    const file = path.join(homedir(), ".openclaw", "openclaw.json");
+    if (!existsSync(file)) return null;
+    const cfg = JSON.parse(readFileSync(file, "utf8")) as any;
+    const list = Array.isArray(cfg?.agents?.list) ? cfg.agents.list : [];
+    const defaultId = typeof cfg?.agents?.defaults?.id === "string" ? cfg.agents.defaults.id : "default";
+    const seen = new Set<string>();
+    const out: Array<{ id: string; name?: string; workspace?: string; model?: { name?: string; provider?: string } }> = [];
+    const push = (raw: any, fallbackId?: string): void => {
+      const id = typeof raw?.id === "string" && raw.id ? raw.id : fallbackId;
+      if (!id || seen.has(id)) return;
+      seen.add(id);
+      const row: { id: string; name?: string; workspace?: string; model?: { name?: string; provider?: string } } = { id };
+      if (typeof raw?.name === "string") row.name = raw.name;
+      if (typeof raw?.workspace === "string") row.workspace = raw.workspace;
+      const m = raw?.model;
+      if (m && typeof m === "object") {
+        const model: { name?: string; provider?: string } = {};
+        if (typeof m.primary === "string") model.name = m.primary;
+        else if (typeof m.name === "string") model.name = m.name;
+        if (typeof m.provider === "string") model.provider = m.provider;
+        if (model.name || model.provider) row.model = model;
+      }
+      out.push(row);
+    };
+    // Default agent first so it surfaces at the top of the dropdown.
+    push({ id: defaultId, workspace: cfg?.agents?.defaults?.workspace, model: cfg?.agents?.defaults?.model }, defaultId);
+    for (const entry of list) push(entry);
+    return out;
+  } catch {
+    return null;
+  }
 }
 
 /**

package/src/user-auth.ts

@@ -188,6 +188,20 @@ export function isTokenNearExpiry(record: UserAuthRecord, windowMs = 60_000): bo
   return record.expiresAt - Date.now() <= windowMs;
 }
 
+/**
+ * Thrown when the Hub rejects a refresh token (401/403). Signals that the
+ * user must re-login — reconnect loops should stop instead of hammering
+ * the refresh endpoint forever with a known-bad token.
+ */
+export class AuthRefreshRejectedError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "AuthRefreshRejectedError";
+    this.status = status;
+  }
+}
+
 /**
  * Stateful helper that owns the in-memory copy of user-auth and knows how
  * to refresh it. Used by the control channel so reconnects always carry
@@ -245,13 +259,35 @@ export class UserAuthManager {
       expiresInMs: current.expiresAt - Date.now(),
     });
     this.refreshInflight = (async () => {
-      const tok = await refreshDaemonToken(current.hubUrl, current.refreshToken);
+      // Refresh tokens rotate server-side. If another local process (e.g. a
+      // second daemon racing on the same user-auth.json) refreshed in the
+      // meantime, the on-disk refreshToken now differs from our in-memory
+      // copy — using the in-memory one would 401 because the server already
+      // invalidated it. Re-read disk first and adopt any newer record.
+      let basis = current;
+      try {
+        const onDisk = loadUserAuth(this.file);
+        if (onDisk && onDisk.refreshToken !== current.refreshToken) {
+          daemonLog.info("user-auth refresh: adopting newer on-disk token", {
+            userId: onDisk.userId,
+            expiresAt: onDisk.expiresAt,
+          });
+          this.record = onDisk;
+          if (!isTokenNearExpiry(onDisk)) return onDisk;
+          basis = onDisk;
+        }
+      } catch (err) {
+        daemonLog.debug("user-auth refresh: disk reread failed (ignored)", {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+      const tok = await refreshDaemonToken(basis.hubUrl, basis.refreshToken);
       const next: UserAuthRecord = {
-        ...current,
+        ...basis,
         accessToken: tok.accessToken,
         refreshToken: tok.refreshToken,
         expiresAt: Date.now() + tok.expiresIn * 1000,
-        hubUrl: tok.hubUrl || current.hubUrl,
+        hubUrl: tok.hubUrl || basis.hubUrl,
       };
       saveUserAuth(next, this.file);
       this.record = next;
@@ -261,10 +297,23 @@ export class UserAuthManager {
       });
       return next;
     })().catch((err) => {
+      const status =
+        typeof (err as { status?: unknown }).status === "number"
+          ? ((err as { status: number }).status)
+          : null;
+      const message = err instanceof Error ? err.message : String(err);
       daemonLog.warn("user-auth refresh: failed", {
         userId: current.userId,
-        error: err instanceof Error ? err.message : String(err),
+        status,
+        error: message,
       });
+      if (status === 401 || status === 403) {
+        // Refresh token is permanently dead — write the expired flag so
+        // `status` surfaces it and re-throw a typed error so the control
+        // channel can stop reconnect loops instead of hammering the Hub.
+        writeAuthExpiredFlag();
+        throw new AuthRefreshRejectedError(status, message);
+      }
       throw err;
     }).finally(() => {
       this.refreshInflight = null;