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.

Keep failed guest reads out of installation advice

pulse-triage[bot]605ebed18c46
diff --git a/frontend-modern/browser-tests/guest-reading-help.cjs b/frontend-modern/browser-tests/guest-reading-help.cjs
new file mode 100644
index 0000000000..393b199f76
--- /dev/null
+++ b/frontend-modern/browser-tests/guest-reading-help.cjs
@@ -0,0 +1,120 @@
+// New current-source static preview, not a replay of the stopped Vite request.
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+const crypto = require('node:crypto');
+const assert = require('node:assert/strict');
+const { chromium, webkit } = require('playwright');
+const root = '/workspace/frontend-modern';
+const output = '/workspace/tmp/guest-reading-help';
+const preview = output + '/preview';
+const origin = 'http://127.0.0.1:5331';
+const runtime = ['frontend-modern/src/utils/workloadGuestPresentation.ts', 'frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx'];
+const hash = file => crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+const load = name => import(require.resolve(name, { paths: [root] }));
+(async () => {
+ fs.mkdirSync(output, { recursive: true });
+ const result = {
+ result: 'incomplete', playwright: require('playwright/package.json').version,
+ runtime_hashes: Object.fromEntries(runtime.map(file => [file, hash('/workspace/' + file)])),
+ fixtures: Object.fromEntries(['cjs','tsx','html'].map(ext => ['guest-reading-help.' + ext, hash(root + '/browser-tests/guest-reading-help.' + ext)])),
+ cases: [], captures: [], cleanup: { browser: false, server: false }, phases: [],
+ limits: 'Static production-component preview with synthetic observations/APIs. No native guest, collector, cause, thaw, writes, restart, installed or release acceptance.',
+ };
+ let server, browser;
+ try {
+ assert.equal(result.playwright, JSON.parse(fs.readFileSync('/workspace/tests/integration/package-lock.json')).packages['node_modules/@playwright/test'].version);
+ const { build } = await load('vite');
+ const solidModule = await load('vite-plugin-solid');
+ const solid = solidModule.default.default || solidModule.default;
+ const { default: tailwind } = await load('@tailwindcss/vite');
+ await build({ root, configFile: false, logLevel: 'warn', plugins: [solid(), tailwind()], resolve: { alias: { '@': root + '/src' } }, build: { target: 'esnext', outDir: preview, emptyOutDir: true, minify: false, rollupOptions: { input: root + '/browser-tests/guest-reading-help.html' } } });
+ result.phases.push('production-component static preview compiled');
+ server = http.createServer((req,res) => {
+ const url = new URL(req.url, origin);
+ let file = path.resolve(preview, '.' + decodeURIComponent(url.pathname));
+ if (file !== preview && !file.startsWith(preview + '/')) { res.writeHead(403); return res.end(); }
+ if (!fs.existsSync(file) || fs.statSync(file).isDirectory()) file = preview + '/browser-tests/guest-reading-help.html';
+ const ext = path.extname(file); res.setHeader('Content-Type', ({'.html':'text/html','.js':'text/javascript','.css':'text/css','.md':'text/plain','.json':'application/json'})[ext] || 'application/octet-stream');
+ res.end(fs.readFileSync(file));
+ });
+ await new Promise(resolve => server.listen(5331, '127.0.0.1', resolve));
+ result.phases.push('loopback-only static server listening');
+ for (const [name, engine, width, dark] of [['chromium-desktop', chromium, 1365, false], ['webkit-phone', webkit, 390, true]]) {
+ browser = await engine.launch(engine === chromium ? {headless:true, channel:'chromium', args:['--no-sandbox']} : {headless:true});
+ const context = await browser.newContext({viewport:{width,height:900},isMobile:width<=768,hasTouch:width<=768,locale:'en-GB'});
+ const page = await context.newPage();
+ page.setDefaultTimeout(12000);
+ const record = { name, browser: browser.version(), width, errors: [], requests: [], states: [] };
+ result.cases.push(record);
+ page.on('pageerror', err => record.errors.push(err.message));
+ await page.route('**/*', route => {
+ const request=route.request(), url=new URL(request.url());
+ if (url.origin !== origin) { record.requests.push({method:request.method(),path:url.pathname,blocked:true}); return route.abort(); }
+ if (url.pathname.startsWith('/api/')) {
+ record.requests.push({method:request.method(),path:url.pathname,synthetic:true});
+ return route.fulfill({status:200,contentType:'application/json',body:JSON.stringify({success:true,data:[],alerts:[],anomalies:[],config:null})});
+ }
+ return route.continue();
+ });
+ await page.addInitScript(dark => {
+ window.__input = [];
+ document.addEventListener('click', event => window.__input.push(event.isTrusted), true);
+ document.addEventListener('DOMContentLoaded', () => { if (dark) document.documentElement.classList.add('dark'); });
+ }, dark);
+ await page.goto(origin, {waitUntil:'domcontentloaded'});
+ await page.waitForFunction(() => window.__readingHelp);
+ const disclosure=page.locator('[data-guest-id="fixture-pve:pve-a:101"] [data-row-action]').first();
+ if (width<=768) await page.getByText('reading-guest', {exact:true}).tap(); else {await disclosure.focus();await page.keyboard.press('Enter');}
+ const drawer=page.getByRole('region',{name:'Guest details'});
+ await drawer.waitFor({state:'visible'});
+ const technical=drawer.getByTestId('guest-technical-details');
+ // The current production overview is a section, not a collapsed details element.
+ for (const state of [
+ {name:'missing-windows',reason:'agent-not-running',retained:false,os:'Windows 11'},
+ {name:'retained-android',reason:'agent-not-running',retained:true,os:'Android'},
+ {name:'disabled',reason:'agent-disabled',retained:false,os:'Windows 11'},
+ {name:'unknown',reason:'future-private-detail',retained:false,os:'Android'},
+ ]) {
+ await page.evaluate(state => window.__readingHelp.update(state), state);
+ await page.waitForFunction(() => document.querySelector('[data-testid="guest-technical-details"]').textContent.includes('Filesystem reading guidance'));
+ const text=await technical.innerText();
+ assert.doesNotMatch(text,/Install and start|Enable it in VM Options|may not be installed|qemu-guest-agent|future-private-detail/);
+ assert.match(text,/backup/);assert.match(text,/guest incident/);
+ if(state.retained) {assert.match(text,/Using last known disk stats/);assert.match(text,/Last known 50%/);assert.equal(await technical.getByRole('progressbar').count(),0);}
+ if(state.name==='missing-windows') assert.match(text,/does not prove it is absent or stopped/);
+ if(state.name==='unknown') assert.match(text,/cause is unknown/);
+ const link=technical.getByRole('link',{name:'Filesystem reading guidance'});
+ assert.equal(await link.getAttribute('href'),'/docs/VM_DISK_MONITORING#a-missing-reading-is-not-an-installation-diagnosis');
+ const layout=await technical.evaluate(el=>({width:el.clientWidth,scroll:el.scrollWidth,document:document.documentElement.clientWidth,documentScroll:document.documentElement.scrollWidth}));
+ assert.ok(layout.scroll<=layout.width+1,JSON.stringify(layout));assert.ok(layout.documentScroll<=layout.document+1,JSON.stringify(layout));
+ const file=name+'-'+state.name+'.png';await technical.screenshot({path:output+'/'+file});
+ result.captures.push({file,sha256:hash(output+'/'+file)});record.states.push({name:state.name,text,layout});
+ }
+ await page.evaluate(() => window.__readingHelp.update({reason:'',retained:true,os:'Windows 11'}));
+ assert.equal(await technical.getByRole('link',{name:'Filesystem reading guidance'}).count(),0);
+ assert.equal(await technical.getByRole('progressbar').getAttribute('aria-valuenow'),'50');
+ record.fresh='Current same-guest data restores the utilization bar and removes uncertain-read guidance.';
+ await page.evaluate(() => window.__readingHelp.update({reason:'agent-not-running',retained:false,os:'Windows 11'}));
+ const link=technical.getByRole('link',{name:'Filesystem reading guidance'});
+ if(width<=768)await link.tap();else {await link.focus();await page.keyboard.press('Enter');}
+ const heading=page.locator('#a-missing-reading-is-not-an-installation-diagnosis');await heading.waitFor({state:'visible'});
+ // Heading and actual renderer output, not a stand-in HTML help page.
+ assert.match(await page.locator('article').innerText(),/does not establish whether an agent is absent or stopped/);
+ assert.match(await page.locator('article').innerText(),/every\s+filesystem covered by the backup/);
+ assert.match(await page.locator('article').innerText(),/Windows or Android/);
+ record.help={url:page.url(),heading:await heading.innerText()};
+ record.input=await page.evaluate(()=>window.__input);assert.ok(record.input.some(Boolean));
+ assert.deepEqual(record.errors,[]);assert.equal(record.requests.filter(r=>!['GET','HEAD'].includes(r.method)).length,0);
+ await context.close();await browser.close();browser=null;
+ }
+ result.result='passed';result.verified_at=new Date().toISOString();
+ } catch(error) {result.error=String(error.stack||error);throw error;}
+ finally {
+ result.cleanup.browser_started = Boolean(browser) || result.cases.length > 0;
+ if(browser)await browser.close();result.cleanup.browser=true;
+ result.cleanup.server_started = Boolean(server);
+ if(server)await new Promise(resolve=>server.close(resolve));result.cleanup.server=true;
+ fs.writeFileSync(output+'/result.json',JSON.stringify(result,null,2)+'\n');
+ }
+})().catch(error=>{console.error(error);process.exitCode=1;});
diff --git a/frontend-modern/browser-tests/guest-reading-help.html b/frontend-modern/browser-tests/guest-reading-help.html
new file mode 100644
index 0000000000..5e1f41ae1e
--- /dev/null
+++ b/frontend-modern/browser-tests/guest-reading-help.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 reading help verification</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="./guest-reading-help.tsx"></script>
+ </body>
+</html>
diff --git a/frontend-modern/browser-tests/guest-reading-help.tsx b/frontend-modern/browser-tests/guest-reading-help.tsx
new file mode 100644
index 0000000000..3641283893
--- /dev/null
+++ b/frontend-modern/browser-tests/guest-reading-help.tsx
@@ -0,0 +1,92 @@
+// Actual production row, full drawer, router, documentation renderer and CSS.
+// Observations are synthetic. This sends no guest or backup command.
+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 { GuestDrawer } from '../src/components/Workloads/GuestDrawer';
+import { DarkModeContext } from '../src/contexts/appRuntime';
+import { syncAIRuntimeSettings } from '../src/stores/aiRuntimeState';
+import Docs from '../src/pages/Docs';
+import type { WorkloadGuest } from '../src/types/workloads';
+import '../src/index.css';
+
+syncAIRuntimeSettings({ discovery_enabled: false });
+function Fixture() {
+ const [reading, setReading] = createSignal({
+ reason: 'agent-not-running',
+ retained: false,
+ os: 'Windows 11',
+ });
+ const [expanded, setExpanded] = createSignal(false);
+ const guest = (): WorkloadGuest => ({
+ id: 'fixture-pve:pve-a:101',
+ vmid: 101,
+ name: 'reading-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: 5 * 1024 ** 3, usage: 50 },
+ disks: reading().retained
+ ? [
+ {
+ mountpoint: '/data',
+ total: 10 * 1024 ** 3,
+ used: 5 * 1024 ** 3,
+ usage: 50,
+ type: 'ext4',
+ },
+ ]
+ : [],
+ diskStatusReason:
+ reading().retained && reading().reason ? `prev-${reading().reason}` : reading().reason,
+ osName: reading().os,
+ networkIn: 0,
+ networkOut: 0,
+ diskRead: 0,
+ diskWrite: 0,
+ uptime: 3600,
+ template: false,
+ lastBackup: 0,
+ tags: [],
+ lastSeen: '2026-10-06T03:16:33Z',
+ });
+ (window as any).__readingHelp = { update: setReading };
+ return (
+ <main class="min-h-screen space-y-3 bg-surface p-3 text-base-content">
+ <h1>Guest reading help</h1>
+ <p class="text-xs text-muted">Synthetic observations; no guest command is sent.</p>
+ <table class="w-full table-fixed">
+ <tbody>
+ <GuestRow
+ guest={guest()}
+ visibleColumnIds={['name', 'disk']}
+ isExpanded={expanded()}
+ onClick={() => setExpanded(!expanded())}
+ workloadTableLayoutMode={window.innerWidth <= 768 ? 'phone' : 'wide'}
+ />
+ </tbody>
+ </table>
+ <Show when={expanded()}>
+ <section aria-label="Guest details">
+ <GuestDrawer guest={guest()} onClose={() => setExpanded(false)} />
+ </section>
+ </Show>
+ </main>
+ );
+}
+render(
+ () => (
+ <DarkModeContext.Provider value={() => document.documentElement.classList.contains('dark')}>
+ <Router>
+ <Route path="/docs/*docPath" component={Docs} />
+ <Route path="/*" component={Fixture} />
+ </Router>
+ </DarkModeContext.Provider>
+ ),
+ document.getElementById('root')!,
+);
diff --git a/frontend-modern/browser-verification/ecc73d9d6bae8c69.json b/frontend-modern/browser-verification/ecc73d9d6bae8c69.json
new file mode 100644
index 0000000000..8d252bc2c1
--- /dev/null
+++ b/frontend-modern/browser-verification/ecc73d9d6bae8c69.json
@@ -0,0 +1,92 @@
+{
+ "version": 1,
+ "result": "passed",
+ "base_sha": "5456291cfe9c7301dbb87407d08bf28c57540dfc",
+ "changed_paths": [
+ "frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx",
+ "frontend-modern/src/utils/workloadGuestPresentation.ts"
+ ],
+ "content_sha256": {
+ "frontend-modern/src/utils/workloadGuestPresentation.ts": "c12816c418af01e7cb3cb6834f1ad9ced1b9bd8e427122ea6b5951907328dda6",
+ "frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx": "8db75c3c3c8e1abfc116aab729116da99182a9999c08b88d68e6b810ada9b1aa"
+ },
+ "routes": [
+ "Workloads VM row and full drawer (synthetic observations)",
+ "/docs/VM_DISK_MONITORING#a-missing-reading-is-not-an-installation-diagnosis"
+ ],
+ "states": [
+ "Windows missing read",
+ "Android retained read, quantitative values last known/no utilization bar",
+ "Provider-disabled agent",
+ "Unknown reason without raw-detail disclosure",
+ "Same guest current read removes uncertainty link/restores utilization bar"
+ ],
+ "interactions": [
+ "Keyboard Enter on desktop disclosure and help link",
+ "Trusted phone row tap and help link",
+ "Follow real Docs renderer and fragment destination; no off-origin or mutating requests"
+ ],
+ "viewports": [
+ {
+ "width": 1365,
+ "height": 900
+ },
+ {
+ "width": 390,
+ "height": 900
+ }
+ ],
+ "verified_at": "2026-10-06T03:31:56.248Z",
+ "evidence": {
+ "script": "frontend-modern/browser-tests/guest-reading-help.cjs",
+ "script_sha256": "05cd1bce89467fe3918f748ea9dc1762f88bb8a7dcfc609f741a3332879804f2",
+ "playwright": "1.56.1",
+ "browsers": [
+ {
+ "name": "chromium-desktop",
+ "browser": "141.0.7390.37",
+ "width": 1365
+ },
+ {
+ "name": "webkit-phone",
+ "browser": "26.0",
+ "width": 390
+ }
+ ],
+ "captures": [
+ {
+ "file": "chromium-desktop-missing-windows.png",
+ "sha256": "a9d2ce9280f8fa889d85a9c0d18ba32391dba23a1a0bacae4df2a5c9527798fa"
+ },
+ {
+ "file": "chromium-desktop-retained-android.png",
+ "sha256": "7770bfe63ff9d85531a4fac6effe9e6c34ebec539b68d58e91e7b692534ea0e0"
+ },
+ {
+ "file": "chromium-desktop-disabled.png",
+ "sha256": "81acb12c2404d612f994f0225caa71d878548bfb3eb6490013d67577164a3346"
+ },
+ {
+ "file": "chromium-desktop-unknown.png",
+ "sha256": "b1391965160966eac56393a6c091c765cd11d362861b2efc3e897c3ef73d1787"
+ },
+ {
+ "file": "webkit-phone-missing-windows.png",
+ "sha256": "f20d99d128b525ce2e6f4b26c124adc459ba9f871b80b7661a32c9053cbd6dfa"
+ },
+ {
+ "file": "webkit-phone-retained-android.png",
+ "sha256": "0ce9f5109d283a7501e92befb3fb01cdc44ae84a35604be70a44d94f59dc7277"
+ },
+ {
+ "file": "webkit-phone-disabled.png",
+ "sha256": "fd18d29e47d084abce6087114c1a10a94a49fbb21083f7cfc6ce8b81e3919d16"
+ },
+ {
+ "file": "webkit-phone-unknown.png",
+ "sha256": "5ff1adb04abc9e80121a34fa1bf84891f9bc1fdeb878ded1d05e882445b476c9"
+ }
+ ],
+ "limits": "Static production-component preview with synthetic observations/APIs. No native guest, collector, cause, thaw, writes, restart, installed or release acceptance."
+ }
+}
diff --git a/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx b/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
index 8ad1d0c370..ff84b765dd 100644
--- a/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
+++ b/frontend-modern/src/components/Workloads/GuestDrawerOverview.tsx
@@ -12,6 +12,7 @@ import type { Alert } from '@/types/api';
import { AvailabilityProbeStatusCards } from '@/components/Infrastructure/AvailabilityProbeStatusCard';
import type { DiscoveryIdentifiedSummary } from '@/utils/discoveryPresentation';
import { formatBytes } from '@/utils/format';
+import { getShippedDocUrl } from '@/utils/docsLinks';
import type { MetricDisplayThresholds } from '@/utils/metricThresholds';
import {
getWorkloadGuestDiskStatusMessage,
@@ -226,6 +227,15 @@ export function GuestDrawerOverview(props: GuestDrawerOverviewProps) {
(props.hasFilesystemDetails && diskRows.length > 0) || diskStatusMessage
? {
label: 'Filesystems',
+ footerContent:
+ diskStatusMessage && isGuestDrawerVM(props.guest) ? (
+ <a
+ class="text-xs font-semibold underline underline-offset-2"
+ href={`${getShippedDocUrl('VM_DISK_MONITORING.md')}#a-missing-reading-is-not-an-installation-diagnosis`}
+ >
+ Filesystem reading guidance
+ </a>
+ ) : undefined,
rows: compactDetailRows([
makeDetailRow('Status', diskStatusMessage, { layout: 'stacked', wrap: true }),
...diskRows.map((disk) =>
diff --git a/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx b/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx
index 5dcbdba685..fc6e275754 100644
--- a/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx
@@ -71,14 +71,14 @@ describe('DiskList', () => {
render(() => <DiskList disks={[]} />);
expect(screen.getByText('-')).toHaveAttribute(
'title',
- 'Disk stats unavailable. Guest agent may not be installed.',
+ 'Guest filesystem usage is unavailable; the cause is unknown. Use guest-local filesystem tools. Defer setup and live probes during backups or a guest incident.',
);
});
it.each([
[
'agent-not-running',
- 'Guest agent not running. Install and start qemu-guest-agent in the VM.',
+ 'Proxmox could not query the guest agent. This does not prove it is absent or stopped. Defer setup and live probes during backups or a guest incident.',
],
[
'agent-timeout',
@@ -88,7 +88,10 @@ describe('DiskList', () => {
'permission-denied',
'Permission denied. Check that your Pulse user/token has VM.Monitor permission (PVE 8) or VM.GuestAgent.Audit permission (PVE 9).',
],
- ['agent-disabled', 'Guest agent is disabled in VM configuration. Enable it in VM Options.'],
+ [
+ 'agent-disabled',
+ 'Proxmox reports the guest agent disabled in VM configuration. Review guest-OS-specific setup outside backups or guest incidents.',
+ ],
['no-filesystems', 'No filesystems found. VM may be booting or using a Live ISO.'],
[
'special-filesystems-only',
@@ -114,7 +117,7 @@ describe('DiskList', () => {
render(() => <DiskList disks={[]} diskStatusReason="some-unknown-reason" />);
expect(screen.getByText('-')).toHaveAttribute(
'title',
- 'Disk stats unavailable. Guest agent may not be installed.',
+ 'Guest filesystem usage is unavailable; the cause is unknown. Use guest-local filesystem tools. Defer setup and live probes during backups or a guest incident.',
);
});
});
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.disk-provenance.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.disk-provenance.test.tsx
index 238a40f0df..c449d6d88e 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.disk-provenance.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerHistory.disk-provenance.test.tsx
@@ -163,7 +163,7 @@ describe('GuestDrawerHistory filesystem provenance', () => {
}
const value = guest('private transport error');
expect(getGuestDrawerDeferredMetrics(value).disk.message).toBe(
- 'Disk stats unavailable. Guest agent may not be installed.',
+ 'Guest filesystem usage is unavailable; the cause is unknown. Use guest-local filesystem tools. Defer setup and live probes during backups or a guest incident.',
);
expect(getGuestDrawerCurrentMetrics(value).disk).toBeUndefined();
});
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.agent-state.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.agent-state.test.tsx
index 3f71c0e44c..669b746599 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.agent-state.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.agent-state.test.tsx
@@ -259,3 +259,59 @@ describe('backup activity is not a confirmed VM lock', () => {
expect((value as VM).guestAgentStatus).toBe('available');
});
});
+
+describe('existing filesystem guidance follows reading uncertainty, not an install diagnosis', () => {
+ it.each([
+ ['agent-not-running', 'Windows 11'],
+ ['agent-disabled', 'Windows 11'],
+ ['future-private-error', 'Android'],
+ ])('keeps %s readings on %s truthful with a safe help destination', (reason, os) => {
+ const [value, setValue] = createSignal(guest({ diskStatusReason: reason }));
+ render(() => <GuestDrawerOverview {...overviewProps(value())} guestOsSummary={os} />);
+ expect(screen.getByRole('link', { name: 'Filesystem reading guidance' })).toHaveAttribute(
+ 'href',
+ '/docs/VM_DISK_MONITORING#a-missing-reading-is-not-an-installation-diagnosis',
+ );
+ expect(screen.getByTestId('guest-technical-details').textContent).not.toMatch(
+ /Install and start|Enable it in VM Options|qemu-guest-agent|future-private-error/,
+ );
+ setValue({
+ ...value(),
+ diskStatusReason: `prev-${reason}`,
+ disks: [{ mountpoint: '/data', total: 1024, used: 512, usage: 50 }],
+ });
+ expect(screen.getByText(/Using last known disk stats/)).toBeVisible();
+ expect(screen.getByRole('link', { name: 'Filesystem reading guidance' })).toBeVisible();
+ setValue({
+ ...value(),
+ diskStatusReason: '',
+ disks: [{ mountpoint: '/data', total: 1024, used: 256, usage: 25 }],
+ });
+ expect(
+ screen.queryByRole('link', { name: 'Filesystem reading guidance' }),
+ ).not.toBeInTheDocument();
+ });
+
+ it('does not direct an independent LXC read to QEMU setup', () => {
+ render(() => (
+ <GuestDrawerOverview
+ {...overviewProps(
+ guest({
+ type: 'lxc',
+ telemetryAvailability: {
+ cpu: true,
+ memory: true,
+ disk: false,
+ networkIO: true,
+ diskIO: true,
+ uptime: true,
+ },
+ }),
+ )}
+ />
+ ));
+ expect(
+ screen.queryByRole('link', { name: 'Filesystem reading guidance' }),
+ ).not.toBeInTheDocument();
+ });
+});
diff --git a/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts b/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts
index 7edf413296..30a280488a 100644
--- a/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts
+++ b/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts
@@ -21,6 +21,21 @@ describe('workloadGuestPresentation', () => {
},
);
+ it.each(['agent-not-running', 'agent-disabled', 'future-private-error', undefined])(
+ 'keeps %s out of installation, activation and guessed OS advice',
+ (reason) => {
+ for (const current of [reason, `prev-${reason ?? 'unknown'}`]) {
+ const text = getWorkloadGuestDiskStatusMessage(current);
+ expect(text).not.toMatch(
+ /Install and start|Enable it in VM Options|may not be installed|qemu-guest-agent/,
+ );
+ expect(text).toMatch(/backup/);
+ expect(text).toMatch(/guest incident/);
+ expect(text).not.toContain('future-private-error');
+ }
+ },
+ );
+
it('returns canonical guest backup status presentation', () => {
expect(getWorkloadsGuestBackupStatusPresentation('fresh')).toEqual({
color: 'text-green-600 dark:text-green-400',
@@ -98,7 +113,7 @@ describe('workloadGuestPresentation', () => {
'No filesystems found. VM may be booting or using a Live ISO.',
);
expect(getWorkloadGuestDiskStatusMessage()).toBe(
- 'Disk stats unavailable. Guest agent may not be installed.',
+ 'Guest filesystem usage is unavailable; the cause is unknown. Use guest-local filesystem tools. Defer setup and live probes during backups or a guest incident.',
);
expect(getWorkloadGuestDiskStatusMessage('prev-no-filesystems')).toBe(
'Using last known disk stats. No filesystems found. VM may be booting or using a Live ISO.',
diff --git a/frontend-modern/src/utils/workloadGuestPresentation.ts b/frontend-modern/src/utils/workloadGuestPresentation.ts
index 36fbe7d28f..edc129d6b6 100644
--- a/frontend-modern/src/utils/workloadGuestPresentation.ts
+++ b/frontend-modern/src/utils/workloadGuestPresentation.ts
@@ -106,7 +106,7 @@ export function getWorkloadGuestDiskStatusMessage(reason?: string): string {
const message = (() => {
switch (normalizedReason) {
case 'agent-not-running':
- return 'Guest agent not running. Install and start qemu-guest-agent in the VM.';
+ return 'Proxmox could not query the guest agent. This does not prove it is absent or stopped. Defer setup and live probes during backups or a guest incident.';
case 'agent-timeout':
return 'Guest request timed out. Completion is uncertain. Do not restart the guest agent during a backup.';
case 'vm-locked':
@@ -126,7 +126,7 @@ export function getWorkloadGuestDiskStatusMessage(reason?: string): string {
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':
- return 'Guest agent is disabled in VM configuration. Enable it in VM Options.';
+ return 'Proxmox reports the guest agent disabled in VM configuration. Review guest-OS-specific setup outside backups or guest incidents.';
case 'no-filesystems':
return 'No filesystems found. VM may be booting or using a Live ISO.';
case 'special-filesystems-only':
@@ -140,7 +140,7 @@ export function getWorkloadGuestDiskStatusMessage(reason?: string): string {
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.';
+ return 'Guest filesystem usage is unavailable; the cause is unknown. Use guest-local filesystem tools. Defer setup and live probes during backups or a guest incident.';
}
})();