fix: address PR review — lint, dedup scope, and cleanup targeting

- Remove unused `autoCleanCorrupted` param from decryptMessageNode (lint fix)
- Scope retry dedup by participant JID in group chats (not group JID)
- Move dedup registration after early-return checks to avoid blocking
  subsequent messages when max retries reached
- Use participant JID for session cleanup in groups (Signal sessions
  are per-participant, not per-group)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/Socket/chats.ts

@@ -50,7 +50,8 @@ import {
 	isMissingKeyError,
 	MAX_SYNC_ATTEMPTS,
 	newLTHashState,
-	processSyncAction
+	processSyncAction,
+	resolveLidToPn
 } from '../Utils'
 import { makeKeyedMutex, makeMutex } from '../Utils/make-mutex'
 import processMessage from '../Utils/process-message'
@@ -757,9 +758,16 @@ export const makeChatsSocket = (config: SocketConfig) => {
 			}, authState?.creds?.me?.id || 'resync-app-state')
 
 			const { onMutation } = newAppStateChunkHandler(isInitialSync)
+			const lidMapping = signalRepository.lidMapping
 			for (const key in globalMutationMap) {
 				const mutation = globalMutationMap[key]
 				if (!mutation) continue
+				// Normalize LID→PN in sync action index[1] (chat/contact ID)
+				if (mutation.index[1] && isAnyLidUser(mutation.index[1])) {
+					const resolved = await resolveLidToPn(mutation.index[1], lidMapping, logger)
+					if (resolved) mutation.index[1] = resolved
+				}
+
 				onMutation(mutation)
 			}
 		}
@@ -912,16 +920,16 @@ export const makeChatsSocket = (config: SocketConfig) => {
 		})
 	}
 
-	const handlePresenceUpdate = ({ tag, attrs, content }: BinaryNode) => {
+	const handlePresenceUpdate = async ({ tag, attrs, content }: BinaryNode) => {
 		let presence: PresenceData | undefined
-		const jid = attrs.from
-		const participant = attrs.participant || attrs.from
-		if (!jid) {
+		const rawJid = attrs.from
+		const rawParticipant = attrs.participant || attrs.from
+		if (!rawJid) {
 			logger.warn({ attrs }, 'handlePresenceUpdate: jid (attrs.from) is missing, skipping')
 			return
 		}
 
-		if (shouldIgnoreJid(jid) && jid !== S_WHATSAPP_NET) {
+		if (shouldIgnoreJid(rawJid) && rawJid !== S_WHATSAPP_NET) {
 			return
 		}
 
@@ -933,7 +941,7 @@ export const makeChatsSocket = (config: SocketConfig) => {
 		} else if (Array.isArray(content)) {
 			const [firstChild] = content
 			if (!firstChild) {
-				logger.warn({ jid }, 'handlePresenceUpdate: firstChild content is empty, skipping')
+				logger.warn({ jid: rawJid }, 'handlePresenceUpdate: firstChild content is empty, skipping')
 				return
 			}
 
@@ -952,12 +960,19 @@ export const makeChatsSocket = (config: SocketConfig) => {
 		}
 
 		if (presence) {
-			if (!participant) {
-				logger.warn({ jid }, 'handlePresenceUpdate: participant is missing, skipping')
+			if (!rawParticipant) {
+				logger.warn({ jid: rawJid }, 'handlePresenceUpdate: participant is missing, skipping')
 				return
 			}
 
-			ev.emit('presence.update', { id: jid, presences: { [participant]: presence } })
+			// Resolve LID→PN so consumers always see phone-number JIDs
+			const lidMapping = signalRepository.lidMapping
+			const [jid, participant] = await Promise.all([
+				resolveLidToPn(rawJid, lidMapping, logger),
+				resolveLidToPn(rawParticipant, lidMapping, logger)
+			])
+
+			ev.emit('presence.update', { id: jid!, presences: { [participant!]: presence } })
 		}
 	}
 
@@ -1031,8 +1046,16 @@ export const makeChatsSocket = (config: SocketConfig) => {
 				undefined,
 				logger
 			)
+			const lidMapping = signalRepository.lidMapping
 			for (const key in mutationMap) {
-				onMutation(mutationMap[key]!)
+				const mutation = mutationMap[key]!
+				// Normalize LID→PN in sync action index[1] (chat/contact ID)
+				if (mutation.index[1] && isAnyLidUser(mutation.index[1])) {
+					const resolved = await resolveLidToPn(mutation.index[1], lidMapping, logger)
+					if (resolved) mutation.index[1] = resolved
+				}
+
+				onMutation(mutation)
 			}
 		}
 	}
@@ -1376,8 +1399,12 @@ export const makeChatsSocket = (config: SocketConfig) => {
 		}
 	})
 
-	ws.on('CB:presence', handlePresenceUpdate)
-	ws.on('CB:chatstate', handlePresenceUpdate)
+	ws.on('CB:presence', (node: BinaryNode) => {
+		handlePresenceUpdate(node).catch(err => onUnexpectedError(err, 'handling presence update'))
+	})
+	ws.on('CB:chatstate', (node: BinaryNode) => {
+		handlePresenceUpdate(node).catch(err => onUnexpectedError(err, 'handling chatstate update'))
+	})
 
 	ws.on('CB:ib,,dirty', async (node: BinaryNode) => {
 		const { attrs } = getBinaryNodeChild(node, 'dirty')!

src/Socket/groups.ts

@@ -1,7 +1,7 @@
 import { proto } from '../../WAProto/index.js'
 import type { GroupMetadata, GroupParticipant, ParticipantAction, SocketConfig, WAMessageKey } from '../Types'
 import { WAMessageAddressingMode, WAMessageStubType } from '../Types'
-import { generateMessageIDV2, unixTimestampSeconds } from '../Utils'
+import { generateMessageIDV2, resolveLidToPn, unixTimestampSeconds } from '../Utils'
 import {
 	type BinaryNode,
 	getBinaryNodeChild,
@@ -17,6 +17,43 @@ import { makeChatsSocket } from './chats'
 export const makeGroupsSocket = (config: SocketConfig) => {
 	const sock = makeChatsSocket(config)
 	const { authState, ev, query, upsertMessage } = sock
+	const { signalRepository } = sock
+	const { logger } = config
+
+	/** Normalize group metadata participant IDs from LID to PN */
+	const normalizeGroupMetadata = async (metadata: GroupMetadata): Promise<GroupMetadata> => {
+		const lidMapping = signalRepository.lidMapping
+
+		// Resolve all participant LIDs in parallel for better performance on large groups
+		await Promise.all(metadata.participants.map(async (p) => {
+			if (isLidUser(p.id)) {
+				if (p.phoneNumber) {
+					p.lid = p.id
+					p.id = p.phoneNumber
+				} else {
+					const resolved = await resolveLidToPn(p.id, lidMapping, logger)
+					if (resolved && resolved !== p.id) {
+						p.lid = p.id
+						p.id = resolved
+					}
+				}
+			}
+		}))
+
+		// Normalize owner/subjectOwner if LID (parallel)
+		const [resolvedOwner, resolvedSubjectOwner] = await Promise.all([
+			metadata.owner && isLidUser(metadata.owner)
+				? (metadata.ownerPn || resolveLidToPn(metadata.owner, lidMapping, logger))
+				: null,
+			metadata.subjectOwner && isLidUser(metadata.subjectOwner)
+				? (metadata.subjectOwnerPn || resolveLidToPn(metadata.subjectOwner, lidMapping, logger))
+				: null
+		])
+		if (resolvedOwner) metadata.owner = resolvedOwner
+		if (resolvedSubjectOwner) metadata.subjectOwner = resolvedSubjectOwner
+
+		return metadata
+	}
 
 	const groupQuery = async (jid: string, type: 'get' | 'set', content: BinaryNode[]) =>
 		query({
@@ -31,7 +68,7 @@ export const makeGroupsSocket = (config: SocketConfig) => {
 
 	const groupMetadata = async (jid: string) => {
 		const result = await groupQuery(jid, 'get', [{ tag: 'query', attrs: { request: 'interactive' } }])
-		return extractGroupMetadata(result)
+		return normalizeGroupMetadata(extractGroupMetadata(result))
 	}
 
 	const groupFetchAllParticipating = async () => {
@@ -58,16 +95,15 @@ export const makeGroupsSocket = (config: SocketConfig) => {
 		if (groupsChild) {
 			const groups = getBinaryNodeChildren(groupsChild, 'group')
 			for (const groupNode of groups) {
-				const meta = extractGroupMetadata({
+				const meta = await normalizeGroupMetadata(extractGroupMetadata({
 					tag: 'result',
 					attrs: {},
 					content: [groupNode]
-				})
+				}))
 				data[meta.id] = meta
 			}
 		}
 
-		// TODO: properly parse LID / PN DATA
 		sock.ev.emit('groups.update', Object.values(data))
 
 		return data
@@ -101,7 +137,7 @@ export const makeGroupsSocket = (config: SocketConfig) => {
 					}))
 				}
 			])
-			return extractGroupMetadata(result)
+			return normalizeGroupMetadata(extractGroupMetadata(result))
 		},
 		groupLeave: async (id: string) => {
 			await groupQuery('@g.us', 'set', [
@@ -277,7 +313,7 @@ export const makeGroupsSocket = (config: SocketConfig) => {
 		),
 		groupGetInviteInfo: async (code: string) => {
 			const results = await groupQuery('@g.us', 'get', [{ tag: 'invite', attrs: { code } }])
-			return extractGroupMetadata(results)
+			return normalizeGroupMetadata(extractGroupMetadata(results))
 		},
 		groupToggleEphemeral: async (jid: string, ephemeralExpiration: number) => {
 			const content: BinaryNode = ephemeralExpiration

src/Types/Call.ts

@@ -1,4 +1,30 @@
-export type WACallUpdateType = 'offer' | 'ringing' | 'timeout' | 'reject' | 'accept' | 'terminate'
+export type WACallUpdateType =
+	| 'offer'
+	| 'ringing'
+	| 'timeout'
+	| 'reject'
+	| 'accept'
+	| 'terminate'
+	| 'preaccept'
+	| 'transport'
+	| 'relaylatency'
+	| 'group_update'
+	| 'reminder'
+	| 'heartbeat'
+	| 'mute_v2'
+	| 'enc_rekey'
+	| 'video'
+	| 'relay'
+
+export type WACallParticipant = {
+	jid?: string
+	/** 'connected' | 'invited' | 'left' etc. */
+	state?: string
+	/** Phone number in s.whatsapp.net format */
+	userPn?: string
+	/** 'admin' for group call link creator */
+	type?: string
+}
 
 export type WACallEvent = {
 	chatId: string
@@ -13,4 +39,20 @@ export type WACallEvent = {
 	latencyMs?: number
 	/** Phone number of the caller (sanitized to fix Brazilian landline bug) */
 	callerPn?: string
+	/** Call link token (forms URL: https://call.whatsapp.com/video/<token>) */
+	linkToken?: string
+	/** JID of who created the call link */
+	linkCreator?: string
+	/** Phone number of link creator */
+	linkCreatorPn?: string
+	/** Media type: 'video' or 'audio' */
+	media?: string
+	/** Max participants for group/link calls */
+	connectedLimit?: number
+	/** Participants in a group/link call */
+	participants?: WACallParticipant[]
+	/** Call duration in ms (from terminate/call_summary) */
+	duration?: number
+	/** Terminate reason (e.g. 'group_call_ended', 'accepted_elsewhere', 'timeout') */
+	terminateReason?: string
 }

src/Utils/decode-wa-message.ts

@@ -276,7 +276,6 @@ export const decryptMessageNode = (
 	meLid: string,
 	repository: SignalRepositoryWithLIDStore,
 	logger: ILogger,
-	autoCleanCorrupted = true
 ) => {
 	const { fullMessage, author, sender } = decodeMessageNode(stanza, meId, meLid)
 	return {
@@ -422,34 +421,19 @@ export const decryptMessageNode = (
 							if (isRetryExhausted) {
 								logger.error(
 									errorContext,
-									`⚠️ Session corrupted and recovery failed after ${err.attempts} attempts. Auto-cleanup will attempt to recover.`
+									`⚠️ Session corrupted after ${err.attempts} attempts. Retry+pkmsg flow will recover.`
 								)
 							} else {
 								// First occurrence - log as warning since auto-recovery will attempt
 								logger.warn(errorContext, '⚠️ Corrupted session detected - attempting auto-recovery')
 							}
 
-							// Automatic cleanup of corrupted session (if enabled)
-							// eslint-disable-next-line max-depth
-							if (autoCleanCorrupted) {
-								// eslint-disable-next-line max-depth
-								try {
-									const deletedCount = await cleanupCorruptedSession(decryptionJid, repository, logger)
-
-									// Mask only user portion of JID for privacy (preserve domain info)
-									const { user, server } = jidDecode(decryptionJid) || {}
-									const maskedUser =
-										user && user.length > 8 ? `${user.substring(0, 4)}****${user.substring(user.length - 4)}` : user
-									const maskedJid = maskedUser && server ? `${maskedUser}@${server}` : decryptionJid
-
-									logger.info(
-										{ jid: decryptionJid, maskedJid, targetedDevices: deletedCount },
-										`🔄 Session Reset | JID: ${maskedJid} | Targeted: ${deletedCount} devices | Will recreate on next message`
-									)
-								} catch (cleanupErr) {
-									logger.error({ decryptionJid, err: cleanupErr }, '❌ Failed to cleanup corrupted session')
-								}
-							}
+							// Session cleanup is deferred to retry exhaustion (safety net).
+							// The Signal Protocol handles recovery naturally via retry+pkmsg:
+							// Bad MAC -> retry receipt -> sender re-sends as pkmsg -> new session.
+							// Deleting sessions here (hot path) causes cascading failures when
+							// multiple messages from the same contact arrive simultaneously.
+							// See: messages-recv.ts sendRetryRequest() for deferred cleanup.
 						} else if (isSessionRecord) {
 							// Session record errors are transient - retry should handle them
 							// eslint-disable-next-line max-depth
@@ -504,10 +488,14 @@ export function isCorruptedSessionError(error: any): boolean {
 }
 
 /**
- * Clean up corrupted session by deleting all device sessions for a JID
- * Signal Protocol will automatically recreate the session on next message
+ * Clean up corrupted session by deleting all device sessions for a JID.
+ * Signal Protocol will automatically recreate the session on next message.
+ *
+ * NOTE: This should NOT be called on every Bad MAC error (hot path).
+ * Instead, let the retry+pkmsg flow handle recovery naturally (like WhatsApp does).
+ * Only call this as a safety net when retries are exhausted.
  */
-async function cleanupCorruptedSession(
+export async function cleanupCorruptedSession(
 	jid: string,
 	repository: SignalRepositoryWithLIDStore,
 	logger: ILogger

src/Utils/generics.ts

@@ -429,6 +429,36 @@ export const getCallStatusFromNode = ({ tag, attrs }: BinaryNode) => {
 		case 'accept':
 			status = 'accept'
 			break
+		case 'preaccept':
+			status = 'preaccept'
+			break
+		case 'transport':
+			status = 'transport'
+			break
+		case 'relaylatency':
+			status = 'relaylatency'
+			break
+		case 'group_update':
+			status = 'group_update'
+			break
+		case 'reminder':
+			status = 'reminder'
+			break
+		case 'heartbeat':
+			status = 'heartbeat'
+			break
+		case 'mute_v2':
+			status = 'mute_v2'
+			break
+		case 'enc_rekey':
+			status = 'enc_rekey'
+			break
+		case 'video':
+			status = 'video'
+			break
+		case 'relay':
+			status = 'relay'
+			break
 		default:
 			status = 'ringing'
 			break

src/Utils/message-retry-manager.ts

@@ -211,15 +211,33 @@ export class MessageRetryManager {
 			}
 		}
 
-		// MAC errors require IMMEDIATE session recreation regardless of history
-		// This handles the case where contact reinstalled WhatsApp (identity key changed)
+		// MAC errors require session recreation, but rate-limited to prevent loops.
+		// When multiple messages fail with Bad MAC simultaneously, only the first
+		// should trigger recreation; subsequent ones within the cooldown window
+		// piggyback on the same new session established by the retry+pkmsg flow.
 		if (errorCode !== undefined && MAC_ERROR_CODES.has(errorCode)) {
-			this.sessionRecreateHistory.set(jid, Date.now())
+			const now = Date.now()
+			const prevTime = this.sessionRecreateHistory.get(jid)
+			const MAC_ERROR_COOLDOWN_MS = 10_000 // 10 seconds
+
+			if (prevTime && now - prevTime < MAC_ERROR_COOLDOWN_MS) {
+				const reasonName = RetryReason[errorCode] || `code_${errorCode}`
+				this.logger.debug(
+					{ jid, errorCode: reasonName, msSinceLast: now - prevTime },
+					'MAC error session recreation skipped — cooldown active'
+				)
+				return {
+					reason: '',
+					recreate: false
+				}
+			}
+
+			this.sessionRecreateHistory.set(jid, now)
 			this.statistics.sessionRecreations++
 			const reasonName = RetryReason[errorCode] || `code_${errorCode}`
 			metrics.signalMacErrors?.inc({ action: 'session_recreation' })
 			metrics.signalSessionRecreations?.inc({ reason: 'mac_error' })
-			this.logger.warn({ jid, errorCode: reasonName }, 'MAC error detected, forcing immediate session recreation')
+			this.logger.warn({ jid, errorCode: reasonName }, 'MAC error detected, recreating session')
 			return {
 				reason: `MAC error (${reasonName}) - contact may have reinstalled WhatsApp`,
 				recreate: true

src/Utils/process-message.ts

@@ -19,10 +19,13 @@ import type {
 	WAMessage,
 	WAMessageKey
 } from '../Types'
+import type { LIDMappingStore } from '../Signal/lid-mapping'
 import { WAMessageStubType } from '../Types'
 import { getContentType, normalizeMessageContent } from '../Utils/messages'
 import {
 	areJidsSameUser,
+	isAnyLidUser,
+	isAnyPnUser,
 	isHostedLidUser,
 	isHostedPnUser,
 	isJidBroadcast,
@@ -125,42 +128,94 @@ export const cleanMessage = (message: WAMessage, meId: string, meLid: string) =>
 	}
 }
 
-export const normalizeMessageJids = async (
-	message: WAMessage,
-	signalRepository: SignalRepositoryWithLIDStore,
+/**
+ * Resolves a LID JID to its PN equivalent using the LID mapping store.
+ * Returns the original JID if it's not a LID or if no mapping is found.
+ * Safe to call with any JID type (group, newsletter, PN, etc.).
+ */
+export const resolveLidToPn = async (
+	jid: string | undefined | null,
+	lidMapping: LIDMappingStore,
 	logger?: ILogger
-): Promise<void> => {
-	const resolveLidToPn = async (jid: string | undefined | null): Promise<string | undefined> => {
+): Promise<string | undefined> => {
 	if (!jid) {
 		return undefined
 	}
 
-		if (isLidUser(jid) || isHostedLidUser(jid)) {
-			const pn = await signalRepository.lidMapping.getPNForLID(jid)
+	if (isAnyLidUser(jid)) {
+		const pn = await lidMapping.getPNForLID(jid)
 		if (pn) {
-				logger?.debug({ lid: jid, pn }, 'Resolved LID to PN for inbound message')
-			} else {
-				logger?.debug({ lid: jid }, 'PN not found for inbound LID, keeping LID')
+			logger?.debug({ lid: jid, pn }, 'Resolved LID to PN')
 		}
 
 		return pn || jid
 	}
 
 	return jid
-	}
+}
 
-	// Execute both lookups in parallel instead of sequentially to reduce latency
+/**
+ * Normalizes a WAMessageKey by resolving LID→PN for remoteJid and participant.
+ */
+export const normalizeKeyLidToPn = async (
+	key: WAMessageKey,
+	lidMapping: LIDMappingStore,
+	logger?: ILogger
+): Promise<void> => {
 	const [resolvedRemoteJid, resolvedParticipant] = await Promise.all([
-		resolveLidToPn(message.key.remoteJid),
-		resolveLidToPn(message.key.participant)
+		resolveLidToPn(key.remoteJid, lidMapping, logger),
+		resolveLidToPn(key.participant, lidMapping, logger)
 	])
-
 	if (resolvedRemoteJid) {
-		message.key.remoteJid = resolvedRemoteJid
+		key.remoteJid = resolvedRemoteJid
 	}
 
 	if (resolvedParticipant) {
-		message.key.participant = resolvedParticipant
+		key.participant = resolvedParticipant
+	}
+}
+
+export const normalizeMessageJids = async (
+	message: WAMessage,
+	signalRepository: SignalRepositoryWithLIDStore,
+	logger?: ILogger
+): Promise<void> => {
+	const lidMapping = signalRepository.lidMapping
+	const key = message.key
+
+	// FAST PATH: Use alt JIDs directly when available (avoids LIDMappingStore race condition).
+	// The stanza always carries both formats (LID + PN) in the attributes.
+	// When addressing_mode=lid, remoteJid is LID and remoteJidAlt is PN.
+	// When addressing_mode=pn, remoteJid is already PN (no conversion needed).
+	if (key.remoteJid && isAnyLidUser(key.remoteJid) && key.remoteJidAlt && isAnyPnUser(key.remoteJidAlt)) {
+		logger?.debug({ lid: key.remoteJid, pn: key.remoteJidAlt }, 'Resolved remoteJid LID→PN via alt (fast path)')
+		key.remoteJid = key.remoteJidAlt
+	}
+
+	if (key.participant && isAnyLidUser(key.participant) && key.participantAlt && isAnyPnUser(key.participantAlt)) {
+		logger?.debug({ lid: key.participant, pn: key.participantAlt }, 'Resolved participant LID→PN via alt (fast path)')
+		key.participant = key.participantAlt
+	}
+
+	// SLOW PATH: Resolve any remaining LIDs via LIDMappingStore lookup
+	await normalizeKeyLidToPn(key, lidMapping, logger)
+
+	// Also normalize participantAlt (the alternative JID format — can be LID when addressing_mode=pn)
+	if (key.participantAlt && isAnyLidUser(key.participantAlt)) {
+		const resolved = await resolveLidToPn(key.participantAlt, lidMapping, logger)
+		if (resolved) {
+			key.participantAlt = resolved
+		}
+	}
+
+	// Normalize nested message keys (reaction, poll) that may contain LID JIDs
+	const content = normalizeMessageContent(message.message)
+	if (content?.reactionMessage?.key) {
+		await normalizeKeyLidToPn(content.reactionMessage.key, lidMapping, logger)
+	}
+
+	if (content?.pollUpdateMessage?.pollCreationMessageKey) {
+		await normalizeKeyLidToPn(content.pollUpdateMessage.pollCreationMessageKey, lidMapping, logger)
 	}
 }
 
@@ -534,6 +589,12 @@ const processMessage = async (
 								'CTWA: Successfully recovered message via placeholder resend'
 							)
 
+							// Normalize LID→PN in PDO-recovered message key before emitting
+							// eslint-disable-next-line max-depth
+							if (webMessageInfo.key && signalRepository) {
+								await normalizeKeyLidToPn(webMessageInfo.key as WAMessageKey, signalRepository.lidMapping, logger)
+							}
+
 							// wait till another upsert event is available, don't want it to be part of the PDO response message
 							// TODO: parse through proper message handling utilities (to add relevant key fields)
 							ev.emit('messages.upsert', {
@@ -674,9 +735,13 @@ const processMessage = async (
 						response: responseMsg
 					}
 
+					// Normalize creationMsgKey JIDs for the emitted event
+					const normalizedCreationKey = { ...creationMsgKey }
+					await normalizeKeyLidToPn(normalizedCreationKey, signalRepository.lidMapping, logger)
+
 					ev.emit('messages.update', [
 						{
-							key: creationMsgKey,
+							key: normalizedCreationKey,
 							update: {
 								eventResponses: [eventResponse]
 							}
@@ -719,7 +784,7 @@ const processMessage = async (
 			})
 		}
 
-		const participantsIncludesMe = () => participants.find(jid => areJidsSameUser(meId, jid.phoneNumber)) // ADD SUPPORT FOR LID
+		const participantsIncludesMe = () => participants.find(p => areJidsSameUser(meId, p.id) || areJidsSameUser(meId, p.phoneNumber))
 
 		switch (message.messageStubType) {
 			case WAMessageStubType.GROUP_PARTICIPANT_CHANGE_NUMBER: