Fix FSEvents delivery liveness

[baron]

Summary

• replace all blocking FSEventStreamFlushSync calls in watcher activation, metadata monitoring, and worktree creation witnessing with asynchronous event-ID delivery barriers
• scope delivery watermarks to stream generations, reject stale callbacks after restart or journal wrap, and tear streams down on their callback queues
• remove the global flush circuit breaker/quarantine machinery and replace timing-based tests with injected delivery/deadline oracles

Why

The shard-2 worktree API smoke reached create-start.tab-ready and then timed out at 180 seconds. That leg uniquely enters the worktree-creation witness and watcher activation paths. Those paths used synchronous FSEvents flushes that can block indefinitely when the host does not deliver the cut. This is a production liveness bug exposed by the integration smoke, not a concurrency condition the test should tolerate.

The new contract is deterministic: the callback observes the exact asynchronous flush target for the current stream generation, or the optimization fails closed to its existing fallback. No sleeps, timeout inflation, CI workflow changes, global serialization, or reduced concurrency.

Validation

• WorktreeAPISmokeHarnessTests/testManageWorktreeAndAgentRunAPISmokeFlow (7.392s)
• FileSystemAcceptedIngressBarrierTests (21 executed, 1 skipped, 0 failures)
• WorkspaceRootCreationReceiptCoordinatorTests (11/11)
• GitLoadedRootAuthorityEvidenceTests (48 executed, 2 skipped, 0 failures)
• AgentRunWorktreeStartTests (51/51)
• GitWorkspaceStateAuthorityTests (8/8)
• make dev-swift-build PRODUCT=RepoPrompt
• make dev-lint
• commit and push contribution preflights

A full local root-suite attempt was not counted as green: it stopped making progress in the unrelated CodemapBindingEngineRootLeaseTests/testSequentialRootsRetainGlobalAdoptionLeaseBudgetUntilUnloadThenRecover. Fresh exact-head hosted CI is required before merge.

[baron]

Triage: current-main textual integration is clean and the historical failure was unrelated, but this is a broad state-sensitive FSEvents generation/liveness change with no human review. As author I cannot self-approve; please obtain non-author lifecycle review and fresh hosted integration evidence.

[baron]

Blocking current-main recheck on exact head 20f28670b1a8e488104164ffbf2bef9954ac14e2.

App shard 1 fails StoreBackedWorkspaceSearchTests.testMutationAfterCatalogCrawlBeforeWatcherStartIsVisibleToFreshSearch (expected Late.swift, got nil). That test exercises the crawl-to-watcher replay/liveness invariant this PR changes through FSEventStreamFlushAsync and the new callback barrier, so it cannot be classified as unrelated without a root-cause investigation.

Please reproduce/diagnose the missed mutation, fix the owning boundary, and rerun exact-current-base CI. Do not add sleeps, retries, or timeout inflation. I am commenting rather than submitting REQUEST_CHANGES because the authenticated reviewer is also the PR author.

[morluto]

Audit disposition — merge candidate after current hosted CI and macOS stress (2026-08-14)

Replacing synchronous FSEvents flushes with an event-ID delivery barrier scoped to a stream generation is the right liveness model. The wrap reset, stale-callback rejection, fail-closed fallback, and callback-queue teardown appear internally coherent.

Please run exact-head hosted CI plus macOS stress for immediate create/rename after activation, rapid start/stop/restart, journal wrap/reset, and worktree creation witnessing. I did not find a static blocker in the reviewed design.

[morluto]

Deep-review assessment — 2026-08-14

Disposition: merge candidate after exact-head macOS CI/stress. Replacing synchronous FSEvents flushes with generation-scoped event-ID barriers is the right liveness model. The implementation rejects stale callbacks, resets on journal wrap, fails closed to existing fallback behavior, and tears streams down on their callback queues rather than blocking a cooperative thread.

I did not find a must-fix in the reviewed design. Final evidence should include current merge-ref CI and repeated macOS create/rename/delete operations immediately after watcher activation, stream restart, timeout, and journal-wrap injection. If those remain green, this is a focused production-liveness correction.