fix: verify flash writes, gate setup on firmware, sticky guidance cards

[joshuagruenstein]

The bug

A newly flashed ting: dictation worked over 3.5mm, green/orange never did. Over USB everything worked.

Diagnosed by recording the raw line-in with ffmpeg and running the production decoder offline over the capture (new --decode-wav flag), with serial events as ground truth. A 5ms frequency-ridge analysis showed the device acoustically playing more symbols than the payload ever queues — a "beacon" with five S0 chirps, a phantom modeChanged(4) that was really (2,3,1,3) on the wire.

Root cause: firmware below 1.0.8 plays the current slot sample on squeeze and on button presses (the ting is an instrument, and our payload chains the stock callback for its bookkeeping). The slots hold chirp symbols, so stock playback sprays extra symbols into the middle of every queued event word. Beacons are 4 identical symbols and survive on FEC; diverse event words die. Serial is unaffected — hence USB looking healthy. Confirmed by A/B: after the firmware upgrade, all three event types decode.

Fixes

Firmware is part of setup. Flash EP on a ting tingle hasn't seen at 1.0.8 routes into the guided upgrade flow (which reinstalls the payload at the end). Firmware state is tracked per device serial — the global flag had marked this brand-new unit "already 1.0.8" because a different ting had been upgraded, which is exactly why the trap was invisible.

Verified flashing. Every write is read back and checksummed before the eject, plus a sync. A truncated/failed/reverted flash now fails loudly ("Flash verification failed — …") instead of reporting success and leaving a dead device. This also would have caught the earlier incident in this same session, where a stale 4096-byte payload sat on the device while Flash EP claimed success.

Dry-bus config.json now ships with every flash (SAMPLE-only presets).

Guidance UX. NSPanel hides itself on app deactivate, so the firmware ritual card disappeared the instant focus moved — user left squeezing the handle with no instructions. Cards are now .statusBar level, hidesOnDeactivate = false, all-Spaces. Added a one-flow-at-a-time guard (a re-click raced two flows into simultaneous "failed" and "succeeded" popups) and fixed the copy: the button needs a true rapid double-click, not two deliberate presses.

Testing

• 358 assertions (new FlasherTests: verification mismatch cases incl. the exact truncation signature, dry-preset invariants, per-serial firmware bookkeeping) + payload tests green.
• Live-verified on hardware: full firmware flow, post-upgrade acoustic A/B, and a focus-stealing flash to confirm cards stick.

Deferred

Payload inter-word pacing — rapid back-to-back presses still clip chirp edges at word boundaries even on 1.0.8 (isolated presses are clean). Real, but wants its own PR tested on both devices.

🤖 Generated with Claude Code