@blackbelt-technology/pi-agent-dashboard 0.4.5 → 0.5.0

package/packages/server/src/__tests__/browser-gateway-snapshot-on-connect.test.ts

@@ -0,0 +1,143 @@
+/**
+ * Regression suite for change: fix-stale-sessions-on-reconnect.
+ *
+ * Pin: on every browser WS connect, the gateway sends exactly one
+ * `sessions_snapshot` message containing all sessions and all non-empty
+ * per-cwd orders, AND it does NOT iterate per-session `session_added`
+ * or per-cwd `sessions_reordered` for the bootstrap.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import { createBrowserGateway } from "../browser-gateway.js";
+import { createMemorySessionManager } from "../memory-session-manager.js";
+import { createMemoryEventStore } from "../memory-event-store.js";
+import type { PiGateway } from "../pi-gateway.js";
+import type { SessionOrderManager } from "../session-order-manager.js";
+
+function makeFakeWs() {
+  const ws = new EventEmitter() as EventEmitter & {
+    send: ReturnType<typeof vi.fn>;
+    close: ReturnType<typeof vi.fn>;
+    readyState: number;
+    OPEN: number;
+  };
+  ws.send = vi.fn();
+  ws.close = vi.fn();
+  ws.readyState = 1;
+  ws.OPEN = 1;
+  return ws;
+}
+
+function makeStubPiGateway(): PiGateway {
+  return {
+    start: vi.fn(),
+    stop: vi.fn(),
+    sendToSession: vi.fn(),
+    getConnectedSessionIds: vi.fn(() => []),
+    hasSession: vi.fn(() => false),
+    onEvent: vi.fn(),
+  } as unknown as PiGateway;
+}
+
+function makeStubOrderManager(orders: Record<string, string[]>): SessionOrderManager {
+  return {
+    insert: vi.fn(),
+    remove: vi.fn(),
+    getOrder: vi.fn((cwd: string) => orders[cwd] ?? []),
+    reorder: vi.fn(),
+    getAllOrders: vi.fn(() => orders),
+    moveToFront: vi.fn(),
+  } as unknown as SessionOrderManager;
+}
+
+function sentMessages(ws: ReturnType<typeof makeFakeWs>) {
+  return ws.send.mock.calls
+    .map((args) => {
+      try { return JSON.parse(String(args[0])); } catch { return null; }
+    })
+    .filter((m): m is Record<string, unknown> => !!m && typeof m === "object");
+}
+
+describe("browser-gateway on-connect sessions_snapshot", () => {
+  it("sends exactly one sessions_snapshot and no per-session session_added/sessions_reordered", () => {
+    const sessionManager = createMemorySessionManager();
+    sessionManager.restore({
+      id: "alive-1",
+      cwd: "/repo/a",
+      source: "tui",
+      status: "active",
+      startedAt: 1,
+      hidden: false,
+      dataUnavailable: false,
+    } as never);
+    sessionManager.restore({
+      id: "ended-1",
+      cwd: "/repo/a",
+      source: "tui",
+      status: "ended",
+      startedAt: 2,
+      endedAt: 3,
+      hidden: false,
+      dataUnavailable: true,
+    } as never);
+
+    const orders: Record<string, string[]> = {
+      "/repo/a": ["alive-1"],
+      "/repo/empty": [], // should be filtered out of snapshot.orders
+    };
+
+    const gateway = createBrowserGateway(
+      sessionManager,
+      createMemoryEventStore(() => false),
+      makeStubPiGateway(),
+      undefined,
+      undefined,
+      makeStubOrderManager(orders),
+    );
+
+    const ws = makeFakeWs();
+    gateway.wss.emit("connection", ws, {});
+
+    const msgs = sentMessages(ws);
+    const snapshots = msgs.filter((m) => m.type === "sessions_snapshot");
+    const sessionAddeds = msgs.filter((m) => m.type === "session_added");
+    const sessionsReordereds = msgs.filter((m) => m.type === "sessions_reordered");
+
+    expect(snapshots).toHaveLength(1);
+    expect(sessionAddeds).toHaveLength(0);
+    expect(sessionsReordereds).toHaveLength(0);
+
+    const snap = snapshots[0] as { sessions: Array<{ id: string; status: string }>; orders: Record<string, string[]> };
+    const ids = snap.sessions.map((s) => s.id).sort();
+    expect(ids).toEqual(["alive-1", "ended-1"]); // alive AND ended both included
+    expect(snap.orders).toEqual({ "/repo/a": ["alive-1"] }); // empty entry filtered out
+  });
+
+  it("snapshot is sent before pinned_dirs_updated and other on-connect sends", () => {
+    const sessionManager = createMemorySessionManager();
+    const gateway = createBrowserGateway(
+      sessionManager,
+      createMemoryEventStore(() => false),
+      makeStubPiGateway(),
+      undefined,
+      undefined,
+      makeStubOrderManager({}),
+      // Stub preferencesStore so pinned_dirs_updated fires.
+      {
+        getPinnedDirectories: () => [],
+        setPinnedDirectories: () => {},
+        getSessionOrder: () => ({}),
+        setSessionOrder: () => {},
+      } as never,
+    );
+
+    const ws = makeFakeWs();
+    gateway.wss.emit("connection", ws, {});
+
+    const types = sentMessages(ws).map((m) => m.type as string);
+    const snapshotIdx = types.indexOf("sessions_snapshot");
+    const pinnedIdx = types.indexOf("pinned_dirs_updated");
+    expect(snapshotIdx).toBeGreaterThanOrEqual(0);
+    expect(pinnedIdx).toBeGreaterThan(snapshotIdx);
+  });
+});

package/packages/server/src/__tests__/build-auth-status.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Tests for `_buildAuthStatus` — server-side pure derivation that merges
+ * the bridge-pushed catalogue, auth.json data, and the local OAuth handler set.
+ * See change: replace-hardcoded-provider-lists.
+ */
+import { describe, it, expect } from "vitest";
+import { _buildAuthStatus, type AuthData } from "../provider-auth-storage.js";
+import type { ProviderHandler } from "../provider-auth-handlers.js";
+import type { ProviderInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+function makeOAuthHandler(providerId: string, displayName: string, flowType: "auth_code" | "device_code" = "auth_code"): ProviderHandler {
+  return {
+    flowType,
+    providerId,
+    displayName,
+    callbackPort: 0,
+    callbackPath: "/cb",
+    buildAuthUrl: () => "",
+    exchangeCode: async () => ({ type: "oauth", refresh: "", access: "", expires: 0 }),
+  } as ProviderHandler;
+}
+
+const ANTHROPIC_HANDLER = makeOAuthHandler("anthropic", "Anthropic (Claude Pro/Max)");
+
+describe("_buildAuthStatus", () => {
+  it("returns OAuth handler rows with authenticated:false when no catalogue or auth", () => {
+    const result = _buildAuthStatus([], {}, [ANTHROPIC_HANDLER]);
+    expect(result).toEqual([
+      {
+        id: "anthropic",
+        name: "Anthropic (Claude Pro/Max)",
+        flowType: "auth_code",
+        authenticated: false,
+      },
+    ]);
+  });
+
+  it("OAuth row authenticated:true with expires when auth.json has oauth credential", () => {
+    const auth: AuthData = {
+      anthropic: { type: "oauth", refresh: "r", access: "a", expires: 999 },
+    };
+    const result = _buildAuthStatus([], auth, [ANTHROPIC_HANDLER]);
+    expect(result[0]).toMatchObject({
+      id: "anthropic",
+      authenticated: true,
+      expires: 999,
+    });
+  });
+
+  it("emits both anthropic (OAuth) and anthropic-api (API key) rows when catalogue has anthropic", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "anthropic", displayName: "Anthropic", hasOAuth: true, configured: false },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, [ANTHROPIC_HANDLER]);
+    expect(result).toHaveLength(2);
+    expect(result[0].id).toBe("anthropic");
+    expect(result[0].flowType).toBe("auth_code");
+    expect(result[1].id).toBe("anthropic-api");
+    expect(result[1].name).toBe("Anthropic (API Key)");
+    expect(result[1].flowType).toBe("api_key");
+  });
+
+  it("non-collision catalogue ids use bare id and bare display name", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: false },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, []);
+    expect(result[0]).toEqual({
+      id: "deepseek",
+      name: "DeepSeek",
+      flowType: "api_key",
+      authenticated: false,
+    });
+  });
+
+  it("masks stored API key (>=12 chars) showing first 5 + ... + last 3", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: true },
+    ];
+    const auth: AuthData = { deepseek: { type: "api_key", key: "sk-abcdef123456789" } };
+    const result = _buildAuthStatus(catalogue, auth, []);
+    expect(result[0].authenticated).toBe(true);
+    expect(result[0].maskedKey).toBe("sk-ab...789");
+  });
+
+  it("masks short stored API key as ****", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "groq", displayName: "Groq", hasOAuth: false, configured: true },
+    ];
+    const auth: AuthData = { groq: { type: "api_key", key: "short" } };
+    const result = _buildAuthStatus(catalogue, auth, []);
+    expect(result[0].maskedKey).toBe("****");
+  });
+
+  it("ambient catalogue entry forces authenticated:true and maskedKey:'(ambient)' even with no auth.json entry", () => {
+    const catalogue: ProviderInfo[] = [
+      {
+        id: "google-vertex",
+        displayName: "Google Vertex AI",
+        hasOAuth: false,
+        configured: false,
+        ambient: true,
+      },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, []);
+    expect(result[0]).toMatchObject({
+      id: "google-vertex",
+      authenticated: true,
+      ambient: true,
+      maskedKey: "(ambient)",
+    });
+  });
+
+  it("envVar from catalogue propagates to status row", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "openai", displayName: "OpenAI", hasOAuth: false, configured: false, envVar: "OPENAI_API_KEY" },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, []);
+    expect(result[0].envVar).toBe("OPENAI_API_KEY");
+    expect(result[0].authenticated).toBe(false);
+  });
+
+  it("OAuth credential under anthropic does NOT mark anthropic-api authenticated", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "anthropic", displayName: "Anthropic", hasOAuth: true, configured: true },
+    ];
+    const auth: AuthData = {
+      anthropic: { type: "oauth", refresh: "r", access: "a", expires: 999 },
+    };
+    const result = _buildAuthStatus(catalogue, auth, [ANTHROPIC_HANDLER]);
+    const oauthRow = result.find((r) => r.id === "anthropic");
+    const apiRow = result.find((r) => r.id === "anthropic-api");
+    expect(oauthRow?.authenticated).toBe(true);
+    expect(apiRow?.authenticated).toBe(false);
+    expect(apiRow?.maskedKey).toBeUndefined();
+  });
+
+  it("api_key credential at auth.json[anthropic] marks anthropic-api authenticated", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "anthropic", displayName: "Anthropic", hasOAuth: true, configured: true },
+    ];
+    const auth: AuthData = {
+      anthropic: { type: "api_key", key: "sk-anthropic-key-1234" },
+    };
+    const result = _buildAuthStatus(catalogue, auth, [ANTHROPIC_HANDLER]);
+    const oauthRow = result.find((r) => r.id === "anthropic");
+    const apiRow = result.find((r) => r.id === "anthropic-api");
+    expect(oauthRow?.authenticated).toBe(false);
+    expect(apiRow?.authenticated).toBe(true);
+    expect(apiRow?.maskedKey).toBe("sk-an...234");
+  });
+
+  it("skips API-key rows for catalogue entries marked custom:true", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: false },
+      { id: "proxy", displayName: "proxy", hasOAuth: false, configured: false, custom: true },
+      { id: "your-llmproxy", displayName: "your-llmproxy", hasOAuth: false, configured: true, custom: true },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, []);
+    const ids = result.map((r) => r.id);
+    expect(ids).toContain("deepseek");
+    expect(ids).not.toContain("proxy");
+    expect(ids).not.toContain("your-llmproxy");
+  });
+
+  it("OAuth row IS still emitted for a custom provider with an OAuth handler", () => {
+    // A custom provider whose id matches a registered OAuth handler
+    // should still surface its OAuth row — only the API-key row is
+    // suppressed for custom providers.
+    const corporateHandler = makeOAuthHandler("corporate-sso", "Corporate SSO");
+    const catalogue: ProviderInfo[] = [
+      { id: "corporate-sso", displayName: "Corporate SSO", hasOAuth: true, configured: false, custom: true },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, [corporateHandler]);
+    const oauthRow = result.find((r) => r.id === "corporate-sso");
+    const apiKeyRow = result.find((r) => r.id === "corporate-sso-api");
+    expect(oauthRow).toBeDefined();
+    expect(oauthRow?.flowType).toBe("auth_code");
+    expect(apiKeyRow).toBeUndefined();
+  });
+
+  it("preserves OAuth handler order then catalogue order", () => {
+    const catalogue: ProviderInfo[] = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: false },
+      { id: "groq", displayName: "Groq", hasOAuth: false, configured: false },
+    ];
+    const result = _buildAuthStatus(catalogue, {}, [ANTHROPIC_HANDLER]);
+    expect(result.map((r) => r.id)).toEqual(["anthropic", "deepseek", "groq"]);
+  });
+});

package/packages/server/src/__tests__/cold-boot-openspec-broadcast.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Cold-boot OpenSpec broadcast — bootstrap initial poll must broadcast
+ * `openspec_update` to connected browsers when the prior cache was
+ * empty/undefined or the polled data differs from prior.
+ *
+ * Mirrors `post-install-openspec-refresh.test.ts` contract for the
+ * bootstrap path. See change: fix-cold-boot-openspec-protocol.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { discoverAndBroadcastSessions } from "../session-bootstrap.js";
+
+interface SpyDirSvc {
+  knownDirectories: ReturnType<typeof vi.fn>;
+  discoverSessions: ReturnType<typeof vi.fn>;
+  getOpenSpecData: ReturnType<typeof vi.fn>;
+  refreshOpenSpec: ReturnType<typeof vi.fn>;
+  startPolling: ReturnType<typeof vi.fn>;
+}
+
+function stubPolling(): { startPolling: ReturnType<typeof vi.fn> } {
+  return { startPolling: vi.fn() };
+}
+interface SpySessionMgr {
+  get: ReturnType<typeof vi.fn>;
+  restore: ReturnType<typeof vi.fn>;
+}
+interface SpyGateway {
+  broadcastToAll: ReturnType<typeof vi.fn>;
+  broadcastSessionAdded: ReturnType<typeof vi.fn>;
+}
+
+function makeSessionMgr(): SpySessionMgr {
+  return { get: vi.fn(() => undefined), restore: vi.fn() };
+}
+function makeGateway(): SpyGateway {
+  return { broadcastToAll: vi.fn(), broadcastSessionAdded: vi.fn() };
+}
+
+/**
+ * `discoverAndBroadcastSessions` fires the openspec poll fire-and-forget
+ * (`void Promise.all(...)`). We need to await the microtask queue to let
+ * those promises resolve before asserting on broadcasts. A few
+ * `setImmediate` cycles is enough since the test mocks resolve synchronously.
+ */
+async function flush() {
+  await new Promise((resolve) => setImmediate(resolve));
+  await new Promise((resolve) => setImmediate(resolve));
+}
+
+describe("discoverAndBroadcastSessions: cold-boot openspec broadcast", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+  });
+
+  it("broadcasts openspec_update for each cwd whose prior cache was empty/undefined", async () => {
+    const cwds = ["/a", "/b"];
+    const fresh = { initialized: true, changes: [{ name: "c1" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => cwds),
+      discoverSessions: vi.fn(() => []),
+      getOpenSpecData: vi.fn((cwd: string) =>
+        cwd === "/a" ? undefined : { initialized: false, changes: [] },
+      ),
+      refreshOpenSpec: vi.fn(async () => fresh),
+      ...stubPolling(),
+    };
+    const browserGateway = makeGateway();
+
+    await discoverAndBroadcastSessions({
+      sessionManager: makeSessionMgr() as never,
+      browserGateway: browserGateway as never,
+      directoryService: directoryService as never,
+    });
+    await flush();
+
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(broadcasts).toHaveLength(2);
+    expect(broadcasts).toContainEqual({ type: "openspec_update", cwd: "/a", data: fresh });
+    expect(broadcasts).toContainEqual({ type: "openspec_update", cwd: "/b", data: fresh });
+  });
+
+  it("does not broadcast openspec_update when refreshed data equals prior data (warm-restart idempotency)", async () => {
+    const same = { initialized: true, changes: [{ name: "stable" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => ["/p"]),
+      discoverSessions: vi.fn(() => []),
+      getOpenSpecData: vi.fn(() => same),
+      refreshOpenSpec: vi.fn(async () => same),
+      ...stubPolling(),
+    };
+    const browserGateway = makeGateway();
+
+    await discoverAndBroadcastSessions({
+      sessionManager: makeSessionMgr() as never,
+      browserGateway: browserGateway as never,
+      directoryService: directoryService as never,
+    });
+    await flush();
+
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(broadcasts).toHaveLength(0);
+  });
+
+  it("broadcasts when prior is populated and fresh differs", async () => {
+    const prior = { initialized: true, changes: [{ name: "old" } as never] };
+    const fresh = { initialized: true, changes: [{ name: "new" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => ["/p"]),
+      discoverSessions: vi.fn(() => []),
+      getOpenSpecData: vi.fn(() => prior),
+      refreshOpenSpec: vi.fn(async () => fresh),
+      ...stubPolling(),
+    };
+    const browserGateway = makeGateway();
+
+    await discoverAndBroadcastSessions({
+      sessionManager: makeSessionMgr() as never,
+      browserGateway: browserGateway as never,
+      directoryService: directoryService as never,
+    });
+    await flush();
+
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]).toEqual({ type: "openspec_update", cwd: "/p", data: fresh });
+  });
+
+  it("does not block on refreshOpenSpec failure; logs error and skips broadcast for that cwd", async () => {
+    const fresh = { initialized: true, changes: [{ name: "ok" } as never] };
+    const directoryService: SpyDirSvc = {
+      knownDirectories: vi.fn(() => ["/bad", "/good"]),
+      discoverSessions: vi.fn(() => []),
+      getOpenSpecData: vi.fn(() => undefined),
+      refreshOpenSpec: vi.fn(async (cwd: string) => {
+        if (cwd === "/bad") throw new Error("boom");
+        return fresh;
+      }),
+      ...stubPolling(),
+    };
+    const browserGateway = makeGateway();
+
+    await discoverAndBroadcastSessions({
+      sessionManager: makeSessionMgr() as never,
+      browserGateway: browserGateway as never,
+      directoryService: directoryService as never,
+    });
+    await flush();
+
+    const broadcasts = browserGateway.broadcastToAll.mock.calls
+      .map((c: unknown[]) => c[0])
+      .filter((m: any) => m?.type === "openspec_update");
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]).toEqual({ type: "openspec_update", cwd: "/good", data: fresh });
+  });
+});

package/packages/server/src/__tests__/doctor-route.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Route tests for `GET /api/doctor`.
+ *
+ * Asserts:
+ *   - JSON shape contract (every check has `section`; non-ok has message+detail+suggestion)
+ *   - summary counts match
+ *   - fault-tolerance arm: a deps function that throws → 200 with fallback row
+ *   - no Electron-only rows (4.5)
+ *
+ * See change: doctor-rich-output (tasks 4.4–4.5).
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Fastify, { type FastifyInstance } from "fastify";
+import { registerDoctorRoutes } from "../routes/doctor-routes.js";
+import type {
+  DoctorReport,
+  SharedChecksDeps,
+} from "@blackbelt-technology/pi-dashboard-shared/doctor-core.js";
+
+const ELECTRON_ONLY_NAMES = new Set([
+  "Electron",
+  "Bundled Node.js",
+  "Bundled npm",
+  "Offline packages bundle",
+  "Dashboard server code",
+  "Server launch test",
+]);
+
+async function makeApp(buildDeps?: () => SharedChecksDeps): Promise<FastifyInstance> {
+  const app = Fastify({ logger: false });
+  registerDoctorRoutes(app, buildDeps ? { buildDeps } : {});
+  await app.ready();
+  return app;
+}
+
+function fakeDeps(overrides: Partial<SharedChecksDeps> = {}): SharedChecksDeps {
+  return {
+    managedDir: "/tmp/doctor-route-test-managed",
+    detectSystemNode: () => ({ found: true, path: "/usr/bin/node" }),
+    detectPi: () => ({ found: true, path: "/usr/local/bin/pi", source: "system" }),
+    detectOpenSpec: () => ({ found: false }),
+    isApiKeyConfigured: () => true,
+    probeServer: async () => ({ running: true, version: "0.4.6", mode: "production" }),
+    ...overrides,
+  };
+}
+
+describe("/api/doctor", () => {
+  let app: FastifyInstance;
+  afterEach(async () => {
+    await app?.close();
+  });
+
+  it("returns 200 with a DoctorReport envelope", async () => {
+    app = await makeApp(() => fakeDeps());
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as DoctorReport;
+    expect(Array.isArray(body.checks)).toBe(true);
+    expect(body.summary).toBeDefined();
+    expect(typeof body.generatedAt).toBe("number");
+  });
+
+  it("every check has a section", async () => {
+    app = await makeApp(() => fakeDeps());
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    const body = res.json() as DoctorReport;
+    for (const c of body.checks) {
+      expect(c.section).toBeDefined();
+      expect(["runtime", "pi-tooling", "server", "setup", "diagnostics"]).toContain(c.section);
+    }
+  });
+
+  it("every non-ok row carries non-empty message + detail + suggestion (Decision 8 lint)", async () => {
+    app = await makeApp(() =>
+      fakeDeps({
+        detectPi: () => ({ found: false }),
+        detectOpenSpec: () => ({ found: false }),
+        probeServer: async () => ({ running: false }),
+      }),
+    );
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    const body = res.json() as DoctorReport;
+    const nonOk = body.checks.filter((c) => c.status !== "ok");
+    expect(nonOk.length).toBeGreaterThan(0);
+    for (const c of nonOk) {
+      expect(c.message.length).toBeGreaterThan(0);
+      expect((c.detail ?? "").length).toBeGreaterThan(0);
+      expect((c.suggestion ?? "").length).toBeGreaterThan(0);
+    }
+  });
+
+  it("summary counts match the rows", async () => {
+    app = await makeApp(() =>
+      fakeDeps({
+        detectPi: () => ({ found: false }),
+      }),
+    );
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    const body = res.json() as DoctorReport;
+    const ok = body.checks.filter((c) => c.status === "ok").length;
+    const warn = body.checks.filter((c) => c.status === "warning").length;
+    const err = body.checks.filter((c) => c.status === "error").length;
+    expect(body.summary.ok).toBe(ok);
+    expect(body.summary.warnings).toBe(warn);
+    expect(body.summary.errors).toBe(err);
+  });
+
+  it("never returns Electron-only rows (4.5)", async () => {
+    app = await makeApp(() => fakeDeps());
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    const body = res.json() as DoctorReport;
+    for (const c of body.checks) {
+      expect(ELECTRON_ONLY_NAMES.has(c.name)).toBe(false);
+    }
+  });
+
+  it("returns 200 with a single fallback row when buildDeps throws", async () => {
+    app = await makeApp(() => {
+      throw new Error("boom — deps unavailable");
+    });
+    const res = await app.inject({ method: "GET", url: "/api/doctor" });
+    // Per task 4.3, the route returns 200 even on internal failure so the
+    // client always has something to render.
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as DoctorReport;
+    expect(body.checks.length).toBe(1);
+    expect(body.checks[0].status).toBe("error");
+    expect(body.checks[0].name).toMatch(/Doctor failed/i);
+    expect(body.summary.errors).toBe(1);
+  });
+});