🤖 fix: add heartbeat pattern to onChat for reliable stall detection

src/browser/stores/WorkspaceStore.ts

@@ -229,10 +229,11 @@ function createInitialChatTransientState(): WorkspaceChatTransientState {
 const ON_CHAT_RETRY_BASE_MS = 250;
 const ON_CHAT_RETRY_MAX_MS = 5000;
 
-// If a stream is active but we stop receiving onChat events, the UI can get stuck.
-// This can happen with half-open WebSocket paths (e.g., some WSL localhost forwarding setups).
-const ON_CHAT_STALL_TIMEOUT_MS = 60_000;
-const ON_CHAT_STALL_CHECK_INTERVAL_MS = 5_000;
+// Stall detection: server sends heartbeats every 5s, so if we don't receive any events
+// (including heartbeats) for 10s, the connection is likely dead. This handles half-open
+// WebSocket paths (e.g., some WSL localhost forwarding setups).
+const ON_CHAT_STALL_TIMEOUT_MS = 10_000;
+const ON_CHAT_STALL_CHECK_INTERVAL_MS = 2_000;
 
 interface ValidationIssue {
   path?: Array<string | number>;
@@ -1383,20 +1384,16 @@ export class WorkspaceStore {
           { signal: attemptController.signal }
         );
 
-        // Stall watchdog: if a stream is active but we stop receiving events, abort this
-        // subscription attempt so the outer loop can resubscribe.
+        // Stall watchdog: server sends heartbeats every 5s, so if we don't receive ANY events
+        // (including heartbeats) for 10s, the connection is likely dead.
         stallInterval = setInterval(() => {
           if (attemptController.signal.aborted) return;
 
-          const aggregator = this.aggregators.get(workspaceId);
-          const hasActiveStream = aggregator?.getActiveStreamMessageId() !== undefined;
-          if (!hasActiveStream) return;
-
           const elapsedMs = Date.now() - lastChatEventAt;
           if (elapsedMs < ON_CHAT_STALL_TIMEOUT_MS) return;
 
           console.warn(
-            `[WorkspaceStore] onChat appears stalled for ${workspaceId} (no events for ${elapsedMs}ms while a stream is active); retrying...`
+            `[WorkspaceStore] onChat appears stalled for ${workspaceId} (no events for ${elapsedMs}ms); retrying...`
           );
           attemptController.abort();
         }, ON_CHAT_STALL_CHECK_INTERVAL_MS);
@@ -1807,6 +1804,11 @@ export class WorkspaceStore {
       return;
     }
 
+    // Heartbeat events are no-ops for UI state - they exist only for connection liveness detection
+    if ("type" in data && data.type === "heartbeat") {
+      return;
+    }
+
     // OPTIMIZATION: Buffer stream events until caught-up to reduce excess re-renders
     // When first subscribing to a workspace, we receive:
     // 1. Historical messages from chat.jsonl (potentially hundreds of messages)

src/common/orpc/schemas/stream.ts

@@ -14,6 +14,11 @@ import { MuxProviderOptionsSchema } from "./providerOptions";
 import { RuntimeModeSchema } from "./runtime";
 
 // Chat Events
+
+/** Heartbeat event to keep the connection alive during long operations */
+export const HeartbeatEventSchema = z.object({
+  type: z.literal("heartbeat"),
+});
 export const CaughtUpMessageSchema = z.object({
   type: z.literal("caught-up"),
 });
@@ -371,6 +376,7 @@ export const RestoreToInputEventSchema = z.object({
 // when loading from history or sending new messages.
 export const WorkspaceChatMessageSchema = z.discriminatedUnion("type", [
   // Stream lifecycle events
+  HeartbeatEventSchema,
   CaughtUpMessageSchema,
   StreamErrorMessageSchema,
   DeleteMessageSchema,

src/node/orpc/router.ts

@@ -1344,9 +1344,17 @@ export const router = (authToken?: string) => {
             push(message);
           });
 
+          // 3. Heartbeat to keep the connection alive during long operations (tool calls, subagents).
+          // Client uses this to detect stalled connections vs. intentionally idle streams.
+          const HEARTBEAT_INTERVAL_MS = 5_000;
+          const heartbeatInterval = setInterval(() => {
+            push({ type: "heartbeat" });
+          }, HEARTBEAT_INTERVAL_MS);
+
           try {
             yield* iterate();
           } finally {
+            clearInterval(heartbeatInterval);
             end();
             unsubscribe();
           }