Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Explain deferred guest reads without unsafe backup advice

pulse-triage[bot]b22d3b4490bd
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index 698506168e..23f91dd104 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -20,6 +20,31 @@
## Purpose
+### Guest disk deferral and retained observations
+
+The existing workload row, disk breakdown tooltip/list and guest Overview use
+one presentation for the fixed guest-read reason vocabulary. Operation locks,
+unverified lock clearance, an in-flight request, cooldown, incomplete response
+and capacity deferrals are not evidence that QGA is missing. Invalid VM identity
+remains distinct. A timeout describes uncertain completion and must not recommend
+restarting QGA during a backup or changing freeze settings.
+
+`prev-` marks last-known disk values, not a fresh sample. Keep those values and
+their identity visible, with the explanation beside the disk evidence, including
+the breakdown tooltip and the phone-readable Overview. Show readable status even
+before the first filesystem sample; do not hide it behind an empty disk list or
+expose only a raw reason. A same-VM fresh observation withdraws the notice and
+updates values without remounting the row. Permission, disabled-agent and actual
+unavailable cases retain their own explanations.
+
+Verification: `workloadGuestPresentation.test.ts`, the mounted `GuestRow`,
+`DiskList`, `StackedDiskBar` and `GuestDrawerOverview.filesystems` regressions,
+and `browser-tests/guest-disk-deferral.cjs` cover the fixed reasons, retained/no
+previous data and fresh resumption with production components and CSS on desktop
+Chromium and touch WebKit. Synthetic observations do not establish the native
+command-ID cause, guest thaw, fresh History collection or containing release.
+
+
### Composed operator tables and conservative rollback consent
Phone storage tables use the canonical weighted-width helper and matching
diff --git a/docs/release-control/v6/internal/subsystems/performance-and-scalability.md b/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
index ecccb3fe0a..9d9e0731fd 100644
--- a/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
+++ b/docs/release-control/v6/internal/subsystems/performance-and-scalability.md
@@ -15,6 +15,16 @@
## Purpose
+### Guest disk status updates retain row ownership
+
+Disk deferral copy follows reactive same-VM props in the existing row and drawer,
+without new guest commands, client polling, History writes or row remounts. Retained
+values are labelled rather than replaced with invented fresh percentages; fresh
+observations update values and remove the status. Mounted row/list/drawer controls
+and `browser-tests/guest-disk-deferral.cjs` verify same-row ownership in bar and
+sparkline modes with desktop and phone CSS. This is client behaviour proof, not
+native backup coordination, new History samples or a fleet performance result.
+
### Phone workload identity weights
The existing phone guest projection allocates 38 percent to the name cell,
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index c93d87e6c8..cf80b93be1 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -23,6 +23,19 @@ and sort the complete canonical change table while startup and ingestion wait.
## Purpose
+### Guest disk freshness presentation
+
+Existing workload disk evidence retains its source reason through the row,
+breakdown and Overview. `prev-` values are explicitly last-known, while a
+deferral with no previous disks explains the missing observation without a
+measured percentage. Lock/uncertain-completion deferrals must not become an
+install/restart recommendation. Human-readable Overview status remains visible
+without filesystem rows and is cleared by a same-identity fresh observation.
+The shared presentation and mounted regressions plus the production-component
+`browser-tests/guest-disk-deferral.cjs` fixture verify this client behaviour;
+they do not prove native QGA coordination, History freshness or delivery.
+
+
### Narrow controller and backup summaries retain their source facts
Kubernetes controller row expansions expose supplied kind-specific targets,
diff --git a/frontend-modern/browser-tests/guest-disk-deferral.cjs b/frontend-modern/browser-tests/guest-disk-deferral.cjs
new file mode 100644
index 0000000000..349adae709
--- /dev/null
+++ b/frontend-modern/browser-tests/guest-disk-deferral.cjs
@@ -0,0 +1,273 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { chromium, webkit } = require('playwright');
+const root = '/workspace/frontend-modern';
+const output = '/workspace/tmp/guest-disk-deferral-proof';
+const runtime = [
+ 'frontend-modern/src/utils/workloadGuestPresentation.ts',
+ 'frontend-modern/src/components/Workloads/GuestRow.tsx',
+ 'frontend-modern/src/components/Workloads/stackedDiskBarModel.ts',
+ 'frontend-modern/src/components/Workloads/StackedDiskBar.tsx',
+ 'frontend-modern/src/components/Workloads/DiskList.tsx',
+ 'frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx',
+];
+const deferrals = [
+ ['vm-locked', 'VM operation lock'],
+ ['lock-unverified', 'cannot verify that the VM is unlocked'],
+ ['agent-busy', 'earlier guest request is still in progress'],
+ ['agent-cooldown', 'after the cooldown'],
+ ['agent-response-incomplete', 'previous response was incomplete'],
+ ['agent-capacity', 'guest-read capacity'],
+ ['invalid-guest-key', 'VM identity is invalid'],
+ ['agent-timeout', 'Do not restart the guest agent during a backup'],
+];
+(async () => {
+ fs.mkdirSync(output, { recursive: true });
+ const playwrightVersion = require('playwright/package.json').version;
+ assert.equal(
+ playwrightVersion,
+ JSON.parse(fs.readFileSync('/workspace/tests/integration/package-lock.json')).packages[
+ 'node_modules/@playwright/test'
+ ].version,
+ );
+ const hashes = Object.fromEntries(
+ runtime.map((p) => [
+ p,
+ crypto
+ .createHash('sha256')
+ .update(fs.readFileSync(path.join('/workspace', p)))
+ .digest('hex'),
+ ]),
+ );
+ process.chdir(root);
+ const { createServer } = await import(path.join(root, 'node_modules/vite/dist/node/index.js'));
+ const server = await createServer({
+ root,
+ configFile: path.join(root, 'vite.config.ts'),
+ cacheDir: path.join(output, 'vite-cache'),
+ server: { host: '127.0.0.1', port: 5294, strictPort: true },
+ });
+ const results = [],
+ screenshots = [];
+ let browser;
+ try {
+ await server.listen();
+ for (const [name, engine, width, dark] of [
+ ['desktop', chromium, 1365, false],
+ ['phone', webkit, 390, true],
+ ]) {
+ browser = await engine.launch(
+ engine === chromium
+ ? { headless: true, channel: 'chromium', args: ['--no-sandbox'] }
+ : { headless: true },
+ );
+ const page = await browser.newPage({
+ viewport: { width, height: width === 390 ? 844 : 900 },
+ isMobile: width === 390,
+ hasTouch: width === 390,
+ locale: 'en-GB',
+ timezoneId: 'UTC',
+ });
+ page.setDefaultTimeout(15000);
+ page.setDefaultNavigationTimeout(60000);
+ const errors = [],
+ checks = [];
+ page.on('pageerror', (e) => {
+ errors.push(e.message);
+ process.stderr.write(`BROWSER_PAGE_ERROR ${e.message}\n`);
+ });
+ page.on('console', (m) => {
+ if (m.type() === 'error')
+ process.stderr.write(`BROWSER_CONSOLE ${m.text().slice(0, 1500)}\n`);
+ });
+ page.on('response', (r) => {
+ if (r.status() >= 400)
+ process.stderr.write(`BROWSER_HTTP ${r.status()} ${new URL(r.url()).pathname}\n`);
+ });
+ await page.route('http://127.0.0.1:5294/api/**', (route) =>
+ route.fulfill({
+ status: 200,
+ contentType: 'application/json',
+ body: JSON.stringify({
+ success: true,
+ data: [],
+ alerts: [],
+ anomalies: [],
+ config: null,
+ }),
+ }),
+ );
+ await page.goto('http://127.0.0.1:5294/browser-tests/guest-disk-deferral.html', {
+ waitUntil: 'domcontentloaded',
+ });
+ try {
+ await page.waitForFunction(() => window.__guestDiskEvidence, null, { timeout: 15000 });
+ } catch (error) {
+ fs.writeFileSync(
+ path.join(output, 'failure.json'),
+ JSON.stringify({ phase: 'fixture-readiness', errors }, null, 2),
+ );
+ throw error;
+ }
+ if (dark) await page.evaluate(() => document.documentElement.classList.add('dark'));
+ const row = page.locator('[data-guest-id="fixture-pve:pve-a:101"]');
+ const cell = row.locator('[data-workload-col="disk"]');
+ await row.click();
+ const drawer = page.getByRole('region', { name: 'Guest Overview' });
+ await drawer.waitFor({ state: 'visible' });
+ await page.evaluate(
+ () =>
+ (window.__originalDiskRow = document.querySelector(
+ '[data-guest-id="fixture-pve:pve-a:101"]',
+ )),
+ );
+ const update = async (reason, data, usage = 50) => {
+ await page.evaluate((value) => window.__guestDiskEvidence.update(value), {
+ reason,
+ data,
+ usage,
+ });
+ await page.waitForFunction(
+ () =>
+ document.querySelector('[data-guest-id="fixture-pve:pve-a:101"]') ===
+ window.__originalDiskRow,
+ );
+ assert.equal(
+ await page.evaluate(() => window.__guestDiskEvidence.identity()),
+ 'fixture-pve:pve-a:101',
+ );
+ };
+ const capture = async (suffix) => {
+ const p = path.join(output, `${name}-${suffix}.png`);
+ await page.screenshot({ path: p, fullPage: true });
+ screenshots.push({
+ path: path.relative('/workspace', p),
+ sha256: crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex'),
+ });
+ };
+ for (const [reason, expected] of deferrals) {
+ await update(`prev-${reason}`, true);
+ await page.waitForFunction(
+ (text) => document.querySelector('[data-workload-col="disk"]').title.includes(text),
+ expected,
+ );
+ const title = await cell.getAttribute('title');
+ assert(title.startsWith('Using last known disk stats. '));
+ assert(title.includes(expected));
+ assert(
+ !title.includes('may not be installed') && !title.includes('may need to be restarted'),
+ );
+ assert((await drawer.innerText()).includes(title));
+ const statusBox = await drawer.getByText(title, { exact: true }).boundingBox();
+ assert(
+ statusBox.width >= 100 && statusBox.height < 220,
+ 'status explanation fits its card',
+ );
+ assert((await drawer.innerText()).includes('/data'));
+ assert(
+ (await page.getByRole('region', { name: 'Guest disk list' }).innerText()).includes(title),
+ );
+ if (name === 'desktop') {
+ // The disclosure click can land on this bar and dismiss its hover
+ // overlay on pointerdown. Leave it before exercising a new hover.
+ await page.locator('h1').hover();
+ await cell.locator('[data-stacked-disk-trigger]').hover();
+ await page.locator('[data-tooltip-portal="true"]').waitFor({ state: 'visible' });
+ assert((await page.locator('[data-tooltip-portal="true"]').innerText()).includes(title));
+ await page.locator('h1').hover();
+ }
+ checks.push(`${reason}: retained row, tooltip, drawer, list and identity`);
+ if (reason === 'vm-locked') await capture('retained-backup');
+ await update(reason, false);
+ await page.waitForFunction(
+ (text) => document.querySelector('[data-workload-col="disk"]').title.includes(text),
+ expected,
+ );
+ assert(!(await cell.getAttribute('title')).includes('Using last known'));
+ assert((await drawer.innerText()).includes(expected));
+ assert(!(await drawer.innerText()).includes('/data'));
+ assert.equal(await cell.locator('[data-stacked-disk-trigger]').count(), 0);
+ checks.push(`${reason}: no previous disk values and no fresh percentage`);
+ if (reason === 'agent-timeout') await capture('uncertain-timeout');
+ }
+ for (const [reason, expected] of [
+ ['permission-denied', 'Permission denied'],
+ ['agent-disabled', 'disabled in VM configuration'],
+ ['agent-not-running', 'Guest agent not running'],
+ ['no-data', 'No disk data available'],
+ ['vm-stopped', 'VM is stopped'],
+ ['no-status', 'could not read the VM status'],
+ ['agent-error', 'Error communicating with guest agent'],
+ ]) {
+ await update(reason, false);
+ await page.waitForFunction(
+ (text) => document.querySelector('[data-workload-col="disk"]').title.includes(text),
+ expected,
+ );
+ assert((await drawer.innerText()).includes(expected));
+ checks.push(`${reason}: existing unavailable case remains distinct`);
+ }
+ await update('prev-agent-cooldown', true);
+ await page.evaluate(() => window.__guestDiskEvidence.mode('sparklines'));
+ assert((await cell.getAttribute('title')).includes('Using last known'));
+ await update('', true, 75);
+ await page.waitForFunction(
+ () => !document.querySelector('[data-workload-col="disk"]').hasAttribute('title'),
+ );
+ assert(!(await drawer.innerText()).includes('Using last known'));
+ assert(!(await drawer.innerText()).includes('Guest reads'));
+ assert.equal(await drawer.getByRole('progressbar').getAttribute('aria-valuenow'), '75');
+ await page.evaluate(() => window.__guestDiskEvidence.mode('bars'));
+ assert.equal(
+ await page.evaluate(
+ () =>
+ document.querySelector('[data-guest-id="fixture-pve:pve-a:101"]') ===
+ window.__originalDiskRow,
+ ),
+ true,
+ );
+ checks.push(
+ 'same-VM fresh resumption removes notice and updates values in both row modes without remount',
+ );
+ await capture('fresh-resumption');
+ assert.equal(
+ await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth),
+ true,
+ );
+ assert.deepEqual(errors, []);
+ results.push({
+ name,
+ browser_version: browser.version(),
+ viewport: { width, height: width === 390 ? 844 : 900 },
+ checks,
+ page_errors: errors,
+ });
+ await browser.close();
+ browser = null;
+ }
+ const receipt = {
+ version: 1,
+ result: 'passed',
+ verified_at: new Date().toISOString(),
+ content_sha256: hashes,
+ playwright_version: playwrightVersion,
+ results,
+ screenshots,
+ limitation:
+ 'Synthetic same-VM observations through production components and CSS; no native QGA/backup, History sample, installation or release acceptance.',
+ };
+ fs.writeFileSync(
+ path.join(output, 'browser-result.json'),
+ JSON.stringify(receipt, null, 2) + '\n',
+ );
+ process.stdout.write(JSON.stringify(receipt) + '\n');
+ } finally {
+ if (browser) await browser.close();
+ await server.close();
+ }
+})().catch((e) => {
+ process.stderr.write(e.stack + '\n');
+ process.exitCode = 1;
+});
diff --git a/frontend-modern/browser-tests/guest-disk-deferral.html b/frontend-modern/browser-tests/guest-disk-deferral.html
new file mode 100644
index 0000000000..16926a6671
--- /dev/null
+++ b/frontend-modern/browser-tests/guest-disk-deferral.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Guest disk deferral verification</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="./guest-disk-deferral.tsx"></script>
+ </body>
+</html>
diff --git a/frontend-modern/browser-tests/guest-disk-deferral.tsx b/frontend-modern/browser-tests/guest-disk-deferral.tsx
new file mode 100644
index 0000000000..d1ad8dfdd2
--- /dev/null
+++ b/frontend-modern/browser-tests/guest-disk-deferral.tsx
@@ -0,0 +1,127 @@
+// Production row, disk tooltip, list and disclosed Overview with synthetic
+// same-VM observations. No collector, QGA, native backup or release proof.
+import { createSignal, Show } from 'solid-js';
+import { render } from 'solid-js/web';
+import { Router, Route } from '@solidjs/router';
+import { GuestRow } from '../src/components/Workloads/GuestRow';
+import { GuestDrawerOverview } from '../src/components/Workloads/GuestDrawerOverview';
+import { DiskList } from '../src/components/Workloads/DiskList';
+import type { VM } from '../src/types/api';
+import { DarkModeContext } from '../src/contexts/appRuntime';
+import '../src/index.css';
+
+function Fixture() {
+ const [observation, setObservation] = createSignal({
+ reason: 'prev-vm-locked',
+ data: true,
+ usage: 50,
+ });
+ const [expanded, setExpanded] = createSignal(false);
+ const [mode, setMode] = createSignal<'bars' | 'sparklines'>('bars');
+ const guest = (): VM => ({
+ id: 'fixture-pve:pve-a:101',
+ vmid: 101,
+ name: 'backup-guest',
+ node: 'pve-a',
+ instance: 'fixture-pve',
+ status: 'running',
+ type: 'qemu',
+ cpu: 0.1,
+ cpus: 2,
+ memory: { total: 1024 ** 3, used: 256 * 1024 ** 2, free: 768 * 1024 ** 2, usage: 25 },
+ disk: {
+ total: 10 * 1024 ** 3,
+ used: observation().data ? (observation().usage / 100) * 10 * 1024 ** 3 : 0,
+ usage: observation().data ? observation().usage : -1,
+ },
+ disks: observation().data
+ ? [
+ {
+ mountpoint: '/data',
+ type: 'ext4',
+ total: 10 * 1024 ** 3,
+ used: (observation().usage / 100) * 10 * 1024 ** 3,
+ usage: observation().usage,
+ },
+ ]
+ : [],
+ diskStatusReason: observation().reason,
+ networkIn: 0,
+ networkOut: 0,
+ diskRead: 0,
+ diskWrite: 0,
+ uptime: 3600,
+ template: false,
+ lastBackup: 0,
+ tags: [],
+ lock: observation().reason.endsWith('vm-locked') ? 'backup' : '',
+ backupInProgress: observation().reason.endsWith('vm-locked'),
+ lastSeen: '2026-10-03T14:00:00Z',
+ });
+ (window as any).__guestDiskEvidence = {
+ update: setObservation,
+ mode: setMode,
+ identity: () => guest().id,
+ };
+ return (
+ <main class="min-h-screen space-y-4 bg-surface p-3 text-base-content">
+ <h1 class="text-base font-semibold">Guest disk observation</h1>
+ <table class="w-full table-fixed">
+ <tbody>
+ <GuestRow
+ guest={guest()}
+ visibleColumnIds={['name', 'disk']}
+ onClick={() => setExpanded(!expanded())}
+ isExpanded={expanded()}
+ metricDisplayMode={mode()}
+ workloadTableLayoutMode={window.innerWidth <= 768 ? 'phone' : 'wide'}
+ />
+ </tbody>
+ </table>
+ <Show when={expanded()}>
+ <section aria-label="Guest Overview">
+ <GuestDrawerOverview
+ guest={guest()}
+ guestOsSummary="Linux"
+ agentHeading="Guest agent"
+ agentLabel=""
+ agentTitle=""
+ hasAgentInfo={false}
+ hasFilesystemDetails={guest().disks!.length > 0}
+ hasNetworkInterfaces={false}
+ hasOsInfo={false}
+ hasWorkloadActionAgent={false}
+ showInGuestAgentInstallCue={false}
+ ipAddresses={[]}
+ networkInterfaces={[]}
+ normalizedTags={[]}
+ backupPresentation={null}
+ workloadActionAgentTitle=""
+ />
+ </section>
+ </Show>
+ <section aria-label="Guest disk list" class="max-w-xl">
+ <h2 class="text-sm font-medium">Filesystems</h2>
+ <DiskList disks={guest().disks!} diskStatusReason={guest().diskStatusReason} />
+ </section>
+ </main>
+ );
+}
+
+render(
+ () => (
+ <Router>
+ <Route
+ path="*"
+ component={() => (
+ <DarkModeContext.Provider
+ value={() => document.documentElement.classList.contains('dark')}
+ >
+ <Fixture />
+ </DarkModeContext.Provider>
+ )}
+ />
+ </Router>
+ ),
+ document.getElementById('root')!,
+);
diff --git a/frontend-modern/browser-verification.json b/frontend-modern/browser-verification.json
index 453fe2f009..66454d4ff9 100644
--- a/frontend-modern/browser-verification.json
+++ b/frontend-modern/browser-verification.json
@@ -1,89 +1,145 @@
{
"version": 1,
"result": "passed",
- "base_sha": "2d6a10ab59d327b461ef762ec69a9c5d0440929a",
- "verified_at": "2026-10-03T11:37:53.905511Z",
- "changed_paths": [
- "frontend-modern/src/features/alerts/AlertDeliveryLogCard.tsx",
- "frontend-modern/src/features/alerts/useNotificationDeliveryLog.ts",
- "frontend-modern/src/features/alerts/useAlertDestinationsTabState.ts",
- "frontend-modern/src/features/alerts/tabs/DestinationsTab.tsx",
- "frontend-modern/src/utils/alertDestinationsPresentation.ts"
- ],
+ "verified_at": "2026-10-03T14:13:34.794Z",
"content_sha256": {
- "frontend-modern/src/features/alerts/AlertDeliveryLogCard.tsx": "cac90b57e94b42360989262b550c9b0beaca8dd6eecdd7f7882911bb49de9fc2",
- "frontend-modern/src/features/alerts/useNotificationDeliveryLog.ts": "e8ce66a9ca6ae82861a9d03a7d565f6c246f9b5fc547e7c2e64f0a3e6bd12014",
- "frontend-modern/src/features/alerts/useAlertDestinationsTabState.ts": "eaf519a7f205be0b0e88ea17b19552f30afef025251262a1ea1b8896442e2673",
- "frontend-modern/src/features/alerts/tabs/DestinationsTab.tsx": "9278ab7cf249eea451040b722b244d1447b05c07557d641187fa51f3bc88a225",
- "frontend-modern/src/utils/alertDestinationsPresentation.ts": "5afa5dbce8eb1602377b7b27f6298438da76e3ebf2f80986677c9988bf36c96c"
+ "frontend-modern/src/utils/workloadGuestPresentation.ts": "bd8ca98831f1da1dfb1b9fd38019940a86626be38e52977d06af8c9a5d611a71",
+ "frontend-modern/src/components/Workloads/GuestRow.tsx": "5b48d53997488fc88c8735f959a325fc242992acba8d4bc7f1f51169ef8398b5",
+ "frontend-modern/src/components/Workloads/stackedDiskBarModel.ts": "f68f8843a64b120d535f6557ef039a246dd65eb2a30d6e4abef223d5dd086de2",
+ "frontend-modern/src/components/Workloads/StackedDiskBar.tsx": "f6bb9a340a77fe749b4a5d0921055397815068008259f5ab9bded7172d750235",
+ "frontend-modern/src/components/Workloads/DiskList.tsx": "b80ffe047b61760061f95a9adc85c3cd3e0cf68674214a64d1d911681f81b240",
+ "frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx": "8f5d8ff247f1f9ed3077e20b55d0dca47994ff7f571d90463fc8b7ee68237bcc"
},
- "routes": [
- "Existing Alerts Notifications tab through production DestinationsTab, destination state, notification/alert API adapters and activity card, under synthetic read-only responses"
- ],
- "viewports": [
- {
- "width": 1365,
- "height": 900
- },
- {
- "width": 390,
- "height": 844
- }
- ],
- "states": [
- "Initial attempt and held-event reads pending without an empty claim",
- "Successful attempts do not wait for held events; refresh remains usable",
- "Both completed empty reads establish the empty window",
- "Independent readable attempts and held-event rows",
- "Held-event HTTP403 clears its rows and warns, without hiding attempt evidence",
- "Pending held retry retains the warning until success",
- "Attempt HTTP503 clears only attempt evidence, preserving readable held rows",
- "Both failures warn without empty claims; successful reads clear warnings"
- ],
- "interactions": [
- "Desktop keyboard Enter and phone touch refresh through the real existing Notifications tab",
- "Partial failure, pending retry and recovery via synthetic API replies; no mutation"
- ],
- "browsers": [
+ "playwright_version": "1.56.1",
+ "results": [
{
- "engine": "desktop",
- "version": "141.0.7390.37"
+ "name": "desktop",
+ "browser_version": "141.0.7390.37",
+ "viewport": {
+ "width": 1365,
+ "height": 900
+ },
+ "checks": [
+ "vm-locked: retained row, tooltip, drawer, list and identity",
+ "vm-locked: no previous disk values and no fresh percentage",
+ "lock-unverified: retained row, tooltip, drawer, list and identity",
+ "lock-unverified: no previous disk values and no fresh percentage",
+ "agent-busy: retained row, tooltip, drawer, list and identity",
+ "agent-busy: no previous disk values and no fresh percentage",
+ "agent-cooldown: retained row, tooltip, drawer, list and identity",
+ "agent-cooldown: no previous disk values and no fresh percentage",
+ "agent-response-incomplete: retained row, tooltip, drawer, list and identity",
+ "agent-response-incomplete: no previous disk values and no fresh percentage",
+ "agent-capacity: retained row, tooltip, drawer, list and identity",
+ "agent-capacity: no previous disk values and no fresh percentage",
+ "invalid-guest-key: retained row, tooltip, drawer, list and identity",
+ "invalid-guest-key: no previous disk values and no fresh percentage",
+ "agent-timeout: retained row, tooltip, drawer, list and identity",
+ "agent-timeout: no previous disk values and no fresh percentage",
+ "permission-denied: existing unavailable case remains distinct",
+ "agent-disabled: existing unavailable case remains distinct",
+ "agent-not-running: existing unavailable case remains distinct",
+ "no-data: existing unavailable case remains distinct",
+ "vm-stopped: existing unavailable case remains distinct",
+ "no-status: existing unavailable case remains distinct",
+ "agent-error: existing unavailable case remains distinct",
+ "same-VM fresh resumption removes notice and updates values in both row modes without remount"
+ ],
+ "page_errors": []
},
{
- "engine": "phone",
- "version": "26.0"
+ "name": "phone",
+ "browser_version": "26.0",
+ "viewport": {
+ "width": 390,
+ "height": 844
+ },
+ "checks": [
+ "vm-locked: retained row, tooltip, drawer, list and identity",
+ "vm-locked: no previous disk values and no fresh percentage",
+ "lock-unverified: retained row, tooltip, drawer, list and identity",
+ "lock-unverified: no previous disk values and no fresh percentage",
+ "agent-busy: retained row, tooltip, drawer, list and identity",
+ "agent-busy: no previous disk values and no fresh percentage",
+ "agent-cooldown: retained row, tooltip, drawer, list and identity",
+ "agent-cooldown: no previous disk values and no fresh percentage",
+ "agent-response-incomplete: retained row, tooltip, drawer, list and identity",
+ "agent-response-incomplete: no previous disk values and no fresh percentage",
+ "agent-capacity: retained row, tooltip, drawer, list and identity",
+ "agent-capacity: no previous disk values and no fresh percentage",
+ "invalid-guest-key: retained row, tooltip, drawer, list and identity",
+ "invalid-guest-key: no previous disk values and no fresh percentage",
+ "agent-timeout: retained row, tooltip, drawer, list and identity",
+ "agent-timeout: no previous disk values and no fresh percentage",
+ "permission-denied: existing unavailable case remains distinct",
+ "agent-disabled: existing unavailable case remains distinct",
+ "agent-not-running: existing unavailable case remains distinct",
+ "no-data: existing unavailable case remains distinct",
+ "vm-stopped: existing unavailable case remains distinct",
+ "no-status: existing unavailable case remains distinct",
+ "agent-error: existing unavailable case remains distinct",
+ "same-VM fresh resumption removes notice and updates values in both row modes without remount"
+ ],
+ "page_errors": []
}
],
- "playwright_version": "1.56.1",
- "checks": 20,
"screenshots": [
{
- "path": "tmp/notification-evidence-proof/desktop-held-pending.png",
- "sha256": "58ddaf1dae1e797e6f938c3e74b705fe75276eaf560de307fe7bfe1644c2df21"
+ "path": "tmp/guest-disk-deferral-proof/desktop-retained-backup.png",
+ "sha256": "6c10970b4c64a784e088067e08fec003a0cf7ca5ef8617b9d91c5a2196bac7ba"
},
{
- "path": "tmp/notification-evidence-proof/desktop-held-unavailable.png",
- "sha256": "fe343a2b7eb67ae1283e4eb411462073e3db26d36d226ef62d9fd49cf9a095c7"
+ "path": "tmp/guest-disk-deferral-proof/desktop-uncertain-timeout.png",
+ "sha256": "f57806ae4c631f1acdb12d466457876ab3e0c94d706bf34fb685ab1254786d1c"
},
{
- "path": "tmp/notification-evidence-proof/desktop-attempts-unavailable.png",
- "sha256": "a4ae26cc87b0bbf91b4dc3150f375a10c6701201deed4eaa3bdfbfce08ade4de"
+ "path": "tmp/guest-disk-deferral-proof/desktop-fresh-resumption.png",
+ "sha256": "770cd0c083a92263ff834befc594ea4caf7c1a0849534655f3d2853b7ccd1bb6"
},
{
- "path": "tmp/notification-evidence-proof/phone-held-pending.png",
- "sha256": "66262c32b745e68f32aba48db19dee2a03c7c62d763efd765ed4da154ec9e00f"
+ "path": "tmp/guest-disk-deferral-proof/phone-retained-backup.png",
+ "sha256": "c79fea8c81dd71f32fcb578725e5bf9ee5ef75e9a8ca4117ab39f67f3b0a753b"
},
{
- "path": "tmp/notification-evidence-proof/phone-held-unavailable.png",
- "sha256": "534cd02e8b5392bd5e73d7f4a7a3d8e2a78596a230d055daef4479ecf0d1fdbc"
+ "path": "tmp/guest-disk-deferral-proof/phone-uncertain-timeout.png",
+ "sha256": "b77012b0d47357f602e5ecd770437b75359944e79ac0c5fcb6930a350293de68"
},
{
- "path": "tmp/notification-evidence-proof/phone-attempts-unavailable.png",
- "sha256": "09652b8023be5e527712d42384e9fee8e114575026aefaf703e62cfa30bc0884"
+ "path": "tmp/guest-disk-deferral-proof/phone-fresh-resumption.png",
+ "sha256": "6bc91549730fb30f64f2ff2f2a0f5d5e3fd8a29147fa50081907da78bc4fa339"
}
],
- "proof_script": "frontend-modern/browser-tests/notification-evidence.cjs",
- "limits": [
- "Synthetic source/UI evidence only, not notification receipt, native provider delivery, release availability or dependency advisory clearance"
+ "limitation": "Synthetic same-VM observations through production components and CSS; no native QGA/backup, History sample, installation or release acceptance.",
+ "base_sha": "d4da7ffefdf91db52043aa2a5b5d1c3e16d13ca9",
+ "changed_paths": [
+ "frontend-modern/src/utils/workloadGuestPresentation.ts",
+ "frontend-modern/src/components/Workloads/GuestRow.tsx",
+ "frontend-modern/src/components/Workloads/stackedDiskBarModel.ts",
+ "frontend-modern/src/components/Workloads/StackedDiskBar.tsx",
+ "frontend-modern/src/components/Workloads/DiskList.tsx",
+ "frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx"
+ ],
+ "routes": [
+ "Existing workload row and guest Overview filesystem evidence, shared disk breakdown tooltip/list; synthetic same-VM props through production components, not a new product route"
+ ],
+ "states": [
+ "Eight fixed lock/uncertain/request/capacity/identity deferral reasons with retained and no previous disk data",
+ "Seven distinct permission/disabled/unavailable cases",
+ "Same-VM fresh 75 percent resumption removes notices without row remount"
+ ],
+ "interactions": [
+ "Real desktop hover breakdown with readable freshness context",
+ "Desktop click and phone touch open the existing row disclosure into production Overview",
+ "Same-VM observation replacement, bars/sparklines and fresh resumption with no guest commands"
+ ],
+ "viewports": [
+ {
+ "width": 1365,
+ "height": 900
+ },
+ {
+ "width": 390,
+ "height": 844
+ }
]
}
diff --git a/frontend-modern/src/components/Workloads/DiskList.tsx b/frontend-modern/src/components/Workloads/DiskList.tsx
index 88afbf99c2..6d8fb6a4f2 100644
--- a/frontend-modern/src/components/Workloads/DiskList.tsx
+++ b/frontend-modern/src/components/Workloads/DiskList.tsx
@@ -15,6 +15,9 @@ export function DiskList(props: DiskListProps) {
}
>
<div class="flex flex-col gap-1.5">
+ <Show when={props.diskStatusReason}>
+ <p class="text-xs text-muted">{diskStatusTooltip()}</p>
+ </Show>
<For each={diskPresentation()}>
{(disk) => {
return (
diff --git a/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx b/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
index c7d95a9fae..2d843f3a35 100644
--- a/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
+++ b/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
@@ -13,7 +13,10 @@ import { AvailabilityProbeStatusCards } from '@/components/Infrastructure/Availa
import type { DiscoveryIdentifiedSummary } from '@/utils/discoveryPresentation';
import { formatBytes } from '@/utils/format';
import type { MetricDisplayThresholds } from '@/utils/metricThresholds';
-import { getWorkloadsGuestProtectionPresentation } from '@/utils/workloadGuestPresentation';
+import {
+ getWorkloadGuestDiskStatusMessage,
+ getWorkloadsGuestProtectionPresentation,
+} from '@/utils/workloadGuestPresentation';
import { AvailabilityProbeSuggestionCard } from './AvailabilityProbeSuggestionCard';
import { buildWorkloadsDiskPresentation } from './diskListModel';
@@ -119,6 +122,10 @@ export function GuestDrawerOverview(props: GuestDrawerOverviewProps) {
const diskRows = (props.guest.disks ?? []).map((disk, index) =>
buildWorkloadsDiskPresentation(disk, index, props.diskThresholds),
);
+ const diskStatusMessage =
+ isGuestDrawerVM(props.guest) && props.guest.diskStatusReason
+ ? getWorkloadGuestDiskStatusMessage(props.guest.diskStatusReason)
+ : null;
return compactDetailSections([
discovery
@@ -187,7 +194,7 @@ export function GuestDrawerOverview(props: GuestDrawerOverviewProps) {
.map((row) => makeDetailRow(row.label, row.value)),
),
},
- props.hasFilesystemDetails && diskRows.length > 0
+ (props.hasFilesystemDetails && diskRows.length > 0) || diskStatusMessage
? {
label: 'Filesystems',
rows: compactDetailRows([
@@ -212,11 +219,7 @@ export function GuestDrawerOverview(props: GuestDrawerOverviewProps) {
},
),
),
- makeDetailRow(
- 'Status',
- isGuestDrawerVM(props.guest) ? props.guest.diskStatusReason : null,
- { wrap: true },
- ),
+ makeDetailRow('Status', diskStatusMessage, { layout: 'stacked', wrap: true }),
]),
}
: null,
diff --git a/frontend-modern/src/components/Workloads/GuestRow.tsx b/frontend-modern/src/components/Workloads/GuestRow.tsx
index 299d9e6875..776bd256d3 100644
--- a/frontend-modern/src/components/Workloads/GuestRow.tsx
+++ b/frontend-modern/src/components/Workloads/GuestRow.tsx
@@ -553,7 +553,13 @@ export function GuestRow(props: GuestRowProps) {
{/* Disk */}
<Show when={isColVisible('disk')}>
- <td class="px-1.5 sm:px-2 py-0.5 align-middle" data-workload-col="disk">
+ <td
+ class="px-1.5 sm:px-2 py-0.5 align-middle"
+ data-workload-col="disk"
+ title={
+ isVM(props.guest) && props.guest.diskStatusReason ? getDiskStatusTooltip() : undefined
+ }
+ >
<Show when={isSparklineMode()}>
{renderMetricSparkline(
'disk',
@@ -585,6 +591,11 @@ export function GuestRow(props: GuestRowProps) {
aggregateDisk={props.guest.disk}
anomaly={diskAnomaly()}
thresholds={diskThresholds()}
+ statusMessage={
+ isVM(props.guest) && props.guest.diskStatusReason
+ ? getDiskStatusTooltip()
+ : undefined
+ }
/>
}
>
diff --git a/frontend-modern/src/components/Workloads/StackedDiskBar.tsx b/frontend-modern/src/components/Workloads/StackedDiskBar.tsx
index 1ae9b1098d..74cb02dbec 100644
--- a/frontend-modern/src/components/Workloads/StackedDiskBar.tsx
+++ b/frontend-modern/src/components/Workloads/StackedDiskBar.tsx
@@ -255,6 +255,9 @@ export function StackedDiskBar(props: StackedDiskBarProps) {
<div class="font-medium mb-1 text-slate-300 border-b border-border pb-1">
{presentation().tooltipTitle}
</div>
+ <Show when={props.statusMessage}>
+ <p class="mb-1 text-xs text-muted">{props.statusMessage}</p>
+ </Show>
<For each={presentation().tooltipContent}>
{(item, idx) => (
<div
diff --git a/frontend-modern/src/components/Workloads/__fixtures__/guestDiskDeferrals.ts b/frontend-modern/src/components/Workloads/__fixtures__/guestDiskDeferrals.ts
new file mode 100644
index 0000000000..cf30a84096
--- /dev/null
+++ b/frontend-modern/src/components/Workloads/__fixtures__/guestDiskDeferrals.ts
@@ -0,0 +1,32 @@
+// Fixed client/builder reason vocabulary, not a diagnosis of a native QGA fault.
+export const guestDiskDeferrals = [
+ [
+ 'vm-locked',
+ 'Guest reads paused while Proxmox reports a VM operation lock, such as a backup. Pulse will check again on a later poll.',
+ ],
+ [
+ 'lock-unverified',
+ 'Guest reads deferred because Pulse cannot verify that the VM is unlocked. Pulse will check again on a later poll.',
+ ],
+ [
+ 'agent-busy',
+ 'Guest reads deferred while an earlier guest request is still in progress. Pulse will check again on a later poll.',
+ ],
+ [
+ 'agent-cooldown',
+ 'Guest reads paused after an earlier request did not complete reliably. Pulse will check again after the cooldown.',
+ ],
+ [
+ 'agent-response-incomplete',
+ 'Guest reads paused because the previous response was incomplete. Pulse will check again on a later poll.',
+ ],
+ [
+ 'agent-capacity',
+ 'Guest reads deferred because Pulse has reached its guest-read capacity. Pulse will check again on a later poll.',
+ ],
+ ['invalid-guest-key', 'Guest reads unavailable because the VM identity is invalid.'],
+ [
+ 'agent-timeout',
+ 'Guest request timed out. Completion is uncertain. Do not restart the guest agent during a backup.',
+ ],
+] as const;
diff --git a/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx b/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx
index 99807094f5..b11f2534e1 100644
--- a/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx
@@ -3,6 +3,8 @@ import { render, screen, cleanup } from '@solidjs/testing-library';
import { DiskList } from '../DiskList';
import { buildWorkloadsDiskPresentation, getWorkloadsDiskUsagePercent } from '../diskListModel';
import type { Disk } from '@/types/api';
+import { createSignal } from 'solid-js';
+import { guestDiskDeferrals } from '../__fixtures__/guestDiskDeferrals';
function makeDisk(overrides: Partial<Disk> = {}): Disk {
return {
@@ -46,7 +48,10 @@ describe('DiskList', () => {
'agent-not-running',
'Guest agent not running. Install and start qemu-guest-agent in the VM.',
],
- ['agent-timeout', 'Guest agent timeout. Agent may need to be restarted.'],
+ [
+ 'agent-timeout',
+ 'Guest request timed out. Completion is uncertain. Do not restart the guest agent during a backup.',
+ ],
[
'permission-denied',
'Permission denied. Check that your Pulse user/token has VM.Monitor permission (PVE 8) or VM.GuestAgent.Audit permission (PVE 9).',
@@ -59,6 +64,11 @@ describe('DiskList', () => {
],
['agent-error', 'Error communicating with guest agent.'],
['no-data', 'No disk data available from Proxmox API.'],
+ ['vm-stopped', 'Guest filesystem stats unavailable while the VM is stopped.'],
+ [
+ 'no-status',
+ 'Guest filesystem stats unavailable because Pulse could not read the VM status from Proxmox.',
+ ],
[
'prev-no-filesystems',
'Using last known disk stats. No filesystems found. VM may be booting or using a Live ISO.',
@@ -78,6 +88,30 @@ describe('DiskList', () => {
});
describe('rendering disks', () => {
+ it.each(guestDiskDeferrals)(
+ 'keeps retained values and explains %s until fresh data resumes',
+ (reason, message) => {
+ const [disks, setDisks] = createSignal([makeDisk()]);
+ const [status, setStatus] = createSignal<string | undefined>(`prev-${reason}`);
+ render(() => <DiskList disks={disks()} diskStatusReason={status()} />);
+ expect(screen.getByText(`Using last known disk stats. ${message}`)).toBeInTheDocument();
+ expect(screen.getByText('50%')).toBeInTheDocument();
+ setDisks([makeDisk({ used: 80530636800, usage: 75 })]);
+ setStatus(undefined);
+ expect(screen.queryByText(/Using last known/)).not.toBeInTheDocument();
+ expect(screen.getByText('75%')).toBeInTheDocument();
+ },
+ );
+
+ it.each(guestDiskDeferrals)(
+ 'explains %s without claiming previous values when none exist',
+ (reason, message) => {
+ render(() => <DiskList disks={[]} diskStatusReason={reason} />);
+ expect(screen.getByText('-')).toHaveAttribute('title', message);
+ expect(screen.queryByText(/Using last known/)).not.toBeInTheDocument();
+ },
+ );
+
it('renders a single disk with correct label, usage, and type', () => {
const disk = makeDisk({ mountpoint: '/data', type: 'xfs' });
render(() => <DiskList disks={[disk]} />);
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystems.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystems.test.tsx
index 38e5e81bce..bb27528599 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystems.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystems.test.tsx
@@ -1,7 +1,8 @@
import { cleanup, render, screen } from '@solidjs/testing-library';
-import type { ComponentProps } from 'solid-js';
+import { createSignal, type ComponentProps } from 'solid-js';
import { afterEach, describe, expect, it } from 'vitest';
import { GuestDrawerOverview } from '../GuestDrawerOverview';
+import { guestDiskDeferrals } from '../__fixtures__/guestDiskDeferrals';
const paths = ['/mnt/Plex/Media/Animation/Films', '/mnt/Plex/Media/Animation/Series'];
const props: ComponentProps<typeof GuestDrawerOverview> = {
@@ -55,6 +56,47 @@ const props: ComponentProps<typeof GuestDrawerOverview> = {
describe('GuestDrawerOverview filesystem labels', () => {
afterEach(cleanup);
+ it.each(guestDiskDeferrals)(
+ 'explains %s in the existing drawer even before any disk sample',
+ (reason, message) => {
+ render(() => (
+ <GuestDrawerOverview
+ {...props}
+ hasFilesystemDetails={false}
+ guest={{ ...props.guest, type: 'qemu', disks: [], diskStatusReason: reason }}
+ />
+ ));
+ expect(screen.getByText('Filesystems')).toBeInTheDocument();
+ expect(screen.getByText(message)).toBeInTheDocument();
+ expect(screen.queryByRole('progressbar')).not.toBeInTheDocument();
+ expect(screen.queryByText(/Using last known/)).not.toBeInTheDocument();
+ },
+ );
+
+ it('retains disk rows with readable status, then withdraws the notice on fresh resumption', () => {
+ const [guest, setGuest] = createSignal({
+ ...props.guest,
+ type: 'qemu' as const,
+ diskStatusReason: 'prev-vm-locked',
+ });
+ render(() => <GuestDrawerOverview {...props} guest={guest()} />);
+ expect(
+ screen.getByText(/^Using last known disk stats\. Guest reads paused/).closest('td'),
+ ).toHaveAttribute('colspan', '2');
+ expect(screen.queryByText('prev-vm-locked')).not.toBeInTheDocument();
+ for (const path of paths) expect(screen.getByText(path)).toBeInTheDocument();
+ setGuest({
+ ...guest(),
+ diskStatusReason: '',
+ disks: guest().disks!.map((disk) => ({ ...disk, usage: 75 })),
+ });
+ expect(screen.queryByText(/Using last known/)).not.toBeInTheDocument();
+ expect(screen.queryByText('Status')).not.toBeInTheDocument();
+ expect(
+ screen.getByRole('progressbar', { name: `Filesystem ${paths[0]} utilization` }),
+ ).toHaveAttribute('aria-valuenow', '75');
+ });
+
it('shows linked-agent RAID arrays beside the guest storage evidence', () => {
render(() => (
<GuestDrawerOverview
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx
index d6fb813c6b..42b1032ce3 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestRow.test.tsx
@@ -3,6 +3,7 @@ import { render, screen, fireEvent, cleanup } from '@solidjs/testing-library';
import { createSignal } from 'solid-js';
import type { WorkloadGuest } from '@/types/workloads';
import type { Memory, Disk } from '@/types/api';
+import { guestDiskDeferrals } from '../__fixtures__/guestDiskDeferrals';
// ── Hoisted mocks ──────────────────────────────────────────────────────
@@ -75,7 +76,9 @@ vi.mock('@/components/Workloads/EnhancedCPUBar', () => ({
}));
vi.mock('../StackedDiskBar', () => ({
- StackedDiskBar: () => <div data-testid="disk-bar" />,
+ StackedDiskBar: (props: { statusMessage?: string }) => (
+ <div data-testid="disk-bar" data-status-message={props.statusMessage} />
+ ),
}));
vi.mock('../StackedMemoryBar', () => ({
@@ -668,6 +671,39 @@ describe('GuestRow', () => {
});
describe('lock label', () => {
+ it.each(guestDiskDeferrals)(
+ 'annotates retained row and disk tooltip for %s',
+ (reason, message) => {
+ const { container } = renderGuestRow({
+ guest: makeGuest({ diskStatusReason: `prev-${reason}` }),
+ });
+ const expected = `Using last known disk stats. ${message}`;
+ expect(container.querySelector('[data-workload-col="disk"]')).toHaveAttribute(
+ 'title',
+ expected,
+ );
+ expect(screen.getByTestId('disk-bar')).toHaveAttribute('data-status-message', expected);
+ },
+ );
+
+ it('clears retained status for a same-VM fresh update in sparkline mode without remounting', () => {
+ const [guest, setGuest] = createSignal(
+ makeGuest({ diskStatusReason: 'prev-agent-cooldown' }),
+ );
+ const { container } = render(() => (
+ <table>
+ <tbody>
+ <GuestRow guest={guest()} metricDisplayMode="sparklines" />
+ </tbody>
+ </table>
+ ));
+ const cell = container.querySelector('[data-workload-col="disk"]');
+ expect(cell).toHaveAttribute('title', expect.stringContaining('Using last known'));
+ setGuest(makeGuest({ diskStatusReason: undefined, disk: makeDisk({ usage: 75 }) }));
+ expect(container.querySelector('[data-workload-col="disk"]')).toBe(cell);
+ expect(cell).not.toHaveAttribute('title');
+ });
+
it('shows lock label when guest is locked', () => {
renderGuestRow({ guest: makeGuest({ lock: 'migrate' }) });
expect(screen.getByText(/Lock:.*migrate/)).toBeTruthy();
diff --git a/frontend-modern/src/components/Workloads/__tests__/StackedDiskBar.test.tsx b/frontend-modern/src/components/Workloads/__tests__/StackedDiskBar.test.tsx
index 391101ac73..9cd200c640 100644
--- a/frontend-modern/src/components/Workloads/__tests__/StackedDiskBar.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/StackedDiskBar.test.tsx
@@ -343,6 +343,17 @@ describe('StackedDiskBar', () => {
// ── Tooltip ──────────────────────────────────────────────────────────────
describe('tooltip', () => {
+ it('includes caller-owned freshness context beside unchanged disk evidence', async () => {
+ const message = 'Using last known disk stats. Guest reads paused while a backup is running.';
+ const { container } = render(() => (
+ <StackedDiskBar disks={[makeDisk()]} statusMessage={message} />
+ ));
+ await fireEvent.mouseEnter(getBarTrigger(container));
+ expect(screen.getByText(message)).toBeInTheDocument();
+ expect(screen.getByText('/')).toBeInTheDocument();
+ expect(screen.getByText('Disk Usage')).toBeInTheDocument();
+ });
+
it('shows tooltip on mouse enter with disk details', async () => {
const disk = makeDisk({
used: 53687091200,
diff --git a/frontend-modern/src/components/Workloads/stackedDiskBarModel.ts b/frontend-modern/src/components/Workloads/stackedDiskBarModel.ts
index ed72f85037..3dbf3531b6 100644
--- a/frontend-modern/src/components/Workloads/stackedDiskBarModel.ts
+++ b/frontend-modern/src/components/Workloads/stackedDiskBarModel.ts
@@ -18,6 +18,7 @@ export interface StackedDiskBarProps {
showDiskCount?: boolean;
anomaly?: AnomalyReport | null;
thresholds?: MetricDisplayThresholds | null;
+ statusMessage?: string;
}
export interface StackedDiskSegment {
diff --git a/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts b/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts
index 7c7c0bd422..d7c8fbde94 100644
--- a/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts
+++ b/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts
@@ -1,4 +1,5 @@
import { describe, expect, it } from 'vitest';
+import { guestDiskDeferrals } from '@/components/Workloads/__fixtures__/guestDiskDeferrals';
import {
getWorkloadsGuestBackupStatusPresentation,
getWorkloadsGuestBackupTooltip,
@@ -8,6 +9,18 @@ import {
} from '@/utils/workloadGuestPresentation';
describe('workloadGuestPresentation', () => {
+ it.each(guestDiskDeferrals)(
+ 'explains %s with and without retained disk evidence',
+ (reason, message) => {
+ expect(getWorkloadGuestDiskStatusMessage(reason)).toBe(message);
+ expect(getWorkloadGuestDiskStatusMessage(`prev-${reason}`)).toBe(
+ `Using last known disk stats. ${message}`,
+ );
+ expect(message).not.toContain('may not be installed');
+ expect(message).not.toContain('may need to be restarted');
+ },
+ );
+
it('returns canonical guest backup status presentation', () => {
expect(getWorkloadsGuestBackupStatusPresentation('fresh')).toEqual({
color: 'text-green-600 dark:text-green-400',
diff --git a/frontend-modern/src/utils/workloadGuestPresentation.ts b/frontend-modern/src/utils/workloadGuestPresentation.ts
index 7b68c92052..62c1ebead9 100644
--- a/frontend-modern/src/utils/workloadGuestPresentation.ts
+++ b/frontend-modern/src/utils/workloadGuestPresentation.ts
@@ -103,7 +103,21 @@ export function getWorkloadGuestDiskStatusMessage(reason?: string): string {
case 'agent-not-running':
return 'Guest agent not running. Install and start qemu-guest-agent in the VM.';
case 'agent-timeout':
- return 'Guest agent timeout. Agent may need to be restarted.';
+ return 'Guest request timed out. Completion is uncertain. Do not restart the guest agent during a backup.';
+ case 'vm-locked':
+ return 'Guest reads paused while Proxmox reports a VM operation lock, such as a backup. Pulse will check again on a later poll.';
+ case 'lock-unverified':
+ return 'Guest reads deferred because Pulse cannot verify that the VM is unlocked. Pulse will check again on a later poll.';
+ case 'agent-busy':
+ return 'Guest reads deferred while an earlier guest request is still in progress. Pulse will check again on a later poll.';
+ case 'agent-cooldown':
+ return 'Guest reads paused after an earlier request did not complete reliably. Pulse will check again after the cooldown.';
+ case 'agent-response-incomplete':
+ return 'Guest reads paused because the previous response was incomplete. Pulse will check again on a later poll.';
+ case 'agent-capacity':
+ return 'Guest reads deferred because Pulse has reached its guest-read capacity. Pulse will check again on a later poll.';
+ case 'invalid-guest-key':
+ return 'Guest reads unavailable because the VM identity is invalid.';
case 'permission-denied':
return 'Permission denied. Check that your Pulse user/token has VM.Monitor permission (PVE 8) or VM.GuestAgent.Audit permission (PVE 9).';
case 'agent-disabled':
@@ -116,6 +130,10 @@ export function getWorkloadGuestDiskStatusMessage(reason?: string): string {
return 'Error communicating with guest agent.';
case 'no-data':
return 'No disk data available from Proxmox API.';
+ case 'vm-stopped':
+ return 'Guest filesystem stats unavailable while the VM is stopped.';
+ case 'no-status':
+ return 'Guest filesystem stats unavailable because Pulse could not read the VM status from Proxmox.';
default:
return 'Disk stats unavailable. Guest agent may not be installed.';
}