@gjczone/pi-swarm 0.3.5 → 0.5.0

package/dist/shared/worktree.js

@@ -0,0 +1,417 @@
+/**
+ * worktree - Git worktree isolation for subagents.
+ *
+ * Creates a temporary git worktree so an agent works on an isolated copy of the repo.
+ * On completion:
+ *   - If no changes: worktree is removed.
+ *   - If changes exist: committed to a new branch, worktree is removed.
+ *   - The caller is responsible for merging the branch back (see mergeBranch).
+ *
+ * Safety:
+ *   - Non-git repos silently fall back to cwd (no worktree created).
+ *   - Symbolic links to node_modules are created to avoid reinstalling dependencies.
+ *   - Each worktree is created from HEAD in detached mode; changes are committed to a
+ *     uniquely-named branch to avoid collisions.
+ *
+ * Reference implementation: gotgenes/pi-subagents-worktrees, pi-crew worktree-manager.
+ */
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, symlinkSync, statSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+/**
+ * Detect whether cwd is inside a git repository.
+ */
+export function isGitRepository(cwd) {
+    try {
+        execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd,
+            stdio: "pipe",
+            timeout: 5000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the current branch name or "HEAD" if detached.
+ */
+function getCurrentBranch(cwd) {
+    try {
+        const name = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd,
+            stdio: "pipe",
+            timeout: 5000,
+        })
+            .toString()
+            .trim();
+        return name || "HEAD";
+    }
+    catch {
+        return "HEAD";
+    }
+}
+/**
+ * Get the current HEAD commit SHA.
+ */
+function getCurrentHead(cwd) {
+    try {
+        return execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd,
+            stdio: "pipe",
+            timeout: 5000,
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Check if the working directory is clean (no uncommitted changes).
+ */
+function isWorkingTreeClean(cwd) {
+    try {
+        const status = execFileSync("git", ["status", "--porcelain"], {
+            cwd,
+            stdio: "pipe",
+            timeout: 5000,
+        })
+            .toString()
+            .trim();
+        return status.length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Files/directories to symlink from repo root into worktree for project context.
+ * These contain project rules, config, and state that subagents need access to.
+ */
+const PROJECT_CONTEXT_ENTRIES = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".pi",
+    ".cursorrules",
+    ".cursor",
+    ".github",
+    "docs",
+    "rules",
+];
+/**
+ * Create a temporary worktree for a subagent.
+ * Returns undefined if not in a git repo or worktree creation fails.
+ *
+ * 业务说明：为子 agent 创建临时 git worktree 实现目录隔离。
+ * worktree 基于 HEAD 的 detached 状态创建，确保不污染主分支。
+ * 同时符号链接项目上下文文件（AGENTS.md、.pi 等）和 mailbox 目录，
+ * 这样子 agent 可以访问项目规则并实时读写 mailbox 消息。
+ * 记录原始分支名和 HEAD SHA 用于后续合并。
+ */
+export function createWorktree(cwd, agentId, mailboxPath) {
+    if (!isGitRepository(cwd))
+        return undefined;
+    try {
+        execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd,
+            stdio: "pipe",
+            timeout: 5000,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const originalBranch = getCurrentBranch(cwd);
+    const originalHead = getCurrentHead(cwd);
+    const branch = `pi-agent-${agentId}`;
+    const suffix = randomUUID().slice(0, 8);
+    const worktreePath = join(tmpdir(), `pi-agent-${agentId}-${suffix}`);
+    try {
+        execFileSync("git", ["worktree", "add", "--detach", worktreePath, "HEAD"], {
+            cwd,
+            stdio: "pipe",
+            timeout: 30000,
+        });
+        // Symlink node_modules to avoid reinstalling dependencies in every worktree
+        try {
+            const nodeModulesSource = join(cwd, "node_modules");
+            const nodeModulesTarget = join(worktreePath, "node_modules");
+            if (existsSync(nodeModulesSource) && !existsSync(nodeModulesTarget)) {
+                symlinkSync(nodeModulesSource, nodeModulesTarget, "dir");
+            }
+        }
+        catch {
+            // node_modules symlink failure is non-fatal; agent can still work
+        }
+        // Symlink project context files that are not tracked by git
+        // (AGENTS.md, .pi config, etc.) so subagents inherit project rules
+        let mailboxLinkCreated = false;
+        for (const entry of PROJECT_CONTEXT_ENTRIES) {
+            const sourcePath = join(cwd, entry);
+            const targetPath = join(worktreePath, entry);
+            if (!existsSync(sourcePath) || existsSync(targetPath))
+                continue;
+            try {
+                const stat = statSync(sourcePath);
+                symlinkSync(sourcePath, targetPath, stat.isDirectory() ? "dir" : "file");
+            }
+            catch {
+                // Best effort per-entry symlink
+            }
+        }
+        // Symlink mailbox directory into worktree so subagents can read/write messages in real time
+        if (mailboxPath && existsSync(mailboxPath)) {
+            const mailboxTarget = join(worktreePath, ".pi", "swarm", "mailbox-link");
+            try {
+                mkdirSync(dirname(mailboxTarget), { recursive: true });
+                if (!existsSync(mailboxTarget)) {
+                    symlinkSync(mailboxPath, mailboxTarget, "dir");
+                    mailboxLinkCreated = true;
+                }
+            }
+            catch {
+                // Best effort mailbox link
+            }
+        }
+        return {
+            path: worktreePath,
+            branch,
+            originalBranch,
+            originalHead,
+            repoCwd: cwd,
+            mailboxLinkCreated,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Clean up the worktree after agent completion.
+ *
+ * Steps:
+ * 1. Check for changes in worktree.
+ * 2. If no changes: remove worktree, return { hasChanges: false }.
+ * 3. If changes: add + commit to a new branch based on the commit, remove worktree.
+ *
+ * Note: This function does NOT merge back to the original branch.
+ * Call mergeBranch() after all agents in a batch complete for safe merging.
+ *
+ * 业务说明：子 agent 完成后清理 worktree。有变更则提交到新分支，
+ * 不自动合并——合并应在批处理完成后顺序执行以避免竞争条件。
+ */
+export function cleanupWorktree(cwd, worktree, agentDescription) {
+    if (!existsSync(worktree.path)) {
+        return { hasChanges: false };
+    }
+    try {
+        const status = execFileSync("git", ["status", "--porcelain"], {
+            cwd: worktree.path,
+            stdio: "pipe",
+            timeout: 10000,
+        })
+            .toString()
+            .trim();
+        if (!status) {
+            removeWorktree(cwd, worktree.path);
+            return { hasChanges: false };
+        }
+        // Stage all changes
+        execFileSync("git", ["add", "-A"], {
+            cwd: worktree.path,
+            stdio: "pipe",
+            timeout: 10000,
+        });
+        // Commit in worktree
+        const safeDesc = agentDescription.slice(0, 200);
+        const commitMsg = `pi-agent: ${safeDesc}`;
+        execFileSync("git", ["commit", "-m", commitMsg], {
+            cwd: worktree.path,
+            stdio: "pipe",
+            timeout: 10000,
+        });
+        // Get the commit SHA from worktree
+        const commitSha = execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: worktree.path,
+            stdio: "pipe",
+            timeout: 5000,
+        })
+            .toString()
+            .trim();
+        // Remove worktree first so we can create the branch in the main repo
+        removeWorktree(cwd, worktree.path);
+        // Create branch pointing to the commit in the main repo
+        let branchName = worktree.branch;
+        try {
+            execFileSync("git", ["branch", branchName, commitSha], {
+                cwd,
+                stdio: "pipe",
+                timeout: 5000,
+            });
+        }
+        catch {
+            branchName = `${worktree.branch}-${Date.now()}`;
+            try {
+                execFileSync("git", ["branch", branchName, commitSha], {
+                    cwd,
+                    stdio: "pipe",
+                    timeout: 5000,
+                });
+            }
+            catch {
+                return { hasChanges: true }; // Commit exists but branch creation failed; user can find by SHA
+            }
+        }
+        return { hasChanges: true, branch: branchName };
+    }
+    catch (err) {
+        try {
+            removeWorktree(cwd, worktree.path);
+        }
+        catch {
+            // best effort cleanup
+        }
+        return { hasChanges: false };
+    }
+}
+/**
+ * Merge a branch into the current branch.
+ * Must be called when the working directory is clean (no parallel agents running).
+ * Uses --no-ff --no-edit to create a merge commit preserving history.
+ *
+ * 业务说明：将子 agent 的分支合并到当前分支。必须在工作目录干净时调用
+ * （所有并行 agent 完成后顺序执行）。冲突时返回错误信息并保留分支供手动解决。
+ */
+export function mergeBranch(cwd, branchName) {
+    try {
+        if (!isWorkingTreeClean(cwd)) {
+            return {
+                success: false,
+                branch: branchName,
+                error: `Working directory is dirty. Merge branch '${branchName}' manually after committing/stashing changes.`,
+            };
+        }
+        // Verify the branch exists
+        try {
+            execFileSync("git", ["rev-parse", "--verify", branchName], {
+                cwd,
+                stdio: "pipe",
+                timeout: 5000,
+            });
+        }
+        catch {
+            return {
+                success: false,
+                branch: branchName,
+                error: `Branch '${branchName}' not found.`,
+            };
+        }
+        // Check if already merged by seeing if the branch commit is an ancestor of HEAD
+        try {
+            execFileSync("git", ["merge-base", "--is-ancestor", branchName, "HEAD"], {
+                cwd,
+                stdio: "pipe",
+                timeout: 5000,
+            });
+            // Already merged; clean up branch
+            try {
+                execFileSync("git", ["branch", "-d", branchName], {
+                    cwd,
+                    stdio: "pipe",
+                    timeout: 5000,
+                });
+            }
+            catch {
+                // Best effort cleanup
+            }
+            return { success: true, branch: branchName };
+        }
+        catch {
+            // Not yet merged, proceed
+        }
+        // Attempt merge with --no-ff --no-edit
+        execFileSync("git", ["merge", "--no-ff", "--no-edit", branchName], {
+            cwd,
+            stdio: "pipe",
+            timeout: 30000,
+        });
+        // Clean up feature branch after successful merge
+        try {
+            execFileSync("git", ["branch", "-d", branchName], {
+                cwd,
+                stdio: "pipe",
+                timeout: 5000,
+            });
+        }
+        catch {
+            // Branch deletion failure is non-fatal
+        }
+        return { success: true, branch: branchName };
+    }
+    catch (err) {
+        const stderr = err instanceof Error ? err.message : String(err);
+        // Attempt to abort if a merge is in progress
+        try {
+            execFileSync("git", ["merge", "--abort"], {
+                cwd,
+                stdio: "pipe",
+                timeout: 5000,
+            });
+        }
+        catch {
+            // Merge abort may fail if no merge was in progress
+        }
+        if (stderr.includes("CONFLICT") ||
+            stderr.includes("Automatic merge failed")) {
+            return {
+                success: false,
+                branch: branchName,
+                error: `Merge conflicts detected. Resolve manually: git merge ${branchName}`,
+            };
+        }
+        return {
+            success: false,
+            branch: branchName,
+            error: `Auto-merge failed: ${stderr}`,
+        };
+    }
+}
+function removeWorktree(cwd, worktreePath) {
+    try {
+        execFileSync("git", ["worktree", "remove", "--force", worktreePath], {
+            cwd,
+            stdio: "pipe",
+            timeout: 10000,
+        });
+    }
+    catch {
+        try {
+            execFileSync("git", ["worktree", "prune"], {
+                cwd,
+                stdio: "pipe",
+                timeout: 5000,
+            });
+        }
+        catch {
+            // best effort prune
+        }
+    }
+}
+export function pruneWorktrees(cwd) {
+    try {
+        execFileSync("git", ["worktree", "prune"], {
+            cwd,
+            stdio: "pipe",
+            timeout: 5000,
+        });
+    }
+    catch {
+        // best effort
+    }
+}
+//# sourceMappingURL=worktree.js.map

package/dist/shared/worktree.js.map

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

package/dist/shared/xml.d.ts

@@ -0,0 +1,18 @@
+/**
+ * xml — reusable XML escaping utilities.
+ *
+ * Extracted from render.ts and supervisor.ts to eliminate duplicate
+ * implementations that had drifted apart.
+ */
+/**
+ * Escape a string for use in an XML attribute value.
+ * Handles all five XML special characters: & " ' < >
+ */
+export declare function escapeXmlAttr(value: string): string;
+/**
+ * Escape a string for use in XML element body content.
+ * Escapes only the structural characters (& < >) plus CDATA-closing
+ * sequence (]]>) which would break XML parsing if left unescaped.
+ */
+export declare function escapeXmlBody(value: string): string;
+//# sourceMappingURL=xml.d.ts.map

package/dist/shared/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../src/shared/xml.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/dist/shared/xml.js

@@ -0,0 +1,31 @@
+/**
+ * xml — reusable XML escaping utilities.
+ *
+ * Extracted from render.ts and supervisor.ts to eliminate duplicate
+ * implementations that had drifted apart.
+ */
+/**
+ * Escape a string for use in an XML attribute value.
+ * Handles all five XML special characters: & " ' < >
+ */
+export function escapeXmlAttr(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;");
+}
+/**
+ * Escape a string for use in XML element body content.
+ * Escapes only the structural characters (& < >) plus CDATA-closing
+ * sequence (]]>) which would break XML parsing if left unescaped.
+ */
+export function escapeXmlBody(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("]]>", "]]&gt;");
+}
+//# sourceMappingURL=xml.js.map

package/dist/shared/xml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.js","sourceRoot":"","sources":["../../src/shared/xml.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK;SACT,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC;SACzB,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC;SACzB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK;SACT,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACjC,CAAC"}

package/dist/swarm/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/swarm/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EAEb,MAAM,iCAAiC,CAAC;AA0DzC,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAsR7D"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/swarm/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,YAAY,EAEb,MAAM,iCAAiC,CAAC;AAiEzC,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAmU7D"}

package/dist/swarm/tool.js

@@ -12,6 +12,7 @@ import { SubagentBatchController, resolveSwarmMaxConcurrency, } from "../shared/
 import { renderSwarmResults, toSwarmRunResults } from "../shared/render.js";
 import { spawnSubagent, resumeSubagent, retrySubagent, } from "../shared/spawner.js";
 import { resolveSwarmRoot, createManifest, updateManifest, readManifest, registerAgentInManifest, validateId, } from "../state/persistence.js";
+import { mergeBranch, isGitRepository } from "../shared/worktree.js";
 import { AgentSwarmProgressComponent, snapshotToProgressState, } from "../tui/progress.js";
 /** Widget key used to render the live swarm progress panel. */
 const PROGRESS_WIDGET_KEY = "pi-swarm-progress";
@@ -22,15 +23,21 @@ const DEFAULT_SUBAGENT_TYPE = "coder";
 const PROMPT_TEMPLATE_PLACEHOLDER = "{{item}}";
 const MAX_AGENT_SWARM_SUBAGENTS = 128;
 const DEFAULT_SUBAGENT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
-const AGENT_SWARM_DESCRIPTION = `Launch multiple subagents from one prompt template, existing agent resumes, or both.
-
-Use AgentSwarm when many subagents should run the same kind of task over different inputs. The placeholder is exactly \`{{item}}\`. For example, with \`prompt_template\` set to \`Review {{item}} for likely regressions.\` and \`items\` set to \`["src/a.ts", "src/b.ts"]\`, AgentSwarm launches two new subagents with those two concrete prompts.
-
-Use \`resume_agent_ids\` to continue subagents that already exist from earlier work, such as ones that failed or timed out: map each agent id to the prompt for that resumed subagent (usually \`continue\` if no extra information is needed). You may combine \`resume_agent_ids\` with \`items\` in the same call to resume existing subagents and launch new ones. Do not duplicate resumed work in \`items\`.
-
-AgentSwarm also works for single subagents (1 item).  Use it for any task you want to delegate to a fresh subagent with an isolated context — from 1 to 128 items.  Launches are queued automatically.  Single-agent calls still require \`prompt_template\` with \`{{item}}\` and at least one item.
-
-If \`AgentSwarm\` is called, that call must be the only tool call in the response.`;
+const AGENT_SWARM_DESCRIPTION = [
+    "Launch 1-128 isolated subagents in parallel from a template or resume list.",
+    "",
+    "CRITICAL RULES:",
+    "1. If `items` is provided, `prompt_template` MUST contain {{item}} exactly once.",
+    "2. If only resuming agents, omit both `items` and `prompt_template`.",
+    "3. This tool MUST be the ONLY tool call in your response — do not batch.",
+    "",
+    "QUICK REFERENCE:",
+    '- New subagents: { "items": ["a","b"], "prompt_template": "Review {{item}}" }',
+    '- Resume only: { "resume_agent_ids": { "ag-1": "retry prompt" } }',
+    "- Combined: both fields together (resumes fire first, then spawns).",
+    "",
+    "Use AgentSwarm for parallel independent tasks. Use SwarmTeam for role-based collaboration.",
+].join("\n");
 // ---------------------------------------------------------------------------
 // Registration
 // ---------------------------------------------------------------------------
@@ -42,19 +49,29 @@ export function registerAgentSwarmTool(pi) {
         parameters: Type.Object({
             description: Type.String({
                 description: "Short description for the whole swarm.",
+                examples: ["Review all source files for bugs"],
             }),
             subagent_type: Type.Optional(Type.String({
                 description: "Subagent type used for every spawned subagent. Defaults to coder when omitted.",
+                examples: ["coder"],
             })),
             prompt_template: Type.Optional(Type.String({
-                description: `Prompt template for each subagent. The ${PROMPT_TEMPLATE_PLACEHOLDER} placeholder is replaced with each item value.`,
+                description: `REQUIRED when items is provided. Must contain ${PROMPT_TEMPLATE_PLACEHOLDER} exactly once. Each item replaces the placeholder.`,
+                examples: [
+                    "Fix issues in {{item}}",
+                    "Review {{item}} for security vulnerabilities",
+                ],
             })),
             items: Type.Optional(Type.Array(Type.String(), {
                 maxItems: MAX_AGENT_SWARM_SUBAGENTS,
-                description: "Values used to fill the {{item}} placeholder. Each item launches one new subagent. Supports 1 to 128 items.",
+                description: "REQUIRED with prompt_template. Each item replaces {{item}}. Values are used as {{item}} in the template. Min 1 item, max 128.",
+                examples: [["src/auth.ts", "src/api.ts", "src/db.ts"]],
             })),
             resume_agent_ids: Type.Optional(Type.Record(Type.String(), Type.String(), {
                 description: "Map of existing subagent agent_id to the prompt used to resume that subagent. Resumed subagents launch before new item-based subagents.",
+                examples: [
+                    { "swarm-abc123": "Retry with more focus on XSS detection" },
+                ],
             })),
         }, { additionalProperties: false }),
         execute: async (toolCallId, params, signal, _onUpdate, ctxRaw) => {
@@ -98,6 +115,7 @@ export function registerAgentSwarmTool(pi) {
                         timeout: DEFAULT_SUBAGENT_TIMEOUT_MS,
                         swarmRoot,
                         runId,
+                        useWorktree: true,
                     };
                     if (spec.kind === "resume") {
                         return {
@@ -113,6 +131,8 @@ export function registerAgentSwarmTool(pi) {
                 });
                 // Run with controller
                 const maxConcurrency = resolveSwarmMaxConcurrency(process.cwd());
+                const repoCwd = process.cwd();
+                const inGitRepo = isGitRepository(repoCwd);
                 const controller = new SubagentBatchController({
                     spawn: spawnSubagent,
                     resume: resumeSubagent,
@@ -124,6 +144,13 @@ export function registerAgentSwarmTool(pi) {
                     },
                 });
                 const results = await controller.run();
+                // Collect worktree branches for auto-merge
+                const allBranches = [];
+                for (const r of results) {
+                    if (r.worktreeBranch) {
+                        allBranches.push(r.worktreeBranch);
+                    }
+                }
                 // Register all agents in manifest and mark run completed
                 for (const r of results) {
                     if (r.agentId) {
@@ -136,11 +163,32 @@ export function registerAgentSwarmTool(pi) {
                     manifest.completedAt = Date.now();
                     updateManifest(swarmRoot, manifest);
                 }
+                // Auto-merge worktree branches back to original branch (in Git repos)
+                const mergeResults = [];
+                if (inGitRepo && allBranches.length > 0) {
+                    for (const branch of allBranches) {
+                        try {
+                            const mergeResult = mergeBranch(repoCwd, branch);
+                            if (mergeResult.success) {
+                                mergeResults.push(`Merged: ${branch}`);
+                            }
+                            else {
+                                mergeResults.push(`Merge failed for ${branch}: ${mergeResult.error}`);
+                            }
+                        }
+                        catch (err) {
+                            mergeResults.push(`Merge error for ${branch}: ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                    }
+                }
                 // Trigger completion animation before tearing down
                 progress?.component.complete();
                 // Render output
                 const swarmResults = toSwarmRunResults(results);
-                const output = renderSwarmResults(swarmResults);
+                let output = renderSwarmResults(swarmResults);
+                if (mergeResults.length > 0) {
+                    output += `\n\n<auto_merge>\n${mergeResults.join("\n")}\n</auto_merge>`;
+                }
                 return {
                     content: [{ type: "text", text: output }],
                     details: undefined,
@@ -245,18 +293,24 @@ function createAgentSwarmSpecs(args) {
     const resumeCount = resumeEntries.length;
     const totalCount = resumeCount + itemCount;
     if (!hasMinimumAgentSwarmInputs(itemCount, resumeCount)) {
-        throw new Error("AgentSwarm requires at least 1 item or a resume_agent_ids entry.");
+        throw new Error("AgentSwarm requires at least 1 item or a resume_agent_ids entry. " +
+            'Example with items: { "items": ["src/a.ts"], "prompt_template": "Review {{item}}" }. ' +
+            'Example with resume: { "resume_agent_ids": { "swarm-abc": "Retry with more detail" } }.');
     }
     if (totalCount > MAX_AGENT_SWARM_SUBAGENTS) {
         throw new Error(`AgentSwarm supports at most ${String(MAX_AGENT_SWARM_SUBAGENTS)} subagents.`);
     }
     const promptTemplate = normalizeOptionalString(args.prompt_template);
     if (items.length > 0 && promptTemplate === undefined) {
-        throw new Error("prompt_template is required when items are provided.");
+        throw new Error("prompt_template is required when items are provided. " +
+            'Example: { "prompt_template": "Review {{item}} for bugs", "items": ["src/a.ts", "src/b.ts"] }');
     }
     if (promptTemplate !== undefined &&
         !promptTemplate.includes(PROMPT_TEMPLATE_PLACEHOLDER)) {
-        throw new Error(`prompt_template must include the ${PROMPT_TEMPLATE_PLACEHOLDER} placeholder.`);
+        throw new Error(`prompt_template must include the ${PROMPT_TEMPLATE_PLACEHOLDER} placeholder. ` +
+            `Got: "${promptTemplate.slice(0, 80)}". ` +
+            `Add {{item}} where each item value should be inserted. ` +
+            'Example: "Fix issues in {{item}}"');
     }
     const seenPrompts = new Map();
     const specs = [];