@desplega.ai/agent-swarm 1.52.0 → 1.52.1

package/README.md

@@ -56,6 +56,8 @@ Agent Swarm lets you run a team of AI coding agents that coordinate autonomously
 - **Linear integration** — Bidirectional ticket tracker sync via OAuth + webhooks with AgentSession lifecycle and generic tracker abstraction
 - **Portless local dev** — Friendly URLs for local development (`api.swarm.localhost:1355`) via portless proxy
 - **Onboarding wizard** — Interactive CLI wizard (`agent-swarm onboard`) to set up a new swarm from scratch with presets, credential collection, and docker-compose generation
+- **Skill system** — Reusable procedural knowledge: create, install, publish, and sync skills from GitHub with scope resolution (agent → swarm → global)
+- **Human-in-the-Loop** — Workflow nodes that pause for human approval or input, with a dashboard UI for reviewing and responding to requests
 
 ## Quick Start
 
@@ -262,6 +264,135 @@ GITHUB_APP_PRIVATE_KEY=base64-encoded-key
 | PR review submitted (on bot's PR) | Creates a notification task with review feedback |
 | CI failure (on PRs with existing tasks) | Creates a CI notification task |
 
+<details>
+<summary><strong>Flow Diagrams</strong> (click to expand)</summary>
+
+#### Task Creation Flow
+
+How GitHub events become tasks in the swarm:
+
+```mermaid
+%%{init: {'theme': 'dark', 'themeVariables': {'fontSize': '13px', 'nodeSpacing': 30, 'rankSpacing': 40}}}%%
+flowchart TB
+    subgraph ENTRY["1. GitHub Webhook Entry Points"]
+        direction LR
+        E1["Issue<br/>opened/edited"]
+        E2["PR<br/>opened/edited"]
+        E3["Comment<br/>created"]
+        E4["Bot Assigned<br/>to Issue/PR"]
+        E5["Review Requested<br/>from Bot"]
+    end
+
+    subgraph GATE["2. Trigger Gate"]
+        M{"@agent-swarm<br/>mention?"}
+        A{"Bot is<br/>assignee?"}
+        D{"Duplicate?<br/>60s TTL"}
+    end
+
+    subgraph CREATE["3. Task Creation"]
+        LEAD["Find Lead Agent<br/>(online > offline > none)"]
+        TPL["resolveTemplate()"]
+        TASK["createTaskExtended()"]
+    end
+
+    subgraph OUT["4. Output"]
+        ASSIGN["Task assigned<br/>to Lead"]
+        POOL["Task in pool<br/>(no lead)"]
+        REACT["eyes reaction<br/>on GitHub"]
+    end
+
+    E1 & E2 & E3 --> M
+    E4 & E5 --> A
+
+    M -->|Yes| D
+    A -->|Yes| D
+    M & A -->|No| DROP1(("skip"))
+
+    D -->|New| LEAD
+    D -->|Dup| DROP2(("skip"))
+
+    LEAD --> TPL --> TASK
+
+    TASK -->|lead found| ASSIGN
+    TASK -.->|no lead| POOL
+    TASK --> REACT
+```
+
+[PNG fallback](assets/github-task-creation-flow.png)
+
+#### Follow-up Flows
+
+Events that create secondary tasks when an active task already exists for a PR:
+
+```mermaid
+%%{init: {'theme': 'dark', 'themeVariables': {'fontSize': '13px'}}}%%
+flowchart TB
+    subgraph EVENTS["GitHub Follow-up Events (require existing active task)"]
+        direction LR
+        F1["PR Closed<br/>(merged/closed)"]
+        F2["PR Synchronize<br/>(new commits)"]
+        F3["Review Submitted<br/>(approved/changes_requested)"]
+        F4["Check Run Failed"]
+        F5["Check Suite Failed"]
+        F6["Workflow Run Failed"]
+    end
+
+    FIND{"findTaskByVcs()<br/>Active task for<br/>repo + PR number?"}
+
+    EVENTS --> FIND
+
+    FIND -->|No task| SKIP(("skip"))
+
+    subgraph FOLLOWUP["Follow-up Task Created (assigned to Lead)"]
+        direction LR
+        T1["github-pr-status<br/>PR merged/closed"]
+        T2["github-pr-update<br/>New commits pushed"]
+        T3["github-review<br/>Review feedback"]
+        T4["github-ci<br/>CI failure alert"]
+    end
+
+    F1 --> FIND -->|task found| T1
+    F2 --> FIND -->|task found| T2
+    F3 --> FIND -->|task found| T3
+    F4 & F5 & F6 --> FIND -->|task found| T4
+
+    NOTE["All follow-up tasks reference<br/>the original task ID for routing"]
+
+    FOLLOWUP --> NOTE
+```
+
+[PNG fallback](assets/github-followup-flows.png)
+
+#### Cancellation Flows
+
+How unassigning the bot cancels active tasks:
+
+```mermaid
+%%{init: {'theme': 'dark', 'themeVariables': {'fontSize': '13px'}}}%%
+flowchart TB
+    subgraph EVENTS["Cancellation Events"]
+        direction LR
+        C1["Bot Unassigned<br/>from Issue"]
+        C2["Bot Unassigned<br/>from PR"]
+        C3["Review Request<br/>Removed from Bot"]
+    end
+
+    BOT{"isBotAssignee()"}
+    FIND{"findTaskByVcs()<br/>Active task?"}
+    CANCEL["failTask()<br/>Cancel with reason"]
+    NOOP(("no-op"))
+
+    EVENTS --> BOT
+    BOT -->|Not bot| NOOP
+    BOT -->|Is bot| FIND
+    FIND -->|No task| NOOP
+    FIND -->|Task found| CANCEL
+```
+
+[PNG fallback](assets/github-cancellation-flows.png)
+
+</details>
+
 ### GitLab
 
 Set up a GitLab webhook to receive events when the bot is @mentioned or assigned to issues/MRs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.52.0",
+  "version": "1.52.1",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -74,6 +74,7 @@
     "e2e:workflows:docker": "bun scripts/e2e-workflow-test.ts --with-docker",
     "docs:mcp": "bun scripts/generate-mcp-docs.ts",
     "docs:openapi": "bun scripts/generate-openapi.ts",
+    "docs:business-use": "bun scripts/generate-business-use-docs.ts",
     "pm2-start": "pm2 start ecosystem.config.cjs",
     "pm2-stop": "pm2 stop ecosystem.config.cjs",
     "pm2-restart": "pm2 restart ecosystem.config.cjs",
@@ -93,6 +94,7 @@
   "dependencies": {
     "@ai-sdk/openai": "^3.0.41",
     "@asteasolutions/zod-to-openapi": "^8.0.0",
+    "@desplega.ai/business-use": "^0.4.2",
     "@desplega.ai/localtunnel": "^2.2.0",
     "@inkjs/ui": "^2.0.0",
     "@linear/sdk": "^77.0.0",

package/src/be/db.ts

@@ -940,6 +940,23 @@ export function getTasksByAgentId(agentId: string): AgentTask[] {
   return taskQueries.getByAgentId().all(agentId).map(rowToAgentTask);
 }
 
+/**
+ * Get the most recently updated in-progress task for an agent.
+ * Used as a fallback when X-Source-Task-Id header is missing (e.g. lead agent HITL requests).
+ *
+ * Note: if agent has multiple in-progress tasks, returns the most recently
+ * updated one. This is a best-effort fallback — the X-Source-Task-Id header
+ * is the authoritative source when available.
+ */
+export function getAgentCurrentTask(agentId: string): AgentTask | null {
+  const row = getDb()
+    .prepare<AgentTaskRow, [string]>(
+      "SELECT * FROM agent_tasks WHERE agentId = ? AND status = 'in_progress' ORDER BY lastUpdatedAt DESC LIMIT 1",
+    )
+    .get(agentId);
+  return row ? rowToAgentTask(row) : null;
+}
+
 export function getTasksByStatus(status: AgentTaskStatus): AgentTask[] {
   return taskQueries.getByStatus().all(status).map(rowToAgentTask);
 }
@@ -6881,6 +6898,16 @@ export function resolveApprovalRequest(
   return row ? rowToApprovalRequest(row) : null;
 }
 
+export function updateApprovalRequestNotifications(
+  id: string,
+  notificationChannels: Array<{ channel: string; target: string; messageTs?: string }>,
+): void {
+  const now = new Date().toISOString();
+  getDb()
+    .prepare("UPDATE approval_requests SET notificationChannels = ?, updatedAt = ? WHERE id = ?")
+    .run(JSON.stringify(notificationChannels), now, id);
+}
+
 export function listApprovalRequests(filters?: {
   status?: string;
   workflowRunId?: string;

package/src/be/migrations/runner.ts

@@ -129,7 +129,7 @@ export function runMigrations(db: Database): void {
     const initialMigration = migrations.find((m) => m.version === 1);
     if (initialMigration) {
       if (shouldBootstrapInitialMigration(db)) {
-        console.log("[migrations] Existing database detected — bootstrapping migration tracking");
+        console.debug("[migrations] Existing database detected — bootstrapping migration tracking");
         db.run(
           "INSERT INTO _migrations (version, name, applied_at, checksum) VALUES (?, ?, ?, ?)",
           [
@@ -145,7 +145,7 @@ export function runMigrations(db: Database): void {
           checksum: initialMigration.checksum,
         });
       } else {
-        console.log(
+        console.warn(
           "[migrations] Existing database appears incomplete — applying 001_initial migration",
         );
       }
@@ -169,7 +169,7 @@ export function runMigrations(db: Database): void {
     }
 
     // Apply migration in a transaction
-    console.log(`[migrations] Applying: ${migration.name}`);
+    console.debug(`[migrations] Applying: ${migration.name}`);
     const start = performance.now();
 
     db.transaction(() => {
@@ -183,6 +183,6 @@ export function runMigrations(db: Database): void {
     })();
 
     const elapsed = (performance.now() - start).toFixed(1);
-    console.log(`[migrations] Applied: ${migration.name} (${elapsed}ms)`);
+    console.debug(`[migrations] Applied: ${migration.name} (${elapsed}ms)`);
   }
 }

package/src/commands/runner.ts

@@ -1,5 +1,6 @@
 import { existsSync, statSync } from "node:fs";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { ensure, initialize } from "@desplega.ai/business-use";
 import type { TemplateResponse } from "../../templates/schema.ts";
 import { type BasePromptArgs, getBasePrompt } from "../prompts/base-prompt.ts";
 import {
@@ -215,10 +216,94 @@ async function fetchResolvedEnv(
   return env;
 }
 
+/** Tools that produce noise — skip auto-progress for these */
+const SKIP_PROGRESS_TOOLS = new Set(["ToolSearch", "TodoRead", "TodoWrite"]);
+
+/** Pretty labels for agent-swarm MCP tools. null = skip (meta/noise). */
+const SWARM_TOOL_LABELS: Record<string, string | null> = {
+  "store-progress": null,
+  "get-task-details": "📋 Reviewing task details",
+  "get-tasks": "📋 Checking task list",
+  "poll-task": "📡 Polling for tasks",
+  "send-task": "📤 Delegating task",
+  "task-action": "⚡ Performing task action",
+  "join-swarm": "🔗 Joining swarm",
+  "my-agent-info": "🪪 Checking agent info",
+  "get-swarm": "👥 Checking swarm status",
+  "post-message": "💬 Sending message",
+  "read-messages": "💬 Reading messages",
+  "request-human-input": "🙋 Requesting human input",
+  "cancel-task": "🚫 Cancelling task",
+  "db-query": "🗃️ Querying database",
+  "inject-learning": "🧠 Storing learning",
+  "memory-search": "🧠 Searching memory",
+  "memory-get": "🧠 Retrieving memory",
+  "update-profile": "🪪 Updating profile",
+  // Slack
+  "slack-post": "💬 Posting to Slack",
+  "slack-reply": "💬 Replying in Slack",
+  "slack-read": "💬 Reading Slack",
+  "slack-list-channels": "💬 Listing Slack channels",
+  "slack-download-file": "📥 Downloading from Slack",
+  "slack-upload-file": "📤 Uploading to Slack",
+  // Tracker
+  "tracker-status": "📊 Checking tracker status",
+  "tracker-sync-status": "📊 Syncing tracker status",
+  "tracker-link-task": "🔗 Linking task to tracker",
+  "tracker-link-epic": "🔗 Linking epic to tracker",
+  "tracker-unlink": "🔗 Unlinking from tracker",
+  "tracker-map-agent": "🔗 Mapping agent to tracker",
+  // Epics
+  "create-epic": "📦 Creating epic",
+  "get-epic-details": "📦 Reviewing epic",
+  "list-epics": "📦 Listing epics",
+  "update-epic": "📦 Updating epic",
+  // Workflows
+  "trigger-workflow": "⚙️ Triggering workflow",
+  "get-workflow": "⚙️ Checking workflow",
+  "list-workflows": "⚙️ Listing workflows",
+  "create-workflow": "⚙️ Creating workflow",
+  // Skills
+  "skill-search": "🔎 Searching skills",
+  "skill-install": "📦 Installing skill",
+  "skill-install-remote": "📦 Installing remote skill",
+  "skill-get": "📦 Getting skill details",
+  "skill-list": "📦 Listing skills",
+  // Config
+  "get-config": "⚙️ Reading config",
+  "set-config": "⚙️ Setting config",
+  "list-config": "⚙️ Listing config",
+  // Schedules
+  "create-schedule": "📅 Creating schedule",
+  "list-schedules": "📅 Listing schedules",
+  "run-schedule-now": "📅 Running schedule",
+  // Context
+  "context-diff": "📜 Viewing context diff",
+  "context-history": "📜 Viewing context history",
+  // Channels
+  "create-channel": "📢 Creating channel",
+  "list-channels": "📢 Listing channels",
+  "delete-channel": "📢 Deleting channel",
+  // Services
+  "register-service": "🔌 Registering service",
+  "list-services": "🔌 Listing services",
+  "unregister-service": "🔌 Unregistering service",
+  "update-service-status": "🔌 Updating service status",
+};
+
+/** Convert kebab-case to sentence case: "get-task-details" → "Get task details" */
+export function humanizeToolName(name: string): string {
+  if (!name) return name;
+  return name.charAt(0).toUpperCase() + name.slice(1).replaceAll("-", " ");
+}
+
 /**
  * Convert a tool call into a human-readable progress description.
+ * Returns null for noisy/meta tools that should be skipped.
  */
-function toolCallToProgress(toolName: string, args: unknown): string {
+export function toolCallToProgress(toolName: string, args: unknown): string | null {
+  if (SKIP_PROGRESS_TOOLS.has(toolName)) return null;
+
   const a = args as Record<string, unknown>;
   const shortPath = (p: unknown) => {
     if (typeof p !== "string") return "";
@@ -229,30 +314,43 @@ function toolCallToProgress(toolName: string, args: unknown): string {
 
   switch (toolName) {
     case "Read":
-      return `Reading ${shortPath(a.file_path)}`;
+      return `📖 Reading ${shortPath(a.file_path)}`;
     case "Edit":
     case "MultiEdit":
-      return `Editing ${shortPath(a.file_path)}`;
+      return `✏️ Editing ${shortPath(a.file_path)}`;
     case "Write":
-      return `Writing ${shortPath(a.file_path)}`;
+      return `📝 Writing ${shortPath(a.file_path)}`;
     case "Bash":
-      return a.description ? `${a.description}` : "Running shell command";
+      return a.description ? `⚡ ${a.description}` : "⚡ Running shell command";
     case "Grep":
-      return `Searching for "${a.pattern}"`;
+      return `🔍 Searching for "${a.pattern}"`;
     case "Glob":
-      return `Finding files matching ${a.pattern}`;
+      return `📁 Finding files matching ${a.pattern}`;
     case "Agent":
     case "Task":
-      return a.description ? `${a.description}` : "Delegating sub-task";
+      return a.description ? `🤖 ${a.description}` : "🤖 Delegating sub-task";
     case "Skill":
-      return `Running /${a.skill}`;
+      return `⚙️ Running /${a.skill}`;
     default: {
-      // MCP tools: mcp__server__tool → "server:tool"
+      // MCP tools: mcp__server__tool
       if (toolName.startsWith("mcp__")) {
         const parts = toolName.split("__");
-        return parts.length >= 3 ? `Using ${parts[1]}:${parts[2]}` : `Using ${toolName}`;
+        if (parts.length >= 3) {
+          const server = parts[1];
+          const tool = parts.slice(2).join("__");
+          // Agent-swarm tools get pretty labels
+          if (server === "agent-swarm") {
+            const label = SWARM_TOOL_LABELS[tool];
+            if (label === null) return null; // skip
+            if (label) return label;
+            return `🔌 ${humanizeToolName(tool)}`;
+          }
+          // Other MCP servers: "🔌 server: Humanized tool"
+          return `🔌 ${server}: ${humanizeToolName(tool)}`;
+        }
+        return `🔌 ${toolName}`;
       }
-      return `Using ${toolName}`;
+      return `🔧 ${toolName}`;
     }
   }
 }
@@ -1369,9 +1467,13 @@ async function spawnProviderProcess(
         // Auto-progress: report tool activity as task progress (throttled)
         const now = Date.now();
         if (effectiveTaskId && opts.apiUrl && now - lastProgressTime >= PROGRESS_THROTTLE_MS) {
-          lastProgressTime = now;
           const progress = toolCallToProgress(event.toolName, event.args);
-          updateProgressViaAPI(opts.apiUrl, opts.apiKey, effectiveTaskId, progress).catch(() => {});
+          if (progress) {
+            lastProgressTime = now;
+            updateProgressViaAPI(opts.apiUrl, opts.apiKey, effectiveTaskId, progress).catch(
+              () => {},
+            );
+          }
         }
         break;
       }
@@ -1579,6 +1681,22 @@ async function checkCompletedProcesses(
       }
       await ensureTaskFinished(apiConfig, role, taskId, result.exitCode, failureReason);
 
+      ensure({
+        id: "worker_process_finished",
+        flow: "task",
+        runId: taskId,
+        depIds: ["worker_process_spawned"],
+        data: {
+          taskId,
+          agentId: apiConfig.agentId,
+          role,
+          exitCode: result.exitCode,
+          success: result.exitCode === 0,
+          failureReason,
+        },
+        validator: (data) => data.exitCode === 0,
+      });
+
       // Commit channel activity cursors after successful processing
       // If the task failed, cursors stay uncommitted so messages are re-seen on next poll
       if (cursorUpdates && cursorUpdates.length > 0 && result.exitCode === 0) {
@@ -1665,6 +1783,9 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   const { defaultPrompt, metadataType } = config;
   let role = config.role;
 
+  // Initialize Business-Use SDK for worker-side instrumentation
+  initialize();
+
   // Create provider adapter based on HARNESS_PROVIDER env var (default: claude)
   const adapter = createProviderAdapter(process.env.HARNESS_PROVIDER || "claude");
 
@@ -2308,6 +2429,24 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
         if (trigger) {
           console.log(`[${role}] Trigger received: ${trigger.type}`);
 
+          if (
+            trigger.taskId &&
+            (trigger.type === "task_assigned" || trigger.type === "task_offered")
+          ) {
+            ensure({
+              id: "worker_received",
+              flow: "task",
+              runId: trigger.taskId,
+              depIds: ["started"],
+              data: {
+                taskId: trigger.taskId,
+                agentId,
+                triggerType: trigger.type,
+                role,
+              },
+            });
+          }
+
           // Build prompt based on trigger
           let triggerPrompt = await buildPromptForTrigger(
             trigger,
@@ -2524,6 +2663,19 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
             continue;
           }
 
+          ensure({
+            id: "worker_process_spawned",
+            flow: "task",
+            runId: runningTask.taskId,
+            depIds: ["worker_received"],
+            data: {
+              taskId: runningTask.taskId,
+              agentId,
+              role,
+              model: taskModel,
+            },
+          });
+
           // Attach trigger metadata for logging
           runningTask.triggerType = trigger.type;
 

package/src/http/agents.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { ensure } from "@desplega.ai/business-use";
 import { z } from "zod";
 import {
   createAgent,
@@ -179,6 +180,34 @@ export async function handleAgentRegister(
       return { agent, created: true };
     })();
 
+    if (result.created) {
+      ensure({
+        id: "registered",
+        flow: "agent",
+        runId: agentId,
+        data: {
+          agentId,
+          name: parsed.body.name,
+          isLead: parsed.body.isLead ?? false,
+        },
+      });
+    } else {
+      ensure({
+        id: "reconnected",
+        flow: "agent",
+        runId: agentId,
+        depIds: ["registered"],
+        data: {
+          agentId,
+          name: parsed.body.name,
+        },
+        validator: (_data, ctx) => {
+          // Validates that registered happened before reconnected
+          return ctx.deps.length > 0;
+        },
+      });
+    }
+
     json(res, result.agent, result.created ? 201 : 200);
     return true;
   }

package/src/http/approval-requests.ts

@@ -2,10 +2,13 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import {
   createApprovalRequest,
+  createTaskExtended,
   getApprovalRequestById,
+  getTaskById,
   listApprovalRequests,
   resolveApprovalRequest,
 } from "../be/db";
+import { resolveTemplate } from "../prompts/resolver";
 import { workflowEventBus } from "../workflows/event-bus";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
@@ -186,6 +189,40 @@ export async function handleApprovalRequests(
       });
     }
 
+    // For standalone (non-workflow) requests, create a follow-up task
+    // so the requesting agent is notified of the human's response
+    if (!updated.workflowRunId && updated.sourceTaskId) {
+      const sourceTask = getTaskById(updated.sourceTaskId);
+      if (sourceTask) {
+        // Format responses for the template
+        const formattedResponses = formatResponses(
+          updated.questions as Array<{ id: string; type: string; label: string }>,
+          updated.responses as Record<string, unknown>,
+        );
+
+        const { text: taskText } = resolveTemplate("hitl.follow_up", {
+          request_id: updated.id,
+          title: updated.title,
+          status: updated.status,
+          responses: formattedResponses,
+        });
+
+        createTaskExtended(taskText, {
+          agentId: sourceTask.agentId,
+          parentTaskId: updated.sourceTaskId,
+          source: "system",
+          taskType: "hitl-follow-up",
+          tags: ["hitl", "follow-up"],
+          // Explicit Slack metadata — parentTaskId auto-inherits too,
+          // but being explicit ensures the follow-up task always gets
+          // the right thread context even if inheritance logic changes.
+          slackChannelId: sourceTask.slackChannelId ?? undefined,
+          slackThreadTs: sourceTask.slackThreadTs ?? undefined,
+          slackUserId: sourceTask.slackUserId ?? undefined,
+        });
+      }
+    }
+
     json(res, { approvalRequest: updated });
     return true;
   }
@@ -245,3 +282,29 @@ export async function handleApprovalRequests(
 
   return false;
 }
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function formatResponses(
+  questions: Array<{ id: string; type: string; label: string }>,
+  responses: Record<string, unknown>,
+): string {
+  return questions
+    .map((q) => {
+      const answer = responses[q.id];
+      let answerText: string;
+      if (answer == null) {
+        answerText = "(no answer)";
+      } else if (q.type === "approval") {
+        const a = answer as { approved?: boolean; comment?: string };
+        answerText = a.approved ? "Approved" : "Rejected";
+        if (a.comment) answerText += ` — ${a.comment}`;
+      } else if (typeof answer === "object") {
+        answerText = JSON.stringify(answer);
+      } else {
+        answerText = String(answer);
+      }
+      return `- ${q.label}: ${answerText}`;
+    })
+    .join("\n");
+}

package/src/http/index.ts

@@ -4,8 +4,9 @@ import {
   type Server,
   type ServerResponse,
 } from "node:http";
+import { assert, initialize } from "@desplega.ai/business-use";
 import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { hasCapability } from "@/server";
+import { getEnabledCapabilities, hasCapability } from "@/server";
 import { initAgentMail } from "../agentmail";
 import { closeDb } from "../be/db";
 import { initGitHub } from "../github";
@@ -45,6 +46,7 @@ const globalState = globalThis as typeof globalThis & {
   __httpServer?: Server<typeof IncomingMessage, typeof ServerResponse>;
   __transports?: Record<string, StreamableHTTPServerTransport>;
   __sigintRegistered?: boolean;
+  __runId?: string;
 };
 
 // Clean up previous server on hot reload
@@ -167,10 +169,26 @@ if (!globalState.__sigintRegistered) {
   process.on("SIGTERM", shutdown);
 }
 
+if (!globalState.__runId) {
+  globalState.__runId = `run_${Date.now()}`;
+}
+
+// business-use initialization (no-op if envs not set)
+initialize();
+
 httpServer
   .listen(port, async () => {
     console.log(`MCP HTTP server running on http://localhost:${port}/mcp`);
 
+    assert({
+      id: "listen",
+      flow: "api",
+      runId: globalState.__runId!,
+      data: {
+        capabilities: getEnabledCapabilities(),
+      },
+    });
+
     // Load global swarm configs into process.env (so integrations can read them)
     // Infrastructure-level env vars take precedence — only missing keys are filled.
     try {
@@ -205,7 +223,9 @@ httpServer
       const { startScheduler } = await import("../scheduler");
       const { getExecutorRegistry } = await import("../workflows");
       const intervalMs = Number(process.env.SCHEDULER_INTERVAL_MS) || 10000;
-      startScheduler(getExecutorRegistry(), intervalMs);
+      startScheduler(getExecutorRegistry(), intervalMs, {
+        runId: globalState.__runId!,
+      });
     }
 
     // Start heartbeat triage (unless disabled)