fix(server): new worktrees refresh their index once, so captures and status stop re-hashing every file#21341

Problem

A worktree T3 creates for a thread stays "racily clean" until something outside T3 rewrites its index, and until then every checkpoint capture and every status refresh in it re-reads the whole checkout (#21328).

git worktree add writes the files first and the index last. Git re-reads, on every status, diff and add, each file whose mtime falls in the index's own second or later. With the checkout.workers=0 that createWorktree passes, a t3code checkout (28,271 files, 396 MB) finishes in about 0.63 s here, so often all of it lands in that second. Nothing T3 runs ever writes the index:

• status polling uses GIT_OPTIONAL_LOCKS=0 and plumbing diff-index (#14718);
• captures work on a copy of the index;
• the agents don't either: Claude Code's startup commands use --no-optional-locks, and Codex's startup left the index unwritten too.

Numbers from #21328, measured in such a worktree:

On acerlinux, real T3 thread worktrees still had their creation-time index days later.

Change

GitVcsDriverCore.createWorktree now refreshes the new worktree's index once, after git worktree add and the submodule update, before it returns the worktree. Every T3 path that creates a worktree goes through this function: thread launch, PR worktree threads, the worktree MCP tool, checkpoint rollback, recreating a missing worktree at turn start, and the client's create-worktree request.

How it works:

1. It reads the index path with git rev-parse --git-path index and notes the index file's mtime second.
2. It runs git update-index -q --refresh --force-write-index.
   • -q exits 0 even when a file really is modified.
   • --force-write-index is needed for older Git: Git 2.30.9 leaves the index unwritten when racy entries merely check out clean. Git 2.53 writes either way.
3. If the rewritten index is still in the checkout's second, its entries are just as racy. In that case it waits until 50 ms past the end of that second and refreshes again; the margin covers file timestamps coming from a coarse kernel clock that can trail the wall clock. A 1,000-file checkout, for example, ends and refreshes within the same second. On t3code the first refresh takes about 1.3–1.8 s, so it never waits.
4. If that wait would be two seconds or more, the clock doesn't match the file timestamps (for example a network share stamped by another machine). It then skips the second refresh rather than guess. A virtual test clock also lands here, so existing tests don't wait.

Failure handling:

• Any failure is logged as a warning and ignored; the worktree is returned either way.
• The refresh gets the same 300 s timeout as git worktree add (WORKTREE_ADD_TIMEOUT_MS), since it re-reads every checked-out file and so scales with the checkout. Like worktree add, a timeout above the default keeps it out of the shared git process permits. When a timeout stops it, Git gets SIGTERM and removes its own index.lock. I checked this by killing a refresh 300 ms in: exit 143, no lock left, index unchanged.
• GIT_OPTIONAL_LOCKS=0, which the core driver sets for every command, doesn't stop update-index from writing (checked).

Why not run it in the background: a refresh holds index.lock for its whole run, which is 1.7 s on t3code. Thread launch starts the project setup script as soon as createWorktree returns, and agents may run git add or git checkout early. A background refresh would make those fail with "Unable to create index.lock: File exists", the failure #14718 removed from status polling. Running it before returning costs a one-time 1.3–1.8 s on t3code, or up to about 1 s on small repositories, when the worktree is created.

Scope and approval

Fixes #21328, which was accepted as a bug, and the triage named this exact gap: "a single missing refresh right after the worktree is created, before anything else uses it". It also endorsed the timing and safety constraints this change follows. The change is a one-time refresh in the one function that creates T3's worktrees. It doesn't change what gets checked out, how status or checkpoints work, or any setting.

It touches only GitVcsDriverCore.ts and its test. git merge-tree reports no conflict with #21315, #21329 or #21291.

A possible follow-up, not in this PR (the triage put clones out of scope for #21328): T3's project clone (git clone --progress in SourceControlRepositoryService) checks out sequentially, which leaves the files from its last second racily clean. A sequential checkout of t3code left 9,688 of 28,271 entries that way, and captures took 1.33 s instead of 0.21 s. The same refresh would apply there. Adding an existing folder as a project checks nothing out, so it isn't affected.

Verification

Tests, Git 2.53.0 and Node 26.12, on lenovolinux:

• cd apps/server && vp test run src/vcs/GitVcsDriverCore.test.ts: 167 passed. The 165 existing tests are unchanged; 2 are new.
  • "refreshes a new worktree's index once its checkout second is over" creates a 51-file worktree through the real driver, with the live clock, and asserts that no index entry is stamped in or after the index's own second.
  • "returns the worktree when its index refresh fails" uses a post-checkout hook to take the new worktree's index.lock. It asserts that createWorktree still returns a usable worktree, leaves that lock alone and logs the warning.
  • Run against origin/main's GitVcsDriverCore.ts, both fail in 5 of 5 runs. The first finds all 51 entries in the index's second; the second gets no warning, because nothing refreshes.
• All 12 server test files that create worktrees or touch checkpoints, including the three above: 844 passed.
  • cd apps/server && vp test run src/vcs/GitVcsDriverCore.test.ts src/vcs/GitVcsDriver.test.ts src/checkpointing/CheckpointStore.test.ts src/git/GitManager.test.ts src/mcp/toolkits/project/handlers.test.ts src/mcp/WorktreeMcpService.test.ts src/orchestration-v2/CheckpointRollbackService.test.ts src/orchestration-v2/ProviderEventIngestor.test.ts src/orchestration-v2/ProviderTurnStartService.test.ts src/orchestration-v2/runtimeLayer.test.ts src/orchestration-v2/ThreadLaunchService.test.ts src/storageCleanup.test.ts
  • Test time is essentially unchanged: the core suite took 19.5 s on main and 20.7 s here, including the new test's real wait of about 1 s. The other 9 files took 110.1 s against 110.3 s.
• Git 2.30.9, built from the kernel.org tarball, put first on PATH for the core suite:
  • main's driver: 159 passed, 8 failed. This branch: 161 passed, 6 failed.
  • The only differences are the two new tests. The other 6 failures are the same on both and come from Git 2.30 itself.
• cd apps/server && vp run --no-cache typecheck: no errors. vp lint and vp fmt --check on both files: nothing new. Two lint warnings elsewhere in these files predate this change.

Measured with a scratch test (not committed). It creates a worktree through the real GitVcsDriver.createWorktree with the live clock, then runs CheckpointStore.captureCheckpoint through the real VcsDriverRegistry and VcsProcess layers, with a small edit before each capture, and three statusDetailsLocal calls. Each round uses a fresh worktree.

t3code (28,271 files, from origin/main d8e9fd267e). main had 6 rounds; this branch had 3 with the final code. How much of a fresh checkout is racy on main depends on where a second boundary falls during it: all of it in 3 rounds, 621–1,748 entries in the other 3.

Three earlier branch rounds, alternated with three of the main rounds and run before I added --force-write-index (which changes nothing on Git 2.53), gave the same picture. createWorktree took 1,805–2,444 ms, captures 197–249 ms, and status 104–125 ms.

A 1,000-file repository (22 MB of t3code sources), 3 rounds on main and 6 on this branch (3 of them alternated with main and run before --force-write-index):

So a small repository waits up to about 1 s once, to save about 50 ms per capture and about 80 ms per status refresh.

Not checked:

• macOS (the Mac was offline) and Windows.
• Network shares.
• Git versions other than 2.53.0 and 2.30.9; Git before 2.17 lacks --force-write-index, so there the refresh fails and is logged.
• A full thread launch through the app: I called createWorktree through the real driver layers, not through ThreadLaunchService and the UI.

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

Fixes pingdotgg/t3code#21328