AGENT_UPDATE

Updates the agent binary itself. The agent downloads the new binary, verifies its SHA-256 (against a checksum file, or against a hash pinned inside the CA-signed action), runs a self-test, and swaps the binary in place. Failed self-tests keep the old binary running.

This is the only way the agent rolls itself forward in a fleet. There's no other path: distro packages aren't shipped, and SERVICE refuses to manage power-manage-agent.service.

Parameters

* At least one of amd64 or arm64 must be set. ** Per architecture, at least one of checksum_url or expected_sha256 must be set — the server rejects an action with neither, so an update can never run without an integrity check.

How it works

1. The agent reads its own architecture and picks the matching entry. If there's no entry for this arch, the action exits with changed=false and a noted skip.
2. It determines the expected hash: expected_sha256 if pinned in the signed action, otherwise it fetches the checksum file (sha256sums format) and takes the entry whose filename matches the binary URL. All URLs must be HTTPS.
3. It downloads the binary to a staging directory and verifies the SHA-256. A mismatch aborts before anything runs.
4. It runs the downloaded binary's version command and compares with the running version. Same version → changed=false, done. An older version is refused unless allow_downgrade is set on the action (anti-rollback); an unparseable version fails closed.
5. It runs the new binary in a subprocess as power-manage-agent self-test with a 60-second timeout. The self-test exercises the same wiring the new binary will need in production — see below.
6. If the self-test passes, the agent copies the current binary to <path>.bak (manual rollback: restore it and restart the service), atomically swaps in the new binary, and restarts itself.
7. If the self-test fails, the new binary is discarded and the old one keeps running.

What the self-test actually does

The subprocess walks four checks in order and exits non-zero on the first failure:

1. Credentials load. The new binary reads the agent's mTLS key + certificate from disk and parses them. Catches enrolment-state issues that would prevent the binary from connecting at all.
2. mTLS handshake. It dials the gateway URL the agent is currently using and completes a TLS handshake with https:// enforced (an http:// gateway URL is a hard failure here). Catches CA-trust drift, cert expiry, gateway address regressions.
3. Bidirectional stream. It opens the streaming RPC, sends Hello, and verifies it receives Welcome back. Catches proto mismatches between agent and gateway.
4. SyncActions round-trip. It calls SyncActions to confirm the new binary can fetch its assignment set. Catches RPC-surface regressions before the binary takes over.

Anything that fails surfaces as the test exit code; the running binary captures stdout/stderr from the subprocess into the execution event so you can see what failed. Side note: the self-test connects with the live agent's device identity, so the running agent briefly disconnects (a few seconds) while the probe holds the stream.

Idempotency

The agent compares the downloaded binary's reported version against its own running version. Equal means changed=false. A newer version triggers the self-test and swap.

Multiple AGENT_UPDATE actions in one reconciliation cycle deduplicate to one execution.

Example

type: AGENT_UPDATE
amd64:
  binary_url: https://updates.power-manage.example/agent/2026.06.0/power-manage-agent.amd64
  checksum_url: https://updates.power-manage.example/agent/2026.06.0/SHA256SUMS
arm64:
  binary_url: https://updates.power-manage.example/agent/2026.06.0/power-manage-agent.arm64
  checksum_url: https://updates.power-manage.example/agent/2026.06.0/SHA256SUMS

Gotchas

• A failing self-test fails the action: the execution reports FAILED with the self-test's output in the execution event, and the old binary keeps running. Fix the underlying issue and let the next run retry.
• No cooldown between retries. Retry frequency is governed entirely by the action's schedule — if the target version is broken and the action runs every 30 minutes, the agent re-downloads and re-tests it every 30 minutes until a fixed release is published or you cancel the assignment.
• The checksum file is the same for both architectures by convention; the agent searches it for the filename matching its binary URL.
• A successful self-update restarts the agent process. The current mTLS stream drops and reconnects on the new binary. Operators watching the device's "online" status will see a brief offline blip (the self-test itself also causes one).
• Maintenance windows do apply: a scheduled AGENT_UPDATE defers like any other due action while the window is closed. Only stream-dispatched instant actions (e.g. "reboot now") bypass the window.