feat(ota): atomic update + filesystem version self-heal (kill the split-update footgun)

[bring42]

The footgun

Update firmware first, and the device's running version now matches the manifest → isNewer(manifest, FIRMWARE_VERSION) goes false → fsAvailable (which was gated on it) goes false too → "Up to date," web UI stranded at the old version with no way to pull it. Hit in real use after the v1.2.0 update.

Root cause: the device only knew its firmware version, never its filesystem version.

Fix — atomic + self-heal (chosen scope)

Self-heal (know the FS version):

• scripts/version.py stamps the LittleFS image with its version at build → data/fsver (gitignored; packed into littlefs.bin).
• The updater reads /fsver and computes appBehind / fsBehind independently; availability is appBehind || fsBehind.
• A legacy image with no stamp reads as behind, so any device that only got a firmware update re-detects its stale UI on the next check and offers the update automatically — no manual flash. (This is what rescues the currently-stuck device once it's on this firmware.)

Atomic apply (can't half-update):

• New requestUpdate() / POST /api/firmware/update flashes whatever's behind — filesystem first, then firmware — and reboots once. The two images move together and can never drift again.
• Console UI collapses the two buttons into a single "Install Update."
• Per-image requestAppUpdate/requestFsUpdate + /update/app,/update/fs remain for recovery/debug (now safe, since drift self-heals).

Verification

• pio run -e seeed_xiao_esp32c3 compiles (90.2% flash).
• 65 native tests pass.
• data/fsver stamp confirmed written + gitignored + not tracked.

Notes / follow-ups

• Can't hardware-test flashing from here — the download/verify/flash path is unchanged from the working per-image code; only sequencing + availability changed.
• Euclid skin still uses the per-image endpoints (unchanged, still functional). Collapsing it can wait on the parked "euclid keep/cut/finish" decision.
• The interrupted-update case (power loss mid-flash) is now also covered by self-heal.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes the OTA “split-update” failure mode by teaching the device to track the LittleFS (web UI) version independently from the firmware version, and by adding a single atomic update path that updates whichever image(s) are behind with one reboot.

Changes:

• Stamp LittleFS builds with a filesystem version (/fsver) and report it via /api/firmware/status, so update availability is computed independently for firmware vs filesystem.
• Add an atomic POST /api/firmware/update apply path (fs-first, then firmware; one reboot) and wire the console UI to a single “Install Update” action.
• Keep the per-image update endpoints for recovery/debug, while shifting the primary UI flow to the atomic endpoint.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
ui-concepts/console-euclid-live/index.html	Collapses OTA actions to a single “Install Update” button.
ui-concepts/console-euclid-live/app.js	Updates console OTA flow to use updateAvailable + a single atomic apply action.
ui-concepts/_engine/engine.js	Adds applyUpdate() calling the new atomic /api/firmware/update endpoint.
src/network/updater.h	Extends UpdateStatus with fsVersion and documents atomic update API.
src/network/updater.cpp	Reads /fsver, computes appBehind/fsBehind, implements atomic apply (fs→app, one reboot).
src/network/server.cpp	Registers the new /api/firmware/update endpoint (atomic path).
src/api/firmware.h	Documents the new atomic update endpoint and clarifies per-image endpoints as recovery.
src/api/firmware.cpp	Serializes fsVersion and adds handler for POST /api/firmware/update.
scripts/version.py	Writes data/fsver during device builds to stamp the LittleFS image version.
.gitignore	Ignores the generated data/fsver artifact.

Comments suppressed due to low confidence (2)

src/network/updater.cpp:474

• doApplyFs() currently gates on g_target.available (appBehind || fsBehind). If only the firmware is behind, this condition still passes and the function will flash the filesystem even though it’s already up to date. Gate on fsBehind (and hasFs) to keep the per-image recovery path correct under the new split-version logic.

    ESP.restart();
}

src/network/updater.cpp:571

• requestAppUpdate()/requestFsUpdate() still gate on g_target.available, which is now (appBehind || fsBehind). That means the per-image endpoints can return true even when the requested image is already current (e.g., fsBehind=true allows requestAppUpdate). Gate each function on its specific behind-flag to preserve the documented API contract and avoid unnecessary flashing.

bool requestAppUpdate() {
    if (!g_cmdQueue) return false;
    if (!g_target.available) return false;