@flamingo-stack/openframe-frontend-core 0.0.444 → 0.0.445

package/src/components/chat/hooks/__tests__/nats-adapter-message-updaters.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Pure message-updater helpers behind `useNatsChatAdapter`'s realtime
+ * callbacks. These guard the post-MESSAGE_END paths that used to corrupt the
+ * thread: continuation fragments replacing the whole trailing bubble, tool
+ * chunks wiping completed replies, and standalone compaction duplication.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  appendToTrailingAssistant,
+  applyToolExecutionToMessages,
+  upsertTrailingCompaction,
+} from '../use-nats-chat-adapter'
+import type { UnifiedChatMessage } from '../../types/unified-chat-state.types'
+import type { MessageSegment, ToolExecutionSegment } from '../../types'
+
+const assistant = (id: string, segments: MessageSegment[]): UnifiedChatMessage => ({
+  id,
+  role: 'assistant',
+  content: '',
+  segments,
+})
+
+const user = (id: string, content: string): UnifiedChatMessage => ({
+  id,
+  role: 'user',
+  content,
+})
+
+const executing = (execId?: string, toolFunction = 'run_command'): ToolExecutionSegment => ({
+  type: 'tool_execution',
+  data: {
+    type: 'EXECUTING_TOOL',
+    integratedToolType: 'SHELL',
+    toolFunction,
+    toolTitle: 'Run command',
+    ...(execId ? { toolExecutionRequestId: execId } : {}),
+  },
+})
+
+const executed = (execId?: string, toolFunction = 'run_command'): ToolExecutionSegment => ({
+  type: 'tool_execution',
+  data: {
+    type: 'EXECUTED_TOOL',
+    integratedToolType: 'SHELL',
+    toolFunction,
+    result: 'ok',
+    success: true,
+    ...(execId ? { toolExecutionRequestId: execId } : {}),
+  },
+})
+
+describe('appendToTrailingAssistant', () => {
+  it('appends into the trailing assistant bubble without dropping prior segments', () => {
+    const prev = [
+      user('u1', 'hi'),
+      assistant('a1', [{ type: 'text', text: 'done. ' }]),
+    ]
+    const next = appendToTrailingAssistant(prev, [{ type: 'text', text: 'continuing' }])
+    expect(next).toHaveLength(2)
+    expect(next[1].segments).toEqual([{ type: 'text', text: 'done. continuing' }])
+  })
+
+  it('pushes a new segment when types differ instead of merging', () => {
+    const prev = [assistant('a1', [{ type: 'text', text: 'answer' }])]
+    const next = appendToTrailingAssistant(prev, [{ type: 'thinking', text: 'hmm' }])
+    expect(next[0].segments).toEqual([
+      { type: 'text', text: 'answer' },
+      { type: 'thinking', text: 'hmm' },
+    ])
+  })
+
+  it('opens a fresh assistant bubble when the thread ends with a user message', () => {
+    const prev = [user('u1', 'hi')]
+    const next = appendToTrailingAssistant(prev, [{ type: 'text', text: 'reply' }])
+    expect(next).toHaveLength(2)
+    expect(next[1].role).toBe('assistant')
+    expect(next[1].segments).toEqual([{ type: 'text', text: 'reply' }])
+  })
+
+  it('returns the input untouched for an empty fragment list', () => {
+    const prev = [assistant('a1', [{ type: 'text', text: 'answer' }])]
+    expect(appendToTrailingAssistant(prev, [])).toBe(prev)
+  })
+
+  it('upserts approval deltas by request id instead of duplicating (replayed emit)', () => {
+    const card = (status: 'pending' | 'approved'): MessageSegment => ({
+      type: 'approval_batch',
+      data: {
+        approvalRequestId: 'req-1',
+        approvalType: 'USER',
+        toolCalls: [
+          {
+            toolExecutionRequestId: 'exec-1',
+            toolName: 'run_command',
+            requiresApproval: true,
+            approvalType: 'USER',
+            toolCallArguments: null,
+          },
+        ],
+      },
+      status,
+    })
+    const prev = [assistant('a1', [{ type: 'text', text: 'reply' }, card('pending')])]
+    const next = appendToTrailingAssistant(prev, [card('approved')])
+    const segs = next[0].segments!
+    expect(segs).toHaveLength(2)
+    expect(segs[1].type).toBe('approval_batch')
+    expect((segs[1] as Extract<MessageSegment, { type: 'approval_batch' }>).status).toBe('approved')
+  })
+
+  it('upserts legacy approval cards by (requestId, command)', () => {
+    const legacy = (command: string, status: 'pending' | 'approved'): MessageSegment => ({
+      type: 'approval_request',
+      data: { requestId: 'req-1', command, approvalType: 'USER' },
+      status,
+    })
+    const prev = [assistant('a1', [legacy('ls', 'pending'), legacy('rm x', 'pending')])]
+    const next = appendToTrailingAssistant(prev, [legacy('rm x', 'approved')])
+    const segs = next[0].segments!
+    expect(segs).toHaveLength(2)
+    expect((segs[0] as Extract<MessageSegment, { type: 'approval_request' }>).status).toBe('pending')
+    expect((segs[1] as Extract<MessageSegment, { type: 'approval_request' }>).status).toBe('approved')
+  })
+})
+
+describe('applyToolExecutionToMessages', () => {
+  it('replaces a matching EXECUTING segment in place (same bubble intact)', () => {
+    const prev = [
+      user('u1', 'run it'),
+      assistant('a1', [{ type: 'text', text: 'running…' }, executing('exec-1')]),
+    ]
+    const next = applyToolExecutionToMessages(prev, executed('exec-1'))
+    expect(next).toHaveLength(2)
+    const segs = next[1].segments!
+    expect(segs[0]).toEqual({ type: 'text', text: 'running…' })
+    expect(segs[1].type).toBe('tool_execution')
+    expect((segs[1] as ToolExecutionSegment).data.type).toBe('EXECUTED_TOOL')
+    // toolTitle restored from the EXECUTING twin (backend omits it on EXECUTED)
+    expect((segs[1] as ToolExecutionSegment).data.toolTitle).toBe('Run command')
+  })
+
+  it('updates a tool in an EARLIER bubble, not just the trailing one', () => {
+    const prev = [
+      assistant('a1', [executing('exec-1')]),
+      assistant('a2', [{ type: 'text', text: 'meanwhile' }]),
+    ]
+    const next = applyToolExecutionToMessages(prev, executed('exec-1'))
+    expect((next[0].segments![0] as ToolExecutionSegment).data.type).toBe('EXECUTED_TOOL')
+    expect(next[1].segments).toEqual([{ type: 'text', text: 'meanwhile' }])
+  })
+
+  it('merges execution state into an approval_batch containing the exec id', () => {
+    const prev: UnifiedChatMessage[] = [
+      assistant('a1', [
+        {
+          type: 'approval_batch',
+          data: {
+            approvalRequestId: 'req-1',
+            approvalType: 'CLIENT',
+            toolCalls: [
+              {
+                toolExecutionRequestId: 'exec-1',
+                toolName: 'run_command',
+                requiresApproval: true,
+                approvalType: 'CLIENT',
+                toolCallArguments: null,
+              },
+            ],
+          },
+          status: 'approved',
+        },
+      ]),
+    ]
+    const next = applyToolExecutionToMessages(prev, executed('exec-1'))
+    const batch = next[0].segments![0]
+    expect(batch.type).toBe('approval_batch')
+    expect((batch as Extract<MessageSegment, { type: 'approval_batch' }>).data.executions).toEqual({
+      'exec-1': { status: 'done', result: 'ok', success: true },
+    })
+  })
+
+  it('appends to the trailing bubble when nothing matches (never replaces content)', () => {
+    const prev = [assistant('a1', [{ type: 'text', text: 'full reply' }])]
+    const next = applyToolExecutionToMessages(prev, executing('exec-9'))
+    const segs = next[0].segments!
+    expect(segs).toHaveLength(2)
+    expect(segs[0]).toEqual({ type: 'text', text: 'full reply' })
+    expect((segs[1] as ToolExecutionSegment).data.toolExecutionRequestId).toBe('exec-9')
+  })
+
+  it('never downgrades an EXECUTED segment back to EXECUTING (replayed chunk)', () => {
+    const prev = [assistant('a1', [executed('exec-1')])]
+    const next = applyToolExecutionToMessages(prev, executing('exec-1'))
+    expect(next).toBe(prev)
+  })
+
+  it('never downgrades a done batch slot back to executing (replayed chunk)', () => {
+    const prev: UnifiedChatMessage[] = [
+      assistant('a1', [
+        {
+          type: 'approval_batch',
+          data: {
+            approvalRequestId: 'req-1',
+            approvalType: 'CLIENT',
+            toolCalls: [
+              {
+                toolExecutionRequestId: 'exec-1',
+                toolName: 'run_command',
+                requiresApproval: true,
+                approvalType: 'CLIENT',
+                toolCallArguments: null,
+              },
+            ],
+            executions: { 'exec-1': { status: 'done', result: 'ok', success: true } },
+          },
+          status: 'approved',
+        },
+      ]),
+    ]
+    const next = applyToolExecutionToMessages(prev, executing('exec-1'))
+    expect(next).toBe(prev)
+  })
+
+  it('falls back to (toolType, toolFunction) pairing when no exec id is present', () => {
+    const prev = [assistant('a1', [executing(undefined, 'get_devices')])]
+    const next = applyToolExecutionToMessages(prev, executed(undefined, 'get_devices'))
+    expect((next[0].segments![0] as ToolExecutionSegment).data.type).toBe('EXECUTED_TOOL')
+  })
+})
+
+describe('upsertTrailingCompaction', () => {
+  it('appends a started compaction into the trailing bubble', () => {
+    const prev = [assistant('a1', [{ type: 'text', text: 'reply' }])]
+    const next = upsertTrailingCompaction(prev, [{ type: 'context_compaction', status: 'started' }])
+    expect(next[0].segments).toEqual([
+      { type: 'text', text: 'reply' },
+      { type: 'context_compaction', status: 'started' },
+    ])
+  })
+
+  it('replaces the started segment on completion instead of duplicating', () => {
+    const prev = [
+      assistant('a1', [
+        { type: 'text', text: 'reply' },
+        { type: 'context_compaction', status: 'started' },
+      ]),
+    ]
+    const next = upsertTrailingCompaction(prev, [
+      { type: 'context_compaction', status: 'completed', summary: 'compacted' },
+    ])
+    expect(next[0].segments).toEqual([
+      { type: 'text', text: 'reply' },
+      { type: 'context_compaction', status: 'completed', summary: 'compacted' },
+    ])
+  })
+
+  it('applies ONLY the compaction segment from a cumulative emission', () => {
+    const prev = [assistant('a1', [{ type: 'text', text: 'reply' }])]
+    // Accumulator emits its whole array — interleaved text must not duplicate.
+    const next = upsertTrailingCompaction(prev, [
+      { type: 'context_compaction', status: 'completed' },
+      { type: 'text', text: 'reply' },
+    ])
+    expect(next[0].segments).toEqual([
+      { type: 'text', text: 'reply' },
+      { type: 'context_compaction', status: 'completed' },
+    ])
+  })
+})

package/src/components/chat/hooks/use-chunk-catchup.ts

@@ -62,9 +62,22 @@ export function useChunkCatchup({
 }: UseChunkCatchupOptions): UseChunkCatchupReturn {
   const processedSequenceKeys = useRef<Set<string>>(new Set())
   const lastSequenceId = useRef<number | null>(null)
+  // Per-messageType resume checkpoints. The legacy Redis transport keeps an
+  // INDEPENDENT sequence counter per (dialog, chatType), so resuming every
+  // stream from the single global `lastSequenceId` would permanently skip
+  // the slower stream's newer chunks (one stream at seq 100, the other at
+  // 20 → resuming both from 100 loses the second stream's 21+).
+  const lastSequenceIdByType = useRef<Map<NatsMessageType, number>>(new Map())
 
   const fetchingInProgress = useRef(false)
   const lastFetchParams = useRef<{ dialogId: string; fromSequenceId?: number | null } | null>(null)
+  // A catch-up requested while another fetch is in flight (double reconnect,
+  // reconnect during the initial catchup). Queued instead of dropped: the old
+  // behaviour returned early and the stale fetch's completion marked catchup
+  // done, so the new gap was never fetched — a permanent transcript hole.
+  // Scoped to its originating dialog — a rerun must never apply one dialog's
+  // offset to another after a switch.
+  const pendingCatchupRef = useRef<{ dialogId: string; fromSequenceId?: number | null } | null>(null)
 
   // Buffer for NATS chunks that arrive during catchup
   const chunkBuffer = useRef<BufferedChunk[]>([])
@@ -92,8 +105,18 @@ export function useChunkCatchup({
 
     if (chunk.sequenceId !== undefined && chunk.sequenceId !== null) {
       const chunkType = typeof chunk.type === 'string' ? chunk.type : ''
-      processedSequenceKeys.current.add(makeSeqKey(messageType, chunkType, chunk.sequenceId))
+      const key = makeSeqKey(messageType, chunkType, chunk.sequenceId)
+      // A live chunk can also be in the catchup fetch result (published just
+      // before the fetch resolved, delivered just after the flush). Without
+      // this check the live path only RECORDED keys and never consulted
+      // them, so the overlap rendered twice (duplicated text / tool cards).
+      if (processedSequenceKeys.current.has(key)) return true
+      processedSequenceKeys.current.add(key)
       lastSequenceId.current = chunk.sequenceId
+      const prevTypeSeq = lastSequenceIdByType.current.get(messageType)
+      if (prevTypeSeq === undefined || chunk.sequenceId > prevTypeSeq) {
+        lastSequenceIdByType.current.set(messageType, chunk.sequenceId)
+      }
     }
 
     onChunkReceivedRef.current(chunk, messageType)
@@ -108,9 +131,11 @@ export function useChunkCatchup({
     const buffered = [...chunkBuffer.current]
     chunkBuffer.current = []
 
+    // Chunks WITHOUT a sequence id are live deliveries — the newest events.
+    // Sorting them as seq 0 (the old behaviour) pushed them BEFORE history.
     buffered.sort((a, b) => {
-      const seqA = a.chunk.sequenceId ?? 0
-      const seqB = b.chunk.sequenceId ?? 0
+      const seqA = a.chunk.sequenceId ?? Number.MAX_SAFE_INTEGER
+      const seqB = b.chunk.sequenceId ?? Number.MAX_SAFE_INTEGER
       return seqA - seqB
     })
 
@@ -132,10 +157,23 @@ export function useChunkCatchup({
     }
 
     if (hasCompletedInitialCatchup.current) {
+      // Safety valve: never leave the buffering flag stuck on a completed
+      // catchup — buffered live chunks would otherwise queue forever and the
+      // dialog would look frozen.
+      if (bufferUntilInitialCatchupComplete.current) {
+        bufferUntilInitialCatchupComplete.current = false
+        flushBufferedRealtimeChunks()
+      }
       return
     }
 
     if (fetchingInProgress.current) {
+      // Queue instead of dropping — the in-flight fetch's finally block
+      // re-runs catch-up with these params once it settles. An explicit
+      // fromSequenceId wins; a queued INITIAL call (undefined) falls back to
+      // the last seq seen so far (null on a fresh dialog → backend returns
+      // everything, same as the original undefined semantics).
+      pendingCatchupRef.current = { dialogId, fromSequenceId: fromSequenceId ?? lastSequenceId.current }
       return
     }
 
@@ -159,7 +197,17 @@ export function useChunkCatchup({
       // Fetch chunks for all configured chat types
       const chunkPromises = chatTypes.map(async (chatType) => {
         try {
-          const chunks = await fetchChunks(dialogId, chatType, fromSequenceId)
+          // Resume each stream from ITS OWN checkpoint: the legacy Redis
+          // transport numbers each (dialog, chatType) stream independently,
+          // so passing one global offset to every type would skip the slower
+          // stream's newer chunks. `undefined` (initial load) still fetches
+          // everything; a type we've never seen resumes from null (= all
+          // unsaved chunks) rather than borrowing another stream's offset.
+          const typeFromSequenceId =
+            fromSequenceId === undefined
+              ? undefined
+              : (lastSequenceIdByType.current.get(getChatTypeMessageType(chatType)) ?? null)
+          const chunks = await fetchChunks(dialogId, chatType, typeFromSequenceId)
           const messageType = getChatTypeMessageType(chatType)
           return chunks.map(chunk => ({ chunk, messageType }))
         } catch (error) {
@@ -183,64 +231,98 @@ export function useChunkCatchup({
       chunkBuffer.current = []
       const allChunks = [...allCatchupChunks, ...bufferedNatsChunks]
       
-      // Sort by sequence ID
+      // Sort by sequence ID. Chunks without one are buffered live deliveries
+      // (the newest events) — sort them AFTER history, not before it.
       allChunks.sort((a, b) => {
-        const seqA = a.chunk.sequenceId ?? 0
-        const seqB = b.chunk.sequenceId ?? 0
+        const seqA = a.chunk.sequenceId ?? Number.MAX_SAFE_INTEGER
+        const seqB = b.chunk.sequenceId ?? Number.MAX_SAFE_INTEGER
         return seqA - seqB
       })
-    
-      // Deduplicate
+
+      // Deduplicate — only chunks that carry a sequence id. Id-less live
+      // chunks get no key: two identical streaming deltas ("the ", "yes")
+      // are distinct content, and collapsing them (the old behaviour, where
+      // the key degraded to type+text) silently dropped text.
       const uniqueAllChunks: BufferedChunk[] = []
       const seenInBatch = new Set<string>()
       for (const item of allChunks) {
-        const k = makeBatchDedupKey(item)
-        if (seenInBatch.has(k)) continue
-        seenInBatch.add(k)
+        const hasSeq = item.chunk.sequenceId !== undefined && item.chunk.sequenceId !== null
+        if (hasSeq) {
+          const k = makeBatchDedupKey(item)
+          if (seenInBatch.has(k)) continue
+          seenInBatch.add(k)
+        }
         uniqueAllChunks.push(item)
       }
       
-      // Find last complete message boundary
-      let lastMessageStartSeqId: number | null = null
-      let lastMessageEndSeqId: number | null = null
-      
-      for (let i = uniqueAllChunks.length - 1; i >= 0; i--) {
-        const seq = uniqueAllChunks[i].chunk.sequenceId
-        if (uniqueAllChunks[i].chunk.type === MESSAGE_TYPE.MESSAGE_END && seq !== undefined && seq !== null) {
-          lastMessageEndSeqId = seq
-          break
-        }
+      // Id-less chunks are buffered live deliveries (newer than anything the
+      // fetch returned) — the boundary filters must KEEP them, not drop them.
+      const hasNoSeq = (item: BufferedChunk) =>
+        item.chunk.sequenceId === undefined || item.chunk.sequenceId === null
+
+      // Boundary detection runs PER messageType. In the legacy Redis
+      // transport each (dialog, chatType) stream has its OWN independent
+      // sequence counter, so a MESSAGE_END boundary found in one stream must
+      // never truncate the other stream's chunks (tool/approval chunks of an
+      // admin mirror used to vanish this way). With JetStream's global seqs
+      // the per-type grouping is still correct — it just partitions the same
+      // ordered list.
+      const byType = new Map<NatsMessageType, BufferedChunk[]>()
+      for (const item of uniqueAllChunks) {
+        const list = byType.get(item.messageType)
+        if (list) list.push(item)
+        else byType.set(item.messageType, [item])
       }
-      
-      for (let i = uniqueAllChunks.length - 1; i >= 0; i--) {
-        const chunk = uniqueAllChunks[i].chunk
-        const seq = chunk.sequenceId
-        if (chunk.type === MESSAGE_TYPE.MESSAGE_START && seq !== undefined && seq !== null) {
-          if (lastMessageEndSeqId === null || seq > lastMessageEndSeqId) {
-            lastMessageStartSeqId = seq
+
+      const chunksToProcess: BufferedChunk[] = []
+      for (const items of byType.values()) {
+        // Find the last complete message boundary within this stream.
+        let lastMessageStartSeqId: number | null = null
+        let lastMessageEndSeqId: number | null = null
+
+        for (let i = items.length - 1; i >= 0; i--) {
+          const seq = items[i].chunk.sequenceId
+          if (items[i].chunk.type === MESSAGE_TYPE.MESSAGE_END && seq !== undefined && seq !== null) {
+            lastMessageEndSeqId = seq
             break
           }
         }
+
+        for (let i = items.length - 1; i >= 0; i--) {
+          const chunk = items[i].chunk
+          const seq = chunk.sequenceId
+          if (chunk.type === MESSAGE_TYPE.MESSAGE_START && seq !== undefined && seq !== null) {
+            if (lastMessageEndSeqId === null || seq > lastMessageEndSeqId) {
+              lastMessageStartSeqId = seq
+              break
+            }
+          }
+        }
+
+        if (lastMessageStartSeqId !== null) {
+          // Process from the last incomplete message
+          chunksToProcess.push(
+            ...items.filter(item => hasNoSeq(item) || item.chunk.sequenceId! >= lastMessageStartSeqId!),
+          )
+        } else if (lastMessageEndSeqId !== null) {
+          // Process only after the last complete message
+          chunksToProcess.push(
+            ...items.filter(item => hasNoSeq(item) || item.chunk.sequenceId! > lastMessageEndSeqId!),
+          )
+        } else {
+          // Process all
+          chunksToProcess.push(...items)
+        }
       }
-      
-      let chunksToProcess: BufferedChunk[]
-      
-      if (lastMessageStartSeqId !== null) {
-        // Process from the last incomplete message
-        chunksToProcess = uniqueAllChunks.filter(item => 
-          item.chunk.sequenceId !== undefined && 
-          item.chunk.sequenceId >= lastMessageStartSeqId!
-        )
-      } else if (lastMessageEndSeqId !== null) {
-        // Process only after the last complete message
-        chunksToProcess = uniqueAllChunks.filter(item => 
-          item.chunk.sequenceId !== undefined && 
-          item.chunk.sequenceId > lastMessageEndSeqId!
-        )
-      } else {
-        // Process all
-        chunksToProcess = uniqueAllChunks
-      }
+
+      // Restore cross-stream order (concatenation above grouped by type).
+      // Stable sort keeps per-type order; JetStream seqs interleave globally,
+      // Redis-mode cross-type order is inherently undefined either way.
+      chunksToProcess.sort((a, b) => {
+        const seqA = a.chunk.sequenceId ?? Number.MAX_SAFE_INTEGER
+        const seqB = b.chunk.sequenceId ?? Number.MAX_SAFE_INTEGER
+        return seqA - seqB
+      })
       
       // Process the chunks
       chunksToProcess.forEach(({ chunk, messageType }) => {
@@ -250,6 +332,10 @@ export function useChunkCatchup({
           if (processedSequenceKeys.current.has(key)) return
           processedSequenceKeys.current.add(key)
           lastSequenceId.current = chunk.sequenceId
+          const prevTypeSeq = lastSequenceIdByType.current.get(messageType)
+          if (prevTypeSeq === undefined || chunk.sequenceId > prevTypeSeq) {
+            lastSequenceIdByType.current.set(messageType, chunk.sequenceId)
+          }
         }
         onChunkReceivedRef.current(chunk, messageType)
       })
@@ -259,24 +345,81 @@ export function useChunkCatchup({
     } catch (error) {
       console.error('Error during chunk catchup:', error)
     } finally {
-      fetchingInProgress.current = false
+      // A fetch whose dialog is no longer active must not touch the NEW
+      // dialog's cycle state — `resetChunkTracking` already re-armed the
+      // flags for it, and clearing `fetchingInProgress` / finalizing the
+      // buffer here would corrupt the new dialog's in-flight catch-up.
+      // That includes the pending queue: only discard an entry that belongs
+      // to THIS stale dialog — a reconnect during the new dialog's initial
+      // fetch queues an entry for the new dialog, and wiping it here would
+      // silently drop that gap's re-fetch (permanent transcript hole).
+      if (dialogId !== dialogIdRef.current) {
+        if (pendingCatchupRef.current?.dialogId === dialogId) {
+          pendingCatchupRef.current = null
+        }
+      } else {
+        fetchingInProgress.current = false
 
-      if (bufferUntilInitialCatchupComplete.current) {
-        bufferUntilInitialCatchupComplete.current = false
-        hasCompletedInitialCatchup.current = true
-        flushBufferedRealtimeChunks()
+        // A reset was requested mid-fetch: re-arm and re-run with the queued
+        // params instead of finalizing on this (stale) fetch's results. The
+        // success path above may have already flipped the completion flags —
+        // reset them so the re-run isn't rejected by its own guards. A
+        // pending entry from a DIFFERENT dialog is discarded, never replayed
+        // against the current one.
+        //
+        // KNOWN LIMIT: the stale fetch may already have processed (and
+        // flushed) chunks NEWER than the queued gap, so on an extreme
+        // double-flap the gap's chunks can render after later ones — order
+        // skew inside the bubble, but no content loss (strictly better than
+        // the pre-fix permanent hole). Perfect ordering would require holding
+        // the stale fetch's flush until the re-run completes, which isn't
+        // worth the complexity for this corner.
+        const pending = pendingCatchupRef.current
+        if (pending) {
+          pendingCatchupRef.current = null
+          if (pending.dialogId === dialogId) {
+            hasCompletedInitialCatchup.current = false
+            lastFetchParams.current = null
+            bufferUntilInitialCatchupComplete.current = true
+            // AWAIT the re-run (not fire-and-forget): callers chain their own
+            // finally on this promise — the adapter lowers its onAgentBusy
+            // suppression there, and a detached re-run would replay a dead
+            // tail's EXECUTING chunk with suppression already off, locking
+            // the composer with no MESSAGE_END ever coming.
+            try {
+              await catchUpChunksRef.current?.(pending.fromSequenceId)
+            } catch (rerunError) {
+              console.error('Queued catch-up re-run failed:', rerunError)
+            }
+          } else if (bufferUntilInitialCatchupComplete.current) {
+            bufferUntilInitialCatchupComplete.current = false
+            hasCompletedInitialCatchup.current = true
+            flushBufferedRealtimeChunks()
+          }
+        } else if (bufferUntilInitialCatchupComplete.current) {
+          bufferUntilInitialCatchupComplete.current = false
+          hasCompletedInitialCatchup.current = true
+          flushBufferedRealtimeChunks()
+        }
       }
     }
   }, [flushBufferedRealtimeChunks])
 
+  // Self-reference for the queued re-run above (the callback can't name
+  // itself inside its own useCallback initializer).
+  const catchUpChunksRef = useRef<typeof catchUpChunks | null>(null)
+  catchUpChunksRef.current = catchUpChunks
+
   /**
    * Reset all tracking state
    */
   const resetChunkTracking = useCallback(() => {
     processedSequenceKeys.current.clear()
     lastSequenceId.current = null
+    lastSequenceIdByType.current.clear()
     fetchingInProgress.current = false
     lastFetchParams.current = null
+    pendingCatchupRef.current = null
     chunkBuffer.current = []
     bufferUntilInitialCatchupComplete.current = false
     hasCompletedInitialCatchup.current = false
@@ -286,8 +429,13 @@ export function useChunkCatchup({
    * Start buffering NATS chunks for initial catchup
    */
   const startInitialBuffering = useCallback(() => {
-    chunkBuffer.current = []
-    bufferUntilInitialCatchupComplete.current = true
+    // Idempotent: a second reconnect while a back-fill is already buffering
+    // (its history refetch still awaiting) must NOT clear the live chunks
+    // collected so far — only a fresh start owns the buffer.
+    if (!bufferUntilInitialCatchupComplete.current) {
+      chunkBuffer.current = []
+      bufferUntilInitialCatchupComplete.current = true
+    }
     hasCompletedInitialCatchup.current = false
   }, [])
 
@@ -305,8 +453,15 @@ export function useChunkCatchup({
     const fromSeq = lastSequenceId.current
     hasCompletedInitialCatchup.current = false
     lastFetchParams.current = null
-    bufferUntilInitialCatchupComplete.current = true
-    chunkBuffer.current = []
+    if (!bufferUntilInitialCatchupComplete.current) {
+      // Starting buffering fresh — drop stale leftovers. When the CALLER
+      // already armed buffering (e.g. `startInitialBuffering()` before an
+      // async history refetch on reconnect), KEEP the chunks it collected:
+      // clearing here would silently discard everything delivered during
+      // that await.
+      chunkBuffer.current = []
+      bufferUntilInitialCatchupComplete.current = true
+    }
     await catchUpChunks(fromSeq)
   }, [catchUpChunks])
 

package/src/components/chat/hooks/use-jetstream-dialog-subscription.ts

@@ -213,6 +213,18 @@ export function useJetStreamDialogSubscription({
     }
   }, [enabled, wsUrl])
 
+  // Reset the highest-seen sequence whenever the dialog changes so a new dialog
+  // starts from optStartSeq (or DeliverPolicy.New) rather than the previous
+  // dialog's offset. MUST be declared BEFORE the subscription effect below:
+  // React runs effects in declaration order, and when this ran after it, the
+  // new dialog's consumer was created with the PREVIOUS dialog's stale
+  // `highestStreamSeq + 1` as its start sequence (skipping messages /
+  // ignoring optStartSeq).
+  useEffect(() => {
+    highestStreamSeqRef.current = null
+    setCurrentStreamSeq(null)
+  }, [dialogId])
+
   // Subscription lifecycle: (re)create the ephemeral JetStream consumer whenever
   // we transition into a connected state for a dialog, and whenever the dialog
   // changes. On reconnect we resume from highestStreamSeq + 1.
@@ -315,13 +327,5 @@ export function useJetStreamDialogSubscription({
     }
   }, [enabled, dialogId, isConnected, streamName, topic, reconnectionCount])
 
-  // Reset the highest-seen sequence whenever the dialog changes so a new dialog
-  // starts from optStartSeq (or DeliverPolicy.New) rather than the previous
-  // dialog's offset.
-  useEffect(() => {
-    highestStreamSeqRef.current = null
-    setCurrentStreamSeq(null)
-  }, [dialogId])
-
   return { isConnected, isSubscribed, reconnectionCount, currentStreamSeq }
 }