🤖 perf: event-driven git status updates instead of polling (#1293)

## Summary

Replaces 3-second interval polling for git status
(dirty/ahead-behind/additions-deletions) with event-driven updates.

## Trigger strategy

Git status now refreshes when:
- **File-modifying tool completions** (bash, file_edit_*) — 3s
trailing-edge debounce, same as ReviewPanel
- **Window focus / visibility change** — catches external git operations
(user ran git commands outside mux)
- **Initial UI subscription** — immediate fetch when workspace indicator
first renders
- **Explicit invalidation** — branch switches and other actions that
already call `invalidateWorkspace()`

## Implementation

- **GitStatusStore**: Removed interval polling; added focus/visibility
listeners; wires into WorkspaceStore's file-modification events via
`subscribeToFileModifications()`
- **WorkspaceStore**: Consolidated `subscribeFileModifyingTool` API —
single method with optional workspace filter instead of two separate
methods
- **AppLoader**: Wires the subscription at init time
- **Preserved optimization**: Only fetches status for workspaces with
active UI subscribers (`hasKeySubscribers`)

## Validation

- `make typecheck` ✓
- `bun test src/browser/stores/` ✓ (60 tests)
- `make static-check` ✓

---
_Generated with `mux` • Model: `anthropic:claude-opus-4-5` • Thinking:
`high`_

Author: ammar-agent

src/browser/components/AppLoader.tsx

@@ -2,7 +2,7 @@ import { useState, useEffect } from "react";
 import App from "../App";
 import { AuthTokenModal } from "./AuthTokenModal";
 import { LoadingScreen } from "./LoadingScreen";
-import { useWorkspaceStoreRaw } from "../stores/WorkspaceStore";
+import { useWorkspaceStoreRaw, workspaceStore } from "../stores/WorkspaceStore";
 import { useGitStatusStoreRaw } from "../stores/GitStatusStore";
 import { ProjectProvider, useProjectContext } from "../contexts/ProjectContext";
 import { APIProvider, useAPI, type APIClient } from "@/browser/contexts/API";
@@ -47,7 +47,7 @@ function AppLoaderInner() {
   const api = apiState.api;
 
   // Get store instances
-  const workspaceStore = useWorkspaceStoreRaw();
+  const workspaceStoreInstance = useWorkspaceStoreRaw();
   const gitStatusStore = useGitStatusStoreRaw();
 
   // Track whether stores have been synced
@@ -56,21 +56,27 @@ function AppLoaderInner() {
   // Sync stores when metadata finishes loading
   useEffect(() => {
     if (api) {
-      workspaceStore.setClient(api);
+      workspaceStoreInstance.setClient(api);
       gitStatusStore.setClient(api);
     }
 
     if (!workspaceContext.loading) {
-      workspaceStore.syncWorkspaces(workspaceContext.workspaceMetadata);
+      workspaceStoreInstance.syncWorkspaces(workspaceContext.workspaceMetadata);
       gitStatusStore.syncWorkspaces(workspaceContext.workspaceMetadata);
+
+      // Wire up file-modification subscription (idempotent - only subscribes once)
+      gitStatusStore.subscribeToFileModifications((listener) =>
+        workspaceStore.subscribeFileModifyingTool(listener)
+      );
+
       setStoresSynced(true);
     } else {
       setStoresSynced(false);
     }
   }, [
     workspaceContext.loading,
     workspaceContext.workspaceMetadata,
-    workspaceStore,
+    workspaceStoreInstance,
     gitStatusStore,
     api,
   ]);

src/browser/components/RightSidebar/CodeReview/ReviewPanel.tsx

@@ -45,6 +45,7 @@ import { applyFrontendFilters } from "@/browser/utils/review/filterHunks";
 import { cn } from "@/common/lib/utils";
 import { useAPI, type APIClient } from "@/browser/contexts/API";
 import { workspaceStore } from "@/browser/stores/WorkspaceStore";
+import { invalidateGitStatus } from "@/browser/stores/GitStatusStore";
 
 /** Stats reported to parent for tab display */
 interface ReviewPanelStats {
@@ -242,6 +243,7 @@ export const ReviewPanel: React.FC<ReviewPanelProps> = ({
     diffBase: filters.diffBase,
     onRefresh: () => setRefreshTrigger((prev) => prev + 1),
     scrollContainerRef,
+    onGitStatusRefresh: () => invalidateGitStatus(workspaceId),
   });
 
   const handleRefresh = () => {

src/browser/hooks/useReviewRefreshController.ts

@@ -31,6 +31,8 @@ export interface UseReviewRefreshControllerOptions {
   onRefresh: () => void;
   /** Ref to scroll container for preserving scroll position */
   scrollContainerRef: React.RefObject<HTMLElement | null>;
+  /** Optional: called after refresh to trigger git status update */
+  onGitStatusRefresh?: () => void;
 }
 
 export interface ReviewRefreshController {
@@ -60,12 +62,17 @@ export interface ReviewRefreshController {
 export function useReviewRefreshController(
   options: UseReviewRefreshControllerOptions
 ): ReviewRefreshController {
-  const { workspaceId, api, isCreating, onRefresh, scrollContainerRef } = options;
+  const { workspaceId, api, isCreating, onRefresh, scrollContainerRef, onGitStatusRefresh } =
+    options;
 
   // Store diffBase in a ref so we always read the latest value
   const diffBaseRef = useRef(options.diffBase);
   diffBaseRef.current = options.diffBase;
 
+  // Store onGitStatusRefresh in a ref to avoid stale closures
+  const onGitStatusRefreshRef = useRef(onGitStatusRefresh);
+  onGitStatusRefreshRef.current = onGitStatusRefresh;
+
   // State refs (avoid re-renders, just track state for refresh logic)
   const isRefreshingRef = useRef(false);
   const isInteractingRef = useRef(false);
@@ -111,6 +118,7 @@ export function useReviewRefreshController(
           isRefreshingRef.current = false;
           isRefreshingForReturn.current = false;
           onRefresh();
+          onGitStatusRefreshRef.current?.();
 
           // If another refresh was requested while we were fetching, do it now
           if (pendingBecauseInFlightRef.current) {
@@ -125,6 +133,7 @@ export function useReviewRefreshController(
 
     // Local base - just trigger refresh immediately
     onRefresh();
+    onGitStatusRefreshRef.current?.();
   });
 
   // Update executeRefresh closure dependencies
@@ -151,6 +160,7 @@ export function useReviewRefreshController(
           isRefreshingRef.current = false;
           isRefreshingForReturn.current = false;
           onRefresh();
+          onGitStatusRefreshRef.current?.();
 
           if (pendingBecauseInFlightRef.current) {
             pendingBecauseInFlightRef.current = false;
@@ -162,6 +172,7 @@ export function useReviewRefreshController(
     }
 
     onRefresh();
+    onGitStatusRefreshRef.current?.();
   };
 
   /**
@@ -225,7 +236,7 @@ export function useReviewRefreshController(
   useEffect(() => {
     if (!api || isCreating) return;
 
-    const unsubscribe = workspaceStore.subscribeFileModifyingTool(workspaceId, scheduleRefresh);
+    const unsubscribe = workspaceStore.subscribeFileModifyingTool(scheduleRefresh, workspaceId);
 
     return () => {
       unsubscribe();

src/browser/stores/GitStatusStore.ts

@@ -10,25 +10,26 @@ import {
 import { useSyncExternalStore } from "react";
 import { MapStore } from "./MapStore";
 import { isSSHRuntime } from "@/common/types/runtime";
+import { RefreshController } from "@/browser/utils/RefreshController";
 
 /**
  * External store for git status of all workspaces.
  *
  * Architecture:
  * - Lives outside React lifecycle (stable references)
- * - Polls git status every 3 seconds
+ * - Event-driven updates (no polling):
+ *   - Initial subscription triggers immediate fetch
+ *   - File-modifying tools trigger debounced refresh (3s)
+ *   - Window focus triggers refresh for visible workspaces
+ *   - Explicit invalidation (branch switch, etc.)
  * - Manages git fetch with exponential backoff
  * - Notifies subscribers when status changes
  * - Components only re-render when their specific workspace status changes
  *
- * Migration from GitStatusContext:
- * - Eliminates provider re-renders every 3 seconds
- * - useSyncExternalStore enables selective re-renders
- * - Store manages polling logic internally (no useEffect cleanup in components)
+ * Uses RefreshController for debouncing, focus handling, and in-flight guards.
  */
 
 // Configuration
-const GIT_STATUS_INTERVAL_MS = 3000; // 3 seconds - interactive updates
 const MAX_CONCURRENT_GIT_OPS = 5;
 
 // Fetch configuration - aggressive intervals for fresh data
@@ -45,16 +46,28 @@ export class GitStatusStore {
   private statuses = new MapStore<string, GitStatus | null>();
   private fetchCache = new Map<string, FetchState>();
   private client: RouterClient<AppRouter> | null = null;
-  private pollInterval: NodeJS.Timeout | null = null;
   private immediateUpdateQueued = false;
   private workspaceMetadata = new Map<string, FrontendWorkspaceMetadata>();
   private isActive = true;
 
+  // File modification subscription
+  private fileModifyUnsubscribe: (() => void) | null = null;
+
+  // RefreshController handles debouncing, focus/visibility, and in-flight guards
+  private readonly refreshController: RefreshController;
+
   setClient(client: RouterClient<AppRouter>) {
     this.client = client;
   }
+
   constructor() {
-    // Store is ready for workspace sync
+    // Create refresh controller with proactive focus refresh (catches external git changes)
+    this.refreshController = new RefreshController({
+      onRefresh: () => this.updateGitStatus(),
+      debounceMs: 3000, // Same as TOOL_REFRESH_DEBOUNCE_MS in ReviewPanel
+      refreshOnFocus: true, // Proactively refresh on focus to catch external changes
+      focusDebounceMs: 500, // Prevent spam from rapid alt-tabbing
+    });
   }
 
   /**
@@ -70,16 +83,14 @@ export class GitStatusStore {
   subscribeKey = (workspaceId: string, listener: () => void) => {
     const unsubscribe = this.statuses.subscribeKey(workspaceId, listener);
 
-    // If a component subscribes after we started polling (common on initial load),
-    // kick an immediate update so the UI doesn't wait for the next interval tick.
-    //
-    // We schedule the update as a microtask to avoid doing work in the subscribe
-    // call itself, and to preserve the batching/concurrency limits of updateGitStatus().
+    // If a component subscribes after initial load, kick an immediate update
+    // so the UI doesn't wait. Uses microtask to batch multiple subscriptions.
+    // Routes through RefreshController to respect in-flight guards.
     if (!this.immediateUpdateQueued && this.isActive && this.client) {
       this.immediateUpdateQueued = true;
       queueMicrotask(() => {
         this.immediateUpdateQueued = false;
-        void this.updateGitStatus();
+        this.refreshController.requestImmediate();
       });
     }
 
@@ -114,8 +125,8 @@ export class GitStatusStore {
     this.statusCache.set(workspaceId, null);
     // Bump version to notify subscribers of the null state
     this.statuses.bump(workspaceId);
-    // Trigger immediate update to fetch fresh status
-    void this.updateGitStatus();
+    // Trigger immediate refresh (routes through RefreshController for in-flight guard)
+    this.refreshController.requestImmediate();
   }
 
   private statusCache = new Map<string, GitStatus | null>();
@@ -146,38 +157,11 @@ export class GitStatusStore {
       }
     }
 
-    // Start polling only once (not on every sync)
-    if (!this.pollInterval) {
-      this.startPolling();
-    }
-  }
-
-  /**
-   * Start polling git status.
-   */
-  private startPolling(): void {
-    // Clear existing interval
-    if (this.pollInterval) {
-      clearInterval(this.pollInterval);
-    }
-
-    // Run immediately
-    void this.updateGitStatus();
-
-    // Poll at configured interval
-    this.pollInterval = setInterval(() => {
-      void this.updateGitStatus();
-    }, GIT_STATUS_INTERVAL_MS);
-  }
+    // Bind focus/visibility listeners once (catches external git changes)
+    this.refreshController.bindListeners();
 
-  /**
-   * Stop polling git status.
-   */
-  private stopPolling(): void {
-    if (this.pollInterval) {
-      clearInterval(this.pollInterval);
-      this.pollInterval = null;
-    }
+    // Initial fetch for all workspaces (routes through RefreshController)
+    this.refreshController.requestImmediate();
   }
 
   /**
@@ -480,9 +464,35 @@ export class GitStatusStore {
    */
   dispose(): void {
     this.isActive = false;
-    this.stopPolling();
     this.statuses.clear();
     this.fetchCache.clear();
+    this.fileModifyUnsubscribe?.();
+    this.fileModifyUnsubscribe = null;
+    this.refreshController.dispose();
+  }
+
+  /**
+   * Subscribe to file-modifying tool completions from WorkspaceStore.
+   * Triggers debounced git status refresh when files change.
+   * Idempotent: only subscribes once, subsequent calls are no-ops.
+   */
+  subscribeToFileModifications(
+    subscribeAny: (listener: (workspaceId: string) => void) => () => void
+  ): void {
+    // Only subscribe once - subsequent calls are no-ops
+    if (this.fileModifyUnsubscribe) {
+      return;
+    }
+
+    this.fileModifyUnsubscribe = subscribeAny((workspaceId) => {
+      // Only schedule if workspace has subscribers (same optimization as before)
+      if (!this.statuses.hasKeySubscribers(workspaceId)) {
+        return;
+      }
+
+      // RefreshController handles debouncing, focus gating, and in-flight guards
+      this.refreshController.schedule();
+    });
   }
 }
 

src/browser/stores/WorkspaceStore.ts

@@ -1536,11 +1536,25 @@ export class WorkspaceStore {
   }
 
   /**
-   * Subscribe to file-modifying tool completions for a workspace.
-   * Used by ReviewPanel to trigger diff refresh.
+   * Subscribe to file-modifying tool completions.
+   * @param listener Called with workspaceId when a file-modifying tool completes
+   * @param workspaceId If provided, only notify for this workspace
    */
-  subscribeFileModifyingTool(workspaceId: string, listener: () => void): () => void {
-    return this.fileModifyingToolSubs.subscribeKey(workspaceId, listener);
+  subscribeFileModifyingTool(
+    listener: (workspaceId: string) => void,
+    workspaceId?: string
+  ): () => void {
+    if (workspaceId) {
+      // Per-workspace: wrap listener to match subscribeKey signature
+      return this.fileModifyingToolSubs.subscribeKey(workspaceId, () => listener(workspaceId));
+    }
+    // All workspaces: subscribe to global notifications
+    return this.fileModifyingToolSubs.subscribeAny(() => {
+      // Notify for all workspaces that have pending changes
+      for (const wsId of this.fileModifyingToolMs.keys()) {
+        listener(wsId);
+      }
+    });
   }
 
   /**
@@ -1793,8 +1807,8 @@ function getStoreInstance(): WorkspaceStore {
 export const workspaceStore = {
   onIdleCompactionNeeded: (callback: (workspaceId: string) => void) =>
     getStoreInstance().onIdleCompactionNeeded(callback),
-  subscribeFileModifyingTool: (workspaceId: string, listener: () => void) =>
-    getStoreInstance().subscribeFileModifyingTool(workspaceId, listener),
+  subscribeFileModifyingTool: (listener: (workspaceId: string) => void, workspaceId?: string) =>
+    getStoreInstance().subscribeFileModifyingTool(listener, workspaceId),
   getFileModifyingToolMs: (workspaceId: string) =>
     getStoreInstance().getFileModifyingToolMs(workspaceId),
   clearFileModifyingToolMs: (workspaceId: string) =>