@botcord/daemon 0.2.62 → 0.2.64

package/src/control-channel.ts

@@ -25,6 +25,7 @@ import {
 
 /** Exponential backoff plan for transient disconnects. */
 const RECONNECT_BACKOFF_MS = [1000, 2000, 4000, 8000, 16000, 30000];
+const RECONNECT_JITTER_RATIO = 0.25;
 /**
  * Keepalive cadence. Has to stay below the smallest idle-timeout in any
  * intermediary on the daemon → Hub WS path. Cloudflare and AWS ALB both
@@ -55,6 +56,11 @@ export function controlSigningInput(
   return jcsCanonicalize(obj) ?? "{}";
 }
 
+function withReconnectJitter(delayMs: number): { delayMs: number; jitterMs: number } {
+  const jitterMs = Math.floor(Math.random() * delayMs * RECONNECT_JITTER_RATIO);
+  return { delayMs: delayMs + jitterMs, jitterMs };
+}
+
 /** Handler invoked for each inbound frame. Return value is the ack payload. */
 export type ControlFrameHandler = (
   frame: ControlFrame,
@@ -110,6 +116,7 @@ export class ControlChannel {
   private readonly seenFrameIds: string[] = [];
   private connectInflight: Promise<void> | null = null;
   private connected = false;
+  private connectionSeq = 0;
 
   constructor(opts: ControlChannelOptions) {
     this.auth = opts.auth;
@@ -220,6 +227,20 @@ export class ControlChannel {
   private async connect(): Promise<void> {
     const record = this.auth.current;
     if (!record) throw new Error("control-channel: no user-auth");
+    const current = this.ws;
+    if (
+      current &&
+      (current.readyState === WebSocket.CONNECTING || current.readyState === WebSocket.OPEN)
+    ) {
+      daemonLog.debug("control-channel connect skipped (socket already active)", {
+        readyState: current.readyState,
+      });
+      return;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
 
     const accessToken = await this.auth.ensureAccessToken();
     const url = buildDaemonWebSocketUrl(
@@ -229,6 +250,7 @@ export class ControlChannel {
     );
     daemonLog.info("control-channel connecting", { url });
 
+    const connectionId = ++this.connectionSeq;
     const ws = new this.webSocketCtor(url, {
       headers: { Authorization: `Bearer ${accessToken}` },
     });
@@ -237,6 +259,15 @@ export class ControlChannel {
     await new Promise<void>((resolve, reject) => {
       const onOpen = (): void => {
         ws.removeListener("error", onError);
+        if (this.stopRequested || this.ws !== ws || connectionId !== this.connectionSeq) {
+          try {
+            ws.close(1000, "stale control-channel connection");
+          } catch {
+            // ignore
+          }
+          resolve();
+          return;
+        }
         this.connected = true;
         this.reconnectAttempts = 0;
         daemonLog.info("control-channel connected", { url });
@@ -245,14 +276,21 @@ export class ControlChannel {
       };
       const onError = (err: Error): void => {
         ws.removeListener("open", onOpen);
+        if (this.ws !== ws || connectionId !== this.connectionSeq) {
+          resolve();
+          return;
+        }
         reject(err);
       };
       ws.once("open", onOpen);
       ws.once("error", onError);
     });
 
-    ws.on("message", (data) => this.onMessage(data));
-    ws.on("close", (code, reason) => this.onClose(code, reason));
+    ws.on("message", (data) => {
+      if (this.ws !== ws || connectionId !== this.connectionSeq) return;
+      void this.onMessage(data);
+    });
+    ws.on("close", (code, reason) => this.onClose(code, reason, ws, connectionId));
     ws.on("error", (err) =>
       daemonLog.warn("control-channel error", {
         error: err instanceof Error ? err.message : String(err),
@@ -292,8 +330,12 @@ export class ControlChannel {
     }
   }
 
-  private onClose(code: number, reason: Buffer): void {
+  private onClose(code: number, reason: Buffer, ws?: WebSocket, connectionId?: number): void {
     const reasonText = reason?.toString() || "";
+    if (ws && (this.ws !== ws || connectionId !== this.connectionSeq)) {
+      daemonLog.debug("control-channel stale close ignored", { code, reason: reasonText });
+      return;
+    }
     this.connected = false;
     this.stopKeepalive();
     this.ws = null;
@@ -314,6 +356,14 @@ export class ControlChannel {
 
   private scheduleReconnect(err?: unknown): void {
     if (this.stopRequested) return;
+    if (this.reconnectTimer) return;
+    const current = this.ws;
+    if (
+      current &&
+      (current.readyState === WebSocket.CONNECTING || current.readyState === WebSocket.OPEN)
+    ) {
+      return;
+    }
     if (err instanceof AuthRefreshRejectedError) {
       this.stopRequested = true;
       daemonLog.warn("control-channel: refresh rejected; halting reconnect (re-login required)", {
@@ -323,20 +373,23 @@ export class ControlChannel {
     }
     const attempt = this.reconnectAttempts;
     this.reconnectAttempts = attempt + 1;
-    const delay = this.backoff[Math.min(attempt, this.backoff.length - 1)];
+    const baseDelayMs = this.backoff[Math.min(attempt, this.backoff.length - 1)];
+    const { delayMs, jitterMs } = withReconnectJitter(baseDelayMs);
     if (err) {
       daemonLog.warn("control-channel reconnect scheduled", {
-        delayMs: delay,
+        delayMs,
+        baseDelayMs,
+        jitterMs,
         error: err instanceof Error ? err.message : String(err),
       });
     } else {
-      daemonLog.info("control-channel reconnect scheduled", { delayMs: delay });
+      daemonLog.info("control-channel reconnect scheduled", { delayMs, baseDelayMs, jitterMs });
     }
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
       if (this.stopRequested) return;
       this.connect().catch((err) => this.scheduleReconnect(err));
-    }, delay);
+    }, delayMs);
   }
 
   private async onMessage(data: WebSocket.RawData): Promise<void> {

package/src/daemon.ts

@@ -518,7 +518,7 @@ export async function startDaemon(opts: DaemonRuntimeOptions): Promise<DaemonHan
     resolveHubUrl,
     transcriptEnabled: resolveTranscriptEnabled(
       process.env.BOTCORD_TRANSCRIPT,
-      opts.config.transcript?.enabled === true,
+      opts.config.transcript?.enabled,
     ),
   });
 

package/src/diagnostics.ts

@@ -1,7 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir, hostname, platform, release, arch } from "node:os";
 import path from "node:path";
 import { Buffer } from "node:buffer";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import { deflateRawSync } from "node:zlib";
 import {
   AUTH_EXPIRED_FLAG_PATH,
@@ -12,6 +14,7 @@ import {
 import {
   CONFIG_FILE_PATH,
   PID_PATH,
+  SESSIONS_PATH,
   SNAPSHOT_PATH,
   loadConfig,
   saveConfig,
@@ -19,6 +22,7 @@ import {
 } from "./config.js";
 import { listDaemonLogFiles, LOG_FILE_PATH, type LogFileEntry } from "./log.js";
 import { listAcpTraceLogFiles, listRuntimeLogFiles } from "./acp-logs.js";
+import { defaultTranscriptRoot } from "./gateway/transcript.js";
 import {
   channelsFromDaemonConfig,
   defaultHttpFetcher,
@@ -38,12 +42,34 @@ import {
 const DIAGNOSTICS_DIR = path.join(homedir(), ".botcord", "diagnostics");
 const MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
 const DEFAULT_ROTATED_LOGS_IN_BUNDLE = 5;
+const require = createRequire(import.meta.url);
+const MODULE_PATH = fileURLToPath(import.meta.url);
+const ENV_ALLOWLIST = new Set([
+  "NODE_ENV",
+  "PATH",
+  "BOTCORD_HUB",
+  "BOTCORD_DAEMON_HOME",
+  "BOTCORD_DAEMON_CONFIG",
+  "BOTCORD_DAEMON_LOG",
+  "BOTCORD_DAEMON_SNAPSHOT_INTERVAL_MS",
+  "BOTCORD_HERMES_AGENT_BIN",
+  "BOTCORD_CLAUDE_CODE_BIN",
+  "BOTCORD_CODEX_BIN",
+  "BOTCORD_GEMINI_BIN",
+  "BOTCORD_DEEPSEEK_TUI_BIN",
+  "BOTCORD_KIMI_CLI_BIN",
+  "OPENCLAW_ACP_URL",
+]);
+const TRANSCRIPT_LOG_DIAGNOSTICS_DEFAULT = 10;
+const TRANSCRIPT_LOG_DIAGNOSTICS_ALL = 50;
+const TRANSCRIPT_LOG_MAX_FILE_BYTES = 2 * 1024 * 1024;
 
 export interface CreateDiagnosticBundleOptions {
   diagnosticsDir?: string;
   logFile?: string;
   configFile?: string;
   snapshotFile?: string;
+  sessionsFile?: string;
   doctor?: { text: string; json: unknown };
   includeAllLogs?: boolean;
 }
@@ -89,6 +115,81 @@ function safeReadText(file: string): string | null {
   }
 }
 
+function readJsonFile(file: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function findDaemonPackageJson(startFile: string): Record<string, unknown> | null {
+  let dir = path.dirname(startFile);
+  for (let i = 0; i < 6; i += 1) {
+    const candidate = path.join(dir, "package.json");
+    const parsed = readJsonFile(candidate);
+    if (parsed?.name === "@botcord/daemon") return parsed;
+    const next = path.dirname(dir);
+    if (next === dir) break;
+    dir = next;
+  }
+  return null;
+}
+
+function readInstalledPackageVersion(packageJsonSpecifier: string): string | null {
+  try {
+    const pkgPath = require.resolve(packageJsonSpecifier);
+    const parsed = readJsonFile(pkgPath);
+    return typeof parsed?.version === "string" ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function daemonRuntimeSummary(): Record<string, unknown> {
+  const pkg = findDaemonPackageJson(MODULE_PATH);
+  const version = typeof pkg?.version === "string" ? pkg.version : null;
+  const startedAtMs = Date.now() - Math.round(process.uptime() * 1000);
+  return {
+    packageName: typeof pkg?.name === "string" ? pkg.name : "@botcord/daemon",
+    version,
+    modulePath: MODULE_PATH,
+    entrypoint: process.argv[1] ?? null,
+    execPath: process.execPath,
+    argv: process.argv.map((arg) => redact(arg)),
+    execArgv: process.execArgv.map((arg) => redact(arg)),
+    cwd: process.cwd(),
+    pid: process.pid,
+    ppid: process.ppid,
+    uptimeSec: Math.round(process.uptime()),
+    startedAt: new Date(startedAtMs).toISOString(),
+    versions: {
+      node: process.version,
+      v8: process.versions.v8,
+      uv: process.versions.uv,
+      openssl: process.versions.openssl,
+    },
+    packages: {
+      "@botcord/daemon": version,
+      "@botcord/cli": readInstalledPackageVersion("@botcord/cli/package.json"),
+      "@botcord/protocol-core": readInstalledPackageVersion("@botcord/protocol-core/package.json"),
+    },
+  };
+}
+
+function safeEnvironmentSummary(): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!value) continue;
+    if (!ENV_ALLOWLIST.has(key) && !key.startsWith("BOTCORD_DAEMON_")) continue;
+    out[key] = redact(value);
+  }
+  return out;
+}
+
 function readUserAuthSummary(): Record<string, unknown> | null {
   const raw = safeReadText(USER_AUTH_PATH);
   if (!raw) return null;
@@ -319,6 +420,55 @@ function bundledLogs(logFile: string, includeAllLogs: boolean): LogFileEntry[] {
   ];
 }
 
+function listTranscriptLogFiles(includeAll: boolean): LogFileEntry[] {
+  const root = defaultTranscriptRoot();
+  const out: LogFileEntry[] = [];
+  collectTranscriptFiles(root, root, out, 5);
+  const limit = includeAll ? TRANSCRIPT_LOG_DIAGNOSTICS_ALL : TRANSCRIPT_LOG_DIAGNOSTICS_DEFAULT;
+  return out
+    .sort((a, b) => b.mtimeMs - a.mtimeMs || b.name.localeCompare(a.name))
+    .slice(0, limit);
+}
+
+function collectTranscriptFiles(
+  root: string,
+  dir: string,
+  out: LogFileEntry[],
+  maxDepth: number,
+): void {
+  if (maxDepth < 0) return;
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const file = path.join(dir, name);
+    try {
+      const st = statSync(file);
+      if (st.isDirectory()) {
+        collectTranscriptFiles(root, file, out, maxDepth - 1);
+      } else if (
+        st.isFile() &&
+        name.endsWith(".jsonl") &&
+        file.includes(`${path.sep}transcripts${path.sep}`) &&
+        st.size <= TRANSCRIPT_LOG_MAX_FILE_BYTES
+      ) {
+        out.push({
+          path: file,
+          name: path.relative(root, file) || name,
+          sizeBytes: st.size,
+          mtimeMs: st.mtimeMs,
+          active: true,
+        });
+      }
+    } catch {
+      // ignore files that disappear while collecting diagnostics
+    }
+  }
+}
+
 export async function createDiagnosticBundle(
   opts: CreateDiagnosticBundleOptions = {},
 ): Promise<DiagnosticBundleResult> {
@@ -329,10 +479,12 @@ export async function createDiagnosticBundle(
   const logFile = opts.logFile ?? LOG_FILE_PATH;
   const configFile = opts.configFile ?? CONFIG_FILE_PATH;
   const snapshotFile = opts.snapshotFile ?? SNAPSHOT_PATH;
+  const sessionsFile = opts.sessionsFile ?? SESSIONS_PATH;
   const includeAllLogs = opts.includeAllLogs === true;
   const logs = bundledLogs(logFile, includeAllLogs);
   const acpLogs = listAcpTraceLogFiles(includeAllLogs);
   const runtimeLogs = listRuntimeLogFiles(includeAllLogs);
+  const transcriptLogs = listTranscriptLogFiles(includeAllLogs);
   mkdirSync(diagnosticsDir, { recursive: true, mode: 0o700 });
 
   const doctor = opts.doctor ?? await buildDoctorEntries();
@@ -343,9 +495,12 @@ export async function createDiagnosticBundle(
     release: release(),
     arch: arch(),
     node: process.version,
+    daemon: daemonRuntimeSummary(),
+    environment: safeEnvironmentSummary(),
     pidPath: PID_PATH,
     pid: process.pid,
     configPath: configFile,
+    sessionsPath: sessionsFile,
     snapshotPath: snapshotFile,
     logPath: logFile,
     logsBundled: logs.map((entry) => ({
@@ -364,6 +519,11 @@ export async function createDiagnosticBundle(
       path: entry.path,
       sizeBytes: entry.sizeBytes,
     })),
+    transcriptLogsBundled: transcriptLogs.map((entry) => ({
+      name: entry.name,
+      path: entry.path,
+      sizeBytes: entry.sizeBytes,
+    })),
     logsBundleMode: includeAllLogs ? "all" : `active_plus_${DEFAULT_ROTATED_LOGS_IN_BUNDLE}_rotated`,
     diagnosticsDir,
     userAuth: readUserAuthSummary(),
@@ -403,6 +563,13 @@ export async function createDiagnosticBundle(
       data: log ?? `no runtime log file at ${entry.path}\n`,
     });
   }
+  for (const entry of transcriptLogs) {
+    const log = safeReadText(entry.path);
+    entries.push({
+      name: `transcripts/${entry.name.split(path.sep).join("/")}`,
+      data: log ?? `no transcript log file at ${entry.path}\n`,
+    });
+  }
   const config = safeReadText(configFile);
   entries.push({
     name: "config.json.redacted",
@@ -413,6 +580,11 @@ export async function createDiagnosticBundle(
     name: "snapshot.json",
     data: snapshot ?? `no snapshot file at ${snapshotFile}\n`,
   });
+  const sessions = safeReadText(sessionsFile);
+  entries.push({
+    name: "sessions.json.redacted",
+    data: sessions ?? `no sessions file at ${sessionsFile}\n`,
+  });
 
   const zip = createZip(entries);
   const out = path.join(diagnosticsDir, filename);

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

@@ -1276,6 +1276,50 @@ describe("Dispatcher", () => {
     expect(blockTypes).toEqual(["system", "tool_use"]);
   });
 
+  it("transcript: records runtime blocks even when channel streaming is disabled", async () => {
+    const blocks: StreamBlock[] = [
+      {
+        raw: {
+          params: {
+            update: {
+              sessionUpdate: "tool_call",
+              toolCall: { name: "botcord_send", rawInput: { text: "hello" } },
+            },
+          },
+        },
+        kind: "tool_use",
+        seq: 7,
+      },
+    ];
+    const runtime = new FakeRuntime({ blocks, reply: "ok", newSessionId: "sid" });
+    const channel = new FakeChannel();
+    const records: import("../transcript.js").TranscriptRecord[] = [];
+    const { store, dir } = await makeStore();
+    tempDirs.push(dir);
+    const channels = new Map<string, ChannelAdapter>([[channel.id, channel]]);
+    const dispatcher = new Dispatcher({
+      config: baseConfig(),
+      channels,
+      runtime: () => runtime,
+      sessionStore: store,
+      log: silentLogger(),
+      transcript: { enabled: true, rootDir: dir, write: (rec) => records.push(rec) },
+    });
+
+    await dispatcher.handle(
+      makeEnvelope({ trace: { id: "tr", streamable: false } }),
+    );
+
+    expect(channel.streams).toHaveLength(0);
+    const block = records.find((r) => r.kind === "block");
+    expect(block).toMatchObject({
+      kind: "block",
+      blockType: "tool_use",
+      seq: 7,
+      summary: { type: "tool_use", name: "botcord_send" },
+    });
+  });
+
   it("runtime throws: sends error reply, does not write session", async () => {
     const runtime = new FakeRuntime({ throwError: "boom" });
     const channel = new FakeChannel();

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

@@ -1,5 +1,5 @@
-import { mkdtemp, readFile, rm } from "node:fs/promises";
-import { existsSync, statSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync, statSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -7,7 +7,9 @@ import { Dispatcher, type RuntimeFactory } from "../dispatcher.js";
 import { SessionStore } from "../session-store.js";
 import {
   createTranscriptWriter,
+  cleanupTranscriptFiles,
   resolveTranscriptEnabled,
+  TRANSCRIPT_RETENTION_MS,
   TRANSCRIPT_TEXT_LIMIT,
   truncateTextField,
   type TranscriptRecord,
@@ -239,6 +241,10 @@ describe("resolveTranscriptEnabled", () => {
     expect(resolveTranscriptEnabled("yes", true)).toBe(true);
     expect(resolveTranscriptEnabled("yes", false)).toBe(false);
   });
+  it("defaults on when env and config are both unset", () => {
+    expect(resolveTranscriptEnabled(undefined, undefined)).toBe(true);
+    expect(resolveTranscriptEnabled("yes", undefined)).toBe(true);
+  });
 });
 
 describe("truncateTextField", () => {
@@ -460,6 +466,25 @@ describe("Dispatcher transcript integration", () => {
     expect(files).toContain("_default.jsonl");
   });
 
+  it("cleans transcript files older than the retention window", async () => {
+    const tmp = await mkdtemp(path.join(tmpdir(), "transcript-clean-"));
+    cleanups.push(() => rm(tmp, { recursive: true, force: true }));
+    const oldFile = transcriptFilePath(tmp, "ag_me", "rm_old", null);
+    const freshFile = transcriptFilePath(tmp, "ag_me", "rm_fresh", null);
+    await mkdir(path.dirname(oldFile), { recursive: true });
+    await mkdir(path.dirname(freshFile), { recursive: true });
+    await writeFile(oldFile, "{}\n", { mode: 0o600 });
+    await writeFile(freshFile, "{}\n", { mode: 0o600 });
+    const oldDate = new Date(Date.now() - TRANSCRIPT_RETENTION_MS - 60_000);
+    utimesSync(oldFile, oldDate, oldDate);
+
+    const removed = cleanupTranscriptFiles(tmp, Date.now() - TRANSCRIPT_RETENTION_MS);
+
+    expect(removed).toBe(1);
+    expect(existsSync(oldFile)).toBe(false);
+    expect(existsSync(freshFile)).toBe(true);
+  });
+
   it("disabled writer does not create files", async () => {
     const tmp = await mkdtemp(path.join(tmpdir(), "transcript-off-"));
     cleanups.push(() => rm(tmp, { recursive: true, force: true }));

package/src/gateway/channels/botcord.ts

@@ -25,6 +25,7 @@ import { sanitizeUntrustedContent } from "./sanitize.js";
 import { revokeAgent } from "../../provision.js";
 
 const RECONNECT_BACKOFF = [1000, 2000, 4000, 8000, 16000, 30000];
+const RECONNECT_JITTER_RATIO = 0.25;
 const KEEPALIVE_INTERVAL = 20_000;
 const MAX_AUTH_FAILURES = 5;
 const SEEN_MESSAGES_CAP = 500;
@@ -33,6 +34,11 @@ const DM_ROOM_PREFIX = "rm_dm_";
 const INBOX_POLL_LIMIT = 50;
 const CHANNEL_PERMANENT_STOP = "channel_permanent_stop";
 
+function withReconnectJitter(delayMs: number): { delayMs: number; jitterMs: number } {
+  const jitterMs = Math.floor(Math.random() * delayMs * RECONNECT_JITTER_RATIO);
+  return { delayMs: delayMs + jitterMs, jitterMs };
+}
+
 type InboxDrainTrigger =
   | "ws_auth_ok"
   | "ws_inbox_update"
@@ -477,6 +483,7 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
     let reconnectTimer: NodeJS.Timeout | null = null;
     let keepaliveTimer: NodeJS.Timeout | null = null;
     let reconnectAttempt = 0;
+    let connectionSeq = 0;
     let consecutiveAuthFailures = 0;
     let running = true;
     let permanentStopping = false;
@@ -603,23 +610,36 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
 
     function scheduleReconnect() {
       if (!running) return;
-      const delay =
+      if (reconnectTimer) return;
+      if (ws && (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)) {
+        return;
+      }
+      const baseDelayMs =
         RECONNECT_BACKOFF[Math.min(reconnectAttempt, RECONNECT_BACKOFF.length - 1)];
+      const { delayMs, jitterMs } = withReconnectJitter(baseDelayMs);
       reconnectAttempt += 1;
       markStatus({
         connected: false,
         restartPending: true,
         reconnectAttempts: reconnectAttempt,
       });
-      log.info("botcord ws reconnect scheduled", { delayMs: delay, attempt: reconnectAttempt });
+      log.info("botcord ws reconnect scheduled", {
+        delayMs,
+        baseDelayMs,
+        jitterMs,
+        attempt: reconnectAttempt,
+      });
       reconnectTimer = setTimeout(() => {
         reconnectTimer = null;
         void connect();
-      }, delay);
+      }, delayMs);
     }
 
     async function connect() {
       if (!running) return;
+      if (ws && (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)) {
+        return;
+      }
       const agentId = options.agentId;
       markStatus({ connected: false, restartPending: false });
       if (pendingRefresh) {
@@ -644,8 +664,11 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
       const url = buildHubWebSocketUrl(hubUrl);
       log.info("botcord ws connecting", { url, agentId });
 
+      const connectionId = ++connectionSeq;
+      let socket: WebSocket;
       try {
-        ws = new wsCtor(url);
+        socket = new wsCtor(url);
+        ws = socket;
       } catch (err) {
         log.error("botcord ws construct failed", { agentId, err: String(err) });
         markStatus({ lastError: String(err) });
@@ -653,11 +676,20 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         return;
       }
 
-      ws.on("open", () => {
-        ws!.send(JSON.stringify({ type: "auth", token }));
+      socket.on("open", () => {
+        if (!running || ws !== socket || connectionId !== connectionSeq) {
+          try {
+            socket.close();
+          } catch {
+            // ignore
+          }
+          return;
+        }
+        socket.send(JSON.stringify({ type: "auth", token }));
       });
 
-      ws.on("message", (data: WebSocket.RawData) => {
+      socket.on("message", (data: WebSocket.RawData) => {
+        if (ws !== socket || connectionId !== connectionSeq) return;
         let msg: { type?: string; agent_id?: string } | null = null;
         try {
           msg = JSON.parse(String(data));
@@ -677,10 +709,11 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
           });
           log.info("botcord ws authenticated", { agentId: msg.agent_id });
           void fireInbox("ws_auth_ok");
+          if (keepaliveTimer) clearInterval(keepaliveTimer);
           keepaliveTimer = setInterval(() => {
-            if (ws && ws.readyState === WebSocket.OPEN) {
+            if (ws === socket && socket.readyState === WebSocket.OPEN) {
               try {
-                ws.send(JSON.stringify({ type: "ping" }));
+                socket.send(JSON.stringify({ type: "ping" }));
               } catch {
                 // ignore
               }
@@ -696,10 +729,15 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         }
       });
 
-      ws.on("close", (code: number, reason: Buffer) => {
+      socket.on("close", (code: number, reason: Buffer) => {
         const reasonStr = reason?.toString() || "";
+        if (ws !== socket || connectionId !== connectionSeq) {
+          log.debug("botcord ws stale close ignored", { agentId, code, reason: reasonStr });
+          return;
+        }
         log.info("botcord ws closed", { agentId, code, reason: reasonStr });
         clearTimers();
+        ws = null;
         markStatus({ connected: false });
         if (!running) {
           if (permanentStopping) return;
@@ -740,7 +778,8 @@ export function createBotCordChannel(options: BotCordChannelOptions): ChannelAda
         scheduleReconnect();
       });
 
-      ws.on("error", (err: Error) => {
+      socket.on("error", (err: Error) => {
+        if (ws !== socket || connectionId !== connectionSeq) return;
         log.warn("botcord ws error", { agentId, err: String(err) });
         markStatus({ lastError: String(err) });
       });