macOS: app hangs after wake — ghostty_surface_free blocks on renderer stuck in CVDisplayLinkStop

[shyim]

Issue Description

Ghostty's main thread hung for about 82 seconds shortly after my Mac woke from sleep, and the whole app stopped responding. macOS wrote a .hang report. The build that hung already includes #14171 (which fixed #14150); 56a3437 is 160 commits after its merge commit 82232ec. So this is a separate path to the same underlying CoreVideo stall.

What the stackshot shows:

1. The renderer thread (0xfa6ffa) is blocked in CVDisplayLink::stop(), reached from the renderer's own code on that thread. It "last ran 120.078s ago", which is before the main thread hung. So it got stuck first, during normal display-link sync rather than teardown. The report was taken 46s after wake.
2. Later, the undo timer for a closed surface fired (ExpiringUndoManager.removeAllActions → SurfaceView deinit → ghostty_surface_free). Surface.deinit joins the renderer thread (renderer_thr.join()), and that join never returns.
3. The CoreVideo display-link threads are idle in CVDisplayLink::waitUntil, and none of them is running Ghostty code. Ghostty isn't holding anything they need; CoreVideo stalls internally, presumably during the display reconfiguration after wake.

#14171 made sure draw_mutex isn't held while stopping. But any CVDisplayLinkStop on the renderer thread can still block indefinitely, and the main thread joins that thread when freeing a surface, so a CoreVideo stall still freezes the app. Renderer.deinit also calls stop() directly on the main thread.

Possible fix: I have a local patch that moves all display-link start/stop onto a per-renderer serial dispatch queue (dispatch_async_f). Requests that arrive while one is queued are merged into one job. On teardown the callback is switched off, then stop and release run on that queue, so neither the renderer nor the main thread ever calls CVDisplayLinkStop directly. I'm glad to share it if this approach seems right.

Expected Behavior

Closing or freeing a surface never blocks the main thread. A stalled CoreVideo display link should at worst delay vsync for that surface, not hang the app

Actual Behavior

The main thread blocks in ghostty_surface_free waiting for the renderer thread, which is stuck in CVDisplayLinkStop. The app was unresponsive for about 82s

Reproduction Steps

It's intermittent, and I don't have a deterministic reproduction. It happens under these conditions:

1. Open Ghostty with a few splits or tabs, then close one (so it sits in the undo stack).
2. Put the Mac to sleep, then wake it (display reconfiguration).
3. The renderer's display-link sync calls CVDisplayLinkStop while CoreVideo stalls.
4. When the closed surface's undo expiry fires, the main thread joins the stuck renderer thread and the app hangs.

Ghostty Logs

Event: hang, Duration: 82.33s (unresponsive 80s before sampling)
Time Since Wake: 46s

Main thread (com.apple.main-thread), last ran 80.415s ago:
  __NSFireTimer
   closure #1 in ExpiringTarget.init(_:expiresAfter:in:)
    ExpiringTarget.expire()
     ExpiringUndoManager.removeAllActions(withTarget:)
      -[NSUndoManager removeAllActionsWithTarget:]
       ... Ghostty.SurfaceView.__deallocating_deinit
        Ghostty.Surface.deinit
         ghostty_surface_free
          __ulock_wait  (blocked by turnstile waiting for ghostty thread 0xfa6ffa)

Thread 0xfa6ffa "renderer", last ran 120.078s ago:
  _pthread_start
   ??? (ghostty + 8426668)   [renderer thread main]
    ??? ... (5 more ghostty frames)
     CVDisplayLink::stop() + 148
      __psynch_cvwait

CVDisplayLink threads (8): all in CVDisplayLink::runIOThread → waitUntil → __psynch_cvwait,
no Ghostty frames.

Ghostty Version

hostty 1.3.2-main-+56a3437a7   (build that hung, report Version: 56a3437a7 (17893))

Current build (same code path): 1.3.2-main-+22391ed64
  - channel: tip
  - Zig version   : 0.16.0
  - build mode    : .ReleaseFast
  - app runtime   : .none
  - font engine   : .coretext
  - renderer      : renderer.generic.Renderer(renderer.Metal)
  - libxev        : kqueue

OS Version Information

macOS 27.0 (26A428), Mac15,9 (Apple Silicon)

(Linux only) Display Server

None

(Linux only) Desktop Environment/Window Manager

No response

Minimal Ghostty Configuration

theme = dark:Ayu,light:Ayu light
font-family = JetBrainsMono Nerd Font
font-size = 11
shell-integration-features = sudo,ssh-env
window-inherit-working-directory = false
tab-inherit-working-directory = false
working-directory = home
keybind = shift+enter=text:\n
macos-option-as-alt = true
auto-update-channel = tip

Additional Relevant Configuration

No response

I acknowledge that:

• I have reviewed the FAQ and confirm that my issue is NOT among them.
• I have searched the Ghostty documentation and confirm there doesn't exist a configuration option that solves my issue.
• I have searched the Ghostty repository (both open and closed Discussions and Issues) and confirm this is not a duplicate of an existing issue or discussion.
• I have checked the "Preview" tab on all text fields to ensure that everything looks right, and have wrapped all configuration and code in code blocks with a group of three backticks (```) on separate lines.

[shyim]

Claude fix was shyim@78f2acdf1 testing it out now few hours

[lswang6]

Setup: headless Mac mini on macOS 27.0, with an iPad over Sidecar plus a BetterDisplay virtual display. Tip 22391ed hung twice in one afternoon when Sidecar disconnected or reconnected. The path was slightly different from your trace: the renderer thread was stuck in CVDisplayLinkStop, its mailbox filled up, and the main thread blocked pushing to it.

I applied shyim@78f2acdf1 to current main (d40bc77). It applies cleanly, and I've had no hangs over two days so far, including a Sidecar disconnect/reconnect. Thanks @shyim! If the maintainers are OK with the approach, would you consider opening a PR?

Drafted with Claude Code; I tested the patch myself.

[shyim]

thats why i created this discussion, as there is this vouch thingy here