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.

Separate refused Docker plans from uncertain workload updates in help

pulse-triage[bot]b5b92e1151d4
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 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 affected
container**, not a shell inside Pulse or on an unrelated Proxmox host. Use the
same Docker context as that workload; do not change socket permissions or enable
diff --git a/frontend-modern/browser-tests/docker-update-guidance.cjs b/frontend-modern/browser-tests/docker-update-guidance.cjs
index 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.md
index 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 affected
container**, not a shell inside Pulse or on an unrelated Proxmox host. Use the
same Docker context as that workload; do not change socket permissions or enable
diff --git a/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts b/frontend-modern/src/features/docs/__tests__/dockerUpdateGuide.test.ts
index 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.py
index 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",