feat: show last refresh time and trigger in tooltip

Adds debugging visibility to ReviewPanel's refresh button tooltip:
- Shows how long ago the last refresh occurred (e.g., '5s ago', '2m ago')
- Shows what triggered the refresh (manual click, tool completion, focus, etc.)
- Persisted per-workspace so it survives workspace switches

RefreshController now uses rate-limiting instead of debouncing:
- First event starts timer; subsequent events don't reset it
- Guarantees refresh fires within N seconds of first trigger
- Events during in-flight refresh queue a follow-up after completion
- Better UX during rapid tool calls (refreshes periodically vs never)

Trigger types tracked:
- manual: user clicked refresh button
- scheduled: rate-limited tool completion
- priority: rate-limited tool completion (active workspace)
- focus: window regained focus
- visibility: tab became visible
- unpaused: interaction ended, flushing pending
- in-flight-followup: queued while previous refresh was running

Also adds formatRelativeTimeCompact() to dateTime utils.

Author: ammar-agent

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

@@ -5,14 +5,30 @@
 import React, { useState, useRef, useEffect } from "react";
 import { Tooltip, TooltipTrigger, TooltipContent } from "@/browser/components/ui/tooltip";
 import { formatKeybind, KEYBINDS } from "@/browser/utils/ui/keybinds";
+import { formatRelativeTimeCompact } from "@/browser/utils/ui/dateTime";
 import { cn } from "@/common/lib/utils";
+import type { LastRefreshInfo, RefreshTrigger } from "@/browser/utils/RefreshController";
 
 interface RefreshButtonProps {
   onClick: () => void;
   isLoading?: boolean;
+  /** Debug info about last refresh (timestamp and trigger) */
+  lastRefreshInfo?: LastRefreshInfo | null;
 }
 
-export const RefreshButton: React.FC<RefreshButtonProps> = ({ onClick, isLoading = false }) => {
+/** Human-readable trigger labels */
+const TRIGGER_LABELS: Record<RefreshTrigger, string> = {
+  manual: "manual click",
+  scheduled: "tool completion",
+  priority: "tool completion (priority)",
+  focus: "window focus",
+  visibility: "tab visible",
+  unpaused: "interaction ended",
+  "in-flight-followup": "queued followup",
+};
+
+export const RefreshButton: React.FC<RefreshButtonProps> = (props) => {
+  const { onClick, isLoading = false, lastRefreshInfo } = props;
   // Track animation state for graceful stopping
   const [animationState, setAnimationState] = useState<"idle" | "spinning" | "stopping">("idle");
   const spinOnceTimeoutRef = useRef<number | null>(null);
@@ -76,9 +92,19 @@ export const RefreshButton: React.FC<RefreshButtonProps> = ({ onClick, isLoading
         </button>
       </TooltipTrigger>
       <TooltipContent side="bottom" align="start">
-        {animationState !== "idle"
-          ? "Refreshing..."
-          : `Refresh diff (${formatKeybind(KEYBINDS.REFRESH_REVIEW)})`}
+        {animationState !== "idle" ? (
+          "Refreshing..."
+        ) : (
+          <span>
+            Refresh diff ({formatKeybind(KEYBINDS.REFRESH_REVIEW)})
+            {lastRefreshInfo && (
+              <span className="text-muted block text-[10px]">
+                Last: {formatRelativeTimeCompact(lastRefreshInfo.timestamp)} via{" "}
+                {TRIGGER_LABELS[lastRefreshInfo.trigger]}
+              </span>
+            )}
+          </span>
+        )}
       </TooltipContent>
     </Tooltip>
   );

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

@@ -5,6 +5,7 @@
 import React, { useState } from "react";
 import { usePersistedState } from "@/browser/hooks/usePersistedState";
 import type { ReviewFilters, ReviewStats } from "@/common/types/review";
+import type { LastRefreshInfo } from "@/browser/utils/RefreshController";
 import { RefreshButton } from "./RefreshButton";
 import { UntrackedStatus } from "./UntrackedStatus";
 
@@ -17,6 +18,8 @@ interface ReviewControlsProps {
   workspaceId: string;
   workspacePath: string;
   refreshTrigger?: number;
+  /** Debug info about last refresh */
+  lastRefreshInfo?: LastRefreshInfo | null;
 }
 
 export const ReviewControls: React.FC<ReviewControlsProps> = ({
@@ -28,6 +31,7 @@ export const ReviewControls: React.FC<ReviewControlsProps> = ({
   workspaceId,
   workspacePath,
   refreshTrigger,
+  lastRefreshInfo,
 }) => {
   // Local state for input value - only commit on blur/Enter
   const [inputValue, setInputValue] = useState(filters.diffBase);
@@ -83,7 +87,13 @@ export const ReviewControls: React.FC<ReviewControlsProps> = ({
 
   return (
     <div className="bg-separator border-border-light flex flex-wrap items-center gap-3 border-b px-3 py-2 text-[11px]">
-      {onRefresh && <RefreshButton onClick={onRefresh} isLoading={isLoading} />}
+      {onRefresh && (
+        <RefreshButton
+          onClick={onRefresh}
+          isLoading={isLoading}
+          lastRefreshInfo={lastRefreshInfo}
+        />
+      )}
       <label className="text-muted font-medium whitespace-nowrap">Base:</label>
       <input
         type="text"

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

@@ -845,6 +845,7 @@ export const ReviewPanel: React.FC<ReviewPanelProps> = ({
         workspaceId={workspaceId}
         workspacePath={workspacePath}
         refreshTrigger={refreshTrigger}
+        lastRefreshInfo={refreshController.lastRefreshInfo}
       />
 
       {diffState.status === "error" ? (

src/browser/hooks/useReviewRefreshController.ts

@@ -1,7 +1,8 @@
 import { useEffect, useRef, useMemo } from "react";
 import { workspaceStore } from "@/browser/stores/WorkspaceStore";
 import type { APIClient } from "@/browser/contexts/API";
-import { RefreshController } from "@/browser/utils/RefreshController";
+import { RefreshController, type LastRefreshInfo } from "@/browser/utils/RefreshController";
+import { usePersistedState } from "@/browser/hooks/usePersistedState";
 
 /** Debounce delay for auto-refresh after tool completion */
 const TOOL_REFRESH_DEBOUNCE_MS = 3000;
@@ -43,6 +44,8 @@ export interface ReviewRefreshController {
   setInteracting: (interacting: boolean) => void;
   /** Whether a git fetch is currently in-flight */
   isRefreshing: boolean;
+  /** Info about the last completed refresh (for debugging) */
+  lastRefreshInfo: LastRefreshInfo | null;
 }
 
 /**
@@ -57,22 +60,30 @@ export interface ReviewRefreshController {
 export function useReviewRefreshController(
   options: UseReviewRefreshControllerOptions
 ): ReviewRefreshController {
-  const { workspaceId, api, isCreating, onRefresh, scrollContainerRef, onGitStatusRefresh } =
-    options;
+  const { workspaceId, api, isCreating, scrollContainerRef } = options;
 
   // Refs for values that executeRefresh needs at call time (avoid stale closures)
   const diffBaseRef = useRef(options.diffBase);
   diffBaseRef.current = options.diffBase;
 
-  const onGitStatusRefreshRef = useRef(onGitStatusRefresh);
-  onGitStatusRefreshRef.current = onGitStatusRefresh;
+  const onRefreshRef = useRef(options.onRefresh);
+  onRefreshRef.current = options.onRefresh;
+
+  const onGitStatusRefreshRef = useRef(options.onGitStatusRefresh);
+  onGitStatusRefreshRef.current = options.onGitStatusRefresh;
 
   // Scroll position to restore after refresh
   const savedScrollTopRef = useRef<number | null>(null);
 
   // User interaction state (pauses auto-refresh)
   const isInteractingRef = useRef(false);
 
+  // Track last refresh info - persisted per workspace so it survives workspace switches
+  const [lastRefreshInfo, setLastRefreshInfo] = usePersistedState<LastRefreshInfo | null>(
+    `review-last-refresh:${workspaceId}`,
+    null
+  );
+
   // Create RefreshController once, with stable callbacks via refs
   const controller = useMemo(() => {
     const ctrl = new RefreshController({
@@ -97,14 +108,16 @@ export function useReviewRefreshController(
           }
         }
 
-        onRefresh();
+        onRefreshRef.current();
         onGitStatusRefreshRef.current?.();
       },
+      onRefreshComplete: setLastRefreshInfo,
     });
     ctrl.bindListeners();
     return ctrl;
     // workspaceId/api/isCreating changes require new controller with updated closure
-  }, [workspaceId, api, isCreating, onRefresh, scrollContainerRef]);
+    // Note: options.onRefresh is accessed via ref to avoid recreating controller on every render
+  }, [workspaceId, api, isCreating, scrollContainerRef, setLastRefreshInfo]);
 
   // Cleanup on unmount or when controller changes
   useEffect(() => {
@@ -115,12 +128,18 @@ export function useReviewRefreshController(
   useEffect(() => {
     if (!api || isCreating) return;
 
-    const unsubscribe = workspaceStore.subscribeFileModifyingTool(
-      () => controller.schedule(),
-      workspaceId
-    );
-
-    return unsubscribe;
+    console.debug(`[ReviewRefresh] subscribing to tool completions for ${workspaceId}`);
+    const unsubscribe = workspaceStore.subscribeFileModifyingTool(() => {
+      console.debug(
+        `[ReviewRefresh] tool completion received for ${workspaceId}, calling schedule()`
+      );
+      controller.schedule();
+    }, workspaceId);
+
+    return () => {
+      console.debug(`[ReviewRefresh] unsubscribing from tool completions for ${workspaceId}`);
+      unsubscribe();
+    };
   }, [api, workspaceId, isCreating, controller]);
 
   // Public API
@@ -144,6 +163,7 @@ export function useReviewRefreshController(
     get isRefreshing() {
       return controller.isRefreshing;
     },
+    lastRefreshInfo,
   };
 }
 

src/browser/stores/WorkspaceStore.test.ts

@@ -773,4 +773,151 @@ describe("WorkspaceStore", () => {
       expect(live).toBeNull();
     });
   });
+
+  describe("file-modifying tool subscription", () => {
+    it("notifies subscribers when bash tool completes", async () => {
+      const workspaceId = "file-modify-test-1";
+      const notifications: string[] = [];
+
+      // Subscribe BEFORE creating workspace
+      const unsubscribe = store.subscribeFileModifyingTool((wsId) => {
+        notifications.push(wsId);
+      }, workspaceId);
+
+      mockOnChat.mockImplementation(async function* (): AsyncGenerator<
+        WorkspaceChatMessage,
+        void,
+        unknown
+      > {
+        yield { type: "caught-up" };
+        await Promise.resolve();
+        yield {
+          type: "tool-call-end",
+          workspaceId,
+          messageId: "m1",
+          toolCallId: "call-1",
+          toolName: "bash",
+          result: { success: true, output: "done", exitCode: 0, wall_duration_ms: 1 },
+          timestamp: 1,
+        };
+      });
+
+      createAndAddWorkspace(store, workspaceId);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(notifications).toContain(workspaceId);
+      expect(notifications.length).toBe(1);
+
+      unsubscribe();
+    });
+
+    it("notifies subscribers when file_edit tool completes", async () => {
+      const workspaceId = "file-modify-test-2";
+      const notifications: string[] = [];
+
+      const unsubscribe = store.subscribeFileModifyingTool((wsId) => {
+        notifications.push(wsId);
+      }, workspaceId);
+
+      mockOnChat.mockImplementation(async function* (): AsyncGenerator<
+        WorkspaceChatMessage,
+        void,
+        unknown
+      > {
+        yield { type: "caught-up" };
+        await Promise.resolve();
+        yield {
+          type: "tool-call-end",
+          workspaceId,
+          messageId: "m1",
+          toolCallId: "call-1",
+          toolName: "file_edit_replace_string",
+          result: { success: true },
+          timestamp: 1,
+        };
+      });
+
+      createAndAddWorkspace(store, workspaceId);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(notifications).toContain(workspaceId);
+      unsubscribe();
+    });
+
+    it("does NOT notify for non-file-modifying tools", async () => {
+      const workspaceId = "file-modify-test-3";
+      const notifications: string[] = [];
+
+      const unsubscribe = store.subscribeFileModifyingTool((wsId) => {
+        notifications.push(wsId);
+      }, workspaceId);
+
+      mockOnChat.mockImplementation(async function* (): AsyncGenerator<
+        WorkspaceChatMessage,
+        void,
+        unknown
+      > {
+        yield { type: "caught-up" };
+        await Promise.resolve();
+        yield {
+          type: "tool-call-end",
+          workspaceId,
+          messageId: "m1",
+          toolCallId: "call-1",
+          toolName: "web_search", // Not file-modifying
+          result: { success: true },
+          timestamp: 1,
+        };
+      });
+
+      createAndAddWorkspace(store, workspaceId);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(notifications.length).toBe(0);
+      unsubscribe();
+    });
+
+    it("only notifies subscribers for the specific workspace", async () => {
+      const workspaceId1 = "file-modify-test-4a";
+      const workspaceId2 = "file-modify-test-4b";
+      const notifications1: string[] = [];
+      const notifications2: string[] = [];
+
+      const unsubscribe1 = store.subscribeFileModifyingTool((wsId) => {
+        notifications1.push(wsId);
+      }, workspaceId1);
+
+      const unsubscribe2 = store.subscribeFileModifyingTool((wsId) => {
+        notifications2.push(wsId);
+      }, workspaceId2);
+
+      // Only emit tool completion for workspace1
+      mockOnChat.mockImplementation(async function* (): AsyncGenerator<
+        WorkspaceChatMessage,
+        void,
+        unknown
+      > {
+        yield { type: "caught-up" };
+        await Promise.resolve();
+        yield {
+          type: "tool-call-end",
+          workspaceId: workspaceId1,
+          messageId: "m1",
+          toolCallId: "call-1",
+          toolName: "bash",
+          result: { success: true, output: "done", exitCode: 0, wall_duration_ms: 1 },
+          timestamp: 1,
+        };
+      });
+
+      createAndAddWorkspace(store, workspaceId1);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      expect(notifications1.length).toBe(1);
+      expect(notifications2.length).toBe(0); // Not notified - different workspace
+
+      unsubscribe1();
+      unsubscribe2();
+    });
+  });
 });

src/browser/stores/WorkspaceStore.ts

@@ -482,6 +482,9 @@ export class WorkspaceStore {
 
       // Track file-modifying tools for ReviewPanel diff refresh
       if (toolCallEnd.toolName.startsWith("file_edit_") || toolCallEnd.toolName === "bash") {
+        console.debug(
+          `[WorkspaceStore] file-modifying tool completed: ${toolCallEnd.toolName} for ${workspaceId}`
+        );
         this.fileModifyingToolMs.set(workspaceId, Date.now());
         this.fileModifyingToolSubs.bump(workspaceId);
       }