Recover Companion WiFi TCP listener failures and expose diagnostics

docs/cli_commands.md

@@ -422,6 +422,26 @@ credentials alone do not turn it on. ESP32 simultaneous-transport builds apply
 the change from the main loop; exclusive-transport builds and Pico W apply it
 after reboot. This does not disable a primary ESP-NOW mesh radio or add Bluetooth
 to a WiFi-only build.
+
+ESP32 WiFi Companions also accept `get wifi.tcp` over USB, BLE, or the browser
+CLI. This checks the app's TCP listener (normally port `5000`), not just the
+WiFi association. `listening` means the socket is open; `waiting-ip` means no
+usable station or setup-AP address yet; `retrying` means listener startup
+failed and will be retried automatically; `off` means no enabled listener
+request. `reg=1` confirms the interface is registered for Companion commands.
+`client=1` means a TCP client is connected. `acc`, `rx`, and `tx` count accepted
+clients, complete received frames, and complete transmitted frames since boot;
+the value after `/` is the last frame's hexadecimal opcode. `fail`, `err`, and
+`retry` show listener failures, the last socket error, and seconds until retry.
+`drop` gives the last client-disconnect reason. These counters contain no
+message contents or credentials. An open listener does not prove a router or
+guest-network firewall permits access from the phone.
+
+Listener retries wait 1, 2, 4, 8, 16, then at most 30 seconds. They do not
+reconnect WiFi, interrupt BLE/WebConfig/OTA, replace a healthy app connection,
+or re-enable explicitly disabled WiFi. `get display.wifi` includes `tcp=1`
+only when the listener is actually open; `services=1` alone is not proof.
+
 See [local maintenance commands](terminal_chat_cli.md#local-maintenance-commands)
 for the complete access rules. WiFi-only Companions accept
 all three modes. A Full Companion that runs BLE and infrastructure WiFi

docs/companion_protocol.md

@@ -314,6 +314,11 @@ WiFi store, and enablement is saved in node preferences. WiFi/BLE builds apply
 enablement from the main loop; exclusive WiFi/BLE builds apply it after reboot.
 `get wifi.status` reports the connection state and `get wifi.ip` reports the
 station address, the setup AP address, or `(not connected)`.
+`get wifi.tcp` reports the actual app listener, interface registration, client
+connection and completed frame counters. It is read-only and available through
+the same binary CLI command over BLE or USB when TCP is unreachable. Listener
+startup failures recover automatically without resetting a healthy client or
+the WiFi connection; see [the CLI diagnostics](cli_commands.md#browser-configuration-portal-esp32-repeater-and-room-server).
 `set freq <MHz>` works through command `0x42` and authorized LoRa CLI, like
 `set radio`; it saves the frequency and requires reboot to apply. See
 [local maintenance commands](terminal_chat_cli.md#local-maintenance-commands)

docs/companion_radio_full.md

@@ -525,6 +525,17 @@ their views. Companion session state is device-wide, so use one active
 Companion application at a time. On nRF52, BLE remains available while USB is
 in terminal or mOTA mode.
 
+The Companion TCP listener starts only after a usable WiFi station or setup-AP
+address exists. If opening the socket fails, it closes any failed-start socket
+and retries with a delay capped at 30 seconds, without restarting the WiFi
+connection or disturbing BLE, WebConfig, OTA, or a healthy accepted TCP client.
+Turning WiFi off or suspending it cancels the listener request; retry service
+cannot turn it back on. Use `get wifi.tcp` through BLE, USB, or the browser CLI
+to inspect listener state, registration, accepted clients, completed RX/TX
+frames, and errors without a PC port probe. `get display.wifi` also shows the
+actual `tcp` listener flag independently of the network-services flag. A
+listening socket alone cannot detect LAN firewall or guest-network isolation.
+
 On WiFi TCP port 5000, reconnecting from the same IP retains queued outgoing
 frames. A different IP takes over immediately, but never receives the previous
 IP's replies: up to four queued frames are parked separately for 30 seconds