fix(mobile): iOS home screen widgets render instead of a containerBackground error

[jakeleventhal]

Before

After

What Changed

iOS home-screen Agent Activity widgets now render instead of Apple's "Please adopt containerBackground API" placeholder.

• Apply containerBackground("clear", "widget") on the home-screen view (small, medium, lock-screen rectangular).
• Register the same layout with createWidget, not only createLiveActivity.
• Publish widget snapshots from the existing Live Activity refresh/arming path.
• Treat missing first-paint props as idle so the widget JS runtime does not throw.

Live Activity / Dynamic Island layouts are unchanged.

Why

expo-widgets 56 stopped applying containerBackground for us, and the home-screen widget never received a createWidget layout (that API writes a different App Group key than Live Activities). iOS 17+ then refused to render the widget.

UI Changes

Before: adding the Agent Activity widget showed a white card with a stop icon and "Please adopt containerBackground API".

After: not captured on a device in this change (needs a native iOS rebuild and adding the widget). After opening the updated app once, the widget should show agent rows or "No active agents" on the system widget chrome.

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

Made-with: Grok 4.6 (T3 Code)

Maintainer verification, September 5

Related report: #6641. Jake Leventhal's original branch and work are preserved.

The current-main widget code at f8b4c464 leaves the regular widget layout and timeline uninitialized. Adding the medium widget, opening the app and returning Home leaves a red placeholder in the Debug extension. The candidate renders the normal empty state on that same widget after loading the app. The app itself writes the regular layout and timeline; no widget preferences were manually seeded.

Before, current-main-equivalent widget source:

After, candidate production source:

Both captures use the same iPhone 17 Pro Max simulator, iOS 26.5, installed Debug app, home-screen placement and empty activity state. The compatible installed widget extension, Expo Widgets 57.0.15, app configuration and relevant native sources were checked against main. This is not a full current-main native build or a pixel-identical reproduction of the report's black release widget on iOS 26.3.1(a). The screenshots verify real WidgetKit rendering, not a React mock. No live relay account, paid provider turn, active-agent push, physical device, Android or watch/CarPlay check is claimed.

Review found a separate race in this PR: local work could wait for preferences, sign out or switch accounts, then republish the previous account's thread and project. The follow-up ee7365cf rejects that stale callback using the existing account generation. Two deterministic regression cases fail before the fix; both pass after it, while the same-account token-refresh control remains valid. The next test-only commit replaces the four timer waits introduced by this PR with preference-continuation completion receipts.

The orchestrator independently reran both complete focused test files at 845ed3d2: 61 passed. Targeted lint, formatting and diff checks pass. The final test-only commit has identical production bytes to the native-tested candidate. The latest CI results and the additional local-start finding are recorded below.

Human review is still required for the widget presentation and app-driven refresh semantics. Regular widget updates are not continuous background Live Activity pushes. The shared renderer also changes glyph scaling, empty Live Activity labels and compact-layout deep links, so the earlier claim of entirely unchanged Live Activity layouts is too broad. Leave this PR unmerged until those choices are accepted.

Fix first: local task start can leave the widget idle

Further review at 845ed3d2 confirmed the two local-start ordering findings filtered from the latest Macroscope output. The blank-widget rendering fix above works, but the current PR does not reliably show newly started work.

NewTaskDraftScreen arms the activity before creating the thread. Attachment preparation and turn submission can therefore finish after the PR's widget snapshot read. With Live Activities off, the widget receives idle. With them on, token registration can replace the Connecting seed with idle. Later activity arriving at the relay does not itself trigger another regular-widget update.

An independent orchestrator run executed the unchanged production arming, token-registration finalizer and foreground callbacks against controlled relay responses. Both delayed-activity cases failed the expected active-count assertion. Both already-active controls passed, and the actual foreground callback recovered Working in the delayed cases. Four cases ran in 2.07 seconds, with two failures and two passes. This proves the module's ordering behavior, not a real provider turn, relay transport or native active-task rendering.

Moving the read after thread creation is not sufficient: turn submission does not acknowledge relay publication. Early native Live Activity arming must also remain before the app can background. A reliable dynamic-widget fix needs an explicit choice of authoritative activity state and reconciliation across connected and relay-only environments. A narrower rendering-only change with clearly last-observed activity is another scope choice.

Leave this PR unmerged. It needs that scope decision and a verified correction before it is ready, not just presentation approval. CI is terminal at this head: 15 checks succeeded, eight skipped and Approvability is neutral with a human-review requirement. Those results do not resolve this finding.

Maintainer audit, follow-up fixes and native verification by GPT 6 Astra via Codex in T3 Code. Original contributor attribution above is preserved.

Note

Render iOS home-screen widgets for AgentActivity and publish activity snapshots

• AgentActivity.tsx adds system-small, system-medium, and accessory widget layouts with T3 branding, project names, and phase icons. Retains the banner layout for Live Activity environments.
• Exports AgentActivityWidget and publishAgentActivityWidget to register the widget and forward snapshot updates.
• remoteRegistration.ts integrates the widget publisher and adds a generation counter to ignore stale refresh results.
• Schedules widget refreshes on local work arming, delayed push-token receipt, and foreground reconciliation. Publishes an idle widget on sign-out.
• Behavioral Change: Removing the relay token provider in setAgentAwarenessRelayTokenProvider now publishes an idle widget state; foreground reconciliation refreshes the widget before priming Live Activities.

^{Macroscope summarized 845ed3d.}

---

Note

Medium Risk
Adds async widget publishing on sign-out, foreground refresh, and local arming with generation guards—wrong ordering could briefly show stale agent state, but changes are scoped to iOS widget/Live Activity registration, not auth or data storage.

Overview
Fixes iOS home-screen Agent Activity widgets that showed Apple’s “adopt containerBackground” placeholder by registering a createWidget layout (alongside the existing Live Activity) with containerBackground("clear", "widget"), dedicated small/medium/accessory UI, and safer handling of empty first-paint props (“No active agents”).

publishAgentActivityWidget pushes relay/local snapshots via updateSnapshot. remoteRegistration now refreshes the widget whenever Live Activity reconciliation runs (including when Live Activities are off or a card is already armed), seeds a “Connecting” snapshot when local work starts, clears to idle on cloud sign-out, and uses widgetRefreshGeneration so slower relay reads cannot overwrite newer local seeds or post–sign-out idle state.

Live Activity / Dynamic Island layouts are intentionally unchanged; tests cover refresh timing, races, and sign-out guards.

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

[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: 86716961-3d50-423b-9dc2-33819956f9fa

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]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This change adds a substantial iOS widget renderer and wires snapshot refreshes into sign-in, foreground reconciliation, local work, token registration, and sign-out. The shared renderer and asynchronous lifecycle changes affect production UI behavior beyond a narrowly scoped bug fix.

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

[cursor]

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

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

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