feat(showcase): surface fleet pool comm-errors (unreachable overlay) on the dashboard

Author: jpr5

showcase/shell-dashboard/src/components/__tests__/depth-chip.test.tsx

@@ -199,6 +199,56 @@ describe("DepthChip", () => {
     const chip = getByTestId("depth-chip");
     expect(chip.className).toContain("danger");
   });
+
+  // ── REQ-B: pool comm-error / unreachable treatment ──────────────────
+
+  it("renders a DISTINCT unreachable treatment when unreachable=true", () => {
+    const { getByTestId } = render(
+      <DepthChip
+        depth={5}
+        status="wired"
+        chipColor="green"
+        unreachable
+        commTooltip="pool unreachable: worker-unreachable — worker w-7"
+      />,
+    );
+    const chip = getByTestId("depth-chip");
+    expect(chip.getAttribute("data-status")).toBe("unreachable");
+    expect(chip.getAttribute("data-surface-state")).toBe("unreachable");
+    // Tooltip names the comm-error kind + worker.
+    expect(chip.getAttribute("title")).toContain("worker-unreachable");
+    expect(chip.getAttribute("title")).toContain("w-7");
+    // Visually distinct from green/amber/red/gray — uses the indigo overlay,
+    // NOT the emerald/danger/amber/text-muted probe-colour classes.
+    expect(chip.className).toContain("indigo");
+    expect(chip.className).not.toContain("emerald");
+    expect(chip.className).not.toContain("danger");
+  });
+
+  it("unreachable overrides chipColor='red' (comm error ≠ red test)", () => {
+    const { getByTestId } = render(
+      <DepthChip depth={3} status="wired" chipColor="red" unreachable />,
+    );
+    const chip = getByTestId("depth-chip");
+    expect(chip.getAttribute("data-status")).toBe("unreachable");
+    // A comm error must never be painted as a red test.
+    expect(chip.className).not.toContain("danger");
+    expect(chip.className).toContain("indigo");
+  });
+
+  it("renders normally (no unreachable) when unreachable=false", () => {
+    const { getByTestId } = render(
+      <DepthChip
+        depth={5}
+        status="wired"
+        chipColor="green"
+        unreachable={false}
+      />,
+    );
+    const chip = getByTestId("depth-chip");
+    expect(chip.getAttribute("data-status")).not.toBe("unreachable");
+    expect(chip.className).toContain("emerald");
+  });
 });
 
 describe("depthColorClass (direct)", () => {

showcase/shell-dashboard/src/components/__tests__/unified-cell.test.tsx

@@ -13,12 +13,13 @@
 import React from "react";
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render } from "@testing-library/react";
-import { UnifiedCell } from "../unified-cell";
+import { UnifiedCell, arePropsEqual } from "../unified-cell";
 import type { UnifiedCellProps } from "../unified-cell";
 import type { CellContext } from "@/components/feature-grid";
-import type { CellModel, TestLevel, ChipColor } from "@/lib/cell-model";
+import type { CellModel, TestLevel } from "@/lib/cell-model";
 import type { Overlay } from "@/lib/overlay-types";
-import type { LiveStatusMap } from "@/lib/live-status";
+import type { LiveStatusMap, StatusRow } from "@/lib/live-status";
+import { keyFor } from "@/lib/live-status";
 
 // ---------------------------------------------------------------------------
 // Mocks -- isolate UnifiedCell's rendering logic from child components
@@ -29,12 +30,21 @@ vi.mock("@/components/depth-chip", () => ({
     ({
       depth,
       chipColor,
+      unreachable,
+      commTooltip,
     }: {
       depth: number;
       status: string;
       chipColor?: string;
+      unreachable?: boolean;
+      commTooltip?: string;
     }) => (
-      <span data-testid="mock-depth-chip" data-chip-color={chipColor ?? ""}>
+      <span
+        data-testid="mock-depth-chip"
+        data-chip-color={chipColor ?? ""}
+        data-unreachable={unreachable ? "1" : "0"}
+        data-comm-tooltip={commTooltip ?? ""}
+      >
         D{depth}
       </span>
     ),
@@ -176,6 +186,7 @@ function makeModel(overrides?: Partial<CellModel>): CellModel {
     ceilingDepth: 5,
     chipColor: "green",
     isRegression: false,
+    surfaceState: "green",
     ...overrides,
   };
 }
@@ -198,7 +209,7 @@ describe("UnifiedCell", () => {
     it("renders only the ban icon with no badges and no depth chip", () => {
       const ctx = makeCtx();
       const model = makeModel({ supported: false });
-      const { getByTestId, queryByTestId, queryAllByTestId } = render(
+      const { getByTestId, queryByTestId } = render(
         <UnifiedCell
           ctx={ctx}
           model={model}
@@ -551,4 +562,110 @@ describe("UnifiedCell", () => {
       expect(queryByTestId("mock-badge-API")).not.toBeInTheDocument();
     });
   });
+
+  // ── REQ-B: pool comm-error → unreachable depth chip ─────────────────
+  describe("pool comm-error overlay (REQ-B)", () => {
+    it("renders the depth chip in the unreachable treatment when surfaceState is unreachable", () => {
+      const ctx = makeCtx();
+      const model = makeModel({
+        surfaceState: "unreachable",
+        // chipColor is preserved underneath — the overlay does not recolour it.
+        chipColor: "green",
+        commError: {
+          kind: "worker-unreachable",
+          message: "connect ECONNREFUSED",
+          workerId: "worker-7",
+          observedAt: new Date().toISOString(),
+        },
+      });
+      const { getByTestId } = render(
+        <UnifiedCell ctx={ctx} model={model} overlays={overlaySet("depth")} />,
+      );
+      const chip = getByTestId("mock-depth-chip");
+      expect(chip.getAttribute("data-unreachable")).toBe("1");
+      // Tooltip names the comm-error kind AND the worker for triage.
+      const tooltip = chip.getAttribute("data-comm-tooltip") ?? "";
+      expect(tooltip).toContain("worker-unreachable");
+      expect(tooltip).toContain("worker-7");
+    });
+
+    it("a normal red cell renders WITHOUT the unreachable treatment", () => {
+      const ctx = makeCtx();
+      const model = makeModel({ chipColor: "red", surfaceState: "red" });
+      const { getByTestId } = render(
+        <UnifiedCell ctx={ctx} model={model} overlays={overlaySet("depth")} />,
+      );
+      const chip = getByTestId("mock-depth-chip");
+      expect(chip.getAttribute("data-unreachable")).toBe("0");
+      expect(chip.getAttribute("data-chip-color")).toBe("red");
+    });
+  });
+
+  // ── REQ-B: arePropsEqual watches the d6 AGGREGATE row (worker-death) ──
+  describe("arePropsEqual aggregate comm-error watch (Fix 2)", () => {
+    function commRow(key: string): StatusRow {
+      return {
+        id: `id-${key}`,
+        key,
+        dimension: "d6",
+        state: "green",
+        signal: {
+          __fleetCommError: {
+            kind: "worker-crashed-mid-job",
+            message: "lease expired with no terminal report",
+            workerId: "fleet-worker-3",
+            observedAt: new Date().toISOString(),
+          },
+        },
+        observed_at: new Date().toISOString(),
+        transitioned_at: new Date().toISOString(),
+        fail_count: 0,
+        first_failure_at: null,
+      };
+    }
+
+    it("forces a re-render when a comm error lands solely on the aggregate d6:<slug> row", () => {
+      const slug = "next";
+      // SAME model reference both renders — isolates the directKeys watch from
+      // the modelsEqual backstop. Without keyFor("d6", slug) in directKeys this
+      // returns true (skips the repaint) and the unreachable overlay is missed.
+      const model = makeModel();
+      const overlays = overlaySet("depth");
+
+      const prevLive: LiveStatusMap = new Map();
+      const nextLive: LiveStatusMap = new Map();
+      // Only the aggregate row differs — it now carries the worker-death signal.
+      nextLive.set(keyFor("d6", slug), commRow(keyFor("d6", slug)));
+
+      // Share ALL ctx fields except liveStatus (arePropsEqual compares the
+      // integration/feature/demo objects by reference, so a fresh makeCtx per
+      // side would short-circuit on those before reaching the directKeys watch).
+      const baseCtx = makeCtx({ liveStatus: prevLive });
+      const prev: UnifiedCellProps = { ctx: baseCtx, model, overlays };
+      const next: UnifiedCellProps = {
+        ctx: { ...baseCtx, liveStatus: nextLive },
+        model,
+        overlays,
+      };
+
+      // false === "props differ, re-render". The aggregate-key watch must catch
+      // the change to the aggregate row even with an identical model reference.
+      expect(arePropsEqual(prev, next)).toBe(false);
+    });
+
+    it("still skips the re-render when nothing the cell reads changed (no false repaint)", () => {
+      const model = makeModel();
+      const overlays = overlaySet("depth");
+      // Two distinct (empty) map identities but no watched key differs. Share
+      // ctx fields so the comparison reaches (and passes) the directKeys loop.
+      const baseCtx = makeCtx({ liveStatus: new Map() });
+      const prev: UnifiedCellProps = { ctx: baseCtx, model, overlays };
+      const next: UnifiedCellProps = {
+        ctx: { ...baseCtx, liveStatus: new Map() },
+        model,
+        overlays,
+      };
+      expect(arePropsEqual(prev, next)).toBe(true);
+    });
+  });
 });

showcase/shell-dashboard/src/components/depth-chip.tsx

@@ -33,6 +33,17 @@ export interface DepthChipProps {
    * already determined the correct color (e.g. green when achieved == ceiling).
    */
   chipColor?: "green" | "amber" | "red" | "gray";
+  /**
+   * Pool COMMUNICATION error (REQ-B). When set, the chip renders a DISTINCT
+   * "couldn't reach the pool" treatment — a purple/indigo fill with a "⚡"
+   * glyph — that is visually unlike green/amber/red/gray, so an operator can
+   * tell "the pool was unreachable" apart from "the test went red". The
+   * underlying depth/colour is intentionally suppressed in favour of the
+   * comm-error overlay; the descriptive tooltip is supplied via `commTooltip`.
+   */
+  unreachable?: boolean;
+  /** Tooltip text for the unreachable treatment (names the comm-error kind). */
+  commTooltip?: string;
 }
 
 /**
@@ -91,7 +102,27 @@ export function DepthChip({
   regression,
   maxDepth,
   chipColor,
+  unreachable,
+  commTooltip,
 }: DepthChipProps) {
+  // Pool comm-error overlay (REQ-B) takes precedence over every probe colour:
+  // a "couldn't reach the pool" state must never be mistaken for a red test.
+  // A distinct indigo fill + ⚡ glyph, resolved BEFORE the unshipped/unsupported
+  // branches so an unreachable cell is always loud.
+  if (unreachable) {
+    return (
+      <span
+        data-testid="depth-chip"
+        data-status="unreachable"
+        data-surface-state="unreachable"
+        className="inline-flex items-center justify-center min-w-[32px] h-5 px-1.5 rounded text-[10px] font-semibold tabular-nums border border-indigo-400/60 bg-indigo-500/20 text-indigo-300"
+        title={commTooltip ?? "pool unreachable — comm error"}
+      >
+        ⚡
+      </span>
+    );
+  }
+
   if (status === "unshipped") {
     return (
       <span

showcase/shell-dashboard/src/components/unified-cell.tsx

@@ -14,6 +14,7 @@
 import { memo, useState, useEffect, useRef, useCallback } from "react";
 import type { CellContext } from "@/components/feature-grid";
 import type { CellModel, TestLevel } from "@/lib/cell-model";
+import type { PoolCommError } from "@/lib/live-status";
 import { DepthChip } from "@/components/depth-chip";
 import { Badge, FlashOnChange } from "@/components/badges";
 import type { BadgeTone } from "@/lib/live-status";
@@ -97,6 +98,21 @@ function TestBadge({
   );
 }
 
+// ---------------------------------------------------------------------------
+// Pool comm-error tooltip (REQ-B)
+// ---------------------------------------------------------------------------
+
+/**
+ * Format the "couldn't reach the pool" tooltip for the unreachable chip,
+ * NAMING the `PoolCommErrorKind` and (when known) the worker so an operator
+ * can triage which pool member dropped. Falls back to the raw message when no
+ * structured detail is available.
+ */
+export function commErrorTooltip(err: PoolCommError): string {
+  const worker = err.workerId ? ` — worker ${err.workerId}` : "";
+  return `pool unreachable: ${err.kind}${worker} — ${err.message}`;
+}
+
 // ---------------------------------------------------------------------------
 // Layer renderers
 // ---------------------------------------------------------------------------
@@ -173,6 +189,10 @@ function DepthLayer({ ctx, model }: { ctx: CellContext; model: CellModel }) {
           chipColor={model.chipColor}
           depth={model.achievedDepth}
           status="wired"
+          unreachable={model.surfaceState === "unreachable"}
+          commTooltip={
+            model.commError ? commErrorTooltip(model.commError) : undefined
+          }
         />
       </button>
       {drilldownOpen && (
@@ -361,6 +381,10 @@ function modelsEqual(a: CellModel, b: CellModel): boolean {
     a.achievedDepth === b.achievedDepth &&
     a.ceilingDepth === b.ceilingDepth &&
     a.chipColor === b.chipColor &&
+    a.surfaceState === b.surfaceState &&
+    a.commError?.kind === b.commError?.kind &&
+    a.commError?.workerId === b.commError?.workerId &&
+    a.commError?.message === b.commError?.message &&
     a.d6Effective === b.d6Effective &&
     a.isRegression === b.isRegression &&
     testLevelsEqual(a.d3, b.d3) &&
@@ -370,7 +394,13 @@ function modelsEqual(a: CellModel, b: CellModel): boolean {
   );
 }
 
-function arePropsEqual(
+/**
+ * Memo equality used by `UnifiedCell`. Exported for direct unit testing of the
+ * `directKeys` watch (a comm error landing solely on the aggregate `d6:<slug>`
+ * row must force a re-render even when the precomputed `model` reference is
+ * reused). Returns `true` to SKIP the re-render, `false` to re-render.
+ */
+export function arePropsEqual(
   prev: UnifiedCellProps,
   next: UnifiedCellProps,
 ): boolean {
@@ -398,6 +428,17 @@ function arePropsEqual(
     keyFor("e2e", slug, featureId),
     keyFor("chat", slug),
     keyFor("tools", slug),
+    // health:<slug> is a pool comm-error carrier (REQ-B) even though it does
+    // not feed the depth ladder — watch it so an incoming comm-error signal
+    // repaints the cell's unreachable overlay.
+    keyFor("health", slug),
+    // d6:<slug> is the integration-level AGGREGATE row. It does not feed the
+    // per-cell depth ladder (that reads `d6:<slug>/<featureType>`), but it IS
+    // a pool comm-error carrier (REQ-B): a worker-death comm error lands solely
+    // on the aggregate row, and `decodeCellCommError` in buildCellModel reads it
+    // to light the cell's "unreachable" overlay. Watch it here so that signal
+    // actually triggers a re-render — keep in sync with buildCellModel.
+    keyFor("d6", slug),
   ];
 
   // Add D5 + D6 sub-keys from CATALOG_TO_D5_KEY. D6 is per-cell (not the