@botcord/daemon 0.2.33 → 0.2.34

package/dist/gateway/channel-manager.js

@@ -2,6 +2,7 @@ const DEFAULT_INITIAL_BACKOFF = 1000;
 const DEFAULT_MAX_BACKOFF = 60_000;
 const DEFAULT_FACTOR = 2;
 const LONG_RUN_THRESHOLD_MS = 30_000;
+const CHANNEL_PERMANENT_STOP = "channel_permanent_stop";
 /** Supervises channel adapters: lifecycle, status tracking, and crash restart with backoff. */
 export class ChannelManager {
     config;
@@ -214,17 +215,28 @@ export class ChannelManager {
         const ranForMs = Date.now() - entry.currentStartAt;
         const channelId = entry.adapter.id;
         const crashed = err !== null && err !== undefined;
+        const permanentStop = typeof err === "object" &&
+            err !== null &&
+            err.code === CHANNEL_PERMANENT_STOP;
         entry.snapshot = {
             ...entry.snapshot,
             running: false,
             lastStopAt: Date.now(),
-            lastError: crashed
+            lastError: crashed && !permanentStop
                 ? err instanceof Error
                     ? err.message
                     : String(err)
                 : entry.snapshot.lastError ?? null,
         };
-        if (crashed) {
+        if (permanentStop) {
+            this.log.info("channel stopped permanently", {
+                channel: channelId,
+                reason: err instanceof Error ? err.message : String(err),
+            });
+            entry.state = "idle";
+            entry.stopRequested = true;
+        }
+        else if (crashed) {
             this.log.warn("channel crashed", {
                 channel: channelId,
                 error: err instanceof Error ? err.message : String(err),

package/dist/gateway/channels/botcord.d.ts

@@ -1,6 +1,6 @@
 import WebSocket from "ws";
 import { type InboxMessage } from "@botcord/protocol-core";
-import type { ChannelAdapter, GatewayInboundMessage } from "../index.js";
+import type { ChannelAdapter, GatewayInboundMessage, GatewayLogger } from "../index.js";
 /** Minimal surface the adapter needs from `BotCordClient`. Matches the subset used at runtime. */
 export interface BotCordChannelClient {
     ensureToken(): Promise<string>;
@@ -55,6 +55,8 @@ export interface BotCordChannelOptions {
      * can't spin up a real WS server.
      */
     webSocketCtor?: typeof WebSocket;
+    /** Test hook: override local cleanup after Hub says the agent is unclaimed. */
+    localRevokeAgent?: (agentId: string, log: GatewayLogger) => Promise<unknown>;
 }
 /**
  * Map `InboxMessage` → `GatewayInboundMessage`. Field origins:

package/dist/gateway/channels/botcord.js

@@ -1,6 +1,7 @@
 import WebSocket from "ws";
 import { BotCordClient, buildHubWebSocketUrl, defaultCredentialsFile, loadStoredCredentials, updateCredentialsToken, } from "@botcord/protocol-core";
 import { sanitizeUntrustedContent } from "./sanitize.js";
+import { revokeAgent } from "../../provision.js";
 const RECONNECT_BACKOFF = [1000, 2000, 4000, 8000, 16000, 30000];
 const KEEPALIVE_INTERVAL = 20_000;
 const MAX_AUTH_FAILURES = 5;
@@ -8,6 +9,17 @@ const SEEN_MESSAGES_CAP = 500;
 const OWNER_CHAT_PREFIX = "rm_oc_";
 const DM_ROOM_PREFIX = "rm_dm_";
 const INBOX_POLL_LIMIT = 50;
+const CHANNEL_PERMANENT_STOP = "channel_permanent_stop";
+function isUnclaimedAgentError(err) {
+    const status = err?.status;
+    if (status !== 403)
+        return false;
+    const message = err instanceof Error ? err.message : String(err);
+    return (message.includes('"code":"agent_not_claimed_generic"') ||
+        message.includes('"code":"agent_not_claimed"') ||
+        message.includes("agent_not_claimed_generic") ||
+        message.includes("agent_not_claimed"));
+}
 /** Default factory: wrap `loadStoredCredentials` + `new BotCordClient`. */
 function defaultClientFactory(input) {
     const credFile = input.credentialsPath ?? defaultCredentialsFile(input.agentId);
@@ -334,12 +346,15 @@ export function createBotCordChannel(options) {
         let reconnectAttempt = 0;
         let consecutiveAuthFailures = 0;
         let running = true;
+        let permanentStopping = false;
         let processing = false;
         let pendingUpdate = false;
         let pendingRefresh = null;
         let resolveLoop = null;
-        const done = new Promise((resolve) => {
+        let rejectLoop = null;
+        const done = new Promise((resolve, reject) => {
             resolveLoop = resolve;
+            rejectLoop = reject;
         });
         function clearTimers() {
             if (reconnectTimer) {
@@ -355,6 +370,68 @@ export function createBotCordChannel(options) {
             statusSnapshot = { ...statusSnapshot, ...patch };
             setStatus(patch);
         }
+        async function revokeLocalUnclaimedAgent(err) {
+            if (!isUnclaimedAgentError(err))
+                return false;
+            running = false;
+            permanentStopping = true;
+            clearTimers();
+            try {
+                ws?.close();
+            }
+            catch {
+                // ignore
+            }
+            try {
+                const result = options.localRevokeAgent
+                    ? await options.localRevokeAgent(options.agentId, log)
+                    : await revokeAgent({
+                        agentId: options.agentId,
+                        deleteCredentials: true,
+                        deleteState: true,
+                        deleteWorkspace: false,
+                    }, {
+                        gateway: {
+                            removeChannel: async () => undefined,
+                            removeManagedRoute: () => undefined,
+                        },
+                    });
+                log.warn("botcord agent unclaimed; revoked local binding", {
+                    agentId: options.agentId,
+                    result,
+                });
+                markStatus({
+                    running: false,
+                    connected: false,
+                    restartPending: false,
+                    lastStopAt: Date.now(),
+                    lastError: "agent not claimed; local binding revoked",
+                });
+            }
+            catch (cleanupErr) {
+                log.error("botcord unclaimed local revoke failed", {
+                    agentId: options.agentId,
+                    err: String(cleanupErr),
+                });
+                markStatus({
+                    running: false,
+                    connected: false,
+                    restartPending: false,
+                    lastStopAt: Date.now(),
+                    lastError: String(cleanupErr),
+                });
+            }
+            permanentStopping = false;
+            if (rejectLoop) {
+                const r = rejectLoop;
+                rejectLoop = null;
+                resolveLoop = null;
+                const stopErr = new Error("agent not claimed; local binding revoked");
+                stopErr.code = CHANNEL_PERMANENT_STOP;
+                r(stopErr);
+            }
+            return true;
+        }
         async function fireInbox(trigger) {
             if (processing) {
                 pendingUpdate = true;
@@ -376,6 +453,9 @@ export function createBotCordChannel(options) {
                 } while ((pendingUpdate || hasMore) && running);
             }
             catch (err) {
+                if (await revokeLocalUnclaimedAgent(err)) {
+                    return;
+                }
                 log.error("botcord inbox drain failed", { err: String(err) });
             }
             finally {
@@ -401,6 +481,7 @@ export function createBotCordChannel(options) {
         async function connect() {
             if (!running)
                 return;
+            const agentId = options.agentId;
             markStatus({ connected: false, restartPending: false });
             if (pendingRefresh) {
                 try {
@@ -418,18 +499,18 @@ export function createBotCordChannel(options) {
                 token = await client.ensureToken();
             }
             catch (err) {
-                log.error("botcord ws token refresh failed", { err: String(err) });
+                log.error("botcord ws token refresh failed", { agentId, err: String(err) });
                 markStatus({ lastError: String(err) });
                 scheduleReconnect();
                 return;
             }
             const url = buildHubWebSocketUrl(hubUrl);
-            log.info("botcord ws connecting", { url, agentId: options.agentId });
+            log.info("botcord ws connecting", { url, agentId });
             try {
                 ws = new wsCtor(url);
             }
             catch (err) {
-                log.error("botcord ws construct failed", { err: String(err) });
+                log.error("botcord ws construct failed", { agentId, err: String(err) });
                 markStatus({ lastError: String(err) });
                 scheduleReconnect();
                 return;
@@ -478,18 +559,21 @@ export function createBotCordChannel(options) {
                     // no-op
                 }
                 else if (msg.type === "error" || msg.type === "auth_failed") {
-                    log.warn("botcord ws server error", { msg });
+                    log.warn("botcord ws server error", { agentId, msg });
                 }
             });
             ws.on("close", (code, reason) => {
                 const reasonStr = reason?.toString() || "";
-                log.info("botcord ws closed", { code, reason: reasonStr });
+                log.info("botcord ws closed", { agentId, code, reason: reasonStr });
                 clearTimers();
                 markStatus({ connected: false });
                 if (!running) {
+                    if (permanentStopping)
+                        return;
                     if (resolveLoop) {
                         const r = resolveLoop;
                         resolveLoop = null;
+                        rejectLoop = null;
                         r();
                     }
                     return;
@@ -498,6 +582,7 @@ export function createBotCordChannel(options) {
                     consecutiveAuthFailures += 1;
                     if (consecutiveAuthFailures >= MAX_AUTH_FAILURES) {
                         log.error("botcord ws auth failing persistently — giving up reconnects", {
+                            agentId,
                             failures: consecutiveAuthFailures,
                         });
                         running = false;
@@ -510,18 +595,19 @@ export function createBotCordChannel(options) {
                         if (resolveLoop) {
                             const r = resolveLoop;
                             resolveLoop = null;
+                            rejectLoop = null;
                             r();
                         }
                         return;
                     }
                     pendingRefresh = client
                         .refreshToken()
-                        .catch((err) => log.error("botcord ws forced refresh failed", { err: String(err) }));
+                        .catch((err) => log.error("botcord ws forced refresh failed", { agentId, err: String(err) }));
                 }
                 scheduleReconnect();
             });
             ws.on("error", (err) => {
-                log.warn("botcord ws error", { err: String(err) });
+                log.warn("botcord ws error", { agentId, err: String(err) });
                 markStatus({ lastError: String(err) });
             });
         }
@@ -547,6 +633,7 @@ export function createBotCordChannel(options) {
             if (resolveLoop) {
                 const r = resolveLoop;
                 resolveLoop = null;
+                rejectLoop = null;
                 r();
             }
         }

package/dist/gateway/log.d.ts

@@ -5,5 +5,5 @@ export interface GatewayLogger {
     error(msg: string, meta?: Record<string, unknown>): void;
     debug(msg: string, meta?: Record<string, unknown>): void;
 }
-/** Default logger that writes JSON lines to stderr; debug lines gated by BOTCORD_GATEWAY_DEBUG. */
+/** Default logger that writes compact text lines to stderr; debug lines gated by BOTCORD_GATEWAY_DEBUG. */
 export declare const consoleLogger: GatewayLogger;

package/dist/gateway/log.js

@@ -1,14 +1,10 @@
+import { formatLogLine } from "../log.js";
 function write(level, msg, meta) {
-    const line = JSON.stringify({
-        ts: new Date().toISOString(),
-        level,
-        msg,
-        ...(meta ?? {}),
-    });
+    const line = formatLogLine(level, msg, meta);
     // Always write to stderr so stdout stays clean for NDJSON-style channel output.
     process.stderr.write(line + "\n");
 }
-/** Default logger that writes JSON lines to stderr; debug lines gated by BOTCORD_GATEWAY_DEBUG. */
+/** Default logger that writes compact text lines to stderr; debug lines gated by BOTCORD_GATEWAY_DEBUG. */
 export const consoleLogger = {
     info: (msg, meta) => write("info", msg, meta),
     warn: (msg, meta) => write("warn", msg, meta),

package/dist/log.d.ts

@@ -1,3 +1,5 @@
+type Level = "info" | "warn" | "error" | "debug";
+export declare function formatLogLine(level: Level, msg: string, fields: Record<string, unknown> | undefined, date?: Date): string;
 export declare const log: {
     info: (msg: string, fields?: Record<string, unknown>) => void;
     warn: (msg: string, fields?: Record<string, unknown>) => void;
@@ -5,3 +7,4 @@ export declare const log: {
     debug: (msg: string, fields?: Record<string, unknown>) => void;
 };
 export declare const LOG_FILE_PATH: string;
+export {};

package/dist/log.js

@@ -15,14 +15,33 @@ function ensureDir() {
     }
     inited = true;
 }
+function formatValue(value) {
+    if (value instanceof Error)
+        return JSON.stringify(value.stack ?? value.message);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean" || value === null)
+        return String(value);
+    if (value === undefined)
+        return "undefined";
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return JSON.stringify(String(value));
+    }
+}
+export function formatLogLine(level, msg, fields, date = new Date()) {
+    const detail = Object.entries(fields ?? {})
+        .map(([key, value]) => `${key}=${formatValue(value)}`)
+        .join(" ");
+    const prefix = `[${level.toUpperCase()}] ${msg}`;
+    const suffix = `ts=${date.toISOString()}`;
+    return detail ? `${prefix} ${detail} ${suffix}` : `${prefix} ${suffix}`;
+}
 function write(level, msg, fields) {
     ensureDir();
-    const line = JSON.stringify({
-        ts: new Date().toISOString(),
-        level,
-        msg,
-        ...(fields ?? {}),
-    });
+    const line = formatLogLine(level, msg, fields);
     try {
         appendFileSync(LOG_FILE, line + "\n", { mode: 0o600 });
     }

package/dist/provision.d.ts

@@ -1,4 +1,4 @@
-import { BotCordClient, type AgentIdentitySnapshot, type ControlAck, type ControlFrame, type ListRuntimesResult } from "@botcord/protocol-core";
+import { BotCordClient, type AgentIdentitySnapshot, type ControlAck, type ControlFrame, type ListRuntimesResult, type RevokeAgentParams, type RevokeAgentResult } from "@botcord/protocol-core";
 import type { Gateway } from "./gateway/index.js";
 import type { PolicyResolverLike } from "./gateway/policy-resolver.js";
 import { type DaemonConfig } from "./config.js";
@@ -80,6 +80,9 @@ export declare function adoptDiscoveredOpenclawAgents(ctx: {
     probe?: WsEndpointProbeFn;
     onAgentInstalled?: OnAgentInstalledHook;
 }): Promise<AdoptDiscoveredOpenclawAgentsResult>;
+export declare function revokeAgent(params: RevokeAgentParams, ctx: {
+    gateway: Gateway;
+}): Promise<RevokeAgentResult>;
 /**
  * Append `agentId` to the daemon config if not already present. Returns a
  * new config object or `null` if nothing changed (so callers can skip the

package/dist/provision.js

@@ -860,7 +860,7 @@ function localOpenclawAcpDisabled(rawUrl) {
         return false;
     }
 }
-async function revokeAgent(params, ctx) {
+export async function revokeAgent(params, ctx) {
     if (!params.agentId) {
         throw new Error("revoke_agent requires params.agentId");
     }

package/package.json

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

package/src/__tests__/log.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { formatLogLine } from "../log.js";
+
+describe("formatLogLine", () => {
+  it("renders compact text with level, message, details, and trailing timestamp", () => {
+    const line = formatLogLine(
+      "warn",
+      "botcord ws error",
+      { err: "Error: Unexpected server response: 503" },
+      new Date("2026-05-01T00:22:07.131Z"),
+    );
+
+    expect(line).toBe(
+      '[WARN] botcord ws error err="Error: Unexpected server response: 503" ts=2026-05-01T00:22:07.131Z',
+    );
+  });
+
+  it("keeps object details readable without replacing the primary message", () => {
+    const line = formatLogLine(
+      "info",
+      "botcord ws server error",
+      { msg: { type: "error", code: 503 } },
+      new Date("2026-05-01T00:22:07.131Z"),
+    );
+
+    expect(line).toBe(
+      '[INFO] botcord ws server error msg={"type":"error","code":503} ts=2026-05-01T00:22:07.131Z',
+    );
+  });
+});

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

@@ -510,6 +510,61 @@ describe("createBotCordChannel — ack + dedup", () => {
       await server.close();
     }
   });
+
+  it("locally revokes the channel when Hub reports the agent is unclaimed", async () => {
+    const server = await startAuthOkServer();
+    try {
+      const err = new Error(
+        'BotCord /hub/inbox?limit=50 failed: 403 {"code":"agent_not_claimed_generic","retryable":false}',
+      ) as Error & { status?: number };
+      err.status = 403;
+      const client = makeClient({
+        getHubUrl: vi.fn().mockReturnValue(server.url),
+        pollInbox: vi.fn().mockRejectedValue(err),
+      });
+      const localRevokeAgent = vi.fn().mockResolvedValue({
+        agentId: "ag_self",
+        credentialsDeleted: true,
+        stateDeleted: true,
+        workspaceDeleted: false,
+      });
+      const statuses: Record<string, unknown>[] = [];
+      const logs: Array<{ msg: string; meta?: Record<string, unknown> }> = [];
+      const log: GatewayLogger = {
+        ...silentLog,
+        warn: (msg, meta) => logs.push({ msg, meta }),
+      };
+      const channel = createBotCordChannel({
+        id: "botcord-main",
+        accountId: "ag_self",
+        agentId: "ag_self",
+        client,
+        hubBaseUrl: server.url,
+        localRevokeAgent,
+      });
+      const startP = channel.start({
+        config: stubConfig,
+        accountId: "ag_self",
+        abortSignal: new AbortController().signal,
+        log,
+        emit: async () => undefined,
+        setStatus: (patch) => statuses.push(patch),
+      });
+
+      await expect(startP).rejects.toMatchObject({ code: "channel_permanent_stop" });
+      expect(localRevokeAgent).toHaveBeenCalledWith("ag_self", log);
+      expect(logs.some((entry) => entry.msg === "botcord agent unclaimed; revoked local binding"))
+        .toBe(true);
+      expect(statuses.at(-1)).toMatchObject({
+        running: false,
+        connected: false,
+        restartPending: false,
+        lastError: "agent not claimed; local binding revoked",
+      });
+    } finally {
+      await server.close();
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -661,6 +716,52 @@ describe("createBotCordChannel — typing()", () => {
   });
 });
 
+describe("createBotCordChannel — websocket logging", () => {
+  it("includes the agent id on websocket server errors", async () => {
+    const server = await startAuthOkServer();
+    const client = makeClient({
+      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,
+      warn: vi.fn(),
+    };
+    const startPromise = channel.start({
+      config: stubConfig,
+      accountId: "ag_self",
+      abortSignal: abort.signal,
+      log,
+      emit: async () => {},
+      setStatus: () => {},
+    });
+    try {
+      await vi.waitFor(() => expect(server.connections.length).toBe(1));
+      server.connections[0].send(JSON.stringify({ type: "error", code: 503 }));
+      await vi.waitFor(() => {
+        expect(log.warn).toHaveBeenCalledWith(
+          "botcord ws server error",
+          expect.objectContaining({
+            agentId: "ag_self",
+            msg: expect.objectContaining({ type: "error", code: 503 }),
+          }),
+        );
+      });
+    } finally {
+      abort.abort();
+      await startPromise;
+      await server.close();
+    }
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Shared: a tiny WS server that acks every `auth` with `auth_ok`.
 // ---------------------------------------------------------------------------

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

@@ -270,6 +270,32 @@ describe("ChannelManager", () => {
     await mgr.stopAll();
   });
 
+  it("does not restart after permanent channel stop", async () => {
+    const c1 = new FakeChannel("c1");
+    const log = makeLogger();
+    const mgr = new ChannelManager({
+      config: makeConfig(["c1"]),
+      channels: [c1],
+      log,
+      emit: async () => {},
+      backoffMs: { initial: 1000, max: 60_000, factor: 2 },
+    });
+    await mgr.startAll();
+    await flush();
+    const err = new Error("agent not claimed; local binding revoked") as Error & {
+      code?: string;
+    };
+    err.code = "channel_permanent_stop";
+    c1.latest().reject(err);
+    await flush();
+    expect(mgr.status()["c1"].restartPending).toBeFalsy();
+    expect(c1.starts).toHaveLength(1);
+    await vi.advanceTimersByTimeAsync(1000);
+    await flush();
+    expect(c1.starts).toHaveLength(1);
+    expect(log.infos.some((entry) => entry[0] === "channel stopped permanently")).toBe(true);
+  });
+
   it("restarts when channel resolves (graceful) without stopAll", async () => {
     const c1 = new FakeChannel("c1");
     const mgr = new ChannelManager({

package/src/gateway/channel-manager.ts

@@ -43,6 +43,7 @@ const DEFAULT_INITIAL_BACKOFF = 1000;
 const DEFAULT_MAX_BACKOFF = 60_000;
 const DEFAULT_FACTOR = 2;
 const LONG_RUN_THRESHOLD_MS = 30_000;
+const CHANNEL_PERMANENT_STOP = "channel_permanent_stop";
 
 /** Supervises channel adapters: lifecycle, status tracking, and crash restart with backoff. */
 export class ChannelManager {
@@ -266,19 +267,30 @@ export class ChannelManager {
     const ranForMs = Date.now() - entry.currentStartAt;
     const channelId = entry.adapter.id;
     const crashed = err !== null && err !== undefined;
+    const permanentStop =
+      typeof err === "object" &&
+      err !== null &&
+      (err as { code?: unknown }).code === CHANNEL_PERMANENT_STOP;
 
     entry.snapshot = {
       ...entry.snapshot,
       running: false,
       lastStopAt: Date.now(),
-      lastError: crashed
+      lastError: crashed && !permanentStop
         ? err instanceof Error
           ? err.message
           : String(err)
         : entry.snapshot.lastError ?? null,
     };
 
-    if (crashed) {
+    if (permanentStop) {
+      this.log.info("channel stopped permanently", {
+        channel: channelId,
+        reason: err instanceof Error ? err.message : String(err),
+      });
+      entry.state = "idle";
+      entry.stopRequested = true;
+    } else if (crashed) {
       this.log.warn("channel crashed", {
         channel: channelId,
         error: err instanceof Error ? err.message : String(err),

package/src/gateway/channels/botcord.ts

@@ -20,7 +20,9 @@ import type {
   GatewayInboundMessage,
   GatewayLogger,
 } from "../index.js";
+import type { Gateway } from "../gateway.js";
 import { sanitizeUntrustedContent } from "./sanitize.js";
+import { revokeAgent } from "../../provision.js";
 
 const RECONNECT_BACKOFF = [1000, 2000, 4000, 8000, 16000, 30000];
 const KEEPALIVE_INTERVAL = 20_000;
@@ -29,6 +31,7 @@ const SEEN_MESSAGES_CAP = 500;
 const OWNER_CHAT_PREFIX = "rm_oc_";
 const DM_ROOM_PREFIX = "rm_dm_";
 const INBOX_POLL_LIMIT = 50;
+const CHANNEL_PERMANENT_STOP = "channel_permanent_stop";
 
 type InboxDrainTrigger =
   | "ws_auth_ok"
@@ -86,6 +89,20 @@ export interface BotCordChannelOptions {
    * can't spin up a real WS server.
    */
   webSocketCtor?: typeof WebSocket;
+  /** Test hook: override local cleanup after Hub says the agent is unclaimed. */
+  localRevokeAgent?: (agentId: string, log: GatewayLogger) => Promise<unknown>;
+}
+
+function isUnclaimedAgentError(err: unknown): boolean {
+  const status = (err as { status?: unknown } | null)?.status;
+  if (status !== 403) return false;
+  const message = err instanceof Error ? err.message : String(err);
+  return (
+    message.includes('"code":"agent_not_claimed_generic"') ||
+    message.includes('"code":"agent_not_claimed"') ||
+    message.includes("agent_not_claimed_generic") ||
+    message.includes("agent_not_claimed")
+  );
 }
 
 /** Default factory: wrap `loadStoredCredentials` + `new BotCordClient`. */
@@ -456,13 +473,16 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
     let reconnectAttempt = 0;
     let consecutiveAuthFailures = 0;
     let running = true;
+    let permanentStopping = false;
     let processing = false;
     let pendingUpdate = false;
     let pendingRefresh: Promise<unknown> | null = null;
     let resolveLoop: (() => void) | null = null;
+    let rejectLoop: ((err: Error) => void) | null = null;
 
-    const done = new Promise<void>((resolve) => {
+    const done = new Promise<void>((resolve, reject) => {
       resolveLoop = resolve;
+      rejectLoop = reject;
     });
 
     function clearTimers() {
@@ -481,6 +501,71 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
       setStatus(patch);
     }
 
+    async function revokeLocalUnclaimedAgent(err: unknown) {
+      if (!isUnclaimedAgentError(err)) return false;
+      running = false;
+      permanentStopping = true;
+      clearTimers();
+      try {
+        ws?.close();
+      } catch {
+        // ignore
+      }
+      try {
+        const result = options.localRevokeAgent
+          ? await options.localRevokeAgent(options.agentId, log)
+          : await revokeAgent(
+              {
+                agentId: options.agentId,
+                deleteCredentials: true,
+                deleteState: true,
+                deleteWorkspace: false,
+              },
+              {
+                gateway: {
+                  removeChannel: async () => undefined,
+                  removeManagedRoute: () => undefined,
+                } as unknown as Gateway,
+              },
+            );
+        log.warn("botcord agent unclaimed; revoked local binding", {
+          agentId: options.agentId,
+          result,
+        });
+        markStatus({
+          running: false,
+          connected: false,
+          restartPending: false,
+          lastStopAt: Date.now(),
+          lastError: "agent not claimed; local binding revoked",
+        });
+      } catch (cleanupErr) {
+        log.error("botcord unclaimed local revoke failed", {
+          agentId: options.agentId,
+          err: String(cleanupErr),
+        });
+        markStatus({
+          running: false,
+          connected: false,
+          restartPending: false,
+          lastStopAt: Date.now(),
+          lastError: String(cleanupErr),
+        });
+      }
+      permanentStopping = false;
+      if (rejectLoop) {
+        const r = rejectLoop;
+        rejectLoop = null;
+        resolveLoop = null;
+        const stopErr = new Error("agent not claimed; local binding revoked") as Error & {
+          code?: string;
+        };
+        stopErr.code = CHANNEL_PERMANENT_STOP;
+        r(stopErr);
+      }
+      return true;
+    }
+
     async function fireInbox(trigger: InboxDrainTrigger) {
       if (processing) {
         pendingUpdate = true;
@@ -501,6 +586,9 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
           currentTrigger = hasMore ? "has_more_continue" : "coalesced_inbox_update";
         } while ((pendingUpdate || hasMore) && running);
       } catch (err) {
+        if (await revokeLocalUnclaimedAgent(err)) {
+          return;
+        }
         log.error("botcord inbox drain failed", { err: String(err) });
       } finally {
         processing = false;
@@ -526,6 +614,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
 
     async function connect() {
       if (!running) return;
+      const agentId = options.agentId;
       markStatus({ connected: false, restartPending: false });
       if (pendingRefresh) {
         try {
@@ -540,19 +629,19 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
       try {
         token = await client.ensureToken();
       } catch (err) {
-        log.error("botcord ws token refresh failed", { err: String(err) });
+        log.error("botcord ws token refresh failed", { agentId, err: String(err) });
         markStatus({ lastError: String(err) });
         scheduleReconnect();
         return;
       }
 
       const url = buildHubWebSocketUrl(hubUrl);
-      log.info("botcord ws connecting", { url, agentId: options.agentId });
+      log.info("botcord ws connecting", { url, agentId });
 
       try {
         ws = new wsCtor(url);
       } catch (err) {
-        log.error("botcord ws construct failed", { err: String(err) });
+        log.error("botcord ws construct failed", { agentId, err: String(err) });
         markStatus({ lastError: String(err) });
         scheduleReconnect();
         return;
@@ -597,19 +686,21 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         } else if (msg.type === "heartbeat" || msg.type === "pong") {
           // no-op
         } else if (msg.type === "error" || msg.type === "auth_failed") {
-          log.warn("botcord ws server error", { msg });
+          log.warn("botcord ws server error", { agentId, msg });
         }
       });
 
       ws.on("close", (code: number, reason: Buffer) => {
         const reasonStr = reason?.toString() || "";
-        log.info("botcord ws closed", { code, reason: reasonStr });
+        log.info("botcord ws closed", { agentId, code, reason: reasonStr });
         clearTimers();
         markStatus({ connected: false });
         if (!running) {
+          if (permanentStopping) return;
           if (resolveLoop) {
             const r = resolveLoop;
             resolveLoop = null;
+            rejectLoop = null;
             r();
           }
           return;
@@ -618,6 +709,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
           consecutiveAuthFailures += 1;
           if (consecutiveAuthFailures >= MAX_AUTH_FAILURES) {
             log.error("botcord ws auth failing persistently — giving up reconnects", {
+              agentId,
               failures: consecutiveAuthFailures,
             });
             running = false;
@@ -630,19 +722,20 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
             if (resolveLoop) {
               const r = resolveLoop;
               resolveLoop = null;
+              rejectLoop = null;
               r();
             }
             return;
           }
           pendingRefresh = client
             .refreshToken()
-            .catch((err) => log.error("botcord ws forced refresh failed", { err: String(err) }));
+            .catch((err) => log.error("botcord ws forced refresh failed", { agentId, err: String(err) }));
         }
         scheduleReconnect();
       });
 
       ws.on("error", (err: Error) => {
-        log.warn("botcord ws error", { err: String(err) });
+        log.warn("botcord ws error", { agentId, err: String(err) });
         markStatus({ lastError: String(err) });
       });
     }
@@ -667,6 +760,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
       if (resolveLoop) {
         const r = resolveLoop;
         resolveLoop = null;
+        rejectLoop = null;
         r();
       }
     }

package/src/gateway/log.ts

@@ -1,3 +1,5 @@
+import { formatLogLine } from "../log.js";
+
 /** Structured logger interface used across the gateway core and adapters. */
 export interface GatewayLogger {
   info(msg: string, meta?: Record<string, unknown>): void;
@@ -9,17 +11,12 @@ export interface GatewayLogger {
 type Level = "info" | "warn" | "error" | "debug";
 
 function write(level: Level, msg: string, meta?: Record<string, unknown>): void {
-  const line = JSON.stringify({
-    ts: new Date().toISOString(),
-    level,
-    msg,
-    ...(meta ?? {}),
-  });
+  const line = formatLogLine(level, msg, meta);
   // Always write to stderr so stdout stays clean for NDJSON-style channel output.
   process.stderr.write(line + "\n");
 }
 
-/** Default logger that writes JSON lines to stderr; debug lines gated by BOTCORD_GATEWAY_DEBUG. */
+/** Default logger that writes compact text lines to stderr; debug lines gated by BOTCORD_GATEWAY_DEBUG. */
 export const consoleLogger: GatewayLogger = {
   info: (msg, meta) => write("info", msg, meta),
   warn: (msg, meta) => write("warn", msg, meta),

package/src/log.ts

@@ -18,14 +18,35 @@ function ensureDir(): void {
 
 type Level = "info" | "warn" | "error" | "debug";
 
+function formatValue(value: unknown): string {
+  if (value instanceof Error) return JSON.stringify(value.stack ?? value.message);
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+  if (value === undefined) return "undefined";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return JSON.stringify(String(value));
+  }
+}
+
+export function formatLogLine(
+  level: Level,
+  msg: string,
+  fields: Record<string, unknown> | undefined,
+  date = new Date(),
+): string {
+  const detail = Object.entries(fields ?? {})
+    .map(([key, value]) => `${key}=${formatValue(value)}`)
+    .join(" ");
+  const prefix = `[${level.toUpperCase()}] ${msg}`;
+  const suffix = `ts=${date.toISOString()}`;
+  return detail ? `${prefix} ${detail} ${suffix}` : `${prefix} ${suffix}`;
+}
+
 function write(level: Level, msg: string, fields?: Record<string, unknown>): void {
   ensureDir();
-  const line = JSON.stringify({
-    ts: new Date().toISOString(),
-    level,
-    msg,
-    ...(fields ?? {}),
-  });
+  const line = formatLogLine(level, msg, fields);
   try {
     appendFileSync(LOG_FILE, line + "\n", { mode: 0o600 });
   } catch {

package/src/provision.ts

@@ -1061,7 +1061,7 @@ function localOpenclawAcpDisabled(rawUrl: string): boolean {
   }
 }
 
-async function revokeAgent(
+export async function revokeAgent(
   params: RevokeAgentParams,
   ctx: { gateway: Gateway },
 ): Promise<RevokeAgentResult> {