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.

docker: offer container updates only where Pulse can apply them

rcourtman6517a9d891c9
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
index 319b8ee1c5..a9c065030b 100644
--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
@@ -15,6 +15,14 @@
## Purpose
+### Manual update checks skip images with no registry tag (21 October 2026)
+
+A manual container update check counts a `local image` status as skipped,
+alongside `digest-pinned image`, rather than as a checked image with a
+registry error. No agent authority or transport changes.
+`TestSummarizeManualUpdateCheckSkipsUncheckableImages` covers the summary.
+
+
### Lost container mutation acknowledgements reconcile through reads
Typed container lifecycle execution attempts its mutation once. A transport
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index d570a3c51c..f6401aa9de 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -20,6 +20,18 @@
## Purpose
+### Container update control offers only what the server advertises (21 October 2026)
+
+`UpdateButton` is live only when the server advertises the `update` capability
+and records no refusal for it. A recorded refusal, or no advertised capability
+(for example a host whose inventory is stale), renders the locked amber pill
+with the reason. When the refusal is a disconnected command agent and the
+host's agent facet reports no command access, the explanation names the host
+and the install option that grants access. The locked pill reads `Update` so
+it fits the Updates column at its narrowest; Local joins Pinned as a neutral
+uncheckable state rather than Check failed.
+
+
### Aggregate disk bars preserve percentage-only evidence (14 October 2026)
The shared stacked-disk primitive keeps independently supplied aggregate
diff --git a/docs/release-control/v6/internal/subsystems/monitoring.md b/docs/release-control/v6/internal/subsystems/monitoring.md
index 4b625475ca..664c7bf48c 100644
--- a/docs/release-control/v6/internal/subsystems/monitoring.md
+++ b/docs/release-control/v6/internal/subsystems/monitoring.md
@@ -17,6 +17,21 @@
## Purpose
+### Locally built images report an uncheckable update state (21 October 2026)
+
+An image with no RepoDigest was built or loaded on its host, so no registry
+holds a copy to compare against. The Docker agent reports such a container's
+update status with the `local image` sentinel and no digests, and does not
+query a registry. Previously it asked Docker Hub for the unknown repository and
+reported the resulting `authentication required` as a failed check on every
+cycle. Like `digest-pinned image`, the sentinel is a state, not a failure:
+update alerts already ignore update-check errors, and the presentation reads it
+as Local. `TestCollectContainerReportsLocallyBuiltImageWithoutRegistryCheck`
+covers the collect path without network access, and
+`TestGenerateDockerContainerUpdateStatusLocalImageShape` keeps the mock
+fixtures to the same shape.
+
+
### Storage investigation history shares the chart source boundary
`ReadStorageMetricHistory` and `GetStorageMetricsForChart` use the same monitor
diff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.md
index 86dcee7881..384fec5f20 100644
--- a/docs/release-control/v6/internal/subsystems/unified-resources.md
+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md
@@ -23,6 +23,21 @@ and sort the complete canonical change table while startup and ingestion wait.
## Purpose
+### Websocket-first routes always obtain their REST snapshot (21 October 2026)
+
+Action readiness, scoped facets and other REST-only enrichment arrive only
+from the REST resource endpoints. A `prefer-ws-then-rest` route that mounted on
+a cache seeded from the websocket-fed all-resources cache (in-app navigation
+from another platform page) read that cache as fresh, and websocket ticks kept
+it fresh, so neither the mount fetch nor the delayed revalidation ever reached
+REST. The Docker table then offered container updates that the server had
+already refused. Each cache entry now records `canonicalAt`, set only by a REST
+fetch; such a route revalidates in the background at mount when its REST
+snapshot is absent or older than the cache window, and the delayed revalidation
+forces the network. `revalidates a prefer-ws-then-rest screen seeded from a
+websocket-only cache on mount` covers the navigation path.
+
+
### Docker object aliases do not identify their reporting host
Containers and other Docker child objects own their native IDs, names and
diff --git a/frontend-modern/browser-verification/a99061ff28286666.json b/frontend-modern/browser-verification/a99061ff28286666.json
new file mode 100644
index 0000000000..ccdadcc9ee
--- /dev/null
+++ b/frontend-modern/browser-verification/a99061ff28286666.json
@@ -0,0 +1,56 @@
+{
+ "version": 1,
+ "base_sha": "29bf5e8a4735cfaa46cabcccc0c76254fad81735",
+ "verified_at": "2026-10-21T14:05:00Z",
+ "result": "passed",
+ "changed_paths": [
+ "frontend-modern/src/components/Infrastructure/ResourceDetailSummary.tsx",
+ "frontend-modern/src/components/shared/ContainerUpdateBadge.tsx",
+ "frontend-modern/src/components/shared/containerUpdateBadgeModel.ts",
+ "frontend-modern/src/components/shared/useContainerUpdateButtonState.ts",
+ "frontend-modern/src/features/docker/DockerContainersTable.tsx",
+ "frontend-modern/src/features/docker/dockerContainerUpdateAction.ts",
+ "frontend-modern/src/features/docker/dockerImagePresentation.ts",
+ "frontend-modern/src/hooks/useUnifiedResources.ts"
+ ],
+ "content_sha256": {
+ "frontend-modern/src/components/Infrastructure/ResourceDetailSummary.tsx": "ccdbcfc46829547ac9e1c3940b471a6b6fad2558c0cb7721c36c2a1d976c029f",
+ "frontend-modern/src/components/shared/ContainerUpdateBadge.tsx": "1d7419040931208f4c69aed65c5148b2335809164a28a37fc2bef441326f772c",
+ "frontend-modern/src/components/shared/containerUpdateBadgeModel.ts": "153d124acbdb8e2af4813bf16409fab5ad76b28e305753a068496cb51b0b73d3",
+ "frontend-modern/src/components/shared/useContainerUpdateButtonState.ts": "494a1795d9d0ceb5706bc53fd760ef8aa8a0305f98c36512ce1ec276fec2909a",
+ "frontend-modern/src/features/docker/DockerContainersTable.tsx": "a3973c2d7eeca063eb5cdc369cf011ed3e42bbf139701162ce0f46e80f372310",
+ "frontend-modern/src/features/docker/dockerContainerUpdateAction.ts": "6d9def6f77718588fbe6e1b040f50857c0212abd7444e7a627e34f39594b8e98",
+ "frontend-modern/src/features/docker/dockerImagePresentation.ts": "124d077230a3612d3d86c0973e95e6d8f88cccad83949824ab451f76df5d54f0",
+ "frontend-modern/src/hooks/useUnifiedResources.ts": "0bf60bbb2b5bbf11d7d867a77c263dd0388b587f174a1da62a71200c770a6ac7"
+ },
+ "routes": [
+ "/proxmox",
+ "/docker/overview"
+ ],
+ "viewports": [
+ {
+ "width": 1024,
+ "height": 768
+ },
+ {
+ "width": 375,
+ "height": 812
+ }
+ ],
+ "states": [
+ "Docker overview reached by in-app navigation from Proxmox with the websocket already live: one REST /api/resources request within about 0.4 s of the click (previously none)",
+ "Containers whose update the server refuses (command agent disconnected) render the locked amber Update pill, no live Update button (previously 16 live buttons)",
+ "Host agent installed without command access: explanation names the host and the Settings \u2192 Infrastructure install option",
+ "Host with no agent facet: explanation falls back to the server refusal reason",
+ "Containers on a host with stale inventory (no update capability advertised): locked pill reading Podman inventory for this host is stale",
+ "Locally built image shows Local with its tooltip instead of Check failed",
+ "Locked pill measured 74 px inside a 116 px Updates cell at 1024 px; no clipping and no page overflow at 375 px",
+ "Container drawer Worth checking row shows Image update Available with the locked Update pill and View image tags link"
+ ],
+ "interactions": [
+ "Clicked the Docker top-navigation link from /proxmox and sampled the table at 0.3, 1, 3 and 8 seconds",
+ "Hovered a locked Update pill to show its explanation tooltip",
+ "Expanded the nginx-edge container row to open its drawer",
+ "Resized to the mobile viewport and reloaded the Docker overview"
+ ]
+}
diff --git a/frontend-modern/src/components/Infrastructure/ResourceDetailSummary.tsx b/frontend-modern/src/components/Infrastructure/ResourceDetailSummary.tsx
index dde957331b..68fd71c7be 100644
--- a/frontend-modern/src/components/Infrastructure/ResourceDetailSummary.tsx
+++ b/frontend-modern/src/components/Infrastructure/ResourceDetailSummary.tsx
@@ -1,6 +1,10 @@
import { For, Show, getOwner, runWithOwner, type Component, type JSX } from 'solid-js';
import type { Resource } from '@/types/resource';
-import { isContainerUpdatePinned } from '@/components/shared/containerUpdateBadgeModel';
+import {
+ isContainerUpdateLocalImage,
+ isContainerUpdatePinned,
+ isContainerUpdateUncheckable,
+} from '@/components/shared/containerUpdateBadgeModel';
import { DetailSectionTable } from '@/components/shared/DetailSectionTable';
import { MetadataBadge } from '@/components/shared/MetadataBadge';
import {
@@ -129,6 +133,7 @@ const ContainerUpdateNextSteps: Component<{ resource: Resource }> = (props) => {
updateStatus={update().updateStatus}
resourceId={update().resourceId}
actionReadiness={update().actionReadiness}
+ updateNotOfferedReason={update().updateNotOfferedReason}
touchTarget
/>
)}
@@ -174,11 +179,13 @@ const dockerSection = (
const updateState = update
? isContainerUpdatePinned(update)
? 'Pinned digest'
- : trimmedDockerValue(update.error)
- ? 'Check failed'
- : update.updateAvailable
- ? 'Available'
- : 'Current'
+ : isContainerUpdateLocalImage(update)
+ ? 'Local image'
+ : trimmedDockerValue(update.error)
+ ? 'Check failed'
+ : update.updateAvailable
+ ? 'Available'
+ : 'Current'
: '';
const image = trimmedDockerValue(docker.image);
const imageRegistryLink = update?.updateAvailable
@@ -189,7 +196,11 @@ const dockerSection = (
identityRow('Image', image),
makeDetailRow('Image update', updateState, {
title: update?.error,
- tone: update?.updateAvailable ? 'accent' : update?.error ? 'danger' : 'default',
+ tone: update?.updateAvailable
+ ? 'accent'
+ : update?.error && !isContainerUpdateUncheckable(update)
+ ? 'danger'
+ : 'default',
// An available update is something to act on: drawers lift it in front.
lift: update?.updateAvailable === true,
// An available update offers its next steps where it is stated.
diff --git a/frontend-modern/src/components/Infrastructure/__tests__/ResourceDetailDrawer.docker-container.test.tsx b/frontend-modern/src/components/Infrastructure/__tests__/ResourceDetailDrawer.docker-container.test.tsx
index 04ad7f25af..90484e8637 100644
--- a/frontend-modern/src/components/Infrastructure/__tests__/ResourceDetailDrawer.docker-container.test.tsx
+++ b/frontend-modern/src/components/Infrastructure/__tests__/ResourceDetailDrawer.docker-container.test.tsx
@@ -112,6 +112,14 @@ vi.mock('@/stores/notifications', () => ({
},
}));
+// The server advertises update on a container with an available update.
+const UPDATE_CAPABILITY = {
+ name: 'update',
+ type: 'common',
+ platform: 'docker',
+ minimumApprovalLevel: 'admin',
+} as NonNullable<Resource['capabilities']>[number];
+
const resource = (overrides: Partial<Resource>): Resource =>
({
id: overrides.id ?? 'app-container-1',
@@ -330,6 +338,7 @@ describe('ResourceDetailDrawer for Docker containers', () => {
lastChecked: '2026-10-14T10:00:00Z',
},
},
+ capabilities: [UPDATE_CAPABILITY],
})}
/>
));
@@ -363,6 +372,7 @@ describe('ResourceDetailDrawer for Docker containers', () => {
createdAt: '2026-10-01T10:00:00Z',
updateStatus: { updateAvailable: true, lastChecked: '2026-10-14T10:00:00Z' },
},
+ capabilities: [UPDATE_CAPABILITY],
});
const [current, setCurrent] = createSignal(proxy(10));
render(() => <ResourceDetailDrawer presentation="table-row" resource={current()} />);
@@ -403,7 +413,7 @@ describe('ResourceDetailDrawer for Docker containers', () => {
const locked = within(lifted).getByLabelText(
/Pulse cannot apply it: Command agent disconnected/,
);
- expect(locked).toHaveTextContent('Update available');
+ expect(locked).toHaveTextContent('Update');
expect(locked).toHaveClass('max-sm:min-h-11');
expect(within(lifted).queryByRole('button')).toBeNull();
});
@@ -424,6 +434,7 @@ describe('ResourceDetailDrawer for Docker containers', () => {
createdAt: '2026-10-01T10:00:00Z',
updateStatus: { updateAvailable: true, lastChecked: '2026-10-14T10:00:00Z' },
},
+ capabilities: [UPDATE_CAPABILITY],
});
const [current, setCurrent] = createSignal(proxy(10));
render(() => <ResourceDetailDrawer presentation="table-row" resource={current()} />);
diff --git a/frontend-modern/src/components/shared/ContainerUpdateBadge.tsx b/frontend-modern/src/components/shared/ContainerUpdateBadge.tsx
index 9e72185576..8501f25f00 100644
--- a/frontend-modern/src/components/shared/ContainerUpdateBadge.tsx
+++ b/frontend-modern/src/components/shared/ContainerUpdateBadge.tsx
@@ -6,13 +6,14 @@ import {
getContainerUpdateBadgeTooltip,
getContainerUpdateCurrentTooltip,
getContainerUpdateErrorTooltip,
- getContainerUpdatePinnedTooltip,
+ getContainerUpdateUncheckableLabel,
+ getContainerUpdateUncheckableTooltip,
getUpdateButtonClass,
getUpdateIconTooltip,
hasContainerUpdate,
hasContainerUpdateCurrent,
hasContainerUpdateError,
- isContainerUpdatePinned,
+ isContainerUpdateUncheckable,
type ContainerUpdateBadgeProps,
type UpdateButtonProps,
type UpdateIconProps,
@@ -79,7 +80,7 @@ export const ContainerUpdateBadge: Component<ContainerUpdateBadgeProps> = (props
when={
hasContainerUpdate(props.updateStatus) ||
hasContainerUpdateError(props.updateStatus) ||
- isContainerUpdatePinned(props.updateStatus) ||
+ isContainerUpdateUncheckable(props.updateStatus) ||
(props.showCurrent && hasContainerUpdateCurrent(props.updateStatus))
}
>
@@ -107,20 +108,25 @@ export const ContainerUpdateBadge: Component<ContainerUpdateBadgeProps> = (props
</Show>
</span>
</Match>
- <Match when={isContainerUpdatePinned(props.updateStatus)}>
+ <Match when={isContainerUpdateUncheckable(props.updateStatus)}>
<span
class="inline-flex items-center justify-center gap-1 rounded-full bg-surface-alt px-1.5 py-0.5 text-[11px] font-medium text-muted cursor-help"
- aria-label={getContainerUpdatePinnedTooltip()}
+ aria-label={getContainerUpdateUncheckableTooltip(props.updateStatus)}
onMouseEnter={(e) => {
const rect = e.currentTarget.getBoundingClientRect();
- showTooltip(getContainerUpdatePinnedTooltip(), rect.left + rect.width / 2, rect.top, {
- align: 'center',
- direction: 'up',
- });
+ showTooltip(
+ getContainerUpdateUncheckableTooltip(props.updateStatus),
+ rect.left + rect.width / 2,
+ rect.top,
+ {
+ align: 'center',
+ direction: 'up',
+ },
+ );
}}
onMouseLeave={() => hideTooltip()}
>
- <span>Pinned</span>
+ <span>{getContainerUpdateUncheckableLabel(props.updateStatus)}</span>
</span>
</Match>
<Match when={hasContainerUpdateError(props.updateStatus)}>
@@ -218,8 +224,7 @@ const UPDATE_TOUCH_TARGET_CLASS = ' max-sm:min-h-11 max-sm:px-3';
export const UpdateButton: Component<UpdateButtonProps> = (props) => {
const state = useContainerUpdateButtonState(props);
- const readOnlyUpdateExplanation = () =>
- `Update available. Pulse cannot apply it: ${state.updateUnavailableReason()}\nApply this update using your container manager on the host.`;
+ const readOnlyUpdateExplanation = () => state.updateUnavailableExplanation();
const showReadOnlyUpdateExplanation = (target: HTMLElement) => {
const rect = target.getBoundingClientRect();
showTooltip(readOnlyUpdateExplanation(), rect.left + rect.width / 2, rect.top, {
@@ -231,7 +236,7 @@ export const UpdateButton: Component<UpdateButtonProps> = (props) => {
state.currentState() === 'idle' &&
(hasContainerUpdateError(props.updateStatus) ||
hasContainerUpdateCurrent(props.updateStatus) ||
- isContainerUpdatePinned(props.updateStatus) ||
+ isContainerUpdateUncheckable(props.updateStatus) ||
state.isUpdateUnavailable() ||
(state.settingsLoaded() && state.shouldHideButton()));
@@ -332,7 +337,9 @@ export const UpdateButton: Component<UpdateButtonProps> = (props) => {
}}
>
<LockIcon class="h-3 w-3 shrink-0" aria-hidden="true" />
- <span>Update available</span>
+ {/* "Update" fits the Updates column at its narrowest; the lock,
+ amber tone and explanation state that Pulse cannot apply it. */}
+ <span>Update</span>
</span>
</Show>
</Show>
diff --git a/frontend-modern/src/components/shared/__tests__/ContainerUpdateBadge.test.tsx b/frontend-modern/src/components/shared/__tests__/ContainerUpdateBadge.test.tsx
index a408400ae2..ab0569bf2b 100644
--- a/frontend-modern/src/components/shared/__tests__/ContainerUpdateBadge.test.tsx
+++ b/frontend-modern/src/components/shared/__tests__/ContainerUpdateBadge.test.tsx
@@ -187,7 +187,7 @@ describe('ContainerUpdateBadge', () => {
));
expect(screen.queryByRole('button')).not.toBeInTheDocument();
- expect(screen.getByText('Update available')).toBeInTheDocument();
+ expect(screen.getByText('Update')).toBeInTheDocument();
const status = screen.getByLabelText(/Pulse cannot apply it/);
expect(status.getAttribute('aria-label')).toContain(
'The Pulse agent on this host is still on an older version.',
@@ -197,6 +197,59 @@ describe('ContainerUpdateBadge', () => {
expect(ResourceActionsAPI.planAction).not.toHaveBeenCalled();
});
+ it('offers no update the server does not advertise', () => {
+ render(() => (
+ <UpdateButton
+ agentId="agent-1"
+ containerId="container-1"
+ containerName="branch-vpn"
+ resourceId="resource-1"
+ updateNotOfferedReason="Docker inventory for this host is offline."
+ updateStatus={{
+ updateAvailable: true,
+ currentDigest: 'sha256:current',
+ latestDigest: 'sha256:latest',
+ lastChecked: 0,
+ }}
+ />
+ ));
+
+ expect(screen.queryByRole('button')).not.toBeInTheDocument();
+ expect(screen.getByLabelText(/Docker inventory for this host is offline/)).toBeInTheDocument();
+ });
+
+ it('tells a host without command access how to turn it on', () => {
+ render(() => (
+ <UpdateButton
+ agentId="agent-1"
+ containerId="container-1"
+ containerName="sonarr"
+ resourceId="resource-1"
+ actionReadiness={[
+ {
+ name: 'update',
+ available: false,
+ reasonCode: 'command_agent_disconnected',
+ reason: 'Docker / Podman command agent is not connected.',
+ },
+ ]}
+ hostName="Tower"
+ hostCommandsEnabled={false}
+ updateStatus={{
+ updateAvailable: true,
+ currentDigest: 'sha256:current',
+ latestDigest: 'sha256:latest',
+ lastChecked: 0,
+ }}
+ />
+ ));
+
+ expect(screen.queryByRole('button')).not.toBeInTheDocument();
+ const status = screen.getByLabelText(/installed without command access/);
+ expect(status.getAttribute('aria-label')).toContain('the Pulse agent on Tower');
+ expect(status.getAttribute('aria-label')).toContain('Settings → Infrastructure');
+ });
+
it('keeps the button enabled when the update readiness entry is available', () => {
render(() => (
<UpdateButton
diff --git a/frontend-modern/src/components/shared/__tests__/containerUpdateBadgeModel.unavailable.test.ts b/frontend-modern/src/components/shared/__tests__/containerUpdateBadgeModel.unavailable.test.ts
new file mode 100644
index 0000000000..f200b24cdd
--- /dev/null
+++ b/frontend-modern/src/components/shared/__tests__/containerUpdateBadgeModel.unavailable.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import {
+ getContainerUpdateUncheckableLabel,
+ getUpdateUnavailableExplanation,
+ hasContainerUpdateError,
+ isContainerUpdateUncheckable,
+} from '@/components/shared/containerUpdateBadgeModel';
+
+const disconnected = {
+ reason: 'Docker / Podman command agent is not connected.',
+ reasonCode: 'command_agent_disconnected',
+ hostName: 'Tower',
+};
+
+describe('locked update explanation', () => {
+ it('names a missing command access and where to turn it on', () => {
+ const text = getUpdateUnavailableExplanation({ ...disconnected, hostCommandsEnabled: false });
+ expect(text).toContain('the Pulse agent on Tower was installed without command access');
+ expect(text).toContain('Settings → Infrastructure');
+ expect(text).toContain('"Enable legacy combined command profile"');
+ expect(text).not.toContain('not connected');
+ });
+
+ it('tells a lost command channel apart from missing access', () => {
+ const text = getUpdateUnavailableExplanation({ ...disconnected, hostCommandsEnabled: true });
+ expect(text).toContain('the command channel to the Pulse agent on Tower is not connected');
+ expect(text).not.toContain('reinstall');
+ });
+
+ it("falls back to the server's reason when command access is unknown", () => {
+ expect(getUpdateUnavailableExplanation(disconnected)).toBe(
+ 'Update available. Pulse cannot apply it: Docker / Podman command agent is not connected.\n' +
+ 'Apply this update using your container manager on the host.',
+ );
+ expect(
+ getUpdateUnavailableExplanation({
+ reason: 'Docker / Podman inventory is not fresh enough to run lifecycle actions.',
+ reasonCode: 'stale_inventory',
+ hostCommandsEnabled: false,
+ }),
+ ).toContain('inventory is not fresh enough');
+ });
+});
+
+describe('uncheckable images', () => {
+ it('reads a local image as its own state, not a failed check', () => {
+ const local = { updateAvailable: false, lastChecked: 0, error: 'local image' };
+ expect(isContainerUpdateUncheckable(local)).toBe(true);
+ expect(hasContainerUpdateError(local)).toBe(false);
+ expect(getContainerUpdateUncheckableLabel(local)).toBe('Local');
+ expect(getContainerUpdateUncheckableLabel({ error: 'digest-pinned image' })).toBe('Pinned');
+ expect(
+ hasContainerUpdateError({
+ updateAvailable: false,
+ lastChecked: 0,
+ error: 'authentication required',
+ }),
+ ).toBe(true);
+ });
+});
diff --git a/frontend-modern/src/components/shared/containerUpdateBadgeModel.ts b/frontend-modern/src/components/shared/containerUpdateBadgeModel.ts
index 9874a107fd..6e72590be3 100644
--- a/frontend-modern/src/components/shared/containerUpdateBadgeModel.ts
+++ b/frontend-modern/src/components/shared/containerUpdateBadgeModel.ts
@@ -23,6 +23,14 @@ export interface UpdateButtonProps {
// unavailable 'update' entry the button renders disabled with the refusal
// reason, instead of letting the click fail at POST /api/actions/plan.
actionReadiness?: ResourceActionReadiness[];
+ // Set when the server row does not advertise the update capability at all
+ // (no refusal is recorded then), with the reason to show instead.
+ updateNotOfferedReason?: string;
+ // The container's host and whether its Pulse agent was installed with
+ // command access. The server's refusal reads "not connected" either way;
+ // these let the locked badge say which, and what to do about it.
+ hostName?: string;
+ hostCommandsEnabled?: boolean;
compact?: boolean;
/**
* A 44px minimum height below the `sm` breakpoint, for a control a phone
@@ -59,12 +67,29 @@ export function hasContainerUpdate(updateStatus?: DockerContainerUpdateStatus):
// it as its own neutral state instead of "Check failed" (#1666).
const DIGEST_PINNED_SENTINEL = 'digest-pinned image';
+// Sentinel for an image built or loaded on the host: it has no RepoDigest, so
+// no registry holds a copy to compare against. Also not a failure.
+const LOCAL_IMAGE_SENTINEL = 'local image';
+
export function isContainerUpdatePinned(updateStatus?: { error?: string }): boolean {
return updateStatus?.error?.trim() === DIGEST_PINNED_SENTINEL;
}
+export function isContainerUpdateLocalImage(updateStatus?: { error?: string }): boolean {
+ return updateStatus?.error?.trim() === LOCAL_IMAGE_SENTINEL;
+}
+
+/** The image has no registry tag to check, which is a state, not a failed check. */
+export function isContainerUpdateUncheckable(updateStatus?: { error?: string }): boolean {
+ return isContainerUpdatePinned(updateStatus) || isContainerUpdateLocalImage(updateStatus);
+}
+
+export function getContainerUpdateUncheckableLabel(updateStatus?: { error?: string }): string {
+ return isContainerUpdateLocalImage(updateStatus) ? 'Local' : 'Pinned';
+}
+
export function hasContainerUpdateError(updateStatus?: DockerContainerUpdateStatus): boolean {
- return Boolean(updateStatus?.error) && !isContainerUpdatePinned(updateStatus);
+ return Boolean(updateStatus?.error) && !isContainerUpdateUncheckable(updateStatus);
}
export function hasContainerUpdateCurrent(updateStatus?: DockerContainerUpdateStatus): boolean {
@@ -79,6 +104,16 @@ export function getContainerUpdatePinnedTooltip(): string {
return 'This image is pinned to a specific digest, so there is no newer tag to check against';
}
+export function getContainerUpdateLocalImageTooltip(): string {
+ return 'This image was built or loaded on this host, so no registry has a newer version to check against';
+}
+
+export function getContainerUpdateUncheckableTooltip(updateStatus?: { error?: string }): string {
+ return isContainerUpdateLocalImage(updateStatus)
+ ? getContainerUpdateLocalImageTooltip()
+ : getContainerUpdatePinnedTooltip();
+}
+
export function getContainerUpdateCurrentTooltip(
updateStatus?: DockerContainerUpdateStatus,
): string {
@@ -88,6 +123,37 @@ export function getContainerUpdateCurrentTooltip(
return `Image is current\nDigest: ${current}...`;
}
+/**
+ * What the locked "Update available" badge says when Pulse cannot apply the
+ * update. An agent installed without command access is the common case and has
+ * one fix, so it is named outright instead of the server's transport wording.
+ */
+export function getUpdateUnavailableExplanation(input: {
+ reason: string;
+ reasonCode?: string;
+ hostName?: string;
+ hostCommandsEnabled?: boolean;
+}): string {
+ const host = input.hostName?.trim() || 'this host';
+ if (input.reasonCode === 'command_agent_disconnected') {
+ if (input.hostCommandsEnabled === false) {
+ return (
+ `Update available. Pulse cannot apply it because the Pulse agent on ${host} was installed without command access.\n` +
+ `To allow updates from Pulse, reinstall the agent from Settings → Infrastructure with ` +
+ '"Enable legacy combined command profile" selected in the advanced install options. ' +
+ 'Otherwise, apply the update with your container manager.'
+ );
+ }
+ if (input.hostCommandsEnabled === true) {
+ return (
+ `Update available. Pulse cannot apply it at the moment because the command channel to the Pulse agent on ${host} is not connected.\n` +
+ 'Check that the agent is running, or apply the update with your container manager.'
+ );
+ }
+ }
+ return `Update available. Pulse cannot apply it: ${input.reason}\nApply this update using your container manager on the host.`;
+}
+
export function getContainerUpdateBadgeTooltip(updateStatus?: DockerContainerUpdateStatus): string {
const current = getDigestPreview(updateStatus?.currentDigest, 19);
const latest = getDigestPreview(updateStatus?.latestDigest, 19);
diff --git a/frontend-modern/src/components/shared/useContainerUpdateButtonState.ts b/frontend-modern/src/components/shared/useContainerUpdateButtonState.ts
index 714ada7b91..90340ea2ae 100644
--- a/frontend-modern/src/components/shared/useContainerUpdateButtonState.ts
+++ b/frontend-modern/src/components/shared/useContainerUpdateButtonState.ts
@@ -15,10 +15,11 @@ import {
getUpdateButtonLabel,
getUpdateButtonTooltip,
getUpdatePlanErrorMessage,
+ getUpdateUnavailableExplanation,
hasContainerUpdate,
hasContainerUpdateCurrent,
hasContainerUpdateError,
- isContainerUpdatePinned,
+ isContainerUpdateUncheckable,
type UpdateButtonProps,
type UpdateState,
} from './containerUpdateBadgeModel';
@@ -70,19 +71,32 @@ export function useContainerUpdateButtonState(props: UpdateButtonProps) {
hasContainerUpdate(props.updateStatus) ||
hasContainerUpdateError(props.updateStatus) ||
hasContainerUpdateCurrent(props.updateStatus) ||
- isContainerUpdatePinned(props.updateStatus) ||
+ isContainerUpdateUncheckable(props.updateStatus) ||
currentState() !== 'idle';
// Server-evaluated refusal for the update capability (agent disconnected,
- // agent too old, stale inventory). Render a passive update status with the
- // reason instead of suggesting that Pulse can apply the update.
+ // agent too old, stale inventory), or the capability not advertised at all.
+ // Render a passive update status with the reason instead of suggesting that
+ // Pulse can apply the update.
// Only gates the actionable states; in-flight and settled states keep their
// own presentation.
const updateUnavailableReason = (): string | undefined => {
if (currentState() !== 'idle') return undefined;
- return getActionReadinessRefusal(props.actionReadiness, 'update');
+ return (
+ getActionReadinessRefusal(props.actionReadiness, 'update') ??
+ (hasContainerUpdate(props.updateStatus) ? props.updateNotOfferedReason : undefined)
+ );
};
const isUpdateUnavailable = () => Boolean(updateUnavailableReason());
+ const updateUnavailableExplanation = (): string =>
+ getUpdateUnavailableExplanation({
+ reason: updateUnavailableReason() ?? '',
+ reasonCode: props.actionReadiness?.find(
+ (item) => item.name?.trim().toLowerCase() === 'update' && item.available === false,
+ )?.reasonCode,
+ hostName: props.hostName,
+ hostCommandsEnabled: props.hostCommandsEnabled,
+ });
const isButtonDisabled = () =>
currentState() === 'updating' ||
@@ -209,6 +223,7 @@ export function useContainerUpdateButtonState(props: UpdateButtonProps) {
reviewDetail,
settingsLoaded,
shouldHideButton,
+ updateUnavailableExplanation,
updateUnavailableReason,
};
}
diff --git a/frontend-modern/src/features/docker/DockerContainersTable.tsx b/frontend-modern/src/features/docker/DockerContainersTable.tsx
index 3e6a38695a..291224041c 100644
--- a/frontend-modern/src/features/docker/DockerContainersTable.tsx
+++ b/frontend-modern/src/features/docker/DockerContainersTable.tsx
@@ -4,7 +4,10 @@ import { useSearchParams } from '@solidjs/router';
import { type FilterDef } from '@/components/shared/FilterBar';
import { UpdateButton } from '@/components/shared/ContainerUpdateBadge';
import { getDockerContainerUpdateAction } from './dockerContainerUpdateAction';
-import { isContainerUpdatePinned } from '@/components/shared/containerUpdateBadgeModel';
+import {
+ getContainerUpdateUncheckableLabel,
+ isContainerUpdateUncheckable,
+} from '@/components/shared/containerUpdateBadgeModel';
import {
GroupedTableModeSegmentedControl,
type GroupedTableMode,
@@ -186,7 +189,7 @@ const isContainerRunning = (resource: Resource): boolean =>
const updateStatusLabel = (resource: Resource): string => {
const update = resource.docker?.updateStatus;
if (!update) return '—';
- if (isContainerUpdatePinned(update)) return 'Pinned';
+ if (isContainerUpdateUncheckable(update)) return getContainerUpdateUncheckableLabel(update);
if (asTrimmedString(update.error)) return 'Error';
return update.updateAvailable ? 'Available' : 'Current';
};
@@ -450,6 +453,11 @@ export const DockerContainersTable: Component<DockerContainersTableProps> = (pro
? [...scopedRows()].sort(compareDockerContainers)
: sortedRows();
});
+ const hostResourceById = createMemo(() => {
+ const map = new Map<string, Resource>();
+ for (const hostResource of props.hosts ?? []) map.set(hostResource.id, hostResource);
+ return map;
+ });
const hostResourceByName = createMemo(() => {
const map = new Map<string, Resource>();
for (const hostResource of props.hosts ?? []) {
@@ -531,7 +539,11 @@ export const DockerContainersTable: Component<DockerContainersTableProps> = (pro
const mounts = () => mountsSummary(resource);
const updates = () => updateStatusLabel(resource);
const updateTitle = () => updateStatusTitle(resource);
- const action = getDockerContainerUpdateAction(resource);
+ // An accessor, not a value: action readiness can arrive after the row
+ // mounts (the REST revalidation follows a websocket paint), and a value
+ // captured at mount kept offering an update the server had refused.
+ const action = () =>
+ getDockerContainerUpdateAction(resource, hostResourceById().get(resource.parentId ?? ''));
const detailRowId = () => drawer.detailRowId(resource);
const isExpanded = () => drawer.isExpanded(resource);
const renderColumnCell = (column: DockerContainerTableColumn): JSX.Element => {
@@ -668,14 +680,26 @@ export const DockerContainersTable: Component<DockerContainersTableProps> = (pro
class={`${getPlatformTableCellClassForKind(column.kind)} text-base-content docker-container-update-cell`}
>
<Show
- when={action}
+ when={action()}
fallback={
<span class="block max-w-full truncate" title={updateTitle()}>
{updates()}
</span>
}
>
- {(updateAction) => <UpdateButton {...updateAction()} />}
+ {(updateAction) => (
+ <UpdateButton
+ agentId={updateAction().agentId}
+ containerId={updateAction().containerId}
+ containerName={updateAction().containerName}
+ updateStatus={updateAction().updateStatus}
+ resourceId={updateAction().resourceId}
+ actionReadiness={updateAction().actionReadiness}
+ updateNotOfferedReason={updateAction().updateNotOfferedReason}
+ hostName={updateAction().hostName}
+ hostCommandsEnabled={updateAction().hostCommandsEnabled}
+ />
+ )}
</Show>
</TableCell>
);
diff --git a/frontend-modern/src/features/docker/__tests__/DockerNativeTables.test.tsx b/frontend-modern/src/features/docker/__tests__/DockerNativeTables.test.tsx
index a387428e38..9f5140d975 100644
--- a/frontend-modern/src/features/docker/__tests__/DockerNativeTables.test.tsx
+++ b/frontend-modern/src/features/docker/__tests__/DockerNativeTables.test.tsx
@@ -1175,6 +1175,9 @@ describe('Docker native tables', () => {
lastChecked: '2026-05-24T13:00:00Z',
},
},
+ capabilities: [
+ { name: 'update', type: 'common', platform: 'docker', minimumApprovalLevel: 'admin' },
+ ],
}),
]}
emptyIcon={<span />}
diff --git a/frontend-modern/src/features/docker/__tests__/dockerContainerUpdateAction.test.ts b/frontend-modern/src/features/docker/__tests__/dockerContainerUpdateAction.test.ts
index 8f10da8d93..841568efd3 100644
--- a/frontend-modern/src/features/docker/__tests__/dockerContainerUpdateAction.test.ts
+++ b/frontend-modern/src/features/docker/__tests__/dockerContainerUpdateAction.test.ts
@@ -34,6 +34,55 @@ describe('docker container update action', () => {
});
});
+ it("names the host and reads its agent's command access", () => {
+ const resource = container({
+ hostSourceId: 'agent-tower',
+ containerId: 'abc',
+ updateStatus: { updateAvailable: true },
+ });
+ const host = (agent?: Record<string, unknown>) =>
+ ({ id: 'agent-tower', type: 'agent', name: 'tower', displayName: 'Tower', agent }) as never;
+
+ // The facet omits commandsEnabled when false: present facet, absent flag.
+ expect(getDockerContainerUpdateAction(resource, host({ agentId: 'a' }))).toMatchObject({
+ hostName: 'Tower',
+ hostCommandsEnabled: false,
+ });
+ expect(
+ getDockerContainerUpdateAction(resource, host({ commandsEnabled: true }))
+ ?.hostCommandsEnabled,
+ ).toBe(true);
+ // A Docker-only host reports no agent facet, so command access is unknown.
+ expect(getDockerContainerUpdateAction(resource, host())?.hostCommandsEnabled).toBeUndefined();
+ expect(getDockerContainerUpdateAction(resource)?.hostName).toBeUndefined();
+ });
+
+ it('says why no update is offered when the server does not advertise one', () => {
+ const update = {
+ hostSourceId: 'h',
+ containerId: 'abc',
+ runtime: 'docker',
+ updateStatus: { updateAvailable: true },
+ };
+ const withCapability = {
+ ...container(update),
+ capabilities: [{ name: 'update', type: 'common' }],
+ } as unknown as Resource;
+ expect(getDockerContainerUpdateAction(withCapability)?.updateNotOfferedReason).toBeUndefined();
+
+ // A host that stopped reporting: no capability and no readiness refusal.
+ const offline = {
+ ...container(update),
+ sourceStatus: { docker: { status: 'offline' } },
+ } as unknown as Resource;
+ expect(getDockerContainerUpdateAction(offline)?.updateNotOfferedReason).toBe(
+ 'Docker inventory for this host is offline.',
+ );
+ expect(getDockerContainerUpdateAction(container(update))?.updateNotOfferedReason).toBe(
+ 'Pulse does not currently offer an update action for this container.',
+ );
+ });
+
it('offers nothing a container cannot be updated through', () => {
const update = { updateAvailable: true };
expect(
diff --git a/frontend-modern/src/features/docker/__tests__/dockerImagePresentation.branchcov2.test.ts b/frontend-modern/src/features/docker/__tests__/dockerImagePresentation.branchcov2.test.ts
index c1498f8550..0a9158b422 100644
--- a/frontend-modern/src/features/docker/__tests__/dockerImagePresentation.branchcov2.test.ts
+++ b/frontend-modern/src/features/docker/__tests__/dockerImagePresentation.branchcov2.test.ts
@@ -388,6 +388,21 @@ describe('dockerImagePresentation.branchcov2', () => {
});
});
+ it('reads a locally built image as Local, not a failed check', () => {
+ const result = getDockerImageOperationalPresentation(
+ image({
+ docker: {
+ runtime: 'docker',
+ image: 'linkplayer-transcoder:latest',
+ updateStatus: { error: 'local image' },
+ },
+ }),
+ [],
+ );
+ expect(result.updateLabel).toBe('Local');
+ expect(result.updateTone).toBe('muted');
+ });
+
it('trims the error text for updateDetail', () => {
const result = getDockerImageOperationalPresentation(
image({
diff --git a/frontend-modern/src/features/docker/dockerContainerUpdateAction.ts b/frontend-modern/src/features/docker/dockerContainerUpdateAction.ts
index e8b872a8ca..e3f62c4d56 100644
--- a/frontend-modern/src/features/docker/dockerContainerUpdateAction.ts
+++ b/frontend-modern/src/features/docker/dockerContainerUpdateAction.ts
@@ -2,6 +2,22 @@ import type { DockerContainerUpdateStatus } from '@/types/api';
import type { Resource } from '@/types/resource';
import type { UpdateButtonProps } from '@/components/shared/containerUpdateBadgeModel';
import { asTrimmedString } from '@/utils/stringUtils';
+import { dockerContainerRuntimeLabel } from './dockerContainerLifecycleActions';
+
+const STALE_SOURCE_STATUSES = new Set(['stale', 'offline', 'missing']);
+
+// Why Pulse offers no update for a container whose server row does not
+// advertise the update capability. The server records a readiness refusal
+// only for capabilities it advertised, so a host that stopped reporting
+// leaves neither, and the button used to read that silence as available.
+const updateNotOfferedReason = (resource: Resource): string | undefined => {
+ if (resource.capabilities?.some((capability) => capability.name === 'update')) return undefined;
+ const status = (asTrimmedString(resource.sourceStatus?.docker?.status) ?? '').toLowerCase();
+ if (STALE_SOURCE_STATUSES.has(status)) {
+ return `${dockerContainerRuntimeLabel(resource)} inventory for this host is ${status}.`;
+ }
+ return 'Pulse does not currently offer an update action for this container.';
+};
const updateLastCheckedMillis = (lastChecked: string | undefined): number => {
if (!lastChecked) return 0;
@@ -32,10 +48,13 @@ export const getDockerContainerUpdateStatus = (
* Everything the shared `UpdateButton` needs for one container, or nothing
* when the container cannot be addressed for an update. The containers table
* and the container drawer both build their update control from this, so the
- * two offer the same action with the same readiness.
+ * two offer the same action with the same readiness. The host resource, where
+ * the caller has it, names the host and its agent's command access in the
+ * explanation shown when Pulse cannot apply the update.
*/
export const getDockerContainerUpdateAction = (
resource: Resource,
+ host?: Resource,
): UpdateButtonProps | undefined => {
const updateStatus = getDockerContainerUpdateStatus(resource);
const agentId = asTrimmedString(resource.docker?.hostSourceId);
@@ -53,5 +72,10 @@ export const getDockerContainerUpdateAction = (
updateStatus,
resourceId: resource.id,
actionReadiness: resource.actionReadiness,
+ updateNotOfferedReason: updateNotOfferedReason(resource),
+ hostName: asTrimmedString(host?.displayName) || asTrimmedString(host?.name) || undefined,
+ // The agent facet omits commandsEnabled when false, so its presence is
+ // what makes an absent flag mean "installed without command access".
+ hostCommandsEnabled: host?.agent ? host.agent.commandsEnabled === true : undefined,
};
};
diff --git a/frontend-modern/src/features/docker/dockerImagePresentation.ts b/frontend-modern/src/features/docker/dockerImagePresentation.ts
index a5d56b0bc3..abbb522db2 100644
--- a/frontend-modern/src/features/docker/dockerImagePresentation.ts
+++ b/frontend-modern/src/features/docker/dockerImagePresentation.ts
@@ -1,5 +1,9 @@
import type { Resource } from '@/types/resource';
-import { isContainerUpdatePinned } from '@/components/shared/containerUpdateBadgeModel';
+import {
+ isContainerUpdateLocalImage,
+ isContainerUpdatePinned,
+ isContainerUpdateUncheckable,
+} from '@/components/shared/containerUpdateBadgeModel';
import { asTrimmedString } from '@/utils/stringUtils';
export type DockerImageUpdateTone = 'danger' | 'warning' | 'success' | 'muted';
@@ -76,7 +80,7 @@ export function getDockerImageOperationalPresentation(
.map((resource) => resource.docker?.updateStatus)
.filter((state): state is NonNullable<typeof state> => state !== undefined);
const failed = updateStates.find(
- (state) => trimmed(state.error).length > 0 && !isContainerUpdatePinned(state),
+ (state) => trimmed(state.error).length > 0 && !isContainerUpdateUncheckable(state),
);
if (consumerCount > 0 && isPulseManagedImage(image)) {
@@ -116,6 +120,16 @@ export function getDockerImageOperationalPresentation(
updateTone: 'muted',
};
}
+ if (updateStates.some((state) => isContainerUpdateLocalImage(state))) {
+ return {
+ consumerCount,
+ consumerSummary: summarizeConsumers(consumers, reportedCount),
+ updateLabel: 'Local',
+ updateDetail:
+ 'The image was built or loaded on this host, so no registry has a newer version to check.',
+ updateTone: 'muted',
+ };
+ }
if (updateStates.some((state) => state.updateAvailable === false)) {
return {
consumerCount,
diff --git a/frontend-modern/src/hooks/__tests__/useUnifiedResources.test.ts b/frontend-modern/src/hooks/__tests__/useUnifiedResources.test.ts
index c18e955172..6e7f861dea 100644
--- a/frontend-modern/src/hooks/__tests__/useUnifiedResources.test.ts
+++ b/frontend-modern/src/hooks/__tests__/useUnifiedResources.test.ts
@@ -1366,6 +1366,65 @@ describe('useUnifiedResources', () => {
dispose();
});
+ it('revalidates a prefer-ws-then-rest screen seeded from a websocket-only cache on mount', async () => {
+ // In-app navigation onto a platform page: the all-resources cache is fed
+ // by the websocket alone, so the scoped route seeds from it and reads as
+ // fresh. Action readiness only arrives over REST, and a route that never
+ // fetched it offered Docker updates the server had already refused.
+ apiFetchMock.mockImplementation(() => new Promise(() => undefined));
+
+ let disposeAll = () => {};
+ let allResources: ReturnType<UseUnifiedResourcesModule['useUnifiedResources']> | undefined;
+ createRoot((d) => {
+ disposeAll = d;
+ allResources = useUnifiedResources({
+ query: '',
+ cacheKey: 'all-resources',
+ initialHydration: 'prefer-ws-then-rest',
+ });
+ });
+ await waitForResourceCount(() => allResources!.resources().length);
+ await flushAsync();
+ expect(apiFetchMock).not.toHaveBeenCalled();
+ disposeAll();
+
+ apiFetchMock.mockReset();
+ apiFetchMock.mockResolvedValue(
+ resourceResponse([
+ {
+ ...v2Resource,
+ actionReadiness: [
+ {
+ name: 'update',
+ available: false,
+ reasonCode: 'command_agent_disconnected',
+ reason: 'Docker / Podman command agent is not connected.',
+ },
+ ],
+ },
+ ]),
+ );
+
+ let disposeScoped = () => {};
+ let scoped: ReturnType<UseUnifiedResourcesModule['useUnifiedResources']> | undefined;
+ createRoot((d) => {
+ disposeScoped = d;
+ scoped = useUnifiedResources({
+ query: 'type=agent',
+ cacheKey: 'seeded-platform-overview',
+ initialHydration: 'prefer-ws-then-rest',
+ });
+ });
+
+ await flushAsync();
+ expect(scoped!.resources()[0]?.id).toBe('node-1');
+ expect(apiFetchMock).toHaveBeenCalledTimes(1);
+ await waitForValue(() => scoped!.resources()[0]?.actionReadiness?.[0]?.name, 'update');
+ expect(scoped!.loading()).toBe(false);
+
+ disposeScoped();
+ });
+
it('waits for the first canonical REST snapshot before painting immediate hydration screens', async () => {
let resolveFetch:
| ((value: { ok: true; json: () => Promise<{ data: Array<typeof v2Resource> }> }) => void)
diff --git a/frontend-modern/src/hooks/useUnifiedResources.ts b/frontend-modern/src/hooks/useUnifiedResources.ts
index f8d87b9d36..bc18008499 100644
--- a/frontend-modern/src/hooks/useUnifiedResources.ts
+++ b/frontend-modern/src/hooks/useUnifiedResources.ts
@@ -595,6 +595,11 @@ type UnifiedResourcesCacheEntry = {
hasSnapshot: boolean;
cachedAt: number;
lastFetchAt: number;
+ // When this entry last received the REST snapshot itself. Websocket ticks
+ // and all-resources seeding refresh cachedAt but carry none of the
+ // REST-only enrichment (action readiness, source status, scoped facets),
+ // so cachedAt alone cannot say whether that enrichment is current.
+ canonicalAt: number;
sharedFetch: Promise<Resource[]> | null;
realtimeVersion: number;
};
@@ -1144,6 +1149,7 @@ const getUnifiedResourcesCacheEntry = (cacheKey: string): UnifiedResourcesCacheE
hasSnapshot: false,
cachedAt: 0,
lastFetchAt: 0,
+ canonicalAt: 0,
sharedFetch: null,
realtimeVersion: 0,
};
@@ -1154,6 +1160,9 @@ const getUnifiedResourcesCacheEntry = (cacheKey: string): UnifiedResourcesCacheE
const hasFreshUnifiedResourcesCache = (entry: UnifiedResourcesCacheEntry) =>
entry.hasSnapshot && Date.now() - entry.cachedAt <= UNIFIED_RESOURCES_CACHE_MAX_AGE_MS;
+const hasFreshCanonicalSnapshot = (entry: UnifiedResourcesCacheEntry) =>
+ entry.canonicalAt > 0 && Date.now() - entry.canonicalAt <= UNIFIED_RESOURCES_CACHE_MAX_AGE_MS;
+
const setUnifiedResourcesCache = (
entry: UnifiedResourcesCacheEntry,
resources: Resource[],
@@ -1454,6 +1463,7 @@ const fetchUnifiedResourcesShared = async (
fetched.facets,
);
entry.lastFetchAt = now;
+ entry.canonicalAt = now;
return fetched.resources;
})();
@@ -1739,15 +1749,30 @@ export function useUnifiedResources(options?: UseUnifiedResourcesOptions) {
// before asking REST to enrich the thinner realtime snapshot.
canonicalRevalidationHandle = setTimeout(() => {
canonicalRevalidationHandle = undefined;
- if (!enabled()) {
+ if (!enabled() || cacheEntry.canonicalAt > 0) {
return;
}
- void runRefetch({ source: 'initial', background: true }).catch((err) => {
- logger.debug('[useUnifiedResources] Background canonical revalidation failed', err);
- });
+ revalidateCanonicalSnapshot();
}, UNIFIED_RESOURCES_WS_CANONICAL_REVALIDATE_DELAY_MS);
};
+ // Forced because websocket ticks keep cachedAt fresh: an unforced refetch
+ // would return the websocket-derived rows and never reach REST.
+ const revalidateCanonicalSnapshot = () => {
+ void runRefetch({ force: true, source: 'initial', background: true }).catch((err) => {
+ logger.debug('[useUnifiedResources] Background canonical revalidation failed', err);
+ });
+ };
+
+ // A `prefer-ws-then-rest` route can mount on a snapshot it did not fetch:
+ // seeded from the all-resources cache, or painted from the websocket on an
+ // earlier visit. Either reads as fresh while lacking the REST-only
+ // enrichment, so the route revalidates now instead of trusting it.
+ const needsCanonicalRevalidationOnMount = () =>
+ revalidatesRestAfterWsInitialHydration &&
+ cacheEntry.hasSnapshot &&
+ !hasFreshCanonicalSnapshot(cacheEntry);
+
createEffect(() => {
orgScope();
@@ -1763,6 +1788,9 @@ export function useUnifiedResources(options?: UseUnifiedResourcesOptions) {
if (hasFreshUnifiedResourcesCache(cacheEntry)) {
clearInitialHydrationTimeout();
+ if (untrack(needsCanonicalRevalidationOnMount)) {
+ revalidateCanonicalSnapshot();
+ }
return;
}
@@ -2127,6 +2155,8 @@ export function useUnifiedResources(options?: UseUnifiedResourcesOptions) {
} else {
void runRefetch({ force: true, source: 'initial' }).catch(() => undefined);
}
+ } else if (enabled() && needsCanonicalRevalidationOnMount()) {
+ revalidateCanonicalSnapshot();
}
});
diff --git a/internal/dockeragent/agent.go b/internal/dockeragent/agent.go
index 4872bdc4fe..971f202ab2 100644
--- a/internal/dockeragent/agent.go
+++ b/internal/dockeragent/agent.go
@@ -1686,7 +1686,7 @@ func summarizeManualUpdateCheck(report agentsdocker.Report) string {
continue
}
updateError := strings.TrimSpace(container.UpdateStatus.Error)
- if strings.EqualFold(updateError, "digest-pinned image") {
+ if strings.EqualFold(updateError, "digest-pinned image") || strings.EqualFold(updateError, localImageUpdateStatus) {
skipped++
continue
}
diff --git a/internal/dockeragent/agent_collect_test.go b/internal/dockeragent/agent_collect_test.go
index 187bbfa501..55e6ef7238 100644
--- a/internal/dockeragent/agent_collect_test.go
+++ b/internal/dockeragent/agent_collect_test.go
@@ -805,6 +805,51 @@ func TestAgentClose(t *testing.T) {
}
}
+// An image built or loaded on the host has no RepoDigests, so no registry
+// holds it. The agent used to ask Docker Hub anyway and reported the 401 for
+// the unknown repository as a failed check on every cycle.
+func TestCollectContainerReportsLocallyBuiltImageWithoutRegistryCheck(t *testing.T) {
+ inspect := baseInspect()
+ inspect.State = &containertypes.State{Running: false, Status: "exited"}
+ inspect.Config.Image = "local/proxmox-backup-server:4.2.3-1-20260729"
+ summary := containertypes.Summary{
+ ID: "container-pbs",
+ Names: []string{"/pbs"},
+ Image: "local/proxmox-backup-server:4.2.3-1-20260729",
+ ImageID: "sha256:pbslocal",
+ State: "exited",
+ Status: "Exited (0) 1 minute ago",
+ }
+
+ checker := NewRegistryChecker(zerolog.Nop())
+ checker.httpClient = &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+ t.Errorf("unexpected registry request to %s", req.URL)
+ return nil, errors.New("offline")
+ })}
+ agent := &Agent{
+ logger: zerolog.Nop(),
+ prevContainerCPU: make(map[string]cpuSample),
+ registryChecker: checker,
+ docker: &fakeDockerClient{
+ containerInspectWithRawFn: func(context.Context, string, bool) (containertypes.InspectResponse, []byte, error) {
+ return inspect, nil, nil
+ },
+ imageInspectWithRawFn: func(context.Context, string) (imagetypes.InspectResponse, []byte, error) {
+ return imagetypes.InspectResponse{Architecture: "amd64", Os: "linux"}, nil, nil
+ },
+ },
+ }
+
+ container, err := agent.collectContainer(context.Background(), summary)
+ if err != nil {
+ t.Fatalf("collect: %v", err)
+ }
+ status := container.UpdateStatus
+ if status == nil || status.UpdateAvailable || status.Error != localImageUpdateStatus {
+ t.Fatalf("locally built image reported %+v, want the %q state", status, localImageUpdateStatus)
+ }
+}
+
// A failed image inspect leaves the local digest unknown. Comparing an empty
// digest reported "no update available", which the server treats as an
// affirmative clear, so a pending update alert resolved and re-fired a whole
diff --git a/internal/dockeragent/agent_internal_test.go b/internal/dockeragent/agent_internal_test.go
index e7e034f91a..6d5275553c 100644
--- a/internal/dockeragent/agent_internal_test.go
+++ b/internal/dockeragent/agent_internal_test.go
@@ -1984,3 +1984,19 @@ func TestCollectContainerPodmanCPUIntervals(t *testing.T) {
})
}
}
+
+// Images with no registry tag to check are skipped by a manual update check,
+// not counted as checked or as registry errors.
+func TestSummarizeManualUpdateCheckSkipsUncheckableImages(t *testing.T) {
+ report := agentsdocker.Report{Containers: []agentsdocker.Container{
+ {UpdateStatus: &agentsdocker.UpdateStatus{Error: localImageUpdateStatus}},
+ {UpdateStatus: &agentsdocker.UpdateStatus{Error: "digest-pinned image"}},
+ {UpdateStatus: &agentsdocker.UpdateStatus{UpdateAvailable: true, CurrentDigest: "sha256:a"}},
+ {UpdateStatus: &agentsdocker.UpdateStatus{Error: "authentication required"}},
+ }}
+ got := summarizeManualUpdateCheck(report)
+ want := "Container update check completed: 2 checked, 1 updates available, 2 skipped, 1 registry errors"
+ if got != want {
+ t.Fatalf("summary = %q, want %q", got, want)
+ }
+}
diff --git a/internal/dockeragent/collect.go b/internal/dockeragent/collect.go
index 42dcda8e6f..5dc34ae144 100644
--- a/internal/dockeragent/collect.go
+++ b/internal/dockeragent/collect.go
@@ -821,6 +821,16 @@ func (a *Agent) collectContainer(ctx context.Context, summary containertypes.Sum
Str("container", container.Name).
Str("image", imageToCheck).
Msg("Skipping update check: local image digest unavailable")
+ } else if registry, _, _ := parseImageReference(imageToCheck); len(currentDigests) == 0 && registry != "" {
+ // An image with no RepoDigests was built or loaded on this host and
+ // never pulled, so no registry holds it to compare against. Asking
+ // anyway reads as a failed check ("authentication required" from
+ // Docker Hub for an unknown repository); report it as local.
+ container.UpdateStatus = &agentsdocker.UpdateStatus{
+ UpdateAvailable: false,
+ LastChecked: time.Now(),
+ Error: localImageUpdateStatus,
+ }
} else {
a.logger.Debug().
Str("container", container.Name).
diff --git a/internal/dockeragent/registry.go b/internal/dockeragent/registry.go
index 297465105c..9d652d1a88 100644
--- a/internal/dockeragent/registry.go
+++ b/internal/dockeragent/registry.go
@@ -238,6 +238,11 @@ func (r *RegistryChecker) ForceCheck() {
// broker's digest-pinned commands instead, so the generic checker stays out.
const proBrokerRegistry = "license.pulserelay.pro"
+// localImageUpdateStatus is the update-status sentinel for an image built or
+// loaded on the host, which no registry holds. Like "digest-pinned image" it
+// is not a failure, and Pulse's update surfaces render it as its own state.
+const localImageUpdateStatus = "local image"
+
// CheckImageUpdate checks if a newer version of the image is available.
func (r *RegistryChecker) CheckImageUpdate(ctx context.Context, image, currentDigest, arch, goos, variant string) *ImageUpdateResult {
if !r.Enabled() {
diff --git a/internal/mock/generator.go b/internal/mock/generator.go
index b29cc80d8d..d33645216b 100644
--- a/internal/mock/generator.go
+++ b/internal/mock/generator.go
@@ -4733,9 +4733,10 @@ func generateDockerContainers(hostName string, hostIdx int, config MockConfig, p
}
// generateDockerContainerUpdateStatus mirrors the states the docker agent's
-// registry checker reports: unchecked, current, update available, and the
-// digest-pinned sentinel for image@sha256 references (no error states, since
-// mock data also feeds the public demo).
+// registry checker reports: unchecked, current, update available, the
+// digest-pinned sentinel for image@sha256 references, and the local-image
+// sentinel for images built on the host (no error states, since mock data
+// also feeds the public demo).
func generateDockerContainerUpdateStatus(now time.Time) *models.DockerContainerUpdateStatus {
roll := rand.Float64()
if roll < 0.45 {
@@ -4746,8 +4747,12 @@ func generateDockerContainerUpdateStatus(now time.Time) *models.DockerContainerU
LastChecked: now.Add(-time.Duration(10+rand.Intn(170)) * time.Minute),
}
switch {
- case roll < 0.50:
+ case roll < 0.48:
status.Error = "digest-pinned image"
+ case roll < 0.50:
+ // A local image has no RepoDigest, so the agent reports no digest.
+ status.CurrentDigest = ""
+ status.Error = "local image"
case roll < 0.65:
status.UpdateAvailable = true
status.LatestDigest = fmt.Sprintf("sha256:%016x%016x%016x%016x", rand.Uint64(), rand.Uint64(), rand.Uint64(), rand.Uint64())
diff --git a/internal/mock/generator_test.go b/internal/mock/generator_test.go
index 9007091210..9395450507 100644
--- a/internal/mock/generator_test.go
+++ b/internal/mock/generator_test.go
@@ -1669,3 +1669,24 @@ func TestFixtureRefreshMovesCurrentGuestMemoryObservationTime(t *testing.T) {
})
}
}
+
+// The mock update states mirror what the agent reports. A local image has no
+// RepoDigest, so its status carries the sentinel and no digests, and is never
+// an available update.
+func TestGenerateDockerContainerUpdateStatusLocalImageShape(t *testing.T) {
+ now := time.Date(2026, 10, 21, 12, 0, 0, 0, time.UTC)
+ seen := false
+ for i := 0; i < 5000 && !seen; i++ {
+ status := generateDockerContainerUpdateStatus(now)
+ if status == nil || status.Error != "local image" {
+ continue
+ }
+ seen = true
+ if status.UpdateAvailable || status.CurrentDigest != "" || status.LatestDigest != "" {
+ t.Fatalf("local image status = %+v, want no update and no digests", status)
+ }
+ }
+ if !seen {
+ t.Fatal("generator never produced the local image state")
+ }
+}