From ea5d772f8ac8dddb86b4ac7247d659ccd542df6a Mon Sep 17 00:00:00 2001 From: Brennan Benson <79079362+brennanb2025@users.noreply.github.com> Date: Wed, 11 Nov 2026 20:56:40 -0800 Subject: [PATCH] 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) --- .../git/worktrees/catalog/worktree-listing.ts | 2 +- .../worktree-base-directory-watch-events.ts | 3 + .../listing/detected-worktree-scan-cache.ts | 9 +- ...rktree-catalog-observation-hygiene.test.ts | 57 +++++ .../worktree-catalog-observation-hygiene.ts | 17 +- .../runtime-construction-services.ts | 3 +- .../construction/runtime-service-state.ts | 3 +- .../worktree-selector-resolution.spec.ts | 2 + .../catalog/repo-worktree-resolution-scan.ts | 14 +- .../catalog/runtime-worktree-catalog-read.ts | 2 +- .../workspaces/catalog/workspace-catalog.ts | 23 +- .../catalog/workspace-repo-scan-refresh.ts | 30 ++- .../repo-worktree-catalog-observation.ts | 66 +++++ .../repo-worktree-catalog-owner.test.ts | 47 +++- .../catalog/repo-worktree-catalog-owner.ts | 228 ++++++++---------- 15 files changed, 345 insertions(+), 161 deletions(-) create mode 100644 src/main/ipc/worktrees/listing/worktree-catalog-observation-hygiene.test.ts create mode 100644 src/main/workspaces/catalog/repo-worktree-catalog-observation.ts diff --git a/src/main/git/worktrees/catalog/worktree-listing.ts b/src/main/git/worktrees/catalog/worktree-listing.ts index 44f9dcc97d2..2106e79b43a 100644 --- a/src/main/git/worktrees/catalog/worktree-listing.ts +++ b/src/main/git/worktrees/catalog/worktree-listing.ts @@ -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 { +export async function isTrueEmptyWorktreeListing(repoPath: string, err: unknown): Promise { if (getErrorCode(err) === 'ENOENT') { try { await stat(repoPath) diff --git a/src/main/ipc/worktrees/creation/worktree-base-directory-watch-events.ts b/src/main/ipc/worktrees/creation/worktree-base-directory-watch-events.ts index 35b9ac4caf0..dedc17f5602 100644 --- a/src/main/ipc/worktrees/creation/worktree-base-directory-watch-events.ts +++ b/src/main/ipc/worktrees/creation/worktree-base-directory-watch-events.ts @@ -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()] }) } diff --git a/src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts b/src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts index 7ac6024a906..37d898a6e02 100644 --- a/src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts +++ b/src/main/ipc/worktrees/listing/detected-worktree-scan-cache.ts @@ -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') { diff --git a/src/main/ipc/worktrees/listing/worktree-catalog-observation-hygiene.test.ts b/src/main/ipc/worktrees/listing/worktree-catalog-observation-hygiene.test.ts new file mode 100644 index 00000000000..02767a97725 --- /dev/null +++ b/src/main/ipc/worktrees/listing/worktree-catalog-observation-hygiene.test.ts @@ -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) + }) +}) diff --git a/src/main/ipc/worktrees/listing/worktree-catalog-observation-hygiene.ts b/src/main/ipc/worktrees/listing/worktree-catalog-observation-hygiene.ts index 2b3e7fee0eb..dc87be127c2 100644 --- a/src/main/ipc/worktrees/listing/worktree-catalog-observation-hygiene.ts +++ b/src/main/ipc/worktrees/listing/worktree-catalog-observation-hygiene.ts @@ -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 { 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) +} diff --git a/src/main/runtime/construction/runtime-construction-services.ts b/src/main/runtime/construction/runtime-construction-services.ts index 6c1c4baadcd..4355681c618 100644 --- a/src/main/runtime/construction/runtime-construction-services.ts +++ b/src/main/runtime/construction/runtime-construction-services.ts @@ -210,7 +210,8 @@ export abstract class RuntimeConstructionServices { protected abstract selectReposBySelector(selector: string): Repo[] protected abstract listRepoWorktreesForListing( repo: Repo, - projectRuntimeByRepoId?: ReadonlyMap + projectRuntimeByRepoId?: ReadonlyMap, + options?: { claimsHygiene?: boolean } ): Promise protected abstract listKnownExecutionHostIds( additionalHostIds?: Iterable, diff --git a/src/main/runtime/construction/runtime-service-state.ts b/src/main/runtime/construction/runtime-service-state.ts index 8605f52bc5a..0afb914a22b 100644 --- a/src/main/runtime/construction/runtime-service-state.ts +++ b/src/main/runtime/construction/runtime-service-state.ts @@ -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() }) diff --git a/src/main/runtime/orca-runtime-tests/worktree-selector-resolution.spec.ts b/src/main/runtime/orca-runtime-tests/worktree-selector-resolution.spec.ts index 3db5b63dec5..4f6f9006b8f 100644 --- a/src/main/runtime/orca-runtime-tests/worktree-selector-resolution.spec.ts +++ b/src/main/runtime/orca-runtime-tests/worktree-selector-resolution.spec.ts @@ -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) diff --git a/src/main/runtime/workspaces/catalog/repo-worktree-resolution-scan.ts b/src/main/runtime/workspaces/catalog/repo-worktree-resolution-scan.ts index 05a118f2ebf..809fc1e308c 100644 --- a/src/main/runtime/workspaces/catalog/repo-worktree-resolution-scan.ts +++ b/src/main/runtime/workspaces/catalog/repo-worktree-resolution-scan.ts @@ -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: [] } } } diff --git a/src/main/runtime/workspaces/catalog/runtime-worktree-catalog-read.ts b/src/main/runtime/workspaces/catalog/runtime-worktree-catalog-read.ts index 39138075ecf..c807c98ce1c 100644 --- a/src/main/runtime/workspaces/catalog/runtime-worktree-catalog-read.ts +++ b/src/main/runtime/workspaces/catalog/runtime-worktree-catalog-read.ts @@ -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' diff --git a/src/main/runtime/workspaces/catalog/workspace-catalog.ts b/src/main/runtime/workspaces/catalog/workspace-catalog.ts index 855010db0b4..523c3a15fe3 100644 --- a/src/main/runtime/workspaces/catalog/workspace-catalog.ts +++ b/src/main/runtime/workspaces/catalog/workspace-catalog.ts @@ -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 + projectRuntimeByRepoId?: ReadonlyMap, + options: { claimsHygiene?: boolean } = {} ): Promise { - 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 + projectRuntimeByRepoId?: ReadonlyMap, + options: { claimsHygiene?: boolean } = {} ): Promise { 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[] { diff --git a/src/main/runtime/workspaces/catalog/workspace-repo-scan-refresh.ts b/src/main/runtime/workspaces/catalog/workspace-repo-scan-refresh.ts index d44f113b0ca..2d65c87f1e1 100644 --- a/src/main/runtime/workspaces/catalog/workspace-repo-scan-refresh.ts +++ b/src/main/runtime/workspaces/catalog/workspace-repo-scan-refresh.ts @@ -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 { 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 { diff --git a/src/main/workspaces/catalog/repo-worktree-catalog-observation.ts b/src/main/workspaces/catalog/repo-worktree-catalog-observation.ts new file mode 100644 index 00000000000..200b0c9c291 --- /dev/null +++ b/src/main/workspaces/catalog/repo-worktree-catalog-observation.ts @@ -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 | 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 + 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 | '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 +} diff --git a/src/main/workspaces/catalog/repo-worktree-catalog-owner.test.ts b/src/main/workspaces/catalog/repo-worktree-catalog-owner.test.ts index 66060d4cec6..58a5120dcc6 100644 --- a/src/main/workspaces/catalog/repo-worktree-catalog-owner.test.ts +++ b/src/main/workspaces/catalog/repo-worktree-catalog-owner.test.ts @@ -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 = { diff --git a/src/main/workspaces/catalog/repo-worktree-catalog-owner.ts b/src/main/workspaces/catalog/repo-worktree-catalog-owner.ts index 7b785e6d6c4..3bfe97e1f2e 100644 --- a/src/main/workspaces/catalog/repo-worktree-catalog-owner.ts +++ b/src/main/workspaces/catalog/repo-worktree-catalog-owner.ts @@ -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 | 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 - 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 | '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 @@ -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() 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 | 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 | 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 { - if (observation.outcome.kind !== 'rows' || now - observation.startedAt >= verifier.ceilingMs) { - return { reuse: false, probe: null } +): Promise { + // 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 | 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 { - 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 | 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 -}