From 17e1525830f185ed6174b5e57f8fbdca1eaaac36 Mon Sep 17 00:00:00 2001
From: rcourtman <8825017+rcourtman@users.noreply.github.com>
Date: Sat, 17 Oct 2026 00:28:13 +0100
Subject: [PATCH] Stop calling an LXC's Proxmox listing memory cache-inclusive

Proxmox's /cluster/resources mem for a container is its cgroup usage with
page cache already subtracted (PVE::CGroup::get_memory_stat: memory.current
minus memory.stat file on cgroup v2, usage_in_bytes minus total_cache on
v1). The backend now reads it as known pressure for containers, but the
frontend classification still listed cluster-resources as cache-inclusive
for every guest, so the container drawer told users the reading "may
include cached memory the container can reuse" and appended setup advice.

Make the classification guest-kind aware the same way: a container's
cluster-resources reading is cache-excluded, while a QEMU guest's (or one
of unknown kind) keeps the caveat. The canonical resource drawer now passes
the guest kind too, so it qualifies the same reading the same way.
---
 .../subsystems/frontend-primitives.md         | 15 ++++---
 .../96fbcd34c5046364.json                     | 39 ++++++++++++++++++
 ...rMetricsHistoryModel.branchcov0712.test.ts | 12 ++++++
 ...resourceDetailDrawerMetricsHistoryModel.ts | 10 +++++
 .../GuestDrawerOverview.memory-cache.test.tsx | 16 +++++++-
 .../Workloads/__tests__/GuestRow.test.tsx     | 26 +++++++++++-
 .../utils/__tests__/memoryObservation.test.ts | 41 ++++++++++++++++++-
 .../src/utils/memoryObservation.ts            | 13 +++++-
 8 files changed, 159 insertions(+), 13 deletions(-)
 create mode 100644 frontend-modern/browser-verification/96fbcd34c5046364.json

diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index 0ca824b116..681caca931 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -243,8 +243,9 @@ An independent qualified memory reading is not paused by a disk deferral.
 Neither Last seen, backup completion nor running power state renews memory.
 Unannotated unrelated platforms and actual zero readings retain their meaning.
 A current reading from a cache-inclusive Proxmox source (`status-mem`,
-`status-freemem`, `cluster-resources`, `derived-total-minus-used`, the same set
-the backend marks `MayIncludeCache`) keeps its numbers, colour and thresholds;
+`status-freemem`, `cluster-resources`, `derived-total-minus-used`, the same
+sources and guest kinds the backend marks `MayIncludeCache`) keeps its numbers,
+colour and thresholds;
 the shared presentation adds `mayIncludeCache` and a `cacheNote` saying a high
 percentage alone does not show memory pressure and which fix can supply the
 guest's own figure. A VM row shows `May include cache` (`Cache?` in compact
@@ -252,9 +253,13 @@ layouts) only while the guest's own memory meets its warning or critical
 threshold, the figure that colours the bar in host-share mode too, which is
 when a cache-inclusive figure reads as pressure; below that the caveat is the
 cell title, the chart's native hover title and assistive text, not a label on every
-agentless VM. A container, whose Proxmox reading is always the cgroup value,
-keeps the caveat in the bar tooltip and drawer instead of a label on every
-row. A retained or freshness-unknown reading keeps its own freshness label
+agentless VM. A container's `cluster-resources` reading is not
+cache-inclusive: Proxmox subtracts page cache from the cgroup usage
+(`PVE::CGroup::get_memory_stat`) before it reaches `/cluster/resources`, so
+`memoryObservation.ts` classifies that source by guest kind and neither row,
+tooltip nor drawer qualifies it. A QEMU guest, or a guest of unknown kind,
+keeps the caveat for it. Any other cache-inclusive container reading keeps the
+caveat in the bar tooltip and drawer instead of a label on every row. A retained or freshness-unknown reading keeps its own freshness label
 with the caveat in its explanation, an unavailable reading is never qualified,
 and the drawer states the note as visible text in `About this reading`. An
 unavailable explanation names only what is known: a powered-off guest reads
diff --git a/frontend-modern/browser-verification/96fbcd34c5046364.json b/frontend-modern/browser-verification/96fbcd34c5046364.json
new file mode 100644
index 0000000000..ad43a52c08
--- /dev/null
+++ b/frontend-modern/browser-verification/96fbcd34c5046364.json
@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "base_sha": "6aef85ac88e3fcb812388c52fa92842a6ef278f5",
+  "verified_at": "2026-10-16T23:27:30Z",
+  "result": "passed",
+  "changed_paths": [
+    "frontend-modern/src/components/Infrastructure/resourceDetailDrawerMetricsHistoryModel.ts",
+    "frontend-modern/src/utils/memoryObservation.ts"
+  ],
+  "content_sha256": {
+    "frontend-modern/src/components/Infrastructure/resourceDetailDrawerMetricsHistoryModel.ts": "6d3917fdd33adf43199becfcb2fc0e32e14c3d282bebefaf3566e586b6feb83d",
+    "frontend-modern/src/utils/memoryObservation.ts": "692666d2a7dbee34ecabde32aac5c4ad226282f96e95feb210b1a69d87a14bdd"
+  },
+  "routes": [
+    "/proxmox"
+  ],
+  "viewports": [
+    {
+      "width": 1440,
+      "height": 900
+    },
+    {
+      "width": 390,
+      "height": 844
+    }
+  ],
+  "states": [
+    "private mock backend built from origin/main; LXC auth-service-01 with a current cluster-resources memory observation",
+    "before (main's memoryObservation.ts): container drawer Details read 'Current · Proxmox (may include cache)' and showed 'About this reading' saying cached memory the container can reuse",
+    "after: container drawer Details read 'Current · Proxmox · <time>' with no cache caveat and no About this reading row",
+    "after: QEMU VM checkout-web-01 drawer still reads 'Proxmox (may include cache)' with the VM cache note",
+    "after at 390px: LXC row memory cell carries no cache cue, drawer reading has no caveat, no horizontal page scroll"
+  ],
+  "interactions": [
+    "opened the LXC row drawer and expanded Details",
+    "opened a VM row drawer and expanded Details",
+    "swapped main's memoryObservation.ts in via Vite HMR for the before view, then restored the fix and reloaded"
+  ]
+}
diff --git a/frontend-modern/src/components/Infrastructure/__tests__/resourceDetailDrawerMetricsHistoryModel.branchcov0712.test.ts b/frontend-modern/src/components/Infrastructure/__tests__/resourceDetailDrawerMetricsHistoryModel.branchcov0712.test.ts
index d90fe3717d..d9a15c7c44 100644
--- a/frontend-modern/src/components/Infrastructure/__tests__/resourceDetailDrawerMetricsHistoryModel.branchcov0712.test.ts
+++ b/frontend-modern/src/components/Infrastructure/__tests__/resourceDetailDrawerMetricsHistoryModel.branchcov0712.test.ts
@@ -67,6 +67,18 @@ describe('canonical drawer History honours selected guest observation provenance
     },
   );
 
+  it('qualifies a retained Proxmox listing reading by the guest kind', () => {
+    const listing = (type: 'vm' | 'system-container') => {
+      const value = { ...resource('last-known'), type };
+      value.memory!.observation!.source = 'cluster-resources';
+      return getResourceMetricsHistoryDeferredMetrics(value).memory.message;
+    };
+    // A QEMU listing counts the guest's cache; a container's has it removed.
+    expect(listing('vm')).toContain('cached memory the VM can reuse');
+    expect(listing('system-container')).not.toContain('cached memory');
+    expect(listing('system-container')).toContain('Source: Proxmox.');
+  });
+
   it.each([-1, 101, NaN, Infinity])('withdraws invalid retained memory %s', (value) => {
     expect(
       getResourceMetricsHistoryDeferredMetrics(resource('last-known', value)).memory.lastKnownValue,
diff --git a/frontend-modern/src/components/Infrastructure/resourceDetailDrawerMetricsHistoryModel.ts b/frontend-modern/src/components/Infrastructure/resourceDetailDrawerMetricsHistoryModel.ts
index a8f78cb0a0..775ac3940b 100644
--- a/frontend-modern/src/components/Infrastructure/resourceDetailDrawerMetricsHistoryModel.ts
+++ b/frontend-modern/src/components/Infrastructure/resourceDetailDrawerMetricsHistoryModel.ts
@@ -166,11 +166,21 @@ const isProxmoxGuest = (resource: Resource): boolean =>
   (resource.platformType === 'proxmox-pve' ||
     resource.platformScopes?.includes('proxmox-pve') === true);
 
+// The guest kind decides whether a Proxmox listing reading counts cache, the
+// same distinction the Workloads drawer makes.
 const memoryReading = (resource: Resource) =>
   getMemoryObservationPresentation(
     resource.memory ? finiteMetric(getMemoryPercent(resource)) : undefined,
     resource.memory?.observation,
     isProxmoxGuest(resource),
+    {
+      guestKind:
+        resource.type === 'vm'
+          ? 'vm'
+          : resource.type === 'system-container'
+            ? 'container'
+            : undefined,
+    },
   );
 
 const guestDiskReading = (resource: Resource) => {
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.memory-cache.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.memory-cache.test.tsx
index 4df7a74672..bf9123e416 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.memory-cache.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.memory-cache.test.tsx
@@ -91,8 +91,12 @@ describe('guest drawer cache-inclusive memory note', () => {
     setValue(guest('agent'));
     expect(screen.queryByText('About this reading')).not.toBeInTheDocument();
     expect(screen.getByText('Memory reading').closest('tr')).not.toHaveTextContent('cache');
-    setValue(guest('cluster-resources', { type: 'lxc' }));
+    setValue(guest('status-mem', { type: 'lxc' }));
     expect(screen.getByText('About this reading').closest('tr')).toHaveTextContent('container');
+    // The container's own listing value already excludes page cache.
+    setValue(guest('cluster-resources', { type: 'lxc' }));
+    expect(screen.queryByText('About this reading')).not.toBeInTheDocument();
+    expect(screen.getByText('Memory reading').closest('tr')).not.toHaveTextContent('cache');
   });
 
   it('keeps the caveat on a retained reading', () => {
@@ -108,10 +112,18 @@ describe('guest drawer cache-inclusive memory note', () => {
     expect(screen.getByText('About this reading')).toBeInTheDocument();
   });
 
-  it('gives a container the Pulse agent only', () => {
+  it('does not call a container listing reading cache-inclusive', () => {
     render(() => (
       <GuestDrawerOverview {...overviewProps(guest('cluster-resources', { type: 'lxc' }))} />
     ));
+    expect(screen.getByText('Memory reading').closest('tr')).toHaveTextContent('Current · Proxmox');
+    expect(screen.getByText('Memory reading').closest('tr')).not.toHaveTextContent('cache');
+    expect(screen.queryByText('About this reading')).not.toBeInTheDocument();
+    expect(screen.queryByText(/may include cache/)).not.toBeInTheDocument();
+  });
+
+  it('gives a container the Pulse agent only', () => {
+    render(() => <GuestDrawerOverview {...overviewProps(guest('status-mem', { type: 'lxc' }))} />);
     const note = screen.getByText('About this reading').closest('tr')!;
     expect(note).toHaveTextContent('Pulse agent in the container');
     expect(note).not.toHaveTextContent('QEMU');
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx
index 16bc30bbfe..217023e865 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx
@@ -1487,7 +1487,7 @@ describe('GuestRow', () => {
           guest: makeGuest({
             type: 'lxc',
             memory: {
-              ...observation('current', observedAt, 'cluster-resources'),
+              ...observation('current', observedAt, 'status-mem'),
               used: 0.9 * 4294967296,
               usage: 90,
             },
@@ -1553,7 +1553,7 @@ describe('GuestRow', () => {
         const { container } = renderGuestRow({
           guest: makeGuest({
             type: 'lxc',
-            memory: observation('current', observedAt, 'cluster-resources'),
+            memory: observation('current', observedAt, 'status-mem'),
           }),
           metricDisplayMode: mode,
           visibleColumnIds: ['name', 'memory'],
@@ -1568,6 +1568,28 @@ describe('GuestRow', () => {
         }
       });
 
+      it(`reads a container's own ${mode} listing value as cache-excluded`, () => {
+        const { container } = renderGuestRow({
+          guest: makeGuest({
+            type: 'lxc',
+            memory: {
+              ...observation('current', observedAt, 'cluster-resources'),
+              used: 0.9 * 4294967296,
+              usage: 90,
+            },
+          }),
+          metricDisplayMode: mode,
+          visibleColumnIds: ['name', 'memory'],
+        });
+        expect(container.querySelector(noticeSelector)).toBeNull();
+        expect(container.querySelector('[data-workload-col="memory"]')).not.toHaveTextContent(
+          /cache/i,
+        );
+        if (mode === 'bars') {
+          expect(screen.getByTestId('memory-bar')).not.toHaveAttribute('data-reading-message');
+        }
+      });
+
       it(`adds no cache cue to a cache-aware ${mode} reading`, () => {
         const { container } = renderGuestRow({
           guest: makeGuest({
diff --git a/frontend-modern/src/utils/__tests__/memoryObservation.test.ts b/frontend-modern/src/utils/__tests__/memoryObservation.test.ts
index 8594acf632..0dcd184b3e 100644
--- a/frontend-modern/src/utils/__tests__/memoryObservation.test.ts
+++ b/frontend-modern/src/utils/__tests__/memoryObservation.test.ts
@@ -122,7 +122,8 @@ describe('cache-inclusive Proxmox memory sources', () => {
     (source) => {
       const precaution =
         'Defer agent setup, restarts and live guest-agent probes during backups or a guest incident.';
-      for (const type of ['qemu', 'lxc']) {
+      // A container's listing reading is cache-excluded, so it carries no note.
+      for (const type of source === 'cluster-resources' ? ['qemu'] : ['qemu', 'lxc']) {
         for (const state of ['current', 'last-known', 'future-state']) {
           const input = reading(source, state, { type });
           const original = structuredClone(input);
@@ -160,6 +161,42 @@ describe('cache-inclusive Proxmox memory sources', () => {
     ).toBeNull();
   });
 
+  it.each([
+    { type: 'lxc' },
+    { type: 'system-container', workloadType: 'system-container' as const },
+  ])('reads a container listing value as cache-excluded (%o)', (changes) => {
+    // Proxmox subtracts page cache from an LXC's cgroup usage before it
+    // reaches /cluster/resources, unlike a QEMU guest's listing mem.
+    for (const state of ['current', 'last-known']) {
+      const presentation = getWorkloadMemoryObservationPresentation(
+        reading('cluster-resources', state, changes),
+      )!;
+      expect(presentation.mayIncludeCache).toBe(false);
+      expect(presentation.cacheNote).toBeUndefined();
+      expect(presentation.summary).not.toContain('may include cache');
+      expect(presentation.message).not.toContain('cached memory');
+      expect(presentation.summary).toContain('Proxmox');
+    }
+    expect(
+      getWorkloadMemoryObservationPresentation(reading('cluster-resources', 'current', changes), {
+        includeCurrent: false,
+      }),
+    ).toBeNull();
+    // Other Proxmox fallbacks keep their caveat for a container.
+    expect(
+      getWorkloadMemoryObservationPresentation(reading('status-mem', 'current', changes))
+        ?.mayIncludeCache,
+    ).toBe(true);
+  });
+
+  it('keeps a listing value of unknown guest kind cache-inclusive', () => {
+    expect(
+      getWorkloadMemoryObservationPresentation(
+        reading('cluster-resources', 'current', { type: 'docker' }),
+      )?.mayIncludeCache,
+    ).toBe(true);
+  });
+
   it('names the fix that fits the guest: the QEMU agent is a VM-only, Linux-only option', () => {
     const vm = getWorkloadMemoryObservationPresentation(reading('status-mem'))!;
     expect(vm.cacheNote).toContain('memory the VM can reuse');
@@ -177,7 +214,7 @@ describe('cache-inclusive Proxmox memory sources', () => {
       { type: 'system-container', workloadType: 'system-container' as const },
     ]) {
       const note = getWorkloadMemoryObservationPresentation(
-        reading('cluster-resources', 'current', changes),
+        reading('status-mem', 'current', changes),
       )!.cacheNote;
       expect(note).toContain('memory the container can reuse');
       expect(note).toContain('Pulse agent in the container');
diff --git a/frontend-modern/src/utils/memoryObservation.ts b/frontend-modern/src/utils/memoryObservation.ts
index 9646c54211..1fd34b210a 100644
--- a/frontend-modern/src/utils/memoryObservation.ts
+++ b/frontend-modern/src/utils/memoryObservation.ts
@@ -28,7 +28,8 @@ export interface MemoryObservationPresentation {
 
 // Proxmox's own listing and status values. Pulse selects them only when no
 // cache-aware source (guest agent, linked Pulse agent, node meminfo) answered;
-// the same four sources set MayIncludeCache in unifiedresources.QualifyGuestMemory.
+// unifiedresources.QualifyGuestMemoryForKind sets MayIncludeCache for the same
+// sources and guest kinds.
 const cacheInclusiveMemorySources = new Set([
   'status-mem',
   'status-freemem',
@@ -38,6 +39,14 @@ const cacheInclusiveMemorySources = new Set([
 
 export type MemoryGuestKind = 'vm' | 'container';
 
+// A container's cluster-resources mem is its cgroup usage with page cache
+// already subtracted (PVE::CGroup::get_memory_stat), so it is not
+// cache-inclusive. A QEMU listing, or one whose guest kind is unknown, is the
+// host's view of guest RAM and counts the guest's own cache.
+const isCacheInclusiveMemorySource = (source: string, kind: MemoryGuestKind | undefined): boolean =>
+  cacheInclusiveMemorySources.has(source) &&
+  !(source === 'cluster-resources' && kind === 'container');
+
 const getCacheNote = (kind: MemoryGuestKind | undefined): string => {
   const noun = kind === 'vm' ? 'VM' : kind === 'container' ? 'container' : 'guest';
   const caveat = `Proxmox's reading may include cached memory the ${noun} can reuse, so a high percentage alone does not mean it is short of memory.`;
@@ -153,7 +162,7 @@ export const getMemoryObservationPresentation = (
   const mayIncludeCache =
     state !== 'unavailable' &&
     observation !== undefined &&
-    cacheInclusiveMemorySources.has(observation.source);
+    isCacheInclusiveMemorySource(observation.source, options.guestKind);
   // Most table rows are current and need no cue. Qualify them identically,
   // but avoid building source/date strings that will never be rendered. A
   // current reading from a cache-inclusive source still carries its caveat.