docs: propose terminal-owned macOS notifications

[anujb-msft]

Summary

Document the macOS notification click problem and add an original, MIT-licensed
terminal notification example with portable regression tests.

This is a reference proposal, not a change to the shipped CLI. This public
repository does not expose the application implementation; maintainers would
need to integrate the backend into the product.

Problem and proposed behavior

With the unmodified 1.0.84-1 release in Ghostty, clicking a desktop notification
can open Script Editor instead of returning to the terminal. The AppleScript
notification path attributes the notification to the scripting host.

The example uses terminal-owned notifications on supported local macOS TTYs:
OSC 777 for Ghostty and OSC 9 for iTerm2. It sanitizes control characters and
field separators, avoids redirected output, awaits write completion, and reports
unsupported contexts or write failures so the caller can retain native fallback.

The proposal preserves existing notification settings, focus gating,
deduplication, rate limits, and protocol-aware multiplexer routing. It documents
permission and notification-feature tradeoffs rather than claiming identical
native behavior.

Validation

node --test examples/terminal-notifications/terminal-notifications.test.mjs

All 33 included tests pass. They run without launching Copilot, reading user
configuration, loading its runtime, or sending desktop notifications.

A separate desktop acceptance run using this backend confirmed that the default
notification click action brought Ghostty to the foreground without opening
Script Editor. That run covered a single Ghostty window; iTerm2 and
multiple-window acceptance remain outside that result.

Submission scope

The four added files contain only the original example, its tests, a scoped MIT
license, and the proposal. No bundled or reconstructed Copilot source, binaries,
runtime-patching tools, user configuration, machine paths, session identifiers,
or private build metadata are included. The repository's existing license is
unchanged.

[Copilot]

🟢 Approval recommended

The standalone proposal is internally consistent, safely scoped, and thoroughly tested.

Pull request overview

Adds a standalone reference implementation for terminal-owned macOS notifications without modifying the shipped CLI.

Changes:

• Implements sanitized OSC 777 and OSC 9 notifications.
• Adds 33 portable regression tests.
• Documents integration constraints, tradeoffs, and scoped licensing.

File summaries

File	Description
terminal-notifications.mjs	Implements terminal detection, encoding, and delivery.
terminal-notifications.test.mjs	Tests supported, unsupported, and failure scenarios.
README.md	Documents the proposal and integration guidance.
LICENSE	Applies MIT licensing to the example.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.