perf(daemon): session-trusted verify-skip for ESP32 warm redeploys

[zackees]

Summary

Implements the session-trusted verify-skip optimization flagged in #114 / LOOP.md: when the daemon has just deployed a known image to a port and the port has stayed continuously enumerated since then, no external agent could have re-flashed the chip without breaking our serial enumeration. The next deploy of the same image can therefore return VerifySkip immediately — skipping the full verify-flash path (serial open + espflash connect + stub upload + 3× FLASH_MD5SUM), which measured ~1.5 s on the native path in #66.

Implements the design the user called out:

if we have exclusive control over a port, then we can guarantee it has the same firmware, otherwise someone else would have broken the exclusive serial connect that we have

What's in the PR

1. TrustedFirmwareHash on DeviceState (crates/fbuild-daemon/src/device_manager.rs) — SHA-256 + set_at Instant, stored in the existing in-memory map. Invalidated by last_disconnect_at stamped on the true → false enumeration edge in refresh_devices.
2. DeviceManager::{trusted_firmware_hash, set_trusted_firmware_hash, clear_trusted_firmware_hash} API methods.
3. compute_esp32_image_hash in handlers::operations — deterministic SHA-256 over (offset_le, len_le, bytes) for bootloader + partitions + firmware, so identical builds hash to identical values.
4. Deploy-handler wiring — check the hash before the existing try_verify_deployment call; short-circuit with VerifySkip on match; refresh enumeration once per deploy so the last_disconnect_at invalidation is sound; record/invalidate the hash after the deploy returns.
5. Skip the post-deploy USB re-enum poll on VerifySkip outcome — on the trust-skip path the port was never closed, so the 3 s poll loop (which collides with an attached monitor) is pure overhead. Load-bearing for the < 4 s warm-trust-skip budget.
6. FBUILD_SELF_EVICTION_SECS env override on SELF_EVICTION_TIMEOUT — lets the warm-deploy benchmark keep one daemon alive across T1→T2→T3 without the 30 s idle timer racing against spawn latency.

Opt-in

Gated by FBUILD_TRUST_DEVICE_HASH=1, mirroring the opt-in convention from #66's FBUILD_USE_ESPFLASH_{VERIFY,WRITE}. Default off until benched on every ESP32 family member.

Tests

• 5 new device_manager unit tests: round-trip, clear, unknown-port, invalidation after disconnect, survival across older disconnect stamp.
• All 116 fbuild-daemon lib tests pass.
• uv run cargo clippy -p fbuild-daemon --all-targets -- -D warnings clean.

Benchmarking

Hardware bench on the real ESP32-S3 on COM13 was attempted but blocked by a pre-existing ESP32 cold-build stall (orchestrator hangs mid-Arduino-framework-library compile with no active compiler processes, stays "operation in progress" for 15+ minutes). That stall is orthogonal to this PR's code path and will be investigated separately.

Verified warm-case fast paths that don't depend on ESP32:

• tests/platform/uno cold build: 4.3 s (healthy)
• tests/platform/uno warm rebuild: 211 ms (fingerprint hit, well inside the 500 ms LOOP.md budget)

Theoretical warm-deploy savings under the new path, once end-to-end bench returns clean:

• Today (native verify-skip): ~1.5 s verify + ~100-3000 ms USB wait ≈ 2-5 s
• With trust-skip: SHA-256 compute (~10 ms for 2.4 MB) + DashMap lookup + early return ≈ < 50 ms server side; monitor reattach adds ~100-300 ms
• Budget room recovered: 1-4 s, comfortably inside the 4 s total target

Test plan

• Apply FBUILD_TRUST_DEVICE_HASH=1 on a daemon + real ESP32 board, run back-to-back deploys of the same image, confirm the second deploy emits "trusted-hash: session-trusted match" instead of the verify-flash line.
• Unplug/replug the board between deploys — confirm the next deploy falls back to the full verify-flash path (trust invalidated by disconnect edge).
• Modify the sketch slightly — confirm the hash mismatch causes a full flash and the trust entry updates to the new hash.

Related: #66 (native espflash migration), #91 (warm-build instrumentation), #114 (warm-deploy loop tracker).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added deployment optimization for Espressif32 devices using cached device verification to reduce deployment time and eliminate redundant checks.

• Configuration

  • New environment variable FBUILD_TRUST_DEVICE_HASH enables hardware-backed verification optimization (disabled by default for safety).
  • New environment variable FBUILD_SELF_EVICTION_SECS configures the daemon's idle timeout duration in seconds (defaults to 30 seconds).

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ec5ebba6-5bbd-4545-a09d-3255336dd47d

📥 Commits

Reviewing files that changed from the base of the PR and between dcda295 and 12083d2.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (5)

• crates/fbuild-daemon/Cargo.toml
• crates/fbuild-daemon/src/context.rs
• crates/fbuild-daemon/src/device_manager.rs
• crates/fbuild-daemon/src/handlers/operations.rs
• crates/fbuild-daemon/src/main.rs

---

📝 Walkthrough

Walkthrough

This PR introduces a session-trusted firmware verification feature for ESP32 devices. It adds SHA-256 hashing of firmware images, device connection state tracking, and a fast-path deployment that skips serial verification when cached hashes match. The daemon's self-eviction timeout is now configurable via environment variable.

Changes

Cohort / File(s)	Summary
Configuration & Runtime Settings crates/fbuild-daemon/Cargo.toml, crates/fbuild-daemon/src/context.rs, crates/fbuild-daemon/src/main.rs	Added sha2 dependency; replaced fixed SELF_EVICTION_TIMEOUT constant with runtime-configurable self_eviction_timeout() function reading FBUILD_SELF_EVICTION_SECS env var; updated main.rs to use the new function for daemon idle timeout logic.
Device State & Trust Management crates/fbuild-daemon/src/device_manager.rs	Added TrustedFirmwareHash struct and extended DeviceState with trusted_firmware and last_disconnect_at fields. Implemented cache tracking of device disconnections and three public APIs: trusted_firmware_hash(), set_trusted_firmware_hash(), and clear_trusted_firmware_hash() to manage session-trusted firmware verification. Added unit tests for trust round-trip, invalidation, and edge cases.
Deployment Fast-Path & Hash Verification crates/fbuild-daemon/src/handlers/operations.rs	Added trust_device_hash_enabled() and compute_esp32_image_hash() functions. Implemented a fast-path in deploy() for Espressif32 targets that computes firmware image hash and returns DeployOutcome::VerifySkip if the hash matches the cached trusted hash, skipping serial verify-flash. Added cache recording/invalidation on deploy success/failure and device enumeration refresh when trust-hash mode is enabled. Updated post-deploy USB polling to skip serial probe when result is VerifySkip.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Handler
    participant DeviceManager
    participant Deployer
    participant SerialPort

    Client->>Handler: deploy(esp32, port)
    Handler->>DeviceManager: refresh_devices()
    DeviceManager-->>Handler: device state updated
    
    Handler->>Handler: compute_esp32_image_hash()
    Handler->>DeviceManager: trusted_firmware_hash(port)
    DeviceManager-->>Handler: cached hash (if available)
    
    alt Hash Matches (Fast-Path)
        Handler-->>Client: DeploymentResult(VerifySkip)
    else Hash Mismatch or No Cache
        Handler->>Deployer: deploy_regions(...)
        Deployer->>SerialPort: write firmware
        SerialPort-->>Deployer: verify-flash/MD5
        Deployer-->>Handler: success/failure
        
        alt Deploy Success
            Handler->>DeviceManager: set_trusted_firmware_hash(port, hash)
        else Deploy Failure
            Handler->>DeviceManager: clear_trusted_firmware_hash(port)
        end
        
        Handler-->>Client: DeploymentResult(normal outcome)
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• fix(deploy): preserve deploy outcome in response message #80: Adds the DeployOutcome enum and threads it into DeploymentResult and handler messages; this PR implements the DeployOutcome::VerifySkip variant and integrates it into the deployment fast-path logic, directly building on that infrastructure.

Poem

🐰 Hop hop, the hashes now align!
No more serial waits—just cryptographic signs.
Trust the cache, skip the slow dance,
Deploy at lightning speed, give devices a chance! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/session-trusted-verify-skip

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}