App stops working after macOS upgrade

[m96-chan]

Summary

After upgrading macOS (e.g., to 15.6 / Sequoia), KTApple may stop working entirely — nothing is displayed (no menu bar icon, no tiling). The app process may or may not be running in the background.

Environment

• macOS 15.6 (Build 24G84)
• Xcode 26.1.1 / Swift 6.2.1
• Build and tests pass (291 tests OK) on a fresh build

Root Cause Analysis

Several factors can cause breakage after a macOS upgrade:

1. TCC (Accessibility permission) reset

macOS upgrades frequently reset the TCC database, revoking previously granted Accessibility permissions. Without Accessibility access:

• AXIsProcessTrusted() returns false
• AppCoordinator.start() runs but accessibilityGranted is false
• No windows are discovered or managed
• The app opens System Settings for re-authorization, but the URL scheme may have changed (see Implement WindowManager (Accessibility API wrapper) #3)

The status bar icon should still appear even without accessibility, but the app is effectively non-functional.

2. Ad-hoc code signing invalidation

KTApple uses ad-hoc signing (codesign --force --sign -). After a macOS upgrade:

• The system may re-validate code signatures with stricter Gatekeeper policies
• Ad-hoc signed apps without a Team ID may be blocked or quarantined
• The com.apple.provenance xattr may trigger additional checks
• Users who installed via Homebrew with --no-quarantine may find that protection removed

3. System Settings URL scheme change

The app uses x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility to guide users to the Accessibility settings. This URL scheme has changed across macOS versions and may silently fail on newer versions, preventing users from re-granting permission.

4. Private API _AXUIElementGetWindow breakage

AppDelegate.updateFocusedWindow() uses the undocumented _AXUIElementGetWindow() function to map AXUIElement → CGWindowID. This private API is not guaranteed to be stable across macOS versions and could be removed or change its signature.

5. Binary/SDK compatibility

The installed binary (built with an older Xcode/SDK) may have ABI or runtime incompatibilities with the new macOS version. Rebuilding from source with the current Xcode resolves this, but end users installing via Homebrew won't automatically get a rebuilt binary.

Steps to Reproduce

1. Install KTApple on macOS ≤ 15.5 — confirm it works
2. Upgrade macOS to 15.6
3. Launch KTApple — observe that nothing is displayed

Expected Behavior

KTApple should either continue working after a macOS upgrade, or clearly guide the user through any required re-configuration (e.g., re-granting accessibility permission).

Proposed Fixes

• Detect and handle TCC reset: Show a clear in-app notification when accessibility is revoked, with a working link to the correct System Settings pane
• Verify System Settings URL: Test the URL scheme on macOS 15.6 and add fallback URLs for different macOS versions
• Add launch diagnostics: Log the macOS version, Xcode SDK version, accessibility status, and code signing status on startup to aid debugging
• Document upgrade procedure: Add a troubleshooting section to README for post-upgrade recovery (re-grant accessibility, reinstall if needed)
• Consider replacing _AXUIElementGetWindow: Investigate public API alternatives or add a graceful fallback
• Homebrew formula rebuild trigger: Ensure the Homebrew tap rebuilds against new macOS SDKs when they ship