fix(macos): System tray icon disappears when restarting Sunshine

[eduardomozart]

Description

This PR fixes an issue on macOS where restarting Sunshine (e.g. from the system tray or Web UI) causes the system tray icon to completely disappear for the newly restarted instance.

macOS WindowServer strictly associates GUI state (including the tray icon and activation policies) with the Process ID (PID). Sunshine previously used execv() to restart itself. execv() replaces the process image but retains the exact same PID. When the new instance starts, WindowServer retains the stale state of the old process and silently refuses to initialize the new system tray icon.

1. execv with an artificial delay: We initially tried passing an environment variable (SUNSHINE_IS_RESTARTING) and delaying the startup of the new instance by 500ms to give the OS time to clean up. Result: Failed. Since the PID remains identical, a delay does not clear WindowServer's cache.
2. NSTask / fork (Fire and Forget): We tried replacing execv with an NSTask launch (which forks a new process and yields a fresh PID), then letting the original parent process exit immediately. Result: This successfully fixed the system tray icon! However, it severely broke the terminal experience. Because the parent process exited immediately, the shell (zsh/bash) reclaimed the terminal foreground. The new Sunshine instance continued running in the background, dumping logs over the user's shell prompt, and completely breaking Ctrl+C termination.

To satisfy both WindowServer (which demands a new PID) and the user's shell (which demands the original process stays alive to maintain terminal control), we implemented a Supervisor Pattern in src/platform/macos/misc.mm:

1. The parent process forks a child and calls execv on the new Sunshine instance. The child gets a completely fresh PID, allowing the system tray icon to initialize perfectly.
2. The child places itself in a new process group (setpgid(0,0)).
3. The parent process does not exit. Instead, it acts as a transparent supervisor, blocking on waitpid(). Because the parent stays alive, the shell never reclaims the terminal, preventing logs from interleaving with the shell prompt.
4. The parent catches termination signals (SIGINT, SIGTERM, SIGHUP) and forwards them directly to the child. This means Ctrl+C in the terminal gracefully kills the new instance.

Screenshot

Gravacao.de.Tela.2026-08-14.as.18.15.43.mov

Issues Fixed or Closed

• Closes macOS: System tray icon disappears when restarting Sunshine #5503

Roadmap Issues

Type of Change

• feat: New feature (non-breaking change which adds functionality)
• fix: Bug fix (non-breaking change which fixes an issue)
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
• refactor: Code change that neither fixes a bug nor adds a feature
• perf: Code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit
• BREAKING CHANGE: Introduces a breaking change (can be combined with any type above)

Checklist

• Code follows the style guidelines of this project
• Code has been self-reviewed
• Code has been commented, particularly in hard-to-understand areas
• Code docstring/documentation-blocks for new or existing methods/components have been added or updated
• Unit tests have been added or updated for any new or modified functionality

AI Usage

See our AI usage policy.

• None: No AI tools were used in creating this PR
• Light: AI provided minor assistance (formatting, simple suggestions)
• Moderate: AI helped with code generation or debugging specific parts
• Heavy: AI generated most or all of the code changes

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud