Host RAM ledger: charge base-shm, parked residents, and running VMs under one allocatable_mib budget

[nikhilunni]

Closes #540

Summary

One host-side RAM ledger (engram-host-agent::ram_ledger) replacing the
three unreconciled views of host RAM: kernel MemAvailable, the
UtilizationProbe formula (silently assumed resident ⇔ reserved), and the
idle-evictor's own private /proc/meminfo read. Every heartbeat tick now
builds one RamLedgerSnapshot, charges every MiB to a named bucket
(running-VM PSS, parked-paused PSS, base-shm tmpfs residency + pending
prewarm charges), and derives allocatable_mib from it once — the
heartbeat and the pressure gate both read the same snapshot (via a
tokio::sync::watch channel), so they can never disagree.

Verified against commit f660225 (issue-authoring time); worktree HEAD
was 42ed9bb — every file:line anchor cited in the issue was re-checked
against HEAD before implementation; all held (line numbers drifted by only
a few lines in places, noted below, no anchor was wrong).

What changed

• New crates/engram-host-agent/src/ram_ledger.rs: RamLedgerSnapshot
  (allocatable_mib(), free_pct()) + RamLedger (the pending-base-shm-
  charge registry). allocatable = MemAvailable + Σ non-parked VM PSS − pending base-shm charges. Parked PSS is never added back — the fix
  for the double-count the parking ladder would otherwise introduce.
• engram-core::traits::sandbox::GuestMemoryStats gains
  parked_pss_bytes / parked_rss_bytes / parked_sampled; the
  Firecracker backend's guest_memory_stats() buckets its smaps_rollup sum
  by a new per-sandbox parked: bool flag on LiveSandbox (always false
  today — no backend transition sets it yet). No SandboxBackend trait
  method added for park/unpark, per the issue's explicit guardrail — only
  a pub(crate), test-visible setter on the FC backend.
• UtilizationProbe::sample no longer computes allocatable_mib
  itself; it projects the heartbeat tick's RamLedgerSnapshot into
  HostUtilization's memory fields. The stale "mlock'd base-memfile
  residency" formula comment is deleted (that machinery is generation-
  purge's, Generation purge: delete the dead memory-path, migration, and compat-stub generations #530, to actually delete).
• Idle-evictor pressure gate reads the same per-tick snapshot instead of
  its own private /proc/meminfo sample. mem_pressure_check deleted (the
  pure mem_pressure_from core is unchanged, tests re-pointed at snapshot
  math — no change needed, they already only exercised the pure core).
  HOST_MEM_FREE_PCT moved to the heartbeat's single emission site (was
  previously only set inside the pressure-aware branch).
• Base-shm prewarm charging (image_prefetch.rs): registers the
  manifest's non-hole byte total + target path in the ledger before
  prewarm_base_shm writes, settles in both the success and failure arms.
  RamLedger::sample nets each pending charge against that specific file's
  own st_blocks (not just the raw promised total), so the charge shrinks
  as bytes actually land instead of double-subtracting the written
  fraction for the whole write window (see Post-review fixups below).
  Added a tmpfs-headroom pre-check (the 2026-06-28
  pwrite ... No space left on device incident class) that skips the
  write with a counter
  (engram_base_shm_prewarm_skipped_total{reason="tmpfs_headroom"}) —
  the existing warn-and-continue-then-lazy-backstop failure posture for the
  write itself is untouched.
• Wire + PG (migration 0078_host_ram_ledger.sql — renumbered from
  0077 post-review to resolve a 6-way collision with sibling in-flight PRs
  in the same land-queue batch): HostUtilization gains base_shm_mib,
  base_shm_pending_mib, parked_pss_mib, running_pss_mib (all
  #[serde(default)]). Only the first, third, and fourth persist to PG
  (base_shm_pending_mib is transient host-local state already folded into
  the persisted allocatable_mib — deliberately not its own column, noted
  in the migration). Surfaced on the fleet view: api/hosts.rs HostView,
  fleet.proto HostView (+3 fields), grpc_app/convert.rs's totality-
  guard destructure, and the web Fleet page (a small ram: X GiB running · Y GiB parked · Z GiB base-shm readout, hidden until non-zero).
  engram-host-operator's HostLoad conversion is a partial (non-
  exhaustive) destructure and needed no change — verified.
• Gauges: engram_host_ram_ledger_mib{category=...},
  engram_host_ram_allocatable_mib,
  engram_host_base_shm_tmpfs_{total,used}_mib (now gated on
  measured, and _used_mib is a real statfs read, not a duplicate of
  the base_shm category gauge — see Post-review fixups),
  engram_base_shm_prewarm_skipped_total,
  engram_sandbox_guest_parked_{pss,rss}_bytes.
• ADR 0046 gets a dated addendum (not a rewrite) explaining the amended
  formula, the resident⇔reserved invariant, and the no-sharing-discount
  stance (backed by the 2026-07-01 prod rss≈pss datum).

Post-review fixups (2026-07-03)

A deep-review pass (review)
found one real accounting bug and two acceptance-criteria boxes that were
checked but not actually true. All six findings were addressed on this
branch:

1. Migration collision. Five sibling open PRs in the same land-queue
   batch also claimed migration number 0077. Renumbered this PR's migration
   to 0078 per the batch owner's collision resolution (0077 stays with
   Generation purge: delete the dead memory-path, migration, and compat-stub generations #560).
2. Transient double-charge. register_pending_base_shm charged the
   full registered prewarm total for the entire multi-minute write window
   while MemAvailable was already dropping as pwrites landed — a ~19 GiB
   prewarm at 90% written was under-reporting allocatable_mib by ~17 GiB.
   Fixed: the pending charge is now netted against the target file's own
   st_blocks on every sample, so it shrinks in step with the actual
   write. New regression test:
   pending_charge_nets_against_bytes_already_written.
3. Gauges emitted unconditionally. The whole ledger gauge family was
   set every tick regardless of ram_snapshot.measured, contradicting the
   checked "gauges not emitted" acceptance box for VZ/Process/non-Linux
   hosts. Now gated on measured.
4. Missing watch-channel unit test. The "one source of truth"
   acceptance box was checked citing construction + grep, but no test
   actually exercised the watch-channel mechanism. Added
   ram_ledger_snapshot_round_trips_through_watch_channel.
5. HOST_BASE_SHM_TMPFS_USED_MIB was a duplicate. It read the same
   st_blocks-over-known-files walk as the base_shm category gauge,
   instead of the tmpfs mount's actual statfs usage — invisible to an
   unlinked-but-open file or stray subdir, exactly the case this gauge
   exists to catch during an ENOSPC-class incident. Now a real
   f_blocks − f_bfree statfs read.
6. parked_rss_bytes discarded. read_smaps_rollup_pss_rss measures
   both PSS and RSS for a parked sandbox, but only PSS was kept — the
   Σpss/Σrss sharing-density signal (ADR 0046's own rule) could never be
   evaluated for parked residents once the parking ladder lands. The
   issue's own spec omitted this field, but it was cheap to add now
   (mirrors the existing non-parked pair) rather than re-touching this
   struct, the FC split, and the read loop later. Added, populated, and
   exposed via new gauge-only metrics.

Acceptance criteria

• Parked exclusion — unit test parked_pss_is_never_added_back
  (ram_ledger.rs) + coordinator placement fixture
  parked_resident_on_one_host_never_gets_placed_on (two-host,
  12 GiB parked on one, a 24 GiB session lands on the other).
• Prewarm charging — unit tests
  ledger_pending_charge_registers_and_settles +
  pending_base_shm_charge_lowers_allocatable +
  pending_charge_nets_against_bytes_already_written (added post-
  review — proves the charge nets against bytes actually written,
  closing the transient double-charge bug); live end-to-end (real
  prewarm write) is out of scope for a unit test (needs a real tmpfs +
  chunk store), covered by the pending-registry contract instead.
• Attribution visible — new gauges emitted every tick once the
  host has measured at least once (gated on measured post-review;
  see finding 3 above); fleet view renders the new columns
  (web/src/pages/Fleet.tsx).
• One source of truth — heartbeat and pressure gate both read the
  same RamLedgerSnapshot via the watch channel; grep confirms no
  /proc/meminfo read outside ram_ledger.rs (the pre-existing
  one-time resource.rs::read_total_memory_mib startup capacity seed
  is a distinct, unrelated figure — HostCapacityReport.total_mib,
  not allocatable_mib/pressure — left untouched, out of scope).
  Now backed by an actual unit test,
  ram_ledger_snapshot_round_trips_through_watch_channel (added
  post-review — publishes a snapshot on a tokio::sync::watch channel
  and asserts two independent readers observe byte-identical values),
  not just construction + grep.
• No sharing assumed — grep confirms no discount multiplication;
  Σpss/Σrss gauges are unchanged as the only sharing signal. Parked
  residents' Σpss/Σrss is now actually observable too
  (parked_rss_bytes, added post-review — see finding 6 above).
• No behavior regression — with zero parked sandboxes and no
  in-flight prewarm, allocatable_mib is the same formula, just
  re-derived through the ledger; placement_reservation_live_pg /
  queue_scanner_live_pg / admin_evac_live_pg all green against
  real Postgres (ran locally, just db-up).
• VZ/Process/non-Linux — measured=false, allocatable_mib=0,
  gauges genuinely not emitted (fixed post-review — the ledger gauge
  block is now gated on ram_snapshot.measured; previously this box
  was checked but the gauges were in fact emitted as a permanent-zero
  series on every tick regardless of platform), matches the existing
  unmeasured-host posture; cross-compiled clean (nix develop -c cargo clippy --target aarch64-unknown-linux-musl -p engram-sandbox-firecracker -p engram-host-agent --all-targets, zero
  warnings) since the smaps/statfs walks and the parked field are
  cfg(target_os = "linux")-gated (macOS clippy can't see them, per
  repo convention).

Deviations / notes

• base_shm_pending_mib has no PG column. The issue's PG section lists
  exactly 3 new columns (util_base_shm_mib, util_parked_pss_mib,
  util_running_pss_mib) even though the wire section lists 4 new
  HostUtilization fields. This is intentional, not a miss: the pending
  charge is transient host-local state, already folded into the persisted
  allocatable_mib, and visible directly via the host's own /metrics —
  documented in the migration and in row.rs.
• File:line anchors drifted slightly (a few lines each, HEAD moved from
  f660225 to 42ed9bb) but every claim held; no anchor was substantively
  wrong.
• Unverified claim confirmed: the operator proto's HostView does
  carry a utilization message (fleet.proto), extended per the issue's
  contingency.
• Pre-existing, unrelated: 3 engram-host-agent chunk-cache write-through
  test failures (disk_daemon::backend, pooled_backend) — filed as
  Regression on main: chunk write-through cache not populated (3 test failures post-#522) #552, reproduce on unmodified main, not touched by this change.
• Migration renumbered 0077 → 0078 post-review to resolve a 6-way
  collision with sibling in-flight PRs in the same land-queue batch (see
  Post-review fixups, finding 1).

just check

fmt clean, clippy clean (-D warnings, full workspace + Linux/musl
cross-compile for the touched Linux-only-gated crates), cargo hakari verify clean, cargo nextest run --workspace --no-fail-fast green — the
pre-existing #552 chunk-cache failures are unrelated to this change
(different files, reproduce identically on unmodified main).

Landing order: #541 -> #536 -> #533 -> #527p1 -> #528 -> #530 -> #537 -> #540 -> #539 -> #526 -> #531 -> #538 -> #529 -> #535

🤖 Generated with Claude Code

[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	Jul 6, 2026, 5:43 AM

[nikhilunni]

Deep review of the RAM-ledger implementation (issue #540). Overall: a faithful, high-quality implementation — the ledger module matches the specced snapshot shape and derivation exactly, the parked/running PSS split lands behind a per-sandbox flag with no trait method (guardrail honored), prewarm pending-charging + the tmpfs headroom pre-check work as specced, and the wire/PG/fleet-view surfacing plus the ADR 0046 addendum are all in place. Verdict: solid, mergeable after the migration-number collision is resolved; one transient accounting bug and two acceptance-checklist boxes that the code doesn't actually satisfy are worth a pass before undrafting.

CI

Green — all lanes pass (fmt+clippy, linux, macOS, firecracker, e2e suite + teleport, orchestrator, web, buf, CI Gate).

Issue compliance

Implementation plan steps 1–9 are all present and faithful: ram_ledger.rs matches the specced struct/derivation (parked never added back; pending subtracted); GuestMemoryStats extended with no trait method (the only setter is a cfg(test) pub(crate) fn on the FC backend); UtilizationProbe::sample retired its guest_pss_mib param with no compat shim; the heartbeat builds one snapshot, publishes on a watch channel, and is the single gauge-emission site (HOST_MEM_FREE_PCT moved there); mem_pressure_check deleted with the pure core kept; prewarm registers-before/settles-both-arms with the headroom pre-check; wire (4 serde-defaulted fields + round-trip + old-host default tests), PG (3 columns per the issue's own spec — the pending-field deviation is explicitly documented in the migration, row.rs, and the PR body), fleet view (totality destructure, fleet.proto +3, regenerated TS in both orchestrator/ and web/), and the dated ADR 0046 addendum. New tests are genuinely wired into CI: the live-PG round-trip rides placement_reservation_live_pg, already in ci.yml's --test list; the FC bucketing test is a plain Linux unit test.

Three gaps against the issue's own checklist:

• The migration-number check verified the on-disk high-water mark (0076) but not the issue's explicit "and any in-flight branches" clause — five sibling open PRs also claim 0077 (finding 1).
• Two acceptance boxes are checked that the code does not satisfy: "VZ/Process/non-Linux — gauges not emitted" (they are emitted, as zeros — finding 3) and the one-source-of-truth criterion's "assertable via the watch channel in a unit test" (no such test exists; the box is checked citing construction + grep — finding 4).

No scope creep; the deviations that exist are declared. (I also checked the finder's claim that the two-host placement fixture is "tautological" — dropped it: the issue's acceptance section explicitly requested exactly that fixture, and the test's comment honestly states placement only ever sees the final allocatable_mib.)

Findings

1. deploy/migrations/0077_host_ram_ledger.sql:19 — [CONFIRMED] migration number 0077 collides with five sibling open PRs. #560 (0077_drop_guest_ready_state.sql), #563 (0077_enable_job_capture_progress.sql), #564 (0077_host_capabilities.sql), #565 (0077_enable_job_prestage.sql), and #566 (0077_session_selected_skills.sql) each also add a 0077 migration, and this PR's own landing order places #530/#537 (→ PR #560 et al.) before #540. Failure: whichever lands second gives sqlx a duplicate migration version → coordinator crash-loops at boot (or the live-PG CI lane fails at apply). Fix: renumber at merge time to the then-current high-water mark + 1, and coordinate the number across the in-flight stack (the issue's unverified-claims list called this out explicitly).

2. crates/engram-host-agent/src/ram_ledger.rs:86 — [CONFIRMED] the written fraction of an in-flight prewarm is double-subtracted from allocatable_mib for the whole write window. register_pending_base_shm charges the FULL non-hole byte total before the write and nothing decrements it until settle_pending after the write completes — but MemAvailable is already dropping as the pwrites land tmpfs pages. Concretely: a ~19 GiB dev-brain prewarm at 90% written has MemAvailable down ~17 GiB and the full 19 GiB pending charge still subtracted, so allocatable_mib under-reports by ~17 GiB on a 64 GiB host for minutes — placement rejects sessions that genuinely fit. The direction is conservative (never over-places), but the field's own doc says "charges not yet on the tmpfs". Fix: in sample(), net each pending charge against that file's measured st_blocks (e.g. pending.saturating_sub(file_blocks_bytes)), or settle incrementally.

3. crates/engram-host-agent/src/lib.rs:1176 — [CONFIRMED] ledger gauges are emitted unconditionally, contradicting the checked acceptance box. The issue's criterion (and the PR body's [x]) says "VZ/Process/non-Linux: … gauges not emitted", but every engram_host_ram_ledger_mib{...} / allocatable / tmpfs gauge is set every tick regardless of ram_snapshot.measured — an unmeasured host carries a full family of permanently-zero series (only HOST_MEM_FREE_PCT is gated). Either gate the emission block on ram_snapshot.measured or un-check/correct the acceptance claim.

4. crates/engram-host-agent/src/lib.rs:1175 — [CONFIRMED] the one-source-of-truth watch-channel unit test the issue asked for doesn't exist. The criterion says the heartbeat/pressure-gate coupling is "assertable via the watch channel in a unit test"; the PR body checks the box citing construction + grep instead. The coupling lives in one large inline tokio task — a refactor that re-orders send_replace after util_probe.sample, or samples twice, would silently reintroduce the two-views divergence with nothing failing. A small test (publish a snapshot on a watch channel, assert borrow() equals what sample() was fed) would pin it; otherwise declare the deviation rather than checking the box.

5. crates/engram-host-agent/src/lib.rs:1190 — [CONFIRMED] HOST_BASE_SHM_TMPFS_USED_MIB duplicates the base_shm category gauge instead of reporting statfs used. It's set from ram_snapshot.base_shm_mib (the read_dir st_blocks walk) — byte-identical to engram_host_ram_ledger_mib{category="base_shm"}. Tmpfs consumption invisible to the flat-file walk (an unlinked-but-open file from a base_shm_gc race, a stray subdir/temp file) counts against the 32 GiB cap and the headroom pre-check (both statfs-based) but not this gauge — i.e. it under-reports exactly during an ENOSPC-class incident. tmpfs_stat_mib already has statfs in hand; report f_blocks − f_bfree there instead.

6. crates/engram-core/src/traits/sandbox.rs:94 — [CONFIRMED] no parked_rss_bytes, so a parked sandbox's RSS is measured then discarded. read_smaps_rollup_pss_rss returns both, but the parked branch keeps only PSS — once the ladder parks a 12 GiB resident, the Σpss/Σrss sharing signal structurally excludes it, and the ADR addendum's own rule ("density math that wants a sharing credit must first observe Σpss/Σrss < 1.0") can never be evaluated for parked residents — the exact population density math cares about. This PR is the cheap moment to add the one defaulted field (a later addition re-touches GuestMemoryStats, the FC split, and the read loop). The issue's spec also omitted it, so PLAUSIBLE-as-scope, but the discard itself is in the code.

Automated deep review (core-ops batch); findings verified against the branch — treat PLAUSIBLE items as questions.

[nikhilunni]

[CONFIRMED] 0077 collides with five sibling open PRs — #560, #563, #564, #565, #566 each also add a 0077_*.sql, and the PR body's landing order puts several of them before this one. sqlx errors on a duplicate version → coordinator crash-loops at boot. Renumber at merge time to the then-current high-water mark + 1 (the issue's unverified-claims list explicitly said to check in-flight branches).

[nikhilunni]

Fixed in 6db9843: renamed the migration file 0077 -> 0078 and every code/doc reference to it (coordinator hosts.rs, engram-postgres row.rs, fleet.proto + regenerated TS in both web/ and orchestrator/, ADR 0046 addendum, the live-PG test comment). Per the batch owner's collision resolution, 0077 stays with #560.

[nikhilunni]

[CONFIRMED] transient double-charge during the prewarm window — the full registered charge stays here for the entire multi-minute write while MemAvailable is already dropping as pwrites land tmpfs pages, so the written fraction is subtracted twice from allocatable_mib (a ~19 GiB dev-brain prewarm at 90% written under-reports by ~17 GiB). Direction is conservative, but the doc says "not yet on the tmpfs". Fix: in sample(), net each pending charge against that file's current st_blocks bytes.

[nikhilunni]

Fixed in 8aade45: RamLedger::register_pending_base_shm now takes the target file path alongside the expected byte count, and sample() nets each pending charge against that specific file's own st_blocks (via a new file_allocated_bytes helper) instead of holding the full charge outstanding for the whole write window. New regression test pending_charge_nets_against_bytes_already_written writes partial bytes into the target file mid-charge and asserts the pending figure shrinks accordingly.

[nikhilunni]

[CONFIRMED] gauges emitted unconditionally, contradicting the checked acceptance box — the issue (and the PR body's [x]) says non-Linux/unmeasured hosts get "gauges not emitted", but this whole block runs every tick regardless of ram_snapshot.measured (only HOST_MEM_FREE_PCT is gated). Either gate the block on measured or correct the acceptance claim.

[nikhilunni]

Fixed in 8aade45: the whole HOST_RAM_LEDGER_MIB/HOST_RAM_ALLOCATABLE_MIB/HOST_BASE_SHM_TMPFS_* gauge block is now gated on ram_snapshot.measured, so VZ/Process/non-Linux hosts stop emitting a permanent-zero series. HOST_MEM_FREE_PCT was already correctly gated via free_pct()'s own None return. PR body's acceptance box corrected to describe the actual (now-true) behavior.

[nikhilunni]

[CONFIRMED] the issue's one-source-of-truth criterion says this coupling is "assertable via the watch channel in a unit test" — no such test exists (the PR body checks the box citing construction + grep). A refactor that re-orders send_replace after util_probe.sample, or samples twice, would silently reintroduce the two-views divergence with nothing failing. A small publish-then-borrow() assertion test would pin it; otherwise declare the deviation.

[nikhilunni]

Fixed in 8aade45: added ram_ledger_snapshot_round_trips_through_watch_channel — publishes a RamLedgerSnapshot on a tokio::sync::watch channel and asserts two independent readers (borrow_and_update) observe byte-identical values to what was published, pinning the one-source-of-truth mechanism the heartbeat and pressure gate rely on. PR body's acceptance box corrected to cite the test instead of construction + grep.

[nikhilunni]

[CONFIRMED] byte-identical duplicate of the base_shm category gauge — "tmpfs used" should be statfs used (f_blocks − f_bfree, which tmpfs_stat_mib already has in hand), not the read_dir st_blocks walk. An unlinked-but-open file or stray subdir occupies tmpfs (counts against the cap and the headroom pre-check, both statfs-based) but is invisible here — so this gauge under-reports exactly during the ENOSPC-class incident it exists to debug.

[nikhilunni]

Fixed in 8aade45: tmpfs_stat_mib now also does a real statfs read (f_blocks - f_bfree) and RamLedgerSnapshot carries a new base_shm_tmpfs_used_mib field for it; HOST_BASE_SHM_TMPFS_USED_MIB now reads that field instead of base_shm_mib (the st_blocks dir-walk). base_shm_mib/the base_shm category gauge is unchanged (still the per-file attribution walk) — the two are now genuinely distinct signals.

[nikhilunni]

[CONFIRMED] no parked_rss_bytes — a parked sandbox's RSS is measured by read_smaps_rollup_pss_rss and then discarded. Once the ladder parks a resident VM, the Σpss/Σrss sharing signal structurally excludes it, so the ADR addendum's "must first observe Σpss/Σrss < 1.0" rule can never be evaluated for parked residents. This PR is the cheap moment to add the one defaulted field (a later addition re-touches this struct, the FC split, and the read loop). Spec also omitted it, so treat as a question.

[nikhilunni]

Fixed in c788990: added parked_rss_bytes to GuestMemoryStats, populated it in the FC backend's guest_memory_stats() alongside parked_pss_bytes (same smaps_rollup read), and exposed both via new gauge-only metrics (engram_sandbox_guest_parked_pss_bytes/_rss_bytes) so the Σpss/Σrss ratio is actually observable for parked residents. Took the fix now rather than deferring — agreed it's cheap and avoids re-touching this struct + the FC split + the read loop later; no follow-up issue needed.

[nikhilunni]

Post-review fixup pass

Addressed every finding from the deep review (all 6 marked [CONFIRMED]) in scoped commits, and replied to each inline thread with the fix commit. Also did an honesty pass on the PR body's acceptance-criteria checklist.

#	Finding	Status	Commit
1	Migration 0077 collides with 5 sibling in-flight PRs	Fixed	6db98436 — renumbered 0077 → 0078 + every code/doc reference
2	Transient double-charge: pending prewarm charge held at full total for the whole write window while MemAvailable was already dropping	Fixed	8aade450 — nets the charge against the target file's own st_blocks; new regression test pending_charge_nets_against_bytes_already_written
3	Ledger gauges emitted unconditionally, contradicting the checked "gauges not emitted" acceptance box	Fixed	8aade450 — gated the whole HOST_RAM_LEDGER_MIB/HOST_RAM_ALLOCATABLE_MIB/HOST_BASE_SHM_TMPFS_* block on ram_snapshot.measured
4	Missing watch-channel unit test for the "one source of truth" claim	Fixed	8aade450 — added ram_ledger_snapshot_round_trips_through_watch_channel
5	HOST_BASE_SHM_TMPFS_USED_MIB duplicated the base_shm category gauge instead of a real statfs read	Fixed	8aade450 — tmpfs_stat_mib now also does f_blocks − f_bfree; new base_shm_tmpfs_used_mib field feeds the gauge
6	parked_rss_bytes measured then discarded, blocking the Σpss/Σrss sharing-density signal for parked residents	Fixed	c7889903 — added the field, populated it in the FC backend, exposed via new gauges

Acceptance-criteria honesty pass

Edited the PR body: corrected the "VZ/Process/non-Linux — gauges not emitted" box (now literally true post-finding-3) and the "one source of truth ... assertable via the watch channel in a unit test" box (now backed by the new test from finding 4), and added a "Post-review fixups" section summarizing all six.

just check

fmt clean, clippy clean (-D warnings, full workspace) + Linux/musl cross-compile clean for the touched Linux-gated crates (nix develop -c cargo clippy --target aarch64-unknown-linux-musl -p engram-host-agent -p engram-sandbox-firecracker -p engram-core --all-targets, zero warnings), cargo hakari verify clean, cargo nextest run --workspace --no-fail-fast: 1351/1354 pass. The 3 failures (disk_daemon::backend::tests::flush_write_throughs_chunks_into_local_cache, pooled_backend::tests::migration_fetch_rejects_unlisted_hash_and_bad_export_id, pooled_backend::tests::materialize_chunked_rootfs_uses_chunk_cache_when_present) are the pre-existing #552 regression, already documented in this PR's body, unrelated to this diff (different modules, reproduce identically on unmodified main).

New Linux-only tests (pending_charge_nets_against_bytes_already_written, guest_memory_stats_buckets_parked_pss_separately's extended assertion) run in CI's Linux unit-test lane like the existing #[cfg(target_os = "linux")] tests in these same files — no new CI wiring needed.

CI is currently pending (just pushed); will report status separately once lanes report in.

[nikhilunni]

Merge conflict resolved against main (merge commit dddb5165) — the collision was struct-literal field renames (guest_ip → guest_endpoints) from #555's GuestEndpoints collapse. Also pinned the chunk-cache free-space floor in 3 local tests (0a3a9cd9, 7e9672b8) so they don't spuriously fail on a near-full local disk — unrelated to the merge itself, found while re-verifying just check post-merge. PR now shows MERGEABLE.

[nikhilunni]

Merge conflict against main resolved (03b37fa4) — a genuine 3-way collision in UtilizationProbe::sample, not a mechanical rebase: since this branch cut, #557 independently replaced the free-function disk_mib(work_dir) call with a new self.sample_disk(work_dir) method (part of its ADR-0067 mountpoint-gate fix), while this PR independently replaced the guest_pss_mib: u64 parameter with the RAM-ledger snapshot. Composed both: sample() now takes ledger: &RamLedgerSnapshot (this PR's contribution) and calls self.sample_disk(work_dir) for the disk figures (#557's contribution) — neither side's improvement is lost. Verified via full just check equivalent (fmt/clippy/hakari/targeted nextest, plus the Linux/musl cross-check since this touches host-agent) — all green, including the 8 util::tests::* unit tests that directly exercise this function.