fleetd #743: expose herdr pane discovery (tab labels) over REST and MCP

GET /agents now carries each agent's tab label, merged in from the same
herdr daemon(s) the roster is drawn from. fleet_list gains a panes array
with the same label, the sessionId fleet_send takes as a target, the
role the daemon resolves that pane as, and the deliverable gate the
injector itself enforces (Fleetd#deliverableTo, now public). Gated like
leads/collaborators (primary, architect, collaborator), not bare READ,
since a tab label and a member's cwd are not roster facts every READ
caller may see.

fleetd/src/main/java/dev/ltms/fleet/Fleetd.java

@@ -233,8 +233,11 @@ public final class Fleetd {
      *
      * <p>Both sets are read through their supplier on each call rather than snapshotted, so a lead or
      * collaborator discovered by {@code leadScan} after startup becomes deliverable without a restart.
+     *
+     * <p>Public so {@code fleet_list}'s {@code panes} row can report the exact same gate the
+     * injector enforces, rather than a second, separately-derived guess at reachability.
      */
-    static Predicate<String> deliverableTo(MemberPresence presence, Supplier<Map<String, String>> leads,
+    public static Predicate<String> deliverableTo(MemberPresence presence, Supplier<Map<String, String>> leads,
             Supplier<Map<String, String>> collaborators) {
         return target -> presence.isPresent(target) || leads.get().containsKey(target)
                 || collaborators.get().containsKey(target);

fleetd/src/main/java/dev/ltms/fleet/herdr/PaneLocator.java

@@ -4,6 +4,7 @@ import com.fasterxml.jackson.databind.JsonNode;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
@@ -145,6 +146,32 @@ public final class PaneLocator {
         return ancestry;
     }
 
+    /**
+     * Every tab herdr tracks across every searched daemon, keyed by tab id, to its display label —
+     * the pane-discovery surface behind {@code GET /agents} and {@code fleet_list}'s {@code panes}
+     * row. Collapses to one scan in the single-daemon deployment, the same as
+     * {@link #terminalForPid}. A tab herdr reports with no label maps to a {@code null} value here;
+     * a tab with no {@code tab_id} is skipped.
+     */
+    public Map<String, String> tabLabelsByTabId() {
+        Map<String, String> out = new LinkedHashMap<>();
+        for (HerdrClient herdr : herdrs) {
+            for (JsonNode w : herdr.call("workspace.list").path("workspaces")) {
+                String workspaceId = w.path("workspace_id").asText(null);
+                if (workspaceId == null) {
+                    continue;
+                }
+                for (JsonNode t : herdr.call("tab.list", Map.of("workspace_id", workspaceId)).path("tabs")) {
+                    Tab tab = Tab.from(t);
+                    if (tab.tabId() != null) {
+                        out.put(tab.tabId(), tab.label());
+                    }
+                }
+            }
+        }
+        return out;
+    }
+
     /** Whether a pane owns one of the scanned pid's ancestors, or the check of it failed outright. */
     private enum Ownership { OWNS, DOES_NOT_OWN, UNKNOWN }
 

fleetd/src/main/java/dev/ltms/fleet/mcp/FleetMcp.java

@@ -1,5 +1,6 @@
 package dev.ltms.fleet.mcp;
 
+import dev.ltms.fleet.Fleetd;
 import dev.ltms.fleet.auth.AuditLog;
 import dev.ltms.fleet.auth.Authz;
 import dev.ltms.fleet.auth.CallerResolver;
@@ -41,6 +42,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.servlet.http.HttpServlet;
 
 import java.util.ArrayList;
+import java.util.Comparator;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
@@ -52,6 +54,7 @@ import java.util.concurrent.TimeUnit;
 import java.util.function.BiFunction;
 import java.util.function.Function;
 import java.util.function.LongSupplier;
+import java.util.function.Predicate;
 import java.util.function.Supplier;
 import java.util.stream.Collectors;
 
@@ -302,6 +305,21 @@ public final class FleetMcp {
         public static LeadConfigDirSource none() { return new LeadConfigDirSource(_ -> null, _ -> null); }
     }
 
+    /**
+     * Pane-discovery facts for {@code fleet_list}'s {@code panes} row — every herdr tab's display
+     * label, and the one deliverability gate the status-gated injector itself reads.
+     *
+     * @param tabLabels    tab id → its display label, read lazily (only once the row is actually
+     *                     assembled) since it costs a herdr {@code workspace.list}/{@code tab.list}
+     *                     scan; a tab herdr reports with no label maps to a {@code null} value
+     * @param deliverable  the same gate {@link dev.ltms.fleet.Fleetd#deliverableTo} builds for the
+     *                     injector, keyed by terminal id — never a second, separately-derived check
+     */
+    public record PaneSource(Supplier<Map<String, String>> tabLabels, Predicate<String> deliverable) {
+        /** Inert source — no labels, and every target reports non-deliverable. */
+        public static PaneSource none() { return new PaneSource(Map::of, _ -> false); }
+    }
+
     /**
      * fleetd #361: peer-visibility facts for {@code fleet_list}'s {@code coordinator} row — this
      * daemon's own {@link LeadChannel} (for its self mailbox state and held messages) plus the
@@ -564,13 +582,21 @@ public final class FleetMcp {
                 (exchange, _) -> {
                     McpSchema.CallToolResult denied = deny(exchange, toolAction("fleet_list", Map.of()), null);
                     if (denied != null) return denied;
+                    // The label lookup costs a herdr scan, so it is only a Supplier here —
+                    // listFleet reads it (inside its own HerdrException handling) only once
+                    // panesVisibleTo has already said this caller receives the row at all. The
+                    // deliverable predicate is the exact gate the injector enforces, never a second,
+                    // separately-derived guess (see Fleetd#deliverableTo's own javadoc).
+                    PaneSource panes = new PaneSource(() -> identity.panes().tabLabelsByTabId(),
+                            Fleetd.deliverableTo(presence, callers::leads, callers::collaborators));
                     return listFleet(workers, sessions, messages, capacity, healthCoverage, loopHealth, quarantine, outage,
                             leadSeats, leadContextGauge, leadConfigDirs, callers.leads(),
                             callerTerminal(exchange),
                             callers.collaborators(), collaboratorsVisibleTo(principal(exchange)),
                             new CoordinationSource(leadChannel, peers),
                             coordinatorVisibleTo(principal(exchange)),
-                            leadsVisibleTo(principal(exchange)), membersVisibleTo(principal(exchange)));
+                            leadsVisibleTo(principal(exchange)), membersVisibleTo(principal(exchange)),
+                            panes, panesVisibleTo(principal(exchange)));
                 };
         BiFunction<McpSyncServerExchange, McpSchema.CallToolRequest, McpSchema.CallToolResult> stopHandler =
                 (exchange, req) -> {
@@ -795,6 +821,22 @@ public final class FleetMcp {
         return caller.isPrimary() || caller.isArchitect();
     }
 
+    /**
+     * Who may see {@code fleet_list}'s {@code panes} array — every herdr-tracked agent pane on the
+     * host, labelled and addressable by {@code sessionId}, including a hand-opened tab this daemon
+     * never spawned and never configured as a lead or collaborator. {@code READ}'s own grant rests
+     * on "the roster carries no secrets" ({@code Authz.java}'s comment on its {@code READ} case) —
+     * a tab label and a member's cwd are not that, so this array gets the same narrower gate as
+     * {@link #leadsVisibleTo}/{@link #collaboratorsVisibleTo} rather than riding bare {@code READ}:
+     * exactly the roles that may {@link Authz.Action#SEND} to a named peer. A plain worker or an
+     * unconfigured observer pane can never {@code SEND} at all, so listing every other pane's label
+     * and working directory to one would expose host shape with no use to that caller — the same
+     * reasoning already applied to {@code collaborators}.
+     */
+    static boolean panesVisibleTo(Principal caller) {
+        return caller.isPrimary() || caller.isArchitect() || caller.isCollaborator();
+    }
+
     /**
      * The terminal of the caller on this call's connection, or {@code null} when that caller carries
      * no terminal, which is only the unnamed primary. A named lead, an architect and a worker each
@@ -1966,6 +2008,27 @@ public final class FleetMcp {
                 Map.of(), false, coordination, callerIsPrimary, leadsVisible, membersVisible);
     }
 
+    /**
+     * As below, with no pane discovery — every wrapper overload above delegates here, so
+     * {@code panes} is omitted and {@code panesVisible} is {@code false}. A test that wants the
+     * {@code panes} row must call the canonical overload below with an explicit {@link PaneSource}
+     * and {@code panesVisible}.
+     */
+    static McpSchema.CallToolResult listFleet(PeerLauncher workers, SessionManager sessions, MessageService messages,
+                                                 CapacitySource capacity, HealthCoverageSource healthCoverage,
+                                                 LoopHealthSource loopHealth,
+                                                QuarantineSource quarantine, OutageSource outage,
+                                               LeadSeatSource leadSeats, LeadContextGauge contextGauge,
+                                               LeadConfigDirSource leadConfigDirs,
+                                               Map<String, String> leads, String selfTerm,
+                                               Map<String, String> collaborators, boolean collaboratorsVisible,
+                                               CoordinationSource coordination, boolean callerIsPrimary,
+                                               boolean leadsVisible, boolean membersVisible) {
+        return listFleet(workers, sessions, messages, capacity, healthCoverage, loopHealth, quarantine, outage,
+                leadSeats, contextGauge, leadConfigDirs, leads, selfTerm, collaborators, collaboratorsVisible,
+                coordination, callerIsPrimary, leadsVisible, membersVisible, PaneSource.none(), false);
+    }
+
     /**
      * The canonical implementation. {@code contextGauge} is the "lead context gauge" (see
      * {@link LeadContextGauge}) — every wrapper overload above passes a freshly constructed one,
@@ -1984,6 +2047,13 @@ public final class FleetMcp {
      *                             {@link #leadsVisibleTo})
      * @param membersVisible       whether this caller may see the {@code members} array (see
      *                             {@link #membersVisibleTo})
+     * @param panes                pane-discovery facts — labels and the deliverable gate for the
+     *                             {@code panes} row; {@link PaneSource#none()} for a caller that
+     *                             does not want the row
+     * @param panesVisible         whether this caller may see the {@code panes} array (see
+     *                             {@link #panesVisibleTo}); every wrapper overload above passes
+     *                             {@code false}, so a test that wants the row must call this overload
+     *                             with an explicit {@code true}
      */
     static McpSchema.CallToolResult listFleet(PeerLauncher workers, SessionManager sessions, MessageService messages,
                                                  CapacitySource capacity, HealthCoverageSource healthCoverage,
@@ -1994,11 +2064,12 @@ public final class FleetMcp {
                                                Map<String, String> leads, String selfTerm,
                                                Map<String, String> collaborators, boolean collaboratorsVisible,
                                                CoordinationSource coordination, boolean callerIsPrimary,
-                                               boolean leadsVisible, boolean membersVisible) {
+                                               boolean leadsVisible, boolean membersVisible,
+                                               PaneSource panes, boolean panesVisible) {
         try {
             // Neither row's assembly (leadView/memberCapacityView probing herdr for live status)
             // runs unless at least one of them needs the live-agent lookup backing it.
-            Map<String, Agent> live = (leadsVisible || membersVisible)
+            Map<String, Agent> live = (leadsVisible || membersVisible || panesVisible)
                     ? workers.list().stream()
                             .map(Agent.class::cast)
                             .filter(a -> a.terminalId() != null)
@@ -2042,6 +2113,12 @@ public final class FleetMcp {
                         .map(e -> collaboratorRow(e.getKey(), e.getValue()))
                         .toList());
             }
+            // A pane's label and a member's cwd are not roster facts every READ-gated caller may
+            // see (see panesVisibleTo) -- gate BEFORE assembling the row, same reason as every
+            // other array above.
+            if (panesVisible) {
+                result.put("panes", paneRows(live, roster, leads, collaborators, panes));
+            }
             // fleetd #439: coordinator/coordinatorView is lead-to-lead coordination state and must
             // never reach a worker or an architect -- gate BEFORE assembling it, not after, so the
             // key is absent rather than present-and-empty.
@@ -2367,6 +2444,67 @@ public final class FleetMcp {
         return m;
     }
 
+    /**
+     * One row per herdr-tracked agent pane, sorted by terminal id for a stable order. {@code live}
+     * is the same terminal-keyed {@link Agent} map {@code leadView}/{@code memberCapacityView}
+     * already read, so a pane neither configured as a lead nor spawned as a member — a hand-opened
+     * tab — still gets a row here.
+     */
+    private static List<Map<String, Object>> paneRows(Map<String, Agent> live, List<MemberSession> roster,
+            Map<String, String> leads, Map<String, String> collaborators, PaneSource panes) {
+        Map<String, String> tabLabels = panes.tabLabels().get();
+        Map<String, MemberSession> byTerminal = roster.stream()
+                .filter(s -> s.terminalId() != null)
+                .collect(Collectors.toMap(MemberSession::terminalId, Function.identity(), (_, b) -> b));
+        return live.values().stream()
+                .sorted(Comparator.comparing(Agent::terminalId))
+                .map(a -> paneRow(a, byTerminal.get(a.terminalId()), leads, collaborators, tabLabels, panes))
+                .toList();
+    }
+
+    /**
+     * @param session the roster entry for this pane's terminal, or {@code null} for a pane the
+     *                 daemon never spawned as a member (a hand-opened tab, or a configured lead)
+     * @param tabLabels tab id → its herdr display label; a tab absent here, or carrying a
+     *                   {@code null} label itself, projects as a {@code null} "label"
+     */
+    private static Map<String, Object> paneRow(Agent a, MemberSession session, Map<String, String> leads,
+            Map<String, String> collaborators, Map<String, String> tabLabels, PaneSource panes) {
+        Map<String, Object> m = new LinkedHashMap<>();
+        m.put("sessionId", a.terminalId());
+        m.put("paneId", a.paneId());
+        m.put("workspaceId", a.workspaceId());
+        m.put("tabId", a.tabId());
+        m.put("label", a.tabId() == null ? null : tabLabels.get(a.tabId()));
+        m.put("agentType", a.agentType());
+        m.put("status", a.status() == null ? "unknown" : a.status().name().toLowerCase());
+        m.put("role", paneRole(a.terminalId(), session, leads, collaborators));
+        m.put("deliverable", panes.deliverable().test(a.terminalId()));
+        if (session != null && session.cwd() != null) {
+            m.put("cwd", session.cwd());
+        }
+        return m;
+    }
+
+    /**
+     * The role this pane resolves as: a spawned member's own {@link MemberRole}, else "lead" or
+     * "collaborator" for a configured but currently-unoccupied slot, else "observer" for a pane
+     * this daemon neither spawned nor configured.
+     */
+    private static String paneRole(String terminal, MemberSession session, Map<String, String> leads,
+            Map<String, String> collaborators) {
+        if (session != null) {
+            return session.role().wireName();
+        }
+        if (leads.containsKey(terminal)) {
+            return "lead";
+        }
+        if (collaborators.containsKey(terminal)) {
+            return "collaborator";
+        }
+        return "observer";
+    }
+
     /**
      * Reads the lead context gauge for one lead. {@code configDir} is this lead's configured
      * {@code CLAUDE_CONFIG_DIR} override (see {@link LeadConfigDirSource}), derived from

fleetd/src/main/java/dev/ltms/fleet/rest/FleetApp.java

@@ -13,6 +13,7 @@ import dev.ltms.fleet.mcp.FleetMcp;
 import dev.ltms.fleet.herdr.Agent;
 import dev.ltms.fleet.herdr.HerdrClient;
 import dev.ltms.fleet.herdr.HerdrException;
+import dev.ltms.fleet.herdr.PaneLocator;
 import dev.ltms.fleet.inject.MemberPresence;
 import dev.ltms.fleet.member.MemberCredentialPolicyView;
 import dev.ltms.fleet.peer.PeerUnreachableException;
@@ -442,8 +443,12 @@ public final class FleetApp {
             return;
         }
         try {
+            // A tab's label is the only human-usable address for a pane this daemon never spawned
+            // (a hand-opened observer tab); agent.list carries no label of its own, so it is merged
+            // in from the same herdr daemon(s) the agent roster itself is drawn from.
+            Map<String, String> tabLabels = new PaneLocator(herdr, memberHerdr).tabLabelsByTabId();
             ctx.status(200).json(Map.of("agents",
-                    workers.list().stream().map(Agent.class::cast).map(FleetApp::view).toList()));
+                    workers.list().stream().map(Agent.class::cast).map(a -> view(a, tabLabels)).toList()));
         } catch (HerdrException e) {
             // fleetd #297: workers.list() reaches herdr — a transport failure must land in the same
             // {error, detail} envelope every other failure path here uses, not escape as a bare
@@ -935,13 +940,19 @@ public final class FleetApp {
         }
     }
 
-    /** Stable JSON projection of an agent (null-safe for the start-time shape). */
-    private static Map<String, Object> view(Agent a) {
+    /**
+     * Stable JSON projection of an agent (null-safe for the start-time shape).
+     *
+     * @param tabLabels tab id → its herdr display label; a tab absent from this map, or carrying
+     *                   a {@code null} label itself, projects as a {@code null} "label"
+     */
+    private static Map<String, Object> view(Agent a, Map<String, String> tabLabels) {
         Map<String, Object> m = new LinkedHashMap<>();
         m.put("terminalId", a.terminalId());
         m.put("paneId", a.paneId());
         m.put("workspaceId", a.workspaceId());
         m.put("tabId", a.tabId());
+        m.put("label", tabLabels.get(a.tabId()));
         m.put("sessionId", a.sessionId());
         m.put("agentType", a.agentType());
         m.put("status", a.status().name().toLowerCase());

fleetd/src/test/java/dev/ltms/fleet/mcp/FleetMcpAuthzTest.java

@@ -453,6 +453,26 @@ class FleetMcpAuthzTest {
         assertFalse(FleetMcp.membersVisibleTo(ANON), "authenticated as nothing must not see it either");
     }
 
+    // --- who may see fleet_list's panes array ----------------------------------------------------
+
+    /**
+     * {@link FleetMcp#panesVisibleTo} is the whole policy decision for {@code fleet_list}'s
+     * {@code panes} array: visible to exactly the roles that may {@code SEND} to a named peer --
+     * the primary, an architect, and a collaborator -- never a worker, never an unconfigured
+     * observer pane, and never an anonymous caller.
+     */
+    @Test
+    void onlyPrimaryArchitectAndCollaboratorMaySeeThePanesArray() {
+        assertTrue(FleetMcp.panesVisibleTo(PRIMARY), "the primary must see the panes array");
+        assertTrue(FleetMcp.panesVisibleTo(ARCH_DESIGN), "an architect must see the panes array");
+        assertTrue(FleetMcp.panesVisibleTo(COLLABORATOR), "a collaborator must see its own peer roster");
+        assertFalse(FleetMcp.panesVisibleTo(WORKER_A),
+                "a worker holds READ but can never SEND, so it must not see the panes array");
+        assertFalse(FleetMcp.panesVisibleTo(Principal.observer("term_obs", 700)),
+                "an unconfigured observer pane must not see every other pane's label and cwd");
+        assertFalse(FleetMcp.panesVisibleTo(ANON), "authenticated as nothing must not see it either");
+    }
+
     /**
      * Same reasoning as {@link #theFleetListHandlerActuallyConsultsCoordinatorVisibleTo}: the
      * predicate above can be perfectly correct while the one production call site never asks it.

fleetd/src/test/java/dev/ltms/fleet/mcp/FleetMcpTest.java

@@ -1,5 +1,6 @@
 package dev.ltms.fleet.mcp;
 
+import dev.ltms.fleet.Fleetd;
 import dev.ltms.fleet.auth.CallerResolver;
 import dev.ltms.fleet.auth.MemberRegistry;
 import dev.ltms.fleet.auth.Principal;
@@ -1110,6 +1111,74 @@ class FleetMcpTest {
         assertTrue(asArchitect.contains("\"sessionId\":\"term_collab\""), asArchitect);
     }
 
+    // --- fleet_list's panes array -----------------------------------------------------------------
+
+    /** Calls the canonical {@code listFleet} overload directly, so a test can set the pane-discovery
+     * payload and its visibility independently of a real {@code Principal} / MCP exchange. */
+    private static McpSchema.CallToolResult listFleetWithPanes(FakeHerdr h, FleetMcp.PaneSource panes,
+            boolean panesVisible) {
+        SessionManager sessions = new SessionManager(workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")));
+        return FleetMcp.listFleet(
+                workerService(h, "http://gx00.gw:8000", Set.of("gx00.gw")), sessions, null,
+                FleetMcp.CapacitySource.none(), new FleetMcp.HealthCoverageSource(() -> "off"),
+                FleetMcp.LoopHealthSource.none(), FleetMcp.QuarantineSource.none(), FleetMcp.OutageSource.none(),
+                FleetMcp.LeadSeatSource.none(), new LeadContextGauge(), FleetMcp.LeadConfigDirSource.none(),
+                Map.of(), "", Map.of(), false,
+                FleetMcp.CoordinationSource.none(), false, true, true, panes, panesVisible);
+    }
+
+    /**
+     * A pane whose tab herdr reports with a label gets that label and the exact terminal id
+     * {@code fleet_send} takes as a target, carried as {@code sessionId}.
+     */
+    @Test
+    void listReportsAPaneRowWithItsTabLabelAndSendableSessionId() {
+        FakeHerdr h = new FakeHerdr().withTab("w2", "w2:t7", "trinotes");
+        MemberPresence presence = new MemberPresence();
+        presence.markPresent("term_a");
+        FleetMcp.PaneSource panes = new FleetMcp.PaneSource(
+                () -> new PaneLocator(h).tabLabelsByTabId(),
+                Fleetd.deliverableTo(presence, Map::of, Map::of));
+
+        String out = textOf(listFleetWithPanes(h, panes, true));
+
+        assertTrue(out.contains("\"panes\":["), out);
+        assertTrue(out.contains("\"sessionId\":\"term_a\""), out);
+        assertTrue(out.contains("\"label\":\"trinotes\""), out);
+        assertTrue(out.contains("\"deliverable\":true"), out);
+    }
+
+    /**
+     * A pane whose tab carries no label known to herdr still gets a row -- a missing label must
+     * never throw, and must never drop the pane from the array, only report a {@code null} label.
+     * Pairs with a {@code deliverable} false reading when the target is neither present, a lead,
+     * nor a collaborator.
+     */
+    @Test
+    void listReportsAPaneRowWithANullLabelWhenHerdrHasNoneAndNotDeliverable() {
+        FakeHerdr h = new FakeHerdr();
+        FleetMcp.PaneSource panes = new FleetMcp.PaneSource(
+                () -> new PaneLocator(h).tabLabelsByTabId(),
+                Fleetd.deliverableTo(new MemberPresence(), Map::of, Map::of));
+
+        String out = textOf(listFleetWithPanes(h, panes, true));
+
+        assertTrue(out.contains("\"panes\":["), out);
+        assertTrue(out.contains("\"sessionId\":\"term_a\""), out);
+        assertTrue(out.contains("\"label\":null"), out);
+        assertTrue(out.contains("\"deliverable\":false"), out);
+    }
+
+    /** A caller this role may not show the array to gets no {@code panes} key at all. */
+    @Test
+    void listOmitsThePanesArrayWhenTheCallerMayNotSeeIt() {
+        FakeHerdr h = new FakeHerdr();
+
+        String out = textOf(listFleetWithPanes(h, FleetMcp.PaneSource.none(), false));
+
+        assertFalse(out.contains("\"panes\""), out);
+    }
+
     /**
      * fleetd #421: {@code mailbox.pending} counts only broker-ready messages, so a blocked lead's
      * normal, healthy state is {@code "pending": 0} next to a non-empty {@code held[]} — which