diff --git a/examples/demo/app/build.gradle.kts b/examples/demo/app/build.gradle.kts
index 25aafbaacb..705637a319 100644
--- a/examples/demo/app/build.gradle.kts
+++ b/examples/demo/app/build.gradle.kts
@@ -134,6 +134,30 @@ android {
     }
 }
 
+// `-PRETRY_TEST_CA=<pem>` makes debug builds trust that CA, so scripts/retry can proxy SDK traffic
+// without installing a certificate on the device.
+demoOverride("RETRY_TEST_CA")?.let { caPath ->
+    val resDir = layout.buildDirectory.dir("generated/retryTestCa/res").get().asFile
+    file(caPath).copyTo(resDir.resolve("raw/retry_test_ca.pem"), overwrite = true)
+    resDir.resolve("xml/network_security_config.xml").apply {
+        parentFile.mkdirs()
+        writeText(
+            """
+            <?xml version="1.0" encoding="utf-8"?>
+            <network-security-config>
+                <debug-overrides>
+                    <trust-anchors>
+                        <certificates src="user" />
+                        <certificates src="@raw/retry_test_ca" />
+                    </trust-anchors>
+                </debug-overrides>
+            </network-security-config>
+            """.trimIndent(),
+        )
+    }
+    android.sourceSets.getByName("debug").res.srcDir(resDir)
+}
+
 dependencies {
     // Kotlin
     implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlinVersion")
diff --git a/examples/demo/app/src/main/AndroidManifest.xml b/examples/demo/app/src/main/AndroidManifest.xml
index c91d1c923a..cd06b9aa51 100644
--- a/examples/demo/app/src/main/AndroidManifest.xml
+++ b/examples/demo/app/src/main/AndroidManifest.xml
@@ -21,6 +21,7 @@
         android:allowBackup="true"
         android:icon="@mipmap/ic_onesignal_launcher"
         android:label="@string/app_name"
+        android:networkSecurityConfig="@xml/network_security_config"
         android:roundIcon="@mipmap/ic_onesignal_launcher"
         android:supportsRtl="true"
         android:theme="@style/AppTheme"
diff --git a/examples/demo/app/src/main/res/xml/network_security_config.xml b/examples/demo/app/src/main/res/xml/network_security_config.xml
new file mode 100644
index 0000000000..3e57ccf4c9
--- /dev/null
+++ b/examples/demo/app/src/main/res/xml/network_security_config.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Debug builds trust user-installed CAs so scripts/retry can proxy SDK traffic. -->
+<network-security-config>
+    <debug-overrides>
+        <trust-anchors>
+            <certificates src="user" />
+        </trust-anchors>
+    </debug-overrides>
+</network-security-config>
diff --git a/examples/demo/scripts/retry/.gitignore b/examples/demo/scripts/retry/.gitignore
new file mode 100644
index 0000000000..ad18e553d6
--- /dev/null
+++ b/examples/demo/scripts/retry/.gitignore
@@ -0,0 +1,2 @@
+.state/
+__pycache__/
diff --git a/examples/demo/scripts/retry/README.md b/examples/demo/scripts/retry/README.md
new file mode 100644
index 0000000000..3d0c57c175
--- /dev/null
+++ b/examples/demo/scripts/retry/README.md
@@ -0,0 +1,127 @@
+# Retry test harness
+
+Injects failures into the SDK's requests from the demo app, so OperationRepo retries and backoff can
+be watched and checked. A [mitmproxy](https://mitmproxy.org) addon fails only requests that carry
+the SDK's `SDK-Version` header. The demo's own REST calls and all other traffic pass through. Only
+`onesignal.com` traffic is decrypted.
+
+```bash
+brew install mitmproxy mobile-dev-inc/tap/maestro
+cd examples/demo/scripts/retry
+./retry-test.sh help
+```
+
+[Maestro](https://maestro.mobile.dev) drives the demo's UI (`tap`) through the flows in `flows/`.
+
+## Setup
+
+1. Start an emulator, or connect a device. With more than one, pick it with
+   `RETRY_TEST_SERIAL=<adb serial>`.
+2. `./retry-test.sh install` builds the demo against the local SDK source and installs it. The
+   debug build trusts the mitmproxy CA (`-PRETRY_TEST_CA`), so nothing has to be installed on the
+   device. If a demo signed with another key is already installed, `adb uninstall
+   com.onesignal.example` first.
+3. `./retry-test.sh start` starts mitmproxy on port 8899 and sets the device's global HTTP proxy.
+   An emulator reaches it at `10.0.2.2`, a physical device through `adb reverse`.
+4. `./retry-test.sh fresh` clears the demo's data so the SDK starts as a new install.
+5. In another terminal, `./retry-test.sh watch` follows each SDK request.
+6. When done, **`./retry-test.sh stop`** clears the device's proxy. Until then the whole device
+   goes through the proxy.
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `fail <route> <status> [--times N] [--retry-after S] [--add]` | Fail matching requests. Status `0` drops the connection, like being offline. Without `--times` it fails until `clear`. `--add` keeps earlier rules. Applies right away. |
+| `clear` / `rules` | Remove or show the rules |
+| `report [regex]` | Per operation: each attempt, the gap since the previous one, and the gap expected. Also lists any SDK request sent during a Retry-After |
+| `reset-log` | Forget recorded attempts, for example between scenarios |
+| `tap <action> [args]` | Use the demo: `add-tag <key> <value>`, `add-alias <label> <id>`, `add-email <email>`, `login <external id> [jwt]`, `logout`, `toggle-push`, `allow-notifications`. With `RETRY_TEST_IV_KEY` set, `login` signs a JWT when none is given |
+| `jwt <external id> [label=id] [email:addr] [sms:number]` | Print an Identity Verification JWT, valid for an hour, that claims those aliases and subscriptions |
+| `install` | Build the demo against the local SDK and install it |
+| `fresh` / `relaunch` | Clear the demo's data and relaunch / kill and relaunch |
+| `background` / `foreground` | Press Home / bring the demo back |
+| `network-flap [s]` | Turn the device's Wi-Fi and mobile data off for `s` seconds (default 10). Turns back on only what was on, even after Ctrl-C. Not over wireless adb |
+| `logs` | Stream the demo's OperationRepo and HttpClient logs |
+
+Routes: `create-user`, `fetch-user`, `update-user` (tags, properties, session data), `identity`
+(add alias and login's Identify User share it), `remove-alias`, `create-sub`, `update-sub`,
+`delete-sub`, `transfer-sub`, `identity-by-sub`, `custom-events`, `all`.
+
+## Reading `report`
+
+```
+POST apps/<app>/users body=b8398c6a
+    #     time status     body      gap         expected  note
+    1     0.0s   408* b8398c6a
+    2     3.9s   408* b8398c6a     3.9s        2.5-10.0s  backoff #1
+    3    11.2s   201  b8398c6a     7.3s        5.0-15.0s  backoff #2
+```
+
+Attempts are grouped per record (full path), and by body for routes without an id in the path
+(Create User, custom events).
+
+What the SDK should do:
+
+- **Backoff per request**: after the Nth retryable failure the request waits 5s × 2^(N-1), capped at
+  300s (`opRepoBaseFailRetryBackoff`, `opRepoMaxFailRetryBackoff`), times a jitter of 0.5 to 1.
+  Operations batched into one request share the wait. `HttpClient` does not re-send on its own.
+  Retryable is anything but 400, 401, 402, 403, 404, 409 and 410.
+- **Retry-After** is the minimum wait for that request, capped at 1h. `HttpClient` also holds
+  every SDK request, on any route, until it passes, and `report` lists any that weren't. Foreground
+  and network return do not cut it short. A 429 without Retry-After, or with an unparsable one,
+  waits 60s.
+- **Other records keep going**: while one request backs off, operations on other records are sent
+  (outside a Retry-After). Operations on the same record wait behind it, so order is kept.
+- **Foreground, and network return while in the foreground,** end the backoff, and the attempt goes
+  out right away without the queue's 5s batching wait. `report` flags those gaps as EARLY with a
+  note. A network return in the background does nothing; the timed retry or the next foreground
+  picks it up.
+- `report` allows 5s of slack past the window (`opRepoExecutionInterval`), since an enqueue near
+  the end of a backoff can add the batching wait.
+- Backoff state is in memory. After a relaunch, queued operations are sent right away.
+
+## Scenarios
+
+Run `reset-log` before each one. Unless noted, the request should succeed after the last failure,
+and nothing should need a relaunch.
+
+1. **Backoff**: `fail create-user 408 --times 3`, then `fresh`. Gaps within 2.5-5s, 5-10s and
+   10-20s (plus slack), then 201.
+2. **Other records are not blocked**: `fail update-user 408`, `tap add-tag k v`, then after the
+   first failure `tap toggle-push`. The subscription PATCH goes out while the tag keeps retrying.
+3. **Retry-After**: `fail update-user 429 --times 1 --retry-after 40`, then `tap add-tag k v`.
+   One retry after about 40s. `background` then `foreground` during the wait does not cut it short,
+   and a `tap toggle-push` during the wait is not sent until it ends.
+4. **Foreground ends the backoff**: `fail update-user 408`, `tap add-tag k v`, wait for four
+   failures (a 20-40s wait), then `background` and `foreground`. An attempt goes out right after
+   foreground.
+5. **Network return**: as in 4, but `network-flap 5` with the demo in the foreground. An attempt
+   goes out right after the network is back. With the demo in the background, the flap changes
+   nothing.
+6. **Order is kept**: `fail create-user 408 --times 2`, then `fresh` and `tap login <id>` during
+   the failures. Identify User (PATCH `.../identity`) is not sent until Create User succeeds.
+7. **Fetch User**: `fail fetch-user 408 --times 2`, then `tap login <id>`. Fetch User retries in
+   the same run.
+8. **Kill during backoff**: `fail update-user 408`, `tap add-tag k v`, wait for two failures,
+   `clear`, then `relaunch`. The cached request is sent right after launch.
+9. **Not retried**: `fail update-user 400 --times 1`, then `tap add-tag k v`. One attempt.
+10. **Offline**: `fail all 0`, then `tap add-tag k v`, `tap add-alias l i` and `tap add-email e`.
+    Wait for a few failures, then `clear`. Everything goes out on its next attempt.
+11. **Login/logout while failing**: `fail all 408`, `tap login b`, `tap logout`, `tap login c`,
+    then `clear`. Requests for each user go out in order.
+12. **Identity Verification**: needs an app with Identity Verification on and its ES256 private
+    key. Ask the SDK team for both and keep the key outside the repo. Set
+    `RETRY_TEST_IV_APP_ID=<app id>` and `RETRY_TEST_IV_KEY=<path to the key>`, then `install` again.
+    `tap login <id>` now signs a JWT. No anonymous Create User is sent, so in 1 and 6 the Create
+    User comes from the login, and 6 checks that a `tap add-tag` during the failures waits for it.
+    Repeat 1, 2, 6 and 10. In 10, log in with a JWT that claims the alias and email:
+    `tap login <id> "$(./retry-test.sh jwt <id> l=i email:e)"`.
+
+## Troubleshooting
+
+- `tap` types nothing: newer emulator images show a stylus handwriting prompt on text fields.
+  `install` turns it off (`settings put secure stylus_handwriting_enabled 0`).
+- Every SDK request fails with status 0 right after `start`: the installed demo was not built by
+  `install`, so it does not trust the mitmproxy CA.
+- The emulator's clock can drift from the Mac's, so compare logcat times with `report` carefully.
diff --git a/examples/demo/scripts/retry/fault_proxy.py b/examples/demo/scripts/retry/fault_proxy.py
new file mode 100644
index 0000000000..a1295cddc1
--- /dev/null
+++ b/examples/demo/scripts/retry/fault_proxy.py
@@ -0,0 +1,115 @@
+"""
+mitmproxy addon that injects failures into OneSignal SDK requests so operation retries can be
+observed in the demo app. Driven by `retry-test.sh`; see README.md.
+
+Only requests carrying the SDK's `SDK-Version` header are touched, so the demo's own REST calls
+pass through. Every SDK request is appended to attempts.jsonl for `retry-test.sh report`.
+
+Rules are re-read whenever rules.json changes. Each rule:
+  {"id": "<unique>", "route": "update-user", "method": "PATCH", "path": "<regex>", "status": 503,
+   "retry_after": "30", "times": 3}
+`status` 0 drops the connection (the SDK sees status 0, like being offline). `times` is how many
+matching requests fail before the rule passes them through; null fails forever. A rule keeps its
+remaining count across reloads, keyed by `id`.
+"""
+
+import hashlib
+import json
+import os
+import re
+import time
+
+from mitmproxy import http
+
+STATE_DIR = os.environ["RETRY_TEST_STATE_DIR"]
+RULES_PATH = os.path.join(STATE_DIR, "rules.json")
+ATTEMPTS_PATH = os.path.join(STATE_DIR, "attempts.jsonl")
+
+API_PATH_PREFIX = re.compile(r"^/(api/v1/)?")
+
+
+class FaultProxy:
+    def __init__(self):
+        self.rules_mtime = None
+        self.rules = []
+        self.remaining = {}
+
+    def load_rules(self):
+        try:
+            mtime = os.stat(RULES_PATH).st_mtime_ns
+        except FileNotFoundError:
+            mtime = None
+        if mtime == self.rules_mtime:
+            return
+        self.rules_mtime = mtime
+        self.rules = []
+        if mtime is not None:
+            with open(RULES_PATH) as f:
+                self.rules = json.load(f)
+        self.remaining = {rule["id"]: self.remaining.get(rule["id"], rule.get("times")) for rule in self.rules}
+        print(f"[fault] rules: {json.dumps(self.rules) if self.rules else 'none, passing everything'}")
+
+    def match(self, flow):
+        path = API_PATH_PREFIX.sub("", flow.request.path.split("?")[0])
+        for rule in self.rules:
+            if rule.get("method") and rule["method"] != flow.request.method:
+                continue
+            if not re.search(rule["path"], path):
+                continue
+            remaining = self.remaining[rule["id"]]
+            if remaining is not None:
+                if remaining <= 0:
+                    continue
+                self.remaining[rule["id"]] = remaining - 1
+            return rule
+        return None
+
+    def request(self, flow: http.HTTPFlow):
+        if "onesignal.com" not in flow.request.pretty_host or "SDK-Version" not in flow.request.headers:
+            return
+        # Timed at the request, so gaps are between sends rather than between responses.
+        flow.metadata["fault_sent_at"] = time.time()
+        self.load_rules()
+        rule = self.match(flow)
+        flow.metadata["fault_rule"] = rule
+        if rule is None:
+            return
+        if rule["status"] == 0:
+            self.record(flow, 0, rule)
+            flow.kill()
+            return
+        headers = {"Content-Type": "application/json"}
+        if rule.get("retry_after") is not None:
+            headers["Retry-After"] = str(rule["retry_after"])
+        body = json.dumps({"errors": [{"title": f"Injected by fault_proxy ({rule['route']})"}]})
+        flow.response = http.Response.make(rule["status"], body, headers)
+
+    def response(self, flow: http.HTTPFlow):
+        if "fault_rule" not in flow.metadata:
+            return
+        self.record(flow, flow.response.status_code, flow.metadata["fault_rule"])
+
+    def error(self, flow: http.HTTPFlow):
+        if "fault_rule" in flow.metadata and flow.metadata["fault_rule"] is None:
+            self.record(flow, 0, None)
+
+    def record(self, flow, status, rule):
+        path = API_PATH_PREFIX.sub("", flow.request.path.split("?")[0])
+        retry_after = flow.response.headers.get("Retry-After") if flow.response else None
+        entry = {
+            "t": flow.metadata["fault_sent_at"],
+            "method": flow.request.method,
+            "path": path,
+            "status": status,
+            "injected": rule is not None,
+            "retry_after": retry_after,
+            "body": hashlib.sha1(flow.request.raw_content or b"").hexdigest()[:8],
+        }
+        with open(ATTEMPTS_PATH, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+        tag = "INJECTED" if rule else "passed"
+        stamp = time.strftime("%H:%M:%S", time.localtime(entry["t"]))
+        print(f"[fault] {stamp} {status:>3} {tag:<8} {flow.request.method:<6} {path} body={entry['body']}", flush=True)
+
+
+addons = [FaultProxy()]
diff --git a/examples/demo/scripts/retry/flows/_scroll-to.yaml b/examples/demo/scripts/retry/flows/_scroll-to.yaml
new file mode 100644
index 0000000000..628a35b093
--- /dev/null
+++ b/examples/demo/scripts/retry/flows/_scroll-to.yaml
@@ -0,0 +1,13 @@
+appId: com.onesignal.example
+---
+- scrollUntilVisible:
+    element:
+      id: app_section
+    direction: UP
+    visibilityPercentage: 10
+    timeout: 60000
+- scrollUntilVisible:
+    element:
+      id: ${TARGET}
+    centerElement: true
+    timeout: 60000
diff --git a/examples/demo/scripts/retry/flows/add-alias.yaml b/examples/demo/scripts/retry/flows/add-alias.yaml
new file mode 100644
index 0000000000..ad4775caa4
--- /dev/null
+++ b/examples/demo/scripts/retry/flows/add-alias.yaml
@@ -0,0 +1,16 @@
+appId: com.onesignal.example
+---
+- runFlow:
+    file: _scroll-to.yaml
+    env:
+      TARGET: add_alias_button
+- tapOn:
+    id: add_alias_button
+- tapOn:
+    id: alias_label_input
+- inputText: ${KEY}
+- tapOn:
+    id: alias_id_input
+- inputText: ${VALUE}
+- tapOn:
+    id: singlepair_confirm_button
diff --git a/examples/demo/scripts/retry/flows/add-email.yaml b/examples/demo/scripts/retry/flows/add-email.yaml
new file mode 100644
index 0000000000..e2fcf1037e
--- /dev/null
+++ b/examples/demo/scripts/retry/flows/add-email.yaml
@@ -0,0 +1,13 @@
+appId: com.onesignal.example
+---
+- runFlow:
+    file: _scroll-to.yaml
+    env:
+      TARGET: add_email_button
+- tapOn:
+    id: add_email_button
+- tapOn:
+    id: email_input
+- inputText: ${VALUE}
+- tapOn:
+    id: singleinput_confirm_button
diff --git a/examples/demo/scripts/retry/flows/add-tag.yaml b/examples/demo/scripts/retry/flows/add-tag.yaml
new file mode 100644
index 0000000000..2e7d035398
--- /dev/null
+++ b/examples/demo/scripts/retry/flows/add-tag.yaml
@@ -0,0 +1,16 @@
+appId: com.onesignal.example
+---
+- runFlow:
+    file: _scroll-to.yaml
+    env:
+      TARGET: add_tag_button
+- tapOn:
+    id: add_tag_button
+- tapOn:
+    id: tag_key_input
+- inputText: ${KEY}
+- tapOn:
+    id: tag_value_input
+- inputText: ${VALUE}
+- tapOn:
+    id: singlepair_confirm_button
diff --git a/examples/demo/scripts/retry/flows/allow-notifications.yaml b/examples/demo/scripts/retry/flows/allow-notifications.yaml
new file mode 100644
index 0000000000..36d98cc51c
--- /dev/null
+++ b/examples/demo/scripts/retry/flows/allow-notifications.yaml
@@ -0,0 +1,6 @@
+appId: com.onesignal.example
+---
+- launchApp
+- tapOn:
+    text: Allow
+    optional: true
diff --git a/examples/demo/scripts/retry/flows/login.yaml b/examples/demo/scripts/retry/flows/login.yaml
new file mode 100644
index 0000000000..d44aa865f9
--- /dev/null
+++ b/examples/demo/scripts/retry/flows/login.yaml
@@ -0,0 +1,20 @@
+appId: com.onesignal.example
+---
+- runFlow:
+    file: _scroll-to.yaml
+    env:
+      TARGET: login_user_button
+- tapOn:
+    id: login_user_button
+- tapOn:
+    id: login_user_id_input
+- inputText: ${VALUE}
+- runFlow:
+    when:
+      true: ${JWT != ''}
+    commands:
+      - tapOn:
+          id: login_user_jwt_input
+      - inputText: ${JWT}
+- tapOn:
+    id: singleinput_confirm_button
diff --git a/examples/demo/scripts/retry/flows/logout.yaml b/examples/demo/scripts/retry/flows/logout.yaml
new file mode 100644
index 0000000000..59e6d6e7a8
--- /dev/null
+++ b/examples/demo/scripts/retry/flows/logout.yaml
@@ -0,0 +1,8 @@
+appId: com.onesignal.example
+---
+- runFlow:
+    file: _scroll-to.yaml
+    env:
+      TARGET: logout_user_button
+- tapOn:
+    id: logout_user_button
diff --git a/examples/demo/scripts/retry/flows/toggle-push.yaml b/examples/demo/scripts/retry/flows/toggle-push.yaml
new file mode 100644
index 0000000000..42e3996806
--- /dev/null
+++ b/examples/demo/scripts/retry/flows/toggle-push.yaml
@@ -0,0 +1,8 @@
+appId: com.onesignal.example
+---
+- runFlow:
+    file: _scroll-to.yaml
+    env:
+      TARGET: push_enabled_toggle
+- tapOn:
+    id: push_enabled_toggle
diff --git a/examples/demo/scripts/retry/make_jwt.py b/examples/demo/scripts/retry/make_jwt.py
new file mode 100644
index 0000000000..2ec0e9a4e5
--- /dev/null
+++ b/examples/demo/scripts/retry/make_jwt.py
@@ -0,0 +1,61 @@
+"""
+Prints an Identity Verification JWT, signed ES256 with openssl so no extra packages are needed.
+Usage: make_jwt.py <private key pem> <app id> <external id> [label=id] [email:addr] [sms:number]
+Aliases, emails and SMS numbers the SDK adds must be claimed in the token.
+"""
+
+import base64
+import json
+import subprocess
+import sys
+import time
+
+# Identity Verification only accepts tokens whose exp is within an hour of now.
+LIFETIME = 3600
+
+
+def b64(data):
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def der_to_raw(der):
+    """openssl emits an ASN.1 DER signature, JWS wants r || s."""
+    i = 3 if der[1] & 0x80 else 2
+    parts = []
+    for _ in range(2):
+        length = der[i + 1]
+        parts.append(int.from_bytes(der[i + 2:i + 2 + length], "big").to_bytes(32, "big"))
+        i += 2 + length
+    return b"".join(parts)
+
+
+def main():
+    if len(sys.argv) < 4:
+        sys.exit(__doc__.strip())
+    key, app_id, external_id, *extra = sys.argv[1:]
+    identity = {"external_id": external_id}
+    subscriptions = []
+    for arg in extra:
+        kind, sep, value = arg.partition(":")
+        if sep and kind in ("email", "sms"):
+            subscriptions.append({"type": "Email" if kind == "email" else "SMS", "token": value})
+        elif "=" in arg:
+            label, value = arg.split("=", 1)
+            identity[label] = value
+        else:
+            sys.exit(f"unrecognized claim: {arg}")
+    claims = {"iss": app_id, "exp": int(time.time()) + LIFETIME, "identity": identity}
+    if subscriptions:
+        claims["subscriptions"] = subscriptions
+
+    header = b64(json.dumps({"alg": "ES256", "typ": "JWT"}).encode())
+    signing_input = f"{header}.{b64(json.dumps(claims).encode())}"
+    der = subprocess.run(
+        ["openssl", "dgst", "-sha256", "-sign", key],
+        input=signing_input.encode(), capture_output=True, check=True,
+    ).stdout
+    print(f"{signing_input}.{b64(der_to_raw(der))}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/demo/scripts/retry/report.py b/examples/demo/scripts/retry/report.py
new file mode 100644
index 0000000000..bbbfffaf1c
--- /dev/null
+++ b/examples/demo/scripts/retry/report.py
@@ -0,0 +1,157 @@
+"""
+Prints each SDK operation's attempts from attempts.jsonl with the gap since the previous attempt,
+and the gap the SDK should have waited. Usage: report.py <attempts.jsonl> [route regex]
+
+Expected gaps model OperationRepo's backoff:
+  - After the Nth retryable failure a request waits 5s * 2^(N-1), capped at 300s, times a jitter
+    of 0.5 to 1. HttpClient does not re-send on its own.
+  - Retry-After is the minimum wait, capped at 1h. An unparsable value, or a 429 without one,
+    counts as 60s. HttpClient also holds every SDK request until it passes, which is checked
+    separately at the end.
+  - A timed retry skips the queue's batching wait, but an enqueue near the end of a backoff can add
+    up to opRepoExecutionInterval (5s), so that much slack is allowed.
+A foreground, or a network return while in the foreground, ends the backoff early (but not
+Retry-After), so short gaps right after those are fine.
+"""
+
+import json
+import math
+import re
+import sys
+from collections import OrderedDict
+
+BASE_BACKOFF = 5
+MAX_BACKOFF = 300
+MIN_JITTER = 0.5
+MAX_RETRY_AFTER = 3600
+RETRY_AFTER_PARSE_FAIL = 60
+QUEUE_SLACK = 5.0
+CLOCK_SLACK = 1.0
+NOT_RETRIED = (400, 401, 402, 403, 404, 409, 410)
+EXECUTOR_ROUTE = re.compile(r"^apps/[^/]+/(users(/by/.*)?|subscriptions/.+|custom_events)$")
+IGNORED_ROUTE = re.compile(r"/iams$")
+# Routes without a record id in the path. Their attempts are told apart by body instead.
+NO_ID_ROUTE = re.compile(r"(/users|/subscriptions|/custom_events)$")
+# Remote logging is sent by the shared KMP logger, not HttpClient, so the gate doesn't apply.
+NOT_GATED_ROUTE = re.compile(r"^sdk/log$")
+
+
+def operation_key(entry):
+    key = f"{entry['method']} {entry['path']}"
+    if entry["method"] == "POST" and NO_ID_ROUTE.search(entry["path"]):
+        key += f" body={entry.get('body', '')}"
+    return key
+
+
+def retry_after_seconds(status, header):
+    """Mirrors HttpClient.retryAfterFromResponse."""
+    if header is None:
+        return RETRY_AFTER_PARSE_FAIL if status == 429 else None
+    try:
+        value = float(str(header).strip())
+    except ValueError:
+        return RETRY_AFTER_PARSE_FAIL
+    if not math.isfinite(value) or value < 0:
+        return RETRY_AFTER_PARSE_FAIL
+    return math.ceil(min(value, MAX_RETRY_AFTER))
+
+
+def backoff_window(failures, retry_after):
+    backoff = min(BASE_BACKOFF * 2 ** (failures - 1), MAX_BACKOFF)
+    low, high = backoff * MIN_JITTER, backoff
+    if retry_after is not None:
+        low, high = max(low, retry_after), max(high, retry_after)
+    return low, high + QUEUE_SLACK
+
+
+def print_operation(key, entries):
+    print(f"\n{key}")
+    print(f"  {'#':>3} {'time':>8} {'status':>6} {'body':>8} {'gap':>8} {'expected':>16}  note")
+    failures = 0
+    expected = None
+    start = entries[0]["t"]
+    for i, entry in enumerate(entries):
+        gap = entry["t"] - entries[i - 1]["t"] if i else None
+        note = ""
+        if expected and gap is not None:
+            low, high, kind = expected
+            if gap < low - CLOCK_SLACK:
+                note = f"EARLY ({kind})"
+                if not kind.endswith("Retry-After"):
+                    note += "; fine if right after a foreground or network return"
+            elif gap > high + CLOCK_SLACK:
+                note = f"LATE ({kind})"
+            else:
+                note = kind
+        elif gap is not None:
+            note = "new attempt"
+        expected_text = f"{expected[0]:.1f}-{expected[1]:.1f}s" if expected else ""
+        gap_text = f"{gap:.1f}s" if gap is not None else ""
+        mark = "*" if entry["injected"] else " "
+        print(f"  {i + 1:>3} {entry['t'] - start:>7.1f}s {entry['status']:>5}{mark} {entry.get('body', ''):>8} {gap_text:>8} {expected_text:>16}  {note}")
+
+        status = entry["status"]
+        if 200 <= status < 300 or status in NOT_RETRIED:
+            failures = 0
+            expected = None
+        else:
+            failures += 1
+            retry_after = retry_after_seconds(status, entry.get("retry_after"))
+            low, high = backoff_window(failures, retry_after)
+            expected = (low, high, f"backoff #{failures}" + (", Retry-After" if retry_after is not None else ""))
+
+
+def print_gate_violations(entries):
+    """HttpClient holds every SDK request, on any route, until a Retry-After passes."""
+    windows = []
+    for entry in entries:
+        retry_after = retry_after_seconds(entry["status"], entry.get("retry_after"))
+        if retry_after:
+            windows.append((entry["t"], entry["t"] + retry_after))
+    violations = [
+        entry
+        for entry in entries
+        if not NOT_GATED_ROUTE.search(entry["path"])
+        and any(start < entry["t"] < end - CLOCK_SLACK for start, end in windows)
+    ]
+    if not windows:
+        return
+    if not violations:
+        print("\nNo SDK request was sent during a Retry-After.")
+        return
+    print("\nSENT DURING A RETRY-AFTER (HttpClient should have held these):")
+    for entry in violations:
+        print(f"  {entry['method']} {entry['path']} status={entry['status']} body={entry.get('body', '')}")
+
+
+def main():
+    path = sys.argv[1]
+    route_filter = re.compile(sys.argv[2]) if len(sys.argv) > 2 else None
+    entries = []
+    with open(path) as f:
+        for line in f:
+            if line.strip():
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    # The proxy may be mid-write on the last line.
+                    continue
+
+    if not entries:
+        print("No SDK requests recorded yet.")
+        return
+
+    operations = OrderedDict()
+    for entry in entries:
+        if EXECUTOR_ROUTE.search(entry["path"]) and not IGNORED_ROUTE.search(entry["path"]):
+            operations.setdefault(operation_key(entry), []).append(entry)
+
+    for key, op_entries in operations.items():
+        if not route_filter or route_filter.search(key):
+            print_operation(key, op_entries)
+    print_gate_violations(entries)
+    print("\n* = failure injected by the proxy")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/demo/scripts/retry/retry-test.sh b/examples/demo/scripts/retry/retry-test.sh
new file mode 100755
index 0000000000..40a67501a2
--- /dev/null
+++ b/examples/demo/scripts/retry/retry-test.sh
@@ -0,0 +1,321 @@
+#!/usr/bin/env bash
+# Fault-injection harness for manually testing SDK operation retries in the demo app.
+# Run `./retry-test.sh help` or see README.md.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SDK_DIR="$(cd "$SCRIPT_DIR/../../../../OneSignalSDK" && pwd)"
+STATE_DIR="${RETRY_TEST_STATE_DIR:-$SCRIPT_DIR/.state}"
+RULES="$STATE_DIR/rules.json"
+ATTEMPTS="$STATE_DIR/attempts.jsonl"
+PROXY_LOG="$STATE_DIR/proxy.log"
+PID_FILE="$STATE_DIR/proxy.pid"
+PORT="${RETRY_TEST_PORT:-8899}"
+PACKAGE="${RETRY_TEST_PACKAGE:-com.onesignal.example}"
+CA_CERT="$HOME/.mitmproxy/mitmproxy-ca-cert.pem"
+IV_APP_ID="${RETRY_TEST_IV_APP_ID:-}"
+IV_KEY="${RETRY_TEST_IV_KEY:-}"
+
+export RETRY_TEST_STATE_DIR="$STATE_DIR"
+mkdir -p "$STATE_DIR"
+
+die() { echo "error: $*" >&2; exit 1; }
+
+# Sets SERIAL from RETRY_TEST_SERIAL / ANDROID_SERIAL, or the only connected device.
+resolve_device() {
+  command -v adb >/dev/null || die "adb not found. Add \$ANDROID_HOME/platform-tools to PATH."
+  SERIAL="${RETRY_TEST_SERIAL:-${ANDROID_SERIAL:-}}"
+  if [[ -z "$SERIAL" ]]; then
+    local devices
+    devices="$(adb devices | awk 'NR > 1 && $2 == "device" {print $1}')"
+    [[ -n "$devices" ]] || die "no device connected. Start an emulator or plug in a device."
+    [[ "$(wc -l <<< "$devices" | tr -d ' ')" == "1" ]] \
+      || die "several devices connected ($(echo $devices)). Pick one with RETRY_TEST_SERIAL=<serial>."
+    SERIAL="$devices"
+  fi
+}
+
+dev() { adb -s "$SERIAL" "$@"; }
+
+is_emulator() { [[ "$SERIAL" == emulator-* ]]; }
+
+launch_app() { dev shell monkey -p "$PACKAGE" -c android.intent.category.LAUNCHER 1 >/dev/null 2>&1; }
+
+route_rule() {
+  # Prints "<method> <path regex>" for a route name. Paths are relative to https://api.onesignal.com/.
+  case "$1" in
+    create-user)     echo "POST ^apps/[^/]+/users$" ;;
+    fetch-user)      echo "GET ^apps/[^/]+/users/by/[^/]+/[^/]+$" ;;
+    update-user)     echo "PATCH ^apps/[^/]+/users/by/[^/]+/[^/]+$" ;;
+    identity)        echo "PATCH /identity$" ;;
+    remove-alias)    echo "DELETE /identity/[^/]+$" ;;
+    create-sub)      echo "POST /subscriptions$" ;;
+    update-sub)      echo "PATCH ^apps/[^/]+/subscriptions/[^/]+$" ;;
+    delete-sub)      echo "DELETE ^apps/[^/]+/subscriptions/[^/]+$" ;;
+    transfer-sub)    echo "PATCH /subscriptions/[^/]+/owner$" ;;
+    identity-by-sub) echo "GET /user/identity$" ;;
+    custom-events)   echo "POST /custom_events$" ;;
+    all)             echo "- ." ;;
+    *) die "unknown route '$1'. Routes: create-user fetch-user update-user identity remove-alias create-sub update-sub delete-sub transfer-sub identity-by-sub custom-events all" ;;
+  esac
+}
+
+proxy_running() { [[ -f "$PID_FILE" ]] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; }
+
+set_device_proxy() {
+  # An emulator reaches the Mac at 10.0.2.2 through its emulated network, so turning the
+  # emulator's network off really takes it offline. A physical device goes through `adb reverse`.
+  local host="10.0.2.2"
+  if ! is_emulator; then
+    dev reverse "tcp:$PORT" "tcp:$PORT" >/dev/null
+    host="127.0.0.1"
+  fi
+  dev shell settings put global http_proxy "$host:$PORT"
+  echo "Pointed $SERIAL's global HTTP proxy at $host:$PORT (cleared by 'stop')."
+}
+
+clear_device_proxy() {
+  dev shell settings put global http_proxy :0
+  dev reverse --remove "tcp:$PORT" >/dev/null 2>&1 || true
+  echo "Cleared $SERIAL's HTTP proxy."
+}
+
+ensure_ca() {
+  [[ -f "$CA_CERT" ]] && return
+  command -v mitmdump >/dev/null || die "mitmdump not found. Install with: brew install mitmproxy"
+  # mitmproxy writes its CA on first run.
+  mitmdump --listen-port 0 >/dev/null 2>&1 &
+  local pid=$!
+  for _ in $(seq 1 50); do [[ -f "$CA_CERT" ]] && break; sleep 0.1; done
+  kill "$pid" 2>/dev/null || true
+  [[ -f "$CA_CERT" ]] || die "mitmproxy CA not generated at $CA_CERT"
+}
+
+cmd_start() {
+  command -v mitmdump >/dev/null || die "mitmdump not found. Install with: brew install mitmproxy"
+  proxy_running && die "proxy already running (pid $(cat "$PID_FILE")). Run '$0 stop' first."
+  resolve_device
+  : > "$ATTEMPTS"
+  [[ -f "$RULES" ]] || echo "[]" > "$RULES"
+  # Only onesignal.com is decrypted; everything else is tunnelled untouched.
+  # Loopback is enough: an emulator's 10.0.2.2 and `adb reverse` both land on it.
+  mitmdump --listen-host 127.0.0.1 --listen-port "$PORT" \
+    --allow-hosts '^(.+\.)?onesignal\.com(:443)?$' \
+    --set connection_strategy=lazy \
+    --set termlog_verbosity=warn \
+    -s "$SCRIPT_DIR/fault_proxy.py" > "$PROXY_LOG" 2>&1 &
+  echo $! > "$PID_FILE"
+  sleep 1
+  proxy_running || { cat "$PROXY_LOG"; die "mitmdump exited"; }
+  echo "mitmdump running (pid $(cat "$PID_FILE")), log: $PROXY_LOG"
+  set_device_proxy
+  echo "Relaunch the demo app so it picks up the proxy: $0 relaunch"
+}
+
+cmd_stop() {
+  if proxy_running; then
+    kill "$(cat "$PID_FILE")" && echo "Stopped mitmdump."
+  fi
+  rm -f "$PID_FILE"
+  resolve_device
+  clear_device_proxy
+}
+
+write_rules() {
+  # write_rules <json array>; written atomically so the addon never reads a partial file.
+  echo "$1" > "$RULES.tmp" && mv "$RULES.tmp" "$RULES"
+}
+
+cmd_fail() {
+  local route="${1:-}" status="${2:-}"
+  [[ -n "$route" && -n "$status" ]] || die "usage: $0 fail <route> <status|0> [--times N] [--retry-after S] [--add]"
+  shift 2
+  local times="null" retry_after="null" add=false
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --times) times="$2"; shift 2 ;;
+      --retry-after) retry_after="\"$2\""; shift 2 ;;
+      --add) add=true; shift ;;
+      *) die "unknown option $1" ;;
+    esac
+  done
+  [[ "$status" == "0" && "$retry_after" != "null" ]] && die "--retry-after needs an HTTP status; a dropped connection has no headers"
+  local method path
+  # A die inside $(...) only exits the subshell, so check it here or a typo becomes a match-all rule.
+  local spec
+  spec="$(route_rule "$route")" || exit 1
+  read -r method path <<< "$spec"
+  [[ "$method" == "-" ]] && method=""
+  python3 - "$RULES" "$add" "$route" "$method" "$path" "$status" "$times" "$retry_after" > "$RULES.tmp" <<'PY'
+import json, sys, uuid
+rules_path, add, route, method, path, status, times, retry_after = sys.argv[1:]
+rules = json.load(open(rules_path)) if add == "true" else []
+rules.append({"id": uuid.uuid4().hex[:8], "route": route, "method": method or None, "path": path,
+              "status": int(status), "times": json.loads(times), "retry_after": json.loads(retry_after)})
+print(json.dumps(rules))
+PY
+  mv "$RULES.tmp" "$RULES"
+  echo "Rules now: $(cat "$RULES")"
+}
+
+cmd_clear() {
+  write_rules "[]"
+  echo "Cleared all rules; requests pass through."
+}
+
+cmd_reset_log() { : > "$ATTEMPTS"; echo "Cleared recorded attempts."; }
+
+restore_radios() {
+  # wifi_on is 2 when Wi-Fi is on in airplane mode, so anything but 0 counts as on.
+  local ok=true
+  if [[ "$WIFI_WAS_ON" != "0" ]]; then dev shell svc wifi enable || ok=false; fi
+  if [[ "$DATA_WAS_ON" != "0" ]]; then dev shell svc data enable || ok=false; fi
+  if $ok; then echo "Network restored."; else echo "error: could not turn the network back on; check $SERIAL" >&2; fi
+}
+
+cmd_network_flap() {
+  # Fires the SDK's online callback when the network comes back. On an emulator this also takes
+  # the proxy route offline; through `adb reverse` a physical device can still reach the proxy.
+  local seconds="${1:-10}"
+  resolve_device
+  [[ "$SERIAL" == *:* || "$SERIAL" == *._adb-tls-connect._tcp* ]] \
+    && die "$SERIAL is wireless adb, which drops with Wi-Fi. Use USB or an emulator."
+  WIFI_WAS_ON="$(dev shell settings get global wifi_on | tr -d '\r')"
+  DATA_WAS_ON="$(dev shell settings get global mobile_data | tr -d '\r')"
+  # Only turns back on what was on, even after Ctrl-C or a failed `svc`.
+  trap restore_radios EXIT
+  trap 'exit 130' INT TERM
+  echo "Wi-Fi and mobile data off on $SERIAL for ${seconds}s..."
+  dev shell svc wifi disable
+  dev shell svc data disable
+  # Waited on in the background so a SIGTERM runs the trap right away.
+  sleep "$seconds" & wait $!
+}
+
+cmd_fresh() {
+  # `pm clear` makes the SDK start as a new install (Create User and so on). Granting the
+  # notification permission again keeps the prompt from covering the demo.
+  resolve_device
+  dev shell pm path "$PACKAGE" >/dev/null 2>&1 || die "demo app not installed on $SERIAL. Run '$0 install'."
+  dev shell pm clear "$PACKAGE" >/dev/null
+  dev shell pm grant "$PACKAGE" android.permission.POST_NOTIFICATIONS 2>/dev/null || true
+  echo "Cleared demo app data."
+  launch_app
+}
+
+cmd_install() {
+  # Builds the demo against the local SDK source, trusting the mitmproxy CA. SDK_VERSION is
+  # required by OneSignalSDK/ but only labels the build.
+  resolve_device
+  ensure_ca
+  local app_id=()
+  [[ -n "$IV_APP_ID" ]] && app_id=(-PONESIGNAL_APP_ID="$IV_APP_ID")
+  (cd "$SDK_DIR" && ANDROID_SERIAL="$SERIAL" ./gradlew -q :app:installGmsDebug \
+    -PSDK_VERSION="${SDK_VERSION:-0.0.0-retry-test}" -PRETRY_TEST_CA="$CA_CERT" ${app_id[@]+"${app_id[@]}"})
+  dev shell pm grant "$PACKAGE" android.permission.POST_NOTIFICATIONS 2>/dev/null || true
+  # The stylus handwriting prompt on newer emulators swallows Maestro's text input.
+  dev shell settings put secure stylus_handwriting_enabled 0
+  echo "Installed the demo app on $SERIAL. Next: $0 start, then $0 fresh"
+}
+
+cmd_tap() {
+  # Drives the demo's UI through Maestro flows in flows/, using the demo's test tags.
+  command -v maestro >/dev/null || die "maestro not found. Install with: brew install mobile-dev-inc/tap/maestro"
+  local action="${1:-}" env=()
+  case "$action" in
+    add-tag|add-alias) [[ $# -eq 3 ]] || die "usage: $0 tap $action <key> <value>"; env=(-e "KEY=$2" -e "VALUE=$3") ;;
+    add-email) [[ $# -eq 2 ]] || die "usage: $0 tap $action <value>"; env=(-e "VALUE=$2") ;;
+    login)
+      [[ $# -eq 2 || $# -eq 3 ]] || die "usage: $0 tap login <external id> [jwt]"
+      local jwt="${3:-}"
+      [[ -z "$jwt" && -n "$IV_KEY" ]] && { jwt="$(cmd_jwt "$2")" || exit 1; }
+      env=(-e "VALUE=$2" -e "JWT=$jwt") ;;
+    logout|toggle-push|allow-notifications) ;;
+    *) die "usage: $0 tap <add-tag|add-alias|add-email|login|logout|toggle-push|allow-notifications> [args]" ;;
+  esac
+  resolve_device
+  # The grep only trims output; with pipefail a failed flow still fails `tap`.
+  local status=0
+  MAESTRO_CLI_NO_ANALYTICS=1 MAESTRO_CLI_ANALYSIS_NOTIFICATION_DISABLED=true \
+    maestro --device "$SERIAL" test ${env[@]+"${env[@]}"} "$SCRIPT_DIR/flows/$action.yaml" \
+    | { grep -E '^ *(>|[A-Z].*(COMPLETED|FAILED|WARNED))' || true; } || status=$?
+  [[ "$status" == "0" ]] || die "maestro flow '$action' failed (exit $status)"
+}
+
+cmd_jwt() {
+  [[ -n "$IV_APP_ID" && -n "$IV_KEY" ]] || die "set RETRY_TEST_IV_APP_ID and RETRY_TEST_IV_KEY (path to the app's private key)"
+  [[ -r "$IV_KEY" ]] || die "can't read $IV_KEY"
+  python3 "$SCRIPT_DIR/make_jwt.py" "$IV_KEY" "$IV_APP_ID" "$@"
+}
+
+cmd_logs() {
+  resolve_device
+  local pid
+  pid="$(dev shell pidof "$PACKAGE" | tr -d '\r')"
+  [[ -n "$pid" ]] || die "demo app is not running"
+  dev logcat -v time --pid="$pid" | grep --line-buffered -iE 'OperationRepo|HttpClient|retry|retry-after'
+}
+
+usage() {
+  cat <<EOF
+Usage: $0 <command>
+
+Proxy
+  start                     Start mitmproxy and point the device's HTTP proxy at it
+  stop                      Stop mitmproxy and clear the device's proxy
+
+Faults (take effect immediately, no relaunch needed)
+  fail <route> <status> [--times N] [--retry-after S] [--add]
+                            Fail matching SDK requests. Status 0 drops the connection.
+                            --times N: fail N times, then pass. Default: until cleared.
+                            --add: keep existing rules instead of replacing them.
+  clear                     Remove all rules
+  rules                     Show current rules
+
+Observe
+  watch                     Follow every SDK request as it passes the proxy
+  report [route regex]      Gaps between attempts per route vs. the expected backoff
+  reset-log                 Forget recorded attempts
+  logs                      Stream the demo app's OperationRepo / HttpClient logs
+
+App / environment
+  install                   Build the demo against the local SDK, trusting the mitmproxy CA, and install it
+  tap <action> [args]       Drive the demo's UI with Maestro:
+                              add-tag <key> <value>, add-alias <label> <id>, add-email <email>,
+                              login <external id> [jwt], logout, toggle-push, allow-notifications
+                            With RETRY_TEST_IV_KEY set, login signs a JWT when none is given.
+  jwt <external id> [label=id] [email:addr] [sms:number]
+                            Print an Identity Verification JWT claiming those aliases and subscriptions
+  relaunch                  Kill and relaunch the demo app
+  fresh                     Clear the demo app's data (new SDK user) and relaunch
+  background | foreground   Send the demo app to the background, or bring it back
+  network-flap [seconds]    Turn the device's Wi-Fi and mobile data off and back on (default 10s)
+
+Routes: create-user fetch-user update-user identity remove-alias create-sub update-sub
+        delete-sub transfer-sub identity-by-sub custom-events all
+Env: RETRY_TEST_SERIAL (adb serial), RETRY_TEST_PORT ($PORT), RETRY_TEST_PACKAGE ($PACKAGE),
+     RETRY_TEST_IV_APP_ID and RETRY_TEST_IV_KEY (Identity Verification app and its private key path)
+EOF
+}
+
+case "${1:-help}" in
+  start) cmd_start ;;
+  stop) cmd_stop ;;
+  fail) shift; cmd_fail "$@" ;;
+  clear) cmd_clear ;;
+  rules) cat "$RULES" 2>/dev/null || echo "[]" ;;
+  watch) tail -n +1 -F "$PROXY_LOG" | grep --line-buffered '^\[fault\]' ;;
+  report) shift; python3 "$SCRIPT_DIR/report.py" "$ATTEMPTS" "$@" ;;
+  reset-log) cmd_reset_log ;;
+  logs) cmd_logs ;;
+  fresh) cmd_fresh ;;
+  install) cmd_install ;;
+  tap) shift; cmd_tap "$@" ;;
+  jwt) shift; cmd_jwt "$@" ;;
+  relaunch) resolve_device; dev shell am force-stop "$PACKAGE"; launch_app ;;
+  background) resolve_device; dev shell input keyevent KEYCODE_HOME && echo "Demo app backgrounded." ;;
+  foreground) resolve_device; launch_app && echo "Demo app foregrounded." ;;
+  network-flap) shift; cmd_network_flap "$@" ;;
+  help|-h|--help) usage ;;
+  *) usage; exit 1 ;;
+esac