opencode-swarm-plugin 0.44.2 → 0.45.1

package/examples/plugin-wrapper-template.ts

@@ -0,0 +1,2892 @@
+/**
+ * ╔═══════════════════════════════════════════════════════════════════════════╗
+ * ║                                                                           ║
+ * ║   🐝 OPENCODE SWARM PLUGIN WRAPPER 🐝                                     ║
+ * ║                                                                           ║
+ * ║   This file lives at: ~/.config/opencode/plugin/swarm.ts                  ║
+ * ║   Generated by: swarm setup                                               ║
+ * ║                                                                           ║
+ * ╠═══════════════════════════════════════════════════════════════════════════╣
+ * ║                                                                           ║
+ * ║   ⚠️  CRITICAL: THIS FILE MUST BE 100% SELF-CONTAINED  ⚠️                 ║
+ * ║                                                                           ║
+ * ║   ❌ NEVER import from "opencode-swarm-plugin" npm package                ║
+ * ║   ❌ NEVER import from any package with transitive deps (evalite, etc)    ║
+ * ║   ❌ NEVER add dependencies that aren't provided by OpenCode              ║
+ * ║                                                                           ║
+ * ║   ✅ ONLY import from: @opencode-ai/plugin, @opencode-ai/sdk, node:*      ║
+ * ║   ✅ Shell out to `swarm` CLI for all tool execution                      ║
+ * ║   ✅ Inline any logic that would otherwise require imports                ║
+ * ║                                                                           ║
+ * ║   WHY? The npm package has dependencies (evalite, etc) that aren't        ║
+ * ║   available in OpenCode's plugin context. Importing causes:               ║
+ * ║   "Cannot find module 'evalite/runner'" → trace trap → OpenCode crash     ║
+ * ║                                                                           ║
+ * ║   PATTERN: Plugin wrapper is DUMB. CLI is SMART.                          ║
+ * ║   - Wrapper: thin shell, no logic, just bridges to CLI                    ║
+ * ║   - CLI: all the smarts, all the deps, runs in its own context            ║
+ * ║                                                                           ║
+ * ╚═══════════════════════════════════════════════════════════════════════════╝
+ *
+ * Environment variables passed to CLI:
+ * - OPENCODE_SESSION_ID: Session state persistence
+ * - OPENCODE_MESSAGE_ID: Message context
+ * - OPENCODE_AGENT: Agent context
+ * - SWARM_PROJECT_DIR: Project directory (critical for database path)
+ */
+import type { Plugin, PluginInput, Hooks } from "@opencode-ai/plugin";
+import type { ToolPart } from "@opencode-ai/sdk";
+import { tool } from "@opencode-ai/plugin";
+import { spawn } from "child_process";
+import { appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// =============================================================================
+// Swarm Signature Detection (INLINED - do not import from opencode-swarm-plugin)
+// =============================================================================
+
+/**
+ * Subtask lifecycle status derived from events
+ */
+type SubtaskStatus = "created" | "spawned" | "in_progress" | "completed" | "closed";
+
+/**
+ * Subtask state projected from events
+ */
+interface SubtaskState {
+  id: string;
+  title: string;
+  status: SubtaskStatus;
+  files: string[];
+  worker?: string;
+  spawnedAt?: number;
+  completedAt?: number;
+}
+
+/**
+ * Epic state projected from events
+ */
+interface EpicState {
+  id: string;
+  title: string;
+  status: "open" | "in_progress" | "closed";
+  createdAt: number;
+}
+
+/**
+ * Complete swarm state projected from session events
+ */
+interface SwarmProjection {
+  isSwarm: boolean;
+  epic?: EpicState;
+  subtasks: Map<string, SubtaskState>;
+  projectPath?: string;
+  coordinatorName?: string;
+  lastEventAt?: number;
+  counts: {
+    total: number;
+    created: number;
+    spawned: number;
+    inProgress: number;
+    completed: number;
+    closed: number;
+  };
+}
+
+/**
+ * Tool call event extracted from session messages
+ */
+interface ToolCallEvent {
+  tool: string;
+  input: Record<string, unknown>;
+  output: string;
+  timestamp: number;
+}
+
+/** Parse epic ID from hive_create_epic output */
+function parseEpicId(output: string): string | undefined {
+  try {
+    const parsed = JSON.parse(output);
+    return parsed.epic?.id || parsed.id;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Parse subtask IDs from hive_create_epic output */
+function parseSubtaskIds(output: string): string[] {
+  try {
+    const parsed = JSON.parse(output);
+    const subtasks = parsed.subtasks || parsed.epic?.subtasks || [];
+    return subtasks
+      .map((s: unknown) => {
+        if (typeof s === "object" && s !== null && "id" in s) {
+          return (s as { id: string }).id;
+        }
+        return undefined;
+      })
+      .filter((id: unknown): id is string => typeof id === "string");
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Project swarm state from session tool call events
+ */
+function projectSwarmState(events: ToolCallEvent[]): SwarmProjection {
+  const state: SwarmProjection = {
+    isSwarm: false,
+    subtasks: new Map(),
+    counts: { total: 0, created: 0, spawned: 0, inProgress: 0, completed: 0, closed: 0 },
+  };
+
+  let hasEpic = false;
+  let hasSpawn = false;
+
+  for (const event of events) {
+    state.lastEventAt = event.timestamp;
+
+    switch (event.tool) {
+      case "hive_create_epic": {
+        const epicId = parseEpicId(event.output);
+        const epicTitle = typeof event.input.epic_title === "string" ? event.input.epic_title : undefined;
+
+        if (epicId) {
+          state.epic = { id: epicId, title: epicTitle || "Unknown Epic", status: "open", createdAt: event.timestamp };
+          hasEpic = true;
+
+          const subtasks = event.input.subtasks;
+          if (Array.isArray(subtasks)) {
+            for (const subtask of subtasks) {
+              if (typeof subtask === "object" && subtask !== null) {
+                state.counts.created++;
+                state.counts.total++;
+              }
+            }
+          }
+
+          const subtaskIds = parseSubtaskIds(event.output);
+          for (const id of subtaskIds) {
+            if (!state.subtasks.has(id)) {
+              state.subtasks.set(id, { id, title: "Unknown", status: "created", files: [] });
+              state.counts.total++;
+              state.counts.created++;
+            }
+          }
+        }
+        break;
+      }
+
+      case "swarm_spawn_subtask": {
+        const beadId = typeof event.input.bead_id === "string" ? event.input.bead_id : undefined;
+        const title = typeof event.input.subtask_title === "string" ? event.input.subtask_title : "Unknown";
+        const files = Array.isArray(event.input.files) ? (event.input.files as string[]) : [];
+
+        if (beadId) {
+          hasSpawn = true;
+          const existing = state.subtasks.get(beadId);
+          if (existing) {
+            if (existing.status === "created") { state.counts.created--; state.counts.spawned++; }
+            existing.status = "spawned";
+            existing.title = title;
+            existing.files = files;
+            existing.spawnedAt = event.timestamp;
+          } else {
+            state.subtasks.set(beadId, { id: beadId, title, status: "spawned", files, spawnedAt: event.timestamp });
+            state.counts.total++;
+            state.counts.spawned++;
+          }
+
+          const epicId = typeof event.input.epic_id === "string" ? event.input.epic_id : undefined;
+          if (epicId && !state.epic) {
+            state.epic = { id: epicId, title: "Unknown Epic", status: "in_progress", createdAt: event.timestamp };
+          }
+        }
+        break;
+      }
+
+      case "hive_start": {
+        const id = typeof event.input.id === "string" ? event.input.id : undefined;
+        if (id) {
+          const subtask = state.subtasks.get(id);
+          if (subtask && subtask.status !== "completed" && subtask.status !== "closed") {
+            if (subtask.status === "created") state.counts.created--;
+            else if (subtask.status === "spawned") state.counts.spawned--;
+            subtask.status = "in_progress";
+            state.counts.inProgress++;
+          }
+          if (state.epic && state.epic.id === id) state.epic.status = "in_progress";
+        }
+        break;
+      }
+
+      case "swarm_complete": {
+        const beadId = typeof event.input.bead_id === "string" ? event.input.bead_id : undefined;
+        if (beadId) {
+          const subtask = state.subtasks.get(beadId);
+          if (subtask && subtask.status !== "closed") {
+            if (subtask.status === "created") state.counts.created--;
+            else if (subtask.status === "spawned") state.counts.spawned--;
+            else if (subtask.status === "in_progress") state.counts.inProgress--;
+            subtask.status = "completed";
+            subtask.completedAt = event.timestamp;
+            state.counts.completed++;
+          }
+        }
+        break;
+      }
+
+      case "hive_close": {
+        const id = typeof event.input.id === "string" ? event.input.id : undefined;
+        if (id) {
+          const subtask = state.subtasks.get(id);
+          if (subtask) {
+            if (subtask.status === "created") state.counts.created--;
+            else if (subtask.status === "spawned") state.counts.spawned--;
+            else if (subtask.status === "in_progress") state.counts.inProgress--;
+            else if (subtask.status === "completed") state.counts.completed--;
+            subtask.status = "closed";
+            state.counts.closed++;
+          }
+          if (state.epic && state.epic.id === id) state.epic.status = "closed";
+        }
+        break;
+      }
+
+      case "swarmmail_init": {
+        try {
+          const parsed = JSON.parse(event.output);
+          if (parsed.agent_name) state.coordinatorName = parsed.agent_name;
+          if (parsed.project_key) state.projectPath = parsed.project_key;
+        } catch { /* skip */ }
+        break;
+      }
+    }
+  }
+
+  state.isSwarm = hasEpic && hasSpawn;
+  return state;
+}
+
+/** Quick check for swarm signature without full projection */
+function hasSwarmSignature(events: ToolCallEvent[]): boolean {
+  let hasEpic = false;
+  let hasSpawn = false;
+  for (const event of events) {
+    if (event.tool === "hive_create_epic") hasEpic = true;
+    else if (event.tool === "swarm_spawn_subtask") hasSpawn = true;
+    if (hasEpic && hasSpawn) return true;
+  }
+  return false;
+}
+
+/** Check if swarm is still active (has pending work) */
+function isSwarmActive(projection: SwarmProjection): boolean {
+  if (!projection.isSwarm) return false;
+  return projection.counts.created > 0 || projection.counts.spawned > 0 ||
+         projection.counts.inProgress > 0 || projection.counts.completed > 0;
+}
+
+/** Get human-readable swarm status summary */
+function getSwarmSummary(projection: SwarmProjection): string {
+  if (!projection.isSwarm) return "No swarm detected";
+  const { counts, epic } = projection;
+  const parts: string[] = [];
+  if (epic) parts.push(`Epic: ${epic.id} - ${epic.title} [${epic.status}]`);
+  parts.push(`Subtasks: ${counts.total} total (${counts.spawned} spawned, ${counts.inProgress} in_progress, ${counts.completed} completed, ${counts.closed} closed)`);
+  parts.push(isSwarmActive(projection) ? "Status: ACTIVE - has pending work" : "Status: COMPLETE - all work closed");
+  return parts.join("\n");
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const SWARM_CLI = "swarm";
+
+// =============================================================================
+// File-based Logging (writes to ~/.config/swarm-tools/logs/)
+// =============================================================================
+
+const LOG_DIR = join(homedir(), ".config", "swarm-tools", "logs");
+const COMPACTION_LOG = join(LOG_DIR, "compaction.log");
+
+/**
+ * Ensure log directory exists
+ */
+function ensureLogDir(): void {
+  if (!existsSync(LOG_DIR)) {
+    mkdirSync(LOG_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Log a compaction event to file (JSON lines format, compatible with `swarm log`)
+ * 
+ * @param level - Log level (info, debug, warn, error)
+ * @param msg - Log message
+ * @param data - Additional structured data
+ */
+function logCompaction(
+  level: "info" | "debug" | "warn" | "error",
+  msg: string,
+  data?: Record<string, unknown>,
+): void {
+  try {
+    ensureLogDir();
+    const entry = JSON.stringify({
+      time: new Date().toISOString(),
+      level,
+      msg,
+      ...data,
+    });
+    appendFileSync(COMPACTION_LOG, entry + "\n");
+  } catch {
+    // Silently fail - logging should never break the plugin
+  }
+}
+
+/**
+ * Capture compaction event for evals via CLI
+ * 
+ * Shells out to `swarm capture` command to avoid import issues.
+ * The CLI handles all the logic - plugin wrapper stays dumb.
+ * 
+ * @param sessionID - Session ID
+ * @param epicID - Epic ID (or "unknown" if not detected)
+ * @param compactionType - Event type (detection_complete, prompt_generated, context_injected)
+ * @param payload - Event-specific data (full prompts, detection results, etc.)
+ */
+async function captureCompaction(
+  sessionID: string,
+  epicID: string,
+  compactionType: "detection_complete" | "prompt_generated" | "context_injected",
+  payload: any,
+): Promise<void> {
+  try {
+    // Shell out to CLI - no imports needed, version always matches
+    const args = [
+      "capture",
+      "--session", sessionID,
+      "--epic", epicID,
+      "--type", compactionType,
+      "--payload", JSON.stringify(payload),
+    ];
+    
+    const proc = spawn(SWARM_CLI, args, {
+      env: { ...process.env, SWARM_PROJECT_DIR: projectDirectory },
+      stdio: ["ignore", "ignore", "ignore"], // Fire and forget
+    });
+    
+    // Don't wait - capture is non-blocking
+    proc.unref();
+  } catch (err) {
+    // Non-fatal - capture failures shouldn't break compaction
+    logCompaction("warn", "compaction_capture_failed", {
+      session_id: sessionID,
+      compaction_type: compactionType,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+// Module-level project directory - set during plugin initialization
+// This is CRITICAL: without it, the CLI uses process.cwd() which may be wrong
+let projectDirectory: string = process.cwd();
+
+// Module-level SDK client - set during plugin initialization
+// Used for scanning session messages during compaction
+let sdkClient: any = null;
+
+// =============================================================================
+// CLI Execution Helper
+// =============================================================================
+
+/**
+ * Execute a swarm tool via CLI
+ *
+ * Spawns `swarm tool <name> --json '<args>'` and returns the result.
+ * Passes session context via environment variables.
+ * 
+ * IMPORTANT: Runs in projectDirectory (set by OpenCode) not process.cwd()
+ */
+async function execTool(
+  name: string,
+  args: Record<string, unknown>,
+  ctx: { sessionID: string; messageID: string; agent: string },
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const hasArgs = Object.keys(args).length > 0;
+    const cliArgs = hasArgs
+      ? ["tool", name, "--json", JSON.stringify(args)]
+      : ["tool", name];
+
+    const proc = spawn(SWARM_CLI, cliArgs, {
+      cwd: projectDirectory, // Run in project directory, not plugin directory
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        OPENCODE_SESSION_ID: ctx.sessionID,
+        OPENCODE_MESSAGE_ID: ctx.messageID,
+        OPENCODE_AGENT: ctx.agent,
+        SWARM_PROJECT_DIR: projectDirectory, // Also pass as env var
+      },
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data) => {
+      stdout += data;
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data;
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        // Success - return the JSON output
+        try {
+          const result = JSON.parse(stdout);
+          if (result.success && result.data !== undefined) {
+            // Unwrap the data for cleaner tool output
+            resolve(
+              typeof result.data === "string"
+                ? result.data
+                : JSON.stringify(result.data, null, 2),
+            );
+          } else if (!result.success && result.error) {
+            // Tool returned an error in JSON format
+            // Handle both string errors and object errors with .message
+            const errorMsg = typeof result.error === "string" 
+              ? result.error 
+              : (result.error.message || "Tool execution failed");
+            reject(new Error(errorMsg));
+          } else {
+            resolve(stdout);
+          }
+        } catch {
+          resolve(stdout);
+        }
+      } else if (code === 2) {
+        reject(new Error(`Unknown tool: ${name}`));
+      } else if (code === 3) {
+        reject(new Error(`Invalid JSON args: ${stderr}`));
+      } else {
+        // Tool returned error
+        try {
+          const result = JSON.parse(stdout);
+          if (!result.success && result.error) {
+            // Handle both string errors and object errors with .message
+            const errorMsg = typeof result.error === "string"
+              ? result.error
+              : (result.error.message || `Tool failed with code ${code}`);
+            reject(new Error(errorMsg));
+          } else {
+            reject(
+              new Error(stderr || stdout || `Tool failed with code ${code}`),
+            );
+          }
+        } catch {
+          reject(
+            new Error(stderr || stdout || `Tool failed with code ${code}`),
+          );
+        }
+      }
+    });
+
+    proc.on("error", (err) => {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        reject(
+          new Error(
+            `swarm CLI not found. Install with: npm install -g opencode-swarm-plugin`,
+          ),
+        );
+      } else {
+        reject(err);
+      }
+    });
+  });
+}
+
+// =============================================================================
+// Beads Tools
+// =============================================================================
+
+const hive_create = tool({
+  description: "Create a new bead with type-safe validation",
+  args: {
+    title: tool.schema.string().describe("Bead title"),
+    type: tool.schema
+      .enum(["bug", "feature", "task", "epic", "chore"])
+      .optional()
+      .describe("Issue type (default: task)"),
+    priority: tool.schema
+      .number()
+      .min(0)
+      .max(3)
+      .optional()
+      .describe("Priority 0-3 (default: 2)"),
+    description: tool.schema.string().optional().describe("Bead description"),
+    parent_id: tool.schema
+      .string()
+      .optional()
+      .describe("Parent bead ID for epic children"),
+  },
+  execute: (args, ctx) => execTool("hive_create", args, ctx),
+});
+
+const hive_create_epic = tool({
+  description: "Create epic with subtasks in one atomic operation",
+  args: {
+    epic_title: tool.schema.string().describe("Epic title"),
+    epic_description: tool.schema
+      .string()
+      .optional()
+      .describe("Epic description"),
+    subtasks: tool.schema
+      .array(
+        tool.schema.object({
+          title: tool.schema.string(),
+          priority: tool.schema.number().min(0).max(3).optional(),
+          files: tool.schema.array(tool.schema.string()).optional(),
+        }),
+      )
+      .describe("Subtasks to create under the epic"),
+  },
+  execute: (args, ctx) => execTool("hive_create_epic", args, ctx),
+});
+
+const hive_query = tool({
+  description: "Query beads with filters (replaces bd list, bd ready, bd wip)",
+  args: {
+    status: tool.schema
+      .enum(["open", "in_progress", "blocked", "closed"])
+      .optional()
+      .describe("Filter by status"),
+    type: tool.schema
+      .enum(["bug", "feature", "task", "epic", "chore"])
+      .optional()
+      .describe("Filter by type"),
+    ready: tool.schema
+      .boolean()
+      .optional()
+      .describe("Only show unblocked beads"),
+    limit: tool.schema
+      .number()
+      .optional()
+      .describe("Max results (default: 20)"),
+  },
+  execute: (args, ctx) => execTool("hive_query", args, ctx),
+});
+
+const hive_update = tool({
+  description: "Update bead status/description",
+  args: {
+    id: tool.schema.string().describe("Cell ID"),
+    status: tool.schema
+      .enum(["open", "in_progress", "blocked", "closed"])
+      .optional()
+      .describe("New status"),
+    description: tool.schema.string().optional().describe("New description"),
+    priority: tool.schema
+      .number()
+      .min(0)
+      .max(3)
+      .optional()
+      .describe("New priority"),
+  },
+  execute: (args, ctx) => execTool("hive_update", args, ctx),
+});
+
+const hive_close = tool({
+  description: "Close a bead with reason",
+  args: {
+    id: tool.schema.string().describe("Cell ID"),
+    reason: tool.schema.string().describe("Completion reason"),
+  },
+  execute: (args, ctx) => execTool("hive_close", args, ctx),
+});
+
+const hive_start = tool({
+  description: "Mark a bead as in-progress",
+  args: {
+    id: tool.schema.string().describe("Cell ID"),
+  },
+  execute: (args, ctx) => execTool("hive_start", args, ctx),
+});
+
+const hive_ready = tool({
+  description: "Get the next ready bead (unblocked, highest priority)",
+  args: {},
+  execute: (args, ctx) => execTool("hive_ready", args, ctx),
+});
+
+const hive_sync = tool({
+  description: "Sync beads to git and push (MANDATORY at session end)",
+  args: {
+    auto_pull: tool.schema.boolean().optional().describe("Pull before sync"),
+  },
+  execute: (args, ctx) => execTool("hive_sync", args, ctx),
+});
+
+const hive_cells = tool({
+  description: `Query cells from the hive database with flexible filtering.
+
+USE THIS TOOL TO:
+- List all open cells: hive_cells()
+- Find cells by status: hive_cells({ status: "in_progress" })
+- Find cells by type: hive_cells({ type: "bug" })
+- Get a specific cell by partial ID: hive_cells({ id: "mjkmd" })
+- Get the next ready (unblocked) cell: hive_cells({ ready: true })
+- Combine filters: hive_cells({ status: "open", type: "task" })
+
+RETURNS: Array of cells with id, title, status, priority, type, parent_id, created_at, updated_at
+
+PREFER THIS OVER hive_query when you need to:
+- See what work is available
+- Check status of multiple cells
+- Find cells matching criteria
+- Look up a cell by partial ID`,
+  args: {
+    id: tool.schema.string().optional().describe("Partial or full cell ID to look up"),
+    status: tool.schema.enum(["open", "in_progress", "blocked", "closed"]).optional().describe("Filter by status"),
+    type: tool.schema.enum(["task", "bug", "feature", "epic", "chore"]).optional().describe("Filter by type"),
+    ready: tool.schema.boolean().optional().describe("If true, return only the next unblocked cell"),
+    limit: tool.schema.number().optional().describe("Max cells to return (default 20)"),
+  },
+  execute: (args, ctx) => execTool("hive_cells", args, ctx),
+});
+
+const beads_link_thread = tool({
+  description: "Add metadata linking bead to Agent Mail thread",
+  args: {
+    bead_id: tool.schema.string().describe("Cell ID"),
+    thread_id: tool.schema.string().describe("Agent Mail thread ID"),
+  },
+  execute: (args, ctx) => execTool("beads_link_thread", args, ctx),
+});
+
+// =============================================================================
+// Swarm Mail Tools (Embedded)
+// =============================================================================
+
+const swarmmail_init = tool({
+  description: "Initialize Swarm Mail session (REQUIRED FIRST)",
+  args: {
+    project_path: tool.schema.string().describe("Absolute path to the project"),
+    agent_name: tool.schema.string().optional().describe("Custom agent name"),
+    task_description: tool.schema
+      .string()
+      .optional()
+      .describe("Task description"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_init", args, ctx),
+});
+
+const swarmmail_send = tool({
+  description: "Send message to other agents via Swarm Mail",
+  args: {
+    to: tool.schema
+      .array(tool.schema.string())
+      .describe("Recipient agent names"),
+    subject: tool.schema.string().describe("Message subject"),
+    body: tool.schema.string().describe("Message body"),
+    thread_id: tool.schema
+      .string()
+      .optional()
+      .describe("Thread ID for grouping"),
+    importance: tool.schema
+      .enum(["low", "normal", "high", "urgent"])
+      .optional()
+      .describe("Message importance"),
+    ack_required: tool.schema
+      .boolean()
+      .optional()
+      .describe("Require acknowledgment"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_send", args, ctx),
+});
+
+const swarmmail_inbox = tool({
+  description: "Fetch inbox (CONTEXT-SAFE: bodies excluded, max 5 messages)",
+  args: {
+    limit: tool.schema
+      .number()
+      .max(5)
+      .optional()
+      .describe("Max messages (max 5)"),
+    urgent_only: tool.schema
+      .boolean()
+      .optional()
+      .describe("Only urgent messages"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_inbox", args, ctx),
+});
+
+const swarmmail_read_message = tool({
+  description: "Fetch ONE message body by ID",
+  args: {
+    message_id: tool.schema.number().describe("Message ID"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_read_message", args, ctx),
+});
+
+const swarmmail_reserve = tool({
+  description: "Reserve file paths for exclusive editing",
+  args: {
+    paths: tool.schema
+      .array(tool.schema.string())
+      .describe("File paths/patterns"),
+    ttl_seconds: tool.schema.number().optional().describe("Reservation TTL"),
+    exclusive: tool.schema.boolean().optional().describe("Exclusive lock"),
+    reason: tool.schema.string().optional().describe("Reservation reason"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_reserve", args, ctx),
+});
+
+const swarmmail_release = tool({
+  description: "Release file reservations",
+  args: {
+    paths: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Paths to release"),
+    reservation_ids: tool.schema
+      .array(tool.schema.number())
+      .optional()
+      .describe("Reservation IDs"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_release", args, ctx),
+});
+
+const swarmmail_ack = tool({
+  description: "Acknowledge a message",
+  args: {
+    message_id: tool.schema.number().describe("Message ID"),
+  },
+  execute: (args, ctx) => execTool("swarmmail_ack", args, ctx),
+});
+
+const swarmmail_health = tool({
+  description: "Check Swarm Mail database health",
+  args: {},
+  execute: (args, ctx) => execTool("swarmmail_health", args, ctx),
+});
+
+// =============================================================================
+// Structured Tools
+// =============================================================================
+
+const structured_extract_json = tool({
+  description: "Extract JSON from markdown/text response",
+  args: {
+    text: tool.schema.string().describe("Text containing JSON"),
+  },
+  execute: (args, ctx) => execTool("structured_extract_json", args, ctx),
+});
+
+const structured_validate = tool({
+  description: "Validate agent response against a schema",
+  args: {
+    response: tool.schema.string().describe("Agent response to validate"),
+    schema_name: tool.schema
+      .enum(["evaluation", "task_decomposition", "cell_tree"])
+      .describe("Schema to validate against"),
+    max_retries: tool.schema
+      .number()
+      .min(1)
+      .max(5)
+      .optional()
+      .describe("Max retries"),
+  },
+  execute: (args, ctx) => execTool("structured_validate", args, ctx),
+});
+
+const structured_parse_evaluation = tool({
+  description: "Parse and validate evaluation response",
+  args: {
+    response: tool.schema.string().describe("Agent response"),
+  },
+  execute: (args, ctx) => execTool("structured_parse_evaluation", args, ctx),
+});
+
+const structured_parse_decomposition = tool({
+  description: "Parse and validate task decomposition response",
+  args: {
+    response: tool.schema.string().describe("Agent response"),
+  },
+  execute: (args, ctx) => execTool("structured_parse_decomposition", args, ctx),
+});
+
+const structured_parse_cell_tree = tool({
+  description: "Parse and validate bead tree response",
+  args: {
+    response: tool.schema.string().describe("Agent response"),
+  },
+  execute: (args, ctx) => execTool("structured_parse_cell_tree", args, ctx),
+});
+
+// =============================================================================
+// Swarm Tools
+// =============================================================================
+
+const swarm_init = tool({
+  description: "Initialize swarm session and check tool availability",
+  args: {
+    project_path: tool.schema.string().optional().describe("Project path"),
+    isolation: tool.schema
+      .enum(["worktree", "reservation"])
+      .optional()
+      .describe(
+        "Isolation mode: 'worktree' for git worktree isolation, 'reservation' for file reservations (default)",
+      ),
+  },
+  execute: (args, ctx) => execTool("swarm_init", args, ctx),
+});
+
+const swarm_select_strategy = tool({
+  description: "Analyze task and recommend decomposition strategy",
+  args: {
+    task: tool.schema.string().min(1).describe("Task to analyze"),
+    codebase_context: tool.schema
+      .string()
+      .optional()
+      .describe("Codebase context"),
+  },
+  execute: (args, ctx) => execTool("swarm_select_strategy", args, ctx),
+});
+
+const swarm_plan_prompt = tool({
+  description: "Generate strategy-specific decomposition prompt",
+  args: {
+    task: tool.schema.string().min(1).describe("Task to decompose"),
+    strategy: tool.schema
+      .enum(["file-based", "feature-based", "risk-based", "auto"])
+      .optional()
+      .describe("Decomposition strategy"),
+    max_subtasks: tool.schema
+      .number()
+      .int()
+      .min(2)
+      .max(10)
+      .optional()
+      .describe("Max subtasks"),
+    context: tool.schema.string().optional().describe("Additional context"),
+    query_cass: tool.schema
+      .boolean()
+      .optional()
+      .describe("Query CASS for similar tasks"),
+    cass_limit: tool.schema
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe("CASS limit"),
+  },
+  execute: (args, ctx) => execTool("swarm_plan_prompt", args, ctx),
+});
+
+const swarm_decompose = tool({
+  description: "Generate decomposition prompt for breaking task into subtasks",
+  args: {
+    task: tool.schema.string().min(1).describe("Task to decompose"),
+    max_subtasks: tool.schema
+      .number()
+      .int()
+      .min(2)
+      .max(10)
+      .optional()
+      .describe("Max subtasks"),
+    context: tool.schema.string().optional().describe("Additional context"),
+    query_cass: tool.schema.boolean().optional().describe("Query CASS"),
+    cass_limit: tool.schema
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe("CASS limit"),
+  },
+  execute: (args, ctx) => execTool("swarm_decompose", args, ctx),
+});
+
+const swarm_validate_decomposition = tool({
+  description: "Validate a decomposition response against CellTreeSchema",
+  args: {
+    response: tool.schema.string().describe("Decomposition response"),
+  },
+  execute: (args, ctx) => execTool("swarm_validate_decomposition", args, ctx),
+});
+
+const swarm_status = tool({
+  description: "Get status of a swarm by epic ID",
+  args: {
+    epic_id: tool.schema.string().describe("Epic bead ID"),
+    project_key: tool.schema.string().describe("Project key"),
+  },
+  execute: (args, ctx) => execTool("swarm_status", args, ctx),
+});
+
+const swarm_progress = tool({
+  description: "Report progress on a subtask to coordinator",
+  args: {
+    project_key: tool.schema.string().describe("Project key"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Cell ID"),
+    status: tool.schema
+      .enum(["in_progress", "blocked", "completed", "failed"])
+      .describe("Status"),
+    message: tool.schema.string().optional().describe("Progress message"),
+    progress_percent: tool.schema
+      .number()
+      .min(0)
+      .max(100)
+      .optional()
+      .describe("Progress %"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+  },
+  execute: (args, ctx) => execTool("swarm_progress", args, ctx),
+});
+
+const swarm_complete = tool({
+  description:
+    "Mark subtask complete with Verification Gate. Runs UBS scan, typecheck, and tests before allowing completion.",
+  args: {
+    project_key: tool.schema.string().describe("Project key"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Cell ID"),
+    summary: tool.schema.string().describe("Completion summary"),
+    evaluation: tool.schema.string().optional().describe("Self-evaluation JSON"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified - will be verified"),
+    skip_ubs_scan: tool.schema.boolean().optional().describe("Skip UBS scan"),
+    skip_verification: tool.schema
+      .boolean()
+      .optional()
+      .describe("Skip ALL verification (UBS, typecheck, tests)"),
+    skip_review: tool.schema
+      .boolean()
+      .optional()
+      .describe("Skip review gate check"),
+  },
+  execute: (args, ctx) => execTool("swarm_complete", args, ctx),
+});
+
+const swarm_record_outcome = tool({
+  description: "Record subtask outcome for implicit feedback scoring",
+  args: {
+    bead_id: tool.schema.string().describe("Cell ID"),
+    duration_ms: tool.schema.number().int().min(0).describe("Duration in ms"),
+    error_count: tool.schema
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Error count"),
+    retry_count: tool.schema
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Retry count"),
+    success: tool.schema.boolean().describe("Whether task succeeded"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+    criteria: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Evaluation criteria"),
+    strategy: tool.schema
+      .enum(["file-based", "feature-based", "risk-based"])
+      .optional()
+      .describe("Strategy used"),
+  },
+  execute: (args, ctx) => execTool("swarm_record_outcome", args, ctx),
+});
+
+const swarm_subtask_prompt = tool({
+  description: "Generate the prompt for a spawned subtask agent",
+  args: {
+    agent_name: tool.schema.string().describe("Agent name"),
+    bead_id: tool.schema.string().describe("Cell ID"),
+    epic_id: tool.schema.string().describe("Epic ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    subtask_description: tool.schema
+      .string()
+      .optional()
+      .describe("Description"),
+    files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+    shared_context: tool.schema.string().optional().describe("Shared context"),
+  },
+  execute: (args, ctx) => execTool("swarm_subtask_prompt", args, ctx),
+});
+
+const swarm_spawn_subtask = tool({
+  description: "Prepare a subtask for spawning with Task tool",
+  args: {
+    bead_id: tool.schema.string().describe("Cell ID"),
+    epic_id: tool.schema.string().describe("Epic ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    subtask_description: tool.schema
+      .string()
+      .optional()
+      .describe("Description"),
+    files: tool.schema.array(tool.schema.string()).describe("Files to work on"),
+    shared_context: tool.schema.string().optional().describe("Shared context"),
+  },
+  execute: (args, ctx) => execTool("swarm_spawn_subtask", args, ctx),
+});
+
+const swarm_complete_subtask = tool({
+  description: "Handle subtask completion after Task agent returns",
+  args: {
+    bead_id: tool.schema.string().describe("Cell ID"),
+    task_result: tool.schema.string().describe("Task result JSON"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified"),
+  },
+  execute: (args, ctx) => execTool("swarm_complete_subtask", args, ctx),
+});
+
+const swarm_evaluation_prompt = tool({
+  description: "Generate self-evaluation prompt for a completed subtask",
+  args: {
+    bead_id: tool.schema.string().describe("Cell ID"),
+    subtask_title: tool.schema.string().describe("Subtask title"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .describe("Files modified"),
+  },
+  execute: (args, ctx) => execTool("swarm_evaluation_prompt", args, ctx),
+});
+
+const swarm_broadcast = tool({
+  description:
+    "Broadcast context update to all agents working on the same epic",
+  args: {
+    project_path: tool.schema.string().describe("Project path"),
+    agent_name: tool.schema.string().describe("Agent name"),
+    epic_id: tool.schema.string().describe("Epic ID"),
+    message: tool.schema.string().describe("Context update message"),
+    importance: tool.schema
+      .enum(["info", "warning", "blocker"])
+      .optional()
+      .describe("Priority level (default: info)"),
+    files_affected: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files this context relates to"),
+  },
+  execute: (args, ctx) => execTool("swarm_broadcast", args, ctx),
+});
+
+// =============================================================================
+// Worktree Isolation Tools
+// =============================================================================
+
+const swarm_worktree_create = tool({
+  description:
+    "Create a git worktree for isolated task execution. Worker operates in worktree, not main branch.",
+  args: {
+    project_path: tool.schema.string().describe("Absolute path to project root"),
+    task_id: tool.schema.string().describe("Task/bead ID (e.g., bd-abc123.1)"),
+    start_commit: tool.schema
+      .string()
+      .describe("Commit SHA to create worktree at (swarm start point)"),
+  },
+  execute: (args, ctx) => execTool("swarm_worktree_create", args, ctx),
+});
+
+const swarm_worktree_merge = tool({
+  description:
+    "Cherry-pick commits from worktree back to main branch. Call after worker completes.",
+  args: {
+    project_path: tool.schema.string().describe("Absolute path to project root"),
+    task_id: tool.schema.string().describe("Task/bead ID"),
+    start_commit: tool.schema
+      .string()
+      .optional()
+      .describe("Original start commit (to find new commits)"),
+  },
+  execute: (args, ctx) => execTool("swarm_worktree_merge", args, ctx),
+});
+
+const swarm_worktree_cleanup = tool({
+  description:
+    "Remove a worktree after completion or abort. Idempotent - safe to call multiple times.",
+  args: {
+    project_path: tool.schema.string().describe("Absolute path to project root"),
+    task_id: tool.schema.string().optional().describe("Task/bead ID to clean up"),
+    cleanup_all: tool.schema
+      .boolean()
+      .optional()
+      .describe("Remove all worktrees for this project"),
+  },
+  execute: (args, ctx) => execTool("swarm_worktree_cleanup", args, ctx),
+});
+
+const swarm_worktree_list = tool({
+  description: "List all active worktrees for a project",
+  args: {
+    project_path: tool.schema.string().describe("Absolute path to project root"),
+  },
+  execute: (args, ctx) => execTool("swarm_worktree_list", args, ctx),
+});
+
+// =============================================================================
+// Structured Review Tools
+// =============================================================================
+
+const swarm_review = tool({
+  description:
+    "Generate a review prompt for a completed subtask. Includes epic context, dependencies, and diff.",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    epic_id: tool.schema.string().describe("Epic bead ID"),
+    task_id: tool.schema.string().describe("Subtask bead ID to review"),
+    files_touched: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Files modified (will get diff for these)"),
+  },
+  execute: (args, ctx) => execTool("swarm_review", args, ctx),
+});
+
+const swarm_review_feedback = tool({
+  description:
+    "Send review feedback to a worker. Tracks attempts (max 3). Fails task after 3 rejections.",
+  args: {
+    project_key: tool.schema.string().describe("Project path"),
+    task_id: tool.schema.string().describe("Subtask bead ID"),
+    worker_id: tool.schema.string().describe("Worker agent name"),
+    status: tool.schema
+      .enum(["approved", "needs_changes"])
+      .describe("Review status"),
+    summary: tool.schema.string().optional().describe("Review summary"),
+    issues: tool.schema
+      .string()
+      .optional()
+      .describe("JSON array of ReviewIssue objects (for needs_changes)"),
+  },
+  execute: (args, ctx) => execTool("swarm_review_feedback", args, ctx),
+});
+
+// =============================================================================
+// Skills Tools
+// =============================================================================
+
+const skills_list = tool({
+  description:
+    "List all available skills from global, project, and bundled sources",
+  args: {
+    source: tool.schema
+      .enum(["all", "global", "project", "bundled"])
+      .optional()
+      .describe("Filter by source (default: all)"),
+  },
+  execute: (args, ctx) => execTool("skills_list", args, ctx),
+});
+
+const skills_read = tool({
+  description: "Read a skill's full content including SKILL.md and references",
+  args: {
+    name: tool.schema.string().describe("Skill name"),
+  },
+  execute: (args, ctx) => execTool("skills_read", args, ctx),
+});
+
+const skills_use = tool({
+  description:
+    "Get skill content formatted for injection into agent context. Use this when you need to apply a skill's knowledge to the current task.",
+  args: {
+    name: tool.schema.string().describe("Skill name"),
+    context: tool.schema
+      .string()
+      .optional()
+      .describe("Optional context about how the skill will be used"),
+  },
+  execute: (args, ctx) => execTool("skills_use", args, ctx),
+});
+
+const skills_create = tool({
+  description: "Create a new skill with SKILL.md template",
+  args: {
+    name: tool.schema.string().describe("Skill name (kebab-case)"),
+    description: tool.schema.string().describe("Brief skill description"),
+    scope: tool.schema
+      .enum(["global", "project"])
+      .optional()
+      .describe("Where to create (default: project)"),
+    tags: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Skill tags for discovery"),
+  },
+  execute: (args, ctx) => execTool("skills_create", args, ctx),
+});
+
+const skills_update = tool({
+  description: "Update an existing skill's SKILL.md content",
+  args: {
+    name: tool.schema.string().describe("Skill name"),
+    content: tool.schema.string().describe("New SKILL.md content"),
+  },
+  execute: (args, ctx) => execTool("skills_update", args, ctx),
+});
+
+const skills_delete = tool({
+  description: "Delete a skill (project skills only)",
+  args: {
+    name: tool.schema.string().describe("Skill name"),
+  },
+  execute: (args, ctx) => execTool("skills_delete", args, ctx),
+});
+
+const skills_init = tool({
+  description: "Initialize skills directory in current project",
+  args: {
+    path: tool.schema
+      .string()
+      .optional()
+      .describe("Custom path (default: .opencode/skills)"),
+  },
+  execute: (args, ctx) => execTool("skills_init", args, ctx),
+});
+
+const skills_add_script = tool({
+  description: "Add an executable script to a skill",
+  args: {
+    skill_name: tool.schema.string().describe("Skill name"),
+    script_name: tool.schema.string().describe("Script filename"),
+    content: tool.schema.string().describe("Script content"),
+    executable: tool.schema
+      .boolean()
+      .optional()
+      .describe("Make executable (default: true)"),
+  },
+  execute: (args, ctx) => execTool("skills_add_script", args, ctx),
+});
+
+const skills_execute = tool({
+  description: "Execute a skill's script",
+  args: {
+    skill_name: tool.schema.string().describe("Skill name"),
+    script_name: tool.schema.string().describe("Script to execute"),
+    args: tool.schema
+      .array(tool.schema.string())
+      .optional()
+      .describe("Script arguments"),
+  },
+  execute: (args, ctx) => execTool("skills_execute", args, ctx),
+});
+
+// =============================================================================
+// Swarm Insights Tools
+// =============================================================================
+
+const swarm_get_strategy_insights = tool({
+  description: "Get strategy success rates for decomposition planning. Use this when planning task decomposition to see which strategies (file-based, feature-based, risk-based) have historically succeeded or failed. Returns success rates and recommendations based on past swarm outcomes.",
+  args: {
+    task: tool.schema.string().describe("Task description to analyze for strategy recommendation"),
+  },
+  execute: (args, ctx) => execTool("swarm_get_strategy_insights", args, ctx),
+});
+
+const swarm_get_file_insights = tool({
+  description: "Get file-specific gotchas for worker context. Use this when assigning files to workers to warn them about historical failure patterns. Queries past outcomes and semantic memory for file-specific learnings (edge cases, common bugs, performance traps).",
+  args: {
+    files: tool.schema.array(tool.schema.string()).describe("File paths to get insights for"),
+  },
+  execute: (args, ctx) => execTool("swarm_get_file_insights", args, ctx),
+});
+
+const swarm_get_pattern_insights = tool({
+  description: "Get common failure patterns across swarms. Use this during planning or when debugging stuck swarms to see recurring anti-patterns (type errors, timeouts, conflicts, test failures). Returns top 5 most frequent failure patterns with recommendations.",
+  args: {},
+  execute: (args, ctx) => execTool("swarm_get_pattern_insights", args, ctx),
+});
+
+// =============================================================================
+// CASS Tools (Cross-Agent Session Search)
+// =============================================================================
+
+const cass_search = tool({
+  description: "Search across all AI coding agent histories (Claude, Codex, Cursor, Gemini, Aider, ChatGPT, Cline, OpenCode, Amp, Pi-Agent). Query BEFORE solving problems from scratch - another agent may have already solved it. Returns matching sessions ranked by relevance.",
+  args: {
+    query: tool.schema.string().describe("Search query (e.g., 'authentication error Next.js')"),
+    agent: tool.schema
+      .string()
+      .optional()
+      .describe("Filter by agent name (e.g., 'claude', 'cursor')"),
+    days: tool.schema
+      .number()
+      .optional()
+      .describe("Only search sessions from last N days"),
+    limit: tool.schema
+      .number()
+      .optional()
+      .describe("Max results to return (default: 5)"),
+    fields: tool.schema
+      .string()
+      .optional()
+      .describe("Field selection: 'minimal' for compact output (path, line, agent only)"),
+  },
+  execute: (args, ctx) => execTool("cass_search", args, ctx),
+});
+
+const cass_view = tool({
+  description: "View a specific conversation/session from search results. Use source_path from cass_search output.",
+  args: {
+    path: tool.schema
+      .string()
+      .describe("Path to session file (from cass_search results)"),
+    line: tool.schema
+      .number()
+      .optional()
+      .describe("Jump to specific line number"),
+  },
+  execute: (args, ctx) => execTool("cass_view", args, ctx),
+});
+
+const cass_expand = tool({
+  description: "Expand context around a specific line in a session. Shows messages before/after.",
+  args: {
+    path: tool.schema
+      .string()
+      .describe("Path to session file"),
+    line: tool.schema
+      .number()
+      .describe("Line number to expand around"),
+    context: tool.schema
+      .number()
+      .optional()
+      .describe("Number of lines before/after to show (default: 5)"),
+  },
+  execute: (args, ctx) => execTool("cass_expand", args, ctx),
+});
+
+const cass_health = tool({
+  description: "Check if cass index is healthy. Exit 0 = ready, Exit 1 = needs indexing. Run this before searching.",
+  args: {},
+  execute: (args, ctx) => execTool("cass_health", args, ctx),
+});
+
+const cass_index = tool({
+  description: "Build or rebuild the search index. Run this if health check fails or to pick up new sessions.",
+  args: {
+    full: tool.schema
+      .boolean()
+      .optional()
+      .describe("Force full rebuild (default: incremental)"),
+  },
+  execute: (args, ctx) => execTool("cass_index", args, ctx),
+});
+
+const cass_stats = tool({
+  description: "Show index statistics - how many sessions, messages, agents indexed.",
+  args: {},
+  execute: (args, ctx) => execTool("cass_stats", args, ctx),
+});
+
+// =============================================================================
+// Plugin Export
+// =============================================================================
+
+// =============================================================================
+// Compaction Hook - Swarm Recovery Context
+// =============================================================================
+
+/**
+ * Detection result with confidence level
+ */
+interface SwarmDetection {
+  detected: boolean;
+  confidence: "high" | "medium" | "low" | "none";
+  reasons: string[];
+}
+
+/**
+ * Structured state snapshot for LLM-powered compaction
+ * 
+ * This is passed to the lite model to generate a continuation prompt
+ * with concrete data instead of just instructions.
+ */
+interface SwarmStateSnapshot {
+  sessionID: string;
+  detection: {
+    confidence: "high" | "medium" | "low" | "none";
+    reasons: string[];
+  };
+  epic?: {
+    id: string;
+    title: string;
+    status: string;
+    subtasks: Array<{
+      id: string;
+      title: string;
+      status: "open" | "in_progress" | "blocked" | "closed";
+      files: string[];
+      assignedTo?: string;
+    }>;
+  };
+  messages: Array<{
+    from: string;
+    to: string[];
+    subject: string;
+    body: string;
+    timestamp: number;
+    importance?: string;
+  }>;
+  reservations: Array<{
+    agent: string;
+    paths: string[];
+    exclusive: boolean;
+    expiresAt: number;
+  }>;
+}
+
+/**
+ * Query actual swarm state using spawn (like detectSwarm does)
+ * 
+ * Returns structured snapshot of current state for LLM compaction.
+ * Shells out to swarm CLI to get real data.
+ */
+async function querySwarmState(sessionID: string): Promise<SwarmStateSnapshot> {
+  const startTime = Date.now();
+  
+  logCompaction("debug", "query_swarm_state_start", {
+    session_id: sessionID,
+    project_directory: projectDirectory,
+  });
+
+  try {
+    // Query cells via swarm CLI
+    const cliStart = Date.now();
+    const cellsResult = await new Promise<{ exitCode: number; stdout: string; stderr: string }>(
+      (resolve) => {
+        const proc = spawn(SWARM_CLI, ["tool", "hive_query"], {
+          cwd: projectDirectory,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (d) => {
+          stdout += d;
+        });
+        proc.stderr.on("data", (d) => {
+          stderr += d;
+        });
+        proc.on("close", (exitCode) =>
+          resolve({ exitCode: exitCode ?? 1, stdout, stderr }),
+        );
+      },
+    );
+    const cliDuration = Date.now() - cliStart;
+
+    logCompaction("debug", "query_swarm_state_cli_complete", {
+      session_id: sessionID,
+      duration_ms: cliDuration,
+      exit_code: cellsResult.exitCode,
+      stdout_length: cellsResult.stdout.length,
+      stderr_length: cellsResult.stderr.length,
+    });
+
+    let cells: any[] = [];
+    if (cellsResult.exitCode === 0) {
+      try {
+        const parsed = JSON.parse(cellsResult.stdout);
+        // Handle wrapped response: { success: true, data: [...] }
+        cells = Array.isArray(parsed) ? parsed : (parsed?.data ?? []);
+      } catch (parseErr) {
+        logCompaction("error", "query_swarm_state_parse_failed", {
+          session_id: sessionID,
+          error: parseErr instanceof Error ? parseErr.message : String(parseErr),
+          stdout_preview: cellsResult.stdout.substring(0, 500),
+        });
+      }
+    }
+
+    logCompaction("debug", "query_swarm_state_cells_parsed", {
+      session_id: sessionID,
+      cell_count: cells.length,
+      cells: cells.map((c: any) => ({
+        id: c.id,
+        title: c.title,
+        type: c.type,
+        status: c.status,
+        parent_id: c.parent_id,
+      })),
+    });
+
+    // Find active epic (first unclosed epic with subtasks)
+    const openEpics = cells.filter(
+      (c: { type?: string; status: string }) =>
+        c.type === "epic" && c.status !== "closed",
+    );
+    const epic = openEpics[0];
+
+    logCompaction("debug", "query_swarm_state_epics", {
+      session_id: sessionID,
+      open_epic_count: openEpics.length,
+      selected_epic: epic ? { id: epic.id, title: epic.title, status: epic.status } : null,
+    });
+
+    // Get subtasks if we have an epic
+    const subtasks =
+      epic && epic.id
+        ? cells.filter(
+            (c: { parent_id?: string }) => c.parent_id === epic.id,
+          )
+        : [];
+
+    logCompaction("debug", "query_swarm_state_subtasks", {
+      session_id: sessionID,
+      subtask_count: subtasks.length,
+      subtasks: subtasks.map((s: any) => ({
+        id: s.id,
+        title: s.title,
+        status: s.status,
+        files: s.files,
+      })),
+    });
+
+    // TODO: Query swarm mail for messages and reservations
+    // For MVP, use empty arrays - the fallback chain handles this
+    const messages: SwarmStateSnapshot["messages"] = [];
+    const reservations: SwarmStateSnapshot["reservations"] = [];
+
+    // Run detection for confidence (already logged internally)
+    const detection = await detectSwarm();
+
+    const snapshot: SwarmStateSnapshot = {
+      sessionID,
+      detection: {
+        confidence: detection.confidence,
+        reasons: detection.reasons,
+      },
+      epic: epic
+        ? {
+            id: epic.id,
+            title: epic.title,
+            status: epic.status,
+            subtasks: subtasks.map((s: {
+              id: string;
+              title: string;
+              status: string;
+              files?: string[];
+            }) => ({
+              id: s.id,
+              title: s.title,
+              status: s.status as "open" | "in_progress" | "blocked" | "closed",
+              files: s.files || [],
+            })),
+          }
+        : undefined,
+      messages,
+      reservations,
+    };
+
+    const totalDuration = Date.now() - startTime;
+    logCompaction("debug", "query_swarm_state_complete", {
+      session_id: sessionID,
+      duration_ms: totalDuration,
+      has_epic: !!snapshot.epic,
+      epic_id: snapshot.epic?.id,
+      subtask_count: snapshot.epic?.subtasks?.length ?? 0,
+      message_count: snapshot.messages.length,
+      reservation_count: snapshot.reservations.length,
+    });
+
+    return snapshot;
+  } catch (err) {
+    logCompaction("error", "query_swarm_state_exception", {
+      session_id: sessionID,
+      error: err instanceof Error ? err.message : String(err),
+      stack: err instanceof Error ? err.stack : undefined,
+      duration_ms: Date.now() - startTime,
+    });
+
+    // If query fails, return minimal snapshot
+    const detection = await detectSwarm();
+    return {
+      sessionID,
+      detection: {
+        confidence: detection.confidence,
+        reasons: detection.reasons,
+      },
+      messages: [],
+      reservations: [],
+    };
+  }
+}
+
+/**
+ * Generate compaction prompt using LLM
+ * 
+ * Shells out to `opencode run -m <liteModel>` with structured state.
+ * Returns markdown continuation prompt or null on failure.
+ * 
+ * Timeout: 30 seconds
+ */
+async function generateCompactionPrompt(
+  snapshot: SwarmStateSnapshot,
+): Promise<string | null> {
+  const startTime = Date.now();
+  const liteModel = process.env.OPENCODE_LITE_MODEL || "__SWARM_LITE_MODEL__";
+
+  logCompaction("debug", "generate_compaction_prompt_start", {
+    session_id: snapshot.sessionID,
+    lite_model: liteModel,
+    has_epic: !!snapshot.epic,
+    epic_id: snapshot.epic?.id,
+    subtask_count: snapshot.epic?.subtasks?.length ?? 0,
+    snapshot_size: JSON.stringify(snapshot).length,
+  });
+
+  try {
+    const promptText = `You are generating a continuation prompt for a compacted swarm coordination session.
+
+Analyze this swarm state and generate a structured markdown prompt that will be given to the resumed session:
+
+${JSON.stringify(snapshot, null, 2)}
+
+Generate a prompt following this structure:
+
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│             🐝  YOU ARE THE COORDINATOR  🐝                 │
+│                                                             │
+│             NOT A WORKER. NOT AN IMPLEMENTER.               │
+│                  YOU ORCHESTRATE.                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+
+# 🐝 Swarm Continuation - [Epic Title or "Unknown"]
+
+**NON-NEGOTIABLE: YOU ARE THE COORDINATOR.** You resumed after context compaction.
+
+## Epic State
+
+**ID:** [epic ID or "Unknown"]
+**Title:** [epic title or "No active epic"]
+**Status:** [X/Y subtasks complete]
+**Project:** ${projectDirectory}
+
+## Subtask Status
+
+### ✅ Completed (N)
+[List completed subtasks with IDs]
+
+### 🚧 In Progress (N)
+[List in-progress subtasks with IDs, files, agents if known]
+
+### 🚫 Blocked (N)
+[List blocked subtasks]
+
+### ⏳ Pending (N)
+[List pending subtasks]
+
+## Next Actions (IMMEDIATE)
+
+[List 3-5 concrete actions with actual commands, using real IDs from the state]
+
+## 🎯 COORDINATOR MANDATES (NON-NEGOTIABLE)
+
+**YOU ARE THE COORDINATOR. NOT A WORKER.**
+
+### ⛔ FORBIDDEN - NEVER do these:
+- ❌ NEVER use \`edit\`, \`write\`, or \`bash\` for implementation - SPAWN A WORKER
+- ❌ NEVER fetch directly with \`repo-crawl_*\`, \`repo-autopsy_*\`, \`webfetch\`, \`fetch_fetch\` - SPAWN A RESEARCHER
+- ❌ NEVER use \`context7_*\` or \`pdf-brain_*\` directly - SPAWN A RESEARCHER
+- ❌ NEVER reserve files - Workers reserve files
+
+### ✅ ALWAYS do these:
+- ✅ ALWAYS check \`swarm_status\` and \`swarmmail_inbox\` first
+- ✅ ALWAYS use \`swarm_spawn_subtask\` for implementation work
+- ✅ ALWAYS use \`swarm_spawn_researcher\` for external data fetching
+- ✅ ALWAYS review worker output with \`swarm_review\` → \`swarm_review_feedback\`
+- ✅ ALWAYS monitor actively - Check messages every ~10 minutes
+- ✅ ALWAYS unblock aggressively - Resolve dependencies immediately
+
+**If you need external data:** Use \`swarm_spawn_researcher\` with a clear research task. The researcher will fetch, summarize, and return findings.
+
+**3-strike rule enforced:** Workers get 3 review attempts. After 3 rejections, escalate to human.
+
+Keep the prompt concise but actionable. Use actual data from the snapshot, not placeholders. Include the ASCII header and ALL coordinator mandates.`;
+
+    logCompaction("debug", "generate_compaction_prompt_calling_llm", {
+      session_id: snapshot.sessionID,
+      prompt_length: promptText.length,
+      model: liteModel,
+      command: `opencode run -m ${liteModel} -- <prompt>`,
+    });
+
+    const llmStart = Date.now();
+    const result = await new Promise<{ exitCode: number; stdout: string; stderr: string }>(
+      (resolve, reject) => {
+        const proc = spawn("opencode", ["run", "-m", liteModel, "--", promptText], {
+          cwd: projectDirectory,
+          stdio: ["ignore", "pipe", "pipe"],
+          timeout: 30000, // 30 second timeout
+        });
+
+        let stdout = "";
+        let stderr = "";
+
+        proc.stdout.on("data", (d) => {
+          stdout += d;
+        });
+        proc.stderr.on("data", (d) => {
+          stderr += d;
+        });
+
+        proc.on("close", (exitCode) => {
+          resolve({ exitCode: exitCode ?? 1, stdout, stderr });
+        });
+
+        proc.on("error", (err) => {
+          reject(err);
+        });
+
+        // Timeout handling
+        setTimeout(() => {
+          proc.kill("SIGTERM");
+          reject(new Error("LLM compaction timeout (30s)"));
+        }, 30000);
+      },
+    );
+    const llmDuration = Date.now() - llmStart;
+
+    logCompaction("debug", "generate_compaction_prompt_llm_complete", {
+      session_id: snapshot.sessionID,
+      duration_ms: llmDuration,
+      exit_code: result.exitCode,
+      stdout_length: result.stdout.length,
+      stderr_length: result.stderr.length,
+      stderr_preview: result.stderr.substring(0, 500),
+      stdout_preview: result.stdout.substring(0, 500),
+    });
+
+    if (result.exitCode !== 0) {
+      logCompaction("error", "generate_compaction_prompt_llm_failed", {
+        session_id: snapshot.sessionID,
+        exit_code: result.exitCode,
+        stderr: result.stderr,
+        stdout: result.stdout,
+        duration_ms: llmDuration,
+      });
+      return null;
+    }
+
+    // Extract the prompt from stdout (LLM may wrap in markdown)
+    const prompt = result.stdout.trim();
+    
+    const totalDuration = Date.now() - startTime;
+    logCompaction("debug", "generate_compaction_prompt_success", {
+      session_id: snapshot.sessionID,
+      total_duration_ms: totalDuration,
+      llm_duration_ms: llmDuration,
+      prompt_length: prompt.length,
+      prompt_preview: prompt.substring(0, 500),
+      prompt_has_content: prompt.length > 0,
+    });
+
+    return prompt.length > 0 ? prompt : null;
+  } catch (err) {
+    const totalDuration = Date.now() - startTime;
+    logCompaction("error", "generate_compaction_prompt_exception", {
+      session_id: snapshot.sessionID,
+      error: err instanceof Error ? err.message : String(err),
+      stack: err instanceof Error ? err.stack : undefined,
+      duration_ms: totalDuration,
+    });
+    return null;
+  }
+}
+
+/**
+ * Session message scan result
+ */
+interface SessionScanResult {
+  messageCount: number;
+  toolCalls: Array<{
+    toolName: string;
+    args: Record<string, unknown>;
+    output?: string;
+    timestamp?: number;
+  }>;
+  swarmDetected: boolean;
+  reasons: string[];
+  /** Projected swarm state from event fold - ground truth from session events */
+  projection?: SwarmProjection;
+}
+
+/**
+ * Scan session messages for swarm tool calls
+ * 
+ * Uses SDK client to fetch messages and look for swarm activity.
+ * This can detect swarm work even if no cells exist yet.
+ */
+async function scanSessionMessages(sessionID: string): Promise<SessionScanResult> {
+  const startTime = Date.now();
+  const result: SessionScanResult = {
+    messageCount: 0,
+    toolCalls: [],
+    swarmDetected: false,
+    reasons: [],
+  };
+
+  logCompaction("debug", "session_scan_start", {
+    session_id: sessionID,
+    has_sdk_client: !!sdkClient,
+  });
+
+  if (!sdkClient) {
+    logCompaction("warn", "session_scan_no_sdk_client", {
+      session_id: sessionID,
+    });
+    return result;
+  }
+
+  try {
+    // Fetch session messages
+    const messagesStart = Date.now();
+    const rawResponse = await sdkClient.session.messages({ path: { id: sessionID } });
+    const messagesDuration = Date.now() - messagesStart;
+
+    // Log the RAW response to understand its shape
+    logCompaction("debug", "session_scan_raw_response", {
+      session_id: sessionID,
+      response_type: typeof rawResponse,
+      is_array: Array.isArray(rawResponse),
+      is_null: rawResponse === null,
+      is_undefined: rawResponse === undefined,
+      keys: rawResponse && typeof rawResponse === 'object' ? Object.keys(rawResponse) : [],
+      raw_preview: JSON.stringify(rawResponse)?.slice(0, 500),
+    });
+
+    // The response might be wrapped - check common patterns
+    const messages = Array.isArray(rawResponse) 
+      ? rawResponse 
+      : rawResponse?.data 
+      ? rawResponse.data 
+      : rawResponse?.messages 
+      ? rawResponse.messages 
+      : rawResponse?.items
+      ? rawResponse.items
+      : [];
+
+    result.messageCount = messages?.length ?? 0;
+
+    logCompaction("debug", "session_scan_messages_fetched", {
+      session_id: sessionID,
+      duration_ms: messagesDuration,
+      message_count: result.messageCount,
+      extraction_method: Array.isArray(rawResponse) ? 'direct_array' : rawResponse?.data ? 'data_field' : rawResponse?.messages ? 'messages_field' : rawResponse?.items ? 'items_field' : 'fallback_empty',
+    });
+
+    if (!Array.isArray(messages) || messages.length === 0) {
+      logCompaction("debug", "session_scan_no_messages", {
+        session_id: sessionID,
+      });
+      return result;
+    }
+
+    // Swarm-related tool patterns
+    const swarmTools = [
+      // High confidence - active swarm coordination
+      "hive_create_epic",
+      "swarm_decompose",
+      "swarm_spawn_subtask",
+      "swarm_complete",
+      "swarmmail_init",
+      "swarmmail_reserve",
+      // Medium confidence - swarm activity
+      "hive_start",
+      "hive_close",
+      "swarm_status",
+      "swarm_progress",
+      "swarmmail_send",
+      // Low confidence - possible swarm
+      "hive_create",
+      "hive_query",
+    ];
+
+    const highConfidenceTools = new Set([
+      "hive_create_epic",
+      "swarm_decompose",
+      "swarm_spawn_subtask",
+      "swarmmail_init",
+      "swarmmail_reserve",
+    ]);
+
+    // Scan messages for tool calls
+    let swarmToolCount = 0;
+    let highConfidenceCount = 0;
+    
+    // Debug: collect part types to understand message structure
+    const partTypeCounts: Record<string, number> = {};
+    let messagesWithParts = 0;
+    let messagesWithoutParts = 0;
+    let samplePartTypes: string[] = [];
+
+    for (const message of messages) {
+      if (!message.parts || !Array.isArray(message.parts)) {
+        messagesWithoutParts++;
+        continue;
+      }
+      messagesWithParts++;
+
+      for (const part of message.parts) {
+        const partType = part.type || "unknown";
+        partTypeCounts[partType] = (partTypeCounts[partType] || 0) + 1;
+        
+        // Collect first 10 unique part types for debugging
+        if (samplePartTypes.length < 10 && !samplePartTypes.includes(partType)) {
+          samplePartTypes.push(partType);
+        }
+        
+        // Check if this is a tool call part
+        // OpenCode SDK: ToolPart has type="tool", tool=<string name>, state={...}
+        if (part.type === "tool") {
+          const toolPart = part as ToolPart;
+          const toolName = toolPart.tool; // tool name is a string directly
+          
+          if (toolName && swarmTools.includes(toolName)) {
+            swarmToolCount++;
+            
+            if (highConfidenceTools.has(toolName)) {
+              highConfidenceCount++;
+            }
+
+            // Extract args/output/timestamp from state if available
+            const state = toolPart.state;
+            const args = state && "input" in state ? state.input : {};
+            const output = state && "output" in state ? state.output : undefined;
+            const timestamp = state && "time" in state && state.time && typeof state.time === "object" && "end" in state.time 
+              ? (state.time as { end: number }).end 
+              : Date.now();
+
+            result.toolCalls.push({
+              toolName,
+              args,
+              output,
+              timestamp,
+            });
+
+            logCompaction("debug", "session_scan_tool_found", {
+              session_id: sessionID,
+              tool_name: toolName,
+              is_high_confidence: highConfidenceTools.has(toolName),
+            });
+          }
+        }
+      }
+    }
+
+    // =======================================================================
+    // PROJECT SWARM STATE FROM EVENTS (deterministic, no heuristics)
+    // =======================================================================
+    // Convert tool calls to ToolCallEvent format for projection
+    const events: ToolCallEvent[] = result.toolCalls.map(tc => ({
+      tool: tc.toolName,
+      input: tc.args as Record<string, unknown>,
+      output: tc.output || "{}",
+      timestamp: tc.timestamp || Date.now(),
+    }));
+
+    // Project swarm state from events - this is the ground truth
+    const projection = projectSwarmState(events);
+    result.projection = projection;
+
+    // Use projection for swarm detection (deterministic)
+    if (projection.isSwarm) {
+      result.swarmDetected = true;
+      result.reasons.push(`Swarm signature detected: epic ${projection.epic?.id || "unknown"} with ${projection.counts.total} subtasks`);
+      
+      if (isSwarmActive(projection)) {
+        result.reasons.push(`Swarm ACTIVE: ${projection.counts.spawned} spawned, ${projection.counts.inProgress} in_progress, ${projection.counts.completed} completed (not closed)`);
+      } else {
+        result.reasons.push(`Swarm COMPLETE: all ${projection.counts.closed} subtasks closed`);
+      }
+    } else if (highConfidenceCount > 0) {
+      // Fallback to heuristic detection if no signature but high-confidence tools found
+      result.swarmDetected = true;
+      result.reasons.push(`${highConfidenceCount} high-confidence swarm tools (${Array.from(new Set(result.toolCalls.filter(tc => highConfidenceTools.has(tc.toolName)).map(tc => tc.toolName))).join(", ")})`);
+    } else if (swarmToolCount > 0) {
+      result.swarmDetected = true;
+      result.reasons.push(`${swarmToolCount} swarm-related tools used`);
+    }
+
+    const totalDuration = Date.now() - startTime;
+    
+    // Debug: log part type distribution to understand message structure
+    logCompaction("debug", "session_scan_part_types", {
+      session_id: sessionID,
+      messages_with_parts: messagesWithParts,
+      messages_without_parts: messagesWithoutParts,
+      part_type_counts: partTypeCounts,
+      sample_part_types: samplePartTypes,
+    });
+    
+    logCompaction("info", "session_scan_complete", {
+      session_id: sessionID,
+      duration_ms: totalDuration,
+      message_count: result.messageCount,
+      tool_call_count: result.toolCalls.length,
+      swarm_tool_count: swarmToolCount,
+      high_confidence_count: highConfidenceCount,
+      swarm_detected: result.swarmDetected,
+      reasons: result.reasons,
+      unique_tools: Array.from(new Set(result.toolCalls.map(tc => tc.toolName))),
+      // Add projection summary
+      projection_summary: projection.isSwarm ? {
+        epic_id: projection.epic?.id,
+        epic_title: projection.epic?.title,
+        epic_status: projection.epic?.status,
+        is_active: isSwarmActive(projection),
+        counts: projection.counts,
+      } : null,
+    });
+
+    return result;
+  } catch (err) {
+    const totalDuration = Date.now() - startTime;
+    logCompaction("error", "session_scan_exception", {
+      session_id: sessionID,
+      error: err instanceof Error ? err.message : String(err),
+      stack: err instanceof Error ? err.stack : undefined,
+      duration_ms: totalDuration,
+    });
+    return result;
+  }
+}
+
+/**
+ * Check for swarm sign - evidence a swarm passed through
+ *
+ * Uses multiple signals with different confidence levels:
+ * - HIGH: in_progress cells (active work)
+ * - MEDIUM: Open subtasks, unclosed epics, recently updated cells
+ * - LOW: Any cells exist
+ *
+ * Philosophy: Err on the side of continuation.
+ * False positive = extra context (low cost)
+ * False negative = lost swarm (high cost)
+ */
+async function detectSwarm(): Promise<SwarmDetection> {
+  const startTime = Date.now();
+  const reasons: string[] = [];
+  let highConfidence = false;
+  let mediumConfidence = false;
+  let lowConfidence = false;
+
+  logCompaction("debug", "detect_swarm_start", {
+    project_directory: projectDirectory,
+    cwd: process.cwd(),
+  });
+
+  try {
+    const cliStart = Date.now();
+    const result = await new Promise<{ exitCode: number; stdout: string; stderr: string }>(
+      (resolve) => {
+        // Use swarm tool to query beads
+        const proc = spawn(SWARM_CLI, ["tool", "hive_query"], {
+          cwd: projectDirectory,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (d) => {
+          stdout += d;
+        });
+        proc.stderr.on("data", (d) => {
+          stderr += d;
+        });
+        proc.on("close", (exitCode) =>
+          resolve({ exitCode: exitCode ?? 1, stdout, stderr }),
+        );
+      },
+    );
+    const cliDuration = Date.now() - cliStart;
+
+    logCompaction("debug", "detect_swarm_cli_complete", {
+      duration_ms: cliDuration,
+      exit_code: result.exitCode,
+      stdout_length: result.stdout.length,
+      stderr_length: result.stderr.length,
+      stderr_preview: result.stderr.substring(0, 200),
+    });
+
+    if (result.exitCode !== 0) {
+      logCompaction("warn", "detect_swarm_cli_failed", {
+        exit_code: result.exitCode,
+        stderr: result.stderr,
+      });
+      return { detected: false, confidence: "none", reasons: ["hive_query failed"] };
+    }
+
+    let cells: any[];
+    try {
+      cells = JSON.parse(result.stdout);
+    } catch (parseErr) {
+      logCompaction("error", "detect_swarm_parse_failed", {
+        error: parseErr instanceof Error ? parseErr.message : String(parseErr),
+        stdout_preview: result.stdout.substring(0, 500),
+      });
+      return { detected: false, confidence: "none", reasons: ["hive_query parse failed"] };
+    }
+
+    if (!Array.isArray(cells) || cells.length === 0) {
+      logCompaction("debug", "detect_swarm_no_cells", {
+        is_array: Array.isArray(cells),
+        length: cells?.length ?? 0,
+      });
+      return { detected: false, confidence: "none", reasons: ["no cells found"] };
+    }
+
+    // Log ALL cells for debugging
+    logCompaction("debug", "detect_swarm_cells_found", {
+      total_cells: cells.length,
+      cells: cells.map((c: any) => ({
+        id: c.id,
+        title: c.title,
+        type: c.type,
+        status: c.status,
+        parent_id: c.parent_id,
+        updated_at: c.updated_at,
+        created_at: c.created_at,
+      })),
+    });
+
+    // HIGH: Any in_progress cells
+    const inProgress = cells.filter(
+      (c: { status: string }) => c.status === "in_progress"
+    );
+    if (inProgress.length > 0) {
+      highConfidence = true;
+      reasons.push(`${inProgress.length} cells in_progress`);
+      logCompaction("debug", "detect_swarm_in_progress", {
+        count: inProgress.length,
+        cells: inProgress.map((c: any) => ({ id: c.id, title: c.title })),
+      });
+    }
+
+    // MEDIUM: Open subtasks (cells with parent_id)
+    const subtasks = cells.filter(
+      (c: { status: string; parent_id?: string }) =>
+        c.status === "open" && c.parent_id
+    );
+    if (subtasks.length > 0) {
+      mediumConfidence = true;
+      reasons.push(`${subtasks.length} open subtasks`);
+      logCompaction("debug", "detect_swarm_open_subtasks", {
+        count: subtasks.length,
+        cells: subtasks.map((c: any) => ({ id: c.id, title: c.title, parent_id: c.parent_id })),
+      });
+    }
+
+    // MEDIUM: Unclosed epics
+    const openEpics = cells.filter(
+      (c: { status: string; type?: string }) =>
+        c.type === "epic" && c.status !== "closed"
+    );
+    if (openEpics.length > 0) {
+      mediumConfidence = true;
+      reasons.push(`${openEpics.length} unclosed epics`);
+      logCompaction("debug", "detect_swarm_open_epics", {
+        count: openEpics.length,
+        cells: openEpics.map((c: any) => ({ id: c.id, title: c.title, status: c.status })),
+      });
+    }
+
+    // MEDIUM: Recently updated cells (last hour)
+    const oneHourAgo = Date.now() - 60 * 60 * 1000;
+    const recentCells = cells.filter(
+      (c: { updated_at?: number }) => c.updated_at && c.updated_at > oneHourAgo
+    );
+    if (recentCells.length > 0) {
+      mediumConfidence = true;
+      reasons.push(`${recentCells.length} cells updated in last hour`);
+      logCompaction("debug", "detect_swarm_recent_cells", {
+        count: recentCells.length,
+        one_hour_ago: oneHourAgo,
+        cells: recentCells.map((c: any) => ({ 
+          id: c.id, 
+          title: c.title, 
+          updated_at: c.updated_at,
+          age_minutes: Math.round((Date.now() - c.updated_at) / 60000),
+        })),
+      });
+    }
+
+    // LOW: Any cells exist at all
+    if (cells.length > 0) {
+      lowConfidence = true;
+      reasons.push(`${cells.length} total cells in hive`);
+    }
+  } catch (err) {
+    // Detection failed, use fallback
+    lowConfidence = true;
+    reasons.push("Detection error, using fallback");
+    logCompaction("error", "detect_swarm_exception", {
+      error: err instanceof Error ? err.message : String(err),
+      stack: err instanceof Error ? err.stack : undefined,
+    });
+  }
+
+  // Determine overall confidence
+  let confidence: "high" | "medium" | "low" | "none";
+  if (highConfidence) {
+    confidence = "high";
+  } else if (mediumConfidence) {
+    confidence = "medium";
+  } else if (lowConfidence) {
+    confidence = "low";
+  } else {
+    confidence = "none";
+  }
+
+  const totalDuration = Date.now() - startTime;
+  logCompaction("debug", "detect_swarm_complete", {
+    duration_ms: totalDuration,
+    confidence,
+    detected: confidence !== "none",
+    reason_count: reasons.length,
+    reasons,
+    high_confidence: highConfidence,
+    medium_confidence: mediumConfidence,
+    low_confidence: lowConfidence,
+  });
+
+  return {
+    detected: confidence !== "none",
+    confidence,
+    reasons,
+  };
+}
+
+/**
+ * Swarm-aware compaction context
+ *
+ * Injected during compaction to keep the swarm cooking. The coordinator should
+ * wake up from compaction and immediately resume orchestration - spawning agents,
+ * monitoring progress, unblocking work.
+ */
+const SWARM_COMPACTION_CONTEXT = `## 🐝 SWARM ACTIVE - Keep Cooking
+
+You are the **COORDINATOR** of an active swarm. Context was compacted but the swarm is still running.
+
+**YOUR JOB:** Keep orchestrating. Spawn agents. Monitor progress. Unblock work. Ship it.
+
+### Preserve in Summary
+
+Extract from session context:
+
+1. **Epic & Subtasks** - IDs, titles, status, file assignments
+2. **What's Running** - Which agents are active, what they're working on  
+3. **What's Blocked** - Blockers and what's needed to unblock
+4. **What's Done** - Completed work and any follow-ups needed
+5. **What's Next** - Pending subtasks ready to spawn
+
+### Summary Format
+
+\`\`\`
+## 🐝 Swarm State
+
+**Epic:** <bd-xxx> - <title>
+**Project:** <path>
+**Progress:** X/Y subtasks complete
+
+**Active:**
+- <bd-xxx>: <title> [in_progress] → <agent> working on <files>
+
+**Blocked:**
+- <bd-xxx>: <title> - BLOCKED: <reason>
+
+**Completed:**
+- <bd-xxx>: <title> ✓
+
+**Ready to Spawn:**
+- <bd-xxx>: <title> (files: <...>)
+\`\`\`
+
+### On Resume - IMMEDIATELY
+
+1. \`swarm_status(epic_id="<epic>", project_key="<path>")\` - Get current state
+2. \`swarmmail_inbox(limit=5)\` - Check for agent messages
+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
+
+- **Spawn aggressively** - If a subtask is ready and unblocked, spawn an agent
+- **Monitor actively** - Check status, read messages, respond to blockers
+- **Close the loop** - When all subtasks done, verify and close the epic
+- **Don't stop** - The swarm runs until the epic is closed
+
+**You are not waiting for instructions. You are the coordinator. Coordinate.**
+`;
+
+/**
+ * Fallback detection prompt - tells the compactor what to look for
+ * 
+ * Used when we can't definitively detect a swarm but want to be safe.
+ * The compactor can check the conversation context for these patterns.
+ */
+const SWARM_DETECTION_FALLBACK = `## 🐝 Swarm Detection - Check Your Context
+
+**IMPORTANT:** Before summarizing, check if this session involves an active swarm.
+
+Look for ANY of these patterns in the conversation:
+
+### Tool Calls (definite swarm sign)
+- \`swarm_decompose\`, \`swarm_spawn_subtask\`, \`swarm_status\`, \`swarm_complete\`
+- \`swarmmail_init\`, \`swarmmail_reserve\`, \`swarmmail_send\`
+- \`hive_create_epic\`, \`hive_start\`, \`hive_close\`
+
+### IDs and Names
+- Cell IDs: \`bd-xxx\`, \`bd-xxx.N\` (subtask format)
+- Agent names: BlueLake, RedMountain, GreenValley, etc.
+- Epic references: "epic", "subtask", "parent"
+
+### Coordination Language
+- "spawn", "worker", "coordinator"
+- "reserve", "reservation", "files"
+- "blocked", "unblock", "dependency"
+- "progress", "complete", "in_progress"
+
+### If You Find Swarm Evidence
+
+Include this in your summary:
+1. Epic ID and title
+2. Project path
+3. Subtask status (running/blocked/done/pending)
+4. Any blockers or issues
+5. What should happen next
+
+**Then tell the resumed session:**
+"This is an active swarm. Check swarm_status and swarmmail_inbox immediately."
+`;
+
+// Extended hooks type to include experimental compaction hook with new prompt API
+type CompactionOutput = {
+  context: string[];
+  prompt?: string; // NEW API from OpenCode PR #5907
+};
+
+type ExtendedHooks = Hooks & {
+  "experimental.session.compacting"?: (
+    input: { sessionID: string },
+    output: CompactionOutput,
+  ) => Promise<void>;
+};
+
+// NOTE: Only default export - named exports cause double registration!
+// OpenCode's plugin loader calls ALL exports as functions.
+const SwarmPlugin: Plugin = async (
+  input: PluginInput,
+): Promise<ExtendedHooks> => {
+  // CRITICAL: Set project directory from OpenCode input
+  // Without this, CLI uses wrong database path
+  projectDirectory = input.directory;
+  
+  // Store SDK client for session message scanning during compaction
+  sdkClient = input.client;
+  
+  return {
+    tool: {
+      // Beads
+      hive_create,
+      hive_create_epic,
+      hive_query,
+      hive_update,
+      hive_close,
+      hive_start,
+      hive_ready,
+      hive_cells,
+      hive_sync,
+      beads_link_thread,
+      // Swarm Mail (Embedded)
+      swarmmail_init,
+      swarmmail_send,
+      swarmmail_inbox,
+      swarmmail_read_message,
+      swarmmail_reserve,
+      swarmmail_release,
+      swarmmail_ack,
+      swarmmail_health,
+      // Structured
+      structured_extract_json,
+      structured_validate,
+      structured_parse_evaluation,
+      structured_parse_decomposition,
+      structured_parse_cell_tree,
+      // Swarm
+      swarm_init,
+      swarm_select_strategy,
+      swarm_plan_prompt,
+      swarm_decompose,
+      swarm_validate_decomposition,
+      swarm_status,
+      swarm_progress,
+      swarm_complete,
+      swarm_record_outcome,
+      swarm_subtask_prompt,
+      swarm_spawn_subtask,
+      swarm_complete_subtask,
+      swarm_evaluation_prompt,
+      swarm_broadcast,
+      // Worktree Isolation
+      swarm_worktree_create,
+      swarm_worktree_merge,
+      swarm_worktree_cleanup,
+      swarm_worktree_list,
+      // Structured Review
+      swarm_review,
+      swarm_review_feedback,
+      // Skills
+      skills_list,
+      skills_read,
+      skills_use,
+      skills_create,
+      skills_update,
+      skills_delete,
+      skills_init,
+      skills_add_script,
+      skills_execute,
+      // Swarm Insights
+      swarm_get_strategy_insights,
+      swarm_get_file_insights,
+      swarm_get_pattern_insights,
+      // CASS (Cross-Agent Session Search)
+      cass_search,
+      cass_view,
+      cass_expand,
+      cass_health,
+      cass_index,
+      cass_stats,
+    },
+
+    // Swarm-aware compaction hook with LLM-powered continuation prompts
+    // Three-level fallback chain: LLM → static context → detection fallback → none
+    "experimental.session.compacting": async (
+      input: { sessionID: string },
+      output: CompactionOutput,
+    ) => {
+      const startTime = Date.now();
+      
+      // =======================================================================
+      // LOG: Compaction hook invoked - capture EVERYTHING we receive
+      // =======================================================================
+      logCompaction("info", "compaction_hook_invoked", {
+        session_id: input.sessionID,
+        project_directory: projectDirectory,
+        input_keys: Object.keys(input),
+        input_full: JSON.parse(JSON.stringify(input)), // Deep clone for logging
+        output_keys: Object.keys(output),
+        output_context_count: output.context?.length ?? 0,
+        output_has_prompt_field: "prompt" in output,
+        output_initial_state: {
+          context: output.context,
+          prompt: (output as any).prompt,
+        },
+        env: {
+          OPENCODE_SESSION_ID: process.env.OPENCODE_SESSION_ID,
+          OPENCODE_MESSAGE_ID: process.env.OPENCODE_MESSAGE_ID,
+          OPENCODE_AGENT: process.env.OPENCODE_AGENT,
+          OPENCODE_LITE_MODEL: process.env.OPENCODE_LITE_MODEL,
+          SWARM_PROJECT_DIR: process.env.SWARM_PROJECT_DIR,
+        },
+        cwd: process.cwd(),
+        timestamp: new Date().toISOString(),
+      });
+
+      // =======================================================================
+      // STEP 1: Scan session messages for swarm tool calls
+      // =======================================================================
+      const sessionScanStart = Date.now();
+      const sessionScan = await scanSessionMessages(input.sessionID);
+      const sessionScanDuration = Date.now() - sessionScanStart;
+
+      logCompaction("info", "session_scan_results", {
+        session_id: input.sessionID,
+        duration_ms: sessionScanDuration,
+        message_count: sessionScan.messageCount,
+        tool_call_count: sessionScan.toolCalls.length,
+        swarm_detected_from_messages: sessionScan.swarmDetected,
+        reasons: sessionScan.reasons,
+      });
+
+      // =======================================================================
+      // STEP 2: Detect swarm state from hive cells
+      // =======================================================================
+      const detectionStart = Date.now();
+      const detection = await detectSwarm();
+      const detectionDuration = Date.now() - detectionStart;
+
+      logCompaction("info", "swarm_detection_complete", {
+        session_id: input.sessionID,
+        duration_ms: detectionDuration,
+        detected: detection.detected,
+        confidence: detection.confidence,
+        reasons: detection.reasons,
+        reason_count: detection.reasons.length,
+      });
+
+      // =======================================================================
+      // STEP 3: Merge session scan with hive detection for final confidence
+      // =======================================================================
+      // If session messages show high-confidence swarm tools, boost confidence
+      if (sessionScan.swarmDetected && sessionScan.reasons.some(r => r.includes("high-confidence"))) {
+        if (detection.confidence === "none" || detection.confidence === "low") {
+          detection.confidence = "high";
+          detection.detected = true;
+          detection.reasons.push(...sessionScan.reasons);
+          
+          logCompaction("info", "confidence_boost_from_session_scan", {
+            session_id: input.sessionID,
+            original_confidence: detection.confidence,
+            boosted_to: "high",
+            session_reasons: sessionScan.reasons,
+          });
+        }
+      } else if (sessionScan.swarmDetected) {
+        // Medium boost for any swarm tools found
+        if (detection.confidence === "none") {
+          detection.confidence = "medium";
+          detection.detected = true;
+          detection.reasons.push(...sessionScan.reasons);
+
+          logCompaction("info", "confidence_boost_from_session_scan", {
+            session_id: input.sessionID,
+            original_confidence: "none",
+            boosted_to: "medium",
+            session_reasons: sessionScan.reasons,
+          });
+        } else if (detection.confidence === "low") {
+          detection.confidence = "medium";
+          detection.reasons.push(...sessionScan.reasons);
+
+          logCompaction("info", "confidence_boost_from_session_scan", {
+            session_id: input.sessionID,
+            original_confidence: "low",
+            boosted_to: "medium",
+            session_reasons: sessionScan.reasons,
+          });
+        }
+      }
+
+      logCompaction("info", "final_swarm_detection", {
+        session_id: input.sessionID,
+        confidence: detection.confidence,
+        detected: detection.detected,
+        combined_reasons: detection.reasons,
+        message_scan_contributed: sessionScan.swarmDetected,
+      });
+
+      if (detection.confidence === "high" || detection.confidence === "medium") {
+        // Definite or probable swarm - try LLM-powered compaction
+        logCompaction("info", "swarm_detected_attempting_llm", {
+          session_id: input.sessionID,
+          confidence: detection.confidence,
+          reasons: detection.reasons,
+          has_projection: !!sessionScan.projection?.isSwarm,
+        });
+
+        try {
+          // =======================================================================
+          // PREFER PROJECTION (ground truth from events) OVER HIVE QUERY
+          // =======================================================================
+          // The projection is derived from session events - it's the source of truth.
+          // Hive query may show all cells closed even if swarm was active.
+          
+          let snapshot: SwarmStateSnapshot;
+          
+          if (sessionScan.projection?.isSwarm) {
+            // Use projection as primary source - convert to snapshot format
+            const proj = sessionScan.projection;
+            snapshot = {
+              sessionID: input.sessionID,
+              detection: {
+                confidence: isSwarmActive(proj) ? "high" : "medium",
+                reasons: sessionScan.reasons,
+              },
+              epic: proj.epic ? {
+                id: proj.epic.id,
+                title: proj.epic.title,
+                status: proj.epic.status,
+                subtasks: Array.from(proj.subtasks.values()).map(s => ({
+                  id: s.id,
+                  title: s.title,
+                  status: s.status as "open" | "in_progress" | "blocked" | "closed",
+                  files: s.files,
+                })),
+              } : undefined,
+              messages: [],
+              reservations: [],
+            };
+            
+            logCompaction("info", "using_projection_as_snapshot", {
+              session_id: input.sessionID,
+              epic_id: proj.epic?.id,
+              epic_title: proj.epic?.title,
+              subtask_count: proj.subtasks.size,
+              is_active: isSwarmActive(proj),
+              counts: proj.counts,
+            });
+          } else {
+            // Fallback to hive query (may be stale)
+            const queryStart = Date.now();
+            snapshot = await querySwarmState(input.sessionID);
+            const queryDuration = Date.now() - queryStart;
+            
+            logCompaction("info", "fallback_to_hive_query", {
+              session_id: input.sessionID,
+              duration_ms: queryDuration,
+              reason: "no projection available or not a swarm",
+            });
+          }
+
+          logCompaction("info", "swarm_state_resolved", {
+            session_id: input.sessionID,
+            source: sessionScan.projection?.isSwarm ? "projection" : "hive_query",
+            has_epic: !!snapshot.epic,
+            epic_id: snapshot.epic?.id,
+            epic_title: snapshot.epic?.title,
+            epic_status: snapshot.epic?.status,
+            subtask_count: snapshot.epic?.subtasks?.length ?? 0,
+            subtasks: snapshot.epic?.subtasks?.map(s => ({
+              id: s.id,
+              title: s.title,
+              status: s.status,
+              file_count: s.files?.length ?? 0,
+            })),
+            message_count: snapshot.messages?.length ?? 0,
+            reservation_count: snapshot.reservations?.length ?? 0,
+            detection_confidence: snapshot.detection.confidence,
+            detection_reasons: snapshot.detection.reasons,
+          });
+
+          // =======================================================================
+          // CAPTURE POINT 1: Detection complete - record confidence and reasons
+          // =======================================================================
+          await captureCompaction(
+            input.sessionID,
+            snapshot.epic?.id || "unknown",
+            "detection_complete",
+            {
+              confidence: snapshot.detection.confidence,
+              detected: detection.detected,
+              reasons: snapshot.detection.reasons,
+              session_scan_contributed: sessionScan.swarmDetected,
+              session_scan_reasons: sessionScan.reasons,
+              epic_id: snapshot.epic?.id,
+              epic_title: snapshot.epic?.title,
+              subtask_count: snapshot.epic?.subtasks?.length ?? 0,
+            },
+          );
+
+          // Level 2: Generate prompt with LLM
+          const llmStart = Date.now();
+          const llmPrompt = await generateCompactionPrompt(snapshot);
+          const llmDuration = Date.now() - llmStart;
+
+          logCompaction("info", "llm_generation_complete", {
+            session_id: input.sessionID,
+            duration_ms: llmDuration,
+            success: !!llmPrompt,
+            prompt_length: llmPrompt?.length ?? 0,
+            prompt_preview: llmPrompt?.substring(0, 500),
+          });
+
+          // =======================================================================
+          // CAPTURE POINT 2: Prompt generated - record FULL prompt content
+          // =======================================================================
+          if (llmPrompt) {
+            await captureCompaction(
+              input.sessionID,
+              snapshot.epic?.id || "unknown",
+              "prompt_generated",
+              {
+                prompt_length: llmPrompt.length,
+                full_prompt: llmPrompt, // FULL content, not truncated
+                context_type: "llm_generated",
+                duration_ms: llmDuration,
+              },
+            );
+          }
+
+          if (llmPrompt) {
+            // SUCCESS: Use LLM-generated prompt
+            const header = `[Swarm compaction: LLM-generated, ${detection.reasons.join(", ")}]\n\n`;
+            const fullContent = header + llmPrompt;
+
+            // Progressive enhancement: use new API if available
+            if ("prompt" in output) {
+              output.prompt = fullContent;
+              logCompaction("info", "context_injected_via_prompt_api", {
+                session_id: input.sessionID,
+                content_length: fullContent.length,
+                method: "output.prompt",
+              });
+            } else {
+              output.context.push(fullContent);
+              logCompaction("info", "context_injected_via_context_array", {
+                session_id: input.sessionID,
+                content_length: fullContent.length,
+                method: "output.context.push",
+                context_count_after: output.context.length,
+              });
+            }
+
+            // =======================================================================
+            // CAPTURE POINT 3a: Context injected (LLM path) - record FULL content
+            // =======================================================================
+            await captureCompaction(
+              input.sessionID,
+              snapshot.epic?.id || "unknown",
+              "context_injected",
+              {
+                full_content: fullContent, // FULL content, not truncated
+                content_length: fullContent.length,
+                injection_method: "prompt" in output ? "output.prompt" : "output.context.push",
+                context_type: "llm_generated",
+              },
+            );
+
+            const totalDuration = Date.now() - startTime;
+            logCompaction("info", "compaction_complete_llm_success", {
+              session_id: input.sessionID,
+              total_duration_ms: totalDuration,
+              detection_duration_ms: detectionDuration,
+              query_duration_ms: queryDuration,
+              llm_duration_ms: llmDuration,
+              confidence: detection.confidence,
+              context_type: "llm_generated",
+              content_length: fullContent.length,
+            });
+            return;
+          }
+
+          // LLM failed, fall through to static prompt
+          logCompaction("warn", "llm_generation_returned_null", {
+            session_id: input.sessionID,
+            llm_duration_ms: llmDuration,
+            falling_back_to: "static_prompt",
+          });
+        } catch (err) {
+          // LLM failed, fall through to static prompt
+          logCompaction("error", "llm_generation_failed", {
+            session_id: input.sessionID,
+            error: err instanceof Error ? err.message : String(err),
+            error_stack: err instanceof Error ? err.stack : undefined,
+            falling_back_to: "static_prompt",
+          });
+        }
+
+        // Level 3: Fall back to static context
+        const header = `[Swarm detected: ${detection.reasons.join(", ")}]\n\n`;
+        const staticContent = header + SWARM_COMPACTION_CONTEXT;
+        output.context.push(staticContent);
+
+        // =======================================================================
+        // CAPTURE POINT 3b: Context injected (static fallback) - record FULL content
+        // =======================================================================
+        await captureCompaction(
+          input.sessionID,
+          "unknown", // No snapshot available in this path
+          "context_injected",
+          {
+            full_content: staticContent,
+            content_length: staticContent.length,
+            injection_method: "output.context.push",
+            context_type: "static_swarm_context",
+          },
+        );
+
+        const totalDuration = Date.now() - startTime;
+        logCompaction("info", "compaction_complete_static_fallback", {
+          session_id: input.sessionID,
+          total_duration_ms: totalDuration,
+          confidence: detection.confidence,
+          context_type: "static_swarm_context",
+          content_length: staticContent.length,
+          context_count_after: output.context.length,
+        });
+      } else if (detection.confidence === "low") {
+        // Level 4: Possible swarm - inject fallback detection prompt
+        const header = `[Possible swarm: ${detection.reasons.join(", ")}]\n\n`;
+        const fallbackContent = header + SWARM_DETECTION_FALLBACK;
+        output.context.push(fallbackContent);
+
+        // =======================================================================
+        // CAPTURE POINT 3c: Context injected (detection fallback) - record FULL content
+        // =======================================================================
+        await captureCompaction(
+          input.sessionID,
+          "unknown", // No snapshot for low confidence
+          "context_injected",
+          {
+            full_content: fallbackContent,
+            content_length: fallbackContent.length,
+            injection_method: "output.context.push",
+            context_type: "detection_fallback",
+          },
+        );
+
+        const totalDuration = Date.now() - startTime;
+        logCompaction("info", "compaction_complete_detection_fallback", {
+          session_id: input.sessionID,
+          total_duration_ms: totalDuration,
+          confidence: detection.confidence,
+          context_type: "detection_fallback",
+          content_length: fallbackContent.length,
+          context_count_after: output.context.length,
+          reasons: detection.reasons,
+        });
+      } else {
+        // Level 5: confidence === "none" - no injection, probably not a swarm
+        const totalDuration = Date.now() - startTime;
+        logCompaction("info", "compaction_complete_no_swarm", {
+          session_id: input.sessionID,
+          total_duration_ms: totalDuration,
+          confidence: detection.confidence,
+          context_type: "none",
+          reasons: detection.reasons,
+          context_count_unchanged: output.context.length,
+        });
+      }
+
+      // =======================================================================
+      // LOG: Final output state
+      // =======================================================================
+      logCompaction("debug", "compaction_hook_complete_final_state", {
+        session_id: input.sessionID,
+        output_context_count: output.context?.length ?? 0,
+        output_context_lengths: output.context?.map(c => c.length) ?? [],
+        output_has_prompt: !!(output as any).prompt,
+        output_prompt_length: (output as any).prompt?.length ?? 0,
+        total_duration_ms: Date.now() - startTime,
+      });
+    },
+  };
+};
+
+export default SwarmPlugin;