@rejourneyco/react-native 1.0.8 → 1.0.10

package/README.md

@@ -11,15 +11,89 @@ npm install @rejourneyco/react-native
 ## Quick Start
 
 ```typescript
-import { initRejourney, startRejourney } from '@rejourneyco/react-native';
+import { Rejourney } from '@rejourneyco/react-native';
 
 // Initialize with your public key
-initRejourney('pk_live_xxxxxxxxxxxx');
+Rejourney.init('pk_live_xxxxxxxxxxxx');
 
 // Start recording after obtaining user consent
-startRejourney();
+Rejourney.start();
 ```
 
+## Navigation Tracking
+
+Rejourney automatically tracks screen changes to provide context for your session replays.
+
+### Expo Router (Automatic)
+If you use **Expo Router**, simply add this import at your root layout (`app/_layout.tsx`):
+```ts
+import '@rejourneyco/react-native/expo-router';
+```
+
+### React Navigation
+If you are using **React Navigation** (`@react-navigation/native`), use the `useNavigationTracking` hook in your root `NavigationContainer`:
+```tsx
+import { Rejourney } from '@rejourneyco/react-native';
+import { NavigationContainer } from '@react-navigation/native';
+
+const navigationTracking = Rejourney.useNavigationTracking();
+return <NavigationContainer {...navigationTracking}>{/*...*/}</NavigationContainer>;
+```
+
+### Custom Screen Names
+If you want to manually specify screen names or use a different library:
+
+#### For Expo Router users:
+Disable automatic tracking in your initialization:
+```ts
+Rejourney.init('pk_live_xxxxxxxxxxxx', {
+  autoTrackExpoRouter: false
+});
+```
+
+#### Manual tracking call:
+Notify Rejourney of screen changes using `trackScreen`:
+```ts
+import { Rejourney } from '@rejourneyco/react-native';
+
+Rejourney.trackScreen('Custom Screen Name');
+```
+
+> [!NOTE]
+> `expo-router` is an **optional peer dependency**. The SDK is carefully architectural to avoid requiring `expo-router` in the main bundle. This prevents Metro from attempting to resolve it at build time in projects where it's not installed, which would otherwise cause a "Requiring unknown module" crash.
+
+## Custom Events & Metadata
+
+You can track custom events and assign metadata to sessions to filter and segment them later.
+
+```typescript
+import { Rejourney } from '@rejourneyco/react-native';
+
+// Log custom events
+Rejourney.logEvent('button_clicked', { buttonName: 'signup' });
+
+// Add custom session metadata
+Rejourney.setMetadata('plan', 'premium');
+Rejourney.setMetadata({
+  role: 'tester',
+  ab_test_group: 'A'
+});
+```
+
+## API Reference & Compatibility
+
+Rejourney supports both a standardized `Rejourney.` namespace and standalone function exports (AKA calls). Both are fully supported.
+
+| Standardized Method | Standalone Alias (AKA) |
+| --- | --- |
+| `Rejourney.init()` | `initRejourney()` |
+| `Rejourney.start()` | `startRejourney()` |
+| `Rejourney.stop()` | `stopRejourney()` |
+| `Rejourney.useNavigationTracking()` | `useNavigationTracking()` |
+
+> [!TIP]
+> We recommend using the `Rejourney.` prefix for better discoverability and a cleaner import surface.
+
 ## Documentation
 
 Full integration guides and API reference: https://rejourney.co/docs/reactnative/overview

package/android/src/main/AndroidManifest.xml

@@ -4,6 +4,12 @@
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
     
     <application>
+        <!-- Run before bridge init so OkHttpClientProvider uses our factory when NetworkingModule is created -->
+        <provider
+            android:name=".RejourneyOkHttpInitProvider"
+            android:authorities="${applicationId}.rejourney.okhttpinit"
+            android:exported="false"
+            android:initOrder="100" />
         <!-- Service to detect app termination when swiped away from recent apps -->
         <!-- stopWithTask="false" is CRITICAL - allows onTaskRemoved() to fire when app is killed -->
         <service

package/android/src/main/java/com/rejourney/RejourneyModuleImpl.kt

@@ -37,14 +37,21 @@ import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.ProcessLifecycleOwner
 import com.facebook.react.bridge.*
+import com.facebook.react.modules.network.CustomClientBuilder
+import com.facebook.react.modules.network.OkHttpClientFactory
+import com.facebook.react.modules.network.OkHttpClientProvider
+import com.facebook.react.modules.network.NetworkingModule
+import okhttp3.OkHttpClient
 import com.rejourney.engine.DeviceRegistrar
 import com.rejourney.engine.DiagnosticLog
+
 import com.rejourney.platform.OEMDetector
 import com.rejourney.platform.SessionLifecycleService
 import com.rejourney.platform.TaskRemovedListener
 import com.rejourney.recording.*
 import kotlinx.coroutines.*
 import java.security.MessageDigest
+import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.locks.ReentrantLock
 import kotlin.concurrent.withLock
 
@@ -68,9 +75,11 @@ class RejourneyModuleImpl(
         var sdkVersion = "1.0.1"
         
         private const val SESSION_TIMEOUT_MS = 60_000L // 60 seconds
+        private const val SESSION_ROLLOVER_GRACE_MS = 2_000L
         
         private const val PREFS_NAME = "com.rejourney.prefs"
         private const val KEY_USER_IDENTITY = "user_identity"
+        private const val KEY_ANONYMOUS_ID = "anonymous_id"
     }
 
     // State machine
@@ -143,8 +152,49 @@ class RejourneyModuleImpl(
                 registerActivityLifecycleCallbacks()
                 registerProcessLifecycleObserver()
                 
-                // Transmit any stored crash reports
-                StabilityMonitor.getInstance(reactContext).transmitStoredReport()
+                // Recover any session interrupted by a previous crash.
+                // Transmit stored fault reports only after recovery restores auth context.
+                ReplayOrchestrator.getInstance(reactContext).recoverInterruptedReplay { recoveredId ->
+                    if (recoveredId != null) {
+                        DiagnosticLog.notice("[Rejourney] Recovered crashed session: $recoveredId")
+                    }
+                    StabilityMonitor.getInstance(reactContext).transmitStoredReport()
+                }
+                
+                // Register OkHttp interceptor so native/RN fetch() and XHR go through Rejourney.
+                // Use both mechanisms so we catch requests regardless of init order:
+                // 1) OkHttpClientProvider factory + clear cache (correct field: sClient)
+                // 2) NetworkingModule.setCustomClientBuilder — applied on every request's client
+                try {
+                    OkHttpClientProvider.setOkHttpClientFactory(OkHttpClientFactory {
+                        OkHttpClientProvider.createClientBuilder()
+                            .addInterceptor(RejourneyNetworkInterceptor())
+                            .build()
+                    })
+                    // React Native caches the client in OkHttpClientProvider.sClient (not "client").
+                    // Clear it so the next getOkHttpClient() uses our factory.
+                    try {
+                        val clientField = OkHttpClientProvider::class.java.getDeclaredField("sClient")
+                        clientField.isAccessible = true
+                        clientField.set(null, null)
+                    } catch (_: Exception) {}
+                    OkHttpClientProvider.getOkHttpClient()
+                    // Ensure every request (including those already using a cached client) gets our
+                    // interceptor. NetworkingModule builds per-request clients via mClient.newBuilder()
+                    // and applies this builder, so this catches all native API calls.
+                    try {
+                        NetworkingModule.setCustomClientBuilder(object : CustomClientBuilder {
+                            override fun apply(builder: OkHttpClient.Builder) {
+                                builder.addInterceptor(RejourneyNetworkInterceptor())
+                            }
+                        })
+                        DiagnosticLog.notice("[Rejourney] Registered OkHttp interceptor + CustomClientBuilder")
+                    } catch (e: Exception) {
+                        DiagnosticLog.notice("[Rejourney] OkHttp interceptor registered (CustomClientBuilder skipped: ${e.message})")
+                    }
+                } catch (e: Exception) {
+                    DiagnosticLog.fault("[Rejourney] Failed to register OkHttp interceptor factory: ${e.message}")
+                }
                 
                 // Android-specific: OEM detection and task removed handling
                 setupOEMSpecificHandling()
@@ -222,6 +272,8 @@ class RejourneyModuleImpl(
                 // Flush pending data
                 TelemetryPipeline.shared?.dispatchNow()
                 SegmentDispatcher.shared.shipPending()
+                // Stop the heartbeat timer to prevent event uploads while backgrounded
+                TelemetryPipeline.shared?.pause()
             }
         }
     }
@@ -245,6 +297,9 @@ class RejourneyModuleImpl(
 
             DiagnosticLog.notice("[Rejourney] App foregrounded after ${backgroundDuration / 1000}s (timeout: ${SESSION_TIMEOUT_MS / 1000}s)")
 
+            // Resume the heartbeat timer now that we're back in foreground
+            TelemetryPipeline.shared?.resume()
+
             if (backgroundDuration > SESSION_TIMEOUT_MS) {
                 // End current session and start a new one
                 state = SessionState.Idle
@@ -252,16 +307,52 @@ class RejourneyModuleImpl(
                 
                 DiagnosticLog.notice("[Rejourney] 🔄 Session timeout! Ending session '$oldSessionId' and creating new one")
 
+                val restartStarted = AtomicBoolean(false)
+                val triggerRestart: (String) -> Unit = { source ->
+                    if (restartStarted.compareAndSet(false, true)) {
+                        DiagnosticLog.notice("[Rejourney] Session rollover trigger source=$source, oldSession=$oldSessionId")
+                        mainHandler.post { startNewSessionAfterTimeout() }
+                    }
+                }
+
+                mainHandler.postDelayed({
+                    if (!restartStarted.get()) {
+                        DiagnosticLog.caution("[Rejourney] Session rollover grace timeout reached (${SESSION_ROLLOVER_GRACE_MS}ms), forcing new session start")
+                    }
+                    triggerRestart("grace_timeout")
+                }, SESSION_ROLLOVER_GRACE_MS)
+
                 backgroundScope.launch {
-                    ReplayOrchestrator.shared?.endReplay { success, uploaded ->
+                    val orchestrator = ReplayOrchestrator.shared
+                    if (orchestrator == null) {
+                        triggerRestart("orchestrator_missing")
+                        return@launch
+                    }
+
+                    orchestrator.endReplayWithReason("background_timeout") { success, uploaded ->
                         DiagnosticLog.notice("[Rejourney] Old session ended (success: $success, uploaded: $uploaded)")
-                        mainHandler.post { startNewSessionAfterTimeout() }
+                        triggerRestart("end_replay_callback")
                     }
                 }
             } else {
-                // Resume existing session
-                state = SessionState.Active(currentState.sessionId, currentState.startTimeMs)
-                DiagnosticLog.notice("[Rejourney] ▶️ Resuming session '${currentState.sessionId}'")
+                val orchestratorSessionId = ReplayOrchestrator.shared?.replayId
+                if (orchestratorSessionId.isNullOrEmpty()) {
+                    // The old session can end while app is backgrounded (e.g. duration limit).
+                    // Do not resume a dead session; start a fresh one.
+                    state = SessionState.Idle
+                    DiagnosticLog.notice("[Rejourney] Session ended while backgrounded, starting fresh session on foreground")
+                    mainHandler.post { startNewSessionAfterTimeout() }
+                    return
+                }
+
+                if (orchestratorSessionId != currentState.sessionId) {
+                    state = SessionState.Active(orchestratorSessionId, System.currentTimeMillis())
+                    DiagnosticLog.notice("[Rejourney] ▶️ Foreground reconciled to active session '$orchestratorSessionId' (was '${currentState.sessionId}')")
+                } else {
+                    // Resume existing session
+                    state = SessionState.Active(currentState.sessionId, currentState.startTimeMs)
+                    DiagnosticLog.notice("[Rejourney] ▶️ Resuming session '${currentState.sessionId}'")
+                }
                 
                 // Record foreground event
                 TelemetryPipeline.shared?.recordAppForeground(backgroundDuration)
@@ -277,6 +368,14 @@ class RejourneyModuleImpl(
 
         DiagnosticLog.notice("[Rejourney] Starting new session after timeout (user: $savedUserId)")
 
+        // Refresh activity on capture components (guards against race with onActivityResumed)
+        val activity = reactContext.currentActivity
+        if (activity != null) {
+            VisualCapture.shared?.setCurrentActivity(activity)
+            ViewHierarchyScanner.shared?.setCurrentActivity(activity)
+            InteractionRecorder.shared?.setCurrentActivity(activity)
+        }
+
         // Try fast path with cached credentials
         val existingCred = DeviceRegistrar.shared?.uploadCredential
         if (existingCred != null && DeviceRegistrar.shared?.credentialValid == true) {
@@ -494,6 +593,7 @@ class RejourneyModuleImpl(
                 state = SessionState.Idle
             }
             
+            
             // Android-specific: Stop SessionLifecycleService
             stopSessionLifecycleService()
 
@@ -502,7 +602,7 @@ class RejourneyModuleImpl(
                 return@post
             }
 
-            ReplayOrchestrator.shared?.endReplay { success, uploaded ->
+            ReplayOrchestrator.shared?.endReplayWithReason("user_initiated") { success, uploaded ->
                 DiagnosticLog.replayEnded(targetSid)
                 
                 promise.resolve(Arguments.createMap().apply {
@@ -554,6 +654,30 @@ class RejourneyModuleImpl(
         promise.resolve(currentUserIdentity)
     }
 
+    fun setAnonymousId(anonymousId: String, promise: Promise) {
+        try {
+            val prefs = reactContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            if (anonymousId.isBlank()) {
+                prefs.edit().remove(KEY_ANONYMOUS_ID).apply()
+            } else {
+                prefs.edit().putString(KEY_ANONYMOUS_ID, anonymousId).apply()
+            }
+        } catch (e: Exception) {
+            DiagnosticLog.fault("[Rejourney] Failed to persist anonymous ID: ${e.message}")
+        }
+
+        promise.resolve(createResultMap(true))
+    }
+
+    fun getAnonymousId(promise: Promise) {
+        try {
+            val prefs = reactContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            promise.resolve(prefs.getString(KEY_ANONYMOUS_ID, null))
+        } catch (_: Exception) {
+            promise.resolve(null)
+        }
+    }
+
     fun logEvent(eventType: String, details: ReadableMap, promise: Promise) {
         // Handle network_request events specially
         if (eventType == "network_request") {
@@ -589,6 +713,17 @@ class RejourneyModuleImpl(
             return
         }
 
+        // Handle console log events - preserve type:"log" with level and message
+        // so the dashboard replay can display them in the console terminal
+        if (eventType == "log") {
+            val detailsMap = details.toHashMap()
+            val level = detailsMap["level"]?.toString() ?: "log"
+            val message = detailsMap["message"]?.toString() ?: ""
+            TelemetryPipeline.shared?.recordConsoleLogEvent(level, message)
+            promise.resolve(createResultMap(true))
+            return
+        }
+
         // All other events go through custom event recording
         val payload = try {
             val json = org.json.JSONObject(details.toHashMap()).toString()

package/android/src/main/java/com/rejourney/RejourneyOkHttpInitProvider.kt

@@ -0,0 +1,68 @@
+/**
+ * Copyright 2026 Rejourney
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.rejourney
+
+import android.content.ContentProvider
+import android.content.ContentValues
+import android.database.Cursor
+import android.net.Uri
+import com.facebook.react.modules.network.OkHttpClientFactory
+import com.facebook.react.modules.network.OkHttpClientProvider
+import com.rejourney.recording.RejourneyNetworkInterceptor
+
+/**
+ * ContentProvider that runs before Application.onCreate() (and thus before the React Native
+ * bridge and NetworkingModule are created). It registers our OkHttpClientFactory so the
+ * first (and all) OkHttpClient instances created by OkHttpClientProvider already include
+ * RejourneyNetworkInterceptor, ensuring native API calls are captured on Android like on iOS.
+ */
+class RejourneyOkHttpInitProvider : ContentProvider() {
+
+    override fun onCreate(): Boolean {
+        try {
+            OkHttpClientProvider.setOkHttpClientFactory(OkHttpClientFactory {
+                OkHttpClientProvider.createClientBuilder()
+                    .addInterceptor(RejourneyNetworkInterceptor())
+                    .build()
+            })
+        } catch (_: Exception) {
+            // Ignore; RejourneyModuleImpl will still register factory + CustomClientBuilder later
+        }
+        return true
+    }
+
+    override fun query(
+        uri: Uri,
+        projection: Array<out String>?,
+        selection: String?,
+        selectionArgs: Array<out String>?,
+        sortOrder: String?
+    ): Cursor? = null
+
+    override fun getType(uri: Uri): String? = null
+
+    override fun insert(uri: Uri, values: ContentValues?): Uri? = null
+
+    override fun delete(uri: Uri, selection: String?, selectionArgs: Array<out String>?): Int = 0
+
+    override fun update(
+        uri: Uri,
+        values: ContentValues?,
+        selection: String?,
+        selectionArgs: Array<out String>?
+    ): Int = 0
+}

package/android/src/main/java/com/rejourney/engine/DeviceRegistrar.kt

@@ -22,6 +22,7 @@ import android.os.Build
 import android.provider.Settings
 import kotlinx.coroutines.*
 import okhttp3.*
+import com.rejourney.recording.RejourneyNetworkInterceptor
 import okhttp3.MediaType.Companion.toMediaType
 import okhttp3.RequestBody.Companion.toRequestBody
 import org.json.JSONObject
@@ -64,12 +65,15 @@ class DeviceRegistrar private constructor(private val context: Context) {
     // Private State
     private val prefsKey = "com.rejourney.device"
     private val fingerprintKey = "device_fingerprint"
+    private val fallbackIdKey = "device_fallback_id"
     private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
     
     private val httpClient: OkHttpClient = OkHttpClient.Builder()
         .connectTimeout(5, TimeUnit.SECONDS) // Short timeout for debugging
         .readTimeout(10, TimeUnit.SECONDS)
         .writeTimeout(10, TimeUnit.SECONDS)
+        // Mirror iOS URLProtocol behaviour: make native SDK HTTP calls observable
+        .addInterceptor(RejourneyNetworkInterceptor())
         .build()
     
     init {
@@ -169,7 +173,6 @@ class DeviceRegistrar private constructor(private val context: Context) {
         var composite = packageName
         composite += Build.MODEL
         composite += Build.MANUFACTURER
-        composite += Build.VERSION.RELEASE
         composite += getAndroidId()
         
         return sha256(composite)
@@ -177,12 +180,27 @@ class DeviceRegistrar private constructor(private val context: Context) {
     
     private fun getAndroidId(): String {
         return try {
-            Settings.Secure.getString(context.contentResolver, Settings.Secure.ANDROID_ID) ?: java.util.UUID.randomUUID().toString()
+            Settings.Secure.getString(context.contentResolver, Settings.Secure.ANDROID_ID)
+                ?: stableDeviceFallback()
         } catch (e: Exception) {
-            java.util.UUID.randomUUID().toString()
+            stableDeviceFallback()
         }
     }
     
+    /**
+     * Returns a SharedPreferences-persisted UUID so the fingerprint stays stable
+     * even when ANDROID_ID is unavailable (restricted profiles, some OEM devices).
+     */
+    private fun stableDeviceFallback(): String {
+        val prefs = context.getSharedPreferences(prefsKey, Context.MODE_PRIVATE)
+        val existing = prefs.getString(fallbackIdKey, null)
+        if (existing != null) return existing
+        
+        val fresh = java.util.UUID.randomUUID().toString()
+        prefs.edit().putString(fallbackIdKey, fresh).apply()
+        return fresh
+    }
+    
     // Server Communication
     
     private suspend fun fetchServerCredential(

package/android/src/main/java/com/rejourney/engine/RejourneyImpl.kt

@@ -30,6 +30,7 @@ import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.ProcessLifecycleOwner
 import com.rejourney.recording.*
 import java.security.MessageDigest
+import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.locks.ReentrantLock
 import kotlin.concurrent.withLock
 
@@ -45,26 +46,26 @@ sealed class SessionState {
 
 /**
  * Main SDK implementation aligned with iOS RejourneyImpl.swift
- * 
+ *
  * This class provides the core SDK functionality for native Android usage.
  * For React Native, use RejourneyModuleImpl instead.
  */
-class RejourneyImpl private constructor(private val context: Context) : 
+class RejourneyImpl private constructor(private val context: Context) :
     Application.ActivityLifecycleCallbacks, DefaultLifecycleObserver {
 
     companion object {
         @Volatile
         private var instance: RejourneyImpl? = null
-        
+
         fun getInstance(context: Context): RejourneyImpl {
             return instance ?: synchronized(this) {
                 instance ?: RejourneyImpl(context.applicationContext).also { instance = it }
             }
         }
-        
+
         val shared: RejourneyImpl?
             get() = instance
-            
+
         var sdkVersion = "1.0.1"
     }
 
@@ -81,14 +82,23 @@ class RejourneyImpl private constructor(private val context: Context) :
 
     // Session timeout threshold (60 seconds)
     private val sessionTimeoutMs = 60_000L
+    private val sessionRolloverGraceMs = 2_000L
 
     private val mainHandler = Handler(Looper.getMainLooper())
-    
+
     @Volatile
     private var isInitialized = false
 
     init {
         setupLifecycleListeners()
+
+        // Recover sessions interrupted by a previous crash first, then send stored faults.
+        ReplayOrchestrator.getInstance(context).recoverInterruptedReplay { recoveredId ->
+            if (recoveredId != null) {
+                DiagnosticLog.notice("[Rejourney] Recovered crashed session: $recoveredId")
+            }
+            StabilityMonitor.getInstance(context).transmitStoredReport()
+        }
     }
 
     private fun setupLifecycleListeners() {
@@ -97,10 +107,10 @@ class RejourneyImpl private constructor(private val context: Context) :
             mainHandler.post {
                 ProcessLifecycleOwner.get().lifecycle.addObserver(this)
             }
-            
+
             // Register activity callbacks
             (context.applicationContext as? Application)?.registerActivityLifecycleCallbacks(this)
-            
+
         } catch (e: Exception) {
             DiagnosticLog.fault("[Rejourney] Failed to setup lifecycle listeners: ${e.message}")
         }
@@ -123,7 +133,7 @@ class RejourneyImpl private constructor(private val context: Context) :
                     state = SessionState.Paused(currentState.sessionId, currentState.startTimeMs)
                     backgroundEntryTimeMs = System.currentTimeMillis()
                     DiagnosticLog.notice("[Rejourney] ⏸️ Session '${currentState.sessionId}' paused (app backgrounded)")
-                    
+
                     TelemetryPipeline.shared?.dispatchNow()
                     SegmentDispatcher.shared.shipPending()
                 }
@@ -158,16 +168,49 @@ class RejourneyImpl private constructor(private val context: Context) :
 
                 DiagnosticLog.notice("[Rejourney] 🔄 Session timeout! Ending session '$oldSessionId' and creating new one")
 
-                Thread {
-                    ReplayOrchestrator.shared?.endReplay { success, uploaded ->
-                        DiagnosticLog.notice("[Rejourney] Old session ended (success: $success, uploaded: $uploaded)")
+                val restartStarted = AtomicBoolean(false)
+                val triggerRestart: (String) -> Unit = { source ->
+                    if (restartStarted.compareAndSet(false, true)) {
+                        DiagnosticLog.notice("[Rejourney] Session rollover trigger source=$source, oldSession=$oldSessionId")
                         mainHandler.post { startNewSessionAfterTimeout() }
                     }
+                }
+
+                mainHandler.postDelayed({
+                    if (!restartStarted.get()) {
+                        DiagnosticLog.caution("[Rejourney] Session rollover grace timeout reached (${sessionRolloverGraceMs}ms), forcing new session start")
+                    }
+                    triggerRestart("grace_timeout")
+                }, sessionRolloverGraceMs)
+
+                Thread {
+                    val orchestrator = ReplayOrchestrator.shared
+                    if (orchestrator == null) {
+                        triggerRestart("orchestrator_missing")
+                    } else {
+                        orchestrator.endReplayWithReason("background_timeout") { success, uploaded ->
+                            DiagnosticLog.notice("[Rejourney] Old session ended (success: $success, uploaded: $uploaded)")
+                            triggerRestart("end_replay_callback")
+                        }
+                    }
                 }.start()
             } else {
-                // Resume existing session
-                state = SessionState.Active(currentState.sessionId, currentState.startTimeMs)
-                DiagnosticLog.notice("[Rejourney] ▶️ Resuming session '${currentState.sessionId}'")
+                val orchestratorSessionId = ReplayOrchestrator.shared?.replayId
+                if (orchestratorSessionId.isNullOrEmpty()) {
+                    state = SessionState.Idle
+                    DiagnosticLog.notice("[Rejourney] Session ended while backgrounded, starting fresh session on foreground")
+                    mainHandler.post { startNewSessionAfterTimeout() }
+                    return
+                }
+
+                if (orchestratorSessionId != currentState.sessionId) {
+                    state = SessionState.Active(orchestratorSessionId, System.currentTimeMillis())
+                    DiagnosticLog.notice("[Rejourney] ▶️ Foreground reconciled to active session '$orchestratorSessionId' (was '${currentState.sessionId}')")
+                } else {
+                    // Resume existing session
+                    state = SessionState.Active(currentState.sessionId, currentState.startTimeMs)
+                    DiagnosticLog.notice("[Rejourney] ▶️ Resuming session '${currentState.sessionId}'")
+                }
 
                 TelemetryPipeline.shared?.recordAppForeground(backgroundDuration)
                 StabilityMonitor.shared?.transmitStoredReport()
@@ -323,7 +366,7 @@ class RejourneyImpl private constructor(private val context: Context) :
                 return@post
             }
 
-            ReplayOrchestrator.shared?.endReplay { success, uploaded ->
+            ReplayOrchestrator.shared?.endReplayWithReason("user_initiated") { success, uploaded ->
                 DiagnosticLog.replayEnded(targetSid)
                 callback?.invoke(success, targetSid, uploaded)
             }
@@ -385,6 +428,15 @@ class RejourneyImpl private constructor(private val context: Context) :
             return
         }
 
+        // Handle console log events - preserve type:"log" with level and message
+        // so the dashboard replay can display them in the console terminal
+        if (eventType == "log") {
+            val level = details?.get("level")?.toString() ?: "log"
+            val message = details?.get("message")?.toString() ?: ""
+            TelemetryPipeline.shared?.recordConsoleLogEvent(level, message)
+            return
+        }
+
         val payload = try {
             org.json.JSONObject(details ?: emptyMap<String, Any>()).toString()
         } catch (e: Exception) {
@@ -499,7 +551,7 @@ class RejourneyImpl private constructor(private val context: Context) :
                 else -> {}
             }
         }
-        
+
         try {
             (context.applicationContext as? Application)?.unregisterActivityLifecycleCallbacks(this)
             mainHandler.post {