feat(host): a recency hot set for every post-copy source from the kernel's idle-page bits (ADR 0045 C2)

[nikhilunni]

Summary

Gives every post-copy source a recency hot set so the destination drains the pages the guest will touch first (ADR 0045 C2). A live move of a File-mode fresh session shipped an empty hot rider (outcome="no_trace"), so the destination drained 8 GiB in manifest order while agentd faulted its working set on demand. The hot-first drain existed; it had nothing to order by for a source without a UFFD handler.

The change

• Mark at presetup, read after the blackout. Presetup marks the guest's present, exclusive, anonymous pages idle through /sys/kernel/mm/page_idle/bitmap (compound pages by head, resolved from /proc/kpageflags with a linear extent cache). The capture keeps today's dirty scan only. PFN collection and the idle read run after the export is registered, while the source stays paused, so the blackout is unchanged.
• Ordering. Accessed pages aggregate per chunk, ordered by count then offset, mapped to chain-manifest hashes, capped at 4096 for the idle tier. The handler-trace tier stays whole and goes first.
• Delivery. The hint is its own optional export artifact (MigrationItem::HotHint, proto 6, bincode 3) fetched only after state.bin lands, with backoff, never touching the export lease, and stopped by the locally observed drain outcome. The destination drain starts at once in manifest order and reorders the remaining chunks when the hint arrives.
• Invariant, stated in the module docs: a hint is advisory and no hint path can fail, delay or block a move, a resume, a drain or the blackout. Every delivery, parse and timeout failure is "no hint".
• HostCapabilities.page_idle is an informational probe (ADR 0068); it never gates placement. Wire version 37.

Tests

PFN word/bit math; shared-page exclusion; aggregation and ordering; hash mapping and caps; compound-extent operation count; trace-first priority; a Linux root test marks and reads a private mapping; a fake-inner test drives the real capture and the real destination poller with hints absent, empty, delayed, malformed and failed, asserting state.bin lands each time; the two-host KVM test asserts move success and hint arrival; the drain reorder is proven deterministically on a fake peer, including hints naming only installed or unsealed chunks.

Validation

just check green (2776 tests); Linux cross clippy for host-agent, uffd-handler, core, protocol and firecracker clean; five Codex adversarial review rounds, final verdict approve on the code and the last test-determinism finding fixed.

Note

🤖 Generated with Claude Code

https://claude.ai/code/session_01UHxL6gj4o8EvxYpgtwEWaM

[github-actions]

The latest Buf updates on your PR. Results from workflow CI / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	⏩ skipped	✅ passed	Oct 8, 2026, 3:18 AM