FullCharge: Cancel a session only on a real native settings change (#65)

The session service's native-change observer cancelled without
restoring on ANY notification for the adapter's setting URIs.
Notifications are dispatched asynchronously, so the session's own
override write can arrive after the observer registers, and an OEM
provider can notify without a value change — both observed on
HyperOS 3 tanzanite (issue #48), where the session ended mid-charge
and the protective policy was never restored.

NativeChangeGuard now verifies the change where the configuration is
synchronously readable: a readback still decoding to the session's
override policy is noise and keeps the session; a different, foreign,
or unreadable value cancels as before. Adapters without sync readback
(Pixel) keep the blanket cancel. A Shizuku readback timeout counts as
unreadable instead of silently dropping the notification.

Also records the tanzanite beta verification results in the
qualification ledger: absent key decodes as Intelligent (confirmed),
app-context three-mode control works over direct WSS, and the mode-2
cap is fixed at 80%.

Author: d4rken

.claude/rules/architecture.md

@@ -69,7 +69,12 @@ ordering, session overrides) lives in the **`oem-adapters` skill** — read it b
   override), expiry or a backwards clock restores as before. `full` and the 24h safety timeout keep priority. On
   every other adapter `replugGraceMillis` is 0 and the decision table is unchanged.
 - While active, the service watches the adapter's settings URIs; an unexpected native/system change **cancels without
-  restoring**, so Amply never overwrites a newer external choice.
+  restoring**, so Amply never overwrites a newer external choice. Cancellation requires a **real** change
+  (`NativeChangeGuard`): settings notifications are dispatched asynchronously, so the session's own override write can
+  arrive after the observer registers, and an OEM provider may notify without any value change (both observed on
+  HyperOS 3 `tanzanite`, issue #48 — blind cancellation ended the session with the protective policy never restored).
+  On sync-readback adapters a notification whose readback still decodes to the session override is ignored as noise;
+  without sync readback (Pixel) any notification still cancels.
 - Boot recovery runs the restore *inside the service* with a bounded convergence check (re-write until the HAL
   confirms or budget expires), because a boot-time write can race the observer registration. The pending target is
   persisted so a killed service resumes.

.claude/skills/device-qualification/SKILL.md

@@ -51,7 +51,7 @@ only after adding a row here. Detailed run narratives live in each adapter's lan
 | Xiaomi | Xiaomi 13T `2306EPN60G` HyperOS 2.0 (`ro.mi.os.version.code=2`) | **Partial** — mapping/readback/session verified; the adaptive 80% hold could not be triggered, so daemon-level hardware enforcement is **not yet demonstrated** | Read matrix, both-direction writes, session at 100%, unknown-value refusal, R8 beta | 2026-07-21 |
 | OnePlus (Oplus) | OnePlus Nord CE4 Lite `CPH2621` ColorOS 15 (`ro.build.version.oplusrom=V15.0.0`) | Full — enforcement directly observable (device holds at 80%); external writes stick | Two mutually-exclusive `system` keys (Charging limit / Smart charging), WSS-only write rejected + Shizuku write succeeds for all three policies, WSS-only UX (controls disabled + Shizuku-required banner) | 2026-07-21 |
 | GrapheneOS | Pixel 9 Pro XL `komodo`, GrapheneOS 2026080501 / Android 17 — **REMOTE qualification via issue #49** (tester-run protocol, not maintainer hardware) | **Enforcement observed**: held at 80% with shield, `dumpsys battery` status=4/Charging state=4/policy=2 (limit on) vs 2/1/1 (off); shell-UID writes move the Settings UI live, **latch at plug-session start** — mid-session writes have no hardware effect until unplug→replug, replug reliably applies the current value | Key isolation (`settings list` diff → single `global battery_charge_limit` 0/1), write→UI both directions, mid-session no-op both directions, replug latch both directions, hardware signal both states. **NOT run**: app-context access tiers (WSS write from Amply, `app.grapheneos.*` package visibility), sessions/boot recovery, wireless, factory-absent key state, secondary user | 2026-08-12 |
-| Xiaomi (HyperOS 3) | Redmi Note 14 `24117RN76G` (`tanzanite`), HyperOS 3.0.302 / Android 16 (`ro.mi.os.version.code=3`) — **REMOTE qualification via issue #48** (contributor-run protocol, not maintainer hardware) | **Both-direction enforcement of EXTERNAL shell-UID writes observed** (the same write path as Amply's Shizuku service): `settings put … 2` below the cap → Battery protection active, Settings UI follows immediately, held at 80% for ~20 min under active use (voltage 4228 mV holding vs 4391 mV charging, charge counter 4283 vs 4341 corroborate; sysfs `current_now` permission-denied, so no current reading); `settings put … 0` mid-hold → charging resumes past 80 immediately. **No hardware hold signal**: `dumpsys battery` reports `status: 2` / `Charging state: 0` / `Charging policy: 0` in both states → read-back-only verification | Key mapping (three modes incl. `2` = Battery protection @80), external write → UI both directions, sustained hold, mid-hold release. **NOT run** (GrapheneOS-precedent landing; verify on the next beta via issue #48): app-context access tiers, sessions/boot recovery, factory-absent key state, wireless, R8 | 2026-08-14 |
+| Xiaomi (HyperOS 3) | Redmi Note 14 `24117RN76G` (`tanzanite`), HyperOS 3.0.302 / Android 16 (`ro.mi.os.version.code=3`) — **REMOTE qualification via issue #48** (contributor-run protocol, not maintainer hardware) | **Both-direction enforcement of EXTERNAL shell-UID writes observed** (the same write path as Amply's Shizuku service): `settings put … 2` below the cap → Battery protection active, Settings UI follows immediately, held at 80% for ~20 min under active use (voltage 4228 mV holding vs 4391 mV charging, charge counter 4283 vs 4341 corroborate; sysfs `current_now` permission-denied, so no current reading); `settings put … 0` mid-hold → charging resumes past 80 immediately. **No hardware hold signal**: `dumpsys battery` reports `status: 2` / `Charging state: 0` / `Charging policy: 0` in both states → read-back-only verification | Key mapping (three modes incl. `2` = Battery protection @80, cap fixed — no percent picker), external write → UI both directions, sustained hold, mid-hold release. Beta run 2026-08-14 added: app-context three-mode control (direct WSS), factory-absent key = Intelligent (confirmed). Session restore FAILED in that run (observer noise cancel — app bug, fixed; see Known gaps). **NOT run**: Shizuku tier, boot recovery, wireless, R8, session re-verify post-fix | 2026-08-14 |
 | GrapheneOS (follow-up) | Same device, **0.3.2-beta0 on-device report via issue #49** | **Package detection VERIFIED from app context** (`is_grapheneos=true` with the FLAG_SYSTEM check); **unprivileged key read DENIED** — `has_battery_charge_limit=false` while the very same report showed `battery_charging_status=4` (limit enforcing). Root cause in GrapheneOS source: the key is `@Protected(read = SYSTEM_UI, readWrite = SETTINGS)` (frameworks_base `c30c6393`); SettingsProvider throws SecurityException for all other packages **including WSS holders**, with the shell UID explicitly exempt ("ADB is used for testing", `e87c93a2`) — so the tester's earlier adb runs ARE the Shizuku-path evidence. Factory-absent semantics resolved from source: `BoolSetting(..., default false)` → absent = off | Detection + fail-closed probe verified live; adapter re-gated to Shizuku-only in response | 2026-08-13 |
 
 ## Known gaps
@@ -190,15 +190,29 @@ only after adding a row here. Detailed run narratives live in each adapter's lan
       contributor was asked whether the settings screen shows any third mode / 80% option.
     - **LANDED 2026-08-14: `xiaomi-hyperos3-v1`, gated to a qualified-codename allowlist (`tanzanite` only) —
       GrapheneOS-precedent landing** (remote enforcement qualification via issue #48, see the Verified devices
-      row; app-level items open, all failing closed, to be verified by the contributor on the next beta):
-      - **Absent-key decode unverified**: absent decodes as Intelligent/Adaptive, mirroring HyperOS 2's
-        factory-state assumption; HyperOS 3 factory semantics are unknown. Worst case if wrong: a session
-        restore writes `1` onto a factory state that was not Intelligent — bounded, no battery hazard.
-        Next-beta ask: `settings delete secure security_pc_secure_protect_mode_key`, then `settings get` +
-        observe which mode the native UI shows.
-      - **Sessions / boot recovery / access tiers (WSS-only vs Shizuku) / R8**: NOT RUN on HyperOS 3;
-        the mechanism is the shared session engine + the same `secure`-namespace write path qualified on
-        HyperOS 2, but on-device confirmation is pending the next beta.
+      row). **First on-device verification run (2026-08-14, issue #48; contributor-run, presumably on
+      v0.3.3-beta0 — the first release carrying the adapter):**
+      - **Absent-key decode CONFIRMED**: `settings delete` → `settings get` returns `null`, and both the native
+        battery settings and Amply fall back to Intelligent charging. Absent = Intelligent is the real factory
+        semantic; the shipped decode is correct.
+      - **App-context writes + three-mode switching CONFIRMED**: switching all three modes from inside Amply is
+        mirrored by the system settings immediately and vice versa, with the key value following each change
+        (contributor polled `settings get` per switch). Access tier in the run: direct WSS (dashboard showed
+        "Read back through direct wss"); the Shizuku tier remains unexercised on this device.
+      - **Temporary session FAILED to restore — real app bug, adapter-independent, FIXED post-run**: the
+        session's native-change observer received a settings notification carrying no value change (the
+        session's own override write delivered late by async dispatch, or a HyperOS spurious notification) and
+        cancelled the session without restoring; the device charged to 100% with the protective policy never
+        re-written. Root-caused from the run's artifacts — the contributor's 22:22 screenshot shows the
+        dashboard already idle at 96% while their 2s key monitor shows no value change after the 21:59:08
+        override write. Fixed by `NativeChangeGuard` (readback-verified cancellation, see
+        `rules/architecture.md`); **session-lifecycle re-verification is the headline ask for the next beta**.
+        Boot recovery and R8 smoke remain NOT RUN.
+      - **Cap is fixed at 80%** (no percent picker in the Battery protection screen), and mode `2`'s own
+        description says the device will "charge fully only when scheduled" — HyperOS reserves an OEM-side
+        scheduled full charge while in Battery protection. No code impact (verification is settings readback;
+        sessions override with `0`), but a future "charged to 100% while protected" report may be this OEM
+        behavior rather than a bug.
       - **Adaptive (mode `1`) enforcement undemonstrated** — identical provisional status as HyperOS 2 (the
         top-level Xiaomi gap above); only mode `2` has demonstrated hardware enforcement.
       - The gate cannot widen past the codename allowlist: record any new HyperOS 3 device here plus a

app/src/main/java/eu/darken/amply/charging/core/adapter/XiaomiChargingAdapter.kt

@@ -166,9 +166,8 @@ class XiaomiHyperOs3ChargingAdapter @Inject constructor() : ChargingAdapter {
             )
         }
         return when (mode.value) {
-            // Absent = intelligent mirrors the HyperOS 2 factory-state assumption but is
-            // UNVERIFIED on HyperOS 3 — pending the issue-#48 qualification run's
-            // factory/absent-key check; adjust if the evidence contradicts it.
+            // Absent = intelligent, VERIFIED on tanzanite (issue #48, 2026-08-14): deleting the
+            // key made the native battery settings fall back to Intelligent charging.
             null, XiaomiChargingAdapter.VALUE_INTELLIGENT ->
                 ChargeObservation.Verified(ChargePolicy.Adaptive, backend.kind)
 

app/src/main/java/eu/darken/amply/fullcharge/core/ChargeSessionService.kt

@@ -31,6 +31,7 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.launch
@@ -93,6 +94,51 @@ class ChargeSessionService : Service() {
                     // fast-path check above but before we acquire the lock, so its own write must not be
                     // mistaken for a native change and cancelled.
                     if (restoring) return@withExclusive
+                    // Only cancel on a REAL native change. Notifications also arrive for the
+                    // session's own override write (async dispatch can outrun the observer
+                    // registration in beginOrResume) and, on some OEM providers, without any value
+                    // change at all — both fatal here, because cancelling ends the session with the
+                    // protective policy never restored (observed on HyperOS 3, issue #48). Where
+                    // the configuration is synchronously readable, a readback still matching the
+                    // override is that noise; without readback (Pixel) cancel as before.
+                    if (fullChargeStore.currentSession() != null) {
+                        val overridePolicy = repository.currentAdapter()?.sessionOverridePolicy
+                            ?: ChargePolicy.Unrestricted
+                        // Holding the dispatch lock across the readback is bounded by the same
+                        // backend a restore would need anyway (worst case one cold Shizuku bind on
+                        // GrapheneOS; every other adapter reads direct).
+                        val readback = try {
+                            repository.syncReadback()
+                        } catch (e: TimeoutCancellationException) {
+                            // A Shizuku bind/command timeout is a failed READBACK, not this
+                            // observer being cancelled — rethrowing would silently drop the
+                            // notification and keep a session alive past a genuine native change.
+                            log(TAG, Logging.Priority.WARN) {
+                                "Readback for the native-change check timed out"
+                            }
+                            null
+                        } catch (e: CancellationException) {
+                            throw e
+                        } catch (e: Exception) {
+                            // Unverifiable counts as a change: same conservative end state as the
+                            // pre-guard blanket cancel.
+                            log(TAG, Logging.Priority.WARN) {
+                                "Readback for the native-change check failed: ${e.message}"
+                            }
+                            null
+                        }
+                        if (!NativeChangeGuard.shouldCancel(readback, overridePolicy)) {
+                            log(TAG) {
+                                "Ignoring settings notification; readback still matches the " +
+                                    "session override: $readback"
+                            }
+                            return@withExclusive
+                        }
+                        log(TAG, Logging.Priority.INFO) {
+                            "Native settings change during session (readback=$readback); " +
+                                "cancelling without restore"
+                        }
+                    }
                     // Respect a native Settings change instead of restoring over the user's choice.
                     manager.cancelWithoutRestore()
                     unregisterSettingObserver()

app/src/main/java/eu/darken/amply/fullcharge/core/SessionDecision.kt

@@ -1,5 +1,6 @@
 package eu.darken.amply.fullcharge.core
 
+import eu.darken.amply.charging.core.ChargeObservation
 import eu.darken.amply.charging.core.ChargePolicy
 import eu.darken.amply.fullcharge.core.ChargeSessionRecord
 
@@ -50,6 +51,32 @@ object SessionStartDecider {
     }
 }
 
+/**
+ * Decides whether a settings-change notification observed during an active session is a genuine
+ * native change (cancel the session without restoring) or noise (ignore, keep the session).
+ *
+ * Android dispatches settings notifications asynchronously, so the session's OWN override write can
+ * be delivered after the observer registers, and an OEM provider may notify without any value
+ * change at all — both observed on HyperOS 3 `tanzanite`, where blind cancellation ended the
+ * session mid-charge and the protective policy was never restored (issue #48). Where the adapter's
+ * configuration is synchronously readable, a notification whose readback still decodes to the
+ * session's override policy is therefore treated as noise. Deliberate trade-off: a native change
+ * that still decodes to the override policy — re-selecting the same value, or on multi-key
+ * adapters editing an auxiliary key the decoded policy ignores (e.g. Samsung's threshold while the
+ * PauseAtFull override is active) — is indistinguishable from that noise and keeps the session
+ * running, and the later restore can overwrite such an auxiliary edit with pre-session values.
+ * Accepted: only reachable by editing protection settings mid-session, and never a charge-safety
+ * regression (the protective policy still comes back).
+ *
+ * Everything else cancels, preserving the previous blanket behavior: a different verified policy
+ * is a real native change; an unrecognized or unreadable value cannot be attributed to the
+ * session; and without sync readback (Pixel, [readback] null) nothing can be verified.
+ */
+object NativeChangeGuard {
+    fun shouldCancel(readback: ChargeObservation?, overridePolicy: ChargePolicy): Boolean =
+        !(readback is ChargeObservation.Verified && readback.policy == overridePolicy)
+}
+
 enum class SessionDecision {
     CONTINUE,
     MARK_CONNECTED,

app/src/test/java/eu/darken/amply/fullcharge/core/NativeChangeGuardTest.kt

@@ -0,0 +1,76 @@
+package eu.darken.amply.fullcharge.core
+
+import eu.darken.amply.charging.core.BackendKind
+import eu.darken.amply.charging.core.ChargeObservation
+import eu.darken.amply.charging.core.ChargePolicy
+import eu.darken.amply.common.ca.toCaString
+import io.kotest.matchers.shouldBe
+import org.junit.jupiter.api.Test
+
+class NativeChangeGuardTest {
+
+    private val override = ChargePolicy.Unrestricted
+
+    private fun verified(policy: ChargePolicy, backend: BackendKind = BackendKind.DIRECT_WSS) =
+        ChargeObservation.Verified(policy, backend)
+
+    @Test
+    fun `readback matching the override is noise`() {
+        NativeChangeGuard.shouldCancel(verified(ChargePolicy.Unrestricted), override) shouldBe false
+        // The backend that produced the readback is irrelevant to the comparison.
+        NativeChangeGuard.shouldCancel(
+            verified(ChargePolicy.Unrestricted, BackendKind.SHIZUKU),
+            override,
+        ) shouldBe false
+    }
+
+    @Test
+    fun `non-Unrestricted overrides compare by policy equality`() {
+        // Samsung modern overrides with PauseAtFull instead of Unrestricted.
+        NativeChangeGuard.shouldCancel(
+            verified(ChargePolicy.PauseAtFull),
+            ChargePolicy.PauseAtFull,
+        ) shouldBe false
+        NativeChangeGuard.shouldCancel(
+            verified(ChargePolicy.FixedLimit(80)),
+            ChargePolicy.FixedLimit(80),
+        ) shouldBe false
+        NativeChangeGuard.shouldCancel(
+            verified(ChargePolicy.FixedLimit(85)),
+            ChargePolicy.FixedLimit(80),
+        ) shouldBe true
+    }
+
+    @Test
+    fun `a different verified policy is a real native change`() {
+        NativeChangeGuard.shouldCancel(verified(ChargePolicy.FixedLimit(80)), override) shouldBe true
+        NativeChangeGuard.shouldCancel(verified(ChargePolicy.Adaptive), override) shouldBe true
+    }
+
+    @Test
+    fun `unrecognized and unreadable values cancel`() {
+        NativeChangeGuard.shouldCancel(
+            ChargeObservation.Unknown("foreign value".toCaString(), unrecognizedValue = true),
+            override,
+        ) shouldBe true
+        NativeChangeGuard.shouldCancel(
+            ChargeObservation.Unknown("unreadable".toCaString()),
+            override,
+        ) shouldBe true
+    }
+
+    @Test
+    fun `no sync readback cancels like before`() {
+        // Async adapters (Pixel) return null — the pre-guard blanket behavior stays.
+        NativeChangeGuard.shouldCancel(null, override) shouldBe true
+    }
+
+    @Test
+    fun `only verified readback can rescue the session`() {
+        // A last-requested claim is Amply's own journal, not an observation of the key.
+        NativeChangeGuard.shouldCancel(
+            ChargeObservation.LastRequested(ChargePolicy.Unrestricted),
+            override,
+        ) shouldBe true
+    }
+}