{
  "title": "phone_focus_mode/enable_persistent_adb.sh: make adb-over-Wi-Fi reachable without anyone touching the phone",
  "objective": "Android's Wireless debugging is deliberately ephemeral: the listener dies when you leave the settings screen or the device sleeps, and it picks a new random port every time it comes back (observed three different ports in one session: 35545, 40401, 43781). Every deploy therefore began with tapping through Settings on the phone. Pin adbd to a fixed port that comes back on its own after a reboot, and make the laptop able to find the phone even if DHCP moves it. Success: with the phone merely on the same network - screen off, nothing opened, nothing tapped - `adb connect` reaches it, and it still does after a reboot.",
  "acceptance_criteria": [
    "adbd listens on the fixed port 5555, which is the port deploy.sh has always assumed",
    "A Magisk service.d boot script re-applies the port on every boot, verified by an actual reboot rather than inferred from the mechanism",
    "The laptop finds the phone by MAC when the configured IP is wrong, since the phone is on DHCP and has no reservation; verified by running the script against a deliberately wrong address",
    "The script never reports success for a connection it does not actually have - it matches the exact ip:port, not the first `device` line, because pairing also leaves an mDNS _adb-tls-connect._tcp entry for the same phone that made an earlier version report a closed port as reachable",
    "It fails loudly and bounded rather than spinning forever when no window ever appears",
    "shellcheck clean, set -uo pipefail, no inline logic in another language"
  ],
  "out_of_scope": [
    "A router DHCP reservation - it would work but needs router access and only helps on one network; MAC discovery is strictly better and needs nothing",
    "USB debugging - the point is to not touch the phone at all",
    "Turning off Android's Wireless debugging UI - it stays available as the bootstrap path for a phone that has never been set up",
    "Any change to what deploy.sh does once connected"
  ],
  "verifier": "./enable_persistent_adb.sh 192.168.1.64 <ephemeral-port> (installs the boot script and switches the port); nmap -p 5555 -Pn 192.168.1.64 shows open; ./enable_persistent_adb.sh 192.168.1.99 (wrong IP on purpose) reports 'phone moved' and still connects; adb reboot, then ./enable_persistent_adb.sh with no arguments connects with zero interaction; shellcheck enable_persistent_adb.sh"
}