ESP32_Serial_Swiss_Army_Knife/docs/agent/current-state.md

Current project state

This file is working memory. Update it during active work and before handoff; do not treat it as a permanent design record.

Development state

Based on checked-in source plus README.md and docs/roadmap.md:

• Hardware characterization, serial service, session broker, USB CDC, Wi-Fi, HTTPS/WebSocket, SSH serial transport, and local display/control are implemented and documented as target-hardware validated.
• Phase 8A role-based user storage/UART0 administration and Phase 8B role-aware HTTPS/SSH authentication and targeted revocation are documented as target-hardware validated.
• Phase 8C admin SSH is implemented in source and uses the shared esp_console registry. Target-hardware validation is explicitly pending.
• Phase 8D web user administration and Phase 8E browser login/session integration are planned, not implemented.
• Security/production hardening, OTA, BLE evaluation, advanced networking, and optional filesystem features remain future roadmap work.
• Reserved OTA, coredump, NVS-key, and storage partitions do not imply those runtime features are implemented.

Recent memory audit

• Fixed failed-initialization ownership leaks for wolfSSH, partial HTTPS startup, and TinyUSB teardown. Failed teardown now retains ownership and blocks unsafe duplicate initialization.
• Serial-service RX/TX stream payloads (16 KiB and 8 KiB effective capacity) now prefer PSRAM with internal fallback; FreeRTOS controls and UART driver buffers remain internal.
• The 5,360-byte transactional user-database candidate now prefers PSRAM with internal fallback while the live database remains internal. Candidate contents are wiped after each transaction and wiped/freed on initialization or recovery failure.
• UART and admin-SSH completion formatter buffers were reduced from 2 KiB to 1 KiB each; current worst-case output is 890 bytes and overflow remains fail-closed.
• Linked RAM fell from 99,508 to 92,188 bytes (7,320 bytes). PSRAM placement of serial payloads additionally removes about 24 KiB of normal internal-heap pressure on the target.
• pio run passes. A preliminary target run reports significantly more free memory and stable, improved operation after these changes. This is useful evidence but not completion of Phase 8C validation.
• The reviewed mDNS-enabled build uses 94,532 bytes of linked static RAM, 2,344 bytes above the earlier 92,188-byte baseline, and 1,599,765 bytes of flash. Minimizing the managed component saved 112 bytes of linked RAM and about 5.9 KiB flash versus the first mDNS build. Its 4 KiB task stack remains internal, while checked-in settings move general mDNS allocations to PSRAM and disable unused browse, component CLI, AP/ETH, and multiple-instance features. Runtime heap impact still requires target measurement.
• Remaining targeted checks include stored/migrated/recovered user-database mutations, USB enumeration, HTTPS start/stop failure recovery where injectable, SSH initialization/login, completion display, and sustained multi-transport serial traffic while checking memory telemetry.

Clearly incomplete or transitional areas

• Phase 8C hardware-validation matrix remains pending. It includes route separation, shared command serialization, history/completion, prompts, output backpressure, revocation during queued work, deferred SSH lifecycle/reboot actions, and full concurrent transport operation.
• Current HTTPS has no web-based user administration and gives both roles the same status/terminal routes.
• Browser authentication still uses HTTP Basic; integrated login/logout sessions are planned.
• NVS encryption, secure boot/flash encryption review, authentication rate limiting, production certificate/provisioning policy, and OTA are not implemented.

Known inconsistencies

These observations should be checked when touching the relevant area; they are not automatically bugs requiring unrelated cleanup.

• Some source comments still call shared commands UART0-only or call the current local status/control task read-only.
• USER_DATABASE_LOAD_EMPTY is only an initialization/failure sentinel at the checked-in revision: every successful user_database_init() path returns STORED or MIGRATED_LEGACY, so main.c's successful "new empty" log branch is unreachable.
• SSH startup is currently gated on successful web_security initialization even though SSH uses separate host-key material. Needs verification: whether this coupling is intentional recovery policy or an accidental startup dependency.

Items to verify in future work

• Complete the documented Phase 8C target-hardware validation before marking it complete.
• Confirm task-local Newlib standard-stream behavior if ESP-IDF/Newlib configuration changes; admin SSH command output relies on dispatcher-task stream redirection.
• If HTTPD concurrency configuration changes, add locking around the boot-local Basic-authentication cache.

Active Task

• Objective: Announce a configurable sak-<suffix>.local hostname through mDNS when Wi-Fi STA has an IPv4 address, without changing the Wi-Fi NVS blob schema.
• Relevant files: src/mdns_config.{c,h}, src/mdns_service.{c,h}, src/mdns_console.{c,h}, src/wifi_manager.{c,h}, src/main.c, src/CMakeLists.txt, src/idf_component.yml, dependencies.lock, completion and command documentation.
• Findings: wifi_manager already serializes all meaningful STA transitions through its permanent task; callbacks only enqueue events. This is the appropriate lifecycle owner for mDNS, while a separate configuration module preserves the existing wifi_app/config wire format.
• Decision: Persist a fixed v1 record under mdns_cfg/config, separate from Wi-Fi configuration. Defaults derive a safe lower-case hexadecimal suffix from the STA MAC. The manager initializes mDNS at most once after validating IP_EVENT_STA_GOT_IP; the managed component's own handlers withdraw/restore the STA responder across connectivity changes, and online hostname changes use mdns_hostname_set() without teardown. Initialization failure is latched instead of retried because the resolved upstream 1.12.0 component has an unsafe partial low-memory initialization path. mDNS errors cannot fail Wi-Fi, UART0, UART1, or native USB.
• Changes completed: Added the espressif/mdns managed dependency (resolved to 1.12.0 on IDF 5.5), mDNS config/service/console modules, mdns status|suffix|save|load|defaults|reset, completion, CMake integration, and command/architecture documentation. Minimized the component to STA-only responder use, moved general allocations to PSRAM, retained the internal task stack, and removed reconnect-time free/reinit churn. Final pio run passes at 94,532 bytes linked RAM and 1,599,765 bytes flash.
• Remaining work: Target-hardware verification: associate a station and resolve the default sak-<mac>.local; change/save/load a suffix and confirm live reannouncement plus reboot persistence; stop Wi-Fi or remove the STA lease and confirm the record withdraws. Verify serial, native USB, and UART0 remain available if mDNS initialization fails.
• Risks / things to remember: Hostnames are STA-only and are intentionally not announced by fallback AP mode. NVS changes to mdns_cfg/config are independent of the unchanged wifi_app/config blob. mDNS remains allocated after first successful initialization (including its internal 4 KiB task stack) to avoid fragmentation and unsafe repeated initialization; measure free/minimum/largest internal heap and mDNS stack margin during reconnect stress.

Handoff template

• Objective:
• Relevant files:
• Findings:
• Decisions made:
• Changes completed:
• Remaining work:
• Risks / things to remember: