fix(git): make post-mutation status refresh authoritative (#2740)

fix(git): make post-mutation status refresh authoritative

packages/ui/src/lib/gitApiHttp.test.ts

@@ -1,10 +1,30 @@
 import { describe, expect, test } from 'bun:test';
 import {
+  abortMerge,
+  abortRebase,
+  applyGitStash,
+  checkoutBranch,
+  checkoutCommit,
+  cherryPick,
+  continueMerge,
+  continueRebase,
+  createBranch,
+  deleteGitBranch,
+  deleteRemoteBranch,
+  dropGitStash,
   getGitBranches,
   getGitStatus,
   gitFetch,
+  merge,
+  popGitStash,
+  rebase,
+  removeRemote,
+  renameBranch,
+  resetToCommit,
+  revertCommit,
   stageGitFile,
   stageGitFiles,
+  stashGitChanges,
   unstageGitFile,
   unstageGitFiles,
 } from './gitApiHttp';
@@ -169,6 +189,200 @@ describe('gitApiHttp status cache', () => {
   });
 });
 
+const statusPayload = (overrides: Record<string, unknown> = {}) => ({
+  current: 'main',
+  tracking: null,
+  ahead: 0,
+  behind: 0,
+  files: [],
+  isClean: true,
+  ...overrides,
+});
+
+const jsonResponse = (payload: unknown) => new Response(JSON.stringify(payload), {
+  status: 200,
+  headers: { 'Content-Type': 'application/json' },
+});
+
+const installStatusMutationFetchMock = () => {
+  const mock = {
+    statusUrls: [] as string[],
+    behind: 0,
+  };
+  globalThis.fetch = (async (input) => {
+    const url = String(input);
+    if (url.startsWith('/api/git/status')) {
+      mock.statusUrls.push(url);
+      return jsonResponse(statusPayload({ behind: mock.behind }));
+    }
+    return jsonResponse({ success: true });
+  }) as typeof fetch;
+  return mock;
+};
+
+/**
+ * Seeds the status cache, performs the mutation, and asserts the next status
+ * read issues a fresh request that observes the post-mutation state instead of
+ * serving the pre-mutation cache entry.
+ */
+const expectStatusInvalidatedBy = async (
+  directory: string,
+  mutate: () => Promise<unknown>
+): Promise<void> => {
+  const mock = installStatusMutationFetchMock();
+
+  const seeded = await getGitStatus(directory);
+  expect(seeded.behind).toBe(0);
+
+  mock.behind = 2;
+  const cached = await getGitStatus(directory);
+  expect(cached.behind).toBe(0);
+  expect(mock.statusUrls).toHaveLength(1);
+
+  await mutate();
+
+  const refreshed = await getGitStatus(directory);
+  expect(refreshed.behind).toBe(2);
+  expect(mock.statusUrls).toHaveLength(2);
+};
+
+describe('gitApiHttp post-mutation status invalidation (#2281)', () => {
+  test('checkout and branch mutations invalidate cached status', async () => {
+    installWindowMock();
+    try {
+      await expectStatusInvalidatedBy('/repo-2281-checkout', () => checkoutBranch('/repo-2281-checkout', 'feature'));
+      await expectStatusInvalidatedBy('/repo-2281-create-branch', () => createBranch('/repo-2281-create-branch', 'feature/new'));
+      await expectStatusInvalidatedBy('/repo-2281-rename-branch', () => renameBranch('/repo-2281-rename-branch', 'old', 'new'));
+      await expectStatusInvalidatedBy('/repo-2281-delete-branch', () => deleteGitBranch('/repo-2281-delete-branch', { branch: 'feature/old' }));
+    } finally {
+      restoreMocks();
+    }
+  });
+
+  test('stash lifecycle mutations invalidate cached status', async () => {
+    installWindowMock();
+    try {
+      await expectStatusInvalidatedBy('/repo-2281-stash', () => stashGitChanges('/repo-2281-stash', { message: 'WIP' }));
+      await expectStatusInvalidatedBy('/repo-2281-stash-apply', () => applyGitStash('/repo-2281-stash-apply', { ref: 'stash@{0}' }));
+      await expectStatusInvalidatedBy('/repo-2281-stash-pop', () => popGitStash('/repo-2281-stash-pop', { ref: 'stash@{0}' }));
+      await expectStatusInvalidatedBy('/repo-2281-stash-drop', () => dropGitStash('/repo-2281-stash-drop', { ref: 'stash@{0}' }));
+    } finally {
+      restoreMocks();
+    }
+  });
+
+  test('merge and rebase lifecycle mutations invalidate cached status', async () => {
+    installWindowMock();
+    try {
+      await expectStatusInvalidatedBy('/repo-2281-merge', () => merge('/repo-2281-merge', { branch: 'feature' }));
+      await expectStatusInvalidatedBy('/repo-2281-merge-abort', () => abortMerge('/repo-2281-merge-abort'));
+      await expectStatusInvalidatedBy('/repo-2281-merge-continue', () => continueMerge('/repo-2281-merge-continue'));
+      await expectStatusInvalidatedBy('/repo-2281-rebase', () => rebase('/repo-2281-rebase', { onto: 'main' }));
+      await expectStatusInvalidatedBy('/repo-2281-rebase-abort', () => abortRebase('/repo-2281-rebase-abort'));
+      await expectStatusInvalidatedBy('/repo-2281-rebase-continue', () => continueRebase('/repo-2281-rebase-continue'));
+    } finally {
+      restoreMocks();
+    }
+  });
+
+  test('history mutations invalidate cached status', async () => {
+    installWindowMock();
+    try {
+      await expectStatusInvalidatedBy('/repo-2281-checkout-commit', () => checkoutCommit('/repo-2281-checkout-commit', 'abc123'));
+      await expectStatusInvalidatedBy('/repo-2281-cherry-pick', () => cherryPick('/repo-2281-cherry-pick', 'abc123'));
+      await expectStatusInvalidatedBy('/repo-2281-revert-commit', () => revertCommit('/repo-2281-revert-commit', 'abc123'));
+      await expectStatusInvalidatedBy('/repo-2281-reset', () => resetToCommit('/repo-2281-reset', 'abc123', 'mixed'));
+    } finally {
+      restoreMocks();
+    }
+  });
+
+  test('remote-side mutations invalidate cached status', async () => {
+    installWindowMock();
+    try {
+      await expectStatusInvalidatedBy('/repo-2281-delete-remote-branch', () => deleteRemoteBranch('/repo-2281-delete-remote-branch', { branch: 'feature', remote: 'origin' }));
+      await expectStatusInvalidatedBy('/repo-2281-remove-remote', () => removeRemote('/repo-2281-remove-remote', { remote: 'origin' }));
+    } finally {
+      restoreMocks();
+    }
+  });
+
+  test('a failed mutation does not invalidate cached status', async () => {
+    installWindowMock();
+    const statusUrls: string[] = [];
+    globalThis.fetch = (async (input) => {
+      const url = String(input);
+      if (url.startsWith('/api/git/status')) {
+        statusUrls.push(url);
+        return jsonResponse(statusPayload());
+      }
+      return new Response(JSON.stringify({ error: 'checkout failed' }), {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }) as typeof fetch;
+
+    try {
+      const directory = '/repo-2281-failed-checkout';
+      await getGitStatus(directory);
+
+      const error = await captureError(async () => {
+        await checkoutBranch(directory, 'feature');
+      });
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toBe('checkout failed');
+
+      await getGitStatus(directory);
+      expect(statusUrls).toHaveLength(1);
+    } finally {
+      restoreMocks();
+    }
+  });
+
+  test('a status request admitted before a mutation cannot satisfy the post-mutation refresh', async () => {
+    installWindowMock();
+    const statusResolvers: Array<(response: Response) => void> = [];
+    const statusUrls: string[] = [];
+    globalThis.fetch = (async (input) => {
+      const url = String(input);
+      if (url.startsWith('/api/git/status')) {
+        statusUrls.push(url);
+        return new Promise<Response>((resolve) => {
+          statusResolvers.push(resolve);
+        });
+      }
+      return jsonResponse({ success: true });
+    }) as typeof fetch;
+
+    try {
+      const directory = '/repo-2281-deferred';
+      const preMutationRead = getGitStatus(directory);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      expect(statusUrls).toHaveLength(1);
+
+      await checkoutBranch(directory, 'feature');
+
+      const postMutationRead = getGitStatus(directory);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      expect(statusUrls).toHaveLength(2);
+
+      statusResolvers[1](jsonResponse(statusPayload({ current: 'feature' })));
+      statusResolvers[0](jsonResponse(statusPayload({ current: 'main' })));
+
+      const [preMutationStatus, postMutationStatus] = await Promise.all([preMutationRead, postMutationRead]);
+      expect(preMutationStatus.current).toBe('main');
+      expect(postMutationStatus.current).toBe('feature');
+
+      // The late pre-mutation response must not repopulate the cache.
+      const cachedRead = await getGitStatus(directory);
+      expect(cachedRead.current).toBe('feature');
+      expect(statusUrls).toHaveLength(2);
+    } finally {
+      restoreMocks();
+    }
+  });
+});
+
 describe('gitApiHttp request priority', () => {
   test('leaves low-level reads outside the background policy', async () => {
     installWindowMock();

packages/ui/src/lib/gitApiHttp.ts

@@ -38,6 +38,7 @@ import type {
 import { runtimeFetch } from './runtime-fetch';
 import { getRuntimeUrlResolver } from './runtime-url';
 import { getRuntimeKey } from './runtime-switch';
+import { notifyGitStatusInvalidated } from './gitStatusInvalidation';
 
 const API_BASE = '/api/git';
 const GIT_STATUS_CACHE_TTL_MS = 1200;
@@ -66,6 +67,16 @@ const invalidateGitStatusCache = (directory: string): void => {
     gitStatusCache.delete(statusKey);
     gitStatusInFlight.delete(statusKey);
   }
+  notifyGitStatusInvalidated(directory);
+};
+
+// Shared success path for status-affecting mutations. The payload is parsed
+// before invalidating so a failed mutation (non-ok response handled by the
+// caller, or a malformed body) cannot publish a false state change.
+const completeStatusMutation = async <T>(directory: string, response: Response): Promise<T> => {
+  const result = await response.json() as T;
+  invalidateGitStatusCache(directory);
+  return result;
 };
 
 function buildUrl(
@@ -464,7 +475,7 @@ export async function deleteGitBranch(directory: string, payload: GitDeleteBranc
     throw new Error(error.error || 'Failed to delete branch');
   }
 
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function deleteRemoteBranch(directory: string, payload: GitDeleteRemoteBranchPayload): Promise<{ success: boolean }> {
@@ -483,7 +494,7 @@ export async function deleteRemoteBranch(directory: string, payload: GitDeleteRe
     throw new Error(error.error || 'Failed to delete remote branch');
   }
 
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function removeRemote(directory: string, payload: GitRemoveRemotePayload): Promise<{ success: boolean }> {
@@ -503,7 +514,7 @@ export async function removeRemote(directory: string, payload: GitRemoveRemotePa
     throw new Error(error.error || 'Failed to remove remote');
   }
 
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function generateCommitMessage(
@@ -710,9 +721,7 @@ export async function createGitCommit(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to create commit');
   }
-  const result = await response.json();
-  invalidateGitStatusCache(directory);
-  return result;
+  return completeStatusMutation(directory, response);
 }
 
 export async function gitPush(
@@ -728,9 +737,7 @@ export async function gitPush(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to push');
   }
-  const result = await response.json();
-  invalidateGitStatusCache(directory);
-  return result;
+  return completeStatusMutation(directory, response);
 }
 
 export async function gitPull(
@@ -746,9 +753,7 @@ export async function gitPull(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to pull');
   }
-  const result = await response.json();
-  invalidateGitStatusCache(directory);
-  return result;
+  return completeStatusMutation(directory, response);
 }
 
 export async function gitFetch(
@@ -764,9 +769,7 @@ export async function gitFetch(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to fetch');
   }
-  const result = await response.json();
-  invalidateGitStatusCache(directory);
-  return result;
+  return completeStatusMutation(directory, response);
 }
 
 export async function listGitStashes(directory: string): Promise<{ stashes: GitStashEntry[] }> {
@@ -801,7 +804,7 @@ export async function stashGitChanges(directory: string, options: { message?: st
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to stash changes');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 const postStashRef = async (directory: string, path: string, options: { ref: string }): Promise<{ success: boolean; ref: string }> => {
@@ -814,7 +817,7 @@ const postStashRef = async (directory: string, path: string, options: { ref: str
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || `Failed to ${path}`);
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 };
 
 export const applyGitStash = (directory: string, options: { ref: string }) => postStashRef(directory, 'stash/apply', options);
@@ -831,7 +834,7 @@ export async function checkoutBranch(directory: string, branch: string): Promise
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to checkout branch');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function createBranch(
@@ -848,7 +851,7 @@ export async function createBranch(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to create branch');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function renameBranch(
@@ -865,7 +868,7 @@ export async function renameBranch(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to rename branch');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function getGitLog(
@@ -1068,7 +1071,7 @@ export async function rebase(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to rebase');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function abortRebase(directory: string): Promise<{ success: boolean }> {
@@ -1079,7 +1082,7 @@ export async function abortRebase(directory: string): Promise<{ success: boolean
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to abort rebase');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function merge(
@@ -1095,7 +1098,7 @@ export async function merge(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to merge');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function checkoutCommit(
@@ -1111,7 +1114,7 @@ export async function checkoutCommit(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to checkout commit');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function cherryPick(
@@ -1127,7 +1130,7 @@ export async function cherryPick(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to cherry-pick');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function revertCommit(
@@ -1143,7 +1146,7 @@ export async function revertCommit(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to revert commit');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function resetToCommit(
@@ -1161,7 +1164,7 @@ export async function resetToCommit(
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to reset');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function abortMerge(directory: string): Promise<{ success: boolean }> {
@@ -1172,7 +1175,7 @@ export async function abortMerge(directory: string): Promise<{ success: boolean
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to abort merge');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function continueRebase(directory: string): Promise<{ success: boolean; conflict: boolean; conflictFiles?: string[] }> {
@@ -1183,7 +1186,7 @@ export async function continueRebase(directory: string): Promise<{ success: bool
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to continue rebase');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function continueMerge(directory: string): Promise<{ success: boolean; conflict: boolean; conflictFiles?: string[] }> {
@@ -1194,7 +1197,7 @@ export async function continueMerge(directory: string): Promise<{ success: boole
     const error = await response.json().catch(() => ({ error: response.statusText }));
     throw new Error(error.error || 'Failed to continue merge');
   }
-  return response.json();
+  return completeStatusMutation(directory, response);
 }
 
 export async function stash(

packages/ui/src/lib/gitStatusInvalidation.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal notification channel for git status invalidation.
+ *
+ * A runtime adapter that caches git status (currently only the HTTP adapter in
+ * `gitApiHttp.ts`) must call `notifyGitStatusInvalidated` whenever a successful
+ * status-affecting mutation invalidates its cache. `useGitStore` subscribes and
+ * bumps its per-directory status mutation revision so an immediate refresh
+ * cannot join an in-flight status request admitted before the mutation, and a
+ * stale response cannot commit over newer authoritative state.
+ *
+ * Runtime parity: the VS Code bridge adapter performs no client-side status
+ * caching (every `getGitStatus` is a fresh bridge request), so it has no cache
+ * to invalidate and does not emit this signal today. Any adapter that adds
+ * caching must emit on invalidation.
+ */
+
+type GitStatusInvalidationListener = (directory: string) => void;
+
+const listeners = new Set<GitStatusInvalidationListener>();
+
+export const subscribeGitStatusInvalidations = (
+  listener: GitStatusInvalidationListener
+): (() => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+export const notifyGitStatusInvalidated = (directory: string): void => {
+  for (const listener of listeners) {
+    listener(directory);
+  }
+};