Repository navigation
perf: warm-deploy agent loop — drive < 4 s rebuild+verify+reconnect budget #114
Description
Goal
Warm rebuild + deploy + monitor reconnect on ESP32-S3 should complete end-to-end in under 4 000 ms when:
- No source / config / toolchain changes since the last build.
- The device already holds the exact firmware image (verify-flash MD5 match).
- The serial monitor is expected to reattach and receive the first JSON-RPC byte.
"Auto-research" is the SerialMonitor.auto_reconnect behaviour — the monitor reattaching after a deploy preempts the serial session.
Budget tree (total: 4 000 ms)
| Phase | Budget |
|---|---|
| CLI → daemon handshake | 200 ms |
| Daemon lock + dispatch | 100 ms |
| Warm-build fingerprint hit (no compile, no link) | 500 ms |
| Verify-flash MD5 match (3 regions) | 1 500 ms |
| Serial port re-open + WebSocket reattach | 700 ms |
| TTFB (first JSON-RPC byte from device) | 1 000 ms |
| Slack | 0 ms |
Agent loop
The full spec — test matrix, per-iteration procedure, decision rules, outputs — lives at LOOP.md in the repo root (landed in #113 / `cacba6f`). It is invokable with the `/loop` skill:
```
/loop @./LOOP.md
```
Every iteration appends a row to `tasks/loop-runs/RESULTS.csv` and the agent judges each capture against the budget tree. On three consecutive green T1–T3 iterations, the loop writes `tasks/loop-runs/SUMMARY.md` and terminates; on five attempts without improvement, it files a follow-up issue and stops.
Known suspects (from existing investigation)
From docs/PERF_WARM_BUILD.md (issue #91):
- First warm build after a daemon restart spends ~68 s in the ESP32 orchestrator even with the fingerprint populated.
- Second warm build still takes ~1.3 s because `fp-watches-collect` walks thousands of files and zccache re-verifies.
- Fix direction: split the fast-path fingerprint into in-memory + on-disk layers.
From #66:
- Verify-flash with `FBUILD_USE_ESPFLASH_VERIFY=1` is ~6 s → targeting ~1.5 s; native `write-flash` is independent via `FBUILD_USE_ESPFLASH_WRITE=1`.
- `/ws/logs` now surfaces per-region progress (perf(daemon): bridge tracing events to /ws/logs (partial #66) #111 / `e7aad0e`).
Deliverables
- `LOOP.md` committed (docs(perf): LOOP.md — warm-deploy agent loop spec #113)
- First pass of the loop against real ESP32-S3 hardware to confirm or tune budgets
- Follow-up issues for any phase that consistently breaches its budget
- Close when T1–T3 land inside the total budget for three consecutive iterations
Related: #91 (warm-build investigation), #66 (espflash migration).
Activity
chore: untrack LOOP.md and add to .gitignore
chore: untrack LOOP.md and add to .gitignore (#115)
zackees commentedon Apr 18, 2026
Phase (b) landed in #116 (
8858dda). The session-trusted verify-skip is now opt-in viaFBUILD_TRUST_DEVICE_HASH=1.Status of the 4 s budget tree:
tests/platform/uno— the fingerprint fast-path is already well inside the 500 ms budget slot.FBUILD_TRUST_DEVICE_HASH=1, the server-side cost drops from ~1.5 s (espflash MD5 round-trip) to ~50 ms (SHA-256 compute + cache lookup + early return). Plus the USB re-enum poll is now skipped onVerifySkipoutcome, recovering another 100–3000 ms on the warm path.COM13) was attempted but blocked — the ESP32 cold bring-up stalls mid-Arduino-framework-library compile with no active compiler processes, stayingoperation in progressfor 15+ minutes. Unrelated to this work; filing a follow-up issue for the orchestrator stall.Remaining on this tracker:
perf(daemon): sub-1s warm deploy — image-hash memo + refresh-skip window
perf(daemon): sub-1s warm deploy — image-hash memo + refresh-skip win…
zackees commentedon Apr 18, 2026
Sub-1 s best-case follow-up landed in #118 (
c01ad5d). Two micro-optimizations on top of the trust-skip:ImageHashMemoonDaemonContext— keys on(firmware_path, bootloader_mtime, partitions_mtime, firmware_mtime)so warm redeploys skip the 2–4 MB disk read + SHA-256 (~5–15 ms saved).DeviceManager::refresh_devices_if_stale(2s)— avoids the 20–30 ms Windows port enumeration on back-to-back deploys.Net server-side cost on a warm trust-skip deploy: ~50 ms → ~1–2 ms. Remaining non-trivial slice in the 1 s budget is the warm-build fingerprint (~100–300 ms) — tracked against #91. Once that lands, the full warm
fbuild deploy --monitorpath should hit sub-1 s in the cached-device / persistent-monitor best case.perf(build): in-memory watch-set fingerprint cache on the daemon
perf(build): in-memory watch-set fingerprint cache on the daemon (#120)
zackees commentedon Apr 18, 2026
Warm-build fingerprint cache landed in #120 (
1316fe0).Budget breakdown now:
fp-watches-collectno longer pays the walk on back-to-back builds — daemon-scopedDaemonWatchSetCache(DashMap + 2 s freshness window) returns the previous hash in microseconds.Follow-ups filed from the #120 self-review:
FBUILD_WATCH_SET_CACHE_SECSenv override (window is a hardcoded 2 s today)tracing::debug!+/api/daemon/infocountersRemaining on this tracker:
zackees commentedon May 10, 2026
First-pass loop result on real hardware (ESP32-S3-DevKitC-1, native USB-CDC, Windows 10, fbuild release build from
feat/114-warm-deploy-loop-first-pass):5/5 inside 4 s; mean 3.613 s, max 3.697 s, lowest margin 303 ms. Deploy-only (no monitor) is ~2.6 s steady-state. The ~1 s extra is the test sketch's
delay(500)×2loop period (nextSerial.printlncadence), not deploy/reconnect cost.All sub-budgets cleared without any phase consistently over, so no follow-up perf issues filed. Loop spec (
LOOP.md) retired — it was already.gitignore'd after #115; local copy removed.Acceptance criteria from the OP:
Closing notes + table land in
docs/PERF_WARM_DEPLOY.mdvia #230.docs(perf): #114 warm-deploy loop first-pass results (#230)
zackees commentedon May 11, 2026
All acceptance criteria met — closing.
Results captured in
docs/PERF_WARM_DEPLOY.mdvia #230 (merged).