Fix Git ref refresh resource storms

[juliusmarminge]

What changed

• remove the five-second client-side ref polling loop and refresh once per connection generation
• expire idle ref atoms after 30 seconds
• key repository/ref snapshots by the common Git directory
• coalesce duplicate refreshes, single-flight full scans, and bound Git subprocess concurrency
• replace separate local/remote ref enumeration with one for-each-ref call
• invalidate cached snapshots after ref mutations

Root cause

Each retained vcs.listRefs atom polled independently. On this repository that multiplied 31 concurrent requests into repeated full scans across 838 worktrees and roughly 16,700 refs. The server had no shared snapshot, single-flight guard, or concurrency bound, so identical requests launched many expensive git branch, git worktree list, and ref-enumeration processes at once.

Impact

Ref lists remain fresh on connection changes and explicit refreshes, while background idle work no longer creates a Git subprocess storm. Mutations still invalidate snapshots immediately.

Verification

• 34 focused client/server tests
• targeted formatting, lint, and affected-package typechecks
• integrated web verification: at most two expensive Git children and one worktree scan
• integrated mobile idle verification: zero expensive Git samples across 60 settled samples

Co-authored-by: codex codex@users.noreply.github.com

Note

Fix Git ref refresh resource storms with coalesced snapshots, exponential backoff, and invalidation hooks

• Replaces periodic polling for VCS refs with a single refresh per connection generation, retried on failure using exponential backoff (1s base, 30s cap), and a 30s idle TTL instead of 5 minutes.
• Adds a coalesced, cached listRefs snapshot in GitVcsDriverCore so concurrent paginated calls share one underlying for-each-ref scan, with generation tracking to prevent stale cache reuse.
• Invalidates cached VCS refs (both in-memory and persisted) after any ref-affecting mutation (pull, push, createRef, switchRef, worktree ops, publish, etc.) on both success and failure via new onSettled hooks on RPC commands.
• Adds removeVcsRefs and clearVcsRefs to EnvironmentCacheStore (web IndexedDB, mobile SQLite) and a per-environment persistence lock to serialize cache mutations.
• Fixes branch list pagination in BranchToolbarBranchSelector to only trigger next-page loads on downward scroll past a threshold, not on layout or array length changes.
• Risk: Idle list-refs atoms now expire after 30s instead of 5 minutes, causing more frequent re-fetches when the atom is re-subscribed after a period of inactivity.

^{Macroscope summarized 2c4c29c.}

---

Note

Medium Risk
Large changes to GitVcsDriverCore caching, invalidation, and client ref streams affect branch lists and worktree-heavy repos; behavior is heavily tested but touches core VCS paths.

Overview
Stops Git ref refresh from spawning subprocess storms by replacing per-atom 5s polling with one refresh per connection generation (exponential retry, 30s idle atom TTL) and a server-side coalesced snapshot keyed by common Git dir (for-each-ref + worktree metadata instead of separate branch listings).

Invalidation: VCS mutations (pull, worktree, create/switch ref, publish, stacked actions) clear persisted vcs-refs via new clearVcsRefs / removeVcsRefs on web and mobile stores, bump a per-environment revision, and invalidate server snapshots after Git-changing RPCs; listRefs accepts optional refresh: true (e.g. PR local branch lookup).

UI: Branch picker pagination loads the next page only on downward scroll near the bottom, with a dedicated isFetchingNextPage flag so background refreshes are not shown as “loading more.”

^{Reviewed by Cursor Bugbot for commit 2c4c29c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bf4cae2f-84f1-4725-a1b6-03f7acf28615

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/git-ref-refresh-resource-storm

---

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces substantial new caching infrastructure for Git ref operations, including multi-layer caches with TTL management, coalescing of concurrent requests, environment-wide invalidation on mutations, and exponential backoff for failures. The complexity of the new state management and fundamental changes to ref fetching behavior warrant human review.

No code changes detected at 2c4c29c. Prior analysis still applies.

^{You can customize Macroscope's approvability policy. Learn more.}