perf(git): take the git pipeline off the UI thread, and stop polling blind

[AThraen]

Fixes #70. The typing stall — input stops echoing, then arrives all at once — diagnosed by measurement, after three of the four standing hypotheses turned out to be wrong.

What the trace said

Instrumented first, then run at the reporter's real workload (47 sessions, not the 25 previously assumed):

42 UI-STALL events, worst 28547ms

10.54.10  d974929c OUTPUT flush len=3350 dispatcher-latency=12781ms prio=fg since-input=22312ms
10.54.51  4b927f0e OUTPUT flush len=1405 dispatcher-latency=23000ms prio=fg since-input=-1ms

That first line is the bug report restated as data: a foreground pane, blocked 12.8s, accumulating 3.3KB, then rendering it in one blob.

Hypothesis	Evidence against
Renderer starvation	0 PAGE write-blocked, 3 paint-lag in 4 minutes
ConPTY write backpressure	662 PTY-WROTE, 661 of them 0ms
Stale IsForeground → Background starvation	the typed pane logged prio=fg throughout
Output flooding the dispatcher queue	69KB across 12 sessions in a 68s window that still contained a 9.1s stall

The last one falsified the theory this issue is titled after, and is what broke the case open — it pointed at work on the UI thread that wasn't terminal I/O at all. Stalls also continued at 10:55:40, 10:56:01 and 10:56:23, after restore finished and before shutdown began, with the app logging nothing.

Root cause

An async method runs everything before its first await synchronously on the calling thread.

using var process = Process.Start(psi);   // before the first await

The git poll chain starts in SessionViewModel's constructor, which LaunchSessionAsync runs on the UI thread. So the SynchronizationContext was captured, every continuation returned there, and git process creation happened on the UI thread — ~94 spawns per 10s cycle at 47 sessions.

Measured on this hardware:

cmd /c exit	21 ms — Windows baseline process creation
git --version	42 ms — git startup, zero repo access
git branch --show-current	41 ms — indistinguishable from doing nothing
git status --porcelain	48–65 ms — only 6–23 ms is the actual tree walk
Process.Start alone	~15 ms — the slice that lands on the UI thread

85–90% of any git call is process startup, not git. There was never a faster query to switch to. That is ~1.4s of hard UI block per cycle on an idle machine — and a git --version outlier at 525ms against its 42ms median shows what contention does to that floor.

#70's step 4 had the right target and the wrong mechanism. It called this "background load — ~46 process spawns per 10s". It was never background, which is why backing off the interval would have made the freeze rarer rather than fixing it.

The three fixes

1. GitService cannot depend on the caller's thread. RunGitFullAsync is Task.Run-wrapped so Process.Start cannot run inline; every await is ConfigureAwait(false) so nothing climbs back. Both halves are load-bearing — ConfigureAwait alone would not have moved Process.Start. SessionViewModel also starts the poll loop under Task.Run, so the context is never captured in the first place.

2. GitRepoWatcher replaces most of the polling. A debounced FileSystemWatcher on .git/HEAD and .git/index catches checkout, commit, merge and staging immediately — more responsive than a 10s poll, not less. It follows the gitdir: indirection so a linked worktree watches its own HEAD rather than the main repo's, which would otherwise report the wrong branch entirely.

Polling survives only for the case the watcher genuinely cannot see — a working-tree edit dirties status without touching anything under .git. Foreground 10s, background 120s, plus an immediate refresh when a pane becomes active.

3. One notification instead of three. GitBranch / GitIsDirty / GitInfoLoaded are now hand-written properties sharing GitInfoVersion. As [ObservableProperty] they raised three events per poll per session, each crossing a blocking Dispatcher.Invoke and rebuilding a sidebar row's WPF inlines — 141 rebuilds per cycle. ApplyGitInfo also returns early on an unchanged result, which is almost every poll: a branch changes maybe once an hour.

The instrumentation had rotted

Worth stating plainly, because it nearly cost another round.

dispatcher-latency was added in 092b801 and deleted by 71e1294 — the coalescing commit for this same issue — which dropped the enqueue timestamp along with the per-chunk post it was attached to. The fix removed the instrument that measured the problem, and nothing looked wrong afterwards because the trace still produced plausible output. I repeated the stale claim that it existed before checking.

It would also have caused the stall it measured: Trace() did Directory.CreateDirectory plus a synchronous File.AppendAllText per call, on the PTY read thread for output and the UI thread for every flush.

• DiagnosticTrace — bounded queue, one background drain, timestamps taken at call time so deferring the I/O does not distort the measurement. Overflow reported in-band, since a silent gap in a latency log reads as a stall that never happened.
• dispatcher-latency restored on the coalesced flush, with the priority the batch was queued at and time-since-last-input.
• UiThreadHeartbeat — UI lateness attributed to no session, the only way to separate real saturation from Background priority yielding correctly.
• Page-side term.write duration and paint lag, threshold-gated. The host is blind past PostWebMessageAsString.
• GIT-SPAWN on-ui=<bool> spawn=<ms> — the probe that proved the diagnosis, now also asserted by a test.

Tests

367 total (19 new), 0 warnings.

GitServiceThreadingTests calls GitService from a thread whose SynchronizationContext never runs work: if any await captures it, the call never completes and the test times out. All three fail against the pre-fix GitService — verified by stashing it and re-running, not assumed:

GetGitInfoAsync_completes_without_the_callers_context_ever_running        [FAIL] 20.36s
GetRepoRootAsync_completes_without_the_callers_context_ever_running       [FAIL] 40.39s
Process_creation_never_happens_on_the_thread_designated_as_the_UI_thread  [FAIL]

GitRepoWatcherTests covers worktree gitdir: resolution, that only HEAD/index wake it, debouncing a checkout's burst into one notification, and that a non-repo returns null rather than throwing. SessionViewModelGitInfoTests pins the single-notification contract and the unchanged-result early-out.

Still worth doing after this

The same trace showed 47 saved sessions restoring over 151 seconds, and SHUTDOWN complete: 17 waited, 10 force-disposed, 30341ms — the full budget spent. Both are #82, untouched here.

Verification

Check	Result
App build	0 errors, 0 warnings
Unit tests	367/367
Regression tests fail without the fix	verified by reverting GitService
terminal-init.js syntax	node --check clean

Not yet run against the live 47-session workload — that is the one thing to confirm on merge. The trace is still in, so a post-merge run should show GIT-SPAWN on-ui=False, UI-HEARTBEAT stalls=0, and spawn counts collapsing from ~94 per 10s to near zero at idle.

The second commit also carries an unrelated drive-by docs fix (chocolatey moderation, download-count overlap) — say the word and I will pull it out.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NDsEfog5kVkT5NmX1Ya5be