talon-agent 3.25.3 → 3.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.25.3",
+  "version": "3.27.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -110,6 +110,7 @@
     "@opencode-ai/sdk": "^1.17.4",
     "@playwright/mcp": "0.0.79",
     "@types/cross-spawn": "^6.0.6",
+    "@types/qrcode": "^1.5.6",
     "baileys": "^7.0.0-rc14",
     "big-integer": "^1.6.52",
     "cheerio": "^1.2.0",
@@ -126,6 +127,7 @@
     "picocolors": "^1.1.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
+    "qrcode": "^1.5.4",
     "qrcode-terminal": "^0.12.0",
     "telegram": "^2.26.22",
     "tsx": "^4.21.0",

package/src/core/pairing-broker.ts

@@ -0,0 +1,50 @@
+/**
+ * Frontend-pairing broker — how one frontend drives another's device
+ * pairing without importing it.
+ *
+ * Concretely: WhatsApp needs a human to scan a QR / enter a code, and
+ * the human is reachable on Telegram. Frontends must not import each
+ * other, so this core seam (baileys-free, grammy-free) carries the
+ * handshake: the WhatsApp side registers a provider at composition time,
+ * the Telegram command consumes it on demand.
+ *
+ * Born from an outage: automatic re-pairing loops burned ~30 codes in
+ * 80 minutes and WhatsApp rate-limited the account ("couldn't connect
+ * device" on every scan). Pairing must be a deliberate act that happens
+ * exactly when the human is holding the phone — one bounded attempt per
+ * command, zero background retries.
+ */
+
+export type PairingAttempt = {
+  /** PNG bytes of the QR to scan, when the flow produced one. */
+  qrPng?: Uint8Array;
+  /** Phone-number pairing code, when the account is configured for it. */
+  code?: string;
+  /** Resolves with the outcome of THIS attempt (bounded, never hangs). */
+  result: Promise<PairingOutcome>;
+  /** Abort the attempt early (user cancelled, command timed out). */
+  cancel: () => void;
+};
+
+export type PairingOutcome =
+  | { ok: true; identity: string }
+  | { ok: false; reason: "expired" | "failed" | "cancelled"; detail?: string };
+
+export type PairingProvider = {
+  /** Human-readable frontend name ("WhatsApp"). */
+  label: string;
+  /** True when the frontend is already linked and connected. */
+  isLinked: () => boolean;
+  /** Start ONE bounded pairing attempt. Rejects if one is already running. */
+  begin: () => Promise<PairingAttempt>;
+};
+
+let provider: PairingProvider | null = null;
+
+export function registerPairingProvider(p: PairingProvider | null): void {
+  provider = p;
+}
+
+export function getPairingProvider(): PairingProvider | null {
+  return provider;
+}

package/src/frontend/telegram/commands/definitions.ts

@@ -29,6 +29,7 @@ export const TELEGRAM_COMMANDS: ReadonlyArray<{
   { command: "stop", description: "Stop the current response" },
   { command: "reset", description: "Clear session and start fresh" },
   { command: "restart", description: "Restart the bot (admin)" },
+  { command: "whatsapp", description: "WhatsApp link status / pair (admin)" },
   { command: "usage", description: "Plan limits across every backend" },
   { command: "metrics", description: "Aggregate performance metrics" },
   {

package/src/frontend/telegram/commands/index.ts

@@ -22,6 +22,7 @@ import { registerInfoCommands } from "./info.js";
 import { registerSessionCommands } from "./session.js";
 import { registerSettingsCommands } from "./settings.js";
 import { registerAdminCommands } from "./admin.js";
+import { registerWhatsAppPairingCommand } from "./whatsapp-pairing.js";
 
 export { TELEGRAM_COMMANDS, telegramCommandMenu } from "./definitions.js";
 export { setAdminUserId } from "./state.js";
@@ -36,4 +37,5 @@ export function registerCommands(
   registerSessionCommands(bot, deps);
   registerSettingsCommands(bot, deps);
   registerAdminCommands(bot, deps);
+  registerWhatsAppPairingCommand(bot);
 }

package/src/frontend/telegram/commands/whatsapp-pairing.ts

@@ -0,0 +1,102 @@
+/**
+ * /whatsapp — drive WhatsApp device pairing from Telegram.
+ *
+ * `/whatsapp` reports link state; `/whatsapp pair` runs ONE bounded
+ * pairing attempt via the core pairing broker and replies with the QR as
+ * a photo (plus the phone-number code when the account has one
+ * configured). The human runs it when they are holding the phone —
+ * pairing is never automatic, because automatic retries are how the
+ * account got rate-limited into "couldn't connect device".
+ */
+
+import { InputFile, type Bot } from "grammy";
+import { getPairingProvider } from "../../../core/pairing-broker.js";
+import { log } from "../../../util/log.js";
+import { isAuthorizedAdmin } from "./state.js";
+
+export function registerWhatsAppPairingCommand(bot: Bot): void {
+  bot.command("whatsapp", async (ctx) => {
+    if (!isAuthorizedAdmin(ctx)) {
+      await ctx.reply("Not authorized.");
+      return;
+    }
+
+    const provider = getPairingProvider();
+    if (!provider) {
+      await ctx.reply(
+        'WhatsApp isn\'t enabled on this daemon — add "whatsapp" to the ' +
+          "frontend list and configure the whatsapp block, then restart.",
+      );
+      return;
+    }
+
+    const arg = (ctx.match ?? "").trim().toLowerCase();
+    if (arg !== "pair") {
+      await ctx.reply(
+        provider.isLinked()
+          ? "✅ WhatsApp is linked and connected.\nSend /whatsapp pair to re-link."
+          : "📴 WhatsApp is not linked.\nSend /whatsapp pair when you're " +
+              "holding the phone — I'll reply with a QR to scan " +
+              "(WhatsApp → Linked devices → Link a device).",
+      );
+      return;
+    }
+
+    if (provider.isLinked()) {
+      await ctx.reply(
+        "WhatsApp is already linked. Unlink it on the phone first if you " +
+          "want to re-pair.",
+      );
+      return;
+    }
+
+    let attempt;
+    try {
+      attempt = await provider.begin();
+    } catch (err) {
+      await ctx.reply(
+        `Couldn't start pairing: ${err instanceof Error ? err.message : err}`,
+      );
+      return;
+    }
+
+    if (attempt.qrPng) {
+      const codeLine = attempt.code
+        ? `\nOr enter code: ${attempt.code} (Link with phone number instead)`
+        : "";
+      await ctx.replyWithPhoto(
+        new InputFile(attempt.qrPng, "whatsapp-qr.png"),
+        {
+          caption:
+            "Scan within ~2 minutes:\n" +
+            "WhatsApp → ⋮ → Linked devices → Link a device" +
+            codeLine,
+        },
+      );
+    } else {
+      await ctx.reply(
+        "No QR came back — WhatsApp may still be rate-limiting. Try later.",
+      );
+    }
+
+    const outcome = await attempt.result;
+    if (outcome.ok) {
+      log("bot", `WhatsApp paired via /whatsapp pair (${outcome.identity})`);
+      await ctx.reply(
+        `✅ Linked as ${outcome.identity}. WhatsApp is connecting now.`,
+      );
+    } else if (outcome.reason === "expired") {
+      await ctx.reply(
+        "⌛ That window expired without a successful scan. Run " +
+          "/whatsapp pair again when you're ready — if the phone says " +
+          '"couldn\'t connect device", WhatsApp is still rate-limiting; ' +
+          "wait an hour and try once more.",
+      );
+    } else if (outcome.reason !== "cancelled") {
+      await ctx.reply(
+        `❌ Pairing failed${outcome.detail ? `: ${outcome.detail}` : ""}. ` +
+          "Run /whatsapp pair to try again.",
+      );
+    }
+  });
+}

package/src/frontend/whatsapp/actions/messaging.ts

@@ -17,7 +17,13 @@ import {
   resolveKey,
 } from "../message-store.js";
 import { recordPin, listPins, forgetPin } from "../pins.js";
-import { resolveQuoted, sendContent, sendText, tryAction } from "./shared.js";
+import {
+  resolveQuoted,
+  sendContent,
+  sendText,
+  tryAction,
+  boundedSend,
+} from "./shared.js";
 import type { WhatsAppActionHandlers } from "./types.js";
 
 /** WhatsApp keeps a pin for 24h, 7d, or 30d — no indefinite option. */
@@ -89,9 +95,11 @@ export const messagingHandlers: WhatsAppActionHandlers = {
       if ("error" in resolved) return { ok: false, error: resolved.error };
       // An empty emoji clears the reaction — WhatsApp's own semantics,
       // and the only way to take one back.
-      await ctx.sock.sendMessage(ctx.chat!.jid, {
-        react: { text: String(body.emoji ?? ""), key: resolved.key },
-      });
+      await boundedSend("react", () =>
+        ctx.sock.sendMessage(ctx.chat!.jid, {
+          react: { text: String(body.emoji ?? ""), key: resolved.key },
+        }),
+      );
       return { ok: true };
     }),
 
@@ -103,10 +111,12 @@ export const messagingHandlers: WhatsAppActionHandlers = {
       if (!text.trim()) {
         return { ok: false, error: "edit_message: text is required" };
       }
-      await ctx.sock.sendMessage(ctx.chat!.jid, {
-        text: toWhatsAppText(text),
-        edit: resolved.key,
-      });
+      await boundedSend("edit", () =>
+        ctx.sock.sendMessage(ctx.chat!.jid, {
+          text: toWhatsAppText(text),
+          edit: resolved.key,
+        }),
+      );
       return { ok: true, message_id: resolved.stored.msgId };
     }),
 
@@ -114,7 +124,9 @@ export const messagingHandlers: WhatsAppActionHandlers = {
     tryAction("delete_message", async () => {
       const resolved = resolveKey(body.message_id, ctx.chat!.chatId);
       if ("error" in resolved) return { ok: false, error: resolved.error };
-      await ctx.sock.sendMessage(ctx.chat!.jid, { delete: resolved.key });
+      await boundedSend("delete", () =>
+        ctx.sock.sendMessage(ctx.chat!.jid, { delete: resolved.key }),
+      );
       forgetPin(ctx.chat!.chatId, resolved.stored.msgId);
       return { ok: true };
     }),
@@ -166,11 +178,13 @@ export const messagingHandlers: WhatsAppActionHandlers = {
       const time =
         PIN_DURATIONS.find((d) => d >= requested) ??
         PIN_DURATIONS[PIN_DURATIONS.length - 1];
-      await ctx.sock.sendMessage(ctx.chat!.jid, {
-        pin: resolved.key,
-        type: proto.PinInChat.Type.PIN_FOR_ALL,
-        time,
-      });
+      await boundedSend("pin", () =>
+        ctx.sock.sendMessage(ctx.chat!.jid, {
+          pin: resolved.key,
+          type: proto.PinInChat.Type.PIN_FOR_ALL,
+          time,
+        }),
+      );
       recordPin(ctx.chat!.chatId, resolved.stored);
       return { ok: true };
     }),
@@ -179,10 +193,12 @@ export const messagingHandlers: WhatsAppActionHandlers = {
     tryAction("unpin_message", async () => {
       const resolved = resolveKey(body.message_id, ctx.chat!.chatId);
       if ("error" in resolved) return { ok: false, error: resolved.error };
-      await ctx.sock.sendMessage(ctx.chat!.jid, {
-        pin: resolved.key,
-        type: proto.PinInChat.Type.UNPIN_FOR_ALL,
-      });
+      await boundedSend("unpin", () =>
+        ctx.sock.sendMessage(ctx.chat!.jid, {
+          pin: resolved.key,
+          type: proto.PinInChat.Type.UNPIN_FOR_ALL,
+        }),
+      );
       forgetPin(ctx.chat!.chatId, resolved.stored.msgId);
       return { ok: true };
     }),

package/src/frontend/whatsapp/actions/shared.ts

@@ -163,6 +163,57 @@ function outboundTextMarker(content: AnyMessageContent): string {
   return "";
 }
 
+// ── Serialized, time-bounded sends ─────────────────────────────────────────
+//
+// Ported from OpenClaw's socket-timing adapter. Two failure modes this
+// removes, both observed live:
+//   - a send on a dying socket hanging a turn indefinitely ("timed out
+//     waiting for message" with nothing delivered and no error surfaced),
+//   - interleaved sends racing each other's Baileys internals.
+// Every outbound WhatsApp operation goes through one FIFO per process
+// with a hard timeout; on timeout the queue advances so later sends
+// aren't wedged behind the dead one.
+
+const SEND_TIMEOUT_MS = 60_000;
+let sendTail: Promise<unknown> = Promise.resolve();
+
+export class WhatsAppSendTimeoutError extends Error {
+  constructor(operation: string) {
+    super(
+      `WhatsApp ${operation} timed out after ${SEND_TIMEOUT_MS / 1000}s — ` +
+        `delivery state unknown (the socket may be dead or reconnecting)`,
+    );
+    this.name = "WhatsAppSendTimeoutError";
+  }
+}
+
+/**
+ * Run one socket operation serialized behind every earlier one, bounded
+ * by SEND_TIMEOUT_MS. The timeout rejects THIS caller but releases the
+ * queue, so a wedged operation can't dam everything after it.
+ */
+export function boundedSend<T>(
+  operation: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  const prev = sendTail.catch(() => {});
+  const result = prev.then(() => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    return Promise.race([
+      run(),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new WhatsAppSendTimeoutError(operation)),
+          SEND_TIMEOUT_MS,
+        );
+        timer.unref?.();
+      }),
+    ]).finally(() => clearTimeout(timer));
+  });
+  sendTail = result.catch(() => {});
+  return result;
+}
+
 /**
  * Send one content payload, remember the resulting message so later
  * tool calls can address it, and report its Talon numeric id.
@@ -173,7 +224,9 @@ export async function sendContent(
   content: AnyMessageContent,
   options: { quoted?: WAMessage } = {},
 ): Promise<ActionResult> {
-  const sent = await ctx.sock.sendMessage(chat.jid, content, options);
+  const sent = await boundedSend("sendMessage", () =>
+    ctx.sock.sendMessage(chat.jid, content, options),
+  );
   ctx.gateway.incrementMessages(chat.numericChatId);
   if (!sent?.key) return { ok: true };
   const text =

package/src/frontend/whatsapp/auth-state.ts

@@ -0,0 +1,133 @@
+/**
+ * Atomic multi-file auth state for Baileys — a drop-in replacement for
+ * `useMultiFileAuthState` with two hardening changes ported from how
+ * OpenClaw persists WhatsApp credentials:
+ *
+ *   1. Every write is ATOMIC (tmp + rename via write-file-atomic). The
+ *      upstream helper uses a bare `writeFile`, so a daemon restart or
+ *      crash mid-write tears creds.json or a signal-key file. A torn
+ *      signal key is invisible until the server starts rejecting stanzas
+ *      ("smax-invalid: stanza rejected — likely stale device"), which is
+ *      the documented prelude to WhatsApp unlinking the device — the
+ *      exact sequence the live deployment logged before its
+ *      `device_removed` conflict.
+ *   2. Writes to the same file are serialized through a promise chain,
+ *      and `flushAuthWrites()` lets shutdown drain the queue before the
+ *      process exits, so `talon stop` can't strand a half-persisted key.
+ *
+ * The on-disk format is byte-compatible with upstream: same folder, same
+ * file names, same BufferJSON encoding — existing auth dirs just work.
+ */
+
+import { mkdir, readFile, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { BufferJSON, initAuthCreds, proto } from "baileys";
+import type { AuthenticationState, SignalDataTypeMap } from "baileys";
+
+/** file path → tail of its write chain. Module-level: one dir per process. */
+const writeTails = new Map<string, Promise<void>>();
+
+function enqueueWrite(
+  filePath: string,
+  task: () => Promise<void>,
+): Promise<void> {
+  const tail = (writeTails.get(filePath) ?? Promise.resolve())
+    .catch(() => {})
+    .then(task);
+  writeTails.set(
+    filePath,
+    tail.catch(() => {}),
+  );
+  return tail;
+}
+
+/** Resolve when every queued auth write has settled. Call before exit. */
+export async function flushAuthWrites(): Promise<void> {
+  await Promise.allSettled(writeTails.values());
+}
+
+/** Baileys' name mangling, kept identical for on-disk compatibility. */
+function fixFileName(file: string): string {
+  return file.replace(/\//g, "__").replace(/:/g, "-");
+}
+
+export async function useAtomicAuthState(folder: string): Promise<{
+  state: AuthenticationState;
+  saveCreds: () => Promise<void>;
+}> {
+  const info = await stat(folder).catch(() => undefined);
+  if (info && !info.isDirectory()) {
+    throw new Error(`not a directory: ${folder}`);
+  }
+  if (!info) await mkdir(folder, { recursive: true });
+
+  const writeData = (data: unknown, file: string): Promise<void> => {
+    const filePath = join(folder, fixFileName(file));
+    return enqueueWrite(filePath, () =>
+      writeFileAtomic(filePath, JSON.stringify(data, BufferJSON.replacer)),
+    );
+  };
+
+  const readData = async (file: string): Promise<unknown> => {
+    const filePath = join(folder, fixFileName(file));
+    // Reads wait for any pending write to that file, so a get() racing a
+    // set() sees the new value rather than the old file.
+    await (writeTails.get(filePath) ?? Promise.resolve()).catch(() => {});
+    try {
+      const raw = await readFile(filePath, "utf-8");
+      return JSON.parse(raw, BufferJSON.reviver);
+    } catch {
+      return null;
+    }
+  };
+
+  const removeData = (file: string): Promise<void> => {
+    const filePath = join(folder, fixFileName(file));
+    return enqueueWrite(filePath, async () => {
+      await unlink(filePath).catch(() => {});
+    });
+  };
+
+  const creds =
+    ((await readData("creds.json")) as ReturnType<
+      typeof initAuthCreds
+    > | null) ?? initAuthCreds();
+
+  return {
+    state: {
+      creds,
+      keys: {
+        get: async <T extends keyof SignalDataTypeMap>(
+          type: T,
+          ids: string[],
+        ) => {
+          const data: { [id: string]: SignalDataTypeMap[T] } = {};
+          await Promise.all(
+            ids.map(async (id) => {
+              let value = await readData(`${type}-${id}.json`);
+              if (type === "app-state-sync-key" && value) {
+                value = proto.Message.AppStateSyncKeyData.fromObject(value);
+              }
+              data[id] = value as SignalDataTypeMap[T];
+            }),
+          );
+          return data;
+        },
+        set: async (data) => {
+          const tasks: Promise<void>[] = [];
+          for (const category in data) {
+            const entries = data[category as keyof SignalDataTypeMap];
+            for (const id in entries) {
+              const value = entries[id];
+              const file = `${category}-${id}.json`;
+              tasks.push(value ? writeData(value, file) : removeData(file));
+            }
+          }
+          await Promise.all(tasks);
+        },
+      },
+    },
+    saveCreds: () => writeData(creds, "creds.json"),
+  };
+}

package/src/frontend/whatsapp/index.ts

@@ -15,10 +15,10 @@
  */
 
 import { rmSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
 import makeWASocket, {
-  DisconnectReason,
   isJidGroup,
-  useMultiFileAuthState,
   type WAMessage,
   type WASocket,
 } from "baileys";
@@ -53,8 +53,13 @@ import {
   seedMessageStore,
 } from "./message-store.js";
 import { runTurnWithRecovery, shouldReplyToCatchUp } from "./turn-recovery.js";
-import { nextPairingDelayMs, shouldNotifyPairingCode } from "./pairing.js";
+import { classifyClose, REPLACED_BACKOFF_MS } from "./pairing.js";
+import { isManualPairingActive, onPairingComplete } from "./pairing-lock.js";
+import { flushAuthWrites, useAtomicAuthState } from "./auth-state.js";
+import { makeWaLogger } from "./wa-logger.js";
 import { notifyAdmin } from "../../core/notify.js";
+import { registerPairingProvider } from "../../core/pairing-broker.js";
+import { beginPairingAttempt } from "./pairing-service.js";
 import {
   lookupWhatsAppChat,
   registerWhatsAppChat,
@@ -109,32 +114,6 @@ function extractText(msg: WAMessage): string {
   );
 }
 
-/**
- * Baileys logs through its own pino instance, far too chatty for a daemon
- * that already has structured logging. Bridge warn+ into Talon's log and
- * drop the rest. The shape is pino's minimal logger contract.
- */
-function makeWaLogger(): never {
-  const fmt = (args: unknown[]): string =>
-    args
-      .map((a) => (typeof a === "string" ? a : JSON.stringify(a)))
-      .join(" ")
-      .slice(0, 300);
-  const shim = {
-    level: "warn",
-    child: () => shim,
-    trace: () => {},
-    debug: () => {},
-    info: () => {},
-    warn: (...args: unknown[]) => logWarn("whatsapp", `baileys: ${fmt(args)}`),
-    error: (...args: unknown[]) =>
-      logError("whatsapp", `baileys: ${fmt(args)}`),
-    fatal: (...args: unknown[]) =>
-      logError("whatsapp", `baileys: ${fmt(args)}`),
-  };
-  return shim as never;
-}
-
 // ── Frontend factory ─────────────────────────────────────────────────────────
 
 export function createWhatsAppFrontend(
@@ -156,11 +135,8 @@ export function createWhatsAppFrontend(
   let sock: WASocket | null = null;
   let stopping = false;
   let reconnectDelay = RECONNECT_BASE_MS;
-  /** Consecutive failed pairing cycles since the last successful open. */
-  let failedPairingCycles = 0;
-  /** Codes issued this outage — throttles the admin notifications. */
-  let pairingCodesIssued = 0;
-  let lastPairingNotifyAt: number | undefined;
+  /** One "not linked" admin note per outage, not one per QR window. */
+  let unpairedNotified = false;
   /** Our own ids (phone and LID), once connected — for mention detection. */
   let selfIds: string[] = [];
 
@@ -432,8 +408,12 @@ export function createWhatsAppFrontend(
   }
 
   /** One socket lifetime. Resolves with what the caller should do next. */
-  async function connectOnce(): Promise<"reconnect" | "logged-out" | "stop"> {
-    const { state, saveCreds } = await useMultiFileAuthState(dirs.whatsappAuth);
+  async function connectOnce(): Promise<
+    "reconnect" | "logged-out" | "unpaired" | "stop"
+  > {
+    // Atomic replacement for Baileys' useMultiFileAuthState — same disk
+    // format, torn-write-proof (see auth-state.ts for why that matters).
+    const { state, saveCreds } = await useAtomicAuthState(dirs.whatsappAuth);
     const socket = makeWASocket({
       auth: state,
       logger: makeWaLogger(),
@@ -445,6 +425,11 @@ export function createWhatsAppFrontend(
       // a ~2½-minute socket lifetime in pairing mode, shorter than it
       // takes a human to pick up their phone and type the code.
       qrTimeout: 120_000,
+      // OpenClaw's production timings: the Baileys 20s connect timeout
+      // is tight on a loaded box, and a slightly faster keepalive spots
+      // a dead transport sooner.
+      connectTimeoutMs: 60_000,
+      keepAliveIntervalMs: 25_000,
     });
     sock = socket;
     socket.ev.on("creds.update", saveCreds);
@@ -470,54 +455,28 @@ export function createWhatsAppFrontend(
       }
     });
 
-    let pairingRequested = false;
     return new Promise((resolve) => {
       socket.ev.on("connection.update", (update) => {
         const { connection, lastDisconnect, qr } = update;
 
         if (qr && !state.creds.registered) {
-          if (settings.pairingNumber && !pairingRequested) {
-            pairingRequested = true;
-            socket
-              .requestPairingCode(bareId(settings.pairingNumber))
-              .then((code) => {
-                log(
-                  "whatsapp",
-                  `Pairing code: ${code} — enter it on ${settings.pairingNumber} ` +
-                    `via WhatsApp → Linked devices → Link with phone number`,
-                );
-                // The daemon log is where pairing codes go to die — the
-                // human who has to type this is on another frontend.
-                pairingCodesIssued++;
-                if (
-                  shouldNotifyPairingCode(
-                    pairingCodesIssued,
-                    lastPairingNotifyAt,
-                  )
-                ) {
-                  lastPairingNotifyAt = Date.now();
-                  void notifyAdmin(
-                    `📱 WhatsApp needs re-pairing.\n` +
-                      `Code: ${code}\n` +
-                      `On the phone with ${settings.pairingNumber}: WhatsApp → ` +
-                      `Linked devices → Link with phone number.\n` +
-                      `Valid for a few minutes; if it expires, the next code ` +
-                      `arrives automatically.`,
-                  );
-                }
-              })
-              .catch((err) =>
-                logError(
-                  "whatsapp",
-                  `Pairing code request failed: ${err instanceof Error ? err.message : err}`,
-                ),
-              );
-          } else if (!settings.pairingNumber) {
-            log(
-              "whatsapp",
-              "Scan with WhatsApp → Linked devices → Link a device:",
+          // The frontend NEVER requests pairing codes on its own — that
+          // loop once burned ~30 codes in 80 minutes and rate-limited
+          // the account. Pairing is on demand via /whatsapp pair
+          // (core/pairing-broker.ts). The terminal QR stays for
+          // foreground first-run setups without a Telegram admin.
+          log(
+            "whatsapp",
+            "Not linked — pair on demand with /whatsapp pair (Telegram), " +
+              "or scan below: WhatsApp → Linked devices → Link a device",
+          );
+          qrcode.generate(qr, { small: true });
+          if (!unpairedNotified) {
+            unpairedNotified = true;
+            void notifyAdmin(
+              "📱 WhatsApp is not linked. Send /whatsapp pair when you're " +
+                "ready and I'll reply with a QR to scan.",
             );
-            qrcode.generate(qr, { small: true });
           }
         }
 
@@ -527,12 +486,10 @@ export function createWhatsAppFrontend(
             .filter((id): id is string => Boolean(id))
             .map(bareId);
           reconnectDelay = RECONNECT_BASE_MS;
-          if (pairingCodesIssued > 0) {
-            void notifyAdmin("✅ WhatsApp re-linked and connected.");
+          if (unpairedNotified) {
+            void notifyAdmin("✅ WhatsApp linked and connected.");
           }
-          failedPairingCycles = 0;
-          pairingCodesIssued = 0;
-          lastPairingNotifyAt = undefined;
+          unpairedNotified = false;
           log(
             "whatsapp",
             `Connected as ${socket.user?.name ?? "?"} (${selfIds.join("/") || "?"})`,
@@ -545,17 +502,81 @@ export function createWhatsAppFrontend(
               { output?: { statusCode?: number } } | undefined
           )?.output?.statusCode;
           if (stopping) return resolve("stop");
-          if (code === DisconnectReason.loggedOut) return resolve("logged-out");
-          log(
-            "whatsapp",
-            `Connection closed (code ${code ?? "?"}) — reconnecting`,
-          );
-          return resolve("reconnect");
+          const disposition = classifyClose(code, state.creds.registered);
+          switch (disposition.kind) {
+            case "pairing-accepted":
+              // 515 right after a pairing code/QR is SUCCESS, not an
+              // error: WhatsApp requires one reconnect with the same
+              // credentials to complete the login.
+              log(
+                "whatsapp",
+                "Pairing accepted (515) — reconnecting to complete login",
+              );
+              reconnectDelay = RECONNECT_BASE_MS;
+              return resolve("reconnect");
+            case "replaced":
+              // Another socket owns this session (440). Fighting it with
+              // an instant reconnect just steals the session back and
+              // forth; sit out a full minute instead.
+              logWarn(
+                "whatsapp",
+                "Connection replaced by another client (440) — backing off",
+              );
+              reconnectDelay = REPLACED_BACKOFF_MS;
+              return resolve("reconnect");
+            case "logged-out":
+              return resolve("logged-out");
+            default:
+              // A socket that died without ever registering is a pairing
+              // window that expired — reconnecting would just open QR
+              // session after QR session against WhatsApp's servers.
+              // Park instead; /whatsapp pair opens the next one.
+              if (!state.creds.registered) return resolve("unpaired");
+              log(
+                "whatsapp",
+                `Connection closed (code ${code ?? "?"}) — reconnecting`,
+              );
+              return resolve("reconnect");
+          }
         }
       });
     });
   }
 
+  /**
+   * Wait until a manual pairing completes (event from pairing-lock) or
+   * registered creds appear on disk, polling slowly. Resolves promptly
+   * when the frontend is stopping.
+   */
+  async function parkUntilPaired(): Promise<void> {
+    while (!stopping) {
+      if (!isManualPairingActive()) {
+        try {
+          const raw = await readFile(
+            resolvePath(dirs.whatsappAuth, "creds.json"),
+            "utf-8",
+          );
+          if ((JSON.parse(raw) as { registered?: boolean }).registered) return;
+        } catch {
+          /* no creds yet — stay parked */
+        }
+      }
+      const paired = await new Promise<boolean>((r) => {
+        const off = onPairingComplete(() => {
+          clearTimeout(timer);
+          off();
+          r(true);
+        });
+        const timer = setTimeout(() => {
+          off();
+          r(false);
+        }, 30_000);
+        timer.unref?.();
+      });
+      if (paired) return;
+    }
+  }
+
   return {
     name: "whatsapp",
     context,
@@ -584,6 +605,13 @@ export function createWhatsAppFrontend(
 
     async init() {
       setWhatsAppBotName(config.botDisplayName);
+      // On-demand pairing, driven from another frontend's admin command
+      // (/whatsapp pair on Telegram) through the core broker.
+      registerPairingProvider({
+        label: "WhatsApp",
+        isLinked: () => Boolean(sock?.user),
+        begin: () => beginPairingAttempt(settings.pairingNumber),
+      });
       // The in-memory message-id counter restarts at its base every boot,
       // but history persists — seed it past what the table already holds
       // so post-restart messages don't re-issue ids INSERT OR IGNORE then
@@ -600,7 +628,13 @@ export function createWhatsAppFrontend(
     async start() {
       log("whatsapp", "WhatsApp frontend starting (Baileys multi-device)");
       while (!stopping) {
-        let outcome: "reconnect" | "logged-out" | "stop";
+        // A manual pairing attempt owns the auth dir: two sockets on one
+        // keypair corrupt it and burn rate-limited pairing attempts.
+        if (isManualPairingActive()) {
+          await new Promise((r) => setTimeout(r, 5_000));
+          continue;
+        }
+        let outcome: "reconnect" | "logged-out" | "unpaired" | "stop";
         try {
           outcome = await connectOnce();
         } catch (err) {
@@ -614,33 +648,29 @@ export function createWhatsAppFrontend(
         if (outcome === "stop" || stopping) break;
         if (outcome === "logged-out") {
           // These credentials are dead — WhatsApp unlinked the device.
-          // Wipe them so the next attempt pairs fresh instead of looping
-          // on a session that can never authenticate.
+          // Wipe them and PARK. Re-pairing needs a human holding the
+          // phone, so it happens strictly on demand (Telegram's
+          // `/whatsapp pair`) — every automatic retry policy tried here,
+          // including a 30-minute backoff ladder, still burned codes
+          // against WhatsApp's rate limit until scans failed with
+          // "couldn't connect device" for everyone.
           logWarn(
             "whatsapp",
-            "Logged out by WhatsApp — clearing auth state, re-pairing",
+            "Logged out by WhatsApp — parked until /whatsapp pair re-links",
+          );
+          void notifyAdmin(
+            "⚠️ WhatsApp unlinked this device. When you're ready to " +
+              "re-link, send /whatsapp pair and scan the QR I reply with. " +
+              "Nothing is retried until then.",
           );
-          if (failedPairingCycles === 0 && pairingCodesIssued === 0) {
-            void notifyAdmin(
-              "⚠️ WhatsApp unlinked this device (logged out). " +
-                "Re-pairing — a pairing code follows.",
-            );
-          }
           rmSync(dirs.whatsappAuth, { recursive: true, force: true });
-          // Pairing needs a HUMAN to type a code, so this is not a
-          // network-blip backoff: retry quickly once, then space cycles
-          // out (5→10→20→30-min cap). The old immediate loop burned a
-          // fresh code every ~2½ minutes forever — each invalidating the
-          // last, at exactly the cadence WhatsApp rate-limits.
-          failedPairingCycles++;
-          const pairingDelay = nextPairingDelayMs(failedPairingCycles - 1);
-          if (pairingDelay > 0) {
-            log(
-              "whatsapp",
-              `Next pairing attempt in ${Math.round(pairingDelay / 60_000)}m`,
-            );
-            await new Promise((r) => setTimeout(r, pairingDelay));
-          }
+          await parkUntilPaired();
+          reconnectDelay = RECONNECT_BASE_MS;
+          continue;
+        }
+        if (outcome === "unpaired") {
+          log("whatsapp", "Not paired — parked until /whatsapp pair links");
+          await parkUntilPaired();
           reconnectDelay = RECONNECT_BASE_MS;
           continue;
         }
@@ -652,12 +682,17 @@ export function createWhatsAppFrontend(
 
     async stop() {
       stopping = true;
+      registerPairingProvider(null);
       try {
         sock?.end(undefined);
       } catch {
         /* already closed */
       }
       sock = null;
+      // Drain queued credential writes before the process exits — a key
+      // half-written at shutdown is invisible until the server starts
+      // rejecting stanzas with it.
+      await flushAuthWrites();
       await gateway.stop();
       log("whatsapp", "WhatsApp frontend stopped");
     },

package/src/frontend/whatsapp/pairing-lock.ts

@@ -0,0 +1,44 @@
+/**
+ * Coordination between the WhatsApp frontend's connection loop and a
+ * manual pairing attempt (driven from Telegram via the core broker).
+ *
+ * Only one Baileys socket may own the auth dir at a time: a manual
+ * pairing socket racing the frontend's reconnect loop corrupts the
+ * half-registered credentials and burns pairing attempts against
+ * WhatsApp's rate limits. The loop checks `isManualPairingActive()`
+ * before every connect and parks; a completed pairing fires the
+ * completion event so a parked loop wakes immediately instead of on its
+ * next poll.
+ */
+
+let active = false;
+const completionCallbacks = new Set<() => void>();
+
+export function acquireManualPairing(): boolean {
+  if (active) return false;
+  active = true;
+  return true;
+}
+
+export function releaseManualPairing(paired: boolean): void {
+  active = false;
+  if (paired) {
+    for (const cb of completionCallbacks) cb();
+  }
+}
+
+export function isManualPairingActive(): boolean {
+  return active;
+}
+
+/** Returns an unsubscribe function. */
+export function onPairingComplete(cb: () => void): () => void {
+  completionCallbacks.add(cb);
+  return () => completionCallbacks.delete(cb);
+}
+
+/** Test seam. */
+export function resetPairingLock(): void {
+  active = false;
+  completionCallbacks.clear();
+}

package/src/frontend/whatsapp/pairing-service.ts

@@ -0,0 +1,187 @@
+/**
+ * One bounded, on-demand WhatsApp pairing attempt — the provider behind
+ * `core/pairing-broker.ts`, invoked from Telegram's /whatsapp command.
+ *
+ * One command = one attempt: a fresh socket, the FIRST QR (rendered to
+ * PNG for delivery as a photo) plus a phone-number code when configured,
+ * a single ~2-minute window, then a definite outcome. No retries, no
+ * background loops — the human re-runs the command when they're ready.
+ * Entering a code / scanning ends with Baileys' 515 restartRequired,
+ * which is SUCCESS: one same-creds reconnect completes the login.
+ */
+
+import { rmSync } from "node:fs";
+import makeWASocket, { type WASocket } from "baileys";
+import QRCode from "qrcode";
+import type {
+  PairingAttempt,
+  PairingOutcome,
+} from "../../core/pairing-broker.js";
+import { log, logError } from "../../util/log.js";
+import { dirs } from "../../util/paths.js";
+import { useAtomicAuthState, flushAuthWrites } from "./auth-state.js";
+import { classifyClose } from "./pairing.js";
+import { acquireManualPairing, releaseManualPairing } from "./pairing-lock.js";
+import { bareId } from "./identity.js";
+import { makeWaLogger } from "./wa-logger.js";
+
+/** How long one attempt may run before reporting "expired". */
+const ATTEMPT_WINDOW_MS = 150_000;
+/** How long we wait for the first QR before calling the attempt failed. */
+const FIRST_QR_TIMEOUT_MS = 20_000;
+
+export async function beginPairingAttempt(
+  pairingNumber?: string,
+): Promise<PairingAttempt> {
+  if (!acquireManualPairing()) {
+    throw new Error("A pairing attempt is already in progress");
+  }
+
+  let sock: WASocket | null = null;
+  let settled = false;
+  let paired = false;
+  let resolveResult!: (o: PairingOutcome) => void;
+  const result = new Promise<PairingOutcome>((r) => (resolveResult = r));
+
+  const settle = (outcome: PairingOutcome) => {
+    if (settled) return;
+    settled = true;
+    paired = outcome.ok;
+    try {
+      sock?.end(undefined);
+    } catch {
+      /* closed */
+    }
+    void flushAuthWrites().finally(() => releaseManualPairing(paired));
+    resolveResult(outcome);
+  };
+
+  const windowTimer = setTimeout(
+    () => settle({ ok: false, reason: "expired" }),
+    ATTEMPT_WINDOW_MS,
+  );
+  windowTimer.unref?.();
+
+  /** One socket generation; 515 recurses once with the same creds. */
+  const connect = async (afterPairing: boolean): Promise<void> => {
+    const { state, saveCreds } = await useAtomicAuthState(dirs.whatsappAuth);
+    const socket = makeWASocket({
+      auth: state,
+      logger: makeWaLogger(),
+      markOnlineOnConnect: false,
+      qrTimeout: 120_000,
+      connectTimeoutMs: 60_000,
+    });
+    sock = socket;
+    socket.ev.on("creds.update", saveCreds);
+    socket.ev.on("connection.update", ({ connection, lastDisconnect, qr }) => {
+      if (qr && !afterPairing && !firstQr.done) {
+        firstQr.done = true;
+        firstQr.resolve(qr);
+      }
+      if (connection === "open") {
+        const identity = bareId(socket.user?.id) || "unknown";
+        log("whatsapp", `Manual pairing succeeded — linked as ${identity}`);
+        settle({ ok: true, identity });
+      }
+      if (connection === "close") {
+        const code = (
+          lastDisconnect?.error as
+            { output?: { statusCode?: number } } | undefined
+        )?.output?.statusCode;
+        const disposition = classifyClose(code, state.creds.registered);
+        if (disposition.kind === "pairing-accepted" && !settled) {
+          // Scan/code accepted — finish the login on the same creds.
+          log("whatsapp", "Pairing accepted (515) — completing login");
+          void connect(true).catch((err) =>
+            settle({
+              ok: false,
+              reason: "failed",
+              detail: err instanceof Error ? err.message : String(err),
+            }),
+          );
+          return;
+        }
+        if (!settled) {
+          settle({
+            ok: false,
+            reason: "expired",
+            detail: `connection closed (code ${code ?? "?"})`,
+          });
+        }
+      }
+    });
+    return;
+  };
+
+  const firstQr: {
+    done: boolean;
+    resolve: (qr: string) => void;
+    promise: Promise<string>;
+  } = (() => {
+    let resolve!: (qr: string) => void;
+    const promise = new Promise<string>((r) => (resolve = r));
+    return { done: false, resolve, promise };
+  })();
+
+  try {
+    // A half-registered keypair from an earlier abandoned attempt 401s
+    // instantly; start clean. Registered creds are never wiped here —
+    // begin() isn't offered when the account is already linked.
+    rmSync(dirs.whatsappAuth, { recursive: true, force: true });
+    await connect(false);
+
+    const qrString = await Promise.race([
+      firstQr.promise,
+      new Promise<null>((r) => {
+        const t = setTimeout(() => r(null), FIRST_QR_TIMEOUT_MS);
+        t.unref?.();
+      }),
+    ]);
+    if (!qrString) {
+      settle({ ok: false, reason: "failed", detail: "no QR from server" });
+      clearTimeout(windowTimer);
+      return {
+        result,
+        cancel: () => settle({ ok: false, reason: "cancelled" }),
+      };
+    }
+
+    const qrPng = new Uint8Array(
+      await QRCode.toBuffer(qrString, {
+        type: "png",
+        errorCorrectionLevel: "M",
+        scale: 8,
+        margin: 2,
+      }),
+    );
+
+    let code: string | undefined;
+    if (pairingNumber) {
+      try {
+        code = await sock!.requestPairingCode(bareId(pairingNumber));
+      } catch (err) {
+        // The QR still works; the code is a bonus.
+        logError(
+          "whatsapp",
+          `pairing code request failed: ${err instanceof Error ? err.message : err}`,
+        );
+      }
+    }
+
+    return {
+      qrPng,
+      ...(code ? { code } : {}),
+      result,
+      cancel: () => settle({ ok: false, reason: "cancelled" }),
+    };
+  } catch (err) {
+    settle({
+      ok: false,
+      reason: "failed",
+      detail: err instanceof Error ? err.message : String(err),
+    });
+    clearTimeout(windowTimer);
+    return { result, cancel: () => {} };
+  }
+}

package/src/frontend/whatsapp/pairing.ts

@@ -1,40 +1,45 @@
 /**
- * Pairing-recovery policy for the WhatsApp frontend.
+ * Pairing policy for the WhatsApp frontend.
  *
- * When WhatsApp unlinks the device (stream conflict `device_removed`,
- * a manual unlink, an account ban), recovery needs a human: someone must
- * enter a pairing code on the phone. The old loop treated a logout like
- * a network blip — wipe auth, reconnect immediately, request a fresh
- * code, time out, repeat — which generated a new code every ~2½ minutes
- * forever (26 codes in 80 minutes on the live deployment), each one
- * invalidating the last, all of them visible only in the daemon log.
- * That cadence is also exactly the shape WhatsApp rate-limits.
- *
- * Policy, kept pure here so it is testable without a socket:
- *   - retry pairing on a growing delay (quick first retry, 30-min cap),
- *   - surface each fresh code to the admin over a live frontend, but
- *     after the first few, at most one notification per hour — each
- *     notification always carries the CURRENT code.
+ * Pairing is strictly on demand (Telegram's /whatsapp pair → the core
+ * pairing broker): the frontend never requests codes by itself. Every
+ * automatic retry policy tried here — including a 30-minute backoff
+ * ladder — still burned pairing codes against WhatsApp's rate limit
+ * until every scan failed with "couldn't connect device". What remains
+ * is the close-code taxonomy the connection loop reads.
  */
 
-/** Delay before pairing attempt `attempt` (1-based, i.e. after `attempt` failures). */
-export function nextPairingDelayMs(failedAttempts: number): number {
-  if (failedAttempts <= 0) return 0;
-  const LADDER = [5_000, 5 * 60_000, 10 * 60_000, 20 * 60_000];
-  const CAP = 30 * 60_000;
-  return LADDER[failedAttempts - 1] ?? CAP;
-}
+// ── Close-code taxonomy ─────────────────────────────────────────────────────
 
-/** First codes always notify; afterwards at most one per hour. */
-export const PAIRING_NOTIFY_FREE_CODES = 3;
-export const PAIRING_NOTIFY_MIN_GAP_MS = 60 * 60_000;
+/**
+ * What one Baileys `connection: "close"` means for the reconnect loop.
+ * Ported from how OpenClaw's connection controller reads DisconnectReason
+ * — the old handler knew only "loggedOut or not", which turned pairing
+ * success (515) into an anonymous reconnect and let another client's
+ * takeover (440) start a reconnect fight.
+ */
+export type CloseDisposition =
+  | { kind: "pairing-accepted" } // 515: code entered — reconnect NOW, same creds
+  | { kind: "replaced" } // 440: another socket owns the session — back off hard
+  | { kind: "logged-out"; midPairing: boolean } // 401: dead creds
+  | { kind: "reconnect" }; // everything else: transient
 
-export function shouldNotifyPairingCode(
-  codesIssued: number,
-  lastNotifiedAt: number | undefined,
-  now: number = Date.now(),
-): boolean {
-  if (codesIssued <= PAIRING_NOTIFY_FREE_CODES) return true;
-  if (lastNotifiedAt === undefined) return true;
-  return now - lastNotifiedAt >= PAIRING_NOTIFY_MIN_GAP_MS;
+export function classifyClose(
+  statusCode: number | undefined,
+  credsRegistered: boolean,
+): CloseDisposition {
+  switch (statusCode) {
+    case 515: // DisconnectReason.restartRequired — expected right after pairing
+      return { kind: "pairing-accepted" };
+    case 440: // DisconnectReason.connectionReplaced
+      return { kind: "replaced" };
+    case 401: // DisconnectReason.loggedOut
+    case 403: // DisconnectReason.forbidden — account-level, same recovery
+      return { kind: "logged-out", midPairing: !credsRegistered };
+    default:
+      return { kind: "reconnect" };
+  }
 }
+
+/** How long to sit out after a 440 — another client owns the session. */
+export const REPLACED_BACKOFF_MS = 60_000;

package/src/frontend/whatsapp/wa-logger.ts

@@ -0,0 +1,31 @@
+/**
+ * Baileys logs through its own pino instance, far too chatty for a daemon
+ * that already has structured logging. Bridge warn+ into Talon's log and
+ * drop the rest. The shape is pino's minimal logger contract.
+ *
+ * Shared by the frontend socket (index.ts) and the manual pairing socket
+ * (pairing-service.ts).
+ */
+
+import { logError, logWarn } from "../../util/log.js";
+
+export function makeWaLogger(): never {
+  const fmt = (args: unknown[]): string =>
+    args
+      .map((a) => (typeof a === "string" ? a : JSON.stringify(a)))
+      .join(" ")
+      .slice(0, 300);
+  const shim = {
+    level: "warn",
+    child: () => shim,
+    trace: () => {},
+    debug: () => {},
+    info: () => {},
+    warn: (...args: unknown[]) => logWarn("whatsapp", `baileys: ${fmt(args)}`),
+    error: (...args: unknown[]) =>
+      logError("whatsapp", `baileys: ${fmt(args)}`),
+    fatal: (...args: unknown[]) =>
+      logError("whatsapp", `baileys: ${fmt(args)}`),
+  };
+  return shim as never;
+}

package/src/util/config.ts

@@ -253,8 +253,9 @@ const whatsappConfigSchema = z
      */
     respondMode: z.enum(["mention", "all"]).default("mention"),
     /**
-     * Pair by phone-number code instead of QR: the account's number in
-     * E.164 digits without the plus (e.g. "353871234567"). Omit for QR.
+     * The account's own number in E.164 digits without the plus (e.g.
+     * "353871234567"). When set, on-demand pairing (/whatsapp pair)
+     * offers a phone-number code alongside the QR.
      */
     pairingNumber: z.string().optional(),
     /** Mark handled inbound messages as read (blue ticks). */