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

package/AGENTS.md

@@ -14,10 +14,10 @@ IDEs injecting this as context: do not re-link from rules.
 | File | Symbols |
 |------|---------|
 | [`src/server.ts`](src/server.ts) | `FastMCP` + `roots: { enabled: true }`; `readMcpServerVersion()`; `registerRethunkGitTools` |
-| [`src/server/json.ts`](src/server/json.ts) | `MCP_JSON_FORMAT_VERSION="2"`, `jsonRespond()` (minified, no envelope), `spreadWhen`, `spreadDefined` |
+| [`src/server/json.ts`](src/server/json.ts) | `jsonRespond()` (minified, no envelope), `spreadWhen`, `spreadDefined` |
 | [`src/server/git.ts`](src/server/git.ts) | `gateGit`, `spawnGitAsync`, `asyncPool`, `GIT_SUBPROCESS_PARALLELISM`, `gitTopLevel`, `gitRevParseGitDir`, `gitRevParseHead`, `parseGitSubmodulePaths`, `hasGitMetadata`, `gitStatusSnapshotAsync`, `gitStatusShortBranchAsync`, `fetchAheadBehind`, `isSafeGitUpstreamToken` |
-| [`src/server/roots.ts`](src/server/roots.ts) | `uriToPath`, `listFileRoots`, `pathMatchesWorkspaceRootHint`, `resolveWorkspaceRoots`, `resolveRootsForPreset`, `requireGitAndRoots` — session roots only |
-| [`src/server/presets.ts`](src/server/presets.ts) | `PRESET_FILE_PATH`, `splitPresetFileRaw`, `loadPresetsFromGitTop`, `getPresetEntry`, `presetLoadErrorPayload`, `applyPresetNestedRoots`, `applyPresetParityPairs`; Zod schemas must match [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json) |
+| [`src/server/roots.ts`](src/server/roots.ts) | `requireGitAndRoots` — sole public export; session root resolution |
+| [`src/server/presets.ts`](src/server/presets.ts) | `PRESET_FILE_PATH`, `loadPresetsFromGitTop`, `presetLoadErrorPayload`, `applyPresetNestedRoots`, `applyPresetParityPairs`; Zod schemas must match [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json) |
 | [`src/server/schemas.ts`](src/server/schemas.ts) | `WorkspacePickSchema`, `MAX_INVENTORY_ROOTS_DEFAULT` |
 | [`src/server/inventory.ts`](src/server/inventory.ts) | `InventoryEntryJson`, `validateRepoPath`, `makeSkipEntry`, `buildInventorySectionMarkdown`, `collectInventoryEntry` |
 | [`src/server/tools.ts`](src/server/tools.ts) | `registerRethunkGitTools` — dispatches to `register*` below |
@@ -25,14 +25,17 @@ IDEs injecting this as context: do not re-link from rules.
 | [`src/server/git-inventory-tool.ts`](src/server/git-inventory-tool.ts) | `git_inventory` |
 | [`src/server/git-parity-tool.ts`](src/server/git-parity-tool.ts) | `git_parity` |
 | [`src/server/list-presets-tool.ts`](src/server/list-presets-tool.ts) | `list_presets` |
+| [`src/server/git-log-tool.ts`](src/server/git-log-tool.ts) | `git_log` |
+| [`src/server/git-diff-summary-tool.ts`](src/server/git-diff-summary-tool.ts) | `git_diff_summary` — structured token-efficient diff viewer; read-only |
+| [`src/server/batch-commit-tool.ts`](src/server/batch-commit-tool.ts) | `batch_commit` — sequential multi-commit; mutating |
 | [`src/server/presets-resource.ts`](src/server/presets-resource.ts) | `rethunk-git://presets` resource |
-| [`src/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop`, `realPathOrSelf` |
+| [`src/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop` |
 
 ## Changing contracts
 
 - **No banner paragraphs** in shipped docs. Use normal titles + cross-links.
-- **`MCP_JSON_FORMAT_VERSION`** (currently `"2"`): bump on incompatible JSON changes (renamed/nested/omitted fields). Document migration here + [docs/mcp-tools.md](docs/mcp-tools.md). v2 removed the `rethunkGitMcp` envelope; payloads are minified; optional fields omitted when empty/null/false.
-- **Preset file:** keep `splitPresetFileRaw` + Zod aligned with [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json).
+- **JSON format version** (currently `"2"`, discoverable via MCP `initialize`): bump on incompatible JSON changes (renamed/nested/omitted fields). Document migration here + [docs/mcp-tools.md](docs/mcp-tools.md). v2 removed the `rethunkGitMcp` envelope; payloads are minified; optional fields omitted when empty/null/false.
+- **Preset file:** keep `presets.ts` Zod schemas aligned with [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json).
 - **Public tool surface:** rename/add → update [docs/mcp-tools.md](docs/mcp-tools.md) + [README.md](README.md) (if mentioned). Install/client wiring → [docs/install.md](docs/install.md) only. `.cursor/rules/rethunk-git-mcp.mdc` → only when *MCP-vs-shell* guidance changes.
 
 ## Validate + CI

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)
 
-Read-only **git** tools over MCP (status, multi-root inventory, `HEAD` parity, presets). **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/repo-paths.js

@@ -1,6 +1,6 @@
 import { realpathSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
-export function realPathOrSelf(p) {
+function realPathOrSelf(p) {
     try {
         return realpathSync(p);
     }

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

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import { isStrictlyUnderGitTop, resolvePathForRepo } from "../repo-paths.js";
+import { gitTopLevel, spawnGitAsync } from "./git.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. Optional `push: "after"` pushes the current branch ' +
+            "to its upstream once all commits succeed. See docs/mcp-tools.md.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            commits: z
+                .array(CommitEntrySchema)
+                .min(1)
+                .max(50)
+                .describe("Commits to create, applied in order."),
+            push: PushModeSchema,
+        }),
+        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 });
+            }
+            const results = [];
+            for (let i = 0; i < args.commits.length; i++) {
+                const entry = args.commits[i];
+                if (!entry)
+                    break;
+                // --- Validate all paths are under the git toplevel ---
+                const escapedPaths = [];
+                for (const rel of entry.files) {
+                    const abs = resolvePathForRepo(rel, gitTop);
+                    if (!isStrictlyUnderGitTop(abs, gitTop)) {
+                        escapedPaths.push(rel);
+                    }
+                }
+                if (escapedPaths.length > 0) {
+                    results.push({
+                        index: i,
+                        ok: false,
+                        message: entry.message,
+                        files: entry.files,
+                        error: "path_escapes_repository",
+                        detail: escapedPaths.join(", "),
+                    });
+                    break;
+                }
+                // --- Stage files ---
+                const addResult = await spawnGitAsync(gitTop, ["add", "--", ...entry.files]);
+                if (!addResult.ok) {
+                    results.push({
+                        index: i,
+                        ok: false,
+                        message: entry.message,
+                        files: entry.files,
+                        error: "stage_failed",
+                        detail: (addResult.stderr || addResult.stdout).trim(),
+                    });
+                    break;
+                }
+                // --- Commit ---
+                const commitResult = await spawnGitAsync(gitTop, ["commit", "-m", entry.message]);
+                if (!commitResult.ok) {
+                    results.push({
+                        index: i,
+                        ok: false,
+                        message: entry.message,
+                        files: entry.files,
+                        error: "commit_failed",
+                        detail: (commitResult.stderr || commitResult.stdout).trim(),
+                    });
+                    break;
+                }
+                // --- Extract SHA from commit output ---
+                const shaMatch = /\[[\w/.-]+\s+([0-9a-f]+)\]/.exec(commitResult.stdout);
+                results.push({
+                    index: i,
+                    ok: true,
+                    sha: shaMatch?.[1],
+                    message: entry.message,
+                    files: entry.files,
+                });
+            }
+            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,
+                    committed: results.filter((r) => r.ok).length,
+                    total: args.commits.length,
+                    results: results.map((r) => ({
+                        index: r.index,
+                        ok: r.ok,
+                        ...spreadDefined("sha", r.sha),
+                        message: r.message,
+                        files: r.files,
+                        ...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 ---
+            const lines = [];
+            const header = allOk
+                ? `# Batch commit: ${results.length}/${args.commits.length} committed`
+                : `# Batch commit: ${results.filter((r) => r.ok).length}/${args.commits.length} committed (stopped on error)`;
+            lines.push(header, "");
+            for (const r of results) {
+                const icon = r.ok ? "✓" : "✗";
+                const sha = r.sha ? ` \`${r.sha}\`` : "";
+                lines.push(`${icon}${sha} ${r.message}`);
+                if (!r.ok && r.detail) {
+                    lines.push(`  Error: ${r.error} — ${r.detail}`);
+                }
+            }
+            if (!allOk && results.length < args.commits.length) {
+                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");
+        },
+    });
+}