talon-agent 3.25.2 → 3.25.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.25.2",
+  "version": "3.25.3",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/prompts/whatsapp.md

@@ -46,6 +46,25 @@ the file path is in the message, so you can read it immediately.
 - No forum topics, no custom admin titles, no stopping a poll.
 - Pins expire (24h, 7d, or 30d) and only pins Talon placed are listable.
 
+### Continuity — your context is not the chat
+
+Your working context can start fresh at any time (a `/reset`, a daemon
+restart, an overflowed session) while the WhatsApp conversation continues
+uninterrupted. The chat's real record lives in persistent history, both
+sides of it, and you can always get it back:
+
+- `read_chat_history` — the recent messages; pass `offset_id` (a msg_id)
+  or `before` (an ISO date) to page further back.
+- `search_chat_history` — keyword search over everything said in this
+  chat, including your own earlier messages.
+- `get_message_by_id` — one specific message when you hold its id.
+
+If the sender references something you don't recognize — "the flights",
+"what you said yesterday", "that plan" — search the history before
+saying you don't know or asking them to repeat themselves. A fresh
+session is your situation, not theirs; to the person on the phone this
+is one long conversation, and it should read like you remember it.
+
 ### Staying silent
 
 Reactions work here, so a react is the light acknowledgement when a

package/src/bootstrap.ts

@@ -27,6 +27,7 @@ import { appendToJournal } from "./storage/journal.js";
 import { initPulse, resetPulseTimer } from "./core/background/pulse.js";
 import { initCron } from "./core/background/cron.js";
 import { initPlanAlerts } from "./core/background/plan-alerts.js";
+import { setAdminNotifier } from "./core/notify.js";
 import {
   initTriggers,
   resumeAfterRestart as resumeTriggersAfterRestart,
@@ -442,6 +443,22 @@ export async function initBackendAndDispatcher(
       (config.adminUserId ? String(config.adminUserId) : undefined),
   });
 
+  // Admin notification seam (core/notify.ts) — how a subsystem reaches
+  // the operator when its own channel is the thing that is broken (the
+  // first consumer is WhatsApp pairing: codes must travel over a LIVE
+  // frontend, not the dead one's log). Same delivery route as the plan
+  // alerts above.
+  if (config.adminUserId) {
+    const adminChatId = config.adminUserId;
+    setAdminNotifier(async (text: string) =>
+      resolveFrontendByNumericId(
+        adminChatId,
+        String(adminChatId),
+        frontends,
+      ).sendMessage(adminChatId, text),
+    );
+  }
+
   // Soul — initialize the identity kernel singleton from config so the prompt
   // injection / dream hooks see the right enabled state. Off by default; a
   // failure here must never block startup.

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

@@ -5,6 +5,8 @@
 
 import {
   getRecentFormatted,
+  getFormattedBefore,
+  getFormattedBeforeTime,
   searchHistory,
   getMessagesByUser,
   getKnownUsers,
@@ -15,7 +17,23 @@ import type { SharedActionHandlers } from "./types.js";
 export const historyHandlers: SharedActionHandlers = {
   read_history: (body, chatId) => {
     const limit = Math.min(100, Number(body.limit ?? 30));
-    return { ok: true, text: getRecentFormatted(String(chatId), limit) };
+    const cid = String(chatId);
+    // The tool schema advertises `offset_id` and `before` for paging back;
+    // this fallback used to ignore both and hand back the same newest
+    // window no matter what the model asked, so "go further back" was a
+    // silent no-op on frontends without a platform history API (WhatsApp,
+    // native).
+    const offsetId = Number(body.offset_id);
+    if (Number.isFinite(offsetId) && offsetId > 0) {
+      return { ok: true, text: getFormattedBefore(cid, offsetId, limit) };
+    }
+    if (body.before !== undefined) {
+      const ts = Date.parse(String(body.before));
+      if (Number.isFinite(ts)) {
+        return { ok: true, text: getFormattedBeforeTime(cid, ts, limit) };
+      }
+    }
+    return { ok: true, text: getRecentFormatted(cid, limit) };
   },
 
   search_history: (body, chatId) => {

package/src/core/notify.ts

@@ -0,0 +1,51 @@
+/**
+ * Admin notification seam — a way for any subsystem to reach the human
+ * operator on their primary chat (adminUserId, usually Telegram).
+ *
+ * Core cannot import frontends, so the composition root injects the
+ * delivery function at boot (bootstrap.ts, next to the plan-alerts
+ * wiring, which does the same thing privately). Unwired — early boot,
+ * tests, terminal mode with no admin — notifications degrade to a log
+ * line rather than throwing.
+ *
+ * First consumer: WhatsApp pairing. When WhatsApp unlinks the device,
+ * recovery needs a human to type a pairing code into the phone — a code
+ * that previously only ever appeared in the daemon log, which nobody
+ * watches. Alerts about a dead frontend must travel over a LIVE one.
+ */
+
+import { log, logWarn } from "./../util/log.js";
+
+let deliver: ((text: string) => Promise<void>) | null = null;
+
+/** Wire (or clear) the delivery function. Called by the composition root. */
+export function setAdminNotifier(
+  fn: ((text: string) => Promise<void>) | null,
+): void {
+  deliver = fn;
+}
+
+/**
+ * Send `text` to the admin chat. Never throws; returns whether delivery
+ * was attempted (false = no notifier wired).
+ */
+export async function notifyAdmin(text: string): Promise<boolean> {
+  if (!deliver) {
+    logWarn(
+      "notify",
+      `No admin notifier wired; dropping: ${text.slice(0, 120)}`,
+    );
+    return false;
+  }
+  try {
+    await deliver(text);
+    log("notify", `Admin notified: ${text.slice(0, 80).replace(/\n/g, " ")}`);
+    return true;
+  } catch (err) {
+    log(
+      "notify",
+      `Admin notification failed: ${err instanceof Error ? err.message : err}`,
+    );
+    return false;
+  }
+}

package/src/frontend/shared/session-status.ts

@@ -44,6 +44,7 @@ import { formatDuration } from "./format.js";
 export async function performSessionReset(
   chatId: string,
   backend: Backend | null | undefined,
+  opts: { keepHistory?: boolean } = {},
 ): Promise<void> {
   const info = getSessionInfo(chatId);
   if (info.turns > 0) {
@@ -59,7 +60,12 @@ export async function performSessionReset(
     );
   }
   resetSession(chatId);
-  clearHistory(chatId);
+  // Frontends whose platform keeps the real chat record (Telegram,
+  // Discord) clear the local mirror too — the platform still has
+  // everything. WhatsApp passes keepHistory: the local store is the ONLY
+  // record there, and wiping it on /reset would destroy exactly what the
+  // continuity tools (read/search_chat_history) exist to recover.
+  if (!opts.keepHistory) clearHistory(chatId);
   resetPulseCheckpoint(chatId);
   backend?.sessions?.resetChat?.(chatId);
   await backend?.sessions?.warmSession?.(chatId);

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

@@ -12,6 +12,7 @@ import { log, logError } from "../../../util/log.js";
 import type { ActionResult } from "../../../core/types.js";
 import { toWhatsAppChunks } from "../formatting.js";
 import { lookupMessage, rememberMessage } from "../message-store.js";
+import { pushMessage, type HistoryMessage } from "../../../storage/history.js";
 import type { WhatsAppChatInfo } from "../registry.js";
 
 /** WhatsApp's own ceiling for a media upload. */
@@ -128,6 +129,40 @@ export function resolveQuoted(
   );
 }
 
+/**
+ * How the bot signs its own rows in persistent history. Set once at
+ * frontend start from `config.botDisplayName`; the 0 sender id is the
+ * cross-frontend "this is the assistant" convention (native/protocol.ts).
+ */
+let botName = "Talon";
+export function setWhatsAppBotName(name: string): void {
+  if (name.trim()) botName = name.trim();
+}
+
+/**
+ * History labels for outbound media, in HistoryMessage's closed
+ * vocabulary. Payloads with no file analogue (polls, locations, contact
+ * cards) return a text marker instead via `outboundTextMarker`.
+ */
+function outboundMediaType(
+  content: AnyMessageContent,
+): NonNullable<HistoryMessage["mediaType"]> | undefined {
+  if ("image" in content) return "photo";
+  if ("video" in content) return content.gifPlayback ? "animation" : "video";
+  if ("audio" in content) return "voice";
+  if ("sticker" in content) return "sticker";
+  if ("document" in content) return "document";
+  return undefined;
+}
+
+/** A readable stand-in for captionless payloads history can't type. */
+function outboundTextMarker(content: AnyMessageContent): string {
+  if ("poll" in content) return `[poll: ${content.poll.name}]`;
+  if ("location" in content) return "[location]";
+  if ("contacts" in content) return "[contact card]";
+  return "";
+}
+
 /**
  * Send one content payload, remember the resulting message so later
  * tool calls can address it, and report its Talon numeric id.
@@ -141,13 +176,35 @@ export async function sendContent(
   const sent = await ctx.sock.sendMessage(chat.jid, content, options);
   ctx.gateway.incrementMessages(chat.numericChatId);
   if (!sent?.key) return { ok: true };
+  const text =
+    "text" in content
+      ? String(content.text ?? "")
+      : "caption" in content && content.caption
+        ? String(content.caption)
+        : outboundTextMarker(content);
   const msgId = rememberMessage({
     key: sent.key,
     chatId: chat.chatId,
     message: sent,
-    text: "text" in content ? String(content.text ?? "") : "",
+    text,
     senderName: "bot",
   });
+  // Persist the bot's side of the conversation. Without this the history
+  // store held only inbound messages, so read_chat_history showed a
+  // one-sided chat and search_chat_history could never find anything the
+  // bot itself had said — exactly the messages a fresh session needs when
+  // reconstructing context after a reset or restart.
+  const mediaType = outboundMediaType(content);
+  if (text || mediaType) {
+    pushMessage(chat.chatId, {
+      msgId,
+      senderId: 0,
+      senderName: botName,
+      text,
+      timestamp: Date.now(),
+      ...(mediaType ? { mediaType } : {}),
+    });
+  }
   return { ok: true, message_id: msgId };
 }
 

package/src/frontend/whatsapp/index.ts

@@ -33,12 +33,10 @@ import { toolInputToRecord } from "../../core/agent-runtime/events.js";
 import { resolveChatBackend } from "../../core/engine/backend-controller/index.js";
 import { performSessionReset } from "../shared/session-status.js";
 import { appendDailyLog } from "../../storage/daily-log.js";
-import { pushMessage } from "../../storage/history.js";
+import { pushMessage, maxMsgIdForChatPrefix } from "../../storage/history.js";
 import {
-  recordError,
   recordMessageProcessed,
   recordMessageReceived,
-  recordMessageSettled,
 } from "../../util/watchdog.js";
 import { createWhatsAppActionHandler } from "./actions/index.js";
 import {
@@ -47,9 +45,16 @@ import {
   identityAllowed,
   resolveIdentity,
 } from "./identity.js";
-import { sendText } from "./actions/shared.js";
+import { sendText, setWhatsAppBotName } from "./actions/shared.js";
 import { saveInboundMedia } from "./media-store.js";
-import { lookupByWaId, rememberMessage } from "./message-store.js";
+import {
+  lookupByWaId,
+  rememberMessage,
+  seedMessageStore,
+} from "./message-store.js";
+import { runTurnWithRecovery, shouldReplyToCatchUp } from "./turn-recovery.js";
+import { nextPairingDelayMs, shouldNotifyPairingCode } from "./pairing.js";
+import { notifyAdmin } from "../../core/notify.js";
 import {
   lookupWhatsAppChat,
   registerWhatsAppChat,
@@ -151,6 +156,11 @@ 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;
   /** Our own ids (phone and LID), once connected — for mention detection. */
   let selfIds: string[] = [];
 
@@ -217,7 +227,10 @@ export function createWhatsAppFrontend(
     return Boolean(ctx?.participant && isSelf(ctx.participant));
   }
 
-  async function handleInbound(msg: WAMessage): Promise<void> {
+  async function handleInbound(
+    msg: WAMessage,
+    opts: { catchUp?: boolean } = {},
+  ): Promise<void> {
     const jid = msg.key.remoteJid;
     // `fromMe` covers our own sends echoing back; status@broadcast is the
     // Stories feed, which is not a conversation.
@@ -278,13 +291,17 @@ export function createWhatsAppFrontend(
     const replyToWaId =
       msg.message?.extendedTextMessage?.contextInfo?.stanzaId ?? undefined;
     const replyTo = replyToWaId ? lookupByWaId(replyToWaId) : undefined;
+    const platformTs = Number(msg.messageTimestamp) * 1000;
     pushMessage(chat.chatId, {
       msgId,
       senderId: Number(BigInt(canonicalId(identity) ?? "0") % 2147483647n),
       senderName,
       senderHandle: canonicalId(identity),
       text,
-      timestamp: Date.now(),
+      // The platform timestamp, so a catch-up message recorded late still
+      // reads in true order; Date.now() only when Baileys omits it.
+      timestamp:
+        Number.isFinite(platformTs) && platformTs > 0 ? platformTs : Date.now(),
       ...(replyTo ? { replyToMsgId: replyTo.msgId } : {}),
       ...(media ? { mediaType: media.type, filePath: media.filePath } : {}),
     });
@@ -295,6 +312,9 @@ export function createWhatsAppFrontend(
       await performSessionReset(
         chat.chatId,
         resolveChatBackend(chat.chatId, gateway.backend),
+        // The local history store is WhatsApp's only chat record — a
+        // reset clears the model's session, not the conversation log.
+        { keepHistory: true },
       );
       log("whatsapp", `Session reset by ${senderName}`);
       if (sock) {
@@ -310,13 +330,31 @@ export function createWhatsAppFrontend(
         await sendText(
           { sock, gateway },
           chat,
-          "*Commands*\n/reset — clear session & history\n/help — this message",
+          "*Commands*\n/reset — start a fresh session (chat log kept)\n/help — this message",
         ).catch(() => {});
       }
       recordMessageProcessed();
       return;
     }
 
+    // Catch-up messages (queued while the daemon was down) get a reply
+    // turn only while fresh; stale ones are already recorded above and
+    // the next live turn reads them from history.
+    if (opts.catchUp) {
+      if (!shouldReplyToCatchUp(platformTs)) {
+        log(
+          "whatsapp",
+          `[${chat.chatId}] Recorded offline message from ${senderName} (history only — too old for a reply turn)`,
+        );
+        recordMessageProcessed();
+        return;
+      }
+      log(
+        "whatsapp",
+        `[${chat.chatId}] Catch-up: replying to offline message from ${senderName}`,
+      );
+    }
+
     const preview = text || `(${media?.type ?? "media"})`;
     log(
       "whatsapp",
@@ -334,8 +372,8 @@ export function createWhatsAppFrontend(
       : "";
     const prompt = `[${senderName}] msg_id:${msgId}: ${text}${mediaNote}`;
 
-    try {
-      await execute({
+    const runTurn = () =>
+      execute({
         chatId: chat.chatId,
         numericChatId: chat.numericChatId,
         prompt,
@@ -374,13 +412,23 @@ export function createWhatsAppFrontend(
           }
         },
       });
-      recordMessageProcessed();
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      logError("whatsapp", `[${chat.chatId}] execute failed: ${message}`);
-      recordError(message);
-      recordMessageSettled();
-    }
+
+    await runTurnWithRecovery({
+      chatId: chat.chatId,
+      senderName,
+      runTurn,
+      sendErrorText: async (text) => {
+        if (!sock) return;
+        try {
+          await sendText({ sock, gateway }, chat, text);
+        } catch (sendErr) {
+          logError(
+            "whatsapp",
+            `error delivery failed: ${sendErr instanceof Error ? sendErr.message : sendErr}`,
+          );
+        }
+      },
+    });
   }
 
   /** One socket lifetime. Resolves with what the caller should do next. */
@@ -392,16 +440,28 @@ export function createWhatsAppFrontend(
       markOnlineOnConnect: false,
       // The account is a bot: announcing "online" would suppress the
       // phone's own notifications for the human who owns the number.
+      //
+      // 120s per QR/pairing ref — the default (60s + 20s refreshes) gave
+      // 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,
     });
     sock = socket;
     socket.ev.on("creds.update", saveCreds);
 
     socket.ev.on("messages.upsert", ({ messages, type }) => {
-      // "notify" is a live message; "append" is history sync, which must
-      // not trigger turns for conversations that already happened.
-      if (type !== "notify") return;
+      // "notify" is a live message. "append" is everything delivered out
+      // of band — chiefly messages QUEUED WHILE THE DAEMON WAS DOWN
+      // (Baileys marks offline-queued nodes as append), but also our own
+      // sends echoing back and newsletter posts, which handleInbound's
+      // fromMe/allowlist gates drop. Dropping append wholesale meant any
+      // message sent during a restart simply vanished: never recorded,
+      // never answered. Appends are processed as catch-up: always
+      // recorded, replied to only while fresh.
+      if (type !== "notify" && type !== "append") return;
+      const catchUp = type === "append";
       for (const msg of messages) {
-        void handleInbound(msg).catch((err) => {
+        void handleInbound(msg, { catchUp }).catch((err) => {
           logError(
             "whatsapp",
             `inbound handler failed: ${err instanceof Error ? err.message : err}`,
@@ -420,13 +480,32 @@ export function createWhatsAppFrontend(
             pairingRequested = true;
             socket
               .requestPairingCode(bareId(settings.pairingNumber))
-              .then((code) =>
+              .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",
@@ -448,6 +527,12 @@ 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.");
+          }
+          failedPairingCycles = 0;
+          pairingCodesIssued = 0;
+          lastPairingNotifyAt = undefined;
           log(
             "whatsapp",
             `Connected as ${socket.user?.name ?? "?"} (${selfIds.join("/") || "?"})`,
@@ -498,6 +583,12 @@ export function createWhatsAppFrontend(
     getBridgePort: () => gateway.getPort(),
 
     async init() {
+      setWhatsAppBotName(config.botDisplayName);
+      // 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
+      // silently drops (chat ids all start with "wa_").
+      seedMessageStore((maxMsgIdForChatPrefix("wa_") ?? 0) + 1);
       gateway.registerFrontendHandler(
         "whatsapp",
         createWhatsAppActionHandler(() => sock, gateway),
@@ -529,8 +620,29 @@ export function createWhatsAppFrontend(
             "whatsapp",
             "Logged out by WhatsApp — clearing auth state, re-pairing",
           );
+          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));
+          }
           reconnectDelay = RECONNECT_BASE_MS;
+          continue;
         }
         await new Promise((r) => setTimeout(r, reconnectDelay));
         reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);

package/src/frontend/whatsapp/message-store.ts

@@ -41,6 +41,22 @@ const ID_BASE = 1_000_000;
 const MAX_TRACKED = 2_000;
 
 let nextId = ID_BASE;
+
+/**
+ * Raise the id counter past what persistent history already holds.
+ *
+ * The counter is in-memory and restarts at ID_BASE every boot, but the
+ * ids it hands out are also the `msg_id`s written to the history table,
+ * where `INSERT OR IGNORE` + UNIQUE(chat_id, msg_id) dedupes. Without
+ * this seed, the first messages after a daemon restart re-issue ids the
+ * previous run already used — the IGNORE then silently drops them from
+ * history, and a reaction/reply addressed at an old id from history hits
+ * whatever new message reused the number. Called at frontend start with
+ * max(msg_id) over wa_* chats + 1.
+ */
+export function seedMessageStore(floor: number): void {
+  if (Number.isFinite(floor)) nextId = Math.max(nextId, Math.floor(floor));
+}
 const byMsgId = new Map<number, StoredMessage>();
 const byWaId = new Map<string, number>();
 

package/src/frontend/whatsapp/pairing.ts

@@ -0,0 +1,40 @@
+/**
+ * Pairing-recovery 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.
+ */
+
+/** 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;
+}

package/src/frontend/whatsapp/turn-recovery.ts

@@ -0,0 +1,113 @@
+/**
+ * Failure semantics for a WhatsApp turn, mirroring the Telegram queue
+ * (frontend/telegram/handlers/queue.ts): a user-initiated stop settles
+ * silently, a brief transient failure gets one retry, and anything else
+ * is REPORTED IN THE CHAT. Before this existed the error went only to
+ * the log — the WhatsApp user's message was marked read and then nothing
+ * ever came back, which reads as being ignored.
+ *
+ * Split from index.ts so the policy is unit-testable without a Baileys
+ * socket: the caller injects the turn and the delivery.
+ */
+
+import {
+  classify,
+  friendlyMessage,
+  RETRY_ELAPSED_CAP_MS,
+} from "../../core/errors.js";
+import { log, logError } from "../../util/log.js";
+import {
+  recordError,
+  recordMessageProcessed,
+  recordMessageSettled,
+} from "../../util/watchdog.js";
+
+export type TurnRecoveryDeps = {
+  chatId: string;
+  senderName: string;
+  runTurn: () => Promise<unknown>;
+  /** Deliver a friendly error line into the chat. Must not throw. */
+  sendErrorText: (text: string) => Promise<void>;
+  /** Test seam for the retry pause; defaults to a real setTimeout. */
+  wait?: (ms: number) => Promise<void>;
+};
+
+export async function runTurnWithRecovery(
+  deps: TurnRecoveryDeps,
+): Promise<void> {
+  const wait =
+    deps.wait ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+
+  const startedAt = Date.now();
+  try {
+    await deps.runTurn();
+    recordMessageProcessed();
+  } catch (err) {
+    const classified = classify(err);
+    // A user-initiated /stop is an outcome, not a fault — the stop was
+    // already acknowledged, so an error bubble here would contradict it.
+    if (classified.reason === "stopped") {
+      log("whatsapp", `[${deps.chatId}] turn stopped by user`);
+      recordMessageSettled();
+      return;
+    }
+    logError(
+      "whatsapp",
+      `[${deps.chatId}] [${deps.senderName}] ${classified.reason}: ${classified.message}`,
+    );
+    recordError(classified.message);
+
+    // Retry once for transients (rate_limit, overloaded, network) — but
+    // only when the failed attempt was brief. An attempt that already ran
+    // for minutes won't be saved by a 2s pause, and turns serialize per
+    // chat, so a blind retry doubles the stall for everything behind it.
+    const attemptMs = Date.now() - startedAt;
+    if (classified.retryable && attemptMs < RETRY_ELAPSED_CAP_MS) {
+      const delayMs = classified.retryAfterMs ?? 2000;
+      log(
+        "whatsapp",
+        `[${deps.chatId}] Retrying after ${classified.reason} (${delayMs}ms)...`,
+      );
+      try {
+        await wait(delayMs);
+        await deps.runTurn();
+        recordMessageProcessed();
+        return;
+      } catch (retryErr) {
+        const retryClassified = classify(retryErr);
+        logError(
+          "whatsapp",
+          `[${deps.chatId}] Retry failed: ${retryClassified.message}`,
+        );
+        recordMessageSettled();
+        await deps.sendErrorText(friendlyMessage(retryClassified));
+        return;
+      }
+    }
+
+    recordMessageSettled();
+    await deps.sendErrorText(friendlyMessage(classified));
+  }
+}
+
+/**
+ * How fresh a catch-up (offline-queued) message must be to still get a
+ * reply turn. Messages older than this are recorded in history — the next
+ * live turn sees them — but not answered: replying to a whole night's
+ * backlog hours later reads worse than picking up naturally.
+ */
+export const CATCH_UP_REPLY_WINDOW_MS = 15 * 60_000;
+
+/**
+ * Whether a message delivered as catch-up (Baileys `append`) should get a
+ * reply turn. `platformTsMs` is the message's own timestamp in ms; a
+ * missing/zero timestamp counts as fresh — better one odd reply than a
+ * silently dropped question.
+ */
+export function shouldReplyToCatchUp(
+  platformTsMs: number,
+  now: number = Date.now(),
+): boolean {
+  if (!Number.isFinite(platformTsMs) || platformTsMs <= 0) return true;
+  return now - platformTsMs <= CATCH_UP_REPLY_WINDOW_MS;
+}

package/src/storage/history.ts

@@ -81,6 +81,11 @@ export function pushMessage(chatId: string, msg: HistoryMessage): void {
   }
 }
 
+/** See repositories/history-repo.ts `maxMsgIdForPrefix`. */
+export function maxMsgIdForChatPrefix(prefix: string): number | undefined {
+  return repo.maxMsgIdForPrefix(prefix);
+}
+
 export function getRecentHistory(chatId: string, limit = 50): HistoryMessage[] {
   return repo.recent(chatId, limit);
 }
@@ -98,6 +103,28 @@ export function getHistoryBefore(
   return repo.recentBefore(chatId, beforeMsgId, limit);
 }
 
+/** Formatted page of the messages strictly older than `beforeMsgId`. */
+export function getFormattedBefore(
+  chatId: string,
+  beforeMsgId: number,
+  limit = 30,
+): string {
+  const messages = repo.recentBefore(chatId, beforeMsgId, limit);
+  if (messages.length === 0) return "No messages before that point.";
+  return messages.map(formatMessage).join("\n");
+}
+
+/** Formatted page of the messages strictly older than a timestamp (ms). */
+export function getFormattedBeforeTime(
+  chatId: string,
+  beforeTs: number,
+  limit = 30,
+): string {
+  const messages = repo.recentBeforeTime(chatId, beforeTs, limit);
+  if (messages.length === 0) return "No messages before that date.";
+  return messages.map(formatMessage).join("\n");
+}
+
 /**
  * Raw (wire-friendly) full-text search over a chat's history. Unlike
  * [searchHistory] — which formats a string for the agent's tool — this

package/src/storage/repositories/history-repo.ts

@@ -108,6 +108,17 @@ export function recentBefore(
   return rows.reverse().map(rowToMessage);
 }
 
+export function recentBeforeTime(
+  chatId: string,
+  beforeTs: number,
+  limit: number,
+): HistoryMessage[] {
+  const rows = getDatabase()
+    .prepare(historySql.recentBeforeTime)
+    .all(chatId, beforeTs, limit) as Row[];
+  return rows.reverse().map(rowToMessage);
+}
+
 export function setFilePath(
   chatId: string,
   msgId: number,
@@ -174,6 +185,19 @@ export function latestMsgId(chatId: string): number | undefined {
   return row?.msg_id;
 }
 
+/**
+ * Highest msg_id over every chat whose id begins with `prefix` (compared
+ * literally — LIKE wildcards in the prefix are escaped). Undefined when no
+ * such chat has any history.
+ */
+export function maxMsgIdForPrefix(prefix: string): number | undefined {
+  const pattern = prefix.replace(/[\\%_]/g, (ch) => `\\${ch}`) + "%";
+  const row = getDatabase()
+    .prepare(historySql.maxMsgIdForPrefix)
+    .get(pattern) as { max_id: number | null } | undefined;
+  return row?.max_id ?? undefined;
+}
+
 export type KnownUser = {
   senderId: number;
   name: string;

package/src/storage/sql/history.sql

@@ -21,6 +21,14 @@ SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
 FROM history_messages
 WHERE chat_id = ? AND msg_id < ? ORDER BY id DESC LIMIT ?
 
+-- name: recentBeforeTime
+-- Time-cursor variant of recentBefore for the read_history `before` date
+-- parameter: the newest `limit` messages strictly older than a timestamp.
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
+       timestamp, media_type, sticker_file_id, file_path
+FROM history_messages
+WHERE chat_id = ? AND timestamp < ? ORDER BY id DESC LIMIT ?
+
 -- name: setFilePath
 UPDATE history_messages SET file_path = ? WHERE chat_id = ? AND msg_id = ?
 
@@ -60,6 +68,12 @@ WHERE chat_id = ? AND sender_id = ? ORDER BY id DESC LIMIT ?
 -- name: latestMsgId
 SELECT msg_id FROM history_messages WHERE chat_id = ? ORDER BY id DESC LIMIT 1
 
+-- name: maxMsgIdForPrefix
+-- Highest msg_id across every chat whose id starts with a prefix
+-- (parameter is a LIKE pattern with \ escapes). Seeds the WhatsApp
+-- frontend's in-memory id counter past what history already holds.
+SELECT MAX(msg_id) AS max_id FROM history_messages WHERE chat_id LIKE ? ESCAPE '\'
+
 -- name: knownUsers
 SELECT sender_id,
        MAX(timestamp) AS last_seen,

package/src/storage/sql/statements.generated.ts

@@ -346,6 +346,12 @@ SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? AND msg_id < ? ORDER BY id DESC LIMIT ?`,
+  recentBeforeTime: `-- Time-cursor variant of recentBefore for the read_history \`before\` date
+-- parameter: the newest \`limit\` messages strictly older than a timestamp.
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
+       timestamp, media_type, sticker_file_id, file_path
+FROM history_messages
+WHERE chat_id = ? AND timestamp < ? ORDER BY id DESC LIMIT ?`,
   setFilePath: `UPDATE history_messages SET file_path = ? WHERE chat_id = ? AND msg_id = ?`,
   deleteChat: `DELETE FROM history_messages WHERE chat_id = ?`,
   searchFts: `-- The match param must already be a valid FTS5 expression
@@ -371,6 +377,10 @@ WHERE chat_id = ? AND msg_id = ? ORDER BY id DESC LIMIT 1`,
 FROM history_messages
 WHERE chat_id = ? AND sender_id = ? ORDER BY id DESC LIMIT ?`,
   latestMsgId: `SELECT msg_id FROM history_messages WHERE chat_id = ? ORDER BY id DESC LIMIT 1`,
+  maxMsgIdForPrefix: `-- Highest msg_id across every chat whose id starts with a prefix
+-- (parameter is a LIKE pattern with \\ escapes). Seeds the WhatsApp
+-- frontend's in-memory id counter past what history already holds.
+SELECT MAX(msg_id) AS max_id FROM history_messages WHERE chat_id LIKE ? ESCAPE '\\'`,
   knownUsers: `SELECT sender_id,
        MAX(timestamp) AS last_seen,
        COUNT(*) AS message_count,

package/src/util/log.ts

@@ -28,6 +28,7 @@ export type LogComponent =
   | "journal"
   | "kv"
   | "media"
+  | "notify"
   | "agent"
   | "pulse"
   | "userbot"