fix(dashboard): statusSignalHasCommErrorKey sibling companion lands on the live-status mirror

The harness contract gained statusSignalHasCommErrorKey (REQ-B
version-skew observability) with its dashboard sibling explicitly left
to the dashboard owner. Add the byte-identity-safe companion to
live-status.ts — placed OUTSIDE the commErrorFromStatusSignal region
pinned by commError-contract-drift.test.ts (only the decode function
source is mirrored; proven by the drift suite staying green) — so
dashboard consumers can distinguish a present-but-undecodable overlay
from a genuinely absent one. Unit-pinned: unknown future kind,
well-formed, absent, and array-expando wire shapes.

Author: jpr5

showcase/shell-dashboard/src/lib/live-status.test.ts

@@ -1,17 +1,20 @@
 import { describe, it, expect, vi, afterEach } from "vitest";
 import {
   CATALOG_TO_D5_KEY,
+  FLEET_COMM_ERROR_SIGNAL_KEY,
   STARTER_COLUMNS,
   STARTER_LEVELS,
   STATUS_LIST_FIELDS,
   buildStarterBadge,
+  commErrorFromStatusSignal,
   keyFor,
   mergeRowsToMap,
   resolveCell,
   resolveD5Row,
   resolveD6Row,
   resolveStarterRow,
   starterIsSupported,
+  statusSignalHasCommErrorKey,
   upsertByKey,
 } from "./live-status";
 import type { LiveStatusMap, StatusRow, StarterLevel } from "./live-status";
@@ -53,6 +56,45 @@ function mapOf(rows: StatusRow[]): LiveStatusMap {
   return m;
 }
 
+describe("statusSignalHasCommErrorKey (sibling of the harness contract companion)", () => {
+  it("distinguishes 'key present but undecodable' from 'genuinely absent' without changing the decode contract", () => {
+    // Key present, kind unknown to this reader (the version-skew case): the
+    // decode fail-safes to undefined but the companion still sees the key.
+    const unknownKind = {
+      [FLEET_COMM_ERROR_SIGNAL_KEY]: {
+        kind: "some-future-kind",
+        message: "x",
+        observedAt: FRESH_OBSERVED_AT,
+      },
+    };
+    expect(commErrorFromStatusSignal(unknownKind)).toBeUndefined();
+    expect(statusSignalHasCommErrorKey(unknownKind)).toBe(true);
+
+    // Key present and well-formed: both sides agree.
+    const wellFormed = {
+      [FLEET_COMM_ERROR_SIGNAL_KEY]: {
+        kind: "worker-unreachable",
+        message: "connect ECONNREFUSED",
+        observedAt: FRESH_OBSERVED_AT,
+      },
+    };
+    expect(commErrorFromStatusSignal(wellFormed)).toBeDefined();
+    expect(statusSignalHasCommErrorKey(wellFormed)).toBe(true);
+
+    // Genuinely absent / never a valid wire shape (mirrors the decoder's
+    // null / non-object / array guards — including the key as an array
+    // expando property).
+    expect(statusSignalHasCommErrorKey({ failedCount: 0 })).toBe(false);
+    expect(statusSignalHasCommErrorKey(null)).toBe(false);
+    expect(statusSignalHasCommErrorKey("nope")).toBe(false);
+    expect(
+      statusSignalHasCommErrorKey(
+        Object.assign([], { [FLEET_COMM_ERROR_SIGNAL_KEY]: {} }),
+      ),
+    ).toBe(false);
+  });
+});
+
 describe("keyFor", () => {
   it("integration-level dimensions have no feature segment", () => {
     expect(keyFor("health", "agno")).toBe("health:agno");

showcase/shell-dashboard/src/lib/live-status.ts

@@ -204,6 +204,28 @@ export function commErrorFromStatusSignal(
   return out;
 }
 
+/**
+ * Companion to `commErrorFromStatusSignal`: does the signal blob CARRY the
+ * well-known comm-error key at all, regardless of whether the embedded value
+ * decodes? Lets consumers distinguish "key present but undecodable" (a REQ-B
+ * overlay written by a NEWER producer — e.g. a new `PoolCommErrorKind` rolled
+ * out write-side first — that this reader silently drops; count/log it) from
+ * "genuinely absent" (nothing to report) without changing the decode's return
+ * contract. Mirrors the decoder's wire-shape guards: a null / non-object /
+ * array blob is never a valid signal, so the key cannot be "present" on one.
+ * Sibling of the harness contract's `statusSignalHasCommErrorKey`
+ * (`showcase/harness/src/fleet/contracts.ts`) — both live OUTSIDE the
+ * byte-identity region pinned by `commError-contract-drift.test.ts` (only the
+ * `commErrorFromStatusSignal` function source is mirrored). Pure;
+ * unit-tested.
+ */
+export function statusSignalHasCommErrorKey(signal: unknown): boolean {
+  if (signal === null || typeof signal !== "object" || Array.isArray(signal)) {
+    return false;
+  }
+  return FLEET_COMM_ERROR_SIGNAL_KEY in signal;
+}
+
 export interface StatusRow {
   id: string;
   key: string;