@botcord/daemon 0.2.16 → 0.2.18

package/dist/agent-discovery.d.ts

@@ -49,6 +49,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;
 }
 /**
  * Scan the credentials directory and return one entry per valid BotCord

package/dist/agent-discovery.js

@@ -66,6 +66,10 @@ export function discoverAgentCredentials(opts = {}) {
             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) {
             byAgent.set(creds.agentId, { creds, credentialsFile: file, mtimeMs });
@@ -116,6 +120,16 @@ export function discoverAgentCredentials(opts = {}) {
 function errMsg(err) {
     return err instanceof Error ? err.message : String(err);
 }
+function sameHubHost(a, b) {
+    if (!a || !b)
+        return true;
+    try {
+        return new URL(a).host === new URL(b).host;
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * Resolve the list of agents the daemon should bind at boot.
  *

package/dist/daemon.js

@@ -116,11 +116,15 @@ function buildDaemonLogger() {
  */
 export async function startDaemon(opts) {
     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 });
     }
@@ -316,9 +320,6 @@ export async function startDaemon(opts) {
     // 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 = 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/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/openclaw-discovery.js

@@ -4,34 +4,23 @@ import path from "node:path";
 import { log as daemonLog } from "./log.js";
 import { probeOpenclawAgents } from "./provision.js";
 const DEFAULT_SEARCH_PATHS = ["~/.openclaw/", "/etc/openclaw/"];
-const DEFAULT_PORTS = [18789];
+const DEFAULT_PORTS = [18789, 16200];
 export async function discoverLocalOpenclawGateways(opts = {}) {
     const found = [];
     for (const root of opts.searchPaths ?? DEFAULT_SEARCH_PATHS) {
         found.push(...discoverFromConfigDir(root));
     }
     const env = opts.env ?? process.env;
-    const envUrl = env.OPENCLAW_ACP_URL;
-    if (envUrl) {
-        const item = {
-            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) {
         await Promise.all(ports.map(async (port) => {
             const url = `ws://127.0.0.1:${port}`;
             try {
-                const res = await probeOpenclawAgents({ url }, { probe: opts.probe, timeoutMs: opts.timeoutMs });
+                const res = await probeOpenclawAgents({ 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) {
@@ -44,6 +33,45 @@ export async function discoverLocalOpenclawGateways(opts = {}) {
     }
     return dedupeDiscovered(found);
 }
+function discoverFromEnv(env) {
+    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) {
+    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) {
+    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, key) {
+    const value = env[key];
+    if (typeof value === "string" && value.trim())
+        return value.trim();
+    return undefined;
+}
 export function mergeOpenclawGateways(cfg, found) {
     const existing = cfg.openclawGateways ?? [];
     const byUrl = new Map();

package/dist/provision.js

@@ -534,6 +534,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;
         try {
             probeResult = await probeOpenclawAgents(gw, {
@@ -611,6 +622,20 @@ export async function adoptDiscoveredOpenclawAgents(ctx) {
     }
     return result;
 }
+function localOpenclawAcpDisabled(rawUrl) {
+    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"));
+        return cfg?.acp?.enabled === false;
+    }
+    catch {
+        return false;
+    }
+}
 async function revokeAgent(params, ctx) {
     if (!params.agentId) {
         throw new Error("revoke_agent requires params.agentId");
@@ -1112,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.16",
+  "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__/agent-discovery.test.ts

@@ -159,6 +159,44 @@ describe("resolveBootAgents", () => {
     expect(res.agents[0].credentialsFile).toBe("/creds/x.json");
   });
 
+  it("skips discovered credentials from a different Hub host", () => {
+    const res = resolveBootAgents(cfg(), {
+      credentialsDir: "/creds",
+      expectedHubUrl: "https://api.preview.botcord.chat",
+      readDir: () => ["prod.json", "preview.json"],
+      stat: () => fakeStat(1),
+      loadCredentials: (f) =>
+        f.endsWith("prod.json")
+          ? fakeCreds("ag_prod", { hubUrl: "https://api.botcord.chat" })
+          : fakeCreds("ag_preview", { hubUrl: "https://api.preview.botcord.chat" }),
+    });
+
+    expect(res.source).toBe("credentials");
+    expect(res.agents.map((a) => a.agentId)).toEqual(["ag_preview"]);
+    expect(res.warnings).toEqual([
+      "credential skipped: hubUrl does not match daemon environment (/creds/prod.json)",
+    ]);
+  });
+
+  it("filters by Hub host before resolving duplicate agentIds", () => {
+    const res = resolveBootAgents(cfg(), {
+      credentialsDir: "/creds",
+      expectedHubUrl: "https://api.preview.botcord.chat",
+      readDir: () => ["preview.json", "prod.json"],
+      stat: (p) => (p.endsWith("prod.json") ? fakeStat(200) : fakeStat(100)),
+      loadCredentials: (f) =>
+        f.endsWith("prod.json")
+          ? fakeCreds("ag_same", { hubUrl: "https://api.botcord.chat" })
+          : fakeCreds("ag_same", { hubUrl: "https://api.preview.botcord.chat" }),
+    });
+
+    expect(res.agents.map((a) => a.agentId)).toEqual(["ag_same"]);
+    expect(res.agents[0].credentialsFile).toBe("/creds/preview.json");
+    expect(res.warnings).toEqual([
+      "credential skipped: hubUrl does not match daemon environment (/creds/prod.json)",
+    ]);
+  });
+
   it("returns an empty agent list (not a throw) when discovery finds nothing", () => {
     const res = resolveBootAgents(cfg(), {
       credentialsDir: "/creds",

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

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
+  defaultOpenclawDiscoveryPorts,
   discoverLocalOpenclawGateways,
   mergeOpenclawGateways,
 } from "../openclaw-discovery.js";
@@ -108,6 +109,69 @@ describe("discoverLocalOpenclawGateways", () => {
     ]);
   });
 
+  it("uses OPENCLAW_GATEWAY_URL and gateway token env vars", async () => {
+    const found = await discoverLocalOpenclawGateways({
+      searchPaths: [],
+      defaultPorts: [],
+      env: {
+        OPENCLAW_GATEWAY_URL: "ws://127.0.0.1:16200",
+        OPENCLAW_GATEWAY_TOKEN: "gateway-token",
+      },
+    });
+
+    expect(found).toEqual([
+      expect.objectContaining({
+        url: "ws://127.0.0.1:16200",
+        token: "gateway-token",
+        source: "env",
+      }),
+    ]);
+  });
+
+  it("builds gateway URL from OPENCLAW_GATEWAY_PORT", async () => {
+    const found = await discoverLocalOpenclawGateways({
+      searchPaths: [],
+      defaultPorts: [],
+      env: {
+        OPENCLAW_GATEWAY_PORT: "16200",
+        OPENCLAW_GATEWAY_TOKEN: "gateway-token",
+      },
+    });
+
+    expect(found).toEqual([
+      expect.objectContaining({
+        url: "ws://127.0.0.1:16200",
+        token: "gateway-token",
+        source: "env",
+      }),
+    ]);
+  });
+
+  it("prefers OPENCLAW_ACP env vars over OPENCLAW_GATEWAY env vars", async () => {
+    const found = await discoverLocalOpenclawGateways({
+      searchPaths: [],
+      defaultPorts: [],
+      env: {
+        OPENCLAW_ACP_URL: "ws://127.0.0.1:18888",
+        OPENCLAW_ACP_TOKEN: "acp-token",
+        OPENCLAW_GATEWAY_URL: "ws://127.0.0.1:16200",
+        OPENCLAW_GATEWAY_TOKEN: "gateway-token",
+      },
+    });
+
+    expect(found).toEqual([
+      expect.objectContaining({
+        url: "ws://127.0.0.1:18888",
+        token: "acp-token",
+        source: "env",
+      }),
+    ]);
+  });
+
+  it("includes 16200 in default discovery ports", () => {
+    expect(defaultOpenclawDiscoveryPorts()).toEqual(expect.arrayContaining([18789, 16200]));
+  });
+
   it("adds default-port candidates only when the probe succeeds", async () => {
     const probe = vi.fn<WsEndpointProbeFn>(async ({ url }) => ({
       ok: url.includes("18789"),
@@ -125,6 +189,37 @@ describe("discoverLocalOpenclawGateways", () => {
     expect(found.map((g) => g.url)).toEqual(["ws://127.0.0.1:18789"]);
   });
 
+  it("attaches gateway token fallback to default-port discovery", async () => {
+    const probe = vi.fn<WsEndpointProbeFn>(async () => ({
+      ok: true,
+      agents: [],
+    }));
+
+    const found = await discoverLocalOpenclawGateways({
+      searchPaths: [],
+      defaultPorts: [16200],
+      probe,
+      timeoutMs: 10,
+      env: {
+        OPENCLAW_GATEWAY_TOKEN: "gateway-token",
+      },
+    });
+
+    expect(probe).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: "ws://127.0.0.1:16200",
+        token: "gateway-token",
+      }),
+    );
+    expect(found).toEqual([
+      expect.objectContaining({
+        url: "ws://127.0.0.1:16200",
+        token: "gateway-token",
+        source: "default-port",
+      }),
+    ]);
+  });
+
   it("prefers config-file auth details over lower-priority duplicate sources", async () => {
     const dir = tempDir();
     writeFileSync(

package/src/__tests__/provision.test.ts

@@ -887,6 +887,56 @@ describe("adoptDiscoveredOpenclawAgents", () => {
     });
   });
 
+  it("skips auto-adopt when local OpenClaw ACP is explicitly disabled", async () => {
+    await withSandboxHome(async ({ tmp, fs, path: nodePath }) => {
+      const credDir = nodePath.join(tmp, ".botcord", "credentials");
+      fs.mkdirSync(credDir, { recursive: true });
+      fs.writeFileSync(
+        nodePath.join(credDir, "ag_seed.json"),
+        JSON.stringify({
+          version: 1,
+          hubUrl: "https://hub.example",
+          agentId: "ag_seed",
+          keyId: "k_seed",
+          privateKey: Buffer.alloc(32, 8).toString("base64"),
+          savedAt: new Date().toISOString(),
+        }),
+      );
+      const openclawDir = nodePath.join(tmp, ".openclaw");
+      fs.mkdirSync(openclawDir, { recursive: true });
+      fs.writeFileSync(
+        nodePath.join(openclawDir, "openclaw.json"),
+        JSON.stringify({ acp: { enabled: false } }),
+      );
+      mockState.cfg = {
+        defaultRoute: { adapter: "claude-code", cwd: "/tmp" },
+        routes: [],
+        streamBlocks: true,
+        agents: ["ag_seed"],
+        openclawGateways: [{ name: "local", url: "ws://127.0.0.1:18789" }],
+      };
+      const register = vi.fn();
+      const probe = vi.fn<Parameters<typeof adoptDiscoveredOpenclawAgents>[0]["probe"]>(
+        async () => ({ ok: true, agents: [{ id: "main" }] }),
+      );
+
+      const res = await adoptDiscoveredOpenclawAgents({
+        gateway: makeFakeGateway(["ag_seed"]) as unknown as Parameters<typeof adoptDiscoveredOpenclawAgents>[0]["gateway"],
+        register: register as unknown as Parameters<typeof adoptDiscoveredOpenclawAgents>[0]["register"],
+        cfg: mockState.cfg as unknown as DaemonConfig,
+        probe,
+      });
+
+      expect(res).toEqual({
+        adopted: [],
+        skipped: [{ gateway: "local", reason: "acp_disabled" }],
+        failed: [],
+      });
+      expect(probe).not.toHaveBeenCalled();
+      expect(register).not.toHaveBeenCalled();
+    });
+  });
+
   it("uses the OpenClaw workspace identity name when agents.list has no name", async () => {
     await withSandboxHome(async ({ tmp, fs, path: nodePath }) => {
       const credDir = nodePath.join(tmp, ".botcord", "credentials");