@skyhook-io/radar-app 1.16.0 → 1.16.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyhook-io/radar-app",
-  "version": "1.16.0",
+  "version": "1.16.2",
   "description": "Radar's full web UI as a reusable React component. Used by Radar's own binary and by external consumers like Radar Cloud.",
   "repository": {
     "type": "git",
@@ -42,7 +42,7 @@
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
-    "@skyhook-io/k8s-ui": ">=1.16.0",
+    "@skyhook-io/k8s-ui": ">=1.16.1",
     "@tanstack/react-query": ">=5",
     "@xyflow/react": ">=12.0.0",
     "clsx": ">=2",

package/src/App.tsx

@@ -529,8 +529,8 @@ function AppInner({ manageDocumentTitle = false, documentTitleSuffix, onClusterL
     navigate(withCrossViewParams(path, location.search))
   }, [location.search, navigate])
 
-  // The standalone rail expresses intent to leave the full-width investigation
-  // workspace. Close it before routing so the destination is immediately visible;
+  // The standalone rail expresses intent to leave the full-width investigations
+  // page. Close it before routing so the destination is immediately visible;
   // docked investigations stay open across views as a persistent side panel.
   const handlePrimaryNavigate = useCallback((view: ExtendedMainView) => {
     navigateFromPrimaryRail(
@@ -1890,11 +1890,12 @@ function AppInner({ manageDocumentTitle = false, documentTitleSuffix, onClusterL
 
           {/* Local terminal */}
           {capabilities.localTerminal && (
-            <Tooltip content="Open local terminal">
+            <Tooltip content={connection.context || connection.state === 'disconnected' ? 'Open local terminal' : 'Waiting for a context to open a terminal'}>
             <button
               onClick={() => openLocalTerminal()}
+              disabled={!connection.context && connection.state !== 'disconnected'}
               aria-label="Open local terminal"
-              className="p-1.5 rounded-md bg-theme-elevated hover:bg-theme-hover text-theme-text-secondary hover:text-theme-text-primary transition-colors"
+              className="p-1.5 rounded-md bg-theme-elevated enabled:hover:bg-theme-hover text-theme-text-secondary enabled:hover:text-theme-text-primary disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
             >
               <SquareTerminal className="w-4 h-4" />
             </button>

package/src/RadarApp.tsx

@@ -34,6 +34,7 @@ import {
 } from "./components/ui/Toast";
 import { setApiBase, setBasename } from "./api/config";
 import { shouldRetryRadarQuery } from "./api/radarFeatures";
+import { isShownInline } from "./api/httpErrors";
 import { NavCustomizationProvider } from "./context/NavCustomization";
 import { FilterLocationBridge } from "./filter/FilterLocationBridge";
 import type { NavCustomization } from "./context/NavCustomization";
@@ -49,6 +50,7 @@ import { DiagnoseCustomizationProvider } from "./context/DiagnoseCustomization";
 import type {
   RenderDiagnoseAction,
   RenderInvestigationRunActions,
+  RenderInvestigationRefusalAction,
   DiagnoseConsentCopy,
 } from "./context/DiagnoseCustomization";
 import { defaultDiagnoseAction } from "./components/diagnose/LocalDiagnoseAction";
@@ -132,6 +134,10 @@ export interface RadarAppProps {
   renderDiagnoseAction?: RenderDiagnoseAction;
   /** Host-owned controls for the focused investigation; absent in standalone Radar. */
   renderInvestigationRunActions?: RenderInvestigationRunActions;
+  /** Host action beside a refused investigation start or follow-up, e.g. Radar
+   *  Cloud's "Upgrade" when the organization has used its investigations.
+   *  Absent in standalone Radar, whose backend sends no refusal details. */
+  renderInvestigationRefusalAction?: RenderInvestigationRefusalAction;
   /**
    * Replaces the first-run consent card's trust copy. REQUIRED of any host whose
    * backend runs the agent somewhere other than the user's own machine — the
@@ -179,7 +185,7 @@ export interface RadarAppProps {
 // Default QueryClient with the same shape Radar's standalone binary uses.
 // Extracted so both standalone + library consumers get identical
 // toast-on-error / toast-on-success behavior.
-function makeDefaultQueryClient(): QueryClient {
+export function makeDefaultQueryClient(): QueryClient {
   return new QueryClient({
     defaultOptions: {
       queries: {
@@ -190,7 +196,7 @@ function makeDefaultQueryClient(): QueryClient {
     mutationCache: new MutationCache({
       onError: (error, _variables, _context, mutation) => {
         const message = mutation.options.meta?.errorMessage;
-        if (message) showApiError(message, (error as Error).message);
+        if (message && !isShownInline(error)) showApiError(message, (error as Error).message);
       },
       onSuccess: (_data, _variables, _context, mutation) => {
         const message = mutation.options.meta?.successMessage;
@@ -224,6 +230,7 @@ export function RadarApp({
   documentTitleSuffix,
   renderDiagnoseAction,
   renderInvestigationRunActions,
+  renderInvestigationRefusalAction,
   diagnoseConsent,
   initialPath,
   onClusterLoadStateChange,
@@ -263,6 +270,7 @@ export function RadarApp({
                     value={renderDiagnoseAction ?? defaultDiagnoseAction}
                     consentCopy={diagnoseConsent}
                     renderRunActions={renderInvestigationRunActions}
+                    renderRefusalAction={renderInvestigationRefusalAction}
                   >
                     <DiagnoseProvider
                       browserURLState={router !== "memory"}

package/src/api/client.ts

@@ -59,7 +59,7 @@ import type {
 } from '../types'
 import type { GitOpsOperationResponse } from '../types/gitops'
 import { apiUrl, getApiBase, getAuthHeaders, getCredentialsMode, getBasename, routePath, stripBasename } from './config'
-import { httpStatusMessage, readErrorBody, readErrorResponse } from './httpErrors'
+import { httpStatusMessage, markShownInline, readErrorBody, readErrorResponse } from './httpErrors'
 import {
   RadarFeatureUnsupportedError,
   guardRadarFeature,
@@ -1782,6 +1782,7 @@ export function useRadarFeature(feature: RadarFeature) {
   const support = radarFeatureSupport(feature, capabilities, currentVersion)
 
   return {
+    support,
     gatedKey: support === 'unsupported' ? ['radar-feature-unsupported'] : [],
     guard: <T,>(request: () => Promise<T>): Promise<T> =>
       guardRadarFeature(feature, support, { currentVersion, latestVersion }, request),
@@ -2946,14 +2947,28 @@ function workloadHistoryPath(kind: string, namespace: string, name: string, grou
 // The newest page of one workload's history: the workload, what it owns, K8s
 // Events about those, and the resources attached to it. Keyed under
 // "changes" so the live-update invalidation refreshes it.
+// A Radar that predates the scoped history endpoint settles as unsupported;
+// WorkloadView then falls back to the namespace's changes.
 export function useWorkloadHistory(kind: string, namespace: string, name: string, group?: string, enabled = true) {
-  return useQuery<WorkloadHistoryPage>({
-    queryKey: ["changes", "workload-history", kind, namespace, name, group ?? ""],
-    queryFn: ({ signal }) => fetchJSON(workloadHistoryPath(kind, namespace, name, group), signal),
+  const { guard, gatedKey, support } = useRadarFeature("workloadHistory");
+  const query = useQuery<WorkloadHistoryPage>({
+    queryKey: ["changes", "workload-history", kind, namespace, name, group ?? "", ...gatedKey],
+    queryFn: ({ signal }) =>
+      guard(() => fetchJSON<WorkloadHistoryPage>(workloadHistoryPath(kind, namespace, name, group), signal)),
     staleTime: 5000,
-    refetchInterval: CHANGES_REFRESH_INTERVAL_MS,
+    retry: shouldRetryRadarQuery,
+    refetchInterval: (query) =>
+      query.state.error instanceof RadarFeatureUnsupportedError ? false : CHANGES_REFRESH_INTERVAL_MS,
     enabled,
   });
+  // A probe answered by an older Radar settles as unsupported and stops
+  // polling; once /capabilities confirms the feature (the agent was upgraded),
+  // ask again rather than staying on the fallback.
+  const { error, refetch } = query;
+  useEffect(() => {
+    if (support === "supported" && error instanceof RadarFeatureUnsupportedError) void refetch();
+  }, [support, error, refetch]);
+  return query;
 }
 
 export function fetchWorkloadHistoryPage(kind: string, namespace: string, name: string, group: string | undefined, beforeSeq: number): Promise<WorkloadHistoryPage> {
@@ -4077,7 +4092,13 @@ export function useUpdateResource() {
       });
       if (!response.ok) {
         const error = await readErrorBody(response);
-        throw new Error(error.error || `HTTP ${response.status}`);
+        const failure = new Error(error.error || `HTTP ${response.status}`);
+        // A reviewed apply's failure is shown in the review itself (the
+        // changed-after-review notice, or the error), so it gets no toast.
+        if (reviewedResourceVersion !== undefined || reviewedContext !== undefined) {
+          markShownInline(failure);
+        }
+        throw failure;
       }
       return response.json();
     },

package/src/api/client.updateResource.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+//
+// A reviewed YAML apply shows its failure in the review itself, so the global
+// "Failed to update resource" toast would say the same thing twice.
+import { act } from 'react'
+import { createRoot } from 'react-dom/client'
+import { QueryClientProvider } from '@tanstack/react-query'
+import { afterEach, expect, it, vi } from 'vitest'
+
+const toasts = vi.hoisted(() => ({ errors: [] as string[] }))
+vi.mock('@skyhook-io/k8s-ui', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@skyhook-io/k8s-ui')>()),
+  showApiError: (title: string) => toasts.errors.push(title),
+}))
+
+const { makeDefaultQueryClient } = await import('../RadarApp')
+const { useUpdateResource } = await import('./client')
+
+vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  toasts.errors = []
+})
+
+async function save(reviewed: boolean) {
+  vi.stubGlobal('fetch', vi.fn(async () => new Response(
+    JSON.stringify({ error: 'resource changed after review; review the latest version before applying' }),
+    { status: 409, headers: { 'Content-Type': 'application/json' } },
+  )))
+  let mutate: ReturnType<typeof useUpdateResource>['mutateAsync'] | undefined
+  function Probe() {
+    mutate = useUpdateResource().mutateAsync
+    return null
+  }
+  const host = document.createElement('div')
+  const root = createRoot(host)
+  await act(async () => {
+    root.render(<QueryClientProvider client={makeDefaultQueryClient()}><Probe /></QueryClientProvider>)
+  })
+  await act(async () => {
+    await mutate!({
+      kind: 'configmaps', namespace: 'shop', name: 'app', yaml: 'kind: ConfigMap',
+      ...(reviewed ? { reviewedResourceVersion: '42', reviewedContext: 'kind-a' } : {}),
+    }).catch(() => {})
+  })
+  act(() => root.unmount())
+}
+
+it('does not toast a reviewed apply, whose review shows the failure', async () => {
+  await save(true)
+  expect(toasts.errors).toEqual([])
+})
+
+it('still toasts a save that did not come from a review', async () => {
+  await save(false)
+  expect(toasts.errors).toEqual(['Failed to update resource'])
+})

package/src/api/diagnose.ts

@@ -310,6 +310,32 @@ export class DiagnoseError extends Error {
   }
 }
 
+/** A host's refusal of an investigation request, with what would unblock it. */
+export interface InvestigationRefusal {
+  status: number;
+  /** The sentence shown to the user. */
+  message: string;
+  code?: string;
+  reason?: string;
+  action?: string;
+}
+
+/** The refusal a DiagnoseError carries, or null when the host sent none
+ * (Radar's own backend never does). */
+export function investigationRefusal(
+  error: unknown,
+): InvestigationRefusal | null {
+  if (!(error instanceof DiagnoseError)) return null;
+  if (!error.code && !error.reason && !error.action) return null;
+  return {
+    status: error.status,
+    message: error.message,
+    code: error.code,
+    reason: error.reason,
+    action: error.action,
+  };
+}
+
 const RUNS = () => `${getApiBase()}/diagnose/runs`;
 
 // createRun starts a server-side investigation (or focuses a live one for the same

package/src/api/httpErrors.ts

@@ -99,3 +99,15 @@ export function nonJsonErrorMessage(response: Response, text: string): string {
 export async function readErrorBody(response: Response): Promise<ErrorBody> {
   return (await readErrorResponse(response)).body
 }
+
+/**
+ * Marks a mutation error whose surface already shows it, so the global
+ * mutation handler doesn't toast it a second time.
+ */
+export function markShownInline(error: Error): void {
+  ;(error as Error & { shownInline?: boolean }).shownInline = true
+}
+
+export function isShownInline(error: unknown): boolean {
+  return error instanceof Error && (error as Error & { shownInline?: boolean }).shownInline === true
+}

package/src/api/radarFeatures.render.test.tsx

@@ -4,7 +4,7 @@ import { createRoot } from 'react-dom/client'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { afterEach, beforeEach, expect, it, vi } from 'vitest'
 import { getRadarUpgradeRequirement } from '@skyhook-io/k8s-ui'
-import { ApiError, isNotFoundError, useApplications, useCapacityPoolDetail, useDrainPlan, usePodEnvironment } from './client'
+import { ApiError, isNotFoundError, useApplications, useCapacityPoolDetail, useDrainPlan, usePodEnvironment, useWorkloadHistory } from './client'
 import { getApiBase } from './config'
 import { usePolicyResource } from './policy'
 import { isRadarFeatureUnsupported } from './radarFeatures'
@@ -188,3 +188,36 @@ it('never asks a Radar older than v1.8 for applications', async () => {
   expect(element.textContent).toBe('upgrade')
   expect(asked('/applications')).toBe(false)
 })
+
+function History() {
+  const { data, error } = useWorkloadHistory('deployments', 'shop', 'web', 'apps')
+  return <span>{data ? 'data' : isRadarFeatureUnsupported(error, 'workloadHistory') ? 'fallback' : 'pending'}</span>
+}
+
+it('never asks a Radar whose capabilities omit workload history', async () => {
+  client.setQueryData(['capabilities'], { features: { policyResource: true } })
+  await render(<History />)
+  expect(element.textContent).toBe('fallback')
+  expect(asked('/history')).toBe(false)
+})
+
+it("reads the router's 404 on workload history as unsupported before capabilities answer", async () => {
+  host.radarVersion = undefined
+  chiRoutes = ['/workloads/deployments/shop/web/history']
+  await render(<History />)
+  expect(element.textContent).toBe('fallback')
+  expect(requested.filter((url) => url.includes('/history'))).toHaveLength(1)
+})
+
+it('asks again once capabilities confirm workload history after a probe hit an older Radar', async () => {
+  host.radarVersion = undefined
+  chiRoutes = ['/workloads/deployments/shop/web/history']
+  await render(<History />)
+  expect(element.textContent).toBe('fallback')
+
+  chiRoutes = []
+  await act(async () => { client.setQueryData(['capabilities'], { features: { workloadHistory: true } }) })
+  await settle()
+  await settle()
+  expect(requested.filter((url) => url.includes('/history'))).toHaveLength(2)
+})

package/src/api/radarFeatures.test.ts

@@ -56,6 +56,15 @@ describe('radarFeatureSupport', () => {
   })
 })
 
+describe('workload history, whose flag shipped with its endpoint', () => {
+  it('trusts a loaded capabilities answer, and probes before it arrives', () => {
+    expect(radarFeatureSupport('workloadHistory', { features: { workloadHistory: true } }, undefined)).toBe('supported')
+    expect(radarFeatureSupport('workloadHistory', { features: { policyResource: true } }, 'v1.15.0')).toBe('unsupported')
+    expect(radarFeatureSupport('workloadHistory', { features: {} }, 'dev')).toBe('unsupported')
+    expect(radarFeatureSupport('workloadHistory', undefined, 'v1.15.0')).toBe('unknown')
+  })
+})
+
 describe('radarSpecSupport for a feature whose flag shipped with its endpoint', () => {
   const driftAlerts: RadarFeatureSpec = { label: 'Drift alerts', flag: 'resourceIssues', flagShippedWithEndpoint: true }
 

package/src/api/radarFeatures.ts

@@ -34,6 +34,7 @@ export const RADAR_FEATURES = {
   upgradeReadiness: { label: 'Upgrade impact reports', minimumVersion: 'v1.9.0' },
   drainPlan: { label: 'Drain plans', minimumVersion: 'v1.14.0' },
   applications: { label: 'Applications', minimumVersion: 'v1.7.7' },
+  workloadHistory: { label: 'Workload history', flag: 'workloadHistory', flagShippedWithEndpoint: true },
 } as const satisfies Record<string, RadarFeatureSpec>
 
 export type RadarFeature = keyof typeof RADAR_FEATURES

package/src/components/ConnectionErrorView.test.tsx

@@ -12,6 +12,8 @@ const capabilitiesMock = vi.hoisted(() => ({ localTerminal: true }))
 
 vi.mock('@skyhook-io/k8s-ui', () => ({
   ClusterName: ({ name }: { name: string }) => <span>{name}</span>,
+}))
+vi.mock('./dock/DockContext', () => ({
   useOpenLocalTerminal: () => vi.fn(),
 }))
 vi.mock('../api/client', () => ({

package/src/components/ConnectionErrorView.tsx

@@ -3,7 +3,8 @@ import { useEffect, useState } from 'react'
 import type { ConnectionState } from '../context/ConnectionContext'
 import { ContextSwitcher } from './ContextSwitcher'
 import { parseContextName } from '../utils/context-name'
-import { useOpenLocalTerminal, ClusterName } from '@skyhook-io/k8s-ui'
+import { ClusterName } from '@skyhook-io/k8s-ui'
+import { useOpenLocalTerminal } from './dock/DockContext'
 import { useAuthMe, useContexts } from '../api/client'
 import { Tooltip } from './ui/Tooltip'
 import { Collapse, CollapseChevron } from '@skyhook-io/k8s-ui/components/ui/Collapse'

package/src/components/diagnose/AgentControls.tsx

@@ -13,7 +13,7 @@ const OPENCODE_FULL_LOCAL_WARNING =
   "Radar runs OpenCode with --auto, which automatically approves actions that your configuration would normally ask about, including built-in tools and configured MCP servers. Explicit denials still apply. Radar does not enforce a CLI sandbox.";
 
 const CURSOR_FULL_LOCAL_WARNING =
-  "Radar passes Cursor --force, which auto-approves its built-in tools and every MCP server it loads, including your global servers. Cursor’s sandbox does not reliably confine those tools to Radar’s temporary workspace.";
+  "Radar passes Cursor --force, which auto-approves its built-in tools and every MCP server it loads, including your global servers. Cursor’s sandbox does not reliably confine those tools to Radar’s temporary working directory.";
 
 // Segmented two-or-more-way selector — shared shape for the agent and execution
 // profile pickers.

package/src/components/diagnose/AssessmentCard.tsx

@@ -11,7 +11,12 @@ import {
   Search,
   ListChecks,
 } from "lucide-react";
-import type { Diagnosis, ApplyMutationOutcome } from "../../api/diagnose";
+import type {
+  Diagnosis,
+  ApplyMutationOutcome,
+  InvestigationRefusal,
+} from "../../api/diagnose";
+import { InvestigationRefusalAction } from "./InvestigationRefusalAction";
 import { Collapse, CollapseChevron } from "@skyhook-io/k8s-ui";
 import { Tooltip } from "../ui/Tooltip";
 import type {
@@ -669,6 +674,8 @@ export type AssessmentExplanation = {
   status: "idle" | "running" | "done" | "error";
   text?: string;
   error?: string;
+  /** The host's refusal behind error, for its action beside the message. */
+  refusal?: InvestigationRefusal | null;
   onGenerate?: () => void;
   openRequest?: number;
 };
@@ -847,6 +854,9 @@ function AssessmentDetails({
                         {explanation.error ||
                           "The agent did not return an explanation."}
                       </span>
+                      <InvestigationRefusalAction
+                        refusal={explanation.refusal ?? null}
+                      />
                       {explanation.onGenerate && (
                         <button
                           type="button"

package/src/components/diagnose/DiagnoseContext.tsx

@@ -28,9 +28,11 @@ import {
   createRun,
   recordConsent,
   DiagnoseError,
+  investigationRefusal,
 } from "../../api/diagnose";
 import { getApiBase } from "../../api/config";
 import {
+  type InvestigationRefusal,
   type RunSummary,
   type AgentInfo,
   type ExecutionProfile,
@@ -86,6 +88,9 @@ interface DiagnoseCtx {
   historyDegraded: boolean; // persistence broke — history won't survive a restart
   needsConsent: boolean; // a start is pending the one-time consent
   startError: string | null;
+  // The host's refusal behind startError, when it sent one, so the surface can
+  // offer the host's action beside the message.
+  startRefusal: InvestigationRefusal | null;
   // Kept apart from startError: the consent card renders this as "why your
   // approval was refused", and a run-start failure landing in the same slot
   // would be read as exactly that — the two paths don't share a lifecycle.
@@ -426,7 +431,10 @@ function RoutedDiagnoseProvider({
   const [runsLoadFailed, setRunsLoadFailed] = useState(false);
   const [historyDegraded, setHistoryDegraded] = useState(false);
   const [pendingTarget, setPendingTarget] = useState<Target | null>(null);
-  const [startError, setStartError] = useState<string | null>(null);
+  const [startFailure, setStartFailure] = useState<{
+    message: string;
+    refusal: InvestigationRefusal | null;
+  } | null>(null);
   const [consentError, setConsentError] = useState<string | null>(null);
   const [width, setWidth] = useState<number>(() => {
     try {
@@ -694,24 +702,28 @@ function RoutedDiagnoseProvider({
       })
       .catch((e) => {
         if (seq !== startSeqRef.current) return;
-        setStartError(
-          e instanceof DiagnoseError
-            ? e.message
-            : "Couldn't start the investigation.",
-        );
+        setStartFailure({
+          message:
+            e instanceof DiagnoseError
+              ? e.message
+              : "Couldn't start the investigation.",
+          refusal: investigationRefusal(e),
+        });
       });
   };
 
   const openInvestigation = useCallback(
     (t: Target) => {
-      setStartError(null);
+      setStartFailure(null);
       setConsentError(null);
       setOpen(true);
       if (!hosted && !consentSurface) {
         setPendingTarget(null);
-        setStartError(
-          "Radar can’t run this agent with a verified execution profile.",
-        );
+        setStartFailure({
+          message:
+            "Radar can’t run this agent with a verified execution profile.",
+          refusal: null,
+        });
         setView("investigation");
         return;
       }
@@ -728,7 +740,7 @@ function RoutedDiagnoseProvider({
   const openRun = useCallback(
     (id: string) => {
       unavailableRunIDsRef.current.delete(id);
-      setStartError(null);
+      setStartFailure(null);
       setActiveRunId(id);
       setView("investigation");
       setOpen(true);
@@ -748,7 +760,7 @@ function RoutedDiagnoseProvider({
   );
 
   // Browser navigation is the source of truth for presentation: a dedicated
-  // /investigations route is the full workspace, while ?ai-run keeps the
+  // /investigations route is the full investigations page, while ?ai-run keeps the
   // contextual drawer on its underlying page. Fetch exact ids rather than
   // assuming the bounded recent list contains them.
   useEffect(() => {
@@ -756,7 +768,7 @@ function RoutedDiagnoseProvider({
       return;
     const workspace = isInvestigationWorkspacePath(location.pathname);
     // Eligibility is unresolved until the agent probe returns. Once it has
-    // definitively resolved to off, workspace routes cannot render anything
+    // definitively resolved to off, investigations-page routes cannot render anything
     // useful; return to the app instead of leaving an eternal loading panel.
     if (agentEligibilityResolved && !eligible) {
       setActiveRunId(null);
@@ -823,7 +835,7 @@ function RoutedDiagnoseProvider({
 
     urlRunIdRef.current = id;
     unavailableRunIDsRef.current.delete(id);
-    setStartError(null);
+    setStartFailure(null);
     setActiveRunId(id);
     setView("investigation");
     setOpen(true);
@@ -856,14 +868,14 @@ function RoutedDiagnoseProvider({
     unavailableRunIDsRef.current.clear();
     setActiveRunId(null);
     setView("home");
-    setStartError(null);
+    setStartFailure(null);
     setOpen(true);
     writeFocusedRunID(null, false);
   }, [writeFocusedRunID]);
   const openWorkspace = useCallback(
     (preferredRunID?: string | null) => {
       setOpen(true);
-      setStartError(null);
+      setStartFailure(null);
       if (!forceRouterURLState && !diagnoseURLStateEnabled(browserURLState)) {
         if (preferredRunID) {
           setActiveRunId(preferredRunID);
@@ -876,8 +888,8 @@ function RoutedDiagnoseProvider({
         return;
       }
       const current = locationRef.current;
-      // The global entry remains visible in the workspace. Treat clicking it
-      // there as an idempotent reveal rather than pushing another workspace
+      // The global entry remains visible on the investigations page. Treat clicking it
+      // there as an idempotent reveal rather than pushing another page
       // entry and replacing the page that Close should return to.
       if (isInvestigationWorkspacePath(current.pathname)) {
         setMaximized(true);
@@ -927,14 +939,14 @@ function RoutedDiagnoseProvider({
     unavailableRunIDsRef.current.clear();
     setActiveRunId(null);
     setView("home");
-    setStartError(null);
+    setStartFailure(null);
     writeFocusedRunID(null, false);
   }, [writeFocusedRunID]);
   const dismissForNavigation = useCallback(() => {
     unavailableRunIDsRef.current.clear();
     setOpen(false);
     setView("home");
-    setStartError(null);
+    setStartFailure(null);
   }, []);
   const close = useCallback(() => {
     unavailableRunIDsRef.current.clear();
@@ -999,7 +1011,7 @@ function RoutedDiagnoseProvider({
     setOpen(true);
     if (!activeRunIdRef.current) setView("home");
   }, []);
-  const dismissError = useCallback(() => setStartError(null), []);
+  const dismissError = useCallback(() => setStartFailure(null), []);
 
   // Reserve a right gutter on the CONTENT area (not the navbar/rail — those stay
   // global and static) so docked content reflows beside the panel. Wide viewports
@@ -1029,7 +1041,8 @@ function RoutedDiagnoseProvider({
     // pendingTarget is set ONLY when the current agent's consent is missing, and
     // cleared on approve/cancel — so its presence is exactly "consent needed now".
     needsConsent: !!pendingTarget,
-    startError,
+    startError: startFailure?.message ?? null,
+    startRefusal: startFailure?.refusal ?? null,
     consentError,
     openInvestigation,
     openRun,

package/src/components/diagnose/DiagnoseSurface.tsx

@@ -1,6 +1,6 @@
 // The right-docked shell of the AI surface. Two layouts:
 //  - docked: a single-pane right column (app reflows left via the provider's push)
-//  - expanded: a master-detail workspace that fills ONLY the content area (does
+//  - expanded: the investigations page, a master-detail layout that fills ONLY the content area (does
 //    not cover the left nav rail or top bar) — recent list on the left, the
 //    selected investigation/report on the right.
 import {
@@ -38,6 +38,7 @@ import {
   type DiagnoseView,
 } from "./DiagnoseContext";
 import { useDiagnoseCustomization } from "../../context/DiagnoseCustomization";
+import { InvestigationRefusalAction } from "./InvestigationRefusalAction";
 import { useNavCustomization } from "../../context/NavCustomization";
 import { InvestigationView } from "./InvestigationView";
 import type { InvestigationTimelineScope } from "./InvestigationEvidencePane";
@@ -419,7 +420,7 @@ export function DiagnoseSurface({
     panelWidthKey: widthKey,
   } = useDiagnoseLayout();
   // Home has no detail pane competing for width, so its history is always part
-  // of the workspace. Only a focused run collapses history into a drawer when
+  // of the page. Only a focused run collapses history into a drawer when
   // the two-pane layout would become cramped.
   const persistentHistory = investigationHistoryIsPersistent({
     maximized,
@@ -604,12 +605,15 @@ export function DiagnoseSurface({
   ) : d.startError ? (
     <div className="flex flex-1 flex-col items-center justify-center gap-3 px-6 text-center">
       <p className="text-sm text-theme-text-secondary">{d.startError}</p>
-      <button
-        onClick={d.dismissError}
-        className="rounded-lg border border-theme-border px-3 py-1.5 text-sm text-theme-text-secondary hover:bg-theme-hover"
-      >
-        Dismiss
-      </button>
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        <InvestigationRefusalAction refusal={d.startRefusal} />
+        <button
+          onClick={d.dismissError}
+          className="rounded-lg border border-theme-border px-3 py-1.5 text-sm text-theme-text-secondary hover:bg-theme-hover"
+        >
+          Dismiss
+        </button>
+      </div>
     </div>
   ) : setupPending ? (
     <div className="flex-1 overflow-y-auto">

package/src/components/diagnose/Home.tsx

@@ -1,5 +1,5 @@
 // Server-side runs keep background and running investigations visible in both
-// the docked Home view and the maximized workspace's master pane.
+// the docked Home view and the investigations page's list pane.
 import {
   ArrowRight,
   CircleAlert,

package/src/components/diagnose/InvestigationEvidencePane.tsx

@@ -204,7 +204,7 @@ export function InvestigationEvidencePane({
     : undefined;
 
   // A source link is a navigation request, not a disclosure preference. Open
-  // whichever collection owns the source first, then tell the workspace that
+  // whichever collection owns the source first, then tell the investigation view that
   // its double-rAF focus/scroll can safely run outside an inert subtree.
   useLayoutEffect(() => {
     if (