Close directory watcher descriptors after failed startup

[stephenlclarke]

Important

All commits are signed and verified.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

During testing of my Container Compose plugin, I found and fixed a path-specific file-descriptor leak in DirectoryWatcher. _startWatching opens an O_EVTONLY descriptor before it lists the directory and calls the handler. If either operation throws, the dispatch source that normally owns and closes the descriptor is never created. The retry loop can therefore leak one descriptor on every failed startup.

This submission retains the correct production fix from #1773 and credits its author, @muk2. It supersedes that proposal with deterministic regression coverage: the test identifies only descriptors whose F_GETPATH resolves to the watched directory, verifies the failing handler ran exactly 32 times, and requires the path-specific count to return to its exact baseline. It also accepts valid descriptor zero, makes the internal escaping handler contract @Sendable, and replaces fixed-sleep test races with explicit watcher readiness and restart synchronisation, bounded condition polling, and locked snapshots.

This PR deliberately does not close #1097. That issue reproduces descriptor growth from guest filesystem traversal through virtiofs, while DirectoryWatcher is used by the host DNS resolver configuration watcher. The available evidence does not establish that this code path causes #1097.

Fixes #2034

Reproduction on stock Apple main

Base tested: 48145ac7fb177d9fb14e015a0bdea4c642b36729. A test-only visibility and @Sendable annotation were applied to the stock method so the regression test could invoke it; the stock descriptor guard and missing error-path close were left unchanged.

/usr/bin/swift test --skip-build -c debug \
  -Xswiftc -warnings-as-errors -Xswiftc -enable-testing \
  --filter testFailingHandlerDoesNotLeakDescriptors

Actual stock result: the single test fails in 0.010 seconds with baseline=0 and afterFailures=32.

Expected result: after 32 intentional handler failures, the number of descriptors resolving to the watched path equals the baseline.

Changes

• Close the opened descriptor when directory enumeration or the initial handler throws.
• Treat descriptor zero as a successful open result.
• Require the stored handler to be @Sendable, matching the public API and dispatch-source use.
• Replace the process-wide descriptor threshold with exact path-specific leak detection.
• Verify all 32 handler invocations occurred.
• Replace fixed sleeps and force unwraps in existing watcher tests with explicit watcher-state synchronisation, locked snapshots, bounded condition polling, and phase-gating requirements.
• Remove the obsolete watcher fixture and its unnecessary force unwrap.

Testing

• Tested locally

• Added/updated tests

• Added/updated docs

• make check: passed in 4.84 seconds wall time.

• swift test --filter DirectoryWatcherTest: 5 tests in 1 suite passed in 1.081 seconds on the final head; 5.84 seconds wall time including the incremental build.

• Stability run: 10 consecutive swift test --filter DirectoryWatcherTest attempts passed, 50 tests total; suite times remained between 1.062 and 1.092 seconds, with cached wall times between 1.89 and 1.97 seconds after the first build refresh.

• make test: 590 tests in 71 suites passed in 1.266 seconds on the final head; 114.91 seconds wall time including the 105.82-second full rebuild.

• Stock negative control: the targeted test failed as expected in 0.010 seconds, reporting exactly 32 leaked descriptors for the watched path; 0.63 seconds wall time.

• git diff --check: passed.

• All seven commits verified with the configured signing key.