Present terminal renderers in on-screen windows that never report an occlusion .visible bit (fixes the display-liveness CI regression from #10815)

[austinywang]

Regression. Since #10815 (581d900) the tests-build-and-lag step Run display UI regressions fails deterministically on main: DisplayResolutionRegressionUITests.testRapidDisplayResolutionChangesKeepTerminalResponsive — XCTAssertGreaterThanOrEqual failed: ("0") is less than ("6") on both attempts (runs 33028942968 rerun, 33034886551 on a pre-#10887 baseline that includes #10815; the step last passed on 2026-08-19, run 32212616081, before #10815). Harness diagnostics show renderWindowVisible=0 / renderAppIsActive=0 throughout.

Root cause. #10815 presents the renderer only while NSWindow.occlusionState.contains(.visible). The harness runs the app on a CGVirtualDisplay (scripts/create-virtual-display.m); AppKit never raises .visible there for a window that is ordered in and drawing, so the renderer stays released and presents never advance.

Rule (TerminalRendererWindowVisibility, one helper used by the occlusion observer, the initial attach, key/main transitions and screen changes): visible if the occlusion bit is set or the window is key; otherwise, until the window has reported .visible at least once, trust its on-screen state (isVisible && !isMiniaturized && isOnActiveSpace); once the bit has been seen, honor the occlusion verdict — so miniaturized, covered and inactive-Space windows still release GPU exactly as #10815 intended.

Tests: TerminalRendererWindowVisibilityTests (4 cases). No change to typing hot paths.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Fixes the display-liveness CI regression from #10815: terminal renderers now present in on-screen windows that never report an occlusion .visible bit, and the IRX keepalive test waits for the first pong instead of sleeping a fixed span. Carries the warning-budget fixes from #10905 so the warning gate lets the display step run.

• Introduces TerminalRendererWindowVisibility: trusts a window's ordinary on-screen state (visible, not miniaturized, on the active Space) until .visible has been observed at least once, then honors the occlusion verdict; key windows always present.
• Re-evaluates visibility on key/main transitions and screen changes; miniaturized, covered, and inactive-Space windows still release the renderer as before.
• The keepalive test now polls for a pong with a deadline, so the assertion tracks the real liveness event.
• Clears the Swift warning buckets on this base: nonisolated IRX defaults keys, hoisted weak captures before MainActor.run hops, and awaited SurfaceCatalog.shared access.

^{Written for commit 7e47d56. Summary will update on new commits.}

Summary by CodeRabbit

• Bug Fixes
  • Improved terminal renderer visibility handling for virtual and headless displays.
  • Windows can now remain available when standard visibility is not reported.
  • Renderer visibility updates reliably when windows change focus, spaces, minimization, or screens.
  • Prevented rendering in minimized, off-screen, or inactive-space windows when visibility cannot be confirmed.
  • Improved connection keepalive reliability and asynchronous surface operations.
  • Improved mobile runtime compatibility during connection lifecycle events.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a25a76c3-e711-4747-801b-59b069ed2392

📥 Commits

Reviewing files that changed from the base of the PR and between f74514c and 7e47d56.

📒 Files selected for processing (2)

• Sources/Mobile/MobileHostIrxRuntime.swift
• Sources/Surfaces/SurfaceSocketCommands.swift

Included review availability: Your plan provides up to 10 included reviews per hour; 4 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds a public renderer-window visibility predicate, integrates it with GhosttyNSView window events, adds predicate tests, updates QUIC keepalive timing, and clarifies asynchronous access in mobile and surface flows.

Changes

Renderer window visibility

Layer / File(s)	Summary
Visibility predicate and coverage Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalRendererWindowVisibility.swift, Packages/macOS/CmuxTerminal/Tests/CmuxTerminalTests/TerminalRendererWindowVisibilityTests.swift	Adds TerminalRendererWindowVisibility.isVisible and tests occlusion history, key windows, on-screen state, miniaturization, and active-space state.
Window lifecycle integration Sources/GhosttyTerminalView.swift	Tracks windows with visible occlusion, observes key-window changes, applies the predicate during window updates and screen changes, and removes observers during teardown.

QUIC keepalive test timing

Layer / File(s)	Summary
Keepalive response polling Packages/Shared/CmuxIrxTransport/Tests/CmuxIrxTransportTests/IrxLiveQUICTests.swift	Replaces the fixed six-second delay with polling until the first pong arrives or an eight-second deadline expires.

Mobile and surface asynchronous access

Layer / File(s)	Summary
Mobile runtime isolation Sources/Mobile/MobileHostIrxRuntime.swift	Marks defaults keys as nonisolated and captures the runtime before main-actor generation checks.
Surface catalog retrieval Sources/Surfaces/SurfaceSocketCommands.swift	Awaits shared catalog retrieval before port opening and terminal creation.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to 7e47d

The PR updates terminal rendering for headless display windows and includes focused tests; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant AppKitWindow
  participant GhosttyNSView
  participant TerminalRendererWindowVisibility
  participant Renderer
  AppKitWindow->>GhosttyNSView: Send occlusion or key-window notification
  GhosttyNSView->>TerminalRendererWindowVisibility: Evaluate window state
  TerminalRendererWindowVisibility-->>GhosttyNSView: Return visibility
  GhosttyNSView->>Renderer: Update renderer window visibility

Loading

Suggested reviewers: azooz2003-bit

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (2 errors, 1 warning)

Check name	Status	Explanation	Resolution
Cmux Architecture Rethink	❌ Error	The diff adds a process-wide mutable side channel: GhosttyNSView.windowsThatReportedVisible stores window history in a static NSHashTable, while TerminalSurface.rendererWindowVisible still owns …	Remove the static window table from GhosttyNSView. Make the existing window/presentation owner, or a per-window @MainActor coordinator created by it, the single owner of observer tokens and hasReportedVisible. Expose an immutable visi…
Cmux No Ambient Global State	❌ Error	The PR adds a caseless public enum used only as a static-helper namespace. In Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalRendererWindowVisibility.swift:13-26, `TerminalRenderer…	Move the visibility behavior onto a constructable, injectable owning type. For example, make TerminalRendererWindowVisibility an instance-based struct with an instance isVisible method, construct or inject one at the GhosttyNSView sea…
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (22 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: presenting terminal renderers in windows that do not report an occlusion .visible state. It also identifies the related CI regression.
Description check	✅ Passed	The description explains what changed, why the change is required, the root cause, the visibility rule, affected paths, and test coverage. It does not include the template's Demo Video, Review Trigger…
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.
Cmux Swift Actor Isolation	✅ Passed	PASS. The production changes do not introduce a stated actor-isolation failure. The new pure visibility helper is in the Swift 6 CmuxTerminal package, whose manifest does not set a MainActor default…
Cmux Swift Blocking Runtime	✅ Passed	PASS: The only newly added timing primitive is Task.sleep(for: .milliseconds(100)) in Packages/Shared/CmuxIrxTransport/Tests/CmuxIrxTransportTests/IrxLiveQUICTests.swift, which is test-only and al…
Cmux Browser Automation Off-Main	✅ Passed	PASS — The PR diff from origin/main changes six files, none of which is Sources/TerminalController.swift or ControlCommandExecutionPolicy.swift. The changed SurfaceSocketCommands.swift edits o…
Cmux Expensive Synchronous Load	✅ Passed	PASS. The pull-request diff adds no RestorableAgentSessionIndex.load(), agent store/history load, transcript or trajectory read, broad scan, per-record syscall loop, or large JSON/JSONL parse. `Ghos…
Cmux Cache Substitution Correctness	✅ Passed	PASS. The PR does not replace a fresh authoritative read with a cache in a persistence, history, undo, or snapshot path. The visibility state is a weak, in-memory UI presentation hint, which the polic…
Cmux No Hacky Sleeps	✅ Passed	PASS. The PR changes six Swift files only; it changes no TypeScript, JavaScript, shell, or non-Swift build/runtime script. The only added sleep/polling is in the Swift test IrxLiveQUICTests.swift, w…
Cmux Algorithmic Complexity	✅ Passed	PASS. The production diff adds only constant-time visibility branches, membership checks on an NSHashTable, and a loop over an explicit three-notification list. The new windowKeyObservers cleanup …
Cmux Swift Concurrency	✅ Passed	PASS — The PR adds no new background Dispatch queues, DispatchGroup, Combine state, completion-handler API, or fire-and-forget Task { ... } pattern. The new NotificationCenter observers use the al…
Cmux Swift @Concurrent	✅ Passed	PASS. The diff adds only a synchronous pure visibility helper, test polling with Task.sleep, synchronous nonisolated constants, and explicit await access to the @MainActor SurfaceCatalog. Th…
Cmux Swift Package Boundaries	✅ Passed	PASS. The new visibility rule is in the SwiftPM CmuxTerminal target at Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalRendererWindowVisibility.swift, with unit tests in that pack…
Cmux Swiftpm Lockfiles	✅ Passed	PASS. The PR diff from 39a1488 to 7e47d56 changes only Swift source and test files. It does not change Package.swift, Package.resolved, .gitignore, workflows, or Xcode project/workspace files. Pac…
Cmux Swift Logging	✅ Passed	PASS — The PR diff from 39a1488 to HEAD adds no print, debugPrint, dump, NSLog, ad hoc file/stdout logging, Logger declaration, or sensitive-data log. Existing logging-related lines in `Sour…
Cmux User-Facing Error Privacy	✅ Passed	PASS — The PR adds no user-facing error, alert, command-output, API-error, or recovery text. The new TerminalRendererWindowVisibility comments and tests are developer-facing, which the rule allows. …
Cmux Full Internationalization	✅ Passed	PASS: The PR introduces no new or changed user-facing copy. The production diff adds only renderer-visibility logic, observer wiring, actor-isolation fixes, and awaited catalog access. Added prose is …
Cmux Swiftui State Layout	✅ Passed	PASS. The diff introduces no SwiftUI state or layout pattern covered by the rule. The visibility changes are inside GhosttyNSView: NSView and use AppKit window notifications and NSHashTable; the S…
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	PASS: The PR does not add or materially change a standalone cmux-owned window. Its only production NSWindow change is visibility observation in GhosttyNSView, which hosts terminal panes. The new `Te…
Cmux Source Artifacts	✅ Passed	PASS. The base-to-HEAD diff contains only six tracked Swift source and test paths. The two added files are under the expected CmuxTerminal Sources and Tests directories. The four modified files are ex…
Cmux No Test Or Debug Seam In Production Source	✅ Passed	The PR adds no test or debug seam in production Swift source. The new TerminalRendererWindowVisibility.isVisible is product logic with a real production caller in Sources/GhosttyTerminalView.swift…

Full details: Description check

Explanation

The description explains what changed, why the change is required, the root cause, the visibility rule, affected paths, and test coverage. It does not include the template's Demo Video, Review Trigger, or Checklist sections, but the core description and testing information are complete.

Full details: Cmux Swift Actor Isolation

Explanation

PASS. The production changes do not introduce a stated actor-isolation failure. The new pure visibility helper is in the Swift 6 CmuxTerminal package, whose manifest does not set a MainActor default. GhosttyNSView is explicitly @MainActor; its new shared window table is accessed through main-queue callbacks and MainActor.assumeIsolated. MobileHostIrxRuntime explicitly marks its constant keys nonisolated and reads generationToken inside MainActor.run. Nonisolated socket-worker paths now await the @MainActor SurfaceCatalog. The remaining changed files are tests.

Full details: Cmux Swift Blocking Runtime

Explanation

PASS: The only newly added timing primitive is Task.sleep(for: .milliseconds(100)) in Packages/Shared/CmuxIrxTransport/Tests/CmuxIrxTransportTests/IrxLiveQUICTests.swift, which is test-only and allowed. The new production visibility helper and observer changes add no blocking or timing synchronization. Existing Task.sleep, asyncAfter, and NSLock occurrences in production files are unchanged by the diff.

Full details: Cmux Browser Automation Off-Main

Explanation

PASS — The PR diff from origin/main changes six files, none of which is Sources/TerminalController.swift or ControlCommandExecutionPolicy.swift. The changed SurfaceSocketCommands.swift edits only awaited SurfaceCatalog.shared; it adds or moves no browser.* command. No changed lines contain browser/WebKit automation routing, waits, or worker-lane policy changes. The custom check is therefore inapplicable, and it does not require new policy tests for this PR.

Full details: Cmux Expensive Synchronous Load

Explanation

PASS. The pull-request diff adds no RestorableAgentSessionIndex.load(), agent store/history load, transcript or trajectory read, broad scan, per-record syscall loop, or large JSON/JSONL parse. GhosttyTerminalView.swift adds only window-state evaluation and observers; its existing file reads remain unchanged. The SurfaceSocketCommands.swift changes await SurfaceCatalog.shared; SurfaceCatalog.init() is empty, and the changed paths do not load agent history. The remaining changes are test polling and Swift isolation fixes.

Full details: Cmux Cache Substitution Correctness

Explanation

PASS. The PR does not replace a fresh authoritative read with a cache in a persistence, history, undo, or snapshot path. The visibility state is a weak, in-memory UI presentation hint, which the policy allows. The SurfaceCatalog edits only add await when obtaining the same @MainActor singleton; the catalog still owns in-memory resources and projections. The other production edits change actor isolation and closure capture. The diff contains no changed TypeScript or JavaScript files and no changed durable-read or persistence consumer.

Full details: Cmux No Hacky Sleeps

Explanation

PASS. The PR changes six Swift files only; it changes no TypeScript, JavaScript, shell, or non-Swift build/runtime script. The only added sleep/polling is in the Swift test IrxLiveQUICTests.swift, which is outside this check's scope and is test-only. The production changes use Swift/AppKit and Swift concurrency APIs, so no covered hacky sleep condition is introduced.

Full details: Cmux Algorithmic Complexity

Explanation

PASS. The production diff adds only constant-time visibility branches, membership checks on an NSHashTable, and a loop over an explicit three-notification list. The new windowKeyObservers cleanup iterates only the three observers installed by that same fixed list. No changed production code adds nested scans, per-target rescans, repeated sorting/filtering, in-memory joins, or a super-linear algorithm. The SurfaceCatalog edits only make actor access explicit, and the remaining collection-heavy code is unchanged. The new tests and keepalive polling are test code, which the policy excludes.

Full details: Cmux Swift Concurrency

Explanation

PASS — The PR adds no new background Dispatch queues, DispatchGroup, Combine state, completion-handler API, or fire-and-forget Task { ... } pattern. The new NotificationCenter observers use the allowed AppKit callback and main-queue boundary. The added Task.sleep is test-only synchronization. The other concurrency changes add await and explicit isolation, which modernize existing code.

Full details: Cmux Swift `@Concurrent`

Explanation

PASS. The diff adds only a synchronous pure visibility helper, test polling with Task.sleep, synchronous nonisolated constants, and explicit await access to the @MainActor SurfaceCatalog. The changed surface entry points run through the existing nonisolated socket-worker v2VmCall bridge, so this is intentional UI-bound catalog coordination, not heavy async work called from UI isolation. No changed declaration adds invalid @concurrent, and no newly introduced nonisolated async operation requires an off-actor boundary.

Full details: Cmux Swift Package Boundaries

Explanation

PASS. The new visibility rule is in the SwiftPM CmuxTerminal target at Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalRendererWindowVisibility.swift, with unit tests in that package's test target. CmuxTerminal/Package.swift defines the library and CmuxTerminalTests dependency. The changes in Sources/GhosttyTerminalView.swift are AppKit/Ghostty integration glue, and the Mobile and surface-socket edits are lifecycle/concurrency fixes rather than new reusable domain logic. No changed production feature remains in an app-root source without a package boundary.

Full details: Cmux Swiftpm Lockfiles

Explanation

PASS. The PR diff from 39a1488 to 7e47d56 changes only Swift source and test files. It does not change Package.swift, Package.resolved, .gitignore, workflows, or Xcode project/workspace files. Packages/macOS/CmuxTerminal/Package.swift is unchanged, and that package has no local Package.resolved or .gitignore. Therefore, no dependency-resolution or package-reference change introduced by this PR requires a lockfile diff.

Full details: Cmux Swift Logging

Explanation

PASS — The PR diff from 39a1488 to HEAD adds no print, debugPrint, dump, NSLog, ad hoc file/stdout logging, Logger declaration, or sensitive-data log. Existing logging-related lines in Sources/GhosttyTerminalView.swift and Sources/Mobile/MobileHostIrxRuntime.swift are outside the changed hunks. The added code only evaluates window visibility, registers observers, updates async access, and changes test timing.

Full details: Cmux User-Facing Error Privacy

Explanation

PASS — The PR adds no user-facing error, alert, command-output, API-error, or recovery text. The new TerminalRendererWindowVisibility comments and tests are developer-facing, which the rule allows. The only modified production lines change visibility logic, Swift isolation, and awaited catalog access; existing socket error messages and raw-error handling are unchanged. The changed defaults strings are internal keys, not user-visible output.

Full details: Cmux Full Internationalization

Explanation

PASS: The PR introduces no new or changed user-facing copy. The production diff adds only renderer-visibility logic, observer wiring, actor-isolation fixes, and awaited catalog access. Added prose is developer documentation/comments, and the added tests and keepalive comments are exempt. The changed paths contain no .xcstrings, .strings, Info.plist, web locale, metadata, markdown, or changelog files. Existing socket error messages remain unchanged.

Full details: Cmux Swiftui State Layout

Explanation

PASS. The diff introduces no SwiftUI state or layout pattern covered by the rule. The visibility changes are inside GhosttyNSView: NSView and use AppKit window notifications and NSHashTable; the SwiftUI NSViewRepresentable wrapper is not changed. The other changed files contain no SwiftUI state, GeometryReader, lazy/list row store references, or render-time state writes.

Full details: Cmux Architecture Rethink

Explanation

The diff adds a process-wide mutable side channel: GhosttyNSView.windowsThatReportedVisible stores window history in a static NSHashTable, while TerminalSurface.rendererWindowVisible still owns the current renderer state and AppKit owns current occlusion. windowDidChangeScreen only reapplies the cached decision; it does not reset or rebind the history. A window can therefore retain a prior .visible result across a hosting or display transition, so stale visibility state remains representable. This violates the rule against new caches or side channels that split lifecycle ownership. The added key notifications are documented platform callbacks, and the polling sleep is test-only, so they are not the finding.

Resolution

Remove the static window table from GhosttyNSView. Make the existing window/presentation owner, or a per-window @MainActor coordinator created by it, the single owner of observer tokens and hasReportedVisible. Expose an immutable visibility snapshot and one apply action to TerminalSurface. Route initial attach, occlusion, key/main transitions, and screen changes through that action. Reset or replace the per-window history when the hosting window or display lifecycle changes. Add tests for detach/reattach and real-display-to-virtual-display transitions, in addition to the existing rule tests.

Full details: Cmux Swift Auxiliary Window Close Shortcuts

Explanation

PASS: The PR does not add or materially change a standalone cmux-owned window. Its only production NSWindow change is visibility observation in GhosttyNSView, which hosts terminal panes. The new TerminalRendererWindowVisibility helper only evaluates an existing hosting window; it does not create a window, assign an identifier, add Cmd+W handling, or change cmuxAuxiliaryWindowIdentifiers. The remaining Swift changes are transport code and test-only code. Terminal panes are explicitly allowed by the rule.

Full details: Cmux Source Artifacts

Explanation

PASS. The base-to-HEAD diff contains only six tracked Swift source and test paths. The two added files are under the expected CmuxTerminal Sources and Tests directories. The four modified files are existing hand-written source or test files. No local logs, screenshots, recordings, temp or scratch directories, dependency checkouts, caches, build output, or package-manager downloads enter the diff.

Full details: Cmux No Test Or Debug Seam In Production Source

Explanation

The PR adds no test or debug seam in production Swift source. The new TerminalRendererWindowVisibility.isVisible is product logic with a real production caller in Sources/GhosttyTerminalView.swift; it does not expose private state and its name does not signal a test/debug hook. The diff adds no test-build guard, test-named member, or wrapper accessor. The new tests remain under Packages/macOS/CmuxTerminal/Tests/** and use @testable import. Other production changes only adjust runtime isolation and catalog access.

Full details: Cmux No Ambient Global State

Explanation

The PR adds a caseless public enum used only as a static-helper namespace. In Packages/macOS/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalRendererWindowVisibility.swift:13-26, TerminalRendererWindowVisibility has no cases and exposes only public static func isVisible. The production caller and tests use TerminalRendererWindowVisibility.isVisible(...) directly. This matches the rule's explicit failure condition for a caseless enum or type whose API is mostly static functions, and the type is newly added by this PR.

Resolution

Move the visibility behavior onto a constructable, injectable owning type. For example, make TerminalRendererWindowVisibility an instance-based struct with an instance isVisible method, construct or inject one at the GhosttyNSView seam, and update the tests and caller to use that instance. Keep any per-window visibility history owned by the scoped view/controller rather than adding another shared static state holder.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/renderer-occlusion-headless-window

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.