@desplega.ai/agent-swarm 1.56.2 → 1.56.3

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.55.0",
+    "version": "1.56.3",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -509,6 +509,10 @@
                     "type": "string",
                     "maxLength": 65536
                   },
+                  "heartbeatMd": {
+                    "type": "string",
+                    "maxLength": 65536
+                  },
                   "changeSource": {
                     "type": "string"
                   },
@@ -1911,6 +1915,27 @@
         }
       }
     },
+    "/api/heartbeat/checklist": {
+      "post": {
+        "summary": "Trigger an immediate heartbeat checklist check",
+        "tags": [
+          "Heartbeat"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Checklist check completed successfully"
+          },
+          "401": {
+            "description": "Unauthorized"
+          }
+        }
+      }
+    },
     "/api/memory/index": {
       "post": {
         "summary": "Ingest content into memory system (async embedding)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.56.2",
+  "version": "1.56.3",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/github/handlers.ts

@@ -1,6 +1,12 @@
 import { createTaskExtended, failTask, findTaskByVcs, getAllAgents } from "../be/db";
 import { resolveTemplate } from "../prompts/resolver";
-import { detectMention, extractMentionContext, GITHUB_BOT_NAME, isBotAssignee } from "./mentions";
+import {
+  detectMention,
+  extractMentionContext,
+  GITHUB_BOT_NAME,
+  isBotAssignee,
+  isSwarmLabel,
+} from "./mentions";
 import { addIssueReaction, addReaction } from "./reactions";
 // Side-effect import: registers all GitHub event templates in the in-memory registry
 import "./templates";
@@ -315,42 +321,32 @@ export async function handlePullRequest(
     return { created: false };
   }
 
-  // Handle closed action - PR was merged or closed without merge
-  if (action === "closed") {
-    // Find the related task
-    const task = findTaskByVcs(repository.full_name, pr.number);
-    if (!task) {
-      // No task for this PR, nothing to notify
+  // Handle labeled action - swarm label added to PR
+  if (action === "labeled") {
+    const labelName = event.label?.name;
+    if (!labelName || !isSwarmLabel(labelName)) {
       return { created: false };
     }
 
     // Deduplicate
-    const eventKey = `pr-closed:${repository.full_name}:${pr.number}`;
+    const eventKey = `pr-labeled:${repository.full_name}:${pr.number}:${labelName}`;
     if (isDuplicate(eventKey)) {
       return { created: false };
     }
 
     const lead = findLeadAgent();
-    const wasMerged = pr.merged;
-    const emoji = wasMerged ? "🎉" : "❌";
-    const status = wasMerged ? "MERGED" : "CLOSED";
-    const mergedBy = wasMerged && pr.merged_by ? ` by ${pr.merged_by.login}` : "";
-    const followUpSuggestion = wasMerged
-      ? "💡 PR successfully merged! Update any related issues or documentation."
-      : "💡 PR was closed without merging. Review if follow-up is needed.";
-
     const result = resolveTemplate(
-      "github.pull_request.closed",
+      "github.pull_request.labeled",
       {
-        status_emoji: emoji,
         pr_number: pr.number,
-        status,
-        merged_by: mergedBy,
         pr_title: pr.title,
+        label_name: labelName,
+        sender_login: sender.login,
         repo_full_name: repository.full_name,
+        head_ref: pr.head.ref,
+        base_ref: pr.base.ref,
         pr_url: pr.html_url,
-        related_task_id: task.id,
-        follow_up_suggestion: followUpSuggestion,
+        context: pr.body || pr.title,
       },
       { agentId: lead?.id, repoId: repository.full_name },
     );
@@ -359,11 +355,11 @@ export async function handlePullRequest(
       return { created: false };
     }
 
-    const notifyTask = createTaskExtended(result.text, {
+    const task = createTaskExtended(result.text, {
       agentId: lead?.id ?? "",
       source: "github",
       vcsProvider: "github",
-      taskType: "github-pr-status",
+      taskType: "github-pr",
       vcsRepo: repository.full_name,
       vcsEventType: "pull_request",
       vcsNumber: pr.number,
@@ -371,64 +367,37 @@ export async function handlePullRequest(
       vcsUrl: pr.html_url,
     });
 
-    console.log(
-      `[GitHub] Created task ${notifyTask.id} for PR #${pr.number} (${status}) -> ${lead?.name ?? "unassigned"}`,
-    );
-
-    return { created: true, taskId: notifyTask.id };
-  }
-
-  // Handle synchronize action - new commits pushed to PR
-  if (action === "synchronize") {
-    // Find the related task
-    const task = findTaskByVcs(repository.full_name, pr.number);
-    if (!task) {
-      // No task for this PR, nothing to notify
-      return { created: false };
-    }
-
-    // Deduplicate using SHA to avoid duplicate notifications for same push
-    const eventKey = `pr-sync:${repository.full_name}:${pr.number}:${pr.head.sha}`;
-    if (isDuplicate(eventKey)) {
-      return { created: false };
+    if (lead) {
+      console.log(
+        `[GitHub] Created task ${task.id} for PR #${pr.number} (labeled: ${labelName}) -> ${lead.name}`,
+      );
+    } else {
+      console.log(
+        `[GitHub] Created unassigned task ${task.id} for PR #${pr.number} (labeled: ${labelName}, no lead available)`,
+      );
     }
 
-    const lead = findLeadAgent();
-    const result = resolveTemplate(
-      "github.pull_request.synchronize",
-      {
-        pr_number: pr.number,
-        pr_title: pr.title,
-        repo_full_name: repository.full_name,
-        head_ref: pr.head.ref,
-        head_sha_short: pr.head.sha.substring(0, 7),
-        pr_url: pr.html_url,
-        related_task_id: task.id,
-      },
-      { agentId: lead?.id, repoId: repository.full_name },
-    );
-
-    if (result.skipped) {
-      return { created: false };
+    if (installation?.id) {
+      addIssueReaction(repository.full_name, pr.number, "eyes", installation.id);
     }
 
-    const notifyTask = createTaskExtended(result.text, {
-      agentId: lead?.id ?? "",
-      source: "github",
-      vcsProvider: "github",
-      taskType: "github-pr-update",
-      vcsRepo: repository.full_name,
-      vcsEventType: "pull_request",
-      vcsNumber: pr.number,
-      vcsAuthor: sender.login,
-      vcsUrl: pr.html_url,
-    });
+    return { created: true, taskId: task.id };
+  }
 
+  // Suppressed: see thoughts/taras/plans/2026-03-30-github-event-safety-defaults.md
+  if (action === "closed") {
     console.log(
-      `[GitHub] Created task ${notifyTask.id} for PR #${pr.number} (synchronize) -> ${lead?.name ?? "unassigned"}`,
+      `[GitHub:suppressed] pull_request.closed on ${repository.full_name}#${pr.number} — lifecycle events disabled by default`,
     );
+    return { created: false };
+  }
 
-    return { created: true, taskId: notifyTask.id };
+  // Suppressed: see thoughts/taras/plans/2026-03-30-github-event-safety-defaults.md
+  if (action === "synchronize") {
+    console.log(
+      `[GitHub:suppressed] pull_request.synchronize on ${repository.full_name}#${pr.number} — lifecycle events disabled by default`,
+    );
+    return { created: false };
   }
 
   // Only handle opened/edited actions for mention-based flow
@@ -595,6 +564,67 @@ export async function handleIssue(
     return { created: false };
   }
 
+  // Handle labeled action - swarm label added to issue
+  if (action === "labeled") {
+    const labelName = event.label?.name;
+    if (!labelName || !isSwarmLabel(labelName)) {
+      return { created: false };
+    }
+
+    // Deduplicate
+    const eventKey = `issue-labeled:${repository.full_name}:${issue.number}:${labelName}`;
+    if (isDuplicate(eventKey)) {
+      return { created: false };
+    }
+
+    const lead = findLeadAgent();
+    const result = resolveTemplate(
+      "github.issue.labeled",
+      {
+        issue_number: issue.number,
+        issue_title: issue.title,
+        label_name: labelName,
+        sender_login: sender.login,
+        repo_full_name: repository.full_name,
+        issue_url: issue.html_url,
+        context: issue.body || issue.title,
+      },
+      { agentId: lead?.id, repoId: repository.full_name },
+    );
+
+    if (result.skipped) {
+      return { created: false };
+    }
+
+    const task = createTaskExtended(result.text, {
+      agentId: lead?.id ?? "",
+      source: "github",
+      vcsProvider: "github",
+      taskType: "github-issue",
+      vcsRepo: repository.full_name,
+      vcsEventType: "issues",
+      vcsNumber: issue.number,
+      vcsAuthor: sender.login,
+      vcsUrl: issue.html_url,
+    });
+
+    if (lead) {
+      console.log(
+        `[GitHub] Created task ${task.id} for issue #${issue.number} (labeled: ${labelName}) -> ${lead.name}`,
+      );
+    } else {
+      console.log(
+        `[GitHub] Created unassigned task ${task.id} for issue #${issue.number} (labeled: ${labelName}, no lead available)`,
+      );
+    }
+
+    if (installation?.id) {
+      addIssueReaction(repository.full_name, issue.number, "eyes", installation.id);
+    }
+
+    return { created: true, taskId: task.id };
+  }
+
   // Only handle opened/edited actions for mention-based flow
   if (action !== "opened" && action !== "edited") {
     return { created: false };
@@ -770,103 +800,13 @@ export async function handleComment(
 export async function handlePullRequestReview(
   event: PullRequestReviewEvent,
 ): Promise<{ created: boolean; taskId?: string }> {
-  const { action, review, pull_request: pr, repository, sender, installation } = event;
+  const { action, pull_request: pr, repository } = event;
 
-  // Only handle submitted reviews (the most important action)
-  // Edited reviews are less common and dismissed is handled by the state
-  if (action !== "submitted") {
-    return { created: false };
-  }
-
-  // Skip "commented" reviews that are empty - these are often just line comments
-  // without an overall review body
-  if (review.state === "commented" && !review.body) {
-    return { created: false };
-  }
-
-  // Deduplicate
-  const eventKey = `pr-review:${repository.full_name}:${pr.number}:${review.id}`;
-  if (isDuplicate(eventKey)) {
-    return { created: false };
-  }
-
-  // Find any existing task for this PR
-  const existingTask = findTaskByVcs(repository.full_name, pr.number);
-
-  // Only notify for PRs where bot is creator or already has a task
-  const isBotCreator = isBotAssignee(pr.user.login);
-  if (!isBotCreator && !existingTask) {
-    return { created: false };
-  }
-
-  // Find lead agent for new task
-  const lead = findLeadAgent();
-
-  // Get review state info
-  const { emoji, label } = getReviewStateInfo(review.state);
-
-  // Build task description
-  const reviewBodySection = review.body ? `\n\nReview Comment:\n${review.body}` : "";
-  const relatedTaskSection = existingTask
-    ? `Related task: ${existingTask.id}\n🔀 Consider routing to the same agent working on the related task.\n`
-    : "";
-  const reviewSuggestions =
-    review.state === "approved"
-      ? "💡 Suggested: Merge the PR or wait for additional reviews"
-      : review.state === "changes_requested"
-        ? "💡 Suggested: Address the requested changes and update the PR"
-        : "💡 Suggested: Review the feedback and respond if needed";
-
-  const result = resolveTemplate(
-    "github.pull_request.review_submitted",
-    {
-      review_emoji: emoji,
-      pr_number: pr.number,
-      review_label: label,
-      pr_title: pr.title,
-      sender_login: sender.login,
-      repo_full_name: repository.full_name,
-      review_url: review.html_url,
-      review_body_section: reviewBodySection,
-      related_task_section: relatedTaskSection,
-      review_suggestions: reviewSuggestions,
-    },
-    { agentId: lead?.id, repoId: repository.full_name },
+  // Suppressed: see thoughts/taras/plans/2026-03-30-github-event-safety-defaults.md
+  console.log(
+    `[GitHub:suppressed] pull_request_review.${action} on ${repository.full_name}#${pr.number} — review events disabled by default`,
   );
-
-  if (result.skipped) {
-    return { created: false };
-  }
-
-  // Create task (assigned to lead if available, otherwise unassigned)
-  const task = createTaskExtended(result.text, {
-    agentId: lead?.id ?? "",
-    source: "github",
-    vcsProvider: "github",
-    taskType: "github-review",
-    vcsRepo: repository.full_name,
-    vcsEventType: "pull_request_review",
-    vcsNumber: pr.number,
-    vcsAuthor: sender.login,
-    vcsUrl: review.html_url,
-  });
-
-  if (lead) {
-    console.log(
-      `[GitHub] Created task ${task.id} for PR #${pr.number} review (${review.state}) -> ${lead.name}`,
-    );
-  } else {
-    console.log(
-      `[GitHub] Created unassigned task ${task.id} for PR #${pr.number} review (${review.state}, no lead available)`,
-    );
-  }
-
-  // Add reaction to acknowledge the review
-  if (installation?.id) {
-    addIssueReaction(repository.full_name, pr.number, "eyes", installation.id);
-  }
-
-  return { created: true, taskId: task.id };
+  return { created: false };
 }
 
 /**
@@ -879,89 +819,12 @@ export async function handleCheckRun(
 ): Promise<{ created: boolean; taskId?: string }> {
   const { action, check_run, repository } = event;
 
-  // Only handle completed check runs
-  if (action !== "completed") {
-    return { created: false };
-  }
-
-  // Only notify on failure or action_required - success is less critical
-  // Skip neutral/skipped/cancelled as they're usually not actionable
-  const conclusion = check_run.conclusion;
-  if (conclusion !== "failure" && conclusion !== "action_required") {
-    return { created: false };
-  }
-
-  // Must be associated with at least one PR
-  if (!check_run.pull_requests || check_run.pull_requests.length === 0) {
-    return { created: false };
-  }
-
-  // Check if we have a task for any of these PRs
-  let relatedTask = null;
-  let prNumber = 0;
-  for (const pr of check_run.pull_requests) {
-    const task = findTaskByVcs(repository.full_name, pr.number);
-    if (task) {
-      relatedTask = task;
-      prNumber = pr.number;
-      break;
-    }
-  }
-
-  if (!relatedTask) {
-    // No task for any of the associated PRs
-    return { created: false };
-  }
-
-  // Deduplicate
-  const eventKey = `check-run:${repository.full_name}:${check_run.id}`;
-  if (isDuplicate(eventKey)) {
-    return { created: false };
-  }
-
-  const lead = findLeadAgent();
-  const { emoji, label } = getCheckConclusionInfo(conclusion);
-
-  const outputSummarySection = check_run.output.summary
-    ? `\n\nSummary:\n${check_run.output.summary.substring(0, 500)}`
-    : "";
-
-  const result = resolveTemplate(
-    "github.check_run.failed",
-    {
-      conclusion_emoji: emoji,
-      pr_number: prNumber,
-      check_name: check_run.name,
-      conclusion_label: label,
-      repo_full_name: repository.full_name,
-      check_url: check_run.html_url,
-      output_summary_section: outputSummarySection,
-      related_task_id: relatedTask.id,
-    },
-    { agentId: lead?.id, repoId: repository.full_name },
-  );
-
-  if (result.skipped) {
-    return { created: false };
-  }
-
-  const task = createTaskExtended(result.text, {
-    agentId: lead?.id ?? "",
-    source: "github",
-    vcsProvider: "github",
-    taskType: "github-ci",
-    vcsRepo: repository.full_name,
-    vcsEventType: "check_run",
-    vcsNumber: prNumber,
-    vcsAuthor: "",
-    vcsUrl: check_run.html_url,
-  });
-
+  // Suppressed: see thoughts/taras/plans/2026-03-30-github-event-safety-defaults.md
+  const conclusion = check_run.conclusion ?? "unknown";
   console.log(
-    `[GitHub] Created task ${task.id} for check_run ${check_run.name} (${conclusion}) on PR #${prNumber} -> ${lead?.name ?? "unassigned"}`,
+    `[GitHub:suppressed] check_run.${action} (${conclusion}) on ${repository.full_name} — CI events disabled by default`,
   );
-
-  return { created: true, taskId: task.id };
+  return { created: false };
 }
 
 /**
@@ -974,84 +837,12 @@ export async function handleCheckSuite(
 ): Promise<{ created: boolean; taskId?: string }> {
   const { action, check_suite, repository } = event;
 
-  // Only handle completed check suites
-  if (action !== "completed") {
-    return { created: false };
-  }
-
-  // Only notify on failure - success notifications would be too noisy
-  const conclusion = check_suite.conclusion;
-  if (conclusion !== "failure") {
-    return { created: false };
-  }
-
-  // Must be associated with at least one PR
-  if (!check_suite.pull_requests || check_suite.pull_requests.length === 0) {
-    return { created: false };
-  }
-
-  // Check if we have a task for any of these PRs
-  let relatedTask = null;
-  let prNumber = 0;
-  for (const pr of check_suite.pull_requests) {
-    const task = findTaskByVcs(repository.full_name, pr.number);
-    if (task) {
-      relatedTask = task;
-      prNumber = pr.number;
-      break;
-    }
-  }
-
-  if (!relatedTask) {
-    // No task for any of the associated PRs
-    return { created: false };
-  }
-
-  // Deduplicate
-  const eventKey = `check-suite:${repository.full_name}:${check_suite.id}`;
-  if (isDuplicate(eventKey)) {
-    return { created: false };
-  }
-
-  const lead = findLeadAgent();
-  const { emoji, label } = getCheckConclusionInfo(conclusion);
-  const branch = check_suite.head_branch ?? "unknown";
-
-  const result = resolveTemplate(
-    "github.check_suite.failed",
-    {
-      conclusion_emoji: emoji,
-      pr_number: prNumber,
-      conclusion_label: label,
-      repo_full_name: repository.full_name,
-      branch,
-      head_sha_short: check_suite.head_sha.substring(0, 7),
-      related_task_id: relatedTask.id,
-    },
-    { agentId: lead?.id, repoId: repository.full_name },
-  );
-
-  if (result.skipped) {
-    return { created: false };
-  }
-
-  const task = createTaskExtended(result.text, {
-    agentId: lead?.id ?? "",
-    source: "github",
-    vcsProvider: "github",
-    taskType: "github-ci",
-    vcsRepo: repository.full_name,
-    vcsEventType: "check_suite",
-    vcsNumber: prNumber,
-    vcsAuthor: "",
-    vcsUrl: repository.html_url,
-  });
-
+  // Suppressed: see thoughts/taras/plans/2026-03-30-github-event-safety-defaults.md
+  const conclusion = check_suite.conclusion ?? "unknown";
   console.log(
-    `[GitHub] Created task ${task.id} for check_suite (${conclusion}) on PR #${prNumber} -> ${lead?.name ?? "unassigned"}`,
+    `[GitHub:suppressed] check_suite.${action} (${conclusion}) on ${repository.full_name} — CI events disabled by default`,
   );
-
-  return { created: true, taskId: task.id };
+  return { created: false };
 }
 
 /**
@@ -1065,87 +856,12 @@ export async function handleCheckSuite(
 export async function handleWorkflowRun(
   event: WorkflowRunEvent,
 ): Promise<{ created: boolean; taskId?: string }> {
-  const { action, workflow_run, workflow, repository } = event;
-
-  // Only handle completed workflow runs
-  if (action !== "completed") {
-    return { created: false };
-  }
-
-  // Only notify on failure - success notifications would be too noisy
-  const conclusion = workflow_run.conclusion;
-  if (conclusion !== "failure") {
-    return { created: false };
-  }
-
-  // Must be associated with at least one PR
-  if (!workflow_run.pull_requests || workflow_run.pull_requests.length === 0) {
-    return { created: false };
-  }
-
-  // Check if we have a task for any of these PRs
-  let relatedTask = null;
-  let prNumber = 0;
-  for (const pr of workflow_run.pull_requests) {
-    const task = findTaskByVcs(repository.full_name, pr.number);
-    if (task) {
-      relatedTask = task;
-      prNumber = pr.number;
-      break;
-    }
-  }
-
-  if (!relatedTask) {
-    // No task for any of the associated PRs
-    return { created: false };
-  }
-
-  // Deduplicate
-  const eventKey = `workflow-run:${repository.full_name}:${workflow_run.id}`;
-  if (isDuplicate(eventKey)) {
-    return { created: false };
-  }
-
-  const lead = findLeadAgent();
-  const { emoji, label } = getCheckConclusionInfo(conclusion);
-
-  const result = resolveTemplate(
-    "github.workflow_run.failed",
-    {
-      conclusion_emoji: emoji,
-      pr_number: prNumber,
-      workflow_run_name: workflow_run.name,
-      conclusion_label: label,
-      repo_full_name: repository.full_name,
-      workflow_name: workflow.name,
-      run_number: workflow_run.run_number,
-      head_branch: workflow_run.head_branch,
-      trigger_event: workflow_run.event,
-      logs_url: workflow_run.html_url,
-      related_task_id: relatedTask.id,
-    },
-    { agentId: lead?.id, repoId: repository.full_name },
-  );
-
-  if (result.skipped) {
-    return { created: false };
-  }
-
-  const task = createTaskExtended(result.text, {
-    agentId: lead?.id ?? "",
-    source: "github",
-    vcsProvider: "github",
-    taskType: "github-ci",
-    vcsRepo: repository.full_name,
-    vcsEventType: "workflow_run",
-    vcsNumber: prNumber,
-    vcsAuthor: "",
-    vcsUrl: workflow_run.html_url,
-  });
+  const { action, workflow_run, repository } = event;
 
+  // Suppressed: see thoughts/taras/plans/2026-03-30-github-event-safety-defaults.md
+  const conclusion = workflow_run.conclusion ?? "unknown";
   console.log(
-    `[GitHub] Created task ${task.id} for workflow_run "${workflow_run.name}" (${conclusion}) on PR #${prNumber} -> ${lead?.name ?? "unassigned"}`,
+    `[GitHub:suppressed] workflow_run.${action} (${conclusion}) on ${repository.full_name} — CI events disabled by default`,
   );
-
-  return { created: true, taskId: task.id };
+  return { created: false };
 }

package/src/github/index.ts

@@ -17,7 +17,14 @@ export {
   handlePullRequestReview,
   handleWorkflowRun,
 } from "./handlers";
-export { detectMention, extractMentionContext, GITHUB_BOT_NAME, isBotAssignee } from "./mentions";
+export {
+  detectMention,
+  extractMentionContext,
+  GITHUB_BOT_NAME,
+  GITHUB_EVENT_LABELS,
+  isBotAssignee,
+  isSwarmLabel,
+} from "./mentions";
 export type { ReactionType } from "./reactions";
 export { addIssueReaction, addReaction, postComment } from "./reactions";
 export type {

package/src/github/mentions.ts

@@ -1,6 +1,16 @@
 // Bot name for @mentions (can be overridden via env)
 export const GITHUB_BOT_NAME = process.env.GITHUB_BOT_NAME || "agent-swarm-bot";
 
+// Labels that trigger agent action on PR/issue label events (comma-separated env var)
+const GITHUB_EVENT_LABELS_RAW = process.env.GITHUB_EVENT_LABELS || "swarm-review";
+export const GITHUB_EVENT_LABELS: string[] = GITHUB_EVENT_LABELS_RAW.split(",")
+  .map((l) => l.trim().toLowerCase())
+  .filter(Boolean);
+
+export function isSwarmLabel(label: string): boolean {
+  return GITHUB_EVENT_LABELS.includes(label.toLowerCase());
+}
+
 // Additional aliases that also trigger the bot (comma-separated env var)
 // Example: GITHUB_BOT_ALIASES=heysidekick,sidekick,review-bot
 function computeBotNames(): string[] {

package/src/github/templates.ts

@@ -197,6 +197,35 @@ Context:
   category: "event",
 });
 
+registerTemplate({
+  eventType: "github.pull_request.labeled",
+  header: "[GitHub PR #{{pr_number}}] {{pr_title}}",
+  defaultBody: `Label added: {{label_name}}
+From: {{sender_login}}
+Repo: {{repo_full_name}}
+Branch: {{head_ref}} → {{base_ref}}
+URL: {{pr_url}}
+
+Context:
+{{context}}
+
+---
+{{@template[common.delegation_instruction]}}
+{{@template[common.command_suggestions.github_pr]}}`,
+  variables: [
+    { name: "pr_number", description: "Pull request number" },
+    { name: "pr_title", description: "Pull request title" },
+    { name: "label_name", description: "Label that was added" },
+    { name: "sender_login", description: "Event sender login" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "head_ref", description: "Head branch name" },
+    { name: "base_ref", description: "Base branch name" },
+    { name: "pr_url", description: "Pull request HTML URL" },
+    { name: "context", description: "PR body or title as context" },
+  ],
+  category: "event",
+});
+
 // ============================================================================
 // Issue events
 // ============================================================================
@@ -251,6 +280,32 @@ Context:
   category: "event",
 });
 
+registerTemplate({
+  eventType: "github.issue.labeled",
+  header: "[GitHub Issue #{{issue_number}}] {{issue_title}}",
+  defaultBody: `Label added: {{label_name}}
+From: {{sender_login}}
+Repo: {{repo_full_name}}
+URL: {{issue_url}}
+
+Context:
+{{context}}
+
+---
+{{@template[common.delegation_instruction]}}
+{{@template[common.command_suggestions.github_issue]}}`,
+  variables: [
+    { name: "issue_number", description: "Issue number" },
+    { name: "issue_title", description: "Issue title" },
+    { name: "label_name", description: "Label that was added" },
+    { name: "sender_login", description: "Event sender login" },
+    { name: "repo_full_name", description: "Repository full name (owner/repo)" },
+    { name: "issue_url", description: "Issue HTML URL" },
+    { name: "context", description: "Issue body or title as context" },
+  ],
+  category: "event",
+});
+
 // ============================================================================
 // Comment events
 // ============================================================================

package/src/github/types.ts

@@ -20,6 +20,7 @@ export interface PullRequestEvent extends GitHubWebhookEvent {
     changed_files?: number;
   };
   requested_reviewer?: { login: string; id: number }; // Added for review_requested/review_request_removed events
+  label?: { id: number; name: string; color: string }; // Added for labeled/unlabeled events
 }
 
 export interface IssueEvent extends GitHubWebhookEvent {
@@ -30,6 +31,7 @@ export interface IssueEvent extends GitHubWebhookEvent {
     html_url: string;
     user: { login: string };
   };
+  label?: { id: number; name: string; color: string }; // Added for labeled/unlabeled events
 }
 
 export interface CommentEvent extends GitHubWebhookEvent {

package/src/hooks/hook.ts

@@ -14,6 +14,7 @@ const CLAUDE_MD_BACKUP_PATH = `${process.env.HOME}/.claude/CLAUDE.md.bak`;
 const SOUL_MD_PATH = "/workspace/SOUL.md";
 const IDENTITY_MD_PATH = "/workspace/IDENTITY.md";
 const TOOLS_MD_PATH = "/workspace/TOOLS.md";
+const HEARTBEAT_MD_PATH = "/workspace/HEARTBEAT.md";
 const SETUP_SCRIPT_PATH = "/workspace/start-up.sh";
 
 type McpServerConfig = {
@@ -389,6 +390,14 @@ export async function handleHook(): Promise<void> {
       }
     }
 
+    const heartbeatFile = Bun.file(HEARTBEAT_MD_PATH);
+    if (await heartbeatFile.exists()) {
+      const content = await heartbeatFile.text();
+      if (content.length <= 65536) {
+        updates.heartbeatMd = content;
+      }
+    }
+
     if (Object.keys(updates).length === 0) return;
 
     try {
@@ -910,7 +919,8 @@ ${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?
             if (
               editedPath === SOUL_MD_PATH ||
               editedPath === IDENTITY_MD_PATH ||
-              editedPath === TOOLS_MD_PATH
+              editedPath === TOOLS_MD_PATH ||
+              editedPath === HEARTBEAT_MD_PATH
             ) {
               await syncIdentityFilesToServer(agentInfo.id, "self_edit");
             }

package/src/prompts/session-templates.ts

@@ -77,6 +77,10 @@ Available Slack tools:
 - \`slack-read\`: Read thread/channel history (use taskId or channelId)
 - \`slack-list-channels\`: Discover available Slack channels the bot can access
 
+#### Identity & profile tools
+
+- \`update-profile\`: Update your own profile fields (name, role, capabilities, soulMd, identityMd, heartbeatMd, claudeMd, toolsMd, setupScript). As lead, you can also update other agents' profiles to shape their behavior.
+
 #### General monitor and control tools
 
 - \`get-swarm\`: Get the list of all workers in the swarm along with their status
@@ -226,6 +230,37 @@ Task: {describe what needs to be done}
 - Complex feature/major refactor → Use PLANNING first, then IMPLEMENTATION
 - Bug fix/small code change → Use QUICK FIX template
 - Non-code task/question → Use GENERAL template
+
+#### Heartbeat Checklist
+
+The system reads your \`/workspace/HEARTBEAT.md\` every 30 minutes. If it has content (not just
+comments or empty lines), it creates a \`heartbeat-checklist\` task for you containing:
+1. **Auto-generated system status** — task counts, stalled tasks, agent health, idle workers, unassigned work
+2. **Your standing orders** — whatever you wrote in HEARTBEAT.md
+
+**How to configure:**
+- **Edit the file directly:** Open \`/workspace/HEARTBEAT.md\` and write your standing orders. Changes sync to the database automatically on save.
+- **Use \`update-profile\`:** Call \`update-profile\` with the \`heartbeatMd\` field set to your checklist content. This updates both the database and the file.
+
+**What to put in HEARTBEAT.md** — a plain markdown list of actionable standing orders:
+\`\`\`markdown
+- Check Slack for unaddressed requests older than 1 hour
+- Review active tasks for any that seem stuck or need follow-up
+- If idle workers exist and unassigned tasks are available, investigate why
+- Post a daily summary to #agent-status at 5pm
+\`\`\`
+
+**Key mechanics:**
+- **Empty = disabled** — leave HEARTBEAT.md empty (or all HTML comments) to skip checks at zero LLM cost
+- **System status is automatic** — don't gather it yourself, it's injected into every checklist task
+- **Don't create checklist tasks yourself** — the system handles scheduling. Complete your current one and the next arrives in ~30 minutes
+- **Boot triage** — after a server restart, you get a one-time higher-priority checklist task within 30 seconds
+
+**When you receive a checklist task:**
+1. Review the system status for anything that needs attention
+2. Review your standing orders for any periodic checks or actions due
+3. If something needs action — do it now (create tasks, post to Slack, etc.)
+4. If everything is healthy — complete the task with a brief "All clear" summary
 `,
   variables: [],
   category: "system",

package/src/tests/concurrency.test.ts

@@ -203,11 +203,11 @@ describe("Concurrency Integration Tests", () => {
         isLead: false,
         status: "idle",
         capabilities: [],
-        maxTasks: 20, // Max allowed by schema
+        maxTasks: 100, // Max allowed by schema
       });
 
-      expect(agent.maxTasks).toBe(20);
-      expect(getRemainingCapacity(agent.id)).toBe(20);
+      expect(agent.maxTasks).toBe(100);
+      expect(getRemainingCapacity(agent.id)).toBe(100);
     });
   });
 });

package/src/tests/github-event-filter.test.ts

@@ -0,0 +1,301 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, createAgent, initDb } from "../be/db";
+import {
+  handleCheckRun,
+  handleCheckSuite,
+  handleComment,
+  handleIssue,
+  handlePullRequest,
+  handlePullRequestReview,
+  handleWorkflowRun,
+} from "../github/handlers";
+import { GITHUB_BOT_NAME } from "../github/mentions";
+import type {
+  CheckRunEvent,
+  CheckSuiteEvent,
+  CommentEvent,
+  IssueEvent,
+  PullRequestEvent,
+  PullRequestReviewEvent,
+  WorkflowRunEvent,
+} from "../github/types";
+
+const TEST_DB_PATH = "./test-github-event-filter.sqlite";
+
+// ── Setup ──
+
+beforeAll(async () => {
+  await unlink(TEST_DB_PATH).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-wal`).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
+  initDb(TEST_DB_PATH);
+  // Create a lead agent so handlers can assign tasks
+  createAgent({
+    id: "lead-gh-001",
+    name: "GitHubTestLead",
+    status: "idle",
+    isLead: true,
+  });
+});
+
+afterAll(async () => {
+  closeDb();
+  await unlink(TEST_DB_PATH).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-wal`).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
+});
+
+// ── Helpers ──
+
+const BASE_REPO = { full_name: "test/repo", html_url: "https://github.com/test/repo" };
+const BASE_SENDER = { login: "testuser" };
+const BASE_PR = {
+  number: 1,
+  title: "Test PR",
+  body: null as string | null,
+  html_url: "https://github.com/test/repo/pull/1",
+  user: { login: "testuser" },
+  head: { ref: "feature", sha: "abc1234567890" },
+  base: { ref: "main" },
+  merged: false,
+  merged_by: undefined,
+};
+
+function makePREvent(overrides: Partial<PullRequestEvent> = {}): PullRequestEvent {
+  return {
+    action: "opened",
+    pull_request: BASE_PR,
+    repository: BASE_REPO,
+    sender: BASE_SENDER,
+    ...overrides,
+  };
+}
+
+function makeIssueEvent(overrides: Partial<IssueEvent> = {}): IssueEvent {
+  return {
+    action: "opened",
+    issue: {
+      number: 10,
+      title: "Test Issue",
+      body: null,
+      html_url: "https://github.com/test/repo/issues/10",
+      user: { login: "testuser" },
+    },
+    repository: BASE_REPO,
+    sender: BASE_SENDER,
+    ...overrides,
+  };
+}
+
+// ── Suppressed events ──
+
+describe("suppressed cascade events", () => {
+  test("pull_request.closed returns created: false", async () => {
+    const result = await handlePullRequest(makePREvent({ action: "closed" }));
+    expect(result.created).toBe(false);
+  });
+
+  test("pull_request.synchronize returns created: false", async () => {
+    const result = await handlePullRequest(makePREvent({ action: "synchronize" }));
+    expect(result.created).toBe(false);
+  });
+
+  test("pull_request_review.submitted returns created: false", async () => {
+    const event: PullRequestReviewEvent = {
+      action: "submitted",
+      review: {
+        id: 1,
+        body: "Looks good",
+        state: "approved",
+        html_url: "https://github.com/test/repo/pull/1#pullrequestreview-1",
+        user: { login: "reviewer" },
+        submitted_at: "2026-01-01T00:00:00Z",
+      },
+      pull_request: {
+        number: 1,
+        title: "Test PR",
+        body: null,
+        html_url: "https://github.com/test/repo/pull/1",
+        user: { login: "testuser" },
+        head: { ref: "feature" },
+        base: { ref: "main" },
+      },
+      repository: BASE_REPO,
+      sender: { login: "reviewer" },
+    };
+    const result = await handlePullRequestReview(event);
+    expect(result.created).toBe(false);
+  });
+
+  test("check_run.completed with failure returns created: false", async () => {
+    const event: CheckRunEvent = {
+      action: "completed",
+      check_run: {
+        id: 1,
+        name: "ci/test",
+        status: "completed",
+        conclusion: "failure",
+        html_url: "https://github.com/test/repo/runs/1",
+        started_at: "2026-01-01T00:00:00Z",
+        completed_at: "2026-01-01T00:01:00Z",
+        output: { title: null, summary: null },
+        check_suite: { id: 1, head_sha: "abc1234" },
+        pull_requests: [{ number: 1, head: { sha: "abc1234" } }],
+      },
+      repository: BASE_REPO,
+      sender: BASE_SENDER,
+    };
+    const result = await handleCheckRun(event);
+    expect(result.created).toBe(false);
+  });
+
+  test("check_suite.completed with failure returns created: false", async () => {
+    const event: CheckSuiteEvent = {
+      action: "completed",
+      check_suite: {
+        id: 1,
+        status: "completed",
+        conclusion: "failure",
+        head_sha: "abc1234567890",
+        head_branch: "feature",
+        pull_requests: [{ number: 1, head: { sha: "abc1234" } }],
+      },
+      repository: BASE_REPO,
+      sender: BASE_SENDER,
+    };
+    const result = await handleCheckSuite(event);
+    expect(result.created).toBe(false);
+  });
+
+  test("workflow_run.completed with failure returns created: false", async () => {
+    const event: WorkflowRunEvent = {
+      action: "completed",
+      workflow_run: {
+        id: 1,
+        name: "CI",
+        head_branch: "feature",
+        head_sha: "abc1234567890",
+        status: "completed",
+        conclusion: "failure",
+        html_url: "https://github.com/test/repo/actions/runs/1",
+        run_number: 42,
+        event: "pull_request",
+        pull_requests: [{ number: 1, head: { sha: "abc1234" } }],
+      },
+      workflow: { id: 1, name: "CI", path: ".github/workflows/ci.yml" },
+      repository: BASE_REPO,
+      sender: BASE_SENDER,
+    };
+    const result = await handleWorkflowRun(event);
+    expect(result.created).toBe(false);
+  });
+});
+
+// ── Explicit actions still create tasks ──
+
+describe("explicit actions create tasks", () => {
+  test("issue_comment with @mention creates task", async () => {
+    const event: CommentEvent = {
+      action: "created",
+      comment: {
+        id: 100,
+        body: `@${GITHUB_BOT_NAME} please review this`,
+        html_url: "https://github.com/test/repo/issues/10#issuecomment-100",
+        user: { login: "testuser" },
+      },
+      issue: {
+        number: 10,
+        title: "Test Issue",
+        html_url: "https://github.com/test/repo/issues/10",
+      },
+      repository: BASE_REPO,
+      sender: BASE_SENDER,
+    };
+    const result = await handleComment(event, "issue_comment");
+    expect(result.created).toBe(true);
+    expect(result.taskId).toBeDefined();
+  });
+
+  test("pull_request.review_requested with bot as reviewer creates task", async () => {
+    const event = makePREvent({
+      action: "review_requested",
+      requested_reviewer: { login: GITHUB_BOT_NAME, id: 1 },
+    });
+    const result = await handlePullRequest(event);
+    expect(result.created).toBe(true);
+    expect(result.taskId).toBeDefined();
+  });
+
+  test("pull_request.assigned with bot as assignee creates task", async () => {
+    const event = makePREvent({
+      action: "assigned",
+      pull_request: { ...BASE_PR, number: 2 },
+      assignee: { login: GITHUB_BOT_NAME, id: 1 },
+    });
+    const result = await handlePullRequest(event);
+    expect(result.created).toBe(true);
+    expect(result.taskId).toBeDefined();
+  });
+
+  test("pull_request.labeled with matching label creates task", async () => {
+    const event = makePREvent({
+      action: "labeled",
+      pull_request: { ...BASE_PR, number: 3 },
+      label: { id: 1, name: "swarm-review", color: "0075ca" },
+    });
+    const result = await handlePullRequest(event);
+    expect(result.created).toBe(true);
+    expect(result.taskId).toBeDefined();
+  });
+
+  test("pull_request.labeled with non-matching label does not create task", async () => {
+    const event = makePREvent({
+      action: "labeled",
+      pull_request: { ...BASE_PR, number: 4 },
+      label: { id: 2, name: "bug", color: "d73a4a" },
+    });
+    const result = await handlePullRequest(event);
+    expect(result.created).toBe(false);
+  });
+
+  test("issue.labeled with matching label creates task", async () => {
+    const event = makeIssueEvent({
+      action: "labeled",
+      label: { id: 1, name: "swarm-review", color: "0075ca" },
+    });
+    const result = await handleIssue(event);
+    expect(result.created).toBe(true);
+    expect(result.taskId).toBeDefined();
+  });
+
+  test("issue.labeled with non-matching label does not create task", async () => {
+    const event = makeIssueEvent({
+      action: "labeled",
+      issue: {
+        number: 11,
+        title: "Another Issue",
+        body: null,
+        html_url: "https://github.com/test/repo/issues/11",
+        user: { login: "testuser" },
+      },
+      label: { id: 2, name: "enhancement", color: "a2eeef" },
+    });
+    const result = await handleIssue(event);
+    expect(result.created).toBe(false);
+  });
+
+  test("pull_request.opened with @mention creates task", async () => {
+    const event = makePREvent({
+      action: "opened",
+      pull_request: {
+        ...BASE_PR,
+        number: 5,
+        title: `@${GITHUB_BOT_NAME} review this PR`,
+      },
+    });
+    const result = await handlePullRequest(event);
+    expect(result.created).toBe(true);
+    expect(result.taskId).toBeDefined();
+  });
+});

package/src/tests/github-event-labels.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { GITHUB_EVENT_LABELS, isSwarmLabel } from "../github/mentions";
+
+describe("isSwarmLabel", () => {
+  test("default label 'swarm-review' matches", () => {
+    expect(isSwarmLabel("swarm-review")).toBe(true);
+  });
+
+  test("case-insensitive matching", () => {
+    expect(isSwarmLabel("Swarm-Review")).toBe(true);
+    expect(isSwarmLabel("SWARM-REVIEW")).toBe(true);
+  });
+
+  test("non-matching labels return false", () => {
+    expect(isSwarmLabel("bug")).toBe(false);
+    expect(isSwarmLabel("enhancement")).toBe(false);
+    expect(isSwarmLabel("")).toBe(false);
+  });
+
+  test("GITHUB_EVENT_LABELS is populated", () => {
+    expect(GITHUB_EVENT_LABELS.length).toBeGreaterThan(0);
+    expect(GITHUB_EVENT_LABELS).toContain("swarm-review");
+  });
+});

package/src/types.ts

@@ -179,7 +179,7 @@ export const AgentSchema = z.object({
   heartbeatMd: z.string().max(65536).optional(),
 
   // Concurrency limit (defaults to 1 for backwards compatibility)
-  maxTasks: z.number().int().min(1).max(20).optional(),
+  maxTasks: z.number().int().min(1).max(100).optional(),
 
   // Polling limit tracking (consecutive empty polls)
   emptyPollCount: z.number().int().min(0).optional(),