Add Dual-Stack Network Diagnostics

docs/agent/architecture.md

@@ -187,6 +187,14 @@ Admin SSH `exit`, remote reboot, SSH stop/disconnect, and host-key rotate/reset
 
 Browser stop/reboot uses this same owner-adapter control path. Exact forced certificate rotation instead uses the typed queue union and immutable `dispatcher_actions` mask to hand off after drain/200 ms to the existing 12 KiB dispatcher, not the 4 KiB control stack. Pending input is discarded through execution and an executing slot remains reserved across self-detach. Canonical shared service/identity replacement preserves commit/stop/start failure semantics. Parsed other-account interactive add/password and forced role/delete are allowed. Canonical Wi-Fi commands are also allowed, including hidden secret prompts and disruptive changes; these use the ordinary owner queue and may cut off the browser before output arrives, without a deferred acknowledgement guarantee. Browser self/generated/key/recovery, mDNS mutations and restricted SSH shell actions remain denied; typed Settings has separate permissions. Post-prompt currentness is operation admission, not an atomic session-liveness/NVS guarantee. [Browser policy and recovery](../web_administration.md#browser-shell-policy).
 
+### Shared IPv4/IPv6 diagnostics
+
+`network_console` owns root and `wifi`-alias ping/traceroute/nslookup for UART0, admin SSH and browser Admin. Family flags are parsed once; explicit IPv6 never silently falls back to IPv4. Hostname probes use IPv4-first resolution fallback only; nslookup queries A and AAAA separately and shows unscoped link-local answers. Probes require a device-local link-local zone (`%sta`, `%ap`, valid index/name). Resolver policy/DNS provisioning and serial transport ownership are unchanged.
+
+Traceroute owns one raw socket and a 1280-byte transient receive buffer on the shared dispatcher stack, one eight-byte probe per hop (max30), and one-second absolute receive deadlines. It rejects incomplete/corrupt/unrelated packets and unsupported IPv6 extension headers/fragments. IDF5.5.0-specific framing, automatic ICMPv6 checksum, common `IP_TTL` hop-limit behavior and millisecond timeout flooring are pinned/retested; <1ms remaining returns timeout rather than configuring an infinite wait. DNS and send/scheduler latency are not covered by the receive deadline.
+
+Ping keeps the 4200-byte PSRAM-only lazy queue payload and SDK transient task. Permanent callback context plus a pending reservation survives the count-based console deadline; later pings cannot reset a live producer's queue. SDK receive can outlast its timeout under unrelated ICMP, so a timed-out session stays reserved until END. END means callback production ended, not synchronous task/socket destruction; retiring resources can briefly overlap a new session. These diagnostics serialize administration but never execute on HTTPD or enter the serial hot path. Tests and exact limits: `tests/network_diagnostics/README.md`.
+
 ## Wi-Fi and persistence
 
 `wifi_config` owns a fixed-width versioned NVS schema with four prioritized station profiles and AP policy `off`, `fallback`, or `always`. Missing configuration generates per-device defaults including a random AP password. Invalid stored data is generally left untouched while RAM defaults are used.

docs/agent/code-map.md

@@ -150,6 +150,7 @@ Shared UI regression: `tests/web_ui_session/run.py` and its domain `.cjs` fixtur
 - Ownership: dispatcher is sole `esp_console_run()` caller; the SSH owner exclusively performs post-initialization wolfSSH runtime calls.
 - Lifecycle: remote session tokens include slot generation; fixed output/history/prompt state is wiped immediately on idle close or after an executing handler returns. Admin SSH `exit` and Ctrl+D on an empty command line request bounded deferred self-disconnect after best-effort output draining.
 - Constraint: one slow command or prompt serializes all administration. Admin SSH is unavailable until command registration and UART frontend creation complete; supported deferred actions wait only for a bounded application-buffer drain heuristic.
+- Dual-stack diagnostics: `network_console.*` is the shared root/`wifi` handler on all three admin surfaces. `-4`/`-6`, device-local `%sta`/`%ap`/index/name; default probes IPv4-first resolution fallback only, nslookup explicit A+AAAA and unscoped link-local display. One-second/hop raw IPv4/IPv6 traceroute validates full outer packet/quoted echo and rejects IPv6 extensions/fragments. IDF5.5.0 raw framing/hoplimit/checksum/timeout contract is version-guarded. Ping uses existing PSRAM queue and SDK transient task with permanent callback context/deadline/pending reservation; END does not imply completed SDK teardown. Tests: `tests/network_diagnostics` (actual handlers/packet and SDK contracts), `tests/network_diagnostics_surfaces` (routing/policy/completion). No serial hot-path changes.
 
 ## Wi-Fi
 

docs/agent/current-state.md

@@ -2,6 +2,14 @@
 
 Working memory, not an implementation timeline. Source is authoritative; begin with [code map](code-map.md), [architecture](architecture.md) and [decisions](design-decisions.md).
 
+## Dual-stack diagnostics follow-up — implemented, device validation pending
+
+- User explicitly requested IPv6 ping/traceroute/nslookup on all surfaces after accepting Phase12. Shared `network_console.*` now supports one `-4`/`-6` anywhere after command, preserves count/hop bounds, root and `wifi` aliases. Default probes try IPv4 then IPv6 on resolution failure only; nslookup performs A+AAAA queries separately (one selected address/family), displays unscoped link-local records. Link-local probes require ESP-local `%sta`/`%ap`/index/name; no client-interface guess or IPv4-mapped fallback. Help/completion updated; permissions unchanged.
+- Actual IDF5.5.0 audit: raw ICMPv6 includes outer IPv6 header, automatic TX checksum, common `IPPROTO_IP/IP_TTL` hoplimit; replies validate checksums/target/id/seq and reject extensions/fragments. Traceroute one socket/max30 probes/1s receive deadline, 1280B receive buffer. Review caught sub-ms timeout flooring to infinite SDK wait; <1000us now returns timeout, actual SDK conversion/mailbox tests verify. No dependency/config/partition/serial path change.
+- Ping retains4200B PSRAM queue, max20 probes and SDK transient task; permanent callback context plus pending reservation protects delayed END after count*2+2 second console deadline. SDK unrelated-ICMP receive loop may outlive timeout; later pings fail busy until END, which does not prove synchronous resource destruction. Read exact limits in command reference/tests README. IPv6-only unicast DNS still requires a configured resolver; no RDNSS/DHCPv6 provisioning added.
+- `pio run` PASS **94,452 B linked RAM / 1,857,673 B flash**, +8/+3,188 versus accepted prior build. Traceroute receive-wait object frame measured240→1408B (not runtime stack high-water). No new permanent task/socket/queue capacity. Hardware/ changes in working tree belong to other agent and were not read/edited.
+- Parent PASS: production diagnostics8027 checks+10k malformed packet inputs, seven installedSDK hashes+actualtimeout fixtures, 432 SSH/WEB root+alias routing cases/UART parity/ordinary-role and revocation guards/completion, existing admin policy and browser Wi-Fi secret fixture. Independent review fixes verified no remaining actionable findings in scoped paths. ASan/UBSan host runtimes absent. Broader console-boundary pre-existing missing rebootfake remains (not changed). No upload/device/network test; Phase12 acceptance remains valid only for its recorded baseline, not this follow-up.
+
 ## Phase 12 COMPLETE — explicit user validation
 
 - User states: “I just validated Phase 12 successfully.” Record acceptance, not a pending phase. Canonical device evidence and reusable regression guidance: [Phase 12](../roadmap.md#phase-12--advanced-network-integration). No unreported DHCP capture, DNS-zone update, exhaustive address/service transition, fault/soak or byte-integrity pass is implied.