talon-agent 3.26.0 → 3.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.26.0",
+  "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/index.ts

@@ -15,6 +15,8 @@
  */
 
 import { rmSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve as resolvePath } from "node:path";
 import makeWASocket, {
   isJidGroup,
   type WAMessage,
@@ -51,14 +53,13 @@ import {
   seedMessageStore,
 } from "./message-store.js";
 import { runTurnWithRecovery, shouldReplyToCatchUp } from "./turn-recovery.js";
-import {
-  classifyClose,
-  nextPairingDelayMs,
-  REPLACED_BACKOFF_MS,
-  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,
@@ -113,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(
@@ -160,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[] = [];
 
@@ -436,7 +408,9 @@ export function createWhatsAppFrontend(
   }
 
   /** One socket lifetime. Resolves with what the caller should do next. */
-  async function connectOnce(): Promise<"reconnect" | "logged-out" | "stop"> {
+  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);
@@ -481,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 });
           }
         }
 
@@ -538,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("/") || "?"})`,
@@ -581,6 +527,11 @@ export function createWhatsAppFrontend(
             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`,
@@ -592,6 +543,40 @@ export function createWhatsAppFrontend(
     });
   }
 
+  /**
+   * 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,
@@ -620,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
@@ -636,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) {
@@ -650,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;
         }
@@ -688,6 +682,7 @@ export function createWhatsAppFrontend(
 
     async stop() {
       stopping = true;
+      registerPairingProvider(null);
       try {
         sock?.end(undefined);
       } catch {

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,44 +1,14 @@
 /**
- * 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;
-}
-
-/** 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;
-
-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;
-}
-
 // ── Close-code taxonomy ─────────────────────────────────────────────────────
 
 /**

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). */