@desplega.ai/agent-swarm 1.67.1 → 1.67.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025-2026 desplega.ai
+Copyright (c) 2025-2026 desplega.sh
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -11,7 +11,12 @@
   <sub>Built by <a href="https://desplega.sh">desplega.sh</a> — by builders, for builders.</sub>
 </p>
 
-https://github.com/user-attachments/assets/bd308567-d21e-44a5-87ec-d25aeb1de3d3
+<p align="center">
+  <video src="https://github.com/user-attachments/assets/e220712e-c54d-4f46-b059-bac04639d229" controls muted playsinline width="720"></video>
+</p>
+<p align="center">
+  <sub>▸ <a href="./assets/agent-swarm.mp4">daily evolution</a> · <a href="./assets/agent-swarm-slack-to-pr.mp4">slack → pr</a> · <a href="./assets/video-source">Making of</a></sub>
+</p>
 
 <p align="center">
   <a href="https://agent-swarm.dev">
@@ -33,101 +38,90 @@ https://github.com/user-attachments/assets/bd308567-d21e-44a5-87ec-d25aeb1de3d3
 
 > **What if your AI agents remembered everything, learned from every mistake, and got better with every task?**
 
-Agent Swarm lets you run a team of AI coding agents that coordinate autonomously. A **lead agent** receives tasks (from you, Slack, or GitHub), breaks them down, and delegates to **worker agents** running in Docker containers. Workers execute tasks, report progress, and ship code — all without manual intervention.
-
-## Key Features
-
-- **Lead/Worker coordination** — A lead agent delegates and tracks work across multiple workers
-- **Docker isolation** — Each worker runs in its own container with a full dev environment
-- **Slack, GitHub, GitLab & Email integration** — Create tasks by messaging the bot, @mentioning it in issues/PRs/MRs, or sending an email
-- **Task lifecycle** — Priority queues, dependencies, pause/resume across deployments
-- **Compounding memory** — Agents learn from every session and get smarter over time
-- **Persistent identity** — Each agent has its own personality, expertise, and working style that evolves
-- **Dashboard UI** — Real-time monitoring of agents, tasks, and inter-agent chat
-- **Service discovery** — Workers can expose HTTP services and discover each other
-- **Scheduled tasks** — Cron-based recurring task automation
-- **Templates registry** — Pre-built agent templates (9 official: lead, coder, researcher, reviewer, tester, FDE, content-writer, content-reviewer, content-strategist) with a gallery UI and docker-compose builder
-- **GitLab integration** — Full GitLab webhook support alongside GitHub via provider adapter pattern
-- **Working directory support** — Tasks can specify a custom starting directory for agents via the `dir` parameter
-- **Multi-provider** — Run agents with Claude Code, pi-mono, or OpenAI Codex (`HARNESS_PROVIDER=claude|pi|codex`)
-- **Agent-fs integration** — Persistent, searchable filesystem shared across the swarm with auto-registration on first boot
-- **Debug dashboard** — SQL query interface with Monaco editor and AG Grid results for database inspection
-- **Workflow engine** — DAG-based workflow automation with executor registry, checkpoint durability, webhook/schedule/manual triggers, per-step retry, structured I/O schemas, fan-out/convergence, configurable failure handling, and version history
-- **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
-- **MCP server management** — Register, install, and manage MCP servers for agents with scope cascade (agent → swarm → global) and auto-injection into worker containers
-- **Context usage tracking** — Monitor context window utilization and compaction events per task with visual indicators in the dashboard
+## What it does
 
-## Quick Start
+Agent Swarm runs a team of AI coding agents that coordinate autonomously. A **lead agent** receives tasks — from Slack, GitHub, GitLab, email, or the API — breaks them down, and delegates to **worker agents** running in Docker containers. Workers execute tasks, ship code, and write their learnings back to a shared memory so the whole swarm gets smarter every session.
 
-### Prerequisites
+Learn more in the [architecture overview](https://docs.agent-swarm.dev/docs/architecture/overview).
 
-- [Docker](https://docker.com) and Docker Compose
-- A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) OAuth token (`claude setup-token`)
+```mermaid
+flowchart LR
+    subgraph IN["Tasks come in"]
+        direction TB
+        S["Slack"]
+        G["GitHub / GitLab"]
+        E["Email"]
+        A["API / CLI"]
+    end
 
-### Option A: Docker Compose (recommended)
+    LEAD(["Lead Agent<br/>plans &amp; delegates"])
 
-The fastest way to get a full swarm running — API server, lead agent, and 2 workers.
+    subgraph WORKERS["Workers in Docker"]
+        direction TB
+        W1["Worker"]
+        W2["Worker"]
+        W3["Worker"]
+    end
 
-```bash
-git clone https://github.com/desplega-ai/agent-swarm.git
-cd agent-swarm
+    subgraph BRAIN["Persistent brain"]
+        direction TB
+        MEM["Memory<br/>(vector search)"]
+        ID["Identity<br/>(SOUL, CLAUDE.md)"]
+    end
 
-# Configure environment
-cp .env.docker.example .env
-# Edit .env — set API_KEY and CLAUDE_CODE_OAUTH_TOKEN at minimum
+    subgraph OUT["Work ships"]
+        direction TB
+        PR["Pull Requests"]
+        REPLY["Slack replies"]
+        EMAIL["Email replies"]
+    end
 
-# Start everything
-docker compose -f docker-compose.example.yml --env-file .env up -d
+    IN --> LEAD --> WORKERS
+    WORKERS -->|reads context| BRAIN
+    WORKERS -->|writes learnings| BRAIN
+    WORKERS --> OUT
 ```
 
-The API runs on port `3013`. The dashboard is available separately (see [Dashboard](#dashboard)).
+## Highlights
 
-The API includes interactive documentation at `http://localhost:3013/docs` (Scalar UI) and a machine-readable OpenAPI 3.1 spec at `http://localhost:3013/openapi.json`.
+- **Lead/worker orchestration in Docker** — isolated dev environments, priority queues, pause/resume across deploys. [Architecture →](https://docs.agent-swarm.dev/docs/architecture/overview)
+- **Compounding memory & persistent identity** — agents remember past sessions and evolve their own persona, expertise, and notes. [Memory →](https://docs.agent-swarm.dev/docs/architecture/memory) · [Agents →](https://docs.agent-swarm.dev/docs/architecture/agents)
+- **Multi-channel inputs** — Slack, GitHub, GitLab, email, Linear, and the HTTP API all create tasks. [Integrations](#integrations)
+- **Workflow engine with Human-in-the-Loop** — DAG-based automation with approval gates, retries, and structured I/O. [Workflows →](https://docs.agent-swarm.dev/docs/concepts/workflows)
+- **Scheduled & recurring tasks** — cron-based automation for standing work. [Scheduling →](https://docs.agent-swarm.dev/docs/concepts/scheduling)
+- **Multi-provider** — run with Claude Code, OpenAI Codex, or pi-mono. [Harness config →](https://docs.agent-swarm.dev/docs/guides/harness-configuration)
+- **Skills & MCP servers** — reusable procedural knowledge and per-agent MCP servers with scope cascade. [MCP tools →](https://docs.agent-swarm.dev/docs/reference/mcp-tools)
+- **Real-time dashboard** — monitor agents, tasks, and inter-agent chat. [app.agent-swarm.dev →](https://app.agent-swarm.dev)
 
-### Option B: Local API + Docker Workers
+## Quick Start
 
-Run the API locally and connect Docker workers to it.
+**Prerequisites:** [Docker](https://docker.com) and a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) OAuth token (`claude setup-token`).
 
-```bash
-git clone https://github.com/desplega-ai/agent-swarm.git
-cd agent-swarm
-bun install
+The fastest way is the onboarding wizard — it collects credentials, picks presets, and generates a working `docker-compose.yml`:
 
-# 1. Configure and start the API server
-cp .env.example .env
-# Edit .env — set API_KEY
-bun run start:http
+```bash
+bunx @desplega.ai/agent-swarm onboard
 ```
 
-In a new terminal, start a worker:
+Prefer manual setup? Clone and run with Docker Compose:
 
 ```bash
-# 2. Configure and run a Docker worker
-cp .env.docker.example .env.docker
-# Edit .env.docker — set API_KEY (same as above) and CLAUDE_CODE_OAUTH_TOKEN
-bun run docker:build:worker
-mkdir -p ./logs ./work/shared ./work/worker-1
-bun run docker:run:worker
+git clone https://github.com/desplega-ai/agent-swarm.git
+cd agent-swarm
+cp .env.docker.example .env
+# edit .env — set API_KEY and CLAUDE_CODE_OAUTH_TOKEN
+docker compose -f docker-compose.example.yml --env-file .env up -d
 ```
 
-### Option C: Claude Code as Lead Agent
+The API runs on port `3013`, with interactive docs at `http://localhost:3013/docs` and an OpenAPI 3.1 spec at `http://localhost:3013/openapi.json`.
 
-Use Claude Code directly as the lead agent — no Docker required for the lead.
-
-```bash
-# After starting the API server (Option B, step 1):
-bunx @desplega.ai/agent-swarm connect
-```
+<details>
+<summary><strong>Other setups</strong></summary>
 
-This configures Claude Code to connect to the swarm. Start Claude Code and tell it:
+- **Local API + Docker workers** — run the API on your host, workers in Docker. See [Getting Started](https://docs.agent-swarm.dev/docs/getting-started).
+- **Claude Code as the lead agent** — `bunx @desplega.ai/agent-swarm connect`, then tell Claude Code to register as the lead.
 
-```
-Register yourself as the lead agent in the agent-swarm.
-```
+</details>
 
 ## How It Works
 
@@ -141,312 +135,37 @@ Worker  Worker  Worker
 (Docker containers with full dev environments)
 ```
 
-1. **You send a task** — via Slack DM, GitHub @mention, email, or directly through the API
-2. **Lead agent plans** — breaks the task down and assigns subtasks to workers
-3. **Workers execute** — each in an isolated Docker container with git, Node.js, Python, etc.
-4. **Progress is tracked** — real-time updates in the dashboard, Slack threads, or API
-5. **Results are delivered** — PRs created, issues closed, Slack replies sent
-6. **Agents learn** — every session's learnings are extracted and recalled in future tasks
-
-## Agents Get Smarter Over Time
-
-Agent Swarm agents aren't stateless. They build compounding knowledge through multiple automatic mechanisms:
-
-### Memory System
+1. A task arrives via Slack DM, GitHub @mention, email, or the API.
+2. The lead plans and delegates subtasks to workers.
+3. Workers execute in isolated Docker containers (git, Node.js, Python, etc.).
+4. Progress streams to the dashboard, Slack threads, or the API.
+5. Results ship back out as PRs, issue replies, or Slack messages.
+6. Session learnings are extracted and become memory for future tasks.
 
-Every agent has a searchable memory backed by OpenAI embeddings (`text-embedding-3-small`). Memories are automatically created from:
-
-- **Session summaries** — At the end of each session, a lightweight model extracts key learnings: mistakes made, patterns discovered, failed approaches, and codebase knowledge. These summaries become searchable memories.
-- **Task completions** — Every completed (or failed) task's output is indexed. Failed tasks include notes about what went wrong, so the agent avoids repeating the same mistake.
-- **File-based notes** — Agents write to `/workspace/personal/memory/` in their per-agent directory. Files are automatically indexed and can be promoted to swarm scope.
-- **Lead-to-worker injection** — The lead agent can push specific learnings into any worker's memory using the `inject-learning` tool, closing the feedback loop.
-
-Before starting each task, the runner automatically searches for relevant memories and includes them in the agent's context. Past experience directly informs future work.
-
-### Persistent Identity
-
-Each agent has four identity files that persist across sessions and evolve over time:
-
-| File | Purpose | Example |
-|------|---------|---------|
-| **SOUL.md** | Core persona, values, behavioral directives | "You're not a chatbot. Be thorough. Own your mistakes." |
-| **IDENTITY.md** | Expertise, working style, track record | "I'm the coding arm of the swarm. I ship fast and clean." |
-| **TOOLS.md** | Environment knowledge — repos, services, APIs | "The API runs on port 3013. Use `wts` for worktree management." |
-| **CLAUDE.md** | Persistent notes and instructions | Learnings, preferences, important context |
-
-Agents can edit these files directly during a session. Changes are synced to the database in real-time (on every file edit) and at session end. When the agent restarts, its identity is restored from the database. Version history is tracked for all changes.
-
-The default templates encourage self-improvement:
-- Tools you wished you had? Update your startup script.
-- Environment knowledge gained? Record it in TOOLS.md.
-- Patterns discovered? Add them to your notes.
-- Mistakes to avoid? Add guardrails.
-
-### Startup Scripts
-
-Each agent has a startup script (`/workspace/start-up.sh`) that runs at every container start. Agents can modify this script to install tools, configure their environment, or set up workflows — and the changes persist across restarts. An agent that discovers it needs `ripgrep` will install it once, and it'll be there for every future session.
-
-## Agent Configuration
-
-### Identity Management
-
-Agent identity is stored in the database and synced to the filesystem at session start. There are three ways to configure it:
-
-1. **Default generation** — On first registration, the system generates templates based on the agent's name, role, and description.
-2. **Self-editing** — Agents modify their own identity files during sessions. A PostToolUse hook syncs changes to the database in real-time.
-3. **API / MCP tool** — Use the `update-profile` tool to programmatically set any identity field (soulMd, identityMd, toolsMd, claudeMd, setupScript).
-
-### System Prompt Assembly
-
-The system prompt is built from multiple layers, assembled at task start:
-
-1. **Base role instructions** — Lead or worker-specific behavior rules
-2. **Agent identity** — SOUL.md + IDENTITY.md content
-3. **Repository context** — If the task targets a specific GitHub repo, that repo's CLAUDE.md is included
-4. **Filesystem guide** — Memory directories, personal/shared workspace, setup script instructions
-5. **Self-awareness** — How the agent is built (runtime, hooks, memory system, task lifecycle)
-6. **Additional prompt** — Custom text from `SYSTEM_PROMPT` env var or `--system-prompt` CLI flag
-
-### Hook System
-
-Six hooks fire during each Claude Code session, providing safety, context management, and persistence:
-
-| Hook | When | What it does |
-|------|------|-------------|
-| **SessionStart** | Session begins | Writes CLAUDE.md from DB, loads concurrent session context for leads |
-| **PreCompact** | Before context compaction | Injects a "goal reminder" with current task details so the agent doesn't lose track |
-| **PreToolUse** | Before each tool call | Checks for task cancellation, detects tool loops (same tool/args repeated), blocks excessive polling |
-| **PostToolUse** | After each tool call | Sends heartbeat, syncs identity file edits to DB, auto-indexes memory files |
-| **UserPromptSubmit** | New iteration starts | Checks for task cancellation |
-| **Stop** | Session ends | Saves PM2 state, syncs all identity files, runs session summarization via Haiku, marks agent offline |
+More detail in the [task lifecycle docs](https://docs.agent-swarm.dev/docs/concepts/task-lifecycle).
 
 ## Integrations
 
-### Slack
-
-Create a [Slack App](https://api.slack.com/apps) with Socket Mode enabled. Required scopes: `chat:write`, `users:read`, `users:read.email`, `channels:history`, `im:history`.
-
-```bash
-# Add to your .env
-SLACK_BOT_TOKEN=xoxb-...    # Bot User OAuth Token
-SLACK_APP_TOKEN=xapp-...    # App-Level Token (Socket Mode)
-```
-
-Message the bot directly to create tasks. Workers reply in threads with progress updates. Optionally restrict access with `SLACK_ALLOWED_EMAIL_DOMAINS` or `SLACK_ALLOWED_USER_IDS`.
-
-### GitHub App
-
-Set up a [GitHub App](https://github.com/settings/apps/new) to receive webhooks when the bot is @mentioned or assigned to issues/PRs.
-
-**Webhook URL:** `https://<your-domain>/api/github/webhook`
-
-**Required permissions:**
-- Issues: Read & Write
-- Pull requests: Read & Write
-
-**Subscribe to events:** Issues, Issue comments, Pull requests, Pull request reviews, Pull request review comments, Check runs, Check suites, Workflow runs
-
-```bash
-# Add to your .env
-GITHUB_WEBHOOK_SECRET=your-webhook-secret
-GITHUB_BOT_NAME=your-bot-name           # Default: agent-swarm-bot
-
-# Optional: Enable bot reactions (emoji acknowledgments on GitHub)
-GITHUB_APP_ID=123456
-GITHUB_APP_PRIVATE_KEY=base64-encoded-key
-```
-
-**Supported events:**
-
-| Event | What happens |
-|-------|-------------|
-| Bot assigned to PR/issue | Creates a task for the lead agent |
-| Review requested from bot | Creates a review task |
-| `@bot-name` in comment/issue/PR | Creates a task with the mention context |
-| 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.
-
-**Webhook URL:** `https://<your-domain>/api/gitlab/webhook`
-
-```bash
-# Add to your .env
-GITLAB_WEBHOOK_SECRET=your-webhook-secret
-GITLAB_TOKEN=your-gitlab-token              # PAT or Group Access Token
-GITLAB_BOT_NAME=agent-swarm-bot             # Bot name for @mentions
-GITLAB_URL=https://gitlab.com               # GitLab instance URL
-```
-
-**Supported events:**
-
-| Event | What happens |
-|-------|-------------|
-| Bot assigned to MR/issue | Creates a task for the lead agent |
-| `@bot-name` in comment/issue/MR | Creates a task with the mention context |
-| Pipeline failure (on MRs with existing tasks) | Creates a CI notification task |
-
-Workers have `glab` CLI pre-installed for GitLab operations (creating MRs, commenting on issues, etc.).
-
-### AgentMail
-
-Give your agents email addresses via [AgentMail](https://agentmail.to). Emails are routed to agents as tasks or inbox messages.
-
-**Webhook URL:** `https://<your-domain>/api/agentmail/webhook`
-
-```bash
-# Add to your .env
-AGENTMAIL_WEBHOOK_SECRET=your-svix-secret
-```
-
-Agents self-register which inboxes they receive mail from using the `register-agentmail-inbox` MCP tool. Emails to a worker's inbox become tasks; emails to a lead's inbox become inbox messages for triage. Follow-up emails in the same thread are automatically routed to the same agent.
-
-### Sentry
-
-Workers can investigate Sentry issues directly with the `/investigate-sentry-issue` command. Add `SENTRY_AUTH_TOKEN` and `SENTRY_ORG` to your worker's environment.
+| Integration | What it does | Setup |
+|---|---|---|
+| **Slack** | DM or @mention the bot to create tasks; workers reply in threads | [Guide](https://docs.agent-swarm.dev/docs/guides/slack-integration) |
+| **GitHub App** | @mention or assign the bot on issues/PRs; CI failures create follow-up tasks | [Guide](https://docs.agent-swarm.dev/docs/guides/github-integration) |
+| **GitLab** | Same model as GitHub — webhooks on issues/MRs, `glab` preinstalled in workers | [Guide](https://docs.agent-swarm.dev/docs/guides/gitlab-integration) |
+| **AgentMail** | Give each agent an inbox; emails become tasks or lead messages | [Guide](https://docs.agent-swarm.dev/docs/guides/agentmail-integration) |
+| **Linear** | Bidirectional ticket sync via OAuth + webhooks | [Guide](https://docs.agent-swarm.dev/docs/guides/linear-integration) |
+| **Sentry** | Workers can triage Sentry issues with the `/investigate-sentry-issue` command | [Guide](https://docs.agent-swarm.dev/docs/guides/sentry-integration) |
 
 ## Dashboard
 
-A React-based monitoring dashboard for real-time visibility into your swarm.
+Real-time monitoring of agents, tasks, and inter-agent chat. Use the hosted version at [app.agent-swarm.dev](https://app.agent-swarm.dev), or run locally:
 
 ```bash
 cd new-ui && pnpm install && pnpm run dev
 ```
 
-Opens at `http://localhost:5173`. See [UI.md](./UI.md) for details.
+Opens at `http://localhost:5274`.
 
-## CLI
+## [CLI](https://docs.agent-swarm.dev/docs/reference/cli)
 
 ```bash
 bunx @desplega.ai/agent-swarm <command>
@@ -456,33 +175,23 @@ bunx @desplega.ai/agent-swarm <command>
 |---------|-------------|
 | `onboard` | Set up a new swarm from scratch (Docker Compose wizard) |
 | `connect` | Connect this project to an existing swarm |
-| `api`   | Start the API + MCP HTTP server |
-| `claude` | Run Claude CLI with optional message and headless mode |
-| `worker` | Run a worker agent |
-| `lead`  | Run a lead agent |
-| `docs`  | Open documentation (`--open` to launch in browser) |
-| `artifact` | Manage agent artifacts |
+| `api`     | Start the API + MCP HTTP server |
+| `worker`  | Run a worker agent |
+| `lead`    | Run a lead agent |
+| `docs`    | Open documentation (`--open` to launch in browser) |
 
 ## Deployment
 
-For production deployments, see [DEPLOYMENT.md](./DEPLOYMENT.md) which covers:
-
-- Docker Compose setup with multiple workers
-- systemd deployment for the API server
-- Graceful shutdown and task resume
-- Integration configuration (Slack, GitHub, AgentMail, Sentry)
+For production deployments (Docker Compose with multiple workers, systemd for the API, graceful shutdown, integration config), see [DEPLOYMENT.md](./DEPLOYMENT.md) and the [deployment guide](https://docs.agent-swarm.dev/docs/guides/deployment).
 
 ## Documentation
 
-| Resource | Description |
-|----------|-------------|
-| [docs.agent-swarm.dev](https://docs.agent-swarm.dev) | Full documentation site |
-| [app.agent-swarm.dev](https://app.agent-swarm.dev) | Hosted dashboard — connect your deployed swarm |
-| [DEPLOYMENT.md](./DEPLOYMENT.md) | Production deployment guide |
-| [Environment Variables](https://docs.agent-swarm.dev/docs/reference/environment-variables) | Complete environment variables reference |
-| [CONTRIBUTING.md](./CONTRIBUTING.md) | Development setup and project structure |
-| [UI.md](./UI.md) | Dashboard UI overview |
-| [MCP.md](./MCP.md) | MCP tools reference (auto-generated) |
+Everything lives at **[docs.agent-swarm.dev](https://docs.agent-swarm.dev)**. Good starting points:
+
+- [Getting Started](https://docs.agent-swarm.dev/docs/getting-started) — install, configure, and run your first task
+- [Architecture overview](https://docs.agent-swarm.dev/docs/architecture/overview) — how the swarm is wired together
+- [CLI reference](https://docs.agent-swarm.dev/docs/reference/cli) and [Environment variables](https://docs.agent-swarm.dev/docs/reference/environment-variables)
+- [API reference](https://docs.agent-swarm.dev/docs/api-reference) — every HTTP endpoint
 
 ## Contributing
 
@@ -509,4 +218,4 @@ Join our [Discord](https://discord.gg/KZgfyyDVZa) if you have questions or want
 
 ## License
 
-[MIT](./LICENSE) — 2025-2026 [desplega.ai](https://desplega.ai)
+[MIT](./LICENSE) — 2025-2026 [desplega.sh](https://desplega.sh)

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.67.1",
+    "version": "1.67.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": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.67.1",
+  "version": "1.67.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/be/crypto/key-bootstrap.ts

@@ -26,22 +26,39 @@ const ENV_KEY = "SECRETS_ENCRYPTION_KEY";
 const ENV_KEY_FILE = "SECRETS_ENCRYPTION_KEY_FILE";
 const KEY_FILENAME = ".encryption-key";
 
+const HEX_32_BYTE_RE = /^[0-9a-fA-F]{64}$/;
+
+function keyGenerationHelp(): string {
+  return [
+    "",
+    "How to generate a valid key:",
+    "  openssl rand -base64 32   # 43-char base64 (recommended)",
+    "  openssl rand -hex 32      # 64-char hex (also accepted)",
+    "",
+    "Common mistake: `openssl rand -base64 39` produces a 52-char string that",
+    "decodes to 39 bytes — the number passed to `openssl rand` is the decoded",
+    "byte count, and AES-256 requires exactly 32.",
+  ].join("\n");
+}
+
 function decodeAndValidate(source: string, content: string): Buffer {
   const trimmed = content.trim();
-  let decoded: Buffer;
-  try {
-    decoded = Buffer.from(trimmed, "base64");
-  } catch (err) {
-    throw new Error(
-      `Invalid encryption key at ${source}: base64 decode failed: ${(err as Error).message}`,
-    );
-  }
-  if (decoded.length !== AES_KEY_BYTES) {
-    throw new Error(
-      `Invalid encryption key at ${source}: expected ${AES_KEY_BYTES} bytes after base64 decode, got ${decoded.length} bytes`,
-    );
+
+  // Hex path: a 64-char string of [0-9a-fA-F] is unambiguously hex — it would
+  // decode to 48 bytes as base64, never 32, so there is no overlap with the
+  // base64 happy path.
+  if (HEX_32_BYTE_RE.test(trimmed)) {
+    const decoded = Buffer.from(trimmed, "hex");
+    if (decoded.length === AES_KEY_BYTES) return decoded;
   }
-  return decoded;
+
+  const decoded = Buffer.from(trimmed, "base64");
+  if (decoded.length === AES_KEY_BYTES) return decoded;
+
+  throw new Error(
+    `Invalid encryption key at ${source}: expected ${AES_KEY_BYTES} bytes, ` +
+      `got ${decoded.length} bytes after base64 decode.\n${keyGenerationHelp()}`,
+  );
 }
 
 type ResolveEncryptionKeyOptions = {

package/src/be/db.ts

@@ -84,6 +84,7 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   const templateBytes = templateGlobals.__testMigrationTemplate;
   if (templateBytes) {
     db = Database.deserialize(templateBytes);
+    db.run("PRAGMA busy_timeout = 5000;");
     db.run("PRAGMA foreign_keys = ON;");
     configureDbResolver(resolvePromptTemplate);
     // Ensure the encryption key is resolved even when restoring from the test
@@ -98,14 +99,24 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
 
   const database = db;
   database.run("PRAGMA journal_mode = WAL;");
+  database.run("PRAGMA busy_timeout = 5000;");
   database.run("PRAGMA foreign_keys = ON;");
 
-  // Load sqlite-vec extension for vector search
+  // Load sqlite-vec extension for vector search.
+  // In compiled binaries (`bun build --compile`) the JS lives in /$bunfs/ and
+  // `require.resolve("sqlite-vec-<platform>/vec0.so")` can't find the native
+  // asset — so we prefer an explicit filesystem path when set, and only fall
+  // back to the npm resolver for normal dev runs.
   try {
-    const sqliteVec = require("sqlite-vec");
-    sqliteVec.load(database);
+    const extensionPath = process.env.SQLITE_VEC_EXTENSION_PATH;
+    if (extensionPath) {
+      database.loadExtension(extensionPath);
+    } else {
+      const sqliteVec = require("sqlite-vec");
+      sqliteVec.load(database);
+    }
     sqliteVecAvailable = true;
-    console.log("[db] sqlite-vec loaded");
+    console.log(`[db] sqlite-vec loaded${extensionPath ? ` from ${extensionPath}` : ""}`);
   } catch (err) {
     console.warn(
       "[db] sqlite-vec not available, falling back to in-memory cosine:",
@@ -1479,6 +1490,26 @@ export function getMostRecentTaskInThread(channelId: string, threadTs: string):
   return row ? rowToAgentTask(row) : null;
 }
 
+export function findCompletedTaskInThread(
+  channelId: string,
+  threadTs: string,
+  windowMinutes: number,
+): AgentTask | null {
+  const since = new Date(Date.now() - windowMinutes * 60 * 1000).toISOString();
+  const row = getDb()
+    .prepare<AgentTaskRow, [string, string, string]>(
+      `SELECT * FROM agent_tasks
+       WHERE slackChannelId = ?
+       AND slackThreadTs = ?
+       AND status = 'completed'
+       AND lastUpdatedAt > ?
+       ORDER BY lastUpdatedAt DESC
+       LIMIT 1`,
+    )
+    .get(channelId, threadTs, since);
+  return row ? rowToAgentTask(row) : null;
+}
+
 export function completeTask(id: string, output?: string): AgentTask | null {
   const oldTask = getTaskById(id);
   const finishedAt = new Date().toISOString();

package/src/be/migrations/040_slack_thread_composite_index.sql

@@ -0,0 +1,3 @@
+-- Composite index for Slack thread queries (findCompletedTaskInThread, getMostRecentTaskInThread)
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_slack_thread
+  ON agent_tasks(slackChannelId, slackThreadTs, status);

package/src/http/index.ts

@@ -43,6 +43,15 @@ import { getPathSegments, parseQueryParams, setCorsHeaders } from "./utils";
 import { handleWebhooks } from "./webhooks";
 import { handleWorkflows } from "./workflows";
 
+// Last-line-of-defense: never let a single bad request (e.g. a SQLITE_BUSY
+// thrown out of a transaction callback) kill the API process. Log and keep going.
+process.on("uncaughtException", (err) => {
+  console.error("[fatal] uncaughtException:", err);
+});
+process.on("unhandledRejection", (reason) => {
+  console.error("[fatal] unhandledRejection:", reason);
+});
+
 const port = parseInt(process.env.PORT || process.argv[2] || "3013", 10);
 const apiKey = process.env.API_KEY || "";
 

package/src/prompts/session-templates.ts

@@ -94,7 +94,7 @@ If you explicitly assign to a different worker, session resume gracefully falls
 When a worker completes or fails a task, you receive an automatic follow-up task. Handle it by:
 1. Review the output/failure reason
 2. If the task has Slack metadata, use \`slack-reply\` with the task's ID to post the result back to the originating thread
-3. Decide: is the goal met? If not, create next task(s) with \`parentTaskId\` for session continuity. If blocked, notify the stakeholder.
+3. Complete this task. Do NOT re-delegate or create new worker tasks from a follow-up \u2014 the worker's result IS the answer. Only escalate to the stakeholder if the worker explicitly failed and the failure needs human attention.
 
 #### Heartbeat Checklist
 

package/src/tests/follow-up-redelivery-guard.test.ts

@@ -0,0 +1,267 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlinkSync } from "node:fs";
+import {
+  closeDb,
+  completeTask,
+  createAgent,
+  createTaskExtended,
+  findCompletedTaskInThread,
+  getDb,
+  getTaskById,
+  initDb,
+} from "../be/db";
+
+const TEST_DB_PATH = "./test-follow-up-redelivery-guard.sqlite";
+
+beforeAll(() => {
+  initDb(TEST_DB_PATH);
+});
+
+afterAll(() => {
+  closeDb();
+  try {
+    unlinkSync(TEST_DB_PATH);
+    unlinkSync(`${TEST_DB_PATH}-wal`);
+    unlinkSync(`${TEST_DB_PATH}-shm`);
+  } catch {
+    // ignore if files don't exist
+  }
+});
+
+describe("findCompletedTaskInThread", () => {
+  test("finds completed tasks in a thread within the time window", () => {
+    const agent = createAgent({
+      name: "dedup-worker-1",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+
+    const task = createTaskExtended("test task for thread", {
+      agentId: agent.id,
+      slackChannelId: "C_DEDUP_1",
+      slackThreadTs: "1000.0001",
+    });
+
+    // Mark as completed
+    completeTask(task.id, "done");
+
+    // Should find the completed task within a 2880-minute (48h) window
+    const result = findCompletedTaskInThread("C_DEDUP_1", "1000.0001", 2880);
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe(task.id);
+    expect(result!.status).toBe("completed");
+  });
+
+  test("returns null when no completed tasks exist in the thread", () => {
+    const agent = createAgent({
+      name: "dedup-worker-2",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+
+    // Create a task but don't complete it
+    createTaskExtended("pending task in thread", {
+      agentId: agent.id,
+      slackChannelId: "C_DEDUP_2",
+      slackThreadTs: "2000.0001",
+    });
+
+    const result = findCompletedTaskInThread("C_DEDUP_2", "2000.0001", 2880);
+    expect(result).toBeNull();
+  });
+
+  test("returns null outside the time window", () => {
+    const agent = createAgent({
+      name: "dedup-worker-3",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+
+    const task = createTaskExtended("old completed task", {
+      agentId: agent.id,
+      slackChannelId: "C_DEDUP_3",
+      slackThreadTs: "3000.0001",
+    });
+
+    completeTask(task.id, "done long ago");
+
+    // Backdate the lastUpdatedAt to 49 hours ago (beyond the 48h window)
+    const fortyNineHoursAgo = new Date(Date.now() - 49 * 60 * 60 * 1000).toISOString();
+    getDb().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [
+      fortyNineHoursAgo,
+      task.id,
+    ]);
+
+    // Should not find with a 48 hour window
+    const result = findCompletedTaskInThread("C_DEDUP_3", "3000.0001", 2880);
+    expect(result).toBeNull();
+  });
+
+  test("returns null for a different thread", () => {
+    const agent = createAgent({
+      name: "dedup-worker-4",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+
+    const task = createTaskExtended("task in different thread", {
+      agentId: agent.id,
+      slackChannelId: "C_DEDUP_4",
+      slackThreadTs: "4000.0001",
+    });
+
+    completeTask(task.id, "done");
+
+    // Search in a different thread — should not find
+    const result = findCompletedTaskInThread("C_DEDUP_4", "4000.9999", 2880);
+    expect(result).toBeNull();
+  });
+});
+
+describe("follow-up re-delegation guard logic", () => {
+  let leadAgent: ReturnType<typeof createAgent>;
+  let workerAgent: ReturnType<typeof createAgent>;
+
+  beforeAll(() => {
+    leadAgent = createAgent({
+      name: "guard-lead",
+      isLead: true,
+      status: "idle",
+      capabilities: [],
+    });
+    workerAgent = createAgent({
+      name: "guard-worker",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+      maxTasks: 5,
+    });
+  });
+
+  test("blocks re-delegation when source task is a follow-up and thread has completed work", () => {
+    // Step 1: Create and complete a worker task in a Slack thread
+    const workerTask = createTaskExtended("implement feature X", {
+      agentId: workerAgent.id,
+      slackChannelId: "C_GUARD_1",
+      slackThreadTs: "5000.0001",
+    });
+    completeTask(workerTask.id, "Feature X implemented");
+
+    // Step 2: Create a follow-up task (as store-progress would)
+    const followUpTask = createTaskExtended("Worker task completed — review needed.", {
+      agentId: leadAgent.id,
+      source: "system",
+      taskType: "follow-up",
+      parentTaskId: workerTask.id,
+      slackChannelId: "C_GUARD_1",
+      slackThreadTs: "5000.0001",
+    });
+
+    // Step 3: Simulate the guard logic from send-task.ts
+    // The lead's sourceTaskId would be the follow-up task
+    const sourceTask = getTaskById(followUpTask.id);
+    expect(sourceTask).not.toBeNull();
+    expect(sourceTask!.taskType).toBe("follow-up");
+    expect(sourceTask!.slackChannelId).toBe("C_GUARD_1");
+    expect(sourceTask!.slackThreadTs).toBe("5000.0001");
+
+    // The guard should find the completed worker task
+    const recentCompleted = findCompletedTaskInThread(
+      sourceTask!.slackChannelId!,
+      sourceTask!.slackThreadTs!,
+      2880,
+    );
+    expect(recentCompleted).not.toBeNull();
+    expect(recentCompleted!.id).toBe(workerTask.id);
+
+    // → Guard would block: re-delegation should be prevented
+  });
+
+  test("allows delegation when source task is NOT a follow-up (normal behavior)", () => {
+    // Create a normal Slack task (not a follow-up)
+    const slackTask = createTaskExtended("user asked a question", {
+      agentId: leadAgent.id,
+      source: "slack",
+      taskType: "inbox",
+      slackChannelId: "C_GUARD_2",
+      slackThreadTs: "6000.0001",
+    });
+
+    // Even if there are completed tasks in the thread, guard shouldn't trigger
+    // because the source task is not a "follow-up"
+    const sourceTask = getTaskById(slackTask.id);
+    expect(sourceTask).not.toBeNull();
+    expect(sourceTask!.taskType).not.toBe("follow-up");
+
+    // Guard condition: sourceTask?.taskType === "follow-up" → false
+    // → Guard does NOT block: delegation proceeds normally
+    const shouldBlock =
+      sourceTask?.taskType === "follow-up" && sourceTask.slackThreadTs && sourceTask.slackChannelId;
+    expect(shouldBlock).toBeFalsy();
+  });
+
+  test("allows delegation when source task is a follow-up but thread has NO completed work", () => {
+    // Create a follow-up task in a thread with no completed work
+    const followUpTask = createTaskExtended("Worker task failed — action needed.", {
+      agentId: leadAgent.id,
+      source: "system",
+      taskType: "follow-up",
+      slackChannelId: "C_GUARD_3",
+      slackThreadTs: "7000.0001",
+    });
+
+    const sourceTask = getTaskById(followUpTask.id);
+    expect(sourceTask).not.toBeNull();
+    expect(sourceTask!.taskType).toBe("follow-up");
+
+    // No completed tasks in this thread
+    const recentCompleted = findCompletedTaskInThread(
+      sourceTask!.slackChannelId!,
+      sourceTask!.slackThreadTs!,
+      2880,
+    );
+    expect(recentCompleted).toBeNull();
+
+    // → Guard does NOT block: first-time delegation is fine
+  });
+
+  test("allows delegation when source task is a follow-up but completed work is outside time window", () => {
+    // Create and complete a worker task, then backdate it
+    const oldWorkerTask = createTaskExtended("old task", {
+      agentId: workerAgent.id,
+      slackChannelId: "C_GUARD_4",
+      slackThreadTs: "8000.0001",
+    });
+    completeTask(oldWorkerTask.id, "done long ago");
+
+    // Backdate to 49 hours ago (beyond the 48h window)
+    const fortyNineHoursAgo = new Date(Date.now() - 49 * 60 * 60 * 1000).toISOString();
+    getDb().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [
+      fortyNineHoursAgo,
+      oldWorkerTask.id,
+    ]);
+
+    // Create a follow-up in the same thread
+    const followUpTask = createTaskExtended("Worker task completed — review needed.", {
+      agentId: leadAgent.id,
+      source: "system",
+      taskType: "follow-up",
+      slackChannelId: "C_GUARD_4",
+      slackThreadTs: "8000.0001",
+    });
+
+    const sourceTask = getTaskById(followUpTask.id);
+    const recentCompleted = findCompletedTaskInThread(
+      sourceTask!.slackChannelId!,
+      sourceTask!.slackThreadTs!,
+      2880,
+    );
+    expect(recentCompleted).toBeNull();
+
+    // → Guard does NOT block: completed work is too old
+  });
+});

package/src/tests/key-bootstrap.test.ts

@@ -157,6 +157,57 @@ describe("key-bootstrap: validation", () => {
     expect(() => resolveEncryptionKey(dbPath)).toThrow(/got 16 bytes/);
   });
 
+  it("error message includes openssl generation commands and the -base64 39 hint", () => {
+    process.env[ENV_KEY] = Buffer.alloc(16).toString("base64");
+    const dbPath = path.join(tmpDir, "test.sqlite");
+    let caught: Error | null = null;
+    try {
+      resolveEncryptionKey(dbPath);
+    } catch (err) {
+      caught = err as Error;
+    }
+    expect(caught).toBeTruthy();
+    const msg = caught?.message ?? "";
+    expect(msg).toContain("openssl rand -base64 32");
+    expect(msg).toContain("openssl rand -hex 32");
+    expect(msg).toContain("openssl rand -base64 39");
+  });
+
+  it("accepts a hex-encoded 32-byte key via SECRETS_ENCRYPTION_KEY env var", () => {
+    const keyBytes = randomBytes(AES_KEY_BYTES);
+    process.env[ENV_KEY] = keyBytes.toString("hex");
+    const dbPath = path.join(tmpDir, "test.sqlite");
+    const resolved = resolveEncryptionKey(dbPath);
+    expect(resolved.equals(keyBytes)).toBe(true);
+  });
+
+  it("accepts a hex-encoded 32-byte key via SECRETS_ENCRYPTION_KEY_FILE", () => {
+    const keyBytes = randomBytes(AES_KEY_BYTES);
+    const keyPath = path.join(tmpDir, "hex.key");
+    writeFileSync(keyPath, keyBytes.toString("hex"));
+    process.env[ENV_KEY_FILE] = keyPath;
+    const dbPath = path.join(tmpDir, "test.sqlite");
+    const resolved = resolveEncryptionKey(dbPath);
+    expect(resolved.equals(keyBytes)).toBe(true);
+  });
+
+  it("accepts a hex-encoded 32-byte key via on-disk .encryption-key", () => {
+    const keyBytes = randomBytes(AES_KEY_BYTES);
+    const keyFilePath = path.join(tmpDir, ".encryption-key");
+    writeFileSync(keyFilePath, keyBytes.toString("hex"));
+    const dbPath = path.join(tmpDir, "test.sqlite");
+    const resolved = resolveEncryptionKey(dbPath);
+    expect(resolved.equals(keyBytes)).toBe(true);
+  });
+
+  it("accepts uppercase hex-encoded keys", () => {
+    const keyBytes = randomBytes(AES_KEY_BYTES);
+    process.env[ENV_KEY] = keyBytes.toString("hex").toUpperCase();
+    const dbPath = path.join(tmpDir, "test.sqlite");
+    const resolved = resolveEncryptionKey(dbPath);
+    expect(resolved.equals(keyBytes)).toBe(true);
+  });
+
   it("throws when SECRETS_ENCRYPTION_KEY_FILE points to a malformed file", () => {
     const keyPath = path.join(tmpDir, "bad.key");
     writeFileSync(keyPath, Buffer.alloc(10).toString("base64"));

package/src/tests/prompt-template-remaining.test.ts

@@ -339,6 +339,11 @@ Task: "Fix the login page CSS"
 Output:
 Fixed the CSS alignment issue on the login form
 
+IMPORTANT: Do NOT re-delegate or re-answer the original request. The worker has already handled it. Your job is ONLY to:
+1. Review the output above
+2. If the task has Slack metadata, use \`slack-reply\` to post the result to the thread (if the worker hasn't already)
+3. Complete this follow-up task
+
 Use \`get-task-details\` with taskId "task-abc-123" for full details.`;
 
     expect(result.text).toBe(expected);

package/src/tools/send-task.ts

@@ -2,6 +2,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import {
   createTaskExtended,
+  findCompletedTaskInThread,
   getActiveTaskCount,
   getAgentById,
   getDb,
@@ -187,6 +188,36 @@ export const registerSendTaskTool = (server: McpServer) => {
         }
       }
 
+      // Guard: prevent re-delegation from follow-up tasks
+      // When the source task is a "follow-up" (worker completed/failed notification),
+      // check if there are completed tasks in the same Slack thread recently.
+      // This prevents the cycle: worker completes → follow-up → Lead re-delegates → repeat.
+      if (requestInfo.sourceTaskId) {
+        const sourceTask = getTaskById(requestInfo.sourceTaskId);
+        if (
+          sourceTask?.taskType === "follow-up" &&
+          sourceTask.slackThreadTs &&
+          sourceTask.slackChannelId
+        ) {
+          const recentCompleted = findCompletedTaskInThread(
+            sourceTask.slackChannelId,
+            sourceTask.slackThreadTs,
+            2880, // 48 hours in minutes
+          );
+          if (recentCompleted) {
+            const msg = `Blocked: re-delegation from follow-up task in a thread that already has completed work (task ${recentCompleted.id.slice(0, 8)}). The original request was already handled.`;
+            return {
+              content: [{ type: "text", text: msg }],
+              structuredContent: {
+                yourAgentId: requestInfo.agentId,
+                success: false,
+                message: msg,
+              },
+            };
+          }
+        }
+      }
+
       const txn = getDb().transaction(() => {
         const finalTags = tags;
 

package/src/tools/templates.ts

@@ -22,6 +22,11 @@ Task: "{{task_desc}}"
 Output:
 {{output_summary}}
 
+IMPORTANT: Do NOT re-delegate or re-answer the original request. The worker has already handled it. Your job is ONLY to:
+1. Review the output above
+2. If the task has Slack metadata, use \`slack-reply\` to post the result to the thread (if the worker hasn't already)
+3. Complete this follow-up task
+
 Use \`get-task-details\` with taskId "{{task_id}}" for full details.`,
   variables: [
     { name: "agent_name", description: "Worker agent name or ID prefix" },

package/tsconfig.json

@@ -44,6 +44,7 @@
     "work",
     "logs",
     "plugin",
-    "docs-site"
+    "docs-site",
+    "assets/video-source"
   ]
 }