Cut worktree-switch latency by capping and deferring git reads

[frenchie4111]

Summary

Worktree switches stalled on git, not on CPU — during a stall perf.log showed lag=1ms while git status --porcelain sat at ~35% CPU statting thousands of files. This branch attacks the wait, not the work.

• Global read-only git concurrency gate (src/main/git-limiter.ts), cap 4, with strict interactive > bulk priority. Permits are acquired at the leaf exec, never held across a nested await, so helpers that call helpers can't deadlock. Writes (merge, fetch, worktree add) deliberately bypass the gate — they're rare, user-initiated, long, and call read helpers internally.
• Per-repo dedup + TTL cache for getMainWorktreeStatus. The panel asked directly while worktree:previewMerge asked internally at the same instant; that's now one read. Merge paths pass { force: true } so the gate never sees stale state, and invalidation happens after a merge so a racing read can't repopulate mid-merge.
• Merge-conflict simulation off the switch critical path. previewMergeConflicts is deferred 500ms and cancelled on worktree change; handleMerge settles the in-flight preview before merging, so the conflict guard is preserved.
• Cleanup's dirty sweep streams at bulk priority instead of one unbounded Promise.all, and renders per answer. dirtyMap now distinguishes unscanned from scanned-and-clean, and selection requires dirtyKnown — an unscanned worktree must never be auto-armed for deletion.

Measured result

A/B on the reference monorepo (20 worktrees, 80 switches per cell), wall-clock click→populated-panel against baseline src/:

scenario	before	after	Δ
quiet p50	2063ms	1605ms	−22%
quiet mean	2159ms	1660ms	−23%
contended p50	2191ms	1573ms	−28%
contended mean	2387ms	1685ms	−29%
contended max	4593ms	3282ms	−29%

The structural win is the last row's cause: a concurrent background dirty sweep used to add +228ms to the mean switch. It now adds +25ms.

Both benchmark tables (concurrency sweep and real-switch sweep) are recorded in the git-limiter.ts module comment so the cap of 4 stays falsifiable. The benchmark harness itself is not committed — it takes ~5min and points at a private repo.

Corrections to the originating brief

• "Concurrency makes it strictly worse" is wrong. Total wall time is flat from cap 4 to cap 64; only per-call latency degrades (p50 77ms → 274ms). The cap is justified by queue fairness and tail latency, not throughput.
• Cleanup's scan never ran with the modal closed (App.tsx gates on showCleanup), so it was never a background cost — only an in-modal one.
• The bigger duplicate was worktree:previewMerge recomputing main status, which the brief didn't mention.

Negative results (investigated, not shipped)

• Demoting XTerminal link-priming to bulk (listAllFiles / listRecentCommitShas): split benchmark gave panels-only mean 1972ms vs everything 1974ms. Priming is never the long pole. No change made.
• Parallelizing getChangedFiles: already a Promise.all. I misread the [git-op] trace initially — execParts sums to cumulative exec time, not wall time.

Also fixed along the way

• The main-status TTL was stamped at dispatch, before the awaits. On a repo where the reads outlast the TTL, every entry landed already expired and the cache could never serve anyone — exactly the slow-repo case it exists for. TTL now runs from settle time; in-flight entries are always fresh.
• Pre-existing stale closures in PRStatusPanel: refreshStatus had deps [worktree.branch] while reading repoRoot/path; handleFix had [] deps over worktree.repoRoot.

Scope

This is switch latency only. It does not address the renderer CPU/RSS jank being handled in a separate worktree, and makes no claim about the app's general stutter.

Test plan

• npm run typecheck
• npx electron-vite build
• npx vitest run — new: 5 limiter tests (cap, queueing, interactive-ahead-of-bulk, permit released on throw, bulk drains after), 6 real-git main-status cache tests (concurrent collapse, TTL hit, invalidation, forced re-read, per-repo keying, failures not cached)
• A/B latency benchmark above, 80 switches per cell, quiet and contended
• Manual: switch between worktrees and confirm the PR panel populates without waiting on conflict simulation
• Manual: open Cleanup on a repo with many worktrees, confirm rows stream in and nothing unscanned is pre-selected for deletion

Known suite noise: 16 failures (8 unique × 2 vitest projects) in git-ops-state.test.ts, path-fix.test.ts, and worktree-watcher.integration.test.ts. These are load-sensitive real-git / fs.watch flakes — they pass in isolation, fail identically on baseline c6a2eb61, and none of them import the modules this branch touches.

🤖 Generated with Claude Code