Fix Git ref refresh resource storms#4727

Reconnect refetch skips server refresh

Medium Severity

On each connection-generation refetch, makeCachedVcsRefsChanges calls vcs.listRefs with the subscribed input unchanged. Atoms that omit refresh: true (for example DiffPanel local/remote base-ref queries with refKind and includeMatchingRemoteRefs) now receive cached server snapshots for up to two minutes instead of a Git rescan. Removing the five-second poll makes out-of-band ref updates visible much later on those paths.

^{Reviewed by Cursor Bugbot for commit 8fb87fd77be389089c439e78bb82e25c66d843bc. Configure here.}

Current branch never marked

Medium Severity

current is set only when ref.worktreePath equals cached worktreeRoot. If git worktree list fails or rev-parse --show-toplevel once fails, worktreeRoot stays null and the worktree map is empty, so no ref is marked current even though the repo and branches are valid.

^{Reviewed by Cursor Bugbot for commit 8fb87fd77be389089c439e78bb82e25c66d843bc. Configure here.}

Fixed in f2449b5152. Repository path discovery now also captures symbolic-ref HEAD, and listRefs uses it only as a fallback when the worktree snapshot cannot identify the current branch. The normal worktree mapping still wins, and mutation invalidation refreshes the fallback branch state. A focused test forces both worktree metadata calls to fail and verifies the active branch remains marked current.

Ignored for-each-ref failures

High Severity

readGitRefsSnapshot parses refsResult.stdout without checking refsResult.exitCode or truncation, unlike the remote, default-ref, and worktree lookups. Because Git subprocess calls allow non-zero exits, a failed for-each-ref can produce an empty snapshot that listRefs still serves with isRepo: true and may cache for minutes.

^{Reviewed by Cursor Bugbot for commit 8fb87fd77be389089c439e78bb82e25c66d843bc. Configure here.}

Confirmed that executeGit already turns a non-zero exit into GitCommandError when allowNonZeroExit is omitted; the snapshot call does omit it. I made that contract explicit with a fallback error detail and added a regression test that forces for-each-ref to exit 128 and verifies listRefs fails with GitCommandError instead of caching an empty repository snapshot.

Backoff cleared on failed fetch

Medium Severity

refreshStatusRemoteCacheEntry clears the consecutive failure counter whenever fetchRemoteForStatus completes as a successful Effect, but that helper uses allowNonZeroExit, so a git fetch that exits with an error still runs clearStatusRemoteRefreshFailures. That resets exponential backoff after earlier spawn or timeout failures and stores a success TTL instead of backing off.

^{Reviewed by Cursor Bugbot for commit 501a7381787030d9adec0bd871f7966438e0e75d. Configure here.}

Fixed in f2449b5152. Background fetch no longer allows non-zero exits, so a failed git fetch is retained as a cache failure and advances the exponential cooldown instead of clearing it. The backoff test now exercises repeated non-zero child exits at 30s and 60s boundaries.

Stale refs after refresh failure

Medium Severity

The refs stream always emits persisted loadVcsRefs data first, including while connected. If the subsequent live vcsListRefs call fails, the stream emits nothing further, so branch-list atoms can keep showing outdated refs (wrong current branch or missing branches) until reconnect or cache expiry.

^{Reviewed by Cursor Bugbot for commit 501a7381787030d9adec0bd871f7966438e0e75d. Configure here.}

Fixed in f2449b5152. While connected, the client now retries a failed live ref refresh with capped exponential backoff instead of leaving persisted refs indefinitely. switchMap cancels the in-flight refresh and its retry timer on disconnect or generation change, and the server caches snapshot failures for 30s so retries cannot recreate a Git subprocess storm. Focused tests cover connected recovery and cancellation.

🟡 Medium vcs/GitVcsDriverCore.ts:236

parseWorktreeBranchPaths returns worktree paths without verifying they exist on disk. Git omits the prunable marker until its prune-expiry threshold elapses, so a worktree directory deleted manually still appears as a valid entry — the returned map points the branch at a nonexistent path. Downstream branch selection can then try to reuse that stale worktree instead of checking out the branch normally. The previous implementation explicitly stated each path, which dropped these entries. Consider re-statting each path before adding it to the map (or pruning stale worktrees first) so deleted directories are not treated as usable.

Fixed in 6caf60955e. Ref snapshots now stat every non-prunable worktree path with bounded concurrency and omit entries that no longer exist. The regression test supplies a stale porcelain entry for a deleted directory and verifies the branch is returned without a reusable worktree path.

Stale cached current branch

Medium Severity

listRefs rebuilds the shared ref snapshot when refresh is true, but it still marks current using repositoryPathsCache (currentBranch / worktreeRoot) with a ten-minute TTL. That cache is only cleared in invalidateListRefsSnapshot for the mutation’s cwd, so a fresh branch list can show the wrong current ref after checkout or rename until the cache expires.

^{Reviewed by Cursor Bugbot for commit f2449b5152a05b3fa0fd90b129935cd608381f9b. Configure here.}

Fixed in 6caf60955e. Explicit ref refreshes now also refresh repository identity through a five-second singleflight cache, keeping current-branch data fresh without multiplying Git subprocesses during concurrent refreshes. The regression test performs a raw external checkout and verifies the refreshed list moves the current marker.

Pull leaves ref lists stale

Medium Severity

Replacing the five-second ref polling with one live vcsListRefs per connection generation means branch-list atoms stop updating unless something explicitly refreshes them. Server-side pull still invalidates ref snapshots, but pull success handlers only refresh git status, so branch pickers can show outdated refs (including remotes) until reconnect or a manual branch refresh.

^{Reviewed by Cursor Bugbot for commit 45ac080cc4eef3a08b13bc6b7f079116974dc2cf. Configure here.}

Fixed in 2a9d07ea73: successful ref-mutating commands now bump a repository-scoped invalidation atom. Every mounted ref query for that environment/cwd depends on that revision, so pull/create/switch/worktree/init refresh once without restoring polling, while the persisted result keeps selectors populated during revalidation. Added focused invalidation coverage.

Ref invalidation misses list cwd

Medium Severity

invalidateRefs bumps a revision keyed only by the mutation RPC’s input.cwd, while listRefs atoms depend on the same key using each query’s input.cwd. Linked worktrees often use different paths for mutations versus branch lists, so successful pulls and checkouts can leave active ref streams stale until idle TTL, reconnect, or a manual refresh.

^{Reviewed by Cursor Bugbot for commit 2a9d07ea73a787280ddc661f26e832c867ca58cd. Configure here.}

Fixed in dfc1459eec: mutation invalidation is now environment-scoped, so every mounted ref stream in that environment revalidates once regardless of which linked-worktree cwd issued the command. Other environments remain isolated, covered by the focused regression.

Stacked commits skip ref invalidation

High Severity

The new mutation-driven invalidation for VCS listRefs atoms is incomplete. gitRunStackedAction and publishRepository don't trigger invalidateRefs on success, leading to stale branch lists and remote status. Additionally, listRefs atoms with filtered inputs may not refresh repository identity or snapshots from the server on reconnect, causing current-branch metadata to lag.

^{Reviewed by Cursor Bugbot for commit dfc1459eec125c057291b04910c3a44cbdf9b6ed. Configure here.}

Fixed in 561c035782. Ref invalidation now uses one module-scoped environment revision shared by the VCS, stacked-action, and source-control atom factories. Successful gitRunStackedAction and publishRepository commands both increment it, with direct command-level regression tests. Connected/reconnected list requests also force refresh: true, including filtered requests, so repository identity and snapshots are refreshed before applying query/pagination filters.

Failed stacked actions skip ref invalidation

Medium Severity

runStackedAction bumps the environment ref revision only when the stacked-action stream completes successfully. If Git already applied an earlier phase (such as creating a feature branch) and a later phase ends in action_failed, the client keeps serving cached ref streams with no reconnect and no periodic polling, so new branches can stay missing while the session remains connected.

^{Reviewed by Cursor Bugbot for commit 561c035782fce4bbd1901f8213f4cc6f8393d43b. Configure here.}

Fixed in 4f3a66092b. Stacked-action ref invalidation now runs in Effect.ensuring, so success, failure after a mutating phase, and interruption all clear persisted refs and advance the live ref revision. The focused test now covers both the completed and action_failed terminal paths.

Stale persisted refs after invalidation

Medium Severity

After a successful ref mutation bumps vcsRefsRevisionAtom, remounted ref streams still emit the on-disk loadVcsRefs snapshot before the live refresh completes. That snapshot was saved from the pre-mutation fetch, so branch UI can briefly revert to outdated refs right after create, switch, or pull succeeds.

^{Reviewed by Cursor Bugbot for commit 561c035782fce4bbd1901f8213f4cc6f8393d43b. Configure here.}

Fixed in 4f3a66092b. Ref invalidation now removes the persisted (environmentId, cwd) snapshot before incrementing the revision that restarts the live stream, so a remount during the refresh window cannot replay stale branch data. The web and mobile cache adapters both implement the removal operation, with focused persistence and invalidation tests.

🟡 Medium state/vcs.ts:154

invalidateRefs only deletes the persisted cache entry for the cwd of the worktree that performed the mutation, even though Git refs are shared across all linked worktrees. When a command mutates refs in worktree A while worktree B's atom is idle, B's persisted entry survives; remounting B later replays the stale branch list before its live refresh completes. The revision bump restarts only currently retained atoms but does not remove persisted entries stored under other worktree paths. Invalidation should remove all cache keys for the repository, or persistence should key them by a shared repository identity rather than per-cwd.

Fixed in ff4df7fe63. Ref invalidation now clears the entire persisted VCS-ref cache namespace for the environment, so linked worktrees cannot replay stale entries, while unrelated thread/shell/settings caches are preserved. Added mobile persistence coverage for two worktree keys plus another environment; focused tests and web/mobile/client-runtime typechecks pass.

Cross-worktree stale persisted refs

Medium Severity

The invalidateCachedVcsRefs function clears the persisted VCS ref cache only for the specific cwd it's called with. Because it triggers an environment-wide revision bump, other linked worktrees in the same environment can briefly display stale branch data from their local cache until live data loads.

^{Reviewed by Cursor Bugbot for commit 4f3a66092b7edf4f27fc45a24ad79fbb501d7a3f. Configure here.}

Late refresh repersists stale refs

Medium Severity

An in-flight vcsListRefs refresh can finish after a ref mutation runs clearVcsRefs and bumps the environment revision. refresh always calls saveVcsRefs with whatever the RPC returns, without tying the write to the current revision or cancelling superseded requests, so a pre-mutation snapshot can be written back to persistence and replayed on remount.

^{Reviewed by Cursor Bugbot for commit ff4df7fe6374103df56fa648a4a8584a3af54b4c. Configure here.}

Fixed in 4ba5ea3a5d. Each refresh now captures the environment ref revision, and its result is committed/emitted only while holding the same per-environment lock used by invalidation. Invalidation advances the revision and clears persisted refs under that lock, so either a prior save is subsequently cleared or a late result observes the new revision and is discarded. Added regression coverage for stale rejection and current-generation persistence; focused tests plus client-runtime/web/mobile typechecks pass.

🟡 Medium state/vcsRefInvalidation.ts:53

invalidateCachedVcsRefs bumps the revision atom before cache.clearVcsRefs finishes, so active ref streams restart synchronously, call loadVcsRefs outside the lock, and emit the stale persisted snapshot before it is deleted. After a successful Git mutation, users can temporarily be shown the pre-mutation branch list. Swap the order so the cache is cleared before the revision is published — the surrounding persistence lock already prevents stale refresh writes.

Fixed in 25c0c7abc8. Invalidation now clears the persisted environment-wide ref namespace while holding the shared persistence lock, and only then publishes the new revision that restarts active streams. The regression test records the revision observed by and verifies it remains at the old generation until clearing completes.

Correction: fixed in 25c0c7abc8. Invalidation now clears the persisted environment-wide ref namespace while holding the shared persistence lock, and only then publishes the new revision that restarts active streams. The regression test records the revision observed by clearVcsRefs and verifies it remains at the old generation until clearing completes.

🟡 Medium vcs/GitVcsDriverCore.ts:246

parseWorktreeBranchPaths splits git worktree list --porcelain output on \n, but worktree paths can legally contain newline characters. A worktree whose path contains a newline is split into multiple pseudo-lines, causing currentPath to be overwritten or misparsed, and the branch is dropped from worktreePaths. The caller then incorrectly reports worktreePath: null for that checked-out branch. Git's porcelain format requires parsing NUL-delimited (-z) output to handle paths with embedded newlines. Consider invoking the command with -z and parsing NUL-delimited records instead of splitting on \n.

Fixed in 7fa76c88e2. Worktree enumeration now requests git worktree list --porcelain -z and parses NUL-delimited fields/records, preserving embedded newlines. A backend integration test creates a real newline-containing worktree path and verifies the listed branch retains its canonical path.

🟡 Medium

https://github.com/pingdotgg/t3code/blob/25c0c7abc81393ea9f52fb054823b928589327ba/packages/client-runtime/src/state/vcs.ts#L251-L256

pull only invalidates cached VCS refs in onSuccess, so a git pull that fetches new remote-tracking refs but then fails during merge/rebase leaves stale cached refs. The RPC reports failure, so onSuccess never fires, yet the remote refs have already changed — branch pickers keep showing the pre-pull snapshot until reconnect or another mutation. Consider invalidating on both success and failure (e.g. via Effect.tapBoth), or invalidating before the RPC so the next ref stream always re-fetches.

Fixed in 7fa76c88e2. The shared RPC command helper now supports an onSettled hook, and pull uses it to clear persisted refs and publish a new ref generation on success or failure. The focused client regression test forces pull to fail and verifies both cache clearing and the revision bump.

Coalesced refresh ignores invalidation

Medium Severity

A listRefs refresh singleflight started before a mutating command can still finish and satisfy waiters after invalidateListRefsSnapshot runs. Those callers may receive a snapshot taken before the mutation, so branch lists and current-branch markers stay wrong until another explicit refresh.

^{Reviewed by Cursor Bugbot for commit 25c0c7abc81393ea9f52fb054823b928589327ba. Configure here.}

Fixed in 5a352e1a3a. Server ref-snapshot refreshes now carry a monotonic per-repository generation. Invalidation advances both generation and snapshot epoch before yielding; any older in-flight result detects the mismatch and retries through a generation-keyed single-flight, so it cannot commit stale data after the mutation. A deterministic backend regression test pauses the first snapshot after its ref scan, mutates refs, resumes it, and verifies the waiter retries and sees the new branch.

Clear failure still rehydrates stale cache

Medium Severity

When clearVcsRefs fails, invalidation still bumps the ref revision and restarts live streams. makeCachedVcsRefsChanges emits whatever loadVcsRefs returns first, so a failed clear can replay pre-mutation branch snapshots until a live refresh succeeds—especially misleading offline or on slow connections.

^{Reviewed by Cursor Bugbot for commit 5a352e1a3aa4a04b69f4169af4fa3b4c5d48bb07. Configure here.}

Fixed in b3f2a38da2. Ref cache state now atomically tracks both revision and whether persisted snapshots are readable. A failed environment-wide clear publishes a new generation with persisted reads disabled, so restarted/offline streams cannot replay stale data; live refreshes can still repopulate storage. The regression test forces clear failure and verifies no persisted load occurs.

Failed mutations skip ref invalidation

High Severity

Several mutating RPCs clear persisted ref snapshots only via onSuccess, while pull uses onSettled. If Git already changed (for example publishRepository adds a remote then push fails), the RPC error skips cache clearing and revision bump, so mounted ref streams keep serving stale branch data until reconnect because background polling was removed.

^{Reviewed by Cursor Bugbot for commit 5a352e1a3aa4a04b69f4169af4fa3b4c5d48bb07. Configure here.}

🟡 Medium state/vcsRefInvalidation.ts:39

invalidateVcsRefs makes persistedCacheReadable sticky: once cache.clearVcsRefs fails and sets it to false, nothing in invalidateCachedVcsRefs or ordinary revision-gated refreshes ever restores it to true. After a one-time persistence deletion error, later atom instances keep skipping the offline cache — which may contain fresh data written by a subsequent successful refresh — until another VCS mutation happens to clear successfully. A single clearVcsRefs failure thus disables offline branch data indefinitely. The persistedCacheReadable: false state should be transient, scoped to the current cache generation, so a successful refresh clears it.

Fixed in 70b295c2b0. The fail-closed state is retained across UI unmounts, and an unfiltered live refresh now retries the environment-wide clear under the shared persistence lock. Only after that cleanup succeeds does it save the fresh snapshot and re-enable persisted reads; failed retries remain fail-closed. The regression test covers clear failure, unmounted/offline suppression, successful live recovery, and subsequent offline rehydration of the fresh snapshot.

Refresh status skips ref invalidation

Medium Severity

refreshStatus is not wired to invalidateCachedVcsRefs, unlike other VCS mutations in this change. After a status refresh updates remote refs on the server, the client still serves the old persisted branch snapshot and does not run another live listRefs until the connection generation changes, so branch UI can stay wrong for a long-lived session.

^{Reviewed by Cursor Bugbot for commit 70b295c2b06f73a10c9e32805da4616898a679f7. Configure here.}

Fixed in f948f0a634. refreshStatus now uses the same settlement invalidation as every other ref-affecting command, covering server-side remote refresh even when the operation fails after partial Git changes. The command-level regression test now verifies both failed pull and successful status refresh clear persistence and advance the ref generation.

🟡 Medium state/paginatedBranches.ts:31

shouldLoadNextBranchPageAfterScroll never loads the next page during slow or smooth scrolling. The guard scrollTop <= previousScrollTop + 1 treats any downward movement of 1px or less as "not scrolling down," so successive subpixel or 1px scroll events are all rejected — even when the user reaches the bottom, fetchNextBranchPage is never called. Because scrollTop is subpixel-precise on modern browsers/trackpads, this is a common case, not an edge case. The direction check should reject only non-increasing movement (scrollTop <= previousScrollTop), not deltas <= 1.

Fixed in 6deb060e97. The direction guard now rejects only non-increasing positions, so 1px and subpixel trackpad movement can trigger the next page at the threshold. The focused regression test covers a 0.5px downward movement at the boundary.

Branch pages stuck without scroll

High Severity

Branch pagination now loads the next page only when shouldLoadNextBranchPageAfterScroll sees a strictly increasing scrollTop, and the branch picker no longer triggers loads from layout, list growth, or onEndReached. When the first page fits the list viewport (scrollHeight equals clientHeight), there is no downward scroll to satisfy the guard, so hasNextPage stays true but additional refs never load.

^{Reviewed by Cursor Bugbot for commit 2c4c29ca4c1909ff5610c175714d3830e647bf34. Configure here.}

Not applicable for this picker. The web query fixes the page size at 100 (VCS_REF_LIST_LIMIT), while paginateBranches only returns a non-null nextCursor when more refs exist after refs.slice(cursor, cursor + limit). Therefore any first page with hasNextPage contains exactly 100 refs. The picker viewport is capped at 14rem (about 8 rows), and the unfiltered client path does not remove page items; filtered search is applied server-side before the same pagination. A hasNextPage page cannot fit this viewport, so a real downward scroll is always possible. Reintroducing mount/layout pagination here would recreate the user-reproduced self-feeding 100→200→300 ref storm.