@skyhook-io/k8s-ui 1.10.4 → 1.11.0

package/src/components/ui/InClusterConsentDialog.tsx

@@ -0,0 +1,141 @@
+import { useState } from 'react'
+import { ConfirmDialog } from './ConfirmDialog'
+import { rememberInClusterConsent } from '../../utils/inClusterConsent'
+
+/** One request the in-cluster job will actually send. */
+export interface ConsentRequest {
+  /** Route label, for the operator to recognise which path this is. */
+  route: string
+  /** Concrete request, e.g. "GET https://checkout.example.com/healthz". */
+  request: string
+}
+
+interface InClusterConsentDialogProps {
+  open: boolean
+  cluster?: string
+  namespace: string
+  /** The requests this run will send, one per declared route. */
+  requests?: ConsentRequest[]
+  /** Declared paths the run covers but for which no concrete request could be
+   *  derived. They still count toward the scope the operator is agreeing to. */
+  untestedCount?: number
+  /** Server-side ceiling on probe Pods per call. */
+  maxProbes?: number
+  onClose: () => void
+  onConfirm: () => void
+}
+
+/** Rows are capped so the dialog stays a confirmation, not a report. */
+const MAX_LISTED_REQUESTS = 6
+
+/**
+ * The fact block the operator confirms against. It is the last screen before
+ * real pod-to-pod traffic, so it must name the requests being sent - it used to
+ * show only where the Job would land, and then only a single "GET /" that was
+ * wrong in the DEFAULT case: with no path override the server keeps each
+ * route's OWN declared path, so "/" is least accurate exactly when it is shown.
+ */
+export function inClusterConsentDetails(o: {
+  cluster?: string
+  namespace: string
+  requests?: ConsentRequest[]
+  untestedCount?: number
+  /** Server-side ceiling on probe Pods per call. Routes past it do not run, and
+   *  since ordering is deterministic they are not reached by re-running either -
+   *  so the screen must say so rather than imply full coverage. */
+  maxProbes?: number
+}): string {
+  const reqs = o.requests ?? []
+  const untested = o.untestedCount ?? 0
+  const total = reqs.length + untested
+  const cap = o.maxProbes ?? 0
+  const willRun = cap > 0 ? Math.min(reqs.length, cap) : reqs.length
+  const lines = [cluster(o.cluster), `Namespace: ${o.namespace}`]
+  if (total > 0) {
+    lines.push(`Declared:  ${total} path${total === 1 ? '' : 's'} on this resource`)
+    // "0 requests, one Pod each" is nonsense, and it describes a run that would
+    // create nothing at all - so say that instead of counting to zero.
+    lines.push(
+      willRun === 0
+        ? 'Will run:  nothing — no request could be derived from these paths'
+        : `Will run:  ${willRun} request${willRun === 1 ? '' : 's'}, one Pod each`,
+    )
+  }
+  for (const r of reqs.slice(0, MAX_LISTED_REQUESTS)) {
+    lines.push(`  → ${r.request}`)
+  }
+  const hidden = reqs.length - Math.min(reqs.length, MAX_LISTED_REQUESTS)
+  if (hidden > 0) lines.push(`  → …and ${hidden} more`)
+  // Named, never silently dropped: they are part of the scope being agreed to
+  // even though no concrete request could be derived for them.
+  if (untested > 0) {
+    lines.push(`  → ${untested} path${untested === 1 ? '' : 's'} with no derivable request`)
+  }
+  const beyond = reqs.length - willRun
+  if (beyond > 0) {
+    lines.push(`  → ${beyond} beyond the ${cap}-Pod limit — not tested, and re-running starts from the same first ${cap}`)
+  }
+  return lines.filter(Boolean).join('\n')
+}
+
+function cluster(name?: string): string {
+  return name ? `Cluster:   ${name}` : ''
+}
+
+// Confirms the mutating in-cluster reachability test before it spawns a Job/pod,
+// naming the cluster it lands in. Permission is enforced upstream (the button only
+// renders when the capability SSAR allows), so this is a safety confirm, not authz.
+export function InClusterConsentDialog({ open, cluster, namespace, requests, untestedCount, maxProbes, onClose, onConfirm }: InClusterConsentDialogProps) {
+  const [dontAskAgain, setDontAskAgain] = useState(false)
+
+  function handleClose() {
+    onClose()
+    setDontAskAgain(false)
+  }
+
+  function handleConfirm() {
+    if (dontAskAgain && cluster) rememberInClusterConsent(cluster)
+    setDontAskAgain(false)
+    onConfirm()
+  }
+
+  return (
+    <ConfirmDialog
+      open={open}
+      onClose={handleClose}
+      onConfirm={handleConfirm}
+      // Wide enough for a real cluster identity: a GKE context name runs past
+      // 50 characters and wrapped mid-name at the default width.
+      className="w-full max-w-xl"
+      title="Run in-cluster reachability test?"
+      message="This creates one short-lived, self-deleting Job per request, sending real pod-to-pod traffic from inside the cluster. Each Pod runs under the target namespace’s default ServiceAccount with no token mounted — not as you — and your cluster may inject sidecars into it."
+      details={inClusterConsentDetails({ cluster, namespace, requests, untestedCount, maxProbes })}
+      // Nothing to send means nothing to confirm. The button was live for a run
+      // that would create no Pods and change no evidence.
+      confirmDisabled={(requests?.length ?? 0) === 0}
+      confirmLabel="Run test"
+      cancelLabel="Cancel"
+      variant="warning"
+    >
+      {/* "Don't ask again" is stored per cluster. Without a cluster identity
+          there is nothing safe to key it on (one origin can front many
+          clusters), so consent is never remembered - hide the checkbox rather
+          than promise a persistence that doesn't stick. */}
+      {cluster ? (
+        <label className="flex items-center gap-2 text-sm text-theme-text-secondary">
+          <input
+            type="checkbox"
+            checked={dontAskAgain}
+            onChange={(e) => setDontAskAgain(e.target.checked)}
+            className="w-4 h-4 rounded border-theme-border bg-theme-base text-amber-600 focus:ring-amber-500 focus:ring-offset-0"
+          />
+          <span>Don&apos;t ask again for this cluster</span>
+        </label>
+      ) : (
+        <p className="text-xs text-theme-text-tertiary">
+          Cluster identity unavailable - this confirmation can&apos;t be saved, so it will be asked on every run.
+        </p>
+      )}
+    </ConfirmDialog>
+  )
+}

package/src/components/ui/index.ts

@@ -27,6 +27,7 @@ export * from './drawer-components'
 export { Collapse, CollapseChevron } from './Collapse'
 export { ResourceBar } from './ResourceBar'
 export { ForceDeleteConfirmDialog } from './ForceDeleteConfirmDialog'
+export { InClusterConsentDialog } from './InClusterConsentDialog'
 export { ToastProvider, useToast, showApiError, showApiSuccess } from './Toast'
 export { CodeViewer } from './CodeViewer'
 export { YamlEditor, YamlDiffEditor } from './YamlEditor'

package/src/components/workload/WorkloadView.tsx

@@ -29,6 +29,7 @@ import {
   X,
   BarChart3,
   Network,
+  Stethoscope,
   DollarSign,
 } from 'lucide-react'
 import type { TimelineEvent, ResourceRef, Relationships, SelectedResource, ResolvedEnvFrom, Topology, TopologyNode, HPADiagnosis, WorkloadPodInfo } from '../../types'
@@ -69,7 +70,7 @@ import {
 } from '../resources/resource-utils'
 import { ServicePortCards, type ServicePortRenderProps } from '../resources/renderers/ServiceRenderer'
 
-export type WorkloadTabType = 'overview' | 'topology' | 'timeline' | 'logs' | 'metrics' | 'cost' | 'yaml'
+export type WorkloadTabType = 'overview' | 'topology' | 'timeline' | 'logs' | 'metrics' | 'reachability' | 'cost' | 'yaml'
 type TabType = WorkloadTabType
 
 export interface ResourceOwnershipContext {
@@ -273,6 +274,17 @@ interface WorkloadViewProps {
   }) => ReactNode
   /** Render the metrics tab content */
   renderMetricsTab?: (props: { kind: string; namespace: string; name: string }) => ReactNode
+  /** Render the Diagnose tab content - a path-shaped trace for network
+   *  entry kinds (Service / Ingress / HTTPRoute / GRPCRoute / Gateway). The
+   *  tab is hidden when this callback is not provided OR when the focused
+   *  kind is neither a network entry kind nor reachable through one. */
+  renderDiagnoseTab?: (props: { kind: string; namespace: string; name: string }) => ReactNode
+  /** Set when the focused resource is NOT itself a network entry kind but is
+   *  served by one - a Deployment behind a Service. Reachability for a workload
+   *  IS the reachability of the Services in front of it, so the tab opens here
+   *  instead of sending the operator to another page to start over. Empty or
+   *  omitted keeps the tab hidden for non-entry kinds. */
+  reachableVia?: { kind: string; namespace?: string; name: string }[]
   /** Render the cost tab content */
   renderCostTab?: (props: { kind: string; namespace: string; name: string }) => ReactNode
   /** Render a read-only YAML view for a related object from the workload's
@@ -285,8 +297,12 @@ interface WorkloadViewProps {
   isMetricsAvailable?: (kind: string, resource: any) => boolean
   /** Whether cost is available for this resource kind */
   isCostAvailable?: (kind: string, resource: any) => boolean
-  /** Render extra content at the bottom of the overview tab (e.g. audit findings) */
-  renderOverviewExtra?: (props: { kind: string; namespace: string; name: string }) => ReactNode
+  /** Render extra content at the bottom of the overview tab (e.g. audit
+   *  findings). `context` lets the host suppress sections that are already
+   *  surfaced by a dedicated tab in expanded mode - e.g. the Diagnose card
+   *  belongs inline when there are no tabs (drawer) but would duplicate the
+   *  Diagnose tab when it is. */
+  renderOverviewExtra?: (props: { kind: string; namespace: string; name: string; group?: string; context: 'drawer' | 'expanded' }) => ReactNode
   /** Render lightweight overview intro content before the default renderer. */
   renderOverviewIntro?: (props: { kind: string; namespace: string; name: string }) => ReactNode
   /** Render content at the TOP of the overview tab, above the renderer (e.g. live
@@ -385,6 +401,8 @@ export function WorkloadView({
   onTabChange,
   // Render props
   renderLogsTab,
+  renderDiagnoseTab,
+  reachableVia,
   renderExpandedOverview,
   renderRelatedYaml,
   renderMetricsTab,
@@ -695,6 +713,12 @@ export function WorkloadView({
     },
     { id: 'logs', label: 'Logs', icon: <Terminal className="w-4 h-4" />, hidden: !logsTabVisible },
     { id: 'metrics', label: 'Metrics', icon: <BarChart3 className="w-4 h-4" />, hidden: !metricsTabVisible },
+    {
+      id: 'reachability',
+      label: 'Reachability',
+      icon: <Stethoscope className="w-4 h-4" />,
+      hidden: !(renderDiagnoseTab && (isDiagnoseKind(apiKind, group) || (reachableVia?.length ?? 0) > 0)),
+    },
     { id: 'cost', label: 'Cost', icon: <DollarSign className="w-4 h-4" />, hidden: !costTabVisible },
     { id: 'yaml', label: 'YAML', icon: <FileText className="w-4 h-4" /> },
   ]
@@ -861,7 +885,7 @@ export function WorkloadView({
                 updates={resourceFocusedUpdates}
                 eventsError={resourceFocusedK8sError}
                 updatesError={resourceFocusedUpdatesError}
-                mainFooter={renderOverviewExtra && renderOverviewExtra({ kind, namespace, name })}
+                mainFooter={renderOverviewExtra && renderOverviewExtra({ kind, namespace, name, group, context: 'drawer' })}
               />
             </OperationalIssuesShownContext.Provider>
           )}
@@ -1028,7 +1052,7 @@ export function WorkloadView({
               updates={resourceFocusedUpdates}
               eventsError={overviewEventsError}
               updatesError={resourceFocusedUpdatesError}
-              extraContent={renderOverviewExtra && renderOverviewExtra({ kind, namespace, name })}
+              extraContent={renderOverviewExtra && renderOverviewExtra({ kind, namespace, name, group, context: 'expanded' })}
               introContent={overviewIntro}
               leadContent={hasOperationalIssues && renderOverviewLead ? renderOverviewLead({ kind, namespace, name }) : undefined}
               onEvaluateCapacity={onEvaluateCapacity}
@@ -1080,6 +1104,11 @@ export function WorkloadView({
             {renderMetricsTab({ kind: resource?.kind || kind, namespace, name })}
           </div>
         )}
+        {effectiveTab === 'reachability' && renderDiagnoseTab && (
+          <div className="flex h-full min-h-0 flex-col p-3">
+            {renderDiagnoseTab({ kind: resource?.kind || kind, namespace, name })}
+          </div>
+        )}
         {effectiveTab === 'cost' && renderCostTab && (
           <div className="h-full overflow-auto p-4">
             {renderCostTab({ kind: resource?.kind || kind, namespace, name })}
@@ -1145,6 +1174,30 @@ export function WorkloadView({
 // HELPER FUNCTIONS
 // ============================================================================
 
+// Diagnose tab is only meaningful for the five network entry kinds. The
+// canonical predicate is internal/trace.IsEntryKind in Go; we mirror the
+// allowlist here so TypeScript callers don't need a fetch to decide whether
+// to render the tab. The two MUST stay in sync - when a kind is added on
+// either side, update both. Exported so the web wrapper can reuse the same
+// predicate for the inline drawer section.
+export function isDiagnoseKind(kind: string, group?: string): boolean {
+  const k = kind.toLowerCase()
+  const g = (group ?? '').toLowerCase()
+  // When the API group is known, require it to match - a CRD sharing a core kind
+  // name (Knative Service, Istio Gateway) must NOT enable the trace, which would
+  // fire /trace/<kind> against the wrong (core) object. group===undefined keeps the
+  // legacy kind-only behavior for callers that don't thread the group yet.
+  const groupOk = (expected: string[]): boolean => group === undefined || expected.includes(g)
+  if (k === 'service' || k === 'services') return groupOk([''])
+  if (k === 'ingress' || k === 'ingresses') return groupOk(['', 'networking.k8s.io'])
+  if (
+    k === 'httproute' || k === 'httproutes' ||
+    k === 'grpcroute' || k === 'grpcroutes' ||
+    k === 'gateway' || k === 'gateways'
+  ) return groupOk(['gateway.networking.k8s.io'])
+  return false
+}
+
 function extractMetadata(kind: string, resource: any): { label: string; value: string }[] {
   if (!resource) return []
   const items: { label: string; value: string }[] = []

package/src/components/workload/index.ts

@@ -1,2 +1,2 @@
-export { WorkloadView, type ResourceOwnershipContext, type ServingResourceDetail, type WorkloadTabType } from './WorkloadView'
+export { WorkloadView, isDiagnoseKind, type ResourceOwnershipContext, type ServingResourceDetail, type WorkloadTabType } from './WorkloadView'
 export { ResourceDetailDrawer } from './ResourceDetailDrawer'

package/src/components/workload/reachabilityTab.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { isDiagnoseKind } from './WorkloadView'
+
+/**
+ * The rule that decides whether a resource gets a Reachability tab.
+ *
+ * `isDiagnoseKind` alone excluded every workload kind, so a Deployment had no
+ * Reachability tab at all - the operator got a link to the Service and had to
+ * navigate away and restart the investigation there. The tab now also opens for
+ * a resource that is SERVED by an entry kind, which is what makes "reachability
+ * for a Service or workload" true of workloads.
+ */
+const tabVisible = (kind: string, group: string | undefined, servingServices: unknown[]): boolean =>
+  isDiagnoseKind(kind, group) || servingServices.length > 0
+
+const svc = [{ kind: 'Service', namespace: 'prod', name: 'web' }]
+
+describe('who gets a Reachability tab', () => {
+  it('entry kinds trace themselves, with no Service needed', () => {
+    expect(tabVisible('Service', '', [])).toBe(true)
+    expect(tabVisible('Ingress', 'networking.k8s.io', [])).toBe(true)
+    expect(tabVisible('HTTPRoute', 'gateway.networking.k8s.io', [])).toBe(true)
+  })
+
+  it('a workload behind a Service now gets one', () => {
+    for (const kind of ['Deployment', 'StatefulSet', 'DaemonSet', 'Pod']) {
+      expect(tabVisible(kind, 'apps', svc)).toBe(true)
+    }
+  })
+
+  // Nothing selects it, so there is no path to trace and no honest tab to show.
+  it('a workload nothing exposes does not', () => {
+    expect(tabVisible('Deployment', 'apps', [])).toBe(false)
+  })
+
+  // A CRD sharing a core kind name must not enable a trace against the wrong
+  // object - the group check that guards this is load-bearing, not incidental.
+  it('a Knative Service is not a core Service', () => {
+    expect(tabVisible('Service', 'serving.knative.dev', [])).toBe(false)
+  })
+
+  // ...but if something does select its pods, it still earns the tab through
+  // the serving Service, exactly like any other workload.
+  it('a same-named CRD still qualifies via its serving Service', () => {
+    expect(tabVisible('Service', 'serving.knative.dev', svc)).toBe(true)
+  })
+})

package/src/index.ts

@@ -40,6 +40,11 @@ export * from './components/topology'
 // Cluster audit (AuditCard, AuditAlerts, AuditFindingsTable)
 export * from './components/audit'
 
+// Network path trace (ReachabilityView + types) - diagnostics for Service /
+// Ingress / HTTPRoute / GRPCRoute / Gateway. Backed by /api/trace and the
+// internal/trace Go package; the view is presentation-only.
+export * from './components/trace'
+
 // Checks remediation queue (ChecksView, shared types + severity vocabulary).
 // Host-agnostic: Hub feeds fleet-resolved data, OSS can feed a single-cluster
 // resolve.

package/src/theme/components.css

@@ -235,3 +235,67 @@
   }
 
 } /* end @layer components */
+
+/* Brief pulse the trace panel uses to flash the broken hop after the
+   verdict banner's "Show me" button scrolls it into view. Outside the
+   components layer so it's not subject to specificity tweaks. */
+@keyframes trace-broken-pulse {
+  0% { box-shadow: 0 0 0 0 rgba(239, 68, 68, 0); }
+  35% { box-shadow: 0 0 0 4px rgba(239, 68, 68, 0.45); }
+  100% { box-shadow: 0 0 0 0 rgba(239, 68, 68, 0); }
+}
+.trace-broken-pulse {
+  animation: trace-broken-pulse 1.2s ease-out;
+}
+
+/* reach-flash: briefly highlights a value that just CHANGED after a probe run, so a
+   fast/identical-looking result is still visibly "new". Fades from the accent tint. */
+@keyframes reach-flash {
+  0%   { background-color: var(--accent-muted); }
+  100% { background-color: transparent; }
+}
+.reach-flash {
+  animation: reach-flash 1.6s ease-out;
+  border-radius: 4px;
+}
+
+/* reach-edge-testing: a request is IN FLIGHT along this edge right now.
+   The dash pattern flows toward the target, so the graph shows the probe
+   travelling the path it is testing rather than the page just saying
+   "running" in a button. Semantic, not decorative: only edges the running
+   vantage is actually exercising get it. */
+@keyframes reach-edge-flow {
+  to { stroke-dashoffset: -24; }
+}
+.reach-edge-testing {
+  animation: reach-edge-flow 0.9s linear infinite;
+}
+@media (prefers-reduced-motion: reduce) {
+  .reach-edge-testing { animation: none; }
+}
+
+/* reach-node-testing: the vantage a test is running FROM, while it runs.
+   The edge already shows the request travelling; the capsule it leaves from
+   stayed inert, so the source of the work looked as static as everything else.
+   A slow border breathe + a lifted surface says "this one is working" without
+   competing with the flowing edge. Semantic: only the running origin gets it. */
+@keyframes reach-node-breathe {
+  0%, 100% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--accent) 45%, transparent); }
+  50% { box-shadow: 0 0 0 4px color-mix(in srgb, var(--accent) 12%, transparent); }
+}
+.reach-node-testing {
+  animation: reach-node-breathe 1.6s ease-in-out infinite;
+}
+/* The label itself pulses gently - "testing now" that never changes reads as
+   a stuck state on a long run. */
+@keyframes reach-label-fade {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.55; }
+}
+.reach-label-testing {
+  animation: reach-label-fade 1.6s ease-in-out infinite;
+}
+@media (prefers-reduced-motion: reduce) {
+  .reach-node-testing,
+  .reach-label-testing { animation: none; }
+}

package/src/theme/variables.css

@@ -29,6 +29,11 @@
   --color-error-light: #F87171;
   --color-error-dark: #DC2626;
   --color-info: #3B82F6;
+  /* alert = the orange tier between warning (amber) and error (red). The
+     .status-alert class predates these tokens and inlines the same hues. */
+  --color-alert: #F97316;
+  --color-alert-light: #FB923C;
+  --color-alert-dark: #EA580C;
 
   /* ── Backgrounds (elevation scale) ──
      sidebar  = primary nav rail — the DEEPEST layer, its own token so the rail

package/src/types/core.ts

@@ -258,8 +258,16 @@ export interface TopologyEdge {
   target: string
   type: EdgeType
   label?: string
+  /** Hover tooltip for the edge label. Used by the Reachability view to keep the
+   *  DECLARED route path available when the label shows an overridden tested path. */
+  labelTitle?: string
   skipIfKindVisible?: string // Hide this edge if this kind is visible (for shortcut edges)
   policyEffect?: 'allowed' | 'blocked' | 'unprotected'
+  /** Reachability outcome for THIS route/hop edge (distinct from policyEffect, a
+   *  NetworkPolicy concept). When set, the topology renderer colors the edge by
+   *  reachability: verified/reached = green, unreachable = red, blocked (downstream
+   *  of a break) = dashed gray, not-tested = neutral. Used by the Reachability view. */
+  reachOutcome?: 'verified' | 'reached' | 'unreachable' | 'blocked' | 'not-tested'
 }
 
 export interface Topology {

package/src/utils/api-resources.ts

@@ -207,6 +207,8 @@ export function formatGroupName(group: string): string {
     'eks.amazonaws.com': 'EKS',
     'networking.k8s.aws': 'AWS Networking',
     'acid.zalan.do': 'Zalando Postgres',
+    'postgresql.cnpg.io': 'CloudNativePG',
+    'barmancloud.cnpg.io': 'CloudNativePG',
     'serving.kserve.io': 'KServe',
     'ray.io': 'KubeRay',
     'leaderworkerset.x-k8s.io': 'LeaderWorkerSet',

package/src/utils/application-history.test.ts

@@ -200,7 +200,7 @@ describe('buildApplicationHistoryItems', () => {
         name: 'shop-config',
         diff: {
           summary: 'Added keys: API_URL',
-          fields: [{ path: 'data (added keys)', newValue: 'API_URL' }],
+          fields: [{ path: 'data (added keys)', oldValue: undefined, newValue: 'API_URL' }],
         },
       }),
       event({

package/src/utils/applications.test.ts

@@ -1,5 +1,67 @@
 import { describe, it, expect } from 'vitest'
-import { compareVersions, appGroupingExplainer, APP_IDENTITY_ANNOTATION, appGroupLagMessage, matchWorkloadAcrossInstances, foldAppGroups, identityEnvInferred, worstHealth, buildAppMembershipIndex, batchActivityForApp, batchRuntimeForApp, servingReadiness, type AppGroupFoldEntry, type AppRow, type AppWorkload } from './applications'
+import { compareVersions, appGroupingExplainer, APP_IDENTITY_ANNOTATION, appGroupLagMessage, matchWorkloadAcrossInstances, foldAppGroups, identityEnvInferred, worstHealth, buildAppMembershipIndex, batchActivityForApp, batchRuntimeForApp, servingReadiness, resolveAppWorkloadSelection, type AppGroupFoldEntry, type AppRow, type AppWorkload } from './applications'
+
+describe('application workload scope resolution', () => {
+  const sole = ['Deployment/prod/api']
+  const many = ['Deployment/prod/api', 'Deployment/prod/worker']
+
+  it('resolves application scope to the sole workload — a one-workload app has none', () => {
+    expect(resolveAppWorkloadSelection(sole, null)).toEqual({
+      selected: 'Deployment/prod/api',
+      hostKeyIsStale: false,
+    })
+  })
+
+  it('keeps application scope for a multi-workload app', () => {
+    expect(resolveAppWorkloadSelection(many, null)).toEqual({
+      selected: null,
+      hostKeyIsStale: false,
+    })
+  })
+
+  it('passes a key that names a current workload straight through', () => {
+    expect(resolveAppWorkloadSelection(many, 'Deployment/prod/worker')).toEqual({
+      selected: 'Deployment/prod/worker',
+      hostKeyIsStale: false,
+    })
+  })
+
+  // The stale key still has to leave the URL even though the sole workload
+  // renders in its place — the two outcomes are deliberately independent.
+  it('renders the sole workload from a stale key and still reports the key stale', () => {
+    expect(resolveAppWorkloadSelection(sole, 'Deployment/prod/gone')).toEqual({
+      selected: 'Deployment/prod/api',
+      hostKeyIsStale: true,
+    })
+  })
+
+  it('falls back to application scope when a stale key has no sole workload to land on', () => {
+    expect(resolveAppWorkloadSelection(many, 'Deployment/prod/gone')).toEqual({
+      selected: null,
+      hostKeyIsStale: true,
+    })
+  })
+
+  it('reports no stale key when none was supplied', () => {
+    expect(resolveAppWorkloadSelection([], null)).toEqual({
+      selected: null,
+      hostKeyIsStale: false,
+    })
+  })
+
+  // A bare `?workload=` reaches a host as '' rather than null, and names no
+  // workload — it has to leave the URL like any other unusable key.
+  it('treats the empty string a bare query param yields as a stale key', () => {
+    expect(resolveAppWorkloadSelection(sole, '')).toEqual({
+      selected: 'Deployment/prod/api',
+      hostKeyIsStale: true,
+    })
+    expect(resolveAppWorkloadSelection(many, '')).toEqual({
+      selected: null,
+      hostKeyIsStale: true,
+    })
+  })
+})
 
 describe('batch application runtime', () => {
   it('uses the latest retained outcome instead of historical failure count', () => {

package/src/utils/applications.ts

@@ -1364,6 +1364,33 @@ export function applicationDisplayHealth(app: AppRow): AppHealth {
   ]);
 }
 
+/** Which workload an application detail view renders, and whether the host's
+ *  key should be dropped from the URL.
+ *
+ *  A single-workload app has no application scope, so it resolves to its sole
+ *  workload even when the caller asks for application scope (`null`) or names a
+ *  workload the app no longer has. Deciding this here rather than in each host
+ *  is the point: a controlled host's only way to say "no workload in the URL"
+ *  is `null`, so leaving the rule to hosts makes the forbidden state their
+ *  default. `hostKeyIsStale` stays independent of what gets rendered — a key
+ *  naming no current workload must leave the URL even when the sole workload
+ *  renders in its place. */
+export function resolveAppWorkloadSelection(
+  workloadKeys: readonly string[],
+  hostSelected: string | null,
+): { selected: string | null; hostKeyIsStale: boolean } {
+  const matched =
+    hostSelected && workloadKeys.includes(hostSelected) ? hostSelected : null;
+  const soleWorkload = workloadKeys.length === 1 ? workloadKeys[0] : null;
+  return {
+    selected: matched ?? soleWorkload,
+    // Any non-null value counts as a key the host supplied, including the empty
+    // string a bare `?workload=` yields — that names no workload either, and
+    // leaving it in the URL would strand a param nothing can act on.
+    hostKeyIsStale: hostSelected !== null && !matched,
+  };
+}
+
 export function servingReadiness(workloads: AppWorkload[]): {
   ready: number;
   desired: number;