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.

Clarify PBS verification and protection evidence in help

pulse-triage[bot]3573abbf0eca
diff --git a/docs/PBS.md b/docs/PBS.md
index bfb61548c9..72f2318adf 100644
--- a/docs/PBS.md
+++ b/docs/PBS.md
@@ -347,7 +347,8 @@ backup or working protection from the strip alone.
| --- | --- |
| **With PBS snapshots** or a matching backup row | That Pulse's protection assessment received the same subject-linked backup evidence. A similar name or guest ID alone is not identity proof. |
| **Verified** on a PBS backup | That every backup is current, every covered disk is included, or the guest recovered after the backup. Verification is evidence about that backup, not a successful restore. |
-| **Protected**, **Attention**, **Unprotected** or **Unknown** | An independent check that backups are restorable. These are Pulse's assessment from the backup evidence it can read, not instructions to change backups. |
+| **Protected** in a restore point's **State** | That this point is verified. This displays the backup's protected flag before its verification state; it is not the workload's protection assessment. |
+| **Protected**, **Attention**, **Unprotected** or **Unknown** on the workload | An independent check that backups are restorable. These are Pulse's assessment from the backup evidence it can read, not instructions to change backups. |
Check one affected guest without changing its setup:
@@ -359,14 +360,27 @@ Check one affected guest without changing its setup:
2. Compare the listed backup with the existing record in PBS: server,
datastore, namespace (including root), guest type/ID and backup time.
Independent PVE installations can reuse an ID; confirm the owning
- installation too. A **guest snapshot** is not a PBS backup. Check the
- existing backup task and verification result in PBS, not just the last
- time Pulse refreshed.
+ installation too. Under **Restore evidence**, choose the newest point whose
+ **Source** is **PBS**, and read its **Created** time and **State**. Hover the
+ Created age for its absolute timestamp; if unavailable, keep the time
+ unknown. A relative age or Pulse's refresh time is not a matching backup
+ timestamp. A **guest snapshot** is not a PBS backup. Check the existing
+ backup task and verification result for that same point in PBS.
3. If the records still disagree, report the Pulse version, one guest's
protection explanation, PBS Job/History/Access values and the matching
- backup's time and verification result. Use consistent placeholders for
- private server, datastore, namespace and guest identities. Do not share
- tokens, full API responses, HAR exports, or screenshots with secrets.
+ point's Created time, State and PBS verification result. Use consistent
+ placeholders for private server, datastore, namespace and guest identities.
+ Do not share tokens, full API responses, HAR exports, or screenshots with secrets.
+
+**If PBS says verified but Pulse disagrees:** an older or absent point in Pulse
+is an inventory discrepancy, before comparing verification. **Unverified** on
+the matching point means Pulse has no successful verification evidence for it;
+it does not prove that PBS's verification job failed. **Verified** with a
+workload still needing attention is a separate assessment disagreement: retain
+its explanation and Provider evidence. A **Protected** point leaves its
+verification state unknown from that label alone. **Job OK** is not an
+individual point's verification result. Use the records already available,
+without running Diagnostics or another verification just to compare them.
Do not delete backups, clear History, change retention or freshness settings,
recreate tokens/connections, restart or downgrade Pulse, or run a new backup,
diff --git a/frontend-modern/browser-tests/pbs-verification-help.cjs b/frontend-modern/browser-tests/pbs-verification-help.cjs
new file mode 100644
index 0000000000..d5f4dfcc21
--- /dev/null
+++ b/frontend-modern/browser-tests/pbs-verification-help.cjs
@@ -0,0 +1,130 @@
+// Read-only help acceptance through the production Docs page, router and CSS.
+// No PBS connection, diagnostic run or verification job is involved.
+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');
+
+(async () => {
+ const root = '/workspace/frontend-modern';
+ const artifacts = path.join(root, 'node_modules', 'pbs-verification-help-browser');
+ const fragment = 'backups-are-visible-but-coverage-says-unprotected';
+ const guide = fs.readFileSync(path.join(root, 'public/docs/PBS.md'));
+ assert.deepEqual(guide, fs.readFileSync('/workspace/docs/PBS.md'));
+ process.chdir(root);
+ fs.mkdirSync(artifacts, { recursive: true });
+ 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(root, 'node_modules', '.vite-pbs-verification-help'),
+ server: { host: '127.0.0.1', port: 5256, strictPort: true },
+ optimizeDeps: { noDiscovery: true, include: [] },
+ });
+ const results = [];
+ let browser;
+ try {
+ await server.listen();
+ for (const [engine, width, dark] of [['chromium', 1280, false], ['webkit', 390, true]]) {
+ browser = await { chromium, webkit }[engine].launch(engine === 'chromium'
+ ? { headless: true, channel: 'chromium', args: ['--no-sandbox'] }
+ : { headless: true });
+ const page = await browser.newPage({ viewport: { width, height: 1000 },
+ ...(engine === 'webkit' ? { isMobile: true, hasTouch: true } : {}) });
+ const errors = [], backendRequests = [], mutations = [], servedDocs = [];
+ page.on('pageerror', (error) => errors.push(error.message));
+ page.on('console', (message) => {
+ if (message.type() === 'error') errors.push(message.text());
+ });
+ page.on('request', (request) => {
+ if (!['GET', 'HEAD'].includes(request.method())) mutations.push(request.method());
+ });
+ page.on('response', async (response) => {
+ if (new URL(response.url()).pathname === '/docs/PBS.md') {
+ const bytes = await response.body();
+ servedDocs.push({ status: response.status(),
+ sha256: crypto.createHash('sha256').update(bytes).digest('hex') });
+ }
+ });
+ await page.route('**/api/**', async (route) => {
+ backendRequests.push(new URL(route.request().url()).pathname);
+ await route.abort();
+ });
+ await page.goto('http://127.0.0.1:5256/browser-tests/docs-fragment-navigation.html', {
+ waitUntil: 'domcontentloaded', timeout: 60000,
+ });
+ if (dark) await page.evaluate(() => document.documentElement.classList.add('dark'));
+ await page.evaluate(() => {
+ history.pushState({}, '', '/docs/RECOVERY#missing-or-inconsistent-evidence');
+ dispatchEvent(new PopStateEvent('popstate'));
+ });
+ const entry = page.locator(`a[href="/docs/PBS#${fragment}"]`);
+ await entry.waitFor({ state: 'visible' });
+ assert.equal(await entry.innerText(), 'backup health checks');
+ await entry.focus();
+ await page.keyboard.press('Enter');
+ await page.waitForFunction((id) => {
+ const target = document.getElementById(id);
+ const rect = target?.getBoundingClientRect();
+ return target && document.activeElement === target && rect.top >= 0 && rect.top < innerHeight;
+ }, fragment);
+ const heading = page.locator(`#${fragment}`);
+ const section = await page.evaluate((id) => {
+ const target = document.getElementById(id);
+ const nodes = [];
+ for (let node = target.nextElementSibling; node && !/^H[1-3]$/.test(node.tagName); node = node.nextElementSibling) {
+ nodes.push(node.textContent);
+ }
+ return nodes.join(' ').replace(/\s+/g, ' ');
+ }, fragment);
+ for (const phrase of [
+ "Protected in a restore point's State", "not the workload's protection assessment",
+ 'choose the newest point whose Source is PBS', 'Created time and State',
+ 'Hover the Created age for its absolute timestamp', 'if unavailable, keep the time unknown',
+ 'an older or absent point in Pulse is an inventory discrepancy',
+ "does not prove that PBS's verification job failed",
+ 'Verified with a workload still needing attention is a separate assessment disagreement',
+ 'Protected point leaves its verification state unknown from that label alone',
+ "Job OK is not an individual point's verification result",
+ 'without running Diagnostics or another verification',
+ 'Do not delete backups, clear History, change retention or freshness settings',
+ ]) assert.ok(section.includes(phrase), `${engine}: ${phrase}`);
+ assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1));
+ await page.waitForFunction(() => document.getAnimations().length === 0);
+ await page.screenshot({ path: path.join(artifacts, `${engine}-evidence.png`) });
+ const comparison = page.locator('p').filter({ hasText: 'If PBS says verified but Pulse disagrees:' });
+ await comparison.scrollIntoViewIfNeeded();
+ await page.screenshot({ path: path.join(artifacts, `${engine}-comparison.png`) });
+ const safety = page.getByRole('link', { name: 'Backup safety', exact: true });
+ await safety.focus();
+ await page.keyboard.press('Enter');
+ await page.waitForFunction(() => document.activeElement?.id === 'backup-safety');
+ assert.ok(await page.locator('#backup-safety').isVisible());
+ assert.ok(await heading.count() === 0);
+ assert.deepEqual(backendRequests, []);
+ assert.deepEqual(mutations, []);
+ assert.deepEqual(errors, []);
+ assert.ok(servedDocs.length >= 1);
+ for (const served of servedDocs) {
+ assert.equal(served.status, 200);
+ assert.equal(served.sha256, crypto.createHash('sha256').update(guide).digest('hex'));
+ }
+ results.push({ engine, browserVersion: browser.version(), width, dark,
+ helpRoute: `/docs/PBS#${fragment}`, sourceMatchedResponses: servedDocs,
+ recoveryEntryKeyboardNavigation: true, visibleFocusedHeading: true,
+ backupSafetyKeyboardNavigation: true, noHorizontalPageOverflow: true,
+ backendRequests, mutations, errors });
+ await browser.close();
+ browser = undefined;
+ }
+ } finally {
+ if (browser) await browser.close();
+ await server.close();
+ }
+ const result = { result: 'passed', playwright: require('playwright/package.json').version,
+ docSha256: crypto.createHash('sha256').update(guide).digest('hex'), results,
+ browserAndServerClosed: true,
+ scope: 'Production documentation renderer, page, router, CSS and exact shipped Markdown; no native PBS, full application, diagnosis or release acceptance.' };
+ fs.writeFileSync(path.join(artifacts, 'result.json'), JSON.stringify(result, null, 2) + '\n');
+ console.log(JSON.stringify(result));
+})().catch((error) => { console.error(error); process.exitCode = 1; });
diff --git a/frontend-modern/public/docs/PBS.md b/frontend-modern/public/docs/PBS.md
index bfb61548c9..72f2318adf 100644
--- a/frontend-modern/public/docs/PBS.md
+++ b/frontend-modern/public/docs/PBS.md
@@ -347,7 +347,8 @@ backup or working protection from the strip alone.
| --- | --- |
| **With PBS snapshots** or a matching backup row | That Pulse's protection assessment received the same subject-linked backup evidence. A similar name or guest ID alone is not identity proof. |
| **Verified** on a PBS backup | That every backup is current, every covered disk is included, or the guest recovered after the backup. Verification is evidence about that backup, not a successful restore. |
-| **Protected**, **Attention**, **Unprotected** or **Unknown** | An independent check that backups are restorable. These are Pulse's assessment from the backup evidence it can read, not instructions to change backups. |
+| **Protected** in a restore point's **State** | That this point is verified. This displays the backup's protected flag before its verification state; it is not the workload's protection assessment. |
+| **Protected**, **Attention**, **Unprotected** or **Unknown** on the workload | An independent check that backups are restorable. These are Pulse's assessment from the backup evidence it can read, not instructions to change backups. |
Check one affected guest without changing its setup:
@@ -359,14 +360,27 @@ Check one affected guest without changing its setup:
2. Compare the listed backup with the existing record in PBS: server,
datastore, namespace (including root), guest type/ID and backup time.
Independent PVE installations can reuse an ID; confirm the owning
- installation too. A **guest snapshot** is not a PBS backup. Check the
- existing backup task and verification result in PBS, not just the last
- time Pulse refreshed.
+ installation too. Under **Restore evidence**, choose the newest point whose
+ **Source** is **PBS**, and read its **Created** time and **State**. Hover the
+ Created age for its absolute timestamp; if unavailable, keep the time
+ unknown. A relative age or Pulse's refresh time is not a matching backup
+ timestamp. A **guest snapshot** is not a PBS backup. Check the existing
+ backup task and verification result for that same point in PBS.
3. If the records still disagree, report the Pulse version, one guest's
protection explanation, PBS Job/History/Access values and the matching
- backup's time and verification result. Use consistent placeholders for
- private server, datastore, namespace and guest identities. Do not share
- tokens, full API responses, HAR exports, or screenshots with secrets.
+ point's Created time, State and PBS verification result. Use consistent
+ placeholders for private server, datastore, namespace and guest identities.
+ Do not share tokens, full API responses, HAR exports, or screenshots with secrets.
+
+**If PBS says verified but Pulse disagrees:** an older or absent point in Pulse
+is an inventory discrepancy, before comparing verification. **Unverified** on
+the matching point means Pulse has no successful verification evidence for it;
+it does not prove that PBS's verification job failed. **Verified** with a
+workload still needing attention is a separate assessment disagreement: retain
+its explanation and Provider evidence. A **Protected** point leaves its
+verification state unknown from that label alone. **Job OK** is not an
+individual point's verification result. Use the records already available,
+without running Diagnostics or another verification just to compare them.
Do not delete backups, clear History, change retention or freshness settings,
recreate tokens/connections, restart or downgrade Pulse, or run a new backup,
diff --git a/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts b/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts
index b51ac25a9f..c71dc97ed2 100644
--- a/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts
+++ b/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts
@@ -3,6 +3,8 @@ import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { describe, expect, it } from 'vitest';
import { renderDocMarkdown } from '@/features/docs/docMarkdown';
+import type { RecoverableArtifact } from '@/features/proxmox/proxmoxBackupRecoveryModel';
+import { artifactStateLabel } from '@/features/proxmox/proxmoxBackupsTableShared';
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
const read = (file: string) => readFileSync(path.join(root, file), 'utf8');
@@ -24,12 +26,14 @@ describe('PBS protection disagreement help', () => {
render(guide, 'PBS').querySelector('#backups-are-visible-but-coverage-says-unprotected'),
).not.toBeNull();
const rows = [...article().querySelectorAll('tbody tr')].map((row) => row.textContent);
- expect(rows).toHaveLength(3);
+ expect(rows).toHaveLength(4);
expect(rows[0]).toContain('subject-linked backup evidence');
expect(rows[0]).toContain('not identity proof');
expect(rows[1]).toContain('not a successful restore');
expect(rows[1]).toContain('every covered disk');
- expect(rows[2]).toContain('not instructions to change backups');
+ expect(rows[2]).toContain("restore point's State");
+ expect(rows[2]).toContain('not the workload');
+ expect(rows[3]).toContain('not instructions to change backups');
expect(text()).toContain("PBS's own backup and verification records");
expect(text()).toContain('do not assume either a failed backup or working protection');
});
@@ -47,6 +51,11 @@ describe('PBS protection disagreement help', () => {
'server, datastore, namespace (including root), guest type/ID and backup time',
);
expect(steps[1]).toContain('confirm the owning installation');
+ expect(steps[1]).toContain('choose the newest point whose Source is PBS');
+ expect(steps[1]).toContain('Created time and State');
+ expect(steps[1]).toContain('Hover the Created age for its absolute timestamp');
+ expect(steps[1]).toContain('if unavailable, keep the time unknown');
+ expect(steps[1]).toContain('refresh time is not a matching backup timestamp');
expect(steps[1]).toContain('guest snapshot is not a PBS backup');
expect(steps[2]).toContain('protection explanation');
expect(article().querySelector('pre')).toBeNull();
@@ -56,6 +65,49 @@ describe('PBS protection disagreement help', () => {
expect(coverage).toContain('Access {evidenceQualityLabel(provider.permissions)}');
});
+ it('distinguishes the available observations without claiming a PBS cause or verification failure', () => {
+ expect(text()).toContain('an older or absent point in Pulse is an inventory discrepancy');
+ expect(text()).toContain(
+ 'Unverified on the matching point means Pulse has no successful verification evidence',
+ );
+ expect(text()).toContain("does not prove that PBS's verification job failed");
+ expect(text()).toContain(
+ 'Verified with a workload still needing attention is a separate assessment disagreement',
+ );
+ expect(text()).toContain('retain its explanation and Provider evidence');
+ expect(text()).toContain("Job OK is not an individual point's verification result");
+ expect(text()).toContain('without running Diagnostics or another verification');
+ });
+
+ it('keeps the Protected caution truthful for every hidden verification value', () => {
+ const point: RecoverableArtifact = {
+ id: 'fixture-point',
+ nativeId: 'fixture-point',
+ sourceKind: 'pbs',
+ sourceLabel: 'PBS',
+ workload: {
+ key: 'fixture-guest',
+ type: 'vm',
+ typeLabel: 'VM',
+ vmid: '100',
+ label: 'Fixture VM',
+ },
+ createdAt: '2026-10-12T02:00:00Z',
+ location: 'fixture / (root)',
+ detail: '',
+ protected: true,
+ };
+ for (const verified of [true, false, undefined]) {
+ expect(artifactStateLabel({ ...point, verified })).toBe('Protected');
+ }
+ expect(artifactStateLabel({ ...point, protected: false, verified: true })).toBe('Verified');
+ expect(artifactStateLabel({ ...point, protected: false, verified: false })).toBe('Unverified');
+ expect(text()).toContain(
+ 'Protected point leaves its verification state unknown from that label alone',
+ );
+ expect(text()).toContain("displays the backup's protected flag before its verification state");
+ });
+
it('prevents destructive diagnostics and an assumed freshness-policy cause', () => {
expect(text()).toContain(
'Do not delete backups, clear History, change retention or freshness settings',