feat: rate-limit mitigation for GitHub API calls (#69)

* feat: rate-limit mitigation for GitHub API calls

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: use poll-based activity tracking instead of SSE client count

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: address PR review — cache eviction, header fallback, rename isActive

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: centdix

backend/src/notifications.ts

@@ -40,6 +40,21 @@ function broadcast(event: SseEvent): void {
   }
 }
 
+// --- Dashboard activity tracking (used to pause PR monitor) ---
+
+const ACTIVITY_TIMEOUT_MS = 15_000;
+let lastActivityAt = Date.now();
+
+/** Call on every frontend poll to mark dashboard as active. */
+export function touchActivity(): void {
+  lastActivityAt = Date.now();
+}
+
+/** Returns true if a dashboard client has polled recently. */
+export function hasDashboardActivity(): boolean {
+  return Date.now() - lastActivityAt < ACTIVITY_TIMEOUT_MS;
+}
+
 // --- Public API ---
 
 export function addNotification(

backend/src/pr.ts

@@ -62,6 +62,7 @@ interface GhPrEntry {
   number: number;
   headRefName: string;
   state: string;
+  updatedAt: string;
   statusCheckRollup: GhCheckEntry[] | null;
   url: string;
   comments: GhComment[];
@@ -81,6 +82,7 @@ export interface PrEntry {
   number: number;
   state: "open" | "closed" | "merged";
   url: string;
+  updatedAt: string;
   ciStatus: "none" | "pending" | "success" | "failed";
   ciChecks: CiCheck[];
   comments: PrComment[];
@@ -90,6 +92,17 @@ type FetchPrsResult =
   | { ok: true; data: Map<string, PrEntry> }
   | { ok: false; error: string };
 
+// ── Caches for rate-limit mitigation ─────────────────────────────────────────
+
+/** Last-seen updatedAt per PR URL — used to skip unchanged PRs' review comments. */
+const prUpdatedAtCache = new Map<string, string>();
+
+/** Cached review comments per PR URL — reused when updatedAt hasn't changed. */
+const prCommentsCache = new Map<string, PrComment[]>();
+
+/** ETag cache for gh api review comment responses. Keyed by API path. */
+const etagCache = new Map<string, { etag: string; comments: PrComment[] }>();
+
 // ── Pure helper functions (exported for unit testing) ─────────────────────────
 
 /** Summarize CI check status from a statusCheckRollup array. */
@@ -167,6 +180,7 @@ export function parsePrResponse(
       number: entry.number,
       state: entry.state.toLowerCase() as PrEntry["state"],
       url: entry.url,
+      updatedAt: entry.updatedAt ?? "",
       ciStatus: summarizeChecks(entry.statusCheckRollup),
       ciChecks: mapChecks(entry.statusCheckRollup),
       comments: (entry.comments ?? []).map((c) => ({
@@ -200,7 +214,7 @@ export async function fetchAllPrs(
     "--state",
     "open",
     "--json",
-    "number,headRefName,state,statusCheckRollup,url,comments",
+    "number,headRefName,state,updatedAt,statusCheckRollup,url,comments",
     "--limit",
     String(PR_FETCH_LIMIT),
   ];
@@ -258,7 +272,8 @@ export async function mapWithConcurrency<T, R>(
   return results;
 }
 
-/** Fetch inline review comments for a single PR via `gh api`. Returns [] on error. */
+/** Fetch inline review comments for a single PR via `gh api` with ETag caching.
+ *  Conditional requests (304) don't count against GitHub's rate limit. */
 async function fetchReviewComments(
   prNumber: number,
   repoSlug?: string,
@@ -267,12 +282,18 @@ async function fetchReviewComments(
   const repoFlag = repoSlug
     ? repoSlug
     : "{owner}/{repo}";
+  const apiPath = `repos/${repoFlag}/pulls/${prNumber}/comments?per_page=100`;
   const args = [
     "gh", "api",
-    `repos/${repoFlag}/pulls/${prNumber}/comments`,
-    "--paginate",
+    apiPath,
+    "--include",
   ];
 
+  const cached = etagCache.get(apiPath);
+  if (cached) {
+    args.push("--header", `If-None-Match: ${cached.etag}`);
+  }
+
   const proc = Bun.spawn(args, {
     stdout: "pipe",
     stderr: "pipe",
@@ -285,13 +306,49 @@ async function fetchReviewComments(
   });
 
   const raceResult = await Promise.race([proc.exited, timeout]);
-  if (raceResult === "timeout" || raceResult !== 0) return [];
+  if (raceResult === "timeout") return cached?.comments ?? [];
+
+  const raw = await new Response(proc.stdout).text();
+
+  // gh api --include prefixes the body with HTTP headers separated by a blank line
+  let blankLineIdx = raw.indexOf("\r\n\r\n");
+  let separatorLen = 4;
+  if (blankLineIdx === -1) {
+    blankLineIdx = raw.indexOf("\n\n");
+    separatorLen = 2;
+  }
+  if (blankLineIdx === -1) {
+    // No headers found — may be an error or empty response
+    if (raceResult !== 0) return cached?.comments ?? [];
+    try {
+      return parseReviewComments(raw);
+    } catch {
+      return cached?.comments ?? [];
+    }
+  }
+
+  const headerBlock = raw.slice(0, blankLineIdx);
+  const body = raw.slice(blankLineIdx + separatorLen);
+
+  // Check for 304 Not Modified
+  if (headerBlock.includes("304 Not Modified")) {
+    log.debug(`[pr] etag cache hit for PR #${prNumber}`);
+    return cached?.comments ?? [];
+  }
+
+  if (raceResult !== 0) return cached?.comments ?? [];
+
+  // Parse ETag from response headers
+  const etagMatch = headerBlock.match(/^etag:\s*(.+)$/mi);
 
   try {
-    const json = await new Response(proc.stdout).text();
-    return parseReviewComments(json);
+    const comments = parseReviewComments(body);
+    if (etagMatch) {
+      etagCache.set(apiPath, { etag: etagMatch[1].trim(), comments });
+    }
+    return comments;
   } catch {
-    return [];
+    return cached?.comments ?? [];
   }
 }
 
@@ -350,6 +407,7 @@ export async function syncPrStatus(
   linkedRepos: LinkedRepoConfig[],
   projectDir?: string,
 ): Promise<void> {
+  log.debug(`[pr] starting sync (${1 + linkedRepos.length} repo(s))`);
   // Fetch current repo + all linked repos in parallel.
   const allRepoResults = await Promise.all([
     fetchAllPrs(undefined, undefined, projectDir),
@@ -370,12 +428,20 @@ export async function syncPrStatus(
     }
   }
 
-  // Fetch inline review comments for all open PRs (concurrency-limited)
-  // and merge into comments array, sorted by date.
+  // Fetch inline review comments for open PRs whose updatedAt has changed.
+  // PRs that haven't been updated reuse cached comments (saves API calls).
   const reviewTuples: { entry: PrEntry; repoSlug: string | undefined }[] = [];
   for (const entries of branchPrs.values()) {
     for (const entry of entries) {
-      if (entry.state === "open") {
+      if (entry.state !== "open") continue;
+      const cachedUpdatedAt = prUpdatedAtCache.get(entry.url);
+      if (cachedUpdatedAt === entry.updatedAt && prCommentsCache.has(entry.url)) {
+        log.debug(`[pr] skipping comments for PR #${entry.number} (unchanged)`);
+        const cached = prCommentsCache.get(entry.url)!;
+        entry.comments = [...entry.comments, ...cached].sort(
+          (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
+        );
+      } else {
         const repoSlug = entry.repo
           ? linkedRepos.find((lr) => lr.alias === entry.repo)?.repo
           : undefined;
@@ -384,12 +450,16 @@ export async function syncPrStatus(
     }
   }
   if (reviewTuples.length > 0) {
+    log.debug(`[pr] fetching review comments for ${reviewTuples.length} PR(s)`);
     const reviewResults = await mapWithConcurrency(reviewTuples, 5, (t) =>
       fetchReviewComments(t.entry.number, t.repoSlug, projectDir),
     );
     for (let i = 0; i < reviewTuples.length; i++) {
       const entry = reviewTuples[i].entry;
-      entry.comments = [...entry.comments, ...reviewResults[i]].sort(
+      const reviewComments = reviewResults[i];
+      prUpdatedAtCache.set(entry.url, entry.updatedAt);
+      prCommentsCache.set(entry.url, reviewComments);
+      entry.comments = [...entry.comments, ...reviewComments].sort(
         (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime(),
       );
     }
@@ -421,16 +491,44 @@ export async function syncPrStatus(
     staleRefreshes.push(refreshStalePrData(wtDir));
   }
   await Promise.all(staleRefreshes);
+
+  // Evict cache entries for PRs that are no longer open.
+  const currentPrUrls = new Set<string>();
+  const currentApiPaths = new Set<string>();
+  for (const entries of branchPrs.values()) {
+    for (const entry of entries) {
+      currentPrUrls.add(entry.url);
+      const repoSlug = entry.repo
+        ? linkedRepos.find((lr) => lr.alias === entry.repo)?.repo ?? "{owner}/{repo}"
+        : "{owner}/{repo}";
+      currentApiPaths.add(`repos/${repoSlug}/pulls/${entry.number}/comments?per_page=100`);
+    }
+  }
+  for (const url of prUpdatedAtCache.keys()) {
+    if (!currentPrUrls.has(url)) prUpdatedAtCache.delete(url);
+  }
+  for (const url of prCommentsCache.keys()) {
+    if (!currentPrUrls.has(url)) prCommentsCache.delete(url);
+  }
+  for (const key of etagCache.keys()) {
+    if (!currentApiPaths.has(key)) etagCache.delete(key);
+  }
 }
 
-/** Start periodic PR status sync. Returns a cleanup function that stops the monitor. */
+/** Start periodic PR status sync. Returns a cleanup function that stops the monitor.
+ *  When `isActive` is provided, polling is skipped if no clients are connected. */
 export function startPrMonitor(
   getWorktreePaths: () => Promise<Map<string, string>>,
   linkedRepos: LinkedRepoConfig[],
   projectDir?: string,
   intervalMs: number = 20_000,
+  isActive?: () => boolean,
 ): () => void {
   const run = (): void => {
+    if (isActive && !isActive()) {
+      log.debug("[pr] skipping PR sync: no active clients");
+      return;
+    }
     syncPrStatus(getWorktreePaths, linkedRepos, projectDir).catch(
       (err: unknown) => {
         log.error(`[pr] sync error: ${err}`);

backend/src/server.ts

@@ -31,7 +31,7 @@ import { loadConfig, gitRoot, type WmdevConfig } from "./config";
 import { startPrMonitor, type PrEntry } from "./pr";
 import { handleWorkmuxRpc } from "./rpc";
 import { jsonResponse, errorResponse } from "./http";
-import { handleNotificationStream, handleDismissNotification, installHookScripts } from "./notifications";
+import { handleNotificationStream, handleDismissNotification, installHookScripts, hasDashboardActivity, touchActivity } from "./notifications";
 import { fetchAssignedIssues, branchMatchesIssue, type LinkedLinearIssue } from "./linear";
 
 const PORT = parseInt(Bun.env.BACKEND_PORT || "5111", 10);
@@ -211,6 +211,7 @@ function makeCallbacks(ws: { send: (data: string) => void; readyState: number })
 // --- API handler functions (thin I/O layer, testable by injecting deps) ---
 
 async function apiGetWorktrees(req: Request): Promise<Response> {
+  touchActivity();
   const now = Date.now();
 
   // Serve from cache if still fresh
@@ -610,7 +611,7 @@ if (tmuxCheck.exitCode !== 0) {
 }
 
 cleanupStaleSessions();
-startPrMonitor(getWorktreePaths, config.linkedRepos, PROJECT_DIR);
+startPrMonitor(getWorktreePaths, config.linkedRepos, PROJECT_DIR, undefined, hasDashboardActivity);
 installHookScripts().catch((err: unknown) => {
   log.error(`[notify] failed to install hook scripts: ${err instanceof Error ? err.message : String(err)}`);
 });

frontend/src/App.svelte

@@ -280,25 +280,37 @@
       .catch(() => {});
     refresh();
     refreshLinear();
-    const interval = setInterval(refresh, 5000);
+    let interval = setInterval(refresh, 5000);
     window.addEventListener("keydown", handleKeydown);
-    const unsubNotifications = api.subscribeNotifications(handleNotification, handleSseDismiss, handleInitialNotification);
+    let unsubNotifications = api.subscribeNotifications(handleNotification, handleSseDismiss, handleInitialNotification);
     // Request notification permission (no-op if already granted/denied)
     if (Notification.permission === "default") {
       Notification.requestPermission().catch(() => {});
     }
 
+    // Pause polling when tab is hidden to reduce server load.
+    function onVisibilityChange(): void {
+      if (document.hidden) {
+        clearInterval(interval);
+      } else {
+        refresh();
+        interval = setInterval(refresh, 5000);
+      }
+    }
+    document.addEventListener("visibilitychange", onVisibilityChange);
+
     const mq = window.matchMedia("(max-width: 768px)");
     isMobile = mq.matches;
     if (isMobile) sidebarOpen = true;
-    function onMqChange(e: MediaQueryListEvent) {
+    function onMqChange(e: MediaQueryListEvent): void {
       isMobile = e.matches;
     }
     mq.addEventListener("change", onMqChange);
 
     return () => {
       clearInterval(interval);
       window.removeEventListener("keydown", handleKeydown);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
       mq.removeEventListener("change", onMqChange);
       unsubNotifications();
     };