ObliviOS Developer portal Project site

Home / Decisions / ADR-058

Land docs/superpowers/plans/2026-08-27-duress-real-user-quiescing-and-return.md in full.

Accepted, recorded 27 August 2026.

Decision
ADR-058
Date
2026-08-27
Status
AcceptedAccepted (qualified — two items left open, see Consequences)
Mentioned by
ADR-059, ADR-064

1Decision

Land docs/superpowers/plans/2026-08-27-duress-real-user-quiescing-and-return.md in full: replace the broken "freeze the real user via stopUserWithDelayedLocking" mechanism (found unworkable for user 0 during Task 7 of the original decoy-switch plan) with app-level quiescing (RealUserQuiescer: existing cached-app freezer + notification suppression, including a call/media-exemption fix found during this plan's own Task 3 review), and add the previously-unspecified return-to-real-user path (ReturnToRealUserHelper).

2Why and evidence

UserController.stopUsersLU unconditionally refuses to stop UserHandle.USER_SYSTEM (confirmed via real source, services/core/java/com/android/server/am/UserController.java:1323-1324) -- true for every AOSP device, not a project-specific gap, since the primary owner is always user 0 on a normal (non-headless-system-user) device including lynx.

Design: docs/superpowers/specs/2026-08-27-duress-real-user-quiescing-and-return-design.md (owner-approved). 8 commits landed on aegisos-duress-decoy-switch in order (two tasks needed a real follow-up fix, landed as separate commits rather than amends): 6ef616c714af (RealUserQuiescer, Task 1), 35dee8ebff74 (ActivityManagerInternal/ActivityManagerService quiescing methods, Task 2), 15162045ce05 (notification suppression, Task 3), 834412c4b589 (generic unquiesce-on-become-current hook, Task 4), 1f4a79aabfa4 (DecoyProfileHelper sequencing fix, Task 5), f15c3d86962e+079d5588f483 (verifyPrimaryCredentialNoRouting, Task 6 -- the second commit zeroizes the synthetic password, a real gap the implementer found in this plan's own sample code), 62b84f2aa8d1+c1c367950ab6 (ReturnToRealUserHelper + wiring, Task 7 -- the second commit fixes a wrong file path the first commit landed under), 295f6f9cf610 (call/media notification exemption fix, Task 8, found during Task 3's own review -- isCallNotification/isMediaNotification previously let a real call for the quiesced user bypass suppression entirely, independently truth-table-verified by two different reviewers).

Consolidated build confirmed all of 0001-0015 compile together: ninja: 1h3m33.34s Build Succeeded: 2444 steps, #### build completed successfully (01:03:38) ####.

Emulator validation (Task 10 of this plan, real HEAD 295f6f9cf610) confirmed with direct evidence: decoy match (real switch, verified via mCurrentUserId and absence of failure logging); frozen-process evidence (32/36 user-0 processes isFrozen=true, remaining 4 plausibly excluded by pre-existing AOSP freezer non-cached rules, not a RealUserQuiescer defect); notification-suppression evidence (dumpsys notification usage-stats proof with a differential control case -- quiesced user's notification blocked, active user's own notification posts normally); return-path result (real match against the real owner's credential, real switch back to user 0, unquiescing proven via a user-0 notification posting normally again afterward); wrong-PIN and wipe-PIN both confirmed correct and not confused with decoy routing (real DuressWipe/storage-key-deletion/device-poweroff evidence for the wipe path).

Two items are explicitly left open, not swept under the rug: the call/media-exemption fix (Task 8) has strong static confirmation (live source re-read matches its own published boolean-logic proof) but no successful dynamic trigger of a real CallStyle/session-token MediaStyle notification against the specific backgrounded-user-0 scenario in the available emulator tooling (a real GSM call routes to the current/decoy user rather than the SIM-owning user 0 in this multi-user configuration -- a newly-observed platform behavior, not a bug); and a post-wipe emulator reboot characterization was time-boxed at ~71 minutes across two relaunches and left genuinely inconclusive (QEMU process and console stayed healthy throughout, the guest never became adb-responsive, no crash-loop found or ruled out) -- assessed as very likely an environment artifact (a resource-shared server's slow first-boot-after-wipe), not a regression, since none of Tasks 1-8 touch early-boot code and the wipe mechanism itself independently fired correctly before this open item began.

A real, unrelated infrastructure defect was also found and fixed during validation: the emulator's initial cold boot hung 1h46m because it loaded a stale quickboot snapshot from an earlier build against this session's freshly built system image; fixed by adding -no-snapshot-load to the documented manual launch sequence.

3Consequences

Exported as aegisos-platform/credential/duress-unlock-decoy/patches/frameworks-base/0008-0015. The decoy mechanism is functionally complete and validated end to end on the emulator: entry, freeze, notification suppression, and return all work with real evidence. Task 7 of the original decoy-switch plan is superseded by this plan's own Task 10; Task 8 of that plan (physical hardware) gained a new battery-measurement requirement and remains not started.

Two residual gaps remain open for future work: a dynamic call/media-notification test against the backgrounded user (needs either a self-managed VoIP-style test call or physical-hardware testing where a real GSM call can be more directly controlled), and confirming whether the post-wipe reboot slowness is real or purely an artifact of this shared build server (worth re-checking on a less loaded host or on physical hardware).

4Review when

Revisit if physical-hardware validation (still-pending Task 8 of the original plan) finds the freeze/unfreeze timing or battery numbers unacceptable, or if either of the two open items above resolves to a real defect rather than an environment/platform artifact -- this ADR only covers emulator-level functional correctness for the mechanism's own code paths, not real-hardware performance or the two explicitly-flagged open items.

Read from docs/governance/decision-log.md, entry ADR-058.