@botcord/daemon 0.2.60 → 0.2.62

package/src/gateway/__tests__/dispatcher.test.ts

@@ -344,6 +344,32 @@ describe("Dispatcher", () => {
     expect(store.all().length).toBe(0);
   });
 
+  it("drops the stored session when a resumed turn errors without text even if the adapter returns the same id", async () => {
+    let callNo = 0;
+    const runtimeFactory: RuntimeFactory = () => {
+      callNo += 1;
+      if (callNo === 1) return new FakeRuntime({ reply: "ok", newSessionId: "sid-1" });
+      return new FakeRuntime({
+        reply: "",
+        newSessionId: "sid-1",
+        errorText: "acp error -32603: Internal error",
+      });
+    };
+    const { dispatcher, store, channel } = await scaffold({ runtimeFactory });
+
+    await dispatcher.handle(
+      makeEnvelope({ id: "msg_1", conversation: { id: "rm_x", kind: "direct" } }),
+    );
+    expect(store.all()[0].runtimeSessionId).toBe("sid-1");
+
+    await dispatcher.handle(
+      makeEnvelope({ id: "msg_2", conversation: { id: "rm_x", kind: "direct" } }),
+    );
+
+    expect(store.all().length).toBe(0);
+    expect(channel.sends[0].message.type).toBe("error");
+  });
+
   it("applies composeUserTurn before handing text to the runtime", async () => {
     const runtime = new FakeRuntime({ reply: "ok", newSessionId: "sid-1" });
     const { store, dir } = await makeStore();
@@ -492,6 +518,7 @@ describe("Dispatcher", () => {
     await dispatcher.handle(makeEnvelope({ id: "msg_error" }));
 
     expect(channel.sends.length).toBe(1);
+    expect(channel.sends[0].message.type).toBe("error");
     expect(channel.sends[0].message.text).toContain("Runtime error");
     expect(channel.sends[0].message.text).toContain("missing openclawAgent");
   });
@@ -1256,6 +1283,7 @@ describe("Dispatcher", () => {
 
     await dispatcher.handle(makeEnvelope({ id: "m1" }));
     expect(channel.sends.length).toBe(1);
+    expect(channel.sends[0].message.type).toBe("error");
     expect(channel.sends[0].message.text).toContain("Runtime error");
     expect(channel.sends[0].message.text).toContain("boom");
     expect(store.all().length).toBe(0);
@@ -1921,6 +1949,7 @@ describe("Dispatcher", () => {
       await p;
       expect(runtime.calls[0].signal.aborted).toBe(true);
       expect(channel.sends.length).toBe(1);
+      expect(channel.sends[0].message.type).toBe("error");
       expect(channel.sends[0].message.text).toMatch(/Runtime timeout/);
       expect(channel.sends[0].message.conversationId).toBe("rm_g_other");
       expect(channel.sends[0].message.replyTo).toBe("m_to");
@@ -1941,6 +1970,7 @@ describe("Dispatcher", () => {
       }),
     );
     expect(channel.sends.length).toBe(1);
+    expect(channel.sends[0].message.type).toBe("error");
     expect(channel.sends[0].message.text).toContain("Runtime error: boom");
     expect(channel.sends[0].message.conversationId).toBe("rm_g_other");
     expect(channel.sends[0].message.replyTo).toBe("m_err");

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

@@ -183,6 +183,33 @@ describe("HermesAgentAdapter", () => {
     expect(res.error).toBeUndefined();
   });
 
+  it("drains late assistant text after a prompt RPC error before closing stdin", async () => {
+    const script = makeAcpServer(
+      "late-after-error.js",
+      `
+        if (msg.method === "initialize") {
+          reply(msg, { protocolVersion: 1 });
+        } else if (msg.method === "session/new") {
+          reply(msg, { sessionId: "sess-late-error" });
+        } else if (msg.method === "session/prompt") {
+          err(msg, -32603, "Internal error");
+          setTimeout(() => {
+            notify("session/update", {
+              sessionId: msg.params.sessionId,
+              update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "late but valid" } }
+            });
+            process.exit(0);
+          }, 25);
+        }
+      `,
+    );
+
+    const res = await runAdapter(script);
+    expect(res.newSessionId).toBe("sess-late-error");
+    expect(res.text).toBe("late but valid");
+    expect(res.error).toContain("acp error -32603");
+  });
+
   it("owner trust → request_permission selects an allow_* option", async () => {
     const script = makeAcpServer(
       "perm-allow.js",

package/src/gateway/channels/botcord.ts

@@ -55,6 +55,12 @@ export interface BotCordChannelClient {
     text: string,
     options?: { replyTo?: string; topic?: string },
   ): Promise<{ hub_msg_id?: string; message_id?: string } & Record<string, unknown>>;
+  sendTypedMessage?(
+    to: string,
+    type: "result" | "error",
+    text: string,
+    options?: { replyTo?: string; topic?: string },
+  ): Promise<{ hub_msg_id?: string; message_id?: string } & Record<string, unknown>>;
   getHubUrl(): string;
   onTokenRefresh?: (token: string, expiresAt: number) => void;
 }
@@ -804,7 +810,10 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
       const options: { replyTo?: string; topic?: string } = {};
       if (message.replyTo) options.replyTo = message.replyTo;
       if (message.threadId) options.topic = message.threadId;
-      const resp = await client.sendMessage(message.conversationId, message.text, options);
+      const resp =
+        message.type === "error" && client.sendTypedMessage
+          ? await client.sendTypedMessage(message.conversationId, "error", message.text, options)
+          : await client.sendMessage(message.conversationId, message.text, options);
       const providerMessageId =
         (resp && typeof resp.hub_msg_id === "string" && resp.hub_msg_id) ||
         (resp && typeof (resp as { message_id?: unknown }).message_id === "string"

package/src/gateway/dispatcher.ts

@@ -1200,6 +1200,14 @@ export class Dispatcher {
           systemContext,
           onBlock,
           onStatus,
+          context: {
+            turnId,
+            messageId: msg.id,
+            roomId: msg.conversation.id,
+            topicId: msg.conversation.threadId ?? null,
+            channel: msg.channel,
+            conversationKind: msg.conversation.kind,
+          },
           gateway: route.gateway,
           ...(route.hermesProfile ? { hermesProfile: route.hermesProfile } : {}),
         });
@@ -1264,6 +1272,7 @@ export class Dispatcher {
             accountId: msg.accountId,
             conversationId: msg.conversation.id,
             threadId: msg.conversation.threadId ?? null,
+            type: "error",
             text: `⚠️ Runtime timeout after ${Math.round(this.turnTimeoutMs / 60000)} minute(s); aborted`,
             replyTo: msg.id,
             traceId: msg.trace?.id ?? null,
@@ -1309,6 +1318,7 @@ export class Dispatcher {
             accountId: msg.accountId,
             conversationId: msg.conversation.id,
             threadId: msg.conversation.threadId ?? null,
+            type: "error",
             text: `⚠️ Runtime error: ${truncate(errMsg, 500)}`,
             replyTo: msg.id,
             traceId: msg.trace?.id ?? null,
@@ -1327,16 +1337,34 @@ export class Dispatcher {
 
       if (!result) return;
 
+      const replyText = (result.text || "").trim();
+      const finalTextField = truncateTextField(result.text || "");
+
       // Persist session before reply so next turn sees the new id even if send fails.
       //
       // Adapter contract:
-      //   result.newSessionId truthy  → upsert the entry
-      //   result.newSessionId empty + had-inbound-sessionId + result.error
-      //                               → the prior session is dead (e.g. Claude Code
-      //                                 "--resume <missing-uuid>"); delete the entry so
+      //   had-inbound-sessionId + result.error + no reply text
+      //                               → the prior session is suspect/dead; delete it so
       //                                 we don't keep resuming a stale id every turn
+      //                                 even when the adapter echoes that id back
+      //   result.newSessionId truthy  → upsert the entry
       //   otherwise                   → no-op (e.g. codex intentionally never persists)
-      if (result.newSessionId) {
+      if (sessionId && result.error && !replyText) {
+        try {
+          await this.sessionStore.delete(key);
+          this.log.info("dispatcher: dropped stale runtime session", {
+            key,
+            prevRuntimeSessionId: sessionId,
+            nextRuntimeSessionId: result.newSessionId || null,
+            error: result.error,
+          });
+        } catch (err) {
+          this.log.warn("dispatcher: session-store.delete failed", {
+            key,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      } else if (result.newSessionId) {
         const session: GatewaySessionEntry = {
           key,
           runtime: route.runtime,
@@ -1379,9 +1407,6 @@ export class Dispatcher {
         }
       }
 
-      const replyText = (result.text || "").trim();
-      const finalTextField = truncateTextField(result.text || "");
-
       if (!replyText) {
         if (result.error) {
           this.log.warn("dispatcher: runtime returned error without reply text", {
@@ -1398,6 +1423,7 @@ export class Dispatcher {
               accountId: msg.accountId,
               conversationId: msg.conversation.id,
               threadId: msg.conversation.threadId ?? null,
+              type: "error",
               text: `⚠️ Runtime error: ${truncate(result.error, 500)}`,
               replyTo: msg.id,
               traceId: msg.trace?.id ?? null,

package/src/gateway/runtimes/acp-stream.ts

@@ -1,4 +1,5 @@
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { createAcpTraceLogger, type AcpTraceLogger } from "../../acp-logs.js";
 import { consoleLogger } from "../log.js";
 import type {
   RuntimeAdapter,
@@ -33,9 +34,17 @@ const ASSISTANT_TEXT_CAP = 1 * 1024 * 1024;
 const KILL_GRACE_MS = 5_000;
 /** Deadline for the initial `initialize` handshake. */
 const INITIALIZE_TIMEOUT_MS = 30_000;
+/** Short drain window for late `session/update` chunks after a prompt RPC error. */
+const PROMPT_ERROR_DRAIN_MS = 750;
 /** ACP protocol version this client targets. */
 export const ACP_PROTOCOL_VERSION = 1;
 
+function stringField(obj: unknown, key: string): string | undefined {
+  if (!obj || typeof obj !== "object") return undefined;
+  const value = (obj as Record<string, unknown>)[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
 export interface AcpInitializeResult {
   protocolVersion?: number;
   agentInfo?: { name?: string; version?: string };
@@ -119,6 +128,7 @@ class AcpConnection {
       ): Promise<unknown> | unknown;
     },
     private readonly logId: string,
+    private readonly trace: AcpTraceLogger | null = null,
   ) {
     child.stdout.setEncoding("utf8");
     child.stdout.on("data", (chunk: string) => this.onStdout(chunk));
@@ -142,9 +152,11 @@ class AcpConnection {
 
   private dispatchLine(line: string): void {
     let msg: any;
+
     try {
       msg = JSON.parse(line);
     } catch {
+      this.trace?.write({ stream: "stdout_non_json", chunk: line });
       log.warn(`${this.logId} non-json acp line`, { line: line.slice(0, 200) });
       return;
     }
@@ -155,11 +167,26 @@ class AcpConnection {
       if (!pending) return;
       this.pending.delete(msg.id);
       if (msg.error) {
+        this.trace?.write({
+          stream: "rpc_in",
+          direction: "in",
+          id: msg.id,
+          status: "error",
+          code: typeof msg.error.code === "number" ? msg.error.code : undefined,
+          error: msg.error.message ?? "(no message)",
+        });
         const err = new Error(
           `acp error ${msg.error.code ?? "?"}: ${msg.error.message ?? "(no message)"}`,
         );
         pending.reject(err);
       } else {
+        this.trace?.write({
+          stream: "rpc_in",
+          direction: "in",
+          id: msg.id,
+          status: "response",
+          result: msg.result ?? null,
+        });
         pending.resolve(msg.result ?? null);
       }
       return;
@@ -167,8 +194,23 @@ class AcpConnection {
     if (typeof msg.method === "string") {
       // Server→client request (has `id`) or notification (no `id`)
       if (msg.id !== undefined) {
+        this.trace?.write({
+          stream: "rpc_in",
+          direction: "in",
+          id: msg.id,
+          method: msg.method,
+          status: "request",
+          params: msg.params,
+        });
         void this.handleServerRequest(msg.id, msg.method, msg.params);
       } else {
+        this.trace?.write({
+          stream: "rpc_in",
+          direction: "in",
+          method: msg.method,
+          status: "notification",
+          params: msg.params,
+        });
         try {
           this.handlers.onNotification(msg.method, msg.params);
         } catch (err) {
@@ -199,6 +241,15 @@ class AcpConnection {
     const reply = error
       ? { jsonrpc: "2.0", id, error }
       : { jsonrpc: "2.0", id, result: result ?? null };
+    this.trace?.write({
+      stream: "rpc_out",
+      direction: "out",
+      id,
+      status: error ? "error" : "response",
+      code: error?.code,
+      error: error?.message,
+      result: error ? undefined : result ?? null,
+    });
     this.writeMessage(reply);
   }
 
@@ -221,11 +272,26 @@ class AcpConnection {
         resolve: (v) => resolve(v as T),
         reject,
       });
+      this.trace?.write({
+        stream: "rpc_out",
+        direction: "out",
+        id,
+        method,
+        status: "request",
+        params,
+      });
       this.writeMessage({ jsonrpc: "2.0", id, method, params });
     });
   }
 
   notify(method: string, params: unknown): void {
+    this.trace?.write({
+      stream: "rpc_out",
+      direction: "out",
+      method,
+      status: "notification",
+      params,
+    });
     this.writeMessage({ jsonrpc: "2.0", method, params });
   }
 
@@ -323,6 +389,20 @@ export abstract class AcpRuntimeAdapter implements RuntimeAdapter {
       env: this.spawnEnv(opts),
       stdio: ["pipe", "pipe", "pipe"],
     }) as ChildProcessWithoutNullStreams;
+    const trace = createAcpTraceLogger({
+      runtime: this.id,
+      accountId: opts.accountId,
+      turnId: stringField(opts.context, "turnId"),
+      roomId: stringField(opts.context, "roomId"),
+      topicId: stringField(opts.context, "topicId") ?? null,
+      hermesProfile: opts.hermesProfile,
+      sessionId: opts.sessionId,
+    });
+    trace?.write({
+      stream: "child_start",
+      pid: child.pid,
+      params: { command: binary, args, cwd: opts.cwd },
+    });
 
     let killTimer: ReturnType<typeof setTimeout> | null = null;
     const onAbort = () => {
@@ -351,6 +431,7 @@ export abstract class AcpRuntimeAdapter implements RuntimeAdapter {
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk: string) => {
       stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_CAP);
+      trace?.write({ stream: "stderr", pid: child.pid, chunk });
     });
 
     const state: AcpRunState = {
@@ -414,13 +495,25 @@ export abstract class AcpRuntimeAdapter implements RuntimeAdapter {
         },
       },
       this.id,
+      trace,
     );
 
     const childExit = new Promise<number>((resolve) => {
-      child.on("close", (code) => resolve(code ?? 0));
+      child.on("close", (code, signal) => {
+        trace?.write({ stream: "child_exit", pid: child.pid, code, signal });
+        resolve(code ?? 0);
+      });
+      child.on("error", (err) => {
+        trace?.write({
+          stream: "child_error",
+          pid: child.pid,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      });
     });
 
     let newSessionId = opts.sessionId ?? "";
+    let promptStarted = false;
 
     try {
       // 1) initialize
@@ -471,6 +564,7 @@ export abstract class AcpRuntimeAdapter implements RuntimeAdapter {
       newSessionId = sessionId;
 
       // 3) session/prompt
+      promptStarted = true;
       const promptResult = (await conn.request<unknown>("session/prompt", {
         sessionId,
         prompt: [{ type: "text", text: opts.text }],
@@ -508,6 +602,9 @@ export abstract class AcpRuntimeAdapter implements RuntimeAdapter {
       const tail = stderrTail.slice(-STDERR_ERROR_SNIPPET).trim();
       state.errorText =
         state.errorText ?? (tail ? `${baseMsg}; stderr: ${tail}` : baseMsg);
+      if (promptStarted && !opts.signal.aborted) {
+        await sleepUnlessAborted(PROMPT_ERROR_DRAIN_MS, opts.signal);
+      }
       try {
         child.stdin.end();
       } catch {
@@ -563,3 +660,17 @@ export abstract class AcpRuntimeAdapter implements RuntimeAdapter {
     });
   }
 }
+
+function sleepUnlessAborted(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const t = setTimeout(done, ms);
+    if (typeof t.unref === "function") t.unref();
+    function done(): void {
+      signal.removeEventListener("abort", done);
+      clearTimeout(t);
+      resolve();
+    }
+    signal.addEventListener("abort", done, { once: true });
+  });
+}

package/src/gateway/runtimes/openclaw-acp.ts

@@ -1,4 +1,5 @@
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { createAcpTraceLogger, type AcpTraceLogger } from "../../acp-logs.js";
 import {
   readCommandVersion,
   resolveCommandOnPath,
@@ -51,6 +52,7 @@ interface AcpProcessHandle {
    */
   spawnedUrl: string;
   spawnedToken: string | undefined;
+  trace: AcpTraceLogger | null;
 }
 
 interface PendingCall {
@@ -358,6 +360,12 @@ export class OpenclawAcpAdapter implements RuntimeAdapter {
 
       if (!finalText) {
         const stopReason = pickStopReason(promptResult);
+        if (!stopReason || stopReason === "end_turn") {
+          return {
+            text: "",
+            newSessionId: acpSessionId,
+          };
+        }
         const warningTail = handle.nonJsonStdoutTail.slice(-8).join("\n").trim();
         const detail = warningTail ? `; stdout: ${truncateDetail(warningTail, 1000)}` : "";
         const reason = stopReason ? `prompt stopped: ${stopReason}` : "empty assistant response";
@@ -444,11 +452,23 @@ export class OpenclawAcpAdapter implements RuntimeAdapter {
     const command = resolveOpenclawCommand() ?? "openclaw";
     const args = ["acp", "--url", gateway.url];
     if (gateway.token) args.push("--token", gateway.token);
+    const accountId = key.split("::", 1)[0];
+    const trace = createAcpTraceLogger({
+      runtime: acpRuntimeLogName(gateway),
+      accountId,
+      gatewayName: gateway.name,
+      gatewayUrl: gateway.url,
+    });
 
     const child = this.spawnFn(command, args, {
       stdio: ["pipe", "pipe", "pipe"],
       env: { ...process.env },
     }) as ChildProcessWithoutNullStreams;
+    trace?.write({
+      stream: "child_start",
+      pid: child.pid,
+      params: { command, args, gateway: gateway.name },
+    });
 
     const handle: AcpProcessHandle = {
       child,
@@ -462,19 +482,27 @@ export class OpenclawAcpAdapter implements RuntimeAdapter {
       closed: false,
       spawnedUrl: gateway.url,
       spawnedToken: gateway.token,
+      trace,
     };
 
     child.stdout.setEncoding("utf8");
     child.stdout.on("data", (chunk: string) => onStdoutChunk(handle, chunk));
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk: string) => {
+      trace?.write({ stream: "stderr", pid: child.pid, chunk });
       log.debug("openclaw-acp.stderr", { key, chunk: chunk.slice(0, 500) });
     });
     child.on("exit", (code, signal) => {
+      trace?.write({ stream: "child_exit", pid: child.pid, code, signal });
       shutdownHandle(handle, `exit code=${code ?? "null"} signal=${signal ?? "null"}`);
       ACP_POOL.delete(key);
     });
     child.on("error", (err) => {
+      trace?.write({
+        stream: "child_error",
+        pid: child.pid,
+        error: err instanceof Error ? err.message : String(err),
+      });
       log.warn("openclaw-acp.child-error", {
         key,
         error: err instanceof Error ? err.message : String(err),
@@ -532,6 +560,16 @@ export class OpenclawAcpAdapter implements RuntimeAdapter {
 // JSON-RPC stdio plumbing
 // ---------------------------------------------------------------------------
 
+function acpRuntimeLogName(gateway: NonNullable<RuntimeRunOptions["gateway"]>): string {
+  if (gateway.name.toLowerCase().includes("qclaw")) return "qclaw-acp";
+  try {
+    if (new URL(gateway.url).port === "28789") return "qclaw-acp";
+  } catch {
+    // Fall back to OpenClaw.
+  }
+  return "openclaw-acp";
+}
+
 function onStdoutChunk(handle: AcpProcessHandle, chunk: string): void {
   handle.buffer += chunk;
   let idx: number;
@@ -551,6 +589,7 @@ function onStdoutChunk(handle: AcpProcessHandle, chunk: string): void {
         error: err instanceof Error ? err.message : String(err),
         line: line.slice(0, 200),
       });
+      handle.trace?.write({ stream: "stdout_non_json", chunk: line });
       continue;
     }
     routeMessage(handle, msg);
@@ -565,14 +604,36 @@ function routeMessage(handle: AcpProcessHandle, msg: any): void {
     handle.pending.delete(id);
     if (msg.error) {
       const message = formatRpcError(msg.error);
+      handle.trace?.write({
+        stream: "rpc_in",
+        direction: "in",
+        id,
+        status: "error",
+        code: typeof msg.error.code === "number" ? msg.error.code : undefined,
+        error: message,
+      });
       pending.reject(new Error(message));
     } else {
+      handle.trace?.write({
+        stream: "rpc_in",
+        direction: "in",
+        id,
+        status: "response",
+        result: msg.result ?? null,
+      });
       pending.resolve(msg.result);
     }
     return;
   }
   // Notification.
   if (msg?.method && msg?.params) {
+    handle.trace?.write({
+      stream: "rpc_in",
+      direction: "in",
+      method: msg.method,
+      status: "notification",
+      params: msg.params,
+    });
     const sid = msg.params?.sessionId;
     if (typeof sid === "string") {
       const sub = handle.subscribers.get(sid);
@@ -598,6 +659,14 @@ function sendRequest(
   return new Promise((resolve, reject) => {
     const id = handle.nextId++;
     handle.pending.set(id, { resolve, reject, method });
+    handle.trace?.write({
+      stream: "rpc_out",
+      direction: "out",
+      id,
+      method,
+      status: "request",
+      params,
+    });
     const frame = JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n";
     try {
       handle.child.stdin.write(frame);
@@ -614,6 +683,13 @@ function sendNotification(
   params: any,
 ): void {
   if (handle.closed) return;
+  handle.trace?.write({
+    stream: "rpc_out",
+    direction: "out",
+    method,
+    status: "notification",
+    params,
+  });
   const frame = JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n";
   try {
     handle.child.stdin.write(frame);

package/src/gateway/types.ts

@@ -187,6 +187,7 @@ export interface GatewayOutboundMessage {
   accountId: string;
   conversationId: string;
   threadId?: string | null;
+  type?: "message" | "error";
   text: string;
   attachments?: GatewayOutboundAttachment[];
   replyTo?: string | null;

package/src/index.ts

@@ -307,6 +307,34 @@ function loadOrInitConfig(args: ParsedArgs): DaemonConfig {
   }
 }
 
+async function refreshDiscoveredOpenclawGateways(
+  cfg: DaemonConfig,
+  source: string,
+): Promise<DaemonConfig> {
+  if (!openclawDiscoveryConfigEnabled(cfg)) return cfg;
+  try {
+    const found = await discoverLocalOpenclawGateways({
+      searchPaths: cfg.openclawDiscovery?.searchPaths,
+      defaultPorts: cfg.openclawDiscovery?.defaultPorts,
+      timeoutMs: 500,
+    });
+    const merged = mergeOpenclawGateways(cfg, found);
+    if (!merged.changed) return cfg;
+    saveConfig(merged.cfg);
+    log.info("openclaw discovery: gateways merged", {
+      source,
+      added: merged.added.map((g) => ({ name: g.name, url: g.url })),
+    });
+    return merged.cfg;
+  } catch (err) {
+    log.warn("openclaw discovery failed; continuing", {
+      source,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return cfg;
+  }
+}
+
 /**
  * Read the current user-auth record without throwing on parse / permission
  * errors — those are returned as `null` so the caller treats them like a
@@ -566,27 +594,7 @@ async function ensureUserAuthForStart(args: ParsedArgs): Promise<UserAuthRecord
 
 async function cmdStart(args: ParsedArgs): Promise<void> {
   let cfg = loadOrInitConfig(args);
-  if (openclawDiscoveryConfigEnabled(cfg)) {
-    try {
-      const found = await discoverLocalOpenclawGateways({
-        searchPaths: cfg.openclawDiscovery?.searchPaths,
-        defaultPorts: cfg.openclawDiscovery?.defaultPorts,
-        timeoutMs: 500,
-      });
-      const merged = mergeOpenclawGateways(cfg, found);
-      if (merged.changed) {
-        cfg = merged.cfg;
-        saveConfig(cfg);
-        log.info("openclaw discovery: gateways merged", {
-          added: merged.added.map((g) => ({ name: g.name, url: g.url })),
-        });
-      }
-    } catch (err) {
-      log.warn("openclaw discovery failed; continuing", {
-        error: err instanceof Error ? err.message : String(err),
-      });
-    }
-  }
+  cfg = await refreshDiscoveredOpenclawGateways(cfg, "start");
   // Foreground is now the default. --background (alias -d) detaches.
   // --foreground is still accepted (no-op) for backwards compatibility and
   // is also what the detached child re-execs itself with.
@@ -1373,8 +1381,8 @@ async function cmdDoctor(args: ParsedArgs): Promise<void> {
   let cfgForEndpoints: import("./config.js").DaemonConfig | null = null;
   try {
     const cfg = loadConfig();
-    cfgForEndpoints = cfg;
-    channels = channelsFromDaemonConfig(cfg);
+    cfgForEndpoints = await refreshDiscoveredOpenclawGateways(cfg, "doctor");
+    channels = channelsFromDaemonConfig(cfgForEndpoints);
   } catch {
     channels = [];
   }