perf(list): cache ahead/behind counts SHA-keyed; skip the for-each-ref walk on warm runs

[max-sixty]

Summary

wt list --branches computed branch ahead/behind counts with one git for-each-ref --format='%(ahead-behind:BASE)' walk, on every invocation, in the post-skeleton setup scope. That walk is O(commits) — ~1.5s on rust-lang/rust — and it runs serially before the parallel task pool opens, because the per-branch tasks consume its result. So on a large real repo roughly 40% of wt list's wall time was a single-threaded git graph walk that thread count couldn't help with (a follow-up from the picker thread-count investigation in #2683/#2685).

Ahead/behind for (base, branch) is a pure function of the two commit SHAs — content-addressed, never stale — exactly the shape of the existing .git/wt/cache/ SHA-keyed caches. This adds an ahead-behind/ cache kind and rewires the population path:

• New ahead-behind/{base_sha}-{head_sha}.json kind in sha_cache.rs, identical machinery to is-ancestor / diff-stats (LRU-bounded, cleared by wt config state clear, wiped by the bench cache-invalidator).
• Repository::ahead_behind_by_sha is now cache-backed: check → compute_ahead_behind → write.
• RefSnapshot::capture_refs_with_ahead_behind builds the snapshot's ahead/behind map from the cache and only walks the graph for the branches the cache doesn't cover:
  • a few misses → left out of the snapshot map; the per-branch AheadBehindTask recomputes (and caches) them by SHA in the parallel pool. (That task already runs merge_base_by_sha for its orphan check, so the merge-base compute_ahead_behind needs is already primed — the fallback is just two cheap rev-list --count calls.)
  • everything cold (fresh repo / after wt config state clear) → one unscoped for-each-ref %(ahead-behind:BASE_SHA) refs/heads/ walk — a single shared traversal finds every merge-base — then results written to the cache.
  • many cold but not all → one for-each-ref %(ahead-behind:BASE_SHA) scoped to just the missed refnames (git for-each-ref takes a ref list, so it's still one shared traversal, only over the cold subset), results written to the cache.

The few-vs-many threshold (AHEAD_BEHIND_SCOPED_BATCH_MIN_MISSES) trades the per-pair path's parallelism (it runs in the pool) against the batch's lower total work (one shared base-history traversal); a batch here is serial, so it's only worth it once "many" misses make the amortization clear.

Cache-correctness details (Codex-prompted)

A few sharp edges, surfaced by /review-codex, that the seeding path now handles explicitly:

• %(ahead-behind) computed against the resolved SHA, not the refname. A tag named main shadows the branch in git's ref resolution; passing base_sha to the batch makes it inert to that. The fallback path (default branch isn't a local/remote-tracking ref) still passes the refname and caches nothing.
• Cache key from the batch's %(objectname), not a separately-scanned value. If a refs/heads/X moved between scan_locals and the batch (a sub-ms window, but possible), the counts are for the new SHA — and the cache now stores them under that SHA, not under the staler b.commit_sha.
• Orphan branches normalized to (0, 0) before writing. Git's %(ahead-behind:BASE) for an orphan (no common ancestor) prints the two disjoint history sizes; compute_ahead_behind returns (0, 0) and signals orphan-ness separately. An orphan's behind count equals base's total commit count, so one git rev-list --count base_sha on the seeding path detects them. The cache invariant — cache hit equals what a miss would recompute — holds for orphans now.
• Bulk-write avoids O(N · dir_size) on the seeding path. write_with_lru scans the cache directory on every call to enforce the LRU bound; the serial setup-scope seeding loop calls it N times. put_ahead_behind_bulk writes all N entries first and sweeps once at the end.

Net effect

	before	after
warm wt list on a large repo	~1.5s serial for-each-ref %(ahead-behind) in the setup scope	N small cache reads; no graph walk; no serial blocker
wt list after committing on one branch	full ~1.5s walk again (batch op — any change re-walks all)	only that branch recomputed (two cheap rev-list --count, in the pool); the rest stay cached
many branches moved since last list	full walk	one for-each-ref %(ahead-behind) scoped to just the moved ones
cold (fresh repo / after state clear)	one combined walk	unchanged — one combined walk + one bulk cache seed
skeleton time (WORKTRUNK_SKELETON_ONLY)	—	unaffected (returns before the scope this touches)

No user-facing behavior change — same numbers, same columns. The picker (wt switch) shares this path, so its preview pre-compute benefits identically.

Follow-ups left as TODOs in the code

• TODO(ahead-behind-pool) (src/commands/list/collect/mod.rs): the cold-cache %(ahead-behind) walk still runs serially in the setup scope, blocking the task pool from opening. Nothing downstream of work-item generation needs the counts (only the per-row AheadBehindTask, which has a per-SHA fallback) — only the cheap ref scan does. So the walk could become a single work item in the pool, overlapping the other ~N workers. Needs an inter-task dependency the work-item model doesn't have today.
• TODO(remote-ahead-behind-batch) (src/commands/list/collect/tasks.rs): the Remote⇅ column's per-branch ahead_behind_by_sha(upstream, branch) is already cache-backed by this change, but has no cold-start batch primer. One for-each-ref --format='%(refname) %(upstream:track,nobracket)' refs/heads/ would fill the ahead-behind/ cache for it in a single walk, mirroring what %(ahead-behind:main) does for main↕.

Testing

• sha_cache.rs: round-trip + cache-read tests for the new kind; test_clear_all_covers_all_kinds extended.
• ref_snapshot.rs: all-cold→unscoped-batch + cold→warm second-capture reads the persistent cache; partial-warm (few misses) omits the moved branch; many-misses uses the scoped batch; orphan normalizes to (0,0) in both the snapshot and the cache file; remote-tracking base resolves; unresolvable base degrades cleanly.
• Smoke-tested manually: wt list --branches populates .git/wt/cache/ahead-behind/; tampering an entry → the next run shows the tampered counts (proves the read path).
• Two passes of /review-codex — second pass clean.
• cargo run -- hook pre-merge --yes — full suite + lints + doc-sync (3595 tests).

Out of scope (flagged, not done here)

docs/dev/cache-staleness.md still references the in-memory RepoCache.ahead_behind field and batch_ahead_behind — both removed when RefSnapshot landed. Pre-existing staleness; rewriting that doc is a separate cleanup. (The pre-skeleton git log --no-walk commit-details batch is also content-addressed by SHA and could in principle be cache-first, but it's already O(refs) and fast — not worth a TODO.)

🤖 Generated with Claude Code