@omnizap-system/omnizap 2.6.1 → 2.6.3

package/app/connection/socketController.js

@@ -2,7 +2,7 @@ import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } fro
 import makeWASocket, { DisconnectReason, Browsers, getAggregateVotesInPollMessage, areJidsSameUser, WAMessageStatus, WAMessageStubType, delayCancellable, getStatusFromReceiptType, promiseTimeout } from '@whiskeysockets/baileys';
 
 import NodeCache from 'node-cache';
-import { parseEnvBool, parseEnvCsv, parseEnvInt, resolveBaileysVersion, resolveAddressingModeFromMessageKey, normalizeAddressingMode, normalizePnToJid, normalizeWAPresence, baileysConnectionLogger as logger, baileysSocketLogger } from '../config/index.js';
+import { parseEnvBool, parseEnvCsv, parseEnvInt, resolveBaileysVersion, resolveAddressingModeFromMessageKey, normalizeAddressingMode, normalizeJid, normalizePnToJid, normalizeWAPresence, isGroupJid, getMultiSessionRuntimeConfig, baileysConnectionLogger as logger, baileysSocketLogger } from '../config/index.js';
 
 import { Boom } from '@hapi/boom';
 import qrcode from 'qrcode-terminal';
@@ -16,18 +16,24 @@ import { resolveCaptchaByReaction } from '../services/messaging/captchaService.j
 
 import { handleGroupUpdate as handleGroupParticipantsEvent, handleGroupJoinRequest } from '../modules/adminModule/groupEventHandlers.js';
 
-import { dbConfig, executeQuery, findBy, findById, pool, remove } from '../../database/index.js';
+import { dbConfig, executeQuery, findBy, findById, pool, remove, TABLES } from '../../database/index.js';
 import { extractSenderInfoFromMessage, primeLidCache, resolveUserIdCached, isLidUserId, isWhatsAppUserId } from '../config/index.js';
 import { queueBaileysEventInsert, queueChatUpdate, queueLidUpdate, queueMessageInsert } from '../services/infra/dbWriteQueue.js';
 import { buildGroupMetadataFromGroup, buildGroupMetadataFromUpdate, upsertGroupMetadata, parseParticipantsFromDb } from '../services/group/groupMetadataService.js';
 import { buildMessageData } from '../configParts/messagePersistenceService.js';
+import { getOwner as getGroupOwner, tryAcquire as tryAcquireGroupOwner, heartbeatOwnerSession as heartbeatGroupOwnerSession } from '../services/multiSession/groupOwnershipService.js';
+import sessionRegistryService from '../services/multiSession/sessionRegistryService.js';
+import { createGroupOwnerWriteStateResolver, normalizeAssignmentVersion } from './groupOwnerWriteStateResolver.js';
 import { useDbAuthState } from './baileysDbAuthState.js';
+import { applyLibsignalRuntimePatch } from './baileysLibsignalPatch.js';
 
 import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+applyLibsignalRuntimePatch();
+
 /**
  * Indica se o ambiente de execução é de produção.
  * @type {boolean}
@@ -132,14 +138,31 @@ const BAILEYS_GROUP_METADATA_CACHE_TTL_SECONDS = parseEnvInt(process.env.BAILEYS
  */
 const BAILEYS_GROUP_METADATA_CACHE_CHECKPERIOD_SECONDS = parseEnvInt(process.env.BAILEYS_GROUP_METADATA_CACHE_CHECKPERIOD_SECONDS, 60, 10, 1800);
 /**
- * Identificador lógico da sessão de autenticação do Baileys no MySQL.
- * Permite isolar múltiplas sessões no mesmo banco.
+ * Configuração de runtime para múltiplas sessões do Baileys.
+ * @type {{
+ *   sessionIds?: string[],
+ *   primarySessionId?: string,
+ *   ownerLeaseMs?: number,
+ *   ownerHeartbeatMs?: number,
+ *   sessionWeights?: Record<string, number>
+ * }}
+ */
+const MULTI_SESSION_RUNTIME_CONFIG = getMultiSessionRuntimeConfig();
+/**
+ * Lista imutável de IDs de sessão habilitadas.
+ * @type {readonly string[]}
+ */
+const BAILEYS_SESSION_IDS = Object.freeze(Array.isArray(MULTI_SESSION_RUNTIME_CONFIG?.sessionIds) && MULTI_SESSION_RUNTIME_CONFIG.sessionIds.length > 0 ? [...MULTI_SESSION_RUNTIME_CONFIG.sessionIds] : [String(process.env.BAILEYS_AUTH_SESSION_ID || 'default').trim() || 'default']);
+/**
+ * Conjunto para consultas rápidas de sessão válida.
+ * @type {Set<string>}
+ */
+const BAILEYS_SESSION_ID_SET = new Set(BAILEYS_SESSION_IDS);
+/**
+ * ID de sessão principal usado como fallback.
  * @type {string}
  */
-const BAILEYS_AUTH_SESSION_ID = (() => {
-  const raw = String(process.env.BAILEYS_AUTH_SESSION_ID || '').trim();
-  return raw || 'default';
-})();
+const BAILEYS_PRIMARY_SESSION_ID = String(MULTI_SESSION_RUNTIME_CONFIG?.primarySessionId || BAILEYS_SESSION_IDS[0] || 'default').trim() || 'default';
 /**
  * Habilita bootstrap inicial do auth state no MySQL usando os arquivos locais legados.
  * @type {boolean}
@@ -164,12 +187,111 @@ const BAILEYS_SINGLE_WRITER_LOCK_RETRY_DELAY_MS = parseEnvInt(process.env.BAILEY
  * Nome do lock de escritor único usado no MySQL.
  * @type {string}
  */
-const BAILEYS_SINGLE_WRITER_LOCK_NAME = (() => {
+const BAILEYS_SINGLE_WRITER_LOCK_NAME_BASE = (() => {
   const raw = String(process.env.BAILEYS_SINGLE_WRITER_LOCK_NAME || '').trim();
   if (raw) return raw;
   const dbLabel = String(dbConfig?.database || 'db').replace(/[^a-zA-Z0-9:_-]+/g, '_');
   return `omnizap:baileys:writer:${dbLabel}`;
 })();
+
+/**
+ * Normaliza um ID de sessão, garantindo fallback para a sessão principal.
+ * @param {string | null | undefined} sessionId
+ * @returns {string}
+ */
+const normalizeSessionId = (sessionId) => {
+  const normalized = String(sessionId || '').trim();
+  if (!normalized) return BAILEYS_PRIMARY_SESSION_ID;
+  if (!BAILEYS_SESSION_ID_SET.has(normalized)) return BAILEYS_PRIMARY_SESSION_ID;
+  return normalized;
+};
+
+/**
+ * Resolve o nome final do lock de escritor único para uma sessão.
+ * @param {string | null | undefined} sessionId
+ * @returns {string}
+ */
+const getWriterLockNameBySession = (sessionId) => {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const base = BAILEYS_SINGLE_WRITER_LOCK_NAME_BASE;
+  if (base.includes('{sessionId}')) {
+    return base.replace(/\{sessionId\}/g, safeSessionId);
+  }
+  return `${base}:${safeSessionId}`;
+};
+
+/**
+ * TTL do cache local de ownership de grupo (em milissegundos).
+ * @type {number}
+ */
+const GROUP_OWNER_WRITE_CACHE_TTL_MS = parseEnvInt(process.env.GROUP_OWNER_WRITE_CACHE_TTL_MS, Math.max(2_000, Math.floor((Number(MULTI_SESSION_RUNTIME_CONFIG?.ownerHeartbeatMs) || 30_000) / 3)), 1_000, 60_000);
+/**
+ * Permite tentar reivindicar ownership no miss de cache.
+ * @type {boolean}
+ */
+const GROUP_OWNER_WRITE_CLAIM_ON_MISS = parseEnvBool(process.env.GROUP_OWNER_WRITE_CLAIM_ON_MISS, true);
+/**
+ * Duração da lease de ownership por sessão (em milissegundos).
+ * @type {number}
+ */
+const GROUP_OWNER_LEASE_MS = Math.max(5_000, Number(MULTI_SESSION_RUNTIME_CONFIG?.ownerLeaseMs) || 120_000);
+/**
+ * Intervalo de heartbeat de ownership (em milissegundos).
+ * @type {number}
+ */
+let GROUP_OWNER_HEARTBEAT_MS = parseEnvInt(process.env.GROUP_OWNER_HEARTBEAT_RUNTIME_MS, Math.max(1_000, Math.min(GROUP_OWNER_LEASE_MS - 500, Number(MULTI_SESSION_RUNTIME_CONFIG?.ownerHeartbeatMs) || 30_000)), 1_000, 5 * 60 * 1000);
+if (GROUP_OWNER_HEARTBEAT_MS >= GROUP_OWNER_LEASE_MS) {
+  GROUP_OWNER_HEARTBEAT_MS = Math.max(1_000, Math.floor(GROUP_OWNER_LEASE_MS / 2));
+}
+/**
+ * Cache local de decisões de escrita por ownership de grupo.
+ * @type {NodeCache}
+ */
+const groupOwnerWriteStateCache = new NodeCache({
+  stdTTL: Math.max(1, Math.ceil(GROUP_OWNER_WRITE_CACHE_TTL_MS / 1000)),
+  checkperiod: Math.max(1, Math.ceil(GROUP_OWNER_WRITE_CACHE_TTL_MS / 1000)),
+  useClones: false,
+});
+
+/**
+ * Monta a chave de cache de ownership para uma combinação sessão+grupo.
+ * @param {string | null | undefined} groupJid
+ * @param {string | null | undefined} sessionId
+ * @returns {string}
+ */
+const buildGroupOwnerWriteCacheKey = (groupJid, sessionId) => {
+  const safeGroupJid = String(groupJid || '').trim();
+  const safeSessionId = normalizeSessionId(sessionId);
+  if (!safeGroupJid || !safeSessionId) return '';
+  return `${safeSessionId}:${safeGroupJid}`;
+};
+
+/**
+ * Remove do cache todas as entradas de ownership da sessão informada.
+ * @param {string | null | undefined} sessionId
+ * @returns {void}
+ */
+const clearGroupOwnerWriteCacheForSession = (sessionId) => {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const prefix = `${safeSessionId}:`;
+  const keys = groupOwnerWriteStateCache.keys();
+  for (const key of keys) {
+    if (String(key || '').startsWith(prefix)) {
+      groupOwnerWriteStateCache.del(key);
+    }
+  }
+};
+
+const resolveGroupOwnerWriteState = createGroupOwnerWriteStateResolver({
+  getOwnerImpl: getGroupOwner,
+  tryAcquireImpl: tryAcquireGroupOwner,
+  cacheImpl: groupOwnerWriteStateCache,
+  isGroupJidImpl: isGroupJid,
+  normalizeSessionIdImpl: normalizeSessionId,
+  buildCacheKeyImpl: buildGroupOwnerWriteCacheKey,
+  loggerImpl: logger,
+  defaultAllowClaim: GROUP_OWNER_WRITE_CLAIM_ON_MISS,
+});
 /**
  * Habilita ou desabilita o diário de eventos do Baileys.
  * @type {boolean}
@@ -267,15 +389,83 @@ const normalizeMessageReceiptType = (receiptType) => {
  */
 let activeSocket = null;
 /**
- * Contador de tentativas de conexão.
- * @type {number}
+ * Contexto runtime de cada sessão de WhatsApp.
+ * @typedef {{
+ *   sessionId: string,
+ *   socket: import('@whiskeysockets/baileys').WASocket|null,
+ *   connectPromise: Promise<void>|null,
+ *   reconnectTimeout: ReturnType<typeof delayCancellable>|null,
+ *   reconnectWindowStartedAt: number,
+ *   connectionAttempts: number,
+ *   socketGeneration: number,
+ *   writerLockConnection: import('mysql2/promise').PoolConnection|null,
+ *   ownerHeartbeatInterval: ReturnType<typeof setInterval>|null,
+ *   ownerHeartbeatInFlight: boolean
+ * }} SessionContext
+ */
+/**
+ * Registry em memória de contexto por sessão.
+ * @type {Map<string, SessionContext>}
+ */
+const sessionContexts = new Map();
+
+/**
+ * Cria o contexto de runtime inicial para uma sessão.
+ * @param {string} sessionId
+ * @returns {SessionContext}
+ */
+const createSessionContext = (sessionId) => ({
+  sessionId,
+  socket: null,
+  connectPromise: null,
+  reconnectTimeout: null,
+  reconnectWindowStartedAt: 0,
+  connectionAttempts: 0,
+  socketGeneration: 0,
+  writerLockConnection: null,
+  ownerHeartbeatInterval: null,
+  ownerHeartbeatInFlight: false,
+});
+
+/**
+ * Obtém o contexto de runtime de uma sessão.
+ * @param {string | null | undefined} sessionId
+ * @param {{ createIfMissing?: boolean }} [options]
+ * @returns {SessionContext | null}
  */
-let connectionAttempts = 0;
+const getSessionContext = (sessionId, { createIfMissing = true } = {}) => {
+  const safeSessionId = normalizeSessionId(sessionId);
+  let context = sessionContexts.get(safeSessionId);
+  if (!context && createIfMissing) {
+    context = createSessionContext(safeSessionId);
+    sessionContexts.set(safeSessionId, context);
+  }
+  return context || null;
+};
+
 /**
- * Timestamp do início da janela de reconexão.
- * @type {number}
+ * Resolve qual socket deve ser exposto como "ativo" no runtime legado.
+ * Prioriza a sessão principal quando conectada.
+ * @returns {import('@whiskeysockets/baileys').WASocket | null}
  */
-let reconnectWindowStartedAt = 0;
+const resolvePreferredActiveSocket = () => {
+  const primaryContext = getSessionContext(BAILEYS_PRIMARY_SESSION_ID, { createIfMissing: false });
+  if (isSocketOpen(primaryContext?.socket)) return primaryContext.socket;
+
+  for (const context of sessionContexts.values()) {
+    if (isSocketOpen(context?.socket)) return context.socket;
+  }
+
+  return primaryContext?.socket || null;
+};
+
+/**
+ * Sincroniza a referência legada `activeSocket` com os contextos por sessão.
+ * @returns {void}
+ */
+const syncLegacyActiveSocketReference = () => {
+  activeSocket = resolvePreferredActiveSocket();
+};
 /**
  * Cache para contadores de retentativa de mensagens.
  * @type {NodeCache}
@@ -322,26 +512,6 @@ const MAX_CONNECTION_ATTEMPTS = 5;
  * @type {number}
  */
 const INITIAL_RECONNECT_DELAY = 3000;
-/**
- * Timeout para reconexão.
- * @type {ReturnType<typeof delayCancellable> | null}
- */
-let reconnectTimeout = null;
-/**
- * Promessa de conexão ativa.
- * @type {Promise<void> | null}
- */
-let connectPromise = null;
-/**
- * Geração atual do socket (incrementado a cada nova conexão).
- * @type {number}
- */
-let socketGeneration = 0;
-/**
- * Conexão MySQL dedicada para manter lock de escritor único do Baileys.
- * @type {import('mysql2/promise').PoolConnection | null}
- */
-let baileysWriterLockConnection = null;
 /**
  * Nomes de todos os eventos do Baileys que são monitorados.
  * @type {string[]}
@@ -884,12 +1054,15 @@ const queueContactsLidUpdates = (contacts, source) => {
  * Eventos selecionados são enfileirados para persistência.
  * @param {import('@whiskeysockets/baileys').WASocket} sock - A instância do socket do Baileys.
  * @param {number} generation - A geração atual do socket.
+ * @param {string} sessionId - Sessão associada ao socket.
  * @returns {void}
  */
-const registerBaileysEventJournal = (sock, generation) => {
+const registerBaileysEventJournal = (sock, generation, sessionId) => {
+  const safeSessionId = normalizeSessionId(sessionId);
   if (!BAILEYS_EVENT_JOURNAL_ENABLED) {
     logger.debug('Journal de eventos Baileys desativado por configuração.', {
       action: 'baileys_event_journal_disabled',
+      sessionId: safeSessionId,
     });
     return;
   }
@@ -898,6 +1071,7 @@ const registerBaileysEventJournal = (sock, generation) => {
   if (unknownEvents.length > 0) {
     logger.warn('Alguns eventos configurados para journal não existem na lista conhecida do Baileys.', {
       action: 'baileys_event_journal_unknown_events',
+      sessionId: safeSessionId,
       unknownEvents,
     });
   }
@@ -906,17 +1080,41 @@ const registerBaileysEventJournal = (sock, generation) => {
   if (eventsToPersist.length === 0) {
     logger.warn('Journal de eventos Baileys habilitado sem eventos válidos para persistir.', {
       action: 'baileys_event_journal_empty',
+      sessionId: safeSessionId,
       configuredEvents: BAILEYS_EVENT_JOURNAL_EVENT_LIST,
     });
     return;
   }
 
   for (const eventName of eventsToPersist) {
-    sock.ev.on(eventName, (payload) => {
+    sock.ev.on(eventName, async (payload) => {
       try {
         const summary = summarizeBaileysEventPayload(eventName, payload);
         const refs = extractBaileysEventReferences(payload);
+        if (isGroupJid(refs.chatId || '')) {
+          const ownerWriteCacheKey = buildGroupOwnerWriteCacheKey(refs.chatId, safeSessionId);
+          const expectedAssignmentVersion = normalizeAssignmentVersion(groupOwnerWriteStateCache.get(ownerWriteCacheKey)?.assignmentVersion);
+          const ownerState = await resolveGroupOwnerWriteState(refs.chatId, safeSessionId, {
+            source: `baileys_journal:${eventName}`,
+            expectedAssignmentVersion,
+            enforceFence: true,
+          });
+          if (!ownerState.allowed) {
+            logger.debug('Evento Baileys de grupo ignorado para escrita por não-owner.', {
+              action: 'baileys_event_group_write_skipped_non_owner',
+              sessionId: safeSessionId,
+              groupId: refs.chatId,
+              ownerSessionId: ownerState.ownerSessionId,
+              ownerAssignmentVersion: ownerState.assignmentVersion || null,
+              expectedAssignmentVersion,
+              reason: ownerState.reason,
+              eventName,
+            });
+            return;
+          }
+        }
         queueBaileysEventInsert({
+          session_id: safeSessionId,
           event_name: eventName,
           socket_generation: generation,
           chat_id: refs.chatId,
@@ -928,6 +1126,7 @@ const registerBaileysEventJournal = (sock, generation) => {
       } catch (error) {
         logger.warn('Falha ao enfileirar evento Baileys para journal.', {
           action: 'baileys_event_journal_enqueue_failed',
+          sessionId: safeSessionId,
           eventName,
           error: error?.message,
         });
@@ -937,6 +1136,7 @@ const registerBaileysEventJournal = (sock, generation) => {
 
   logger.info('Journal de eventos Baileys habilitado.', {
     action: 'baileys_event_journal_ready',
+    sessionId: safeSessionId,
     generation,
     eventsCount: eventsToPersist.length,
     events: eventsToPersist,
@@ -978,11 +1178,13 @@ const safeJsonParse = (value, fallback) => {
  * @param {'append' | 'notify' | string} type - Tipo do evento de upsert.
  * @returns {Promise<void>} Conclusão da persistência.
  */
-async function persistIncomingMessages(incomingMessages, type) {
+async function persistIncomingMessages(incomingMessages, type, sessionId = BAILEYS_PRIMARY_SESSION_ID) {
   if (type !== 'append' && type !== 'notify') return;
 
   const entries = [];
   const lidsToPrime = new Set();
+  const groupWriteStateByJid = new Map();
+  const safeSessionId = normalizeSessionId(sessionId);
 
   for (const msg of incomingMessages) {
     if (!msg.message || msg.key.remoteJid === 'status@broadcast') continue;
@@ -1018,7 +1220,36 @@ async function persistIncomingMessages(incomingMessages, type) {
 
     const canonicalSenderId = resolveUserIdCached(senderInfo) || msg.key.participant || msg.key.remoteJid;
 
-    const messageData = buildMessageData(msg, canonicalSenderId);
+    const messageData = {
+      ...buildMessageData(msg, canonicalSenderId, safeSessionId),
+    };
+    if (isGroupJid(messageData.chat_id || '')) {
+      let ownerState = groupWriteStateByJid.get(messageData.chat_id);
+      if (!ownerState) {
+        const ownerWriteCacheKey = buildGroupOwnerWriteCacheKey(messageData.chat_id, safeSessionId);
+        const expectedAssignmentVersion = normalizeAssignmentVersion(groupOwnerWriteStateCache.get(ownerWriteCacheKey)?.assignmentVersion);
+        ownerState = await resolveGroupOwnerWriteState(messageData.chat_id, safeSessionId, {
+          source: 'persist_incoming_messages',
+          expectedAssignmentVersion,
+          enforceFence: true,
+        });
+        groupWriteStateByJid.set(messageData.chat_id, ownerState);
+      }
+      if (!ownerState.allowed) {
+        logger.debug('Persistência de mensagem de grupo ignorada para sessão não-owner.', {
+          action: 'incoming_group_message_persistence_skipped_non_owner',
+          sessionId: safeSessionId,
+          groupId: messageData.chat_id,
+          ownerSessionId: ownerState.ownerSessionId,
+          ownerAssignmentVersion: ownerState.assignmentVersion || null,
+          messageId: messageData.message_id,
+          reason: ownerState.reason,
+        });
+        continue;
+      }
+      messageData.allow_group_write = true;
+    }
+
     queueMessageInsert(messageData);
   }
 }
@@ -1029,17 +1260,36 @@ async function persistIncomingMessages(incomingMessages, type) {
  * @param {import('@whiskeysockets/baileys').WAMessageKey} key - Chave da mensagem.
  * @returns {Promise<import('@whiskeysockets/baileys').proto.IMessage | undefined>} Conteúdo da mensagem armazenada.
  */
-async function getStoredMessage(key) {
+async function getStoredMessage(key, sessionId = BAILEYS_PRIMARY_SESSION_ID) {
   const messageId = key?.id;
   const remoteJid = key?.remoteJid;
   if (!messageId || !remoteJid) return undefined;
 
   try {
-    const results = await findBy('messages', { message_id: messageId, chat_id: remoteJid }, { limit: 1 });
-    const record = results?.[0];
+    const safeSessionId = normalizeSessionId(sessionId);
+    let record = null;
+
+    try {
+      const rows = await executeQuery(
+        `SELECT raw_message
+           FROM ${TABLES.MESSAGES}
+          WHERE session_id = ? AND message_id = ? AND chat_id = ?
+          LIMIT 1`,
+        [safeSessionId, messageId, remoteJid],
+      );
+      record = rows?.[0] || null;
+    } catch (error) {
+      if (String(error?.code || '') !== 'ER_BAD_FIELD_ERROR') {
+        throw error;
+      }
+      const fallbackRows = await findBy('messages', { message_id: messageId, chat_id: remoteJid }, { limit: 1 });
+      record = fallbackRows?.[0] || null;
+    }
+
     const stored = safeJsonParse(record?.raw_message, null);
     if (record?.raw_message && !stored) {
       logger.error('Falha ao interpretar raw_message armazenado.', {
+        sessionId: safeSessionId,
         messageId,
         remoteJid,
       });
@@ -1047,6 +1297,7 @@ async function getStoredMessage(key) {
     return stored?.message ?? undefined;
   } catch (error) {
     logger.error('Erro ao buscar mensagem armazenada no banco:', {
+      sessionId: normalizeSessionId(sessionId),
       error: error.message,
       messageId,
       remoteJid,
@@ -1057,55 +1308,66 @@ async function getStoredMessage(key) {
 
 /**
  * Limpa o timeout de reconexão agendado, se houver.
+ * @param {string} sessionId
  * @returns {void}
  */
-const clearReconnectTimeout = () => {
-  if (!reconnectTimeout) return;
-  reconnectTimeout.cancel();
-  reconnectTimeout = null;
+const clearReconnectTimeout = (sessionId = BAILEYS_PRIMARY_SESSION_ID) => {
+  const context = getSessionContext(sessionId, { createIfMissing: false });
+  if (!context?.reconnectTimeout) return;
+  context.reconnectTimeout.cancel();
+  context.reconnectTimeout = null;
 };
 
 /**
  * Reseta o estado das tentativas de reconexão.
+ * @param {string} sessionId
  * @returns {void}
  */
-const resetReconnectState = () => {
-  connectionAttempts = 0;
-  reconnectWindowStartedAt = 0;
+const resetReconnectState = (sessionId = BAILEYS_PRIMARY_SESSION_ID) => {
+  const context = getSessionContext(sessionId);
+  context.connectionAttempts = 0;
+  context.reconnectWindowStartedAt = 0;
 };
 
 /**
  * Calcula o número da próxima tentativa de reconexão.
  * Reseta a contagem de tentativas se a janela de reconexão expirou.
+ * @param {string} sessionId
  * @returns {number} O número da próxima tentativa.
  */
-const getNextReconnectAttempt = () => {
+const getNextReconnectAttempt = (sessionId = BAILEYS_PRIMARY_SESSION_ID) => {
+  const context = getSessionContext(sessionId);
   const now = __timeNowMs();
-  if (!reconnectWindowStartedAt || now - reconnectWindowStartedAt >= BAILEYS_RECONNECT_ATTEMPT_RESET_MS) {
-    reconnectWindowStartedAt = now;
-    connectionAttempts = 0;
+  if (!context.reconnectWindowStartedAt || now - context.reconnectWindowStartedAt >= BAILEYS_RECONNECT_ATTEMPT_RESET_MS) {
+    context.reconnectWindowStartedAt = now;
+    context.connectionAttempts = 0;
   }
-  connectionAttempts += 1;
-  return connectionAttempts;
+  context.connectionAttempts += 1;
+  return context.connectionAttempts;
 };
 
 /**
  * Agenda uma reconexão com o WhatsApp após um determinado atraso.
  * Evita agendar múltiplas reconexões.
+ * @param {string} sessionId
  * @param {number} delay - O atraso em milissegundos antes de tentar a reconexão.
  * @returns {void}
  */
-const scheduleReconnect = (delay) => {
-  if (reconnectTimeout) return;
+const scheduleReconnect = (sessionId, delay) => {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const context = getSessionContext(safeSessionId);
+  if (context.reconnectTimeout) return;
+
   const pendingReconnect = delayCancellable(Math.max(0, Number(delay) || 0));
-  reconnectTimeout = pendingReconnect;
+  context.reconnectTimeout = pendingReconnect;
   pendingReconnect.delay
     .then(() => {
-      if (reconnectTimeout !== pendingReconnect) return;
-      reconnectTimeout = null;
-      connectToWhatsApp().catch((error) => {
+      if (context.reconnectTimeout !== pendingReconnect) return;
+      context.reconnectTimeout = null;
+      connectToWhatsApp(safeSessionId).catch((error) => {
         logger.error('Falha ao executar reconexão agendada.', {
           action: 'reconnect_schedule_failure',
+          sessionId: safeSessionId,
           errorMessage: error?.message,
           stack: error?.stack,
           timestamp: __timeNowIso(),
@@ -1113,8 +1375,8 @@ const scheduleReconnect = (delay) => {
       });
     })
     .catch((error) => {
-      if (reconnectTimeout === pendingReconnect) {
-        reconnectTimeout = null;
+      if (context.reconnectTimeout === pendingReconnect) {
+        context.reconnectTimeout = null;
       }
       if (
         String(error?.message || '')
@@ -1125,37 +1387,146 @@ const scheduleReconnect = (delay) => {
       }
       logger.warn('Falha ao aguardar atraso da reconexão agendada.', {
         action: 'reconnect_schedule_delay_error',
+        sessionId: safeSessionId,
         errorMessage: error?.message,
       });
     });
 };
 
+/**
+ * Interrompe o heartbeat de ownership por sessão.
+ * @param {string} sessionId
+ * @param {string} reason
+ * @returns {void}
+ */
+const stopGroupOwnerHeartbeat = (sessionId, reason = 'unknown') => {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const context = getSessionContext(safeSessionId, { createIfMissing: false });
+  if (!context) return;
+
+  if (context.ownerHeartbeatInterval) {
+    clearInterval(context.ownerHeartbeatInterval);
+    context.ownerHeartbeatInterval = null;
+  }
+  context.ownerHeartbeatInFlight = false;
+  clearGroupOwnerWriteCacheForSession(safeSessionId);
+
+  logger.debug('Heartbeat de ownership por grupo interrompido.', {
+    action: 'group_owner_heartbeat_stopped',
+    sessionId: safeSessionId,
+    reason,
+  });
+};
+
+/**
+ * Inicia heartbeat de ownership por sessão para renovar lease dos grupos de que a sessão é owner.
+ * @param {string} sessionId
+ * @param {number} generation
+ * @returns {void}
+ */
+const startGroupOwnerHeartbeat = (sessionId, generation) => {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const context = getSessionContext(safeSessionId);
+
+  stopGroupOwnerHeartbeat(safeSessionId, 'restart');
+
+  const runTick = async () => {
+    const latestContext = getSessionContext(safeSessionId, { createIfMissing: false });
+    if (!latestContext) return;
+    if (latestContext.ownerHeartbeatInFlight) return;
+    if (latestContext.socketGeneration !== generation) return;
+    if (!isSocketOpen(latestContext.socket)) return;
+
+    latestContext.ownerHeartbeatInFlight = true;
+    try {
+      const socket = latestContext.socket;
+      const botJid = normalizeJid(socket?.user?.id || socket?.authState?.creds?.me?.id || socket?.authState?.creds?.me?.lid) || undefined;
+      const sessionWeight = Math.max(1, Number(MULTI_SESSION_RUNTIME_CONFIG?.sessionWeights?.[safeSessionId] || 1));
+      const heartbeatOutcome = await heartbeatGroupOwnerSession({
+        sessionId: safeSessionId,
+        leaseMs: GROUP_OWNER_LEASE_MS,
+        reason: 'owner_lease_heartbeat',
+        botJid,
+        metadata: {
+          source: 'socket_controller',
+          socketGeneration: generation,
+        },
+        capacityWeight: sessionWeight,
+        currentScore: 0,
+      });
+
+      logger.debug('Heartbeat de ownership executado.', {
+        action: 'group_owner_heartbeat_tick',
+        sessionId: safeSessionId,
+        generation,
+        renewedAssignments: heartbeatOutcome?.renewedAssignments || 0,
+        heartbeatMs: GROUP_OWNER_HEARTBEAT_MS,
+        leaseMs: GROUP_OWNER_LEASE_MS,
+      });
+    } catch (error) {
+      logger.warn('Falha no heartbeat de ownership da sessão.', {
+        action: 'group_owner_heartbeat_failed',
+        sessionId: safeSessionId,
+        generation,
+        error: error?.message,
+      });
+    } finally {
+      const current = getSessionContext(safeSessionId, { createIfMissing: false });
+      if (current) {
+        current.ownerHeartbeatInFlight = false;
+      }
+    }
+  };
+
+  context.ownerHeartbeatInterval = setInterval(() => {
+    void runTick();
+  }, GROUP_OWNER_HEARTBEAT_MS);
+  if (typeof context.ownerHeartbeatInterval.unref === 'function') {
+    context.ownerHeartbeatInterval.unref();
+  }
+
+  logger.info('Heartbeat de ownership por grupo iniciado.', {
+    action: 'group_owner_heartbeat_started',
+    sessionId: safeSessionId,
+    generation,
+    heartbeatMs: GROUP_OWNER_HEARTBEAT_MS,
+    leaseMs: GROUP_OWNER_LEASE_MS,
+  });
+
+  void runTick();
+};
+
 /**
  * Libera lock de escritor único do Baileys, se estiver ativo.
+ * @param {string} sessionId
  * @param {string} reason
  * @returns {Promise<void>}
  */
-const releaseBaileysWriterLock = async (reason = 'unknown') => {
-  const connection = baileysWriterLockConnection;
+const releaseBaileysWriterLock = async (sessionId, reason = 'unknown') => {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const context = getSessionContext(safeSessionId, { createIfMissing: false });
+  const connection = context?.writerLockConnection;
   if (!connection) return;
-
-  baileysWriterLockConnection = null;
+  const lockName = getWriterLockNameBySession(safeSessionId);
+  context.writerLockConnection = null;
 
   try {
-    const rows = await executeQuery('SELECT RELEASE_LOCK(?) AS released', [BAILEYS_SINGLE_WRITER_LOCK_NAME], connection);
+    const rows = await executeQuery('SELECT RELEASE_LOCK(?) AS released', [lockName], connection);
     const released = Number(rows?.[0]?.released) === 1;
     logger.info('Lock de escritor do Baileys liberado.', {
       action: 'baileys_writer_lock_released',
+      sessionId: safeSessionId,
       reason,
       released,
-      lockName: BAILEYS_SINGLE_WRITER_LOCK_NAME,
+      lockName,
       timestamp: __timeNowIso(),
     });
   } catch (error) {
     logger.warn('Falha ao liberar lock de escritor do Baileys.', {
       action: 'baileys_writer_lock_release_error',
+      sessionId: safeSessionId,
       reason,
-      lockName: BAILEYS_SINGLE_WRITER_LOCK_NAME,
+      lockName,
       errorMessage: error?.message,
       timestamp: __timeNowIso(),
     });
@@ -1173,27 +1544,33 @@ const releaseBaileysWriterLock = async (reason = 'unknown') => {
 
 /**
  * Garante lock de escritor único para a sessão do Baileys.
+ * @param {string} sessionId
  * @returns {Promise<boolean>}
  */
-const ensureBaileysWriterLock = async () => {
+const ensureBaileysWriterLock = async (sessionId) => {
   if (!BAILEYS_SINGLE_WRITER_LOCK_ENABLED) {
     return true;
   }
 
-  if (baileysWriterLockConnection) {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const context = getSessionContext(safeSessionId);
+  const lockName = getWriterLockNameBySession(safeSessionId);
+
+  if (context.writerLockConnection) {
     return true;
   }
 
   const connection = await pool.getConnection();
 
   try {
-    const rows = await executeQuery('SELECT GET_LOCK(?, ?) AS lock_status', [BAILEYS_SINGLE_WRITER_LOCK_NAME, BAILEYS_SINGLE_WRITER_LOCK_TIMEOUT_SECONDS], connection);
+    const rows = await executeQuery('SELECT GET_LOCK(?, ?) AS lock_status', [lockName, BAILEYS_SINGLE_WRITER_LOCK_TIMEOUT_SECONDS], connection);
     const lockStatus = Number(rows?.[0]?.lock_status);
     if (lockStatus !== 1) {
       connection.release();
       logger.warn('Nao foi possivel adquirir lock de escritor do Baileys nesta tentativa.', {
         action: 'baileys_writer_lock_busy',
-        lockName: BAILEYS_SINGLE_WRITER_LOCK_NAME,
+        sessionId: safeSessionId,
+        lockName,
         timeoutSeconds: BAILEYS_SINGLE_WRITER_LOCK_TIMEOUT_SECONDS,
         status: Number.isFinite(lockStatus) ? lockStatus : null,
         retryAfterMs: BAILEYS_SINGLE_WRITER_LOCK_RETRY_DELAY_MS,
@@ -1202,10 +1579,11 @@ const ensureBaileysWriterLock = async () => {
       return false;
     }
 
-    baileysWriterLockConnection = connection;
+    context.writerLockConnection = connection;
     logger.info('Lock de escritor do Baileys adquirido com sucesso.', {
       action: 'baileys_writer_lock_acquired',
-      lockName: BAILEYS_SINGLE_WRITER_LOCK_NAME,
+      sessionId: safeSessionId,
+      lockName,
       timeoutSeconds: BAILEYS_SINGLE_WRITER_LOCK_TIMEOUT_SECONDS,
       timestamp: __timeNowIso(),
     });
@@ -1220,16 +1598,30 @@ const ensureBaileysWriterLock = async () => {
   }
 };
 
+/**
+ * Libera todos os locks de escritor mantidos pelo processo atual.
+ * @param {string} [reason='unknown']
+ * @returns {Promise<void>}
+ */
+const releaseAllBaileysWriterLocks = async (reason = 'unknown') => {
+  const targets = Array.from(sessionContexts.keys());
+  if (!targets.length) {
+    await releaseBaileysWriterLock(BAILEYS_PRIMARY_SESSION_ID, reason).catch(() => {});
+    return;
+  }
+  await Promise.allSettled(targets.map((sessionId) => releaseBaileysWriterLock(sessionId, reason)));
+};
+
 process.once('beforeExit', () => {
-  releaseBaileysWriterLock('before_exit').catch(() => {});
+  releaseAllBaileysWriterLocks('before_exit').catch(() => {});
 });
 
 process.once('SIGINT', () => {
-  releaseBaileysWriterLock('sigint').catch(() => {});
+  releaseAllBaileysWriterLocks('sigint').catch(() => {});
 });
 
 process.once('SIGTERM', () => {
-  releaseBaileysWriterLock('sigterm').catch(() => {});
+  releaseAllBaileysWriterLocks('sigterm').catch(() => {});
 });
 
 /**
@@ -1313,34 +1705,40 @@ const syncGroupsOnConnectionOpen = async (sock) => {
  * Configura autenticação, cria o socket e registra handlers de eventos.
  * Gerencia a lógica de reconexão e a distribuição de eventos.
  * @async
+ * @param {string} [sessionId=BAILEYS_PRIMARY_SESSION_ID] - Sessão alvo da conexão.
  * @returns {Promise<void>} Conclusão da inicialização e do registro de handlers.
  * @throws {Error} Lança erro se a conexão inicial falhar.
  */
-export async function connectToWhatsApp() {
-  if (connectPromise) {
-    return connectPromise;
+export async function connectToWhatsApp(sessionId = BAILEYS_PRIMARY_SESSION_ID) {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const context = getSessionContext(safeSessionId);
+
+  if (context.connectPromise) {
+    return context.connectPromise;
   }
 
-  if (isSocketOpen(activeSocket)) {
+  if (isSocketOpen(context.socket)) {
     return;
   }
 
   logger.info('Iniciando conexão com o WhatsApp...', {
     action: 'connect_init',
+    sessionId: safeSessionId,
     timestamp: __timeNowIso(),
   });
-  connectPromise = (async () => {
-    clearReconnectTimeout();
-    const isWriterReady = await ensureBaileysWriterLock();
+
+  const currentConnectPromise = (async () => {
+    clearReconnectTimeout(safeSessionId);
+    const isWriterReady = await ensureBaileysWriterLock(safeSessionId);
     if (!isWriterReady) {
-      scheduleReconnect(BAILEYS_SINGLE_WRITER_LOCK_RETRY_DELAY_MS);
+      scheduleReconnect(safeSessionId, BAILEYS_SINGLE_WRITER_LOCK_RETRY_DELAY_MS);
       return;
     }
 
-    const generation = ++socketGeneration;
+    const generation = ++context.socketGeneration;
     const legacyAuthPath = path.join(__dirname, 'auth');
     const { state, saveCreds } = await useDbAuthState({
-      sessionId: BAILEYS_AUTH_SESSION_ID,
+      sessionId: safeSessionId,
       bootstrapFromDir: legacyAuthPath,
       bootstrapFromFiles: BAILEYS_AUTH_BOOTSTRAP_FROM_FILES,
     });
@@ -1348,7 +1746,8 @@ export async function connectToWhatsApp() {
     const version = await resolveBaileysVersion();
 
     logger.debug('Dados de autenticação carregados com sucesso.', {
-      authSessionId: BAILEYS_AUTH_SESSION_ID,
+      sessionId: safeSessionId,
+      authSessionId: safeSessionId,
       bootstrappedFromFiles: BAILEYS_AUTH_BOOTSTRAP_FROM_FILES,
       version,
       generation,
@@ -1366,7 +1765,7 @@ export async function connectToWhatsApp() {
       msgRetryCounterCache,
       maxMsgRetryCount: 5,
       retryRequestDelayMs: 250,
-      getMessage: getStoredMessage,
+      getMessage: (key) => getStoredMessage(key, safeSessionId),
       userDevicesCache,
       mediaCache,
       cachedGroupMetadata: resolveCachedGroupMetadata,
@@ -1377,16 +1776,22 @@ export async function connectToWhatsApp() {
     };
 
     const sock = makeWASocket(socketConfig);
+    sock.__omnizapSessionId = safeSessionId;
 
-    activeSocket = sock;
-    storeActiveSocket(sock);
+    context.socket = sock;
+    storeActiveSocket(sock, safeSessionId);
+    syncLegacyActiveSocketReference();
 
-    const isCurrentSocket = () => activeSocket === sock && generation === socketGeneration;
+    const isCurrentSocket = () => {
+      const latest = getSessionContext(safeSessionId, { createIfMissing: false });
+      return Boolean(latest && latest.socket === sock && latest.socketGeneration === generation);
+    };
 
     sock.ev.on('creds.update', async () => {
       if (!isCurrentSocket()) return;
       logger.debug('Atualizando credenciais de autenticação...', {
         action: 'creds_update',
+        sessionId: safeSessionId,
         timestamp: __timeNowIso(),
       });
       await saveCreds();
@@ -1394,12 +1799,13 @@ export async function connectToWhatsApp() {
 
     sock.ev.on('connection.update', (update) => {
       if (!isCurrentSocket()) return;
-      handleConnectionUpdate(update, sock);
+      handleConnectionUpdate(update, sock, safeSessionId, generation);
       if (update.connection === 'open') {
         syncNewsBroadcastService();
       }
       logger.debug('Estado da conexão atualizado.', {
         action: 'connection_update',
+        sessionId: safeSessionId,
         status: update.connection,
         lastDisconnect: update.lastDisconnect?.error?.message || null,
         isNewLogin: update.isNewLogin || false,
@@ -1415,17 +1821,19 @@ export async function connectToWhatsApp() {
       try {
         logger.debug('Novo(s) evento(s) em messages.upsert', {
           action: 'messages_upsert',
+          sessionId: safeSessionId,
           type: update.type,
           messagesCount: update.messages.length,
           remoteJid: update.messages[0]?.key.remoteJid || null,
         });
-        const persistPromise = persistIncomingMessages(update.messages, update.type).catch((error) => {
+        const persistPromise = persistIncomingMessages(update.messages, update.type, safeSessionId).catch((error) => {
           logger.error('Erro ao persistir mensagens no banco de dados:', {
+            sessionId: safeSessionId,
             error: error.message,
           });
           recordError('messages_upsert');
         });
-        const handlePromise = handleMessages(update, sock).catch((error) => {
+        const handlePromise = handleMessages(update, sock, { sessionId: safeSessionId }).catch((error) => {
           recordError('messages_upsert');
           throw error;
         });
@@ -1442,6 +1850,7 @@ export async function connectToWhatsApp() {
         });
       } catch (error) {
         logger.error('Erro no evento messages.upsert:', {
+          sessionId: safeSessionId,
           error: error.message,
           stack: error.stack,
           action: 'messages_upsert_error',
@@ -1476,6 +1885,7 @@ export async function connectToWhatsApp() {
       for (const chatId of deletions) {
         remove('chats', chatId).catch((error) => {
           logger.error('Erro ao remover chat do banco:', {
+            sessionId: safeSessionId,
             error: error.message,
             chatId,
           });
@@ -1493,6 +1903,7 @@ export async function connectToWhatsApp() {
           invalidateCachedGroupMetadata(group.id);
         } catch (error) {
           logger.error('Erro no upsert do grupo:', {
+            sessionId: safeSessionId,
             error: error.message,
             groupId: group.id,
           });
@@ -1519,6 +1930,7 @@ export async function connectToWhatsApp() {
         queueLidUpdate(lid, pnJid, 'lid-mapping');
       } catch (error) {
         logger.warn('Falha ao processar lid-mapping.update para lid_map.', {
+          sessionId: safeSessionId,
           error: error.message,
         });
       }
@@ -1529,11 +1941,13 @@ export async function connectToWhatsApp() {
       try {
         logger.debug('Atualização de mensagens recebida.', {
           action: 'messages_update',
+          sessionId: safeSessionId,
           updatesCount: update.length,
         });
         handleMessageUpdate(update, sock);
       } catch (error) {
         logger.error('Erro no evento messages.update:', {
+          sessionId: safeSessionId,
           error: error.message,
           stack: error.stack,
           action: 'messages_update_error',
@@ -1550,6 +1964,7 @@ export async function connectToWhatsApp() {
         const firstError = erroredUpdates[0]?.error;
         logger.warn('Falha reportada em atualização de mídia.', {
           action: 'messages_media_update_error',
+          sessionId: safeSessionId,
           updatesCount: updates.length,
           errorCount: erroredUpdates.length,
           firstMessageId: erroredUpdates[0]?.key?.id || null,
@@ -1561,6 +1976,7 @@ export async function connectToWhatsApp() {
 
       logger.debug('Atualização de mídia de mensagem recebida.', {
         action: 'messages_media_update',
+        sessionId: safeSessionId,
         updatesCount: updates.length,
       });
     });
@@ -1582,6 +1998,7 @@ export async function connectToWhatsApp() {
 
       logger.debug('Atualização de recibos de mensagem recebida.', {
         action: 'message_receipt_update',
+        sessionId: safeSessionId,
         updatesCount: updates.length,
         receiptTypes: Array.from(receiptTypes),
         invalidReceiptTypeCount,
@@ -1621,6 +2038,7 @@ export async function connectToWhatsApp() {
         }
       } catch (error) {
         logger.error('Erro no evento messages.reaction:', {
+          sessionId: safeSessionId,
           error: error.message,
           stack: error.stack,
           action: 'messages_reaction_error',
@@ -1633,12 +2051,14 @@ export async function connectToWhatsApp() {
       try {
         logger.debug('Grupo(s) atualizado(s).', {
           action: 'groups_update',
+          sessionId: safeSessionId,
           groupCount: updates.length,
           groupIds: updates.map((u) => u.id),
         });
         handleGroupUpdate(updates);
       } catch (err) {
         logger.error('Erro no evento groups.update:', {
+          sessionId: safeSessionId,
           error: err.message,
           stack: err.stack,
           action: 'groups_update_error',
@@ -1651,6 +2071,7 @@ export async function connectToWhatsApp() {
       try {
         logger.debug('Participantes do grupo atualizados.', {
           action: 'group_participants_update',
+          sessionId: safeSessionId,
           groupId: update.id,
           actionType: update.action,
           participants: update.participants,
@@ -1659,6 +2080,7 @@ export async function connectToWhatsApp() {
         handleGroupParticipantsEvent(sock, update.id, update.participants, update.action);
       } catch (err) {
         logger.error('Erro no evento group-participants.update:', {
+          sessionId: safeSessionId,
           error: err.message,
           stack: err.stack,
           action: 'group_participants_update_error',
@@ -1671,6 +2093,7 @@ export async function connectToWhatsApp() {
       try {
         logger.debug('Solicitação de entrada no grupo recebida.', {
           action: 'group_join_request',
+          sessionId: safeSessionId,
           groupId: update?.id,
           participant: update?.participant,
           method: update?.method,
@@ -1679,6 +2102,7 @@ export async function connectToWhatsApp() {
         handleGroupJoinRequest(sock, update);
       } catch (err) {
         logger.error('Erro no evento group.join-request:', {
+          sessionId: safeSessionId,
           error: err.message,
           stack: err.stack,
           action: 'group_join_request_error',
@@ -1704,6 +2128,7 @@ export async function connectToWhatsApp() {
           await sock.rejectCall(call.id, call.from);
           logger.info('Chamada recebida rejeitada automaticamente.', {
             action: 'call_auto_reject',
+            sessionId: safeSessionId,
             callId: call.id,
             from: call.from,
             isGroup: call.isGroup || false,
@@ -1713,6 +2138,7 @@ export async function connectToWhatsApp() {
         } catch (error) {
           logger.warn('Falha ao rejeitar chamada automaticamente.', {
             action: 'call_auto_reject_failed',
+            sessionId: safeSessionId,
             callId: call?.id || null,
             from: call?.from || null,
             error: error?.message,
@@ -1722,19 +2148,43 @@ export async function connectToWhatsApp() {
     });
 
     registerBaileysEventLoggers(sock);
-    registerBaileysEventJournal(sock, generation);
+    registerBaileysEventJournal(sock, generation, safeSessionId);
 
     logger.info('Conexão com o WhatsApp estabelecida com sucesso.', {
       action: 'connect_success',
+      sessionId: safeSessionId,
       generation,
       timestamp: __timeNowIso(),
     });
   })();
 
+  context.connectPromise = currentConnectPromise;
+
   try {
-    await connectPromise;
+    await currentConnectPromise;
   } finally {
-    connectPromise = null;
+    if (context.connectPromise === currentConnectPromise) {
+      context.connectPromise = null;
+    }
+  }
+}
+
+/**
+ * Conecta todas as sessões configuradas no runtime.
+ * @returns {Promise<void>}
+ */
+export async function connectAllWhatsAppSessions() {
+  const results = await Promise.allSettled(BAILEYS_SESSION_IDS.map((sessionId) => connectToWhatsApp(sessionId)));
+  const failures = results.map((result, index) => ({ result, sessionId: BAILEYS_SESSION_IDS[index] })).filter(({ result }) => result.status === 'rejected');
+
+  if (failures.length > 0) {
+    const error = new Error(`Falha ao conectar ${failures.length}/${BAILEYS_SESSION_IDS.length} sessões do WhatsApp.`);
+    // @ts-ignore enrich error object for logs
+    error.failures = failures.map(({ sessionId, result }) => ({
+      sessionId,
+      message: result.reason?.message || String(result.reason || ''),
+    }));
+    throw error;
   }
 }
 
@@ -1744,15 +2194,23 @@ export async function connectToWhatsApp() {
  * @async
  * @param {import('@whiskeysockets/baileys').ConnectionState} update - Objeto contendo o estado atual da conexão.
  * @param {import('@whiskeysockets/baileys').WASocket} sock - Instância do socket do WhatsApp que disparou a atualização.
+ * @param {string} sessionId - Sessão do socket.
+ * @param {number} generation - Geração do socket.
  * @returns {Promise<void>} Uma promessa que resolve quando o processamento do estado da conexão é concluído.
  */
-async function handleConnectionUpdate(update, sock) {
-  if (sock !== activeSocket) return;
+async function handleConnectionUpdate(update, sock, sessionId, generation) {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const context = getSessionContext(safeSessionId, { createIfMissing: false });
+  if (!context) return;
+  if (context.socket !== sock) return;
+  if (context.socketGeneration !== generation) return;
+
   const { connection, lastDisconnect, qr } = update;
 
   if (qr) {
     logger.info('📱 QR Code gerado! Escaneie com seu WhatsApp.', {
       action: 'qr_code_generated',
+      sessionId: safeSessionId,
       timestamp: __timeNowIso(),
     });
     qrcode.generate(qr, { small: true });
@@ -1763,13 +2221,32 @@ async function handleConnectionUpdate(update, sock) {
     const errorMessage = lastDisconnect?.error?.message || 'Sem mensagem de erro';
 
     const shouldReconnect = lastDisconnect?.error instanceof Boom && disconnectCode !== DisconnectReason.loggedOut;
+    stopGroupOwnerHeartbeat(safeSessionId, shouldReconnect ? 'connection_close_reconnect' : 'connection_close_final');
+    void sessionRegistryService
+      .markSessionDisconnected(safeSessionId, {
+        status: shouldReconnect ? 'reconnecting' : 'offline',
+        metadata: {
+          reasonCode: disconnectCode,
+          errorMessage,
+          shouldReconnect,
+        },
+      })
+      .catch((error) => {
+        logger.warn('Falha ao registrar sessao offline no registry.', {
+          action: 'session_registry_mark_disconnected_failed',
+          sessionId: safeSessionId,
+          reasonCode: disconnectCode,
+          error: error?.message,
+        });
+      });
 
     if (shouldReconnect) {
-      const attempt = getNextReconnectAttempt();
+      const attempt = getNextReconnectAttempt(safeSessionId);
       if (attempt <= MAX_CONNECTION_ATTEMPTS) {
         const reconnectDelay = INITIAL_RECONNECT_DELAY * Math.pow(2, attempt - 1);
         logger.warn(`⚠️ Conexão perdida. Tentando reconectar...`, {
           action: 'reconnect_attempt',
+          sessionId: safeSessionId,
           attempt,
           maxAttempts: MAX_CONNECTION_ATTEMPTS,
           delay: reconnectDelay,
@@ -1777,12 +2254,14 @@ async function handleConnectionUpdate(update, sock) {
           errorMessage,
           timestamp: __timeNowIso(),
         });
-        activeSocket = null;
-        storeActiveSocket(null);
-        scheduleReconnect(reconnectDelay);
+        context.socket = null;
+        storeActiveSocket(null, safeSessionId);
+        syncLegacyActiveSocketReference();
+        scheduleReconnect(safeSessionId, reconnectDelay);
       } else {
         logger.error('❌ Limite de tentativas atingido; aguardando janela para novo retry.', {
           action: 'reconnect_backoff_window',
+          sessionId: safeSessionId,
           totalAttempts: attempt,
           maxAttempts: MAX_CONNECTION_ATTEMPTS,
           retryAfterMs: BAILEYS_RECONNECT_ATTEMPT_RESET_MS,
@@ -1790,38 +2269,60 @@ async function handleConnectionUpdate(update, sock) {
           errorMessage,
           timestamp: __timeNowIso(),
         });
-        activeSocket = null;
-        storeActiveSocket(null);
-        connectionAttempts = 0;
-        reconnectWindowStartedAt = __timeNowMs();
-        scheduleReconnect(BAILEYS_RECONNECT_ATTEMPT_RESET_MS);
+        context.socket = null;
+        storeActiveSocket(null, safeSessionId);
+        syncLegacyActiveSocketReference();
+        context.connectionAttempts = 0;
+        context.reconnectWindowStartedAt = __timeNowMs();
+        scheduleReconnect(safeSessionId, BAILEYS_RECONNECT_ATTEMPT_RESET_MS);
       }
     } else {
       logger.error('❌ Conexão fechada definitivamente.', {
         action: 'connection_closed',
+        sessionId: safeSessionId,
         reasonCode: disconnectCode,
         errorMessage,
         timestamp: __timeNowIso(),
       });
-      activeSocket = null;
-      storeActiveSocket(null);
-      await releaseBaileysWriterLock('connection_closed_no_reconnect');
+      context.socket = null;
+      storeActiveSocket(null, safeSessionId);
+      syncLegacyActiveSocketReference();
+      await releaseBaileysWriterLock(safeSessionId, 'connection_closed_no_reconnect');
     }
   }
 
   if (connection === 'open') {
     logger.info('✅ Conectado com sucesso ao WhatsApp!', {
       action: 'connection_open',
+      sessionId: safeSessionId,
       timestamp: __timeNowIso(),
     });
 
-    resetReconnectState();
-    clearReconnectTimeout();
+    resetReconnectState(safeSessionId);
+    clearReconnectTimeout(safeSessionId);
+    startGroupOwnerHeartbeat(safeSessionId, generation);
+    void sessionRegistryService
+      .markSessionConnected(safeSessionId, {
+        botJid: normalizeJid(sock?.user?.id || sock?.authState?.creds?.me?.id || sock?.authState?.creds?.me?.lid) || undefined,
+        metadata: {
+          source: 'connection_open',
+          socketGeneration: generation,
+        },
+        capacityWeight: Math.max(1, Number(MULTI_SESSION_RUNTIME_CONFIG?.sessionWeights?.[safeSessionId] || 1)),
+      })
+      .catch((error) => {
+        logger.warn('Falha ao registrar sessao online no registry.', {
+          action: 'session_registry_mark_connected_failed',
+          sessionId: safeSessionId,
+          error: error?.message,
+        });
+      });
 
     if (process.send) {
       process.send('ready');
       logger.info('🟢 Sinal de "ready" enviado ao PM2.', {
         action: 'pm2_ready_signal',
+        sessionId: safeSessionId,
         timestamp: __timeNowIso(),
       });
     }
@@ -1831,6 +2332,7 @@ async function handleConnectionUpdate(update, sock) {
     } catch (error) {
       logger.error('❌ Erro ao carregar metadados de grupos na conexão.', {
         action: 'groups_load_error',
+        sessionId: safeSessionId,
         errorMessage: error.message,
         stack: error.stack,
         timeoutMs: GROUP_SYNC_TIMEOUT_MS,
@@ -1953,6 +2455,7 @@ async function handleGroupUpdate(updates) {
  * @returns {import('@whiskeysockets/baileys').WASocket | null} O objeto socket do Baileys ativo ou `null` se não houver conexão ativa.
  */
 export function getActiveSocket() {
+  syncLegacyActiveSocketReference();
   logger.debug('🔍 Recuperando instância do socket ativo.', {
     action: 'get_active_socket',
     socketExists: !!activeSocket,
@@ -1961,6 +2464,17 @@ export function getActiveSocket() {
   return activeSocket;
 }
 
+/**
+ * Retorna o socket de uma sessão específica.
+ * @param {string} sessionId
+ * @returns {import('@whiskeysockets/baileys').WASocket | null}
+ */
+export function getSocketBySession(sessionId = BAILEYS_PRIMARY_SESSION_ID) {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const context = getSessionContext(safeSessionId, { createIfMissing: false });
+  return context?.socket || null;
+}
+
 /**
  * Executa um método centralizado no socket ativo, tratando erros e mapeando-os para respostas HTTP.
  * @async
@@ -1970,6 +2484,7 @@ export function getActiveSocket() {
  * @throws {Boom} Retorna um erro HTTP 503 se o socket não estiver disponível, ou 501 se o método não existir.
  */
 async function runControllerSocketMethod(methodName, ...args) {
+  const socket = getActiveSocket();
   try {
     return await runActiveSocketMethod(methodName, ...args);
   } catch (error) {
@@ -1977,8 +2492,8 @@ async function runControllerSocketMethod(methodName, ...args) {
     if (message.includes('Socket do WhatsApp indisponível')) {
       logger.warn('Socket ativo indisponível para operação.', {
         action: methodName,
-        socketExists: !!activeSocket,
-        socketOpen: isSocketOpen(activeSocket),
+        socketExists: !!socket,
+        socketOpen: isSocketOpen(socket),
         timestamp: __timeNowIso(),
       });
       throw new Boom('Socket do WhatsApp indisponível no momento.', { statusCode: 503 });
@@ -2207,23 +2722,79 @@ export async function rejectCall(callId, callFrom) {
  * Encerra o socket ativo atual, se existir, para disparar a lógica de reconexão.
  * Se nenhum socket estiver ativo, inicia uma nova conexão.
  * @async
+ * @param {string} [sessionId=BAILEYS_PRIMARY_SESSION_ID]
  * @returns {Promise<void>} Uma promessa que resolve quando o fluxo de reconexão é iniciado ou uma nova conexão é tentada.
  */
-export async function reconnectToWhatsApp() {
-  // eslint-disable-next-line no-undef
-  if (activeSocket && activeSocket.ws?.readyState === WebSocket.OPEN) {
+export async function reconnectToWhatsApp(sessionId = BAILEYS_PRIMARY_SESSION_ID) {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const targetSocket = getSocketBySession(safeSessionId);
+  if (targetSocket && isSocketOpen(targetSocket)) {
     logger.info('♻️ Forçando fechamento do socket para reconectar...', {
       action: 'force_reconnect',
+      sessionId: safeSessionId,
       timestamp: __timeNowIso(),
     });
-    activeSocket.ws.close();
+    targetSocket.ws?.close?.();
   } else {
     logger.warn('⚠️ Nenhum socket ativo detectado. Iniciando nova conexão manualmente.', {
       action: 'reconnect_no_active_socket',
+      sessionId: safeSessionId,
       timestamp: __timeNowIso(),
     });
-    await connectToWhatsApp();
+    await connectToWhatsApp(safeSessionId);
+  }
+}
+
+/**
+ * Encerra todas as sessões ativas no processo.
+ * @param {{ releaseLocks?: boolean }} [options]
+ * @returns {Promise<void>}
+ */
+export async function disconnectAllWhatsAppSessions(options = {}) {
+  const { releaseLocks = true } = options;
+  const targetSessionIds = Array.from(new Set([...BAILEYS_SESSION_IDS, ...sessionContexts.keys()]));
+
+  await Promise.allSettled(
+    targetSessionIds.map(async (sessionId) => {
+      const safeSessionId = normalizeSessionId(sessionId);
+      const context = getSessionContext(safeSessionId, { createIfMissing: false });
+      if (!context) return;
+
+      clearReconnectTimeout(safeSessionId);
+      stopGroupOwnerHeartbeat(safeSessionId, 'disconnect_all_sessions');
+
+      const socket = context.socket;
+      context.socket = null;
+      context.connectPromise = null;
+      storeActiveSocket(null, safeSessionId);
+
+      if (socket && typeof socket.end === 'function') {
+        try {
+          await socket.end();
+        } catch (error) {
+          logger.warn('Falha ao encerrar sessão do WhatsApp.', {
+            action: 'disconnect_session_failed',
+            sessionId: safeSessionId,
+            errorMessage: error?.message,
+          });
+        }
+      }
+
+      void sessionRegistryService
+        .markSessionDisconnected(safeSessionId, {
+          status: 'offline',
+          metadata: {
+            reason: 'disconnect_all_sessions',
+          },
+        })
+        .catch(() => {});
+    }),
+  );
+
+  if (releaseLocks) {
+    await releaseAllBaileysWriterLocks('disconnect_all_sessions');
   }
+  syncLegacyActiveSocketReference();
 }
 
 if (process.argv[1] === __filename) {