fix(mobile): Persist crash diagnostics before runtime fatals

[juliusmarminge]

Extracted from #3910.

Adds early JS crash capture, disk-backed breadcrumbs, and a synchronous native write path so release-runtime failures leave recoverable diagnostics before React Native terminates. It also records outbox activity as crash context.

Validation inherited from #3910: vp check and mobile native lint passed before the split. The full typecheck is currently blocked in this workspace by unavailable mobile dependencies (expo-blur, expo-quick-actions, and @tabler/icons-react-native).

Note

Persist crash diagnostics to disk before runtime fatals in the mobile app

• Adds a global JS error handler via installCrashLogger that intercepts fatal errors, writes a JSON crash record to the device's crash-logs directory, then delegates to the previous handler.
• Crash files are named crash-<epoch>-<seq>.json for stable lexicographic ordering; on next launch, the most recent 3 are logged to the console and files beyond 20 are pruned.
• installCrashLog.ts is imported at the top of index.ts as a side-effect so the handler registers before any other app modules load.
• Risk: file I/O failures during a crash are silently swallowed; if ErrorUtils is unavailable the installer does nothing.

^{Macroscope summarized 65fbd78.}

---

Note

Medium Risk
Fatal-error handling performs synchronous document-directory file I/O before the prior global handler runs, which can add latency on the crash path and must not interfere with existing crash reporting.

Overview
Adds early fatal JS crash capture so release-runtime failures leave recoverable diagnostics before React Native tears down.

A side-effect import at the top of index.ts runs installCrashLogger() before the rest of the app loads. The logger chains React Native’s global ErrorUtils handler: on fatal errors it synchronously writes a JSON record (message, name, stack, timestamp) under crash-logs in the document directory, then calls the previous handler. Persistence is wrapped so logging failures never hide the original crash.

On the next launch, a deferred setTimeout(0) pass (no file I/O during install) warns the three newest prior crash files to the console and prunes older logs beyond a cap of 20.

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

Summary by CodeRabbit

• New Features
  • Added automatic crash logging for fatal mobile app errors.
  • Crash details are saved as timestamped records for later review.
  • Up to three previous crash records are displayed when the app starts.
  • Stored crash records are automatically limited to the 20 most recent entries.
  • Crash logging failures are safely handled without interrupting app startup or error reporting.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: b7a444dc-d380-4af5-b7f0-40130226eccb

📥 Commits

Reviewing files that changed from the base of the PR and between dadba6d and 65fbd78.

📒 Files selected for processing (3)

• apps/mobile/index.ts
• apps/mobile/src/lib/crashLog.ts
• apps/mobile/src/lib/installCrashLog.ts

Included review availability: 4 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

---

📝 Walkthrough

Walkthrough

The mobile app adds crash logging. It installs the global error handler before the app module graph evaluates, persists fatal errors, reports recent records at startup, and limits stored records to 20.

Changes

Mobile crash logging

Layer / File(s)	Summary
Crash logging infrastructure apps/mobile/src/lib/crashLog.ts	Adds guarded global error handling, timestamped crash-file persistence, startup reporting for up to three records, and pruning beyond 20 records.
Early crash logger initialization apps/mobile/src/lib/installCrashLog.ts, apps/mobile/index.ts	Invokes crash logging during module initialization and imports it before the remaining app module graph evaluates.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 65fbd

This change installs early mobile crash logging to persist and report fatal-error diagnostics without altering the existing error-handler chain. No current merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant AppEntry as Mobile app entry
  participant CrashLogger as installCrashLogger
  participant FileSystem as Document directory
  participant ReactNative as React Native global error handler
  AppEntry->>CrashLogger: initialize before app modules
  CrashLogger->>ReactNative: install fatal-error handler
  ReactNative->>CrashLogger: deliver fatal error
  CrashLogger->>FileSystem: write timestamped JSON record
  CrashLogger->>FileSystem: read and prune crash records
  CrashLogger->>CrashLogger: report up to three recent records

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the crash-capture changes, motivation, risks, and validation status. It does not use the template headings or include the checklist, but the required change and ration…
Title check	✅ Passed	The title clearly and concisely describes the main change: persisting mobile crash diagnostics before runtime fatal errors.
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.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces new crash logging infrastructure that installs a global error handler before the app module graph loads. While defensively implemented, changes to fatal error handling at this level warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{Bugbot Autofix is ON, but it could not run because the branch was deleted or merged before autofix could start.}

^{Reviewed by Cursor Bugbot for commit 959a39b. Configure here.}