opencode-swarm-plugin 0.25.2 → 0.26.0

package/src/beads.ts

@@ -1,27 +1,34 @@
 /**
- * Beads Module - Type-safe wrappers around the `bd` CLI
+ * Beads Module - Type-safe wrappers using BeadsAdapter
  *
  * This module provides validated, type-safe operations for the beads
- * issue tracker. All responses are parsed and validated with Zod schemas.
+ * issue tracker using the BeadsAdapter from swarm-mail.
  *
  * Key principles:
- * - Always use `--json` flag for bd commands
- * - Validate all output with Zod schemas
+ * - Use BeadsAdapter for all operations (no CLI commands)
+ * - Validate all inputs with Zod schemas
  * - Throw typed errors on failure
- * - Support atomic epic creation with rollback hints
+ * - Support atomic epic creation with rollback
  *
  * IMPORTANT: Call setBeadsWorkingDirectory() before using tools to ensure
- * bd commands run in the correct project directory.
+ * operations run in the correct project directory.
  */
 import { tool } from "@opencode-ai/plugin";
 import { z } from "zod";
+import {
+  createBeadsAdapter,
+  FlushManager,
+  type BeadsAdapter,
+  type Bead as AdapterBead,
+  getSwarmMail,
+} from "swarm-mail";
 
 // ============================================================================
 // Working Directory Configuration
 // ============================================================================
 
 /**
- * Module-level working directory for bd commands.
+ * Module-level working directory for beads commands.
  * Set this via setBeadsWorkingDirectory() before using tools.
  * If not set, commands run in process.cwd() which may be wrong for plugins.
  */
@@ -45,30 +52,6 @@ export function getBeadsWorkingDirectory(): string {
   return beadsWorkingDirectory || process.cwd();
 }
 
-/**
- * Run a bd command in the correct working directory.
- * Uses Bun.spawn with cwd option to ensure commands run in project directory.
- */
-async function runBdCommand(
-  args: string[],
-): Promise<{ exitCode: number; stdout: string; stderr: string }> {
-  const cwd = getBeadsWorkingDirectory();
-  const proc = Bun.spawn(["bd", ...args], {
-    cwd,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-
-  const exitCode = await proc.exited;
-
-  return { exitCode, stdout, stderr };
-}
-
 /**
  * Run a git command in the correct working directory.
  */
@@ -134,93 +117,58 @@ export class BeadValidationError extends Error {
   }
 }
 
+// ============================================================================
+// Adapter Singleton
+// ============================================================================
+
 /**
- * Build a bd create command from args
- *
- * Note: Bun's `$` template literal properly escapes arguments when passed as array.
- * Each array element is treated as a separate argument, preventing shell injection.
- * Example: ["bd", "create", "; rm -rf /"] becomes: bd create "; rm -rf /"
+ * Lazy singleton for BeadsAdapter instances
+ * Maps projectKey -> BeadsAdapter
  */
-function buildCreateCommand(args: BeadCreateArgs): string[] {
-  const parts = ["bd", "create", args.title];
-
-  if (args.type && args.type !== "task") {
-    parts.push("-t", args.type);
-  }
-
-  if (args.priority !== undefined && args.priority !== 2) {
-    parts.push("-p", args.priority.toString());
-  }
+const adapterCache = new Map<string, BeadsAdapter>();
 
-  if (args.description) {
-    parts.push("-d", args.description);
+/**
+ * Get or create a BeadsAdapter instance for a project
+ * Exported for testing - allows tests to verify state directly
+ */
+export async function getBeadsAdapter(projectKey: string): Promise<BeadsAdapter> {
+  if (adapterCache.has(projectKey)) {
+    return adapterCache.get(projectKey)!;
   }
 
-  if (args.parent_id) {
-    parts.push("--parent", args.parent_id);
-  }
+  const swarmMail = await getSwarmMail(projectKey);
+  const db = await swarmMail.getDatabase();
+  const adapter = createBeadsAdapter(db, projectKey);
 
-  // Custom ID for human-readable bead names (e.g., 'phase-0', 'phase-1.e2e-test')
-  if (args.id) {
-    parts.push("--id", args.id);
-  }
+  // Run migrations to ensure schema exists
+  await adapter.runMigrations();
 
-  parts.push("--json");
-  return parts;
+  adapterCache.set(projectKey, adapter);
+  return adapter;
 }
 
 /**
- * Parse and validate bead JSON output
- * Handles both object and array responses (CLI may return either)
+ * Format adapter bead for output (map field names)
+ * Adapter uses: type, created_at/updated_at (timestamps)
+ * Schema expects: issue_type, created_at/updated_at (ISO strings)
  */
-function parseBead(output: string): Bead {
-  try {
-    const parsed = JSON.parse(output);
-    // CLI commands like `bd close`, `bd update` return arrays even for single items
-    const data = Array.isArray(parsed) ? parsed[0] : parsed;
-    if (!data) {
-      throw new BeadError(
-        "No bead data in response. The bd CLI may not be installed or returned unexpected output. Try: Run 'bd --version' to verify installation, or check if .beads/ directory exists in project.",
-        "parse",
-      );
-    }
-    return BeadSchema.parse(data);
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      throw new BeadValidationError(
-        `Invalid bead data: ${error.message}`,
-        error,
-      );
-    }
-    if (error instanceof BeadError) {
-      throw error;
-    }
-    throw new BeadError(
-      `Failed to parse bead JSON because output is malformed. Try: Check if bd CLI is up to date with 'bd --version' (need v1.0.0+), or inspect output: ${output.slice(0, 100)}`,
-      "parse",
-    );
-  }
-}
-
-/**
- * Parse and validate array of beads
- */
-function parseBeads(output: string): Bead[] {
-  try {
-    const parsed = JSON.parse(output);
-    return z.array(BeadSchema).parse(parsed);
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      throw new BeadValidationError(
-        `Invalid beads data: ${error.message}`,
-        error,
-      );
-    }
-    throw new BeadError(
-      `Failed to parse beads JSON because output is malformed. Try: Check if bd CLI is up to date with 'bd --version' (need v1.0.0+), or inspect output: ${output.slice(0, 100)}`,
-      "parse",
-    );
-  }
+function formatBeadForOutput(adapterBead: AdapterBead): Record<string, unknown> {
+  return {
+    id: adapterBead.id,
+    title: adapterBead.title,
+    description: adapterBead.description || "",
+    status: adapterBead.status,
+    priority: adapterBead.priority,
+    issue_type: adapterBead.type, // Adapter: type → Schema: issue_type
+    created_at: new Date(adapterBead.created_at).toISOString(),
+    updated_at: new Date(adapterBead.updated_at).toISOString(),
+    closed_at: adapterBead.closed_at
+      ? new Date(adapterBead.closed_at).toISOString()
+      : undefined,
+    parent_id: adapterBead.parent_id || undefined,
+    dependencies: [], // TODO: fetch from adapter if needed
+    metadata: {},
+  };
 }
 
 // ============================================================================
@@ -252,43 +200,30 @@ export const beads_create = tool({
   },
   async execute(args, ctx) {
     const validated = BeadCreateArgsSchema.parse(args);
-    const cmdParts = buildCreateCommand(validated);
+    const projectKey = getBeadsWorkingDirectory();
+    const adapter = await getBeadsAdapter(projectKey);
 
-    // Execute command in the correct working directory
-    const result = await runBdCommand(cmdParts.slice(1)); // Remove 'bd' prefix
-
-    if (result.exitCode !== 0) {
-      throw new BeadError(
-        `Failed to create bead because bd command exited with code ${result.exitCode}. Error: ${result.stderr}. Try: Check if beads initialized with 'bd init' in project root, or verify .beads/ directory exists.`,
-        cmdParts.join(" "),
-        result.exitCode,
-        result.stderr,
-      );
-    }
+    try {
+      const bead = await adapter.createBead(projectKey, {
+        title: validated.title,
+        type: validated.type || "task",
+        priority: validated.priority ?? 2,
+        description: validated.description,
+        parent_id: validated.parent_id,
+      });
 
-    // Validate output before parsing
-    const stdout = result.stdout.trim();
-    if (!stdout) {
-      throw new BeadError(
-        "bd create returned empty output because command produced no response. Try: Check if bd is properly installed with 'bd --version', or run 'bd list' to test basic functionality.",
-        cmdParts.join(" "),
-        0,
-        "Empty stdout",
-      );
-    }
+      // Mark dirty for export
+      await adapter.markDirty(projectKey, bead.id);
 
-    // Check for error messages in stdout (bd sometimes outputs errors to stdout)
-    if (stdout.startsWith("error:") || stdout.startsWith("Error:")) {
+      const formatted = formatBeadForOutput(bead);
+      return JSON.stringify(formatted, null, 2);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
       throw new BeadError(
-        `bd create failed because command returned error in stdout: ${stdout}. Try: Check error message above, verify beads initialized with 'bd init', or check .beads/issues.jsonl for corruption.`,
-        cmdParts.join(" "),
-        0,
-        stdout,
+        `Failed to create bead: ${message}`,
+        "beads_create",
       );
     }
-
-    const bead = parseBead(stdout);
-    return JSON.stringify(bead, null, 2);
   },
 });
 
@@ -345,66 +280,37 @@ export const beads_create_epic = tool({
   },
   async execute(args, ctx) {
     const validated = EpicCreateArgsSchema.parse(args);
-    const created: Bead[] = [];
+    const projectKey = getBeadsWorkingDirectory();
+    const adapter = await getBeadsAdapter(projectKey);
+    const created: AdapterBead[] = [];
 
     try {
       // 1. Create epic
-      const epicCmd = buildCreateCommand({
+      const epic = await adapter.createBead(projectKey, {
         title: validated.epic_title,
         type: "epic",
         priority: 1,
         description: validated.epic_description,
-        id: validated.epic_id,
       });
-
-      const epicResult = await runBdCommand(epicCmd.slice(1)); // Remove 'bd' prefix
-
-      if (epicResult.exitCode !== 0) {
-        throw new BeadError(
-          `Failed to create epic because bd command failed: ${epicResult.stderr}. Try: Verify beads initialized with 'bd init', check if .beads/ directory is writable, or run 'bd list' to test basic functionality.`,
-          epicCmd.join(" "),
-          epicResult.exitCode,
-        );
-      }
-
-      const epic = parseBead(epicResult.stdout);
+      await adapter.markDirty(projectKey, epic.id);
       created.push(epic);
 
       // 2. Create subtasks
       for (const subtask of validated.subtasks) {
-        // Build subtask ID: if epic has custom ID and subtask has suffix, combine them
-        // e.g., epic_id='phase-0', id_suffix='e2e-test' → 'phase-0.e2e-test'
-        let subtaskId: string | undefined;
-        if (validated.epic_id && subtask.id_suffix) {
-          subtaskId = `${validated.epic_id}.${subtask.id_suffix}`;
-        }
-
-        const subtaskCmd = buildCreateCommand({
+        const subtaskBead = await adapter.createBead(projectKey, {
           title: subtask.title,
           type: "task",
           priority: subtask.priority ?? 2,
           parent_id: epic.id,
-          id: subtaskId,
         });
-
-        const subtaskResult = await runBdCommand(subtaskCmd.slice(1)); // Remove 'bd' prefix
-
-        if (subtaskResult.exitCode !== 0) {
-          throw new BeadError(
-            `Failed to create subtask because bd command failed: ${subtaskResult.stderr}. Try: Check if parent epic exists with 'bd show ${epic.id}', verify .beads/issues.jsonl is not corrupted, or check for invalid characters in title.`,
-            subtaskCmd.join(" "),
-            subtaskResult.exitCode,
-          );
-        }
-
-        const subtaskBead = parseBead(subtaskResult.stdout);
+        await adapter.markDirty(projectKey, subtaskBead.id);
         created.push(subtaskBead);
       }
 
       const result: EpicCreateResult = {
         success: true,
-        epic,
-        subtasks: created.slice(1),
+        epic: formatBeadForOutput(epic) as Bead,
+        subtasks: created.slice(1).map((b) => formatBeadForOutput(b) as Bead),
       };
 
       // Emit DecompositionGeneratedEvent for learning system
@@ -436,31 +342,15 @@ export const beads_create_epic = tool({
 
       return JSON.stringify(result, null, 2);
     } catch (error) {
-      // Partial failure - execute rollback automatically
-      const rollbackCommands: string[] = [];
+      // Partial failure - rollback via deleteBead
       const rollbackErrors: string[] = [];
 
       for (const bead of created) {
         try {
-          const closeArgs = [
-            "close",
-            bead.id,
-            "--reason",
-            "Rollback partial epic",
-            "--json",
-          ];
-          const rollbackResult = await runBdCommand(closeArgs);
-          if (rollbackResult.exitCode === 0) {
-            rollbackCommands.push(
-              `bd close ${bead.id} --reason "Rollback partial epic"`,
-            );
-          } else {
-            rollbackErrors.push(
-              `${bead.id}: exit ${rollbackResult.exitCode} - ${rollbackResult.stderr.trim()}`,
-            );
-          }
+          await adapter.deleteBead(projectKey, bead.id, {
+            reason: "Rollback partial epic",
+          });
         } catch (rollbackError) {
-          // Log rollback failure and collect error
           const errMsg =
             rollbackError instanceof Error
               ? rollbackError.message
@@ -470,24 +360,15 @@ export const beads_create_epic = tool({
         }
       }
 
-      // Throw error with rollback info including any failures
       const errorMsg = error instanceof Error ? error.message : String(error);
-      let rollbackInfo = "";
-
-      if (rollbackCommands.length > 0) {
-        rollbackInfo += `\n\nRolled back ${rollbackCommands.length} bead(s):\n${rollbackCommands.join("\n")}`;
-      }
+      let rollbackInfo = `\n\nRolled back ${created.length - rollbackErrors.length} bead(s)`;
 
       if (rollbackErrors.length > 0) {
         rollbackInfo += `\n\nRollback failures (${rollbackErrors.length}):\n${rollbackErrors.join("\n")}`;
       }
 
-      if (!rollbackInfo) {
-        rollbackInfo = "\n\nNo beads to rollback.";
-      }
-
       throw new BeadError(
-        `Epic creation failed: ${errorMsg}${rollbackInfo}. Try: If rollback failed, manually close beads with 'bd close <id> --reason "Rollback"', check .beads/issues.jsonl for partial state, or re-run beads_create_epic with corrected parameters.`,
+        `Epic creation failed: ${errorMsg}${rollbackInfo}`,
         "beads_create_epic",
         1,
       );
@@ -520,35 +401,32 @@ export const beads_query = tool({
   },
   async execute(args, ctx) {
     const validated = BeadQueryArgsSchema.parse(args);
+    const projectKey = getBeadsWorkingDirectory();
+    const adapter = await getBeadsAdapter(projectKey);
 
-    let cmd: string[];
-
-    if (validated.ready) {
-      cmd = ["bd", "ready", "--json"];
-    } else {
-      cmd = ["bd", "list", "--json"];
-      if (validated.status) {
-        cmd.push("--status", validated.status);
-      }
-      if (validated.type) {
-        cmd.push("--type", validated.type);
+    try {
+      let beads: AdapterBead[];
+
+      if (validated.ready) {
+        const readyBead = await adapter.getNextReadyBead(projectKey);
+        beads = readyBead ? [readyBead] : [];
+      } else {
+        beads = await adapter.queryBeads(projectKey, {
+          status: validated.status,
+          type: validated.type,
+          limit: validated.limit || 20,
+        });
       }
-    }
-
-    const result = await runBdCommand(cmd.slice(1)); // Remove 'bd' prefix
 
-    if (result.exitCode !== 0) {
+      const formatted = beads.map((b) => formatBeadForOutput(b));
+      return JSON.stringify(formatted, null, 2);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
       throw new BeadError(
-        `Failed to query beads because bd command failed: ${result.stderr}. Try: Check if beads initialized with 'bd init', verify .beads/ directory exists, or run 'bd --version' to check CLI version.`,
-        cmd.join(" "),
-        result.exitCode,
+        `Failed to query beads: ${message}`,
+        "beads_query",
       );
     }
-
-    const beads = parseBeads(result.stdout);
-    const limited = beads.slice(0, validated.limit);
-
-    return JSON.stringify(limited, null, 2);
   },
 });
 
@@ -573,32 +451,50 @@ export const beads_update = tool({
   },
   async execute(args, ctx) {
     const validated = BeadUpdateArgsSchema.parse(args);
+    const projectKey = getBeadsWorkingDirectory();
+    const adapter = await getBeadsAdapter(projectKey);
 
-    const cmd = ["bd", "update", validated.id];
+    try {
+      let bead: AdapterBead;
 
-    if (validated.status) {
-      cmd.push("--status", validated.status);
-    }
-    if (validated.description) {
-      cmd.push("-d", validated.description);
-    }
-    if (validated.priority !== undefined) {
-      cmd.push("-p", validated.priority.toString());
-    }
-    cmd.push("--json");
+      // Status changes use changeBeadStatus, other fields use updateBead
+      if (validated.status) {
+        bead = await adapter.changeBeadStatus(
+          projectKey,
+          validated.id,
+          validated.status,
+        );
+      }
+
+      // Update other fields if provided
+      if (validated.description !== undefined || validated.priority !== undefined) {
+        bead = await adapter.updateBead(projectKey, validated.id, {
+          description: validated.description,
+          priority: validated.priority,
+        });
+      } else if (!validated.status) {
+        // No changes requested
+        const existingBead = await adapter.getBead(projectKey, validated.id);
+        if (!existingBead) {
+          throw new BeadError(
+            `Bead not found: ${validated.id}`,
+            "beads_update",
+          );
+        }
+        bead = existingBead;
+      }
 
-    const result = await runBdCommand(cmd.slice(1)); // Remove 'bd' prefix
+      await adapter.markDirty(projectKey, validated.id);
 
-    if (result.exitCode !== 0) {
+      const formatted = formatBeadForOutput(bead!);
+      return JSON.stringify(formatted, null, 2);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
       throw new BeadError(
-        `Failed to update bead because bd command failed: ${result.stderr}. Try: Verify bead exists with 'bd show ${validated.id}', check for invalid status values, or inspect .beads/issues.jsonl for corruption.`,
-        cmd.join(" "),
-        result.exitCode,
+        `Failed to update bead: ${message}`,
+        "beads_update",
       );
     }
-
-    const bead = parseBead(result.stdout);
-    return JSON.stringify(bead, null, 2);
   },
 });
 
@@ -613,28 +509,26 @@ export const beads_close = tool({
   },
   async execute(args, ctx) {
     const validated = BeadCloseArgsSchema.parse(args);
+    const projectKey = getBeadsWorkingDirectory();
+    const adapter = await getBeadsAdapter(projectKey);
 
-    const cmd = [
-      "bd",
-      "close",
-      validated.id,
-      "--reason",
-      validated.reason,
-      "--json",
-    ];
+    try {
+      const bead = await adapter.closeBead(
+        projectKey,
+        validated.id,
+        validated.reason,
+      );
 
-    const result = await runBdCommand(cmd.slice(1)); // Remove 'bd' prefix
+      await adapter.markDirty(projectKey, validated.id);
 
-    if (result.exitCode !== 0) {
+      return `Closed ${bead.id}: ${validated.reason}`;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
       throw new BeadError(
-        `Failed to close bead because bd command failed: ${result.stderr}. Try: Verify bead exists and is not already closed with 'beads_query(status="closed")' or 'bd show ${validated.id}', check if bead ID is correct.`,
-        cmd.join(" "),
-        result.exitCode,
+        `Failed to close bead: ${message}`,
+        "beads_close",
       );
     }
-
-    const bead = parseBead(result.stdout);
-    return `Closed ${bead.id}: ${validated.reason}`;
   },
 });
 
@@ -648,24 +542,26 @@ export const beads_start = tool({
     id: tool.schema.string().describe("Bead ID"),
   },
   async execute(args, ctx) {
-    const result = await runBdCommand([
-      "update",
-      args.id,
-      "--status",
-      "in_progress",
-      "--json",
-    ]);
+    const projectKey = getBeadsWorkingDirectory();
+    const adapter = await getBeadsAdapter(projectKey);
+
+    try {
+      const bead = await adapter.changeBeadStatus(
+        projectKey,
+        args.id,
+        "in_progress",
+      );
+
+      await adapter.markDirty(projectKey, args.id);
 
-    if (result.exitCode !== 0) {
+      return `Started: ${bead.id}`;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
       throw new BeadError(
-        `Failed to start bead because bd update command failed: ${result.stderr}. Try: Verify bead exists with 'bd show ${args.id}', check if already in_progress with 'beads_query(status="in_progress")', or use beads_update directly.`,
-        `bd update ${args.id} --status in_progress --json`,
-        result.exitCode,
+        `Failed to start bead: ${message}`,
+        "beads_start",
       );
     }
-
-    const bead = parseBead(result.stdout);
-    return `Started: ${bead.id}`;
   },
 });
 
@@ -676,24 +572,25 @@ export const beads_ready = tool({
   description: "Get the next ready bead (unblocked, highest priority)",
   args: {},
   async execute(args, ctx) {
-    const result = await runBdCommand(["ready", "--json"]);
+    const projectKey = getBeadsWorkingDirectory();
+    const adapter = await getBeadsAdapter(projectKey);
 
-    if (result.exitCode !== 0) {
-      throw new BeadError(
-        `Failed to get ready beads because bd ready command failed: ${result.stderr}. Try: Check if beads initialized with 'bd init', verify .beads/ directory is readable, or run 'bd list --json' to test basic query.`,
-        "bd ready --json",
-        result.exitCode,
-      );
-    }
+    try {
+      const bead = await adapter.getNextReadyBead(projectKey);
 
-    const beads = parseBeads(result.stdout);
+      if (!bead) {
+        return "No ready beads";
+      }
 
-    if (beads.length === 0) {
-      return "No ready beads";
+      const formatted = formatBeadForOutput(bead);
+      return JSON.stringify(formatted, null, 2);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new BeadError(
+        `Failed to get ready beads: ${message}`,
+        "beads_ready",
+      );
     }
-
-    const next = beads[0];
-    return JSON.stringify(next, null, 2);
   },
 });
 
@@ -710,11 +607,12 @@ export const beads_sync = tool({
   },
   async execute(args, ctx) {
     const autoPull = args.auto_pull ?? true;
+    const projectKey = getBeadsWorkingDirectory();
+    const adapter = await getBeadsAdapter(projectKey);
     const TIMEOUT_MS = 30000; // 30 seconds
 
     /**
      * Helper to run a command with timeout
-     * Properly clears the timeout to avoid lingering timers
      */
     const withTimeout = async <T>(
       promise: Promise<T>,
@@ -745,18 +643,21 @@ export const beads_sync = tool({
       }
     };
 
-    // 1. Flush beads to JSONL (doesn't use worktrees)
+    // 1. Flush beads to JSONL using FlushManager
+    const flushManager = new FlushManager({
+      adapter,
+      projectKey,
+      outputPath: `${projectKey}/.beads/issues.jsonl`,
+    });
+
     const flushResult = await withTimeout(
-      runBdCommand(["sync", "--flush-only"]),
+      flushManager.flush(),
       TIMEOUT_MS,
-      "bd sync --flush-only",
+      "flush beads",
     );
-    if (flushResult.exitCode !== 0) {
-      throw new BeadError(
-        `Failed to flush beads because bd sync failed: ${flushResult.stderr}. Try: Check if .beads/ directory is writable, verify no corrupted JSONL files, or run 'bd list' to test basic beads functionality.`,
-        "bd sync --flush-only",
-        flushResult.exitCode,
-      );
+
+    if (flushResult.beadsExported === 0) {
+      return "No beads to sync";
     }
 
     // 2. Check if there are changes to commit
@@ -772,7 +673,7 @@ export const beads_sync = tool({
       const addResult = await runGitCommand(["add", ".beads/"]);
       if (addResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to stage beads because git add failed: ${addResult.stderr}. Try: Check if .beads/ directory exists, verify git is initialized with 'git status', or check for .gitignore patterns blocking .beads/.`,
+          `Failed to stage beads: ${addResult.stderr}`,
           "git add .beads/",
           addResult.exitCode,
         );
@@ -789,91 +690,31 @@ export const beads_sync = tool({
         !commitResult.stdout.includes("nothing to commit")
       ) {
         throw new BeadError(
-          `Failed to commit beads because git commit failed: ${commitResult.stderr}. Try: Check git config (user.name, user.email) with 'git config --list', verify working tree is clean, or check for pre-commit hooks blocking commit.`,
+          `Failed to commit beads: ${commitResult.stderr}`,
           "git commit",
           commitResult.exitCode,
         );
       }
     }
 
-    // 5. Pull if requested (with rebase to avoid merge commits)
+    // 5. Pull if requested
     if (autoPull) {
-      // Check for unstaged changes that would block pull --rebase
-      const dirtyCheckResult = await runGitCommand([
-        "status",
-        "--porcelain",
-        "--untracked-files=no",
-      ]);
-      const hasDirtyFiles = dirtyCheckResult.stdout.trim() !== "";
-      let didStash = false;
-
-      // Stash dirty files before pull (self-healing for "unstaged changes" error)
-      if (hasDirtyFiles) {
-        console.warn(
-          "[beads] Detected unstaged changes, stashing before pull...",
-        );
-        const stashResult = await runGitCommand([
-          "stash",
-          "push",
-          "-m",
-          "beads_sync: auto-stash before pull",
-          "--include-untracked",
-        ]);
-        if (stashResult.exitCode === 0) {
-          didStash = true;
-          console.warn("[beads] Changes stashed successfully");
-        } else {
-          // Stash failed - try pull anyway, it might work
-          console.warn(
-            `[beads] Stash failed (${stashResult.stderr}), attempting pull anyway...`,
-          );
-        }
-      }
-
       const pullResult = await withTimeout(
         runGitCommand(["pull", "--rebase"]),
         TIMEOUT_MS,
         "git pull --rebase",
       );
 
-      // Restore stashed changes regardless of pull result
-      if (didStash) {
-        console.warn("[beads] Restoring stashed changes...");
-        const unstashResult = await runGitCommand(["stash", "pop"]);
-        if (unstashResult.exitCode !== 0) {
-          // Unstash failed - this is bad, user needs to know
-          console.error(
-            `[beads] WARNING: Failed to restore stashed changes: ${unstashResult.stderr}`,
-          );
-          console.error(
-            "[beads] Your changes are in 'git stash list' - run 'git stash pop' manually",
-          );
-        } else {
-          console.warn("[beads] Stashed changes restored");
-        }
-      }
-
       if (pullResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to pull because git pull --rebase failed: ${pullResult.stderr}. Try: Resolve merge conflicts manually with 'git status', check if remote is accessible with 'git remote -v', or use skip_verification to bypass automatic pull.`,
+          `Failed to pull: ${pullResult.stderr}`,
           "git pull --rebase",
           pullResult.exitCode,
         );
       }
-
-      // 6. Import any changes from remote
-      const importResult = await withTimeout(
-        runBdCommand(["sync", "--import-only"]),
-        TIMEOUT_MS,
-        "bd sync --import-only",
-      );
-      if (importResult.exitCode !== 0) {
-        // Non-fatal - just log warning
-        console.warn(`[beads] Import warning: ${importResult.stderr}`);
-      }
     }
 
-    // 7. Push
+    // 6. Push
     const pushResult = await withTimeout(
       runGitCommand(["push"]),
       TIMEOUT_MS,
@@ -881,20 +722,12 @@ export const beads_sync = tool({
     );
     if (pushResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to push because git push failed: ${pushResult.stderr}. Try: Check if remote branch is up to date with 'git pull --rebase', verify push permissions, check remote URL with 'git remote -v', or force push with 'git push --force-with-lease' if safe.`,
+        `Failed to push: ${pushResult.stderr}`,
         "git push",
         pushResult.exitCode,
       );
     }
 
-    // 4. Verify clean state
-    const statusResult = await runGitCommand(["status", "--porcelain"]);
-    const status = statusResult.stdout.trim();
-
-    if (status !== "") {
-      return `Beads synced and pushed, but working directory not clean:\n${status}`;
-    }
-
     return "Beads synced and pushed successfully";
   },
 });
@@ -909,48 +742,44 @@ export const beads_link_thread = tool({
     thread_id: tool.schema.string().describe("Agent Mail thread ID"),
   },
   async execute(args, ctx) {
-    // Update bead description to include thread link
-    // This is a workaround since bd doesn't have native metadata support
-    const queryResult = await runBdCommand(["show", args.bead_id, "--json"]);
+    const projectKey = getBeadsWorkingDirectory();
+    const adapter = await getBeadsAdapter(projectKey);
 
-    if (queryResult.exitCode !== 0) {
-      throw new BeadError(
-        `Failed to get bead because bd show command failed: ${queryResult.stderr}. Try: Verify bead ID is correct with 'beads_query()', check if bead exists with 'bd list --json', or check .beads/issues.jsonl for valid entries.`,
-        `bd show ${args.bead_id} --json`,
-        queryResult.exitCode,
-      );
-    }
+    try {
+      const bead = await adapter.getBead(projectKey, args.bead_id);
+
+      if (!bead) {
+        throw new BeadError(
+          `Bead not found: ${args.bead_id}`,
+          "beads_link_thread",
+        );
+      }
 
-    const bead = parseBead(queryResult.stdout);
-    const existingDesc = bead.description || "";
+      const existingDesc = bead.description || "";
+      const threadMarker = `[thread:${args.thread_id}]`;
 
-    // Add thread link if not already present
-    const threadMarker = `[thread:${args.thread_id}]`;
-    if (existingDesc.includes(threadMarker)) {
-      return `Bead ${args.bead_id} already linked to thread ${args.thread_id}`;
-    }
+      if (existingDesc.includes(threadMarker)) {
+        return `Bead ${args.bead_id} already linked to thread ${args.thread_id}`;
+      }
 
-    const newDesc = existingDesc
-      ? `${existingDesc}\n\n${threadMarker}`
-      : threadMarker;
+      const newDesc = existingDesc
+        ? `${existingDesc}\n\n${threadMarker}`
+        : threadMarker;
 
-    const updateResult = await runBdCommand([
-      "update",
-      args.bead_id,
-      "-d",
-      newDesc,
-      "--json",
-    ]);
+      await adapter.updateBead(projectKey, args.bead_id, {
+        description: newDesc,
+      });
+
+      await adapter.markDirty(projectKey, args.bead_id);
 
-    if (updateResult.exitCode !== 0) {
+      return `Linked bead ${args.bead_id} to thread ${args.thread_id}`;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
       throw new BeadError(
-        `Failed to update bead because bd update command failed: ${updateResult.stderr}. Try: Verify bead exists with 'bd show ${args.bead_id}', check for invalid characters in description, or inspect .beads/issues.jsonl for corruption.`,
-        `bd update ${args.bead_id} -d ...`,
-        updateResult.exitCode,
+        `Failed to link thread: ${message}`,
+        "beads_link_thread",
       );
     }
-
-    return `Linked bead ${args.bead_id} to thread ${args.thread_id}`;
   },
 });