iiab-termux

#!/data/data/com.termux/files/usr/bin/bash
set -euo pipefail

# -----------------------------------------------------------------------------
# GENERATED FILE: 2026-05-06T08:30:49-06:00 - do not edit directly.
# Source modules: termux-setup/*.sh + manifest.sh
# Rebuild: (cd termux-setup && bash build_bundle.sh)
# -----------------------------------------------------------------------------


# ---- BEGIN 00_lib_common.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

RED="\033[31m"; YEL="\033[33m"; GRN="\033[32m"; BLU="\033[34m"; RST="\033[0m"; BOLD="\033[1m"

log()       { printf "${BLU}[iiab]${RST} %s\n" "$*"; }
log_red()   { printf "${RED}[iiab]${RST} %s\n" "$*"; }
log_yel()   { printf "${YEL}[iiab]${RST} %s\n" "$*"; }
ok()        { printf "${GRN}[iiab]${RST} %s\n" "$*"; }
warn()      { printf "${YEL}[iiab] WARNING:${RST} %s\n" "$*" >&2; }
warn_red()  { printf "${RED}${BOLD}[iiab] WARNING:${RST} %s\n" "$*" >&2; }
boxyp_log() { printf "${BLU}[boxyproxy]${RST} %s\n" "$*"; }
indent()    { sed 's/^/ /'; }

have() { command -v "$1" >/dev/null 2>&1; }
need() { have "$1" || return 1; }
die()  { printf "${RED}[!] ERROR${RST}: %s\n" "$*" >&2; exit 1; }

blank() {
  local n="${1:-1}" fd=1
  [[ "$n" =~ ^[0-9]+$ ]] || n=1
  if { : >&3; } 2>/dev/null; then fd=3; fi
  while (( n-- > 0 )); do printf '\n' >&"$fd"; done
}

clear_line() {
  local outfd; outfd="$(console_outfd)"
  printf "\r%-80s\r" " " >&"$outfd"
}

# Choose warning level depending on context.
# - In explicit readiness checks (--check/--all), use red for "will likely fail".
# - In passive/self-check (baseline runs), keep it yellow to avoid over-alarming.
warn_red_context() {
  # args: long message
  if [[ "${MODE:-}" == "check" || "${MODE:-}" == "all" || "${MODE:-}" == "ppk-only" ]]; then
    warn_red "$*"
  else
    warn "$*"
  fi
}

# -------------------------
# Global defaults (may be overridden via environment)
# -------------------------
STATE_DIR="${STATE_DIR:-${HOME}/.iiab-android}"
ADB_STATE_DIR="${ADB_STATE_DIR:-${STATE_DIR}/adbw_pair}"
LOG_DIR="${LOG_DIR:-${STATE_DIR}/logs}"

HOST="${HOST:-127.0.0.1}"
CONNECT_PORT="${CONNECT_PORT:-}"
TIMEOUT_SECS="${TIMEOUT_SECS:-180}"

# -------------------------
# Android App State Sync (Controller Communication)
# -------------------------
ANDROID_SHARED_STATE_DIR="/sdcard/.iiab_state"

set_android_state_flag() {
  local flag_name="$1"
  # Only attempt if /sdcard is accessible
  if [[ -d "/sdcard" ]]; then
    mkdir -p "$ANDROID_SHARED_STATE_DIR" 2>/dev/null || true
    touch "${ANDROID_SHARED_STATE_DIR}/${flag_name}" 2>/dev/null || true
  fi
}

clear_android_state_flag() {
  local flag_name="$1"
  if [[ -d "/sdcard" ]]; then
    rm -f "${ANDROID_SHARED_STATE_DIR}/${flag_name}" 2>/dev/null || true
  fi
}

# Defaults used by ADB flows / logging / misc
CLEANUP_OFFLINE="${CLEANUP_OFFLINE:-1}"
DEBUG="${DEBUG:-0}"
BOXYPROXY_NO_EXTERNAL="${BOXYPROXY_NO_EXTERNAL:-0}"

# Package name for the Termux app.
TERMUX_PACKAGE="${TERMUX_PACKAGE:-com.termux}"

# Version and Update logic
IIAB_TERMUX_RAW_URL="${IIAB_TERMUX_RAW_URL:-https://raw.githubusercontent.com/iiab/iiab-android/main/iiab-termux}"

# Android info
get_android_sdk()     { getprop ro.build.version.sdk 2>/dev/null || true; }
get_android_release() { getprop ro.build.version.release 2>/dev/null || true; }
ANDROID_SDK="$(get_android_sdk)"
ANDROID_REL="$(get_android_release)"

# Default URLs for auto-pulling rootfs
IIAB_ROOTFS_URL_ARM64="${IIAB_ROOTFS_URL_ARM64:-https://iiab.switnet.org/android/rootfs/latest_arm64-v8a.meta4}"
IIAB_ROOTFS_URL_ARM32="${IIAB_ROOTFS_URL_ARM32:-https://iiab.switnet.org/android/rootfs/latest_armeabi-v7a.meta4}"

get_iiab_termux_version() {
  local file="${1:-$0}"
  local raw_ts=""
  if [[ -f "$file" ]]; then
    raw_ts="$(grep '^# GENERATED FILE:' "$file" 2>/dev/null | sed -E 's/.*GENERATED FILE: ([^ ]+).*/\1/' | head -n1)"
    if [[ -n "$raw_ts" ]]; then
      # Convert ISO 8601 to YYYY.DDD.HHMM in UTC
      # %Y = Year, %j = Day of year (001-366), %H%M = Hours/Minutes
      date -u -d "$raw_ts" +"%Y.%j.%H%M" 2>/dev/null && return 0
    fi
  fi
  echo "unknown"
}

update_iiab_termux() {
  local current_file="${1:-$0}"
  log "downloading latest version..."
  have curl || { warn_red "curl is required to update. Run: pkg install curl"; return 1; }

  # Use the state directory since Termux lacks a standard /tmp
  local tmp_file="${STATE_DIR}/iiab-termux-update.tmp.$$"

  if ! curl -fsSL --retry 5 --retry-connrefused --retry-delay 2 "$IIAB_TERMUX_RAW_URL" -o "$tmp_file"; then
    warn_red "Failed to download update from $IIAB_TERMUX_RAW_URL"
    rm -f "$tmp_file" >/dev/null 2>&1 || true
    return 1
  fi

  local first_line=""
  IFS= read -r first_line < "$tmp_file" || true
  if [[ "$first_line" != \#!*bash* ]]; then
    warn_red "Downloaded file doesn't look like a valid bash script (bad shebang)."
    rm -f "$tmp_file" >/dev/null 2>&1 || true
    return 1
  fi

  local old_v new_v backup_dir ts
  old_v="$(get_iiab_termux_version "$current_file")"
  new_v="$(get_iiab_termux_version "$tmp_file")"

  # Compare versions if both are successfully parsed
  if [[ "$old_v" != "unknown" && "$new_v" != "unknown" ]]; then
    if [[ "$old_v" == "$new_v" ]]; then
      ok "You already have the latest version ($old_v)."
      rm -f "$tmp_file" >/dev/null 2>&1 || true
      return 0
    elif [[ "$old_v" > "$new_v" ]]; then
      log_yel "Your local version ($old_v) appears to be newer than the repository version ($new_v)."
      log_yel "You might be running local uncommitted changes."
      if ! tty_yesno_default_n "[iiab] Do you want to overwrite your local version with the repository version? [y/N]: "; then
        log "Update aborted by user. Keeping local version."
        rm -f "$tmp_file" >/dev/null 2>&1 || true
        return 0
      fi
    fi
  fi

  log "updating $new_v over $old_v"

  backup_dir="${STATE_DIR}/termux"
  mkdir -p "$backup_dir"
  ts="$(date +%Y%m%d-%H%M%S)"
  cp -f "$current_file" "${backup_dir}/iiab-termux.old.${ts}" 2>/dev/null || true

  mv -f "$tmp_file" "$current_file" && chmod 700 "$current_file"
  log "installed version: $new_v"
  return 0
}

# One-time helper: guide user to set Termux battery policy to keep sessions alive.
POWER_MODE_BATTERY_PROMPT="${POWER_MODE_BATTERY_PROMPT:-1}"  # 1=ask, 0=never ask
POWER_MODE_BATTERY_STAMP="${POWER_MODE_BATTERY_STAMP:-$STATE_DIR/stamp.termux_battery_settings}"

export PIP_EXTRA_INDEX_URL="https://iiab.switnet.org/simple"

tty_prompt_print() {
  local prompt="$1" outfd=1
  # Prefer original console FD3 if available (set by setup_logging)
  if [[ -t 3 ]]; then
    outfd=3
  fi
  printf '%b' "$prompt" >&"$outfd"
}

fd3_available() { : >&3 2>/dev/null; }
fd4_available() { : >&4 2>/dev/null; }

console_outfd() { fd3_available && echo 3 || echo 1; }
console_errfd() { fd4_available && echo 4 || echo 2; }

tty_yesno_default_y() {
  # args: prompt
  # Returns 0 for Yes, 1 for No. Default is Yes.
  local prompt="$1" ans="Y" outfd
  outfd="$(console_outfd)"
  if [[ -r /dev/tty ]]; then
    tty_prompt_print "$prompt"
    if ! read -r ans < /dev/tty; then
      ans="Y"
    fi
  else
    warn "No /dev/tty available; defaulting to YES."
    ans="Y"
  fi
  ans="${ans:-Y}"
  [[ "$ans" =~ ^[Nn]$ ]] && return 1
  return 0
}

tty_yesno_default_n() {
  # args: prompt
  # Returns 0 for Yes, 1 for No. Default is No.
  local prompt="$1" ans="N" outfd
  outfd="$(console_outfd)"
  if [[ -r /dev/tty ]]; then
    tty_prompt_print "$prompt"
    read -r ans < /dev/tty || ans="N"
  else
    warn "No /dev/tty available; defaulting to NO."
    ans="N"
  fi
  ans="${ans:-N}"
  [[ "$ans" =~ ^[Yy]$ ]] && return 0
  return 1
}

countdown_timer() {
  # $1 = Seconds (e.g., 5)
  # $2 = Format string with %d (e.g., "\r${YEL}Waiting %d secs...${RST}")
  local secs="${1:-5}"
  local msg="$2"
  local outfd; outfd="$(console_outfd)"

  if [[ -r /dev/tty ]]; then
    for (( i=secs; i>=1; i-- )); do
      printf "$msg" "$i" >&"$outfd"
      sleep 1
    done
    clear_line
  else
    sleep "$secs"
  fi
}

iiab_login() {
  local stamp="$STATE_DIR/stamp.termux_base"

  # Baseline stamp is advisory only for login (do not block).
  if [[ -f "$stamp" ]]; then
    ok "Baseline stamp found: $stamp"
  else
    warn_red "Baseline stamp not found ($stamp)."
    warn "Tip: run the baseline once: iiab-termux"
  fi

  have proot-distro || die "proot-distro not found. Install baseline first (pkg install proot-distro or run iiab-termux)."
  if ! iiab_exists; then
    warn_red "IIAB Debian is not installed in proot-distro (alias 'iiab' missing)."
    warn "Recommended: iiab-termux --all"
    warn "Or:          proot-distro install --override-alias iiab debian"
    return 1
  fi

  # Reminder: Android battery policy must be configured before long installs.
  if [[ "${POWER_MODE_BATTERY_PROMPT:-1}" -eq 1 ]]; then
    local bst="$POWER_MODE_BATTERY_STAMP"
    if [[ ! -f "$bst" && ! -f "${ANDROID_SHARED_STATE_DIR}/flag_perm_battery" ]]; then
      warn "Reminder: for reliable long installs, set Termux -> Battery to 'Unrestricted'."
      power_mode_battery_instructions
      if tty_yesno_default_n "[iiab] Open Termux App info now to adjust Battery policy? [y/N]: "; then
        if android_open_termux_app_info; then
          tty_prompt_print "[iiab] When done, return to Termux and press Enter to continue... "
          if [[ -r /dev/tty ]]; then
            read -r _ </dev/tty || true
          else
            local outfd
            outfd="$(console_outfd)"
            printf "\n" >&"$outfd"
          fi
          date > "$bst" 2>/dev/null || true
        else
          warn "Unable to open Settings automatically. Open manually: Settings -> Apps -> Termux."
        fi
      fi
    fi
  fi

  # Best-effort Android advice before user starts doing heavy installs inside proot.
  local sdk="${ANDROID_SDK:-}"
  if [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 31 && sdk <= 33 )); then
    # Android 12-13: PPK is a common hard failure point.
    if have adb; then
      adb start-server >/dev/null 2>&1 || true
      if adb_pick_loopback_serial >/dev/null 2>&1; then
        check_readiness || true
      else
        warn_red "Android 12-13: ADB is not connected, so PPK fix cannot be verified/applied."
        warn "Before running the IIAB installer inside proot, run:"
        ok   "  iiab-termux --all"
      fi
    else
      warn_red "Android 12-13: adb is missing, so PPK fix cannot be verified/applied."
      warn "Install adb (android-tools) and run:"
      ok   "  iiab-termux --all"
    fi
  fi

  ok "Starting IIAB Debian (via: iiab-termux --start)"
  local wlan_ip; wlan_ip="$(adb_local_ipv4s_csv 2>/dev/null | cut -d, -f1)"
  if [[ -n "$wlan_ip" && "$wlan_ip" != "Disconnected" && "$wlan_ip" != "0.0.0.0" ]]; then
    if ! have qrencode; then
      log "Installing missing dependency: libqrencode..."
      termux_apt install libqrencode >/dev/null 2>&1 || true
    fi
    blank
    log "To use your IIAB on Android over the network, please scan the following QR Code:"
    qrencode -t UTF8 "http://${wlan_ip}:8085/"
    blank
  else
    blank
    warn "It seems there is no network available to share IIAB on Android over the network."
    blank
  fi
  power_mode_login_enter || true

  # Auto-start boxyproxy for the duration of this proot session.
  BOXYPROXY_MANAGED=1
  if boxyproxy_is_running; then
    if [[ "${BOXYPROXY_NO_EXTERNAL:-0}" -eq 1 ]]; then
      boxyp_log "Auto-start: restarting proxy to apply --no-external..."
      boxyproxy_stop >/dev/null 2>&1 || true
      boxyproxy_start >/dev/null 2>&1 || true
    else
      boxyp_log "Auto-start: already running (will stop on exit)."
    fi
  else
    # Best-effort: install once if missing (avoid forcing updates every login).
    if ! boxyproxy_is_installed; then
      boxyp_log "Auto-start: installing boxyproxy.py (best-effort)..."
      boxyproxy_install_or_update >/dev/null 2>&1 || true
    fi
    boxyproxy_start >/dev/null 2>&1 || true
  fi

  # Preserve interactivity even if logging is enabled (avoid pipes/tee issues).
  local rc=0
  local outfd errfd
  outfd="$(console_outfd)"
  errfd="$(console_errfd)"

  # Don't let a non-zero exit from proot skip cleanup (set -e).
  set +e
   if [[ "${INTENT_MODE:-}" == "headless" ]]; then
     boxyp_log "Running in APK Headless mode (no TTY, sleep infinity)"
     if command -v am >/dev/null 2>&1; then
         am start -n org.iiab.controller/org.iiab.controller.MainActivity >/dev/null 2>&1 || true
     fi
     proot-distro login iiab -- bash -lc "/usr/local/bin/pdsm start && sleep infinity"
     rc=$?
   elif [[ -r /dev/tty ]]; then
    proot-distro login iiab </dev/tty >&"$outfd" 2>&"$errfd"
    rc=$?
  else
    proot-distro login iiab
    rc=$?
  fi
  set -e

  # Stop proxy after leaving proot session (also covered by trap for signals).
  boxyproxy_stop >/dev/null 2>&1 || true
  BOXYPROXY_MANAGED=0

  power_mode_login_exit || true
  return $rc
}

iiab_stop() {
  log "Stopping IIAB environment..."

  # Stop the 'boxyproxy' proxy
  boxyproxy_stop >/dev/null 2>&1 || true

  # Graceful shutdown of internal services using 'pdsm'
  if iiab_exists; then
    log "Executing 'pdsm stop' for internal services..."
     if command -v am >/dev/null 2>&1; then
         am start -n org.iiab.controller/org.iiab.controller.MainActivity >/dev/null 2>&1 || true
     fi
    # Send the command into proot. The script won't fail if a service fails.
    proot-distro login iiab -- /usr/local/bin/pdsm stop || warn "Partial failure while stopping services via pdsm."
  fi

  # Allow a few seconds for processes to save data and exit
  sleep 3

  # Final zombie cleanup
  # We kill any orphaned processes pdsm might left hanging after 3 seconds
  if pkill -0 -f "proot.*iiab" 2>/dev/null; then
    log "Cleaning up remaining processes..."
    pkill -TERM -f "proot.*iiab" || true
    sleep 1
    pkill -KILL -f "proot.*iiab" 2>/dev/null || true
  fi

  ok "All IIAB services have been successfully stopped."
}

cmd_json_vars() {
  local yaml_content=""

  # Extract content directly from inside PRoot
  if iiab_exists; then
     yaml_content="$(proot-distro login iiab -- cat /etc/iiab/local_vars.yml 2>/dev/null || true)"
  fi

  # If it fails or is empty, return an empty JSON
  if [[ -z "$yaml_content" ]]; then
     if [[ "${INTENT_MODE:-}" == "headless" ]]; then
        mkdir -p "$ANDROID_SHARED_STATE_DIR" 2>/dev/null || true
        echo "{}" > "${ANDROID_SHARED_STATE_DIR}/local_vars.json"
     else
        echo "{}"
     fi
     return 1
  fi

  # Ultra-fast parsing with awk: Looks for lines ending in _install: or _enabled: with True/False
  local json_data
  json_data=$(echo "$yaml_content" | awk -F':' '/^[a-zA-Z0-9_]+_(install|enabled):[ \t]+(True|False|true|false)/ {
      key=$1;
      val=$2;
      gsub(/^[ \t]+|[ \t]+$/, "", val); # Remove leading/trailing spaces
      if (tolower(val) == "true") val="true"; else val="false";
      printf "  \"%s\": %s,\n", key, val;
  }' | sed '$ s/,$//') # Remove the trailing comma to make it valid JSON

  local final_json="{\n${json_data}\n}"

  # If called from the app (headless), write to the shared file. Otherwise, print to terminal.
  if [[ "${INTENT_MODE:-}" == "headless" ]]; then
     mkdir -p "$ANDROID_SHARED_STATE_DIR" 2>/dev/null || true
     echo -e "$final_json" > "${ANDROID_SHARED_STATE_DIR}/local_vars.json"
     if command -v am >/dev/null 2>&1; then
         am start -n org.iiab.controller/org.iiab.controller.MainActivity >/dev/null 2>&1 || true
     fi
  else
     echo -e "$final_json"
  fi
}

cmd_install_module() {
  local role="$1"
  [[ -z "$role" ]] && die "You must specify a module/role to install."

  log "Preparing to install module: $role"

  if ! iiab_exists; then
    die "IIAB Debian (alias 'iiab') is not installed."
  fi

  # Safety guard: Dashboard is auto-installed, it shouldn't be executed via runrole
  if [[ "$role" == "dashboard" ]]; then
    warn "Role '$role' is managed automatically. Skipping runrole execution."
    return 0
  fi

  # Update local_vars.yml inside PRoot
  log "Updating local_vars.yml for $role..."
  proot-distro login iiab -- bash -c "
    sed -i -E '/^[[:space:]]*${role}_(install|enabled)[[:space:]]*:/d' /etc/iiab/local_vars.yml
    echo '${role}_install: True' >> /etc/iiab/local_vars.yml
    echo '${role}_enabled: True' >> /etc/iiab/local_vars.yml
  "

  # Execute Ansible runrole
  log "Executing Ansible runrole for $role..."
  local rc=0
  set +e

  # Execute runrole preserving interactivity (TTY) if available
  if [[ -r /dev/tty ]]; then
    proot-distro login iiab < /dev/tty -- bash -lc "cd /opt/iiab/iiab && ./runrole $role"
    rc=$?
  else
    proot-distro login iiab -- bash -lc "cd /opt/iiab/iiab && ./runrole $role"
    rc=$?
  fi
  set -e

  if (( rc == 0 )); then
    ok "Module $role installed successfully!"
  else
    warn_red "Module $role installation failed or completed with errors (rc=$rc)."
  fi

  # Bounce back to Controller App if called via Android Intent
  if [[ "${INTENT_MODE:-}" == "headless" ]]; then
     log "Refreshing JSON state for the Controller App..."
     cmd_json_vars > /dev/null 2>&1 || true

     if command -v am >/dev/null 2>&1; then
         log "Returning control to Android App..."
         sleep 1 # Brief visual pause before bouncing back
         am start -n org.iiab.controller/org.iiab.controller.MainActivity >/dev/null 2>&1 || true
     fi
  fi

  return $rc
}

### --- Pre-flight Check & Metrics ---
check_preflight_requirements() {
  local outfd; outfd="$(console_outfd)"
  printf "${BLU}[iiab] --- Pre-flight System Checks ---${RST}\n" >&"$outfd"

  # 1. Architecture Check
  local arch; arch=$(get_android_arch)
  local arch_stat="${GRN}OK${RST}"
  [[ "$arch" == "unknown" ]] && arch_stat="${YEL}WARN${RST}"
  printf "${BLU}[iiab]${RST}  * %-30s [%b]\n" "Architecture ($arch)" "$arch_stat" >&"$outfd"

  # 2. Disk Space Logic (Thresholds: 2.5GB and 5GB)
  local free_mb; free_mb=$(df -k "$PREFIX" | awk 'END{print $4 / 1024}' | cut -d. -f1)
  local free_gb; free_gb=$(awk -v mb="$free_mb" 'BEGIN { printf "%.2f", mb / 1024 }')
  local disk_stat="${GRN}OK${RST}"
  if [[ "$free_mb" -lt 2500 ]]; then disk_stat="${RED}FAIL${RST}"; elif [[ "$free_mb" -lt 5000 ]]; then disk_stat="${YEL}WARN${RST}"; fi
  printf "${BLU}[iiab]${RST}  * %-30s [%b]\n" "Free Space (${free_gb} GB)" "$disk_stat" >&"$outfd"

  # 3. Network Latency Check (Inside Table)
  local net_stat="${RED}FAIL${RST}"
  local net_text="Network Latency (Offline)"
  local start_t; start_t=$(date +%s%N 2>/dev/null || echo 0)
  if curl -Isf --connect-timeout 5 google.com >/dev/null 2>&1; then
    local end_t; end_t=$(date +%s%N 2>/dev/null || echo 0)
    if [[ "$start_t" != "0" && "$end_t" != "0" ]]; then
      local delta=$(( (end_t - start_t) / 1000000 ))
      net_text="Network Latency (${delta}ms)"
      if [[ "$delta" -le 50 ]]; then net_stat="${BOLD}${BLU}EXCEL${RST}"
      elif [[ "$delta" -le 150 ]]; then net_stat="${GRN}GOOD${RST}"
      elif [[ "$delta" -le 250 ]]; then net_stat="${YEL}FAIR${RST}"
      else net_stat="${RED}SLOW${RST}"
      fi
    fi
  fi
  printf "${BLU}[iiab]${RST}  * %-30s [%b]\n" "$net_text" "$net_stat" >&"$outfd"

  # 4. Developer Options Contextual Reminder
  local sdk="${ANDROID_SDK:-0}"
  local rel="${ANDROID_REL:-0}"
  local dev_stat="${YEL}NOTE${RST}"
  if [[ "$sdk" -ge 34 ]]; then
    printf "${BLU}[iiab]${RST}  * %-30s [%b]\n" "Dev. Options (Child Process)" "$dev_stat" >&"$outfd"
  elif [[ "$sdk" -ge 31 ]]; then
    printf "${BLU}[iiab]${RST}  * %-30s [%b]\n" "Dev. Options (Phantom Process)" "$dev_stat" >&"$outfd"
   else
    printf "${BLU}[iiab]${RST}  * %-30s [%b]\n" "Dev. Options (Not Required)" "${GRN}N/A${RST}" >&"$outfd"
  fi

  printf "${BLU}[iiab] --------------------------------------${RST}\n" >&"$outfd"

  # --- Checks and warnings (summary) ---
  [[ "$arch" == "unknown" ]] && warn "Unknown architecture. Results may vary."

  if [[ "$free_mb" -lt 2500 ]]; then
    warn_red "Error: Insufficient space to install IIAB on Android."
    die "Please free up space (at least 2.5GB) to continue."
  elif [[ "$free_mb" -lt 5000 ]]; then
    log_yel "Warning: Limited storage detected (${free_gb} GB)."
    warn "You may face limitations when adding additional content later."
    tty_yesno_default_n "[iiab] Do you want to continue with a tight installation? [y/N]: " || die "Aborted by user."
  else
    ok "Sufficient disk space for installation (${free_gb} GB)"
    log "Note: Space for multimedia content depends on the specific modules you add later."
  fi

  if [[ "$net_stat" == *FAIL* ]]; then
    warn_red "Network unreachable or timeout. Downloads may fail."
  elif [[ "$net_stat" == *SLOW* ]]; then
    warn "High network latency detected."
  fi

  if [[ "$sdk" -ge 34 ]]; then
    log_yel "Reminder: Developer Options must be enabled to toggle 'Disable child process restrictions'."
  elif [[ "$sdk" -ge 31 ]]; then
    log_yel "Reminder: Developer Options must be enabled to pair ADB and fix 'Phantom Process Killer'."
  elif [[ "$sdk" -gt 0 && "$sdk" -le 30 ]]; then
    ok "No known process restrictions for Android $rel."
  fi

  ok "Pre-flight checks completed."
  countdown_timer 7 "\r${BLU}[iiab]${RST} Proceeding in %d seconds... "
}

welcome_interactive() {
  local mode_label="${1:-Installation}"
  local prompt_text="Press [ENTER] to start system validation... "
  [[ "$mode_label" == "Preview" ]] && prompt_text="Press [ENTER] to exit welcome message... "

  local outfd; outfd="$(console_outfd)"
  {
    clear
    printf "${BLU}==================================================${RST}\n"
    printf " 🌐 WELCOME TO IIAB on Android 🌐\n"
    printf "     Starting mode: ${mode_label}\n"
    printf "${BLU}==================================================${RST}\n"
    printf "\n${BOLD}Internet-in-a-Box (IIAB) on Android${RST} will allow\n"
    printf "millions of people worldwide to build their own \n"
    printf "family libraries, inside their own phones!\n"
    blank
    printf "This script prepares your Android device as an\n"
    printf "Offline Learning Environment (Internet-in-a-Box).\n"
    blank
    printf "Please follow the installation guide at:\n"
    printf "${YEL}*${RST} 📄: ${BLU}https://github.com/iiab/iiab-android${RST}\n"
    blank
    printf "Other online resources:\n"
    printf "${YEL}*${RST} 🔗: ${BOLD}https://internet-in-a-box.org${RST}\n"
    printf "${YEL}*${RST} 🐛: ${BOLD}https://github.com/iiab/iiab-android/issues${RST}\n"
    blank
    printf " TIP: Keep the charger around and ensure Termux\n"
    printf " battery settings are set to 'Unrestricted'.\n"
    printf "${BLU}==================================================${RST}\n"
    
    if [[ -r /dev/tty ]]; then
      printf "%s" "$prompt_text"
    fi
  } >&"$outfd"

  if [[ -r /dev/tty ]]; then
    read -r _ < /dev/tty || true
   fi
 }

offer_welcome_once() {
  local mode_label="$1"
  local stamp="${STATE_DIR}/stamp.welcome"
  
  if [[ ! -f "$stamp" ]]; then
    welcome_interactive "$mode_label"
    date > "$stamp" 2>/dev/null || true
  fi
}

measure_disk_usage() {
  # $1 = Function or mode name to execute
  local before; before=$(du -sm "$PREFIX/.." | awk '{print $1}')
  log "Calculating installation footprint..."
  
  # Execute the passed logic
  "$@" 

  local after; after=$(du -sm "$PREFIX/.." | awk '{print $1}')
  local footprint=$((after - before))
  ok "Installation completed. System footprint: +${footprint}MB."
}
# -------------------------
# Help / usage (static text)
# -------------------------
usage() {
  printf '%b\n' "
${BOLD}Usage:${RST} iiab-termux [MODE] [OPTIONS]

${BLU}=== CORE & INSTALL ===${RST}
  ${GRN}(no args)${RST}       Baseline + IIAB Debian bootstrap
  ${GRN}--all${RST}           Full setup: baseline, Debian, ADB, PPK, & checks
  ${GRN}--barebones${RST}     Minimal installation: Termux base + proxy (no rootfs)
  ${GRN}--start, --login${RST} Start / Login IIAB Debian
  ${GRN}--iiab-android${RST}  Install/update 'iiab-android' tool inside proot
  ${GRN}--install-module [M]${RST} Install a specific Ansible role (e.g. books)
  ${GRN}--json-vars${RST}     Export local_vars.yml status as JSON (for Controller App)

${BLU}=== ADB & SYSTEM TUNING ===${RST}
  ${GRN}--with-adb${RST}      Baseline + Debian + ADB wireless pair/connect
  ${GRN}--adb-only${RST}      Only ADB pair/connect (skips Debian)
  ${GRN}--connect-only${RST}  Connect to an already-paired device
  ${GRN}--ppk-only${RST}      Set max_phantom_processes=256 via ADB
  ${GRN}--check${RST}         Check Android readiness (Process restrictions, PPK)

${BLU}=== BACKUP & RESTORE ===${RST}
  ${GRN}--backup-rootfs${RST} Backup IIAB Debian to .tar.gz
  ${GRN}--restore-rootfs${RST} Restore IIAB Debian from local .tar.gz
  ${GRN}--pull-rootfs${RST}   Download & restore rootfs from URL (P2P enabled)
  ${GRN}--remove-rootfs${RST} Delete IIAB Debian rootfs and all data

${BLU}=== PROXY (BOXYPROXY) ===${RST}
  ${GRN}--proxy-start${RST}   Start background proxy
  ${GRN}--proxy-stop${RST}    Stop background proxy
  ${GRN}--proxy-status${RST}  Show proxy status

${BOLD}Options:${RST}
  --connect-port [P]  Skip CONNECT PORT prompt
  --timeout [SECS]    Wait time per prompt (default 180)
  --no-meta4          Disable Metalink/P2P for --pull-rootfs
  --keep-tarball      Keep the downloaded archive after --pull-rootfs
  --reset-iiab        Reinstall IIAB Debian
  --install-self      Install the current script to Termux bin path
  --welcome           Show the welcome screen
  --debug             Enable extra logs
  --help, --version   Show this help or version

${YEL}Notes:${RST} Setup on Android 12 & 13 requires ADB due to OS design. 14+ simplifies this with system UI toggles
"
}

# ---- END 00_lib_common.sh ----


# ---- BEGIN 10_mod_logging.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

# -------------------------
# Logging
# -------------------------
LOG_ENABLED=1
LOG_FILE=""          # if empty, auto-generate under $LOG_DIR
LOG_KEEP=5           # keep only the last 5 days worth of logs

prune_old_logs() {
  [[ -d "${LOG_DIR:-}" ]] || return 0
  local keep="${LOG_KEEP:-3}"
  local i=0 f
  while IFS= read -r f; do
    [[ -n "${f:-}" ]] || continue
    i=$((i + 1))
    (( i <= keep )) && continue
    rm -f -- "$f" 2>/dev/null || true
  done < <(ls -1t "$LOG_DIR"/*.log 2>/dev/null || true)
}

setup_logging() {
  # Save original console fds so interactive tools still work after we redirect stdout/stderr.
  exec 3>&1 4>&2

  # If logging is disabled, still allow --debug to trace to console.
  if [[ "${LOG_ENABLED:-1}" -ne 1 ]]; then
    if [[ "${DEBUG:-0}" -eq 1 ]]; then
      set -x
      ok "Debug trace enabled (bash -x) -> console (logging disabled)"
    fi
    return 0
  fi

  mkdir -p "$LOG_DIR"

  if [[ -z "${LOG_FILE:-}" ]]; then
    LOG_FILE="${LOG_DIR}/iiab-termux.$(date +%Y%m%d).log"
  else
    mkdir -p "$(dirname -- "$LOG_FILE")"
  fi

  # Header (best-effort)
  local started
  started="$(date -Is 2>/dev/null || date 2>/dev/null || echo "?")"
  {
    echo "=== iiab termux setup log ==="
    echo "Started: $started"
    echo "Script: $0"
    echo "Args: ${*:-}"
    echo "Android SDK=${ANDROID_SDK:-?} Release=${ANDROID_REL:-?}"
    echo "PWD: $(pwd 2>/dev/null || true)"
    echo "================================"
  } >>"$LOG_FILE" 2>/dev/null || true

  chmod 600 "$LOG_FILE"

  prune_old_logs

      # Duplicate stdout/stderr to console + log (strip ANSI in log)
      # Single pipeline for stable ordering (no stdout/stderr interleaving) at FD3.
      exec > >(tee >(sed -E 's/\x1B\[[0-9;]*[ -/]*[@-~]//g' >>"$LOG_FILE") >&3) 2>&1

  ok "Logging to: ${LOG_FILE/#$HOME/\~}"

  # If --debug, send xtrace only to log
  if [[ "${DEBUG:-0}" -eq 1 ]]; then
    exec 9>>"$LOG_FILE"
    export BASH_XTRACEFD=9
    export PS4='+(${BASH_SOURCE}:${LINENO}): ${FUNCNAME[0]:+${FUNCNAME[0]}(): }'
    set -x
    ok "Debug trace enabled (bash -x) -> log only"
  fi
}

# ---- END 10_mod_logging.sh ----


# ---- BEGIN 15_mod_prepatch_env.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

# -------------------------
# Environment Pre-patches & Hacks (15_mod_prepatch_env.sh)
# -------------------------
# This module acts as a registry for upstream bugs, weird Android
# edge cases, and environment quirks.
#
# ALL functions must be idempotent and fail silently if not needed.

python_patch_sysconfig_armv8l() {
  # Fixes a bug in Termux Python 3.13 where 'armv8l' architecture throws a KeyError
  # during pip C-extensions compilation (like aiohttp or zeroconf).

  local py=""
  py="$(command -v python 2>/dev/null || command -v python3 2>/dev/null || true)"
  [[ -n "$py" ]] || return 0 # no python; end.

  local sysconfig_file=""
  sysconfig_file="$("$py" -c "import sysconfig; print(sysconfig.__file__)" 2>/dev/null || true)"

  [[ -z "$sysconfig_file" ]] || [[ ! -f "$sysconfig_file" ]] && return 0

  if grep -q '"armv8l": "armeabi_v7a"' "$sysconfig_file"; then
    return 0 # already fixed; end.
  fi

  if grep -q '"armv7l": "armeabi_v7a"' "$sysconfig_file"; then
    log_yel "Patching Python sysconfig to resolve armv8l architecture bug..."
    sed -i 's/"armv7l": "armeabi_v7a",/"armv7l": "armeabi_v7a",\n        "armv8l": "armeabi_v7a",/g' "$sysconfig_file"
  fi
}

# ---- END 15_mod_prepatch_env.sh ----


# ---- BEGIN 20_mod_termux_base.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

# -------------------------
# Python helpers + mDNS deps (zeroconf)
# -------------------------
# Rationale: If mDNS autodetect is enabled, prepare it here so it's available from the start.

TERMUX_ZEROCONF_STAMP="${STATE_DIR}/stamp.termux_zeroconf"

# Cache: avoid repeating zeroconf checks/installs/warnings in the same run.
PY_ZEROCONF_CHECKED=0
PY_ZEROCONF_OK=0

# -------------------------
# Python deps for boxyproxy (aiohttp)
# -------------------------
# Prepare it early so proxy-start works reliably.

TERMUX_AIOHTTP_STAMP="${STATE_DIR}/stamp.termux_aiohttp"

# Cache: avoid repeating aiohttp checks/installs/warnings in the same run.
PY_AIOHTTP_CHECKED=0
PY_AIOHTTP_OK=0

# Allow disabling auto-install (keep default enabled).
BOXYPROXY_DEPS_INSTALL="${BOXYPROXY_DEPS_INSTALL:-1}"
BOXYPROXY_DEPS_PIP_INSTALL="${BOXYPROXY_DEPS_PIP_INSTALL:-1}"

python_cmd() {
  command -v python 2>/dev/null || command -v python3 2>/dev/null || true
}

python_has_zeroconf() {
  local py=""
  py="$(python_cmd)"
  [[ -n "$py" ]] || return 1
  "$py" -c 'import zeroconf' >/dev/null 2>&1
}

python_has_aiohttp() {
  local py=""
  py="$(python_cmd)"
  [[ -n "$py" ]] || return 1
  "$py" -c 'import aiohttp' >/dev/null 2>&1
}

python_pip_install_zeroconf() {
  local py=""
  py="$(python_cmd)"
  [[ -n "$py" ]] || return 1
  # Some environments may lack pip initially; try ensurepip if available.
  if ! "$py" -m pip --version >/dev/null 2>&1; then
    if "$py" -c 'import ensurepip' >/dev/null 2>&1; then
      "$py" -m ensurepip --upgrade || return 1
      "$py" -m pip --version || return 1
    else
      return 1
    fi
  fi
  # Run pip directly on the real TTY when FD 3/4 are available.
  if : >&3 2>/dev/null && : >&4 2>/dev/null; then
    ( exec 1>&3 2>&4; "$py" -m pip install --upgrade zeroconf --progress-bar on )
  else
    "$py" -m pip install --upgrade zeroconf --progress-bar on
  fi
}

python_ensure_zeroconf() {
  # Fast path: if we already decided in this run, return the same result.
  if [[ "${PY_ZEROCONF_CHECKED:-0}" -eq 1 ]]; then
    [[ "${PY_ZEROCONF_OK:-0}" -eq 1 ]] && return 0
    return 1
  fi

  PY_ZEROCONF_CHECKED=1

  # Android < 11 does not use Wireless debugging pairing; skip mDNS prep.
  if [[ "${ANDROID_SDK:-}" =~ ^[0-9]+$ ]] && (( ANDROID_SDK < 30 )); then
    PY_ZEROCONF_OK=0
    return 1
  fi
  if python_has_zeroconf; then
    PY_ZEROCONF_OK=1
    return 0
  fi
  [[ "${ADB_MDNS_PIP_INSTALL:-1}" -eq 1 ]] || { PY_ZEROCONF_OK=0; return 1; }

  log_yel "Python module 'zeroconf' not found. Installing it..."
  if python_pip_install_zeroconf && python_has_zeroconf; then
    ok "Installed Python module 'zeroconf' (mDNS autodetect enabled)."
    PY_ZEROCONF_OK=1
    return 0
  fi
  warn "Could not install 'zeroconf' (no network, pip missing, or install failed). Falling back to manual prompts."
  PY_ZEROCONF_OK=0
  return 1
}

python_pip_install_aiohttp() {
  local py=""
  py="$(python_cmd)"
  [[ -n "$py" ]] || return 1
  if ! "$py" -m pip --version >/dev/null 2>&1; then
    if "$py" -c 'import ensurepip' >/dev/null 2>&1; then
      "$py" -m ensurepip --upgrade || return 1
      "$py" -m pip --version || return 1
    else
      return 1
    fi
  fi
  if : >&3 2>/dev/null && : >&4 2>/dev/null; then
    ( exec 1>&3 2>&4; "$py" -m pip install --upgrade aiohttp --progress-bar on )
  else
    "$py" -m pip install --upgrade aiohttp --progress-bar on
  fi
}

termux_prepare_boxyproxy_deps() {
  have python || have python3 || return 0
  python_has_aiohttp && return 0

  log_yel "Python module 'aiohttp' not found. Installing it ..."
  python_pip_install_aiohttp >/dev/null 2>&1 || true
  python_has_aiohttp && { ok "Installed 'aiohttp' via pip."; return 0; }

  warn "Could not install 'aiohttp'. boxyproxy may fail until it's installed."
  return 1
}

termux_prepare_mdns_deps() {
  # Only if mDNS autodetect is enabled & pip-install is allowed.
  [[ "${ADB_MDNS:-0}" -eq 1 ]] || return 0
  [[ "${ADB_MDNS_PIP_INSTALL:-1}" -eq 1 ]] || return 0
  have python || have python3 || return 0

  # If we stamped success before and it's still present, do nothing.
  if [[ -f "$TERMUX_ZEROCONF_STAMP" ]] && python_has_zeroconf; then
    return 0
  fi
  # If stamp exists but module disappeared, drop stamp and retry.
  [[ -f "$TERMUX_ZEROCONF_STAMP" ]] && rm -f "$TERMUX_ZEROCONF_STAMP" >/dev/null 2>&1 || true

  log "Preparing mDNS autodetect dependency (python module: zeroconf)..."
  if python_ensure_zeroconf; then
    date > "$TERMUX_ZEROCONF_STAMP" 2>/dev/null || true
  else
    # python_ensure_zeroconf already warned; keep this generic to avoid duplicates.
    warn "mDNS autodetect may fall back to manual prompts."
  fi
  return 0
}

# If baseline fails, store the last command that failed for better diagnostics.
BASELINE_ERR=""

baseline_need_python() {
  # Android 11+ (SDK 30+) only
  [[ "${ANDROID_SDK:-}" =~ ^[0-9]+$ ]] && (( ANDROID_SDK >= 30 ))
}

baseline_prereqs_ok() {
  have proot-distro && have adb && have termux-notification && have termux-dialog && have sha256sum || return 1
  if baseline_need_python; then
    have python || return 1
  fi
  return 0
}

baseline_missing_prereqs() {
  local req=(adb proot-distro termux-notification termux-dialog)
  baseline_need_python && req+=(python)
  for b in "${req[@]}"; do
    have "$b" || echo "$b"
  done
  have sha256sum || echo "sha256sum (coreutils)"
}

baseline_bail_details() {
  warn "Baseline package installation failed (network / repo unreachable or packages missing)."
  [[ -n "${BASELINE_ERR:-}" ]] && warn "Last failing command: ${BASELINE_ERR}"
  local miss=()
  mapfile -t miss < <(baseline_missing_prereqs || true)
  ((${#miss[@]})) && warn "Missing prerequisites: ${miss[*]}"
  warn "Not stamping; rerun later when prerequisites are available."
}

# Termux apt options (avoid conffile prompts)
TERMUX_APT_OPTS=( "-y" "-o" "Dpkg::Options::=--force-confdef" "-o" "Dpkg::Options::=--force-confold" )
termux_apt() { apt-get "${TERMUX_APT_OPTS[@]}" "$@"; }

# Default: enable mDNS autodetect only on Android 11+ (SDK 30+).
if [[ -z "${ADB_MDNS+x}" ]]; then
  if [[ "${ANDROID_SDK:-}" =~ ^[0-9]+$ ]] && (( ANDROID_SDK >= 30 )); then
    ADB_MDNS=1
  else
    ADB_MDNS=0
  fi
fi
ADB_MDNS_PIP_INSTALL="${ADB_MDNS_PIP_INSTALL:-1}"

# -------------------------
# Wakelock (Termux:API)
# -------------------------
WAKELOCK_HELD=0
acquire_wakelock() {
  if have termux-wake-lock; then
    if termux-wake-lock; then
      WAKELOCK_HELD=1
      ok "Wakelock acquired (termux-wake-lock)."
    else
      warn "Failed to acquire wakelock (termux-wake-lock)."
    fi
  else
    warn "termux-wake-lock not available. Install: pkg install termux-api + Termux:API app."
  fi
}
release_wakelock() {
  if [[ "$WAKELOCK_HELD" -eq 1 ]] && have termux-wake-unlock; then
    termux-wake-unlock || true
    ok "Wakelock released (termux-wake-unlock)."
    WAKELOCK_HELD=0
  fi
}

# -------------------------
# Set Battery usage step.
# -------------------------
android_am_bin() {
  # Return a usable 'am' binary path.
  if have am; then
    command -v am
    return 0
  fi
  [[ -x /system/bin/am ]] && { echo /system/bin/am; return 0; }
  return 1
}

android_start_activity() {
  # Start an Android activity via 'am'.
  local ambin
  ambin="$(android_am_bin 2>/dev/null)" || return 1
  "$ambin" start "$@" >/dev/null 2>&1
}

android_open_developer_options() {
  # Open Developer options to enable Wireless debugging.
  android_start_activity -a android.settings.APPLICATION_DEVELOPMENT_SETTINGS && return 0
  android_start_activity -a android.settings.DEVELOPMENT_SETTINGS && return 0
  return 1
}

android_open_termux_app_info() {
  # Open Settings -> App info -> Termux (most standard across vendors).
  android_start_activity -a android.settings.APPLICATION_DETAILS_SETTINGS -d "package:${TERMUX_PACKAGE}"
}

android_open_battery_optimization_list() {
  # Optional fallback screen (varies by vendor).
  android_start_activity -a android.settings.IGNORE_BATTERY_OPTIMIZATION_SETTINGS
}

power_mode_battery_instructions() {
  local fd=1
  if { : >&3; } 2>/dev/null; then fd=3; fi
  {
    printf '%b' "\n${YEL}${BOLD}[iiab] IMPORTANT: Android Battery Restrictions${RST}\n"
    printf '%b' "To prevent Android from killing the installation, apply:\n"
    printf '%b' "  ${BLU}1.${RST} Battery -> ${BOLD}Unrestricted${RST} (or 'Don't optimize')\n"
    printf '%b' "  ${BLU}2.${RST} Allow background activity -> ${BOLD}ON${RST}\n\n"
   } >&"$fd"
}

power_mode_offer_battery_settings_once() {
  [[ "${POWER_MODE_BATTERY_PROMPT:-1}" -eq 1 ]] || return 0
  if [[ -f "${ANDROID_SHARED_STATE_DIR}/flag_perm_battery" ]]; then
    return 0
  fi

  mkdir -p "$STATE_DIR" >/dev/null 2>&1 || true

  local stamp="$POWER_MODE_BATTERY_STAMP"
  [[ -f "$stamp" ]] && return 0

  local outfd; outfd="$(console_outfd)"
  power_mode_battery_instructions
  countdown_timer 5 "\r${YEL}[iiab] Opening Battery Settings in %d seconds...${RST}"

  if android_open_termux_app_info; then
    printf "${YEL}[iiab] Adjust the settings. When done, return here.${RST}\n" >&"$outfd"
    if [[ -r /dev/tty ]]; then
      # -n 1 captures a single character, -s makes it silent
      read -n 1 -s -r -p "Press any key to continue... " </dev/tty || true
      printf "\n" >&"$outfd"
    else
      printf "\n" >&"$outfd"
    fi
    date > "$stamp" 2>/dev/null || true
  else
    warn "Unable to open Settings automatically. Open manually: Settings -> Apps -> Termux."
    android_open_battery_optimization_list || true
  fi
  return 0
}

# -------------------------
# Set Display Over Other Apps (Overlay) step.
# -------------------------
POWER_MODE_OVERLAY_STAMP="${STATE_DIR}/stamp.termux_overlay_settings"

power_mode_offer_overlay_settings_once() {
  [[ "${POWER_MODE_OVERLAY_PROMPT:-1}" -eq 1 ]] || return 0
  if [[ -f "${ANDROID_SHARED_STATE_DIR}/flag_perm_overlay" ]]; then
    return 0
  fi

  mkdir -p "$STATE_DIR" >/dev/null 2>&1 || true

  local stamp="$POWER_MODE_OVERLAY_STAMP"
  [[ -f "$stamp" ]] && return 0

  local outfd; outfd="$(console_outfd)"
  local sdk="${ANDROID_SDK:-}"

  # Stage 1 (Android 13+ only): The One-Step Restricted Settings & Overlay bypass
  if [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 33 )); then
    {
      printf '%b' "\n${YEL}${BOLD}[iiab] Android 13+ Security Requirement${RST}\n"
      printf '%b' "Android restricts background permissions for sideloaded apps.\n"
      printf '%b' "For this to work, follow these 5 steps:\n\n"
      printf '%b' "  ${BLU}1.${RST} Tap on ${BOLD}'Display over other apps'${RST}\n     and toggle the switch.\n"
      printf '%b' "  ${BLU}2.${RST} A security warning will pop up. Tap ${BOLD}'OK'${RST}.\n"
      printf '%b' "  ${BLU}3.${RST} Go ${BOLD}BACK${RST} to the main screen (App info).\n"
      printf '%b' "  ${BLU}4.${RST} Now, on the top right you'll see ${BOLD}3 dots (⋮)${RST}\n     tap them and select ${BOLD}'Allow restricted settings'${RST}.\n"
      printf '%b' "  ${BLU}5.${RST} Finally you can go and enable\n     ${BOLD}'Display over other apps'${RST}.\n\n"
    } >&"$outfd"

    printf "\r${YEL}[iiab] Press Enter to open App Info when ready...${RST}\n"
    if [[ -r /dev/tty ]]; then
      # We use normal read (with Enter) to give the user time to read and return
      read -r _ </dev/tty || true
    fi

    if android_open_termux_app_info; then
      printf "${YEL}[iiab] When done, return here and press Enter to continue...${RST}\n" >&"$outfd"
      if [[ -r /dev/tty ]]; then
        # We use normal read (with Enter) to give the user time to read and return
        read -r _ </dev/tty || true
      fi
      printf "\n" >&"$outfd"
      date > "$stamp" 2>/dev/null || true
    else
      warn "Unable to open Settings automatically."
    fi

  # Stage 2 (Android 12 and below): Direct Overlay Permission
  else
    {
      printf '%b' "\n${YEL}${BOLD}[iiab] UX REQUIREMENT: Bring to Foreground${RST}\n"
      printf '%b' "To allow the IIAB Controller App to open Termux automatically:\n"
      printf '%b' "  Please grant the ${BOLD}'Display over other apps'${RST} permission.\n\n"
    } >&"$outfd"

    countdown_timer 5 "\r${YEL}[iiab] Opening Overlay Settings in %d seconds...${RST}"

    if android_open_overlay_settings; then
      printf "${YEL}[iiab] Enable the switch. When done, return here.${RST}\n" >&"$outfd"
      if [[ -r /dev/tty ]]; then
        read -n 1 -s -r -p "Press any key to continue... " </dev/tty || true
        printf "\n" >&"$outfd"
      else
        printf "\n" >&"$outfd"
      fi
      date > "$stamp" 2>/dev/null || true
    else
      warn "Unable to open Settings automatically."
    fi
  fi

  return 0
}

# -------------------------
# One-time repo selector
# -------------------------
repo_selector__mirror_base_dir() {
  echo "${PREFIX}/etc/termux/mirrors"
}

repo_selector__chosen_path() {
  echo "${PREFIX}/etc/termux/chosen_mirrors"
}

repo_selector__is_all_mirrors() {
  # Returns 0 if in "All mirrors" mode, 1 otherwise.
  local chosen; chosen="$(repo_selector__chosen_path)"

  # Missing -> treat as all mirrors.
  [[ -e "$chosen" || -L "$chosen" || -d "$chosen" ]] || return 0

  # Broken symlink -> pkg treats as all mirrors.
  if [[ -L "$chosen" ]] && [[ ! -e "$chosen" ]]; then
    return 0
  fi

  # If it resolves to mirrors/all, treat as all mirrors (in some installs it exists).
  local base; base="$(repo_selector__mirror_base_dir)"
  local resolved=""
  resolved="$(readlink -f "$chosen" 2>/dev/null || true)"
  if [[ -n "$resolved" && "$resolved" == "$base/all" ]]; then
    return 0
  fi

  return 1
}

repo_selector__android_country_code() {
  # Best-effort ISO-3166-1 alpha-2 (e.g. MX, US, CN, RU). Empty if unknown.
  local v=""
  for k in \
    gsm.operator.iso-country \
    gsm.sim.operator.iso-country \
    persist.sys.country \
    ro.product.locale.region \
    ro.boot.wificountrycode \
  ; do
    v="$(getprop "$k" 2>/dev/null | tr -d '\r' | tr '[:lower:]' '[:upper:]')"
    [[ -n "$v" ]] && { echo "$v"; return 0; }
  done
  return 1
}

repo_selector__android_timezone() {
  getprop persist.sys.timezone 2>/dev/null | tr -d '\r'
}

repo_selector__detect_group() {
  # Echo one of: asia|chinese_mainland|europe|north_america|oceania|russia
  # or empty if unknown.
  local cc=""; cc="$(repo_selector__android_country_code 2>/dev/null || true)"
  case "$cc" in
    CN) echo "chinese_mainland"; return 0 ;;
    RU) echo "russia"; return 0 ;;
  esac

  local tz=""; tz="$(repo_selector__android_timezone)"
  case "$tz" in
    Asia/*)      echo "asia"; return 0 ;;
    Europe/*)    echo "europe"; return 0 ;;
    Africa/*)    echo "europe"; return 0 ;;   # closest available group
    America/*)   echo "north_america"; return 0 ;;
    Australia/*) echo "oceania"; return 0 ;;
    Pacific/*)   echo "oceania"; return 0 ;;
    *)           return 1 ;;
  esac
}

repo_selector__label_for_group() {
  # args: group_id [tz_hint]
  local g="$1" tz="${2:-}"
  case "$g" in
    russia)           echo "Russia" ;;
    chinese_mainland) echo "Chinese (Mainland)" ;;
    asia)             echo "Asia" ;;
    europe)
      # If timezone suggests Africa, show that we chose Europe as closest.
      if [[ "$tz" == Africa/* ]]; then
        echo "Europe (Closest)"
      else
        echo "Europe"
      fi
      ;;
    north_america)    echo "North America" ;;
    oceania)          echo "Oceania" ;;
    all)              echo "All mirrors" ;;
    *)                echo "$g" ;;
  esac
}

repo_selector__apply_group() {
  local group="$1"
  local base chosen target
  base="$(repo_selector__mirror_base_dir)"
  chosen="$(repo_selector__chosen_path)"
  target="${base}/${group}"

  if [[ ! -d "$target" ]]; then
    warn "Repo group dir not found: $target"
    return 1
  fi

  # Remove existing chosen_mirrors if it's a symlink (same behavior as termux-change-repo).
  if [[ -L "$chosen" ]]; then
    unlink "$chosen" 2>/dev/null || rm -f "$chosen" 2>/dev/null || true
  elif [[ -e "$chosen" ]]; then
    # Unexpected: file/dir created by user. Don't delete; just warn and stop.
    warn "chosen_mirrors exists and is not a symlink: $chosen (leaving unchanged)"
    return 1
  fi

  ln -s "$target" "$chosen"

  # Force pkg to re-pick mirror from the new group and rewrite apt sources now.
  # Same intent as termux-change-repo's final step.
  ok "Repo group set: $group (chosen_mirrors -> $target)"
  pkg --check-mirror update || true
}

repo_selector_ask_configure() {
  local group="" tz="" label=""

  # Only run if still on "All mirrors".
  if ! repo_selector__is_all_mirrors; then
    return 0
  fi

  log "Configuring Termux repository location..."
  tz="$(repo_selector__android_timezone)"
  group="$(repo_selector__detect_group 2>/dev/null || true)"
  label="$(repo_selector__label_for_group "$group" "$tz")"

  if [[ -z "$group" ]]; then
    warn "Unable to detect region reliably."
    warn "Tip: run 'termux-change-repo' to select a nearby mirror group manually."
    return 0
  fi

  log "Detected repo group: "
  printf "> ${BOLD}${BLU}$label${RST}\n"
  # Auto-apply to optimize zero-touch installation
  log "Automatically applying this mirror group to optimize downloads."
  repo_selector__apply_group "$group" || true
  ok "Region repo set. You can always change it later by running: termux-change-repo"
}

# -------------------------
# Baseline packages
# -------------------------
step_termux_base() {
  local stamp="$STATE_DIR/stamp.termux_base"

  BASELINE_OK=0

  # Even if we have a stamp, validate that core commands still exist.
  if [[ -f "$stamp" ]]; then
    if baseline_prereqs_ok; then
      BASELINE_OK=1
      ok "Termux baseline already prepared (stamp found)."
      if declare -f python_patch_sysconfig_armv8l > /dev/null; then
        # Safe call: check if declared at 15_mod_prepatch_env.sh
        python_patch_sysconfig_armv8l
      fi
      # Ensure optional mDNS deps are ready from the start (does not affect stamp).
      termux_prepare_mdns_deps || true
      # Ensure boxyproxy deps are ready from the start (does not affect stamp).
      termux_prepare_boxyproxy_deps || true
      return 0
    fi
    warn "Baseline stamp found but prerequisites are missing; forcing reinstall."
    rm -f "$stamp"
  fi

# Enable communication with Controller APK
  local props="${HOME}/.termux/termux.properties"
  mkdir -p "${HOME}/.termux"
  touch "$props"

  if ! grep -qE '^allow-external-apps\s*=\s*true' "$props"; then
    log "Enabling allow-external-apps for the IIAB Controller..."

    if grep -qE '^#?\s*allow-external-apps\s*=' "$props"; then
      sed -i 's/^#\?\s*allow-external-apps\s*=.*/allow-external-apps = true/' "$props"
    else
      echo "allow-external-apps = true" >> "$props"
    fi
    have termux-reload-settings && termux-reload-settings || true
  fi

  # Test if the APK already granted us real Android storage access
  if touch /sdcard/.iiab_storage_test 2>/dev/null; then
    rm -f /sdcard/.iiab_storage_test

    # We have access! Just ensure the Termux symlinks exist silently.
    if [[ ! -d "${HOME}/storage/shared" ]]; then
      termux-setup-storage
      sleep 1 # Give it a second to create symlinks
    fi
    ok "Storage access already granted (Managed by IIAB Controller)."
  else
    log_yel "Termux needs storage access to communicate with the IIAB Controller App."
    warn "An Android permission dialog will appear."
    warn "Please tap 'Allow' (or 'All files access')."
    termux-setup-storage
    # termux-setup-storage is asynchronous, so we must pause to let the user tap 'Allow'
    countdown_timer 10 "\r${BLU}[iiab]${RST} Waiting for storage permission... %d secs "
  fi

  log "Updating Termux packages (noninteractive) and installing baseline dependencies..."
  export DEBIAN_FRONTEND=noninteractive

  if ! termux_apt update; then
    BASELINE_ERR="termux_apt update"
    baseline_bail_details
    return 1
  fi

  if ! termux_apt upgrade; then
    BASELINE_ERR="termux_apt upgrade"
    baseline_bail_details
    return 1
  fi

  local pkgs=(
    android-tools
    aria2
    ca-certificates
    coreutils
    curl
    gawk
    git
    grep
    jq
    libqrencode
    openssh
    proot
    proot-distro
    python
    rsync
    sed
    termux-api
    which
  )
  baseline_need_python && pkgs+=(python)

  if ! termux_apt install "${pkgs[@]}"; then
    BASELINE_ERR="termux_apt install (baseline deps)"
    baseline_bail_details
    return 1
  fi

  if declare -f python_patch_sysconfig_armv8l > /dev/null; then
    # Safe call: check if declared at 15_mod_prepatch_env.sh
    python_patch_sysconfig_armv8l
  fi

  if baseline_prereqs_ok; then
    BASELINE_OK=1
    ok "Termux baseline ready."
    # Prepare Python zeroconf *now* if mDNS autodetect is enabled.
    termux_prepare_mdns_deps || true
    # Prepare aiohttp now so proxy-start is reliable.
    termux_prepare_boxyproxy_deps || true
    date > "$stamp"
    return 0
  fi

  BASELINE_ERR="post-install check (commands missing after install)"
  baseline_bail_details
  return 1
}

# -------------------------
# Python + zeroconf prep (Android 11+)
# -------------------------
step_termux_python_zeroconf() {
  baseline_need_python || return 0
  if [[ -f "$TERMUX_ZEROCONF_STAMP" ]] && python_has_zeroconf; then
    return 0
  fi
  [[ -f "$TERMUX_ZEROCONF_STAMP" ]] && rm -f "$TERMUX_ZEROCONF_STAMP" >/dev/null 2>&1 || true

  if ! have python; then
    warn "Android 11+: python is expected but missing; skipping zeroconf prep."
    return 0
  fi

  termux_prepare_mdns_deps
  python_has_zeroconf && date > "$TERMUX_ZEROCONF_STAMP" 2>/dev/null || true
}

# ---- END 20_mod_termux_base.sh ----


# ---- BEGIN 25_mod_backup_restore.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

get_android_arch() {
  case "$(uname -m)" in
    aarch64)       echo "arm64-v8a" ;;
    armv7l|armv8l) echo "armeabi-v7a" ;;
    x86_64)        echo "x86_64" ;;
    i686)          echo "x86" ;;
    *)             echo "unknown" ;;
  esac
}

cmd_list_backups() {
  local json_content="{\"backups\": ["
  local first=1

  # Use a while loop to iterate over all ls results sorted by date
  while IFS= read -r file; do
    [[ -n "$file" && -f "$file" ]] || continue

    local filename="${file##*/}"
    local size; size="$(du -h "$file" | awk '{print $1}')"

    local date_str
    if date --version >/dev/null 2>&1; then
      date_str="$(date -r "$file" +"%Y-%m-%d %H:%M")"
    else
      local epoch; epoch="$(stat -c %Y "$file")"
      date_str="$(date -d "@$epoch" +"%Y-%m-%d %H:%M" 2>/dev/null || echo "Unknown")"
    fi

    # Handle commas for JSON formatting
    if [[ $first -eq 1 ]]; then
      first=0
    else
      json_content+=","
    fi
    
    # Add the object to the array
    json_content+="{\"filename\": \"$filename\", \"size\": \"$size\", \"date\": \"$date_str\"}"
  done < <(ls -1t "${HOME}"/iiab-android_rootfs_*.tar.gz 2>/dev/null || true)

  json_content+="]}"

  # --- BEHAVIOR DUALITY ---
  if [[ "${INTENT_MODE:-}" == "headless" ]]; then
    mkdir -p "$ANDROID_SHARED_STATE_DIR" 2>/dev/null || true
    echo "$json_content" > "${ANDROID_SHARED_STATE_DIR}/backups_list.json"

    if command -v am >/dev/null 2>&1; then
       sleep 1
       am start -n org.iiab.controller/org.iiab.controller.MainActivity >/dev/null 2>&1 || true
    fi
  else
    echo "$json_content"
  fi
}

cmd_backup_rootfs() {
  local custom_path="${1:-}"
  local out_file

  have proot-distro || die "proot-distro is not installed. Run the baseline first."
  iiab_exists || die "IIAB Debian (alias 'iiab') is not installed. Nothing to backup."

  if [[ -n "$custom_path" ]]; then
    out_file="$custom_path"
  else
    local ts arch
    # Format: YYYY.DDD.HHMM (Day of year: %j)
    ts="$(date -u +"%Y.%j.%H%M")"
    arch="$(get_android_arch)"
    out_file_name="iiab-android_rootfs_${ts}_${arch}.tar.gz"
    out_file_path="${HOME}/$out_file_name"
  fi

  log "Starting backup of IIAB Debian..."
  log "Destination: $out_file_path"

  if proot-distro backup iiab --output "$out_file_path"; then
    ok "Backup completed successfully: $out_file_name"
  else
    warn_red "Failed to create backup."
    return 1
  fi
}

cmd_restore_rootfs() {
  local backup_file="${1:-}"
  rm -f "${ANDROID_SHARED_STATE_DIR}/restore_error_flag" 2>/dev/null || true

  [[ -z "$backup_file" ]] && die "You must specify the path to the backup file to restore."
  [[ -f "$backup_file" ]] || die "Backup file does not exist: $backup_file"

  if [[ -z "$backup_file" || ! -f "$backup_file" ]]; then
    if [[ "${INTENT_MODE:-}" == "headless" ]]; then
      mkdir -p "$ANDROID_SHARED_STATE_DIR" 2>/dev/null || true
      touch "${ANDROID_SHARED_STATE_DIR}/restore_error_flag"
      # Pause for android parsing
      sleep 2
    fi
    die "Backup file does not exist: $backup_file"
  fi

  have proot-distro || die "proot-distro is not installed."

  log "Restoring IIAB Debian from: $backup_file"

  if iiab_exists; then
    log_yel "Restoration will overwrite the current system."
  fi


  if proot-distro restore "$backup_file"; then
    ok "Restoration completed successfully."
    BASELINE_OK=1

    # Sync state to Android App: Restored and ready!
    set_android_state_flag "flag_system_installed"
    set_android_state_flag "flag_iiab_ready"
  else
    if [[ "${INTENT_MODE:-}" == "headless" ]]; then
      touch "${ANDROID_SHARED_STATE_DIR}/restore_error_flag"
      sleep 2
    fi
    warn_red "Failed to restore backup."
    return 1
  fi
}

check_url_architecture() {
  local url="$1" dev_arch="$2" allow_mismatch="$3"
  local url_lower; url_lower="$(printf '%s' "$url" | tr '[:upper:]' '[:lower:]')"

  local count=0 detected=""

  # Identification by keywords
  if [[ "$url_lower" == *arm64* || "$url_lower" == *aarch64* || "$url_lower" == *v8a* ]]; then
    detected="arm64-v8a"; count=$((count + 1))
  fi
  if [[ "$url_lower" == *armv7* || "$url_lower" == *v7a* || "$url_lower" == *armeabi* ]]; then
    detected="armeabi-v7a"; count=$((count + 1))
  fi
  if [[ "$url_lower" == *x86_64* || "$url_lower" == *amd64* ]]; then
    detected="x86_64"; count=$((count + 1))
  elif [[ "$url_lower" == *x86* || "$url_lower" == *i686* || "$url_lower" == *i386* ]]; then
    detected="x86"; count=$((count + 1)) # Excluded if x86_64 matched
  fi

  # Case B: None or a contradictory mixture
  if (( count == 0 )); then
   log_yel "Cannot verify device compatibility from URL or Meta4."
   log_yel "Proceed only if you trust this file matches your device ($dev_arch)."
   read -r -p "Press [Enter] to continue, or [Ctrl+C] to cancel... "
   return 0
  elif (( count > 1 )); then
   log_yel "Contradictory architectures detected between URL and Meta4!"
   log_yel "Proceed only if you trust this file matches your device ($dev_arch)."
   read -r -p "Press [Enter] to continue, or [Ctrl+C] to cancel... "
   return 0
  fi

  # Case A: Exact match (Silent to avoid screen clutter)
  [[ "$detected" == "$dev_arch" ]] && return 0

  # Case C: Clear mismatch
  if [[ "$allow_mismatch" -eq 1 ]]; then
    log_yel "Arch mismatch ($detected vs $dev_arch) ignored via --arch-mismatch-ok."
    return 0
  else
    warn_red "The target file indicates an architecture ($detected) that doesn't match your device ($dev_arch)."
    die "To proceed anyway, run again with: --arch-mismatch-ok"
  fi
}

cmd_pull_rootfs() {
  local target_url="${1:-}"
  local use_meta4="${2:-1}"  # 1 = yes, 0 = no (--no-meta4)
  local keep_tarball="${3:-0}" # 1 = keep, 0 = delete (default)
  local arch_mismatch_ok="${4:-0}"

  if [[ -z "$target_url" || "$target_url" == "AUTO" ]]; then
    local arch
    arch="$(get_android_arch)"

    if [[ "$arch" == "arm64-v8a" ]]; then
      target_url="$IIAB_ROOTFS_URL_ARM64"
    elif [[ "$arch" == "armeabi-v7a" ]]; then
      target_url="$IIAB_ROOTFS_URL_ARM32"
    else
      die "Architecture not supported for automatic download: $arch. Specify a URL manually."
    fi

    log "Automatically selecting base image for $arch:"
    log "> $target_url"
  fi

  [[ -z "$target_url" ]] && die "You must provide a URL to download the rootfs."

  # Ensure aria2 and curl are available
  have aria2c || { log "Installing aria2..."; termux_apt update || true; termux_apt install aria2 || die "Failed to install aria2."; }
  have curl || { log "Installing curl..."; termux_apt install curl || die "Failed to install curl."; }

  local dest_dir="${STATE_DIR}/downloads"
  mkdir -p "$dest_dir"

 log "Resolving target URL and checking availability..."
 local curl_out; curl_out=$(curl -sLI -o /dev/null -w "%{http_code}|%{url_effective}" "$target_url" || true)
 local http_code="${curl_out%%|*}"
 local download_url="${curl_out##*|}"

 # Fail quickly if the link is broken or misspelled.
 if [[ "$http_code" == "404" ]]; then
   die "HTTP 404 Not Found: There is nothing here. Please verify the URL for typos."
 elif [[ "$http_code" == "000" || -z "$http_code" ]]; then
   die "Connection failed: Could not reach the server. Please check your internet or the URL."
 elif [[ "$http_code" -ge 400 ]]; then
   die "HTTP Error $http_code: Unable to access the requested file."
 fi

 [[ -z "$download_url" ]] && download_url="$target_url"

  if [[ "$download_url" != "$target_url" ]]; then
    log "Resolved to: $download_url"
  fi

  # Meta4 Logic
  if [[ "$use_meta4" -eq 1 ]]; then
    if [[ "$download_url" == *.meta4 ]]; then
      log "URL directly provides a .meta4 file."
    else
      if curl -IsLf "${download_url}.meta4" > /dev/null 2>&1; then
        download_url="${download_url}.meta4"
      else
        log_yel "No .meta4 file found. Falling back to direct download."
      fi
    fi
  else
    log "Mode --no-meta4 is active. Skipping Metalink check."
  fi

  local dht_file="${STATE_DIR}/dht.dat"

  # UX trick: "Preheat" DHT before execution.
  if [[ ! -f "$dht_file" ]]; then
    aria2c --enable-dht=true \
           --dht-file-path="$dht_file" \
           --stop=1 \
           "magnet:?xt=urn:btih:0123456789abcdef0123456789abcdef01234567" \
           >/dev/null 2>&1 || true
  fi

  # 1. Determine local file name
  local file_name=""
  local expected_name="${target_url##*/}"
  expected_name="${expected_name%.meta4}"

  if [[ "$use_meta4" -eq 1 && "$download_url" == *.meta4 ]]; then
    # Parse the <name> or fallback to the file part of the first <url>
    file_name=$(curl -sL "$download_url" | awk -F'[<>]' '/<name>/ && !found {print $3; found=1}' | tr -d '\r ' || true)
    if [[ -z "$file_name" ]]; then
      local meta_url; meta_url=$(curl -sL "$download_url" | awk -F'[<>]' '/<url.*>/ && !found {print $3; found=1}' | tr -d '\r ' || true)
      file_name="${meta_url##*/}"
    fi

   # Validate meta4 content matches requested tarball (if a tarball was originally requested)
   if [[ "$target_url" != *.meta4 && "$file_name" != "$expected_name" ]]; then
     log_yel "Meta4 content ($file_name) does not match requested tarball ($expected_name)."
     log_yel "Discarding .meta4 and falling back to direct download."
     download_url="${download_url%.meta4}"
     file_name="$expected_name"
   fi
  fi

  if [[ -z "$file_name" ]]; then
    file_name="${download_url##*/}"     # Extract filename from URL
    file_name="${file_name%.meta4}"     # Strip .meta4 extension if present
  fi

 # --- DEFINITIVE ARCHITECTURE CHECKUP ---
 # We check both the original target URL and the final resolved file_name.
 # This detects missing info OR contradictory info across both sources.
 check_url_architecture "${target_url} | ${file_name}" "$(get_android_arch)" "$arch_mismatch_ok"

  local out_path="${dest_dir}/${file_name}"

  # Smart Toggle: verify integrity only if available.
  local check_int="false"
  if [[ -f "$out_path" ]]; then
    log "Local file detected ($file_name). Verifying integrity via P2P/Metalink..."
    check_int="true"
  fi

  # 2. Check size before downloading
  local remote_bytes=""

  # Priority 1: Get exact size directly from the Metalink XML file
  if [[ "$use_meta4" -eq 1 && "$download_url" == *.meta4 ]]; then
    log "Fetching image size from Metalink file..."
    # Downloads the XML, finds the <size> tag, extracts the number, and cleans any carriage returns
    remote_bytes=$(curl -sL "$download_url" | awk -F'[<>]' '/<size>/ && !found {print $3; found=1}' | tr -d '\r ' || true)
  fi

  # Priority 2: Fallback to HTTP headers
  if [[ -z "$remote_bytes" ]]; then
    log "Checking image size via HTTP headers..."
    local size_url="${download_url%.meta4}"
    # Follow redirects (-L) and safely parse with awk to survive 'set -e pipefail'
    remote_bytes=$(curl -sIL "$size_url" | awk 'tolower($1) ~ /^content-length/ {print $2}' | tail -n 1 | tr -d '\r' || true)
  fi || true

  # Get free space in MB
  local free_mb; free_mb=$(df -k "$PREFIX" | awk 'END{print $4 / 1024}' | cut -d. -f1)

  if [[ -n "$remote_bytes" ]]; then
     local req_space=$(( remote_bytes * 25 / 10 / 1048576 )) # 2.5x in MB
     # Floor fallback: ensure at least 5GB for pull-rootfs
     [[ "$req_space" -lt 5120 ]] && req_space=5120
     local img_gb; img_gb=$(awk -v bytes="$remote_bytes" 'BEGIN { printf "%.2f", bytes / 1073741824 }')
     local req_gb; req_gb=$(awk -v mb="$req_space" 'BEGIN { printf "%.2f", mb / 1024 }')
     local free_gb_disp; free_gb_disp=$(awk -v mb="$free_mb" 'BEGIN { printf "%.2f", mb / 1024 }')
     log "Image size: ${img_gb} GB. Safety threshold: ${req_gb} GB."

     if [[ "$free_mb" -lt "$req_space" ]]; then
        die "Insufficient space! You need ${req_gb} GB, but only ${free_gb_disp} GB are free."
     fi
  else
     # Fallback if server doesn't report size
     log_yel "Could not determine remote size. Applying 5.00 GB safety floor."
     if [[ "$free_mb" -lt 5120 ]]; then
        local free_gb_disp; free_gb_disp=$(awk -v mb="$free_mb" 'BEGIN { printf "%.2f", mb / 1024 }')
        die "Risk of saturation! At least 5.00 GB free required when size is unknown (You have ${free_gb_disp} GB)."
     fi
  fi

  log "Downloading rootfs..."

  # Mimic aria2 arguments in ansible playbooks
  local aria_args=(
    # --- Dirs and files ---
    "--dir=$dest_dir"
    "--continue=true"
    "--allow-overwrite=false"
    "--auto-file-renaming=false"

    # --- Connections and performance ---
    "--max-connection-per-server=4"
    "--file-allocation=falloc"
    "--enable-http-pipelining=true"
    "--async-dns=false"
    "--connect-timeout=60"

    # --- P2P & metalink ---
    "--follow-metalink=mem"
    "--enable-dht=true"
    "--dht-file-path=$dht_file"
    "--bt-enable-lpd=true"
    "--check-integrity=$check_int"
    "--seed-time=0"

    # --- Console output & logs ---
    "--log-level=warn"
    "--console-log-level=warn"
    "--summary-interval=0"
    "--show-console-readout=true"
    "--download-result=hide"

    # --- Target ---
    "$download_url"
  )

  # Run aria2 bypassing the log to maintain the interactive bar
  if : >&3 2>/dev/null && : >&4 2>/dev/null; then
    aria2c "${aria_args[@]}" >&3 2>&4 || die "aria2 download failed."
  else
    aria2c "${aria_args[@]}" || die "aria2 download failed."
  fi

  # As a fallback, ensure the targeted file actually exists
  if [[ ! -f "$out_path" ]]; then
    log_yel "Expected file not found at $out_path, scanning directory..."
    out_path=$(ls -1t "$dest_dir"/*.tar.gz 2>/dev/null | head -n 1 || true)
    if [[ -z "$out_path" || ! -f "$out_path" ]]; then
      die "Download finished, but no .tar.gz file was found in $dest_dir"
    fi
  fi

  ok "Download finished: $out_path"

  # Proceed with restoration
  cmd_restore_rootfs "$out_path"

  # --- POST-RESTORE CLEANUP ---
  if [[ "$keep_tarball" -eq 1 ]]; then
    ok "Flag '--keep-tarball' active. Keeping rootfs archive at: $out_path"
  else
    # 1. Gather stats before deletion
    local count; count=$(ls -1 "$dest_dir"/*.tar.gz 2>/dev/null | wc -l)
    local folder_size; folder_size=$(du -sm "$dest_dir" 2>/dev/null | awk '{printf "%.2f GB", $1 / 1024}')
    if rm -f "$dest_dir"/*.tar.gz >/dev/null 2>&1; then
      local final_free; final_free=$(df -h "$PREFIX" | awk 'END{print $4}')
      ok "Space freed: $folder_size out of $count tarball(s)."
      log "Remaining free space: $final_free"
      log "Tip: Use '--keep-tarball' next time to preserve the downloaded images."
    else
      warn "Cleanup failed. Please check permissions in $dest_dir"
    fi
  fi
}

# ---- END 25_mod_backup_restore.sh ----


# ---- BEGIN 30_mod_iiab-debian.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

# -------------------------
# IIAB Debian bootstrap
# -------------------------
iiab_exists() {
  have proot-distro || return 1
  proot-distro login iiab -- true >/dev/null 2>&1
}

cmd_remove_iiab() {
  have proot-distro || die "proot-distro is not installed."

  if ! iiab_exists; then
    log "IIAB Debian (alias 'iiab') is not installed. Nothing to remove."
    return 0
  fi

  warn_red "This will completely delete the IIAB Debian rootfs and ALL its data."
  if tty_yesno_default_n "[iiab] Are you sure you want to remove IIAB Debian? [y/N]: "; then
    log "Removing IIAB Debian..."
    proot-distro remove iiab || { warn_red "Failed to remove IIAB Debian."; return 1; }
    ok "IIAB Debian successfully removed."

    # Sync state to Android App: System is gone
    clear_android_state_flag "flag_system_installed"
    clear_android_state_flag "flag_iiab_ready"
  else
    log "Removal aborted by user."
  fi
}

ensure_proot_distro() {
  if have proot-distro; then return 0; fi
  warn "proot-distro not found; attempting to install..."
  termux_apt install proot-distro || true
  have proot-distro
}

proot_install_iiab_safe() {
  local out rc
  set +e

  local help
  help="$(proot-distro install --help 2>&1 || true)"
  if ! printf '%s\n' "$help" | grep -q -- '--override-alias'; then
    warn_red "proot-distro is too old (missing --override-alias). Please upgrade Termux packages and retry."
    return 1
  fi

  if [[ "${INTENT_MODE:-}" == "headless" ]]; then
    log_yel "Headless mode: Using tmux to provide a virtual PTY to PRoot..."
    have tmux || termux_apt install tmux >/dev/null 2>&1 || true
    # Launch proot-distro encapsulated in a virtual session (real PTY guaranteed)
    tmux new-session -d -s iiab_setup "proot-distro install --override-alias iiab debian"
    log "Extracting and configuring base system (this will take a few minutes)..."
    while tmux has-session -t iiab_setup 2>/dev/null; do
        sleep 3
        printf "."
    done
    echo ""
    # Verify if the virtual installation was successful
    if iiab_exists; then
        rc=0
    else
        rc=1
        out="Fatal failure inside the tmux session."
    fi
  else
    out="$(proot-distro install --override-alias iiab debian 2>&1)"
    rc=$?
  fi

  set -e
  if [[ $rc -eq 0 ]]; then return 0; fi
  if echo "$out" | grep -qi "already installed"; then
    warn "IIAB Debian is already installed; continuing."
    return 0
  fi
  printf "%s\n" "$out" >&2
  return $rc
}

step_iiab_bootstrap_default() {
  if ! ensure_proot_distro; then
    warn "Unable to ensure proot-distro; skipping IIAB Debian bootstrap."
    return 0
  fi

  if [[ "$RESET_IIAB" -eq 1 ]]; then
    log_yel "Reset requested: reinstalling IIAB Debian (clean environment)..."
    if proot-distro help 2>/dev/null | grep -qE '\breset\b'; then
      proot-distro reset iiab || true

      # Sync state to Android App: Old system wiped
      clear_android_state_flag "flag_system_installed"
      clear_android_state_flag "flag_iiab_ready"

      # If reset was requested but iiab wasn't installed yet (or reset failed), ensure it's present.
      iiab_exists || proot_install_iiab_safe || true
    else
      if iiab_exists; then
        proot-distro remove iiab || true
        clear_android_state_flag "flag_system_installed"
        clear_android_state_flag "flag_iiab_ready"
      fi
      proot_install_iiab_safe || true
    fi
  else
    if iiab_exists; then
      ok "IIAB Debian already present in proot-distro. Not reinstalling."
    else
      log "Installing IIAB Debian (proot-distro install --override-alias iiab debian)..."
      proot_install_iiab_safe || true
    fi
  fi

  log "Installing minimal tools inside IIAB Debian (noninteractive)..."
  if ! iiab_exists; then
    warn_red "IIAB Debian is not available in proot-distro (install may have failed). Rerun later."
    return 0
  fi
  local rc=0
  set +e
  proot-distro login iiab -- bash -lc '
    set -e
    export DEBIAN_FRONTEND=noninteractive
    apt-get update
    apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold \
      install ca-certificates \
              coreutils \
              curl \
              e2fsprogs \
              iputils-ping \
              netcat-traditional \
              sudo
  '
  rc=$?
  set -e
  if [[ $rc -eq 0 ]]; then
    ok "IIAB Debian bootstrap complete."

    # Sync state to Android App: System is ready!
    set_android_state_flag "flag_system_installed"
  else
    warn_red "IIAB Debian bootstrap incomplete (inner apt-get failed, rc=$rc)."
    warn "You can retry later with: iiab-termux --login"
  fi
}


install_iiab_android_cmd() {
  have proot-distro || die "proot-distro not found"
  iiab_exists || { warn_red "IIAB Debian (alias 'iiab') not installed."; return 1; }

  local url="${IIAB_ANDROID_URL:-https://raw.githubusercontent.com/iiab/iiab-android/main/iiab-android}"
  local dest="${IIAB_ANDROID_DEST:-/usr/local/sbin/iiab-android}"
  local tmp="/tmp/iiab-android.$$"

  local meta old new rc=0
  set +e
  meta="$(proot-distro login iiab -- env URL="$url" DEST="$dest" TMP="$tmp" bash -lc '
    set -e
    old=""
    if [ -r "$DEST" ]; then old="$(sha256sum "$DEST" 2>/dev/null | cut -d" " -f1 || true)"; fi
    if ! command -v curl >/dev/null 2>&1; then
      export DEBIAN_FRONTEND=noninteractive
      apt-get update
      apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold install ca-certificates curl coreutils
    fi
    curl -fsSL --retry 5 --retry-connrefused --retry-delay 2 "$URL" -o "$TMP"
    head -n1 "$TMP" | grep -q "bash" || { echo "BAD_SHEBANG"; exit 2; }
    new="$(sha256sum "$TMP" | cut -d" " -f1)"
    echo "OLD=$old"
    echo "NEW=$new"
  ' 2>&1)"
  rc=$?
  set -e

  if (( rc != 0 )); then
    if printf '%s\n' "$meta" | grep -q 'BAD_SHEBANG'; then
      warn_red "Downloaded iiab-android does not look like a bash script (bad shebang)."
    else
      warn_red "Failed to fetch/install iiab-android in proot (rc=$rc)."
      printf "%s\n" "$meta" | indent >&2
    fi
    return 1
  fi

  old="$(printf '%s\n' "$meta" | sed -n 's/^OLD=//p' | head -n1)"
  new="$(printf '%s\n' "$meta" | sed -n 's/^NEW=//p' | head -n1)"

  if [[ -n "$old" && "$old" == "$new" ]]; then
    ok "iiab-android already up to date inside proot."
    proot-distro login iiab -- env TMP="$tmp" bash -lc 'rm -f "$TMP" >/dev/null 2>&1 || true' || true
    return 0
  fi

  if [[ -n "$old" && "$old" != "$new" ]]; then
    warn "iiab-android exists and differs inside proot."
    if ! tty_yesno_default_n "[iiab] Replace existing iiab-android inside proot? [y/N]: "; then
      warn "Keeping existing iiab-android."
      proot-distro login iiab -- env TMP="$tmp" bash -lc 'rm -f "$TMP" >/dev/null 2>&1 || true' || true
     return 0
    fi
  fi

  proot-distro login iiab -- env DEST="$dest" TMP="$tmp" bash -lc '
    set -e
    mkdir -p "$(dirname "$DEST")"
    if [ -f "$DEST" ]; then
      ts="$(date +%Y%m%d-%H%M%S 2>/dev/null || echo now)"
      mv -f "$DEST" "${DEST}.old.${ts}" 2>/dev/null || true
    fi
    install -m 0755 "$TMP" "$DEST"
    rm -f "$TMP" >/dev/null 2>&1 || true
  ' || { warn_red "Failed to finalize iiab-android install inside proot."; return 1; }

  ok "Installed inside proot: $dest"
  ok "Next (inside proot): iiab-android"
}

# ---- END 30_mod_iiab-debian.sh ----


# ---- BEGIN 40_mod_termux_api.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

# -------------------------
# Termux:API notifications + prompts
# -------------------------
NOTIF_BASE_ID=9400
NOTIF_SEQ=0
LAST_NOTIF_ID=""

# Termux:API sanity check (notifications)
termux_api_ready() {
  have termux-notification || return 1
  if have termux-notification-remove; then
    termux-notification-remove "$NOTIF_BASE_ID" >/dev/null 2>&1 || true
  fi
  return 0
}

sanitize_timeout() {
  # Ensure TIMEOUT_SECS is a positive integer
  if ! [[ "${TIMEOUT_SECS:-}" =~ ^[0-9]+$ ]]; then
    warn "Invalid --timeout='${TIMEOUT_SECS:-}'. Falling back to 180."
    TIMEOUT_SECS=180
  elif (( TIMEOUT_SECS < 5 )); then
    warn "Very low --timeout=${TIMEOUT_SECS}. Forcing minimum 5 seconds."
    TIMEOUT_SECS=5
  fi
}

cleanup_notif() {
  have termux-notification-remove || return 0
  termux-notification-remove "$NOTIF_BASE_ID" >/dev/null 2>&1 || true
  if [[ -n "${LAST_NOTIF_ID:-}" ]]; then
    termux-notification-remove "$LAST_NOTIF_ID" >/dev/null 2>&1 || true
  fi
}

notify_ask_one() {
  # args: key title content
  local key="$1" title="$2" content="$3"
  local out="$ADB_STATE_DIR/$key.reply"
  rm -f "$out" >/dev/null 2>&1 || true

  # Fresh notification each time + sound (use a new ID so Android plays sound each time)
  local nid
  nid=$((NOTIF_BASE_ID + 1 + NOTIF_SEQ))
  NOTIF_SEQ=$((NOTIF_SEQ + 1))
  LAST_NOTIF_ID="$nid"

  if have termux-notification-remove; then
    termux-notification-remove "$nid" >/dev/null 2>&1 || true
  fi

  # Direct reply: Termux:API injects the user input into $REPLY for the action.
  # Write it to a known file, then the main loop reads it.
  local action
  # Avoid brittle nested quoting by passing OUT via environment.
  # shellcheck disable=SC2016
  action="env OUT=\"$out\" sh -lc 'umask 077; printf %s \"\$REPLY\" > \"\$OUT\"'"

  termux-notification \
    --id "$nid" \
    --ongoing \
    --priority max \
    --title "$title" \
    --content "$content" \
    --sound \
    --button1 "Answer" \
    --button1-action "$action" \
    || return 1

  local start now reply
  start="$(date +%s)"

  while true; do
    if [[ -f "$out" ]]; then
      reply="$(tr -d '\r\n' < "$out" 2>/dev/null || true)"
      rm -f "$out" >/dev/null 2>&1 || true
      if have termux-notification-remove; then
        termux-notification-remove "$nid" >/dev/null 2>&1 || true
      fi
      printf '%s' "$reply"
      return 0
    fi

    now="$(date +%s)"
    if (( now - start >= TIMEOUT_SECS )); then
      if have termux-notification-remove; then
        termux-notification-remove "$nid" >/dev/null 2>&1 || true
      fi
      return 1
    fi
    sleep 1
  done
}

normalize_port_5digits() {
  # Accept either "12345" or strings that contain "...:12345" (e.g. "192.168.1.10:12345").
  # We extract the last ':' segment (if any), strip non-digits, and require exactly 5 digits.
  local raw="$1"
  raw="${raw//[[:space:]]/}"

  local tail="$raw"
  if [[ "$raw" == *:* ]]; then
    tail="${raw##*:}"
  fi

  # Strip any non-digits (handles cases like "IP:12345)" or "Port:12345")
  tail="${tail//[^0-9]/}"
  [[ "$tail" =~ ^[0-9]{5}$ ]] || return 1
  printf '%s' "$tail"
}

ask_port_5digits() {
  # args: key title prompt_text
  local key="$1" title="$2" prompt_text="${3:-"(5 digits PORT)"}" v="" p=""
  while true; do
    v="$(notify_ask_one "$key" "$title" "$prompt_text")" || return 1
    p="$(normalize_port_5digits "$v")" || continue
    echo "$p"
    return 0
  done
}

ask_connect_port_5digits() {
  # args: key title
  ask_port_5digits "$1" "$2" "(5 digits PORT or IP:PORT)"
}

ask_pair_port_5digits() {
  # args: key title
  # NOTE: We still tolerate pasted "IP:PORT" via normalize_port_5digits(),
  # but we do NOT advertise it here to reduce confusion/stress.
  ask_port_5digits "$1" "$2" "(5 digits PORT)"
}

ask_code_6digits() {
  local v=""
  while true; do
    v="$(notify_ask_one code "PAIR CODE" "(6 digits)")" || return 1
    v="${v//[[:space:]]/}"
    [[ -n "$v" ]] || continue
    [[ "$v" =~ ^[0-9]+$ ]] || continue
    # Normalize to 6 digits (allow missing leading zeros)
    if ((${#v} < 6)); then
      v="$(printf "%06d" "$v")"
    fi
    [[ "$v" =~ ^[0-9]{6}$ ]] || continue
    echo "$v"
    return 0
  done
}

# ---- END 40_mod_termux_api.sh ----


# ---- BEGIN 45_mod_power_mode.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh
# Power-mode wrapper for proot login:
# - Termux wakelock
# - Persistent notification

LOGIN_POWERMODE="${LOGIN_POWERMODE:-1}"        # 1=enable, 0=disable
# Stable ID for the login session (derive from NOTIF_BASE_ID if available)
LOGIN_NOTIF_ID="${LOGIN_NOTIF_ID:-$((NOTIF_BASE_ID + 75))}"
LOGIN_NOTIF_ACTIVE=0
POWER_MODE_ACQUIRED_WAKELOCK=0

power_mode_login_enter() {
  [[ "${LOGIN_POWERMODE:-1}" -eq 1 ]] || return 0
  POWER_MODE_ACQUIRED_WAKELOCK=0
  LOGIN_NOTIF_ACTIVE=0

  # Wakelock. Avoid double-acquire.
  local before_wl="${WAKELOCK_HELD:-0}"
  if [[ "$before_wl" -ne 1 ]]; then
    acquire_wakelock || true
    [[ "${WAKELOCK_HELD:-0}" -eq 1 ]] && POWER_MODE_ACQUIRED_WAKELOCK=1
  fi

  # Persistent notification
  if ! have termux-notification; then
    warn "Power-mode: termux-notification not available. Install 'termux-api' + Termux:API app."
    return 0
  fi

  # Remove any stale notif first (ignore errors)
  if have termux-notification-remove; then
    termux-notification-remove "$LOGIN_NOTIF_ID" >/dev/null 2>&1 || true
  fi

  local title="Internet-in-a-Box on Android"
  local content="IIAB session active (proot). For screen-off running, please set battery usage to Unrestricted"

  if termux-notification \
      --id "$LOGIN_NOTIF_ID" \
      --ongoing \
      --priority max \
      --title "$title" \
      --content "$content" \
      >/dev/null 2>&1
  then
    LOGIN_NOTIF_ACTIVE=1
    ok "Power-mode: enabled for this login session (persistent notification active)."
  else
    warn "Power-mode: failed to post notification (permission/app missing?)."
    warn "Tip: install Termux:API app and grant notification permission to Termux."
  fi

  return 0
}

power_mode_login_exit() {
  [[ "${LOGIN_POWERMODE:-1}" -eq 1 ]] || return 0
  local did=0

  # Remove persistent notification (best-effort)
  if have termux-notification-remove; then
    termux-notification-remove "$LOGIN_NOTIF_ID" >/dev/null 2>&1 || true
  fi
  if [[ "${LOGIN_NOTIF_ACTIVE:-0}" -eq 1 ]]; then
    LOGIN_NOTIF_ACTIVE=0
    did=1
  fi

  # Release wakelock (only if this script acquired it)
  if [[ "${POWER_MODE_ACQUIRED_WAKELOCK:-0}" -eq 1 ]]; then
    release_wakelock || true
    POWER_MODE_ACQUIRED_WAKELOCK=0
    did=1
  fi

  (( did )) && ok "Power-mode: released (notification removed, wakelock released)."
  return 0
}

# ---- END 45_mod_power_mode.sh ----


# ---- BEGIN 50_mod_adb.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

# -------------------------
# ADB wireless pair/connect wizard
# -------------------------

# Local stamp so we can detect "connect-only" misuse after reinstall/clear-data.
ADB_PAIRED_STAMP="${ADB_STATE_DIR}/stamp.adb_paired"

# -------------------------
# mDNS / Zeroconf autodiscovery (Wireless debugging ports)
# -------------------------
# Defaults + python/zeroconf helpers are defined in 20_mod_termux_base.sh.
ADB_MDNS_WAIT_SECS="${ADB_MDNS_WAIT_SECS:-90}"
# If ports were discovered via mDNS, use a shorter/relaxed timeout for the PAIR CODE prompt
ADB_CODE_TIMEOUT_SECS="${ADB_CODE_TIMEOUT_SECS:-90}"
# Notification ID for the "open wireless debugging" hint (separate from ask/reply notifications)
ADB_HINT_NOTIF_ID="${ADB_HINT_NOTIF_ID:-$((NOTIF_BASE_ID + 30))}"

adb_local_ipv4s_csv() {
  termux-wifi-connectioninfo 2>/dev/null \
    | jq -r '.ip // empty' \
    | awk 'NF && $0!="127.0.0.1"{print $0}' \
    | paste -sd, - 2>/dev/null \
    || true
}

adb_hint_notif_post() {
  have termux-notification || return 1
  have termux-notification-remove && termux-notification-remove "$ADB_HINT_NOTIF_ID" >/dev/null 2>&1 || true
  termux-notification \
    --id "$ADB_HINT_NOTIF_ID" \
    --ongoing \
    --priority max \
    --title "Wireless debugging" \
    --content "Go to: Developer options -> Wireless debugging -> Pair device (pairing code)." \
    >/dev/null 2>&1 || return 1
  return 0
}

adb_hint_notif_remove() {
  have termux-notification-remove || return 0
  termux-notification-remove "$ADB_HINT_NOTIF_ID" >/dev/null 2>&1 || true
}

adb_prepare_wireless_debugging_ui() {
  # Best-effort: bring user close to Wireless debugging before starting the mDNS timer.
  warn "Opening Developer options. Please enable Wireless debugging, then choose 'Pair device with pairing code'."
  if android_open_developer_options; then
    ok "Developer options opened."
  else
    warn "Could not open Developer options automatically. Open manually: Settings -> System -> Developer options."
  fi
  # Optional hint notification while user navigates UI
  adb_hint_notif_post || true
}

adb_mdns_scan_ports_py() {
  # args: wait_seconds local_ips_csv
  local wait="${1:-90}" ips="${2:-}"
  local py=""
  py="$(command -v python 2>/dev/null || command -v python3 2>/dev/null || true)"
  [[ -n "$py" ]] || return 1
  LOCAL_IPS="$ips" "$py" - "$wait" <<'PY'
import os, sys, time
try:
    from zeroconf import Zeroconf, ServiceBrowser
except Exception:
    sys.exit(1)

CONNECT_TYPE = "_adb-tls-connect._tcp.local."
PAIR_TYPE    = "_adb-tls-pairing._tcp.local."

deadline = time.time() + max(1, int(sys.argv[1])) if len(sys.argv) > 1 else time.time() + 90
local_ips = set([x.strip() for x in os.environ.get("LOCAL_IPS","").split(",") if x.strip()])

found = {CONNECT_TYPE: [], PAIR_TYPE: []}  # list of (port, addrs)

def addr_match(addrs):
    if not local_ips:
        return True
    return any(a in local_ips for a in addrs)

class Listener:
    def add_service(self, zc, type_, name):
        info = zc.get_service_info(type_, name, timeout=1200)
        if not info:
            return
        try:
            addrs = info.parsed_addresses()
        except Exception:
            addrs = []
        if not addr_match(addrs):
            return
        found.setdefault(type_, []).append((info.port, addrs))

    def update_service(self, zc, type_, name):
        self.add_service(zc, type_, name)

    def remove_service(self, zc, type_, name):
        return

zc = Zeroconf()
try:
    ServiceBrowser(zc, [CONNECT_TYPE, PAIR_TYPE], listener=Listener())
    while time.time() < deadline:
        # stop early when we have at least one candidate for both
        if found.get(CONNECT_TYPE) and found.get(PAIR_TYPE):
            break
        time.sleep(0.2)
finally:
    try:
        zc.close()
    except Exception:
        pass

def pick_first_port(type_):
    items = found.get(type_) or []
    if not items:
        return None
    # pick first seen; on-device should usually be unique
    return items[0][0]

cp = pick_first_port(CONNECT_TYPE)
pp = pick_first_port(PAIR_TYPE)
if cp:
    print(f"CONNECT_PORT={cp}")
if pp:
    print(f"PAIR_PORT={pp}")
PY
}

adb_mdns_autodetect_pair_and_connect_ports() {
  # Returns: "CONNECT_PORT PAIR_PORT" (5-digit ports only), or fails.
  python_ensure_zeroconf || return 1
  local ips out cp pp
  ips="$(adb_local_ipv4s_csv 2>/dev/null || true)"
  out="$(adb_mdns_scan_ports_py "${ADB_MDNS_WAIT_SECS:-90}" "$ips" 2>/dev/null || true)"
  cp="$(printf '%s\n' "$out" | sed -n 's/^CONNECT_PORT=//p' | head -n1)"
  pp="$(printf '%s\n' "$out" | sed -n 's/^PAIR_PORT=//p' | head -n1)"
  [[ "$cp" =~ ^[0-9]{5}$ ]] || return 1
  [[ "$pp" =~ ^[0-9]{5}$ ]] || return 1
  printf '%s %s\n' "$cp" "$pp"
}

adb_mdns_autodetect_connect_port_only() {
  # Returns: "CONNECT_PORT" (5-digit only), or fails.
  python_ensure_zeroconf || return 1
  local ips out cp
  ips="$(adb_local_ipv4s_csv 2>/dev/null || true)"
  out="$(adb_mdns_scan_ports_py "${ADB_MDNS_WAIT_SECS:-90}" "$ips" 2>/dev/null || true)"
  cp="$(printf '%s\n' "$out" | sed -n 's/^CONNECT_PORT=//p' | head -n1)"
  [[ "$cp" =~ ^[0-9]{5}$ ]] || return 1
  printf '%s\n' "$cp"
}

adb_hostkey_fingerprint() {
  # Returns a stable fingerprint for THIS Termux install's adb host key.
  # Defaulted to sha256 being available/confirmed in the baseline.
  local pub="${HOME}/.android/adbkey.pub"
  [[ -r "$pub" ]] || return 1
  sha256sum "$pub" | awk '{print $1}'
}

adb_stamp_write() {
  # args: mode serial
  local mode="$1" serial="$2" fp=""
  fp="$(adb_hostkey_fingerprint 2>/dev/null || true)"
  {
    echo "ts=$(date -Is 2>/dev/null || date || true)"
    echo "mode=${mode}"
    echo "host=${HOST}"
    echo "serial=${serial}"
    echo "connect_port=${CONNECT_PORT:-}"
    echo "hostkey_fp=${fp}"
  } >"$ADB_PAIRED_STAMP" 2>/dev/null || true
  chmod 600 "$ADB_PAIRED_STAMP"
}

adb_stamp_read_fp() {
  [[ -r "$ADB_PAIRED_STAMP" ]] || return 1
  sed -n 's/^hostkey_fp=//p' "$ADB_PAIRED_STAMP" 2>/dev/null | head -n 1
}

adb_warn_connect_only_if_suspicious() {
  # Called only in connect-only flows.
  local cur_fp old_fp
  cur_fp="$(adb_hostkey_fingerprint 2>/dev/null || true)"
  old_fp="$(adb_stamp_read_fp 2>/dev/null || true)"

  if [[ ! -f "$ADB_PAIRED_STAMP" ]]; then
    warn "connect-only assumes THIS Termux install has been paired before."
    warn "No local pairing stamp found ($ADB_PAIRED_STAMP)."
    warn "If you reinstalled Termux / cleared data / changed user, you must re-pair (run: --adb-only)."
    [[ -n "$cur_fp" ]] && warn "Current ADB hostkey fingerprint: ${cur_fp:0:12}..."
    return 0
  fi

  if [[ -n "$old_fp" && -n "$cur_fp" && "$old_fp" != "$cur_fp" ]]; then
    warn_red "ADB host key changed since last pairing stamp."
    warn "Old fingerprint: ${old_fp:0:12}...  Current: ${cur_fp:0:12}..."
    warn "Android Wireless debugging -> Paired devices: remove the old entry, then run: --adb-only"
  fi
}

adb_connect_verify() {
  # args: serial (HOST:PORT)
  local serial="$1" out rc start now state
  set +e
  out="$(adb connect "$serial" 2>&1)"
  rc=$?
  set -e

  # Always verify via `adb devices` (adb may exit 0 even on failure).
  start="$(date +%s)"
  while true; do
    state="$(adb_device_state "$serial" || true)"
    [[ "$state" == "device" ]] && { printf '%s\n' "$out"; return 0; }
    now="$(date +%s)"
    (( now - start >= 5 )) && break
    sleep 1
  done

  warn_red "adb connect did not result in a usable device entry for: $serial (state='${state:-none}')."
  warn "adb connect output: ${out:-<none>}"
  warn "If you recently reinstalled Termux/cleared data, the phone may show an OLD paired device. Remove it and re-pair."
  return 1
}

cleanup_offline_loopback() {
  local keep_serial="$1"  # e.g. 127.0.0.1:41313
  local serial state rest
  while read -r serial state rest; do
    [[ -n "${serial:-}" ]] || continue
    [[ "$serial" == ${HOST}:* ]] || continue
    [[ "$state" == "offline" ]] || continue
    [[ "$serial" == "$keep_serial" ]] && continue
    adb disconnect "$serial" >/dev/null 2>&1 || true
  done < <(adb devices 2>/dev/null | tail -n +2 | sed '/^[[:space:]]*$/d')
}

adb_pair_connect() {
  need adb || die "Missing adb. Install: pkg install android-tools"

  # Only require Termux:API when we will prompt the user
  if [[ "$ONLY_CONNECT" != "1" || -z "${CONNECT_PORT:-}" ]]; then
    termux_api_ready || die "Termux:API not ready."
  fi

  echo "[*] adb: $(adb version | head -n 1)"
  adb start-server >/dev/null 2>&1 || true

  if [[ "$ONLY_CONNECT" == "1" ]]; then
    adb_warn_connect_only_if_suspicious
    if [[ -n "$CONNECT_PORT" ]]; then
      local raw="$CONNECT_PORT" norm=""
      norm="$(normalize_port_5digits "$raw" 2>/dev/null)" || \
        die "Invalid CONNECT PORT (must be 5 digits PORT or IP:PORT): '$raw'"
      CONNECT_PORT="$norm"
    else
      echo "[*] CONNECT PORT not provided; asking..."
      CONNECT_PORT="$(ask_connect_port_5digits connect "CONNECT PORT")" || die "Timeout waiting CONNECT PORT."
    fi

    local serial="${HOST}:${CONNECT_PORT}"
    adb disconnect "$serial" >/dev/null 2>&1 || true
    echo "[*] adb connect $serial"
    adb_connect_verify "$serial" >/dev/null || die "adb connect failed to $serial. Verify Wireless debugging is enabled, and pairing exists for THIS Termux install."

    if [[ "$CLEANUP_OFFLINE" == "1" ]]; then
      cleanup_offline_loopback "$serial"
    fi

    echo "[*] Devices:"
    adb devices -l

    echo "[*] ADB check (shell):"
    adb -s "$serial" shell sh -lc 'echo "it worked: adb shell is working"; id' || true
    adb_stamp_write "connect-only" "$serial"

    cleanup_notif
    ok "ADB connected (connect-only): $serial"
    return 0
  fi

  if [[ -n "$CONNECT_PORT" ]]; then
    local raw="$CONNECT_PORT" norm=""
    norm="$(normalize_port_5digits "$raw" 2>/dev/null)" || \
      die "Invalid --connect-port (must be 5 digits PORT or IP:PORT): '$raw'"
    CONNECT_PORT="$norm"
  else
    # mDNS window (90s): open Developer options, scan for both connect+pair ports.
    local ports="" pair_port="" auto_ports=0
    if [[ "${ADB_MDNS:-0}" -eq 1 ]] && [[ "${ANDROID_SDK:-}" =~ ^[0-9]+$ ]] && (( ANDROID_SDK >= 30 )); then
      if python_ensure_zeroconf; then
        adb_prepare_wireless_debugging_ui
        if ports="$(adb_mdns_autodetect_pair_and_connect_ports 2>/dev/null)"; then
          CONNECT_PORT="${ports%% *}"
          pair_port="${ports##* }"
          auto_ports=1
          ok "Auto-detected ports via mDNS: CONNECT=$CONNECT_PORT PAIR=$pair_port"
        else
          warn "mDNS auto-detect timed out (${ADB_MDNS_WAIT_SECS}s). Falling back to manual prompts."
        fi
      else
        # python_ensure_zeroconf already warned; keep this generic to avoid duplicates.
        warn "mDNS auto-detect unavailable. Falling back to manual prompts."
      fi
    else
      warn "mDNS auto-detect disabled (ADB_MDNS=0). Falling back to manual prompts."
    fi

    if [[ "$auto_ports" -ne 1 ]]; then
      warn "Manual ports needed. On Android open: Settings -> System -> Developer options -> Wireless debugging."
      warn "CONNECT PORT: shown as 'IP address & port' on the Wireless debugging screen."
      warn "PAIR PORT: shown inside 'Pair device with pairing code' dialog (keep it open)."
      echo "[*] Asking CONNECT PORT..."
      CONNECT_PORT="$(ask_connect_port_5digits connect "CONNECT PORT")" || die "Timeout waiting CONNECT PORT."
      echo "[*] Asking PAIR PORT..."
      pair_port="$(ask_pair_port_5digits pair "PAIR PORT")" || die "Timeout waiting PAIR PORT."
    fi
    adb_hint_notif_remove || true

    echo "[*] Asking PAIR CODE..."
    local code old_timeout
    if [[ "$auto_ports" -eq 1 ]]; then
      old_timeout="$TIMEOUT_SECS"
      TIMEOUT_SECS="${ADB_CODE_TIMEOUT_SECS:-90}"
      code="$(ask_code_6digits)" || { TIMEOUT_SECS="$old_timeout"; die "Timeout waiting PAIR CODE."; }
      TIMEOUT_SECS="$old_timeout"
    else
      code="$(ask_code_6digits)" || die "Timeout waiting PAIR CODE."
    fi

    local serial="${HOST}:${CONNECT_PORT}"
    adb disconnect "$serial" >/dev/null 2>&1 || true

    echo "[*] adb pair ${HOST}:${pair_port}"
    printf '%s\n' "$code" | adb pair "${HOST}:${pair_port}" || die "adb pair failed. Verify PAIR PORT and PAIR CODE (and that the pairing dialog is showing)."

    echo "[*] adb connect $serial"
    adb_connect_verify "$serial" >/dev/null || die "adb connect failed after pairing. Re-check CONNECT PORT and Wireless debugging."

    if [[ "$CLEANUP_OFFLINE" == "1" ]]; then
      cleanup_offline_loopback "$serial"
    fi

    echo "[*] Devices:"
    adb devices -l

    echo "[*] ADB check (shell):"
    adb -s "$serial" shell sh -lc 'echo "it worked: adb shell is working"; getprop ro.product.model; getprop ro.build.version.release' || true
    adb_stamp_write "paired" "$serial"

    cleanup_notif
    ok "ADB connected: $serial"
    return 0
  fi

  # If --connect-port was provided, keep the original manual prompts (no 90s delay).
  echo "[*] Asking PAIR PORT..."
  local pair_port
  pair_port="$(ask_pair_port_5digits pair "PAIR PORT")" || die "Timeout waiting PAIR PORT."

  echo "[*] Asking PAIR CODE..."
  local code
  code="$(ask_code_6digits)" || die "Timeout waiting PAIR CODE."

  local serial="${HOST}:${CONNECT_PORT}"
  adb disconnect "$serial" >/dev/null 2>&1 || true

  echo "[*] adb pair ${HOST}:${pair_port}"
  printf '%s\n' "$code" | adb pair "${HOST}:${pair_port}" || die "adb pair failed. Verify PAIR PORT and PAIR CODE (and that the pairing dialog is showing)."

  echo "[*] adb connect $serial"
  adb_connect_verify "$serial" >/dev/null || die "adb connect failed after pairing. Re-check CONNECT PORT and Wireless debugging."

  if [[ "$CLEANUP_OFFLINE" == "1" ]]; then
    cleanup_offline_loopback "$serial"
  fi

  echo "[*] Devices:"
  adb devices -l

  echo "[*] ADB check (shell):"
  adb -s "$serial" shell sh -lc 'echo "it worked: adb shell is working"; getprop ro.product.model; getprop ro.build.version.release' || true
  adb_stamp_write "paired" "$serial"

  cleanup_notif
  ok "ADB connected: $serial"
}

# Return state for an exact serial (e.g. "device", "offline", empty)
adb_device_state() {
  local s="$1"
  adb devices 2>/dev/null | awk -v s="$s" 'NR>1 && $1==s {print $2; exit}'
}

# Return first loopback serial in "device" state (e.g. 127.0.0.1:41313)
adb_any_loopback_device() {
  adb devices 2>/dev/null | awk -v h="$HOST" '
    NR>1 && $2=="device" && index($1, h":")==1 {print $1; found=1; exit}
    END { exit (found ? 0 : 1) }
  '
}

# Pick the loopback serial we will operate on:
# - If CONNECT_PORT is set, require that exact HOST:PORT to be in "device" state.
# - Otherwise, return the first loopback device.
adb_pick_loopback_serial() {
  if [[ -n "${CONNECT_PORT:-}" ]]; then
      local raw="$CONNECT_PORT" p=""
      p="$(normalize_port_5digits "$raw" 2>/dev/null)" || return 1
      local target="${HOST}:${p}"
    [[ "$(adb_device_state "$target")" == "device" ]] && { echo "$target"; return 0; }
    return 1
  fi
  adb_any_loopback_device
}

# If already connected, avoid re-pairing/re-connecting prompts (useful for --all),
# BUT only consider loopback/target connections as "already connected".
adb_pair_connect_if_needed() {
  need adb || die "Missing adb. Install: pkg install android-tools"
  adb start-server >/dev/null 2>&1 || true

  local serial=""

  # If user provided a connect-port, insist on that exact target serial.
  if [[ -n "${CONNECT_PORT:-}" ]]; then
    local raw="$CONNECT_PORT" norm=""
    norm="$(normalize_port_5digits "$raw" 2>/dev/null)" || \
      die "Invalid --connect-port (must be 5 digits PORT or IP:PORT): '$raw'"
    CONNECT_PORT="$norm"

    local target="${HOST}:${CONNECT_PORT}"

    if [[ "$(adb_device_state "$target")" == "device" ]]; then
      ok "ADB already connected to target: $target (skipping pair/connect)."
      return 0
    fi

    # Try connect-only first (in case it was already paired before)
    adb connect "$target" >/dev/null 2>&1 || true
    if [[ "$(adb_device_state "$target")" == "device" ]]; then
      ok "ADB connected to target: $target (connect-only succeeded; skipping pair)."
      return 0
    fi

    # Not connected: run full wizard (pair+connect)
    adb_pair_connect
    return $?
  fi

  # No explicit port: only skip if we already have a loopback device connected.
  if serial="$(adb_any_loopback_device 2>/dev/null)"; then
    ok "ADB already connected (loopback): $serial (skipping pair/connect)."
    return 0
  fi

  adb_pair_connect
}

require_adb_connected() {
  need adb || { warn_red "Missing adb. Install: pkg install android-tools"; return 1; }
  adb start-server >/dev/null 2>&1 || true
  if ! adb_pick_loopback_serial >/dev/null 2>&1; then
    warn_red "No ADB device connected."
    warn "If already paired before: run --connect-only [PORT]."
    warn "Otherwise: run --adb-only to pair+connect."
    return 1
  fi
  return 0
}

adb_loopback_serial_or_die() {
  local s
  s="$(adb_pick_loopback_serial 2>/dev/null)" || return 1
  echo "$s"
}

run_if_adb_connected() {
  # run input command only if adb_pick_loopback_serial is connected 
  if adb_pick_loopback_serial >/dev/null 2>&1; then
    "$@"
  fi
}

# ---- END 50_mod_adb.sh ----


# ---- BEGIN 60_mod_ppk_checks.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

# PPK / phantom-process checks and tuning via ADB (best-effort)
# Moved out of 99_main.sh to keep it as an orchestrator.

# -------------------------
# PPK / phantom-process tuning (best-effort)
# -------------------------
ppk_fix_via_adb() {
  need adb || die "Missing adb. Install: pkg install android-tools"

  local serial
  if ! serial="$(adb_pick_loopback_serial)"; then
    CHECK_NO_ADB=1
    warn "No ADB loopback device connected (expected ${HOST}:${CONNECT_PORT:-*})."
    return 1
  fi
  ok "Using ADB device: $serial"

  local sdk max
  sdk="$(adb -s "$serial" shell getprop ro.build.version.sdk 2>/dev/null | tr -d '\r' || true)"
  max="${PPK_MAX:-256}"

  # Android 14+ (SDK 34+) -> max_phantom_processes is informational; rely on "Disable child process restrictions".
  if [[ "${sdk:-}" =~ ^[0-9]+$ ]] && (( sdk >= 34 )); then
    log "PPK: sdk=${sdk} (A14+). Skipping max_phantom_processes; rely on Child restrictions."
    return 0
  fi

  log "Setting PPK: max_phantom_processes=${max}"
# Some Android versions may ignore/rename this; we don't hard-fail.
adb -s "$serial" shell sh -s -- "$max" <<'EOF' || true
    set -e
    max="${1:-256}"

    # Prefer device_config binary; fallback to "cmd device_config" on some ROMs.
    if command -v device_config >/dev/null 2>&1; then
      dc() { device_config "$@"; }
    elif command -v cmd >/dev/null 2>&1; then
      dc() { cmd device_config "$@"; }
    else
      echo "device_config not available; skipping."
      exit 0
    fi

    dc set_sync_disabled_for_tests persistent >/dev/null 2>&1 || true
    dc put activity_manager max_phantom_processes "$max" >/dev/null 2>&1 || true

    echo "dumpsys effective max_phantom_processes:"
    dumpsys activity settings 2>/dev/null | grep -i "max_phantom_processes=" | head -n 1 || true
EOF

  ok "PPK set done (best effort)."
  return 0
}

# Prefer Android 14+ feature-flag override if present:
# OFF -> true, ON -> false
adb_get_child_restrictions_flag() {
  local serial="$1"
  adb -s "$serial" shell getprop persist.sys.fflag.override.settings_enable_monitor_phantom_procs 2>/dev/null | tr -d '\r' || true
}

# SDK 34 / Android 14 can return 1 / 0 , instead of "true" / "false".
normalize_bool_tf01() {
  local v="${1:-}"
  v="${v//$'\r'/}"
  v="${v,,}"
  case "$v" in
    0|false) echo "false" ;;
    1|true)  echo "true" ;;
    *)       echo "${1:-}" ;;
  esac
}

adb_settings_get_key() {
  # args: serial namespace key
  local serial="$1" ns="$2" key="$3"
  adb -s "$serial" shell settings get "$ns" "$key" 2>/dev/null | tr -d '\r' | tr -d '[:space:]' || true
}

adb_device_config_get_key() {
  # args: serial namespace key  (namespace here is device_config "activity_manager")
  local serial="$1" ns="$2" key="$3"
  local out=""
  out="$(adb -s "$serial" shell device_config get "$ns" "$key" 2>/dev/null || true)"
  # Some ROMs expose it only via "cmd device_config"
  if [[ -z "${out//[$'\r\n\t ']/}" || "${out//$'\r'/}" == "null" ]]; then
    out="$(adb -s "$serial" shell cmd device_config get "$ns" "$key" 2>/dev/null || true)"
  fi
  printf '%s' "$out" | tr -d '\r' | tr -d '[:space:]' || true
}

# Unified reader for Android "Disable child process restrictions"
# Prints: true | false | unknown
adb_get_monitor_phantom_procs() {
  local serial="$1"
  local v=""

  # 1) settings global/secure (keys vary by Android version/OEM)
  local keys=(
    settings_enable_monitor_phantom_procs
    enable_monitor_phantom_procs
    settings_enable_monitor_phantom_processes
    enable_monitor_phantom_processes
  )
  local ns k
  for ns in global secure; do
    for k in "${keys[@]}"; do
      v="$(adb_settings_get_key "$serial" "$ns" "$k")"
      v="$(normalize_bool_tf01 "$v")"
      [[ "$v" == "true" || "$v" == "false" ]] && { echo "$v"; return 0; }
    done
  done

  # 2) device_config fallbacks
  if adb -s "$serial" shell 'command -v device_config >/dev/null 2>&1 || command -v cmd >/dev/null 2>&1'; then
    for k in "${keys[@]}"; do
      v="$(adb_device_config_get_key "$serial" activity_manager "$k")"
      v="$(normalize_bool_tf01 "$v")"
      [[ "$v" == "true" || "$v" == "false" ]] && { echo "$v"; return 0; }
    done
  fi

  # 3) legacy helper (last resort)
  v="$(adb_get_child_restrictions_flag "$serial" 2>/dev/null | tr -d '\r' | tr -d '[:space:]' || true)"
  v="$(normalize_bool_tf01 "$v")"
  [[ "$v" == "true" || "$v" == "false" ]] && { echo "$v"; return 0; }

  echo "unknown"
}

adb_disable_child_process_restrictions_via_adb() {
  # Best-effort: try to force "Disable child process restrictions" ON
  # Expected readback: monitor=false
  local serial="$1"
  local keys=(
    settings_enable_monitor_phantom_procs
    enable_monitor_phantom_procs
    settings_enable_monitor_phantom_processes
    enable_monitor_phantom_processes
  )

  log "Android 14+: trying to disable child process restrictions via ADB (best-effort)..."
  adb -s "$serial" shell sh -s <<'EOF' || true
set -e
keys="settings_enable_monitor_phantom_procs enable_monitor_phantom_procs settings_enable_monitor_phantom_processes enable_monitor_phantom_processes"

# Prefer settings (some ROMs use global, others secure)
for ns in global secure; do
  for k in $keys; do
    settings put "$ns" "$k" 0 >/dev/null 2>&1 || true
  done
done

# DeviceConfig fallback
if command -v device_config >/dev/null 2>&1; then
  for k in $keys; do
    device_config put activity_manager "$k" false >/dev/null 2>&1 || true
  done
fi
EOF

  local mon
  mon="$(adb_get_monitor_phantom_procs "$serial")"
  if [[ "$mon" == "false" ]]; then
    ok "Child restrictions: OK (monitor=false)"
    return 0
  fi
  warn "Child restrictions: could not verify (monitor='${mon:-}'). You may still need to toggle it manually in Developer options."
  return 1
}

# -------------------------
# Check readiness (best-effort)
# -------------------------
check_readiness() {
  # Reset exported check signals so final_advice() never sees stale values
  CHECK_NO_ADB=0
  CHECK_SDK=""
  CHECK_MON=""
  CHECK_PPK=""

  need adb || die "Missing adb. Install: pkg install android-tools"
  adb start-server >/dev/null 2>&1 || true

  local serial
  if ! serial="$(adb_pick_loopback_serial)"; then
    CHECK_NO_ADB=1
    # Best-effort: keep local SDK so final_advice can still warn on A12-13.
    CHECK_SDK="${ANDROID_SDK:-}"
    if [[ "${ANDROID_SDK:-}" =~ ^[0-9]+$ ]] && (( ANDROID_SDK >= 31 && ANDROID_SDK <= 33 )); then
      warn_red "No ADB device connected. Cannot check for PPK fix."
      warn "If already paired before: run --connect-only [PORT]. Otherwise: run --adb-only to pair+connect."
    else
      log "ADB not connected. Skipping ADB checks."
    fi
    return 1
  fi

  ok "Check using ADB device: $serial"

  local dev_enabled sdk rel mon mon_fflag ds ppk_eff
  sdk="$(adb -s "$serial" shell getprop ro.build.version.sdk 2>/dev/null | tr -d '\r' || true)"
  rel="$(adb -s "$serial" shell getprop ro.build.version.release 2>/dev/null | tr -d '\r' || true)"
  dev_enabled="$(adb -s "$serial" shell settings get global development_settings_enabled 2>/dev/null | tr -d '\r' || true)"
  mon="$(adb_get_monitor_phantom_procs "$serial")"

  # If user opted-in to ADB and we're in --all, be proactive on Android 14+.
  # Allow override: CHILD_RESTRICTIONS_AUTOFIX=0
  if [[ "${MODE:-}" == "all" ]] && [[ "${CHILD_RESTRICTIONS_AUTOFIX:-1}" -eq 1 ]]; then
    if [[ "${sdk:-}" =~ ^[0-9]+$ ]] && (( sdk >= 34 )) && [[ "${dev_enabled:-}" == "1" ]]; then
      if [[ "$mon" != "false" ]]; then
        adb_disable_child_process_restrictions_via_adb "$serial" || true
        mon="$(adb_get_monitor_phantom_procs "$serial")"
      fi
    fi
  fi

  # Get effective value from dumpsys (device_config get may return 'null' even when an effective value exists)
  ds="$(adb -s "$serial" shell dumpsys activity settings 2>/dev/null | tr -d '\r' || true)"
  ppk_eff="$(printf '%s\n' "$ds" | awk -F= '/max_phantom_processes=/{print $2; exit}' | tr -d '[:space:]' || true)"

  # Export check signals for the final advice logic
  CHECK_SDK="${sdk:-}"
  CHECK_MON="${mon:-}"
  CHECK_PPK="${ppk_eff:-}"

  log " Android release=${rel:-?} sdk=${sdk:-?}"

  if [[ "${dev_enabled:-}" == "1" ]]; then
    ok " Developer options: enabled (development_settings_enabled=1)"
  elif [[ -n "${dev_enabled:-}" ]]; then
    warn " Developer options: unknown/disabled (development_settings_enabled=${dev_enabled})"
  else
    warn " Developer options: unreadable (permission/ROM differences)."
  fi

  # Android 14+ only: "Disable child process restrictions" proxy flag
  if [[ "${sdk:-}" =~ ^[0-9]+$ ]] && (( sdk >= 34 )); then
    if [[ "${mon:-}" == "false" ]]; then
      ok " Child restrictions: OK (monitor=false)"
    elif [[ "${mon:-}" == "true" ]]; then
      warn_red " Child restrictions: NOT OK (monitor=true)"
    elif [[ -n "${mon:-}" && "${mon:-}" != "null" ]]; then
      warn " Child restrictions: unknown (${mon})"
    else
      warn " Child restrictions: unreadable/absent"
    fi
  fi

  # Android 12-13 only: PPK matters (use effective value from dumpsys)
  if [[ "${sdk:-}" =~ ^[0-9]+$ ]] && (( sdk >= 31 && sdk <= 33 )); then
    if [[ "${ppk_eff:-}" =~ ^[0-9]+$ ]]; then
      if (( ppk_eff >= 256 )); then
        ok " PPK: OK (max_phantom_processes=${ppk_eff})"
      else
        warn_red " PPK: low (max_phantom_processes=${ppk_eff}) -> suggest: run --ppk-only"
      fi
    else
      warn " PPK: unreadable (dumpsys max_phantom_processes='${ppk_eff:-}')."
    fi
  fi

  log " dumpsys (phantom-related):"
  printf '%s\n' "$ds" | grep -i phantom || true

  if [[ "${sdk:-}" =~ ^[0-9]+$ ]] && (( sdk >= 34 )); then
    log " Note: On A14+, max_phantom_processes is informational; rely on Child restrictions."
  fi
  if [[ "${sdk:-}" =~ ^[0-9]+$ ]] && (( sdk >= 34 )) && [[ "${mon:-}" == "false" ]]; then
    log " Child restrictions OK."
  fi
  return 0
}

self_check_android_flags() {
  have adb || return 0
  adb start-server >/dev/null 2>&1 || true

  local serial sdk rel mon mon_fflag ds ppk_eff
  serial="$(adb_pick_loopback_serial 2>/dev/null)" || {
  if [[ "${sdk:-}" =~ ^[0-9]+$ ]] && (( sdk >= 31 && sdk <= 33 )); then
    log "ADB: no loopback device connected. Tip: run --adb-only or --check if you require it."
    return 0
  fi
  }

  sdk="$(adb -s "$serial" shell getprop ro.build.version.sdk 2>/dev/null | tr -d '\r' || true)"
  rel="$(adb -s "$serial" shell getprop ro.build.version.release 2>/dev/null | tr -d '\r' || true)"
  if [[ "${sdk:-}" =~ ^[0-9]+$ ]] && (( sdk >= 31 && sdk <= 33 )); then
    log " Android flags (quick): release=${rel:-?} sdk=${sdk:-?} serial=$serial"
  fi

  if [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 34 )); then
    mon="$(adb_get_monitor_phantom_procs "$serial")"
    if [[ "$mon" == "false" ]]; then
      ok " Child restrictions: OK (monitor=false)"
    elif [[ "$mon" == "true" ]]; then
      warn_red_context " Child restrictions: NOT OK (monitor=true) -> check Developer Options"
    else
      warn " Child restrictions: unknown/unreadable (monitor='${mon:-}')"
    fi
  fi

  if [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 31 && sdk <= 33 )); then
    ds="$(adb -s "$serial" shell dumpsys activity settings 2>/dev/null | tr -d '\r' || true)"
    ppk_eff="$(printf '%s\n' "$ds" | awk -F= '/max_phantom_processes=/{print $2; exit}' | tr -d '[:space:]' || true)"

    if [[ "$ppk_eff" =~ ^[0-9]+$ ]]; then
      if (( ppk_eff >= 256 )); then
        ok " PPK: OK (max_phantom_processes=$ppk_eff)"
      else
        warn_red_context " PPK: low (max_phantom_processes=$ppk_eff) -> suggest: --ppk-only"
      fi
    else
      warn " PPK: unreadable (max_phantom_processes='${ppk_eff:-}')"
    fi
  fi

  # Avoid redundant tip when we're already in --check mode.
  if [[ "${MODE:-}" != "check" && "${MODE:-}" != "all" ]]; then
    log " Tip: run --check for full details."
  fi
}

# ---- END 60_mod_ppk_checks.sh ----


# ---- BEGIN 70_mod_boxyproxy.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

# -----------------------------------------------------------------------------
# boxyproxy.py companion management
# - Installs/updates to: $PREFIX/bin/boxyproxy.py
# - Runtime state: ~/.iiab-android/boxyproxy/
# - Controlled by iiab-termux flags:
#     --proxy-start | --proxy-stop | --proxy-status
# -----------------------------------------------------------------------------

BOXYPROXY_BIN="${PREFIX}/bin/boxyproxy.py"
BOXYPROXY_PIDFILE="${STATE_DIR}/boxyproxy.pid"
BOXYPROXY_LOG="${LOG_DIR}/boxyproxy.log"

# DNF: Confirm final URL
BOXYPROXY_RAW_URL_DEFAULT="https://raw.githubusercontent.com/iiab/iiab-android/main/termux-setup/proxy/boxyproxy.py"
BOXYPROXY_RAW_URL="${BOXYPROXY_RAW_URL:-$BOXYPROXY_RAW_URL_DEFAULT}"

boxyproxy_is_installed() { [[ -x "$BOXYPROXY_BIN" ]]; }

boxyproxy_state_init() {
  mkdir -p "$STATE_DIR" "$LOG_DIR" >/dev/null 2>&1 || true
}

boxyproxy_is_running() {
  boxyproxy_is_installed || return 1
  [[ -f "$BOXYPROXY_PIDFILE" ]] || return 1
  local pid=""
  pid="$(tr -d '\r' <"$BOXYPROXY_PIDFILE" 2>/dev/null | head -n1)" || return 1
  [[ "$pid" =~ ^[0-9]+$ ]] || return 1
  kill -0 "$pid" 2>/dev/null
}

boxyproxy_install_or_update() {
  boxyproxy_state_init
  have curl || { log "Installing curl (needed to fetch boxyproxy.py)"; termux_apt update || true; termux_apt install curl || return 1; }

  mkdir -p "${PREFIX}/bin" >/dev/null 2>&1 || true
  local tmp="${BOXYPROXY_BIN}.tmp.$$"
  log "Updating boxyproxy.py -> ${BOXYPROXY_BIN}"
  if ! curl -fsSL --retry 3 --retry-delay 1 --connect-timeout 8 --max-time 45 \
      "$BOXYPROXY_RAW_URL" -o "$tmp"; then
    warn_red "Failed downloading boxyproxy.py from: $BOXYPROXY_RAW_URL"
    rm -f "$tmp" >/dev/null 2>&1 || true
    return 1
  fi

  # Minimal sanity check: must look like a python script.
  if ! head -n1 "$tmp" 2>/dev/null | grep -qE '^#!.*python'; then
    warn_red "Downloaded file does not look like a python script (missing shebang)."
    rm -f "$tmp" >/dev/null 2>&1 || true
    return 1
  fi

  chmod 700 "$tmp" >/dev/null 2>&1 || true
  mv -f "$tmp" "$BOXYPROXY_BIN" || return 1
  chmod 700 "$BOXYPROXY_BIN" >/dev/null 2>&1 || true
  ok "boxyproxy.py installed/updated: $BOXYPROXY_BIN"
  return 0
}

boxyproxy_start() {
  boxyproxy_state_init
  boxyproxy_is_running && { ok "boxyproxy already running."; return 0; }

  # Ensure Python deps (aiohttp) before launching.
  if declare -F termux_prepare_boxyproxy_deps >/dev/null 2>&1; then
    termux_prepare_boxyproxy_deps || true
  fi

  boxyproxy_is_installed || {
    warn "boxyproxy.py not installed yet. Installing now..."
    boxyproxy_install_or_update || return 1
  }

  local -a args=()
  if [[ -n "${BOXYPROXY_ARGS:-}" ]]; then
    args=( $BOXYPROXY_ARGS )
  fi

  # Append --no-external if requested via flag
  if [[ "${BOXYPROXY_NO_EXTERNAL:-0}" -eq 1 ]]; then
    args+=( "--no-external" )
  fi

  # On headless we force python3 instead of depending on shebang env
  if [[ "${INTENT_MODE:-}" == "headless" ]]; then
    boxyp_log "Iniciando boxyproxy (headless)..."
    python3 "$BOXYPROXY_BIN" "${args[@]}" >> "$BOXYPROXY_LOG" 2>&1 &
    echo $! > "$BOXYPROXY_PIDFILE"
  else
    python3 "$BOXYPROXY_BIN" -d \
      --pidfile "$BOXYPROXY_PIDFILE" \
      --logfile "$BOXYPROXY_LOG" \
      "${args[@]}" >/dev/null 2>&1
  fi
  sleep 0.2

  python3 "$BOXYPROXY_BIN" --status --pidfile "$BOXYPROXY_PIDFILE" 2>/dev/null | indent || true
  boxyproxy_is_running || { warn_red "boxyproxy failed to start (see $BOXYPROXY_LOG)"; return 1; }
  ok "boxyproxy started."
  return 0
}

boxyproxy_stop() {
  boxyproxy_state_init
  boxyproxy_is_installed || return 0
  python3 "$BOXYPROXY_BIN" --stop --pidfile "$BOXYPROXY_PIDFILE" 2>/dev/null | indent || true
  return 0
}

boxyproxy_status() {
  boxyproxy_state_init
  boxyproxy_is_installed || { warn "installed=no"; return 0; }
  python3 "$BOXYPROXY_BIN" --status --pidfile "$BOXYPROXY_PIDFILE" 2>/dev/null || true

  # Check if the process is actually running with the --no-external flag
  local running_no_ext="no"
  local pid
  pid="$(tr -d '\r' <"$BOXYPROXY_PIDFILE" 2>/dev/null || true)"
  if [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null; then
    if grep -aq "no-external" "/proc/$pid/cmdline" 2>/dev/null; then
      running_no_ext="yes"
    fi
  fi

  # Report current running state
  boxyp_log "walled-garden (active): $running_no_ext"

  boxyp_log "bin=$BOXYPROXY_BIN"
  boxyp_log "log=$BOXYPROXY_LOG"
}

# ---- END 70_mod_boxyproxy.sh ----


# ---- BEGIN 99_main.sh ----
# shellcheck shell=bash
# Module file (no shebang). Bundled by build_bundle.sh

# iiab-termux
# - Termux bootstrap (packages, wakelock)
# - proot-distro + IIAB Debian bootstrap
# - ADB wireless pair/connect via Termux:API notifications (no Shizuku)
# - Optional PPK / phantom-process tweaks (best-effort)

# -------------------------
# Defaults
# -------------------------
# NOTE: Core defaults live in 00_lib_common.sh to guarantee availability for all modules.

# Ensure state directories exist (safe even if user overrides via environment).
mkdir -p "$STATE_DIR" "$ADB_STATE_DIR" "$LOG_DIR"

BASELINE_OK=0
BASELINE_ERR=""
RESET_IIAB=0
ONLY_CONNECT=0

CHECK_NO_ADB=0
CHECK_SDK=""
CHECK_MON=""
CHECK_PPK=""

# Modes are mutually exclusive (baseline is default)
MODE="baseline"      # baseline|with-adb|adb-only|connect-only|ppk-only|check|all|login|proxy-start|proxy-stop|proxy-status

MODE_SET=0
CONNECT_PORT_FROM=""   # "", "flag", "positional"
BOXYPROXY_MANAGED=0

# Set backup / restore vars
PULL_USE_META4=1
PULL_KEEP_TARBALL=0
PULL_ARCH_MISMATCH_OK=0
BACKUP_RESTORE_TARGET=""

trap 'if [[ "${BOXYPROXY_MANAGED:-0}" -eq 1 ]]; then boxyproxy_stop >/dev/null 2>&1 || true; fi; power_mode_login_exit >/dev/null 2>&1 || true; adb_hint_notif_remove >/dev/null 2>&1 || true; cleanup_notif >/dev/null 2>&1 || true; release_wakelock >/dev/null 2>&1 || true' EXIT INT TERM
# NOTE: Termux:API prompts live in 40_mod_termux_api.sh

# -------------------------
# OS guardrails
# -------------------------
# Guard: avoid running iiab-termux inside proot-distro rootfs.
in_proot_rootfs() {
  # Debian rootfs indicator
  [ -f /etc/debian_version ] && return 0
  return 1
}

termux_path_leaked() {
  # Termux prefix on PATH indicates we're inside proot but inheriting host tools
  printf '%s' "${PATH:-}" | grep -q '/data/data/com\.termux/files/usr/'
}

guard_no_iiab_termux_in_proot() {
  if in_proot_rootfs && termux_path_leaked; then
    warn_red_context "Detected proot environment: IIAB Debian"
    warn "Don't run iiab-termux inside IIAB Debian"
    ok   "In order to run a first-time install run:"
    ok   "  iiab-android"
    blank
    warn "To resume or continue an installation in progress, use the usual IIAB command:"
    ok   "  iiab -f"
    blank
    warn "If you meant to prepare Termux, exit proot and run:"
    ok   "  iiab-termux --all"
    exit 2
  fi
}

guard_no_iiab_termux_in_proot

# -------------------------
# Self-check
# -------------------------
self_check() {
  local wlan_ip
  wlan_ip="$(adb_local_ipv4s_csv 2>/dev/null)"
  [[ -z "$wlan_ip" ]] && wlan_ip="Disconnected"

  log "Self-check summary:"
  log " iiab-termux version: $(get_iiab_termux_version "$0")"
  log " Android system details:"
  echo "        - Release: ${ANDROID_REL:-?}"
  echo "        - SDK:     ${ANDROID_SDK:-?}"
  echo "        - Arch:    $(get_android_arch)"
  log " Wireless IP:  ${wlan_ip}"
  if have proot-distro; then
    log " proot-distro: present"
    if iiab_exists; then log " IIAB Debian: present"; else log_yel " IIAB Debian: not present"; fi
  else
    warn " proot-distro: not present"
  fi

  if have adb; then
    log " android-tools: present"
    if adb_pick_loopback_serial >/dev/null 2>&1; then
      adb devices -l 2>/dev/null | indent || true
      #re-enable in need for verbose output.
      #run_if_adb_connected log " adb shell id (first device):"
      #run_if_adb_connected adb -s "$serial" shell id 2>/dev/null | indent || true
    fi
  else
    warn " android-tools: not present"
  fi

# Network & Proxy tools
  if python_has_zeroconf >/dev/null 2>&1; then
    log " mDNS/Zeroconf: present"
  else
    if sdk_le 29; then
      log " mDNS/Zeroconf: no wireless debugging"
    else
      warn " mDNS/Zeroconf: not present"
    fi
  fi

  if boxyproxy_is_installed >/dev/null 2>&1; then
    log " Boxyproxy: present"
  else
    warn " Boxyproxy: not present"
  fi

  # Quick Android flags check
  run_if_adb_connected self_check_android_flags || true

  if have termux-wake-lock; then log " Termux:API wakelock: available"; else log_yel " Termux:API wakelock: not available"; fi
  if have termux-notification; then log " Termux:API notifications: command present"; else log_yel " Termux:API notifications: missing"; fi
}

baseline_bail() {
  warn_red "Cannot continue: Termux baseline is incomplete."
  [[ -n "${BASELINE_ERR:-}" ]] && warn "Reason: ${BASELINE_ERR}"
  baseline_bail_details || true
  exit 1
}

final_advice() {
  if [[ "${BASELINE_OK:-0}" -ne 1 ]]; then
    warn_red "Baseline is not ready, so ADB prompts / IIAB Debian bootstrap may be unavailable."
    [[ -n "${BASELINE_ERR:-}" ]] && warn "Reason: ${BASELINE_ERR}"
    warn "Fix: check network + Termux repos, then re-run the script."
    return 0
  fi

  # 1) Android-related warnings (only meaningful if we attempted checks)
  local sdk="${CHECK_SDK:-${ANDROID_SDK:-}}"
  local _active=0
  case "${MODE:-}" in
    with-adb|adb-only|connect-only|ppk-only|check|all) _active=1 ;;
    *) _active=0 ;;
  esac

  local adb_connected=0
  local serial="" mon="" mon_fflag=""

  # Passive ADB detection
  if have adb; then
    adb start-server >/dev/null 2>&1 || true
    if adb_pick_loopback_serial >/dev/null 2>&1; then
      adb_connected=1
      serial="$(adb_pick_loopback_serial 2>/dev/null || true)"
    fi
  fi
  # Escalate to red only when user is actively checking/fixing,
  # OR when we already have ADB connected (strong evidence).
  advice_warn_bad() {  # args: message
    if (( _active || adb_connected )); then
      warn_red "$*"
    else
      warn "$*"
    fi
  }

  # Baseline safety gate:
  # On Android 12-13 (SDK 31-33), IIAB/proot installs can fail if PPK is low (often 32).
  # Baseline mode does NOT force ADB pairing nor run check_readiness(), so PPK may be unknown.
  # If PPK is not determined, suggest running --all BEFORE telling user to proceed to proot-distro.
  if [[ "$MODE" == "baseline" ]]; then
    if [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 31 && sdk <= 33 )); then
      # If we didn't run checks, CHECK_PPK will be empty. Even with adb_connected=1, baseline
      # still doesn't populate CHECK_PPK unless user ran --check/--all.
      if [[ "${CHECK_PPK:-}" != "" && "${CHECK_PPK:-}" =~ ^[0-9]+$ ]]; then
        : # PPK determined -> ok to continue with normal advice below
      else
        warn "Android 12-13: PPK fix hasn't been verified (max_phantom_processes may be low, e.g. 32)."
        warn "Before starting the IIAB install, run the complete setup so it can apply/check PPK fix; otherwise the installation may fail:"
        ok   "  iiab-termux --all"
        return 0
      fi
    elif [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 34 )); then
      # On Android 14+, rely on "Disable child process restrictions"
      # Proxy signals: settings_enable_monitor_phantom_procs (or the fflag override).
      # Baseline does not run check_readiness(), so CHECK_MON is usually empty.
      if [[ "${CHECK_MON:-}" == "false" ]]; then
        : # Verified OK (rare in baseline) -> continue
      else
        # If ADB is already connected, try to read the flag best-effort (no prompts).
        if [[ "$adb_connected" -eq 1 && -n "${serial:-}" ]]; then
          mon="$(adb_get_monitor_phantom_procs "$serial")"
        fi

        if [[ "${mon:-}" == "false" ]]; then
          : # Restrictions already disabled -> ok to continue
        else
          if [[ "${mon:-}" == "true" ]]; then
            log_yel "Child process restrictions appear ENABLED (monitor=true)."
            log_yel "Please make sure to set 'Disable child process restrictions' enabled; otherwise the installation may fail."
            return 0
          fi
        fi
      fi
    fi
  fi

  if [[ "${CHECK_NO_ADB:-0}" -eq 1 ]]; then
    # If we could not check, still warn on A12-13 because PPK is critical there
    if [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 31 && sdk <= 33 )); then
      warn "A12-13: verify PPK fix before installing IIAB."
    fi
  else
    # A14+ child restrictions proxy (only if readable)
    if [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 34 )) && [[ "${CHECK_MON:-}" == "true" ]]; then
      advice_warn_bad "A14+: disable child process restrictions before installing IIAB."
    fi

    # Only warn about PPK on A12-13 (A14+ uses child restrictions)
    if [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 31 && sdk <= 33 )); then
      if [[ "${CHECK_PPK:-}" =~ ^[0-9]+$ ]] && (( CHECK_PPK < 256 )); then
        advice_warn_bad "PPK is low (${CHECK_PPK}); consider --ppk-only."
      fi
    fi
  fi

  # 2) IIAB Debian "next step" should only be shown for modes that actually bootstrap IIAB
  case "$MODE" in
    baseline|with-adb|pull-rootfs|all)
      if iiab_exists; then
        ok "Next: iiab-termux --start"
      else
        warn "IIAB Debian not present. Run:"
        warn "Preferred: iiab-termux --all"
      fi
      ;;
    *)
      # adb-only/connect-only/ppk-only/check: do not suggest Debian login as a generic ending
      ;;
  esac
}

cmd_install_self() {
  local current_file="$1"
  local target="${PREFIX}/bin/iiab-termux"
  
  if [[ -z "${PREFIX:-}" ]]; then
    die "PREFIX is not defined. Are you running inside Termux?"
  fi

  # Get absolute path safely
  local abs_current; abs_current="$(realpath "$current_file" 2>/dev/null || echo "$current_file")"

  if [[ "$abs_current" == "$target" ]]; then
    ok "Script is already installed at: $target"
    return 0
  fi

  log "Installing script to: $target"
  mkdir -p "${PREFIX}/bin" >/dev/null 2>&1 || true
  cp -f "$abs_current" "$target" || die "Failed to copy script to $target"
  chmod 700 "$target" || true
  ok "Successfully installed! You can now run 'iiab-termux' from anywhere."
}

# -------------------------
# Args
# -------------------------
set_mode() {
  local new="$1"
  if [[ "$MODE_SET" -eq 1 ]]; then
    die "Modes are mutually exclusive. Already set: --${MODE}. Tried: --${new}"
  fi
  MODE="$new"
  MODE_SET=1
}

while [[ $# -gt 0 ]]; do
  case "$1" in
    --with-adb) set_mode "with-adb"; shift ;;
    --adb-only) set_mode "adb-only"; shift ;;
    --start|--login) set_mode "login"; shift ;;
    --stop) set_mode "stop"; shift ;;
    --connect-only)
      set_mode "connect-only"
      ONLY_CONNECT=1
      # Optional positional connect spec (accept PORT or IP:PORT)
      if [[ -n "${2:-}" ]]; then
        connect_norm=""
        if connect_norm="$(normalize_port_5digits "${2:-}" 2>/dev/null)"; then
          if [[ -n "${CONNECT_PORT_FROM:-}" && "${CONNECT_PORT_FROM}" != "positional" ]]; then
            die "CONNECT PORT specified twice (positional + --connect-port). Use only one."
          fi
          CONNECT_PORT="$connect_norm"
          CONNECT_PORT_FROM="positional"
          shift 2
          continue
        fi
      fi
      shift
      ;;
    --bb|--barebones) set_mode "barebones"; shift ;;
    --ppk-only) set_mode "ppk-only"; shift ;;
    --iiab-android) set_mode "iiab-android"; shift ;;
    --check) set_mode "check"; shift ;;
    --all) set_mode "all"; shift ;;
    --proxy-start) set_mode "proxy-start"; shift ;;
    --proxy-stop) set_mode "proxy-stop"; shift ;;
    --proxy-status) set_mode "proxy-status"; shift ;;
    --proxy-no-external) BOXYPROXY_NO_EXTERNAL=1; shift ;;
    --connect-port)
      if [[ -n "${CONNECT_PORT_FROM:-}" && "${CONNECT_PORT_FROM}" != "flag" ]]; then
        die "CONNECT PORT specified twice (positional + --connect-port). Use only one."
      fi
      CONNECT_PORT="$(normalize_port_5digits "${2:-}" 2>/dev/null)" || {
        die "Invalid --connect-port (must be 5 digits PORT or IP:PORT): '${2:-}'"
      }
      CONNECT_PORT_FROM="flag"
      shift 2
      ;;
    --timeout) TIMEOUT_SECS="${2:-180}"; shift 2 ;;
    --host) HOST="${2:-127.0.0.1}"; shift 2 ;;
    --reset-iiab|--shell) RESET_IIAB=1; shift ;;
    --remove-iiab|--remove-rootfs) set_mode "remove-iiab"; shift ;;
    --no-log) LOG_ENABLED=0; shift ;;
    --log-file) LOG_FILE="${2:-}"; shift 2 ;;
    --debug) DEBUG=1; shift ;;
    --install-self) set_mode "install-self"; shift ;;
    --welcome) set_mode "welcome"; shift ;;
    --json-vars) set_mode "json-vars"; shift ;;
    -h|--help) usage; exit 0 ;;
    --version)
      log "installed version: $(get_iiab_termux_version "$0")"
      exit 0
      ;;
    --update) set_mode "update"; shift ;;
    --list-backups) set_mode "list-backups"; shift ;;
    --backup-rootfs)
      set_mode "backup-rootfs"
      # Check if the next argument is a path (and not another flag)
      if [[ -n "${2:-}" && "${2}" != -* ]]; then
        BACKUP_RESTORE_TARGET="$2"
        shift 2
      else
        shift 1
      fi
      ;;
    --restore-rootfs)
      set_mode "restore-rootfs"
      if [[ -n "${2:-}" && "${2}" != -* ]]; then
        BACKUP_RESTORE_TARGET="$2"
        shift 2
      else
        die "--restore-rootfs requires a file path."
      fi
      ;;
    --pull-rootfs)
      set_mode "pull-rootfs"
      if [[ -n "${2:-}" && "${2}" != -* ]]; then
        BACKUP_RESTORE_TARGET="$2"
        shift 2
      else
        BACKUP_RESTORE_TARGET="AUTO"
        shift 1
      fi
      ;;
    --install-module)
      set_mode "install-module"
      INSTALL_TARGET="${2:-}"
      shift 2
      ;;
    --no-meta4)
      PULL_USE_META4=0
      shift
      ;;
    --keep-tarball)
      PULL_KEEP_TARBALL=1
      shift
      ;;
    --arch-mismatch-ok)
      PULL_ARCH_MISMATCH_OK=1
      shift
      ;;
    --*) die "Unknown option: $1. See --help." ;;
    *) shift ;;
  esac
done

sdk_is_num() { [[ "${ANDROID_SDK:-}" =~ ^[0-9]+$ ]]; }
sdk_le() { local n="$1"; sdk_is_num && (( ANDROID_SDK <= n )); }
sdk_eq() { local n="$1"; sdk_is_num && (( ANDROID_SDK == n )); }

warn_skip_adb_pre11() {
  warn "Android 8-10: skipping ADB steps (Wireless debugging pairing is not available)."
  warn "This is OK: so far, our testing indicates ADB is not required on those versions."
}

warn_adb_only_pre11() {
  warn "Android 8-10: --adb-only cannot run Wireless debugging pairing (Android 11+ feature)."
  warn "So far, our testing indicates ADB is not required on Android 8-10."
}

validate_args() {
  if [[ -n "${CONNECT_PORT:-}" ]]; then
    local raw="$CONNECT_PORT" norm=""
    norm="$(normalize_port_5digits "$raw" 2>/dev/null)" || {
      die "Invalid --connect-port (must be 5 digits PORT or IP:PORT): '$raw'"
    }
    CONNECT_PORT="$norm"
    # Android 8-10 (SDK <=29): Wireless debugging pairing isn't available.
    # If user provided --connect-port, make it explicit it's ignored here.
    if sdk_le 29; then
      warn "Android 8-10: ignoring --connect-port (ADB wireless pairing/connect is not available)."
      CONNECT_PORT=""
      CONNECT_PORT_FROM=""
      return 0
    fi
    case "$MODE" in
      adb-only|with-adb|connect-only|ppk-only|check|all) : ;;
      baseline)
        log "--connect-port requires an ADB mode."
        die "Use along with: --adb-only / --with-adb / --connect-only / --check / --ppk-only / --all"
        ;;
      *)
        die "--connect-port is not valid with mode=$MODE"
        ;;
    esac
  fi
}

# Android 12-13 only (SDK 31-33): apply PPK tuning automatically
attempt_auto_apply_ppk() {
  local sdk="${ANDROID_SDK:-}"
  if [[ "$sdk" =~ ^[0-9]+$ ]] && (( sdk >= 31 && sdk <= 33 )); then
    log "Android SDK=${sdk} detected -> applying --ppk automatically (12-13 rule)."
    ppk_fix_via_adb || true
  else
    log "Android SDK=${sdk:-?} -> skipping auto-PPK (only for Android 12-13)."
  fi
}

run_barebones_logic() {
  step_termux_base || baseline_bail
  power_mode_offer_battery_settings_once || true
  power_mode_offer_overlay_settings_once || true
  repo_selector_ask_configure
  boxyproxy_install_or_update || true
}

# -------------------------
# Main flows
# -------------------------
main() {
  setup_logging "$@"
  validate_args
  sanitize_timeout
  acquire_wakelock

  # Sync state to Android App: Installer is actively running/present
  set_android_state_flag "flag_installer_present"

  case "$MODE" in
    update)
      update_iiab_termux "$0"
      ;;

    install-self)
      cmd_install_self "$0"
      ;;

    welcome)
      welcome_interactive "Preview"
      ;;

    json-vars)
      cmd_json_vars
      ;;

    login)
      iiab_login
      ;;

    stop)
      iiab_stop
      ;;

    list-backups)
      cmd_list_backups
      ;;

    backup-rootfs)
      cmd_backup_rootfs "$BACKUP_RESTORE_TARGET"
      ;;

    restore-rootfs)
      cmd_restore_rootfs "$BACKUP_RESTORE_TARGET"
      ;;

    pull-rootfs)
      run_barebones_logic
      cmd_pull_rootfs "$BACKUP_RESTORE_TARGET" "$PULL_USE_META4" "$PULL_KEEP_TARBALL" "$PULL_ARCH_MISMATCH_OK"
      self_check
      ;;

    install-module)
      cmd_install_module "$INSTALL_TARGET"
      ;;

    remove-iiab)
      cmd_remove_iiab
      ;;

    barebones)
      offer_welcome_once "Barebones"
      check_preflight_requirements
      run_barebones_logic
      self_check
      ;;

    baseline)
      offer_welcome_once "Baseline"
      step_termux_base || baseline_bail
      power_mode_offer_battery_settings_once || true
      power_mode_offer_overlay_settings_once || true
      repo_selector_ask_configure
      boxyproxy_install_or_update || true
      step_iiab_bootstrap_default
      install_iiab_android_cmd || true
      self_check
      ;;

    with-adb)
      offer_welcome_once "With ADB"
      step_termux_base || baseline_bail
      power_mode_offer_battery_settings_once || true
      power_mode_offer_overlay_settings_once || true
      repo_selector_ask_configure
      boxyproxy_install_or_update || true
      step_iiab_bootstrap_default
      install_iiab_android_cmd || true
      # Android 8-10: skip ADB (no Wireless debugging pairing).
      if sdk_le 29; then
        warn_skip_adb_pre11
      else
        adb_pair_connect_if_needed
      fi
      self_check
      ;;

    adb-only)
      step_termux_base || baseline_bail
      # Android 8-10: no Wireless debugging pairing flow (Android 11+ feature).
      if sdk_le 29; then
        warn_adb_only_pre11
        return 0
      fi
      adb_pair_connect_if_needed
      self_check
      ;;

    connect-only)
      step_termux_base || baseline_bail
      adb_pair_connect
      self_check
      ;;

    ppk-only)
      # No baseline. Only requires adb already available + connected.
      require_adb_connected || exit 1
      ppk_fix_via_adb || true
      self_check
      ;;

    iiab-android)
      offer_welcome_once "IIAB Android"
      step_termux_base || baseline_bail
      power_mode_offer_battery_settings_once || true
      power_mode_offer_overlay_settings_once || true
      repo_selector_ask_configure
      step_iiab_bootstrap_default
      boxyproxy_install_or_update || true
      install_iiab_android_cmd || true
      ;;

    check)
      step_termux_base || baseline_bail
      check_readiness || true
      check_preflight_requirements
      self_check
      ;;

    all)
      offer_welcome_once "All - Full Setup"
      step_termux_base || baseline_bail
      power_mode_offer_battery_settings_once || true
      power_mode_offer_overlay_settings_once || true
      repo_selector_ask_configure
      step_iiab_bootstrap_default
      boxyproxy_install_or_update || true
      boxyproxy_start || true
      install_iiab_android_cmd || true
      if sdk_is_num && (( ANDROID_SDK >= 34 )); then
        # Android 14+
        log_yel "Android 14+: Skipping ADB setup."
        log_yel "Reminder: enable Developer Options -> 'Disable child process restrictions' (otherwise installs may fail)."
        CHECK_NO_ADB=1
        CHECK_SDK="${ANDROID_SDK:-}"
      elif sdk_eq 30; then
        # Android 11
        log_yel "Android 11: Skipping ADB setup."
        log_yel "Note: Wireless debugging is optional here; installs usually work without ADB."
        CHECK_NO_ADB=1
        CHECK_SDK="${ANDROID_SDK:-}"
      elif sdk_le 29; then
        # Android 8-10
        warn_skip_adb_pre11
        CHECK_NO_ADB=1
        CHECK_SDK="${ANDROID_SDK:-}"
      else
        # Android 12-13 (SDK 31-33): ADB + PPK still needed
        adb_pair_connect_if_needed
        attempt_auto_apply_ppk
        check_readiness || true
      fi
      self_check
      ;;

    proxy-start)
      termux_prepare_boxyproxy_deps || baseline_bail
      boxyproxy_start
      ;;

    proxy-stop)
      boxyproxy_stop
      ;;

    proxy-status)
      boxyproxy_status
      ;;

    *)
      die "Unknown MODE='$MODE'"
      ;;
  esac

  blank
  ok "Setup tasks for mode '${MODE}' completed."
  printf "${BLU}[iiab]${RST} You can see the iiab-termux mode list with:\n"
  printf "  ${BOLD}iiab-termux --help${RST}\n"

  # Do not print generic "next steps" for certain modes.
  case "$MODE" in
    # Backup and system utilities
    backup-rootfs | remove-iiab)
      : ;;
    # Proxy Management
    proxy-start | proxy-stop | proxy-status)
      : ;;
    # Single commands with no final advice
    login | update | install-self | welcome)
      : ;;
    *) final_advice ;;
  esac
}

main "$@"

# ---- END 99_main.sh ----