etanhey/mac-systems

mac-systems

macOS systems specialist for low-level AppKit, launchd, security policy, resilient networking, and SwiftUI dashboard architecture.

When to Use

• Building or fixing menu bar apps (NSStatusItem, NSPanel, NSPopover migration)
• Configuring LaunchAgents/LaunchDaemons
• Debugging syspolicyd, Gatekeeper, TCC, or codesigning issues
• Implementing resilient Unix Domain Socket bridges (especially for MCP)
• Architecting high-frequency SwiftUI dashboards (10Hz+) on macOS
• Working with launchd socket activation for zero-downtime restarts

Mechanical Environment Truths (hard-won — gen-12 weave E14)

One-liners every worker and launchd plist author must internalize:

1. Tailnet IP bind ban — NEVER hardcode tailnet IPs in launchd plists or worker-prompt URLs. Bind 127.0.0.1 / loopback or resolve at start. Three live catches: Phoenix phantom listener (two eras), W10 dead :8852 URL.
2. Codex detached-child reap — Codex exec reaps detached children (& / nohup die). launchctl submit is the surviving detach path; clean up leftover runners after.
3. pipefail + early-exit consumer — Under set -o pipefail, piping into an early-exit consumer (awk '{exit}') SIGPIPE-kills the producer (exit 141). Buffer first, then consume. See /shell-hardening.
4. zsh read-only specials — Never use zsh read-only specials (status, etc.) as variable names.
5. nvm FUNCNEST in profiles — voicelayer-profile node hits nvm _lazy_nvm FUNCNEST recursion — use bun for profile scripts.
6. CloudStorage read bounds — Bound any read of ~/Library/CloudStorage — cloud-only placeholders hang naive tar/read.
7. Host-identity check first — Machine-named tasks: verify current-host vs target-host identity BEFORE acting ("What you're on is the M4 Max. I was asking about the M1 Pro.").
8. Computer-use fallback ladder — When CU fails on a UI element: element click → coords → osascript System Events AX → keystroke.

Core Knowledge

1. Menu Bar App Architecture (NSPopover → NSPanel)

NSPopover is wrong for dashboard-class UIs. It causes:

• White flash on Sonoma/Sequoia/Tahoe (Apple regression in popover composition)
• No resize persistence
• View hierarchy teardown on every dismiss (kills @State)
• No right-click, drag, modifier-click, or programmatic show/hide

The correct primitive: NSStatusItem + custom NSPanel + NSHostingView.

Every serious menu-bar app uses this: Ice, Stats, Raycast, 1Password mini, Bartender, iStatMenus, CleanShot X, Alfred, MonitorControl.

NSPanel Recipe

final class DashboardPanel: NSPanel {
    init<V: View>(rootView: V) {
        super.init(
            contentRect: NSRect(x: 0, y: 0, width: 520, height: 620),
            styleMask: [.titled, .closable, .resizable, .fullSizeContentView,
                        .nonactivatingPanel, .utilityWindow],
            backing: .buffered, defer: false
        )
        titlebarAppearsTransparent = true
        titleVisibility = .hidden
        isFloatingPanel = true
        level = .statusBar
        hidesOnDeactivate = false
        becomesKeyOnlyIfNeeded = true
        collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .transient]
        animationBehavior = .utilityWindow   // THE flash fix
        isMovableByWindowBackground = false
        hasShadow = true
        isOpaque = false
        backgroundColor = .clear

        let effect = NSVisualEffectView()
        effect.material = .menu
        effect.state = .active
        effect.blendingMode = .behindWindow
        effect.wantsLayer = true
        effect.layer?.cornerRadius = 10
        effect.layer?.masksToBounds = true

        let host = NSHostingView(rootView: rootView)
        host.sizingOptions = [.preferredContentSize]
        host.translatesAutoresizingMaskIntoConstraints = false
        effect.addSubview(host)
        NSLayoutConstraint.activate([
            host.leadingAnchor.constraint(equalTo: effect.leadingAnchor),
            host.trailingAnchor.constraint(equalTo: effect.trailingAnchor),
            host.topAnchor.constraint(equalTo: effect.topAnchor),
            host.bottomAnchor.constraint(equalTo: effect.bottomAnchor),
        ])
        contentView = effect
    }

    override var canBecomeKey: Bool { true }
    override var canBecomeMain: Bool { false }
}

Seven Anti-Flash Measures

1. animationBehavior = .utilityWindow — subtle fade instead of scale-in
2. Pre-create panel at launch, not on first click
3. setContentSize(...) before first makeKeyAndOrderFront
4. isOpaque = false + backgroundColor = .clear + NSVisualEffectView
5. wantsLayer = true on hosting view
6. clipsToBounds = true on Sonoma+
7. NSHostingView.sizingOptions = [.preferredContentSize] (macOS 13.3+)

2. LaunchAgents & LaunchDaemons

See mechanical truth #1 (loopback bind) and #2 (launchctl submit for Codex detach).

launchctl Commands (macOS 10.10+)

# Load/enable
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.myservice.plist

# Unload/disable
launchctl bootout gui/$(id -u)/com.example.myservice

# Status
launchctl print gui/$(id -u)/com.example.myservice

# Detached one-shot (survives Codex exec reap — preferred over bare nohup &)
launchctl submit -l com.example.oneshot -- /path/to/script.sh

3. Security — syspolicyd, Gatekeeper, TCC

# Watch syspolicyd in real time
/usr/bin/log stream --predicate 'subsystem == "com.apple.syspolicy"' --level debug
# ⚠️ In scripted zsh, ALWAYS invoke /usr/bin/log absolutely — zsh has a `log` builtin that
# shadows it and exits 0 with no output, silently fabricating "no log entries" conclusions.

References

• R1 BrainBar UX Research: ~/Gits/orchestrator/docs.local/research/R1-claude-desktop-macos-menubar-ux-FULL.md
• MCP Reconnection Research: ~/Gits/orchestrator/docs.local/research/mcp-reconnection-research.md
• /shell-hardening — pipefail/SIGPIPE section pairs with mechanical truth #3