Keep Windows guest-read diagnosis separate from Linux file permissions

Existing Windows restart reports supply unsupported meminfo reads beside working guest filesystems. Explain the distinction and existing safe views without new probes, agent churn, wider permissions or an unverified recovery claim.

Contract-Neutral: Existing documentation and rendered-guide regression coverage only; no monitoring, permission, API or runtime contract change.
Change-source: pulse-maintainer

docs/VM_DISK_MONITORING.md

@@ -303,7 +303,13 @@ guest incidents. Table filters and alert suppression do not stop API polling.
 | Collection | Proxmox VE 9+ | Proxmox VE 8 |
 | --- | --- | --- |
 | Filesystem usage and guest information | `VM.GuestAgent.Audit` | `VM.Monitor` |
-| Reading guest memory via `/proc/meminfo` | Also `VM.GuestAgent.FileRead` | `VM.Monitor` |
+| Reading Linux guest memory via `/proc/meminfo` | Also `VM.GuestAgent.FileRead` | `VM.Monitor` |
+
+Windows has no `/proc/meminfo`. A failure reading that Linux path is not evidence
+that Windows filesystem collection needs `VM.GuestAgent.FileRead` or that the
+guest agent is stopped. Keep memory-file access separate from filesystem access;
+see [Windows readings after a Pulse restart](#windows-readings-after-a-pulse-restart)
+before changing permissions or services.
 
 Do not grant Administrator or guest execution/write permissions to diagnose a
 missing disk value. The built-in `PVEAuditor` role cannot be modified; use a
@@ -377,6 +383,31 @@ supported QEMU Guest Agent. The Linux package name is not a Windows or Android
 installation instruction. If no supported agent is available, use the guest's
 own filesystem tools; missing Pulse usage is unknown, not zero.
 
+### Windows readings after a Pulse restart
+
+If Windows disks become **Unavailable** after Pulse restarts, a
+**guest reads paused** or `agent-cooldown` explanation describes Pulse's deferred
+collection, not a stopped Windows service or proof that the guest is frozen.
+Windows does not provide the Linux `/proc/meminfo` file. An existing HTTP 500
+for that file alone does not establish why filesystem reads are missing; do not
+grant more privileges or change the guest's file-read policy to make it succeed.
+
+Keep the original sequence: which readings worked before the Pulse restart,
+the existing error and times, and whether normal Windows use remained responsive.
+A later working reading from a Pulse Agent is a different collection path, not
+confirmation that QEMU Guest Agent reads recovered. For capacity decisions, use
+Windows' own filesystem view or
+[current readings from an already installed Pulse Agent](#use-existing-machines-readings-without-changing-the-guest).
+Keep the same guest identity, filesystem and observation time with the comparison.
+
+Do not repeat the restart, run Diagnostics or guest-agent probes, clear a
+cooldown, or install, remove or restart either agent just to diagnose this state.
+If those observations are already in your report, do not collect them again.
+An expired cooldown or a number returning is not proof that every volume or
+History recovered. If the workload is unresponsive or a backup is involved,
+[Backup safety](#backup-safety) takes precedence; these interim views do not
+prove thaw or successful writes.
+
 ### Use existing Machines readings without changing the guest
 
 The Proxmox disk view and an in-guest **Pulse Agent** use different collection

frontend-modern/public/docs/VM_DISK_MONITORING.md

@@ -303,7 +303,13 @@ guest incidents. Table filters and alert suppression do not stop API polling.
 | Collection | Proxmox VE 9+ | Proxmox VE 8 |
 | --- | --- | --- |
 | Filesystem usage and guest information | `VM.GuestAgent.Audit` | `VM.Monitor` |
-| Reading guest memory via `/proc/meminfo` | Also `VM.GuestAgent.FileRead` | `VM.Monitor` |
+| Reading Linux guest memory via `/proc/meminfo` | Also `VM.GuestAgent.FileRead` | `VM.Monitor` |
+
+Windows has no `/proc/meminfo`. A failure reading that Linux path is not evidence
+that Windows filesystem collection needs `VM.GuestAgent.FileRead` or that the
+guest agent is stopped. Keep memory-file access separate from filesystem access;
+see [Windows readings after a Pulse restart](#windows-readings-after-a-pulse-restart)
+before changing permissions or services.
 
 Do not grant Administrator or guest execution/write permissions to diagnose a
 missing disk value. The built-in `PVEAuditor` role cannot be modified; use a
@@ -377,6 +383,31 @@ supported QEMU Guest Agent. The Linux package name is not a Windows or Android
 installation instruction. If no supported agent is available, use the guest's
 own filesystem tools; missing Pulse usage is unknown, not zero.
 
+### Windows readings after a Pulse restart
+
+If Windows disks become **Unavailable** after Pulse restarts, a
+**guest reads paused** or `agent-cooldown` explanation describes Pulse's deferred
+collection, not a stopped Windows service or proof that the guest is frozen.
+Windows does not provide the Linux `/proc/meminfo` file. An existing HTTP 500
+for that file alone does not establish why filesystem reads are missing; do not
+grant more privileges or change the guest's file-read policy to make it succeed.
+
+Keep the original sequence: which readings worked before the Pulse restart,
+the existing error and times, and whether normal Windows use remained responsive.
+A later working reading from a Pulse Agent is a different collection path, not
+confirmation that QEMU Guest Agent reads recovered. For capacity decisions, use
+Windows' own filesystem view or
+[current readings from an already installed Pulse Agent](#use-existing-machines-readings-without-changing-the-guest).
+Keep the same guest identity, filesystem and observation time with the comparison.
+
+Do not repeat the restart, run Diagnostics or guest-agent probes, clear a
+cooldown, or install, remove or restart either agent just to diagnose this state.
+If those observations are already in your report, do not collect them again.
+An expired cooldown or a number returning is not proof that every volume or
+History recovered. If the workload is unresponsive or a backup is involved,
+[Backup safety](#backup-safety) takes precedence; these interim views do not
+prove thaw or successful writes.
+
 ### Use existing Machines readings without changing the guest
 
 The Proxmox disk view and an in-guest **Pulse Agent** use different collection

frontend-modern/src/features/docs/__tests__/proxmoxPermissionsGuide.test.ts

@@ -121,4 +121,49 @@ describe('shipped Proxmox permission diagnosis', () => {
       );
     }
   });
+
+  it('keeps Linux memory-file privileges separate from Windows filesystem access', () => {
+    const article = renderGuide('VM_DISK_MONITORING');
+    const row = [...article.querySelectorAll('tr')].find((element) =>
+      prose(element as HTMLElement).startsWith('Reading Linux guest memory'),
+    );
+    expect(prose(row as HTMLElement)).toContain('/proc/meminfo');
+    expect(prose(row as HTMLElement)).toContain('VM.GuestAgent.FileRead');
+    expect(prose(article)).toContain('Windows has no /proc/meminfo');
+    expect(prose(article)).toContain(
+      'not evidence that Windows filesystem collection needs VM.GuestAgent.FileRead',
+    );
+    expect(
+      article.querySelector('a[href="/docs/VM_DISK_MONITORING#windows-readings-after-a-pulse-restart"]'),
+    ).not.toBeNull();
+    expect(article.querySelector('#windows-readings-after-a-pulse-restart')).not.toBeNull();
+  });
+
+  it('explains the Windows restart state without diagnosing agent failure or recovery', () => {
+    const content = section(renderGuide('VM_DISK_MONITORING'), 'windows-readings-after-a-pulse-restart');
+    const text = prose(content);
+    expect(text).toContain('agent-cooldown');
+    expect(text).toContain("describes Pulse's deferred collection");
+    expect(text).toContain('not a stopped Windows service or proof that the guest is frozen');
+    expect(text).toContain('An existing HTTP 500 for that file alone does not establish why');
+    expect(text).toContain('not confirmation that QEMU Guest Agent reads recovered');
+    expect(text).toContain('not proof that every volume or History recovered');
+    expect(content.querySelector('pre')).toBeNull();
+  });
+
+  it('offers existing Windows or agent readings without new probes, privilege or state churn', () => {
+    const content = section(renderGuide('VM_DISK_MONITORING'), 'windows-readings-after-a-pulse-restart');
+    const text = prose(content);
+    expect(text).toContain("Windows' own filesystem view");
+    expect(text).toContain('same guest identity, filesystem and observation time');
+    expect(text).toContain('do not grant more privileges');
+    expect(text).toContain('Do not repeat the restart, run Diagnostics or guest-agent probes');
+    expect(text).toContain('clear a cooldown, or install, remove or restart either agent');
+    expect(text).toContain('do not collect them again');
+    expect(text).toContain('these interim views do not prove thaw or successful writes');
+    for (const fragment of ['use-existing-machines-readings-without-changing-the-guest', 'backup-safety']) {
+      expect(content.querySelector(`a[href="/docs/VM_DISK_MONITORING#${fragment}"]`)).not.toBeNull();
+      expect(renderGuide('VM_DISK_MONITORING').querySelector(`#${fragment}`)).not.toBeNull();
+    }
+  });
 });