feat(relay): silence mobile notifications while the desktop is focused

[ahalekelly]

🤖 Generated by Claude Code

What Changed

Agent-activity publishes carry a signed notify flag, separating "update the phone's state" from "alert the user".

• RelayAgentActivityPublishRequest and the signed proof payload gain notify: boolean, decoding to true when omitted.
• The server always publishes state so mobile cards and Live Activities stay current. notify is false while any client is visible and focused and the host is awake and unlocked, from the client-activity leases and host power state BackgroundPolicy already tracks. Focus is global: a user watching the app gets no phone alerts for any thread.
• The relay verifies notify against the signed proof and, when false, sends Live Activity updates with no alert and skips push notifications entirely.

A state published silently is not re-alerted when focus is later lost; the user saw it on screen.

Compatibility

Desktop/server	Relay	Result
old	new	Request and proof omit notify; both decode to true and match, so publishes verify and alert as before (tested in contracts and relay).
new	old	The old relay's schema drops the unknown key and its proof check ignores it; alerts on every publish, as today.

Mobile is unaffected in every combination: the flag only travels server → relay, and a silent update is a Live Activity update with alert: null, which the app already handles.

Why

Every published completed/failed/waiting_* state becomes a push. When T3 Code is focused on desktop the user is already watching, so the phone buzzing is noise — but the phone's state still has to converge, so the server can't just skip the publish. Without a channel split the alternatives are hold-and-replay (bursts late pushes for work the user already saw; #4747, +847 lines) or dropping publishes (stale cards, lost tombstones).

Related: #780, #4747.

UI Changes

None.

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

---

Note

Medium Risk
Changes signed publish verification and APNs delivery semantics for agent awareness; mismatched or tampered notify rejects publishes, but legacy omitting notify still defaults to alerting.

Overview
Agent-activity publishes now carry a signed notify flag so the relay can refresh mobile cards and Live Activities without ringing the phone when the user is already watching on desktop.

The local server still publishes every state change, but AgentAwarenessRelay sets notify to false when BackgroundPolicy.hasFocusedClient sees a visible, focused client and the host is awake and unlocked (not suspended or locked). That value is bound into the JWT proof and HTTP payload. RelayAgentActivityPublishRequest / proof schemas add notify with decode default true when omitted for older publishers.

On the relay, signature verification requires proof and request notify to match. AgentActivityPublisher and ApnsDeliveries honor notify: false by skipping notification-only push fallbacks and sending Live Activity updates/ends with alert: null; no companion push is queued on end. Updates published silently while focused are not re-alerted when focus is lost later.

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

Note

Silence mobile push notifications while a desktop client is focused

• Adds hasFocusedClient(snapshot) to BackgroundPolicy to detect a visible, focused client while the host is awake and unlocked
• AgentAwarenessRelay.make computes notify = !hasFocusedClient(...) and includes it in the signed publish proof and relay payload
• AgentActivityPublisher and ApnsDeliveries honor notify=false by suppressing push notification alerts while still updating Live Activities
• Adds notify boolean to RelayAgentActivityPublishProofPayload and RelayAgentActivityPublishRequest schemas, defaulting to true for legacy decodes
• EnvironmentPublishSignatures.verify rejects requests where the signed proof notify does not match the request notify
• Risk: old clients that omit notify default to true (no behavior change), but any mismatch between proof and request notify is now rejected — verify callers in Api.ts always forward the same value

^{Macroscope summarized ba72b28.}

[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: a995f562-0519-466e-8d61-55e34a3df4e0

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

---

_{Comment @coderabbitai help to get the list of available commands.}

[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 7f8c2f8. Configure here.}

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a cross-service, user-visible policy that automatically changes mobile push and Live Activity alert behavior based on desktop focus and host state. It is backward compatible at the protocol level and well tested, but the production blast radius and automatic notification gate warrant human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[ahalekelly]

Compatibility issues found by the bots are fixed, it passed claude /code-review as well