opencode-swarm-plugin 0.39.1 → 0.42.0

package/bin/swarm.ts

@@ -2520,6 +2520,8 @@ ${cyan("Commands:")}
   swarm migrate   Migrate PGlite database to libSQL
   swarm cells     List or get cells from database (replaces 'swarm tool hive_query')
   swarm log       View swarm logs with filtering
+  swarm stats     Show swarm health metrics and success rates
+  swarm history   Show recent swarm activity timeline
   swarm eval      Eval-driven development commands
   swarm update    Update to latest version
   swarm version   Show version and banner
@@ -2548,6 +2550,21 @@ ${cyan("Log Viewing:")}
   swarm log --limit <n>                Limit output to n lines (default: 50)
   swarm log --watch, -w                Watch mode - continuously monitor for new logs
   swarm log --interval <ms>            Poll interval in ms (default: 1000, min: 100)
+  swarm log sessions                   List all captured coordinator sessions
+  swarm log sessions <session_id>      View events for a specific session
+  swarm log sessions --latest          View most recent session
+  swarm log sessions --type <type>     Filter by event type (DECISION, VIOLATION, OUTCOME, COMPACTION)
+  swarm log sessions --json            Raw JSON output for jq
+
+${cyan("Stats & History:")}
+  swarm stats                          Show swarm health metrics (last 7 days)
+  swarm stats --since 24h              Show stats for custom time period
+  swarm stats --json                   Output as JSON for scripting
+  swarm history                        Show recent swarms (last 10)
+  swarm history --limit 20             Show more swarms
+  swarm history --status success       Filter by success/failed/in_progress
+  swarm history --strategy file-based  Filter by decomposition strategy
+  swarm history --verbose              Show detailed subtask information
 
 ${cyan("Eval Commands:")}
   swarm eval status [eval-name]        Show current phase, thresholds, recent scores
@@ -2911,6 +2928,298 @@ async function migrate() {
   }
 }
 
+// ============================================================================
+// Session Log Helpers
+// ============================================================================
+
+import type { CoordinatorEvent } from "../src/eval-capture.js";
+
+/**
+ * Parse a session file and return events
+ */
+function parseSessionFile(filePath: string): CoordinatorEvent[] {
+  if (!existsSync(filePath)) {
+    throw new Error(`Session file not found: ${filePath}`);
+  }
+
+  const content = readFileSync(filePath, "utf-8");
+  const lines = content.split("\n").filter((line) => line.trim());
+  const events: CoordinatorEvent[] = [];
+
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      events.push(parsed);
+    } catch {
+      // Skip invalid JSON lines
+    }
+  }
+
+  return events;
+}
+
+/**
+ * List all session files in a directory
+ */
+function listSessionFiles(
+  dir: string,
+): Array<{
+  session_id: string;
+  file_path: string;
+  event_count: number;
+  start_time: string;
+  end_time?: string;
+}> {
+  if (!existsSync(dir)) return [];
+
+  const files = readdirSync(dir).filter((f: string) => f.endsWith(".jsonl"));
+  const sessions: Array<{
+    session_id: string;
+    file_path: string;
+    event_count: number;
+    start_time: string;
+    end_time?: string;
+  }> = [];
+
+  for (const file of files) {
+    const filePath = join(dir, file);
+    try {
+      const events = parseSessionFile(filePath);
+      if (events.length === 0) continue;
+
+      const timestamps = events.map((e) => new Date(e.timestamp).getTime());
+      const startTime = new Date(Math.min(...timestamps)).toISOString();
+      const endTime =
+        timestamps.length > 1
+          ? new Date(Math.max(...timestamps)).toISOString()
+          : undefined;
+
+      sessions.push({
+        session_id: events[0].session_id,
+        file_path: filePath,
+        event_count: events.length,
+        start_time: startTime,
+        end_time: endTime,
+      });
+    } catch {
+      // Skip invalid files
+    }
+  }
+
+  // Sort by start time (newest first)
+  return sessions.sort((a, b) =>
+    new Date(b.start_time).getTime() - new Date(a.start_time).getTime()
+  );
+}
+
+/**
+ * Get the latest session file
+ */
+function getLatestSession(
+  dir: string,
+): {
+  session_id: string;
+  file_path: string;
+  event_count: number;
+  start_time: string;
+  end_time?: string;
+} | null {
+  const sessions = listSessionFiles(dir);
+  return sessions.length > 0 ? sessions[0] : null;
+}
+
+/**
+ * Filter events by type
+ */
+function filterEventsByType(
+  events: CoordinatorEvent[],
+  eventType: string,
+): CoordinatorEvent[] {
+  if (eventType === "all") return events;
+  return events.filter((e) => e.event_type === eventType.toUpperCase());
+}
+
+/**
+ * Filter events by time
+ */
+function filterEventsSince(
+  events: CoordinatorEvent[],
+  sinceMs: number,
+): CoordinatorEvent[] {
+  const cutoffTime = Date.now() - sinceMs;
+  return events.filter((e) =>
+    new Date(e.timestamp).getTime() >= cutoffTime
+  );
+}
+
+/**
+ * Format an event for display
+ */
+function formatEvent(event: CoordinatorEvent, useColor = true): string {
+  const timestamp = new Date(event.timestamp).toLocaleTimeString();
+  const typeColor = useColor
+    ? event.event_type === "VIOLATION"
+      ? red
+      : event.event_type === "OUTCOME"
+      ? green
+      : cyan
+    : (s: string) => s;
+  
+  const type = typeColor(event.event_type.padEnd(12));
+  
+  // Get specific type
+  let specificType = "";
+  if (event.event_type === "DECISION") {
+    specificType = event.decision_type;
+  } else if (event.event_type === "VIOLATION") {
+    specificType = event.violation_type;
+  } else if (event.event_type === "OUTCOME") {
+    specificType = event.outcome_type;
+  } else if (event.event_type === "COMPACTION") {
+    specificType = event.compaction_type;
+  }
+  
+  return `${timestamp} ${type} ${specificType}`;
+}
+
+// ============================================================================
+// Session Log Command
+// ============================================================================
+
+async function logSessions() {
+  const args = process.argv.slice(4); // Skip 'log' and 'sessions'
+  const sessionsDir = join(homedir(), ".config", "swarm-tools", "sessions");
+  
+  // Parse arguments
+  let sessionId: string | null = null;
+  let latest = false;
+  let jsonOutput = false;
+  let eventTypeFilter: string | null = null;
+  let sinceMs: number | null = null;
+  let limit = 100;
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg === "--latest") {
+      latest = true;
+    } else if (arg === "--json") {
+      jsonOutput = true;
+    } else if (arg === "--type" && i + 1 < args.length) {
+      eventTypeFilter = args[++i];
+    } else if (arg === "--since" && i + 1 < args.length) {
+      const duration = parseDuration(args[++i]);
+      if (duration === null) {
+        p.log.error(`Invalid duration format: ${args[i]}`);
+        p.log.message(dim("  Use format: 30s, 5m, 2h, 1d"));
+        process.exit(1);
+      }
+      sinceMs = duration;
+    } else if (arg === "--limit" && i + 1 < args.length) {
+      limit = parseInt(args[++i], 10);
+      if (isNaN(limit) || limit <= 0) {
+        p.log.error(`Invalid limit: ${args[i]}`);
+        process.exit(1);
+      }
+    } else if (!arg.startsWith("--") && !arg.startsWith("-")) {
+      // Positional arg = session ID
+      sessionId = arg;
+    }
+  }
+  
+  // If no args, list sessions
+  if (!sessionId && !latest) {
+    const sessions = listSessionFiles(sessionsDir);
+    
+    if (jsonOutput) {
+      console.log(JSON.stringify({ sessions }, null, 2));
+      return;
+    }
+    
+    if (sessions.length === 0) {
+      p.log.warn("No session files found");
+      p.log.message(dim(`  Expected: ${sessionsDir}/*.jsonl`));
+      return;
+    }
+    
+    console.log(yellow(BANNER));
+    console.log(dim(`  Coordinator Sessions (${sessions.length} total)\n`));
+    
+    // Show sessions table
+    for (const session of sessions) {
+      const startTime = new Date(session.start_time).toLocaleString();
+      const duration = session.end_time
+        ? ((new Date(session.end_time).getTime() - new Date(session.start_time).getTime()) / 1000).toFixed(0) + "s"
+        : "ongoing";
+      
+      console.log(`  ${cyan(session.session_id)}`);
+      console.log(`    ${dim("Started:")} ${startTime}`);
+      console.log(`    ${dim("Events:")}  ${session.event_count}`);
+      console.log(`    ${dim("Duration:")} ${duration}`);
+      console.log();
+    }
+    
+    console.log(dim("  Use --latest to view most recent session"));
+    console.log(dim("  Use <session_id> to view specific session"));
+    console.log();
+    return;
+  }
+  
+  // Get session (either by ID or latest)
+  let session: { session_id: string; file_path: string; event_count: number; start_time: string; end_time?: string; } | null = null;
+  
+  if (latest) {
+    session = getLatestSession(sessionsDir);
+    if (!session) {
+      p.log.error("No sessions found");
+      return;
+    }
+  } else if (sessionId) {
+    // Find session by ID (partial match)
+    const sessions = listSessionFiles(sessionsDir);
+    session = sessions.find(s => s.session_id.includes(sessionId!)) || null;
+    
+    if (!session) {
+      p.log.error(`Session not found: ${sessionId}`);
+      return;
+    }
+  }
+  
+  // Load and filter events
+  let events = parseSessionFile(session!.file_path);
+  
+  if (eventTypeFilter) {
+    events = filterEventsByType(events, eventTypeFilter);
+  }
+  
+  if (sinceMs !== null) {
+    events = filterEventsSince(events, sinceMs);
+  }
+  
+  // Apply limit
+  if (events.length > limit) {
+    events = events.slice(-limit);
+  }
+  
+  // Output
+  if (jsonOutput) {
+    console.log(JSON.stringify({ session_id: session!.session_id, events }, null, 2));
+    return;
+  }
+  
+  console.log(yellow(BANNER));
+  console.log(dim(`  Session: ${session!.session_id}\n`));
+  console.log(`  ${dim("Events:")}  ${events.length}/${session!.event_count}`);
+  if (eventTypeFilter) console.log(`  ${dim("Type:")}    ${eventTypeFilter}`);
+  if (sinceMs !== null) console.log(`  ${dim("Since:")}   ${args[args.indexOf("--since") + 1]}`);
+  console.log();
+  
+  for (const event of events) {
+    console.log("  " + formatEvent(event, true));
+  }
+  console.log();
+}
+
 // ============================================================================
 // Log Command - View swarm logs with filtering
 // ============================================================================
@@ -3226,6 +3535,12 @@ async function cells() {
 async function logs() {
   const args = process.argv.slice(3);
   
+  // Check for 'sessions' subcommand
+  if (args[0] === "sessions") {
+    await logSessions();
+    return;
+  }
+  
   // Parse arguments
   let moduleFilter: string | null = null;
   let levelFilter: number | null = null;
@@ -3710,6 +4025,262 @@ function formatEvalRunResultOutput(result: {
   p.log.message(result.message);
 }
 
+// ============================================================================
+// Stats Command - Swarm Health Metrics
+// ============================================================================
+
+async function stats() {
+	const { getSwarmMailLibSQL } = await import("swarm-mail");
+	const { formatSwarmStats, parseTimePeriod, aggregateByStrategy } = await import(
+		"../src/observability-tools"
+	);
+
+	p.intro("swarm stats");
+
+	// Parse args
+	const args = process.argv.slice(3);
+	let period = "7d"; // default to 7 days
+	let format: "text" | "json" = "text";
+
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--since" || args[i] === "-s") {
+			period = args[i + 1] || "7d";
+			i++;
+		} else if (args[i] === "--json") {
+			format = "json";
+		}
+	}
+
+	try {
+		const projectPath = process.cwd();
+		const swarmMail = await getSwarmMailLibSQL(projectPath);
+		const db = await swarmMail.getDatabase();
+		
+		// Calculate since timestamp
+		const since = parseTimePeriod(period);
+		const periodMatch = period.match(/^(\d+)([dhm])$/);
+		const periodDays = periodMatch ? 
+			(periodMatch[2] === "d" ? Number.parseInt(periodMatch[1]) :
+			 periodMatch[2] === "h" ? Number.parseInt(periodMatch[1]) / 24 :
+			 Number.parseInt(periodMatch[1]) / (24 * 60)) : 7;
+
+		// Query overall stats
+		const overallResult = await db.query(
+			`SELECT 
+				COUNT(DISTINCT json_extract(data, '$.epic_id')) as total_swarms,
+				SUM(CASE WHEN json_extract(data, '$.success') = 'true' THEN 1 ELSE 0 END) as successes,
+				COUNT(*) as total_outcomes,
+				CAST(AVG(CAST(json_extract(data, '$.duration_ms') AS REAL)) / 60000 AS REAL) as avg_duration_min
+			FROM events
+			WHERE type = 'subtask_outcome'
+				AND timestamp >= ?`,
+			[since],
+		);
+
+		const overall = overallResult.rows[0] as {
+			total_swarms: number;
+			successes: number;
+			total_outcomes: number;
+			avg_duration_min: number;
+		} || { total_swarms: 0, successes: 0, total_outcomes: 0, avg_duration_min: 0 };
+
+		// Query strategy breakdown
+		const strategyResult = await db.query(
+			`SELECT 
+				json_extract(data, '$.strategy') as strategy,
+				json_extract(data, '$.success') as success
+			FROM events
+			WHERE type = 'subtask_outcome'
+				AND timestamp >= ?`,
+			[since],
+		);
+
+		const strategies = aggregateByStrategy(
+			(strategyResult.rows as Array<{ strategy: string | null; success: string }>).map(
+				(row) => ({
+					strategy: row.strategy,
+					success: row.success === "true",
+				}),
+			),
+		);
+
+		// Query coordinator stats from sessions
+		const sessionsPath = join(
+			homedir(),
+			".config",
+			"swarm-tools",
+			"sessions",
+		);
+		let coordinatorStats = {
+			violationRate: 0,
+			spawnEfficiency: 0,
+			reviewThoroughness: 0,
+		};
+
+		if (existsSync(sessionsPath)) {
+			const sessionFiles = readdirSync(sessionsPath).filter(
+				(f) => f.endsWith(".jsonl") && statSync(join(sessionsPath, f)).mtimeMs >= since,
+			);
+
+			let totalViolations = 0;
+			let totalSpawns = 0;
+			let totalReviews = 0;
+			let totalSwarms = 0;
+
+			for (const file of sessionFiles) {
+				try {
+					const content = readFileSync(join(sessionsPath, file), "utf-8");
+					const lines = content.trim().split("\n");
+
+					let violations = 0;
+					let spawns = 0;
+					let reviews = 0;
+
+					for (const line of lines) {
+						try {
+							const event = JSON.parse(line);
+							if (event.type === "VIOLATION") violations++;
+							if (event.type === "DECISION" && event.action === "spawn") spawns++;
+							if (event.type === "DECISION" && event.action === "review") reviews++;
+						} catch {
+							// Skip invalid lines
+						}
+					}
+
+					if (spawns > 0 || violations > 0) {
+						totalViolations += violations;
+						totalSpawns += spawns;
+						totalReviews += reviews;
+						totalSwarms++;
+					}
+				} catch {
+					// Skip unreadable files
+				}
+			}
+
+			coordinatorStats = {
+				violationRate: totalSwarms > 0 ? (totalViolations / totalSwarms) * 100 : 0,
+				spawnEfficiency: totalSwarms > 0 ? (totalSpawns / totalSwarms) * 100 : 0,
+				reviewThoroughness: totalSpawns > 0 ? (totalReviews / totalSpawns) * 100 : 0,
+			};
+		}
+
+		// Build stats data
+		const stats = {
+			overall: {
+				totalSwarms: overall.total_swarms,
+				successRate:
+					overall.total_outcomes > 0
+						? (overall.successes / overall.total_outcomes) * 100
+						: 0,
+				avgDurationMin: overall.avg_duration_min || 0,
+			},
+			byStrategy: strategies,
+			coordinator: coordinatorStats,
+			recentDays: Math.round(periodDays * 10) / 10,
+		};
+
+		// Output
+		if (format === "json") {
+			console.log(JSON.stringify(stats, null, 2));
+		} else {
+			console.log();
+			console.log(formatSwarmStats(stats));
+			console.log();
+		}
+
+		p.outro("Stats ready!");
+	} catch (error) {
+		p.log.error(error instanceof Error ? error.message : String(error));
+		p.outro("Failed to load stats");
+		process.exit(1);
+	}
+}
+
+// ============================================================================
+// History Command
+// ============================================================================
+
+async function swarmHistory() {
+	const {
+		querySwarmHistory,
+		formatSwarmHistory,
+	} = await import("../src/observability-tools.js");
+
+	p.intro("swarm history");
+
+	// Parse args
+	const args = process.argv.slice(3);
+	let limit = 10;
+	let status: "success" | "failed" | "in_progress" | undefined;
+	let strategy: "file-based" | "feature-based" | "risk-based" | undefined;
+	let verbose = false;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+
+		if (arg === "--limit" || arg === "-n") {
+			const limitStr = args[i + 1];
+			if (limitStr && !Number.isNaN(Number(limitStr))) {
+				limit = Number(limitStr);
+				i++;
+			}
+		} else if (arg === "--status") {
+			const statusStr = args[i + 1];
+			if (
+				statusStr &&
+				["success", "failed", "in_progress"].includes(statusStr)
+			) {
+				status = statusStr as "success" | "failed" | "in_progress";
+				i++;
+			}
+		} else if (arg === "--strategy") {
+			const strategyStr = args[i + 1];
+			if (
+				strategyStr &&
+				["file-based", "feature-based", "risk-based"].includes(strategyStr)
+			) {
+				strategy = strategyStr as "file-based" | "feature-based" | "risk-based";
+				i++;
+			}
+		} else if (arg === "--verbose" || arg === "-v") {
+			verbose = true;
+		}
+	}
+
+	try {
+		const projectPath = process.cwd();
+		const records = await querySwarmHistory(projectPath, {
+			limit,
+			status,
+			strategy,
+		});
+
+		console.log();
+		console.log(formatSwarmHistory(records));
+		console.log();
+
+		if (verbose && records.length > 0) {
+			console.log("Details:");
+			for (const record of records) {
+				console.log(
+					`  ${record.epic_id}: ${record.epic_title} (${record.strategy})`,
+				);
+				console.log(
+					`    Tasks: ${record.completed_count}/${record.task_count}, Success: ${record.overall_success ? "✅" : "❌"}`,
+				);
+			}
+			console.log();
+		}
+
+		p.outro("History ready!");
+	} catch (error) {
+		p.log.error(error instanceof Error ? error.message : String(error));
+		p.outro("Failed to load history");
+		process.exit(1);
+	}
+}
+
 // ============================================================================
 // Eval Command
 // ============================================================================
@@ -3971,6 +4542,12 @@ switch (command) {
   case "logs":
     await logs();
     break;
+  case "stats":
+    await stats();
+    break;
+  case "history":
+    await swarmHistory();
+    break;
   case "eval":
     await evalCommand();
     break;

package/dist/compaction-hook.d.ts

@@ -37,8 +37,17 @@
  *
  * This is NOT about preserving state for a human - it's about the swarm continuing
  * autonomously after context compression.
+ *
+ * Structure optimized for eval scores:
+ * 1. ASCII header (visual anchor, coordinatorIdentity scorer)
+ * 2. What Good Looks Like (behavioral examples, outcome-focused)
+ * 3. Immediate actions (actionable tool calls, postCompactionDiscipline scorer)
+ * 4. Forbidden tools (explicit list, forbiddenToolsPresent scorer)
+ * 5. Mandatory behaviors (inbox, skills, review)
+ * 6. Role & mandates (strong language, coordinatorIdentity scorer)
+ * 7. Reference sections (supporting material)
  */
-export declare const SWARM_COMPACTION_CONTEXT = "\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                                                             \u2502\n\u2502             \uD83D\uDC1D  YOU ARE THE COORDINATOR  \uD83D\uDC1D                 \u2502\n\u2502                                                             \u2502\n\u2502             NOT A WORKER. NOT AN IMPLEMENTER.               \u2502\n\u2502                  YOU ORCHESTRATE.                           \u2502\n\u2502                                                             \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n## \uD83C\uDFAF NON-NEGOTIABLE: YOU ARE THE COORDINATOR\n\nContext was compacted but the swarm is still running. **YOU ARE THE COORDINATOR.**\n\nYour role is ORCHESTRATION, not implementation. When you catch yourself about to do work directly, STOP.\n\n### \u26D4 NEVER DO THESE (Coordinator Anti-Patterns)\n\n**CRITICAL: Coordinators NEVER do implementation work. ALWAYS spawn workers.**\n\n- \u274C **NEVER** use `edit` or `write` tools - SPAWN A WORKER\n- \u274C **NEVER** run tests with `bash` - SPAWN A WORKER  \n- \u274C **NEVER** implement features yourself - SPAWN A WORKER\n- \u274C **NEVER** \"just do it myself to save time\" - NO. SPAWN A WORKER.\n- \u274C **NEVER** reserve files with `swarmmail_reserve` - Workers reserve files\n- \u274C **NEVER** fetch files/docs directly - SPAWN A RESEARCHER\n\n**If you catch yourself about to edit a file, STOP. Use `swarm_spawn_subtask` instead.**\n\n### \uD83D\uDEAB FORBIDDEN TOOLS (Coordinators MUST delegate these)\n\n**NEVER use these tools directly. ALWAYS spawn a researcher worker via `swarm_spawn_researcher`:**\n\n**Repository fetching:**\n- `repo-crawl_file`, `repo-crawl_readme`, `repo-crawl_search`, `repo-crawl_structure`, `repo-crawl_tree`\n- `repo-autopsy_*` (all repo-autopsy tools)\n\n**Web/documentation fetching:**\n- `webfetch`, `fetch_fetch`\n- `context7_resolve-library-id`, `context7_get-library-docs`\n\n**Knowledge base:**\n- `pdf-brain_search`, `pdf-brain_read`\n\n**If you need external data:** Use `swarm_spawn_researcher` with a clear research task. The researcher will fetch, summarize, and return findings.\n\n### \u2705 ALWAYS DO THESE (Coordinator Checklist)\n\nOn resume, execute this checklist IN ORDER:\n\n1. `swarm_status(epic_id=\"<epic>\", project_key=\"<path>\")` - Get current state\n2. `swarmmail_inbox(limit=5)` - Check for agent messages\n3. For completed work: `swarm_review` \u2192 `swarm_review_feedback`\n4. For open subtasks: `swarm_spawn_subtask` (NOT \"do it yourself\")\n5. For blocked work: Investigate, unblock, reassign\n\n### Preserve in Summary\n\nExtract from session context:\n\n1. **Epic & Subtasks** - IDs, titles, status, file assignments\n2. **What's Running** - Which agents are active, what they're working on  \n3. **What's Blocked** - Blockers and what's needed to unblock\n4. **What's Done** - Completed work and any follow-ups needed\n5. **What's Next** - Pending subtasks ready to spawn\n\n### Summary Format\n\n```\n## \uD83D\uDC1D Swarm State\n\n**Epic:** <cell-xxx> - <title>\n**Project:** <path>\n**Progress:** X/Y subtasks complete\n\n**Active:**\n- <cell-xxx>: <title> [in_progress] \u2192 <agent> working on <files>\n\n**Blocked:**\n- <cell-xxx>: <title> - BLOCKED: <reason>\n\n**Completed:**\n- <cell-xxx>: <title> \u2713\n\n**Ready to Spawn:**\n- <cell-xxx>: <title> (files: <...>)\n```\n\n### Your Role\n\n- **Spawn aggressively** - If a subtask is ready and unblocked, spawn an agent\n- **Monitor actively** - Check status, read messages, respond to blockers\n- **Review work** - Use `swarm_review` and `swarm_review_feedback` for completed work\n- **Close the loop** - When all subtasks done, verify and close the epic\n\n**You are the COORDINATOR. You orchestrate. You do NOT implement. Spawn workers.**\n\n---\n\n## \uD83D\uDCCB FULL COORDINATOR WORKFLOW (Reference)\n\nYou are ALWAYS swarming. Here is the complete workflow for any new work:\n\n### Phase 1.5: Research Phase (FOR COMPLEX TASKS)\n\n**If the task requires understanding unfamiliar technologies, spawn a researcher FIRST:**\n\n```\nswarm_spawn_researcher(\n  research_id=\"research-<topic>\",\n  epic_id=\"<epic-id>\",\n  tech_stack=[\"<technology>\"],\n  project_path=\"<path>\"\n)\n// Then spawn with Task(subagent_type=\"swarm/researcher\", prompt=\"<from above>\")\n```\n\n### Phase 2: Knowledge Gathering\n\n```\nsemantic-memory_find(query=\"<task keywords>\", limit=5)   # Past learnings\ncass_search(query=\"<task description>\", limit=5)         # Similar past tasks  \nskills_list()                                            # Available skills\n```\n\n### Phase 3: Decompose\n\n```\nswarm_select_strategy(task=\"<task>\")\nswarm_plan_prompt(task=\"<task>\", context=\"<synthesized knowledge>\")\nswarm_validate_decomposition(response=\"<CellTree JSON>\")\n```\n\n### Phase 4: Create Cells\n\n`hive_create_epic(epic_title=\"<task>\", subtasks=[...])`\n\n### Phase 5: DO NOT Reserve Files\n\n> **\u26A0\uFE0F Coordinator NEVER reserves files.** Workers reserve their own files.\n\n### Phase 6: Spawn Workers\n\n```\nswarm_spawn_subtask(bead_id, epic_id, title, files, shared_context, project_path)\nTask(subagent_type=\"swarm/worker\", prompt=\"<from above>\")\n```\n\n### Phase 7: MANDATORY Review Loop\n\n**AFTER EVERY Task() RETURNS:**\n\n1. `swarmmail_inbox()` - Check for messages\n2. `swarm_review(project_key, epic_id, task_id, files_touched)` - Generate review\n3. Evaluate against epic goals\n4. `swarm_review_feedback(project_key, task_id, worker_id, status, issues)`\n\n**If needs_changes:**\n```\nswarm_spawn_retry(bead_id, epic_id, original_prompt, attempt, issues, diff, files, project_path)\n// Spawn NEW worker with Task() using retry prompt\n// Max 3 attempts before marking task blocked\n```\n\n### Phase 8: Complete\n\n`hive_sync()` - Sync all cells to git\n\n## Strategy Reference\n\n| Strategy       | Best For                 | Keywords                               |\n| -------------- | ------------------------ | -------------------------------------- |\n| file-based     | Refactoring, migrations  | refactor, migrate, rename, update all  |\n| feature-based  | New features             | add, implement, build, create, feature |\n| risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent   |\n\n**You are the COORDINATOR. You orchestrate. You do NOT implement. Spawn workers.**\n";
+export declare const SWARM_COMPACTION_CONTEXT = "\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502                                                             \u2502\n\u2502             \uD83D\uDC1D  YOU ARE THE COORDINATOR  \uD83D\uDC1D                 \u2502\n\u2502                                                             \u2502\n\u2502             NOT A WORKER. NOT AN IMPLEMENTER.               \u2502\n\u2502                  YOU ORCHESTRATE.                           \u2502\n\u2502                                                             \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\nContext was compacted but the swarm is still running. **YOU ARE THE COORDINATOR.**\n\nYour role is ORCHESTRATION, not implementation. The resume steps above (if present) tell you exactly what to do first.\n\n---\n\n## \uD83C\uDFAF WHAT GOOD LOOKS LIKE (Behavioral Examples)\n\n**\u2705 GOOD Coordinator Behavior:**\n- Spawned researcher for unfamiliar tech \u2192 got summary \u2192 stored in semantic-memory\n- Loaded `skills_use(name=\"testing-patterns\")` BEFORE spawning test workers\n- Checked `swarmmail_inbox()` every 5-10 minutes \u2192 caught blocked worker \u2192 unblocked in 2min\n- Delegated planning to swarm/planner subagent \u2192 main context stayed clean\n- Workers reserved their OWN files \u2192 no conflicts\n- Reviewed all worker output with `swarm_review` \u2192 caught integration issue before merge\n\n**\u274C COMMON MISTAKES (Avoid These):**\n- Called context7/pdf-brain directly \u2192 dumped 50KB into thread \u2192 context exhaustion\n- Skipped skill loading \u2192 workers reinvented patterns already in skills\n- Never checked inbox \u2192 worker stuck 25 minutes \u2192 silent failure\n- Reserved files as coordinator \u2192 workers blocked \u2192 swarm stalled\n- Closed cells when workers said \"done\" \u2192 skipped review \u2192 shipped broken code\n\n---\n\n## \uD83D\uDEAB FORBIDDEN TOOLS (NEVER Use These Directly)\n\nCoordinators do NOT do implementation work. These tools are **FORBIDDEN**:\n\n### File Modification (ALWAYS spawn workers instead)\n- `Edit` - SPAWN A WORKER\n- `Write` - SPAWN A WORKER\n- `bash` (for file modifications) - SPAWN A WORKER\n- `swarmmail_reserve` - Workers reserve their own files\n- `git commit` - Workers commit their own changes\n\n### External Data Fetching (SPAWN A RESEARCHER instead)\n\n**Repository fetching:**\n- `repo-crawl_file`, `repo-crawl_readme`, `repo-crawl_search`, `repo-crawl_structure`, `repo-crawl_tree`\n- `repo-autopsy_*` (all repo-autopsy tools)\n\n**Web/documentation fetching:**\n- `webfetch`, `fetch_fetch`\n- `context7_resolve-library-id`, `context7_get-library-docs`\n\n**Knowledge base:**\n- `pdf-brain_search`, `pdf-brain_read`\n\n**Instead:** Use `swarm_spawn_researcher` with a clear research task. The researcher will fetch, summarize, and return findings.\n\n---\n\n## \uD83D\uDCBC YOUR ROLE (Non-Negotiable)\n\nYou are the **COORDINATOR**. Your job is ORCHESTRATION, not implementation.\n\n### What Coordinators Do:\n- \u2705 Spawn workers for implementation tasks\n- \u2705 Monitor worker progress via `swarm_status` and `swarmmail_inbox`\n- \u2705 Review completed work with `swarm_review`\n- \u2705 Unblock dependencies and resolve conflicts\n- \u2705 Close the loop when epics complete\n\n### What Coordinators NEVER Do:\n- \u274C **NEVER** edit or write files directly\n- \u274C **NEVER** run tests with `bash`\n- \u274C **NEVER** \"just do it myself to save time\"\n- \u274C **NEVER** reserve files (workers reserve)\n- \u274C **NEVER** fetch external data directly (spawn researchers)\n\n**If you catch yourself about to edit a file, STOP. Use `swarm_spawn_subtask` instead.**\n\n### Strong Mandates:\n- **ALWAYS** spawn workers for implementation tasks\n- **ALWAYS** check status and inbox before decisions\n- **ALWAYS** review worker output before accepting\n- **NON-NEGOTIABLE:** You orchestrate. You do NOT implement.\n\n---\n\n## \uD83D\uDCCB MANDATORY BEHAVIORS (Post-Compaction Checklist)\n\n### 1. Inbox Monitoring (EVERY 5-10 MINUTES)\n```\nswarmmail_inbox(limit=5)           # Check for messages\nswarmmail_read_message(message_id=N)  # Read urgent ones\nswarm_status(epic_id, project_key)    # Overall progress\n```\n**Intervention triggers:** Worker blocked >5min, file conflict, scope creep\n\n### 2. Skill Loading (BEFORE spawning workers)\n```\nskills_use(name=\"swarm-coordination\")  # ALWAYS for swarms\nskills_use(name=\"testing-patterns\")    # If task involves tests\nskills_use(name=\"system-design\")       # If architectural decisions\n```\n**Include skill recommendations in shared_context for workers.**\n\n### 3. Worker Review (AFTER EVERY worker returns)\n```\nswarm_review(project_key, epic_id, task_id, files_touched)\n# Evaluate: Does it fulfill requirements? Enable downstream tasks? Type safe?\nswarm_review_feedback(project_key, task_id, worker_id, status, issues)\n```\n**3-Strike Rule:** After 3 rejections \u2192 mark blocked \u2192 escalate to human.\n\n### 4. Research Spawning (For unfamiliar tech)\n```\nTask(subagent_type=\"swarm-researcher\", prompt=\"Research <topic>...\")\n```\n**NEVER call context7, pdf-brain, webfetch directly.** Spawn a researcher.\n\n---\n\n## \uD83D\uDCDD SUMMARY FORMAT (Preserve This State)\n\nWhen compaction occurs, extract and preserve this structure:\n\n```\n## \uD83D\uDC1D Swarm State\n\n**Epic:** CELL_ID - TITLE\n**Project:** PROJECT_PATH\n**Progress:** X/Y subtasks complete\n\n**Active:**\n- CELL_ID: TITLE [in_progress] \u2192 AGENT working on FILES\n\n**Blocked:**\n- CELL_ID: TITLE - BLOCKED: REASON\n\n**Completed:**\n- CELL_ID: TITLE \u2713\n\n**Ready to Spawn:**\n- CELL_ID: TITLE (files: FILES)\n```\n\n### What to Extract:\n1. **Epic & Subtasks** - IDs, titles, status, file assignments\n2. **What's Running** - Active agents and their current work\n3. **What's Blocked** - Blockers and what's needed to unblock\n4. **What's Done** - Completed work and follow-ups\n5. **What's Next** - Pending subtasks ready to spawn\n\n---\n\n## \uD83D\uDCCB REFERENCE: Full Coordinator Workflow\n\nYou are ALWAYS swarming. Use this workflow for any new work:\n\n### Phase 1.5: Research (For Complex Tasks)\n\nIf the task requires unfamiliar technologies, spawn a researcher FIRST:\n\n```\nswarm_spawn_researcher(\n  research_id=\"research-TOPIC\",\n  epic_id=\"mjkw...\",  # your epic ID\n  tech_stack=[\"TECHNOLOGY\"],\n  project_path=\"PROJECT_PATH\"\n)\n// Then spawn with Task(subagent_type=\"swarm/researcher\", prompt=\"...\")\n```\n\n### Phase 2: Knowledge Gathering\n\n```\nsemantic-memory_find(query=\"TASK_KEYWORDS\", limit=5)   # Past learnings\ncass_search(query=\"TASK_DESCRIPTION\", limit=5)         # Similar past tasks\nskills_list()                                          # Available skills\n```\n\n### Phase 3: Decompose\n\n```\nswarm_select_strategy(task=\"TASK\")\nswarm_plan_prompt(task=\"TASK\", context=\"KNOWLEDGE\")\nswarm_validate_decomposition(response=\"CELLTREE_JSON\")\n```\n\n### Phase 4: Create Cells\n\n`hive_create_epic(epic_title=\"TASK\", subtasks=[...])`\n\n### Phase 5: File Reservations\n\n> **\u26A0\uFE0F Coordinator NEVER reserves files.** Workers reserve their own files with `swarmmail_reserve`.\n\n### Phase 6: Spawn Workers\n\n```\nswarm_spawn_subtask(bead_id, epic_id, title, files, shared_context, project_path)\nTask(subagent_type=\"swarm/worker\", prompt=\"GENERATED_PROMPT\")\n```\n\n### Phase 7: Review Loop (MANDATORY)\n\n**AFTER EVERY Task() RETURNS:**\n\n1. `swarmmail_inbox()` - Check for messages\n2. `swarm_review(project_key, epic_id, task_id, files_touched)` - Generate review\n3. Evaluate against epic goals\n4. `swarm_review_feedback(project_key, task_id, worker_id, status, issues)`\n\n**If needs_changes:**\n```\nswarm_spawn_retry(bead_id, epic_id, original_prompt, attempt, issues, diff, files, project_path)\n// Spawn NEW worker with Task() using retry prompt\n// Max 3 attempts before marking task blocked\n```\n\n### Phase 8: Complete\n\n`hive_sync()` - Sync all cells to git\n\n---\n\n## \uD83D\uDCCA REFERENCE: Decomposition Strategies\n\n| Strategy       | Best For                 | Keywords                               |\n| -------------- | ------------------------ | -------------------------------------- |\n| file-based     | Refactoring, migrations  | refactor, migrate, rename, update all  |\n| feature-based  | New features             | add, implement, build, create, feature |\n| risk-based     | Bug fixes, security      | fix, bug, security, critical, urgent   |\n\n---\n\n**You are the COORDINATOR. You orchestrate. You do NOT implement. Spawn workers.**\n";
 /**
  * Fallback detection prompt - tells the compactor what to look for
  *

package/dist/compaction-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../src/compaction-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA+BH;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,w6NAiLpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,0nCAiCpC,CAAC;AAqFF;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,GAAG,CACX,MAAM,EACN;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CACrE,CAAC;IACF,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAY,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAgJ5B;AAoVD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,cAAc,IAExD,OAAO;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC5B,QAAQ;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,KAC5B,OAAO,CAAC,IAAI,CAAC,CA4HjB"}
+{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../src/compaction-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAwCH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,0jSAgPpC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,0nCAiCpC,CAAC;AA2FF;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,GAAG,CACX,MAAM,EACN;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CACrE,CAAC;IACF,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAY,GAClB,OAAO,CAAC,iBAAiB,CAAC,CAgJ5B;AAwVD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,cAAc,IAExD,OAAO;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC5B,QAAQ;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,KAC5B,OAAO,CAAC,IAAI,CAAC,CAqLjB"}