fix(tui): replace 500ms sidebar poll with persistent WebSocket (#200)

The TUI sidebar polled the server plugin every 500ms over localhost HTTP.
The TUI runner and server runner are separate Bun contexts in the same
process, so each poll opened a fresh loopback TCP connection (Bun's fetch
isn't pooled to our server) — ~10ms of client work twice a second, idle,
forever. That was the entire source of idle TUI CPU: a few percent on fast
machines, ~20% on slower ones, additive per sidebar plugin.

Replace the poll with a single persistent WebSocket. The RPC server moves
from node:http to Bun.serve, keeping all HTTP request/reply routes unchanged
and adding a /ws endpoint; the server pushes each queued notification over
it the instant it's queued. isTuiConnected is now exact socket liveness
instead of a 3s poll-drain window, so server-initiated dialogs route to the
TUI reliably. Bearer-token auth in the hello, per-session scoped delivery,
backlog replay on (re)connect, auto-reconnect with port rediscovery. The
client keeps a property-read-only session watcher (no network at idle) to
re-scope the socket on session switch.

Deletes the dead poll path (pending-notifications handler, consumeTuiMessages).
Pi is unaffected (it does not import the RPC server/client).

Author: ualtinok

.alfonso/release-notes/v0.30.2.md

@@ -0,0 +1,9 @@
+# v0.30.2
+
+A patch release fixing high idle CPU from the TUI sidebar.
+
+## Fixes
+
+- **High idle CPU from the TUI sidebar (#200).** The sidebar polled the plugin every 500ms over a localhost connection. Because the TUI and the plugin run in separate runtimes inside the same process, each poll opened a brand-new loopback connection, so an idle session kept burning CPU continuously (a few percent on fast machines, noticeably more on slower ones, and additive when other sidebar plugins were also installed). The sidebar now holds a single persistent WebSocket to the plugin and receives updates the instant they happen, instead of polling. Idle CPU drops back to baseline. Thanks to @null-axiom for the report and the cross-plugin cross-check that pointed at the shared mechanism.
+
+  As part of this, the plugin's detection of whether a TUI is connected is now based on the live connection itself rather than a recent-poll timeout, so server-initiated dialogs (`/ctx-status`, `/ctx-recomp`, the upgrade prompt) route to the TUI reliably instead of depending on timing.

packages/plugin/src/plugin/rpc-handlers.ts

@@ -44,7 +44,6 @@ import {
     shouldShowAnnouncement,
 } from "../shared/announcement";
 import { log } from "../shared/logger";
-import { drainNotifications } from "../shared/rpc-notifications";
 import type { MagicContextRpcServer } from "../shared/rpc-server";
 import type { EmbedDetail, SidebarSnapshot, StatusDetail } from "../shared/rpc-types";
 import { applyStickySnapshotCache } from "./sidebar-snapshot-cache";
@@ -914,23 +913,10 @@ export function registerRpcHandlers(
         return { toastDurationMs: resolved };
     });
 
-    rpcServer.handle("pending-notifications", async (params) => {
-        const lastReceivedId = Number(params.lastReceivedId ?? 0);
-        // Scope drain to the TUI's active session so a notification tagged for a
-        // different session (e.g. an upgrade dialog triggered by another client
-        // sharing this process) is never delivered here. sessionId is optional
-        // for back-compat: an older TUI that omits it falls back to the previous
-        // unscoped behavior.
-        const sessionId =
-            typeof params.sessionId === "string" && params.sessionId.length > 0
-                ? params.sessionId
-                : undefined;
-        const notifications = drainNotifications(
-            Number.isFinite(lastReceivedId) ? lastReceivedId : 0,
-            sessionId,
-        );
-        return { messages: notifications } as unknown as Record<string, unknown>;
-    });
+    // Server→TUI notification delivery is no longer an HTTP poll. The TUI holds a
+    // persistent WebSocket (rpc-server `/ws`); the server pushes each queued
+    // notification over it and replays the unacked backlog on the hello. See
+    // rpc-server.ts + rpc-notifications.ts.
 
     // Startup announcement — called by the TUI plugin once per session to decide
     // whether to show the "What's new" dialog. We deliberately read state via

packages/plugin/src/shared/announcement.ts

@@ -24,14 +24,14 @@ import { getMagicContextStorageDir } from "./data-path";
  * Bump only when there are user-visible changes worth a startup dialog.
  * Does NOT need to match the published package version.
  */
-export const ANNOUNCEMENT_VERSION = "0.30.1";
+export const ANNOUNCEMENT_VERSION = "0.30.2";
 
 /**
  * Short, user-facing bullet strings. Keep each line ~80 chars or shorter so the
  * TUI dialog renders cleanly without horizontal scroll on a typical terminal.
  */
 export const ANNOUNCEMENT_FEATURES: ReadonlyArray<string> = [
-    "Local embeddings work on OpenCode Desktop again (#195): /ctx-embed no longer fails with 'Unsupported device: cpu' on the Desktop app.",
+    "Fixed high idle CPU from the TUI sidebar (#200): it now uses a single persistent connection to the plugin instead of polling, so an idle session no longer burns CPU.",
 ];
 
 /**

packages/plugin/src/shared/rpc-client.ts

@@ -97,6 +97,20 @@ export class MagicContextRpcClient {
         }
     }
 
+    /** Resolve the live server's port + bearer token (for opening the WS push
+     *  channel). Reuses the same health-checked port-file discovery as `call`,
+     *  so the WS client and the HTTP client always agree on which server instance
+     *  (and token) to use. Returns null when no live server is found. */
+    async resolveEndpoint(): Promise<{ port: number; token: string | null } | null> {
+        try {
+            const port = await this.resolvePort();
+            if (port === null) return null;
+            return { port, token: this.token };
+        } catch {
+            return null;
+        }
+    }
+
     private async resolvePort(): Promise<number | null> {
         if (this.port && this.healthChecked) {
             return this.port;

packages/plugin/src/shared/rpc-notifications.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { drainNotifications, isTuiConnected, pushNotification } from "./rpc-notifications";
+import {
+    drainNotifications,
+    isTuiConnected,
+    type NotificationSink,
+    pushNotification,
+    registerNotificationSink,
+} from "./rpc-notifications";
 
 describe("rpc notifications", () => {
     test("keeps messages queued until the client acks their id", () => {
@@ -45,17 +51,68 @@ describe("rpc notifications", () => {
         expect(poll.map((m) => m.type).sort()).toEqual(["x", "y"]);
     });
 
-    test("isTuiConnected is per-session: a TUI on session A does not mark session B connected", () => {
-        // A TUI draining for tuiA must not make tuiB's producers think a TUI is
-        // polling for tuiB (which would route tuiB's /ctx-status, upgrade
-        // reminder, etc. to the dialog path and lose them in the unrelated TUI).
-        // Use ids no other test drains so the per-session window is unambiguous.
-        drainNotifications(0, "ses_tuiA_only");
-        expect(isTuiConnected("ses_tuiA_only")).toBe(true);
-        expect(isTuiConnected("ses_tuiB_never_drained")).toBe(false);
-        // The session-less (global) query still reports recent activity for the
-        // legacy callers that have no session context.
+    test("isTuiConnected reflects live WS sinks per-session", () => {
+        // No sinks → nothing connected.
+        expect(isTuiConnected("ses_anything")).toBe(false);
+        expect(isTuiConnected()).toBe(false);
+
+        // A live sink scoped to session A marks ONLY A connected (so B's producers
+        // don't misroute B's /ctx-status / upgrade reminder to the dialog path and
+        // lose it in an unrelated TUI), and the global query is also "connected".
+        const unregister = registerNotificationSink({ sessionId: "ses_A", send: () => {} });
+        expect(isTuiConnected("ses_A")).toBe(true);
+        expect(isTuiConnected("ses_B")).toBe(false);
         expect(isTuiConnected()).toBe(true);
+
+        // Closing the socket removes the sink → disconnected again.
+        unregister();
+        expect(isTuiConnected("ses_A")).toBe(false);
+        expect(isTuiConnected()).toBe(false);
+    });
+
+    test("a session-less sink counts as connected for any session query", () => {
+        const unregister = registerNotificationSink({ sessionId: undefined, send: () => {} });
+        expect(isTuiConnected("ses_whatever")).toBe(true);
+        expect(isTuiConnected()).toBe(true);
+        unregister();
+    });
+
+    test("pushNotification fans out live to a matching sink and skips a foreign session", () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        const received: string[] = [];
+        const sink: NotificationSink = {
+            sessionId: "ses_live",
+            send: (n) => received.push(n.type),
+        };
+        const unregister = registerNotificationSink(sink);
+
+        pushNotification("for-live", { action: "show-status-dialog" }, "ses_live");
+        pushNotification("for-other", { action: "show-status-dialog" }, "ses_other");
+        pushNotification("global", { action: "show-status-dialog" });
+
+        // The sink sees its own session + global, never the foreign session.
+        expect(received.sort()).toEqual(["for-live", "global"]);
+        unregister();
+    });
+
+    test("a dead sink (throwing send) does not block delivery to other sinks", () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        const live: string[] = [];
+        const unregDead = registerNotificationSink({
+            sessionId: undefined,
+            send: () => {
+                throw new Error("socket dead");
+            },
+        });
+        const unregLive = registerNotificationSink({
+            sessionId: undefined,
+            send: (n) => live.push(n.type),
+        });
+        // Must not throw, and the live sink still receives it.
+        expect(() => pushNotification("resilient", { ok: true })).not.toThrow();
+        expect(live).toEqual(["resilient"]);
+        unregDead();
+        unregLive();
     });
 
     test("queue-cap eviction is session-fair: a noisy session cannot evict another session's newest unseen item", () => {

packages/plugin/src/shared/rpc-notifications.ts

@@ -16,31 +16,73 @@ export interface RpcNotification {
 
 let queue: RpcNotification[] = [];
 let nextNotificationId = 1;
-// Timestamp of last drain — used to detect if a TUI is actively polling.
-// The TUI polls every 500ms; we consider it connected if it polled within
-// the last 3 seconds (6× the poll interval, tolerates transient delays).
-//
-// PER-SESSION: a single server process can serve MANY sessions (e.g. a TUI on
-// session A plus an OpenCode Desktop opened on session B for the same project,
-// whose newer RPC server this TUI's port discovery then selects). The TUI
-// poller drains with ITS active session id, so a session is "TUI-connected"
-// only if a TUI recently drained FOR THAT session. A process-global timestamp
-// would make session B's producers (`/ctx-status`, upgrade reminder) take the
-// TUI-dialog path because session A's TUI is polling — queuing a B-scoped
-// dialog action that A's poller correctly refuses to show, so B's notice is
-// lost (it also suppressed B's non-TUI fallback). Tracking drains per session
-// routes each producer to the right delivery path.
-const lastDrainAtBySession = new Map<string, number>();
-let lastDrainAtAny = 0;
-const TUI_CONNECTED_WINDOW_MS = 3_000;
 
-/** Push a notification for TUI to pick up via polling. */
+/**
+ * A connected TUI notification sink — one per authenticated WebSocket. The RPC
+ * server registers a sink when a TUI socket authenticates (hello) and removes
+ * it on close. `send` is sink-agnostic (the server owns the actual WS socket)
+ * so this module stays free of Bun/WS types.
+ */
+export interface NotificationSink {
+    /** The TUI's active session at connect time (its hello scope). */
+    sessionId?: string;
+    /** Deliver one notification over this sink's live socket. */
+    send: (notification: RpcNotification) => void;
+}
+
+// Live sinks replace the old poll-drain-timestamp inference. "TUI connected for
+// a session" is now exact socket liveness — accurate and immediate — instead of
+// "did a 500ms poll drain within the last 3s". Per-session scoping still matters:
+// one process can serve MANY sessions (a TUI on session A plus an OpenCode
+// Desktop opened on session B for the same project, whose newer RPC server this
+// TUI's port discovery then selects). Each sink carries ITS session, so a
+// B-scoped producer (`/ctx-status`, upgrade reminder) only sees B's TUI as
+// connected and routes its dialog there, never to A.
+const sinks = new Set<NotificationSink>();
+
+/** Register a live TUI sink. Returns an unregister fn (call on socket close). */
+export function registerNotificationSink(sink: NotificationSink): () => void {
+    sinks.add(sink);
+    return () => {
+        sinks.delete(sink);
+    };
+}
+
+/** Whether a given notification may be delivered to a given sink. A global
+ *  notification (no sessionId) reaches every sink; a session-scoped one reaches
+ *  only sinks for that session (or session-less sinks). Mirrors the drain filter
+ *  from the sink's perspective. */
+function notificationMatchesSink(notification: RpcNotification, sink: NotificationSink): boolean {
+    return (
+        notification.sessionId === undefined ||
+        sink.sessionId === undefined ||
+        notification.sessionId === sink.sessionId
+    );
+}
+
+/** Push a notification to the TUI. Fans out to any live WS sink immediately and
+ *  also enqueues it so a TUI that is momentarily disconnected (reconnecting, or
+ *  not yet connected) still receives it on its next hello via the backlog drain.
+ *  At-least-once: a live push that the socket drops is re-delivered from the
+ *  queue on reconnect (pruned only when the client acks via `lastReceivedId`). */
 export function pushNotification(
     type: string,
     payload: Record<string, unknown>,
     sessionId?: string,
 ): void {
-    queue.push({ id: nextNotificationId++, type, payload, sessionId });
+    const notification: RpcNotification = { id: nextNotificationId++, type, payload, sessionId };
+    queue.push(notification);
+    // Fan out to every live sink this notification is scoped to. A delivery throw
+    // (dead socket mid-send) must not block other sinks or the caller.
+    for (const sink of sinks) {
+        if (!notificationMatchesSink(notification, sink)) continue;
+        try {
+            sink.send(notification);
+        } catch {
+            // Socket died between liveness check and send; the close handler will
+            // unregister it, and the queue backlog re-delivers on reconnect.
+        }
+    }
     // Cap queue size to prevent unbounded growth if a TUI is not draining.
     // Session-FAIR eviction: a naive `slice(-50)` drops the globally-oldest
     // items, so a noisy session could evict ANOTHER session's single unseen
@@ -66,13 +108,12 @@ export function pushNotification(
 }
 
 /** Return pending notifications after acking the client's last received id.
- *  Updates lastDrainAt so isTuiConnected() reflects recent activity.
  *
  *  Session scoping: when `sessionId` is provided, only notifications tagged for
  *  that session (or session-less/global ones) are returned and pruned — a
  *  notification tagged for a DIFFERENT session is never handed to this client
  *  and is never pruned by this client's ack. This matters because the in-memory
- *  queue is per-process but a TUI can end up draining a process that also serves
+ *  queue is per-process but a TUI can end up bound to a process that also serves
  *  OTHER sessions: e.g. opening OpenCode Desktop on the same project starts a
  *  newer RPC server that the TUI's port discovery (newest-pid-wins) then selects,
  *  so a Desktop-session upgrade-dialog action would otherwise surface in an
@@ -82,11 +123,9 @@ export function pushNotification(
  *
  *  Delivery is at-least-once (non-destructive return + prune-on-ack): a returned
  *  notification stays queued until a later call acks it via a higher
- *  `lastReceivedId`, so a lost poll response re-delivers on the next poll. */
+ *  `lastReceivedId`, so a dropped WS socket re-delivers the backlog on reconnect
+ *  (the client sends its `lastReceivedId` in the hello). */
 export function drainNotifications(lastReceivedId = 0, sessionId?: string): RpcNotification[] {
-    const now = Date.now();
-    lastDrainAtAny = now;
-    if (sessionId !== undefined) lastDrainAtBySession.set(sessionId, now);
     const matchesClient = (notification: RpcNotification): boolean =>
         sessionId === undefined ||
         notification.sessionId === undefined ||
@@ -103,20 +142,20 @@ export function drainNotifications(lastReceivedId = 0, sessionId?: string): RpcN
     );
 }
 
-/** Whether a TUI client is actively polling for notifications.
- *  Returns true only if a TUI has drained within the last 3 seconds.
+/** Whether a TUI client is connected via a live notification socket.
+ *  Now exact socket liveness (a registered WS sink), not a poll-drain timestamp.
  *
- *  Pass `sessionId` (preferred) to ask whether a TUI is polling FOR THAT
+ *  Pass `sessionId` (preferred) to ask whether a TUI is connected FOR THAT
  *  SESSION — this is what producers (`/ctx-status`, `/ctx-recomp`, the upgrade
  *  reminder) must use to decide dialog-vs-message, so a TUI on a different
- *  session in the same process does not misroute their delivery. Omit it only
- *  for legacy/global callers that genuinely have no session context; they fall
- *  back to "any session recently drained" (the pre-per-session behavior). */
+ *  session in the same process does not misroute their delivery. A session-less
+ *  sink (legacy/global) counts for any session query. Omit `sessionId` only for
+ *  callers with no session context; they get "any sink connected". */
 export function isTuiConnected(sessionId?: string): boolean {
-    const now = Date.now();
-    if (sessionId !== undefined) {
-        const at = lastDrainAtBySession.get(sessionId) ?? 0;
-        return at > 0 && now - at < TUI_CONNECTED_WINDOW_MS;
+    if (sinks.size === 0) return false;
+    if (sessionId === undefined) return true;
+    for (const sink of sinks) {
+        if (sink.sessionId === undefined || sink.sessionId === sessionId) return true;
     }
-    return lastDrainAtAny > 0 && now - lastDrainAtAny < TUI_CONNECTED_WINDOW_MS;
+    return false;
 }