@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/client/hooks/chat/omp/reconnect.test.ts

@@ -0,0 +1,338 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The lost-run trigger: a channel that comes back after frames were missed.
+ *
+ * The reported failure is a run whose `message_end`/`agent_end` were emitted
+ * into a socket nobody was reading (a backgrounded tab, a frozen phone), so the
+ * timeline kept the stream's last partial segment and its generating flag never
+ * released. What decides whether this hook acts is the CHANNEL, and the two
+ * conditions are pinned here because getting either wrong is destructive:
+ *
+ * - a dial is not a reconnect. A send whose `connect()` opens a closed channel
+ *   passes through `connecting`/`open` too, and settling there would delete the
+ *   optimistic turn of a prompt that is not even on the wire yet.
+ * - the server's verdict must be asked, and only `runIsOver` settles. An
+ *   unanswered probe, a `busy` session and a live run all leave the timeline
+ *   alone.
+ *
+ * The status publisher driven here is the one the connection layer calls
+ * (`setStatus`), so the trigger path is the real one; the socket itself is not
+ * what these cases are about.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { useRef } from 'preact/hooks';
+import { act } from 'preact/test-utils';
+
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+import { useReconnectSettle } from '@/client/hooks/chat/omp/reconnect';
+import { resetConnection } from '@/shared/lib/realtime/connection';
+import { setStatus } from '@/shared/lib/realtime/state';
+
+let container: HTMLElement | undefined;
+const originalFetch = Bun.fetch;
+
+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 Harness {
+  settles: () => number;
+  losses: () => number;
+  /** Re-render under another session id (a spawn adoption). */
+  adopt: (nextId: string) => Promise<void>;
+  generating: { current: boolean };
+  streamRun: { current: boolean };
+  serverRun: { current: boolean };
+  /** Drive the connection status the way the socket lifecycle does. */
+  setStatus: (status: 'idle' | 'connecting' | 'open' | 'closed') => Promise<void>;
+}
+
+/** Answer the attach probe with `answer` (or fail when it is null). */
+function stubProbe(answer: unknown, onCall?: () => void): void {
+  globalThis.fetch = (async () => {
+    onCall?.();
+    if (answer === null) throw new Error('offline');
+    return new Response(JSON.stringify(answer), { status: 200, headers: { 'content-type': 'application/json' } });
+  }) as unknown as typeof fetch;
+}
+
+async function mount(generating: boolean, sessionId = 'omp-1'): Promise<Harness> {
+  const seen = {
+    settles: 0,
+    losses: 0,
+    generating: { current: generating },
+    streamRun: { current: generating },
+    serverRun: { current: generating },
+  };
+  function Probe({ id = sessionId }: { id?: string }) {
+    const generatingRef = useRef(seen.generating.current);
+    // The stream has announced the run, which is the state a lost run is in.
+    const streamRunRef = useRef(seen.streamRun.current);
+    const serverRunRef = useRef(seen.serverRun.current);
+    seen.generating = generatingRef;
+    seen.streamRun = streamRunRef;
+    seen.serverRun = serverRunRef;
+    useReconnectSettle({
+      sessionId: id,
+      isGeneratingRef: generatingRef,
+      streamRunRef,
+      serverRunRef,
+      onSettled: () => { seen.settles += 1; },
+      onFramesLost: () => { seen.losses += 1; },
+    });
+    return null;
+  }
+  container ??= document.body.appendChild(document.createElement('div'));
+  await act(async () => { render(h(Probe, null), container as HTMLElement); });
+  return {
+    settles: () => seen.settles,
+    losses: () => seen.losses,
+    generating: seen.generating,
+    streamRun: seen.streamRun,
+    serverRun: seen.serverRun,
+    /** Re-render with another session id — the spawn adoption that re-mounts
+     *  the effect mid-run. */
+    adopt: async (nextId: string) => {
+      await act(async () => {
+        render(h(Probe, { id: nextId }), container as HTMLElement);
+      });
+    },
+    setStatus: async (status) => {
+      await act(async () => {
+        setStatus(status);
+        // Let the probe's fetch/then chain (and the re-check at the answer) run.
+        for (let i = 0; i < 8; i += 1) await Promise.resolve();
+      });
+    },
+  };
+}
+
+describe('a channel that comes back after frames were missed', () => {
+  test('settles the run the server reports as finished', async () => {
+    let probes = 0;
+    stubProbe({ running: true, state: { isStreaming: false, isPromptRunning: false, isSettled: true } }, () => { probes += 1; });
+    const harness = await mount(true);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('connecting');
+    await harness.setStatus('open');
+
+    expect(probes).toBe(1);
+    expect(harness.settles()).toBe(1);
+  });
+
+  test('a session the server no longer runs is settled too', async () => {
+    stubProbe({ running: false });
+    const harness = await mount(true);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+
+    expect(harness.settles()).toBe(1);
+  });
+
+  test('a run still in flight is left alone', async () => {
+    stubProbe({ running: true, state: { isStreaming: true, isPromptRunning: true } });
+    const harness = await mount(true);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+
+    expect(harness.settles()).toBe(0);
+  });
+
+  test('a busy session with no run is left alone', async () => {
+    // A live subagent whose parent turn ended: `busy` is not run evidence, and
+    // settling it would abandon the work still going.
+    stubProbe({ running: true, busy: true, state: { isStreaming: false, isPromptRunning: false } });
+    const harness = await mount(true);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+
+    expect(harness.settles()).toBe(0);
+  });
+
+  test('an unanswered probe settles nothing', async () => {
+    stubProbe(null);
+    const harness = await mount(true);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+
+    expect(harness.settles()).toBe(0);
+  });
+
+  test('a FIRST dial is not a reconnect', async () => {
+    // The send path opens a closed channel for a prompt it is about to send:
+    // no frames can have been missed, so the optimistic turn must survive.
+    stubProbe({ running: true, state: { isStreaming: false, isPromptRunning: false, isSettled: true } });
+    const harness = await mount(true);
+
+    await harness.setStatus('connecting');
+    await harness.setStatus('open');
+
+    expect(harness.settles()).toBe(0);
+  });
+
+  test('a session with NO run at all is never probed', async () => {
+    // Nothing has started, so nothing can have been lost: a reconnect on an
+    // idle session must not even ask.
+    let probes = 0;
+    stubProbe({ running: false }, () => { probes += 1; });
+    const harness = await mount(false);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+
+    expect(probes).toBe(0);
+    expect(harness.settles()).toBe(0);
+  });
+
+  test('a run that FLICKERED off before the drop still counts as lost', async () => {
+    // Measured on a real run: the drop landed in a beat where the generating
+    // flag and both run flags read false (the spawn-adoption window, a
+    // `prompt_result` folded as settled), so the loss was read as "nothing was
+    // running" — and the transcript was never re-read. The evidence is
+    // LATCHED, so a flicker cannot erase it.
+    let probes = 0;
+    stubProbe({ running: false }, () => { probes += 1; });
+    const harness = await mount(true);
+
+    await harness.setStatus('open');
+    // Every live signal goes quiet before the channel does.
+    harness.generating.current = false;
+    harness.streamRun.current = false;
+    harness.serverRun.current = false;
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+
+    expect(probes).toBe(1);
+    expect(harness.settles()).toBe(1);
+  });
+
+  test('the loss is recorded at the DROP, before any probe answers', async () => {
+    // The probe is a request, and a run can settle while it is in flight —
+    // measured as a flaky e2e where `agent_end` arrived first, read a flag that
+    // was still false, and never re-read the transcript. What was lost is a
+    // fact about the drop, so it is written then.
+    let probes = 0;
+    stubProbe({ running: true, state: { isStreaming: true } }, () => { probes += 1; });
+    const harness = await mount(true);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+
+    // No `open` yet: the probe has not even been issued.
+    expect(probes).toBe(0);
+    expect(harness.losses()).toBe(1);
+    expect(harness.settles()).toBe(0);
+  });
+
+  test('a spawn adoption DURING the outage does not lose the fact', async () => {
+    // The effect is keyed on the session id, and that id moves mid-run: a spawn
+    // answers with omp's UUID a beat after the first prompt. A tab that went
+    // away in that window re-mounted the effect INSIDE the outage, and local
+    // variables came back with `wasOpen:false` — so the drop read as a dial
+    // that never opened, nothing was recorded, and the transcript was never
+    // re-read (measured on a real run; the e2e spec caught it as a flake).
+    let probes = 0;
+    stubProbe({ running: true, state: { isStreaming: true } }, () => { probes += 1; });
+    const harness = await mount(true, 'new-1');
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    // The adoption lands while the channel is down.
+    await harness.adopt('omp-1');
+    await harness.setStatus('connecting');
+    await harness.setStatus('open');
+
+    expect(harness.losses()).toBe(1);
+    expect(probes).toBe(1);
+  });
+
+  test('a probe that answers "still live" settles nothing', async () => {
+    stubProbe({ running: true, state: { isStreaming: true } });
+    const harness = await mount(true);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+
+    expect(harness.settles()).toBe(0);
+    expect(harness.losses()).toBe(1);
+  });
+
+  test('the SERVER\'s stream row alone is enough evidence', async () => {
+    // A run whose very FIRST frame (`agent_start`) was the one lost has no
+    // stream-side mark on this client, but the server wrote its `stream` row at
+    // dispatch — and that row is what proves frames could have been missed.
+    // Without this the first-frame loss was unrecoverable: the timeline kept
+    // the empty placeholder while the answer streamed into a socket that was
+    // gone.
+    stubProbe({ running: false });
+    const harness = await mount(true);
+    harness.streamRun.current = false;
+    harness.serverRun.current = true;
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+
+    expect(harness.settles()).toBe(1);
+  });
+
+  test('a drop with no run believed live settles nothing', async () => {
+    stubProbe({ running: true, state: { isStreaming: false, isSettled: true } });
+    const harness = await mount(false);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+
+    expect(harness.settles()).toBe(0);
+  });
+
+  test('a run that finished during the drop is settled once, not on every reconnect', async () => {
+    stubProbe({ running: false });
+    const harness = await mount(true);
+
+    await harness.setStatus('open');
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+    expect(harness.settles()).toBe(1);
+
+    // The settle path releases the generating flag; a second flap must not
+    // re-settle (and must not re-read the transcript again).
+    harness.generating.current = false;
+    await harness.setStatus('closed');
+    await harness.setStatus('open');
+    expect(harness.settles()).toBe(1);
+  });
+});

package/src/client/hooks/chat/omp/reconnect.ts

@@ -0,0 +1,187 @@
+/**
+ * @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.
+ *
+ * Two facts decide when this applies, and both are about the CHANNEL, not about
+ * a run's bookkeeping:
+ *
+ * - frames can only have been missed if the socket was OPEN while a run was
+ *   believed live and then went away. A send whose `connect()` dials a closed
+ *   channel never meets that condition, so the optimistic turn it just mounted
+ *   can never be settled by this path (the prompt is not even on the wire yet).
+ * - the run must be over on the SERVER, asked through the same attach probe the
+ *   mount path uses (`runIsOver`). `busy` is not a verdict there, and an
+ *   unanswered probe settles nothing.
+ *
+ * Recovery is two steps and both are needed: settle the local run (release the
+ * generating flag, drop the ids only a live stream would consume), then re-read
+ * the committed transcript — the rows on screen are the stream's last PARTIAL
+ * segment, and the session JSONL is the only record of the rest.
+ */
+
+import { useEffect, useRef } from 'preact/hooks';
+
+import { realtimeClient } from '@/shared/lib/realtime/client';
+import { runIsOver, type AgentRunProbe } from '@/client/hooks/chat/omp/run-liveness';
+
+export interface ReconnectSettleDeps {
+  /** The session on screen; null for a pending `new-…` chat (no child yet). */
+  sessionId: string | null;
+  /** Live "this page is showing a run" flag — owned or adopted. */
+  isGeneratingRef: { current: boolean };
+  /** The stream has spoken for that run (see `streamRunRef`). */
+  streamRunRef: { current: boolean };
+  /** The SERVER reports a run for this session (`session_stream_state`'s
+   *  `stream` row, the same source the sidebar spinner reads). This is the
+   *  evidence that a prompt was DISPATCHED, which is what makes frame loss
+   *  possible — and it is the only signal available for a run whose own
+   *  `agent_start` was the first frame lost. A prompt that has not reached the
+   *  server yet has no row, so it is still excluded. */
+  serverRunRef: { current: boolean };
+  /** The run is over server-side: settle the local UI and re-read the
+   *  committed transcript. */
+  onSettled: () => void;
+  /** Frames were LOST — called SYNCHRONOUSLY at the drop, not at the probe's
+   *  answer. A run in flight when an open channel goes away has already lost
+   *  whatever finished during the outage: its `message_end` went into the dead
+   *  socket, and `agent_end` only materializes turns that stopped abnormally.
+   *  The caller records it so the transcript is re-read when the run settles.
+   *
+   *  At the DROP, deliberately: the attach probe is a request, so a run can
+   *  settle while it is in flight — measured as a flaky spec where `agent_end`
+   *  arrived first, read a flag that was still false, and never reloaded. What
+   *  is lost is a fact about the drop, not about the probe's answer. */
+  onFramesLost: () => void;
+}
+
+/**
+ * The channel facts this hook needs, held OUTSIDE the effect.
+ *
+ * The effect is keyed on the session id, and that id MOVES mid-run: a spawn
+ * answers with omp's UUID a beat after the first prompt, so the URL — and this
+ * effect — re-mounts. Local variables therefore lose the only two facts that
+ * make the repair possible, measured on a real run: the tab went away during
+ * the spawn adoption, the effect re-mounted inside the outage, `wasOpen` came
+ * back `false`, and the drop was read as "a dial that never opened" — so
+ * nothing was recorded and the transcript was never re-read.
+ */
+interface ChannelFacts {
+  /** The channel was OPEN at the last transition we saw. */
+  wasOpen: boolean;
+  /** A run was in flight when it went away, so frames were lost. */
+  missedFrames: boolean;
+  /**
+   * A run has been seen live for this session since it was last reconciled.
+   *
+   * A LATCH, not a live read, and that is the whole point: the client's
+   * generating flag flickers false during a live run (measured: a `prompt_result`
+   * folded as "settled", and the spawn-adoption window), and a drop that landed
+   * in one of those beats was read as "no run in flight" — so nothing was
+   * recorded and the transcript was never re-read, which is exactly the
+   * cut-off answer this hook exists to repair.
+   */
+  sawRun: boolean;
+  /** The session id `sawRun` belongs to, so a real switch resets it while a
+   *  spawn ADOPTION (same conversation, new id) keeps it. */
+  sessionId: string | null;
+}
+
+export function useReconnectSettle(deps: ReconnectSettleDeps): void {
+  const { sessionId, isGeneratingRef, streamRunRef, serverRunRef, onSettled, onFramesLost } = deps;
+  // Held in a ref: the caller rebuilds `onSettled` on every render (it closes
+  // over the timeline's own callbacks), and an effect keyed on its identity
+  // would re-subscribe constantly.
+  const onSettledRef = useRef(onSettled);
+  onSettledRef.current = onSettled;
+  const onFramesLostRef = useRef(onFramesLost);
+  onFramesLostRef.current = onFramesLost;
+  // Survives a re-mount, which is the whole point (see `ChannelFacts`).
+  const factsRef = useRef<ChannelFacts | null>(null);
+
+  // Latch the run evidence on EVERY render, before any effect runs: the flags
+  // are refs, so a beat that flickers false would otherwise erase the only
+  // proof a run existed when the channel went away.
+  const facts = (factsRef.current ??= {
+    wasOpen: realtimeClient.status() === 'open',
+    missedFrames: false,
+    sawRun: false,
+    sessionId,
+  });
+  // Re-read the CHANNEL on every render, because this hook re-mounts and the
+  // channel does not. Measured: the effect was re-created while the socket was
+  // OPEN (a spawn adoption, a session-state re-render), the latch still said
+  // `wasOpen:false` from before that, and the following drop was read as a dial
+  // that never opened — so the repair never ran. Only the TRANSITION matters,
+  // so reconciling here cannot invent a loss: `missedFrames` is still armed by
+  // the subscriber alone.
+  facts.wasOpen = realtimeClient.status() === 'open';
+  if (isGeneratingRef.current || streamRunRef.current || serverRunRef.current) facts.sawRun = true;
+  // A genuine switch (nothing live) starts over; an adoption keeps the latch.
+  if (facts.sessionId !== sessionId) {
+    if (!isGeneratingRef.current && !serverRunRef.current) facts.sawRun = false;
+    facts.sessionId = sessionId;
+  }
+
+  useEffect(() => {
+    if (!sessionId) return;
+    // Lit when an OPEN channel goes away while a run is in flight: the only
+    // state in which frames can have been missed. `wasOpen` is what separates
+    // that from a dial: a send whose `connect()` opens a closed channel also
+    // passes through `connecting`, and settling on that would delete the
+    // optimistic turn of a prompt that is not even on the wire yet.
+    let cancelled = false;
+
+    const unsubscribe = realtimeClient.onStatus(() => {
+      if (cancelled) return;
+      if (realtimeClient.status() !== 'open') {
+        // Either piece of evidence that a run is in flight: the stream named it,
+        // or the server's `stream` row exists (which also covers a run whose
+        // very first frame — `agent_start` — was the one lost).
+        if (facts.wasOpen && facts.sawRun) {
+          facts.missedFrames = true;
+          // Recorded NOW: the probe below is a request, and a run that settles
+          // while it is in flight would otherwise settle against a flag that
+          // has not been written yet.
+          onFramesLostRef.current();
+        }
+        facts.wasOpen = false;
+        return;
+      }
+      facts.wasOpen = true;
+      if (!facts.missedFrames) return;
+      facts.missedFrames = false;
+      // Deliberately NOT gated on `isGeneratingRef`: the flag can be false for a
+      // run that is still live (or one that ended while the tab was away), and
+      // the probe below is the authority on which it is.
+      void (async () => {
+        const probe = await fetch(`/api/agent/${encodeURIComponent(sessionId)}`)
+          .then((res) => (res.ok ? (res.json() as Promise<AgentRunProbe>) : null))
+          .catch(() => null);
+        // Re-checked at the answer, not only at the trigger: the user may have
+        // switched sessions while the probe was in flight.
+        if (cancelled) return;
+        // Still live: nothing to settle, and the loss is already recorded.
+        if (!runIsOver(probe)) return;
+        facts.sawRun = false;
+        onSettledRef.current();
+      })();
+    });
+
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [sessionId, isGeneratingRef, streamRunRef, serverRunRef]);
+}

package/src/client/hooks/chat/omp/run-liveness.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `runIsOver` — the verdict a reattached client asks before settling a run it
+ * was following. Every case here is a shape the server really produces:
+ *
+ * - `running:false` is the answer for a session this process does not manage
+ *   (and for one whose child is gone): the run is over, whatever the local
+ *   generating flag still believes;
+ * - `busy` with no run is NOT over — the server sets it for work a probe would
+ *   queue behind (a live subagent whose parent turn ended, a parked dialog);
+ * - a live `isStreaming`/`isPromptRunning` is NOT over;
+ * - no answer at all (a failed request) is NOT a verdict.
+ *
+ * The asymmetry is deliberate: settling a run that is still going throws away
+ * the streaming answer, while missing a settle costs a reload.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { runIsOver } from '@/client/hooks/chat/omp/run-liveness';
+
+describe('runIsOver', () => {
+  test('a session this process does not run is over', () => {
+    expect(runIsOver({ running: false })).toBe(true);
+  });
+
+  test('no answer is not a verdict', () => {
+    expect(runIsOver(null)).toBe(false);
+    expect(runIsOver(undefined)).toBe(false);
+  });
+
+  test('a busy session with no run in flight is NOT over', () => {
+    // A live subagent whose parent turn ended, or a dialog a reloaded client
+    // has not answered: settling here would abandon the work still running.
+    expect(runIsOver({ running: true, busy: true, state: { isStreaming: false, isPromptRunning: false } })).toBe(false);
+  });
+
+  test('a streaming or prompting run is NOT over', () => {
+    expect(runIsOver({ running: true, state: { isStreaming: true, isPromptRunning: false } })).toBe(false);
+    expect(runIsOver({ running: true, state: { isStreaming: false, isPromptRunning: true } })).toBe(false);
+  });
+
+  test('omp\'s verdict is REQUIRED: a child with nothing streaming is not enough', () => {
+    // A turn can be admitted but not yet streaming, and a build that does not
+    // report `isSettled` cannot tell us which. The server refuses to settle on
+    // anything but `isSettled === true` (`RunSettle`), so this must too —
+    // otherwise the client reloads a transcript the server still considers live.
+    expect(runIsOver({ running: true, state: { isStreaming: false, isPromptRunning: false } })).toBe(false);
+    expect(runIsOver({ running: true, state: { isStreaming: false, isPromptRunning: false, isSettled: true } })).toBe(true);
+  });
+
+  test('omp\'s own quiescence verdict decides when it is present', () => {
+    expect(runIsOver({ running: true, state: { isSettled: true } })).toBe(true);
+    // omp says something is still admitted/scheduled/queued: a retry wait, a
+    // background job. Not over.
+    expect(runIsOver({ running: true, state: { isSettled: false } })).toBe(false);
+  });
+
+  test('a payload with no state is not read as settled', () => {
+    expect(runIsOver({ running: true })).toBe(false);
+  });
+
+  test('a queued follow-up keeps the session open even when it reads settled', () => {
+    // omp will wake again, so this is not a finished run: settling would reload
+    // the transcript while the next turn is about to open.
+    expect(runIsOver({ running: true, state: { isSettled: true, queuedMessageCount: 1 } })).toBe(false);
+  });
+});

package/src/client/hooks/chat/omp/run-liveness.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Whether the run a REATTACHED client was following is over.
+ *
+ * A socket that comes back after a run's terminal frames were lost with it
+ * leaves the timeline holding the stream's last `message_update` — a partial
+ * answer — and nothing else will ever finalize it: `message_end` and
+ * `agent_end` were emitted into a socket nobody was reading. The snapshot that
+ * repairs the attachment says only whether a run is live NOW, and that answer
+ * has to be read precisely, because the SAME shape ("child alive, nothing
+ * running") appears in the beat between a send's `connect()` and its prompt —
+ * acting on it there would settle a run that is about to start.
+ *
+ * `busy` is deliberately NOT evidence either way: the server sets it for work a
+ * probe would queue behind (a live subagent whose parent turn ended, a parked
+ * dialog), and a session with something else live is left alone rather than
+ * settled.
+ *
+ * The final word is omp's OWN verdict, `state.isSettled`, and it must be
+ * literally `true`. The server's `RunSettle` applies exactly that rule
+ * (`isSettled !== true` → do not settle), and two answers to "is this run over"
+ * is how the indicator and the transcript end up disagreeing. A build that does
+ * not report the field therefore settles nothing here — a reload costs one
+ * reconnect, while settling a live run throws the streaming answer away.
+ */
+
+/** The `GET /api/agent/:id` / topic-snapshot payload, narrowed to what this
+ *  decision reads. */
+export interface AgentRunProbe {
+  running?: boolean;
+  busy?: boolean;
+  state?: {
+    isStreaming?: boolean;
+    isPromptRunning?: boolean;
+    /** omp's own quiescence verdict. Absent on builds that do not report it. */
+    isSettled?: boolean;
+    /** Follow-ups and steers omp has accepted but not run yet. A non-zero
+     *  count means the session WILL wake again, so it is not finished — and it
+     *  is what keeps this from settling a session whose queued prompt was
+     *  delivered server-side while the tab was away. */
+    queuedMessageCount?: number;
+  } | null;
+}
+
+export function runIsOver(probe: AgentRunProbe | null | undefined): boolean {
+  // No answer (a failed request, a refused payload) is not a verdict: leave the
+  // timeline alone and let the next reconnect ask again.
+  if (!probe) return false;
+  if (probe.running === false) return true;
+  if (probe.busy) return false;
+  const state = probe.state;
+  if (!state) return false;
+  if (state.isStreaming || state.isPromptRunning) return false;
+  if (typeof state.queuedMessageCount === 'number' && state.queuedMessageCount > 0) return false;
+  // omp's own quiescence verdict, and the ONLY thing that may settle a run —
+  // the same rule the server applies (`RunSettle`: `isSettled !== true` → do
+  // not settle). Absent means the build does not report it, which is NOT
+  // evidence of quiescence: a turn can be admitted but not yet streaming, and
+  // settling there would reload the transcript mid-dispatch.
+  return state.isSettled === true;
+}