Skip to content

fix(macos): close both macOS 26 main-thread deadlock doors and restore the reveal reflow - #10473

Merged
nwparker merged 4 commits into
mainfrom
nwparker/uber-crash
Jul 25, 2026
Merged

nwparker merged 4 commits into
mainfrom
nwparker/uber-crash

Conversation

@nwparker

@nwparker nwparker commented Jul 25, 2026 •

Copy link
Copy Markdown
Contributor

Why

A user's app froze for 109 minutes on macOS 26 Tahoe (Darwin 25.5.0, v1.4.152) and had to be force-quit. macOS 26 backs AppKit objects with scenes, and a scene update sent re-entrantly from inside AppKit's own dispatch self-deadlocks the main thread in FrontBoardServices (FBSScene _sendUpdate: -> BSServiceDispatchQueue performAsyncAndWait: -> _dispatch_event_loop_wait_for_ownership). Because the freeze is on the main process, every telemetry path is silenced with it — the app just stops.

#10253 fixed the window half by skipping the repaint size nudge on macOS 26. This PR closes the remaining hole and repairs the regression that fix introduced.

What this changes

1. The reveal reflow was lost on macOS 26 (regression from #10253).
webContents.invalidate() repaints but does not reflow, so the h-dvh app-shell root kept a stale dynamic-viewport height and the StatusBar stayed clipped below the viewport — the exact "no bottom bar" bug #10056 had just fixed. On Tahoe forceRepaint returned right after invalidate(), so every reveal, restore and wake got the known-insufficient behavior. Neither commit has shipped in a stable release, so this was caught before users saw it.

The fix drives the reflow through Chrome device emulation: a +1px emulated viewport, reverted a frame later. The renderer recomputes layout for real, and no NSWindow mutation ever happens — so the deadlock is still never reachable.

2. The tray was a second, un-fixed door into the same deadlock.
window.on('show'/'restore') calls setTrayAttention(false) straight from the AppKit handler, and tray.setImage/setToolTip drive an NSStatusItem scene update — the same re-entrant pattern, matching the stackshot in openai/codex#23695. The native mutation now runs on a fresh event-loop turn. The attention flag itself still flips synchronously, or rapid show/hide would mis-dedupe against a value that had not landed yet.

3. Maximized and fullscreen windows never reflowed.
That bail-out predates the Tahoe path and existed only to stop setSize from resizing a window out of those states. Emulation leaves the frame alone, so the guard was suppressing the reflow for nothing.

4. A failed restore could strand the renderer.
If disableDeviceEmulation threw while the webContents was still alive, the first version cleared its latch anyway — pinning the renderer at the overshot viewport for the window's lifetime and letting the next reveal stack another cycle on top. The restore now retries on a bounded schedule and holds the latch while a retry is pending.

5. Two smaller defects found along the way.

  • The pre-Tahoe size jiggle could leak its WeakSet latch if setSize threw, permanently suppressing every later repaint for that window. Now cleared in a finally.
  • The Tahoe test only drove show; powerMonitor 'resume' — the other dispatch context implicated in the incident — was uncovered. Now tested.

Verification

Behavior was measured against real Electron 43.1.0 on macOS 26.3.1 (Darwin 25.3.0), not just mocks:

  • the renderer receives the resize and relayouts; layout ends correct in every configuration tried
  • getSize() is unchanged throughout — the native frame is never touched
  • viewport and devicePixelRatio restore exactly, across zoom levels 0/+1/-1
  • maximized and fullscreen windows reflow and stay maximized/fullscreen
  • overlapping reveals collapse to one cycle; the latch re-arms after, and is held across retries
  • window destroyed mid-cycle, and enable/disable throwing, leave no stuck emulation
  • 40 aggressive show/hide/minimize/restore cycles against the combined window+tray logic, with the main thread continuously responsive
  • no SIGWINCH: even with a pane tuned to sit exactly on an xterm row boundary — the worst case — the 32 ms revert lands before the fit stabilizes, so no pane reports new geometry. The old jiggle nudged width, which was strictly riskier.

Every new test was mutation-checked: reverting the corresponding fix makes it fail, so none pass vacuously.

pnpm typecheck:node clean, oxlint clean, full main-process suite green (15,000 tests).

Limits worth stating

  • The original deadlock is not deterministically reproducible. It is a race; repeated attempts on this machine (both sync frame and sync tray mutation from AppKit callouts) completed normally. The fix rests on the documented mechanism and the stackshots, plus the fact that the crashing v1.4.152 build mutated the frame synchronously inside the callout.
  • The dvh staleness itself did not reproduce locally either, so item 1 is verified at the mechanism level — a real reflow reaches the renderer without touching the frame — rather than by observing the clipped status bar recover.
  • With the renderer blocked past the 32 ms window, Chromium coalesces the intermediate viewport, so the renderer never observes the +1px step. Layout still ends correct, and the 250 ms second repaint plus the next reveal both retry.

Notes

  • Behavior on macOS < 26, Windows and Linux is unchanged apart from the added try/finally.
  • One consequence at parity with what non-Tahoe macOS already did via the jiggle: an open text-selection popup or link bubble dismisses on reveal.

nwparker added 3 commits July 24, 2026 19:03
…frame

#10253 stopped the main-thread deadlock by skipping the repaint size nudge on
macOS 26, but invalidate() repaints without reflowing, so the h-dvh root kept a
stale viewport height and the status bar stayed clipped off-screen (STA-2383) on
every Tahoe reveal, restore and wake.

Drive the reflow through device emulation instead: a +1px emulated viewport,
reverted a frame later, makes the renderer recompute layout without any NSWindow
mutation, so the FrontBoardServices re-entrancy that wedged the main thread for
109 minutes is still never triggered.

Verified against real Electron 43.1.0 on macOS 26.3.1 (Darwin 25.3.0): the
renderer sees the resize and relayouts, the native frame is untouched, the
viewport and devicePixelRatio restore exactly across zoom levels, overlapping
calls collapse to one cycle, and a 1px delta never crosses a terminal cell
boundary so no pane reports new geometry (no SIGWINCH to running shells).

Also close two gaps in the surrounding code:
- the pre-Tahoe size jiggle now clears its WeakSet latch in a finally block, so a
  throwing setSize can no longer suppress every later repaint for that window
- cover powerMonitor 'resume' under the Tahoe guard, the other AppKit dispatch
  context implicated in the freeze
The main-window repaint was only one of the two doors into the macOS 26
FrontBoardServices deadlock. Showing or restoring the window calls
setTrayAttention(false) straight from the window event handler, and
tray.setImage/setToolTip drive an NSStatusItem scene update — the same
re-entrant scene mutation from inside AppKit's own dispatch, matching the
stackshot in openai/codex#23695.

Defer the native mutation to a fresh event-loop turn so the callout frame is
vacated first. The attention flag itself still flips synchronously: rapid
show/hide would otherwise mis-dedupe against a value that had not landed yet.

Bursts collapse to a single repaint, and because the deferred pass reads current
module state rather than a captured value, a coalesced schedule can never apply
a stale icon. applyTrayImage already no-ops on a destroyed tray, so a repaint
still queued when the tray goes away is harmless.
The maximized/fullscreen bail-out predates the Tahoe path and exists only to
keep the size nudge from resizing a window out of those states. Emulation never
touches the frame, so that guard was suppressing the reflow for no reason — and
a maximized window strands its dvh layout exactly like a normal one.

Run the Tahoe branch before the guard. Verified on macOS 26.3.1 that the
emulated viewport reflows a maximized and a fullscreen window while leaving both
states intact.
@coderabbitai

coderabbitai Bot commented Jul 25, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Adds deferred AppKit scene mutations and coalesced tray image repainting for attention and appearance changes. Introduces renderer viewport reflow through temporary device emulation on macOS Tahoe+, with deduplication, delayed cleanup, destruction checks, and failure recovery. Updates main-window repaint handling to use the reflow path and hardens the existing size-nudge cleanup. Expands tests for timer behavior, tray lifecycle handling, window states, and wake-from-sleep repainting.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check ⚠️ Warning The PR description covers the change well, but it omits required template sections like Summary, Screenshots, Testing, AI Review Report, and Security Audit. Add the missing template sections, including screenshots or no visual change, testing checklist, AI review cross-platform notes, and a security audit summary.
✅ Passed checks (3 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title is concise and accurately reflects the macOS 26 deadlock/reflow changes.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (2)
src/main/appkit-scene-mutation.ts (1)

4-6: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Consider containing errors thrown by mutate.

setTimeout(mutate, 0) runs on a fresh turn, so if mutate throws it becomes an uncaught exception at the process level rather than something callers can catch — this can crash the whole app unless a global uncaughtException handler exists. Since this helper is shared infra for AppKit scene mutations (tray now, viewport reflow per the stack outline), guarding it here protects every future caller instead of relying on each call site remembering to wrap risky work.

🛡️ Proposed fix
 export function deferAppKitSceneMutation(mutate: () => void): void {
-  setTimeout(mutate, 0)
+  setTimeout(() => {
+    try {
+      mutate()
+    } catch (error) {
+      console.warn('[appkit-scene-mutation] deferred mutation failed', error)
+    }
+  }, 0)
 }
src/main/tray/system-tray.test.ts (1)

514-527: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Test doesn't verify what its name claims.

Both setTrayAttention(true) calls use the same value, so the second call is short-circuited by attentionActive === active in setTrayAttention before scheduleTrayImage() ever runs — this only re-tests the same-state guard, not whether trayImageRepaintPending correctly resets and can be re-armed after a flush.

✅ Proposed fix to actually exercise the post-flush latch
   setTrayAttention(true)
   flushTraySceneMutation()
-  setTrayAttention(true)
+  setTrayAttention(false)
+  setTrayAttention(true)
   flushTraySceneMutation()

-  expect(created.setImage).toHaveBeenCalledTimes(1)
+  expect(created.setImage).toHaveBeenCalledTimes(2)

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ce7e6024-58d9-4d4c-a06a-9690dc41e03e

📥 Commits

Reviewing files that changed from the base of the PR and between b4718dd and 7e995e5.

📒 Files selected for processing (8)
  • src/main/appkit-scene-mutation.test.ts
  • src/main/appkit-scene-mutation.ts
  • src/main/tray/system-tray.test.ts
  • src/main/tray/system-tray.ts
  • src/main/window/createMainWindow.test.ts
  • src/main/window/createMainWindow.ts
  • src/main/window/renderer-viewport-reflow.test.ts
  • src/main/window/renderer-viewport-reflow.ts

…erer

If disableDeviceEmulation threw while the webContents was still alive, the
previous code swallowed the error and cleared the latch anyway, leaving the
renderer pinned at the emulated 1px-taller viewport for the rest of the window's
life — and letting the next reveal stack a fresh cycle on top of it.

Retry the restore on a bounded schedule and hold the latch while a retry is
pending. A destroyed webContents still short-circuits, since the emulated
viewport dies with it, and the attempt budget keeps a permanently failing
restore from pinning the latch forever.
@nwparker

Copy link
Copy Markdown
Contributor Author

Post-merge attribution: this PR is very likely the fix for the reported "freeze after closing my laptop and coming back."

Investigating that report (v1.4.152, macOS 26 Tahoe / Darwin 25.5.0, app unresponsive ~109 min, force-quit), the evidence points here:

  • v1.4.152 does not contain fix(window): defer the repaint size nudge and skip it on macOS 26 #10253. Verified: git merge-base --is-ancestor 4569a4fe71 v1.4.152 → false. So that build shipped forceRepaint() calling window.setSize(width + 1, height) synchronously from window.on('restore') / on('show') (src/main/window/createMainWindow.ts:66 at that tag), with no macOS 26 guard.
  • Lid-open wake fires restore/show, so the nudge ran re-entrantly inside AppKit's window-state dispatch — exactly the pattern fix(window): defer the repaint size nudge and skip it on macOS 26 #10253's kernel-confirmed spindump identified as self-deadlocking the main thread in FrontBoardServices on scene-backed Tahoe windows.
  • It explains the missing crash report. A main thread deadlocked in AppKit cannot run the JS that would record one, which is why the only trace was a heartbeat gap.

An earlier stage of this investigation reported the 109-minute gap as "very likely OS sleep, not a hang." That was a mistake: the gap is sleep-shaped, but sleep is the precondition, not the alibi — the freeze is at the tail of the gap, on wake. Corrected in #10530.

Caveat, stated plainly: a synthetic repro driving show()/minimize()/restore() on macOS 26.3.1 did not reproduce the hang (6/6 cycles clean; harness validated to fire the handlers and reach setSize). Programmatic window-state changes don't reproduce a genuine FrontBoardServices lid-open wake, so this is weak counter-evidence against a kernel-confirmed spindump — but the deadlock remains inferred, not reproduced.

Current main closes both doors: on Tahoe forceRepaint returns before any setSize (emulation reflow instead), and on older macOS the nudge is deferred to a fresh event-loop turn. isMacosTahoeOrNewer correctly maps the user's Darwin 25.5.0 to the safe path.

enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
…e the reveal reflow (stablyai#10473)

* fix(window): restore the macOS 26 reflow without touching the native frame

stablyai#10253 stopped the main-thread deadlock by skipping the repaint size nudge on
macOS 26, but invalidate() repaints without reflowing, so the h-dvh root kept a
stale viewport height and the status bar stayed clipped off-screen (STA-2383) on
every Tahoe reveal, restore and wake.

Drive the reflow through device emulation instead: a +1px emulated viewport,
reverted a frame later, makes the renderer recompute layout without any NSWindow
mutation, so the FrontBoardServices re-entrancy that wedged the main thread for
109 minutes is still never triggered.

Verified against real Electron 43.1.0 on macOS 26.3.1 (Darwin 25.3.0): the
renderer sees the resize and relayouts, the native frame is untouched, the
viewport and devicePixelRatio restore exactly across zoom levels, overlapping
calls collapse to one cycle, and a 1px delta never crosses a terminal cell
boundary so no pane reports new geometry (no SIGWINCH to running shells).

Also close two gaps in the surrounding code:
- the pre-Tahoe size jiggle now clears its WeakSet latch in a finally block, so a
  throwing setSize can no longer suppress every later repaint for that window
- cover powerMonitor 'resume' under the Tahoe guard, the other AppKit dispatch
  context implicated in the freeze

* fix(tray): keep NSStatusItem scene updates off the AppKit callout stack

The main-window repaint was only one of the two doors into the macOS 26
FrontBoardServices deadlock. Showing or restoring the window calls
setTrayAttention(false) straight from the window event handler, and
tray.setImage/setToolTip drive an NSStatusItem scene update — the same
re-entrant scene mutation from inside AppKit's own dispatch, matching the
stackshot in openai/codex#23695.

Defer the native mutation to a fresh event-loop turn so the callout frame is
vacated first. The attention flag itself still flips synchronously: rapid
show/hide would otherwise mis-dedupe against a value that had not landed yet.

Bursts collapse to a single repaint, and because the deferred pass reads current
module state rather than a captured value, a coalesced schedule can never apply
a stale icon. applyTrayImage already no-ops on a destroyed tray, so a repaint
still queued when the tray goes away is harmless.

* fix(window): reflow maximized and fullscreen windows on macOS 26 too

The maximized/fullscreen bail-out predates the Tahoe path and exists only to
keep the size nudge from resizing a window out of those states. Emulation never
touches the frame, so that guard was suppressing the reflow for no reason — and
a maximized window strands its dvh layout exactly like a normal one.

Run the Tahoe branch before the guard. Verified on macOS 26.3.1 that the
emulated viewport reflows a maximized and a fullscreen window while leaving both
states intact.

* fix(window): retry the viewport restore instead of stranding the renderer

If disableDeviceEmulation threw while the webContents was still alive, the
previous code swallowed the error and cleared the latch anyway, leaving the
renderer pinned at the emulated 1px-taller viewport for the rest of the window's
life — and letting the next reveal stack a fresh cycle on top of it.

Retry the restore on a bounded schedule and hold the latch while a retry is
pending. A destroyed webContents still short-circuits, since the emulated
viewport dies with it, and the attempt budget keeps a permanently failing
restore from pinning the latch forever.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant