fix: aggressive sleep fires reliably after every scheduled refresh

Author: bpmct

AGENTS.md

@@ -85,3 +85,8 @@ docker exec <container_id> bash -c "<command>"
 ## Worktrees
 
 Active development happens in the worktree at `/home/coder/trmnl-nook-sleep` on branch `feature/tap-menu-sleep`. The main checkout is at `/home/coder/trmnl-nook-simple-touch`.
+
+> **CRITICAL for agents:** The devcontainer mounts `/home/coder/trmnl-nook-sleep` as `/workspace`.
+> All source edits MUST be made to files under `/home/coder/trmnl-nook-sleep/` (the worktree).
+> Editing `/home/coder/trmnl-nook-simple-touch/` (the main checkout) has NO effect on builds.
+> Always verify with: `docker inspect <container_id> --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{println}}{{end}}'`

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [v0.12.0] - 2026-03-29
+
+### Fixed
+- **Aggressive sleep now reliably fires after every scheduled refresh.** Previously the super-sleep check used `fetchReason` and flag state that could be clobbered by `onResume()`, meaning the device often stayed awake after displaying a new image. Simplified to: if Aggressive Sleep is enabled and the fetch was not triggered by the user (menu tap), call `sleepNow()` immediately after the image renders — no flags, no race conditions.
+- `sleepPending` is now correctly cleared in `onResume()` and the screen timeout is always restored to 120 s on wake, regardless of sleep path.
+
+### Notes
+- All source edits must target the worktree at `/home/coder/trmnl-nook-sleep/` — see AGENTS.md.
+
+---
+
+## [v0.11.0] - 2026-03-28
+
+### Added
+- **Aggressive Sleep** (`Settings → General → Aggressive sleep`): puts the device to sleep immediately after each scheduled image refresh rather than waiting for the screensaver timeout. Battery savings vs. standard deep sleep are TBD.
+- **Sleep button** (`Settings → System → Sleep`): manually triggers an immediate sleep from the settings screen.
+- `android.permission.WRITE_SETTINGS` permission — used to set `SCREEN_OFF_TIMEOUT = 1000 ms` to trigger Android's natural screen-off path (no root required). Restored to 120 s on wake.
+- `AGENTS.md`: documents the build environment, all failed sleep approaches, and the working `WRITE_SETTINGS` trick.
+
+### Changed
+- Screensaver/sleep-ready delay reduced from 5 s to 2 s.
+- Deep sleep hint always visible when "Sleep between updates" is enabled.
+- README: added Aggressive Sleep section and listed it in Features.
+
+### Removed
+- `android.permission.DEVICE_POWER` (was unused / ungrantable).
+
+---
+
+## [v0.10.0] - 2026-03-25
+
+### Added
+- Gift Mode restart flow improvements.
+
+---
+
+*Older releases are documented on the [GitHub Releases](https://github.com/usetrmnl/trmnl-nook-simple-touch/releases) page.*

src/com/bpmct/trmnl_nook_simple_touch/DisplayActivity.java

@@ -93,7 +93,8 @@ public class DisplayActivity extends Activity {
     private BroadcastReceiver connectivityReceiver;
     private Runnable pendingSleepRunnable;
     private Runnable pendingScreenOffRunnable;
-    /** True while sleepNow() is armed — blocks onResume from re-asserting FLAG_KEEP_SCREEN_ON. */
+    /** True while sleepNow() is armed — blocks onResume from re-asserting FLAG_KEEP_SCREEN_ON
+     * and restoring the 120s screen timeout until the device actually wakes. */
     private volatile boolean sleepPending = false;
     private Runnable pendingWifiWarmupRunnable;
     private Runnable pendingConnectivityTimeoutRunnable;
@@ -374,18 +375,14 @@ protected void onResume() {
         getWindow().setFlags(
                 WindowManager.LayoutParams.FLAG_FULLSCREEN,
                 WindowManager.LayoutParams.FLAG_FULLSCREEN);
-        if (!sleepPending) {
-            setKeepScreenAwake(true);
-            // Restore screen timeout to normal (in case sleep button set it to 1s)
-            try {
-                android.provider.Settings.System.putInt(
-                    getContentResolver(),
-                    android.provider.Settings.System.SCREEN_OFF_TIMEOUT,
-                    120000);
-            } catch (Throwable t) { /* ignore */ }
-        } else {
-            logD("onResume: sleepPending=true, skipping setKeepScreenAwake");
-        }
+        sleepPending = false;
+        try {
+            android.provider.Settings.System.putInt(
+                getContentResolver(),
+                android.provider.Settings.System.SCREEN_OFF_TIMEOUT,
+                120000);
+        } catch (Throwable t) { /* ignore */ }
+        setKeepScreenAwake(true);
 
         boolean wifiJustOn = ensureWifiOnWhenForeground();
 
@@ -1289,7 +1286,7 @@ private void sleepNow() {
         pendingScreenOffRunnable = new Runnable() {
             public void run() {
                 pendingScreenOffRunnable = null;
-                sleepPending = false;
+                // NOTE: sleepPending stays true until onResume() after the real wake.
                 logD("sleepNow: setting screen_off_timeout=1000 to force natural sleep");
                 try {
                     android.provider.Settings.System.putInt(
@@ -1595,11 +1592,12 @@ protected void onPostExecute(Object result) {
                     a.forceFullRefresh();
                     a.logD("displayed image");
                     a.logD("next display in " + (a.refreshMs / 1000L) + "s");
-                    // Super Sleep: if enabled and this was a background (timer/alarm) fetch, sleep immediately
-                    if (ApiPrefs.isSuperSleep(a)
-                            && ApiPrefs.isAllowSleep(a)
-                            && !fromMenu
-                            && ("timer".equals(a.fetchReason) || "alarm".equals(a.fetchReason))) {
+                    // Super Sleep: sleep immediately after every background image render.
+                    // Skip only if user tapped Next from the menu.
+                    boolean superSleep = ApiPrefs.isSuperSleep(a);
+                    boolean allowSleep = ApiPrefs.isAllowSleep(a);
+                    a.logD("super-sleep check: superSleep=" + superSleep + " allowSleep=" + allowSleep + " fromMenu=" + fromMenu);
+                    if (superSleep && allowSleep && !fromMenu) {
                         a.logD("super sleep: sleeping immediately after image load");
                         a.sleepNow();
                     } else {