fix(signal): bot-review round 2 — injectE2ESession lock, doc/error fixes

Addresses bot review on commit 4bdcd5769d:

1) [Major — CodeRabbit + Copilot] `injectE2ESession` was the last
   session-mutating path still locking on raw `jid` while writing through
   `storeSession()` (which canonicalizes via `resolveLIDSignalAddress`). Same
   PN/LID lock-vs-storage drift as the original bug — fixed by computing
   `wireAddr` once and locking on it (same pattern as encrypt/decrypt).

2) [Minor — Copilot] `resolveLIDSignalAddress` docstring described the input
   as `userDomain.device` but the actual format from
   `jidToSignalProtocolAddress` is `signalUser.device`, where `signalUser` is
   either the bare user (WhatsApp domain) or `user_domainType` for LID/hosted.
   Updated to match.

3) [Minor — Copilot] `Missing device ID` error fired when the user portion
   (before the `.`) was empty, which was misleading. Split into two specific
   errors and added validation for the empty-device-portion case (e.g.
   trailing `.`). Each now points at the actual missing part.

4) [Doc — CodeRabbit residual race concern] Added a paragraph explaining the
   theoretical race between our `wireAddr` resolution and storage's internal
   re-resolution if `lidMapping` mutates between the two awaits. In production
   this is mitigated by the `migrateSession()` call upstream in
   `messages-recv.ts` running synchronously BEFORE `decryptMessage`, so the
   mapping is populated by the time the lock is acquired. Eliminating the
   residual entirely requires storage to skip re-resolution — bigger refactor
   reserved for a follow-up if the residual ever bites in prod.

5) [Out of scope — Copilot PR-metadata staleness] PR title still says "raw
   JID" from the original commit. Will be retitled on the GitHub side after
   this lands.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

WAProto/WAProto.proto

@@ -1,7 +1,7 @@
 syntax = "proto3";
 package proto;
 
-/// WhatsApp Version: 2.3000.1038024963
+/// WhatsApp Version: 2.3000.1038164556
 
 message ADVDeviceIdentity {
     optional uint32 rawId = 1;

WAProto/fix-imports.js

@@ -18,14 +18,21 @@ try {
     '\tif (typeof value === "number") {\n' +
     '\t\treturn String(value);\n' +
     '\t}\n' +
-    '\tif (!$util.Long) {\n' +
+    '\t// Fast path: convert Long {low, high} directly via native BigInt\n' +
-    '\t\treturn String(value);\n' +
+    '\t// BigInt.toString() is a native C++ operation, much faster than Long\'s pure JS division loops\n' +
+    '\tif (value && typeof value.low === "number" && typeof value.high === "number") {\n' +
+    '\t\t// Normalize high to signed int32 so the sign-bit check works for inputs\n' +
+    '\t\t// where high is stored unsigned (e.g. raw {low, high} JSON).\n' +
+    '\t\tconst high = value.high | 0;\n' +
+    '\t\tconst lo = BigInt(value.low >>> 0);\n' +
+    '\t\tconst hi = BigInt(value.high >>> 0);\n' +
+    '\t\tconst combined = (hi << 32n) | lo;\n' +
+    '\t\tif (!unsigned && high < 0) {\n' +
+    '\t\t\treturn (combined - (1n << 64n)).toString();\n' +
+    '\t\t}\n' +
+    '\t\treturn combined.toString();\n' +
     '\t}\n' +
-    '\tconst normalized = $util.Long.fromValue(value);\n' +
+    '\treturn String(value);\n' +
-    '\tconst prepared = unsigned && normalized && typeof normalized.toUnsigned === "function"\n' +
-    '\t\t? normalized.toUnsigned()\n' +
-    '\t\t: normalized;\n' +
-    '\treturn prepared.toString();\n' +
     '}\n\n'
   const longToNumberHelper =
     'function longToNumber(value, unsigned) {\n' +
@@ -33,19 +40,20 @@ try {
     '\t\treturn value;\n' +
     '\t}\n' +
     '\tif (typeof value === "string") {\n' +
-    '\t\tconst numeric = Number(value);\n' +
-    '\t\treturn numeric;\n' +
-    '\t}\n' +
-    '\tif (!$util.Long) {\n' +
     '\t\treturn Number(value);\n' +
     '\t}\n' +
-    '\tconst normalized = $util.Long.fromValue(value);\n' +
+    '\t// Fast path: convert Long {low, high} directly via native BigInt\n' +
-    '\tconst prepared = unsigned && normalized && typeof normalized.toUnsigned === "function"\n' +
+    '\tif (value && typeof value.low === "number" && typeof value.high === "number") {\n' +
-    '\t\t? normalized.toUnsigned()\n' +
+    '\t\tconst high = value.high | 0;\n' +
-    '\t\t: typeof normalized.toSigned === "function"\n' +
+    '\t\tconst lo = BigInt(value.low >>> 0);\n' +
-    '\t\t\t? normalized.toSigned()\n' +
+    '\t\tconst hi = BigInt(value.high >>> 0);\n' +
-    '\t\t\t: normalized;\n' +
+    '\t\tconst combined = (hi << 32n) | lo;\n' +
-    '\treturn prepared.toNumber();\n' +
+    '\t\tif (!unsigned && high < 0) {\n' +
+    '\t\t\treturn Number(combined - (1n << 64n));\n' +
+    '\t\t}\n' +
+    '\t\treturn Number(combined);\n' +
+    '\t}\n' +
+    '\treturn Number(value);\n' +
     '}\n\n'
 
   if (!content.includes('function longToString(')) {

WAProto/index.js

@@ -12,14 +12,21 @@ function longToString(value, unsigned) {
 	if (typeof value === "number") {
 		return String(value);
 	}
-	if (!$util.Long) {
+	// Fast path: convert Long {low, high} directly via native BigInt
-		return String(value);
+	// BigInt.toString() is a native C++ operation, much faster than Long's pure JS division loops
+	if (value && typeof value.low === "number" && typeof value.high === "number") {
+		// Normalize high to signed int32 so the sign-bit check works for inputs
+		// where high is stored unsigned (e.g. raw {low, high} JSON).
+		const high = value.high | 0;
+		const lo = BigInt(value.low >>> 0);
+		const hi = BigInt(value.high >>> 0);
+		const combined = (hi << 32n) | lo;
+		if (!unsigned && high < 0) {
+			return (combined - (1n << 64n)).toString();
+		}
+		return combined.toString();
 	}
-	const normalized = $util.Long.fromValue(value);
+	return String(value);
-	const prepared = unsigned && normalized && typeof normalized.toUnsigned === "function"
-		? normalized.toUnsigned()
-		: normalized;
-	return prepared.toString();
 }
 
 function longToNumber(value, unsigned) {
@@ -27,19 +34,20 @@ function longToNumber(value, unsigned) {
 		return value;
 	}
 	if (typeof value === "string") {
-		const numeric = Number(value);
-		return numeric;
-	}
-	if (!$util.Long) {
 		return Number(value);
 	}
-	const normalized = $util.Long.fromValue(value);
+	// Fast path: convert Long {low, high} directly via native BigInt
-	const prepared = unsigned && normalized && typeof normalized.toUnsigned === "function"
+	if (value && typeof value.low === "number" && typeof value.high === "number") {
-		? normalized.toUnsigned()
+		const high = value.high | 0;
-		: typeof normalized.toSigned === "function"
+		const lo = BigInt(value.low >>> 0);
-			? normalized.toSigned()
+		const hi = BigInt(value.high >>> 0);
-			: normalized;
+		const combined = (hi << 32n) | lo;
-	return prepared.toNumber();
+		if (!unsigned && high < 0) {
+			return Number(combined - (1n << 64n));
+		}
+		return Number(combined);
+	}
+	return Number(value);
 }
 
 export const proto = $root.proto = (() => {

src/Defaults/baileys-version.json

@@ -1 +1 @@
-{"version":[2,3000,1038147544]}
+{"version":[2,3000,1038189736]}

src/Defaults/index.ts

@@ -142,8 +142,6 @@ export const DEFAULT_CONNECTION_CONFIG: SocketConfig = {
 	getMessage: async () => undefined,
 	cachedGroupMetadata: async () => undefined,
 	makeSignalRepository: makeLibSignalRepository,
-	// Circuit breaker configuration
-	enableCircuitBreaker: true,
 	// Listener limits (memory leak prevention)
 	// WebSocket: 8 core events (open, close, error, message, ping, pong, upgrade, unexpected-response)
 	//          + 10 dynamic listeners (reconnect handlers, custom events)

src/Signal/libsignal.ts

@@ -6,7 +6,6 @@ import type { LIDMapping, SignalAuthState, SignalKeyStoreWithTransaction } from
 import type { BaileysEventEmitter } from '../Types/Events'
 import type { SignalRepositoryWithLIDStore } from '../Types/Signal'
 import { generateSignalPubKey } from '../Utils'
-import { CircuitBreaker } from '../Utils/circuit-breaker.js'
 import type { ILogger } from '../Utils/logger'
 import { metrics } from '../Utils/prometheus-metrics.js'
 import { isAnyLidUser, isAnyPnUser, jidDecode, transferDevice, WAJIDDomains } from '../WABinary'
@@ -67,8 +66,6 @@ export interface IdentitySaveResult {
 export interface LibSignalRepositoryOptions {
 	/** Event emitter for broadcasting identity changes */
 	ev?: BaileysEventEmitter
-	/** Circuit breaker for prekey operations (optional) */
-	preKeyCircuitBreaker?: CircuitBreaker
 }
 
 // ============================================
@@ -256,7 +253,7 @@ export function makeLibSignalRepository(
 	pnToLIDFunc?: (jids: string[]) => Promise<LIDMapping[] | undefined>,
 	options?: LibSignalRepositoryOptions
 ): SignalRepositoryWithLIDStore {
-	const { ev, preKeyCircuitBreaker } = options || {}
+	const { ev } = options || {}
 	const lidMapping = new LIDMappingStore(auth.keys as SignalKeyStoreWithTransaction, logger, pnToLIDFunc)
 
 	// Identity key cache to avoid repeated storage reads
@@ -277,7 +274,7 @@ export function makeLibSignalRepository(
 		cacheMetricsInterval.unref()
 	}
 
-	const storage = signalStorage(auth, lidMapping, identityKeyCache, ev, preKeyCircuitBreaker, logger)
+	const storage = signalStorage(auth, lidMapping, identityKeyCache, ev, logger)
 
 	const parsedKeys = auth.keys as SignalKeyStoreWithTransaction
 	const migratedSessionCache = new LRUCache<string, true>({
@@ -302,25 +299,6 @@ export function makeLibSignalRepository(
 	// Promise instead of each spawning their own DB transactions.
 	const migrationInFlight = new Map<string, Promise<{ migrated: number; skipped: number; total: number }>>()
 
-	// Resolve PN JID to its canonical LID JID for transaction locking.
-	// This prevents PN/LID race conditions where concurrent operations for the
-	// same logical contact acquire different mutex locks because one uses PN
-	// and the other uses LID. (Aligned with WABA behavior — all operations use LID internally.)
-	const resolveCanonicalJid = async(jid: string): Promise<string> => {
-		if (isAnyLidUser(jid)) {
-			return jid
-		}
-
-		if (isAnyPnUser(jid)) {
-			const lid = await lidMapping.getLIDForPN(jid)
-			if (lid) {
-				return lid
-			}
-		}
-
-		return jid
-	}
-
 	const repository: SignalRepositoryWithLIDStore = {
 		decryptGroupMessage({ group, authorJid, msg }) {
 			const senderName = jidToSignalSenderKeyName(group, authorJid)
@@ -363,6 +341,14 @@ export function makeLibSignalRepository(
 		},
 		async decryptMessage({ jid, type, ciphertext }) {
 			const addr = jidToSignalProtocolAddress(jid)
+			// Wire address = the EXACT key that signalStorage's loadSession/storeSession
+			// uses internally (it canonicalizes PN→LID via resolveLIDSignalAddress).
+			// We MUST lock on this same key — locking on the raw `jid` lets two
+			// concurrent ops for the same logical contact (one arriving as PN, one as
+			// LID) acquire DIFFERENT mutex slots and interleave on the same session
+			// record, corrupting the ratchet → perpetual `Bad MAC` on own DSM after
+			// the WhatsApp PN→LID DSM rollout.
+			const wireAddr = await resolveLIDSignalAddress(addr.toString(), lidMapping)
 			const session = new libsignal.SessionCipher(storage, addr)
 
 			async function doDecrypt() {
@@ -385,13 +371,9 @@ export function makeLibSignalRepository(
 									'Identity key changed - contact may have reinstalled WhatsApp, session will be re-established'
 								)
 
-								// Reset prekey circuit breaker since we identified the cause
+								// (No circuit breaker to reset — bounded-retry is stateless,
-								// Reset regardless of state (could be open, half-open, or closed with accumulated failures)
+								// each retry is independent so identity-change recovery
-								// eslint-disable-next-line max-depth
+								// happens automatically on the next operation.)
-								if (preKeyCircuitBreaker) {
-									preKeyCircuitBreaker.reset()
-									logger.debug({ jid }, 'Reset prekey circuit breaker after identity key change detection')
-								}
 							} else if (saveResult.isNew) {
 								logger.debug(
 									{ jid, addr: addrStr, fingerprint: saveResult.currentFingerprint },
@@ -415,24 +397,23 @@ export function makeLibSignalRepository(
 				return result
 			}
 
-			// Use canonical JID (PN→LID resolved) as transaction key to prevent
-			// PN/LID race conditions on the same logical session.
-			const canonicalJid = await resolveCanonicalJid(jid)
 			return parsedKeys.transaction(async () => {
 				return await doDecrypt()
-			}, canonicalJid)
+			}, wireAddr)
 		},
 
 		async encryptMessage({ jid, data }) {
 			const addr = jidToSignalProtocolAddress(jid)
+			// See decryptMessage above for the rationale: lock on the wire address,
+			// not the raw JID, so concurrent PN/LID ops on the same session serialize.
+			const wireAddr = await resolveLIDSignalAddress(addr.toString(), lidMapping)
 			const cipher = new libsignal.SessionCipher(storage, addr)
 
-			const canonicalJid = await resolveCanonicalJid(jid)
 			return parsedKeys.transaction(async () => {
 				const { type: sigType, body } = await cipher.encrypt(data)
 				const type = sigType === 3 ? 'pkmsg' : 'msg'
 				return { type, ciphertext: Buffer.from(body, 'binary') }
-			}, canonicalJid)
+			}, wireAddr)
 		},
 
 		async encryptGroupMessage({ group, meId, data }) {
@@ -460,10 +441,16 @@ export function makeLibSignalRepository(
 
 		async injectE2ESession({ jid, session }) {
 			logger.trace({ jid }, 'injecting E2EE session')
-			const cipher = new libsignal.SessionBuilder(storage, jidToSignalProtocolAddress(jid))
+			const addr = jidToSignalProtocolAddress(jid)
+			// Same wire-address locking as encrypt/decrypt — `SessionBuilder.initOutgoing`
+			// writes via `storeSession` which canonicalizes, so the lock key must be
+			// the wire address for the mutex to actually serialize concurrent ops on
+			// the same logical session.
+			const wireAddr = await resolveLIDSignalAddress(addr.toString(), lidMapping)
+			const cipher = new libsignal.SessionBuilder(storage, addr)
 			return parsedKeys.transaction(async () => {
 				await cipher.initOutgoing(session)
-			}, jid)
+			}, wireAddr)
 		},
 		jidToSignalProtocolAddress(jid) {
 			return jidToSignalProtocolAddress(jid).toString()
@@ -740,6 +727,65 @@ const jidToSignalSenderKeyName = (group: string, user: string): SenderKeyName =>
 	return new SenderKeyName(group, jidToSignalProtocolAddress(user))
 }
 
+/**
+ * Resolve a Signal protocol address (string form `signalUser.device`, where
+ * `signalUser` is `user` for the WhatsApp domain or `user_domainType` for any
+ * other domain — e.g. `12345_1.0` for a LID device 0) to its canonical *wire*
+ * address — the exact key that `loadSession`/`storeSession` uses when
+ * reading/writing `keys.get('session', [...])`.
+ *
+ * This is the SAME key the storage layer uses internally, so callers that need
+ * a transaction lock around session mutations MUST lock on this resolved
+ * address (not the raw JID), otherwise the lock key and storage key drift
+ * apart and concurrent ops on the same session interleave → ratchet
+ * corruption → perpetual `Bad MAC` errors.
+ *
+ * Behavior: if the input already targets a LID domain, returns it unchanged
+ * (cheap fast path — no awaits). Otherwise looks up the PN→LID mapping; if
+ * found, returns the LID-form Signal address. If no mapping exists, returns
+ * the input unchanged.
+ *
+ * Residual race window: the lock and the storage's internal re-resolution
+ * each call this function once. If a PN→LID mapping is added between those
+ * two calls (microsecond window), the lock could be on the PN address while
+ * storage canonicalizes to LID. In production this is mitigated upstream:
+ * `messages-recv.ts` runs `migrateSession()` synchronously BEFORE
+ * `decryptMessage()` is called, so the mapping is already populated by the
+ * time we lock. Eliminating the residual race entirely would require storage
+ * to NOT re-resolve, which is a bigger refactor (other call sites depend on
+ * the current contract).
+ *
+ * Top-level (not inside `signalStorage`) so `makeLibSignalRepository` can
+ * compute the same wire address for transaction locking.
+ */
+const resolveLIDSignalAddress = async (id: string, lidMapping: LIDMappingStore): Promise<string> => {
+	if (id.includes('.')) {
+		const [deviceId, device] = id.split('.')
+		if (!deviceId) {
+			throw new Error(`Malformed signal address (empty user portion before '.'): "${id}"`)
+		}
+
+		if (device === undefined || device === '') {
+			throw new Error(`Malformed signal address (empty device portion after '.'): "${id}"`)
+		}
+
+		const [user, domainType_] = deviceId.split('_')
+		const domainType = parseInt(domainType_ || '0')
+
+		if (domainType === WAJIDDomains.LID || domainType === WAJIDDomains.HOSTED_LID) return id
+
+		const pnJid = `${user!}${device !== '0' ? `:${device}` : ''}@${domainType === WAJIDDomains.HOSTED ? 'hosted' : 's.whatsapp.net'}`
+
+		const lidForPN = await lidMapping.getLIDForPN(pnJid)
+		if (lidForPN) {
+			const lidAddr = jidToSignalProtocolAddress(lidForPN)
+			return lidAddr.toString()
+		}
+	}
+
+	return id
+}
+
 /**
  * Extended SignalStorage with identity key management
  * This type adds identity key operations to the standard Signal storage
@@ -769,33 +815,11 @@ function signalStorage(
 	lidMapping: LIDMappingStore,
 	identityKeyCache: LRUCache<string, Uint8Array>,
 	ev?: BaileysEventEmitter,
-	preKeyCircuitBreaker?: CircuitBreaker,
 	logger?: ILogger
 ): ExtendedSignalStorage {
-	// Shared function to resolve PN signal address to LID if mapping exists
+	// Bind the top-level `resolveLIDSignalAddress` to this instance's lidMapping
-	const resolveLIDSignalAddress = async (id: string): Promise<string> => {
+	// so call sites below stay readable.
-		if (id.includes('.')) {
+	const resolveAddr = (id: string) => resolveLIDSignalAddress(id, lidMapping)
-			const [deviceId, device] = id.split('.')
-			if (!deviceId) {
-				throw new Error('Missing device ID')
-			}
-
-			const [user, domainType_] = deviceId.split('_')
-			const domainType = parseInt(domainType_ || '0')
-
-			if (domainType === WAJIDDomains.LID || domainType === WAJIDDomains.HOSTED_LID) return id
-
-			const pnJid = `${user!}${device !== '0' ? `:${device}` : ''}@${domainType === WAJIDDomains.HOSTED ? 'hosted' : 's.whatsapp.net'}`
-
-			const lidForPN = await lidMapping.getLIDForPN(pnJid)
-			if (lidForPN) {
-				const lidAddr = jidToSignalProtocolAddress(lidForPN)
-				return lidAddr.toString()
-			}
-		}
-
-		return id
-	}
 
 	// Delayed PreKey deletion: grace period to handle race conditions
 	// where two pkmsg with the same preKeyId arrive nearly simultaneously.
@@ -807,7 +831,7 @@ function signalStorage(
 	return {
 		loadSession: async (id: string) => {
 			try {
-				const wireJid = await resolveLIDSignalAddress(id)
+				const wireJid = await resolveAddr(id)
 				const { [wireJid]: sess } = await keys.get('session', [wireJid])
 
 				if (sess) {
@@ -820,7 +844,7 @@ function signalStorage(
 			return null
 		},
 		storeSession: async (id: string, session: libsignal.SessionRecord) => {
-			const wireJid = await resolveLIDSignalAddress(id)
+			const wireJid = await resolveAddr(id)
 			await keys.set({ session: { [wireJid]: session.serialize() } })
 		},
 		isTrustedIdentity: () => {
@@ -897,7 +921,7 @@ function signalStorage(
 			const timer = metrics.signalIdentityKeyOperations?.startTimer({ operation: 'load' })
 
 			try {
-				const wireJid = await resolveLIDSignalAddress(id)
+				const wireJid = await resolveAddr(id)
 
 				// Check cache first
 				const cached = identityKeyCache.get(wireJid)
@@ -931,7 +955,7 @@ function signalStorage(
 			const timer = metrics.signalIdentityKeyOperations?.startTimer({ operation: 'save' })
 
 			try {
-				const wireJid = await resolveLIDSignalAddress(id)
+				const wireJid = await resolveAddr(id)
 				const currentFingerprint = generateKeyFingerprint(identityKey)
 
 				// Load existing key (from cache or storage)

src/Socket/chats.ts

@@ -54,7 +54,7 @@ import {
 	resolveLidToPn
 } from '../Utils'
 import { makeKeyedMutex, makeMutex } from '../Utils/make-mutex'
-import processMessage from '../Utils/process-message'
+import processMessage, { getChatId } from '../Utils/process-message'
 import { buildTcTokenFromJid } from '../Utils/tc-token-utils'
 import {
 	type BinaryNode,
@@ -98,6 +98,24 @@ export const makeChatsSocket = (config: SocketConfig) => {
 
 	let privacySettings: { [_: string]: string } | undefined
 
+	/**
+	 * Server-assigned AB props that gate tctoken-related protocol behavior.
+	 * Defaults match WA Web (safe — avoids spurious error 463 if the prop never
+	 * arrives). Populated from `fetchProps()` on connection.
+	 *
+	 * - `privacyTokenOn1to1` (AB prop 10518 / `privacy_token_sending_on_all_1_on_1_messages`):
+	 *    include tctoken in 1:1 messages.
+	 * - `profilePicPrivacyToken` (AB prop 9666 / `profile_scraping_privacy_token_in_photo_iq`):
+	 *    include tctoken in profile picture IQs.
+	 * - `lidTrustedTokenIssueToLid` (AB prop 14303 / `lid_trusted_token_issue_to_lid`):
+	 *    issue privacy tokens to the contact's LID instead of the PN.
+	 */
+	const serverProps = {
+		privacyTokenOn1to1: true,
+		profilePicPrivacyToken: true,
+		lidTrustedTokenIssueToLid: false
+	}
+
 	let syncState: SyncState = SyncState.Connecting
 
 	/** this mutex ensures that messages from the same chat are processed in order, while allowing parallel processing of messages from different chats */
@@ -112,6 +130,18 @@ export const makeChatsSocket = (config: SocketConfig) => {
 	/** this mutex ensures that notifications from the same chat are processed in order, while allowing parallel processing across chats */
 	const notificationMutex = makeKeyedMutex()
 
+	/**
+	 * Per-chat mutex dedicated to post-upsert work (history app-state sync +
+	 * processMessage side effects). Kept separate from `messageMutex` because
+	 * the inbound caller already holds `messageMutex(chatId)` while running
+	 * decrypt + upsertMessage; sharing the same mutex would let a concurrently-
+	 * arrived message N+1 enqueue *between* msg N's outer callback and msg N's
+	 * post-upsert task, so msg N+1's processMessage could run before msg N's
+	 * (breaking per-chat ordering of side effects). With a separate mutex,
+	 * post-upsert tasks enqueue strictly in upsertMessage call order.
+	 */
+	const postUpsertMutex = makeKeyedMutex()
+
 	// Timeout for AwaitingInitialSync state
 	let awaitingSyncTimeout: NodeJS.Timeout | undefined
 
@@ -791,7 +821,10 @@ export const makeChatsSocket = (config: SocketConfig) => {
 			me && (normalizedJid === jidNormalizedUser(me.id) || (me.lid && normalizedJid === jidNormalizedUser(me.lid)))
 		let content: BinaryNode[] | undefined = baseContent
 
-		if (isUserJid && !isSelf) {
+		// Gate inclusion on AB prop 9666 (profile_scraping_privacy_token_in_photo_iq).
+		// WA Web defaults to true; if the server flips it off, we mirror that to
+		// avoid divergence with the spec-compliant client.
+		if (serverProps.profilePicPrivacyToken && isUserJid && !isSelf) {
 			content = await buildTcTokenFromJid({
 				authState,
 				jid: normalizedJid,
@@ -1093,7 +1126,25 @@ export const makeChatsSocket = (config: SocketConfig) => {
 			props = reduceBinaryNodeToDictionary(propsNode, 'prop')
 		}
 
-		logger.debug('fetched props')
+		// Extract protocol-relevant AB props (defaults match WA Web; see serverProps doc).
+		// We accept both numeric IDs and human-readable names so the parser is resilient
+		// to upstream renaming and to future-versioned WA Web servers.
+		const privacyTokenProp = props['10518'] ?? props['privacy_token_sending_on_all_1_on_1_messages']
+		if (privacyTokenProp !== undefined) {
+			serverProps.privacyTokenOn1to1 = privacyTokenProp === 'true' || privacyTokenProp === '1'
+		}
+
+		const profilePicProp = props['9666'] ?? props['profile_scraping_privacy_token_in_photo_iq']
+		if (profilePicProp !== undefined) {
+			serverProps.profilePicPrivacyToken = profilePicProp === 'true' || profilePicProp === '1'
+		}
+
+		const lidIssueProp = props['14303'] ?? props['lid_trusted_token_issue_to_lid']
+		if (lidIssueProp !== undefined) {
+			serverProps.lidTrustedTokenIssueToLid = lidIssueProp === 'true' || lidIssueProp === '1'
+		}
+
+		logger.debug({ serverProps }, 'fetched props')
 
 		return props
 	}
@@ -1360,7 +1411,19 @@ export const makeChatsSocket = (config: SocketConfig) => {
 				blockedCollections.clear()
 
 				logger.info('Doing app state sync')
-				await resyncAppState(ALL_WA_PATCH_NAMES, true)
+				try {
+					await resyncAppState(ALL_WA_PATCH_NAMES, true)
+				} catch (err) {
+					// Failure recovery: without this, syncState would stay at Syncing
+					// and ev.flush() would never run, leaving the event buffer pinned
+					// until the buffer's own safety timeout expires. Force the state
+					// machine forward so live inbound events can flow even if the
+					// app-state resync failed (collections are already cleared, so
+					// blocked patches will be retried on the next creds.update tick).
+					syncState = SyncState.Online
+					ev.flush()
+					throw err
+				}
 
 				// Sync is complete, go online and flush everything
 				syncState = SyncState.Online
@@ -1372,29 +1435,131 @@ export const makeChatsSocket = (config: SocketConfig) => {
 			}
 		}
 
-		await Promise.all([
+		// Post-upsert work: history app-state sync + processMessage side effects.
-			(async () => {
+		// Awaiting here keeps `messages.upsert` pinned in the event buffer
-				if (shouldProcessHistoryMsg) {
+		// (createBufferedFunction only schedules flush after work() resolves), so
-					await doAppStateSync()
+		// the hot path detaches this work to release the emit on the next debounce
-				}
+		// tick.
-			})(),
+		//
-			processMessage(msg, {
+		// Use Promise.allSettled so the combined promise only settles after BOTH
-				signalRepository,
+		// tasks finish. With a plain Promise.all, an early rejection from one task
-				shouldProcessHistoryMsg,
+		// would release the keyed mutex while the other task is still mutating
-				placeholderResendCache,
+		// chat state — letting the next message of the same chat overtake it and
-				ev,
+		// break per-chat ordering.
-				creds: authState.creds,
+		//
-				keyStore: authState.keys,
+		// Returns the per-task settle status so the keyShare branch can know
-				logger,
+		// whether processMessage actually persisted the new app-state-sync key
-				options: config.options,
+		// before triggering doAppStateSync (otherwise the sync would hit
-				getMessage
+		// isMissingKeyError and park collections in blockedCollections).
-			})
+		const postUpsertTasks = async (): Promise<{ processMessageOk: boolean }> => {
-		])
+			const [historyResult, processResult] = await Promise.allSettled([
+				shouldProcessHistoryMsg ? doAppStateSync() : Promise.resolve(),
+				processMessage(msg, {
+					signalRepository,
+					shouldProcessHistoryMsg,
+					placeholderResendCache,
+					ev,
+					creds: authState.creds,
+					keyStore: authState.keys,
+					logger,
+					options: config.options,
+					getMessage
+				})
+			])
 
-		// If the app state key arrives and we are waiting to sync, trigger the sync now.
+			if (historyResult.status === 'rejected') {
-		if (msg.message?.protocolMessage?.appStateSyncKeyShare && syncState === SyncState.Syncing) {
+				logger?.warn(
-			logger.info('App state sync key arrived, triggering app state sync')
+					{ err: historyResult.reason, messageId: msg.key?.id, remoteJid: msg.key?.remoteJid },
-			await doAppStateSync()
+					'history doAppStateSync failed'
+				)
+			}
+
+			if (processResult.status === 'rejected') {
+				logger?.warn(
+					{ err: processResult.reason, messageId: msg.key?.id, remoteJid: msg.key?.remoteJid },
+					'processMessage failed'
+				)
+			}
+
+			return { processMessageOk: processResult.status === 'fulfilled' }
+		}
+
+		// Use getChatId + jidNormalizedUser so the mutex key matches the chat-id
+		// scheme processMessage uses for chat updates (broadcasts target the
+		// participant). When getChatId/jidNormalizedUser yields nothing usable
+		// (missing or malformed JID), prefer a message-derived fallback over a
+		// single global 'unknown' bucket — that bucket would head-of-line block
+		// every malformed message behind a shared queue. msg.key.id is unique
+		// per message so unrelated malformed inputs no longer serialize together;
+		// for valid messages we still hit the normalized chat-id path, so the
+		// per-chat ordering guarantee is unchanged where it matters.
+		const rawChatId = getChatId(msg.key)
+		const normalizedChatId = rawChatId ? jidNormalizedUser(rawChatId) : ''
+		const postUpsertChatId = normalizedChatId || msg.key?.id || 'unknown'
+
+		// Wrap in `postUpsertMutex(chatId)` (a SEPARATE keyed mutex from the outer
+		// `messageMutex` held by the inbound caller) so per-chat ordering of
+		// processMessage side effects (chat.unreadCount, LID/PN mapping,
+		// messages.update, history downloads) is preserved across messages of the
+		// same chat.
+		//
+		// Why a separate mutex: if we re-used messageMutex, a concurrently-arrived
+		// message N+1 could enqueue on the outer mutex BEFORE msg N's post-upsert
+		// task gets enqueued (because N's outer callback yields on `await decrypt()`
+		// before reaching the inner enqueue site). The queue would then be
+		// [OuterN+1, InnerN, ...], so InnerN+1 would beat InnerN to processMessage.
+		// With its own mutex, post-upsert tasks enqueue strictly in upsertMessage
+		// call order (which IS message arrival order because the outer
+		// messageMutex serializes the upserts per-chat).
+		const postUpsertWork = postUpsertMutex.mutex(postUpsertChatId, postUpsertTasks)
+
+		const isKeyShareDuringSync =
+			!!msg.message?.protocolMessage?.appStateSyncKeyShare && syncState === SyncState.Syncing
+
+		if (isKeyShareDuringSync) {
+			// appStateSyncKeyShare path: processMessage persists the new app-state-sync
+			// key in its APP_STATE_SYNC_KEY_SHARE handler (via keyStore.transaction).
+			// The follow-up doAppStateSync() needs that key to decrypt patches, so
+			// we MUST wait for processMessage to actually succeed before kicking off
+			// the sync — otherwise it would hit isMissingKeyError and park
+			// collections in blockedCollections, regressing the very issue this
+			// branch was added to fix.
+			//
+			// No deadlock with the inbound caller's messageMutex because
+			// postUpsertMutex is a different mutex instance.
+			logger.info('App state sync key arrived, awaiting persistence before triggering sync')
+			const { processMessageOk } = await postUpsertWork
+
+			if (!processMessageOk) {
+				logger?.warn(
+					{ messageId: msg.key?.id, remoteJid: msg.key?.remoteJid },
+					'processMessage failed during key-share — skipping doAppStateSync to avoid isMissingKeyError'
+				)
+			} else {
+				try {
+					await doAppStateSync()
+				} catch (err) {
+					logger?.warn(
+						{ err, messageId: msg.key?.id, remoteJid: msg.key?.remoteJid },
+						'doAppStateSync failed after key-share persistence'
+					)
+				}
+			}
+		} else {
+			// `postUpsertWork` is not expected to reject — `Promise.allSettled`
+			// inside `postUpsertTasks` never rejects, and per-task failures are
+			// already logged inline. The defensive catch routes any truly
+			// unexpected rejection (e.g. `postUpsertMutex` internal corruption,
+			// future synchronous throws inside processMessage) through
+			// `onUnexpectedError` instead of letting it surface as an
+			// UnhandledPromiseRejection — which on Node ≥15 can terminate the
+			// long-running socket process.
+			postUpsertWork.catch(err =>
+				onUnexpectedError(
+					err,
+					`processing post-upsert work for message ${msg.key?.id || 'unknown'} on ${msg.key?.remoteJid || 'unknown chat'}`
+				)
+			)
 		}
 	})
 
@@ -1611,6 +1776,7 @@ export const makeChatsSocket = (config: SocketConfig) => {
 
 	return {
 		...sock,
+		serverProps,
 		createCallLink,
 		getBotListV2,
 		messageMutex,

src/Socket/messages-recv.ts

@@ -73,7 +73,14 @@ import {
 	recordMessageReceived,
 	recordMessageRetry
 } from '../Utils/prometheus-metrics.js'
-import { isTcTokenExpired, resolveTcTokenJid, storeTcTokensFromIqResult } from '../Utils/tc-token-utils'
+import {
+	buildMergedTcTokenIndexWrite,
+	isTcTokenExpired,
+	resolveIssuanceJid,
+	resolveTcTokenJid,
+	storeTcTokensFromIqResult,
+	TC_TOKEN_INDEX_KEY
+} from '../Utils/tc-token-utils'
 import {
 	areJidsSameUser,
 	type BinaryNode,
@@ -164,7 +171,12 @@ export const makeMessagesRecvSocket = (config: SocketConfig) => {
 	let sendActiveReceipts = false
 
 	// ======= tctoken index tracking for cross-session pruning =======
-	const TC_TOKEN_INDEX_KEY = '__index'
+	// TC_TOKEN_INDEX_KEY is imported from tc-token-utils so the value stays in sync
+	// with messages-send/process-message writes (avoids string drift on rename).
+	// Race note: this prune-driven index write may interleave with
+	// buildMergedTcTokenIndexWrite calls from issuance/history-sync paths. Worst
+	// case: a JID resurrected by a stale read gets pruned again on the next 24h
+	// sweep — no data loss, just one extra cycle.
 	const TC_TOKEN_PRUNE_TS_KEY = '__prune_ts'
 	const tcTokenKnownJids = new Set<string>()
 	const tcTokenRetriedMsgIds = new Set<string>()
@@ -198,16 +210,25 @@ export const makeMessagesRecvSocket = (config: SocketConfig) => {
 		}
 	})()
 
-	/** Debounced save of the tctoken JID index (5s) */
+	/**
+	 * Debounced save of the tctoken JID index (5s).
+	 *
+	 * Merges with the persisted index instead of overwriting — other layers
+	 * (messages-send fire-and-forget issuance, process-message history sync) may
+	 * write JIDs to the index via `buildMergedTcTokenIndexWrite` without updating
+	 * `tcTokenKnownJids`. Without the merge those JIDs would be silently dropped
+	 * the next time this debounced save fires.
+	 */
 	const scheduleTcTokenIndexSave = () => {
 		if (tcTokenIndexSaveTimer) clearTimeout(tcTokenIndexSaveTimer)
 		tcTokenIndexSaveTimer = setTimeout(async () => {
 			try {
-				const arr = Array.from(tcTokenKnownJids)
+				const merged = await buildMergedTcTokenIndexWrite(authState.keys, tcTokenKnownJids)
 				await authState.keys.set({
 					tctoken: {
+						...merged,
 						[TC_TOKEN_INDEX_KEY]: {
-							token: Buffer.from(JSON.stringify(arr), 'utf8'),
+							...merged[TC_TOKEN_INDEX_KEY],
 							timestamp: unixTimestampSeconds().toString()
 						}
 					}
@@ -1434,6 +1455,58 @@ export const makeMessagesRecvSocket = (config: SocketConfig) => {
 		}, authState?.creds?.me?.id || 'sendRetryRequest')
 	}
 
+	/**
+	 * Fire-and-forget tctoken re-issuance after a peer's device identity changed.
+	 * Mirrors WAWebSendTcTokenWhenDeviceIdentityChange — runs in PARALLEL with the
+	 * session refresh (not after it).
+	 *
+	 * Why parallel and not sequential:
+	 *  - WA Web invokes this BEFORE assertSessions to maximise the chance the contact
+	 *    has a fresh tctoken by the time the next outbound send executes.
+	 *  - Running after assertSessions (the fork's previous behaviour) races with the
+	 *    next send and risks error 463 when the contact reinstalls and the user replies
+	 *    immediately afterwards.
+	 *
+	 * Gated on `entry.senderTimestamp` (we previously issued a token to this peer in the
+	 * current bucket window). Preserves the existing senderTimestamp instead of issuing
+	 * a fresh one — keeps WA Web's bucket coalescing semantics: same token, same window.
+	 */
+	const reissueTcTokenAfterIdentityChange = (from: string): void => {
+		void (async () => {
+			const normalizedJid = jidNormalizedUser(from)
+			const tcJid = await resolveTcTokenJid(normalizedJid, getLIDForPN)
+			const tcTokenData = await authState.keys.get('tctoken', [tcJid])
+			const senderTs = tcTokenData?.[tcJid]?.senderTimestamp
+
+			if (senderTs === null || senderTs === undefined || isTcTokenExpired(senderTs)) {
+				return
+			}
+
+			logTcToken('reissue', { jid: normalizedJid, reason: 'identity_changed', senderTimestamp: senderTs })
+			const getPNForLID = signalRepository.lidMapping.getPNForLID.bind(signalRepository.lidMapping)
+			const issueJid = await resolveIssuanceJid(
+				normalizedJid,
+				sock.serverProps.lidTrustedTokenIssueToLid,
+				getLIDForPN,
+				getPNForLID
+			)
+			const result = await getPrivacyTokens([issueJid], senderTs)
+			await storeTcTokensFromIqResult({
+				result,
+				fallbackJid: tcJid,
+				keys: authState.keys,
+				getLIDForPN,
+				onNewJidStored: storedJid => {
+					tcTokenKnownJids.add(storedJid)
+					scheduleTcTokenIndexSave()
+				}
+			})
+			logTcToken('reissue_ok', { jid: normalizedJid, reason: 'identity_changed' })
+		})().catch(err => {
+			logTcToken('reissue_fail', { jid: from, error: err?.message })
+		})
+	}
+
 	const handleEncryptNotification = async (node: BinaryNode) => {
 		const from = node.attrs.from
 		if (from === S_WHATSAPP_NET) {
@@ -1453,57 +1526,12 @@ export const makeMessagesRecvSocket = (config: SocketConfig) => {
 				validateSession: signalRepository.validateSession,
 				assertSessions,
 				debounceCache: identityAssertDebounce,
-				logger
+				logger,
+				// Fire reissue in parallel with the session refresh, NOT after it.
+				// See reissueTcTokenAfterIdentityChange doc for the rationale.
+				onBeforeSessionRefresh: reissueTcTokenAfterIdentityChange
 			})
 
-			// When a session is refreshed (identity change), re-issue tctoken fire-and-forget
-			// WABA Android: reissue stores senderTimestamp + realIssueTimestamp after IQ success
-			if (result.action === 'session_refreshed') {
-				const normalizedJid = jidNormalizedUser(from)
-				resolveTcTokenJid(normalizedJid, getLIDForPN)
-					.then(async tcJid => {
-						const tcData = await authState.keys.get('tctoken', [tcJid])
-						const entry = tcData[tcJid]
-						if (entry?.token?.length && !isTcTokenExpired(entry.timestamp)) {
-							const senderTs = unixTimestampSeconds()
-							logTcToken('reissue', { jid: normalizedJid, reason: 'session_refreshed' })
-							getPrivacyTokens([normalizedJid], senderTs)
-								.then(async (iqResult) => {
-									await storeTcTokensFromIqResult({
-										result: iqResult,
-										fallbackJid: normalizedJid,
-										keys: authState.keys,
-										getLIDForPN,
-										onNewJidStored: (storedJid) => {
-											tcTokenKnownJids.add(storedJid)
-											scheduleTcTokenIndexSave()
-										}
-									})
-									// Persist senderTimestamp + realIssueTimestamp after IQ success
-									const currentData = await authState.keys.get('tctoken', [tcJid])
-									const currentEntry = currentData[tcJid]
-									await authState.keys.set({
-										tctoken: {
-											[tcJid]: {
-												...currentEntry,
-												token: currentEntry?.token ?? Buffer.alloc(0),
-												senderTimestamp: senderTs,
-												realIssueTimestamp: 0
-											}
-										}
-									})
-									logTcToken('reissue_ok', { jid: normalizedJid, reason: 'session_refreshed' })
-								})
-								.catch(err => {
-									logTcToken('reissue_fail', { jid: normalizedJid, error: err?.message })
-								})
-						}
-					})
-					.catch(() => {
-						/* ignore resolution errors */
-					})
-			}
-
 			if (result.action === 'no_identity_node') {
 				logger.info({ node }, 'unknown encrypt notification')
 			}
@@ -2302,44 +2330,54 @@ export const makeMessagesRecvSocket = (config: SocketConfig) => {
 		)
 
 		const alt = msg.key.participantAlt || msg.key.remoteJidAlt
-		// Handle LID/PN mappings with hybrid approach:
+		// Handle LID/PN mappings with optimized hot-path:
-		// - Store mapping operation runs in background (non-critical for decrypt)
+		// - storeLIDPNMappings is fire-and-forget (background) — does NOT block decrypt
-		// - Session migration MUST complete before decrypt() to avoid "No session record" errors
+		// - migrateSession is SYNC (await) — REQUIRED for decrypt to find session
-		// This addresses Codex/Copilot review concerns about race conditions with decrypt()
+		//
+		// SAFETY: normalizeMessageJids has a fast-path that uses key.*Alt directly without
+		// hitting the store, so the just-arrived message normalizes correctly even before
+		// the background store completes. Subsequent messages in the same chat hit the
+		// store after the background write is done (ms later).
+		//
+		// Pre-check (getPNForLID/getLIDForPN) was removed — storeLIDPNMappings has internal
+		// LRU cache + dedup, the pre-check was a redundant store round-trip per inbound
+		// message that added latency under load.
+		//
+		// HISTORICAL: this restores the intent of d73cd28d39 (2026-02-03) which was
+		// partially reverted by c3fc792351 the same day due to a race-condition concern
+		// with migrateSession (kept sync here). storeLIDPNMappings was over-protected:
+		// it persists a mapping that downstream consumers can re-derive from key.*Alt,
+		// while migrateSession actually moves the Signal session record that decrypt()
+		// will load microseconds later — those two have very different criticality.
+		//
+		// DO NOT make migrateSession async — decrypt() depends on the session being at
+		// the correct identifier (LID vs PN) when it runs. Other code paths (USync
+		// device lookup in messages-send.ts) create LID/PN mappings without migrating
+		// the session, so we cannot skip migration even when the mapping already exists.
 		if (!!alt) {
 			const altServer = jidDecode(alt)?.server
 			const primaryJid = msg.key.participant || msg.key.remoteJid!
 
 			if (altServer === 'lid') {
-				// Check if mapping already exists to avoid unnecessary storage operations
+				// Fire-and-forget: storeLIDPNMappings has internal cache+dedup,
-				const existingMapping = await signalRepository.lidMapping.getPNForLID(alt)
+				// pre-check (getPNForLID) was redundant.
-				if (!existingMapping) {
+				signalRepository.lidMapping
-					// MUST await: normalizeMessageJids() runs after this and needs the mapping
+					.storeLIDPNMappings([{ lid: alt, pn: primaryJid }])
-					// in the LIDMappingStore to resolve LID→PN for events delivered to consumers
+					.catch(error => logger.warn({ error, alt, primaryJid }, 'background LID mapping store failed'))
-					await signalRepository.lidMapping
-						.storeLIDPNMappings([{ lid: alt, pn: primaryJid }])
-						.catch(error => logger.warn({ error, alt, primaryJid }, 'LID mapping storage failed'))
-				}
 
-				// CRITICAL: ALWAYS migrate session, even if mapping exists
+				// CRITICAL: ALWAYS migrate session SYNC, even if mapping exists.
-				// Other code paths (e.g., USync device lookup in messages-send.ts:310-319)
+				// Other code paths (e.g., USync device lookup in messages-send.ts) may create
-				// may create mappings via storeLIDPNMappings() without calling migrateSession()
+				// mappings via storeLIDPNMappings() without calling migrateSession(). This
-				// This leaves sessions under PN format while decrypt() expects LID format
+				// leaves sessions under PN format while decrypt() expects LID format.
-				// Skipping migration based on mapping existence causes "No session record" errors
+				// Skipping migration based on mapping existence causes "No session record" errors.
 				await signalRepository.migrateSession(primaryJid, alt)
 			} else {
-				// Check if reverse mapping exists
+				// Fire-and-forget: same rationale as above.
-				const existingMapping = await signalRepository.lidMapping.getLIDForPN(alt)
+				signalRepository.lidMapping
-				if (!existingMapping) {
+					.storeLIDPNMappings([{ lid: primaryJid, pn: alt }])
-					// MUST await: normalizeMessageJids() runs after this and needs the mapping
+					.catch(error => logger.warn({ error, alt, primaryJid }, 'background LID mapping store failed'))
-					// in the LIDMappingStore to resolve LID→PN for events delivered to consumers
-					await signalRepository.lidMapping
-						.storeLIDPNMappings([{ lid: primaryJid, pn: alt }])
-						.catch(error => logger.warn({ error, alt, primaryJid }, 'LID mapping storage failed'))
-				}
 
-				// CRITICAL: ALWAYS migrate session, even if mapping exists
+				// CRITICAL: ALWAYS migrate session SYNC.
-				// Same reasoning as above - mapping existence doesn't guarantee session migration
 				await signalRepository.migrateSession(alt, primaryJid)
 			}
 		}
@@ -3220,19 +3258,24 @@ export const makeMessagesRecvSocket = (config: SocketConfig) => {
 			// Await index load first — prevents overwriting a more complete persisted index
 			// if the connection closes before the initial load finishes.
 			tcTokenIndexLoaded
-				.then(() => {
+				.then(async () => {
-					Promise.resolve(
+					try {
-						authState.keys.set({
+						// Same merge-with-persisted invariant as scheduleTcTokenIndexSave —
+						// other layers may have written cross-layer JIDs to the index since
+						// our in-memory set was last updated.
+						const merged = await buildMergedTcTokenIndexWrite(authState.keys, tcTokenKnownJids)
+						await authState.keys.set({
 							tctoken: {
+								...merged,
 								[TC_TOKEN_INDEX_KEY]: {
-									token: Buffer.from(JSON.stringify([...tcTokenKnownJids]), 'utf8'),
+									...merged[TC_TOKEN_INDEX_KEY],
 									timestamp: unixTimestampSeconds().toString()
 								}
 							}
 						})
-					).catch(() => {
+					} catch {
 						/* non-critical */
-					})
+					}
 				})
 				.catch(() => {
 					/* non-critical */

src/Socket/messages-send.ts

@@ -46,7 +46,10 @@ import { makeKeyedMutex } from '../Utils/make-mutex'
 import { metrics, recordMessageFailure, recordMessageSent } from '../Utils/prometheus-metrics'
 import { getMessageReportingToken, shouldIncludeReportingToken } from '../Utils/reporting-utils'
 import {
+	buildMergedTcTokenIndexWrite,
+	isRegularUser,
 	isTcTokenExpired,
+	resolveIssuanceJid,
 	resolveTcTokenJid,
 	shouldSendNewTcToken,
 	storeTcTokensFromIqResult
@@ -125,6 +128,15 @@ export const makeMessagesSocket = (config: SocketConfig) => {
 	// Tracks JIDs with an in-flight getPrivacyTokens IQ to avoid duplicate concurrent fetches
 	const tcTokenFetchingJids = new Set<string>()
 
+	/**
+	 * Set of tctoken storage JIDs with a fire-and-forget `issuePrivacyTokens` IQ in flight.
+	 * Distinct from `tcTokenFetchingJids` (which dedupes inbound *fetches* of the peer's
+	 * token). Prevents duplicate IQs when a caller fires several rapid back-to-back sends
+	 * to the same contact before `senderTimestamp` persists. Entries are always removed
+	 * in `.finally()`, so the set is bounded by current concurrency.
+	 */
+	const inFlightTcTokenIssuance = new Set<string>()
+
 	let mediaConn: Promise<MediaConnInfo>
 	const refreshMediaConn = async (forceGet = false) => {
 		const media = await mediaConn
@@ -1715,7 +1727,16 @@ export const makeMessagesSocket = (config: SocketConfig) => {
 				}
 			}
 
-			if (tcTokenBuffer?.length) {
+			// Gate inclusion on AB prop 10518 (privacy_token_sending_on_all_1_on_1_messages).
+			// WA Web defaults to true; if the server flips it off we mirror that to avoid
+			// divergence with the spec-compliant client.
+			//
+			// CARROUSEL EXCEPTION: Pastorini-validated carousel stanzas REQUIRE tctoken
+			// (CDP capture confirms it). If the AB prop ever flips off, dropping the
+			// tctoken from carousel would break rendering on Android. Carousel always
+			// includes the tctoken when one is available, regardless of the prop —
+			// matching the fork's existing behaviour pre-PR #2339.
+			if (tcTokenBuffer?.length && (sock.serverProps.privacyTokenOn1to1 || isCarousel)) {
 				;(stanza.content as BinaryNode[]).push({
 					tag: 'tctoken',
 					attrs: {},
@@ -1815,13 +1836,39 @@ export const makeMessagesSocket = (config: SocketConfig) => {
 			// Gated only by shouldSendNewTcToken — removed tcTokenBuffer?.length guard so
 			// issuance fires even when we don't yet hold a token (bucket boundary crossed).
 			// IMPORTANT: must run AFTER sendNode — issuing before the message causes error 463.
-			if (is1on1Send && shouldSendNewTcToken(existingTokenEntry?.senderTimestamp)) {
+			//
+			// WA Web also skips issuance for:
+			//   - protocol messages (revoke, ephemeral settings, etc — see TcTokenChatAction)
+			//   - PSA, bots, MetaAI (isRegularUser filter)
+			// and dedupes back-to-back issuances with `inFlightTcTokenIssuance` so a burst of
+			// rapid sends to the same contact only triggers a single IQ before senderTimestamp
+			// is persisted.
+			const isProtocolMsg = !!normalizeMessageContent(message)?.protocolMessage
+			// Use isRegularUser (the same Wid.isRegularUser() port that gates the store
+			// path) so we filter PSA/bot/MetaAI consistently regardless of JID server
+			// (@c.us vs @s.whatsapp.net) and device suffix. The previous PSA_WID/isJidBot
+			// checks only matched @c.us forms — destinationJid arrives normalized.
+			const isBotOrPSA = !isRegularUser(destinationJid)
+			if (
+				is1on1Send &&
+				!isProtocolMsg &&
+				!isBotOrPSA &&
+				shouldSendNewTcToken(existingTokenEntry?.senderTimestamp) &&
+				!inFlightTcTokenIssuance.has(tcTokenJid)
+			) {
+				inFlightTcTokenIssuance.add(tcTokenJid)
 				const issueTimestamp = unixTimestampSeconds()
 				logTcToken('reissue', { jid: destinationJid })
-				getPrivacyTokens([destinationJid], issueTimestamp)
+				const getPNForLID = signalRepository.lidMapping.getPNForLID.bind(signalRepository.lidMapping)
+				resolveIssuanceJid(
+					destinationJid,
+					sock.serverProps.lidTrustedTokenIssueToLid,
+					getLIDForPN,
+					getPNForLID
+				)
+					.then(issueJid => getPrivacyTokens([issueJid], issueTimestamp))
 					.then(async result => {
 						// Store any tokens received in the IQ response.
-						// onNewJidStored not passed — pruning index lives in messages-recv (higher layer).
 						await storeTcTokensFromIqResult({
 							result,
 							fallbackJid: tcTokenJid,
@@ -1832,9 +1879,11 @@ export const makeMessagesSocket = (config: SocketConfig) => {
 						// Persist senderTimestamp unconditionally — WA Web stores it in the chat table
 						// regardless of whether a token exists. Spread preserves token+timestamp if present.
 						// WABA Android: INSERT INTO wa_trusted_contacts_send (jid, sent_tc_token_timestamp, real_issue_timestamp)
-						// VALUES (?, ?, 0) — realIssueTimestamp=0 means issued but not yet confirmed by server
+						// VALUES (?, ?, 0) — realIssueTimestamp=0 means issued but not yet confirmed by server.
+						// Also bump the cross-session prune index so this JID is tracked persistently.
 						const currentData = await authState.keys.get('tctoken', [tcTokenJid])
 						const currentEntry = currentData[tcTokenJid]
+						const indexWrite = await buildMergedTcTokenIndexWrite(authState.keys, [tcTokenJid])
 						await authState.keys.set({
 							tctoken: {
 								[tcTokenJid]: {
@@ -1842,7 +1891,8 @@ export const makeMessagesSocket = (config: SocketConfig) => {
 									token: currentEntry?.token ?? Buffer.alloc(0),
 									senderTimestamp: issueTimestamp,
 									realIssueTimestamp: 0
-								}
+								},
+								...indexWrite
 							}
 						})
 
@@ -1851,6 +1901,9 @@ export const makeMessagesSocket = (config: SocketConfig) => {
 					.catch(err => {
 						logTcToken('reissue_fail', { jid: destinationJid, error: err?.message })
 					})
+					.finally(() => {
+						inFlightTcTokenIssuance.delete(tcTokenJid)
+					})
 			}
 
 			// Log with [BAILEYS] prefix

src/Socket/socket.ts

@@ -39,12 +39,7 @@ import {
 	xmppSignedPreKey
 } from '../Utils'
 import { getPlatformId, isAndroidBrowser } from '../Utils/browser-utils'
-import {
+import { withBoundedRetry } from '../Utils/bounded-retry'
-	CircuitBreaker,
-	CircuitOpenError,
-	createConnectionCircuitBreaker,
-	createPreKeyCircuitBreaker
-} from '../Utils/circuit-breaker'
 import {
 	decrementActiveConnections,
 	incrementActiveConnections,
@@ -94,10 +89,6 @@ export const makeSocket = (config: SocketConfig) => {
 		transactionOpts,
 		qrTimeout,
 		makeSignalRepository,
-		enableCircuitBreaker = true,
-		queryCircuitBreaker: queryCircuitBreakerConfig,
-		connectionCircuitBreaker: connectionCircuitBreakerConfig,
-		preKeyCircuitBreaker: preKeyCircuitBreakerConfig,
 		// If enableUnifiedSession is explicitly set (true/false), use it
 		// Otherwise (undefined), check env var, then default to true
 		enableUnifiedSession: enableUnifiedSessionConfig
@@ -107,57 +98,6 @@ export const makeSocket = (config: SocketConfig) => {
 	const enableUnifiedSession =
 		enableUnifiedSessionConfig !== undefined ? enableUnifiedSessionConfig : shouldEnableUnifiedSession()
 
-	// Initialize circuit breakers if enabled
-	let queryCircuitBreaker: CircuitBreaker | undefined
-	let connectionCircuitBreaker: CircuitBreaker | undefined
-	let preKeyCircuitBreaker: CircuitBreaker | undefined
-
-	if (enableCircuitBreaker) {
-		// Circuit breaker for query operations (most critical)
-		queryCircuitBreaker = createConnectionCircuitBreaker({
-			name: 'socket-query',
-			failureThreshold: 5,
-			failureWindow: 60000,
-			resetTimeout: 30000,
-			successThreshold: 2,
-			timeout: defaultQueryTimeoutMs || 60000,
-			onStateChange: (from, to) => {
-				logger.info({ from, to }, 'Query circuit breaker state changed')
-			},
-			onOpen: () => {
-				logger.warn('Query circuit breaker OPENED - blocking requests')
-			},
-			onClose: () => {
-				logger.info('Query circuit breaker CLOSED - resuming normal operation')
-			},
-			...queryCircuitBreakerConfig
-		})
-
-		// Circuit breaker for connection operations
-		connectionCircuitBreaker = createConnectionCircuitBreaker({
-			name: 'socket-connection',
-			failureThreshold: 3,
-			failureWindow: 30000,
-			resetTimeout: 60000,
-			successThreshold: 1,
-			onStateChange: (from, to) => {
-				logger.info({ from, to }, 'Connection circuit breaker state changed')
-			},
-			...connectionCircuitBreakerConfig
-		})
-
-		// Circuit breaker for pre-key operations
-		preKeyCircuitBreaker = createPreKeyCircuitBreaker({
-			name: 'socket-prekey',
-			onStateChange: (from, to) => {
-				logger.info({ from, to }, 'PreKey circuit breaker state changed')
-			},
-			...preKeyCircuitBreakerConfig
-		})
-
-		logger.info('Circuit breakers initialized for socket operations')
-	}
-
 	// Unified Session Manager will be initialized after sendNode is defined
 	let unifiedSessionManager: UnifiedSessionManager | undefined
 
@@ -238,20 +178,17 @@ export const makeSocket = (config: SocketConfig) => {
 		})
 	}
 
-	/** send a raw buffer with circuit breaker protection */
+	/**
+	 * Send a raw buffer over the WebSocket.
+	 *
+	 * Replaces the previous connectionCircuitBreaker wrapping. WebSocket
+	 * lifecycle errors (Connection Closed / Lost / Replaced) were already
+	 * filtered out of the circuit's failure count, so the only failures it
+	 * tripped on were rare native send() errors — for which a state-machine
+	 * gate adds no value over a fast propagated error. Reconnection logic
+	 * in makeSocket already handles WS recovery independently.
+	 */
 	const sendRawMessage = async (data: Uint8Array | Buffer) => {
-		if (connectionCircuitBreaker) {
-			try {
-				return await connectionCircuitBreaker.execute(() => sendRawMessageInternal(data))
-			} catch (error) {
-				if (error instanceof CircuitOpenError) {
-					logger.warn({ circuitName: error.circuitName }, 'Send blocked by connection circuit breaker')
-				}
-
-				throw error
-			}
-		}
-
 		return sendRawMessageInternal(data)
 	}
 
@@ -266,7 +203,7 @@ export const makeSocket = (config: SocketConfig) => {
 	}
 
 	// Initialize Unified Session Manager now that sendNode is defined
-	// (single initialization to avoid duplicating circuit breakers and state)
+	// (single initialization to avoid duplicating manager state)
 	if (enableUnifiedSession) {
 		const sendNodeForSession = async (node: BinaryNode): Promise<void> => {
 			await sendNode(node)
@@ -275,7 +212,6 @@ export const makeSocket = (config: SocketConfig) => {
 		unifiedSessionManager = createUnifiedSessionManager({
 			enabled: true,
 			logger,
-			enableCircuitBreaker,
 			sendNode: sendNodeForSession
 		})
 		logger.info('Unified session manager initialized')
@@ -346,11 +282,8 @@ export const makeSocket = (config: SocketConfig) => {
 		// Register the response listener BEFORE sending — avoids a race where the server
 		// responds before we start listening.  waitForMessage already handles its own
 		// timeout (returns undefined) and connection-close errors (throws), so we do NOT
-		// wrap it in a second promiseTimeout.  The outer wrapper caused a race condition
+		// wrap it in a second promiseTimeout.  The outer wrapper would race the inner
-		// where both timers fired at ~the same deadline: the outer one threw
+		// timeout near the deadline and throw a spurious Boom('Timed Out').
-		// Boom('Timed Out') while sendNode was still pending, producing a spurious error
-		// whose message contained "socket-query" → matched the circuit-breaker's
-		// "socket" pattern → incorrectly tripped the breaker after 5 timeouts.
 		const responsePromise = waitForMessage<any>(msgId, timeoutMs)
 		// Prevent unhandled-rejection if sendNode throws before we reach
 		// `await responsePromise` below. The error from sendNode still propagates
@@ -372,23 +305,17 @@ export const makeSocket = (config: SocketConfig) => {
 		return result
 	}
 
-	/** send a query with circuit breaker protection */
+	/**
+	 * Send a query (iq stanza) and wait for its response.
+	 *
+	 * Replaces the previous queryCircuitBreaker wrapping (state-machine that
+	 * blocked ALL queries for 30s after 5 failures). The cascade behavior
+	 * was incompatible with WhatsApp Android's empirical retry pattern:
+	 * each operation retries independently with exponential backoff, no
+	 * global state. Callers that need retry semantics wrap query() with
+	 * withBoundedRetry() at their level (assertSessions, etc.).
+	 */
 	const query = async (node: BinaryNode, timeoutMs?: number) => {
-		// If circuit breaker is enabled, wrap the query
-		if (queryCircuitBreaker) {
-			try {
-				return await queryCircuitBreaker.execute(() => queryInternal(node, timeoutMs))
-			} catch (error) {
-				// If circuit is open, log and rethrow with context
-				if (error instanceof CircuitOpenError) {
-					logger.warn({ circuitName: error.circuitName, state: error.state }, 'Query blocked by circuit breaker')
-				}
-
-				throw error
-			}
-		}
-
-		// Fallback to direct query if circuit breaker is disabled
 		return queryInternal(node, timeoutMs)
 	}
 
@@ -685,20 +612,14 @@ export const makeSocket = (config: SocketConfig) => {
 	let lastUploadTime = 0
 
 	/** generates and uploads a set of pre-keys to the server */
-	const uploadPreKeys = async (count = MIN_PREKEY_COUNT, retryCount = 0) => {
+	const uploadPreKeys = async (count = MIN_PREKEY_COUNT) => {
-		// Check if pre-key circuit breaker is open
+		// Check minimum interval. (Previously this was guarded by `retryCount === 0`
-		if (preKeyCircuitBreaker?.isOpen()) {
+		// because the function recursed on retry; with bounded-retry handling
-			logger.warn('PreKey circuit breaker is open, skipping upload')
+		// retries internally there is no recursion and the guard is implicit.)
-			throw new CircuitOpenError('socket-prekey', 'open')
+		const timeSinceLastUpload = Date.now() - lastUploadTime
-		}
+		if (timeSinceLastUpload < MIN_UPLOAD_INTERVAL) {
-
+			logger.debug(`Skipping upload, only ${timeSinceLastUpload}ms since last upload`)
-		// Check minimum interval (except for retries)
+			return
-		if (retryCount === 0) {
-			const timeSinceLastUpload = Date.now() - lastUploadTime
-			if (timeSinceLastUpload < MIN_UPLOAD_INTERVAL) {
-				logger.debug(`Skipping upload, only ${timeSinceLastUpload}ms since last upload`)
-				return
-			}
 		}
 
 		// Prevent multiple concurrent uploads — if one is already running, wait for it and return:
@@ -709,8 +630,15 @@ export const makeSocket = (config: SocketConfig) => {
 			return
 		}
 
+		// Shared abort controller so the outer Promise.race can cancel the
+		// in-flight bounded-retry loop if its own timeout fires first.
+		// Without this, the outer race rejects but the bounded-retry loop
+		// keeps running in the background, mutating lastUploadTime / logs
+		// after the caller has given up (CodeRabbit + Copilot reviews).
+		const uploadAbort = new AbortController()
+
 		const uploadLogic = async () => {
-			logger.info({ count, retryCount }, 'uploading pre-keys')
+			logger.info({ count }, 'uploading pre-keys')
 
 			// Generate and save pre-keys atomically (prevents ID collisions on retry)
 			const node = await keys.transaction(async () => {
@@ -721,45 +649,69 @@ export const makeSocket = (config: SocketConfig) => {
 				return node // Only return node since update is already used
 			}, creds?.me?.id || 'upload-pre-keys')
 
-			// Upload to server with circuit breaker protection
+			// Upload to server. Bounded-retry handles backoff (replaces both
-			const uploadToServer = async () => {
+			// the previous circuit breaker AND the manual exponential backoff
-				await query(node)
+			// retry loop with maxRetries=3).
+			//
+			// CRITICAL: query() returns `undefined` on timeout (it does NOT
+			// throw — see waitForMessage). If we just `await query(node)`,
+			// a timed-out upload would resolve with undefined and bounded-retry
+			// would treat it as success. Validate the response shape so a
+			// timeout actually triggers a retry (CodeRabbit review on PR #393).
+			//
+			// bounded-retry's ttlMs MUST be < UPLOAD_TIMEOUT (the outer
+			// Promise.race below). With margin (28s vs 30s) bounded-retry
+			// always reaches its natural give-up first. We additionally pass
+			// an AbortController signal so that if the outer race ever fires
+			// first, the bounded-retry loop is aborted and does not keep
+			// running in the background (CodeRabbit + Copilot reviews).
+			const PER_ATTEMPT_TIMEOUT_MS = 8_000
+			const RETRY_TTL_MS = UPLOAD_TIMEOUT - 2_000
+
+			const uploadToServer = async (signal?: AbortSignal) => {
+				const result = await query(node, PER_ATTEMPT_TIMEOUT_MS)
+				if (signal?.aborted) {
+					throw new Error('aborted')
+				}
+
+				if (!result) {
+					// query() returned undefined → underlying iq response
+					// timed out. Throw so bounded-retry retries.
+					throw new Boom('Pre-key upload query timed out (no response)', { statusCode: 408 })
+				}
+
 				logger.info({ count }, 'uploaded pre-keys successfully')
 				lastUploadTime = Date.now()
 			}
 
 			try {
-				// Use circuit breaker if available
+				await withBoundedRetry(uploadToServer, {
-				if (preKeyCircuitBreaker) {
+					name: 'uploadPreKeys',
-					await preKeyCircuitBreaker.execute(uploadToServer)
+					// 1s -> 2s -> 4s -> 8s (cap). Max 4 attempts fit comfortably
-				} else {
+					// within RETRY_TTL_MS (28s) given perAttemptTimeoutMs=8s.
-					await uploadToServer()
+					delays: [1000, 2000, 4000, 8000],
-				}
+					ttlMs: RETRY_TTL_MS,
+					perAttemptTimeoutMs: PER_ATTEMPT_TIMEOUT_MS,
+					signal: uploadAbort.signal,
+					logger
+				})
 			} catch (uploadError) {
 				logger.error({ uploadError: (uploadError as Error).toString(), count }, 'Failed to upload pre-keys to server')
-
-				// Don't retry if circuit breaker is open
-				if (uploadError instanceof CircuitOpenError) {
-					throw uploadError
-				}
-
-				// Exponential backoff retry (max 3 retries)
-				if (retryCount < 3) {
-					const backoffDelay = Math.min(1000 * Math.pow(2, retryCount), 10000)
-					logger.info(`Retrying pre-key upload in ${backoffDelay}ms`)
-					await new Promise(resolve => setTimeout(resolve, backoffDelay))
-					return uploadPreKeys(count, retryCount + 1)
-				}
-
 				throw uploadError
 			}
 		}
 
-		// Add timeout protection
+		// Outer timeout protection. With ttlMs=28s vs UPLOAD_TIMEOUT=30s,
+		// bounded-retry should always win — but if anything ever blocks
+		// uploadLogic outside bounded-retry's reach, this race aborts the
+		// whole thing cleanly via uploadAbort.
 		uploadPreKeysPromise = Promise.race([
 			uploadLogic(),
 			new Promise<void>((_, reject) =>
-				setTimeout(() => reject(new Boom('Pre-key upload timeout', { statusCode: 408 })), UPLOAD_TIMEOUT)
+				setTimeout(() => {
+					uploadAbort.abort()
+					reject(new Boom('Pre-key upload timeout', { statusCode: 408 }))
+				}, UPLOAD_TIMEOUT)
 			)
 		])
 
@@ -1231,12 +1183,6 @@ export const makeSocket = (config: SocketConfig) => {
 		cleanupPreKeyAutoSync()
 		cleanupSessionTTL()
 
-		// CRITICAL: Destroy circuit breakers AFTER cleanup functions complete
-		// This ensures cleanup functions can still use circuit breakers if needed
-		queryCircuitBreaker?.destroy()
-		connectionCircuitBreaker?.destroy()
-		preKeyCircuitBreaker?.destroy()
-
 		// IMPORTANT: Do NOT use removeAllListeners('connection.update')
 		// It would remove consumer listeners, breaking their reconnection logic
 	}
@@ -1289,11 +1235,12 @@ export const makeSocket = (config: SocketConfig) => {
 				return // connection closing — do not reschedule
 			} else if (ws.isOpen) {
 				// Send keep-alive ping via sendNode() (fire-and-forget) instead of query().
-				// query() wraps the ping in the query circuit breaker — when that breaker is
+				// We don't need the response correlator overhead — WA's pong arrives as an
-				// open or timing out, the ping is never sent, WA never responds, lastDateRecv
+				// incoming frame and updates lastDateRecv via the standard receive path.
-				// goes stale, and the diff check above wrongly fires "Connection was lost".
+				// (Historical context: this used to bypass the query circuit breaker,
-				// sendNode() bypasses the query circuit breaker entirely; WA's ping response
+				// which would block pings during cascade failures. Circuit breaker has
-				// still arrives as an incoming frame and updates lastDateRecv normally.
+				// since been replaced by per-operation bounded-retry — but the
+				// fire-and-forget pattern stays correct on its own merits.)
 				sendNode({
 					tag: 'iq',
 					attrs: {
@@ -1809,25 +1756,6 @@ export const makeSocket = (config: SocketConfig) => {
 		sendWAMBuffer,
 		executeUSyncQuery,
 		onWhatsApp,
-		// Circuit breaker utilities
-		circuitBreakers: {
-			query: queryCircuitBreaker,
-			connection: connectionCircuitBreaker,
-			preKey: preKeyCircuitBreaker
-		},
-		/** Get circuit breaker statistics */
-		getCircuitBreakerStats: () => ({
-			query: queryCircuitBreaker?.getStats(),
-			connection: connectionCircuitBreaker?.getStats(),
-			preKey: preKeyCircuitBreaker?.getStats()
-		}),
-		/** Reset all circuit breakers to closed state */
-		resetCircuitBreakers: () => {
-			queryCircuitBreaker?.reset()
-			connectionCircuitBreaker?.reset()
-			preKeyCircuitBreaker?.reset()
-			logger.info('All circuit breakers reset to closed state')
-		},
 		// Unified Session Telemetry
 		/** Send unified_session telemetry manually */
 		sendUnifiedSession,

src/Types/Socket.ts

@@ -1,7 +1,6 @@
 import type { Agent } from 'https'
 import type { URL } from 'url'
 import { proto } from '../../WAProto/index.js'
-import type { CircuitBreakerOptions } from '../Utils/circuit-breaker'
 import type { ILogger } from '../Utils/logger'
 import type { AuthenticationState, LIDMapping, SignalAuthState, TransactionCapabilityOptions } from './Auth'
 import type { GroupMetadata } from './GroupMetadata'
@@ -203,23 +202,6 @@ export type SocketConfig = {
 		pnToLIDFunc?: (jids: string[]) => Promise<LIDMapping[] | undefined>
 	) => SignalRepositoryWithLIDStore
 
-	// === Circuit Breaker Configuration ===
-
-	/** Enable circuit breaker protection for socket operations (default: true) */
-	enableCircuitBreaker?: boolean
-
-	/** Circuit breaker configuration for query operations */
-	queryCircuitBreaker?: Partial<CircuitBreakerOptions>
-
-	/** Circuit breaker configuration for connection operations */
-	connectionCircuitBreaker?: Partial<CircuitBreakerOptions>
-
-	/** Circuit breaker configuration for pre-key operations */
-	preKeyCircuitBreaker?: Partial<CircuitBreakerOptions>
-
-	/** Circuit breaker configuration for message operations */
-	messageCircuitBreaker?: Partial<CircuitBreakerOptions>
-
 	// === Listener Limits (Memory Leak Prevention) ===
 
 	/**

src/Utils/auth-utils.ts

@@ -341,7 +341,18 @@ export const addTransactionCapability = (
 
 						return result
 					} catch (error) {
-						logger.error({ error }, 'transaction failed, rolling back')
+						// SessionError is part of the normal Bad MAC recovery flow
+						// (retry receipt → sender resends as pkmsg → new session within ~1.3s).
+						// Logging it as ERROR creates 2 noise lines per recoverable Bad MAC cycle.
+						// Downgrade to debug for SessionError; keep ERROR for everything else.
+						// The error is still re-thrown — recovery behavior is unchanged.
+						const errName = (error as { name?: string })?.name
+						if (errName === 'SessionError') {
+							logger.debug({ error }, 'transaction failed (SessionError — recoverable via retry receipt)')
+						} else {
+							logger.error({ error }, 'transaction failed, rolling back')
+						}
+
 						throw error
 					}
 				})

src/Utils/bounded-retry.ts

@@ -0,0 +1,393 @@
+/**
+ * Bounded retry — WhatsApp-aligned per-operation retry without global state.
+ *
+ * # Why this exists
+ *
+ * Replaces the circuit breaker pattern that was causing cascading failures
+ * in production: 5 timeouts in 60s would trip the global breaker, blocking
+ * EVERY socket query (typing indicators, profile pic fetches, contact
+ * validation, presence updates) for 30s — even queries to peers that were
+ * perfectly healthy.
+ *
+ * # Empirical justification
+ *
+ * Captured WhatsApp Android's actual retry behavior via Frida hooks
+ * (`hook-circuit-breaker-re-v2.js`, `hook-retry-bounds.js`) on a real
+ * device under controlled WiFi off/on cycles. Findings:
+ *
+ *   1. Delay sequence (per-operation): 3s -> 10s -> 60s -> ~64s -> 120s
+ *      (cap at 2 min). Last value reused for further attempts.
+ *   2. Memory profile during 5-min network outage: PSS dropped 53MB and
+ *      stabilised. FDs closed (305 -> 295). NO unbounded accumulation.
+ *   3. Recovery on reconnect: ~10s. No retry storm.
+ *   4. NO global state machine observed. Each operation has its own timer.
+ *      Failures of operation A do NOT block operation B.
+ *
+ * The default delays in WHATSAPP_BACKOFF_DELAYS below match the captured
+ * sequence directly. The default 10-min TTL is empirical 3-5 min stability
+ * + safety buffer.
+ *
+ * # Design properties
+ *
+ * - Per-operation isolation: each call to `withBoundedRetry` has its own
+ *   timer. No shared state. Operation A failing has zero effect on B.
+ * - Bounded by `ttlMs` (wall-clock budget). The TTL is enforced strictly
+ *   at three points: (a) before each attempt, (b) cap on per-attempt
+ *   timeout, (c) cap on retry delay.
+ * - Per-attempt timeout: each attempt has its own deadline (default 30s),
+ *   automatically capped to remaining TTL budget so total runtime never
+ *   exceeds ttlMs.
+ * - AbortSignal cancellation: external cancellation supported, both for
+ *   the sleep between retries AND (optionally) the in-flight operation
+ *   when the operation accepts a signal parameter.
+ * - Memory bound: at most one outstanding retry timer per call. Listeners
+ *   are explicitly removed when timers settle. Once the call resolves /
+ *   rejects / aborts, all state is freed.
+ *
+ * # Logging
+ *
+ * Pass `logger` in options to get structured logs at each retry attempt,
+ * give-up, and post-failure recovery. The module emits Prometheus metrics
+ * regardless of whether a logger is provided.
+ *
+ * # When to use this vs. plain query()
+ *
+ * - Use plain `query()` when you want fast-fail semantics (caller decides
+ *   what to do on failure). Most call sites in InfiniteAPI use this.
+ * - Use `withBoundedRetry(() => query(...), { name: 'X' })` when the
+ *   operation is "must-eventually-succeed" with no upstream retry — e.g.
+ *   `uploadPreKeys` or other write paths where the alternative is data loss.
+ *
+ * # Examples
+ *
+ * ```ts
+ * // Single attempt with 5-min TTL, give up after that:
+ * await withBoundedRetry(
+ *   () => assertSessions([jid], true),
+ *   { name: 'assertSessions', ttlMs: 5 * 60_000, logger }
+ * )
+ *
+ * // Tight deadline, fast give-up:
+ * await withBoundedRetry(
+ *   () => sendNode(node),
+ *   { name: 'send', ttlMs: 30_000, perAttemptTimeoutMs: 5_000 }
+ * )
+ *
+ * // Operation that respects abort signal (best practice):
+ * await withBoundedRetry(
+ *   (signal) => fetchSomething({ signal }),
+ *   { name: 'fetch', logger }
+ * )
+ * ```
+ *
+ * @module Utils/bounded-retry
+ */
+
+import type { ILogger } from './logger'
+import { metrics } from './prometheus-metrics.js'
+
+/**
+ * Default delay sequence (milliseconds) — matches WhatsApp Android empirical
+ * behavior. After exhausting the sequence, the last value is used (cap).
+ */
+export const WHATSAPP_BACKOFF_DELAYS = [3000, 10000, 60000, 60000, 120000] as const
+
+/**
+ * Default jitter (+/- 15%) to prevent thundering-herd retries.
+ */
+export const DEFAULT_JITTER_FACTOR = 0.15 as const
+
+/**
+ * Default time-to-live for retries: 10 minutes.
+ *
+ * Empirical justification: WhatsApp Android stabilises memory in ~3-5 min
+ * during a network outage; 10 min gives a generous safety buffer while
+ * preventing unbounded retry accumulation.
+ */
+export const DEFAULT_TTL_MS = 10 * 60 * 1000
+
+/**
+ * Default per-attempt timeout: 30 seconds.
+ *
+ * Most WhatsApp queries respond within seconds. A 30s timeout is generous
+ * enough for slow networks but prevents a single hang from blocking retries.
+ */
+export const DEFAULT_PER_ATTEMPT_TIMEOUT_MS = 30000
+
+export interface BoundedRetryOptions {
+	/** Operation name for logging/metrics */
+	name?: string
+	/** Sequence of delays (ms). Last value is used as cap. */
+	delays?: readonly number[]
+	/** Jitter factor 0..1 (default 0.15) */
+	jitter?: number
+	/** Total wall-clock budget — gives up after this. Default 10 min. */
+	ttlMs?: number
+	/** Per-attempt timeout (ms). Default 30s. Capped by remaining TTL. */
+	perAttemptTimeoutMs?: number
+	/** Predicate: should we retry on this error? Default: always */
+	shouldRetry?: (err: Error, attempt: number) => boolean
+	/** Hook fired before each retry */
+	onRetry?: (err: Error, attempt: number, delayMs: number) => void
+	/**
+	 * AbortSignal — when fired, the loop stops at the next observation point:
+	 *   - If the loop is sleeping between retries, the sleep rejects immediately.
+	 *   - If an attempt is in flight, the abort is forwarded to the operation
+	 *     via the per-attempt signal. The operation must ITSELF observe the
+	 *     signal (e.g. `(signal) => fetch({ signal })`) for cancellation to
+	 *     be truly immediate; otherwise it cancels at the next per-attempt
+	 *     timeout boundary.
+	 *   - Either way, on the next loop iteration BoundedRetryAbortedError is
+	 *     thrown, so the caller never sees more than one trailing attempt
+	 *     after the abort.
+	 */
+	signal?: AbortSignal
+	/** Optional logger for structured retry/give-up/recovery logs */
+	logger?: ILogger
+}
+
+export class BoundedRetryGiveUpError extends Error {
+	constructor(
+		public readonly opName: string,
+		public readonly attempts: number,
+		public readonly elapsedMs: number,
+		public readonly lastError: Error
+	) {
+		super(
+			`bounded-retry "${opName}" gave up after ${attempts} attempts ` +
+				`(${elapsedMs}ms elapsed). Last error: ${lastError.message}`
+		)
+		this.name = 'BoundedRetryGiveUpError'
+	}
+}
+
+export class BoundedRetryAbortedError extends Error {
+	constructor(public readonly opName: string) {
+		super(`bounded-retry "${opName}" aborted via signal`)
+		this.name = 'BoundedRetryAbortedError'
+	}
+}
+
+/**
+ * Apply jitter to a delay: returns delay * (1 +/- jitter)
+ */
+function withJitter(delayMs: number, jitter: number): number {
+	if (jitter <= 0) return delayMs
+	const factor = 1 + (Math.random() * 2 - 1) * jitter
+	return Math.max(0, Math.round(delayMs * factor))
+}
+
+/**
+ * Pick the delay for a given attempt index. Falls back to the last value
+ * (cap) once the sequence is exhausted.
+ */
+function pickDelay(attempt: number, delays: readonly number[]): number {
+	if (delays.length === 0) return 0
+	if (attempt < delays.length) return delays[attempt]!
+	return delays[delays.length - 1]!
+}
+
+/**
+ * Wrap a promise with a per-attempt timeout. Aborts the supplied controller
+ * when the timeout fires so the caller can cancel any in-flight work
+ * (operations that accept the signal). Always clears the timer on settlement.
+ */
+function withTimeout<T>(
+	promise: Promise<T>,
+	timeoutMs: number,
+	name: string,
+	abortOnTimeout: AbortController
+): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => {
+			abortOnTimeout.abort()
+			reject(new Error(`bounded-retry "${name}" attempt timed out after ${timeoutMs}ms`))
+		}, timeoutMs)
+		promise
+			.then(value => {
+				clearTimeout(timer)
+				resolve(value)
+			})
+			.catch(err => {
+				clearTimeout(timer)
+				reject(err as Error)
+			})
+	})
+}
+
+/**
+ * Sleep with abort support. Always removes the abort listener on settlement
+ * so listeners do not accumulate on long-lived signals.
+ */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error('aborted'))
+			return
+		}
+
+		let onAbort: (() => void) | undefined
+		const cleanup = () => {
+			if (onAbort && signal) {
+				signal.removeEventListener('abort', onAbort)
+			}
+		}
+
+		const timer = setTimeout(() => {
+			cleanup()
+			resolve()
+		}, ms)
+
+		if (signal) {
+			onAbort = () => {
+				clearTimeout(timer)
+				cleanup()
+				reject(new Error('aborted'))
+			}
+
+			signal.addEventListener('abort', onAbort, { once: true })
+		}
+	})
+}
+
+/**
+ * Run an async operation with bounded exponential-backoff retry.
+ *
+ * Independent per-call: no global state, no cross-operation interaction.
+ * Memory bound: at most one outstanding retry timer per call.
+ *
+ * The operation may optionally accept an `AbortSignal` parameter — when the
+ * per-attempt timeout fires (or the outer signal is aborted), the inner
+ * signal is aborted so the operation can stop in-flight work cleanly.
+ *
+ * @example
+ * ```ts
+ * const result = await withBoundedRetry(
+ *     (signal) => assertSessions([jid], true, { signal }),
+ *     { name: 'assertSessions', ttlMs: 5 * 60_000, logger }
+ * )
+ * ```
+ */
+export async function withBoundedRetry<T>(
+	operation: (signal?: AbortSignal) => Promise<T>,
+	options: BoundedRetryOptions = {}
+): Promise<T> {
+	const name = options.name ?? 'bounded-retry'
+	const delays = options.delays ?? WHATSAPP_BACKOFF_DELAYS
+	const jitter = options.jitter ?? DEFAULT_JITTER_FACTOR
+	const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
+	const perAttemptTimeoutMs = options.perAttemptTimeoutMs ?? DEFAULT_PER_ATTEMPT_TIMEOUT_MS
+	const shouldRetry = options.shouldRetry ?? (() => true)
+	const logger = options.logger
+
+	const start = Date.now()
+	let lastError: Error = new Error('unknown')
+	let attempt = 0
+
+	while (true) {
+		// Check abort + TTL BEFORE starting an attempt — strict wall-clock
+		// budget. Without this check the loop could begin a new attempt with
+		// 0ms remaining and then run for up to `perAttemptTimeoutMs`.
+		if (options.signal?.aborted) {
+			throw new BoundedRetryAbortedError(name)
+		}
+
+		const elapsedBeforeAttempt = Date.now() - start
+		const remainingBudget = ttlMs - elapsedBeforeAttempt
+		if (remainingBudget <= 0) {
+			metrics.errors?.inc({ category: 'bounded_retry', code: 'ttl_exceeded' })
+			logger?.warn?.(
+				{ op: name, attempts: attempt, elapsedMs: elapsedBeforeAttempt, ttlMs, lastError: lastError.message },
+				'bounded-retry: TTL exceeded before next attempt — giving up'
+			)
+			throw new BoundedRetryGiveUpError(name, attempt, elapsedBeforeAttempt, lastError)
+		}
+
+		// Cap the per-attempt timeout to the remaining TTL budget so a single
+		// attempt cannot run past the wall-clock deadline.
+		const attemptTimeoutMs = Math.min(perAttemptTimeoutMs, remainingBudget)
+		const attemptAbort = new AbortController()
+
+		// Forward outer abort to the per-attempt controller so the in-flight
+		// operation is cancelled when the user aborts. Cleaned up below.
+		let onOuterAbort: (() => void) | undefined
+		if (options.signal) {
+			onOuterAbort = () => attemptAbort.abort()
+			if (options.signal.aborted) {
+				attemptAbort.abort()
+			} else {
+				options.signal.addEventListener('abort', onOuterAbort, { once: true })
+			}
+		}
+
+		try {
+			const result = await withTimeout(operation(attemptAbort.signal), attemptTimeoutMs, name, attemptAbort)
+
+			if (attempt > 0) {
+				metrics.socketEvents?.inc({ event: 'bounded_retry_recovered' })
+				logger?.info?.(
+					{ op: name, attempts: attempt + 1, elapsedMs: Date.now() - start },
+					'bounded-retry: operation succeeded after retries'
+				)
+			}
+
+			return result
+		} catch (err) {
+			lastError = err as Error
+			attempt++
+
+			// (outer-abort listener detachment happens in the finally below —
+			// avoiding a double-remove that breaks listener-count assertions.)
+
+			// If the outer signal aborted us mid-attempt, surface that explicitly
+			// rather than as a generic operation failure.
+			if (options.signal?.aborted) {
+				throw new BoundedRetryAbortedError(name)
+			}
+
+			const elapsed = Date.now() - start
+
+			if (!shouldRetry(lastError, attempt)) {
+				metrics.errors?.inc({ category: 'bounded_retry', code: 'predicate_no_retry' })
+				logger?.warn?.(
+					{ op: name, attempts: attempt, elapsedMs: elapsed, error: lastError.message },
+					'bounded-retry: shouldRetry returned false — giving up'
+				)
+				throw lastError
+			}
+
+			// Re-check budget after the failure so we do not sleep past TTL.
+			const remainingAfterFailure = ttlMs - elapsed
+			if (remainingAfterFailure <= 0) {
+				metrics.errors?.inc({ category: 'bounded_retry', code: 'ttl_exceeded' })
+				logger?.warn?.(
+					{ op: name, attempts: attempt, elapsedMs: elapsed, ttlMs, lastError: lastError.message },
+					'bounded-retry: TTL exceeded after attempt — giving up'
+				)
+				throw new BoundedRetryGiveUpError(name, attempt, elapsed, lastError)
+			}
+
+			const baseDelay = pickDelay(attempt - 1, delays)
+			const delayMs = Math.min(withJitter(baseDelay, jitter), remainingAfterFailure)
+
+			options.onRetry?.(lastError, attempt, delayMs)
+			metrics.socketEvents?.inc({ event: 'bounded_retry_attempt' })
+			logger?.debug?.(
+				{ op: name, attempt, delayMs, elapsedMs: elapsed, error: lastError.message },
+				'bounded-retry: scheduling next attempt'
+			)
+
+			try {
+				await sleep(delayMs, options.signal)
+			} catch {
+				throw new BoundedRetryAbortedError(name)
+			}
+		} finally {
+			// Belt-and-suspenders: ensure the outer-abort listener is always
+			// removed even on early throws.
+			if (options.signal && onOuterAbort) {
+				options.signal.removeEventListener('abort', onOuterAbort)
+			}
+		}
+	}
+}

src/Utils/circuit-breaker.ts

@@ -1,766 +0,0 @@
-/**
- * Circuit Breaker Pattern Implementation
- *
- * Provides protection against cascading failures by monitoring operation outcomes
- * and temporarily blocking requests when failure thresholds are exceeded.
- *
- * States:
- * - CLOSED: Normal operation, requests pass through
- * - OPEN: Failures exceeded threshold, requests are blocked
- * - HALF_OPEN: Testing recovery, limited requests allowed
- *
- * @module Utils/circuit-breaker
- */
-
-import { EventEmitter } from 'events'
-import { metrics } from './prometheus-metrics.js'
-
-/**
- * Circuit breaker operational states
- */
-export type CircuitState = 'closed' | 'open' | 'half-open'
-
-/**
- * Failure record with timestamp for sliding window tracking
- */
-export interface FailureRecord {
-	timestamp: number
-	error: Error
-}
-
-/**
- * Circuit breaker configuration options
- */
-export interface CircuitBreakerOptions {
-	/** Unique identifier for this circuit breaker (used in metrics/logging) */
-	name: string
-	/** Number of failures within the window to trigger OPEN state (default: 5) */
-	failureThreshold?: number
-	/** Time window in ms for counting failures (default: 60000) */
-	failureWindow?: number
-	/** Number of successes required in HALF_OPEN to return to CLOSED (default: 2) */
-	successThreshold?: number
-	/** Time in ms to wait before transitioning from OPEN to HALF_OPEN (default: 30000) */
-	resetTimeout?: number
-	/** Timeout for individual operations in ms (default: 10000) */
-	timeout?: number
-	/** Minimum number of requests before circuit can trip (default: 5) */
-	volumeThreshold?: number
-	/** Predicate to determine if an error should count as a failure */
-	shouldCountError?: (error: Error) => boolean
-	/** Whether to collect Prometheus metrics (default: true) */
-	collectMetrics?: boolean
-	/** Fallback function when circuit is OPEN */
-	fallback?: <T>() => T | Promise<T>
-	/** Callback when state changes */
-	onStateChange?: (from: CircuitState, to: CircuitState) => void
-	/** Callback on failure */
-	onFailure?: (error: Error) => void
-	/** Callback on success */
-	onSuccess?: () => void
-	/** Callback when circuit opens */
-	onOpen?: () => void
-	/** Callback when circuit closes */
-	onClose?: () => void
-	/** Callback when circuit enters half-open */
-	onHalfOpen?: () => void
-}
-
-/**
- * Circuit breaker statistics
- */
-export interface CircuitBreakerStats {
-	state: CircuitState
-	failures: number
-	successes: number
-	consecutiveFailures: number
-	consecutiveSuccesses: number
-	totalCalls: number
-	totalFailures: number
-	totalSuccesses: number
-	totalRejected: number
-	failureRate: number
-	lastFailureTime?: number
-	lastSuccessTime?: number
-	lastStateChange?: number
-	isOpen: boolean
-	isClosed: boolean
-	isHalfOpen: boolean
-}
-
-/**
- * Error thrown when circuit is OPEN and request is rejected
- */
-export class CircuitOpenError extends Error {
-	constructor(
-		public readonly circuitName: string,
-		public readonly state: CircuitState
-	) {
-		super(`Circuit breaker "${circuitName}" is ${state}`)
-		this.name = 'CircuitOpenError'
-	}
-}
-
-/**
- * Error thrown when operation exceeds timeout
- */
-export class CircuitTimeoutError extends Error {
-	constructor(
-		public readonly circuitName: string,
-		public readonly timeoutMs: number
-	) {
-		super(`Circuit breaker "${circuitName}" operation timed out after ${timeoutMs}ms`)
-		this.name = 'CircuitTimeoutError'
-	}
-}
-
-/**
- * Circuit Breaker implementation with sliding window failure tracking
- *
- * @example
- * ```typescript
- * const breaker = new CircuitBreaker({
- *   name: 'whatsapp-api',
- *   failureThreshold: 5,
- *   resetTimeout: 30000
- * })
- *
- * try {
- *   const result = await breaker.execute(() => sendMessage(msg))
- * } catch (error) {
- *   if (error instanceof CircuitOpenError) {
- *     // Circuit is open, use fallback
- *   }
- * }
- * ```
- */
-export class CircuitBreaker extends EventEmitter {
-	private state: CircuitState = 'closed'
-	private failureRecords: FailureRecord[] = []
-	private consecutiveFailures = 0
-	private consecutiveSuccesses = 0
-	private totalCalls = 0
-	private totalFailures = 0
-	private totalSuccesses = 0
-	private totalRejected = 0
-	private lastFailureTime?: number
-	private lastSuccessTime?: number
-	private lastStateChange: number
-	private resetTimer?: ReturnType<typeof setTimeout>
-	private readonly options: Required<CircuitBreakerOptions>
-
-	constructor(options: CircuitBreakerOptions) {
-		super()
-
-		this.options = {
-			name: options.name,
-			failureThreshold: options.failureThreshold ?? 5,
-			failureWindow: options.failureWindow ?? 60000,
-			successThreshold: options.successThreshold ?? 2,
-			resetTimeout: options.resetTimeout ?? 30000,
-			timeout: options.timeout ?? 10000,
-			volumeThreshold: options.volumeThreshold ?? 5,
-			shouldCountError: options.shouldCountError ?? (() => true),
-			collectMetrics: options.collectMetrics ?? true,
-			fallback:
-				options.fallback ??
-				(() => {
-					throw new CircuitOpenError(this.options.name, this.state)
-				}),
-			onStateChange: options.onStateChange ?? (() => {}),
-			onFailure: options.onFailure ?? (() => {}),
-			onSuccess: options.onSuccess ?? (() => {}),
-			onOpen: options.onOpen ?? (() => {}),
-			onClose: options.onClose ?? (() => {}),
-			onHalfOpen: options.onHalfOpen ?? (() => {})
-		}
-
-		this.lastStateChange = Date.now()
-	}
-
-	/**
-	 * Check if the circuit allows execution
-	 */
-	canExecute(): boolean {
-		if (this.state === 'closed') {
-			return true
-		}
-
-		if (this.state === 'open') {
-			return false
-		}
-
-		// HALF_OPEN: allow limited requests for testing
-		return true
-	}
-
-	/**
-	 * Execute an async operation with circuit breaker protection
-	 */
-	async execute<T>(operation: () => T | Promise<T>): Promise<T> {
-		this.totalCalls++
-
-		// Check if circuit allows execution
-		if (this.state === 'open') {
-			this.totalRejected++
-
-			if (this.options.collectMetrics) {
-				metrics.errors.inc({ category: 'circuit_breaker', code: 'rejected' })
-			}
-
-			return this.options.fallback() as T
-		}
-
-		// Execute with timeout protection
-		try {
-			const result = await this.executeWithTimeout(operation)
-			this.recordSuccess()
-			return result
-		} catch (error) {
-			this.recordFailure(error as Error)
-			throw error
-		}
-	}
-
-	/**
-	 * Execute a synchronous operation with circuit breaker protection
-	 */
-	executeSync<T>(operation: () => T): T {
-		this.totalCalls++
-
-		if (this.state === 'open') {
-			this.totalRejected++
-
-			if (this.options.collectMetrics) {
-				metrics.errors.inc({ category: 'circuit_breaker', code: 'rejected' })
-			}
-
-			return this.options.fallback() as T
-		}
-
-		try {
-			const result = operation()
-			this.recordSuccess()
-			return result
-		} catch (error) {
-			this.recordFailure(error as Error)
-			throw error
-		}
-	}
-
-	/**
-	 * Execute operation with timeout wrapper
-	 */
-	private async executeWithTimeout<T>(operation: () => T | Promise<T>): Promise<T> {
-		return new Promise<T>((resolve, reject) => {
-			const timer = setTimeout(() => {
-				reject(new CircuitTimeoutError(this.options.name, this.options.timeout))
-			}, this.options.timeout)
-
-			Promise.resolve(operation())
-				.then(result => {
-					clearTimeout(timer)
-					resolve(result)
-				})
-				.catch(error => {
-					clearTimeout(timer)
-					reject(error)
-				})
-		})
-	}
-
-	/**
-	 * Record a successful operation
-	 */
-	private recordSuccess(): void {
-		this.totalSuccesses++
-		this.lastSuccessTime = Date.now()
-		this.consecutiveSuccesses++
-		this.consecutiveFailures = 0
-
-		if (this.options.collectMetrics) {
-			metrics.socketEvents.inc({ event: 'circuit_success' })
-		}
-
-		this.options.onSuccess()
-		this.emit('success')
-
-		// In HALF_OPEN state, check if we can close the circuit
-		if (this.state === 'half-open') {
-			if (this.consecutiveSuccesses >= this.options.successThreshold) {
-				this.transitionTo('closed')
-			}
-		}
-	}
-
-	/**
-	 * Record a failed operation
-	 */
-	private recordFailure(error: Error): void {
-		// Check if this error should count as a failure
-		if (!this.options.shouldCountError(error)) {
-			return
-		}
-
-		const now = Date.now()
-		this.totalFailures++
-		this.lastFailureTime = now
-		this.consecutiveFailures++
-		this.consecutiveSuccesses = 0
-
-		// Add to failure records for sliding window
-		this.failureRecords.push({ timestamp: now, error })
-
-		// Clean old failures outside the window
-		this.cleanOldFailures()
-
-		if (this.options.collectMetrics) {
-			metrics.errors.inc({ category: 'circuit_breaker', code: 'failure' })
-		}
-
-		this.options.onFailure(error)
-		this.emit('failure', error)
-
-		// State transition logic
-		if (this.state === 'half-open') {
-			// Any failure in HALF_OPEN immediately reopens the circuit
-			this.transitionTo('open')
-		} else if (this.state === 'closed') {
-			// Check if we should trip the circuit
-			const recentFailures = this.failureRecords.length
-
-			if (this.totalCalls >= this.options.volumeThreshold && recentFailures >= this.options.failureThreshold) {
-				this.transitionTo('open')
-			}
-		}
-	}
-
-	/**
-	 * Remove failure records outside the sliding window
-	 */
-	private cleanOldFailures(): void {
-		const cutoff = Date.now() - this.options.failureWindow
-		this.failureRecords = this.failureRecords.filter(record => record.timestamp > cutoff)
-	}
-
-	/**
-	 * Transition to a new state
-	 */
-	private transitionTo(newState: CircuitState): void {
-		const oldState = this.state
-
-		if (oldState === newState) {
-			return
-		}
-
-		this.state = newState
-		this.lastStateChange = Date.now()
-
-		// Clear existing reset timer
-		if (this.resetTimer) {
-			clearTimeout(this.resetTimer)
-			this.resetTimer = undefined
-		}
-
-		// State-specific actions
-		switch (newState) {
-			case 'closed':
-				this.consecutiveFailures = 0
-				this.consecutiveSuccesses = 0
-				this.failureRecords = []
-				this.options.onClose()
-				this.emit('close')
-				break
-
-			case 'open':
-				this.consecutiveSuccesses = 0
-				this.options.onOpen()
-				this.emit('open')
-
-				// Record circuit breaker trip metric
-				if (this.options.collectMetrics) {
-					metrics.circuitBreakerTrips?.inc({ name: this.options.name })
-				}
-
-				// Schedule transition to HALF_OPEN
-				this.resetTimer = setTimeout(() => {
-					this.transitionTo('half-open')
-				}, this.options.resetTimeout)
-				break
-
-			case 'half-open':
-				this.consecutiveSuccesses = 0
-				this.consecutiveFailures = 0
-				this.options.onHalfOpen()
-				this.emit('half-open')
-				break
-		}
-
-		this.options.onStateChange(oldState, newState)
-		this.emit('state-change', { from: oldState, to: newState })
-	}
-
-	/**
-	 * Manually trip the circuit to OPEN state
-	 */
-	trip(): void {
-		this.transitionTo('open')
-	}
-
-	/**
-	 * Manually reset the circuit to CLOSED state
-	 */
-	reset(): void {
-		this.transitionTo('closed')
-	}
-
-	/**
-	 * Get current circuit state
-	 */
-	getState(): CircuitState {
-		return this.state
-	}
-
-	/**
-	 * Check if circuit is OPEN
-	 */
-	isOpen(): boolean {
-		return this.state === 'open'
-	}
-
-	/**
-	 * Check if circuit is CLOSED
-	 */
-	isClosed(): boolean {
-		return this.state === 'closed'
-	}
-
-	/**
-	 * Check if circuit is HALF_OPEN
-	 */
-	isHalfOpen(): boolean {
-		return this.state === 'half-open'
-	}
-
-	/**
-	 * Get circuit breaker statistics
-	 */
-	getStats(): CircuitBreakerStats {
-		this.cleanOldFailures()
-
-		const failureRate = this.totalCalls > 0 ? (this.totalFailures / this.totalCalls) * 100 : 0
-
-		return {
-			state: this.state,
-			failures: this.failureRecords.length,
-			successes: this.consecutiveSuccesses,
-			consecutiveFailures: this.consecutiveFailures,
-			consecutiveSuccesses: this.consecutiveSuccesses,
-			totalCalls: this.totalCalls,
-			totalFailures: this.totalFailures,
-			totalSuccesses: this.totalSuccesses,
-			totalRejected: this.totalRejected,
-			failureRate,
-			lastFailureTime: this.lastFailureTime,
-			lastSuccessTime: this.lastSuccessTime,
-			lastStateChange: this.lastStateChange,
-			isOpen: this.isOpen(),
-			isClosed: this.isClosed(),
-			isHalfOpen: this.isHalfOpen()
-		}
-	}
-
-	/**
-	 * Get circuit breaker name
-	 */
-	getName(): string {
-		return this.options.name
-	}
-
-	/**
-	 * Destroy circuit breaker and clean up resources
-	 */
-	destroy(): void {
-		if (this.resetTimer) {
-			clearTimeout(this.resetTimer)
-		}
-
-		this.failureRecords = []
-		this.removeAllListeners()
-	}
-}
-
-/**
- * Factory function to create a circuit breaker
- */
-export function createCircuitBreaker(options: CircuitBreakerOptions): CircuitBreaker {
-	return new CircuitBreaker(options)
-}
-
-/**
- * Registry for managing multiple circuit breakers
- */
-export class CircuitBreakerRegistry {
-	private breakers: Map<string, CircuitBreaker> = new Map()
-
-	/**
-	 * Get or create a circuit breaker by name
-	 */
-	get(name: string, options?: Omit<CircuitBreakerOptions, 'name'>): CircuitBreaker {
-		if (!this.breakers.has(name)) {
-			const breaker = new CircuitBreaker({ ...options, name })
-			this.breakers.set(name, breaker)
-		}
-
-		return this.breakers.get(name)!
-	}
-
-	/**
-	 * Check if a circuit breaker exists
-	 */
-	has(name: string): boolean {
-		return this.breakers.has(name)
-	}
-
-	/**
-	 * Remove a circuit breaker
-	 */
-	remove(name: string): boolean {
-		const breaker = this.breakers.get(name)
-		if (breaker) {
-			breaker.destroy()
-			return this.breakers.delete(name)
-		}
-
-		return false
-	}
-
-	/**
-	 * Get all circuit breakers
-	 */
-	getAll(): Map<string, CircuitBreaker> {
-		return new Map(this.breakers)
-	}
-
-	/**
-	 * Get statistics for all circuit breakers
-	 */
-	getAllStats(): Record<string, CircuitBreakerStats> {
-		const stats: Record<string, CircuitBreakerStats> = {}
-		for (const [name, breaker] of this.breakers) {
-			stats[name] = breaker.getStats()
-		}
-
-		return stats
-	}
-
-	/**
-	 * Reset all circuit breakers to CLOSED state
-	 */
-	resetAll(): void {
-		for (const breaker of this.breakers.values()) {
-			breaker.reset()
-		}
-	}
-
-	/**
-	 * Destroy all circuit breakers
-	 */
-	destroyAll(): void {
-		for (const breaker of this.breakers.values()) {
-			breaker.destroy()
-		}
-
-		this.breakers.clear()
-	}
-}
-
-/**
- * Global circuit breaker registry instance
- */
-export const globalCircuitRegistry = new CircuitBreakerRegistry()
-
-/**
- * Decorator to protect a method with circuit breaker
- *
- * @example
- * ```typescript
- * class MyService {
- *   @circuitBreaker({ failureThreshold: 3 })
- *   async fetchData() {
- *     return await api.getData()
- *   }
- * }
- * ```
- */
-export function circuitBreaker(options: Omit<CircuitBreakerOptions, 'name'> & { name?: string } = {}) {
-	return function (
-		_target: unknown,
-		propertyKey: string,
-		descriptor: TypedPropertyDescriptor<(...args: unknown[]) => unknown>
-	) {
-		const originalMethod = descriptor.value
-		if (!originalMethod) return descriptor
-
-		const name = options.name || propertyKey
-		const breaker = globalCircuitRegistry.get(name, options)
-
-		descriptor.value = async function (...args: unknown[]): Promise<unknown> {
-			return breaker.execute(() => originalMethod.apply(this, args))
-		}
-
-		return descriptor
-	}
-}
-
-/**
- * Wrap a function with circuit breaker protection
- *
- * @example
- * ```typescript
- * const protectedFetch = withCircuitBreaker(
- *   fetchData,
- *   { name: 'api-fetch', failureThreshold: 5 }
- * )
- * ```
- */
-// eslint-disable-next-line space-before-function-paren
-export function withCircuitBreaker<T extends (...args: unknown[]) => unknown>(
-	fn: T,
-	options: CircuitBreakerOptions
-): T {
-	const breaker = new CircuitBreaker(options)
-
-	return (async (...args: Parameters<T>): Promise<ReturnType<T>> => {
-		return breaker.execute(() => fn(...args)) as Promise<ReturnType<T>>
-	}) as unknown as T
-}
-
-/**
- * Get health status of all circuit breakers
- */
-export function getCircuitHealth(): {
-	healthy: boolean
-	openCircuits: string[]
-	stats: Record<string, CircuitBreakerStats>
-} {
-	const stats = globalCircuitRegistry.getAllStats()
-	const openCircuits: string[] = []
-
-	for (const [name, stat] of Object.entries(stats)) {
-		if (stat.isOpen) {
-			openCircuits.push(name)
-		}
-	}
-
-	return {
-		healthy: openCircuits.length === 0,
-		openCircuits,
-		stats
-	}
-}
-
-/**
- * Create a pre-configured circuit breaker for WhatsApp PreKey operations
- *
- * This circuit breaker is optimized for handling encryption/session errors
- * that commonly occur with WhatsApp's Signal protocol implementation.
- *
- * @example
- * ```typescript
- * const preKeyBreaker = createPreKeyCircuitBreaker()
- *
- * async function sendEncryptedMessage(msg) {
- *   return preKeyBreaker.execute(async () => {
- *     return await encryptAndSend(msg)
- *   })
- * }
- * ```
- */
-export function createPreKeyCircuitBreaker(customOptions?: Partial<CircuitBreakerOptions>): CircuitBreaker {
-	const preKeyErrorPatterns = ['prekey', 'pre-key', 'session', 'signal', 'encrypt', 'decrypt', 'cipher', 'key']
-
-	return new CircuitBreaker({
-		name: 'prekey-operations',
-		failureThreshold: 5,
-		failureWindow: 60000,
-		resetTimeout: 30000,
-		successThreshold: 2,
-		shouldCountError: (error: Error) => {
-			const message = error.message.toLowerCase()
-			return preKeyErrorPatterns.some(pattern => message.includes(pattern))
-		},
-		...customOptions
-	})
-}
-
-/**
- * Create a circuit breaker for WebSocket connection operations
- */
-export function createConnectionCircuitBreaker(customOptions?: Partial<CircuitBreakerOptions>): CircuitBreaker {
-	const connectionErrorPatterns = [
-		'econnrefused',
-		'econnreset',
-		'etimedout',
-		'enotfound',
-		'socket',
-		'websocket',
-		'connection',
-		'network'
-	]
-
-	// Normal WS lifecycle status codes that must NEVER trip the query circuit breaker.
-	// These are transient events that happen on every reconnect and carry no information
-	// about persistent server-side failures.  The reconnection logic in makeSocket handles
-	// them independently.
-	const WS_LIFECYCLE_STATUS_CODES = new Set([
-		428, // connectionClosed
-		408, // connectionLost / timedOut
-		440, // connectionReplaced
-	])
-
-	return new CircuitBreaker({
-		name: 'connection-operations',
-		failureThreshold: 3,
-		failureWindow: 30000,
-		resetTimeout: 60000,
-		successThreshold: 1,
-		shouldCountError: (error: Error) => {
-			// CircuitTimeoutError messages embed the circuit name (e.g. "socket-query"), which
-			// accidentally matches the "socket" pattern below and causes a self-reinforcing loop
-			// where the breaker's own timeouts keep tripping the breaker. Exclude them explicitly.
-			if (error instanceof CircuitTimeoutError) return false
-
-			// Exclude normal WS reconnect events (Connection Closed, Connection Lost, Timed Out, etc.).
-			// These are not server-side failures — they happen on every restart/redeploy and should
-			// never cause the circuit to open.  If we counted them, the 3 concurrent parallel
-			// post-login queries (sendPassiveIq, uploadPreKeysToServerIfRequired, digestKeyBundle) could all
-			// fail simultaneously when the WS drops, instantly opening the circuit and blocking
-			// profile-picture fetches and message delivery for the next 30 s.
-			const statusCode = (error as { output?: { statusCode?: number } })?.output?.statusCode
-			if (statusCode !== undefined && WS_LIFECYCLE_STATUS_CODES.has(statusCode)) return false
-
-			const message = error.message.toLowerCase()
-			const code = (error as NodeJS.ErrnoException).code?.toLowerCase() || ''
-			return connectionErrorPatterns.some(pattern => message.includes(pattern) || code.includes(pattern))
-		},
-		...customOptions
-	})
-}
-
-/**
- * Create a circuit breaker for message sending operations
- */
-export function createMessageCircuitBreaker(customOptions?: Partial<CircuitBreakerOptions>): CircuitBreaker {
-	return new CircuitBreaker({
-		name: 'message-operations',
-		failureThreshold: 5,
-		failureWindow: 60000,
-		resetTimeout: 15000,
-		successThreshold: 2,
-		timeout: 30000,
-		...customOptions
-	})
-}
-
-export default CircuitBreaker

src/Utils/decode-wa-message.ts

@@ -58,7 +58,11 @@ export const BAD_MAC_ERROR_TEXT = 'Bad MAC'
 export const DECRYPTION_RETRY_CONFIG = {
 	maxRetries: 3,
 	baseDelayMs: 100,
-	sessionRecordErrors: ['No session record', 'SessionError: No session record'],
+	// 'No matching sessions found' is the libsignal error when decryptWithSessions exhausts
+	// all stored sessions for a JID. Same recovery flow (retry receipt → pkmsg → new session)
+	// — categorise it as session-record so the caller logs DEBUG on retry, ERROR only when
+	// retries are exhausted (instead of dumping the full stack as an unknown error).
+	sessionRecordErrors: ['No session record', 'SessionError: No session record', 'No matching sessions found'],
 	corruptedSessionErrors: ['Bad MAC', 'MessageCounterError', MISSING_KEYS_ERROR_TEXT]
 }
 
@@ -421,9 +425,26 @@ export const decryptMessageNode = (
 						const isCorrupted = isCorruptedSessionError(originalError)
 						const isSessionRecord = isSessionRecordError(originalError)
 
+						// Slim error projection — keep name/message/type for diagnosis,
+						// drop `stack` which adds 4-5 lines of node_modules paths per log
+						// for known-recoverable libsignal errors.
+						//
+						// CRITICAL: only slim for KNOWN-RECOVERABLE categories (corrupted /
+						// session-record). The unknown-error branch keeps the full Error so
+						// protobuf/parsing/runtime bugs still emit a stack trace where it
+						// matters most. Catches Copilot/Codex P2 review on PR #391.
+						const slimErr = originalError
+							? {
+									name: (originalError as { name?: string }).name,
+									message: (originalError as { message?: string }).message,
+									type: (originalError as { type?: string }).type
+								}
+							: undefined
+						const isRecoverableCategory = isCorrupted || isSessionRecord
+
 						const errorContext = {
 							key: fullMessage.key,
-							err: originalError,
+							err: isRecoverableCategory ? slimErr : originalError,
 							messageType: tag === 'plaintext' ? 'plaintext' : attrs.type,
 							sender,
 							author,

src/Utils/health-status.ts

@@ -6,11 +6,12 @@
  * @module Utils/health-status
  */
 
-import { globalCircuitRegistry } from './circuit-breaker.js'
 import { getVersionCacheStatus } from './version-cache.js'
 
 /**
- * Circuit breaker health information
+ * Circuit breaker health information (kept for k8s probe schema stability —
+ * always reports an empty list now that circuit breakers were removed in
+ * favour of bounded-retry).
  */
 export interface CircuitBreakerHealth {
 	name: string
@@ -105,44 +106,10 @@ export function getHealthStatus(): HealthStatus {
 		})
 	}
 
-	// 2. Check circuit breakers
+	// 2. Circuit breakers were removed in favour of bounded-retry.
+	// Keep the field for backward-compat with k8s probe schema, always empty.
 	const circuitBreakers: CircuitBreakerHealth[] = []
-	let openCircuits = 0
+	checks.push({ name: 'circuit_breakers', status: 'pass' })
-
-	for (const [name, breaker] of globalCircuitRegistry.getAll()) {
-		const stats = breaker.getStats()
-		const state = breaker.getState()
-
-		circuitBreakers.push({
-			name,
-			state,
-			failures: stats.totalFailures,
-			successes: stats.totalSuccesses,
-			totalCalls: stats.totalCalls
-		})
-
-		if (state === 'open') {
-			openCircuits++
-		}
-	}
-
-	if (openCircuits > 0) {
-		checks.push({
-			name: 'circuit_breakers',
-			status: openCircuits > 2 ? 'fail' : 'warn',
-			message: `${openCircuits} circuit breaker(s) are open`
-		})
-		if (openCircuits > 2) {
-			overallStatus = 'unhealthy'
-		} else if (overallStatus === 'healthy') {
-			overallStatus = 'degraded'
-		}
-	} else {
-		checks.push({
-			name: 'circuit_breakers',
-			status: 'pass'
-		})
-	}
 
 	// 3. Check memory usage (warn if > 90%)
 	const memUsage = process.memoryUsage()

src/Utils/history.ts

@@ -1,5 +1,6 @@
+import { pipeline } from 'stream/promises'
 import { promisify } from 'util'
-import { inflate } from 'zlib'
+import { createInflate, inflate } from 'zlib'
 import { proto } from '../../WAProto/index.js'
 import type { Chat, Contact, LIDMapping, WAMessage } from '../Types'
 import { WAMessageStubType } from '../Types'
@@ -29,16 +30,15 @@ const inflatePromise = promisify(inflate)
  */
 export const downloadHistory = async (msg: proto.Message.IHistorySyncNotification, options: RequestInit) => {
 	const stream = await downloadContentFromMessage(msg, 'md-msg-hist', { options })
-	const bufferArray: Buffer[] = []
+	// Pipe decrypted stream directly through zlib inflate.
-	for await (const chunk of stream) {
+	// Avoids allocating an intermediate buffer for the compressed payload —
-		bufferArray.push(chunk)
+	// memory peaks during 50MB history syncs drop ~50% (PR upstream #2333).
-	}
+	const inflater = createInflate()
-
+	const chunks: Buffer[] = []
-	let buffer: Buffer = Buffer.concat(bufferArray)
+	inflater.on('data', (chunk: Buffer) => chunks.push(chunk))
-
+	await pipeline(stream, inflater)
-	// decompress buffer
-	buffer = await inflatePromise(buffer)
 
+	const buffer = Buffer.concat(chunks)
 	const syncData = proto.HistorySync.decode(buffer)
 	return syncData
 }
@@ -361,7 +361,7 @@ export const processHistoryMessage = (item: proto.IHistorySync, logger?: ILogger
 					}
 				}
 
-				chats.push({ ...chat })
+				chats.push(chat)
 			}
 
 			break

src/Utils/identity-change-handler.ts

@@ -57,6 +57,16 @@ export type IdentityChangeContext = {
 	debounceCache: NodeCache<boolean>
 	/** Logger instance for debugging and monitoring */
 	logger: ILogger
+	/**
+	 * Invoked right before `assertSessions` is called for an existing-session identity
+	 * change. Used to kick off fire-and-forget side effects (e.g. tctoken re-issuance)
+	 * in the same order WA Web does — i.e. before the E2E session is re-established.
+	 * Must not throw; implementations are responsible for their own error handling.
+	 *
+	 * Skipped when the refresh itself is skipped (no_identity_node, invalid_notification,
+	 * skipped_companion_device, skipped_self_primary, debounced, skipped_offline).
+	 */
+	onBeforeSessionRefresh?: (jid: string) => void
 }
 
 // ============================================================================
@@ -170,6 +180,19 @@ export async function handleIdentityChange(
 	// This ensures we don't incorrectly debounce when we exit early (offline, etc.)
 	ctx.debounceCache.set(from, true)
 
+	// Fire-and-forget side effects (e.g. tctoken re-issuance) BEFORE the session is
+	// re-established. WA Web runs these in parallel with the session refresh —
+	// running afterwards would race with the next outbound send and risk error 463.
+	//
+	// Wrapped in try/catch so a misbehaving consumer callback cannot abort identity
+	// change recovery. We log and continue — assertSessions still runs so the E2E
+	// session always gets refreshed.
+	try {
+		ctx.onBeforeSessionRefresh?.(from)
+	} catch (error) {
+		ctx.logger.warn({ error, jid: from }, 'onBeforeSessionRefresh callback threw — continuing with session refresh')
+	}
+
 	// Attempt session refresh/creation
 	try {
 		await ctx.assertSessions([from], true)

src/Utils/index.ts

@@ -33,8 +33,8 @@ export * from './trace-context'
 export * from './prometheus-metrics'
 
 // Resilience and performance
+export * from './bounded-retry'
 export * from './cache-utils'
-export * from './circuit-breaker'
 export * from './retry-utils'
 
 // Telemetry and detection mitigation

src/Utils/messages-media.ts

@@ -618,7 +618,7 @@ export const downloadEncryptedContent = async (
 
 	const output = new Transform({
 		transform(chunk, _, callback) {
-			let data = Buffer.concat([remainingBytes, chunk])
+			let data = remainingBytes.length ? Buffer.concat([remainingBytes, chunk]) : chunk
 
 			const decryptLength = toSmallestChunkSize(data.length)
 			remainingBytes = data.slice(decryptLength)

src/Utils/process-message.ts

@@ -40,6 +40,7 @@ import { getKeyAuthor, toNumber } from './generics'
 import { downloadAndProcessHistorySyncNotification } from './history'
 import type { ILogger } from './logger'
 import { metrics, recordHistorySyncMessages } from './prometheus-metrics.js'
+import { buildMergedTcTokenIndexWrite } from './tc-token-utils'
 
 type ProcessMessageContext = {
 	shouldProcessHistoryMsg: boolean
@@ -62,6 +63,163 @@ const REAL_MSG_STUB_TYPES = new Set([
 
 const REAL_MSG_REQ_ME_STUB_TYPES = new Set([WAMessageStubType.GROUP_PARTICIPANT_ADD])
 
+/**
+ * Extract tctoken / tcTokenTimestamp / tcTokenSenderTimestamp from history-sync chats
+ * and persist them to the `tctoken` store. Mirrors WA Web's `bulkCreateOrMerge` pass
+ * over the chat table during history sync.
+ *
+ * Why this matters: when a user logs in on a new device, the multi-device history sync
+ * is the only way that device learns about tctokens issued/received on the original
+ * device. Without this pass, the new device sends 1:1 messages with no tctoken until
+ * the contact triggers a fresh notification — which surfaces as error 463 in production.
+ *
+ * Monotonicity: we only overwrite an existing entry if the incoming timestamp is
+ * STRICTLY newer (`incoming > existing`). Equal timestamps are skipped to avoid
+ * reverting senderTimestamp / realIssueTimestamp set by other layers (e.g. a
+ * reissue that fired between history-sync chunks).
+ *
+ * Index hygiene: every JID we write here is added to the persistent prune index
+ * (TC_TOKEN_INDEX_KEY) via buildMergedTcTokenIndexWrite, so the 24h prune sweep in
+ * messages-recv picks them up across sessions.
+ */
+/**
+ * Single-concurrency queue for `storeTcTokensFromHistorySync` calls.
+ *
+ * Why: the function does read-then-write merges (`keyStore.get('tctoken', ...)` →
+ * compute → `keyStore.set(...)`) which are NOT atomic at the store level. If two
+ * history-sync chunks invoke this concurrently (common during reconnect / QR
+ * scan), an older chunk that started first can `keyStore.set` AFTER a newer
+ * chunk, overwriting the newer entry — and worse, the merged `__index` write
+ * can drop JIDs the other chunk just added. Result: stale tcTokens / repeat 463
+ * sends until the next opportunistic refetch.
+ *
+ * Serialising via a chained Promise keeps the runs ordered while still freeing
+ * the calling `processMessage` to emit `messaging-history.set` immediately
+ * (the chain is fire-and-forget at the call site). Errors don't break the chain
+ * — each `catch` resets it to `Promise.resolve()` so a single failure can't
+ * stall future runs.
+ *
+ * The chain is module-scoped (one per Node process). Multiple Baileys instances
+ * sharing this module will serialise across instances too, but their writes
+ * target different keyStores so there's no correctness gain — only a tiny loss
+ * of inter-instance parallelism for tcToken syncs, which is acceptable given
+ * how rarely this runs vs. how rare cross-instance contention is.
+ */
+let historyTcTokenChain: Promise<void> = Promise.resolve()
+
+function scheduleHistoryTcTokenSync(
+	chats: Chat[],
+	signalRepository: SignalRepositoryWithLIDStore,
+	keyStore: SignalKeyStoreWithTransaction,
+	logger?: ILogger
+): void {
+	historyTcTokenChain = historyTcTokenChain
+		.catch(() => {
+			/* swallow prior error so chain stays alive */
+		})
+		.then(() => storeTcTokensFromHistorySync(chats, signalRepository, keyStore, logger))
+		.catch(err => {
+			logger?.warn({ err }, 'background tctoken history-sync persistence failed')
+		})
+}
+
+async function storeTcTokensFromHistorySync(
+	chats: Chat[],
+	signalRepository: SignalRepositoryWithLIDStore,
+	keyStore: SignalKeyStoreWithTransaction,
+	logger?: ILogger
+) {
+	// Cheap filter first — most chats in a sync chunk don't carry tcToken at all,
+	// and we want to avoid spinning up promises for them.
+	const tokenChats = chats.filter(chat => {
+		const ts = chat.tcTokenTimestamp ? toNumber(chat.tcTokenTimestamp) : 0
+		return !!chat.tcToken?.length && ts > 0
+	})
+
+	if (!tokenChats.length) {
+		return
+	}
+
+	// Pre-normalize so the rest of the pipeline is a synchronous join.
+	const normalized = tokenChats.map(chat => ({
+		chat,
+		ts: toNumber(chat.tcTokenTimestamp!),
+		jid: jidNormalizedUser(chat.id!)
+	}))
+
+	// BATCHED LID resolution. The previous shape called getLIDForPN once per
+	// chat (sequential await inside a for-of), which became the bottleneck
+	// during heavy history sync — every cold-cache hit was a DB round-trip,
+	// stalling messaging-history.set and spilling into the event-buffer.
+	// `getLIDsForPNs` resolves a deduped list in ONE batched query (and shares
+	// USync retry across PNs that miss cache), turning O(N) round-trips into 1.
+	//
+	// LID inputs (and `@hosted.lid`) skip the lookup entirely — they're already
+	// the storage form. Failures degrade gracefully: a missing mapping just
+	// stores under the original jid, matching `resolveTcTokenJid`'s null branch.
+	const pnsToResolve = [...new Set(normalized.filter(({ jid }) => !isLidUser(jid)).map(({ jid }) => jid))]
+	const pnToLid = new Map<string, string>()
+
+	if (pnsToResolve.length) {
+		try {
+			const mappings = await signalRepository.lidMapping.getLIDsForPNs(pnsToResolve)
+			// Flat loop (continue-on-skip) keeps max nesting depth at 4 for lint.
+			for (const { pn, lid } of mappings ?? []) {
+				if (!pn || !lid) continue
+				pnToLid.set(jidNormalizedUser(pn), lid)
+			}
+		} catch (err) {
+			// Per-chat fallback below (storageJid := jid). Don't abort the chunk —
+			// CodeRabbit noted that all-or-nothing rejection here would drop every
+			// tctoken in the batch AND prevent messaging-history.set from firing.
+			logger?.warn({ err }, 'storeTcTokensFromHistorySync: getLIDsForPNs batch failed; falling back to per-chat jid')
+		}
+	}
+
+	const candidates = normalized.map(({ chat, ts, jid }) => ({
+		storageJid: pnToLid.get(jid) ?? jid,
+		token: Buffer.from(chat.tcToken!),
+		ts,
+		senderTs: chat.tcTokenSenderTimestamp ? toNumber(chat.tcTokenSenderTimestamp) : undefined
+	}))
+
+	const jids = candidates.map(c => c.storageJid)
+	const existing = await keyStore.get('tctoken', jids)
+	const entries: Record<string, { token: Buffer; timestamp?: string; senderTimestamp?: number }> = {}
+
+	for (const c of candidates) {
+		// Same-batch dedup: when two chats resolve to the same storageJid (e.g. PN+LID
+		// aliases collapsing through resolveTcTokenJid, or duplicate chunks across
+		// retries), prefer the value already written by an earlier iteration so a
+		// lower-ts entry can't overwrite a higher-ts one captured from `existing`.
+		const existingEntry = entries[c.storageJid] ?? existing[c.storageJid]
+		const existingTs = existingEntry?.timestamp ? Number(existingEntry.timestamp) : 0
+		// Strict > guard: equal timestamps are skipped so we never clobber
+		// senderTimestamp written by other layers (issuance after send, etc).
+		if (existingTs > 0 && existingTs >= c.ts) {
+			continue
+		}
+
+		entries[c.storageJid] = {
+			...existingEntry,
+			token: c.token,
+			timestamp: String(c.ts),
+			...(c.senderTs !== undefined ? { senderTimestamp: c.senderTs } : {})
+		}
+	}
+
+	if (Object.keys(entries).length) {
+		logger?.debug({ count: Object.keys(entries).length }, 'storing tctokens from history sync')
+		try {
+			// Include updated __index so cross-session pruning picks these JIDs up.
+			const indexWrite = await buildMergedTcTokenIndexWrite(keyStore, Object.keys(entries))
+			await keyStore.set({ tctoken: { ...entries, ...indexWrite } })
+		} catch (err) {
+			logger?.warn({ err }, 'failed to store tctokens from history sync')
+		}
+	}
+}
+
 /** Cleans a received message to further processing */
 export const cleanMessage = (message: WAMessage, meId: string, meLid: string) => {
 	// ensure remoteJid and participant doesn't have device or agent in it
@@ -418,6 +576,12 @@ const processMessage = async (
 
 					// Emit LID-PN mappings from history sync
 					// This is how WhatsApp Web learns mappings for chats with non-contacts
+					//
+					// MUST run BEFORE storeTcTokensFromHistorySync — otherwise resolveTcTokenJid()
+					// can't resolve PN→LID for fresh-device chats (mapping cache is empty), tokens
+					// get persisted under PN keys, and the send path (which resolves to LID first)
+					// misses them — exactly the error 463 scenario this whole change is meant to
+					// prevent. Catches Codex P1 review on PR #386.
 					if (data.lidPnMappings?.length) {
 						logger?.debug({ count: data.lidPnMappings.length }, 'processing LID-PN mappings from history sync')
 						// eslint-disable-next-line max-depth
@@ -442,6 +606,29 @@ const processMessage = async (
 						}
 					}
 
+					// Persist tctokens carried by history-sync chats in BACKGROUND, serialised.
+					//
+					// Originally awaited (PR #386) to avoid 463 on first multi-device send, but in
+					// production this drained the event buffer per-chunk and added visible delivery
+					// latency (especially after restart / QR scan when many chunks arrived at once).
+					//
+					// `scheduleHistoryTcTokenSync` enqueues onto a single-concurrency promise chain
+					// (see definition above) — chunks persist sequentially in the order they were
+					// emitted, preserving timestamp monotonicity AND keeping the `__index` write
+					// safe from concurrent merge clobbers. The call returns immediately so the
+					// `messaging-history.set` emit is not blocked.
+					//
+					// TRADE-OFF: a listener that fires an outbound send IMMEDIATELY after the emit
+					// may race the still-pending persistence and get a 463 on that specific send.
+					// The existing 463 handler in messages-recv.ts triggers a getPrivacyTokens()
+					// refetch that auto-recovers within seconds. Net result is much better UX than
+					// per-chunk stalls.
+					//
+					// DO NOT add `await` back here without re-evaluating production latency, AND
+					// DO NOT call storeTcTokensFromHistorySync directly — it must go through the
+					// chain to preserve write ordering across overlapping chunks.
+					scheduleHistoryTcTokenSync(data.chats, signalRepository, keyStore, logger)
+
 					ev.emit('messaging-history.set', {
 						...data,
 						isLatest: histNotification.syncType !== proto.HistorySync.HistorySyncType.ON_DEMAND ? isLatest : undefined,

src/Utils/prometheus-metrics.ts

@@ -1570,26 +1570,6 @@ export const metrics = {
 		new Counter('socket_reconnects_total', 'Total socket reconnection attempts', ['reason'])
 	),
 
-	// ========== Circuit Breaker Metrics ==========
-	circuitBreakerState: baileysMetrics.register(
-		new Gauge('circuit_breaker_state', 'Circuit breaker state (0=closed, 1=open, 2=half-open)', ['name'])
-	),
-	circuitBreakerTrips: baileysMetrics.register(
-		new Counter('circuit_breaker_trips_total', 'Total circuit breaker trips', ['name'])
-	),
-	circuitBreakerRecoveries: baileysMetrics.register(
-		new Counter('circuit_breaker_recoveries_total', 'Total circuit breaker recoveries', ['name'])
-	),
-	circuitBreakerRejections: baileysMetrics.register(
-		new Counter('circuit_breaker_rejections_total', 'Total requests rejected by circuit breaker', ['name'])
-	),
-	circuitBreakerSuccesses: baileysMetrics.register(
-		new Counter('circuit_breaker_successes_total', 'Total successful requests through circuit breaker', ['name'])
-	),
-	circuitBreakerFailures: baileysMetrics.register(
-		new Counter('circuit_breaker_failures_total', 'Total failed requests through circuit breaker', ['name'])
-	),
-
 	// ========== Encryption Metrics ==========
 	encryptionOperations: baileysMetrics.register(
 		new Counter('encryption_operations_total', 'Total encryption operations', ['operation'])
@@ -2167,9 +2147,6 @@ function initializeMetricsWithLabels(): void {
 		metrics.messageFailures?.inc({ type: 'text', reason: 'max_retries' }, 0)
 		metrics.messageFailures?.inc({ type: 'other', reason: 'max_retries' }, 0)
 
-		// Circuit breaker metric
-		metrics.circuitBreakerTrips?.inc({ name: 'main' }, 0)
-
 		console.log('[Prometheus] Initialized metrics with labels')
 	} catch (error) {
 		console.error('[Prometheus] Error initializing metrics with labels:', error)

src/Utils/retry-utils.ts

@@ -6,15 +6,21 @@
  * - Jitter to avoid thundering herd
  * - Configurable max attempts
  * - Customizable retry predicates
- * - Circuit breaker integration
+ * - Cancellation support (AbortSignal)
- * - Event hooks
+ *
- * - Cancellation support
+ * Used by `decode-wa-message.ts` for Bad MAC retry recovery on the decrypt
+ * path. For socket-operation retries (uploadPreKeys etc.) prefer
+ * `withBoundedRetry` from `./bounded-retry.ts`, which is empirically
+ * aligned with WhatsApp Android's per-operation backoff.
+ *
+ * NOTE: the previous `circuitBreaker` integration option, the `withRetry`
+ * decorator, the `retryable` wrapper and the `RetryManager` class were
+ * removed when the socket-level circuit breaker was retired — see PR #393
+ * for the rationale.
  *
  * @module Utils/retry-utils
  */
 
-import { EventEmitter } from 'events'
-import type { CircuitBreaker } from './circuit-breaker.js'
 import { metrics } from './prometheus-metrics.js'
 
 /**
@@ -59,8 +65,6 @@ export interface RetryOptions {
 	operationName?: string
 	/** Collect metrics */
 	collectMetrics?: boolean
-	/** Circuit breaker for integration */
-	circuitBreaker?: CircuitBreaker
 	/** Callback before each retry */
 	onRetry?: (error: Error, attempt: number, delay: number) => void | Promise<void>
 	/** Callback on success */
@@ -283,7 +287,6 @@ export async function retry<T>(
 		timeout: options.timeout,
 		operationName: options.operationName ?? 'operation',
 		collectMetrics: options.collectMetrics ?? true,
-		circuitBreaker: options.circuitBreaker,
 		onRetry: options.onRetry ?? (() => {}),
 		onSuccess: options.onSuccess ?? (() => {}),
 		onFailure: options.onFailure ?? (() => {}),
@@ -313,11 +316,6 @@ export async function retry<T>(
 			throw new RetryAbortedError(attempt)
 		}
 
-		// Check circuit breaker
-		if (config.circuitBreaker?.isOpen()) {
-			throw new Error(`Circuit breaker "${config.circuitBreaker.getName()}" is open`)
-		}
-
 		try {
 			// Execute operation
 			let result: T
@@ -425,138 +423,6 @@ export function createRetrier(defaultOptions: RetryOptions = {}) {
 	}
 }
 
-/**
- * Decorator to add retry to method
- */
-export function withRetry(options: RetryOptions = {}) {
-	return function (
-		_target: unknown,
-		propertyKey: string,
-		descriptor: TypedPropertyDescriptor<(...args: unknown[]) => unknown>
-	) {
-		const originalMethod = descriptor.value
-		if (!originalMethod) return descriptor
-
-		descriptor.value = async function (...args: unknown[]): Promise<unknown> {
-			return retry(() => originalMethod.apply(this, args), {
-				...options,
-				operationName: options.operationName || propertyKey
-			})
-		}
-
-		return descriptor
-	}
-}
-
-/**
- * Wrapper for function with retry
- */
-// eslint-disable-next-line space-before-function-paren
-export function retryable<T extends (...args: unknown[]) => unknown>(
-	fn: T,
-	options: RetryOptions = {}
-): (...args: Parameters<T>) => Promise<ReturnType<T>> {
-	return async (...args: Parameters<T>): Promise<ReturnType<T>> => {
-		return retry(() => fn(...args), options) as Promise<ReturnType<T>>
-	}
-}
-
-/**
- * Class to manage retries with state
- */
-export class RetryManager extends EventEmitter {
-	private activeRetries: Map<string, { cancel: () => void; context: RetryContext }> = new Map()
-	private defaultOptions: RetryOptions
-
-	constructor(defaultOptions: RetryOptions = {}) {
-		super()
-		this.defaultOptions = defaultOptions
-	}
-
-	/**
-	 * Execute operation with retry
-	 */
-	async execute<T>(
-		id: string,
-		operation: (context: RetryContext) => T | Promise<T>,
-		options?: RetryOptions
-	): Promise<T> {
-		// Cancel previous retry with same ID
-		this.cancel(id)
-
-		const abortController = new AbortController()
-		const mergedOptions = { ...this.defaultOptions, ...options, abortSignal: abortController.signal }
-
-		const retryPromise = retry(context => {
-			this.activeRetries.set(id, {
-				cancel: () => abortController.abort(),
-				context
-			})
-			this.emit('attempt', { id, attempt: context.attempt })
-			return operation(context)
-		}, mergedOptions)
-
-		try {
-			const result = await retryPromise
-			this.emit('success', { id })
-			return result
-		} catch (error) {
-			this.emit('failure', { id, error })
-			throw error
-		} finally {
-			this.activeRetries.delete(id)
-		}
-	}
-
-	/**
-	 * Cancel in-progress retry
-	 */
-	cancel(id: string): boolean {
-		const active = this.activeRetries.get(id)
-		if (active) {
-			active.cancel()
-			this.activeRetries.delete(id)
-			this.emit('cancelled', { id })
-			return true
-		}
-
-		return false
-	}
-
-	/**
-	 * Cancel all retries
-	 */
-	cancelAll(): void {
-		for (const [id, active] of this.activeRetries) {
-			active.cancel()
-			this.emit('cancelled', { id })
-		}
-
-		this.activeRetries.clear()
-	}
-
-	/**
-	 * Check if there is an active retry
-	 */
-	isActive(id: string): boolean {
-		return this.activeRetries.has(id)
-	}
-
-	/**
-	 * Return active retry context
-	 */
-	getContext(id: string): RetryContext | undefined {
-		return this.activeRetries.get(id)?.context
-	}
-
-	/**
-	 * Return active retry IDs
-	 */
-	getActiveIds(): string[] {
-		return Array.from(this.activeRetries.keys())
-	}
-}
-
 /**
  * Common predicates for shouldRetry
  */
@@ -660,9 +526,8 @@ export const retryConfigs = {
 	 * Uses fixed delay array: 1s, 2s, 5s, 10s, 20s (with ±15% jitter)
 	 *
 	 * NOTE: Values are hardcoded instead of referencing RETRY_BACKOFF_DELAYS/RETRY_JITTER_FACTOR
-	 * to prevent "Cannot access before initialization" errors in ESM environments.
+	 * to prevent "Cannot access before initialization" errors in ESM environments
-	 * This occurs when modules are loaded in specific orders due to indirect circular imports
+	 * caused by indirect circular imports through prometheus-metrics.ts.
-	 * (e.g., via prometheus-metrics.ts -> circuit-breaker.ts chain).
 	 * Keep these values in sync with the constants above (lines 25, 31).
 	 */
 	rsocket: {

src/Utils/structured-logger.ts

@@ -6,7 +6,9 @@
  * - Configurable log levels (trace, debug, info, warn, error, fatal)
  * - JSON formatting for log analysis
  * - Hierarchical context with child loggers
- * - External system integration via hooks with circuit breaker
+ * - External system integration via fire-and-forget hooks (failures
+ *   counted in hookFailures metric; no per-hook circuit breaker — chronic
+ *   breakage is visible to operators via the metric)
  * - Logging metrics with Prometheus integration
  * - Sensitive data sanitization
  * - Log buffering for batch writes
@@ -73,10 +75,6 @@ export interface StructuredLoggerConfig {
 	maxLogsPerSecond?: number
 	/** Enable async logging queue (default: false) */
 	enableAsyncQueue?: boolean
-	/** Circuit breaker failure threshold for external hooks (default: 5) */
-	circuitBreakerThreshold?: number
-	/** Circuit breaker reset timeout in ms (default: 30000) */
-	circuitBreakerResetMs?: number
 	/** Enable Prometheus metrics integration (default: false) */
 	enableMetrics?: boolean
 }
@@ -155,8 +153,6 @@ export interface LoggerMetrics {
 	bufferFlushes: number
 	/** External hook failures */
 	hookFailures: number
-	/** Circuit breaker trips */
-	circuitBreakerTrips: number
 	/** Average log processing time in ms */
 	avgProcessingTimeMs: number
 }
@@ -169,8 +165,6 @@ export interface LoggerStatistics extends LoggerMetrics {
 	bufferSize: number
 	/** Rate limiter tokens available */
 	rateLimiterTokens: number
-	/** Circuit breaker state */
-	circuitBreakerState: 'closed' | 'open' | 'half-open'
 	/** Queue size (if async enabled) */
 	queueSize: number
 	/** Created timestamp */
@@ -242,69 +236,6 @@ class RateLimiter {
 	}
 }
 
-// ============================================================================
-// CIRCUIT BREAKER
-// ============================================================================
-
-/**
- * Circuit breaker for external hook protection
- */
-class CircuitBreaker {
-	private failures = 0
-	private lastFailure = 0
-	private state: 'closed' | 'open' | 'half-open' = 'closed'
-
-	constructor(
-		private readonly threshold: number,
-		private readonly resetTimeoutMs: number
-	) {}
-
-	async execute<T>(operation: () => Promise<T>): Promise<T | null> {
-		if (this.state === 'open') {
-			if (Date.now() - this.lastFailure > this.resetTimeoutMs) {
-				this.state = 'half-open'
-			} else {
-				return null // Circuit is open, skip
-			}
-		}
-
-		try {
-			const result = await operation()
-			this.onSuccess()
-			return result
-		} catch (error) {
-			this.onFailure()
-			throw error
-		}
-	}
-
-	private onSuccess(): void {
-		this.failures = 0
-		this.state = 'closed'
-	}
-
-	private onFailure(): void {
-		this.failures++
-		this.lastFailure = Date.now()
-		if (this.failures >= this.threshold) {
-			this.state = 'open'
-		}
-	}
-
-	getState(): 'closed' | 'open' | 'half-open' {
-		// Check if should transition from open to half-open
-		if (this.state === 'open' && Date.now() - this.lastFailure > this.resetTimeoutMs) {
-			this.state = 'half-open'
-		}
-
-		return this.state
-	}
-
-	getFailures(): number {
-		return this.failures
-	}
-}
-
 // ============================================================================
 // ASYNC LOG QUEUE
 // ============================================================================
@@ -403,8 +334,6 @@ export class StructuredLogger implements ILogger {
 	private rateLimiter: RateLimiter | null = null
 
 	// Circuit breaker for external hook
-	private circuitBreaker: CircuitBreaker | null = null
-
 	// Async queue
 	private asyncQueue: AsyncLogQueue | null = null
 
@@ -435,8 +364,6 @@ export class StructuredLogger implements ILogger {
 			enableRateLimiting: config.enableRateLimiting ?? envConfig.enableRateLimiting ?? false,
 			maxLogsPerSecond: config.maxLogsPerSecond ?? envConfig.maxLogsPerSecond ?? 1000,
 			enableAsyncQueue: config.enableAsyncQueue ?? envConfig.enableAsyncQueue ?? false,
-			circuitBreakerThreshold: config.circuitBreakerThreshold ?? 5,
-			circuitBreakerResetMs: config.circuitBreakerResetMs ?? 30000,
 			enableMetrics: config.enableMetrics ?? envConfig.enableMetrics ?? false
 		}
 
@@ -455,7 +382,6 @@ export class StructuredLogger implements ILogger {
 			droppedLogs: 0,
 			bufferFlushes: 0,
 			hookFailures: 0,
-			circuitBreakerTrips: 0,
 			avgProcessingTimeMs: 0
 		}
 
@@ -464,11 +390,6 @@ export class StructuredLogger implements ILogger {
 			this.rateLimiter = new RateLimiter(this.config.maxLogsPerSecond)
 		}
 
-		// Initialize circuit breaker for external hook
-		if (this.config.externalHook) {
-			this.circuitBreaker = new CircuitBreaker(this.config.circuitBreakerThreshold, this.config.circuitBreakerResetMs)
-		}
-
 		// Initialize async queue
 		if (this.config.enableAsyncQueue) {
 			this.asyncQueue = new AsyncLogQueue()
@@ -569,19 +490,27 @@ export class StructuredLogger implements ILogger {
 				this.output(entry)
 			}
 
-			// External hook with circuit breaker
+			// External hook — fire-and-forget. Failures are counted in
+			// hookFailures metric so chronic breakage is visible to operators
+			// who can fix their hook. We do not gate further calls — that is
+			// the consumer's responsibility (consistent with the rest of the
+			// codebase after the circuit-breaker removal).
 			const externalHook = this.config.externalHook
-			if (externalHook && this.circuitBreaker) {
+			if (externalHook) {
-				this.circuitBreaker
+				try {
-					.execute(async () => {
+					const hookResult = externalHook(entry) as unknown
-						await Promise.resolve(externalHook(entry))
+					// Use Promise.resolve().catch() so any thenable (including
-					})
+					// Promise-likes that only implement .then) is handled
-					.catch(() => {
+					// safely — calling .catch directly would throw on such
-						this.metrics.hookFailures++
+					// objects (Copilot review on PR #393).
-						if (this.circuitBreaker?.getState() === 'open') {
+					if (hookResult && typeof (hookResult as PromiseLike<unknown>).then === 'function') {
-							this.metrics.circuitBreakerTrips++
+						void Promise.resolve(hookResult as PromiseLike<unknown>).catch(() => {
-						}
+							this.metrics.hookFailures++
-					})
+						})
+					}
+				} catch {
+					this.metrics.hookFailures++
+				}
 			}
 
 			// Track processing time
@@ -834,7 +763,6 @@ export class StructuredLogger implements ILogger {
 			...this.metrics,
 			bufferSize: this.buffer.length,
 			rateLimiterTokens: this.rateLimiter?.getTokens() ?? 0,
-			circuitBreakerState: this.circuitBreaker?.getState() ?? 'closed',
 			queueSize: this.asyncQueue?.getSize() ?? 0,
 			createdAt: this.createdAt,
 			uptimeMs: Date.now() - this.createdAt
@@ -860,7 +788,6 @@ export class StructuredLogger implements ILogger {
 			droppedLogs: 0,
 			bufferFlushes: 0,
 			hookFailures: 0,
-			circuitBreakerTrips: 0,
 			avgProcessingTimeMs: 0
 		}
 		this.totalProcessingTime = 0
@@ -893,7 +820,6 @@ export class StructuredLogger implements ILogger {
 
 		// Clear references
 		this.rateLimiter = null
-		this.circuitBreaker = null
 		this.metricsModule = null
 	}
 }

src/Utils/tc-token-utils.ts

@@ -1,12 +1,86 @@
 import type { SignalKeyStoreWithTransaction } from '../Types'
 import type { BinaryNode } from '../WABinary'
-import { getBinaryNodeChild, getBinaryNodeChildren, isLidUser, jidNormalizedUser } from '../WABinary'
+import {
+	getBinaryNodeChild,
+	getBinaryNodeChildren,
+	isAnyLidUser,
+	isAnyPnUser,
+	isHostedLidUser,
+	isHostedPnUser,
+	isJidMetaAI,
+	isLidUser,
+	isPnUser,
+	jidNormalizedUser
+} from '../WABinary'
 
 /** 7 days in seconds — matches WA Web AB prop tctoken_duration */
 const TC_TOKEN_BUCKET_DURATION = 604800
 /** 4 buckets → ~28-day rolling window — matches WA Web AB prop tctoken_num_buckets */
 const TC_TOKEN_NUM_BUCKETS = 4
 
+/**
+ * Sentinel key under the `tctoken` store holding a JSON array of tracked storage JIDs
+ * for cross-session pruning. Mirrors WA Web's CLEAN_TC_TOKENS index lookup.
+ *
+ * Exported so other modules (messages-recv, messages-send, process-message) reference
+ * the same constant. The fork previously inlined this string in messages-recv.ts;
+ * keep the value identical (`'__index'`) for backward compatibility with persisted state.
+ */
+export const TC_TOKEN_INDEX_KEY = '__index'
+
+// Phone-number pattern matching WABinary's isJidBot, applied against the user part so
+// the check is invariant to @c.us ↔ @s.whatsapp.net normalization.
+const BOT_PHONE_REGEX = /^1313555\d{4}$|^131655500\d{2}$/
+
+/**
+ * Mirrors WA Web's `Wid.isRegularUser()` (user ∧ ¬PSA ∧ ¬Bot). Used to gate tctoken
+ * storage against malformed notifications — WA Web filters server-side but we
+ * defend here for parity with `WAWebSetTcTokenChatAction.handleIncomingTcToken`.
+ * Works for both pre- and post-normalized JIDs (`@c.us` vs `@s.whatsapp.net`).
+ */
+export function isRegularUser(jid: string | undefined): boolean {
+	if (!jid) return false
+	const user = jid.split('@')[0] ?? ''
+	if (user === '0') return false // PSA
+	if (BOT_PHONE_REGEX.test(user)) return false // Bot by phone pattern
+	if (isJidMetaAI(jid)) return false // MetaAI (@bot server)
+	return !!(isPnUser(jid) || isLidUser(jid) || isHostedPnUser(jid) || isHostedLidUser(jid) || jid.endsWith('@c.us'))
+}
+
+/** Read the persisted tctoken JID index and return its entries (never contains the sentinel key itself). */
+export async function readTcTokenIndex(keys: SignalKeyStoreWithTransaction): Promise<string[]> {
+	const data = await keys.get('tctoken', [TC_TOKEN_INDEX_KEY])
+	const entry = data[TC_TOKEN_INDEX_KEY]
+	if (!entry?.token?.length) return []
+	try {
+		const parsed = JSON.parse(Buffer.from(entry.token).toString())
+		if (!Array.isArray(parsed)) return []
+		return parsed.filter((j): j is string => typeof j === 'string' && j.length > 0 && j !== TC_TOKEN_INDEX_KEY)
+	} catch {
+		return []
+	}
+}
+
+/**
+ * Build a SignalDataSet fragment that writes the merged index (persisted ∪ added)
+ * under the sentinel key. Lets callers update the index without clobbering writes
+ * made by other layers (history sync, concurrent sessions on the same store).
+ */
+export async function buildMergedTcTokenIndexWrite(
+	keys: SignalKeyStoreWithTransaction,
+	addedJids: Iterable<string>
+): Promise<{ [TC_TOKEN_INDEX_KEY]: { token: Buffer } }> {
+	const persisted = await readTcTokenIndex(keys)
+	const merged = new Set(persisted)
+	for (const jid of addedJids) {
+		if (jid && jid !== TC_TOKEN_INDEX_KEY) merged.add(jid)
+	}
+
+	return {
+		[TC_TOKEN_INDEX_KEY]: { token: Buffer.from(JSON.stringify([...merged])) }
+	}
+}
+
 /**
  * Check if a received token is expired using WA Web's rolling bucket algorithm.
  * Reference: WAWebTrustedContactsUtils.isTokenExpired
@@ -63,6 +137,43 @@ export async function resolveTcTokenJid(
 	return lid ?? normalized
 }
 
+/**
+ * Resolve target JID for issuing privacy token based on AB prop 14303
+ * (`lid_trusted_token_issue_to_lid`). When the prop is on, issuance goes to
+ * the LID; when off, it goes to the PN. Returns the original JID if no
+ * mapping is found in either direction.
+ *
+ * Normalizes the JID upfront and uses the `isAny*` helpers so callers can pass
+ * `@c.us`, `@s.whatsapp.net`, `@hosted`, `@hosted.lid`, `@lid` or device-specific
+ * forms — `LIDMappingStore.getLIDForPN` early-returns unless `isAnyPnUser`,
+ * so unnormalized inputs would silently bypass routing.
+ *
+ * Reference: WAWebTrustedContactsManager.issuePrivacyTokens
+ */
+export async function resolveIssuanceJid(
+	jid: string,
+	issueToLid: boolean,
+	getLIDForPN: (pn: string) => Promise<string | null>,
+	getPNForLID?: (lid: string) => Promise<string | null>
+): Promise<string> {
+	const normalized = jidNormalizedUser(jid)
+
+	if (issueToLid) {
+		if (isAnyLidUser(normalized)) return normalized
+		if (!isAnyPnUser(normalized)) return normalized
+		const lid = await getLIDForPN(normalized)
+		return lid ?? normalized
+	}
+
+	if (!isAnyLidUser(normalized)) return normalized
+	if (getPNForLID) {
+		const pn = await getPNForLID(normalized)
+		return pn ?? normalized
+	}
+
+	return normalized
+}
+
 type TcTokenParams = {
 	jid: string
 	baseContent?: BinaryNode[]
@@ -135,7 +246,13 @@ export async function storeTcTokensFromIqResult({
 			continue
 		}
 
-		const rawJid = jidNormalizedUser(tokenNode.attrs.jid || fallbackJid)
+		// In notifications, tokenNode.attrs.jid is OUR own device JID, not the sender's.
+		// Prefer fallbackJid (resolved from notification's `from` / `sender_lid`) so the
+		// token is stored under the peer's JID, never under self.
+		const rawJid = jidNormalizedUser(fallbackJid || tokenNode.attrs.jid)
+		// Defense against malformed notifications (PSA WID '0', bots, MetaAI). WA Web
+		// filters these server-side; we mirror Wid.isRegularUser() locally.
+		if (!isRegularUser(rawJid)) continue
 		const storageJid = await resolveTcTokenJid(rawJid, getLIDForPN)
 		const existingTcData = await keys.get('tctoken', [storageJid])
 		const existingEntry = existingTcData[storageJid]

src/Utils/unified-session.ts

@@ -15,7 +15,6 @@
  */
 
 import type { BinaryNode } from '../WABinary/types.js'
-import { CircuitBreaker, CircuitOpenError, createConnectionCircuitBreaker } from './circuit-breaker.js'
 import type { ILogger } from './logger.js'
 import { metrics } from './prometheus-metrics.js'
 
@@ -58,8 +57,6 @@ export interface UnifiedSessionOptions {
 	enabled?: boolean
 	/** Logger instance for debugging */
 	logger?: ILogger
-	/** Enable circuit breaker protection for send operations */
-	enableCircuitBreaker?: boolean
 	/** Function to send binary nodes to WhatsApp */
 	sendNode?: (node: BinaryNode) => Promise<void>
 }
@@ -93,7 +90,9 @@ export type UnifiedSessionTrigger = 'login' | 'pairing' | 'presence' | 'manual'
  * Manages the unified_session telemetry feature with:
  * - Server time synchronization
  * - Rate limiting (prevents spam)
- * - Circuit breaker protection
+ * - Best-effort send semantics (failures are swallowed and counted —
+ *   telemetry is non-critical so a single attempt with the underlying
+ *   sendNode timeout is enough; no retry, no circuit breaker)
  * - Prometheus metrics integration
  * - Structured logging
  *
@@ -121,7 +120,6 @@ export class UnifiedSessionManager {
 	}
 
 	private readonly options: Required<UnifiedSessionOptions>
-	private circuitBreaker: CircuitBreaker | null = null
 
 	/** Minimum interval between unified_session sends (1 minute) */
 	private static readonly MIN_SEND_INTERVAL_MS = TimeMs.Minute
@@ -130,7 +128,6 @@ export class UnifiedSessionManager {
 		this.options = {
 			enabled: options.enabled ?? true,
 			logger: options.logger ?? (console as unknown as ILogger),
-			enableCircuitBreaker: options.enableCircuitBreaker ?? true,
 			sendNode:
 				options.sendNode ??
 				(async () => {
@@ -138,25 +135,6 @@ export class UnifiedSessionManager {
 				})
 		}
 
-		// Initialize circuit breaker if enabled
-		if (this.options.enableCircuitBreaker) {
-			this.circuitBreaker = createConnectionCircuitBreaker({
-				name: 'unified-session',
-				failureThreshold: 3,
-				failureWindow: 60000,
-				resetTimeout: 30000,
-				successThreshold: 1,
-				timeout: 10000,
-				onStateChange: (from, to) => {
-					this.options.logger.debug?.({ from, to }, 'Unified session circuit breaker state changed')
-				},
-				onOpen: () => {
-					this.options.logger.warn?.('Unified session circuit breaker OPENED')
-					metrics.circuitBreakerTrips?.inc({ name: 'unified-session' })
-				}
-			})
-		}
-
 		this.state.isInitialized = true
 		this.options.logger.debug?.('UnifiedSessionManager initialized')
 	}
@@ -292,20 +270,12 @@ export class UnifiedSessionManager {
 		}
 
 		try {
-			// Execute with circuit breaker if available
+			// Telemetry is non-critical: a single send attempt with the
-			if (this.circuitBreaker) {
+			// underlying sendNode timeout is enough. No retry/circuit needed.
-				await this.circuitBreaker.execute(sendOperation)
+			await sendOperation()
-			} else {
-				await sendOperation()
-			}
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error)
-
+			this.options.logger.warn?.({ trigger, error: errorMessage }, 'Failed to send unified session telemetry')
-			if (error instanceof CircuitOpenError) {
-				this.options.logger.warn?.({ trigger, circuitState: error.state }, 'Unified session blocked by circuit breaker')
-			} else {
-				this.options.logger.warn?.({ trigger, error: errorMessage }, 'Failed to send unified session telemetry')
-			}
 
 			// Record failure metric
 			metrics.errors?.inc({ category: 'unified_session', code: 'send_failed' })
@@ -331,7 +301,6 @@ export class UnifiedSessionManager {
 			sendCount: 0,
 			isInitialized: true
 		}
-		this.circuitBreaker?.reset()
 		this.options.logger.debug?.('UnifiedSessionManager reset')
 	}
 
@@ -339,7 +308,6 @@ export class UnifiedSessionManager {
 	 * Destroy the manager and clean up resources.
 	 */
 	destroy(): void {
-		this.circuitBreaker?.destroy()
 		this.state.isInitialized = false
 		this.options.logger.debug?.('UnifiedSessionManager destroyed')
 	}

src/__tests__/Socket/identity-change-handling.test.ts

@@ -297,4 +297,52 @@ describe('Identity Change Handling', () => {
 			expect(result.device).toBe(5)
 		})
 	})
+
+	describe('onBeforeSessionRefresh callback', () => {
+		it('fires before assertSessions when a session refresh is about to run', async () => {
+			mockValidateSession.mockResolvedValue({ exists: true })
+			const callOrder: string[] = []
+			mockAssertSessions.mockImplementation(async () => {
+				callOrder.push('assertSessions')
+				return true
+			})
+			const onBeforeSessionRefresh = jest.fn((jid: string) => {
+				callOrder.push(`before:${jid}`)
+			})
+
+			const node = createIdentityChangeNode('user@s.whatsapp.net')
+			const ctx = { ...createContext(), onBeforeSessionRefresh }
+			const result = await handleIdentityChange(node, ctx)
+
+			expect(result.action).toBe('session_refreshed')
+			expect(callOrder).toEqual(['before:user@s.whatsapp.net', 'assertSessions'])
+		})
+
+		it('does not fire when the refresh is skipped (no_identity / offline / self)', async () => {
+			const onBeforeSessionRefresh = jest.fn()
+
+			// no identity node
+			const noIdentityNode: BinaryNode = {
+				tag: 'notification',
+				attrs: { from: 'a@s.whatsapp.net', type: 'encrypt' },
+				content: []
+			}
+			await handleIdentityChange(noIdentityNode, { ...createContext(), onBeforeSessionRefresh })
+
+			// offline notification
+			mockValidateSession.mockResolvedValue({ exists: true })
+			await handleIdentityChange(createIdentityChangeNode('b@s.whatsapp.net', '0'), {
+				...createContext(),
+				onBeforeSessionRefresh
+			})
+
+			// self primary
+			await handleIdentityChange(createIdentityChangeNode(mockMeId!), {
+				...createContext(),
+				onBeforeSessionRefresh
+			})
+
+			expect(onBeforeSessionRefresh).not.toHaveBeenCalled()
+		})
+	})
 })

src/__tests__/Utils/bounded-retry.test.ts

@@ -0,0 +1,391 @@
+import { jest } from '@jest/globals'
+import {
+	withBoundedRetry,
+	BoundedRetryGiveUpError,
+	BoundedRetryAbortedError,
+	WHATSAPP_BACKOFF_DELAYS,
+	DEFAULT_TTL_MS
+} from '../../Utils/bounded-retry'
+
+// All tests use very short real delays (1-50ms) so they run fast.
+// This sidesteps the fragility of jest fake timers + async chains.
+
+describe('bounded-retry — WhatsApp-aligned per-operation retry', () => {
+	test('default delay sequence matches WhatsApp Android empirical capture', () => {
+		// Frida trace: 3000 -> 10000 -> 60000 -> ~64000 -> 120000 ms
+		expect(WHATSAPP_BACKOFF_DELAYS).toEqual([3000, 10000, 60000, 60000, 120000])
+	})
+
+	test('default TTL is 10 minutes (matches empirical stabilisation + safety buffer)', () => {
+		expect(DEFAULT_TTL_MS).toBe(600_000)
+	})
+
+	test('first-attempt success returns immediately, no retries', async () => {
+		const op = jest.fn<() => Promise<string>>().mockResolvedValue('ok')
+		const result = await withBoundedRetry(op, { name: 'fast-success' })
+		expect(result).toBe('ok')
+		expect(op).toHaveBeenCalledTimes(1)
+	})
+
+	test('retries with the configured delay sequence after failures', async () => {
+		const op = jest
+			.fn<() => Promise<number>>()
+			.mockRejectedValueOnce(new Error('try1'))
+			.mockRejectedValueOnce(new Error('try2'))
+			.mockResolvedValueOnce(42)
+
+		const onRetry = jest.fn<(err: Error, attempt: number, delayMs: number) => void>()
+		const result = await withBoundedRetry(op, {
+			name: 'three-tries',
+			delays: [10, 20, 40],
+			jitter: 0,
+			onRetry
+		})
+
+		expect(result).toBe(42)
+		expect(op).toHaveBeenCalledTimes(3)
+		expect(onRetry).toHaveBeenCalledTimes(2)
+		expect(onRetry.mock.calls[0]![2]).toBe(10)
+		expect(onRetry.mock.calls[1]![2]).toBe(20)
+	})
+
+	test('TTL exhaustion throws BoundedRetryGiveUpError (no infinite retries)', async () => {
+		const op = jest.fn<() => Promise<string>>().mockRejectedValue(new Error('always-fails'))
+
+		await expect(
+			withBoundedRetry(op, {
+				name: 'ttl-test',
+				delays: [10],
+				jitter: 0,
+				ttlMs: 50
+			})
+		).rejects.toBeInstanceOf(BoundedRetryGiveUpError)
+
+		// Should have tried multiple times before giving up
+		expect(op.mock.calls.length).toBeGreaterThanOrEqual(2)
+	})
+
+	test('per-attempt timeout fires for slow operations', async () => {
+		const slowOp = jest.fn<() => Promise<string>>(() => new Promise(() => {})) // hangs
+
+		await expect(
+			withBoundedRetry(slowOp, {
+				name: 'slow',
+				delays: [5],
+				jitter: 0,
+				ttlMs: 200,
+				perAttemptTimeoutMs: 30
+			})
+		).rejects.toBeInstanceOf(BoundedRetryGiveUpError)
+
+		// Multiple attempts should have been tried (each timed out at 30ms)
+		expect(slowOp.mock.calls.length).toBeGreaterThan(1)
+	})
+
+	test('shouldRetry predicate can short-circuit retries', async () => {
+		const op = jest
+			.fn<() => Promise<string>>()
+			.mockRejectedValueOnce(new Error('transient'))
+			.mockRejectedValueOnce(new Error('FATAL: do not retry'))
+
+		await expect(
+			withBoundedRetry(op, {
+				name: 'predicate-test',
+				delays: [1],
+				jitter: 0,
+				shouldRetry: err => !err.message.startsWith('FATAL')
+			})
+		).rejects.toThrow('FATAL: do not retry')
+
+		expect(op).toHaveBeenCalledTimes(2)
+	})
+
+	test('AbortSignal cancels in-flight retry sleep', async () => {
+		const op = jest.fn<() => Promise<string>>().mockRejectedValue(new Error('fail'))
+		const ctrl = new AbortController()
+
+		const promise = withBoundedRetry(op, {
+			name: 'abort-test',
+			delays: [10_000], // long sleep so abort can happen during it
+			jitter: 0,
+			signal: ctrl.signal
+		})
+
+		// First attempt fires immediately; sleep starts
+		await new Promise(resolve => setTimeout(resolve, 10))
+		ctrl.abort()
+
+		await expect(promise).rejects.toBeInstanceOf(BoundedRetryAbortedError)
+	})
+
+	test('two concurrent retry chains do NOT interfere with each other (per-op isolation)', async () => {
+		// Key advantage over circuit breaker: failures in one chain do not
+		// block another chain. With circuit breaker, 5 failures from chain A
+		// would block chain B too. With bounded-retry, B is independent.
+
+		const flakyOp = jest
+			.fn<() => Promise<string>>()
+			.mockRejectedValueOnce(new Error('a1'))
+			.mockResolvedValueOnce('a-ok')
+
+		const fastOp = jest.fn<() => Promise<string>>().mockResolvedValue('b-ok')
+
+		// Start a (will retry once after 30ms) and b (immediate)
+		const aPromise = withBoundedRetry(flakyOp, { name: 'a', delays: [30], jitter: 0 })
+		const bPromise = withBoundedRetry(fastOp, { name: 'b', delays: [30], jitter: 0 })
+
+		// b should resolve right away
+		const bResult = await bPromise
+		expect(bResult).toBe('b-ok')
+		expect(fastOp).toHaveBeenCalledTimes(1)
+
+		// a still running — wait for it
+		const aResult = await aPromise
+		expect(aResult).toBe('a-ok')
+		expect(flakyOp).toHaveBeenCalledTimes(2)
+	})
+
+	test('delay sequence caps at last value (no unbounded growth)', async () => {
+		const op = jest.fn<() => Promise<string>>().mockRejectedValue(new Error('fail'))
+		const onRetry = jest.fn<(err: Error, attempt: number, delayMs: number) => void>()
+
+		await expect(
+			withBoundedRetry(op, {
+				name: 'cap-test',
+				delays: [5, 10, 15], // 3 distinct steps; 4th+ retry should reuse 15
+				jitter: 0,
+				ttlMs: 300,
+				onRetry
+			})
+		).rejects.toBeInstanceOf(BoundedRetryGiveUpError)
+
+		// Find delays >= 4th retry — all should be capped at 15
+		const lateRetries = onRetry.mock.calls.filter(c => c[1] >= 4)
+		expect(lateRetries.length).toBeGreaterThan(0)
+		for (const call of lateRetries) {
+			expect(call[2]).toBeLessThanOrEqual(15)
+		}
+	})
+
+	test('jitter randomises delay within +/- factor', async () => {
+		const op = jest.fn<() => Promise<string>>().mockRejectedValue(new Error('fail'))
+		const observed: number[] = []
+
+		// Single run, capture multiple onRetry calls (each with different jitter)
+		await withBoundedRetry(op, {
+			name: 'jitter-test',
+			delays: [50], // base delay
+			jitter: 0.3, // +/- 30% -> [35, 65]
+			ttlMs: 1000, // ttl high enough for ~10 retries
+			perAttemptTimeoutMs: 5,
+			onRetry: (_, __, d) => observed.push(d)
+		}).catch(() => {})
+
+		expect(observed.length).toBeGreaterThanOrEqual(3)
+		const unique = new Set(observed)
+		expect(unique.size).toBeGreaterThan(1)
+		// Every observed delay must be within jitter window — but the LAST one
+		// may be capped by remaining ttl budget, so check all but the last
+		const inWindow = observed.slice(0, -1)
+		for (const d of inWindow) {
+			expect(d).toBeGreaterThanOrEqual(35)
+			expect(d).toBeLessThanOrEqual(65)
+		}
+	})
+
+	test('delay does not exceed remaining TTL budget', async () => {
+		const op = jest.fn<() => Promise<string>>().mockRejectedValue(new Error('fail'))
+		const onRetry = jest.fn<(err: Error, attempt: number, delayMs: number) => void>()
+
+		await withBoundedRetry(op, {
+			name: 'budget-cap',
+			delays: [200], // would exceed ttl
+			jitter: 0,
+			ttlMs: 50, // very short
+			onRetry
+		}).catch(() => {})
+
+		// All scheduled delays should be capped to remaining budget
+		for (const call of onRetry.mock.calls) {
+			expect(call[2]).toBeLessThanOrEqual(50)
+		}
+	})
+
+	// ─── Tests for fixes from PR #393 review ──────────────────────────────
+
+	test('TTL is enforced BEFORE the next attempt (not just after)', async () => {
+		// Regression: previously TTL was only checked after a failure, so a
+		// new attempt could start with 0ms remaining and run for the full
+		// per-attempt timeout, overshooting wall-clock budget by that much.
+		const slowOp = jest.fn<() => Promise<string>>(() => new Promise(resolve => setTimeout(() => resolve('late'), 200)))
+
+		const start = Date.now()
+		await expect(
+			withBoundedRetry(slowOp, {
+				name: 'ttl-strict',
+				delays: [10],
+				jitter: 0,
+				ttlMs: 50,
+				perAttemptTimeoutMs: 1000 // huge, must be capped by TTL
+			})
+		).rejects.toBeInstanceOf(BoundedRetryGiveUpError)
+
+		const elapsed = Date.now() - start
+		// With strict TTL enforcement, total runtime should be very close to ttlMs.
+		// Allow up to 100ms slack for Node timer + microtask scheduling.
+		expect(elapsed).toBeLessThan(150)
+	})
+
+	test('per-attempt timeout is capped by remaining TTL budget', async () => {
+		// If user passes perAttemptTimeoutMs > ttlMs, the cap should apply.
+		const slowOp = jest.fn<() => Promise<string>>(() => new Promise(() => {})) // hangs forever
+
+		const start = Date.now()
+		await expect(
+			withBoundedRetry(slowOp, {
+				name: 'attempt-cap',
+				delays: [1],
+				jitter: 0,
+				ttlMs: 30,
+				perAttemptTimeoutMs: 5000 // way bigger than ttl
+			})
+		).rejects.toBeInstanceOf(BoundedRetryGiveUpError)
+
+		const elapsed = Date.now() - start
+		expect(elapsed).toBeLessThan(150) // not 5000ms!
+	})
+
+	test('operation receives an AbortSignal that is aborted on per-attempt timeout', async () => {
+		// New API: operation can opt into cancellation via the signal arg.
+		const aborts: boolean[] = []
+		const opThatRespectsSignal = jest.fn(
+			(signal?: AbortSignal) =>
+				new Promise<string>((resolve, reject) => {
+					const timer = setTimeout(() => resolve('late'), 100)
+					signal?.addEventListener('abort', () => {
+						clearTimeout(timer)
+						aborts.push(true)
+						reject(new Error('aborted by signal'))
+					})
+				})
+		)
+
+		await withBoundedRetry(opThatRespectsSignal, {
+			name: 'signal-aware',
+			delays: [1],
+			jitter: 0,
+			ttlMs: 80,
+			perAttemptTimeoutMs: 20 // smaller than 100ms op duration
+		}).catch(() => {})
+
+		expect(aborts.length).toBeGreaterThan(0) // at least one attempt was aborted
+	})
+
+	test('sleep listener is removed when timeout completes normally (no leak)', async () => {
+		// Regression: sleep used signal.addEventListener with { once: true } but
+		// never removed the listener on timer-resolve. With many retries on a
+		// shared signal, listeners would accumulate.
+		//
+		// Make the failure mode observable by spying on add/removeEventListener
+		// directly so the assertion fails if cleanup is removed.
+		const ctrl = new AbortController()
+		const realAdd = ctrl.signal.addEventListener.bind(ctrl.signal)
+		const realRemove = ctrl.signal.removeEventListener.bind(ctrl.signal)
+		let addCount = 0
+		let removeCount = 0
+		ctrl.signal.addEventListener = ((type: string, listener: never, opts?: never) => {
+			if (type === 'abort') addCount++
+			return realAdd(type, listener, opts)
+		}) as typeof ctrl.signal.addEventListener
+		ctrl.signal.removeEventListener = ((type: string, listener: never, opts?: never) => {
+			if (type === 'abort') removeCount++
+			return realRemove(type, listener, opts)
+		}) as typeof ctrl.signal.removeEventListener
+
+		const op = jest
+			.fn<() => Promise<string>>()
+			.mockRejectedValueOnce(new Error('1'))
+			.mockRejectedValueOnce(new Error('2'))
+			.mockRejectedValueOnce(new Error('3'))
+			.mockResolvedValueOnce('ok')
+
+		const result = await withBoundedRetry(op, {
+			name: 'no-leak',
+			delays: [5],
+			jitter: 0,
+			ttlMs: 500,
+			signal: ctrl.signal
+		})
+
+		expect(result).toBe('ok')
+		expect(op).toHaveBeenCalledTimes(4)
+		// If sleep() leaks listeners, addCount > removeCount. Each retry adds
+		// listeners (1 sleep + 1 outer-abort forwarding) and must remove the
+		// same number on settlement.
+		expect(addCount).toBeGreaterThan(0)
+		expect(addCount).toBe(removeCount)
+	})
+
+	test('logger receives structured logs for retry, give-up, and recovery', async () => {
+		const debugCalls: unknown[][] = []
+		const infoCalls: unknown[][] = []
+		const warnCalls: unknown[][] = []
+		const fakeLogger = {
+			debug: (...args: unknown[]) => debugCalls.push(args),
+			info: (...args: unknown[]) => infoCalls.push(args),
+			warn: (...args: unknown[]) => warnCalls.push(args),
+			error: () => {},
+			fatal: () => {},
+			trace: () => {},
+			child: () => fakeLogger,
+			level: 'debug'
+		}
+
+		const op = jest
+			.fn<() => Promise<string>>()
+			.mockRejectedValueOnce(new Error('boom'))
+			.mockResolvedValueOnce('ok')
+
+		const result = await withBoundedRetry(op, {
+			name: 'logged-op',
+			delays: [5],
+			jitter: 0,
+			ttlMs: 200,
+			logger: fakeLogger as never
+		})
+
+		expect(result).toBe('ok')
+		// Should have logged the scheduling at debug level
+		expect(debugCalls.length).toBeGreaterThanOrEqual(1)
+		// Should have logged the recovery at info level
+		expect(infoCalls.length).toBeGreaterThanOrEqual(1)
+	})
+
+	test('logger reports give-up via warn when TTL exceeded', async () => {
+		const warnCalls: unknown[][] = []
+		const fakeLogger = {
+			debug: () => {},
+			info: () => {},
+			warn: (...args: unknown[]) => warnCalls.push(args),
+			error: () => {},
+			fatal: () => {},
+			trace: () => {},
+			child: () => fakeLogger,
+			level: 'debug'
+		}
+
+		const op = jest.fn<() => Promise<string>>().mockRejectedValue(new Error('always-fails'))
+
+		await expect(
+			withBoundedRetry(op, {
+				name: 'logged-fail',
+				delays: [5],
+				jitter: 0,
+				ttlMs: 30,
+				logger: fakeLogger as never
+			})
+		).rejects.toBeInstanceOf(BoundedRetryGiveUpError)
+
+		expect(warnCalls.length).toBeGreaterThanOrEqual(1)
+	})
+})

src/__tests__/Utils/circuit-breaker.test.ts

@@ -1,371 +0,0 @@
-/**
- * Testes unitários para circuit-breaker.ts
- */
-
-import { afterEach, beforeEach, describe, expect, it } from '@jest/globals'
-import {
-	CircuitBreaker,
-	CircuitBreakerRegistry,
-	CircuitOpenError,
-	type CircuitState,
-	CircuitTimeoutError,
-	createCircuitBreaker,
-	getCircuitHealth,
-	globalCircuitRegistry,
-	withCircuitBreaker
-} from '../../Utils/circuit-breaker.js'
-
-describe('CircuitBreaker', () => {
-	let breaker: CircuitBreaker
-
-	beforeEach(() => {
-		breaker = createCircuitBreaker({
-			name: 'test',
-			failureThreshold: 3,
-			successThreshold: 2,
-			resetTimeout: 100,
-			timeout: 1000,
-			volumeThreshold: 3,
-			collectMetrics: false
-		})
-	})
-
-	afterEach(() => {
-		breaker.destroy()
-	})
-
-	describe('initial state', () => {
-		it('should start in closed state', () => {
-			expect(breaker.getState()).toBe('closed')
-			expect(breaker.isClosed()).toBe(true)
-			expect(breaker.isOpen()).toBe(false)
-			expect(breaker.isHalfOpen()).toBe(false)
-		})
-	})
-
-	describe('successful operations', () => {
-		it('should execute successful operations', async () => {
-			const result = await breaker.execute(() => 'success')
-			expect(result).toBe('success')
-		})
-
-		it('should execute async operations', async () => {
-			const result = await breaker.execute(async () => {
-				await new Promise(resolve => setTimeout(resolve, 10))
-				return 'async success'
-			})
-			expect(result).toBe('async success')
-		})
-
-		it('should track successful calls in stats', async () => {
-			await breaker.execute(() => 'success')
-			await breaker.execute(() => 'success')
-
-			const stats = breaker.getStats()
-			expect(stats.totalCalls).toBe(2)
-			expect(stats.totalSuccesses).toBe(2)
-			expect(stats.totalFailures).toBe(0)
-		})
-	})
-
-	describe('failure handling', () => {
-		it('should open after reaching failure threshold', async () => {
-			const failingOp = () => {
-				throw new Error('Failure')
-			}
-
-			// Reach failure threshold
-			for (let i = 0; i < 3; i++) {
-				await expect(breaker.execute(failingOp)).rejects.toThrow('Failure')
-			}
-
-			expect(breaker.isOpen()).toBe(true)
-		})
-
-		it('should not open before reaching threshold', async () => {
-			const failingOp = () => {
-				throw new Error('Failure')
-			}
-
-			// Below threshold
-			for (let i = 0; i < 2; i++) {
-				await expect(breaker.execute(failingOp)).rejects.toThrow('Failure')
-			}
-
-			expect(breaker.isClosed()).toBe(true)
-		})
-
-		it('should reset failure count on success', async () => {
-			const failingOp = () => {
-				throw new Error('Failure')
-			}
-
-			await expect(breaker.execute(failingOp)).rejects.toThrow()
-			await expect(breaker.execute(failingOp)).rejects.toThrow()
-
-			// Success resets failures
-			await breaker.execute(() => 'success')
-
-			// Only 1 more failure needed (already have 2 in window, need 3 total)
-			await expect(breaker.execute(failingOp)).rejects.toThrow()
-
-			// Should open now (3 failures in window)
-			expect(breaker.isOpen()).toBe(true)
-		})
-	})
-
-	describe('open state', () => {
-		beforeEach(async () => {
-			// Force open
-			breaker.trip()
-		})
-
-		it('should reject operations when open', async () => {
-			await expect(breaker.execute(() => 'success')).rejects.toThrow(CircuitOpenError)
-		})
-
-		it('should transition to half-open after reset timeout', async () => {
-			await new Promise(resolve => setTimeout(resolve, 150))
-			expect(breaker.isHalfOpen()).toBe(true)
-		})
-	})
-
-	describe('half-open state', () => {
-		beforeEach(async () => {
-			breaker.trip()
-			await new Promise(resolve => setTimeout(resolve, 150))
-		})
-
-		it('should close after success threshold', async () => {
-			expect(breaker.isHalfOpen()).toBe(true)
-
-			// Success threshold is 2
-			await breaker.execute(() => 'success')
-			await breaker.execute(() => 'success')
-
-			expect(breaker.isClosed()).toBe(true)
-		})
-
-		it('should reopen on failure', async () => {
-			expect(breaker.isHalfOpen()).toBe(true)
-
-			await expect(
-				breaker.execute(() => {
-					throw new Error('Failure')
-				})
-			).rejects.toThrow()
-
-			expect(breaker.isOpen()).toBe(true)
-		})
-	})
-
-	describe('manual controls', () => {
-		it('should force open with trip()', () => {
-			breaker.trip()
-			expect(breaker.isOpen()).toBe(true)
-		})
-
-		it('should force close with reset()', async () => {
-			breaker.trip()
-			breaker.reset()
-			expect(breaker.isClosed()).toBe(true)
-		})
-	})
-
-	describe('timeout', () => {
-		it('should timeout slow operations', async () => {
-			const slowBreaker = createCircuitBreaker({
-				name: 'slow',
-				timeout: 50,
-				collectMetrics: false
-			})
-
-			await expect(slowBreaker.execute(() => new Promise(resolve => setTimeout(resolve, 200)))).rejects.toThrow(
-				CircuitTimeoutError
-			)
-
-			slowBreaker.destroy()
-		})
-	})
-
-	describe('events', () => {
-		it('should emit state-change event', async () => {
-			const stateChanges: Array<{ from: CircuitState; to: CircuitState }> = []
-
-			breaker.on('state-change', change => {
-				stateChanges.push(change)
-			})
-
-			breaker.trip()
-			breaker.reset()
-
-			expect(stateChanges).toHaveLength(2)
-			expect(stateChanges[0]).toEqual({ from: 'closed', to: 'open' })
-			expect(stateChanges[1]).toEqual({ from: 'open', to: 'closed' })
-		})
-
-		it('should emit success and failure events', async () => {
-			let successCount = 0
-			let failureCount = 0
-
-			breaker.on('success', () => successCount++)
-			breaker.on('failure', () => failureCount++)
-
-			await breaker.execute(() => 'success')
-			await expect(
-				breaker.execute(() => {
-					throw new Error()
-				})
-			).rejects.toThrow()
-
-			expect(successCount).toBe(1)
-			expect(failureCount).toBe(1)
-		})
-	})
-
-	describe('isFailure predicate', () => {
-		it('should use custom isFailure predicate', async () => {
-			const customBreaker = createCircuitBreaker({
-				name: 'custom',
-				failureThreshold: 1,
-				volumeThreshold: 1,
-				shouldCountError: (error: any) => error.message !== 'Ignored',
-				collectMetrics: false
-			})
-
-			// This error should be ignored
-			await expect(
-				customBreaker.execute(() => {
-					throw new Error('Ignored')
-				})
-			).rejects.toThrow()
-
-			expect(customBreaker.isClosed()).toBe(true)
-
-			// This should trip the breaker
-			await expect(
-				customBreaker.execute(() => {
-					throw new Error('Real failure')
-				})
-			).rejects.toThrow()
-
-			expect(customBreaker.isOpen()).toBe(true)
-
-			customBreaker.destroy()
-		})
-	})
-
-	describe('sync operations', () => {
-		it('should execute sync operations', () => {
-			const result = breaker.executeSync(() => 'sync result')
-			expect(result).toBe('sync result')
-		})
-
-		it('should handle sync failures', () => {
-			expect(() =>
-				breaker.executeSync(() => {
-					throw new Error('Sync failure')
-				})
-			).toThrow('Sync failure')
-		})
-	})
-})
-
-describe('CircuitBreakerRegistry', () => {
-	let registry: CircuitBreakerRegistry
-
-	beforeEach(() => {
-		registry = new CircuitBreakerRegistry()
-	})
-
-	afterEach(() => {
-		registry.destroyAll()
-	})
-
-	it('should create and retrieve circuit breakers', () => {
-		const breaker1 = registry.get('test1')
-		const breaker2 = registry.get('test1')
-
-		expect(breaker1).toBe(breaker2)
-	})
-
-	it('should check if breaker exists', () => {
-		registry.get('exists')
-
-		expect(registry.has('exists')).toBe(true)
-		expect(registry.has('notexists')).toBe(false)
-	})
-
-	it('should remove breaker', () => {
-		registry.get('toRemove')
-		expect(registry.remove('toRemove')).toBe(true)
-		expect(registry.has('toRemove')).toBe(false)
-	})
-
-	it('should get all stats', () => {
-		registry.get('breaker1')
-		registry.get('breaker2')
-
-		const stats = registry.getAllStats()
-
-		expect(stats).toHaveProperty('breaker1')
-		expect(stats).toHaveProperty('breaker2')
-	})
-
-	it('should reset all breakers', async () => {
-		const breaker = registry.get('test')
-		breaker.trip()
-
-		registry.resetAll()
-
-		expect(breaker.isClosed()).toBe(true)
-	})
-})
-
-describe('withCircuitBreaker', () => {
-	it('should wrap function with circuit breaker', async () => {
-		let callCount = 0
-
-		const protectedFn = withCircuitBreaker(
-			async () => {
-				callCount++
-				return 'result'
-			},
-			{
-				name: 'wrapped-fn',
-				collectMetrics: false
-			}
-		)
-
-		const result = await protectedFn()
-
-		expect(result).toBe('result')
-		expect(callCount).toBe(1)
-	})
-})
-
-describe('getCircuitHealth', () => {
-	beforeEach(() => {
-		globalCircuitRegistry.destroyAll()
-	})
-
-	it('should report healthy when all circuits closed', () => {
-		globalCircuitRegistry.get('healthy1')
-		globalCircuitRegistry.get('healthy2')
-
-		const health = getCircuitHealth()
-
-		expect(health.healthy).toBe(true)
-		expect(health.openCircuits).toHaveLength(0)
-	})
-
-	it('should report unhealthy when circuit is open', () => {
-		const breaker = globalCircuitRegistry.get('unhealthy')
-		breaker.trip()
-
-		const health = getCircuitHealth()
-
-		expect(health.healthy).toBe(false)
-		expect(health.openCircuits).toContain('unhealthy')
-	})
-})

src/__tests__/Utils/retry-utils.test.ts

@@ -2,7 +2,7 @@
  * Testes unitários para retry-utils.ts
  */
 
-import { beforeEach, describe, expect, it, jest } from '@jest/globals'
+import { describe, expect, it, jest } from '@jest/globals'
 import {
 	calculateDelay,
 	createRetrier,
@@ -11,12 +11,10 @@ import {
 	retry,
 	RETRY_BACKOFF_DELAYS,
 	RETRY_JITTER_FACTOR,
-	retryable,
 	RetryAbortedError,
 	retryConfigs,
 	type RetryContext,
 	RetryExhaustedError,
-	RetryManager,
 	retryPredicates,
 	retryWithResult
 } from '../../Utils/retry-utils.js'
@@ -315,103 +313,6 @@ describe('createRetrier', () => {
 	})
 })
 
-describe('retryable', () => {
-	it('should wrap function with retry', async () => {
-		let attempts = 0
-
-		const fn = retryable(
-			() => {
-				attempts++
-				if (attempts < 2) throw new Error('Failing')
-				return 'wrapped result'
-			},
-			{
-				maxAttempts: 5,
-				baseDelay: 10,
-				collectMetrics: false
-			}
-		)
-
-		const result = await fn()
-
-		expect(result).toBe('wrapped result')
-		expect(attempts).toBe(2)
-	})
-})
-
-describe('RetryManager', () => {
-	let manager: RetryManager
-
-	beforeEach(() => {
-		manager = new RetryManager({ baseDelay: 200, collectMetrics: false })
-	})
-
-	it('should execute operation with id', async () => {
-		const result = await manager.execute('op1', () => 'result')
-		expect(result).toBe('result')
-	})
-
-	it('should cancel active retry', async () => {
-		let attempt = 0
-
-		const promise = manager.execute('cancelable', async () => {
-			attempt++
-			if (attempt === 1) {
-				throw new Error('Temporary failure')
-			}
-
-			await new Promise(resolve => setTimeout(resolve, 1000))
-			return 'result'
-		})
-
-		// Cancel during retry delay
-		setTimeout(() => manager.cancel('cancelable'), 100)
-
-		await expect(promise).rejects.toThrow()
-	})
-
-	it('should check if operation is active', async () => {
-		let resolve: () => void
-		const promise = manager.execute(
-			'active',
-			() =>
-				new Promise<string>(r => {
-					resolve = () => r('done')
-				})
-		)
-
-		expect(manager.isActive('active')).toBe(true)
-
-		resolve!()
-		await promise
-
-		expect(manager.isActive('active')).toBe(false)
-	})
-
-	it('should cancel all operations', async () => {
-		const promises = [
-			manager.execute('op1', () => new Promise((_, reject) => setTimeout(() => reject(new Error()), 1000))),
-			manager.execute('op2', () => new Promise((_, reject) => setTimeout(() => reject(new Error()), 1000)))
-		]
-
-		setTimeout(() => manager.cancelAll(), 20)
-
-		await expect(Promise.all(promises)).rejects.toThrow()
-	})
-
-	it('should emit events', async () => {
-		const events: string[] = []
-
-		manager.on('attempt', () => events.push('attempt'))
-		manager.on('success', () => events.push('success'))
-
-		await manager.execute('test', () => 'result')
-
-		expect(events).toContain('attempt')
-		expect(events).toContain('success')
-	})
-})
-
 describe('retryPredicates', () => {
 	describe('always', () => {
 		it('should always return true', () => {

src/__tests__/Utils/tc-token.test.ts

@@ -1,7 +1,17 @@
 import { jest } from '@jest/globals'
 import { DisconnectReason, type SignalKeyStoreWithTransaction } from '../../Types'
 import { getErrorCodeFromStreamError, SERVER_ERROR_CODES } from '../../Utils'
-import { buildTcTokenFromJid, isTcTokenExpired, shouldSendNewTcToken } from '../../Utils/tc-token-utils'
+import {
+	buildMergedTcTokenIndexWrite,
+	buildTcTokenFromJid,
+	isRegularUser,
+	isTcTokenExpired,
+	readTcTokenIndex,
+	resolveIssuanceJid,
+	shouldSendNewTcToken,
+	storeTcTokensFromIqResult,
+	TC_TOKEN_INDEX_KEY
+} from '../../Utils/tc-token-utils'
 import type { BinaryNode } from '../../WABinary'
 
 /** 7 days in seconds — matches WA Web tctoken_duration */
@@ -848,3 +858,340 @@ describe('tctoken integration scenarios', () => {
 		})
 	})
 })
+
+// ─── isRegularUser (PSA / bot / MetaAI gating) ─────────────────────────
+
+describe('isRegularUser', () => {
+	it('rejects undefined / empty', () => {
+		expect(isRegularUser(undefined)).toBe(false)
+		expect(isRegularUser('')).toBe(false)
+	})
+
+	it('rejects PSA WID (user "0")', () => {
+		expect(isRegularUser('0@s.whatsapp.net')).toBe(false)
+		expect(isRegularUser('0@c.us')).toBe(false)
+	})
+
+	it('rejects bot phone numbers (1313555XXXX, 131655500XX)', () => {
+		expect(isRegularUser('13135550000@s.whatsapp.net')).toBe(false)
+		expect(isRegularUser('13135559999@s.whatsapp.net')).toBe(false)
+		// /^131655500\d{2}$/ — 11 digits: 131655500 + 2 trailing
+		expect(isRegularUser('13165550000@s.whatsapp.net')).toBe(false)
+		expect(isRegularUser('13165550099@s.whatsapp.net')).toBe(false)
+	})
+
+	it('rejects MetaAI (@bot server)', () => {
+		expect(isRegularUser('foo@bot')).toBe(false)
+	})
+
+	it('accepts regular PN users (@s.whatsapp.net, @c.us)', () => {
+		expect(isRegularUser('5511999999999@s.whatsapp.net')).toBe(true)
+		expect(isRegularUser('5511999999999@c.us')).toBe(true)
+	})
+
+	it('accepts LID users', () => {
+		expect(isRegularUser('123456@lid')).toBe(true)
+	})
+
+	it('accepts hosted PN/LID users', () => {
+		expect(isRegularUser('5511999999999@hosted')).toBe(true)
+		expect(isRegularUser('123456@hosted.lid')).toBe(true)
+	})
+})
+
+// ─── resolveIssuanceJid (AB prop 14303 routing) ────────────────────────
+
+describe('resolveIssuanceJid', () => {
+	const PN = '5511999999999@s.whatsapp.net'
+	const LID = '123456@lid'
+	const PN_NO_LID = '5511888888888@s.whatsapp.net'
+	const LID_NO_PN = '999999@lid'
+
+	const getLIDForPN = jest.fn<(pn: string) => Promise<string | null>>(async (pn: string) => {
+		if (pn === PN) return LID
+		return null
+	})
+	const getPNForLID = jest.fn<(lid: string) => Promise<string | null>>(async (lid: string) => {
+		if (lid === LID) return PN
+		return null
+	})
+
+	beforeEach(() => {
+		getLIDForPN.mockClear()
+		getPNForLID.mockClear()
+	})
+
+	describe('AB prop 14303 ON (issueToLid=true)', () => {
+		it('returns LID unchanged when input is LID', async () => {
+			expect(await resolveIssuanceJid(LID, true, getLIDForPN, getPNForLID)).toBe(LID)
+			expect(getLIDForPN).not.toHaveBeenCalled()
+		})
+
+		it('resolves PN to LID via lidMapping', async () => {
+			expect(await resolveIssuanceJid(PN, true, getLIDForPN, getPNForLID)).toBe(LID)
+			expect(getLIDForPN).toHaveBeenCalledWith(PN)
+		})
+
+		it('falls back to original PN when no LID mapping exists', async () => {
+			expect(await resolveIssuanceJid(PN_NO_LID, true, getLIDForPN, getPNForLID)).toBe(PN_NO_LID)
+		})
+	})
+
+	describe('AB prop 14303 OFF (issueToLid=false)', () => {
+		it('returns PN unchanged when input is PN', async () => {
+			expect(await resolveIssuanceJid(PN, false, getLIDForPN, getPNForLID)).toBe(PN)
+			expect(getPNForLID).not.toHaveBeenCalled()
+		})
+
+		it('resolves LID to PN via lidMapping', async () => {
+			expect(await resolveIssuanceJid(LID, false, getLIDForPN, getPNForLID)).toBe(PN)
+			expect(getPNForLID).toHaveBeenCalledWith(LID)
+		})
+
+		it('falls back to original LID when no PN mapping exists', async () => {
+			expect(await resolveIssuanceJid(LID_NO_PN, false, getLIDForPN, getPNForLID)).toBe(LID_NO_PN)
+		})
+
+		it('returns LID unchanged when getPNForLID is omitted', async () => {
+			expect(await resolveIssuanceJid(LID, false, getLIDForPN)).toBe(LID)
+		})
+	})
+
+	describe('JID normalization (handles @c.us and hosted forms)', () => {
+		const PN_CUS = '5511999999999@c.us'
+		const PN_NORMALIZED = '5511999999999@s.whatsapp.net'
+		const HOSTED_LID = '999999@hosted.lid'
+
+		it('normalizes @c.us before resolving (issueToLid=true)', async () => {
+			const fn = jest.fn<(pn: string) => Promise<string | null>>(async (pn: string) => {
+				if (pn === PN_NORMALIZED) return LID
+				return null
+			})
+			const result = await resolveIssuanceJid(PN_CUS, true, fn, getPNForLID)
+			expect(result).toBe(LID)
+			// Mapping store called with NORMALIZED form
+			expect(fn).toHaveBeenCalledWith(PN_NORMALIZED)
+		})
+
+		it('treats hosted LID as LID input (issueToLid=true returns it unchanged)', async () => {
+			expect(await resolveIssuanceJid(HOSTED_LID, true, getLIDForPN, getPNForLID)).toBe(HOSTED_LID)
+			expect(getLIDForPN).not.toHaveBeenCalled()
+		})
+
+		it('treats hosted LID as LID input (issueToLid=false converts via getPNForLID)', async () => {
+			const fn = jest.fn<(lid: string) => Promise<string | null>>(async () => null)
+			await resolveIssuanceJid(HOSTED_LID, false, getLIDForPN, fn)
+			expect(fn).toHaveBeenCalledWith(HOSTED_LID)
+		})
+	})
+})
+
+// ─── readTcTokenIndex / buildMergedTcTokenIndexWrite ───────────────────
+
+describe('tctoken cross-session prune index', () => {
+	it('exports the sentinel key as "__index"', () => {
+		// Persisted state compatibility — tests freeze the value to catch unintended renames.
+		expect(TC_TOKEN_INDEX_KEY).toBe('__index')
+	})
+
+	describe('readTcTokenIndex', () => {
+		it('returns [] when the index entry is absent', async () => {
+			const keys = createMockKeys()
+			;(keys.get as any).mockResolvedValue({})
+			expect(await readTcTokenIndex(keys)).toEqual([])
+		})
+
+		it('returns [] when the index token buffer is empty', async () => {
+			const keys = createMockKeys()
+			;(keys.get as any).mockResolvedValue({ [TC_TOKEN_INDEX_KEY]: { token: Buffer.alloc(0) } })
+			expect(await readTcTokenIndex(keys)).toEqual([])
+		})
+
+		it('returns [] when the JSON payload is corrupted', async () => {
+			const keys = createMockKeys()
+			;(keys.get as any).mockResolvedValue({ [TC_TOKEN_INDEX_KEY]: { token: Buffer.from('not-json') } })
+			expect(await readTcTokenIndex(keys)).toEqual([])
+		})
+
+		it('returns [] when the JSON payload is not an array', async () => {
+			const keys = createMockKeys()
+			;(keys.get as any).mockResolvedValue({ [TC_TOKEN_INDEX_KEY]: { token: Buffer.from('{"a":1}') } })
+			expect(await readTcTokenIndex(keys)).toEqual([])
+		})
+
+		it('returns the persisted JIDs', async () => {
+			const keys = createMockKeys()
+			const stored = ['a@lid', 'b@lid', 'c@s.whatsapp.net']
+			;(keys.get as any).mockResolvedValue({
+				[TC_TOKEN_INDEX_KEY]: { token: Buffer.from(JSON.stringify(stored)) }
+			})
+			expect(await readTcTokenIndex(keys)).toEqual(stored)
+		})
+
+		it('filters out the sentinel key itself, empty strings, and non-strings', async () => {
+			const keys = createMockKeys()
+			const stored = ['a@lid', '', TC_TOKEN_INDEX_KEY, 42, null, 'b@lid']
+			;(keys.get as any).mockResolvedValue({
+				[TC_TOKEN_INDEX_KEY]: { token: Buffer.from(JSON.stringify(stored)) }
+			})
+			expect(await readTcTokenIndex(keys)).toEqual(['a@lid', 'b@lid'])
+		})
+	})
+
+	describe('buildMergedTcTokenIndexWrite', () => {
+		it('merges added JIDs with the persisted set (de-duplicated)', async () => {
+			const keys = createMockKeys()
+			;(keys.get as any).mockResolvedValue({
+				[TC_TOKEN_INDEX_KEY]: { token: Buffer.from(JSON.stringify(['a@lid', 'b@lid'])) }
+			})
+			const write = await buildMergedTcTokenIndexWrite(keys, ['b@lid', 'c@lid'])
+			const decoded = JSON.parse(write[TC_TOKEN_INDEX_KEY].token.toString()) as string[]
+			expect(decoded.sort()).toEqual(['a@lid', 'b@lid', 'c@lid'])
+		})
+
+		it('drops the sentinel key from the added set', async () => {
+			const keys = createMockKeys()
+			;(keys.get as any).mockResolvedValue({})
+			const write = await buildMergedTcTokenIndexWrite(keys, [TC_TOKEN_INDEX_KEY, 'a@lid'])
+			const decoded = JSON.parse(write[TC_TOKEN_INDEX_KEY].token.toString()) as string[]
+			expect(decoded).toEqual(['a@lid'])
+		})
+
+		it('handles empty inputs', async () => {
+			const keys = createMockKeys()
+			;(keys.get as any).mockResolvedValue({})
+			const write = await buildMergedTcTokenIndexWrite(keys, [])
+			const decoded = JSON.parse(write[TC_TOKEN_INDEX_KEY].token.toString()) as string[]
+			expect(decoded).toEqual([])
+		})
+	})
+})
+
+// ─── storeTcTokensFromIqResult — isRegularUser gating + monotonicity ───
+
+describe('storeTcTokensFromIqResult — gating and monotonicity', () => {
+	const PEER_PN = '5511999999999@s.whatsapp.net'
+	const PEER_LID = '123456@lid'
+
+	const getLIDForPN = jest.fn<(pn: string) => Promise<string | null>>(async (pn: string) => {
+		if (pn === PEER_PN) return PEER_LID
+		return null
+	})
+
+	beforeEach(() => {
+		getLIDForPN.mockClear()
+	})
+
+	const buildIqResult = (jid: string, tokenBytes: Uint8Array, t: string): BinaryNode => ({
+		tag: 'iq',
+		attrs: {},
+		content: [
+			{
+				tag: 'tokens',
+				attrs: {},
+				content: [
+					{
+						tag: 'token',
+						attrs: { jid, type: 'trusted_contact', t },
+						content: tokenBytes
+					}
+				]
+			}
+		]
+	})
+
+	it('skips PSA WID (jid="0") even if returned in tokens block', async () => {
+		const keys = createMockKeys()
+		;(keys.get as any).mockResolvedValue({})
+		await storeTcTokensFromIqResult({
+			result: buildIqResult('myDeviceJid@s.whatsapp.net', Buffer.from([0x01, 0x02]), '1700000000'),
+			fallbackJid: '0@s.whatsapp.net',
+			keys,
+			getLIDForPN
+		})
+		expect(keys.set).not.toHaveBeenCalled()
+	})
+
+	it('skips bot phone numbers', async () => {
+		const keys = createMockKeys()
+		;(keys.get as any).mockResolvedValue({})
+		await storeTcTokensFromIqResult({
+			result: buildIqResult('myDeviceJid@s.whatsapp.net', Buffer.from([0x01, 0x02]), '1700000000'),
+			fallbackJid: '13135550000@s.whatsapp.net',
+			keys,
+			getLIDForPN
+		})
+		expect(keys.set).not.toHaveBeenCalled()
+	})
+
+	it('skips MetaAI (@bot server)', async () => {
+		const keys = createMockKeys()
+		;(keys.get as any).mockResolvedValue({})
+		await storeTcTokensFromIqResult({
+			result: buildIqResult('myDeviceJid@s.whatsapp.net', Buffer.from([0x01, 0x02]), '1700000000'),
+			fallbackJid: 'meta-ai@bot',
+			keys,
+			getLIDForPN
+		})
+		expect(keys.set).not.toHaveBeenCalled()
+	})
+
+	it('uses fallbackJid (NOT the token node jid which is own device) as storage source', async () => {
+		const keys = createMockKeys()
+		;(keys.get as any).mockResolvedValue({})
+		const onNewJidStored = jest.fn()
+		await storeTcTokensFromIqResult({
+			result: buildIqResult('myDeviceJid:1@s.whatsapp.net', Buffer.from([0xaa, 0xbb]), '1700000000'),
+			fallbackJid: PEER_PN,
+			keys,
+			getLIDForPN,
+			onNewJidStored
+		})
+		expect(keys.set).toHaveBeenCalled()
+		const setArgs = (keys.set.mock.calls[0]?.[0] as { tctoken: Record<string, unknown> }).tctoken
+		expect(Object.keys(setArgs)).toContain(PEER_LID)
+		expect(onNewJidStored).toHaveBeenCalledWith(PEER_LID)
+	})
+
+	it('skips when incoming timestamp is older than existing (monotonicity)', async () => {
+		const keys = createMockKeys()
+		;(keys.get as any).mockResolvedValue({
+			[PEER_LID]: { token: Buffer.from([0x99]), timestamp: '1800000000' }
+		})
+		await storeTcTokensFromIqResult({
+			result: buildIqResult('myDeviceJid@s.whatsapp.net', Buffer.from([0xaa]), '1700000000'),
+			fallbackJid: PEER_PN,
+			keys,
+			getLIDForPN
+		})
+		expect(keys.set).not.toHaveBeenCalled()
+	})
+
+	it('skips timestamp-less tokens (would be immediately expired)', async () => {
+		const keys = createMockKeys()
+		;(keys.get as any).mockResolvedValue({})
+		await storeTcTokensFromIqResult({
+			result: {
+				tag: 'iq',
+				attrs: {},
+				content: [
+					{
+						tag: 'tokens',
+						attrs: {},
+						content: [
+							{
+								tag: 'token',
+								attrs: { jid: 'd@s.whatsapp.net', type: 'trusted_contact' },
+								content: Buffer.from([0x01])
+							}
+						]
+					}
+				]
+			},
+			fallbackJid: PEER_PN,
+			keys,
+			getLIDForPN
+		})
+		expect(keys.set).not.toHaveBeenCalled()
+	})
+})

src/__tests__/Utils/unified-session.test.ts

@@ -29,8 +29,7 @@ const TimeMs = {
 jest.mock('../../Utils/prometheus-metrics.js', () => ({
 	metrics: {
 		socketEvents: { inc: jest.fn() },
-		errors: { inc: jest.fn() },
+		errors: { inc: jest.fn() }
-		circuitBreakerTrips: { inc: jest.fn() }
 	}
 }))
 
@@ -59,7 +58,6 @@ describe('UnifiedSessionManager', () => {
 		manager = createUnifiedSessionManager({
 			enabled: true,
 			logger: mockLogger as any,
-			enableCircuitBreaker: false, // Disable for simpler testing
 			sendNode: mockSendNode
 		})
 	})
@@ -356,7 +354,11 @@ describe('shouldEnableUnifiedSession', () => {
 	})
 })
 
-describe('UnifiedSessionManager with CircuitBreaker', () => {
+describe('UnifiedSessionManager — non-critical send semantics', () => {
+	// The previous "with CircuitBreaker" suite is gone — telemetry no longer
+	// uses a circuit breaker. Verify equivalent behavior still holds:
+	// failures are swallowed (telemetry is non-critical) and don't propagate.
+
 	let manager: UnifiedSessionManager
 	let mockSendNode: MockSendNode
 
@@ -366,7 +368,6 @@ describe('UnifiedSessionManager with CircuitBreaker', () => {
 		manager = createUnifiedSessionManager({
 			enabled: true,
 			logger: createMockLogger() as any,
-			enableCircuitBreaker: true,
 			sendNode: mockSendNode
 		})
 	})
@@ -375,24 +376,13 @@ describe('UnifiedSessionManager with CircuitBreaker', () => {
 		manager.destroy()
 	})
 
-	it('should work with circuit breaker enabled', async () => {
+	it('should send telemetry once per call', async () => {
 		await manager.send('login')
 		expect(mockSendNode).toHaveBeenCalledTimes(1)
 	})
 
-	it('should handle circuit breaker failures gracefully', async () => {
+	it('should swallow send failures gracefully (telemetry is non-critical)', async () => {
-		// Make send fail multiple times to trigger circuit breaker
+		mockSendNode.mockRejectedValueOnce(new Error('boom'))
-		let callCount = 0
-		mockSendNode.mockImplementation(async () => {
-			callCount++
-			if (callCount <= 3) {
-				throw new Error(`Fail ${callCount}`)
-			}
-		})
-
-		// These should not throw even with failures
-		await expect(manager.send('login')).resolves.toBeUndefined()
-		await expect(manager.send('login')).resolves.toBeUndefined()
 		await expect(manager.send('login')).resolves.toBeUndefined()
 	})
 })

src/__tests__/bigint-validation.test.ts

@@ -0,0 +1,209 @@
+import Long from 'long'
+import $protobuf from 'protobufjs/minimal.js'
+
+const $util = $protobuf.util
+
+// proto implementation
+function longToStringOld(value: any, unsigned?: boolean): string {
+	if (typeof value === 'string') return value
+	if (typeof value === 'number') return String(value)
+	if (!$util.Long) return String(value)
+	const normalized = ($util.Long as any).fromValue(value)
+	const prepared =
+		unsigned && normalized && typeof normalized.toUnsigned === 'function' ? normalized.toUnsigned() : normalized
+	return prepared.toString()
+}
+
+// bigint implementation
+function longToStringNew(value: any, unsigned?: boolean): string {
+	if (typeof value === 'string') return value
+	if (typeof value === 'number') return String(value)
+	if (value && typeof value.low === 'number' && typeof value.high === 'number') {
+		const high = value.high | 0
+		const lo = BigInt(value.low >>> 0)
+		const hi = BigInt(value.high >>> 0)
+		const combined = (hi << 32n) | lo
+		if (!unsigned && high < 0) {
+			return (combined - (1n << 64n)).toString()
+		}
+
+		return combined.toString()
+	}
+
+	return String(value)
+}
+
+function longToNumberOld(value: any, unsigned?: boolean): number {
+	if (typeof value === 'number') return value
+	if (typeof value === 'string') return Number(value)
+	if (!$util.Long) return Number(value)
+	const normalized = ($util.Long as any).fromValue(value)
+	const prepared =
+		unsigned && normalized && typeof normalized.toUnsigned === 'function'
+			? normalized.toUnsigned()
+			: typeof normalized.toSigned === 'function'
+				? normalized.toSigned()
+				: normalized
+	return prepared.toNumber()
+}
+
+function longToNumberNew(value: any, unsigned?: boolean): number {
+	if (typeof value === 'number') return value
+	if (typeof value === 'string') return Number(value)
+	if (value && typeof value.low === 'number' && typeof value.high === 'number') {
+		const high = value.high | 0
+		const lo = BigInt(value.low >>> 0)
+		const hi = BigInt(value.high >>> 0)
+		const combined = (hi << 32n) | lo
+		if (!unsigned && high < 0) {
+			return Number(combined - (1n << 64n))
+		}
+
+		return Number(combined)
+	}
+
+	return Number(value)
+}
+
+describe('BigInt vs Long equivalence validation', () => {
+	// Test cases: [description, Long value, unsigned flag]
+	const testCases: [string, Long, boolean][] = [
+		// Basic values
+		['zero unsigned', Long.fromNumber(0, true), true],
+		['zero signed', Long.fromNumber(0, false), false],
+		['one unsigned', Long.fromNumber(1, true), true],
+		['one signed', Long.fromNumber(1, false), false],
+
+		// Typical WhatsApp timestamps (seconds since epoch)
+		['timestamp 2023', Long.fromNumber(1700000000, true), true],
+		['timestamp 2025', Long.fromNumber(1750000000, true), true],
+		['timestamp as signed', Long.fromNumber(1700000000, false), false],
+
+		// File sizes
+		['small file', Long.fromNumber(1024, true), true],
+		['medium file 10MB', Long.fromNumber(10485760, true), true],
+		['large file 2GB', Long.fromNumber(2147483648, true), true],
+
+		// Boundary values - 32-bit
+		['max int32', Long.fromNumber(2147483647, false), false],
+		['min int32', Long.fromNumber(-2147483648, false), false],
+		['max uint32', Long.fromNumber(4294967295, true), true],
+
+		// Around MAX_SAFE_INTEGER
+		['MAX_SAFE_INTEGER', Long.fromString('9007199254740991', false), false],
+		['MAX_SAFE_INTEGER + 1', Long.fromString('9007199254740992', false), false],
+		['MAX_SAFE_INTEGER unsigned', Long.fromString('9007199254740991', true), true],
+
+		// Large unsigned values
+		['large unsigned', Long.fromString('9999999999999999999', true), true],
+		['max uint64', Long.fromString('18446744073709551615', true), true],
+		['max uint64 - 1', Long.fromString('18446744073709551614', true), true],
+
+		// Signed negative values
+		['negative one', Long.fromNumber(-1, false), false],
+		['negative small', Long.fromNumber(-100, false), false],
+		['negative large', Long.fromNumber(-2147483648, false), false],
+		['min int64', Long.fromString('-9223372036854775808', false), false],
+		['max int64', Long.fromString('9223372036854775807', false), false],
+		['-1 as signed Long', Long.fromBits(-1, -1, false), false],
+
+		// Tricky bit patterns
+		['high=1, low=0', Long.fromBits(0, 1, true), true],
+		['high=0, low=-1 (0xFFFFFFFF)', Long.fromBits(-1, 0, true), true],
+		['high=-1, low=-1 unsigned (max uint64)', Long.fromBits(-1, -1, true), true],
+		['high=0x7FFFFFFF, low=0xFFFFFFFF (max int64)', Long.fromBits(-1, 0x7fffffff, false), false],
+		['high=0x80000000, low=0 (min int64)', Long.fromBits(0, -2147483648, false), false],
+
+		// Powers of 2
+		['2^32', Long.fromString('4294967296', true), true],
+		['2^32 signed', Long.fromString('4294967296', false), false],
+		['2^48', Long.fromString('281474976710656', true), true],
+		['2^63', Long.fromString('9223372036854775808', true), true]
+	]
+
+	describe('longToString equivalence', () => {
+		for (const [desc, longVal, unsigned] of testCases) {
+			it(`${desc}: Long(${longVal.low}, ${longVal.high}, ${unsigned})`, () => {
+				const oldResult = longToStringOld(longVal, unsigned)
+				const newResult = longToStringNew(longVal, unsigned)
+				expect(newResult).toBe(oldResult)
+			})
+		}
+	})
+
+	describe('longToNumber equivalence', () => {
+		for (const [desc, longVal, unsigned] of testCases) {
+			it(`${desc}: Long(${longVal.low}, ${longVal.high}, ${unsigned})`, () => {
+				const oldResult = longToNumberOld(longVal, unsigned)
+				const newResult = longToNumberNew(longVal, unsigned)
+				// For large values, both may lose precision equally (Number limitation)
+				// So we compare string representations
+				expect(newResult.toString()).toBe(oldResult.toString())
+			})
+		}
+	})
+
+	describe('non-Long inputs (fallback paths)', () => {
+		it('string passthrough', () => {
+			expect(longToStringNew('12345')).toBe('12345')
+			expect(longToStringNew('0')).toBe('0')
+		})
+		it('number passthrough', () => {
+			expect(longToStringNew(42)).toBe('42')
+			expect(longToStringNew(0)).toBe('0')
+			expect(longToStringNew(-1)).toBe('-1')
+		})
+		it('null/undefined fallback', () => {
+			expect(longToStringNew(null)).toBe('null')
+			expect(longToStringNew(undefined)).toBe('undefined')
+		})
+		it('object without low/high', () => {
+			expect(longToStringNew({ foo: 'bar' })).toBe('[object Object]')
+		})
+
+		// Defensive: a raw {low, high} JSON object can carry `high` as an
+		// unsigned 32-bit value (Long.fromBits would normalize via `| 0`,
+		// but plain JSON deserialization does not). Without `value.high | 0`
+		// the sign-bit check fails and the result is interpreted as unsigned.
+		// Upstream Baileys PR #2333 has this latent bug; InfiniteAPI fixes it.
+		it('signed sign-bit detection on raw unsigned high (-1 as {low: -1, high: 4294967295})', () => {
+			const raw = { low: -1, high: 0xffffffff }
+			// signed: -1
+			expect(longToStringNew(raw, false)).toBe('-1')
+			// unsigned: max uint64
+			expect(longToStringNew(raw, true)).toBe('18446744073709551615')
+		})
+
+		it('signed sign-bit detection on raw unsigned high (-4294967296 as {low: 0, high: 4294967295})', () => {
+			const raw = { low: 0, high: 0xffffffff }
+			// signed: -4294967296 (high word = -1 after normalization)
+			expect(longToStringNew(raw, false)).toBe('-4294967296')
+			// unsigned: 0xFFFFFFFF00000000 = 18446744069414584320
+			expect(longToStringNew(raw, true)).toBe('18446744069414584320')
+		})
+	})
+
+	describe('fuzz: random Long values', () => {
+		it('100 random unsigned values match', () => {
+			for (let i = 0; i < 100; i++) {
+				const low = (Math.random() * 0xffffffff) | 0
+				const high = (Math.random() * 0xffffffff) | 0
+				const longVal = Long.fromBits(low, high, true)
+				const oldResult = longToStringOld(longVal, true)
+				const newResult = longToStringNew(longVal, true)
+				expect(newResult).toBe(oldResult)
+			}
+		})
+
+		it('100 random signed values match', () => {
+			for (let i = 0; i < 100; i++) {
+				const low = (Math.random() * 0xffffffff) | 0
+				const high = (Math.random() * 0xffffffff) | 0
+				const longVal = Long.fromBits(low, high, false)
+				const oldResult = longToStringOld(longVal, false)
+				const newResult = longToStringNew(longVal, false)
+				expect(newResult).toBe(oldResult)
+			}
+		})
+	})
+})

src/__tests__/binary/reconnection-sync-skip.test.ts

@@ -0,0 +1,146 @@
+import { jest } from '@jest/globals'
+import { proto, type WAMessage } from '../..'
+import { DEFAULT_CONNECTION_CONFIG } from '../../Defaults'
+import makeWASocket from '../../Socket'
+import { makeSession, mockWebSocket } from '../TestUtils/session'
+
+mockWebSocket()
+
+// chats.ts treats a connection as a reconnection when EITHER signal is true:
+//   1. authState.creds.accountSyncCounter > 0
+//      (at least one full history sync completed in a previous session)
+//   2. socketSkippedOfflineBuffer (forwarded from socket.ts as `skipOfflineBuffer`)
+//      (socket.ts already decided to skip the offline buffer, e.g. because
+//       routingInfo was stale and was discarded on startup)
+// On reconnection, AwaitingInitialSync is skipped and the buffer is flushed
+// immediately so live messages are not held in the initial-sync window.
+describe('Reconnection Sync Skip', () => {
+	it('should skip the history sync wait on reconnection (accountSyncCounter > 0)', async () => {
+		const { state, clear } = await makeSession()
+
+		state.creds.me = { id: '1234567890:1@s.whatsapp.net', name: 'Test User' }
+		// Simulate a session that has already synced before
+		state.creds.accountSyncCounter = 1
+
+		const sock = makeWASocket({
+			...DEFAULT_CONNECTION_CONFIG,
+			auth: state
+		})
+
+		const messageListener = jest.fn()
+		sock.ev.on('messages.upsert', messageListener)
+
+		// Simulate receiving pending notifications (triggers AwaitingInitialSync)
+		sock.ev.emit('connection.update', { receivedPendingNotifications: true })
+
+		// Emit a message immediately after — if the wait is skipped,
+		// the buffer should already be flushed and this message should be delivered.
+		const msg = proto.WebMessageInfo.fromObject({
+			key: { remoteJid: '1234567890@s.whatsapp.net', fromMe: false, id: 'MSG_AFTER_RECONNECT' },
+			messageTimestamp: Date.now() / 1000,
+			message: { conversation: 'Hello after reconnect' }
+		}) as WAMessage
+		sock.ev.emit('messages.upsert', { messages: [msg], type: 'notify' })
+
+		await new Promise(resolve => setTimeout(resolve, 50))
+
+		// Message should be delivered immediately, NOT buffered
+		expect(messageListener).toHaveBeenCalledTimes(1)
+		expect(messageListener).toHaveBeenCalledWith(
+			expect.objectContaining({
+				messages: expect.arrayContaining([expect.objectContaining({ key: msg.key })]),
+				type: 'notify'
+			})
+		)
+
+		await sock.end(new Error('Test completed'))
+		await clear()
+	})
+
+	it('should skip the history sync wait when socketSkippedOfflineBuffer is true (stale routingInfo, accountSyncCounter === 0)', async () => {
+		const { state, clear } = await makeSession()
+
+		state.creds.me = { id: '1234567890:1@s.whatsapp.net', name: 'Test User' }
+		// Fresh-looking session from the counter perspective
+		state.creds.accountSyncCounter = 0
+		// But routingInfo is present and we ask the socket to discard it on start.
+		// socket.ts will set hadStaleRoutingInfo=true → skipOfflineBuffer=true,
+		// which chats.ts forwards as socketSkippedOfflineBuffer. Without this
+		// branch, the buffers would be misaligned (offline buffer skipped while
+		// AwaitingInitialSync still waits) and live messages would stall.
+		state.creds.routingInfo = Buffer.from([1, 2, 3, 4])
+
+		const sock = makeWASocket({
+			...DEFAULT_CONNECTION_CONFIG,
+			auth: state,
+			clearRoutingInfoOnStart: true
+		})
+
+		const messageListener = jest.fn()
+		sock.ev.on('messages.upsert', messageListener)
+
+		sock.ev.emit('connection.update', { receivedPendingNotifications: true })
+
+		const msg = proto.WebMessageInfo.fromObject({
+			key: { remoteJid: '1234567890@s.whatsapp.net', fromMe: false, id: 'MSG_AFTER_STALE_ROUTING' },
+			messageTimestamp: Date.now() / 1000,
+			message: { conversation: 'Hello after stale routing reconnect' }
+		}) as WAMessage
+		sock.ev.emit('messages.upsert', { messages: [msg], type: 'notify' })
+
+		await new Promise(resolve => setTimeout(resolve, 50))
+
+		expect(messageListener).toHaveBeenCalledTimes(1)
+		expect(messageListener).toHaveBeenCalledWith(
+			expect.objectContaining({
+				messages: expect.arrayContaining([expect.objectContaining({ key: msg.key })]),
+				type: 'notify'
+			})
+		)
+
+		await sock.end(new Error('Test completed'))
+		await clear()
+	})
+
+	it('should still wait for history sync on fresh pairing (both signals false)', async () => {
+		const { state, clear } = await makeSession()
+
+		state.creds.me = { id: '1234567890:1@s.whatsapp.net', name: 'Test User' }
+		// Fresh pairing — both reconnect signals are false:
+		// accountSyncCounter is 0 (default) and no stale routingInfo to clear.
+		state.creds.accountSyncCounter = 0
+
+		const sock = makeWASocket({
+			...DEFAULT_CONNECTION_CONFIG,
+			auth: state
+		})
+
+		const messageListener = jest.fn()
+		sock.ev.on('messages.upsert', messageListener)
+
+		sock.ev.emit('connection.update', { receivedPendingNotifications: true })
+
+		const msg = proto.WebMessageInfo.fromObject({
+			key: { remoteJid: '1234567890@s.whatsapp.net', fromMe: false, id: 'MSG_DURING_INITIAL_SYNC' },
+			messageTimestamp: Date.now() / 1000,
+			message: { conversation: 'Hello during initial sync' }
+		}) as WAMessage
+		sock.ev.emit('messages.upsert', { messages: [msg], type: 'notify' })
+
+		await new Promise(resolve => setTimeout(resolve, 50))
+
+		// Message should be BUFFERED (not delivered) because we're waiting for history sync
+		expect(messageListener).toHaveBeenCalledTimes(0)
+
+		// Drain the 2s AwaitingInitialSync timeout (chats.ts:1522) so its callback
+		// doesn't fire after Jest considers the test done — otherwise we get a
+		// "Cannot log after tests are done" warning from the post-teardown flush
+		// and the suite is flagged with --detectOpenHandles. After the timer
+		// fires, syncState becomes Online and the buffer flushes; that delivery
+		// is post-assertion and irrelevant to the test goal.
+		await new Promise(resolve => setTimeout(resolve, 2_100))
+
+		await sock.end(new Error('Test completed'))
+		await clear()
+	}, 10_000)
+})

src/__tests__/proto-tojson-long.test.ts

@@ -1,3 +1,4 @@
+import Long from 'long'
 import '../index.js'
 import { proto } from '../../WAProto/index.js'
 
@@ -28,4 +29,91 @@ describe('proto serialization', () => {
 		const json = message.toJSON()
 		expect(json.message?.imageMessage?.fileLength).toBe('1234567890123456789')
 	})
+
+	it('converts Long objects to strings correctly via BigInt fast path', () => {
+		const message = proto.WebMessageInfo.fromObject({
+			key: {
+				remoteJid: '123@s.whatsapp.net',
+				id: 'ABC123',
+				fromMe: false
+			},
+			messageTimestamp: Long.fromNumber(1700000000, true),
+			message: {
+				imageMessage: {
+					fileLength: Long.fromString('9876543210', true)
+				}
+			}
+		})
+
+		const json = message.toJSON()
+		expect(json.messageTimestamp).toBe('1700000000')
+		expect(json.message?.imageMessage?.fileLength).toBe('9876543210')
+	})
+
+	it('handles large unsigned Long values (> MAX_SAFE_INTEGER)', () => {
+		const message = proto.WebMessageInfo.fromObject({
+			key: {
+				remoteJid: '123@s.whatsapp.net',
+				id: 'ABC123',
+				fromMe: false
+			},
+			messageTimestamp: Long.fromString('18446744073709551615', true), // max uint64
+			message: {
+				imageMessage: {
+					fileLength: Long.fromString('9999999999999999999', true)
+				}
+			}
+		})
+
+		const json = message.toJSON()
+		expect(json.messageTimestamp).toBe('18446744073709551615')
+		expect(json.message?.imageMessage?.fileLength).toBe('9999999999999999999')
+	})
+
+	it('handles zero and small Long values', () => {
+		const message = proto.WebMessageInfo.fromObject({
+			key: {
+				remoteJid: '123@s.whatsapp.net',
+				id: 'ABC123',
+				fromMe: false
+			},
+			messageTimestamp: Long.fromNumber(0, true),
+			message: {
+				imageMessage: {
+					fileLength: Long.fromNumber(1, true)
+				}
+			}
+		})
+
+		const json = message.toJSON()
+		expect(json.messageTimestamp).toBe('0')
+		expect(json.message?.imageMessage?.fileLength).toBe('1')
+	})
+
+	it('roundtrips encode/decode with Long fields preserving values (> MAX_SAFE_INTEGER)', () => {
+		// Use uint64 values above Number.MAX_SAFE_INTEGER (2^53 - 1) so the
+		// roundtrip actually exercises the BigInt fast path on decode->toJSON.
+		// Safe integers would silently work even if longToString fell back to
+		// Number(value).
+		const original = proto.WebMessageInfo.fromObject({
+			key: {
+				remoteJid: '123@s.whatsapp.net',
+				id: 'ABC123',
+				fromMe: false
+			},
+			messageTimestamp: Long.fromString('18446744073709551615', true),
+			message: {
+				imageMessage: {
+					fileLength: Long.fromString('9999999999999999999', true)
+				}
+			}
+		})
+
+		const encoded = proto.WebMessageInfo.encode(original).finish()
+		const decoded = proto.WebMessageInfo.decode(encoded)
+		const json = decoded.toJSON()
+
+		expect(json.messageTimestamp).toBe('18446744073709551615')
+		expect(json.message?.imageMessage?.fileLength).toBe('9999999999999999999')
+	})
 })

src/index.ts

@@ -28,7 +28,16 @@ console.info = function (...args: unknown[]) {
 
 // Track errors by type + JID to avoid duplicates (using Map for better performance)
 const _errorTimestamps = new Map<string, number>()
-const DEDUP_WINDOW_MS = 150
+// Dedup window for repeated decrypt-error console lines (Bad MAC / Counter / etc).
+// Was 150ms, but retry attempts of the SAME message are typically ~300-1000ms apart,
+// so the second attempt fell outside the window and double-printed.
+//
+// TRADE-OFF: dedup key is `errorType + JID` (no message-id). With 5s, a burst of
+// errors for the SAME JID — even of slightly different categories or different
+// messages — collapses to one log line every 5s. This is intentional for a noisy
+// production stream; if you need per-message visibility, set BAILEYS_LOG_LEVEL=debug
+// to bypass this console-side dedup and see the structured pino logs in full.
+const DEDUP_WINDOW_MS = 5000
 
 console.error = function (...args: unknown[]) {
 	if (args.length > 0 && typeof args[0] === 'string') {
@@ -70,7 +79,7 @@ console.error = function (...args: unknown[]) {
 				const lastTime = _errorTimestamps.get(dedupeKey)
 
 				if (lastTime && now - lastTime < DEDUP_WINDOW_MS) {
-					return // Skip duplicate within 150ms window
+					return // Skip duplicate within DEDUP_WINDOW_MS window
 				}
 
 				_errorTimestamps.set(dedupeKey, now)