openclaw-channel-dmwork 0.5.11 → 0.5.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-channel-dmwork",
-  "version": "0.5.11",
+  "version": "0.5.12",
   "description": "DMWork channel plugin for OpenClaw via WuKongIM WebSocket",
   "main": "index.ts",
   "type": "module",

package/src/bug-repro.test.ts

@@ -0,0 +1,390 @@
+/**
+ * Bug fix verification tests for WebSocket reconnect v2 (Issue #139)
+ *
+ * These tests verify that three bugs have been FIXED:
+ *   Bug A: Exponential backoff now works (reconnectAttempts not reset prematurely)
+ *   Bug B: Kicked bots reconnect even during cooldown window
+ *   Bug C: Rapid silent disconnects now trigger onError for token refresh
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// Track mock WS instances created during tests
+const mockWsInstances: any[] = [];
+
+vi.mock("ws", () => {
+  class MockWS {
+    static OPEN = 1;
+    binaryType = "arraybuffer";
+    readyState = 1;
+    private handlers = new Map<string, Function[]>();
+
+    constructor(public url: string) {
+      (globalThis as any).__mockWsInstances?.push(this);
+    }
+
+    on(event: string, handler: Function) {
+      if (!this.handlers.has(event)) this.handlers.set(event, []);
+      this.handlers.get(event)!.push(handler);
+    }
+
+    send = vi.fn();
+
+    close() {
+      this.readyState = 3; // CLOSED
+      queueMicrotask(() => this.emit("close"));
+    }
+
+    emit(event: string, ...args: any[]) {
+      const handlers = this.handlers.get(event);
+      if (handlers) {
+        for (const h of handlers) h(...args);
+      }
+    }
+  }
+
+  return { default: MockWS, WebSocket: MockWS };
+});
+
+vi.mock("curve25519-js", () => ({
+  generateKeyPair: () => ({
+    private: new Uint8Array(32),
+    public: new Uint8Array(32),
+  }),
+  sharedKey: () => new Uint8Array(32),
+}));
+
+import { WKSocket } from "./socket.js";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Build a minimal CONNACK packet with reasonCode=1 (success) */
+function buildConnackSuccess(): ArrayBuffer {
+  const serverVersion = 4;
+  const reasonCode = 1; // success
+  const serverKey = Buffer.from(new Uint8Array(32)).toString("base64");
+  const salt = "1234567890123456";
+
+  const body: number[] = [];
+  body.push(serverVersion);
+  for (let i = 0; i < 8; i++) body.push(0); // timeDiff
+  body.push(reasonCode);
+  const keyBytes = [...Buffer.from(serverKey)];
+  body.push((keyBytes.length >> 8) & 0xff, keyBytes.length & 0xff);
+  body.push(...keyBytes);
+  const saltBytes = [...Buffer.from(salt)];
+  body.push((saltBytes.length >> 8) & 0xff, saltBytes.length & 0xff);
+  body.push(...saltBytes);
+  for (let i = 0; i < 8; i++) body.push(0); // nodeId
+
+  const header = (2 << 4) | 1; // CONNACK with hasServerVersion
+  const packet = new Uint8Array([header, body.length, ...body]);
+  return packet.buffer;
+}
+
+/** Build a CONNACK packet with reasonCode=0 (kicked) */
+function buildConnackKicked(): ArrayBuffer {
+  const serverVersion = 4;
+  const reasonCode = 0; // kicked
+
+  const body: number[] = [];
+  body.push(serverVersion);
+  for (let i = 0; i < 8; i++) body.push(0); // timeDiff
+  body.push(reasonCode);
+  // serverKey (empty)
+  body.push(0, 0);
+  // salt (empty)
+  body.push(0, 0);
+  for (let i = 0; i < 8; i++) body.push(0); // nodeId
+
+  const header = (2 << 4) | 1;
+  const packet = new Uint8Array([header, body.length, ...body]);
+  return packet.buffer;
+}
+
+// ─── Test Suites ────────────────────────────────────────────────────────────
+
+describe("Bug A fix: Exponential backoff grows correctly", () => {
+  let setTimeoutCalls: { fn: Function; delay: number }[];
+  let originalSetTimeout: typeof setTimeout;
+  let dateNowSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    mockWsInstances.length = 0;
+    (globalThis as any).__mockWsInstances = mockWsInstances;
+    setTimeoutCalls = [];
+    originalSetTimeout = global.setTimeout;
+    global.setTimeout = vi.fn((fn: Function, delay?: number) => {
+      setTimeoutCalls.push({ fn, delay: delay ?? 0 });
+      return 999 as any;
+    }) as any;
+  });
+
+  afterEach(() => {
+    global.setTimeout = originalSetTimeout;
+    dateNowSpy?.mockRestore();
+    delete (globalThis as any).__mockWsInstances;
+    vi.restoreAllMocks();
+  });
+
+  it("delays should GROW after 5 connect→CONNACK→close cycles", () => {
+    /**
+     * With the fix, reconnectAttempts only resets after the 30s stable timer
+     * fires (which requires the connection to stay up for 30s). Connections
+     * that live <30s keep the backoff counter, so delays grow exponentially.
+     *
+     * We mock Date.now so each connection appears to last 6s (>5s threshold)
+     * to isolate Bug A from Bug C's rapid-disconnect detection.
+     */
+    let now = 10000;
+    dateNowSpy = vi.spyOn(Date, "now").mockImplementation(() => now);
+
+    const socket = new WKSocket({
+      wsUrl: "ws://test:5200",
+      uid: "bot1",
+      token: "tok1",
+      onMessage: vi.fn(),
+      onConnected: vi.fn(),
+      onDisconnected: vi.fn(),
+    });
+
+    const reconnectDelays: number[] = [];
+
+    for (let cycle = 0; cycle < 5; cycle++) {
+      socket.connect();
+      const ws = mockWsInstances[mockWsInstances.length - 1];
+      ws.emit("open");
+
+      // CONNACK success → sets lastConnectTime = now, starts stable timer
+      ws.emit("message", buildConnackSuccess());
+
+      // Advance time by 6s (above 5s rapid-disconnect threshold,
+      // but well below the 30s stable timer)
+      now += 6000;
+
+      setTimeoutCalls = [];
+      ws.emit("close");
+
+      // The only setTimeout from the close handler is scheduleReconnect
+      if (setTimeoutCalls.length > 0) {
+        reconnectDelays.push(setTimeoutCalls[0].delay);
+      }
+    }
+
+    // All 5 cycles should have produced reconnect delays
+    expect(reconnectDelays).toHaveLength(5);
+
+    // Delays should strictly increase (exponential backoff working)
+    for (let i = 1; i < reconnectDelays.length; i++) {
+      expect(reconnectDelays[i]).toBeGreaterThan(reconnectDelays[i - 1]);
+    }
+
+    // First delay ~3000ms (base), with ±25% jitter → [2250, 3750]
+    expect(reconnectDelays[0]).toBeGreaterThanOrEqual(2250);
+    expect(reconnectDelays[0]).toBeLessThanOrEqual(4500);
+
+    // Last delay should be much larger (~48000ms at attempt 4)
+    expect(reconnectDelays[4]).toBeGreaterThan(20000);
+
+    socket.disconnect();
+  });
+});
+
+
+describe("Bug B fix: Kicked during cooldown still reconnects", () => {
+  it("channel.ts onError handler reconnects even when cooldown is active", () => {
+    /**
+     * With the fix, the else branch in channel.ts onError reconnects the
+     * bot with current credentials when cooldown is active, instead of
+     * doing nothing and letting the bot die permanently.
+     */
+    let lastTokenRefreshAt = 0;
+    const TOKEN_REFRESH_COOLDOWN_MS = 60_000;
+    let isRefreshingToken = false;
+    let stopped = false;
+    let tokenRefreshCount = 0;
+    let reconnectCount = 0;
+
+    // Simulate the FIXED onError handler from channel.ts
+    function onError(err: Error) {
+      const cooldownElapsed = Date.now() - lastTokenRefreshAt > TOKEN_REFRESH_COOLDOWN_MS;
+      if (cooldownElapsed && !isRefreshingToken && !stopped &&
+          (err.message.includes("Kicked") || err.message.includes("Connect failed"))) {
+        isRefreshingToken = true;
+        lastTokenRefreshAt = Date.now();
+        tokenRefreshCount++;
+        // Would do: socket.disconnect() + socket.updateCredentials() + socket.connect()
+        reconnectCount++;
+        isRefreshingToken = false;
+      } else if (!isRefreshingToken && !stopped &&
+          (err.message.includes("Kicked") || err.message.includes("Connect failed"))) {
+        // FIX: Cooldown active — skip token refresh but still reconnect
+        // Would do: socket.disconnect() + socket.connect()
+        reconnectCount++;
+      }
+    }
+
+    // First kick — cooldown not active yet, full refresh happens
+    onError(new Error("Kicked by server"));
+    expect(tokenRefreshCount).toBe(1);
+    expect(reconnectCount).toBe(1);
+
+    // Second kick — within 60s cooldown
+    onError(new Error("Kicked by server"));
+
+    // FIX VERIFIED: reconnect still happens (via else branch), just no token refresh
+    expect(tokenRefreshCount).toBe(1); // no new refresh (cooldown active)
+    expect(reconnectCount).toBe(2);    // reconnect DID happen!
+  });
+
+  it("socket reconnects after channel.ts calls disconnect+connect on kick", () => {
+    /**
+     * When CONNACK returns kicked (reasonCode=0), needReconnect is set to false
+     * and the close event won't trigger scheduleReconnect. But channel.ts can
+     * call socket.disconnect() + socket.connect() to revive the bot.
+     */
+    const originalSetTimeout = global.setTimeout;
+    const setTimeoutCalls: { fn: Function; delay: number }[] = [];
+    global.setTimeout = vi.fn((fn: Function, delay?: number) => {
+      setTimeoutCalls.push({ fn, delay: delay ?? 0 });
+      return 999 as any;
+    }) as any;
+
+    mockWsInstances.length = 0;
+    (globalThis as any).__mockWsInstances = mockWsInstances;
+
+    const onError = vi.fn();
+    const socket = new WKSocket({
+      wsUrl: "ws://test:5200",
+      uid: "bot1",
+      token: "tok1",
+      onMessage: vi.fn(),
+      onError,
+    });
+
+    // Initial connection → kicked
+    socket.connect();
+    const ws1 = mockWsInstances[0];
+    ws1.emit("open");
+    ws1.emit("message", buildConnackKicked());
+
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({
+      message: "Kicked by server",
+    }));
+
+    // needReconnect is false after kick, close won't trigger scheduleReconnect
+    setTimeoutCalls.length = 0;
+    ws1.emit("close");
+    expect(setTimeoutCalls.length).toBe(0);
+
+    // FIX: channel.ts calls disconnect + connect → bot reconnects
+    socket.disconnect();
+    socket.connect();
+
+    // Verify a new WebSocket was created (bot is alive!)
+    expect(mockWsInstances.length).toBeGreaterThan(1);
+    const ws2 = mockWsInstances[mockWsInstances.length - 1];
+    expect(ws2).not.toBe(ws1);
+
+    socket.disconnect();
+    global.setTimeout = originalSetTimeout;
+    delete (globalThis as any).__mockWsInstances;
+    vi.restoreAllMocks();
+  });
+});
+
+
+describe("Bug C fix: Rapid silent disconnects trigger onError", () => {
+  it("onError fires after 3 consecutive rapid disconnects", () => {
+    /**
+     * With the fix, the close handler tracks rapid disconnects (connections
+     * lasting <5s). After 3 consecutive rapid disconnects, it calls onError
+     * with "Connect failed: rapid disconnect detected" so channel.ts can
+     * refresh the token.
+     */
+    const originalSetTimeout = global.setTimeout;
+    global.setTimeout = vi.fn((fn: Function, delay?: number) => {
+      return 999 as any;
+    }) as any;
+
+    mockWsInstances.length = 0;
+    (globalThis as any).__mockWsInstances = mockWsInstances;
+
+    const onError = vi.fn();
+    const socket = new WKSocket({
+      wsUrl: "ws://test:5200",
+      uid: "bot1",
+      token: "tok1",
+      onMessage: vi.fn(),
+      onError,
+      onConnected: vi.fn(),
+      onDisconnected: vi.fn(),
+    });
+
+    // Simulate 3 rapid connect→CONNACK→immediate-close cycles
+    // (connection lasting <5s each time, simulating server restart)
+    for (let i = 0; i < 3; i++) {
+      socket.connect();
+      const ws = mockWsInstances[mockWsInstances.length - 1];
+      ws.emit("open");
+      ws.emit("message", buildConnackSuccess());
+      // Connection closes immediately (server restart, no Kicked packet)
+      ws.emit("close");
+    }
+
+    // FIX VERIFIED: onError IS called after 3 rapid disconnects
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({
+      message: "Connect failed: rapid disconnect detected",
+    }));
+
+    socket.disconnect();
+    global.setTimeout = originalSetTimeout;
+    delete (globalThis as any).__mockWsInstances;
+    vi.restoreAllMocks();
+  });
+
+  it("rapid-disconnect loop with stale token triggers onError for refresh", () => {
+    /**
+     * Simulates the production scenario: server restarts, bot reconnects with
+     * stale token, server silently closes again. After 3 such cycles, onError
+     * fires so channel.ts can refresh the token.
+     */
+    const originalSetTimeout = global.setTimeout;
+    global.setTimeout = vi.fn((fn: Function, delay?: number) => {
+      return 999 as any;
+    }) as any;
+
+    mockWsInstances.length = 0;
+    (globalThis as any).__mockWsInstances = mockWsInstances;
+
+    const onError = vi.fn();
+    const socket = new WKSocket({
+      wsUrl: "ws://test:5200",
+      uid: "bot1",
+      token: "stale-token",
+      onMessage: vi.fn(),
+      onError,
+    });
+
+    // 3 rapid connect→close cycles (simulating stale token scenario)
+    for (let i = 0; i < 3; i++) {
+      socket.connect();
+      const ws = mockWsInstances[mockWsInstances.length - 1];
+      ws.emit("open");
+      ws.emit("message", buildConnackSuccess());
+      ws.emit("close");
+    }
+
+    // FIX VERIFIED: After 3 short-lived connections, onError fires
+    // This allows channel.ts to refresh the token
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({
+      message: "Connect failed: rapid disconnect detected",
+    }));
+
+    socket.disconnect();
+    global.setTimeout = originalSetTimeout;
+    delete (globalThis as any).__mockWsInstances;
+    vi.restoreAllMocks();
+  });
+});

package/src/channel.ts

@@ -640,13 +640,18 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
             botToken: account.config.botToken!,
           }).then(() => {
             consecutiveHeartbeatFailures = 0; // Reset on success
-          }).catch((err) => {
+          }).catch(async (err) => {
             consecutiveHeartbeatFailures++;
-            log?.error?.(`dmwork: heartbeat failed (${consecutiveHeartbeatFailures}/${MAX_HEARTBEAT_FAILURES}): ${String(err)}`);
+            log?.error?.(`dmwork: [${account.accountId}] heartbeat failed (${consecutiveHeartbeatFailures}/${MAX_HEARTBEAT_FAILURES}): ${String(err)}`);
             if (consecutiveHeartbeatFailures >= MAX_HEARTBEAT_FAILURES && !stopped) {
-              log?.warn?.("dmwork: too many heartbeat failures, triggering reconnect...");
+              log?.warn?.(`dmwork: [${account.accountId}] too many heartbeat failures, triggering reconnect...`);
               consecutiveHeartbeatFailures = 0;
-              socket.disconnect();
+              if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+              const backoffMs = 3000 + Math.floor(Math.random() * 2000);
+              await new Promise(r => setTimeout(r, backoffMs));
+              if (stopped) return;
+              await socket.disconnectAndWait();
+              socket.stopReconnectTimer();
               socket.connect();
             }
           });
@@ -670,7 +675,10 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
       const TOKEN_REFRESH_COOLDOWN_MS = 60_000; // 60 seconds
       let isRefreshingToken = false; // Guard against concurrent refreshes (#43)
 
-      // 5b. Heartbeat failure tracking — reconnect after consecutive failures (#42)
+      // 5b. Cooldown reconnect timer — deduplicate to prevent self-kick storms (#139)
+      let cooldownReconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+      // 5c. Heartbeat failure tracking — reconnect after consecutive failures (#42)
       let consecutiveHeartbeatFailures = 0;
       const MAX_HEARTBEAT_FAILURES = 3;
 
@@ -740,18 +748,20 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
         },
 
         onConnected: () => {
-          log?.info?.(`dmwork: WebSocket connected to ${wsUrl}`);
+          log?.info?.(`dmwork: [${account.accountId}] WebSocket connected to ${wsUrl}`);
           statusSink({ lastError: null });
+          consecutiveHeartbeatFailures = 0;
           startHeartbeat();
         },
 
         onDisconnected: () => {
-          log?.warn?.("dmwork: WebSocket disconnected, will reconnect...");
+          log?.warn?.(`dmwork: [${account.accountId}] WebSocket disconnected, will reconnect...`);
+          if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
           statusSink({ lastError: "disconnected" });
         },
 
         onError: async (err: Error) => {
-          log?.error?.(`dmwork: WebSocket error: ${err.message}`);
+          log?.error?.(`dmwork: [${account.accountId}] WebSocket error: ${err.message}`);
           statusSink({ lastError: err.message });
 
           // If kicked or connect failed, try refreshing the IM token with a cooldown
@@ -762,30 +772,49 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
               (err.message.includes("Kicked") || err.message.includes("Connect failed"))) {
             isRefreshingToken = true;
             lastTokenRefreshAt = Date.now();
-            log?.warn?.("dmwork: connection rejected — refreshing IM token...");
+            log?.warn?.(`dmwork: [${account.accountId}] connection rejected — refreshing IM token...`);
             try {
+              await socket.disconnectAndWait();
               const fresh = await registerBot({
                 apiUrl: account.config.apiUrl,
                 botToken: account.config.botToken!,
                 forceRefresh: true,
               });
               credentials = fresh;
-              log?.info?.("dmwork: got fresh IM token, reconnecting WS...");
-              socket.disconnect();
+              log?.info?.(`dmwork: [${account.accountId}] got fresh IM token, reconnecting WS...`);
               socket.updateCredentials(fresh.robot_id, fresh.im_token);
               // Stagger reconnect to avoid thundering herd when multiple bots
               // refresh tokens simultaneously after server-wide token expiry
               const staggerMs = Math.floor(Math.random() * 5000);
-              log?.info?.(`dmwork: staggering reconnect by ${staggerMs}ms`);
+              log?.info?.(`dmwork: [${account.accountId}] staggering reconnect by ${staggerMs}ms`);
               await new Promise(r => setTimeout(r, staggerMs));
               if (stopped) return; // account was stopped during stagger delay
               socket.connect();
             } catch (refreshErr) {
-              log?.error?.(`dmwork: token refresh failed: ${String(refreshErr)}`);
+              log?.error?.(`dmwork: [${account.accountId}] token refresh failed: ${String(refreshErr)}`);
               // Keep cooldown active even on failure to prevent rapid retry hammering
             } finally {
               isRefreshingToken = false;
             }
+          } else if (!isRefreshingToken && !stopped &&
+              (err.message.includes("Kicked") || err.message.includes("Connect failed"))) {
+            // Cooldown active — skip token refresh but still reconnect with current credentials.
+            // Deduplicate: clear any pending cooldown reconnect timer to prevent self-kick storms
+            // where multiple setTimeout callbacks fire simultaneously, each calling connect(),
+            // causing the same bot to have multiple WS connections that kick each other (#139).
+            if (cooldownReconnectTimer) {
+              clearTimeout(cooldownReconnectTimer);
+            }
+            log?.warn?.(`dmwork: [${account.accountId}] cooldown active, scheduling reconnect with current credentials...`);
+            const backoffMs = 5000 + Math.floor(Math.random() * 5000);
+            cooldownReconnectTimer = setTimeout(async () => {
+              cooldownReconnectTimer = null;
+              if (!stopped) {
+                await socket.disconnectAndWait();
+                socket.stopReconnectTimer();
+                socket.connect();
+              }
+            }, backoffMs);
           }
         },
       });
@@ -799,6 +828,7 @@ export const dmworkPlugin: ChannelPlugin<ResolvedDmworkAccount> = {
           stopped = true;
           socket.disconnect();
           if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+          if (cooldownReconnectTimer) { clearTimeout(cooldownReconnectTimer); cooldownReconnectTimer = null; }
           ctx.setStatus({
             accountId: account.accountId,
             running: false,

package/src/reconnect-fixes.test.ts

@@ -0,0 +1,541 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// Track mock WS instances created during tests
+const mockWsInstances: any[] = [];
+
+// Mock ws module
+vi.mock("ws", () => {
+  class MockWS {
+    static OPEN = 1;
+    binaryType = "arraybuffer";
+    readyState = 1;
+    private handlers = new Map<string, Function[]>();
+
+    constructor(public url: string) {
+      (globalThis as any).__mockWsInstances?.push(this);
+    }
+
+    on(event: string, handler: Function) {
+      if (!this.handlers.has(event)) this.handlers.set(event, []);
+      this.handlers.get(event)!.push(handler);
+    }
+
+    send = vi.fn();
+
+    close() {
+      queueMicrotask(() => this.emit("close"));
+    }
+
+    terminate() {
+      queueMicrotask(() => this.emit("close"));
+    }
+
+    emit(event: string, ...args: any[]) {
+      const handlers = this.handlers.get(event);
+      if (handlers) {
+        for (const h of handlers) h(...args);
+      }
+    }
+  }
+
+  return { default: MockWS, WebSocket: MockWS };
+});
+
+// Mock curve25519-js to avoid real crypto in tests
+vi.mock("curve25519-js", () => ({
+  generateKeyPair: () => ({
+    private: new Uint8Array(32),
+    public: new Uint8Array(32),
+  }),
+  sharedKey: () => new Uint8Array(32),
+}));
+
+import { WKSocket } from "./socket.js";
+
+// Helper to build a CONNACK packet
+function buildConnackPacket(reasonCode: number): ArrayBuffer {
+  const serverVersion = 4;
+  const serverKey = Buffer.from(new Uint8Array(32)).toString("base64");
+  const salt = "1234567890123456";
+
+  const body: number[] = [];
+  body.push(serverVersion);
+  for (let i = 0; i < 8; i++) body.push(0); // timeDiff
+  body.push(reasonCode);
+  const keyBytes = [...Buffer.from(serverKey)];
+  body.push((keyBytes.length >> 8) & 0xff, keyBytes.length & 0xff);
+  body.push(...keyBytes);
+  const saltBytes = [...Buffer.from(salt)];
+  body.push((saltBytes.length >> 8) & 0xff, saltBytes.length & 0xff);
+  body.push(...saltBytes);
+  for (let i = 0; i < 8; i++) body.push(0); // nodeId
+
+  const header = (2 << 4) | 1; // CONNACK with hasServerVersion
+  const packet = new Uint8Array([header, body.length, ...body]);
+  return packet.buffer;
+}
+
+// Helper to build a DISCONNECT packet
+function buildDisconnectPacket(reasonCode = 0, reason = "kicked"): ArrayBuffer {
+  const body: number[] = [];
+  body.push(reasonCode);
+  // Write reason string (length-prefixed)
+  const reasonBytes = [...Buffer.from(reason)];
+  body.push((reasonBytes.length >> 8) & 0xff, reasonBytes.length & 0xff);
+  body.push(...reasonBytes);
+
+  const header = (9 << 4) | 0; // DISCONNECT
+  const packet = new Uint8Array([header, body.length, ...body]);
+  return packet.buffer;
+}
+
+function createSocket(overrides: Partial<ConstructorParameters<typeof WKSocket>[0]> = {}) {
+  return new WKSocket({
+    wsUrl: "ws://test:5200",
+    uid: "bot1",
+    token: "tok1",
+    onMessage: vi.fn(),
+    ...overrides,
+  });
+}
+
+describe("reconnect fixes", () => {
+  let originalSetTimeout: typeof setTimeout;
+  let setTimeoutCalls: { fn: Function; delay: number }[];
+
+  beforeEach(() => {
+    mockWsInstances.length = 0;
+    (globalThis as any).__mockWsInstances = mockWsInstances;
+    setTimeoutCalls = [];
+    originalSetTimeout = global.setTimeout;
+
+    global.setTimeout = vi.fn((fn: Function, delay?: number) => {
+      setTimeoutCalls.push({ fn, delay: delay ?? 0 });
+      return 999 as any;
+    }) as any;
+  });
+
+  afterEach(() => {
+    global.setTimeout = originalSetTimeout;
+    delete (globalThis as any).__mockWsInstances;
+    vi.restoreAllMocks();
+  });
+
+  // ─── Fix #1: Stale socket guards ──────────────────────────────────────
+
+  describe("#1 — stale socket guards", () => {
+    it("should ignore message events from a previous WebSocket instance", () => {
+      const onMessage = vi.fn();
+      const socket = createSocket({ onMessage });
+      socket.connect();
+
+      const oldWs = mockWsInstances[0];
+
+      // Simulate open + CONNACK on old WS so AES keys are set
+      oldWs.emit("open");
+      oldWs.emit("message", buildConnackPacket(1));
+
+      // Disconnect and reconnect — creates a new WS instance
+      socket.disconnect();
+      socket.connect();
+      const newWs = mockWsInstances[1];
+      expect(newWs).toBeDefined();
+
+      // Fire message on the OLD WebSocket — should be ignored due to stale guard
+      const callsBefore = onMessage.mock.calls.length;
+      oldWs.emit("message", buildConnackPacket(1));
+      expect(onMessage.mock.calls.length).toBe(callsBefore);
+    });
+
+    it("should ignore open events from a previous WebSocket instance", () => {
+      const socket = createSocket();
+      socket.connect();
+
+      const oldWs = mockWsInstances[0];
+
+      socket.disconnect();
+      socket.connect();
+      const newWs = mockWsInstances[1];
+
+      // Fire open on old WS — should not send CONNECT packet on old WS
+      const sendsBefore = oldWs.send.mock.calls.length;
+      oldWs.emit("open");
+      expect(oldWs.send.mock.calls.length).toBe(sendsBefore);
+    });
+
+    it("should ignore error events from a previous WebSocket instance", () => {
+      const socket = createSocket();
+      socket.connect();
+
+      const oldWs = mockWsInstances[0];
+
+      socket.disconnect();
+      socket.connect();
+
+      // Fire error on old WS — should not crash or affect new WS
+      expect(() => oldWs.emit("error", new Error("stale error"))).not.toThrow();
+    });
+  });
+
+  // ─── Fix #2: CONNACK=0 closes WS ─────────────────────────────────────
+
+  describe("#2 — CONNACK=0 closes WS", () => {
+    it("should close WebSocket when CONNACK reasonCode=0 (kicked)", () => {
+      const onError = vi.fn();
+      const socket = createSocket({ onError });
+      socket.connect();
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+
+      // Spy on close
+      const closeSpy = vi.spyOn(ws, "close");
+
+      ws.emit("message", buildConnackPacket(0));
+
+      expect(onError).toHaveBeenCalledWith(expect.objectContaining({
+        message: "Kicked by server",
+      }));
+      expect(closeSpy).toHaveBeenCalled();
+    });
+  });
+
+  // ─── Fix #2: DISCONNECT packet closes WS ──────────────────────────────
+
+  describe("#2 — DISCONNECT packet closes WS", () => {
+    it("should close WebSocket on DISCONNECT packet", () => {
+      const onError = vi.fn();
+      const socket = createSocket({ onError });
+      socket.connect();
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+
+      // First send successful CONNACK so state is connected
+      ws.emit("message", buildConnackPacket(1));
+
+      // Spy on close after CONNACK
+      const closeSpy = vi.spyOn(ws, "close");
+
+      // Now send DISCONNECT
+      ws.emit("message", buildDisconnectPacket());
+
+      expect(onError).toHaveBeenCalledWith(expect.objectContaining({
+        message: "Kicked by server",
+      }));
+      expect(closeSpy).toHaveBeenCalled();
+    });
+  });
+
+  // ─── Fix #4: disconnectAndWait() ──────────────────────────────────────
+
+  describe("#4 — disconnectAndWait()", () => {
+    it("should wait for WS close event before resolving", async () => {
+      // Use real setTimeout for async tests
+      global.setTimeout = originalSetTimeout;
+
+      const socket = createSocket();
+      socket.connect();
+
+      const ws = mockWsInstances[0];
+      expect(ws).toBeDefined();
+
+      // disconnectAndWait should resolve after close event fires
+      const promise = socket.disconnectAndWait();
+
+      // The mock WS close() queues a microtask to emit 'close'
+      await promise;
+      // If we get here, promise resolved successfully
+      expect(true).toBe(true);
+    });
+
+    it("should resolve on timeout if close event never fires", async () => {
+      global.setTimeout = originalSetTimeout;
+
+      const socket = createSocket();
+      socket.connect();
+
+      const ws = mockWsInstances[0];
+
+      // Override close to NOT emit close event
+      ws.close = vi.fn(); // no-op, no close event
+      ws.terminate = vi.fn(); // track terminate calls
+
+      const start = Date.now();
+      await socket.disconnectAndWait(100); // short timeout for test
+      const elapsed = Date.now() - start;
+
+      expect(elapsed).toBeGreaterThanOrEqual(90); // waited ~100ms
+      expect(ws.terminate).toHaveBeenCalled();
+    });
+
+    it("should resolve immediately if no WS exists", async () => {
+      global.setTimeout = originalSetTimeout;
+
+      const socket = createSocket();
+      // Don't connect — no WS exists
+
+      const start = Date.now();
+      await socket.disconnectAndWait();
+      const elapsed = Date.now() - start;
+
+      expect(elapsed).toBeLessThan(50); // resolved immediately
+    });
+  });
+
+  // ─── Fix #3: Heartbeat timer cleared on disconnect ────────────────────
+
+  describe("#3 — heartbeat timer cleared on disconnect", () => {
+    it("should clear heartbeat timer when onDisconnected fires", () => {
+      // This tests the channel-layer pattern: heartbeatTimer cleared in onDisconnected
+      let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+      let heartbeatCleared = false;
+
+      const originalClearInterval = global.clearInterval;
+      global.clearInterval = vi.fn((id) => {
+        if (id === heartbeatTimer) heartbeatCleared = true;
+        originalClearInterval(id);
+      }) as any;
+
+      try {
+        // Simulate startHeartbeat
+        heartbeatTimer = setInterval(() => {}, 60_000);
+
+        // Simulate onDisconnected callback
+        if (heartbeatTimer) {
+          clearInterval(heartbeatTimer);
+          heartbeatTimer = null;
+        }
+
+        expect(heartbeatCleared).toBe(true);
+        expect(heartbeatTimer).toBeNull();
+      } finally {
+        global.clearInterval = originalClearInterval;
+      }
+    });
+
+    it("should restart heartbeat timer on connect", () => {
+      // Simulate the onConnected/onDisconnected pattern
+      let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+      const startHeartbeat = () => {
+        if (heartbeatTimer) clearInterval(heartbeatTimer);
+        heartbeatTimer = setInterval(() => {}, 60_000);
+      };
+
+      // onConnected
+      startHeartbeat();
+      expect(heartbeatTimer).not.toBeNull();
+
+      const firstTimer = heartbeatTimer;
+
+      // onDisconnected
+      if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+      expect(heartbeatTimer).toBeNull();
+
+      // onConnected again
+      startHeartbeat();
+      expect(heartbeatTimer).not.toBeNull();
+      expect(heartbeatTimer).not.toBe(firstTimer);
+
+      // Cleanup
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
+    });
+  });
+
+  // ─── Fix #5: Token refresh disconnects before API call ────────────────
+
+  describe("#5 — token refresh disconnects before API call", () => {
+    it("should call disconnectAndWait before registerBot in refresh path", async () => {
+      // Verify the ordering pattern: disconnect -> refresh -> connect
+      const callOrder: string[] = [];
+
+      const mockSocket = {
+        disconnectAndWait: async () => { callOrder.push("disconnectAndWait"); },
+        updateCredentials: () => { callOrder.push("updateCredentials"); },
+        connect: () => { callOrder.push("connect"); },
+      };
+
+      const mockRegisterBot = async () => {
+        callOrder.push("registerBot");
+        return { robot_id: "bot1", im_token: "tok1" };
+      };
+
+      // Simulate the token refresh path
+      await (async () => {
+        await mockSocket.disconnectAndWait();
+        const fresh = await mockRegisterBot();
+        mockSocket.updateCredentials();
+        mockSocket.connect();
+      })();
+
+      expect(callOrder).toEqual([
+        "disconnectAndWait",
+        "registerBot",
+        "updateCredentials",
+        "connect",
+      ]);
+    });
+  });
+
+  // ─── Fix #6: Heartbeat failure has backoff delay ──────────────────────
+
+  describe("#6 — heartbeat failure backoff delay", () => {
+    it("should delay reconnect after heartbeat failures", async () => {
+      global.setTimeout = originalSetTimeout;
+
+      // Simulate the heartbeat failure backoff pattern
+      const start = Date.now();
+      const backoffMs = 3000 + Math.floor(Math.random() * 2000);
+
+      expect(backoffMs).toBeGreaterThanOrEqual(3000);
+      expect(backoffMs).toBeLessThan(5000);
+
+      // Verify pattern is non-zero delay (not immediate reconnect)
+      expect(backoffMs).toBeGreaterThan(0);
+    });
+
+    it("should apply random jitter to avoid thundering herd", () => {
+      const delays = new Set<number>();
+      for (let i = 0; i < 100; i++) {
+        delays.add(3000 + Math.floor(Math.random() * 2000));
+      }
+      // Should produce multiple distinct values (not all the same)
+      expect(delays.size).toBeGreaterThan(1);
+    });
+  });
+
+  // ─── Fix #7: consecutiveHeartbeatFailures reset on connect ────────────
+
+  describe("#7 — consecutiveHeartbeatFailures reset on connect", () => {
+    it("should reset failure counter on successful connection", () => {
+      let consecutiveHeartbeatFailures = 0;
+
+      // Simulate failures building up
+      consecutiveHeartbeatFailures = 2;
+      expect(consecutiveHeartbeatFailures).toBe(2);
+
+      // Simulate onConnected callback
+      consecutiveHeartbeatFailures = 0;
+      expect(consecutiveHeartbeatFailures).toBe(0);
+
+      // Next failure should start from 0
+      consecutiveHeartbeatFailures++;
+      expect(consecutiveHeartbeatFailures).toBe(1);
+    });
+
+    it("should not trigger reconnect at 1 failure after reset", () => {
+      const MAX_HEARTBEAT_FAILURES = 3;
+      let consecutiveHeartbeatFailures = 2;
+
+      // Reset on connect
+      consecutiveHeartbeatFailures = 0;
+
+      // Single failure after reset
+      consecutiveHeartbeatFailures++;
+
+      // Should NOT trigger reconnect
+      expect(consecutiveHeartbeatFailures >= MAX_HEARTBEAT_FAILURES).toBe(false);
+    });
+  });
+
+  // ─── Fix #8: Ping timeout path (covered by #3) ───────────────────────
+
+  describe("#8 — ping timeout calls onDisconnected", () => {
+    it("should fire onDisconnected on ping timeout so channel clears heartbeat", () => {
+      // Verify that the WKSocket ping timeout path calls onDisconnected
+      const onDisconnected = vi.fn();
+      const socket = createSocket({ onDisconnected });
+      socket.connect();
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+      ws.emit("message", buildConnackPacket(1));
+
+      expect(onDisconnected).not.toHaveBeenCalled();
+
+      // Now simulate ping timeout: the socket's internal restartHeart timer
+      // fires >3 times → closes WS → calls onDisconnected
+      // We can verify by triggering close event which is what happens
+      ws.emit("close");
+
+      expect(onDisconnected).toHaveBeenCalled();
+    });
+  });
+
+  // ─── Fix #9: No dual reconnect ───────────────────────────────────────
+
+  describe("#9 — no dual reconnect", () => {
+    it("should expose stopReconnectTimer as public method", () => {
+      const socket = createSocket();
+      expect(typeof socket.stopReconnectTimer).toBe("function");
+    });
+
+    it("should cancel socket-level reconnect timer", () => {
+      const socket = createSocket();
+      socket.connect();
+
+      const ws = mockWsInstances[0];
+
+      // Trigger close to schedule a reconnect
+      setTimeoutCalls = [];
+      ws.emit("close");
+      expect(setTimeoutCalls.length).toBe(1); // reconnect scheduled
+
+      // Now cancel from channel layer
+      socket.stopReconnectTimer();
+
+      // Execute the scheduled callback — it should be a no-op because
+      // the timer was cleared (though in our mock, clearTimeout doesn't
+      // actually prevent execution, we verify the method exists and works)
+      expect(typeof socket.stopReconnectTimer).toBe("function");
+    });
+
+    it("cooldown path should cancel socket reconnect before calling connect", async () => {
+      // Verify the pattern: stopReconnectTimer() called before connect()
+      const callOrder: string[] = [];
+      const mockSocket = {
+        disconnectAndWait: async () => { callOrder.push("disconnectAndWait"); },
+        stopReconnectTimer: () => { callOrder.push("stopReconnectTimer"); },
+        connect: () => { callOrder.push("connect"); },
+      };
+
+      // Simulate cooldown reconnect path
+      await (async () => {
+        await mockSocket.disconnectAndWait();
+        mockSocket.stopReconnectTimer();
+        mockSocket.connect();
+      })();
+
+      expect(callOrder).toEqual([
+        "disconnectAndWait",
+        "stopReconnectTimer",
+        "connect",
+      ]);
+    });
+  });
+
+  // ─── disconnectAndWait clears state ───────────────────────────────────
+
+  describe("disconnectAndWait clears reconnect state", () => {
+    it("should clear lastConnectTime and rapidDisconnectCount", async () => {
+      global.setTimeout = originalSetTimeout;
+
+      const socket = createSocket();
+      socket.connect();
+
+      const ws = mockWsInstances[0];
+      ws.emit("open");
+      ws.emit("message", buildConnackPacket(1));
+
+      // After successful connect, lastConnectTime is set
+      // disconnectAndWait should clear it
+      await socket.disconnectAndWait();
+
+      // Reconnect and verify no rapid disconnect tracking from before
+      socket.connect();
+      const ws2 = mockWsInstances[1];
+      expect(ws2).toBeDefined();
+    });
+  });
+});

package/src/socket.test.ts

@@ -161,20 +161,19 @@ describe("WKSocket reconnection", () => {
   });
 
   describe("reconnectAttempts reset on successful CONNACK", () => {
-    it("should reset reconnect attempts counter after successful connection", () => {
+    it("should reset reconnect attempts only after 30s stable timer fires", () => {
       const onConnected = vi.fn();
       const socket = createSocket({ onConnected });
       socket.connect();
 
       const ws = mockWsInstances[0];
 
-      // Build up reconnect attempts
+      // Build up reconnect attempts (5 close events → reconnectAttempts = 5)
       for (let i = 0; i < 5; i++) {
         ws.emit("close");
       }
 
       // Build a minimal CONNACK packet:
-      // Header byte: (CONNACK=2 << 4) | 1 (hasServerVersion flag)
       const serverVersion = 4;
       const reasonCode = 1; // success
       const serverKey = Buffer.from(new Uint8Array(32)).toString("base64");
@@ -182,19 +181,15 @@ describe("WKSocket reconnection", () => {
 
       const body: number[] = [];
       body.push(serverVersion);
-      // timeDiff (8 bytes)
-      for (let i = 0; i < 8; i++) body.push(0);
+      for (let i = 0; i < 8; i++) body.push(0); // timeDiff
       body.push(reasonCode);
-      // serverKey as string (2-byte length prefix + data)
       const keyBytes = [...Buffer.from(serverKey)];
       body.push((keyBytes.length >> 8) & 0xff, keyBytes.length & 0xff);
       body.push(...keyBytes);
-      // salt as string
       const saltBytes = [...Buffer.from(salt)];
       body.push((saltBytes.length >> 8) & 0xff, saltBytes.length & 0xff);
       body.push(...saltBytes);
-      // nodeId (8 bytes for version >= 4)
-      for (let i = 0; i < 8; i++) body.push(0);
+      for (let i = 0; i < 8; i++) body.push(0); // nodeId
 
       const header = (2 << 4) | 1; // CONNACK with hasServerVersion
       const packet = new Uint8Array([header, body.length, ...body]);
@@ -202,12 +197,17 @@ describe("WKSocket reconnection", () => {
       // Trigger the open event first so DH keypair is generated
       ws.emit("open");
 
-      // Now send CONNACK
+      // Send CONNACK — starts 30s stable timer but does NOT reset reconnectAttempts
       ws.emit("message", packet.buffer);
-
       expect(onConnected).toHaveBeenCalled();
 
-      // After successful CONNACK, next close+reconnect should use base delay
+      // Find the 30s stable timer callback and execute it
+      // (simulates 30s of stable connection)
+      const stableTimerCall = setTimeoutCalls.find(c => c.delay === 30_000);
+      expect(stableTimerCall).toBeDefined();
+      stableTimerCall!.fn();
+
+      // NOW after stable timer fires, next close+reconnect should use base delay
       setTimeoutCalls = [];
       ws.emit("close");
 

package/src/socket.ts

@@ -261,6 +261,9 @@ export class WKSocket extends EventEmitter {
   private pingRetryCount = 0;
   private readonly pingMaxRetry = 3;
   private reconnectAttempts = 0;
+  private stableTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastConnectTime = 0;
+  private rapidDisconnectCount = 0;
 
   // Per-instance crypto state (set after CONNACK)
   private aesKey = "";
@@ -291,17 +294,54 @@ export class WKSocket extends EventEmitter {
   disconnect(): void {
     this.needReconnect = false;
     this.connected = false;
+    this.lastConnectTime = 0;
+    this.rapidDisconnectCount = 0;
     this.stopHeart();
     this.stopReconnectTimer();
+    this.clearStableTimer();
     if (this.ws) {
       try { this.ws.close(); } catch { /* ignore */ }
       this.ws = null;
     }
   }
 
+  /** Disconnect and wait for the old WS to fully close before resolving. */
+  async disconnectAndWait(timeoutMs = 2000): Promise<void> {
+    this.needReconnect = false;
+    this.connected = false;
+    this.stopHeart();
+    this.stopReconnectTimer();
+    this.clearStableTimer();
+
+    const oldWs = this.ws;
+    this.ws = null;
+    this.lastConnectTime = 0;
+    this.rapidDisconnectCount = 0;
+
+    if (!oldWs) return;
+
+    return new Promise<void>((resolve) => {
+      let resolved = false;
+      const done = () => {
+        if (resolved) return;
+        resolved = true;
+        resolve();
+      };
+      oldWs.on("close", done);
+      try { oldWs.close(); } catch { /* ignore */ }
+      setTimeout(() => {
+        if (!resolved) {
+          try { (oldWs as any).terminate?.(); } catch { /* ignore */ }
+          done();
+        }
+      }, timeoutMs);
+    });
+  }
+
   // ─── Internal Connection Logic ──────────────────────────────────────────
 
   private doConnect(): void {
+    this.clearStableTimer();
     if (this.ws) {
       try { this.ws.close(); } catch { /* ignore */ }
       this.ws = null;
@@ -313,6 +353,7 @@ export class WKSocket extends EventEmitter {
     this.ws = ws;
 
     ws.on("open", () => {
+      if (this.ws !== ws) return; // stale guard
       this.tempBuffer = [];
       // Generate DH key pair
       const seed = Uint8Array.from(stringToUint(generateDeviceID()));
@@ -334,6 +375,7 @@ export class WKSocket extends EventEmitter {
     });
 
     ws.on("message", (data: ArrayBuffer | Buffer) => {
+      if (this.ws !== ws) return; // stale guard
       const bytes = new Uint8Array(data instanceof ArrayBuffer ? data : data.buffer);
       this.handleRawData(bytes);
     });
@@ -349,12 +391,34 @@ export class WKSocket extends EventEmitter {
         this.opts.onDisconnected?.();
       }
       this.stopHeart();
+      this.clearStableTimer();
+
+      // Track rapid disconnects: if connection lasted <5s, it's unstable
+      if (this.lastConnectTime > 0) {
+        const duration = Date.now() - this.lastConnectTime;
+        if (duration < 5000) {
+          this.rapidDisconnectCount++;
+        } else {
+          this.rapidDisconnectCount = 0;
+        }
+        this.lastConnectTime = 0;
+      }
+
+      // If 3+ consecutive rapid disconnects, trigger onError for token refresh
+      if (this.rapidDisconnectCount >= 3) {
+        this.needReconnect = false;
+        this.rapidDisconnectCount = 0;
+        this.opts.onError?.(new Error("Connect failed: rapid disconnect detected"));
+        return;
+      }
+
       if (this.needReconnect) {
         this.scheduleReconnect();
       }
     });
 
     ws.on("error", (err) => {
+      if (this.ws !== ws) return; // stale guard
       console.debug("[WKSocket] ws error:", err.message);
       // The 'close' event will follow, which handles reconnect
     });
@@ -376,13 +440,30 @@ export class WKSocket extends EventEmitter {
     }, delay);
   }
 
-  private stopReconnectTimer(): void {
+  stopReconnectTimer(): void {
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
   }
 
+  private startStableTimer(): void {
+    this.clearStableTimer();
+    this.stableTimer = setTimeout(() => {
+      if (this.connected) {
+        this.reconnectAttempts = 0;
+        this.rapidDisconnectCount = 0;
+      }
+    }, 30_000);
+  }
+
+  private clearStableTimer(): void {
+    if (this.stableTimer) {
+      clearTimeout(this.stableTimer);
+      this.stableTimer = null;
+    }
+  }
+
   // ─── Heartbeat ──────────────────────────────────────────────────────────
 
   private restartHeart(): void {
@@ -393,6 +474,7 @@ export class WKSocket extends EventEmitter {
       if (this.pingRetryCount > this.pingMaxRetry) {
         console.debug("[WKSocket] ping timeout, reconnecting...");
         this.stopHeart();
+        this.clearStableTimer();
         if (this.ws) {
           try { this.ws.close(); } catch { /* ignore */ }
           this.ws = null;
@@ -552,13 +634,15 @@ export class WKSocket extends EventEmitter {
       this.aesIV = salt && salt.length > 16 ? salt.substring(0, 16) : salt;
 
       this.connected = true;
-      this.reconnectAttempts = 0;
+      this.lastConnectTime = Date.now();
       this.restartHeart();
+      this.startStableTimer();
       this.opts.onConnected?.();
     } else if (reasonCode === 0) {
       // Kicked
       this.connected = false;
       this.needReconnect = false;
+      if (this.ws) { try { this.ws.close(); } catch {} this.ws = null; }
       this.opts.onError?.(new Error("Kicked by server"));
       this.opts.onDisconnected?.();
     } else {
@@ -629,6 +713,8 @@ export class WKSocket extends EventEmitter {
     this.connected = false;
     this.needReconnect = false;
     this.stopHeart();
+    this.clearStableTimer();
+    if (this.ws) { try { this.ws.close(); } catch {} this.ws = null; }
     this.opts.onError?.(new Error("Kicked by server"));
     this.opts.onDisconnected?.();
   }