opencode-swarm-plugin 0.20.0 → 0.22.0

package/src/swarm-orchestrate.ts

@@ -37,6 +37,9 @@ import {
   releaseSwarmFiles,
   sendSwarmMessage,
 } from "./streams/swarm-mail";
+import { getAgent } from "./streams/projections";
+import { createEvent } from "./streams/events";
+import { appendEvent } from "./streams/store";
 import {
   addStrike,
   clearStrikes,
@@ -836,7 +839,74 @@ export const swarm_progress = tool({
       importance: args.status === "blocked" ? "high" : "normal",
     });
 
-    return `Progress reported: ${args.status}${args.progress_percent !== undefined ? ` (${args.progress_percent}%)` : ""}`;
+    // Auto-checkpoint at milestone progress (25%, 50%, 75%)
+    let checkpointCreated = false;
+    if (
+      args.progress_percent !== undefined &&
+      args.files_touched &&
+      args.files_touched.length > 0
+    ) {
+      const milestones = [25, 50, 75];
+      if (milestones.includes(args.progress_percent)) {
+        try {
+          // Create checkpoint event directly (non-fatal if it fails)
+          const checkpoint = {
+            epic_id: epicId,
+            bead_id: args.bead_id,
+            strategy: "file-based" as const,
+            files: args.files_touched,
+            dependencies: [] as string[],
+            directives: {},
+            recovery: {
+              last_checkpoint: Date.now(),
+              files_modified: args.files_touched,
+              progress_percent: args.progress_percent,
+              last_message: args.message,
+            },
+          };
+
+          const event = createEvent("swarm_checkpointed", {
+            project_key: args.project_key,
+            ...checkpoint,
+          });
+          await appendEvent(event, args.project_key);
+
+          // Update swarm_contexts table
+          const { getDatabase } = await import("./streams/index");
+          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 (error) {
+          // Non-fatal - log and continue
+          console.warn(
+            `[swarm_progress] Auto-checkpoint failed at ${args.progress_percent}%:`,
+            error,
+          );
+        }
+      }
+    }
+
+    return `Progress reported: ${args.status}${args.progress_percent !== undefined ? ` (${args.progress_percent}%)` : ""}${checkpointCreated ? " [checkpoint created]" : ""}`;
   },
 });
 
@@ -966,210 +1036,356 @@ export const swarm_complete = tool({
       .describe(
         "Skip ALL verification (UBS, typecheck, tests). Use sparingly! (default: false)",
       ),
+    planned_files: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files that were originally planned to be modified"),
+    start_time: tool.schema
+      .number()
+      .optional()
+      .describe("Task start timestamp (Unix ms) for duration calculation"),
+    error_count: tool.schema
+      .number()
+      .optional()
+      .describe("Number of errors encountered during task"),
+    retry_count: tool.schema
+      .number()
+      .optional()
+      .describe("Number of retry attempts during task"),
   },
   async execute(args) {
-    // Run Verification Gate unless explicitly skipped
-    let verificationResult: VerificationGateResult | null = null;
+    // Extract epic ID early for error notifications
+    const epicId = args.bead_id.includes(".")
+      ? args.bead_id.split(".")[0]
+      : args.bead_id;
 
-    if (!args.skip_verification && args.files_touched?.length) {
-      verificationResult = await runVerificationGate(
-        args.files_touched,
-        args.skip_ubs_scan ?? false,
-      );
+    try {
+      // Verify agent is registered in swarm-mail
+      // This catches agents who skipped swarmmail_init
+      const projectKey = args.project_key
+        .replace(/\//g, "-")
+        .replace(/\\/g, "-");
+      let agentRegistered = false;
+      let registrationWarning = "";
 
-      // Block completion if verification failed
-      if (!verificationResult.passed) {
-        return JSON.stringify(
-          {
-            success: false,
-            error: "Verification Gate FAILED - fix issues before completing",
-            verification: {
-              passed: false,
-              summary: verificationResult.summary,
-              blockers: verificationResult.blockers,
-              steps: verificationResult.steps.map((s) => ({
-                name: s.name,
-                passed: s.passed,
-                skipped: s.skipped,
-                skipReason: s.skipReason,
-                error: s.error?.slice(0, 200),
-              })),
-            },
-            hint:
-              verificationResult.blockers.length > 0
-                ? `Fix these issues: ${verificationResult.blockers.map((b, i) => `${i + 1}. ${b}`).join(", ")}. Use skip_verification=true only as last resort.`
-                : "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
-            gate_function:
-              "IDENTIFY → RUN → READ → VERIFY → CLAIM (you are at VERIFY, claim blocked)",
-          },
-          null,
-          2,
+      try {
+        const agent = await getAgent(
+          projectKey,
+          args.agent_name,
+          args.project_key,
         );
+        agentRegistered = agent !== null;
+
+        if (!agentRegistered) {
+          registrationWarning = `⚠️  WARNING: Agent '${args.agent_name}' was NOT registered in swarm-mail for project '${projectKey}'.
+
+This usually means you skipped the MANDATORY swarmmail_init step.
+
+**Impact:**
+- Your work was not tracked in the coordination system
+- File reservations may not have been managed
+- Other agents couldn't coordinate with you
+- Learning/eval data may be incomplete
+
+**Next time:** Run swarmmail_init(project_path="${args.project_key}", task_description="<task>") FIRST, before any other work.
+
+Continuing with completion, but this should be fixed for future subtasks.`;
+
+          console.warn(`[swarm_complete] ${registrationWarning}`);
+        }
+      } catch (error) {
+        // Non-fatal - agent might be using legacy workflow
+        console.warn(
+          `[swarm_complete] Could not verify agent registration:`,
+          error,
+        );
+        registrationWarning = `ℹ️  Could not verify swarm-mail registration (database may not be available). Consider running swarmmail_init next time.`;
       }
-    }
 
-    // Legacy UBS-only path for backward compatibility (when no files_touched)
-    let ubsResult: UbsScanResult | null = null;
-    if (
-      !args.skip_verification &&
-      !verificationResult &&
-      args.files_touched?.length &&
-      !args.skip_ubs_scan
-    ) {
-      ubsResult = await runUbsScan(args.files_touched);
+      // Run Verification Gate unless explicitly skipped
+      let verificationResult: VerificationGateResult | null = null;
 
-      // Block completion if critical bugs found
-      if (ubsResult && ubsResult.summary.critical > 0) {
-        return JSON.stringify(
-          {
-            success: false,
-            error: `UBS found ${ubsResult.summary.critical} critical bug(s) that must be fixed before completing`,
-            ubs_scan: {
-              critical_count: ubsResult.summary.critical,
-              bugs: ubsResult.bugs.filter((b) => b.severity === "critical"),
-            },
-            hint: `Fix these critical bugs: ${ubsResult.bugs
-              .filter((b) => b.severity === "critical")
-              .map((b) => `${b.file}:${b.line} - ${b.message}`)
-              .slice(0, 3)
-              .join(
-                "; ",
-              )}. Try: Run 'ubs scan ${args.files_touched?.join(" ") || "."} --json' for full report, fix reported issues, or use skip_ubs_scan=true to bypass (not recommended).`,
-          },
-          null,
-          2,
+      if (!args.skip_verification && args.files_touched?.length) {
+        verificationResult = await runVerificationGate(
+          args.files_touched,
+          args.skip_ubs_scan ?? false,
         );
+
+        // Block completion if verification failed
+        if (!verificationResult.passed) {
+          return JSON.stringify(
+            {
+              success: false,
+              error: "Verification Gate FAILED - fix issues before completing",
+              verification: {
+                passed: false,
+                summary: verificationResult.summary,
+                blockers: verificationResult.blockers,
+                steps: verificationResult.steps.map((s) => ({
+                  name: s.name,
+                  passed: s.passed,
+                  skipped: s.skipped,
+                  skipReason: s.skipReason,
+                  error: s.error?.slice(0, 200),
+                })),
+              },
+              hint:
+                verificationResult.blockers.length > 0
+                  ? `Fix these issues: ${verificationResult.blockers.map((b, i) => `${i + 1}. ${b}`).join(", ")}. Use skip_verification=true only as last resort.`
+                  : "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
+              gate_function:
+                "IDENTIFY → RUN → READ → VERIFY → CLAIM (you are at VERIFY, claim blocked)",
+            },
+            null,
+            2,
+          );
+        }
       }
-    }
 
-    // Parse and validate evaluation if provided
-    let parsedEvaluation: Evaluation | undefined;
-    if (args.evaluation) {
-      try {
-        parsedEvaluation = EvaluationSchema.parse(JSON.parse(args.evaluation));
-      } catch (error) {
-        return JSON.stringify(
-          {
-            success: false,
-            error: "Invalid evaluation format",
-            details: error instanceof z.ZodError ? error.issues : String(error),
-          },
-          null,
-          2,
+      // Legacy UBS-only path for backward compatibility (when no files_touched)
+      let ubsResult: UbsScanResult | null = null;
+      if (
+        !args.skip_verification &&
+        !verificationResult &&
+        args.files_touched?.length &&
+        !args.skip_ubs_scan
+      ) {
+        ubsResult = await runUbsScan(args.files_touched);
+
+        // Block completion if critical bugs found
+        if (ubsResult && ubsResult.summary.critical > 0) {
+          return JSON.stringify(
+            {
+              success: false,
+              error: `UBS found ${ubsResult.summary.critical} critical bug(s) that must be fixed before completing`,
+              ubs_scan: {
+                critical_count: ubsResult.summary.critical,
+                bugs: ubsResult.bugs.filter((b) => b.severity === "critical"),
+              },
+              hint: `Fix these critical bugs: ${ubsResult.bugs
+                .filter((b) => b.severity === "critical")
+                .map((b) => `${b.file}:${b.line} - ${b.message}`)
+                .slice(0, 3)
+                .join(
+                  "; ",
+                )}. Try: Run 'ubs scan ${args.files_touched?.join(" ") || "."} --json' for full report, fix reported issues, or use skip_ubs_scan=true to bypass (not recommended).`,
+            },
+            null,
+            2,
+          );
+        }
+      }
+
+      // Parse and validate evaluation if provided
+      let parsedEvaluation: Evaluation | undefined;
+      if (args.evaluation) {
+        try {
+          parsedEvaluation = EvaluationSchema.parse(
+            JSON.parse(args.evaluation),
+          );
+        } catch (error) {
+          return JSON.stringify(
+            {
+              success: false,
+              error: "Invalid evaluation format",
+              details:
+                error instanceof z.ZodError ? error.issues : String(error),
+            },
+            null,
+            2,
+          );
+        }
+
+        // If evaluation failed, don't complete
+        if (!parsedEvaluation.passed) {
+          return JSON.stringify(
+            {
+              success: false,
+              error: "Self-evaluation failed",
+              retry_suggestion: parsedEvaluation.retry_suggestion,
+              feedback: parsedEvaluation.overall_feedback,
+            },
+            null,
+            2,
+          );
+        }
+      }
+
+      // Close the bead
+      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.`,
         );
       }
 
-      // If evaluation failed, don't complete
-      if (!parsedEvaluation.passed) {
-        return JSON.stringify(
-          {
-            success: false,
-            error: "Self-evaluation failed",
-            retry_suggestion: parsedEvaluation.retry_suggestion,
-            feedback: parsedEvaluation.overall_feedback,
-          },
-          null,
-          2,
+      // Emit SubtaskOutcomeEvent for learning system
+      try {
+        const epicId = args.bead_id.includes(".")
+          ? args.bead_id.split(".")[0]
+          : args.bead_id;
+
+        const durationMs = args.start_time ? Date.now() - args.start_time : 0;
+
+        const event = createEvent("subtask_outcome", {
+          project_key: args.project_key,
+          epic_id: epicId,
+          bead_id: args.bead_id,
+          planned_files: args.planned_files || [],
+          actual_files: args.files_touched || [],
+          duration_ms: durationMs,
+          error_count: args.error_count || 0,
+          retry_count: args.retry_count || 0,
+          success: true,
+        });
+        await appendEvent(event, args.project_key);
+      } catch (error) {
+        // Non-fatal - log and continue
+        console.warn(
+          "[swarm_complete] Failed to emit SubtaskOutcomeEvent:",
+          error,
         );
       }
-    }
 
-    // Close the bead
-    const closeResult =
-      await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`
-        .quiet()
-        .nothrow();
+      // Automatic memory capture (MANDATORY on successful completion)
+      // Extract strategy from bead metadata if available
+      let capturedStrategy: LearningDecompositionStrategy | undefined;
+      const durationMs = args.start_time ? Date.now() - args.start_time : 0;
 
-    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.`,
+      // Build memory information from task completion
+      const memoryInfo = formatMemoryStoreOnSuccess(
+        args.bead_id,
+        args.summary,
+        args.files_touched || [],
+        capturedStrategy,
       );
-    }
 
-    // Release file reservations for this agent using embedded swarm-mail
-    try {
-      await releaseSwarmFiles({
-        projectPath: args.project_key,
-        agentName: args.agent_name,
-        // Release all reservations for this agent
-      });
-    } catch (error) {
-      // Release might fail (e.g., no reservations existed)
-      // This is non-fatal - log and continue
-      console.warn(
-        `[swarm] Failed to release file reservations for ${args.agent_name}:`,
-        error,
-      );
-    }
+      let memoryStored = false;
+      let memoryError: string | undefined;
 
-    // Extract epic ID
-    const epicId = args.bead_id.includes(".")
-      ? args.bead_id.split(".")[0]
-      : args.bead_id;
+      // Attempt to store in semantic-memory (non-blocking)
+      try {
+        const memoryAvailable = await isToolAvailable("semantic-memory");
+        if (memoryAvailable) {
+          // Call semantic-memory store command
+          const storeResult =
+            await Bun.$`semantic-memory store ${memoryInfo.information} --metadata ${memoryInfo.metadata}`
+              .quiet()
+              .nothrow();
+
+          if (storeResult.exitCode === 0) {
+            memoryStored = true;
+            console.log(
+              `[swarm_complete] Stored learning for ${args.bead_id} in semantic-memory`,
+            );
+          } else {
+            memoryError = `semantic-memory store failed: ${storeResult.stderr.toString().slice(0, 200)}`;
+            console.warn(`[swarm_complete] ${memoryError}`);
+          }
+        } else {
+          memoryError =
+            "semantic-memory not available - learning stored in-memory only";
+          warnMissingTool("semantic-memory");
+        }
+      } catch (error) {
+        memoryError = `Failed to store memory: ${error instanceof Error ? error.message : String(error)}`;
+        console.warn(`[swarm_complete] ${memoryError}`);
+      }
 
-    // Send completion message using embedded swarm-mail
-    const completionBody = [
-      `## Subtask Complete: ${args.bead_id}`,
-      "",
-      `**Summary**: ${args.summary}`,
-      "",
-      parsedEvaluation
-        ? `**Self-Evaluation**: ${parsedEvaluation.passed ? "PASSED" : "FAILED"}`
-        : "",
-      parsedEvaluation?.overall_feedback
-        ? `**Feedback**: ${parsedEvaluation.overall_feedback}`
-        : "",
-    ]
-      .filter(Boolean)
-      .join("\n");
+      // Release file reservations for this agent using embedded swarm-mail
+      try {
+        await releaseSwarmFiles({
+          projectPath: args.project_key,
+          agentName: args.agent_name,
+          // Release all reservations for this agent
+        });
+      } catch (error) {
+        // Release might fail (e.g., no reservations existed)
+        // This is non-fatal - log and continue
+        console.warn(
+          `[swarm] Failed to release file reservations for ${args.agent_name}:`,
+          error,
+        );
+      }
 
-    await sendSwarmMessage({
-      projectPath: args.project_key,
-      fromAgent: args.agent_name,
-      toAgents: [], // Thread broadcast
-      subject: `Complete: ${args.bead_id}`,
-      body: completionBody,
-      threadId: epicId,
-      importance: "normal",
-    });
+      // Extract epic ID
+      const epicId = args.bead_id.includes(".")
+        ? args.bead_id.split(".")[0]
+        : args.bead_id;
+
+      // Send completion message using embedded swarm-mail with memory capture status
+      const completionBody = [
+        `## Subtask Complete: ${args.bead_id}`,
+        "",
+        `**Summary**: ${args.summary}`,
+        "",
+        parsedEvaluation
+          ? `**Self-Evaluation**: ${parsedEvaluation.passed ? "PASSED" : "FAILED"}`
+          : "",
+        parsedEvaluation?.overall_feedback
+          ? `**Feedback**: ${parsedEvaluation.overall_feedback}`
+          : "",
+        "",
+        `**Memory Capture**: ${memoryStored ? "✓ Stored in semantic-memory" : `✗ ${memoryError || "Failed"}`}`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+
+      await sendSwarmMessage({
+        projectPath: args.project_key,
+        fromAgent: args.agent_name,
+        toAgents: [], // Thread broadcast
+        subject: `Complete: ${args.bead_id}`,
+        body: completionBody,
+        threadId: epicId,
+        importance: "normal",
+      });
 
-    // Build success response with semantic-memory integration
-    const response = {
-      success: true,
-      bead_id: args.bead_id,
-      closed: true,
-      reservations_released: true,
-      message_sent: true,
-      verification_gate: verificationResult
-        ? {
-            passed: true,
-            summary: verificationResult.summary,
-            steps: verificationResult.steps.map((s) => ({
-              name: s.name,
-              passed: s.passed,
-              skipped: s.skipped,
-              skipReason: s.skipReason,
-            })),
-          }
-        : args.skip_verification
-          ? { skipped: true, reason: "skip_verification=true" }
-          : { skipped: true, reason: "no files_touched provided" },
-      ubs_scan: ubsResult
-        ? {
-            ran: true,
-            bugs_found: ubsResult.summary.total,
-            summary: ubsResult.summary,
-            warnings: ubsResult.bugs.filter((b) => b.severity !== "critical"),
-          }
-        : verificationResult
-          ? { ran: true, included_in_verification_gate: true }
-          : {
-              ran: false,
-              reason: args.skip_ubs_scan
-                ? "skipped"
-                : "no files or ubs unavailable",
-            },
-      learning_prompt: `## Reflection
+      // Build success response with semantic-memory integration
+      const response = {
+        success: true,
+        bead_id: args.bead_id,
+        closed: true,
+        reservations_released: true,
+        message_sent: true,
+        agent_registration: {
+          verified: agentRegistered,
+          warning: registrationWarning || undefined,
+        },
+        verification_gate: verificationResult
+          ? {
+              passed: true,
+              summary: verificationResult.summary,
+              steps: verificationResult.steps.map((s) => ({
+                name: s.name,
+                passed: s.passed,
+                skipped: s.skipped,
+                skipReason: s.skipReason,
+              })),
+            }
+          : args.skip_verification
+            ? { skipped: true, reason: "skip_verification=true" }
+            : { skipped: true, reason: "no files_touched provided" },
+        ubs_scan: ubsResult
+          ? {
+              ran: true,
+              bugs_found: ubsResult.summary.total,
+              summary: ubsResult.summary,
+              warnings: ubsResult.bugs.filter((b) => b.severity !== "critical"),
+            }
+          : verificationResult
+            ? { ran: true, included_in_verification_gate: true }
+            : {
+                ran: false,
+                reason: args.skip_ubs_scan
+                  ? "skipped"
+                  : "no files or ubs unavailable",
+              },
+        learning_prompt: `## Reflection
 
 Did you learn anything reusable during this subtask? Consider:
 
@@ -1181,15 +1397,110 @@ Did you learn anything reusable during this subtask? Consider:
 If you discovered something valuable, use \`swarm_learn\` or \`skills_create\` to preserve it as a skill for future swarms.
 
 Files touched: ${args.files_touched?.join(", ") || "none recorded"}`,
-      // Add semantic-memory integration on success
-      memory_store: formatMemoryStoreOnSuccess(
-        args.bead_id,
-        args.summary,
-        args.files_touched || [],
-      ),
-    };
+        // Automatic memory capture (MANDATORY)
+        memory_capture: {
+          attempted: true,
+          stored: memoryStored,
+          error: memoryError,
+          information: memoryInfo.information,
+          metadata: memoryInfo.metadata,
+          note: memoryStored
+            ? "Learning automatically stored in semantic-memory"
+            : `Failed to store: ${memoryError}. Learning lost unless semantic-memory is available.`,
+        },
+      };
 
-    return JSON.stringify(response, null, 2);
+      return JSON.stringify(response, null, 2);
+    } catch (error) {
+      // CRITICAL: Notify coordinator of failure via swarm mail
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      const errorStack = error instanceof Error ? error.stack : undefined;
+
+      // Determine which step failed
+      let failedStep = "unknown";
+      if (errorMessage.includes("verification")) {
+        failedStep = "Verification Gate (UBS/typecheck/tests)";
+      } else if (errorMessage.includes("UBS") || errorMessage.includes("ubs")) {
+        failedStep = "UBS scan";
+      } else if (errorMessage.includes("evaluation")) {
+        failedStep = "Self-evaluation parsing";
+      } else if (
+        errorMessage.includes("bead") ||
+        errorMessage.includes("close")
+      ) {
+        failedStep = "Bead close";
+      } else if (
+        errorMessage.includes("memory") ||
+        errorMessage.includes("semantic")
+      ) {
+        failedStep = "Memory storage (non-fatal)";
+      } else if (
+        errorMessage.includes("reservation") ||
+        errorMessage.includes("release")
+      ) {
+        failedStep = "File reservation release";
+      } else if (
+        errorMessage.includes("message") ||
+        errorMessage.includes("mail")
+      ) {
+        failedStep = "Swarm mail notification";
+      }
+
+      // Build error notification body
+      const errorBody = [
+        `## ⚠️ SWARM_COMPLETE FAILED`,
+        "",
+        `**Bead**: ${args.bead_id}`,
+        `**Agent**: ${args.agent_name}`,
+        `**Failed Step**: ${failedStep}`,
+        "",
+        `### Error Message`,
+        "```",
+        errorMessage,
+        "```",
+        "",
+        errorStack
+          ? `### Stack Trace\n\`\`\`\n${errorStack.slice(0, 1000)}\n\`\`\`\n`
+          : "",
+        `### Context`,
+        `- **Summary**: ${args.summary}`,
+        `- **Files touched**: ${args.files_touched?.length ? args.files_touched.join(", ") : "none"}`,
+        `- **Skip UBS**: ${args.skip_ubs_scan ?? false}`,
+        `- **Skip verification**: ${args.skip_verification ?? false}`,
+        "",
+        `### Recovery Actions`,
+        "1. Check error message for specific issue",
+        "2. Review failed step (UBS scan, typecheck, bead close, etc.)",
+        "3. Fix underlying issue or use skip flags if appropriate",
+        "4. Retry swarm_complete after fixing",
+      ]
+        .filter(Boolean)
+        .join("\n");
+
+      // Send urgent notification to coordinator
+      try {
+        await sendSwarmMessage({
+          projectPath: args.project_key,
+          fromAgent: args.agent_name,
+          toAgents: [], // Thread broadcast to coordinator
+          subject: `FAILED: swarm_complete for ${args.bead_id}`,
+          body: errorBody,
+          threadId: epicId,
+          importance: "urgent",
+        });
+      } catch (mailError) {
+        // Even swarm mail failed - log to console as last resort
+        console.error(
+          `[swarm_complete] CRITICAL: Failed to notify coordinator of failure for ${args.bead_id}:`,
+          mailError,
+        );
+        console.error(`[swarm_complete] Original error:`, error);
+      }
+
+      // Re-throw the original error after notifying
+      throw error;
+    }
   },
 });
 
@@ -1647,6 +1958,275 @@ export const swarm_check_strikes = tool({
   },
 });
 
+/**
+ * Swarm context shape stored in swarm_contexts table
+ */
+interface SwarmBeadContext {
+  id: string;
+  epic_id: string;
+  bead_id: string;
+  strategy: "file-based" | "feature-based" | "risk-based";
+  files: string[];
+  dependencies: string[];
+  directives: {
+    shared_context?: string;
+    skills_to_load?: string[];
+    coordinator_notes?: string;
+  };
+  recovery: {
+    last_checkpoint: number;
+    files_modified: string[];
+    progress_percent: number;
+    last_message?: string;
+    error_context?: string;
+  };
+  created_at: number;
+  updated_at: number;
+}
+
+/**
+ * Checkpoint swarm context for recovery
+ *
+ * Records the current state of a subtask to enable recovery after crashes,
+ * context overflows, or agent restarts. Non-fatal errors - logs warnings
+ * and continues if checkpoint fails.
+ *
+ * Integration:
+ * - Called automatically by swarm_progress at milestone thresholds (25%, 50%, 75%)
+ * - Can be called manually by agents at critical points
+ * - Emits SwarmCheckpointedEvent for audit trail
+ * - Updates swarm_contexts table for fast recovery queries
+ */
+export const swarm_checkpoint = tool({
+  description:
+    "Checkpoint swarm context for recovery. Records current state for crash recovery. Non-fatal errors.",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Subtask bead ID"),
+    epic_id: tool.schema.string().describe("Epic bead ID"),
+    files_modified: tool.schema
+      .array(tool.schema.string())
+      .describe("Files modified so far"),
+    progress_percent: tool.schema
+      .number()
+      .min(0)
+      .max(100)
+      .describe("Current progress"),
+    directives: tool.schema
+      .object({
+        shared_context: tool.schema.string().optional(),
+        skills_to_load: tool.schema.array(tool.schema.string()).optional(),
+        coordinator_notes: tool.schema.string().optional(),
+      })
+      .optional()
+      .describe("Coordinator directives for this subtask"),
+    error_context: tool.schema
+      .string()
+      .optional()
+      .describe("Error context if checkpoint is during error handling"),
+  },
+  async execute(args) {
+    try {
+      // Build checkpoint data
+      const checkpoint: Omit<
+        SwarmBeadContext,
+        "id" | "created_at" | "updated_at"
+      > = {
+        epic_id: args.epic_id,
+        bead_id: args.bead_id,
+        strategy: "file-based", // TODO: Extract from decomposition metadata
+        files: args.files_modified,
+        dependencies: [], // TODO: Extract from bead metadata
+        directives: args.directives || {},
+        recovery: {
+          last_checkpoint: Date.now(),
+          files_modified: args.files_modified,
+          progress_percent: args.progress_percent,
+          error_context: args.error_context,
+        },
+      };
+
+      // Emit checkpoint event
+      const event = createEvent("swarm_checkpointed", {
+        project_key: args.project_key,
+        epic_id: args.epic_id,
+        bead_id: args.bead_id,
+        strategy: checkpoint.strategy,
+        files: checkpoint.files,
+        dependencies: checkpoint.dependencies,
+        directives: checkpoint.directives,
+        recovery: checkpoint.recovery,
+      });
+
+      await appendEvent(event, args.project_key);
+
+      // Update swarm_contexts table for fast recovery
+      const { getDatabase } = await import("./streams/index");
+      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, // Use bead_id as unique 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,
+          summary: `Checkpoint saved for ${args.bead_id} at ${args.progress_percent}%`,
+          bead_id: args.bead_id,
+          epic_id: args.epic_id,
+          files_tracked: args.files_modified.length,
+        },
+        null,
+        2,
+      );
+    } catch (error) {
+      // Non-fatal - log warning and continue
+      console.warn(
+        `[swarm_checkpoint] Failed to checkpoint ${args.bead_id}:`,
+        error,
+      );
+      return JSON.stringify(
+        {
+          success: false,
+          warning: "Checkpoint failed but continuing",
+          error: error instanceof Error ? error.message : String(error),
+          bead_id: args.bead_id,
+          note: "This is non-fatal. Work can continue without checkpoint.",
+        },
+        null,
+        2,
+      );
+    }
+  },
+});
+
+/**
+ * Recover swarm context from last checkpoint
+ *
+ * Queries swarm_contexts table for the most recent checkpoint of an epic.
+ * Returns the full context including files, progress, and recovery state.
+ * Emits SwarmRecoveredEvent for audit trail.
+ *
+ * Graceful fallback: Returns { found: false } if no checkpoint exists.
+ */
+export const swarm_recover = tool({
+  description:
+    "Recover swarm context from last checkpoint. Returns context or null if not found.",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    epic_id: tool.schema.string().describe("Epic bead ID to recover"),
+  },
+  async execute(args) {
+    try {
+      const { getDatabase } = await import("./streams/index");
+      const db = await getDatabase(args.project_key);
+
+      // Query most recent checkpoint for this epic
+      const result = await db.query<{
+        id: string;
+        epic_id: string;
+        bead_id: string;
+        strategy: string;
+        files: string;
+        dependencies: string;
+        directives: string;
+        recovery: string;
+        created_at: number;
+        updated_at: number;
+      }>(
+        `SELECT * FROM swarm_contexts 
+         WHERE epic_id = $1 
+         ORDER BY updated_at DESC 
+         LIMIT 1`,
+        [args.epic_id],
+      );
+
+      if (result.rows.length === 0) {
+        return JSON.stringify(
+          {
+            found: false,
+            message: `No checkpoint found for epic ${args.epic_id}`,
+            epic_id: args.epic_id,
+          },
+          null,
+          2,
+        );
+      }
+
+      const row = result.rows[0];
+      const context: SwarmBeadContext = {
+        id: row.id,
+        epic_id: row.epic_id,
+        bead_id: row.bead_id,
+        strategy: row.strategy as SwarmBeadContext["strategy"],
+        files: JSON.parse(row.files),
+        dependencies: JSON.parse(row.dependencies),
+        directives: JSON.parse(row.directives),
+        recovery: JSON.parse(row.recovery),
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+      };
+
+      // Emit recovery event
+      const event = createEvent("swarm_recovered", {
+        project_key: args.project_key,
+        epic_id: args.epic_id,
+        bead_id: context.bead_id,
+        recovered_from_checkpoint: context.recovery.last_checkpoint,
+      });
+
+      await appendEvent(event, args.project_key);
+
+      return JSON.stringify(
+        {
+          found: true,
+          context,
+          summary: `Recovered checkpoint from ${new Date(context.updated_at).toISOString()}`,
+          age_seconds: Math.round((Date.now() - context.updated_at) / 1000),
+        },
+        null,
+        2,
+      );
+    } catch (error) {
+      // Graceful fallback
+      console.warn(
+        `[swarm_recover] Failed to recover context for ${args.epic_id}:`,
+        error,
+      );
+      return JSON.stringify(
+        {
+          found: false,
+          error: error instanceof Error ? error.message : String(error),
+          message: `Recovery failed for epic ${args.epic_id}`,
+          epic_id: args.epic_id,
+        },
+        null,
+        2,
+      );
+    }
+  },
+});
+
 /**
  * Learn from completed work and optionally create a skill
  *
@@ -1865,5 +2445,7 @@ export const orchestrateTools = {
   swarm_get_error_context,
   swarm_resolve_error,
   swarm_check_strikes,
+  swarm_checkpoint,
+  swarm_recover,
   swarm_learn,
 };