fix: refresh widgets after idle

[ovitrif]

Fixes #975

Motivation

• Android home-screen widgets could show stale data after the device stayed idle because Android defers periodic WorkManager refreshes during idle/Doze and the app did not enqueue a catch-up refresh on unlock or idle exit.

Description

• Add AppWidgetRefreshReceiver that enqueues a one-shot widget catch-up when Intent.ACTION_USER_PRESENT or PowerManager.ACTION_DEVICE_IDLE_MODE_CHANGED idle exit occurs while the app process is alive.
• Add an explicit AppWidgetRefreshAlarmReceiver scheduled with AlarmManager.setAndAllowWhileIdle so overdue widget catch-up can start the app process after long idle even if Bitkit was reclaimed.
• Schedule widget refresh work from app startup and when LightningNodeService stops so existing OS widgets are covered after app updates and after stopping Bitkit from the persistent notification.
• Add enqueueCatchUp one-time WorkManager path to AppWidgetRefreshWorker and hasActiveWidgets/cancel logic so catch-up runs only when OS widgets are installed and catch-up work is cancelled when no widgets remain.
• Register the receiver at app startup and trigger the same catch-up when the app returns to foreground.
• Add Context.alarmManager, Context.powerManager, and changelog fragment changelog.d/next/978.fixed.md.

Preview

N/A

QA Notes

Manual Tests

• 1. Android launcher → add any Bitkit home-screen widget, not only an in-app widget → open Bitkit once → press Home: the widget is visible and the app process has registered/scheduled refresh catch-up.
• 2. regression: ADB → force the device into idle/Doze with the commands below → exit idle and unlock: logcat shows Enqueued widget refresh for 'device_idle_exit' or Enqueued widget refresh for 'user_present', then Refreshing data for widget types: ...; the home-screen widget updates without waiting for the 15-minute periodic WorkManager window.
• 3. regression: Bitkit running with background payments enabled → stop Bitkit from the persistent notification → lock for 15+ minutes → unlock and check OS widgets: widgets refresh without opening Bitkit.
• 4. No-lock smoke test → apply the temporary debug patch below → rebuild/install dev debug → send the custom broadcast: logcat shows Enqueued widget refresh for 'debug_catch_up', then Refreshing data for widget types: ....

The original stale-widget condition is: an actual Android home-screen widget exists, the app has previously started, Android enters idle/Doze and defers the 15-minute periodic WorkManager refresh, then the user unlocks/exits idle before the periodic job is allowed to run. On master, the same forced-idle/unidle flow has no widget catch-up receiver path, so the widget can stay on cached data until the next periodic refresh is eventually allowed. This PR should enqueue immediate one-time catch-up work on idle exit, unlock, app foreground, app startup, and Bitkit service stop, and it schedules an explicit alarm catch-up path for the case where the app process was reclaimed during a long idle period.

Force the idle condition without waiting 15+ minutes:

adb logcat -c
adb shell am start -n to.bitkit.dev/to.bitkit.ui.MainActivity
adb shell input keyevent KEYCODE_HOME
adb shell dumpsys battery unplug
adb shell dumpsys deviceidle enable
adb shell dumpsys deviceidle force-idle
adb shell dumpsys deviceidle get deep
adb shell dumpsys deviceidle unforce
adb shell input keyevent KEYCODE_WAKEUP
adb shell input keyevent 82
adb logcat -d -s APP | grep -E "AppWidgetRefreshReceiver|AppWidgetRefreshAlarmReceiver|AppWidgetRefreshWorker|Enqueued widget refresh|Received widget refresh alarm|Refreshing data for widget types"
adb shell dumpsys battery reset

Optional temporary patch for a no-lock, no-wait adb trigger. Apply in one command, rebuild with ./gradlew installDevDebug, open Bitkit once, then run adb shell am broadcast -a to.bitkit.dev.DEBUG_WIDGET_CATCH_UP -p to.bitkit.dev.

git apply <<'PATCH'
diff --git a/app/src/main/java/to/bitkit/App.kt b/app/src/main/java/to/bitkit/App.kt
index d7a412346..6d22fb89b 100644
--- a/app/src/main/java/to/bitkit/App.kt
+++ b/app/src/main/java/to/bitkit/App.kt
@@ -47,10 +47,16 @@ internal open class App : Application(), Configuration.Provider {
             addAction(Intent.ACTION_USER_PRESENT)
             addAction(PowerManager.ACTION_DEVICE_IDLE_MODE_CHANGED)
+            if (BuildConfig.DEBUG) addAction("to.bitkit.dev.DEBUG_WIDGET_CATCH_UP")
+        }
+        val receiverFlags = if (BuildConfig.DEBUG) {
+            ContextCompat.RECEIVER_EXPORTED
+        } else {
+            ContextCompat.RECEIVER_NOT_EXPORTED
         }
         ContextCompat.registerReceiver(
             this,
             AppWidgetRefreshReceiver(),
             filter,
-            ContextCompat.RECEIVER_NOT_EXPORTED,
+            receiverFlags,
         )
     }
 
diff --git a/app/src/main/java/to/bitkit/appwidget/AppWidgetRefreshReceiver.kt b/app/src/main/java/to/bitkit/appwidget/AppWidgetRefreshReceiver.kt
index 486406d79..78e4cda0b 100644
--- a/app/src/main/java/to/bitkit/appwidget/AppWidgetRefreshReceiver.kt
+++ b/app/src/main/java/to/bitkit/appwidget/AppWidgetRefreshReceiver.kt
@@ -11,6 +11,7 @@ class AppWidgetRefreshReceiver : BroadcastReceiver() {
     override fun onReceive(context: Context, intent: Intent) {
         when (intent.action) {
             Intent.ACTION_USER_PRESENT -> enqueueCatchUp(context, "user_present")
+            "to.bitkit.dev.DEBUG_WIDGET_CATCH_UP" -> enqueueCatchUp(context, "debug_catch_up")
             PowerManager.ACTION_DEVICE_IDLE_MODE_CHANGED -> {
                 if (!context.powerManager.isDeviceIdleMode) enqueueCatchUp(context, "device_idle_exit")
             }
PATCH

Clean up the temporary patch after testing:

git restore app/src/main/java/to/bitkit/App.kt app/src/main/java/to/bitkit/appwidget/AppWidgetRefreshReceiver.kt

Automated Checks

• git diff --check was run and produced no whitespace errors.
• The temporary debug QA patch in these notes was validated with git apply --check.
• ./gradlew compileDevDebugKotlin passed locally.
• ./gradlew testDevDebugUnitTest passed locally.
• ./gradlew detekt passed locally.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 295079f67e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[piotr-iohk]

Testing notes:

Prerequisite: add all OS widgets and lock the phone for a few (15+) minutes.

a) Bitkit running in bg

• unlock and check widgets -> OK, widgets get refreshed after unlock ✅

b) Bitkit not running in background (foreground service stopped from the persistent Bitkit notification)

• unlock and check widgets -> widgets are not refreshed ❌

---

Also noticed this after force shutdown the app - OS widgets loose the content, until tapped on. (however force shutdown warns that this action may cause app misbehavior).

Screen_Recording_20260601_162003_One.UI.Home.mp4

[ovitrif]

Testing notes:

Prerequisite: add all OS widgets and lock the phone for a few (15+) minutes.

a) Bitkit running in bg

• unlock and check widgets -> OK, widgets get refreshed after unlock ✅

b) Bitkit not running in background (foreground service stopped from the persistent Bitkit notification)

• unlock and check widgets -> widgets are not refreshed ❌

Also noticed this after force shutdown the app - OS widgets loose the content, until tapped on. (however force shutdown warns that this action may cause app misbehavior).

[media]

Resolved in de12165

[ovitrif]

Also noticed this after force shutdown the app - OS widgets loose the content, until tapped on. (however force shutdown warns that this action may cause app misbehavior).

Probably same behavior for all other apps 🤷🏻 ? That's what I'm observing:

[jvsena42]

Starting review