fix(core:engine): surface TorState.Error on silent startup failures and add 90s timeout

Three bugs caused the Tor loading overlay to freeze the UI indefinitely:

1. registerStatusReceiver() assigned torReceiver before registerReceiver() succeeded.
   If registration threw, the field was non-null but unregistered. Future calls
   returned early on the null-guard so no STATUS broadcasts ever arrived and
   _torState stayed Connecting forever.

2. ensureStarted() only logged startService() failures. _torState remained
   Connecting with no way to transition to Error, blocking the UI.

3. onAppReady() used torState.filter().first() with no timeout. Any silent failure
   (SELinux denial, native crash with no onServiceDisconnected, broadcast
   registration failure) suspended the coroutine and froze the overlay forever.

Fixes:
- registerStatusReceiver: assign torReceiver only after successful registration;
  emit TorState.Error on failure so future ensureStarted() calls can retry.
- ensureStarted: emit TorState.Error in the onFailure handler.
- onAppReady: wrap filter.first() in withTimeoutOrNull(90s); treat null as Error.

Tests added:
- TorManagerTest T6: ensureStarted emits Error when startService throws.
- WebViewViewModelTorTest T7: onAppReady surfaces error after 90s timeout.
- Fixed Test 2: replaced advanceUntilIdle() with runCurrent() between onAppReady()
  and the Ready emission to avoid accidentally firing the new timeout delay.

Author: smellouk

core/engine/build.gradle.kts

@@ -5,6 +5,13 @@ plugins {
 android {
     namespace = "io.shellify.core.engine"
 
+    testOptions {
+        unitTests {
+            // Prevents android.util.Log.* from throwing "not mocked" in JVM unit tests.
+            isReturnDefaultValues = true
+        }
+    }
+
     packaging {
         jniLibs {
             excludes += "**/libxul.so"

core/engine/src/main/java/io/shellify/app/core/engine/TorManager.kt

@@ -146,7 +146,11 @@ class TorManager(
                     val bound = context.bindService(intent, torServiceConnection, Context.BIND_AUTO_CREATE)
                     if (!bound) Log.w(TAG, "bindService returned false — process-death detection unavailable")
                 }
-            }.onFailure { Log.e(TAG, "Failed to start TorService", it) }
+            }.onFailure {
+                // Surface the failure so the UI can offer a retry instead of freezing on Connecting.
+                Log.e(TAG, "Failed to start TorService", it)
+                _torState.value = TorState.Error("Failed to start Tor: ${it.message}")
+            }
         }
     }
 
@@ -227,7 +231,11 @@ class TorManager(
     private fun registerStatusReceiver() {
         if (torReceiver != null) return
 
-        torReceiver = object : BroadcastReceiver() {
+        // Build the receiver locally so it is only assigned to torReceiver after successful
+        // registration. If registerReceiver() throws and we assigned torReceiver first, the
+        // null-guard at the top of this function would skip all future registration attempts,
+        // leaving _torState stuck at Connecting forever (no broadcasts would ever arrive).
+        val receiver = object : BroadcastReceiver() {
             override fun onReceive(ctx: Context, intent: Intent) {
                 val status = intent.getStringExtra(TorService.EXTRA_STATUS) ?: return
                 when (status) {
@@ -243,11 +251,17 @@ class TorManager(
         runCatching {
             ContextCompat.registerReceiver(
                 context,
-                torReceiver,
+                receiver,
                 IntentFilter(TorService.ACTION_STATUS),
                 ContextCompat.RECEIVER_NOT_EXPORTED,
             )
-        }.onFailure { Log.w(TAG, "Failed to register TorService receiver", it) }
+            // Assign only on success so a failed registration leaves torReceiver null
+            // and the next ensureStarted() call can attempt registration again.
+            torReceiver = receiver
+        }.onFailure {
+            Log.e(TAG, "Failed to register TorService receiver", it)
+            _torState.value = TorState.Error("Failed to listen for Tor status: ${it.message}")
+        }
     }
 
     private fun stop() {

core/engine/src/test/java/io/shellify/app/core/engine/TorManagerTest.kt

@@ -1,6 +1,8 @@
 package io.shellify.app.core.engine
 
 import android.content.ComponentName
+import android.content.Context
+import io.mockk.every
 import io.mockk.mockk
 import io.mockk.verify
 import kotlinx.coroutines.ExperimentalCoroutinesApi
@@ -92,4 +94,21 @@ class TorManagerTest {
         val state = manager.torState.value
         assertTrue("Expected TorState.Error but got $state", state is TorState.Error)
     }
+
+    @Test
+    fun `T6 - ensureStarted emits TorState Error when startService throws`() = testScope.runTest {
+        // Arrange: context.startService throws (e.g. IllegalStateException from background start).
+        val context = mockk<Context>(relaxed = true) {
+            every { startService(any()) } throws IllegalStateException("Not allowed in background")
+        }
+        val manager = TorManager(context = context, testScope = testScope)
+
+        // Act
+        manager.ensureStarted(appId = 1L, preserveIdentity = false)
+        testDispatcher.scheduler.advanceUntilIdle()
+
+        // Assert: error is surfaced so the UI can show Retry instead of freezing on Connecting.
+        val state = manager.torState.value
+        assertTrue("Expected TorState.Error after startService failure but got $state", state is TorState.Error)
+    }
 }

feature/webview/src/main/java/io/shellify/app/presentation/webview/WebViewViewModel.kt

@@ -25,6 +25,7 @@ import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withTimeoutOrNull
 
 class WebViewViewModel(
     private val initialApp: WebApp,
@@ -221,7 +222,12 @@ class WebViewViewModel(
                 // This is the critical gate that prevents DNS and traffic leaks (T-02-23).
                 // Also handles TorState.Error so the coroutine is not suspended indefinitely
                 // when TorService fails to start (CR-02).
-                val state = tm.torState.filter { it is TorState.Ready || it is TorState.Error }.first()
+                // withTimeoutOrNull guards against TorService hanging silently (e.g. native
+                // binary crash with no onServiceDisconnected, or registerReceiver failure) —
+                // without it the overlay freezes the UI forever (CR-07).
+                val state = withTimeoutOrNull(TOR_STARTUP_TIMEOUT_MS) {
+                    tm.torState.filter { it is TorState.Ready || it is TorState.Error }.first()
+                } ?: TorState.Error("Tor startup timed out after ${TOR_STARTUP_TIMEOUT_MS / 1_000}s")
                 if (state is TorState.Error) {
                     _uiState.update { it.copy(error = WebLoadError.from(-1, state.message)) }
                     return@launch
@@ -367,6 +373,15 @@ class WebViewViewModel(
 
     private fun currentApp(): WebApp = _uiState.value.app ?: initialApp
 
+    companion object {
+        /**
+         * Maximum time to wait for [TorState.Ready] or [TorState.Error] before aborting.
+         * Prevents the Tor connecting overlay from freezing the UI indefinitely when
+         * TorService hangs or crashes without emitting a status broadcast (CR-07).
+         */
+        internal const val TOR_STARTUP_TIMEOUT_MS = 90_000L
+    }
+
     class Factory(
         private val app: WebApp,
         private val services: WebViewServiceProvider,

feature/webview/src/test/java/io/shellify/app/presentation/webview/WebViewViewModelTorTest.kt

@@ -20,13 +20,16 @@ import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.test.StandardTestDispatcher
 import kotlinx.coroutines.test.TestScope
+import kotlinx.coroutines.test.advanceTimeBy
 import kotlinx.coroutines.test.advanceUntilIdle
 import kotlinx.coroutines.test.resetMain
+import kotlinx.coroutines.test.runCurrent
 import kotlinx.coroutines.test.runTest
 import kotlinx.coroutines.test.setMain
 import org.junit.After
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
 import org.junit.Before
 import org.junit.Test
 
@@ -130,20 +133,26 @@ class WebViewViewModelTorTest {
     fun `when useTor true, onAppReady gates LoadUrl on TorState Ready`() = testScope.runTest {
         torStateFlow.value = TorState.Connecting
         val vm = createViewModel(torApp)
-        advanceUntilIdle()
+        advanceUntilIdle()  // Safe: no withTimeoutOrNull in play yet during vm init.
 
         vm.onAppReady(torApp)
-        advanceUntilIdle()
+        // Use runCurrent() instead of advanceUntilIdle() here and below.
+        // advanceUntilIdle() advances virtual time through ALL pending delays, including
+        // the TOR_STARTUP_TIMEOUT_MS delay, which would fire the timeout and emit an error
+        // before TorState.Ready ever arrives — causing a false failure.
+        runCurrent()
 
         // Should NOT have emitted LoadUrl yet while Connecting
         val commands = mutableListOf<WebViewCommand>()
         val job = launch { vm.commands.collect { commands += it } }
 
         // No LoadUrl should be emitted while Connecting
-        advanceUntilIdle()
+        runCurrent()
         assertFalse("No LoadUrl while Connecting", commands.any { it is WebViewCommand.LoadUrl })
 
-        // Emit Ready — now LoadUrl should be dispatched
+        // Emit Ready — now LoadUrl should be dispatched.
+        // advanceUntilIdle() is safe here because withTimeoutOrNull cancels its internal timer
+        // the moment filter.first() returns TorState.Ready, leaving no residual delayed tasks.
         torStateFlow.value = TorState.Ready
         advanceUntilIdle()
 
@@ -218,4 +227,31 @@ class WebViewViewModelTorTest {
         advanceUntilIdle()
         assertEquals(TorState.Ready, vm.uiState.value.torState)
     }
+
+    /**
+     * Test 7: When TorService never emits Ready or Error within TOR_STARTUP_TIMEOUT_MS,
+     * onAppReady must surface a WebLoadError instead of freezing the UI forever (CR-07).
+     */
+    @Test
+    fun `when tor startup exceeds timeout, onAppReady surfaces error instead of freezing`() =
+        testScope.runTest {
+            // TorService is stuck at Connecting — no Ready/Error broadcast ever arrives.
+            torStateFlow.value = TorState.Connecting
+            val vm = createViewModel(torApp)
+            runCurrent()  // Run vm init without advancing virtual time.
+
+            vm.onAppReady(torApp)
+            runCurrent()  // Run the coroutine to its filter.first() suspension point.
+
+            // Just before the deadline: no error yet.
+            // advanceTimeBy runs all tasks that become due at the new virtual time, so
+            // no explicit runCurrent() is needed after it.
+            advanceTimeBy(WebViewViewModel.TOR_STARTUP_TIMEOUT_MS - 1_000L)
+            assertEquals(null, vm.uiState.value.error)
+
+            // Cross the deadline: timeout fires, withTimeoutOrNull returns null, error is set.
+            advanceTimeBy(2_000L)
+            val error = vm.uiState.value.error
+            assertTrue("Expected a WebLoadError after timeout but got $error", error != null)
+        }
 }