feat(dashboard): add system health diagnostics

Author: outof-place

apps/dashboard/app/(cockpit)/cockpit-shell.tsx

@@ -58,6 +58,7 @@ const TITLE_FOR_SCREEN: Record<string, string> = {
   editor: "Workflow editor",
   profiles: "Harness profiles",
   checks: "Pre-PR checks",
+  health: "System health",
   users: "Users",
   trace: "Run trace",
   ticket: "Ticket runs",

apps/dashboard/app/(cockpit)/health/page.tsx

@@ -0,0 +1,11 @@
+import { Suspense } from "react";
+import { HealthData } from "@/app/health-data";
+import { HealthSkeleton } from "@/app/health-skeleton";
+
+export default function HealthPage() {
+  return (
+    <Suspense fallback={<HealthSkeleton />}>
+      <HealthData />
+    </Suspense>
+  );
+}

apps/dashboard/app/health-data.tsx

@@ -0,0 +1,12 @@
+import { redirect } from "next/navigation";
+import type { SystemHealthResponse } from "@shared/contracts";
+import { getJSON } from "@/lib/api/server";
+import { requireSession } from "@/lib/auth/session";
+import { HealthScreen } from "@/components/cockpit/screens/health";
+
+export async function HealthData() {
+  const session = await requireSession();
+  if (!session.canManageUsers) redirect("/");
+  const data = await getJSON<SystemHealthResponse>("/api/v1/system/health");
+  return <HealthScreen data={data} />;
+}

apps/dashboard/app/health-skeleton.tsx

@@ -0,0 +1,21 @@
+import { Block } from "./skeleton-block";
+
+export function HealthSkeleton() {
+  return (
+    <div className="mx-auto w-full max-w-[1120px] px-4 pb-10 pt-5 lg:px-6 lg:pt-6">
+      <div className="mb-5 flex items-end justify-between border-b border-neutral-300 pb-5">
+        <div className="space-y-2">
+          <Block className="h-3 w-36" />
+          <Block className="h-8 w-52" />
+          <Block className="h-4 w-[480px] max-w-full" />
+        </div>
+        <Block className="h-8 w-24" />
+      </div>
+      <Block className="mb-5 h-[92px]" />
+      <div className="grid gap-4">
+        <Block className="h-[330px]" />
+        <Block className="h-[220px]" />
+      </div>
+    </div>
+  );
+}

apps/dashboard/components/cockpit/chrome.test.ts

@@ -3,16 +3,18 @@ import test from "node:test";
 
 import { cockpitNavItems } from "./chrome";
 
-test("Harness Profiles is always discoverable while user management remains role-gated", () => {
+test("Harness Profiles is always discoverable while administration remains role-gated", () => {
   const memberIds = cockpitNavItems({ canManageUsers: false }).map(
     (item) => item.id,
   );
   assert.ok(memberIds.includes("profiles"));
+  assert.ok(!memberIds.includes("health"));
   assert.ok(!memberIds.includes("users"));
 
   const adminIds = cockpitNavItems({ canManageUsers: true }).map(
     (item) => item.id,
   );
   assert.ok(adminIds.includes("profiles"));
+  assert.ok(adminIds.includes("health"));
   assert.ok(adminIds.includes("users"));
 });

apps/dashboard/components/cockpit/chrome.tsx

@@ -14,13 +14,14 @@ const NAV = [
   { id: "editor", label: "Workflow editor", glyph: "▷", group: "flow" },
   { id: "profiles", label: "Harness profiles", glyph: "⌘", group: "flow" },
   { id: "checks", label: "Pre-PR checks", glyph: "☑", group: "flow" },
+  { id: "health", label: "System health", glyph: "＋", group: "team" },
   { id: "users", label: "Users", glyph: "U", group: "team" },
 ];
 
 const NAV_GROUPS = [
   { id: "obs", label: "Observability" },
   { id: "flow", label: "Workflow" },
-  { id: "team", label: "Users" },
+  { id: "team", label: "Administration" },
 ];
 
 export const MOBILE_MORE_NAV_IDS = [
@@ -31,6 +32,7 @@ export const MOBILE_MORE_NAV_IDS = [
   "cost",
   "profiles",
   "checks",
+  "health",
   "users",
 ] as const;
 
@@ -44,7 +46,8 @@ export function cockpitNavItems({
   canManageUsers: boolean;
 }) {
   return NAV.filter(
-    (item) => item.id !== "users" || canManageUsers,
+    (item) =>
+      (item.id !== "users" && item.id !== "health") || canManageUsers,
   );
 }
 

apps/dashboard/components/cockpit/screens/health.test.tsx

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import React from "react";
+import { act, create } from "react-test-renderer";
+import { AppRouterContext } from "next/dist/shared/lib/app-router-context.shared-runtime";
+import type { SystemHealthResponse } from "@shared/contracts";
+import { HealthScreen } from "./health";
+
+(globalThis as typeof globalThis & { React: typeof React }).React = React;
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const data: SystemHealthResponse = {
+  generatedAt: "2026-08-20T12:00:00.000Z",
+  summary: { total: 2, live: 1, down: 1, notConfigured: 0, criticalDown: 1 },
+  integrations: [
+    {
+      id: "database",
+      label: "Database",
+      group: "core",
+      envVars: ["DATABASE_URL"],
+      critical: true,
+      mode: "live",
+      ping: { ok: true, latencyMs: 12 },
+    },
+    {
+      id: "jira",
+      label: "Jira",
+      group: "core",
+      envVars: ["JIRA_API_TOKEN"],
+      critical: true,
+      mode: "down",
+      ping: { ok: false, latencyMs: 40, error: "Jira authentication check failed." },
+    },
+  ],
+  alerts: [
+    {
+      severity: "critical",
+      integrationId: "jira",
+      message: "Jira: Jira authentication check failed.",
+      fixHint: "Check JIRA_API_TOKEN and the provider setup.",
+    },
+  ],
+};
+
+function textOf(value: unknown): string {
+  if (typeof value === "string" || typeof value === "number") return String(value);
+  if (Array.isArray(value)) return value.map(textOf).join(" ");
+  if (value && typeof value === "object" && "children" in value) {
+    return textOf((value as { children?: unknown }).children);
+  }
+  return "";
+}
+
+test("health screen exposes the failed service, fix hint, and safe env names", () => {
+  const router = { refresh() {} };
+  let renderer!: ReturnType<typeof create>;
+  act(() => {
+    renderer = create(
+      <AppRouterContext.Provider value={router as never}>
+        <HealthScreen data={data} />
+      </AppRouterContext.Provider>,
+    );
+  });
+  const text = textOf(renderer.toJSON());
+  assert.match(text, /Action required/);
+  assert.match(text, /Jira authentication check failed/);
+  assert.match(text, /JIRA_API_TOKEN/);
+  assert.match(text, /DATABASE_URL/);
+  assert.doesNotMatch(text, /secret-value/);
+  act(() => renderer.unmount());
+});
+
+test("scan again refreshes the server data", () => {
+  let refreshes = 0;
+  const router = { refresh: () => refreshes++ };
+  let renderer!: ReturnType<typeof create>;
+  act(() => {
+    renderer = create(
+      <AppRouterContext.Provider value={router as never}>
+        <HealthScreen data={{ ...data, alerts: [], summary: { ...data.summary, down: 0, criticalDown: 0 } }} />
+      </AppRouterContext.Provider>,
+    );
+  });
+  const button = renderer.root.findByProps({ children: "Scan again" });
+  act(() => button.props.onClick());
+  assert.equal(refreshes, 1);
+  act(() => renderer.unmount());
+});