fix(mobile): collect UI runtime garbage on iOS memory warnings

[juliusmarminge]

On iOS, React Native's memory-warning handler only collects the main Hermes runtime. The Reanimated/worklets UI runtime is a separate Hermes heap with no memory-pressure handling. Garbage there keeps native objects alive, including view shadow nodes, ShadowNodeWrappers and worklets SynchronizableFixeds, until that heap happens to collect. In a 40-cycle navigation run, the control build still held 3,098 SynchronizableFixed and 1,973 ViewShadowNode objects after the late memory warning.

useUiRuntimeMemoryWarningGc, mounted once at the app root, listens for AppState memoryWarning and schedules a worklet on the UI runtime that calls globalThis.gc if Hermes exposes it. Without gc, the hook does nothing. The PR adds no polling, timers or state, and changes no visible behavior. React Native emits memoryWarning only on iOS, so the hook does nothing on Android.

Release memory measurements

Both runs used iPhone 17 Pro on the iOS 27 simulator, not a physical device. Both used the same optimized Release native executable (UUID D0C2BDE9-D7DA-3283-9891-83622F94DC12), Hermes -O, dev=false and no Metro server. Each run did 40 navigation cycles alternating a 30-turn, 70-tools-per-turn history and a 300-turn plain history, with 13 background/resume transitions on a 1,210-thread fixture. A test-only injected dylib posted UIApplicationDidReceiveMemoryWarningNotification on Home after cycle 6 and after cycle 40. Logs show both deliveries in each run. vmmap -summary and heap -s were captured on Home.

• Control: bundle d391d0c5… built from parent 4ff5c69, without the hook.
• Production: bundle 251e775e… built from 4ff5c69 plus this patch (source patch sha256 11f5b957…). The source map's sourcesContent for both changed files matches this commit exactly. The hook is not instrumented.

Home, after warning	Control c6	Control c40	Hook c6	Hook c40
worklets::SynchronizableFixed	1,104	3,098	754	828
ViewShadowNode	1,002	1,973	875	877
ShadowNodeWrapper	1,349	2,436	1,179	1,179
worklets::SerializableJSRef	7,337	12,008	6,924	8,927
Malloc allocated (MiB)	65.6	78.3	64.3	71.0
Malloc allocation count	305,772	358,516	300,287	323,029
Physical footprint (MiB)	233.5	290.8	230.5	285.9

With the hook, the late warning returned the target classes to their early levels. Before the late warning, the run held 2,857 SynchronizableFixed, 5,456 ViewShadowNode, 4,818 ShadowNodeWrapper, 108.4 MiB malloc allocated in 510,275 allocations, and a 306.2 MiB footprint.

Limits: This is one control run and one production run, so no percentage improvement is claimed. Physical footprint still grows +55.4 MiB from c6 to c40 after the warning with the hook, compared with +57.3 MiB in the control. Most of that growth is retained Hermes heap capacity in untagged regions. This PR does not fix overall memory growth. leaks reports the same 66 blocks (2,112 bytes) in both runs. Neither run measured battery use or latency.

UI GC timing: The production run has no timing instrumentation. A separate scratch build with an instrumented probe, which is not shipped, measured UI-runtime gc() at 2 ms after the early warning (allocated 8.36 → 3.02 MB) and 4 ms after the late warning (16.84 → 3.23 MB). Those numbers come from that diagnostic run, not from this exact hook.

Evidence: evidence.json (aggregates, bundle hashes, workload, diagnostic log)
Hook run: c06-home-postwarn-heap.txt · c06-home-postwarn-vmmap.txt · c40-home-postwarn-heap.txt · c40-home-postwarn-leaks.txt · c40-home-postwarn-vmmap.txt · c40-home-pre-heap.txt · c40-home-pre-vmmap.txt
Control run: c06-home-postwarn-heap.txt · c06-home-postwarn-vmmap.txt · c40-home-postwarn-heap.txt · c40-home-postwarn-leaks.txt · c40-home-postwarn-vmmap.txt · c40-home-pre-heap.txt · c40-home-pre-vmmap.txt

App paths and simulator identifiers are redacted from the captures. No source maps, bundles or databases are uploaded.

Verification

Mobile typecheck and targeted lint pass. The hook only runs on a native memory warning, so it has no unit test. The memory runs above are its behavioral proof.

Surfaces: only the iOS mobile client changes behavior. Android, web, desktop, server, providers and contracts are unchanged. Unrelated local widget edits are excluded.

Julius requested one PR per measured issue in this maintainer mobile performance audit.

Implementation and PR preparation: Claude Opus 5.5 through T3 Code. Production run integration and verification: GPT-6 Astra through the Codex harness.

🤖 Generated with Claude Code

---

[macroscopeapp]

Approvability

Verdict: Approved at 6e13d8f

Macroscope's review found this PR approvable — This is a small, self-contained mobile memory-management fix that only schedules UI-runtime garbage collection during memory-warning events, leaving normal app behavior and product defaults unchanged. The listener has a guarded fallback and is removed on cleanup.

No code changes detected at f190ecf. Prior analysis still applies.

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

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	—	5.0 KiB	—	6.8 KiB	✅
Codex	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Codex	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Codex	Live turn WebSocket decoded	—	20.9 KiB	—	29.3 KiB	✅
Codex	Live turn messages	—	2	—	8	✅
Claude	Total thread wire	—	5.0 KiB	—	6.8 KiB	✅
Claude	Thread snapshot wire	—	3.8 KiB	—	4.9 KiB	✅
Claude	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Claude	Live turn WebSocket decoded	—	21.2 KiB	—	29.3 KiB	✅
Claude	Live turn messages	—	2	—	8	✅

Baseline: unavailable · PR result: f190ecf · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[coderabbitai]

Important

Review skipped

We couldn't safely recover the incremental review. No full review was started, and the last reviewed checkpoint was preserved. Retry later, or explicitly request a full review by commenting @coderabbitai full review.

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

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml
• Review profile: CHILL
• Plan: Team
• Run ID: 10eadbb2-53e3-4431-a2fb-94d3c5e51d45

📥 Commits

Reviewing files that changed from the base of the PR and between 4ff5c69 and 6e13d8f.

📒 Files selected for processing (2)

• apps/mobile/src/App.tsx
• apps/mobile/src/lib/useUiRuntimeMemoryWarningGc.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The mobile app now registers a hook that listens for AppState memory warnings and schedules guarded garbage collection on the UI runtime.

Changes

Mobile memory warning garbage collection

Layer / File(s)	Summary
Memory warning listener and app wiring apps/mobile/src/lib/useUiRuntimeMemoryWarningGc.ts, apps/mobile/src/App.tsx	The hook schedules a worklet on each memory warning. The worklet calls globalThis.gc only when it is a function. The hook removes the listener on cleanup, and App invokes the hook.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~8 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant AppState
  participant useUiRuntimeMemoryWarningGc
  participant UI runtime
  participant globalThis.gc
  AppState->>useUiRuntimeMemoryWarningGc: memoryWarning event
  useUiRuntimeMemoryWarningGc->>UI runtime: schedule garbage-collection worklet
  UI runtime->>globalThis.gc: call if it is a function

Loading

Merge Risk: ⚪ Minimal · up to 6e13d

The change adds a guarded UI-runtime collection attempt on iOS memory warnings. No actionable merge-blocking risk is established; the PR appears mergeable with normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise, follows the conventional commit style, and clearly describes scheduling UI-runtime garbage collection on iOS memory warnings.
Description check	✅ Passed	The description clearly explains the problem, implementation, affected surfaces, and detailed verification results. It does not link the maintainer audit or include an explicit approval comment, but i…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[juliusmarminge]

Reviewed the docstring-coverage warning. No code change is needed: the hook already documents why the separate UI runtime needs collection, and the worklet comments explain its guarded runtime lookup. Additional comments describing the effect callback and cleanup would repeat the code, contrary to this repository’s documentation guidance. The review reports no actionable correctness findings.