Problem

QQBot adapter enters a zombie state after repeated WebSocket disconnections — the adapter process remains alive but stops receiving messages. This was observed in production logs where the connection dropped (code 4009: Session timed out) and then went silent for 93+ minutes.

Root cause: when _listen_loop exhausts its reconnect attempts, it simply returns without notifying the Gateway's _platform_reconnect_watcher. The watcher never knows the adapter has given up, so no higher-level reconnection is attempted.

Fixes by Severity

P0 — Zombie state: _listen_loop exit silently dies without notifying Gateway

Symptom: After MAX_RECONNECT_ATTEMPTS reconnect failures, _listen_loop returns but the adapter process stays alive. No messages are received. The _platform_reconnect_watcher in gateway/run.py is unaware the adapter has given up.

Fix: All three exit paths in _listen_loop now call _set_fatal_error("qq_reconnect_exhausted", ..., retryable=True) before returning. This signals the Gateway's reconnect watcher to take over reconnection at the platform management level.

Affected paths:

• Rate limit 4008 backoff exhaustion
• QQCloseError (CLOSE/CLOSED events) exhaustion
• Generic Exception exhaustion

P1 — CLOSED/ERROR WebSocket events lose close code and reason

Symptom: WSMsgType.CLOSED and WSMsgType.ERROR events raised a plain RuntimeError("WebSocket closed") with no close code or reason. This prevented proper error classification (e.g., distinguishing a server-side 4009 Session Timeout from a network error).

Fix: Changed to raise QQCloseError(msg.data, msg.extra) instead, preserving the close code and reason for downstream error classification logic.

P1 — No cooldown period between reconnect failures

Symptom: After a failed reconnect attempt, the adapter immediately tries again. The QQ server may not have finished cleaning up the old session, causing the new attempt to fail with a session conflict.

Fix: Added a 15-second await asyncio.sleep(15) in _reconnect() after a failed connection attempt, giving the server time to clean up the old session before the next retry.

P2 — Heartbeat interval reset on reconnect failure

Symptom: _heartbeat_interval was reset to 30.0 at the beginning of _reconnect(), before the connection attempt. If reconnect failed, the interval was already reset, potentially causing incorrect heartbeat timing on the next attempt.

Fix: Moved _heartbeat_interval = 30.0 inside the try block, after await self._open_ws(gateway_url) succeeds. Now it only resets after a confirmed successful connection.

P1 — Heartbeat task not recreated on reconnect (60s code=None death loop)

Symptom: After _reconnect() opens a new WebSocket, the old _heartbeat_task from the dead connection is orphaned — no heartbeat task runs on the new connection. QQ server receives no heartbeat ACK for 60s, then drops the connection with code=None (no close code because the server terminates cleanly without negotiation). Reconnect succeeds via the Gateway watcher, but the same death loop repeats every ~60s.

Production log pattern:

INFO: [QQBot:xxx] Reconnected
... (exactly ~60s later)
WARNING: [QQBot:xxx] WebSocket closed: code=None reason=
INFO: [QQBot:xxx] Reconnecting in 2s (attempt 1)...
INFO: [QQBot:xxx] Reconnected
... (cycle repeats indefinitely)

Root cause: _reconnect() calls _open_ws() to establish a new WebSocket but never calls asyncio.create_task(self._heartbeat_loop()). The _heartbeat_task attribute still references the old task (which died with the old connection's event loop), so no heartbeat is ever sent on the new connection.

Fix (two-part):

1. WS-level ping/pong via aiohttp heartbeat parameter: Added heartbeat=20 to the aiohttp.ClientSession.ws_connect() call in _open_ws(). This enables aiohttp's built-in ping/pong at the transport layer, sending a WebSocket PING every 20s. If no PONG arrives within the timeout, aiohttp closes the connection with a proper error — preventing silent idle disconnects.

2. Recreate heartbeat task on reconnect: In _reconnect():

   • Before opening the new WebSocket: cancel the old _heartbeat_task with cancel() and await it (catches CancelledError)
   • After _open_ws() succeeds: create a fresh _heartbeat_task via asyncio.create_task(self._heartbeat_loop())

These two changes together ensure that every reconnected WebSocket has its own active heartbeat, and the transport layer itself has a safety net for idle connections.

Changes

Test Results

• 71/71 QQBot adapter tests passed (including new heartbeat task lifecycle tests)
• 182/182 total gateway tests passed (base adapter, reconnect watcher, runner fatal adapter tests)
• 0 regressions in adapter base class tests

Reproduction

Bug 1-4 (zombie state): Production logs showed:

WARNING: WebSocket closed: code=4009 reason=Session timed out
WARNING: WebSocket closed: code=4009 reason=Session timed out
... (then silence for 93+ minutes)

After this fix, the adapter properly signals the Gateway, which triggers _platform_reconnect_watcher to reinitialize the adapter.

Bug 5 (60s death loop): Reproduced in staging by:

1. Connect adapter → heartbeat active on connection
2. Simulate WebSocket failure (close underlying TCP) → _reconnect() triggers
3. Observe: new WebSocket opens, "Reconnected" logged, but no heartbeat task created
4. After 60s: WebSocket closed: code=None reason= → reconnect → repeat

After fix: heartbeat task recreated on every reconnect, WS-level ping/pong prevents idle timeout. Connection stays alive across reconnects.