@skyhook-io/k8s-ui 1.19.0 → 1.20.0

package/src/utils/gitops-owner.test.ts

@@ -1,8 +1,8 @@
 import { describe, it, expect } from 'vitest'
 
-import type { Relationships } from '../types/core'
+import type { ManagerAnswer, Relationships } from '../types/core'
 
-import { gitOpsOwnerFromRelationships, managerListing } from './gitops-owner'
+import { argoAutoSyncController, gitOpsOwnerFromRelationships, managerListing } from './gitops-owner'
 
 describe('gitOpsOwnerFromRelationships', () => {
   it('returns null when relationships is undefined', () => {
@@ -134,3 +134,29 @@ describe('managerListing', () => {
     expect(managerListing(owner, [app('hub')], true, false)).toBeUndefined()
   })
 })
+
+describe('argoAutoSyncController', () => {
+  const self = { namespace: 'argocd', name: 'guestbook' }
+  const parent = { kind: 'Application', group: 'argoproj.io', namespace: 'argocd', name: 'apps' }
+  const managed = (state: ManagerAnswer['state'], lead = parent): Relationships => ({ ownership: { manager: { state, lead } } } as unknown as Relationships)
+
+  it('names the owning ApplicationSet first', () => {
+    const rel: Relationships = { ...managed('listed'), owner: { kind: 'ApplicationSet', group: 'argoproj.io', namespace: 'argocd', name: 'clusters' } }
+    expect(argoAutoSyncController(rel, self)).toEqual({ kind: 'ApplicationSet', name: 'clusters' })
+  })
+
+  it.each(['agree', 'listed'] as const)('names a parent Application whose resources list it (%s)', (state) => {
+    expect(argoAutoSyncController(managed(state), self)).toEqual({ kind: 'Application', name: 'apps' })
+  })
+
+  it.each(['claimed', 'shared', 'disagree', 'unknown', 'none'] as const)('names no parent on a %s answer', (state) => {
+    expect(argoAutoSyncController(managed(state), self)).toBeNull()
+  })
+
+  it('names nothing without an answer, for a non-Argo owner, or for itself', () => {
+    expect(argoAutoSyncController(undefined, self)).toBeNull()
+    expect(argoAutoSyncController({ managedBy: [parent] }, self)).toBeNull()
+    expect(argoAutoSyncController({ owner: { kind: 'ApplicationSet', group: 'example.com', namespace: 'argocd', name: 'x' } }, self)).toBeNull()
+    expect(argoAutoSyncController(managed('listed', { ...parent, name: 'guestbook' }), self)).toBeNull()
+  })
+})

package/src/utils/gitops-owner.ts

@@ -39,6 +39,25 @@ export function gitOpsOwnerFromRelationships(
   return gitOpsOwnerFromRef(refs[0])
 }
 
+/**
+ * The Argo CD object that rewrites an Application's spec, and so can turn its
+ * auto-sync back on after a suspend: the ApplicationSet that owns it, else the
+ * Application whose recorded resources list it. A tracking claim alone can
+ * outlive a detached parent, so it names nothing.
+ */
+export function argoAutoSyncController(
+  rel: Relationships | undefined | null,
+  self: { namespace: string; name: string },
+): { kind: 'ApplicationSet' | 'Application'; name: string } | null {
+  const appSet = [rel?.owner, ...(rel?.owners ?? [])].find(ref => ref?.kind === 'ApplicationSet' && ref.group === ARGO_APPLICATION_GROUP)
+  if (appSet) return { kind: 'ApplicationSet', name: appSet.name }
+  const answer = rel?.ownership?.manager
+  const lead = answer?.state === 'agree' || answer?.state === 'listed' ? answer.lead : undefined
+  return lead?.kind === 'Application' && lead.group === ARGO_APPLICATION_GROUP && !(lead.namespace === self.namespace && lead.name === self.name)
+    ? { kind: 'Application', name: lead.name }
+    : null
+}
+
 /** A manager ref (relationships.managedBy, a workspace's managedBy) as a GitOps owner, or null when the manager is not a GitOps controller. */
 export function gitOpsOwnerFromRef(ref: ResourceRef): GitOpsOwnerRef | null {
   switch (true) {

package/src/utils/kueue-queue-workloads.ts

@@ -0,0 +1,19 @@
+import type { KueueQueueWorkloadsResponse } from '../types/kueue-queues'
+import { readActionFor } from './read-actions'
+
+/**
+ * A response part a quick retry can complete: a nested read error or gap
+ * whose remedy is to retry (still loading, a failed read). A permission check
+ * that didn't run also clears on its own, but each poll spends more checks,
+ * and a load that is overdue (`wait`) won't clear in seconds: both wait for
+ * the ordinary refresh.
+ */
+export function kueueQueueRetryable(page: KueueQueueWorkloadsResponse | undefined): boolean {
+  if (!page) return false
+  const codes = [
+    page.workloadsError?.error_code, page.localQueuesError?.error_code,
+    ...(page.workloads?.coverage.gaps ?? []).map(gap => gap.code),
+    ...(page.localQueues?.coverage.gaps ?? []).map(gap => gap.code),
+  ]
+  return codes.some(code => code !== 'user_permission_check_failed' && readActionFor(code) === 'retry')
+}

package/src/utils/resource-icons.ts

@@ -52,6 +52,7 @@ import {
   // GitOps
   GitBranch,
   Layers,
+  ListVideo,
   Anchor,
   FolderGit2,
 
@@ -91,6 +92,7 @@ const KIND_ICON_MAP: Record<string, LucideIcon> = {
   replicaset: Copy,
   job: Play,
   cronjob: Timer,
+  jobset: ListVideo,
   rollout: Rocket,
 
   // Networking

package/src/utils/topology-neighborhood.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { batchRunParentNodes, neighborhoodFor, tagWorkloadOwnership, workloadKey } from './topology-neighborhood'
+import { batchRunParentNodes, jobSetMemberRunKey, neighborhoodFor, tagWorkloadOwnership, workloadKey } from './topology-neighborhood'
 import type { Topology, NodeKind, EdgeType } from '../types/core'
 
 function node(id: string, kind: string, ns: string, name: string): Topology['nodes'][number] {
@@ -455,3 +455,92 @@ describe('tagWorkloadOwnership', () => {
     expect(dataOf(topology, 'cert').ownerWorkloadId).toBe('Deployment/app/web')
   })
 })
+
+describe('JobSet ownership in the neighborhood', () => {
+  const jobSetID = 'jobset/ml/train/jobset.x-k8s.io'
+  const topo: Topology = {
+    nodes: [
+      crdNode(jobSetID, 'JobSet', 'ml', 'train', 'jobset.x-k8s.io/v1alpha2'),
+      crdNode('job/ml/train-workers-0', 'Job', 'ml', 'train-workers-0', 'batch/v1'),
+      crdNode('job/ml/train-workers-1', 'Job', 'ml', 'train-workers-1', 'batch/v1'),
+      node('pod/ml/train-workers-0-a', 'Pod', 'ml', 'train-workers-0-a'),
+      node('pod/ml/train-workers-1-a', 'Pod', 'ml', 'train-workers-1-a'),
+      crdNode('job/ml/standalone', 'Job', 'ml', 'standalone', 'batch/v1'),
+      crdNode('job/ml/train-workers-0/batch.volcano.sh', 'Job', 'ml', 'train-workers-0', 'batch.volcano.sh/v1alpha1'),
+    ],
+    edges: [
+      edge(jobSetID, 'job/ml/train-workers-0', 'manages'),
+      edge(jobSetID, 'job/ml/train-workers-1', 'manages'),
+      edge('job/ml/train-workers-0', 'pod/ml/train-workers-0-a', 'manages'),
+      edge('job/ml/train-workers-1', 'pod/ml/train-workers-1-a', 'manages'),
+      { ...edge(jobSetID, 'pod/ml/train-workers-0-a', 'manages'), id: 'shortcut-0', skipIfKindVisible: 'Job' },
+      { ...edge(jobSetID, 'job/ml/train-workers-0/batch.volcano.sh', 'manages'), id: 'foreign' },
+    ],
+  }
+
+  it('walks a JobSet down to every member Job and Pod, not capped as retained runs', () => {
+    const out = neighborhoodFor(topo, [{ kind: 'JobSet', group: 'jobset.x-k8s.io', namespace: 'ml', name: 'train' }])
+    const ids = new Set(out.nodes.map((n) => n.id))
+    for (const id of ['job/ml/train-workers-0', 'job/ml/train-workers-1', 'pod/ml/train-workers-0-a', 'pod/ml/train-workers-1-a']) {
+      expect(ids.has(id)).toBe(true)
+    }
+    expect(ids.has('job/ml/standalone')).toBe(false)
+    // Jobs are present, so the collapsed shortcut is dropped.
+    expect(out.edges.some((e) => e.id === 'shortcut-0')).toBe(false)
+    expect(out.warnings ?? []).toEqual([])
+  })
+
+  it('shows the JobSet as context from a member Job without pulling in sibling members', () => {
+    const out = neighborhoodFor(topo, [{ kind: 'Job', group: 'batch', namespace: 'ml', name: 'train-workers-1' }])
+    const ids = new Set(out.nodes.map((n) => n.id))
+    expect(ids.has(jobSetID)).toBe(true)
+    expect(ids.has('job/ml/train-workers-0')).toBe(false)
+  })
+
+  it('keys only directly controlled batch/v1 member Jobs for in-place selection', () => {
+    const byId = new Map(topo.nodes.map((n) => [n.id, n]))
+    expect(jobSetMemberRunKey(topo, jobSetID, byId.get('job/ml/train-workers-0')!)).toBe('jobs/ml/train-workers-0')
+    expect(batchRunParentNodes(topo, byId.get('job/ml/train-workers-0')!)).toEqual([byId.get(jobSetID)])
+    expect(batchRunParentNodes(topo, byId.get('job/ml/train-workers-0/batch.volcano.sh')!)).toEqual([])
+    expect(jobSetMemberRunKey(topo, jobSetID, byId.get('job/ml/standalone')!)).toBeUndefined()
+    expect(jobSetMemberRunKey(topo, jobSetID, byId.get('job/ml/train-workers-0/batch.volcano.sh')!)).toBeUndefined()
+    expect(jobSetMemberRunKey(topo, jobSetID, byId.get('pod/ml/train-workers-0-a')!)).toBeUndefined()
+    // Only a JobSet of the exact group selects members.
+    expect(jobSetMemberRunKey(topo, 'job/ml/train-workers-0', byId.get('pod/ml/train-workers-0-a')!)).toBeUndefined()
+  })
+})
+
+describe('JobSet member cap', () => {
+  it('keeps failed and active members first and says how many it left out', () => {
+    const jobSetID = 'jobset/ml/big/jobset.x-k8s.io'
+    const nodes: Topology['nodes'] = [crdNode(jobSetID, 'JobSet', 'ml', 'big', 'jobset.x-k8s.io/v1alpha2')]
+    const edges: Topology['edges'] = []
+    for (let i = 0; i < 40; i++) {
+      const id = `job/ml/big-w-${String(i).padStart(2, '0')}`
+      const job = { ...crdNode(id, 'Job', 'ml', `big-w-${String(i).padStart(2, '0')}`, 'batch/v1'), status: 'neutral' as const }
+      if (i === 39) job.status = 'unhealthy' as never
+      if (i === 38) job.data = { ...job.data, active: 1 }
+      if (i !== 38) job.data = { ...job.data, completionTime: '2026-11-01T00:00:00Z', succeeded: 1 }
+      nodes.push(job)
+      edges.push(edge(jobSetID, id, 'manages'))
+      const pod = `pod/ml/big-w-${i}-a`
+      nodes.push(node(pod, 'Pod', 'ml', `big-w-${i}-a`))
+      edges.push(edge(id, pod, 'manages'))
+      edges.push({ ...edge(jobSetID, pod, 'manages'), id: `shortcut-${i}`, skipIfKindVisible: 'Job' })
+    }
+    nodes.push(crdNode('workload/ml/big', 'Workload', 'ml', 'big', 'kueue.x-k8s.io/v1beta2'))
+    edges.push(edge(jobSetID, 'workload/ml/big', 'manages'))
+
+    const out = neighborhoodFor({ nodes, edges }, [{ kind: 'JobSet', group: 'jobset.x-k8s.io', namespace: 'ml', name: 'big' }])
+    const ids = new Set(out.nodes.map((n) => n.id))
+    const jobs = out.nodes.filter((n) => n.kind === 'Job')
+    expect(jobs).toHaveLength(24)
+    expect(ids.has('job/ml/big-w-39')).toBe(true) // failed first
+    expect(ids.has('job/ml/big-w-38')).toBe(true) // active next
+    // Pods only of the shown members: shortcuts don't bring back the rest.
+    expect(out.nodes.filter((n) => n.kind === 'Pod')).toHaveLength(24)
+    // Other things the JobSet owns aren't capped as members.
+    expect(ids.has('workload/ml/big')).toBe(true)
+    expect(out.warnings).toEqual(['Topology view: showing 24 of 40 member Jobs of JobSet/big, failed and active first. Find any member in the Overview\'s member list.'])
+  })
+})

package/src/utils/topology-neighborhood.ts

@@ -40,6 +40,9 @@ export interface NeighborhoodSeed {
 const IDENTITY_EDGES = new Set<EdgeType>(['manages'])
 const ROUTING_EDGES = new Set<EdgeType>(['exposes', 'routes-to'])
 const BATCH_RUN_FANOUT_LIMIT = 8
+// A JobSet's member Jobs run side by side, so they aren't thinned like
+// retained runs; past this many, the failed and active ones are kept first.
+const JOBSET_MEMBER_LIMIT = 24
 // context: 'configures' | 'uses' | 'protects' — everything else is leaf-attached.
 
 // GitOps managers: included as context ("managed by"), never expanded through.
@@ -92,9 +95,36 @@ function isBatchRunFanoutEdge(edge: TopologyEdge, nodeById: Map<string, Topology
   return isTemplateToRunEdge(edge, nodeById)
 }
 
+/** The member key (`jobs/<ns>/<name>`, the JobSet member list's selection key)
+ *  when `node` is a batch/v1 Job the JobSet node `jobSetNodeId` controls, by
+ *  its direct manages edge — the server draws that edge only for exact
+ *  controller-owned members. Undefined for anything else. */
+export function jobSetMemberRunKey(topology: Topology, jobSetNodeId: string, node: TopologyNode): string | undefined {
+  const root = topology.nodes.find((candidate) => candidate.id === jobSetNodeId)
+  if (!root || root.kind !== 'JobSet' || nodeGroup(root) !== 'jobset.x-k8s.io') return undefined
+  if (node.kind !== 'Job' || canonicalResourceGroup('Job', nodeGroup(node)) !== 'batch') return undefined
+  const member = topology.edges.some((edge) =>
+    edge.type === 'manages' && edge.source === root.id && edge.target === node.id && !edge.skipIfKindVisible,
+  )
+  return member ? `jobs/${nodeNamespace(node)}/${node.name}` : undefined
+}
+
+function isJobSetMemberEdge(edge: TopologyEdge, nodeById: Map<string, TopologyNode>): boolean {
+  const source = nodeById.get(edge.source)
+  const target = nodeById.get(edge.target)
+  return edge.type === 'manages' && !edge.skipIfKindVisible
+    && source?.kind === 'JobSet' && !!source && nodeGroup(source) === 'jobset.x-k8s.io'
+    && target?.kind === 'Job' && canonicalResourceGroup('Job', nodeGroup(target)) === 'batch'
+}
+
+function memberRank(node: TopologyNode): number {
+  if (node.status === 'unhealthy') return 0
+  return runDisposition(node) === 'active' ? 1 : 2
+}
+
 export function batchRunParentNodes(topology: Topology, run: TopologyNode): TopologyNode[] {
   const nodeById = new Map(topology.nodes.map((node) => [node.id, node]))
-  const parentEdges = topology.edges.filter((edge) => edge.target === run.id && isBatchRunFanoutEdge(edge, nodeById))
+  const parentEdges = topology.edges.filter((edge) => edge.target === run.id && (isBatchRunFanoutEdge(edge, nodeById) || isJobSetMemberEdge(edge, nodeById)))
   parentEdges.sort((left, right) => Number(right.type === 'manages') - Number(left.type === 'manages'))
   return parentEdges.flatMap((edge) => {
     const parent = nodeById.get(edge.source)
@@ -207,8 +237,24 @@ export function neighborhoodFor(topology: Topology, seeds: NeighborhoodSeed[]):
     }
   }
 
-  const limitedFanouts = new Map<string, { allowed: Set<string>; total: number; kind: string; activeTotal: number; activeShown: number }>()
+  const limitedFanouts = new Map<string, { allowed: Set<string>; total: number; kind: string; activeTotal: number; activeShown: number; members?: boolean }>()
   for (const [sourceId, edges] of adjacency) {
+    const memberEdges = edges.filter((edge) => edge.source === sourceId && isJobSetMemberEdge(edge, nodeById))
+    if (memberEdges.length > JOBSET_MEMBER_LIMIT) {
+      const members = memberEdges
+        .map((edge) => nodeById.get(edge.target))
+        .filter((node): node is TopologyNode => !!node)
+        .sort((a, b) => memberRank(a) - memberRank(b) || a.name.localeCompare(b.name))
+      limitedFanouts.set(sourceId, {
+        allowed: new Set(members.slice(0, JOBSET_MEMBER_LIMIT).map((node) => node.id)),
+        total: members.length,
+        kind: 'Job',
+        activeTotal: 0,
+        activeShown: 0,
+        members: true,
+      })
+      continue
+    }
     const runEdges = edges.filter((edge) => edge.source === sourceId && batchFanoutLimit(edge, nodeById) !== null)
     if (runEdges.length <= BATCH_RUN_FANOUT_LIMIT) continue
     const targets = runEdges
@@ -240,7 +286,10 @@ export function neighborhoodFor(topology: Topology, seeds: NeighborhoodSeed[]):
       const nextNode = nodeById.get(nextId)
       if (!nextNode) continue
       const fanout = e.source === id ? limitedFanouts.get(id) : undefined
-      if (fanout && !fanout.allowed.has(nextId)) {
+      // A capped JobSet's shortcuts to Pods would bring back the Pods of the
+      // members left out; the shown members still reach theirs.
+      if (fanout?.members && e.skipIfKindVisible) continue
+      if (fanout && (!fanout.members || isJobSetMemberEdge(e, nodeById)) && !fanout.allowed.has(nextId)) {
         cappedSources.add(id)
         continue
       }
@@ -308,6 +357,9 @@ export function neighborhoodFor(topology: Topology, seeds: NeighborhoodSeed[]):
       ...Array.from(cappedSources).map((sourceId) => {
         const source = nodeById.get(sourceId)
         const fanout = limitedFanouts.get(sourceId)
+        if (fanout?.members) {
+          return `Topology view: showing ${JOBSET_MEMBER_LIMIT} of ${fanout.total} member Jobs of ${source?.kind ?? 'JobSet'}/${source?.name ?? sourceId}, failed and active first. Find any member in the Overview's member list.`
+        }
         const activeNote = fanout && fanout.activeTotal > fanout.activeShown ? ` showing the ${fanout.activeShown - 1} newest and oldest of ${fanout.activeTotal} active runs plus representative completed runs` : ' showing active and representative completed runs'
         return `Topology view:${activeNote} from ${fanout?.total ?? BATCH_RUN_FANOUT_LIMIT} retained ${fanout?.kind ?? 'batch'} runs for ${source?.kind ?? 'workload'}/${source?.name ?? sourceId}. Use Run history for the full retained set.`
       }),

package/src/utils/workload-history-notes.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import { workloadHistoryNotes } from './workload-history-notes'
+
+describe('workloadHistoryNotes', () => {
+  it('says nothing when the history is complete and nothing is withheld', () => {
+    expect(workloadHistoryNotes(undefined, undefined)).toEqual([])
+    expect(workloadHistoryNotes({ incomplete: false, reasons: [] }, [])).toEqual([])
+  })
+
+  it('dates the start of complete history when the viewer may see the time', () => {
+    const since = '2026-11-03T05:00:00Z'
+    const [note] = workloadHistoryNotes({ incomplete: true, complete_since: since, reasons: ['observation_started_late'] })
+    expect(note).toBe(`Changes before ${new Date(since).toLocaleString()} may be missing: Radar began recording part of this history later.`)
+  })
+
+  it('names both reasons, and no time when the server withheld it', () => {
+    expect(workloadHistoryNotes({ incomplete: true, reasons: ['observation_started_late', 'events_evicted'] })).toEqual([
+      'Earlier changes may be missing: Radar began recording part of this history later and older history was deleted to stay within its limits.',
+    ])
+    expect(workloadHistoryNotes({ incomplete: true, reasons: ['something_new'] })).toEqual(['Earlier changes may be missing.'])
+  })
+
+  it('names the Kueue kinds a viewer may not list', () => {
+    expect(
+      workloadHistoryNotes(null, [
+        {
+          code: 'user_forbidden',
+          kinds: { count: 2, names: [{ kind: 'Workload', group: 'kueue.x-k8s.io' }, { kind: 'ProvisioningRequest', group: 'autoscaling.x-k8s.io' }] },
+          namespaces: { count: 1, names: ['ml'] },
+        },
+      ]),
+    ).toEqual(["Changes to Kueue Workloads and ProvisioningRequests aren't shown: you don't have access to list them in this namespace."])
+  })
+
+  it('separates what Radar does not collect from what is still loading', () => {
+    expect(
+      workloadHistoryNotes(null, [
+        { code: 'radar_forbidden', kinds: { count: 1, names: [{ kind: 'Workload', group: 'kueue.x-k8s.io' }] } },
+        { code: 'kind_sync_pending', kinds: { count: 1, names: [{ kind: 'ProvisioningRequest', group: 'autoscaling.x-k8s.io' }] } },
+        { code: 'some_future_code' },
+      ]),
+    ).toEqual([
+      "Changes to Kueue Workloads aren't shown: Radar's Kubernetes identity may not list them.",
+      "Changes to ProvisioningRequests aren't shown: still loading.",
+      "Some related changes aren't shown: the read failed.",
+    ])
+  })
+})
+
+
+describe('history gap remedies', () => {
+  it('preserves known Radar access and collection reasons separately', () => {
+    expect(workloadHistoryNotes(null, [
+      { code: 'radar_credentials_rejected', action: 'radar_config' },
+      { code: 'radar_namespace_not_collected', action: 'radar_config' },
+      { code: 'cluster_disconnected', action: 'radar_config' },
+    ])).toEqual([
+      "Some related changes aren't shown: Kubernetes rejected Radar's credentials.",
+      "Some related changes aren't shown: Radar doesn't collect them here.",
+      "Some related changes aren't shown: Radar lost its connection.",
+    ])
+  })
+
+  it.each([
+    ['user_access', "you don't have access to list them in this namespace"],
+    ['radar_config', "Radar's connection or collection settings need attention"],
+    ['retry', 'retry the read'],
+    ['wait', 'wait and retry the read'],
+    ['check_target', 'check the requested target and retry'],
+    ['change_request', 'change the read request'],
+  ])('uses the supplied %s action for an unknown code', (action, clause) => {
+    expect(workloadHistoryNotes(null, [{ code: 'new_server_code', action }])).toEqual([
+      `Some related changes aren't shown: ${clause}.`,
+    ])
+  })
+})

package/src/utils/workload-history-notes.ts

@@ -0,0 +1,93 @@
+import type { ReadGap, ReadKindRef } from '../types/read-coverage'
+import { canonicalReadCode, gapReasonText, READ_ACTIONS, readActionFor } from './read-actions'
+
+/**
+ * Whether Radar holds every change since a workload existed, as Radar's
+ * issuesapi.HistoryCoverage serializes it. Present only when incomplete;
+ * complete_since is sent only to callers who can read every namespace.
+ * An absent coverage value means complete history or an older Radar; it
+ * does not establish completeness on its own.
+ */
+export interface WorkloadHistoryCoverage {
+  incomplete: boolean
+  complete_since?: string
+  reasons: string[]
+}
+
+// Kinds a history gap names, as a reader knows them.
+const KIND_LABELS: Record<string, string> = {
+  'kueue.x-k8s.io/Workload': 'Kueue Workloads',
+  'autoscaling.x-k8s.io/ProvisioningRequest': 'ProvisioningRequests',
+}
+
+function kindLabel(ref: ReadKindRef): string {
+  return KIND_LABELS[`${ref.group ?? ''}/${ref.kind}`] ?? `${ref.kind} resources`
+}
+
+function joinWords(words: string[]): string {
+  if (words.length <= 1) return words[0] ?? ''
+  return `${words.slice(0, -1).join(', ')} and ${words[words.length - 1]}`
+}
+
+function gapClause(gap: ReadGap): string {
+  const code = canonicalReadCode(gap.code)
+  switch (code) {
+    case 'radar_forbidden':
+      return "Radar's Kubernetes identity may not list them"
+    case 'radar_credentials_rejected':
+      return "Kubernetes rejected Radar's credentials"
+    case 'radar_kind_not_collected':
+    case 'radar_namespace_not_collected':
+      return "Radar doesn't collect them here"
+  }
+  if (typeof code === 'string' && Object.hasOwn(READ_ACTIONS, code)) {
+    return readActionFor(code) === 'user_access'
+      ? "you don't have access to list them in this namespace"
+      : gapReasonText(code)
+  }
+  switch (gap.action) {
+    case 'user_access':
+      return "you don't have access to list them in this namespace"
+    case 'radar_config':
+      return "Radar's connection or collection settings need attention"
+    case 'retry':
+      return 'retry the read'
+    case 'wait':
+      return 'wait and retry the read'
+    case 'check_target':
+      return 'check the requested target and retry'
+    case 'change_request':
+      return 'change the read request'
+    default:
+      return gapReasonText(gap.code)
+  }
+}
+
+function formatSince(iso: string): string {
+  const date = new Date(iso)
+  return Number.isNaN(date.getTime()) ? iso : date.toLocaleString()
+}
+
+/**
+ * Sentences for a workload Timeline's note line: since when Radar's history
+ * is complete, and which related kinds it can't include for this viewer.
+ * Unknown reasons and codes from a newer Radar still produce a sentence.
+ */
+export function workloadHistoryNotes(coverage?: WorkloadHistoryCoverage | null, gaps?: ReadGap[] | null): string[] {
+  const notes: string[] = []
+  if (coverage?.incomplete) {
+    const why: string[] = []
+    if (coverage.reasons.includes('observation_started_late')) why.push('Radar began recording part of this history later')
+    if (coverage.reasons.includes('events_evicted')) why.push('older history was deleted to stay within its limits')
+    const head = coverage.complete_since
+      ? `Changes before ${formatSince(coverage.complete_since)} may be missing`
+      : 'Earlier changes may be missing'
+    notes.push(why.length > 0 ? `${head}: ${joinWords(why)}.` : `${head}.`)
+  }
+  for (const gap of gaps ?? []) {
+    const kinds = gap.kinds?.names?.map(kindLabel) ?? []
+    const what = kinds.length > 0 ? `Changes to ${joinWords(kinds)}` : 'Some related changes'
+    notes.push(`${what} aren't shown: ${gapClause(gap)}.`)
+  }
+  return notes
+}