/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.
9. footprint, not RSS, for leak watches — RSS is a liar under the macOS memory compressor: a leak sampler showed RSS bouncing 444–760MB while footprint sat at 5.1G. Leak watches and escalation thresholds MUST read phys_footprint (/usr/bin/footprint <PID>), never ps -o rss. Recipe in Core Knowledge §4.

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.

4. Memory Leak Watches — footprint, not RSS

The macOS memory compressor masks leaks from RSS: compressed pages leave the resident set but still count against the process's physical footprint (and its jetsam limit). Observed divergence (2026-06-07 cmux leak watch): RSS bounced 444–760MB while footprint sat at 5.1G — an RSS-based watch nearly suppressed the escalation. The canonical metric is phys_footprint, read via /usr/bin/footprint (summary line: name [pid]: 64-bit Footprint: NNNN KB).

Watch-rebuild recipe — threshold on footprint bytes, never ps -o rss:

# Footprint-based leak watch (RSS under-reports under the compressor)
PID=12345; LIMIT_BYTES=$((4 * 1024 * 1024 * 1024))   # escalate at 4 GiB
while kill -0 "$PID" 2>/dev/null; do
  fp_bytes=$(/usr/bin/footprint --format bytes "$PID" 2>/dev/null \
    | sed -n 's/.*Footprint: \([0-9]*\) B.*/\1/p')
  if [ -n "$fp_bytes" ] && [ "$fp_bytes" -ge "$LIMIT_BYTES" ]; then
    echo "LEAK: phys_footprint=${fp_bytes}B >= ${LIMIT_BYTES}B" >&2
    # escalate here
  fi
  sleep 60
done

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