From 8d29ebf53c0e643cd879ac88ec70cf2db22d8eca Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Wed, 2 Sep 2026 19:58:38 +0200
Subject: [PATCH] swarm-ui: give hive-reported-but-unknown agents their own
 status label
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An agent whose freshness is "unknown" is a distinct case, not a
fallback: it reported into the KV bucket but isn't in the swarm-identity
roster. The label used to just reuse the enum name ("unknown"), which
doesn't tell an operator what to do about it. Give it a label that
names the actual situation ("not in swarm identity") plus a tooltip
spelling out the fix (register/migrate it), so an operator scanning the
roster during a migration can immediately tell which agents still need
work.

No backend change needed — GET /api/agents/status already emits a row
for every hive-reported agent outside the roster (AgentStatusReader,
unit-tested as an_agent_outside_the_roster_is_surfaced_as_unknown), and
the page already renders every row it gets back.
---
 .../swarm-ui/src/pages/AgentsPage.tsx         | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/frontend/packages/swarm-ui/src/pages/AgentsPage.tsx b/frontend/packages/swarm-ui/src/pages/AgentsPage.tsx
index de965942..63128fad 100644
--- a/frontend/packages/swarm-ui/src/pages/AgentsPage.tsx
+++ b/frontend/packages/swarm-ui/src/pages/AgentsPage.tsx
@@ -78,13 +78,21 @@ interface AgentRow {
   wanted: Wanted;
 }
 
-// Same tone/label pairing as HivesPage — one freshness enum shared by both
-// endpoints, so the same rendering rule applies to both pages.
+// Same tone pairing as HivesPage — one freshness enum shared by both
+// endpoints, so the same tone rule applies to both pages — but `unknown`'s
+// label diverges deliberately: an agent outside the swarm-identity roster
+// has a concrete next step (register it), while an unrecognized *hive* on
+// HivesPage doesn't carry the same actionable meaning.
 const FRESHNESS: Record<Freshness, { tone: BadgeTone; label: string }> = {
   fresh: { tone: "positive", label: "fresh" },
   stale: { tone: "warning", label: "stale" },
   never_reported: { tone: "neutral", label: "never reported" },
-  unknown: { tone: "negative", label: "unknown" },
+  // `unknown` means the agent reported into the KV bucket but isn't in
+  // the swarm-identity roster — a real, distinct case ("hive-reported,
+  // not yet in swarm level"), not just a fallback default, so it gets a
+  // label that says what to do about it rather than reusing the enum
+  // name as the label.
+  unknown: { tone: "negative", label: "not in swarm identity" },
 };
 
 // Same 30s default + same reasoning as HivesPage: no inputs on this page
@@ -214,6 +222,11 @@ export function AgentsPage() {
         return (
           <Badge
             tone={tone}
+            title={
+              a.freshness === "unknown"
+                ? "reported by its hive but not registered in swarm-level identity — needs migration"
+                : undefined
+            }
             value={
               <>
                 {text ? `${text} — ` : ""}