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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Separate refused Docker plans from uncertain workload updates in help
pulse-triage[bot]b5b92e1151d4
diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex 7d435a312e..05414793dd 100644--- a/docs/DOCKER.md+++ b/docs/DOCKER.md@@ -301,7 +301,45 @@ returning to the old image alone does not undo a data migration.### Check a failed or pending workload update-A failed banner or missing receipt does not tell you whether the update ran.+Start with the **existing error and action stage**, not another click on Update:++- **Planning refused:** “Docker / Podman command agent is not connected” on the+ planning request means Pulse could not find a matching admitted live command+ channel and refused that plan before dispatch. The planning response can be+ HTTP 409, but 409 alone has other causes. This does **not** establish what an+ earlier action did; use the command-channel checks below for this refusal.+- **Action sent, receipt pending:** “The action was sent once” or a pending+ durable receipt means the outcome is uncertain, even beside a failed banner.+ Use the existing receipt and workload-state checks below, without dispatching+ another update.+- **Stage unknown:** a failed banner alone does not tell you whether the update+ ran. Retain that uncertainty; do not assume nothing changed or repeat the+ action to find out. Use existing observations where safe.++#### Command agent is not connected++Open **Settings → Infrastructure → Agent Doctor**, expand the **affected Docker+host**, and inspect the existing **Privilege** wording. This is the agent for+the workload, not necessarily the host running Pulse. `commands monitoring-only`+describes a local command ceiling; `commands command-capable` and `credential+grants exec` describe local authority and credential scope, **not a connected+session**. A missing Privilege line is unknown, not proof that commands are off.+Fresh monitoring or an available image update does not prove command transport.++For a command-capable host, follow the existing+[command-channel connection and admission checks](UNIFIED_AGENT.md#commands-enabled-but-remote-control-blocked).+A monitoring-only setup is intentional when you only need readings and update+detection; do not enable commands, broaden a token, change Proxmox permissions+or loosen TLS merely to diagnose the refusal. Keep saved identity and credentials+intact; do not reinstall or retry the workload update as a connection test.++For help, retain the original error, time and stage plus the existing command+authority/scope wording, or say it is unavailable. Share only those distinctions,+not a full Agent Doctor report, token hint, agent ID or service configuration.+The connection refusal does not settle an earlier missing receipt.++#### Action was sent or its outcome is unknown+Use your normal Docker administration shell **on the host running the affectedcontainer**, not a shell inside Pulse or on an unrelated Proxmox host. Use thesame Docker context as that workload; do not change socket permissions or enablediff --git a/frontend-modern/browser-tests/docker-update-guidance.cjs b/frontend-modern/browser-tests/docker-update-guidance.cjsindex bfddf3c4ae..a820270495 100644--- a/frontend-modern/browser-tests/docker-update-guidance.cjs+++ b/frontend-modern/browser-tests/docker-update-guidance.cjs@@ -2,6 +2,7 @@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 () => {@@ -98,6 +99,61 @@ const { chromium, webkit } = require('playwright');.textContent(),'▶️ Container Lifecycle Actions',);++ // Follow the existing troubleshooting entry, then distinguish a refused+ // plan from an already-sent action before reaching any shell recipe.+ await page.evaluate(() => {+ history.pushState({}, '', '/docs/TROUBLESHOOTING#choose-the-affected-workflow');+ dispatchEvent(new PopStateEvent('popstate'));+ });+ await waitForHeading('choose-the-affected-workflow');+ await page.getByRole('link', { name: 'Docker workload update checks', exact: true }).focus();+ await page.keyboard.press('Enter');+ await waitForHeading('check-a-failed-or-pending-workload-update');+ assert.ok(page.url().endsWith('/docs/DOCKER#check-a-failed-or-pending-workload-update'));+ const stages = page.locator('#check-a-failed-or-pending-workload-update + p + ul');+ assert.equal(await stages.locator('li').count(), 3);+ const stageText = (await stages.innerText()).replace(/\s+/g, ' ');+ for (const phrase of [+ 'refused that plan before dispatch',+ '409 alone has other causes',+ 'does not establish what an earlier action did',+ 'outcome is uncertain, even beside a failed banner',+ 'do not assume nothing changed',+ ])+ assert.ok(stageText.includes(phrase), phrase);+ assert.ok(+ await page.evaluate(() => {+ const commands = document.getElementById('command-agent-is-not-connected');+ const uncertain = document.getElementById('action-was-sent-or-its-outcome-is-unknown');+ const firstCode = uncertain.nextElementSibling.nextElementSibling.nextElementSibling;+ return (+ commands.compareDocumentPosition(uncertain) & Node.DOCUMENT_POSITION_FOLLOWING &&+ firstCode.tagName === 'PRE'+ );+ }),+ );+ await page.screenshot({ path: path.join(artifacts, `${engine}-update-stages.png`) });+ await page.evaluate(() => {+ history.pushState({}, '', '/docs/DOCKER#command-agent-is-not-connected');+ dispatchEvent(new PopStateEvent('popstate'));+ });+ await waitForHeading('command-agent-is-not-connected');+ await page.screenshot({ path: path.join(artifacts, `${engine}-authority.png`) });+ await page+ .getByRole('link', {+ name: 'command-channel connection and admission checks',+ exact: true,+ })+ .focus();+ await page.keyboard.press('Enter');+ await waitForHeading('commands-enabled-but-remote-control-blocked');+ assert.ok(+ page.url().endsWith('/docs/UNIFIED_AGENT#commands-enabled-but-remote-control-blocked'),+ );+ const connectionGuide = (await page.locator('article').innerText()).replace(/\s+/g, ' ');+ assert.ok(connectionGuide.includes('not a connected session'));+ assert.ok(connectionGuide.includes('Keep saved identity and credentials intact'));assert.deepEqual(errors, []);results.push({engine,@@ -106,6 +162,9 @@ const { chromium, webkit } = require('playwright');dark,precautionsAndLimitsRendered: true,keyboardRequirementsLink: true,+ refusedSentUnknownStages: true,+ commandGuidanceBeforeShellChecks: true,+ keyboardTroubleshootingAndCommandChannelLinks: true,headingsFocusedAndVisible: true,noHorizontalOverflow: true,errors,@@ -117,6 +176,15 @@ const { chromium, webkit } = require('playwright');result: 'passed',playwright: require('playwright/package.json').version,scope: 'shipped help rendering and keyboard navigation, not native updates or rollback',+ documents: Object.fromEntries(+ ['DOCKER', 'UNIFIED_AGENT', 'TROUBLESHOOTING'].map((name) => [+ name,+ crypto+ .createHash('sha256')+ .update(fs.readFileSync(path.join(root, 'public/docs', `${name}.md`)))+ .digest('hex'),+ ]),+ ),results,};fs.writeFileSync(path.join(artifacts, 'result.json'), JSON.stringify(result, null, 2) + '\n');diff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.mdindex 7d435a312e..05414793dd 100644--- a/frontend-modern/public/docs/DOCKER.md+++ b/frontend-modern/public/docs/DOCKER.md@@ -301,7 +301,45 @@ returning to the old image alone does not undo a data migration.### Check a failed or pending workload update-A failed banner or missing receipt does not tell you whether the update ran.+Start with the **existing error and action stage**, not another click on Update:++- **Planning refused:** “Docker / Podman command agent is not connected” on the+ planning request means Pulse could not find a matching admitted live command+ channel and refused that plan before dispatch. The planning response can be+ HTTP 409, but 409 alone has other causes. This does **not** establish what an+ earlier action did; use the command-channel checks below for this refusal.+- **Action sent, receipt pending:** “The action was sent once” or a pending+ durable receipt means the outcome is uncertain, even beside a failed banner.+ Use the existing receipt and workload-state checks below, without dispatching+ another update.+- **Stage unknown:** a failed banner alone does not tell you whether the update+ ran. Retain that uncertainty; do not assume nothing changed or repeat the+ action to find out. Use existing observations where safe.++#### Command agent is not connected++Open **Settings → Infrastructure → Agent Doctor**, expand the **affected Docker+host**, and inspect the existing **Privilege** wording. This is the agent for+the workload, not necessarily the host running Pulse. `commands monitoring-only`+describes a local command ceiling; `commands command-capable` and `credential+grants exec` describe local authority and credential scope, **not a connected+session**. A missing Privilege line is unknown, not proof that commands are off.+Fresh monitoring or an available image update does not prove command transport.++For a command-capable host, follow the existing+[command-channel connection and admission checks](UNIFIED_AGENT.md#commands-enabled-but-remote-control-blocked).+A monitoring-only setup is intentional when you only need readings and update+detection; do not enable commands, broaden a token, change Proxmox permissions+or loosen TLS merely to diagnose the refusal. Keep saved identity and credentials+intact; do not reinstall or retry the workload update as a connection test.++For help, retain the original error, time and stage plus the existing command+authority/scope wording, or say it is unavailable. Share only those distinctions,+not a full Agent Doctor report, token hint, agent ID or service configuration.+The connection refusal does not settle an earlier missing receipt.++#### Action was sent or its outcome is unknown+Use your normal Docker administration shell **on the host running the affectedcontainer**, not a shell inside Pulse or on an unrelated Proxmox host. Use thesame Docker context as that workload; do not change socket permissions or enablediff --git a/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts b/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.tsindex 2ff6bcecfb..780105d37f 100644--- a/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts+++ b/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts@@ -25,6 +25,62 @@ function section(article: HTMLElement, id: string): string {}describe('shipped monitored-container update guide', () => {+ it('separates a refused plan from a sent or unknown action before any shell check', () => {+ const article = renderGuide();+ const checks = section(article, 'check-a-failed-or-pending-workload-update');+ for (const phrase of [+ 'existing error and action stage',+ 'refused that plan before dispatch',+ '409 alone has other causes',+ 'does not establish what an earlier action did',+ 'outcome is uncertain, even beside a failed banner',+ 'do not assume nothing changed',+ 'A missing Privilege line is unknown',+ 'not a connected session',+ 'do not enable commands, broaden a token',+ 'do not reinstall or retry the workload update as a connection test',+ 'not a full Agent Doctor report, token hint, agent ID',+ ]) {+ expect(checks).toContain(phrase);+ }+ const stages = article.querySelector('#check-a-failed-or-pending-workload-update')!;+ const commands = article.querySelector('#command-agent-is-not-connected')!;+ const uncertain = article.querySelector('#action-was-sent-or-its-outcome-is-unknown')!;+ const firstShellCheck = uncertain.nextElementSibling!.nextElementSibling!.nextElementSibling!;+ expect(firstShellCheck.tagName).toBe('PRE');+ for (const [before, after] of [+ [stages, commands],+ [commands, uncertain],+ [uncertain, firstShellCheck],+ ]) {+ expect(before.compareDocumentPosition(after) & Node.DOCUMENT_POSITION_FOLLOWING).not.toBe(0);+ }+ });++ it('hands command-capable hosts to the actual shipped connection guide, not an install command', () => {+ const article = renderGuide();+ const link = Array.from(article.querySelectorAll('a')).find(+ (anchor) => anchor.textContent === 'command-channel connection and admission checks',+ );+ expect(link?.getAttribute('href')).toBe(+ '/docs/UNIFIED_AGENT#commands-enabled-but-remote-control-blocked',+ );+ expect(link?.hasAttribute('data-doc-link')).toBe(true);+ expect(link?.hasAttribute('target')).toBe(false);+ const agentGuide = document.createElement('article');+ agentGuide.innerHTML = renderDocMarkdown(+ readFileSync(path.join(repoRoot, 'frontend-modern/public/docs/UNIFIED_AGENT.md'), 'utf8'),+ 'UNIFIED_AGENT',+ );+ expect(agentGuide.querySelector(link!.hash)?.textContent).toBe(+ 'Commands enabled but remote control blocked',+ );+ expect(section(agentGuide, link!.hash.slice(1))).toContain('not a connected session');+ expect(guide).toBe(+ readFileSync(path.join(repoRoot, 'frontend-modern/public/docs/DOCKER.md'), 'utf8'),+ );+ });+it('places independent data backup and deployment-manager limits before the action', () => {const article = renderGuide();const precautions = section(article, 'before-updating-a-workload');diff --git a/scripts/tests/test_update_recovery_docs.py b/scripts/tests/test_update_recovery_docs.pyindex 62a831db76..8106a0922f 100644--- a/scripts/tests/test_update_recovery_docs.py+++ b/scripts/tests/test_update_recovery_docs.py@@ -305,6 +305,45 @@ class UpdateRecoveryDocsTest(unittest.TestCase):self.assertIn("Check for receipt", ui)self.assertIn("refreshReceipt()", ui)+ def test_workload_refusal_help_is_stage_qualified_and_matches_planning_source(self):+ text = section("DOCKER", "Check a failed or pending workload update", "###")+ stages = text.split("#### Command agent is not connected", 1)[0]+ for phrase in ("**existing error and action stage**", "**Planning refused:**",+ "planning request", "refused that plan before dispatch",+ "409 alone has other causes", "earlier action did",+ "**Action sent, receipt pending:**", "even beside a failed banner",+ "**Stage unknown:**", "repeat the\n action to find out"):+ self.assertIn(phrase, stages)+ self.assertNotIn("```", stages)+ executor = (ROOT / "internal/api/docker_container_action_executor.go").read_text()+ self.assertIn('"command_agent_disconnected", "Docker / Podman command agent is not connected."', executor)+ lifecycle = (ROOT / "internal/actionlifecycle/service.go").read_text()+ planning = lifecycle.split("func (s *Service) PlanWithOptions(", 1)[1].split(+ "\nfunc ", 1)[0]+ refusal = planning.index("checker.CheckActionAvailable(")+ self.assertLess(refusal, planning.index("checker.CheckActionFeasible("))+ self.assertLess(refusal, planning.index("persistPlanAudit("))+ self.assertIn("&AvailabilityRefusedError", planning[refusal:planning.index("persistPlanAudit(")])++ def test_disconnected_workload_help_reads_authority_without_widening_it(self):+ text = section("DOCKER", "Command agent is not connected", "####")+ flat = " ".join(text.split())+ for phrase in ("**affected Docker host**", "not necessarily the host running Pulse",+ "`commands monitoring-only`", "`commands command-capable`",+ "**not a connected session**", "missing Privilege line is unknown",+ "do not enable commands, broaden a token, change Proxmox permissions",+ "do not reinstall or retry the workload update as a connection test",+ "not a full Agent Doctor report, token hint, agent ID",+ "does not settle an earlier missing receipt"):+ self.assertIn(phrase, flat)+ self.assertNotIn("```", text)+ self.assertIn("UNIFIED_AGENT.md#commands-enabled-but-remote-control-blocked", text)+ model = (ROOT / "frontend-modern/src/components/Settings/infrastructureAgentUpdateCommandsModel.ts").read_text()+ self.assertIn("commands ${authority}", model)+ self.assertIn("'credential grants exec' : 'monitoring credential'", model)+ doctor = (ROOT / "frontend-modern/src/components/Settings/InfrastructureAgentDoctorPage.tsx").read_text()+ self.assertIn("· Privilege: {target.privilegeLabel}", doctor)+def test_update_failure_entry_reuses_bounded_readers_before_any_recovery(self):text = " ".join(section("AUTO_UPDATE", "Update failed", "###").split())for phrase in ("**Pulse server**", "UNIFIED_AGENT.md#auto-update",