- Decision
- ADR-036
- Date
- 2026-08-07
- Status
- SupersededSuperseded by ADR-240. Accepted
- Mentions
- ADR-035, ADR-240
- Mentioned by
- ADR-240
1Decision
Root-cause and close ADR-035's open Guardian real-hardware detection defect (GBL-105/106); rebuild, re-sign, and re-flash a clean (non-debug) lynx candidate; complete the previously-blocked real-hardware remediation/undo validation.
2Why and evidence
Followed superpowers:systematic-debugging: gathered evidence before touching any fix. A full-system (-b all) logcat sweep around a freshly confirmed AppOps note found zero framework-level signal — no exception, no StrictMode, no crash.
A freezer hypothesis (Guardian's watcher process suspended when the fixture's op fires) was formed and cleanly ruled out via dumpsys activity processes: Guardian is persistent=true, isFrozen=false, cached=false throughout.
With non-invasive avenues exhausted, added a single temporary Slog.w to the one catch (RemoteException e) block in AppOpsService.notifyOpChecked() (frameworks/base), rebuilt services.jar alone, live-pushed it to the running device (bypassing a full image flash for a throwaway diagnostic), and re-triggered the fixture: the instrumentation never fired, disconfirming ADR-035's leading hypothesis.
The real cause was in the evidence already gathered but initially read past: dumpsys appops's own output format for the fixture's GPS/MONITOR_LOCATION access (duration=+Xms, Running start at:) is the signature of a duration-tracked (startOp/finishOp) access, not an instantaneous noteOp one.
Reading AppOpsService.java/AttributedOp.java directly confirmed this structurally: AttributedOp#started() — the method a real startOp call reaches — dispatches exclusively through scheduleOpActiveChangedIfNeededLocked/notifyOpActiveChanged (the "active" callback path, registered via the public AppOpsManager.startWatchingActive(String[], Executor, OnOpActiveChangedListener)), and scheduleOpActiveChangedIfNeededLocked has exactly one caller in the entire tree — AttributedOp.java, never AppOpsService.java's own one-shot noteOperationUnchecked.
Guardian's BackgroundLocationWatcher was registered only on the "noted" channel (startWatchingNoted); for ops that only ever go through started(), no noted-dispatch is ever attempted for them at all — not filtered, not swallowed, simply never scheduled — which is also why ADR-035's four previously-ruled-out noted-path hypotheses (switch-op remapping, MANAGE_APPOPS gate, per-uid scoping, batched-note path) were all correctly ruled out: none of them were the mechanism, because the noted path was never engaged in the first place.
Fix: BackgroundLocationWatcher.start() now registers a second, independent watcher via startWatchingActive for OPSTR_GPS/OPSTR_MONITOR_LOCATION (acting only on active=true), alongside the existing startWatchingNoted registration (left in place, unchanged, for whatever may still reach it via a one-shot path); both funnel into a renamed shared handler (onAccess, replacing the now-inaccurate onNoted).
Verified end-to-end on real hardware, each step independently cross-checked via dumpsys, never trusted from the app's own UI alone: fresh AppOps note -> Guardian auto-opens (topResumedActivity=.../.GuardianActivity, confirmed via two onDetection: startActivity succeeded log lines, one per watched op) -> "Protect app" -> dumpsys package confirms ACCESS_BACKGROUND_LOCATION: granted=false while ACCESS_FINE_LOCATION stays untouched -> Undo -> dumpsys package confirms granted=true again.
This closes GBL-105/106 and completes Task 6 Steps 4-6 of the lynx hardware-port plan, previously blocked.
Separately, cleaning up the temporary framework instrumentation surfaced and fixed a real, independent signing-quality regression before it shipped: re-running avbtool add_hashtree_footer without an explicit --hash_algorithm silently defaults to sha1 (a real AVB tooling behavior, not specific to this candidate) — caught only because the newly-signed system.img's hash algorithm was diffed against the previously-accepted candidate's (sha256) before accepting the signing output, matching this project's own established "diff before trusting N/N verified" discipline.
Corrected with an explicit --hash_algorithm sha256, then independently AVB-verified 13/13 on two machines (build server's python3 external/avb/avbtool.py, local machine's /usr/bin/avbtool) — full 12-partition cross-check on both, not a partial re-check, despite tight local disk pressure (a shared, RAM-backed /tmp briefly hit 99% full transferring all 12 images; managed by deleting already-verified, no-longer-needed local scratch files rather than skipping partitions).
Before trusting the reflash, also identified and closed a real, non-obvious integrity gap: the scratch-overlay remount used earlier in the session for fast debug-iteration (adb remount, backing /system with a writable overlay at /mnt/scratch/...) persists its upper-directory content across reboots and continues to shadow reads even while the overlay mount itself reports ro — so simply reflashing a new, properly signed system.img underneath an untorn-down overlay would have left the device silently still running the earlier unsigned, adb-pushed files, not the verified image, while every AVB/boot check would still report clean.
Resolved by adb enable-verity + reboot before flashing (re-enabling dm-verity enforcement, which is incompatible with the overlay and tears it down), confirmed after flashing via /proc/mounts showing a real /dev/block/dm-N block device (not overlay) and ro.boot.veritymode=enforcing, and via services.jar/GuardianApp.apk on-device md5sum exactly matching the pristine/staged expected content — not merely inferred from a clean boot.
3Consequences
Build-log version progression this session: 1.05 (session start, debug logging shipped, superseded) -> 1.06 (this entry's fix, clean: no Guardian-side trace logging, no framework instrumentation, system+vbmeta rebuilt via m systemimage with BUILD_NUMBER=2026080701/USE_FIXED_TIMESTAMP_IMG_FILES=true, rollback index 1783209600 re-confirmed fresh via avbtool info_image rather than assumed, 13/13 AVB-verified on two machines, flashed, verity re-enforced, byte-for-byte confirmed on-device).
Note ro.build.fingerprint's visible incremental value still reads 2026080601 (unchanged) because only system.img was rebuilt this pass — the device-wide fingerprint is sourced from vendor's (unchanged) build identity, confirmed via ro.vendor.build.fingerprint/system/build.prop's own ro.build.version.incremental=2026080701, not a sign the new build number failed to take.
docs/quality/validation-matrix.md gets GBL-107..GBL-112 closing GBL-105/106. vendor/aegisos/guardian's not-git-tracked state (ADR-035) remains open and unaddressed by this entry.
4Review when
Before BLOCK_BACKGROUND_NETWORK/REMOVE_OVERLAY_PERMISSION/FREEZE_APPLICATION are ported to lynx: any watcher registration for a new capability must be checked against whether the underlying AppOps op (or equivalent OS signal) is a one-shot or duration-tracked/stateful mechanism before assuming a single watch API covers it — this entry's root cause generalizes beyond location.
Also before further hardware work on this device: close the vendor/aegisos/guardian git-tracking gap, and revisit whether the scratch-overlay-remount workflow used for fast debug-iteration should be a documented, standard step (with its teardown requirement made explicit) rather than discovered ad hoc each time.
Read from docs/governance/decision-log.md, entry ADR-036.