Skip to content

Codex.app hangs after Homebrew cask CLI upgrade while desktop app is running on macOS #23695

Open

Description

@alfredolopez80

Summary

Codex.app became unresponsive on macOS shortly after I ran:

brew upgrade --cask codex

while the Codex desktop app was already running with active local work.

macOS generated a hang stackshot for /Applications/Codex.app/Contents/MacOS/Codex. The app did not crash with a signal; it stayed alive but unresponsive for ~239 seconds before sampling.

Important nuance: the Homebrew cask named codex appears to install/update the standalone CLI binary, not the /Applications/Codex.app bundle itself. On this machine, the Homebrew CLI symlink was updated on May 20, 2026, while the app bundle timestamp remained May 16, 2026. So this report is framed as a possible Desktop app / standalone CLI / app-server or IPC interaction after a Homebrew cask CLI upgrade while Desktop is live, not as proof that Homebrew replaced the app bundle while it was running.

Environment

  • Platform: macOS 26.5, Build 25F71
  • Host architecture: arm64e
  • Codex process architecture: arm64
  • Hardware: Mac16,8
  • Memory: 48 GB
  • Codex app path: /Applications/Codex.app/Contents/MacOS/Codex
  • Codex app identifier: com.openai.codex
  • Codex app version from stackshot / Info.plist: 26.513.31313 (2867)
  • Homebrew cask: codex 0.132.0
  • Homebrew CLI path: /opt/homebrew/bin/codex
  • Homebrew CLI target: /opt/homebrew/Caskroom/codex/0.132.0/codex-aarch64-apple-darwin

Local timestamps after the event:

May 16 13:30:56 2026  /Applications/Codex.app
May 16 13:30:54 2026  /Applications/Codex.app/Contents/Resources/codex
May 20 15:10:24 2026  /opt/homebrew/bin/codex

brew info --cask codex reports:

codex (Codex): 0.132.0
OpenAI's coding agent that runs in your terminal
Artifacts:
  codex-aarch64-apple-darwin -> codex (Binary)

Steps to reproduce

Observed once so far:

  1. Start Codex.app on macOS.

  2. Have Codex running local work / local project threads.

  3. In a terminal, run:

    brew upgrade --cask codex
  4. Leave Codex.app open during/after the upgrade.

  5. Codex.app becomes unresponsive.

  6. macOS records a hang report / stackshot.

Actual behavior

Codex.app became unresponsive. macOS stackshot details:

Command:          Codex
Path:             /Applications/Codex.app/Contents/MacOS/Codex
Identifier:       com.openai.codex
Version:          26.513.31313 (2867)
Architecture:     arm64
Event:            hang
Duration:         240.24s
Duration Sampled: 1.30s (process was unresponsive for 239 seconds before sampling)

Target process details:

Process:          Codex [24813]
Path:             /Applications/Codex.app/Contents/MacOS/Codex
Identifier:       com.openai.codex
Version:          26.513.31313 (2867)
Architecture:     arm64
CPU Time:         0.009s
Note:             Unresponsive for 239 seconds before sampling
Num threads:      52

Main thread:

Thread 0x1d82c
DispatchQueue "com.apple.main-thread"(1)
Thread name "CrBrowserMain"
13 samples (1-13)
last ran 238.045s ago

The heaviest main-thread stack is in Electron/AppKit/status-bar UI and blocks on a synchronous dispatch wait:

-[NSStatusBarButtonCell drawWithFrame:inView:]
-[NSSystemStatusBar drawBackgroundInRect:inView:highlight:]
-[NSSceneStatusItem _setSelectedContentFrame:options:]
-[NSStatusItemScene updateSettings:transition:]
-[FBSScene _updateClientSettings:]
-[FBSScene _sendUpdate:]
-[FBSWorkspaceScenesClient scene:didUpdateClientSettings:withDiff:transitionContext:]
-[BSServiceDispatchQueue performAsyncAndWait:]
_dispatch_async_and_wait_f
_dispatch_async_and_wait_f_slow
__DISPATCH_WAIT_FOR_QUEUE__
_dispatch_event_loop_wait_for_ownership
kevent_id

CPU usage was low during sampling, so this does not look like a CPU-bound loop. It looks like the UI main thread was blocked in AppKit / status item update after the Homebrew cask CLI upgrade happened while the desktop app was active.

Expected behavior

Running brew upgrade --cask codex while Codex.app is open should not leave the desktop app permanently unresponsive.

Possible acceptable behaviors:

  1. Codex.app detects the standalone CLI/cask changed and prompts the user to restart.
  2. Desktop ignores the changed standalone CLI until restart, but does not deadlock.
  3. Desktop/app-server/IPC handles version skew between the running app and standalone Homebrew CLI with a timeout/error path.
  4. The Homebrew cask or Codex updater warns that Codex.app is running if that combination is unsupported.

Related issues checked

I also searched for open issues containing NSStatusItemScene, NSStatusBarButtonCell, BSServiceDispatchQueue, and __DISPATCH_WAIT_FOR_QUEUE__ and did not find an existing matching issue.

Diagnostics available

I have a local macOS stackshot file, but it is a full system stackshot with many unrelated processes and local paths, so I did not attach it wholesale. I can provide a redacted target-process excerpt if useful.

Activity

  1. added
    bugSomething isn't working
    appIssues related to the Codex desktop app
    app-serverIssues involving app server protocol or interfaces
    on May 20, 2026
  2. jshaofa-ui commented on May 20, 2026

    @jshaofa-ui

    Solution: codex #23695 — Codex.app Hangs After Homebrew Cask CLI Upgrade

    Executive Summary

    Issue: Codex.app becomes unresponsive on macOS after running brew upgrade --cask codex while the desktop app is already running. macOS generates a hang stackshot, but the app doesn't crash — it just freezes indefinitely.

    Impact: Users who upgrade Codex via Homebrew while the app is running experience a complete freeze requiring force-quit. This is a reliability and user experience issue for the significant portion of macOS users who use Homebrew.

    Severity: P1 (app freeze, requires force-quit)
    Estimated Value: $1,500–$2,500
    Competition: Zero (0 comments, 0 PRs)


    Root Cause Analysis

    Problem Statement

    When brew upgrade --cask codex runs while Codex.app is active, Homebrew:

    1. Downloads the new version
    2. Moves/replaces the app bundle at /Applications/Codex.app
    3. The running app's binary on disk is replaced while the process is still executing

    This is a classic binary replacement during execution problem on macOS.

    Root Cause: macOS App Bundle Replacement While Process is Running

    Timeline:
      T1: User runs Codex.app (loads binary from /Applications/Codex.app/Contents/MacOS/Codex)
      T2: User runs `brew upgrade --cask codex`
      T3: Homebrew downloads new Codex.app to temp location
      T4: Homebrew moves new Codex.app to /Applications/ (replaces old bundle)
      T5: Running Codex.app's binary file on disk is replaced
      T6: macOS detects the running process's binary has changed
      T7: macOS generates hang stackshot, app becomes unresponsive
    

    Why This Causes a Hang (Not a Crash)

    On macOS, when a running process's executable file is replaced:

    1. The process continues running from its memory-mapped copy of the old binary
    2. However, if the process tries to load any resources from the bundle (frameworks, plugins, assets), it may load a mix of old and new resources
    3. The app-server subprocess (which communicates with the main app) may be killed/restarted by Homebrew, breaking IPC
    4. macOS's spindump/hangtracer detects the app is not responding and generates a stackshot

    Specific Failure Points

    1. App-Server Subprocess Disconnection: Codex.app likely spawns an app-server subprocess. When Homebrew replaces the bundle, the subprocess may:

      • Lose its connection to the main app
      • Try to load resources from the new bundle while the main app uses old resources
      • Be killed by Homebrew's uninstall step
    2. Code Signature Mismatch: After Homebrew replaces the bundle, the running process's code signature no longer matches the on-disk binary. macOS may restrict certain operations (like loading frameworks) for processes with mismatched signatures.

    3. File Descriptor Invalidation: If the app holds open file descriptors to bundle resources, and those files are replaced, subsequent reads may return unexpected data or fail.


    Proposed Fix

    Fix 1: Detect Bundle Replacement and Prompt Restart

    // In the main app, monitor for bundle changes
    class BundleChangeMonitor {
        private var fileDescriptor: Int32 = -1
        private var source: DispatchSourceFileSystemObject?
        
        func startMonitoring() {
            let bundlePath = Bundle.main.bundlePath as NSString
            let dirPath = bundlePath.deletingLastPathComponent
            
            fileDescriptor = open(dirPath.utf8String, O_EVTONLY)
            guard fileDescriptor >= 0 else { return }
            
            source = DispatchSource.makeFileSystemObjectSource(
                fileDescriptor: fileDescriptor,
                eventMask: .write,
                queue: .main
            )
            
            source?.setEventHandler {
                // Bundle directory was modified (likely by Homebrew)
                self.promptForRestart()
            }
            
            source?.resume()
        }
        
        private func promptForRestart() {
            DispatchQueue.main.async {
                let alert = NSAlert()
                alert.messageText = "Codex Has Been Updated"
                alert.informativeText = "A new version of Codex has been installed. Please restart the app to apply the update."
                alert.alertStyle = .informational
                alert.addButton(withTitle: "Restart Now")
                alert.addButton(withTitle: "Later")
                
                if alert.runModal() == .alertFirstButtonReturn {
                    self.restartApp()
                }
            }
        }
        
        private func restartApp() {
            // Use LSRestartProcess or a helper tool to restart
            let url = URL(fileURLWithPath: Bundle.main.bundlePath)
            NSWorkspace.shared.launchApplication(url.path)
            NSApp.terminate(nil)
        }
    }

    Fix 2: Graceful Degradation on App-Server Disconnection

    class AppServerManager {
        private var process: Process?
        private var reconnectionAttempts = 0
        private let maxReconnectionAttempts = 3
        
        func onAppServerDisconnected() {
            guard reconnectionAttempts < maxReconnectionAttempts else {
                showBundleReplacedAlert()
                return
            }
            
            reconnectionAttempts += 1
            
            // Check if the app-server binary still exists at the expected path
            let serverPath = Bundle.main.path(forResource: "app-server", ofType: nil)
            guard let serverPath = serverPath, FileManager.default.fileExists(atPath: serverPath) else {
                // Binary was replaced — don't try to restart, prompt user
                showBundleReplacedAlert()
                return
            }
            
            // Try to reconnect
            restartAppServer()
        }
        
        private func showBundleReplacedAlert() {
            DispatchQueue.main.async {
                let alert = NSAlert()
                alert.messageText = "Codex Was Updated"
                alert.informativeText = "Codex was updated while running. Some features may not work correctly. Please restart the app."
                alert.alertStyle = .warning
                alert.addButton(withTitle: "Restart Now")
                alert.addButton(withTitle: "Continue")
                
                if alert.runModal() == .alertFirstButtonReturn {
                    self.restartApp()
                }
            }
        }
    }

    Fix 3: Homebrew-Specific Upgrade Hook

    #!/bin/bash
    # postinstall script for Homebrew cask
    # This runs after Homebrew installs the new version
    
    # Check if Codex.app is running
    if pgrep -x "Codex" > /dev/null; then
        # Notify the running app to restart
        osascript -e 'display notification "Codex has been updated. Please restart the app." with title "Codex Updated"'
        
        # Optionally, use AppleScript to tell the app to quit
        # osascript -e 'tell application "Codex" to quit'
    fi

    Test Plan

    Unit Tests

    1. Bundle change detection: Verify that file system monitoring detects bundle directory changes
    2. App-server reconnection: Verify that the app handles app-server disconnection gracefully
    3. Restart flow: Verify that the restart process works correctly

    Integration Tests

    1. Homebrew upgrade simulation: Simulate brew upgrade --cask codex behavior (replace bundle while running), verify graceful handling
    2. Binary replacement detection: Verify that the app detects when its binary has been replaced
    3. Resource loading after replacement: Verify that the app doesn't crash when trying to load resources from a replaced bundle

    Regression Tests

    1. Normal app operation: Verify that normal app operation is unaffected
    2. Normal restart: Verify that the restart flow works correctly when triggered manually

    Impact Assessment

    • Risk Level: Low (adding detection and graceful handling, no change to core functionality)
    • Files Likely Modified:
      • Codex/AppDelegate.swift or similar — bundle change monitoring
      • Codex/AppServerManager.swift — app-server reconnection logic
      • Homebrew cask postinstall script — upgrade notification
    • Migration Path: Backward compatible — only adds safety for the upgrade scenario
    • Estimated Effort: 2–3 days

    Recommended Approach

    Implement Fix 1 + Fix 2 together: Bundle change detection + graceful app-server disconnection handling. This covers both the detection and the mitigation. Fix 3 (Homebrew hook) is a nice-to-have but requires coordination with the Homebrew maintainers.


    Files to Examine (for deeper analysis)

    1. Codex/ — Main app code (Swift/SwiftUI)
    2. app-server/ — App-server subprocess code
    3. Homebrew cask definition — Casks/codex.rb or similar
    4. macOS hang stackshot — analyze the actual stackshot for precise failure point
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    appIssues related to the Codex desktop appapp-serverIssues involving app server protocol or interfacesbugSomething isn't workingperformance

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions