[mikestankavich]

The nine findings the remote-update review (#765) deferred, each fixed test-first. Daemon and guard changes reach readers as a remote update. The guard and install.sh changes reach a reader only through install.sh.

What changed

Daemon (mqtt-rpc/internal/update, readerd)

• Item 1. Preflight requires the guard timer to be enabled (timers.target.wants/mqtt-rpcd-guard.timer), not just installed. It makes no systemctl call.
• Item 2. versions/ is fsynced after the download is renamed in, before pending names the new binary.
• Item 5. CleanStale removes .mqtt-rpcd-*.download and .upload files left behind by a killed transfer. It runs at startup and before each download, and only touches files older than any live transfer could be (15 min).
• Item 7. A reply that loses the commit race to this process's own earlier commit gets ErrAlreadyCommitted, and answered() no longer logs that as a failure.
• Item 6. The download client trusts the system pool plus the Mozilla roots from golang.org/x/crypto/x509roots/fallback/bundle, so every update ships fresh roots. It adds to the system roots rather than replacing them: Ed25519 and sha256 decide what gets installed, and TLS only decides whether the download can happen. The broker's TLS is unchanged. That module requires Go 1.26, so mqtt-rpc's go line moves from 1.25.1 to 1.26.0. The backend is already on 1.26, and the release workflow reads go-version-file.

Guard (deploy/edge/mqtt-rpc/mqtt-rpcd-guard)

• Item 3. When the recorded from version is gone, the guard falls back to the newest other installed version, using legacy only as a last resort, and records rolled_back with reason <why>_fallback. If nothing else is installed, it records a new unguarded state instead of failed ("nothing replaced" was false: the target is live).

• Item 4. A new place <version> mode is install.sh's binary-and-link step, so the existing harness tests it against the real script:

  • it stops the guard timer first;
  • it removes rollback.claim, pending.commit and pending before the binary moves in;
  • it hardlinks a plain pre-versioning binary to versions/mqtt-rpcd-legacy and renames the symlink over it, so /opt/trakrf/mqtt-rpcd never goes missing;
  • it converges when re-run.

  install.sh calls it and restarts the timer on any exit, including an error or a dropped session. It is named place, not install, because TRA-1321 plans install <version|latest> for the full one-command install.

Backend and app

• Item 8. A refused update is now a 422 in the standard error envelope (validation_error, detail = the reader's reason). A request that was published but never answered is now 504 (readercontrol.ErrNoReply) instead of 502. A failed publish stays 502. On a 504 the panel watches the requested version instead of showing "Could not start".
• Item 9. "Timeout" now needs a check of the reader after the deadline. A successful fetch or an error both count. A background tab whose refetches paused no longer settles "timeout" without asking the reader.
• The panel shows unguarded as running but unconfirmed, never as "failed, nothing replaced".

Other commits: a pre-existing gofmt drift in servlet_test.go, and README updates for the guard fallback, the new state and the embedded roots.

Not done here: bench verification (acceptance item 10)

This was dispatched with no hardware, because an overnight soak was running. The ticket asks for items 4–6 on cs463-212 with a remote update from a CI release, so this PR refs the ticket rather than closing it.

Worth testing on hardware

• Go 1.26 daemon build. It cross-builds for linux/armv7 (10.6 MB, well under the 64 MB cap). It has not run on a CS463.
• Item 6. A remote update from a CI release succeeds on the reader with the new transport (same-origin GitHub download, redirect to objects.githubusercontent.com).
• Item 4.
  • install.sh onto a reader that is mid-probation for the same version: the binary survives and the timer comes back active.
  • An interrupted install.sh (kill the SSH session during the remote step), then a re-run.
  • A pre-versioning plain-file reader if one is still around: legacy should be the same inode.
• Item 5. Kill the daemon mid-download, then restart. The .download file is removed once it is older than 15 minutes.
• Item 1. systemctl disable mqtt-rpcd-guard.timer, then the update is refused with "not enabled".

Spun out

recover still trusts only the firmware CA bundle, so a stale bundle would also break on-site recovery. That fix needs the reader's curl/OpenSSL 1.0.2 to validate, so it is a comment on TRA-1321, which owns the recover/install redesign.

Validation

• just validate: exit 0. Frontend 2,665 passed / 0 failed; Go, mqtt-rpc (-race) and shellcheck green; lint rewrote nothing.
• csw-gates --worktree main: no gates fire (no migrations).
• readerconfig software integration tests (-tags=integration) pass against a throwaway TimescaleDB.

Refs TRA-1319

🤖 Generated with Claude Code

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://app.preview.trakrf.id