coreshift_core/binder/

mod.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/

//! NDK binder primitives for querying Android system services.
//!
//! Uses `dlopen` on `libbinder_ndk.so` to avoid hard-linking against a library
//! absent from older NDK toolchains or non-Android targets.
//!
//! ## Transaction code resolution
//!
//! Transaction codes are resolved fresh from `framework.jar` DEX on each
//! startup; no persistent cache.
//!
//! ## Observer mode
//!
//! `ActivityManager::open_with_observer` registers this process as an
//! `IProcessObserver` with ActivityManager. Callbacks fire when foreground
//! activities change and signal an `eventfd` that callers can poll via epoll.
//! After the eventfd fires, call `get_focused_package` to read the new value.

// ─────────────────────────────────────────────────────────────────────────────
// Android-only implementation
// ─────────────────────────────────────────────────────────────────────────────

#[cfg(target_os = "android")]
mod imp {
    use crate::CoreError;
    use crate::android::dex;
    use std::os::fd::{AsRawFd, FromRawFd, IntoRawFd, OwnedFd};
    use std::os::raw::{c_char, c_void};
    use std::sync::Mutex;
    use std::sync::atomic::{AtomicBool, AtomicI32, AtomicU32, AtomicUsize, Ordering};

    // ── NDK binder status codes ───────────────────────────────────────────────

    const STATUS_OK: i32 = 0;
    const STATUS_UNKNOWN_TRANSACTION: i32 = -2;
    const EX_NONE: i32 = 0;

    // ── Interface constants ───────────────────────────────────────────────────

    const AM_DESCRIPTOR: &[u8] = b"android.app.IActivityManager\0";
    const OBS_DESCRIPTOR: &[u8] = b"android.app.IProcessObserver\0";
    const FGPROC_DESCRIPTOR: &[u8] = b"android.app.IForegroundProcessObserver\0";
    const ACTIVITY_SERVICE: &[u8] = b"activity\0";
    #[cfg(target_pointer_width = "64")]
    const LIBBINDER_PATH: &[u8] = b"/system/lib64/libbinder_ndk.so\0";
    #[cfg(target_pointer_width = "32")]
    const LIBBINDER_PATH: &[u8] = b"/system/lib/libbinder_ndk.so\0";

    // ── Tx code cache ─────────────────────────────────────────────────────────
    // Format (watcher.c compatible): observer_code query_code api_mode fg_code
    // api_mode: 1 = getFocusedRootTaskInfo, 2 = getFocusedStackInfo (API 29)

    // ── Statics for observer callback (binder thread pool context) ────────────
    // The core owns the eventfd for the observer lifetime; the consumer receives
    // a dup and may close it freely. The callback only ever writes to the core's
    // copy, so it can never touch a closed/recycled fd (C2). The mutex guards
    // publication/revocation against a callback firing concurrently.

    static OBS_FG_CODE: AtomicU32 = AtomicU32::new(0);
    static OBS_EVENTFD: Mutex<Option<OwnedFd>> = Mutex::new(None);

    fn obs_eventfd_guard() -> std::sync::MutexGuard<'static, Option<OwnedFd>> {
        OBS_EVENTFD.lock().unwrap_or_else(|p| p.into_inner())
    }

    // ── IForegroundProcessObserver statics ───────────────────────────────────
    // Separate from the IProcessObserver pair; same C2 discipline (core owns
    // the eventfd, consumer gets a dup). FGPROC_READ_I32 holds the vtable's
    // AParcel_readInt32 fn pointer so the callback can decode the `int pid`
    // argument without owning the Vtable; it is published (non-zero) before
    // FGPROC_FG_CODE/eventfd, so the callback never races an unset reader.

    static FGPROC_FG_CODE: AtomicU32 = AtomicU32::new(0);
    static FGPROC_PID: AtomicI32 = AtomicI32::new(0);
    static FGPROC_EVENTFD: Mutex<Option<OwnedFd>> = Mutex::new(None);
    static FGPROC_READ_I32: AtomicUsize = AtomicUsize::new(0);
    // Binder class mode: 0 = stock IForegroundProcessObserver (single int pid),
    // 1 = custom IProcessObserver (pid, uid, fg triplets). Only one of the two
    // is ever configured by open_with_fgproc_observer; the callback branches on
    // this to decode the in-parcel layout it actually receives.
    static FGPROC_IPROC_MODE: AtomicU32 = AtomicU32::new(0);

    fn fgproc_eventfd_guard() -> std::sync::MutexGuard<'static, Option<OwnedFd>> {
        FGPROC_EVENTFD.lock().unwrap_or_else(|p| p.into_inner())
    }

    // ── Raw NDK type aliases ──────────────────────────────────────────────────

    type AIBinder = c_void;
    #[allow(non_camel_case_types)]
    type AIBinder_Class = c_void;
    type AParcel = c_void;
    type BinderStatus = i32;
    type StringAllocator = unsafe extern "C" fn(*mut c_void, i32, *mut *mut c_char) -> bool;

    // ── AIBinder_Class callbacks ──────────────────────────────────────────────

    // AM client — no-op server side (we're a client only)
    unsafe extern "C" fn am_on_create(_: *mut c_void) -> *mut c_void {
        std::ptr::null_mut()
    }
    unsafe extern "C" fn am_on_destroy(_: *mut c_void) {}
    unsafe extern "C" fn am_on_transact(
        _: *mut AIBinder,
        _: u32,
        _: *const AParcel,
        _: *mut AParcel,
    ) -> BinderStatus {
        STATUS_UNKNOWN_TRANSACTION
    }

    // IProcessObserver server callbacks
    unsafe extern "C" fn obs_on_create(_: *mut c_void) -> *mut c_void {
        std::ptr::null_mut()
    }
    unsafe extern "C" fn obs_on_destroy(_: *mut c_void) {}
    unsafe extern "C" fn obs_on_transact(
        _: *mut AIBinder,
        code: u32,
        _: *const AParcel,
        _: *mut AParcel,
    ) -> BinderStatus {
        if code == OBS_FG_CODE.load(Ordering::Relaxed) {
            // Write while holding the lock: the fd can only be closed while
            // we hold it, so a revoke can never race us into a stale number.
            if let Some(fd) = obs_eventfd_guard().as_ref() {
                let val: u64 = 1;
                unsafe { libc::write(fd.as_raw_fd(), &val as *const u64 as *const c_void, 8) };
            }
        }
        STATUS_OK
    }

    // IForegroundProcessObserver server callbacks. Two parcel layouts, selected
    // by FGPROC_IPROC_MODE:
    //  - mode 0 (stock): `onForegroundProcessChanged(int pid)` — single int32.
    //  - mode 1 (custom ROMs without IForegroundProcessObserver): the ROM
    //    repurposes `IProcessObserver.onForegroundActivitiesChanged` to deliver
    //    `(int pid, int uid, int fg)`. The callback stores the pid and only
    //    signals the eventfd when fg != 0 (a foreground transition), so
    //    background transitions never cause the daemon to react.
    unsafe extern "C" fn fgproc_on_create(_: *mut c_void) -> *mut c_void {
        std::ptr::null_mut()
    }
    unsafe extern "C" fn fgproc_on_destroy(_: *mut c_void) {}
    unsafe extern "C" fn fgproc_on_transact(
        _: *mut AIBinder,
        code: u32,
        in_parcel: *const AParcel,
        _: *mut AParcel,
    ) -> BinderStatus {
        if code != FGPROC_FG_CODE.load(Ordering::Relaxed) {
            return STATUS_UNKNOWN_TRANSACTION;
        }
        // Read fn is published non-zero before the code/eventfd, so a matching
        // code is never paired with an unset reader.
        let read_addr = FGPROC_READ_I32.load(Ordering::Relaxed);
        if read_addr != 0 {
            let read_fn: unsafe extern "C" fn(*const AParcel, *mut i32) -> BinderStatus =
                unsafe { std::mem::transmute(read_addr) };
            if FGPROC_IPROC_MODE.load(Ordering::Relaxed) == 1 {
                // IProcessObserver.onForegroundActivitiesChanged(pid, uid, fg)
                let mut pid: i32 = 0;
                let mut _uid: i32 = 0;
                let mut fg: i32 = 0;
                let mut ok = unsafe { read_fn(in_parcel, &mut pid) } == STATUS_OK;
                ok &= unsafe { read_fn(in_parcel, &mut _uid) } == STATUS_OK;
                ok &= unsafe { read_fn(in_parcel, &mut fg) } == STATUS_OK;
                if ok {
                    FGPROC_PID.store(pid, Ordering::Relaxed);
                    // Only foreground transitions are actionable; suppress the
                    // background transition entirely (fg == 0).
                    if fg == 0 {
                        return STATUS_OK;
                    }
                } else {
                    return STATUS_OK;
                }
            } else {
                let mut pid: i32 = 0;
                if unsafe { read_fn(in_parcel, &mut pid) } == STATUS_OK {
                    FGPROC_PID.store(pid, Ordering::Relaxed);
                }
            }
        }
        // Write while holding the lock: the fd can only be closed while we
        // hold it, so a revoke can never race us into a stale number.
        if let Some(fd) = fgproc_eventfd_guard().as_ref() {
            let val: u64 = 1;
            unsafe { libc::write(fd.as_raw_fd(), &val as *const u64 as *const c_void, 8) };
        }
        STATUS_OK
    }

    /// The PID captured by the most recent `onForegroundProcessChanged`
    /// callback (requires `open_with_fgproc_observer`).
    pub fn last_foreground_pid() -> i32 {
        FGPROC_PID.load(Ordering::Relaxed)
    }

    // ── String allocator ─────────────────────────────────────────────────────

    /// Ceiling on a single parcel string regardless of the length the peer
    /// advertises. Component names are at most a few hundred bytes; this bounds
    /// the allocation so a malformed advertised length cannot drive a giant
    /// `reserve_exact` (which would abort on OOM).
    const MAX_BINDER_STRING_LEN: usize = 1024 * 1024;

    unsafe extern "C" fn string_alloc(
        cookie: *mut c_void,
        length: i32,
        buffer: *mut *mut c_char,
    ) -> bool {
        // length == -1 is the Java null-string marker: AParcel_readString
        // calls the allocator with -1 (and a null buffer) when the parcel
        // holds a null string, so returning true there decodes it to None
        // instead of a hard STATUS_UNEXPECTED_NULL failure. Any other
        // negative length is corruption and an allocation failure: returning
        // true with no usable buffer would hand the reader a dangling pointer,
        // and an oversized reserve_exact would abort on OOM.
        if length == -1 {
            return true;
        }
        if length < 0 {
            return false;
        }
        let len = length as usize;
        if len > MAX_BINDER_STRING_LEN {
            return false;
        }
        let s = unsafe { &mut *(cookie as *mut StringBuf) };
        s.0.reserve_exact(len + 1);
        unsafe { s.0.as_mut_vec().resize(len + 1, 0) };
        unsafe { *buffer = s.0.as_mut_ptr() as *mut c_char };
        true
    }

    struct StringBuf(String);
    impl StringBuf {
        fn new() -> Self {
            Self(String::new())
        }
        fn finish(mut self) -> Option<String> {
            if let Some(pos) = self.0.as_bytes().iter().position(|&b| b == 0) {
                unsafe { self.0.as_mut_vec().truncate(pos) };
            }
            if self.0.is_empty() {
                None
            } else {
                Some(self.0)
            }
        }
    }

    // ── Vtable ────────────────────────────────────────────────────────────────

    struct Vtable {
        get_service: unsafe extern "C" fn(*const c_char) -> *mut AIBinder,
        class_define: unsafe extern "C" fn(
            *const c_char,
            unsafe extern "C" fn(*mut c_void) -> *mut c_void,
            unsafe extern "C" fn(*mut c_void),
            unsafe extern "C" fn(*mut AIBinder, u32, *const AParcel, *mut AParcel) -> BinderStatus,
        ) -> *mut AIBinder_Class,
        associate_class: unsafe extern "C" fn(*mut AIBinder, *mut AIBinder_Class) -> bool,
        new_binder: unsafe extern "C" fn(*const AIBinder_Class, *mut c_void) -> *mut AIBinder,
        prepare_transaction: unsafe extern "C" fn(*mut AIBinder, *mut *mut AParcel) -> BinderStatus,
        transact: unsafe extern "C" fn(
            *mut AIBinder,
            u32,
            *mut *mut AParcel,
            *mut *mut AParcel,
            u32,
        ) -> BinderStatus,
        dec_strong: unsafe extern "C" fn(*mut AIBinder),
        parcel_delete: unsafe extern "C" fn(*mut AParcel),
        read_int32: unsafe extern "C" fn(*const AParcel, *mut i32) -> BinderStatus,
        read_string:
            unsafe extern "C" fn(*const AParcel, *mut c_void, StringAllocator) -> BinderStatus,
        write_strong_binder: unsafe extern "C" fn(*mut AParcel, *mut AIBinder) -> BinderStatus,
        set_thread_pool_max: unsafe extern "C" fn(u32),
        join_thread_pool: unsafe extern "C" fn(),
        get_user_data: unsafe extern "C" fn(*const AIBinder) -> *mut c_void,
        write_int32: unsafe extern "C" fn(*mut AParcel, i32) -> BinderStatus,
        read_float: Option<unsafe extern "C" fn(*const AParcel, *mut f32) -> BinderStatus>,
        read_int64: Option<unsafe extern "C" fn(*const AParcel, *mut i64) -> BinderStatus>,
        // Optional: only present on API 29+, but all modern Android has this
        read_bool: Option<unsafe extern "C" fn(*const AParcel, *mut bool) -> BinderStatus>,
    }

    // ── RAII wrappers ─────────────────────────────────────────────────────────

    struct DlHandle;
    unsafe impl Send for DlHandle {}
    impl Drop for DlHandle {
        fn drop(&mut self) {
            // Intentionally no dlclose: the binder thread pool spawned in
            // open_with_observer() keeps executing library code until process
            // exit. Unloading the library while that thread runs causes
            // use-after-free. libbinder_ndk.so is never unloaded during the
            // daemon lifetime; the OS reclaims it on exit.
        }
    }

    struct OwnedParcel {
        ptr: *mut AParcel,
        delete: unsafe extern "C" fn(*mut AParcel),
    }
    impl Drop for OwnedParcel {
        fn drop(&mut self) {
            if !self.ptr.is_null() {
                unsafe { (self.delete)(self.ptr) };
            }
        }
    }

    struct OwnedBinder {
        ptr: *mut AIBinder,
        dec_strong: unsafe extern "C" fn(*mut AIBinder),
    }
    unsafe impl Send for OwnedBinder {}
    impl Drop for OwnedBinder {
        fn drop(&mut self) {
            if !self.ptr.is_null() {
                unsafe { (self.dec_strong)(self.ptr) };
            }
        }
    }

    // ── dlsym helper ─────────────────────────────────────────────────────────

    macro_rules! dlsym_fn {
        ($handle:expr, $name:literal, $ty:ty) => {{
            let sym =
                unsafe { libc::dlsym($handle, concat!($name, "\0").as_ptr() as *const c_char) };
            if sym.is_null() {
                return Err(CoreError::binder(-1, concat!("dlsym:", $name)));
            }
            unsafe { std::mem::transmute::<*mut c_void, $ty>(sym) }
        }};
    }

    macro_rules! dlsym_opt {
        ($handle:expr, $name:literal, $ty:ty) => {{
            let sym =
                unsafe { libc::dlsym($handle, concat!($name, "\0").as_ptr() as *const c_char) };
            if sym.is_null() {
                None
            } else {
                Some(unsafe { std::mem::transmute::<*mut c_void, $ty>(sym) })
            }
        }};
    }

    fn load_vtable(handle: *mut c_void) -> Result<Vtable, CoreError> {
        Ok(Vtable {
            get_service: dlsym_fn!(
                handle,
                "AServiceManager_getService",
                unsafe extern "C" fn(*const c_char) -> *mut AIBinder
            ),
            class_define: dlsym_fn!(
                handle,
                "AIBinder_Class_define",
                unsafe extern "C" fn(
                    *const c_char,
                    unsafe extern "C" fn(*mut c_void) -> *mut c_void,
                    unsafe extern "C" fn(*mut c_void),
                    unsafe extern "C" fn(
                        *mut AIBinder,
                        u32,
                        *const AParcel,
                        *mut AParcel,
                    ) -> BinderStatus,
                ) -> *mut AIBinder_Class
            ),
            associate_class: dlsym_fn!(
                handle,
                "AIBinder_associateClass",
                unsafe extern "C" fn(*mut AIBinder, *mut AIBinder_Class) -> bool
            ),
            new_binder: dlsym_fn!(
                handle,
                "AIBinder_new",
                unsafe extern "C" fn(*const AIBinder_Class, *mut c_void) -> *mut AIBinder
            ),
            prepare_transaction: dlsym_fn!(
                handle,
                "AIBinder_prepareTransaction",
                unsafe extern "C" fn(*mut AIBinder, *mut *mut AParcel) -> BinderStatus
            ),
            transact: dlsym_fn!(
                handle,
                "AIBinder_transact",
                unsafe extern "C" fn(
                    *mut AIBinder,
                    u32,
                    *mut *mut AParcel,
                    *mut *mut AParcel,
                    u32,
                ) -> BinderStatus
            ),
            dec_strong: dlsym_fn!(
                handle,
                "AIBinder_decStrong",
                unsafe extern "C" fn(*mut AIBinder)
            ),
            parcel_delete: dlsym_fn!(handle, "AParcel_delete", unsafe extern "C" fn(*mut AParcel)),
            read_int32: dlsym_fn!(
                handle,
                "AParcel_readInt32",
                unsafe extern "C" fn(*const AParcel, *mut i32) -> BinderStatus
            ),
            read_string: dlsym_fn!(
                handle,
                "AParcel_readString",
                unsafe extern "C" fn(*const AParcel, *mut c_void, StringAllocator) -> BinderStatus
            ),
            write_strong_binder: dlsym_fn!(
                handle,
                "AParcel_writeStrongBinder",
                unsafe extern "C" fn(*mut AParcel, *mut AIBinder) -> BinderStatus
            ),
            set_thread_pool_max: dlsym_fn!(
                handle,
                "ABinderProcess_setThreadPoolMaxThreadCount",
                unsafe extern "C" fn(u32)
            ),
            join_thread_pool: dlsym_fn!(
                handle,
                "ABinderProcess_joinThreadPool",
                unsafe extern "C" fn()
            ),
            get_user_data: dlsym_fn!(
                handle,
                "AIBinder_getUserData",
                unsafe extern "C" fn(*const AIBinder) -> *mut c_void
            ),
            write_int32: dlsym_fn!(
                handle,
                "AParcel_writeInt32",
                unsafe extern "C" fn(*mut AParcel, i32) -> BinderStatus
            ),
            read_bool: dlsym_opt!(
                handle,
                "AParcel_readBool",
                unsafe extern "C" fn(*const AParcel, *mut bool) -> BinderStatus
            ),
            read_float: dlsym_opt!(
                handle,
                "AParcel_readFloat",
                unsafe extern "C" fn(*const AParcel, *mut f32) -> BinderStatus
            ),
            read_int64: dlsym_opt!(
                handle,
                "AParcel_readInt64",
                unsafe extern "C" fn(*const AParcel, *mut i64) -> BinderStatus
            ),
        })
    }

    // ── ParcelReader ──────────────────────────────────────────────────────────

    struct ParcelReader<'a> {
        vt: &'a Vtable,
        parcel: &'a OwnedParcel,
    }

    impl<'a> ParcelReader<'a> {
        fn read_i32(&self) -> Result<i32, CoreError> {
            let mut v = 0i32;
            let s = unsafe { (self.vt.read_int32)(self.parcel.ptr, &mut v) };
            if s != STATUS_OK {
                return Err(CoreError::binder(s, "AParcel_readInt32"));
            }
            Ok(v)
        }
        /// Read a String16 (Java `writeString`) as an owned `String`. Returns
        /// `None` for a null string (`-1` marker); `string_alloc` accepts the
        /// `-1` length so `AParcel_readString` returns `STATUS_OK` instead of
        /// `STATUS_UNEXPECTED_NULL`. Strings are bound-capped (1 MiB) by
        /// `string_alloc`.
        fn read_string(&self) -> Result<Option<String>, CoreError> {
            let mut buf = StringBuf::new();
            let s = unsafe {
                (self.vt.read_string)(
                    self.parcel.ptr,
                    &mut buf as *mut StringBuf as *mut c_void,
                    string_alloc,
                )
            };
            if s != STATUS_OK {
                return Err(CoreError::binder(s, "AParcel_readString"));
            }
            Ok(buf.finish())
        }
        fn read_float(&self) -> Result<f32, CoreError> {
            let r = self
                .vt
                .read_float
                .ok_or_else(|| CoreError::binder(-1, "AParcel_readFloat:unavailable"))?;
            let mut v = 0f32;
            let s = unsafe { r(self.parcel.ptr, &mut v) };
            if s != STATUS_OK {
                return Err(CoreError::binder(s, "AParcel_readFloat"));
            }
            Ok(v)
        }
        fn read_int64(&self) -> Result<i64, CoreError> {
            let r = self
                .vt
                .read_int64
                .ok_or_else(|| CoreError::binder(-1, "AParcel_readInt64:unavailable"))?;
            let mut v = 0i64;
            let s = unsafe { r(self.parcel.ptr, &mut v) };
            if s != STATUS_OK {
                return Err(CoreError::binder(s, "AParcel_readInt64"));
            }
            Ok(v)
        }
        fn read_bool(&self) -> Result<bool, CoreError> {
            if let Some(rb) = self.vt.read_bool {
                let mut v = false;
                let s = unsafe { rb(self.parcel.ptr, &mut v) };
                if s != STATUS_OK {
                    return Err(CoreError::binder(s, "AParcel_readBool"));
                }
                Ok(v)
            } else {
                Ok(self.read_i32()? != 0)
            }
        }
        fn skip_i32s(&self, n: usize) -> Result<(), CoreError> {
            for _ in 0..n {
                self.read_i32()?;
            }
            Ok(())
        }
        fn skip_int_array(&self) -> Result<(), CoreError> {
            let count = self.read_i32()?.max(0) as usize;
            self.skip_i32s(count)
        }
        /// Skip `n` bytes, consuming 4-byte words. Parcel payloads are always
        /// 4-byte aligned (Parcel::pad_size), so `n` is a multiple of 4 for
        /// every skip we perform; the ceiling rounding is defensive.
        fn skip_bytes(&self, n: usize) -> Result<(), CoreError> {
            self.skip_i32s(n.div_ceil(4))
        }
        /// Skip a String16 (Java `writeString`) payload — `writeInt32(len)`
        /// then `(len+1)*2` UTF-16 bytes padded to 4. Returns `Ok(true)` if a
        /// non-null string was consumed, `Ok(false)` for the null marker
        /// (`-1`). This never touches the decoded value, so it is immune to
        /// the UTF-16→UTF-8 allocation path.
        fn skip_string16(&self) -> Result<bool, CoreError> {
            let len = self.read_i32()?;
            if len < 0 {
                return Ok(false);
            }
            // saturating: a hostile `len` could otherwise wrap the byte math
            // on 32-bit targets and silently desync the walk.
            let bytes = ((len as usize).saturating_add(1)).saturating_mul(2);
            self.skip_bytes(bytes)?;
            Ok(true)
        }
        /// Skip a String8 (Java `writeString8`) payload — `writeInt32(len)`
        /// then `len+1` UTF-8 bytes padded to 4. Used for
        /// `DisplayInfo.{name,ownerPackageName,uniqueId}` which the framework
        /// writes with `writeString8`; `AParcel_readString` only decodes
        /// String16 and would desync the walk.
        fn skip_string8(&self) -> Result<bool, CoreError> {
            let len = self.read_i32()?;
            if len < 0 {
                return Ok(false);
            }
            let bytes = (len as usize).saturating_add(1);
            self.skip_bytes(bytes)?;
            Ok(true)
        }
        /// Skip a `Parcel.readValue()` encoded value (Java `writeValue`).
        /// Wire: an i32 type tag, optionally followed by a length prefix and a
        /// payload per tag. Only the tags present in `DeviceProductInfo`
        /// (String/Integer/Parcelable/null) and its nested `ManufactureDate`
        /// must be handled; everything else is defensively rejected so a
        /// layout drift surfaces as a `display_info` error instead of a
        /// misaligned parse.
        fn skip_value(&self) -> Result<(), CoreError> {
            let tag = self.read_i32()?;
            match tag {
                // VAL_NULL (-1): no payload.
                -1 => Ok(()),
                // VAL_STRING (0): writeString → String16.
                0 => self.skip_string16().map(|_| ()),
                // VAL_INTEGER (1), VAL_SHORT (5), VAL_BOOLEAN (9), VAL_BYTE (20),
                // VAL_CHAR (29): 4-byte scalar.
                1 | 5 | 9 | 20 | 29 => self.read_i32().map(|_| ()),
                // VAL_LONG (6): 8-byte scalar.
                6 => self.read_int64().map(|_| ()),
                // VAL_FLOAT (7): 4-byte scalar.
                7 => self.read_float().map(|_| ()),
                // VAL_DOUBLE (8): 8-byte scalar.
                8 => {
                    self.read_i32()?;
                    self.read_i32()?;
                    Ok(())
                }
                // VAL_SIZE (26): 2×i32.
                26 => self.skip_i32s(2),
                // VAL_SIZEF (27): 2×f32.
                27 => {
                    self.read_float()?;
                    self.read_float()?;
                    Ok(())
                }
                // VAL_PARCELABLE (4): length-prefixed — i32 tag, i32 body
                // length, then the parcelable (class name + fields). Lengths
                // are 4-byte aligned in practice; the ceiling is defensive.
                4 => {
                    let len = self.read_i32()?;
                    if len < 0 {
                        return Ok(());
                    }
                    self.skip_bytes(len as usize)
                }
                _ => Err(CoreError::binder(
                    tag,
                    "display_info:unsupported readValue tag",
                )),
            }
        }
        /// Skip a `Parcel.writeTypedObject` Rect: an i32 marker (0 = null,
        /// 1 = non-null) followed by 4×i32 bounds when non-null. Anything else
        /// is a layout drift and rejected.
        fn skip_typed_rect(&self) -> Result<(), CoreError> {
            match self.read_i32()? {
                0 => Ok(()),
                1 => self.skip_i32s(4),
                m => Err(CoreError::binder(m, "display_info:bad typed Rect marker")),
            }
        }
        fn read_first_package_from_names(&self) -> Result<Option<String>, CoreError> {
            let count = self.read_i32()?.max(0) as usize;
            let mut first: Option<String> = None;
            for _ in 0..count {
                let s = self.read_string()?;
                if first.is_none() {
                    first = s.and_then(|c| c.split('/').next().map(str::to_owned));
                }
            }
            Ok(first)
        }
    }

    // ── ParcelWriter / transact helper ────────────────────────────────────────

    struct ParcelWriter<'a> {
        vt: &'a Vtable,
        parcel: &'a OwnedParcel,
    }

    impl<'a> ParcelWriter<'a> {
        fn write_i32(&self, v: i32) -> Result<(), CoreError> {
            let s = unsafe { (self.vt.write_int32)(self.parcel.ptr, v) };
            if s != STATUS_OK {
                return Err(CoreError::binder(s, "AParcel_writeInt32"));
            }
            Ok(())
        }
        fn write_strong_binder(&self, b: *mut AIBinder) -> Result<(), CoreError> {
            let s = unsafe { (self.vt.write_strong_binder)(self.parcel.ptr, b) };
            if s != STATUS_OK {
                return Err(CoreError::binder(s, "AParcel_writeStrongBinder"));
            }
            Ok(())
        }
    }

    /// Prepare an input parcel, run `writes`, then transact. RAII on both
    /// ends: a write error drops the input parcel (previously it leaked on the
    /// write-error path, never reaching transact), and the reply parcel is
    /// returned owned. The input parcel is transferred to `AIBinder_transact`
    /// (the framework deletes it even on failure), so the wrapper records that
    /// by nulling its pointer — never a double-delete.
    fn transact_write(
        vt: &Vtable,
        binder: *mut AIBinder,
        code: u32,
        writes: impl FnOnce(&ParcelWriter<'_>) -> Result<(), CoreError>,
    ) -> Result<OwnedParcel, CoreError> {
        let mut in_ptr: *mut AParcel = std::ptr::null_mut();
        let s = unsafe { (vt.prepare_transaction)(binder, &mut in_ptr) };
        if s != STATUS_OK {
            return Err(CoreError::binder(s, "AIBinder_prepareTransaction"));
        }
        let mut inp = OwnedParcel {
            ptr: in_ptr,
            delete: vt.parcel_delete,
        };
        {
            let writer = ParcelWriter { vt, parcel: &inp };
            writes(&writer)?;
        }
        let mut out_ptr: *mut AParcel = std::ptr::null_mut();
        let s = unsafe { (vt.transact)(binder, code, &mut inp.ptr, &mut out_ptr, 0) };
        // The framework owns (and deletes) the input parcel from here.
        inp.ptr = std::ptr::null_mut();
        let out = OwnedParcel {
            ptr: out_ptr,
            delete: vt.parcel_delete,
        };
        if s != STATUS_OK {
            return Err(CoreError::binder(s, "AIBinder_transact"));
        }
        Ok(out)
    }

    // ── Response parsers ──────────────────────────────────────────────────────

    fn parse_stack_info_body(r: &ParcelReader<'_>) -> Result<Option<String>, CoreError> {
        r.skip_i32s(5)?;
        r.skip_int_array()?;
        r.read_first_package_from_names()
    }

    // RootTaskInfo → (taskId, first childTaskName package). Walks the parcel
    // once: prefix (bounds, childTaskIds), captures the first package from
    // childTaskNames, then skips childTaskBounds / childTaskUserIds / visible /
    // position / TaskInfo.userId to reach taskId — never touching the
    // Intent/TaskInfo tail. taskId and pkg come from the same transaction, so
    // callers pair them without a second (racy) round-trip.
    fn parse_root_task_info_task(r: &ParcelReader<'_>) -> Result<(i32, Option<String>), CoreError> {
        let scratch = r.read_i32()?;
        if scratch != 0 {
            r.skip_i32s(4)?;
        }
        r.skip_int_array()?; // childTaskIds
        let pkg = r.read_first_package_from_names()?; // childTaskNames → pkg
        // childTaskBounds: typed Rect array (nullable) — read count, skip 4 per entry
        let bounds_count = r.read_i32()?;
        let n = if bounds_count < 0 {
            0
        } else {
            bounds_count as usize
        };
        for _ in 0..n {
            let entry = r.read_i32()?;
            if entry != 0 {
                r.skip_i32s(4)?;
            }
        }
        r.skip_int_array()?; // childTaskUserIds
        r.skip_i32s(2)?; // visible, position
        r.skip_i32s(1)?; // TaskInfo.userId
        let task_id = r.read_i32()?;
        Ok((task_id, pkg))
    }

    /// Decoded subset of the Android 14 `android.view.DisplayInfo` parcel used
    /// for FPS normalization.
    struct ParsedDisplayInfo {
        active_mode_id: i32,
        vsync_rate: f32,
        peak_refresh_rate: f32,
        render_frame_rate: f32,
    }

    /// Walk the `IDisplayManager.getDisplayInfo` reply parcel following the
    /// Android 14 `android.view.DisplayInfo.writeToParcel` field order.
    ///
    /// Field order (Android 14):
    /// layerStack, flags, type, displayId, displayGroupId (5×i32), then a
    /// nullable `DisplayAddress` parcelable (`writeParcelable` → a String16
    /// class name, or a single `-1` marker for null), a nullable
    /// `DeviceProductInfo` parcelable, then `name` as a **String8** (Java
    /// `writeString8`), 8 logical-dimension i32s, the `DisplayCutout`
    /// ParcelableWrapper, rotation/modeId/renderFrameRate/defaultModeId, and
    /// `supportedModes`. Only fields up to `supportedModes` are consumed — the
    /// tail (color modes, HDR, rounded corners, …) is never touched.
    ///
    /// `AParcel_readString` decodes String16 only; `name` is String8, so it is
    /// consumed with `skip_string8`. Null strings and null parcelables carry a
    /// `-1` length marker, which `string_alloc` now accepts so they decode to
    /// `None` rather than a hard `STATUS_UNEXPECTED_NULL`.
    ///
    /// Validity gate: any value shape outside the expected one returns a
    /// `CoreError` tagged `display_info` so on-device logs identify the layout
    /// mismatch.
    fn parse_display_info(r: &ParcelReader<'_>) -> Result<ParsedDisplayInfo, CoreError> {
        // 1. layerStack/type/displayId prefix: layerStack, flags, type,
        //    displayId, displayGroupId.
        r.skip_i32s(5)?;

        // 2. address: nullable DisplayAddress parcelable. Non-null writes the
        //    class name as a String16 then the body; null writes a -1 marker.
        //    Body differs by subtype: Physical → 1×i64 display id, Network →
        //    String16 mac address. Dispatch on the decoded class name so a
        //    network display cannot desync the walk.
        if let Some(addr_class) = r.read_string()? {
            if addr_class.ends_with("$Physical") {
                r.read_int64()?;
            } else if addr_class.ends_with("$Network") {
                r.skip_string16()?;
            } else {
                return Err(CoreError::binder(
                    -1,
                    "display_info:unsupported DisplayAddress",
                ));
            }
        }

        // 3. deviceProductInfo: nullable parcelable (same null probe). Body:
        //    mName (String16), mManufacturerPnpId (String16), then three
        //    readValue() fields — mProductId (String), mModelYear (Integer),
        //    mManufactureDate (nullable ManufactureDate parcelable) — and a
        //    final mConnectionToSinkType i32. The ManufactureDate parcelable is
        //    length-prefixed, so skip_value's VAL_PARCELABLE case consumes it
        //    wholesale including its internal writeValue fields.
        if let Some(_dpi_class) = r.read_string()? {
            r.skip_string16()?; // mName
            r.skip_string16()?; // mManufacturerPnpId
            r.skip_value()?; // mProductId
            r.skip_value()?; // mModelYear
            r.skip_value()?; // mManufactureDate
            r.read_i32()?; // mConnectionToSinkType
        }

        // 4. name — Java `writeString8`, a String8 (byte length + UTF-8), may
        //    be null. Must NOT be read with read_string() (String16 only).
        r.skip_string8()?;

        // 5. Logical dimensions: appWidth, appHeight, smallestNominalAppWidth,
        //    smallestNominalAppHeight, largestNominalAppWidth,
        //    largestNominalAppHeight, logicalWidth, logicalHeight (8×i32).
        r.skip_i32s(8)?;

        // 6. displayCutout: ParcelableWrapper. writeCutoutToParcel writes -1
        //    (null), 0 (NO_CUTOUT), or 1 + body. Body: safeInsets (typed
        //    Rect), bounds (typed Rect array), waterfallInsets (typed Rect),
        //    4×i32 cutout path parser dims, density f32, cutoutSpec String16,
        //    rotation i32, scale f32, physicalPixelDisplaySizeRatio f32.
        let cutout_marker = r.read_i32()?;
        if cutout_marker == 1 {
            r.skip_typed_rect()?; // mSafeInsets
            let bounds = r.read_i32()?; // mBounds Rect[]
            if bounds >= 0 {
                for _ in 0..bounds {
                    r.skip_typed_rect()?;
                }
            }
            r.skip_typed_rect()?; // mWaterfallInsets
            r.skip_i32s(4)?; // cutout path parser info (display/phys dims)
            r.read_float()?; // density
            r.skip_string16()?; // cutoutSpec
            r.read_i32()?; // rotation
            r.read_float()?; // scale
            r.read_float()?; // physicalPixelDisplaySizeRatio
        }

        // 7. rotation (i32), modeId (i32), renderFrameRate (f32),
        //    defaultModeId (i32), then nModes (i32).
        r.read_i32()?; // rotation
        let active_mode_id = r.read_i32()?;
        let render_frame_rate = {
            let v = r.read_float()?;
            if v.is_finite() && v >= 0.0 { v } else { 0.0 }
        };
        r.read_i32()?; // defaultModeId
        let n_modes = r.read_i32()?.max(0) as usize;

        // 8. supportedModes: each Display.Mode = { modeId, width, height,
        //    refreshRate (×4 primitive) + alternativeRefreshRates float[],
        //    supportedHdrTypes int[] }.
        let mut vsync_rate: f32 = 0.0;
        let mut peak_refresh_rate: f32 = 0.0;
        for _ in 0..n_modes {
            let mode_id = r.read_i32()?;
            r.read_i32()?; // width
            r.read_i32()?; // height
            let refresh_rate = {
                let v = r.read_float()?;
                // collapse NaN/±Inf/negative like the FPS path; otherwise a
                // hostile peer could leak +Inf into the public DisplayInfo.
                if v.is_finite() && v >= 0.0 { v } else { 0.0 }
            };
            // alternativeRefreshRates: float[] (count + values)
            let alt = r.read_i32()?.max(0) as usize;
            for _ in 0..alt {
                let _f = r.read_float()?;
            }
            // supportedHdrTypes: int[]
            let hdr = r.read_i32()?.max(0) as usize;
            for _ in 0..hdr {
                r.read_i32()?;
            }
            peak_refresh_rate = peak_refresh_rate.max(refresh_rate);
            if mode_id == active_mode_id {
                vsync_rate = refresh_rate.max(vsync_rate);
            }
        }

        Ok(ParsedDisplayInfo {
            active_mode_id,
            vsync_rate,
            peak_refresh_rate,
            render_frame_rate,
        })
    }

    // ── Tx code resolution ────────────────────────────────────────────────────

    pub struct TxCodes {
        pub observer_code: u32,
        pub query_code: u32,
        pub api_mode: u8, // 1 = RootTaskInfo, 2 = StackInfo
        pub fg_code: u32,
    }

    pub fn resolve_tx_codes() -> Result<TxCodes, CoreError> {
        let (obs, query, api, fg) = dex::resolve_tx_codes_from_dex()
            .ok_or_else(|| CoreError::binder(-1, "tx_code_resolution:dex_parse_failed"))?;
        Ok(TxCodes {
            observer_code: obs,
            query_code: query,
            api_mode: api,
            fg_code: fg,
        })
    }

    // ── ActivityManager ─────────────────────────────────────────────────

    pub struct ActivityManager {
        _lib: DlHandle,
        vt: Vtable,
        _class: *mut AIBinder_Class,
        service: OwnedBinder,
        tx_code: u32,
        legacy: bool,
    }
    unsafe impl Send for ActivityManager {}

    impl ActivityManager {
        fn open_inner(
            handle: *mut c_void,
        ) -> Result<(DlHandle, Vtable, *mut AIBinder_Class, OwnedBinder), CoreError> {
            let lib = DlHandle;
            let vt = load_vtable(handle)?;

            let am_class = unsafe {
                (vt.class_define)(
                    AM_DESCRIPTOR.as_ptr() as *const c_char,
                    am_on_create,
                    am_on_destroy,
                    am_on_transact,
                )
            };
            if am_class.is_null() {
                return Err(CoreError::binder(-1, "AIBinder_Class_define:AM"));
            }

            let raw = unsafe { (vt.get_service)(ACTIVITY_SERVICE.as_ptr() as *const c_char) };
            if raw.is_null() {
                return Err(CoreError::binder(-1, "AServiceManager_getService:activity"));
            }
            unsafe { (vt.associate_class)(raw, am_class) };

            let service = OwnedBinder {
                ptr: raw,
                dec_strong: vt.dec_strong,
            };
            Ok((lib, vt, am_class, service))
        }

        fn dlopen_libbinder() -> Result<*mut c_void, CoreError> {
            use std::os::raw::c_char;
            let handle = unsafe {
                libc::dlopen(
                    LIBBINDER_PATH.as_ptr() as *const c_char,
                    libc::RTLD_NOW | libc::RTLD_LOCAL,
                )
            };
            if handle.is_null() {
                return Err(CoreError::binder(-1, "dlopen:libbinder_ndk.so"));
            }
            Ok(handle)
        }

        /// Open ActivityManager binder (polling mode — no observer).
        /// Resolves the query tx code from cache or DEX.
        pub fn open() -> Result<Self, CoreError> {
            let handle = Self::dlopen_libbinder()?;
            let (lib, vt, class, service) = Self::open_inner(handle)?;
            let codes = resolve_tx_codes()?;
            let legacy = codes.api_mode == 2;
            Ok(Self {
                _lib: lib,
                vt,
                _class: class,
                service,
                tx_code: codes.query_code,
                legacy,
            })
        }

        /// Open ActivityManager binder and register as IProcessObserver.
        ///
        /// Returns `(Self, OwnedFd)` where the eventfd is a dup of the core's
        /// callback fd. It becomes readable whenever `onForegroundActivitiesChanged`
        /// fires. Caller must add it to epoll and may close it at any time — the
        /// callback keeps writing to the core's copy, so closing the returned
        /// fd never invalidates the notification path (C2). After the event
        /// fires, call `get_focused_package`.
        pub fn open_with_observer() -> Result<(Self, OwnedFd), CoreError> {
            let handle = Self::dlopen_libbinder()?;
            let (lib, vt, am_class, service) = Self::open_inner(handle)?;
            let codes = resolve_tx_codes()?;
            let legacy = codes.api_mode == 2;

            // Create eventfd for callback → epoll bridge. Ownership stays in the
            // core for the observer lifetime; the consumer receives a dup below.
            let owned = unsafe {
                let raw = libc::eventfd(0, libc::EFD_NONBLOCK | libc::EFD_CLOEXEC);
                if raw < 0 {
                    return Err(CoreError::sys(*libc::__errno(), "eventfd"));
                }
                OwnedFd::from_raw_fd(raw)
            };

            // Define IProcessObserver class (we're the server)
            let obs_class = unsafe {
                (vt.class_define)(
                    OBS_DESCRIPTOR.as_ptr() as *const c_char,
                    obs_on_create,
                    obs_on_destroy,
                    obs_on_transact,
                )
            };
            if obs_class.is_null() {
                return Err(CoreError::binder(-1, "AIBinder_Class_define:Observer"));
            }

            // Instantiate our observer binder object
            let obs_binder = unsafe { (vt.new_binder)(obs_class, std::ptr::null_mut()) };
            if obs_binder.is_null() {
                return Err(CoreError::binder(-1, "AIBinder_new:Observer"));
            }
            unsafe { (vt.associate_class)(obs_binder, obs_class) };

            // Call registerProcessObserver(observer)
            let _ = transact_write(&vt, service.ptr, codes.observer_code, |w| {
                w.write_strong_binder(obs_binder)
            })?;

            // Consumer dup — made before publishing, so an error path drops the
            // owned fd without ever leaving a stale handle for the callback.
            let consumer = owned
                .try_clone()
                .map_err(|e| CoreError::sys(e.raw_os_error().unwrap_or(-1), "dup:observer"))?;

            // Publish fg_code and the core-owned eventfd for the callback
            OBS_FG_CODE.store(codes.fg_code, Ordering::Relaxed);
            *obs_eventfd_guard() = Some(owned);

            // Start binder thread pool — blocks forever in background thread
            unsafe { (vt.set_thread_pool_max)(0) };
            let join_fn = vt.join_thread_pool;
            std::thread::spawn(move || unsafe { join_fn() });

            let binder = Self {
                _lib: lib,
                vt,
                _class: am_class,
                service,
                tx_code: codes.query_code,
                legacy,
            };
            Ok((binder, consumer))
        }

        /// Open ActivityManager binder and register as the foreground process
        /// observer.
        ///
        /// The authoritative foreground PID is delivered in the callback; this
        /// is the low-noise foreground source. Two ROM variants are supported
        /// and selected automatically:
        ///
        /// - Stock: `IForegroundProcessObserver.onForegroundProcessChanged`
        ///   delivers a single `int pid`.
        /// - Custom ROMs that dropped that interface instead deliver `(int pid,
        ///   int uid, int fg)` through the repurposed
        ///   `IProcessObserver.onForegroundActivitiesChanged`; this registers
        ///   via `registerProcessObserver` and only signals on `fg != 0`.
        ///
        /// The callback stores the PID (readable via [`last_foreground_pid`])
        /// and signals the returned eventfd.
        ///
        /// Returns `(Self, OwnedFd)` where the eventfd is a dup of the core's
        /// callback fd. It becomes readable whenever a foreground process
        /// change fires. Same lifetime contract as
        /// [`ActivityManager::open_with_observer`] (C2): the core owns
        /// the eventfd and the callback only ever writes to that copy, so
        /// closing the returned dup never invalidates the notification path.
        pub fn open_with_fgproc_observer() -> Result<(Self, OwnedFd), CoreError> {
            let handle = Self::dlopen_libbinder()?;
            let (lib, vt, am_class, service) = Self::open_inner(handle)?;

            // Resolve the foreground-observer tx codes. Prefer the stock
            // IForegroundProcessObserver path; fall back to the custom
            // IProcessObserver pid-carrying form on ROMs that dropped it.
            // mode 0 = stock single-int callback, mode 1 = (pid, uid, fg).
            let (register_code, fgproc_code, mode, descriptor): (u32, u32, u32, &[u8]) =
                match crate::android::dex::resolve_fgproc_codes() {
                    Some((r, c)) => (r, c, 0, FGPROC_DESCRIPTOR),
                    None => match crate::android::dex::resolve_fgproc_codes_fallback() {
                        Some((r, c)) => (r, c, 1, OBS_DESCRIPTOR),
                        None => {
                            return Err(CoreError::binder(
                                -1,
                                "tx_code_resolution:fgproc_dex_parse_failed",
                            ));
                        }
                    },
                };

            // Create eventfd for callback → epoll bridge. Ownership stays in the
            // core for the observer lifetime; the consumer receives a dup below.
            let owned = unsafe {
                let raw = libc::eventfd(0, libc::EFD_NONBLOCK | libc::EFD_CLOEXEC);
                if raw < 0 {
                    return Err(CoreError::sys(*libc::__errno(), "eventfd"));
                }
                OwnedFd::from_raw_fd(raw)
            };

            // Define our observer class (we're the server). The descriptor must
            // match whichever interface we actually register as.
            let obs_class = unsafe {
                (vt.class_define)(
                    descriptor.as_ptr() as *const c_char,
                    fgproc_on_create,
                    fgproc_on_destroy,
                    fgproc_on_transact,
                )
            };
            if obs_class.is_null() {
                return Err(CoreError::binder(
                    -1,
                    "AIBinder_Class_define:FGProcessObserver",
                ));
            }

            // Instantiate our observer binder object
            let obs_binder = unsafe { (vt.new_binder)(obs_class, std::ptr::null_mut()) };
            if obs_binder.is_null() {
                return Err(CoreError::binder(-1, "AIBinder_new:FGProcessObserver"));
            }
            unsafe { (vt.associate_class)(obs_binder, obs_class) };

            // Call registerForegroundProcessObserver(observer) or the fallback
            // registerProcessObserver(observer) depending on resolved mode.
            let _ = transact_write(&vt, service.ptr, register_code, |w| {
                w.write_strong_binder(obs_binder)
            })?;

            // Consumer dup — made before publishing, so an error path drops the
            // owned fd without ever leaving a stale handle for the callback.
            let consumer = owned.try_clone().map_err(|e| {
                CoreError::sys(e.raw_os_error().unwrap_or(-1), "dup:fgproc_observer")
            })?;

            // Publish reader fn, mode, fg code, pid base, and the core-owned
            // eventfd for the callback. Reader and mode are published first so
            // the callback never sees a matching code with an unset reader or
            // mode (C2-adjacent init order).
            FGPROC_READ_I32.store(vt.read_int32 as usize, Ordering::Relaxed);
            FGPROC_IPROC_MODE.store(mode, Ordering::Relaxed);
            FGPROC_FG_CODE.store(fgproc_code, Ordering::Relaxed);
            FGPROC_PID.store(0, Ordering::Relaxed);
            *fgproc_eventfd_guard() = Some(owned);

            // Start binder thread pool — blocks forever in background thread
            unsafe { (vt.set_thread_pool_max)(0) };
            let join_fn = vt.join_thread_pool;
            std::thread::spawn(move || unsafe { join_fn() });

            let binder = Self {
                _lib: lib,
                vt,
                _class: am_class,
                service,
                tx_code: 0,
                legacy: false,
            };
            Ok((binder, consumer))
        }

        fn do_transact(&self) -> Result<OwnedParcel, CoreError> {
            transact_write(&self.vt, self.service.ptr, self.tx_code, |_| Ok(()))
        }

        /// The focused root task's `(taskId, topActivity package)` from a single
        /// txn-31 transaction. Outer `None` = no focused root task (or legacy
        /// API 29, where the reply is `StackInfo` and carries no taskId); inner
        /// `None` = task known but no package in `childTaskNames`. Both values
        /// come from the same parcel, so the registration key and the report
        /// tag can never diverge.
        pub fn get_focused_task(&self) -> Result<Option<(i32, Option<String>)>, CoreError> {
            if self.legacy {
                // StackInfo has no taskId — report None rather than a wrong id.
                return Ok(None);
            }
            let out = self.do_transact()?;
            let r = ParcelReader {
                vt: &self.vt,
                parcel: &out,
            };
            let ex = r.read_i32()?;
            if ex != EX_NONE {
                return Err(CoreError::binder(ex, "getFocusedTask:exception"));
            }
            let present = r.read_i32()?;
            if present == 0 {
                return Ok(None);
            }
            Ok(Some(parse_root_task_info_task(&r)?))
        }

        /// The `topActivity` package of the focused root task (legacy API 29
        /// builds use `StackInfo` and still resolve the package). Thin wrapper
        /// over [`ActivityManager::get_focused_task`].
        pub fn get_focused_package(&self) -> Result<Option<String>, CoreError> {
            if self.legacy {
                let out = self.do_transact()?;
                let r = ParcelReader {
                    vt: &self.vt,
                    parcel: &out,
                };
                let ex = r.read_i32()?;
                if ex != EX_NONE {
                    return Err(CoreError::binder(ex, "getFocusedTask:exception"));
                }
                let present = r.read_i32()?;
                if present == 0 {
                    return Ok(None);
                }
                return parse_stack_info_body(&r);
            }
            Ok(self.get_focused_task()?.and_then(|(_, pkg)| pkg))
        }

        /// The `taskId` of the currently focused root task. Thin wrapper over
        /// [`ActivityManager::get_focused_task`]; returns `None` when there
        /// is no focused root task or on legacy API 29 builds.
        pub fn get_focused_task_id(&self) -> Result<Option<i32>, CoreError> {
            Ok(self.get_focused_task()?.map(|(task_id, _)| task_id))
        }
    }

    // ── DisplayManager ─────────────────────────────────────────────────

    const DISPLAY_SERVICE: &[u8] = b"display\0";
    const DISPLAY_DESCRIPTOR: &[u8] = b"android.hardware.display.IDisplayManager\0";
    const CALLBACK_DESCRIPTOR: &[u8] = b"android.hardware.display.IDisplayManagerCallback\0";
    const POWER_SERVICE: &[u8] = b"power\0";
    const POWER_DESCRIPTOR: &[u8] = b"android.os.IPowerManager\0";

    const TX_DISPLAY_REGISTER_CALLBACK: u32 = 4;

    // Core owns the callback eventfd; the consumer gets a dup and may close it
    // freely. Same lifetime discipline as the ActivityManager observer (C2).
    static DISP_EVENTFD: Mutex<Option<OwnedFd>> = Mutex::new(None);

    fn disp_eventfd_guard() -> std::sync::MutexGuard<'static, Option<OwnedFd>> {
        DISP_EVENTFD.lock().unwrap_or_else(|p| p.into_inner())
    }

    unsafe extern "C" fn disp_cb_on_create(_: *mut c_void) -> *mut c_void {
        std::ptr::null_mut()
    }
    unsafe extern "C" fn disp_cb_on_destroy(_: *mut c_void) {}
    unsafe extern "C" fn disp_cb_on_transact(
        _: *mut AIBinder,
        code: u32,
        _: *const AParcel,
        _: *mut AParcel,
    ) -> BinderStatus {
        if code == 1 {
            if let Some(fd) = disp_eventfd_guard().as_ref() {
                let val: u64 = 1;
                unsafe { libc::write(fd.as_raw_fd(), &val as *const u64 as *const c_void, 8) };
            }
        }
        STATUS_OK
    }
    // Client-only classes: the NDK requires a class on ANY binder that
    // participates in a transaction (AIBinder_prepareTransaction fails with
    // STATUS_INVALID_OPERATION when getClass() == null) and uses the class
    // descriptor to write the interface token. These stubs are never invoked
    // for a client (remote) binder — onCreate/onTransact only fire on local
    // AIBinder_new instances — so they mirror the ActivityManager client
    // pattern exactly.
    unsafe extern "C" fn disp_client_on_create(_: *mut c_void) -> *mut c_void {
        std::ptr::null_mut()
    }
    unsafe extern "C" fn disp_client_on_destroy(_: *mut c_void) {}
    unsafe extern "C" fn disp_client_on_transact(
        _: *mut AIBinder,
        _: u32,
        _: *const AParcel,
        _: *mut AParcel,
    ) -> BinderStatus {
        STATUS_UNKNOWN_TRANSACTION
    }
    /// Snapshot of the active display state used for FPS normalization.
    ///
    /// Populated from `IDisplayManager.getDisplayInfo` (tx resolved from the
    /// installed ROM's framework.jar). The parcel layout is Android-version
    /// specific; this parse targets Android 14 and must be validated on-device
    /// before consumers rely on the values for fps/R normalization.
    #[derive(Clone, Copy, Debug, PartialEq, Default)]
    pub struct DisplayInfo {
        /// Active display mode id (`DisplayInfo.modeId`).
        pub active_mode_id: i32,
        /// Refresh rate of the active mode, in Hz.
        pub vsync_rate: f32,
        /// Highest refresh rate across supported modes, in Hz.
        pub peak_refresh_rate: f32,
        /// `DisplayInfo.renderFrameRate` (Android 13+), in Hz.
        pub render_frame_rate: f32,
        /// Interactive state reported by the power service.
        pub is_interactive: bool,
    }

    pub struct DisplayManager {
        _lib: DlHandle,
        vt: Vtable,
        display: Option<OwnedBinder>,
        display_info_tx: Option<u32>,
        power: Option<OwnedBinder>,
        is_interactive_tx: u32,
    }
    unsafe impl Send for DisplayManager {}

    impl DisplayManager {
        pub fn open_with_callback() -> Result<(Self, crate::fd::Fd), CoreError> {
            let handle = unsafe {
                libc::dlopen(
                    LIBBINDER_PATH.as_ptr() as *const c_char,
                    libc::RTLD_NOW | libc::RTLD_LOCAL,
                )
            };
            if handle.is_null() {
                return Err(CoreError::binder(-1, "dlopen:libbinder_ndk.so"));
            }
            let lib = DlHandle;
            let vt = load_vtable(handle)?;

            // Blocking eventfd (no EFD_NONBLOCK) — callback writes, caller's
            // read_u64_blocking() waits. The core owns it for the callback's
            // lifetime; the consumer receives a dup below (C2).
            let owned = unsafe {
                let raw = libc::eventfd(0, libc::EFD_CLOEXEC);
                if raw < 0 {
                    return Err(CoreError::sys(*libc::__errno(), "eventfd"));
                }
                OwnedFd::from_raw_fd(raw)
            };

            // Get display service. A client-only binder still needs a class
            // (AIBinder_prepareTransaction requires getClass() != null and
            // writes the interface token from the class descriptor).
            let raw_display =
                unsafe { (vt.get_service)(DISPLAY_SERVICE.as_ptr() as *const c_char) };
            if raw_display.is_null() {
                return Err(CoreError::binder(-1, "AServiceManager_getService:display"));
            }
            let display_class = unsafe {
                (vt.class_define)(
                    DISPLAY_DESCRIPTOR.as_ptr() as *const c_char,
                    disp_client_on_create,
                    disp_client_on_destroy,
                    disp_client_on_transact,
                )
            };
            if display_class.is_null() {
                return Err(CoreError::binder(
                    -1,
                    "AIBinder_Class_define:IDisplayManager",
                ));
            }
            unsafe { (vt.associate_class)(raw_display, display_class) };
            let display = OwnedBinder {
                ptr: raw_display,
                dec_strong: vt.dec_strong,
            };

            // Define IDisplayManagerCallback (we're the server receiving callbacks)
            let cb_class = unsafe {
                (vt.class_define)(
                    CALLBACK_DESCRIPTOR.as_ptr() as *const c_char,
                    disp_cb_on_create,
                    disp_cb_on_destroy,
                    disp_cb_on_transact,
                )
            };
            if cb_class.is_null() {
                return Err(CoreError::binder(
                    -1,
                    "AIBinder_Class_define:DisplayCallback",
                ));
            }

            let cb_binder = unsafe { (vt.new_binder)(cb_class, std::ptr::null_mut()) };
            if cb_binder.is_null() {
                return Err(CoreError::binder(-1, "AIBinder_new:DisplayCallback"));
            }

            // registerCallback(callback) — tx 4
            let _ = transact_write(&vt, display.ptr, TX_DISPLAY_REGISTER_CALLBACK, |w| {
                w.write_strong_binder(cb_binder)
            })?;

            // Optional: grab power service for is_interactive(). Same client
            // class requirement as the display binder above.
            let power_class = unsafe {
                (vt.class_define)(
                    POWER_DESCRIPTOR.as_ptr() as *const c_char,
                    disp_client_on_create,
                    disp_client_on_destroy,
                    disp_client_on_transact,
                )
            };
            let power = if power_class.is_null() {
                None
            } else {
                let raw = unsafe { (vt.get_service)(POWER_SERVICE.as_ptr() as *const c_char) };
                if raw.is_null() {
                    None
                } else {
                    unsafe { (vt.associate_class)(raw, power_class) };
                    Some(OwnedBinder {
                        ptr: raw,
                        dec_strong: vt.dec_strong,
                    })
                }
            };

            // Resolve isInteractive tx code from DEX at open time
            let is_interactive_tx = crate::android::dex::resolve_is_interactive_tx()
                .ok_or_else(|| CoreError::binder(-1, "dex:TRANSACTION_isInteractive not found"))?;

            // Resolve getDisplayInfo tx from DEX (best-effort, optional). ROMs
            // that drop the field skip the info() API rather than failing open.
            let display_info_tx = crate::android::dex::resolve_display_info_tx();

            // Consumer dup — made before publishing, so an error path drops the
            // owned fd without ever leaving a stale handle for the callback.
            let efd_owned = owned
                .try_clone()
                .map_err(|e| CoreError::sys(e.raw_os_error().unwrap_or(-1), "dup:display"))
                .and_then(|dup| unsafe {
                    crate::fd::Fd::from_owned_raw_fd(dup.into_raw_fd(), "display.efd")
                        .map_err(|_| CoreError::binder(-1, "Fd::from_owned_raw_fd:display.efd"))
                })?;

            // Publish the core-owned eventfd for the callback
            *disp_eventfd_guard() = Some(owned);

            // Join binder thread pool so callbacks can fire
            unsafe { (vt.set_thread_pool_max)(0) };
            let join_fn = vt.join_thread_pool;
            std::thread::spawn(move || unsafe { join_fn() });

            Ok((
                Self {
                    _lib: lib,
                    vt,
                    display: Some(display),
                    display_info_tx,
                    power,
                    is_interactive_tx,
                },
                efd_owned,
            ))
        }

        pub fn is_interactive(&self) -> Result<bool, CoreError> {
            let power = self
                .power
                .as_ref()
                .ok_or_else(|| CoreError::binder(-1, "power:unavailable"))?;
            let out = transact_write(&self.vt, power.ptr, self.is_interactive_tx, |_| Ok(()))?;
            let r = ParcelReader {
                vt: &self.vt,
                parcel: &out,
            };
            let ex = r.read_i32()?;
            if ex != EX_NONE {
                return Err(CoreError::binder(ex, "isInteractive:exception"));
            }
            r.read_bool()
        }

        /// Query the display's current render state for FPS normalization.
        ///
        /// Transacts `IDisplayManager.getDisplayInfo(display_id)` and decodes
        /// the reply parcel (Android 14 `android.view.DisplayInfo` layout):
        /// active mode id, active-mode refresh rate, peak refresh rate across
        /// supported modes, and `renderFrameRate`, plus the interactive state
        /// from the power service.
        ///
        /// # Best-effort / on-device caveat
        /// The parcel walk below follows the Android 14 field ordering. ROMs or
        /// future Android releases that reorder `DisplayInfo` fields will fail
        /// the walk with a `CoreError` (never garbage) — tune
        /// `parse_display_info` against the installed framework.jar, which is
        /// why the tx code is resolved at open time via DEX.
        pub fn info(&self, display_id: i32) -> Result<DisplayInfo, CoreError> {
            let display = self
                .display
                .as_ref()
                .ok_or_else(|| CoreError::binder(-1, "display:unavailable"))?;
            let tx = self
                .display_info_tx
                .ok_or_else(|| CoreError::binder(-1, "display_info:tx unavailable"))?;
            let out = transact_write(&self.vt, display.ptr, tx, |w| {
                w.write_i32(display_id)
            })?;
            let r = ParcelReader {
                vt: &self.vt,
                parcel: &out,
            };

            let ex = r.read_i32()?;
            if ex != EX_NONE {
                return Err(CoreError::binder(ex, "getDisplayInfo:exception"));
            }
            // The reply parcel carries the parcelable off the framework's own
            // writeToParcel, which writes no class-name header for a top-level
            // reply value in native code — it is the raw DisplayInfo fields.
            // The first field read must be layerStack. If a future framework
            // writes a class name first, the first read becomes a string length
            // (small positive int) and `layer_stack` is a plausible-looking
            // wrong value; guard by sanity-checking later fields instead.
            let parsed = parse_display_info(&r)?;

            let interactive = self.is_interactive().unwrap_or(false);
            Ok(DisplayInfo {
                active_mode_id: parsed.active_mode_id,
                vsync_rate: parsed.vsync_rate,
                peak_refresh_rate: parsed.peak_refresh_rate,
                render_frame_rate: parsed.render_frame_rate,
                is_interactive: interactive,
            })
        }
    }

    // ── FpsListener (task FPS callback) ───────────────────────────────────────

    const WINDOW_SERVICE: &[u8] = b"window\0";
    const WM_DESCRIPTOR: &[u8] = b"android.view.IWindowManager\0";
    const FPS_DESCRIPTOR: &[u8] = b"android.window.ITaskFpsCallback\0";
    // The last reported FPS (bit pattern of the f32) is published before the
    // eventfd is signalled, so the consumer never reads a stale value. The wake
    // eventfd is per-instance (same pattern as TaskStackListener): it is handed
    // to AIBinder_new as the callback binder's userdata, so a second
    // FpsListener can never rewire an earlier registration's wake into its own
    // fd (the callback resolves its own binder's fd via AIBinder_getUserData).
    static FPS_VALUE: AtomicU32 = AtomicU32::new(0);
    // Distinct from FPS_VALUE's bits: `0.0f32` has bit pattern 0, so a "not
    // seen" sentinel of 0 would misread a genuine idle (0-FPS) report as "no
    // report yet" — swallowing the sample and (downstream) leaving the first-
    // report-after-swap drop armed. The seen flag disambiguates.
    static FPS_SEEN: AtomicBool = AtomicBool::new(false);
    static FPS_CODE: AtomicU32 = AtomicU32::new(0);
    static FPS_READ_I32: AtomicUsize = AtomicUsize::new(0);

    // No-op callbacks for the client-only IWindowManager class (we never serve
    // transactions on the `window` binder — the class exists only to satisfy
    // AIBinder_prepareTransaction's remote-transaction contract).
    unsafe extern "C" fn wm_on_create(_: *mut c_void) -> *mut c_void {
        std::ptr::null_mut()
    }
    unsafe extern "C" fn wm_on_destroy(_: *mut c_void) {}
    unsafe extern "C" fn wm_on_transact(
        _: *mut AIBinder,
        _: u32,
        _: *const AParcel,
        _: *mut AParcel,
    ) -> BinderStatus {
        STATUS_OK
    }

    // The per-instance wake eventfd is this callback binder's userdata, so
    // onCreate must return the args passed to AIBinder_new — AIBinder_getUserData
    // returns exactly that value — and onDestroy must reclaim the box (same
    // pattern as TaskStackListener). Returning null here would make
    // AIBinder_getUserData return null, silently breaking the FPS wake.
    unsafe extern "C" fn fps_on_create(userdata: *mut c_void) -> *mut c_void {
        userdata
    }
    unsafe extern "C" fn fps_on_destroy(userdata: *mut c_void) {
        if !userdata.is_null() {
            unsafe { drop(Box::from_raw(userdata as *mut OwnedFd)) };
        }
    }
    unsafe extern "C" fn fps_on_transact(
        binder: *mut AIBinder,
        code: u32,
        in_parcel: *const AParcel,
        _: *mut AParcel,
    ) -> BinderStatus {
        if code != FPS_CODE.load(Ordering::Relaxed) {
            return STATUS_UNKNOWN_TRANSACTION;
        }
        // Reader is published non-zero before the code, so a matching code is
        // never paired with an unset reader.
        let read_addr = FPS_READ_I32.load(Ordering::Relaxed);
        if read_addr != 0 {
            let read_fn: unsafe extern "C" fn(*const AParcel, *mut i32) -> BinderStatus =
                unsafe { std::mem::transmute(read_addr) };
            let mut bits: i32 = 0;
            if unsafe { read_fn(in_parcel, &mut bits) } == STATUS_OK {
                // Publish the value before signalling so the consumer always
                // sees the value that triggered the wakeup. Non-finite/negative
                // reports are normalized to 0.0 first (L5) — the stream must
                // never carry "NaN"/"inf".
                FPS_VALUE.store(sanitize_fps(bits as u32), Ordering::Relaxed);
                FPS_SEEN.store(true, Ordering::Release);
                // Per-instance wake: the eventfd is this callback binder's
                // userdata (see FpsListener::open), so two FpsListeners never
                // cross-wire their wakes. A missing slot means the process-wide
                // AIBinder_getUserData symbol has not been cached — drop the
                // signal rather than risk a stale fd.
                let get_user_data = GET_USER_DATA.lock().unwrap_or_else(|p| p.into_inner());
                if let Some(get_user_data) = *get_user_data {
                    let userdata = unsafe { get_user_data(binder) };
                    if !userdata.is_null() {
                        let efd = userdata as *mut OwnedFd;
                        let val: u64 = 1;
                        unsafe {
                            libc::write((*efd).as_raw_fd(), &val as *const u64 as *const c_void, 8)
                        };
                    }
                }
            }
        }
        STATUS_OK
    }

    /// Push-based per-task FPS listener registered with `WindowManager`.
    ///
    /// Uses `IWindowManager.registerTaskFpsCallback(taskId, callback)`; the
    /// daemon hosts the `ITaskFpsCallback` server object and receives
    /// `onFpsReported(float)` one-way transactions from the `FpsReporter` at
    /// most every ~500 ms.
    ///
    /// The registering UID must hold `ACCESS_FPS_COUNTER` (signature|privileged)
    /// — this process typically runs as shell (uid 2000) via `su`.
    ///
    /// Returns `(Self, OwnedFd)` where the eventfd is a dup of the core's
    /// callback fd. It becomes readable whenever `onFpsReported` fires; call
    /// [`FpsListener::last_fps`] after the event to read the value.
    pub struct FpsListener {
        _lib: DlHandle,
        vt: Vtable,
        window: OwnedBinder,
        cb_binder: *mut AIBinder,
        _wm_class: *mut AIBinder_Class,
        register_code: u32,
        unregister_code: u32,
        task_id: i32,
    }
    unsafe impl Send for FpsListener {}

    impl FpsListener {
        /// Open WindowManager and define the `ITaskFpsCallback` server object.
        ///
        /// Resolves the three tx codes from DEX. Does **not** register a task
        /// yet — call [`FpsListener::register`] once a taskId is known. Starts
        /// the binder thread pool so `onFpsReported` can fire.
        pub fn open() -> Result<(Self, OwnedFd), CoreError> {
            let handle = unsafe {
                libc::dlopen(
                    LIBBINDER_PATH.as_ptr() as *const c_char,
                    libc::RTLD_NOW | libc::RTLD_LOCAL,
                )
            };
            if handle.is_null() {
                return Err(CoreError::binder(-1, "dlopen:libbinder_ndk.so"));
            }
            let lib = DlHandle;
            let vt = load_vtable(handle)?;

            let (register_code, unregister_code, on_fps_code) =
                crate::android::dex::resolve_fps_codes().ok_or_else(|| {
                    CoreError::binder(-1, "dex:TRANSACTION_registerTaskFpsCallback not found")
                })?;

            let window = {
                let raw = unsafe { (vt.get_service)(WINDOW_SERVICE.as_ptr() as *const c_char) };
                if raw.is_null() {
                    return Err(CoreError::binder(-1, "AServiceManager_getService:window"));
                }
                OwnedBinder {
                    ptr: raw,
                    dec_strong: vt.dec_strong,
                }
            };

            // Remote transactions require a class on the binder (same
            // AIBinder_prepareTransaction contract as the AM service above).
            let wm_class = unsafe {
                (vt.class_define)(
                    WM_DESCRIPTOR.as_ptr() as *const c_char,
                    wm_on_create,
                    wm_on_destroy,
                    wm_on_transact,
                )
            };
            if wm_class.is_null() {
                return Err(CoreError::binder(
                    -1,
                    "AIBinder_Class_define:IWindowManager",
                ));
            }
            unsafe { (vt.associate_class)(window.ptr, wm_class) };

            let cb_class = unsafe {
                (vt.class_define)(
                    FPS_DESCRIPTOR.as_ptr() as *const c_char,
                    fps_on_create,
                    fps_on_destroy,
                    fps_on_transact,
                )
            };
            if cb_class.is_null() {
                return Err(CoreError::binder(
                    -1,
                    "AIBinder_Class_define:ITaskFpsCallback",
                ));
            }

            // Nonblocking eventfd — the callback only ever writes to it (an
            // eventfd write never blocks), while epoll-based consumers register
            // it edge-triggered and drain to EAGAIN, so a blocking fd would
            // wedge the consumer's drain loop. Matches the obs/fgproc observer
            // eventfds. Each instance owns its own fd; it is handed to the
            // callback binder as userdata (per-instance routing, no process-wide
            // static) and the consumer receives a dup below (C2).
            let owned = unsafe {
                let raw = libc::eventfd(0, libc::EFD_NONBLOCK | libc::EFD_CLOEXEC);
                if raw < 0 {
                    return Err(CoreError::sys(*libc::__errno(), "eventfd"));
                }
                OwnedFd::from_raw_fd(raw)
            };

            let consumer = owned
                .try_clone()
                .map_err(|e| CoreError::sys(e.raw_os_error().unwrap_or(-1), "dup:fps"))?;

            let userdata = Box::into_raw(Box::new(owned)) as *mut c_void;
            let cb_binder = unsafe { (vt.new_binder)(cb_class, userdata) };
            if cb_binder.is_null() {
                // Reclaim the userdata box handed to AIBinder_new before bailing.
                unsafe { drop(Box::from_raw(userdata as *mut OwnedFd)) };
                return Err(CoreError::binder(-1, "AIBinder_new:ITaskFpsCallback"));
            }
            unsafe { (vt.associate_class)(cb_binder, cb_class) };

            // Publish the reader and code before the eventfd registration; a
            // matching code is never paired with an unset reader (C2-adjacent).
            FPS_READ_I32.store(vt.read_int32 as usize, Ordering::Relaxed);
            FPS_SEEN.store(false, Ordering::Relaxed);
            FPS_CODE.store(on_fps_code, Ordering::Relaxed);
            FPS_VALUE.store(0, Ordering::Relaxed);
            // The callback resolves AIBinder_getUserData from this vtable; the
            // symbol address is process-wide, so a cached static is safe.
            *GET_USER_DATA.lock().unwrap_or_else(|p| p.into_inner()) = Some(vt.get_user_data);

            unsafe { (vt.set_thread_pool_max)(0) };
            let join_fn = vt.join_thread_pool;
            std::thread::spawn(move || unsafe { join_fn() });

            Ok((
                Self {
                    _lib: lib,
                    vt,
                    window,
                    cb_binder,
                    _wm_class: wm_class,
                    register_code,
                    unregister_code,
                    task_id: -1,
                },
                consumer,
            ))
        }

        /// Register the callback for `task_id`. If a task was already
        /// registered, it is unregistered first (WindowManager tracks one task
        /// per callback binder).
        pub fn register(&mut self, task_id: i32) -> Result<(), CoreError> {
            if self.task_id == task_id {
                return Ok(());
            }
            if self.task_id >= 0 {
                let _ = self.unregister();
            }

            let _ = transact_write(&self.vt, self.window.ptr, self.register_code, |w| {
                w.write_i32(task_id)?;
                w.write_strong_binder(self.cb_binder)
            })?;
            self.task_id = task_id;
            Ok(())
        }

        /// Unregister the callback from WindowManager. No-op if nothing is
        /// registered.
        pub fn unregister(&mut self) -> Result<(), CoreError> {
            if self.task_id < 0 {
                return Ok(());
            }
            let _ = transact_write(&self.vt, self.window.ptr, self.unregister_code, |w| {
                w.write_strong_binder(self.cb_binder)
            })?;
            self.task_id = -1;
            Ok(())
        }

        /// The most recent `onFpsReported` value (f32), or `None` if no report
        /// has arrived yet. Safe to call at any time; the bit pattern is
        /// published atomically. A genuine 0.0 (idle) report reads as `Some`,
        /// distinguished from the no-report state by `FPS_SEEN`.
        pub fn last_fps(&self) -> Option<f32> {
            fps_from_state(
                FPS_SEEN.load(Ordering::Acquire),
                FPS_VALUE.load(Ordering::Relaxed),
            )
        }

        /// The taskId currently registered, or `None` if none.
        pub fn task_id(&self) -> Option<i32> {
            (self.task_id >= 0).then_some(self.task_id)
        }
    }

    impl Drop for FpsListener {
        /// Best-effort deregistration from WindowManager so a dropped listener
        /// does not leave the framework delivering `onFpsReported` forever. The
        /// callback binder's local strong ref is intentionally NOT released:
        /// keeping it alive guarantees the per-binder userdata (the OwnedFd)
        /// can never be reclaimed by `on_destroy` while a callback is in
        /// flight, and the framework-side registration has been dropped by the
        /// unregister, so no stale transaction targets this instance.
        fn drop(&mut self) {
            let _ = self.unregister();
        }
    }

    /// Disambiguate "no report yet" from a genuine 0.0 (idle) report: `seen`
    /// tracks whether the callback published a value; `bits` is that value's
    /// bit pattern. `0.0f32` has bits 0, so the bits alone cannot tell a real
    /// idle sample from an unset slot.
    fn fps_from_state(seen: bool, bits: u32) -> Option<f32> {
        if seen {
            Some(f32::from_bits(bits))
        } else {
            None
        }
    }

    /// Normalize an `onFpsReported` bit pattern for the stream. Real FPS is
    /// non-negative and finite; NaN/±Inf (garbage or corruption) and negative
    /// values collapse to 0.0 (idle) so the value stream never shows "NaN" or
    /// "inf".
    fn sanitize_fps(bits: u32) -> u32 {
        let v = f32::from_bits(bits);
        if v.is_finite() && v >= 0.0 {
            bits
        } else {
            0.0f32.to_bits()
        }
    }

    // ── TaskStackListener (task-stack change wake-up) ────────────────────────

    const TASK_SERVICE: &[u8] = b"activity_task\0";
    const ATM_DESCRIPTOR: &[u8] = b"android.app.IActivityTaskManager\0";
    const TASK_STACK_DESCRIPTOR: &[u8] = b"android.app.ITaskStackListener\0";

    // No-op callbacks for the client-only IActivityTaskManager class (we never
    // serve transactions on the `activity_task` binder — the class exists only
    // to satisfy AIBinder_prepareTransaction's remote-transaction contract).
    unsafe extern "C" fn atm_on_create(_: *mut c_void) -> *mut c_void {
        std::ptr::null_mut()
    }
    unsafe extern "C" fn atm_on_destroy(_: *mut c_void) {}
    unsafe extern "C" fn atm_on_transact(
        _: *mut AIBinder,
        _: u32,
        _: *const AParcel,
        _: *mut AParcel,
    ) -> BinderStatus {
        STATUS_OK
    }

    // Pure wake-up handler: any ITaskStackListener callback
    // (onTaskStackChanged, onTaskMovedToFront, …) just signals the eventfd.
    // The callback arguments are deliberately NOT parsed — the authoritative
    // (taskId, pkg) comes from re-querying getFocusedRootTaskInfo (txn 31) on
    // the event, so we never depend on a parcel layout (RunningTaskInfo places
    // taskId near the parcel tail).
    //
    // The wake eventfd is per-instance: the daemon hosts two listeners (the fg
    // task source and the fps channel), each with its own eventfd. It is handed
    // to AIBinder_new as the binder's userdata, so on_destroy must reclaim it.
    // No process-wide static — a shared fd would deliver every instance's
    // wake to whichever listener opened last.
    //
    // The callback resolves the per-binder eventfd through AIBinder_getUserData.
    // The symbol address is process-wide, so it is cached once in a static.
    static GET_USER_DATA: std::sync::Mutex<
        Option<unsafe extern "C" fn(*const AIBinder) -> *mut c_void>,
    > = std::sync::Mutex::new(None);

    unsafe extern "C" fn task_stack_on_create(userdata: *mut c_void) -> *mut c_void {
        userdata
    }
    unsafe extern "C" fn task_stack_on_destroy(userdata: *mut c_void) {
        if !userdata.is_null() {
            unsafe { drop(Box::from_raw(userdata as *mut OwnedFd)) };
        }
    }
    unsafe extern "C" fn task_stack_on_transact(
        binder: *mut AIBinder,
        _code: u32,
        _in_parcel: *const AParcel,
        _reply: *mut AParcel,
    ) -> BinderStatus {
        let get_user_data = GET_USER_DATA.lock().unwrap_or_else(|p| p.into_inner());
        if let Some(get_user_data) = *get_user_data {
            let userdata = unsafe { get_user_data(binder) };
            if !userdata.is_null() {
                let efd = userdata as *mut OwnedFd;
                let val: u64 = 1;
                unsafe { libc::write((*efd).as_raw_fd(), &val as *const u64 as *const c_void, 8) };
            }
        }
        STATUS_OK
    }

    /// Push-based task-stack change listener registered with
    /// `IActivityTaskManager`.
    ///
    /// Uses `IActivityTaskManager.registerTaskStackListener(listener)`; the
    /// daemon hosts the `ITaskStackListener` server object. The callback is a
    /// pure wake-up: on any task-stack change it signals the eventfd and
    /// parses nothing. Consumers re-query `getFocusedRootTaskInfo` (txn 31) on
    /// the event for the authoritative `(taskId, pkg)`.
    ///
    /// This target's ROM exposes the legacy `ITaskStackListener` /
    /// `registerTaskStackListener` pair; the newer `ITaskChangeListener` /
    /// `registerTaskChangeListener` interface is absent.
    ///
    /// The registering UID must hold `MANAGE_ACTIVITY_TASKS` /
    /// `MANAGE_ACTIVITY_STACKS` — the same gate as txn 31, which root passes
    /// empirically on the target ROM.
    ///
    /// Returns `(Self, OwnedFd)` where the eventfd is a dup of the core's
    /// callback fd. It becomes readable on any task-stack change.
    pub struct TaskStackListener {
        _lib: DlHandle,
        vt: Vtable,
        service: OwnedBinder,
        cb_binder: *mut AIBinder,
        _atm_class: *mut AIBinder_Class,
        register_code: u32,
        unregister_code: u32,
    }
    unsafe impl Send for TaskStackListener {}

    impl TaskStackListener {
        /// Open `activity_task`, define the `ITaskStackListener` server object,
        /// and start the binder thread pool. Does **not** register yet — call
        /// [`TaskStackListener::register`] once consumers are active.
        pub fn open() -> Result<(Self, OwnedFd), CoreError> {
            let handle = unsafe {
                libc::dlopen(
                    LIBBINDER_PATH.as_ptr() as *const c_char,
                    libc::RTLD_NOW | libc::RTLD_LOCAL,
                )
            };
            if handle.is_null() {
                return Err(CoreError::binder(-1, "dlopen:libbinder_ndk.so"));
            }
            let lib = DlHandle;
            let vt = load_vtable(handle)?;

            let (register_code, unregister_code) = crate::android::dex::resolve_task_stack_codes()
                .ok_or_else(|| {
                    CoreError::binder(-1, "dex:TRANSACTION_registerTaskStackListener not found")
                })?;

            let service = {
                let raw = unsafe { (vt.get_service)(TASK_SERVICE.as_ptr() as *const c_char) };
                if raw.is_null() {
                    return Err(CoreError::binder(
                        -1,
                        "AServiceManager_getService:activity_task",
                    ));
                }
                OwnedBinder {
                    ptr: raw,
                    dec_strong: vt.dec_strong,
                }
            };

            // Remote transactions require a class on the binder (same
            // AIBinder_prepareTransaction contract as the other services).
            let atm_class = unsafe {
                (vt.class_define)(
                    ATM_DESCRIPTOR.as_ptr() as *const c_char,
                    atm_on_create,
                    atm_on_destroy,
                    atm_on_transact,
                )
            };
            if atm_class.is_null() {
                return Err(CoreError::binder(
                    -1,
                    "AIBinder_Class_define:IActivityTaskManager",
                ));
            }
            unsafe { (vt.associate_class)(service.ptr, atm_class) };

            let cb_class = unsafe {
                (vt.class_define)(
                    TASK_STACK_DESCRIPTOR.as_ptr() as *const c_char,
                    task_stack_on_create,
                    task_stack_on_destroy,
                    task_stack_on_transact,
                )
            };
            if cb_class.is_null() {
                return Err(CoreError::binder(
                    -1,
                    "AIBinder_Class_define:ITaskStackListener",
                ));
            }

            // Blocking eventfd — callback writes, consumer waits/reads. Each
            // instance owns its own fd; it is handed to the callback binder as
            // userdata (per-instance routing, no process-wide static) and the
            // consumer receives a dup below (C2).
            let owned = unsafe {
                let raw = libc::eventfd(0, libc::EFD_CLOEXEC);
                if raw < 0 {
                    return Err(CoreError::sys(*libc::__errno(), "eventfd"));
                }
                OwnedFd::from_raw_fd(raw)
            };

            let consumer = owned
                .try_clone()
                .map_err(|e| CoreError::sys(e.raw_os_error().unwrap_or(-1), "dup:task_stack"))?;

            let userdata = Box::into_raw(Box::new(owned)) as *mut c_void;
            let cb_binder = unsafe { (vt.new_binder)(cb_class, userdata) };
            if cb_binder.is_null() {
                // Reclaim the userdata box handed to AIBinder_new before bailing.
                unsafe { drop(Box::from_raw(userdata as *mut OwnedFd)) };
                return Err(CoreError::binder(-1, "AIBinder_new:ITaskStackListener"));
            }
            unsafe { (vt.associate_class)(cb_binder, cb_class) };

            // The callback resolves AIBinder_getUserData from this vtable; the
            // symbol address is process-wide, so a cached static is safe.
            *GET_USER_DATA.lock().unwrap_or_else(|p| p.into_inner()) = Some(vt.get_user_data);

            unsafe { (vt.set_thread_pool_max)(0) };
            let join_fn = vt.join_thread_pool;
            std::thread::spawn(move || unsafe { join_fn() });

            Ok((
                Self {
                    _lib: lib,
                    vt,
                    service,
                    cb_binder,
                    _atm_class: atm_class,
                    register_code,
                    unregister_code,
                },
                consumer,
            ))
        }

        /// Register the task-stack listener with `activity_task` (one listener
        /// receives all task-stack events). Idempotent at the framework level;
        /// callers should register once and keep the object alive.
        pub fn register(&self) -> Result<(), CoreError> {
            let _ = transact_write(&self.vt, self.service.ptr, self.register_code, |w| {
                w.write_strong_binder(self.cb_binder)
            })?;
            Ok(())
        }

        /// Unregister the task-stack listener from `activity_task`. No-op at
        /// the framework level if not registered; callers should unregister
        /// before dropping the object.
        pub fn unregister(&self) -> Result<(), CoreError> {
            let _ = transact_write(&self.vt, self.service.ptr, self.unregister_code, |w| {
                w.write_strong_binder(self.cb_binder)
            })?;
            Ok(())
        }
    }

    impl Drop for TaskStackListener {
        /// Best-effort deregistration from `activity_task`. Same deliberate
        /// non-release of the local strong ref as [`FpsListener`] — the
        /// userdata OwnedFd stays valid for any in-flight wake, and the
        /// framework-side registration is gone after the unregister.
        fn drop(&mut self) {
            let _ = self.unregister();
        }
    }

    // ── RawBinderService ──────────────────────────────────────────────────────

    /// Generic binder client for any named Android service.
    ///
    /// Handles its own `dlopen` on `libbinder_ndk.so`. Callers provide raw
    /// transaction codes (resolved via [`crate::android::dex::find_transaction_code`])
    /// and use [`RawBinderService::transact_bool`] /
    /// [`RawBinderService::transact_i32`] for typed round-trips.
    pub struct RawBinderService {
        _lib: DlHandle,
        vt: Vtable,
        service: OwnedBinder,
    }
    unsafe impl Send for RawBinderService {}

    impl RawBinderService {
        /// Open a connection to the named service (e.g. `"power"`, `"batterystats"`).
        pub fn open(service_name: &str) -> Result<Self, CoreError> {
            use std::ffi::CString;
            let handle = unsafe {
                libc::dlopen(
                    LIBBINDER_PATH.as_ptr() as *const c_char,
                    libc::RTLD_NOW | libc::RTLD_LOCAL,
                )
            };
            if handle.is_null() {
                return Err(CoreError::binder(-1, "dlopen:libbinder_ndk.so"));
            }
            let lib = DlHandle;
            let vt = load_vtable(handle)?;
            let cs = CString::new(service_name)
                .map_err(|_| CoreError::binder(-1, "service_name:nul_byte"))?;
            let raw = unsafe { (vt.get_service)(cs.as_ptr()) };
            if raw.is_null() {
                return Err(CoreError::binder(-1, "AServiceManager_getService:null"));
            }
            let service = OwnedBinder {
                ptr: raw,
                dec_strong: vt.dec_strong,
            };
            Ok(Self {
                _lib: lib,
                vt,
                service,
            })
        }

        /// Send a no-argument transaction; read exception header then bool reply.
        pub fn transact_bool(&self, code: u32) -> Result<bool, CoreError> {
            let out = self.raw_noarg(code)?;
            let r = ParcelReader {
                vt: &self.vt,
                parcel: &out,
            };
            let ex = r.read_i32()?;
            if ex != EX_NONE {
                return Err(CoreError::binder(ex, "transact_bool:exception"));
            }
            if let Some(rb) = self.vt.read_bool {
                let mut v = false;
                let s = unsafe { rb(out.ptr as *const AParcel, &mut v) };
                if s != STATUS_OK {
                    return Err(CoreError::binder(s, "AParcel_readBool"));
                }
                Ok(v)
            } else {
                Ok(r.read_i32()? != 0)
            }
        }

        /// Send a transaction with one i32 argument; discard reply.
        pub fn transact_i32(&self, code: u32, arg: i32) -> Result<(), CoreError> {
            let _ = transact_write(&self.vt, self.service.ptr, code, |w| w.write_i32(arg))?;
            Ok(())
        }

        fn raw_noarg(&self, code: u32) -> Result<OwnedParcel, CoreError> {
            transact_write(&self.vt, self.service.ptr, code, |_| Ok(()))
        }
    }

    #[cfg(test)]
    mod tests {
        use super::*;

        fn alloc(length: i32) -> bool {
            let mut buf = StringBuf::new();
            let mut out: *mut c_char = std::ptr::null_mut();
            unsafe { string_alloc(&mut buf as *mut StringBuf as *mut c_void, length, &mut out) }
        }

        #[test]
        fn string_alloc_rejects_oversized() {
            assert!(!alloc(MAX_BINDER_STRING_LEN as i32 + 1));
        }

        #[test]
        fn string_alloc_accepts_null_marker_rejects_other_negative() {
            assert!(alloc(-1));
            assert!(!alloc(-2));
        }

        #[test]
        fn string_alloc_accepts_valid_len_and_nul_terminates() {
            let mut buf = StringBuf::new();
            let mut out: *mut c_char = std::ptr::null_mut();
            let ok =
                unsafe { string_alloc(&mut buf as *mut StringBuf as *mut c_void, 4, &mut out) };
            assert!(ok);
            assert!(!out.is_null());
            {
                let vec = unsafe { buf.0.as_mut_vec() };
                b"ABCD".iter().enumerate().for_each(|(i, &b)| vec[i] = b);
                vec[4] = 0;
            }
            assert_eq!(buf.finish().as_deref(), Some("ABCD"));
        }

        #[test]
        fn fps_zero_report_distinct_from_unseen() {
            assert_eq!(fps_from_state(false, 0), None);
            assert_eq!(fps_from_state(true, 0), Some(0.0));
            assert_eq!(fps_from_state(true, 60.0f32.to_bits()), Some(60.0));
            assert_eq!(fps_from_state(false, 60.0f32.to_bits()), None);
        }

        #[test]
        fn sanitize_fps_rejects_non_finite_and_negative() {
            let de = |bits| f32::from_bits(sanitize_fps(bits));
            assert_eq!(de(0.0f32.to_bits()), 0.0);
            assert_eq!(de(60.0f32.to_bits()), 60.0);
            assert_eq!(de(f32::NAN.to_bits()), 0.0);
            assert_eq!(de(f32::INFINITY.to_bits()), 0.0);
            assert_eq!(de(f32::NEG_INFINITY.to_bits()), 0.0);
            assert_eq!(de((-5.0f32).to_bits()), 0.0);
        }
    }
}

// ── Public re-exports ─────────────────────────────────────────────────────────

#[cfg(target_os = "android")]
pub use imp::{
    ActivityManager, DisplayInfo, DisplayManager, FpsListener, RawBinderService, TaskStackListener,
    TxCodes, last_foreground_pid, resolve_tx_codes,
};

// ── Non-Android stubs ─────────────────────────────────────────────────────────

#[cfg(not(target_os = "android"))]
pub struct ActivityManager;

#[cfg(not(target_os = "android"))]
impl ActivityManager {
    pub fn open() -> Result<Self, crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn open_with_observer() -> Result<(Self, std::os::fd::OwnedFd), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn open_with_fgproc_observer() -> Result<(Self, std::os::fd::OwnedFd), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn get_focused_task(&self) -> Result<Option<(i32, Option<String>)>, crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn get_focused_package(&self) -> Result<Option<String>, crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn get_focused_task_id(&self) -> Result<Option<i32>, crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
}

#[cfg(not(target_os = "android"))]
pub struct DisplayManager;

#[cfg(not(target_os = "android"))]
impl DisplayManager {
    pub fn open_with_callback() -> Result<(Self, crate::fd::Fd), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn is_interactive(&self) -> Result<bool, crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn info(&self, _display_id: i32) -> Result<DisplayInfo, crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
}

#[cfg(not(target_os = "android"))]
#[derive(Clone, Copy, Debug, PartialEq, Default)]
pub struct DisplayInfo {
    pub active_mode_id: i32,
    pub vsync_rate: f32,
    pub peak_refresh_rate: f32,
    pub render_frame_rate: f32,
    pub is_interactive: bool,
}

#[cfg(not(target_os = "android"))]
pub struct RawBinderService;

#[cfg(not(target_os = "android"))]
impl RawBinderService {
    pub fn open(_service_name: &str) -> Result<Self, crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn transact_bool(&self, _code: u32) -> Result<bool, crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn transact_i32(&self, _code: u32, _arg: i32) -> Result<(), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
}

#[cfg(not(target_os = "android"))]
pub struct FpsListener;

#[cfg(not(target_os = "android"))]
impl FpsListener {
    pub fn open() -> Result<(Self, std::os::fd::OwnedFd), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn register(&mut self, _task_id: i32) -> Result<(), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn unregister(&mut self) -> Result<(), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn last_fps(&self) -> Option<f32> {
        None
    }
    pub fn task_id(&self) -> Option<i32> {
        None
    }
}

#[cfg(not(target_os = "android"))]
pub struct TaskStackListener;

#[cfg(not(target_os = "android"))]
impl TaskStackListener {
    pub fn open() -> Result<(Self, std::os::fd::OwnedFd), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn register(&self) -> Result<(), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
    pub fn unregister(&self) -> Result<(), crate::CoreError> {
        Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
    }
}

#[cfg(not(target_os = "android"))]
pub struct TxCodes {
    pub observer_code: u32,
    pub query_code: u32,
    pub api_mode: u8,
    pub fg_code: u32,
}

#[cfg(not(target_os = "android"))]
pub fn resolve_tx_codes() -> Result<TxCodes, crate::CoreError> {
    Err(crate::CoreError::binder(-1, "binder:unsupported platform"))
}

#[cfg(not(target_os = "android"))]
pub fn last_foreground_pid() -> i32 {
    0
}