feat(poll): skips background polls when notifications gate is disabled

Author: wgordon17

README.md

@@ -18,7 +18,7 @@ Dashboard SPA tracking GitHub issues, PRs, and GHA workflow runs across multiple
 - **Ignore System** — Hide specific items with an "N ignored" badge and unignore popover.
 - **Dark Mode** — System-aware with flash prevention via inline script + CSP SHA-256 hash.
 - **ETag Caching** — Conditional requests (304s are free against GitHub's rate limit).
-- **Auto-refresh** — Background polling keeps data fresh even in hidden tabs; hot poll pauses to save API budget.
+- **Auto-refresh** — Background polling keeps data fresh even in hidden tabs (requires notifications scope for efficient 304 change detection); hot poll pauses to save API budget.
 
 ## Tech Stack
 

src/app/services/poll.ts

@@ -71,6 +71,12 @@ export function clearHotSets(): void {
   _hotRuns.clear();
 }
 
+/** Simulate 403 on /notifications — disables the notifications gate.
+ * Used by tests to exercise the conditional background-poll guard. */
+export function disableNotifGate(): void {
+  _notifGateDisabled = true;
+}
+
 export function resetPollState(): void {
   _notifLastModified = null;
   _lastSuccessfulFetch = null;
@@ -178,8 +184,8 @@ async function hasNotificationChanges(): Promise<boolean> {
     ) {
       console.warn("[poll] Notifications API returned 403 — disabling gate");
       pushNotification("notifications", config.authMethod === "pat"
-        ? "Notifications API returned 403 — fine-grained tokens do not support notifications; classic tokens need the notifications scope"
-        : "Notifications API returned 403 — check that the notifications scope is granted", "warning");
+        ? "Notifications API returned 403 — fine-grained tokens do not support notifications; classic tokens need the notifications scope. Background refresh in hidden tabs is disabled."
+        : "Notifications API returned 403 — check that the notifications scope is granted. Background refresh in hidden tabs is disabled.", "warning");
       _notifGateDisabled = true;
     }
     return true;
@@ -323,7 +329,10 @@ function withJitter(intervalMs: number): number {
  * - Triggers an immediate fetch on init
  * - Polls at getInterval() seconds (reactive — restarts when interval changes)
  * - If getInterval() === 0, disables auto-polling (SDR-017)
- * - Continues polling in background tabs (no visibility pause)
+ * - Continues polling in background tabs when notifications gate is available
+ *   (304 responses make background polls near-zero cost). When the gate is
+ *   disabled (fine-grained PAT or missing notifications scope), background
+ *   polling pauses to conserve API budget.
  * - On re-visible after >2 min hidden, fires catch-up fetch (safety net for
  *   browser tab throttling/freezing — Safari purge, Chrome Energy Saver)
  * - Applies ±30 second jitter to poll interval
@@ -393,6 +402,10 @@ export function createPollCoordinator(
 
     const intervalMs = withJitter(intervalSec * 1000);
     intervalId = setInterval(() => {
+      // Without the notifications gate (403 — scope not granted), every background
+      // poll is a full fetch with no 304 shortcut. Skip background polls to avoid
+      // burning API budget; the catch-up handler still fires on tab return.
+      if (document.visibilityState === "hidden" && _notifGateDisabled) return;
       void doFetch();
     }, intervalMs);
   }

tests/services/poll.test.ts

@@ -1,7 +1,7 @@
 import "fake-indexeddb/auto";
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { createRoot } from "solid-js";
-import { createPollCoordinator, type DashboardData } from "../../src/app/services/poll";
+import { createPollCoordinator, disableNotifGate, resetPollState, type DashboardData } from "../../src/app/services/poll";
 
 // Mock pushError so we can spy on it
 const mockPushError = vi.fn();
@@ -29,6 +29,7 @@ vi.mock("../../src/app/lib/errors", () => ({
 vi.mock("../../src/app/lib/notifications", () => ({
   detectNewItems: vi.fn(() => []),
   dispatchNotifications: vi.fn(),
+  _resetNotificationState: vi.fn(),
 }));
 
 // Mock config so doFetch doesn't fail when accessing config.selectedRepos
@@ -119,7 +120,7 @@ describe("createPollCoordinator", () => {
     });
   });
 
-  it("continues polling when document is hidden", async () => {
+  it("continues polling when document is hidden (notifications gate enabled)", async () => {
     const fetchAll = makeFetchAll();
 
     await createRoot(async (dispose) => {
@@ -167,6 +168,31 @@ describe("createPollCoordinator", () => {
     });
   });
 
+  it("pauses background polling when hidden and notifications gate is disabled", async () => {
+    disableNotifGate();
+    const fetchAll = makeFetchAll();
+
+    await createRoot(async (dispose) => {
+      createPollCoordinator(makeGetInterval(60), fetchAll);
+      await Promise.resolve(); // initial fetch
+
+      const callsAfterInit = fetchAll.mock.calls.length;
+
+      // Hide document
+      setDocumentVisible(false);
+
+      // Advance past the interval
+      vi.advanceTimersByTime(90_000);
+      await Promise.resolve();
+
+      // Should NOT have fetched — gate disabled means no cheap 304, skip background polls
+      expect(fetchAll.mock.calls.length).toBe(callsAfterInit);
+      dispose();
+    });
+
+    resetPollState(); // restore gate for other tests
+  });
+
   it("does NOT trigger immediate refresh on re-visible within 2 minutes", async () => {
     // Pin jitter to 0 so 300s interval is exactly 300s (no background poll in 90s)
     const randomSpy = vi.spyOn(Math, "random").mockReturnValue(0.5);