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

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 = {