From 65eae0f6c76e5e56ff33f6e3c6b32aa60a3f6810 Mon Sep 17 00:00:00 2001
From: Jason Ross <jason.ross841@gmail.com>
Date: Wed, 8 Jul 2026 19:04:13 -0500
Subject: [PATCH 1/3] test(accountsetup): de-flake URL-open link E2E tests via
 fake LocalUriHandler

The outbound-link E2E tests verified the opened page with Espresso-Intents
(intending(ACTION_VIEW).respondWith(...) + intended(...)). intended() runs an
onView(isRoot()).check(...) whose RootViewPicker waits up to 10s for a
window-focused root. On the CI matrix emulator the activity window
intermittently reports has-window-focus=false, so the assertion flakes with
RootViewPicker$RootViewWithoutFocusException, failing the whole E2E leg and
forcing a 9-min retry. The intent stubs were already present and do NOT fix
this: no external activity launches, the focus loss is environmental (the same
run failed 8 unrelated RootViewPicker-based tests at once).

Verify these ACTION_VIEW/browser-open link taps by injecting a recording
LocalUriHandler and asserting the exact URL the screen opens. That keeps the
tests entirely on Compose interactions, which do not depend on window focus
(280+ Compose-only tests passed in the same failing run), so they are
deterministic without weakening the assertion (still asserts the provider
page / host).

Converted (ACTION_VIEW / UriHandler "browser-open" shape):
- AppPasswordSetupScreenTest.tappingCreateAppPasswordPage_launchesBrowserIntentToHelpUrl
- AppPasswordSetupScreenTest.imapDisabledFailure_showsThePrompt_andHelpLinkOpensTheProviderPage
- OutlookImapNoticeScreenTest.tappingImapHelpLink_opensTheMicrosoftArticle

Real-intent tests (hasComponent/Settings action, no UriHandler seam) keep
Espresso-Intents and are out of scope here.
---
 .../AppPasswordSetupScreenTest.kt             | 83 ++++++++++---------
 .../onboarding/OutlookImapNoticeScreenTest.kt | 70 +++++++++-------
 2 files changed, 88 insertions(+), 65 deletions(-)

diff --git a/app/src/androidTest/kotlin/org/libremail/ui/accountsetup/AppPasswordSetupScreenTest.kt b/app/src/androidTest/kotlin/org/libremail/ui/accountsetup/AppPasswordSetupScreenTest.kt
index 4a09675..9afcdbe 100644
--- a/app/src/androidTest/kotlin/org/libremail/ui/accountsetup/AppPasswordSetupScreenTest.kt
+++ b/app/src/androidTest/kotlin/org/libremail/ui/accountsetup/AppPasswordSetupScreenTest.kt
@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 package org.libremail.ui.accountsetup
 
-import android.app.Activity
-import android.app.Instrumentation
-import android.content.Intent
+import android.net.Uri
 import androidx.activity.ComponentActivity
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.ui.platform.LocalUriHandler
+import androidx.compose.ui.platform.UriHandler
 import androidx.compose.ui.test.assertIsDisplayed
 import androidx.compose.ui.test.junit4.v2.createAndroidComposeRule
 import androidx.compose.ui.test.onAllNodesWithText
@@ -13,14 +14,9 @@ import androidx.compose.ui.test.performClick
 import androidx.compose.ui.test.performScrollTo
 import androidx.compose.ui.test.performTextInput
 import androidx.lifecycle.SavedStateHandle
-import androidx.test.espresso.intent.Intents
-import androidx.test.espresso.intent.matcher.IntentMatchers.hasAction
-import androidx.test.espresso.intent.matcher.IntentMatchers.hasData
-import androidx.test.espresso.intent.matcher.UriMatchers.hasHost
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import jakarta.mail.AuthenticationFailedException
-import org.hamcrest.CoreMatchers.allOf
-import org.hamcrest.CoreMatchers.equalTo
+import org.junit.Assert.assertEquals
 import org.junit.Rule
 import org.junit.Test
 import org.junit.runner.RunWith
@@ -35,8 +31,17 @@ import org.libremail.ui.theme.LibreMailTheme
  * [AppPasswordSetupScreen] + [AppPasswordViewModel] over a [FakeAccountRepository] for the preset
  * Gmail vendor: the provider-specific chrome renders, entering an email + app password and tapping
  * "Test & add" persists through the repository and reports the new account id, and tapping the
- * "create an app password" help link fires the browser intent. That launch is asserted with
- * Espresso-Intents (mirroring `AccountPickerScreenTest`'s Outlook test), so no real browser opens.
+ * "create an app password" help link opens the provider's help page.
+ *
+ * The outbound help links are verified by injecting a recording [UriHandler] for [LocalUriHandler]
+ * and asserting the URL the screen asked to open — deliberately NOT via Espresso-Intents. The two
+ * approaches verify the same behaviour, but `Intents.intended(...)` runs an `onView(isRoot())` view
+ * assertion whose `RootViewPicker` waits up to 10s for a window-focused root; on the CI emulator the
+ * activity window intermittently reports `has-window-focus=false`, so that assertion flakes with
+ * `RootViewWithoutFocusException` (an infra flake that fails every `intended()`-based E2E test on the
+ * affected leg and forces a costly 9-min retry). Driving the link through a fake [UriHandler] keeps
+ * the whole test on Compose interactions, which do not depend on window focus, so it is deterministic
+ * — while still asserting the exact provider page the tap opens.
  */
 @RunWith(AndroidJUnit4::class)
 class AppPasswordSetupScreenTest {
@@ -46,6 +51,9 @@ class AppPasswordSetupScreenTest {
 
     private val provider = MailProvider.GMAIL
 
+    // Captures the URL the screen hands to LocalUriHandler instead of launching a real browser.
+    private val uriHandler = RecordingUriHandler()
+
     private fun string(resId: Int, vararg args: Any) = composeTestRule.activity.getString(resId, *args)
 
     private fun setContent(
@@ -57,8 +65,10 @@ class AppPasswordSetupScreenTest {
             repository,
         )
         composeTestRule.setContent {
-            LibreMailTheme(darkTheme = false, dynamicColor = false) {
-                AppPasswordSetupScreen(onBack = {}, onAccountAdded = onAccountAdded, viewModel = viewModel)
+            CompositionLocalProvider(LocalUriHandler provides uriHandler) {
+                LibreMailTheme(darkTheme = false, dynamicColor = false) {
+                    AppPasswordSetupScreen(onBack = {}, onAccountAdded = onAccountAdded, viewModel = viewModel)
+                }
             }
         }
     }
@@ -90,34 +100,29 @@ class AppPasswordSetupScreenTest {
     }
 
     /**
-     * Tapping the "create an app password" link opens the provider's help page via
-     * [androidx.compose.ui.platform.UriHandler], which starts an `ACTION_VIEW` intent. Stubbing that
-     * intent both proves the tap launched it and stops a real browser from opening on the device.
+     * Tapping the "create an app password" link opens the provider's help page via [LocalUriHandler].
+     * Asserting the URL captured by [RecordingUriHandler] proves the tap requested the right page
+     * without launching a real browser (and without the window-focus-dependent Espresso-Intents
+     * assertion that flakes on CI — see the class comment).
      */
     @Test
     fun tappingCreateAppPasswordPage_launchesBrowserIntentToHelpUrl() {
         setContent()
 
-        Intents.init()
-        try {
-            Intents.intending(hasAction(Intent.ACTION_VIEW))
-                .respondWith(Instrumentation.ActivityResult(Activity.RESULT_CANCELED, null))
+        composeTestRule.onNodeWithText(string(R.string.app_password_open_page, provider.displayName))
+            .performScrollTo()
+            .performClick()
 
-            composeTestRule.onNodeWithText(string(R.string.app_password_open_page, provider.displayName))
-                .performScrollTo()
-                .performClick()
-
-            Intents.intended(allOf(hasAction(Intent.ACTION_VIEW), hasData(provider.appPasswordHelpUrl)))
-        } finally {
-            Intents.release()
-        }
+        assertEquals(provider.appPasswordHelpUrl, uriHandler.lastUri)
     }
 
     /**
      * When the connection test fails specifically because IMAP is disabled (Gmail's "not enabled for
      * IMAP use"), the screen surfaces the actionable "turn on IMAP" dialog instead of a generic error,
      * and its help link opens the provider's enable-IMAP page (#390). Driving the failure through a
-     * [FakeAccountRepository] exercises the real classification + dialog wiring end to end on device.
+     * [FakeAccountRepository] exercises the real classification + dialog wiring end to end on device;
+     * the help link's target is verified through the injected [RecordingUriHandler] (see the class
+     * comment for why not Espresso-Intents).
      */
     @Test
     fun imapDisabledFailure_showsThePrompt_andHelpLinkOpensTheProviderPage() {
@@ -138,16 +143,20 @@ class AppPasswordSetupScreenTest {
         }
         composeTestRule.onNodeWithText(string(R.string.imap_disabled_message, provider.displayName)).assertIsDisplayed()
 
-        Intents.init()
-        try {
-            Intents.intending(hasAction(Intent.ACTION_VIEW))
-                .respondWith(Instrumentation.ActivityResult(Activity.RESULT_CANCELED, null))
+        composeTestRule.onNodeWithText(string(R.string.imap_disabled_help)).performClick()
 
-            composeTestRule.onNodeWithText(string(R.string.imap_disabled_help)).performClick()
+        // Mirrors the previous Espresso hasHost(...) check: the Gmail enable-IMAP page is on Google's
+        // support host. Verifying the exact host keeps the assertion strength without any focus wait.
+        assertEquals("support.google.com", Uri.parse(uriHandler.lastUri).host)
+    }
 
-            Intents.intended(allOf(hasAction(Intent.ACTION_VIEW), hasData(hasHost(equalTo("support.google.com")))))
-        } finally {
-            Intents.release()
+    /** A [UriHandler] that records the last opened URL instead of starting a real `ACTION_VIEW` intent. */
+    private class RecordingUriHandler : UriHandler {
+        var lastUri: String? = null
+            private set
+
+        override fun openUri(uri: String) {
+            lastUri = uri
         }
     }
 }
diff --git a/app/src/androidTest/kotlin/org/libremail/ui/onboarding/OutlookImapNoticeScreenTest.kt b/app/src/androidTest/kotlin/org/libremail/ui/onboarding/OutlookImapNoticeScreenTest.kt
index 5670175..34d2dbe 100644
--- a/app/src/androidTest/kotlin/org/libremail/ui/onboarding/OutlookImapNoticeScreenTest.kt
+++ b/app/src/androidTest/kotlin/org/libremail/ui/onboarding/OutlookImapNoticeScreenTest.kt
@@ -4,23 +4,22 @@ package org.libremail.ui.onboarding
 import android.app.Activity
 import android.app.Instrumentation
 import android.content.Context
-import android.content.Intent
+import android.net.Uri
 import androidx.activity.ComponentActivity
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.ui.platform.LocalUriHandler
+import androidx.compose.ui.platform.UriHandler
 import androidx.compose.ui.test.assertIsDisplayed
 import androidx.compose.ui.test.junit4.v2.createAndroidComposeRule
 import androidx.compose.ui.test.onNodeWithText
 import androidx.compose.ui.test.performClick
 import androidx.compose.ui.test.performScrollTo
 import androidx.test.espresso.intent.Intents
-import androidx.test.espresso.intent.matcher.IntentMatchers.hasAction
 import androidx.test.espresso.intent.matcher.IntentMatchers.hasComponent
-import androidx.test.espresso.intent.matcher.IntentMatchers.hasData
-import androidx.test.espresso.intent.matcher.UriMatchers.hasHost
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import androidx.test.platform.app.InstrumentationRegistry
 import net.openid.appauth.AuthorizationManagementActivity
-import org.hamcrest.CoreMatchers.allOf
-import org.hamcrest.CoreMatchers.equalTo
+import org.junit.Assert.assertEquals
 import org.junit.Rule
 import org.junit.Test
 import org.junit.runner.RunWith
@@ -33,11 +32,18 @@ import org.libremail.ui.theme.LibreMailTheme
 /**
  * End-to-end UI test for the pre-auth Outlook IMAP-enablement notice (#411). Drives the real
  * [OutlookImapNoticeScreen] + [AccountSetupViewModel] over a [FakeAccountRepository]: the IMAP
- * question and both outbound links render, tapping a help link fires the browser `ACTION_VIEW`
- * intent, and tapping the bottom "Sign in" button starts the existing Microsoft OAuth (AppAuth)
- * flow. Both launches are asserted with Espresso-Intents (mirroring `AccountPickerScreenTest`), so no
- * real browser ever opens; the interstitial → OAuth navigation in the full onboarding graph is
- * covered by `OnboardingFlowTest`.
+ * question and both outbound links render, tapping the "How to enable IMAP" help link opens
+ * Microsoft's help article, and tapping the bottom "Sign in" button starts the existing Microsoft
+ * OAuth (AppAuth) flow.
+ *
+ * The help link is verified by injecting a recording [UriHandler] for [LocalUriHandler] and asserting
+ * the opened URL — not via Espresso-Intents, whose `intended(...)` runs an `onView(isRoot())`
+ * assertion that waits for a window-focused root and flakes with `RootViewWithoutFocusException` on
+ * the CI emulator (see `AppPasswordSetupScreenTest` for the full write-up). The "Sign in" launch has
+ * no [UriHandler] seam — AppAuth calls `startActivity` directly — so it stays on Espresso-Intents,
+ * matched by AppAuth's [AuthorizationManagementActivity] component and stubbed so no real browser
+ * opens; the interstitial → OAuth navigation in the full onboarding graph is covered by
+ * `OnboardingFlowTest`.
  */
 @RunWith(AndroidJUnit4::class)
 class OutlookImapNoticeScreenTest {
@@ -48,13 +54,18 @@ class OutlookImapNoticeScreenTest {
     private val context: Context =
         InstrumentationRegistry.getInstrumentation().targetContext.applicationContext
 
+    // Captures the URL the screen hands to LocalUriHandler instead of launching a real browser.
+    private val uriHandler = RecordingUriHandler()
+
     private fun string(resId: Int) = composeTestRule.activity.getString(resId)
 
     private fun setContent(onAccountAdded: (String) -> Unit = {}) {
         val viewModel = AccountSetupViewModel(OutlookAuthManager(context), FakeAccountRepository())
         composeTestRule.setContent {
-            LibreMailTheme(darkTheme = false, dynamicColor = false) {
-                OutlookImapNoticeScreen(onBack = {}, onAccountAdded = onAccountAdded, viewModel = viewModel)
+            CompositionLocalProvider(LocalUriHandler provides uriHandler) {
+                LibreMailTheme(darkTheme = false, dynamicColor = false) {
+                    OutlookImapNoticeScreen(onBack = {}, onAccountAdded = onAccountAdded, viewModel = viewModel)
+                }
             }
         }
     }
@@ -70,27 +81,20 @@ class OutlookImapNoticeScreenTest {
     }
 
     /**
-     * Tapping the "How to enable IMAP" link opens Microsoft's help article via
-     * [androidx.compose.ui.platform.UriHandler], which starts an `ACTION_VIEW` intent. Stubbing that
-     * intent both proves the tap launched it and stops a real browser from opening on the device.
+     * Tapping the "How to enable IMAP" link opens Microsoft's help article via [LocalUriHandler].
+     * Asserting the URL captured by [RecordingUriHandler] proves the tap requested the right page
+     * without launching a real browser (and without the window-focus-dependent Espresso-Intents
+     * assertion that flakes on CI — see the class comment).
      */
     @Test
     fun tappingImapHelpLink_opensTheMicrosoftArticle() {
         setContent()
 
-        Intents.init()
-        try {
-            Intents.intending(hasAction(Intent.ACTION_VIEW))
-                .respondWith(Instrumentation.ActivityResult(Activity.RESULT_CANCELED, null))
+        composeTestRule.onNodeWithText(string(R.string.outlook_imap_help))
+            .performScrollTo()
+            .performClick()
 
-            composeTestRule.onNodeWithText(string(R.string.outlook_imap_help))
-                .performScrollTo()
-                .performClick()
-
-            Intents.intended(allOf(hasAction(Intent.ACTION_VIEW), hasData(hasHost(equalTo("support.microsoft.com")))))
-        } finally {
-            Intents.release()
-        }
+        assertEquals("support.microsoft.com", Uri.parse(uriHandler.lastUri).host)
     }
 
     /**
@@ -118,4 +122,14 @@ class OutlookImapNoticeScreenTest {
             Intents.release()
         }
     }
+
+    /** A [UriHandler] that records the last opened URL instead of starting a real `ACTION_VIEW` intent. */
+    private class RecordingUriHandler : UriHandler {
+        var lastUri: String? = null
+            private set
+
+        override fun openUri(uri: String) {
+            lastUri = uri
+        }
+    }
 }
-- 
2.47.3


From b1a7931dfac27eec4cb5cc195d3e02af66b8d5e0 Mon Sep 17 00:00:00 2001
From: Jason Ross <jason.ross841@gmail.com>
Date: Wed, 8 Jul 2026 19:23:25 -0500
Subject: [PATCH 2/3] perf(gmail): respect Gmail IMAP connection & bandwidth
 limits in sync/backfill

Add Gmail's documented IMAP caps (15 max simultaneous connections, 2,500 MB/day
download, 500 MB/day upload, 10,000 messages/labels per limit) as provider-scoped
config/policy that feeds the existing #360/#356 pacing machinery instead of
reinventing it:

- GmailSyncLimits: pure constants + `appliesTo(account)` provider detection via the
  existing MailProvider.forImapHost lookup (no changes to MailProvider itself).
- GmailBandwidthTracker: a new, per-account/per-day download-byte tracker (mirrors
  AccountThrottleGate's shape: ConcurrentHashMap state, injectable clock, PII-free
  once-per-crossing AppLog breadcrumb). Proactive and orthogonal to the #360
  AccountThrottleGate (which only reacts to a provider-issued throttle) and #356's
  BackfillPacer (which paces slice cadence, not bytes) - same relationship
  InteractiveImapGate already documents having to AccountThrottleGate.

Wiring: MailRepositoryImpl.prefetchMessage (the single funnel both MailBackfiller
and MailSyncer's background prefetch already share) records bytes actually pulled
over the network for Gmail accounts; MailBackfiller/MailSyncer's prefetchIfEnabled
consult isOverDailyBudget once per account before starting a batch and defer
body/attachment prefetch for the rest of the day once Gmail's budget is reached -
header paging/sync is never gated, and interactive fetches (open, attachment tap,
inline images) are never gated either, matching the existing interactive-priority
principle (#355/#360).

The 15-connection cap is already satisfied by the existing architecture
(ImapConnectionCache keeps one reused connection per account plus one dedicated
IDLE connection - 2 total, well under the cap); GmailSyncLimitsTest pins that
invariant against the documented ceiling so a future change that grows per-account
concurrency trips a test before it could approach Gmail's real limit. The
10k-messages-per-label figure is captured as a documented constant only - it is
deliberately NOT wired into a backfill stop condition, since issue #12's full
history backfill is intentional and a large real mailbox can exceed 10k messages.

AccountThrottleGate, BackfillPacer, ThrottleClassifier/ThrottleSignal/ThrottleBackoff,
InteractiveImapGate, and MailProvider are all untouched.

Closes #361
---
 .../GmailBandwidthTrackerInstrumentedTest.kt  |  71 ++++++++++
 .../data/repository/MailRepositoryImpl.kt     |  33 ++++-
 .../data/sync/GmailBandwidthTracker.kt        |  88 ++++++++++++
 .../libremail/data/sync/GmailSyncLimits.kt    |  76 ++++++++++
 .../org/libremail/data/sync/MailBackfiller.kt |  16 ++-
 .../org/libremail/data/sync/MailSyncer.kt     |  12 ++
 .../repository/MailRepositoryGrantsTest.kt    |   2 +
 .../MailRepositoryImplCoverageTest.kt         |   2 +
 .../data/repository/MailRepositoryImplTest.kt |  47 +++++++
 .../data/sync/GmailBandwidthTrackerTest.kt    | 131 ++++++++++++++++++
 .../data/sync/GmailSyncLimitsTest.kt          |  58 ++++++++
 .../libremail/data/sync/MailBackfillerTest.kt |  56 +++++++-
 .../data/sync/MailMaintenanceGateTest.kt      |   1 +
 .../data/sync/MailSyncConcurrencyTest.kt      |   2 +
 .../org/libremail/data/sync/MailSyncerTest.kt |  44 +++++-
 config/detekt/detekt.yml                      |   3 +
 16 files changed, 632 insertions(+), 10 deletions(-)
 create mode 100644 app/src/androidTest/kotlin/org/libremail/data/sync/GmailBandwidthTrackerInstrumentedTest.kt
 create mode 100644 app/src/main/kotlin/org/libremail/data/sync/GmailBandwidthTracker.kt
 create mode 100644 app/src/main/kotlin/org/libremail/data/sync/GmailSyncLimits.kt
 create mode 100644 app/src/test/kotlin/org/libremail/data/sync/GmailBandwidthTrackerTest.kt
 create mode 100644 app/src/test/kotlin/org/libremail/data/sync/GmailSyncLimitsTest.kt

diff --git a/app/src/androidTest/kotlin/org/libremail/data/sync/GmailBandwidthTrackerInstrumentedTest.kt b/app/src/androidTest/kotlin/org/libremail/data/sync/GmailBandwidthTrackerInstrumentedTest.kt
new file mode 100644
index 0000000..feb2db3
--- /dev/null
+++ b/app/src/androidTest/kotlin/org/libremail/data/sync/GmailBandwidthTrackerInstrumentedTest.kt
@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+package org.libremail.data.sync
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.async
+import kotlinx.coroutines.awaitAll
+import kotlinx.coroutines.runBlocking
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.libremail.domain.model.Account
+import org.libremail.domain.model.MailProvider
+
+/**
+ * On-device proof of issue #361's Gmail bandwidth pacing across the CI API matrix. Production feeds
+ * [GmailBandwidthTracker] from `MailRepositoryImpl.prefetchMessage`, which can race across
+ * concurrently-syncing accounts under the real dispatcher, so this proves the tracker's
+ * concurrent-map-backed accounting holds up under genuine concurrent updates on real threads rather
+ * than coroutines-test virtual time (the JVM [GmailBandwidthTrackerTest] covers the day-rollover and
+ * threshold-crossing logic in detail). Also proves [GmailSyncLimits.appliesTo] resolves the real
+ * [MailProvider] presets identically to production. Deliberately mock-free — no `mockk`, no framework
+ * `Context` — the tracker's only collaborator is the real wall clock (mirrors
+ * `BackfillPacerInstrumentedTest`'s mock-free idiom).
+ */
+@RunWith(AndroidJUnit4::class)
+class GmailBandwidthTrackerInstrumentedTest {
+
+    @Test
+    fun concurrentDownloadsForOneAccountAllLandWithoutLosingAnUpdate() = runBlocking {
+        val tracker = GmailBandwidthTracker()
+        val perTask = 1_000L
+
+        val jobs = (1..CONCURRENT_TASKS).map {
+            async(Dispatchers.Default) { tracker.recordDownload("acct", perTask) }
+        }
+        jobs.awaitAll()
+
+        assertEquals(CONCURRENT_TASKS * perTask, tracker.bytesDownloadedToday("acct"))
+    }
+
+    @Test
+    fun accountsStayIsolatedUnderConcurrentRecording() = runBlocking {
+        val tracker = GmailBandwidthTracker()
+
+        val heavy = async(Dispatchers.Default) {
+            tracker.recordDownload("heavy", GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES)
+        }
+        val light = async(Dispatchers.Default) { tracker.recordDownload("light", 1L) }
+        heavy.await()
+        light.await()
+
+        assertTrue(tracker.isOverDailyBudget("heavy"))
+        assertFalse(tracker.isOverDailyBudget("light"))
+    }
+
+    @Test
+    fun appliesToResolvesTheRealGmailPresetOnDevice() {
+        val gmail = MailProvider.GMAIL.createAccount("user@gmail.com")
+        val outlook = Account.outlook("user@outlook.com")
+
+        assertTrue(GmailSyncLimits.appliesTo(gmail))
+        assertFalse(GmailSyncLimits.appliesTo(outlook))
+    }
+
+    private companion object {
+        const val CONCURRENT_TASKS = 50
+    }
+}
diff --git a/app/src/main/kotlin/org/libremail/data/repository/MailRepositoryImpl.kt b/app/src/main/kotlin/org/libremail/data/repository/MailRepositoryImpl.kt
index 1a0480a..de70bbd 100644
--- a/app/src/main/kotlin/org/libremail/data/repository/MailRepositoryImpl.kt
+++ b/app/src/main/kotlin/org/libremail/data/repository/MailRepositoryImpl.kt
@@ -39,6 +39,8 @@ import org.libremail.data.local.toOutgoingAttachments
 import org.libremail.data.local.toOutgoingAttachmentsJson
 import org.libremail.data.settings.AccountSettingsRepository
 import org.libremail.data.settings.SignatureRepository
+import org.libremail.data.sync.GmailBandwidthTracker
+import org.libremail.data.sync.GmailSyncLimits
 import org.libremail.data.sync.InteractiveImapGate
 import org.libremail.data.sync.MailConnectionFactory
 import org.libremail.data.sync.SendScheduler
@@ -81,6 +83,7 @@ class MailRepositoryImpl @Inject constructor(
     private val signatureRepository: SignatureRepository,
     private val attachmentUriGrants: AttachmentUriGrants,
     private val interactiveGate: InteractiveImapGate,
+    private val bandwidthTracker: GmailBandwidthTracker,
 ) : MailRepository {
 
     // Application-lifetime scope for fire-and-forget server pushes that must outlive the caller — e.g.
@@ -253,7 +256,7 @@ class MailRepositoryImpl @Inject constructor(
                     // fetch just omits that image, leaving a broken <img> rather than failing the open.
                     val file = runCatching {
                         ensureAttachmentFile(messageId, routing.accountId, routing.folder, row.partIndex, row.filename)
-                    }.getOrNull() ?: return@mapNotNull null
+                    }.getOrNull()?.file ?: return@mapNotNull null
                     InlineImage(contentId = row.contentId!!, mimeType = row.mimeType, bytes = file.readBytes())
                 }
             }
@@ -275,11 +278,18 @@ class MailRepositoryImpl @Inject constructor(
                         routing.folder,
                         partIndex,
                         meta?.filename ?: "attachment",
-                    )
+                    ).file
                 }
             }
         }
 
+    /**
+     * [ensureAttachmentFile]'s outcome: the cached [file] plus the bytes actually pulled over the
+     * network THIS call — `0` on a cache hit. [downloadedBytes] feeds Gmail's bandwidth accounting
+     * (issue #361, see [prefetchMessage]); a cache hit costs nothing so it must not be double-counted.
+     */
+    private class AttachmentFetch(val file: File, val downloadedBytes: Long)
+
     /**
      * Returns the on-disk file for one attachment part, downloading and caching it on first use so it
      * then opens instantly and offline. Takes the message's already-resolved account/folder so a batch
@@ -292,16 +302,16 @@ class MailRepositoryImpl @Inject constructor(
         folder: String,
         partIndex: Int,
         filename: String,
-    ): File {
+    ): AttachmentFetch {
         val target = attachmentFile(messageId, partIndex, filename)
         // Reuse a previously downloaded (or pre-fetched) file so it opens instantly and offline.
-        if (target.exists() && target.length() > 0L) return target
+        if (target.exists() && target.length() > 0L) return AttachmentFetch(target, downloadedBytes = 0L)
         val account = accountDao.getById(accountId)?.toDomain() ?: error("Account not found")
         val params = connectionFactory.imapParamsFor(account)
         val downloaded = imapClient.fetchAttachment(params, folder, uidOf(messageId), partIndex)
         target.parentFile?.mkdirs()
         target.outputStream().use { it.write(downloaded.bytes) }
-        return target
+        return AttachmentFetch(target, downloadedBytes = downloaded.bytes.size.toLong())
     }
 
     override suspend fun downloadedAttachmentParts(messageId: String): Set<Int> = withContext(Dispatchers.IO) {
@@ -317,12 +327,17 @@ class MailRepositoryImpl @Inject constructor(
     override suspend fun prefetchMessage(messageId: String): Result<Unit> = runCatching {
         val routing = messageDao.getRouting(messageId) ?: return@runCatching
         val account = accountDao.getById(routing.accountId)?.toDomain() ?: return@runCatching
+        // Bytes actually pulled over the network this call (0 on an all-cache-hit prefetch), fed to
+        // Gmail's daily download-budget tracker below (issue #361) — the proactive pacing that composes
+        // with #360's reactive AccountThrottleGate and #356's BackfillPacer without modifying either.
+        var downloadedBytes = 0L
         // Cache the body (peek, so prefetching never marks the message read) and its attachment metadata.
         if (!routing.bodyFetched) {
             val params = connectionFactory.imapParamsFor(account)
             val content = imapClient.fetchBodyPeek(params, routing.folder, uidOf(messageId))
             messageDao.updateBody(messageId, content.body, content.isHtml, Snippet.of(content.body, content.isHtml))
             attachmentDao.replaceForMessage(messageId, content.attachments.map { it.toEntity(messageId) })
+            downloadedBytes += content.body.toByteArray(Charsets.UTF_8).size.toLong()
         }
         // Auto-download every attachment's bytes into the persistent per-part cache (skips ones present).
         // This is BACKGROUND work driven by the backfill, so it goes straight to ensureAttachmentFile and
@@ -338,7 +353,13 @@ class MailRepositoryImpl @Inject constructor(
                     attachment.partIndex,
                     attachment.filename,
                 )
-            }
+            }.getOrNull()?.let { downloadedBytes += it.downloadedBytes }
+        }
+        // Gmail-specific bandwidth accounting (issue #361): only tracked for Gmail, since that is the
+        // only provider whose daily download budget is enforced today (see GmailSyncLimits.appliesTo /
+        // MailBackfiller.prefetchIfEnabled / MailSyncer.prefetchIfEnabled for the deferral this feeds).
+        if (downloadedBytes > 0L && GmailSyncLimits.appliesTo(account)) {
+            bandwidthTracker.recordDownload(account.id, downloadedBytes)
         }
     }
 
diff --git a/app/src/main/kotlin/org/libremail/data/sync/GmailBandwidthTracker.kt b/app/src/main/kotlin/org/libremail/data/sync/GmailBandwidthTracker.kt
new file mode 100644
index 0000000..bb556e8
--- /dev/null
+++ b/app/src/main/kotlin/org/libremail/data/sync/GmailBandwidthTracker.kt
@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+package org.libremail.data.sync
+
+import org.libremail.reporting.AppLog
+import org.libremail.reporting.accountLogRef
+import java.util.concurrent.ConcurrentHashMap
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Per-account, per-day running total of bytes downloaded by background prefetch, tracked against
+ * Gmail's documented [GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES] (issue #361). The stateful
+ * counterpart to the pure [GmailSyncLimits]:
+ * [org.libremail.data.repository.MailRepositoryImpl.prefetchMessage] feeds it bytes actually pulled
+ * over the network via [recordDownload], and [MailBackfiller] / [MailSyncer] consult
+ * [isOverDailyBudget] before starting a fresh prefetch batch for an account, deferring the rest of the
+ * day's prefetch once the budget is reached.
+ *
+ * **Proactive, not reactive — orthogonal to [AccountThrottleGate].** The #360 gate only fires once a
+ * provider actually rejects a request; this tracker heads that off by pacing our OWN traffic against a
+ * budget Gmail documents but does not necessarily announce hitting. It has the same relationship to
+ * [AccountThrottleGate] that [InteractiveImapGate] already documents having with it: a separate,
+ * composing mechanism, not a duplicate or a replacement.
+ *
+ * **Self-healing.** A day boundary (a wall-clock day number derived from [nowMillis]) resets an
+ * account's tracked total, so a deferred account automatically resumes full prefetch the next day with
+ * no explicit reset needed — mirrors how [AccountThrottleGate]'s backoff window elapses on its own.
+ *
+ * **Interactive traffic is deliberately NOT tracked here.** Only background prefetch (issue #361's
+ * "sync/backfill" scope) feeds this tracker — opening a message, downloading a tapped attachment, and
+ * loading inline images are never deferred by a budget (the same interactive-priority principle
+ * #355/#360 already apply), so counting their bytes here would only make the tracker's *deferral*
+ * decision — which exclusively affects background prefetch — less representative of what it can
+ * actually still influence.
+ *
+ * State lives only in-process (a `@Singleton`); a process restart clears it, which simply means a
+ * fresh process re-earns its budget for the (partial) remainder of the day — a conservative direction
+ * to fail in, same as [AccountThrottleGate]'s reset-on-restart. Every log line is PII-free:
+ * [accountLogRef] for the account, and byte counts only.
+ */
+@Singleton
+class GmailBandwidthTracker internal constructor(private val nowMillis: () -> Long) {
+    /** Production wiring: the real wall clock. */
+    @Inject constructor() : this(nowMillis = System::currentTimeMillis)
+
+    /** One account's running download total for [dayEpoch] (whole days since the epoch). */
+    private data class Window(val dayEpoch: Long, val bytes: Long)
+
+    private val windows = ConcurrentHashMap<String, Window>()
+
+    /**
+     * Adds [bytes] to [accountId]'s running total for today, starting a fresh window if the day has
+     * rolled over since the last call (yesterday's total is simply discarded, not carried forward). A
+     * no-op for `bytes <= 0`. Logs once, PII-free, the moment this call carries the account from under
+     * budget to at-or-over it — not on every call, so an account that stays over budget for the rest of
+     * a sync/backfill pass doesn't spam the log.
+     */
+    fun recordDownload(accountId: String, bytes: Long) {
+        if (bytes <= 0L) return
+        val day = currentDayEpoch()
+        val before = windows[accountId]?.takeIf { it.dayEpoch == day }?.bytes ?: 0L
+        val updated = windows.compute(accountId) { _, previous ->
+            val carried = if (previous != null && previous.dayEpoch == day) previous.bytes else 0L
+            Window(day, carried + bytes)
+        }!!
+        val budget = GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES
+        if (before < budget && updated.bytes >= budget) {
+            AppLog.w(TAG, "daily download budget reached ${accountLogRef(accountId)}")
+        }
+    }
+
+    /** [accountId]'s tracked download bytes so far today, or 0 when untracked or the day has rolled over. */
+    fun bytesDownloadedToday(accountId: String): Long {
+        val window = windows[accountId] ?: return 0L
+        return if (window.dayEpoch == currentDayEpoch()) window.bytes else 0L
+    }
+
+    /** True once [accountId]'s tracked downloads for today reach [GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES]. */
+    fun isOverDailyBudget(accountId: String): Boolean =
+        bytesDownloadedToday(accountId) >= GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES
+
+    private fun currentDayEpoch(): Long = nowMillis() / MILLIS_PER_DAY
+
+    private companion object {
+        const val TAG = "GmailBandwidth"
+        const val MILLIS_PER_DAY = 24 * 60 * 60 * 1000L
+    }
+}
diff --git a/app/src/main/kotlin/org/libremail/data/sync/GmailSyncLimits.kt b/app/src/main/kotlin/org/libremail/data/sync/GmailSyncLimits.kt
new file mode 100644
index 0000000..804a2f4
--- /dev/null
+++ b/app/src/main/kotlin/org/libremail/data/sync/GmailSyncLimits.kt
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+package org.libremail.data.sync
+
+import org.libremail.domain.model.Account
+import org.libremail.domain.model.MailProvider
+
+/**
+ * Gmail's documented IMAP connection and bandwidth ceilings (issue #361) — the Gmail-specific config
+ * that feeds the shared, provider-agnostic pacing machinery ([AccountThrottleGate]'s reactive backoff,
+ * issue #360; [BackfillPacer]'s proactive inter-slice cooldown, issue #356) instead of reinventing
+ * either. Per-account, per-provider connection/bandwidth caps were deliberately deferred out of both
+ * (see [org.libremail.mail.ImapConnectionCache]'s "separate effort #356/#360-#364" note); this is
+ * Gmail's slice of that follow-up. Kept additive and provider-scoped — the sibling Yahoo (#362), iCloud
+ * (#363), and Outlook/Graph (#364) tickets land their own provider config independently.
+ *
+ * Values are Google's documented Gmail IMAP limits (as referenced by issue #361):
+ *  - 15 max simultaneous IMAP connections per account.
+ *  - 2,500 MB/day download, 500 MB/day upload.
+ *  - 10,000 messages per label, 10,000 labels.
+ *
+ * Pure data + provider detection only — no state, no logging (mirrors how [ThrottleBackoff] and
+ * [ThrottleClassifier] stay pure while [AccountThrottleGate] carries the state and logging). The
+ * stateful counterpart that actually tracks bytes against [DAILY_DOWNLOAD_BUDGET_BYTES] is
+ * [GmailBandwidthTracker].
+ */
+object GmailSyncLimits {
+    /** Gmail's documented simultaneous-IMAP-connection ceiling, per account. */
+    const val MAX_IMAP_CONNECTIONS = 15
+
+    /**
+     * Connections proactively reserved for interactive use (never spent by background sync/backfill),
+     * mirroring the "interactive-request priority over backfill" lever from the #360 umbrella issue.
+     * LibreMail's IMAP layer already keeps at most ONE reused connection per account
+     * ([org.libremail.mail.ImapConnectionCache], issue #125/#357) plus one dedicated IMAP-IDLE
+     * connection ([org.libremail.mail.ImapClient.idle]) — 2 total, well inside the resulting headroom
+     * regardless of this value — so today this is documented config for any future pooling work rather
+     * than something that needs active enforcement (see `GmailSyncLimitsTest` for the invariant that
+     * ties the two together).
+     */
+    const val INTERACTIVE_RESERVED_CONNECTIONS = 1
+
+    /** [MAX_IMAP_CONNECTIONS] minus [INTERACTIVE_RESERVED_CONNECTIONS] — background sync/backfill's budget. */
+    const val MAX_BACKGROUND_IMAP_CONNECTIONS = MAX_IMAP_CONNECTIONS - INTERACTIVE_RESERVED_CONNECTIONS
+
+    private const val BYTES_PER_MB = 1024L * 1024L
+
+    /**
+     * Gmail's documented daily download budget. [GmailBandwidthTracker] accumulates bytes actually
+     * pulled by background prefetch (see
+     * [org.libremail.data.repository.MailRepositoryImpl.prefetchMessage]) against this; [MailBackfiller]
+     * and [MailSyncer] defer further prefetch for an account once it is reached, resuming automatically
+     * the next day. Interactive fetches (opening a message, downloading a tapped attachment, loading
+     * inline images) are never gated by it — the same interactive-priority principle #355/#360 already
+     * apply elsewhere.
+     */
+    const val DAILY_DOWNLOAD_BUDGET_BYTES = 2_500L * BYTES_PER_MB
+
+    /**
+     * Gmail's documented daily upload budget (SMTP send). Captured here for completeness against
+     * issue #361's documented limits; sending/composing is a separate path from this issue's
+     * sync/backfill scope, so it is not enforced by this change.
+     */
+    const val DAILY_UPLOAD_BUDGET_BYTES = 500L * BYTES_PER_MB
+
+    /** Gmail's documented per-label message ceiling. */
+    const val MAX_MESSAGES_PER_LABEL = 10_000
+
+    /** Gmail's documented total-labels ceiling. */
+    const val MAX_LABELS = 10_000
+
+    /**
+     * True when [account]'s IMAP host resolves to [MailProvider.GMAIL] (including its legacy
+     * `imap.googlemail.com` alias) — the single place issue #361's caps decide "is this Gmail".
+     */
+    fun appliesTo(account: Account): Boolean = MailProvider.forImapHost(account.imap.host) == MailProvider.GMAIL
+}
diff --git a/app/src/main/kotlin/org/libremail/data/sync/MailBackfiller.kt b/app/src/main/kotlin/org/libremail/data/sync/MailBackfiller.kt
index 42bb8f0..00001e2 100644
--- a/app/src/main/kotlin/org/libremail/data/sync/MailBackfiller.kt
+++ b/app/src/main/kotlin/org/libremail/data/sync/MailBackfiller.kt
@@ -59,6 +59,7 @@ class MailBackfiller @Inject constructor(
     private val maintenanceGate: MailMaintenanceGate,
     private val throttleGate: AccountThrottleGate,
     private val interactiveGate: InteractiveImapGate,
+    private val bandwidthTracker: GmailBandwidthTracker,
 ) {
     /** One folder's slice outcome: pages fetched, and whether an immediate follow-up slice has work to do. */
     private data class FolderResult(val batches: Int, val moreWork: Boolean)
@@ -214,7 +215,7 @@ class MailBackfiller @Inject constructor(
             }
             beforeUid = nextBeforeUid
             backfillProgressDao.upsert(BackfillProgressEntity(account.id, folder, beforeUid, complete = false))
-            prefetchIfEnabled(entities.map { it.id })
+            prefetchIfEnabled(account, entities.map { it.id })
             // Breathe between pages so a large mailbox doesn't hammer the server.
             delay(BACKFILL_BATCH_DELAY_MS)
         }
@@ -293,7 +294,7 @@ class MailBackfiller @Inject constructor(
      * Best-effort and cancellable between messages so an interruption stops promptly; anything not
      * fetched is filled in lazily when the message is opened.
      */
-    private suspend fun prefetchIfEnabled(ids: List<String>) {
+    private suspend fun prefetchIfEnabled(account: Account, ids: List<String>) {
         // Debug-only fetch gate (issue #393): pause proactive body prefetch so a later open is a genuine
         // uncached fetch. Header paging above is untouched (its own gate is the BackfillWorker entry), so
         // history still lands; a skipped body is filled in lazily on open. Compiled out of release
@@ -308,6 +309,17 @@ class MailBackfiller @Inject constructor(
             battery = batteryStatusProvider.current(),
         )
         if (!shouldPrefetch) return
+        // Gmail-specific proactive bandwidth pacing (#361): once this account's tracked downloads for
+        // today reach Gmail's documented daily budget, defer body/attachment prefetch for the rest of
+        // the day instead of continuing to spend it — header paging above is unaffected, and a fresh
+        // cycle resumes automatically once the day rolls over (GmailBandwidthTracker). Orthogonal to
+        // the #360 throttle skip above (which only fires once the provider actually rejects a request)
+        // and #356's BackfillPacer (which paces slice cadence, not bytes) — same graceful-degradation
+        // shape as both, composing rather than duplicating either.
+        if (GmailSyncLimits.appliesTo(account) && bandwidthTracker.isOverDailyBudget(account.id)) {
+            AppLog.i(TAG, "prefetch deferred ${accountLogRef(account.id)}: Gmail daily download budget reached")
+            return
+        }
         for (id in ids) {
             currentCoroutineContext().ensureActive()
             mailRepository.prefetchMessage(id)
diff --git a/app/src/main/kotlin/org/libremail/data/sync/MailSyncer.kt b/app/src/main/kotlin/org/libremail/data/sync/MailSyncer.kt
index e2f0814..426860c 100644
--- a/app/src/main/kotlin/org/libremail/data/sync/MailSyncer.kt
+++ b/app/src/main/kotlin/org/libremail/data/sync/MailSyncer.kt
@@ -41,6 +41,7 @@ class MailSyncer @Inject constructor(
     private val notifier: MailNotifier,
     private val mailRepository: MailRepository,
     private val throttleGate: AccountThrottleGate,
+    private val bandwidthTracker: GmailBandwidthTracker,
 ) : Syncer {
     // Serializes all syncing: syncAll/syncAccount/syncFolder are invoked concurrently by the periodic
     // worker, pull-to-refresh, one-shot syncs, folder opens, and one IDLE watcher per account. Without
@@ -187,6 +188,17 @@ class MailSyncer @Inject constructor(
             battery = batteryStatusProvider.current(),
         )
         if (!shouldPrefetch) return
+        // Gmail-specific proactive bandwidth pacing (#361): once this account's tracked downloads for
+        // today reach Gmail's documented daily budget, defer body/attachment prefetch for the rest of
+        // the day instead of continuing to spend it — header sync above is unaffected, and a fresh
+        // cycle resumes automatically once the day rolls over (GmailBandwidthTracker). Orthogonal to
+        // #360's reactive AccountThrottleGate (only fires once the provider actually rejects a request)
+        // and #356's BackfillPacer (paces backfill slice cadence, not bytes) — same graceful-degradation
+        // shape as both, composing rather than duplicating either.
+        if (GmailSyncLimits.appliesTo(account) && bandwidthTracker.isOverDailyBudget(account.id)) {
+            AppLog.i(TAG, "prefetch deferred ${accountLogRef(account.id)}: Gmail daily download budget reached")
+            return
+        }
         for (id in messageDao.getUnfetchedIds(account.id, folder)) {
             currentCoroutineContext().ensureActive()
             mailRepository.prefetchMessage(id) // best-effort; swallows its own per-message failures
diff --git a/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryGrantsTest.kt b/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryGrantsTest.kt
index 805955c..fcc9f83 100644
--- a/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryGrantsTest.kt
+++ b/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryGrantsTest.kt
@@ -16,6 +16,7 @@ import org.libremail.data.local.dao.DraftDao
 import org.libremail.data.local.dao.OutboxDao
 import org.libremail.data.local.entity.DraftEntity
 import org.libremail.data.local.entity.OutboxEntity
+import org.libremail.data.sync.GmailBandwidthTracker
 import org.libremail.data.sync.InteractiveImapGate
 import java.nio.file.Files
 
@@ -47,6 +48,7 @@ class MailRepositoryGrantsTest {
         signatureRepository = mockk(relaxed = true),
         attachmentUriGrants = attachmentUriGrants,
         interactiveGate = InteractiveImapGate(),
+        bandwidthTracker = GmailBandwidthTracker(),
     )
 
     @Test
diff --git a/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryImplCoverageTest.kt b/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryImplCoverageTest.kt
index 46afc61..6690a04 100644
--- a/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryImplCoverageTest.kt
+++ b/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryImplCoverageTest.kt
@@ -40,6 +40,7 @@ import org.libremail.data.local.entity.OutboxEntity
 import org.libremail.data.local.entity.ServerConfigEmbedded
 import org.libremail.data.settings.AccountSettingsRepository
 import org.libremail.data.settings.SignatureRepository
+import org.libremail.data.sync.GmailBandwidthTracker
 import org.libremail.data.sync.InteractiveImapGate
 import org.libremail.data.sync.MailConnectionFactory
 import org.libremail.data.sync.SendScheduler
@@ -99,6 +100,7 @@ class MailRepositoryImplCoverageTest {
         signatureRepository = signatureRepository,
         attachmentUriGrants = mockk<AttachmentUriGrants>(relaxed = true),
         interactiveGate = InteractiveImapGate(),
+        bandwidthTracker = GmailBandwidthTracker(),
     )
 
     // openMessage now breadcrumbs via AppLog (issue #358); android.util.Log is a no-op stub under plain
diff --git a/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryImplTest.kt b/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryImplTest.kt
index 36a22fc..50413b5 100644
--- a/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryImplTest.kt
+++ b/app/src/test/kotlin/org/libremail/data/repository/MailRepositoryImplTest.kt
@@ -40,6 +40,7 @@ import org.libremail.data.local.entity.MessageSummary
 import org.libremail.data.local.entity.ServerConfigEmbedded
 import org.libremail.data.settings.AccountSettingsRepository
 import org.libremail.data.settings.SignatureRepository
+import org.libremail.data.sync.GmailBandwidthTracker
 import org.libremail.data.sync.InteractiveImapGate
 import org.libremail.data.sync.MailConnectionFactory
 import org.libremail.domain.model.AccountSettings
@@ -78,6 +79,9 @@ class MailRepositoryImplTest {
 
     // A real gate (cheap, no deps) so tests can observe the interactive-fetch counter it raises (#355).
     private val interactiveGate = InteractiveImapGate()
+
+    // A real tracker (cheap, no deps) so tests can observe Gmail's daily download-budget accounting (#361).
+    private val bandwidthTracker = GmailBandwidthTracker()
     private val repository = MailRepositoryImpl(
         context = context,
         messageDao = messageDao,
@@ -94,6 +98,7 @@ class MailRepositoryImplTest {
         // Grant-release wiring (deleteDraft / cancelOutboxMessage) is covered by MailRepositoryGrantsTest.
         attachmentUriGrants = mockk(relaxed = true),
         interactiveGate = interactiveGate,
+        bandwidthTracker = bandwidthTracker,
     )
 
     // openMessage now breadcrumbs via AppLog (issue #358); android.util.Log is a no-op stub under plain
@@ -411,6 +416,48 @@ class MailRepositoryImplTest {
         assertEquals("Reply to <ada@example.org>: 3 < 5", snippet.captured)
     }
 
+    // --- issue #361: Gmail bandwidth-aware prefetch pacing ----------------------------------------
+
+    @Test
+    fun `prefetchMessage records the fetched body and attachment bytes for a gmail account`() = runTest {
+        val cache = Files.createTempDirectory("attach").toFile()
+        every { context.cacheDir } returns cache
+        val id = "acct:INBOX:22"
+        val body = "Hello world"
+        coEvery { messageDao.getRouting(id) } returns messageRouting(id, "INBOX")
+        coEvery { accountDao.getById("acct") } returns
+            accountEntity().copy(imap = ServerConfigEmbedded("imap.gmail.com", 993, "SSL_TLS"))
+        coEvery { connectionFactory.imapParamsFor(any()) } returns imapParams()
+        coEvery { imapClient.fetchBodyPeek(any(), "INBOX", "22") } returns MessageContent(body, isHtml = false)
+        coEvery { messageDao.updateBody(id, any(), any(), any()) } just Runs
+        coEvery { attachmentDao.getForMessage(id) } returns listOf(attachmentEntity(id, 0, "photo.jpg"))
+        coEvery { imapClient.fetchAttachment(any(), "INBOX", "22", 0) } returns
+            DownloadedAttachment("photo.jpg", "image/jpeg", ByteArray(500))
+
+        repository.prefetchMessage(id)
+
+        val expectedBytes = body.toByteArray(Charsets.UTF_8).size + 500
+        assertEquals(expectedBytes.toLong(), bandwidthTracker.bytesDownloadedToday("acct"))
+    }
+
+    @Test
+    fun `prefetchMessage does not track bytes for a non-gmail account`() = runTest {
+        val cache = Files.createTempDirectory("attach").toFile()
+        every { context.cacheDir } returns cache
+        val id = "acct:INBOX:23"
+        coEvery { messageDao.getRouting(id) } returns messageRouting(id, "INBOX")
+        coEvery { accountDao.getById("acct") } returns accountEntity() // non-Gmail host (imap.example.org)
+        coEvery { connectionFactory.imapParamsFor(any()) } returns imapParams()
+        coEvery { imapClient.fetchBodyPeek(any(), "INBOX", "23") } returns
+            MessageContent("Hello world", isHtml = false)
+        coEvery { messageDao.updateBody(id, any(), any(), any()) } just Runs
+        coEvery { attachmentDao.getForMessage(id) } returns emptyList()
+
+        repository.prefetchMessage(id)
+
+        assertEquals(0L, bandwidthTracker.bytesDownloadedToday("acct"))
+    }
+
     @Test
     fun `archive moves messages to the account's archive folder and drops the local rows`() = runTest {
         val id = "acct:INBOX:5"
diff --git a/app/src/test/kotlin/org/libremail/data/sync/GmailBandwidthTrackerTest.kt b/app/src/test/kotlin/org/libremail/data/sync/GmailBandwidthTrackerTest.kt
new file mode 100644
index 0000000..0ce7c4b
--- /dev/null
+++ b/app/src/test/kotlin/org/libremail/data/sync/GmailBandwidthTrackerTest.kt
@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+package org.libremail.data.sync
+
+import android.util.Log
+import io.mockk.every
+import io.mockk.mockkStatic
+import io.mockk.unmockkAll
+import org.junit.After
+import org.junit.Before
+import org.junit.Test
+import org.libremail.reporting.AppLog
+import org.libremail.reporting.RingLogBuffer
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+/**
+ * [GmailBandwidthTracker] (issue #361) must accumulate an account's daily download bytes, isolate
+ * accounts from one another, roll its window over at the day boundary, report the daily-budget
+ * threshold accurately, and log only a PII-free, once-per-crossing breadcrumb. Mirrors
+ * [AccountThrottleGateTest]'s virtual-clock idiom (a plain injected `nowMillis` instead of
+ * coroutines-test virtual time, since the tracker itself is not a suspend API).
+ */
+class GmailBandwidthTrackerTest {
+
+    private val logBuffer = RingLogBuffer()
+
+    /** A manual clock for the day-rollover tests; [tracker] reads it live, so tests advance it by hand. */
+    private var now = 0L
+
+    private fun tracker() = GmailBandwidthTracker(nowMillis = { now })
+
+    @Before
+    fun setUp() {
+        // AppLog forwards to android.util.Log, a throwing no-op stub under plain JVM unit tests.
+        mockkStatic(Log::class)
+        every { Log.w(any<String>(), any<String>()) } returns 0
+        AppLog.install(logBuffer)
+    }
+
+    @After
+    fun tearDown() = unmockkAll()
+
+    @Test
+    fun `bytes accumulate across calls for the same account and day`() {
+        val tracker = tracker()
+
+        tracker.recordDownload("acct", 100L)
+        tracker.recordDownload("acct", 250L)
+
+        assertEquals(350L, tracker.bytesDownloadedToday("acct"))
+    }
+
+    @Test
+    fun `an untracked account reports zero bytes and is not over budget`() {
+        val tracker = tracker()
+
+        assertEquals(0L, tracker.bytesDownloadedToday("acct"))
+        assertFalse(tracker.isOverDailyBudget("acct"))
+    }
+
+    @Test
+    fun `crossing the daily download budget marks the account over budget`() {
+        val tracker = tracker()
+
+        tracker.recordDownload("acct", GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES - 1)
+        assertFalse(tracker.isOverDailyBudget("acct"), "one byte under budget must not trip it")
+
+        tracker.recordDownload("acct", 1L)
+        assertTrue(tracker.isOverDailyBudget("acct"), "reaching the budget exactly must trip it")
+    }
+
+    @Test
+    fun `a tracked account never affects another account's budget`() {
+        val tracker = tracker()
+
+        tracker.recordDownload("heavy", GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES)
+
+        assertTrue(tracker.isOverDailyBudget("heavy"))
+        assertFalse(tracker.isOverDailyBudget("light"))
+        assertEquals(0L, tracker.bytesDownloadedToday("light"))
+    }
+
+    @Test
+    fun `a new day resets the tracked total instead of carrying it forward`() {
+        val tracker = tracker()
+        val oneDayMs = 24 * 60 * 60 * 1000L
+
+        tracker.recordDownload("acct", GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES)
+        assertTrue(tracker.isOverDailyBudget("acct"))
+
+        now += oneDayMs
+        assertFalse(tracker.isOverDailyBudget("acct"), "a new day must clear yesterday's total")
+        assertEquals(0L, tracker.bytesDownloadedToday("acct"))
+
+        tracker.recordDownload("acct", 10L)
+        assertEquals(10L, tracker.bytesDownloadedToday("acct"), "today's total starts fresh, not carried over")
+    }
+
+    @Test
+    fun `recording zero or negative bytes is a no-op`() {
+        val tracker = tracker()
+
+        tracker.recordDownload("acct", 0L)
+        tracker.recordDownload("acct", -5L)
+
+        assertEquals(0L, tracker.bytesDownloadedToday("acct"))
+    }
+
+    @Test
+    fun `crossing the budget logs exactly once and stays PII-free`() {
+        val tracker = tracker()
+        val accountId = "imap:user@example.org"
+
+        tracker.recordDownload(accountId, GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES) // crosses
+        tracker.recordDownload(accountId, 10L) // still over budget; must not log again
+
+        val messages = logBuffer.snapshot().map { it.message }
+        assertEquals(1, messages.count { it.contains("daily download budget reached") })
+        messages.forEach { assertFalse(it.contains("user@example.org"), it) }
+    }
+
+    @Test
+    fun `staying under budget never logs`() {
+        val tracker = tracker()
+
+        tracker.recordDownload("acct", GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES - 1)
+
+        assertTrue(logBuffer.snapshot().isEmpty())
+    }
+}
diff --git a/app/src/test/kotlin/org/libremail/data/sync/GmailSyncLimitsTest.kt b/app/src/test/kotlin/org/libremail/data/sync/GmailSyncLimitsTest.kt
new file mode 100644
index 0000000..3ed6094
--- /dev/null
+++ b/app/src/test/kotlin/org/libremail/data/sync/GmailSyncLimitsTest.kt
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+package org.libremail.data.sync
+
+import org.junit.Test
+import org.libremail.domain.model.Account
+import org.libremail.domain.model.MailProvider
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+/**
+ * Locks down Gmail's documented IMAP connection/bandwidth ceilings (issue #361) — easy to mistype and
+ * painful to debug on-device, so the exact figures are asserted here rather than trusted to a code
+ * review (mirrors [org.libremail.domain.model.MailProviderTest]'s rationale for the provider presets).
+ */
+class GmailSyncLimitsTest {
+
+    @Test
+    fun `documented connection and bandwidth ceilings match Gmail's published limits`() {
+        assertEquals(15, GmailSyncLimits.MAX_IMAP_CONNECTIONS)
+        assertEquals(1, GmailSyncLimits.INTERACTIVE_RESERVED_CONNECTIONS)
+        assertEquals(14, GmailSyncLimits.MAX_BACKGROUND_IMAP_CONNECTIONS)
+        assertEquals(2_500L * 1024 * 1024, GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES)
+        assertEquals(500L * 1024 * 1024, GmailSyncLimits.DAILY_UPLOAD_BUDGET_BYTES)
+        assertEquals(10_000, GmailSyncLimits.MAX_MESSAGES_PER_LABEL)
+        assertEquals(10_000, GmailSyncLimits.MAX_LABELS)
+    }
+
+    /**
+     * Ties Gmail's documented ceiling to today's actual architecture: [org.libremail.mail.ImapConnectionCache]
+     * (#125/#357) keeps at most ONE reused connection per account, plus `ImapClient.idle`'s own dedicated
+     * IDLE connection — 2 total, regardless of provider. Asserting that invariant against the real
+     * headroom-adjusted cap means a future change that grows per-account concurrency (e.g. a real
+     * connection pool) trips this test well before it could ever approach Gmail's actual ceiling.
+     */
+    @Test
+    fun `today's architecture keeps concurrent connections per account well inside the background budget`() {
+        val knownConcurrentConnectionsPerAccount = 2 // one reused IMAP connection + one dedicated IDLE connection
+        assertTrue(knownConcurrentConnectionsPerAccount <= GmailSyncLimits.MAX_BACKGROUND_IMAP_CONNECTIONS)
+    }
+
+    @Test
+    fun `appliesTo is true for a gmail account, including the legacy googlemail host`() {
+        val gmail = MailProvider.GMAIL.createAccount("user@gmail.com")
+        assertTrue(GmailSyncLimits.appliesTo(gmail))
+
+        val legacyHost = gmail.copy(imap = gmail.imap.copy(host = "imap.googlemail.com"))
+        assertTrue(GmailSyncLimits.appliesTo(legacyHost))
+    }
+
+    @Test
+    fun `appliesTo is false for a non-gmail account`() {
+        assertFalse(GmailSyncLimits.appliesTo(MailProvider.YAHOO.createAccount("user@yahoo.com")))
+        assertFalse(GmailSyncLimits.appliesTo(MailProvider.ICLOUD.createAccount("user@icloud.com")))
+        assertFalse(GmailSyncLimits.appliesTo(MailProvider.AOL.createAccount("user@aol.com")))
+        assertFalse(GmailSyncLimits.appliesTo(Account.outlook("user@outlook.com")))
+    }
+}
diff --git a/app/src/test/kotlin/org/libremail/data/sync/MailBackfillerTest.kt b/app/src/test/kotlin/org/libremail/data/sync/MailBackfillerTest.kt
index 4a9ad75..b9948e1 100644
--- a/app/src/test/kotlin/org/libremail/data/sync/MailBackfillerTest.kt
+++ b/app/src/test/kotlin/org/libremail/data/sync/MailBackfillerTest.kt
@@ -606,6 +606,57 @@ class MailBackfillerTest {
         coVerify(atLeast = 1) { imapClient.fetchOlderThan(any(), any(), any(), any()) }
     }
 
+    // --- issue #361: Gmail bandwidth-aware prefetch pacing ----------------------------------------
+
+    /**
+     * Once a Gmail account's tracked downloads for today reach the documented daily budget, backfill's
+     * body/attachment prefetch is deferred for the rest of the day — but header paging (the history
+     * itself) is untouched, the same "prefetch-only" gating shape as the low-battery (#89) and
+     * fetch-gate (#393) tests above.
+     */
+    @Test
+    fun `gmail prefetch defers once the daily download budget is reached, but header paging is unaffected`() = runTest {
+        appendMessages(60)
+        seedForegroundWindow()
+        val gmailAccount = accountEntity.copy(imap = ServerConfigEmbedded("imap.gmail.com", 993, "SSL_TLS"))
+        val tracker = GmailBandwidthTracker().apply {
+            recordDownload("acct", GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES)
+        }
+
+        backfiller(
+            AccountSettings("acct"),
+            fetchPolicy = FetchPolicy.ALWAYS,
+            bandwidthTracker = tracker,
+            account = gmailAccount,
+        ).runBackfill()
+
+        assertEquals(60, distinctCachedUids().size, "header paging itself is not budget-gated")
+        coVerify(exactly = 0) { requireNotNull(lastMailRepository).prefetchMessage(any()) }
+        assertTrue(
+            logBuffer.snapshot().any { it.message.startsWith("prefetch deferred acct:") },
+            "a PII-free deferral breadcrumb is recorded",
+        )
+    }
+
+    /**
+     * The Gmail bandwidth budget is provider-scoped, not a blanket cap: an over-budget tracker entry
+     * for the same account id must not affect a non-Gmail account's prefetch.
+     */
+    @Test
+    fun `a non-gmail account's prefetch is unaffected by an over-budget gmail bandwidth tracker`() = runTest {
+        appendMessages(60)
+        seedForegroundWindow()
+        val tracker = GmailBandwidthTracker().apply {
+            recordDownload("acct", GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES)
+        }
+
+        // account defaults to the fixture's non-Gmail (127.0.0.1) host.
+        backfiller(AccountSettings("acct"), fetchPolicy = FetchPolicy.ALWAYS, bandwidthTracker = tracker)
+            .runBackfill()
+
+        coVerify(atLeast = 1) { requireNotNull(lastMailRepository).prefetchMessage(any()) }
+    }
+
     // --- issue #329: AppLog breadcrumbs ---------------------------------------------------------
 
     @Test
@@ -686,9 +737,11 @@ class MailBackfillerTest {
         imapClient: ImapClient = client,
         throttleGate: AccountThrottleGate = AccountThrottleGate(),
         interactiveGate: InteractiveImapGate = InteractiveImapGate(),
+        bandwidthTracker: GmailBandwidthTracker = GmailBandwidthTracker(),
+        account: AccountEntity = accountEntity,
     ): MailBackfiller {
         val accountDao = mockk<AccountDao>()
-        coEvery { accountDao.getAll() } returns listOf(accountEntity)
+        coEvery { accountDao.getAll() } returns listOf(account)
 
         val messageDao = mockk<MessageDao>(relaxed = true)
         coEvery { messageDao.insertNew(any()) } answers {
@@ -743,6 +796,7 @@ class MailBackfillerTest {
             maintenanceGate = MailMaintenanceGate(),
             throttleGate = throttleGate,
             interactiveGate = interactiveGate,
+            bandwidthTracker = bandwidthTracker,
         ).also {
             lastMessageDao = messageDao
             lastMailRepository = mailRepository
diff --git a/app/src/test/kotlin/org/libremail/data/sync/MailMaintenanceGateTest.kt b/app/src/test/kotlin/org/libremail/data/sync/MailMaintenanceGateTest.kt
index 410f941..50790f1 100644
--- a/app/src/test/kotlin/org/libremail/data/sync/MailMaintenanceGateTest.kt
+++ b/app/src/test/kotlin/org/libremail/data/sync/MailMaintenanceGateTest.kt
@@ -202,6 +202,7 @@ class MailMaintenanceGateTest {
             maintenanceGate = gate,
             throttleGate = AccountThrottleGate(),
             interactiveGate = InteractiveImapGate(),
+            bandwidthTracker = GmailBandwidthTracker(),
         )
     }
 
diff --git a/app/src/test/kotlin/org/libremail/data/sync/MailSyncConcurrencyTest.kt b/app/src/test/kotlin/org/libremail/data/sync/MailSyncConcurrencyTest.kt
index c659e8e..10c0a8c 100644
--- a/app/src/test/kotlin/org/libremail/data/sync/MailSyncConcurrencyTest.kt
+++ b/app/src/test/kotlin/org/libremail/data/sync/MailSyncConcurrencyTest.kt
@@ -331,6 +331,7 @@ class MailSyncConcurrencyTest {
             notifier = mockk(relaxed = true),
             mailRepository = mockk(relaxed = true),
             throttleGate = AccountThrottleGate(),
+            bandwidthTracker = GmailBandwidthTracker(),
         )
     }
 
@@ -362,6 +363,7 @@ class MailSyncConcurrencyTest {
             maintenanceGate = MailMaintenanceGate(),
             throttleGate = AccountThrottleGate(),
             interactiveGate = InteractiveImapGate(),
+            bandwidthTracker = GmailBandwidthTracker(),
         )
     }
 
diff --git a/app/src/test/kotlin/org/libremail/data/sync/MailSyncerTest.kt b/app/src/test/kotlin/org/libremail/data/sync/MailSyncerTest.kt
index 1f5e611..0e36516 100644
--- a/app/src/test/kotlin/org/libremail/data/sync/MailSyncerTest.kt
+++ b/app/src/test/kotlin/org/libremail/data/sync/MailSyncerTest.kt
@@ -95,9 +95,11 @@ class MailSyncerTest {
         battery: BatteryStatus = BatteryStatus(percent = 100, isCharging = false),
         fetched: List<FetchedMessage> = emptyList(),
         throttleGate: AccountThrottleGate = AccountThrottleGate(),
+        bandwidthTracker: GmailBandwidthTracker = GmailBandwidthTracker(),
+        accountEntity: AccountEntity = account,
     ): MailSyncer {
         val accountDao = mockk<AccountDao>()
-        coEvery { accountDao.getById("acct") } returns account
+        coEvery { accountDao.getById("acct") } returns accountEntity
         val messageDao = mockk<MessageDao>(relaxed = true)
         coEvery { messageDao.getSyncedIds(any(), any()) } returns emptyList()
         coEvery { messageDao.getUnfetchedIds("acct", "INBOX") } returns listOf("acct:INBOX:1")
@@ -124,6 +126,7 @@ class MailSyncerTest {
             notifier = mockk<MailNotifier>(relaxed = true),
             mailRepository = mailRepository,
             throttleGate = throttleGate,
+            bandwidthTracker = bandwidthTracker,
         )
     }
 
@@ -282,6 +285,43 @@ class MailSyncerTest {
         coVerify { repo.prefetchMessage("acct:INBOX:1") }
     }
 
+    // --- issue #361: Gmail bandwidth-aware prefetch pacing ----------------------------------------
+
+    @Test
+    fun `gmail prefetch defers once the daily download budget is reached, leaving the header sync untouched`() =
+        runTest {
+            val repo = mockk<MailRepository>(relaxed = true)
+            val gmailAccount = account.copy(imap = ServerConfigEmbedded("imap.gmail.com", 993, "SSL_TLS"))
+            val tracker = GmailBandwidthTracker().apply {
+                recordDownload("acct", GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES)
+            }
+
+            val result = syncer(
+                FetchPolicy.ALWAYS,
+                repo,
+                accountEntity = gmailAccount,
+                bandwidthTracker = tracker,
+            ).syncFolder("acct", "INBOX")
+
+            assertEquals(0, result.getOrNull()) // header sync still ran and succeeded
+            coVerify(exactly = 0) { repo.prefetchMessage(any()) }
+            assertTrue(logBuffer.snapshot().any { it.message.startsWith("prefetch deferred acct:") })
+        }
+
+    @Test
+    fun `a non-gmail account's prefetch is unaffected by an over-budget gmail bandwidth tracker`() = runTest {
+        val repo = mockk<MailRepository>()
+        coEvery { repo.prefetchMessage(any()) } returns Result.success(Unit)
+        val tracker = GmailBandwidthTracker().apply {
+            recordDownload("acct", GmailSyncLimits.DAILY_DOWNLOAD_BUDGET_BYTES)
+        }
+
+        // accountEntity defaults to the fixture's non-Gmail (imap.example.org) host.
+        syncer(FetchPolicy.ALWAYS, repo, bandwidthTracker = tracker).syncFolder("acct", "INBOX")
+
+        coVerify { repo.prefetchMessage("acct:INBOX:1") }
+    }
+
     @Test
     fun `notifies for new mail when both global and per-account notifications are enabled`() = runTest {
         val notifier = mockk<MailNotifier>(relaxed = true)
@@ -340,6 +380,7 @@ class MailSyncerTest {
             notifier = notifier,
             mailRepository = mockk(relaxed = true),
             throttleGate = AccountThrottleGate(),
+            bandwidthTracker = GmailBandwidthTracker(),
         )
     }
 
@@ -423,6 +464,7 @@ class MailSyncerTest {
             notifier = mockk(relaxed = true),
             mailRepository = mockk(relaxed = true),
             throttleGate = AccountThrottleGate(),
+            bandwidthTracker = GmailBandwidthTracker(),
         )
     }
 
diff --git a/config/detekt/detekt.yml b/config/detekt/detekt.yml
index 6458d26..3bb9f85 100644
--- a/config/detekt/detekt.yml
+++ b/config/detekt/detekt.yml
@@ -75,6 +75,9 @@ style:
       - '**/data/sync/AccountThrottleGateTest.kt'
       # #356 backfill pacer: cooldown/cap/skip breadcrumbs through AppLog, so this suite mockkStatic(Log) too.
       - '**/data/sync/BackfillPacerTest.kt'
+      # #361 Gmail bandwidth tracker: the daily-budget-crossing breadcrumb goes through AppLog, so this
+      # suite mockkStatic(Log) too.
+      - '**/data/sync/GmailBandwidthTrackerTest.kt'
       # Reader-path perf logging (issue #358): the repository's openMessage and the reader ViewModel
       # log via AppLog, so their unit tests mockkStatic(Log) too.
       - '**/data/repository/MailRepositoryImplTest.kt'
-- 
2.47.3


From 58447d7d12f17f2bec660394c93da53b9c7d1b8e Mon Sep 17 00:00:00 2001
From: Jason Ross <jason.ross841@gmail.com>
Date: Wed, 8 Jul 2026 20:32:16 -0500
Subject: [PATCH 3/3] ci(e2e): gate the emulator on window focus to fix the
 RootViewPicker flake (#468)

Root cause: intermittently the launched activity window has has-window-focus=false
for the WHOLE instrumented run, so Espresso's RootViewPicker (onView().check(),
Intents.intended(), pressBack(), focus-dependent clipboard) times out after 10s and
fails EVERY focus-dependent test at once while the ~280 pure-Compose semantics tests
(which don't need window focus) pass. A failing E2E (35) leg's logcat (PR #470, run
28985259521) shows has-window-focus=true ZERO times across the whole session and both
the first attempt and the once-retry fail identically -- a persistent environmental
state, not a per-test transient. The prior mitigation, a single fire-and-forget
`adb shell input keyevent 82` (MENU) right after boot, is too weak: MENU no longer
dismisses the modern (API 30+) keyguard and, delivered before SystemUI/keyguard comes
up, is simply dropped -- so the insecure keyguard / non-interactive display persists
and no app window ever takes focus.

Fix: a single shared helper, .github/scripts/emulator_focus_gate.py, invoked
identically by BOTH E2E jobs (the e2e API 29-36 matrix AND e2e-preview API 37) and by
the local preflight runners (local_instrumented.py / api37_e2e.py), so it cannot drift.
It wakes the display (KEYCODE_WAKEUP), dismisses + disables the keyguard
(wm dismiss-keyguard, locksettings set-disabled true), keeps the screen on
(svc power stayon true + max screen_off_timeout), zeroes the animation scales, then
polls dumpsys power/window until the device is interactive AND a real window holds
input focus (mCurrentFocus non-null) -- re-nudging each iteration -- before the suite
runs. Applied uniformly, this also gives e2e-preview the animation-disable the matrix
already had. The gate is soft (bounded wait, then proceeds with a ::warning:: and the
final device state) and non-fatal (`|| true`), preserving #454's guarantee that the
unlock never aborts the boot; it leaves #454's manual boot, #460's path-filter and
#464's wedge-capture untouched.

The pure readiness parser is unit-tested by test_emulator_focus_gate.py (run by the
traffic-control-tests job). Determinism is validated by this PR's own matrix run.

Closes #468
---
 .claude/skills/preflight/api37_e2e.py         |  14 +-
 .../skills/preflight/local_instrumented.py    |  17 +-
 .github/scripts/emulator_focus_gate.py        | 277 ++++++++++++++++++
 .github/scripts/test_emulator_focus_gate.py   | 111 +++++++
 .github/workflows/ci.yml                      |  28 +-
 5 files changed, 432 insertions(+), 15 deletions(-)
 create mode 100644 .github/scripts/emulator_focus_gate.py
 create mode 100644 .github/scripts/test_emulator_focus_gate.py

diff --git a/.claude/skills/preflight/api37_e2e.py b/.claude/skills/preflight/api37_e2e.py
index 14474aa..1421ded 100644
--- a/.claude/skills/preflight/api37_e2e.py
+++ b/.claude/skills/preflight/api37_e2e.py
@@ -365,10 +365,18 @@ def main() -> int:
         if not booted:
             raise RuntimeError("API 37 preview emulator failed to boot after 2 attempts.")
 
-        # 4. Dismiss the keyguard, then run the instrumented/E2E suite against the booted emulator.
-        subprocess.run(cmd(adb, "shell", "input", "keyevent", "82"), check=False)
-
+        # 4. Force the emulator to grant the app window focus, then GATE on it (the SAME shared
+        # helper CI's e2e / e2e-preview jobs invoke, issue #468), before running the suite: wake
+        # the display, dismiss + disable the keyguard, keep the screen on, disable animations, and
+        # wait for a focused window. Replaces the lone `input keyevent 82`. Best-effort: fall back
+        # to that legacy nudge if the shared helper is somehow missing.
         repo_root = Path(__file__).resolve().parents[3]
+        focus_gate = repo_root / ".github" / "scripts" / "emulator_focus_gate.py"
+        if focus_gate.is_file():
+            subprocess.run([sys.executable, str(focus_gate), "--adb", adb], check=False)
+        else:
+            subprocess.run(cmd(adb, "shell", "input", "keyevent", "82"), check=False)
+
         gradlew = repo_root / ("gradlew.bat" if IS_WINDOWS else "gradlew")
         print(f"Running :app:connectedDebugAndroidTest against {AVD_NAME}...")
         test_exit = subprocess.run(
diff --git a/.claude/skills/preflight/local_instrumented.py b/.claude/skills/preflight/local_instrumented.py
index b31eeab..fc4bf35 100644
--- a/.claude/skills/preflight/local_instrumented.py
+++ b/.claude/skills/preflight/local_instrumented.py
@@ -324,10 +324,17 @@ def wait_for_boot(adb: str, proc: subprocess.Popen, timeout: int) -> bool:
     return False
 
 
-def dismiss_keyguard(adb: str) -> None:
-    # Dismiss the keyguard (mirrors CI + api37_e2e.py). Best-effort: a cold -wipe-data boot
-    # rarely needs it, and the input service can lose a race right after boot.
-    _run_quiet(cmd(adb, "-s", SERIAL, "shell", "input", "keyevent", "82"))
+def prepare_focus(adb: str) -> None:
+    # Force the emulator to grant the app window focus BEFORE the suite, then gate on it -- the
+    # SAME shared helper CI's e2e / e2e-preview jobs invoke (issue #468), so local preflight
+    # exercises the identical fix. It wakes the display, dismisses + disables the keyguard, keeps
+    # the screen on, disables animations, and waits for a focused window. Best-effort: fall back
+    # to the legacy `input keyevent 82` nudge if the shared helper is somehow missing.
+    gate = REPO_ROOT / ".github" / "scripts" / "emulator_focus_gate.py"
+    if gate.is_file():
+        subprocess.run([sys.executable, str(gate), "--adb", adb, "--serial", SERIAL], check=False)
+    else:
+        _run_quiet(cmd(adb, "-s", SERIAL, "shell", "input", "keyevent", "82"))
 
 
 def run_tests(test_classes: str) -> int:
@@ -420,7 +427,7 @@ def main() -> int:
         proc = start_emulator(emulator)
         if wait_for_boot(adb, proc, BOOT_TIMEOUT):
             print("Emulator booted.")
-            dismiss_keyguard(adb)
+            prepare_focus(adb)
             _STATE.test_exit = run_tests(args.test_classes)
         else:
             warn(f"Emulator did not reach sys.boot_completed within {BOOT_TIMEOUT}s.")
diff --git a/.github/scripts/emulator_focus_gate.py b/.github/scripts/emulator_focus_gate.py
new file mode 100644
index 0000000..44ade49
--- /dev/null
+++ b/.github/scripts/emulator_focus_gate.py
@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""emulator_focus_gate.py -- make a booted emulator reliably grant the app window focus
+BEFORE an instrumented UI suite runs, then GATE on that state (issue #468).
+
+WHY THIS EXISTS  (issue #468 -- the environmental app-window-focus flake)
+------------------------------------------------------------------------
+Intermittently, on the CI emulator the launched activity window has
+``has-window-focus=false`` for the WHOLE instrumented run, so Espresso's ``RootViewPicker``
+(used by ``onView(...).check()``, ``Intents.intended()``, ``Espresso.pressBack()`` and
+focus-dependent clipboard reads) waits 10s for a focused root and times out --
+``RootViewWithoutFocusException``. It fails EVERY window-focus-dependent test at once while
+the ~280 pure-Compose semantics tests (which do not need window focus) pass. Root-cause
+evidence from a failing ``E2E (35)`` leg (PR #470, run 28985259521): across the entire
+captured logcat ``has-window-focus=true`` appears ZERO times and both the first attempt and
+the once-retry fail identically -- i.e. the window NEVER gains focus for the session, a
+persistent environmental state, not a per-test transient.
+
+The prior mitigation was a single fire-and-forget ``adb shell input keyevent 82`` (MENU)
+right after ``sys.boot_completed=1``. On modern Android (API 30+) MENU does NOT reliably
+dismiss the keyguard, and when it is delivered before SystemUI/keyguard finishes coming up it
+is simply dropped ("no focused window"). The insecure keyguard / non-interactive display then
+persists and no app window ever takes focus -- hence the intermittent, whole-leg flake.
+
+WHAT THIS DOES
+--------------
+A single shared mechanism invoked identically by every E2E job (the ``e2e`` API 29-36 matrix
+AND the ``e2e-preview`` API 37 job in ``.github/workflows/ci.yml``) and by the local preflight
+runners (``local_instrumented.py`` / ``api37_e2e.py``), so the fix cannot drift between them:
+
+  1. PREPARE the device so an app window CAN take focus, and keep it that way for the whole
+     run (all best-effort; a missing service right after boot must never abort the leg):
+       * ``input keyevent WAKEUP`` (224)  -- force the display INTERACTIVE (never toggles it
+         off the way POWER would).
+       * ``wm dismiss-keyguard``          -- dismiss the (insecure) keyguard now.
+       * ``locksettings set-disabled true`` -- disable the lock screen for the session so it
+         cannot re-curtain the app window mid-run.
+       * ``svc power stayon true`` + a max ``screen_off_timeout`` -- never sleep during the run.
+       * ``input keyevent 82`` (MENU)     -- legacy nudge, kept harmless for parity with #454.
+       * zero the three animation scales   -- deterministic UI tests (this also gives the
+         ``e2e-preview`` job the animation-disable the matrix already had -- uniformly).
+  2. GATE: poll ``dumpsys power`` + ``dumpsys window`` until the device is interactive
+     (``mWakefulness=Awake``) AND a real window holds input focus (``mCurrentFocus`` is a
+     ``Window{...}``, not ``null``) -- i.e. the exact precondition ``RootViewPicker`` needs --
+     re-issuing the wake / dismiss-keyguard nudges each iteration so a lost race self-heals.
+
+The gate is SOFT: it waits up to ``--timeout`` seconds and then proceeds regardless, printing a
+GitHub ``::warning::`` annotation and the final device state if it never confirmed focus (the
+determinism comes from the PREPARE actions + the wait; a parsing quirk on some API level must
+not convert an otherwise-fine leg into a hard failure -- the real tests remain the arbiter).
+It always prints the final ``mWakefulness`` / ``mCurrentFocus`` / keyguard state so a genuine
+environmental failure is diagnosable from the step log without downloading artifacts.
+
+Pure standard library, cross-platform (Windows / Linux / macOS): ``adb`` is invoked via
+subprocess. The readiness parser (``evaluate_readiness``) is a pure function, unit-tested by
+``test_emulator_focus_gate.py`` (run by the ``traffic-control-tests`` CI job).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import subprocess
+import sys
+import time
+from typing import NamedTuple
+
+# WAKEUP (not POWER): guarantees the display ends up INTERACTIVE. POWER (26) toggles, so it
+# would turn an already-on display OFF. MENU (82) is kept only as a legacy parity nudge.
+KEYCODE_WAKEUP = "224"
+KEYCODE_MENU = "82"
+# Max int -- effectively "never" auto-sleep the screen during the suite.
+SCREEN_OFF_TIMEOUT_MS = "2147483647"
+DEFAULT_TIMEOUT_S = 90
+POLL_INTERVAL_S = 2
+
+
+class Readiness(NamedTuple):
+    """Outcome of parsing ``dumpsys power`` + ``dumpsys window`` for focus readiness."""
+
+    ready: bool
+    awake: bool
+    focus_state: str  # 'focused' | 'unfocused' | 'unknown'
+    focus_value: str  # the mCurrentFocus / mFocusedWindow token, or ''
+    keyguard_state: str  # 'showing' | 'not_showing' | 'unknown'
+
+    @property
+    def summary(self) -> str:
+        return (
+            f"awake={self.awake} focus={self.focus_state}"
+            f"({self.focus_value or '-'}) keyguard={self.keyguard_state}"
+        )
+
+
+def _is_awake(power_out: str) -> bool:
+    """True if ``dumpsys power`` reports an INTERACTIVE display. ``mWakefulness=Awake`` is the
+    stable signal across API 29-37; ``Display Power: state=ON`` / ``mInteractive=true`` are
+    accepted as fallbacks for dump-format drift."""
+    return bool(
+        re.search(r"mWakefulness=Awake\b", power_out)
+        or re.search(r"Display Power:\s*state=ON\b", power_out)
+        or re.search(r"mInteractive=true\b", power_out)
+    )
+
+
+def _focus(window_out: str) -> tuple[str, str]:
+    """Classify the current input focus from ``dumpsys window``.
+
+    Returns ``(state, value)`` where state is 'focused' (a non-null ``Window{...}`` holds
+    focus -- what RootViewPicker needs), 'unfocused' (focus is explicitly ``null`` -- asleep /
+    keyguard-curtained / no focusable window), or 'unknown' (the field is absent on this dump
+    format). ``mCurrentFocus`` is preferred; ``mFocusedWindow`` is the fallback field name."""
+    tokens = re.findall(r"mCurrentFocus=(\S+)", window_out)
+    if not tokens:
+        tokens = re.findall(r"mFocusedWindow=(\S+)", window_out)
+    if not tokens:
+        return ("unknown", "")
+    non_null = [t for t in tokens if t != "null"]
+    if non_null:
+        return ("focused", non_null[0])
+    return ("unfocused", "null")
+
+
+def _keyguard(window_out: str) -> str:
+    """Best-effort keyguard state from ``dumpsys window``: 'showing' / 'not_showing' /
+    'unknown'. Informational for the summary, plus a fallback readiness signal when the focus
+    field is absent. Field names vary by API level, so several are accepted."""
+    match = re.search(
+        r"(?:mShowingLockscreen|mDreamingLockscreen|isKeyguardShowing|"
+        r"mKeyguardShowing|keyguardShowing|mKeyguardOccluded)=(true|false)",
+        window_out,
+    )
+    if not match:
+        return "unknown"
+    return "showing" if match.group(1) == "true" else "not_showing"
+
+
+def evaluate_readiness(power_out: str, window_out: str) -> Readiness:
+    """Pure decision core (unit-tested). The device is READY for a focus-dependent UI suite
+    when it is interactive AND a real window holds input focus. When the focus field is absent
+    on a given dump format, fall back to "interactive AND keyguard explicitly not showing" so a
+    format quirk cannot hang the gate forever."""
+    awake = _is_awake(power_out)
+    focus_state, focus_value = _focus(window_out)
+    keyguard_state = _keyguard(window_out)
+    ready = awake and (
+        focus_state == "focused"
+        or (focus_state == "unknown" and keyguard_state == "not_showing")
+    )
+    return Readiness(ready, awake, focus_state, focus_value, keyguard_state)
+
+
+def _adb_base(adb: str, serial: str | None) -> list[str]:
+    return [adb, "-s", serial] if serial else [adb]
+
+
+def _adb_quiet(adb: str, serial: str | None, *args: str) -> None:
+    """Run an ``adb`` command, swallowing output and any error -- every prepare nudge is
+    best-effort (a service can lose a race right after boot; a missing tool must not abort)."""
+    try:
+        subprocess.run(
+            _adb_base(adb, serial) + list(args),
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+            timeout=30,
+        )
+    except (OSError, subprocess.SubprocessError):
+        pass
+
+
+def _adb_capture(adb: str, serial: str | None, *args: str) -> str:
+    try:
+        return (
+            subprocess.run(
+                _adb_base(adb, serial) + list(args),
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=30,
+            ).stdout
+            or ""
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+
+
+def nudge_focus(adb: str, serial: str | None) -> None:
+    """Wake the display + dismiss the keyguard. Cheap and idempotent, so it is re-issued every
+    poll iteration to self-heal a nudge that lost the post-boot race with SystemUI/keyguard."""
+    _adb_quiet(adb, serial, "shell", "input", "keyevent", KEYCODE_WAKEUP)
+    _adb_quiet(adb, serial, "shell", "wm", "dismiss-keyguard")
+
+
+def prepare_device(adb: str, serial: str | None) -> None:
+    """One-time device preparation: disable the lock screen for the session, keep the screen on
+    for the whole run, zero the animation scales for deterministic UI tests, and issue the first
+    wake / dismiss-keyguard nudge. All best-effort."""
+    print("focus-gate: preparing device (wake + dismiss-keyguard + stay-awake + no-animations)")
+    nudge_focus(adb, serial)
+    _adb_quiet(adb, serial, "shell", "input", "keyevent", KEYCODE_MENU)  # legacy #454 parity
+    _adb_quiet(adb, serial, "shell", "locksettings", "set-disabled", "true")
+    _adb_quiet(adb, serial, "shell", "svc", "power", "stayon", "true")
+    _adb_quiet(adb, serial, "shell", "settings", "put", "system",
+               "screen_off_timeout", SCREEN_OFF_TIMEOUT_MS)
+    for scale in ("window_animation_scale", "transition_animation_scale",
+                  "animator_duration_scale"):
+        _adb_quiet(adb, serial, "shell", "settings", "put", "global", scale, "0.0")
+
+
+def probe(adb: str, serial: str | None) -> Readiness:
+    power_out = _adb_capture(adb, serial, "shell", "dumpsys", "power")
+    window_out = _adb_capture(adb, serial, "shell", "dumpsys", "window")
+    return evaluate_readiness(power_out, window_out)
+
+
+def wait_for_focus(adb: str, serial: str | None, timeout: int, label: str) -> Readiness:
+    """Prepare the device, then poll (re-nudging each iteration) until it is interactive with a
+    focused window, or ``timeout`` seconds elapse. Returns the final Readiness (SOFT gate: the
+    caller proceeds regardless -- see the module docstring)."""
+    tag = f" [{label}]" if label else ""
+    prepare_device(adb, serial)
+    deadline = time.monotonic() + timeout
+    last = probe(adb, serial)
+    attempt = 0
+    while True:
+        if last.ready:
+            elapsed = timeout - max(0, int(deadline - time.monotonic()))
+            print(f"focus-gate{tag}: READY after ~{elapsed}s -- {last.summary}")
+            return last
+        if time.monotonic() >= deadline:
+            print(f"::warning::focus-gate{tag}: window focus NOT confirmed within {timeout}s "
+                  f"-- proceeding anyway -- {last.summary}")
+            return last
+        attempt += 1
+        if attempt % 5 == 0:
+            print(f"focus-gate{tag}: waiting for window focus -- {last.summary}")
+        nudge_focus(adb, serial)
+        time.sleep(POLL_INTERVAL_S)
+        last = probe(adb, serial)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="emulator_focus_gate.py",
+        description=(
+            "Force a booted emulator to grant the app window focus (wake + dismiss-keyguard + "
+            "stay-awake + no-animations) and gate on that state before an instrumented UI "
+            "suite runs. Shared by CI's e2e / e2e-preview jobs and the local preflight runners "
+            "(issue #468)."
+        ),
+    )
+    parser.add_argument("--serial", default=None,
+                        help="adb device serial (default: the single attached device).")
+    parser.add_argument("--adb", default=None,
+                        help="Path to adb (default: resolve from PATH). For callers that resolve "
+                             "adb from the SDK rather than PATH (e.g. api37_e2e.py).")
+    parser.add_argument("--timeout", type=int, default=DEFAULT_TIMEOUT_S,
+                        help=f"Max seconds to wait for window focus (default {DEFAULT_TIMEOUT_S}).")
+    parser.add_argument("--label", default="",
+                        help="Label for log lines (e.g. an API level), for multi-leg runs.")
+    args = parser.parse_args(argv)
+
+    adb = args.adb or shutil.which("adb")
+    if not adb:
+        # Non-fatal by contract: never turn a missing-tool hiccup into a red leg. The suite that
+        # follows will surface a genuinely broken device.
+        print("::warning::focus-gate: adb not on PATH -- skipping focus preparation/gate")
+        return 0
+
+    wait_for_focus(adb, args.serial, args.timeout, args.label)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.github/scripts/test_emulator_focus_gate.py b/.github/scripts/test_emulator_focus_gate.py
new file mode 100644
index 0000000..6afa073
--- /dev/null
+++ b/.github/scripts/test_emulator_focus_gate.py
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Unit tests for the pure readiness parser of emulator_focus_gate.py (no adb, no emulator).
+
+Covers the decision core that decides whether a booted emulator is ready for a focus-dependent
+instrumented UI suite (issue #468): interactive (``mWakefulness=Awake``) AND a real window holds
+input focus (``mCurrentFocus`` is a non-null ``Window{...}``). The window-focus flake this guards
+against is exactly the "awake but mCurrentFocus=null" state, so that case must read NOT ready."""
+
+from __future__ import annotations
+
+import unittest
+
+import emulator_focus_gate as gate
+
+# A ``dumpsys power`` where the display is interactive vs. asleep.
+POWER_AWAKE = "Power Manager State:\n  mWakefulness=Awake\n  mWakefulnessChanging=false\n"
+POWER_ASLEEP = "Power Manager State:\n  mWakefulness=Asleep\n  mWakefulnessChanging=false\n"
+
+# ``dumpsys window`` with a focused app window (the healthy state RootViewPicker needs)...
+WINDOW_FOCUSED = (
+    "  mCurrentFocus=Window{23e192a u0 org.libremail.app/org.libremail.MainActivity}\n"
+    "  mFocusedApp=ActivityRecord{a1 u0 org.libremail.app/.MainActivity t9}\n"
+    "  mDreamingLockscreen=false\n"
+)
+# ...and the flake state: interactive-parse aside, NO window holds focus.
+WINDOW_NO_FOCUS = "  mCurrentFocus=null\n  mFocusedApp=null\n  mDreamingLockscreen=true\n"
+
+
+class AwakeParsingTests(unittest.TestCase):
+    def test_mwakefulness_awake(self) -> None:
+        self.assertTrue(gate._is_awake(POWER_AWAKE))
+
+    def test_mwakefulness_asleep(self) -> None:
+        self.assertFalse(gate._is_awake(POWER_ASLEEP))
+
+    def test_display_power_state_on_fallback(self) -> None:
+        self.assertTrue(gate._is_awake("Display Power: state=ON"))
+
+    def test_minteractive_fallback(self) -> None:
+        self.assertTrue(gate._is_awake("mInteractive=true"))
+
+    def test_empty_is_not_awake(self) -> None:
+        self.assertFalse(gate._is_awake(""))
+
+
+class FocusParsingTests(unittest.TestCase):
+    def test_non_null_current_focus(self) -> None:
+        state, value = gate._focus(WINDOW_FOCUSED)
+        self.assertEqual(state, "focused")
+        self.assertTrue(value.startswith("Window{"))
+
+    def test_null_current_focus(self) -> None:
+        self.assertEqual(gate._focus(WINDOW_NO_FOCUS), ("unfocused", "null"))
+
+    def test_focused_window_fallback_field(self) -> None:
+        state, value = gate._focus("mFocusedWindow=Window{deadbeef u0 launcher}\n")
+        self.assertEqual(state, "focused")
+        self.assertEqual(value, "Window{deadbeef")
+
+    def test_absent_focus_field_is_unknown(self) -> None:
+        self.assertEqual(gate._focus("no focus fields here"), ("unknown", ""))
+
+
+class KeyguardParsingTests(unittest.TestCase):
+    def test_showing(self) -> None:
+        self.assertEqual(gate._keyguard("mDreamingLockscreen=true"), "showing")
+
+    def test_not_showing(self) -> None:
+        self.assertEqual(gate._keyguard("isKeyguardShowing=false"), "not_showing")
+
+    def test_unknown(self) -> None:
+        self.assertEqual(gate._keyguard("nothing relevant"), "unknown")
+
+
+class EvaluateReadinessTests(unittest.TestCase):
+    def test_awake_and_focused_is_ready(self) -> None:
+        result = gate.evaluate_readiness(POWER_AWAKE, WINDOW_FOCUSED)
+        self.assertTrue(result.ready)
+        self.assertTrue(result.awake)
+        self.assertEqual(result.focus_state, "focused")
+
+    def test_the_flake_awake_but_no_focus_is_not_ready(self) -> None:
+        # The exact issue #468 signature: display parses/awake but no window has focus.
+        result = gate.evaluate_readiness(POWER_AWAKE, WINDOW_NO_FOCUS)
+        self.assertFalse(result.ready)
+
+    def test_asleep_even_with_focus_is_not_ready(self) -> None:
+        result = gate.evaluate_readiness(POWER_ASLEEP, WINDOW_FOCUSED)
+        self.assertFalse(result.ready)
+
+    def test_unknown_focus_but_awake_and_keyguard_gone_is_ready(self) -> None:
+        # Fallback so a dump format without mCurrentFocus can't hang the gate forever.
+        result = gate.evaluate_readiness(POWER_AWAKE, "mDreamingLockscreen=false")
+        self.assertTrue(result.ready)
+
+    def test_unknown_focus_and_keyguard_showing_is_not_ready(self) -> None:
+        result = gate.evaluate_readiness(POWER_AWAKE, "mDreamingLockscreen=true")
+        self.assertFalse(result.ready)
+
+    def test_unknown_focus_and_keyguard_unknown_is_not_ready(self) -> None:
+        result = gate.evaluate_readiness(POWER_AWAKE, "")
+        self.assertFalse(result.ready)
+
+    def test_summary_is_human_readable(self) -> None:
+        summary = gate.evaluate_readiness(POWER_AWAKE, WINDOW_FOCUSED).summary
+        self.assertIn("awake=True", summary)
+        self.assertIn("focus=focused", summary)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a03b1ce..5b27e4e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -632,12 +632,20 @@ jobs:
           for attempt in 1 2; do boot_emulator "$attempt" && { booted=1; break; }; done
           [ "$booted" = "1" ] || { echo "::error::API ${{ matrix.api-level }} emulator failed to boot after 2 attempts"; exit 1; }
 
-          # NON-FATAL unlock (the boot-race fix) + disable animations for deterministic UI tests
-          # (parity with the replaced android-emulator-runner `disable-animations: true`).
-          adb shell input keyevent 82 || true
-          adb shell settings put global window_animation_scale 0.0 || true
-          adb shell settings put global transition_animation_scale 0.0 || true
-          adb shell settings put global animator_duration_scale 0.0 || true
+          # Focus/readiness gate (issue #468): the durable fix for the intermittent app-window-
+          # focus flake. Occasionally the launched activity window has has-window-focus=false for
+          # the WHOLE run, so Espresso's RootViewPicker (onView().check(), Intents.intended(),
+          # pressBack(), focus-dependent clipboard) times out after 10s and fails EVERY
+          # focus-dependent test at once while the ~280 pure-Compose tests pass (evidence: a
+          # failing E2E leg's logcat had has-window-focus=true ZERO times, both attempt + retry).
+          # The single `input keyevent 82` here was too weak (MENU no longer dismisses the modern
+          # keyguard, and races SystemUI coming up). This shared helper WAKES the display, dismisses
+          # + disables the keyguard, keeps the screen on, disables animations (parity with the
+          # replaced `disable-animations: true`), then WAITS until a real window holds input focus
+          # before the suite runs. It is the IDENTICAL mechanism the e2e-preview job and the local
+          # preflight runners invoke, so the fix cannot drift between jobs. Non-fatal (`|| true`),
+          # preserving #454's guarantee that the unlock never aborts the boot.
+          python3 .github/scripts/emulator_focus_gate.py --label "api${{ matrix.api-level }}" || true
 
           # WEDGE (hang) smoking-gun capture (#404, restored to the matrix by #421). On the wrapper
           # `timeout` below (exit 124), grab the smoking gun WHILE this hand-provisioned emulator is
@@ -968,7 +976,13 @@ jobs:
           for attempt in 1 2; do boot_emulator "$attempt" && { booted=1; break; }; done
           [ "$booted" = "1" ] || { echo "::error::API 37 preview emulator failed to boot after 2 attempts"; exit 1; }
 
-          adb shell input keyevent 82 || true
+          # Focus/readiness gate (issue #468) -- the IDENTICAL shared mechanism the `e2e` matrix job
+          # (and the local preflight runners) invoke, so the fix can't drift: wake the display,
+          # dismiss + disable the keyguard, keep the screen on, disable animations, then WAIT until a
+          # real window holds input focus before the suite runs. This replaces the lone `input
+          # keyevent 82` and, applied UNIFORMLY, also gives this preview job the animation-disable
+          # the matrix already had. Non-fatal (`|| true`) -- the unlock must never abort the boot.
+          python3 .github/scripts/emulator_focus_gate.py --label "api37-shard${{ matrix.shard }}" || true
 
           # WEDGE (hang) smoking-gun capture (#404). On the wrapper `timeout` below (exit 124), grab
           # the smoking gun WHILE this hand-provisioned emulator is still alive (it stays up until the
-- 
2.47.3