fix(frontend): make disconnect indicator clickable to reconnect (#9410)

## 📝 Summary

Closes #9385 

**This pull request was primarily authored by a coding agent.**

### Problem

When marimo is accessed over an SSH-forwarded tunnel (or any flaky
link), the kernel WebSocket drops on tunnel reset or laptop sleep. The
browser shows the broken-link indicator in the top-left, and the only
recovery is a full page reload — disruptive because it resets scroll
position, cell focus, and any unsaved client state, despite the kernel
surviving the WS drop in edit mode and the server already supporting
session resume on a fresh connection
(`marimo/_server/api/endpoints/ws/ws_session_connector.py`).

The frontend was forcing the reload because of two compounding issues:

1. **One-shot reconnect gate**:
`useMarimoKernelConnection.shouldTryReconnecting` only resets on a
successful `onOpen`. After partysocket's 10-retry budget is exhausted,
the gate stays closed and `ws.reconnect()` is never called again from
our code.
2. **Upstream partysocket bug**: in `partysocket@1.1.10`, `_connectLock`
leaks in the `_connect()` max-retries early-return — even if the gate
were reset, `ws.reconnect()` would silently no-op because the lock is
permanently held. Fixed upstream in
[partykit#322](cloudflare/partykit#322),
released as partysocket 1.1.13.
3. **Stuck spinner**: the `onClose` default branch always sets state to
`CONNECTING`, even after partysocket has exhausted its retry budget —
the spinner outlives the actual retry loop with no escape.

The broken-link icon also gives the visual impression of being clickable
but is a no-op `<div>` today.

### What changed

This is two commits — a dependency bump (precondition) followed by the
frontend fix.

#### `chore(frontend): bump partysocket 1.1.10 → 1.1.13`

Patch-version bump pulling in the upstream `_connectLock` fix. No
API-surface changes — verified that `retryCount`, `reconnect()`, and
`maxRetries` signatures are identical between 1.1.10 and 1.1.13. The
lockfile diff is exactly 6 lines, all about partysocket.

#### `fix(frontend): make disconnect indicator clickable to reconnect`

- **Disconnect indicator becomes a real `<button>`** (`status.tsx`).
Native button gives Enter/Space activation and accessibility; previously
it was a `<div>` with a tooltip. When the connection is in a recoverable
CLOSED state, clicking calls a new `reconnect()` exposed by
`useMarimoKernelConnection`. When the connection is `CLOSED` for any
other reason, the button is `disabled`.
- **`reconnect()` probes the runtime first** via the existing
`runtimeManager.isHealthy()` (`/health`). If the server is genuinely
unreachable (e.g. the SSH tunnel is dead), we transition straight back
to `CLOSED + KERNEL_DISCONNECTED` in ~1s instead of burning
partysocket's full retry budget on the silent click. The probe also
resets the one-shot reconnect gate so subsequent automatic retries work.
- **Surface `CLOSED` when partysocket has given up.** In the `onClose`
default branch, when `ws.retryCount >= MAX_RETRIES`, transition to
`CLOSED + KERNEL_DISCONNECTED` instead of `CONNECTING`. This makes the
disconnect icon reappear and become clickable again, so the user can
manually retry without reloading. Without this, the spinner stayed up
forever even after partysocket had stopped trying.
- **Refactor**: the inline switch on `event.reason` in `onClose` is
extracted into a pure `classifyCloseEvent` helper (`close-handler.ts`)
so the regression behavior can be unit-tested. The hook is now thin
glue: classify → setConnection → optionally close transport or call
`tryReconnecting`.
- **Tests**: `close-handler.test.ts` (15 cases) covers each terminal
reason plus the retry-budget-exhaustion path. `status.test.tsx` (3
cases) covers the click → callback wiring and the disabled state.

### Heads-up for review

- **`runtimeManager.isHealthy()` has a side effect** (`setDOMBaseUri()`
on success). It was previously only triggered during initial startup;
now it can fire on each manual reconnect. Almost certainly a no-op in
practice (URL hasn't changed) but flagging in case you want it gated.
- **`IConnectionTransport.retryCount` was added** to the transport
interface so the close handler can detect partysocket give-up. This
leaks a partysocket-specific concept into a transport-agnostic
interface; an alternative would be to have the transport emit a
synthetic close event with a "gave-up" reason. Open to that direction if
preferred — current approach was chosen for minimal diff.
- **No automatic-behavior changes** for users on a healthy connection.
The only paths that exercise the new code are user-initiated clicks and
the previously-stuck post-give-up case.
- **No new user-facing strings.** `"kernel not found"` / tooltip text
reuse existing copy; only new string is the tooltip suffix `"— click to
reconnect"`.

## 📋 Pre-Review Checklist
<!-- These checks need to be completed before a PR is reviewed -->

- [ ] For large changes, or changes that affect the public API: this
change was discussed or approved through an issue, on
[Discord](https://marimo.io/discord?ref=pr), or the community
[discussions](https://github.com/marimo-team/marimo/discussions) (Please
provide a link if applicable).
- [x] Any AI generated code has been reviewed line-by-line by the human
PR author, who stands by it.
- [x] Video or media evidence is provided for any visual changes
(optional). <!-- PR is more likely to be merged if evidence is provided
for changes made -->

## ✅ Merge Checklist

- [x] I have read the [contributor
guidelines](https://github.com/marimo-team/marimo/blob/main/CONTRIBUTING.md).
- [x] Documentation has been updated where applicable, including
docstrings for API changes.
- [x] Tests have been added for the changes made.


I have read the CLA Document and I hereby sign the CLA

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: bestvibes

frontend/package.json

@@ -120,7 +120,7 @@
     "lz-string": "^1.5.0",
     "marked": "^15.0.12",
     "mermaid": "^11.12.3",
-    "partysocket": "1.1.10",
+    "partysocket": "1.1.13",
     "path-to-regexp": "^8.4.0",
     "plotly.js": "^3.3.1",
     "pyodide": "0.27.7",

frontend/src/components/editor/app-container.tsx

@@ -15,20 +15,26 @@ interface Props {
   connection: ConnectionStatus;
   isRunning: boolean;
   width: AppConfig["width"];
+  onReconnect?: () => void;
 }
 
 export const AppContainer: React.FC<PropsWithChildren<Props>> = ({
   width,
   connection,
   isRunning,
   children,
+  onReconnect,
 }) => {
   const connectionState = connection.state;
 
   return (
     <>
       <DynamicFavicon isRunning={isRunning} />
-      <StatusOverlay connection={connection} isRunning={isRunning} />
+      <StatusOverlay
+        connection={connection}
+        isRunning={isRunning}
+        onReconnect={onReconnect}
+      />
       <PyodideLoader>
         <WrappedWithSidebar>
           {/** oxlint-ignore-next-line -- ID is used by other components to grab the DOM element */}

frontend/src/components/editor/header/__tests__/status.test.tsx

@@ -0,0 +1,108 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+// @vitest-environment jsdom
+
+import { fireEvent, render } from "@testing-library/react";
+import { createStore, Provider as JotaiProvider } from "jotai";
+import type React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { viewStateAtom } from "@/core/mode";
+import {
+  type ConnectionStatus,
+  WebSocketClosedReason,
+  WebSocketState,
+} from "@/core/websocket/types";
+import { StatusOverlay } from "../status";
+
+function renderOverlay(
+  connection: ConnectionStatus,
+  onReconnect?: () => void,
+): ReturnType<typeof render> {
+  const store = createStore();
+  store.set(viewStateAtom, { mode: "edit", cellAnchor: null });
+  const wrapper: React.FC<React.PropsWithChildren> = ({ children }) => (
+    <JotaiProvider store={store}>
+      <TooltipProvider>{children}</TooltipProvider>
+    </JotaiProvider>
+  );
+  return render(
+    <StatusOverlay
+      connection={connection}
+      isRunning={false}
+      onReconnect={onReconnect}
+    />,
+    { wrapper },
+  );
+}
+
+describe("StatusOverlay disconnect indicator", () => {
+  it("invokes onReconnect when the disconnect icon is clicked", () => {
+    const onReconnect = vi.fn();
+    const { getByTestId } = renderOverlay(
+      {
+        state: WebSocketState.CLOSED,
+        code: WebSocketClosedReason.KERNEL_DISCONNECTED,
+        reason: "kernel not found",
+      },
+      onReconnect,
+    );
+
+    const icon = getByTestId("disconnected-indicator") as HTMLButtonElement;
+    expect(icon.tagName).toBe("BUTTON");
+    expect(icon.disabled).toBe(false);
+    expect(icon.getAttribute("aria-label")).toBe("Reconnect to app");
+    fireEvent.click(icon);
+    expect(onReconnect).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders a disabled button when no onReconnect is provided", () => {
+    const { getByTestId } = renderOverlay({
+      state: WebSocketState.CLOSED,
+      code: WebSocketClosedReason.KERNEL_DISCONNECTED,
+      reason: "kernel not found",
+    });
+
+    const button = getByTestId("disconnected-indicator");
+    expect((button as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it.each([
+    [
+      WebSocketClosedReason.MALFORMED_QUERY,
+      "the kernel did not recognize a request; please file a bug with marimo",
+    ],
+    [
+      WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+      "Failed to start kernel sandbox",
+    ],
+  ])(
+    "renders a disabled button for non-recoverable close reason %s",
+    (code, reason) => {
+      const onReconnect = vi.fn();
+      const { getByTestId } = renderOverlay(
+        { state: WebSocketState.CLOSED, code, reason },
+        onReconnect,
+      );
+
+      const button = getByTestId("disconnected-indicator") as HTMLButtonElement;
+      expect(button.disabled).toBe(true);
+      fireEvent.click(button);
+      expect(onReconnect).not.toHaveBeenCalled();
+    },
+  );
+
+  it("does not render the disconnect icon when another tab has taken over", () => {
+    const onReconnect = vi.fn();
+    const { queryByTestId } = renderOverlay(
+      {
+        state: WebSocketState.CLOSED,
+        code: WebSocketClosedReason.ALREADY_RUNNING,
+        reason: "another browser tab is already connected to the kernel",
+        canTakeover: true,
+      },
+      onReconnect,
+    );
+
+    expect(queryByTestId("disconnected-indicator")).toBeNull();
+  });
+});

frontend/src/components/editor/header/status.tsx

@@ -7,16 +7,26 @@ import { Tooltip } from "@/components/ui/tooltip";
 import { notebookScrollToRunning } from "@/core/cells/actions";
 import { onlyScratchpadIsRunningAtom } from "@/core/cells/cells";
 import { viewStateAtom } from "@/core/mode";
-import { type ConnectionStatus, WebSocketState } from "@/core/websocket/types";
+import {
+  type ConnectionStatus,
+  WebSocketClosedReason,
+  WebSocketState,
+} from "@/core/websocket/types";
 import { cn } from "@/utils/cn";
 
 export const StatusOverlay: React.FC<{
   connection: ConnectionStatus;
   isRunning: boolean;
-}> = ({ connection, isRunning }) => {
+  onReconnect?: () => void;
+}> = ({ connection, isRunning, onReconnect }) => {
   const { mode } = useAtomValue(viewStateAtom);
   const isClosed = connection.state === WebSocketState.CLOSED;
   const isOpen = connection.state === WebSocketState.OPEN;
+  // Only KERNEL_DISCONNECTED is recoverable by a retry. Other terminal
+  // reasons (MALFORMED_QUERY, KERNEL_STARTUP_ERROR) would deterministically
+  // fail the same way; ALREADY_RUNNING is handled by `LockedIcon` below.
+  const canReconnect =
+    isClosed && connection.code === WebSocketClosedReason.KERNEL_DISCONNECTED;
 
   return (
     <>
@@ -28,7 +38,11 @@ export const StatusOverlay: React.FC<{
         )}
       >
         {isOpen && isRunning && <RunningIcon />}
-        {isClosed && !connection.canTakeover && <DisconnectedIcon />}
+        {isClosed && !connection.canTakeover && (
+          <DisconnectedIcon
+            onReconnect={canReconnect ? onReconnect : undefined}
+          />
+        )}
         {isClosed && connection.canTakeover && <LockedIcon />}
       </div>
     </>
@@ -37,13 +51,33 @@ export const StatusOverlay: React.FC<{
 
 const topLeftStatus = "print:hidden pointer-events-auto hover:cursor-pointer";
 
-const DisconnectedIcon = () => (
-  <Tooltip content="App disconnected">
-    <div className={topLeftStatus}>
-      <UnlinkIcon className="w-[25px] h-[25px] text-(--red-11)" />
-    </div>
-  </Tooltip>
-);
+const DisconnectedIcon: React.FC<{ onReconnect?: () => void }> = ({
+  onReconnect,
+}) => {
+  const disabled = !onReconnect;
+  return (
+    <Tooltip
+      content={
+        disabled ? "App disconnected" : "App disconnected — click to reconnect"
+      }
+    >
+      {/* Wrapper span keeps the tooltip reachable when the button is
+          disabled — a disabled <button> swallows pointer events. */}
+      <span tabIndex={disabled ? 0 : -1}>
+        <button
+          type="button"
+          className={cn(topLeftStatus, "bg-transparent border-0 p-0")}
+          aria-label={disabled ? "App disconnected" : "Reconnect to app"}
+          data-testid="disconnected-indicator"
+          onClick={onReconnect}
+          disabled={disabled}
+        >
+          <UnlinkIcon className="w-[25px] h-[25px] text-(--red-11)" />
+        </button>
+      </span>
+    </Tooltip>
+  );
+};
 
 const LockedIcon = () => (
   <Tooltip content="Notebook locked">

frontend/src/core/edit-app.tsx

@@ -79,7 +79,7 @@ export const EditApp: React.FC<AppProps> = ({
     };
   }, []);
 
-  const { connection } = useMarimoKernelConnection({
+  const { connection, reconnect } = useMarimoKernelConnection({
     autoInstantiate: userConfig.runtime.auto_instantiate,
     setCells: (cells, layout) => {
       setCells(cells);
@@ -147,6 +147,7 @@ export const EditApp: React.FC<AppProps> = ({
         connection={connection}
         isRunning={isRunning}
         width={appConfig.width}
+        onReconnect={reconnect}
       >
         <AppHeader
           connection={connection}

frontend/src/core/run-app.tsx

@@ -38,7 +38,7 @@ export const RunApp: React.FC<AppProps> = ({ appConfig }) => {
     };
   }, []);
 
-  const { connection } = useMarimoKernelConnection({
+  const { connection, reconnect } = useMarimoKernelConnection({
     autoInstantiate: true,
     setCells: setCells,
     sessionId: getSessionId(),
@@ -84,6 +84,7 @@ export const RunApp: React.FC<AppProps> = ({ appConfig }) => {
       connection={connection}
       isRunning={isRunning}
       width={appConfig.width}
+      onReconnect={reconnect}
     >
       <AppHeader connection={connection} className="sm:pt-8">
         {galleryHref && (