@botcord/daemon 0.2.16 → 0.2.18

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/agent-discovery.ts

@@ -66,6 +66,12 @@ export interface DiscoveryFs {
 export interface DiscoveryOptions extends DiscoveryFs {
   /** Directory to scan. Defaults to {@link DEFAULT_CREDENTIALS_DIR}. */
   credentialsDir?: string;
+  /**
+   * Optional daemon target Hub. When set, auto-discovered credentials whose
+   * hubUrl points at a different host are skipped so preview/prod identities
+   * are not mixed by accident.
+   */
+  expectedHubUrl?: string;
 }
 
 /**
@@ -137,6 +143,12 @@ export function discoverAgentCredentials(
       warnings.push(`credentials at ${file} missing agentId; skipped`);
       continue;
     }
+    if (opts.expectedHubUrl && !sameHubHost(creds.hubUrl, opts.expectedHubUrl)) {
+      warnings.push(
+        `credential skipped: hubUrl does not match daemon environment (${file})`,
+      );
+      continue;
+    }
 
     const existing = byAgent.get(creds.agentId);
     if (!existing) {
@@ -188,6 +200,15 @@ function errMsg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+function sameHubHost(a: string | undefined, b: string | undefined): boolean {
+  if (!a || !b) return true;
+  try {
+    return new URL(a).host === new URL(b).host;
+  } catch {
+    return true;
+  }
+}
+
 /** Result of composing explicit config + discovery into the final boot list. */
 export interface BootAgentsResult {
   /** Ordered list of agents the daemon should bind channels for. */

package/src/daemon.ts

@@ -217,12 +217,17 @@ function buildDaemonLogger(): GatewayLogger {
  */
 export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHandle> {
   const logger = opts.log ?? buildDaemonLogger();
+  const userAuth =
+    opts.userAuth === undefined
+      ? tryLoadUserAuth(logger)
+      : opts.userAuth;
+  const expectedHubUrl = opts.hubBaseUrl ?? userAuth?.current?.hubUrl;
 
   // Resolve boot agents: explicit `agents` config wins; otherwise scan the
   // credentials directory. A zero-agent result is valid in P1 — the daemon
   // still starts with zero channels so operators can drop credentials in
   // and restart without re-running `init`.
-  const boot = opts.bootAgents ?? resolveBootAgents(opts.config);
+  const boot = opts.bootAgents ?? resolveBootAgents(opts.config, { expectedHubUrl });
   for (const w of boot.warnings) {
     logger.warn("daemon.discovery.warning", { message: w });
   }
@@ -455,10 +460,6 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
   // when user-auth hasn't been set up yet. Operators can `login` later
   // without restarting, but for P0 we require a restart to pick it up.
   let controlChannel: ControlChannel | null = null;
-  const userAuth =
-    opts.userAuth === undefined
-      ? tryLoadUserAuth(logger)
-      : opts.userAuth;
   if (userAuth?.current && !opts.disableControlChannel) {
     logger.info("control-channel: enabling", {
       userId: userAuth.current.userId,

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/openclaw-discovery.ts

@@ -30,7 +30,7 @@ export interface MergeOpenclawGatewayResult {
 }
 
 const DEFAULT_SEARCH_PATHS = ["~/.openclaw/", "/etc/openclaw/"];
-const DEFAULT_PORTS = [18789];
+const DEFAULT_PORTS = [18789, 16200];
 
 export async function discoverLocalOpenclawGateways(
   opts: OpenclawGatewayDiscoveryOptions = {},
@@ -41,17 +41,8 @@ export async function discoverLocalOpenclawGateways(
   }
 
   const env = opts.env ?? process.env;
-  const envUrl = env.OPENCLAW_ACP_URL;
-  if (envUrl) {
-    const item: DiscoveredOpenclawGateway = {
-      name: nameFromUrl(envUrl),
-      url: envUrl,
-      source: "env",
-    };
-    if (env.OPENCLAW_ACP_TOKEN) item.token = env.OPENCLAW_ACP_TOKEN;
-    else if (env.OPENCLAW_ACP_TOKEN_FILE) item.tokenFile = env.OPENCLAW_ACP_TOKEN_FILE;
-    found.push(item);
-  }
+  found.push(...discoverFromEnv(env));
+  const envAuth = pickOpenclawEnvAuth(env);
 
   const ports = opts.defaultPorts ?? DEFAULT_PORTS;
   if (ports.length > 0) {
@@ -60,11 +51,11 @@ export async function discoverLocalOpenclawGateways(
         const url = `ws://127.0.0.1:${port}`;
         try {
           const res = await probeOpenclawAgents(
-            { url },
+            { url, ...envAuth },
             { probe: opts.probe, timeoutMs: opts.timeoutMs },
           );
           if (res.ok) {
-            found.push({ name: nameFromUrl(url), url, source: "default-port" });
+            found.push({ name: nameFromUrl(url), url, source: "default-port", ...envAuth });
           }
         } catch (err) {
           daemonLog.debug("openclaw discovery default-port probe failed", {
@@ -79,6 +70,46 @@ export async function discoverLocalOpenclawGateways(
   return dedupeDiscovered(found);
 }
 
+function discoverFromEnv(env: NodeJS.ProcessEnv): DiscoveredOpenclawGateway[] {
+  const url =
+    pickEnv(env, "OPENCLAW_ACP_URL") ??
+    pickEnv(env, "OPENCLAW_GATEWAY_URL") ??
+    urlFromGatewayPort(env);
+  if (!url) return [];
+
+  return [
+    {
+      name: nameFromUrl(url),
+      url,
+      source: "env",
+      ...pickOpenclawEnvAuth(env),
+    },
+  ];
+}
+
+function pickOpenclawEnvAuth(env: NodeJS.ProcessEnv): { token?: string; tokenFile?: string } {
+  const token = pickEnv(env, "OPENCLAW_ACP_TOKEN") ?? pickEnv(env, "OPENCLAW_GATEWAY_TOKEN");
+  if (token) return { token };
+  const tokenFile =
+    pickEnv(env, "OPENCLAW_ACP_TOKEN_FILE") ?? pickEnv(env, "OPENCLAW_GATEWAY_TOKEN_FILE");
+  if (tokenFile) return { tokenFile };
+  return {};
+}
+
+function urlFromGatewayPort(env: NodeJS.ProcessEnv): string | undefined {
+  const raw = pickEnv(env, "OPENCLAW_GATEWAY_PORT");
+  if (!raw) return undefined;
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return undefined;
+  return `ws://127.0.0.1:${port}`;
+}
+
+function pickEnv(env: NodeJS.ProcessEnv, key: string): string | undefined {
+  const value = env[key];
+  if (typeof value === "string" && value.trim()) return value.trim();
+  return undefined;
+}
+
 export function mergeOpenclawGateways(
   cfg: DaemonConfig,
   found: DiscoveredOpenclawGateway[],

package/src/provision.ts

@@ -667,6 +667,17 @@ export async function adoptDiscoveredOpenclawAgents(ctx: {
     failed: [],
   };
   for (const gw of cfg.openclawGateways ?? []) {
+    if (localOpenclawAcpDisabled(gw.url)) {
+      result.skipped.push({
+        gateway: gw.name,
+        reason: "acp_disabled",
+      });
+      daemonLog.warn("openclaw discovery: gateway found but ACP runtime disabled", {
+        gateway: gw.name,
+        url: gw.url,
+      });
+      continue;
+    }
     let probeResult: Awaited<ReturnType<typeof probeOpenclawAgents>>;
     try {
       probeResult = await probeOpenclawAgents(gw, {
@@ -743,6 +754,18 @@ export async function adoptDiscoveredOpenclawAgents(ctx: {
   return result;
 }
 
+function localOpenclawAcpDisabled(rawUrl: string): boolean {
+  if (!isLoopbackUrl(rawUrl)) return false;
+  try {
+    const file = path.join(homedir(), ".openclaw", "openclaw.json");
+    if (!existsSync(file)) return false;
+    const cfg = JSON.parse(readFileSync(file, "utf8")) as any;
+    return cfg?.acp?.enabled === false;
+  } catch {
+    return false;
+  }
+}
+
 async function revokeAgent(
   params: RevokeAgentParams,
   ctx: { gateway: Gateway },
@@ -1301,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";
+}