@clawling/clawchat-plugin-openclaw 2026.8.22-1 → 2026.8.27-1

package/README.md

@@ -6,7 +6,7 @@ OpenClaw channel plugin that connects an agent to ClawChat over ClawChat Protoco
 
 - Plugin-owned WebSocket transport with auto-reconnect (exponential backoff + jitter), heartbeat, and ack tracking
 - Inbound `message.send` / `message.reply` with reply context
-- Outbound text replies in `static` or `stream` mode, with a consolidated final `message.reply`
+- Outbound text replies as complete `message.send` / `message.reply` frames — the plugin consumes inbound streams but never emits streaming lifecycle frames
 - Typing indicators and filtered forwarding for thinking / tool-call content
 - Media fragments (image / file / audio / video) in either direction
 - Invite-code onboarding (no raw credentials) via `/clawchat-activate` or supported `openclaw channels add`, plus always-registered `clawchat_*` account/media tools
@@ -95,7 +95,7 @@ src/
                         per-group idle/max batching for non-mention turns
   group-settings.ts     per-group agent settings cache (GET /v1/agents/me/
                         group-settings)
-  reply-dispatcher.ts   static vs stream routing
+  reply-dispatcher.ts   outbound reply routing (complete frames only)
   no-reply.ts           clawchat:no-reply / :silent suppression token guard
   login.runtime.ts      invite-code exchange flow
   refresh-manager.ts    ClawChat token refresh + auto-logout orchestration
@@ -153,7 +153,7 @@ The main reference is
 - Full configuration reference
 - Onboarding / activation details
 - REST endpoint table
-- Streaming frame shapes (`message.created` / `message.add` / `message.done` / `message.reply`)
+- Inbound streaming frame shapes (`message.created` / `message.add` / `message.done` / `message.reply`) — consumed, never produced
 - End-to-end sequence diagram
 - Media pipeline (inbound download / outbound upload)
 - Troubleshooting

package/dist/src/runtime.js

@@ -108,20 +108,26 @@ function isRecord(value) {
 }
 /**
  * §A.2 — classify a WS `hello-fail` reason for refresh gating.
- *  - "token-rejected": reason names an authentication failure → refresh.
+ *  - "token-rejected": the ONE terminal reason → refresh.
  *  - "auth-unavailable": 5xx auth-backend outage → backoff, DO NOT refresh.
- *  - "generic": unattributed → refresh only if the token is at/near expiry.
+ *  - "generic": anything else → transient; backoff with the current token.
  *
- * `auth service unavailable` is already split off by the ws-client into a
- * TransportError (backoff), but we classify defensively here too.
+ * msghub Protocol v2 §3.5 pins the matching contract: `"authentication failed"`
+ * is matched by exact equality (case / surrounding whitespace tolerant, like the
+ * hermes plugin's `_is_token_rejected`), never by substring or prefix, and no
+ * speculative matchers (`invalid token`, `token expired`, `unauthorized`, …) may
+ * be added — msghub does not emit them, and matching them would turn a reason
+ * added later into a forced refresh and, on a rotated refresh token, a re-pair.
+ * The ws-client already routes every non-terminal reason as a TransportError
+ * (backoff), so only the exact terminal string normally reaches this classifier;
+ * it stays defensive for the live-session path.
  */
 export function classifyHelloFailReason(reason) {
-    const r = (reason || "").toLowerCase();
+    const r = (reason || "").trim().toLowerCase();
     if (/auth service unavailable|temporarily unavailable/.test(r))
         return "auth-unavailable";
-    if (/authentication failed|invalid token|token expired|unauthorized|auth failed|invalid credentials/.test(r)) {
+    if (r === "authentication failed")
         return "token-rejected";
-    }
     return "generic";
 }
 /** Read `channels.<CHANNEL_ID>.refreshToken` from a live config, or null. */
@@ -1534,7 +1540,6 @@ export async function startOpenclawClawlingGateway(params) {
     const protocolControlLogger = createProtocolControlHandler({
         accountId,
         log: (msg) => log?.info?.(msg),
-        send: () => { },
         context: wsLogContext,
     });
     const notifySignalObserver = createNotifySignalObserver({
@@ -2914,18 +2919,23 @@ export async function startOpenclawClawlingGateway(params) {
     // Ids only: the frame carries no content, and `payload.message_id` is the
     // server's `rcl:<target>` slot — the id to delete is `target_message_id`.
     //
-    // Synchronous and fire-and-forget on purpose. There is no ack to send (the
-    // frame is BestEffort and non-ackable), and no tombstone to write: a Kafka
-    // redelivery of the original can resurrect the row, which is an accepted
-    // known limitation rather than a fourth reimplementation of the mobile
-    // client's tombstone table.
+    // Synchronous and fire-and-forget on purpose: there is no ack to send (the
+    // frame is BestEffort and non-ackable).
+    //
+    // §9.8 requires a permanent tombstone consulted on every ingest path, and
+    // `store.recallMessage` writes one in the same transaction as the delete.
+    // That is what makes this handler's timing irrelevant: the inbound ledger
+    // write sits behind an await, so on a replay carrying the original and its
+    // recall back-to-back the DELETE runs first — and the tombstone then refuses
+    // the INSERT. It also closes the Kafka-redelivery resurrection this comment
+    // previously accepted as a known limitation.
     client.on("message:recall", (env) => {
         const target = recallTargetMessageId(env.payload);
         if (!target) {
             log?.info?.(`[${accountId}] clawchat-plugin-openclaw recall ignored (no target_message_id) chat_id=${String(env.chat_id ?? "")}`);
             return;
         }
-        const removed = store?.deleteMessagesByMessageId?.({
+        const removed = store?.recallMessage?.({
             platform: "openclaw",
             accountId,
             messageId: target,

package/dist/src/storage.js

@@ -171,6 +171,19 @@ CREATE TABLE IF NOT EXISTS owner_profile (
   updated_at INTEGER NOT NULL,
   PRIMARY KEY (platform, account_id)
 );
+`,
+    },
+    {
+        version: 10,
+        name: "recalled_messages",
+        sql: `
+CREATE TABLE IF NOT EXISTS recalled_messages (
+  platform TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  message_id TEXT NOT NULL,
+  recalled_at INTEGER NOT NULL,
+  PRIMARY KEY (platform, account_id, message_id)
+);
 `,
     },
 ];
@@ -412,6 +425,14 @@ export class ClawChatStore {
     }
     claimMessageOnce(input) {
         return this.write(() => {
+            // Protocol v2 §9.8: consult the recall tombstone on every ingest path.
+            // Doing it inside this same write transaction is what makes the delete
+            // and the insert order-independent: whichever frame the server delivers
+            // first, a recalled message_id can never end up in the ledger. Without
+            // it, a replay carrying the original and its recall back-to-back ran the
+            // DELETE before the INSERT and the row survived.
+            if (input.messageId && this.isMessageRecalled(input))
+                return false;
             const result = this.requireDb()
                 .prepare(`INSERT OR IGNORE INTO clawchat_messages(
             platform, account_id, kind, direction, event_type, trace_id, chat_id,
@@ -462,6 +483,43 @@ export class ClawChatStore {
      * account was paired, or one dropped by the inbound filter). `null` means the
      * store is unavailable.
      */
+    /** True when `message_id` was recalled for this (platform, account). */
+    isMessageRecalled(input) {
+        if (!input.messageId)
+            return false;
+        const row = this.requireDb()
+            .prepare(`SELECT 1 FROM recalled_messages
+          WHERE platform = ? AND account_id = ? AND message_id = ?`)
+            .get(input.platform, input.accountId, input.messageId);
+        return row !== undefined;
+    }
+    /**
+     * Record the permanent recall tombstone and purge any row already stored,
+     * atomically. Returns the number of ledger rows deleted (0 when the recall
+     * arrived before the message did — the tombstone still stands and the later
+     * ingest is refused by {@link claimMessageOnce}).
+     */
+    recallMessage(input) {
+        // An empty id would tombstone and delete rows keyed by '' — every row the
+        // store never managed to key. Refuse rather than guess.
+        if (!input.messageId)
+            return 0;
+        return this.write(() => {
+            const db = this.requireDb();
+            db.prepare(`INSERT OR IGNORE INTO recalled_messages(platform, account_id, message_id, recalled_at)
+          VALUES (?, ?, ?, ?)`).run(input.platform, input.accountId, input.messageId, input.recalledAt ?? Date.now());
+            const result = db
+                .prepare(`DELETE FROM clawchat_messages
+            WHERE platform = ? AND account_id = ? AND message_id = ?`)
+                .run(input.platform, input.accountId, input.messageId);
+            return Number(result.changes);
+        });
+    }
+    /**
+     * Low-level purge by message id. NOT the recall path: it writes no tombstone,
+     * so a recall routed through here loses to a redelivery or to an ingest that
+     * is still behind an await. Use {@link recallMessage} for `message.recall`.
+     */
     deleteMessagesByMessageId(input) {
         // An empty id would match every row whose message_id is '' — deleting
         // everything the store never managed to key. Refuse rather than guess.

package/dist/src/ws-alignment.js

@@ -171,15 +171,12 @@ export function createProtocolControlHandler(options) {
     return {
         handleInbound(env) {
             if (env.event === "ping") {
-                logControl("protocol_ping_received", "send_pong", [["trace_id", env.trace_id]]);
-                options.send(JSON.stringify({
-                    version: "2",
-                    event: "pong",
-                    trace_id: env.trace_id ?? "-",
-                    // §12: echo the sender's emitted_at verbatim (do not restamp).
-                    emitted_at: env.emitted_at ?? Date.now(),
-                    payload: {},
-                }));
+                // §12: the server never emits a JSON-level `ping`, so this is an
+                // anomaly worth seeing — but answering it would send exactly the
+                // unsolicited `pong` the spec bans, which the server drops as an
+                // unknown uplink event. Log it and drop it; this handler has no send
+                // capability, so the banned frame cannot be produced here at all.
+                logControl("protocol_ping_received", "drop", [["trace_id", env.trace_id]]);
                 return true;
             }
             if (env.event === "pong") {

package/dist/src/ws-client.js

@@ -185,6 +185,62 @@ export function isValidChatId(chatId) {
     }
     return true;
 }
+/**
+ * §3.5 terminal `hello-fail` reason. Exact equality after trimming and
+ * lower-casing (parity with the hermes plugin's `_is_token_rejected`); never a
+ * substring or prefix match — see `onHelloFail`.
+ */
+export const TERMINAL_HELLO_FAIL_REASON = "authentication failed";
+export function isTerminalHelloFailReason(reason) {
+    return (reason ?? "").trim().toLowerCase() === TERMINAL_HELLO_FAIL_REASON;
+}
+/**
+ * §3.6 duplicate-session refusal. msghub turns away the NEWER connection with
+ * this close code and a JSON reason `{reason, retry_after_ms}` when the opt-in
+ * guard is on. The server owns the 60s → 300s escalation, so the client only
+ * has to wait the value it is handed.
+ */
+export const CLOSE_CODE_DUPLICATE_THROTTLED = 4002;
+/** Floor used when a 4002 close carries no parseable retry_after_ms. */
+export const DEFAULT_REFUSAL_FLOOR_MS = 60_000;
+/**
+ * §3.6 duplicate-session takeover. msghub closes the OLDER socket with 4001
+ * when a newer session for the same (user, device) takes over. Reconnecting at
+ * the ordinary initial delay races that session and kicks it back — the
+ * mutual-eviction storm.
+ *
+ * A single eviction waits the base floor; consecutive evictions of the same
+ * connection escalate it (doubling, capped), so whichever instance keeps losing
+ * withdraws further each round until the other simply stays connected. Prod
+ * measured 9–163 s per eviction (msghub 2026-08-18), longer than the base, so a
+ * flat floor cannot break a persistent loop — only the escalation does. The
+ * streak survives `hello-ok` (an eviction happens *after* we connect) and is
+ * reset only by a non-4001 close, mirroring the hermes plugin.
+ */
+export const CLOSE_CODE_REPLACED = 4001;
+/** Base floor for the first takeover eviction (the §3.6 minimum). */
+export const TAKEOVER_FLOOR_MS = 5_000;
+/** Ceiling for the escalating takeover floor. */
+export const TAKEOVER_FLOOR_MAX_MS = 600_000;
+/** Reconnect floor for `streak` consecutive 4001 evictions (0 → no floor). */
+export function takeoverFloorMs(streak) {
+    if (streak <= 0)
+        return 0;
+    return Math.min(TAKEOVER_FLOOR_MS * 2 ** (streak - 1), TAKEOVER_FLOOR_MAX_MS);
+}
+export function parseRefusalRetryAfterMs(reason) {
+    if (reason) {
+        try {
+            const value = JSON.parse(reason).retry_after_ms;
+            if (typeof value === "number" && Number.isFinite(value) && value > 0)
+                return value;
+        }
+        catch {
+            // fall through to the default floor
+        }
+    }
+    return DEFAULT_REFUSAL_FLOOR_MS;
+}
 export class ClawChatClient extends EventEmitter {
     opts;
     currentState = "idle";
@@ -194,6 +250,10 @@ export class ClawChatClient extends EventEmitter {
     pongTimer;
     reconnectTimer;
     reconnectAttempts = 0;
+    // Consecutive 4001 duplicate-session evictions. Unlike reconnectAttempts it
+    // is NOT reset on hello-ok (the eviction lands after we connect); a non-4001
+    // close resets it. Drives the escalating takeover floor (§3.6).
+    takeoverStreak = 0;
     closing = false;
     authFailed = false;
     expectedConnectTraceId;
@@ -548,8 +608,10 @@ export class ClawChatClient extends EventEmitter {
             return this.onHelloOk(env);
         if (env.event === EVENT.HELLO_FAIL)
             return this.onHelloFail(env);
-        if (env.event === EVENT.PING)
-            return this.onPing(env);
+        // §12: the server never emits a JSON-level `ping`, and an unsolicited
+        // `pong` is an unknown uplink event the server drops. We therefore do NOT
+        // answer a downlink ping. `pong` below is still handled: it is the reply
+        // to the client-initiated heartbeat probe §12 does allow.
         if (env.event === EVENT.PONG)
             return this.onPong();
         if (env.event === EVENT.MESSAGE_ACK)
@@ -662,13 +724,16 @@ export class ClawChatClient extends EventEmitter {
             this.failHandshake(new ProtocolError("invalid hello-fail payload", env), 4002, "protocol error");
             return;
         }
-        // §14.1: distinguish upstream auth-service unavailability (5xx) from token
-        // rejection (4xx). On a 5xx the token may still be valid and the auth backend
-        // is down — backoff-reconnect with the SAME token and do
-        // NOT refresh (a 5xx storm must not become a mass token-refresh storm). Until
-        // the server emits the distinct 5xx reason, every other hello-fail is treated
-        // as a terminal token rejection (the caller acquires a fresh token first).
-        if (/auth service unavailable/i.test(reason)) {
+        // §3.5: `"authentication failed"` — matched by EXACT equality, never a
+        // substring — is the one terminal reason (the token was rejected by upstream
+        // auth). Every other reason is transient: `remote auth service unavailable`
+        // (the auth backend is down, the token may still be valid — §14.1), `nonce
+        // mismatch`, `invalid connect …`, and any string msghub adds after this
+        // client shipped. For all of those: backoff-reconnect with the SAME token,
+        // keep the outbound queue, and do NOT refresh (a 5xx storm must not become
+        // a mass token-refresh storm; a new server-side reason must not brick old
+        // clients). Widening the terminal branch breaks that forward-compat rule.
+        if (!isTerminalHelloFailReason(reason)) {
             const err = new TransportError(reason);
             this.expectedConnectTraceId = undefined;
             this.clearTimers();
@@ -678,8 +743,12 @@ export class ClawChatClient extends EventEmitter {
             this.connectReject = undefined;
             this.emitError(err);
             if (this.opts.transport.state !== "closed") {
-                // Close WITHOUT marking closing/authFailed so handleClose backoff-reconnects.
-                this.opts.transport.close(4001, "auth service unavailable");
+                // Close WITHOUT marking closing/authFailed so handleClose
+                // backoff-reconnects. Use 1000, NOT 4001: 4001 is the server's
+                // duplicate-session takeover code that handleClose now floors to 5s
+                // (§3.6), and this client-initiated transient teardown must reconnect
+                // on the ordinary backoff instead of inheriting that floor.
+                this.opts.transport.close(1000, reason);
             }
             else if (!this.closing && this.opts.reconnect.enabled) {
                 this.scheduleReconnect(reason);
@@ -704,15 +773,6 @@ export class ClawChatClient extends EventEmitter {
             this.opts.transport.close(4001, "auth failed");
         }
     }
-    onPing(env) {
-        this.sendRawEnvelope({
-            version: "2",
-            event: EVENT.PONG,
-            trace_id: env.trace_id,
-            emitted_at: env.emitted_at,
-            payload: {},
-        });
-    }
     onPong() {
         if (this.pongTimer)
             clearTimeout(this.pongTimer);
@@ -803,7 +863,27 @@ export class ClawChatClient extends EventEmitter {
             this.connectReject?.(closeError);
             return;
         }
-        this.scheduleReconnect(reason || `close ${code}`);
+        // §3.6: raise an explicit reconnect floor for the two server-timed
+        // duplicate-session closes. 4002 (refusal) waits the server's
+        // retry_after_ms, which exceeds the maxDelay cap; 4001 (takeover) waits at
+        // least 5s so an instant reconnect doesn't re-enter the eviction storm.
+        let floorMs;
+        if (code === CLOSE_CODE_DUPLICATE_THROTTLED) {
+            // A refusal is not a takeover-loss — reset the streak and wait the
+            // server's retry_after_ms.
+            this.takeoverStreak = 0;
+            floorMs = parseRefusalRetryAfterMs(reason);
+        }
+        else if (code === CLOSE_CODE_REPLACED) {
+            this.takeoverStreak += 1;
+            floorMs = takeoverFloorMs(this.takeoverStreak);
+        }
+        else {
+            // Any other close (ordinary drop, backpressure kick) is not an eviction
+            // loss — reset so the next takeover starts from the base floor again.
+            this.takeoverStreak = 0;
+        }
+        this.scheduleReconnect(reason || `close ${code}`, floorMs);
     }
     failHandshake(err, code, reason) {
         this.clearTimers();
@@ -820,7 +900,7 @@ export class ClawChatClient extends EventEmitter {
             this.opts.transport.close(code, reason);
         }
     }
-    scheduleReconnect(reason) {
+    scheduleReconnect(reason, floorMs) {
         if (this.reconnectTimer)
             return;
         if (this.reconnectAttempts >= this.opts.reconnect.maxRetries) {
@@ -830,7 +910,10 @@ export class ClawChatClient extends EventEmitter {
             return;
         }
         this.reconnectAttempts += 1;
-        const baseDelay = Math.min(this.opts.reconnect.maxDelay, this.opts.reconnect.initialDelay * 2 ** Math.max(0, this.reconnectAttempts - 1));
+        const cappedDelay = Math.min(this.opts.reconnect.maxDelay, this.opts.reconnect.initialDelay * 2 ** Math.max(0, this.reconnectAttempts - 1));
+        // An explicit floor (a 4002 retry_after_ms) overrides the maxDelay cap: the
+        // server's wait is deliberately longer than the ordinary backoff ceiling.
+        const baseDelay = floorMs !== undefined ? Math.max(cappedDelay, floorMs) : cappedDelay;
         const jitter = baseDelay * this.opts.reconnect.jitterRatio * Math.random();
         const delay = Math.round(baseDelay + jitter);
         this.transition("reconnecting");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.8.22-1",
+  "version": "2026.8.27-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/runtime.ts

@@ -124,7 +124,7 @@ type RuntimeConnectionStore = Pick<
       | "getActivationConversation"
       | "getLastResolvedDeviceId"
       | "listRecentGroupMessages"
-      | "deleteMessagesByMessageId"
+      | "recallMessage"
       | "upsertOwnerProfile"
     >
   >;
@@ -210,21 +210,26 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 
 /**
  * §A.2 — classify a WS `hello-fail` reason for refresh gating.
- *  - "token-rejected": reason names an authentication failure → refresh.
+ *  - "token-rejected": the ONE terminal reason → refresh.
  *  - "auth-unavailable": 5xx auth-backend outage → backoff, DO NOT refresh.
- *  - "generic": unattributed → refresh only if the token is at/near expiry.
+ *  - "generic": anything else → transient; backoff with the current token.
  *
- * `auth service unavailable` is already split off by the ws-client into a
- * TransportError (backoff), but we classify defensively here too.
+ * msghub Protocol v2 §3.5 pins the matching contract: `"authentication failed"`
+ * is matched by exact equality (case / surrounding whitespace tolerant, like the
+ * hermes plugin's `_is_token_rejected`), never by substring or prefix, and no
+ * speculative matchers (`invalid token`, `token expired`, `unauthorized`, …) may
+ * be added — msghub does not emit them, and matching them would turn a reason
+ * added later into a forced refresh and, on a rotated refresh token, a re-pair.
+ * The ws-client already routes every non-terminal reason as a TransportError
+ * (backoff), so only the exact terminal string normally reaches this classifier;
+ * it stays defensive for the live-session path.
  */
 export function classifyHelloFailReason(
   reason: string,
 ): "token-rejected" | "auth-unavailable" | "generic" {
-  const r = (reason || "").toLowerCase();
+  const r = (reason || "").trim().toLowerCase();
   if (/auth service unavailable|temporarily unavailable/.test(r)) return "auth-unavailable";
-  if (/authentication failed|invalid token|token expired|unauthorized|auth failed|invalid credentials/.test(r)) {
-    return "token-rejected";
-  }
+  if (r === "authentication failed") return "token-rejected";
   return "generic";
 }
 
@@ -1922,7 +1927,6 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   const protocolControlLogger = createProtocolControlHandler({
     accountId,
     log: (msg) => log?.info?.(msg),
-    send: () => {},
     context: wsLogContext,
   });
   const notifySignalObserver = createNotifySignalObserver({
@@ -3456,11 +3460,16 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
   // Ids only: the frame carries no content, and `payload.message_id` is the
   // server's `rcl:<target>` slot — the id to delete is `target_message_id`.
   //
-  // Synchronous and fire-and-forget on purpose. There is no ack to send (the
-  // frame is BestEffort and non-ackable), and no tombstone to write: a Kafka
-  // redelivery of the original can resurrect the row, which is an accepted
-  // known limitation rather than a fourth reimplementation of the mobile
-  // client's tombstone table.
+  // Synchronous and fire-and-forget on purpose: there is no ack to send (the
+  // frame is BestEffort and non-ackable).
+  //
+  // §9.8 requires a permanent tombstone consulted on every ingest path, and
+  // `store.recallMessage` writes one in the same transaction as the delete.
+  // That is what makes this handler's timing irrelevant: the inbound ledger
+  // write sits behind an await, so on a replay carrying the original and its
+  // recall back-to-back the DELETE runs first — and the tombstone then refuses
+  // the INSERT. It also closes the Kafka-redelivery resurrection this comment
+  // previously accepted as a known limitation.
   client.on("message:recall", (env: Envelope) => {
     const target = recallTargetMessageId(env.payload);
     if (!target) {
@@ -3469,7 +3478,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       );
       return;
     }
-    const removed = store?.deleteMessagesByMessageId?.({
+    const removed = store?.recallMessage?.({
       platform: "openclaw",
       accountId,
       messageId: target,

package/src/storage.ts

@@ -389,6 +389,19 @@ CREATE TABLE IF NOT EXISTS owner_profile (
   updated_at INTEGER NOT NULL,
   PRIMARY KEY (platform, account_id)
 );
+`,
+  },
+  {
+    version: 10,
+    name: "recalled_messages",
+    sql: `
+CREATE TABLE IF NOT EXISTS recalled_messages (
+  platform TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  message_id TEXT NOT NULL,
+  recalled_at INTEGER NOT NULL,
+  PRIMARY KEY (platform, account_id, message_id)
+);
 `,
   },
 ];
@@ -722,6 +735,13 @@ export class ClawChatStore {
 
   claimMessageOnce(input: MessageInput): true | false | null {
     return this.write(() => {
+      // Protocol v2 §9.8: consult the recall tombstone on every ingest path.
+      // Doing it inside this same write transaction is what makes the delete
+      // and the insert order-independent: whichever frame the server delivers
+      // first, a recalled message_id can never end up in the ledger. Without
+      // it, a replay carrying the original and its recall back-to-back ran the
+      // DELETE before the INSERT and the row survived.
+      if (input.messageId && this.isMessageRecalled(input)) return false;
       const result = this.requireDb()
         .prepare(
           `INSERT OR IGNORE INTO clawchat_messages(
@@ -821,6 +841,54 @@ export class ClawChatStore {
    * account was paired, or one dropped by the inbound filter). `null` means the
    * store is unavailable.
    */
+  /** True when `message_id` was recalled for this (platform, account). */
+  isMessageRecalled(input: { platform: string; accountId: string; messageId?: string | null }): boolean {
+    if (!input.messageId) return false;
+    const row = this.requireDb()
+      .prepare(
+        `SELECT 1 FROM recalled_messages
+          WHERE platform = ? AND account_id = ? AND message_id = ?`,
+      )
+      .get(input.platform, input.accountId, input.messageId);
+    return row !== undefined;
+  }
+
+  /**
+   * Record the permanent recall tombstone and purge any row already stored,
+   * atomically. Returns the number of ledger rows deleted (0 when the recall
+   * arrived before the message did — the tombstone still stands and the later
+   * ingest is refused by {@link claimMessageOnce}).
+   */
+  recallMessage(input: {
+    platform: string;
+    accountId: string;
+    messageId: string;
+    recalledAt?: number;
+  }): number | null {
+    // An empty id would tombstone and delete rows keyed by '' — every row the
+    // store never managed to key. Refuse rather than guess.
+    if (!input.messageId) return 0;
+    return this.write(() => {
+      const db = this.requireDb();
+      db.prepare(
+        `INSERT OR IGNORE INTO recalled_messages(platform, account_id, message_id, recalled_at)
+          VALUES (?, ?, ?, ?)`,
+      ).run(input.platform, input.accountId, input.messageId, input.recalledAt ?? Date.now());
+      const result = db
+        .prepare(
+          `DELETE FROM clawchat_messages
+            WHERE platform = ? AND account_id = ? AND message_id = ?`,
+        )
+        .run(input.platform, input.accountId, input.messageId);
+      return Number(result.changes);
+    });
+  }
+
+  /**
+   * Low-level purge by message id. NOT the recall path: it writes no tombstone,
+   * so a recall routed through here loses to a redelivery or to an ingest that
+   * is still behind an await. Use {@link recallMessage} for `message.recall`.
+   */
   deleteMessagesByMessageId(input: {
     platform: string;
     accountId: string;

package/src/ws-alignment.ts

@@ -238,7 +238,6 @@ export interface ProtocolControlEnvelope {
 export interface CreateProtocolControlHandlerOptions {
   accountId: string;
   log: (msg: string) => void;
-  send: (wire: string) => void;
   scheduleReconnect?: (reason: string) => void;
   attempt?: number;
   reconnectCount?: number;
@@ -275,17 +274,12 @@ export function createProtocolControlHandler(options: CreateProtocolControlHandl
   return {
     handleInbound(env: ProtocolControlEnvelope): boolean {
       if (env.event === "ping") {
-        logControl("protocol_ping_received", "send_pong", [["trace_id", env.trace_id]]);
-        options.send(
-          JSON.stringify({
-            version: "2",
-            event: "pong",
-            trace_id: env.trace_id ?? "-",
-            // §12: echo the sender's emitted_at verbatim (do not restamp).
-            emitted_at: env.emitted_at ?? Date.now(),
-            payload: {},
-          }),
-        );
+        // §12: the server never emits a JSON-level `ping`, so this is an
+        // anomaly worth seeing — but answering it would send exactly the
+        // unsolicited `pong` the spec bans, which the server drops as an
+        // unknown uplink event. Log it and drop it; this handler has no send
+        // capability, so the banned frame cannot be produced here at all.
+        logControl("protocol_ping_received", "drop", [["trace_id", env.trace_id]]);
         return true;
       }
       if (env.event === "pong") {

package/src/ws-client.ts

@@ -270,6 +270,65 @@ export function isValidChatId(chatId: unknown): chatId is string {
  */
 export type DeadChatSource = "signal" | "server";
 
+/**
+ * §3.5 terminal `hello-fail` reason. Exact equality after trimming and
+ * lower-casing (parity with the hermes plugin's `_is_token_rejected`); never a
+ * substring or prefix match — see `onHelloFail`.
+ */
+export const TERMINAL_HELLO_FAIL_REASON = "authentication failed";
+
+export function isTerminalHelloFailReason(reason: string | undefined): boolean {
+  return (reason ?? "").trim().toLowerCase() === TERMINAL_HELLO_FAIL_REASON;
+}
+
+/**
+ * §3.6 duplicate-session refusal. msghub turns away the NEWER connection with
+ * this close code and a JSON reason `{reason, retry_after_ms}` when the opt-in
+ * guard is on. The server owns the 60s → 300s escalation, so the client only
+ * has to wait the value it is handed.
+ */
+export const CLOSE_CODE_DUPLICATE_THROTTLED = 4002;
+/** Floor used when a 4002 close carries no parseable retry_after_ms. */
+export const DEFAULT_REFUSAL_FLOOR_MS = 60_000;
+
+/**
+ * §3.6 duplicate-session takeover. msghub closes the OLDER socket with 4001
+ * when a newer session for the same (user, device) takes over. Reconnecting at
+ * the ordinary initial delay races that session and kicks it back — the
+ * mutual-eviction storm.
+ *
+ * A single eviction waits the base floor; consecutive evictions of the same
+ * connection escalate it (doubling, capped), so whichever instance keeps losing
+ * withdraws further each round until the other simply stays connected. Prod
+ * measured 9–163 s per eviction (msghub 2026-08-18), longer than the base, so a
+ * flat floor cannot break a persistent loop — only the escalation does. The
+ * streak survives `hello-ok` (an eviction happens *after* we connect) and is
+ * reset only by a non-4001 close, mirroring the hermes plugin.
+ */
+export const CLOSE_CODE_REPLACED = 4001;
+/** Base floor for the first takeover eviction (the §3.6 minimum). */
+export const TAKEOVER_FLOOR_MS = 5_000;
+/** Ceiling for the escalating takeover floor. */
+export const TAKEOVER_FLOOR_MAX_MS = 600_000;
+
+/** Reconnect floor for `streak` consecutive 4001 evictions (0 → no floor). */
+export function takeoverFloorMs(streak: number): number {
+  if (streak <= 0) return 0;
+  return Math.min(TAKEOVER_FLOOR_MS * 2 ** (streak - 1), TAKEOVER_FLOOR_MAX_MS);
+}
+
+export function parseRefusalRetryAfterMs(reason: string | undefined): number {
+  if (reason) {
+    try {
+      const value = (JSON.parse(reason) as { retry_after_ms?: unknown }).retry_after_ms;
+      if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
+    } catch {
+      // fall through to the default floor
+    }
+  }
+  return DEFAULT_REFUSAL_FLOOR_MS;
+}
+
 export class ClawChatClient extends EventEmitter {
   private currentState: ConnState = "idle";
   private connectResolve?: () => void;
@@ -278,6 +337,10 @@ export class ClawChatClient extends EventEmitter {
   private pongTimer?: ReturnType<typeof setTimeout>;
   private reconnectTimer?: ReturnType<typeof setTimeout>;
   private reconnectAttempts = 0;
+  // Consecutive 4001 duplicate-session evictions. Unlike reconnectAttempts it
+  // is NOT reset on hello-ok (the eviction lands after we connect); a non-4001
+  // close resets it. Drives the escalating takeover floor (§3.6).
+  private takeoverStreak = 0;
   private closing = false;
   private authFailed = false;
   private expectedConnectTraceId?: string;
@@ -646,7 +709,10 @@ export class ClawChatClient extends EventEmitter {
     if (env.event === EVENT.CONNECT_CHALLENGE) return this.onChallenge(env);
     if (env.event === EVENT.HELLO_OK) return this.onHelloOk(env);
     if (env.event === EVENT.HELLO_FAIL) return this.onHelloFail(env);
-    if (env.event === EVENT.PING) return this.onPing(env);
+    // §12: the server never emits a JSON-level `ping`, and an unsolicited
+    // `pong` is an unknown uplink event the server drops. We therefore do NOT
+    // answer a downlink ping. `pong` below is still handled: it is the reply
+    // to the client-initiated heartbeat probe §12 does allow.
     if (env.event === EVENT.PONG) return this.onPong();
     if (env.event === EVENT.MESSAGE_ACK) return this.onAck(env as Envelope<MessageAckPayload>);
     if (env.event === EVENT.MESSAGE_ERROR) return this.onMessageError(env as Envelope<MessageErrorPayload>);
@@ -744,13 +810,16 @@ export class ClawChatClient extends EventEmitter {
       this.failHandshake(new ProtocolError("invalid hello-fail payload", env), 4002, "protocol error");
       return;
     }
-    // §14.1: distinguish upstream auth-service unavailability (5xx) from token
-    // rejection (4xx). On a 5xx the token may still be valid and the auth backend
-    // is down — backoff-reconnect with the SAME token and do
-    // NOT refresh (a 5xx storm must not become a mass token-refresh storm). Until
-    // the server emits the distinct 5xx reason, every other hello-fail is treated
-    // as a terminal token rejection (the caller acquires a fresh token first).
-    if (/auth service unavailable/i.test(reason)) {
+    // §3.5: `"authentication failed"` — matched by EXACT equality, never a
+    // substring — is the one terminal reason (the token was rejected by upstream
+    // auth). Every other reason is transient: `remote auth service unavailable`
+    // (the auth backend is down, the token may still be valid — §14.1), `nonce
+    // mismatch`, `invalid connect …`, and any string msghub adds after this
+    // client shipped. For all of those: backoff-reconnect with the SAME token,
+    // keep the outbound queue, and do NOT refresh (a 5xx storm must not become
+    // a mass token-refresh storm; a new server-side reason must not brick old
+    // clients). Widening the terminal branch breaks that forward-compat rule.
+    if (!isTerminalHelloFailReason(reason)) {
       const err = new TransportError(reason);
       this.expectedConnectTraceId = undefined;
       this.clearTimers();
@@ -760,8 +829,12 @@ export class ClawChatClient extends EventEmitter {
       this.connectReject = undefined;
       this.emitError(err);
       if (this.opts.transport.state !== "closed") {
-        // Close WITHOUT marking closing/authFailed so handleClose backoff-reconnects.
-        this.opts.transport.close(4001, "auth service unavailable");
+        // Close WITHOUT marking closing/authFailed so handleClose
+        // backoff-reconnects. Use 1000, NOT 4001: 4001 is the server's
+        // duplicate-session takeover code that handleClose now floors to 5s
+        // (§3.6), and this client-initiated transient teardown must reconnect
+        // on the ordinary backoff instead of inheriting that floor.
+        this.opts.transport.close(1000, reason);
       } else if (!this.closing && this.opts.reconnect.enabled) {
         this.scheduleReconnect(reason);
       } else {
@@ -785,16 +858,6 @@ export class ClawChatClient extends EventEmitter {
     }
   }
 
-  private onPing(env: Envelope): void {
-    this.sendRawEnvelope({
-      version: "2",
-      event: EVENT.PONG,
-      trace_id: env.trace_id,
-      emitted_at: env.emitted_at,
-      payload: {} satisfies EmptyPayload,
-    });
-  }
-
   private onPong(): void {
     if (this.pongTimer) clearTimeout(this.pongTimer);
     this.pongTimer = undefined;
@@ -882,7 +945,25 @@ export class ClawChatClient extends EventEmitter {
       this.connectReject?.(closeError);
       return;
     }
-    this.scheduleReconnect(reason || `close ${code}`);
+    // §3.6: raise an explicit reconnect floor for the two server-timed
+    // duplicate-session closes. 4002 (refusal) waits the server's
+    // retry_after_ms, which exceeds the maxDelay cap; 4001 (takeover) waits at
+    // least 5s so an instant reconnect doesn't re-enter the eviction storm.
+    let floorMs: number | undefined;
+    if (code === CLOSE_CODE_DUPLICATE_THROTTLED) {
+      // A refusal is not a takeover-loss — reset the streak and wait the
+      // server's retry_after_ms.
+      this.takeoverStreak = 0;
+      floorMs = parseRefusalRetryAfterMs(reason);
+    } else if (code === CLOSE_CODE_REPLACED) {
+      this.takeoverStreak += 1;
+      floorMs = takeoverFloorMs(this.takeoverStreak);
+    } else {
+      // Any other close (ordinary drop, backpressure kick) is not an eviction
+      // loss — reset so the next takeover starts from the base floor again.
+      this.takeoverStreak = 0;
+    }
+    this.scheduleReconnect(reason || `close ${code}`, floorMs);
   }
 
   private failHandshake(err: Error, code: number, reason: string): void {
@@ -901,7 +982,7 @@ export class ClawChatClient extends EventEmitter {
     }
   }
 
-  private scheduleReconnect(reason: string): void {
+  private scheduleReconnect(reason: string, floorMs?: number): void {
     if (this.reconnectTimer) return;
     if (this.reconnectAttempts >= this.opts.reconnect.maxRetries) {
       this.sendQueue.length = 0;
@@ -910,10 +991,13 @@ export class ClawChatClient extends EventEmitter {
       return;
     }
     this.reconnectAttempts += 1;
-    const baseDelay = Math.min(
+    const cappedDelay = Math.min(
       this.opts.reconnect.maxDelay,
       this.opts.reconnect.initialDelay * 2 ** Math.max(0, this.reconnectAttempts - 1),
     );
+    // An explicit floor (a 4002 retry_after_ms) overrides the maxDelay cap: the
+    // server's wait is deliberately longer than the ordinary backoff ceiling.
+    const baseDelay = floorMs !== undefined ? Math.max(cappedDelay, floorMs) : cappedDelay;
     const jitter = baseDelay * this.opts.reconnect.jitterRatio * Math.random();
     const delay = Math.round(baseDelay + jitter);
     this.transition("reconnecting");