Charging: Gate GrapheneOS charge control on Shizuku

The 0.3.2-beta0 on-device report (issue #49) disproved the landing
assumption that global battery_charge_limit is world-readable and
WSS-writable: the probe read absent while the same report showed the
limit enforcing (charging state 4). GrapheneOS declares the key
@Protected(read = SYSTEM_UI, readWrite = SETTINGS) (frameworks_base
c30c6393) and its SettingsProvider throws SecurityException on reads
and writes from every other package - including WRITE_SECURE_SETTINGS
holders; the check is package-based and runs after the permission
check (e87c93a2). The one exemption Amply can use is the shell UID
('ADB is used for testing'), which is exactly how the Shizuku user
service executes settings get/put - the tester's successful adb runs
were this path's evidence all along.

The adapter now sets preferShizukuForWrites (existing Oplus plumbing:
Shizuku-required banner, disabled controls, skipped WSS auto-grant)
and drops the unprobeable key-presence gate - @Protected denies the
probe whether the key exists or not, so presence is assumed on any
GrapheneOS build, the Xiaomi-precedent assumption with the same
accepted harmless-false-claim failure mode. An absent key now decodes
as the factory off state per upstream source (BoolSetting default
false) instead of refusing. Reads need no code change: the direct read
comes back unreadable and readSyncDirectFirst already falls through to
Shizuku. The shared Shizuku-required banner no longer claims state
stays readable without Shizuku, which was only true for Oplus.

On-device beta evidence recorded in the ledger: package detection
verified from app context; unprivileged key access denied as designed
(fail closed).

Author: d4rken

.claude/CLAUDE.md

@@ -20,14 +20,15 @@ binary Adaptive/Unrestricted) is gated to the HyperOS 2.x ROM (`ro.mi.os.version
 gated to a **physically-qualified device-codename allowlist** (HAL enforcement is per-device) plus the provider and
 system user; **reads are unprivileged (ContentResolver), writes require Shizuku** (the shell UID holds
 `lineageos.permission.WRITE_SETTINGS`, which `WRITE_SECURE_SETTINGS` does not cover). **GrapheneOS charge limit**
-(world-readable `global battery_charge_limit`, binary FixedLimit(80)/Unrestricted, WSS-writable — no Shizuku) is
-gated to GrapheneOS identity (its `app.grapheneos.*` core packages; no property/feature/fingerprint marker exists)
-plus key presence and the system user; the ROM **latches the key at plug-session start** (`policyLatchesAtPlug`),
-so external writes take effect at the next unplug→replug — handled by a pending-until-replug verification state
-and a 30s session grace window; the reconnect gesture is unsupported there. Other Pixels, Samsung on
-unverified One UI versions (6/7, 9+), non-HyperOS-2 Xiaomi devices, non-ColorOS-15 Oplus devices, unqualified
-LineageOS builds, and GrapheneOS builds without the key remain diagnostics-only. See the qualification ledger
-(`.claude/skills/device-qualification/`) for the verified devices and mappings.
+(`global battery_charge_limit`, binary FixedLimit(80)/Unrestricted) is gated to GrapheneOS identity (its
+`app.grapheneos.*` core packages; no property/feature/fingerprint marker exists) plus the system user —
+**reads AND writes require Shizuku**: GrapheneOS marks the key `@Protected`, denying it to all third-party
+packages including WSS holders, with only the shell UID exempt. The ROM **latches the key at plug-session start**
+(`policyLatchesAtPlug`), so external writes take effect at the next unplug→replug — handled by a
+pending-until-replug verification state and a 30s session grace window; the reconnect gesture is unsupported
+there. Other Pixels, Samsung on unverified One UI versions (6/7, 9+), non-HyperOS-2 Xiaomi devices,
+non-ColorOS-15 Oplus devices, and unqualified LineageOS builds remain diagnostics-only. See the qualification
+ledger (`.claude/skills/device-qualification/`) for the verified devices and mappings.
 
 Package: `eu.darken.amply`. License: GPL-3.0-or-later. Status: pre-launch (current version in `VERSION`).
 

.claude/rules/privileged-access.md

@@ -90,13 +90,27 @@ long-term observation (see Known gaps below).
 ### GrapheneOS
 
 GrapheneOS control requires **all** of: GrapheneOS identity (`DeviceInfo.isGrapheneOs` — resolved from the OS's
-core `app.grapheneos.*` packages via PackageManager `<queries>` entries; **no** graphene property, system feature,
-or fingerprint marker exists, verified on a real device), a present world-readable `global battery_charge_limit`
-key (the capability signal — GrapheneOS ships the toggle exactly where its implementation works), and the system
-user. Identity is deliberately **not** OR-ed with key presence: the adapter is registered ahead of the Pixel
-adapter, and a future stock Pixel shipping a same-named key must not be swallowed as GrapheneOS.
+core `app.grapheneos.*` system packages (FLAG_SYSTEM required) via PackageManager `<queries>` entries; **no**
+graphene property, system feature, or fingerprint marker exists, verified on a real device) and the system user.
+**Key presence is deliberately NOT a gate condition and cannot be**: GrapheneOS declares the key
+`@Protected(read = SYSTEM_UI, readWrite = SETTINGS)` (frameworks_base `c30c6393`) and its SettingsProvider throws
+`SecurityException` on reads and writes from every other package — **including `WRITE_SECURE_SETTINGS` holders**;
+the check is package-based and runs after the permission check (`e87c93a2`). The unprivileged probe therefore
+reads absent whether the key exists or not (verified via the issue-#49 beta report: probe false while the same
+report showed the limit enforcing). The feature is treated as present on any GrapheneOS build (Xiaomi-precedent
+assumption; their platform ships it for every Google device, which is every device GrapheneOS supports). Accepted
+failure mode, same class as Xiaomi's: on a build without the feature a shell-UID write could still create the row
+and read back, yielding a harmless false claim of configured control — no battery hazard, and the hardware decode
+(state 4) stays honest.
+
+**Access is Shizuku-only.** The one usable exemption in their enforcement is the shell UID ("ADB is used for
+testing"), which is how the Shizuku user service executes `settings get/put`. The adapter sets
+`preferShizukuForWrites`; direct reads come back unreadable (SecurityException → `access_read_blocked`) and
+`readSyncDirectFirst` falls through to the Shizuku backend. The key is binary (`1` = fixed 80% cap with bypass
+charging, `0` = off); an **absent key decodes as the factory off state** — upstream reads it through
+`BoolSetting(GLOBAL, BATTERY_CHARGE_LIMIT, /* default */ false)`, so a never-toggled device has no row and
+charges unrestricted.
 
-The key is binary (`1` = fixed 80% cap with bypass charging, `0` = off) and WSS-writable — **no Shizuku needed**.
 The defining quirk is **`policyLatchesAtPlug`**: the ROM samples the key only at plug-session start, so an external
 write reads back correctly but has no hardware effect until the next unplug→replug (the native Settings toggle
 applies live because Settings pokes the charging service directly). Three mechanisms handle this — the
@@ -108,10 +122,10 @@ enforcement evidence. The reconnect gesture is unsupported — its override writ
 broadcast, which the ROM has already sampled past.
 
 Qualification is **remote** (issue #49, Pixel 9 Pro XL `komodo`, GrapheneOS 2026080501 / Android 17): the tester
-physically observed enforcement (held at 80% with the shield and state 4) and the latch behavior. Package
-visibility of `app.grapheneos.*` from app context and the factory-absent key state are still unverified on-device;
-both fail closed (Pixel-adapter diagnostics, or diagnostics + contribution wizard). Record any new evidence in the
-qualification ledger (`device-qualification` skill).
+physically observed enforcement (held at 80% with the shield and state 4), the latch behavior, and — via the
+0.3.2-beta0 report — that package detection works from app context while unprivileged key access is denied.
+Shizuku-path writes are the same shell-UID mechanism the tester's adb commands proved. Record any new evidence in
+the qualification ledger (`device-qualification` skill).
 
 ### LineageOS
 

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

@@ -51,6 +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 |
+| 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
 
@@ -116,18 +117,14 @@ only after adding a row here. Detailed run narratives live in each adapter's lan
     ROM: install/launch/onboarding/dashboard/settings with no crashes, honest "Unsupported device" reporting, live
     battery monitoring across simulated plug/level transitions, and the charge alarm firing at threshold.
 - **GrapheneOS** — landed **live** on remote qualification (issue #49; the only OEM row not tested on maintainer
-  hardware). Open items, all failing closed:
-  - **`app.grapheneos.*` package visibility from app context is unverified** — `<queries>` package entries are
-    specified platform behavior (not SELinux-fragile like `ro.lineage.*`), but GrapheneOS hardens aggressively. If
-    the packages are hidden, `isGrapheneOs` is false and the device falls to the Pixel adapter as
-    matched/diagnostics-only — no unsafe write path, but support silently vanishes; the first tester report of
-    "still unsupported" on the test build should check `is_grapheneos=` in the device report.
-  - **App-context WSS write unverified** — the tester's writes ran as shell UID; an Amply-originated
-    `Settings.Global.putString` under granted WSS is expected to behave identically (same namespace rules) but has
-    not been observed. The read-back-equality check catches a silently-failing write.
-  - **Factory-absent key state unknown** — the tester's device had the key present while off; whether a
-    never-toggled install exposes it is unverified. Absent → gate fails closed → diagnostics + contribution wizard
-    (`adapter_detail_grapheneos_no_key`), and `read()` refuses (`unrecognizedValue`) so a session never clobbers it.
+  hardware), then **re-gated to Shizuku-only** after the 0.3.2-beta0 on-device report (see the follow-up ledger
+  row). Resolved since the landing PR: package visibility ✔ verified from app context; app-context WSS access ✘
+  resolved as DENIED (`@Protected` — the reason for the re-gate, not a bug in Amply); factory-absent key state ✔
+  resolved from upstream source (`BoolSetting` default false → absent decodes as Unrestricted). Still open, all
+  failing closed or cosmetic:
+  - **Shizuku end-to-end on real hardware unverified** — the shell-UID `settings get/put` mechanism is proven (the
+    tester's adb runs), but Amply's own Shizuku service driving it, plus sessions/boot recovery/R8 smoke, await the
+    next beta report on issue #49.
   - **State 4 below the limit unverified** — evidence was sampled at the 80% hold; if the ROM reports 4 only while
     holding, a FixedLimit pending clears late (at the hold) instead of instantly. Cosmetic.
   - **A plugged restore configures but cannot enforce** — restore-at-100%, the 24h safety timeout,
@@ -137,7 +134,6 @@ only after adding a row here. Detailed run narratives live in each adapter's lan
     session/recovery closed, pending-until-replug hint shown — and the exposure is one charge cycle,
     bounded by the plug session the user is already in. Deliberately NOT treated as a defect.
   - **Wireless charging and secondary users**: NOT RUN (gated to system user).
-  - Sessions/boot-recovery/R8 smoke on real GrapheneOS hardware: pending the test build posted to issue #49.
 - **Xiaomi** — adaptive hardware enforcement of external writes unconfirmed; treat the adapter as provisional until
   the 80% hold is physically observed.
   - **HyperOS 3 candidate mapping (contribution report, 2026-08-07 — unqualified, stays diagnostics-only).** A

.claude/skills/oem-adapters/SKILL.md

@@ -95,18 +95,22 @@ clobbering the user's native choice. Verified devices + coverage: see the qualif
 One live adapter (`grapheneos-chargelimit-v1`) for GrapheneOS's own "Limit to 80%" (Settings → Battery → Charging
 optimization). **ROM-identity adapter, ordered after the Lineage pair and BEFORE `pixel`** in `AdapterRegistry` —
 GrapheneOS ships only on Pixels, and the Pixel probe (any Google/Pixel*) would otherwise swallow the device as a
-matched-but-diagnostics-only stock Pixel. Gate: `DeviceInfo.isGrapheneOs` (core `app.grapheneos.*` packages via
-PackageManager `<queries>` — NO property/feature/fingerprint marker exists; verified empty on a real device) +
-`hasBatteryChargeLimit` (world-readable key presence — the capability signal, deliberately NOT part of identity) +
-system user. No lab adapter: a GrapheneOS build without the key stays on this adapter as diagnostics-only with
-`contributionWanted`.
+matched-but-diagnostics-only stock Pixel. Gate: `DeviceInfo.isGrapheneOs` (core `app.grapheneos.*` FLAG_SYSTEM
+packages via PackageManager `<queries>` — NO property/feature/fingerprint marker exists; verified on a real
+device) + system user. **Key presence is not — and cannot be — a gate condition**: the key is `@Protected`
+(below), so the unprivileged probe reads absent regardless; the feature is assumed present on any GrapheneOS
+build (their platform ships it for every Google device). No lab adapter; `contributionWanted = false`.
 
 Single key `global battery_charge_limit`: `1` = fixed 80% cap (bypass charging; hard-wired, no threshold key) →
-`FixedLimit(80)`, `0` = off → `Unrestricted`; absent/other → `Unknown(unrecognizedValue=true)` (factory-absent
-semantics unverified — refuse, don't guess). WSS-writable, **no Shizuku**. SYNC_READBACK with read-back equality;
-session override = Unrestricted; protective default = FixedLimit(80); `reapply == apply` (no observer-poke — see
-below); reconnect gesture **unsupported** (structurally: the gesture's override write lands strictly after the
-replug broadcast, which the ROM has already sampled past).
+`FixedLimit(80)`, `0` **or absent** → `Unrestricted` (upstream reads it via `BoolSetting(..., default false)` —
+absent IS the factory off state); other → `Unknown(unrecognizedValue=true)`. **Reads and writes are Shizuku-only**:
+GrapheneOS declares the key `@Protected(read = SYSTEM_UI, readWrite = SETTINGS)` (frameworks_base `c30c6393`) and
+throws SecurityException for every other package *including WSS holders* (`e87c93a2`); the shell UID is the one
+usable exemption, which is exactly the Shizuku user service's `settings get/put` path. `preferShizukuForWrites`;
+direct reads come back unreadable and `readSyncDirectFirst` falls through to Shizuku. SYNC_READBACK with read-back
+equality; session override = Unrestricted; protective default = FixedLimit(80); `reapply == apply` (no
+observer-poke — see below); reconnect gesture **unsupported** (structurally: the gesture's override write lands
+strictly after the replug broadcast, which the ROM has already sampled past).
 
 **The defining quirk: `policyLatchesAtPlug = true`.** GrapheneOS samples the key only at plug-session start; an
 external write updates the Settings UI live but has no hardware effect until the next unplug→replug (the native

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

@@ -270,11 +270,12 @@ class ChargingRepository @Inject constructor(
     }
 
     /**
-     * Sync-readback adapters use world-readable / unprivileged keys, so the DIRECT provider read is
+     * Most sync-readback adapters use world-readable keys, so the DIRECT provider read is
      * authoritative and — unlike a Shizuku user-service bind, which can block up to ~15s on a cold process
      * ([ShizukuController.service]) — never stalls. Read direct first so that bind is never on the critical
-     * path (the widget/tile refresh after a tap); consult Shizuku only as a fallback when the direct read is
-     * not authoritative on some ROM. A nominally "ready" but misbehaving Shizuku service therefore can no
+     * path (the widget/tile refresh after a tap); consult Shizuku as the fallback when the direct read is
+     * not authoritative — including GrapheneOS's @Protected key, where the direct read is always denied
+     * and Shizuku (shell UID) is the only readable path. A nominally "ready" but misbehaving Shizuku service therefore can no
      * longer delay verification.
      */
     private suspend fun readSyncWithFallback(adapter: ChargingAdapter): ChargeObservation? {
@@ -603,11 +604,12 @@ class ChargingRepository @Inject constructor(
 
 /**
  * Read a sync-readback adapter's configured state, preferring the [direct] provider and consulting
- * [shizuku] (may be null when not ready) only as a fallback. Direct reads of these adapters' world-readable
- * keys are authoritative and cannot stall, so an *authoritative* direct read — [ChargeObservation.Verified]
+ * [shizuku] (may be null when not ready) only as a fallback. A direct read of a world-readable key is
+ * authoritative and cannot stall, so an *authoritative* direct read — [ChargeObservation.Verified]
  * or a readable-but-unrecognized OEM value — short-circuits without ever binding the Shizuku user service
- * (both backends read the same settings provider, so Shizuku could not report anything stronger). Only a
- * genuinely unreadable direct result falls back to Shizuku.
+ * (both backends read the same settings provider, so Shizuku could not report anything stronger). A
+ * genuinely unreadable direct result falls back to Shizuku — the routine case for GrapheneOS's @Protected
+ * key, which the provider denies to Amply but not to the shell UID.
  */
 internal suspend fun readSyncDirectFirst(
     adapter: ChargingAdapter,

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

@@ -88,8 +88,11 @@ data class DeviceInfo(
                     Settings.Global.getString(it.contentResolver, KEY_PROTECT_BATTERY) != null
                 }.getOrDefault(false)
             } ?: false,
-            // GrapheneOS's charge-limit key, world-readable in `global`. Presence is the capability
-            // gate (the OS only ships the toggle where its implementation works); fail closed.
+            // GrapheneOS's charge-limit key. NOT a gate: GrapheneOS marks the key @Protected, so
+            // this unprivileged read throws SecurityException (→ false) on real GrapheneOS whether
+            // the key exists or not — verified via the issue-#49 beta report. Kept as a diagnostic
+            // signal only: true would indicate a ROM exposing a same-named key WITHOUT the
+            // GrapheneOS restriction, which is worth seeing in a device-support report.
             hasBatteryChargeLimit = context?.let {
                 runCatching {
                     Settings.Global.getString(it.contentResolver, KEY_BATTERY_CHARGE_LIMIT) != null