macOS: permanent deadlock during the display reconfiguration that follows wake from sleep — renderer thread blocked forever in CVDisplayLinkStop()

[XhstormR]

Issue Description

Ghostty freezes permanently the instant the machine wakes from sleep. It is a
two-thread deadlock between the renderer thread and the main thread, triggered by
the display reconfiguration that wake produces.

Symptom

The window is completely frozen: no redraw, no keyboard input. The rest of the
system is unaffected. The process burns ~0% CPU, produces no crash report, and
macOS does not flag it as "Not Responding" (lsappinfo reports
StatusLabel = kCFNULL), so no force-quit dialog is ever offered. Only kill
recovers. In my capture the process sat deadlocked for 23 minutes before I gave up
and killed it; it would have stayed that way indefinitely.

The deadlock

Renderer thread — blocked forever in CVDisplayLinkStop(), which is a
synchronous join waiting for the display link's IO thread to acknowledge the stop:

??? (ghostty + 8054316) [0x102a0262c]   <- libxev / kqueue loop
  ??? (ghostty + 8628820) [0x102a8ea54]
    ??? (ghostty + 8443364) [0x102a615e4]
      ??? (ghostty + 8242636) [0x102a305cc]
        ??? (ghostty + 8267428) [0x102a366a4]
          CVDisplayLink::stop() + 148 (CoreVideo + 10708) [0x18fcf19d4]
            __psynch_cvwait + 8 (libsystem_kernel.dylib + 17676) [0x1852ef50c]

Main thread — blocked forever on a Zig futex, called from inside a
CoreAnimation transaction commit, which AppKit is running in order to react to the
screen change:

__CFRUNLOOP_IS_CALLING_OUT_TO_AN_OBSERVER_CALLBACK_FUNCTION__ + 36
  UC::DriverCore::continueProcessing() + 84 (UpdateCycle)
    stepTransactionFlush + 220 (AppKit + 9908424) [0x18a15c0c8]
      CA::Transaction::flush_as_runloop_observer(bool) + 140 (QuartzCore)
        CA::Transaction::commit() + 652 (QuartzCore + 9504) [0x18f421520]
          CA::Context::commit_transaction(CA::Transaction*, double, double*) + 620
            CA::Layer::display_if_needed(CA::Transaction*) + 784 (QuartzCore + 137188)
              ??? (ghostty + 8639068) [0x102a9125c]
                ??? (ghostty + 8242580) [0x102a31d94]
                  __ulock_wait2 + 8 (libsystem_kernel.dylib + 60568) [0x1852f9c98]

Because the main thread blocks inside CA::Transaction::commit(), it holds the
CoreAnimation transaction lock and never returns to the run loop. That is why the
entire window freezes rather than just the terminal content, and why AppKit never
reports the app as unresponsive.

The spindump puts the renderer thread's last run 21 ms before the main
thread's (last ran 1399.730s ago vs 1399.709s ago; larger = earlier). Renderer
first, main thread second — the ordering required if the renderer is the lock
holder and the main thread is the waiter, and not what you would see if both were
independent victims of a stalled WindowServer.

Where in the source

The binary is stripped so I cannot symbolize the ??? (in ghostty) frames
directly (see "Diagnostics limitations" below). But the frame count and the source
structure line up exactly on one path, in
src/renderer/generic.zig:

// src/renderer/generic.zig, fn syncDisplayLink  (~L1150)
//   "Create or update the display link and match it to the current surface state."

if (display_id) |id| {
    log.info("updating display link display id={}", .{id});
    display_link.setCurrentCGDisplay(id) catch |err| {          // ~L1185
        log.warn("error setting display link display id err={}", .{err});
    };
}

const should_run =
    // Non-visible windows never vsync
    self.visible and
    // Only vsync if we have cell changes or animation
    (self.cells_rebuilt or self.animationWake() != null);       // ~L1193

if (should_run) {
    if (!display_link.isRunning()) {
        display_link.start() catch {};
    }
} else {
    display_link.stop() catch {};                               // ~L1197  <-- blocks here
}

syncDisplayLink has two callers that a wake will hit:

• setVisible(visible) (~L1101) — "Callback when the window is visible or
  occluded", calls syncDisplayLink(null, null);
• setMacOSDisplayID(id, draw_now) (~L996) — "Called when we get an updated
  display ID for our display link", calls syncDisplayLink(id, draw_now).

Both run on the render thread. Either chain — loop handler → setVisible → syncDisplayLink → DisplayLink.stop() or loop handler → setMacOSDisplayID → syncDisplayLink → DisplayLink.stop() — is exactly 3 intermediate frames between
the libxev loop and the DisplayLink.stop() wrapper, matching the 3 unsymbolized
frames 0x102a8ea54, 0x102a615e4, 0x102a305cc in the stack above.

The locking problem. draw_mutex is documented as:

/// This mutex must be held whenever any state used in `drawFrame` is
/// being modified, and also when it's being accessed in `drawFrame`.
draw_mutex: std.Io.Mutex = .init,

syncDisplayLink reads self.visible and self.cells_rebuilt and calls
self.animationWake() — all drawFrame state. So by that contract it runs under
draw_mutex, and it performs a blocking CVDisplayLinkStop() while holding it.
Meanwhile the main thread's blocked frame is the layer-display callback inside
CA::Layer::display_if_needed, i.e. the draw path, which needs the same lock.
Since AppKit runs that commit as its reaction to a screen change, the two paths
collide by construction on every display reconfiguration. (If syncDisplayLink
does not hold draw_mutex, then it violates its own documented contract while
reading draw state — either way there is something to fix here.)

Why the display link is running at all: custom-shader

animationWake() (~L1034) is documented as "Custom shaders animate by redrawing
on a fixed cadence, gated by configuration and focus" and starts with:

const shader_delay: ?u64 = shader: {
    if (!self.has_custom_shaders) break :shader null;
    break :shader switch (self.config.custom_shader_animation) { ...

has_custom_shaders is options.config.custom_shaders.value.items.len > 0 (~L676).

I have two custom-shader entries configured and custom-shader-animation = true
(the default). So animationWake() != null while the window is focused, should_run
is true, and the display link runs continuously. When wake flips visible to
false, or takes focus away, should_run flips to false and stop() is called on a
link that is actually running — the case where CVDisplayLinkStop() really has to
join its IO thread rather than returning immediately.

Without custom shaders the link only runs when cells_rebuilt, so on an idle
terminal stop() mostly hits an already-stopped link and returns immediately. That
makes custom-shader a plausible necessary condition, or at minimum a large risk
amplifier. I have not bisected this; see the Minimal Configuration field.

Why the stop never completes: 1 display-link object, 2 live IO threads

heap <pid> reports exactly one live CVDisplayLink:

       1       1536    1536.0   CVDisplayLink        CFType   CoreVideo

but the spindump lists two live CVDisplayLink IO threads (0x1fa250,
0x1fa25c), both with thread IDs far above the startup threads (0x192e5x /
0x192e6x), i.e. both created long after launch — consistent with creation during
a display reconfiguration.

And neither is wedged. Both are looping normally, consuming CPU, last ran 0.019s ago inside the sampling window:

Thread 0x1fa25c "CVDisplayLink"  cpu time 0.012s  last ran 0.019s ago
  495  CVDisplayLink::runIOThread() → CVDisplayLink::waitUntil() → __psynch_cvwait
    6  CVDisplayLink::runIOThread() → CVXTime::update() → ... → CVCGDisplayLink::updateDisplayTiming()
Thread 0x1fa250 "CVDisplayLink"  cpu time 0.011s
  498  CVDisplayLink::runIOThread() → CVDisplayLink::waitUntil() → __psynch_cvwait
    3  CVDisplayLink::runIOThread() → ... → CVCGDisplayLink::updateDisplayTiming()

So CVDisplayLinkStop() is waiting on a condition variable that no live IO thread
will ever signal. In 501 spindump samples, zero show
CVDisplayLink::performIO() calling back into Ghostty — the IO threads spin
without delivering frames.

What the OS was doing at that instant

Merged millisecond timeline from Ghostty's log and WindowServer's log:

13:41:51.186  WS       Display 5 setEnabled:0            <- real display (3440x1440) off
13:41:51.188  WS       Display 9 setEnabled:1            <- transient synthetic display on
13:41:51.206  ghostty  main thread starts handling reconfiguration notifications
13:41:51.208  ghostty  Display 0x00000009: Mode 0, (0 x 0) [1920 x 1080], active
13:41:51.208  ghostty  NSApplication._react(to:) displaySetChanges=3  reactions=3f5
13:41:51.283  ghostty  kCGSDisplayDidReconfigure2   <- last line the main thread ever emits
13:41:51.498  WS       Display 5 hotplug-state 1: timing 0xbfd099a70; 54 timing modes
13:41:51.563  WS       Display 5 setEnabled:1            <- real display back on
~13:41:51.84  ghostty  renderer thread stops running  (spindump: 21 ms before main)
13:41:51.846  WS       Display 9 setEnabled:0            <- transient display torn down
13:41:51.855  ghostty  E [com.apple.corevideo:] [0xa988d9220] Bad CurrentVBLDelta for
                       display 9 is zero. defaulting to 60Hz.   (on CVDisplayLink TID 1fa25c)
~13:41:51.86  ghostty  main thread stops running
13:41:52.108  WS       Timed out 0.250s wait for reply for synchronous notification
                       type 115 (kCGSDisplayDidReconfigure2) (CID 0xdabc7, PID 96728)

kCGSDisplayDidReconfigure2 is a synchronous notification — WindowServer blocks
up to 0.25 s per client for a reply. Ghostty answered round 1 (it logged it at
.283) and never answered round 2 (timeout recorded at 13:41:52.108). That brackets
the main thread's death to ≈13:41:51.86, inside that notification's handling.
Eight other processes also timed out on round 1 at 13:41:51.459 and all
recovered — being slow here is normal, never replying is not.

Note the transient display: macOS briefly creates a synthetic
Mode 0, (0 x 0) [1920 x 1080] display during wake and tears it down ~660 ms
later. CoreVideo reports a zero VBL delta for display 9 9 ms after WindowServer
disabled it. A display link bound to that display via
setCurrentCGDisplay(9) would be pointing at a display that has just ceased to
exist.

Control: an earlier wake in the same process that did NOT deadlock

The same process survived a wake at 11:50:27 before deadlocking at 13:41:51. On
WindowServer's side the two wakes are structurally identical:

failing wake                              healthy wake
13:41:51.186  Display 5 setEnabled:0      11:50:27.660  Display 5 setEnabled:0
13:41:51.188  Display 9 setEnabled:1      11:50:27.662  Display 8 setEnabled:1
13:41:51.498  Display 5 54 timing modes   11:50:27.958  Display 5 54 timing modes
13:41:51.563  Display 5 setEnabled:1      11:50:27.962  Display 5 setEnabled:1
13:41:51.846  Display 9 setEnabled:0      11:50:28.244  Display 8 setEnabled:0
              (span 660 ms)                             (span 584 ms)

Five steps, same order, comparable timings. WindowServer did nothing unusual on
the failing wake. It is healthy in the same spindump (CPU Time: 2.094s across 30
threads in a 5-second window, no unresponsive note), and
system_profiler SPDisplaysDataType run while Ghostty was still frozen reported
PHL 345E2 / 3440 x 1440 / 60.00Hz / Main Display: Yes / Online: Yes — the OS
recovered completely. The deadlock is entirely intra-process.

On Ghostty's side the healthy wake ran the same round 1 — same transient
(0 x 0) [1920 x 1080] mode, same two CALocalDisplayUpdateBlock returned NO
errors — then went on to process round 2, picked up the real
Mode 77, [3440 x 1440], and settled at displaySetChanges=1. So neither the
transient bogus mode nor CALocalDisplayUpdateBlock returned NO is sufficient on
its own. The failing wake differs in exactly two respects: CoreVideo logged
Bad CurrentVBLDelta ... is zero (the healthy wake did not), and Ghostty never
processed round 2 — the latter being a consequence of the main thread already
being deadlocked, since those CGSDisplayNotifyProc lines are emitted by Ghostty's
own callback on its own main thread.

Suggested direction

1. Don't call CVDisplayLinkStop() while holding draw_mutex. This is what
   turns a CoreVideo stall into a whole-application deadlock with no "Not
   Responding" indication. Either drop the lock across the stop, or move off the
   deprecated CVDisplayLink API to CADisplayLink (macOS 14+), whose
   invalidation is not a blocking join on an IO thread.
2. Don't bind the display link to the transient wake-time display. Deferring
   the setCurrentCGDisplay rebind until the reconfiguration settles
   (kCGSDisplayReconfigureHappened, or displaySetChanges returning to 1) would
   avoid the ~660 ms window in which the bound display is about to disappear.
3. Audit display-link start/stop across reconfiguration. One live
   CVDisplayLink object with two live IO threads, both created during
   reconfiguration, is an anomaly worth explaining on its own. Note also that both
   stop sites swallow the result (display_link.stop() catch {}) and deinit
   proceeds to display_link.release() regardless, so a failed stop is
   indistinguishable from a successful one.
4. A timeout, or an assertion that the stop is issued from a known-safe context,
   would at minimum turn this from a silent permanent hang into a diagnosable
   event.

Diagnostics limitations

• lldb -p <pid> → error: attach failed (Not allowed to attach to process.).
  The signed release build has no get-task-allow entitlement, so I cannot read
  out the futex address or the lock owner.

• heap -addresses CVDisplayLink <pid> → Process is not debuggable. Due to security restrictions, heap can only show contents of readonly memory of restricted processes. Plain heap type/count output still works.

• The shipped binary is stripped; only the exported ghostty_* C ABI symbols
  survive, so sample, atos and nm resolve none of the ??? (in ghostty)
  frames (nm-based nearest-symbol resolution produced offsets of 200 000+ bytes
  and is pure noise). All Ghostty frames above are quoted with the load address so
  you can symbolize them from your own build artifacts for c81f0b268:

  atos -o <unstripped ghostty binary or dSYM> -arch arm64 -l 0x102254000 \
       0x102a9125c 0x102a31d94 0x102a366a4 0x102a305cc 0x102a615e4 0x102a8ea54 0x102a5c340 0x102a0262c

• Ghostty's own Zig-side renderer logs are not in the unified log: filtering
  the hung process's entire 40-minute log window for com.mitchellh.ghostty
  yields 0 lines. In particular
  log.info("updating display link display id={}", .{id}) — which would say
  exactly which CGDirectDisplayID the link was bound to — is unavailable
  post-hoc. Capturing it requires launching Ghostty from another terminal so its
  stderr is visible. I will do that on the next reproduction attempt.

Expected Behavior

Ghostty survives wake from sleep: the display link is re-bound to the restored
display, the window redraws, and keyboard input works.

Specifically, CVDisplayLinkStop() — a synchronous join on a CoreVideo IO thread —
should never be invoked from a context that can block the CoreAnimation commit
path, because AppKit runs that commit as its reaction to every display
reconfiguration. If the stop cannot complete, Ghostty should degrade (drop vsync,
log a warning) rather than deadlock; and if it does hang, macOS should at least be
able to mark the app unresponsive so the user can force-quit it from the UI.

Actual Behavior

The window is permanently frozen the instant the machine wakes. No redraw, no
input, ~0% CPU (0.025 s of CPU across a 1404 s window), no crash report, and
StatusLabel = kCFNULL so macOS never marks it "Not Responding" and never offers
a force-quit dialog. The only recovery is kill from another terminal.

The renderer thread is blocked in CVDisplayLinkStop() → pthread_cond_wait and
the main thread is blocked on __ulock_wait2 inside CA::Transaction::commit(),
both continuously for 1399.7 s at the time of the spindump and still stuck 23
minutes later. Three sample runs 4 minutes apart show every thread pinned at an
identical frame in 100% of samples (4144/4144, 2516/2516, 1677/1677), so this is a
true deadlock and not slow progress.

Reproduction Steps

1. MacBook Pro (M4 Max, Mac16,5) in clamshell mode — lid closed, built-in
   display not enumerated — driving a single external display at 3440x1440
   @ 60 Hz.
2. Run Ghostty with custom-shader configured (two shaders, attached) and
   custom-shader-animation = true (default), plus
   background-opacity = 0.7 / background-blur = true.
3. Leave the window focused and idle. Let the machine idle-sleep (display turns
   off, then Idle Sleep).
4. Wake the machine via HID activity.
5. Ghostty's window is frozen; the rest of the system is fine. No force-quit
   prompt is offered. kill <pid> is the only way out.

This is not deterministic. The same process survived a sleep/wake cycle at
11:50 and deadlocked on the next one at 13:41. Two cheap signatures distinguish a
failing wake from a healthy one, neither needing root:

# 1. CoreVideo saw invalid timing for the transient wake-time display
/usr/bin/log show --process <ghostty-pid> --last 30m --info --debug --style compact \
  | grep -i 'CurrentVBLDelta'

# 2. WindowServer gave up waiting for ghostty to answer a synchronous display notification
/usr/bin/log show --process $(pgrep -x WindowServer) --last 30m --info --debug --style compact \
  | grep -E "Timed out.*kCGSDisplayDidReconfigure2.*PID <ghostty-pid>"

And a one-second check for whether a live Ghostty is in this state:

sample $(pgrep -x ghostty) 1 -f /dev/stdout 2>/dev/null | grep -q 'CVDisplayLink::stop' \
  && echo DEADLOCKED

Ghostty Logs

=== NOTE ===
Ghostty's own Zig-side logs are NOT in the macOS unified log: filtering the hung
process's entire 40-minute log window for subsystem "com.mitchellh.ghostty"
yields 0 lines. Everything below is from Apple subsystems (SkyLight, QuartzCore,
CoreVideo, AppKit) attributed to the ghostty process, plus sample/spindump/heap
output. Full files attached.

=== spindump: main thread (501/501 samples, last ran 1399.709s ago) ===
501  start + 6992 (dyld + 132324) [0x184f644e4]
  501  main + 140 (ghostty + 9404) [0x1022564bc]
    501  NSApplicationMain + 880 (AppKit + 18352) [0x1897ed7b0]
      501  -[NSApplication run] + 368 (AppKit + 180540) [0x18981513c]
        501  -[NSApplication(NSEventRouting) nextEventMatchingMask:untilDate:inMode:dequeue:] + 72
          501  -[NSApplication(NSEventRouting) _nextEventMatchingEventMask:untilDate:inMode:dequeue:] + 688
            501  _DPSNextEvent + 576
              501  _DPSBlockUntilNextEventMatchingListInMode + 228
                501  _BlockUntilNextEventMatchingListInMode + 48 (HIToolbox)
                  501  ReceiveNextEventCommon + 488
                    501  RunCurrentEventLoopInMode + 320
                      501  _CFRunLoopRunSpecificWithOptions + 484
                        501  __CFRunLoopDoObservers + 648
                          501  __CFRUNLOOP_IS_CALLING_OUT_TO_AN_OBSERVER_CALLBACK_FUNCTION__ + 36
                            501  UC::DriverCore::continueProcessing() + 84 (UpdateCycle)
                              501  stepTransactionFlush + 220 (AppKit + 9908424) [0x18a15c0c8]
                                501  CA::Transaction::flush_as_runloop_observer(bool) + 140 (QuartzCore)
                                  501  CA::Transaction::commit() + 652 (QuartzCore + 9504) [0x18f421520]
                                    501  CA::Context::commit_transaction(CA::Transaction*, double, double*) + 620
                                      501  CA::Layer::display_if_needed(CA::Transaction*) + 784 (QuartzCore + 137188) [0x18f4407e4]
                                        501  ??? (ghostty + 8639068) [0x102a9125c]
                                          501  __ulock_wait2 + 8 (libsystem_kernel.dylib + 60568) [0x1852f9c98]
                                           *501  ??? (kernel.release.t6041 + 6548016) [0xfffffe000bd7ea30]

(sample resolves one more ghostty frame that spindump collapses:
   CA::Layer::display_if_needed + 784
     ??? (in ghostty)  load address 0x102254000 + 0x83d25c  [0x102a9125c]
       ??? (in ghostty)  load address 0x102254000 + 0x7ddd94  [0x102a31d94]
         __ulock_wait2 + 8)

=== spindump: renderer thread (501/501 samples, last ran 1399.730s ago) ===
501  thread_start + 8 (libsystem_pthread.dylib + 7196) [0x18532ac1c]
  501  _pthread_start + 136 (libsystem_pthread.dylib + 27736) [0x18532fc58]
    501  ??? (ghostty + 8422208) [0x102a5c340]     <- renderer thread entry
      501  ??? (ghostty + 8054316) [0x102a0262c]   <- libxev / kqueue loop
        501  ??? (ghostty + 8628820) [0x102a8ea54]
          501  ??? (ghostty + 8443364) [0x102a615e4]
            501  ??? (ghostty + 8242636) [0x102a305cc]
              501  ??? (ghostty + 8267428) [0x102a366a4]   <- DisplayLink.stop() wrapper
                501  CVDisplayLink::stop() + 148 (CoreVideo + 10708) [0x18fcf19d4]
                  501  __psynch_cvwait + 8 (libsystem_kernel.dylib + 17676) [0x1852ef50c]
                   *501  psynch_cvcontinue + 0 (pthread + 17948) [0xfffffe000b67e10c]

=== spindump header ===
Date/Time:        2026-09-05 13:41:51.426 +0800
End time:         2026-09-05 14:05:15.955 +0800
Duration:         1404.53s
Duration Sampled: 5.01s (process was unresponsive for 1400 seconds before sampling)
Time Since Fork:  10866s
CPU Time:         0.025s (31.4M cycles, 30.1M instructions)
Note:             Unresponsive for 1400 seconds before sampling
Num threads:      12 (2 idle work queue threads omitted)

=== spindump: thread list (note TWO CVDisplayLink IO threads) ===
Thread 0x192e52    DispatchQueue "com.apple.main-thread"(1)
Thread 0x1fa25c    Thread name "CVDisplayLink"
Thread 0x1fa250    Thread name "CVDisplayLink"
Thread 0x192e65    Thread name "io-reader"
Thread 0x192e67    Thread name "io-gather"
Thread 0x192e62    Thread name "io"
Thread 0x192e5b    Thread name "com.apple.NSEventThread"
Thread 0x192e61    Thread name "renderer"
Thread 0x192e55                                      (google_breakpad ExceptionHandler)
Thread 0x192e60    Thread name "cf_release"

=== spindump: both CVDisplayLink IO threads are ALIVE and looping ===
Thread 0x1fa25c "CVDisplayLink"  501 samples  priority 54  cpu time 0.012s  last ran 0.019s ago
  495  CVDisplayLink::runIOThread() + 452 -> CVDisplayLink::waitUntil(unsigned long long) + 336 -> __psynch_cvwait
    6  CVDisplayLink::runIOThread() + 544 -> CVXTime::update() -> CVHWTime::update(double, bool*, bool*)
         -> CVCGDisplayLink::getDisplayTimes(...) -> CVCGDisplayLink::updateDisplayTiming()
             5  SLSDisplayGetCurrentVBLDelta + 96 -> realtime_data_for_display(int, bool)
                  -> WS::RealtimeDisplayDataMapping::data() -> ::shmem()
                  -> _CGSGetRealtimeDisplayDataShmemPort -> mach_msg2_trap
                     *4  (blocked by turnstile waiting for WindowServer [413])
             1  SLSDisplayGetCurrentVBLDelta + 288 -> _WSSDisplayGetRefreshTiming -> mach_msg2_trap
Thread 0x1fa250 "CVDisplayLink"  501 samples  priority 54  cpu time 0.011s
  498  CVDisplayLink::runIOThread() + 452 -> CVDisplayLink::waitUntil(unsigned long long) + 336 -> __psynch_cvwait
    3  CVDisplayLink::runIOThread() + 544 -> ... -> CVCGDisplayLink::updateDisplayTiming()

=== heap <pid>: only ONE CVDisplayLink object exists ===
Process 96728: 6 zones
Found:  1553 ObjC classes  1307 Swift classes  224 C++ classes  281 CFTypes
       1       1536    1536.0   CVDisplayLink        CFType   CoreVideo

=== Binary Images (relevant) ===
0x102254000 - 0x10323bfff  com.mitchellh.ghostty c81f0b268 (17709) <FF78904B-7ACA-39FC-BD01-522AEF53B313>
0x18f41f000 - 0x18f834e3f  com.apple.QuartzCore 1195.17
0x18fcef000 - 0x18fd6fbbf  com.apple.CoreVideo 1.8
0x18bb21000 - 0x18c0d7a1f  com.apple.SkyLight 1.600.0 (922.13.1)
0x1897e9000 - 0x18af0c49f  com.apple.AppKit 6.9 (2685.70.101)

=== unified log, ghostty pid, FAILING wake ===
13:41:51.206 Df [SkyLight] CGSDisplayNotifyProc: got notification kCGSDisplayDisplaySystemStateChanged
13:41:51.206 Df [SkyLight] CGSDisplayNotifyProc: display system state seed 137 -> 138
13:41:51.207 Df [SkyLight] CGSDisplayNotifyProc: got notification kCGSDisplayMovedOffConsoleInternal
13:41:51.207 Df [SkyLight] CGSDisplayNotifyProc: got notification kCGSDisplayPrepareForReprobing
13:41:51.208 E  [coreanimation:WindowServer] CALocalDisplayUpdateBlock returned NO
13:41:51.208 Df [SkyLight] CGSDisplayNotifyProc: got notification kCGSDisplayWillReconfigure
13:41:51.208 Df [SkyLight] CGSDisplayNotifyProc: got notification kCGSDisplayUpdateInternalState
13:41:51.208 Df [SkyLight] updateAllDisplayInfoAsNeeded, 666: Display 0x00000009: Mode 0, (0 x 0) [1920 x 1080], Depth 32 BPP, active
13:41:51.208 Df [SkyLight] CGSDisplayNotifyProc: got notification kCGSDisplayHardwareChanged
13:41:51.208 Df [AppKit:Screen] NSApplication._react(to:) displaySetChanges=3
13:41:51.208 Df [AppKit:Screen] NSApplication._react(to:) reactions=3f5
13:41:51.283 E  [coreanimation:WindowServer] CALocalDisplayUpdateBlock returned NO
13:41:51.283 Df [SkyLight] CGSDisplayNotifyProc: got notification kCGSDisplayDidReconfigure2
             <-- main thread (TID 192e52) never logs again -->
13:41:51.855 E  [com.apple.corevideo:] [0xa988d9220] Bad CurrentVBLDelta for display 9 is zero. defaulting to 60Hz.   (TID 1fa25c)
             <-- nothing but RunningBoardServices noise for the next 40 minutes -->

=== unified log, ghostty pid, HEALTHY wake (control, same process, 1h51m earlier) ===
11:50:27.686 Df [SkyLight] kCGSDisplayMovedOffConsoleInternal
11:50:27.686 E  [coreanimation:WindowServer] CALocalDisplayUpdateBlock returned NO
11:50:27.686 Df [SkyLight] kCGSDisplayWillReconfigure
11:50:27.687 Df [SkyLight] Display 0x00000008: Mode 0, (0 x 0) [1920 x 1080], Depth 32 BPP, active
11:50:27.687 Df [SkyLight] kCGSDisplayHardwareChanged
11:50:27.690 Df [AppKit:Screen] NSApplication._react(to:) displaySetChanges=3
11:50:27.762 E  [coreanimation:WindowServer] CALocalDisplayUpdateBlock returned NO
11:50:27.762 Df [SkyLight] kCGSDisplayDidReconfigure2            <- round 1
11:50:27.943 Df [SkyLight] kCGSDisplayReconfigureHappened
11:50:28.257 Df [SkyLight] kCGSDisplayWillReconfigure            <- round 2
11:50:28.264 Df [SkyLight] Display 0x00000005: Mode 77, (0 x 0) [3440 x 1440], Depth 32 BPP, active
11:50:28.264 Df [SkyLight] Display 0x00000001: Mode 0, (0 x 0) [3440 x 1440], inactive
11:50:28.264 Df [SkyLight] kCGSDisplayHardwareChanged
11:50:28.277 Df [SkyLight] kCGSDisplayDidReconfigure2
11:50:28.473 Df [SkyLight] kCGSDisplayReconfigureHappened
11:50:28.494 Df [AppKit:Screen] NSApplication._react(to:) displaySetChanges=1   <- settled
(no "Bad CurrentVBLDelta" line anywhere in this window)

=== unified log, WindowServer pid 413, FAILING wake ===
13:41:51.032 Df Display 5 hotplug-state 0 updating digital modes: color 0x0; timing 0x0
13:41:51.186 Df Display 5 setEnabled:0
13:41:51.188 Df Display 9 setEnabled:1
13:41:51.459 Df Timed out 0.250 second wait for reply from "<private>" for synchronous
                notification type 115 (kCGSDisplayDidReconfigure2) (CID 0xb7103, PID 9592)
                [... 7 more pids, ghostty NOT among them ...]
13:41:51.498 Df Display 5 hotplug-state 1 updating digital modes: color 0xbfd098f60; timing 0xbfd099a70
13:41:51.498 Df Display 5 54 timing modes, 10 color modes
13:41:51.563 Df Display 5 setEnabled:1
13:41:51.580 Df Display 5 hotplug-state 1 updating digital modes: color 0xbfdff5c20; timing 0xbfdfbed00
13:41:51.580 Df Display 5 54 timing modes, 10 color modes
13:41:51.846 Df Display 9 setEnabled:0
13:41:52.108 Df Timed out 0.250 second wait for reply from "<private>" for synchronous
                notification type 115 (kCGSDisplayDidReconfigure2) (CID 0xdabc7, PID 96728)

=== unified log, WindowServer pid 413, HEALTHY wake (control) ===
11:50:27.660 Df Display 5 setEnabled:0
11:50:27.662 Df Display 8 setEnabled:1
11:50:27.958 Df Display 5 54 timing modes, 10 color modes
11:50:27.962 Df Display 5 setEnabled:1
11:50:28.244 Df Display 8 setEnabled:0
(no "Timed out ... PID 96728" line)

=== pmset -g log ===
2026-09-05 13:33:16  Notification  Display is turned off
2026-09-05 13:33:36  Sleep         Entering Sleep state due to 'Idle Sleep':TCPKeepAlive=active Using AC (Charge:80%) 495 secs
2026-09-05 13:41:51  Wake          Wake from Deep Idle [CDNVA] : due to smc.sysState.Wake(0x70070000) wifibt SMC.OutboxNotEmpty bluetooth-pcie/HID Activity Using AC
2026-09-05 13:41:51  Notification  Display is turned on

=== lsappinfo (why macOS never offers force-quit) ===
StatusLabel = kCFNULL

=== display state while ghostty was STILL frozen ===
PHL 345E2:  Resolution: 3440 x 1440   UI Looks like: 3440 x 1440 @ 60.00Hz
            Main Display: Yes   Mirror: Off   Online: Yes

Ghostty Version

Ghostty 1.3.2-main-+c81f0b268

Version
  - version: 1.3.2-main-+c81f0b268
  - channel: tip
Build Config
  - 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 26.6.1 (Build 25G76) — MacBook Pro Mac16,5, Apple M4 Max, 32-core GPU, 36 GB, clamshell + single external display

(Linux only) Display Server

None

(Linux only) Desktop Environment/Window Manager

No response

Minimal Ghostty Configuration

# NOTE: minimality is NOT verified by bisection. The bug reproduced once in >=2
# sleep/wake cycles of a single process, so a few negative trials would prove
# nothing. The lines below are the ones I can argue for from the source, not
# from experiment:
#
#   custom-shader           -> has_custom_shaders = true (generic.zig ~L676)
#                              -> animationWake() != null (~L1034)
#                              -> should_run = true (~L1193)
#                              -> the display link is RUNNING, so stop() has to
#                                 actually join its IO thread instead of
#                                 returning immediately.
#   custom-shader-animation -> default `true`; gates the above on focus.
#
# background-opacity / background-blur are included only because they were active
# when it reproduced; I have no mechanism linking them to the deadlock.
#
# Full `ghostty +show-config --default=false` output is attached as
# config-full.txt (393 lines, mostly the Dracula palette).

custom-shader = ~/.config/ghostty/cursor_blaze.glsl
custom-shader = ~/.config/ghostty/focus_cursor.glsl
custom-shader-animation = true
background-opacity = 0.7
background-opacity-cells = true
background-blur = true

Additional Relevant Configuration

Two custom shaders are attached, since the template asks for shader sources and
because custom-shader is my primary suspect for keeping the display link
running:

• cursor_blaze.glsl (158 lines) — cursor trail; based on
  https://gist.github.com/chardskarth/95874c54e29da6b5a36ab7b50ae2d088 and
  Inigo Quilez's 2D distance functions (https://iquilezles.org/articles/distfunctions2d/).
• focus_cursor.glsl (82 lines) — cursor highlight on window focus,
  © 2025 Martin Emde.

No tmux/zellij/neovim involved — the freeze happens with the window idle.

cursor_blaze.glsl. focus_cursor.glsl

glsl.zip

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.

[mitchellh]

#14171

[adam0white]

Second reporter, same deadlock — twice in five days on 1.3.2-main-+c81f0b268 (build 17709), macOS 26.6.2, Mac16,7 with an external UWQHD display. Same config shape as the OP: two custom-shader entries, custom-shader-animation = true.

Both were captured as .hang reports. Two details I think are worth adding, because they suggest #14171 narrows this rather than closing it.

1. The block can happen in setCurrentCGDisplay, not only the no-redraw stop().

Four seconds after a wake from display sleep:

Thread "renderer"
  ??? (ghostty + 8436464)
    ??? (ghostty + 8068704)
      ??? (ghostty + 8646240)
        ??? (ghostty + 8280636)
          CVCGDisplayLink::setCurrentDisplay(unsigned int) + 256 (CoreVideo)
            CVDisplayLink::stop() + 148 (CoreVideo)
              __psynch_cvwait

That is syncDisplayLink's setCurrentCGDisplay(id) call, reached via setMacOSDisplayID — not drawFrame's no-redraw path. CVDisplayLinkSetCurrentCGDisplay stops the link internally, so it blocks the same way, and #14171 does not move that call.

2. The wedge can stay silent for a long time, then detonate on surface teardown.

The renderer above wedged at 10:50:49. The app stayed completely usable for the next 43 minutes — one tab simply never repainted again. It froze at 11:34:09.9, when I closed that tab, and the main thread was not waiting on draw_mutex:

__NSFireTimer
  -[NSUndoManager removeAllActionsWithTarget:]
    -[_NSUndoStack removeAllObjectsWithTarget:]
      -[_NSUndoBlockInvocation dealloc] -> _Block_release
        ...swift_release_dealloc cascade...
          -[NSView dealloc] -> -[NSResponder dealloc]
            ...Surface deinit...
              __ulock_wait
*blocked by turnstile with priority 47 waiting for ghostty thread 0x195470f*

Teardown joins the wedged renderer. Two consequences:

• The 43-minute gap argues against draw_mutex being the mechanism in this instance. Had the renderer held it, the main thread would have blocked on that surface's next layer display, not 43 minutes later.
• undo-timeout (default 5s) retains the closed surface, so the freeze lands 5.0s after the close rather than at it. That badly disguises the trigger — I first blamed the long-running TUI in that tab.

Practical note for anyone hitting this: don't Cmd+Q a frozen Ghostty. Quitting runs the same teardown and joins the same thread, so the quit hangs too. kill -9 recovers; window-save-state = always restores the tabs.

3. An earlier occurrence (22 min) had no Ghostty frame in the blocking path at all — the main thread was inside CoreVideo's own reconfiguration callback:

displayConfigFinalizedProc
  _cvDisplayLinkDisplayReconfigurationCallback
    CVCGDisplayLink::displayReconfiguration(unsigned int, unsigned int)
      CVDisplayLink::stop() + 148
        __psynch_cvwait

with a SwiftUI dispatch thread piled up behind it on CVCGDisplayLink::finalize()'s mutex.

Happy to share fuller stacks from either report if they'd help. I'm now updating to a version with this fix without disabling shaders, and will report back in case of re-occurrence.

[mitchellh]

This was fixed yesterday afternoon. Have you updated to that version?

[adam0white]

I saw that. This happened before updating to that version, but I still wanted to post since it may not fully fix the issue based on the investigation. I'll follow up if the issue happens again on the new version, feel free to check my report above.

[erickochen]

Hi! So it seems like this or something related is still an issue on a build that has the fix. I'm on 1.3.2-main-+448062571 (build 17742) which is nine commits past 82232ec by the looks of it.

My MacBook Pro was awake the whole time and I had just changed the resolution on my external display. A display reconfiguration on its own seems to be enough to trigger it?

I had Claude Code read the spindump and it pointed me at this:

Thread "renderer"
  ??? (ghostty + 8422316)
    ??? (ghostty + 8054316)
      ??? (ghostty + 8628928)
        ??? (ghostty + 8443472)
          ??? (ghostty + 8250364)
            ??? (ghostty + 8254920)
              CVDisplayLink::stop() + 148 (CoreVideo + 10800)
                __psynch_cvwait

The MacBook Pro is a Mac16,7 on macOS 26A5425a. The external display is a BenQ at 70Hz as the main next to the internal 120Hz panel. No custom shaders.

Let me know if/how I can help. I will try to reproduce the various sleep and screen adjustment scenarios to gather some additional logs.

[XhstormR]

Ghostty still occasionally freezes when waking up from screen sleep.
version https://github.com/ghostty-org/ghostty/commits/4a70ee471

[XhstormR]

stuck again. 123.log

└──❯ ghostty +version
Ghostty 1.3.2-main-+7aab0a039

Version
  - version: 1.3.2-main-+7aab0a039
  - channel: tip
Build Config
  - Zig version   : 0.16.0
  - build mode    : .ReleaseFast
  - app runtime   : .none
  - font engine   : .coretext
  - renderer      : renderer.generic.Renderer(renderer.Metal)
  - libxev        : kqueue

[ahmedelgabri]

Same deadlock on 1.3.2-main-+7aab0a039 (17767), a build that includes #14171 (72cf508) and #14035 (d9840f3), in the variant @adam0white listed as point 3: CoreVideo's own reconfiguration callback calling stop() on the main thread. That report was from a pre-#14171 build. This one shows the variant survives it.

What is new relative to the thread so far:

1. Post-#14171 the main-thread variant is the whole story, and the renderer is idle. sample, 2550/2550 samples, unchanged over an hour:

main -> ... -> __CFRunLoopDoBlocks
  CGSDatagramReadStream::dispatchMainQueueDatagrams -> CGSPostLocalNotification
    displayConfigFinalizedProc  (SkyLight)
      _cvDisplayLinkDisplayReconfigurationCallback  (CoreVideo)
        CVCGDisplayLink::displayReconfiguration -> CVDisplayLink::stop() + 148 -> __psynch_cvwait

Renderer thread: 2482/2550 in kevent64, the rest in normal frame processing. It is not in stop() or setCurrentDisplay, and it holds nothing the main thread is waiting for. No Ghostty lock is involved. The join inside CVDisplayLink::stop() is what never completes, and CoreVideo issues that join itself on every reconfiguration.

2. Three IO threads for one link within a single reconfiguration. heap again shows one CVDisplayLink object and sample again shows two live IO threads (0x130db39, 0x130db3c), both looping normally in waitUntil. The Bad CurrentVBLDelta for display 3 is zero line at 15:43:27.761 was logged by IO thread 0x130d9f0, which no longer exists. So during that one reconfiguration the link lost the IO thread it had and gained two more, and the main thread's stop() is waiting on an acknowledgement none of the survivors will send.

3. The trigger was a display removal while awake, six seconds before sleep. Lid closed and external display (3008 x 1692) disconnected at 15:43:27.03. The main thread answered reconfiguration round 1 at .450, logged its last line at .776 while handling round 2 (the same transient (0 x 0) [1920 x 1080] display as in the OP appeared at .763), and WindowServer's kCGSDisplayDidReconfigure2 timeout for the process fired at 28.018. pmset shows Clamshell Sleep at 15:43:33. The wake at 15:44:30 produced no main-thread log lines at all. Together with @erickochen's resolution change, wake is not required. Neither is custom-shader (none configured). window-vsync is at its default.

4. Environment. macOS 26.6.2 (25G83), Mac14,10 (M2 Pro). macos-non-native-fullscreen = true, window-decoration = false, window-colorspace = display-p3, no opacity or blur. One window, one tab. About 3 days of uptime, one occurrence across several undock cycles.

One remark on direction. The blocking stop() in this variant is CoreVideo's, not Ghostty's, so relocating Ghostty's own stop() calls cannot close it. The link has to not be running, or being re-bound, while a reconfiguration is in flight. #14035 makes renderer-side start/stop very frequent, so if the two-IO-thread state comes from renderer start/stop racing CoreVideo's internal stop/start during reconfiguration, it widened that window. Untested.

ghostty-sample.txt

[svirschevskiy]

Still reproducible after wake while an external display was being reconfigured, on Ghostty 1.3.2-main+982fe90d9 (build 17925), and macOS 27.0 (26A428). Ghostty was using the default configuration with no custom shaders.

The renderer has the same CVDisplayLink::stop() deadlock already documented here:

Thread name "renderer"
  ??? (ghostty)
    ??? (ghostty)
      ??? (ghostty)
        ??? (ghostty)
          ??? (ghostty)
            CVDisplayLink::stop()
              __psynch_cvwait

The additional detail in this occurrence is that focusing Ghostty after the renderer wedged turned it into a whole-application hang through the surface-focus path:

DispatchQueue "com.apple.main-thread"
  BaseTerminalController.windowDidBecomeKey(_:)
    BaseTerminalController.syncFocusToSurfaceTree()
      Ghostty.SurfaceView.focusDidChange(_:)
        ghostty_surface_set_focus
          ??? (ghostty)
            __ulock_wait2

All samples in the macOS hang report showed these same stacks.

[cattyhouse]

@XhstormR @mitchellh can someone reopen this discussion, it is not fully resolved.

it is easy to reproduce on macOS 27 and tip 1a9edb0: turn off the external monitor , then turn on, try a few times, 100% freeze. here is the report with the help of pi agent + LLM : see next message for details.

[XhstormR]

i don't have permission to reopen

[cattyhouse]

@mitchellh

attached 2 files, with the help of pi agent + LLM. i try to make it as simple as possible, easy to read.
patch.md
reproduce.md

[cattyhouse]

Tested (monitor turn off / on 10 times) with below patch ( all done by LLM), problem fixed:

patch : main...cattyhouse:ghostty:patch/bound-surface-join

app : https://github.com/cattyhouse/ghostty/releases

due to limited knowledge, i didn't review any of the code, i only tested the final app, so i think i am not qualified to propose a PR.

fyi @mitchellh @XhstormR

[Liooo]

Ghostty became unresponsive as a whole. Activity Monitor showed two Ghostty processes; one was marked "Not Responding" with 27 threads, while the other had 6 threads. The attached captures are for PID 687, the process with 27 threads. I have observed this repeatedly when using Codex together with herdr. So far, this is the context in which I encounter the freeze, but I do not know the exact triggering action or have reliable step-by-step reproduction instructions. I have not established whether either tool causes the hang.

Environment: Ghostty 1.3.2-main+f523504ea (build 18047, tip, ARM64), macOS 27.0 (26A428), Mac15,6, 36 GB RAM.

I captured a sample and spindump during the freeze on October 7, 2026, around 23:19 PDT. The spindump reports that Ghostty had been unresponsive for 830 seconds before its 10-second sampling window.

Both captures show these stacks throughout their sampled main/renderer threads:

Main thread:
  BaseTerminalController.windowDidResignKey(_:)
    BaseTerminalController.syncFocusToSurfaceTree()
      Ghostty.SurfaceView.focusDidChange(_:)
        ghostty_surface_set_focus
          [unsymbolicated Ghostty frames]
            __ulock_wait2

Renderer thread 0x1dbc:
  [unsymbolicated Ghostty frames]
    CVDisplayLink::stop()
      __psynch_cvwait

The spindump contains 282 samples for each of these threads. It reports the renderer last ran 1340.670 seconds earlier and the main thread 829.573 seconds earlier. The earlier sample has the same stacks in all 1587 samples. The captures identify the blocked paths but do not establish the lock owner or a complete deadlock cycle.

This resembles the follow-up reports in #14150. This capture is on build 18047 and the main-thread path is windowDidResignKey, rather than windowDidBecomeKey. I have not established that display reconfiguration triggered this occurrence.

The current configuration has no custom shaders. The attached configuration was collected after the hang and has not been minimized or confirmed to match the hung process exactly.

Attachments: Ghostty sample, Ghostty-only spindump excerpt, version output, current configuration, and Activity Monitor screenshot. Other process sections and personal identifiers were removed from the shared diagnostic copies. Original captures are preserved locally.

AI disclosure: OpenAI Codex assisted with capture analysis, privacy filtering, and drafting this report.

ghostty-diagnostics.zip

[erickochen]

Still happens on 1.3.2-main+ca2356fa0 (build 18085, main as of Oct 6), #14171 included. macOS 27.2 (26B5101f), Mac16,7 (M4 Pro), same BenQ MA270S at 3008 x 1692 @ 70 Hz as main display, internal panel on, no custom shaders, window-colorspace = display-p3, native tabs.

I asked Claude to summarize:

• Was on a different monitor earlier that day, slept at 17:07 and woke at 17:19:14 to only the internal display, no trouble.
• The BenQ arrived about 6 seconds later (17:19:19.907) and the main thread cleared that round from 17:19:20.54 to 17:19:20.85, no WindowServer timeout.
• One renderer thread last ran at about 17:19:20.5 and sits in CVDisplayLink::stop() in 74 of 74 samples, while the other two nap in kevent64.
• New this time: no transient (0 x 0) [1920 x 1080] display and no Bad CurrentVBLDelta.
• Same as before: two CVDisplayLink IO threads idle in waitUntil, holding the process's highest thread IDs.
• Ghostty stayed usable for about 55 seconds, until a native tab click at 17:20:16 blocked the main thread in ghostty_surface_set_focus and earned a .hang report. That's @Liooo's windowDidResignKey path and @adam0white's point 2.

Main thread:

-[NSTabBar _clickRecognized:]
  ...
  -[NSWindow _sendResignKeyWindow]
    BaseTerminalController.windowDidResignKey(_:)
      BaseTerminalController.syncFocusToSurfaceTree()
        Ghostty.SurfaceView.focusDidChange(_:)
          ghostty_surface_set_focus + 208
            ??? (ghostty + 7977304)
              __ulock_wait2

Renderer:

??? (ghostty + 8454832)
  ??? (ghostty + 8085092)
    ??? (ghostty + 8643416)
      ??? (ghostty + 8476004)
        ??? (ghostty + 8284168)
          ??? (ghostty + 8288740)
            CVDisplayLink::stop() + 148 (CoreVideo)
              __psynch_cvwait

In Surface.focusCallback two calls can block: renderer_state.mutex.lockUncancelable and renderer_thread.mailbox.push(..., .{ .forever = {} }) into a 64-slot mailbox that a wedged renderer never drains. Symbolizing ghostty + 7977304 against ca2356f would say which (load address 0x10298c000, UUID 80EE779A-0FFF-3D4D-B33E-078B1B30D7D6).

Happy to share the Ghostty section of the .hang report.

[mitchellh]

Okay, I've found the follow up issue, will be in 1.4: #14691