@rethunk/mcp-multi-root-git 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to `@rethunk/mcp-multi-root-git` are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com); the project uses [Semantic Versioning](https://semver.org).
+
+## [2.2.0] — 2026-04-17
+
+Mutating git operations: merge, cherry-pick, and optional push-after for `batch_commit`.
+
+### Added
+
+- **`git_merge`** tool — merge one or more source branches into a destination. Default strategy `auto` cascades fast-forward → rebase → merge-commit per source, preferring linear history. Refuses on dirty tree; stops on first conflict with structured path report. Optional `deleteMergedBranches` / `deleteMergedWorktrees` cascade cleanup, always skipping protected names (`main`, `master`, `dev`, `develop`, `stable`, `trunk`, `prod`, `production`, `release*`, `hotfix*`).
+- **`git_cherry_pick`** tool — play commits from one or more sources onto a destination. Sources may be SHAs, `A..B` ranges, or branch names (expanded to `onto..<branch>`, oldest-first). Uses `--empty=drop` so patch-equivalent re-applies add nothing. Refuses on dirty tree; stops on first conflict, aborting cleanly. Same protected-name cleanup flags as `git_merge`.
+- **`batch_commit`** `push: "after"` — push the current branch to its upstream once every commit in the batch lands. Omitted by default; no behavior change for existing callers.
+
+### Changed
+
+- **Internal** — shared ref/branch helpers extracted to a common module; merge/cherry-pick/batch-commit implementations now reuse the same dirty-tree guards, protected-name checks, and upstream detection.
+- **Tooling** — Biome upgraded to 2.4.11; dev dependency refresh.
+
+### Documentation
+
+- `docs/mcp-tools.md` — `git_merge` and `git_cherry_pick` sections with parameters, JSON shape, and error codes; `batch_commit` `push: "after"` option documented.
+
+## [2.1.0] — prior
+
+- Added `git_log` — path-filtered, time-windowed log across workspace roots.
+- Added `git_diff_summary` — structured, token-efficient diff viewer with per-file truncation and default exclusions (lock files, `dist`, vendor).
+- Added `batch_commit` — sequential multi-commit tool. Mutating, not idempotent.
+- Test harness: fake-server duck-type lets unit tests drive the full FastMCP execute path without a live transport.
+
+## [2.0.1] — prior
+
+- Bug fixes and internal cleanup; no public tool-surface change.
+
+## [2.0.0] — prior
+
+- **Breaking:** JSON response envelope removed. `MCP_JSON_FORMAT_VERSION` now `"2"`; payloads are minified, and optional fields are omitted when empty / `null` / `false` (consumers test for presence, not equality to `null`).
+- Initial preset file schema (`.rethunk/git-mcp-presets.json`) with wrapped and legacy-map layouts.
+
+## [1.0.0] — prior
+
+- Initial release: `git_status`, `git_inventory`, `git_parity`, `list_presets`.
+
+[2.2.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.2.0
+[2.1.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.1.0
+[2.0.1]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.0.1
+[2.0.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.0.0
+[1.0.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v1.0.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/%40rethunk%2Fmcp-multi-root-git.svg)](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**git** tools over MCP: read-only status, multi-root inventory, `HEAD` parity, presets, structured diff viewer, and batch commit. **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
+**git** tools over MCP: read-only status, multi-root inventory, `HEAD` parity, presets, structured diff viewer, batch commit, merge, and cherry-pick. **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
 
 **Repository:** [github.com/Rethunk-AI/mcp-multi-root-git](https://github.com/Rethunk-AI/mcp-multi-root-git) · **npmjs (manual releases):** [`@rethunk/mcp-multi-root-git`](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git) · **GitHub Packages (CI on each tag):** [`@rethunk-ai/mcp-multi-root-git`](https://github.com/Rethunk-AI/mcp-multi-root-git/packages) — see [docs/install.md](docs/install.md) and [HUMANS.md](HUMANS.md) Publishing.
 

package/dist/server/batch-commit-tool.js

@@ -1,19 +1,68 @@
 import { z } from "zod";
 import { isStrictlyUnderGitTop, resolvePathForRepo } from "../repo-paths.js";
 import { gitTopLevel, spawnGitAsync } from "./git.js";
-import { jsonRespond, spreadDefined } from "./json.js";
+import { getCurrentBranch } from "./git-refs.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
 import { requireGitAndRoots } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
 const CommitEntrySchema = z.object({
     message: z.string().min(1).describe("Commit message."),
     files: z.array(z.string().min(1)).min(1).describe("Paths to stage, relative to the git root."),
 });
+const PushModeSchema = z
+    .enum(["never", "after"])
+    .optional()
+    .default("never")
+    .describe("`never` (default): no push. `after`: push the current branch to its upstream once all commits succeed; " +
+    "fails with `push_no_upstream` if the branch has no upstream (commits are NOT rolled back). " +
+    "Enum reserved for future modes such as `force-with-lease`.");
+/**
+ * After all commits succeed, push the current branch to its upstream.
+ * Commits are already applied at this point — do NOT attempt rollback on push failure.
+ */
+async function runPushAfter(gitTop) {
+    const branch = await getCurrentBranch(gitTop);
+    if (!branch) {
+        return { ok: false, error: "push_detached_head" };
+    }
+    // Verify upstream exists before attempting push (avoids side effects of auto-set-upstream).
+    const upstreamProbe = await spawnGitAsync(gitTop, [
+        "rev-parse",
+        "--abbrev-ref",
+        "--symbolic-full-name",
+        "@{u}",
+    ]);
+    if (!upstreamProbe.ok) {
+        return {
+            ok: false,
+            branch,
+            error: "push_no_upstream",
+            detail: (upstreamProbe.stderr || upstreamProbe.stdout).trim(),
+        };
+    }
+    const upstream = upstreamProbe.stdout.trim();
+    // Explicit remote + branch so a future push refspec change to the upstream does not surprise us.
+    const slash = upstream.indexOf("/");
+    const remote = slash > 0 ? upstream.slice(0, slash) : "origin";
+    const pushResult = await spawnGitAsync(gitTop, ["push", remote, branch]);
+    if (!pushResult.ok) {
+        return {
+            ok: false,
+            branch,
+            upstream,
+            error: "push_failed",
+            detail: (pushResult.stderr || pushResult.stdout).trim(),
+        };
+    }
+    return { ok: true, branch, upstream };
+}
 export function registerBatchCommitTool(server) {
     server.addTool({
         name: "batch_commit",
         description: "Create multiple sequential git commits in a single call. " +
             "Each entry stages the listed files then commits with the given message. " +
-            "Stops on first failure. See docs/mcp-tools.md.",
+            'Stops on first failure. Optional `push: "after"` pushes the current branch ' +
+            "to its upstream once all commits succeed. See docs/mcp-tools.md.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -25,6 +74,7 @@ export function registerBatchCommitTool(server) {
                 .min(1)
                 .max(50)
                 .describe("Commits to create, applied in order."),
+            push: PushModeSchema,
         }),
         execute: async (args) => {
             const pre = requireGitAndRoots(server, args, undefined);
@@ -99,6 +149,8 @@ export function registerBatchCommitTool(server) {
                 });
             }
             const allOk = results.length === args.commits.length && results.every((r) => r.ok);
+            // --- Optional push after all commits succeed ---
+            const push = allOk && args.push === "after" ? await runPushAfter(gitTop) : undefined;
             if (args.format === "json") {
                 return jsonRespond({
                     ok: allOk,
@@ -113,6 +165,15 @@ export function registerBatchCommitTool(server) {
                         ...spreadDefined("error", r.error),
                         ...spreadDefined("detail", r.detail),
                     })),
+                    ...spreadWhen(push !== undefined, {
+                        push: {
+                            ok: push?.ok ?? false,
+                            ...spreadDefined("branch", push?.branch),
+                            ...spreadDefined("upstream", push?.upstream),
+                            ...spreadDefined("error", push?.error),
+                            ...spreadDefined("detail", push?.detail),
+                        },
+                    }),
                 });
             }
             // --- Markdown ---
@@ -133,6 +194,15 @@ export function registerBatchCommitTool(server) {
                 const skipped = args.commits.length - results.length;
                 lines.push("", `${skipped} remaining commit(s) skipped.`);
             }
+            if (push) {
+                lines.push("");
+                if (push.ok) {
+                    lines.push(`Push: ✓ ${push.branch} → ${push.upstream}`);
+                }
+                else {
+                    lines.push(`Push: ✗ ${push.error}${push.detail ? ` — ${push.detail}` : ""}`);
+                }
+            }
             return lines.join("\n");
         },
     });

package/dist/server/git-cherry-pick-tool.js

@@ -0,0 +1,299 @@
+import { z } from "zod";
+import { gitTopLevel, spawnGitAsync } from "./git.js";
+import { commitListBetween, getCurrentBranch, isFullyMergedInto, isProtectedBranch, isSafeGitRangeToken, isSafeGitRefToken, isWorkingTreeClean, resolveRef, worktreeForBranch, } from "./git-refs.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function conflictPaths(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["diff", "--name-only", "--diff-filter=U"]);
+    if (!r.ok)
+        return [];
+    return r.stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+async function cherryPickHead(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["rev-parse", "--verify", "--quiet", "CHERRY_PICK_HEAD"]);
+    if (!r.ok)
+        return undefined;
+    const sha = r.stdout.trim();
+    return sha === "" ? undefined : sha;
+}
+async function abortCherryPick(gitTop) {
+    await spawnGitAsync(gitTop, ["cherry-pick", "--abort"]);
+}
+async function branchExists(gitTop, name) {
+    const r = await spawnGitAsync(gitTop, ["show-ref", "--verify", "--quiet", `refs/heads/${name}`]);
+    return r.ok;
+}
+/**
+ * Expand a source spec into a list of SHAs to cherry-pick.
+ * - `A..B` / `A...B` → `git rev-list --reverse` of the range
+ * - branch name (refs/heads/<name> exists) → `onto..<branch>` oldest-first
+ * - SHA or ref → single commit
+ */
+async function resolveSource(gitTop, onto, raw) {
+    if (raw.includes("..")) {
+        if (!isSafeGitRangeToken(raw)) {
+            return { error: "unsafe_ref_token", raw };
+        }
+        const r = await spawnGitAsync(gitTop, ["rev-list", "--reverse", raw]);
+        if (!r.ok) {
+            return {
+                error: "range_resolution_failed",
+                detail: (r.stderr || r.stdout).trim(),
+                raw,
+            };
+        }
+        const commits = r.stdout
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0);
+        return { raw, kind: "range", commits };
+    }
+    if (!isSafeGitRefToken(raw)) {
+        return { error: "unsafe_ref_token", raw };
+    }
+    if (await branchExists(gitTop, raw)) {
+        const commits = await commitListBetween(gitTop, onto, raw);
+        if (commits === null) {
+            return { error: "range_resolution_failed", raw };
+        }
+        return { raw, kind: "branch", commits };
+    }
+    const sha = await resolveRef(gitTop, raw);
+    if (!sha) {
+        return { error: "source_not_found", raw };
+    }
+    return { raw, kind: "sha", commits: [sha] };
+}
+/**
+ * Pre-filter already-in-destination commits (they would cherry-pick to empty).
+ * Also dedupe across sources while preserving first-seen order per-commit.
+ */
+async function filterAndDedupe(gitTop, onto, resolved) {
+    const seen = new Set();
+    const picks = [];
+    const perSourceKept = new Map();
+    for (const src of resolved) {
+        const kept = [];
+        for (const sha of src.commits) {
+            if (seen.has(sha))
+                continue;
+            seen.add(sha);
+            // Skip commits already reachable from destination (would produce empty commits).
+            const contained = await spawnGitAsync(gitTop, ["merge-base", "--is-ancestor", sha, onto]);
+            if (contained.ok)
+                continue; // already in destination
+            picks.push(sha);
+            kept.push(sha);
+        }
+        perSourceKept.set(src.raw, kept);
+    }
+    return { picks, perSourceKept };
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitCherryPickTool(server) {
+    server.addTool({
+        name: "git_cherry_pick",
+        description: "Play commits from one or more sources onto a destination. Sources may be SHAs, " +
+            "`A..B` ranges, or branch names (expanded to `onto..<branch>`, oldest-first). " +
+            "Commits already reachable from the destination are skipped. Refuses on dirty tree; " +
+            "stops on the first conflict and reports paths. Optional flags auto-delete fully " +
+            "merged source branches and their worktrees, skipping protected names. See docs/mcp-tools.md.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            sources: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(50)
+                .describe("Sources to cherry-pick: SHA, `A..B` range, or branch name. Branch sources " +
+                "resolve to `onto..<branch>` (only commits missing from destination)."),
+            onto: z
+                .string()
+                .optional()
+                .describe("Destination branch. Defaults to the currently checked-out branch."),
+            deleteMergedBranches: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("After all commits apply, delete each branch-kind source locally " +
+                "(`git branch -d`) when it is fully merged into the destination. " +
+                "Protected names always skipped; never touches remote refs."),
+            deleteMergedWorktrees: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("After success, remove any local worktree attached to a branch-kind source " +
+                "(`git worktree remove`). Protected tails always skipped."),
+        }),
+        execute: async (args) => {
+            const pre = requireGitAndRoots(server, args, undefined);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const rootInput = pre.roots[0];
+            if (!rootInput)
+                return jsonRespond({ error: "no_workspace_root" });
+            const gitTop = gitTopLevel(rootInput);
+            if (!gitTop)
+                return jsonRespond({ error: "not_a_git_repository", path: rootInput });
+            // --- Resolve destination ---
+            const startBranch = await getCurrentBranch(gitTop);
+            const onto = args.onto?.trim() || startBranch;
+            if (!onto)
+                return jsonRespond({ error: "onto_detached_head" });
+            if (args.onto !== undefined && !isSafeGitRefToken(args.onto)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.onto });
+            }
+            // --- Refuse dirty tree ---
+            if (!(await isWorkingTreeClean(gitTop))) {
+                return jsonRespond({ error: "working_tree_dirty" });
+            }
+            // --- Ensure destination is checked out ---
+            if (onto !== startBranch) {
+                const co = await spawnGitAsync(gitTop, ["checkout", onto]);
+                if (!co.ok) {
+                    return jsonRespond({
+                        error: "checkout_failed",
+                        detail: (co.stderr || co.stdout).trim(),
+                    });
+                }
+            }
+            if (!(await resolveRef(gitTop, onto))) {
+                return jsonRespond({ error: "destination_not_found", ref: onto });
+            }
+            // --- Resolve each source ---
+            const resolved = [];
+            for (const raw of args.sources) {
+                const r = await resolveSource(gitTop, onto, raw);
+                if ("error" in r) {
+                    return jsonRespond({
+                        error: r.error,
+                        source: raw,
+                        ...spreadDefined("detail", r.detail),
+                    });
+                }
+                resolved.push(r);
+            }
+            // --- Dedupe + skip already-present ---
+            const { picks, perSourceKept } = await filterAndDedupe(gitTop, onto, resolved);
+            // --- Apply cherry-pick (single atomic call) ---
+            // `--empty=drop` silently drops commits that would produce no change against the
+            // current tip — makes the tool idempotent when the same patch is re-applied.
+            let conflict;
+            let appliedCount = 0;
+            const preHeadProbe = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const preHead = preHeadProbe.ok ? preHeadProbe.stdout.trim() : "";
+            if (picks.length > 0) {
+                const r = await spawnGitAsync(gitTop, ["cherry-pick", "--empty=drop", ...picks]);
+                if (!r.ok) {
+                    const failedSha = await cherryPickHead(gitTop);
+                    const paths = await conflictPaths(gitTop);
+                    await abortCherryPick(gitTop);
+                    conflict = {
+                        stage: "cherry-pick",
+                        ...spreadDefined("commit", failedSha),
+                        paths,
+                        detail: (r.stderr || r.stdout).trim(),
+                    };
+                }
+                else {
+                    // Actual commits written = HEAD advance count (empty-drop may skip some).
+                    const adv = await spawnGitAsync(gitTop, ["rev-list", "--count", `${preHead}..HEAD`]);
+                    appliedCount = adv.ok ? parseInt(adv.stdout.trim(), 10) || 0 : 0;
+                }
+            }
+            const allOk = !conflict;
+            // --- Cleanup (only on full success, only branch-kind sources) ---
+            const perSourceReport = resolved.map((s) => ({ ...s }));
+            if (allOk) {
+                for (let i = 0; i < perSourceReport.length; i++) {
+                    const src = perSourceReport[i];
+                    if (!src || src.kind !== "branch")
+                        continue;
+                    if (isProtectedBranch(src.raw))
+                        continue;
+                    if (args.deleteMergedWorktrees) {
+                        const path = await worktreeForBranch(gitTop, src.raw);
+                        if (path) {
+                            const tail = path.split("/").pop() ?? "";
+                            if (!isProtectedBranch(tail)) {
+                                const r = await spawnGitAsync(gitTop, ["worktree", "remove", path]);
+                                if (r.ok)
+                                    src.worktreeRemoved = path;
+                            }
+                        }
+                    }
+                    if (args.deleteMergedBranches) {
+                        const merged = await isFullyMergedInto(gitTop, src.raw, onto);
+                        if (merged) {
+                            const r = await spawnGitAsync(gitTop, ["branch", "-d", src.raw]);
+                            if (r.ok)
+                                src.branchDeleted = true;
+                        }
+                    }
+                }
+            }
+            const headProbe = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const headSha = headProbe.ok ? headProbe.stdout.trim() : undefined;
+            if (args.format === "json") {
+                return jsonRespond({
+                    ok: allOk,
+                    onto,
+                    ...spreadDefined("headSha", headSha),
+                    applied: appliedCount,
+                    picked: picks.length,
+                    results: perSourceReport.map((s) => ({
+                        source: s.raw,
+                        kind: s.kind,
+                        resolvedCommits: s.commits.length,
+                        keptCommits: perSourceKept.get(s.raw)?.length ?? 0,
+                        ...spreadWhen(s.branchDeleted === true, { branchDeleted: true }),
+                        ...spreadDefined("worktreeRemoved", s.worktreeRemoved),
+                    })),
+                    ...spreadWhen(conflict !== undefined, {
+                        conflict: {
+                            stage: conflict?.stage ?? "cherry-pick",
+                            ...spreadDefined("commit", conflict?.commit),
+                            paths: conflict?.paths ?? [],
+                            ...spreadDefined("detail", conflict?.detail),
+                        },
+                    }),
+                });
+            }
+            // --- Markdown ---
+            const lines = [];
+            const header = allOk
+                ? `# Cherry-pick onto \`${onto}\`: ${appliedCount} commit(s) applied`
+                : `# Cherry-pick onto \`${onto}\`: stopped on conflict after ${appliedCount} commit(s)`;
+            lines.push(header, "");
+            for (const s of perSourceReport) {
+                const kept = perSourceKept.get(s.raw)?.length ?? 0;
+                const tail = [`${s.kind}`, `${kept}/${s.commits.length} picked`];
+                if (s.branchDeleted)
+                    tail.push("branch deleted");
+                if (s.worktreeRemoved)
+                    tail.push(`worktree removed: ${s.worktreeRemoved}`);
+                lines.push(`- ${s.raw}  —  ${tail.join(", ")}`);
+            }
+            if (conflict) {
+                lines.push("", `Conflict at commit \`${conflict.commit ?? "?"}\` (${conflict.stage}):`);
+                for (const p of conflict.paths)
+                    lines.push(`  conflict: ${p}`);
+                if (conflict.detail)
+                    lines.push(`  detail: ${conflict.detail}`);
+            }
+            return lines.join("\n");
+        },
+    });
+}

package/dist/server/git-merge-tool.js

@@ -0,0 +1,393 @@
+import { z } from "zod";
+import { gitTopLevel, spawnGitAsync } from "./git.js";
+import { getCurrentBranch, isFullyMergedInto, isProtectedBranch, isSafeGitRefToken, isWorkingTreeClean, resolveRef, worktreeForBranch, } from "./git-refs.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireGitAndRoots } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+const StrategySchema = z
+    .enum(["auto", "ff-only", "rebase", "merge"])
+    .optional()
+    .default("auto")
+    .describe("`auto` (default): cascade fast-forward → rebase → merge-commit per source. " +
+    "`ff-only`: only fast-forward, fail if diverged. " +
+    "`rebase`: rebase source onto destination, then fast-forward (no merge-commit fallback). " +
+    "`merge`: always create a merge commit (no fast-forward).");
+// ---------------------------------------------------------------------------
+// Conflict helpers
+// ---------------------------------------------------------------------------
+async function conflictPaths(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["diff", "--name-only", "--diff-filter=U"]);
+    if (!r.ok)
+        return [];
+    return r.stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+async function abortMerge(gitTop) {
+    await spawnGitAsync(gitTop, ["merge", "--abort"]);
+}
+async function abortRebase(gitTop) {
+    await spawnGitAsync(gitTop, ["rebase", "--abort"]);
+}
+// ---------------------------------------------------------------------------
+// Per-source merge logic
+// ---------------------------------------------------------------------------
+/**
+ * Attempt to land `source` on `into`. Caller must ensure `into` is checked out.
+ * On conflict the repo state is cleaned (merge/rebase aborted, HEAD restored to `into`).
+ */
+async function mergeOneSource(gitTop, into, source, strategy, mergeMessage) {
+    // --- Classify state via merge-base ---
+    const intoSha = await resolveRef(gitTop, into);
+    const sourceSha = await resolveRef(gitTop, source);
+    if (!sourceSha) {
+        return { source, ok: false, error: "source_not_found" };
+    }
+    if (!intoSha) {
+        return { source, ok: false, error: "destination_not_found" };
+    }
+    const mb = await spawnGitAsync(gitTop, ["merge-base", into, source]);
+    if (!mb.ok) {
+        return {
+            source,
+            ok: false,
+            error: "merge_base_failed",
+            detail: (mb.stderr || mb.stdout).trim(),
+        };
+    }
+    const mergeBase = mb.stdout.trim();
+    // source fully contained in into → noop
+    if (mergeBase === sourceSha) {
+        return { source, ok: true, outcome: "up_to_date", mergedSha: intoSha };
+    }
+    // into fully contained in source → fast-forward is the right move
+    const canFastForward = mergeBase === intoSha;
+    // --- ff-only strategy ---
+    if (strategy === "ff-only") {
+        if (!canFastForward) {
+            return {
+                source,
+                ok: false,
+                error: "cannot_fast_forward",
+                detail: "destination and source have diverged; retry with strategy: rebase, merge, or auto",
+            };
+        }
+        return fastForward(gitTop, source);
+    }
+    // --- Fast-forward path for auto/rebase when applicable ---
+    if (canFastForward && (strategy === "auto" || strategy === "rebase")) {
+        return fastForward(gitTop, source);
+    }
+    // --- merge strategy: always merge commit ---
+    if (strategy === "merge") {
+        return mergeCommit(gitTop, source, mergeMessage, into);
+    }
+    // --- rebase or auto (diverged case) ---
+    const rebased = await rebaseSourceOntoInto(gitTop, into, source);
+    if (rebased.ok) {
+        // Rebase succeeded; FF destination up to the now-rebased source tip.
+        const ff = await fastForward(gitTop, source);
+        if (!ff.ok)
+            return ff;
+        return { ...ff, outcome: "rebase_then_ff" };
+    }
+    if (strategy === "rebase") {
+        return rebased; // caller opted out of merge-commit fallback
+    }
+    // auto: fall through to merge commit
+    return mergeCommit(gitTop, source, mergeMessage, into);
+}
+async function fastForward(gitTop, source) {
+    const r = await spawnGitAsync(gitTop, ["merge", "--ff-only", source]);
+    if (!r.ok) {
+        await abortMerge(gitTop);
+        return {
+            source,
+            ok: false,
+            outcome: "conflicts",
+            conflictStage: "merge",
+            conflictPaths: [],
+            error: "merge_failed",
+            detail: (r.stderr || r.stdout).trim(),
+        };
+    }
+    const head = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+    return {
+        source,
+        ok: true,
+        outcome: "fast_forward",
+        mergedSha: head.ok ? head.stdout.trim() : undefined,
+    };
+}
+async function mergeCommit(gitTop, source, message, into) {
+    const msg = message?.trim() || `Merge branch '${source}' into ${into}`;
+    const r = await spawnGitAsync(gitTop, ["merge", "--no-ff", "--no-edit", "-m", msg, source]);
+    if (!r.ok) {
+        const paths = await conflictPaths(gitTop);
+        await abortMerge(gitTop);
+        return {
+            source,
+            ok: false,
+            outcome: "conflicts",
+            conflictStage: "merge",
+            conflictPaths: paths,
+            error: "merge_conflicts",
+            detail: (r.stderr || r.stdout).trim(),
+        };
+    }
+    const head = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+    return {
+        source,
+        ok: true,
+        outcome: "merge_commit",
+        mergedSha: head.ok ? head.stdout.trim() : undefined,
+    };
+}
+/**
+ * Rebase `source` onto `into`, then return to `into`.
+ * On failure: abort rebase, check out `into` again, return structured conflict.
+ */
+async function rebaseSourceOntoInto(gitTop, into, source) {
+    // `git rebase <upstream> <branch>` first switches to <branch>.
+    const r = await spawnGitAsync(gitTop, ["rebase", into, source]);
+    if (!r.ok) {
+        const paths = await conflictPaths(gitTop);
+        await abortRebase(gitTop);
+        // Ensure we're back on `into` regardless of rebase state.
+        await spawnGitAsync(gitTop, ["checkout", into]);
+        return {
+            source,
+            ok: false,
+            outcome: "conflicts",
+            conflictStage: "rebase",
+            conflictPaths: paths,
+            error: "rebase_conflicts",
+            detail: (r.stderr || r.stdout).trim(),
+        };
+    }
+    // Rebase succeeded; switch back to destination so the caller can FF.
+    const co = await spawnGitAsync(gitTop, ["checkout", into]);
+    if (!co.ok) {
+        return {
+            source,
+            ok: false,
+            error: "checkout_failed",
+            detail: (co.stderr || co.stdout).trim(),
+        };
+    }
+    return { source, ok: true }; // caller FFs
+}
+// ---------------------------------------------------------------------------
+// Cleanup helpers
+// ---------------------------------------------------------------------------
+async function maybeRemoveWorktree(gitTop, source, enabled) {
+    if (!enabled)
+        return undefined;
+    const path = await worktreeForBranch(gitTop, source);
+    if (!path)
+        return undefined;
+    // Re-check protected names against the worktree path's trailing segment too.
+    const tail = path.split("/").pop() ?? "";
+    if (isProtectedBranch(tail))
+        return undefined;
+    const r = await spawnGitAsync(gitTop, ["worktree", "remove", path]);
+    return r.ok ? path : undefined;
+}
+async function maybeDeleteBranch(gitTop, source, enabled, into) {
+    if (!enabled)
+        return false;
+    if (isProtectedBranch(source))
+        return false;
+    // Safety double-check: source must be fully merged into destination.
+    const merged = await isFullyMergedInto(gitTop, source, into);
+    if (!merged)
+        return false;
+    const r = await spawnGitAsync(gitTop, ["branch", "-d", source]);
+    return r.ok;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitMergeTool(server) {
+    server.addTool({
+        name: "git_merge",
+        description: "Merge one or more source branches into a destination. Default strategy `auto` " +
+            "cascades fast-forward → rebase → merge-commit per source, preferring linear history. " +
+            "Refuses if the working tree is dirty. Stops on the first conflict and reports " +
+            "the affected paths. Optional flags auto-delete merged branches and worktrees, " +
+            "skipping protected names (main, master, dev, develop, stable, trunk, prod, " +
+            "production, release/*, hotfix/*). See docs/mcp-tools.md.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            sources: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(20)
+                .describe("Branches to merge into the destination, in order."),
+            into: z
+                .string()
+                .optional()
+                .describe("Destination branch. Defaults to the currently checked-out branch."),
+            strategy: StrategySchema,
+            message: z
+                .string()
+                .optional()
+                .describe("Merge commit message (used only when a merge commit is created)."),
+            deleteMergedBranches: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("After all sources merge cleanly, delete each source branch locally (`git branch -d`). " +
+                "Protected names (main, master, dev, develop, stable, trunk, prod, production, " +
+                "release/*, hotfix/*) are always skipped. Never affects remote branches."),
+            deleteMergedWorktrees: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("After all sources merge cleanly, remove any local worktree currently checked out " +
+                "on a source branch (`git worktree remove`). Protected tails always skipped."),
+        }),
+        execute: async (args) => {
+            const pre = requireGitAndRoots(server, args, undefined);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const rootInput = pre.roots[0];
+            if (!rootInput)
+                return jsonRespond({ error: "no_workspace_root" });
+            const gitTop = gitTopLevel(rootInput);
+            if (!gitTop)
+                return jsonRespond({ error: "not_a_git_repository", path: rootInput });
+            // --- Validate ref tokens early ---
+            for (const s of args.sources) {
+                if (!isSafeGitRefToken(s)) {
+                    return jsonRespond({ error: "unsafe_ref_token", ref: s });
+                }
+            }
+            if (args.into !== undefined && !isSafeGitRefToken(args.into)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.into });
+            }
+            // --- Resolve destination ---
+            const startBranch = await getCurrentBranch(gitTop);
+            const into = args.into?.trim() || startBranch;
+            if (!into) {
+                return jsonRespond({ error: "into_detached_head" });
+            }
+            // --- Refuse dirty tree ---
+            if (!(await isWorkingTreeClean(gitTop))) {
+                return jsonRespond({ error: "working_tree_dirty" });
+            }
+            // --- Ensure destination is checked out ---
+            if (into !== startBranch) {
+                const co = await spawnGitAsync(gitTop, ["checkout", into]);
+                if (!co.ok) {
+                    return jsonRespond({
+                        error: "checkout_failed",
+                        detail: (co.stderr || co.stdout).trim(),
+                    });
+                }
+            }
+            // Verify destination exists after checkout.
+            const intoShaProbe = await resolveRef(gitTop, into);
+            if (!intoShaProbe) {
+                return jsonRespond({ error: "destination_not_found", ref: into });
+            }
+            // --- Merge each source sequentially ---
+            const strategy = args.strategy ?? "auto";
+            const results = [];
+            let firstConflict = false;
+            for (const source of args.sources) {
+                const r = await mergeOneSource(gitTop, into, source, strategy, args.message);
+                results.push(r);
+                if (!r.ok) {
+                    firstConflict = true;
+                    break;
+                }
+            }
+            const allOk = !firstConflict && results.every((r) => r.ok);
+            // --- Cleanup (only on full success) ---
+            if (allOk) {
+                for (let i = 0; i < results.length; i++) {
+                    const r = results[i];
+                    if (!r || r.outcome === "up_to_date")
+                        continue;
+                    const worktreeRemoved = await maybeRemoveWorktree(gitTop, r.source, args.deleteMergedWorktrees ?? false);
+                    const branchDeleted = await maybeDeleteBranch(gitTop, r.source, args.deleteMergedBranches ?? false, into);
+                    results[i] = {
+                        ...r,
+                        ...spreadDefined("worktreeRemoved", worktreeRemoved),
+                        ...spreadWhen(branchDeleted, { branchDeleted: true }),
+                    };
+                }
+            }
+            const headProbe = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const headSha = headProbe.ok ? headProbe.stdout.trim() : undefined;
+            if (args.format === "json") {
+                return jsonRespond({
+                    ok: allOk,
+                    into,
+                    strategy,
+                    ...spreadDefined("headSha", headSha),
+                    applied: results.filter((r) => r.ok).length,
+                    total: args.sources.length,
+                    results: results.map((r) => ({
+                        source: r.source,
+                        ok: r.ok,
+                        ...spreadDefined("outcome", r.outcome),
+                        ...spreadDefined("mergedSha", r.mergedSha),
+                        ...spreadDefined("conflictStage", r.conflictStage),
+                        ...spreadWhen((r.conflictPaths?.length ?? 0) > 0, {
+                            conflictPaths: r.conflictPaths,
+                        }),
+                        ...spreadWhen(r.branchDeleted === true, { branchDeleted: true }),
+                        ...spreadDefined("worktreeRemoved", r.worktreeRemoved),
+                        ...spreadDefined("skipReason", r.skipReason),
+                        ...spreadDefined("error", r.error),
+                        ...spreadDefined("detail", r.detail),
+                    })),
+                });
+            }
+            // --- Markdown ---
+            const lines = [];
+            const applied = results.filter((r) => r.ok).length;
+            const header = allOk
+                ? `# Merge into \`${into}\`: ${applied}/${args.sources.length} sources applied`
+                : `# Merge into \`${into}\`: ${applied}/${args.sources.length} sources applied (stopped on conflict)`;
+            lines.push(header, "");
+            for (const r of results) {
+                const icon = r.ok ? "✓" : "✗";
+                const tail = [];
+                if (r.outcome)
+                    tail.push(r.outcome);
+                if (r.mergedSha)
+                    tail.push(`\`${r.mergedSha.slice(0, 7)}\``);
+                if (r.branchDeleted)
+                    tail.push("branch deleted");
+                if (r.worktreeRemoved)
+                    tail.push(`worktree removed: ${r.worktreeRemoved}`);
+                lines.push(`${icon} ${r.source}${tail.length ? `  —  ${tail.join(", ")}` : ""}`);
+                if (!r.ok) {
+                    if (r.conflictPaths?.length) {
+                        for (const p of r.conflictPaths)
+                            lines.push(`  conflict: ${p}`);
+                    }
+                    if (r.error)
+                        lines.push(`  Error: ${r.error}${r.detail ? ` — ${r.detail}` : ""}`);
+                }
+            }
+            if (!allOk) {
+                const skipped = args.sources.length - results.length;
+                if (skipped > 0)
+                    lines.push("", `${skipped} remaining source(s) skipped.`);
+            }
+            return lines.join("\n");
+        },
+    });
+}

package/dist/server/git-refs.js

@@ -0,0 +1,151 @@
+import { spawnGitAsync } from "./git.js";
+// ---------------------------------------------------------------------------
+// Protected branch names — never auto-delete, never cascade destructive ops onto
+// ---------------------------------------------------------------------------
+const PROTECTED_EXACT = new Set([
+    "main",
+    "master",
+    "dev",
+    "develop",
+    "stable",
+    "trunk",
+    "prod",
+    "production",
+    "HEAD",
+]);
+const PROTECTED_PATTERN = /^(release|hotfix)[-/].+$/i;
+/** True when a branch name is on the protected list and must not be auto-deleted. */
+export function isProtectedBranch(name) {
+    const t = name.trim();
+    if (t === "")
+        return true;
+    if (PROTECTED_EXACT.has(t))
+        return true;
+    return PROTECTED_PATTERN.test(t);
+}
+// ---------------------------------------------------------------------------
+// Ref/branch name validation (argv-safe subset of git's ref-format rules)
+// ---------------------------------------------------------------------------
+/**
+ * Conservative check for branch/ref names passed to git argv.
+ * Rejects anything outside the ASCII subset `A-Z a-z 0-9 _ . / + -`,
+ * sequences git itself rejects (`..`, `@{`, leading `-`, trailing `.lock`/`/`),
+ * and pathological tokens.
+ */
+export function isSafeGitRefToken(s) {
+    const t = s.trim();
+    if (t.length === 0 || t.length > 256)
+        return false;
+    if (t.startsWith("-"))
+        return false;
+    if (t.endsWith("/") || t.endsWith(".lock") || t.endsWith("."))
+        return false;
+    if (t.includes(".."))
+        return false;
+    if (t.includes("@{"))
+        return false;
+    if (t.includes("//"))
+        return false;
+    return /^[A-Za-z0-9_./+-]+$/.test(t);
+}
+/**
+ * Same as `isSafeGitRefToken` but also allows the `A..B` / `A...B` range forms
+ * used by `git log` / `git cherry-pick`. Splits once and validates each side.
+ */
+export function isSafeGitRangeToken(s) {
+    const t = s.trim();
+    if (t.includes("...")) {
+        const parts = t.split("...");
+        return parts.length === 2 && parts.every((p) => isSafeGitRefToken(p));
+    }
+    if (t.includes("..")) {
+        const parts = t.split("..");
+        return parts.length === 2 && parts.every((p) => isSafeGitRefToken(p));
+    }
+    return isSafeGitRefToken(t);
+}
+// ---------------------------------------------------------------------------
+// Async helpers
+// ---------------------------------------------------------------------------
+/** Current branch name; `null` if detached HEAD. */
+export async function getCurrentBranch(cwd) {
+    const r = await spawnGitAsync(cwd, ["symbolic-ref", "--short", "-q", "HEAD"]);
+    if (!r.ok)
+        return null;
+    const name = r.stdout.trim();
+    return name === "" ? null : name;
+}
+/** Resolve a ref to its full SHA; `null` if unknown. */
+export async function resolveRef(cwd, ref) {
+    if (!isSafeGitRefToken(ref))
+        return null;
+    const r = await spawnGitAsync(cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+    if (!r.ok)
+        return null;
+    const sha = r.stdout.trim();
+    return sha === "" ? null : sha;
+}
+/** Working tree clean (no staged, no unstaged, no untracked). */
+export async function isWorkingTreeClean(cwd) {
+    const r = await spawnGitAsync(cwd, ["status", "--porcelain"]);
+    if (!r.ok)
+        return false;
+    return r.stdout.trim() === "";
+}
+/** True when every commit on `branch` is reachable from `target`. */
+export async function isFullyMergedInto(cwd, branch, target) {
+    if (!isSafeGitRefToken(branch) || !isSafeGitRefToken(target))
+        return false;
+    const r = await spawnGitAsync(cwd, ["merge-base", "--is-ancestor", branch, target]);
+    return r.ok;
+}
+/**
+ * SHAs of commits in `exclude..include`, oldest-first (cherry-pick feed order).
+ * Returns `null` on git failure.
+ */
+export async function commitListBetween(cwd, excludeRef, includeRef) {
+    if (!isSafeGitRefToken(excludeRef) || !isSafeGitRefToken(includeRef))
+        return null;
+    const r = await spawnGitAsync(cwd, ["rev-list", "--reverse", `${excludeRef}..${includeRef}`]);
+    if (!r.ok)
+        return null;
+    return r.stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+/** Parse `git worktree list --porcelain` into structured entries. */
+export async function listWorktrees(cwd) {
+    const r = await spawnGitAsync(cwd, ["worktree", "list", "--porcelain"]);
+    if (!r.ok)
+        return [];
+    const out = [];
+    let cur = {};
+    for (const line of r.stdout.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            if (cur.path)
+                out.push({ path: cur.path, branch: cur.branch ?? null, head: cur.head ?? null });
+            cur = { path: line.slice("worktree ".length).trim() };
+        }
+        else if (line.startsWith("HEAD ")) {
+            cur.head = line.slice("HEAD ".length).trim();
+        }
+        else if (line.startsWith("branch ")) {
+            // e.g. `branch refs/heads/foo`
+            const ref = line.slice("branch ".length).trim();
+            cur.branch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+        }
+        else if (line === "detached") {
+            cur.branch = null;
+        }
+    }
+    if (cur.path)
+        out.push({ path: cur.path, branch: cur.branch ?? null, head: cur.head ?? null });
+    return out;
+}
+/** Path of the worktree currently checked out on `branch`; `null` if none. */
+export async function worktreeForBranch(cwd, branch) {
+    const trees = await listWorktrees(cwd);
+    const hit = trees.find((t) => t.branch === branch);
+    return hit?.path ?? null;
+}

package/dist/server/tools.js

@@ -1,7 +1,9 @@
 import { registerBatchCommitTool } from "./batch-commit-tool.js";
+import { registerGitCherryPickTool } from "./git-cherry-pick-tool.js";
 import { registerGitDiffSummaryTool } from "./git-diff-summary-tool.js";
 import { registerGitInventoryTool } from "./git-inventory-tool.js";
 import { registerGitLogTool } from "./git-log-tool.js";
+import { registerGitMergeTool } from "./git-merge-tool.js";
 import { registerGitParityTool } from "./git-parity-tool.js";
 import { registerGitStatusTool } from "./git-status-tool.js";
 import { registerListPresetsTool } from "./list-presets-tool.js";
@@ -14,5 +16,7 @@ export function registerRethunkGitTools(server) {
     registerBatchCommitTool(server);
     registerGitDiffSummaryTool(server);
     registerGitLogTool(server);
+    registerGitMergeTool(server);
+    registerGitCherryPickTool(server);
     registerPresetsResource(server);
 }

package/docs/mcp-tools.md

@@ -17,7 +17,9 @@ MCP clients expose tools as `{serverName}_{toolName}`. With the server registere
 | `list_presets` | `rethunk-git_list_presets` | List preset names/counts from `.rethunk/git-mcp-presets.json`; invalid JSON/schema surface as errors. Workspace pick + `format` only. |
 | `git_log` | `rethunk-git_git_log` | Path-filtered, time-windowed `git log` across one or more workspace roots. Returns commit history with author, date, subject, and shortstat. Args: `since`, `paths`, `grep`, `author`, `maxCommits`, `branch`, plus workspace pick args + `format`. |
 | `git_diff_summary` | `rethunk-git_git_diff_summary` | Structured, token-efficient diff viewer. Returns per-file diffs with additions/deletions counts, truncated to configurable line limits, with lock files/dist/vendor excluded by default. Args: `range`, `fileFilter`, `maxLinesPerFile`, `maxFiles`, `excludePatterns`, plus workspace pick args + `format`. **Read-only.** |
-| `batch_commit` | `rethunk-git_batch_commit` | Create multiple sequential git commits in a single call. Each entry stages the listed files then commits with the given message. Stops on first failure. Args: `commits` (array of `{message, files}`), plus workspace pick args + `format`. **Mutating — not idempotent.** |
+| `batch_commit` | `rethunk-git_batch_commit` | Create multiple sequential git commits in a single call. Each entry stages the listed files then commits with the given message. Stops on first failure. Optional `push: "after"` pushes the current branch to its upstream once every commit lands. Args: `commits` (array of `{message, files}`), `push?`, plus workspace pick args + `format`. **Mutating — not idempotent.** |
+| `git_merge` | `rethunk-git_git_merge` | Merge one or more source branches into a destination. Default strategy `auto` cascades fast-forward → rebase → merge-commit per source, preferring linear history. Refuses on dirty tree; stops on first conflict with structured path report. Optional `deleteMergedBranches` / `deleteMergedWorktrees` cascade cleanup, always skipping protected names (main/master/dev/develop/stable/trunk/prod/production/release\*/hotfix\*). Args: `sources`, `into?`, `strategy?`, `message?`, cleanup flags + workspace pick + `format`. **Mutating.** |
+| `git_cherry_pick` | `rethunk-git_git_cherry_pick` | Play commits from one or more sources onto a destination. Sources may be SHAs, `A..B` ranges, or branch names (expanded to `onto..<branch>`, oldest-first). Uses `--empty=drop` so patch-equivalent re-applies add nothing. Refuses on dirty tree; stops on first conflict, aborting cleanly. Same cleanup flags as `git_merge` (branch-kind sources only, protected names skipped). Args: `sources`, `onto?`, cleanup flags + workspace pick + `format`. **Mutating.** |
 
 Pass **`format: "json"`** on any tool for structured JSON instead of markdown (default).
 
@@ -152,6 +154,7 @@ v2 field-omission rules: `filesChanged`, `insertions`, `deletions` are omitted w
 | Parameter | Type | Notes |
 |-----------|------|-------|
 | `commits` | `{message: string, files: string[]}[]` | Commits to create in order. 1–50 entries. Each `files` entry is a path relative to the git root; all must stay within the git toplevel. |
+| `push` | `"never"` \| `"after"` | Default `"never"`. `"after"` pushes the current branch to its upstream **once all commits succeed**. Never auto-sets upstream — branches without an upstream fail with `push_no_upstream`. Commits are **not** rolled back on push failure. Enum reserved for future modes such as `"force-with-lease"`. |
 | `workspaceRoot` | string | Explicit root; highest priority. |
 | `rootIndex` | int | Pick one of several MCP roots (0-based). |
 | `format` | `"markdown"` \| `"json"` | Output format. Default: `"markdown"`. |
@@ -175,12 +178,19 @@ v2 field-omission rules: `filesChanged`, `insertions`, `deletions` are omitted w
     "sha": "b2c3d4e",
     "message": "chore: update config",
     "files": ["config.json"]
-  }]
+  }],
+  "push": {
+    "ok": true,
+    "branch": "main",
+    "upstream": "origin/main"
+  }
 }
 ```
 
 On first failure `ok` is `false`, `committed` reflects only the entries that succeeded before the error, and the failing entry includes `error` and `detail` fields. Remaining entries are skipped and not included in `results`.
 
+The `push` object is present only when `push: "after"` was requested **and** every commit landed. On push failure the top-level `ok` stays `true` (the commits themselves succeeded) while `push.ok` is `false` and `push.error` carries the code.
+
 ### `batch_commit` — error codes (per-result `error` field)
 
 | Code | Meaning |
@@ -190,6 +200,143 @@ On first failure `ok` is `false`, `committed` reflects only the entries that suc
 | `commit_failed` | `git commit` failed (e.g. nothing staged, hooks rejected). |
 | `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
 
+### `batch_commit` — push error codes (`push.error` field)
+
+| Code | Meaning |
+|------|---------|
+| `push_detached_head` | HEAD is detached; no branch to push. |
+| `push_no_upstream` | Current branch has no configured upstream. `batch_commit` will not auto-set one — do `git push -u origin <branch>` yourself (or re-run without `push`). |
+| `push_failed` | `git push` exited non-zero (network error, non-fast-forward, hook rejection). `detail` carries the stderr/stdout from git. |
+
+---
+
+### `git_merge` — parameters
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `sources` | `string[]` | Source branches to merge, in order. 1–20 entries. Each must be a valid git ref token. |
+| `into` | string | Destination branch. Defaults to the currently checked-out branch. Rejected when HEAD is detached. |
+| `strategy` | `"auto"` \| `"ff-only"` \| `"rebase"` \| `"merge"` | Default `"auto"`: cascade **fast-forward → rebase → merge-commit** per source. `"ff-only"` fails on divergence. `"rebase"` rebases source onto destination and fast-forwards; no merge-commit fallback. `"merge"` always creates a merge commit (`--no-ff`). |
+| `message` | string | Merge commit message, used only when a merge commit is created. Defaults to `Merge branch '<source>' into <into>`. |
+| `deleteMergedBranches` | boolean | Default `false`. After **all** sources land cleanly, delete each source branch locally (`git branch -d`). **Protected names always skipped** (main, master, dev, develop, stable, trunk, prod, production, `release/*`, `release-*`, `hotfix/*`, `hotfix-*`). Never touches remote refs. |
+| `deleteMergedWorktrees` | boolean | Default `false`. After success, remove any local worktree currently checked out on a source branch (`git worktree remove`). Protected tails always skipped. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard workspace pick + output format. |
+
+### `git_merge` — JSON shape (`format: "json"`)
+
+```json
+{
+  "ok": true,
+  "into": "main",
+  "strategy": "auto",
+  "headSha": "a1b2c3d4e5f6…",
+  "applied": 2,
+  "total": 2,
+  "results": [
+    {
+      "source": "feature/a",
+      "ok": true,
+      "outcome": "fast_forward",
+      "mergedSha": "a1b2c3d4e5f6…",
+      "branchDeleted": true,
+      "worktreeRemoved": "/tmp/agent-a"
+    },
+    {
+      "source": "feature/b",
+      "ok": true,
+      "outcome": "rebase_then_ff",
+      "mergedSha": "b2c3d4e5f6a1…"
+    }
+  ]
+}
+```
+
+**`outcome`** (per source): `fast_forward`, `rebase_then_ff`, `merge_commit`, `up_to_date`, or `conflicts`. Cleanup fields (`branchDeleted`, `worktreeRemoved`) are only emitted when the corresponding flag was set and the operation actually ran — both are omitted for up-to-date sources and are never populated on partial-failure runs.
+
+On conflict: top-level `ok` is `false`, the conflicting entry has `ok: false` with `conflictStage` (`"rebase"` or `"merge"`), `conflictPaths` (array of paths with unresolved markers), and an `error` code. Remaining sources are not attempted.
+
+### `git_merge` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `unsafe_ref_token` | A source or `into` contains characters outside the argv-safe subset (spaces, shell meta, `..`, `@{`, leading `-`, trailing `.lock`). |
+| `into_detached_head` | HEAD is detached and no `into` was given — the tool needs a concrete destination branch. |
+| `working_tree_dirty` | Uncommitted changes present. Commit, stash, or discard before merging. |
+| `checkout_failed` | Could not switch to `into`. `detail` carries git's stderr. |
+| `destination_not_found` | `into` does not resolve to a commit. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+| `source_not_found` (per source) | A source branch name does not resolve. |
+| `cannot_fast_forward` (per source) | `strategy: "ff-only"` refused because branches have diverged. |
+| `rebase_conflicts` (per source) | Rebase encountered conflicts. Repo state is cleaned before returning. |
+| `merge_conflicts` (per source) | Merge commit encountered conflicts. Repo state is cleaned before returning. |
+| `merge_failed` (per source) | `git merge --ff-only` failed unexpectedly. `detail` carries stderr. |
+| `merge_base_failed` (per source) | `git merge-base` failed (usually unrelated histories). |
+
+---
+
+### `git_cherry_pick` — parameters
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `sources` | `string[]` | Source specs. 1–50 entries. Each entry is one of: a full/short SHA, an `A..B` / `A...B` range, or a branch name. Branch names expand to `onto..<branch>` (oldest-first). |
+| `onto` | string | Destination branch. Defaults to the currently checked-out branch. Rejected when HEAD is detached. |
+| `deleteMergedBranches` | boolean | Default `false`. After all commits apply, delete each **branch-kind** source locally (`git branch -d`) when it is fully merged into the destination by SHA-reachability (not patch-equivalence). Protected names always skipped; never touches remote refs. |
+| `deleteMergedWorktrees` | boolean | Default `false`. After success, remove any local worktree attached to a branch-kind source (`git worktree remove`). Protected tails always skipped. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard workspace pick + output format. |
+
+### `git_cherry_pick` — JSON shape (`format: "json"`)
+
+```json
+{
+  "ok": true,
+  "onto": "main",
+  "headSha": "a1b2c3d…",
+  "picked": 3,
+  "applied": 2,
+  "results": [
+    { "source": "feature/a", "kind": "branch", "resolvedCommits": 2, "keptCommits": 2 },
+    { "source": "abcdef1",    "kind": "sha",    "resolvedCommits": 1, "keptCommits": 1 }
+  ]
+}
+```
+
+**`picked`** is the number of unique SHAs fed to `git cherry-pick` after SHA-reachability filtering. **`applied`** is the number of new commits actually added to HEAD — may be less than `picked` because the tool passes `--empty=drop` to git, so patch-equivalent commits are skipped at apply time without error.
+
+**`kind`** is `"sha"`, `"range"`, or `"branch"`. **`resolvedCommits`** is how many commits the source expanded to; **`keptCommits`** is how many survived SHA-reachability dedupe. Cleanup fields (`branchDeleted`, `worktreeRemoved`) are only emitted for branch-kind sources when the corresponding flag was set and the operation succeeded.
+
+On conflict, the response has `ok: false` and a top-level `conflict` object:
+
+```json
+{
+  "ok": false,
+  "onto": "main",
+  "picked": 2,
+  "applied": 0,
+  "results": [ ... ],
+  "conflict": {
+    "stage": "cherry-pick",
+    "commit": "abcdef1",
+    "paths": ["src/foo.ts"],
+    "detail": "…git stderr…"
+  }
+}
+```
+
+Repo state is cleaned (`git cherry-pick --abort`) before returning — no partially-applied index.
+
+### `git_cherry_pick` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `unsafe_ref_token` | A source or `onto` contains characters outside the argv-safe subset. |
+| `onto_detached_head` | HEAD is detached and no `onto` was given. |
+| `working_tree_dirty` | Uncommitted changes present. Commit, stash, or discard before cherry-picking. |
+| `checkout_failed` | Could not switch to `onto`. |
+| `destination_not_found` | `onto` does not resolve to a commit. |
+| `source_not_found` | A source spec resolves to neither a branch, a range, nor a commit. |
+| `range_resolution_failed` | `git rev-list` failed to expand a range spec. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
 ---
 
 ## Resource

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/mcp-multi-root-git",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP stdio server: multi-root git status, inventory, and HEAD parity checks. Generic tools usable by any workspace.",
   "type": "module",
   "private": false,
@@ -14,6 +14,7 @@
     "docs/install.md",
     "docs/mcp-tools.md",
     "AGENTS.md",
+    "CHANGELOG.md",
     "HUMANS.md",
     "README.md",
     "LICENSE"
@@ -59,9 +60,9 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
-    "@types/node": "^22.0.0",
-    "rimraf": "^6.0.1",
+    "@biomejs/biome": "^2.4.11",
+    "@types/node": "^22.19.17",
+    "rimraf": "^6.1.3",
     "typescript": "^6.0.2"
   }
 }