@botcord/daemon 0.2.17 → 0.2.18

package/dist/gateway/channels/botcord.js

@@ -7,6 +7,7 @@ const MAX_AUTH_FAILURES = 5;
 const SEEN_MESSAGES_CAP = 500;
 const OWNER_CHAT_PREFIX = "rm_oc_";
 const DM_ROOM_PREFIX = "rm_dm_";
+const INBOX_POLL_LIMIT = 50;
 /** Default factory: wrap `loadStoredCredentials` + `new BotCordClient`. */
 function defaultClientFactory(input) {
     const credFile = input.credentialsPath ?? defaultCredentialsFile(input.agentId);
@@ -199,20 +200,41 @@ export function createBotCordChannel(options) {
         }
         return clientRef;
     }
-    async function drainInbox(client, emit, log) {
-        const resp = await client.pollInbox({ limit: 50, ack: false });
+    async function drainInbox(client, emit, log, trigger) {
+        const startedAt = Date.now();
+        const resp = await client.pollInbox({ limit: INBOX_POLL_LIMIT, ack: false });
         const msgs = resp.messages ?? [];
-        log.info("botcord inbox drained", { count: msgs.length });
-        if (msgs.length === 0)
+        let duplicateCount = 0;
+        let skippedCount = 0;
+        let emittedGroups = 0;
+        const logDrain = () => {
+            log.info("botcord inbox drained", {
+                trigger,
+                count: msgs.length,
+                responseCount: resp.count,
+                hasMore: resp.has_more,
+                limit: INBOX_POLL_LIMIT,
+                ack: false,
+                eligibleCount: eligible.length,
+                duplicateCount,
+                skippedCount,
+                emittedGroups,
+                durationMs: Date.now() - startedAt,
+            });
+        };
+        const eligible = [];
+        if (msgs.length === 0) {
+            logDrain();
             return;
+        }
         // First pass: ack duplicates/skipped messages so Hub stops requeueing,
         // and collect eligible messages preserving poll order. Grouping by
         // `(room_id, topic)` mirrors plugin's `handleInboxMessageBatch` — the
         // same conversation thread folds into one turn so the agent sees all
         // new messages at once instead of running N turns back-to-back.
-        const eligible = [];
         for (const msg of msgs) {
             if (!rememberSeen(msg.hub_msg_id)) {
+                duplicateCount += 1;
                 try {
                     await client.ackMessages([msg.hub_msg_id]);
                 }
@@ -226,6 +248,7 @@ export function createBotCordChannel(options) {
                 accountId: options.accountId,
             });
             if (!normalized) {
+                skippedCount += 1;
                 try {
                     await client.ackMessages([msg.hub_msg_id]);
                 }
@@ -236,8 +259,10 @@ export function createBotCordChannel(options) {
             }
             eligible.push(msg);
         }
-        if (eligible.length === 0)
+        if (eligible.length === 0) {
+            logDrain();
             return;
+        }
         // Group by `(room_id, topic)`. Insertion order is the poll order, so
         // iterating the map yields groups with the same external chronology.
         const groups = new Map();
@@ -278,6 +303,7 @@ export function createBotCordChannel(options) {
             };
             try {
                 await emit(envelope);
+                emittedGroups += 1;
             }
             catch (err) {
                 log.error("botcord emit threw", {
@@ -286,6 +312,7 @@ export function createBotCordChannel(options) {
                 });
             }
         }
+        logDrain();
     }
     function startWsLoop(client, ctx) {
         const { abortSignal, log, emit, setStatus } = ctx;
@@ -318,16 +345,19 @@ export function createBotCordChannel(options) {
             statusSnapshot = { ...statusSnapshot, ...patch };
             setStatus(patch);
         }
-        async function fireInbox() {
+        async function fireInbox(trigger) {
             if (processing) {
                 pendingUpdate = true;
+                log.debug("botcord inbox drain queued while previous drain is running", { trigger });
                 return;
             }
             processing = true;
             try {
+                let currentTrigger = trigger;
                 do {
                     pendingUpdate = false;
-                    await drainInbox(client, emit, log);
+                    await drainInbox(client, emit, log, currentTrigger);
+                    currentTrigger = "coalesced_inbox_update";
                 } while (pendingUpdate && running);
             }
             catch (err) {
@@ -413,7 +443,7 @@ export function createBotCordChannel(options) {
                         lastError: null,
                     });
                     log.info("botcord ws authenticated", { agentId: msg.agent_id });
-                    void fireInbox();
+                    void fireInbox("ws_auth_ok");
                     keepaliveTimer = setInterval(() => {
                         if (ws && ws.readyState === WebSocket.OPEN) {
                             try {
@@ -427,7 +457,7 @@ export function createBotCordChannel(options) {
                 }
                 else if (msg.type === "inbox_update") {
                     log.info("botcord ws inbox_update received");
-                    void fireInbox();
+                    void fireInbox("ws_inbox_update");
                 }
                 else if (msg.type === "heartbeat" || msg.type === "pong") {
                     // no-op

package/dist/index.js

@@ -15,6 +15,7 @@ import { renderStatus } from "./status-render.js";
 import { appendNextParam } from "./url-utils.js";
 import { channelsFromDaemonConfig, defaultHttpFetcher, renderDoctor, runDoctor, } from "./doctor.js";
 import { clearWorkingMemory, readWorkingMemory, resolveMemoryDir, updateWorkingMemory, DEFAULT_SECTION, } from "./working-memory.js";
+import { resolveStartAuthAction } from "./start-auth.js";
 import { discoverLocalOpenclawGateways, mergeOpenclawGateways, openclawDiscoveryConfigEnabled, } from "./openclaw-discovery.js";
 const ADAPTER_LIST = listAdapterIds().join("|");
 const DEFAULT_HUB = "https://api.botcord.chat";
@@ -329,9 +330,10 @@ async function runDeviceCodeFlow(opts) {
  * plane (legacy P0 behavior — caller may still log a warning).
  *
  * Decision tree (plan §4.4 + §6.4):
- * 1. Have existing creds, no `--relogin`, no `--install-token` → return existing record.
- * 2. `--install-token` (overrides existing creds — they may be stale or
- *    belong to a different account) → redeem the one-time dashboard ticket.
+ * 1. Have existing creds and no `--relogin` → return existing record, even
+ *    when a dashboard `--install-token` is present. The token is one-time and
+ *    the generated install command should be safe to re-run after first login.
+ * 2. No existing creds + `--install-token` → redeem the one-time dashboard ticket.
  * 3. `--relogin` → device-code login.
  * 4. No creds + TTY → device-code login.
  * 5. No creds + no TTY → exit 1 with the §6.4 hint.
@@ -342,7 +344,8 @@ async function ensureUserAuthForStart(args) {
     const installToken = typeof args.flags["install-token"] === "string" ? args.flags["install-token"] : undefined;
     const relogin = args.flags.relogin === true;
     const existing = safeLoadUserAuth();
-    if (!relogin && !installToken && existing) {
+    const authAction = resolveStartAuthAction({ existing, relogin, installToken });
+    if (authAction === "reuse-existing" && existing) {
         // A previously-set auth-expired flag is stale by definition once the
         // operator runs `start` again — if creds genuinely don't work, the
         // control channel will re-write the flag on the next 4401/4403.
@@ -356,12 +359,15 @@ async function ensureUserAuthForStart(args) {
         if (labelFlag && existing.label !== labelFlag) {
             console.error(`note: --label "${labelFlag}" ignored (already logged in as "${existing.label ?? "<unset>"}"); pass --relogin to change it`);
         }
+        if (installToken) {
+            console.error("note: --install-token ignored because daemon is already logged in; pass --relogin to re-bind");
+        }
         return existing;
     }
     // Need a fresh login. Resolve hubUrl: explicit --hub > existing record > DEFAULT_HUB.
     const hubUrl = hubFlag ?? existing?.hubUrl ?? DEFAULT_HUB;
     const label = labelFlag ?? defaultLoginLabel();
-    if (installToken) {
+    if (authAction === "install-token" && installToken) {
         const tok = await redeemInstallToken({ hubUrl, installToken, label });
         const record = userAuthFromTokenResponse(tok, { label });
         saveUserAuth(record);

package/dist/provision.js

@@ -1137,26 +1137,51 @@ export async function collectRuntimeSnapshotAsync(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 3000;
     const capped = gateways.slice(0, RUNTIME_ENDPOINTS_CAP);
     const endpoints = await Promise.all(capped.map(async (g) => {
+        if (localOpenclawAcpDisabled(g.url)) {
+            return {
+                name: g.name,
+                url: g.url,
+                reachable: false,
+                status: "acp_disabled",
+                error: "OpenClaw ACP runtime disabled",
+                diagnostics: [
+                    {
+                        code: "acp_disabled",
+                        message: "OpenClaw config explicitly disables the ACP runtime",
+                    },
+                ],
+            };
+        }
         try {
             const res = await probeOpenclawAgents(g, {
                 probe: opts.wsProbe,
                 timeoutMs,
             });
-            const entry = { name: g.name, url: g.url, reachable: res.ok };
+            const entry = {
+                name: g.name,
+                url: g.url,
+                reachable: res.ok,
+                status: res.ok ? "reachable" : "unreachable",
+            };
             if (res.version)
                 entry.version = res.version;
-            if (res.error)
+            if (res.error) {
                 entry.error = res.error;
+                entry.diagnostics = [{ code: "gateway_unreachable", message: res.error }];
+            }
             if (res.agents)
                 entry.agents = res.agents;
             return entry;
         }
         catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
             return {
                 name: g.name,
                 url: g.url,
                 reachable: false,
-                error: err.message,
+                status: "unreachable",
+                error: message,
+                diagnostics: [{ code: "probe_failed", message }],
             };
         }
     }));

package/dist/start-auth.d.ts

@@ -0,0 +1,7 @@
+import type { UserAuthRecord } from "./user-auth.js";
+export type StartAuthAction = "reuse-existing" | "install-token" | "device-code";
+export declare function resolveStartAuthAction(opts: {
+    existing: UserAuthRecord | null;
+    relogin: boolean;
+    installToken?: string;
+}): StartAuthAction;

package/dist/start-auth.js

@@ -0,0 +1,7 @@
+export function resolveStartAuthAction(opts) {
+    if (opts.existing && !opts.relogin)
+        return "reuse-existing";
+    if (opts.installToken)
+        return "install-token";
+    return "device-code";
+}

package/package.json

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

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

@@ -1,4 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 
 // Hoisted mock for `../adapters/runtimes.js` so each suite can stub
 // `detectRuntimes()` independently — we want coverage of the "empty
@@ -24,7 +27,12 @@ vi.mock("../adapters/runtimes.js", async () => {
   };
 });
 
-const { collectRuntimeSnapshot, clearRuntimeProbeCache, createProvisioner } = await import("../provision.js");
+const {
+  collectRuntimeSnapshot,
+  collectRuntimeSnapshotAsync,
+  clearRuntimeProbeCache,
+  createProvisioner,
+} = await import("../provision.js");
 
 beforeEach(() => {
   // The L1 probe is memoized for 30s in production; tests rotate the
@@ -94,6 +102,100 @@ describe("collectRuntimeSnapshot", () => {
   });
 });
 
+describe("collectRuntimeSnapshotAsync", () => {
+  it("adds OpenClaw endpoint status and diagnostics", async () => {
+    setRuntimes([
+      {
+        id: "openclaw-acp",
+        displayName: "OpenClaw",
+        binary: "openclaw",
+        supportsRun: true,
+        result: { available: true, version: "0.1.0" },
+      },
+    ]);
+
+    const snap = await collectRuntimeSnapshotAsync({
+      cfg: {
+        openclawGateways: [
+          { name: "ok", url: "ws://127.0.0.1:18789" },
+          { name: "bad", url: "ws://127.0.0.1:16200" },
+        ],
+      },
+      wsProbe: async ({ url }) =>
+        url.includes("18789")
+          ? { ok: true, version: "gw-1", agents: [{ id: "main" }] }
+          : { ok: false, error: "connect rejected" },
+    });
+
+    const runtime = snap.runtimes.find((r) => r.id === "openclaw-acp");
+    expect(runtime?.endpoints).toEqual([
+      expect.objectContaining({
+        name: "ok",
+        reachable: true,
+        status: "reachable",
+        version: "gw-1",
+        agents: [{ id: "main" }],
+      }),
+      expect.objectContaining({
+        name: "bad",
+        reachable: false,
+        status: "unreachable",
+        error: "connect rejected",
+        diagnostics: [{ code: "gateway_unreachable", message: "connect rejected" }],
+      }),
+    ]);
+  });
+
+  it("reports acp_disabled without probing the gateway", async () => {
+    const tmp = mkdtempSync(path.join(tmpdir(), "daemon-runtime-openclaw-"));
+    const prevHome = process.env.HOME;
+    process.env.HOME = tmp;
+    try {
+      mkdirSync(path.join(tmp, ".openclaw"), { recursive: true });
+      writeFileSync(
+        path.join(tmp, ".openclaw", "openclaw.json"),
+        JSON.stringify({ acp: { enabled: false } }),
+      );
+      setRuntimes([
+        {
+          id: "openclaw-acp",
+          displayName: "OpenClaw",
+          binary: "openclaw",
+          supportsRun: true,
+          result: { available: true },
+        },
+      ]);
+      const wsProbe = vi.fn(async () => ({ ok: true }));
+
+      const snap = await collectRuntimeSnapshotAsync({
+        cfg: { openclawGateways: [{ name: "local", url: "ws://127.0.0.1:18789" }] },
+        wsProbe,
+      });
+
+      expect(wsProbe).not.toHaveBeenCalled();
+      const runtime = snap.runtimes.find((r) => r.id === "openclaw-acp");
+      expect(runtime?.endpoints).toEqual([
+        expect.objectContaining({
+          name: "local",
+          reachable: false,
+          status: "acp_disabled",
+          error: "OpenClaw ACP runtime disabled",
+          diagnostics: [
+            {
+              code: "acp_disabled",
+              message: "OpenClaw config explicitly disables the ACP runtime",
+            },
+          ],
+        }),
+      ]);
+    } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});
+
 interface FakeGateway {
   addChannel: ReturnType<typeof vi.fn>;
   removeChannel: ReturnType<typeof vi.fn>;

package/src/__tests__/start-auth.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { resolveStartAuthAction } from "../start-auth.js";
+import type { UserAuthRecord } from "../user-auth.js";
+
+const existingAuth: UserAuthRecord = {
+  version: 1,
+  userId: "usr_1",
+  daemonInstanceId: "dm_1",
+  hubUrl: "https://hub.example",
+  accessToken: "at",
+  refreshToken: "rt",
+  expiresAt: Date.now() + 60_000,
+  loggedInAt: new Date().toISOString(),
+};
+
+describe("resolveStartAuthAction", () => {
+  it("reuses existing auth even when a one-time install token is present", () => {
+    expect(
+      resolveStartAuthAction({
+        existing: existingAuth,
+        relogin: false,
+        installToken: "dit_expired",
+      }),
+    ).toBe("reuse-existing");
+  });
+
+  it("redeems an install token when no existing auth is available", () => {
+    expect(
+      resolveStartAuthAction({
+        existing: null,
+        relogin: false,
+        installToken: "dit_new",
+      }),
+    ).toBe("install-token");
+  });
+
+  it("allows --relogin to re-bind with an install token", () => {
+    expect(
+      resolveStartAuthAction({
+        existing: existingAuth,
+        relogin: true,
+        installToken: "dit_new",
+      }),
+    ).toBe("install-token");
+  });
+});

package/src/gateway/__tests__/botcord-channel.test.ts

@@ -182,6 +182,58 @@ describe("createBotCordChannel — inbox normalization", () => {
     return { emits, client, server };
   }
 
+  it("logs why an empty inbox drain ran", async () => {
+    const server = await startAuthOkServer();
+    const client = makeClient({
+      pollInbox: vi.fn().mockResolvedValue({ messages: [], count: 0, has_more: false }),
+      getHubUrl: vi.fn().mockReturnValue(server.url),
+    });
+    const channel = createBotCordChannel({
+      id: "botcord-main",
+      accountId: "ag_self",
+      agentId: "ag_self",
+      client,
+      hubBaseUrl: server.url,
+    });
+    const abort = new AbortController();
+    const log: GatewayLogger = {
+      ...silentLog,
+      info: vi.fn(),
+    };
+    const startPromise = channel.start({
+      config: stubConfig,
+      accountId: "ag_self",
+      abortSignal: abort.signal,
+      log,
+      emit: async () => {},
+      setStatus: () => {},
+    });
+    try {
+      await vi.waitFor(() => {
+        expect(log.info).toHaveBeenCalledWith(
+          "botcord inbox drained",
+          expect.objectContaining({
+            trigger: "ws_auth_ok",
+            count: 0,
+            responseCount: 0,
+            hasMore: false,
+            limit: 50,
+            ack: false,
+            eligibleCount: 0,
+            duplicateCount: 0,
+            skippedCount: 0,
+            emittedGroups: 0,
+            durationMs: expect.any(Number),
+          }),
+        );
+      });
+    } finally {
+      abort.abort();
+      await startPromise;
+      await server.close();
+    }
+  });
+
   it("maps a group-room InboxMessage to a GatewayInboundMessage", async () => {
     const { emits, server } = await startWithInbox([
       makeInbox({

package/src/gateway/channels/botcord.ts

@@ -28,6 +28,9 @@ const MAX_AUTH_FAILURES = 5;
 const SEEN_MESSAGES_CAP = 500;
 const OWNER_CHAT_PREFIX = "rm_oc_";
 const DM_ROOM_PREFIX = "rm_dm_";
+const INBOX_POLL_LIMIT = 50;
+
+type InboxDrainTrigger = "ws_auth_ok" | "ws_inbox_update" | "coalesced_inbox_update";
 
 /** Minimal surface the adapter needs from `BotCordClient`. Matches the subset used at runtime. */
 export interface BotCordChannelClient {
@@ -305,20 +308,43 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
     client: BotCordChannelClient,
     emit: (env: GatewayInboundEnvelope) => Promise<void>,
     log: GatewayLogger,
+    trigger: InboxDrainTrigger,
   ): Promise<void> {
-    const resp = await client.pollInbox({ limit: 50, ack: false });
+    const startedAt = Date.now();
+    const resp = await client.pollInbox({ limit: INBOX_POLL_LIMIT, ack: false });
     const msgs = resp.messages ?? [];
-    log.info("botcord inbox drained", { count: msgs.length });
-    if (msgs.length === 0) return;
+    let duplicateCount = 0;
+    let skippedCount = 0;
+    let emittedGroups = 0;
+    const logDrain = () => {
+      log.info("botcord inbox drained", {
+        trigger,
+        count: msgs.length,
+        responseCount: resp.count,
+        hasMore: resp.has_more,
+        limit: INBOX_POLL_LIMIT,
+        ack: false,
+        eligibleCount: eligible.length,
+        duplicateCount,
+        skippedCount,
+        emittedGroups,
+        durationMs: Date.now() - startedAt,
+      });
+    };
+    const eligible: InboxMessage[] = [];
+    if (msgs.length === 0) {
+      logDrain();
+      return;
+    }
 
     // First pass: ack duplicates/skipped messages so Hub stops requeueing,
     // and collect eligible messages preserving poll order. Grouping by
     // `(room_id, topic)` mirrors plugin's `handleInboxMessageBatch` — the
     // same conversation thread folds into one turn so the agent sees all
     // new messages at once instead of running N turns back-to-back.
-    const eligible: InboxMessage[] = [];
     for (const msg of msgs) {
       if (!rememberSeen(msg.hub_msg_id)) {
+        duplicateCount += 1;
         try {
           await client.ackMessages([msg.hub_msg_id]);
         } catch (err) {
@@ -331,6 +357,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         accountId: options.accountId,
       });
       if (!normalized) {
+        skippedCount += 1;
         try {
           await client.ackMessages([msg.hub_msg_id]);
         } catch (err) {
@@ -341,7 +368,10 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
       eligible.push(msg);
     }
 
-    if (eligible.length === 0) return;
+    if (eligible.length === 0) {
+      logDrain();
+      return;
+    }
 
     // Group by `(room_id, topic)`. Insertion order is the poll order, so
     // iterating the map yields groups with the same external chronology.
@@ -381,6 +411,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
       };
       try {
         await emit(envelope);
+        emittedGroups += 1;
       } catch (err) {
         log.error("botcord emit threw", {
           hubMsgIds: hubIds,
@@ -388,6 +419,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         });
       }
     }
+    logDrain();
   }
 
   function startWsLoop(
@@ -429,16 +461,19 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
       setStatus(patch);
     }
 
-    async function fireInbox() {
+    async function fireInbox(trigger: InboxDrainTrigger) {
       if (processing) {
         pendingUpdate = true;
+        log.debug("botcord inbox drain queued while previous drain is running", { trigger });
         return;
       }
       processing = true;
       try {
+        let currentTrigger = trigger;
         do {
           pendingUpdate = false;
-          await drainInbox(client, emit, log);
+          await drainInbox(client, emit, log, currentTrigger);
+          currentTrigger = "coalesced_inbox_update";
         } while (pendingUpdate && running);
       } catch (err) {
         log.error("botcord inbox drain failed", { err: String(err) });
@@ -521,7 +556,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
             lastError: null,
           });
           log.info("botcord ws authenticated", { agentId: msg.agent_id });
-          void fireInbox();
+          void fireInbox("ws_auth_ok");
           keepaliveTimer = setInterval(() => {
             if (ws && ws.readyState === WebSocket.OPEN) {
               try {
@@ -533,7 +568,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
           }, KEEPALIVE_INTERVAL);
         } else if (msg.type === "inbox_update") {
           log.info("botcord ws inbox_update received");
-          void fireInbox();
+          void fireInbox("ws_inbox_update");
         } else if (msg.type === "heartbeat" || msg.type === "pong") {
           // no-op
         } else if (msg.type === "error" || msg.type === "auth_failed") {

package/src/index.ts

@@ -57,6 +57,7 @@ import {
   updateWorkingMemory,
   DEFAULT_SECTION,
 } from "./working-memory.js";
+import { resolveStartAuthAction } from "./start-auth.js";
 import {
   discoverLocalOpenclawGateways,
   mergeOpenclawGateways,
@@ -417,9 +418,10 @@ async function runDeviceCodeFlow(opts: {
  * plane (legacy P0 behavior — caller may still log a warning).
  *
  * Decision tree (plan §4.4 + §6.4):
- * 1. Have existing creds, no `--relogin`, no `--install-token` → return existing record.
- * 2. `--install-token` (overrides existing creds — they may be stale or
- *    belong to a different account) → redeem the one-time dashboard ticket.
+ * 1. Have existing creds and no `--relogin` → return existing record, even
+ *    when a dashboard `--install-token` is present. The token is one-time and
+ *    the generated install command should be safe to re-run after first login.
+ * 2. No existing creds + `--install-token` → redeem the one-time dashboard ticket.
  * 3. `--relogin` → device-code login.
  * 4. No creds + TTY → device-code login.
  * 5. No creds + no TTY → exit 1 with the §6.4 hint.
@@ -432,8 +434,9 @@ async function ensureUserAuthForStart(args: ParsedArgs): Promise<UserAuthRecord
   const relogin = args.flags.relogin === true;
 
   const existing = safeLoadUserAuth();
+  const authAction = resolveStartAuthAction({ existing, relogin, installToken });
 
-  if (!relogin && !installToken && existing) {
+  if (authAction === "reuse-existing" && existing) {
     // A previously-set auth-expired flag is stale by definition once the
     // operator runs `start` again — if creds genuinely don't work, the
     // control channel will re-write the flag on the next 4401/4403.
@@ -449,6 +452,9 @@ async function ensureUserAuthForStart(args: ParsedArgs): Promise<UserAuthRecord
         `note: --label "${labelFlag}" ignored (already logged in as "${existing.label ?? "<unset>"}"); pass --relogin to change it`,
       );
     }
+    if (installToken) {
+      console.error("note: --install-token ignored because daemon is already logged in; pass --relogin to re-bind");
+    }
     return existing;
   }
 
@@ -456,7 +462,7 @@ async function ensureUserAuthForStart(args: ParsedArgs): Promise<UserAuthRecord
   const hubUrl = hubFlag ?? existing?.hubUrl ?? DEFAULT_HUB;
   const label = labelFlag ?? defaultLoginLabel();
 
-  if (installToken) {
+  if (authAction === "install-token" && installToken) {
     const tok = await redeemInstallToken({ hubUrl, installToken, label });
     const record = userAuthFromTokenResponse(tok, { label });
     saveUserAuth(record);

package/src/provision.ts

@@ -1324,22 +1324,48 @@ export async function collectRuntimeSnapshotAsync(opts: {
   const capped = gateways.slice(0, RUNTIME_ENDPOINTS_CAP);
   const endpoints = await Promise.all(
     capped.map(async (g) => {
+      if (localOpenclawAcpDisabled(g.url)) {
+        return {
+          name: g.name,
+          url: g.url,
+          reachable: false,
+          status: "acp_disabled",
+          error: "OpenClaw ACP runtime disabled",
+          diagnostics: [
+            {
+              code: "acp_disabled",
+              message: "OpenClaw config explicitly disables the ACP runtime",
+            },
+          ],
+        };
+      }
       try {
         const res = await probeOpenclawAgents(g, {
           probe: opts.wsProbe,
           timeoutMs,
         });
-        const entry: any = { name: g.name, url: g.url, reachable: res.ok };
+        const entry: any = {
+          name: g.name,
+          url: g.url,
+          reachable: res.ok,
+          status: res.ok ? "reachable" : "unreachable",
+        };
         if (res.version) entry.version = res.version;
-        if (res.error) entry.error = res.error;
+        if (res.error) {
+          entry.error = res.error;
+          entry.diagnostics = [{ code: "gateway_unreachable", message: res.error }];
+        }
         if (res.agents) entry.agents = res.agents;
         return entry;
       } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
         return {
           name: g.name,
           url: g.url,
           reachable: false,
-          error: (err as Error).message,
+          status: "unreachable",
+          error: message,
+          diagnostics: [{ code: "probe_failed", message }],
         };
       }
     }),

package/src/start-auth.ts

@@ -0,0 +1,13 @@
+import type { UserAuthRecord } from "./user-auth.js";
+
+export type StartAuthAction = "reuse-existing" | "install-token" | "device-code";
+
+export function resolveStartAuthAction(opts: {
+  existing: UserAuthRecord | null;
+  relogin: boolean;
+  installToken?: string;
+}): StartAuthAction {
+  if (opts.existing && !opts.relogin) return "reuse-existing";
+  if (opts.installToken) return "install-token";
+  return "device-code";
+}