fix(webapp): keep the agent wake poll to one chain per tab

Author: kathiekiwi

apps/webapp/app/components/dashboard-agent/DashboardAgent.tsx

@@ -19,20 +19,19 @@ import {
   readAgentFullscreen,
   writeAgentFullscreen,
 } from "./panel-layout";
+import { startWakePolling } from "./wake-poll";
 import {
   showWatchWakesSummaryToast,
   showWatchWakeToast,
   WAKE_TOAST_MAX_INDIVIDUAL,
   type WatchWake,
 } from "./WatchWakeToast";
 
-const UNREAD_POLL_INTERVAL_MS = 60_000;
-
-// Added to each delay so open tabs never settle into polling on the same second.
-const UNREAD_POLL_JITTER_MS = 15_000;
-
 const TOASTED_WAKES_STORAGE_KEY = "tdev:dashboard-agent:toasted-wakes";
 
+// Shorter than the poll interval, so a stuck request is dropped before the next tick.
+const UNREAD_REQUEST_TIMEOUT_MS = 30_000;
+
 /** `hasAccess` is a UI gate only; the resource routes enforce the same check server-side. */
 export function DashboardAgent({
   children,
@@ -143,7 +142,10 @@ export function DashboardAgent({
     let cancelled = false;
     const load = async () => {
       try {
-        const res = await fetch(`${actionPath}?unread=1`);
+        // Bounded, so one stuck request can't hold the poll's in-flight guard.
+        const res = await fetch(`${actionPath}?unread=1`, {
+          signal: AbortSignal.timeout(UNREAD_REQUEST_TIMEOUT_MS),
+        });
         if (!res.ok) return;
         const data = (await res.json()) as { unreadWakes?: number; wakes?: WatchWake[] };
         if (cancelled) return;
@@ -168,31 +170,18 @@ export function DashboardAgent({
       }
     };
 
-    let timer: number | undefined;
-    function schedule() {
-      timer = window.setTimeout(
-        tick,
-        UNREAD_POLL_INTERVAL_MS + Math.random() * UNREAD_POLL_JITTER_MS
-      );
-    }
-    async function tick() {
-      // A hidden tab asks nothing; `onVisible` catches it up.
-      if (!document.hidden) await load();
-      if (!cancelled) schedule();
-    }
-    const onVisible = () => {
-      if (document.hidden || cancelled) return;
-      window.clearTimeout(timer);
-      void tick();
-    };
+    const stop = startWakePolling({
+      load,
+      isHidden: () => document.hidden,
+      onVisibilityChange: (listener) => {
+        document.addEventListener("visibilitychange", listener);
+        return () => document.removeEventListener("visibilitychange", listener);
+      },
+    });
 
-    void load();
-    schedule();
-    document.addEventListener("visibilitychange", onVisible);
     return () => {
       cancelled = true;
-      window.clearTimeout(timer);
-      document.removeEventListener("visibilitychange", onVisible);
+      stop();
     };
   }, [hasAccess, actionPath, setPanelOpen, openChat]);
 

apps/webapp/app/components/dashboard-agent/wake-poll.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { startWakePolling, UNREAD_POLL_INTERVAL_MS } from "./wake-poll";
+
+function harness() {
+  let hidden = false;
+  const listeners = new Set<() => void>();
+  const loads: number[] = [];
+
+  const stop = startWakePolling({
+    load: async () => {
+      loads.push(Date.now());
+    },
+    isHidden: () => hidden,
+    onVisibilityChange: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    // No jitter, so every delay is exactly one interval.
+    random: () => 0,
+    setTimer: (callback, ms) => setTimeout(callback, ms) as unknown as number,
+    clearTimer: (handle) => clearTimeout(handle as unknown as NodeJS.Timeout),
+  });
+
+  return {
+    loads,
+    stop,
+    setHidden(next: boolean) {
+      hidden = next;
+      for (const listener of listeners) listener();
+    },
+    listenerCount: () => listeners.size,
+  };
+}
+
+describe("startWakePolling", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("polls once immediately and then once per interval", async () => {
+    const poll = harness();
+
+    expect(poll.loads).toHaveLength(1);
+    await vi.advanceTimersByTimeAsync(UNREAD_POLL_INTERVAL_MS * 3);
+    expect(poll.loads).toHaveLength(4);
+
+    poll.stop();
+  });
+
+  it("asks nothing while hidden and catches up once when visible again", async () => {
+    const poll = harness();
+    poll.setHidden(true);
+
+    await vi.advanceTimersByTimeAsync(UNREAD_POLL_INTERVAL_MS * 3);
+    expect(poll.loads).toHaveLength(1);
+
+    poll.setHidden(false);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(poll.loads).toHaveLength(2);
+
+    poll.stop();
+  });
+
+  it("keeps exactly one chain across ten rapid hide/show cycles", async () => {
+    const poll = harness();
+
+    for (let cycle = 0; cycle < 10; cycle++) {
+      poll.setHidden(true);
+      await vi.advanceTimersByTimeAsync(10);
+      poll.setHidden(false);
+      await vi.advanceTimersByTimeAsync(10);
+    }
+
+    const afterCycles = poll.loads.length;
+    await vi.advanceTimersByTimeAsync(UNREAD_POLL_INTERVAL_MS * 10);
+
+    // One poll per interval, not ten: the resumes replaced the chain instead of
+    // forking it.
+    expect(poll.loads.length - afterCycles).toBe(10);
+
+    poll.stop();
+  });
+
+  it("stops every timer and listener on unmount", async () => {
+    const poll = harness();
+    poll.setHidden(true);
+    poll.setHidden(false);
+
+    poll.stop();
+    const settled = poll.loads.length;
+
+    await vi.advanceTimersByTimeAsync(UNREAD_POLL_INTERVAL_MS * 10);
+    expect(poll.loads).toHaveLength(settled);
+    expect(poll.listenerCount()).toBe(0);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

apps/webapp/app/components/dashboard-agent/wake-poll.ts

@@ -0,0 +1,68 @@
+/**
+ * The wake feed's poll: one self-scheduling chain per mount. A hidden tab asks nothing, a
+ * resume catches up once, and neither can fork the chain into a second one.
+ */
+
+export const UNREAD_POLL_INTERVAL_MS = 60_000;
+
+// Added to each delay so open tabs never settle into polling on the same second.
+export const UNREAD_POLL_JITTER_MS = 15_000;
+
+export type WakePollOptions = {
+  load: () => Promise<void>;
+  isHidden: () => boolean;
+  /** Subscribe to visibility changes; returns its own unsubscribe. */
+  onVisibilityChange: (listener: () => void) => () => void;
+  /** Seams so a test can drive the chain without real timers. */
+  random?: () => number;
+  setTimer?: (callback: () => void, delayMs: number) => number;
+  clearTimer?: (handle: number) => void;
+};
+
+/** Start polling. The returned function stops the chain for good. */
+export function startWakePolling(options: WakePollOptions): () => void {
+  const random = options.random ?? Math.random;
+  const setTimer = options.setTimer ?? ((callback, ms) => window.setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => window.clearTimeout(handle));
+
+  let stopped = false;
+  let timer: number | undefined;
+  let loading = false;
+  // Each tick carries the chain it belongs to, so an orphaned callback returns
+  // instead of scheduling itself again.
+  let chain = 0;
+
+  const tick = (generation: number) => {
+    if (stopped || generation !== chain) return;
+
+    // Scheduled before the load, so a slow response can't stall the chain.
+    timer = setTimer(
+      () => tick(generation),
+      UNREAD_POLL_INTERVAL_MS + random() * UNREAD_POLL_JITTER_MS
+    );
+
+    if (loading || options.isHidden()) return;
+    loading = true;
+    const done = () => {
+      loading = false;
+    };
+    options.load().then(done, done);
+  };
+
+  const unsubscribe = options.onVisibilityChange(() => {
+    if (stopped || options.isHidden()) return;
+    // One catch-up fetch on a new chain, replacing the pending timer rather than
+    // adding a second chain.
+    if (timer !== undefined) clearTimer(timer);
+    chain += 1;
+    tick(chain);
+  });
+
+  tick(chain);
+
+  return () => {
+    stopped = true;
+    if (timer !== undefined) clearTimer(timer);
+    unsubscribe();
+  };
+}