Keep minimized windows in the Dock when the global hotkey reveals cmux

[jacob-carlborg]

Summary

With cmux in the background but not hidden, the system-wide show/hide hotkey pulled minimized windows back out of the Dock along with the on-screen ones. Minimizing a window is an explicit "put this away" that only the user undoes, and other Mac terminals leave those windows alone. After this change the hotkey reveals only on-screen windows, which is what the hidden-application path already did.

showApplicationWindows chose visible || miniaturized for the background branch; it now chooses on-screen windows only (visible && !miniaturized). Minimized windows stay reachable as a last resort: when nothing else can be shown, both the hidden and the background branch fall back to them through miniaturizedTargetsOfLastResort. That fallback is load-bearing — without it the hotkey goes completely inert while every window is minimized, because reveal returns early on an empty target list and never calls activate.

@austinywang diagnosed this first in #10688 and converged on the same shape there before it was closed; both commits here carry his Co-authored-by.

Fixes #9991.

Testing

Two Swift Testing cases added in cmuxTests/MainWindowVisibilityLifecycleTests.swift, both driven through toggleApplicationVisibility with isApplicationActive: { false } and isApplicationHidden: { false } — the state the global hotkey actually fires from:

• backgroundHotkeyLeavesMiniaturizedWindowsInTheDock — a visible window alongside a minimized one. Asserts the application activates, the visible window is made key, and the minimized one is never deminiaturized. This is the reported symptom.
• backgroundHotkeyRestoresMiniaturizedWindowsWhenNothingElseCanBeShown — every window minimized. Asserts the application still activates and both windows are restored, so the first fix cannot be satisfied by dropping minimized windows from the reveal set and leaving the hotkey dead.

The existing testShowApplicationWindowsStillRestoresMiniaturizedWindowsWhenNoHiddenTargetsWereCaptured passes unchanged; it covers the same fallback through showApplicationWindows directly.

python3 scripts/verify-local.py — 17/17 selected checks pass.

./scripts/test-unit.sh -derivedDataPath ~/Library/Developer/Xcode/DerivedData/cmux-hotkeymin-tests build-for-testing — ** TEST BUILD SUCCEEDED ** at both commits.

Test execution is pending in CI: the cmuxTests host is the app itself, and this repo's instructions rule out launching an untagged cmux DEV.app locally, so the red/green receipts come from scripts/run-e2e.sh cmuxTests/MainWindowVisibilityLifecycleTests at the test-only commit and at the fix commit. I'll post both run links here.

Changelog

Fixed: The system-wide show/hide hotkey no longer pulls minimized windows out of the Dock

Proof

No visual change — the behavior is whether a window stays in the Dock. The two added tests are the oracle; a dogfood build can be requested with the dev-build label if a reviewer wants to feel it.

Checklist

• Behavior changes have added or updated tests, or Testing says why not
• UI, settings, menu, schema, help-text or user-facing docs change: localization audited — n/a, no user-facing strings
• New or changed v2 socket method allowlisted for cmux ssh — n/a
• iOS connectivity, auth, lifecycle, workspace action, terminal I/O or mobile RPC contract change — n/a
• User-facing docs updated if needed — n/a
• Reviewed with a subagent before merge, and all bot and human review comments resolved

---

🤖 Generated with Claude Code

https://claude.ai/code/session_012gWLE61zVSnNbkTq5DDjHC

---

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

---

Summary by cubic

Fixes the global show/hide hotkey pulling minimized windows back out of the Dock when cmux is in the background but not hidden. Revealing now targets on-screen windows only. Fixes #9991.

• When every window is minimized, the hotkey still restores minimized windows as a last resort so the reveal never goes inert; this fallback applies to both the hidden-application and background branches.
• Adds three tests covering the visible-plus-minimized, background all-minimized, and hidden-application all-minimized paths.

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

---

Note

Medium Risk
Changes core window-restore logic for the global hotkey path; behavior is well-covered by new tests but affects activation and focus whenever users toggle visibility.

Overview
Fixes the global show/hide hotkey undeminiaturizing windows when cmux is in the background but not hidden. showApplicationWindows now prefers on-screen windows (visible && !miniaturized) instead of treating minimized windows as normal reveal targets.

Minimized windows are restored only via miniaturizedTargetsOfLastResort when nothing else can be shown (hidden app with no captured/dismissed targets, or background with no visible or dismissed windows), so the hotkey still activates instead of no-oping when every window is minimized.

Adds lifecycle tests for the hidden-app fallback and the two background hotkey cases (mixed visible/minimized vs all minimized).

^{Reviewed by Cursor Bugbot for commit 6876194. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes
  • Improved global hotkey window selection when the app is inactive: a visible window is activated without restoring minimized windows. If no visible window is available, minimized windows are restored and the first is selected.
  • When showing a hidden app, previously captured or dismissed windows are prioritized; minimized windows are restored only when no such windows are available.
  • When a hidden app has only a minimized window, it is restored and selected as the active window.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 12802002-f36b-464c-b344-fc5cfc6204bd

📥 Commits

Reviewing files that changed from the base of the PR and between 56a4302 and 6876194.

📒 Files selected for processing (1)

• cmuxTests/MainWindowVisibilityLifecycleTests.swift

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The global hotkey treats visible windows as ordinary reveal targets and leaves miniaturized windows untouched when visible targets exist. It uses miniaturized windows as a fallback when other targets are unavailable.

Changes

Window reveal behavior

Layer / File(s)	Summary
Reveal target selection and regression coverage Sources/App/MainWindowVisibilityController.swift, cmuxTests/MainWindowVisibilityLifecycleTests.swift	The controller excludes miniaturized windows from ordinary visible targets. It prefers dismissed targets before miniaturized windows when the application is not hidden, and uses miniaturized windows as a fallback when other targets are unavailable. Tests cover hidden-app restoration, retaining a miniaturized window when a visible window exists, and restoring all-miniaturized windows.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to 68761

The change is ready for normal CI validation before merging.

🚥 Pre-merge checks | ✅ 24 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (24 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR meets the coding requirements in issue #9991. showApplicationWindows uses visible && !miniaturized for ordinary background targets. It uses miniaturized windows only as a last-resort fallba…
Out of Scope Changes check	✅ Passed	The changes stay within issue #9991. The source change updates global hotkey target selection and preserves activation when all windows are minimized. The added tests directly verify these paths. No u…
Cmux Cloud Persistent Session And Early Input	✅ Passed	The pull request changes only MainWindowVisibilityController.swift and MainWindowVisibilityLifecycleTests.swift. The diff updates window reveal and miniaturized-window tests; it does not change Cloud …
Cmux Swift Actor Isolation	✅ Passed	PASS: The only production change is in MainWindowVisibilityController, which is explicitly @MainActor. The new miniaturizedTargetsOfLastResort helper accesses NSWindow and MainActor-isolated `…
Cmux Swift Blocking Runtime	✅ Passed	The production diff only filters window targets and adds a miniaturized-window fallback. It introduces no semaphore, wait, sleep, delayed dispatch, timer, polling, main-queue sync, or manual lock. The…
Cmux Browser Automation Off-Main	✅ Passed	The pull request changes only MainWindowVisibilityController.swift and its lifecycle tests. The diff contains no browser socket automation commands, WebKit callbacks, worker-router changes, or `proc…
Cmux Expensive Synchronous Load	✅ Passed	The production diff only changes window-target filtering and adds miniaturizedTargetsOfLastResort, which performs an in-memory window-state filter. It adds no agent-history loader, file read, direct…
Cmux Cache Substitution Correctness	✅ Passed	PASS: The production diff changes only in-memory window-target selection in showApplicationWindows. It filters live NSWindow state through windowOperations.isVisible and isMiniaturized, then u…
Cmux No Hacky Sleeps	✅ Passed	The pull request changes only Swift files: Sources/App/MainWindowVisibilityController.swift and cmuxTests/MainWindowVisibilityLifecycleTests.swift. The custom check applies only to non-Swift TypeS…
Cmux Algorithmic Complexity	✅ Passed	PASS. The production diff in Sources/App/MainWindowVisibilityController.swift adds only linear passes over the window list: the visibleTargets filter at lines 316–318 and the `miniaturizedTargetsO…
Cmux Swift Concurrency	✅ Passed	The diff adds only synchronous window-target selection and a synchronous helper. The new tests use synchronous closures under @MainActor. No new DispatchQueue, DispatchGroup, Combine state, comp…
Cmux Swift @Concurrent	✅ Passed	PASS: The pull request changes only synchronous window-selection logic and synchronous tests. The new miniaturizedTargetsOfLastResort(in:) helper is synchronous, and the diff adds no async, `nonis…
Cmux Swift Package Boundaries	✅ Passed	The production diff only changes MainWindowVisibilityController, an @MainActor AppKit controller that operates on NSWindow, application visibility, activation, and deminiaturization. The new hel…
Cmux Swiftpm Lockfiles	✅ Passed	The pull request changes only Sources/App/MainWindowVisibilityController.swift and cmuxTests/MainWindowVisibilityLifecycleTests.swift. It changes no SwiftPM package, Package.swift, `Package.reso…
Cmux Swift Logging	✅ Passed	The production diff changes window-target selection and adds a fallback helper. It does not add or materially change logging. The changed Swift lines contain no print, debugPrint, dump, NSLog,…
Cmux User-Facing Error Privacy	✅ Passed	PASS: The pull request changes window-selection behavior and adds lifecycle tests. It adds no user-facing error, alert, command output, API error body, or recovery text. The only new prose is a develo…
Cmux Full Internationalization	✅ Passed	The PR changes window-selection behavior and adds tests only. The production diff adds no user-facing Swift text, localization keys, string-catalog entries, web messages, metadata, or changelog conten…
Cmux Swiftui State Layout	✅ Passed	PASS. The PR changes only Sources/App/MainWindowVisibilityController.swift and cmuxTests/MainWindowVisibilityLifecycleTests.swift. Both use AppKit; the diff adds window-visibility logic and tests.…
Cmux Architecture Rethink	✅ Passed	PASS. The Swift change is a small local correctness fix in the existing @MainActor MainWindowVisibilityController. It keeps target selection and activation in the existing showApplicationWindows → rev…
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	PASS. The PR changes reveal-target selection in Sources/App/MainWindowVisibilityController.swift; it does not add or materially change a standalone cmux-owned NSWindow, NSPanel, controller, Swif…
Cmux Source Artifacts	✅ Passed	The PR changes only two intentional source-control paths: Sources/App/MainWindowVisibilityController.swift and cmuxTests/MainWindowVisibilityLifecycleTests.swift. The diff contains hand-written ap…
Cmux No Test Or Debug Seam In Production Source	✅ Passed	The production diff only changes window-target selection and adds the private miniaturizedTargetsOfLastResort behavior helper. It adds no test/debug-named member, visibility widening, test-only wrap…
Title check	✅ Passed	The title clearly and concisely describes the main user-visible change: minimized windows remain in the Dock when the global hotkey reveals cmux.
Description check	✅ Passed	The description includes the required Summary, Testing, Changelog, Proof, and Checklist sections. It explains the behavior, documents added tests and verification results, and clearly states that test…

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[teamleaderleo]

Thank you @jacob-carlborg! :D

[github-actions]

Merge receipt for 68761941b2: every check was green at merge (15 verified; 20 skipped by policy). Full suite runs on main after merge.