Fix Computer Use onboarding and preference notification deadlocks

Packages/macOS/CmuxFoundation/Sources/CmuxFoundation/NotificationCenter+UserDefaults.swift

@@ -0,0 +1,29 @@
+public import Foundation
+
+extension NotificationCenter {
+    /// Observes preference changes on the main actor without blocking background writers.
+    ///
+    /// Main-thread posts retain synchronous delivery. Background posts schedule
+    /// the callback and return before it runs. Foundation's `queue: .main`
+    /// observer blocks the posting thread, which can deadlock a lazy initializer
+    /// when the main thread is waiting for its value.
+    ///
+    /// - Parameters:
+    ///   - object: The preferences object to observe, or `nil` for all objects.
+    ///   - handler: The main-actor action that re-reads the current preferences.
+    /// - Returns: An observer token to remove with `removeObserver(_:)` at teardown.
+    public func addUserDefaultsObserver(
+        object: AnyObject? = nil,
+        using handler: @escaping @MainActor @Sendable () -> Void
+    ) -> any NSObjectProtocol {
+        // This callback is the Foundation notification boundary. Never make a
+        // preference writer wait for an operation on the main queue.
+        addObserver(forName: UserDefaults.didChangeNotification, object: object, queue: nil) { _ in
+            if Thread.isMainThread {
+                MainActor.assumeIsolated { handler() }
+            } else {
+                Task { @MainActor in handler() }
+            }
+        }
+    }
+}

Packages/macOS/CmuxFoundation/Tests/CmuxFoundationTests/UserDefaultsNotificationDeliveryTests.swift

@@ -0,0 +1,61 @@
+import Foundation
+import Testing
+@testable import CmuxFoundation
+
+@Suite("Preference notification delivery")
+struct UserDefaultsNotificationDeliveryTests {
+    @Test @MainActor func mainThreadPostsDeliverSynchronously() {
+        let center = NotificationCenter()
+        var deliveries = 0
+        let observer = center.addUserDefaultsObserver { deliveries += 1 }
+        defer { center.removeObserver(observer) }
+
+        center.post(name: UserDefaults.didChangeNotification, object: nil)
+
+        #expect(deliveries == 1)
+    }
+
+    @Test(.timeLimit(.minutes(1))) @MainActor
+    func backgroundWriterReturnsWhileMainThreadIsOccupied() async {
+        let center = NotificationCenter()
+        let (deliveries, continuation) = AsyncStream<Void>.makeStream()
+        let observer = center.addUserDefaultsObserver {
+            MainActor.preconditionIsolated()
+            continuation.yield()
+        }
+        defer {
+            center.removeObserver(observer)
+            continuation.finish()
+        }
+        let posted = DispatchSemaphore(value: 0)
+        Thread.detachNewThread {
+            center.post(name: UserDefaults.didChangeNotification, object: nil)
+            posted.signal()
+        }
+        // Hold main until the writer returns, with a finite failure deadline.
+        // A synchronous main-queue observer cannot complete this sequence.
+        #expect(Self.waitForPostWhileMainThreadIsOccupied(posted))
+        var iterator = deliveries.makeAsyncIterator()
+        #expect(await iterator.next() != nil)
+    }
+
+    @MainActor private static func waitForPostWhileMainThreadIsOccupied(_ posted: DispatchSemaphore) -> Bool {
+        posted.wait(timeout: .now() + 1) == .success
+    }
+
+    @Test @MainActor func objectFilteringAndRemovalRemainEffective() {
+        let center = NotificationCenter()
+        let expected = NSObject()
+        let other = NSObject()
+        var deliveries = 0
+        let observer = center.addUserDefaultsObserver(object: expected) { deliveries += 1 }
+        center.post(name: UserDefaults.didChangeNotification, object: other)
+        #expect(deliveries == 0)
+        center.post(name: UserDefaults.didChangeNotification, object: expected)
+        #expect(deliveries == 1)
+
+        center.removeObserver(observer)
+        center.post(name: UserDefaults.didChangeNotification, object: expected)
+        #expect(deliveries == 1)
+    }
+}

Sources/App/ExternalApplicationWindowTracker.swift

@@ -285,13 +285,14 @@ final class ExternalApplicationWindowTracker {
         processIdentifier: pid_t,
         primaryScreenMaxY: CGFloat
     ) -> Snapshot? {
-        // CGWindowListCreateDescriptionFromArray returns an empty result for a
-        // valid external window on macOS 26. The including-window query uses
-        // the same public metadata and returns the requested record reliably.
-        guard let windowInfo = CGWindowListCopyWindowInfo(
-            [.optionIncludingWindow, .excludeDesktopElements],
-            windowID
-        ) as? [[String: Any]] else {
+        // This API expects pointer-sized window IDs, not boxed CFNumbers.
+        // Query the tracked ID directly so ordered-out windows retain their
+        // identity without scanning every window on each sample.
+        guard windowID != kCGNullWindowID else { return nil }
+        var rawWindowID = UnsafeRawPointer(bitPattern: UInt(windowID))
+        guard let windowIDs = CFArrayCreate(kCFAllocatorDefault, &rawWindowID, 1, nil),
+              let windowInfo = CGWindowListCreateDescriptionFromArray(windowIDs) as? [[String: Any]]
+        else {
             return nil
         }
         return windowInfo.compactMap {
@@ -304,7 +305,7 @@ final class ExternalApplicationWindowTracker {
         }.first
     }
 
-    private nonisolated static func snapshot(
+    nonisolated static func snapshot(
         from entry: [String: Any],
         expectedWindowID: CGWindowID?,
         processIdentifier: pid_t,
@@ -333,7 +334,9 @@ final class ExternalApplicationWindowTracker {
                 width: quartzFrame.width,
                 height: quartzFrame.height
             ),
-            isOnScreen: (entry[kCGWindowIsOnscreen as String] as? NSNumber)?.boolValue ?? true
+            // Missing visibility metadata is ambiguous. Suppress companion
+            // presentation until WindowServer confirms that the window is on screen.
+            isOnScreen: (entry[kCGWindowIsOnscreen as String] as? NSNumber)?.boolValue ?? false
         )
     }
 }

Sources/App/ExternalWindowCompanionPresenter.swift

@@ -19,8 +19,12 @@ struct ExternalWindowCompanionPresenter {
 
     func present(_ companionWindow: NSWindow) {
         companionWindow.level = .floating
-        companionWindow.collectionBehavior = [.managed]
+        // Move to the Space containing System Settings for this first order.
+        // Clear the transient flag immediately so later app activation cannot
+        // rehome the companion.
+        companionWindow.collectionBehavior = [.managed, .moveToActiveSpace]
         companionWindow.hidesOnDeactivate = false
         orderWindow(companionWindow)
+        companionWindow.collectionBehavior = [.managed]
     }
 }

Sources/AppDelegate.swift

@@ -10739,11 +10739,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate, UNUserNotificationCent
 
     private func installMenuBarVisibilityObserver() {
         guard menuBarVisibilityObserver == nil else { return }
-        menuBarVisibilityObserver = NotificationCenter.default.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        menuBarVisibilityObserver = NotificationCenter.default.addUserDefaultsObserver(object: nil) { [weak self] in
             Task { @MainActor [weak self] in
                 self?.syncApplicationPresentationPreferences()
             }
@@ -10766,11 +10762,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate, UNUserNotificationCent
 
     private func installMobileHostSettingsObserver() {
         guard mobileHostSettingsObserver == nil else { return }
-        mobileHostSettingsObserver = NotificationCenter.default.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        mobileHostSettingsObserver = NotificationCenter.default.addUserDefaultsObserver(object: nil) { [weak self] in
             Task { @MainActor [weak self] in
                 self?.syncMobileHostService()
             }

Sources/AppearanceSettings.swift

@@ -1,3 +1,4 @@
+import CmuxFoundation
 import AppKit
 import SwiftUI
 import CmuxTerminalCore
@@ -272,7 +273,7 @@ enum AppearanceSettings {
 
 final class AppearanceSettingsUserDefaultsObserver {
     struct Environment {
-        let addDefaultsObserver: (@escaping () -> Void) -> NSObjectProtocol
+        let addDefaultsObserver: (@escaping @MainActor @Sendable () -> Void) -> NSObjectProtocol
         let removeObserver: (NSObjectProtocol) -> Void
         let currentRawValue: () -> String?
         let applyStoredMode: (String?, String) -> AppearanceMode
@@ -283,11 +284,7 @@ final class AppearanceSettingsUserDefaultsObserver {
         ) -> Environment {
             Environment(
                 addDefaultsObserver: { handler in
-                    notificationCenter.addObserver(
-                        forName: UserDefaults.didChangeNotification,
-                        object: nil,
-                        queue: .main
-                    ) { _ in
+                    notificationCenter.addUserDefaultsObserver(object: nil) {
                         handler()
                     }
                 },

Sources/Cloud/ConnectivityInvalidationSubscriberCoordinator.swift

@@ -1,3 +1,4 @@
+import CmuxFoundation
 import CmuxAuthRuntime
 import CmuxIrohTransport
 import Foundation
@@ -25,11 +26,7 @@ final class ConnectivityInvalidationSubscriberCoordinator {
     func configure(auth: AuthCoordinator) {
         self.auth = auth
         if defaultsObserver == nil {
-            defaultsObserver = NotificationCenter.default.addObserver(
-                forName: UserDefaults.didChangeNotification,
-                object: UserDefaults.standard,
-                queue: .main
-            ) { [weak self] _ in
+            defaultsObserver = NotificationCenter.default.addUserDefaultsObserver(object: UserDefaults.standard) { [weak self] in
                 MainActor.assumeIsolated {
                     self?.evaluate()
                 }

Sources/Cloud/PresenceHeartbeatClient.swift

@@ -1,3 +1,4 @@
+import CmuxFoundation
 import CMUXMobileCore
 import CmuxAuthRuntime
 import Foundation
@@ -50,11 +51,7 @@ final class PresenceHeartbeatClient {
             // Re-evaluate when the flag or URL flips, so enabling presence in a
             // running app starts the loop without a relaunch (and disabling
             // stops it and says goodbye).
-            defaultsObserver = NotificationCenter.default.addObserver(
-                forName: UserDefaults.didChangeNotification,
-                object: UserDefaults.standard,
-                queue: .main
-            ) { _ in
+            defaultsObserver = NotificationCenter.default.addUserDefaultsObserver(object: UserDefaults.standard) {
                 MainActor.assumeIsolated {
                     PresenceHeartbeatClient.shared.evaluate()
                 }

Sources/ContentView.swift

@@ -11059,11 +11059,7 @@ private final class SidebarTabItemSettingsStore: ObservableObject {
             defaults: defaults,
             sidebarFontSize: sidebarFontSize
         )
-        defaultsObserver = NotificationCenter.default.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        defaultsObserver = NotificationCenter.default.addUserDefaultsObserver(object: nil) { [weak self] in
             Task { @MainActor [weak self] in
                 self?.refreshSnapshot()
             }

Sources/KeyboardShortcutSettings.swift

@@ -1,3 +1,4 @@
+import CmuxFoundation
 import AppKit
 import Bonsplit
 import Carbon
@@ -1218,11 +1219,7 @@ final class SystemWideHotkeyController {
 
         installHotKeyHandlerIfNeeded()
 
-        defaultsObserver = NotificationCenter.default.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        defaultsObserver = NotificationCenter.default.addUserDefaultsObserver(object: nil) { [weak self] in
             self?.refreshRegistration()
         }
         shortcutObserver = NotificationCenter.default.addObserver(

Sources/Panels/BrowserHiddenWebViewDiscardManager.swift

@@ -1,3 +1,4 @@
+import CmuxFoundation
 import AppKit
 import Foundation
 
@@ -306,11 +307,7 @@ final class BrowserHiddenWebViewDiscardManager {
     func installPolicyObserver() {
         policyState = BrowserHiddenWebViewDiscardPolicy.resolved(defaults: policyDefaults)
         guard policyObserver == nil else { return }
-        policyObserver = NotificationCenter.default.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        policyObserver = NotificationCenter.default.addUserDefaultsObserver(object: nil) { [weak self] in
             Task { @MainActor [weak self] in
                 self?.handlePolicyDefaultsChanged()
             }

Sources/Panels/MarkdownPanel.swift

@@ -267,11 +267,7 @@ final class MarkdownPanel: Panel, ObservableObject, FilePreviewTextEditingPanel
     /// or a `cmux.json` reload), but only while this viewer still matches the
     /// default it was tracking — i.e. the user has not customized it.
     private func observeTypographyDefaults() {
-        typographyDefaultsObserver = NotificationCenter.default.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: UserDefaults.standard,
-            queue: .main
-        ) { [weak self] _ in
+        typographyDefaultsObserver = NotificationCenter.default.addUserDefaultsObserver(object: UserDefaults.standard) { [weak self] in
             Task { @MainActor in
                 self?.adoptTypographyDefaultsIfFollowing()
             }

Sources/TabManager.swift

@@ -726,11 +726,7 @@ class TabManager: ObservableObject {
         })
 
         startAgentPIDSweepTimer()
-        observers.append(NotificationCenter.default.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        observers.append(NotificationCenter.default.addUserDefaultsObserver(object: nil) { [weak self] in
             MainActor.assumeIsolated { [weak self] in
                 self?.sidebarMetadataSettingsDidChange()
                 self?.focusHistoryScopeSettingsDidChange()

Sources/TerminalNotificationStore.swift

@@ -471,11 +471,7 @@ final class TerminalNotificationStore: ObservableObject {
             )
         }
         indexes = Self.buildIndexes(for: notifications)
-        userDefaultsObserver = NotificationCenter.default.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        userDefaultsObserver = NotificationCenter.default.addUserDefaultsObserver(object: nil) { [weak self] in
             Task { @MainActor [weak self] in
                 self?.refreshDockBadge()
             }

Sources/Update/UpdateTitlebarAccessory.swift

@@ -180,11 +180,7 @@ final class TitlebarControlsLayoutModel {
         )
 
         observers.append(
-            notificationCenter.addObserver(
-                forName: UserDefaults.didChangeNotification,
-                object: nil,
-                queue: .main
-            ) { [weak self] _ in
+            notificationCenter.addUserDefaultsObserver(object: nil) { [weak self] in
                 MainActor.assumeIsolated {
                     self?.refreshStyleIfNeeded()
                 }
@@ -2040,11 +2036,7 @@ final class TitlebarControlsAccessoryViewController: NSTitlebarAccessoryViewCont
         hostingView.layer?.masksToBounds = false
         containerView.addSubview(hostingView)
 
-        userDefaultsObserver = NotificationCenter.default.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        userDefaultsObserver = NotificationCenter.default.addUserDefaultsObserver(object: nil) { [weak self] in
             guard let self else { return }
             let shouldShow = self.showsWorkspaceTitlebar
             let debugSnapshot = MinimalModeTitlebarDebugSettings.snapshot()
@@ -2865,11 +2857,7 @@ final class UpdateTitlebarAccessoryController {
 
         // Re-evaluate all windows when the presentation mode changes so that
         // accessories are removed in minimal mode and re-attached in standard mode.
-        observers.append(center.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        observers.append(center.addUserDefaultsObserver(object: nil) { [weak self] in
             Task { @MainActor [weak self] in
                 self?.reattachIfPresentationModeChanged()
             }

Sources/WindowDecorationsController.swift

@@ -1,3 +1,4 @@
+import CmuxFoundation
 import AppKit
 import CmuxTestSupport
 
@@ -59,7 +60,7 @@ final class WindowDecorationsController {
         for name in TitlebarWindowGeometryNotifications.names {
             observers.append(center.addObserver(forName: name, object: nil, queue: .main, using: handler))
         }
-        observers.append(center.addObserver(forName: UserDefaults.didChangeNotification, object: nil, queue: .main) { [weak self] _ in
+        observers.append(center.addUserDefaultsObserver(object: nil) { [weak self] in
             self?.applyDefaultsDrivenDecorationChangeIfNeeded()
         })
     }

Sources/WindowToolbarController.swift

@@ -111,11 +111,7 @@ final class WindowToolbarController: NSObject, NSToolbarDelegate {
             }
         })
 
-        observers.append(center.addObserver(
-            forName: UserDefaults.didChangeNotification,
-            object: nil,
-            queue: .main
-        ) { [weak self] _ in
+        observers.append(center.addUserDefaultsObserver(object: nil) { [weak self] in
             Task { @MainActor [weak self] in
                 self?.updateToolbarVisibilityIfNeeded()
             }