create-cmp-cli 0.10.1 → 0.12.0

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/AlarmAsserts.kt

@@ -0,0 +1,152 @@
+package __PACKAGE__.testing
+
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+
+/**
+ * Alarm assertions against the OS alarm table (`dumpsys alarm`) — what AlarmManager
+ * actually HOLDS for this app, not what the app believes it scheduled.
+ *
+ * Why this exists — the PendingIntent identity trap: AlarmManager keys alarms by
+ * PendingIntent identity (creator + request code + intent filterEquals — extras excluded).
+ * Two logically distinct alarms built with the same request code and an intent differing
+ * only in extras silently collapse into ONE slot: the second `set()` replaces the first,
+ * no error, no log line, and every JVM tier stays green. The only place the collapse is
+ * visible is the OS alarm table, which is what this file reads.
+ *
+ * Constraints the code can't show:
+ *  - `dumpsys alarm` is a human-oriented dump whose exact format shifts across API levels
+ *    and OEMs. The parser below is deliberately tolerant — it anchors on the stable parts
+ *    (`Alarm{... this-package}` entry lines, the indented `tag=` detail) and carries the
+ *    raw block so a predicate can always fall back to substring matching. If a future
+ *    Android release reshuffles the dump, fix the parser here, once — tests state intent
+ *    through predicates, not format.
+ *  - Reading the table proves REGISTRATION, not delivery. Delivery is its own proof:
+ *    [TimeWarp] warps the clock past the trigger, and [DozeControl] holds the device in
+ *    forced idle while it happens. App-standby buckets and OEM battery managers remain
+ *    outside the seam's reach (see docs/TESTING.md).
+ *  - The shell runs with the instrumentation's uiAutomation (shell uid, via [Shell.exec]),
+ *    so no permission or root is needed.
+ */
+object AlarmAsserts {
+
+    /**
+     * One row of the OS alarm table attributed to [packageName].
+     *
+     * @property whenMs the alarm's trigger wall/elapsed time in ms as printed by the dump
+     *   (`when` field), or null when the entry line carries no parseable `when`.
+     * @property tag the `tag=` detail line if present (AlarmManager's listener/operation
+     *   tag, e.g. `*walarm*:pkg/receiver`), else "".
+     * @property raw the full dump block for this entry — the fallback surface for
+     *   predicates when the parsed fields aren't enough.
+     */
+    data class RegisteredAlarm(val whenMs: Long?, val tag: String, val raw: String)
+
+    /** All alarms the OS currently holds for [packageName] (default: the app under test). */
+    fun registeredAlarms(
+        packageName: String =
+            InstrumentationRegistry.getInstrumentation().targetContext.packageName,
+    ): List<RegisteredAlarm> = parseDumpsysAlarm(Shell.exec("dumpsys alarm"), packageName)
+
+    /**
+     * Asserts at least one alarm matching [predicate] is registered. [what] names the
+     * expectation in the failure message ("the daily-reset alarm").
+     */
+    fun assertAlarmRegistered(
+        what: String = "a matching alarm",
+        packageName: String =
+            InstrumentationRegistry.getInstrumentation().targetContext.packageName,
+        predicate: (RegisteredAlarm) -> Boolean,
+    ) {
+        val alarms = registeredAlarms(packageName)
+        assertTrue(
+            "$what is not in the OS alarm table for $packageName. " +
+                "Registered: ${describe(alarms)}",
+            alarms.any(predicate),
+        )
+    }
+
+    /**
+     * Asserts EXACTLY [expected] matching alarms are registered — the generic form of the
+     * PendingIntent-identity-collision bug. If two logical alarms share one PendingIntent
+     * slot, the table holds one entry and this fails with the survivors listed; schedule
+     * your N alarms, then assert N distinct rows.
+     */
+    fun assertDistinctAlarms(
+        expected: Int,
+        what: String = "matching alarms",
+        packageName: String =
+            InstrumentationRegistry.getInstrumentation().targetContext.packageName,
+        predicate: (RegisteredAlarm) -> Boolean,
+    ) {
+        val matching = registeredAlarms(packageName).filter(predicate)
+        assertEquals(
+            "expected $expected distinct $what in the OS alarm table but found " +
+                "${matching.size} — fewer than scheduled usually means two logical alarms " +
+                "share one PendingIntent identity (same request code + filter-equal intent) " +
+                "and the later set() replaced the earlier. Found: ${describe(matching)}",
+            expected,
+            matching.size,
+        )
+    }
+
+    // ── dump plumbing ───────────────────────────────────────────────────────
+
+    /**
+     * Tolerant `dumpsys alarm` parse: an entry starts at a line containing
+     * `Alarm{... <packageName>` (batched and unbatched dumps both print this shape) and
+     * runs until the next entry line or an outdent. `when <millis>` is read off the entry
+     * line when present; the first indented `tag=` detail line is captured.
+     */
+    internal fun parseDumpsysAlarm(dump: String, packageName: String): List<RegisteredAlarm> {
+        val entryRe = Regex("""Alarm\{[^}]*\b${Regex.escape(packageName)}\b[^}]*\}""")
+        // Entry-line trigger time. Two shapes across API levels: legacy prints
+        // `when <ms>`, modern (S+) prints `origWhen <ms> whenElapsed <ms>` — origWhen is
+        // the requested wall/elapsed time, which is what a test scheduled and can equate.
+        // Digits only, deliberately: the DETAIL lines print `when=+56m6s0ms` (a formatted
+        // duration), and a looser pattern would swallow that "+56" as milliseconds.
+        val whenRe = Regex("""\b(?:origWhen|when)\b[ =]+(\d+)""")
+        val tagRe = Regex("""\btag=(\S+)""")
+
+        val lines = dump.lines()
+        val alarms = mutableListOf<RegisteredAlarm>()
+        var i = 0
+        while (i < lines.size) {
+            val line = lines[i]
+            if (entryRe.containsMatchIn(line)) {
+                val entryIndent = line.indexOfFirst { !it.isWhitespace() }.coerceAtLeast(0)
+                val block = StringBuilder(line)
+                var tag = tagRe.find(line)?.groupValues?.get(1) ?: ""
+                var j = i + 1
+                while (j < lines.size) {
+                    val next = lines[j]
+                    val nextIndent = next.indexOfFirst { !it.isWhitespace() }
+                    // Stop at the next entry, a blank line, or an outdent back to/above
+                    // this entry's level — the detail lines of an entry are indented past it.
+                    if (next.isBlank() || entryRe.containsMatchIn(next) ||
+                        (nextIndent in 0..entryIndent)
+                    ) break
+                    block.append('\n').append(next)
+                    if (tag.isEmpty()) tag = tagRe.find(next)?.groupValues?.get(1) ?: ""
+                    j++
+                }
+                alarms.add(
+                    RegisteredAlarm(
+                        whenMs = whenRe.find(line)?.groupValues?.get(1)?.toLongOrNull(),
+                        tag = tag,
+                        raw = block.toString(),
+                    ),
+                )
+                i = j
+            } else {
+                i++
+            }
+        }
+        return alarms
+    }
+
+    private fun describe(alarms: List<RegisteredAlarm>): String =
+        if (alarms.isEmpty()) "(none)"
+        else alarms.joinToString { "[when=${it.whenMs} tag=${it.tag}]" }
+}

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/ConfigControl.kt

@@ -0,0 +1,124 @@
+package __PACKAGE__.testing
+
+import android.os.Build
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assume.assumeTrue
+
+/**
+ * Configuration control for the on-device tier — dark mode, font scale, and per-app
+ * locale as test inputs.
+ *
+ * Why this exists: configuration is the OTHER classic state-loss lever. Every one of
+ * these switches delivers a configuration change, and a configuration change destroys
+ * and recreates the foreground activity — the same "came back and it was gone" class
+ * [ProcessControl] targets, triggered by the user flipping dark mode or bumping the
+ * system font size mid-session. The JVM tiers render one configuration forever; a claim
+ * like "the form survives the user toggling dark mode" or "the layout holds at 1.3x
+ * font scale" needs the device to actually change underneath the running app. Compose
+ * with the seam's observation helpers: flip the config, then assert what the app did
+ * about it.
+ *
+ * Mechanisms, each verified root-free from the shell uid on a stock user-build emulator
+ * image (API 35), each snapshot-restored in `finally`:
+ *  - [withDarkMode] — `cmd uimode night yes|no` (read back via the same command's
+ *    "Night mode: X" line, so restore is snapshot-exact, including `auto` and the
+ *    custom modes).
+ *  - [withFontScale] — `settings put system font_scale <x>`; an absent prior value is
+ *    DELETED on restore, not defaulted to 1.0 (see [Shell.restoreSetting]).
+ *  - [withAppLocale] — `cmd locale set-app-locales <pkg> --locales <tags>`, the per-app
+ *    locale system (API 33+; the bracket SKIPs below that). App-scoped on purpose: it
+ *    is the same state the user's own per-app language setting writes, and it touches
+ *    no other app on the device. Restore passes the snapshotted list back, or clears by
+ *    omitting `--locales` (the documented "empty when unspecified").
+ *
+ * Constraints the code can't show:
+ *  - DEVICE-WIDE locale has no root-free path — changing it needs
+ *    CHANGE_CONFIGURATION/root, so this organ does not offer it rather than offering a
+ *    broken version of it. For "the whole device is German", set the AVD up that way;
+ *    for "this app renders German", [withAppLocale] is the real user-reachable state.
+ *  - Config delivery is asynchronous and, for a foreground activity, DESTRUCTIVE — the
+ *    activity you held a reference to before the flip is not the one resumed after it.
+ *    That is the point, not a flake: capture identity before, await the recreated
+ *    activity ([ProcessControl.resumedActivity]), then assert.
+ *  - What the app DOES with the change (re-render, reload resources, lose the form) is
+ *    the app's half; these brackets only guarantee the device half moved.
+ */
+object ConfigControl {
+
+    private val context
+        get() = InstrumentationRegistry.getInstrumentation().targetContext
+
+    /**
+     * Run [block] with night mode forced on (`cmd uimode night yes`), restoring the
+     * snapshotted mode afterwards even when the block throws.
+     */
+    fun <T> withDarkMode(block: () -> T): T {
+        assumeEmulator("Forcing dark mode")
+        val prior = readNightMode()
+        Shell.exec("cmd uimode night yes")
+        try {
+            return block()
+        } finally {
+            Shell.exec("cmd uimode night $prior")
+        }
+    }
+
+    /**
+     * Run [block] with the system font scale at [scale] (e.g. 1.3f — the accessibility
+     * sizes users actually run), restoring the prior value (or its absence) afterwards.
+     */
+    fun <T> withFontScale(scale: Float, block: () -> T): T {
+        assumeEmulator("Changing the font scale")
+        val prior = Shell.readSetting("system", "font_scale")
+        Shell.exec("settings put system font_scale $scale")
+        try {
+            return block()
+        } finally {
+            Shell.restoreSetting("system", "font_scale", prior)
+        }
+    }
+
+    /**
+     * Run [block] with the app under test set to [languageTag] (BCP-47, e.g. "fr-FR"),
+     * via the per-app locale system — API 33+; SKIPs (assumption) below that, never
+     * vacuously green. Restores the snapshotted locale list afterwards.
+     */
+    fun <T> withAppLocale(languageTag: String, block: () -> T): T {
+        assumeEmulator("Changing the app locale")
+        assumeTrue(
+            "per-app locales need API 33+ (device is ${Build.VERSION.SDK_INT}); there " +
+                "is no root-free device-wide locale switch to fall back to — configure " +
+                "the AVD's locale instead for older images",
+            Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU,
+        )
+        val prior = readAppLocales() // comma-separated tags, or "" when following system
+        Shell.exec("cmd locale set-app-locales ${context.packageName} --locales $languageTag")
+        try {
+            return block()
+        } finally {
+            if (prior.isEmpty()) {
+                // Omitting --locales is the documented "empty list", i.e. follow system.
+                Shell.exec("cmd locale set-app-locales ${context.packageName}")
+            } else {
+                Shell.exec("cmd locale set-app-locales ${context.packageName} --locales $prior")
+            }
+        }
+    }
+
+    /** The current night mode word as `cmd uimode night` prints it (`yes`/`no`/`auto`/custom). */
+    private fun readNightMode(): String =
+        Shell.exec("cmd uimode night").substringAfter("Night mode:").trim().ifEmpty { "no" }
+
+    /** The app's current locale list ("fr-FR,en" style), or "" when it follows the system. */
+    private fun readAppLocales(): String =
+        Shell.exec("cmd locale get-app-locales ${context.packageName}")
+            .substringAfter("are [", "").substringBefore("]").trim()
+
+    private fun assumeEmulator(what: String) {
+        Shell.assumeOnEmulator(
+            "ConfigControl runs only on emulators (ro.kernel.qemu != 1 here). $what on " +
+                "a real phone rewrites its owner's chosen settings — run this suite on " +
+                "a stock QA AVD instead.",
+        )
+    }
+}

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/DozeControl.kt

@@ -0,0 +1,113 @@
+package __PACKAGE__.testing
+
+import android.os.SystemClock
+import org.junit.Assert.assertEquals
+
+/**
+ * Doze (device idle) control for the on-device tier — put the device INTO the state the
+ * claim is about, instead of shipping the claim and waiting for the field to test it.
+ *
+ * Why this exists: Doze is the #1 production cause of "the alarm never fired". A device
+ * that sits still on battery drops into deep idle, and in that state regular alarms are
+ * deferred to the next maintenance window — hours away — while `setExactAndAllowWhileIdle`
+ * exists ENTIRELY to punch through it. That API's whole value is its behavior in a state
+ * no test tier ever visited: the JVM tiers can't see the OS, [AlarmAsserts] proves the OS
+ * holds the alarm, [TimeWarp] proves delivery on an awake device — and "delivers from
+ * inside Doze", the actual production claim, shipped unverified every time. This organ
+ * closes that: force the idle state, then let TimeWarp warp past the trigger, and the
+ * delivery-from-Doze claim becomes a sixty-second test (see RuntimeStateSeamTest for the
+ * composed exemplar).
+ *
+ * The sequence, each command verified root-free from the shell uid on a stock user-build
+ * emulator image (API 35):
+ *
+ *   1. `dumpsys battery unplug` — fake "on battery". Real Doze never engages on charge;
+ *      modern `force-idle` no longer strictly requires this, but older API levels did and
+ *      the precondition is part of the state being modeled, so it stays.
+ *   2. `dumpsys deviceidle force-idle deep|light` — teleport straight into the idle
+ *      state ("Now forced in to deep idle mode"). Verified with `deviceidle get` — the
+ *      command's own output is not trusted.
+ *   3. the block — schedule/warp/assert.
+ *   4. finally: `dumpsys deviceidle unforce` + `dumpsys battery reset`, then a bounded
+ *      poll until the controller reports ACTIVE again. A test that leaves the device
+ *      idle poisons every later test, so the restore runs even when the block throws.
+ *
+ * HONESTY — what forced idle does and does not reproduce. Overclaiming here would be
+ * worse than the gap, so read this before citing a green test as proof:
+ *
+ *  REPRODUCED faithfully:
+ *   - The idle STATE itself, as AlarmManager sees it: regular alarms deferred,
+ *     `setAndAllowWhileIdle`/`setExactAndAllowWhileIdle` eligible to fire (throttled to
+ *     one window per app per ~9 minutes — one alarm per test is inside the budget).
+ *     This is the alarm-delivery policy, keyed on the DEVICE state, and it is exactly
+ *     the claim the composed exemplar proves.
+ *   - Light vs deep as distinct states (`IdleMode`): light restricts jobs/syncs; deep
+ *     is the full alarm-deferral regime. An exact-alarm claim is about DEEP.
+ *
+ *  NOT reproduced:
+ *   - The path INTO idle. `force-idle` skips the real ladder (screen-off, stationary,
+ *     IDLE_PENDING → SENSING → LOCATING → IDLE), so motion-exit and the timing of the
+ *     descent are untested here.
+ *   - Maintenance windows. Forced idle HOLDS the state; real deep Doze alternates
+ *     IDLE ↔ IDLE_MAINTENANCE. "My deferred work runs in the maintenance window" is a
+ *     different claim and this organ does not prove it.
+ *   - App-standby buckets. A separate throttling system (`am set-standby-bucket`),
+ *     untouched by this organ.
+ *   - The cached-process experience. Instrumentation pins the app's process at
+ *     foreground oom-adj, so the network-cutoff and job-suspension that a CACHED process
+ *     feels in deep Doze do not bite the app under test. The OS-side alarm policy above
+ *     is unaffected by that pinning — which is why the alarm claim survives this caveat
+ *     and a "my background sync pauses in Doze" claim does not.
+ *   - OEM battery managers (aggressive kill lists, vendor "optimization"). Emulator-only
+ *     by construction; the OEM half stays a documented manual tier.
+ */
+object DozeControl {
+
+    /** The two real idle regimes. An exact-alarm claim is about [DEEP]. */
+    enum class IdleMode(internal val arg: String) { LIGHT("light"), DEEP("deep") }
+
+    /**
+     * Run [block] with the device forced into [mode] idle, restoring everything
+     * afterwards even when the block throws. Entry is VERIFIED (`deviceidle get` must
+     * report IDLE) before the block runs — a bracket that silently failed to enter the
+     * state would hand out green for a claim it never tested.
+     *
+     * Composes with the other organs by nesting; the canonical composition is
+     * Doze outside, clock inside:
+     *
+     *   DozeControl.withDeviceIdle {
+     *     TimeWarp.withWarpedClock(target + epsilon) { awaitDelivery() }
+     *   }
+     */
+    fun <T> withDeviceIdle(mode: IdleMode = IdleMode.DEEP, block: () -> T): T {
+        Shell.assumeOnEmulator(
+            "DozeControl runs only on emulators (ro.kernel.qemu != 1 here). Forcing a " +
+                "real phone into idle silences its owner's real alarms and messages — " +
+                "run this suite on a stock QA AVD instead.",
+        )
+        Shell.exec("dumpsys battery unplug")
+        Shell.exec("dumpsys deviceidle force-idle ${mode.arg}")
+        try {
+            assertEquals(
+                "the device did not enter forced ${mode.arg} idle — without the state, " +
+                    "nothing this block asserts is about Doze. On a stock emulator this " +
+                    "sequence is verified to work; a changed image or API may need " +
+                    "`dumpsys deviceidle help` re-read.",
+                "IDLE",
+                Shell.exec("dumpsys deviceidle get ${mode.arg}").trim(),
+            )
+            return block()
+        } finally {
+            Shell.exec("dumpsys deviceidle unforce")
+            Shell.exec("dumpsys battery reset")
+            // Bounded settle: on the verified image `unforce` returns to ACTIVE
+            // immediately, but the next test deserves the wait, not the race.
+            val deadline = SystemClock.elapsedRealtime() + 5_000L
+            while (SystemClock.elapsedRealtime() < deadline &&
+                Shell.exec("dumpsys deviceidle get ${mode.arg}").trim() != "ACTIVE"
+            ) {
+                Thread.sleep(100)
+            }
+        }
+    }
+}

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/NetworkControl.kt

@@ -0,0 +1,137 @@
+package __PACKAGE__.testing
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.NetworkCapabilities
+import android.os.SystemClock
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assert.fail
+
+/**
+ * Network-state control for the on-device tier — make "offline" a state the test puts
+ * the device into, instead of a branch the code claims to handle.
+ *
+ * Why this exists: the template ships a connectivity abstraction
+ * (`core/connectivity/NetworkMonitor.kt`, expect/actual) whose entire reason to exist is
+ * behavior under network loss — and no tier could ever produce network loss, so every
+ * claim built on it (offline banners, retry paths, queued writes) was structurally
+ * unprovable. Desktop fakes prove the ViewModel folds a Boolean; only the device can
+ * prove the Boolean tracks the world.
+ *
+ * Mechanisms, each verified root-free from the shell uid on a stock user-build emulator
+ * image (API 35):
+ *  - [withAirplaneMode] — `cmd connectivity airplane-mode enable|disable`, the modern,
+ *    reliable, root-free switch (verified: active default network gone on enable, back
+ *    on disable; the same command queries the state, so restore is snapshot-exact).
+ *    The LEGACY route — `settings put global airplane_mode_on` plus a broadcast — is NOT
+ *    usable root-free on modern API levels: the broadcast is protected, and the setting
+ *    alone changes nothing. Prefer this bracket for "the app is offline".
+ *  - [withWifiDisabled] / [withMobileDataDisabled] — `svc wifi|data disable|enable`,
+ *    for claims about ONE transport (e.g. metered-only behavior, wifi-to-cellular
+ *    failover). Prior state is snapshotted from `settings get global wifi_on` /
+ *    `mobile_data` (both verified to track the toggles) so restore matches what was.
+ *
+ * Constraints the code can't show:
+ *  - State changes are ASYNCHRONOUS. Each bracket polls ConnectivityManager (bounded)
+ *    until the state actually lands before running the block — asserting "offline
+ *    behavior" while the network is still up tests nothing — and polls the way back on
+ *    exit, because a device left offline poisons every later test (the restore runs in
+ *    `finally` either way; if connectivity does not return in time the bracket fails
+ *    loudly rather than leaving a silent trap).
+ *  - The emulator's adb transport rides the qemu pipe, not the device's network — so
+ *    airplane mode cannot sever the harness from the device. On a REAL device attached
+ *    over wifi-adb it would, which is one more reason these brackets are emulator-only.
+ *  - Emulator networking is NAT through the host: "wifi" and "cellular" here are both
+ *    the host's connection wearing different transports. Presence/absence and transport
+ *    switching are faithful; bandwidth, latency, captive portals, and flaky-RSSI
+ *    behavior are not reproduced.
+ */
+object NetworkControl {
+
+    private val connectivity: ConnectivityManager
+        get() = InstrumentationRegistry.getInstrumentation().targetContext
+            .getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+
+    private const val SETTLE_TIMEOUT_MS = 15_000L
+
+    /**
+     * Run [block] with the device fully offline (airplane mode), restoring the prior
+     * airplane state afterwards even when the block throws. The block runs only after
+     * ConnectivityManager reports no active network; on exit the bracket waits for
+     * connectivity to return and fails loudly if it does not.
+     */
+    fun <T> withAirplaneMode(block: () -> T): T {
+        assumeEmulator("Airplane mode")
+        val prior = Shell.exec("cmd connectivity airplane-mode").trim() // enabled|disabled
+        Shell.exec("cmd connectivity airplane-mode enable")
+        try {
+            awaitState("no active network (airplane mode)") { connectivity.activeNetwork == null }
+            return block()
+        } finally {
+            Shell.exec("cmd connectivity airplane-mode ${if (prior == "enabled") "enable" else "disable"}")
+            if (prior != "enabled") {
+                awaitState("connectivity restored after airplane mode") {
+                    connectivity.activeNetwork != null
+                }
+            }
+        }
+    }
+
+    /**
+     * Run [block] with wifi off (`svc wifi disable`), restoring the snapshotted state.
+     * The block runs once no active network carries TRANSPORT_WIFI — on an emulator with
+     * cellular up, the default network fails over to it, which is itself testable
+     * behavior (assert what [block] sees, not that everything went dark).
+     */
+    fun <T> withWifiDisabled(block: () -> T): T =
+        withTransportDisabled("wifi", "wifi_on", NetworkCapabilities.TRANSPORT_WIFI, block)
+
+    /** Run [block] with mobile data off (`svc data disable`), restoring the snapshotted state. */
+    fun <T> withMobileDataDisabled(block: () -> T): T =
+        withTransportDisabled("data", "mobile_data", NetworkCapabilities.TRANSPORT_CELLULAR, block)
+
+    private fun <T> withTransportDisabled(
+        svcName: String,
+        settingKey: String,
+        transport: Int,
+        block: () -> T,
+    ): T {
+        assumeEmulator("Disabling $svcName")
+        val prior = Shell.readSetting("global", settingKey) // "1" | "0" | null
+        Shell.exec("svc $svcName disable")
+        try {
+            awaitState("no active network on the '$svcName' transport") {
+                !activeNetworkHas(transport)
+            }
+            return block()
+        } finally {
+            if (prior != "0") {
+                Shell.exec("svc $svcName enable")
+                awaitState("'$svcName' transport restored") { activeNetworkHas(transport) }
+            }
+        }
+    }
+
+    private fun activeNetworkHas(transport: Int): Boolean {
+        val network = connectivity.activeNetwork ?: return false
+        return connectivity.getNetworkCapabilities(network)?.hasTransport(transport) == true
+    }
+
+    /** Bounded poll; fails naming [what] so a timeout diagnoses itself. */
+    private fun awaitState(what: String, timeoutMs: Long = SETTLE_TIMEOUT_MS, state: () -> Boolean) {
+        val deadline = SystemClock.elapsedRealtime() + timeoutMs
+        while (SystemClock.elapsedRealtime() < deadline) {
+            if (state()) return
+            Thread.sleep(200)
+        }
+        fail("network state never settled: waited ${timeoutMs}ms for $what")
+    }
+
+    private fun assumeEmulator(what: String) {
+        Shell.assumeOnEmulator(
+            "NetworkControl runs only on emulators (ro.kernel.qemu != 1 here). $what " +
+                "on a real phone cuts its owner's calls and messages — and over wifi-adb " +
+                "it severs the test harness itself. Run this suite on a stock QA AVD.",
+        )
+    }
+}