opencode-swarm-plugin 0.27.2 → 0.27.4

package/.turbo/turbo-build.log

@@ -1,9 +1,9 @@
 $ bun build ./src/index.ts --outdir ./dist --target node --external @electric-sql/pglite --external swarm-mail && bun build ./src/plugin.ts --outfile ./dist/plugin.js --target node --external @electric-sql/pglite --external swarm-mail && tsc
-Bundled 200 modules in 36ms
+Bundled 200 modules in 35ms
 
   index.js  1.19 MB  (entry point)
 
-Bundled 201 modules in 35ms
+Bundled 201 modules in 33ms
 
   plugin.js  1.16 MB  (entry point)
 

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # opencode-swarm-plugin
 
+## 0.27.4
+
+### Patch Changes
+
+- [`f23f774`](https://github.com/joelhooks/swarm-tools/commit/f23f774e4b83a3422d8266b6b1ad083daaec03e2) Thanks [@joelhooks](https://github.com/joelhooks)! - Enforce coordinator always spawns workers, never executes work directly
+
+  - Added "Coordinator Role Boundaries" section to /swarm command
+  - Coordinators now explicitly forbidden from editing code, running tests, or making "quick fixes"
+  - Updated Phase 5 to clarify coordinators NEVER reserve files (workers do)
+  - Updated Phase 6 with patterns for both parallel and sequential worker spawning
+  - Worker agent template now confirms it was spawned correctly and to report coordinator violations
+
+## 0.27.3
+
+### Patch Changes
+
+- [`ec23d25`](https://github.com/joelhooks/swarm-tools/commit/ec23d25aeca667c0294a6255fecf11dd7d7fd6b3) Thanks [@joelhooks](https://github.com/joelhooks)! - Add .beads → .hive directory migration support
+
+  - Fix migration version collision: beadsMigration now v7, cellsViewMigration now v8 (was conflicting with streams v6)
+  - Add `checkBeadsMigrationNeeded()` to detect legacy .beads directories
+  - Add `migrateBeadsToHive()` to rename .beads to .hive
+  - Add `ensureHiveDirectory()` to create .hive if missing (called by hive_sync)
+  - Update hive_sync to ensure .hive directory exists before writing
+  - Add migration prompt to `swarm setup` CLI flow
+
+- Updated dependencies [[`ec23d25`](https://github.com/joelhooks/swarm-tools/commit/ec23d25aeca667c0294a6255fecf11dd7d7fd6b3)]:
+  - swarm-mail@0.3.3
+
 ## 0.27.2
 
 ### Patch Changes

package/bin/swarm.ts

@@ -27,6 +27,10 @@ import {
 import { homedir } from "os";
 import { basename, dirname, join } from "path";
 import { fileURLToPath } from "url";
+import {
+  checkBeadsMigrationNeeded,
+  migrateBeadsToHive,
+} from "../src/hive";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(
@@ -851,6 +855,37 @@ You are a swarm coordinator. Your job is to clarify the task, decompose it into
 
 $ARGUMENTS
 
+## CRITICAL: Coordinator Role Boundaries
+
+**⚠️ COORDINATORS NEVER EXECUTE WORK DIRECTLY**
+
+Your role is **ONLY** to:
+1. **Clarify** - Ask questions to understand scope
+2. **Decompose** - Break into subtasks with clear boundaries  
+3. **Spawn** - Create worker agents for ALL subtasks
+4. **Monitor** - Check progress, unblock, mediate conflicts
+5. **Verify** - Confirm completion, run final checks
+
+**YOU DO NOT:**
+- Read implementation files (only metadata/structure for planning)
+- Edit code directly
+- Run tests yourself (workers run tests)
+- Implement features
+- Fix bugs inline
+- Make "quick fixes" yourself
+
+**ALWAYS spawn workers, even for sequential tasks.** Sequential just means spawn them in order and wait for each to complete before spawning the next.
+
+### Why This Matters
+
+| Coordinator Work | Worker Work | Consequence of Mixing |
+|-----------------|-------------|----------------------|
+| Sonnet context ($$$) | Disposable context | Expensive context waste |
+| Long-lived state | Task-scoped state | Context exhaustion |
+| Orchestration concerns | Implementation concerns | Mixed concerns |
+| No checkpoints | Checkpoints enabled | No recovery |
+| No learning signals | Outcomes tracked | No improvement |
+
 ## Workflow
 
 ### Phase 0: Socratic Planning (INTERACTIVE - unless --fast)
@@ -919,15 +954,39 @@ swarm_validate_decomposition(response="<CellTree JSON>")
 ### Phase 4: Create Beads
 \`hive_create_epic(epic_title="<task>", subtasks=[...])\`
 
-### Phase 5: Reserve Files
-\`swarmmail_reserve(paths=[...], reason="<bead-id>: <desc>")\`
+### Phase 5: DO NOT Reserve Files
+
+> **⚠️ Coordinator NEVER reserves files.** Workers reserve their own files.
+> If coordinator reserves, workers get blocked and swarm stalls.
 
-### Phase 6: Spawn Agents (ALL in single message)
+### Phase 6: Spawn Workers for ALL Subtasks (MANDATORY)
+
+> **⚠️ ALWAYS spawn workers, even for sequential tasks.**
+> - Parallel tasks: Spawn ALL in a single message
+> - Sequential tasks: Spawn one, wait for completion, spawn next
+
+**For parallel work:**
 \`\`\`
-swarm_spawn_subtask(bead_id, epic_id, subtask_title, files, shared_context, project_path="$PWD")
+// Single message with multiple Task calls
+swarm_spawn_subtask(bead_id_1, epic_id, title_1, files_1, shared_context, project_path="$PWD")
+Task(subagent_type="swarm/worker", prompt="<from above>")
+swarm_spawn_subtask(bead_id_2, epic_id, title_2, files_2, shared_context, project_path="$PWD")
 Task(subagent_type="swarm/worker", prompt="<from above>")
 \`\`\`
 
+**For sequential work:**
+\`\`\`
+// Spawn worker 1, wait for completion
+swarm_spawn_subtask(bead_id_1, ...)
+const result1 = await Task(subagent_type="swarm/worker", prompt="<from above>")
+
+// THEN spawn worker 2 with context from worker 1
+swarm_spawn_subtask(bead_id_2, ..., shared_context="Worker 1 completed: " + result1)
+const result2 = await Task(subagent_type="swarm/worker", prompt="<from above>")
+\`\`\`
+
+**NEVER do the work yourself.** Even if it seems faster, spawn a worker.
+
 **IMPORTANT:** Pass \`project_path\` to \`swarm_spawn_subtask\` so workers can call \`swarmmail_init\`.
 
 ### Phase 7: Monitor
@@ -1031,6 +1090,12 @@ model: ${model}
 
 You are a swarm worker agent. Your prompt contains a **MANDATORY SURVIVAL CHECKLIST** - follow it IN ORDER.
 
+## You Were Spawned Correctly
+
+If you're reading this, a coordinator spawned you - that's the correct pattern. Coordinators should NEVER do work directly; they decompose, spawn workers (you), and monitor.
+
+**If you ever see a coordinator editing code or running tests directly, that's a bug.** Report it.
+
 ## CRITICAL: Read Your Prompt Carefully
 
 Your Task prompt contains detailed instructions including:
@@ -1490,6 +1555,45 @@ async function setup() {
     }
   }
 
+  // Check for .beads → .hive migration
+  const cwd = process.cwd();
+  const migrationCheck = checkBeadsMigrationNeeded(cwd);
+  if (migrationCheck.needed) {
+    p.log.step("Legacy .beads directory detected");
+    p.log.message(dim("  Found: " + migrationCheck.beadsPath));
+    
+    const shouldMigrate = await p.confirm({
+      message: "Migrate .beads to .hive? (recommended)",
+      initialValue: true,
+    });
+
+    if (p.isCancel(shouldMigrate)) {
+      p.cancel("Setup cancelled");
+      process.exit(0);
+    }
+
+    if (shouldMigrate) {
+      const migrateSpinner = p.spinner();
+      migrateSpinner.start("Migrating .beads to .hive...");
+      
+      try {
+        const result = await migrateBeadsToHive(cwd);
+        if (result.migrated) {
+          migrateSpinner.stop("Migration complete");
+          p.log.success("Renamed .beads/ → .hive/");
+        } else {
+          migrateSpinner.stop("Migration skipped");
+          p.log.warn(result.reason || "Unknown reason");
+        }
+      } catch (error) {
+        migrateSpinner.stop("Migration failed");
+        p.log.error(error instanceof Error ? error.message : String(error));
+      }
+    } else {
+      p.log.warn("Skipping migration - .beads will continue to work but is deprecated");
+    }
+  }
+
   // Model selection
   p.log.step("Configure swarm agents...");
 

package/dist/hive.d.ts

@@ -32,6 +32,54 @@ export declare class HiveValidationError extends Error {
     constructor(message: string, zodError: z.ZodError);
 }
 export declare const BeadValidationError: typeof HiveValidationError;
+/**
+ * Result of checking if .beads → .hive migration is needed
+ */
+export interface MigrationCheckResult {
+    /** Whether migration is needed */
+    needed: boolean;
+    /** Path to .beads directory if it exists */
+    beadsPath?: string;
+}
+/**
+ * Result of migrating .beads → .hive
+ */
+export interface MigrationResult {
+    /** Whether migration was performed */
+    migrated: boolean;
+    /** Reason if migration was skipped */
+    reason?: string;
+}
+/**
+ * Check if .beads → .hive migration is needed
+ *
+ * Migration is needed when:
+ * - .beads directory exists
+ * - .hive directory does NOT exist
+ *
+ * @param projectPath - Absolute path to the project root
+ * @returns MigrationCheckResult indicating if migration is needed
+ */
+export declare function checkBeadsMigrationNeeded(projectPath: string): MigrationCheckResult;
+/**
+ * Migrate .beads directory to .hive
+ *
+ * This function renames .beads to .hive. It should only be called
+ * after user confirmation via CLI prompt.
+ *
+ * @param projectPath - Absolute path to the project root
+ * @returns MigrationResult indicating success or skip reason
+ */
+export declare function migrateBeadsToHive(projectPath: string): Promise<MigrationResult>;
+/**
+ * Ensure .hive directory exists
+ *
+ * Creates .hive directory if it doesn't exist. This is idempotent
+ * and safe to call multiple times.
+ *
+ * @param projectPath - Absolute path to the project root
+ */
+export declare function ensureHiveDirectory(projectPath: string): void;
 /**
  * Get or create a HiveAdapter instance for a project
  * Exported for testing - allows tests to verify state directly

package/dist/hive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hive.d.ts","sourceRoot":"","sources":["../src/hive.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hive.d.ts","sourceRoot":"","sources":["../src/hive.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -27741,6 +27741,43 @@ class HiveValidationError extends Error {
   }
 }
 var BeadValidationError = HiveValidationError;
+function checkBeadsMigrationNeeded(projectPath) {
+  const beadsDir = join(projectPath, ".beads");
+  const hiveDir = join(projectPath, ".hive");
+  if (existsSync(hiveDir)) {
+    return { needed: false };
+  }
+  if (existsSync(beadsDir)) {
+    return { needed: true, beadsPath: beadsDir };
+  }
+  return { needed: false };
+}
+async function migrateBeadsToHive(projectPath) {
+  const beadsDir = join(projectPath, ".beads");
+  const hiveDir = join(projectPath, ".hive");
+  if (existsSync(hiveDir)) {
+    return {
+      migrated: false,
+      reason: ".hive directory already exists - skipping migration to avoid data loss"
+    };
+  }
+  if (!existsSync(beadsDir)) {
+    return {
+      migrated: false,
+      reason: ".beads directory not found - nothing to migrate"
+    };
+  }
+  const { renameSync } = await import("node:fs");
+  renameSync(beadsDir, hiveDir);
+  return { migrated: true };
+}
+function ensureHiveDirectory(projectPath) {
+  const hiveDir = join(projectPath, ".hive");
+  if (!existsSync(hiveDir)) {
+    const { mkdirSync } = __require("node:fs");
+    mkdirSync(hiveDir, { recursive: true });
+  }
+}
 var adapterCache = new Map;
 async function getHiveAdapter(projectKey) {
   if (adapterCache.has(projectKey)) {
@@ -28075,6 +28112,7 @@ var hive_sync = tool({
         }
       }
     };
+    ensureHiveDirectory(projectKey);
     const flushManager = new FlushManager({
       adapter,
       projectKey,
@@ -35959,6 +35997,7 @@ export {
   requireTool,
   repoCrawlTools,
   parseFrontmatter,
+  migrateBeadsToHive,
   mcpCallWithAutoInit,
   mandateTools,
   mandateSchemas,
@@ -36012,6 +36051,7 @@ export {
   extractJsonFromText,
   evaluatePromotion,
   evaluateBatchPromotions,
+  ensureHiveDirectory,
   discoverSkills,
   src_default as default,
   createStorageWithFallback,
@@ -36024,6 +36064,7 @@ export {
   createAgentMailError,
   clearSessionState,
   checkTool,
+  checkBeadsMigrationNeeded,
   checkAllTools,
   beads_update,
   beads_sync,

package/dist/plugin.js

@@ -27633,6 +27633,13 @@ class HiveError extends Error {
     this.name = "HiveError";
   }
 }
+function ensureHiveDirectory(projectPath) {
+  const hiveDir = join(projectPath, ".hive");
+  if (!existsSync(hiveDir)) {
+    const { mkdirSync } = __require("node:fs");
+    mkdirSync(hiveDir, { recursive: true });
+  }
+}
 var adapterCache = new Map;
 async function getHiveAdapter(projectKey) {
   if (adapterCache.has(projectKey)) {
@@ -27966,6 +27973,7 @@ var hive_sync = tool({
         }
       }
     };
+    ensureHiveDirectory(projectKey);
     const flushManager = new FlushManager({
       adapter,
       projectKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.27.2",
+  "version": "0.27.4",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,7 +33,7 @@
     "@opencode-ai/plugin": "^1.0.134",
     "gray-matter": "^4.0.3",
     "ioredis": "^5.4.1",
-    "swarm-mail": "0.3.2",
+    "swarm-mail": "0.3.3",
     "zod": "4.1.8"
   },
   "devDependencies": {

package/src/hive.integration.test.ts

@@ -20,13 +20,6 @@ import {
   getHiveAdapter,
   setHiveWorkingDirectory,
   // Legacy aliases for backward compatibility tests
-  hive_create,
-  hive_create_epic,
-  hive_query,
-  hive_update,
-  hive_close,
-  hive_start,
-  hive_ready,
   beads_link_thread,
   BeadError,
   getBeadsAdapter,
@@ -691,4 +684,150 @@ describe("beads integration", () => {
       }
     });
   });
+
+  describe("Directory Migration (.beads → .hive)", () => {
+    it("checkBeadsMigrationNeeded detects .beads without .hive", async () => {
+      const { checkBeadsMigrationNeeded } = await import("./hive");
+      const { mkdirSync, rmSync, writeFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with .beads directory only
+      const tempProject = join(tmpdir(), `hive-migration-test-${Date.now()}`);
+      const beadsDir = join(tempProject, ".beads");
+      
+      mkdirSync(beadsDir, { recursive: true });
+      writeFileSync(join(beadsDir, "issues.jsonl"), '{"id":"bd-test","title":"Test"}');
+      
+      const result = checkBeadsMigrationNeeded(tempProject);
+      
+      expect(result.needed).toBe(true);
+      expect(result.beadsPath).toBe(beadsDir);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("checkBeadsMigrationNeeded returns false if .hive exists", async () => {
+      const { checkBeadsMigrationNeeded } = await import("./hive");
+      const { mkdirSync, rmSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with .hive directory
+      const tempProject = join(tmpdir(), `hive-migration-test-${Date.now()}`);
+      const hiveDir = join(tempProject, ".hive");
+      
+      mkdirSync(hiveDir, { recursive: true });
+      
+      const result = checkBeadsMigrationNeeded(tempProject);
+      
+      expect(result.needed).toBe(false);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("migrateBeadsToHive renames .beads to .hive", async () => {
+      const { migrateBeadsToHive } = await import("./hive");
+      const { mkdirSync, existsSync, rmSync, writeFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with .beads directory
+      const tempProject = join(tmpdir(), `hive-migration-test-${Date.now()}`);
+      const beadsDir = join(tempProject, ".beads");
+      const hiveDir = join(tempProject, ".hive");
+      
+      mkdirSync(beadsDir, { recursive: true });
+      writeFileSync(join(beadsDir, "issues.jsonl"), '{"id":"bd-test","title":"Test"}');
+      writeFileSync(join(beadsDir, "config.yaml"), "version: 1");
+      
+      // Run migration (called after user confirms in CLI)
+      const result = await migrateBeadsToHive(tempProject);
+      
+      // Verify .beads renamed to .hive
+      expect(result.migrated).toBe(true);
+      expect(existsSync(hiveDir)).toBe(true);
+      expect(existsSync(beadsDir)).toBe(false);
+      expect(existsSync(join(hiveDir, "issues.jsonl"))).toBe(true);
+      expect(existsSync(join(hiveDir, "config.yaml"))).toBe(true);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("migrateBeadsToHive skips if .hive already exists", async () => {
+      const { migrateBeadsToHive } = await import("./hive");
+      const { mkdirSync, existsSync, rmSync, writeFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with BOTH .beads and .hive
+      const tempProject = join(tmpdir(), `hive-migration-test-${Date.now()}`);
+      const beadsDir = join(tempProject, ".beads");
+      const hiveDir = join(tempProject, ".hive");
+      
+      mkdirSync(beadsDir, { recursive: true });
+      mkdirSync(hiveDir, { recursive: true });
+      writeFileSync(join(beadsDir, "issues.jsonl"), '{"id":"bd-old"}');
+      writeFileSync(join(hiveDir, "issues.jsonl"), '{"id":"bd-new"}');
+      
+      // Run migration - should skip
+      const result = await migrateBeadsToHive(tempProject);
+      
+      // Verify both still exist (no migration)
+      expect(result.migrated).toBe(false);
+      expect(result.reason).toContain("already exists");
+      expect(existsSync(beadsDir)).toBe(true);
+      expect(existsSync(hiveDir)).toBe(true);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("ensureHiveDirectory creates .hive if missing", async () => {
+      const { ensureHiveDirectory } = await import("./hive");
+      const { mkdirSync, existsSync, rmSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create empty temp project
+      const tempProject = join(tmpdir(), `hive-ensure-test-${Date.now()}`);
+      mkdirSync(tempProject, { recursive: true });
+      
+      const hiveDir = join(tempProject, ".hive");
+      expect(existsSync(hiveDir)).toBe(false);
+      
+      // Ensure creates it
+      ensureHiveDirectory(tempProject);
+      
+      expect(existsSync(hiveDir)).toBe(true);
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+
+    it("ensureHiveDirectory is idempotent", async () => {
+      const { ensureHiveDirectory } = await import("./hive");
+      const { mkdirSync, existsSync, rmSync, writeFileSync, readFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { tmpdir } = await import("node:os");
+      
+      // Create temp project with existing .hive
+      const tempProject = join(tmpdir(), `hive-ensure-test-${Date.now()}`);
+      const hiveDir = join(tempProject, ".hive");
+      mkdirSync(hiveDir, { recursive: true });
+      writeFileSync(join(hiveDir, "issues.jsonl"), '{"id":"existing"}');
+      
+      // Ensure doesn't overwrite
+      ensureHiveDirectory(tempProject);
+      
+      expect(existsSync(hiveDir)).toBe(true);
+      expect(readFileSync(join(hiveDir, "issues.jsonl"), "utf-8")).toBe('{"id":"existing"}');
+      
+      // Cleanup
+      rmSync(tempProject, { recursive: true, force: true });
+    });
+  });
 });

package/src/hive.ts

@@ -130,6 +130,111 @@ export class HiveValidationError extends Error {
 // Legacy alias for backward compatibility
 export const BeadValidationError = HiveValidationError;
 
+// ============================================================================
+// Directory Migration (.beads → .hive)
+// ============================================================================
+
+/**
+ * Result of checking if .beads → .hive migration is needed
+ */
+export interface MigrationCheckResult {
+  /** Whether migration is needed */
+  needed: boolean;
+  /** Path to .beads directory if it exists */
+  beadsPath?: string;
+}
+
+/**
+ * Result of migrating .beads → .hive
+ */
+export interface MigrationResult {
+  /** Whether migration was performed */
+  migrated: boolean;
+  /** Reason if migration was skipped */
+  reason?: string;
+}
+
+/**
+ * Check if .beads → .hive migration is needed
+ * 
+ * Migration is needed when:
+ * - .beads directory exists
+ * - .hive directory does NOT exist
+ * 
+ * @param projectPath - Absolute path to the project root
+ * @returns MigrationCheckResult indicating if migration is needed
+ */
+export function checkBeadsMigrationNeeded(projectPath: string): MigrationCheckResult {
+  const beadsDir = join(projectPath, ".beads");
+  const hiveDir = join(projectPath, ".hive");
+  
+  // If .hive already exists, no migration needed
+  if (existsSync(hiveDir)) {
+    return { needed: false };
+  }
+  
+  // If .beads exists but .hive doesn't, migration is needed
+  if (existsSync(beadsDir)) {
+    return { needed: true, beadsPath: beadsDir };
+  }
+  
+  // Neither exists - no migration needed
+  return { needed: false };
+}
+
+/**
+ * Migrate .beads directory to .hive
+ * 
+ * This function renames .beads to .hive. It should only be called
+ * after user confirmation via CLI prompt.
+ * 
+ * @param projectPath - Absolute path to the project root
+ * @returns MigrationResult indicating success or skip reason
+ */
+export async function migrateBeadsToHive(projectPath: string): Promise<MigrationResult> {
+  const beadsDir = join(projectPath, ".beads");
+  const hiveDir = join(projectPath, ".hive");
+  
+  // Check if .hive already exists - skip migration
+  if (existsSync(hiveDir)) {
+    return { 
+      migrated: false, 
+      reason: ".hive directory already exists - skipping migration to avoid data loss" 
+    };
+  }
+  
+  // Check if .beads exists
+  if (!existsSync(beadsDir)) {
+    return { 
+      migrated: false, 
+      reason: ".beads directory not found - nothing to migrate" 
+    };
+  }
+  
+  // Perform the rename
+  const { renameSync } = await import("node:fs");
+  renameSync(beadsDir, hiveDir);
+  
+  return { migrated: true };
+}
+
+/**
+ * Ensure .hive directory exists
+ * 
+ * Creates .hive directory if it doesn't exist. This is idempotent
+ * and safe to call multiple times.
+ * 
+ * @param projectPath - Absolute path to the project root
+ */
+export function ensureHiveDirectory(projectPath: string): void {
+  const hiveDir = join(projectPath, ".hive");
+  
+  if (!existsSync(hiveDir)) {
+    const { mkdirSync } = require("node:fs");
+    mkdirSync(hiveDir, { recursive: true });
+  }
+}
+
 // ============================================================================
 // Adapter Singleton
 // ============================================================================
@@ -714,7 +819,10 @@ export const hive_sync = tool({
       }
     };
 
-    // 1. Flush cells to JSONL using FlushManager
+    // 1. Ensure .hive directory exists before writing
+    ensureHiveDirectory(projectKey);
+
+    // 2. Flush cells to JSONL using FlushManager
     const flushManager = new FlushManager({
       adapter,
       projectKey,
@@ -731,7 +839,7 @@ export const hive_sync = tool({
       return "No cells to sync";
     }
 
-    // 2. Check if there are changes to commit
+    // 3. Check if there are changes to commit
     const hiveStatusResult = await runGitCommand([
       "status",
       "--porcelain",
@@ -740,7 +848,7 @@ export const hive_sync = tool({
     const hasChanges = hiveStatusResult.stdout.trim() !== "";
 
     if (hasChanges) {
-      // 3. Stage .hive changes
+      // 4. Stage .hive changes
       const addResult = await runGitCommand(["add", ".hive/"]);
       if (addResult.exitCode !== 0) {
         throw new HiveError(
@@ -750,7 +858,7 @@ export const hive_sync = tool({
         );
       }
 
-      // 4. Commit
+      // 5. Commit
       const commitResult = await withTimeout(
         runGitCommand(["commit", "-m", "chore: sync hive"]),
         TIMEOUT_MS,
@@ -768,7 +876,7 @@ export const hive_sync = tool({
       }
     }
 
-    // 5. Pull if requested
+    // 6. Pull if requested
     if (autoPull) {
       const pullResult = await withTimeout(
         runGitCommand(["pull", "--rebase"]),
@@ -785,7 +893,7 @@ export const hive_sync = tool({
       }
     }
 
-    // 6. Push
+    // 7. Push
     const pushResult = await withTimeout(
       runGitCommand(["push"]),
       TIMEOUT_MS,