fix: distinguish failed image-update checks from "up to date" (#1470)

* fix: distinguish failed image-update checks from "up to date"

The image-update detector collapsed every failure (registry unreachable,
missing auth, rate limit, unresolved local digest) into hasUpdate:false and
dropped the captured reason, so a failed check was indistinguishable from a
current image and never raised a notification, even while a manual stack
update still pulled a newer image.

Detection now records a tri-state per stack (ok / partial / failed) with the
failure reason, exposed via a new GET /api/image-updates/detail (the boolean
GET / is unchanged so fleet aggregation is unaffected). A fully-failed check
preserves the last known has_update, so a transient outage neither erases a
real update nor flaps the notification state. The sidebar shows a muted
"couldn't check" indicator with the reason on hover, and the Update board
lists stacks whose check failed in a "could not be checked" advisory.

Detector hardening: the manifest digest lookup issues HEAD first (falling back
to GET) so it no longer draws down Docker Hub's anonymous pull-rate budget, and
local RepoDigest matching is normalized so official library/* images resolve
their digest instead of falling through to a silent "no update".

* fix: preserve confirmed updates through partial checks; tighten failure surfacing

Address review findings on the tri-state image-update detection:

- A partial check (some images errored) no longer erases a previously
  confirmed update; only a fully-ok check can lower has_update, so a single
  image's registry blip cannot drop the stack's update and re-fire the
  notification on recovery. Adds a regression test.
- The image-level catch stores getErrorMessage(e) rather than raw String(e),
  since that value surfaces verbatim in the sidebar tooltip and readiness
  advisory.
- useImageUpdates and the readiness detail fetch now log unexpected non-ok
  responses instead of silently leaving stale state.
- Remove an unused checkFailedCount derivation (the row indicator is driven by
  the checkStatus prop).
- Reword the recordStackCheckFailure docstring and the HEAD-first comment.

frontend/src/hooks/__tests__/useImageUpdates.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+
+vi.mock('@/lib/api', () => ({ apiFetch: vi.fn() }));
+
+import { apiFetch } from '@/lib/api';
+import { useImageUpdates } from '../useImageUpdates';
+
+const mockedFetch = apiFetch as unknown as ReturnType<typeof vi.fn>;
+
+describe('useImageUpdates', () => {
+  beforeEach(() => {
+    mockedFetch.mockReset();
+  });
+
+  it('loads the rich detail map from /image-updates/detail', async () => {
+    mockedFetch.mockImplementation((url: string) => {
+      if (url === '/image-updates/detail') {
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          json: async () => ({
+            web: { hasUpdate: true, checkStatus: 'ok', lastError: null, checkedAt: 5 },
+            api: { hasUpdate: false, checkStatus: 'failed', lastError: 'Registry unreachable', checkedAt: 6 },
+          }),
+        });
+      }
+      return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
+    });
+
+    const { result } = renderHook(() => useImageUpdates(1));
+
+    await waitFor(() => expect(result.current.stackUpdates.web).toBeDefined());
+    expect(result.current.stackUpdates.web.hasUpdate).toBe(true);
+    expect(result.current.stackUpdates.api.checkStatus).toBe('failed');
+    expect(result.current.stackUpdates.api.lastError).toBe('Registry unreachable');
+  });
+
+  it('falls back to the boolean map when /detail 404s (older remote node)', async () => {
+    mockedFetch.mockImplementation((url: string) => {
+      if (url === '/image-updates/detail') {
+        return Promise.resolve({ ok: false, status: 404, json: async () => ({}) });
+      }
+      if (url === '/image-updates') {
+        return Promise.resolve({ ok: true, status: 200, json: async () => ({ web: true, api: false }) });
+      }
+      return Promise.resolve({ ok: false, status: 500, json: async () => ({}) });
+    });
+
+    const { result } = renderHook(() => useImageUpdates(1));
+
+    await waitFor(() => expect(result.current.stackUpdates.web).toBeDefined());
+    // Boolean map is synthesized into the rich shape with checkStatus 'ok'.
+    expect(result.current.stackUpdates.web).toEqual({ hasUpdate: true, checkStatus: 'ok', lastError: null, checkedAt: 0 });
+    expect(result.current.stackUpdates.api.hasUpdate).toBe(false);
+  });
+});

frontend/src/hooks/useImageUpdates.ts

@@ -1,5 +1,6 @@
 import { useState, useEffect, useCallback, useRef } from 'react';
 import { apiFetch } from '@/lib/api';
+import type { StackUpdateInfo } from '@/types/imageUpdates';
 
 const IMAGE_UPDATE_POLL_MS = 5 * 60 * 1000;
 
@@ -15,15 +16,34 @@ const IMAGE_UPDATE_POLL_MS = 5 * 60 * 1000;
  * through the active-node header just like before.
  */
 export function useImageUpdates(activeNodeId: number | undefined) {
-  const [stackUpdates, setStackUpdates] = useState<Record<string, boolean>>({});
+  const [stackUpdates, setStackUpdates] = useState<Record<string, StackUpdateInfo>>({});
 
   const refresh = useCallback(async () => {
     try {
-      const res = await apiFetch('/image-updates');
+      const res = await apiFetch('/image-updates/detail');
       if (res.ok) {
-        const data = await res.json() as Record<string, boolean>;
-        setStackUpdates(data);
+        setStackUpdates(await res.json() as Record<string, StackUpdateInfo>);
+        return;
       }
+      // A remote node on an older Sencho lacks /detail; fall back to the boolean
+      // map so update badges keep working until that node is upgraded.
+      if (res.status === 404) {
+        const boolRes = await apiFetch('/image-updates');
+        if (boolRes.ok) {
+          const bool = await boolRes.json() as Record<string, boolean>;
+          const synthesized: Record<string, StackUpdateInfo> = {};
+          for (const [stack, hasUpdate] of Object.entries(bool)) {
+            synthesized[stack] = { hasUpdate, checkStatus: 'ok', lastError: null, checkedAt: 0 };
+          }
+          setStackUpdates(synthesized);
+        } else {
+          console.error('[ImageUpdates] /detail 404 fallback to /image-updates failed:', boolRes.status);
+        }
+        return;
+      }
+      // Any other non-ok (500, or a proxy 5xx from an unreachable remote): keep
+      // the last-known state on screen, but do not let the failure go silent.
+      console.error('[ImageUpdates] /image-updates/detail returned', res.status);
     } catch (e: unknown) {
       console.error('[ImageUpdates] fetch failed:', e);
     }