GhosttyTerminalView decomposition: terminal surface model (stack D)

[azooz2003-bit]

Stack D of the modular refactor: decomposing Sources/GhosttyTerminalView.swift per GhosttyTerminalView.plan.md, stacked on the TerminalEngine slice (#5929). One large PR; tranches land as separate commits.

Tranche 1 (landed): TerminalSurface model into CmuxTerminal

GhosttyTerminalView.swift 15,221 -> 12,226 lines.

New Packages/CmuxTerminal (Wave 3 domain package, depends on CmuxTerminalCore + CmuxGhosttyKit): TerminalSurface + SearchState lifted faithfully (still ObservableObject/@Published; modernization is a separate phase), split by role under Surface/, Spawn/, Lifecycle/, Hosting/, Runtime/, Events/.

Seam inversions (all legacy reach-ups now injected through TerminalSurfaceRuntimeDependencies):

• GhosttyApp.shared -> TerminalEngineHosting
• view construction -> TerminalSurfaceViewProviding (app injects the GhosttyNSView/GhosttySurfaceScrollView factory)
• settings/control-socket reads at spawn -> TerminalSurfaceSpawnPolicyProviding
• MobileTerminalByteTee.shared + Unmanaged tee context -> TerminalByteTeeBinding with lease objects
• RendererRealizationController.shared -> TerminalRendererRealizationScheduling
• recordAgentHibernationTerminalInput free function + AgentHibernationController.shared -> AgentHibernationRecording
• TerminalSurfaceRuntimeTeardownCoordinator.shared actor singleton -> injected instance; its two enqueue free functions folded into one member with defaulted freeSurface

App-side residue: Sources/TerminalSurfaceRuntimeWiring.swift holds the conformances/bridges plus a convenience init that keeps every legacy TerminalSurface(...) call site byte-identical. CmuxSurfaceConfigTemplate, the surface runtime probes, the Claude command shim, and the cmux context environment lifted to CmuxTerminalCore; WorkspaceSurfaceConfig.swift keeps forwarding shims. App-side tests naming the moved type get import CmuxTerminal hoisted above the canImport(cmux_DEV) block.

Behavior invariants: Defaults keys, environment keys (CMUX_*), and notification raw strings byte-identical (cmux.terminalSurfaceDidBecomeReady moved, same string). Adversarial normalize-and-diff of createSurface and the teardown path vs pre-tranche HEAD (8bbb21b) shows only the seam substitutions.

Two deliberate compiler-enforced isolation upgrades of legacy main-thread-only contracts: TerminalSurface.searchState is @MainActor (its didSet always ran on main), so startOrFocusTerminalSearch is now @MainActor (both callers already were); GhosttyNSView's copy-mode indicator accessors went fileprivate -> internal as protocol witnesses.

Gates: swift_file_length_budget (cutover budget write), lint-ios-package-conventions, pbxproj normalize/check + ID-collision sweep, swift build+swift test on CmuxTerminal/Core/Engine/Services (Core 66, Engine 14, Services 15, Terminal 2 incl. new teardown-coordinator behavior tests), full app xcodebuild build green.

e2e: FindSelectionShortcutUITests PASSED at ea8d799 (exercises full app launch + terminal + the moved searchState path: manaflow-ai/cmux-dev-artifacts#2939). AutomationSocketUITests failed with app-activation timeouts (manaflow-ai/cmux-dev-artifacts#2942), but that class is red on main too (manaflow-ai/cmux-dev-artifacts#2528, manaflow-ai/cmux-dev-artifacts#2479), pre-existing runner flake class, not introduced by this branch.

Leg 2 status: remaining slices are blocked on prerequisite domain packaging

Leg 1 (TerminalSurface MODEL → CmuxTerminal) succeeded because the model's dependencies had already been seam-inverted into CmuxTerminalCore/Engine (TerminalSurfaceRuntimeDependencies, TerminalSurfaceViewProviding, etc.). The model package never names a view type or an app singleton.

Leg 2 surveyed the rest of the god file (now 12,226 lines) to continue the lift. Every remaining slice is deeply entangled with app-domain types that have not yet been extracted into packages, so none can be lifted faithfully and latency-neutrally in isolation right now:

• View layer (GhosttyNSView 3865–7923, GhosttySurfaceScrollView 8027–11245, the NSTextInputClient IME extension 11246–11751, the GhosttyTerminalView representable 11752–end; ~7,400 lines) references 51 distinct app-defined types across the Panels, Appearance, Find, Settings-shortcuts, Workspace, image-transfer, and portal domains, plus the GhosttyApp / AppDelegate / Workspace singletons. ~28 of those are reached only transiently inside method bodies (seamable to primitives), but ~23 appear in stored-property or function-signature positions and would each need either co-moving (they are shared with 1–8 other app files, so co-moving breaks their other callers) or a behavioral seam with an app-side conformer. Reach-up neutrality is favorable — every GhosttyApp.shared (11 members) and AppDelegate.shared (8 members) reference is on a COLD path (background/appearance/theme-sync/focus/config/debug), none in the per-keystroke or per-frame inner loop; the only hot-path app symbol is CmuxTypingTiming telemetry. So a faithful lift is possible but is a large multi-seam effort that must be dogfooded on the typing-critical paths between steps (repo CLAUDE.md flags TerminalSurface.forceRefresh(), WindowTerminalHostView.hitTest(), and the SurfaceSearchOverlay-must-mount-from-GhosttySurfaceScrollView portal-layering contract as fragile).

• Engine wrapper (GhosttyApp 362–3855, a static let shared @MainActor singleton; ~3,500 lines) references 45 distinct app types (incl. GhosttyConfig, MobileTerminalByteTee, RendererRealizationController, WindowBackdropController, settings types) with 17 AppDelegate.shared + 12 Workspace.shared reach-ups. Its target package CmuxTerminalEngine currently depends only on CmuxTerminalCore.

• Even the plan's "pure Sendable engine value DTOs" (ScrollbarVisibility, AppearanceSynchronizationPlan, RuntimeColorSchemeSynchronizationDecision, DefaultBackgroundValues, the font/appearance summaries) cannot be promoted into CmuxTerminalEngine in isolation: they are nested in GhosttyApp, carry app types (GhosttyConfig.ColorSchemePreference, GhosttyBackgroundBlur, NSColor), and are produced by GhosttyApp static/instance methods that call other GhosttyApp appearance-engine helpers. They only separate cleanly as part of the full GhosttyApp lift, which itself needs GhosttyConfig packaged first.

Prerequisite (the unblocker): package GhosttyConfig and the shared value/styling types the view+engine layers depend on (the Panels styling enums, WindowAppearanceSnapshot, image-transfer DTOs, the Settings shortcut/scrollbar value types) — work owned by the parallel AppDelegate/TabManager/ContentView stacks. Once those land, the seam surface for the view layer drops to behavioral-only and the engine value DTOs become liftable.

Corrected sequencing for the next leg (once GhosttyConfig + shared value types are packaged):

1. GhosttyApp → GhosttyAppService in CmuxTerminalEngine, lifting the engine value DTOs to top-level Sendable types; invert its AppDelegate/Workspace reach-ups via WorkspaceResolving/tab-routing seams. This removes the heaviest view-layer reach-up family (GhosttyApp.shared).
2. View layer → CmuxTerminalSurface, with the GhosttyApp/AppDelegate/Workspace/portal reach-ups injected as the plan's TerminalSurfaceBackgroundProviding / TerminalPortalBinding / TerminalPortalGeometryReporting seams (all cold-path, so latency-neutral), the IME/scroll/overlay transient state staying in the moved view types. Preserve the SurfaceSearchOverlay portal-mount contract.
3. Window chrome → CmuxWorkspaceWindow.
4. Final god-file deletion + composition-root wiring.

Leg 2 leaves the worktree at the verified-green leg-1 head (file-length budget + package-conventions lint pass; CmuxTerminal package swift build green; full app xcodebuild build BUILD SUCCEEDED) rather than forcing a high-risk partial lift of the typing-latency-critical view in a state that cannot be dogfooded between steps.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added mobile terminal viewport limiting plus new mobile scroll/click and grid-frame export capabilities.
  • Introduced hex-based color helpers and a dedicated terminal light/dark color-scheme preference model.
  • Improved Ghostty config discovery/loading and added safe editing support for sidebar and surface tab bar font sizes (with validation and clamping).

• Improvements

  • Refreshed terminal surface focus, renderer/portal lifecycle, and input/copy-mode handling for more reliable behavior.
  • Standardized window glass/transparent background decisions and compositor blur resets for more consistent visuals.

[coderabbitai]

Actionable comments posted: 11

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

cmux.xcodeproj/project.pbxproj (1)

1700-1710: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add CmuxTerminal and CmuxWorkspaceWindow to cmux target package dependencies.

Lines 1700 and 1710 add these products to the Frameworks phase, but PBXNativeTarget "cmux" packageProductDependencies (around Line 2637) does not include C750500000000000000000A2 or C750400000000000000000D2. This leaves SwiftPM target wiring incomplete.

Suggested pbxproj fix

 			packageProductDependencies = (
 				A5001231 /* Sparkle */,
 				A5001251 /* Sentry */,
@@
 				C750300000000000000000A2 /* CmuxTerminalEngine */,
 				C750400000000000000000A2 /* CmuxTerminalServices */,
+				C750500000000000000000A2 /* CmuxTerminal */,
+				C750400000000000000000D2 /* CmuxWorkspaceWindow */,
 				A8BD195031FC4B82B4354297 /* StackAuth */,
 				EFB18E3B3099DFE2ECA3C263 /* CMUXMobileCore */,
 			);

As per coding guidelines, cmux.xcodeproj/** changes must keep project wiring coherent for app/runtime code paths.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cmux.xcodeproj/project.pbxproj` around lines 1700 - 1710, The diff adds
CmuxTerminal and CmuxWorkspaceWindow to the Frameworks section (lines 1700 and
1710 with IDs C750500000000000000000A3 and C750400000000000000000D3), but the
corresponding product dependency IDs C750500000000000000000A2 and
C750400000000000000000D2 are missing from the packageProductDependencies array
of the PBXNativeTarget "cmux" (around line 2637). Add both missing product
dependency IDs to the packageProductDependencies array to complete the SwiftPM
target wiring and ensure consistency between framework dependencies and package
product declarations.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Packages/CmuxFoundation/Sources/CmuxFoundation/Color/NSColor`+Hex.swift:
- Around line 7-22: The hex parser has two validation issues that accept
malformed input. First, the global replacingOccurrences(of:"#", with:"") call
removes all # characters instead of just a leading prefix, allowing input like
"1#23456" to be accepted. Second, Scanner.scanHexInt64(_:) only validates a
valid hex prefix and does not require consuming the entire string, so input like
"12ABXX" passes the length check but is parsed incorrectly. Replace the hex
string sanitization and validation logic by first removing only a leading # if
present, then validating that the remaining string is exactly 6 characters long
and contains only valid hexadecimal characters (0-9, A-F, a-f) before attempting
to parse it with the Scanner, rejecting any input that fails these strict
checks.

In
`@Packages/CmuxTerminal/Sources/CmuxTerminal/Lifecycle/TerminalSurfaceRuntimeTeardownCoordinator.swift`:
- Around line 76-82: The nextRequestForWorker() method uses Array.removeFirst()
to dequeue items from queuedRequests, which performs O(n) array shifts per
dequeue operation, resulting in O(n²) complexity when draining large queues.
Replace the queuedRequests Array with a Deque (or implement a head-index FIFO
pattern with manual index tracking) to achieve O(1) dequeue operations. Update
the isEmpty check and the removeFirst() call in nextRequestForWorker() to use
the new data structure's dequeue method.

In `@Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/NSScreen`+DisplayID.swift:
- Around line 10-11: The code casts Int and NSNumber values directly to UInt32
without checking if they are non-negative, which can cause negative values to
wrap around and produce incorrect display IDs. Add guard conditions before the
UInt32 conversions to ensure both the Int value and the NSNumber value are
non-negative (greater than or equal to zero). If a value is negative, skip that
conversion and continue to the next check or return a default value. This
applies to both the Int casting line and the NSNumber casting line in this
function.

In
`@Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface`+Mobile.swift:
- Around line 15-27: The mobileScroll function does not validate that col and
row parameters are non-negative before calculating positions and sending them to
ghostty_surface_mouse_pos, unlike mobileClick which guards against negative
values. Add a guard statement early in the mobileScroll function to ensure both
col >= 0 and row >= 0, returning early if either condition fails, to prevent
negative coordinates from being forwarded to the ghostty surface mouse position
handler.

In
`@Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface`+RuntimeLifecycle.swift:
- Around line 13-919: The TerminalSurface+RuntimeLifecycle.swift extension file
exceeds 900 lines and violates the repository's coding guidelines by combining
multiple distinct responsibilities: bootstrap-window management, liveness
quarantine, teardown/hibernation, view attachment, Claude shim installation, and
runtime/environment construction. Split this file into separate, focused
extensions following the repository's guidance that Swift production files
should not exceed 800 lines. At minimum, move the createSurface method and all
related environment assembly logic (setManagedEnvironmentValue, environment
variable setup, command/working directory resolution) into one new extension
file (e.g., TerminalSurface+SurfaceCreation.swift), and move the
teardown-related methods (teardownSurface,
suspendRuntimeSurfaceForAgentHibernation, closeHeadlessStartupWindowIfNeeded)
and attachment logic (attachToView, attachedView management) into another
extension file (e.g., TerminalSurface+Teardown.swift or
TerminalSurface+Attachment.swift). Ensure each resulting file has a clear,
single primary responsibility and remains under 800 lines.
- Around line 409-419: The code is calling ghostty_surface_set_display_id
directly on the raw surface pointer instead of routing through the liveness
guard liveSurfaceForGhosttyAccess(reason:). Replace the direct surface pointer
usage with a call to liveSurfaceForGhosttyAccess to ensure the pointer is
validated before dereferencing, preventing crashes from dangling pointers if
Ghostty has already freed the surface out-of-band. This pattern appears in
multiple locations throughout the reattach logic and should be fixed
consistently everywhere ghostty_surface_set_display_id is called on a
potentially-invalidated surface reference.

In
`@Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface`+Sizing.swift:
- Around line 312-315: The display ID is being set on currentSurface after a
potential surface recreation via view.forceRefreshSurface(), but when the
surface is invalidated and recreated, the reacquired surface never receives the
display ID topology fix. Apply the display ID setting to the newly reacquired
surface immediately after it is obtained, before any subsequent operations like
ghostty_surface_refresh. This fix needs to be applied at both locations where
surfaces are reacquired in TerminalSurface+Sizing.swift (at lines 312-315 and
lines 323-326).
- Around line 272-285: Remove the DEBUG block containing string construction and
the logDebugEvent call from the forceRefresh method because this method is a
per-keystroke hot path and adding string formatting and logging violates the
typing-latency coding guidelines. Delete the entire if DEBUG section from
forceRefresh and apply the same fix to any other similar debug logging blocks in
this file that have been added to hot-path methods.

In
`@Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/Config/GhosttyConfig.swift`:
- Around line 246-251: When rawSidebarBackground is nil in the guard statement
at line 246-251 of GhosttyConfig.swift, stale sidebarTintHex* keys remain in
UserDefaults and continue to affect sidebar rendering. In the early-return
branch where rawSidebarBackground is nil, add code to remove the stale sidebar
tint defaults (the sidebarTintHex* keys) from UserDefaults in addition to the
existing sidebarTintOpacity handling. This same cleanup logic should also be
applied at the corresponding location mentioned around lines 255-269 to ensure
consistency across all cases where sidebar-background is removed or cleared.
- Around line 207-220: The cmuxConfigPaths function currently uses
fileManager.urls(...).first which only retrieves a single application support
directory, ignoring CFFIXED_USER_HOME overrides and fallback candidates that are
standardized in CmuxApplicationSupportDirectories.userDirectories(...). Replace
the guard statement that retrieves appSupport using fileManager.urls with a call
to CmuxApplicationSupportDirectories.userDirectories(...), then update the
CmuxGhosttyConfigPathResolver.loadConfigURLs call to iterate through all
resolved directories instead of just a single appSupport directory, ensuring
proper handling of sandbox and test override scenarios.

In
`@Packages/CmuxWorkspaceWindow/Sources/CmuxWorkspaceWindow/Blur/CompositorBlurController.swift`:
- Around line 40-45: The resetBackgroundBlur(windowNumber:) function accepts an
Int parameter and directly converts it to UInt without validation, which will
cause a fatal runtime error if a negative value is passed. Add a guard statement
at the beginning of the function to verify that windowNumber is non-negative
(greater than or equal to 0), and either return early or throw an error if the
check fails. This ensures the API enforces its contract at the boundary rather
than relying on callers to only pass valid positive window numbers.

---

Outside diff comments:
In `@cmux.xcodeproj/project.pbxproj`:
- Around line 1700-1710: The diff adds CmuxTerminal and CmuxWorkspaceWindow to
the Frameworks section (lines 1700 and 1710 with IDs C750500000000000000000A3
and C750400000000000000000D3), but the corresponding product dependency IDs
C750500000000000000000A2 and C750400000000000000000D2 are missing from the
packageProductDependencies array of the PBXNativeTarget "cmux" (around line
2637). Add both missing product dependency IDs to the packageProductDependencies
array to complete the SwiftPM target wiring and ensure consistency between
framework dependencies and package product declarations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 962aeada-9b8e-4d11-92e6-e517acca0c56

📥 Commits

Reviewing files that changed from the base of the PR and between 02a041f and 3f8e336.

⛔ Files ignored due to path filters (1)

• .github/swift-file-length-budget.tsv is excluded by !**/*.tsv

📒 Files selected for processing (133)

• CLI/CMUXCLI+Config.swift
• CLI/CMUXCLI+ThemeSupport.swift
• CLI/CMUXCLI+Themes.swift
• Packages/CmuxFoundation/Sources/CmuxFoundation/Color/NSColor+Hex.swift
• Packages/CmuxFoundation/Sources/CmuxFoundation/ConfigPaths/CmuxApplicationSupportDirectories.swift
• Packages/CmuxFoundation/Sources/CmuxFoundation/ConfigPaths/CmuxGhosttyConfigPathResolver.swift
• Packages/CmuxFoundation/Sources/CmuxFoundation/ConfigPaths/CmuxGhosttyConfigSettingEditor.swift
• Packages/CmuxFoundation/Sources/CmuxFoundation/ConfigValues/GhosttyBackgroundBlur.swift
• Packages/CmuxTerminal/Package.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Events/TerminalSurfaceNotifications.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Hosting/TerminalSurfaceNativeViewing.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Hosting/TerminalSurfacePaneHosting.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Hosting/TerminalSurfaceViewProviding.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Lifecycle/TerminalSurfaceRuntimeTeardownCoordinator.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Lifecycle/TerminalSurfaceRuntimeTeardownRequest.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Runtime/AgentHibernationRecording.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Runtime/TerminalByteTeeBinding.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Runtime/TerminalEngineHosting.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Runtime/TerminalRendererRealizationScheduling.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Runtime/TerminalSurfaceRuntimeDependencies.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Spawn/TerminalSurface+StartupEnvironment.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Spawn/TerminalSurfaceSpawnPolicy.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Spawn/TerminalSurfaceSpawnPolicyProviding.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/NSScreen+DisplayID.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+CopyMode.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Debug.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Input.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Mobile.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+PortalLease.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Renderer.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+RuntimeLifecycle.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface+Sizing.swift
• Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface.swift
• Packages/CmuxTerminal/Tests/CmuxTerminalTests/TerminalSurfaceRuntimeTeardownCoordinatorTests.swift
• Packages/CmuxTerminal/Tests/GhosttyRuntimeTestStubs/GhosttyRuntimeTestStubs.c
• Packages/CmuxTerminal/Tests/GhosttyRuntimeTestStubs/include/GhosttyRuntimeTestStubs.h
• Packages/CmuxTerminalCore/Package.swift
• Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/ColorScheme/TerminalColorSchemePreference.swift
• Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/ColorScheme/TerminalStartupAppearancePreviewOverride.swift
• Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/ColorScheme/TerminalSystemAppearance.swift
• Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/Config/GhosttyConfig.swift
• Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/Interop/GhosttySurfaceRuntimeProbe.swift
• Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/SurfaceValues/CmuxSurfaceConfigTemplate.swift
• Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/SurfaceValues/TerminalSurfaceClaudeCommandShim.swift
• Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/SurfaceValues/TerminalSurfaceCmuxContextEnvironment.swift
• Packages/CmuxTerminalCore/Tests/CmuxTerminalCoreTests/SidebarFontSizeConfigTests.swift
• Packages/CmuxTerminalCore/Tests/CmuxTerminalCoreTests/SurfaceTabBarFontSizeConfigTests.swift
• Packages/CmuxTerminalCore/Tests/CmuxTerminalCoreTests/TerminalSystemAppearanceTests.swift
• Packages/CmuxTerminalCore/Tests/GhosttyRuntimeTestStubs/GhosttyRuntimeTestStubs.c
• Packages/CmuxTerminalCore/Tests/GhosttyRuntimeTestStubs/include/GhosttyRuntimeTestStubs.h
• Packages/CmuxWorkspaceWindow/Package.swift
• Packages/CmuxWorkspaceWindow/Sources/CmuxWorkspaceWindow/Blur/CompositorBlurController.swift
• Packages/CmuxWorkspaceWindow/Sources/CmuxWorkspaceWindow/Policy/WindowBackgroundPolicy.swift
• Packages/CmuxWorkspaceWindow/Sources/CmuxWorkspaceWindow/Settings/WindowBackgroundSettingsReading.swift
• Packages/CmuxWorkspaceWindow/Tests/CmuxWorkspaceWindowTests/WindowBackgroundPolicyTests.swift
• Sources/App/RendererRealizationController.swift
• Sources/App/ShortcutRoutingSupport.swift
• Sources/App/TerminalFindEscapeRouting.swift
• Sources/AppDelegate.swift
• Sources/AppearanceSettings.swift
• Sources/BackgroundWorkspacePrimeCoordinator.swift
• Sources/CmuxApplicationSupportDirectories.swift
• Sources/ContentView.swift
• Sources/DockPanelView.swift
• Sources/DragOverlayRoutingPolicy.swift
• Sources/Feed/FeedButtonStyleDebugWindowController.swift
• Sources/Find/SurfaceSearchOverlay.swift
• Sources/GhosttyConfig.swift
• Sources/GhosttyTerminalAppearance.swift
• Sources/GhosttyTerminalView.swift
• Sources/GhosttyTerminalViewSupport.swift
• Sources/HostSettingsActions.swift
• Sources/MainWindowFocusController.swift
• Sources/Mobile/MobileTerminalByteTee.swift
• Sources/Panels/AgentSessionWebTheme.swift
• Sources/Panels/BrowserPanel.swift
• Sources/Panels/MarkdownPanelView.swift
• Sources/Panels/MarkdownWebSupport.swift
• Sources/Panels/TerminalPanel.swift
• Sources/Panels/TerminalPanelView.swift
• Sources/Settings/ConfigSource.swift
• Sources/Sidebar/SidebarAppearanceSupport.swift
• Sources/SidebarWorkspaceGroupHeaderView.swift
• Sources/TabManager.swift
• Sources/TerminalController+ControlDebugContext.swift
• Sources/TerminalController+ControlSidebarContext3.swift
• Sources/TerminalController.swift
• Sources/TerminalImageTransfer.swift
• Sources/TerminalPaneDropTargetView.swift
• Sources/TerminalSurfaceClaudeCommandShim.swift
• Sources/TerminalSurfaceCmuxContextEnvironment.swift
• Sources/TerminalSurfaceRuntimeWiring.swift
• Sources/TerminalViewportUITestRecorder.swift
• Sources/TerminalWindowPortal.swift
• Sources/TextBoxInput.swift
• Sources/Windowing/WindowAppearanceSnapshot.swift
• Sources/Windowing/WindowBackdropController.swift
• Sources/Windowing/WindowBackgroundComposition.swift
• Sources/Windowing/WindowGlassEffect.swift
• Sources/Workspace.swift
• Sources/WorkspaceAppearanceResolution.swift
• Sources/WorkspaceContentView.swift
• Sources/WorkspaceSurfaceConfig.swift
• Sources/cmuxApp.swift
• cmux.xcodeproj/project.pbxproj
• cmuxTests/AgentHibernationTests.swift
• cmuxTests/AppDelegateMoveTabToNewWorkspaceTests.swift
• cmuxTests/AppDelegateShortcutRoutingTests.swift
• cmuxTests/CJKIMEInputTests.swift
• cmuxTests/CJKIMEMarkedSelectionTests.swift
• cmuxTests/FinderFileDropRegressionTests.swift
• cmuxTests/FishShellIntegrationTests.swift
• cmuxTests/GhosttyCommandShiftForwardingTests.swift
• cmuxTests/GhosttyConfigPathResolverTests.swift
• cmuxTests/GhosttyConfigTests.swift
• cmuxTests/GhosttyNotificationDispatcherTests.swift
• cmuxTests/GhosttyTerminalStartupEnvironmentTests.swift
• cmuxTests/SessionPersistenceTests.swift
• cmuxTests/ShellStartupMatrixTests.swift
• cmuxTests/ShellStartupMissingBundleTests.swift
• cmuxTests/SidebarWidthPolicyTests.swift
• cmuxTests/TabManagerSessionSnapshotTests.swift
• cmuxTests/TabManagerUnitTests.swift
• cmuxTests/TerminalAndGhosttyTests.swift
• cmuxTests/TerminalControllerSocketSecurityTests.swift
• cmuxTests/TerminalSearchOverlayMouseReleaseTests.swift
• cmuxTests/TraditionalChineseIMENumpadRegressionTests.swift
• cmuxTests/WindowAppearanceSnapshotTests.swift
• cmuxTests/WorkspaceAppearanceConfigResolutionTests.swift
• cmuxTests/WorkspaceCloseTabsContextMenuTests.swift
• cmuxTests/WorkspaceRemoteConnectionTests.swift
• cmuxTests/WorkspaceSplitStartupCommandTests.swift
• cmuxTests/WorkspaceUnitTests.swift

💤 Files with no reviewable changes (3)

• Sources/TerminalSurfaceCmuxContextEnvironment.swift
• Sources/TerminalSurfaceClaudeCommandShim.swift
• Sources/CmuxApplicationSupportDirectories.swift

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

In Swift Foundation, does Scanner.scanHexInt64(_:) succeed when only a prefix is valid hex (for example "12GG34")? Is checking scanner.isAtEnd required for strict full-string validation?

💡 Result:

In Swift Foundation, Scanner.scanHexInt64(:) does succeed when only a prefix is valid [1][2]. The method scans for a valid hexadecimal representation starting at the current position, and if found, it returns true and advances the scanner's position past the end of the scanned hexadecimal digits [1]. It does not require that the entire remainder of the string be consumed or that the scanner be at the end of the string [1]. For example, if you call scanHexInt64(:) on the string "12GG34", the scanner will successfully identify "12" as a valid hexadecimal number, store the value 0x12 (18) in the provided pointer, and move the scanner's current position to the character 'G'. Because it successfully scanned a valid prefix, it returns true [1]. Therefore, checking scanner.isAtEnd is required if you want to ensure the entire string is a valid hexadecimal number [1][3]. Without this check, the scanner will report success as long as it finds a valid numeric start, leaving the remaining invalid characters unparsed [1]. To perform strict full-string validation, you must ensure that after the scan completes, scanner.isAtEnd is true [1][4].

Citations:

• 1: https://developer.apple.com/documentation/foundation/scanner/scanhexint64(_:)
• 2: https://sosumi.ai/documentation/foundation/scanner/scanhexint64(_:)
• 3: https://developer.apple.com/documentation/foundation/scanner
• 4: https://www.kodeco.com/1039-scanner-tutorial-for-macos/page/2

---

🏁 Script executed:

find . -name "NSColor+Hex.swift" -type f

Repository: manaflow-ai/cmux

Length of output: 133

---

🏁 Script executed:

cat -n "./Packages/CmuxFoundation/Sources/CmuxFoundation/Color/NSColor+Hex.swift"

Repository: manaflow-ai/cmux

Length of output: 3537

---

Reject malformed hex input before conversion.

The hex parser accepts invalid input for two reasons:

1. Line 8: replacingOccurrences(of: "#", with: "") removes all # characters globally, not just a leading prefix. Input like "1#23456" normalizes to "123456" and is accepted.

2. Lines 10–13: Scanner.scanHexInt64(_:) succeeds on a valid hex prefix and does not consume the entire string. Input like "12ABXX" (6 chars) passes the length check, but Scanner consumes only "12AB", leaving "XX" unparsed. The resulting color is incorrect.

Replace with strict validation and parsing:

🔧 Suggested fix

-        var hexSanitized = hex.trimmingCharacters(in: .whitespacesAndNewlines)
-        hexSanitized = hexSanitized.replacingOccurrences(of: "#", with: "")
-
-        var rgb: UInt64 = 0
-        guard Scanner(string: hexSanitized).scanHexInt64(&rgb) else {
-            return nil
-        }
+        var hexSanitized = hex.trimmingCharacters(in: .whitespacesAndNewlines)
+        if hexSanitized.hasPrefix("#") {
+            hexSanitized.removeFirst()
+        }
+        guard hexSanitized.count == 6,
+              hexSanitized.unicodeScalars.allSatisfy({ CharacterSet.hexDigits.contains($0) }),
+              let rgb = UInt64(hexSanitized, radix: 16) else {
+            return nil
+        }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@Packages/CmuxFoundation/Sources/CmuxFoundation/Color/NSColor`+Hex.swift
around lines 7 - 22, The hex parser has two validation issues that accept
malformed input. First, the global replacingOccurrences(of:"#", with:"") call
removes all # characters instead of just a leading prefix, allowing input like
"1#23456" to be accepted. Second, Scanner.scanHexInt64(_:) only validates a
valid hex prefix and does not require consuming the entire string, so input like
"12ABXX" passes the length check but is parsed incorrectly. Replace the hex
string sanitization and validation logic by first removing only a leading # if
present, then validating that the remaining string is exactly 6 characters long
and contains only valid hexadecimal characters (0-9, A-F, a-f) before attempting
to parse it with the Scanner, rejecting any input that fails these strict
checks.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify the dequeue pattern currently uses front-removal in the worker path.
rg -n -C3 'nextRequestForWorker|removeFirst\(\)' Packages/CmuxTerminal/Sources/CmuxTerminal/Lifecycle/TerminalSurfaceRuntimeTeardownCoordinator.swift

Repository: manaflow-ai/cmux

Length of output: 785

---

🏁 Script executed:

cat .github/review-bot-rules/algorithmic-complexity.md

Repository: manaflow-ai/cmux

Length of output: 2617

---

🏁 Script executed:

# Check the overall context of TerminalSurfaceRuntimeTeardownCoordinator
wc -l Packages/CmuxTerminal/Sources/CmuxTerminal/Lifecycle/TerminalSurfaceRuntimeTeardownCoordinator.swift

Repository: manaflow-ai/cmux

Length of output: 165

---

🏁 Script executed:

# Get the full file to understand queue bounds and usage patterns
cat -n Packages/CmuxTerminal/Sources/CmuxTerminal/Lifecycle/TerminalSurfaceRuntimeTeardownCoordinator.swift

Repository: manaflow-ai/cmux

Length of output: 5547

---

Switch from Array.removeFirst() to a head-index FIFO pattern to avoid O(n²) queue drains during large close bursts.

Using Array.removeFirst() shifts the buffer for each dequeue, making the total cost for draining n queued surfaces O(n²). For workspace closes that queue 100+ surfaces at once, this wastes CPU on array shifts. The teardown coordinator is a production path expected to handle 1000+ surfaces (per algorithmic-complexity.md), so switch to a linear-time dequeue using a head index or deque.

♻️ Suggested implementation

+    private var queueHead = 0

     private func nextRequestForWorker() -> TerminalSurfaceRuntimeTeardownRequest? {
-        guard !queuedRequests.isEmpty else {
+        guard queueHead < queuedRequests.count else {
+            queuedRequests.removeAll(keepingCapacity: true)
+            queueHead = 0
             isWorkerRunning = false
             return nil
         }
-        return queuedRequests.removeFirst()
+        let request = queuedRequests[queueHead]
+        queueHead += 1
+        return request
     }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/CmuxTerminal/Sources/CmuxTerminal/Lifecycle/TerminalSurfaceRuntimeTeardownCoordinator.swift`
around lines 76 - 82, The nextRequestForWorker() method uses Array.removeFirst()
to dequeue items from queuedRequests, which performs O(n) array shifts per
dequeue operation, resulting in O(n²) complexity when draining large queues.
Replace the queuedRequests Array with a Deque (or implement a head-index FIFO
pattern with manual index tracking) to achieve O(1) dequeue operations. Update
the isEmpty check and the removeFirst() call in nextRequestForWorker() to use
the new data structure's dequeue method.

Source: Coding guidelines

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Guard signed NSScreenNumber conversions before casting to UInt32.

Int/NSNumber can be negative; converting directly to UInt32 wraps and can produce a bogus display ID.

Suggested fix

-        if let v = deviceDescription[key] as? Int { return UInt32(v) }
-        if let v = deviceDescription[key] as? NSNumber { return v.uint32Value }
+        if let v = deviceDescription[key] as? Int,
+           v >= 0,
+           v <= Int(UInt32.max) {
+            return UInt32(v)
+        }
+        if let v = deviceDescription[key] as? NSNumber {
+            let n = v.int64Value
+            guard n >= 0, n <= Int64(UInt32.max) else { return nil }
+            return UInt32(n)
+        }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/NSScreen`+DisplayID.swift
around lines 10 - 11, The code casts Int and NSNumber values directly to UInt32
without checking if they are non-negative, which can cause negative values to
wrap around and produce incorrect display IDs. Add guard conditions before the
UInt32 conversions to ensure both the Int value and the NSNumber value are
non-negative (greater than or equal to zero). If a value is negative, skip that
conversion and continue to the next check or return a default value. This
applies to both the Int casting line and the NSNumber casting line in this
function.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clamp negative mobile scroll coordinates before sending mouse position.

mobileClick already guards negative col/row, but mobileScroll forwards them directly to ghostty_surface_mouse_pos. A gesture that starts just outside the rendered grid can therefore report an invalid cell to alt-screen mouse handling and drop or misplace the wheel event.

Suggested fix

-        let posX = (Double(col) + 0.5) * cellWidthPt
-        let posY = (Double(row) + 0.5) * cellHeightPt
+        let clampedCol = max(0, col)
+        let clampedRow = max(0, row)
+        let posX = (Double(clampedCol) + 0.5) * cellWidthPt
+        let posY = (Double(clampedRow) + 0.5) * cellHeightPt

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface`+Mobile.swift
around lines 15 - 27, The mobileScroll function does not validate that col and
row parameters are non-negative before calculating positions and sending them to
ghostty_surface_mouse_pos, unlike mobileClick which guards against negative
values. Add a guard statement early in the mobileScroll function to ensure both
col >= 0 and row >= 0, returning early if either condition fails, to prevent
negative coordinates from being forwarded to the ghostty surface mouse position
handler.

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | 🏗️ Heavy lift

Split this lifecycle extension before it grows further.

This new production file is already 900+ lines and now combines bootstrap-window management, liveness quarantine, teardown/hibernation, view attachment, Claude shim installation, and runtime/environment construction. That is past the repo’s hard review threshold for production Swift files; at minimum, createSurface/environment assembly and teardown/attachment should move into separate files. As per coding guidelines, "Flag Swift production files that exceed 400 lines without a clear single responsibility, or exceed 800 lines even with mostly coherent responsibility."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface`+RuntimeLifecycle.swift
around lines 13 - 919, The TerminalSurface+RuntimeLifecycle.swift extension file
exceeds 900 lines and violates the repository's coding guidelines by combining
multiple distinct responsibilities: bootstrap-window management, liveness
quarantine, teardown/hibernation, view attachment, Claude shim installation, and
runtime/environment construction. Split this file into separate, focused
extensions following the repository's guidance that Swift production files
should not exceed 800 lines. At minimum, move the createSurface method and all
related environment assembly logic (setManagedEnvironmentValue, environment
variable setup, command/working directory resolution) into one new extension
file (e.g., TerminalSurface+SurfaceCreation.swift), and move the
teardown-related methods (teardownSurface,
suspendRuntimeSurfaceForAgentHibernation, closeHeadlessStartupWindowIfNeeded)
and attachment logic (attachToView, attachedView management) into another
extension file (e.g., TerminalSurface+Teardown.swift or
TerminalSurface+Attachment.swift). Ensure each resulting file has a clear,
single primary responsibility and remains under 800 lines.

Source: Coding guidelines

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Keep forceRefresh free of debug formatting/logging.

This method is a per-keystroke hot path in this repo. The new DEBUG block adds string construction and a debug log call on every invocation, which is exactly the kind of work the typing-latency rule is trying to keep out of forceRefresh.

As per coding guidelines, TerminalSurface.forceRefresh() is called on every keystroke, so do not add allocations, file I/O, or formatting there.

Also applies to: 305-321

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface`+Sizing.swift
around lines 272 - 285, Remove the DEBUG block containing string construction
and the logDebugEvent call from the forceRefresh method because this method is a
per-keystroke hot path and adding string formatting and logging violates the
typing-latency coding guidelines. Delete the entire if DEBUG section from
forceRefresh and apply the same fix to any other similar debug logging blocks in
this file that have been added to hot-path methods.

Source: Coding guidelines

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Reapply the display ID to the reacquired surface.

The comment above already documents that view.forceRefreshSurface() can invalidate and recreate the runtime surface. In that case, ghostty_surface_set_display_id only updates currentSurface, while the surface reacquired before ghostty_surface_refresh never gets the topology fix.

Suggested fix

         guard let surface = liveSurfaceForGhosttyAccess(reason: refreshReason) else {
             return
         }
+        if let displayID,
+           displayID != 0 {
+            ghostty_surface_set_display_id(surface, displayID)
+        }
         ghostty_surface_refresh(surface)

Also applies to: 323-326

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/CmuxTerminal/Sources/CmuxTerminal/Surface/TerminalSurface`+Sizing.swift
around lines 312 - 315, The display ID is being set on currentSurface after a
potential surface recreation via view.forceRefreshSurface(), but when the
surface is invalidated and recreated, the reacquired surface never receives the
display ID topology fix. Apply the display ID setting to the newly reacquired
surface immediately after it is obtained, before any subsequent operations like
ghostty_surface_refresh. This fix needs to be applied at both locations where
surfaces are reacquired in TerminalSurface+Sizing.swift (at lines 312-315 and
lines 323-326).

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use the override-aware directory resolver for config-path discovery.

On Line 211, cmuxConfigPaths only reads FileManager.urls(...).first, which can skip CFFIXED_USER_HOME/fallback candidates already standardized by CmuxApplicationSupportDirectories.userDirectories(...). This can load the wrong effective config set in sandbox/test override scenarios.

🔧 Suggested fix

     private static func cmuxConfigPaths(
         fileManager: FileManager = .default,
-        currentBundleIdentifier: String? = Bundle.main.bundleIdentifier
+        currentBundleIdentifier: String? = Bundle.main.bundleIdentifier,
+        environment: [String: String] = ProcessInfo.processInfo.environment
     ) -> [String] {
-        guard let appSupport = fileManager.urls(for: .applicationSupportDirectory, in: .userDomainMask).first else {
-            return []
-        }
-
-        return CmuxGhosttyConfigPathResolver.loadConfigURLs(
-            currentBundleIdentifier: currentBundleIdentifier,
-            appSupportDirectory: appSupport,
-            fileManager: fileManager
-        ).map(\.path)
+        var paths: [String] = []
+        var seen = Set<String>()
+        for appSupport in CmuxApplicationSupportDirectories.userDirectories(
+            environment: environment,
+            fileManager: fileManager
+        ) {
+            for url in CmuxGhosttyConfigPathResolver.loadConfigURLs(
+                currentBundleIdentifier: currentBundleIdentifier,
+                appSupportDirectory: appSupport,
+                fileManager: fileManager
+            ) where seen.insert(url.path).inserted {
+                paths.append(url.path)
+            }
+        }
+        return paths
     }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/Config/GhosttyConfig.swift`
around lines 207 - 220, The cmuxConfigPaths function currently uses
fileManager.urls(...).first which only retrieves a single application support
directory, ignoring CFFIXED_USER_HOME overrides and fallback candidates that are
standardized in CmuxApplicationSupportDirectories.userDirectories(...). Replace
the guard statement that retrieves appSupport using fileManager.urls with a call
to CmuxApplicationSupportDirectories.userDirectories(...), then update the
CmuxGhosttyConfigPathResolver.loadConfigURLs call to iterate through all
resolved directories instead of just a single appSupport directory, ensuring
proper handling of sandbox and test override scenarios.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Clear stale sidebar tint defaults when sidebar-background is removed.

On Line 246, the early-return branch preserves previously stored sidebarTintHex* keys. If a user deletes sidebar-background, stale tint values can continue to drive sidebar rendering.

🔧 Suggested fix

     public func applySidebarAppearanceToUserDefaults() {
         guard rawSidebarBackground != nil else {
+            let defaults = UserDefaults.standard
+            defaults.removeObject(forKey: "sidebarTintHexLight")
+            defaults.removeObject(forKey: "sidebarTintHexDark")
+            defaults.removeObject(forKey: "sidebarTintHex")
             if let opacity = sidebarTintOpacity {
-                UserDefaults.standard.set(opacity, forKey: "sidebarTintOpacity")
+                defaults.set(opacity, forKey: "sidebarTintOpacity")
+            } else {
+                defaults.removeObject(forKey: "sidebarTintOpacity")
             }
             return
         }

Also applies to: 255-269

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/CmuxTerminalCore/Sources/CmuxTerminalCore/Config/GhosttyConfig.swift`
around lines 246 - 251, When rawSidebarBackground is nil in the guard statement
at line 246-251 of GhosttyConfig.swift, stale sidebarTintHex* keys remain in
UserDefaults and continue to affect sidebar rendering. In the early-return
branch where rawSidebarBackground is nil, add code to remove the stale sidebar
tint defaults (the sidebarTintHex* keys) from UserDefaults in addition to the
existing sidebarTintOpacity handling. This same cleanup logic should also be
applied at the corresponding location mentioned around lines 255-269 to ensure
consistency across all cases where sidebar-background is removed or cleared.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

In Swift 6, what happens when UInt(windowNumber)is called with a negativeInt value?

💡 Result:

In Swift 6, calling the initializer UInt(windowNumber) with a negative Int value will trigger a runtime error (a trap), causing your program to crash [1][2][3]. The standard init(_:) initializer for integer conversion requires that the value being converted is representable within the destination type [4]. Because UInt cannot represent negative numbers, passing a negative Int violates this requirement, resulting in a fatal runtime error [1][4][3]. If you need to handle potential negative values without crashing, consider using one of the following alternatives: 1. Use init?(exactly:): This failable initializer returns nil if the value cannot be represented in the destination type (e.g., if it is negative) [1][5]. let unsignedValue = UInt(exactly: windowNumber) // returns nil if windowNumber < 0 2. Use init(bitPattern:): If you specifically intend to reinterpret the underlying bits of the negative integer as an unsigned value (ignoring the numerical value), use this initializer [3]. This will not crash, but it will result in a large, positive UInt value based on the two's complement representation of the input [6][3]. let bitPatternValue = UInt(bitPattern: windowNumber) 3. Use init(clamping:): This initializer constrains the value to the destination type's representable range [1]. For a negative input converted to UInt, it will clamp the result to 0 [1]. let clampedValue = UInt(clamping: windowNumber) // returns 0 if windowNumber < 0

Citations:

• 1: https://srk1nn.medium.com/crash-during-int-to-uint-converting-swift-cb23f73b6bd8
• 2: https://forums.swift.org/t/prevent-using-integer-initializers-that-can-generate-runtime-errors/75467
• 3: https://docs.syntblaze.com/swift/numeric-types/uint
• 4: https://github.com/apple/swift/blob/main/stdlib/public/core/Integers.swift
• 5: https://github.com/swiftlang/swift-evolution/blob/main/proposals/0080-failable-numeric-initializers.md
• 6: https://psychminds.org/swift_documentation/developer.apple.com/documentation/swift/binaryinteger

---

🏁 Script executed:

cd /tmp && find . -type f -name "*.swift" 2>/dev/null | head -1 && cd -

Repository: manaflow-ai/cmux

Length of output: 79

---

🏁 Script executed:

# Locate the file being reviewed
fd "CompositorBlurController.swift" --type f

Repository: manaflow-ai/cmux

Length of output: 153

---

🏁 Script executed:

# Check the full CompositorBlurController to understand its public API surface
cat -n Packages/CmuxWorkspaceWindow/Sources/CmuxWorkspaceWindow/Blur/CompositorBlurController.swift

Repository: manaflow-ai/cmux

Length of output: 2507

---

🏁 Script executed:

# Search for resetBackgroundBlur callsites
rg "resetBackgroundBlur" --type swift

Repository: manaflow-ai/cmux

Length of output: 691

---

🏁 Script executed:

# Check how windowNumber is typically obtained in this codebase
rg "windowNumber" --type swift -B 2 -A 2 | head -40

Repository: manaflow-ai/cmux

Length of output: 2421

---

Guard negative window numbers before converting to UInt.

The public resetBackgroundBlur(windowNumber:) API accepts a raw Int, but UInt(windowNumber) crashes with a fatal runtime error on negative inputs. All current callsites safely pass NSWindow.windowNumber (which is positive for valid windows), but the API boundary should enforce this contract rather than rely on caller discipline. Either reject negatives with an early guard or tighten the signature to a nonnegative type.

Suggested fix

     public func resetBackgroundBlur(windowNumber: Int) {
+        guard windowNumber >= 0 else { return }
         _ = cmuxCGSSetWindowBackgroundBlurRadius(
             cmuxCGSDefaultConnectionForThread(),
             UInt(windowNumber),
             0
         )
     }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/CmuxWorkspaceWindow/Sources/CmuxWorkspaceWindow/Blur/CompositorBlurController.swift`
around lines 40 - 45, The resetBackgroundBlur(windowNumber:) function accepts an
Int parameter and directly converts it to UInt without validation, which will
cause a fatal runtime error if a negative value is passed. Add a guard statement
at the beginning of the function to verify that windowNumber is non-negative
(greater than or equal to 0), and either return early or throw an error if the
check fails. This ensures the API enforces its contract at the boundary rather
than relying on callers to only pass valid positive window numbers.