opencode-swarm-plugin 0.31.7 → 0.33.0

package/dist/index.js

@@ -26558,7 +26558,7 @@ var init_skills = __esm(() => {
     "skills"
   ];
   skills_list = tool({
-    description: `List all available skills in the project.
+    description: `[DEPRECATED] List all available skills in the project.
 
 Skills are specialized instructions that help with specific domains or tasks.
 Use this tool to discover what skills are available, then use skills_use to
@@ -26569,6 +26569,7 @@ Returns skill names, descriptions, and whether they have executable scripts.`,
       tag: tool.schema.string().optional().describe("Optional tag to filter skills by")
     },
     async execute(args) {
+      console.warn("[DEPRECATED] skills_list is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.");
       const skills = await discoverSkills();
       let refs = Array.from(skills.values());
       if (args.tag) {
@@ -26591,7 +26592,7 @@ ${formatted}`;
     }
   });
   skills_use = tool({
-    description: `Activate a skill by loading its full instructions.
+    description: `[DEPRECATED] Activate a skill by loading its full instructions.
 
 After calling this tool, follow the skill's instructions for the current task.
 Skills provide domain-specific guidance and best practices.
@@ -26602,6 +26603,7 @@ If the skill has scripts, you can run them with skills_execute.`,
       include_scripts: tool.schema.boolean().optional().describe("Also list available scripts (default: true)")
     },
     async execute(args) {
+      console.warn("[DEPRECATED] skills_use is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.");
       const skill = await getSkill(args.name);
       if (!skill) {
         const available = await listSkills();
@@ -26634,7 +26636,7 @@ Run scripts with skills_execute tool.`;
     }
   });
   skills_execute = tool({
-    description: `Execute a script from a skill's scripts/ directory.
+    description: `[DEPRECATED] Execute a script from a skill's scripts/ directory.
 
 Some skills include helper scripts for common operations.
 Use skills_use first to see available scripts, then execute them here.
@@ -26646,6 +26648,7 @@ Scripts run in the skill's directory with the project directory as an argument.`
       args: tool.schema.array(tool.schema.string()).optional().describe("Additional arguments to pass to the script")
     },
     async execute(args, ctx) {
+      console.warn("[DEPRECATED] skills_execute is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.");
       const skill = await getSkill(args.skill);
       if (!skill) {
         return `Skill '${args.skill}' not found.`;
@@ -26691,7 +26694,7 @@ ${output}`;
     }
   });
   skills_read = tool({
-    description: `Read a resource file from a skill's directory.
+    description: `[DEPRECATED] Read a resource file from a skill's directory.
 
 Skills may include additional files like:
 - examples.md - Example usage
@@ -26704,6 +26707,7 @@ Use this to access supplementary skill resources.`,
       file: tool.schema.string().describe("Relative path to the file within the skill directory")
     },
     async execute(args) {
+      console.warn("[DEPRECATED] skills_read is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.");
       const skill = await getSkill(args.skill);
       if (!skill) {
         return `Skill '${args.skill}' not found.`;
@@ -27084,7 +27088,7 @@ import {
   FlushManager,
   importFromJSONL,
   syncMemories,
-  getSwarmMail,
+  getSwarmMailLibSQL,
   resolvePartialId
 } from "swarm-mail";
 import { existsSync, readFileSync } from "node:fs";
@@ -27977,7 +27981,7 @@ async function getHiveAdapter(projectKey) {
   if (adapterCache.has(projectKey)) {
     return adapterCache.get(projectKey);
   }
-  const swarmMail = await getSwarmMail(projectKey);
+  const swarmMail = await getSwarmMailLibSQL(projectKey);
   const db = await swarmMail.getDatabase();
   const adapter = createHiveAdapter(db, projectKey);
   await adapter.runMigrations();
@@ -28345,7 +28349,7 @@ var hive_sync = tool({
       outputPath: `${projectKey}/.hive/issues.jsonl`
     });
     const flushResult = await withTimeout(flushManager.flush(), TIMEOUT_MS, "flush hive");
-    const swarmMail = await getSwarmMail(projectKey);
+    const swarmMail = await getSwarmMailLibSQL(projectKey);
     const db = await swarmMail.getDatabase();
     const hivePath = join(projectKey, ".hive");
     let memoriesSynced = 0;
@@ -28378,9 +28382,27 @@ var hive_sync = tool({
       const remoteCheckResult2 = await runGitCommand(["remote"]);
       const hasRemote2 = remoteCheckResult2.stdout.trim() !== "";
       if (hasRemote2) {
-        const pullResult = await withTimeout(runGitCommand(["pull", "--rebase"]), TIMEOUT_MS, "git pull --rebase");
-        if (pullResult.exitCode !== 0) {
-          throw new HiveError(`Failed to pull: ${pullResult.stderr}`, "git pull --rebase", pullResult.exitCode);
+        const statusResult = await runGitCommand(["status", "--porcelain"]);
+        const hasUnstagedChanges = statusResult.stdout.trim() !== "";
+        let didStash = false;
+        if (hasUnstagedChanges) {
+          const stashResult = await runGitCommand(["stash", "push", "-u", "-m", "hive_sync: auto-stash before pull"]);
+          if (stashResult.exitCode === 0) {
+            didStash = true;
+          }
+        }
+        try {
+          const pullResult = await withTimeout(runGitCommand(["pull", "--rebase"]), TIMEOUT_MS, "git pull --rebase");
+          if (pullResult.exitCode !== 0) {
+            throw new HiveError(`Failed to pull: ${pullResult.stderr}`, "git pull --rebase", pullResult.exitCode);
+          }
+        } finally {
+          if (didStash) {
+            const popResult = await runGitCommand(["stash", "pop"]);
+            if (popResult.exitCode !== 0) {
+              console.warn(`[hive_sync] Warning: stash pop failed. Your changes are in 'git stash list'. Error: ${popResult.stderr}`);
+            }
+          }
         }
       }
     }
@@ -32936,7 +32958,8 @@ import {
   sendSwarmMessage as sendSwarmMessage3,
   getAgent,
   createEvent as createEvent2,
-  appendEvent as appendEvent2
+  appendEvent as appendEvent2,
+  getSwarmMailLibSQL as getSwarmMailLibSQL2
 } from "swarm-mail";
 init_skills();
 
@@ -33740,60 +33763,6 @@ ${progress.blockers.map((b) => `- ${b}`).join(`
 
 `);
 }
-async function runUbsScan(files) {
-  if (files.length === 0) {
-    return null;
-  }
-  const ubsAvailable = await isToolAvailable("ubs");
-  if (!ubsAvailable) {
-    warnMissingTool("ubs");
-    return null;
-  }
-  try {
-    const result = await Bun.$`ubs scan ${files.join(" ")} --json`.quiet().nothrow();
-    const output = result.stdout.toString();
-    if (!output.trim()) {
-      return {
-        exitCode: result.exitCode,
-        bugs: [],
-        summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
-      };
-    }
-    try {
-      const parsed = JSON.parse(output);
-      if (typeof parsed !== "object" || parsed === null) {
-        throw new Error("UBS output is not an object");
-      }
-      if (!Array.isArray(parsed.bugs)) {
-        console.warn("[swarm] UBS output missing bugs array, using empty");
-      }
-      if (typeof parsed.summary !== "object" || parsed.summary === null) {
-        console.warn("[swarm] UBS output missing summary object, using empty");
-      }
-      return {
-        exitCode: result.exitCode,
-        bugs: Array.isArray(parsed.bugs) ? parsed.bugs : [],
-        summary: parsed.summary || {
-          total: 0,
-          critical: 0,
-          high: 0,
-          medium: 0,
-          low: 0
-        }
-      };
-    } catch (error45) {
-      console.error(`[swarm] CRITICAL: UBS scan failed to parse JSON output because output is malformed:`, error45);
-      console.error(`[swarm] Raw output: ${output}. Try: Run 'ubs doctor' to check installation, verify UBS version with 'ubs --version' (need v1.0.0+), or check if UBS supports --json flag.`);
-      return {
-        exitCode: result.exitCode,
-        bugs: [],
-        summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 }
-      };
-    }
-  } catch {
-    return null;
-  }
-}
 async function runTypecheckVerification() {
   const step = {
     name: "typecheck",
@@ -33878,34 +33847,9 @@ async function runTestVerification(filesTouched) {
   }
   return step;
 }
-async function runVerificationGate(filesTouched, skipUbs = false) {
+async function runVerificationGate(filesTouched, _skipUbs = false) {
   const steps = [];
   const blockers = [];
-  if (!skipUbs && filesTouched.length > 0) {
-    const ubsResult = await runUbsScan(filesTouched);
-    if (ubsResult) {
-      const ubsStep = {
-        name: "ubs_scan",
-        command: `ubs scan ${filesTouched.join(" ")}`,
-        passed: ubsResult.summary.critical === 0,
-        exitCode: ubsResult.exitCode
-      };
-      if (!ubsStep.passed) {
-        ubsStep.error = `Found ${ubsResult.summary.critical} critical bugs`;
-        blockers.push(`UBS found ${ubsResult.summary.critical} critical bug(s). Try: Run 'ubs scan ${filesTouched.join(" ")}' to see details, fix critical bugs in reported files, or use skip_ubs_scan=true to bypass (not recommended).`);
-      }
-      steps.push(ubsStep);
-    } else {
-      steps.push({
-        name: "ubs_scan",
-        command: "ubs scan",
-        passed: true,
-        exitCode: 0,
-        skipped: true,
-        skipReason: "UBS not available"
-      });
-    }
-  }
   const typecheckStep = await runTypecheckVerification();
   steps.push(typecheckStep);
   if (!typecheckStep.passed && !typecheckStep.skipped) {
@@ -34228,16 +34172,15 @@ ${args.files_affected.map((f) => `- \`${f}\``).join(`
   }
 });
 var swarm_complete = tool({
-  description: "Mark subtask complete with Verification Gate. Runs UBS scan, typecheck, and tests before allowing completion.",
+  description: "Mark subtask complete with Verification Gate. Runs typecheck and tests before allowing completion.",
   args: {
     project_key: tool.schema.string().describe("Project path"),
     agent_name: tool.schema.string().describe("Your Agent Mail name"),
     bead_id: tool.schema.string().describe("Subtask bead ID"),
     summary: tool.schema.string().describe("Brief summary of work done"),
     evaluation: tool.schema.string().optional().describe("Self-evaluation JSON (Evaluation schema)"),
-    files_touched: tool.schema.array(tool.schema.string()).optional().describe("Files modified - will be verified (UBS, typecheck, tests)"),
-    skip_ubs_scan: tool.schema.boolean().optional().describe("Skip UBS bug scan (default: false)"),
-    skip_verification: tool.schema.boolean().optional().describe("Skip ALL verification (UBS, typecheck, tests). Use sparingly! (default: false)"),
+    files_touched: tool.schema.array(tool.schema.string()).optional().describe("Files modified - will be verified (typecheck, tests)"),
+    skip_verification: tool.schema.boolean().optional().describe("Skip ALL verification (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"),
@@ -34320,7 +34263,7 @@ Continuing with completion, but this should be fixed for future subtasks.`;
       }
       let verificationResult = null;
       if (!args.skip_verification && args.files_touched?.length) {
-        verificationResult = await runVerificationGate(args.files_touched, args.skip_ubs_scan ?? false);
+        verificationResult = await runVerificationGate(args.files_touched, false);
         if (!verificationResult.passed) {
           return JSON.stringify({
             success: false,
@@ -34342,21 +34285,6 @@ Continuing with completion, but this should be fixed for future subtasks.`;
           }, null, 2);
         }
       }
-      let ubsResult = null;
-      if (!args.skip_verification && !verificationResult && args.files_touched?.length && !args.skip_ubs_scan) {
-        ubsResult = await runUbsScan(args.files_touched);
-        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);
-        }
-      }
       let contractValidation = null;
       let contractWarning;
       if (args.files_touched && args.files_touched.length > 0) {
@@ -34426,6 +34354,23 @@ This will be recorded as a negative learning signal.`;
           }
         }, null, 2);
       }
+      let deferredResolved = false;
+      let deferredError;
+      try {
+        const swarmMail = await getSwarmMailLibSQL2(args.project_key);
+        const db = await swarmMail.getDatabase();
+        const deferredUrl = `deferred:${args.bead_id}`;
+        const checkResult = await db.query(`SELECT url, resolved FROM deferred WHERE url = ? AND resolved = 0`, [deferredUrl]);
+        if (checkResult.rows.length > 0) {
+          await db.query(`UPDATE deferred SET resolved = 1, value = ? WHERE url = ? AND resolved = 0`, [JSON.stringify({ completed: true, summary: args.summary }), deferredUrl]);
+          deferredResolved = true;
+        } else {
+          console.info(`[swarm_complete] No deferred found for ${args.bead_id} - task may not be part of active swarm`);
+        }
+      } catch (error45) {
+        deferredError = error45 instanceof Error ? error45.message : String(error45);
+        console.warn(`[swarm_complete] Failed to resolve deferred (non-fatal): ${deferredError}`);
+      }
       let syncSuccess = false;
       let syncError;
       try {
@@ -34530,6 +34475,8 @@ This will be recorded as a negative learning signal.`;
         sync_error: syncError,
         message_sent: messageSent,
         message_error: messageError,
+        deferred_resolved: deferredResolved,
+        deferred_error: deferredError,
         agent_registration: {
           verified: agentRegistered,
           warning: registrationWarning || undefined
@@ -34544,15 +34491,6 @@ This will be recorded as a negative learning signal.`;
             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:
@@ -34590,9 +34528,7 @@ Files touched: ${args.files_touched?.join(", ") || "none recorded"}`,
       const errorStack = error45 instanceof Error ? error45.stack : undefined;
       let failedStep = "unknown";
       if (errorMessage.includes("verification")) {
-        failedStep = "Verification Gate (UBS/typecheck/tests)";
-      } else if (errorMessage.includes("UBS") || errorMessage.includes("ubs")) {
-        failedStep = "UBS scan";
+        failedStep = "Verification Gate (typecheck/tests)";
       } else if (errorMessage.includes("evaluation")) {
         failedStep = "Self-evaluation parsing";
       } else if (errorMessage.includes("bead") || errorMessage.includes("close")) {
@@ -34624,7 +34560,6 @@ ${errorStack.slice(0, 1000)}
         `### 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`,
@@ -34662,7 +34597,6 @@ ${errorStack.slice(0, 1000)}
         context: {
           summary: args.summary,
           files_touched: args.files_touched || [],
-          skip_ubs_scan: args.skip_ubs_scan ?? false,
           skip_verification: args.skip_verification ?? false
         },
         recovery: {
@@ -34674,7 +34608,6 @@ ${errorStack.slice(0, 1000)}
           ],
           common_fixes: {
             "Verification Gate": "Use skip_verification=true to bypass (not recommended)",
-            "UBS scan": "Use skip_ubs_scan=true to bypass",
             "Cell close": "Check cell status with hive_query(), may need hive_update() first",
             "Self-evaluation": "Check evaluation JSON format matches EvaluationSchema"
           }
@@ -34980,8 +34913,9 @@ var swarm_recover = tool({
   },
   async execute(args) {
     try {
-      const { getDatabase } = await import("swarm-mail");
-      const db = await getDatabase(args.project_key);
+      const { getSwarmMailLibSQL: getSwarmMailLibSQL3 } = await import("swarm-mail");
+      const swarmMail = await getSwarmMailLibSQL3(args.project_key);
+      const db = await swarmMail.getDatabase();
       const result = await db.query(`SELECT * FROM swarm_contexts 
          WHERE epic_id = $1 
          ORDER BY updated_at DESC 
@@ -35615,6 +35549,167 @@ Other cell operations:
 **Memory is the swarm's collective intelligence. Query it. Feed it.**
 
 Begin now.`;
+var RESEARCHER_PROMPT = `You are a swarm researcher gathering documentation for: **{research_id}**
+
+## [IDENTITY]
+Agent: (assigned at spawn)
+Research Task: {research_id}
+Epic: {epic_id}
+
+## [MISSION]
+Gather comprehensive documentation for the specified technologies to inform task decomposition.
+
+**COORDINATOR PROVIDED THESE TECHNOLOGIES TO RESEARCH:**
+{tech_stack}
+
+You do NOT discover what to research - the coordinator already decided that.
+You DO discover what TOOLS are available to fetch documentation.
+
+## [OUTPUT MODE]
+{check_upgrades}
+
+## [WORKFLOW]
+
+### Step 1: Initialize (MANDATORY FIRST)
+\`\`\`
+swarmmail_init(project_path="{project_path}", task_description="{research_id}: Documentation research")
+\`\`\`
+
+### Step 2: Discover Available Documentation Tools
+Check what's available for fetching docs:
+- **next-devtools**: \`nextjs_docs\` for Next.js documentation
+- **context7**: Library documentation lookup (\`use context7\` in prompts)
+- **fetch**: General web fetching for official docs sites
+- **pdf-brain**: Internal knowledge base search
+
+**Don't assume** - check which tools exist in your environment.
+
+### Step 3: Read Installed Versions
+For each technology in the tech stack:
+1. Check package.json (or equivalent) for installed version
+2. Record exact version numbers
+3. Note any version constraints (^, ~, etc.)
+
+### Step 4: Fetch Documentation
+For EACH technology in the list:
+- Use the most appropriate tool (Next.js → nextjs_docs, libraries → context7, others → fetch)
+- Fetch documentation for the INSTALLED version (not latest, unless --check-upgrades)
+- Focus on: API changes, breaking changes, migration guides, best practices
+- Extract key patterns, gotchas, and compatibility notes
+
+**If --check-upgrades mode:**
+- ALSO fetch docs for the LATEST version
+- Compare installed vs latest
+- Note breaking changes, new features, migration complexity
+
+### Step 5: Store Detailed Findings
+For EACH technology, store in semantic-memory:
+\`\`\`
+semantic-memory_store(
+  information="<technology-name> <version>: <key patterns, gotchas, API changes, compatibility notes>",
+  tags="research, <tech-name>, documentation, {epic_id}"
+)
+\`\`\`
+
+**Why store individually?** Future agents can search by technology name.
+
+### Step 6: Broadcast Summary
+Send condensed findings to coordinator:
+\`\`\`
+swarmmail_send(
+  to=["coordinator"],
+  subject="Research Complete: {research_id}",
+  body="<brief summary - see semantic-memory for details>",
+  thread_id="{epic_id}"
+)
+\`\`\`
+
+### Step 7: Return Structured Output
+Output JSON with:
+\`\`\`json
+{
+  "technologies": [
+    {
+      "name": "string",
+      "installed_version": "string",
+      "latest_version": "string | null",  // Only if --check-upgrades
+      "key_patterns": ["string"],
+      "gotchas": ["string"],
+      "breaking_changes": ["string"],  // Only if --check-upgrades
+      "memory_id": "string"  // ID of semantic-memory entry
+    }
+  ],
+  "summary": "string"  // Condensed summary for shared_context
+}
+\`\`\`
+
+## [CRITICAL REQUIREMENTS]
+
+**NON-NEGOTIABLE:**
+1. Step 1 (swarmmail_init) MUST be first
+2. Research ONLY the technologies the coordinator specified
+3. Fetch docs for INSTALLED versions (unless --check-upgrades)
+4. Store detailed findings in semantic-memory (one per technology)
+5. Return condensed summary for coordinator (full details in memory)
+6. Use appropriate doc tools (nextjs_docs for Next.js, context7 for libraries, etc.)
+
+**Output goes TWO places:**
+- **semantic-memory**: Detailed findings (searchable by future agents)
+- **Return JSON**: Condensed summary (for coordinator's shared_context)
+
+Begin research now.`;
+var COORDINATOR_POST_WORKER_CHECKLIST = `
+## ⚠️ MANDATORY: Post-Worker Review (DO THIS IMMEDIATELY)
+
+**A worker just returned. Before doing ANYTHING else, complete this checklist:**
+
+### Step 1: Check Swarm Mail
+\`\`\`
+swarmmail_inbox()
+swarmmail_read_message(message_id=N)  // Read any messages from the worker
+\`\`\`
+
+### Step 2: Review the Work
+\`\`\`
+swarm_review(
+  project_key="{project_key}",
+  epic_id="{epic_id}",
+  task_id="{task_id}",
+  files_touched=[{files_touched}]
+)
+\`\`\`
+
+This generates a review prompt with:
+- Epic context (what we're trying to achieve)
+- Subtask requirements
+- Git diff of changes
+- Dependency status
+
+### Step 3: Evaluate Against Criteria
+- Does the work fulfill the subtask requirements?
+- Does it serve the overall epic goal?
+- Does it enable downstream tasks?
+- Type safety, no obvious bugs?
+
+### Step 4: Send Feedback
+\`\`\`
+swarm_review_feedback(
+  project_key="{project_key}",
+  task_id="{task_id}",
+  worker_id="{worker_id}",
+  status="approved",  // or "needs_changes"
+  summary="<brief summary>",
+  issues="[]"  // or "[{file, line, issue, suggestion}]"
+)
+\`\`\`
+
+### Step 5: ONLY THEN Continue
+- If approved: Close the cell, spawn next worker
+- If needs_changes: Worker gets feedback, retries (max 3 attempts)
+- If 3 failures: Mark blocked, escalate to human
+
+**⚠️ DO NOT spawn the next worker until review is complete.**
+`;
 var EVALUATION_PROMPT = `Evaluate the work completed for this subtask.
 
 ## Subtask
@@ -35651,6 +35746,12 @@ For each criterion, assess passed/failed and provide brief feedback:
 
 If any criterion fails, the overall evaluation fails and retry_suggestion 
 should describe what needs to be fixed.`;
+function formatResearcherPrompt(params) {
+  const techList = params.tech_stack.map((t) => `- ${t}`).join(`
+`);
+  const upgradesMode = params.check_upgrades ? "**UPGRADE COMPARISON MODE**: Fetch docs for BOTH installed AND latest versions. Compare and note breaking changes." : "**DEFAULT MODE**: Fetch docs for INSTALLED versions only (from lockfiles).";
+  return RESEARCHER_PROMPT.replace(/{research_id}/g, params.research_id).replace(/{epic_id}/g, params.epic_id).replace("{tech_stack}", techList).replace("{project_path}", params.project_path).replace("{check_upgrades}", upgradesMode);
+}
 function formatSubtaskPromptV2(params) {
   const fileList = params.files.length > 0 ? params.files.map((f) => `- \`${f}\``).join(`
 `) : "(no specific files - use judgment)";
@@ -35786,6 +35887,8 @@ var swarm_spawn_subtask = tool({
       liteModel: "anthropic/claude-haiku-4-5"
     };
     const selectedModel = selectWorkerModel2(subtask, config2);
+    const filesJoined = args.files.map((f) => `"${f}"`).join(", ");
+    const postCompletionInstructions = COORDINATOR_POST_WORKER_CHECKLIST.replace(/{project_key}/g, args.project_path || "$PWD").replace(/{epic_id}/g, args.epic_id).replace(/{task_id}/g, args.bead_id).replace(/{files_touched}/g, filesJoined).replace(/{worker_id}/g, "worker");
     return JSON.stringify({
       prompt,
       bead_id: args.bead_id,
@@ -35793,7 +35896,50 @@ var swarm_spawn_subtask = tool({
       files: args.files,
       project_path: args.project_path,
       recovery_context: args.recovery_context,
-      recommended_model: selectedModel
+      recommended_model: selectedModel,
+      post_completion_instructions: postCompletionInstructions
+    }, null, 2);
+  }
+});
+var swarm_spawn_researcher = tool({
+  description: "Prepare a research task for spawning. Returns prompt for gathering technology documentation. Researcher fetches docs and stores findings in semantic-memory.",
+  args: {
+    research_id: tool.schema.string().describe("Unique ID for this research task"),
+    epic_id: tool.schema.string().describe("Parent epic ID"),
+    tech_stack: tool.schema.array(tool.schema.string()).describe("Explicit list of technologies to research (from coordinator)"),
+    project_path: tool.schema.string().describe("Absolute project path for swarmmail_init"),
+    check_upgrades: tool.schema.boolean().optional().describe("If true, compare installed vs latest versions (default: false)")
+  },
+  async execute(args) {
+    const prompt = formatResearcherPrompt({
+      research_id: args.research_id,
+      epic_id: args.epic_id,
+      tech_stack: args.tech_stack,
+      project_path: args.project_path,
+      check_upgrades: args.check_upgrades ?? false
+    });
+    return JSON.stringify({
+      prompt,
+      research_id: args.research_id,
+      epic_id: args.epic_id,
+      tech_stack: args.tech_stack,
+      project_path: args.project_path,
+      check_upgrades: args.check_upgrades ?? false,
+      subagent_type: "swarm/researcher",
+      expected_output: {
+        technologies: [
+          {
+            name: "string",
+            installed_version: "string",
+            latest_version: "string | null",
+            key_patterns: ["string"],
+            gotchas: ["string"],
+            breaking_changes: ["string"],
+            memory_id: "string"
+          }
+        ],
+        summary: "string"
+      }
     }, null, 2);
   }
 });
@@ -35908,6 +36054,7 @@ ${args.context}` : `## Additional Context
 var promptTools = {
   swarm_subtask_prompt,
   swarm_spawn_subtask,
+  swarm_spawn_researcher,
   swarm_evaluation_prompt,
   swarm_plan_prompt
 };
@@ -37006,7 +37153,7 @@ var mandateTools = {
 
 // src/memory-tools.ts
 init_dist();
-import { getSwarmMail as getSwarmMail2 } from "swarm-mail";
+import { getSwarmMailLibSQL as getSwarmMailLibSQL3 } from "swarm-mail";
 
 // ../../node_modules/.bun/effect@3.19.12/node_modules/effect/dist/esm/Function.js
 var isFunction = (input) => typeof input === "function";
@@ -50427,7 +50574,8 @@ import {
   makeOllamaLive,
   Ollama,
   legacyDatabaseExists,
-  migrateLegacyMemories
+  migrateLegacyMemories,
+  toSwarmDb
 } from "swarm-mail";
 var migrationChecked = false;
 async function maybeAutoMigrate(db) {
@@ -50461,7 +50609,8 @@ async function createMemoryAdapter(db) {
     migrationChecked = true;
     await maybeAutoMigrate(db);
   }
-  const store = createMemoryStore(db);
+  const drizzleDb = toSwarmDb(db);
+  const store = createMemoryStore(drizzleDb);
   const config2 = getDefaultConfig();
   const ollamaLayer = makeOllamaLive(config2);
   const generateId = () => {
@@ -50606,9 +50755,9 @@ async function getMemoryAdapter(projectPath) {
   if (cachedAdapter && cachedProjectPath === path2) {
     return cachedAdapter;
   }
-  const swarmMail = await getSwarmMail2(path2);
-  const db = await swarmMail.getDatabase();
-  cachedAdapter = await createMemoryAdapter(db);
+  const swarmMail = await getSwarmMailLibSQL3(path2);
+  const dbAdapter = await swarmMail.getDatabase();
+  cachedAdapter = await createMemoryAdapter(dbAdapter);
   cachedProjectPath = path2;
   return cachedAdapter;
 }
@@ -50719,6 +50868,368 @@ var memoryTools = {
   "semantic-memory_check": semantic_memory_check
 };
 
+// src/observability-tools.ts
+init_dist();
+import {
+  agentActivity,
+  checkpointFrequency,
+  failedDecompositions,
+  getSwarmMailLibSQL as getSwarmMailLibSQL4,
+  humanFeedback,
+  lockContention,
+  messageLatency,
+  recoverySuccess,
+  scopeViolations,
+  strategySuccessRates,
+  taskDuration
+} from "swarm-mail";
+function parseSince(since) {
+  const now = Date.now();
+  const match11 = since.match(/^(\d+)([dhm])$/);
+  if (!match11) {
+    throw new Error(`Invalid since format: ${since}. Use "7d", "24h", or "1h"`);
+  }
+  const [, value, unit] = match11;
+  const num = Number.parseInt(value, 10);
+  switch (unit) {
+    case "d":
+      return now - num * 24 * 60 * 60 * 1000;
+    case "h":
+      return now - num * 60 * 60 * 1000;
+    case "m":
+      return now - num * 60 * 1000;
+    default:
+      throw new Error(`Unknown unit: ${unit}`);
+  }
+}
+async function executeQuery(swarmMail, query) {
+  const db = await swarmMail.getDatabase();
+  const result = await db.query(query.sql, Object.values(query.parameters || {}));
+  return result.rows;
+}
+function formatSummary(queryType, results) {
+  if (results.length === 0) {
+    return `No ${queryType} data found.`;
+  }
+  const count = results.length;
+  const preview = results.slice(0, 3);
+  return `${queryType}: ${count} result(s). Top 3: ${JSON.stringify(preview, null, 2).slice(0, 400)}`;
+}
+function capResults(results) {
+  return results.slice(0, 50);
+}
+var swarm_analytics = tool({
+  description: "Query pre-built analytics for swarm coordination. Returns structured data about failed decompositions, strategy success rates, lock contention, agent activity, message latency, scope violations, task duration, checkpoint frequency, recovery success, and human feedback.",
+  args: {
+    query: tool.schema.enum([
+      "failed-decompositions",
+      "strategy-success-rates",
+      "lock-contention",
+      "agent-activity",
+      "message-latency",
+      "scope-violations",
+      "task-duration",
+      "checkpoint-frequency",
+      "recovery-success",
+      "human-feedback"
+    ]).describe("Type of analytics query to run"),
+    since: tool.schema.string().optional().describe("Time filter: '7d', '24h', '1h' (optional)"),
+    format: tool.schema.enum(["json", "summary"]).optional().describe("Output format: 'json' (default) or 'summary' (context-efficient)")
+  },
+  async execute(args2) {
+    try {
+      const projectPath = process.cwd();
+      const db = await getSwarmMailLibSQL4(projectPath);
+      const filters = {
+        project_key: projectPath
+      };
+      if (args2.since) {
+        filters.since = parseSince(args2.since);
+      }
+      let query;
+      switch (args2.query) {
+        case "failed-decompositions":
+          query = failedDecompositions(filters);
+          break;
+        case "strategy-success-rates":
+          query = strategySuccessRates(filters);
+          break;
+        case "lock-contention":
+          query = lockContention(filters);
+          break;
+        case "agent-activity":
+          query = agentActivity(filters);
+          break;
+        case "message-latency":
+          query = messageLatency(filters);
+          break;
+        case "scope-violations":
+          query = scopeViolations.buildQuery ? scopeViolations.buildQuery(filters) : scopeViolations;
+          break;
+        case "task-duration":
+          query = taskDuration.buildQuery ? taskDuration.buildQuery(filters) : taskDuration;
+          break;
+        case "checkpoint-frequency":
+          query = checkpointFrequency.buildQuery ? checkpointFrequency.buildQuery(filters) : checkpointFrequency;
+          break;
+        case "recovery-success":
+          query = recoverySuccess.buildQuery ? recoverySuccess.buildQuery(filters) : recoverySuccess;
+          break;
+        case "human-feedback":
+          query = humanFeedback.buildQuery ? humanFeedback.buildQuery(filters) : humanFeedback;
+          break;
+        default:
+          return JSON.stringify({
+            error: `Unknown query type: ${args2.query}`
+          });
+      }
+      const results = await executeQuery(db, query);
+      if (args2.format === "summary") {
+        return formatSummary(args2.query, results);
+      }
+      return JSON.stringify({
+        query: args2.query,
+        filters,
+        count: results.length,
+        results
+      }, null, 2);
+    } catch (error45) {
+      return JSON.stringify({
+        error: error45 instanceof Error ? error45.message : String(error45)
+      });
+    }
+  }
+});
+var swarm_query = tool({
+  description: "Execute raw SQL queries against the swarm event store. Context-safe: results capped at 50 rows. Useful for custom analytics and debugging.",
+  args: {
+    sql: tool.schema.string().describe("SQL query to execute (SELECT only for safety)"),
+    format: tool.schema.enum(["json", "table"]).optional().describe("Output format: 'json' (default) or 'table' (visual)")
+  },
+  async execute(args2) {
+    try {
+      const projectPath = process.cwd();
+      const swarmMail = await getSwarmMailLibSQL4(projectPath);
+      const db = await swarmMail.getDatabase();
+      if (!args2.sql.trim().toLowerCase().startsWith("select")) {
+        return JSON.stringify({
+          error: "Only SELECT queries are allowed for safety"
+        });
+      }
+      const result = await db.query(args2.sql, []);
+      const rows = result.rows;
+      const cappedRows = capResults(rows);
+      if (args2.format === "table") {
+        if (cappedRows.length === 0) {
+          return "No results";
+        }
+        const headers = Object.keys(cappedRows[0]);
+        const headerRow = headers.join(" | ");
+        const separator = headers.map(() => "---").join(" | ");
+        const dataRows = cappedRows.map((row) => headers.map((h) => row[h]).join(" | "));
+        return [headerRow, separator, ...dataRows].join(`
+`);
+      }
+      return JSON.stringify({
+        count: cappedRows.length,
+        total: rows.length,
+        capped: rows.length > 50,
+        results: cappedRows
+      }, null, 2);
+    } catch (error45) {
+      return JSON.stringify({
+        error: error45 instanceof Error ? error45.message : String(error45)
+      });
+    }
+  }
+});
+var swarm_diagnose = tool({
+  description: "Auto-diagnose issues for a specific epic or task. Returns structured diagnosis with blockers, conflicts, slow tasks, errors, and timeline.",
+  args: {
+    epic_id: tool.schema.string().optional().describe("Epic ID to diagnose"),
+    bead_id: tool.schema.string().optional().describe("Task ID to diagnose"),
+    include: tool.schema.array(tool.schema.enum([
+      "blockers",
+      "conflicts",
+      "slow_tasks",
+      "errors",
+      "timeline"
+    ])).optional().describe("What to include in diagnosis (default: all)")
+  },
+  async execute(args2) {
+    try {
+      const projectPath = process.cwd();
+      const swarmMail = await getSwarmMailLibSQL4(projectPath);
+      const db = await swarmMail.getDatabase();
+      const diagnosis = [];
+      const include = args2.include || [
+        "blockers",
+        "conflicts",
+        "slow_tasks",
+        "errors",
+        "timeline"
+      ];
+      if (include.includes("blockers")) {
+        const blockerQuery = `
+					SELECT json_extract(data, '$.agent_name') as agent,
+					       json_extract(data, '$.bead_id') as bead_id,
+					       timestamp
+					FROM events
+					WHERE type = 'task_blocked'
+					${args2.epic_id ? "AND json_extract(data, '$.epic_id') = ?" : ""}
+					${args2.bead_id ? "AND json_extract(data, '$.bead_id') = ?" : ""}
+					ORDER BY timestamp DESC
+					LIMIT 10
+				`;
+        const params = [];
+        if (args2.epic_id)
+          params.push(args2.epic_id);
+        if (args2.bead_id)
+          params.push(args2.bead_id);
+        const blockers = await db.query(blockerQuery, params);
+        if (blockers.rows.length > 0) {
+          diagnosis.push({
+            type: "blockers",
+            message: `Found ${blockers.rows.length} blocked task(s)`,
+            severity: "high"
+          });
+        }
+      }
+      if (include.includes("errors")) {
+        const errorQuery = `
+					SELECT type, json_extract(data, '$.error_count') as error_count
+					FROM events
+					WHERE type = 'subtask_outcome'
+					AND json_extract(data, '$.success') = 'false'
+					${args2.epic_id ? "AND json_extract(data, '$.epic_id') = ?" : ""}
+					${args2.bead_id ? "AND json_extract(data, '$.bead_id') = ?" : ""}
+					LIMIT 10
+				`;
+        const params = [];
+        if (args2.epic_id)
+          params.push(args2.epic_id);
+        if (args2.bead_id)
+          params.push(args2.bead_id);
+        const errors3 = await db.query(errorQuery, params);
+        if (errors3.rows.length > 0) {
+          diagnosis.push({
+            type: "errors",
+            message: `Found ${errors3.rows.length} failed task(s)`,
+            severity: "high"
+          });
+        }
+      }
+      let timeline = [];
+      if (include.includes("timeline")) {
+        const timelineQuery = `
+					SELECT timestamp, type, json_extract(data, '$.agent_name') as agent
+					FROM events
+					${args2.epic_id ? "WHERE json_extract(data, '$.epic_id') = ?" : ""}
+					${args2.bead_id ? (args2.epic_id ? "AND" : "WHERE") + " json_extract(data, '$.bead_id') = ?" : ""}
+					ORDER BY timestamp DESC
+					LIMIT 20
+				`;
+        const params = [];
+        if (args2.epic_id)
+          params.push(args2.epic_id);
+        if (args2.bead_id)
+          params.push(args2.bead_id);
+        const events = await db.query(timelineQuery, params);
+        timeline = events.rows;
+      }
+      return JSON.stringify({
+        epic_id: args2.epic_id,
+        bead_id: args2.bead_id,
+        diagnosis,
+        timeline: include.includes("timeline") ? timeline : undefined
+      }, null, 2);
+    } catch (error45) {
+      return JSON.stringify({
+        error: error45 instanceof Error ? error45.message : String(error45)
+      });
+    }
+  }
+});
+var swarm_insights = tool({
+  description: "Generate learning insights from swarm coordination metrics. Analyzes success rates, duration, conflicts, and retries to provide actionable recommendations.",
+  args: {
+    scope: tool.schema.enum(["epic", "project", "recent"]).describe("Scope of analysis: 'epic', 'project', or 'recent'"),
+    epic_id: tool.schema.string().optional().describe("Epic ID (required if scope='epic')"),
+    metrics: tool.schema.array(tool.schema.enum([
+      "success_rate",
+      "avg_duration",
+      "conflict_rate",
+      "retry_rate"
+    ])).describe("Metrics to analyze")
+  },
+  async execute(args2) {
+    try {
+      if (args2.scope === "epic" && !args2.epic_id) {
+        return JSON.stringify({
+          error: "epic_id is required when scope='epic'"
+        });
+      }
+      const projectPath = process.cwd();
+      const swarmMail = await getSwarmMailLibSQL4(projectPath);
+      const db = await swarmMail.getDatabase();
+      const insights = [];
+      if (args2.metrics.includes("success_rate")) {
+        const query = `
+					SELECT
+						SUM(CASE WHEN json_extract(data, '$.success') = 'true' THEN 1 ELSE 0 END) as successes,
+						COUNT(*) as total
+					FROM events
+					WHERE type = 'subtask_outcome'
+					${args2.epic_id ? "AND json_extract(data, '$.epic_id') = ?" : ""}
+				`;
+        const result = await db.query(query, args2.epic_id ? [args2.epic_id] : []);
+        const row = result.rows[0];
+        if (row && row.total > 0) {
+          const rate = row.successes / row.total * 100;
+          insights.push({
+            metric: "success_rate",
+            value: `${rate.toFixed(1)}%`,
+            insight: rate < 50 ? "Low success rate - review decomposition strategy" : rate < 80 ? "Moderate success rate - monitor for patterns" : "Good success rate - maintain current approach"
+          });
+        }
+      }
+      if (args2.metrics.includes("avg_duration")) {
+        const query = `
+					SELECT AVG(CAST(json_extract(data, '$.duration_ms') AS REAL)) as avg_duration
+					FROM events
+					WHERE type = 'subtask_outcome'
+					${args2.epic_id ? "AND json_extract(data, '$.epic_id') = ?" : ""}
+				`;
+        const result = await db.query(query, args2.epic_id ? [args2.epic_id] : []);
+        const row = result.rows[0];
+        if (row?.avg_duration) {
+          const avgMinutes = (row.avg_duration / 60000).toFixed(1);
+          insights.push({
+            metric: "avg_duration",
+            value: `${avgMinutes} min`,
+            insight: row.avg_duration > 600000 ? "Tasks taking >10min - consider smaller decomposition" : "Task duration is reasonable"
+          });
+        }
+      }
+      return JSON.stringify({
+        scope: args2.scope,
+        epic_id: args2.epic_id,
+        insights
+      }, null, 2);
+    } catch (error45) {
+      return JSON.stringify({
+        error: error45 instanceof Error ? error45.message : String(error45)
+      });
+    }
+  }
+});
+var observabilityTools = {
+  swarm_analytics,
+  swarm_query,
+  swarm_diagnose,
+  swarm_insights
+};
+
 // src/output-guardrails.ts
 var DEFAULT_GUARDRAIL_CONFIG = {
   defaultMaxChars: 32000,
@@ -51472,9 +51983,11 @@ Extract from session context:
 
 1. \`swarm_status(epic_id="<epic>", project_key="<path>")\` - Get current state
 2. \`swarmmail_inbox(limit=5)\` - Check for agent messages
-3. **Spawn ready subtasks** - Don't wait, fire them off
-4. **Unblock blocked work** - Resolve dependencies, reassign if needed
-5. **Collect completed work** - Close done subtasks, verify quality
+3. \`swarm_review(project_key, epic_id, task_id, files_touched)\` - Review any completed work
+4. \`swarm_review_feedback(project_key, task_id, worker_id, status, issues)\` - Approve or request changes
+5. **Spawn ready subtasks** - Don't wait, fire them off
+6. **Unblock blocked work** - Resolve dependencies, reassign if needed
+7. **Collect completed work** - Close done subtasks, verify quality
 
 ### Keep the Swarm Cooking
 
@@ -51658,7 +52171,8 @@ var SwarmPlugin = async (input) => {
       ...repoCrawlTools,
       ...skillsTools,
       ...mandateTools,
-      ...memoryTools
+      ...memoryTools,
+      ...observabilityTools
     },
     event: async ({ event }) => {
       if (event.type === "session.idle") {