opencode-swarm-plugin 0.23.5 → 0.24.0

package/dist/index.js

@@ -16973,7 +16973,7 @@ WD9f
 
 // ../../node_modules/.bun/ioredis@5.8.2/node_modules/ioredis/built/utils/index.js
 var require_utils2 = __commonJS((exports) => {
-  var __dirname = "/home/runner/work/opencode-swarm-plugin/opencode-swarm-plugin/node_modules/.bun/ioredis@5.8.2/node_modules/ioredis/built/utils";
+  var __dirname = "/home/runner/work/swarm-tools/swarm-tools/node_modules/.bun/ioredis@5.8.2/node_modules/ioredis/built/utils";
   Object.defineProperty(exports, "__esModule", { value: true });
   exports.noop = exports.defaults = exports.Debug = exports.getPackageMeta = exports.zipMap = exports.CONNECTION_CLOSED_ERROR_MSG = exports.shuffle = exports.sample = exports.resolveTLSProfile = exports.parseURL = exports.optimizeErrorStack = exports.toArg = exports.convertMapToArray = exports.convertObjectToArray = exports.timeout = exports.packObject = exports.isInt = exports.wrapMultiResult = exports.convertBufferToString = undefined;
   var fs_1 = __require("fs");
@@ -17203,7 +17203,7 @@ var require_utils2 = __commonJS((exports) => {
 
 // ../../node_modules/.bun/ioredis@5.8.2/node_modules/ioredis/built/Command.js
 var require_Command = __commonJS((exports) => {
-  var __dirname = "/home/runner/work/opencode-swarm-plugin/opencode-swarm-plugin/node_modules/.bun/ioredis@5.8.2/node_modules/ioredis/built";
+  var __dirname = "/home/runner/work/swarm-tools/swarm-tools/node_modules/.bun/ioredis@5.8.2/node_modules/ioredis/built";
   Object.defineProperty(exports, "__esModule", { value: true });
   var commands_1 = require_built();
   var calculateSlot = require_lib();
@@ -26174,6 +26174,7 @@ import {
   isAbsolute,
   sep
 } from "path";
+import { fileURLToPath } from "url";
 function setSkillsProjectDirectory(dir) {
   skillsProjectDirectory = dir;
   skillsCache = null;
@@ -26220,8 +26221,13 @@ function getClaudeGlobalSkillsDir() {
   return join4(home, ".claude", "skills");
 }
 function getPackageSkillsDir() {
-  const currentDir = new URL(".", import.meta.url).pathname;
-  return join4(currentDir, "..", "global-skills");
+  try {
+    const currentFilePath = fileURLToPath(import.meta.url);
+    return join4(dirname2(currentFilePath), "..", "global-skills");
+  } catch {
+    const currentDir = decodeURIComponent(new URL(".", import.meta.url).pathname);
+    return join4(currentDir, "..", "global-skills");
+  }
 }
 async function findSkillFiles(baseDir) {
   const skillFiles = [];
@@ -27422,6 +27428,228 @@ var QuerySwarmContextsArgsSchema = exports_external.object({
   strategy: SwarmStrategySchema.optional(),
   has_errors: exports_external.boolean().optional()
 });
+// src/schemas/bead-events.ts
+init_zod();
+var BaseBeadEventSchema = exports_external.object({
+  id: exports_external.number().optional(),
+  type: exports_external.string(),
+  project_key: exports_external.string(),
+  timestamp: exports_external.number(),
+  sequence: exports_external.number().optional()
+});
+var BeadCreatedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_created"),
+  bead_id: exports_external.string(),
+  title: exports_external.string(),
+  description: exports_external.string().optional(),
+  issue_type: BeadTypeSchema,
+  priority: exports_external.number().int().min(0).max(3),
+  parent_id: exports_external.string().optional(),
+  created_by: exports_external.string().optional(),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
+var BeadUpdatedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_updated"),
+  bead_id: exports_external.string(),
+  updated_by: exports_external.string().optional(),
+  changes: exports_external.object({
+    title: exports_external.object({
+      old: exports_external.string(),
+      new: exports_external.string()
+    }).optional(),
+    description: exports_external.object({
+      old: exports_external.string(),
+      new: exports_external.string()
+    }).optional(),
+    priority: exports_external.object({
+      old: exports_external.number(),
+      new: exports_external.number()
+    }).optional()
+  })
+});
+var BeadStatusChangedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_status_changed"),
+  bead_id: exports_external.string(),
+  from_status: BeadStatusSchema,
+  to_status: BeadStatusSchema,
+  changed_by: exports_external.string().optional(),
+  reason: exports_external.string().optional()
+});
+var BeadClosedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_closed"),
+  bead_id: exports_external.string(),
+  reason: exports_external.string(),
+  closed_by: exports_external.string().optional(),
+  files_touched: exports_external.array(exports_external.string()).optional(),
+  duration_ms: exports_external.number().optional()
+});
+var BeadReopenedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_reopened"),
+  bead_id: exports_external.string(),
+  reason: exports_external.string().optional(),
+  reopened_by: exports_external.string().optional()
+});
+var BeadDeletedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_deleted"),
+  bead_id: exports_external.string(),
+  reason: exports_external.string().optional(),
+  deleted_by: exports_external.string().optional()
+});
+var BeadDependencyAddedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_dependency_added"),
+  bead_id: exports_external.string(),
+  dependency: BeadDependencySchema,
+  added_by: exports_external.string().optional(),
+  reason: exports_external.string().optional()
+});
+var BeadDependencyRemovedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_dependency_removed"),
+  bead_id: exports_external.string(),
+  dependency: BeadDependencySchema,
+  removed_by: exports_external.string().optional(),
+  reason: exports_external.string().optional()
+});
+var BeadLabelAddedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_label_added"),
+  bead_id: exports_external.string(),
+  label: exports_external.string(),
+  added_by: exports_external.string().optional()
+});
+var BeadLabelRemovedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_label_removed"),
+  bead_id: exports_external.string(),
+  label: exports_external.string(),
+  removed_by: exports_external.string().optional()
+});
+var BeadCommentAddedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_comment_added"),
+  bead_id: exports_external.string(),
+  comment_id: exports_external.number().optional(),
+  author: exports_external.string(),
+  body: exports_external.string(),
+  parent_comment_id: exports_external.number().optional(),
+  metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+});
+var BeadCommentUpdatedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_comment_updated"),
+  bead_id: exports_external.string(),
+  comment_id: exports_external.number(),
+  old_body: exports_external.string(),
+  new_body: exports_external.string(),
+  updated_by: exports_external.string()
+});
+var BeadCommentDeletedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_comment_deleted"),
+  bead_id: exports_external.string(),
+  comment_id: exports_external.number(),
+  deleted_by: exports_external.string(),
+  reason: exports_external.string().optional()
+});
+var BeadEpicChildAddedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_epic_child_added"),
+  bead_id: exports_external.string(),
+  child_id: exports_external.string(),
+  child_index: exports_external.number().optional(),
+  added_by: exports_external.string().optional()
+});
+var BeadEpicChildRemovedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_epic_child_removed"),
+  bead_id: exports_external.string(),
+  child_id: exports_external.string(),
+  removed_by: exports_external.string().optional(),
+  reason: exports_external.string().optional()
+});
+var BeadEpicClosureEligibleEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_epic_closure_eligible"),
+  bead_id: exports_external.string(),
+  child_ids: exports_external.array(exports_external.string()),
+  total_duration_ms: exports_external.number().optional(),
+  all_files_touched: exports_external.array(exports_external.string()).optional()
+});
+var BeadAssignedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_assigned"),
+  bead_id: exports_external.string(),
+  agent_name: exports_external.string(),
+  task_description: exports_external.string().optional()
+});
+var BeadWorkStartedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_work_started"),
+  bead_id: exports_external.string(),
+  agent_name: exports_external.string(),
+  reserved_files: exports_external.array(exports_external.string()).optional()
+});
+var BeadCompactedEventSchema = BaseBeadEventSchema.extend({
+  type: exports_external.literal("bead_compacted"),
+  bead_id: exports_external.string(),
+  events_archived: exports_external.number(),
+  new_start_sequence: exports_external.number()
+});
+var BeadEventSchema = exports_external.discriminatedUnion("type", [
+  BeadCreatedEventSchema,
+  BeadUpdatedEventSchema,
+  BeadStatusChangedEventSchema,
+  BeadClosedEventSchema,
+  BeadReopenedEventSchema,
+  BeadDeletedEventSchema,
+  BeadDependencyAddedEventSchema,
+  BeadDependencyRemovedEventSchema,
+  BeadLabelAddedEventSchema,
+  BeadLabelRemovedEventSchema,
+  BeadCommentAddedEventSchema,
+  BeadCommentUpdatedEventSchema,
+  BeadCommentDeletedEventSchema,
+  BeadEpicChildAddedEventSchema,
+  BeadEpicChildRemovedEventSchema,
+  BeadEpicClosureEligibleEventSchema,
+  BeadAssignedEventSchema,
+  BeadWorkStartedEventSchema,
+  BeadCompactedEventSchema
+]);
+function createBeadEvent(type, data) {
+  const event = {
+    type,
+    timestamp: Date.now(),
+    ...data
+  };
+  const result = BeadEventSchema.safeParse(event);
+  if (!result.success) {
+    throw new Error(`Invalid bead event: ${result.error.message}`);
+  }
+  return result.data;
+}
+function isBeadEventType(event, type) {
+  return event.type === type;
+}
+function getBeadIdFromEvent(event) {
+  return event.bead_id;
+}
+function isStateTransitionEvent(event) {
+  return event.type === "bead_status_changed" || event.type === "bead_closed" || event.type === "bead_reopened";
+}
+function isEpicEvent(event) {
+  return event.type === "bead_epic_child_added" || event.type === "bead_epic_child_removed" || event.type === "bead_epic_closure_eligible";
+}
+function isAgentEvent(event) {
+  if ("agent_name" in event)
+    return true;
+  const actorFields = [
+    "created_by",
+    "updated_by",
+    "changed_by",
+    "closed_by",
+    "deleted_by",
+    "added_by",
+    "removed_by",
+    "reopened_by"
+  ];
+  return actorFields.some((field) => {
+    if (field in event) {
+      const value = event[field];
+      return typeof value === "string" && /^[a-z]+$/i.test(value);
+    }
+    return false;
+  });
+}
 // src/beads.ts
 import { createEvent, appendEvent } from "swarm-mail";
 var beadsWorkingDirectory = null;
@@ -30694,10 +30922,222 @@ class DecompositionError extends SwarmError {
     this.zodError = zodError;
   }
 }
+var swarm_plan_interactive = tool({
+  description: "Interactive planning phase with Socratic questioning before decomposition. Supports multiple modes from full interactive to auto-proceed.",
+  args: {
+    task: tool.schema.string().min(1).describe("The task to plan"),
+    mode: tool.schema.enum(["socratic", "fast", "auto", "confirm-only"]).default("socratic").describe("Planning mode: socratic (full), fast (skip questions), auto (minimal), confirm-only (single yes/no)"),
+    context: tool.schema.string().optional().describe("Optional additional context about the task"),
+    user_response: tool.schema.string().optional().describe("User's response to a previous question (for multi-turn socratic mode)"),
+    phase: tool.schema.enum(["questioning", "alternatives", "recommendation", "ready"]).optional().describe("Current planning phase (for resuming multi-turn interaction)")
+  },
+  async execute(args) {
+    const { selectStrategy: selectStrategy2, formatStrategyGuidelines: formatStrategyGuidelines2, STRATEGIES: STRATEGIES2 } = await Promise.resolve().then(() => (init_swarm_strategies(), exports_swarm_strategies));
+    const { formatMemoryQueryForDecomposition: formatMemoryQueryForDecomposition2 } = await Promise.resolve().then(() => (init_learning(), exports_learning));
+    const currentPhase = args.phase || "questioning";
+    const mode = args.mode || "socratic";
+    let memoryContext = "";
+    let codebaseContext = {};
+    try {
+      const memoryQuery = formatMemoryQueryForDecomposition2(args.task, 3);
+      memoryContext = `[Memory Query Instruction]
+${memoryQuery.instruction}
+Query: "${memoryQuery.query}"
+Limit: ${memoryQuery.limit}`;
+    } catch (error45) {
+      console.warn("[swarm_plan_interactive] Memory query formatting failed:", error45);
+    }
+    try {
+      const gitResult = await Bun.$`git status --short`.quiet().nothrow();
+      if (gitResult.exitCode === 0) {
+        codebaseContext.git_status = gitResult.stdout.toString().trim();
+      }
+    } catch (error45) {}
+    if (mode === "fast") {
+      const strategyResult = selectStrategy2(args.task);
+      const guidelines = formatStrategyGuidelines2(strategyResult.strategy);
+      const output = {
+        mode: "fast",
+        phase: "ready",
+        recommendation: {
+          approach: strategyResult.strategy,
+          reasoning: `${strategyResult.reasoning}
+
+${guidelines}`
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: true,
+        next_action: "Proceed to swarm_decompose or swarm_delegate_planning"
+      };
+      return JSON.stringify(output, null, 2);
+    }
+    if (mode === "auto") {
+      const strategyResult = selectStrategy2(args.task);
+      const output = {
+        mode: "auto",
+        phase: "ready",
+        recommendation: {
+          approach: strategyResult.strategy,
+          reasoning: `Auto-selected based on task keywords: ${strategyResult.reasoning}`
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: true,
+        next_action: "Auto-proceeding to decomposition"
+      };
+      return JSON.stringify(output, null, 2);
+    }
+    if (mode === "confirm-only") {
+      const output = {
+        mode: "confirm-only",
+        phase: "ready",
+        recommendation: {
+          approach: "Will generate decomposition for your review",
+          reasoning: "Use swarm_delegate_planning to generate the plan, then present it for yes/no confirmation"
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: false,
+        next_action: "Call swarm_delegate_planning, then show result and ask for confirmation"
+      };
+      return JSON.stringify(output, null, 2);
+    }
+    if (currentPhase === "questioning") {
+      const taskLower = args.task.toLowerCase();
+      const questions = [];
+      const isVague = {
+        noFiles: !taskLower.includes("src/") && !taskLower.includes("file"),
+        vagueVerb: taskLower.includes("improve") || taskLower.includes("fix") || taskLower.includes("update") || taskLower.includes("make better"),
+        noSuccessCriteria: !taskLower.includes("test") && !taskLower.includes("verify")
+      };
+      if (isVague.noFiles) {
+        questions.push({
+          question: "Which part of the codebase should this change affect?",
+          options: [
+            "Core functionality (src/)",
+            "UI components (components/)",
+            "API routes (app/api/)",
+            "Configuration and tooling",
+            "Tests"
+          ]
+        });
+      } else if (isVague.vagueVerb) {
+        questions.push({
+          question: "What specific change are you looking for?",
+          options: [
+            "Add new functionality",
+            "Modify existing behavior",
+            "Remove/deprecate something",
+            "Refactor without behavior change",
+            "Fix a bug"
+          ]
+        });
+      } else if (isVague.noSuccessCriteria) {
+        questions.push({
+          question: "How will we know this task is complete?",
+          options: [
+            "All tests pass",
+            "Feature works as demonstrated",
+            "Code review approved",
+            "Documentation updated",
+            "Performance target met"
+          ]
+        });
+      }
+      if (questions.length === 0) {
+        const output2 = {
+          mode: "socratic",
+          phase: "alternatives",
+          memory_context: memoryContext || undefined,
+          codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+          ready_to_decompose: false,
+          next_action: "Task is clear. Call again with phase=alternatives to explore approaches"
+        };
+        return JSON.stringify(output2, null, 2);
+      }
+      const output = {
+        mode: "socratic",
+        phase: "questioning",
+        questions: [questions[0]],
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: false,
+        next_action: "User should answer this question, then call again with user_response"
+      };
+      return JSON.stringify(output, null, 2);
+    }
+    if (currentPhase === "alternatives") {
+      const strategyResult = selectStrategy2(args.task);
+      const alternatives = [];
+      alternatives.push({
+        name: strategyResult.strategy,
+        description: strategyResult.reasoning,
+        tradeoffs: `Confidence: ${(strategyResult.confidence * 100).toFixed(0)}%. ${STRATEGIES2[strategyResult.strategy].description}`
+      });
+      for (let i = 0;i < Math.min(2, strategyResult.alternatives.length); i++) {
+        const alt = strategyResult.alternatives[i];
+        alternatives.push({
+          name: alt.strategy,
+          description: STRATEGIES2[alt.strategy].description,
+          tradeoffs: `Match score: ${alt.score}. ${STRATEGIES2[alt.strategy].antiPatterns[0] || "Consider trade-offs carefully"}`
+        });
+      }
+      const output = {
+        mode: "socratic",
+        phase: "alternatives",
+        alternatives,
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: false,
+        next_action: "User should choose an approach, then call again with phase=recommendation"
+      };
+      return JSON.stringify(output, null, 2);
+    }
+    if (currentPhase === "recommendation") {
+      const strategyResult = selectStrategy2(args.task);
+      const guidelines = formatStrategyGuidelines2(strategyResult.strategy);
+      const output = {
+        mode: "socratic",
+        phase: "recommendation",
+        recommendation: {
+          approach: strategyResult.strategy,
+          reasoning: `Based on your input and task analysis:
+
+${strategyResult.reasoning}
+
+${guidelines}`
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: false,
+        next_action: "User should confirm to proceed. Then call again with phase=ready"
+      };
+      return JSON.stringify(output, null, 2);
+    }
+    if (currentPhase === "ready") {
+      const output = {
+        mode: "socratic",
+        phase: "ready",
+        recommendation: {
+          approach: "Confirmed by user",
+          reasoning: "Ready to proceed with decomposition"
+        },
+        memory_context: memoryContext || undefined,
+        codebase_context: Object.keys(codebaseContext).length > 0 ? codebaseContext : undefined,
+        ready_to_decompose: true,
+        next_action: "Proceed to swarm_decompose or swarm_delegate_planning"
+      };
+      return JSON.stringify(output, null, 2);
+    }
+    throw new Error(`Invalid planning phase: ${currentPhase}`);
+  }
+});
 var decomposeTools = {
   swarm_decompose,
   swarm_validate_decomposition,
-  swarm_delegate_planning
+  swarm_delegate_planning,
+  swarm_plan_interactive
 };
 // src/swarm-prompts.ts
 init_dist();
@@ -30863,13 +31303,11 @@ Only modify these files. Need others? Message the coordinator.
 
 {error_context}
 
-## [MANDATORY: SWARM MAIL INITIALIZATION]
-
-**CRITICAL: YOU MUST INITIALIZE SWARM MAIL BEFORE DOING ANY WORK.**
+## [MANDATORY SURVIVAL CHECKLIST]
 
-This is your FIRST step - before reading files, before planning, before ANY other action.
+**CRITICAL: Follow this checklist IN ORDER. Each step builds on the previous.**
 
-### Step 1: Initialize (REQUIRED - DO THIS FIRST)
+### Step 1: Initialize Coordination (REQUIRED - DO THIS FIRST)
 \`\`\`
 swarmmail_init(project_path="{project_path}", task_description="{bead_id}: {subtask_title}")
 \`\`\`
@@ -30882,26 +31320,124 @@ swarmmail_init(project_path="{project_path}", task_description="{bead_id}: {subt
 
 **If you skip this step, your work will not be tracked and swarm_complete will fail.**
 
-## [SWARM MAIL USAGE]
+### Step 2: Query Past Learnings (BEFORE starting work)
+\`\`\`
+semantic-memory_find(query="<keywords from your task>", limit=5)
+\`\`\`
 
-After initialization, use Swarm Mail for coordination:
+**Check if past agents solved similar problems.** Search for:
+- Error messages if debugging
+- Domain concepts (e.g., "authentication", "caching")
+- Technology stack (e.g., "Next.js", "React")
+- Patterns (e.g., "event sourcing", "validation")
 
-### Check Inbox Regularly
+**Past learnings save time and prevent repeating mistakes.**
+
+### Step 3: Load Relevant Skills (if available)
 \`\`\`
-swarmmail_inbox()  # Check for coordinator messages
-swarmmail_read_message(message_id=N)  # Read specific message
+skills_list()  # See what skills exist
+skills_use(name="<relevant-skill>", context="<your task>")  # Load skill
 \`\`\`
 
-### Report Progress (REQUIRED - don't work silently)
+**Common skill triggers:**
+- Writing tests? → \`skills_use(name="testing-patterns")\`
+- Breaking dependencies? → \`skills_use(name="testing-patterns")\`
+- Multi-agent coordination? → \`skills_use(name="swarm-coordination")\`
+- Building a CLI? → \`skills_use(name="cli-builder")\`
+
+### Step 4: Reserve Your Files (YOU reserve, not coordinator)
 \`\`\`
-swarmmail_send(
-  to=["coordinator"],
-  subject="Progress: {bead_id}",
-  body="<what you did, blockers, questions>",
-  thread_id="{epic_id}"
+swarmmail_reserve(
+  paths=[{file_list}],
+  reason="{bead_id}: {subtask_title}",
+  exclusive=true
+)
+\`\`\`
+
+**Workers reserve their own files.** This prevents edit conflicts with other agents.
+
+### Step 5: Do the Work
+- Read your assigned files
+- Implement changes
+- Verify (typecheck if applicable)
+
+### Step 6: Report Progress at Milestones
+\`\`\`
+swarm_progress(
+  project_key="{project_path}",
+  agent_name="<your-agent-name>",
+  bead_id="{bead_id}",
+  status="in_progress",
+  progress_percent=25,  # or 50, 75
+  message="<what you just completed>"
+)
+\`\`\`
+
+**Report at 25%, 50%, 75% completion.** This:
+- Triggers auto-checkpoint (saves context)
+- Keeps coordinator informed
+- Prevents silent failures
+
+### Step 7: Manual Checkpoint BEFORE Risky Operations
+\`\`\`
+swarm_checkpoint(
+  project_key="{project_path}",
+  agent_name="<your-agent-name>",
+  bead_id="{bead_id}"
+)
+\`\`\`
+
+**Call BEFORE:**
+- Large refactors
+- File deletions
+- Breaking API changes
+- Anything that might fail catastrophically
+
+**Checkpoints preserve context so you can recover if things go wrong.**
+
+### Step 8: Store Learnings (if you discovered something)
+\`\`\`
+semantic-memory_store(
+  information="<what you learned, WHY it matters, how to apply it>",
+  metadata="<tags: domain, tech-stack, pattern-type>"
 )
 \`\`\`
 
+**Store:**
+- Tricky bugs you solved (root cause + solution)
+- Project-specific patterns or domain rules
+- Tool/library gotchas and workarounds
+- Failed approaches (anti-patterns to avoid)
+
+**Don't store generic knowledge.** Store the WHY, not just the WHAT.
+
+### Step 9: Complete (REQUIRED - releases reservations)
+\`\`\`
+swarm_complete(
+  project_key="{project_path}",
+  agent_name="<your-agent-name>",
+  bead_id="{bead_id}",
+  summary="<what you accomplished>",
+  files_touched=["list", "of", "files"]
+)
+\`\`\`
+
+**This automatically:**
+- Runs UBS bug scan
+- Releases file reservations
+- Records learning signals
+- Notifies coordinator
+
+**DO NOT manually close the bead with beads_close.** Use swarm_complete.
+
+## [SWARM MAIL COMMUNICATION]
+
+### Check Inbox Regularly
+\`\`\`
+swarmmail_inbox()  # Check for coordinator messages
+swarmmail_read_message(message_id=N)  # Read specific message
+\`\`\`
+
 ### When Blocked
 \`\`\`
 swarmmail_send(
@@ -30914,42 +31450,48 @@ swarmmail_send(
 beads_update(id="{bead_id}", status="blocked")
 \`\`\`
 
-### Release Files When Done
+### Report Issues to Other Agents
 \`\`\`
-swarmmail_release()  # Or let swarm_complete handle it
+swarmmail_send(
+  to=["OtherAgent", "coordinator"],
+  subject="Issue in {bead_id}",
+  body="<describe problem, don't fix their code>",
+  thread_id="{epic_id}"
+)
+\`\`\`
+
+### Manual Release (if needed)
 \`\`\`
+swarmmail_release()  # Manually release reservations
+\`\`\`
+
+**Note:** \`swarm_complete\` automatically releases reservations. Only use manual release if aborting work.
 
 ## [OTHER TOOLS]
 ### Beads
 - beads_update(id, status) - Mark blocked if stuck
 - beads_create(title, type) - Log new bugs found
 
-### Skills (if available)
+### Skills
 - skills_list() - Discover available skills
 - skills_use(name) - Activate skill for specialized guidance
+- skills_create(name) - Create new skill (if you found a reusable pattern)
 
-### Completion (REQUIRED)
-- swarm_complete(project_key, agent_name, bead_id, summary, files_touched)
-
-## [LEARNING]
-As you work, note reusable patterns, best practices, or domain insights:
-- If you discover something that would help future agents, consider creating a skill
-- Use skills_create to codify patterns for the project
-- Good skills have clear "when to use" descriptions with actionable instructions
-- Skills make swarms smarter over time
-
-## [WORKFLOW]
-1. **swarmmail_init** - Initialize session (MANDATORY FIRST STEP)
-2. Read assigned files
-3. Implement changes
-4. **swarmmail_send** - Report progress to coordinator
-5. Verify (typecheck)
-6. **swarm_complete** - Mark done, release reservations
-
-**CRITICAL REQUIREMENTS:**
-- Step 1 (swarmmail_init) is NON-NEGOTIABLE - do it before anything else
-- Never work silently - send progress updates via swarmmail_send every significant milestone
-- If you complete without initializing, swarm_complete will detect this and warn/fail
+## [CRITICAL REQUIREMENTS]
+
+**NON-NEGOTIABLE:**
+1. Step 1 (swarmmail_init) MUST be first - do it before anything else
+2. Step 2 (semantic-memory_find) MUST happen before starting work
+3. Step 4 (swarmmail_reserve) - YOU reserve files, not coordinator
+4. Step 6 (swarm_progress) - Report at milestones, don't work silently
+5. Step 9 (swarm_complete) - Use this to close, NOT beads_close
+
+**If you skip these steps:**
+- Your work won't be tracked (swarm_complete will fail)
+- You'll waste time repeating solved problems (no semantic memory query)
+- Edit conflicts with other agents (no file reservation)
+- Lost work if you crash (no checkpoints)
+- Future agents repeat your mistakes (no learnings stored)
 
 Begin now.`;
 var EVALUATION_PROMPT = `Evaluate the work completed for this subtask.
@@ -31671,26 +32213,6 @@ var swarm_progress = tool({
             ...checkpoint
           });
           await appendEvent2(event, args.project_key);
-          const { getDatabase } = await import("swarm-mail");
-          const db = await getDatabase(args.project_key);
-          const now = Date.now();
-          await db.query(`INSERT INTO swarm_contexts (id, epic_id, bead_id, strategy, files, dependencies, directives, recovery, created_at, updated_at)
-             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
-             ON CONFLICT (id) DO UPDATE SET
-               files = EXCLUDED.files,
-               recovery = EXCLUDED.recovery,
-               updated_at = EXCLUDED.updated_at`, [
-            args.bead_id,
-            epicId,
-            args.bead_id,
-            checkpoint.strategy,
-            JSON.stringify(checkpoint.files),
-            JSON.stringify(checkpoint.dependencies),
-            JSON.stringify(checkpoint.directives),
-            JSON.stringify(checkpoint.recovery),
-            now,
-            now
-          ]);
           checkpointCreated = true;
         } catch (error45) {
           console.warn(`[swarm_progress] Auto-checkpoint failed at ${args.progress_percent}%:`, error45);
@@ -31853,7 +32375,23 @@ Continuing with completion, but this should be fixed for future subtasks.`;
       }
       const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.quiet().nothrow();
       if (closeResult.exitCode !== 0) {
-        throw new Error(`Failed to close bead because bd close command failed: ${closeResult.stderr.toString()}. Try: Verify bead exists and is not already closed with 'bd show ${args.bead_id}', check if bead ID is correct with 'beads_query()', or use beads_close tool directly.`);
+        const stderrOutput = closeResult.stderr.toString().trim();
+        return JSON.stringify({
+          success: false,
+          error: "Failed to close bead",
+          failed_step: "bd close",
+          details: stderrOutput || "Unknown error from bd close command",
+          bead_id: args.bead_id,
+          recovery: {
+            steps: [
+              `1. Check bead exists: bd show ${args.bead_id}`,
+              `2. Check bead status (might already be closed): beads_query()`,
+              `3. If bead is blocked, unblock first: beads_update(id="${args.bead_id}", status="in_progress")`,
+              `4. Try closing directly: beads_close(id="${args.bead_id}", reason="...")`
+            ],
+            hint: "If bead is in 'blocked' status, you must change it to 'in_progress' or 'open' before closing."
+          }
+        }, null, 2);
       }
       try {
         const epicId3 = args.bead_id.includes(".") ? args.bead_id.split(".")[0] : args.bead_id;
@@ -32026,6 +32564,7 @@ ${errorStack.slice(0, 1000)}
         "4. Retry swarm_complete after fixing"
       ].filter(Boolean).join(`
 `);
+      let notificationSent = false;
       try {
         await sendSwarmMessage2({
           projectPath: args.project_key,
@@ -32036,11 +32575,40 @@ ${errorStack.slice(0, 1000)}
           threadId: epicId,
           importance: "urgent"
         });
+        notificationSent = true;
       } catch (mailError) {
         console.error(`[swarm_complete] CRITICAL: Failed to notify coordinator of failure for ${args.bead_id}:`, mailError);
         console.error(`[swarm_complete] Original error:`, error45);
       }
-      throw error45;
+      return JSON.stringify({
+        success: false,
+        error: errorMessage,
+        failed_step: failedStep,
+        bead_id: args.bead_id,
+        agent_name: args.agent_name,
+        coordinator_notified: notificationSent,
+        stack_trace: errorStack?.slice(0, 500),
+        context: {
+          summary: args.summary,
+          files_touched: args.files_touched || [],
+          skip_ubs_scan: args.skip_ubs_scan ?? false,
+          skip_verification: args.skip_verification ?? false
+        },
+        recovery: {
+          steps: [
+            "1. Check the error message above for specific issue",
+            `2. Review failed step: ${failedStep}`,
+            "3. Fix underlying issue or use skip flags if appropriate",
+            "4. Retry swarm_complete after fixing"
+          ],
+          common_fixes: {
+            "Verification Gate": "Use skip_verification=true to bypass (not recommended)",
+            "UBS scan": "Use skip_ubs_scan=true to bypass",
+            "Bead close": "Check bead status with beads_query(), may need beads_update() first",
+            "Self-evaluation": "Check evaluation JSON format matches EvaluationSchema"
+          }
+        }
+      }, null, 2);
     }
   }
 });
@@ -32312,26 +32880,7 @@ var swarm_checkpoint = tool({
         recovery: checkpoint.recovery
       });
       await appendEvent2(event, args.project_key);
-      const { getDatabase } = await import("swarm-mail");
-      const db = await getDatabase(args.project_key);
       const now = Date.now();
-      await db.query(`INSERT INTO swarm_contexts (id, epic_id, bead_id, strategy, files, dependencies, directives, recovery, created_at, updated_at)
-         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
-         ON CONFLICT (id) DO UPDATE SET
-           files = EXCLUDED.files,
-           recovery = EXCLUDED.recovery,
-           updated_at = EXCLUDED.updated_at`, [
-        args.bead_id,
-        args.epic_id,
-        args.bead_id,
-        checkpoint.strategy,
-        JSON.stringify(checkpoint.files),
-        JSON.stringify(checkpoint.dependencies),
-        JSON.stringify(checkpoint.directives),
-        JSON.stringify(checkpoint.recovery),
-        now,
-        now
-      ]);
       return JSON.stringify({
         success: true,
         checkpoint_timestamp: now,
@@ -32374,15 +32923,16 @@ var swarm_recover = tool({
         }, null, 2);
       }
       const row = result.rows[0];
+      const parseIfString = (val) => typeof val === "string" ? JSON.parse(val) : val;
       const context = {
         id: row.id,
         epic_id: row.epic_id,
         bead_id: row.bead_id,
         strategy: row.strategy,
-        files: JSON.parse(row.files),
-        dependencies: JSON.parse(row.dependencies),
-        directives: JSON.parse(row.directives),
-        recovery: JSON.parse(row.recovery),
+        files: parseIfString(row.files),
+        dependencies: parseIfString(row.dependencies),
+        directives: parseIfString(row.directives),
+        recovery: parseIfString(row.recovery),
         created_at: row.created_at,
         updated_at: row.updated_at
       };
@@ -34410,9 +34960,13 @@ export {
   mandateSchemas,
   listSkills,
   isToolAvailable,
+  isStateTransitionEvent,
   isSemanticMemoryAvailable,
   isProjectNotFoundError,
+  isEpicEvent,
+  isBeadEventType,
   isAgentNotFoundError,
+  isAgentEvent,
   invalidateSkillsCache,
   ifToolAvailable,
   guardrailOutput,
@@ -34426,6 +34980,7 @@ export {
   getSchemaByName,
   getMandateStorage,
   getBeadsWorkingDirectory,
+  getBeadIdFromEvent,
   getAgentMailProjectDirectory,
   formatZodErrors,
   formatToolAvailability,
@@ -34444,6 +34999,7 @@ export {
   createStorage,
   createMetrics,
   createMandateStorage,
+  createBeadEvent,
   createAgentMailError,
   clearSessionState,
   checkTool,
@@ -34513,17 +35069,38 @@ export {
   CreateSwarmContextArgsSchema,
   CreateMandateArgsSchema,
   CastVoteArgsSchema,
+  BeadWorkStartedEventSchema,
   BeadValidationError,
+  BeadUpdatedEventSchema,
   BeadUpdateArgsSchema,
   BeadTypeSchema,
   BeadTreeSchema,
   BeadStatusSchema,
+  BeadStatusChangedEventSchema,
   BeadSchema,
+  BeadReopenedEventSchema,
   BeadQueryArgsSchema,
+  BeadLabelRemovedEventSchema,
+  BeadLabelAddedEventSchema,
+  BeadEventSchema,
   BeadError,
+  BeadEpicClosureEligibleEventSchema,
+  BeadEpicChildRemovedEventSchema,
+  BeadEpicChildAddedEventSchema,
   BeadDependencySchema,
+  BeadDependencyRemovedEventSchema,
+  BeadDependencyAddedEventSchema,
+  BeadDeletedEventSchema,
+  BeadCreatedEventSchema,
   BeadCreateArgsSchema,
+  BeadCompactedEventSchema,
+  BeadCommentUpdatedEventSchema,
+  BeadCommentDeletedEventSchema,
+  BeadCommentAddedEventSchema,
+  BeadClosedEventSchema,
   BeadCloseArgsSchema,
+  BeadAssignedEventSchema,
+  BaseBeadEventSchema,
   AgentProgressSchema,
   AgentMailNotInitializedError,
   AgentMailError