@vibexnpm/talkx 8.4.1 → 8.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "8.4.1",
+    "version": "8.6.0",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",

package/src/TalkFlowClient.js

@@ -72,6 +72,7 @@ class TalkFlowClient extends EventEmitter {
             reconnectDelay: options.reconnectDelay || DefaultConfig.reconnectDelay,
             maxReconnectDelay: options.maxReconnectDelay || DefaultConfig.maxReconnectDelay,
             maxReconnectAttempts: options.maxReconnectAttempts || DefaultConfig.maxReconnectAttempts,
+            reconnectRecoveryDelay: options.reconnectRecoveryDelay ?? DefaultConfig.reconnectRecoveryDelay,
             heartbeatIncoming: options.heartbeatIncoming || DefaultConfig.heartbeatIncoming,
             heartbeatOutgoing: options.heartbeatOutgoing || DefaultConfig.heartbeatOutgoing,
             // 탭 복귀 / 네트워크 복구 시 자동 재연결. false 로 꺼야 하므로 !== false 로 보존 —

package/src/chat/ChatClient.js

@@ -7,7 +7,7 @@
 
 import EventEmitter from '../utils/EventEmitter.js';
 import Logger from '../utils/Logger.js';
-import { WebSocketPaths, LogLevel, RoomListEventType, ChatRoomType, DefaultConfig } from '../constants.js';
+import { WebSocketPaths, LogLevel, RoomListEventType, ChatRoomType, DefaultConfig, ConnectionState } from '../constants.js';
 
 const MAX_FILES_PER_MESSAGE = 20;
 
@@ -49,6 +49,9 @@ class ChatClient extends EventEmitter {
         // 채팅방 리스트 구독 상태 (카톡 스타일 리스트 실시간 업데이트)
         this.roomListSubscribed = false;
 
+        // Gmail 메일함 변화 구독 상태 — 자동 구독하지 않는다(Gmail 을 연결한 화면에서 subscribeMail()).
+        this.mailSubscribed = false;
+
         // 현재 보고 있는 채팅방 ID (이 방에서만 자동 읽음 처리)
         this._activeRoomId = null;
 
@@ -183,6 +186,8 @@ class ChatClient extends EventEmitter {
         // 상수로 두면 maxSyncPages 튜닝 시 조용히 어긋나므로 config 에서 파생시킨다 (설계 §7).
         this._maxSeenPerRoom = Math.max(200, this.maxSyncPages * this.syncPageSize + 100);
 
+        this._reconnectSyncGeneration = 0;
+        this._delayedReconnectSyncTimer = null;
         this._installSyncTriggers();
     }
 
@@ -202,8 +207,20 @@ class ChatClient extends EventEmitter {
         // syncOnReconnect 옵션 + anchor 있는 방이라는 두 겹 필터가 걸려 있어서, 거기 얹으면 옵션이
         // 꺼져 있거나 그 방에서 메시지를 받은 적이 없을 때 replay 가 조용히 빠진다.
         this._onReconnectedForSync = ({ attempts } = {}) => {
+            this._cancelDelayedReconnectSync();
+            const generation = this._reconnectSyncGeneration;
             this.syncAfterReconnect(`reconnected:${attempts ?? 0}`)
-                .catch((error) => this.logger.warn('Gap sync after reconnect failed:', error));
+                .catch((error) => this.logger.warn('Gap sync after reconnect failed:', error))
+                .then((cursors) => {
+                    if (!this.syncOnReconnect || !cursors || generation !== this._reconnectSyncGeneration) return;
+                    // SUBSCRIBE 전송과 SimpleBroker 등록은 다른 시점이다. 첫 snapshot 뒤의 공백을 다시 읽는다.
+                    this._delayedReconnectSyncTimer = setTimeout(() => {
+                        this._delayedReconnectSyncTimer = null;
+                        this._supplementAfterReconnect(cursors, generation)
+                            .catch(error => this.logger.warn('Delayed gap sync failed:', error));
+                    }, 1000);
+                    this._delayedReconnectSyncTimer.unref?.();
+                });
             this.resumeAssistantStreams(`reconnected:${attempts ?? 0}`)
                 .catch((error) => this.logger.warn('Assistant stream replay after reconnect failed:', error));
         };
@@ -214,6 +231,10 @@ class ChatClient extends EventEmitter {
                 .catch((error) => this.logger.warn('Assistant stream replay after resume failed:', error));
         };
 
+        this._onStateChangeForSync = ({ state }) => {
+            if (state !== ConnectionState.CONNECTED) this._cancelDelayedReconnectSync();
+        };
+        this.connectionManager.on('stateChange', this._onStateChangeForSync);
         this.connectionManager.on('reconnected', this._onReconnectedForSync);
         this.connectionManager.on('resumed', this._onResumedForSync);
     }
@@ -1593,8 +1614,7 @@ class ChatClient extends EventEmitter {
      * @private
      * @returns {Promise<Object|null>} 복구 결과. 대상이 아니면 null.
      */
-    async _syncRoom(roomId) {
-        const anchor = this._anchor.get(roomId);
+    async _syncRoom(roomId, anchor = this._anchor.get(roomId), quiet = false) {
         // 이 세션에서 아직 받은 메시지가 없는 방 — enterRoom 의 초기 로드가 담당한다.
         if (!anchor) return null;
         if (this._syncInFlight.has(roomId)) return null;
@@ -1628,25 +1648,25 @@ class ChatClient extends EventEmitter {
             if (hasMore) {
                 // 상한 초과 — 버퍼를 통째로 버리고 최신 페이지로 전환한다(부분 replay 금지).
                 this.logger.info(`Gap too large, falling back to latest page: room=${roomId}`);
-                this.emit('gapTruncated', { roomId, fetched: buffer.length });
+                if (!quiet) this.emit('gapTruncated', { roomId, fetched: buffer.length });
                 const reloaded = await this._reloadLatestPage(roomId, genAtStart);
                 return {
-                    roomId, recovered: reloaded, truncated: true, durationMs: Date.now() - startedAt
+                    roomId, cursor: this._anchor.get(roomId), recovered: reloaded, truncated: true, durationMs: Date.now() - startedAt
                 };
             }
 
             const recovered = this._replayMessages(roomId, buffer);
             this._commitAnchorFromSync(roomId, cursor, genAtStart);
-            return { roomId, recovered, truncated: false, durationMs: Date.now() - startedAt };
+            return { roomId, cursor, recovered, truncated: false, durationMs: Date.now() - startedAt };
 
         } catch (error) {
             if (this._isCursorExpired(error)) {
                 // retention 정리 등으로 앵커가 사라짐 — 최신 페이지로 복구한다.
                 this.logger.warn(`Sync cursor expired, reloading latest: room=${roomId}`);
-                this.emit('gapTruncated', { roomId, fetched: 0, reason: 'cursorExpired' });
+                if (!quiet) this.emit('gapTruncated', { roomId, fetched: 0, reason: 'cursorExpired' });
                 const reloaded = await this._reloadLatestPage(roomId, genAtStart);
                 return {
-                    roomId, recovered: reloaded, truncated: true, durationMs: Date.now() - startedAt
+                    roomId, cursor: this._anchor.get(roomId), recovered: reloaded, truncated: true, durationMs: Date.now() - startedAt
                 };
             }
             throw error;
@@ -1662,7 +1682,7 @@ class ChatClient extends EventEmitter {
      * 상호 배타적이라 중복 실행되지 않는다.</p>
      *
      * @param {string} [reason]
-     * @returns {Promise<void>}
+     * @returns {Promise<Map<string, string>|undefined>} 1차 조회 cursor — 내부 보충 조회용.
      */
     async syncAfterReconnect(reason = 'manual') {
         if (!this.syncOnReconnect) return;
@@ -1676,11 +1696,15 @@ class ChatClient extends EventEmitter {
         this.emit('syncStarted', { roomIds, reason });
         const startedAt = Date.now();
         const rooms = [];
+        const cursors = new Map();
 
         for (const roomId of roomIds) {
             try {
                 const result = await this._syncRoom(roomId);
-                if (result) rooms.push(result);
+                if (result) {
+                    rooms.push(result);
+                    cursors.set(roomId, result.cursor);
+                }
             } catch (error) {
                 // 한 방의 실패가 나머지 방 복구를 막지 않게 한다.
                 this.logger.warn(`Gap sync failed: room=${roomId}`, error);
@@ -1695,6 +1719,17 @@ class ChatClient extends EventEmitter {
             durationMs: Date.now() - startedAt,
             reason
         });
+        return cursors;
+    }
+
+    /** 첫 조회가 끝난 cursor부터 조용히 보충한다. 목록·동기화 이벤트는 첫 조회의 책임이다. */
+    async _supplementAfterReconnect(cursors, generation) {
+        for (const [roomId, cursor] of cursors) {
+            if (generation !== this._reconnectSyncGeneration) return;
+            if (!this.subscribedRooms.has(roomId)) continue;
+            try { await this._syncRoom(roomId, cursor, true); }
+            catch (error) { this.logger.warn(`Supplemental gap sync failed: room=${roomId}`, error); }
+        }
     }
 
     /**
@@ -2732,6 +2767,61 @@ class ChatClient extends EventEmitter {
         return this.roomListSubscribed;
     }
 
+    /**
+     * Gmail 메일함 변화 구독 — {@code /user/queue/mail}. 받은 이벤트를 {@code mailChanged} 로 그대로 낸다.
+     *
+     * <p>새 메일 알림은 최상위 클라이언트의 {@code newMail} 을 쓴다 — 웹소켓 이벤트의 미리보기와 포그라운드 FCM 메일 푸시를
+     * 합쳐 메일마다 한 번만 낸다. 재연결 때는 연결 관리자가 구독을 되살린다(이벤트는 최대 한 번 전달이라 재연결·창 포커스 때
+     * 안읽은 수와 목록을 다시 읽는다).</p>
+     */
+    async subscribeMail() {
+        if (this.mailSubscribed) {
+            this.logger.debug('Already subscribed to mail');
+            return;
+        }
+
+        await this.connectionManager.subscribe(WebSocketPaths.MAIL_USER_DESTINATION, (event) => {
+            this._handleMailEvent(event);
+        });
+
+        this.mailSubscribed = true;
+        this.logger.info('Subscribed to mail');
+        this.emit('mailSubscribed', {});
+    }
+
+    /**
+     * Gmail 메일함 변화 구독 해제.
+     */
+    unsubscribeMail() {
+        if (!this.mailSubscribed) {
+            return;
+        }
+
+        this.connectionManager.unsubscribe(WebSocketPaths.MAIL_USER_DESTINATION);
+        this.mailSubscribed = false;
+
+        this.logger.info('Unsubscribed from mail');
+        this.emit('mailUnsubscribed', {});
+    }
+
+    /**
+     * Gmail 메일함 변화 구독 여부.
+     * @returns {boolean}
+     */
+    isMailSubscribed() {
+        return this.mailSubscribed;
+    }
+
+    /** 메일 이벤트 — 보낸 사람·제목이 실리므로 내용은 로그에 남기지 않는다(연결 ID·건수만). */
+    _handleMailEvent(event) {
+        if (!event || event.eventType !== 'MAIL_CHANGED') {
+            return;
+        }
+        this.logger.debug('Mail changed:', event.connectionId,
+            Array.isArray(event.messages) ? event.messages.length : 0);
+        this.emit('mailChanged', event);
+    }
+
     /**
      * 메시지 읽음 처리
      * @param {string} roomId - 채팅방 ID
@@ -3806,13 +3896,16 @@ class ChatClient extends EventEmitter {
         this.logger.setLevel(level);
     }
 
-    /**
-     * 리소스 정리.
-     *
-     * <p>{@link #unsubscribeRoom} 에서 방별 타이머를 정리하지만, 구독 목록에 없는
-     * roomId 의 debounce 타이머가 남아 있을 수 있어 Map 전체를 명시적으로 비운다.</p>
-     */
+    _cancelDelayedReconnectSync() {
+        this._reconnectSyncGeneration++;
+        clearTimeout(this._delayedReconnectSyncTimer);
+        this._delayedReconnectSyncTimer = null;
+    }
+
+    /** 구독, 예약된 복구, 방별 진행 표시를 정리한다. */
     destroy() {
+        this._cancelDelayedReconnectSync();
+        this.connectionManager.off?.('stateChange', this._onStateChangeForSync);
         this.unsubscribeAllRooms();
         if (this.roomListSubscribed) {
             this.unsubscribeRoomList();

package/src/constants.js

@@ -384,6 +384,10 @@ export const WebSocketPaths = {
     // 클라이언트는 "/user/queue/rooms" 구독 (Spring STOMP 가 세션별 자동 격리)
     ROOM_LIST_USER_DESTINATION: '/user/queue/rooms',
 
+    // Gmail 메일함 변화 (서버 GMAIL_MAILBOX_FEATURES_DESIGN.md §6-6·§6-7)
+    // 서버가 convertAndSendToUser(userId, "/queue/mail", MAIL_CHANGED) 로 전송 — 새 메일이면 messages[] 미리보기 포함
+    MAIL_USER_DESTINATION: '/user/queue/mail',
+
     // WebRTC destinations
     getWebRTCDestination: (roomId) => `/topic/webrtc/${roomId}`,
     getWebRTCUserDestination: () => `/user/queue/webrtc`,
@@ -434,6 +438,7 @@ export const DefaultConfig = {
     // 지수 백오프 상한 — 서버 재시작 시 전 클라이언트가 고정 간격으로 몰리는 것을 완화.
     maxReconnectDelay: 30000,
     maxReconnectAttempts: 10,
+    reconnectRecoveryDelay: 60000,
     heartbeatIncoming: 10000,
     heartbeatOutgoing: 10000,
 

package/src/core/ConnectionManager.js

@@ -37,7 +37,8 @@ class ConnectionManager extends EventEmitter {
      * @param {string} options.projectId - 프로젝트 ID
      * @param {boolean} [options.useSockJS=true] - SockJS 사용 여부
      * @param {number} [options.reconnectDelay] - 재연결 지연 시간
-     * @param {number} [options.maxReconnectAttempts] - 최대 재연결 시도 횟수
+     * @param {number} [options.maxReconnectAttempts] - 한 묶음의 최대 재연결 시도 횟수
+     * @param {number} [options.reconnectRecoveryDelay=60000] - 기존 연결의 재시도 소진 후 대기(ms), 0이면 비활성화
      * @param {number} [options.heartbeatIncoming] - 수신 하트비트 간격
      * @param {number} [options.heartbeatOutgoing] - 발신 하트비트 간격
      * @param {number} [options.logLevel] - 로그 레벨
@@ -54,6 +55,7 @@ class ConnectionManager extends EventEmitter {
         this.reconnectDelay = options.reconnectDelay || DefaultConfig.reconnectDelay;
         this.maxReconnectDelay = options.maxReconnectDelay || DefaultConfig.maxReconnectDelay;
         this.maxReconnectAttempts = options.maxReconnectAttempts || DefaultConfig.maxReconnectAttempts;
+        this.reconnectRecoveryDelay = options.reconnectRecoveryDelay ?? DefaultConfig.reconnectRecoveryDelay;
         this.heartbeatIncoming = options.heartbeatIncoming || DefaultConfig.heartbeatIncoming;
         this.heartbeatOutgoing = options.heartbeatOutgoing || DefaultConfig.heartbeatOutgoing;
         this.resumeOnVisibility = options.resumeOnVisibility !== false;
@@ -77,6 +79,9 @@ class ConnectionManager extends EventEmitter {
         // forceReconnect 단일 실행 보장 (복귀 이벤트 3종이 거의 동시에 들어온다).
         this._forceReconnectPromise = null;
         this._lifecycleHandlers = null;
+        this._recoveryTimer = null;
+        this._terminalAuthError = false;
+        this._recoveryEligible = false;
 
         this._installLifecycleListeners();
     }
@@ -148,7 +153,7 @@ class ConnectionManager extends EventEmitter {
      * @private
      */
     _onResume(reason) {
-        if (!this.resumeOnVisibility || this._intentionalDisconnect) {
+        if (!this.resumeOnVisibility || this._intentionalDisconnect || this._terminalAuthError) {
             return;
         }
 
@@ -209,26 +214,26 @@ class ConnectionManager extends EventEmitter {
      * @returns {Promise<void>}
      */
     async forceReconnect(reason) {
-        if (this._intentionalDisconnect || this.state === ConnectionState.CONNECTING) {
+        if (this._intentionalDisconnect || this._terminalAuthError || this.state === ConnectionState.CONNECTING) {
             return;
         }
 
         // 단일 실행 — 복귀 시 visibilitychange / pageshow / online 이 거의 동시에 들어오는데,
         // deactivate() 를 await 하는 동안 state 는 아직 CONNECTED 라 재진입 가드가 없으면
         // 두 번째 resume 이 그대로 통과해 클라이언트를 이중으로 만든다.
-        if (this._forceReconnectPromise) {
-            this.logger.debug(`Force reconnect already in progress, joining: ${reason}`);
-            return this._forceReconnectPromise;
+        if (!this._forceReconnectPromise) {
+            this._forceReconnectPromise = this._doForceReconnect(reason)
+                .finally(() => { this._forceReconnectPromise = null; });
         }
-
-        this._forceReconnectPromise = this._doForceReconnect(reason)
-            .finally(() => { this._forceReconnectPromise = null; });
-
-        return this._forceReconnectPromise;
+        await this._forceReconnectPromise;
+        // 외부 호출의 완료 의미는 유지하되, 다음 복구 묶음을 막는 실행 잠금은 이미 풀었다.
+        try { await this._connectPromise; }
+        catch { /* connect/error 이벤트가 종료 사유를 전달한다. */ }
     }
 
     /** @private */
     async _doForceReconnect(reason) {
+        this._cancelReconnectRecovery();
         this.logger.info(`Force reconnect: ${reason}`);
 
         if (this.stompClient) {
@@ -243,12 +248,16 @@ class ConnectionManager extends EventEmitter {
             this.stompClient = null;
         }
 
+        if (this._intentionalDisconnect || this._terminalAuthError) return;
+
         // connect() 가 CONNECTED/CONNECTING 이면 조기 반환하므로 상태를 먼저 내려둔다.
         this._setState(ConnectionState.DISCONNECTED);
         this.reconnectAttempts = 0;
 
         try {
-            await this.connect();
+            // 활성화까지만 직렬화한다. connect 대기는 장애 전체에 걸쳐 유지되므로
+            // 여기서 await 하면 다음 저빈도 복구가 이 잠금에 막힌다.
+            this.connect().catch(error => this.logger.warn(`Force reconnect failed (${reason}):`, error));
         } catch (error) {
             this.logger.warn(`Force reconnect failed (${reason}):`, error);
         }
@@ -288,25 +297,35 @@ class ConnectionManager extends EventEmitter {
      */
     _createStompClient() {
         const wsUrl = this._getWebSocketUrl();
+        // 교체된 클라이언트(정지 뒤 새 토큰으로 다시 연결 등)의 늦은 콜백은 현재 연결 상태를 바꾸지 않는다.
+        let stomp = null;
+        const current = () => !this.stompClient || this.stompClient === stomp;
 
         const config = {
             beforeConnect: async (client) => {
-                if (!this.getAccessToken) return;
+                if (!this.getAccessToken) {
+                    this._connectionToken = this.jwtToken;
+                    return;
+                }
                 let attempt = 0;
                 while (!this._intentionalDisconnect && (!client || client.active)) {
                     try {
                         const token = await this.getAccessToken({ forceRefresh: this._authRejected === true });
                         if (this._intentionalDisconnect || (client && !client.active)) return;
+                        if (this._authRejected && (!token || token.replace(/^Bearer\s+/i, '') === this._rejectedToken)) {
+                            this._stopForAuthError(new Error('Authentication rejected without a new access token'), client);
+                            return;
+                        }
                         this.updateToken(token);
+                        this._connectionToken = token;
                         this._authRejected = false;
                         return;
                     } catch (error) {
                         this.emit('error', { type: ErrorTypes.CONNECTION_FAILED, message: error.message, error });
+                        // 거부된 access token과 갱신 요청의 일시 실패는 별개다.
+                        // 새 토큰/동일 토큰 판정은 위에서, 확정된 인증 종료만 여기서 처리한다.
                         if (isTerminalAuthError(error)) {
-                            this._setState(ConnectionState.ERROR);
-                            this._connectReject?.(error);
-                            this._connectResolve = this._connectReject = null;
-                            await (client || this.stompClient)?.deactivate();
+                            this._stopForAuthError(error, client);
                             return;
                         }
                         // beforeConnect의 예외에는 STOMP 소켓 종료 백오프가 적용되지 않는다.
@@ -329,7 +348,8 @@ class ConnectionManager extends EventEmitter {
             },
             heartbeatIncoming: this.heartbeatIncoming,
             heartbeatOutgoing: this.heartbeatOutgoing,
-            reconnectDelay: this.reconnectDelay,
+            // stompjs는 연결 성공 시 다음 지연을 저장한다. close 콜백보다 먼저 지터를 적용한다.
+            reconnectDelay: this.reconnectDelay * (0.8 + Math.random() * 0.4),
             // 지수 백오프 — 고정 간격이면 서버 재시작 시 전 클라이언트가 같은 주기로 몰린다.
             // STOMP 7 내장 기능이라 직접 타이머를 굴리지 않는다.
             reconnectTimeMode: ReconnectionTimeMode.EXPONENTIAL,
@@ -339,11 +359,11 @@ class ConnectionManager extends EventEmitter {
                     this.logger.debug('STOMP:', str);
                 }
             },
-            onConnect: (frame) => this._onConnect(frame),
-            onDisconnect: (frame) => this._onDisconnect(frame),
-            onStompError: (frame) => this._onStompError(frame),
-            onWebSocketClose: (event) => this._onWebSocketClose(event),
-            onWebSocketError: (event) => this._onWebSocketError(event)
+            onConnect: (frame) => { if (current()) this._onConnect(frame); },
+            onDisconnect: (frame) => { if (current()) this._onDisconnect(frame); },
+            onStompError: (frame) => { if (current()) this._onStompError(frame); },
+            onWebSocketClose: (event) => { if (current()) this._onWebSocketClose(event); },
+            onWebSocketError: (event) => { if (current()) this._onWebSocketError(event); }
         };
 
         if (this.useSockJS) {
@@ -357,7 +377,8 @@ class ConnectionManager extends EventEmitter {
         }
 
         const Client = getStompClient();
-        return new Client(config);
+        stomp = new Client(config);
+        return stomp;
     }
 
     /**
@@ -370,29 +391,35 @@ class ConnectionManager extends EventEmitter {
             return;
         }
 
-        if (this.state === ConnectionState.CONNECTING) {
-            this.logger.warn('Connection in progress');
-            return;
+        if (!this._connectPromise) {
+            this._connectPromise = new Promise((resolve, reject) => {
+                const clear = () => {
+                    this._connectPromise = null;
+                    this._connectResolve = this._connectReject = null;
+                };
+                this._connectResolve = () => { clear(); resolve(); };
+                this._connectReject = error => { clear(); reject(error); };
+            });
         }
-
+        const connected = this._connectPromise;
+        if (this.stompClient && (this.state === ConnectionState.CONNECTING || this.state === ConnectionState.RECONNECTING)) {
+            return connected;
+        }
+        this._cancelReconnectRecovery();
+        this._terminalAuthError = false;
         this._setState(ConnectionState.CONNECTING);
         this.reconnectAttempts = 0;
         this._intentionalDisconnect = false;
         this._connectRequested = true;
-
-        return new Promise((resolve, reject) => {
-            this._connectResolve = resolve;
-            this._connectReject = reject;
-
-            try {
-                this.stompClient = this._createStompClient();
-                this.stompClient.activate();
-            } catch (error) {
-                this._setState(ConnectionState.ERROR);
-                this._drainPendingSubscriptions('Connection activation failed');
-                reject(error);
-            }
-        });
+        try {
+            this.stompClient = this._createStompClient();
+            this.stompClient.activate();
+        } catch (error) {
+            this._setState(ConnectionState.ERROR);
+            this._drainPendingSubscriptions('Connection activation failed');
+            this._connectReject?.(error);
+        }
+        return connected;
     }
 
     /**
@@ -408,6 +435,10 @@ class ConnectionManager extends EventEmitter {
         this._setState(ConnectionState.CONNECTED);
         this.reconnectAttempts = 0;
         this._hasConnectedBefore = true;
+        this._recoveryEligible = true;
+        this._authRejected = false;
+        this._rejectedToken = null;
+        this._notifiedRejectedToken = null;
         this.logger.info('Connected to server', frame);
 
         // 기존 구독 재등록 (재연결 시)
@@ -458,12 +489,13 @@ class ConnectionManager extends EventEmitter {
             frame
         };
 
-        // terminal 전이 — 대기 중 구독 Promise 가 영구 hang 되지 않도록 drain.
-        this._drainPendingSubscriptions(`STOMP error: ${error.message}`);
+        if (this._authRejected) this._recordAuthRejection();
+        const terminal = !this._canRecoverConnection();
+        if (terminal) this._drainPendingSubscriptions(`STOMP error: ${error.message}`);
 
         this.emit('error', error);
 
-        if (this._connectReject) {
+        if (terminal && this._connectReject) {
             this._connectReject(new Error(error.message));
             this._connectResolve = null;
             this._connectReject = null;
@@ -475,13 +507,12 @@ class ConnectionManager extends EventEmitter {
      * @private
      */
     _onWebSocketClose(event) {
-        if (this.stompClient && event?.code === 1012) this.stompClient.reconnectDelay = this.reconnectDelay * (0.8 + Math.random() * 0.4);
-        if (event?.code === 4001) this._authRejected = true;
+        if (event?.code === 4001) this._recordAuthRejection();
         this.logger.warn('WebSocket closed:', event);
 
         // forceReconnect 의 의도적 teardown 이면 재연결 시도로 집계하지 않는다 —
         // 카운터가 오염되면 복귀 직후 다시 max 를 소진해버린다.
-        if (this._tearingDown) {
+        if (this._tearingDown || this._intentionalDisconnect || this._terminalAuthError) {
             this.logger.debug('WebSocket closed during intentional teardown — not counting as reconnect');
             return;
         }
@@ -498,11 +529,8 @@ class ConnectionManager extends EventEmitter {
     _onWebSocketError(event) {
         this.logger.error('WebSocket error:', event);
 
-        // 초기 연결 실패 경로 — _connectReject 가 살아있다는 건 아직 한 번도
-        // CONNECTED 된 적이 없다는 뜻. pending 구독도 함께 drain 해서 호출자 hang 방지.
-        // 이미 CONNECTED 후 일시 끊김은 _onWebSocketClose → _handleReconnect 로 흘러
-        // 재연결 성공 시 _processPendingSubscriptions 가 살린다.
-        if (this._connectReject) {
+        // 이전에 연결된 클라이언트의 복구 중에는 원래 호출자의 대기를 유지한다.
+        if (this._connectReject && !this._canRecoverConnection()) {
             this._drainPendingSubscriptions('WebSocket connection failed');
             this._connectReject(new Error('WebSocket connection failed'));
             this._connectResolve = null;
@@ -523,17 +551,26 @@ class ConnectionManager extends EventEmitter {
         this.reconnectAttempts++;
 
         if (this.reconnectAttempts > this.maxReconnectAttempts) {
-            if (this.stompClient) {
-                try {
-                    this.stompClient.deactivate();
-                } catch (error) {
-                    this.logger.warn('Error deactivating stomp client on max reconnect:', error);
-                }
-                this.stompClient = null;
+            const exhaustedClient = this.stompClient;
+            this.stompClient = null;
+            // 같은 STOMP 인스턴스의 타이머를 완전히 끈 뒤 저빈도 복구를 예약한다.
+            // Promise 안에서 호출을 시작하면 stompjs가 close 이후 재시도를 먼저 예약할 수 있다.
+            let deactivated;
+            try {
+                deactivated = exhaustedClient?.deactivate();
+            } catch (error) {
+                this.logger.warn('Error deactivating stomp client on max reconnect:', error);
+            }
+            Promise.resolve(deactivated).catch(error => {
+                this.logger.warn('Error deactivating stomp client on max reconnect:', error);
+            }).then(() => this._scheduleReconnectRecovery());
+
+            // 복구 묶음 사이에서도 같은 connect/subscribe 요청을 유지한다.
+            if (!this._canRecoverConnection()) {
+                this._connectReject?.(new Error('Max reconnection attempts exceeded'));
+                this._connectResolve = this._connectReject = null;
+                this._drainPendingSubscriptions('Max reconnection attempts exceeded');
             }
-
-            // terminal 전이 — 재연결 성공으로 살릴 기회가 사라졌으므로 pending 도 drain.
-            this._drainPendingSubscriptions('Max reconnection attempts exceeded');
 
             this._setState(ConnectionState.ERROR);
             this.emit('error', {
@@ -548,6 +585,61 @@ class ConnectionManager extends EventEmitter {
         this.logger.info(`Reconnecting... attempt ${this.reconnectAttempts}`);
     }
 
+    /** 실제 거부된 자격 증명을 기록한다. 공급 함수가 있어도 정적 토큰일 수 있다. */
+    _recordAuthRejection() {
+        this._authRejected = true;
+        this._rejectedToken = (this._connectionToken || this.jwtToken).replace(/^Bearer\s+/i, '');
+        if (!this.getAccessToken) this._stopForAuthError(new Error('STOMP error: authentication rejected'));
+    }
+
+    _stopForAuthError(error, client = this.stompClient) {
+        // 같은 거부 토큰은 한 번만 알린다. 오류 처리기가 connect() 를 다시 불러도 즉시 정지 → 알림이 반복되지 않는다.
+        const notify = !this._terminalAuthError && this._usesStaticToken() && this._rejectedToken !== this._notifiedRejectedToken;
+        this._terminalAuthError = true;
+        this._recoveryEligible = false;
+        this._cancelReconnectRecovery();
+        this._setState(ConnectionState.ERROR);
+        this._connectReject?.(error);
+        this._drainPendingSubscriptions(error.message);
+        // beforeConnect 안에서도 호출된다. 여기서 deactivate 완료를 기다리지 않는다.
+        Promise.resolve(client?.deactivate()).catch(failure => this.logger.warn('Auth teardown failed:', failure));
+        // 정적 토큰 모드는 정지를 오류 이벤트(FE connectionError)로 알린다. 새 토큰은 updateToken() 으로 온다.
+        // 정지 전이(이 함수와 호출한 _onStompError 의 나머지)를 마친 뒤 알린다. 처리기의 updateToken()·connect() 가 정리 중인 연결과 섞이지 않는다.
+        if (notify) {
+            this._notifiedRejectedToken = this._rejectedToken;
+            Promise.resolve().then(() => this.emit('error', { type: ErrorTypes.CONNECTION_LOST, message: error.message, error }));
+        }
+    }
+
+    /** 갱신 세션이 없는 정적 토큰(레거시) 모드. canRefreshToken 은 TalkFlowClient 가 설치한다. */
+    _usesStaticToken() {
+        return !this.getAccessToken || this.canRefreshToken?.() === false;
+    }
+
+    _canRecoverConnection() {
+        return this._recoveryEligible && !this._intentionalDisconnect && !this._terminalAuthError
+            && this.reconnectRecoveryDelay > 0;
+    }
+
+    /** 기존에 연결됐던 클라이언트만 긴 장애 후 탭 이벤트 없이 다시 시도한다. */
+    _scheduleReconnectRecovery() {
+        if (!this._canRecoverConnection() || this.state !== ConnectionState.ERROR || this.stompClient) return;
+        this._cancelReconnectRecovery();
+        const delay = this.reconnectRecoveryDelay * (0.8 + Math.random() * 0.4);
+        this._recoveryTimer = setTimeout(() => {
+            this._recoveryTimer = null;
+            if (!this._intentionalDisconnect && !this._terminalAuthError && this.state === ConnectionState.ERROR) {
+                this.forceReconnect('retry-cooldown');
+            }
+        }, delay);
+        this._recoveryTimer.unref?.();
+    }
+
+    _cancelReconnectRecovery() {
+        clearTimeout(this._recoveryTimer);
+        this._recoveryTimer = null;
+    }
+
     /**
      * 기존 구독 재등록 (재연결 시)
      * @private
@@ -684,6 +776,13 @@ class ConnectionManager extends EventEmitter {
                 'Authorization': token.startsWith('Bearer ') ? token : `Bearer ${token}`
             };
         }
+
+        // 정적 토큰 모드에서 거부된 토큰으로 정지했다면 새 토큰으로 다시 연결한다. 같은 토큰이면 정지를 유지한다.
+        // connect() 는 진행 중인 연결을 공유한다. connect(jwt) 가 이어서 connect() 를 불러도 클라이언트는 하나다.
+        if (this._terminalAuthError && !this._intentionalDisconnect && this._usesStaticToken()
+                && token.replace(/^Bearer\s+/i, '') !== this._rejectedToken) {
+            this.connect().catch(error => this.logger.warn('Reconnect with updated token failed:', error));
+        }
     }
 
     /**
@@ -695,6 +794,10 @@ class ConnectionManager extends EventEmitter {
     async disconnect() {
         // 명시적 해제 — 포그라운드 복귀가 이걸 되살리면 안 된다.
         this._intentionalDisconnect = true;
+        this._recoveryEligible = false;
+        this._authRejected = false;
+        this._rejectedToken = null;
+        this._cancelReconnectRecovery();
         this._connectRequested = false;
         this._cancelAuthRetry?.();
         this._connectReject?.(Object.assign(new Error('Connection cancelled'), { code: 'AUTH_OPERATION_CANCELLED' }));