feat(review): diff staleness detection — 'out of date · Refresh' notice

Files changing mid-review (an agent editing/committing while the user
reviews) silently left a stale snapshot on screen. Now the client polls a
cheap server-side fingerprint check every 5s and shows a non-blocking
amber notice in the toolbar; the user refreshes when ready (never
automatic — annotations are line-anchored).

Architecture (write-once, both servers inherit):
- packages/shared: getGitDiffFingerprint (per git mode: commit-anchored →
  rev-parse only; working-tree → hash of the same diff the patch is built
  from + untracked contents, capped), getJjDiffFingerprint (jj snapshots
  the working copy per command, so commit ids are content-complete),
  WorkspaceReviewSession.getFingerprint (combines all children),
  VcsProvider.getDiffFingerprint + VcsApi dispatch. P4: no fingerprint →
  always fresh (no banner) in v1. All git probes use --no-optional-locks
  so background polling never races concurrent git add/commit.
- Bun + Pi servers: fingerprint captured beside every patch snapshot
  (startup + all switch endpoints); GET /api/diff/fresh recomputes and
  compares. PR layer scope is platform-side → never stale locally; PR
  full-stack fingerprints the local checkout's HEAD.
- UI: useDiffFreshness hook (5s poll, paused while hidden, off in demo),
  amber toolbar pill with Refresh (existing switch path with preserveFile
  — reviewer stays on their file; PR full-stack re-runs scope switch) and
  Dismiss (stays dismissed until a DIFFERENT change lands — endpoint
  returns the probe fingerprint to tell those apart).

Tested against a real throwaway git repo (8 cases incl. the already-
modified-file-modified-again case that git status alone cannot detect).

Author: backnotprop

apps/pi-extension/plannotator-browser.ts

@@ -10,6 +10,7 @@ import {
 	reviewRuntime,
 	detectManagedVcs,
 	getVcsContext,
+	getVcsDiffFingerprint,
 	getVcsFileContentsForDiff,
 	canStageFiles,
 	runVcsDiff,
@@ -108,6 +109,7 @@ async function buildLocalWorkspaceReview(
 		getVcsContext,
 		runVcsDiff,
 		getVcsFileContentsForDiff,
+		getVcsDiffFingerprint,
 		canStageFiles,
 		stageFile,
 		unstageFile,

apps/pi-extension/server.ts

@@ -32,6 +32,7 @@ export {
 	detectVcs,
 	getGitContext,
 	getVcsContext,
+	getVcsDiffFingerprint,
 	getVcsFileContentsForDiff,
 	prepareLocalReviewDiff,
 	resolveInitialDiffType,

apps/pi-extension/server/serverReview.ts

@@ -109,6 +109,7 @@ import {
 	canStageFiles,
 	detectRemoteDefaultCompareTarget,
 	getVcsContext,
+	getVcsDiffFingerprint,
 	getVcsFileContentsForDiff,
 	resolveVcsCwd,
 	reviewRuntime,
@@ -288,6 +289,44 @@ export async function startReviewServer(options: {
 	let currentBase = options.initialBase || detectedCompareTarget();
 	let baseEverSwitched = false;
 
+	// --- Diff staleness fingerprint (mirrors packages/server/review.ts) -------
+	// Captured beside every patch snapshot; GET /api/diff/fresh recomputes and
+	// compares so the client can show a "diff out of date — refresh" notice when
+	// files change mid-review. Best-effort: null = "cannot fingerprint" and is
+	// reported fresh, never stale.
+	let currentFingerprint: string | null = null;
+	const computeDiffFingerprint = async (): Promise<string | null> => {
+		try {
+			if (workspace) return await workspace.getFingerprint();
+			if (isPRMode) {
+				if (currentPRDiffScope === "layer") {
+					// Platform-computed diff — immutable locally; recaptured on pr-switch.
+					return `pr-layer:${prMeta?.url ?? ""}`;
+				}
+				const fullStackCwd =
+					(options.worktreePool && prMeta ? options.worktreePool.resolve(prMeta.url) : undefined) ??
+					options.agentCwd;
+				return await getVcsDiffFingerprint("last-commit", currentBase, fullStackCwd);
+			}
+			if (!hasLocalAccess) return null;
+			return await getVcsDiffFingerprint(
+				currentDiffType as DiffType,
+				currentBase,
+				options.gitContext?.cwd,
+				{ hideWhitespace: currentHideWhitespace },
+			);
+		} catch {
+			return null;
+		}
+	};
+	// Fire-and-forget capture: never delays the snapshot response it describes.
+	const captureDiffFingerprint = (): void => {
+		void computeDiffFingerprint().then((fingerprint) => {
+			currentFingerprint = fingerprint;
+		});
+	};
+	captureDiffFingerprint();
+
 	// Fire-and-forget: query the remote for its actual default branch.
 	if (options.gitContext && !options.initialBase && !isPRMode) {
 		detectRemoteDefaultCompareTarget(options.gitContext.cwd, sessionVcsType).then((remote) => {
@@ -619,6 +658,27 @@ export async function startReviewServer(options: {
 				semanticDiff: await getSemanticDiffAdvert(),
 				serverConfig: getServerConfig(gitUser),
 			});
+		} else if (url.pathname === "/api/diff/fresh" && req.method === "GET") {
+			// Cheap staleness probe — has the underlying VCS state changed since
+			// the current diff snapshot was computed? Best-effort: anything that
+			// cannot be fingerprinted reports fresh (no banner).
+			const baseline = currentFingerprint;
+			if (baseline == null) {
+				json(res, { fresh: true });
+				return;
+			}
+			const probe = await computeDiffFingerprint();
+			// A diff switch landing mid-probe replaces the snapshot (and its
+			// fingerprint); report fresh and let the next poll compare against
+			// the new baseline.
+			if (currentFingerprint !== baseline) {
+				json(res, { fresh: true });
+				return;
+			}
+			const fresh = probe == null || probe === baseline;
+			// The probe fingerprint lets the client distinguish "still the same
+			// staleness I dismissed" from "ANOTHER change landed since".
+			json(res, { fresh, ...(fresh ? {} : { fingerprint: probe }) });
 		} else if (url.pathname === "/api/semantic-diff" && req.method === "GET") {
 			json(res, await getSemanticDiff(url));
 		} else if (url.pathname === "/api/diff/switch" && req.method === "POST") {
@@ -646,6 +706,7 @@ export async function startReviewServer(options: {
 					currentDiffType = workspace.diffType;
 					currentError = snapshot.error;
 					draftKey = contentHash(currentPatch);
+					captureDiffFingerprint();
 
 					json(res, {
 						rawPatch: currentPatch,
@@ -673,6 +734,7 @@ export async function startReviewServer(options: {
 				currentBase = base;
 				baseEverSwitched = true;
 				currentError = result.error;
+				captureDiffFingerprint();
 
 				// Recompute gitContext for the effective cwd so the client's
 				// sidebar reflects the worktree we're now reviewing.
@@ -722,6 +784,7 @@ export async function startReviewServer(options: {
 					currentGitRef = originalPRGitRef;
 					currentError = originalPRError;
 					currentPRDiffScope = "layer";
+					captureDiffFingerprint();
 					json(res, {
 						rawPatch: currentPatch,
 						gitRef: currentGitRef,
@@ -750,6 +813,7 @@ export async function startReviewServer(options: {
 				currentGitRef = result.label;
 				currentError = undefined;
 				currentPRDiffScope = "full-stack";
+				captureDiffFingerprint();
 				json(res, {
 					rawPatch: currentPatch,
 					gitRef: currentGitRef,
@@ -785,6 +849,7 @@ export async function startReviewServer(options: {
 				currentPRDiffScope = "layer";
 				draftKey = contentHash(pr.rawPatch);
 				prListCache = null;
+				captureDiffFingerprint();
 
 				prStackInfo = getPRStackInfo(pr.metadata);
 				if (prStackTreeCache.has(body.url)) {

apps/pi-extension/server/vcs.ts

@@ -98,6 +98,7 @@ export const {
 	prepareLocalReviewDiff,
 	runVcsDiff,
 	getVcsFileContentsForDiff,
+	getVcsDiffFingerprint,
 	canStageFiles,
 	stageFile,
 	unstageFile,

packages/review-editor/App.tsx

@@ -60,6 +60,7 @@ import { StackedPRLabel } from './components/StackedPRLabel';
 import { PRSelector } from './components/PRSelector';
 import { PRSwitchOverlay } from './components/PRSwitchOverlay';
 import { usePRStack } from './hooks/usePRStack';
+import { useDiffFreshness } from './hooks/useDiffFreshness';
 import { usePRSession, type PRSessionUpdate } from './hooks/usePRSession';
 import { useAnnotationFactory } from './hooks/useAnnotationFactory';
 import { DEMO_DIFF } from './demoData';
@@ -1459,6 +1460,29 @@ const ReviewApp: React.FC = () => {
     fetchDiffSwitch(diffType, selectedBase, { preserveFile: true });
   }, [diffHideWhitespace, origin, reviewMode]); // eslint-disable-line react-hooks/exhaustive-deps
 
+  // --- Diff staleness ---------------------------------------------------------
+  // Files changing mid-review (an agent editing/committing while the user
+  // reviews) make the snapshot on screen stale. The hook polls the server's
+  // cheap fingerprint check; the toolbar shows a non-blocking notice and the
+  // user refreshes when THEY are ready — never automatically (annotations are
+  // line-anchored; rug-pulling the diff under them is worse than staleness).
+  const diffFreshness = useDiffFreshness({
+    enabled: !!origin,
+    resetKey: diffData?.rawPatch ?? '',
+  });
+
+  const handleRefreshStaleDiff = useCallback(() => {
+    if (prMetadata) {
+      // Only the full-stack scope can go stale locally — the layer diff is
+      // computed platform-side and its fingerprint never flips.
+      if (prDiffScope === 'full-stack') handlePRDiffScopeSelect('full-stack');
+      return;
+    }
+    // Same params, fresh snapshot. preserveFile keeps the reviewer on the
+    // file they were reading.
+    void fetchDiffSwitch(diffType, selectedBase, { preserveFile: true });
+  }, [prMetadata, prDiffScope, handlePRDiffScopeSelect, fetchDiffSwitch, diffType, selectedBase]);
+
   // Select annotation - switches file if needed and scrolls to it.
   // isAllFilesActive is read through the ref (declared with the state): this
   // handler is baked into Pierre slot portals, which only republish on item
@@ -2150,6 +2174,31 @@ const ReviewApp: React.FC = () => {
                   </div>
                 )}
 
+                {/* Diff staleness notice — files changed since this snapshot
+                    was computed (agent editing mid-review). Non-blocking; the
+                    user refreshes when ready. */}
+                {diffFreshness.isStale && !isLoadingDiff && (
+                  <div className="flex items-center gap-2 text-xs text-amber-700 dark:text-amber-300 px-2 py-1 bg-amber-500/10 rounded border border-amber-500/25">
+                    <span className="hidden md:inline">Diff out of date</span>
+                    <span className="md:hidden">Stale</span>
+                    <button
+                      onClick={handleRefreshStaleDiff}
+                      className="font-medium underline underline-offset-2 hover:text-amber-900 dark:hover:text-amber-100 transition-colors"
+                      title="Re-run the diff with the current settings"
+                    >
+                      Refresh
+                    </button>
+                    <button
+                      onClick={diffFreshness.dismiss}
+                      className="text-amber-700/60 dark:text-amber-300/60 hover:text-amber-900 dark:hover:text-amber-100 transition-colors leading-none"
+                      title="Dismiss"
+                      aria-label="Dismiss stale diff notice"
+                    >
+                      ×
+                    </button>
+                  </div>
+                )}
+
                 {/* Agent mode: Close/SendFeedback flip + Approve */}
                 {!platformMode ? (
                   <AgentReviewActions

packages/review-editor/hooks/useDiffFreshness.ts

@@ -0,0 +1,89 @@
+import { useCallback, useEffect, useState } from 'react';
+
+const POLL_INTERVAL_MS = 5000;
+
+export interface DiffFreshness {
+  /** True when the underlying files changed since the current diff snapshot
+   * was computed AND the user hasn't dismissed this particular staleness. */
+  isStale: boolean;
+  /** Hide the notice for the CURRENT staleness. A further change (different
+   * server fingerprint) re-shows it; a diff refresh resets everything. */
+  dismiss: () => void;
+}
+
+/**
+ * Polls `GET /api/diff/fresh` while the review is open. The server compares a
+ * cheap VCS fingerprint captured when the diff snapshot was computed against
+ * the repo's state NOW — files changing mid-review (the normal agent-editing-
+ * while-you-review workflow) flips `fresh` to false.
+ *
+ * Polling is timer-based on purpose: in this product the files change while
+ * the user is actively IN the review (an agent works underneath them), so a
+ * focus/visibility trigger would miss the case that matters. Ticks are
+ * skipped while the document is hidden, and the whole hook no-ops in demo
+ * mode (`enabled: false`).
+ */
+export function useDiffFreshness({
+  enabled,
+  resetKey,
+}: {
+  enabled: boolean;
+  /** Identity of the current diff snapshot (e.g. the rawPatch string). A new
+   * snapshot (refresh / switch) clears staleness + dismissal and resumes. */
+  resetKey: string;
+}): DiffFreshness {
+  const [staleFingerprint, setStaleFingerprint] = useState<string | null>(null);
+  const [dismissedFingerprint, setDismissedFingerprint] = useState<string | null>(null);
+
+  // New snapshot → clean slate.
+  useEffect(() => {
+    setStaleFingerprint(null);
+    setDismissedFingerprint(null);
+  }, [resetKey]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const schedule = () => {
+      if (!cancelled) timer = setTimeout(tick, POLL_INTERVAL_MS);
+    };
+
+    const tick = async () => {
+      // Nobody is looking — don't burn VCS commands on a hidden window.
+      if (document.hidden) {
+        schedule();
+        return;
+      }
+      try {
+        const res = await fetch('/api/diff/fresh');
+        if (!cancelled && res.ok) {
+          const data = (await res.json()) as { fresh: boolean; fingerprint?: string };
+          // Keep polling even while stale: a reverted edit flips back to
+          // fresh, and a FURTHER change updates the fingerprint so a
+          // dismissed notice can reappear.
+          setStaleFingerprint(data.fresh ? null : data.fingerprint ?? 'stale');
+        }
+      } catch {
+        // Transient/network/server-gone: ignore — staleness is best-effort.
+      }
+      schedule();
+    };
+
+    schedule();
+    return () => {
+      cancelled = true;
+      if (timer) clearTimeout(timer);
+    };
+  }, [enabled, resetKey]);
+
+  const dismiss = useCallback(() => {
+    setDismissedFingerprint(staleFingerprint);
+  }, [staleFingerprint]);
+
+  return {
+    isStale: staleFingerprint != null && staleFingerprint !== dismissedFingerprint,
+    dismiss,
+  };
+}

packages/server/review-workspace.ts

@@ -1,6 +1,7 @@
 import {
   canStageFiles,
   getVcsContext,
+  getVcsDiffFingerprint,
   getVcsFileContentsForDiff,
   runVcsDiff,
   stageFile,
@@ -35,6 +36,7 @@ const workspaceRuntime = {
   getVcsContext,
   runVcsDiff,
   getVcsFileContentsForDiff,
+  getVcsDiffFingerprint,
   canStageFiles,
   stageFile,
   unstageFile,