@skyhook-io/radar-app 1.16.3 → 1.17.1

package/src/components/settings/SettingsDialog.tsx

@@ -23,7 +23,7 @@ import { AISettingsSection, type AIDraft } from '../diagnose/AISettings'
 import { MyPermissionsContent } from './MyPermissionsDialog'
 import { PrivacySection } from './PrivacySection'
 import { ConfigToggle, SubHeading } from './controls'
-import { useDiagnose } from '../diagnose/DiagnoseContext'
+import { useDiagnose, type DiagnoseSetup } from '../diagnose/DiagnoseContext'
 import { currencyOptionsForValue } from './currency-options'
 import { UpdateNotification } from '../ui/UpdateNotification'
 import {
@@ -856,11 +856,8 @@ export function SettingsDialog({
                 anonymous={argoSectionStatus?.connected && argoSectionStatus.anonymous}
                 connectedAddress={argoSectionStatus?.connected && !argoSectionStatus.anonymous ? argoSectionStatus.address : undefined}
                 active={section === 'argocd'}
-                statusReason={
-                  argoSectionStatus?.configured && !argoSectionStatus.connected
-                    ? argoSectionStatus.reason
-                    : undefined
-                }
+                statusReason={argoSectionStatus?.configured ? argoSectionStatus.reason : undefined}
+                connecting={argoSectionStatus?.connecting}
                 onChangeUrl={(v) => updateConfigField('argoCdUrl', v || undefined)}
                 onChangeInsecureTls={(v) => updateConfigField('argoCdInsecureTls', v || undefined)}
                 onApplied={({ url, insecureTls, tokenSet }) => {
@@ -924,7 +921,13 @@ export function SettingsDialog({
                   )}
                 </div>
               ) : (
-                <AIUnavailableNotice />
+                <AIUnavailableNotice
+                  setupState={diag.setupState}
+                  cliOverride={diag.cliOverride}
+                  checkingAgents={diag.checkingAgents}
+                  agentsCheckFailed={diag.agentsCheckFailed}
+                  recheckAgents={diag.recheckAgents}
+                />
               )}
             </div>
 
@@ -1212,7 +1215,7 @@ function OperatorSettingsSummary({ section, config }: { section: SettingsSection
       break
     case 'argocd':
       rows = [
-        ['Status', argoError ? 'Status unavailable' : !argo ? 'Checking…' : argo.connected ? 'Connected' : 'Not connected'],
+        ['Status', argoError ? 'Status unavailable' : !argo ? 'Checking…' : argo.connected ? 'Connected' : argo.connecting ? 'Connecting…' : 'Not connected'],
         ['Endpoint', argo?.address || c.argoCdUrl || 'Auto-discovery'],
         ['Token', config.argoCdTokenSet ? 'Configured' : 'None configured'],
         ['TLS verification', c.argoCdInsecureTls ? 'Disabled' : 'Enabled'],
@@ -1311,7 +1314,7 @@ function OverviewPanel({ active, onNavigate }: { active: boolean; onNavigate: (s
       : cost?.reason === 'access_denied'
         ? 'Your current permissions do not allow cost data.'
         : cost?.reason
-          ? costIntegrationUnavailableMessage(cost.reason) ?? 'The active cost source query failed.'
+          ? costIntegrationUnavailableMessage(cost.reason) ?? 'The active cost source could not provide data.'
           : undefined
 
   const rows: OverviewRow[] = [
@@ -1341,9 +1344,9 @@ function OverviewPanel({ active, onNavigate }: { active: boolean; onNavigate: (s
     },
     {
       id: 'argocd', icon: GitBranch, label: 'Argo CD',
-      tone: argo?.connected ? 'ok' : argo?.configured || argo?.reason ? 'warn' : 'off',
-      value: argo?.connected ? (argo.anonymous ? 'Connected · no token needed' : 'Connected') : 'Not connected',
-      detail: argo?.connected ? argo.address : argo?.reason ? 'Open Argo CD for connection details.' : undefined,
+      tone: argo?.connected ? (argo.reason ? 'warn' : 'ok') : argo?.connecting ? 'unknown' : argo?.configured || argo?.reason ? 'warn' : 'off',
+      value: argo?.connected ? (argo.anonymous ? 'Connected · no token needed' : 'Connected') : argo?.connecting ? 'Connecting…' : 'Not connected',
+      detail: argo?.reason ? 'Open Argo CD for connection details.' : argo?.connected ? argo.address : undefined,
     },
     {
       id: 'advanced', icon: Zap, label: 'MCP',
@@ -1354,8 +1357,7 @@ function OverviewPanel({ active, onNavigate }: { active: boolean; onNavigate: (s
     },
     {
       id: 'ai', icon: Sparkles, label: 'AI investigations',
-      tone: aiAvailable ? 'ok' : 'off',
-      value: aiAvailable ? 'Ready' : 'No agent CLI',
+      ...aiOverviewStatus(aiAvailable, diag.setupState, diag.cliOverride, diag.agentsCheckFailed),
       detail: aiAvailable ? agentLabel : undefined,
     },
   ]
@@ -1408,6 +1410,33 @@ function OverviewPanel({ active, onNavigate }: { active: boolean; onNavigate: (s
   )
 }
 
+// aiOverviewStatus says which reason applies, for the same reason
+// AIUnavailableNotice does: "No agent CLI" is a claim about the user's machine,
+// and it is false when RADAR_AI_CLI_BIN is what's broken, when an agent is
+// reported but off, when this deployment can't run investigations at all, or
+// when the agents probe hasn't answered.
+function aiOverviewStatus(
+  aiAvailable: boolean,
+  setupState: DiagnoseSetup,
+  cliOverride: boolean,
+  checkFailed: boolean,
+): Pick<OverviewRow, 'tone' | 'value'> {
+  if (aiAvailable) return { tone: 'ok', value: 'Ready' }
+  if (cliOverride && (setupState === 'needs-install' || setupState === 'needs-restart')) {
+    return { tone: 'warn', value: "RADAR_AI_CLI_BIN can't be run" }
+  }
+  switch (setupState) {
+    case 'unknown':
+      return checkFailed ? { tone: 'warn', value: "Couldn't check" } : { tone: 'unknown', value: 'Checking…' }
+    case 'needs-restart':
+      return { tone: 'warn', value: 'Not available right now' }
+    case 'off':
+      return { tone: 'off', value: 'Not available in this deployment' }
+    default:
+      return { tone: 'off', value: 'No agent CLI' }
+  }
+}
+
 function OverviewStatus({ tone }: { tone: OverviewTone }) {
   const cls =
     tone === 'ok' ? 'bg-green-500'
@@ -1417,24 +1446,95 @@ function OverviewStatus({ tone }: { tone: OverviewTone }) {
   return <span className={clsx('w-2 h-2 rounded-full shrink-0', cls)} />
 }
 
-// AIUnavailableNotice is the body of the AI investigations tab when no supported agent
-// CLI is installed — the heading/description are provided by the tab itself, so
-// this is just the enable explainer (keeping the feature discoverable to whoever
-// would set it up).
-function AIUnavailableNotice() {
-  return (
+// AIUnavailableNotice is the body of the AI investigations tab when the agent,
+// model and effort controls have nothing to configure. The tab supplies the
+// heading, so this is just the explainer.
+//
+// It must say WHICH of the reasons applies. "No supported agent CLI found" is a
+// claim about the user's machine, and when a CLI was found but investigations
+// didn't start it is false.
+function AIUnavailableNotice({
+  setupState,
+  cliOverride,
+  checkingAgents,
+  agentsCheckFailed,
+  recheckAgents,
+}: {
+  setupState: DiagnoseSetup
+  cliOverride: boolean
+  checkingAgents: boolean
+  agentsCheckFailed: boolean
+  recheckAgents: () => Promise<void>
+}) {
+  // The state the tab was in when a check started. "Still…" is only true when
+  // the finished check left it there.
+  const [checkedState, setCheckedState] = useState<DiagnoseSetup | null>(null)
+  const unchanged = checkedState === setupState && !checkingAgents && !agentsCheckFailed
+  const checkAgain = (
+    <button
+      type="button"
+      disabled={checkingAgents}
+      onClick={() => void recheckAgents().then(() => setCheckedState(setupState))}
+      className="mt-3 flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium btn-brand rounded-md disabled:opacity-50"
+    >
+      <RotateCw className={clsx('w-3.5 h-3.5', checkingAgents && 'animate-spin')} />
+      {checkingAgents ? 'Checking…' : 'Check again'}
+    </button>
+  )
+  const panel = (title: string, body?: ReactNode, action?: ReactNode) => (
     <div className="rounded-md border border-theme-border bg-theme-elevated/50 p-3">
-      <p className="text-sm font-medium text-theme-text-primary">No supported agent CLI found</p>
-      <p className="mt-1 text-xs text-theme-text-tertiary">
-        Install <span className="text-theme-text-secondary">Claude Code</span>,{' '}
-        <span className="text-theme-text-secondary">Codex</span>,{' '}
-        <span className="text-theme-text-secondary">Cursor</span> (
-        <span className="font-mono">cursor-agent</span>), or{' '}
-        <span className="text-theme-text-secondary">OpenCode</span>, then restart Radar — this tab
-        will show the agent, model, and effort controls.
-      </p>
+      <p className="text-sm font-medium text-theme-text-primary">{title}</p>
+      {body && <p className="mt-1 text-xs text-theme-text-tertiary">{body}</p>}
+      {action}
     </div>
   )
+  if (setupState === 'unknown') {
+    // The agent probe hasn't answered. Saying anything about the CLI or the
+    // deployment here would be a guess.
+    return agentsCheckFailed && !checkingAgents
+      ? panel("Couldn't check for agent CLIs", 'Try again.', checkAgain)
+      : panel('Checking…')
+  }
+  if (setupState === 'off') {
+    return panel(
+      'Not available in this deployment',
+      'They need Radar running on your own computer, with MCP on and sign-in off.',
+    )
+  }
+  if (cliOverride) {
+    return panel(
+      "Radar can't run your RADAR_AI_CLI_BIN",
+      <>
+        Fix the path, or remove it and restart Radar.
+        {unchanged && " Still can't run it."}
+      </>,
+      checkAgain,
+    )
+  }
+  if (setupState === 'needs-restart') {
+    return panel(
+      "AI investigations aren't available right now",
+      <>
+        {agentsCheckFailed && !checkingAgents ? "Couldn't check. Try again." : 'Try again in a moment.'}
+        {unchanged && ' Still not available.'}
+      </>,
+      checkAgain,
+    )
+  }
+  return panel(
+    'No supported agent CLI found',
+    <>
+      Install <span className="text-theme-text-secondary">Claude Code</span>,{' '}
+      <span className="text-theme-text-secondary">Codex</span>,{' '}
+      <span className="text-theme-text-secondary">Cursor</span> (
+      <span className="font-mono">cursor-agent</span>), or{' '}
+      <span className="text-theme-text-secondary">OpenCode</span>, and this tab will show the
+      agent, model, and effort controls.
+      {agentsCheckFailed && !checkingAgents && " Couldn't check. Try again."}
+      {unchanged && ' Still not found.'}
+    </>,
+    checkAgain,
+  )
 }
 
 // -- Startup section bodies ---------------------------------------------------
@@ -2125,6 +2225,7 @@ function ArgoCDConfigField({
   envError,
   cliSession,
   statusReason,
+  connecting,
   anonymous,
   connectedAddress,
   active,
@@ -2139,6 +2240,7 @@ function ArgoCDConfigField({
   envError?: string
   cliSession?: { server: string; user: string; insecure?: boolean }
   statusReason?: string
+  connecting?: boolean
   anonymous?: boolean
   connectedAddress?: string
   active?: boolean
@@ -2147,7 +2249,7 @@ function ArgoCDConfigField({
   onApplied?: (v: { url: string; insecureTls: boolean; tokenSet: boolean }) => void
 }) {
   if (envManaged) {
-    return <ArgoCDEnvManagedField url={url} insecureTls={insecureTls} envError={envError} connectedAddress={connectedAddress} statusReason={statusReason} />
+    return <ArgoCDEnvManagedField url={url} insecureTls={insecureTls} envError={envError} connectedAddress={connectedAddress} statusReason={statusReason} connecting={connecting} />
   }
   return (
     <ArgoCDEditableField
@@ -2156,6 +2258,7 @@ function ArgoCDConfigField({
       tokenSet={tokenSet}
       cliSession={cliSession}
       statusReason={statusReason}
+      connecting={connecting}
       anonymous={anonymous}
       connectedAddress={connectedAddress}
       active={active}
@@ -2176,6 +2279,7 @@ function ArgoCDEnvManagedField({
   envError,
   connectedAddress,
   statusReason,
+  connecting,
 }: {
   url: string
   insecureTls: boolean
@@ -2185,6 +2289,7 @@ function ArgoCDEnvManagedField({
   // so this is the one thing on it that can change after deploy.
   connectedAddress?: string
   statusReason?: string
+  connecting?: boolean
 }) {
   if (envError) {
     return (
@@ -2241,10 +2346,15 @@ function ArgoCDEnvManagedField({
             <dt className="w-24 shrink-0 text-theme-text-tertiary">Status</dt>
             <dd className="min-w-0 truncate text-theme-text-secondary">
               {connectedAddress ? (
-                <span className="inline-flex items-center gap-1">
-                  <Check className="w-3 h-3 shrink-0 text-green-600 dark:text-green-400/80" />
-                  Connected at {connectedAddress}
-                </span>
+                <>
+                  <span className="inline-flex items-center gap-1">
+                    <Check className="w-3 h-3 shrink-0 text-green-600 dark:text-green-400/80" />
+                    Connected at {connectedAddress}
+                  </span>
+                  {statusReason && <span className="block whitespace-normal text-warning-text">{statusReason}</span>}
+                </>
+              ) : connecting ? (
+                'Connecting…'
               ) : statusReason ? (
                 <span className="text-warning-text">Not connected — {statusReason}</span>
               ) : (
@@ -2274,6 +2384,7 @@ function ArgoCDEditableField({
   tokenSet,
   cliSession,
   statusReason,
+  connecting: serverConnecting,
   anonymous,
   connectedAddress,
   active,
@@ -2286,6 +2397,7 @@ function ArgoCDEditableField({
   tokenSet: boolean
   cliSession?: { server: string; user: string; insecure?: boolean }
   statusReason?: string
+  connecting?: boolean
   anonymous?: boolean
   connectedAddress?: string
   active?: boolean
@@ -2414,6 +2526,10 @@ function ArgoCDEditableField({
         </p>
       )}
 
+      {serverConnecting && state.status === 'idle' && !anonymous && !connectedAddress && (
+        <p className="mb-3 text-xs text-theme-text-secondary">Connecting to Argo CD…</p>
+      )}
+
       {statusReason && state.status !== 'connected' && (
         <div className="mb-3 rounded-md border border-theme-border bg-theme-elevated p-3">
           <p className="flex items-center gap-1.5 text-sm font-medium text-warning-text">

package/src/components/shared/LargeClusterNamespacePicker.tsx

@@ -1,10 +1,14 @@
-import { useState, useRef, useEffect, useMemo } from 'react'
+import { useState, useRef, useEffect, useMemo, type ReactNode } from 'react'
 import { Search } from 'lucide-react'
 import { Input } from '@skyhook-io/k8s-ui'
 
-export function LargeClusterNamespacePicker({ namespaces, onSelect }: {
+export function LargeClusterNamespacePicker({ namespaces, onSelect, ranked = false, renderMeta }: {
   namespaces: { name: string }[] | undefined
   onSelect: (ns: string) => void
+  /** Keep the given order (already ranked) instead of sorting by name. */
+  ranked?: boolean
+  /** Extra detail shown at the end of a namespace's row. */
+  renderMeta?: (name: string) => ReactNode
 }) {
   const [search, setSearch] = useState('')
   const inputRef = useRef<HTMLInputElement>(null)
@@ -15,8 +19,9 @@ export function LargeClusterNamespacePicker({ namespaces, onSelect }: {
 
   const sorted = useMemo(() => {
     if (!namespaces) return []
+    if (ranked) return namespaces
     return [...namespaces].sort((a, b) => a.name.localeCompare(b.name))
-  }, [namespaces])
+  }, [namespaces, ranked])
 
   const filtered = useMemo(() => {
     if (!search.trim()) return sorted
@@ -51,9 +56,10 @@ export function LargeClusterNamespacePicker({ namespaces, onSelect }: {
               key={ns.name}
               type="button"
               onClick={() => onSelect(ns.name)}
-              className="w-full text-left px-3 py-2 text-sm text-theme-text-primary hover:bg-theme-hover transition-colors border-b border-theme-border last:border-b-0"
+              className="w-full flex items-center justify-between gap-3 text-left px-3 py-2 text-sm text-theme-text-primary hover:bg-theme-hover transition-colors border-b border-theme-border last:border-b-0"
             >
-              {ns.name}
+              <span className="truncate">{ns.name}</span>
+              {renderMeta?.(ns.name)}
             </button>
           ))
         )}

package/src/components/timeline/TimelineList.tsx

@@ -1,6 +1,5 @@
 import { useState, useCallback, useMemo } from 'react'
 import {
-  SEVERITY_TEXT,
   TimelineList as TimelineListUI,
   eventsForApplication,
   isTimelineProblem,
@@ -13,9 +12,12 @@ import {
 import type { TimelineEvent } from '../../types'
 import { useTimelineSource } from '../../context/TimelineSource'
 import { isManagedTimelineEvent } from '../../api/timelineSource'
+import { TimelineRetentionBanner } from './TimelineRetentionNote'
 import { useHasLimitedAccess } from '../../contexts/CapabilitiesContext'
 import type { NavigateToResource } from '../../utils/navigation'
-import { AlertTriangle, RefreshCw } from 'lucide-react'
+import { TimelineLoadError, TimelineStaleNote } from './TimelineLoadError'
+import { useStickyError } from './useStickyError'
+import { ViewModeToggle } from './ViewModeToggle'
 
 export type { ActivityTypeFilter, ActivityFilterKey }
 
@@ -92,9 +94,10 @@ interface TimelineListProps {
   appScoped?: boolean
   topology?: Topology
   appScopeLoading?: boolean
+  onOpenDiagnostics?: () => void
 }
 
-export function TimelineList({ namespaces, onViewChange, currentView, onResourceClick, initialFilter, initialTimeRange, showDeleted, onShowDeletedChange, showRoutine, onShowRoutineChange, search, onSearchChange, activityFilter, onActivityFilterChange, kindFilter, onKindFilterChange, selectionWindow, onVisibleWindowChange, scrollToMs, focusedAppIndex, appScoped = false, topology, appScopeLoading = false }: TimelineListProps) {
+export function TimelineList({ namespaces, onViewChange, currentView, onResourceClick, initialFilter, initialTimeRange, showDeleted, onShowDeletedChange, showRoutine, onShowRoutineChange, search, onSearchChange, activityFilter, onActivityFilterChange, kindFilter, onKindFilterChange, selectionWindow, onVisibleWindowChange, scrollToMs, focusedAppIndex, appScoped = false, topology, appScopeLoading = false, onOpenDiagnostics }: TimelineListProps) {
   const hasLimitedAccess = useHasLimitedAccess()
   const timelineSource = useTimelineSource()
   const [queryParams, setQueryParams] = useState<{ timeRange: TimeRange; kinds: string[] }>({
@@ -111,7 +114,7 @@ export function TimelineList({ namespaces, onViewChange, currentView, onResource
   const splitRows = !appScoped
   // Uncapped when splitting: each part gets its own cap below. The rows come
   // from the loaded ring, so this costs no extra fetch.
-  const { data: fetchedEvents, isLoading, isError, error, refetch } = timelineSource.useEvents({
+  const { data: fetchedEvents, isLoading, isFetching, isError, error, refetch } = timelineSource.useEvents({
     namespaces,
     kinds: queryParams.kinds,
     timeRange: queryParams.timeRange,
@@ -122,6 +125,7 @@ export function TimelineList({ namespaces, onViewChange, currentView, onResource
     fromMs: selectionWindow?.fromMs,
     toMs: selectionWindow?.toMs,
   })
+  const loadError = useStickyError(error, fetchedEvents != null)
   const split = useMemo(
     () => (splitRows && fetchedEvents ? splitRoutineActivity(fetchedEvents, fetchLimit) : undefined),
     [splitRows, fetchedEvents, fetchLimit],
@@ -140,21 +144,22 @@ export function TimelineList({ namespaces, onViewChange, currentView, onResource
 
   // Full-screen error only when nothing is loaded; a failing background poll
   // with data on screen keeps rendering (data before error).
-  if (isError && !fetchedEvents) {
+  if (loadError && !fetchedEvents) {
     return (
-      <div className="flex flex-col items-center justify-center h-full text-theme-text-tertiary gap-3">
-        <AlertTriangle className="w-10 h-10 text-amber-400/70" />
-        <p className="text-base">Failed to load timeline data</p>
-        {error?.message?.trim() && (
-          <p className="max-w-md px-6 text-center text-sm text-theme-text-tertiary">{error.message.trim()}</p>
+      <div className="flex flex-col h-full">
+        {currentView && onViewChange && (
+          <div className="flex items-center justify-between px-4 py-2 border-b border-theme-border">
+            <div />
+            <ViewModeToggle viewMode={currentView} onViewModeChange={onViewChange} />
+          </div>
         )}
-        <button
-          onClick={() => refetch()}
-          className="flex items-center gap-2 px-3 py-1.5 text-sm bg-theme-elevated border border-theme-border-light rounded-lg hover:bg-theme-hover transition-colors"
-        >
-          <RefreshCw className="w-3.5 h-3.5" />
-          Try again
-        </button>
+        <TimelineLoadError
+          className="flex-1"
+          error={loadError}
+          retrying={isFetching}
+          onRetry={() => refetch()}
+          onOpenDiagnostics={onOpenDiagnostics}
+        />
       </div>
     )
   }
@@ -164,17 +169,13 @@ export function TimelineList({ namespaces, onViewChange, currentView, onResource
   // view-level banner already reports the shared failure, and a second note
   // would double up.
   const staleNote = isError && fetchedEvents && !selectionWindow ? (
-    <div className="flex items-center gap-1.5 border-b border-theme-border px-4 py-1.5 text-xs text-theme-text-tertiary">
-      <AlertTriangle className={`h-3.5 w-3.5 shrink-0 ${SEVERITY_TEXT.warning}`} />
-      Live updates are failing — the list may be stale.
-      <button type="button" onClick={() => refetch()} className="underline hover:text-theme-text-primary">
-        Retry now
-      </button>
-    </div>
+    <TimelineStaleNote error={error} subject="list" onRetry={() => refetch()} />
   ) : null
 
   return (
     <div className="flex h-full min-h-0 flex-1 flex-col">
+      {/* Under a scrubber TimelineView already shows the note above it. */}
+      {!selectionWindow && <TimelineRetentionBanner />}
       {staleNote}
       <div className="min-h-0 flex-1">
         <TimelineListUI

package/src/components/timeline/TimelineLoadError.test.tsx

@@ -0,0 +1,62 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+import { ApiError } from '../../api/client'
+import { TimelineLoadError, TimelineStaleNote } from './TimelineLoadError'
+
+const driverError = 'open PostgreSQL timeline database: dial tcp 10.0.0.5:5432: connect: connection refused'
+
+function databaseDown(): ApiError {
+  return new ApiError('Timeline history is unavailable because Radar can\'t connect to its PostgreSQL database.', 503, {
+    error_code: 'timeline_database_unreachable',
+    detail: driverError,
+  })
+}
+
+function render(error: Error, onOpenDiagnostics?: () => void): string {
+  return renderToStaticMarkup(
+    <TimelineLoadError error={error} onRetry={() => {}} onOpenDiagnostics={onOpenDiagnostics} />,
+  )
+}
+
+describe('TimelineLoadError', () => {
+  it('names the database and points to the logs when PostgreSQL is unreachable', () => {
+    const html = render(databaseDown(), () => {})
+    expect(html).toContain('Timeline history is unavailable')
+    expect(html).toContain('can&#x27;t connect to its PostgreSQL database')
+    expect(html).toContain('[timeline]')
+    // The driver's error names the database host; it belongs in the logs and
+    // diagnostics, not on the page.
+    expect(html).not.toContain(driverError)
+    expect(html).toContain('Open diagnostics')
+    expect(html).not.toContain('Failed to load timeline data')
+  })
+
+  it('omits the diagnostics link when the host cannot open diagnostics', () => {
+    expect(render(databaseDown())).not.toContain('Open diagnostics')
+  })
+
+  it('keeps the generic state, without a diagnostics link, for other failures', () => {
+    const html = render(new ApiError('upstream timed out', 502, { error: 'upstream timed out' }), () => {})
+    expect(html).toContain('Failed to load timeline data')
+    expect(html).toContain('upstream timed out')
+    expect(html).not.toContain('Open diagnostics')
+  })
+})
+
+describe('TimelineStaleNote', () => {
+  const note = (error: Error) =>
+    renderToStaticMarkup(<TimelineStaleNote error={error} subject="timeline" onRetry={() => {}} />)
+
+  it('names the database and points to the logs when PostgreSQL is the cause', () => {
+    const html = note(databaseDown())
+    expect(html).toContain('can&#x27;t connect to its PostgreSQL database, so the timeline may be stale')
+    expect(html).toContain('[timeline]')
+    expect(html).not.toContain(driverError)
+  })
+
+  it('keeps the generic note for other failures', () => {
+    const html = note(new ApiError('upstream timed out', 502, { error: 'upstream timed out' }))
+    expect(html).toContain('Live updates are failing, so the timeline may be stale')
+    expect(html).not.toContain('PostgreSQL')
+  })
+})

package/src/components/timeline/TimelineLoadError.tsx

@@ -0,0 +1,96 @@
+import { clsx } from 'clsx'
+import { AlertTriangle, Bug, RefreshCw } from 'lucide-react'
+import { timelineDatabaseError } from '../../api/client'
+import { SEVERITY_TEXT } from '@skyhook-io/k8s-ui'
+
+const SECONDARY_BUTTON =
+  'flex items-center gap-2 px-3 py-1.5 text-sm bg-theme-elevated border border-theme-border-light rounded-lg hover:bg-theme-hover transition-colors'
+
+// TimelineLoadError is the full-screen state when the timeline has nothing to
+// show. An unreachable PostgreSQL database gets its own copy: it says the
+// database is the problem and where to look. The driver's error stays in
+// Radar's logs and the diagnostics overlay.
+export function TimelineLoadError({
+  error,
+  onRetry,
+  retrying = false,
+  onOpenDiagnostics,
+  className,
+}: {
+  error?: Error | null
+  onRetry: () => void
+  /** A request is in flight: the error stays up, the button shows the attempt. */
+  retrying?: boolean
+  onOpenDiagnostics?: () => void
+  className?: string
+}) {
+  const databaseError = timelineDatabaseError(error)
+  const detail = error?.message?.trim()
+
+  return (
+    <div className={clsx('flex flex-col items-center justify-center text-theme-text-tertiary gap-3 px-6', className)}>
+      <AlertTriangle className="w-10 h-10 text-amber-400/70" />
+      {databaseError !== null ? (
+        <>
+          <p className="text-base text-theme-text-secondary">Timeline history is unavailable</p>
+          <p className="max-w-md text-center text-sm">
+            Radar can't connect to its PostgreSQL database, so changes aren't being recorded. It keeps
+            retrying, and this page recovers on its own once the database is back.
+          </p>
+          <p className="max-w-md text-center text-xs">
+            Radar's logs have the details: search them for <code className="font-mono">[timeline]</code>.
+          </p>
+        </>
+      ) : (
+        <>
+          <p className="text-base">Failed to load timeline data</p>
+          {detail && <p className="max-w-md text-center text-sm">{detail}</p>}
+        </>
+      )}
+      <div className="flex items-center gap-2">
+        <button type="button" onClick={onRetry} disabled={retrying} className={clsx(SECONDARY_BUTTON, 'disabled:opacity-60 disabled:cursor-default')}>
+          <RefreshCw className={clsx('w-3.5 h-3.5', retrying && 'animate-spin')} />
+          Try again
+        </button>
+        {databaseError !== null && onOpenDiagnostics && (
+          <button type="button" onClick={onOpenDiagnostics} className={SECONDARY_BUTTON}>
+            <Bug className="w-3.5 h-3.5" />
+            Open diagnostics
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// TimelineStaleNote is the banner over data that is still on screen while its
+// refresh fails. When the database is the cause it says so and where to look,
+// since the data underneath otherwise reads as current.
+export function TimelineStaleNote({
+  error,
+  subject,
+  onRetry,
+}: {
+  error?: Error | null
+  /** What may be stale: the swimlane view or the list. */
+  subject: 'timeline' | 'list'
+  onRetry: () => void
+}) {
+  const databaseDown = timelineDatabaseError(error) !== null
+  return (
+    <div className="flex items-center gap-1.5 border-b border-theme-border px-4 py-1.5 text-xs text-theme-text-tertiary">
+      <AlertTriangle className={`h-3.5 w-3.5 shrink-0 ${SEVERITY_TEXT.warning}`} />
+      {databaseDown ? (
+        <span>
+          Radar can't connect to its PostgreSQL database, so the {subject} may be stale. Search Radar's logs
+          for <code className="font-mono">[timeline]</code>.
+        </span>
+      ) : (
+        <span>Live updates are failing, so the {subject} may be stale.</span>
+      )}
+      <button type="button" onClick={onRetry} className="underline hover:text-theme-text-primary">
+        Retry now
+      </button>
+    </div>
+  )
+}