fix(desktop): improve Windows host lifecycle

[Ivorisnoob]

What Changed

• Add a Windows system tray with Open and Quit actions.
• Hide the desktop window on close while keeping the backend and remote connections running.
• Preserve the existing graceful shutdown path when the user explicitly quits.
• Enable close-to-background only after tray creation succeeds, preventing an inaccessible hidden app.
• Cache the PowerShell-derived Windows shell environment for repeated launches.
• Invalidate the cache after 24 hours or whenever the inherited PATH changes.
• Add focused lifecycle, tray, window-close, and shell-environment tests.
• Document the Windows background behavior in the remote-access guide.

Why

Closing the final T3 Code window on Windows previously exited the entire desktop host. That stopped the backend and disconnected devices using T3 Code remotely.

Windows startup also synchronously repeated expensive PowerShell environment discovery even when the inherited environment had not changed. Local traces showed this adding roughly 3–4 seconds to repeated launches.

This keeps the Windows host available for remote use, provides an explicit way to quit it completely, and avoids repeated environment-discovery work without changing lifecycle behavior on macOS or Linux.

UI Changes

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

Implemented with GPT-5.6-sol through the Codex harness in T3 Code.

---

Note

Medium Risk
Changes Windows quit/close semantics and process lifetime (backend stays up when the window is hidden), which affects remote connections and shutdown; macOS/Linux behavior is largely unchanged aside from test stubs.

Overview
Windows no longer exits when the main window is closed if the system tray is active: closing hides the window and keeps the backend running for remote pairing, while Quit from the tray (or the normal shutdown path) still tears down the app.

A new Windows-only system tray (Open / Quit) is registered at startup; close-to-background is enabled only after the tray is created successfully so users are not left with a hidden app and no way to reopen it. before-quit calls prepareForQuit so updater-driven and explicit quits bypass the hide behavior.

Startup on Windows caches the PowerShell-derived shell environment snapshot under the app state directory (windows-shell-environment.json), reusing it for up to 24 hours or until the inherited PATH changes, avoiding repeated profile probes on warm launches.

Tests cover tray lifecycle, window close vs quit, lifecycle prepareForQuit, and cache reuse; remote-access docs describe the tray behavior.

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

Note

Add Windows system tray support with background mode and shell environment caching

• On Windows, the app now creates a system tray icon (via DesktopTray) with Open and Quit menu actions. Closing the main window hides it rather than quitting while the tray is active.
• DesktopWindow gains setBackgroundModeEnabled and prepareForQuit methods; prepareForQuit is called during before-quit so subsequent closes proceed normally instead of hiding.
• On Windows, shell environment variables from PowerShell are cached to disk (under stateDir) and reused for up to 24 hours when the inherited PATH is unchanged, reducing repeated PowerShell profile loads on each launch.
• User-facing docs in remote-access.md explain the tray behavior and how to fully quit the app.
• Behavioral Change: on Windows, closing the main window no longer quits the app when the tray is active; users must use the tray Quit action to stop the process.

📊 Macroscope summarized c5325cb. 7 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0d4750e7-5808-45f3-88d3-cacde634e904

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

[macroscopeapp]

🟡 Medium shell/DesktopShellEnvironment.ts:446

A failed or timed-out PowerShell probe is cached as a valid snapshot for 24 hours, so subsequent launches skip the probes and permanently miss profile-derived PATH, FNM_DIR, and FNM_MULTISHELL_PATH during that period. runCommandOutput converts failures to "", and readWindowsEnvironment converts that to {}, but line 446 writes those empty or partial results whenever no valid cache was loaded; cache writes must be gated on successful, complete probes rather than only Option.isNone(cached).

🤖 Copy this AI Prompt to have your agent fix this:

In file @apps/desktop/src/shell/DesktopShellEnvironment.ts around line 446:

A failed or timed-out PowerShell probe is cached as a valid snapshot for 24 hours, so subsequent launches skip the probes and permanently miss profile-derived `PATH`, `FNM_DIR`, and `FNM_MULTISHELL_PATH` during that period. `runCommandOutput` converts failures to `""`, and `readWindowsEnvironment` converts that to `{}`, but line 446 writes those empty or partial results whenever no valid cache was loaded; cache writes must be gated on successful, complete probes rather than only `Option.isNone(cached)`.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit c5325cb. Configure here.}

[cursor]

Failed shell probes stay cached

Medium Severity

A cache miss always writes noProfile and profile, including empty objects from timeouts or failed PowerShell probes. The next launches then treat that snapshot as valid for 24 hours while inheritedPath is unchanged, so profile PATH and FNM_* hydration stay skipped after a bad first discovery.

 

^{Reviewed by Cursor Bugbot for commit c5325cb. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a new Windows system tray feature with close-to-background behavior and shell environment caching - significant new runtime capability beyond a simple fix. Additionally, two medium-severity findings about caching failed PowerShell probes remain unresolved.

Not approved because:

• 1 blocking correctness issue found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[Ivorisnoob]

Superseded by #7492 for the Windows startup performance fix and #7493 for the Windows tray/background feature. The two concerns now have independent branches, commits, tests, and review histories.