@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/client/hooks/chat/timeline/index.ts

@@ -18,7 +18,7 @@ import { cancelStreamingCoalescer } from '@/shared/lib/chat/timeline/stream-coal
 import { useChatTimelineAccessMode } from '@/client/hooks/chat/timeline/access-mode';
 import { useComposerModes } from '@/client/hooks/chat/timeline/composer-modes';
 import { useComposerDraft } from '@/client/hooks/chat/composer/use-draft';
-import { isChatRunning } from '@/client/hooks/chat/omp/session-statuses';
+import { isChatRunning, isSessionStreaming } from '@/client/hooks/chat/omp/session-statuses';
 import { useWaitingDependencyChoice } from '@/client/hooks/chat/waiting/choice';
 import { useComposerRefs } from '@/client/hooks/chat/timeline/composer-refs';
 
@@ -41,10 +41,8 @@ export function useChatTimeline({
 }: UseChatTimelineOptions = {}) {
   const { sessionId, folderId, selectedFolderId, selectContextFolder, setSearchParams } = useTimelineScope();
   // Plan/goal toggles plus the plan-review surface. PER SESSION, unlike the
-  // access mode: they describe what this conversation is doing, and a global
-  // toggle would drag every other open chat into the same mode. One hook
-  // returns both halves, because a mode command can produce a proposal and
-  // answering that proposal is itself a mode command.
+  // access mode: they describe what this conversation is doing, and one hook
+  // returns both halves because a mode command can produce a proposal.
   const { modes, planReview } = useComposerModes(sessionId);
 
   // Ref mirror of loadOlder so the scroll handler can call the latest one
@@ -76,6 +74,7 @@ export function useChatTimeline({
     isGeneratingRef,
     ownRun,
     ownRunRef,
+    streamRunRef,
     setGenerating,
     generatingVerb,
     activityRef,
@@ -125,11 +124,16 @@ export function useChatTimeline({
   // not start is still reported by the server row and never by client state.
   const timelineRunning = isChatRunning(streamStatusMap, sessionId, ownRun);
 
+  // SERVER evidence a prompt was dispatched (the `stream` row), mirrored for
+  // the reconnect guard: a run whose FIRST frame was lost has no `agent_start`.
+  const serverRunRef = useRef(isSessionStreaming(streamStatusMap, sessionId));
+  serverRunRef.current = isSessionStreaming(streamStatusMap, sessionId);
+
   const aiPlaceholderIdRef = useRef<string | null>(null);
 
   const {
     sessionData,
-    adoptedSessionIdRef, refreshSessionMeta, seedSession,
+    adoptedSessionIdRef, refreshSessionMeta, seedSession, reloadMessages, needsReloadRef,
     hasMore,
     loadingOlder, loadOlderError, sessionLoading, loadOlder, jumpToTurn,
   } = useSessionLoad({
@@ -138,8 +142,11 @@ export function useChatTimeline({
     setGenerating,
     isGeneratingRef,
     ownRunRef,
+    streamRunRef,
+    serverRunRef,
     aiPlaceholderIdRef,
     optimisticUserIdRef,
+    pendingUserDisplaysRef,
     cancelStreamingCoalescer,
     metaRefreshedRef,
     scrollRef,
@@ -147,15 +154,10 @@ export function useChatTimeline({
     jumpCountRef,
   });
   loadOlderRef.current = loadOlder;
-
   // Jump rail: the full-history turn index plus the paging walk that reaches a
   // turn outside the mounted window. The walk is wrapped so follow mode stands
   // down until the jump lands (see rail-jump.ts).
-  const { turns: userTurns, jumping: jumpingTurn, jumpToTurn: pagedJumpToTurn } = useUserTurns({
-    sessionId,
-    messages: localMessages,
-    jumpToTurn,
-  });
+  const { turns: userTurns, jumping: jumpingTurn, jumpToTurn: pagedJumpToTurn } = useUserTurns({ sessionId, messages: localMessages, jumpToTurn });
   const jumpToUserTurn = useRailJump(pagedJumpToTurn, { followRef, scrollRef });
 
   // The composer's model/thinking mirrors and the mid-run stash (see the hook).
@@ -210,6 +212,8 @@ export function useChatTimeline({
     appSettings,
     enqueueExtensionDialog,
     withdrawExtensionDialog,
+    reloadMessages,
+    needsReloadRef,
   }), activityRef);
   const spawn = useSpawnTarget(sessionId);
 
@@ -243,20 +247,11 @@ export function useChatTimeline({
   });
 
   // Queue auto-delivery moved server-side: the wrapper's terminal `agent_end`
-  // schedules the next queued prompt, with a transactional head claim so no
+  // schedules the next queued prompt with a transactional head claim, so no
   // reload/tab race can double-send. `stopHoldRef` serves only the mock path.
 
-  const {
-    handleSend,
-    handleEditQueueItem,
-    handleSendNowQueueItem,
-    handleUndo,
-    handleRetry,
-    submitNewChat,
-    stopGenerating,
-    handleThinkingLevelChange,
-    handleModelChange,
-  } = useChatTimelineActions({
+  const { handleSend, handleEditQueueItem, handleSendNowQueueItem, handleUndo, handleRetry,
+    submitNewChat, stopGenerating, handleThinkingLevelChange, handleModelChange } = useChatTimelineActions({
     inputValue,
     setInputValue,
     setInputAttachments,

package/src/client/hooks/chat/timeline/lost-run.test.ts

@@ -0,0 +1,329 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Recovery of a run whose terminal frames were lost with the channel.
+ *
+ * The reported failure, end to end: a streaming chat left in a background tab,
+ * the socket torn down, the turn finished with nobody reading. The timeline
+ * kept the stream's last PARTIAL segment and its generating flag never
+ * released, while the server's `stream` row had already settled — so the
+ * indicator stopped and the answer stayed cut off mid-sentence.
+ *
+ * Mounted through the REAL `useSessionLoad`, because the repair is a reload of
+ * that hook's own state: asserting on the recovery hook's calls would pass
+ * while the timeline kept the partial row.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+import { useSessionLoad } from '@/client/hooks/chat/timeline/session-load';
+import { resetConnection } from '@/shared/lib/realtime/connection';
+import { setStatus } from '@/shared/lib/realtime/state';
+import type { ChatMessageData } from '@/shared/types';
+
+const originalFetch = Bun.fetch;
+const PARTIAL: ChatMessageData = { id: 'omp-ai', role: 'ai', content: 'The answer stops mid-sent' };
+const COMMITTED: ChatMessageData[] = [
+  { id: 'omp-user', role: 'user', content: 'tolong jelaskan' },
+  { id: 'omp-ai', role: 'ai', content: 'The answer, in full.' },
+];
+
+let container: HTMLElement | undefined;
+/** Render-triggered waiters, so a case can await the state it asserts on. */
+const messageWaiters: { match: (rows: ChatMessageData[]) => boolean; resolve: () => void }[] = [];
+
+beforeAll(() => {
+  installDomGlobals(new Window({ url: 'http://localhost' }));
+});
+
+afterAll(() => {
+  restoreDomGlobals();
+  globalThis.fetch = originalFetch;
+});
+
+afterEach(() => {
+  if (container) render(null, container);
+  container?.remove();
+  container = undefined;
+  resetConnection();
+  globalThis.fetch = originalFetch;
+});
+
+interface Api {
+  messages: ChatMessageData[];
+  generating: boolean;
+  setMessages: (next: ChatMessageData[]) => void;
+  /** Arm the state a dropped run leaves behind. */
+  loseRun: () => void;
+  /** The recovery's own flag: set when a still-live run lost segments, which
+   *  is what schedules the read at its settle. A ref, not a render value — the
+   *  flag is written without a state change, and no consumer renders for it. */
+  needsReloadRef: { current: boolean };
+  /** Run the reconnect: open → closed → open. */
+  reconnect: () => Promise<void>;
+  /** Resolves on the render where the timeline holds rows matching `match`:
+   *  the retry is timer-driven, so this is the signal to wait on. */
+  awaitMessages: (match: (rows: ChatMessageData[]) => boolean) => Promise<void>;
+}
+
+interface ProbeProps {
+  api: Api;
+}
+
+function Probe({ api }: ProbeProps) {
+  const [messages, setMessages] = useState<ChatMessageData[]>([]);
+  const isGeneratingRef = useRef(false);
+  const ownRunRef = useRef(false);
+  const streamRunRef = useRef(false);
+  const serverRunRef = useRef(false);
+  const aiPlaceholderIdRef = useRef<string | null>(null);
+  const optimisticUserIdRef = useRef<string | null>(null);
+  const pendingUserDisplaysRef = useRef<{ sent: string; display: string }[]>([]);
+  const metaRefreshedRef = useRef<string | null>(null);
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const jumpActiveRef = useRef(false);
+  const jumpCountRef = useRef(0);
+  const [generating, setGeneratingState] = useState(false);
+  useEffect(() => {
+    for (const waiter of [...messageWaiters]) {
+      if (!waiter.match(messages)) continue;
+      messageWaiters.splice(messageWaiters.indexOf(waiter), 1);
+      waiter.resolve();
+    }
+  }, [messages]);
+  const setGenerating = useCallback((v: boolean) => {
+    isGeneratingRef.current = v;
+    setGeneratingState(v);
+  }, []);
+
+  api.messages = messages;
+  api.awaitMessages = (match) => {
+    if (match(messages)) return Promise.resolve();
+    const { promise, resolve } = Promise.withResolvers<void>();
+    messageWaiters.push({ match, resolve });
+    return promise;
+  };
+  api.generating = generating;
+  api.setMessages = setMessages;
+  api.loseRun = () => {
+    isGeneratingRef.current = true;
+    // The stream had announced this run — that is the state a lost run is in
+    // (a dispatch whose first frame never arrived is a different case, and the
+    // recovery deliberately refuses it).
+    streamRunRef.current = true;
+    serverRunRef.current = true;
+    setGeneratingState(true);
+    aiPlaceholderIdRef.current = 'omp-ai';
+    setMessages([PARTIAL]);
+  };
+  api.reconnect = async () => {
+    await act(async () => {
+      setStatus('open');
+      setStatus('closed');
+      setStatus('connecting');
+      setStatus('open');
+      for (let i = 0; i < 10; i += 1) await Promise.resolve();
+    });
+  };
+
+  const load = useSessionLoad({
+    sessionId: 'omp-1',
+    setLocalMessages: setMessages,
+    setGenerating,
+    isGeneratingRef,
+    ownRunRef,
+    streamRunRef,
+    serverRunRef,
+    aiPlaceholderIdRef,
+    optimisticUserIdRef,
+    pendingUserDisplaysRef,
+    cancelStreamingCoalescer: () => {},
+    metaRefreshedRef,
+    scrollRef,
+    jumpActiveRef,
+    jumpCountRef,
+  });
+  api.needsReloadRef = load.needsReloadRef;
+  return null;
+}
+
+/** Route the two reads this path makes: the transcript, and the attach probe.
+ *  The transcript is EMPTY until `arm()` — a run still in flight has not
+ *  committed the turn it is streaming, and arming only after the drop is what
+ *  makes a reload observable (an always-populated route would let a broken
+ *  path pass by having the initial load paint the same rows). */
+interface StubRoutes {
+  transcriptReads: number;
+  arm: () => void;
+  /** Answer the next N transcript reads with an EMPTY list — omp buffers its
+   *  writes, so the turn that just finished is not on disk yet. */
+  emptyReads: (count: number) => void;
+  /** Resolves once the transcript has been read `count` times: the retry is
+   *  timer-driven, so this is the signal to wait on rather than a duration. */
+  readsReached: (count: number) => Promise<void>;
+  /** Resolves on the FIRST transcript read, so the harness can wait for the
+   *  initial load to land instead of guessing a delay. */
+  firstRead: Promise<void>;
+}
+
+function stubRoutes(probeAnswer: unknown): StubRoutes {
+  const seen = { transcriptReads: 0, armed: false, empty: 0 };
+  const waiters: { count: number; resolve: () => void }[] = [];
+  const settleWaiters = (): void => {
+    for (const waiter of [...waiters]) {
+      if (seen.transcriptReads < waiter.count) continue;
+      waiters.splice(waiters.indexOf(waiter), 1);
+      waiter.resolve();
+    }
+  };
+  const firstRead = Promise.withResolvers<void>();
+  globalThis.fetch = (async (input: unknown) => {
+    const url = String(input);
+    if (url.includes('/api/agent/')) {
+      return new Response(JSON.stringify(probeAnswer), { status: 200, headers: { 'content-type': 'application/json' } });
+    }
+    seen.transcriptReads += 1;
+    firstRead.resolve();
+    settleWaiters();
+    const empty = !seen.armed || seen.empty > 0;
+    if (seen.empty > 0) seen.empty -= 1;
+    return new Response(JSON.stringify({
+      session: { id: 'omp-1', messages: empty ? [] : COMMITTED },
+      hasMore: false,
+      oldestIndex: 0,
+    }), { status: 200, headers: { 'content-type': 'application/json' } });
+  }) as unknown as typeof fetch;
+  return {
+    get transcriptReads() { return seen.transcriptReads; },
+    arm: () => { seen.armed = true; },
+    emptyReads: (count) => { seen.empty = count; },
+    readsReached: (count) => {
+      if (seen.transcriptReads >= count) return Promise.resolve();
+      const { promise, resolve } = Promise.withResolvers<void>();
+      waiters.push({ count, resolve });
+      return promise;
+    },
+    firstRead: firstRead.promise,
+  };
+}
+
+async function mount(probeAnswer: unknown): Promise<{ api: Api; routes: StubRoutes }> {
+  const routes = stubRoutes(probeAnswer);
+  const api = {} as Api;
+  container ??= document.body.appendChild(document.createElement('div'));
+  await act(async () => {
+    render(h(Probe, { api }), container as HTMLElement);
+  });
+  // The initial history read is a real promise chain (`json()` included), so a
+  // bare microtask flush is not enough — and a load landing AFTER the test arms
+  // its partial row would clear it, which is the harness racing the behaviour
+  // under test. Waiting on the read itself is deterministic. It is awaited
+  // OUTSIDE the render's `act`: effects flush when that callback returns, so a
+  // fetch issued by one cannot settle inside it.
+  await act(async () => {
+    await routes.firstRead;
+    for (let i = 0; i < 8; i += 1) await Promise.resolve();
+  });
+  return { api, routes };
+}
+
+describe('a run whose terminal frames were lost with the channel', () => {
+  test('settles the local run and replaces the partial answer with the transcript', async () => {
+    const { api, routes } = await mount({ running: false });
+    await act(async () => { api.loseRun(); routes.arm(); });
+    expect(api.messages).toEqual([PARTIAL]);
+    expect(api.generating).toBe(true);
+
+    await api.reconnect();
+
+    // The rows on screen were the stream's last PARTIAL segment; the session
+    // JSONL is the only record of the rest.
+    expect(api.messages).toEqual(COMMITTED);
+    expect(api.generating).toBe(false);
+  });
+
+  test('leaves a run the server still reports as live alone — but remembers it', async () => {
+    // Reloading mid-turn would replace the stream's own rows with a lagging
+    // snapshot, so nothing is applied here. What must NOT be lost is the fact
+    // that segments finished during the outage: their `message_end` went into
+    // the dead socket, and only a full read once the run is over recovers them.
+    const { api, routes } = await mount({ running: true, state: { isStreaming: true, isPromptRunning: true } });
+    await act(async () => { api.loseRun(); routes.arm(); });
+
+    await api.reconnect();
+
+    expect(api.messages).toEqual([PARTIAL]);
+    expect(api.generating).toBe(true);
+    expect(api.needsReloadRef.current).toBe(true);
+  });
+
+  test('a first dial is not a reconnect and does not settle the run', async () => {
+    const { api, routes } = await mount({ running: false });
+    await act(async () => { api.loseRun(); routes.arm(); });
+
+    await act(async () => {
+      setStatus('connecting');
+      setStatus('open');
+      for (let i = 0; i < 10; i += 1) await Promise.resolve();
+    });
+
+    expect(api.messages).toEqual([PARTIAL]);
+    expect(api.generating).toBe(true);
+  });
+
+  test('a transcript omp has not flushed yet is retried until the turn lands', async () => {
+    // omp buffers its transcript writes: the turn that just finished can be
+    // absent from the file for a beat after the channel returns. One read and
+    // stop would leave the partial answer on screen — the state this recovery
+    // exists to clear — so an EMPTY answer is retried on the same front-loaded
+    // schedule the metadata refresh uses, and stops at the first real one.
+    //
+    // Fake timers, not a sleep: the retry is a real `setTimeout` chain, and the
+    // schedule is what this case is about.
+    const { api, routes } = await mount({ running: false });
+    await act(async () => {
+      api.loseRun();
+      routes.arm();
+      routes.emptyReads(2);
+    });
+
+    await api.reconnect();
+    // The first read came back empty, so the rows are still the partial answer.
+    expect(api.messages).toEqual([PARTIAL]);
+
+    // The retry is a real timer chain; wait on the RENDER that carries the
+    // committed rows, not on a guessed delay. Two empty answers, so the third
+    // read is the one with the turn in it.
+    // The retry is a real timer chain, and the rows land from a render it
+    // triggers. Awaited OUTSIDE `act`: preact defers effects until the act
+    // callback returns, so waiting for a render-driven signal inside one
+    // deadlocks.
+    await api.awaitMessages((rows) => rows.length === COMMITTED.length);
+
+    expect(api.messages).toEqual(COMMITTED);
+    expect(routes.transcriptReads).toBeGreaterThanOrEqual(4);
+
+    expect(api.messages).toEqual(COMMITTED);
+    expect(routes.transcriptReads).toBeGreaterThanOrEqual(3);
+  });
+
+  test('a lost run on a session this server does not own still settles', async () => {
+    // `running:false` is also the answer for a session owned by another
+    // instance; the frames are gone either way and the transcript is readable.
+    const { api, routes } = await mount({ running: false });
+    await act(async () => { api.loseRun(); routes.arm(); });
+
+    await api.reconnect();
+
+    expect(api.generating).toBe(false);
+    expect(api.messages).toEqual(COMMITTED);
+  });
+});

package/src/client/hooks/chat/timeline/lost-run.ts

@@ -0,0 +1,177 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Recover a run whose terminal frames were lost with the realtime channel.
+ *
+ * The reported failure: a streaming chat was left in a background tab, the
+ * socket was torn down, the turn finished while nothing was reading, and the
+ * user came back to an answer cut off mid-sentence with the docked indicator
+ * already gone. Both halves of that state come from the same missing frames —
+ * `message_end` never replaced the streaming row, and `agent_end` never
+ * released the local generating flag — while the SERVER's `stream` row settled
+ * normally, which is why the indicator stopped but the transcript did not.
+ *
+ * The trigger is the channel reopening while this page still believes a run is
+ * live (`useReconnectSettle`, which also asks the server whether the run is
+ * really over). Recovery is two steps and both are needed:
+ *
+ * 1. settle the local run — release the generating flag and drop the ids that
+ *    only a live stream would consume (the AI placeholder, the optimistic user
+ *    mark, pending steer displays);
+ * 2. re-read the committed transcript, because the rows on screen are the
+ *    stream's last PARTIAL segment and the session JSONL is the only record of
+ *    the rest.
+ *
+ * The reload is deliberately unconditional about ownership: a run this page
+ * dispatched is over by the time this fires, so the guard in `session-load.ts`
+ * (which exists to keep a LAGGING snapshot away from a live run) does not
+ * apply here.
+ *
+ * A run that is STILL LIVE at reconnect is a different case and is NOT
+ * reloaded here — its rows are the stream's, and replacing them mid-turn is the
+ * lagging-snapshot bug the guard exists for. But its earlier segments are gone:
+ * their `message_end` went into the dead socket, and `agent_end` only
+ * materializes turns that stopped abnormally (`materializeTerminalMessages`).
+ * So the loss is REMEMBERED (`needsReloadRef`) and the transcript is re-read
+ * when the run settles, which is the only point where a full read is safe.
+ */
+
+import type { Dispatch, SetStateAction } from 'preact/compat';
+import { useCallback, useRef } from 'preact/hooks';
+
+import { SESSION_META_RETRY_SCHEDULE_MS } from '@/shared/lib/workspace/refresh-cadence';
+import type { ChatMessageData } from '@/shared/types';
+import { useReconnectSettle } from '@/client/hooks/chat/omp/reconnect';
+
+export interface LostRunRecoveryDeps {
+  sessionId: string | null;
+  sessionIdRef: { current: string | null };
+  /** The id a spawn adopted, while the URL still carries the pending one. */
+  adoptedSessionIdRef: { current: string | null };
+  isGeneratingRef: { current: boolean };
+  /** The stream has announced the run in flight — see `useReconnectSettle`. */
+  streamRunRef: { current: boolean };
+  /** The server reports a run for this session (its `stream` row). */
+  serverRunRef: { current: boolean };
+  setGenerating: (v: boolean) => void;
+  setLocalMessages: Dispatch<SetStateAction<ChatMessageData[]>>;
+  /** Pagination cursor for the window the reload applies. */
+  applyWindow: (hasMore: unknown, oldestIndex: unknown) => void;
+  aiPlaceholderIdRef: { current: string | null };
+  optimisticUserIdRef: { current: string | null };
+  pendingUserDisplaysRef: { current: { sent: string; display: string }[] };
+  cancelStreamingCoalescer: () => void;
+}
+
+export interface LostRunRecovery {
+  /** Re-read the committed transcript now (used by the run's own settle path
+   *  when `needsReloadRef` is set — see `omp-callbacks.ts`). */
+  reloadMessages: () => void;
+  /** Set when a run that lost frames is still streaming: its earlier segments
+   *  can only be recovered by a full read once the run is over. */
+  needsReloadRef: { current: boolean };
+}
+
+export function useLostRunRecovery(deps: LostRunRecoveryDeps): LostRunRecovery {
+  const {
+    sessionId,
+    sessionIdRef,
+    adoptedSessionIdRef,
+    isGeneratingRef,
+    streamRunRef,
+    serverRunRef,
+    setGenerating,
+    setLocalMessages,
+    applyWindow,
+    aiPlaceholderIdRef,
+    optimisticUserIdRef,
+    pendingUserDisplaysRef,
+    cancelStreamingCoalescer,
+  } = deps;
+
+  /** Replace the timeline with the session's committed transcript.
+   *
+   *  A FAILED read leaves the rows alone. An EMPTY one is retried on the same
+   *  front-loaded schedule `refreshSessionMeta` uses, and for the same reason:
+   *  omp buffers its transcript writes, so the turn that just finished may not
+   *  be on disk yet when the channel comes back — reading once and stopping
+   *  would leave the partial answer in place, which is the very state this
+   *  recovery exists to clear. The retry is bounded and stops at the first
+   *  non-empty answer. */
+  const reloadMessages = useCallback(() => {
+    const current = sessionIdRef.current;
+    // A spawn answers with omp's id a beat before the URL carries it, so the
+    // adopted id is the one with a transcript when the pending id is still in
+    // the URL.
+    const target = current && !current.startsWith('new-')
+      ? current
+      : adoptedSessionIdRef.current;
+    if (!target) return;
+    let attempt = 0;
+    const tryRead = (): void => {
+      fetch(`/api/chat/${encodeURIComponent(target)}`)
+        .then(res => res.json())
+        .then(data => {
+          // The session may have moved while the read was in flight; applying
+          // it would paint one conversation's rows into another.
+          const now = sessionIdRef.current;
+          if (now !== target && adoptedSessionIdRef.current !== target) return;
+          if (!data?.session) return;
+          const fetched: ChatMessageData[] = data.session.messages || [];
+          if (fetched.length > 0) {
+            setLocalMessages(fetched);
+            applyWindow(data.hasMore, data.oldestIndex);
+            return;
+          }
+          const delay = SESSION_META_RETRY_SCHEDULE_MS[attempt];
+          attempt += 1;
+          if (delay !== undefined) setTimeout(tryRead, delay);
+        })
+        .catch(() => {});
+    };
+    tryRead();
+  }, [sessionIdRef, adoptedSessionIdRef, setLocalMessages, applyWindow]);
+
+  const needsReloadRef = useRef(false);
+
+  useReconnectSettle({
+    // A pending `new-…` chat has no omp child and no committed transcript: its
+    // run is covered by the pending view, and settling it here would drop the
+    // optimistic rows of a spawn still in flight.
+    sessionId: sessionId?.startsWith('new-') ? null : sessionId,
+    isGeneratingRef,
+    streamRunRef,
+    serverRunRef,
+    // Recorded at the DROP: the segments that finished during the outage have
+    // no other way back, and the read that recovers them is only safe once the
+    // run is over — so the flag is consumed by `onAgentEnd` (`omp-callbacks.ts`)
+    // rather than read here.
+    onFramesLost: () => { needsReloadRef.current = true; },
+    onSettled: () => {
+      setGenerating(false);
+      // Queued updates are the same lost segment's tail: the reload is
+      // authoritative, and applying them would paint a partial answer over the
+      // committed one.
+      cancelStreamingCoalescer();
+      optimisticUserIdRef.current = null;
+      pendingUserDisplaysRef.current = [];
+      // The placeholder mark is released, but its ROW is not deleted here: the
+      // committed read below is what replaces the rows, and dropping the only
+      // row first would blank the transcript for the retry window — and leave
+      // it blank for good if omp never flushed the turn. A row the stream left
+      // mid-flight also carries `thinking.isGenerating`, which is what pulses
+      // the collapsed accordion; the run is over, so nothing is generating.
+      aiPlaceholderIdRef.current = null;
+      setLocalMessages(prev => prev.map(m => (typeof m.thinking === 'object' && m.thinking?.isGenerating
+        ? { ...m, thinking: { ...m.thinking, isGenerating: false } }
+        : m)));
+      needsReloadRef.current = false;
+      reloadMessages();
+    },
+  });
+
+  return { reloadMessages, needsReloadRef };
+}