Bound the post-open handshake wait so a silent server can't hang the spinner

If the terminal server accepted the WebSocket but never sent its hello /
status:connected, the UI hung forever on the yellow "Connecting" (initial /
resume) or "Reconnecting" (auto-reconnect) box. The 30s connection timeout only
covers the pre-open CONNECTING phase, so once a socket opened there was nothing
to bound the wait — reproduced both in the unit harness and the live dashboard.

Arm an "awaiting hello" timeout (12s) when a socket opens; if it elapses before
we reach `connected`, close the socket with a private recoverable code (4901)
so the reconnect scheduler retries — with fresh credentials — and ultimately
lands on the recoverable "Press Enter" prompt instead of a frozen spinner. The
timer is cleared on connected and on close.

DX-1379

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: matt423

packages/react-web-cli/src/AblyCliTerminal.inactivity.test.tsx

@@ -77,6 +77,7 @@ vi.mock("./utils/crypto", () => ({
 // visibility changes trigger real re-renders.
 import { AblyCliTerminal } from "./AblyCliTerminal";
 import { CONTROL_MESSAGE_PREFIX } from "./terminal-shared";
+import * as GlobalReconnect from "./global-reconnect";
 
 const createControlMessage = (payload: unknown) =>
   CONTROL_MESSAGE_PREFIX + JSON.stringify(payload);
@@ -582,4 +583,151 @@ describe("DX-1379: inactivity pause & resume-on-return", () => {
       expect(authSend?.signature).toBe(SIGNATURE);
     },
   );
+
+  // The reporter's "stuck on Connecting/Reconnecting to Ably" symptom: a socket
+  // that opens but never receives the server's hello. Before the await-hello
+  // timeout this hung forever (the 30s connection timeout only covers the
+  // pre-open CONNECTING phase). It must now be force-closed for retry. (DX-1379)
+  const AWAIT_HELLO_MS = 12_000;
+
+  test("a socket that opens but never receives hello is force-closed for retry (not left hanging)", async () => {
+    await act(async () => {
+      render(
+        <AblyCliTerminal
+          websocketUrl={WS_URL}
+          signedConfig={SIGNED_CONFIG}
+          signature={SIGNATURE}
+          resumeOnReload
+          inactivityTimeoutMs={INACTIVITY_MS}
+          maxReconnectAttempts={15}
+        />,
+      );
+    });
+    await flush();
+    const ws = sockets[0];
+    await act(async () => {
+      ws.fireOpen(); // opens, but the server stays silent (no hello)
+    });
+    await flush();
+
+    // Just before the threshold: still waiting, not force-closed.
+    await act(async () => {
+      vi.advanceTimersByTime(AWAIT_HELLO_MS - 1000);
+    });
+    expect(
+      ws.close.mock.calls.some(
+        ([, reason]) => reason === "awaiting-hello-timeout",
+      ),
+    ).toBe(false);
+
+    // Cross the await-hello threshold -> the silent socket is closed for retry.
+    await act(async () => {
+      vi.advanceTimersByTime(1500);
+    });
+    await flush();
+    const helloTimeoutClose = ws.close.mock.calls.find(
+      ([code, reason]) => code === 4901 && reason === "awaiting-hello-timeout",
+    );
+    expect(helloTimeoutClose).toBeTruthy();
+  });
+
+  test("a resumed socket that never receives hello is closed for retry (the stuck-reconnecting repro)", async () => {
+    await renderConnected("sess-hang");
+
+    await act(async () => {
+      setVisibility("hidden");
+    });
+    await flush();
+    await act(async () => {
+      vi.advanceTimersByTime(INACTIVITY_MS + 10);
+    });
+    await flush();
+
+    const afterPause = sockets.length;
+    await act(async () => {
+      setVisibility("visible");
+    });
+    await flush();
+    await act(async () => {
+      vi.advanceTimersByTime(50);
+    });
+    await flush();
+
+    const resumeSocket = sockets[afterPause];
+    await act(async () => {
+      resumeSocket.fireOpen(); // resume socket opens; server never sends hello
+    });
+    await flush();
+
+    // It must not hang: after the await-hello timeout the resume socket is closed.
+    await act(async () => {
+      vi.advanceTimersByTime(AWAIT_HELLO_MS + 500);
+    });
+    await flush();
+    const helloTimeoutClose = resumeSocket.close.mock.calls.find(
+      ([code, reason]) => code === 4901 && reason === "awaiting-hello-timeout",
+    );
+    expect(helloTimeoutClose).toBeTruthy();
+  });
+
+  test("a hello within the await-hello window keeps the connection (no spurious close)", async () => {
+    await act(async () => {
+      render(
+        <AblyCliTerminal
+          websocketUrl={WS_URL}
+          signedConfig={SIGNED_CONFIG}
+          signature={SIGNATURE}
+          resumeOnReload
+          inactivityTimeoutMs={INACTIVITY_MS}
+        />,
+      );
+    });
+    await flush();
+    const ws = sockets[0];
+    await act(async () => {
+      ws.fireOpen();
+    });
+    await flush();
+    // Server replies in time.
+    await act(async () => {
+      ws.fireMessage(
+        createControlMessage({ type: "hello", sessionId: "sess-ok" }),
+      );
+    });
+    await flush();
+
+    // Advancing past the await-hello window must NOT close the live socket.
+    await act(async () => {
+      vi.advanceTimersByTime(AWAIT_HELLO_MS + 2000);
+    });
+    await flush();
+    // The live socket is not closed and stays usable.
+    expect(
+      ws.close.mock.calls.some(
+        ([, reason]) => reason === "awaiting-hello-timeout",
+      ),
+    ).toBe(false);
+    expect(ws.readyState).toBe(FakeWebSocket.OPEN);
+  });
+
+  test("the await-hello close code (4901) routes to a reconnect, not a terminal disconnect", async () => {
+    const ws = await renderConnected("sess-route");
+    // Isolate the effect of the 4901 close from the initial-connect bookkeeping.
+    vi.mocked(GlobalReconnect.increment).mockClear();
+    vi.mocked(GlobalReconnect.scheduleReconnect).mockClear();
+
+    // A 4901 close (what the await-hello timeout emits) must be treated as
+    // recoverable: schedule a reconnect rather than purging the session.
+    await act(async () => {
+      ws.fireClose(4901, "awaiting-hello-timeout");
+    });
+    await flush();
+
+    expect(GlobalReconnect.increment).toHaveBeenCalled();
+    expect(GlobalReconnect.scheduleReconnect).toHaveBeenCalled();
+    // Recoverable => the session is NOT purged.
+    expect(sessionStorage.getItem(`ably.cli.sessionId.${URL_HOST}`)).toBe(
+      "sess-route",
+    );
+  });
 });

packages/react-web-cli/src/AblyCliTerminal.tsx

@@ -206,6 +206,18 @@ const BASE_NON_RECOVERABLE_CLOSE_CODES = [
 // never confused.
 const INACTIVITY_PAUSE_CLOSE_CODE = 4900;
 
+// Private recoverable close code used when a socket opens but the server never
+// sends its `hello`/`connected` within AWAIT_HELLO_TIMEOUT_MS. Closing it as a
+// (recoverable, not in NON_RECOVERABLE) failure lets the reconnect scheduler
+// retry rather than leaving the UI stuck on "Connecting"/"Reconnecting" forever.
+const AWAIT_HELLO_CLOSE_CODE = 4901;
+
+// How long to wait, after a socket has *opened*, for the server's first
+// `hello`/`status: connected` before treating the attempt as failed. The 30s
+// connection timeout only covers the pre-open CONNECTING phase, so without this
+// a silent-but-accepting server hangs the spinner indefinitely (DX-1379).
+const AWAIT_HELLO_TIMEOUT_MS = 12_000;
+
 const AblyCliTerminalInner = (
   {
     websocketUrl,
@@ -685,9 +697,14 @@ const AblyCliTerminalInner = (
     (status: ConnectionStatus) => {
       // updateConnectionStatusAndExpose debug removed
       // A successful connection clears any in-flight inactivity-resume guard so
-      // a later unrelated disconnect isn't misread as a failed resume.
+      // a later unrelated disconnect isn't misread as a failed resume, and the
+      // "awaiting hello" timeout (the handshake completed).
       if (status === "connected") {
         resumeAttemptReference.current = false;
+        if (awaitHelloTimerReference.current) {
+          clearTimeout(awaitHelloTimerReference.current);
+          awaitHelloTimerReference.current = null;
+        }
       }
       setComponentConnectionStatusState(status);
       // (window as any).componentConnectionStatusForTest = status; // Keep for direct inspection if needed, but primary is below
@@ -761,6 +778,26 @@ const AblyCliTerminalInner = (
     }
   }, []);
 
+  // "Awaiting hello" timeout: armed once a socket opens, cleared on
+  // connected/close. Guards against a server that accepts the socket but never
+  // completes the handshake.
+  const awaitHelloTimerReference = useRef<NodeJS.Timeout | null>(null);
+  const clearAwaitHelloTimer = useCallback(() => {
+    if (awaitHelloTimerReference.current) {
+      clearTimeout(awaitHelloTimerReference.current);
+      awaitHelloTimerReference.current = null;
+    }
+  }, []);
+
+  // Same guard for the split-screen secondary socket (its own timer).
+  const secondaryAwaitHelloTimerReference = useRef<NodeJS.Timeout | null>(null);
+  const clearSecondaryAwaitHelloTimer = useCallback(() => {
+    if (secondaryAwaitHelloTimerReference.current) {
+      clearTimeout(secondaryAwaitHelloTimerReference.current);
+      secondaryAwaitHelloTimerReference.current = null;
+    }
+  }, []);
+
   const clearInstallInstructionsTimer = useCallback(() => {
     if (installInstructionsTimerReference.current) {
       clearTimeout(installInstructionsTimerReference.current);
@@ -1577,6 +1614,24 @@ const AblyCliTerminalInner = (
         sock.send(JSON.stringify(payload));
       }
 
+      // Arm the "awaiting hello" timeout: the socket is open, but until the
+      // server sends its hello/connected we have no session. If it never
+      // arrives, force-close this socket as a recoverable failure so the
+      // reconnect scheduler retries instead of the UI hanging on the spinner.
+      clearAwaitHelloTimer();
+      awaitHelloTimerReference.current = setTimeout(() => {
+        if (connectionStatusReference.current !== "connected") {
+          debugLog(
+            `⚠️ DIAGNOSTIC: No hello within ${AWAIT_HELLO_TIMEOUT_MS}ms of open - closing socket to retry`,
+          );
+          try {
+            sock.close(AWAIT_HELLO_CLOSE_CODE, "awaiting-hello-timeout");
+          } catch {
+            /* ignore */
+          }
+        }
+      }, AWAIT_HELLO_TIMEOUT_MS);
+
       // Set up initial command to be sent when prompt is detected
       // Skip initial command if we're resuming an existing session
       if (initialCommand && !sessionId) {
@@ -1600,6 +1655,7 @@ const AblyCliTerminalInner = (
       clearPtyBuffer,
       sessionId,
       clearConnectionTimeout,
+      clearAwaitHelloTimer,
       refreshAuth,
     ],
   );
@@ -1844,6 +1900,7 @@ const AblyCliTerminalInner = (
         `[AblyCLITerminal] WebSocket closed. Code: ${event.code}, Reason: ${event.reason}, Clean: ${event.wasClean}`,
       );
       clearConnectionTimeout(); // Clear timeout on close
+      clearAwaitHelloTimer();
       clearTerminalBoxOnly();
       updateSessionActive(false);
 
@@ -2070,6 +2127,7 @@ const AblyCliTerminalInner = (
       resumeOnReload,
       sessionId,
       clearConnectionTimeout,
+      clearAwaitHelloTimer,
       clearPtyBuffer,
     ],
   );
@@ -2796,6 +2854,11 @@ const AblyCliTerminalInner = (
   ]);
 
   useEffect(() => () => clearInactivityTimer(), [clearInactivityTimer]);
+  useEffect(() => () => clearAwaitHelloTimer(), [clearAwaitHelloTimer]);
+  useEffect(
+    () => () => clearSecondaryAwaitHelloTimer(),
+    [clearSecondaryAwaitHelloTimer],
+  );
 
   // Cleanup install instructions timer on unmount
   useEffect(
@@ -3118,6 +3181,19 @@ const AblyCliTerminalInner = (
           newSocket.send(JSON.stringify(payload));
         }
 
+        // Bound the wait for the server's hello on the secondary socket too, so
+        // a silent-but-accepting server can't hang the secondary pane's spinner.
+        clearSecondaryAwaitHelloTimer();
+        secondaryAwaitHelloTimerReference.current = setTimeout(() => {
+          if (secondaryConnectionStatusReference.current !== "connected") {
+            try {
+              newSocket.close(AWAIT_HELLO_CLOSE_CODE, "awaiting-hello-timeout");
+            } catch {
+              /* ignore */
+            }
+          }
+        }, AWAIT_HELLO_TIMEOUT_MS);
+
         // Set up initial command to be sent when prompt is detected
         // Skip initial command if we're resuming an existing session
         if (initialCommand && !secondarySessionId) {
@@ -3346,6 +3422,7 @@ const AblyCliTerminalInner = (
       debugLog(
         `[AblyCLITerminal] [Secondary] WebSocket closed. Code: ${event.code}, Reason: ${event.reason}`,
       );
+      clearSecondaryAwaitHelloTimer();
       setIsSecondarySessionActive(false);
       updateSecondaryConnectionStatus("disconnected");
 
@@ -3740,6 +3817,10 @@ const AblyCliTerminalInner = (
       // Update internal state for the secondary terminal
       setSecondaryConnectionStatus(status);
       secondaryConnectionStatusReference.current = status;
+      if (status === "connected" && secondaryAwaitHelloTimerReference.current) {
+        clearTimeout(secondaryAwaitHelloTimerReference.current);
+        secondaryAwaitHelloTimerReference.current = null;
+      }
 
       // We intentionally don't call onConnectionStatusChange here
       // as per requirements - only the primary terminal status should be reported