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.

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.json
new file mode 100644
index 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.tsx
index 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>
<div
data-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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.go
index 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.Do
return 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.Do
if 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.Do
func 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 agen
status = unified.ActionVerificationConfirmed
reason = ""
}
- 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 agen
status = unified.ActionVerificationConfirmed
reason = ""
}
- 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.go
index 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 api
import (
+ "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)
+ }
+ })
+ }
+}