Skip to content

fix(desktop): prevent macOS fullscreen ghost windows - #12126

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
Skymore:fix/mac-fullscreen-exit-ghost
Sep 22, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
Skymore:fix/mac-fullscreen-exit-ghost

Conversation

@Skymore

@Skymore Skymore commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

On macOS, closing Kiro Crew around a native fullscreen transition can leave an immovable full-display copy of the window over the desktop. The copy has no traffic lights, cannot be resized or moved, and can remain after the real application window has hidden.

Why it matters

The abandoned window snapshot covers other applications and leaves no usable Kiro Crew window to dismiss. Clamshell and multi-display setups can encounter the failure during ordinary fullscreen, display, sleep, and tray-close transitions.

What changed (motivation → approach → change)

AppKit can report a fullscreen transition as complete before its Space animation is actually quiet. Issuing the reverse transition during that interval abandons AppKit's snapshot overlay, while hiding only the real window leaves the overlay onscreen.

The macOS tray-close path waits for a bounded quiet period before leaving fullscreen, hides the application so any AppKit-owned overlay is ordered out, and reasserts that hide after the transition tail. If an exit is already in flight, the close attaches to its terminal event instead of issuing a second fullscreen toggle; the same protection remains active through AppKit's short post-terminal order-in tail. A bounded watchdog detects stalled or reversed fullscreen transitions and performs the application-level repair without re-showing a window the user dismissed.

The website/electron desktop shell keeps close intent live across independent timeout paths, and every explicit reveal path restores the application before its window: Dock activation, tray actions, the global summon shortcut, settings and connection actions, and gateway errors requiring user input. A needs-user reveal cancels both its target window and any distinct main-window app-hide owner before app.show(), so a pending reassert cannot hide a connection-window dialog again. Windowed closes and non-macOS behavior remain window-level. The Electron package manifest includes the new watchdog module; no dependency or lockfile changed. Desktop documentation records the transition and recovery contract.

Backwards compatibility

Compatible: existing windowed-close behavior, fullscreen preferences, gateway sessions, and Windows/Linux behavior are unchanged. The macOS change only delays a fullscreen tray-close while AppKit motion settles and makes hidden-application restores explicit.

Tests

  • Electron node:test suite: 2,044 passed, 3 skipped (on the current main base). New coverage exercises quiet-time gating, an already-active user exit, the post-terminal order-in tail, terminal-event loss, reversed transitions, listener and timer failures, duplicate closes, durable close intent, cross-window reassert cancellation, application-level repair, and every restore entry point.
  • Frontend related suite selected by the repository gate: 8,026 tests across 269 files passed.
  • The remaining 48 executable prepare-pr profile gates passed, including TypeScript, ESLint, mypy, flake8, documentation, i18n, duplication, bundle-size, chunk-cycle, and packaging-manifest checks.
  • The focused fullscreen transition and tray-close suite passes 68 tests; the original state-machine set passed in 30 consecutive runs.
  • Local GPT 5.6 and Opus 4.8 reviews ran from the repository's extracted CI contracts before publication; reviewer findings are validated against dedicated regression tests before each revision.

The restricted local host cannot produce a meaningful verdict for the profile's cross-surface backend run: 42,011 tests passed while 89 host/sandbox-dependent tests failed on unavailable systemd, process, sensitive-path, and installer facilities. The PR's standard CI runners remain authoritative for that matrix.

Manual verification

A patched universal build using Electron 43.2.0 was exercised on the affected macOS multi-display machine. Thirty real window.close() cycles landed at randomized points 100–849 ms into fullscreen entry; all 30 hid correctly and left zero snapshot overlays. A second 30-cycle run first initiated fullscreen exit and then closed at randomized points 0–850 ms later, covering the active exit and post-terminal tail; all 30 hid correctly and left zero overlays. The unguarded enter-transition implementation previously left overlays in 7 of 20 cycles and completed only 10 of 20 hides.

The application was then restored successfully through macOS app activation, the tray Show Kiro Crew action, the tray New Connection Window… action, and the global summon shortcut. The packaged asar hash matched the tested source bundle, and the universal shell contained both arm64 and x86_64 slices.

Screenshots / video

Why no screenshot: Healthy rendered pixels and controls are unchanged. The fix changes native AppKit transition ordering and is verified by the absence of an abandoned system snapshot under repeated close cycles.

Related Issues

Fixes #10159

Pattern harvest

Rule candidate: review-prompt

Pattern: A macOS fullscreen completion event may precede the end of AppKit's Space animation; code that reverses the transition must use an independent quiet-state guard and preserve application-level show/hide symmetry.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@Skymore
Skymore requested review from a team September 20, 2026 00:25
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 20, 2026
@Skymore

Skymore commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

Intent: Prevent macOS native-fullscreen transitions from leaving an immovable AppKit snapshot over the desktop, while keeping every explicit restore path usable after an application-level tray hide.
Not a goal: Redesign general window management, change non-macOS close behavior, or alter the rendered dashboard UI.

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of df5eab6bc91a196b4bd1304e063dba6473a15af5 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify on hardware that a fullscreen main-window close with a secondary connection window open hides both and one Dock/tray click restores them.

[DESIGN-REVIEWED] df5eab6

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed df5eab6bc91a196b4bd1304e063dba6473a15af5 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] df5eab6

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of df5eab6bc91a196b4bd1304e063dba6473a15af5 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify on a multi-window session that a fullscreen main-window tray-close hiding every open connection window is acceptable — the description never states that consequence.

Not justified as shipped

  • Item 3 — undeclared: app.hide() "orders out every window the process owns", so closing the fullscreen main window now hides connection windows the user did not close; the description only says "Windowed closes and non-macOS behavior remain window-level".

What this change ships

Inventory (10 items) — 9 justified

Intent: FIX — stop macOS tray-closes around fullscreen transitions from leaving an immovable AppKit snapshot overlay (Fixes #10159, with measured reproductions).

  1. Fullscreen tray-close waits for ~700ms of AppKit quiet before leaving fullscreen — justified
  2. The fullscreen close hides the application, not the window, and re-asserts the hide once — justified
  3. Closing the fullscreen main window also hides other open Kiro Crew windows — undeclared (consequence of item 2; window-level hide was tried and shown to strand the overlay)
  4. A watchdog spots stalled or reversed transitions and repairs via an app hide/show cycle — justified
  5. Every user reveal path (Dock, tray, hotkey, modals, gateway dialogs) unhides the app first — justified
  6. A duplicate close during a pending fullscreen hide is absorbed — justified
  7. Revealing a needs-user connection window disarms the main window's pending app-hide — justified
  8. Fullscreen transitions, stalls and repairs are journaled to gateway-launch.log — justified
  9. Tray "Show" routes through the existing showMainWindow helper (deletes a second spelling) — justified
  10. desktop-app.md documents the transition/recovery contract in the same commit — justified

Rewritten test pins (backstop win.hide() → app.hide()) reverse a prior decision with evidence: the linked issue, the measured 7-of-20 overlay reproduction, and the pins' replacements state why the old behavior was the bug. New exports have real consumers in window-lifecycle.js; the timing constants are consumed only by tests (internal file, freely deletable — not flagged).

[FIRST-PRINCIPLES-REVIEWED] df5eab6

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed df5eab6bc91a196b4bd1304e063dba6473a15af5 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] df5eab6

@Skymore
Skymore force-pushed the fix/mac-fullscreen-exit-ghost branch from 3de929b to 3fc2ce3 Compare September 20, 2026 01:26
@Skymore

Skymore commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

span=4224e4e09b96
self-added: yes
mechanism: carry the active exit target and post-terminal settle clock into tray-close

fixed
hideToTray now attaches to an already-active fullscreen exit without issuing another toggle, and keeps the known 300 ms post-terminal order-in tail on the app-level hide path.
Regression coverage fails on the reviewed head and passes on 3fc2ce34a; 68 focused tests, 1,999 Electron tests, and 30 randomized macOS exit-then-close cycles passed with zero overlays.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 20, 2026
@Skymore
Skymore force-pushed the fix/mac-fullscreen-exit-ghost branch from 3fc2ce3 to c2ba31f Compare September 20, 2026 02:17
@Skymore

Skymore commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

span=538694776b8b
self-added: yes
mechanism: cancel every app-hide owner before a needs-user application reveal

fixed
revealForUserDecision now cancels a live distinct main window before canceling the target and calling app.show(), so a main-window reassert cannot hide a secondary gateway dialog.
The regression test drives the real hideToTray reassert timer and proves draining it after the reveal leaves the app visible; c2ba31f22 passes 169 neighboring tests and 2,002 Electron tests.

@Skymore

Skymore commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

All code-related checks are green on c2ba31f22. Two infrastructure reruns need repository permissions:

  • Windows shard 7 failed only in two untouched test_auto_research.py cases with TimeoutError/CancelledError after a 14m38s loaded run; 13,263 tests in the shard passed. Please rerun the failed job.
  • Fork Opus 4.8 Review failed before model execution because the runner could not download Claude Code from claude.ai (curl: (7) on all three attempts). Please rerun this workflow after egress recovers.

The PR author token has read permission on the upstream repository, so GitHub refuses both reruns with “Must have admin rights to Repository.”

@Skymore
Skymore force-pushed the fix/mac-fullscreen-exit-ghost branch from c2ba31f to bf73340 Compare September 20, 2026 03:50
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 20, 2026
@Skymore
Skymore force-pushed the fix/mac-fullscreen-exit-ghost branch from bf73340 to b0e8c8b Compare September 20, 2026 05:32
@Skymore

Skymore commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

Pushed b0e8c8b5d (rebased onto main @ 2b7d37811, desktop commit patch-identical). Two of the three red items on the previous head have a cause outside this PR's desktop change; both are now addressed at their source:

  • Backend Tests (Windows) (4) failed in test/test_sel.py::TestThreadSafety::test_concurrent_writes (assert 39 == 40, with PermissionError: [Errno 13] from sel.py:_chain_lock at the sidecar prime write). Two threads both find the fresh trust/security_events.lock empty; the first to prime it also takes the byte-range lock, and Windows then refuses the second thread's prime with EACCES, so its event is dropped. A second commit on this PR makes a refused prime re-check the sidecar size and fail only when it is still empty, with two regression tests (the positive one fails on the unfixed code).
  • Opus 4.8 Review posts review incomplete because the fork lane's harden-runner egress allowlist has no claude.ai / downloads.claude.ai, so claude-code-action cannot install Claude Code (domain not allowed: claude.ai, curl: (7) on all three attempts, run 35487678930). No fork Opus review has completed since the harden-runner bump on 2026-09-18 21:37Z. The fix is ci: allow the Claude Code installer hosts in the fork review lanes #12201; it cannot take effect from inside this PR because workflow_run lanes execute main's copy of the yaml, so this lane will stay review incomplete until ci: allow the Claude Code installer hosts in the fork review lanes #12201 (or an equivalent) merges and this PR is re-run.
  • PR Readiness aggregates the two above.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 20, 2026
@Skymore
Skymore force-pushed the fix/mac-fullscreen-exit-ghost branch from b0e8c8b to 6e1b1f1 Compare September 20, 2026 06:09
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 20, 2026
@Skymore
Skymore force-pushed the fix/mac-fullscreen-exit-ghost branch from 6e1b1f1 to 6c397ff Compare September 20, 2026 06:53
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 20, 2026
Wait for native fullscreen motion to settle before exiting and hide the
application so abandoned AppKit snapshots cannot remain onscreen.

Add bounded recovery for stalled transitions and keep every user-driven
restore path consistent with application-level hiding.
@Skymore
Skymore force-pushed the fix/mac-fullscreen-exit-ghost branch from 6c397ff to df5eab6 Compare September 22, 2026 07:49
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — ✅ PASS

UX-level review of df5eab6bc91a196b4bd1304e063dba6473a15af5 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Verify on a Mac that a fullscreen tray-close's app-level hide doesn't strand a second connection window the user never closed — one Dock click must restore it.

[UX-REVIEWED] df5eab6

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 22, 2026
@iamwhatever
iamwhatever enabled auto-merge (squash) September 22, 2026 17:23
@iamwhatever
iamwhatever merged commit ef01746 into kirodotdev:main Sep 22, 2026
97 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 22, 2026
@buluoray

Copy link
Copy Markdown
Contributor

Reviewed at df5eab6 with three independent lanes: a reveal-path sweep, a state-machine/timing audit, and a 10-mutation falsification run against the new tests. The core fix is well-engineered and the test discipline is genuinely unusual — I want to be specific about that before the one ask.

Withholding approval on one verified gap

crew-companion/index.js:274 reveals the main dashboard window with a bare win.show() and no app.show().

initCrewCompanion is handed getDashboardWindow: () => windows.focusedDashboardWindow() || null (main.js:574), so openDashboardSession operates on the same window app.hide() just hid:

if (win.isMinimized()) win.restore();
win.show();
win.focus();
...
if (!ready) return false;
if (slotKey) wc.send("navigate", `/chat?sid=…`);
return true;      // <- overlay dismisses the sticky approval on true

Reached from the pet overlay via crew-companion:open-session (pet-preload.js:122 → index.js:405). After a fullscreen close-to-tray, win.show() on a hidden app is ignored, but ready is true (the SPA was loaded, merely hidden) so the function still returns true — the overlay dismisses the sticky approval notification. The user loses their only pointer back to a gateway the approval is still blocking on, and the window never appeared.

This is the exact failure class the PR fixes one file over, with the reasoning already written down at ipc-registrar.js:494:

Reveal through the façade so a pending fullscreen/tray hide is cancelled before restore/show/focus; otherwise the click can appear to work and then immediately hide the window again.

showMainWindow is already exported (window-lifecycle.js:2139), so the fix is to pass a reveal callback into initCrewCompanion and call it instead of win.show() — or an app.show() on darwin ahead of the existing call.

Wider, same cause: grep -rn "app\.show\|unhideApp" mochi/ crew-companion/ returns no call site at all — only a comment at mochi/index.js:1030 which already names this coupling ("app.hide() would take the dashboard with it"). Every reveal path in those two trees predates app.hide() existing in the shell. The two I would prioritise after the one above are the global shortcuts — mochi/panelWindow.js:397 (⌘⇧M, the tip the composer advertises) and mochi/snipWindow.js:107 (⌘⇧X) — because a global shortcut fires precisely while the app is hidden and unfocused.

I could not verify on a real macOS whether [NSApp hide:] orders out the alwaysOnTop + setVisibleOnAllWorkspaces(…, visibleOnFullScreen: true) panels (crew-companion/panelWindow.js:120,131), and that decides which way the overlay side fails, not whether it does: if the panels survive the hide, their reveals are ignored as above; if they do not, the pet vanishes on a fullscreen tray-close where win.hide() previously left it alone, and the reconcile showInactive() paths have no app.show() to bring it back. The openDashboardSession finding does not depend on that question — its target is a regular window.

crew-companion/ is outside the diff, which is exactly why all five lanes passed it: the line reviewers' FIX BAR excludes untouched files. The hazard is nonetheless created here, since before this change a bare win.show() was sufficient.

What I verified as sound

Mutation falsification — 10/10 caught, 0 survived. Every guard is load-bearing and pinned. Baseline 105 pass / 0 fail confirmed before and after each mutation, files restored byte-identical, tree clean.

Mutation Caught by
quiet-time gate removed (afterQuiet() unconditional) waits for AppKit to be quiet before issuing the exit +2
fullscreen hide reverted to hideNow() hides the app, not the window, on the fullscreen path +16
reassertHide() made a no-op re-asserts the app hide once AppKit is certainly quiet +2
pendingReasserts dropped from cancelPendingTrayHide still disarms the re-asserted hide when the exit could not be started +3
shouldKeepAppHidden → always false keeps the close intent after both hide timers drain until a show clears it +1
double-close guard removed does not arm a second hide for a repeated close while one is pending
exitInFlight → always false attaches to an in-flight user exit without requesting another exit +2
onAbort reporting deleted reports the abandoned transition when one reverses to the baseline
mustStayHidden() catch → false fails closed when the dynamic close-intent probe throws
!isMac early return removed is a no-op off macOS

State machine. No path where the close gesture visibly does nothing: every deferred path is terminated by leave-full-screen or the backstop, and both actuate a hide. Worst case with quietFor() never clearing is the backstop at 2000 + 700 = 2700ms → settle("stalled") → app.hide(). Every failure branch I walked (win.once throws, setTimer throws in onLeave/whenQuiet, quietFor throws, setFullScreen throws, window destroyed mid-flight) lands on a hide or a safe no-op.

No unreachable-hidden state. createTray() runs unconditionally at main.js:549, before createMainWindow(), and nothing in these paths calls app.dock.hide() or setActivationPolicy("accessory"), so the Dock icon survives app.hide(). Dock activate, tray click/menu, summon hotkey, second-instance and notification click are all independent ways back, and each calls cancelPendingTrayHide first, so none can be undone by the 1s reassert.

exitTail is reachable and correct. lastExitAt is set only in onLeave and reset in onEnter, so exitSettlingFor() is finite only between a leave-full-screen and the next enter. In that window the close correctly neither re-arms the terminal listener nor re-issues setFullScreen, and polls against settleMs with a 2000 + 300 backstop.

Non-macOS is genuinely untouched. fullscreen-transition-watch.js:106 returns the idle object and registers no listeners; hide-to-tray.js:226-228 returns via hideNow() before reading transitionTarget/quietFor/exitSettlingFor; repairStalledFullScreenExit no-ops at :282 and is only called from handlers the idle watch never fires.

Two nits, neither worth a revision on its own

  1. The backstop budget timeoutMs + graceMs (hide-to-tray.js:445) is a single shared 2700ms window, not grace plus a fresh 2000ms for the exit — the backstop is not re-armed when requestExit fires. Correct today (700 ≪ 2000), but the comment at :441-443 ("the budget covers the quiet wait as well as the exit itself") reads as additive and would mislead anyone later raising TRANSITION_QUIET_MS.
  2. In the deferred fullscreen path, a throwing setTimer(onBackstop, …) is swallowed as best-effort at :444-450 on the grounds that the listener is still armed. If that throw coincides with leave-full-screen never arriving, no terminator remains and the window stays visible with deferred latched. Requires setTimeout itself to throw, so not reachable in practice.

Happy to approve as soon as the openDashboardSession reveal goes through the façade — or, if you would rather not grow the diff into crew-companion/, on an explicit follow-up issue covering it plus the two mochi global-shortcut reveals. The ghost-window fix is worth more than the companion dead-end costs; I just do not want the omission to land unrecorded.

@Skymore

Skymore commented Sep 23, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for flagging this. I tested the actual user paths on Electron 43 and macOS 26.

In the merged #12126 build:

  • app.hide() hides both the Dashboard and Mochi.
  • Contrary to the original concern, BrowserWindow.show() and showInactive() implicitly unhide the app on this system.
  • Crew Companion’s Open session, ⌘⇧M, and ⌘⇧X all work. The snip overlay also closes normally with Esc and leaves no hidden fullscreen window.
  • The real side effect is that revealing Mochi or the snip tool can also reveal the Dashboard.

I now have a local follow-up implementation with this behavior:

  1. Fullscreen red-close temporarily hides the entire app to clear the macOS fullscreen overlay.
  2. After cleanup, it hides the Dashboard window first and then restores the app.
  3. Mochi briefly disappears and automatically returns.
  4. The Dashboard remains hidden in the tray, with no ghost window.

The real fullscreen-close path passed 10/10 rounds. Across 8,428 window samples at approximately 157 Hz, neither the Dashboard nor a ghost window appeared. Repeated manual ⌘⇧M and ⌘⇧X tests also behaved correctly.

wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
Wait for native fullscreen motion to settle before exiting and hide the
application so abandoned AppKit snapshots cannot remain onscreen.

Add bounded recovery for stalled transitions and keep every user-driven
restore path consistent with application-level hiding.

Co-authored-by: Rui Tao <ruit@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Kiro Crew leaves a frozen window copy when moved between displays

3 participants