fix(esp): raise loopTask stack so the OTA manifest TLS handshake fits

[cofade]

Addresses #276 — the one-line fix is verified on hardware, but the issue's follow-up questions (a measured stack bound, and whether setup()'s TLS call sites should share a task with an explicit stack) are deliberately not answered here, so this should not auto-close the issue.

What was broken

Current main firmware could not complete setup() on real hardware. A field module joined Wi-Fi, printed an IP, then panicked and rebooted — a ~5.7 s crash loop — so it never reached registration, heartbeat, geolocation or capture, and never appeared on the dashboard.

[WIFI] (re)connected, IP: 192.168.178.120
[STAGE] arduino_ota_begin took=15ms
Guru Meditation Error: Core  1 panic'ed (Unhandled debug exception).
Debug exception reason: Stack canary watchpoint triggered (loopTask)

Next boot: [BOOT] last_stage_before_reboot=ota:manifest_fetch.

setup() runs on the Arduino core's loopTask, whose stack is 8192 bytes by default (ARDUINO_LOOP_STACK_SIZE, in the core's main.cpp — a default that no repo file configures or references). That is not enough for an mbedTLS handshake that parses and verifies a certificate chain against the pinned ISRG Root X1, which is what ota.cpp's httpOtaCheckAndApply does. It dies inside the handshake, before the manifest's status line is read — which reads as a network failure and is not one.

Neither build path raised the default, so the merged firmware.bin the setup wizard flashes had the same defect as the PlatformIO build.

The change

One line at file scope in ESP32-CAM.ino, plus a comment explaining the budget:

SET_LOOP_TASK_STACK_SIZE(16384);

Verification (hardware, not just CI)

ESP32-CAM on COM5, module hive-01 / b0696ef23a08, built without DEV_SERVER_HOST so it targets production.

Before: stack canary panic on every boot, no exceptions, across many reboots.

After — same board, same config, whole path green against highfive.schutera.com:

[OTA] manifest HTTP 404                 <- #275, now survived instead of fatal
[STAGE] http_ota_check took=4279ms
[getGeolocation] success on attempt 1 (lat=48.200001 lng=11.770000 acc=19.1)
Response: {"id":"b0696ef23a08","message":"Module added successfully","name":"hive-01"}
[heartbeat] HTTP/1.1 200 OK
---- warm-up frame 1 OK (21244 bytes)
---- https://highfive.schutera.com/upload responded with status: 200
------ Success

Registration, heartbeat and first image upload all 200. The module is live on production now.

Also run: pio test -e native → 291/291 pass; pio run -e esp32cam links clean; scripts/check-doc-citations.sh → 7 OK, 0 problems.

The uncomfortable part

Every automated gate this repo runs on firmware was green while the firmware could not boot. pio test -e native has no Arduino runtime and no TLS; pio run -e esp32cam only proves it links. A green CI board on ESP32-CAM/ means "compiles and its pure helpers pass", never "boots". The only thing that closes that gap is a smoke-flash on real hardware before a SEQUENCE bump, and it is manual — now decided: it is a named step in the firmware release checklist (step 2, loopTask stack re-verify).

Second-order finding, in the docs and worth a reviewer's attention: during the crash loop the OTA boot gate counted pv=1/3 → 2/3 → 3/3 and tried to save the board — [OTA] rollback ... — reverting slot — and could not: esp_ota_ops: Rollback is not possible, do not have any suitable apps in slots. The ADR-008 / #148 rollback design assumes a good slot to revert to, which a fleet OTA has and a freshly wizard-flashed factory slot does not. The rollback net protects the fleet from a bad release; it does not protect the onboarding path, which is exactly where this defect lived.

Docs

Per CLAUDE.md's documentation gate:

• docs/11-risks-and-technical-debt/README.md — lessons learned: the stack was the one resource with no guard, no log line and no comment, while heap headroom and handshake timeouts (each of which had already caused an incident) were treated as first-class.
• docs/06-runtime-view/esp-reliability.md — new section 9, loopTask stack budget, framed as a budget the TLS call sites share rather than a constant.
• docs/troubleshooting.md — three entries: the crash-loop signature; the production variant of the wizard's "/firmware.bin not found" (setup wizard cannot flash on production: /firmware.bin, /firmware.app.bin and /firmware.json are all missing from the live host #275, where Firmware: Local is the tell and there is no operator fix from a laptop); and an obsolete PlatformIO core shadowing a good one (Unknown development platform 'espressif32'), which cost time in this session.

Not in scope

• This ships nothing to the field. Reaching the fleet needs a SEQUENCE-bumped release per firmware-release.md. Given firmware: setTimeout() unit bug (seconds on core 2.0.17), captive-portal loops without deadline/WDT feed, and a fixed OTA download deadline — one SEQUENCE-bumped release #231 is also waiting on a release, these are probably worth landing together as one OTA rather than two.
• setup wizard cannot flash on production: /firmware.bin, /firmware.app.bin and /firmware.json are all missing from the live host #275 (production serves no firmware artefacts) is untouched — it needs a release/ops change, not code.
• The senior-reviewer gate has been run (4 rounds, 2026-09-01): it surfaced a factual doc error (the loopTask TLS call-site count — geolocation is NVS-cache-gated, so setup() does TLS up to four times, not at least four), a PIO-troubleshooting section that had split its own tail, a false "the repo always writes python -m platformio" claim, and wording traps (fake-quoted log text, a dangling clause, dump-specific addr2line addresses). All findings are fixed on the rebased branch; doc-citation and firmware-build gates pass, and CI is green.

🤖 Generated with Claude Code