@stigmer/react 3.12.4 → 3.12.6

package/src/conversation/__tests__/ConversationTemplatePickerDialog.test.tsx

@@ -0,0 +1,224 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  ChannelSendOutcome,
+  SendChannelMessageOutputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { ConversationTemplatePickerDialog } from "../ConversationTemplatePickerDialog";
+
+function makeTemplate(overrides?: Partial<Record<string, unknown>>) {
+  return {
+    name: "fee_reminder",
+    language: "en_US",
+    category: "UTILITY",
+    status: "APPROVED",
+    parameterFormat: "POSITIONAL",
+    parameterNames: ["1", "2"],
+    bodyText: "Hi {{1}}, your fee of {{2}} is due.",
+    headerFormat: "",
+    rejectionReason: "",
+    unsupportedReason: "",
+    ...overrides,
+  };
+}
+
+function output(outcome: ChannelSendOutcome, detail = "") {
+  return create(SendChannelMessageOutputSchema, {
+    outcome,
+    outboundMessageId: outcome === ChannelSendOutcome.refused ? "" : "obm_1",
+    detail,
+  });
+}
+
+function renderPicker(options?: {
+  templates?: unknown[];
+  onSend?: ReturnType<typeof vi.fn>;
+  onOpenChange?: ReturnType<typeof vi.fn>;
+  isSending?: boolean;
+}) {
+  const listTemplates = vi
+    .fn()
+    .mockResolvedValue({ entries: options?.templates ?? [makeTemplate()] });
+  const onSend =
+    options?.onSend ?? vi.fn().mockResolvedValue(output(ChannelSendOutcome.accepted));
+  const client = { agentChannel: { listTemplates } } as never;
+  function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  }
+  const view = render(
+    <ConversationTemplatePickerDialog
+      open
+      onOpenChange={options?.onOpenChange ?? vi.fn()}
+      channelSlug="wa-main"
+      org="acme"
+      onSend={onSend}
+      isSending={options?.isSending ?? false}
+      modal={false}
+    />,
+    { wrapper: Wrapper },
+  );
+  return { view, listTemplates, onSend };
+}
+
+describe("ConversationTemplatePickerDialog", () => {
+  afterEach(() => cleanup());
+
+  it("lists approved templates and asks the wire for approved only", async () => {
+    const { listTemplates } = renderPicker();
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    expect(listTemplates).toHaveBeenCalledWith(
+      expect.objectContaining({ channel: "wa-main", org: "acme", approvedOnly: true }),
+    );
+  });
+
+  it("marks unsupported and image-header templates unsendable, with the reason", async () => {
+    renderPicker({
+      templates: [
+        makeTemplate({
+          name: "flow_template",
+          unsupportedReason: "FLOW buttons are not supported",
+        }),
+        makeTemplate({ name: "hero_image", headerFormat: "IMAGE" }),
+        makeTemplate(),
+      ],
+    });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    const unsupported = screen
+      .getByText("flow_template")
+      .closest("button") as HTMLButtonElement;
+    expect(unsupported.disabled).toBe(true);
+    expect(screen.getByText(/FLOW buttons are not supported/)).toBeDefined();
+
+    // The v1 scope cut (cloud#260): the send payload's image link has no
+    // console-side source yet, so the template shows but cannot be picked.
+    const imageHeader = screen
+      .getByText("hero_image")
+      .closest("button") as HTMLButtonElement;
+    expect(imageHeader.disabled).toBe(true);
+    expect(screen.getByText(/image header needs a hosted image/)).toBeDefined();
+
+    const sendable = screen
+      .getByText("fee_reminder")
+      .closest("button") as HTMLButtonElement;
+    expect(sendable.disabled).toBe(false);
+  });
+
+  it("phrases an empty registry answer as none FOUND, never none exist", async () => {
+    renderPicker({ templates: [] });
+    await waitFor(() =>
+      expect(screen.getByText("No approved templates found")).toBeDefined(),
+    );
+  });
+
+  it("fills variables with a live preview and only then enables Send", async () => {
+    const user = userEvent.setup();
+    renderPicker();
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+
+    const send = screen.getByRole("button", { name: "Send template" }) as HTMLButtonElement;
+    expect(send.disabled).toBe(true);
+
+    await user.type(screen.getByLabelText("1"), "Noor");
+    await user.type(screen.getByLabelText("2"), "$40");
+
+    // The preview substitutes the filled values into the verbatim body —
+    // the exact message the customer receives. Segments render as
+    // separate spans, so assert on the whole paragraph.
+    const preview = screen.getByText("Preview").nextElementSibling;
+    expect(preview?.textContent).toBe("Hi Noor, your fee of $40 is due.");
+    expect(send.disabled).toBe(false);
+  });
+
+  it("sends the chosen entry's name, language, and trimmed parameters, and closes on accepted", async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    const { onSend } = renderPicker({ onOpenChange });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+    await user.type(screen.getByLabelText("1"), " Noor ");
+    await user.type(screen.getByLabelText("2"), "$40");
+    await user.click(screen.getByRole("button", { name: "Send template" }));
+
+    await waitFor(() =>
+      expect(onSend).toHaveBeenCalledWith({
+        kind: "template",
+        name: "fee_reminder",
+        language: "en_US",
+        parameters: { "1": "Noor", "2": "$40" },
+      }),
+    );
+    await waitFor(() => expect(onOpenChange).toHaveBeenCalledWith(false));
+  });
+
+  it("keeps the dialog open with every value intact and shows the detail verbatim on refusal", async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    const onSend = vi
+      .fn()
+      .mockResolvedValue(
+        output(ChannelSendOutcome.refused, "template 'fee_reminder' is PAUSED on WhatsApp"),
+      );
+    renderPicker({ onSend, onOpenChange });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+    await user.type(screen.getByLabelText("1"), "Noor");
+    await user.type(screen.getByLabelText("2"), "$40");
+    await user.click(screen.getByRole("button", { name: "Send template" }));
+
+    await waitFor(() =>
+      expect(
+        screen.getByText("template 'fee_reminder' is PAUSED on WhatsApp"),
+      ).toBeDefined(),
+    );
+    // The words never left; the correction the detail asks for starts
+    // from the values already filled (the composer's draft contract).
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    expect((screen.getByLabelText("1") as HTMLInputElement).value).toBe("Noor");
+    expect((screen.getByLabelText("2") as HTMLInputElement).value).toBe("$40");
+  });
+
+  it("keeps the dialog open and renders a thrown failure", async () => {
+    const user = userEvent.setup();
+    const onSend = vi.fn().mockRejectedValue(new Error("transport exploded"));
+    renderPicker({ onSend });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+    await user.type(screen.getByLabelText("1"), "Noor");
+    await user.type(screen.getByLabelText("2"), "$40");
+    await user.click(screen.getByRole("button", { name: "Send template" }));
+
+    await waitFor(() => expect(screen.getByText(/transport exploded/)).toBeDefined());
+    expect((screen.getByLabelText("1") as HTMLInputElement).value).toBe("Noor");
+  });
+
+  it("navigates back to the list, discarding the selection", async () => {
+    const user = userEvent.setup();
+    renderPicker({
+      templates: [makeTemplate(), makeTemplate({ name: "order_update" })],
+    });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+    expect(screen.getByRole("button", { name: "Send template" })).toBeDefined();
+
+    await user.click(screen.getByRole("button", { name: "Back to the template list" }));
+    expect(screen.getByText("order_update")).toBeDefined();
+    expect(screen.queryByRole("button", { name: "Send template" })).toBeNull();
+  });
+});

package/src/conversation/__tests__/useConversationParticipation.test.tsx

@@ -100,7 +100,9 @@ describe("useConversationParticipation", () => {
       { wrapper: wrapper(client) },
     );
 
-    const output = await act(() => result.current.reply("on my way"));
+    const output = await act(() =>
+      result.current.reply({ kind: "text", body: "on my way" }),
+    );
 
     expect(output.outboundMessageId).toBe("obm_1");
     const agentChannel = (client as { agentChannel: Record<string, ReturnType<typeof vi.fn>> })
@@ -109,7 +111,10 @@ describe("useConversationParticipation", () => {
       expect.objectContaining({
         ...IDENTITY,
         payload: expect.objectContaining({
-          kind: expect.objectContaining({ case: "text" }),
+          kind: expect.objectContaining({
+            case: "text",
+            value: expect.objectContaining({ body: "on my way" }),
+          }),
         }),
       }),
     );
@@ -121,6 +126,40 @@ describe("useConversationParticipation", () => {
     );
   });
 
+  it("reply sends the template lane through the same command — name, language, and parameters verbatim", async () => {
+    const client = createMockStigmer();
+    const { result } = renderHook(() => useConversationParticipation(IDENTITY), {
+      wrapper: wrapper(client),
+    });
+
+    await act(() =>
+      result.current.reply({
+        kind: "template",
+        name: "order_update",
+        language: "en_US",
+        parameters: { "1": "Noor", "2": "tomorrow" },
+      }),
+    );
+
+    const agentChannel = (client as { agentChannel: Record<string, ReturnType<typeof vi.fn>> })
+      .agentChannel;
+    expect(agentChannel.reply).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ...IDENTITY,
+        payload: expect.objectContaining({
+          kind: expect.objectContaining({
+            case: "template",
+            value: expect.objectContaining({
+              name: "order_update",
+              language: "en_US",
+              parameters: { "1": "Noor", "2": "tomorrow" },
+            }),
+          }),
+        }),
+      }),
+    );
+  });
+
   it("still resolves the reply when the follow-up row read fails — the send outcome is the answer", async () => {
     const client = createMockStigmer({
       getConversation: vi.fn().mockRejectedValue(new Error("blip")),
@@ -131,7 +170,9 @@ describe("useConversationParticipation", () => {
       { wrapper: wrapper(client) },
     );
 
-    const output = await act(() => result.current.reply("on my way"));
+    const output = await act(() =>
+      result.current.reply({ kind: "text", body: "on my way" }),
+    );
 
     expect(output.outboundMessageId).toBe("obm_1");
     expect(onConversation).not.toHaveBeenCalled();
@@ -144,7 +185,7 @@ describe("useConversationParticipation", () => {
       wrapper: wrapper(client),
     });
 
-    await act(() => result.current.reply("on my way"));
+    await act(() => result.current.reply({ kind: "text", body: "on my way" }));
 
     const agentChannel = (client as { agentChannel: Record<string, ReturnType<typeof vi.fn>> })
       .agentChannel;

package/src/conversation/index.ts

@@ -22,6 +22,9 @@ export type { ConversationAttentionBannerProps } from "./ConversationAttentionBa
 export { ConversationComposer } from "./ConversationComposer.js";
 export type { ConversationComposerProps } from "./ConversationComposer.js";
 
+export { ConversationTemplatePickerDialog } from "./ConversationTemplatePickerDialog.js";
+export type { ConversationTemplatePickerDialogProps } from "./ConversationTemplatePickerDialog.js";
+
 export { useConversation } from "./useConversation.js";
 export type {
   UseConversationOptions,
@@ -49,6 +52,7 @@ export type {
 export { useConversationParticipation } from "./useConversationParticipation.js";
 export type {
   ConversationCommand,
+  ConversationReplyPayload,
   UseConversationParticipationOptions,
   UseConversationParticipationReturn,
 } from "./useConversationParticipation.js";

package/src/conversation/useConversationParticipation.ts

@@ -17,6 +17,43 @@ import { useKeyedSubmission } from "../internal/useKeyedSubmission.js";
 /** The four staff-facing participation commands. */
 export type ConversationCommand = "reply" | "takeOver" | "handBack" | "clearAttention";
 
+/**
+ * A staff reply's payload — the client-side face of the wire's
+ * `ChannelOutboundPayload` oneof. Reply is ONE command with two lanes,
+ * never two commands: both lanes share the implicit takeover, the
+ * `"reply"` pending key, and the outcome contract.
+ *
+ * - `text` — free-form; requires an open 24-hour customer-service
+ *   window on providers that enforce one (WhatsApp).
+ * - `template` — a provider-approved message template, the only lane
+ *   for a closed window. `language` is always required here (the wire
+ *   allows omitting it for single-language names, but a caller that
+ *   picked a template knows its language — sending it structurally
+ *   avoids the ambiguity refusal). Image-header templates are not yet
+ *   sendable from the SDK: the wire's `header_image_link` needs a
+ *   public HTTPS asset no console surface can supply today.
+ */
+export type ConversationReplyPayload =
+  | {
+      readonly kind: "text";
+      /** The message body, as the customer will receive it. */
+      readonly body: string;
+    }
+  | {
+      readonly kind: "template";
+      /** Template name on the channel provider's registry. */
+      readonly name: string;
+      /** Template language code (e.g. `"en"`, `"en_US"`). */
+      readonly language: string;
+      /**
+       * Variable values: keyed by parameter name for NAMED templates,
+       * by position (`"1"`, `"2"`, …) for POSITIONAL ones — exactly the
+       * template's declared parameters, no more, no fewer (the server's
+       * pre-check refuses mismatches with a corrective detail).
+       */
+      readonly parameters: Readonly<Record<string, string>>;
+    };
+
 /** Options for {@link useConversationParticipation}. */
 export interface UseConversationParticipationOptions {
   /** AgentChannel the conversation belongs to. */
@@ -37,13 +74,16 @@ export interface UseConversationParticipationOptions {
 /** Return value of {@link useConversationParticipation}. */
 export interface UseConversationParticipationReturn {
   /**
-   * Send a staff text reply. Resolves with the truthful outcome of the
-   * inline attempt: `accepted` (with `outboundMessageId` — the item will
-   * appear on the timeline as `ob:<that id>`), `queued`, or `refused`.
+   * Send a staff reply — text or template (see
+   * {@link ConversationReplyPayload}). Resolves with the truthful
+   * outcome of the inline attempt: `accepted` (with
+   * `outboundMessageId` — the item will appear on the timeline as
+   * `ob:<that id>`), `queued`, or `refused` (template pre-check
+   * refusals land here too, with the server's corrective detail).
    * A `refused` outcome WITHOUT an `outboundMessageId` left no ledger
    * row and no timeline item will ever exist for it.
    */
-  readonly reply: (text: string) => Promise<SendChannelMessageOutput>;
+  readonly reply: (payload: ConversationReplyPayload) => Promise<SendChannelMessageOutput>;
   /**
    * Take the conversation over: the agent goes quiet until handBack.
    * Resolves with the fresh row — for the LOSER of a concurrent
@@ -120,13 +160,25 @@ export function useConversationParticipation(
   );
 
   const reply = useCallback(
-    (text: string) =>
+    (payload: ConversationReplyPayload) =>
       run("reply", async () => {
         const output = await stigmer.agentChannel.reply(
           create(ReplyToConversationInputSchema, {
             agentChannelId,
             conversationKey,
-            payload: { kind: { case: "text", value: { body: text } } },
+            payload: {
+              kind:
+                payload.kind === "text"
+                  ? { case: "text", value: { body: payload.body } }
+                  : {
+                      case: "template",
+                      value: {
+                        name: payload.name,
+                        language: payload.language,
+                        parameters: { ...payload.parameters },
+                      },
+                    },
+            },
           }),
         );
         // The implicit takeover flipped control BEFORE the send ran —

package/src/cursor-accounts/CursorAccountsConsole.tsx

@@ -10,7 +10,7 @@ import { Button } from "../button/index.js";
 import { StateBadge } from "./badges.js";
 import { CursorAccountEditor } from "./CursorAccountEditor.js";
 import { CursorAccountsAccessNotice } from "./CursorAccountsAccessNotice.js";
-import { deriveCoverage } from "./cursor-account-coverage.js";
+import { deriveCoverage, derivePoolHealth } from "./cursor-account-coverage.js";
 import { formatSyncTime } from "./cursor-account-format.js";
 import { MemberKeysPanel } from "./MemberKeysPanel.js";
 import { useCursorAccounts } from "./useCursorAccounts.js";
@@ -119,11 +119,38 @@ export function CursorAccountsConsole({ className }: CursorAccountsConsoleProps)
   }
 
   const accounts = list.accounts?.accounts ?? [];
+  const health = derivePoolHealth(accounts);
 
   return (
     <div className={cn("stg:space-y-3", className)}>
       <div className="stg:flex stg:items-center stg:justify-between stg:gap-3">
-        <h3 className="stg:text-sm stg:font-semibold stg:text-foreground">Cursor accounts</h3>
+        <div>
+          <h3 className="stg:text-sm stg:font-semibold stg:text-foreground">Cursor accounts</h3>
+          {/* Fleet health in one line (server-computed routability): the
+              2026-08-15 drain hid behind per-account enabled counts — this
+              is the fact the operator needed on THIS screen. */}
+          {accounts.length > 0 && (
+            <p
+              className={cn(
+                "stg:text-[11px]",
+                health.totalRoutableKeys === 0
+                  ? "stg:text-destructive"
+                  : "stg:text-muted-foreground",
+              )}
+              role={health.totalRoutableKeys === 0 ? "alert" : undefined}
+            >
+              {health.totalRoutableKeys === 0
+                ? "No routable execution key anywhere - executions on API-pool models are failing"
+                : `${health.totalRoutableKeys} routable ${health.totalRoutableKeys === 1 ? "key" : "keys"} across ${health.totalAccounts} ${health.totalAccounts === 1 ? "account" : "accounts"}`}
+              {health.drainedAccounts > 0
+                ? ` · ${health.drainedAccounts} ${health.drainedAccounts === 1 ? "account" : "accounts"} drained`
+                : ""}
+              {health.guardTrippedKeys > 0
+                ? ` · ${health.guardTrippedKeys} ${health.guardTrippedKeys === 1 ? "key" : "keys"} usage-drained`
+                : ""}
+            </p>
+          )}
+        </div>
         <Button size="sm" onClick={() => setFlow({ phase: "create" })}>
           Add account
         </Button>
@@ -137,7 +164,7 @@ export function CursorAccountsConsole({ className }: CursorAccountsConsoleProps)
           <span>Account</span>
           <span>Orgs</span>
           <span>Status</span>
-          <span>Execution keys</span>
+          <span>Routable keys</span>
           <span className="stg:text-right">Last synced</span>
         </div>
         {accounts.length === 0 ? (
@@ -214,8 +241,16 @@ function AccountRow({
           />
         </span>
         <span>
-          {summary.enabledKeyCount > 0 ? (
-            <span className="stg:text-muted-foreground">{summary.enabledKeyCount}</span>
+          {/* Routability, not enabled-ness: what key selection would DO.
+              "Drained" (usage guard) is recoverable at the cycle reset;
+              "Not routable" (no enabled key, or owners removed) needs
+              operator action. */}
+          {summary.routableKeyCount > 0 ? (
+            <span className="stg:text-muted-foreground">
+              {summary.routableKeyCount} of {summary.enabledKeyCount}
+            </span>
+          ) : summary.guardTrippedKeyCount > 0 ? (
+            <StateBadge tone="warn" label="Drained" />
           ) : (
             <StateBadge tone="warn" label="Not routable" />
           )}

package/src/cursor-accounts/__tests__/CursorAccountsConsole.test.tsx

@@ -86,6 +86,7 @@ function scenarSummary() {
   return create(CursorAccountSummarySchema, {
     account: scenarAccount(),
     enabledKeyCount: 1,
+    routableKeyCount: 1,
     lastSyncedAt: timestampFromDate(new Date("2026-07-22T12:00:00Z")),
   });
 }
@@ -194,6 +195,37 @@ describe("CursorAccountsConsole", () => {
     expect(screen.getByText("empty team")).toBeTruthy();
     expect(screen.getByText("Not routable")).toBeTruthy();
     expect(screen.getByText("shared pool")).toBeTruthy();
+    // Routable count renders as "N of M" (server-computed routability),
+    // and the fleet-health line aggregates it.
+    expect(screen.getByText("1 of 1")).toBeTruthy();
+    expect(screen.getByText(/1 routable key across 2 accounts/)).toBeTruthy();
+  });
+
+  it("surfaces a fully guard-drained account and the fleet drain alert", async () => {
+    // The 2026-08-15 shape: enabled keys exist, none routable — the one
+    // key left is usage-guard-tripped. The row must read "Drained" (a
+    // cycle-reset condition), not the misleading enabled count, and with
+    // zero routable keys fleet-wide the health line must alarm.
+    const drained = create(CursorAccountSummarySchema, {
+      account: scenarAccount({
+        accountId: "acc-3",
+        displayName: "drained team",
+        orgIds: [],
+      }),
+      enabledKeyCount: 1,
+      routableKeyCount: 0,
+      guardTrippedKeyCount: 1,
+    });
+    const client = createMockStigmer({
+      listAccounts: vi.fn().mockResolvedValue({ accounts: [drained] }),
+    });
+    render(<CursorAccountsConsole />, { wrapper: wrapper(client) });
+
+    await waitFor(() => expect(screen.getByText("drained team")).toBeTruthy());
+    expect(screen.getByText("Drained")).toBeTruthy();
+    expect(
+      screen.getByText(/No routable execution key anywhere/),
+    ).toBeTruthy();
   });
 
   it("shows the designed access notice on PERMISSION_DENIED", async () => {

package/src/cursor-accounts/__tests__/cursor-account-coverage.test.ts

@@ -7,12 +7,14 @@ import {
   CursorTeamMemberSchema,
 } from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/cursor_account_pb";
 import {
+  CursorAccountSummarySchema,
   CursorAccountViewSchema,
   CursorMemberKeyState,
   CursorMemberKeyViewSchema,
   CursorTeamMemberViewSchema,
 } from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/io_pb";
-import { deriveCoverage } from "../cursor-account-coverage";
+import { CursorAccountSchema } from "@stigmer/protos/ai/stigmer/platform/cursoraccount/v1/cursor_account_pb";
+import { deriveCoverage, derivePoolHealth } from "../cursor-account-coverage";
 
 function keyView(keyId: string, state: CursorMemberKeyState) {
   return create(CursorMemberKeyViewSchema, {
@@ -71,3 +73,58 @@ describe("deriveCoverage", () => {
     expect(coverage.onTeamWithKey).toEqual([]);
   });
 });
+
+describe("derivePoolHealth", () => {
+  function summary(opts: {
+    enabled?: boolean;
+    enabledKeyCount: number;
+    routableKeyCount: number;
+    guardTrippedKeyCount?: number;
+  }) {
+    return create(CursorAccountSummarySchema, {
+      account: create(CursorAccountSchema, {
+        accountId: "acc",
+        enabled: opts.enabled ?? true,
+      }),
+      enabledKeyCount: opts.enabledKeyCount,
+      routableKeyCount: opts.routableKeyCount,
+      guardTrippedKeyCount: opts.guardTrippedKeyCount ?? 0,
+    });
+  }
+
+  it("reproduces the 2026-08-15 drain as a one-line fact", () => {
+    // Four accounts with enabled keys but zero routable (guard-tripped or
+    // owner-removed), one fresh account with a single routable key — the
+    // fleet state the per-account enabled counts hid.
+    const health = derivePoolHealth([
+      summary({ enabledKeyCount: 1, routableKeyCount: 0, guardTrippedKeyCount: 1 }),
+      summary({ enabledKeyCount: 10, routableKeyCount: 0 }),
+      summary({ enabledKeyCount: 1, routableKeyCount: 0 }),
+      summary({ enabledKeyCount: 0, routableKeyCount: 0 }),
+      summary({ enabledKeyCount: 2, routableKeyCount: 1, guardTrippedKeyCount: 0 }),
+    ]);
+
+    expect(health.totalAccounts).toBe(5);
+    expect(health.totalRoutableKeys).toBe(1);
+    // The zero-key account is not "drained" — it never had capacity.
+    expect(health.drainedAccounts).toBe(3);
+    expect(health.guardTrippedKeys).toBe(1);
+  });
+
+  it("does not count disabled accounts as drained (disable means drain-by-choice)", () => {
+    const health = derivePoolHealth([
+      summary({ enabled: false, enabledKeyCount: 3, routableKeyCount: 0 }),
+    ]);
+
+    expect(health.drainedAccounts).toBe(0);
+  });
+
+  it("is all zeros for an empty list", () => {
+    const health = derivePoolHealth([]);
+
+    expect(health.totalAccounts).toBe(0);
+    expect(health.totalRoutableKeys).toBe(0);
+    expect(health.drainedAccounts).toBe(0);
+    expect(health.guardTrippedKeys).toBe(0);
+  });
+});

package/src/cursor-accounts/cursor-account-coverage.ts

@@ -1,5 +1,6 @@
 import {
   CursorMemberKeyState,
+  type CursorAccountSummary,
   type CursorAccountView,
   type CursorMemberKeyView,
   type CursorTeamMemberView,
@@ -69,3 +70,57 @@ export function deriveCoverage(view: CursorAccountView): CursorAccountCoverage {
     unclassified: [],
   };
 }
+
+/**
+ * Fleet-wide health rolled up from the list summaries — the console's
+ * answer to "can the platform serve right now, and from where?". Pure
+ * aggregation of the server-computed routable/guard counts (the same
+ * routability rule key selection uses); this module must never
+ * re-derive routability client-side.
+ *
+ * <p>Why this exists: in the 2026-08-15 pool drain, the list showed
+ * five accounts with healthy-looking enabled-key counts while exactly
+ * one guard-tripped key could serve — the operator had to open every
+ * account detail to see it. The rollup makes fleet exhaustion a
+ * one-line fact.
+ */
+export interface CursorPoolHealth {
+  /** Total accounts in the list. */
+  readonly totalAccounts: number;
+  /** Keys the routability rule would select for a new session, fleet-wide. */
+  readonly totalRoutableKeys: number;
+  /**
+   * Enabled accounts with enabled keys but zero routable ones — every
+   * key is dead (owner removed) or usage-drained. These are the rows
+   * that look healthy at a glance and are not.
+   */
+  readonly drainedAccounts: number;
+  /** Enabled keys excluded only by the usage guard, fleet-wide. */
+  readonly guardTrippedKeys: number;
+}
+
+/** Aggregate the server-computed summary counts across the account list. */
+export function derivePoolHealth(
+  summaries: readonly CursorAccountSummary[],
+): CursorPoolHealth {
+  let totalRoutableKeys = 0;
+  let drainedAccounts = 0;
+  let guardTrippedKeys = 0;
+  for (const summary of summaries) {
+    totalRoutableKeys += summary.routableKeyCount;
+    guardTrippedKeys += summary.guardTrippedKeyCount;
+    if (
+      summary.account?.enabled === true
+      && summary.enabledKeyCount > 0
+      && summary.routableKeyCount === 0
+    ) {
+      drainedAccounts += 1;
+    }
+  }
+  return {
+    totalAccounts: summaries.length,
+    totalRoutableKeys,
+    drainedAccounts,
+    guardTrippedKeys,
+  };
+}