@skyhook-io/radar-app 1.14.0 → 1.14.2

package/src/components/cloudConnectHandoff.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { ApiError, type CloudInstallAttempted } from '../api/client'
-import { exitFor, handoffForBlocked, handoffForPrepareError, isHandoffOutcome, signupUrlFor } from './cloudConnectHandoff'
+import { composeAdminNote, composeFailureNote, exitFor, needsAdminHandoff, handoffForBlocked, handoffForPrepareError, isHandoffOutcome, signupUrlFor } from './cloudConnectHandoff'
 
 const APP = 'https://app.test.example'
 const UTM = 'utm_source=radar-oss&utm_medium=app&utm_campaign=cloud-modal'
@@ -35,13 +35,15 @@ describe('signupUrlFor', () => {
 })
 
 describe('exitFor — every blocked card has one exit, chosen by what Radar established', () => {
-  it('adopts a release Radar found, pinned to the Helm tab', () => {
+  it('adopts a release Radar found, pinned to the Helm tab, named after the context', () => {
     const h = handoffForBlocked('preflight', attempted({ mode: 'adopt', namespace: 'monitoring', release: 'radar-prod', stage: 'inspect' }))
-    const exit = exitFor(APP, CARD, h)
+    const exit = exitFor(APP, CARD, h, 'prod-east')
     expect(exit).toMatchObject({ install: true, label: 'Get the install command' })
     expect(exit.href).toBe(
-      `${APP}/install?existing=1&ns=monitoring&release=radar-prod&method=helm&${UTM}&utm_content=${CARD}&radar_outcome=blocked_preflight_checks_failed`,
+      `${APP}/install?name=prod-east&existing=1&ns=monitoring&release=radar-prod&method=helm&${UTM}&utm_content=${CARD}&radar_outcome=blocked_preflight_checks_failed`,
     )
+    // Without a context there is simply no name to suggest.
+    expect(exitFor(APP, CARD, h).href).not.toContain('name=')
   })
 
   it('offers a fresh install only from a complete plan whose discovery saw the whole cluster', () => {
@@ -138,3 +140,106 @@ describe('isHandoffOutcome', () => {
     }
   })
 })
+
+describe('composeAdminNote — an ask, then the link, then the evidence', () => {
+  const where = { context: 'prod-east', cluster: 'arn:aws:eks:us-east-1:1:cluster/prod-east' }
+
+  it('asks for a permissions block, naming the identity and trimming the refusal to what and why', () => {
+    const blocked = {
+      reason: 'preflight' as const,
+      cause: 'permissions' as const,
+      identity: 'system:serviceaccount:default:limited',
+      message: '',
+      attempted: attempted({ stage: 'inspect', releaseUnread: true }),
+      blocking: [
+        'inspect Helm release "radar" in namespace "radar": failed to inspect existing release: query: failed to query with labels: secrets is forbidden: User "system:serviceaccount:default:limited" cannot list resource "secrets" in API group "" in the namespace "radar"',
+      ],
+    }
+    const exit = exitFor(APP, CARD, handoffForBlocked('preflight', blocked.attempted), where.context)
+    const note = composeAdminNote(blocked, exit, where)
+    expect(note).toMatch(/^Request to connect cluster prod-east to Radar Cloud\n/)
+    expect(note).toContain("the identity in use (system:serviceaccount:default:limited) doesn't have the permissions to install it")
+    expect(note).toContain('Nothing in the cluster was changed. Could someone with cluster access connect it?')
+    // The link a person reads carries only what the page needs — no attribution.
+    // The link a person reads keeps what the page needs to land prefilled,
+    // plus one marker that the arrival came by handoff — no utm noise.
+    expect(note).toContain('Open Radar Cloud to get the install command (sign in, confirm the cluster name, pick Helm / Argo CD / Flux):\n' + `${APP}/install?name=prod-east&method=helm&via=admin_handoff`)
+    expect(note).not.toContain('utm_')
+    expect(note).not.toContain('radar_outcome')
+    expect(note).toContain("Details: No Radar install was found in the cluster; the check stopped while reading Helm's release records.")
+    expect(note).toContain('inspect Helm release "radar" in namespace "radar" — User "system:serviceaccount:default:limited" cannot list resource "secrets" in API group "" in the namespace "radar".')
+    expect(note).toContain('Please confirm nothing is already installed before a fresh install.')
+    // Never the card's second person.
+    expect(note).not.toMatch(/\byour\b/i)
+  })
+
+  it('asks for a GitOps values patch from the verified tool', () => {
+    const blocked = { reason: 'gitops' as const, message: 'managed by Flux', attempted: attempted({ mode: 'gitops', stage: 'inspect', method: 'flux' }) }
+    const exit = exitFor(APP, CARD, handoffForBlocked('gitops', blocked.attempted))
+    const note = composeAdminNote(blocked, exit, where)
+    expect(note).toContain('the install is managed by Flux, so connecting it is a values change in the repository')
+    expect(note).toContain('Open Radar Cloud to get the values patch for Flux (sign in, confirm the cluster name')
+    expect(note).toContain(`${APP}/install?existing=1&ns=radar&release=radar&method=flux&via=admin_handoff`)
+    expect(note).toContain('Details: The release radar in namespace radar is managed by Flux.')
+  })
+
+  it('quotes the refusal and sends the admin to Radar Cloud when Radar had no target', () => {
+    const blocked = { reason: 'unsupported' as const, message: 'Multiple Radar installations were found in this cluster.  Use `radar cloud install` to pick one.' }
+    const exit = exitFor(APP, CARD, handoffForBlocked('unsupported'))
+    const note = composeAdminNote(blocked, exit, { cluster: 'kind-dev' })
+    expect(note).toContain('Request to connect cluster kind-dev to Radar Cloud')
+    expect(note).toContain('Radar reported: Multiple Radar installations were found in this cluster. Use `radar cloud install` to pick one. Nothing in the cluster was changed.')
+    expect(note).not.toContain('..')
+    expect(note).toContain('Could someone with cluster access connect it from Radar Cloud?')
+    expect(note).toContain('Open Radar Cloud:\n' + `${APP}/signup?via=admin_handoff`)
+  })
+
+  it('keeps the whole line when a refusal has no error chain to trim', () => {
+    const blocked = {
+      reason: 'preflight' as const,
+      cause: 'cluster' as const,
+      message: '',
+      attempted: attempted({}),
+      blocking: ['create Deployment "radar" in namespace "radar": an object already exists but is not owned by the current Helm release'],
+    }
+    const note = composeAdminNote(blocked, exitFor(APP, CARD, handoffForBlocked('preflight', blocked.attempted)))
+    expect(note).toContain('the cluster refused part of the install — a policy, or something already there (details below)')
+    expect(note).toContain('Details: No Radar install was found in the cluster; the dry run of the install stopped. create Deployment "radar" in namespace "radar": an object already exists but is not owned by the current Helm release.')
+  })
+})
+
+describe('composeFailureNote — finishing a connection the Hub already approved', () => {
+  const guidance = {
+    summary: 'Hub cluster "abc123" already exists. Do not rerun the installer; first inspect the existing attempt.',
+    lines: ['The Helm upgrade did not start, so there was no rollback to verify.'],
+    inspect: ['helm status radar -n radar', 'kubectl -n radar get secret/radar-cloud-config'],
+    clusterUrl: 'https://app.radarhq.io/c/abc123?utm_source=x',
+  }
+
+  it('is offered only after the Hub approved and Helm ran', () => {
+    expect(needsAdminHandoff({ kind: 'helm_provision_failed', message: 'x', retrySafe: false })).toBe(true)
+    expect(needsAdminHandoff({ kind: 'installed_but_tunnel_not_confirmed', message: 'x', retrySafe: false })).toBe(true)
+    for (const kind of ['hub_connect_request_failed', 'approval_rejected_in_browser', 'approved_but_credential_pickup_expired', 'canceled_after_approval']) {
+      expect(needsAdminHandoff({ kind, message: 'x', retrySafe: false })).toBe(false)
+    }
+    expect(needsAdminHandoff(undefined)).toBe(false)
+  })
+
+  it('asks to finish the install, links the cluster page, and carries the operator guidance', () => {
+    const note = composeFailureNote(
+      { kind: 'helm_provision_failed', message: 'helm install failed: timed out waiting for the condition', retrySafe: false, guidance },
+      { context: 'prod-east' },
+    )
+    expect(note).toMatch(/^Request to finish connecting cluster prod-east to Radar Cloud\n/)
+    expect(note).toContain('the Helm install of Radar failed. helm install failed: timed out waiting for the condition Could someone with cluster access take it from here?')
+    expect(note).toContain('The cluster in Radar Cloud (its page shows the recovery options):\nhttps://app.radarhq.io/c/abc123?via=admin_handoff')
+    expect(note).toContain('Details: Hub cluster "abc123" already exists. Do not rerun the installer; first inspect the existing attempt. The Helm upgrade did not start, so there was no rollback to verify.')
+    expect(note).toContain('To inspect:\n  helm status radar -n radar\n  kubectl -n radar get secret/radar-cloud-config')
+  })
+
+  it('names the tunnel case for what it is', () => {
+    const note = composeFailureNote({ kind: 'installed_but_tunnel_not_confirmed', message: 'No tunnel within 5 minutes.', retrySafe: false }, {})
+    expect(note).toContain('Radar was installed by Helm, but its connection to Radar Cloud could not be confirmed. No tunnel within 5 minutes.')
+    expect(note).toContain('cluster this cluster to Radar Cloud')
+  })
+})

package/src/components/cloudConnectHandoff.ts

@@ -1,4 +1,4 @@
-import { ApiError, type CloudInstallAttempted, type CloudInstallBlocked } from '../api/client'
+import { ApiError, type CloudInstallAttempted, type CloudInstallBlocked, type CloudInstallFailure } from '../api/client'
 
 // The Cloud dialog's links into the Hub. utm_content names the link that was
 // clicked. After an in-app connect attempt that did not end connected, the
@@ -84,7 +84,10 @@ export interface BlockedExit {
   install: boolean
 }
 
-export function exitFor(appUrl: string, content: string, handoff: Handoff | null | undefined): BlockedExit {
+// clusterName is the kubeconfig context, offered to the Hub as the cluster's
+// name (`name=`) so the install page opens with its form already filled in;
+// the person can still change it there.
+export function exitFor(appUrl: string, content: string, handoff: Handoff | null | undefined, clusterName?: string): BlockedExit {
   const generic = { href: signupUrlFor(appUrl, content, handoff), label: 'Open Radar Cloud', install: false }
   const t = handoff?.target
   if (!t) return generic
@@ -93,6 +96,7 @@ export function exitFor(appUrl: string, content: string, handoff: Handoff | null
   // happens to know is not an invitation to install over it.
   if (handoff?.outcome === BLOCKED_OUTCOMES.unsupported) return generic
   const params = new URLSearchParams()
+  if (clusterName) params.set('name', clusterName)
   switch (t.mode) {
     case 'adopt':
       params.set('existing', '1')
@@ -122,3 +126,151 @@ function installHref(appUrl: string, content: string, handoff: Handoff | null |
   const url = `${appUrl}/install?${params.toString()}&${SIGNUP_QUERY.slice(1)}&utm_content=${content}`
   return handoff && isHandoffOutcome(handoff.outcome) ? `${url}&radar_outcome=${handoff.outcome}` : url
 }
+
+// The note a blocked person hands to whoever administers the cluster. An
+// ask, not a diagnostic: the request first, the link second, the evidence
+// last — and written about the attempt rather than in the reader's or the
+// sender's voice, so it can be pasted as-is or trimmed to a sentence.
+export interface AdminNoteContext {
+  context?: string
+  cluster?: string
+}
+
+export function composeAdminNote(blocked: CloudInstallBlocked, exit: BlockedExit, where: AdminNoteContext = {}): string {
+  const a = blocked.attempted
+  const name = where.context || where.cluster || 'this cluster'
+  const identity = blocked.identity ? ` (${blocked.identity})` : ''
+  const tool = a?.method === 'argocd' ? 'Argo CD' : a?.method === 'flux' ? 'Flux' : 'a GitOps controller'
+
+  let because: string
+  switch (blocked.reason) {
+    case 'gitops':
+      because = `the install is managed by ${tool}, so connecting it is a values change in the repository — Radar Cloud generates the patch`
+      break
+    case 'unsupported':
+      // The server's message ends its own sentence; the clause adds the period.
+      because = `Radar reported: ${blocked.message.replace(/\s+/g, ' ').trim().replace(/\.$/, '')}`
+      break
+    default:
+      switch (blocked.cause) {
+        case 'permissions':
+          because = `the identity in use${identity} doesn't have the permissions to install it`
+          break
+        case 'verification':
+          because = 'the Radar version in use can\'t install this chart version from there'
+          break
+        default:
+          because = 'the cluster refused part of the install — a policy, or something already there (details below)'
+      }
+  }
+
+  const ask = exit.install
+    ? 'Could someone with cluster access connect it?'
+    : 'Could someone with cluster access connect it from Radar Cloud?'
+  const linkLabel = !exit.install
+    ? 'Open Radar Cloud:'
+    : blocked.reason === 'gitops'
+      ? `Open Radar Cloud to get the values patch for ${tool} (sign in, confirm the cluster name; it also shows the one command that creates the token Secret):`
+      : 'Open Radar Cloud to get the install command (sign in, confirm the cluster name, pick Helm / Argo CD / Flux):'
+
+  // Observations, not Radar narrating itself: what was found, where it stopped.
+  const details: string[] = []
+  if (a) {
+    const target = `release ${a.release} in namespace ${a.namespace}`
+    const stage =
+      a.stage === 'inspect'
+        ? "the check stopped while reading Helm's release records"
+        : a.stage === 'prepare'
+          ? 'the check stopped while preparing the chart'
+          : 'the dry run of the install stopped'
+    details.push(
+      a.mode === 'gitops'
+        ? `The ${target} is managed by ${tool}.`
+        : a.mode === 'adopt'
+          ? `An existing ${target} was found; ${stage}.`
+          : a.partialScan
+            ? `Only namespace ${a.namespace} could be checked for an existing install; ${stage}.`
+            : `No Radar install was found in the cluster; ${stage}.`,
+    )
+  } else if (blocked.reason === 'preflight') {
+    details.push('The check for an existing Radar install did not complete.')
+  }
+  for (const line of blocked.blocking ?? []) details.push(trimRefusal(line))
+  if (a?.releaseUnread) details.push('Please confirm nothing is already installed before a fresh install.')
+  if (a?.partialScan) details.push('Please check the rest of the cluster for an existing install first.')
+
+  return [
+    `Request to connect cluster ${name} to Radar Cloud`,
+    '',
+    `Connecting it from Radar was blocked: ${because}. Nothing in the cluster was changed. ${ask}`,
+    '',
+    linkLabel,
+    plainLink(exit.href),
+    ...(details.length ? ['', `Details: ${details.join(' ')}`] : []),
+  ].join('\n')
+}
+
+// The note is text a person reads and forwards, so its link carries only what
+// the page needs to open in the right place (an existing release to adopt,
+// the install method) plus one short marker saying it arrived by handoff;
+// the card's own button keeps the full attribution params. The Hub stashes
+// the target and method across sign-in, so the admin still lands on the
+// prefilled install page.
+export const HANDOFF_VIA = 'admin_handoff'
+
+function plainLink(href: string): string {
+  try {
+    const url = new URL(href)
+    const keep = new URLSearchParams()
+    for (const key of ['name', 'existing', 'ns', 'release', 'method']) {
+      const v = url.searchParams.get(key)
+      if (v) keep.set(key, v)
+    }
+    keep.set('via', HANDOFF_VIA)
+    url.search = keep.toString()
+    return url.toString()
+  } catch {
+    return href
+  }
+}
+
+// A refusal line is a Go error chain — "create Namespace "radar": namespaces
+// "radar" is forbidden: ValidatingAdmissionPolicy … denied request: <reason>".
+// Keep what was attempted and why it was refused; drop the wrapping between.
+function trimRefusal(line: string): string {
+  const parts = line.split(': ').map((p) => p.trim()).filter(Boolean)
+  if (parts.length <= 2) return line.trim().replace(/\.?$/, '.')
+  return `${parts[0]} — ${parts[parts.length - 1]}`.replace(/\.?$/, '.')
+}
+
+// Failures after the Hub approved — Helm ran, or ran and the tunnel never
+// came up — are the ones whose guidance is written for an operator: inspect
+// commands, "keep this Hub cluster, don't rerun". A person who cannot act
+// on that hands it over the same way a blocked one does, as a request to
+// finish the connection rather than start one.
+export const HANDOFF_FAILURE_KINDS = new Set(['helm_provision_failed', 'installed_but_tunnel_not_confirmed'])
+
+export function needsAdminHandoff(failure: CloudInstallFailure | undefined): boolean {
+  return !!failure && HANDOFF_FAILURE_KINDS.has(failure.kind)
+}
+
+export function composeFailureNote(failure: CloudInstallFailure, where: AdminNoteContext = {}): string {
+  const name = where.context || where.cluster || 'this cluster'
+  const g = failure.guidance
+  const stage =
+    failure.kind === 'installed_but_tunnel_not_confirmed'
+      ? 'Radar was installed by Helm, but its connection to Radar Cloud could not be confirmed'
+      : 'the Helm install of Radar failed'
+  const lines: string[] = [
+    `Request to finish connecting cluster ${name} to Radar Cloud`,
+    '',
+    `Connecting it from Radar got as far as the install: ${stage}. ${failure.message.replace(/\s+/g, ' ').trim()} Could someone with cluster access take it from here?`,
+  ]
+  if (g?.clusterUrl) lines.push('', 'The cluster in Radar Cloud (its page shows the recovery options):', plainLink(g.clusterUrl))
+  const details: string[] = []
+  if (g?.summary && g.summary !== failure.message) details.push(g.summary)
+  for (const l of g?.lines ?? []) details.push(l)
+  if (details.length) lines.push('', `Details: ${details.join(' ')}`)
+  if (g?.inspect?.length) lines.push('', 'To inspect:', ...g.inspect.map((c) => `  ${c}`))
+  return lines.join('\n')
+}

package/src/components/curl/ServiceCurlButton.tsx

@@ -1,12 +1,13 @@
 import { useState, useEffect, useLayoutEffect, useRef } from 'react'
 import { createPortal } from 'react-dom'
 import { useMutation } from '@tanstack/react-query'
-import { Activity, Loader2, X, ChevronDown, Maximize2, Copy, Check } from 'lucide-react'
+import { Activity, Loader2, X, Maximize2, Copy, Check } from 'lucide-react'
 import { clsx } from 'clsx'
 import { apiFetch } from '../../api/client'
 import { apiUrl } from '../../api/config'
 import { Tooltip } from '../ui/Tooltip'
 import { Input } from '@skyhook-io/k8s-ui'
+import { Collapse, CollapseChevron } from '@skyhook-io/k8s-ui/components/ui/Collapse'
 
 // A port is "curl-able" only if it plausibly speaks HTTP — probing a raw TCP
 // port (Postgres, Redis) with a GET returns noise, so we don't offer it there
@@ -135,7 +136,7 @@ export function CurlButton({ active, onClick }: { active: boolean; onClick: () =
       >
         Curl
         {/* Disclosure caret: signals this expands an inline panel rather than firing a request. */}
-        <ChevronDown className={clsx('w-3 h-3 transition-transform', active && 'rotate-180')} />
+        <CollapseChevron open={active} className="w-3 h-3" />
       </button>
     </Tooltip>
   )
@@ -163,7 +164,7 @@ function VerdictLine({
         onClick={onToggleHeaders}
         className="ml-auto flex items-center gap-1 text-theme-text-secondary hover:text-theme-text-primary"
       >
-        Headers <ChevronDown className={clsx('w-3 h-3 transition-transform', showHeaders && 'rotate-180')} />
+        Headers <CollapseChevron open={showHeaders} className="w-3 h-3" />
       </button>
     </div>
   )
@@ -224,13 +225,11 @@ function CurlResponseDialog({
           <VerdictLine result={result} showHeaders={showHeaders} onToggleHeaders={() => setShowHeaders((v) => !v)} />
         </div>
 
-        <div className="grid transition-[grid-template-rows] duration-200 ease-out mx-4" style={{ gridTemplateRows: showHeaders ? '1fr' : '0fr' }}>
-          <div className="overflow-hidden">
-            <pre className="text-xs bg-theme-base mt-4 rounded p-3 overflow-auto max-h-48 text-theme-text-secondary font-mono whitespace-pre">
-              {Object.entries(result.headers).map(([k, v]) => `${k}: ${v}`).join('\n') || '(no headers)'}
-            </pre>
-          </div>
-        </div>
+        <Collapse open={showHeaders} className="mx-4">
+          <pre className="text-xs bg-theme-base mt-4 rounded p-3 overflow-auto max-h-48 text-theme-text-secondary font-mono whitespace-pre">
+            {Object.entries(result.headers).map(([k, v]) => `${k}: ${v}`).join('\n') || '(no headers)'}
+          </pre>
+        </Collapse>
 
         {result.error ? (
           <div className="m-4 text-sm text-amber-400 bg-amber-500/10 border border-amber-500/30 rounded px-3 py-2">
@@ -317,8 +316,7 @@ export function CurlPanel({
   }, [peek?.text, open])
 
   return (
-    <div className="grid transition-[grid-template-rows] duration-200 ease-out" style={{ gridTemplateRows: mounted && open ? '1fr' : '0fr' }}>
-      <div className="overflow-hidden">
+    <Collapse open={mounted && open}>
       <div className="mt-3 pt-3 border-t border-theme-border space-y-2" onClick={(e) => e.stopPropagation()}>
       <div className="flex items-center justify-between">
         <span className="flex items-center gap-1.5 text-xs font-medium text-theme-text-secondary">
@@ -370,9 +368,8 @@ export function CurlPanel({
         </div>
       )}
 
-      {/* Reveal the response with the same grid transition as the panel itself. */}
-      <div className="grid transition-[grid-template-rows] duration-200 ease-out" style={{ gridTemplateRows: result ? '1fr' : '0fr' }}>
-        <div className="overflow-hidden">
+      {/* Reveal the response with the same disclosure motion as the panel itself. */}
+      <Collapse open={!!result}>
       {result && (
         <div className="space-y-2 pt-0.5">
           <VerdictLine result={result} showHeaders={showHeaders} onToggleHeaders={() => setShowHeaders((v) => !v)} />
@@ -383,13 +380,11 @@ export function CurlPanel({
             </div>
           )}
 
-          <div className="grid transition-[grid-template-rows] duration-200 ease-out" style={{ gridTemplateRows: showHeaders ? '1fr' : '0fr' }}>
-            <div className="overflow-hidden">
-              <pre className="text-xs bg-theme-base rounded p-2 overflow-auto max-h-32 text-theme-text-secondary font-mono whitespace-pre">
-                {Object.entries(result.headers).map(([k, v]) => `${k}: ${v}`).join('\n') || '(no headers)'}
-              </pre>
-            </div>
-          </div>
+          <Collapse open={showHeaders}>
+            <pre className="text-xs bg-theme-base rounded p-2 overflow-auto max-h-32 text-theme-text-secondary font-mono whitespace-pre">
+              {Object.entries(result.headers).map(([k, v]) => `${k}: ${v}`).join('\n') || '(no headers)'}
+            </pre>
+          </Collapse>
 
           {peek && (
             <>
@@ -425,8 +420,7 @@ export function CurlPanel({
           )}
         </div>
       )}
-        </div>
-      </div>
+      </Collapse>
 
       {sheetOpen && result && (
         <CurlResponseDialog
@@ -439,7 +433,6 @@ export function CurlPanel({
         />
       )}
       </div>
-      </div>
-    </div>
+    </Collapse>
   )
 }

package/src/components/diagnose/AgentCase.tsx

@@ -1,5 +1,4 @@
 import { clsx } from "clsx";
-import { Sparkles } from "lucide-react";
 import { Badge } from "@skyhook-io/k8s-ui";
 
 import type { DiagnosisEvidenceRole } from "../../api/diagnose";
@@ -11,7 +10,7 @@ export const AGENT_ROLE_LABELS: Readonly<
   cause: "Cause",
   symptom: "Symptom",
   context: "Context",
-  benign: "Not a problem",
+  benign: "Not a live problem",
   demoted: "Less relevant",
   rules_out: "Rules out",
 };
@@ -29,8 +28,11 @@ export function AgentRoleChip({ role }: { role: DiagnosisEvidenceRole }) {
       // and the badge's own baseline comes from the sparkle, landing 1px high.
       wrapperClassName="shrink-0 align-[-1px]"
     >
-      <Badge tone="agent" size="sm">
-        <Sparkles className="h-2.5 w-2.5 shrink-0" aria-hidden />
+      <Badge
+        tone="structural"
+        size="sm"
+        className="border-theme-border-light font-medium text-theme-text-primary"
+      >
         {AGENT_ROLE_LABELS[role]}
       </Badge>
     </Tooltip>
@@ -55,10 +57,13 @@ export function AgentClaimNote({
   role,
   excludes,
   subject,
+  gap,
   className,
 }: {
   claim: string;
   role?: DiagnosisEvidenceRole;
+  /** What the agent says this result does not cover; shown beside its reading of it. */
+  gap?: string;
   /**
    * The hypothesis this item excludes. Rendered only for `rules_out`, where
    * the chip frames it as rejected: a hypothesis is a claim the agent
@@ -69,7 +74,7 @@ export function AgentClaimNote({
   subject?: string;
   className?: string;
 }) {
-  if (!claim && !role) return null;
+  if (!claim && !role && !gap) return null;
   return (
     <p
       data-agent-claim
@@ -102,6 +107,14 @@ export function AgentClaimNote({
             {renderClaim(claim)}
           </>
         ) : null}
+        {gap ? (
+          <span
+            data-agent-gap
+            className="block text-[11px] text-theme-text-tertiary"
+          >
+            Not shown: {gap}
+          </span>
+        ) : null}
       </span>
     </p>
   );