@desplega.ai/agent-swarm 2.5.4 → 2.7.0

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 },

package/src/http/tasks.ts

@@ -227,6 +227,8 @@ const listTasks = route({
     status: z.string().optional(),
     agentId: z.string().optional(),
     scheduleId: z.string().optional(),
+    /** Only tasks of this workflow run (indexed; independent of fleet size). */
+    workflowRunId: z.string().uuid().optional(),
     key: AssetKeySchema.optional(),
     keyPrefix: AssetKeySchema.optional(),
     search: z.string().optional(),
@@ -976,6 +978,7 @@ export async function handleTasks(
       status,
       agentId: parsed.query.agentId || undefined,
       scheduleId: parsed.query.scheduleId || undefined,
+      workflowRunId: parsed.query.workflowRunId,
       key: parsed.query.key,
       keyPrefix: parsed.query.keyPrefix,
       search: parsed.query.search || undefined,

package/src/http/used-by.ts

@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { getDbClient, upsertSwarmConfig } from "../be/db";
 import { isTelemetryEnabled, trackRelayed } from "../telemetry";
-import { USER_FUNCTIONS } from "../utils/company-profile";
+import { reportedUserFunction, USER_FUNCTIONS } from "../utils/company-profile";
 import { orgIdentityStatus } from "../utils/org-identity";
 import { normalizeOrgWebsite, TELEMETRY_PROXY_ORIGIN } from "../utils/org-website";
 import { ensureConfigAdmin } from "./config";
@@ -129,7 +129,12 @@ export async function handleUsedBy(
         ...(orgDomain ? { org_domain: orgDomain } : {}),
         granted,
         ...(granted
-          ? { contact_email: contactEmail, contact_function: contactFunction, quote }
+          ? {
+              contact_email: contactEmail,
+              // The proxy rejects a job function its catalog does not list yet.
+              contact_function: reportedUserFunction(contactFunction),
+              quote,
+            }
           : {}),
         changed_at: changedAt,
       }),

package/src/http/workflows.ts

@@ -23,7 +23,14 @@ import {
   type WorkflowIdempotencyClaim,
   workflowRequestFingerprint,
 } from "../be/db/workflow-idempotency";
-import { getWorkflowRunParent } from "../be/db/workflow-runs";
+import {
+  getWorkflowRunParent,
+  getWorkflowRunStepsSlimByRunId,
+  getWorkflowRunSummary,
+  getWorkflowRunTree,
+  WORKFLOW_RUN_TREE_MAX_DEPTH,
+  WorkflowRunTreeError,
+} from "../be/db/workflow-runs";
 import {
   AssetKeySchema,
   AutomationIntegrationIdSchema,
@@ -39,6 +46,7 @@ import {
   WorkflowRunSchema,
   WorkflowRunStatusSchema,
   WorkflowRunStepSchema,
+  WorkflowRunStepSlimSchema,
   WorkflowRunSummarySchema,
   WorkflowSchema,
   WorkflowVersionSchema,
@@ -109,6 +117,13 @@ const WorkflowRunPageSchema = z.object({
   }),
 });
 
+/** Mirrors `WorkflowRunTree` in src/be/db/workflow-runs.ts. */
+const WorkflowRunTreeSchema = z.object({
+  rootRunId: z.string(),
+  runs: z.array(WorkflowRunSummarySchema),
+  hasOpenWork: z.boolean(),
+});
+
 const SuccessResponseSchema = z.object({ success: z.literal(true) });
 
 /** Adds `warnings` to a just-saved workflow when a node in it cannot run yet. */
@@ -292,6 +307,15 @@ const triggerWorkflowRoute = route({
     "With an `Idempotency-Key`, a retry returns the accepted run's `runId` and `skipped` without starting, resuming or waiting for anything, even after the workflow was disabled or edited and whatever state the run is in now.",
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
+  query: z.object({
+    wait: z
+      .enum(["true", "false"])
+      .optional()
+      .describe(
+        "Default true: respond after the run's instant steps ran, when it finishes or parks at its first async step. " +
+          "false: respond as soon as the run is committed and walk it in the background.",
+      ),
+  }),
   headers: idempotencyKeyHeader("starts one run"),
   responses: {
     201: {
@@ -349,22 +373,50 @@ const getWorkflowRunRoute = route({
   path: "/api/workflow-runs/{id}",
   pattern: ["api", "workflow-runs", null],
   summary: "Get a workflow run with steps (includes retry columns)",
+  description:
+    "Returns the run with its `context` and every step with its `input` by default. A step's `input` is a snapshot of the context when the step started, so in runs with loops (polling, `wait`, iterations) the response grows with steps × context size. Pass `fields=slim` to drop `run.context` and `steps[].input`; outputs, errors, diagnostics, retry fields and `parent` stay.",
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
+  query: z.object({
+    /** `slim` omits `run.context` and `steps[].input`; default is full. */
+    fields: z.enum(["full", "slim"]).optional(),
+  }),
   responses: {
     200: {
       description: "Workflow run details with steps including retry info",
-      schema: z.object({
-        run: WorkflowRunSchema,
-        steps: z.array(WorkflowRunStepSchema),
-        /** Set on a child run: the run and `sub-workflow` step that started it. */
-        parent: WorkflowRunParentSchema.optional(),
-      }),
+      schema: z.union([
+        z.object({
+          run: WorkflowRunSchema,
+          steps: z.array(WorkflowRunStepSchema),
+          /** Set on a child run: the run and `sub-workflow` step that started it. */
+          parent: WorkflowRunParentSchema.optional(),
+        }),
+        z.object({
+          run: WorkflowRunSummarySchema,
+          steps: z.array(WorkflowRunStepSlimSchema),
+          parent: WorkflowRunParentSchema.optional(),
+        }),
+      ]),
     },
     404: { description: "Run not found" },
   },
 });
 
+const getWorkflowRunTreeRoute = route({
+  method: "get",
+  path: "/api/workflow-runs/{id}/tree",
+  pattern: ["api", "workflow-runs", null, "tree"],
+  summary: "Get a workflow run and every sub-workflow run below it",
+  description: `Follows stored parent links (\`parentStepId\` → step → run) through every attempt of every step, terminal runs included. \`runs\` holds list rows without \`context\`, root first. \`hasOpenWork\` is true while any run in the tree is live, has a pending, running or waiting step, a queued retry, an open task or a pending approval; after a cancel it turns false once the tree has settled. Both come from one read snapshot. The tree is not paginated. Links that form a cycle or nest deeper than ${WORKFLOW_RUN_TREE_MAX_DEPTH} levels return 409.`,
+  tags: ["Workflows"],
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "The run tree", schema: WorkflowRunTreeSchema },
+    404: { description: "Run not found" },
+    409: { description: "Stored parent links form a cycle or nest past the depth bound" },
+  },
+});
+
 const retryWorkflowRunRoute = route({
   method: "post",
   path: "/api/workflow-runs/{id}/retry",
@@ -959,6 +1011,7 @@ export async function handleWorkflows(
       runId = await startWorkflowExecution(workflow, body, getExecutorRegistry(), {
         triggerType: "api",
         requestedByUserId: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
+        detach: parsed.query.wait === "false",
         // Recorded in the run's own transaction, before the walk starts.
         accept: claim
           ? async (run) => {
@@ -1014,18 +1067,44 @@ export async function handleWorkflows(
     const parsed = await getWorkflowRunRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     // Display view: the scrubbed context and step outputs, never replay state.
-    const run = await getWorkflowRun(parsed.params.id, "display");
+    // `fields=slim` skips the context and step-input columns in SQL too.
+    const slim = parsed.query.fields === "slim";
+    const run = slim
+      ? await getWorkflowRunSummary(parsed.params.id)
+      : await getWorkflowRun(parsed.params.id, "display");
     if (!run) {
       res.writeHead(404);
       res.end();
       return true;
     }
-    const steps = await getWorkflowRunStepsByRunId(parsed.params.id, "display");
+    const steps = slim
+      ? await getWorkflowRunStepsSlimByRunId(parsed.params.id)
+      : await getWorkflowRunStepsByRunId(parsed.params.id, "display");
     const parent = run.parentStepId ? await getWorkflowRunParent(run.parentStepId) : null;
     getWorkflowRunRoute.respond(res, 200, { run, steps, ...(parent ? { parent } : {}) });
     return true;
   }
 
+  if (getWorkflowRunTreeRoute.match(req.method, pathSegments)) {
+    const parsed = await getWorkflowRunTreeRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    let tree: Awaited<ReturnType<typeof getWorkflowRunTree>>;
+    try {
+      tree = await getWorkflowRunTree(parsed.params.id);
+    } catch (err) {
+      if (!(err instanceof WorkflowRunTreeError)) throw err;
+      jsonError(res, err.message, 409);
+      return true;
+    }
+    if (!tree) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    getWorkflowRunTreeRoute.respond(res, 200, tree);
+    return true;
+  }
+
   if (retryWorkflowRunRoute.match(req.method, pathSegments)) {
     const parsed = await retryWorkflowRunRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;

package/src/http/x.ts

@@ -20,6 +20,7 @@ import {
   MAX_SCRIPT_WALL_CLOCK_MS,
   MIN_SCRIPT_WALL_CLOCK_MS,
 } from "../scripts-runtime/executors/types";
+import { HOST_VALIDATED_ARGS } from "../scripts-runtime/host-validated-args";
 import type { RunScriptOutput } from "../scripts-runtime/loader";
 import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
 import { validateJsonSchema } from "../workflows/json-schema-validator";
@@ -214,6 +215,7 @@ export async function handleX(
   // Scripts predating the schema column, or where extraction failed, have a
   // null schema — we skip and let the in-subprocess Zod check surface as a
   // runtime_error instead.
+  let hostValidatedArgs = false;
   if (script.argsJsonSchema) {
     try {
       const schema = JSON.parse(script.argsJsonSchema) as Record<string, unknown>;
@@ -227,6 +229,7 @@ export async function handleX(
         });
         return true;
       }
+      hostValidatedArgs = true;
     } catch {
       // Malformed stored schema — don't block execution on it.
     }
@@ -245,7 +248,9 @@ export async function handleX(
   const output = await runScriptWithRunCredential({
     source: script.source,
     args: args ?? null,
+    [HOST_VALIDATED_ARGS]: hostValidatedArgs,
     fsMode: "none",
+    executor: script.executor,
     agentId: endpoint.agentId,
     // timeoutMs only raises the wall-clock limit (network-bound scripts can use
     // the full window); the CPU ulimit (`ulimit -t`) is intentionally left at

package/src/integrations/chat-sdk/inbound.ts

@@ -1,5 +1,7 @@
 import type { Adapter, Message, Thread } from "chat";
 import { z } from "zod";
+import { sessionGroupKey } from "@/assets/key";
+import { sessionSourceKey } from "@/assets/source-key";
 import {
   getAgentById,
   getAgentWorkingOnContextKey,
@@ -9,6 +11,7 @@ import {
   getLeadAgent,
   isExtensionAgent,
 } from "@/be/db";
+import { rememberSessionLabel } from "@/be/db/session-labels";
 import { resolveIdentity } from "@/be/identity";
 import { recordUnmappedIdentity } from "@/be/unmapped-identities";
 import { dispatchPre } from "@/extensions/dispatcher";
@@ -373,6 +376,20 @@ async function targetFromExtension(
  * Runs outside any transaction, so `pre.chat.route` is dispatched here, after
  * the flush and before any task exists.
  */
+/**
+ * The source group label a Telegram or Discord message gives: the DM sender,
+ * or a Telegram group title. Slack labels come from the Slack lookup instead.
+ */
+function chatSourceLabel(adapter: string, item: ChatBufferedMessage): string | undefined {
+  if (adapter !== "telegram" && adapter !== "discord") return undefined;
+  const { facts } = item;
+  if (facts.chatType === "dm" || item.isDirectMessage)
+    return facts.from ? `DM · ${facts.from}` : undefined;
+  if (adapter === "telegram" && (facts.chatType === "group" || facts.chatType === "supergroup"))
+    return facts.title || undefined;
+  return undefined;
+}
+
 export async function flushChatThread(
   threadId: string,
   items: ChatBufferedMessage[],
@@ -538,6 +555,7 @@ export async function flushChatThread(
   const latestActive = await getLatestActiveTaskByContextKey(contextKey, "chat");
   const dependsOn = !immediate && latestActive ? [latestActive.id] : undefined;
   let created = 0;
+  let sourceKey: string | null = null;
   for (const match of target.matches) {
     const options: CreateTaskOptions = {
       agentId: match.agent?.id ?? null,
@@ -564,6 +582,7 @@ export async function flushChatThread(
     };
     try {
       const { task, unattached } = await createChatTaskWithFiles(description, options, inbound);
+      sourceKey ??= sessionSourceKey(task);
       created++;
       console.log(
         `[chat-sdk] ${threadId}: task ${task.id} for ${match.agent ? `agent ${match.agent.id}` : "no agent (queued)"} (${match.matchedText}, dependsOn: ${dependsOn?.join(", ") ?? "none"}${unattached.length ? `, ${unattached.length} file(s) not attached` : ""})`,
@@ -578,6 +597,14 @@ export async function flushChatThread(
       }
     }
   }
+  const label = chatSourceLabel(adapter, requester);
+  if (sourceKey && label) {
+    // Every message refreshes the label, so a renamed group shows its new title.
+    // The error may echo the label, which can hold a person's name: do not log it.
+    await rememberSessionLabel(sessionGroupKey(sourceKey), label).catch(() => {
+      console.warn("[chat-sdk] Could not save a session source label");
+    });
+  }
   if (created > 0) {
     await rememberChatThreadRequester(threadId, requester.userId);
     await subscribe(thread);

package/src/kv-reserved-namespaces.ts

@@ -12,8 +12,20 @@ const RESERVED_FAMILIES = new Map([
   ["worker", "namespace is reserved for worker nudges"],
   // Durable dedupe for SLACK_BLOCK_EXTERNAL_CHANNELS alerts (src/slack/external-channel.ts).
   ["slack-external-alert", "namespace is reserved for Slack external channel alerts"],
+  // Source group labels (src/be/db/session-labels.ts). Private, see PRIVATE_FAMILIES.
+  [
+    "session-labels",
+    "namespace is reserved for session source labels; GET /api/session-tree returns them",
+  ],
 ]);
 
+/**
+ * Reserved families that generic KV callers may not read either. Their rows
+ * hold data that another route returns only to callers with access (a
+ * source label names a private channel or a DM partner).
+ */
+const PRIVATE_FAMILIES = new Set(["session-labels"]);
+
 export function isReservedNamespace(namespace: string): boolean {
   return reservedNamespaceError(namespace) !== null;
 }
@@ -22,6 +34,13 @@ export function reservedNamespaceError(namespace: string): string | null {
   return RESERVED_FAMILIES.get(namespace.split(":", 1)[0] ?? "") ?? null;
 }
 
+/** The error a generic KV read of a private family gets, or null. */
+export function privateNamespaceError(namespace: string): string | null {
+  return PRIVATE_FAMILIES.has(namespace.split(":", 1)[0] ?? "")
+    ? reservedNamespaceError(namespace)
+    : null;
+}
+
 export function reservedRoomKeyError(key: string): string | null {
   return key.startsWith("_room/")
     ? "room snapshot keys are reserved; use the room endpoints"

package/src/prompts/base-prompt.ts

@@ -271,12 +271,22 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
       renderToolsAndSkillsVars({
         skillsSummary: args.skillsSummary,
         mcpServers: args.mcpServers,
+        // pi defers installed MCP servers together with swarm tools.
+        mcpToolsDeferred: provider === "pi" && hasToolSearch,
         nativeSkillDiscovery,
         toolDiscovery: discoveryResult.text,
         hasLocalEnv,
       }),
     );
     prompt += toolsResult.text;
+
+    // Lead docs pointer: only when the lead has the `swarm-docs` skill. The
+    // skill list is unknown on claude-managed (the cloud sandbox owns skill
+    // delivery) and before the first skill load, so render it then.
+    if (role === "lead" && hasSwarmDocsSkill(args.skillsSummary)) {
+      const docsResult = await resolveTemplateAsync("system.agent.lead.docs", {});
+      prompt += docsResult.text;
+    }
   }
 
   // J. Agent notes (CLAUDE.md), only when it differs from the generated
@@ -339,6 +349,11 @@ export const getTaskContextPrompt = async (args: TaskContextPromptArgs): Promise
   return prompt.replace(/\n{3,}/g, "\n\n").trim();
 };
 
+/** True when the skill list includes `swarm-docs`, or when the list is unknown. */
+function hasSwarmDocsSkill(skills: { name: string }[] | undefined): boolean {
+  return skills === undefined || skills.some((skill) => skill.name === "swarm-docs");
+}
+
 /**
  * Dynamic lines for `system.agent.tools_skills`. The static text lives in the
  * template so operators can override or skip the section; only the lists that
@@ -347,6 +362,7 @@ export const getTaskContextPrompt = async (args: TaskContextPromptArgs): Promise
 function renderToolsAndSkillsVars(input: {
   skillsSummary?: { name: string; description: string }[];
   mcpServers?: string[];
+  mcpToolsDeferred?: boolean;
   nativeSkillDiscovery: boolean;
   hasLocalEnv: boolean;
   toolDiscovery: string;
@@ -382,7 +398,11 @@ function renderToolsAndSkillsVars(input: {
   const servers = (input.mcpServers ?? []).filter((name) => name.trim().length > 0);
   const mcpLine =
     servers.length > 0
-      ? `Connected MCP servers: ${servers.join(", ")}. Their tools are in your tool list.\n`
+      ? `Connected MCP servers: ${servers.join(", ")}. ${
+          input.mcpToolsDeferred
+            ? "Load their tools with your harness tool search."
+            : "Their tools are in your tool list."
+        }\n`
       : "";
 
   return {

package/src/prompts/session-templates.ts

@@ -15,8 +15,9 @@
  *   G  secrets                 system.agent.secrets
  *
  * Deployment-gated blocks (E outputs, H slack, steering) and the per-agent and
- * per-task sections (tools and skills, agent notes, repository, requester
- * profile) are appended by base-prompt.ts after the composite.
+ * per-task sections (tools and skills, the lead docs pointer, agent notes,
+ * repository, requester profile) are appended by base-prompt.ts after the
+ * composite.
  *
  * Writing rules for every body: sentence case headings, one idea per sentence,
  * active voice, plain words, no em dashes, a prohibition only where no positive
@@ -109,6 +110,19 @@ Your heartbeat runbook is the \`heartbeatMd\` profile field. Edit it with \`upda
   category: "system",
 });
 
+// Lead docs pointer. base-prompt.ts appends it after the tools and skills
+// section when the lead has the `swarm-docs` skill (or when the skill list is
+// unknown). An operator override with an empty body switches it off.
+registerTemplate({
+  eventType: "system.agent.lead.docs",
+  header: "",
+  defaultBody: `
+Load the \`swarm-docs\` skill only when a person asks for something no skill, workflow, schedule or memory of yours covers, or asks where something is documented. Then follow its offer rules.
+`,
+  variables: [],
+  category: "system",
+});
+
 // Remote providers (no MCP, no container): the task arrives in the session
 // prompt and the final message is the output. No tools to name.
 registerTemplate({
@@ -168,7 +182,7 @@ registerTemplate({
 ## Memory
 
 Memories from past sessions are in your task message. Read them before you start. For a wider search, run the \`task-context-gathering\` script with the task ID and two to four queries.
-Store a learning with \`memory-store\` when you solve something that will come back: a fix, a pattern, a gotcha. Completed task outputs are stored for you.
+When you learn something that would change how the next agent works (a fix, a pattern, a gotcha), pass it as \`learning\` on a \`store-progress\` call before the task ends. Completed task outputs are stored for you.
 You MUST use the \`memory\` skill before you store, edit, or delete a memory.
 `,
   variables: [],

package/src/providers/acp-targets.ts

@@ -359,7 +359,7 @@ const copilotTargetProfile: AcpTargetProfile = {
   },
 };
 
-/** Qwen Code's `--auth-type` choices (0.26.0). `qwen-oauth` needs a browser, so it is left out. */
+/** Qwen Code's `--auth-type` choices (0.26.1). `qwen-oauth` needs a browser, so it is left out. */
 const QWEN_AUTH_TYPES = ["openai", "openai-responses", "anthropic", "gemini", "vertex-ai"] as const;
 
 // Qwen Code is a Gemini CLI fork: QWEN_SYSTEM_MD replaces its built-in prompt

package/src/providers/amp-adapter.ts

@@ -45,7 +45,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1792844927-g360c96";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1793025586-g9211b5";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";

package/src/providers/claude-adapter.ts

@@ -1445,7 +1445,11 @@ export class ClaudeAdapter implements ProviderAdapter {
     // (headless) or block on the trust dialog (tmux), so seed trust for every session.
     if (isEnvFlagEnabled("CLAUDE_TRUST_PRESEED", true, sourceEnv)) {
       try {
-        await preseedClaudeTrustDialog(await resolveClaudeTrustDirs(config.cwd));
+        // Seed the ~/.claude.json the CLI reads: its HOME comes from the session env.
+        await preseedClaudeTrustDialog(
+          await resolveClaudeTrustDirs(config.cwd),
+          sourceEnv.HOME || undefined,
+        );
       } catch (err) {
         console.warn(
           `\x1b[33m[claude]\x1b[0m ${scrubSecrets(`Failed to pre-seed trust for ${config.cwd}: ${err}`)}`,

package/src/providers/claude-managed-adapter.ts

@@ -64,6 +64,7 @@ import {
   computeContextUsedUnified,
   getContextWindowSize,
 } from "../utils/context-window";
+import { selectCredential } from "../utils/credentials";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { computeClaudeManagedCostUsd } from "./claude-managed-models";
 import { getRuntimeFeePerHour } from "./claude-managed-pricing";
@@ -862,7 +863,11 @@ export class ClaudeManagedAdapter implements ProviderAdapter {
       );
     }
 
-    this.apiKey = process.env.ANTHROPIC_API_KEY as string;
+    this.apiKey = selectCredential(
+      process.env.ANTHROPIC_API_KEY as string,
+      undefined,
+      "ANTHROPIC_API_KEY",
+    ).selected;
     this.agentId = process.env.MANAGED_AGENT_ID as string;
     this.environmentId = process.env.MANAGED_ENVIRONMENT_ID as string;
 
@@ -879,6 +884,14 @@ export class ClaudeManagedAdapter implements ProviderAdapter {
   }
 
   async createSession(config: ProviderSessionConfig): Promise<ProviderSession> {
+    // Keep the runner's task selection instead of the container's pool.
+    const taskKey = config.env?.ANTHROPIC_API_KEY;
+    const client =
+      taskKey && this.client instanceof Anthropic
+        ? this.client.withOptions({
+            apiKey: selectCredential(taskKey, undefined, "ANTHROPIC_API_KEY").selected,
+          })
+        : this.client;
     // Native resume is deprecated. Follow-up continuity is delivered via the
     // context preamble (see src/commands/context-preamble.ts). Any stray
     // resumeSessionId is logged and ignored — we always create a fresh session.
@@ -942,16 +955,10 @@ export class ClaudeManagedAdapter implements ProviderAdapter {
     if (vaultIds.length > 0) {
       createParams.vault_ids = Array.from(new Set(vaultIds));
     }
-    const created = await Promise.resolve(this.client.beta.sessions.create(createParams));
+    const created = await Promise.resolve(client.beta.sessions.create(createParams));
     const sessionId = created.id;
 
-    return new ClaudeManagedSession(
-      this.client,
-      sessionId,
-      config,
-      userMessageContent,
-      seenEventIds,
-    );
+    return new ClaudeManagedSession(client, sessionId, config, userMessageContent, seenEventIds);
   }
 
   /**