@aitne/daemon 0.1.7 → 0.1.9

package/dist/adapters/whatsapp-adapter.js

@@ -1,3 +1,4 @@
+import { lookup as nodeDnsLookup } from "node:dns/promises";
 import { mkdirSync, unlinkSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { Readable } from "node:stream";
@@ -31,14 +32,51 @@ const WA_VERSION_TTL_MS = 12 * 60 * 60 * 1000;
  * Reconnect tunables. Initial 1 s, double per attempt, cap at 60 s, plus a
  * small jitter so multiple processes restarting simultaneously do not
  * thunder-herd WhatsApp's relay servers. After RECONNECT_MAX_ATTEMPTS
- * consecutive failures we surface an error state and stop retrying — hammering
- * a relay that keeps closing us is the fast path to an IP-level ban.
+ * consecutive failures the *fast* phase ends. What happens next depends on
+ * why we closed (see {@link TRANSIENT_NETWORK_STATUS_CODES}):
+ *
+ *   - a transport/network close (the laptop lost WiFi, suspended, or switched
+ *     networks) drops into the sustained connectivity watch below, which never
+ *     gives up and recovers on its own once the network returns;
+ *   - any other close (WhatsApp rejected us at the app layer — bad version,
+ *     bad session, throttle) surfaces an error and stops, because hammering a
+ *     relay that keeps closing us is the fast path to an IP-level ban.
  */
 const RECONNECT_INITIAL_DELAY_MS = 1_000;
 const RECONNECT_MAX_DELAY_MS = 60_000;
 const RECONNECT_BACKOFF_FACTOR = 2;
 const RECONNECT_JITTER_MS = 500;
 const RECONNECT_MAX_ATTEMPTS = 10;
+/**
+ * Sustained-watch tunables. Once the fast phase exhausts on a *network-class*
+ * close we keep watching for connectivity indefinitely on this long, fixed
+ * cadence rather than giving up — a laptop carried out of WiFi range,
+ * suspended, or moved between networks routinely stays offline far longer than
+ * the ~5 min fast window, and must still recover without a manual reset. The
+ * watch probes connectivity with a cheap DNS lookup (see
+ * {@link WhatsAppAdapter.isNetworkReachable}) and only opens a socket to
+ * WhatsApp once the network is back, so an offline laptop poses zero ban risk
+ * and near-zero cost.
+ */
+const RECONNECT_SUSTAINED_DELAY_MS = 30_000;
+const RECONNECT_SUSTAINED_JITTER_MS = 5_000;
+const WA_REACHABILITY_PROBE_HOST = "web.whatsapp.com";
+/**
+ * Disconnect codes (and the no-code case) that mean the *transport* failed,
+ * not that WhatsApp's app layer rejected us. These are safe to retry
+ * indefinitely under the sustained watch — they are the "carried the laptop
+ * out of range / sleep-wake / network switch" symptoms.
+ *
+ *   408 — DisconnectReason.connectionLost / timedOut (the ping window elapsed
+ *         silently; this is the status the dashboard shows for a moved laptop)
+ *   428 — DisconnectReason.connectionClosed (transport closed under us)
+ *   503 — DisconnectReason.unavailableService (WhatsApp temporarily unreachable)
+ *
+ * A close carrying no Boom statusCode at all is a raw socket error
+ * (ENOTFOUND / ECONNRESET / EHOSTUNREACH / EAI_AGAIN) — also transport, also
+ * network — so we treat the null case as network-class too.
+ */
+const TRANSIENT_NETWORK_STATUS_CODES = new Set([408, 428, 503]);
 /**
  * Disconnect codes that mean the user must take action — re-pair, fix a
  * conflicting device, or contact WhatsApp. There is no point reconnecting on
@@ -68,6 +106,21 @@ const VERSION_REJECTED_STATUS_CODES = new Set([405, 515]);
  * normal pacing.
  */
 const SENT_MESSAGE_ID_CAP = 256;
+/**
+ * Thrown by {@link WhatsAppAdapter.requestQR} when the adapter is in a
+ * terminal `logged_out` state and cannot accept a fresh QR attempt without
+ * a session reset (auth-dir deletion). Carries no recovery path inside the
+ * adapter — callers (the dashboard's WhatsApp settings page, the setup
+ * wizard) detect this error via `instanceof` and surface a "Reset session"
+ * CTA so the operator can remove the auth bundle and re-pair from scratch.
+ */
+export class WhatsAppLoggedOutError extends Error {
+    code = "logged_out_requires_reset";
+    constructor(message) {
+        super(message);
+        this.name = "WhatsAppLoggedOutError";
+    }
+}
 export function toWhatsAppJid(phone) {
     if (!OWNER_PHONE_RE.test(phone)) {
         throw new Error(`Invalid WhatsApp owner phone "${phone}". Expected E.164 format like +818012345678`);
@@ -155,8 +208,7 @@ function unwrapWhatsAppMessage(message) {
 }
 /**
  * WhatsAppAdapter — Baileys-based owner-only WhatsApp DM integration.
- *
- * Phase 1 accepts messages from exactly one configured owner JID.
+ * Accepts messages from exactly one configured owner JID.
  */
 export class WhatsAppAdapter {
     platformName = "whatsapp";
@@ -164,17 +216,14 @@ export class WhatsAppAdapter {
     authDir;
     onMessage;
     onLoggedOut;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     sock = null;
     authState = null;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     makeWASocket = null;
     renderQr = null;
     renderQrToDataUrl = null;
     fetchLatestWaWebVersion = null;
     fetchLatestBaileysVersion = null;
     generateMessageId = null;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     downloadMediaMessage = null;
     attachmentStore;
     /**
@@ -205,9 +254,43 @@ export class WhatsAppAdapter {
     intentionalClose = false;
     reconnectTimer = null;
     qrExpiryTimer = null;
+    /**
+     * Outstanding presence-refresh interval. Tracked at the adapter level
+     * (rather than only inside the `beginProcessingIndicator` closure) so
+     * `stop()` can cancel it. Without this, an adapter teardown that races
+     * an in-flight processing indicator would leave `sendPresence("composing")`
+     * firing every {@link PRESENCE_REFRESH_MS} against a torn-down socket —
+     * one `Error: socket disconnected` per tick until GC reclaimed the
+     * closure. Only one indicator can be live at a time (the dispatcher
+     * begins one indicator per inbound message and awaits its stop before
+     * the next), so a single field is enough.
+     */
+    presenceInterval = null;
     latestQr = null;
     lastError = null;
     reconnectAttempts = 0;
+    /**
+     * Whether the most recent unsolicited close was a transport/network failure
+     * (see {@link TRANSIENT_NETWORK_STATUS_CODES}) rather than an app-layer
+     * rejection. Read by {@link scheduleReconnect} to decide, once the fast
+     * phase exhausts, whether to enter the never-give-up sustained watch
+     * (network) or surface an error and stop (app-layer).
+     */
+    lastCloseWasNetwork = false;
+    /**
+     * True while a reconnect is scheduled OR an attempt (including the sustained
+     * watch's async connectivity probe) is in flight, and we have NOT
+     * permanently given up. Lets the status accessors report "connecting"
+     * during the brief timer-less window of a sustained probe instead of
+     * flashing a red error. Cleared on open / give-up / logout / stop.
+     */
+    reconnecting = false;
+    /**
+     * Connectivity probe used by the sustained watch. Injectable so tests can
+     * drive the offline / back-online transitions without real DNS; production
+     * resolves a WhatsApp host through the OS resolver.
+     */
+    dnsLookup = (hostname) => nodeDnsLookup(hostname);
     cachedWAVersion = null;
     cachedWAVersionAt = 0;
     constructor(options) {
@@ -238,10 +321,11 @@ export class WhatsAppAdapter {
      *     transitioning). `disabled` covers the pre-connect window during
      *     {@link start}'s awaits.
      *   - `logged_out` → terminal, surface the error.
-     *   - `disconnected` → if a reconnect timer is pending, recovery is in
-     *     flight; otherwise we've either hit `RECONNECT_MAX_ATTEMPTS` or the
-     *     adapter is between attempts with no scheduled retry, both of which
-     *     are real, user-actionable failures.
+     *   - `disconnected` → recovery is in flight when a reconnect timer is
+     *     pending OR a sustained-watch attempt is mid-probe ({@link reconnecting}
+     *     covers the brief timer-less DNS window). Only when neither holds have
+     *     we permanently given up (app-layer rejection past the fast cap) — a
+     *     real, user-actionable failure.
      */
     getStatusError() {
         switch (this.connectionState) {
@@ -253,7 +337,7 @@ export class WhatsAppAdapter {
             case "logged_out":
                 return this.lastError ?? "WhatsApp logged out";
             case "disconnected":
-                if (this.reconnectTimer !== null)
+                if (this.reconnectTimer !== null || this.reconnecting)
                     return null;
                 return this.lastError ?? "WhatsApp disconnected";
             /* v8 ignore next 2 — default branch unreachable with correctly typed connectionState */
@@ -277,8 +361,10 @@ export class WhatsAppAdapter {
                 // rendered red on /health polled during that window.
                 return { runtimeState: "connecting", error: null };
             case "disconnected":
-                // getStatusError returned null → reconnect timer is pending, so this
-                // is a transient gap, not a failure. Treat as connecting.
+                // getStatusError returned null → a reconnect timer is pending or the
+                // sustained watch is mid-probe, so this is a transient gap (including
+                // a moved/offline laptop being watched for), not a failure. Treat as
+                // connecting.
                 return { runtimeState: "connecting", error: null };
             /* v8 ignore next 2 — default branch unreachable with correctly typed connectionState */
             default:
@@ -286,12 +372,27 @@ export class WhatsAppAdapter {
         }
     }
     async requestQR() {
+        // A fresh `connect()` from a `logged_out` state cannot succeed
+        // — WhatsApp's relays reject the same auth bundle and the adapter
+        // bounces straight back to `logged_out`. Worse, retrying repeatedly
+        // is the fast path to an IP-level rate limit. Surface the terminal
+        // state to the dashboard so it can show a "Reset session" CTA
+        // instead of silently burning attempts. The user clears the auth
+        // dir via the dashboard's reset flow (which deletes
+        // {@link authDir}); a subsequent requestQR() then succeeds because
+        // ensureAuthState() loads a fresh bundle.
+        if (this.connectionState === "logged_out") {
+            throw new WhatsAppLoggedOutError(this.lastError
+                ?? "WhatsApp session is logged out — reset the session to re-pair");
+        }
         // User-initiated retry: clear any previous failure state and the
         // backoff counter so the dashboard's "Refresh QR" button always gets a
         // fresh attempt instead of inheriting the last reconnect's exhaustion.
         this.shuttingDown = false;
         this.lastError = null;
         this.reconnectAttempts = 0;
+        this.reconnecting = false;
+        this.lastCloseWasNetwork = false;
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
@@ -372,7 +473,18 @@ export class WhatsAppAdapter {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        // Cancel any presence-refresh interval still in flight so
+        // sendPresence("composing") doesn't keep firing against the torn-down
+        // socket. The closure inside beginProcessingIndicator owns its `stopped`
+        // flag, so a subsequent stop() from the indicator's own caller is a
+        // safe no-op after this.
+        if (this.presenceInterval) {
+            clearInterval(this.presenceInterval);
+            this.presenceInterval = null;
+        }
         this.reconnectAttempts = 0;
+        this.reconnecting = false;
+        this.lastCloseWasNetwork = false;
         this.sentMessageIds.clear();
         this.clearQrSnapshot();
         this.clearQrFile();
@@ -408,22 +520,19 @@ export class WhatsAppAdapter {
             try {
                 const { readFileSync: rfs } = await import("node:fs");
                 const buf = rfs(att.path);
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                let mediaPayload;
-                if (att.mimeType.startsWith("image/")) {
-                    mediaPayload = { image: buf, mimetype: att.mimeType, caption };
-                }
-                else {
-                    mediaPayload = {
+                const mediaPayload = att.mimeType.startsWith("image/")
+                    ? { image: buf, mimetype: att.mimeType, caption }
+                    : {
                         document: buf,
                         mimetype: att.mimeType,
                         fileName: att.originalFilename,
                         caption,
                     };
-                }
                 const preId = this.generateMessageId?.() ?? null;
                 if (preId)
                     this.rememberSentMessageId(preId);
+                if (!this.sock)
+                    continue;
                 const result = await this.sock.sendMessage(channel, mediaPayload, preId ? { messageId: preId } : undefined);
                 const actualId = result?.key?.id;
                 if (typeof actualId === "string" && actualId !== preId) {
@@ -437,8 +546,20 @@ export class WhatsAppAdapter {
         }
         return { messageId: lastMessageId };
     }
+    /**
+     * Send a plain-text reply, splitting at {@link OUTBOUND_CHUNK_SIZE} so we
+     * stay under WhatsApp's ~4096-char per-message ceiling. Splits are
+     * fence-aware and surrogate-safe (see {@link splitOutboundText}). When the
+     * payload is chunked we emit a `wa outbound chunked` debug line so ops
+     * can reconcile a single agent reply that lands as multiple WhatsApp
+     * messages — the previous silent chunking made it look like the agent
+     * had repeated itself.
+     */
     async sendWhatsAppText(channel, text) {
         const chunks = splitOutboundText(text, OUTBOUND_CHUNK_SIZE);
+        if (chunks.length > 1) {
+            logger.debug({ chunks: chunks.length, totalChars: text.length }, "wa outbound chunked");
+        }
         let lastMessageId;
         for (const chunk of chunks) {
             // Pre-generate the WAMessage id so we can register it BEFORE Baileys
@@ -448,6 +569,8 @@ export class WhatsAppAdapter {
             const preId = this.generateMessageId?.() ?? null;
             if (preId)
                 this.rememberSentMessageId(preId);
+            if (!this.sock)
+                break;
             const result = await this.sock.sendMessage(channel, { text: chunk }, preId ? { messageId: preId } : undefined);
             // If something between us and the test mock didn't honor our
             // pre-generated id, fall back to the id Baileys actually used and
@@ -481,16 +604,28 @@ export class WhatsAppAdapter {
             }
         };
         await sendPresence("composing");
+        // Clear any previously-active interval before claiming the slot.
+        // The dispatcher invariant is "one indicator at a time per channel",
+        // so this branch only triggers if a prior indicator's stop() was
+        // skipped (e.g. crashed callsite); cancelling defensively is cheap
+        // and prevents stacking firing intervals.
+        if (this.presenceInterval) {
+            clearInterval(this.presenceInterval);
+        }
         const interval = setInterval(() => {
             void sendPresence("composing");
         }, PRESENCE_REFRESH_MS);
         interval.unref?.();
+        this.presenceInterval = interval;
         return {
             stop: async () => {
                 if (stopped)
                     return;
                 stopped = true;
                 clearInterval(interval);
+                if (this.presenceInterval === interval) {
+                    this.presenceInterval = null;
+                }
                 await sendPresence("paused");
             },
         };
@@ -506,30 +641,27 @@ export class WhatsAppAdapter {
             return;
         }
         const installHint = "Run: pnpm --filter @aitne/daemon add @whiskeysockets/baileys qrcode-terminal qrcode";
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let baileys;
         try {
-            baileys = await import("@whiskeysockets/baileys");
+            baileys = (await import("@whiskeysockets/baileys"));
             /* v8 ignore next 4 — packages always installed in production; catch only reachable when package is absent */
         }
         catch (err) {
             logger.error({ err }, "Failed to load @whiskeysockets/baileys");
             throw new Error(`@whiskeysockets/baileys not installed. ${installHint}`);
         }
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let qrTermModule;
         try {
-            qrTermModule = await import("qrcode-terminal");
+            qrTermModule = (await import("qrcode-terminal"));
             /* v8 ignore next 4 — packages always installed in production; catch only reachable when package is absent */
         }
         catch (err) {
             logger.error({ err }, "Failed to load qrcode-terminal");
             throw new Error(`qrcode-terminal not installed. ${installHint}`);
         }
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let qrModule;
         try {
-            qrModule = await import("qrcode");
+            qrModule = (await import("qrcode"));
             /* v8 ignore next 4 — packages always installed in production; catch only reachable when package is absent */
         }
         catch (err) {
@@ -549,7 +681,10 @@ export class WhatsAppAdapter {
             throw new Error("qrcode-terminal module does not expose generate()");
         }
         this.renderQr = qrTermLib.generate.bind(qrTermLib);
-        const qrLib = /* v8 ignore next */ qrModule.default ?? qrModule;
+        // `qrcode` is CommonJS but provides named ESM exports; the dynamic import
+        // returns the namespace with `toDataURL` directly. Cast through `unknown`
+        // to also tolerate the legacy `{ default: { toDataURL } }` shape.
+        const qrLib = ((qrModule.default ?? qrModule));
         /* v8 ignore next 3 — unreachable when qrcode exposes toDataURL() */
         if (!qrLib || typeof qrLib.toDataURL !== "function") {
             throw new Error("qrcode module does not expose toDataURL()");
@@ -590,9 +725,7 @@ export class WhatsAppAdapter {
         else if (typeof baileys.generateMessageIDV2 === "function") {
             this.generateMessageId = () => baileys.generateMessageIDV2();
         }
-        // Phase 2 inbound media download helper.
         if (typeof baileys.downloadMediaMessage === "function") {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.downloadMediaMessage = baileys.downloadMediaMessage;
             /* v8 ignore next 3 — null branch only reachable with a Baileys build that omits this helper */
         }
@@ -609,7 +742,7 @@ export class WhatsAppAdapter {
             /* v8 ignore next 9 — real Baileys auth state is always pre-injected in tests; this branch only runs in production */
         }
         else {
-            const baileys = await import("@whiskeysockets/baileys");
+            const baileys = (await import("@whiskeysockets/baileys"));
             const bundle = await baileys.useMultiFileAuthState(this.authDir);
             this.authState = {
                 state: bundle.state,
@@ -742,9 +875,22 @@ export class WhatsAppAdapter {
             syncFullHistory: false,
             shouldSyncHistoryMessage: () => false,
             /* v8 ignore next 1 — both truthy and falsy version paths tested; V8 ternary branch merge artefact */
-            ...(version ? { version } : {}),
+            ...(version && version.length === 3
+                ? { version: version }
+                : {}),
         });
         this.sock = sock;
+        // Clear the self-echo dedup set on every fresh socket. WAMessage
+        // ids are unique per session, so any id left over from the previous
+        // socket would mis-classify an incoming message as our own echo if (in
+        // practice, never) WhatsApp redelivered it on the new socket. More
+        // importantly, the set used to grow unboundedly across long-lived
+        // adapters with frequent reconnects — only `stop()` reset it, and a
+        // daemon that lives weeks between restarts accumulates the full
+        // outbound history. Even with the FIFO cap, every reconnect deserves
+        // a fresh window because previous-socket ids are no longer ours to
+        // dedup.
+        this.sentMessageIds.clear();
         sock.ev.on("creds.update", this.authState.saveCreds);
         sock.ev.on("creds.update", (update) => {
             this.captureOwnerIdentity(update);
@@ -756,7 +902,6 @@ export class WhatsAppAdapter {
             void this.handleConnectionUpdate(update, sock);
         });
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async handleConnectionUpdate(update, sock) {
         if (sock !== this.sock)
             return;
@@ -777,6 +922,8 @@ export class WhatsAppAdapter {
             this.connectionState = "ok";
             this.lastError = null;
             this.reconnectAttempts = 0;
+            this.reconnecting = false;
+            this.lastCloseWasNetwork = false;
             this.clearQrSnapshot();
             this.clearQrFile();
             logger.info("whatsapp connected");
@@ -791,8 +938,9 @@ export class WhatsAppAdapter {
         if (this.intentionalClose) {
             return;
         }
-        const statusCode = update?.lastDisconnect?.error?.output?.statusCode
-            ?? update?.lastDisconnect?.error?.data?.statusCode
+        const boomError = update?.lastDisconnect?.error;
+        const statusCode = boomError?.output?.statusCode
+            ?? boomError?.data?.statusCode
             ?? null;
         this.closeSocket();
         this.clearQrSnapshot();
@@ -807,6 +955,7 @@ export class WhatsAppAdapter {
             /* v8 ignore next 1 — statusCode is always a number when isLoggedOut=true */
             this.lastError = `WhatsApp logged out (status ${statusCode ?? "unknown"}) — re-pair required`;
             this.reconnectAttempts = 0;
+            this.reconnecting = false;
             logger.error({ statusCode }, "whatsapp connection closed: logged out");
             if (this.onLoggedOut) {
                 try {
@@ -821,8 +970,14 @@ export class WhatsAppAdapter {
         if (this.shuttingDown) {
             this.connectionState = "disabled";
             this.reconnectAttempts = 0;
+            this.reconnecting = false;
             return;
         }
+        // Classify the close: a transport/network failure (or a raw socket error
+        // with no Boom code) is safe to retry indefinitely under the sustained
+        // watch; anything else is an app-layer rejection that keeps the hard cap.
+        this.lastCloseWasNetwork =
+            statusCode === null || TRANSIENT_NETWORK_STATUS_CODES.has(statusCode);
         // Version-rejection codes mean WhatsApp doesn't accept the client version
         // we advertised. Drop the cache so the next connect re-fetches a fresh
         // version, then fall through to the normal backoff path.
@@ -842,51 +997,128 @@ export class WhatsAppAdapter {
         this.scheduleReconnect();
     }
     /**
-     * Schedule the next reconnect attempt with full-jitter exponential backoff.
+     * Schedule the next reconnect attempt.
      *
-     * - Delay: `min(initial * factor^attempt, max) + random(0, jitter)`
-     * - Cap: after {@link RECONNECT_MAX_ATTEMPTS} consecutive failures the loop
-     *   stops and the adapter sits in `disconnected` until something external
-     *   (e.g. the dashboard's "Refresh QR" button → `requestQR()`) restarts it.
+     * Two phases:
      *
-     * Why a hard cap: when WhatsApp is blocking us (bad version, throttled IP,
-     * regional outage) every retry burns CPU and risks escalating the block.
-     * Better to surface the error and let the user decide whether to wait it
-     * out or rotate IP / re-pair.
+     *  1. **Fast phase** (`reconnectAttempts < RECONNECT_MAX_ATTEMPTS`) —
+     *     full-jitter exponential backoff, `min(initial * factor^attempt, max) +
+     *     random(0, jitter)`. Recovers quick blips in seconds.
+     *  2. **Sustained watch** (fast phase exhausted, last close was
+     *     network-class) — a fixed long cadence; {@link runReconnectAttempt}
+     *     gates each attempt on a connectivity probe so we only open a socket to
+     *     WhatsApp once the network is back. Never gives up; the attempt counter
+     *     is pinned at the cap to avoid unbounded growth across a long offline
+     *     window. This is what lets a laptop carried out of WiFi range recover
+     *     on its own instead of wedging in an error state.
+     *
+     * If the fast phase exhausts on a *non*-network close (WhatsApp rejecting us
+     * at the app layer — bad version, bad session, throttle) we stop and surface
+     * an error: hammering a relay that keeps closing us is the fast path to an
+     * IP-level block and needs operator action (re-pair / wait it out).
      */
     scheduleReconnect() {
         if (this.reconnectTimer || this.shuttingDown)
             return;
         if (this.connectionState === "logged_out")
             return;
-        if (this.reconnectAttempts >= RECONNECT_MAX_ATTEMPTS) {
+        const exhaustedFastPhase = this.reconnectAttempts >= RECONNECT_MAX_ATTEMPTS;
+        if (exhaustedFastPhase && !this.lastCloseWasNetwork) {
             const previousError = this.lastError ?? "unknown error";
             this.lastError = `WhatsApp reconnect gave up after ${RECONNECT_MAX_ATTEMPTS} attempts (${previousError})`;
+            this.reconnecting = false;
             logger.error({ attempts: this.reconnectAttempts, lastError: previousError }, "whatsapp reconnect: max attempts exceeded");
             return;
         }
-        const exponential = Math.min(RECONNECT_INITIAL_DELAY_MS * RECONNECT_BACKOFF_FACTOR ** this.reconnectAttempts, RECONNECT_MAX_DELAY_MS);
-        const jitter = Math.floor(Math.random() * RECONNECT_JITTER_MS);
-        const delayMs = exponential + jitter;
-        this.reconnectAttempts += 1;
-        logger.info({ attempt: this.reconnectAttempts, delayMs }, "whatsapp reconnect scheduled");
+        let delayMs;
+        if (exhaustedFastPhase) {
+            // Sustained network watch — fixed cadence, counter left pinned at the
+            // cap so we stay in this branch without growing reconnectAttempts.
+            delayMs =
+                RECONNECT_SUSTAINED_DELAY_MS
+                    + Math.floor(Math.random() * RECONNECT_SUSTAINED_JITTER_MS);
+        }
+        else {
+            const exponential = Math.min(RECONNECT_INITIAL_DELAY_MS * RECONNECT_BACKOFF_FACTOR ** this.reconnectAttempts, RECONNECT_MAX_DELAY_MS);
+            delayMs = exponential + Math.floor(Math.random() * RECONNECT_JITTER_MS);
+            this.reconnectAttempts += 1;
+        }
+        this.reconnecting = true;
+        logger.info({ attempt: this.reconnectAttempts, delayMs, sustained: exhaustedFastPhase }, "whatsapp reconnect scheduled");
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             if (this.shuttingDown || this.connectionState === "logged_out") {
+                this.reconnecting = false;
                 return;
             }
-            void this.connect().catch((err) => {
-                // connect() throws synchronously on a misconfigured adapter; the
-                // close-event path can't recover that, so we have to feed the loop
-                // ourselves. Errors here are already counted in reconnectAttempts.
-                logger.error({ err }, "whatsapp reconnect attempt threw");
-                this.connectionState = "disconnected";
-                this.lastError = err instanceof Error ? err.message : String(err);
-                this.scheduleReconnect();
-            });
+            void this.runReconnectAttempt(exhaustedFastPhase);
         }, delayMs);
         this.reconnectTimer.unref?.();
     }
+    /**
+     * Carry out one reconnect attempt. In the sustained watch we first probe
+     * connectivity: if we're still offline, keep watching without poking
+     * WhatsApp (zero ban risk, near-zero cost); once the network is back we
+     * reset to a fresh fast phase and reconnect.
+     *
+     * Why reset the counter on reachability (not just on a clean `open`): when
+     * the network returns, the first reconnect frequently replays WhatsApp's
+     * handshake steps — `restartRequired` (515) and version negotiation — which
+     * close with a *non*-network status and need a few retries to clear. With
+     * the counter still pinned at the cap, that normal 515 would hit
+     * `exhausted && !network` in {@link scheduleReconnect} and falsely give up.
+     * A fresh fast phase gives those handshake closes their proper retry budget
+     * (a clean `open` doesn't fire before a 515, so we can't rely on it here).
+     */
+    async runReconnectAttempt(sustained) {
+        if (sustained) {
+            const reachable = await this.isNetworkReachable();
+            // shuttingDown / logged_out may have flipped during the async probe.
+            if (this.shuttingDown || this.connectionState === "logged_out") {
+                this.reconnecting = false;
+                return;
+            }
+            if (!reachable) {
+                logger.debug("whatsapp reconnect: network unreachable, continuing sustained watch");
+                this.scheduleReconnect();
+                return;
+            }
+            logger.info("whatsapp reconnect: network reachable, reconnecting");
+            this.reconnectAttempts = 0;
+        }
+        try {
+            await this.connect();
+        }
+        catch (err) {
+            // connect() only throws on a misconfigured adapter (deps/auth not
+            // initialized) — never on a network failure, which always arrives via
+            // the close *event*. So a thrown connect is a local, non-network error:
+            // mark it as such so a persistent failure gives up at the cap instead of
+            // looping forever in the sustained watch (it would otherwise inherit a
+            // stale lastCloseWasNetwork=true from the close that started the watch).
+            logger.error({ err }, "whatsapp reconnect attempt threw");
+            this.connectionState = "disconnected";
+            this.lastError = err instanceof Error ? err.message : String(err);
+            this.lastCloseWasNetwork = false;
+            this.scheduleReconnect();
+        }
+    }
+    /**
+     * Cheap connectivity probe for the sustained watch: resolve a WhatsApp host
+     * through the OS resolver. We deliberately do NOT open a socket to the relay
+     * here — a DNS lookup is enough to tell "the laptop has a working network
+     * path again" without poking WhatsApp's servers while we may be throttled or
+     * offline. Fails fast (EAI_AGAIN / ENOTFOUND) when there is no network.
+     */
+    async isNetworkReachable() {
+        try {
+            await this.dnsLookup(WA_REACHABILITY_PROBE_HOST);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     handleMessagesUpsert(payload) {
         const messages = Array.isArray(payload?.messages)
             ? payload.messages
@@ -897,7 +1129,6 @@ export class WhatsAppAdapter {
             });
         }
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async handleIncomingMessage(rawMessage) {
         const remoteJid = rawMessage?.key?.remoteJid;
         const messageId = rawMessage?.key?.id;
@@ -967,12 +1198,11 @@ export class WhatsAppAdapter {
         });
         this.onMessage(event);
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async extractAndIngestWhatsAppMedia(rawMessage) {
         /* v8 ignore next 1 — caller already checks attachmentStore && downloadMediaMessage */
         if (!this.attachmentStore || !this.downloadMediaMessage)
             return [];
-        const msg = unwrapWhatsAppMessage(rawMessage?.message ?? null);
+        const msg = unwrapWhatsAppMessage((rawMessage?.message ?? null));
         if (!msg)
             return [];
         const refs = [];
@@ -1043,15 +1273,13 @@ export class WhatsAppAdapter {
         }
         return refs;
     }
-    async downloadAndIngestWhatsApp(
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    rawMessage, mimeType, filename, maxBytes, caption) {
+    async downloadAndIngestWhatsApp(rawMessage, mimeType, filename, maxBytes, caption) {
         /* v8 ignore next 1 — caller (extractAndIngestWhatsAppMedia) already checks both are set */
         if (!this.downloadMediaMessage || !this.attachmentStore)
             return null;
         let buf;
         try {
-            buf = await this.downloadMediaMessage(rawMessage, "buffer");
+            buf = await this.downloadMediaMessage(rawMessage, "buffer", {});
         }
         catch (err) {
             logger.error({ err }, "whatsapp downloadMediaMessage failed");
@@ -1192,7 +1420,16 @@ export class WhatsAppAdapter {
         // Without this, repeated reconnection cycles accumulate stale listeners
         // on the old socket's EventEmitter until the socket is garbage collected.
         try {
-            sock.ev?.removeAllListeners?.();
+            // Baileys' typed emitter constrains removeAllListeners(event) to a
+            // single known event name, but at runtime its prototype chain inherits
+            // EventEmitter#removeAllListeners() which accepts no args and wipes
+            // every listener — including Baileys' own internal subscriptions
+            // attached during socket setup. We want that wildcard sweep here so
+            // a reconnect cycle doesn't leak internal listeners on the previous
+            // socket's emitter. Cast through the Node EventEmitter shape to skip
+            // the narrowed typed signature without losing the runtime behaviour.
+            sock.ev
+                ?.removeAllListeners?.();
         }
         catch {
             // Ignore — ev may already be torn down.
@@ -1212,4 +1449,3 @@ export class WhatsAppAdapter {
         this.intentionalClose = false;
     }
 }
-//# sourceMappingURL=whatsapp-adapter.js.map