fix(web-shell): reset managed stream backoff on delivered events

When an SSE connection dies by proxy idle timeout it surfaces as a status-less throw, so the stream loop's end-of-iteration reset never ran and the shared failure counter climbed to the 30s cap for the life of the panel even though every reconnect succeeded and delivered events. Reset on progress inside the for-await body, matching the bootstrap and summary loops' notion of success. Also pin previously unwitnessed review invariants: the empty-incoming merge case (a load-bearing crash guard, not an optimization), the exact exponential backoff ladder under a deterministic random, the stream loop's non-retryable exit and its unchanged resubscribe cursor, and comments documenting the exact-3s first-failure floor and the merge fast path's sorted-input contract. Co-authored-by: Qwen-Coder <[email protected]>
wenshao · Oct 1, 2026 · Oct 1, 2026 · Oct 2, 2026 · Oct 2, 2026 · Oct 2, 2026
commit 3ad03d2ea17e57991110fdb48c19bf5c94a6b05e
diff --git a/packages/web-shell/client/components/managed/managed-session-messages.test.ts b/packages/web-shell/client/components/managed/managed-session-messages.test.ts
@@ -204,6 +204,15 @@ describe('Managed transcript projection', () => {
     expect(merged[2]?.data).toEqual({ text: 'newer' });
   });
 
+  it('returns the current events unchanged for an empty incoming page', () => {
+    expect(
+      mergeManagedEvents([event(1, 'accepted'), event(2, 'completed')], []).map(
+        (item) => item.id,
+      ),
+    ).toEqual([1, 2]);
+    expect(mergeManagedEvents([], []).map((item) => item.id)).toEqual([]);
+  });
+
   it('keeps approval updates out of the Turn being streamed', () => {
     const messages = managedEventsToMessages(
       [

diff --git a/packages/web-shell/client/components/managed/managed-session-messages.ts b/packages/web-shell/client/components/managed/managed-session-messages.ts
@@ -2,10 +2,15 @@ import type { ACPToolCall, Message } from '../../adapters/types';
 import type { ManagedAgentSessionEvent } from './managed-agent-provider';
 import type { ManagedToolResult } from './managed-tool-result-types';
 
+// `current` must already be ascending and deduplicated by id (stream state
+// and transcript pages are); the append path checks only that `incoming`
+// extends it, so a disordered first argument stays disordered.
 export function mergeManagedEvents(
   current: readonly ManagedAgentSessionEvent[],
   incoming: readonly ManagedAgentSessionEvent[],
 ): ManagedAgentSessionEvent[] {
+  // An empty input cannot ride the ascending check: strictlyAscendingIds
+  // loops from index 1, and the fast path dereferences incoming[0].
   if (incoming.length === 0) return [...current];
   if (
     strictlyAscendingIds(incoming) &&

diff --git a/packages/web-shell/client/components/managed/use-managed-session.test.tsx b/packages/web-shell/client/components/managed/use-managed-session.test.tsx
@@ -94,6 +94,129 @@ describe('useManagedSession', () => {
     });
   });
 
+  it('grows the failure backoff exponentially toward the jittered cap', () => {
+    const random = vi.spyOn(Math, 'random').mockReturnValue(0.5);
+    try {
+      expect([0, 1, 2, 3, 4, 5, 6].map(failureRetryDelayMs)).toEqual([
+        3_000, 4_500, 7_500, 13_500, 16_500, 16_500, 16_500,
+      ]);
+    } finally {
+      random.mockRestore();
+    }
+  });
+
+  it('resets the stream backoff after every delivered event', async () => {
+    vi.useFakeTimers();
+    const random = vi.spyOn(Math, 'random').mockReturnValue(0.999999);
+    try {
+      let calls = 0;
+      const subscribeEvents = vi.fn(async function* (
+        _sessionId: string,
+        request: { signal?: AbortSignal },
+      ) {
+        calls++;
+        if (calls <= 3) {
+          yield event(calls);
+          throw new TypeError('connection reset by peer');
+        }
+        yield event(4);
+        await new Promise((resolve) =>
+          request.signal?.addEventListener('abort', resolve),
+        );
+      });
+      const provider = {
+        getSession: vi.fn().mockResolvedValue({ sessionId: 'session-1' }),
+        getTranscript: vi.fn().mockResolvedValue(transcript(1)),
+        subscribeEvents,
+      } as unknown as ManagedAgentProvider;
+      function Probe() {
+        useManagedSession(provider, 'client-1', 'session-1');
+        return null;
+      }
+      root = createRoot(document.createElement('div'));
+      act(() => root!.render(<Probe />));
+      await act(async () => {});
+      for (let step = 0; step < 3; step++)
+        await act(async () => {
+          await vi.advanceTimersByTimeAsync(3_000);
+        });
+      expect(
+        subscribeEvents.mock.calls.map(([, options]) => options.lastEventId),
+      ).toEqual([1, 1, 2, 3]);
+    } finally {
+      random.mockRestore();
+      vi.useRealTimers();
+    }
+  });
+
+  it('stops resubscribing when the stream answers with a non-retryable error', async () => {
+    vi.useFakeTimers();
+    try {
+      const subscribeEvents = vi.fn(async function* () {
+        yield event(1);
+        throw Object.assign(new Error('session gone'), { status: 404 });
+      });
+      const provider = {
+        getSession: vi.fn().mockResolvedValue({ sessionId: 'session-1' }),
+        getTranscript: vi.fn().mockResolvedValue(transcript(1)),
+        subscribeEvents,
+      } as unknown as ManagedAgentProvider;
+      function Probe() {
+        useManagedSession(provider, 'client-1', 'session-1');
+        return null;
+      }
+      root = createRoot(document.createElement('div'));
+      act(() => root!.render(<Probe />));
+      await act(async () => {});
+      expect(subscribeEvents).toHaveBeenCalledTimes(1);
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(120_000);
+      });
+      expect(subscribeEvents).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('resubscribes an unchanged cursor after a retryable stream failure', async () => {
+    vi.useFakeTimers();
+    try {
+      let calls = 0;
+      const subscribeEvents = vi.fn(async function* (
+        _sessionId: string,
+        request: { signal?: AbortSignal },
+      ) {
+        calls++;
+        if (calls === 1)
+          throw Object.assign(new Error('server busy'), { status: 500 });
+        yield event(2);
+        await new Promise((resolve) =>
+          request.signal?.addEventListener('abort', resolve),
+        );
+      });
+      const provider = {
+        getSession: vi.fn().mockResolvedValue({ sessionId: 'session-1' }),
+        getTranscript: vi.fn().mockResolvedValue(transcript(1)),
+        subscribeEvents,
+      } as unknown as ManagedAgentProvider;
+      function Probe() {
+        useManagedSession(provider, 'client-1', 'session-1');
+        return null;
+      }
+      root = createRoot(document.createElement('div'));
+      act(() => root!.render(<Probe />));
+      await act(async () => {});
+      expect(subscribeEvents).toHaveBeenCalledTimes(1);
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(3_000);
+      });
+      expect(subscribeEvents).toHaveBeenCalledTimes(2);
+      expect(subscribeEvents.mock.calls[1]?.[1].lastEventId).toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('stops the bootstrap retry loop on a non-retryable failure', async () => {
     vi.useFakeTimers();
     try {

diff --git a/packages/web-shell/client/components/managed/use-managed-session.ts b/packages/web-shell/client/components/managed/use-managed-session.ts
@@ -10,6 +10,9 @@ import { mergeManagedEvents } from './managed-session-messages';
 const BASE_RETRY_DELAY_MS = 3_000;
 const MAX_RETRY_DELAY_MS = 30_000;
 
+// Rung zero must stay exactly BASE_RETRY_DELAY_MS: ManagedSessionsPage pins
+// the gap-recovery cadence with a 2999/3000ms boundary in another file, and
+// any first-failure jitter would break it.
 export function failureRetryDelayMs(failures: number): number {
   const cap = Math.min(MAX_RETRY_DELAY_MS, BASE_RETRY_DELAY_MS * 2 ** failures);
   return (
@@ -116,6 +119,9 @@ export function useManagedSession(
             }
             if (event.id <= lastEventId) continue;
             lastEventId = event.id;
+            // A delivered event proves the connection healthy even when it
+            // later dies by proxy idle timeout, which surfaces as a throw.
+            failures = 0;
             setState((current) => ({
               ...current,
               events: mergeManagedEvents(current.events, [event]),