opencode-swarm-plugin 0.39.1 → 0.40.0

package/bin/swarm.ts

@@ -2548,6 +2548,11 @@ ${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("Eval Commands:")}
   swarm eval status [eval-name]        Show current phase, thresholds, recent scores
@@ -2911,6 +2916,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 +3523,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;

package/dist/compaction-hook.d.ts

@@ -37,8 +37,15 @@
  *
  * 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. Immediate actions (actionable tool calls, postCompactionDiscipline scorer)
+ * 3. Forbidden tools (explicit list, forbiddenToolsPresent scorer)
+ * 4. Role & mandates (strong language, coordinatorIdentity scorer)
+ * 5. 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## \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\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;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,wBAAwB,mwNA2LpC,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"}

package/dist/compaction-observability.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Compaction Hook Observability
+ *
+ * Structured logging, metrics, and queryable history for the pre-compaction hook.
+ *
+ * **Philosophy:** Make the invisible visible. When patterns aren't extracted,
+ * when detection fails, when timing explodes - we need to know WHY.
+ *
+ * @example
+ * ```typescript
+ * const metrics = createMetricsCollector({ session_id: "abc123" });
+ *
+ * recordPhaseStart(metrics, CompactionPhase.DETECT);
+ * // ... detection logic ...
+ * recordPhaseComplete(metrics, CompactionPhase.DETECT, { confidence: "high" });
+ *
+ * recordPatternExtracted(metrics, "epic_state", "Found epic bd-123");
+ *
+ * const summary = getMetricsSummary(metrics);
+ * console.log(`Detected: ${summary.detected}, Confidence: ${summary.confidence}`);
+ * ```
+ */
+/**
+ * Compaction phases - aligned with existing log structure
+ *
+ * From compaction-hook.ts:
+ * - START: session_id, trigger
+ * - GATHER: source (swarm-mail|hive), duration_ms, stats/counts
+ * - DETECT: confidence, detected, reason_count, reasons
+ * - INJECT: confidence, context_length, context_type (full|fallback|none)
+ * - COMPLETE: duration_ms, success, detected, confidence, context_injected
+ */
+export declare enum CompactionPhase {
+    START = "START",
+    GATHER_SWARM_MAIL = "GATHER_SWARM_MAIL",
+    GATHER_HIVE = "GATHER_HIVE",
+    DETECT = "DETECT",
+    INJECT = "INJECT",
+    COMPLETE = "COMPLETE"
+}
+/**
+ * Phase timing and outcome
+ */
+interface PhaseMetrics {
+    duration_ms: number;
+    success: boolean;
+    error?: string;
+    /** Additional phase-specific data */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Pattern extraction record
+ */
+interface PatternRecord {
+    pattern_type: string;
+    reason: string;
+    /** Debug details (only captured if debug mode enabled) */
+    details?: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Compaction metrics collector
+ *
+ * Mutable state object that accumulates metrics during a compaction run.
+ */
+export interface CompactionMetrics {
+    /** Session metadata */
+    session_id?: string;
+    has_sdk_client?: boolean;
+    debug?: boolean;
+    /** Phase timings */
+    phases: Map<CompactionPhase, {
+        start_time: number;
+        end_time?: number;
+        metadata?: Record<string, unknown>;
+        error?: string;
+    }>;
+    /** Pattern extraction tracking */
+    extracted: PatternRecord[];
+    skipped: PatternRecord[];
+    /** Final detection result */
+    confidence?: "high" | "medium" | "low" | "none";
+    detected?: boolean;
+    /** Overall timing */
+    start_time: number;
+    end_time?: number;
+}
+/**
+ * Metrics summary (read-only snapshot)
+ */
+export interface CompactionMetricsSummary {
+    session_id?: string;
+    has_sdk_client?: boolean;
+    /** Phase breakdown */
+    phases: Record<string, PhaseMetrics>;
+    /** Pattern extraction stats */
+    patterns_extracted: number;
+    patterns_skipped: number;
+    extraction_success_rate: number;
+    extracted_patterns: string[];
+    skipped_patterns: string[];
+    /** Detection outcome */
+    confidence?: "high" | "medium" | "low" | "none";
+    detected?: boolean;
+    /** Timing */
+    total_duration_ms: number;
+    /** Debug info (only if debug mode enabled) */
+    debug_info?: Array<{
+        phase: string;
+        pattern: string;
+        details: Record<string, unknown>;
+    }>;
+}
+/**
+ * Create a metrics collector
+ *
+ * @param metadata - Session metadata to capture
+ * @returns Mutable metrics collector
+ */
+export declare function createMetricsCollector(metadata?: {
+    session_id?: string;
+    has_sdk_client?: boolean;
+    debug?: boolean;
+}): CompactionMetrics;
+/**
+ * Record phase start
+ *
+ * @param metrics - Metrics collector
+ * @param phase - Phase being started
+ */
+export declare function recordPhaseStart(metrics: CompactionMetrics, phase: CompactionPhase): void;
+/**
+ * Record phase completion
+ *
+ * @param metrics - Metrics collector
+ * @param phase - Phase being completed
+ * @param result - Phase outcome
+ */
+export declare function recordPhaseComplete(metrics: CompactionMetrics, phase: CompactionPhase, result?: {
+    success?: boolean;
+    error?: string;
+    confidence?: "high" | "medium" | "low" | "none";
+    detected?: boolean;
+    [key: string]: unknown;
+}): void;
+/**
+ * Record an extracted pattern
+ *
+ * @param metrics - Metrics collector
+ * @param pattern_type - Type of pattern extracted (e.g., "epic_state", "agent_name")
+ * @param reason - Human-readable reason for extraction
+ * @param details - Debug details (only captured if debug mode enabled)
+ */
+export declare function recordPatternExtracted(metrics: CompactionMetrics, pattern_type: string, reason: string, details?: Record<string, unknown>): void;
+/**
+ * Record a skipped pattern
+ *
+ * @param metrics - Metrics collector
+ * @param pattern_type - Type of pattern that was skipped
+ * @param reason - Human-readable reason for skipping
+ */
+export declare function recordPatternSkipped(metrics: CompactionMetrics, pattern_type: string, reason: string): void;
+/**
+ * Get metrics summary (read-only snapshot)
+ *
+ * Computes derived metrics like success rates and total duration.
+ *
+ * @param metrics - Metrics collector
+ * @returns Immutable summary
+ */
+export declare function getMetricsSummary(metrics: CompactionMetrics): CompactionMetricsSummary;
+export {};
+//# sourceMappingURL=compaction-observability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compaction-observability.d.ts","sourceRoot":"","sources":["../src/compaction-observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;GASG;AACH,oBAAY,eAAe;IACzB,KAAK,UAAU;IACf,iBAAiB,sBAAsB;IACvC,WAAW,gBAAgB;IAC3B,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,QAAQ,aAAa;CACtB;AAED;;GAEG;AACH,UAAU,YAAY;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,UAAU,aAAa;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,oBAAoB;IACpB,MAAM,EAAE,GAAG,CAAC,eAAe,EAAE;QAC3B,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IAEH,kCAAkC;IAClC,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,OAAO,EAAE,aAAa,EAAE,CAAC;IAEzB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,qBAAqB;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAErC,+BAA+B;IAC/B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,uBAAuB,EAAE,MAAM,CAAC;IAChC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAE3B,wBAAwB;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,aAAa;IACb,iBAAiB,EAAE,MAAM,CAAC;IAE1B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC,CAAC;CACJ;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,iBAAiB,CAUpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,eAAe,GACrB,IAAI,CAIN;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,eAAe,EACtB,MAAM,CAAC,EAAE;IACP,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAChD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,GACA,IAAI,CAmCN;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,iBAAiB,EAC1B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAYN;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,EAC1B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,IAAI,CAMN;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,wBAAwB,CAkDtF"}