@gakr-gakr/whatsapp 0.1.0

package/src/auto-reply/monitor.ts

@@ -0,0 +1,720 @@
+import { resolveAccountEntry } from "autobot/plugin-sdk/account-core";
+import { resolveInboundDebounceMs } from "autobot/plugin-sdk/channel-inbound-debounce";
+import { formatCliCommand } from "autobot/plugin-sdk/cli-runtime";
+import { hasControlCommand } from "autobot/plugin-sdk/command-detection";
+import { drainPendingDeliveries } from "autobot/plugin-sdk/delivery-queue-runtime";
+import { DEFAULT_GROUP_HISTORY_LIMIT } from "autobot/plugin-sdk/reply-history";
+import { resolveAgentRoute } from "autobot/plugin-sdk/routing";
+import { logVerbose } from "autobot/plugin-sdk/runtime-env";
+import { registerUnhandledRejectionHandler } from "autobot/plugin-sdk/runtime-env";
+import { getChildLogger } from "autobot/plugin-sdk/runtime-env";
+import {
+  defaultRuntime,
+  formatDurationPrecise,
+  warn,
+  type RuntimeEnv,
+} from "autobot/plugin-sdk/runtime-env";
+import { enqueueSystemEvent } from "autobot/plugin-sdk/system-event-runtime";
+import { resolveWhatsAppAccount, resolveWhatsAppMediaMaxBytes } from "../accounts.js";
+import { WHATSAPP_AUTH_UNSTABLE_CODE, WhatsAppAuthUnstableError } from "../auth-store.js";
+import {
+  WhatsAppConnectionController,
+  WHATSAPP_WATCHDOG_TIMEOUT_ERROR,
+  type ManagedWhatsAppListener,
+} from "../connection-controller.js";
+import { resolveWhatsAppInboundPolicy } from "../inbound-policy.js";
+import { attachWebInboxToSocket, type WhatsAppGroupMetadataCache } from "../inbound/monitor.js";
+import {
+  newConnectionId,
+  resolveHeartbeatSeconds,
+  resolveReconnectPolicy,
+  sleepWithAbort,
+} from "../reconnect.js";
+import {
+  formatError,
+  getStatusCode,
+  getWebAuthAgeMs,
+  logoutWeb,
+  readWebSelfId,
+} from "../session.js";
+import { resolveWhatsAppSocketTiming } from "../socket-timing.js";
+import { getRuntimeConfig, getRuntimeConfigSourceSnapshot } from "./config.runtime.js";
+import { whatsappHeartbeatLog, whatsappLog } from "./loggers.js";
+import { buildMentionConfig } from "./mentions.js";
+import { createWebChannelStatusController } from "./monitor-state.js";
+import { createEchoTracker } from "./monitor/echo.js";
+import { formatWhatsAppInboundListeningLog } from "./monitor/listener-log.js";
+import { createWebOnMessageHandler } from "./monitor/on-message.js";
+import type { WebInboundMsg, WebMonitorTuning } from "./types.js";
+import { isLikelyWhatsAppCryptoError } from "./util.js";
+
+function isNonRetryableWebCloseStatus(statusCode: unknown): boolean {
+  // WhatsApp 440 = session conflict ("Unknown Stream Errored (conflict)").
+  // This is persistent until the operator resolves the conflicting session.
+  // Baileys 428 = DisconnectReason.connectionClosed, a generic WebSocket close
+  // that is often transient and must stay on the reconnect path.
+  return statusCode === 440;
+}
+
+type ReplyResolver = typeof import("./reply-resolver.runtime.js").getReplyFromConfig;
+type WhatsAppRuntimeConfig = ReturnType<typeof getRuntimeConfig>;
+
+let replyResolverRuntimePromise: Promise<typeof import("./reply-resolver.runtime.js")> | null =
+  null;
+
+function loadReplyResolverRuntime() {
+  replyResolverRuntimePromise ??= import("./reply-resolver.runtime.js");
+  return replyResolverRuntimePromise;
+}
+
+function resolveWebMonitorConfigSnapshot(params: {
+  cfg: WhatsAppRuntimeConfig;
+  accountId?: string | null;
+}): {
+  cfg: WhatsAppRuntimeConfig;
+  account: ReturnType<typeof resolveWhatsAppAccount>;
+} {
+  const account = resolveWhatsAppAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  const cfg = {
+    ...params.cfg,
+    channels: {
+      ...params.cfg.channels,
+      whatsapp: {
+        ...params.cfg.channels?.whatsapp,
+        ackReaction: account.ackReaction,
+        messagePrefix: account.messagePrefix,
+        allowFrom: account.allowFrom,
+        groupAllowFrom: account.groupAllowFrom,
+        groupPolicy: account.groupPolicy,
+        textChunkLimit: account.textChunkLimit,
+        chunkMode: account.chunkMode,
+        mediaMaxMb: account.mediaMaxMb,
+        blockStreaming: account.blockStreaming,
+        groups: account.groups,
+      },
+    },
+  } satisfies WhatsAppRuntimeConfig;
+  return { cfg, account };
+}
+
+function normalizeReconnectAccountId(accountId?: string | null): string {
+  return (accountId ?? "").trim() || "default";
+}
+
+function isNoListenerReconnectError(lastError?: string): boolean {
+  return typeof lastError === "string" && /No active WhatsApp Web listener/i.test(lastError);
+}
+
+function resolveExplicitWhatsAppDebounceOverride(params: {
+  cfg: ReturnType<typeof getRuntimeConfig>;
+  sourceCfg?: ReturnType<typeof getRuntimeConfig> | null;
+  accountId: string;
+}): number | undefined {
+  const channel = params.sourceCfg?.channels?.whatsapp;
+  if (!channel) {
+    return undefined;
+  }
+
+  const accountId = normalizeReconnectAccountId(params.accountId);
+  const accountDebounce = resolveAccountEntry(channel.accounts, accountId)?.debounceMs;
+  if (accountDebounce !== undefined) {
+    return accountDebounce;
+  }
+  if (accountId !== "default") {
+    const defaultAccountDebounce = resolveAccountEntry(channel.accounts, "default")?.debounceMs;
+    if (defaultAccountDebounce !== undefined) {
+      return defaultAccountDebounce;
+    }
+  }
+
+  return channel.debounceMs;
+}
+
+function isRetryableAuthUnstableError(error: unknown): error is WhatsAppAuthUnstableError {
+  return (
+    error instanceof WhatsAppAuthUnstableError ||
+    (typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      (error as { code?: unknown }).code === WHATSAPP_AUTH_UNSTABLE_CODE)
+  );
+}
+
+async function clearTerminalWebAuthState(params: {
+  account: ReturnType<typeof resolveWhatsAppAccount>;
+  runtime: RuntimeEnv;
+  statusLabel: number | "unknown";
+  healthState: "logged-out" | "conflict";
+  log: ReturnType<typeof getChildLogger>;
+}) {
+  try {
+    const cleared = await logoutWeb({
+      authDir: params.account.authDir,
+      isLegacyAuthDir: params.account.isLegacyAuthDir,
+      runtime: params.runtime,
+    });
+    params.log.warn(
+      {
+        accountId: params.account.accountId,
+        cleared,
+        healthState: params.healthState,
+        status: params.statusLabel,
+      },
+      "web reconnect: cleared cached auth after terminal close",
+    );
+  } catch (error) {
+    params.log.warn(
+      {
+        accountId: params.account.accountId,
+        error: formatError(error),
+        healthState: params.healthState,
+        status: params.statusLabel,
+      },
+      "web reconnect: failed clearing cached auth after terminal close",
+    );
+    params.runtime.error(
+      `WhatsApp Web cleanup failed after terminal close (status ${params.statusLabel}). Run \`${formatCliCommand("autobot channels logout --channel whatsapp")}\`, then relink with \`${formatCliCommand("autobot channels login --channel whatsapp")}\`.`,
+    );
+  }
+}
+const DEFAULT_TRANSPORT_TIMEOUT_MS = 5 * 60 * 1000;
+
+export async function monitorWebChannel(
+  verbose: boolean,
+  listenerFactory: typeof attachWebInboxToSocket | undefined = attachWebInboxToSocket,
+  keepAlive = true,
+  replyResolver?: ReplyResolver,
+  runtime: RuntimeEnv = defaultRuntime,
+  abortSignal?: AbortSignal,
+  tuning: WebMonitorTuning = {},
+) {
+  const activeReplyResolver =
+    replyResolver ?? (await loadReplyResolverRuntime()).getReplyFromConfig;
+  const runId = newConnectionId();
+  const replyLogger = getChildLogger({ module: "web-auto-reply", runId });
+  const heartbeatLogger = getChildLogger({ module: "web-heartbeat", runId });
+  const reconnectLogger = getChildLogger({ module: "web-reconnect", runId });
+  const statusController = createWebChannelStatusController(tuning.statusSink);
+  statusController.emit();
+
+  const baseCfg = getRuntimeConfig();
+  const sourceCfg = getRuntimeConfigSourceSnapshot();
+  const { cfg, account } = resolveWebMonitorConfigSnapshot({
+    cfg: baseCfg,
+    accountId: tuning.accountId,
+  });
+  const loadCurrentMonitorConfig = () =>
+    resolveWebMonitorConfigSnapshot({
+      cfg: getRuntimeConfig(),
+      accountId: account.accountId,
+    }).cfg;
+
+  const maxMediaBytes = resolveWhatsAppMediaMaxBytes(account);
+  const heartbeatSeconds = resolveHeartbeatSeconds(cfg, tuning.heartbeatSeconds);
+  const reconnectPolicy = resolveReconnectPolicy(cfg, tuning.reconnect);
+  const socketTiming = resolveWhatsAppSocketTiming(cfg, tuning.socketTiming);
+  const baseMentionConfig = buildMentionConfig(cfg);
+  const groupHistoryLimit =
+    account.historyLimit ??
+    cfg.channels?.whatsapp?.historyLimit ??
+    cfg.messages?.groupChat?.historyLimit ??
+    DEFAULT_GROUP_HISTORY_LIMIT;
+  const groupHistories = new Map<
+    string,
+    Array<{
+      sender: string;
+      body: string;
+      timestamp?: number;
+      id?: string;
+      senderJid?: string;
+    }>
+  >();
+  const groupMemberNames = new Map<string, Map<string, string>>();
+  const groupMetadataCache: WhatsAppGroupMetadataCache = new Map();
+  const echoTracker = createEchoTracker({ maxItems: 100, logVerbose });
+
+  const sleep =
+    tuning.sleep ??
+    ((ms: number, signal?: AbortSignal) => sleepWithAbort(ms, signal ?? abortSignal));
+  const stopRequested = () => abortSignal?.aborted === true;
+
+  // Avoid noisy MaxListenersExceeded warnings in test environments where
+  // multiple gateway instances may be constructed.
+  const currentMaxListeners = process.getMaxListeners?.() ?? 10;
+  if (process.setMaxListeners && currentMaxListeners < 50) {
+    process.setMaxListeners(50);
+  }
+
+  let sigintStop = false;
+  const handleSigint = () => {
+    sigintStop = true;
+  };
+  process.once("SIGINT", handleSigint);
+
+  const transportTimeoutMs = tuning.transportTimeoutMs ?? DEFAULT_TRANSPORT_TIMEOUT_MS;
+  const messageTimeoutMs = tuning.messageTimeoutMs ?? 30 * 60 * 1000;
+  const watchdogCheckMs = tuning.watchdogCheckMs ?? 60 * 1000;
+  const controller = new WhatsAppConnectionController({
+    accountId: account.accountId,
+    authDir: account.authDir,
+    verbose,
+    keepAlive,
+    heartbeatSeconds,
+    transportTimeoutMs,
+    messageTimeoutMs,
+    watchdogCheckMs,
+    reconnectPolicy,
+    socketTiming,
+    abortSignal,
+    sleep,
+    isNonRetryableStatus: isNonRetryableWebCloseStatus,
+  });
+
+  try {
+    while (true) {
+      if (stopRequested()) {
+        break;
+      }
+
+      const connectionId = newConnectionId();
+      const inboundDebounceMs = resolveInboundDebounceMs({
+        cfg,
+        channel: "whatsapp",
+        overrideMs: resolveExplicitWhatsAppDebounceOverride({
+          cfg,
+          sourceCfg,
+          accountId: account.accountId,
+        }),
+      });
+      const shouldDebounce = (msg: WebInboundMsg) => {
+        if (msg.mediaPath || msg.mediaType) {
+          return false;
+        }
+        if (msg.location) {
+          return false;
+        }
+        if (msg.replyToId || msg.replyToBody) {
+          return false;
+        }
+        return !hasControlCommand(msg.body, cfg);
+      };
+
+      let connection;
+      try {
+        connection = await controller.openConnection({
+          connectionId,
+          createListener: async ({ sock, connection }) => {
+            const onMessage = createWebOnMessageHandler({
+              cfg,
+              loadConfig: loadCurrentMonitorConfig,
+              verbose,
+              connectionId,
+              maxMediaBytes,
+              groupHistoryLimit,
+              groupHistories,
+              groupMemberNames,
+              echoTracker,
+              backgroundTasks: connection.backgroundTasks,
+              replyResolver: activeReplyResolver,
+              replyLogger,
+              baseMentionConfig,
+              account,
+            });
+
+            return (await (listenerFactory ?? attachWebInboxToSocket)({
+              cfg,
+              loadConfig: loadCurrentMonitorConfig,
+              verbose,
+              accountId: account.accountId,
+              authDir: account.authDir,
+              mediaMaxMb: account.mediaMaxMb,
+              selfChatMode: account.selfChatMode,
+              sendReadReceipts: account.sendReadReceipts,
+              debounceMs: inboundDebounceMs,
+              shouldDebounce,
+              socketRef: controller.socketRef,
+              shouldRetryDisconnect: () => !sigintStop && controller.shouldRetryDisconnect(),
+              disconnectRetryPolicy: reconnectPolicy,
+              disconnectRetryAbortSignal: controller.getDisconnectRetryAbortSignal(),
+              groupMetadataCache,
+              onMessage: async (msg: WebInboundMsg) => {
+                const inboundAt = Date.now();
+                controller.noteInbound(inboundAt);
+                statusController.noteInbound(inboundAt);
+                await onMessage(msg);
+              },
+              sock,
+            })) as ManagedWhatsAppListener;
+          },
+          onHeartbeat: (snapshot) => {
+            const authAgeMs = getWebAuthAgeMs(account.authDir);
+            const minutesSinceLastMessage = snapshot.lastInboundAt
+              ? Math.floor((Date.now() - snapshot.lastInboundAt) / 60000)
+              : null;
+
+            const logData = {
+              connectionId: snapshot.connectionId,
+              reconnectAttempts: snapshot.reconnectAttempts,
+              messagesHandled: snapshot.handledMessages,
+              lastInboundAt: snapshot.lastInboundAt,
+              lastTransportActivityAt: snapshot.lastTransportActivityAt,
+              authAgeMs,
+              uptimeMs: snapshot.uptimeMs,
+              ...(minutesSinceLastMessage !== null && minutesSinceLastMessage > 30
+                ? { minutesSinceLastMessage }
+                : {}),
+            };
+            statusController.noteTransportActivity(snapshot.lastTransportActivityAt);
+
+            if (minutesSinceLastMessage && minutesSinceLastMessage > 30) {
+              heartbeatLogger.warn(
+                logData,
+                "⚠️ web gateway heartbeat - no messages in 30+ minutes",
+              );
+            } else {
+              heartbeatLogger.info(logData, "web gateway heartbeat");
+            }
+          },
+          onWatchdogTimeout: (snapshot) => {
+            const now = Date.now();
+            const transportSilentMs = now - snapshot.lastTransportActivityAt;
+            const appBaselineAt = snapshot.lastInboundAt ?? snapshot.startedAt;
+            const minutesSinceTransportActivity = Math.floor(transportSilentMs / 60000);
+            const minutesSinceAppActivity = Math.floor((now - appBaselineAt) / 60000);
+            const watchdogReason =
+              transportSilentMs > transportTimeoutMs ? "transport-inactive" : "app-silent";
+            statusController.noteWatchdogStale();
+            heartbeatLogger.warn(
+              {
+                connectionId: snapshot.connectionId,
+                watchdogReason,
+                minutesSinceTransportActivity,
+                minutesSinceAppActivity,
+                lastInboundAt: snapshot.lastInboundAt ? new Date(snapshot.lastInboundAt) : null,
+                lastTransportActivityAt: new Date(snapshot.lastTransportActivityAt),
+                messagesHandled: snapshot.handledMessages,
+              },
+              "WhatsApp watchdog timeout detected - forcing reconnect",
+            );
+            whatsappHeartbeatLog.warn(
+              `WhatsApp watchdog timeout (${watchdogReason}) - restarting connection`,
+            );
+          },
+        });
+      } catch (error) {
+        if (getStatusCode(error) === 428) {
+          const retryDecision = controller.consumeReconnectAttempt();
+          statusController.noteReconnectAttempts(retryDecision.reconnectAttempts);
+          statusController.noteClose({
+            statusCode: 428,
+            error: formatError(error),
+            reconnectAttempts: retryDecision.reconnectAttempts,
+            healthState: retryDecision.healthState,
+          });
+          if (retryDecision.action === "stop") {
+            reconnectLogger.warn(
+              {
+                connectionId,
+                status: 428,
+                reconnectAttempts: retryDecision.reconnectAttempts,
+                maxAttempts: reconnectPolicy.maxAttempts,
+              },
+              "web reconnect: 428 during opening; max attempts reached",
+            );
+            runtime.error(
+              `WhatsApp Web connection closed during setup (status 428) after ${retryDecision.reconnectAttempts}/${reconnectPolicy.maxAttempts} attempts. Relink with \`${formatCliCommand("autobot channels login --channel whatsapp")}\` if the issue persists.`,
+            );
+            await controller.shutdown();
+            break;
+          }
+          reconnectLogger.info(
+            {
+              connectionId,
+              status: 428,
+              reconnectAttempts: retryDecision.reconnectAttempts,
+              delayMs: retryDecision.delayMs,
+            },
+            "web reconnect: 428 during opening; retrying",
+          );
+          runtime.error(
+            `WhatsApp Web connection closed during setup (status 428). Retry ${retryDecision.reconnectAttempts}/${reconnectPolicy.maxAttempts || "∞"} in ${formatDurationPrecise(retryDecision.delayMs ?? 0)}.`,
+          );
+          try {
+            await controller.waitBeforeRetry(retryDecision.delayMs ?? 0);
+          } catch {
+            break;
+          }
+          continue;
+        }
+        if (!isRetryableAuthUnstableError(error)) {
+          throw error;
+        }
+        const retryDecision = controller.consumeReconnectAttempt();
+        statusController.noteReconnectAttempts(retryDecision.reconnectAttempts);
+        statusController.noteClose({
+          error: error.message,
+          reconnectAttempts: retryDecision.reconnectAttempts,
+          healthState: retryDecision.healthState,
+        });
+        if (retryDecision.action === "stop") {
+          reconnectLogger.warn(
+            {
+              connectionId,
+              reconnectAttempts: retryDecision.reconnectAttempts,
+              maxAttempts: reconnectPolicy.maxAttempts,
+            },
+            "web reconnect: auth state stayed unstable; max attempts reached",
+          );
+          runtime.error(
+            `WhatsApp auth state is still stabilizing after ${retryDecision.reconnectAttempts}/${reconnectPolicy.maxAttempts} attempts. Stopping web monitoring.`,
+          );
+          await controller.shutdown();
+          break;
+        }
+        reconnectLogger.info(
+          {
+            connectionId,
+            reconnectAttempts: retryDecision.reconnectAttempts,
+            delayMs: retryDecision.delayMs,
+          },
+          "web reconnect: auth state still stabilizing during inbox attach; retrying",
+        );
+        runtime.error(
+          `WhatsApp auth state is still stabilizing. Retry ${retryDecision.reconnectAttempts}/${reconnectPolicy.maxAttempts || "∞"} for inbox attach in ${formatDurationPrecise(retryDecision.delayMs ?? 0)}.`,
+        );
+        try {
+          await controller.waitBeforeRetry(retryDecision.delayMs ?? 0);
+        } catch {
+          break;
+        }
+        continue;
+      }
+
+      statusController.noteConnected();
+      controller.setUnhandledRejectionCleanup(
+        registerUnhandledRejectionHandler((reason) => {
+          if (!isLikelyWhatsAppCryptoError(reason)) {
+            return false;
+          }
+          const errorStr = formatError(reason);
+          reconnectLogger.warn(
+            { connectionId: connection.connectionId, error: errorStr },
+            "web reconnect: unhandled rejection from WhatsApp socket; forcing reconnect",
+          );
+          controller.forceClose({
+            status: 499,
+            isLoggedOut: false,
+            error: reason,
+          });
+          return true;
+        }),
+      );
+
+      const { e164: selfE164 } = readWebSelfId(account.authDir);
+      const connectRoute = resolveAgentRoute({
+        cfg,
+        channel: "whatsapp",
+        accountId: account.accountId,
+      });
+      enqueueSystemEvent(`WhatsApp gateway connected${selfE164 ? ` as ${selfE164}` : ""}.`, {
+        sessionKey: connectRoute.sessionKey,
+        trusted: true,
+      });
+
+      const normalizedAccountId = normalizeReconnectAccountId(account.accountId);
+      void drainPendingDeliveries({
+        drainKey: `whatsapp:${normalizedAccountId}`,
+        logLabel: "WhatsApp reconnect drain",
+        cfg,
+        log: reconnectLogger,
+        selectEntry: (entry) => ({
+          match:
+            entry.channel === "whatsapp" &&
+            normalizeReconnectAccountId(entry.accountId) === normalizedAccountId,
+          bypassBackoff: isNoListenerReconnectError(entry.lastError),
+        }),
+      }).catch((err) => {
+        reconnectLogger.warn(
+          { connectionId: connection.connectionId, error: String(err) },
+          "reconnect drain failed",
+        );
+      });
+
+      const periodicDrainInterval = setInterval(() => {
+        void drainPendingDeliveries({
+          drainKey: `whatsapp:${normalizedAccountId}`,
+          logLabel: "WhatsApp periodic drain",
+          cfg,
+          log: reconnectLogger,
+          selectEntry: (entry) => ({
+            match:
+              entry.channel === "whatsapp" &&
+              normalizeReconnectAccountId(entry.accountId) === normalizedAccountId,
+            bypassBackoff: false,
+          }),
+        }).catch((err) => {
+          reconnectLogger.warn(
+            { connectionId: connection.connectionId, error: String(err) },
+            "periodic drain failed",
+          );
+        });
+      }, 30_000);
+
+      const inboundPolicy = resolveWhatsAppInboundPolicy({
+        cfg,
+        accountId: account.accountId,
+        selfE164: selfE164 ?? null,
+      });
+      whatsappLog.info(
+        formatWhatsAppInboundListeningLog({
+          groups: inboundPolicy.account.groups,
+          groupPolicy: inboundPolicy.groupPolicy,
+          hasGroupAllowFrom: inboundPolicy.groupAllowFrom.length > 0,
+        }),
+      );
+      if (process.stdout.isTTY || process.stderr.isTTY) {
+        whatsappLog.raw("Ctrl+C to stop.");
+      }
+
+      if (!keepAlive) {
+        clearInterval(periodicDrainInterval);
+        await controller.shutdown();
+        return;
+      }
+
+      const reason = await controller
+        .waitForClose()
+        .finally(() => clearInterval(periodicDrainInterval));
+      if (stopRequested() || sigintStop || reason === "aborted") {
+        await controller.shutdown();
+        break;
+      }
+
+      const decision = controller.resolveCloseDecision(reason);
+      if (decision === "aborted") {
+        await controller.shutdown();
+        break;
+      }
+      statusController.noteReconnectAttempts(controller.getReconnectAttempts());
+
+      reconnectLogger.info(
+        {
+          connectionId: connection.connectionId,
+          status: decision.normalized.statusLabel,
+          loggedOut: decision.normalized.isLoggedOut,
+          reconnectAttempts: decision.reconnectAttempts,
+          error: decision.normalized.errorText,
+        },
+        "web reconnect: connection closed",
+      );
+
+      enqueueSystemEvent(
+        `WhatsApp gateway disconnected (status ${decision.normalized.statusLabel})`,
+        {
+          sessionKey: connectRoute.sessionKey,
+          trusted: true,
+        },
+      );
+
+      if (decision.action === "stop") {
+        await controller.closeCurrentConnection();
+        statusController.noteClose({
+          statusCode: decision.normalized.statusCode,
+          loggedOut: decision.normalized.isLoggedOut,
+          error: decision.normalized.errorText,
+          reconnectAttempts: decision.reconnectAttempts,
+          healthState: decision.healthState,
+        });
+
+        if (decision.healthState === "logged-out") {
+          await clearTerminalWebAuthState({
+            account,
+            runtime,
+            statusLabel: decision.normalized.statusLabel,
+            healthState: decision.healthState,
+            log: reconnectLogger,
+          });
+          runtime.error(
+            `WhatsApp session logged out. Run \`${formatCliCommand("autobot channels login --channel whatsapp")}\` to relink.`,
+          );
+        } else if (decision.healthState === "conflict") {
+          await clearTerminalWebAuthState({
+            account,
+            runtime,
+            statusLabel: decision.normalized.statusLabel,
+            healthState: decision.healthState,
+            log: reconnectLogger,
+          });
+          reconnectLogger.warn(
+            {
+              connectionId: connection.connectionId,
+              status: decision.normalized.statusLabel,
+              error: decision.normalized.errorText,
+            },
+            "web reconnect: non-retryable close status; stopping monitor",
+          );
+          runtime.error(
+            `WhatsApp Web connection closed (status ${decision.normalized.statusLabel}: session conflict). Resolve conflicting WhatsApp Web sessions, then relink with \`${formatCliCommand("autobot channels login --channel whatsapp")}\`. Stopping web monitoring.`,
+          );
+        } else {
+          reconnectLogger.warn(
+            {
+              connectionId: connection.connectionId,
+              status: decision.normalized.statusLabel,
+              reconnectAttempts: decision.reconnectAttempts,
+              maxAttempts: reconnectPolicy.maxAttempts,
+            },
+            "web reconnect: max attempts reached; continuing in degraded mode",
+          );
+          runtime.error(
+            `WhatsApp Web reconnect: max attempts reached (${decision.reconnectAttempts}/${reconnectPolicy.maxAttempts}). Stopping web monitoring.`,
+          );
+        }
+
+        await controller.shutdown();
+        break;
+      }
+
+      const isWatchdogRecoveryReconnect =
+        decision.normalized.error === WHATSAPP_WATCHDOG_TIMEOUT_ERROR;
+      statusController.noteClose({
+        statusCode: decision.normalized.statusCode,
+        error: decision.normalized.errorText,
+        reconnectAttempts: decision.reconnectAttempts,
+        healthState: decision.healthState,
+        watchdogRecovery: isWatchdogRecoveryReconnect,
+      });
+      reconnectLogger.info(
+        {
+          connectionId: connection.connectionId,
+          status: decision.normalized.statusLabel,
+          reconnectAttempts: decision.reconnectAttempts,
+          maxAttempts: reconnectPolicy.maxAttempts || "unlimited",
+          delayMs: decision.delayMs,
+        },
+        "web reconnect: scheduling retry",
+      );
+      const reconnectMessage = isWatchdogRecoveryReconnect
+        ? `WhatsApp Web watchdog is recovering a stale connection (status ${decision.normalized.statusLabel}). Retry ${decision.reconnectAttempts}/${reconnectPolicy.maxAttempts || "∞"} in ${formatDurationPrecise(decision.delayMs ?? 0)}.`
+        : `WhatsApp Web connection closed (status ${decision.normalized.statusLabel}). Retry ${decision.reconnectAttempts}/${reconnectPolicy.maxAttempts || "∞"} in ${formatDurationPrecise(decision.delayMs ?? 0)}… (${decision.normalized.errorText})`;
+      if (isWatchdogRecoveryReconnect) {
+        runtime.log(warn(reconnectMessage));
+      } else {
+        runtime.error(reconnectMessage);
+      }
+      await controller.closeCurrentConnection();
+      try {
+        await controller.waitBeforeRetry(decision.delayMs ?? 0);
+      } catch {
+        break;
+      }
+    }
+  } finally {
+    statusController.markStopped();
+    process.removeListener("SIGINT", handleSigint);
+    await controller.shutdown();
+  }
+}