opencode-swarm-plugin 0.17.1 → 0.19.0

package/src/anti-patterns.ts

@@ -19,10 +19,15 @@ export const PatternKindSchema = z.enum(["pattern", "anti_pattern"]);
 export type PatternKind = z.infer<typeof PatternKindSchema>;
 
 /**
- * A decomposition pattern that has been observed
+ * Decomposition pattern with success/failure tracking.
  *
- * Patterns are extracted from successful/failed decompositions and
- * tracked over time to learn what works and what doesn't.
+ * Field relationships:
+ * - `kind`: Tracks pattern lifecycle ("pattern" → "anti_pattern" when failure rate exceeds threshold)
+ * - `is_negative`: Derived boolean flag for quick filtering (true when kind === "anti_pattern")
+ *
+ * Both fields exist because:
+ * - `kind` is the source of truth for pattern status
+ * - `is_negative` enables efficient filtering without string comparison
  */
 export const DecompositionPatternSchema = z.object({
   /** Unique ID for this pattern */
@@ -69,6 +74,9 @@ export type PatternInversionResult = z.infer<
 // Configuration
 // ============================================================================
 
+/** Maximum number of example beads to keep per pattern */
+const MAX_EXAMPLE_BEADS = 10;
+
 /**
  * Configuration for anti-pattern detection
  */
@@ -186,7 +194,7 @@ export function recordPatternObservation(
     failure_count: success ? pattern.failure_count : pattern.failure_count + 1,
     updated_at: new Date().toISOString(),
     example_beads: beadId
-      ? [...pattern.example_beads.slice(-9), beadId] // Keep last 10
+      ? [...pattern.example_beads.slice(-(MAX_EXAMPLE_BEADS - 1)), beadId]
       : pattern.example_beads,
   };
 
@@ -216,8 +224,16 @@ export function recordPatternObservation(
 export function extractPatternsFromDescription(description: string): string[] {
   const patterns: string[] = [];
 
-  // Common decomposition strategies to detect
-  const strategyPatterns = [
+  /**
+   * Regex patterns for detecting common decomposition strategies.
+   *
+   * Detection is keyword-based and not exhaustive - patterns can be
+   * manually created for novel strategies not covered here.
+   *
+   * Each pattern maps a regex to a strategy name that will be extracted
+   * from task descriptions during pattern observation.
+   */
+  const strategyPatterns: Array<{ regex: RegExp; pattern: string }> = [
     {
       regex: /split(?:ting)?\s+by\s+file\s+type/i,
       pattern: "Split by file type",
@@ -322,15 +338,17 @@ export function formatAntiPatternsForPrompt(
 }
 
 /**
- * Format successful patterns for inclusion in decomposition prompts
+ * Format successful patterns for inclusion in prompts.
  *
- * @param patterns - Patterns to format
- * @param minSuccessRate - Minimum success rate to include (0-1)
- * @returns Formatted string for prompt inclusion
+ * @param patterns - Array of decomposition patterns to filter and format
+ * @param minSuccessRate - Minimum success rate to include (default 0.7 = 70%).
+ *   Chosen to filter out patterns with marginal track records - only patterns
+ *   that succeed at least 70% of the time are recommended.
+ * @returns Formatted string of successful patterns for prompt injection
  */
 export function formatSuccessfulPatternsForPrompt(
   patterns: DecompositionPattern[],
-  minSuccessRate: number = 0.7,
+  minSuccessRate = 0.7,
 ): string {
   const successful = patterns.filter((p) => {
     if (p.kind === "anti_pattern") return false;

package/src/learning.ts

@@ -956,6 +956,112 @@ export class ErrorAccumulator {
   }
 }
 
+// ============================================================================
+// Semantic Memory Integration Helpers
+// ============================================================================
+
+/**
+ * Format memory store instruction for successful task completion
+ *
+ * @param beadId - Bead ID that completed
+ * @param summary - Completion summary
+ * @param filesTouched - Files modified
+ * @param strategy - Decomposition strategy used (if applicable)
+ * @returns Memory store instruction object
+ */
+export function formatMemoryStoreOnSuccess(
+  beadId: string,
+  summary: string,
+  filesTouched: string[],
+  strategy?: DecompositionStrategy,
+): {
+  information: string;
+  metadata: string;
+  instruction: string;
+} {
+  const strategyInfo = strategy ? ` using ${strategy} strategy` : "";
+
+  return {
+    information: `Task "${beadId}" completed successfully${strategyInfo}.
+Key insight: ${summary}
+Files touched: ${filesTouched.join(", ") || "none"}`,
+    metadata: `swarm, success, ${beadId}, ${strategy || "completion"}`,
+    instruction:
+      "Store this successful completion in semantic-memory for future reference",
+  };
+}
+
+/**
+ * Format memory store instruction for architectural problems (3-strike)
+ *
+ * @param beadId - Bead ID that struck out
+ * @param failures - Array of failure attempts
+ * @returns Memory store instruction object
+ */
+export function formatMemoryStoreOn3Strike(
+  beadId: string,
+  failures: Array<{ attempt: string; reason: string }>,
+): {
+  information: string;
+  metadata: string;
+  instruction: string;
+} {
+  const failuresList = failures
+    .map((f, i) => `${i + 1}. ${f.attempt} - Failed: ${f.reason}`)
+    .join("\n");
+
+  return {
+    information: `Architecture problem detected in ${beadId}: Task failed after 3 attempts.
+Attempts:
+${failuresList}
+
+This indicates a structural issue requiring human decision, not another fix attempt.`,
+    metadata: `architecture, 3-strike, ${beadId}, failure`,
+    instruction:
+      "Store this architectural problem in semantic-memory to avoid similar patterns in future",
+  };
+}
+
+/**
+ * Format memory query instruction for task decomposition
+ *
+ * @param task - Task description
+ * @param limit - Max results to return
+ * @returns Memory query instruction object
+ */
+export function formatMemoryQueryForDecomposition(
+  task: string,
+  limit: number = 3,
+): {
+  query: string;
+  limit: number;
+  instruction: string;
+} {
+  return {
+    query: task,
+    limit,
+    instruction:
+      "Query semantic-memory for relevant past learnings about similar tasks before decomposition",
+  };
+}
+
+/**
+ * Format memory validation hint when CASS history helped
+ *
+ * @param beadId - Bead ID that benefited from CASS
+ * @returns Memory validation hint
+ */
+export function formatMemoryValidationHint(beadId: string): {
+  instruction: string;
+  context: string;
+} {
+  return {
+    instruction:
+      "If any semantic-memory entries helped with this task, validate them to reset decay timer",
+    context: `Task ${beadId} completed successfully with assistance from past learnings`,
+  };
+}
+
 // ============================================================================
 // Exports
 // ============================================================================

package/src/pattern-maturity.ts

@@ -12,6 +12,16 @@
 import { z } from "zod";
 import { calculateDecayedValue } from "./learning";
 
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Tolerance for floating-point comparisons.
+ * Used when comparing success rates to avoid floating-point precision issues.
+ */
+const FLOAT_EPSILON = 0.01;
+
 // ============================================================================
 // Schemas
 // ============================================================================
@@ -164,26 +174,26 @@ export function calculateMaturityState(
   );
 
   const total = decayedHelpful + decayedHarmful;
-  const epsilon = 0.01; // Float comparison tolerance
-  const safeTotal = total > epsilon ? total : 0;
+  // Use FLOAT_EPSILON constant (defined at module level)
+  const safeTotal = total > FLOAT_EPSILON ? total : 0;
   const harmfulRatio = safeTotal > 0 ? decayedHarmful / safeTotal : 0;
 
   // Deprecated: high harmful ratio with enough feedback
   if (
     harmfulRatio > config.deprecationThreshold &&
-    safeTotal >= config.minFeedback - epsilon
+    safeTotal >= config.minFeedback - FLOAT_EPSILON
   ) {
     return "deprecated";
   }
 
   // Candidate: not enough feedback yet
-  if (safeTotal < config.minFeedback - epsilon) {
+  if (safeTotal < config.minFeedback - FLOAT_EPSILON) {
     return "candidate";
   }
 
   // Proven: strong positive signal
   if (
-    decayedHelpful >= config.minHelpful - epsilon &&
+    decayedHelpful >= config.minHelpful - FLOAT_EPSILON &&
     harmfulRatio < config.maxHarmful
   ) {
     return "proven";
@@ -210,14 +220,23 @@ export function createPatternMaturity(patternId: string): PatternMaturity {
 }
 
 /**
- * Update pattern maturity with new feedback
+ * Update pattern maturity with new feedback.
+ *
+ * Side Effects:
+ * - Sets `promoted_at` timestamp on first entry into 'proven' status
+ * - Sets `deprecated_at` timestamp on first entry into 'deprecated' status
+ * - Updates `helpful_count` and `harmful_count` based on feedback events
+ * - Recalculates `state` based on decayed feedback counts
  *
- * Records feedback, updates counts, and recalculates state.
+ * State Transitions:
+ * - candidate → established: After minFeedback observations (default 3)
+ * - established → proven: When decayedHelpful >= minHelpful (5) AND harmfulRatio < maxHarmful (15%)
+ * - any → deprecated: When harmfulRatio > deprecationThreshold (30%) AND total >= minFeedback
  *
  * @param maturity - Current maturity record
  * @param feedbackEvents - All feedback events for this pattern
  * @param config - Maturity configuration
- * @returns Updated maturity record
+ * @returns Updated maturity record with new state
  */
 export function updatePatternMaturity(
   maturity: PatternMaturity,
@@ -269,7 +288,16 @@ export function promotePattern(maturity: PatternMaturity): PatternMaturity {
   }
 
   if (maturity.state === "proven") {
-    return maturity; // Already proven
+    console.warn(
+      `[PatternMaturity] Pattern already proven: ${maturity.pattern_id}`,
+    );
+    return maturity; // No-op but warn
+  }
+
+  if (maturity.state === "candidate" && maturity.helpful_count < 3) {
+    console.warn(
+      `[PatternMaturity] Promoting candidate with insufficient data: ${maturity.pattern_id} (${maturity.helpful_count} helpful observations)`,
+    );
   }
 
   const now = new Date().toISOString();
@@ -309,12 +337,16 @@ export function deprecatePattern(
 }
 
 /**
- * Get maturity score multiplier for pattern ranking
+ * Get weight multiplier based on pattern maturity status.
  *
- * Higher maturity patterns should be weighted more heavily.
+ * Multipliers chosen to:
+ * - Heavily penalize deprecated patterns (0x) - never recommend
+ * - Slightly boost proven patterns (1.5x) - reward validated success
+ * - Penalize unvalidated candidates (0.5x) - reduce impact until proven
+ * - Neutral for established (1.0x) - baseline weight
  *
- * @param state - Maturity state
- * @returns Score multiplier (0-1.5)
+ * @param state - Pattern maturity status
+ * @returns Multiplier to apply to pattern weight
  */
 export function getMaturityMultiplier(state: MaturityState): number {
   const multipliers: Record<MaturityState, number> = {
@@ -336,6 +368,12 @@ export function getMaturityMultiplier(state: MaturityState): number {
  */
 export function formatMaturityForPrompt(maturity: PatternMaturity): string {
   const total = maturity.helpful_count + maturity.harmful_count;
+
+  // Don't show percentages for insufficient data
+  if (total < 3) {
+    return `[LIMITED DATA - ${total} observation${total !== 1 ? "s" : ""}]`;
+  }
+
   const harmfulRatio =
     total > 0 ? Math.round((maturity.harmful_count / total) * 100) : 0;
   const helpfulRatio =

package/src/plugin.ts

@@ -1,9 +1,21 @@
 /**
  * OpenCode Plugin Entry Point
  *
- * This file ONLY exports the plugin function.
- * The plugin loader iterates over all exports and calls them as functions,
- * so we cannot export anything else here (classes, constants, types, etc.)
+ * CRITICAL: Only export the plugin function from this file.
+ *
+ * OpenCode's plugin loader calls ALL exports as functions during initialization.
+ * Exporting classes, constants, or non-function values will cause the plugin
+ * to fail to load with cryptic errors.
+ *
+ * If you need to export utilities for external use, add them to src/index.ts instead.
+ *
+ * @example
+ * // ✅ CORRECT - only export the plugin function
+ * export default SwarmPlugin;
+ *
+ * // ❌ WRONG - will break plugin loading
+ * export const VERSION = "1.0.0";
+ * export class Helper {}
  */
 import { SwarmPlugin } from "./index";
 

package/src/rate-limiter.ts

@@ -35,12 +35,15 @@ import { homedir } from "node:os";
 // SQLite is optional - only available in Bun runtime
 // We use dynamic import to avoid breaking Node.js environments
 interface BunDatabase {
-  run(sql: string, params?: unknown[]): void;
+  run(
+    sql: string,
+    params?: unknown[],
+  ): { changes: number; lastInsertRowid: number };
   query<T>(sql: string): {
     get(...params: unknown[]): T | null;
   };
   prepare(sql: string): {
-    run(...params: unknown[]): void;
+    run(...params: unknown[]): { changes: number; lastInsertRowid: number };
   };
   close(): void;
 }
@@ -453,6 +456,47 @@ export class SqliteRateLimiter implements RateLimiter {
     return { allowed, remaining, resetAt };
   }
 
+  /**
+   * Clean up old rate limit entries in bounded batches
+   *
+   * Limits cleanup to prevent blocking recordRequest on large datasets:
+   * - BATCH_SIZE: 1000 rows per iteration
+   * - MAX_BATCHES: 10 (max 10k rows per cleanup invocation)
+   *
+   * Stops early if fewer than BATCH_SIZE rows deleted (no more to clean).
+   */
+  private cleanup(): void {
+    const BATCH_SIZE = 1000;
+    const MAX_BATCHES = 10;
+    const cutoff = Date.now() - 7_200_000; // 2 hours
+
+    let totalDeleted = 0;
+
+    // Run bounded batches
+    for (let i = 0; i < MAX_BATCHES; i++) {
+      const result = this.db.run(
+        `DELETE FROM rate_limits 
+         WHERE rowid IN (
+           SELECT rowid FROM rate_limits 
+           WHERE timestamp < ? 
+           LIMIT ?
+         )`,
+        [cutoff, BATCH_SIZE],
+      );
+
+      totalDeleted += result.changes;
+
+      // Stop if we deleted less than batch size (no more to delete)
+      if (result.changes < BATCH_SIZE) break;
+    }
+
+    if (totalDeleted > 0) {
+      console.log("[RateLimiter] Cleanup completed:", {
+        deletedRows: totalDeleted,
+      });
+    }
+  }
+
   async recordRequest(agentName: string, endpoint: string): Promise<void> {
     const now = Date.now();
 
@@ -465,9 +509,9 @@ export class SqliteRateLimiter implements RateLimiter {
     stmt.run(agentName, endpoint, "hour", now);
 
     // Opportunistic cleanup of old entries (1% chance to avoid overhead)
+    // Now bounded to prevent blocking on large datasets
     if (Math.random() < 0.01) {
-      const cutoff = Date.now() - 7_200_000;
-      this.db.run(`DELETE FROM rate_limits WHERE timestamp < ?`, [cutoff]);
+      this.cleanup();
     }
   }
 

package/src/schemas/bead.ts

@@ -42,19 +42,42 @@ export type BeadDependency = z.infer<typeof BeadDependencySchema>;
  * - Custom subtask: `{project}-{custom-id}.{suffix}` (e.g., `migrate-egghead-phase-0.e2e-test`)
  */
 export const BeadSchema = z.object({
+  /**
+   * Bead ID format: project-slug-hash with optional subtask index.
+   *
+   * Pattern: `project-name-xxxxx` or `project-name-xxxxx.N`
+   * Examples:
+   * - `my-project-abc12` (main bead)
+   * - `my-project-abc12.1` (first subtask)
+   * - `my-project-abc12.2` (second subtask)
+   */
   id: z
     .string()
-    .regex(/^[a-z0-9]+(-[a-z0-9]+)+(\.[\w-]+)?$/, "Invalid bead ID format"),
+    .regex(
+      /^[a-z0-9]+(-[a-z0-9]+)+(\.[\w-]+)?$/,
+      "Invalid bead ID format (expected: project-slug-hash or project-slug-hash.N)",
+    ),
   title: z.string().min(1, "Title required"),
   description: z.string().optional().default(""),
   status: BeadStatusSchema.default("open"),
   priority: z.number().int().min(0).max(3).default(2),
   issue_type: BeadTypeSchema.default("task"),
-  created_at: z.string().datetime({ offset: true }), // ISO-8601 with timezone offset
-  updated_at: z.string().datetime({ offset: true }).optional(),
+  created_at: z.string().datetime({
+    offset: true,
+    message:
+      "Must be ISO-8601 datetime with timezone (e.g., 2024-01-15T10:30:00Z)",
+  }),
+  updated_at: z
+    .string()
+    .datetime({
+      offset: true,
+      message:
+        "Must be ISO-8601 datetime with timezone (e.g., 2024-01-15T10:30:00Z)",
+    })
+    .optional(),
   closed_at: z.string().datetime({ offset: true }).optional(),
   parent_id: z.string().optional(),
-  dependencies: z.array(BeadDependencySchema).optional().default([]),
+  dependencies: z.array(BeadDependencySchema).default([]),
   metadata: z.record(z.string(), z.unknown()).optional(),
 });
 export type Bead = z.infer<typeof BeadSchema>;
@@ -111,6 +134,14 @@ export const SubtaskSpecSchema = z.object({
   description: z.string().optional().default(""),
   files: z.array(z.string()).default([]),
   dependencies: z.array(z.number().int().min(0)).default([]), // Indices of other subtasks
+  /**
+   * Complexity estimate on 1-5 scale:
+   * 1 = trivial (typo fix, simple rename)
+   * 2 = simple (single function change)
+   * 3 = moderate (multi-file, some coordination)
+   * 4 = complex (significant refactoring)
+   * 5 = very complex (architectural change)
+   */
   estimated_complexity: z.number().int().min(1).max(5).default(3),
 });
 export type SubtaskSpec = z.infer<typeof SubtaskSpecSchema>;

package/src/schemas/evaluation.ts

@@ -12,9 +12,15 @@
 import { z } from "zod";
 
 /**
- * Single criterion evaluation
+ * Evaluation of a single criterion.
  *
- * Each criterion (type_safe, no_bugs, etc.) gets its own evaluation.
+ * @example
+ * // Passing criterion
+ * { passed: true, feedback: "All types validated", score: 0.95 }
+ *
+ * @example
+ * // Failing criterion
+ * { passed: false, feedback: "Missing error handling in auth flow", score: 0.3 }
  */
 export const CriterionEvaluationSchema = z.object({
   passed: z.boolean(),
@@ -31,7 +37,11 @@ export type CriterionEvaluation = z.infer<typeof CriterionEvaluationSchema>;
  */
 export const WeightedCriterionEvaluationSchema =
   CriterionEvaluationSchema.extend({
-    /** Current weight after decay (0-1, lower = less reliable) */
+    /**
+     * Current weight after 90-day half-life decay.
+     * Range: 0-1 where 1 = recent/validated, 0 = old/unreliable.
+     * Weights decay over time unless revalidated via semantic-memory_validate.
+     */
     weight: z.number().min(0).max(1).default(1),
     /** Weighted score = score * weight */
     weighted_score: z.number().min(0).max(1).optional(),
@@ -75,9 +85,11 @@ export type DefaultCriterion = (typeof DEFAULT_CRITERIA)[number];
  * Evaluation request arguments
  */
 export const EvaluationRequestSchema = z.object({
-  subtask_id: z.string(),
-  criteria: z.array(z.string()).default([...DEFAULT_CRITERIA]),
-  context: z.string().optional(),
+  bead_id: z.string(),
+  subtask_title: z.string(),
+  files_touched: z.array(z.string()),
+  /** ISO-8601 timestamp when evaluation was requested */
+  requested_at: z.string().datetime().optional(),
 });
 export type EvaluationRequest = z.infer<typeof EvaluationRequestSchema>;
 

package/src/schemas/index.ts

@@ -1,7 +1,30 @@
 /**
- * Schema exports
+ * Schema Definitions - Central export point for all Zod schemas
  *
- * Re-export all schemas for convenient importing.
+ * This module re-exports all schema definitions used throughout the plugin.
+ * Schemas are organized by domain:
+ *
+ * ## Bead Schemas (Issue Tracking)
+ * - `BeadSchema` - Core bead/issue definition
+ * - `BeadStatusSchema` - Status enum (open, in_progress, blocked, closed)
+ * - `BeadTypeSchema` - Type enum (bug, feature, task, epic, chore)
+ * - `SubtaskSpecSchema` - Subtask specification for epic creation
+ *
+ * ## Task Schemas (Swarm Decomposition)
+ * - `TaskDecompositionSchema` - Full task breakdown
+ * - `DecomposedSubtaskSchema` - Individual subtask definition
+ * - `BeadTreeSchema` - Epic + subtasks structure
+ *
+ * ## Evaluation Schemas (Agent Self-Assessment)
+ * - `EvaluationSchema` - Complete evaluation with criteria
+ * - `CriterionEvaluationSchema` - Single criterion result
+ *
+ * ## Progress Schemas (Swarm Coordination)
+ * - `SwarmStatusSchema` - Overall swarm progress
+ * - `AgentProgressSchema` - Individual agent status
+ * - `SpawnedAgentSchema` - Spawned agent metadata
+ *
+ * @module schemas
  */
 
 // Bead schemas

package/src/schemas/task.ts

@@ -7,13 +7,19 @@
 import { z } from "zod";
 
 /**
- * Effort estimation levels
+ * Effort estimation for subtasks.
+ *
+ * Time ranges:
+ * - `trivial`: < 5 minutes (simple rename, typo fix)
+ * - `small`: 5-30 minutes (single function, simple feature)
+ * - `medium`: 30 min - 2 hours (multi-file change, moderate complexity)
+ * - `large`: 2+ hours (significant feature, refactoring)
  */
 export const EffortLevelSchema = z.enum([
-  "trivial", // < 5 min
-  "small", // 5-30 min
-  "medium", // 30 min - 2 hours
-  "large", // 2+ hours
+  "trivial",
+  "small",
+  "medium",
+  "large",
 ]);
 export type EffortLevel = z.infer<typeof EffortLevelSchema>;
 
@@ -35,6 +41,7 @@ export const DecomposedSubtaskSchema = z.object({
   description: z.string(),
   files: z.array(z.string()), // File paths this subtask will modify
   estimated_effort: EffortLevelSchema,
+  /** Potential risks or complications (e.g., 'tight coupling', 'data migration required', 'breaking change') */
   risks: z.array(z.string()).optional().default([]),
 });
 export type DecomposedSubtask = z.infer<typeof DecomposedSubtaskSchema>;
@@ -43,8 +50,10 @@ export type DecomposedSubtask = z.infer<typeof DecomposedSubtaskSchema>;
  * Dependency between subtasks
  */
 export const SubtaskDependencySchema = z.object({
-  from: z.number().int().min(0), // Subtask index
-  to: z.number().int().min(0), // Subtask index
+  /** Zero-based index of the dependency source subtask */
+  from: z.number().int().min(0),
+  /** Zero-based index of the dependency target subtask */
+  to: z.number().int().min(0),
   type: DependencyTypeSchema,
 });
 export type SubtaskDependency = z.infer<typeof SubtaskDependencySchema>;
@@ -56,10 +65,15 @@ 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
+  /** Rationale for this decomposition strategy (why these subtasks, why this order) */
+  reasoning: z.string().optional(),
   subtasks: z.array(DecomposedSubtaskSchema).min(1),
   dependencies: z.array(SubtaskDependencySchema).optional().default([]),
-  shared_context: z.string().optional(), // Context to pass to all agents
+  /**
+   * Context shared with all spawned agents.
+   * Examples: API contracts, shared types, project conventions, architectural decisions.
+   */
+  shared_context: z.string().optional(),
 });
 export type TaskDecomposition = z.infer<typeof TaskDecompositionSchema>;
 
@@ -78,11 +92,19 @@ export type DecomposeArgs = z.infer<typeof DecomposeArgsSchema>;
  */
 export const SpawnedAgentSchema = z.object({
   bead_id: z.string(),
-  agent_name: z.string(), // Agent Mail name (e.g., "BlueLake")
+  /**
+   * Agent Mail assigned name (e.g., 'BlueLake', 'CrimsonRiver').
+   * Generated by Agent Mail on session init.
+   */
+  agent_name: z.string(),
   task_id: z.string().optional(), // OpenCode task ID
   status: z.enum(["pending", "running", "completed", "failed"]),
   files: z.array(z.string()), // Reserved files
-  reservation_ids: z.array(z.number()).optional(), // Agent Mail reservation IDs
+  /**
+   * Agent Mail reservation IDs for file locking.
+   * Used to release locks on task completion via agentmail_release.
+   */
+  reservation_ids: z.array(z.number()).optional(),
 });
 export type SpawnedAgent = z.infer<typeof SpawnedAgentSchema>;
 
@@ -101,16 +123,22 @@ export type SwarmSpawnResult = z.infer<typeof SwarmSpawnResultSchema>;
 /**
  * Progress update from an agent
  */
-export const AgentProgressSchema = z.object({
-  bead_id: z.string(),
-  agent_name: z.string(),
-  status: z.enum(["in_progress", "blocked", "completed", "failed"]),
-  progress_percent: z.number().min(0).max(100).optional(),
-  message: z.string().optional(),
-  files_touched: z.array(z.string()).optional(),
-  blockers: z.array(z.string()).optional(),
-  timestamp: z.string().datetime({ offset: true }), // ISO-8601 with timezone
-});
+export const AgentProgressSchema = z
+  .object({
+    bead_id: z.string(),
+    agent_name: z.string(),
+    status: z.enum(["in_progress", "blocked", "completed", "failed"]),
+    progress_percent: z.number().min(0).max(100).optional(),
+    message: z.string().optional(),
+    files_touched: z.array(z.string()).optional(),
+    blockers: z.array(z.string()).optional(),
+    timestamp: z.string().datetime({ offset: true }), // ISO-8601 with timezone
+  })
+  .refine(
+    (data) =>
+      data.status !== "blocked" || (data.blockers && data.blockers.length > 0),
+    { message: "blockers array required when status is 'blocked'" },
+  );
 export type AgentProgress = z.infer<typeof AgentProgressSchema>;
 
 /**