talon-agent 3.26.0 → 3.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -18,7 +18,7 @@
     "chatbot"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=24.15"
   },
   "type": "module",
   "main": "./src/index.ts",
@@ -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/prompts/system/heartbeat-agent.md

@@ -40,7 +40,7 @@ is a primary responsibility, not an optional extra. Goal tools
 (`update_goal`, `list_goals`, …) require an explicit `chat_id` parameter
 in heartbeat mode — use the chat id shown next to each goal.
 
-OUTBOUND MESSAGING: You also have access to the frontend tool servers — {{toolList}} — which expose `send`, `react`, and the rest of the messaging surface. Because there is NO ambient chat in heartbeat mode, every outbound tool call MUST include an explicit `chat_id` parameter. The bridge promotes that chat_id to the routing target, so `send(type="text", text="...", chat_id=N)` from `{{exampleFrontend}}-tools` delivers a message to chat N on that frontend. Known chat IDs live in your memory.md (per-frontend — for Telegram, Dylan's DM ID and group IDs are recorded; other frontends list their own). Without `chat_id`, the gateway returns 'No active chat context and no explicit numeric chat_id'.
+OUTBOUND MESSAGING: You also have access to the frontend tool servers — {{toolList}} — which expose `send`, `react`, and the rest of the messaging surface. Because there is NO ambient chat in heartbeat mode, every outbound tool call MUST include an explicit `chat_id` parameter. The bridge promotes that chat_id to the routing target, so `send(type="text", text="...", chat_id=N)` from `{{exampleFrontend}}-tools` delivers a message to chat N on that frontend. Known chat IDs live in your memory.md (per-frontend — for Telegram, Dylan's DM ID and group IDs are recorded; other frontends list their own). Without `chat_id`, the gateway returns 'No active chat context and no explicit numeric chat_id'. Cross-frontend: every tool server also carries `send_via(frontend=..., target=..., text=...)`, which delivers through ANY enabled frontend — target is the numeric chat id as a string, or for WhatsApp a phone number ("+353871234567") or wa_dm_/wa_group_ id.
 
 Reaching out is part of the job, not an exception: when a run turns up
 something a user would genuinely want to know — a goal completed or

package/src/core/engine/gateway-actions/cross-send.ts

@@ -0,0 +1,91 @@
+/**
+ * Cross-frontend send — the server side of the `send_via` tool.
+ *
+ * A chat-free shared action: any session (an active Telegram chat, the
+ * heartbeat, a dream run) delivers a plain text message through ANY
+ * enabled messaging frontend by naming it explicitly. Explicit is the
+ * point — the gateway's normal chat_id routing infers the owning
+ * frontend from the numeric id's shape, and WhatsApp's hash-derived ids
+ * also match the Telegram matcher, so a cross-frontend send routed that
+ * way lands on the wrong platform once the originating turn's context
+ * is cleared.
+ *
+ * Core never imports src/frontend (dependency-cruiser enforces it), so
+ * dispatch goes through a broker: `Gateway.registerFrontendHandler`
+ * mirrors each frontend's action handler here, and the action calls the
+ * target's own `send_message` — the one send action every messaging
+ * frontend implements. A numeric target doubles as the handler's chatId
+ * key, so id-addressed frontends (telegram, discord, teams, native)
+ * need no changes; non-numeric forms (WhatsApp phone numbers, wa_* ids)
+ * ride in `body.target` for the frontend's adapter to resolve.
+ */
+
+import type { FrontendActionHandler } from "../../types.js";
+import type { SharedActionHandlers } from "./types.js";
+
+const targets = new Map<string, FrontendActionHandler>();
+
+/**
+ * Broker registration — called by `Gateway.registerFrontendHandler` as
+ * each frontend wires up (and with null on deregistration), so the set
+ * of reachable targets is exactly the set of enabled frontends.
+ */
+export function registerCrossSendTarget(
+  name: string,
+  handler: FrontendActionHandler | null,
+): void {
+  if (handler === null) targets.delete(name);
+  else targets.set(name, handler);
+}
+
+export const crossSendHandlers: SharedActionHandlers = {
+  send_via: async (body) => {
+    const frontend = String(body.frontend ?? "")
+      .trim()
+      .toLowerCase();
+    const target = String(body.target ?? "").trim();
+    const text = String(body.text ?? "");
+    if (!frontend) {
+      return { ok: false, error: "send_via: frontend is required" };
+    }
+    if (!target) {
+      return { ok: false, error: "send_via: target is required" };
+    }
+    if (!text.trim()) {
+      return { ok: false, error: "send_via: text is required" };
+    }
+    const handler = targets.get(frontend);
+    if (!handler) {
+      const enabled = [...targets.keys()].sort().join(", ") || "none";
+      return {
+        ok: false,
+        error: `send_via: the ${frontend} frontend is not enabled (enabled: ${enabled})`,
+      };
+    }
+    // A numeric target is the handler's chatId key; other forms travel in
+    // body.target for the frontend's adapter to resolve. 0 is the same
+    // "no chat" sentinel the chat-free dispatch itself uses.
+    const numericTarget = /^-?\d+$/.test(target) ? Number(target) : 0;
+    const result = await handler(
+      { action: "send_message", text, target },
+      numericTarget,
+    );
+    if (!result) {
+      return {
+        ok: false,
+        error: `send_via: the ${frontend} frontend does not implement send_message`,
+      };
+    }
+    return result;
+  },
+};
+
+/**
+ * send_via is chat-free by design: it reads only its own explicit target
+ * and the broker, so it stays reachable from heartbeat/background runs —
+ * and skipping chat resolution is what keeps the wrong-frontend numeric
+ * routing hazard out of the path entirely.
+ */
+export const crossSendChatFreeActions: ReadonlySet<string> = new Set([
+  "send_via",
+]);

package/src/core/engine/gateway-actions/index.ts

@@ -17,6 +17,7 @@
  *   - `plugins`   — plugin hot-reload
  *   - `models`    — model / backend discovery
  *   - `mesh`      — companion device mesh (presence + location)
+ *   - `cross-send` — explicit-target sends through any enabled frontend
  */
 
 import type { ActionResult } from "../../types.js";
@@ -31,7 +32,11 @@ import { scriptHandlers } from "./scripts.js";
 import { skillHandlers } from "./skills.js";
 import { pluginHandlers } from "./plugins.js";
 import { modelHandlers } from "./models.js";
-import { meshHandlers, chatFreeActions } from "./mesh.js";
+import {
+  meshHandlers,
+  chatFreeActions as meshChatFreeActions,
+} from "./mesh.js";
+import { crossSendHandlers, crossSendChatFreeActions } from "./cross-send.js";
 import { nativeHandlers } from "./native.js";
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
@@ -48,9 +53,19 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
   ...pluginHandlers,
   ...modelHandlers,
   ...meshHandlers,
+  ...crossSendHandlers,
   ...nativeHandlers,
 });
 
+/**
+ * All chat-free actions — each domain module declares its own set, merged
+ * here into the one view the gateway (and `isChatFreeAction`) consults.
+ */
+const chatFreeActions: ReadonlySet<string> = new Set([
+  ...meshChatFreeActions,
+  ...crossSendChatFreeActions,
+]);
+
 export async function handleSharedAction(
   body: Record<string, unknown>,
   chatId: number,

package/src/core/engine/gateway.ts

@@ -25,6 +25,7 @@ import {
   handleChatFreeAction,
   isChatFreeAction,
 } from "./gateway-actions/index.js";
+import { registerCrossSendTarget } from "./gateway-actions/cross-send.js";
 import {
   handleHubRequest,
   getHubSessionCount,
@@ -154,6 +155,9 @@ export class Gateway {
     name: string,
     handler: FrontendActionHandler | null,
   ): void {
+    // Mirror into the cross-send broker so the chat-free `send_via`
+    // action can dispatch to any enabled frontend by explicit name.
+    registerCrossSendTarget(name, handler);
     if (handler === null) {
       this.frontendHandlers.delete(name);
       return;

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/core/tools/cross-send.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+/**
+ * Cross-frontend send. Deliberately NOT frontend-restricted (the meshTools
+ * pattern): the whole point is reaching a DIFFERENT enabled frontend than
+ * the one the session lives on — a Telegram chat messaging a WhatsApp
+ * number, the heartbeat reaching WhatsApp when only telegram-tools is
+ * mounted. The gateway serves it as a chat-free action (see
+ * engine/gateway-actions/cross-send.ts), so it works from background runs
+ * with no ambient chat, and the target frontend is named EXPLICITLY —
+ * never inferred from the shape of a numeric id.
+ */
+export const crossSendTools: ToolDefinition[] = [
+  {
+    name: "send_via",
+    description: `Send a plain text message through ANY enabled messaging frontend — including one this chat does not live on. Use it to reach someone on another platform (e.g. from Telegram or a heartbeat run, message a WhatsApp number). For the current chat, keep using the normal delivery tools (end_turn / send / send_message).
+
+Target forms:
+- whatsapp: a phone number with country code ("+353871234567" or "353871234567"), a wa_dm_<number>/wa_group_<id> chat id, or a raw JID; a bare numeric chat id works only for chats already seen since startup
+- telegram / discord / teams / native: the numeric chat id, as a string (Telegram supergroups/channels are negative, DMs positive)
+
+Examples:
+  send_via(frontend="whatsapp", target="+353871234567", text="On my way")
+  send_via(frontend="telegram", target="-1001426819337", text="Build is green")
+
+Fails with a clear error when the named frontend is not enabled or not connected.`,
+    schema: {
+      frontend: z
+        .enum(["telegram", "whatsapp", "discord", "teams", "native"])
+        .describe("Messaging frontend to deliver through."),
+      target: z
+        .string()
+        .describe(
+          "Destination chat: numeric chat id as a string; for WhatsApp also a phone number with country code or a wa_dm_/wa_group_ id.",
+        ),
+      text: z
+        .string()
+        .describe(
+          "Message text. Markdown supported where the platform supports it.",
+        ),
+    },
+    execute: (params, bridge) => bridge("send_via", params),
+    tag: "messaging",
+  },
+];

package/src/core/tools/index.ts

@@ -22,6 +22,7 @@ import { webTools } from "./web.js";
 import { adminTools } from "./admin.js";
 import { modelTools } from "./models.js";
 import { meshTools } from "./mesh.js";
+import { crossSendTools } from "./cross-send.js";
 import { moderationTools } from "./moderation.js";
 import { nativeTools } from "./native.js";
 
@@ -42,6 +43,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...adminTools,
   ...modelTools,
   ...meshTools,
+  ...crossSendTools,
   ...moderationTools,
 ];
 

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/index.ts

@@ -19,7 +19,11 @@
 import type { WASocket } from "baileys";
 import type { Gateway } from "../../../core/engine/gateway.js";
 import type { ActionResult } from "../../../core/types.js";
-import { lookupWhatsAppChat } from "../registry.js";
+import {
+  lookupWhatsAppChat,
+  resolveWhatsAppTarget,
+  type WhatsAppChatInfo,
+} from "../registry.js";
 import { chatInfoHandlers } from "./chat-info.js";
 import { mediaHandlers } from "./media.js";
 import { messagingHandlers } from "./messaging.js";
@@ -57,7 +61,26 @@ export function createWhatsAppActionHandler(
       return { ok: false, error: "WhatsApp socket is not connected" };
     }
 
-    const chat = lookupWhatsAppChat(chatId) ?? null;
+    // An explicit cross-send target (send_via) names the destination
+    // itself — phone number, wa_* id, or JID — and may be a chat this
+    // process has never seen; resolveWhatsAppTarget registers it so the
+    // usual numeric-id routing works from then on. Without a target,
+    // the gateway's numeric chatId (an active chat) is the destination.
+    let chat: WhatsAppChatInfo | null;
+    if (body.target !== undefined) {
+      chat = resolveWhatsAppTarget(body.target) ?? null;
+      if (!chat) {
+        return {
+          ok: false,
+          error:
+            `Unresolvable WhatsApp target "${String(body.target)}" — use a ` +
+            `phone number with country code, a wa_dm_/wa_group_ id, or a ` +
+            `known chat id.`,
+        };
+      }
+    } else {
+      chat = lookupWhatsAppChat(chatId) ?? null;
+    }
     if (!chat && !CHATLESS_ACTIONS.has(action)) {
       return {
         ok: false,

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/registry.ts

@@ -85,6 +85,45 @@ export function lookupWhatsAppChatByString(
   return byString.get(chatId);
 }
 
+/**
+ * Resolve an explicit send target — the `target` a cross-frontend
+ * `send_via` names — onto chat info, REGISTERING the chat when it's new
+ * so numeric-id routing and replies work from then on. Accepted forms:
+ *
+ *   - a registered Talon id: `wa_dm_*`/`wa_group_*` string, or its
+ *     numeric hash (only resolvable while registered — the hash can't
+ *     be reversed)
+ *   - a raw JID: `<number>@s.whatsapp.net` or `<id>@g.us`
+ *   - a phone number with country code: "+353871234567", "353 87 123 4567"
+ *
+ * Digits with punctuation normalize to a DM JID; an all-digit string is
+ * tried as a registered numeric id first, then treated as a phone number.
+ * Returns undefined when nothing sendable can be derived.
+ */
+export function resolveWhatsAppTarget(
+  raw: unknown,
+): WhatsAppChatInfo | undefined {
+  const target = String(raw ?? "").trim();
+  if (!target) return undefined;
+  const registered = byString.get(target);
+  if (registered) return registered;
+  if (/^\d+$/.test(target)) {
+    const byHash = byNumeric.get(Number(target));
+    if (byHash) return byHash;
+  }
+  if (target.includes("@")) return registerWhatsAppChat(target);
+  if (target.startsWith("wa_group_")) {
+    return registerWhatsAppChat(`${target.slice("wa_group_".length)}@g.us`);
+  }
+  if (target.startsWith("wa_dm_")) {
+    return registerWhatsAppChat(
+      `${target.slice("wa_dm_".length)}@s.whatsapp.net`,
+    );
+  }
+  const digits = target.replace(/[^0-9]/g, "");
+  return digits ? registerWhatsAppChat(`${digits}@s.whatsapp.net`) : undefined;
+}
+
 /** Test seam: forget every registered chat. */
 export function resetWhatsAppRegistry(): void {
   byNumeric.clear();

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