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
Say in plain words what a container action actually did
rcourtman922ee650caab
diff --git a/frontend-modern/browser-verification/c187bb027afb2b39.json b/frontend-modern/browser-verification/c187bb027afb2b39.jsonnew file mode 100644index 0000000000..8bb16d03f8--- /dev/null+++ b/frontend-modern/browser-verification/c187bb027afb2b39.json@@ -0,0 +1,43 @@+{+ "version": 1,+ "base_sha": "8c248d45a0eca4037812c60cb9491125a0a846bd",+ "verified_at": "2026-11-03T16:02:57Z",+ "result": "passed",+ "changed_paths": [+ "frontend-modern/src/features/actions/ActionDecisionPacket.tsx",+ "frontend-modern/src/utils/actionAuditPresentation.ts"+ ],+ "content_sha256": {+ "frontend-modern/src/features/actions/ActionDecisionPacket.tsx": "bd547cb644bafb7e936b2f0d793a768c51aaee28a586fb7897a7d7cdc29c9516",+ "frontend-modern/src/utils/actionAuditPresentation.ts": "111949116f58a54ca7a5228530595d889e964273f66f9c0dafb59f2f1e946182"+ },+ "routes": [+ "/docker (container actions menu -> Review restart -> action review dialog)",+ "/docker on a phone (container row drawer -> Review restart -> action review dialog)",+ "/docker?host=<docker host> (host drawer Overview and Manage tabs)"+ ],+ "viewports": [+ {+ "width": 1280,+ "height": 800+ },+ {+ "width": 390,+ "height": 844+ }+ ],+ "states": [+ "Pulse server and pulse-agent built from this tree (origin/main 94a368de87 plus this change), frontend served by the Vite dev server from the same tree on pulse-dev; one real Docker host agent with the command channel enabled, a fresh data dir, telemetry off.",+ "Two busybox containers on the real Docker daemon: vrig-web (wget health check, page removed so it is unhealthy; a restart recreates the page) and vrig-broken (health check always fails).",+ "Restart of vrig-web at 1280x800: Execution card 'Succeeded' with 'Docker restarted the container.' and a collapsed 'Agent details' disclosure; Verification card 'Confirmed by independent observer', 'Source: Independent observer', 'The container restarted and is running and healthy.' and a collapsed 'Evidence details'.",+ "Agent details expanded: monospace raw report 'Container lifecycle: phase=complete; mutation started=true; mutation completed=true; readback ran=true; before=running/unknown; after=running/unknown'; it collapses again on a second click.",+ "Restart of vrig-broken at 390x844: Execution 'Succeeded' with 'Docker restarted the container.'; Verification 'Outcome contradicted', 'Reason: Postcondition Contradicted', 'The container restarted, but its health check is failing. Check its logs.'; the expanded agent report wraps inside the card, and the document and dialog have no horizontal overflow (scrollWidth 390 = innerWidth).",+ "The vrig-broken restart first showed the existing 'Receipt pending' state (server lifecycle timeout of 2m equals the agent health wait); 'Check for receipt' reconciled it to the outcome above. That timing is unchanged by this change.",+ "The Docker host drawer's action history lists host-level actions only, so the reworded ResourceActionHistory detail lines are covered by actionAuditPresentation unit tests rather than this pass."+ ],+ "interactions": [+ "Sign in, open /docker, open the vrig-web actions menu, choose Review restart, Approve and run, read Recorded outcome, expand and collapse Agent details, scroll to Verification and Recovery.",+ "Expand the Docker host row, open the host drawer Overview and Manage tabs.",+ "At 390x844: open the vrig-broken row drawer, Review restart, Approve and run, Check for receipt until the outcome records, scroll the dialog to Recorded outcome, expand Agent details, check horizontal overflow."+ ]+}diff --git a/frontend-modern/src/features/actions/ActionDecisionPacket.tsx b/frontend-modern/src/features/actions/ActionDecisionPacket.tsxindex f5cc554c6d..96662fb1cf 100644--- a/frontend-modern/src/features/actions/ActionDecisionPacket.tsx+++ b/frontend-modern/src/features/actions/ActionDecisionPacket.tsx@@ -20,6 +20,12 @@ export const ActionDecisionPacket: Component<{const result = () => props.audit.result?.actionResultV2;const apt = () => getAPTActionPresentation(props.audit);const firstEvidence = () => result()?.verification.evidence?.[0];+ // The execution summary is the plain sentence; the agent's raw report stays+ // one click away for anyone diagnosing the action.+ const agentDetails = () => {+ const output = props.audit.result?.output?.trim();+ return output && !apt() && output !== result()?.execution.summary?.trim() ? output : undefined;+ };const originLabel = () => getActionOriginLabel(props.audit.origin);const resource = createMemo(() =>getActionResourcePresentation(props.audit.request.resourceId, props.audit.resource),@@ -257,6 +263,12 @@ export const ActionDecisionPacket: Component<{<Show when={truth().execution.summary && !apt()}><p class="mt-2 text-sm">{truth().execution.summary}</p></Show>+ <Show when={agentDetails()}>+ <details class="mt-3 rounded-sm border border-border-subtle p-3 text-xs">+ <summary class="cursor-pointer font-medium">Agent details</summary>+ <p class="mt-2 break-words font-mono text-muted">{agentDetails()}</p>+ </details>+ </Show></div><divdata-testid="action-verification-truth"diff --git a/frontend-modern/src/features/actions/__tests__/ActionDecisionPacket.test.tsx b/frontend-modern/src/features/actions/__tests__/ActionDecisionPacket.test.tsxindex b805148977..efd212d1f1 100644--- a/frontend-modern/src/features/actions/__tests__/ActionDecisionPacket.test.tsx+++ b/frontend-modern/src/features/actions/__tests__/ActionDecisionPacket.test.tsx@@ -241,6 +241,42 @@ describe('ActionDecisionPacket', () => {},);+ it('keeps the agent raw report behind an Agent details disclosure under the plain execution sentence', () => {+ const raw =+ 'Container lifecycle: phase=verify; mutation started=true; mutation completed=true; readback ran=true; before=running/unknown; after=running/unknown';+ const variant: ActionAuditRecord = {+ ...audit,+ result: {+ ...audit.result!,+ output: raw,+ actionResultV2: {+ ...audit.result!.actionResultV2!,+ execution: { status: 'succeeded', summary: 'Docker restarted the container.' },+ },+ },+ };+ render(() => <ActionDecisionPacket audit={variant} />);+ const execution = screen.getByTestId('action-execution-truth');+ expect(within(execution).getByText('Docker restarted the container.')).toBeInTheDocument();+ const details = within(execution).getByText('Agent details').closest('details');+ expect(details).not.toBeNull();+ expect(details).not.toHaveAttribute('open');+ expect(within(details as HTMLElement).getByText(raw)).toBeInTheDocument();+ cleanup();++ render(() => (+ <ActionDecisionPacket+ audit={{+ ...variant,+ result: { ...variant.result!, output: 'Docker restarted the container.' },+ }}+ />+ ));+ expect(+ within(screen.getByTestId('action-execution-truth')).queryByText('Agent details'),+ ).toBeNull();+ });+it('shows bounded APT facts, agent attestation, recovery, and one durable receipt without a reboot control', () => {const aptAudit: ActionAuditRecord = {...audit,diff --git a/frontend-modern/src/utils/__tests__/actionAuditPresentation.branchcov0712c.test.ts b/frontend-modern/src/utils/__tests__/actionAuditPresentation.branchcov0712c.test.tsindex b5e0063729..34e8d2873a 100644--- a/frontend-modern/src/utils/__tests__/actionAuditPresentation.branchcov0712c.test.ts+++ b/frontend-modern/src/utils/__tests__/actionAuditPresentation.branchcov0712c.test.ts@@ -148,7 +148,7 @@ describe('getActionAuditVerificationOutcomePresentation — actionResultV2 verif);expect(presentation).toStrictEqual({label: 'Confirmed by independent observer',- detail: 'An observer in a different trust domain confirmed the intended state.',+ detail: 'A separate check after the action confirmed the expected result.',evidenceSummary: 'readback matched Source: Independent observer.',className:'border-emerald-200 bg-emerald-50 text-emerald-800 dark:border-emerald-800 dark:bg-emerald-950/40 dark:text-emerald-300',@@ -167,7 +167,7 @@ describe('getActionAuditVerificationOutcomePresentation — actionResultV2 verif);expect(presentation).toStrictEqual({label: 'Confirmed by executing agent',- detail: 'The same agent trust domain that executed the action reported the intended state.',+ detail: 'The agent that ran the action reported the expected result.',evidenceSummary:'No additional verification summary. Source: Executing agent (agent-attested).',className:@@ -202,7 +202,7 @@ describe('getActionAuditVerificationOutcomePresentation — actionResultV2 verif);expect(presentation).toStrictEqual({label: 'Outcome contradicted',- detail: 'Observed evidence contradicted the intended state.',+ detail: 'Pulse checked afterwards, and what it found did not match the expected result.',evidenceSummary: 'observed state differed Source: Independent observer.',className:'border-rose-200 bg-rose-50 text-rose-800 dark:border-rose-800 dark:bg-rose-950/40 dark:text-rose-300',@@ -218,7 +218,7 @@ describe('getActionAuditVerificationOutcomePresentation — actionResultV2 verif);expect(presentation).toStrictEqual({label: 'Outcome inconclusive',- detail: 'Available evidence could not establish the intended state.',+ detail: 'Pulse could not tell whether this action had the expected result.',evidenceSummary:'No additional verification summary. Source: Executing agent (agent-attested).',className:@@ -235,7 +235,7 @@ describe('getActionAuditVerificationOutcomePresentation — actionResultV2 verif);expect(presentation).toStrictEqual({label: 'Outcome not verified',- detail: 'No outcome verification was attempted.',+ detail: 'Pulse did not check the result of this action.',evidenceSummary: 'No additional verification summary. Source: No evidence source.',className:'border-amber-200 bg-amber-50 text-amber-800 dark:border-amber-800 dark:bg-amber-950/40 dark:text-amber-300',diff --git a/frontend-modern/src/utils/__tests__/actionAuditPresentation.test.ts b/frontend-modern/src/utils/__tests__/actionAuditPresentation.test.tsindex ea39a32fd2..ffb9fd1a43 100644--- a/frontend-modern/src/utils/__tests__/actionAuditPresentation.test.ts+++ b/frontend-modern/src/utils/__tests__/actionAuditPresentation.test.ts@@ -191,4 +191,29 @@ describe('actionAuditPresentation', () => {}),).toMatchObject({ label: 'Verification outcome recorded' });});++ it('pairs a contradicted check with the plain sentence saying what Pulse saw', () => {+ expect(+ getActionAuditVerificationOutcomePresentation({+ result: {+ success: true,+ actionResultV2: {+ version: 2,+ execution: { status: 'succeeded', summary: 'Docker restarted the container.' },+ verification: {+ status: 'contradicted',+ evidenceClass: 'independent',+ summary: 'The container restarted, but its health check is failing. Check its logs.',+ },+ compensation: { support: 'unavailable', status: 'not_available' },+ },+ },+ }),+ ).toMatchObject({+ label: 'Outcome contradicted',+ detail: 'Pulse checked afterwards, and what it found did not match the expected result.',+ evidenceSummary:+ 'The container restarted, but its health check is failing. Check its logs. Source: Independent observer.',+ });+ });});diff --git a/frontend-modern/src/utils/actionAuditPresentation.ts b/frontend-modern/src/utils/actionAuditPresentation.tsindex 2dcbc45c65..bb3a3b4b5a 100644--- a/frontend-modern/src/utils/actionAuditPresentation.ts+++ b/frontend-modern/src/utils/actionAuditPresentation.ts@@ -344,23 +344,26 @@ export const getActionAuditVerificationOutcomePresentation = (audit: {truth.evidenceClass === 'independent'? ['Confirmed by independent observer',- 'An observer in a different trust domain confirmed the intended state.',+ 'A separate check after the action confirmed the expected result.',]: truth.evidenceClass === 'agent_attested'? ['Confirmed by executing agent',- 'The same agent trust domain that executed the action reported the intended state.',+ 'The agent that ran the action reported the expected result.',]: ['Confirmation lacks an evidence source','The record says confirmed but provides no evidence source. Do not treat it as independently verified.',],- contradicted: ['Outcome contradicted', 'Observed evidence contradicted the intended state.'],+ contradicted: [+ 'Outcome contradicted',+ 'Pulse checked afterwards, and what it found did not match the expected result.',+ ],inconclusive: ['Outcome inconclusive',- 'Available evidence could not establish the intended state.',+ 'Pulse could not tell whether this action had the expected result.',],- not_attempted: ['Outcome not verified', 'No outcome verification was attempted.'],+ not_attempted: ['Outcome not verified', 'Pulse did not check the result of this action.'],} as const;const [label, detail] = statusCopy[truth.status];return {diff --git a/internal/api/docker_container_action_result.go b/internal/api/docker_container_action_result.goindex 680d3f34eb..f74afbb67f 100644--- a/internal/api/docker_container_action_result.go+++ b/internal/api/docker_container_action_result.go@@ -11,12 +11,14 @@ import ()func dockerContainerExecutionResult(resourceID, agentID string, req agentexec.DockerContainerLifecyclePayload, facts agentexec.DockerContainerLifecycleResultPayload, independent *dockerContainerPostconditionObservation, receivedAt time.Time) (*unified.ExecutionResult, error) {+ // The raw fact summary stays on the evidence and legacy output; the+ // execution and verification summaries are the plain sentences people read.summary := dockerContainerFactSummary(facts)- execution := unified.ActionExecutionTruth{Status: unified.ActionExecutionNotRun, ReasonCode: actionPreflightReasonCode(facts.ReasonCode), Summary: summary}+ execution := unified.ActionExecutionTruth{Status: unified.ActionExecutionNotRun, ReasonCode: actionPreflightReasonCode(facts.ReasonCode), Summary: dockerLifecycleExecutionSummary(req.Operation, facts)}if facts.MutationCompleted {- execution = unified.ActionExecutionTruth{Status: unified.ActionExecutionSucceeded, Summary: summary}+ execution = unified.ActionExecutionTruth{Status: unified.ActionExecutionSucceeded, Summary: dockerLifecycleExecutionSummary(req.Operation, facts)}} else if facts.MutationStarted {- execution = unified.ActionExecutionTruth{Status: unified.ActionExecutionInconclusive, ReasonCode: "possible_partial_effect", Summary: summary}+ execution = unified.ActionExecutionTruth{Status: unified.ActionExecutionInconclusive, ReasonCode: "possible_partial_effect", Summary: dockerLifecycleExecutionSummary(req.Operation, facts)}}verification := unified.ActionVerificationTruth{Status: unified.ActionVerificationInconclusive, EvidenceClass: unified.ActionEvidenceNone, ReasonCode: "agent_readback_unavailable", Summary: "The typed operation did not return a usable container readback."}@@ -34,7 +36,7 @@ func dockerContainerExecutionResult(resourceID, agentID string, req agentexec.Doreturn nil, fmt.Errorf("normalize docker lifecycle evidence: %w", err)}status, reason := dockerLifecycleVerification(req.Operation, facts.Before, facts.After)- verification = unified.ActionVerificationTruth{Status: status, EvidenceClass: unified.ActionEvidenceAgentAttested, ReasonCode: reason, Summary: summary, Evidence: []unified.ActionEvidence{evidence}}+ verification = unified.ActionVerificationTruth{Status: status, EvidenceClass: unified.ActionEvidenceAgentAttested, ReasonCode: reason, Summary: dockerLifecycleOutcomeSummary(req.Operation, status, reason, facts.Before, facts.After), Evidence: []unified.ActionEvidence{evidence}}}}if independent != nil && freshDockerLifecycleObservation(facts.Before.ObservedAt, independent.Snapshot.ObservedAt, independent.ReceivedAt) && strings.TrimSpace(independent.TrustDomain) != "" && strings.TrimSpace(independent.TrustDomain) != "agent:"+agentID && strings.EqualFold(independent.Snapshot.ContainerID, facts.ContainerID) {@@ -57,11 +59,12 @@ func dockerContainerExecutionResult(resourceID, agentID string, req agentexec.Doif err != nil {return nil, fmt.Errorf("normalize independent docker observation: %w", err)}- status, reason := dockerLifecycleVerification(req.Operation, facts.Before, agentexec.DockerContainerLifecycleSnapshot{+ observed := agentexec.DockerContainerLifecycleSnapshot{ContainerID: independent.Snapshot.ContainerID, State: independent.Snapshot.State, Running: independent.Snapshot.Running,Health: independent.Snapshot.Health, StartedAt: independent.Snapshot.StartedAt,- })- verification = unified.ActionVerificationTruth{Status: status, EvidenceClass: unified.ActionEvidenceIndependent, ReasonCode: reason, Summary: independentSummary, Evidence: []unified.ActionEvidence{evidence}}+ }+ status, reason := dockerLifecycleVerification(req.Operation, facts.Before, observed)+ verification = unified.ActionVerificationTruth{Status: status, EvidenceClass: unified.ActionEvidenceIndependent, ReasonCode: reason, Summary: dockerLifecycleOutcomeSummary(req.Operation, status, reason, facts.Before, observed), Evidence: []unified.ActionEvidence{evidence}}}canonical := unified.ActionResultV2{@@ -79,11 +82,11 @@ func dockerContainerExecutionResult(resourceID, agentID string, req agentexec.Dofunc dockerContainerUpdateExecutionResult(resourceID, agentID string, facts agentexec.DockerContainerUpdateResultPayload, independent *dockerContainerPostconditionObservation, receivedAt time.Time) (*unified.ExecutionResult, error) {summary := dockerContainerUpdateFactSummary(facts)- execution := unified.ActionExecutionTruth{Status: unified.ActionExecutionNotRun, ReasonCode: actionPreflightReasonCode(facts.ReasonCode), Summary: summary}+ execution := unified.ActionExecutionTruth{Status: unified.ActionExecutionNotRun, ReasonCode: actionPreflightReasonCode(facts.ReasonCode), Summary: dockerUpdateExecutionSummary(facts)}if facts.MutationCompleted {- execution = unified.ActionExecutionTruth{Status: unified.ActionExecutionSucceeded, Summary: summary}+ execution = unified.ActionExecutionTruth{Status: unified.ActionExecutionSucceeded, Summary: dockerUpdateExecutionSummary(facts)}} else if facts.MutationStarted {- execution = unified.ActionExecutionTruth{Status: unified.ActionExecutionInconclusive, ReasonCode: "possible_partial_effect", Summary: summary}+ execution = unified.ActionExecutionTruth{Status: unified.ActionExecutionInconclusive, ReasonCode: "possible_partial_effect", Summary: dockerUpdateExecutionSummary(facts)}}verification := unified.ActionVerificationTruth{Status: unified.ActionVerificationInconclusive, EvidenceClass: unified.ActionEvidenceNone, ReasonCode: "agent_readback_unavailable", Summary: "The typed operation did not return a usable replacement-container readback."}@@ -119,7 +122,7 @@ func dockerContainerUpdateExecutionResult(resourceID, agentID string, facts agenstatus = unified.ActionVerificationConfirmedreason = ""}- verification = unified.ActionVerificationTruth{Status: status, EvidenceClass: unified.ActionEvidenceAgentAttested, ReasonCode: reason, Summary: summary, Evidence: []unified.ActionEvidence{evidence}}+ verification = unified.ActionVerificationTruth{Status: status, EvidenceClass: unified.ActionEvidenceAgentAttested, ReasonCode: reason, Summary: dockerUpdateOutcomeSummary(status, reason, facts.After.State, facts.After.Running, facts.After.Health), Evidence: []unified.ActionEvidence{evidence}}}}if independent != nil && facts.NewContainerID != "" && freshDockerUpdateObservation(independent.Snapshot.ObservedAt, independent.ReceivedAt) && strings.TrimSpace(independent.TrustDomain) != "" && strings.TrimSpace(independent.TrustDomain) != "agent:"+agentID {@@ -165,7 +168,11 @@ func dockerContainerUpdateExecutionResult(resourceID, agentID string, facts agenstatus = unified.ActionVerificationConfirmedreason = ""}- verification = unified.ActionVerificationTruth{Status: status, EvidenceClass: unified.ActionEvidenceIndependent, ReasonCode: reason, Summary: independentSummary, Evidence: []unified.ActionEvidence{evidence}}+ outcome := dockerUpdateOutcomeSummary(status, reason, independent.Snapshot.State, independent.Snapshot.Running, independent.Snapshot.Health)+ if status == unified.ActionVerificationContradicted && !dockerUpdateFactsMatch(facts, independent.Snapshot.ContainerID) {+ outcome = "Pulse found a different container than the one the update created."+ }+ verification = unified.ActionVerificationTruth{Status: status, EvidenceClass: unified.ActionEvidenceIndependent, ReasonCode: reason, Summary: outcome, Evidence: []unified.ActionEvidence{evidence}}}canonical := unified.ActionResultV2{@@ -324,3 +331,184 @@ func dockerLifecycleVerification(operation string, before, after agentexec.Docke}return unified.ActionVerificationContradicted, "postcondition_contradicted"}++// dockerLifecycleVerbs returns the base and past-tense verb for a lifecycle+// operation, so summaries read "restart" and "restarted".+func dockerLifecycleVerbs(operation string) (string, string) {+ switch operation {+ case agentexec.DockerContainerOperationStart:+ return "start", "started"+ case agentexec.DockerContainerOperationStop:+ return "stop", "stopped"+ case agentexec.DockerContainerOperationRestart:+ return "restart", "restarted"+ default:+ return "change", "changed"+ }+}++func dockerLifecycleExecutionSummary(operation string, facts agentexec.DockerContainerLifecycleResultPayload) string {+ base, past := dockerLifecycleVerbs(operation)+ var summary string+ switch {+ case facts.MutationCompleted:+ return "Docker " + past + " the container."+ case facts.MutationStarted:+ summary = "Docker was asked to " + base + " the container, but did not confirm it, so the change may or may not have happened."+ default:+ summary = "The agent did not " + base + " the container."+ }+ return summary + dockerAgentErrorSentence(facts.Error)+}++// dockerAgentErrorSentence appends the agent's own error text, if any, as a+// trailing sentence.+func dockerAgentErrorSentence(errText string) string {+ errText = strings.TrimRight(strings.TrimSpace(errText), " .:")+ if errText == "" {+ return ""+ }+ return " Agent said: " + errText + "."+}++// dockerContainerStateWords describes what Docker reports for a container. It+// reads the state and the running flag together so the two cannot disagree.+func dockerContainerStateWords(state string, running bool) string {+ state = strings.ToLower(strings.TrimSpace(state))+ switch state {+ case "running":+ if running {+ return "running"+ }+ return "running but not marked as running"+ case "exited":+ return "stopped"+ case "restarting":+ return "restarting, which usually means it keeps crashing"+ case "created":+ return "created but not started"+ case "paused", "dead":+ return state+ case "removing":+ return "being removed"+ case "":+ return "in an unknown state"+ default:+ return "in the " + state + " state"+ }+}++func dockerContainerIsRunning(state string, running bool) bool {+ return running && strings.EqualFold(strings.TrimSpace(state), "running")+}++const dockerHealthStartingAdvice = " Its health check was still starting when Pulse checked. Wait a moment, then refresh its status."++// dockerLifecycleOutcomeSummary says in plain words what Pulse saw after a+// container start, stop or restart. The typed facts stay on the evidence.+func dockerLifecycleOutcomeSummary(operation string, status unified.ActionVerificationStatus, reason string, before, after agentexec.DockerContainerLifecycleSnapshot) string {+ running := dockerContainerIsRunning(after.State, after.Running)+ healthy := strings.EqualFold(strings.TrimSpace(after.Health), agentexec.DockerContainerHealthHealthy)+ unhealthy := strings.EqualFold(strings.TrimSpace(after.Health), agentexec.DockerContainerHealthUnhealthy)+ switch status {+ case unified.ActionVerificationConfirmed:+ switch operation {+ case agentexec.DockerContainerOperationStop:+ return "The container is stopped."+ case agentexec.DockerContainerOperationRestart:+ if healthy {+ return "The container restarted and is running and healthy."+ }+ return "The container restarted and is running."+ default:+ if healthy {+ return "The container is running and healthy."+ }+ return "The container is running."+ }+ case unified.ActionVerificationInconclusive:+ switch reason {+ case "container_health_starting":+ return "The container is running." + dockerHealthStartingAdvice+ case "container_health_unknown":+ return "Docker reports the container as " + dockerContainerStateWords(after.State, after.Running) + ". Pulse could not get its health information, so it could not confirm the result."+ }+ return "Pulse could not confirm the result."+ case unified.ActionVerificationContradicted:+ if operation == agentexec.DockerContainerOperationStop {+ if running {+ return "The container is still running."+ }+ return "Pulse expected a stopped container. Docker reports it as " + dockerContainerStateWords(after.State, after.Running) + "."+ }+ if !running {+ return "The container is not running. Docker reports it as " + dockerContainerStateWords(after.State, after.Running) + "."+ }+ if operation == agentexec.DockerContainerOperationRestart && (after.StartedAt.IsZero() || !after.StartedAt.After(before.StartedAt)) {+ switch {+ case after.StartedAt.IsZero():+ return "The container is running, but Pulse did not receive its start time, so it could not confirm a restart."+ case after.StartedAt.Equal(before.StartedAt):+ return "The container is running, but its start time did not change, so it did not restart."+ default:+ return "The container is running, but its start time is not newer than before, so Pulse could not confirm a restart."+ }+ }+ if unhealthy {+ if operation == agentexec.DockerContainerOperationRestart {+ return "The container restarted, but its health check is failing. Check its logs."+ }+ return "The container started, but its health check is failing. Check its logs."+ }+ return "The container is not in the state this action should have left it in."+ }+ return "Pulse could not confirm the result."+}++func dockerUpdateExecutionSummary(facts agentexec.DockerContainerUpdateResultPayload) string {+ var summary string+ switch {+ case facts.MutationCompleted:+ return "Docker replaced the container with one using the new image."+ case facts.MutationStarted:+ summary = "The update started, but Pulse could not confirm it completed."+ default:+ summary = "The update stopped before changing the container."+ }+ return summary + dockerAgentErrorSentence(facts.Error)+}++// dockerUpdateOutcomeSummary says in plain words what Pulse saw of the+// replacement container after an update.+func dockerUpdateOutcomeSummary(status unified.ActionVerificationStatus, reason, state string, running bool, health string) string {+ isRunning := dockerContainerIsRunning(state, running)+ switch status {+ case unified.ActionVerificationConfirmed:+ if !isRunning {+ return "The updated container is in place. Docker reports it as " + dockerContainerStateWords(state, running) + "."+ }+ if strings.EqualFold(strings.TrimSpace(health), agentexec.DockerContainerHealthHealthy) {+ return "The updated container is running and healthy."+ }+ return "The updated container is running."+ case unified.ActionVerificationInconclusive:+ switch reason {+ case "container_health_starting":+ return "The updated container is running." + dockerHealthStartingAdvice+ case "container_health_unknown":+ return "Docker reports the updated container as " + dockerContainerStateWords(state, running) + ". Pulse could not get its health information, so it could not confirm the update."+ case "agent_readback_unavailable":+ return "The agent did not report the updated container's state, so Pulse could not confirm the update."+ }+ return "Pulse could not confirm the update."+ case unified.ActionVerificationContradicted:+ if !isRunning {+ return "Docker reports the updated container as " + dockerContainerStateWords(state, running) + "."+ }+ if strings.EqualFold(strings.TrimSpace(health), agentexec.DockerContainerHealthUnhealthy) {+ return "The updated container is running, but its health check is failing. Check its logs."+ }+ return "The updated container is not in the expected state."+ }+ return "Pulse could not confirm the update."+}diff --git a/internal/api/docker_container_action_result_test.go b/internal/api/docker_container_action_result_test.goindex 600d4ba403..dd06dc8419 100644--- a/internal/api/docker_container_action_result_test.go+++ b/internal/api/docker_container_action_result_test.go@@ -1,6 +1,8 @@package apiimport (+ "encoding/json"+ "strings""testing""time"@@ -303,3 +305,209 @@ func TestDockerContainerUpdateAgentReadbackMustSupportRunningClaim(t *testing.T)})}}++// The execution and verification summaries are the sentences people read in+// the action result, so they must say what Pulse saw in plain words while the+// typed facts stay on the evidence.+func TestDockerContainerExecutionResultSummariesSayWhatPulseSaw(t *testing.T) {+ now := time.Now().UTC()+ beforeStart := now.Add(-time.Minute)+ for _, tc := range []struct {+ name, operation, state, health string+ running bool+ startedAt time.Time+ status unified.ActionVerificationStatus+ want string+ }{+ {name: "restart recovered", operation: agentexec.DockerContainerOperationRestart, state: "running", running: true, health: agentexec.DockerContainerHealthHealthy, startedAt: now, status: unified.ActionVerificationConfirmed, want: "The container restarted and is running and healthy."},+ {name: "restart without health check", operation: agentexec.DockerContainerOperationRestart, state: "running", running: true, health: agentexec.DockerContainerHealthNone, startedAt: now, status: unified.ActionVerificationConfirmed, want: "The container restarted and is running."},+ {name: "restart health failing", operation: agentexec.DockerContainerOperationRestart, state: "running", running: true, health: agentexec.DockerContainerHealthUnhealthy, startedAt: now, status: unified.ActionVerificationContradicted, want: "The container restarted, but its health check is failing. Check its logs."},+ {name: "restart crash loop", operation: agentexec.DockerContainerOperationRestart, state: "restarting", running: true, health: agentexec.DockerContainerHealthNone, startedAt: now, status: unified.ActionVerificationContradicted, want: "The container is not running. Docker reports it as restarting, which usually means it keeps crashing."},+ {name: "restart same start time", operation: agentexec.DockerContainerOperationRestart, state: "running", running: true, health: agentexec.DockerContainerHealthNone, startedAt: beforeStart, status: unified.ActionVerificationContradicted, want: "The container is running, but its start time did not change, so it did not restart."},+ {name: "restart earlier start time", operation: agentexec.DockerContainerOperationRestart, state: "running", running: true, health: agentexec.DockerContainerHealthNone, startedAt: beforeStart.Add(-time.Hour), status: unified.ActionVerificationContradicted, want: "The container is running, but its start time is not newer than before, so Pulse could not confirm a restart."},+ {name: "restart missing start time", operation: agentexec.DockerContainerOperationRestart, state: "running", running: true, health: agentexec.DockerContainerHealthNone, status: unified.ActionVerificationContradicted, want: "The container is running, but Pulse did not receive its start time, so it could not confirm a restart."},+ {name: "restart health pending", operation: agentexec.DockerContainerOperationRestart, state: "running", running: true, health: agentexec.DockerContainerHealthStarting, startedAt: now, status: unified.ActionVerificationInconclusive, want: "The container is running. Its health check was still starting when Pulse checked. Wait a moment, then refresh its status."},+ {name: "running state without running flag", operation: agentexec.DockerContainerOperationStart, state: "running", running: false, health: agentexec.DockerContainerHealthNone, startedAt: now, status: unified.ActionVerificationContradicted, want: "The container is not running. Docker reports it as running but not marked as running."},+ {name: "start exited again", operation: agentexec.DockerContainerOperationStart, state: "exited", running: false, health: agentexec.DockerContainerHealthNone, startedAt: now, status: unified.ActionVerificationContradicted, want: "The container is not running. Docker reports it as stopped."},+ {name: "start health failing", operation: agentexec.DockerContainerOperationStart, state: "running", running: true, health: agentexec.DockerContainerHealthUnhealthy, startedAt: now, status: unified.ActionVerificationContradicted, want: "The container started, but its health check is failing. Check its logs."},+ {name: "stop still running", operation: agentexec.DockerContainerOperationStop, state: "running", running: true, health: agentexec.DockerContainerHealthNone, startedAt: beforeStart, status: unified.ActionVerificationContradicted, want: "The container is still running."},+ {name: "stop paused", operation: agentexec.DockerContainerOperationStop, state: "paused", running: false, health: agentexec.DockerContainerHealthNone, startedAt: beforeStart, status: unified.ActionVerificationContradicted, want: "Pulse expected a stopped container. Docker reports it as paused."},+ {name: "stop paused but flagged running", operation: agentexec.DockerContainerOperationStop, state: "paused", running: true, health: agentexec.DockerContainerHealthNone, startedAt: beforeStart, status: unified.ActionVerificationContradicted, want: "Pulse expected a stopped container. Docker reports it as paused."},+ {name: "stop confirmed", operation: agentexec.DockerContainerOperationStop, state: "exited", running: false, health: agentexec.DockerContainerHealthNone, startedAt: beforeStart, status: unified.ActionVerificationConfirmed, want: "The container is stopped."},+ } {+ t.Run(tc.name, func(t *testing.T) {+ facts := dockerResultFacts(now, true, true, true, true)+ facts.ContainerID = dockerLifecycleTestID+ req := agentexec.DockerContainerLifecyclePayload{ActionID: "action-1", Operation: tc.operation}+ observation := &dockerContainerPostconditionObservation{+ ObserverID: "docker-daemon:agent-1", TrustDomain: "docker-daemon:agent-1", Method: "typed_docker_daemon_observation",+ Snapshot: agentexec.DockerContainerObservationSnapshot{ContainerID: dockerLifecycleTestID, State: tc.state, Running: tc.running, Health: tc.health, StartedAt: tc.startedAt, ObservedAt: now},+ ReceivedAt: now,+ }+ result, err := dockerContainerExecutionResult("app-container:fixture", "agent-1", req, facts, observation, now)+ if err != nil {+ t.Fatal(err)+ }+ truth := result.ActionResultV2+ if truth.Verification.Status != tc.status || truth.Verification.Summary != tc.want {+ t.Fatalf("verification = %q %q, want %q %q", truth.Verification.Status, truth.Verification.Summary, tc.status, tc.want)+ }+ _, past := dockerLifecycleVerbs(tc.operation)+ if want := "Docker " + past + " the container."; truth.Execution.Summary != want {+ t.Fatalf("execution summary = %q, want %q", truth.Execution.Summary, want)+ }+ if len(truth.Verification.Evidence) != 1 || !strings.HasPrefix(truth.Verification.Evidence[0].Summary, "Direct daemon observation:") {+ t.Fatalf("typed observation facts left the evidence: %#v", truth.Verification.Evidence)+ }+ if !strings.HasPrefix(result.Output, "Container lifecycle: phase=") {+ t.Fatalf("legacy output lost the typed facts: %q", result.Output)+ }+ })+ }+}++// The agent receipt does not carry health on the wire, so without a daemon+// observation the server cannot confirm a start or restart. The summary must+// say Pulse lacked the health information rather than blame Docker.+func TestDockerContainerAgentOnlySummaryAfterWireRoundTrip(t *testing.T) {+ now := time.Now().UTC()+ for _, tc := range []struct {+ name, state string+ running bool+ want string+ }{+ {name: "running", state: "running", running: true, want: "Docker reports the container as running. Pulse could not get its health information, so it could not confirm the result."},+ {name: "exited", state: "exited", running: false, want: "Docker reports the container as stopped. Pulse could not get its health information, so it could not confirm the result."},+ {name: "restarting", state: "restarting", running: true, want: "Docker reports the container as restarting, which usually means it keeps crashing. Pulse could not get its health information, so it could not confirm the result."},+ } {+ t.Run(tc.name, func(t *testing.T) {+ facts := dockerResultFacts(now, true, true, true, true)+ facts.After.State, facts.After.Running = tc.state, tc.running+ encoded, err := json.Marshal(facts)+ if err != nil {+ t.Fatal(err)+ }+ var wire agentexec.DockerContainerLifecycleResultPayload+ if err := json.Unmarshal(encoded, &wire); err != nil {+ t.Fatal(err)+ }+ if wire.After.Health != "" {+ t.Fatalf("fixture expects health to stay off the wire, got %q", wire.After.Health)+ }+ result, err := dockerContainerExecutionResult("app-container:fixture", "agent-1", agentexec.DockerContainerLifecyclePayload{Operation: agentexec.DockerContainerOperationRestart}, wire, nil, now)+ if err != nil {+ t.Fatal(err)+ }+ verification := result.ActionResultV2.Verification+ if verification.Status != unified.ActionVerificationInconclusive || verification.ReasonCode != "container_health_unknown" || verification.Summary != tc.want {+ t.Fatalf("verification = %q %q %q, want %q", verification.Status, verification.ReasonCode, verification.Summary, tc.want)+ }+ if len(verification.Evidence) != 1 || !strings.HasPrefix(verification.Evidence[0].Summary, "Container lifecycle: phase=") {+ t.Fatalf("agent readback facts left the evidence: %#v", verification.Evidence)+ }+ })+ }+}++func TestDockerContainerExecutionSummariesCarryUncertaintyAndAgentError(t *testing.T) {+ now := time.Now().UTC()+ for _, tc := range []struct {+ name string+ started, completed bool+ errText string+ want string+ }{+ {name: "refused", errText: "container preflight state no longer matches the request", want: "The agent did not restart the container. Agent said: container preflight state no longer matches the request."},+ {name: "partial", started: true, errText: "context deadline exceeded", want: "Docker was asked to restart the container, but did not confirm it, so the change may or may not have happened. Agent said: context deadline exceeded."},+ } {+ t.Run(tc.name, func(t *testing.T) {+ facts := dockerResultFacts(now, tc.started, tc.completed, false, true)+ facts.ReasonCode = agentexec.ActionRefusalTargetStateChanged+ facts.Error = tc.errText+ result, err := dockerContainerExecutionResult("app-container:fixture", "agent-1", agentexec.DockerContainerLifecyclePayload{Operation: agentexec.DockerContainerOperationRestart}, facts, nil, now)+ if err != nil {+ t.Fatal(err)+ }+ if got := result.ActionResultV2.Execution.Summary; got != tc.want {+ t.Fatalf("execution summary = %q, want %q", got, tc.want)+ }+ if !strings.Contains(result.Output, "error="+tc.errText) {+ t.Fatalf("legacy output lost the agent error: %q", result.Output)+ }+ })+ }+}++func TestDockerContainerUpdateSummariesSayWhatPulseSaw(t *testing.T) {+ now := time.Now().UTC()+ for _, tc := range []struct {+ name, agentState, state, health string+ agentRunning, running bool+ observedID string+ status unified.ActionVerificationStatus+ want string+ }{+ {name: "running healthy", agentState: "running", agentRunning: true, state: "running", running: true, health: agentexec.DockerContainerHealthHealthy, observedID: dockerLifecycleTestID, status: unified.ActionVerificationConfirmed, want: "The updated container is running and healthy."},+ {name: "kept stopped", agentState: "exited", state: "exited", health: agentexec.DockerContainerHealthNone, observedID: dockerLifecycleTestID, status: unified.ActionVerificationConfirmed, want: "The updated container is in place. Docker reports it as stopped."},+ {name: "kept created", agentState: "created", state: "created", health: agentexec.DockerContainerHealthNone, observedID: dockerLifecycleTestID, status: unified.ActionVerificationConfirmed, want: "The updated container is in place. Docker reports it as created but not started."},+ {name: "health failing", agentState: "running", agentRunning: true, state: "running", running: true, health: agentexec.DockerContainerHealthUnhealthy, observedID: dockerLifecycleTestID, status: unified.ActionVerificationContradicted, want: "The updated container is running, but its health check is failing. Check its logs."},+ {name: "exited after readback", agentState: "running", agentRunning: true, state: "exited", health: agentexec.DockerContainerHealthNone, observedID: dockerLifecycleTestID, status: unified.ActionVerificationContradicted, want: "Docker reports the updated container as stopped."},+ {name: "health pending", agentState: "running", agentRunning: true, state: "running", running: true, health: agentexec.DockerContainerHealthStarting, observedID: dockerLifecycleTestID, status: unified.ActionVerificationInconclusive, want: "The updated container is running. Its health check was still starting when Pulse checked. Wait a moment, then refresh its status."},+ {name: "different container", agentState: "running", agentRunning: true, state: "running", running: true, health: agentexec.DockerContainerHealthHealthy, observedID: strings.Repeat("f", 64), status: unified.ActionVerificationContradicted, want: "Pulse found a different container than the one the update created."},+ {name: "readback unavailable", state: "running", running: true, health: agentexec.DockerContainerHealthHealthy, observedID: dockerLifecycleTestID, status: unified.ActionVerificationInconclusive, want: "The agent did not report the updated container's state, so Pulse could not confirm the update."},+ } {+ t.Run(tc.name, func(t *testing.T) {+ facts := agentexec.DockerContainerUpdateResultPayload{+ Operation: agentexec.DockerContainerOperationUpdate, ActionID: "action-update", ExecutionPhase: agentexec.DockerContainerPhaseComplete,+ MutationStarted: true, MutationCompleted: true, ReadbackRan: tc.agentState != "", NewContainerID: dockerLifecycleTestID,+ After: agentexec.DockerContainerLifecycleSnapshot{ContainerID: dockerLifecycleTestID, State: tc.agentState, Running: tc.agentRunning, ObservedAt: now},+ }+ observation := &dockerContainerPostconditionObservation{+ ObserverID: "docker-daemon:agent-1", TrustDomain: "docker-daemon:agent-1", Method: "typed_docker_daemon_observation",+ Snapshot: agentexec.DockerContainerObservationSnapshot{ContainerID: tc.observedID, State: tc.state, Running: tc.running, Health: tc.health, ObservedAt: now},+ ReceivedAt: now,+ }+ result, err := dockerContainerUpdateExecutionResult("app-container:fixture", "agent-1", facts, observation, now)+ if err != nil {+ t.Fatal(err)+ }+ truth := result.ActionResultV2+ if truth.Verification.Status != tc.status || truth.Verification.Summary != tc.want {+ t.Fatalf("verification = %q %q, want %q %q", truth.Verification.Status, truth.Verification.Summary, tc.status, tc.want)+ }+ if truth.Execution.Summary != "Docker replaced the container with one using the new image." {+ t.Fatalf("execution summary = %q", truth.Execution.Summary)+ }+ if !strings.HasPrefix(result.Output, "Container update: phase=") {+ t.Fatalf("legacy output lost the typed facts: %q", result.Output)+ }+ })+ }+}++func TestDockerContainerUpdateExecutionSummariesCarryUncertaintyAndAgentError(t *testing.T) {+ now := time.Now().UTC()+ for _, tc := range []struct {+ name string+ started bool+ errText string+ want string+ }{+ {name: "not started", errText: "Failed to pull image: manifest unknown: ", want: "The update stopped before changing the container. Agent said: Failed to pull image: manifest unknown."},+ {name: "partial", started: true, errText: "context deadline exceeded", want: "The update started, but Pulse could not confirm it completed. Agent said: context deadline exceeded."},+ } {+ t.Run(tc.name, func(t *testing.T) {+ facts := agentexec.DockerContainerUpdateResultPayload{+ Operation: agentexec.DockerContainerOperationUpdate, ActionID: "action-update", ExecutionPhase: agentexec.DockerContainerPhasePreflight,+ MutationStarted: tc.started, Error: tc.errText,+ }+ result, err := dockerContainerUpdateExecutionResult("app-container:fixture", "agent-1", facts, nil, now)+ if err != nil {+ t.Fatal(err)+ }+ if got := result.ActionResultV2.Execution.Summary; got != tc.want {+ t.Fatalf("execution summary = %q, want %q", got, tc.want)+ }+ })+ }+}