fix(worktrees): fence the catalog owner by runtime, single flight and hygiene claims

Sidebar reads age from scan start, so runtime verifications no longer
stretch them; probes only certify rows fingerprinted before their scan.
One flight per owner, with a single trailing scan after invalidation.
Switching a repo's Git runtime retires the old owner, and a reader whose
owner was retired mid-read returns non-authoritative rows. Only pruning
readers claim hygiene, failed scans keep the evidence gate's no-retry
claim, overflow invalidates at once, and the stopped-distro fallback
serves only current rows.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Brennan Benson
2026-11-11 20:56:40 -08:00
co-authored by Claude Opus 5.5
parent 315ce1b8cf
commit ea5d772f8a
15 changed files with 345 additions and 161 deletions
@@ -68,7 +68,7 @@ export async function listWorktreesUnshared(
}
/** Only a missing path or confirmed non-repo permits an authoritative empty listing. */
async function isTrueEmptyWorktreeListing(repoPath: string, err: unknown): Promise<boolean> {
export async function isTrueEmptyWorktreeListing(repoPath: string, err: unknown): Promise<boolean> {
if (getErrorCode(err) === 'ENOENT') {
try {
await stat(repoPath)
@@ -67,5 +67,8 @@ export function handleWatchOverflow(
return
}
invalidateActiveGitStatusRefResolution(watch, getActiveWatches)
for (const repoId of watch.repos.keys()) {
runWorktreeChangeInvalidators(repoId)
}
scheduleWorktreeBaseNotification(watch, { structureRepoIds: [...watch.repos.keys()] })
}
@@ -34,6 +34,7 @@ import {
import { resolveWorktreeScanRuntime } from '../../../runtime/workspaces/catalog/runtime-worktree-scan-cache'
import {
claimWorktreeCatalogHygiene,
needsWorktreeCatalogHygieneClaim,
worktreeCatalogHygienePlan
} from './worktree-catalog-observation-hygiene'
@@ -95,13 +96,17 @@ export async function listDetectedGitWorktrees(
const { observation, superseded } = await readWorktreeCatalog(
repo,
resolveWorktreeScanRuntime(store, repo).runtimeKey,
{ kind: 'desktop', maxAgeMs: DETECTED_WORKTREE_SCAN_CACHE_TTL_MS },
{
kind: 'desktop',
maxAgeMs: DETECTED_WORKTREE_SCAN_CACHE_TTL_MS,
needsHygieneClaim: needsWorktreeCatalogHygieneClaim(repo)
},
{
scan: async () => {
const worktrees = await listRepoWorktreesForDetectedScan(repo, localWorktreeGitOptions)
return worktrees.length > 0 ? { kind: 'rows', worktrees } : { kind: 'true-empty' }
},
...worktreeCatalogHygienePlan(store, repo, localWorktreeGitOptions)
...worktreeCatalogHygienePlan(store, repo, localWorktreeGitOptions, true)
}
)
if (observation.outcome.kind === 'failed') {
@@ -0,0 +1,57 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import type { Repo } from '../../../../shared/repo-types'
import {
_resetWorktreeCatalogOwnerForTests,
readWorktreeCatalog
} from '../../../workspaces/catalog/repo-worktree-catalog-owner'
import { __resetLocalWorktreeMetadataPruneGateForTests } from '../../../workspaces/catalog/local-worktree-metadata-prune-gate'
import {
needsWorktreeCatalogHygieneClaim,
worktreeCatalogHygienePlan
} from './worktree-catalog-observation-hygiene'
vi.mock('../removal/registered-worktree-roots-cache', () => ({
getRegisteredWorktreeRootsRevision: () => 0,
registerWorktreeRootsForRepo: vi.fn()
}))
const repo = { id: 'repo-1', path: '/repos/app', kind: 'git' } as Repo
async function readFailing(times: number, claimsHygiene: boolean) {
const capture = vi.fn(() => ({}) as never)
const store = { captureNativeLocalWorktreeMetadataScanExpectation: capture }
for (let read = 0; read < times; read += 1) {
await readWorktreeCatalog(
repo,
'local:default',
{
kind: 'desktop',
maxAgeMs: 5_000,
...(claimsHygiene ? { needsHygieneClaim: needsWorktreeCatalogHygieneClaim(repo) } : {})
},
{
scan: () => Promise.reject(new Error('fatal: not a git repository (permission denied)')),
...worktreeCatalogHygienePlan(store as never, repo, {}, claimsHygiene)
}
)
}
return capture.mock.calls.length
}
describe('worktree catalog observation hygiene', () => {
afterEach(() => {
_resetWorktreeCatalogOwnerForTests()
__resetLocalWorktreeMetadataPruneGateForTests()
})
it('captures the whole-store expectation once per evidence, however often a failing repo is read', async () => {
expect(await readFailing(5, true)).toBe(1)
__resetLocalWorktreeMetadataPruneGateForTests()
_resetWorktreeCatalogOwnerForTests()
expect(await readFailing(50, true)).toBe(1)
})
it('never captures for readers that do not prune', async () => {
expect(await readFailing(5, false)).toBe(0)
})
})
@@ -6,7 +6,7 @@ import type {
WorktreeCatalogFlightPlan,
WorktreeCatalogObservation,
WorktreeCatalogWitness
} from '../../../workspaces/catalog/repo-worktree-catalog-owner'
} from '../../../workspaces/catalog/repo-worktree-catalog-observation'
import {
isLocalWorktreeMetadataPruneDue,
markLocalWorktreeMetadataPruneStarted,
@@ -33,17 +33,19 @@ export type WorktreeCatalogHygieneClaim = Readonly<{
expectation?: NativeLocalWorktreeMetadataScanExpectation
}>
/** Every reader's flight carries the same pre-scan capture, so whoever starts it observes for all (#17775). */
/** Pre-scan facts for every flight; only readers that prune claim the evidence gate (#17775). */
export function worktreeCatalogHygienePlan(
store: Store | HygieneStore,
repo: Repo,
gitOptions: { wslDistro?: string }
gitOptions: { wslDistro?: string },
claimsHygiene: boolean
): Pick<WorktreeCatalogFlightPlan, 'captureWitness' | 'observed'> {
return {
captureWitness: () => {
const authorizedRootsRevision = getRegisteredWorktreeRootsRevision(repo.id)
// Whole-table capture and missing-path stats run only when changed evidence makes hygiene due.
const hygieneDue = isLocalWorktreeMetadataPruneDue(repo.id)
// Whole-table capture and missing-path stats run only when changed evidence makes hygiene due,
// and only for a reader that will consume them; unclaimed captures would re-arm and repeat.
const hygieneDue = claimsHygiene && isLocalWorktreeMetadataPruneDue(repo.id)
if (hygieneDue) {
markLocalWorktreeMetadataPruneStarted(repo.id)
}
@@ -108,3 +110,8 @@ export function claimWorktreeCatalogHygiene(
...(witness.expectation ? { expectation: witness.expectation } : {})
}
}
/** A pruning reader must not settle for rows observed without its pre-scan claim while hygiene is due. */
export function needsWorktreeCatalogHygieneClaim(repo: Repo): () => boolean {
return () => isLocalWorktreeMetadataPruneDue(repo.id)
}
@@ -210,7 +210,8 @@ export abstract class RuntimeConstructionServices {
protected abstract selectReposBySelector(selector: string): Repo[]
protected abstract listRepoWorktreesForListing(
repo: Repo,
projectRuntimeByRepoId?: ReadonlyMap<string, ProjectExecutionRuntimeResolution>
projectRuntimeByRepoId?: ReadonlyMap<string, ProjectExecutionRuntimeResolution>,
options?: { claimsHygiene?: boolean }
): Promise<RuntimeWorktreeScanResult>
protected abstract listKnownExecutionHostIds(
additionalHostIds?: Iterable<ExecutionHostId>,
@@ -147,7 +147,8 @@ export abstract class OrcaRuntimeWithStopRequestedPtyIds extends OrcaRuntimeWith
listResolved: () => this.listResolvedWorktrees(),
resolveRepo: (selector) => this.resolveRepoSelector(selector),
selectRepos: (selector) => this.selectReposBySelector(selector),
scanRepo: (repo) => this.listRepoWorktreesForListing(repo),
// listDetected prunes metadata, so its scans carry the pre-scan hygiene claim.
scanRepo: (repo) => this.listRepoWorktreesForListing(repo, undefined, { claimsHygiene: true }),
listKnownHostIds: () => this.listKnownExecutionHostIds()
})
@@ -77,6 +77,8 @@ describe('OrcaRuntimeService', () => {
vi.mocked(listWorktrees)
.mockImplementationOnce(() => staleScan.promise)
.mockResolvedValueOnce([createdWorktree])
// listDetected prunes after the create, so it observes again with its own pre-scan claim.
.mockResolvedValueOnce([...MOCK_GIT_WORKTREES, createdWorktree])
.mockResolvedValueOnce([...MOCK_GIT_WORKTREES, createdWorktree])
const staleLookup = runtime.showManagedWorktree(TEST_WORKTREE_ID)
@@ -1,11 +1,15 @@
import type { GitWorktreeInfo } from '../../../../shared/worktree/types'
import { listWorktreesStrict } from '../../../git/worktrees/catalog/worktree-listing'
import {
isTrueEmptyWorktreeListing,
listWorktreesStrict
} from '../../../git/worktrees/catalog/worktree-listing'
import type { LocalProjectWorktreeGitOptions } from '../../../workspaces/execution-host/project-runtime-git-options'
export type RuntimeWorktreeScanResult =
| { ok: true; worktrees: GitWorktreeInfo[] }
| { ok: false; worktrees: GitWorktreeInfo[] }
| { ok: false; worktrees: GitWorktreeInfo[]; trueEmpty?: boolean }
/** Runtime readers never treat an empty catalog as success; `trueEmpty` tells the shared owner it was confirmed. */
export async function scanLocalRepoWorktreesForResolution(
repoPath: string,
options: LocalProjectWorktreeGitOptions
@@ -15,7 +19,9 @@ export async function scanLocalRepoWorktreesForResolution(
? await listWorktreesStrict(repoPath, options)
: await listWorktreesStrict(repoPath)
return { ok: true, worktrees }
} catch {
return { ok: false, worktrees: [] }
} catch (err) {
return (await isTrueEmptyWorktreeListing(repoPath, err))
? { ok: false, worktrees: [], trueEmpty: true }
: { ok: false, worktrees: [] }
}
}
@@ -1,4 +1,4 @@
import type { WorktreeCatalogObservation } from '../../../workspaces/catalog/repo-worktree-catalog-owner'
import type { WorktreeCatalogObservation } from '../../../workspaces/catalog/repo-worktree-catalog-observation'
import type { RuntimeWorktreeScanResult } from './repo-worktree-resolution-scan'
import { dropRepeatedWorktreeRows } from './repeated-worktree-rows'
@@ -150,7 +150,13 @@ export abstract class RuntimeWorkspaceCatalog extends OrcaRuntimeWithReadKittyFi
}
protected pruneUnregisteredWorktreeScans(): void {
retireUnregisteredWorktreeCatalogs(this.store?.getRepos() ?? [])
const store = this.store
if (store) {
retireUnregisteredWorktreeCatalogs(
store.getRepos(),
(repo) => ScanCache.resolveWorktreeScanRuntime(store, repo).runtimeKey
)
}
}
private peekRepoWorktreeObservation(repo: Repo) {
@@ -214,9 +220,10 @@ export abstract class RuntimeWorkspaceCatalog extends OrcaRuntimeWithReadKittyFi
/** The resolution scan plus the checkouts this host's removals own that Git no longer lists. */
protected async listRepoWorktreesForListing(
repo: Repo,
projectRuntimeByRepoId?: ReadonlyMap<string, ProjectExecutionRuntimeResolution>
projectRuntimeByRepoId?: ReadonlyMap<string, ProjectExecutionRuntimeResolution>,
options: { claimsHygiene?: boolean } = {}
): Promise<RuntimeWorktreeScanResult> {
const cached = await this.listRepoWorktreesForResolution(repo, projectRuntimeByRepoId)
const cached = await this.listRepoWorktreesForResolution(repo, projectRuntimeByRepoId, options)
// Paired detectedList must retain folder-upgrade locators or folder ids lose metadata and terminals (#30150).
const scan = { ...cached, worktrees: preserveFolderUpgradeWorktreePath(repo, cached.worktrees) }
const listing =
@@ -235,7 +242,8 @@ export abstract class RuntimeWorkspaceCatalog extends OrcaRuntimeWithReadKittyFi
protected async listRepoWorktreesForResolution(
repo: Repo,
projectRuntimeByRepoId?: ReadonlyMap<string, ProjectExecutionRuntimeResolution>
projectRuntimeByRepoId?: ReadonlyMap<string, ProjectExecutionRuntimeResolution>,
options: { claimsHygiene?: boolean } = {}
): Promise<RuntimeWorktreeScanResult> {
const { projectRuntime, runtimeKey, sshConnectionId } = ScanCache.resolveWorktreeScanRuntime(
this.requireStore(),
@@ -246,7 +254,12 @@ export abstract class RuntimeWorkspaceCatalog extends OrcaRuntimeWithReadKittyFi
if (sshConnectionId) {
return { ok: false, worktrees: this.listStoredWorktreesForResolution(repo) }
}
return await this.readRepoWorktreeCatalog(repo, projectRuntime, runtimeKey)
return await this.readRepoWorktreeCatalog(
repo,
projectRuntime,
runtimeKey,
options.claimsHygiene === true
)
}
listRepos(): Repo[] {
@@ -21,11 +21,13 @@ import {
import {
invalidateWorktreeCatalogForRepo,
peekWorktreeCatalog,
readWorktreeCatalog,
retireUnregisteredWorktreeCatalogs
readWorktreeCatalog
} from '../../../workspaces/catalog/repo-worktree-catalog-owner'
import { runtimeResultForObservation } from './runtime-worktree-catalog-read'
import { worktreeCatalogHygienePlan } from '../../../ipc/worktrees/listing/worktree-catalog-observation-hygiene'
import {
needsWorktreeCatalogHygieneClaim,
worktreeCatalogHygienePlan
} from '../../../ipc/worktrees/listing/worktree-catalog-observation-hygiene'
import type { Store } from '../../../persistence/loading-store/store'
import { SUPERSEDED_SCAN_RESCANS } from '../../../ipc/worktrees/listing/overtaken-scan-rerun'
@@ -53,7 +55,8 @@ export abstract class RuntimeWorkspaceRepoScanRefresh extends RuntimeWorkspaceCa
protected async readRepoWorktreeCatalog(
repo: Repo,
projectRuntime: ProjectExecutionRuntimeResolution | undefined,
runtimeKey: string
runtimeKey: string,
claimsHygiene: boolean
): Promise<RuntimeWorktreeScanResult> {
const gitOptions = getLocalProjectWorktreeGitOptionsForRuntime(repo, projectRuntime)
// E9: the admin reads below and the Git scan both boot a stopped distro; keep known rows until it runs.
@@ -61,8 +64,9 @@ export abstract class RuntimeWorkspaceRepoScanRefresh extends RuntimeWorkspaceCa
wslDistroForPath(repo.path, gitOptions.wslDistro) &&
(await blockedWslDistroForPath(repo.path, gitOptions.wslDistro))
) {
// Known rows only while nothing has invalidated them; otherwise last stored rows, as non-authoritative.
const known = peekWorktreeCatalog(repo, runtimeKey)
return known
return known?.current
? runtimeResultForObservation(known.observation)
: { ok: false, worktrees: this.listStoredWorktreesForResolution(repo) }
}
@@ -87,16 +91,22 @@ export abstract class RuntimeWorkspaceRepoScanRefresh extends RuntimeWorkspaceCa
reusesFailure: true,
// Readers that joined an overtaken scan follow current truth, within the detected listing's bound.
overtakenFlights: SUPERSEDED_SCAN_RESCANS + 1,
...(verifier ? { verifier } : {})
...(verifier ? { verifier } : {}),
...(claimsHygiene ? { needsHygieneClaim: needsWorktreeCatalogHygieneClaim(repo) } : {})
},
{
scan: async () => {
const scan = await scanLocalRepoWorktreesForResolution(repo.path, gitOptions)
return scan.ok
? { kind: 'rows', worktrees: scan.worktrees }
if (scan.ok) {
return { kind: 'rows', worktrees: scan.worktrees }
}
return scan.trueEmpty
? { kind: 'true-empty' }
: { kind: 'failed', error: new Error(`worktree list failed for ${repo.path}`) }
},
...(store ? worktreeCatalogHygienePlan(store as unknown as Store, repo, gitOptions) : {})
...(store
? worktreeCatalogHygienePlan(store as unknown as Store, repo, gitOptions, claimsHygiene)
: {})
}
)
const result = runtimeResultForObservation(observation)
@@ -133,7 +143,7 @@ export abstract class RuntimeWorkspaceRepoScanRefresh extends RuntimeWorkspaceCa
invalidateWorktreeScanCacheForRepo(repoId: string): void {
invalidateWorktreeCatalogForRepo(repoId)
retireUnregisteredWorktreeCatalogs(this.store?.getRepos() ?? [])
this.pruneUnregisteredWorktreeScans()
}
invalidateWorktreeCatalog(repoId: string): void {
@@ -0,0 +1,66 @@
import type { GitWorktreeInfo } from '../../../shared/worktree/types'
/** One `git worktree list`; a confirmed missing/non-repo stays distinct from a failed run. */
export type WorktreeCatalogOutcome =
| { kind: 'rows'; worktrees: GitWorktreeInfo[] }
| { kind: 'true-empty' }
| { kind: 'failed'; error: unknown }
/** Captured before Git runs; destructive consumers claim it at most once. */
export type WorktreeCatalogWitness = {
readonly authorizedRootsRevision: number
readonly hygieneDue: boolean
readonly expectation?: unknown
/** Returns an unconsumed claim so the evidence gate can re-arm. */
readonly release: () => void
}
export type WorktreeCatalogObservation = {
readonly outcome: WorktreeCatalogOutcome
/** Scan start: verification never moves it, so the full-list ceiling cannot slide. */
readonly startedAt: number
readonly generation: number
readonly revision: number
/** Only runtime-started flights fingerprint first; without one the rows cannot be verified. */
readonly adminFingerprint: Promise<string | null> | null
readonly startedBy: WorktreeCatalogReaderKind
witness: WorktreeCatalogWitness | undefined
/** Scan start, or the latest verifier answer that let a runtime reader reuse these rows. */
confirmedAt: number
}
export type WorktreeCatalogFlightPlan = {
scan: () => Promise<WorktreeCatalogOutcome>
captureWitness?: () => WorktreeCatalogWitness | undefined
observed?: (observation: WorktreeCatalogObservation) => void
}
export type WorktreeCatalogVerifier = {
/** Full-list ceiling measured from scan start. */
ceilingMs: number
/** One outstanding probe per repo; 'in-flight' and timeouts reuse rows without proving them (#19312). */
probe: () => Promise<string | null> | 'in-flight'
timeoutMs: number
onUnknown?: (reason: string) => void
}
export type WorktreeCatalogReaderKind = 'desktop' | 'runtime'
export type WorktreeCatalogRequirement = {
kind: WorktreeCatalogReaderKind
/** Oldest confirmation this reader accepts; a fresher demand refreshes the shared observation. */
maxAgeMs: number
/** Reuse failures only from this reader kind's own attempts; another kind's failure never blacks out a retry. */
reusesFailure?: boolean
verifier?: WorktreeCatalogVerifier
/** Trailing flights this read follows when mutations overtake it; callers with their own rescan loop keep 1. */
overtakenFlights?: number
/** Destructive hygiene is due: rows without a pre-scan hygiene claim are not good enough for this reader. */
needsHygieneClaim?: () => boolean
}
export type WorktreeCatalogRead = {
observation: WorktreeCatalogObservation
/** Invalidations kept overtaking scans; callers must not treat these rows as authoritative. */
superseded: boolean
}
@@ -5,10 +5,12 @@ import { bumpWorktreeScanGeneration } from '../../git/worktrees/catalog/worktree
import {
_resetWorktreeCatalogOwnerForTests,
invalidateWorktreeCatalogForRepo,
readWorktreeCatalog,
type WorktreeCatalogFlightPlan,
type WorktreeCatalogOutcome
readWorktreeCatalog
} from './repo-worktree-catalog-owner'
import type {
WorktreeCatalogFlightPlan,
WorktreeCatalogOutcome
} from './repo-worktree-catalog-observation'
const repo = { id: 'repo-1', path: '/repos/app', kind: 'git' } as Repo
const row = (path: string): GitWorktreeInfo => ({
@@ -78,6 +80,30 @@ describe('repo worktree catalog owner', () => {
expect(sidebarRead.observation.outcome).toEqual(rows('/repos/app', '/repos/app-feature'))
})
it('does not let a runtime verification stretch the sidebar past its 5 seconds', async () => {
const plan = scanner([rows('/repos/app'), rows('/repos/app', '/repos/app-external')])
const verifier = {
ceilingMs: 300_000,
timeoutMs: 1_000,
probe: () => Promise.resolve('fingerprint-1')
}
await readWorktreeCatalog(repo, 'local:default', { ...runtime, verifier }, plan)
vi.advanceTimersByTime(31_000)
const verified = await readWorktreeCatalog(
repo,
'local:default',
{ ...runtime, verifier },
plan
)
expect(plan.calls).toBe(1)
expect(verified.observation.outcome).toEqual(rows('/repos/app'))
const sidebar = await readWorktreeCatalog(repo, 'local:default', desktop, plan)
expect(plan.calls).toBe(2)
expect(sidebar.observation.outcome).toEqual(rows('/repos/app', '/repos/app-external'))
})
it('moves readers that joined an overtaken scan onto one trailing scan', async () => {
const plan = scanner([rows('/repos/app'), rows('/repos/app', '/repos/app-new')])
plan.gate = true
@@ -117,6 +143,21 @@ describe('repo worktree catalog owner', () => {
expect(read.observation.outcome).toEqual(rows('/repos/app'))
})
it('retires the old Git runtime so switching back lists again', async () => {
const plan = scanner([
rows('/repos/app'),
rows('/repos/app'),
rows('/repos/app', '/repos/app-new')
])
await readWorktreeCatalog(repo, 'local:native', runtime, plan)
await readWorktreeCatalog(repo, 'local:wsl:Ubuntu', runtime, plan)
const back = await readWorktreeCatalog(repo, 'local:native', runtime, plan)
expect(plan.calls).toBe(3)
expect(back.observation.outcome).toEqual(rows('/repos/app', '/repos/app-new'))
})
it('returns an unclaimed hygiene claim when a newer observation replaces it', async () => {
const release = vi.fn()
const plan = {
@@ -1,77 +1,21 @@
import type { GitWorktreeInfo } from '../../../shared/worktree/types'
import type { Repo } from '../../../shared/repo-types'
import { getRepoExecutionHostId } from '../../../shared/execution-host'
import { areWorktreePathsEqual } from '../../git/worktrees/catalog/worktree-path-comparison'
import { onWorktreeScanGenerationBump } from '../../git/worktrees/catalog/worktree-scan-cache'
import { preserveFolderUpgradeWorktreePath } from './folder-upgrade-worktree-path'
import type {
WorktreeCatalogOutcome,
WorktreeCatalogObservation,
WorktreeCatalogFlightPlan,
WorktreeCatalogVerifier,
WorktreeCatalogRequirement,
WorktreeCatalogRead
} from './repo-worktree-catalog-observation'
import {
getLocalWorktreeScanGeneration,
isLocalWorktreeScanGenerationCurrent
} from './local-worktree-scan-generation'
/** One `git worktree list`; a confirmed missing/non-repo stays distinct from a failed run. */
export type WorktreeCatalogOutcome =
| { kind: 'rows'; worktrees: GitWorktreeInfo[] }
| { kind: 'true-empty' }
| { kind: 'failed'; error: unknown }
/** Captured before Git runs; destructive consumers claim it at most once. */
export type WorktreeCatalogWitness = {
readonly authorizedRootsRevision: number
readonly hygieneDue: boolean
readonly expectation?: unknown
/** Returns an unconsumed claim so the evidence gate can re-arm. */
readonly release: () => void
}
export type WorktreeCatalogObservation = {
readonly outcome: WorktreeCatalogOutcome
/** Scan start: verification never moves it, so the full-list ceiling cannot slide. */
readonly startedAt: number
readonly generation: number
readonly revision: number
/** Only runtime-started flights fingerprint first; without one the rows cannot be verified. */
readonly adminFingerprint: Promise<string | null> | null
readonly startedBy: WorktreeCatalogReaderKind
witness: WorktreeCatalogWitness | undefined
/** Scan start, or the latest verifier answer that let a reader reuse these rows. */
confirmedAt: number
}
export type WorktreeCatalogFlightPlan = {
scan: () => Promise<WorktreeCatalogOutcome>
captureWitness?: () => WorktreeCatalogWitness | undefined
observed?: (observation: WorktreeCatalogObservation) => void
}
export type WorktreeCatalogVerifier = {
/** Full-list ceiling measured from scan start. */
ceilingMs: number
/** One outstanding probe per repo; 'in-flight' and timeouts reuse rows without proving them (#19312). */
probe: () => Promise<string | null> | 'in-flight'
timeoutMs: number
onUnknown?: (reason: string) => void
}
export type WorktreeCatalogReaderKind = 'desktop' | 'runtime'
export type WorktreeCatalogRequirement = {
kind: WorktreeCatalogReaderKind
/** Oldest confirmation this reader accepts; a fresher demand refreshes the shared observation. */
maxAgeMs: number
/** Reuse failures only from this reader kind's own attempts; another kind's failure never blacks out a retry. */
reusesFailure?: boolean
verifier?: WorktreeCatalogVerifier
/** Trailing flights this read follows when mutations overtake it; callers with their own rescan loop keep 1. */
overtakenFlights?: number
}
export type WorktreeCatalogRead = {
observation: WorktreeCatalogObservation
/** Invalidations kept overtaking scans; callers must not treat these rows as authoritative. */
superseded: boolean
}
type Flight = {
revision: number
promise: Promise<WorktreeCatalogObservation>
@@ -80,7 +24,9 @@ type Flight = {
type Entry = {
repoId: string
repoPath: string
runtimeKey: string
revision: number
retired: boolean
success: WorktreeCatalogObservation | null
failure: WorktreeCatalogObservation | null
flight: Flight | null
@@ -90,9 +36,13 @@ const entries = new Map<string, Entry>()
onWorktreeScanGenerationBump((repoPath) => invalidateWorktreeCatalogForRepoPath(repoPath))
function repoScope(repo: Repo): string {
return `${repo.id}\0${getRepoExecutionHostId(repo)}\0`
}
/** Owner identity: repo, host and the project runtime that runs Git (distro, selected Git, repair state). */
function entryKey(repo: Repo, runtimeKey: string): string {
return `${repo.id}\0${getRepoExecutionHostId(repo)}\0${runtimeKey}`
return `${repoScope(repo)}${runtimeKey}`
}
function releaseWitness(observation: WorktreeCatalogObservation | null): void {
@@ -105,30 +55,60 @@ function releaseWitness(observation: WorktreeCatalogObservation | null): void {
function retireEntry(key: string, entry: Entry): void {
entries.delete(key)
entry.retired = true
entry.revision += 1
releaseWitness(entry.success)
}
/** The live owner for this repo and runtime; a path or runtime change retires the old one. */
function resolveEntry(repo: Repo, runtimeKey: string): { key: string; entry: Entry } {
const key = entryKey(repo, runtimeKey)
const scope = repoScope(repo)
for (const [candidateKey, candidate] of entries) {
// One project runtime runs a repo's Git at a time; rows from another one are obsolete.
if (
candidateKey.startsWith(scope) &&
(candidateKey !== key || !areWorktreePathsEqual(candidate.repoPath, repo.path))
) {
retireEntry(candidateKey, candidate)
}
}
let entry = entries.get(key)
if (!entry) {
entry = {
repoId: repo.id,
repoPath: repo.path,
runtimeKey,
revision: 0,
retired: false,
success: null,
failure: null,
flight: null
}
entries.set(key, entry)
}
return { key, entry }
}
function isCurrent(entry: Entry, observation: WorktreeCatalogObservation): boolean {
return (
!entry.retired &&
observation.revision === entry.revision &&
isLocalWorktreeScanGenerationCurrent(entry.repoId, observation.generation)
)
}
function startFlight(
key: string,
entry: Entry,
repo: Repo,
requirement: WorktreeCatalogRequirement,
plan: WorktreeCatalogFlightPlan,
pendingProbe: Promise<string | null> | null
plan: WorktreeCatalogFlightPlan
): Flight {
// Capture before Git can yield so a concurrent mutation is never stamped as observed.
const revision = entry.revision
const generation = getLocalWorktreeScanGeneration(entry.repoId)
const startedAt = Date.now()
const probe = pendingProbe ?? requirement.verifier?.probe() ?? null
const probe = requirement.verifier?.probe() ?? null
const adminFingerprint = probe && probe !== 'in-flight' ? probe : null
const witness = plan.captureWitness?.()
const flight: Flight = {
@@ -157,7 +137,7 @@ function startFlight(
if (entry.flight === flight) {
entry.flight = null
}
publish(key, entry, observation, plan)
publish(entry, observation, plan)
return observation
})
}
@@ -166,21 +146,20 @@ function startFlight(
}
function publish(
key: string,
entry: Entry,
observation: WorktreeCatalogObservation,
plan: WorktreeCatalogFlightPlan
): void {
const retired = entries.get(key) !== entry
if (observation.outcome.kind === 'failed') {
releaseWitness(observation)
if (!retired && (entry.failure?.startedAt ?? -1) <= observation.startedAt) {
// Like the evidence gate's own claim, a failed pass is not retried on every read (#17775); new evidence re-arms it.
observation.witness = undefined
if (!entry.retired && (entry.failure?.startedAt ?? -1) <= observation.startedAt) {
entry.failure = observation
}
return
}
// A retired owner or a newer published observation keeps late completions out.
if (retired || (entry.success?.startedAt ?? -1) > observation.startedAt) {
if (entry.retired || (entry.success?.startedAt ?? -1) > observation.startedAt) {
releaseWitness(observation)
return
}
@@ -194,21 +173,24 @@ function publish(
}
}
type Verification = { reuse: true } | { reuse: false; probe: Promise<string | null> | null }
/** True when a probe proves, or cannot yet disprove (#19312), that rows with a pre-scan fingerprint still hold. */
async function verify(
observation: WorktreeCatalogObservation,
verifier: WorktreeCatalogVerifier,
now: number
): Promise<Verification> {
if (observation.outcome.kind !== 'rows' || now - observation.startedAt >= verifier.ceilingMs) {
return { reuse: false, probe: null }
): Promise<boolean> {
// Without a fingerprint from before its scan, no probe can certify these rows.
if (
observation.outcome.kind !== 'rows' ||
!observation.adminFingerprint ||
now - observation.startedAt >= verifier.ceilingMs
) {
return false
}
// Probe before any rescan so changes during it cannot be stamped as already observed.
const probe = verifier.probe()
if (probe === 'in-flight') {
verifier.onUnknown?.('previous probe still pending')
return { reuse: true }
return true
}
let timer: ReturnType<typeof setTimeout> | undefined
const timeout = new Promise<'timeout'>((resolve) => {
@@ -218,75 +200,67 @@ async function verify(
if (current === 'timeout') {
// Unknown is not proof, but rescanning slow mounts on every read amplifies load (#19312).
verifier.onUnknown?.('probe expired')
return { reuse: true }
return true
}
const recorded = observation.adminFingerprint ? await observation.adminFingerprint : null
// Only a known fingerprint taken before this observation's scan proves nothing changed.
return current !== null && recorded === current ? { reuse: true } : { reuse: false, probe }
return current !== null && (await observation.adminFingerprint) === current
}
function acceptsAge(
function acceptable(
observation: WorktreeCatalogObservation,
requirement: WorktreeCatalogRequirement,
now: number
): boolean {
return now - observation.confirmedAt <= requirement.maxAgeMs
if (requirement.needsHygieneClaim?.() && !observation.witness?.hygieneDue) {
return false
}
// Verifier confirmations are a runtime admission; other readers need a full observation that young.
const basis = requirement.verifier ? observation.confirmedAt : observation.startedAt
return now - basis <= requirement.maxAgeMs
}
/** The sole owner of a repo's raw worktree rows: readers state what they accept and share its flights. */
/** The sole owner of a repo's raw worktree rows: readers state what they accept and share its one flight. */
export async function readWorktreeCatalog(
repo: Repo,
runtimeKey: string,
requirement: WorktreeCatalogRequirement,
plan: WorktreeCatalogFlightPlan
): Promise<WorktreeCatalogRead> {
const key = entryKey(repo, runtimeKey)
let entry = entries.get(key)
if (entry && !areWorktreePathsEqual(entry.repoPath, repo.path)) {
retireEntry(key, entry)
entry = undefined
}
if (!entry) {
entry = {
repoId: repo.id,
repoPath: repo.path,
revision: 0,
success: null,
failure: null,
flight: null
}
entries.set(key, entry)
}
let last: WorktreeCatalogObservation | null = null
const { entry } = resolveEntry(repo, runtimeKey)
for (let flights = 0; flights < (requirement.overtakenFlights ?? 1); flights += 1) {
// A newer runtime or path took over this repo mid-read; this reader's rows stay non-authoritative.
if (entry.retired && last) {
break
}
const now = Date.now()
const failure = entry.failure
if (
requirement.reusesFailure &&
failure?.startedBy === requirement.kind &&
isCurrent(entry, failure) &&
acceptsAge(failure, requirement, now)
now - failure.startedAt <= requirement.maxAgeMs
) {
return { observation: failure, superseded: false }
}
const success = entry.success
let pendingProbe: Promise<string | null> | null = null
if (success && isCurrent(entry, success)) {
if (acceptsAge(success, requirement, now)) {
if (acceptable(success, requirement, now)) {
return { observation: success, superseded: false }
}
if (requirement.verifier) {
const verification = await verify(success, requirement.verifier, now)
if (verification.reuse && entry.success === success && isCurrent(entry, success)) {
success.confirmedAt = Math.max(success.confirmedAt, Date.now())
return { observation: success, superseded: false }
}
pendingProbe = verification.reuse ? null : verification.probe
if (
requirement.verifier &&
!requirement.needsHygieneClaim?.() &&
(await verify(success, requirement.verifier, now)) &&
entry.success === success &&
isCurrent(entry, success)
) {
success.confirmedAt = Math.max(success.confirmedAt, Date.now())
return { observation: success, superseded: false }
}
}
const joinable = entry.flight?.revision === entry.revision ? entry.flight : null
last = await (joinable ?? startFlight(key, entry, repo, requirement, plan, pendingProbe))
.promise
// At most one flight per owner: a reader arriving after an invalidation waits for the
// overtaken flight, then starts the single trailing one.
last = await (entry.flight ?? startFlight(entry, repo, requirement, plan)).promise
if (isCurrent(entry, last)) {
return { observation: last, superseded: false }
}
@@ -325,12 +299,14 @@ export function invalidateWorktreeCatalogForRepoPath(repoPath: string): void {
}
}
/** Drop owners whose repo or host registration is gone; late completions cannot recreate them. */
export function retireUnregisteredWorktreeCatalogs(registered: readonly Repo[]): void {
const live = new Set(registered.map((repo) => `${repo.id}\0${getRepoExecutionHostId(repo)}\0`))
/** Drop owners whose repo, host or project runtime is gone; late completions cannot recreate them. */
export function retireUnregisteredWorktreeCatalogs(
registered: readonly Repo[],
runtimeKeyFor: (repo: Repo) => string
): void {
const live = new Set(registered.map((repo) => entryKey(repo, runtimeKeyFor(repo))))
for (const [key, entry] of entries) {
const prefix = key.slice(0, key.lastIndexOf('\0') + 1)
if (!live.has(prefix)) {
if (!live.has(key)) {
retireEntry(key, entry)
}
}
@@ -341,7 +317,3 @@ export function _resetWorktreeCatalogOwnerForTests(): void {
retireEntry(key, entry)
}
}
export function _getWorktreeCatalogOwnerSizeForTests(): number {
return entries.size
}