chore(menu-bar): add bounded Control Center startup diagnostics

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 0.67.1 — Unreleased
 
+### Added
+
+- Menu bar: add opt-in, bounded startup diagnostics for status-item creation and Control Center hosting investigations (#3377).
+
 ### Changed
 
 - Settings: simplify menu bar layout controls while keeping token-removal instructions in the section footer (#3999). Thanks @elijahfriedman!

Sources/CodexBar/CodexbarApp.swift

@@ -434,6 +434,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
     }
 
     func applicationWillFinishLaunching(_ notification: Notification) {
+        MenuBarStatusItemWindowProbe.trace("will-finish-launching")
         self.configureAppIconForMacOSVersion()
         // The SwiftUI `Settings` scene is an empty placeholder; macOS otherwise presents it at launch.
         self.placeholderSettingsWindowGuard.start()
@@ -445,6 +446,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
     }
 
     func applicationDidFinishLaunching(_ notification: Notification) {
+        MenuBarStatusItemWindowProbe.trace("did-finish-launching")
         self.dockIconController.start()
         self.memoryPressureMonitor.start()
         #if DEBUG

Sources/CodexBar/MenuBarStatusItemWindowProbe.swift

@@ -37,10 +37,63 @@ struct MenuBarStatusItemWindowSnapshot: Equatable, CustomStringConvertible {
 }
 
 enum MenuBarStatusItemWindowProbe {
+    @MainActor static let diagnosticsEnabled = ProcessInfo.processInfo
+        .environment["CODEXBAR_STATUS_ITEM_DIAGNOSTICS"] == "1"
+    @MainActor private static var diagnosticRecords = 0
+
+    /// Opt-in, bounded stdout trace; never includes window titles, accounts, or provider content.
+    @MainActor static func trace(_ stage: String, item: NSStatusItem? = nil, evidence: String = "") {
+        guard self.diagnosticsEnabled, self.diagnosticRecords < 128 else { return }
+        self.diagnosticRecords += 1
+        let name = item?.autosaveName ?? ""
+        let window = item?.button?.window
+        let records = self.windowInfo()
+        let receipt: [String: Any] = [
+            "stage": stage, "sequence": self.diagnosticRecords,
+            "uptime": ProcessInfo.processInfo.systemUptime,
+            "bundle": Bundle.main.bundleIdentifier ?? "unknown",
+            "git": Bundle.main.object(forInfoDictionaryKey: "CodexGitCommit") as? String ?? "unknown",
+            "mainThread": Thread.isMainThread, "running": NSApp?.isRunning ?? false,
+            "activationPolicy": NSApp?.activationPolicy().rawValue ?? -1,
+            "identity": name, "visible": item?.isVisible ?? false, "length": item?.length ?? 0, "evidence": evidence,
+            "buttonWindow": window?.windowNumber ?? -1,
+            "buttonFrame": NSStringFromRect(item?.button?.frame ?? .zero),
+            "windowFrame": NSStringFromRect(window?.frame ?? .zero),
+            "screens": NSScreen.screens.map { NSStringFromRect($0.frame) },
+            "placeholderWindows": NSApp?.windows.filter {
+                $0.identifier?.rawValue.contains(PlaceholderSettingsWindowDecision.swiftUISettingsNameFragment) == true
+            }.map { ["number": $0.windowNumber, "frame": NSStringFromRect($0.frame), "visible": $0.isVisible] } ?? [],
+            "windowQuerySucceeded": records != nil,
+            "controlCenter": self.hostingDiagnostics(name: name, windowInfo: records ?? []),
+        ]
+        guard let data = try? JSONSerialization.data(withJSONObject: receipt, options: [.sortedKeys]) else { return }
+        FileHandle.standardOutput.write(data + Data([0x0A]))
+    }
+
+    static func hostingDiagnostics(name: String, windowInfo: [[String: Any]]) -> [String: Any] {
+        let windows = windowInfo.filter {
+            ($0[kCGWindowLayer as String] as? Int) == 25
+                && ["Control Center", "Control Centre"].contains($0[kCGWindowOwnerName as String] as? String ?? "")
+        }
+        let matches = windows.filter { !name.isEmpty && ($0[kCGWindowName as String] as? String) == name }
+        return [
+            "layer25Count": windows.count,
+            "layer25Numbers": windows.compactMap { $0[kCGWindowNumber as String] as? Int }.sorted(),
+            "unnamedCount": windows.filter { ($0[kCGWindowName as String] as? String ?? "").isEmpty }.count,
+            "namedMatches": matches.map { record in
+                [
+                    "number": record[kCGWindowNumber as String] as? Int ?? -1,
+                    "bounds": NSStringFromRect(self.bounds(record[kCGWindowBounds as String]) ?? .zero),
+                    "onscreen": (record[kCGWindowIsOnscreen as String] as? Bool) ?? false,
+                ] as [String: Any]
+            },
+        ]
+    }
+
     static func snapshots(matching names: Set<String>) -> [MenuBarStatusItemWindowSnapshot] {
         self.snapshots(
             matching: names,
-            windowInfo: self.windowInfo(),
+            windowInfo: self.windowInfo() ?? [],
             screenFrames: NSScreen.screens.map(\.frame))
     }
 
@@ -61,11 +114,8 @@ enum MenuBarStatusItemWindowProbe {
         }
     }
 
-    private static func windowInfo() -> [[String: Any]] {
-        guard let windows = CGWindowListCopyWindowInfo([.optionAll], kCGNullWindowID) as? [[String: Any]] else {
-            return []
-        }
-        return windows
+    private static func windowInfo() -> [[String: Any]]? {
+        CGWindowListCopyWindowInfo([.optionAll], kCGNullWindowID) as? [[String: Any]]
     }
 
     private static func snapshot(

Sources/CodexBar/MenuBarVisibilityWatcher.swift

@@ -176,19 +176,6 @@ enum MenuBarVisibilityWatcher {
             detectTahoeBlockedStatusItem: detectTahoeBlockedStatusItem)
     }
 
-    static func shouldRefreshScreenChangePlacement(
-        previousScreenCount _: Int,
-        currentScreenCount _: Int,
-        snapshots: [StatusItemVisibilitySnapshot])
-        -> Bool
-    {
-        self.hasAnyDisplacedVisibleSnapshot(snapshots)
-    }
-
-    static func shouldAttemptScreenChangeRecovery(snapshots: [StatusItemVisibilitySnapshot]) -> Bool {
-        self.hasAnyBlockedVisibleSnapshot(snapshots)
-    }
-
     static func shouldShowGuidance(defaults: UserDefaults, now: Date = Date()) -> Bool {
         guard defaults.bool(forKey: self.guidanceShownKey) else { return true }
         let lastShownAt = defaults.double(forKey: self.guidanceLastShownAtKey)
@@ -227,6 +214,12 @@ enum MenuBarVisibilityWatcher {
 extension StatusItemController {
     func scheduleStartupStatusItemVisibilityCheck(appLaunchedAt: Date = Date()) {
         guard !SettingsStore.isRunningTests else { return }
+        self.traceStatusItems("rendered")
+        if MenuBarStatusItemWindowProbe.diagnosticsEnabled {
+            DispatchQueue.main.asyncAfter(deadline: .now() + 15) { [weak self] in
+                self?.traceStatusItems("settled")
+            }
+        }
         DispatchQueue.main.asyncAfter(deadline: .now() + MenuBarVisibilityWatcher.startupCheckDelay) { [weak self] in
             Task { @MainActor [weak self] in
                 self?.checkStartupStatusItemVisibility(appLaunchedAt: appLaunchedAt)
@@ -235,77 +228,43 @@ extension StatusItemController {
     }
 
     private func checkStartupStatusItemVisibility(appLaunchedAt: Date, now: Date = Date()) {
-        let evidence = self.startupStatusItemVisibilityEvidence()
-        let snapshots = evidence.map(\.snapshot)
-        let windowSnapshots = self.statusItemWindowSnapshots()
-        guard MenuBarVisibilityWatcher.shouldAttemptStartupRecovery(
-            appLaunchedAt: appLaunchedAt,
-            now: now,
-            snapshots: snapshots,
-            evidence: evidence,
-            windowSnapshots: windowSnapshots,
-            detectTahoeBlockedStatusItem: self.canDetectTahoeBlockedStatusItem)
-        else {
-            return
-        }
-
+        self.traceStatusItems("startup-check")
+        guard let metadata = self.startupRecoveryMetadata(appLaunchedAt: appLaunchedAt, now: now) else { return }
         self.menuLogger.error(
-            "Status item failed to materialize or remained detached; recreating status items",
-            metadata: [
-                "snapshots": snapshots.map(\.description).joined(separator: " | "),
-                "evidence": evidence.map(\.description).joined(separator: " | "),
-                "windows": self.statusItemWindowDiagnosticsDescription(windowSnapshots),
-            ])
+            "Status item failed to materialize or remained detached; recreating status items", metadata: metadata)
         self.recreateStatusItemsForVisibilityRecovery()
-
-        let recoveredEvidence = self.startupStatusItemVisibilityEvidence()
-        let recoveredSnapshots = recoveredEvidence.map(\.snapshot)
-        let recoveredWindowSnapshots = self.statusItemWindowSnapshots()
-        guard MenuBarVisibilityWatcher.shouldAttemptStartupRecovery(
-            appLaunchedAt: appLaunchedAt,
-            now: now,
-            snapshots: recoveredSnapshots,
-            evidence: recoveredEvidence,
-            windowSnapshots: recoveredWindowSnapshots,
-            detectTahoeBlockedStatusItem: self.canDetectTahoeBlockedStatusItem)
-        else {
+        guard let recovered = self.startupRecoveryMetadata(appLaunchedAt: appLaunchedAt, now: now) else {
             self.menuLogger.info(
                 "Status item materialized after recreation",
-                metadata: ["snapshots": recoveredSnapshots.map(\.description).joined(separator: " | ")])
+                metadata: self.statusItemVisibilityMetadata())
             return
         }
-
-        self.menuLogger.error(
-            "Status item still unavailable after recreation",
-            metadata: [
-                "snapshots": recoveredSnapshots.map(\.description).joined(separator: " | "),
-                "evidence": recoveredEvidence.map(\.description).joined(separator: " | "),
-                "windows": self.statusItemWindowDiagnosticsDescription(recoveredWindowSnapshots),
-            ])
+        self.menuLogger.error("Status item still unavailable after recreation", metadata: recovered)
         guard #available(macOS 26.0, *),
               MenuBarVisibilityWatcher.shouldShowGuidance(defaults: self.settings.userDefaults, now: now)
-        else {
-            return
-        }
+        else { return }
         MenuBarVisibilityWatcher.presentGuidance(defaults: self.settings.userDefaults, now: now)
     }
 
-    @objc func handleScreenParametersDidChange(_: Notification) {
-        let previousScreenCount = max(
-            self.pendingScreenChangePreviousCount ?? self.lastKnownScreenCount,
-            self.lastKnownScreenCount)
-        let currentScreenCount = NSScreen.screens.count
-        self.pendingScreenChangePreviousCount = previousScreenCount
-        self.lastKnownScreenCount = currentScreenCount
-        self.scheduleScreenChangeStatusItemVisibilityCheck(
-            previousScreenCount: previousScreenCount,
-            currentScreenCount: currentScreenCount)
+    private func startupRecoveryMetadata(appLaunchedAt: Date, now: Date) -> [String: String]? {
+        let evidence = self.startupStatusItemVisibilityEvidence()
+        let windowSnapshots = self.statusItemWindowSnapshots()
+        guard MenuBarVisibilityWatcher.shouldAttemptStartupRecovery(
+            appLaunchedAt: appLaunchedAt,
+            now: now,
+            snapshots: evidence.map(\.snapshot),
+            evidence: evidence,
+            windowSnapshots: windowSnapshots,
+            detectTahoeBlockedStatusItem: self.canDetectTahoeBlockedStatusItem)
+        else { return nil }
+        return [
+            "snapshots": evidence.map(\.snapshot.description).joined(separator: " | "),
+            "evidence": evidence.map(\.description).joined(separator: " | "),
+            "windows": self.statusItemWindowDiagnosticsDescription(windowSnapshots),
+        ]
     }
 
-    private func scheduleScreenChangeStatusItemVisibilityCheck(
-        previousScreenCount: Int,
-        currentScreenCount: Int)
-    {
+    @objc func handleScreenParametersDidChange(_: Notification) {
         guard !SettingsStore.isRunningTests else { return }
         self.screenChangeVisibilityTask?.cancel()
         self.screenChangeVisibilityTask = Task { @MainActor [weak self] in
@@ -314,49 +273,39 @@ extension StatusItemController {
             } catch {
                 return
             }
-            self?.checkScreenChangeStatusItemVisibility(
-                previousScreenCount: previousScreenCount,
-                currentScreenCount: currentScreenCount)
+            self?.checkScreenChangeStatusItemVisibility()
         }
     }
 
-    private func checkScreenChangeStatusItemVisibility(previousScreenCount: Int, currentScreenCount: Int) {
-        self.pendingScreenChangePreviousCount = nil
-        let settledCurrentScreenCount = NSScreen.screens.count
-        self.lastKnownScreenCount = settledCurrentScreenCount
+    private func checkScreenChangeStatusItemVisibility() {
         let snapshots = MenuBarVisibilityWatcher.visibilitySnapshots(self.startupVisibilityStatusItems)
-        if MenuBarVisibilityWatcher.shouldAttemptScreenChangeRecovery(snapshots: snapshots) {
+        if MenuBarVisibilityWatcher.hasAnyBlockedVisibleSnapshot(snapshots) {
             self.menuLogger.error(
-                "Display configuration changed; recreating status items",
-                metadata: [
-                    "previousScreenCount": "\(previousScreenCount)",
-                    "currentScreenCount": "\(settledCurrentScreenCount)",
-                    "capturedScreenCount": "\(currentScreenCount)",
-                    "snapshots": snapshots.map(\.description).joined(separator: " | "),
-                    "windows": self.statusItemWindowDiagnosticsDescription(),
-                ])
+                "Display configuration changed; recreating status items", metadata: self.statusItemVisibilityMetadata())
             self.recreateStatusItemsForVisibilityRecovery()
             self.schedulePostScreenChangeRecoveryVerification(attempt: 1)
-            return
+        } else if MenuBarVisibilityWatcher.hasAnyDisplacedVisibleSnapshot(snapshots) {
+            self.menuLogger.info(
+                "Display configuration changed; refreshing existing status items",
+                metadata: self.statusItemVisibilityMetadata())
+            self.refreshExistingStatusItemsForVisibilityRecovery()
         }
+    }
 
-        guard MenuBarVisibilityWatcher.shouldRefreshScreenChangePlacement(
-            previousScreenCount: previousScreenCount,
-            currentScreenCount: settledCurrentScreenCount,
-            snapshots: snapshots)
-        else {
-            return
-        }
+    private func statusItemVisibilityMetadata() -> [String: String] {
+        [
+            "snapshots": MenuBarVisibilityWatcher.visibilitySnapshots(self.startupVisibilityStatusItems)
+                .map(\.description).joined(separator: " | "),
+            "windows": self.statusItemWindowDiagnosticsDescription(),
+            "screenCount": "\(NSScreen.screens.count)",
+        ]
+    }
 
-        self.menuLogger.info(
-            "Display configuration changed; refreshing existing status items",
-            metadata: [
-                "previousScreenCount": "\(previousScreenCount)",
-                "currentScreenCount": "\(settledCurrentScreenCount)",
-                "capturedScreenCount": "\(currentScreenCount)",
-                "snapshots": snapshots.map(\.description).joined(separator: " | "),
-            ])
-        self.refreshExistingStatusItemsForVisibilityRecovery()
+    private func traceStatusItems(_ stage: String) {
+        guard MenuBarStatusItemWindowProbe.diagnosticsEnabled else { return }
+        for (item, evidence) in zip(self.startupVisibilityStatusItems, self.startupStatusItemVisibilityEvidence()) {
+            MenuBarStatusItemWindowProbe.trace(stage, item: item, evidence: evidence.description)
+        }
     }
 
     private func schedulePostScreenChangeRecoveryVerification(attempt: Int) {

Sources/CodexBar/StatusItemController+Shutdown.swift

@@ -43,7 +43,6 @@ extension StatusItemController {
         self.menuCardRefreshMonitor.resetManualRefresh()
         self.screenChangeVisibilityTask?.cancel()
         self.screenChangeVisibilityTask = nil
-        self.pendingScreenChangePreviousCount = nil
         self.animationDriver?.stop()
         self.animationDriver = nil
         self.animationPhase = 0

Sources/CodexBar/StatusItemController+StatusItemVending.swift

@@ -25,13 +25,16 @@ extension StatusItemController {
             legacyDefaultItemIndex: legacyDefaultItemIndex)
         // AppKit has no named factory: keep the item zero-width until its stable identity is attached.
         let item = create(0)
+        MenuBarStatusItemWindowProbe.trace("created", item: item as? NSStatusItem)
         // Registration must see the stable identity before its callback can re-enter setup.
         item.autosaveName = identity.autosaveName
+        MenuBarStatusItemWindowProbe.trace("named", item: item as? NSStatusItem)
         onCreated?(item)
         // Reentrant registration may have already rendered a custom width.
         if item.length == 0 {
             item.length = NSStatusItem.variableLength
         }
+        MenuBarStatusItemWindowProbe.trace("sized", item: item as? NSStatusItem)
         if let button = item.button {
             let title = self.statusItemAccessibilityTitle(
                 isDebugApp: self.isDebugApp(bundleIdentifier: Bundle.main.bundleIdentifier))

Sources/CodexBar/StatusItemController.swift

@@ -317,8 +317,6 @@ final class StatusItemController: NSObject, NSMenuDelegate, StatusItemControllin
     var lastObservedStoreIconWorkSignature: String?
     var iconPerfRefreshCycleMetrics: IconPerfRefreshCycleMetrics?
     var iconPerfUpdatePassActive = false
-    var lastKnownScreenCount: Int
-    var pendingScreenChangePreviousCount: Int?
     var screenChangeVisibilityTask: Task<Void, Never>?
     let loginLogger = CodexBarLog.logger(LogCategories.login)
     let menuLogger = CodexBarLog.logger(LogCategories.app)
@@ -417,7 +415,6 @@ final class StatusItemController: NSObject, NSMenuDelegate, StatusItemControllin
             identity: .merged,
             defaults: settings.userDefaults,
             legacyDefaultItemIndex: Self.mergedLegacyDefaultItemIndex)
-        self.lastKnownScreenCount = NSScreen.screens.count
         // Status items for individual providers are now created lazily in updateVisibility()
         super.init()
         if !repairedStatusItemVisibilityKeys.isEmpty {
@@ -920,7 +917,6 @@ final class StatusItemController: NSObject, NSMenuDelegate, StatusItemControllin
         self.loginTask?.cancel()
         self.overviewSharePresentation.task?.cancel()
         self.screenChangeVisibilityTask?.cancel()
-        self.pendingScreenChangePreviousCount = nil
         NotificationCenter.default.removeObserver(self)
     }
 }