talon-agent 3.25.2 → 3.26.0

package/package.json

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

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

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

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

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

package/src/frontend/whatsapp/index.ts

@@ -16,9 +16,7 @@
 
 import { rmSync } from "node:fs";
 import makeWASocket, {
-  DisconnectReason,
   isJidGroup,
-  useMultiFileAuthState,
   type WAMessage,
   type WASocket,
 } from "baileys";
@@ -33,12 +31,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 +43,22 @@ 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 {
+  classifyClose,
+  nextPairingDelayMs,
+  REPLACED_BACKOFF_MS,
+  shouldNotifyPairingCode,
+} from "./pairing.js";
+import { flushAuthWrites, useAtomicAuthState } from "./auth-state.js";
+import { notifyAdmin } from "../../core/notify.js";
 import {
   lookupWhatsAppChat,
   registerWhatsAppChat,
@@ -151,6 +160,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 +231,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 +295,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 +316,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 +334,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 +376,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,34 +416,63 @@ 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. */
   async function connectOnce(): Promise<"reconnect" | "logged-out" | "stop"> {
-    const { state, saveCreds } = await useMultiFileAuthState(dirs.whatsappAuth);
+    // Atomic replacement for Baileys' useMultiFileAuthState — same disk
+    // format, torn-write-proof (see auth-state.ts for why that matters).
+    const { state, saveCreds } = await useAtomicAuthState(dirs.whatsappAuth);
     const socket = makeWASocket({
       auth: state,
       logger: makeWaLogger(),
       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,
+      // OpenClaw's production timings: the Baileys 20s connect timeout
+      // is tight on a loaded box, and a slightly faster keepalive spots
+      // a dead transport sooner.
+      connectTimeoutMs: 60_000,
+      keepAliveIntervalMs: 25_000,
     });
     sock = socket;
     socket.ev.on("creds.update", saveCreds);
 
     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 +491,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 +538,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("/") || "?"})`,
@@ -460,12 +556,37 @@ export function createWhatsAppFrontend(
               { output?: { statusCode?: number } } | undefined
           )?.output?.statusCode;
           if (stopping) return resolve("stop");
-          if (code === DisconnectReason.loggedOut) return resolve("logged-out");
-          log(
-            "whatsapp",
-            `Connection closed (code ${code ?? "?"}) — reconnecting`,
-          );
-          return resolve("reconnect");
+          const disposition = classifyClose(code, state.creds.registered);
+          switch (disposition.kind) {
+            case "pairing-accepted":
+              // 515 right after a pairing code/QR is SUCCESS, not an
+              // error: WhatsApp requires one reconnect with the same
+              // credentials to complete the login.
+              log(
+                "whatsapp",
+                "Pairing accepted (515) — reconnecting to complete login",
+              );
+              reconnectDelay = RECONNECT_BASE_MS;
+              return resolve("reconnect");
+            case "replaced":
+              // Another socket owns this session (440). Fighting it with
+              // an instant reconnect just steals the session back and
+              // forth; sit out a full minute instead.
+              logWarn(
+                "whatsapp",
+                "Connection replaced by another client (440) — backing off",
+              );
+              reconnectDelay = REPLACED_BACKOFF_MS;
+              return resolve("reconnect");
+            case "logged-out":
+              return resolve("logged-out");
+            default:
+              log(
+                "whatsapp",
+                `Connection closed (code ${code ?? "?"}) — reconnecting`,
+              );
+              return resolve("reconnect");
+          }
         }
       });
     });
@@ -498,6 +619,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 +656,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);
@@ -546,6 +694,10 @@ export function createWhatsAppFrontend(
         /* already closed */
       }
       sock = null;
+      // Drain queued credential writes before the process exits — a key
+      // half-written at shutdown is invisible until the server starts
+      // rejecting stanzas with it.
+      await flushAuthWrites();
       await gateway.stop();
       log("whatsapp", "WhatsApp frontend stopped");
     },

package/src/frontend/whatsapp/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,75 @@
+/**
+ * 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;
+}
+
+// ── Close-code taxonomy ─────────────────────────────────────────────────────
+
+/**
+ * What one Baileys `connection: "close"` means for the reconnect loop.
+ * Ported from how OpenClaw's connection controller reads DisconnectReason
+ * — the old handler knew only "loggedOut or not", which turned pairing
+ * success (515) into an anonymous reconnect and let another client's
+ * takeover (440) start a reconnect fight.
+ */
+export type CloseDisposition =
+  | { kind: "pairing-accepted" } // 515: code entered — reconnect NOW, same creds
+  | { kind: "replaced" } // 440: another socket owns the session — back off hard
+  | { kind: "logged-out"; midPairing: boolean } // 401: dead creds
+  | { kind: "reconnect" }; // everything else: transient
+
+export function classifyClose(
+  statusCode: number | undefined,
+  credsRegistered: boolean,
+): CloseDisposition {
+  switch (statusCode) {
+    case 515: // DisconnectReason.restartRequired — expected right after pairing
+      return { kind: "pairing-accepted" };
+    case 440: // DisconnectReason.connectionReplaced
+      return { kind: "replaced" };
+    case 401: // DisconnectReason.loggedOut
+    case 403: // DisconnectReason.forbidden — account-level, same recovery
+      return { kind: "logged-out", midPairing: !credsRegistered };
+    default:
+      return { kind: "reconnect" };
+  }
+}
+
+/** How long to sit out after a 440 — another client owns the session. */
+export const REPLACED_BACKOFF_MS = 60_000;

package/src/frontend/whatsapp/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"