perf(worktree): fix the prepared-checkout hit rate and make misses visible (#17863)

src/shared/git-binary-compatibility.test.ts

@@ -182,6 +182,38 @@ describeBinaryCompatibility('real Git binary compatibility', () => {
     await runGit(['branch', '-D', 'compat-prepared-final'])
   })
 
+  // Why pin this: the prepared-checkout retarget bound reads these as data, and it fails closed,
+  // so a version that printed a different shape would silently stop every retarget rather than
+  // error. Built with `commit-tree` so the check leaves no ref, branch, or worktree behind.
+  it('measures retarget drift identically on every supported Git', async () => {
+    const tree = (await runGit(['rev-parse', 'HEAD^{tree}'])).stdout.trim()
+    const head = (await runGit(['rev-parse', 'HEAD'])).stdout.trim()
+    const ahead1 = (await runGit(['commit-tree', tree, '-p', head, '-m', 'drift 1'])).stdout.trim()
+    const ahead2 = (
+      await runGit(['commit-tree', tree, '-p', ahead1, '-m', 'drift 2'])
+    ).stdout.trim()
+
+    await expect(
+      runGit(['rev-list', '--count', '--max-count=101', '--end-of-options', `${head}..${ahead2}`])
+    ).resolves.toMatchObject({ stdout: '2\n' })
+    // `--max-count` must report the capped number, not the full one: the bound reads it as a
+    // ceiling, so a Git that returned the true count would reject every retarget instead.
+    await expect(
+      runGit(['rev-list', '--count', '--max-count=1', '--end-of-options', `${head}..${ahead2}`])
+    ).resolves.toMatchObject({ stdout: '1\n' })
+    await expect(
+      runGit(['rev-list', '--count', '--max-count=101', '--end-of-options', `${ahead2}..${head}`])
+    ).resolves.toMatchObject({ stdout: '0\n' })
+
+    await expect(runGit(['merge-base', '--end-of-options', head, ahead2])).resolves.toMatchObject({
+      stdout: `${head}\n`
+    })
+    // A parentless commit shares no history, which is the case the bound must reject however few
+    // commits each side carries.
+    const unrelated = (await runGit(['commit-tree', tree, '-m', 'unrelated root'])).stdout.trim()
+    await expect(runGit(['merge-base', '--end-of-options', head, unrelated])).rejects.toBeDefined()
+  })
+
   it('recognizes ref and merge-tree compatibility boundaries', async () => {
     const fetchHeadPath = join(repoPath, '.git', 'FETCH_HEAD')
     await writeFile(fetchHeadPath, 'sentinel\n')

src/shared/worktree/base-ref.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { resolveWorktreeAddBaseRef } from './base-ref'
+import { resolveWorktreeAddBaseRef, worktreeBaseRefFamily } from './base-ref'
 
 describe('resolveWorktreeAddBaseRef', () => {
   it('leaves fully qualified refs unchanged', async () => {
@@ -62,3 +62,31 @@ describe('resolveWorktreeAddBaseRef', () => {
     await expect(resolveWorktreeAddBaseRef('abc1234', refExists)).resolves.toBe('abc1234')
   })
 })
+
+describe('worktreeBaseRefFamily', () => {
+  it('gives a local branch and its remote-tracking copies the same family', () => {
+    expect(worktreeBaseRefFamily('refs/heads/main')).toBe('main')
+    expect(worktreeBaseRefFamily('refs/remotes/origin/main')).toBe('main')
+    expect(worktreeBaseRefFamily('refs/remotes/upstream/main')).toBe('main')
+  })
+
+  it('keeps the full branch path for slash-containing branches', () => {
+    expect(worktreeBaseRefFamily('refs/heads/release/24.1')).toBe('release/24.1')
+    expect(worktreeBaseRefFamily('refs/remotes/origin/release/24.1')).toBe('release/24.1')
+  })
+
+  it('separates different branches', () => {
+    expect(worktreeBaseRefFamily('refs/heads/main')).not.toBe(
+      worktreeBaseRefFamily('refs/heads/release')
+    )
+  })
+
+  it('has no family for anything that is not a branch ref', () => {
+    expect(worktreeBaseRefFamily('abc1234')).toBeNull()
+    expect(worktreeBaseRefFamily('main')).toBeNull()
+    expect(worktreeBaseRefFamily('refs/tags/v1.0.0')).toBeNull()
+    expect(worktreeBaseRefFamily('refs/pull/123/head')).toBeNull()
+    expect(worktreeBaseRefFamily('refs/remotes/origin/HEAD')).toBeNull()
+    expect(worktreeBaseRefFamily('refs/remotes/origin')).toBeNull()
+  })
+})

src/shared/worktree/base-ref.ts

@@ -23,3 +23,30 @@ export async function resolveWorktreeAddBaseRef(
 
   return baseRef
 }
+
+/**
+ * The branch identity two base refs share when one is the local branch and the
+ * other is a remote-tracking copy of it: `refs/heads/main` and
+ * `refs/remotes/origin/main` both return `main`.
+ *
+ * Bounds the prepared-checkout retarget. A prepared checkout may only be reused
+ * for a different base when both name the same branch, so the retarget reset is
+ * bounded by that branch's drift across remotes rather than by an arbitrary
+ * divergence. Anything unqualified — a bare name, a commit id — has no family.
+ */
+export function worktreeBaseRefFamily(qualifiedRef: string): string | null {
+  if (qualifiedRef.startsWith('refs/heads/')) {
+    return qualifiedRef.slice('refs/heads/'.length) || null
+  }
+  if (qualifiedRef.startsWith('refs/remotes/')) {
+    const withoutRemote = qualifiedRef.slice('refs/remotes/'.length)
+    const separator = withoutRemote.indexOf('/')
+    if (separator <= 0) {
+      return null
+    }
+    const branch = withoutRemote.slice(separator + 1)
+    // `refs/remotes/<remote>/HEAD` is a symbolic pointer, not a branch identity.
+    return branch && branch !== 'HEAD' ? branch : null
+  }
+  return null
+}

src/shared/worktree/create-types.ts

@@ -31,9 +31,40 @@ export type WorktreeCreateTimingPhase = {
   durationMs: number
 }
 
+/** Closed vocabulary: these values reach span attributes, so none of them may ever
+ *  be derived from a branch name, a ref, or a path. */
+export type PreparedCheckoutMissReason =
+  | 'none_armed'
+  /** Preparations exist, but none for this repo — it was never warmed, or the pool's size cap
+   *  evicted it for another repo. Distinguished from `none_armed` because it is the signal that
+   *  the cap is thrashing for a multi-project user. */
+  | 'repo_mismatch'
+  | 'base_mismatch'
+  | 'retarget_too_divergent'
+  /** The drift check returned no answer. Distinct from `retarget_too_divergent` because that one
+   *  is the bound working as intended, while this one means a possibly cheap retarget was skipped
+   *  anyway. Deliberately a mixed bucket — a blown deadline, a cancelled create, and an ordinary
+   *  Git failure such as a missing ref all land here — so treat a rise as "look at why", not as a
+   *  direct readout of the budget being too small. */
+  | 'retarget_unverifiable'
+  | 'workspace_root_mismatch'
+  | 'wsl_distro_mismatch'
+  | 'prepare_failed'
+  | 'finalize_failed'
+  | 'checkout_existing_branch'
+  | 'sparse_checkout'
+
+/** Whether a create reused a prewarmed checkout, and when it did not, which part of
+ *  the claim key disagreed. `retargeted` marks a hit that had to reset the prepared
+ *  checkout onto a different ref in the same base family. */
+export type PreparedCheckoutOutcome =
+  | { status: 'hit'; retargeted: boolean }
+  | { status: 'miss'; reason: PreparedCheckoutMissReason }
+
 export type WorktreeCreateTiming = {
   totalDurationMs: number
   phases: WorktreeCreateTimingPhase[]
+  preparedCheckout?: PreparedCheckoutOutcome
 }
 
 export type CreateSparseCheckoutRequest = {