@vibexnpm/talkx 4.0.1 → 5.2.0

package/src/chat/ChatClient.js

@@ -70,11 +70,73 @@ class ChatClient extends EventEmitter {
         this._assistantTypingUserId = '__assistant__';
         this._assistantTypingUserName = 'AI';
 
-        // AI 진행 표시(생각중/검색중/작성중) — assistant-stream 채널의 PHASE/DONE 수신 상태.
-        // roomId → { streamId, personaId, phase, timer }. typing 과 별개의 가산 레이어(서버가 둘 다 발행).
-        // 자동 해제 3경로: (1) DONE 수신 (2) 어시 메시지 도착 (3) TTL(expiresAt) 만료 — typing 타이머와 동형.
-        // 현재는 PM_BACKSTAGE(방당 단일 PM) 만 phase 를 발행하므로 방 단위 1개 진행으로 추적한다.
+        // AI 진행 표시(생각중/검색중/작성중) — assistant-stream 채널의 PHASE/DELTA/DONE 수신 상태.
+        //
+        // roomId → Map(streamId → { personaId, phase, text, lastSeq, textAvailable, updatedAt, timer })
+        //
+        // ⚠️ v5.0.0 에서 <b>방 단위 1슬롯 → stream 단위 다중 슬롯</b>으로 바꿨다(설계 §7.1). 한 방에 동시
+        // 스트림이 <b>실재</b>하기 때문이다 — 어시 리스너가 @Async 이고 방 단위 직렬화 락이 없어서, PM 방에
+        // 트리거가 겹치면 각각 streamId 를 발급받아 동시에 산다. 1슬롯이면 나중 것이 앞 것을 덮어 한쪽이
+        // 통째로 사라진다(그게 v4.x 의 "stale 무시" 가드가 하던 일이다).
+        //
+        // 자동 해제는 **2경로**다: (1) DONE 수신 (2) TTL(expiresAt) 만료.
+        // ⚠️ 어시 메시지 도착은 해제 경로가 <b>아니다</b>(v4.2.0, 설계 §7.3) — 서버가 MESSAGE_CREATED 를
+        // DONE 보다 먼저 보내 그 시점엔 messageId → streamId 를 알 수 없다.
+        //
+        // lastSeq/textAvailable = seq 가드용 커서(설계 §5.5.0). 커서 초기값은 -1 이다 — 첫 청크가 seq=0.
         this._assistantProgress = new Map();
+
+        // 종료된 streamId 의 묘비 — roomId → Map(streamId → expiresAt).
+        //
+        // <b>다중 슬롯 전환의 대가다.</b> 1슬롯 시절엔 "streamId 가 다르면 버린다"가 늦은 이벤트를 막는
+        // race 차단 장치였는데, 슬롯이 여러 개가 되면 그 가드가 사라진다. 그러면 DONE 으로 닫힌 스트림의
+        // 늦은 DELTA 가 <b>새 슬롯을 만들어 유령 버블로 되살아난다</b>. 서버 gate 가 terminal 직후 제거를
+        // 금지하고 TTL 로만 회수하는 것과 같은 이유이고 같은 해법이다(설계 §7.2).
+        //
+        // ⚠️ 등록 트리거는 <b>DONE 하나뿐</b>이다. 클라 TTL 만료는 "표시가 낡았다"이지 서버의 확정 종료가
+        // 아니라서, 그걸로 묘비를 세우면 뒤늦게 오는 정상 DELTA 가 영영 막힌다.
+        //
+        // 회수는 <b>lazy</b> 다 — 만료분은 같은 방에 다음 DONE 이 오거나 그 streamId 이벤트가 올 때 지워진다.
+        // 별도 타이머를 두지 않는 이유: 항목이 문자열+숫자뿐이고 방 구독을 끊으면 방 단위로 통째 삭제되므로
+        // 상한이 자연히 걸린다. 타이머 하나를 더 관리하는 비용이 이득보다 크다.
+        this._assistantStreamTombstones = new Map();
+        this._assistantTombstoneTtlMs = 120000;
+        // ⚠️ <b>상한이 아니라 경보 임계</b>다. 넘어도 유효한 묘비를 지우지 않는다(지우면 유령이 되살아난다).
+        this._assistantTombstoneWarnThreshold = 32;
+        /** 임계 초과 경보를 방마다 1회만 내기 위한 표식 — 넘은 동안 DONE 마다 짖지 않게. @private */
+        this._assistantTombstoneWarned = new Set();
+
+        // 슬롯 갱신 순번 — "가장 최근에 갱신된 stream" 판정용.
+        // ⚠️ 벽시계(Date.now)로는 안 된다. 밀리초 해상도라 연속 갱신이 <b>동률</b>이 되고, 동률이면
+        // 순회 순서가 승자를 정해 <b>다른 stream 의 본문이 방 버블에 뜬다</b>. 단조 카운터가 유일하게 안전하다.
+        this._assistantSlotSeq = 0;
+
+        // 방별 세대 카운터 — 구독/해제마다 증가. 스냅샷 응답이 "아직 같은 세대인가"를 판정하는 축이다
+        // (늦게 도착한 응답이 이미 떠난 방의 슬롯을 되살리는 것을 막는다, 설계 §6.1-a).
+        this._assistantRoomGeneration = new Map();
+
+        // ── 스냅샷 재개 (설계 §6.1, R-4) ──
+        //
+        // 스트림은 Pub/Sub 라 <b>구독 시점 이후만</b> 온다. 재입장·중간입장 사용자가 앞부분을 받는 유일한
+        // 경로가 서버 스냅샷이고, 그걸 라이브와 이어붙이는 순서가 이 세 자료구조에 걸려 있다.
+        //
+        // roomId → { generation, events: [] } : 스냅샷 도착 전 라이브 이벤트 보류함.
+        //
+        // ⚠️ <b>구독보다 먼저</b> 켜야 한다. 구독 호출과 보류 플래그 사이에 DELTA 가 오면 그건 보류되지
+        // 않고 그대로 렌더돼, 스냅샷 병합 전에 화면이 잘린 본문으로 먼저 그려진다.
+        //
+        // ⚠️ 큐는 <b>방 단위 단일 배열</b>이다. stream 별로 쪼개면 A0→B0→A1 로 도착한 것이 A0→A1→B0 로
+        // 풀려 "가장 최근 stream" 판정이 뒤집히고 방 집계 버블이 엉뚱한 본문을 보여준다 — R-3 이 단조
+        // 카운터로 세운 정합성을 drain 이 다시 깨는 자리다.
+        //
+        // ⚠️ 세대를 함께 들고 있어야 한다. 안 그러면 이전 세대의 늦은 응답이 <b>현재 세대의 보류분을
+        // 통째로 삭제</b>한다.
+        this._assistantSnapshotPending = new Map();
+        // roomId → { generation, task } : 진행 중인 스냅샷 요청. <b>같은 세대일 때만</b> 재사용한다 —
+        // 다른 세대 요청을 재사용하면 그 응답이 세대 불일치로 버려지면서 이번 요청까지 함께 사라진다.
+        this._assistantSnapshotInFlight = new Map();
+        // 스냅샷 재개 사용 여부 — 서버가 구버전이면 404/빈 배열이라 자동으로 무해하지만, 끄고 싶을 때를 위해.
+        this.assistantStreamReplay = options.assistantStreamReplay !== false;
         // phase → 기본 표시 라벨(설계 §2 — 서버는 의미만, 라벨 텍스트는 SDK 매핑). 소비자는 payload.phase 로 커스텀 가능.
         this._assistantPhaseLabels = {
             THINKING: '생각 중…',
@@ -134,13 +196,20 @@ class ChatClient extends EventEmitter {
     _installSyncTriggers() {
         if (!this.connectionManager || typeof this.connectionManager.on !== 'function') return;
 
+        // ⚠️ 어시 스트림 재개는 <b>메시지 갭 복구와 별도 경로</b>다(설계 §7.4). syncAfterReconnect 는
+        // syncOnReconnect 옵션 + anchor 있는 방이라는 두 겹 필터가 걸려 있어서, 거기 얹으면 옵션이
+        // 꺼져 있거나 그 방에서 메시지를 받은 적이 없을 때 replay 가 조용히 빠진다.
         this._onReconnectedForSync = ({ attempts } = {}) => {
             this.syncAfterReconnect(`reconnected:${attempts ?? 0}`)
                 .catch((error) => this.logger.warn('Gap sync after reconnect failed:', error));
+            this.resumeAssistantStreams(`reconnected:${attempts ?? 0}`)
+                .catch((error) => this.logger.warn('Assistant stream replay after reconnect failed:', error));
         };
         this._onResumedForSync = ({ reason } = {}) => {
             this.syncAfterReconnect(`resumed:${reason ?? 'unknown'}`)
                 .catch((error) => this.logger.warn('Gap sync after resume failed:', error));
+            this.resumeAssistantStreams(`resumed:${reason ?? 'unknown'}`)
+                .catch((error) => this.logger.warn('Assistant stream replay after resume failed:', error));
         };
 
         this.connectionManager.on('reconnected', this._onReconnectedForSync);
@@ -948,6 +1017,222 @@ class ChatClient extends EventEmitter {
         return this.apiClient.post(`/api/v1/rooms/group/${roomId}/unpin`);
     }
 
+    // ── 투표 ────────────────────────────────────────────────────────────────
+    //
+    // 투표 서버는 클러스터 내부에만 있어 클라이언트가 직접 부를 수 없다. 모든 호출은 채팅 서버를 거치고,
+    // 신원(userId/projectId)은 채팅 서버가 인증 결과로 채워 넣는다.
+    //
+    // 🔴 실패는 서버가 투표 서버의 code 를 <b>그대로</b> 내려준다 — {@code error.response.code} 로 분기한다
+    //    (VOTE_ALREADY_CLOSED / VOTE_NOT_EDITABLE / VOTE_MODIFY_FORBIDDEN / CONFLICT ...).
+    //    409 는 세 종류이고 대응이 다르다: ALREADY_CLOSED·NOT_EDITABLE 은 재시도해도 같고,
+    //    CONFLICT 만 <b>재조회 후</b> 재전송하면 성공한다.
+    //
+    // 🔴 결과 마스킹은 <b>호출자마다</b> 계산된다. 목록에는 집계가 없고, 단건 조회/접수 응답에만 있다.
+    //    같은 투표라도 다른 사용자가 보면 가려지므로 응답을 공유 캐시에 넣으면 안 된다.
+
+    /**
+     * 투표 생성.
+     *
+     * <p>🔴 <b>{@code idempotencyKey} 는 필수다.</b> SDK 가 대신 만들지 않는다 — 만들면 그 값이 호출자에게
+     * 남지 않아, 응답만 유실된 타임아웃에서 <b>복구가 불가능</b>하다(다음 호출이 새 키를 만들어 투표가
+     * 두 개 생긴다). 호출자가 키를 소유하고, 같은 시도의 재시도에는 <b>같은 키</b>를 넘긴다 —
+     * 그러면 서버가 기존 투표를 돌려준다(응답도 201, {@code voteId} 도 같다).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} vote - 투표 폼
+     * @param {string} vote.question - 질문 (최대 500자)
+     * @param {'SINGLE'|'MULTIPLE'} vote.type
+     * @param {number} vote.maxSelections - 양수. {@code SINGLE} 이면 1
+     * @param {'TEXT'|'TEXT_WITH_IMAGE'} vote.optionType - {@code 'IMAGE'} 라는 값은 없다
+     * @param {number} vote.closeAt - 마감 시각 (epoch millis). 과거·현재 불가 · 최대 30일 뒤
+     * @param {Array<{id: string, content: string, order: number, imageUrl?: string}>} vote.options - 2~10개.
+     *   {@code imageUrl} 은 {@link #uploadVoteImage} 가 돌려준 값을 <b>가공 없이</b> 넣는다
+     * @param {Object} options
+     * @param {string} options.idempotencyKey - <b>필수.</b> 재시도에는 반드시 같은 값을 넘긴다
+     * @returns {Promise<Object>} 생성된 투표 (집계 포함)
+     * @throws {Error} {@code idempotencyKey} 가 없으면 서버를 호출하지 않고 즉시 실패한다
+     * @example
+     * const key = crypto.randomUUID();
+     * const vote = await chat.createVote(roomId, {
+     *   question: '점심 뭐 먹지', type: 'SINGLE', optionType: 'TEXT', maxSelections: 1,
+     *   closeAt: Date.now() + 86_400_000,
+     *   options: [{ id: 'opt-1', content: '삼겹살', order: 0 }, { id: 'opt-2', content: '국밥', order: 1 }]
+     * }, { idempotencyKey: key });
+     */
+    async createVote(roomId, vote, options = {}) {
+        if (!roomId) {
+            throw new Error('roomId is required');
+        }
+        const { idempotencyKey } = options;
+        if (!idempotencyKey) {
+            // SDK 가 만들어 주면 호출자는 그 값을 볼 수 없다 — 타임아웃으로 응답만 유실됐을 때
+            // 같은 키로 재시도할 방법이 사라지고, 다음 호출이 투표를 하나 더 만든다.
+            throw new Error(
+                'createVote: options.idempotencyKey is required — '
+                + 'generate it once per vote and reuse the same value on retry '
+                + '(재시도에 같은 키를 넘겨야 투표가 중복 생성되지 않는다).'
+            );
+        }
+        const response = await this.apiClient.post(
+            `/api/v1/rooms/${roomId}/votes`,
+            vote,
+            undefined,
+            { 'X-Idempotency-Key': idempotencyKey }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 방의 투표 목록 (최신순).
+     *
+     * <p>목록 항목에는 선택지별 집계도 내 선택도 없다 — 참여자 수({@code responseCount})만 있다.
+     * 결과를 보려면 {@link #getVote} 를 쓴다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {Object} [options]
+     * @param {string} [options.cursor] - 이전 응답의 {@code nextCursor} 를 <b>그대로</b>. 불투명 문자열이라 파싱하지 않는다
+     * @param {number} [options.limit=20] - 최대 100. 초과분은 서버가 조용히 100 으로 보정한다(에러 아님)
+     * @returns {Promise<{items: Array<Object>, nextCursor: ?string}>} {@code items} 가 비면 끝
+     */
+    async getVotes(roomId, options = {}) {
+        const { cursor, limit } = options;
+        const response = await this.apiClient.get(`/api/v1/rooms/${roomId}/votes`, { cursor, limit });
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 투표 단건 + 집계.
+     *
+     * <p>{@code revealed: false} 일 때의 {@code count}/{@code ratio} 0 은 「참여자가 없다」가 아니라
+     * <b>서버가 가린 값</b>이다. 결과 공개 조건은 「내가 응답했다」 또는 「마감됐다」. 비공개 상태에서도
+     * {@code myOptionIds} 는 채워진다(재투표 화면용).</p>
+     *
+     * <p>{@code ratio} 의 분모는 응답자 수이지 총 선택 수가 아니다 — 복수 선택에서 <b>합이 100을 넘는 것이
+     * 정상</b>이고 화면이 「복수 응답」임을 표기해야 한다.</p>
+     *
+     * <p>마감 여부는 {@code status} 만으로 정해지지 않는다. 서버 자동 마감이 미구현이라
+     * {@code status: 'OPEN'} 인데 {@code closeAt} 이 지난 투표가 있고 그건 마감된 것으로 동작한다 —
+     * <b>{@code status} 와 {@code closeAt} 을 함께</b> 봐야 한다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @returns {Promise<Object>}
+     */
+    async getVote(roomId, voteId) {
+        const response = await this.apiClient.get(`/api/v1/rooms/${roomId}/votes/${voteId}`);
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 투표 수정 — <b>부분 수정이 아니다.</b> 등록 폼 전체를 보낸다({@link #createVote} 와 같은 타입).
+     *
+     * <p>{@code maxSelections}↔{@code type}, {@code optionType}↔{@code imageUrl} 이 서로 묶여 있어
+     * 한쪽만 바꾸면 판독 불가능한 투표가 만들어지기 때문이다.</p>
+     *
+     * <p>조건 둘: <b>개설자만</b> · <b>참여자가 0명일 때만</b>. 표가 들어오면
+     * {@code VOTE_NOT_EDITABLE}(409), 개설자가 아니면 {@code VOTE_MODIFY_FORBIDDEN}(403).
+     * 선택지 {@code id} 를 이전 값과 맞출 필요는 없다 — 참여자가 0명이라 어긋날 응답이 없다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @param {Object} vote - 투표 폼 (생성과 동일)
+     * @returns {Promise<Object>}
+     */
+    async updateVote(roomId, voteId, vote) {
+        const response = await this.apiClient.patch(`/api/v1/rooms/${roomId}/votes/${voteId}`, vote);
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 투표 삭제 — 개설자면 된다. 마감 여부도 참여자 유무도 보지 않는다.
+     *
+     * <p>채팅에 이미 게시된 투표 카드는 <b>그대로 남는다</b>(서버가 발행된 메시지를 고칠 수 없다).
+     * 원본 카드를 누르면 404 가 오고, 이 404 를 「취소된 투표」로 표시하는 것은 화면 몫이다.
+     * 삭제 사실은 별도의 취소 카드 메시지로도 방에 발행된다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @returns {Promise<void>} 본문 없음 (204)
+     */
+    async deleteVote(roomId, voteId) {
+        await this.apiClient.delete(`/api/v1/rooms/${roomId}/votes/${voteId}`);
+    }
+
+    /**
+     * 수동 마감 (개설자만).
+     *
+     * <p>본문이 없으므로 마감 후 결과를 보려면 {@link #getVote} 를 다시 호출한다.
+     * 이미 마감이면 {@code VOTE_ALREADY_CLOSED}(409), 개설자가 아니면 {@code VOTE_CLOSE_FORBIDDEN}(403)
+     * — 수정의 403 과 code 가 다르다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @returns {Promise<void>} 본문 없음 (204)
+     */
+    async closeVote(roomId, voteId) {
+        await this.apiClient.patch(`/api/v1/rooms/${roomId}/votes/${voteId}/close`);
+    }
+
+    /**
+     * 투표 접수 · 재투표 — <b>같은 메서드</b>다.
+     *
+     * <p>재투표는 새 자원을 만들지 않고 기존 응답을 덮어쓴다. 클라이언트가 최초/재투표를 구분해 보낼 필요가
+     * 없고, 같은 값을 여러 번 보내도 결과가 같다. 응답에 <b>갱신된 집계가 함께</b> 오므로 별도 폴링이 필요 없다.</p>
+     *
+     * <p>빈 배열은 「투표 취소」로 해석되지 않는다 — 투표를 취소하는 경로는 없다(400).</p>
+     *
+     * <p>여러 규칙을 동시에 위반해도 서버는 <b>먼저 걸린 하나만</b> 응답한다. 하나를 고쳐 재시도하면
+     * 다음 위반이 드러날 수 있어, 모든 오류를 한 번에 수집하는 화면은 성립하지 않는다.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {string} voteId - 투표 ID
+     * @param {string[]} optionIds - 고른 선택지. 빈 배열 불가
+     * @returns {Promise<Object>} 갱신된 투표 (집계 포함)
+     */
+    async submitVote(roomId, voteId, optionIds) {
+        const response = await this.apiClient.put(
+            `/api/v1/rooms/${roomId}/votes/${voteId}/responses`,
+            { optionIds }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
+    /**
+     * 선택지 이미지 업로드.
+     *
+     * <p>돌려받은 {@code imageUrl} 을 <b>가공 없이 그대로</b> 생성·수정 본문의 {@code options[].imageUrl} 에
+     * 넣는다 — 서버가 문자열로 비교하고, 이 API 가 발급한 URL 만 통과한다. <b>채팅 첨부 URL 은 쓸 수 없다</b>
+     * (같은 버킷이라도 거절된다).</p>
+     *
+     * <p>형식은 매직넘버로 판정한다(PNG · JPEG · GIF · WEBP) — 신고된 Content-Type 과 확장자는 쓰이지 않으므로
+     * {@code .png} 로 이름 붙인 텍스트 파일은 거절된다. 10MB 를 넘으면 {@code VOTE_IMAGE_TOO_LARGE}.</p>
+     *
+     * <p>{@code optionType: 'TEXT_WITH_IMAGE'} 는 「이미지를 쓸 수 있다」는 상한이지 「모두 이미지다」가 아니다 —
+     * 이미지가 있는 선택지와 없는 선택지를 섞어도 되고 하나도 없어도 된다. 다만 {@code imageUrl} 이
+     * <b>빈 문자열</b>이면 거절된다(없으면 키를 아예 빼거나 {@code null}).</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @param {File|Blob} file - 이미지 파일
+     * @param {Object} [options]
+     * @param {Function} [options.onProgress] - {@code ({loaded, total, percent}) => void}
+     * @param {AbortSignal} [options.signal] - 취소용
+     * @returns {Promise<{imageUrl: string}>}
+     */
+    async uploadVoteImage(roomId, file, options = {}) {
+        if (!roomId) {
+            throw new Error('roomId is required');
+        }
+        if (!file) {
+            throw new Error('file is required');
+        }
+        const response = await this.apiClient.upload(
+            `/api/v1/rooms/${roomId}/votes/images`,
+            file,
+            { onProgress: options.onProgress, signal: options.signal }
+        );
+        return this._unwrapSuccessResponse(response);
+    }
+
     /**
      * 이모지 리액션 토글.
      * <p>한 사용자는 메시지당 하나의 이모지만 보유.
@@ -2084,10 +2369,20 @@ class ChatClient extends EventEmitter {
         });
 
         // AI 진행 표시(생각중/검색중/작성중) 구독 — typing 과 별개 채널(가산 UX). 구버전 SDK 는 미구독 → 기존 typing 만.
+        //
+        // ⚠️ 보류함을 <b>구독보다 먼저</b> 연다(설계 §6.1 ①). 구독 호출과 보류 플래그 사이에 DELTA 가
+        // 도착하면 그건 보류되지 않고 그대로 렌더돼, 스냅샷 병합 전에 잘린 본문이 화면에 먼저 그려진다.
+        const snapshotGeneration = this.assistantStreamReplay ? this._armAssistantSnapshot(roomId) : null;
         const assistantStreamDestination = WebSocketPaths.getChatAssistantStreamDestination(roomId);
         await this.connectionManager.subscribe(assistantStreamDestination, (event) => {
             this._handleAssistantStreamEvent(roomId, event);
         });
+        if (snapshotGeneration !== null) {
+            // 구독 직후 스냅샷 — 응답을 기다리지 않는다. 구독은 이미 걸렸으므로 그 사이 이벤트는 보류함에 쌓이고,
+            // 병합이 끝나면 순서대로 풀린다. 실패해도 보류분은 풀리므로 라이브만으로 계속 동작한다.
+            this._loadAssistantSnapshot(roomId, snapshotGeneration)
+                .catch((error) => this.logger.warn(`Assistant snapshot merge failed: room=${roomId}`, error));
+        }
 
         // Rolling 누적 요약 완료 알림 구독 — refreshSummary 완료/실패를 summaryUpdate 이벤트로 통지(transient).
         const summaryDestination = WebSocketPaths.getChatSummaryDestination(roomId);
@@ -2169,8 +2464,8 @@ class ChatClient extends EventEmitter {
         // 타이핑 타이머 정리 (outgoing + incoming assistant 둘 다)
         this._clearTypingTimer(roomId);
         this._clearAssistantTypingTimer(roomId);
-        // AI 진행 표시 상태/타이머 정리 (emit 없이 — 구독 해제 중)
-        this._clearAssistantProgress(roomId, false);
+        // AI 진행 표시 상태/타이머/묘비 정리 + 세대 증가 (emit 없이 — 구독 해제 중)
+        this._clearAssistantProgress(roomId);
 
         // 현재 보고 있는 방이면 activeRoom 해제
         if (this._activeRoomId === roomId) {
@@ -2386,9 +2681,16 @@ class ChatClient extends EventEmitter {
                         typing: false,
                         senderType: 'ASSISTANT'
                     });
-                    // AI 진행 표시도 해제 — 최종 메시지 도착 = 진행 종료(설계 §3.1·§4.1, 메시지=진실).
-                    // DONE 이 유실/지연돼도 메시지로 수렴. active:false emit.
-                    this._clearAssistantProgress(roomId, true, 'message');
+                    // ⚠️ AI 진행 표시(assistantProgress)는 <b>여기서 끄지 않는다</b>
+                    // (ASSISTANT_STREAM_REPLAY_DESIGN §7.3).
+                    //
+                    // 서버 발행 순서가 메시지 → DONE 이라(ChatMessagePublicationWorkflow 가 MESSAGE_CREATED 를
+                    // 먼저 내고, InterveneInChatService 가 그 뒤에 DONE(streamId, messageId) 을 낸다) 이 시점의
+                    // 클라는 <b>messageId → streamId 관계를 아직 모른다</b>. 그래서 "이 메시지에 해당하는 stream 만
+                    // 끈다" 가 불가능하고, 방 단위로 끄면 같은 방의 <b>다른 살아 있는 stream</b> 까지 사라진다.
+                    //
+                    // 종료 SSOT 는 DONE 이고, DONE 유실 대비 안전망은 TTL(_startAssistantProgressTimer) 이다.
+                    // DONE 은 메시지 post 직후에 나오므로 표시가 늦게 꺼지는 체감도 사실상 없다.
                 }
 
                 // 상대방 메시지일 때만 newMessage + 자동 읽음 처리
@@ -2713,76 +3015,128 @@ class ChatClient extends EventEmitter {
      * 없으면 {@code label}(단계) 표시, {@code active:false} 면 해제. PHASE→DELTA 흐름으로 "작성 중" 라벨이
      * 점진 렌더 텍스트로 자연 전환된다. 서버가 typing 도 이중발행하므로 구버전 SDK 는 본 채널 미구독 → 기존
      * typing 만으로 정상 동작(graceful).</p>
+     *
+     * <p><b>seq 가드</b>(ASSISTANT_STREAM_REPLAY_DESIGN §5.5.0/§7.1-a): 스트림은 Pub/Sub 라 <b>구독 시점
+     * 이후만</b> 수신된다. 방을 나갔다 재입장하거나 WS 가 순단되면 앞부분을 받은 적이 없는데, 예전 구현은
+     * 그 상태에서 도착한 청크를 그대로 누적본으로 렌더해 <b>잘린 본문</b>을 보여줬다. 이제 {@code seq} 로
+     * "앞이 비었다"를 스스로 판정해 본문 대신 {@code label} 로 물러선다({@code textAvailable=false}).
+     * 최종 메시지가 도착하면 어차피 본문이 확정되므로, 잘린 본문을 보여주는 것보다 라벨이 낫다.</p>
      * @private
      */
     _handleAssistantStreamEvent(roomId, event) {
         if (!event || !event.type) return;
 
+        const streamId = event.streamId || null;
+        if (!streamId) {
+            // streamId 없는 이벤트는 슬롯을 키잉할 수 없다. 서버 계약상 always non-null 이라 도달하지 않는다.
+            this.logger.debug(`Assistant stream event without streamId ignored: room=${roomId}, type=${event.type}`);
+            return;
+        }
+        // 종료된 stream 의 늦은 이벤트 — 되살리지 않는다(§7.2). DONE 자체도 중복 도착하면 여기서 걸린다.
+        if (this._isAssistantStreamClosed(roomId, streamId)) {
+            this.logger.debug(`Assistant event for closed stream ignored: room=${roomId}, stream=${streamId}, type=${event.type}`);
+            return;
+        }
+        // 스냅샷 대기 중이면 보류 — 병합 뒤에 seq 규칙으로 이어붙인다(§6.1). 렌더는 아직 하지 않는다.
+        //
+        // ⚠️ <b>DONE 만은 즉시 처리한다</b>(§6.2). 큐에 넣으면 스냅샷의 ACTIVE 가 먼저 적용돼
+        // {@code active:true} 버블이 한 번 떴다가 곧바로 꺼진다. DONE 은 "서버가 끝났다고 명시한" 신호라
+        // 지금 tombstone 을 세워야 스냅샷이 그 stream 을 되살리지 못한다. 같은 stream 의 이미 보류된
+        // PHASE/DELTA 는 drain 때 그 tombstone 에 걸려 자연히 무시된다.
+        const pending = this._assistantSnapshotPending.get(roomId);
+        if (pending && event.type !== 'DONE') {
+            pending.events.push(event);
+            return;
+        }
+
         if (event.type === 'PHASE') {
+            // PHASE 에는 seq 가 없다 — <b>시각이 유일한 순서 축</b>이다. 스냅샷의 phaseUpdatedAt 보다
+            // 오래된 pending PHASE 를 적용하면 라벨이 WRITING → SEARCHING 으로 역행한다(§6.2).
+            const prevSlot = this._assistantSlot(roomId, streamId);
+            const createdAt = typeof event.createdAt === 'number' ? event.createdAt : null;
+            // ⚠️ 등호도 stale 이다. 계약이 "더 최신일 때만 적용"이라 같은 시각이면 적용하면 안 된다 —
+            // 같은 밀리초에 발행된 pending PHASE 가 스냅샷 phase 를 덮어 라벨이 역행한다.
+            if (prevSlot && createdAt !== null && createdAt <= (prevSlot.phaseUpdatedAt || 0)) {
+                this.logger.debug(`Stale assistant PHASE ignored: room=${roomId}, stream=${streamId}, createdAt=${createdAt}, applied=${prevSlot.phaseUpdatedAt}`);
+                return;
+            }
             const phase = event.phase || null;
-            const label = (phase && this._assistantPhaseLabels[phase]) || null;
-            // 같은 stream 의 PHASE 재발행(B-3 synthesis heartbeat 등)이면 누적 텍스트 보존, 새 stream 이면 리셋.
-            const prev = this._assistantProgress.get(roomId);
-            const text = (prev && prev.streamId === event.streamId) ? (prev.text || '') : '';
-            // 진행 상태 갱신 + TTL 재무장(heartbeat 재수신마다 연장). 같은 방의 이전 타이머는 reset.
-            this._startAssistantProgressTimer(roomId, event, { phase, text });
-            this.emit('assistantProgress', {
-                roomId,
-                streamId: event.streamId || null,
-                personaId: event.personaId || null,
+            // 같은 stream 의 PHASE 재발행(B-3 synthesis heartbeat 등)이면 누적 상태를 보존한다.
+            // ⚠️ 새 stream 의 커서는 <b>-1</b> 로 연다. DeltaCoalescer 의 첫 청크가 seq=0 이라 0 으로 열면
+            // 첫 글자가 "중복"으로 버려진다 (설계 §5.5.0).
+            const prev = prevSlot;
+            const slot = this._setAssistantSlot(roomId, streamId, event, {
                 phase,
-                label,
+                phaseUpdatedAt: createdAt !== null ? createdAt : (prev ? prev.phaseUpdatedAt : 0),
+                text: prev ? (prev.text || '') : '',
+                lastSeq: prev ? this._seqOf(prev.lastSeq) : -1,
+                textAvailable: prev ? prev.textAvailable !== false : true
+            });
+            this._emitAssistantStream(roomId, streamId, slot, {
                 active: true,
-                text: text || null
+                text: slot.textAvailable ? (slot.text || null) : null
             });
             return;
         }
 
         if (event.type === 'DELTA') {
             // 토큰 청크(B) — 누적 텍스트에 이어붙여 점진 렌더용으로 emit. WRITING 단계에서 흐른다.
-            const prev = this._assistantProgress.get(roomId);
-            // stale DELTA 무시 — 이전 stream 의 늦은 토큰이 새 stream 표시를 오염시키지 않게(DONE 가드와 동형).
-            if (prev?.streamId && event.streamId && prev.streamId !== event.streamId) {
-                this.logger.debug(`Stale assistant DELTA ignored: room=${roomId}, delta=${event.streamId}, active=${prev.streamId}`);
+            const prev = this._assistantSlot(roomId, streamId);
+            const phase = (prev && prev.phase) || 'WRITING';
+            const seq = typeof event.seq === 'number' ? event.seq : null;
+
+            let lastSeq = prev ? this._seqOf(prev.lastSeq) : -1;
+            let textAvailable = prev ? prev.textAvailable !== false : true;
+            let text = prev ? (prev.text || '') : '';
+
+            // ── seq 취급 규칙 (설계 §5.5.0 SSOT — 소비자 열. 서버 스냅샷 병합도 같은 표를 쓴다) ──
+            //   seq <= lastSeq     : 중복·지연 도착. <b>장애가 아니다</b> — 조용히 무시.
+            //   seq == lastSeq + 1 : 정상 append.
+            //   seq >  lastSeq + 1 : 실제 gap. 앞이 비었으니 본문을 포기하고 라벨로 물러선다.
+            // 슬롯이 없는 상태의 late join(재입장 직후 seq>0)도 lastSeq=-1 기준으로 마지막 분기에 걸린다.
+            //
+            // ⚠️ <b>커서 판정은 degrade 여부와 무관하다.</b> textAvailable=false 가 멈추는 것은 <b>본문 누적
+            // 뿐</b>이다. 커서까지 멈추면 (1) 이후 중복이 걸러지지 않아 같은 청크가 다시 emit 되고,
+            // (2) lastSeq 가 옛 값에 갇혀 R-4 스냅샷 병합이 잘못된 지점에서 절단한다.
+            if (seq === null) {
+                // 서버가 seq 를 안 실은 경우(구버전 서버) — 판정 불가라 기존 동작(그대로 append)을 유지한다.
+                if (textAvailable) text += event.delta || '';
+            } else if (seq <= lastSeq) {
+                this.logger.debug(`Duplicate assistant DELTA ignored: room=${roomId}, stream=${streamId}, seq=${seq}, lastSeq=${lastSeq}`);
                 return;
+            } else if (seq === lastSeq + 1) {
+                // 포기한 슬롯이면 커서만 전진시키고 본문은 비운 채 둔다 — 베이스가 없는데 이어붙이면 오염이다.
+                if (textAvailable) text += event.delta || '';
+                lastSeq = seq;
+            } else {
+                this.logger.debug(`Assistant DELTA gap — text dropped: room=${roomId}, stream=${streamId}, seq=${seq}, lastSeq=${lastSeq}`);
+                textAvailable = false;
+                text = '';
+                lastSeq = seq;
             }
-            const phase = (prev && prev.phase) || 'WRITING';
-            const text = (prev ? (prev.text || '') : '') + (event.delta || '');
-            this._startAssistantProgressTimer(roomId, event, { phase, text });
-            this.emit('assistantProgress', {
-                roomId,
-                streamId: event.streamId || null,
-                personaId: event.personaId || null,
-                phase,
-                label: this._assistantPhaseLabels[phase] || null,
+
+            const slot = this._setAssistantSlot(roomId, streamId, event, { phase, text, lastSeq, textAvailable });
+            this._emitAssistantStream(roomId, streamId, slot, {
                 active: true,
-                text,                                   // 지금까지 누적된 전체 텍스트(버블 렌더용)
-                delta: event.delta || null,             // 이번 청크(append 렌더 선호 시)
-                seq: typeof event.seq === 'number' ? event.seq : null
+                text: slot.textAvailable ? slot.text : null,            // 누적 전체(버블 렌더용)
+                delta: slot.textAvailable ? (event.delta || null) : null, // 이번 청크(append 렌더 선호 시)
+                seq
             });
             return;
         }
 
         if (event.type === 'DONE') {
-            // 종료(성공·실패 공통) — 상태/타이머 해제 + active:false emit(status/messageId 동봉, 권위 신호).
-            const state = this._assistantProgress.get(roomId);
-            // 늦게 도착한 이전 stream 의 DONE 무시 — 다음 stream 의 PHASE 이후 도착 시 새 진행 표시를 끄는 race 차단.
-            // 메시지/assistant-stream 채널은 ordering 이 묶여 있지 않다. streamId 가 둘 다 있고 다를 때만 stale 판정
-            // (UI 계약이 "active 만 보면 됨"이므로 SDK 가 stale false 를 막는다).
-            if (state?.streamId && event.streamId && state.streamId !== event.streamId) {
-                this.logger.debug(`Stale assistant DONE ignored: room=${roomId}, done=${event.streamId}, active=${state.streamId}`);
-                return;
-            }
-            // 메시지 도착으로 먼저 해제됐어도 DONE 은 한 번 더 발행될 수 있으나 active:false 는 idempotent(설계 §4.1).
-            if (state && state.timer) clearTimeout(state.timer);
-            this._assistantProgress.delete(roomId);
-            this.emit('assistantProgress', {
-                roomId,
-                streamId: event.streamId || null,
-                personaId: event.personaId || null,
+            // 종료(성공·실패 공통) — <b>이 stream 만</b> 닫는다. 같은 방의 다른 stream 은 계속 산다.
+            const slot = this._assistantSlot(roomId, streamId);
+            if (slot && slot.timer) clearTimeout(slot.timer);
+            this._deleteAssistantSlot(roomId, streamId);
+            // 서버가 "끝났다"고 명시한 유일한 신호 — 묘비는 여기서만 세운다(§7.2).
+            this._tombstoneAssistantStream(roomId, streamId);
+            this._emitAssistantStream(roomId, streamId, slot, {
+                active: false,
+                personaId: event.personaId || (slot && slot.personaId) || null,
                 phase: null,
                 label: null,
-                active: false,
                 status: event.status || null,
                 messageId: event.messageId || null
             });
@@ -2790,6 +3144,236 @@ class ChatClient extends EventEmitter {
         // 그 외 미지 type 은 무시(forward-compat).
     }
 
+    /**
+     * 진행 중 스트림 스냅샷을 받아 라이브와 병합한다 (설계 §6.1, R-4).
+     *
+     * <pre>
+     * 0. gen 발급 + pending ON   ← 구독보다 <b>먼저</b> (호출자가 한다)
+     * 1. SUBSCRIBE               ← 호출자가 한다
+     * 2. GET  /assistant/streams
+     * 3. 세대 검증 — 다르면 응답 통째 폐기
+     * 4. 병합: 스냅샷을 베이스로, 보류분을 §5.5.0 규칙으로 이어붙임
+     * 5. pending OFF + 렌더
+     * </pre>
+     *
+     * <p><b>왜 구독이 먼저인가</b>: 반대로 하면 스냅샷 생성과 구독 사이에 발행된 청크가 <b>유실</b>된다.
+     * 구독을 먼저 걸면 최악이 중복인데, 중복은 {@code seq} 로 정확히 잘라낼 수 있다.</p>
+     *
+     * <p><b>실패해도 보류분은 반드시 푼다</b> — 안 그러면 라이브 이벤트가 큐에 갇혀 진행 표시가 통째로
+     * 멈춘다. 스냅샷 실패는 "복구 포기"일 뿐 채팅을 막지 않는다(§6.2).</p>
+     * @private
+     */
+    async _loadAssistantSnapshot(roomId, generation) {
+        // 같은 <b>세대</b>의 요청이 이미 떠 있으면 재사용한다. 다른 세대 것은 재사용하면 안 된다 —
+        // 그 응답은 세대 불일치로 폐기되는데, 재사용했다면 이번 세대의 요청까지 함께 사라진다(그리고
+        // 이번 세대가 쌓아둔 보류분이 통째로 버려진다).
+        const inFlight = this._assistantSnapshotInFlight.get(roomId);
+        if (inFlight && inFlight.generation === generation) return inFlight.task;
+
+        const task = (async () => {
+            let streams = null;
+            try {
+                const response = await this.apiClient.get(`/api/v1/rooms/${roomId}/assistant/streams`);
+                const data = this._unwrapSuccessResponse(response);
+                streams = (data && Array.isArray(data.streams)) ? data.streams : [];
+            } catch (error) {
+                // 구버전 서버(404)·네트워크·5xx 모두 여기로 온다. 사용자에게 노출하지 않는다.
+                this.logger.warn(`Assistant stream snapshot failed (live-only fallback): room=${roomId}`, error);
+            }
+
+            if (this._assistantGeneration(roomId) !== generation) {
+                // 응답 전에 방을 떠났거나 재구독했다 — 이 스냅샷은 이미 다른 세대의 것이다.
+                // ⚠️ <b>내 세대의 보류함만</b> 정리한다. 무조건 지우면 그 사이 열린 현재 세대의 보류분이
+                // 통째로 사라져 라이브 이벤트가 증발한다.
+                this.logger.debug(`Assistant snapshot discarded (stale generation): room=${roomId}`);
+                this._deleteAssistantPendingIfGeneration(roomId, generation);
+                return;
+            }
+            if (streams) this._applyAssistantSnapshot(roomId, streams);
+            this._drainAssistantPending(roomId, generation);
+        })();
+
+        this._assistantSnapshotInFlight.set(roomId, { generation, task });
+        try {
+            await task;
+        } finally {
+            // 내가 등록한 항목일 때만 지운다 — 그 사이 새 세대가 자기 요청을 올려놨을 수 있다.
+            const current = this._assistantSnapshotInFlight.get(roomId);
+            if (current && current.generation === generation) {
+                this._assistantSnapshotInFlight.delete(roomId);
+            }
+        }
+    }
+
+    /** @private */
+    _deleteAssistantPendingIfGeneration(roomId, generation) {
+        const pending = this._assistantSnapshotPending.get(roomId);
+        if (pending && pending.generation === generation) {
+            this._assistantSnapshotPending.delete(roomId);
+        }
+    }
+
+    /** 스냅샷을 슬롯에 심는다 — 보류분을 풀기 <b>전에</b> 끝나야 베이스가 선다. @private */
+    _applyAssistantSnapshot(roomId, streams) {
+        streams.forEach((s) => {
+            const streamId = s && s.streamId;
+            if (!streamId) return;
+            // 이미 DONE 을 라이브로 받아 닫은 stream — 스냅샷이 그걸 되살리면 안 된다(§6.2).
+            if (this._isAssistantStreamClosed(roomId, streamId)) return;
+
+            if (s.status === 'DONE') {
+                // 유예 구간에 걸린 종료분. 진행 표시를 켜지 않고 최종 메시지로 바로 확정시킨다.
+                this._tombstoneAssistantStream(roomId, streamId);
+                this._emitAssistantStream(roomId, streamId, null, {
+                    active: false, phase: null, label: null, personaId: s.personaId || null,
+                    status: s.doneStatus || null, messageId: s.messageId || null, resumed: true
+                });
+                return;
+            }
+
+            const textAvailable = s.textAvailable !== false;
+            const slot = this._setAssistantSlot(roomId, streamId, {
+                personaId: s.personaId, expiresAt: undefined
+            }, {
+                phase: s.phase || null,
+                phaseUpdatedAt: typeof s.phaseUpdatedAt === 'number' ? s.phaseUpdatedAt : 0,
+                text: textAvailable ? (s.text || '') : '',
+                lastSeq: this._seqOf(s.lastSeq),
+                textAvailable,
+                resumed: true
+            });
+            this._emitAssistantStream(roomId, streamId, slot, {
+                active: true,
+                text: slot.textAvailable ? (slot.text || null) : null,
+                resumed: true
+            });
+        });
+    }
+
+    /**
+     * 보류분을 <b>도착 순서 그대로</b> 흘려보낸다. 이 시점부터 §5.5.0 규칙이 스냅샷 베이스 위에서 돈다.
+     *
+     * <p>순서가 중요하다 — stream 별로 몰아서 풀면 방 집계의 "가장 최근 stream" 판정이 실제 도착 순서와
+     * 달라져 엉뚱한 본문이 버블에 뜬다.</p>
+     * @private
+     */
+    _drainAssistantPending(roomId, generation) {
+        const pending = this._assistantSnapshotPending.get(roomId);
+        if (!pending) return;
+        if (generation !== undefined && pending.generation !== generation) return;
+        this._assistantSnapshotPending.delete(roomId);   // 먼저 지워야 재귀로 다시 큐에 들어가지 않는다
+        pending.events.forEach((event) => this._handleAssistantStreamEvent(roomId, event));
+    }
+
+    /** @private */
+    _assistantGeneration(roomId) {
+        return this._assistantRoomGeneration.get(roomId) || 0;
+    }
+
+    /** 세대를 넘기고 보류함을 연다 — <b>구독 직전</b>에 부른다(§6.1 ①). @private */
+    _armAssistantSnapshot(roomId) {
+        const generation = this._assistantGeneration(roomId) + 1;
+        this._assistantRoomGeneration.set(roomId, generation);
+        const previous = this._assistantSnapshotPending.get(roomId);
+        // ⚠️ <b>보류분은 세대를 넘겨 이어받는다.</b> 세대는 <b>스냅샷 응답</b>의 유효성을 가르는 축이지
+        // 큐 내용의 소유권이 아니다. 큐에 있는 건 아직 렌더되지 않은 <b>정상 라이브 이벤트</b>라, 새 세대를
+        // 빈 배열로 열면 그대로 유실된다(GET 대기 중 재개가 한 번 더 불리면 그 사이 도착한 DELTA 가 통째로
+        // 사라진다). 방을 떠날 때 버리는 건 별개 경로다({@link #_clearAssistantProgress}).
+        this._assistantSnapshotPending.set(roomId, {
+            generation,
+            events: previous ? previous.events : []
+        });
+        return generation;
+    }
+
+    /**
+     * 재연결·복귀 시 <b>구독 중인 모든 방</b>의 스냅샷을 다시 받는다 (설계 §7.4).
+     *
+     * <p>⚠️ {@link #syncAfterReconnect} 에 얹으면 안 된다. 그쪽은 {@code syncOnReconnect} 옵션과
+     * <b>anchor 가 있는 방</b>이라는 두 겹 필터가 걸려 있어서, 옵션이 꺼져 있거나 그 방에서 메시지를 받은
+     * 적이 없으면 replay 가 조용히 빠진다. 어시 재개는 메시지 갭 복구와 발동 조건이 다르다.</p>
+     */
+    async resumeAssistantStreams(reason = 'manual') {
+        if (!this.assistantStreamReplay) return;
+        const rooms = Array.from(this.subscribedRooms.keys());
+        if (rooms.length === 0) return;
+        this.logger.debug(`Assistant stream replay: rooms=${rooms.length}, reason=${reason}`);
+        await Promise.all(rooms.map((roomId) => {
+            const generation = this._armAssistantSnapshot(roomId);
+            return this._loadAssistantSnapshot(roomId, generation)
+                .catch((error) => this.logger.warn(`Assistant stream replay failed: room=${roomId}`, error));
+        }));
+    }
+
+    /** 방의 stream 슬롯 맵 — 없으면 생성. @private */
+    _assistantSlots(roomId) {
+        let slots = this._assistantProgress.get(roomId);
+        if (!slots) {
+            slots = new Map();
+            this._assistantProgress.set(roomId, slots);
+        }
+        return slots;
+    }
+
+    /** @private */
+    _assistantSlot(roomId, streamId) {
+        const slots = this._assistantProgress.get(roomId);
+        return slots ? slots.get(streamId) : undefined;
+    }
+
+    /** @private */
+    _deleteAssistantSlot(roomId, streamId) {
+        const slots = this._assistantProgress.get(roomId);
+        if (!slots) return;
+        slots.delete(streamId);
+        if (slots.size === 0) this._assistantProgress.delete(roomId);
+    }
+
+    /** 종료된 stream 인가 — 늦은 이벤트가 슬롯을 되살리는 것을 막는다(§7.2). @private */
+    _isAssistantStreamClosed(roomId, streamId) {
+        const graves = this._assistantStreamTombstones.get(roomId);
+        if (!graves) return false;
+        const expiresAt = graves.get(streamId);
+        if (expiresAt === undefined) return false;
+        if (expiresAt <= Date.now()) {
+            graves.delete(streamId);   // 만료된 묘비는 회수 — 그 뒤엔 새 stream 취급이 맞다.
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * 묘비 등록 — <b>회수는 시간으로만</b> 한다.
+     *
+     * <p>⚠️ 임계를 넘어도 <b>아직 유효한 묘비는 지우지 않는다.</b> 지우는 순간 그 stream 의 늦은 DELTA 가
+     * 슬롯을 되살려 유령 버블이 되고, 그건 "DONE 이후 절대 되살리지 않는다"는 이 장치의 존재 이유 자체를
+     * 깬다. 서버 gate 가 상한 초과 시에도 pruning 대신 경보만 내는 것과 <b>같은 규칙</b>이다 —
+     * 계약 파손이 메모리보다 훨씬 비싸다(항목당 문자열+숫자다).</p>
+     * @private
+     */
+    _tombstoneAssistantStream(roomId, streamId) {
+        let graves = this._assistantStreamTombstones.get(roomId);
+        if (!graves) {
+            graves = new Map();
+            this._assistantStreamTombstones.set(roomId, graves);
+        }
+        const now = Date.now();
+        graves.forEach((expiresAt, id) => {
+            if (expiresAt <= now) graves.delete(id);   // 만료분만 회수(lazy)
+        });
+        graves.set(streamId, now + this._assistantTombstoneTtlMs);
+
+        // 경보는 임계를 <b>넘는 순간 1회</b>만 — 넘은 동안 DONE 마다 짖으면 로그가 신호를 덮는다.
+        if (graves.size > this._assistantTombstoneWarnThreshold) {
+            if (!this._assistantTombstoneWarned.has(roomId)) {
+                this._assistantTombstoneWarned.add(roomId);
+                this.logger.warn(`Assistant tombstones above threshold — NOT pruning (TTL only): room=${roomId}, size=${graves.size}, threshold=${this._assistantTombstoneWarnThreshold}`);
+            }
+        } else {
+            this._assistantTombstoneWarned.delete(roomId);
+        }
+    }
+
     /**
      * Rolling 누적 요약 완료 알림(summary 채널) 수신 처리 — status 를 그대로 {@code summaryUpdate} 로 emit.
      *
@@ -2816,13 +3400,24 @@ class ChatClient extends EventEmitter {
     }
 
     /**
-     * AI 진행 상태 갱신 + TTL 타이머 재무장 — {@code expiresAt}(epochMillis) 기반, 누락/이상 시 fallback.
-     * {@code fields}={phase, text}(PHASE/DELTA 가 해소해 전달 — DELTA 는 직전 phase 유지 + 누적 text).
-     * 만료 = DONE·메시지 유실로 진행이 끊긴 것 → UI 가 영구 표시에 갇히지 않게 {@code active:false} 자동 emit.
+     * seq 커서 정규화 — 값이 없으면 {@code -1}(DELTA 0건). 첫 청크가 {@code seq=0} 이라 기본값이 0 이면
+     * 첫 글자를 중복으로 버린다(설계 §5.5.0).
      * @private
      */
-    _startAssistantProgressTimer(roomId, event, fields) {
-        const prev = this._assistantProgress.get(roomId);
+    _seqOf(value) {
+        return typeof value === 'number' ? value : -1;
+    }
+
+    /**
+     * stream 슬롯 갱신 + TTL 타이머 재무장 — {@code expiresAt}(epochMillis) 기반, 누락/이상 시 fallback.
+     *
+     * <p>만료 = DONE 유실로 진행이 끊긴 것 → UI 가 영구 표시에 갇히지 않게 {@code active:false} 를 자동
+     * emit 한다. ⚠️ 만료는 <b>묘비를 세우지 않는다</b> — "표시가 낡았다"는 것이지 서버의 확정 종료가
+     * 아니라서, 뒤늦게 정상 DELTA 가 오면 다시 살아나야 맞다(§7.2).</p>
+     * @private
+     */
+    _setAssistantSlot(roomId, streamId, event, fields) {
+        const prev = this._assistantSlot(roomId, streamId);
         if (prev && prev.timer) clearTimeout(prev.timer);
 
         let ttl = this._assistantProgressFallbackTtlMs;
@@ -2831,39 +3426,114 @@ class ChatClient extends EventEmitter {
             ttl = Math.min(120000, Math.max(5000, event.expiresAt - Date.now()));
         }
         const timer = setTimeout(() => {
-            this._clearAssistantProgress(roomId, true, 'timeout');
-            this.logger.debug(`Assistant progress auto-cleared (timeout): room=${roomId}`);
+            this._expireAssistantStream(roomId, streamId);
         }, ttl);
-        this._assistantProgress.set(roomId, {
-            streamId: event.streamId || null,
-            personaId: event.personaId || null,
+
+        const slot = {
+            personaId: event.personaId || (prev && prev.personaId) || null,
             phase: fields.phase,
+            // 마지막으로 <b>적용된</b> PHASE 의 발행 시각 — pending PHASE 역행 판정 커서(§6.2).
+            phaseUpdatedAt: fields.phaseUpdatedAt !== undefined
+                ? fields.phaseUpdatedAt
+                : (prev ? (prev.phaseUpdatedAt || 0) : 0),
             text: fields.text || '',
+            lastSeq: this._seqOf(fields.lastSeq),
+            textAvailable: fields.textAvailable !== false,
+            resumed: fields.resumed === true || (prev ? prev.resumed === true : false),
+            updatedAt: Date.now(),
+            order: ++this._assistantSlotSeq,   // 최신 판정 축 — updatedAt 은 진단용일 뿐이다
             timer
+        };
+        this._assistantSlots(roomId).set(streamId, slot);
+        return slot;
+    }
+
+    /** TTL 만료 — 이 stream 만 끈다. 묘비는 세우지 않는다. @private */
+    _expireAssistantStream(roomId, streamId) {
+        const slot = this._assistantSlot(roomId, streamId);
+        if (!slot) return;
+        if (slot.timer) clearTimeout(slot.timer);
+        this._deleteAssistantSlot(roomId, streamId);
+        this.logger.debug(`Assistant progress auto-cleared (timeout): room=${roomId}, stream=${streamId}`);
+        this._emitAssistantStream(roomId, streamId, slot, {
+            active: false, phase: null, label: null, reason: 'timeout'
         });
     }
 
     /**
-     * AI 진행 표시 상태/타이머 해제. {@code emit=true} 면 {@code active:false} 를 발행(메시지 도착/타임아웃 해제용).
-     * 구독 해제 시엔 {@code emit=false} 로 조용히 정리.
+     * {@code assistantProgress}(stream 단위) + {@code assistantRoomProgress}(방 단위 집계)를 함께 발행한다.
+     *
+     * <p><b>왜 둘인가</b>: 진짜 상태는 stream 단위지만, 기존 프론트는 "방마다 임시 버블 하나"를 전제로
+     * 짜여 있다. 그 코드에 stream 단위 {@code active:false} 가 들어가면 <b>같은 방의 다른 살아 있는
+     * 버블까지 숨긴다</b>. 그래서 이행용 다리로 방 단위 집계를 별도 이벤트로 함께 낸다(설계 §7.5 (b)).
+     * 프론트는 리스너 이름만 바꿔 기존 렌더를 유지하다가, 준비되면 stream 단위로 넘어오면 된다.</p>
      * @private
      */
-    _clearAssistantProgress(roomId, emit, reason) {
-        const state = this._assistantProgress.get(roomId);
-        if (!state) return;
-        if (state.timer) clearTimeout(state.timer);
-        this._assistantProgress.delete(roomId);
-        if (emit) {
-            this.emit('assistantProgress', {
-                roomId,
-                streamId: state.streamId || null,
-                personaId: state.personaId || null,
-                phase: null,
-                label: null,
-                active: false,
-                reason: reason || null
+    _emitAssistantStream(roomId, streamId, slot, overrides) {
+        const phase = 'phase' in overrides ? overrides.phase : (slot ? slot.phase : null);
+        this.emit('assistantProgress', {
+            roomId,
+            streamId,
+            personaId: slot ? slot.personaId : null,
+            phase,
+            label: phase ? (this._assistantPhaseLabels[phase] || null) : null,
+            textAvailable: slot ? slot.textAvailable : true,
+            lastSeq: slot ? slot.lastSeq : -1,
+            ...overrides
+        });
+        this._emitAssistantRoomProgress(roomId);
+    }
+
+    /**
+     * 방 단위 집계 — 살아 있는 stream 이 하나라도 있으면 {@code active:true}.
+     * 표시 내용은 <b>가장 최근에 갱신된</b> stream 을 따른다(단일 버블 UI 가 자연스럽게 최신을 보여준다).
+     * @private
+     */
+    _emitAssistantRoomProgress(roomId) {
+        const slots = this._assistantProgress.get(roomId);
+        const alive = slots ? Array.from(slots.entries()) : [];
+        if (alive.length === 0) {
+            this.emit('assistantRoomProgress', {
+                roomId, active: false, streamCount: 0,
+                streamId: null, personaId: null, phase: null, label: null, text: null, textAvailable: true
             });
+            return;
+        }
+        const [streamId, slot] = alive.reduce((a, b) => (b[1].order > a[1].order ? b : a));
+        this.emit('assistantRoomProgress', {
+            roomId,
+            active: true,
+            streamCount: alive.length,
+            streamId,
+            personaId: slot.personaId,
+            phase: slot.phase,
+            label: slot.phase ? (this._assistantPhaseLabels[slot.phase] || null) : null,
+            text: slot.textAvailable ? (slot.text || null) : null,
+            textAvailable: slot.textAvailable
+        });
+    }
+
+    /**
+     * 방의 모든 stream 상태/타이머 정리 — 구독 해제·destroy 용. 조용히 지운다(emit 없음).
+     *
+     * <p>묘비도 함께 지운다. 방을 떠나면 되살아날 유령 자체가 없고, 재입장은 새 세대이기 때문이다.</p>
+     * @private
+     */
+    _clearAssistantProgress(roomId) {
+        const slots = this._assistantProgress.get(roomId);
+        if (slots) {
+            slots.forEach((slot) => slot.timer && clearTimeout(slot.timer));
+            this._assistantProgress.delete(roomId);
         }
+        this._assistantStreamTombstones.delete(roomId);
+        // 경고 표식도 묘비와 <b>같은 수명</b>이어야 한다. 남겨두면 재구독 후 임계를 다시 넘어도
+        // "이미 알렸다"로 판정해 경고가 영영 안 나오고, Set 에 죽은 roomId 가 쌓인다.
+        this._assistantTombstoneWarned.delete(roomId);
+        // 보류함도 비운다 — 방을 떠났는데 큐가 남아 있으면 재구독 때 옛 이벤트가 섞여 들어간다.
+        // (진행 중 스냅샷 응답은 아래 세대 증가로 무효화되므로 별도 취소가 필요 없다.)
+        this._assistantSnapshotPending.delete(roomId);
+        // 진행 중이던 스냅샷 응답이 뒤늦게 도착해도 적용되지 않도록 세대를 넘긴다(§6.1-a, R-4 가 소비).
+        this._assistantRoomGeneration.set(roomId, (this._assistantRoomGeneration.get(roomId) || 0) + 1);
     }
 
     // ==================== 유틸리티 ====================
@@ -2914,8 +3584,14 @@ class ChatClient extends EventEmitter {
         this._assistantTypingTimers.clear();
 
         // AI 진행 표시 상태/타이머도 전체 cleanup (구독 외 경로로 남은 roomId 방어).
-        this._assistantProgress.forEach((state) => state.timer && clearTimeout(state.timer));
+        // 슬롯이 방 → stream 2단이라 안쪽까지 순회해야 타이머가 남지 않는다(v5.0.0).
+        this._assistantProgress.forEach((slots) => slots.forEach((slot) => slot.timer && clearTimeout(slot.timer)));
         this._assistantProgress.clear();
+        this._assistantStreamTombstones.clear();
+        this._assistantTombstoneWarned.clear();
+        this._assistantRoomGeneration.clear();
+        this._assistantSnapshotPending.clear();
+        this._assistantSnapshotInFlight.clear();
 
         // dedup bucket 전체 clear — unsubscribeRoom 이 방별로 정리하지만 구독 외 경로로 누적된 bucket
         // (예: 구독 안 한 방의 push/listener) 이 있을 수 있어 안전하게 명시 정리.