feat: git merge conflict prevention — auto-rebase + escalation

- Rebase agent branch onto base before merge (reduces conflicts)
- Conflict detection: extract conflicted files, abort safely
- Escalation: task → blocked, review_comment with conflict details, WS notify
- Cleanup consolidation into reusable cleanupBranch()
- 9 new tests, 106 total pass

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: recuu-pfeg

src/__tests__/git-merge.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { rebaseOntoBase, escalateConflict } from "../handlers/git-merge.js";
+import type { ActionContext } from "../agent-templates.js";
+
+describe("rebaseOntoBase", () => {
+  it("returns success when rebase completes without conflict", () => {
+    const exec = vi.fn();
+    const result = rebaseOntoBase("/repo", "agent/builder-abc", "main", exec as never);
+
+    expect(result.success).toBe(true);
+    expect(result.conflictedFiles).toEqual([]);
+    // Should checkout the branch then rebase
+    expect(exec).toHaveBeenCalledTimes(2);
+    expect(exec).toHaveBeenCalledWith(
+      'git checkout "agent/builder-abc"',
+      { cwd: "/repo", stdio: "pipe" }
+    );
+    expect(exec).toHaveBeenCalledWith(
+      'git rebase "main"',
+      { cwd: "/repo", stdio: "pipe" }
+    );
+  });
+
+  it("returns failure with conflicted files when rebase fails", () => {
+    const exec = vi.fn()
+      .mockImplementationOnce(() => {}) // checkout succeeds
+      .mockImplementationOnce(() => { throw new Error("CONFLICT"); }) // rebase fails
+      .mockReturnValueOnce(Buffer.from("src/file-a.ts\nsrc/file-b.ts\n")) // diff --name-only
+      .mockImplementationOnce(() => {}); // rebase --abort
+
+    const result = rebaseOntoBase("/repo", "agent/builder-abc", "main", exec as never);
+
+    expect(result.success).toBe(false);
+    expect(result.conflictedFiles).toEqual(["src/file-a.ts", "src/file-b.ts"]);
+    // Should have called rebase --abort
+    expect(exec).toHaveBeenCalledWith(
+      "git rebase --abort",
+      { cwd: "/repo", stdio: "pipe" }
+    );
+  });
+
+  it("returns failure with empty conflictedFiles when diff also fails", () => {
+    const exec = vi.fn()
+      .mockImplementationOnce(() => {}) // checkout
+      .mockImplementationOnce(() => { throw new Error("CONFLICT"); }) // rebase
+      .mockImplementationOnce(() => { throw new Error("diff failed"); }) // diff fails
+      .mockImplementationOnce(() => {}); // rebase --abort
+
+    const result = rebaseOntoBase("/repo", "agent/builder-abc", "main", exec as never);
+
+    expect(result.success).toBe(false);
+    expect(result.conflictedFiles).toEqual([]);
+  });
+
+  it("handles rebase --abort failure gracefully", () => {
+    const exec = vi.fn()
+      .mockImplementationOnce(() => {}) // checkout
+      .mockImplementationOnce(() => { throw new Error("CONFLICT"); }) // rebase
+      .mockReturnValueOnce(Buffer.from("file.ts\n")) // diff
+      .mockImplementationOnce(() => { throw new Error("abort failed"); }); // abort fails
+
+    const result = rebaseOntoBase("/repo", "agent/builder-abc", "main", exec as never);
+
+    // Should still return the conflict info even if abort fails
+    expect(result.success).toBe(false);
+    expect(result.conflictedFiles).toEqual(["file.ts"]);
+  });
+});
+
+describe("escalateConflict", () => {
+  let ctx: ActionContext;
+  let mockUpdateTask: ReturnType<typeof vi.fn>;
+  let mockOnDataUpdate: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockUpdateTask = vi.fn().mockResolvedValue(undefined);
+    mockOnDataUpdate = vi.fn();
+    ctx = {
+      api: { updateTask: mockUpdateTask } as never,
+      task: { id: "task-123", title: "Test task", description: "desc", status: "in_progress", priority: "p2" },
+      agentName: "builder",
+      config: {
+        apiUrl: "http://localhost:8787",
+        apiKey: "tb_test",
+        workingDir: "/repo",
+        baseBranch: "main",
+      },
+      onDataUpdate: mockOnDataUpdate as (entity: string, id: string, changes: Record<string, unknown>) => void,
+    };
+  });
+
+  it("updates task to blocked with conflict file list", async () => {
+    await escalateConflict(ctx, ["src/a.ts", "src/b.ts"], "agent/builder-abc");
+
+    expect(mockUpdateTask).toHaveBeenCalledWith("task-123", {
+      status: "blocked",
+      review_comment: "Merge conflict on agent/builder-abc: src/a.ts, src/b.ts",
+    });
+  });
+
+  it("broadcasts data update via WS", async () => {
+    await escalateConflict(ctx, ["src/a.ts"], "agent/builder-abc");
+
+    expect(mockOnDataUpdate).toHaveBeenCalledWith("task", "task-123", {
+      status: "blocked",
+      review_comment: "Merge conflict on agent/builder-abc: src/a.ts",
+    });
+  });
+
+  it("handles unknown files when conflict list is empty", async () => {
+    await escalateConflict(ctx, [], "agent/builder-abc");
+
+    expect(mockUpdateTask).toHaveBeenCalledWith("task-123", {
+      status: "blocked",
+      review_comment: "Merge conflict on agent/builder-abc: (unknown files)",
+    });
+  });
+
+  it("does not throw when API update fails", async () => {
+    mockUpdateTask.mockRejectedValue(new Error("network error"));
+
+    // Should not throw
+    await escalateConflict(ctx, ["file.ts"], "agent/builder-abc");
+
+    // WS broadcast should still happen
+    expect(mockOnDataUpdate).toHaveBeenCalled();
+  });
+
+  it("works without onDataUpdate callback", async () => {
+    ctx.onDataUpdate = undefined;
+
+    // Should not throw
+    await escalateConflict(ctx, ["file.ts"], "agent/builder-abc");
+
+    expect(mockUpdateTask).toHaveBeenCalled();
+  });
+});

src/handlers/git-merge.ts

@@ -1,6 +1,11 @@
 /**
  * Handler for the git_merge template action.
  * Merges the agent's worktree branch into the base branch.
+ *
+ * Before merging, attempts a rebase onto the base branch to incorporate
+ * any commits merged by other agents while this agent was working.
+ * If the rebase encounters conflicts, the merge is aborted and the
+ * task is escalated to "blocked" status with conflict details.
  */
 
 import { execSync } from "node:child_process";
@@ -15,14 +20,111 @@ import { resolveRepoRoot } from "../git-ops.js";
 /** Module-level mutex to serialize concurrent merge operations */
 const mergeLock = new Mutex();
 
+/** Result of attempting to rebase a branch onto the base */
+export interface RebaseResult {
+  success: boolean;
+  /** Files that had conflicts (only populated on failure) */
+  conflictedFiles: string[];
+}
+
+/**
+ * Attempt to rebase the worktree branch onto the base branch.
+ * If conflicts are detected, aborts the rebase and returns the conflicted file list.
+ */
+export function rebaseOntoBase(
+  repoDir: string,
+  worktreeBranch: string,
+  baseBranch: string,
+  exec: typeof execSync = execSync
+): RebaseResult {
+  try {
+    // Switch to the worktree branch for rebasing
+    exec(`git checkout "${worktreeBranch}"`, { cwd: repoDir, stdio: "pipe" });
+    exec(`git rebase "${baseBranch}"`, { cwd: repoDir, stdio: "pipe" });
+    return { success: true, conflictedFiles: [] };
+  } catch (err) {
+    // Rebase failed — extract conflicted files before aborting
+    let conflictedFiles: string[] = [];
+    try {
+      const diffOutput = exec(
+        "git diff --name-only --diff-filter=U",
+        { cwd: repoDir, stdio: "pipe" }
+      ).toString().trim();
+      conflictedFiles = diffOutput.split("\n").filter(Boolean);
+    } catch {
+      // Could not list conflicts — still need to abort
+    }
+
+    // Abort the rebase to leave the repo in a clean state
+    try {
+      exec("git rebase --abort", { cwd: repoDir, stdio: "pipe" });
+    } catch {
+      // Already clean or no rebase in progress
+    }
+
+    return { success: false, conflictedFiles };
+  }
+}
+
+/**
+ * Escalate a merge conflict: update task to blocked, record conflict details,
+ * and notify connected clients via WebSocket.
+ */
+export async function escalateConflict(
+  ctx: ActionContext,
+  conflictedFiles: string[],
+  worktreeBranch: string
+): Promise<void> {
+  const fileList = conflictedFiles.length > 0
+    ? conflictedFiles.join(", ")
+    : "(unknown files)";
+  const comment = `Merge conflict on ${worktreeBranch}: ${fileList}`;
+
+  ui.warn(`[git_merge] Conflict detected — ${comment}`);
+
+  // Update task status to blocked with conflict info
+  try {
+    await ctx.api.updateTask(ctx.task.id, {
+      status: "blocked",
+      review_comment: comment,
+    } as unknown as Parameters<typeof ctx.api.updateTask>[1]);
+  } catch {
+    // Non-fatal — log but continue
+    ui.warn("[git_merge] Failed to update task status to blocked");
+  }
+
+  // Broadcast via WS so dashboard shows the conflict immediately
+  if (ctx.onDataUpdate) {
+    ctx.onDataUpdate("task", ctx.task.id, {
+      status: "blocked",
+      review_comment: comment,
+    });
+  }
+}
+
+/**
+ * Clean up worktree directory, prune stale worktree refs, and delete the branch.
+ */
+function cleanupBranch(
+  repoDir: string,
+  worktreeDir: string,
+  worktreeBranch: string,
+  exec: typeof execSync = execSync
+): void {
+  if (existsSync(worktreeDir)) {
+    try { rmSync(worktreeDir, { recursive: true, force: true }); } catch { /* non-fatal */ }
+  }
+  try { exec("git worktree prune", { cwd: repoDir, stdio: "pipe" }); } catch { /* non-fatal */ }
+  try { exec(`git branch -D "${worktreeBranch}"`, { cwd: repoDir, stdio: "pipe" }); } catch { /* non-fatal */ }
+}
+
 export async function handleGitMerge(
   action: TemplateAction,
   ctx: ActionContext,
   phase: "pre" | "post"
 ): Promise<void> {
   const label = action.label ?? "git_merge";
   const gitExec = execSync;
-  const gitExists = existsSync;
   const gitJoin = join;
   // workingDir is the worktree path — we need the main repo root
   const worktreePath = ctx.config.workingDir;
@@ -55,12 +157,7 @@ export async function handleGitMerge(
       if (!agentCommits) {
         ui.warn(`[${phase}] ${label}: no agent commits on ${worktreeBranch} — skipping merge`);
         ctx.mergeSkipped = true;
-        // Clean up the empty branch
-        if (gitExists(worktreeDir)) {
-          try { rmSync(worktreeDir, { recursive: true, force: true }); } catch { /* non-fatal */ }
-        }
-        try { gitExec("git worktree prune", { cwd: repoDir, stdio: "pipe" }); } catch { /* non-fatal */ }
-        try { gitExec(`git branch -D "${worktreeBranch}"`, { cwd: repoDir, stdio: "pipe" }); } catch { /* non-fatal */ }
+        cleanupBranch(repoDir, worktreeDir, worktreeBranch);
         return;
       }
 
@@ -78,27 +175,36 @@ export async function handleGitMerge(
       if (meaningfulFiles.length === 0) {
         ui.warn(`[${phase}] ${label}: only metadata files changed (${diffFiles.join(", ")}) — skipping merge`);
         ctx.mergeSkipped = true;
-        if (gitExists(worktreeDir)) {
-          try { rmSync(worktreeDir, { recursive: true, force: true }); } catch { /* non-fatal */ }
-        }
-        try { gitExec("git worktree prune", { cwd: repoDir, stdio: "pipe" }); } catch { /* non-fatal */ }
-        try { gitExec(`git branch -D "${worktreeBranch}"`, { cwd: repoDir, stdio: "pipe" }); } catch { /* non-fatal */ }
+        cleanupBranch(repoDir, worktreeDir, worktreeBranch);
         return;
       }
 
       ui.info(`[${phase}] ${label}: ${agentCommits.split("\n").length} commit(s), ${meaningfulFiles.length} file(s)`);
+
+      // ── Rebase onto base branch before merging ──
+      // This incorporates any commits merged by other agents while this one was working.
+      // If rebase encounters conflicts, we abort and escalate.
+      const rebaseResult = rebaseOntoBase(repoDir, worktreeBranch, baseBranch);
+      if (!rebaseResult.success) {
+        await escalateConflict(ctx, rebaseResult.conflictedFiles, worktreeBranch);
+        logError(
+          CLI_ERR.GIT_MERGE_FAILED,
+          `Rebase conflict on ${worktreeBranch}: ${rebaseResult.conflictedFiles.join(", ")}`,
+          { taskId: ctx.task.id }
+        );
+        // Clean up — the branch is back to pre-rebase state (rebase --abort was called)
+        cleanupBranch(repoDir, worktreeDir, worktreeBranch);
+        return;
+      }
+
       // Record pre-merge hash for accurate diff in reviewer
       try { ctx.preMergeHash = gitExec("git rev-parse HEAD", { cwd: repoDir, stdio: "pipe" }).toString().trim(); } catch { /* non-fatal */ }
       gitExec(`git checkout "${baseBranch}"`, { cwd: repoDir, stdio: "pipe" });
       gitExec(`git merge --no-ff "${worktreeBranch}" -m "merge: ${worktreeBranch}"`, { cwd: repoDir, stdio: "pipe" });
       ui.info( `[${phase}] ${label}: merged ${worktreeBranch}`);
 
       // Clean up worktree
-      if (gitExists(worktreeDir)) {
-        try { rmSync(worktreeDir, { recursive: true, force: true }); } catch { /* non-fatal */ }
-      }
-      try { gitExec("git worktree prune", { cwd: repoDir, stdio: "pipe" }); } catch { /* non-fatal */ }
-      try { gitExec(`git branch -D "${worktreeBranch}"`, { cwd: repoDir, stdio: "pipe" }); } catch { /* non-fatal */ }
+      cleanupBranch(repoDir, worktreeDir, worktreeBranch);
     } else {
       ui.info( `[${phase}] ${label}: no agent branch found, skipping`);
     }
@@ -107,6 +213,9 @@ export async function handleGitMerge(
     logError(CLI_ERR.GIT_MERGE_FAILED, `git_merge failed: ${msg}`, { taskId: ctx.task.id }, mergeErr);
     ui.warn(`[template] git_merge failed: ${msg}`);
     try { gitExec("git merge --abort", { cwd: repoDir, stdio: "pipe" }); } catch { /* already clean */ }
+
+    // Escalate merge failure to blocked status
+    await escalateConflict(ctx, [], ctx.agentBranch ?? "unknown");
   } finally {
     release();
   }