Changelog: FSEvents Maildir Watcher & Bus Latency Benchmarking (FEAT-20260905-41, TASK-20260924-11)

Timestamp: 2026-09-24 23:48:00 EDT
Host: rdmpw3265m (Intel Xeon W-3265M, macOS 26.7)
Agent: agy@rdmpw3265m/1b772f66-eb66-4280-b839-1638b7406470
Project: Tyrell (~/dev/apps/Tyrell)
Tickets: FEAT-20260905-41, TASK-20260924-11 (RESOLVED)

1. Summary of Changes

• CoreServices FSEvents Stream (FSEventMaildirWatcher.swift):
  • Implemented FSEventMaildirWatcher wrapping CoreServices FSEventStreamCreate on dedicated dispatch queue com.eastcoastscience.tyrell.maildirwatcher with low-latency kernel notifications (kFSEventStreamCreateFlagUseCFTypes | kFSEventStreamCreateFlagFileEvents | kFSEventStreamCreateFlagNoDefer).
  • Replaces periodic readdir polling of 6,800+ files in ~/.agent-coordination/mail every 5 seconds, reclaiming ~0.7 percentage points of continuous single-core CPU overhead.
  • Implemented rolling BusLatencyTelemetry (samples, min, max, avg, median, p95) and BusLatencyBenchmark harness.
• Service Integration (FleetObserver.swift):
  • Added useFSEventsWatcher: Bool = true to FleetObserverConfig.
  • Wired maildirWatcher into FleetObservationService.start(...) and stop().
  • When the FSEvents watcher is active, the background loop bypasses 5-second readdir scanning and sleeps for the full observation interval (30 seconds), reacting instantly on mail landing.
• Test Suite (FSEventMaildirWatcherTests.swift):
  • Added 6 comprehensive Swift Testing unit and benchmark tests: lifecycle, file change detection, latency math, benchmark SLA validation (< 500ms target; measured ~62ms median), config parsing, and service integration.

2. Verification Evidence

• Build: swift build rc=0, clean compilation across all targets.
• Test Results:
  • FSEventMaildirWatcherTests: 6/6 tests passed (100%), 0 failures.
  • FleetObservationTests: 51/51 tests across 11 suites passed (100%), 0 failures.
  • AgentBusProjectorTests: 4/4 tests passed (100%), 0 failures.
• Static Gate: scripts/verify_zero_fleet_identity.zsh exited 0 (0 compiled-in fleet identity violations in Sources/).
• Git Lineage:
  • Feature branch agy/fsevents-maildir-watcher-FEAT-20260905-41 (commit d04c021).
  • Integration merge into canonical main (5c98feb) with TYRELL_CANONICAL_INTEGRATION=1.
  • Synchronized across remotes: fleet (git.ecs0.net:git/apps/Tyrell.git) and backup (github.com/richhdoty/rdmsm4x-dev-apps-tyrell.git).
• Ticket Store & Wiki:
  • Both tickets marked RESOLVED in issueRoo; committed on rdmsm4x:~/dev/issues (6789258).
  • Exported 1,227 wiki HTML pages; committed and pushed to dev.ecs0.net (a33cc10).
  • Fleet announcement broadcast via agent_msg.zsh: 20260924-234817-DE8598DE.