fix(overlay): show the Possible spam warning only once a call will ring

HeuristicChecker started the incoming overlay in the middle of the
checker pipeline, so a mid-band call that a lower-priority checker
(campaign burst, caller name, ML) then rejected flashed the warning
until the rejection withdrew it. The checker now records the score and
reason on CheckContext.suspicion, SpamRepositoryImpl carries it on the
SpamCheckResult, and the screening service shows it after the verdict:
on an allow, on a silence, and never on a reject.

Test changes: the setUp overlay launcher lambda now takes the live
lookup flag, because the screening service passes it where the
heuristic used to read it itself, and tearDown resets the shared hot
ranges the new tests seed. Three new tests cover a mid-band call that
rings, one a later check rejects and one it silences. No existing test
assertion changed. With the old direct overlay start put back, the
reject and ring tests fail.

Author: SysAdminDoc

CHANGELOG.md

@@ -4,6 +4,7 @@ All notable changes to CallShield will be documented in this file.
 
 ## Unreleased
 
+- The "Possible spam" popup no longer flashes up for a moment on a call that CallShield then rejects. It used to open while the call was still being checked, so a later check that rejected the call left it on screen until it was taken back. Now it waits until the call is going to ring, or go to silent voicemail, and a rejected call never shows it.
 - With TalkBack on and a large font size, the bottom tabs other than the open one had no name for TalkBack to read. At 150% and up the bar shows just the open tab's label, and the others now read their names from their icons. At normal sizes each tab still reads its name once.
 - Tapping Not spam on a blocked call alert for a number you blocked yourself now shows a short "Your own block still applies." and turns the alert into a notification that explains why. Tap it and the number opens in CallShield, where you can remove the block. The old message was a toast, and Android 12 and later cut it off after two lines, so the part about where to remove the block never showed. The Not spam and empty crash log messages are shorter too, so they fit at the largest font size.
 - The caller ID popup no longer stays up for 20 seconds after CallShield rejects a call it first showed as possible spam. A rejected call never rings, so nothing told the popup the call was over, and it kept offering Block for a call that was already gone. It closes as soon as the call is rejected now.

README.md

@@ -12,7 +12,7 @@
 <p align="center">
   <a href="https://github.com/SysAdminDoc/CallShield/releases/latest"><img src="https://img.shields.io/github/v/release/SysAdminDoc/CallShield?style=flat-square&color=a6e3a1" alt="Release"></a>
   <img src="https://img.shields.io/badge/Spam%20Numbers-51%2C403-f38ba8?style=flat-square" alt="51,403 Numbers">
-  <img src="https://img.shields.io/badge/JVM%20unit%20tests-2071-94e2d5?style=flat-square" alt="2071 JVM unit tests">
+  <img src="https://img.shields.io/badge/JVM%20unit%20tests-2074-94e2d5?style=flat-square" alt="2074 JVM unit tests">
   <img src="https://img.shields.io/badge/Android-10%2B-89b4fa?style=flat-square" alt="Android 10+">
   <img src="https://img.shields.io/badge/License-MIT-cba6f7?style=flat-square" alt="MIT License">
   <img src="https://img.shields.io/badge/API%20Keys-None-fab387?style=flat-square" alt="No required API keys">
@@ -592,12 +592,12 @@ RELEASE_KEY_PASSWORD=...
 ## Testing
 
 ```bash
-./gradlew testDebugUnitTest   # 2071 tests
+./gradlew testDebugUnitTest   # 2074 tests
 ./gradlew connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.sysadmindoc.callshield.platform.TargetSdkBehaviorSmokeTest
 ./gradlew verifyPipelineTests # Cloudflare Worker (node) + data-pipeline and translation checks (python)
 ```
 
-The suite is **2071 total JVM unit tests**, run with Robolectric wherever a screen, a service or the database is involved.
+The suite is **2074 total JVM unit tests**, run with Robolectric wherever a screen, a service or the database is involved.
 
 Two GitHub workflows run without building the app. **Validation** runs the Worker and
 pipeline suites on every push except report-only ones (`run-pipeline-tests.ps1 -CorrectnessOnly`),
@@ -634,7 +634,7 @@ language in [issue #7](https://github.com/SysAdminDoc/CallShield/issues/7).
 | Community API | Cloudflare Workers |
 | URL Safety | Local spam-domain data, with optional PhishTank and OpenPhish |
 | Verification | Local Gradle, lint, and release-artifact checks |
-| Tests | 2071 JVM unit tests (JUnit) |
+| Tests | 2074 JVM unit tests (JUnit) |
 | Strings | 1796 string resources and 49 plural groups (translation-ready) |
 | Accessibility | 100+ content descriptions, 48dp touch targets |
 | Min SDK | 29 (Android 10) |

app/src/main/java/com/sysadmindoc/callshield/data/checker/Checkers.kt

@@ -27,8 +27,8 @@ import com.sysadmindoc.callshield.data.SpamRepository
 import com.sysadmindoc.callshield.data.SystemBlockList
 import com.sysadmindoc.callshield.data.model.SpamNumber
 import com.sysadmindoc.callshield.data.repository.SpamRepositoryImpl
+import com.sysadmindoc.callshield.domain.model.CallSuspicion
 import com.sysadmindoc.callshield.permissions.CallShieldPermissions
-import com.sysadmindoc.callshield.service.CallerIdOverlayService
 import com.sysadmindoc.callshield.ui.describeIdentityEvidence
 import com.sysadmindoc.callshield.ui.joinSignalLabels
 import com.sysadmindoc.callshield.ui.signalLabel
@@ -1046,17 +1046,13 @@ internal class HeuristicChecker(
             )
         }
 
-        // Suspicious-but-not-blocked overlay (realtime CALLS only, score 30..threshold).
+        // Suspicious-but-not-blocked warning (realtime CALLS only, score 30..threshold).
         // Guard on smsBody == null so a suspicious SMS re-scored through the shared
         // chain never pops an incoming-call overlay or fires live caller lookups.
+        // The screening service shows it once it knows a later checker didn't
+        // reject the call, so a rejected call never flashes it.
         if (ctx.realtimeCall && ctx.smsBody == null && hResult.score in 30 until threshold) {
-            showCallerIdOverlay(
-                appContext,
-                ctx.number,
-                hResult.score,
-                hResult.reasons.firstOrNull() ?: "suspicious",
-                ctx.prefs[SpamRepository.KEY_LIVE_CALLER_ENRICHMENT] ?: false,
-            )
+            ctx.suspicion = CallSuspicion(hResult.score, hResult.reasons.firstOrNull() ?: "suspicious")
         }
         return null
     }
@@ -1082,20 +1078,6 @@ internal class HeuristicChecker(
                 (ctx.prefs[SpamRepository.KEY_SMS_CONTENT] ?: true) && !ctx.smsContextTrusted
             }
     }
-
-    private fun showCallerIdOverlay(
-        ctx: Context,
-        number: String,
-        confidence: Int,
-        reason: String,
-        liveEnrichmentEnabled: Boolean,
-    ) {
-        try {
-            CallerIdOverlayService.startIncoming(ctx, number, confidence, reason, liveEnrichmentEnabled)
-        } catch (_: Exception) {
-            // overlay is best-effort
-        }
-    }
 }
 
 internal class CampaignBurstChecker(

app/src/main/java/com/sysadmindoc/callshield/data/checker/IChecker.kt

@@ -8,6 +8,7 @@ import com.sysadmindoc.callshield.data.SenderProvenance
 import com.sysadmindoc.callshield.data.SpamRepository
 import com.sysadmindoc.callshield.data.repository.SpamRepositoryImpl
 import com.sysadmindoc.callshield.domain.model.BlockReasonCode
+import com.sysadmindoc.callshield.domain.model.CallSuspicion
 import com.sysadmindoc.callshield.domain.model.CallerIdentity
 import com.sysadmindoc.callshield.domain.model.ScreeningDiagnostics
 import kotlinx.coroutines.CancellationException
@@ -154,6 +155,13 @@ data class CheckContext(
     /** Shared plan classification for NANP-only checkers in this evaluation. */
     val numberingPlan: NumberingPlan = NumberingPlan.from(number, homeRegionIso)
 
+    /**
+     * Set by [HeuristicChecker] when a live call scores too low to block. A
+     * later checker can still block the call, so the screening service shows
+     * it only once the call is going to ring.
+     */
+    var suspicion: CallSuspicion? = null
+
     /**
      * Forms to try when matching stored numbers exactly, canonical first.
      * Allow and block lookups both use it, so a number saved in any form

app/src/main/java/com/sysadmindoc/callshield/data/repository/SpamRepositoryImpl.kt

@@ -264,10 +264,10 @@ class SpamRepositoryImpl(
         val pipelineRun = CheckerPipeline.runWithDiagnostics(callChain, ctx)
         val verdict = pipelineRun.result
         if (verdict == null) {
-            return SpamCheckResult(isSpam = false, screeningDiagnostics = pipelineRun.diagnostics)
+            return SpamCheckResult(isSpam = false, screeningDiagnostics = pipelineRun.diagnostics, suspicion = ctx.suspicion)
         }
 
-        val result = verdict.toSpamCheckResult(pipelineRun.diagnostics)
+        val result = verdict.toSpamCheckResult(pipelineRun.diagnostics).copy(suspicion = ctx.suspicion)
         return if (smsBody == null) CategoryCallPolicy.apply(result, prefs) else result
     }
 

app/src/main/java/com/sysadmindoc/callshield/domain/model/SpamCheckResult.kt

@@ -11,4 +11,12 @@ data class SpamCheckResult(
     val screeningDiagnostics: ScreeningDiagnostics? = null,
     /** Raw signal tokens behind a scored block; [description] is display text. */
     val signals: List<String> = emptyList(),
+    /** A live call's below-threshold heuristic score, shown only if the call goes on to ring. */
+    val suspicion: CallSuspicion? = null,
+)
+
+/** A heuristic [score] too low to block, and the first [reason] behind it. */
+data class CallSuspicion(
+    val score: Int,
+    val reason: String,
 )

app/src/main/java/com/sysadmindoc/callshield/service/CallShieldScreeningService.kt

@@ -22,6 +22,7 @@ import com.sysadmindoc.callshield.data.areacodes.AreaCodeLookup
 import com.sysadmindoc.callshield.data.checker.MeetingModeChecker
 import com.sysadmindoc.callshield.data.local.AppDatabase
 import com.sysadmindoc.callshield.di.ApplicationScope
+import com.sysadmindoc.callshield.domain.model.CallSuspicion
 import com.sysadmindoc.callshield.domain.model.CallerIdentity
 import com.sysadmindoc.callshield.domain.usecase.CheckSpamUseCase
 import com.sysadmindoc.callshield.permissions.CallShieldPermissions
@@ -71,9 +72,9 @@ class CallShieldScreeningService : CallScreeningService() {
         }
 
     /** Kept injectable so the RTT contract can prove that no overlay is launched. */
-    internal var incomingOverlayLauncher: (android.content.Context, String, Int, String) -> Unit =
-        { context, number, confidence, reason ->
-            CallerIdOverlayService.startIncoming(context, number, confidence, reason)
+    internal var incomingOverlayLauncher: (android.content.Context, String, Int, String, Boolean) -> Unit =
+        { context, number, confidence, reason, liveEnrichment ->
+            CallerIdOverlayService.startIncoming(context, number, confidence, reason, liveEnrichment)
         }
 
     /** Kept injectable so a test can see which calls take their overlay back. */
@@ -250,6 +251,7 @@ class CallShieldScreeningService : CallScreeningService() {
                                 CategoryCallPolicy.parseMatchSource(result.matchSource)?.action
                                     ?: CategoryCallAction.INHERIT
                             if (categoryAction == CategoryCallAction.ALLOW) {
+                                result.suspicion?.let { showSuspicion(number, it, prefs) }
                                 respondAllow(responseGate)
                                 CodeDuringCallWarning.onCallAllowed(applicationScope, appContext, number, result.matchSource)
                                 logPipelineDiagnostic(repository, number, result.screeningDiagnostics?.toWireValue())
@@ -264,21 +266,27 @@ class CallShieldScreeningService : CallScreeningService() {
                                     pipelineDiagnostic = result.screeningDiagnostics?.toWireValue(),
                                     prefs = prefs,
                                     callerIdentity = callerIdentity,
+                                    suspicion = result.suspicion,
                                 )
                             }
                         } else {
                             val repeatedUrgentAllow = result.matchSource == "repeated_urgent"
                             val suppressFeedback = shouldSuppressAfterCallFeedback(result.matchSource)
-                            // Unknown non-contact caller — area-code-only caller ID overlay.
-                            // A number other users reported gets it even with no area code
-                            // to name, since the popup is where its label shows.
-                            val location =
-                                AreaCodeLookup.lookup(number, PhoneIdentityCanonicalizer.cachedFromContext(appContext).homeRegionIso)
-                                    ?: "".takeIf { heuristics().communityWatchReporterCount(appContext, number) >= SpamHeuristics.COMMUNITY_WATCH_MIN_REPORTERS }
-                            if (location != null) {
-                                try {
-                                    incomingOverlayLauncher(appContext, number, 0, location)
-                                } catch (_: Exception) {
+                            val suspicion = result.suspicion
+                            if (suspicion != null) {
+                                showSuspicion(number, suspicion, prefs)
+                            } else {
+                                // Unknown non-contact caller — area-code-only caller ID overlay.
+                                // A number other users reported gets it even with no area code
+                                // to name, since the popup is where its label shows.
+                                val location =
+                                    AreaCodeLookup.lookup(number, PhoneIdentityCanonicalizer.cachedFromContext(appContext).homeRegionIso)
+                                        ?: "".takeIf { heuristics().communityWatchReporterCount(appContext, number) >= SpamHeuristics.COMMUNITY_WATCH_MIN_REPORTERS }
+                                if (location != null) {
+                                    try {
+                                        incomingOverlayLauncher(appContext, number, 0, location, false)
+                                    } catch (_: Exception) {
+                                    }
                                 }
                             }
                             respondAllow(responseGate)
@@ -378,6 +386,7 @@ class CallShieldScreeningService : CallScreeningService() {
         pipelineDiagnostic: String? = null,
         prefs: androidx.datastore.preferences.core.Preferences,
         callerIdentity: CallerIdentity? = null,
+        suspicion: CallSuspicion? = null,
     ) {
         val repository = repository()
         val logTimestamp = System.currentTimeMillis()
@@ -476,10 +485,12 @@ class CallShieldScreeningService : CallScreeningService() {
                     ),
                     number,
                     reason,
+                    suspicion,
+                    prefs,
                 )
             }
         } else {
-            respondRinging(responseGate, response, number, reason)
+            respondRinging(responseGate, response, number, reason, suspicion, prefs)
         }
 
         applicationScope.launch {
@@ -817,15 +828,17 @@ class CallShieldScreeningService : CallScreeningService() {
 
     /**
      * Sends a block [response]. A silenced call still reaches the phone and can
-     * be answered, so it's watched for one-time codes like an allowed one. A
-     * rejected call never rings, so an overlay a checker opened for it while
-     * screening ran is taken back.
+     * be answered, so it's watched for one-time codes like an allowed one, and
+     * gets the [suspicion] warning. A rejected call never rings, so it gets no
+     * overlay, and one still up for the same caller is taken back.
      */
     private fun respondRinging(
         responseGate: ScreeningResponseGate<CallResponse>,
         response: CallResponse,
         number: String,
         reason: String,
+        suspicion: CallSuspicion?,
+        prefs: androidx.datastore.preferences.core.Preferences,
     ) {
         val unanswered = !responseGate.hasResponded
         responseGate.respond(response)
@@ -837,6 +850,27 @@ class CallShieldScreeningService : CallScreeningService() {
                 incomingOverlayWithdrawer(applicationContext, number)
             } catch (_: Exception) {
             }
+        } else if (unanswered && suspicion != null) {
+            showSuspicion(number, suspicion, prefs)
+        }
+    }
+
+    /** Shows the "Possible spam" overlay for a call screening let ring. */
+    private fun showSuspicion(
+        number: String,
+        suspicion: CallSuspicion,
+        prefs: androidx.datastore.preferences.core.Preferences,
+    ) {
+        try {
+            incomingOverlayLauncher(
+                applicationContext,
+                number,
+                suspicion.score,
+                suspicion.reason,
+                prefs[SpamRepository.KEY_LIVE_CALLER_ENRICHMENT] ?: false,
+            )
+        } catch (_: Exception) {
+            // The overlay is best effort.
         }
     }
 

app/src/main/java/com/sysadmindoc/callshield/service/CallerIdOverlayService.kt

@@ -292,12 +292,10 @@ class CallerIdOverlayService : Service() {
 
     // What the active session is showing, so a later start for the SAME
     // caller with LESS information can be ignored instead of tearing the
-    // session down. Concretely: HeuristicChecker shows a "Possible spam N%"
-    // overlay for mid-band scores during checkSpam(), then the screening
-    // service's not-spam path fires the generic area-code overlay
-    // (confidence 0) for every NANP caller — without this guard the second
-    // start destroyed the suspicion warning before the user could read it
-    // and restarted the live lookups from scratch.
+    // session down. Concretely: a generic area-code start (confidence 0)
+    // arriving after a "Possible spam N%" warning for the same caller would
+    // otherwise destroy the warning before the user could read it and
+    // restart the live lookups from scratch.
     @Volatile private var activeNumber: String = ""
 
     @Volatile private var activeConfidence = 0
@@ -730,7 +728,8 @@ class CallerIdOverlayService : Service() {
         // Auto-dismiss after 20 seconds (backstop). The call-state watcher below
         // dismisses sooner, right when the call ends, so a 2-3 s silenced call's
         // overlay doesn't hover over unrelated UI for the full 20 s. A call that
-        // screening rejects never rings, so it's closed by withdrawIncoming().
+        // screening rejects never rings and gets no overlay, and one still up
+        // for the same caller is closed by withdrawIncoming().
         scheduleDismiss(sessionId, AUTO_DISMISS_MS)
         registerCallStateWatcher(sessionId, outgoingRiskWarning)
         return sessionId