Home / Engineering notes / Grab detection
Grab detection engineering notes
Short, actionable lessons from authoring and reviewing the grab detection patches of ADR-169, for the next change to physical/grab-detection in oblivios-platform.
Short, actionable lessons from authoring and reviewing the grab detection patches of ADR-169, for the next change to physical/grab-detection in oblivios-platform. The design is 2026-10-15-grab-detection-design.md; the evidence rows are GRB-* in the validation matrix. Claims are labelled [verified-in-source], [measured] or [assumption].
lockNow()posts the lock; it does not lock.PhoneWindowManager.lockNowremoves and postsmScreenLockTimeoutand sets a pending flag, then returns[verified-in-source: services/core/.../policy/PhoneWindowManager.java:6068-6080]. A return without an exception therefore proves nothing about the keyguard. The 60-second timer is armed before the lock (init ignores a request while a timer runs), so the service cancels it when the keyguard has not shown five seconds later.- Register and unregister of a pointer listener are not symmetric.
WindowManagerService.registerPointerEventListenerdoes nothing when the display has no content, whilePointerEventDispatcher.unregisterInputEventListenerthrowsIllegalStateExceptionfor a listener that was never added[verified-in-source: services/core/.../wm/WindowManagerService.java:4087-4093, wm/PointerEventDispatcher.java:84-93]. A disarm must tolerate that, and a sensor registration returns a boolean that must be read. - Nothing may throw out of a service thread. An exception from
onBootPhaseis rethrown asRuntimeException("Failed to boot service …")[verified-in-source: services/core/.../SystemServiceManager.java:328-335]; an exception that leaves the service's ownHandlerThreadreaches the uncaught-exception handler ofsystem_server[assumption]. Every entry point of the service is wrapped, and the cosmetic write (the triggered flag) is separated from the lock. - A shadow log must show what the rule rejected. The first detector returned nothing for a peak without recent touch, so the shadow phase could not answer the open question of a route without touch (design 4.2, 7). The detector now reports such a peak once per cool-down, marked untouched.
- A release before the peak is void after a new touch. A finger that went up and is down again at the peak counted as pulled out of the fingers
[measured: host harness, 2026-10-15, trigger=true released=true]. The detector clears the earlier release when a new touch starts. - Changing a return contract can hollow out old assertions. After the untouched-peak report, the assertion
d != nullno longer meant "a candidate", and the mutant "touch window is exclusive" survived[measured: mutate.py, 25 of 26 killed before the assertions checkedtouched]. Run the mutation check after every change of what a function returns. - Hidden
Settings.Globalkeys are not readable by every app.SettingsProviderrunscheckReadableAnnotationfor a read of a hidden global key[verified-in-source: packages/SettingsProvider/.../SettingsProvider.java:2513,2640], so the keys of the feature are probably not an oracle for apps; the outcome is recorded byGRB-014and stays[assumption]until then. - Put
@hideon its own javadoc line, as the neighbouring keys do. A tag in the middle of a line may be missed by the API tooling and leak the key into the public API[assumption]; a module build does not catch that. - A module build proves little about the tests.
m services SystemUI Settingspassed (GRB-002) but does not compiletests/utils, so the brokenBouncerMessageInteractorKosmos.ktfixture and any API check of the keys stay unproven. Patch0008adds the missing argument to the fixture; the full image build2026101407passed, but it does not compiletests/utilseither, so the fixture is read against the constructor, not built. - Candidates in a row are at least about 3 s apart. The detector ignores peaks for the 2 s cooldown that follows a decision logged 1 s after the peak, so continuous shaking gives one candidate per 3.01 s
[measured: lynx, 2026-10-17, GRB-004]and a counted series of pulls must leave 4 s between them. - A pull that stops is not a grab. Laying the phone down or catching it gave energy 0.62 to 1.15 m/s², below the 1.5 m/s² default
[measured: GRB-004]; the test instruction "pull and keep moving" is what a thief does, and an instruction that ends the movement tests nothing. - A catch with a touching hand can trigger. In a series without touch, 6 of 7
trigger=truelines followed apeak without touchby 1.1 to 1.6 s with a release within 124 ms, so the catching hand reads as the touch of a second candidate[inference from timing; the touch events are not logged]. The counted series of 2026-10-18 repeats it: 6 of 10 pulls without touch locked the phone, each lock 1.10 to 1.36 s after apeak without touch, with a catch peak of 39.9 to 125.0 against 16.1 to 27.0 for the untouched pulls[measured: lynx, 2026-10-18, GRB-004]. The detector cannot tell the owner's catching hand from a thief's grab; whether a normal hand-over triggers isGRB-005. - A locked phone is dark to
adb, and the log of the previous boot is not readable. The 60 s restart cannot be timed from the host:logcat -Lis empty andpstoreis denied. Read the lock from theinitandGrabDetectionlines before the restart, or use the owner's stopwatch[measured: GRB-008]. su <app uid>does not test what an app may do.settingsandcontentfail first onINTERACT_ACROSS_USERSandACCESS_CONTENT_PROVIDERS_EXTERNALLY, also for an ordinary key, so the refusal says nothing about the keys of the feature[measured].GRB-014needs a test app.- The stock lockdown text needs biometrics.
PIN is required after lockdownis shown only when trust or biometrics are available[verified-in-source: BouncerMessageInteractor.kt, patch 0004]; with no fingerprint enrolled (dumpsys fingerprint,"count":0) the manual Lockdown shows nothing, and "no fingerprint offered" after a grab lock says nothing either. Enrol a fingerprint on the test phone beforeGRB-006andGRB-012are judged. - The 5 s keyguard check logs an error when the owner unlocks first. A PIN entered within 5 s of the lock gives
E GrabDetection: keyguard did not show after the lock, cancelling the restart timerafter the unlock, followed byon_device_unlocked: no started timer[measured: 2026-10-17 21:26:03]; harmless, but a false error line in the log. - The Settings screen does not observe the mode key. A screen that is open keeps the old switch state when the mode changes by
adb[measured: GRB-013]. - A raw recorder needs the screen on and untouched. An app in the background gets no continuous sensor events on Android 9 and later, so a recording stopped when the owner touched the screen and the app went away
[measured: 2026-10-18, benign trace ended at its first touch].dumpsys sensorservicekeeps the last 50 accelerometer events but masks the values.tools/grab-recorderruns at 200 Hz; the service runs atSENSOR_DELAY_GAME, so a peak from the recorder is not a peak the service logs, and thresholds are set from the service's own log only. - Rest and a hand overlap in the movement level. One-second standard deviation of the magnitude: 0.005 to 0.01 on a table in the first 43 s, 0.018 to 0.43 over 360 s of the same table, 0.10 to 1.7 in a hand
[measured: lynx, 2026-10-18]. A hold-state rule has no clean threshold (ADR-176). - Grabs that stand still fail only the energy condition. Eight staged grabs with the other hand became candidates and had energy 0.18 to 1.50 against 1.5
[measured: GRB-004, 2026-10-18]; the impact route of ADR-176 does not depend on what follows the peak. - The free fall before an impact separates a set-down from a grab; the peak does not. Grabs peak at 47 to 210 m/s², set-downs of 3 cm at 47 to 106 and hard ones at 83 to 199
[measured: GRB-019, 2026-10-25]. A phone set down falls freely for 16 to 163 ms before it lands (magnitude below 4 m/s²) and none of 12 staged grabs has any[measured: the real GrabDetector replayed over the recordings at 50 Hz in five phases of the sample grid, 2026-10-26]; ADR-195 uses it. The detector must see the free fall at the service's own rate: a fall of 3 cm is 4 samples at 50 Hz, and one run of samples counts askintervals, notk - 1. The free-fall tracker has to update before the cool-down check, or a fall that ends inside a cool-down is lost. - Hold the test to the real code, not a model of it. A first Python model of the rule counted only the last low run within 100 ms of the impact and reported no free fall for nine of eleven hard set-downs; replaying the Java class over the recordings gave the right answer. Replay the real class over the recordings before a threshold is chosen. A mutation run whose base test fails reports every mutant as killed;
mutate.pyis meaningful only afterrun.shprintsall passed. - The recordings differ in rate.
grab-still.csvwas recorded at 40 Hz and the others at 238 Hz; a replay resamples every file to 20 ms steps. The recordings stay on the phone and the workstation and are not committed. - The first device look at the free-fall rule found a gap on each side
[measured: GRB-020, GRB-021, lynx 2026102302, 2026-10-27, shadow mode, level 1]. Of 21 set-downs 20 gave a free fall of 19 to 208 ms and no lock; one soft set-down gavefallMs=0and would lock. Of 7 recorded grabs 6 gavefallMs=0and would lock; one gave 16 ms and would not. A drop from 30 cm gave 154 to 196 ms and no lock (0 of 5). The longest hard set-down (208 ms) is 42 ms under the limit. The result stands on one hand and one phone; the number of pulls was not counted, so pulls under 30 m/s² are unseen. - A grab and a pickup look the same at the first sample, and only the width of the pulse tells them apart
[measured: GRB-024, 2026-10-29]. Theimpactline shows the first sample overimpactPeak, not the peak of the pulse: the 12 recorded grabs give 30 to 50 m/s² there and a pickup from a table 30.4, with no free fall in both. The recordings give the width, the time above 15 m/s²: 171 to 310 ms for a grab, 4 to 13 ms for the spikes of pickups and bumps. The rule is in ADR-204 (minPulseMs, 120 ms). Shadow mode ran the same code as active mode and was right about every event it saw; it saw only staged ones, and the first normal pickup in active mode locked the phone. A shadow measurement of staged events is not a test of daily use: pick the phone up from a table, put it in a pocket and take it out, in a block of its own, and count theimpactlines. The recordings stay on the phone (/sdcard/Android/data/org.freehold.grabrec/files, 7 files, 23 MB) and are pulled withadb pullinto a scratch directory;tools/grab-recorder/replayreplays the real detector over them. Do not ask the owner to repeat a measurement before the recordings and the earlier rows are read: they hold 12 grabs, 17 set-downs of 3 cm, 11 hard set-downs, one pickup and some bumps. - Shadow mode logs the same
impactline as active mode (locks=,fallMs,level,mode=1), so a set of grabs can be measured without ten PIN entries; the first block of the session ran in mode 2 and locked at 11:46:07 and 11:46:15 withfallMs=0. - Shadow and active mode decide the same, and the pickup and the levels were shown
[verified-in-source: GrabDetectionService.onDecision, patches 0003 and 0009; measured: GRB-018 to GRB-024, lynx 2026110203, 2026-11-03]. Only the calllockAndArmRestartdepends on the mode; thelocks=of a shadow line is what active mode does. Active run (owner's reports against the log): a pickup 5impactlines alllocks=false; set-downs 14 lineslocks=false; one hard set-down with the hand still on the phone gavepeak=156.6 fallMs=0 pulseMs=134 locks=trueand locked (the signature of a grab: no free fall, a pulse of 130 to 150 ms); 4 grabslocks=true, each followed bydisarmedandauto_reboot: started timer for 60 seconds. Shadow run at the standard level: pickup 0 of 10 locks (a line withfallMs=0 pulseMs=34is the case offrameworks-base/0011), drops 50 cm 4 of 5 (fallMs284 to 356; the miss was 243, limit 250) and 1 m 5 of 5, set-downs 0 of 18, grabs 7 of 10 (the gentle ones stay under the 30 m/s^2 first-sample limit and make no line; the owner leaves that as it is). Level 0 locks set-downs, level 2 only grabs of 60 m/s^2 and more. The pulse limit lies between 102 ms (locks=false) and 130 ms. - A switch to a user without a lock screen cancels the restart timer
[measured: GRB-017, lynx 2026110203, 2026-11-03]: after a grab lock the owner switched from the lock screen to a second user; the log showssendContinueUserSwitchLU-0-to-13and one second laterauto_reboot: on_device_unlocked: stopped timer; the phone then ran on the normal 18 hour timer. Fix: ADR-213, no user switcher on any locked device. To test it:pm create-user NAME(the removal by the owner,pm remove-user ID, destroys the CE and DE keys of the id through vold), mode 2, a pull, the switcher on the PIN screen. While a screen is off the service isdisarmed(the keyguard shows), so drops made then are not logged: a block of drops that gave no line was repeated after the unlock.
Read from docs/architecture/grab-detection-engineering-notes.md.