Sync guest wall clock from KVM PTP after standby restore

[sjmiller609]

Summary

The guest wall clock lags after a standby restore: CLOCK_REALTIME resumes from the snapshot's saved time and nothing corrects it. The guest runs no NTP daemon, and VMGenID's only guest-side effect is an RNG reseed (add_vmfork_randomness) — it never touches the clock. Verified on a live instance: guest was ~5–6 minutes behind after standby cycles, while /dev/ptp0 (KVM virtual PTP, CONFIG_PTP_1588_CLOCK_KVM=y in the current guest kernel) returned correct host time the whole while.

This adds a clock keeper to guest-agent that consumes that already-present time source:

• reads host time via clock_gettime on /dev/ptp0 (FD_TO_CLOCKID) and steps CLOCK_REALTIME when drift exceeds 1s
• checks every 30s, plus immediately when the vmgenid kmsg line (crng reseeded due to virtual machine fork) signals a restore, so correction is near-instant on resume
• no-ops with a log line if /dev/ptp0 is absent

No host-side changes, no RPC/proto changes, no kernel or hypervisor version bump. Works with the kernels and VMMs already deployed.

Alternative considered: VMClock kernel backport

A VMClock-based path exists (ch-6.16.9-kernel-0.1-202605301 carries the backported generation-counter/notification driver, previously wired up in #254) but was deliberately not taken: even with VMClock the kernel never sets CLOCK_REALTIME itself, so a userspace clock-setter is needed either way. That path would additionally require jumping guests from 6.12.8 to 6.16.9 and bumping Firecracker to v1.15.1 for the notification support — a much larger blast radius for the same end result. VMClock remains a clean future upgrade for the trigger (device notification instead of the kmsg line), without changing this keeper's structure.

Test plan

• go build (linux + darwin), go vet, guest_agent unit tests pass locally
• TestStandbyAndRestore extended minimally: the guest clock is skewed back an hour before standby, and after restore the test asserts it converges to within 5s of host time. Deterministic and adds no test wall time; fails without the keeper (guest would stay an hour behind)
• The extended integration test was NOT run locally (local KVM test environment issues) — needs a CI run or a machine with working /dev/kvm nested virt

🤖 Generated with Claude Code

---

Note

Medium Risk
Guest-side clock_settime on every restore and periodic drift checks could affect time-sensitive workloads; scope is limited to Linux guests with /dev/ptp0 and no host API changes.

Overview
Adds a guest-agent clock keeper (Linux only) so CLOCK_REALTIME realigns with the host after standby restore, when the guest resumes from snapshot time with no NTP.

The keeper reads time from /dev/ptp0 via clock_gettime, steps the wall clock when drift exceeds 1s, runs a 30s periodic check, and triggers an immediate sync when /dev/kmsg shows the vmgenid fork line (crng reseeded due to virtual machine fork). It starts after guest-agent readiness; non-Linux builds no-op. No host, RPC, or kernel changes.

TestStandbyAndRestore skews the guest clock back one hour before standby and asserts it converges to within ±5s of host time after restore, so the test fails without the keeper.

^{Reviewed by Cursor Bugbot for commit 210cf46. Bugbot is set up for automated code reviews on this repo. Configure here.}