perf(server): a checkpoint capture starts 8 git processes instead of 10#21315

Problem

Every checkpoint capture starts 10 git processes one after another, and three of them are git rev-parse lookups that one process can answer. Captures run at the start and end of every turn, under a per-worktree lock, so a turn waits for each process to start and exit. On Linux each start also blocks the server's event loop for longer as the server's memory grows (libuv uses fork(); about 23 ms per start at 513 MB RSS, #21289). In #21289 a maintainer confirmed the T3 side: "a checkpoint capture on the common path runs 10 git processes in sequence".

From the trace of the profiling run in #21289 (scratch server at origin/main 1b5c2d1d30, 6 concurrent Claude threads with 4 short turns each; since then the capture has only gained -c flags):

• All 98 captures ran exactly 10 git processes: rev-parse --git-common-dir, rev-parse --verify HEAD, config --bool core.sparseCheckout, rev-parse --path-format=absolute --git-path index, read-tree --reset HEAD, ls-files, add -A, write-tree, commit-tree and update-ref.
• A capture took 325 ms (p50), and the time inside those processes added up to 311 ms (p50). Each of the three rev-parse lookups took 11–12 ms (p50), almost all of it starting and stopping the process.
• Captures started 980 of the session's 1,325 git processes. A turn started about 27 in all; with this change it would start about 23.

Change

One git rev-parse --git-common-dir --path-format=absolute --git-path index --verify --quiet HEAD replaces the three lookups in apps/server/src/vcs/GitVcsDriver.ts. It prints the same values the separate commands did:

• --git-common-dir comes before --path-format, so it keeps its default form: .git, ../../.git from a subdirectory, or an absolute path in a linked worktree. The capture resolves that string as before.
• --git-path index after --path-format=absolute prints the same absolute index path as the old lookup.
• --verify prints HEAD's oid after both paths. With --quiet, an unborn HEAD exits 1 after printing only the paths, so exit 1 still means "no commit yet".

A capture now starts 8 git processes instead of 10, or 6 instead of 7 with an unborn HEAD. Everything after the lookups is unchanged: the sparse checkout, skip-worktree, split index and nested repository handling, the durability flags, and the timeouts (the three lookups used the default 30 s, and so does the new one).

If the output isn't exactly two paths and an oid, the capture reads the paths with the old commands:

• Git before 2.31 doesn't know --path-format and echoes it as an extra line. Its old index lookup also printed --path-format=absolute plus a relative path, which the capture can't stat, so it rebuilt the index from HEAD; it still does. HEAD's existence comes from the exit code, so Git 2.30 still starts 9 processes per capture, as before.
• A repository path containing a newline spans lines; the old commands read it as before.
• Any other exit (not a repository, dubious ownership) re-runs rev-parse --git-common-dir, which fails with the same error as before.

I left the core.sparseCheckout probe alone. Caching it per repository would save one more process, but Git can read that value from the repository's config or config.worktree (where git sparse-checkout writes it once extensions.worktreeConfig is on), global and system config, include.path files, includeIf "onbranch:…" sections that change with HEAD, and GIT_CONFIG_* variables. A stale value changes whether git add gets --sparse and how skip-worktree entries are read, so it needs its own design.

Scope and approval

This is a focused performance fix inside the existing capture: three read-only lookups become one, with no change to what a checkpoint contains, which refs it writes, or the flags Git writes them with. #21289 established the problem, and the maintainer's comment linked above confirms the 10-process capture.

• #18219 (open) starts Linux child processes from a long-lived spawn host to cut each start's fork() cost. It doesn't touch GitVcsDriver.ts, and this PR doesn't touch process spawning. The two stack: with or without the spawn host, every process still costs an exec, Git's startup and an exit wait inside the per-worktree lock, and the spawn host only applies on Linux.
• #21291 (open, mine) changes only the durableWrite constant in the same file. This PR doesn't touch it. git merge-tree reports no conflict, and both suites below pass on the two branches merged together (76 passed).

Verification

Tests, Git 2.53.0 on Linux:

• cd apps/server && vp test run src/vcs/GitVcsDriver.test.ts src/checkpointing/CheckpointStore.test.ts: 76 passed. The 72 existing tests are unchanged; 4 are new.
  • "checkpoint capture reads the repository with one rev-parse (HEAD=committed)" and "(HEAD=unborn)" record every git subcommand a capture starts and pin the 8- and 6-command sequences. They also check the captured file and that the checkpoint's parent is HEAD (or that it has none for an unborn HEAD). On origin/main both fail, recording 10 and 7 commands.
  • "checkpoint capture outside a repository fails with the common dir lookup error" and "checkpoint capture handles a repository path containing a newline" (skipped on Windows) cover the fallback. Both also pass on origin/main, which shows the fallback keeps today's behavior: the same error, the same 10 commands, the same checkpoint, and an untouched user index.
• cd apps/server && vp run --no-cache typecheck: only the two existing Duplicate identifier 'Path' errors in GrokAdapterV2.test.ts, which main also has.
• vp lint and vp fmt --check on both changed files: clean.

Older Git: I built Git 2.30.9 from the kernel.org tarball and ran both suites with it first on PATH, once on origin/main with the new tests added and once on this branch. The per-test results match exactly: 48 passed and 28 failed on each. The failures are:

• 20 sparse checkout cases whose fixtures run sparse-checkout set --sparse-index (Git 2.32+);
• 2 listAuthoredPaths cases that use log --diff-merges=remerge (Git 2.36+);
• 3 tests that rely on index reuse, which Git before 2.31 never reaches;
• the 3 new tests that pin the modern command sequence.

A capture on Git 2.30.9 runs the same 9 processes in the same order on both.

Benchmark (scratch test, not committed): CheckpointStore.captureCheckpoint through the real VcsDriverRegistry and VcsProcess layers, with git processes counted at ProcessRunner. The setup:

• Repositories on ext4 (Ryzen 7 8840HS, Node 26.12), one file changed before each capture.
• 3 warm-up captures, then 20 (50-file repository) or 10 (t3code checkout) measured captures per round.
• 3 rounds alternating main and this branch.
• The test process's RSS raised with filled buffers.

Each cell is the median of the three rounds' p50 wall time, with the range across rounds:

The event loop's busy time per capture (performance.eventLoopUtilization()) fell by about the same amount, for example from 305 to 243 ms on the t3code checkout at ~1 GB, so the time saved is mostly the main thread blocked while starting processes. Before measuring the t3code checkout I ran git status in it so its index wasn't racily clean. Straight after a checkout, every capture re-hashes most files (about 1.3 s per capture), which hides the difference.

Not checked: macOS and Windows; Git versions other than 2.53.0 and 2.30.9; a fresh multi-thread server profile with this branch.

Written by Claude Opus 5.5 in Claude Code, orchestrated from T3 Code.