[codex] Add local macOS integration harness

[xcv58]

What changed

• added a local-only ShortcutCycleIntegrationTests harness for real app switching on macOS
• added a hidden app-side integration runtime that imports a fixture, listens for harness commands, and emits fixtureLoaded, hudPresented, switchFinalized, and error events
• added a checked-in HUD fixture, a local runner script, screenshot capture support, and optional playback video generation from captured PNG frames
• updated the harness screenshot selection so captures follow the relevant visible window first, with fallback display selection when that lookup fails

Why this changed

We needed a real macOS integration path that exercises the production switching flow against actual system apps instead of only unit-level abstractions. This gives us deterministic fixture setup, real frontmost-app assertions, and visual artifacts developers can inspect locally.

Developer impact

• developers can run bash scripts/run_integration_harness.sh locally to build the isolated integration app, launch Calculator and Chess, execute the three-cycle scenario, and save screenshots under .artifacts/integration/<run-id>
• --video can assemble a playback MP4 from the captured frames when ffmpeg is available
• the app uses an isolated bundle identifier for the integration run so defaults and sandbox state stay separate from the normal dev app

Root cause addressed

The earlier harness work had two main problems:

1. the app and test process needed a reliable private command/event channel and deterministic fixture bootstrap path inside the sandboxed integration container
2. screenshot/video capture needed to stop blindly recording the wrong display when multiple monitors were connected

This PR adds the sandbox-aware harness plumbing and makes frame capture follow the relevant visible window before falling back to display preference heuristics.

Validation

• passed: xcodebuild build-for-testing -project ShortcutCycle/ShortcutCycle.xcodeproj -scheme ShortcutCycleIntegration -configuration Debug -destination 'platform=macOS' -derivedDataPath .artifacts/xcode-integration/DerivedData -clonedSourcePackagesDirPath .artifacts/xcode-integration/SourcePackages SHORTCUTCYCLE_APP_BUNDLE_IDENTIFIER=com.xcv58.ShortcutCycle.Integration
• exercised repeatedly: bash ShortcutCycle/scripts/run_integration_harness.sh

Known issue

The real happy-path integration run still has an intermittent frontmost-app flake during the final assertion phase. The draft is intentional so we can review the harness structure and current behavior while that macOS focus race is still being tightened up.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
shortcut-cycle	Ready	Preview, Comment	Apr 5, 2026 8:08pm

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (ad6263b) to head (5ab28b9).

Additional details and impacted files

@@            Coverage Diff            @@
##            master       #42   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           11        11           
  Lines         1191      1191           
=========================================
  Hits          1191      1191           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.