opencode-swarm-plugin 0.16.0 → 0.17.0

package/.beads/issues.jsonl

@@ -966,6 +966,11 @@
 {"id":"opencode-swarm-plugin-gpse","title":"Workflow test epic","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-08T07:49:11.489232-08:00","updated_at":"2025-12-08T07:49:11.696115-08:00","closed_at":"2025-12-08T07:49:11.696115-08:00"}
 {"id":"opencode-swarm-plugin-gpse.1","title":"Step 1","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:49:11.52435-08:00","updated_at":"2025-12-08T07:49:11.619347-08:00","closed_at":"2025-12-08T07:49:11.619347-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpse.1","depends_on_id":"opencode-swarm-plugin-gpse","type":"parent-child","created_at":"2025-12-08T07:49:11.524725-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-gpse.2","title":"Step 2","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:49:11.56095-08:00","updated_at":"2025-12-08T07:49:11.671061-08:00","closed_at":"2025-12-08T07:49:11.671061-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpse.2","depends_on_id":"opencode-swarm-plugin-gpse","type":"parent-child","created_at":"2025-12-08T07:49:11.561312-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gpusl","title":"DX Improvements: Actionable Errors \u0026 Troubleshooting","description":"Improve developer experience with actionable error messages that tell users HOW to fix problems, add troubleshooting docs, and enhance CLI doctor output.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-13T15:21:23.537986-08:00","updated_at":"2025-12-13T15:26:06.152115-08:00","closed_at":"2025-12-13T15:26:06.152115-08:00"}
+{"id":"opencode-swarm-plugin-gpusl.1","title":"Add troubleshooting section to README","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T15:21:23.645841-08:00","updated_at":"2025-12-13T15:24:59.766004-08:00","closed_at":"2025-12-13T15:24:59.766004-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpusl.1","depends_on_id":"opencode-swarm-plugin-gpusl","type":"parent-child","created_at":"2025-12-13T15:21:23.64819-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gpusl.2","title":"Make BeadError and SwarmError actionable","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T15:21:23.728838-08:00","updated_at":"2025-12-13T15:25:01.061305-08:00","closed_at":"2025-12-13T15:25:01.061305-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpusl.2","depends_on_id":"opencode-swarm-plugin-gpusl","type":"parent-child","created_at":"2025-12-13T15:21:23.730994-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gpusl.3","title":"Make MandateError and storage errors actionable","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T15:21:23.806569-08:00","updated_at":"2025-12-13T15:25:02.21639-08:00","closed_at":"2025-12-13T15:25:02.21639-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpusl.3","depends_on_id":"opencode-swarm-plugin-gpusl","type":"parent-child","created_at":"2025-12-13T15:21:23.808361-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-gpusl.4","title":"Enhance CLI doctor with fix suggestions","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T15:21:23.868538-08:00","updated_at":"2025-12-13T15:25:03.179053-08:00","closed_at":"2025-12-13T15:25:03.179053-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-gpusl.4","depends_on_id":"opencode-swarm-plugin-gpusl","type":"parent-child","created_at":"2025-12-13T15:21:23.869987-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-gq4y","title":"Update test bead","description":"Updated description","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:26.032848-08:00","updated_at":"2025-12-08T11:12:28.256366-08:00","closed_at":"2025-12-08T11:12:28.256366-08:00"}
 {"id":"opencode-swarm-plugin-gr8j","title":"Update test bead","description":"Original description","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-08T11:11:08.754659-08:00","updated_at":"2025-12-08T11:11:11.067841-08:00","closed_at":"2025-12-08T11:11:11.067841-08:00"}
 {"id":"opencode-swarm-plugin-gswv","title":"Bead to start","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:53:44.538704-08:00","updated_at":"2025-12-08T07:53:46.579794-08:00","closed_at":"2025-12-08T07:53:46.579794-08:00"}

package/README.md

@@ -29,19 +29,15 @@ swarm setup
 The setup wizard handles everything:
 
 ```
-┌  opencode-swarm-plugin v0.10.0
+┌  opencode-swarm-plugin v0.16.0
 │
 ◇  Checking dependencies...
 │
 ◆  OpenCode
 ◆  Beads
-◆  Go
-▲  Swarm Mail (optional)
-▲  Redis (optional)
-│
-◆  Install optional dependencies?
-│  ◻ Swarm Mail - Multi-agent coordination
-│  ◻ Redis - Rate limiting
+▲  CASS (optional)
+▲  UBS (optional)
+▲  semantic-memory (optional)
 │
 ◇  Setting up OpenCode integration...
 │
@@ -271,16 +267,14 @@ What NOT to do...
 
 ## Dependencies
 
-| Dependency                                                                                             | Purpose                                                                                                | Required |
-| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | -------- |
-| [OpenCode](https://opencode.ai)                                                                        | Plugin host                                                                                            | Yes      |
-| [Beads](https://github.com/steveyegge/beads)                                                           | Git-backed issue tracking                                                                              | Yes      |
-| [Go](https://go.dev)                                                                                   | Required for Swarm Mail                                                                                | No       |
-| [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) ⭐                               | **The original** - Multi-agent coordination, file reservations. Swarm Mail is built on these patterns. | No       |
-| [CASS (Coding Agent Session Search)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context from past sessions                                                                  | No       |
-| [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner)                | Pre-completion bug scanning using AI-powered static analysis                                           | No       |
-| [semantic-memory](https://github.com/joelhooks/semantic-memory)                                        | Learning persistence                                                                                   | No       |
-| [Redis](https://redis.io)                                                                              | Rate limiting (SQLite fallback available)                                                              | No       |
+| Dependency                                                                                             | Purpose                                                      | Required |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -------- |
+| [OpenCode](https://opencode.ai)                                                                        | Plugin host                                                  | Yes      |
+| [Beads](https://github.com/steveyegge/beads)                                                           | Git-backed issue tracking                                    | Yes      |
+| [CASS (Coding Agent Session Search)](https://github.com/Dicklesworthstone/coding_agent_session_search) | Historical context from past sessions                        | No       |
+| [UBS (Ultimate Bug Scanner)](https://github.com/Dicklesworthstone/ultimate_bug_scanner)                | Pre-completion bug scanning using AI-powered static analysis | No       |
+| [semantic-memory](https://github.com/joelhooks/semantic-memory)                                        | Learning persistence                                         | No       |
+| [Redis](https://redis.io)                                                                              | Rate limiting (SQLite fallback available)                    | No       |
 
 All dependencies are checked and can be installed via `swarm setup`.
 
@@ -298,13 +292,7 @@ curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_sca
 curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/coding_agent_session_search/main/install.sh | bash -s -- --easy-mode
 ```
 
-**MCP Agent Mail** ⭐ - The original multi-agent coordination system. Swarm Mail's embedded implementation is inspired by and compatible with MCP Agent Mail's protocol:
-
-```bash
-curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh" | bash -s -- --yes
-```
-
-> **Note:** The embedded Swarm Mail (PGLite in-process) is now the primary option and works out of the box with no external dependencies. MCP Agent Mail (external Go server) is still supported for advanced use cases requiring a separate server process.
+> **Note:** Swarm Mail is now embedded (PGLite in-process) and works out of the box with no external dependencies. No Go or external servers required.
 
 ## Tools Reference
 
@@ -584,6 +572,34 @@ bun test
 bun run build
 ```
 
+## Troubleshooting
+
+### 1. First Step: Run Doctor
+
+```bash
+swarm doctor
+```
+
+This checks all dependencies and shows their installation status.
+
+### 2. Common Issues
+
+| Issue                       | Cause                              | Solution                                          |
+| --------------------------- | ---------------------------------- | ------------------------------------------------- |
+| `beads: command not found`  | Beads CLI not installed            | `npm install -g @joelhooks/beads`                 |
+| `bd: command not found`     | Same as above                      | `npm install -g @joelhooks/beads`                 |
+| Verification Gate fails     | TypeScript errors or test failures | Fix errors shown, or use `skip_verification=true` |
+| File reservation conflict   | Another agent has the file         | Wait for release, or check `swarmmail_inbox`      |
+| `Mandate not found`         | ID doesn't exist                   | Use `mandate_list` to see available mandates      |
+| Swarm Mail connection error | Database not initialized           | Run `swarm setup` again                           |
+| `Agent not registered`      | Session not initialized            | Call `swarmmail_init` first                       |
+
+### 3. Getting Help
+
+- Run `swarm doctor` for dependency status
+- Check `swarmmail_health` for database status
+- File issues at: https://github.com/joelhooks/opencode-swarm-plugin/issues
+
 ## License
 
 MIT

package/bin/swarm.ts

@@ -670,6 +670,34 @@ If you discover a reusable pattern worth preserving:
 // Commands
 // ============================================================================
 
+/**
+ * Get the fix command for a dependency
+ * Returns null for manual installs (those show a link instead)
+ */
+function getFixCommand(dep: Dependency): string | null {
+  switch (dep.name) {
+    case "OpenCode":
+      return "brew install sst/tap/opencode";
+    case "Beads":
+      return "curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash";
+    case "Go":
+      return "brew install go (or visit https://go.dev/dl/)";
+    case "semantic-memory":
+      return "npm install -g semantic-memory";
+    case "Redis":
+      return "brew install redis && brew services start redis";
+    case "MCP Agent Mail":
+      return "See: https://github.com/Dicklesworthstone/mcp_agent_mail";
+    case "CASS (Coding Agent Session Search)":
+      return "See: https://github.com/Dicklesworthstone/coding_agent_session_search";
+    case "UBS (Ultimate Bug Scanner)":
+      return "See: https://github.com/Dicklesworthstone/ultimate_bug_scanner";
+    default:
+      // Fallback to generic install command if available
+      return dep.installType !== "manual" ? dep.install : null;
+  }
+}
+
 async function doctor() {
   p.intro("swarm doctor v" + VERSION);
 
@@ -689,7 +717,10 @@ async function doctor() {
       p.log.success(dep.name + (version ? " v" + version : ""));
     } else {
       p.log.error(dep.name + " - not found");
-      p.log.message("  Install: " + dep.install);
+      const fixCmd = getFixCommand(dep);
+      if (fixCmd) {
+        p.log.message(dim("   └─ Fix: " + fixCmd));
+      }
     }
   }
 
@@ -701,10 +732,9 @@ async function doctor() {
       );
     } else {
       p.log.warn(dep.name + " - not found (" + dep.description + ")");
-      if (dep.installType !== "manual") {
-        p.log.message("  Install: " + dep.install);
-      } else {
-        p.log.message("  See: " + dep.install);
+      const fixCmd = getFixCommand(dep);
+      if (fixCmd) {
+        p.log.message(dim("   └─ Fix: " + fixCmd));
       }
     }
   }

package/dist/index.js

@@ -29841,7 +29841,7 @@ function parseBead(output) {
     const parsed = JSON.parse(output);
     const data = Array.isArray(parsed) ? parsed[0] : parsed;
     if (!data) {
-      throw new BeadError("No bead data in response", "parse");
+      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 (error45) {
@@ -29851,7 +29851,7 @@ function parseBead(output) {
     if (error45 instanceof BeadError) {
       throw error45;
     }
-    throw new BeadError(`Failed to parse bead JSON: ${output}`, "parse");
+    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");
   }
 }
 function parseBeads(output) {
@@ -29862,7 +29862,7 @@ function parseBeads(output) {
     if (error45 instanceof exports_external.ZodError) {
       throw new BeadValidationError(`Invalid beads data: ${error45.message}`, error45);
     }
-    throw new BeadError(`Failed to parse beads JSON: ${output}`, "parse");
+    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");
   }
 }
 var beads_create = tool({
@@ -29879,14 +29879,14 @@ var beads_create = tool({
     const cmdParts = buildCreateCommand(validated);
     const result = await runBdCommand(cmdParts.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to create bead: ${result.stderr}`, cmdParts.join(" "), result.exitCode, result.stderr);
+      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);
     }
     const stdout = result.stdout.trim();
     if (!stdout) {
-      throw new BeadError("bd create returned empty output", cmdParts.join(" "), 0, "Empty 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");
     }
     if (stdout.startsWith("error:") || stdout.startsWith("Error:")) {
-      throw new BeadError(`bd create failed: ${stdout}`, cmdParts.join(" "), 0, stdout);
+      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);
     }
     const bead = parseBead(stdout);
     return JSON.stringify(bead, null, 2);
@@ -29918,7 +29918,7 @@ var beads_create_epic = tool({
       });
       const epicResult = await runBdCommand(epicCmd.slice(1));
       if (epicResult.exitCode !== 0) {
-        throw new BeadError(`Failed to create epic: ${epicResult.stderr}`, epicCmd.join(" "), epicResult.exitCode);
+        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);
       created.push(epic);
@@ -29936,7 +29936,7 @@ var beads_create_epic = tool({
         });
         const subtaskResult = await runBdCommand(subtaskCmd.slice(1));
         if (subtaskResult.exitCode !== 0) {
-          throw new BeadError(`Failed to create subtask: ${subtaskResult.stderr}`, subtaskCmd.join(" "), subtaskResult.exitCode);
+          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);
         created.push(subtaskBead);
@@ -29992,7 +29992,7 @@ ${rollbackErrors.join(`
 
 No beads to rollback.`;
       }
-      throw new BeadError(`Epic creation failed: ${errorMsg}${rollbackInfo}`, "beads_create_epic", 1);
+      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.`, "beads_create_epic", 1);
     }
   }
 });
@@ -30020,7 +30020,7 @@ var beads_query = tool({
     }
     const result = await runBdCommand(cmd.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to query beads: ${result.stderr}`, cmd.join(" "), result.exitCode);
+      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);
     }
     const beads = parseBeads(result.stdout);
     const limited = beads.slice(0, validated.limit);
@@ -30050,7 +30050,7 @@ var beads_update = tool({
     cmd.push("--json");
     const result = await runBdCommand(cmd.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to update bead: ${result.stderr}`, cmd.join(" "), result.exitCode);
+      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);
     }
     const bead = parseBead(result.stdout);
     return JSON.stringify(bead, null, 2);
@@ -30074,7 +30074,7 @@ var beads_close = tool({
     ];
     const result = await runBdCommand(cmd.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to close bead: ${result.stderr}`, cmd.join(" "), result.exitCode);
+      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);
     }
     const bead = parseBead(result.stdout);
     return `Closed ${bead.id}: ${validated.reason}`;
@@ -30094,7 +30094,7 @@ var beads_start = tool({
       "--json"
     ]);
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to start bead: ${result.stderr}`, `bd update ${args.id} --status in_progress --json`, result.exitCode);
+      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);
     }
     const bead = parseBead(result.stdout);
     return `Started: ${bead.id}`;
@@ -30106,7 +30106,7 @@ var beads_ready = tool({
   async execute(args, ctx) {
     const result = await runBdCommand(["ready", "--json"]);
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to get ready beads: ${result.stderr}`, "bd ready --json", result.exitCode);
+      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);
     }
     const beads = parseBeads(result.stdout);
     if (beads.length === 0) {
@@ -30139,7 +30139,7 @@ var beads_sync = tool({
     };
     const flushResult = await withTimeout(runBdCommand(["sync", "--flush-only"]), TIMEOUT_MS, "bd sync --flush-only");
     if (flushResult.exitCode !== 0) {
-      throw new BeadError(`Failed to flush beads: ${flushResult.stderr}`, "bd sync --flush-only", flushResult.exitCode);
+      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);
     }
     const beadsStatusResult = await runGitCommand([
       "status",
@@ -30150,11 +30150,11 @@ var beads_sync = tool({
     if (hasChanges) {
       const addResult = await runGitCommand(["add", ".beads/"]);
       if (addResult.exitCode !== 0) {
-        throw new BeadError(`Failed to stage beads: ${addResult.stderr}`, "git add .beads/", addResult.exitCode);
+        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/.`, "git add .beads/", addResult.exitCode);
       }
       const commitResult = await withTimeout(runGitCommand(["commit", "-m", "chore: sync beads"]), TIMEOUT_MS, "git commit");
       if (commitResult.exitCode !== 0 && !commitResult.stdout.includes("nothing to commit")) {
-        throw new BeadError(`Failed to commit beads: ${commitResult.stderr}`, "git commit", commitResult.exitCode);
+        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.`, "git commit", commitResult.exitCode);
       }
     }
     if (autoPull) {
@@ -30193,7 +30193,7 @@ var beads_sync = tool({
         }
       }
       if (pullResult.exitCode !== 0) {
-        throw new BeadError(`Failed to pull: ${pullResult.stderr}`, "git pull --rebase", pullResult.exitCode);
+        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.`, "git pull --rebase", pullResult.exitCode);
       }
       const importResult = await withTimeout(runBdCommand(["sync", "--import-only"]), TIMEOUT_MS, "bd sync --import-only");
       if (importResult.exitCode !== 0) {
@@ -30202,7 +30202,7 @@ var beads_sync = tool({
     }
     const pushResult = await withTimeout(runGitCommand(["push"]), TIMEOUT_MS, "git push");
     if (pushResult.exitCode !== 0) {
-      throw new BeadError(`Failed to push: ${pushResult.stderr}`, "git push", pushResult.exitCode);
+      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.`, "git push", pushResult.exitCode);
     }
     const statusResult = await runGitCommand(["status", "--porcelain"]);
     const status = statusResult.stdout.trim();
@@ -30222,7 +30222,7 @@ var beads_link_thread = tool({
   async execute(args, ctx) {
     const queryResult = await runBdCommand(["show", args.bead_id, "--json"]);
     if (queryResult.exitCode !== 0) {
-      throw new BeadError(`Failed to get bead: ${queryResult.stderr}`, `bd show ${args.bead_id} --json`, queryResult.exitCode);
+      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);
     }
     const bead = parseBead(queryResult.stdout);
     const existingDesc = bead.description || "";
@@ -30241,7 +30241,7 @@ ${threadMarker}` : threadMarker;
       "--json"
     ]);
     if (updateResult.exitCode !== 0) {
-      throw new BeadError(`Failed to update bead: ${updateResult.stderr}`, `bd update ${args.bead_id} -d ...`, updateResult.exitCode);
+      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);
     }
     return `Linked bead ${args.bead_id} to thread ${args.thread_id}`;
   }
@@ -34015,7 +34015,7 @@ async function runVerificationGate(filesTouched, skipUbs = false) {
       };
       if (!ubsStep.passed) {
         ubsStep.error = `Found ${ubsResult.summary.critical} critical bugs`;
-        blockers.push(`UBS: ${ubsResult.summary.critical} critical bugs found`);
+        blockers.push(`UBS found ${ubsResult.summary.critical} critical bug(s). Try: Run 'ubs scan ${filesTouched.join(" ")}' to see details, fix critical bugs in reported files, or use skip_ubs_scan=true to bypass (not recommended).`);
       }
       steps.push(ubsStep);
     } else {
@@ -34032,12 +34032,12 @@ async function runVerificationGate(filesTouched, skipUbs = false) {
   const typecheckStep = await runTypecheckVerification();
   steps.push(typecheckStep);
   if (!typecheckStep.passed && !typecheckStep.skipped) {
-    blockers.push(`Typecheck: ${typecheckStep.error?.slice(0, 100) || "failed"}`);
+    blockers.push(`Typecheck failed: ${typecheckStep.error?.slice(0, 100) || "type errors found"}. Try: Run 'tsc --noEmit' to see full errors, check tsconfig.json configuration, or fix reported type errors in modified files.`);
   }
   const testStep = await runTestVerification(filesTouched);
   steps.push(testStep);
   if (!testStep.passed && !testStep.skipped) {
-    blockers.push(`Tests: ${testStep.error?.slice(0, 100) || "failed"}`);
+    blockers.push(`Tests failed: ${testStep.error?.slice(0, 100) || "test failures"}. Try: Run 'bun test ${testStep.command.split(" ").slice(2).join(" ")}' to see full output, check test assertions, or fix failing tests in modified files.`);
   }
   const passedCount = steps.filter((s) => s.passed).length;
   const skippedCount = steps.filter((s) => s.skipped).length;
@@ -34092,8 +34092,8 @@ async function runUbsScan(files) {
         }
       };
     } catch (error45) {
-      console.error(`[swarm] CRITICAL: UBS scan failed to parse JSON output:`, error45);
-      console.error(`[swarm] Raw output:`, output);
+      console.error(`[swarm] CRITICAL: UBS scan failed to parse JSON output because output is malformed:`, error45);
+      console.error(`[swarm] Raw output: ${output}. Try: Run 'ubs doctor' to check installation, verify UBS version with 'ubs --version' (need v1.0.0+), or check if UBS supports --json flag.`);
       return {
         exitCode: result.exitCode,
         bugs: [],
@@ -34183,7 +34183,7 @@ var swarm_complete = tool({
               error: s.error?.slice(0, 200)
             }))
           },
-          hint: "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
+          hint: verificationResult.blockers.length > 0 ? `Fix these issues: ${verificationResult.blockers.map((b, i) => `${i + 1}. ${b}`).join(", ")}. Use skip_verification=true only as last resort.` : "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
           gate_function: "IDENTIFY → RUN → READ → VERIFY → CLAIM (you are at VERIFY, claim blocked)"
         }, null, 2);
       }
@@ -34194,12 +34194,12 @@ var swarm_complete = tool({
       if (ubsResult && ubsResult.summary.critical > 0) {
         return JSON.stringify({
           success: false,
-          error: "UBS found critical bugs - fix before completing",
+          error: `UBS found ${ubsResult.summary.critical} critical bug(s) that must be fixed before completing`,
           ubs_scan: {
             critical_count: ubsResult.summary.critical,
             bugs: ubsResult.bugs.filter((b) => b.severity === "critical")
           },
-          hint: "Fix the critical bugs and try again, or use skip_ubs_scan=true to bypass"
+          hint: `Fix these critical bugs: ${ubsResult.bugs.filter((b) => b.severity === "critical").map((b) => `${b.file}:${b.line} - ${b.message}`).slice(0, 3).join("; ")}. Try: Run 'ubs scan ${args.files_touched?.join(" ") || "."} --json' for full report, fix reported issues, or use skip_ubs_scan=true to bypass (not recommended).`
         }, null, 2);
       }
     }
@@ -34225,7 +34225,7 @@ var swarm_complete = tool({
     }
     const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.quiet().nothrow();
     if (closeResult.exitCode !== 0) {
-      throw new SwarmError(`Failed to close bead: ${closeResult.stderr.toString()}`, "complete");
+      throw new SwarmError(`Failed to close bead because bd close command failed: ${closeResult.stderr.toString()}. Try: Verify bead exists and is not already closed with 'bd show ${args.bead_id}', check if bead ID is correct with 'beads_query()', or use beads_close tool directly.`, "complete");
     }
     try {
       await releaseSwarmFiles({
@@ -35403,7 +35403,7 @@ class SemanticMemoryMandateStorage {
   async update(id, updates) {
     const existing = await this.get(id);
     if (!existing) {
-      throw new Error(`Mandate ${id} not found`);
+      throw new Error(`Mandate '${id}' not found. Use list() to see available mandates.`);
     }
     const updated = { ...existing, ...updates };
     await this.store(updated);
@@ -35411,7 +35411,7 @@ class SemanticMemoryMandateStorage {
   async vote(vote) {
     const existing = await this.hasVoted(vote.mandate_id, vote.agent_name);
     if (existing) {
-      throw new Error(`Agent ${vote.agent_name} has already voted on mandate ${vote.mandate_id}`);
+      throw new Error(`Agent '${vote.agent_name}' has already voted on mandate '${vote.mandate_id}'. Each agent can vote once per mandate to ensure fair consensus.`);
     }
     await this.storeInternal(this.config.collections.votes, vote, {
       id: vote.id,
@@ -35502,7 +35502,7 @@ class InMemoryMandateStorage {
   async update(id, updates) {
     const existing = await this.get(id);
     if (!existing) {
-      throw new Error(`Mandate ${id} not found`);
+      throw new Error(`Mandate '${id}' not found. Use list() to see available mandates.`);
     }
     const updated = { ...existing, ...updates };
     this.entries.set(id, updated);
@@ -35510,7 +35510,7 @@ class InMemoryMandateStorage {
   async vote(vote) {
     const existing = await this.hasVoted(vote.mandate_id, vote.agent_name);
     if (existing) {
-      throw new Error(`Agent ${vote.agent_name} has already voted on mandate ${vote.mandate_id}`);
+      throw new Error(`Agent '${vote.agent_name}' has already voted on mandate '${vote.mandate_id}'. Each agent can vote once per mandate to ensure fair consensus.`);
     }
     this.votes.set(vote.id, vote);
   }
@@ -35565,13 +35565,13 @@ function createMandateStorage(config2 = {}) {
     case "memory":
       return new InMemoryMandateStorage(fullConfig);
     default:
-      throw new Error(`Unknown storage backend: ${fullConfig.backend}`);
+      throw new Error(`Unknown storage backend: '${fullConfig.backend}'. Valid backends are 'semantic-memory' or 'memory'.`);
   }
 }
 async function updateMandateStatus(mandateId, storage) {
   const entry = await storage.get(mandateId);
   if (!entry) {
-    throw new Error(`Mandate ${mandateId} not found`);
+    throw new Error(`Mandate '${mandateId}' not found when calculating score. Use storage.list() to verify the mandate exists.`);
   }
   const score = await storage.calculateScore(mandateId);
   const previousStatus = entry.status;
@@ -35781,11 +35781,11 @@ var mandate_vote = tool({
     const storage = getMandateStorage();
     const mandate = await storage.get(validated.mandate_id);
     if (!mandate) {
-      throw new MandateError(`Mandate ${validated.mandate_id} not found`, "mandate_vote");
+      throw new MandateError(`Mandate '${validated.mandate_id}' not found. Use mandate_list() to see available mandates, or check the ID is correct.`, "mandate_vote");
     }
     const hasVoted = await storage.hasVoted(validated.mandate_id, args.agent_name);
     if (hasVoted) {
-      throw new MandateError(`Agent ${args.agent_name} has already voted on mandate ${validated.mandate_id}`, "mandate_vote");
+      throw new MandateError(`Agent '${args.agent_name}' has already voted on mandate '${validated.mandate_id}'. Each agent can vote once per mandate. This is expected behavior to prevent vote manipulation.`, "mandate_vote");
     }
     const vote = {
       id: generateVoteId(),
@@ -35928,7 +35928,7 @@ var mandate_stats = tool({
       if (args.mandate_id) {
         const mandate = await storage.get(args.mandate_id);
         if (!mandate) {
-          throw new MandateError(`Mandate ${args.mandate_id} not found`, "mandate_stats");
+          throw new MandateError(`Mandate '${args.mandate_id}' not found. Use mandate_list() to see available mandates, or check the ID is correct.`, "mandate_stats");
         }
         const score = await storage.calculateScore(args.mandate_id);
         const votes = await storage.getVotes(args.mandate_id);

package/dist/plugin.js

@@ -29829,7 +29829,7 @@ function parseBead(output) {
     const parsed = JSON.parse(output);
     const data = Array.isArray(parsed) ? parsed[0] : parsed;
     if (!data) {
-      throw new BeadError("No bead data in response", "parse");
+      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 (error45) {
@@ -29839,7 +29839,7 @@ function parseBead(output) {
     if (error45 instanceof BeadError) {
       throw error45;
     }
-    throw new BeadError(`Failed to parse bead JSON: ${output}`, "parse");
+    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");
   }
 }
 function parseBeads(output) {
@@ -29850,7 +29850,7 @@ function parseBeads(output) {
     if (error45 instanceof exports_external.ZodError) {
       throw new BeadValidationError(`Invalid beads data: ${error45.message}`, error45);
     }
-    throw new BeadError(`Failed to parse beads JSON: ${output}`, "parse");
+    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");
   }
 }
 var beads_create = tool({
@@ -29867,14 +29867,14 @@ var beads_create = tool({
     const cmdParts = buildCreateCommand(validated);
     const result = await runBdCommand(cmdParts.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to create bead: ${result.stderr}`, cmdParts.join(" "), result.exitCode, result.stderr);
+      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);
     }
     const stdout = result.stdout.trim();
     if (!stdout) {
-      throw new BeadError("bd create returned empty output", cmdParts.join(" "), 0, "Empty 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");
     }
     if (stdout.startsWith("error:") || stdout.startsWith("Error:")) {
-      throw new BeadError(`bd create failed: ${stdout}`, cmdParts.join(" "), 0, stdout);
+      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);
     }
     const bead = parseBead(stdout);
     return JSON.stringify(bead, null, 2);
@@ -29906,7 +29906,7 @@ var beads_create_epic = tool({
       });
       const epicResult = await runBdCommand(epicCmd.slice(1));
       if (epicResult.exitCode !== 0) {
-        throw new BeadError(`Failed to create epic: ${epicResult.stderr}`, epicCmd.join(" "), epicResult.exitCode);
+        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);
       created.push(epic);
@@ -29924,7 +29924,7 @@ var beads_create_epic = tool({
         });
         const subtaskResult = await runBdCommand(subtaskCmd.slice(1));
         if (subtaskResult.exitCode !== 0) {
-          throw new BeadError(`Failed to create subtask: ${subtaskResult.stderr}`, subtaskCmd.join(" "), subtaskResult.exitCode);
+          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);
         created.push(subtaskBead);
@@ -29980,7 +29980,7 @@ ${rollbackErrors.join(`
 
 No beads to rollback.`;
       }
-      throw new BeadError(`Epic creation failed: ${errorMsg}${rollbackInfo}`, "beads_create_epic", 1);
+      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.`, "beads_create_epic", 1);
     }
   }
 });
@@ -30008,7 +30008,7 @@ var beads_query = tool({
     }
     const result = await runBdCommand(cmd.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to query beads: ${result.stderr}`, cmd.join(" "), result.exitCode);
+      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);
     }
     const beads = parseBeads(result.stdout);
     const limited = beads.slice(0, validated.limit);
@@ -30038,7 +30038,7 @@ var beads_update = tool({
     cmd.push("--json");
     const result = await runBdCommand(cmd.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to update bead: ${result.stderr}`, cmd.join(" "), result.exitCode);
+      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);
     }
     const bead = parseBead(result.stdout);
     return JSON.stringify(bead, null, 2);
@@ -30062,7 +30062,7 @@ var beads_close = tool({
     ];
     const result = await runBdCommand(cmd.slice(1));
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to close bead: ${result.stderr}`, cmd.join(" "), result.exitCode);
+      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);
     }
     const bead = parseBead(result.stdout);
     return `Closed ${bead.id}: ${validated.reason}`;
@@ -30082,7 +30082,7 @@ var beads_start = tool({
       "--json"
     ]);
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to start bead: ${result.stderr}`, `bd update ${args.id} --status in_progress --json`, result.exitCode);
+      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);
     }
     const bead = parseBead(result.stdout);
     return `Started: ${bead.id}`;
@@ -30094,7 +30094,7 @@ var beads_ready = tool({
   async execute(args, ctx) {
     const result = await runBdCommand(["ready", "--json"]);
     if (result.exitCode !== 0) {
-      throw new BeadError(`Failed to get ready beads: ${result.stderr}`, "bd ready --json", result.exitCode);
+      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);
     }
     const beads = parseBeads(result.stdout);
     if (beads.length === 0) {
@@ -30127,7 +30127,7 @@ var beads_sync = tool({
     };
     const flushResult = await withTimeout(runBdCommand(["sync", "--flush-only"]), TIMEOUT_MS, "bd sync --flush-only");
     if (flushResult.exitCode !== 0) {
-      throw new BeadError(`Failed to flush beads: ${flushResult.stderr}`, "bd sync --flush-only", flushResult.exitCode);
+      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);
     }
     const beadsStatusResult = await runGitCommand([
       "status",
@@ -30138,11 +30138,11 @@ var beads_sync = tool({
     if (hasChanges) {
       const addResult = await runGitCommand(["add", ".beads/"]);
       if (addResult.exitCode !== 0) {
-        throw new BeadError(`Failed to stage beads: ${addResult.stderr}`, "git add .beads/", addResult.exitCode);
+        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/.`, "git add .beads/", addResult.exitCode);
       }
       const commitResult = await withTimeout(runGitCommand(["commit", "-m", "chore: sync beads"]), TIMEOUT_MS, "git commit");
       if (commitResult.exitCode !== 0 && !commitResult.stdout.includes("nothing to commit")) {
-        throw new BeadError(`Failed to commit beads: ${commitResult.stderr}`, "git commit", commitResult.exitCode);
+        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.`, "git commit", commitResult.exitCode);
       }
     }
     if (autoPull) {
@@ -30181,7 +30181,7 @@ var beads_sync = tool({
         }
       }
       if (pullResult.exitCode !== 0) {
-        throw new BeadError(`Failed to pull: ${pullResult.stderr}`, "git pull --rebase", pullResult.exitCode);
+        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.`, "git pull --rebase", pullResult.exitCode);
       }
       const importResult = await withTimeout(runBdCommand(["sync", "--import-only"]), TIMEOUT_MS, "bd sync --import-only");
       if (importResult.exitCode !== 0) {
@@ -30190,7 +30190,7 @@ var beads_sync = tool({
     }
     const pushResult = await withTimeout(runGitCommand(["push"]), TIMEOUT_MS, "git push");
     if (pushResult.exitCode !== 0) {
-      throw new BeadError(`Failed to push: ${pushResult.stderr}`, "git push", pushResult.exitCode);
+      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.`, "git push", pushResult.exitCode);
     }
     const statusResult = await runGitCommand(["status", "--porcelain"]);
     const status = statusResult.stdout.trim();
@@ -30210,7 +30210,7 @@ var beads_link_thread = tool({
   async execute(args, ctx) {
     const queryResult = await runBdCommand(["show", args.bead_id, "--json"]);
     if (queryResult.exitCode !== 0) {
-      throw new BeadError(`Failed to get bead: ${queryResult.stderr}`, `bd show ${args.bead_id} --json`, queryResult.exitCode);
+      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);
     }
     const bead = parseBead(queryResult.stdout);
     const existingDesc = bead.description || "";
@@ -30229,7 +30229,7 @@ ${threadMarker}` : threadMarker;
       "--json"
     ]);
     if (updateResult.exitCode !== 0) {
-      throw new BeadError(`Failed to update bead: ${updateResult.stderr}`, `bd update ${args.bead_id} -d ...`, updateResult.exitCode);
+      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);
     }
     return `Linked bead ${args.bead_id} to thread ${args.thread_id}`;
   }
@@ -33846,7 +33846,7 @@ async function runVerificationGate(filesTouched, skipUbs = false) {
       };
       if (!ubsStep.passed) {
         ubsStep.error = `Found ${ubsResult.summary.critical} critical bugs`;
-        blockers.push(`UBS: ${ubsResult.summary.critical} critical bugs found`);
+        blockers.push(`UBS found ${ubsResult.summary.critical} critical bug(s). Try: Run 'ubs scan ${filesTouched.join(" ")}' to see details, fix critical bugs in reported files, or use skip_ubs_scan=true to bypass (not recommended).`);
       }
       steps.push(ubsStep);
     } else {
@@ -33863,12 +33863,12 @@ async function runVerificationGate(filesTouched, skipUbs = false) {
   const typecheckStep = await runTypecheckVerification();
   steps.push(typecheckStep);
   if (!typecheckStep.passed && !typecheckStep.skipped) {
-    blockers.push(`Typecheck: ${typecheckStep.error?.slice(0, 100) || "failed"}`);
+    blockers.push(`Typecheck failed: ${typecheckStep.error?.slice(0, 100) || "type errors found"}. Try: Run 'tsc --noEmit' to see full errors, check tsconfig.json configuration, or fix reported type errors in modified files.`);
   }
   const testStep = await runTestVerification(filesTouched);
   steps.push(testStep);
   if (!testStep.passed && !testStep.skipped) {
-    blockers.push(`Tests: ${testStep.error?.slice(0, 100) || "failed"}`);
+    blockers.push(`Tests failed: ${testStep.error?.slice(0, 100) || "test failures"}. Try: Run 'bun test ${testStep.command.split(" ").slice(2).join(" ")}' to see full output, check test assertions, or fix failing tests in modified files.`);
   }
   const passedCount = steps.filter((s) => s.passed).length;
   const skippedCount = steps.filter((s) => s.skipped).length;
@@ -33923,8 +33923,8 @@ async function runUbsScan(files) {
         }
       };
     } catch (error45) {
-      console.error(`[swarm] CRITICAL: UBS scan failed to parse JSON output:`, error45);
-      console.error(`[swarm] Raw output:`, output);
+      console.error(`[swarm] CRITICAL: UBS scan failed to parse JSON output because output is malformed:`, error45);
+      console.error(`[swarm] Raw output: ${output}. Try: Run 'ubs doctor' to check installation, verify UBS version with 'ubs --version' (need v1.0.0+), or check if UBS supports --json flag.`);
       return {
         exitCode: result.exitCode,
         bugs: [],
@@ -34014,7 +34014,7 @@ var swarm_complete = tool({
               error: s.error?.slice(0, 200)
             }))
           },
-          hint: "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
+          hint: verificationResult.blockers.length > 0 ? `Fix these issues: ${verificationResult.blockers.map((b, i) => `${i + 1}. ${b}`).join(", ")}. Use skip_verification=true only as last resort.` : "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
           gate_function: "IDENTIFY → RUN → READ → VERIFY → CLAIM (you are at VERIFY, claim blocked)"
         }, null, 2);
       }
@@ -34025,12 +34025,12 @@ var swarm_complete = tool({
       if (ubsResult && ubsResult.summary.critical > 0) {
         return JSON.stringify({
           success: false,
-          error: "UBS found critical bugs - fix before completing",
+          error: `UBS found ${ubsResult.summary.critical} critical bug(s) that must be fixed before completing`,
           ubs_scan: {
             critical_count: ubsResult.summary.critical,
             bugs: ubsResult.bugs.filter((b) => b.severity === "critical")
           },
-          hint: "Fix the critical bugs and try again, or use skip_ubs_scan=true to bypass"
+          hint: `Fix these critical bugs: ${ubsResult.bugs.filter((b) => b.severity === "critical").map((b) => `${b.file}:${b.line} - ${b.message}`).slice(0, 3).join("; ")}. Try: Run 'ubs scan ${args.files_touched?.join(" ") || "."} --json' for full report, fix reported issues, or use skip_ubs_scan=true to bypass (not recommended).`
         }, null, 2);
       }
     }
@@ -34056,7 +34056,7 @@ var swarm_complete = tool({
     }
     const closeResult = await Bun.$`bd close ${args.bead_id} --reason ${args.summary} --json`.quiet().nothrow();
     if (closeResult.exitCode !== 0) {
-      throw new SwarmError(`Failed to close bead: ${closeResult.stderr.toString()}`, "complete");
+      throw new SwarmError(`Failed to close bead because bd close command failed: ${closeResult.stderr.toString()}. Try: Verify bead exists and is not already closed with 'bd show ${args.bead_id}', check if bead ID is correct with 'beads_query()', or use beads_close tool directly.`, "complete");
     }
     try {
       await releaseSwarmFiles({
@@ -35234,7 +35234,7 @@ class SemanticMemoryMandateStorage {
   async update(id, updates) {
     const existing = await this.get(id);
     if (!existing) {
-      throw new Error(`Mandate ${id} not found`);
+      throw new Error(`Mandate '${id}' not found. Use list() to see available mandates.`);
     }
     const updated = { ...existing, ...updates };
     await this.store(updated);
@@ -35242,7 +35242,7 @@ class SemanticMemoryMandateStorage {
   async vote(vote) {
     const existing = await this.hasVoted(vote.mandate_id, vote.agent_name);
     if (existing) {
-      throw new Error(`Agent ${vote.agent_name} has already voted on mandate ${vote.mandate_id}`);
+      throw new Error(`Agent '${vote.agent_name}' has already voted on mandate '${vote.mandate_id}'. Each agent can vote once per mandate to ensure fair consensus.`);
     }
     await this.storeInternal(this.config.collections.votes, vote, {
       id: vote.id,
@@ -35333,7 +35333,7 @@ class InMemoryMandateStorage {
   async update(id, updates) {
     const existing = await this.get(id);
     if (!existing) {
-      throw new Error(`Mandate ${id} not found`);
+      throw new Error(`Mandate '${id}' not found. Use list() to see available mandates.`);
     }
     const updated = { ...existing, ...updates };
     this.entries.set(id, updated);
@@ -35341,7 +35341,7 @@ class InMemoryMandateStorage {
   async vote(vote) {
     const existing = await this.hasVoted(vote.mandate_id, vote.agent_name);
     if (existing) {
-      throw new Error(`Agent ${vote.agent_name} has already voted on mandate ${vote.mandate_id}`);
+      throw new Error(`Agent '${vote.agent_name}' has already voted on mandate '${vote.mandate_id}'. Each agent can vote once per mandate to ensure fair consensus.`);
     }
     this.votes.set(vote.id, vote);
   }
@@ -35396,13 +35396,13 @@ function createMandateStorage(config2 = {}) {
     case "memory":
       return new InMemoryMandateStorage(fullConfig);
     default:
-      throw new Error(`Unknown storage backend: ${fullConfig.backend}`);
+      throw new Error(`Unknown storage backend: '${fullConfig.backend}'. Valid backends are 'semantic-memory' or 'memory'.`);
   }
 }
 async function updateMandateStatus(mandateId, storage) {
   const entry = await storage.get(mandateId);
   if (!entry) {
-    throw new Error(`Mandate ${mandateId} not found`);
+    throw new Error(`Mandate '${mandateId}' not found when calculating score. Use storage.list() to verify the mandate exists.`);
   }
   const score = await storage.calculateScore(mandateId);
   const previousStatus = entry.status;
@@ -35566,11 +35566,11 @@ var mandate_vote = tool({
     const storage = getMandateStorage();
     const mandate = await storage.get(validated.mandate_id);
     if (!mandate) {
-      throw new MandateError(`Mandate ${validated.mandate_id} not found`, "mandate_vote");
+      throw new MandateError(`Mandate '${validated.mandate_id}' not found. Use mandate_list() to see available mandates, or check the ID is correct.`, "mandate_vote");
     }
     const hasVoted = await storage.hasVoted(validated.mandate_id, args.agent_name);
     if (hasVoted) {
-      throw new MandateError(`Agent ${args.agent_name} has already voted on mandate ${validated.mandate_id}`, "mandate_vote");
+      throw new MandateError(`Agent '${args.agent_name}' has already voted on mandate '${validated.mandate_id}'. Each agent can vote once per mandate. This is expected behavior to prevent vote manipulation.`, "mandate_vote");
     }
     const vote = {
       id: generateVoteId(),
@@ -35713,7 +35713,7 @@ var mandate_stats = tool({
       if (args.mandate_id) {
         const mandate = await storage.get(args.mandate_id);
         if (!mandate) {
-          throw new MandateError(`Mandate ${args.mandate_id} not found`, "mandate_stats");
+          throw new MandateError(`Mandate '${args.mandate_id}' not found. Use mandate_list() to see available mandates, or check the ID is correct.`, "mandate_stats");
         }
         const score = await storage.calculateScore(args.mandate_id);
         const votes = await storage.getVotes(args.mandate_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-swarm-plugin",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Multi-agent swarm coordination for OpenCode with learning capabilities, beads integration, and Agent Mail",
   "type": "module",
   "main": "dist/index.js",

package/src/beads.ts

@@ -178,7 +178,10 @@ function parseBead(output: string): Bead {
     // 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", "parse");
+      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) {
@@ -191,7 +194,10 @@ function parseBead(output: string): Bead {
     if (error instanceof BeadError) {
       throw error;
     }
-    throw new BeadError(`Failed to parse bead JSON: ${output}`, "parse");
+    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",
+    );
   }
 }
 
@@ -209,7 +215,10 @@ function parseBeads(output: string): Bead[] {
         error,
       );
     }
-    throw new BeadError(`Failed to parse beads JSON: ${output}`, "parse");
+    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",
+    );
   }
 }
 
@@ -249,7 +258,7 @@ export const beads_create = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to create bead: ${result.stderr}`,
+        `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,
@@ -260,7 +269,7 @@ export const beads_create = tool({
     const stdout = result.stdout.trim();
     if (!stdout) {
       throw new BeadError(
-        "bd create returned empty output",
+        "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",
@@ -270,7 +279,7 @@ export const beads_create = tool({
     // Check for error messages in stdout (bd sometimes outputs errors to stdout)
     if (stdout.startsWith("error:") || stdout.startsWith("Error:")) {
       throw new BeadError(
-        `bd create failed: ${stdout}`,
+        `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,
@@ -331,7 +340,7 @@ export const beads_create_epic = tool({
 
       if (epicResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to create epic: ${epicResult.stderr}`,
+          `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,
         );
@@ -361,7 +370,7 @@ export const beads_create_epic = tool({
 
         if (subtaskResult.exitCode !== 0) {
           throw new BeadError(
-            `Failed to create subtask: ${subtaskResult.stderr}`,
+            `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,
           );
@@ -430,7 +439,7 @@ export const beads_create_epic = tool({
       }
 
       throw new BeadError(
-        `Epic creation failed: ${errorMsg}${rollbackInfo}`,
+        `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.`,
         "beads_create_epic",
         1,
       );
@@ -482,7 +491,7 @@ export const beads_query = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to query beads: ${result.stderr}`,
+        `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,
       );
@@ -534,7 +543,7 @@ export const beads_update = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to update bead: ${result.stderr}`,
+        `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,
       );
@@ -570,7 +579,7 @@ export const beads_close = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to close bead: ${result.stderr}`,
+        `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,
       );
@@ -601,7 +610,7 @@ export const beads_start = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to start bead: ${result.stderr}`,
+        `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,
       );
@@ -623,7 +632,7 @@ export const beads_ready = tool({
 
     if (result.exitCode !== 0) {
       throw new BeadError(
-        `Failed to get ready beads: ${result.stderr}`,
+        `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,
       );
@@ -696,7 +705,7 @@ export const beads_sync = tool({
     );
     if (flushResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to flush beads: ${flushResult.stderr}`,
+        `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,
       );
@@ -715,7 +724,7 @@ export const beads_sync = tool({
       const addResult = await runGitCommand(["add", ".beads/"]);
       if (addResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to stage beads: ${addResult.stderr}`,
+          `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/.`,
           "git add .beads/",
           addResult.exitCode,
         );
@@ -732,7 +741,7 @@ export const beads_sync = tool({
         !commitResult.stdout.includes("nothing to commit")
       ) {
         throw new BeadError(
-          `Failed to commit beads: ${commitResult.stderr}`,
+          `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.`,
           "git commit",
           commitResult.exitCode,
         );
@@ -798,7 +807,7 @@ export const beads_sync = tool({
 
       if (pullResult.exitCode !== 0) {
         throw new BeadError(
-          `Failed to pull: ${pullResult.stderr}`,
+          `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.`,
           "git pull --rebase",
           pullResult.exitCode,
         );
@@ -824,7 +833,7 @@ export const beads_sync = tool({
     );
     if (pushResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to push: ${pushResult.stderr}`,
+        `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.`,
         "git push",
         pushResult.exitCode,
       );
@@ -858,7 +867,7 @@ export const beads_link_thread = tool({
 
     if (queryResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to get bead: ${queryResult.stderr}`,
+        `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,
       );
@@ -887,7 +896,7 @@ export const beads_link_thread = tool({
 
     if (updateResult.exitCode !== 0) {
       throw new BeadError(
-        `Failed to update bead: ${updateResult.stderr}`,
+        `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,
       );

package/src/mandate-storage.ts

@@ -383,7 +383,9 @@ export class SemanticMemoryMandateStorage implements MandateStorage {
   async update(id: string, updates: Partial<MandateEntry>): Promise<void> {
     const existing = await this.get(id);
     if (!existing) {
-      throw new Error(`Mandate ${id} not found`);
+      throw new Error(
+        `Mandate '${id}' not found. Use list() to see available mandates.`,
+      );
     }
 
     const updated = { ...existing, ...updates };
@@ -399,7 +401,7 @@ export class SemanticMemoryMandateStorage implements MandateStorage {
     const existing = await this.hasVoted(vote.mandate_id, vote.agent_name);
     if (existing) {
       throw new Error(
-        `Agent ${vote.agent_name} has already voted on mandate ${vote.mandate_id}`,
+        `Agent '${vote.agent_name}' has already voted on mandate '${vote.mandate_id}'. Each agent can vote once per mandate to ensure fair consensus.`,
       );
     }
 
@@ -540,7 +542,9 @@ export class InMemoryMandateStorage implements MandateStorage {
   async update(id: string, updates: Partial<MandateEntry>): Promise<void> {
     const existing = await this.get(id);
     if (!existing) {
-      throw new Error(`Mandate ${id} not found`);
+      throw new Error(
+        `Mandate '${id}' not found. Use list() to see available mandates.`,
+      );
     }
 
     const updated = { ...existing, ...updates };
@@ -553,7 +557,7 @@ export class InMemoryMandateStorage implements MandateStorage {
     const existing = await this.hasVoted(vote.mandate_id, vote.agent_name);
     if (existing) {
       throw new Error(
-        `Agent ${vote.agent_name} has already voted on mandate ${vote.mandate_id}`,
+        `Agent '${vote.agent_name}' has already voted on mandate '${vote.mandate_id}'. Each agent can vote once per mandate to ensure fair consensus.`,
       );
     }
 
@@ -662,7 +666,9 @@ export function createMandateStorage(
     case "memory":
       return new InMemoryMandateStorage(fullConfig);
     default:
-      throw new Error(`Unknown storage backend: ${fullConfig.backend}`);
+      throw new Error(
+        `Unknown storage backend: '${fullConfig.backend}'. Valid backends are 'semantic-memory' or 'memory'.`,
+      );
   }
 }
 
@@ -689,7 +695,9 @@ export async function updateMandateStatus(
 ): Promise<ScoreCalculationResult> {
   const entry = await storage.get(mandateId);
   if (!entry) {
-    throw new Error(`Mandate ${mandateId} not found`);
+    throw new Error(
+      `Mandate '${mandateId}' not found when calculating score. Use storage.list() to verify the mandate exists.`,
+    );
   }
 
   const score = await storage.calculateScore(mandateId);

package/src/mandates.ts

@@ -177,7 +177,7 @@ export const mandate_vote = tool({
     const mandate = await storage.get(validated.mandate_id);
     if (!mandate) {
       throw new MandateError(
-        `Mandate ${validated.mandate_id} not found`,
+        `Mandate '${validated.mandate_id}' not found. Use mandate_list() to see available mandates, or check the ID is correct.`,
         "mandate_vote",
       );
     }
@@ -189,7 +189,7 @@ export const mandate_vote = tool({
     );
     if (hasVoted) {
       throw new MandateError(
-        `Agent ${args.agent_name} has already voted on mandate ${validated.mandate_id}`,
+        `Agent '${args.agent_name}' has already voted on mandate '${validated.mandate_id}'. Each agent can vote once per mandate. This is expected behavior to prevent vote manipulation.`,
         "mandate_vote",
       );
     }
@@ -447,7 +447,7 @@ export const mandate_stats = tool({
         const mandate = await storage.get(args.mandate_id);
         if (!mandate) {
           throw new MandateError(
-            `Mandate ${args.mandate_id} not found`,
+            `Mandate '${args.mandate_id}' not found. Use mandate_list() to see available mandates, or check the ID is correct.`,
             "mandate_stats",
           );
         }

package/src/swarm.ts

@@ -2039,7 +2039,9 @@ async function runVerificationGate(
 
       if (!ubsStep.passed) {
         ubsStep.error = `Found ${ubsResult.summary.critical} critical bugs`;
-        blockers.push(`UBS: ${ubsResult.summary.critical} critical bugs found`);
+        blockers.push(
+          `UBS found ${ubsResult.summary.critical} critical bug(s). Try: Run 'ubs scan ${filesTouched.join(" ")}' to see details, fix critical bugs in reported files, or use skip_ubs_scan=true to bypass (not recommended).`,
+        );
       }
 
       steps.push(ubsStep);
@@ -2060,7 +2062,7 @@ async function runVerificationGate(
   steps.push(typecheckStep);
   if (!typecheckStep.passed && !typecheckStep.skipped) {
     blockers.push(
-      `Typecheck: ${typecheckStep.error?.slice(0, 100) || "failed"}`,
+      `Typecheck failed: ${typecheckStep.error?.slice(0, 100) || "type errors found"}. Try: Run 'tsc --noEmit' to see full errors, check tsconfig.json configuration, or fix reported type errors in modified files.`,
     );
   }
 
@@ -2068,7 +2070,9 @@ async function runVerificationGate(
   const testStep = await runTestVerification(filesTouched);
   steps.push(testStep);
   if (!testStep.passed && !testStep.skipped) {
-    blockers.push(`Tests: ${testStep.error?.slice(0, 100) || "failed"}`);
+    blockers.push(
+      `Tests failed: ${testStep.error?.slice(0, 100) || "test failures"}. Try: Run 'bun test ${testStep.command.split(" ").slice(2).join(" ")}' to see full output, check test assertions, or fix failing tests in modified files.`,
+    );
   }
 
   // Build summary
@@ -2150,10 +2154,12 @@ async function runUbsScan(files: string[]): Promise<UbsScanResult | null> {
     } catch (error) {
       // UBS output wasn't JSON - this is an error condition
       console.error(
-        `[swarm] CRITICAL: UBS scan failed to parse JSON output:`,
+        `[swarm] CRITICAL: UBS scan failed to parse JSON output because output is malformed:`,
         error,
       );
-      console.error(`[swarm] Raw output:`, output);
+      console.error(
+        `[swarm] Raw output: ${output}. Try: Run 'ubs doctor' to check installation, verify UBS version with 'ubs --version' (need v1.0.0+), or check if UBS supports --json flag.`,
+      );
       return {
         exitCode: result.exitCode,
         bugs: [],
@@ -2320,7 +2326,10 @@ export const swarm_complete = tool({
                 error: s.error?.slice(0, 200),
               })),
             },
-            hint: "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
+            hint:
+              verificationResult.blockers.length > 0
+                ? `Fix these issues: ${verificationResult.blockers.map((b, i) => `${i + 1}. ${b}`).join(", ")}. Use skip_verification=true only as last resort.`
+                : "Fix the failing checks and try again. Use skip_verification=true only as last resort.",
             gate_function:
               "IDENTIFY → RUN → READ → VERIFY → CLAIM (you are at VERIFY, claim blocked)",
           },
@@ -2345,12 +2354,18 @@ export const swarm_complete = tool({
         return JSON.stringify(
           {
             success: false,
-            error: "UBS found critical bugs - fix before completing",
+            error: `UBS found ${ubsResult.summary.critical} critical bug(s) that must be fixed before completing`,
             ubs_scan: {
               critical_count: ubsResult.summary.critical,
               bugs: ubsResult.bugs.filter((b) => b.severity === "critical"),
             },
-            hint: "Fix the critical bugs and try again, or use skip_ubs_scan=true to bypass",
+            hint: `Fix these critical bugs: ${ubsResult.bugs
+              .filter((b) => b.severity === "critical")
+              .map((b) => `${b.file}:${b.line} - ${b.message}`)
+              .slice(0, 3)
+              .join(
+                "; ",
+              )}. Try: Run 'ubs scan ${args.files_touched?.join(" ") || "."} --json' for full report, fix reported issues, or use skip_ubs_scan=true to bypass (not recommended).`,
           },
           null,
           2,
@@ -2398,7 +2413,7 @@ export const swarm_complete = tool({
 
     if (closeResult.exitCode !== 0) {
       throw new SwarmError(
-        `Failed to close bead: ${closeResult.stderr.toString()}`,
+        `Failed to close bead because bd close command failed: ${closeResult.stderr.toString()}. Try: Verify bead exists and is not already closed with 'bd show ${args.bead_id}', check if bead ID is correct with 'beads_query()', or use beads_close tool directly.`,
         "complete",
       );
     }