opencode-swarm-plugin 0.12.18 → 0.12.20

package/dist/index.js

@@ -21608,7 +21608,7 @@ var BeadTreeSchema = exports_external.object({
     title: exports_external.string().min(1),
     description: exports_external.string().optional().default("")
   }),
-  subtasks: exports_external.array(SubtaskSpecSchema).min(1).max(10)
+  subtasks: exports_external.array(SubtaskSpecSchema).min(1)
 });
 var EpicCreateArgsSchema = exports_external.object({
   epic_title: exports_external.string().min(1),
@@ -21617,7 +21617,7 @@ var EpicCreateArgsSchema = exports_external.object({
     title: exports_external.string().min(1),
     priority: exports_external.number().int().min(0).max(3).default(2),
     files: exports_external.array(exports_external.string()).optional().default([])
-  })).min(1).max(10)
+  })).min(1)
 });
 var EpicCreateResultSchema = exports_external.object({
   success: exports_external.boolean(),
@@ -21720,13 +21720,13 @@ var SubtaskDependencySchema = exports_external.object({
 var TaskDecompositionSchema = exports_external.object({
   task: exports_external.string(),
   reasoning: exports_external.string().optional(),
-  subtasks: exports_external.array(DecomposedSubtaskSchema).min(1).max(10),
+  subtasks: exports_external.array(DecomposedSubtaskSchema).min(1),
   dependencies: exports_external.array(SubtaskDependencySchema).optional().default([]),
   shared_context: exports_external.string().optional()
 });
 var DecomposeArgsSchema = exports_external.object({
   task: exports_external.string().min(1),
-  max_subtasks: exports_external.number().int().min(1).max(10).default(5),
+  max_subtasks: exports_external.number().int().min(1).default(5),
   context: exports_external.string().optional()
 });
 var SpawnedAgentSchema = exports_external.object({
@@ -22153,7 +22153,40 @@ var beads_sync = tool({
       }
     }
     if (autoPull) {
+      const dirtyCheckResult = await runGitCommand([
+        "status",
+        "--porcelain",
+        "--untracked-files=no"
+      ]);
+      const hasDirtyFiles = dirtyCheckResult.stdout.trim() !== "";
+      let didStash = false;
+      if (hasDirtyFiles) {
+        console.warn("[beads] Detected unstaged changes, stashing before pull...");
+        const stashResult = await runGitCommand([
+          "stash",
+          "push",
+          "-m",
+          "beads_sync: auto-stash before pull",
+          "--include-untracked"
+        ]);
+        if (stashResult.exitCode === 0) {
+          didStash = true;
+          console.warn("[beads] Changes stashed successfully");
+        } else {
+          console.warn(`[beads] Stash failed (${stashResult.stderr}), attempting pull anyway...`);
+        }
+      }
       const pullResult = await withTimeout(runGitCommand(["pull", "--rebase"]), TIMEOUT_MS, "git pull --rebase");
+      if (didStash) {
+        console.warn("[beads] Restoring stashed changes...");
+        const unstashResult = await runGitCommand(["stash", "pop"]);
+        if (unstashResult.exitCode !== 0) {
+          console.error(`[beads] WARNING: Failed to restore stashed changes: ${unstashResult.stderr}`);
+          console.error("[beads] Your changes are in 'git stash list' - run 'git stash pop' manually");
+        } else {
+          console.warn("[beads] Stashed changes restored");
+        }
+      }
       if (pullResult.exitCode !== 0) {
         throw new BeadError(`Failed to pull: ${pullResult.stderr}`, "git pull --rebase", pullResult.exitCode);
       }
@@ -23014,6 +23047,20 @@ function isRetryableError(error45) {
   }
   return false;
 }
+function isProjectNotFoundError(error45) {
+  if (error45 instanceof Error) {
+    const message = error45.message.toLowerCase();
+    return message.includes("project") && (message.includes("not found") || message.includes("does not exist"));
+  }
+  return false;
+}
+function isAgentNotFoundError(error45) {
+  if (error45 instanceof Error) {
+    const message = error45.message.toLowerCase();
+    return message.includes("agent") && (message.includes("not found") || message.includes("does not exist"));
+  }
+  return false;
+}
 var agentMailAvailable = null;
 async function checkAgentMailAvailable() {
   if (agentMailAvailable !== null) {
@@ -23144,6 +23191,68 @@ async function mcpCall(toolName, args) {
   }
   throw lastError || new Error("Unknown error in mcpCall");
 }
+async function reRegisterProject(projectKey) {
+  try {
+    console.warn(`[agent-mail] Re-registering project "${projectKey}" after server restart...`);
+    await mcpCall("ensure_project", {
+      human_key: projectKey
+    });
+    console.warn(`[agent-mail] Project "${projectKey}" re-registered successfully`);
+    return true;
+  } catch (error45) {
+    console.error(`[agent-mail] Failed to re-register project "${projectKey}":`, error45);
+    return false;
+  }
+}
+async function reRegisterAgent(projectKey, agentName, taskDescription) {
+  try {
+    console.warn(`[agent-mail] Re-registering agent "${agentName}" for project "${projectKey}"...`);
+    await mcpCall("register_agent", {
+      project_key: projectKey,
+      program: "opencode",
+      model: "claude-opus-4",
+      name: agentName,
+      task_description: taskDescription || "Re-registered after server restart"
+    });
+    console.warn(`[agent-mail] Agent "${agentName}" re-registered successfully`);
+    return true;
+  } catch (error45) {
+    console.error(`[agent-mail] Failed to re-register agent "${agentName}":`, error45);
+    return false;
+  }
+}
+async function mcpCallWithAutoInit(toolName, args, options) {
+  const maxAttempts = options?.maxReregistrationAttempts ?? 1;
+  let reregistrationAttempts = 0;
+  while (true) {
+    try {
+      return await mcpCall(toolName, args);
+    } catch (error45) {
+      const isProjectError = isProjectNotFoundError(error45);
+      const isAgentError = isAgentNotFoundError(error45);
+      if (!isProjectError && !isAgentError) {
+        throw error45;
+      }
+      if (reregistrationAttempts >= maxAttempts) {
+        console.error(`[agent-mail] Exhausted ${maxAttempts} re-registration attempt(s) for ${toolName}`);
+        throw error45;
+      }
+      reregistrationAttempts++;
+      console.warn(`[agent-mail] Detected "${isProjectError ? "project" : "agent"} not found" for ${toolName}, ` + `attempting re-registration (attempt ${reregistrationAttempts}/${maxAttempts})...`);
+      const projectOk = await reRegisterProject(args.project_key);
+      if (!projectOk) {
+        throw error45;
+      }
+      if (args.agent_name && (isAgentError || toolName !== "ensure_project")) {
+        const agentOk = await reRegisterAgent(args.project_key, args.agent_name, options?.taskDescription);
+        if (!agentOk) {
+          console.warn(`[agent-mail] Agent re-registration failed, but continuing with retry...`);
+        }
+      }
+      console.warn(`[agent-mail] Retrying ${toolName} after re-registration...`);
+    }
+  }
+}
 function requireState(sessionID) {
   let state = sessionStates.get(sessionID);
   if (!state) {
@@ -24928,10 +25037,10 @@ var swarm_plan_prompt = tool({
   args: {
     task: tool.schema.string().min(1).describe("Task description to decompose"),
     strategy: tool.schema.enum(["file-based", "feature-based", "risk-based", "auto"]).optional().describe("Decomposition strategy (default: auto-detect)"),
-    max_subtasks: tool.schema.number().int().min(2).max(10).default(5).describe("Maximum number of subtasks (default: 5)"),
+    max_subtasks: tool.schema.number().int().min(2).default(5).describe("Maximum number of subtasks (default: 5)"),
     context: tool.schema.string().optional().describe("Additional context (codebase info, constraints, etc.)"),
     query_cass: tool.schema.boolean().optional().describe("Query CASS for similar past tasks (default: true)"),
-    cass_limit: tool.schema.number().int().min(1).max(10).optional().describe("Max CASS results to include (default: 3)")
+    cass_limit: tool.schema.number().int().min(1).optional().describe("Max CASS results to include (default: 3)")
   },
   async execute(args) {
     let selectedStrategy;
@@ -25001,10 +25110,10 @@ var swarm_decompose = tool({
   description: "Generate decomposition prompt for breaking task into parallelizable subtasks. Optionally queries CASS for similar past tasks.",
   args: {
     task: tool.schema.string().min(1).describe("Task description to decompose"),
-    max_subtasks: tool.schema.number().int().min(2).max(10).default(5).describe("Maximum number of subtasks (default: 5)"),
+    max_subtasks: tool.schema.number().int().min(2).default(5).describe("Maximum number of subtasks (default: 5)"),
     context: tool.schema.string().optional().describe("Additional context (codebase info, constraints, etc.)"),
     query_cass: tool.schema.boolean().optional().describe("Query CASS for similar past tasks (default: true)"),
-    cass_limit: tool.schema.number().int().min(1).max(10).optional().describe("Max CASS results to include (default: 3)")
+    cass_limit: tool.schema.number().int().min(1).optional().describe("Max CASS results to include (default: 3)")
   },
   async execute(args) {
     let cassContext = "";
@@ -25217,8 +25326,9 @@ var swarm_progress = tool({
       await Bun.$`bd update ${args.bead_id} --status ${beadStatus} --json`.quiet().nothrow();
     }
     const epicId = args.bead_id.includes(".") ? args.bead_id.split(".")[0] : args.bead_id;
-    await mcpCall("send_message", {
+    await mcpCallWithAutoInit("send_message", {
       project_key: args.project_key,
+      agent_name: args.agent_name,
       sender_name: args.agent_name,
       to: [],
       subject: `Progress: ${args.bead_id} - ${args.status}`,
@@ -25308,8 +25418,9 @@ ${args.files_affected.map((f) => `- \`${f}\``).join(`
     ].filter(Boolean).join(`
 `);
     const mailImportance = args.importance === "blocker" ? "urgent" : args.importance === "warning" ? "high" : "normal";
-    await mcpCall("send_message", {
+    await mcpCallWithAutoInit("send_message", {
       project_key: state.projectKey,
+      agent_name: state.agentName,
       sender_name: state.agentName,
       to: [],
       subject: `[${args.importance.toUpperCase()}] Context update from ${state.agentName}`,
@@ -25381,7 +25492,7 @@ var swarm_complete = tool({
       throw new SwarmError(`Failed to close bead: ${closeResult.stderr.toString()}`, "complete");
     }
     try {
-      await mcpCall("release_file_reservations", {
+      await mcpCallWithAutoInit("release_file_reservations", {
         project_key: args.project_key,
         agent_name: args.agent_name
       });
@@ -25398,8 +25509,9 @@ var swarm_complete = tool({
       parsedEvaluation?.overall_feedback ? `**Feedback**: ${parsedEvaluation.overall_feedback}` : ""
     ].filter(Boolean).join(`
 `);
-    await mcpCall("send_message", {
+    await mcpCallWithAutoInit("send_message", {
       project_key: args.project_key,
+      agent_name: args.agent_name,
       sender_name: args.agent_name,
       to: [],
       subject: `Complete: ${args.bead_id}`,

package/dist/plugin.js

@@ -21608,7 +21608,7 @@ var BeadTreeSchema = exports_external.object({
     title: exports_external.string().min(1),
     description: exports_external.string().optional().default("")
   }),
-  subtasks: exports_external.array(SubtaskSpecSchema).min(1).max(10)
+  subtasks: exports_external.array(SubtaskSpecSchema).min(1)
 });
 var EpicCreateArgsSchema = exports_external.object({
   epic_title: exports_external.string().min(1),
@@ -21617,7 +21617,7 @@ var EpicCreateArgsSchema = exports_external.object({
     title: exports_external.string().min(1),
     priority: exports_external.number().int().min(0).max(3).default(2),
     files: exports_external.array(exports_external.string()).optional().default([])
-  })).min(1).max(10)
+  })).min(1)
 });
 var EpicCreateResultSchema = exports_external.object({
   success: exports_external.boolean(),
@@ -21720,13 +21720,13 @@ var SubtaskDependencySchema = exports_external.object({
 var TaskDecompositionSchema = exports_external.object({
   task: exports_external.string(),
   reasoning: exports_external.string().optional(),
-  subtasks: exports_external.array(DecomposedSubtaskSchema).min(1).max(10),
+  subtasks: exports_external.array(DecomposedSubtaskSchema).min(1),
   dependencies: exports_external.array(SubtaskDependencySchema).optional().default([]),
   shared_context: exports_external.string().optional()
 });
 var DecomposeArgsSchema = exports_external.object({
   task: exports_external.string().min(1),
-  max_subtasks: exports_external.number().int().min(1).max(10).default(5),
+  max_subtasks: exports_external.number().int().min(1).default(5),
   context: exports_external.string().optional()
 });
 var SpawnedAgentSchema = exports_external.object({
@@ -22153,7 +22153,40 @@ var beads_sync = tool({
       }
     }
     if (autoPull) {
+      const dirtyCheckResult = await runGitCommand([
+        "status",
+        "--porcelain",
+        "--untracked-files=no"
+      ]);
+      const hasDirtyFiles = dirtyCheckResult.stdout.trim() !== "";
+      let didStash = false;
+      if (hasDirtyFiles) {
+        console.warn("[beads] Detected unstaged changes, stashing before pull...");
+        const stashResult = await runGitCommand([
+          "stash",
+          "push",
+          "-m",
+          "beads_sync: auto-stash before pull",
+          "--include-untracked"
+        ]);
+        if (stashResult.exitCode === 0) {
+          didStash = true;
+          console.warn("[beads] Changes stashed successfully");
+        } else {
+          console.warn(`[beads] Stash failed (${stashResult.stderr}), attempting pull anyway...`);
+        }
+      }
       const pullResult = await withTimeout(runGitCommand(["pull", "--rebase"]), TIMEOUT_MS, "git pull --rebase");
+      if (didStash) {
+        console.warn("[beads] Restoring stashed changes...");
+        const unstashResult = await runGitCommand(["stash", "pop"]);
+        if (unstashResult.exitCode !== 0) {
+          console.error(`[beads] WARNING: Failed to restore stashed changes: ${unstashResult.stderr}`);
+          console.error("[beads] Your changes are in 'git stash list' - run 'git stash pop' manually");
+        } else {
+          console.warn("[beads] Stashed changes restored");
+        }
+      }
       if (pullResult.exitCode !== 0) {
         throw new BeadError(`Failed to pull: ${pullResult.stderr}`, "git pull --rebase", pullResult.exitCode);
       }
@@ -22984,6 +23017,20 @@ function isRetryableError(error45) {
   }
   return false;
 }
+function isProjectNotFoundError(error45) {
+  if (error45 instanceof Error) {
+    const message = error45.message.toLowerCase();
+    return message.includes("project") && (message.includes("not found") || message.includes("does not exist"));
+  }
+  return false;
+}
+function isAgentNotFoundError(error45) {
+  if (error45 instanceof Error) {
+    const message = error45.message.toLowerCase();
+    return message.includes("agent") && (message.includes("not found") || message.includes("does not exist"));
+  }
+  return false;
+}
 var agentMailAvailable = null;
 async function checkAgentMailAvailable() {
   if (agentMailAvailable !== null) {
@@ -23114,6 +23161,68 @@ async function mcpCall(toolName, args) {
   }
   throw lastError || new Error("Unknown error in mcpCall");
 }
+async function reRegisterProject(projectKey) {
+  try {
+    console.warn(`[agent-mail] Re-registering project "${projectKey}" after server restart...`);
+    await mcpCall("ensure_project", {
+      human_key: projectKey
+    });
+    console.warn(`[agent-mail] Project "${projectKey}" re-registered successfully`);
+    return true;
+  } catch (error45) {
+    console.error(`[agent-mail] Failed to re-register project "${projectKey}":`, error45);
+    return false;
+  }
+}
+async function reRegisterAgent(projectKey, agentName, taskDescription) {
+  try {
+    console.warn(`[agent-mail] Re-registering agent "${agentName}" for project "${projectKey}"...`);
+    await mcpCall("register_agent", {
+      project_key: projectKey,
+      program: "opencode",
+      model: "claude-opus-4",
+      name: agentName,
+      task_description: taskDescription || "Re-registered after server restart"
+    });
+    console.warn(`[agent-mail] Agent "${agentName}" re-registered successfully`);
+    return true;
+  } catch (error45) {
+    console.error(`[agent-mail] Failed to re-register agent "${agentName}":`, error45);
+    return false;
+  }
+}
+async function mcpCallWithAutoInit(toolName, args, options) {
+  const maxAttempts = options?.maxReregistrationAttempts ?? 1;
+  let reregistrationAttempts = 0;
+  while (true) {
+    try {
+      return await mcpCall(toolName, args);
+    } catch (error45) {
+      const isProjectError = isProjectNotFoundError(error45);
+      const isAgentError = isAgentNotFoundError(error45);
+      if (!isProjectError && !isAgentError) {
+        throw error45;
+      }
+      if (reregistrationAttempts >= maxAttempts) {
+        console.error(`[agent-mail] Exhausted ${maxAttempts} re-registration attempt(s) for ${toolName}`);
+        throw error45;
+      }
+      reregistrationAttempts++;
+      console.warn(`[agent-mail] Detected "${isProjectError ? "project" : "agent"} not found" for ${toolName}, ` + `attempting re-registration (attempt ${reregistrationAttempts}/${maxAttempts})...`);
+      const projectOk = await reRegisterProject(args.project_key);
+      if (!projectOk) {
+        throw error45;
+      }
+      if (args.agent_name && (isAgentError || toolName !== "ensure_project")) {
+        const agentOk = await reRegisterAgent(args.project_key, args.agent_name, options?.taskDescription);
+        if (!agentOk) {
+          console.warn(`[agent-mail] Agent re-registration failed, but continuing with retry...`);
+        }
+      }
+      console.warn(`[agent-mail] Retrying ${toolName} after re-registration...`);
+    }
+  }
+}
 function requireState(sessionID) {
   let state = sessionStates.get(sessionID);
   if (!state) {
@@ -24867,10 +24976,10 @@ var swarm_plan_prompt = tool({
   args: {
     task: tool.schema.string().min(1).describe("Task description to decompose"),
     strategy: tool.schema.enum(["file-based", "feature-based", "risk-based", "auto"]).optional().describe("Decomposition strategy (default: auto-detect)"),
-    max_subtasks: tool.schema.number().int().min(2).max(10).default(5).describe("Maximum number of subtasks (default: 5)"),
+    max_subtasks: tool.schema.number().int().min(2).default(5).describe("Maximum number of subtasks (default: 5)"),
     context: tool.schema.string().optional().describe("Additional context (codebase info, constraints, etc.)"),
     query_cass: tool.schema.boolean().optional().describe("Query CASS for similar past tasks (default: true)"),
-    cass_limit: tool.schema.number().int().min(1).max(10).optional().describe("Max CASS results to include (default: 3)")
+    cass_limit: tool.schema.number().int().min(1).optional().describe("Max CASS results to include (default: 3)")
   },
   async execute(args) {
     let selectedStrategy;
@@ -24940,10 +25049,10 @@ var swarm_decompose = tool({
   description: "Generate decomposition prompt for breaking task into parallelizable subtasks. Optionally queries CASS for similar past tasks.",
   args: {
     task: tool.schema.string().min(1).describe("Task description to decompose"),
-    max_subtasks: tool.schema.number().int().min(2).max(10).default(5).describe("Maximum number of subtasks (default: 5)"),
+    max_subtasks: tool.schema.number().int().min(2).default(5).describe("Maximum number of subtasks (default: 5)"),
     context: tool.schema.string().optional().describe("Additional context (codebase info, constraints, etc.)"),
     query_cass: tool.schema.boolean().optional().describe("Query CASS for similar past tasks (default: true)"),
-    cass_limit: tool.schema.number().int().min(1).max(10).optional().describe("Max CASS results to include (default: 3)")
+    cass_limit: tool.schema.number().int().min(1).optional().describe("Max CASS results to include (default: 3)")
   },
   async execute(args) {
     let cassContext = "";
@@ -25156,8 +25265,9 @@ var swarm_progress = tool({
       await Bun.$`bd update ${args.bead_id} --status ${beadStatus} --json`.quiet().nothrow();
     }
     const epicId = args.bead_id.includes(".") ? args.bead_id.split(".")[0] : args.bead_id;
-    await mcpCall("send_message", {
+    await mcpCallWithAutoInit("send_message", {
       project_key: args.project_key,
+      agent_name: args.agent_name,
       sender_name: args.agent_name,
       to: [],
       subject: `Progress: ${args.bead_id} - ${args.status}`,
@@ -25247,8 +25357,9 @@ ${args.files_affected.map((f) => `- \`${f}\``).join(`
     ].filter(Boolean).join(`
 `);
     const mailImportance = args.importance === "blocker" ? "urgent" : args.importance === "warning" ? "high" : "normal";
-    await mcpCall("send_message", {
+    await mcpCallWithAutoInit("send_message", {
       project_key: state.projectKey,
+      agent_name: state.agentName,
       sender_name: state.agentName,
       to: [],
       subject: `[${args.importance.toUpperCase()}] Context update from ${state.agentName}`,
@@ -25320,7 +25431,7 @@ var swarm_complete = tool({
       throw new SwarmError(`Failed to close bead: ${closeResult.stderr.toString()}`, "complete");
     }
     try {
-      await mcpCall("release_file_reservations", {
+      await mcpCallWithAutoInit("release_file_reservations", {
         project_key: args.project_key,
         agent_name: args.agent_name
       });
@@ -25337,8 +25448,9 @@ var swarm_complete = tool({
       parsedEvaluation?.overall_feedback ? `**Feedback**: ${parsedEvaluation.overall_feedback}` : ""
     ].filter(Boolean).join(`
 `);
-    await mcpCall("send_message", {
+    await mcpCallWithAutoInit("send_message", {
       project_key: args.project_key,
+      agent_name: args.agent_name,
       sender_name: args.agent_name,
       to: [],
       subject: `Complete: ${args.bead_id}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.12.18",
+  "version": "0.12.20",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

package/src/agent-mail.integration.test.ts

@@ -11,12 +11,15 @@
 import { describe, it, expect, beforeAll } from "vitest";
 import {
   mcpCall,
+  mcpCallWithAutoInit,
   sessionStates,
   setState,
   clearState,
   requireState,
   MAX_INBOX_LIMIT,
   AgentMailNotInitializedError,
+  isProjectNotFoundError,
+  isAgentNotFoundError,
   type AgentMailState,
 } from "./agent-mail";
 
@@ -1318,4 +1321,109 @@ describe("agent-mail integration", () => {
       clearState(worker2Ctx.sessionID);
     });
   });
+
+  // ============================================================================
+  // Self-Healing Tests (mcpCallWithAutoInit)
+  // ============================================================================
+
+  describe("self-healing (mcpCallWithAutoInit)", () => {
+    it("detects project not found errors correctly", () => {
+      const projectError = new Error("Project 'migrate-egghead' not found.");
+      const agentError = new Error("Agent 'BlueLake' not found in project");
+      const otherError = new Error("Network timeout");
+
+      expect(isProjectNotFoundError(projectError)).toBe(true);
+      expect(isProjectNotFoundError(agentError)).toBe(false);
+      expect(isProjectNotFoundError(otherError)).toBe(false);
+
+      expect(isAgentNotFoundError(agentError)).toBe(true);
+      expect(isAgentNotFoundError(projectError)).toBe(false);
+      expect(isAgentNotFoundError(otherError)).toBe(false);
+    });
+
+    it("auto-registers project on 'not found' error", async () => {
+      const ctx = createTestContext();
+
+      // First, ensure project exists and register an agent
+      const { state } = await initTestAgent(ctx, `AutoInit_${Date.now()}`);
+
+      // Now use mcpCallWithAutoInit - it should work normally
+      // (no error to recover from, but verifies the wrapper works)
+      await mcpCallWithAutoInit("send_message", {
+        project_key: state.projectKey,
+        agent_name: state.agentName,
+        sender_name: state.agentName,
+        to: [],
+        subject: "Test auto-init wrapper",
+        body_md: "This should work normally",
+        thread_id: "test-thread",
+        importance: "normal",
+      });
+
+      // Verify message was sent by checking inbox
+      const inbox = await mcpCall<Array<{ subject: string }>>("fetch_inbox", {
+        project_key: state.projectKey,
+        agent_name: state.agentName,
+        limit: 5,
+        include_bodies: false,
+      });
+
+      // The message should be in the inbox (sent to empty 'to' = broadcast)
+      // Note: depending on Agent Mail behavior, broadcast might not show in sender's inbox
+      // This test mainly verifies the wrapper doesn't break normal operation
+
+      // Cleanup
+      clearState(ctx.sessionID);
+    });
+
+    it("recovers from simulated project not found by re-registering", async () => {
+      const ctx = createTestContext();
+
+      // Create a fresh project key that doesn't exist yet
+      const freshProjectKey = `/test/fresh-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const agentName = `Recovery_${Date.now()}`;
+
+      // First ensure the project exists (simulating initial setup)
+      await mcpCall("ensure_project", { human_key: freshProjectKey });
+      await mcpCall("register_agent", {
+        project_key: freshProjectKey,
+        program: "opencode-test",
+        model: "test-model",
+        name: agentName,
+        task_description: "Recovery test agent",
+      });
+
+      // Now use mcpCallWithAutoInit for an operation
+      // This should work, and if the project somehow got lost, it would re-register
+      await mcpCallWithAutoInit("send_message", {
+        project_key: freshProjectKey,
+        agent_name: agentName,
+        sender_name: agentName,
+        to: [],
+        subject: "Recovery test",
+        body_md: "Testing self-healing",
+        thread_id: "recovery-test",
+        importance: "normal",
+      });
+
+      // If we got here without error, the wrapper is working
+      // (In a real scenario where the server restarted, it would have re-registered)
+    });
+
+    it("passes through non-recoverable errors", async () => {
+      const ctx = createTestContext();
+      const { state } = await initTestAgent(ctx, `ErrorPass_${Date.now()}`);
+
+      // Try to call a non-existent tool - should throw, not retry forever
+      await expect(
+        mcpCallWithAutoInit("nonexistent_tool_xyz", {
+          project_key: state.projectKey,
+          agent_name: state.agentName,
+        }),
+      ).rejects.toThrow(/Unknown tool/);
+
+      // Cleanup
+      clearState(ctx.sessionID);
+    });
+  });
 });

package/src/agent-mail.ts

@@ -541,6 +541,39 @@ function isRetryableError(error: unknown): boolean {
   return false;
 }
 
+/**
+ * Check if an error indicates the project was not found
+ *
+ * This happens when Agent Mail server restarts and loses project registrations.
+ * The fix is to re-register the project and retry the operation.
+ */
+export function isProjectNotFoundError(error: unknown): boolean {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("project") &&
+      (message.includes("not found") || message.includes("does not exist"))
+    );
+  }
+  return false;
+}
+
+/**
+ * Check if an error indicates the agent was not found
+ *
+ * Similar to project not found - server restart loses agent registrations.
+ */
+export function isAgentNotFoundError(error: unknown): boolean {
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    return (
+      message.includes("agent") &&
+      (message.includes("not found") || message.includes("does not exist"))
+    );
+  }
+  return false;
+}
+
 // ============================================================================
 // MCP Client
 // ============================================================================
@@ -823,6 +856,153 @@ export async function mcpCall<T>(
   throw lastError || new Error("Unknown error in mcpCall");
 }
 
+/**
+ * Re-register a project with Agent Mail server
+ *
+ * Called when we detect "Project not found" error, indicating server restart.
+ * This is a lightweight operation that just ensures the project exists.
+ */
+async function reRegisterProject(projectKey: string): Promise<boolean> {
+  try {
+    console.warn(
+      `[agent-mail] Re-registering project "${projectKey}" after server restart...`,
+    );
+    await mcpCall<ProjectInfo>("ensure_project", {
+      human_key: projectKey,
+    });
+    console.warn(
+      `[agent-mail] Project "${projectKey}" re-registered successfully`,
+    );
+    return true;
+  } catch (error) {
+    console.error(
+      `[agent-mail] Failed to re-register project "${projectKey}":`,
+      error,
+    );
+    return false;
+  }
+}
+
+/**
+ * Re-register an agent with Agent Mail server
+ *
+ * Called when we detect "Agent not found" error, indicating server restart.
+ */
+async function reRegisterAgent(
+  projectKey: string,
+  agentName: string,
+  taskDescription?: string,
+): Promise<boolean> {
+  try {
+    console.warn(
+      `[agent-mail] Re-registering agent "${agentName}" for project "${projectKey}"...`,
+    );
+    await mcpCall<AgentInfo>("register_agent", {
+      project_key: projectKey,
+      program: "opencode",
+      model: "claude-opus-4",
+      name: agentName,
+      task_description: taskDescription || "Re-registered after server restart",
+    });
+    console.warn(
+      `[agent-mail] Agent "${agentName}" re-registered successfully`,
+    );
+    return true;
+  } catch (error) {
+    console.error(
+      `[agent-mail] Failed to re-register agent "${agentName}":`,
+      error,
+    );
+    return false;
+  }
+}
+
+/**
+ * MCP call with automatic project/agent re-registration on "not found" errors
+ *
+ * This is the self-healing wrapper that handles Agent Mail server restarts.
+ * When the server restarts, it loses all project and agent registrations.
+ * This wrapper detects those errors and automatically re-registers before retrying.
+ *
+ * Use this instead of raw mcpCall when you have project_key and agent_name context.
+ *
+ * @param toolName - The MCP tool to call
+ * @param args - Arguments including project_key and optionally agent_name
+ * @param options - Optional configuration for re-registration
+ * @returns The result of the MCP call
+ */
+export async function mcpCallWithAutoInit<T>(
+  toolName: string,
+  args: Record<string, unknown> & { project_key: string; agent_name?: string },
+  options?: {
+    /** Task description for agent re-registration */
+    taskDescription?: string;
+    /** Max re-registration attempts (default: 1) */
+    maxReregistrationAttempts?: number;
+  },
+): Promise<T> {
+  const maxAttempts = options?.maxReregistrationAttempts ?? 1;
+  let reregistrationAttempts = 0;
+
+  while (true) {
+    try {
+      return await mcpCall<T>(toolName, args);
+    } catch (error) {
+      // Check if this is a recoverable "not found" error
+      const isProjectError = isProjectNotFoundError(error);
+      const isAgentError = isAgentNotFoundError(error);
+
+      if (!isProjectError && !isAgentError) {
+        // Not a recoverable error, rethrow
+        throw error;
+      }
+
+      // Check if we've exhausted re-registration attempts
+      if (reregistrationAttempts >= maxAttempts) {
+        console.error(
+          `[agent-mail] Exhausted ${maxAttempts} re-registration attempt(s) for ${toolName}`,
+        );
+        throw error;
+      }
+
+      reregistrationAttempts++;
+      console.warn(
+        `[agent-mail] Detected "${isProjectError ? "project" : "agent"} not found" for ${toolName}, ` +
+          `attempting re-registration (attempt ${reregistrationAttempts}/${maxAttempts})...`,
+      );
+
+      // Re-register project first (always needed)
+      const projectOk = await reRegisterProject(args.project_key);
+      if (!projectOk) {
+        throw error; // Can't recover without project
+      }
+
+      // Re-register agent if we have one and it was an agent error
+      // (or if the original call needs an agent)
+      if (args.agent_name && (isAgentError || toolName !== "ensure_project")) {
+        const agentOk = await reRegisterAgent(
+          args.project_key,
+          args.agent_name,
+          options?.taskDescription,
+        );
+        if (!agentOk) {
+          // Agent re-registration failed, but project is OK
+          // Some operations might still work, so continue
+          console.warn(
+            `[agent-mail] Agent re-registration failed, but continuing with retry...`,
+          );
+        }
+      }
+
+      // Retry the original call
+      console.warn(
+        `[agent-mail] Retrying ${toolName} after re-registration...`,
+      );
+      // Loop continues to retry
+    }
+  }
+}
+
 /**
  * Get Agent Mail state for a session, or throw if not initialized
  *
@@ -1490,4 +1670,6 @@ export {
   restartServer,
   RETRY_CONFIG,
   RECOVERY_CONFIG,
+  // Note: isProjectNotFoundError, isAgentNotFoundError, mcpCallWithAutoInit
+  // are exported at their definitions
 };

package/src/beads.ts

@@ -717,11 +717,61 @@ export const beads_sync = tool({
 
     // 5. Pull if requested (with rebase to avoid merge commits)
     if (autoPull) {
+      // Check for unstaged changes that would block pull --rebase
+      const dirtyCheckResult = await runGitCommand([
+        "status",
+        "--porcelain",
+        "--untracked-files=no",
+      ]);
+      const hasDirtyFiles = dirtyCheckResult.stdout.trim() !== "";
+      let didStash = false;
+
+      // Stash dirty files before pull (self-healing for "unstaged changes" error)
+      if (hasDirtyFiles) {
+        console.warn(
+          "[beads] Detected unstaged changes, stashing before pull...",
+        );
+        const stashResult = await runGitCommand([
+          "stash",
+          "push",
+          "-m",
+          "beads_sync: auto-stash before pull",
+          "--include-untracked",
+        ]);
+        if (stashResult.exitCode === 0) {
+          didStash = true;
+          console.warn("[beads] Changes stashed successfully");
+        } else {
+          // Stash failed - try pull anyway, it might work
+          console.warn(
+            `[beads] Stash failed (${stashResult.stderr}), attempting pull anyway...`,
+          );
+        }
+      }
+
       const pullResult = await withTimeout(
         runGitCommand(["pull", "--rebase"]),
         TIMEOUT_MS,
         "git pull --rebase",
       );
+
+      // Restore stashed changes regardless of pull result
+      if (didStash) {
+        console.warn("[beads] Restoring stashed changes...");
+        const unstashResult = await runGitCommand(["stash", "pop"]);
+        if (unstashResult.exitCode !== 0) {
+          // Unstash failed - this is bad, user needs to know
+          console.error(
+            `[beads] WARNING: Failed to restore stashed changes: ${unstashResult.stderr}`,
+          );
+          console.error(
+            "[beads] Your changes are in 'git stash list' - run 'git stash pop' manually",
+          );
+        } else {
+          console.warn("[beads] Stashed changes restored");
+        }
+      }
+
       if (pullResult.exitCode !== 0) {
         throw new BeadError(
           `Failed to pull: ${pullResult.stderr}`,

package/src/schemas/bead.ts

@@ -117,7 +117,7 @@ export const BeadTreeSchema = z.object({
     title: z.string().min(1),
     description: z.string().optional().default(""),
   }),
-  subtasks: z.array(SubtaskSpecSchema).min(1).max(10),
+  subtasks: z.array(SubtaskSpecSchema).min(1),
 });
 export type BeadTree = z.infer<typeof BeadTreeSchema>;
 
@@ -133,8 +133,7 @@ export const EpicCreateArgsSchema = z.object({
         files: z.array(z.string()).optional().default([]),
       }),
     )
-    .min(1)
-    .max(10),
+    .min(1),
 });
 export type EpicCreateArgs = z.infer<typeof EpicCreateArgsSchema>;
 

package/src/schemas/task.ts

@@ -57,7 +57,7 @@ export type SubtaskDependency = z.infer<typeof SubtaskDependencySchema>;
 export const TaskDecompositionSchema = z.object({
   task: z.string(), // Original task description
   reasoning: z.string().optional(), // Why this decomposition
-  subtasks: z.array(DecomposedSubtaskSchema).min(1).max(10),
+  subtasks: z.array(DecomposedSubtaskSchema).min(1),
   dependencies: z.array(SubtaskDependencySchema).optional().default([]),
   shared_context: z.string().optional(), // Context to pass to all agents
 });
@@ -68,7 +68,7 @@ export type TaskDecomposition = z.infer<typeof TaskDecompositionSchema>;
  */
 export const DecomposeArgsSchema = z.object({
   task: z.string().min(1),
-  max_subtasks: z.number().int().min(1).max(10).default(5),
+  max_subtasks: z.number().int().min(1).default(5),
   context: z.string().optional(),
 });
 export type DecomposeArgs = z.infer<typeof DecomposeArgsSchema>;

package/src/swarm.ts

@@ -25,7 +25,7 @@ import {
   type SpawnedAgent,
   type Bead,
 } from "./schemas";
-import { mcpCall, requireState } from "./agent-mail";
+import { mcpCall, mcpCallWithAutoInit, requireState } from "./agent-mail";
 import {
   OutcomeSignalsSchema,
   DecompositionStrategySchema,
@@ -1222,7 +1222,7 @@ export const swarm_plan_prompt = tool({
       .number()
       .int()
       .min(2)
-      .max(10)
+
       .default(5)
       .describe("Maximum number of subtasks (default: 5)"),
     context: tool.schema
@@ -1237,7 +1237,7 @@ export const swarm_plan_prompt = tool({
       .number()
       .int()
       .min(1)
-      .max(10)
+
       .optional()
       .describe("Max CASS results to include (default: 3)"),
   },
@@ -1352,7 +1352,7 @@ export const swarm_decompose = tool({
       .number()
       .int()
       .min(2)
-      .max(10)
+
       .default(5)
       .describe("Maximum number of subtasks (default: 5)"),
     context: tool.schema
@@ -1367,7 +1367,7 @@ export const swarm_decompose = tool({
       .number()
       .int()
       .min(1)
-      .max(10)
+
       .optional()
       .describe("Max CASS results to include (default: 3)"),
   },
@@ -1721,9 +1721,10 @@ export const swarm_progress = tool({
       ? args.bead_id.split(".")[0]
       : args.bead_id;
 
-    // Send progress message to thread
-    await mcpCall("send_message", {
+    // Send progress message to thread (with auto-reinit on server restart)
+    await mcpCallWithAutoInit("send_message", {
       project_key: args.project_key,
+      agent_name: args.agent_name,
       sender_name: args.agent_name,
       to: [], // Coordinator will pick it up from thread
       subject: `Progress: ${args.bead_id} - ${args.status}`,
@@ -1892,8 +1893,10 @@ export const swarm_broadcast = tool({
           : "normal";
 
     // Send as broadcast to thread (empty 'to' = all agents in thread)
-    await mcpCall("send_message", {
+    // Uses auto-reinit wrapper to handle server restarts gracefully
+    await mcpCallWithAutoInit("send_message", {
       project_key: state.projectKey,
+      agent_name: state.agentName,
       sender_name: state.agentName,
       to: [], // Broadcast to thread
       subject: `[${args.importance.toUpperCase()}] Context update from ${state.agentName}`,
@@ -2020,12 +2023,16 @@ export const swarm_complete = tool({
     }
 
     // Release file reservations for this agent
+    // Uses auto-reinit wrapper to handle server restarts - this was the original
+    // failure point that prompted the self-healing implementation
     try {
-      await mcpCall("release_file_reservations", {
+      await mcpCallWithAutoInit("release_file_reservations", {
         project_key: args.project_key,
         agent_name: args.agent_name,
       });
     } catch (error) {
+      // Even with auto-reinit, 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,
@@ -2053,8 +2060,9 @@ export const swarm_complete = tool({
       .filter(Boolean)
       .join("\n");
 
-    await mcpCall("send_message", {
+    await mcpCallWithAutoInit("send_message", {
       project_key: args.project_key,
+      agent_name: args.agent_name,
       sender_name: args.agent_name,
       to: [], // Thread broadcast
       subject: `Complete: ${args.bead_id}`,