Add on-monitor-changed config callback

When a monitor is connected or disconnected, users often need to
reload external tools (e.g. sketchybar) that depend on the display
configuration. AeroSpace already detects monitor count changes in
gcMonitors() and rearranges workspaces, but provides no hook for
users to run commands in response.

Add on-monitor-changed callback that fires when the set of connected
monitors changes.

Detection: register a CGDisplayReconfigurationCallback in
GlobalObserver. This fires reliably for monitor connect/disconnect
at the CoreGraphics level, unlike NSApplication notifications which
may not be delivered to agent apps. The callback triggers a refresh
session which runs gcMonitors() and layoutWorkspaces() as usual.

Callback timing: checkOnMonitorChangedCallback() runs AFTER
layoutWorkspaces() in runRefreshSessionBlocking, so external tools
that query AeroSpace (e.g. `aerospace list-workspaces --monitor X`)
see the final workspace-to-monitor assignments. This avoids a race
where the callback fires mid-rearrangement and tools see stale state.

The callback tracks monitor count via a separate _previousMonitorCount
variable rather than hooking into gcMonitors() directly, because other
refresh sessions (triggered by concurrent AX notifications) often call
rearrangeWorkspacesOnMonitors() first, making gcMonitors()'s own
count comparison a no-op by the time the display reconfiguration
session runs.

Config syntax:
  on-monitor-changed = 'exec-and-forget sketchybar --reload'

Also adds monitor-changed to the subscribe event types so that
`aerospace subscribe monitor-changed` works for external tooling.

Author: willzeng274

Sources/AppBundle/GlobalObserver.swift

@@ -53,6 +53,16 @@ enum GlobalObserver {
         nc.addObserver(forName: NSWorkspace.activeSpaceDidChangeNotification, object: nil, queue: .main, using: onNotif)
         nc.addObserver(forName: NSWorkspace.didTerminateApplicationNotification, object: nil, queue: .main, using: onNotif)
 
+        // Detect monitor connect/disconnect via CoreGraphics callback.
+        CGDisplayRegisterReconfigurationCallback({ _, flags, _ in
+            // Only act on completion of a reconfiguration, not the begin phase
+            guard flags.contains(.beginConfigurationFlag) == false else { return }
+            Task { @MainActor in
+                if !TrayMenuModel.shared.isEnabled { return }
+                scheduleRefreshSession(.globalObserver("displayReconfiguration"))
+            }
+        }, nil)
+
         NSEvent.addGlobalMonitorForEvents(matching: .leftMouseUp) { _ in
             // todo reduce number of refreshSession in the callback
             //  resetManipulatedWithMouseIfPossible might call its own refreshSession

Sources/AppBundle/config/Config.swift

@@ -54,6 +54,7 @@ struct Config: ConvenienceCopyable {
     var onFocusChanged: [any Command] = []
     // var onFocusedWorkspaceChanged: [any Command] = []
     var onFocusedMonitorChanged: [any Command] = []
+    var onMonitorChanged: [any Command] = []
 
     var gaps: Gaps = .zero
     var workspaceToMonitorForceAssignment: [String: [MonitorDescription]] = [:]

Sources/AppBundle/config/parseConfig.swift

@@ -102,6 +102,7 @@ private let configParser: [String: any ParserProtocol<Config>] = [
     "on-focus-changed": Parser(\.onFocusChanged) { parseCommandOrCommands($0).toParsedConfig($1) },
     "on-mode-changed": Parser(\.onModeChanged) { parseCommandOrCommands($0).toParsedConfig($1) },
     "on-focused-monitor-changed": Parser(\.onFocusedMonitorChanged) { parseCommandOrCommands($0).toParsedConfig($1) },
+    "on-monitor-changed": Parser(\.onMonitorChanged) { parseCommandOrCommands($0).toParsedConfig($1) },
     // "on-focused-workspace-changed": Parser(\.onFocusedWorkspaceChanged, { parseCommandOrCommands($0).toParsedConfig($1) }),
 
     "enable-normalization-flatten-containers": Parser(\.enableNormalizationFlattenContainers, parseBool),

Sources/AppBundle/layout/refresh.swift

@@ -41,6 +41,7 @@ func runRefreshSessionBlocking(
             SecureInputPanel.shared.refresh()
             try await normalizeLayoutReason()
             if shouldLayoutWorkspaces { try await layoutWorkspaces() }
+            checkOnMonitorChangedCallback()
         }
     }
 }

Sources/AppBundle/model/ServerEvent.swift

@@ -45,4 +45,8 @@ public struct ServerEvent: Codable, Sendable {
     public static func bindingTriggered(mode: String, binding: String) -> ServerEvent {
         ServerEvent(_event: .bindingTriggered, mode: mode, binding: binding)
     }
+
+    public static func monitorChanged(monitorCount: Int) -> ServerEvent {
+        ServerEvent(_event: .monitorChanged, monitorId: monitorCount)
+    }
 }

Sources/AppBundle/subscriptions.swift

@@ -30,7 +30,7 @@ func handleSubscribeAndWaitTillError(_ connection: NWConnection, _ args: Subscri
                         workspace: f.workspace.name,
                         monitorId_oneBased: f.workspace.workspaceMonitor.monitorId_oneBased ?? 0,
                     )
-                case .windowDetected, .bindingTriggered: continue
+                case .windowDetected, .bindingTriggered, .monitorChanged: continue
             }
             if await connection.writeAtomic(event, jsonEncoder).error != nil {
                 return

Sources/AppBundle/tree/Workspace.swift

@@ -132,13 +132,34 @@ extension Monitor {
     }
 }
 
+@MainActor
+var _previousMonitorCount: Int = NSScreen.screens.count
+
 @MainActor
 func gcMonitors() {
     if screenPointToVisibleWorkspace.count != monitors.count {
         rearrangeWorkspacesOnMonitors()
     }
 }
 
+/// Check if the monitor count changed since last check and fire the callback.
+/// Must be called AFTER layoutWorkspaces() so that external tools see the final state.
+@MainActor
+func checkOnMonitorChangedCallback() {
+    let current = monitors.count
+    if current != _previousMonitorCount {
+        _previousMonitorCount = current
+        broadcastEvent(.monitorChanged(monitorCount: current))
+        if config.onMonitorChanged.isEmpty { return }
+        guard let token: RunSessionGuard = .isServerEnabled else { return }
+        Task {
+            try await runLightSession(.onMonitorChanged, token) {
+                _ = try await config.onMonitorChanged.runCmdSeq(.defaultEnv, .emptyStdin)
+            }
+        }
+    }
+}
+
 extension CGPoint {
     @MainActor
     fileprivate func setActiveWorkspace(_ workspace: Workspace) -> Bool {

Sources/AppBundleTests/command/SubscribeCmdArgsTest.swift

@@ -31,7 +31,7 @@ final class SubscribeCmdArgsTest: XCTestCase {
             case .failure(let err):
                 assertEquals(err, """
                     ERROR: Can't parse 'unknown-event'.
-                           Possible values: (focus-changed|focused-monitor-changed|focused-workspace-changed|mode-changed|window-detected|binding-triggered)
+                           Possible values: (focus-changed|focused-monitor-changed|focused-workspace-changed|mode-changed|window-detected|binding-triggered|monitor-changed)
                     """)
         }
     }

Sources/Common/cmdArgs/impl/SubscribeCmdArgs.swift

@@ -61,4 +61,5 @@ public enum ServerEventType: String, Codable, CaseIterable, Sendable {
     case modeChanged = "mode-changed"
     case windowDetected = "window-detected"
     case bindingTriggered = "binding-triggered"
+    case monitorChanged = "monitor-changed"
 }

Sources/Common/util/commonUtil.swift

@@ -80,6 +80,8 @@ public enum RefreshSessionEvent: Sendable, CustomStringConvertible {
     case onFocusedMonitorChanged
     case onFocusChanged
     case onModeChanged
+    case focusFollowsMouse
+    case onMonitorChanged
 
     public var isStartup: Bool {
         if case .startup = self { return true } else { return false }
@@ -99,6 +101,8 @@ public enum RefreshSessionEvent: Sendable, CustomStringConvertible {
             case .onFocusedMonitorChanged: "onFocusedMonitorChanged"
             case .onFocusChanged: "onFocusChanged"
             case .onModeChanged: "onModeChanged"
+            case .focusFollowsMouse: "focusFollowsMouse"
+            case .onMonitorChanged: "onMonitorChanged"
         }
     }
 }