feat(cli): enable notifications cross-platform via terminal bell fallback

[genneth]

Summary

• Remove the macOS-only (process.platform === 'darwin') restriction from the notification system
• The BEL fallback was already implemented but unreachable on non-macOS platforms
• On terminals supporting OSC 9 (iTerm2, WezTerm, Ghostty, Kitty), rich notifications are emitted; on all others (including Windows Terminal), the terminal bell is used

Details

The notification system had two darwin gates:

1. isNotificationsEnabled() — prevented the setting from being active on non-macOS
2. notifyViaTerminal() — early-returned on non-macOS even if called

Meanwhile, emitOsc9Notification() already had a working BEL fallback for terminals without OSC 9 support, and supportsOsc9Notifications() already correctly returned false for Windows Terminal (via the WT_SESSION env var check). Removing the platform restriction lets the existing fallback path work cross-platform.

Also fixes two OSC 9 tests that failed when run inside Windows Terminal because WT_SESSION was set in the environment, causing supportsOsc9Notifications() to return false regardless of the stubbed TERM_PROGRAM.

Related Issues

Fixes #21617

How to Validate

1. Enable notifications: set general.enableNotifications: true in settings.json
2. On a non-macOS platform (Windows/Linux), start a session and switch away from the terminal
3. Wait for session complete or action-required event
4. Terminal should flash/beep via BEL character

Pre-Merge Checklist

• Updated documentation (removed "macOS only" from docs and setting description)
• Updated tests (inverted non-macOS test expectation, fixed OSC 9 tests for Windows Terminal)
• Validated on macOS (npm run)
• Validated on Windows (npm run)
• Validated on Linux (npm run)

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the CLI's notification capabilities by extending them beyond macOS to a truly cross-platform experience. It ensures that users on Windows and Linux can also receive run-event notifications, leveraging either rich OSC 9 notifications where supported or falling back to the terminal bell for broader compatibility. This change makes the notification feature more inclusive and functional across different operating systems.

Highlights

• Cross-Platform Notifications: Removed the macOS-only restriction from the notification system, enabling notifications on non-macOS platforms.
• Terminal Bell Fallback: The existing terminal bell (BEL) fallback mechanism is now reachable and utilized on non-macOS platforms when rich OSC 9 notifications are not supported.
• Test Fixes: Fixed two OSC 9 tests that were failing in Windows Terminal environments due to the WT_SESSION environment variable interfering with supportsOsc9Notifications().

Changelog

• docs/cli/notifications.md
  • Removed the statement indicating macOS-only support for system notifications.
  • Updated the description of terminal support to explicitly list iTerm2, WezTerm, Ghostty, and Kitty as supporting OSC 9.
  • Clarified that the fallback mechanism uses a 'terminal bell (BEL)' instead of a 'system alert sound'.
• docs/cli/settings.md
  • Removed the 'Currently macOS only.' restriction from the description of the general.enableNotifications setting.
• docs/reference/configuration.md
  • Removed the 'Currently macOS only.' restriction from the description of the general.enableNotifications configuration option.
• packages/cli/src/config/settingsSchema.ts
  • Updated the description for the general.enableNotifications setting in the schema to remove the macOS-only text.
• packages/cli/src/utils/terminalNotifications.test.ts
  • Renamed a test case from 'returns false without writing on non-macOS platforms' to 'emits notification on non-macOS platforms'.
  • Modified assertions in the non-macOS test to expect notifications to be shown and writeToStdout to be called.
  • Added vi.stubEnv('WT_SESSION', ''); to OSC 9 tests to ensure correct behavior when run in Windows Terminal environments.
• packages/cli/src/utils/terminalNotifications.ts
  • Removed the process.platform === 'darwin' check from the isNotificationsEnabled function, allowing notifications to be enabled on any platform.
  • Removed the process.platform !== 'darwin' early return check from the notifyViaTerminal function, enabling the notification logic for all platforms.

Activity

• Updated documentation to reflect cross-platform notification support, removing all 'macOS only' mentions.
• Updated tests to correctly validate cross-platform notification behavior and fixed specific OSC 9 test failures in Windows Terminal.
• Validated the changes on Windows using npm run.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request successfully enables cross-platform notifications by removing macOS-specific platform checks, allowing the existing terminal bell (BEL) fallback to function on all operating systems. The changes to the core logic, tests, and documentation are correct and well-aligned with this goal. I have one high-severity suggestion regarding a legacy setting that has become misleading as a result of this change. Based on our rules, this setting should be removed entirely rather than deprecated, which will improve configuration clarity and maintainability for users on all platforms.

[genneth]

@Adib234 -- sorry, the PR became unmergeable to main so I rebased, but I think that caused the CI to stall. Could you kick it?

[Adib234]

I can kick off the workflow but please address the changes not relevant to the PR

[genneth]

Ah -- didn't realise something touched the CONTRIBUTING.md file. Reverted.

[SandyTao520]

tests failed, could you please fix them?

[genneth]

Will do but am away for the rest of the month... Okay to wait?

[SandyTao520]

@genneth Might be too long, do you mind if we fix it for you and merge?

[genneth]

Of course -- no preciousness here about the PR!