@desplega.ai/agent-swarm 2.5.4 → 2.6.0

package/src/http/kv.ts

@@ -12,7 +12,11 @@ import {
   upsertKv,
 } from "../be/db";
 import { mcpOverflowAuthError } from "../kv-overflow";
-import { reservedNamespaceError, reservedRoomKeyError } from "../kv-reserved-namespaces";
+import {
+  privateNamespaceError,
+  reservedNamespaceError,
+  reservedRoomKeyError,
+} from "../kv-reserved-namespaces";
 import { hasKvViewArgs, resolveKvView } from "../kv-view";
 import { can } from "../rbac";
 import { agentContextKey, pageContextKey } from "../tasks/context-key";
@@ -405,8 +409,9 @@ function authorizeRead(
   namespace: string,
   ctx: AuthCtx,
 ): { status: number; message: string } | null {
-  const overflowAuthErr = mcpOverflowAuthError(namespace, ctx.callerAgentId);
-  return overflowAuthErr ? { status: 403, message: overflowAuthErr } : null;
+  const readErr =
+    privateNamespaceError(namespace) ?? mcpOverflowAuthError(namespace, ctx.callerAgentId);
+  return readErr ? { status: 403, message: readErr } : null;
 }
 
 function encodeValueOrError(

package/src/http/onboarding.ts

@@ -21,6 +21,7 @@ import {
 } from "../be/onboarding";
 import { assertUrlSafe, publicEndpointSsrfOptions } from "../oauth/mcp-wrapper";
 import { ProviderNameSchema } from "../types";
+import { splitCredentialPool } from "../utils/credentials";
 import { getOpenRouterAttributionHeaders } from "../utils/openrouter-base-url";
 import { ensureConfigAdmin } from "./config";
 import { scheduleIntegrationsReload } from "./core";
@@ -36,11 +37,14 @@ async function buildSignals(state: OnboardingState): Promise<OnboardingSignals>
     const provider = ProviderNameSchema.safeParse(entry.provider);
     if (!provider.success) continue;
     const rollup = await rollupCredStatusForProvider(provider.data);
+    const live = rollup.latestLiveTest;
     providers.push({
       provider: provider.data,
       state: rollup.state,
       workers: rollup.workers,
       verifiedWorkers: rollup.verifiedWorkers,
+      error: live && !live.ok ? (live.error ?? null) : null,
+      warning: live?.ok ? (live.warning ?? null) : null,
     });
   }
 
@@ -241,7 +245,8 @@ async function handleMemoryProbe(body: OnboardingMemoryRequest): Promise<Onboard
     body.preset === "existing"
       ? (process.env.EMBEDDING_API_KEY ?? process.env.OPENAI_API_KEY)
       : undefined;
-  const apiKey = explicitKey ?? reusedKey ?? implicitKey;
+  // Test and save the same pool member.
+  const apiKey = splitCredentialPool(explicitKey ?? reusedKey ?? implicitKey ?? "")[0];
 
   if (!apiKey) {
     return {

package/src/http/pool-keys.ts

@@ -0,0 +1,354 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { baseUrlEnvVar, providerForKeyVar } from "@desplega/model-catalog";
+import { z } from "zod";
+import {
+  deleteSwarmConfigByKey,
+  getDbClient,
+  getKeyStatuses,
+  getSwarmConfigs,
+  recordKeyValidation,
+} from "../be/db";
+import { retirePoolKeyStatus } from "../be/db/api-keys";
+import { upsertSwarmConfigWithPolicyMirror } from "../be/multi-runtime";
+import { validateConfigEntry } from "../be/swarm-config-guard";
+import type { SwarmConfig } from "../types";
+import { CREDENTIAL_POOL_VARS, splitCredentialPool } from "../utils/credentials";
+import { checkProviderPoolKey } from "../utils/provider-key-probes";
+import { registerEnvSecrets, scrubSecrets } from "../utils/secret-scrubber";
+import { ensureConfigAdmin, requestSecretReadScope, runConfigWriteSideEffects } from "./config";
+import { getDeploymentEnvValue } from "./core";
+import { route } from "./route-def";
+import { jsonError } from "./utils";
+
+export const PoolKeyStatusSchema = z.enum(["ok", "rejected", "rate_limited", "unchecked"]);
+export type PoolKeyStatus = z.infer<typeof PoolKeyStatusSchema>;
+export const PoolKeySchema = z.object({
+  index: z.number().int().min(0),
+  suffix: z.string(),
+  status: PoolKeyStatusSchema,
+  error: z.string().nullable(),
+  checkedAt: z.string().nullable(),
+  rateLimitedUntil: z.string().nullable(),
+});
+export type PoolKey = z.infer<typeof PoolKeySchema>;
+export const PoolKeysResponseSchema = z.object({
+  key: z.string(),
+  source: z.enum(["stored", "env", "none"]),
+  readOnly: z.boolean(),
+  keys: z.array(PoolKeySchema),
+});
+export type PoolKeysResponse = z.infer<typeof PoolKeysResponseSchema>;
+export const PoolKeyCheckResultSchema = z.enum(["verified", "rejected", "not_tested"]);
+export type PoolKeyCheckResult = z.infer<typeof PoolKeyCheckResultSchema>;
+export const PoolKeyCheckSchema = z.object({
+  suffix: z.string(),
+  result: PoolKeyCheckResultSchema,
+  httpStatus: z.number().nullable(),
+  error: z.string().nullable(),
+});
+export type PoolKeyCheck = z.infer<typeof PoolKeyCheckSchema>;
+
+const poolVar = z
+  .string()
+  .refine(
+    (key) => key !== "CODEX_OAUTH" && CREDENTIAL_POOL_VARS.includes(key),
+    "Choose a credential pool variable.",
+  );
+const getPoolKeys = route({
+  method: "get",
+  path: "/api/config/pool-keys",
+  pattern: ["api", "config", "pool-keys"],
+  summary: "List credential pool suffixes and status",
+  tags: ["Config"],
+  query: z.object({ key: poolVar }),
+  responses: {
+    200: { description: "Credential pool", schema: PoolKeysResponseSchema },
+    400: { description: "Invalid pool variable" },
+    403: { description: "Secret read permission required" },
+  },
+});
+const addPoolKeys = route({
+  method: "post",
+  path: "/api/config/pool-keys",
+  pattern: ["api", "config", "pool-keys"],
+  summary: "Test and append keys to a credential pool",
+  tags: ["Config"],
+  rbac: { permission: "config.write.any" },
+  body: z.object({
+    key: poolVar,
+    value: z.string(),
+    // The OpenRouter card can switch away from a stored gateway before the new key is saved.
+    baseUrl: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        "Base URL for the check only. Null tests the provider default. Omit to use the stored URL.",
+      ),
+  }),
+  responses: {
+    200: {
+      description: "Updated credential pool and checks",
+      schema: PoolKeysResponseSchema.extend({ checks: z.array(PoolKeyCheckSchema) }),
+    },
+    400: { description: "Invalid key" },
+    403: { description: "Config administration and permission to read all secrets required" },
+    409: { description: "Duplicate key or deployment env pool" },
+    422: {
+      description: "Provider rejected a key. Nothing was saved.",
+      schema: z.object({ error: z.string(), checks: z.array(PoolKeyCheckSchema) }),
+    },
+  },
+});
+const deletePoolKey = route({
+  method: "delete",
+  path: "/api/config/pool-keys",
+  pattern: ["api", "config", "pool-keys"],
+  summary: "Remove one credential pool member",
+  tags: ["Config"],
+  rbac: { permission: "config.delete.any" },
+  query: z.object({
+    key: poolVar,
+    index: z.coerce.number().int().min(0),
+    suffix: z.string().min(1).max(5),
+  }),
+  responses: {
+    200: { description: "Updated credential pool", schema: PoolKeysResponseSchema },
+    400: { description: "Invalid pool member" },
+    403: { description: "Config administration and permission to read all secrets required" },
+    409: { description: "The pool changed or comes from the deployment env" },
+  },
+});
+
+const ENV_POOL_ERROR = "These keys come from the deployment env. Change them there.";
+
+async function readPool(key: string) {
+  const [row] = await getSwarmConfigs({ scope: "global", key });
+  const envValue = getDeploymentEnvValue(key);
+  const source = row ? "stored" : envValue ? "env" : "none";
+  const value = row?.value ?? envValue ?? "";
+  registerEnvSecrets({ [key]: value });
+  return { row, source, members: splitCredentialPool(value) } as const;
+}
+
+async function poolResponse(key: string): Promise<PoolKeysResponse> {
+  const pool = await readPool(key);
+  const statuses = await getKeyStatuses(key, "global", null);
+  return {
+    key,
+    source: pool.source,
+    readOnly: pool.source === "env",
+    keys: pool.members.map((member, index) => {
+      const suffix = member.slice(-5);
+      const row = statuses.find((status) => status.keySuffix === suffix);
+      const rejected = !!row?.lastValidationFailedAt;
+      const limited =
+        row?.status === "rate_limited" &&
+        !!row.rateLimitedUntil &&
+        Date.parse(row.rateLimitedUntil) > Date.now();
+      return {
+        index,
+        suffix,
+        status: rejected ? "rejected" : limited ? "rate_limited" : row ? "ok" : "unchecked",
+        error: rejected ? scrubSecrets(row?.lastValidationError) || null : null,
+        checkedAt: rejected ? row!.lastValidationFailedAt : (row?.updatedAt ?? null),
+        rateLimitedUntil: row?.rateLimitedUntil ?? null,
+      };
+    }),
+  };
+}
+
+function duplicateError(members: readonly string[], additions: string[]): string | null {
+  const seen = new Set(members);
+  for (const member of additions) {
+    if (seen.has(member)) return `The key ending ${member.slice(-5)} is already in the pool.`;
+    seen.add(member);
+  }
+  return null;
+}
+
+async function savePool(key: string, members: string[], row: SwarmConfig | undefined) {
+  const value = members.join(",");
+  const validationError = validateConfigEntry({
+    scope: "global",
+    key,
+    value,
+    exportToEnv: row?.exportToEnv,
+  });
+  if (validationError) return validationError;
+  await upsertSwarmConfigWithPolicyMirror({
+    scope: "global",
+    key,
+    value,
+    isSecret: true,
+    description: row?.description ?? null,
+    envPath: row?.envPath ?? null,
+    exportToEnv: row?.exportToEnv,
+  });
+  return null;
+}
+
+/** Every response lists the pool's key suffixes and statuses, so each route needs this gate. */
+async function ensureSecretRead(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if ((await requestSecretReadScope(req)) === "all") return true;
+  jsonError(res, "Reading credential pools requires permission to read all secrets.", 403);
+  return false;
+}
+
+export async function handlePoolKeys(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (getPoolKeys.match(req.method, pathSegments)) {
+    const parsed = await getPoolKeys.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureSecretRead(req, res))) return true;
+    getPoolKeys.respond(res, 200, await poolResponse(parsed.query.key));
+    return true;
+  }
+  if (addPoolKeys.match(req.method, pathSegments)) {
+    const parsed = await addPoolKeys.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureConfigAdmin(req, res, "config.write.any"))) return true;
+    if (!(await ensureSecretRead(req, res))) return true;
+    const { key, value, baseUrl } = parsed.body;
+    const additions = value
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean);
+    if (!additions.length) {
+      jsonError(res, "Enter a key.", 400);
+      return true;
+    }
+    if (additions.some((part) => /\s/.test(part))) {
+      jsonError(res, "A key cannot contain spaces or line breaks.", 400);
+      return true;
+    }
+    registerEnvSecrets({ [key]: additions.join(",") });
+    const initial = await readPool(key);
+    if (initial.source === "env") {
+      jsonError(res, ENV_POOL_ERROR, 409);
+      return true;
+    }
+    const duplicate = duplicateError(initial.members, additions);
+    if (duplicate) {
+      jsonError(res, scrubSecrets(duplicate), 409);
+      return true;
+    }
+    const env = { ...process.env };
+    const provider = providerForKeyVar(key);
+    const baseUrlKey =
+      key === "OPENROUTER_API_KEY"
+        ? "OPENROUTER_BASE_URL"
+        : provider
+          ? baseUrlEnvVar(provider)
+          : undefined;
+    if (baseUrlKey && baseUrl !== undefined) {
+      env[baseUrlKey] = baseUrl ?? "";
+    } else if (baseUrlKey) {
+      const [row] = await getSwarmConfigs({ scope: "global", key: baseUrlKey });
+      if (row) env[baseUrlKey] = row.value;
+    }
+    const checks = await Promise.all(
+      additions.map(async (member): Promise<PoolKeyCheck> => {
+        try {
+          const probe = await checkProviderPoolKey(key, member, env);
+          return {
+            suffix: member.slice(-5),
+            result: probe.skipped
+              ? "not_tested"
+              : probe.ok
+                ? "verified"
+                : probe.httpStatus === 401
+                  ? "rejected"
+                  : "not_tested",
+            httpStatus: probe.httpStatus ?? null,
+            error: scrubSecrets(probe.error?.replaceAll(member, "[REDACTED]")) || null,
+          };
+        } catch {
+          return {
+            suffix: member.slice(-5),
+            result: "not_tested",
+            httpStatus: null,
+            error: "The provider check did not complete.",
+          };
+        }
+      }),
+    );
+    const rejected = checks.find((check) => check.result === "rejected");
+    if (rejected) {
+      addPoolKeys.respond(res, 422, {
+        error: scrubSecrets(
+          `The key ending ${rejected.suffix} was rejected (HTTP 401). Nothing was saved.`,
+        ),
+        checks,
+      });
+      return true;
+    }
+    const result = await getDbClient().transaction(async () => {
+      const current = await readPool(key);
+      if (current.source === "env") return { error: ENV_POOL_ERROR, status: 409 };
+      const duplicate = duplicateError(current.members, additions);
+      if (duplicate) return { error: duplicate, status: 409 };
+      const members = [...current.members, ...additions];
+      const error = await savePool(key, members, current.row);
+      if (error) return { error, status: 400 };
+      await recordKeyValidation(
+        key,
+        checks.flatMap((check, index) =>
+          check.result === "verified"
+            ? [{ keyIndex: current.members.length + index, keySuffix: check.suffix, ok: true }]
+            : [],
+        ),
+        "global",
+        null,
+        { retireAbsent: false },
+      );
+      return { value: members.join(",") };
+    });
+    if ("error" in result) {
+      jsonError(res, scrubSecrets(result.error), result.status);
+      return true;
+    }
+    await runConfigWriteSideEffects("global", key, result.value);
+    addPoolKeys.respond(res, 200, { ...(await poolResponse(key)), checks });
+    return true;
+  }
+  if (deletePoolKey.match(req.method, pathSegments)) {
+    const parsed = await deletePoolKey.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureConfigAdmin(req, res, "config.delete.any"))) return true;
+    if (!(await ensureSecretRead(req, res))) return true;
+    const { key, index, suffix } = parsed.query;
+    const result = await getDbClient().transaction(async () => {
+      const current = await readPool(key);
+      if (current.source === "env") return { error: ENV_POOL_ERROR, status: 409 };
+      if (!current.members[index] || current.members[index].slice(-5) !== suffix) {
+        return { error: "The key list changed. Reload it and try again.", status: 409 };
+      }
+      const members = current.members.filter((_, position) => position !== index);
+      if (members.length) {
+        const error = await savePool(key, members, current.row);
+        if (error) return { error, status: 400 };
+      } else {
+        await deleteSwarmConfigByKey("global", null, key);
+      }
+      await retirePoolKeyStatus(
+        key,
+        suffix,
+        members.map((member, keyIndex) => ({ keySuffix: member.slice(-5), keyIndex })),
+      );
+      return { value: members.join(",") };
+    });
+    if ("error" in result) {
+      jsonError(res, scrubSecrets(result.error), result.status);
+      return true;
+    }
+    await runConfigWriteSideEffects("global", key, result.value);
+    deletePoolKey.respond(res, 200, await poolResponse(key));
+    return true;
+  }
+  return false;
+}

package/src/http/sessions.ts

@@ -6,6 +6,7 @@ import {
   normalizeAssetKey,
   parseAssetKey,
 } from "../assets/key";
+import { SOURCE_GROUPS_READ_ONLY, sourceMoveError, sourceOfKey } from "../assets/source-key";
 import { AssetKeyAuthorizationError, authorizeAssetKeyWrite } from "../be/asset-key-auth";
 import { resolveHttpAuditUserId } from "../be/audit-user";
 import {
@@ -20,13 +21,19 @@ import {
   getTaskById,
   listRecentSessions,
 } from "../be/db";
+import { getSessionLabels } from "../be/db/session-labels";
 import {
   listPrefixRoots,
   listSharedPrefixRoots,
   moveSessionChains,
   type SessionKeyMove,
 } from "../be/db/session-moves";
-import { getSessionReadState, getSessionTree, triageSessionList } from "../be/db/session-tree";
+import {
+  getSessionGroupKey,
+  getSessionReadState,
+  getSessionTree,
+  triageSessionList,
+} from "../be/db/session-tree";
 import { getUserGrant } from "../be/rbac-roles";
 import {
   getSessionRoot,
@@ -53,6 +60,7 @@ import {
 import { can, isRbacEnabled } from "../rbac";
 import { sessionAccessTopic } from "../realtime/auth";
 import { realtimeBus } from "../realtime/bus";
+import { warmSlackChannelLabels } from "../slack/channel-labels";
 import {
   type AgentTask,
   AgentTaskSchema,
@@ -152,6 +160,7 @@ const SessionTreeGroupSchema = SessionSectionCountsSchema.extend({
   lastActivityAt: z.string(),
 });
 const SessionTreeResponseSchema = z.object({
+  labels: z.record(z.string(), z.string()).optional(),
   groups: z.array(SessionTreeGroupSchema),
   inbox: SessionSectionCountsSchema,
   later: SessionSectionCountsSchema,
@@ -738,7 +747,7 @@ async function checkSessionMove(
   actor: SessionActor,
   req: IncomingMessage,
   myAgentId: string | undefined,
-  options: { ownerOnly?: boolean } = {},
+  options: { ownerOnly?: boolean; destination?: string | null } = {},
 ): Promise<{ reason: string } | { taskIds: string[] }> {
   const root = await getTaskById(rootTaskId);
   if (!root) return { reason: SESSION_MOVE_UNAVAILABLE };
@@ -752,6 +761,8 @@ async function checkSessionMove(
     if (!hasSessionAccess(access, "write")) return { reason: "Session write access required" };
   }
   if (root.parentTaskId) return { reason: "Task is not a session root" };
+  const sourceError = sourceMoveError(options.destination ?? null, root);
+  if (sourceError) return { reason: sourceError };
   const tasks = await getRootTaskChain(root.id);
   for (const task of tasks) {
     if (!(await canMutateTaskNamespace(task, myAgentId, req))) {
@@ -778,6 +789,8 @@ const getSession = route({
         chain: z.array(TaskWithSteeringSchema),
         access: SessionAccessSchema,
         owner: SessionOwnerSchema.nullable(),
+        /** The group of `root` with the list's rule: a source thread with two or more roots is its own group. */
+        groupKey: z.string(),
         approvals: z.array(SessionApprovalSchema).optional(),
         /** The viewer's read state, with the list's rule. Omitted for callers that act for no user. */
         readState: z.enum(["unread", "read", "later", "done"]).optional(),
@@ -1012,15 +1025,18 @@ export async function handleSessions(
     const parsed = await sessionTree.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     const actor = await resolveSessionActor(req, myAgentId);
-    sessionTree.respond(
-      res,
-      200,
-      await getSessionTree(actor, undefined, {
-        mine: parsed.query.show !== "all",
-        hideSource: parsed.query.hideSource,
-        showSource: parsed.query.showSource,
-      }),
+    const tree = await getSessionTree(actor, undefined, {
+      mine: parsed.query.show !== "all",
+      hideSource: parsed.query.hideSource,
+      showSource: parsed.query.showSource,
+    });
+    // Labels cover hidden sources too: a pane or tab of a hidden source still names its group.
+    const { sourceGroups, slackChannels, threadLabels, ...counts } = tree;
+    const labels = { ...threadLabels, ...(await getSessionLabels(sourceGroups)) };
+    warmSlackChannelLabels(
+      slackChannels.map((id) => `shared/slack/${id}/`).filter((key) => labels[key] === undefined),
     );
+    sessionTree.respond(res, 200, { ...counts, labels });
     return true;
   }
 
@@ -1054,7 +1070,9 @@ export async function handleSessions(
         const skipped: { rootTaskId: string; reason: string }[] = [];
         const moves: SessionKeyMove[] = [];
         for (const rootId of new Set(parsed.body.rootTaskIds)) {
-          const checked = await checkSessionMove(rootId, actor, req, myAgentId);
+          const checked = await checkSessionMove(rootId, actor, req, myAgentId, {
+            destination: key,
+          });
           if ("reason" in checked) {
             skipped.push({ rootTaskId: rootId, reason: checked.reason });
           } else {
@@ -1076,6 +1094,10 @@ export async function handleSessions(
     const parsed = await moveSessionPrefix.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     const from = normalizeAssetKey(parsed.body.from);
+    if (sourceOfKey(from) || (parsed.body.to && sourceOfKey(normalizeAssetKey(parsed.body.to)))) {
+      jsonError(res, SOURCE_GROUPS_READ_ONLY, 400);
+      return true;
+    }
     if (parseAssetKey(from).relativeSegments.length === 0) {
       jsonError(res, "Cannot move a namespace root", 400);
       return true;
@@ -1126,6 +1148,7 @@ export async function handleSessions(
             }
             const checked = await checkSessionMove(root.id, actor, req, myAgentId, {
               ownerOnly: true,
+              destination: nextKey,
             });
             if ("reason" in checked) {
               skipped.push({ rootTaskId: root.id, reason: checked.reason });
@@ -1175,7 +1198,7 @@ export async function handleSessions(
     const chain = await getRootTaskChain(parsed.params.rootTaskId);
     // Load steering, citations and pending approvals for the already loaded chain.
     const tasks = [root, ...chain];
-    const [steering, citations, approvals, read] = await Promise.all([
+    const [steering, citations, approvals, read, groupKey] = await Promise.all([
       getTaskSteeringFieldsForTasks(tasks),
       getTaskCitationsForTasks(tasks.map((task) => task.id)),
       getPendingApprovalsForTasks(tasks.map((task) => task.id)),
@@ -1184,6 +1207,7 @@ export async function handleSessions(
       actor.kind === "user" && actor.userId
         ? getSessionReadState(sessionRoot.id, actor.userId)
         : Promise.resolve(null),
+      getSessionGroupKey(root),
     ]);
     const decorate = (task: AgentTask) => ({
       ...task,
@@ -1195,6 +1219,7 @@ export async function handleSessions(
       chain: chain.map(decorate),
       access,
       owner,
+      groupKey,
       ...(approvals.length ? { approvals } : {}),
       ...(read ?? {}),
     });

package/src/http/stats.ts

@@ -86,6 +86,7 @@ const SwarmMetricsSchema = z.object({
     agentLog: RetentionTableStatsSchema.optional(),
     events: RetentionTableStatsSchema.optional(),
     contextVersions: RetentionTableStatsSchema.optional(),
+    scriptRuns: RetentionTableStatsSchema.optional(),
   }),
 });
 

package/src/http/status.ts

@@ -29,6 +29,7 @@ import {
   getDbClient,
   getInstanceActivity,
   getLiveAgentCounts,
+  getReadyAgentCounts,
   hasFirstCompletedTask,
   listAgentsWithCredStatusByProvider,
   NOT_EXTENSION_AGENT_SQL,
@@ -121,6 +122,12 @@ export type StatusIdentity = z.infer<typeof StatusIdentitySchema>;
 export const StatusActivitySchema = z.object({
   agents_online: z.number().int().nonnegative(),
   leads_online: z.number().int().nonnegative(),
+  /**
+   * Leads that can take work now (status `idle` or `busy`). Unlike
+   * `leads_online`, this does not depend on a recent heartbeat: an idle lead
+   * stops updating its activity time.
+   */
+  leads_ready: z.number().int().nonnegative(),
   recent_tasks_count: z.number().int().nonnegative(),
 });
 export type StatusActivity = z.infer<typeof StatusActivitySchema>;
@@ -194,12 +201,13 @@ export type AutomationStatus = z.infer<typeof AutomationStatusSchema>;
 /**
  * Phase 2: Aggregate health derived from setup milestones.
  *
- * - `broken`  — harness or workers blocking (creds missing, no live workers ever).
- * - `degraded` — at least one optional integration `unverified`/`configured`
- *                 while another is configured, OR harness creds present but
- *                 the latest live test failed or never ran (`configured`).
- * - `ok`       — harness + workers `verified`; no integration left in
- *                 `configured` state.
+ * - `broken`: harness or workers blocking (creds missing, no live workers ever).
+ * - `degraded`: no lead can take work (none is `idle` or `busy`), OR at
+ *   least one optional integration `unverified`/`configured` while another
+ *   is configured, OR harness creds present but the latest live test failed
+ *   or never ran (`configured`).
+ * - `ok`: harness + workers `verified`, a lead can take work, and no
+ *   integration left in `configured` state.
  */
 export const StatusHealthSchema = z.enum(["ok", "degraded", "broken"]);
 export type StatusHealth = z.infer<typeof StatusHealthSchema>;
@@ -692,19 +700,23 @@ export async function buildSetup(
  * Decision matrix:
  * - Harness `unverified` (no creds at all) → `broken` — the swarm cannot run a task.
  * - Workers `unverified` (no agents ever) → `broken` — same reason.
+ * - No lead can take work (`readyLeads` is 0) → `degraded`. Tasks wait until a lead is online.
  * - Harness `configured` (creds present, never live-tested) → `degraded`.
  * - Any of {slack, github, linear, jira} `configured` (i.e. half-set-up) → `degraded`.
  * - Otherwise → `ok`.
  *
  * Notes:
+ * - `readyLeads` counts leads with status `idle` or `busy`
+ *   (`getReadyAgentCounts`). It does not use the heartbeat time: an agent
+ *   updates `lastActivityAt` only while a session runs, so an idle, healthy
+ *   lead looks stale.
  * - Worker `configured` (fleet exists but missed recent heartbeats) does NOT
- *   degrade the rollup. Heartbeat drift is a runtime concern surfaced on the
- *   /agents page and the dashboard canvas — not a setup health signal.
+ *   degrade the rollup on its own, for the same reason.
  * - Integrations in `unverified` are NOT degrading on their own — most
  *   deployments don't connect every integration. They only nudge the rollup if
  *   paired with another integration in `configured` (the brainstorm contract).
  */
-export function computeHealth(setup: SetupMilestone[]): StatusHealth {
+export function computeHealth(setup: SetupMilestone[], readyLeads: number): StatusHealth {
   const byId = new Map(setup.map((m) => [m.id, m] as const));
   const harness = byId.get("harness");
   const workers = byId.get("workers");
@@ -714,6 +726,7 @@ export function computeHealth(setup: SetupMilestone[]): StatusHealth {
   if (!workers || workers.state === "unverified") return "broken";
 
   // `degraded` rules.
+  if (readyLeads === 0) return "degraded";
   if (harness.state === "configured") return "degraded";
 
   for (const id of ["slack", "github", "linear", "jira"] as const) {
@@ -740,12 +753,13 @@ export async function buildStatusPayload(): Promise<StatusResponse> {
     .map((automation) => toStatus(preflightAutomation(automation, automationSetup)))
     .sort((a, b) => a.name.localeCompare(b.name) || a.kind.localeCompare(b.kind));
   const activity = await getInstanceActivity();
+  const readyLeads = (await getReadyAgentCounts()).leads;
   const instance = await getInstanceFeedbackSignals();
   return {
     runtime_pools: { enabled: isRuntimePoolsEnabled(), supervisor: runtimeSupervisorStatus() },
     identity: buildIdentity(),
     setup,
-    activity,
+    activity: { ...activity, leads_ready: readyLeads },
     agent_fs: {
       configured: !!process.env.AGENT_FS_API_URL,
       base_url: process.env.AGENT_FS_API_URL ?? null,
@@ -753,7 +767,7 @@ export async function buildStatusPayload(): Promise<StatusResponse> {
       comb: getCombStatus(await combServiceUserId),
     },
     automations,
-    health: computeHealth(setup),
+    health: computeHealth(setup, readyLeads),
     telemetry: { enabled: isTelemetryEnabled() },
     instance,
   };
@@ -797,7 +811,7 @@ const getStatus = route({
   pattern: ["status"],
   summary: "Identity + setup readiness + live activity for the swarm dashboard",
   description:
-    "Single source of truth consumed by the UI home page. Identity comes from SWARM_* envs; setup milestones each emit `unverified | configured | verified`; automations report `running | needs_setup` from the same runtime preflight used at dispatch; activity counts agents alive in the last 5 min and tasks created in the last 24h; agent_fs reports whether AGENT_FS_API_URL is set, plus the Comb settings (COMB_ENABLED, the browser-facing agent-fs URL, the shared org and drive ids, and the agent-fs user id of the swarm service account); telemetry reports the effective ANONYMIZED_TELEMETRY opt-out state.",
+    "Single source of truth consumed by the UI home page. Identity comes from SWARM_* envs; setup milestones each emit `unverified | configured | verified`; automations report `running | needs_setup` from the same runtime preflight used at dispatch; activity counts agents alive in the last 5 min, leads that can take work (status idle or busy), and tasks created in the last 24h; agent_fs reports whether AGENT_FS_API_URL is set, plus the Comb settings (COMB_ENABLED, the browser-facing agent-fs URL, the shared org and drive ids, and the agent-fs user id of the swarm service account); telemetry reports the effective ANONYMIZED_TELEMETRY opt-out state.",
   tags: ["Status"],
   responses: {
     200: { description: "Status payload", schema: StatusResponseSchema },