@agentplate/cli 1.0.0

package/src/merge/queue.ts

@@ -0,0 +1,177 @@
+/**
+ * FIFO merge queue backed by SQLite.
+ *
+ * WHY a persisted queue (and not an in-memory array): agent branches become
+ * mergeable asynchronously and from different processes — a worker signals
+ * `merge_ready`, the coordinator (a separate process, possibly a separate run)
+ * drains the queue later. The queue therefore has to survive process exits and
+ * be safe under concurrent access, which is exactly what our WAL-mode SQLite
+ * helper (`openDatabase`) provides.
+ *
+ * FIFO ordering: rows carry a monotonically increasing integer `seq`
+ * (AUTOINCREMENT) used only for ordering. The caller-facing `id` is a random
+ * UUID (per project convention) and says nothing about insertion order, so we
+ * cannot order by it. `seq` is an internal column and never leaves this module.
+ */
+
+import type { Database } from "bun:sqlite";
+
+import { openDatabase } from "../db/sqlite.ts";
+import { NotFoundError } from "../errors.ts";
+import type { MergeEntry, MergeStatus } from "../types.ts";
+
+/** A merge queue handle bound to one SQLite database. */
+export interface MergeQueue {
+	/**
+	 * Append a new entry to the queue. `id`, `createdAt`, and `status` are
+	 * assigned here (status starts as "pending"); the caller supplies the rest.
+	 */
+	enqueue(entry: Omit<MergeEntry, "id" | "createdAt" | "status">): MergeEntry;
+	/** All pending entries, oldest first. */
+	listPending(): MergeEntry[];
+	/** Set the status of an entry by id. Throws {@link NotFoundError} if absent. */
+	markStatus(id: string, status: MergeStatus): void;
+	/**
+	 * Remove and return the oldest pending entry, or null if none remain.
+	 * The returned object reflects its pre-removal `status` ("pending").
+	 */
+	dequeue(): MergeEntry | null;
+	/** Close the underlying database connection. */
+	close(): void;
+}
+
+/** Row shape as stored in SQLite (snake_case columns + internal `seq`). */
+interface MergeQueueRow {
+	seq: number;
+	id: string;
+	branch_name: string;
+	agent_name: string;
+	task_id: string;
+	target_branch: string;
+	status: string;
+	created_at: string;
+}
+
+// `seq` drives FIFO ordering; `id` is the stable public identifier. We index
+// status because every read path (listPending / dequeue) filters on it.
+const CREATE_TABLE = `
+CREATE TABLE IF NOT EXISTS merge_queue (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  id TEXT NOT NULL UNIQUE,
+  branch_name TEXT NOT NULL,
+  agent_name TEXT NOT NULL,
+  task_id TEXT NOT NULL,
+  target_branch TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending'
+    CHECK(status IN ('pending','merged','failed')),
+  created_at TEXT NOT NULL
+)`;
+
+const CREATE_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_merge_queue_status_seq ON merge_queue(status, seq)`;
+
+/** Map a stored row to the public {@link MergeEntry} shape (drops `seq`). */
+function rowToEntry(row: MergeQueueRow): MergeEntry {
+	return {
+		id: row.id,
+		branchName: row.branch_name,
+		agentName: row.agent_name,
+		taskId: row.task_id,
+		targetBranch: row.target_branch,
+		// The CHECK constraint guarantees this is a valid MergeStatus.
+		status: row.status as MergeStatus,
+		createdAt: row.created_at,
+	};
+}
+
+/**
+ * Open (or create) a FIFO merge queue at `dbPath`. Pass `":memory:"` for an
+ * ephemeral queue in tests. The standard project path is
+ * `<root>/.agentplate/merge-queue.db`.
+ */
+export function createMergeQueue(dbPath: string): MergeQueue {
+	const db: Database = openDatabase(dbPath);
+	db.exec(CREATE_TABLE);
+	db.exec(CREATE_INDEX);
+
+	// Prepared statements are reused across calls for the hot paths.
+	const insertStmt = db.query<
+		MergeQueueRow,
+		{
+			$id: string;
+			$branch_name: string;
+			$agent_name: string;
+			$task_id: string;
+			$target_branch: string;
+			$created_at: string;
+		}
+	>(
+		`INSERT INTO merge_queue (id, branch_name, agent_name, task_id, target_branch, created_at)
+		 VALUES ($id, $branch_name, $agent_name, $task_id, $target_branch, $created_at)
+		 RETURNING *`,
+	);
+
+	const listPendingStmt = db.query<MergeQueueRow, []>(
+		"SELECT * FROM merge_queue WHERE status = 'pending' ORDER BY seq ASC",
+	);
+
+	const firstPendingStmt = db.query<MergeQueueRow, []>(
+		"SELECT * FROM merge_queue WHERE status = 'pending' ORDER BY seq ASC LIMIT 1",
+	);
+
+	const getByIdStmt = db.query<MergeQueueRow, { $id: string }>(
+		"SELECT * FROM merge_queue WHERE id = $id",
+	);
+
+	const updateStatusStmt = db.query<void, { $id: string; $status: string }>(
+		"UPDATE merge_queue SET status = $status WHERE id = $id",
+	);
+
+	const deleteBySeqStmt = db.query<void, { $seq: number }>(
+		"DELETE FROM merge_queue WHERE seq = $seq",
+	);
+
+	return {
+		enqueue(entry): MergeEntry {
+			const row = insertStmt.get({
+				$id: crypto.randomUUID(),
+				$branch_name: entry.branchName,
+				$agent_name: entry.agentName,
+				$task_id: entry.taskId,
+				$target_branch: entry.targetBranch,
+				$created_at: new Date().toISOString(),
+			});
+			// RETURNING * always yields a row on a successful INSERT; the guard is
+			// here only to satisfy noUncheckedIndexedAccess-style strictness.
+			if (row === null) {
+				throw new NotFoundError("merge queue insert returned no row");
+			}
+			return rowToEntry(row);
+		},
+
+		listPending(): MergeEntry[] {
+			return listPendingStmt.all().map(rowToEntry);
+		},
+
+		markStatus(id, status): void {
+			const existing = getByIdStmt.get({ $id: id });
+			if (existing === null) {
+				throw new NotFoundError(`No merge queue entry with id "${id}"`);
+			}
+			updateStatusStmt.run({ $id: id, $status: status });
+		},
+
+		dequeue(): MergeEntry | null {
+			const row = firstPendingStmt.get();
+			if (row === null) return null;
+			// Remove by the internal seq so we delete exactly the row we read,
+			// even if two entries somehow shared other column values.
+			deleteBySeqStmt.run({ $seq: row.seq });
+			return rowToEntry(row);
+		},
+
+		close(): void {
+			db.close();
+		},
+	};
+}

package/src/merge/resolver.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Tests for branch merge + conflict resolution.
+ *
+ * Every test runs against a REAL git repository created in a temp directory
+ * (per the project's "never mock what you can use for real" rule). We drive git
+ * through Bun.spawn exactly as the resolver does, so the tests validate true git
+ * behavior — clean merges, conflict detection, abort cleanliness, and the
+ * keep-theirs auto-resolution.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { mergeBranch, predictMerge } from "./resolver.ts";
+
+let repo: string;
+
+/** Run a git command in the test repo, asserting success. Returns stdout. */
+async function git(...args: string[]): Promise<string> {
+	const proc = Bun.spawn(["git", ...args], { cwd: repo, stdout: "pipe", stderr: "pipe" });
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+	if (exitCode !== 0) {
+		throw new Error(`git ${args.join(" ")} failed (exit ${exitCode}): ${stderr}`);
+	}
+	return stdout;
+}
+
+/** Write a file (relative to repo root) and return its absolute path. */
+async function writeFile(rel: string, content: string): Promise<void> {
+	await Bun.write(join(repo, rel), content);
+}
+
+/** Read a tracked file's current working-tree content. */
+async function readFile(rel: string): Promise<string> {
+	return Bun.file(join(repo, rel)).text();
+}
+
+/**
+ * Create a fresh repo on branch `main` with an initial commit containing
+ * `file.txt`. Returns once HEAD is on `main`.
+ */
+async function initRepo(): Promise<void> {
+	await git("init", "-q");
+	// Deterministic identity so commits succeed in CI without global git config.
+	await git("config", "user.email", "test@agentplate.dev");
+	await git("config", "user.name", "Agentplate Test");
+	// Pin the default branch name regardless of the host's init.defaultBranch.
+	await git("checkout", "-q", "-b", "main");
+	await writeFile("file.txt", "line1\nline2\nline3\n");
+	await git("add", "-A");
+	await git("commit", "-q", "-m", "initial");
+}
+
+/** Create `branch` off the current HEAD and check it out. */
+async function branchOff(branch: string): Promise<void> {
+	await git("checkout", "-q", "-b", branch);
+}
+
+/** Switch to an existing branch. */
+async function checkout(branch: string): Promise<void> {
+	await git("checkout", "-q", branch);
+}
+
+/** Commit the current working tree with a message. */
+async function commitAll(message: string): Promise<void> {
+	await git("add", "-A");
+	await git("commit", "-q", "-m", message);
+}
+
+beforeEach(async () => {
+	repo = mkdtempSync(join(tmpdir(), "agentplate-merge-"));
+	await initRepo();
+});
+
+afterEach(() => {
+	rmSync(repo, { recursive: true, force: true });
+});
+
+describe("mergeBranch — clean merge", () => {
+	test("non-conflicting branch merges cleanly", async () => {
+		// Branch touches a NEW file; main is unchanged -> no conflict.
+		await branchOff("agent/clean");
+		await writeFile("feature.txt", "hello from agent\n");
+		await commitAll("add feature.txt");
+
+		await checkout("main");
+		const result = await mergeBranch(repo, "agent/clean", "main");
+
+		expect(result.status).toBe("merged");
+		expect(result.tier).toBe("clean-merge");
+		expect(result.conflictFiles).toEqual([]);
+		expect(result.branchName).toBe("agent/clean");
+
+		// The branch's file is now present on main.
+		expect(await readFile("feature.txt")).toBe("hello from agent\n");
+
+		// A --no-ff merge always records a merge commit (two parents).
+		const parents = (await git("rev-list", "--parents", "-n", "1", "HEAD")).trim().split(/\s+/);
+		expect(parents.length).toBe(3); // commit + 2 parents
+	});
+});
+
+describe("mergeBranch — conflict handling", () => {
+	/** Build a branch that conflicts with main on file.txt's first line. */
+	async function makeConflict(): Promise<void> {
+		await branchOff("agent/conflict");
+		await writeFile("file.txt", "BRANCH-EDIT\nline2\nline3\n");
+		await commitAll("branch edits line1");
+
+		await checkout("main");
+		await writeFile("file.txt", "MAIN-EDIT\nline2\nline3\n");
+		await commitAll("main edits line1");
+	}
+
+	test("autoResolve=false fails and leaves NO in-progress merge", async () => {
+		await makeConflict();
+
+		const result = await mergeBranch(repo, "agent/conflict", "main", { autoResolve: false });
+
+		expect(result.status).toBe("failed");
+		expect(result.tier).toBeNull();
+		expect(result.conflictFiles).toContain("file.txt");
+
+		// Critical: the repo must be clean — no MERGE_HEAD, no conflict markers.
+		// `git rev-parse --verify MERGE_HEAD` must fail (exit != 0).
+		const mh = Bun.spawn(["git", "rev-parse", "--verify", "-q", "MERGE_HEAD"], {
+			cwd: repo,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		expect(await mh.exited).not.toBe(0);
+
+		// Working tree is clean (porcelain output empty).
+		const status = await git("status", "--porcelain");
+		expect(status.trim()).toBe("");
+
+		// main's content is untouched (the conflicting merge was aborted).
+		expect(await readFile("file.txt")).toBe("MAIN-EDIT\nline2\nline3\n");
+	});
+
+	test("autoResolve=true merges by keeping incoming (theirs) changes", async () => {
+		await makeConflict();
+
+		const result = await mergeBranch(repo, "agent/conflict", "main", { autoResolve: true });
+
+		expect(result.status).toBe("merged");
+		expect(result.tier).toBe("auto-resolve");
+		expect(result.conflictFiles).toContain("file.txt");
+
+		// keep-theirs => the incoming branch's version wins.
+		expect(await readFile("file.txt")).toBe("BRANCH-EDIT\nline2\nline3\n");
+
+		// Merge is committed: clean tree, no MERGE_HEAD.
+		const status = await git("status", "--porcelain");
+		expect(status.trim()).toBe("");
+		const mh = Bun.spawn(["git", "rev-parse", "--verify", "-q", "MERGE_HEAD"], {
+			cwd: repo,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		expect(await mh.exited).not.toBe(0);
+	});
+});
+
+describe("predictMerge — side-effect-free", () => {
+	test("reports clean for a non-conflicting branch without changing HEAD", async () => {
+		await branchOff("agent/clean");
+		await writeFile("feature.txt", "x\n");
+		await commitAll("add feature.txt");
+		await checkout("main");
+
+		const headBefore = (await git("rev-parse", "HEAD")).trim();
+		const result = await predictMerge(repo, "agent/clean", "main");
+
+		expect(result.status).toBe("pending");
+		expect(result.tier).toBe("clean-merge");
+		expect(result.conflictFiles).toEqual([]);
+
+		// HEAD unchanged and working tree clean: prediction had no side effects.
+		expect((await git("rev-parse", "HEAD")).trim()).toBe(headBefore);
+		expect((await git("status", "--porcelain")).trim()).toBe("");
+		// The would-be-merged file was NOT brought in.
+		expect(await Bun.file(join(repo, "feature.txt")).exists()).toBe(false);
+	});
+
+	test("reports conflicts without changing HEAD or leaving a merge in progress", async () => {
+		// Conflicting setup.
+		await branchOff("agent/conflict");
+		await writeFile("file.txt", "BRANCH\nline2\nline3\n");
+		await commitAll("branch edit");
+		await checkout("main");
+		await writeFile("file.txt", "MAIN\nline2\nline3\n");
+		await commitAll("main edit");
+
+		const headBefore = (await git("rev-parse", "HEAD")).trim();
+		const result = await predictMerge(repo, "agent/conflict", "main");
+
+		expect(result.status).toBe("pending");
+		expect(result.tier).toBe("auto-resolve");
+		expect(result.conflictFiles).toContain("file.txt");
+
+		// No side effects: HEAD pinned, tree clean, no MERGE_HEAD, content intact.
+		expect((await git("rev-parse", "HEAD")).trim()).toBe(headBefore);
+		expect((await git("status", "--porcelain")).trim()).toBe("");
+		expect(await readFile("file.txt")).toBe("MAIN\nline2\nline3\n");
+		const mh = Bun.spawn(["git", "rev-parse", "--verify", "-q", "MERGE_HEAD"], {
+			cwd: repo,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		expect(await mh.exited).not.toBe(0);
+	});
+});

package/src/merge/resolver.ts

@@ -0,0 +1,274 @@
+/**
+ * Branch merge with tiered conflict resolution.
+ *
+ * Two execution paths share the same git primitives:
+ *
+ *   mergeBranch()   — mutating. Checks out the target branch and runs a real
+ *                     `git merge`. On conflict it either auto-resolves
+ *                     (keep-theirs) or aborts cleanly, depending on `opts`.
+ *   predictMerge()  — side-effect-free. Reports whether a merge WOULD conflict
+ *                     and which tier would apply, WITHOUT touching HEAD or the
+ *                     working tree. Used by `agentplate merge --dry-run`.
+ *
+ * Resolution tiers (this module implements the first two; "ai-resolve" /
+ * "reimagine" from {@link MergeTier} are reserved for a later phase):
+ *
+ *   clean-merge   — `git merge --no-ff` succeeded with no conflicts.
+ *   auto-resolve  — conflicts existed; we took the incoming branch's version of
+ *                   every conflicted file (`git checkout --theirs`) and
+ *                   committed. This is "agent work wins", matching the
+ *                   orchestration model where the branch is the source of truth.
+ *
+ * WHY keep-theirs for auto-resolve: agent worktrees are branched from the
+ * target and own an exclusive file scope, so when a conflict does occur the
+ * branch side is the intended change and the target side is stale. Taking
+ * "theirs" wholesale is the deterministic, no-LLM resolution. Semantically
+ * risky conflicts are a future-phase concern (ai-resolve).
+ */
+
+import { SubprocessError, WorktreeError } from "../errors.ts";
+import type { MergeResult } from "../types.ts";
+
+/** Result of running a git subprocess. */
+interface GitResult {
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+}
+
+/**
+ * Run a git command in `repoRoot` and capture its output. Never throws on a
+ * non-zero exit — callers inspect `exitCode` because for git a non-zero exit is
+ * frequently expected (a merge conflict is exit 1, not a crash).
+ */
+async function runGit(repoRoot: string, args: string[]): Promise<GitResult> {
+	const proc = Bun.spawn(["git", ...args], {
+		cwd: repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+	return { stdout, stderr, exitCode };
+}
+
+/**
+ * Run a git command that is expected to succeed. Throws {@link SubprocessError}
+ * (carrying the git exit code) on any non-zero exit. Use this only for steps
+ * where a failure is genuinely exceptional (checkout of an existing branch,
+ * staging, committing a resolution).
+ */
+async function runGitChecked(repoRoot: string, args: string[]): Promise<GitResult> {
+	const result = await runGit(repoRoot, args);
+	if (result.exitCode !== 0) {
+		throw new SubprocessError(
+			`git ${args.join(" ")} failed (exit ${result.exitCode}): ${result.stderr.trim()}`,
+			result.exitCode,
+		);
+	}
+	return result;
+}
+
+/**
+ * Split git's newline-delimited path output into a clean array, dropping the
+ * trailing empty entry that a final newline produces.
+ */
+function parsePathList(stdout: string): string[] {
+	return stdout
+		.trim()
+		.split("\n")
+		.filter((line) => line.length > 0);
+}
+
+/** Files currently in an unmerged (conflicted) state in the index. */
+async function conflictedFiles(repoRoot: string): Promise<string[]> {
+	const { stdout } = await runGit(repoRoot, ["diff", "--name-only", "--diff-filter=U"]);
+	return parsePathList(stdout);
+}
+
+/** True if a merge is currently in progress (MERGE_HEAD exists). */
+async function mergeInProgress(repoRoot: string): Promise<boolean> {
+	// `git rev-parse --verify -q MERGE_HEAD` exits 0 iff a merge is in progress.
+	const { exitCode } = await runGit(repoRoot, ["rev-parse", "--verify", "-q", "MERGE_HEAD"]);
+	return exitCode === 0;
+}
+
+/** The short name of the currently checked-out branch (empty if detached). */
+async function currentBranch(repoRoot: string): Promise<string> {
+	const { stdout, exitCode } = await runGit(repoRoot, ["symbolic-ref", "--short", "-q", "HEAD"]);
+	return exitCode === 0 ? stdout.trim() : "";
+}
+
+/**
+ * Ensure `branch` is the checked-out branch. No-op when already on it — this
+ * avoids git's "already checked out / would overwrite" error when the target is
+ * current (common when merging straight into the session branch).
+ */
+async function ensureOnBranch(repoRoot: string, branch: string): Promise<void> {
+	if ((await currentBranch(repoRoot)) === branch) return;
+	const { exitCode, stderr } = await runGit(repoRoot, ["checkout", branch]);
+	if (exitCode !== 0) {
+		throw new WorktreeError(`Failed to checkout "${branch}": ${stderr.trim()}`);
+	}
+}
+
+/**
+ * Merge `branchName` into `targetBranch`, resolving conflicts per `opts`.
+ *
+ * Always returns a {@link MergeResult} (never throws for the ordinary
+ * conflict/failure case) so the caller can record an outcome uniformly. It does
+ * throw {@link WorktreeError}/{@link SubprocessError} for genuine git failures
+ * that are not "this branch conflicts" (e.g. the target branch does not exist).
+ *
+ * @param opts.autoResolve When true, conflicts are resolved keep-theirs and
+ *   committed (tier "auto-resolve"). When false (default), a conflicting merge
+ *   is aborted and reported as failed, leaving the repo with no in-progress
+ *   merge.
+ */
+export async function mergeBranch(
+	repoRoot: string,
+	branchName: string,
+	targetBranch: string,
+	opts: { autoResolve?: boolean } = {},
+): Promise<MergeResult> {
+	await ensureOnBranch(repoRoot, targetBranch);
+
+	// --no-ff: always create a merge commit so the branch's history is preserved
+	// as a distinct unit. --no-edit: accept the default merge message
+	// non-interactively (no editor in a headless context).
+	const merge = await runGit(repoRoot, ["merge", "--no-ff", "--no-edit", branchName]);
+
+	if (merge.exitCode === 0) {
+		return {
+			branchName,
+			status: "merged",
+			tier: "clean-merge",
+			conflictFiles: [],
+			message: `Merged ${branchName} into ${targetBranch} cleanly.`,
+		};
+	}
+
+	// Non-zero exit: capture the conflict set. If git failed for a reason other
+	// than a content conflict (e.g. it refused to start the merge), there will be
+	// no unmerged files — surface that as a typed error rather than a silent
+	// "failed with no conflicts".
+	const conflicts = await conflictedFiles(repoRoot);
+	if (conflicts.length === 0) {
+		// Abort any half-started merge so we never leave the repo wedged.
+		if (await mergeInProgress(repoRoot)) {
+			await runGit(repoRoot, ["merge", "--abort"]);
+		}
+		throw new SubprocessError(
+			`git merge of ${branchName} into ${targetBranch} failed without conflicts: ${merge.stderr.trim()}`,
+			merge.exitCode,
+		);
+	}
+
+	if (!opts.autoResolve) {
+		// Leave the repo exactly as we found it: abort the merge so there is no
+		// MERGE_HEAD and `git status` is clean for the next caller.
+		await runGitChecked(repoRoot, ["merge", "--abort"]);
+		return {
+			branchName,
+			status: "failed",
+			tier: null,
+			conflictFiles: conflicts,
+			message: `Merge of ${branchName} into ${targetBranch} conflicts in ${conflicts.length} file(s); auto-resolve disabled, merge aborted.`,
+		};
+	}
+
+	// Auto-resolve: take the incoming branch's version of each conflicted file.
+	// `--theirs` during a merge refers to the branch being merged in (branchName).
+	for (const file of conflicts) {
+		await runGitChecked(repoRoot, ["checkout", "--theirs", "--", file]);
+	}
+	// Stage everything (including any deletes/renames the resolution implies) and
+	// commit the in-progress merge with its default message.
+	await runGitChecked(repoRoot, ["add", "-A"]);
+	await runGitChecked(repoRoot, ["commit", "--no-edit"]);
+
+	return {
+		branchName,
+		status: "merged",
+		tier: "auto-resolve",
+		conflictFiles: conflicts,
+		message: `Merged ${branchName} into ${targetBranch}; auto-resolved ${conflicts.length} conflict(s) by keeping incoming changes.`,
+	};
+}
+
+/**
+ * Predict the outcome of merging `branchName` into `targetBranch` WITHOUT
+ * changing HEAD or the working tree.
+ *
+ * Strategy: a trial `git merge --no-commit --no-ff` followed unconditionally by
+ * `git merge --abort`. We deliberately do NOT use `git merge-tree` here so the
+ * prediction exercises the same merge machinery the real run does (identical
+ * rename/conflict detection), and because `--no-commit` works on every git
+ * version we support. The `--abort` in the `finally` guarantees the repo is
+ * restored even if parsing throws.
+ *
+ * Returned status is "pending" (a prediction, not a completed merge):
+ *   - clean    -> tier "clean-merge", no conflict files
+ *   - conflict -> tier "auto-resolve" (what mergeBranch would apply), files listed
+ */
+export async function predictMerge(
+	repoRoot: string,
+	branchName: string,
+	targetBranch: string,
+): Promise<MergeResult> {
+	await ensureOnBranch(repoRoot, targetBranch);
+
+	// `--no-commit` still applies the merge to the index/worktree, so we MUST
+	// undo it. `--no-ff` forces the merge machinery even for fast-forwardable
+	// branches, matching mergeBranch's behavior.
+	const trial = await runGit(repoRoot, ["merge", "--no-commit", "--no-ff", branchName]);
+	try {
+		if (trial.exitCode === 0) {
+			return {
+				branchName,
+				status: "pending",
+				tier: "clean-merge",
+				conflictFiles: [],
+				message: `${branchName} would merge into ${targetBranch} cleanly.`,
+			};
+		}
+
+		const conflicts = await conflictedFiles(repoRoot);
+		if (conflicts.length === 0) {
+			// Non-zero exit with no unmerged files means git refused the merge for
+			// a structural reason (e.g. unrelated histories). Report it as a failure
+			// prediction rather than inventing a tier.
+			return {
+				branchName,
+				status: "failed",
+				tier: null,
+				conflictFiles: [],
+				message: `${branchName} cannot be merged into ${targetBranch}: ${trial.stderr.trim()}`,
+			};
+		}
+
+		return {
+			branchName,
+			status: "pending",
+			tier: "auto-resolve",
+			conflictFiles: conflicts,
+			message: `${branchName} would conflict with ${targetBranch} in ${conflicts.length} file(s); auto-resolve would keep incoming changes.`,
+		};
+	} finally {
+		// Restore HEAD/index/worktree no matter what. A trial merge that
+		// fast-forwarded or fully applied leaves MERGE_HEAD unset, in which case
+		// `merge --abort` is a harmless no-op error we ignore; when there are
+		// staged-but-uncommitted merge changes, it rewinds them.
+		if (await mergeInProgress(repoRoot)) {
+			await runGit(repoRoot, ["merge", "--abort"]);
+		} else {
+			// A --no-commit merge that did not record MERGE_HEAD (rare) can still
+			// leave staged changes; hard-reset to HEAD to guarantee a clean tree
+			// without altering committed history.
+			await runGit(repoRoot, ["reset", "--hard", "HEAD"]);
+		}
+	}
+}