pi-webdesk 0.1.0

package/dist/packages/git/src/merge.js

@@ -0,0 +1,1008 @@
+// packages/git/src/merge.ts
+import {
+  GitMergeConflictError,
+  GitServiceError,
+  boundedDetailText,
+  isGitServiceError
+} from "./errors.js";
+import { inspectRepository, COMMIT_SHA_PATTERN } from "./repository.js";
+import {
+  commitEntryId,
+  parseDiffTreeOutput,
+  readGpgSignConfig,
+  requireCommitIdentity
+} from "./commit.js";
+import {
+  READ_ONLY_GIT_FLAGS,
+  parseStatusOutput,
+  validateReportedPath
+} from "./review.js";
+import {
+  defaultGitRunner,
+  runGitExpectingSuccess
+} from "./runner.js";
+var DEFAULT_MERGE_MAX_FILES = 200;
+var DEFAULT_MERGE_MAX_DIFF_CHARS_PER_FILE = 2e4;
+var DEFAULT_MERGE_MAX_TOTAL_DIFF_CHARS = 2e5;
+var DEFAULT_MERGE_MAX_DURATION_MS = 2e4;
+var DEFAULT_MERGE_SIGNING_TIMEOUT_MS = 3e4;
+var DEFAULT_MERGE_MAX_COMMIT_SUBJECTS = 20;
+var DEFAULT_MERGE_MAX_ENTRIES = 2e3;
+var DEFAULT_MERGE_MAX_GUARD_PATH_CHARS = 96e3;
+var DEFAULT_MERGE_GUARD_TIMEOUT_MS = 2e3;
+var MAX_MERGE_MESSAGE_CHARS = 1e5;
+var MAX_MERGE_CONFLICT_PATHS = 20;
+var MIN_MERGE_GIT_VERSION = "2.38";
+var MERGE_DIFF_TIMEOUT_MS = 2e3;
+var DIFF_FLAGS = [
+  "--no-color",
+  "--no-ext-diff",
+  "--no-textconv",
+  "--unified=3"
+];
+function positiveBound(value, label) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new GitServiceError("GIT_STATE_TOO_LARGE", `${label} must be a positive safe integer`);
+  }
+  return value;
+}
+var OID_PATTERN = COMMIT_SHA_PATTERN;
+function singleOid(stdout, label) {
+  const value = stdout.endsWith("\n") ? stdout.slice(0, -1) : stdout;
+  if (!OID_PATTERN.test(value)) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", `git returned an unexpected ${label}`, {
+      details: { value: boundedDetailText(value, 80) }
+    });
+  }
+  return value;
+}
+function requireExactOid(value, label) {
+  if (!OID_PATTERN.test(value)) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", `Merge requires an exact ${label}`);
+  }
+}
+function isBinaryDiff(diff) {
+  return diff.split("\n").some((line) => line.startsWith("Binary files ") && line.endsWith(" differ"));
+}
+function withDeadline(runner, deadlineMs, now, perCommandLimitMs) {
+  return async (args, options = {}) => {
+    const remainingMs = Math.floor(deadlineMs - now());
+    if (remainingMs < 1) {
+      throw new GitServiceError(
+        "GIT_STATE_DEADLINE_EXCEEDED",
+        "The merge preflight exceeded its overall time budget"
+      );
+    }
+    const callerLimitMs = options.timeoutMs ?? Number.POSITIVE_INFINITY;
+    const commandLimitMs = perCommandLimitMs ?? Number.POSITIVE_INFINITY;
+    const aggregateIsLimit = remainingMs <= callerLimitMs && remainingMs <= commandLimitMs;
+    try {
+      return await runner(args, {
+        ...options,
+        timeoutMs: Math.min(remainingMs, callerLimitMs, commandLimitMs)
+      });
+    } catch (error) {
+      if (aggregateIsLimit && isGitServiceError(error, "GIT_COMMAND_TERMINATED")) {
+        throw new GitServiceError(
+          "GIT_STATE_DEADLINE_EXCEEDED",
+          "The merge preflight exceeded its overall time budget",
+          { cause: error }
+        );
+      }
+      throw error;
+    }
+  };
+}
+async function ensureMergeCapableGit(runner = defaultGitRunner, cwd) {
+  const result = await runGitExpectingSuccess(
+    runner,
+    ["version"],
+    cwd === void 0 ? {} : { cwd }
+  );
+  const match = /git version (\d+)\.(\d+)/.exec(result.stdout);
+  if (match === null) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", "git version returned unexpected output", {
+      details: { value: boundedDetailText(result.stdout, 80) }
+    });
+  }
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  if (major > 2 || major === 2 && minor >= 38) return;
+  throw new GitServiceError(
+    "GIT_MERGE_VERSION_UNSUPPORTED",
+    `Webdesk merges require Git ${MIN_MERGE_GIT_VERSION} or newer (merge-tree --write-tree); found ${major}.${minor}`,
+    { details: { major, minor } }
+  );
+}
+async function classifyAncestry(runner, cwd, targetHead, taskHead) {
+  const taskReachable = await runner(
+    ["merge-base", "--is-ancestor", "--end-of-options", taskHead, targetHead],
+    { cwd }
+  );
+  if (taskReachable.exitCode === 0) return "already-merged";
+  if (taskReachable.exitCode !== 1) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", "git merge-base exited unexpectedly", {
+      details: { exitCode: taskReachable.exitCode, stderr: boundedDetailText(taskReachable.stderr) }
+    });
+  }
+  const targetReachable = await runner(
+    ["merge-base", "--is-ancestor", "--end-of-options", targetHead, taskHead],
+    { cwd }
+  );
+  if (targetReachable.exitCode === 0) return "fast-forward";
+  if (targetReachable.exitCode !== 1) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", "git merge-base exited unexpectedly", {
+      details: {
+        exitCode: targetReachable.exitCode,
+        stderr: boundedDetailText(targetReachable.stderr)
+      }
+    });
+  }
+  const base = await runner(["merge-base", "--end-of-options", targetHead, taskHead], { cwd });
+  if (base.exitCode === 0) return "diverged";
+  if (base.exitCode === 1) return "unrelated";
+  throw new GitServiceError("GIT_COMMAND_FAILED", "git merge-base exited unexpectedly", {
+    details: { exitCode: base.exitCode, stderr: boundedDetailText(base.stderr) }
+  });
+}
+async function requireRecordedBase(runner, cwd, baseCommit, targetHead, taskHead) {
+  for (const [label, head] of [
+    ["task", taskHead],
+    ["target", targetHead]
+  ]) {
+    const result = await runner(
+      ["merge-base", "--is-ancestor", "--end-of-options", baseCommit, head],
+      { cwd }
+    );
+    if (result.exitCode === 0) continue;
+    if (result.exitCode === 1) {
+      throw new GitServiceError(
+        "GIT_MERGE_WRONG_BASE",
+        `The recorded task base is no longer an ancestor of the ${label} branch; Webdesk refuses to merge a rebased or wrong-base task`
+      );
+    }
+    throw new GitServiceError(
+      "GIT_COMMAND_FAILED",
+      "git merge-base could not verify the recorded task base",
+      {
+        details: {
+          side: label,
+          exitCode: result.exitCode,
+          stderr: boundedDetailText(result.stderr)
+        }
+      }
+    );
+  }
+}
+async function writeMergeTree(runner, cwd, targetHead, taskHead) {
+  const result = await runner(
+    [
+      "merge-tree",
+      "--write-tree",
+      "-z",
+      "--name-only",
+      "--no-messages",
+      "--end-of-options",
+      targetHead,
+      taskHead
+    ],
+    { cwd }
+  );
+  if (result.exitCode !== 0 && result.exitCode !== 1) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", "git merge-tree exited unexpectedly", {
+      details: { exitCode: result.exitCode, stderr: boundedDetailText(result.stderr) }
+    });
+  }
+  const tokens = result.stdout.split("\0");
+  const tree = tokens[0];
+  if (tree === void 0 || !OID_PATTERN.test(tree)) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", "git merge-tree returned an unexpected tree id", {
+      details: { value: boundedDetailText(tree ?? "", 80) }
+    });
+  }
+  if (result.exitCode === 0) return tree;
+  const conflicted = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const token of tokens.slice(1)) {
+    if (token === "") continue;
+    const validated = validateReportedPath(token);
+    if (seen.has(validated)) continue;
+    seen.add(validated);
+    conflicted.push(validated);
+  }
+  const retained = conflicted.slice(0, MAX_MERGE_CONFLICT_PATHS);
+  throw new GitMergeConflictError(
+    "The merge has content conflicts; resolve them in the task worktree (merge the target branch into the task) and commit before merging",
+    retained,
+    conflicted.length - retained.length
+  );
+}
+function parseCommitSubjects(stdout) {
+  const lines = stdout.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  if (lines.length % 2 !== 0) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", "git rev-list returned unexpected output", {
+      details: { sample: boundedDetailText(stdout, 120) }
+    });
+  }
+  const subjects = [];
+  for (let index = 0; index < lines.length; index += 2) {
+    const header = lines[index];
+    const body = lines[index + 1];
+    const separator = body.indexOf("
");
+    if (!header.startsWith("commit ") || separator === -1 || !OID_PATTERN.test(body.slice(0, separator))) {
+      throw new GitServiceError("GIT_COMMAND_FAILED", "git rev-list returned unexpected output", {
+        details: { sample: boundedDetailText(`${header}
+${body}`, 120) }
+      });
+    }
+    subjects.push(body.slice(separator + 1));
+  }
+  return subjects;
+}
+async function deriveMergePaths(runner, cwd, previousHead, newTreeish) {
+  const rawDiff = await runGitExpectingSuccess(
+    runner,
+    [
+      ...READ_ONLY_GIT_FLAGS,
+      "diff-tree",
+      "-r",
+      "-z",
+      "--find-renames",
+      previousHead,
+      newTreeish
+    ],
+    { cwd }
+  );
+  const records = parseDiffTreeOutput(rawDiff.stdout);
+  if (records.length > DEFAULT_MERGE_MAX_ENTRIES) {
+    throw new GitServiceError(
+      "GIT_STATE_TOO_LARGE",
+      "The recovered merge changes too many paths to inspect safely",
+      { details: { entries: records.length, limit: DEFAULT_MERGE_MAX_ENTRIES } }
+    );
+  }
+  const addedPaths = [];
+  const changedPaths = /* @__PURE__ */ new Set();
+  let pathChars = 0;
+  function addChangedPath(candidate) {
+    if (changedPaths.has(candidate)) return;
+    pathChars += candidate.length + 1;
+    if (pathChars > DEFAULT_MERGE_MAX_GUARD_PATH_CHARS) {
+      throw new GitServiceError(
+        "GIT_STATE_TOO_LARGE",
+        "The recovered merge path set is too large to inspect safely",
+        { details: { pathChars, limit: DEFAULT_MERGE_MAX_GUARD_PATH_CHARS } }
+      );
+    }
+    changedPaths.add(candidate);
+  }
+  for (const record of records) {
+    validateReportedPath(record.path);
+    if (record.previousPath !== null) validateReportedPath(record.previousPath);
+    addChangedPath(record.path);
+    if (record.previousPath !== null) addChangedPath(record.previousPath);
+    if (record.status === "added" || record.previousPath !== null) {
+      addedPaths.push(record.path);
+    }
+  }
+  return { addedPaths, changedPaths: [...changedPaths] };
+}
+async function prepareMergeTree(options) {
+  const maxFiles = positiveBound(options.maxFiles ?? DEFAULT_MERGE_MAX_FILES, "Merge file limit");
+  const maxDiffCharsPerFile = positiveBound(
+    options.maxDiffCharsPerFile ?? DEFAULT_MERGE_MAX_DIFF_CHARS_PER_FILE,
+    "Per-file diff limit"
+  );
+  const maxTotalDiffChars = positiveBound(
+    options.maxTotalDiffChars ?? DEFAULT_MERGE_MAX_TOTAL_DIFF_CHARS,
+    "Total diff limit"
+  );
+  const maxDurationMs = positiveBound(
+    options.maxDurationMs ?? DEFAULT_MERGE_MAX_DURATION_MS,
+    "Merge preflight duration limit"
+  );
+  const maxCommitSubjects = positiveBound(
+    options.maxCommitSubjects ?? DEFAULT_MERGE_MAX_COMMIT_SUBJECTS,
+    "Commit subject limit"
+  );
+  const maxEntries = positiveBound(
+    options.maxEntries ?? DEFAULT_MERGE_MAX_ENTRIES,
+    "Merge entry limit"
+  );
+  requireExactOid(options.targetHead, "target head");
+  requireExactOid(options.taskHead, "task head");
+  requireExactOid(options.baseCommit, "recorded task base");
+  const now = options.now ?? Date.now;
+  const deadlineMs = now() + maxDurationMs;
+  const runner = withDeadline(options.runner ?? defaultGitRunner, deadlineMs, now);
+  const diffRunner = withDeadline(
+    options.runner ?? defaultGitRunner,
+    deadlineMs,
+    now,
+    MERGE_DIFF_TIMEOUT_MS
+  );
+  const cwd = options.targetRootPath;
+  const ancestry = await classifyAncestry(runner, cwd, options.targetHead, options.taskHead);
+  if (ancestry === "already-merged") {
+    throw new GitServiceError(
+      "GIT_MERGE_ALREADY_MERGED",
+      "The task branch is already contained in the target branch; archive the task instead of merging"
+    );
+  }
+  if (ancestry === "unrelated") {
+    throw new GitServiceError(
+      "GIT_MERGE_UNRELATED_HISTORIES",
+      "The task and target branches share no history; Webdesk refuses to merge unrelated histories"
+    );
+  }
+  await requireRecordedBase(
+    runner,
+    cwd,
+    options.baseCommit,
+    options.targetHead,
+    options.taskHead
+  );
+  const mode = ancestry === "fast-forward" ? "fast-forward" : "merge-commit";
+  const targetTree = singleOid(
+    (await runGitExpectingSuccess(
+      runner,
+      ["rev-parse", "--verify", `${options.targetHead}^{tree}`],
+      { cwd }
+    )).stdout,
+    "target tree id"
+  );
+  let mergedTree;
+  if (mode === "fast-forward") {
+    mergedTree = singleOid(
+      (await runGitExpectingSuccess(
+        runner,
+        ["rev-parse", "--verify", `${options.taskHead}^{tree}`],
+        { cwd }
+      )).stdout,
+      "task tree id"
+    );
+  } else {
+    mergedTree = await writeMergeTree(runner, cwd, options.targetHead, options.taskHead);
+  }
+  if (mergedTree === targetTree) {
+    throw new GitServiceError(
+      "GIT_MERGE_NOTHING_TO_MERGE",
+      "The merge result is exactly the current target tree (the changes are already present); archive the task instead of merging"
+    );
+  }
+  const rawDiff = await runGitExpectingSuccess(
+    runner,
+    [
+      ...READ_ONLY_GIT_FLAGS,
+      "diff-tree",
+      "-r",
+      "-z",
+      "--find-renames",
+      options.targetHead,
+      mergedTree
+    ],
+    { cwd }
+  );
+  const records = parseDiffTreeOutput(rawDiff.stdout);
+  if (records.length > maxEntries) {
+    throw new GitServiceError(
+      "GIT_STATE_TOO_LARGE",
+      `The merge changes ${records.length} paths, exceeding Webdesk's safety limit of ${maxEntries}`,
+      { details: { entries: records.length, limit: maxEntries } }
+    );
+  }
+  const addedPaths = [];
+  let mergePathChars = 0;
+  for (const record of records) {
+    validateReportedPath(record.path);
+    if (record.previousPath !== null) validateReportedPath(record.previousPath);
+    mergePathChars += record.path.length + 1 + (record.previousPath === null ? 0 : record.previousPath.length + 1);
+    if (mergePathChars > DEFAULT_MERGE_MAX_GUARD_PATH_CHARS) {
+      throw new GitServiceError(
+        "GIT_STATE_TOO_LARGE",
+        "The merge path set is too large to inspect safely",
+        { details: { pathChars: mergePathChars, limit: DEFAULT_MERGE_MAX_GUARD_PATH_CHARS } }
+      );
+    }
+    if (record.oldMode === "160000" || record.newMode === "160000") {
+      throw new GitServiceError(
+        "GIT_MERGE_STATE_UNSUPPORTED",
+        "The merge changes a gitlink (submodule pointer), which Webdesk cannot publish and sync safely yet",
+        { details: { path: boundedDetailText(record.path, 200) } }
+      );
+    }
+    if (record.status === "added" || record.previousPath !== null) {
+      addedPaths.push(record.path);
+    }
+  }
+  records.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const totalFiles = records.length;
+  const selected = records.slice(0, maxFiles);
+  let remainingChars = maxTotalDiffChars;
+  let totalDiffTruncated = false;
+  const files = [];
+  for (const record of selected) {
+    const base = {
+      entryId: commitEntryId(record),
+      path: record.path,
+      previousPath: record.previousPath,
+      kind: record.status
+    };
+    if (remainingChars <= 0) {
+      totalDiffTruncated = true;
+      files.push({
+        ...base,
+        binary: false,
+        diff: null,
+        diffTruncated: false,
+        diffOmittedReason: "total-budget"
+      });
+      continue;
+    }
+    let produced;
+    try {
+      produced = await diffRunner(
+        [
+          ...READ_ONLY_GIT_FLAGS,
+          "diff-tree",
+          "-r",
+          "-p",
+          ...DIFF_FLAGS,
+          "--find-renames",
+          options.targetHead,
+          mergedTree,
+          "--",
+          record.path,
+          ...record.previousPath === null ? [] : [record.previousPath]
+        ],
+        { cwd }
+      );
+    } catch (error) {
+      if (isGitServiceError(error, "GIT_OUTPUT_OVERFLOW")) {
+        files.push({
+          ...base,
+          binary: false,
+          diff: null,
+          diffTruncated: false,
+          diffOmittedReason: "too-large"
+        });
+        continue;
+      }
+      if (isGitServiceError(error, "GIT_STATE_DEADLINE_EXCEEDED") || isGitServiceError(error, "GIT_COMMAND_TERMINATED")) {
+        totalDiffTruncated = true;
+        files.push({
+          ...base,
+          binary: false,
+          diff: null,
+          diffTruncated: false,
+          diffOmittedReason: "review-budget"
+        });
+        continue;
+      }
+      throw error;
+    }
+    if (produced.exitCode !== 0) {
+      files.push({
+        ...base,
+        binary: false,
+        diff: null,
+        diffTruncated: false,
+        diffOmittedReason: "diff-failed"
+      });
+      continue;
+    }
+    if (isBinaryDiff(produced.stdout)) {
+      files.push({
+        ...base,
+        binary: true,
+        diff: null,
+        diffTruncated: false,
+        diffOmittedReason: "binary"
+      });
+      continue;
+    }
+    const perFileLimit = Math.min(maxDiffCharsPerFile, remainingChars);
+    let text = produced.stdout;
+    let truncated = false;
+    if (text.length > perFileLimit) {
+      if (perFileLimit < maxDiffCharsPerFile) totalDiffTruncated = true;
+      text = text.slice(0, perFileLimit);
+      truncated = true;
+    }
+    remainingChars -= text.length;
+    files.push({
+      ...base,
+      binary: false,
+      diff: text,
+      diffTruncated: truncated,
+      diffOmittedReason: null
+    });
+  }
+  const countResult = await runGitExpectingSuccess(
+    runner,
+    ["rev-list", "--count", "--end-of-options", `${options.targetHead}..${options.taskHead}`],
+    { cwd }
+  );
+  const commitCount = Number.parseInt(countResult.stdout.trim(), 10);
+  if (!Number.isSafeInteger(commitCount) || commitCount < 1) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", "git rev-list returned an unexpected count", {
+      details: { value: boundedDetailText(countResult.stdout, 80) }
+    });
+  }
+  const subjectsResult = await runGitExpectingSuccess(
+    runner,
+    [
+      "rev-list",
+      `--max-count=${maxCommitSubjects}`,
+      "--format=%H%x01%s",
+      "--end-of-options",
+      `${options.targetHead}..${options.taskHead}`
+    ],
+    { cwd }
+  );
+  const commitSubjects = parseCommitSubjects(subjectsResult.stdout);
+  return {
+    mode,
+    targetHead: options.targetHead,
+    taskHead: options.taskHead,
+    mergedTree,
+    files,
+    totalFiles,
+    omittedFiles: totalFiles - selected.length,
+    totalDiffTruncated,
+    addedPaths,
+    commitCount,
+    commitSubjects
+  };
+}
+async function assertMergeTargetPathsUnoccupied(targetRootPath, addedPaths, options = {}) {
+  const maxDurationMs = positiveBound(
+    options.maxDurationMs ?? DEFAULT_MERGE_GUARD_TIMEOUT_MS,
+    "Merge occupancy duration limit"
+  );
+  const maxPathChars = positiveBound(
+    options.maxPathChars ?? DEFAULT_MERGE_MAX_GUARD_PATH_CHARS,
+    "Merge occupancy path limit"
+  );
+  const now = options.now ?? Date.now;
+  const runner = withDeadline(
+    options.runner ?? defaultGitRunner,
+    now() + maxDurationMs,
+    now
+  );
+  const candidates = /* @__PURE__ */ new Set();
+  let pathChars = 0;
+  for (const addedPath of addedPaths) {
+    const segments = validateReportedPath(addedPath).split("/");
+    for (let depth = 1; depth <= segments.length; depth++) {
+      const candidate = segments.slice(0, depth).join("/");
+      if (candidates.has(candidate)) continue;
+      const nextPathChars = pathChars + candidate.length + 1;
+      if (nextPathChars > maxPathChars) {
+        throw new GitServiceError(
+          "GIT_STATE_TOO_LARGE",
+          "The merge-created path set is too large to inspect safely",
+          { details: { pathChars: nextPathChars, limit: maxPathChars } }
+        );
+      }
+      candidates.add(candidate);
+      pathChars = nextPathChars;
+    }
+  }
+  const pathspecs = [...candidates];
+  if (pathspecs.length === 0) return;
+  async function firstOccupant(ignored) {
+    const result = await runGitExpectingSuccess(
+      runner,
+      [
+        ...READ_ONLY_GIT_FLAGS,
+        "ls-files",
+        "--others",
+        ...ignored ? ["--ignored"] : [],
+        "--exclude-standard",
+        "-z",
+        "--",
+        ...pathspecs
+      ],
+      { cwd: targetRootPath }
+    );
+    const reported = result.stdout.split("\0").find((candidate) => candidate.length > 0);
+    return reported === void 0 ? null : validateReportedPath(reported);
+  }
+  const occupied = await firstOccupant(false) ?? await firstOccupant(true);
+  if (occupied !== null) {
+    throw new GitServiceError(
+      "GIT_MERGE_TARGET_PATH_OCCUPIED",
+      "An untracked or ignored path already occupies a location the merge would create; move it away and preflight again",
+      { details: { path: boundedDetailText(occupied, 200) } }
+    );
+  }
+}
+async function isMergeCommitAncestor(targetRootPath, ancestor, descendant, runner = defaultGitRunner) {
+  requireExactOid(ancestor, "ancestor commit");
+  requireExactOid(descendant, "descendant commit");
+  const result = await runner(
+    ["merge-base", "--is-ancestor", "--end-of-options", ancestor, descendant],
+    { cwd: targetRootPath }
+  );
+  if (result.exitCode === 0) return true;
+  if (result.exitCode === 1) return false;
+  throw new GitServiceError("GIT_COMMAND_FAILED", "Git could not verify merge ancestry", {
+    details: { exitCode: result.exitCode, stderr: boundedDetailText(result.stderr) }
+  });
+}
+function validateBranchName(branch, label) {
+  if (branch.length === 0 || branch.length > 1024) {
+    throw new GitServiceError("GIT_COMMAND_FAILED", `Merge requires a bounded ${label}`);
+  }
+}
+async function readBranchTip(runner, cwd, branch) {
+  try {
+    const result = await runner(
+      ["rev-parse", "--verify", "--end-of-options", `refs/heads/${branch}`],
+      { cwd }
+    );
+    if (result.exitCode !== 0) return null;
+    return singleOid(result.stdout, "branch tip");
+  } catch {
+    return null;
+  }
+}
+async function publishMerge(options) {
+  const runner = options.runner ?? defaultGitRunner;
+  const signingTimeoutMs = positiveBound(
+    options.signingTimeoutMs ?? DEFAULT_MERGE_SIGNING_TIMEOUT_MS,
+    "Signing timeout"
+  );
+  requireExactOid(options.taskHead, "task head");
+  requireExactOid(options.targetHead, "target head");
+  requireExactOid(options.mergedTree, "merged tree");
+  validateBranchName(options.taskBranch, "task branch");
+  validateBranchName(options.targetBranch, "target branch");
+  if (options.taskBranch === options.targetBranch) {
+    throw new GitServiceError(
+      "GIT_COMMAND_FAILED",
+      "Merge publication requires distinct task and target branches"
+    );
+  }
+  if (options.reflogReason.length === 0 || options.reflogReason.length > 200 || [...options.reflogReason].some((character) => {
+    const code = character.codePointAt(0) ?? 0;
+    return code < 32 || code === 127;
+  })) {
+    throw new GitServiceError(
+      "GIT_COMMAND_FAILED",
+      "Merge publication requires a bounded, control-character-free reflog reason"
+    );
+  }
+  if (options.mode === "fast-forward" !== (options.message === null)) {
+    throw new GitServiceError(
+      "GIT_COMMAND_FAILED",
+      "Exactly the merge-commit mode carries a merge message"
+    );
+  }
+  const cwd = options.targetRootPath;
+  let newCommit;
+  let signed = false;
+  if (options.mode === "fast-forward") {
+    const taskTree = singleOid(
+      (await runGitExpectingSuccess(runner, ["rev-parse", "--verify", `${options.taskHead}^{tree}`], {
+        cwd
+      })).stdout,
+      "task tree id"
+    );
+    if (taskTree !== options.mergedTree) {
+      throw new GitServiceError(
+        "GIT_MERGE_TREE_MISMATCH",
+        "The fast-forward head no longer carries the approved tree; no ref was moved",
+        { details: { approvedTree: options.mergedTree, taskTree } }
+      );
+    }
+    newCommit = options.taskHead;
+  } else {
+    const message = options.message;
+    if (message.trim().length === 0 || message.length > MAX_MERGE_MESSAGE_CHARS) {
+      throw new GitServiceError(
+        "GIT_COMMAND_FAILED",
+        "Merge publication requires a non-empty bounded message"
+      );
+    }
+    await requireCommitIdentity(runner, cwd);
+    const sign = await readGpgSignConfig(runner, cwd);
+    const body = message.endsWith("\n") ? message : `${message}
+`;
+    const commitResult = await runner(
+      [
+        "commit-tree",
+        ...sign ? ["-S"] : [],
+        "-p",
+        options.targetHead,
+        "-p",
+        options.taskHead,
+        options.mergedTree
+      ],
+      {
+        cwd,
+        stdin: body,
+        ...sign ? { timeoutMs: signingTimeoutMs } : {}
+      }
+    ).catch((error) => {
+      if (sign && isGitServiceError(error, "GIT_COMMAND_TERMINATED")) {
+        throw new GitServiceError(
+          "GIT_MERGE_SIGNING_FAILED",
+          "Merge-commit signing did not complete within its time bound; no ref was moved",
+          { cause: error }
+        );
+      }
+      throw error;
+    });
+    if (commitResult.exitCode !== 0) {
+      if (sign) {
+        throw new GitServiceError(
+          "GIT_MERGE_SIGNING_FAILED",
+          "Merge-commit signing failed; no ref was moved",
+          { details: { stderr: boundedDetailText(commitResult.stderr) } }
+        );
+      }
+      throw new GitServiceError("GIT_COMMAND_FAILED", "git commit-tree exited unexpectedly", {
+        details: {
+          exitCode: commitResult.exitCode,
+          stderr: boundedDetailText(commitResult.stderr)
+        }
+      });
+    }
+    newCommit = singleOid(commitResult.stdout, "merge commit id");
+    signed = sign;
+    const commitTree = singleOid(
+      (await runGitExpectingSuccess(runner, ["rev-parse", "--verify", `${newCommit}^{tree}`], {
+        cwd
+      })).stdout,
+      "merge commit tree id"
+    );
+    if (commitTree !== options.mergedTree) {
+      throw new GitServiceError(
+        "GIT_MERGE_TREE_MISMATCH",
+        "The created merge commit does not carry the approved tree; no ref was moved",
+        { details: { approvedTree: options.mergedTree, commitTree } }
+      );
+    }
+    const parents = (await runGitExpectingSuccess(
+      runner,
+      ["rev-list", "--parents", "--max-count=1", "--end-of-options", newCommit],
+      { cwd }
+    )).stdout.trim().split(" ");
+    if (parents.length !== 3 || parents[0] !== newCommit || parents[1] !== options.targetHead || parents[2] !== options.taskHead) {
+      throw new GitServiceError(
+        "GIT_MERGE_TREE_MISMATCH",
+        "The created merge commit does not carry the approved parent order; no ref was moved",
+        { details: { commit: newCommit } }
+      );
+    }
+  }
+  await options.recordIntent?.(newCommit);
+  const transactionStdin = `start\0verify refs/heads/${options.taskBranch}\0${options.taskHead}\0update refs/heads/${options.targetBranch}\0${newCommit}\0${options.targetHead}\0prepare\0commit\0`;
+  let publishFailure = null;
+  let publicationIndeterminate = false;
+  try {
+    const transaction = await runner(
+      ["update-ref", "-m", options.reflogReason, "--stdin", "-z"],
+      { cwd, stdin: transactionStdin }
+    );
+    if (transaction.exitCode !== 0) {
+      publishFailure = new GitServiceError(
+        "GIT_MERGE_REF_CAS_FAILED",
+        "git update-ref did not report a successful publication",
+        { details: { stderr: boundedDetailText(transaction.stderr) } }
+      );
+    }
+  } catch (error) {
+    publishFailure = error;
+    publicationIndeterminate = true;
+  }
+  if (publishFailure !== null) {
+    const targetTip = await readBranchTip(runner, cwd, options.targetBranch);
+    if (targetTip === null) {
+      throw new GitServiceError(
+        "GIT_MERGE_PUBLICATION_UNKNOWN",
+        `Git stopped before Webdesk could determine whether commit ${newCommit.slice(0, 12)} was published to the target branch; inspect the repository before retrying`,
+        {
+          cause: publishFailure,
+          details: { branch: options.targetBranch, commit: newCommit }
+        }
+      );
+    }
+    if (targetTip !== newCommit) {
+      if (publicationIndeterminate) {
+        throw new GitServiceError(
+          "GIT_MERGE_PUBLICATION_UNKNOWN",
+          `Git stopped before Webdesk could determine whether commit ${newCommit.slice(0, 12)} was published`,
+          {
+            cause: publishFailure,
+            details: { branch: options.targetBranch, commit: newCommit }
+          }
+        );
+      }
+      if (targetTip !== options.targetHead) {
+        throw new GitServiceError(
+          "GIT_MERGE_TARGET_MOVED",
+          "The target branch moved before publication; Webdesk did not replace the newer tip",
+          { cause: publishFailure }
+        );
+      }
+      const sourceTip = await readBranchTip(runner, cwd, options.taskBranch);
+      if (sourceTip !== options.taskHead) {
+        throw new GitServiceError(
+          "GIT_MERGE_SOURCE_MOVED",
+          "The task branch changed underneath the approved merge; nothing was published",
+          {
+            cause: publishFailure,
+            details: { sourceReadable: sourceTip !== null }
+          }
+        );
+      }
+      throw new GitServiceError(
+        "GIT_MERGE_REF_CAS_FAILED",
+        "The ref transaction was refused (a repository hook may have aborted it); nothing was published",
+        { cause: publishFailure }
+      );
+    }
+  }
+  return {
+    mode: options.mode,
+    newCommit,
+    treeOid: options.mergedTree,
+    previousTargetHead: options.targetHead,
+    taskHead: options.taskHead,
+    signed
+  };
+}
+async function assertMergePathsUseOrdinaryIndexEntries(runner, cwd, changedPaths) {
+  if (changedPaths.length === 0) return;
+  const result = await runGitExpectingSuccess(
+    runner,
+    [
+      ...READ_ONLY_GIT_FLAGS,
+      "ls-files",
+      "-v",
+      "-z",
+      "--",
+      ...changedPaths
+    ],
+    { cwd }
+  );
+  for (const token of result.stdout.split("\0")) {
+    if (token.length === 0) continue;
+    if (token.length < 3 || token[1] !== " ") {
+      throw new GitServiceError(
+        "GIT_COMMAND_FAILED",
+        "Git returned unexpected index flags before checkout sync"
+      );
+    }
+    const tag = token[0];
+    const reportedPath = validateReportedPath(token.slice(2));
+    if (tag !== "H") {
+      throw new GitServiceError(
+        "GIT_MERGE_SYNC_REFUSED",
+        "A merge-modified target path uses skip-worktree, assume-unchanged, or another non-ordinary index mode; clear the index flag before reconciling",
+        { details: { path: boundedDetailText(reportedPath, 200), indexTag: tag } }
+      );
+    }
+  }
+}
+async function syncTargetCheckout(options) {
+  const runner = options.runner ?? defaultGitRunner;
+  requireExactOid(options.previousTargetHead, "previous target head");
+  requireExactOid(options.newTargetHead, "new target head");
+  validateBranchName(options.targetBranch, "target branch");
+  const cwd = options.targetRootPath;
+  const inspected = await inspectRepository(cwd, { runner });
+  if (inspected.root !== cwd || inspected.branch !== options.targetBranch || inspected.headCommit !== options.newTargetHead) {
+    throw new GitServiceError(
+      "GIT_MERGE_TARGET_MISMATCHED",
+      "The target checkout is no longer on the published branch and head; Webdesk refuses to touch it",
+      {
+        details: {
+          expectedBranch: boundedDetailText(options.targetBranch, 200),
+          actualBranch: inspected.branch === null ? null : boundedDetailText(inspected.branch, 200),
+          expectedHead: options.newTargetHead,
+          actualHead: inspected.headCommit
+        }
+      }
+    );
+  }
+  const mergePaths = await deriveMergePaths(
+    runner,
+    cwd,
+    options.previousTargetHead,
+    options.newTargetHead
+  );
+  await assertMergePathsUseOrdinaryIndexEntries(runner, cwd, mergePaths.changedPaths);
+  for (const [args, label] of [
+    [
+      [
+        ...READ_ONLY_GIT_FLAGS,
+        "diff-index",
+        "--cached",
+        "--quiet",
+        "--ignore-submodules=none",
+        options.previousTargetHead,
+        "--"
+      ],
+      "index"
+    ],
+    [
+      [
+        ...READ_ONLY_GIT_FLAGS,
+        "diff-files",
+        "--quiet",
+        "--ignore-submodules=none",
+        "--"
+      ],
+      "worktree"
+    ]
+  ]) {
+    const clean = await runner(args, { cwd });
+    if (clean.exitCode === 0) continue;
+    if (clean.exitCode === 1) {
+      throw new GitServiceError(
+        "GIT_MERGE_SYNC_REFUSED",
+        `The target ${label} changed after publication; Webdesk refuses to overwrite it`
+      );
+    }
+    throw new GitServiceError(
+      "GIT_COMMAND_FAILED",
+      `Git could not verify the target ${label} before checkout sync`,
+      { details: { exitCode: clean.exitCode, stderr: boundedDetailText(clean.stderr) } }
+    );
+  }
+  await assertMergeTargetPathsUnoccupied(cwd, mergePaths.addedPaths, { runner });
+  const sync = await runner(
+    ["read-tree", "-m", "-u", "--end-of-options", options.previousTargetHead, options.newTargetHead],
+    { cwd }
+  );
+  if (sync.exitCode !== 0) {
+    throw new GitServiceError(
+      "GIT_MERGE_SYNC_REFUSED",
+      "Git refused to update the target checkout (local edits, an untracked file, or a held index lock); nothing was modified and nothing was rolled back",
+      { details: { stderr: boundedDetailText(sync.stderr) } }
+    );
+  }
+  let statusClean = false;
+  try {
+    const status = await runner(
+      [...READ_ONLY_GIT_FLAGS, "status", "--porcelain=v2", "-z", "--untracked-files=all"],
+      { cwd }
+    );
+    statusClean = status.exitCode === 0 && parseStatusOutput(status.stdout).length === 0;
+  } catch {
+    statusClean = false;
+  }
+  let headVerified = false;
+  try {
+    const verified = await inspectRepository(cwd, { runner });
+    headVerified = verified.branch === options.targetBranch && verified.headCommit === options.newTargetHead;
+  } catch {
+    headVerified = false;
+  }
+  return { statusClean, headVerified };
+}
+export {
+  DEFAULT_MERGE_GUARD_TIMEOUT_MS,
+  DEFAULT_MERGE_MAX_COMMIT_SUBJECTS,
+  DEFAULT_MERGE_MAX_DIFF_CHARS_PER_FILE,
+  DEFAULT_MERGE_MAX_DURATION_MS,
+  DEFAULT_MERGE_MAX_ENTRIES,
+  DEFAULT_MERGE_MAX_FILES,
+  DEFAULT_MERGE_MAX_GUARD_PATH_CHARS,
+  DEFAULT_MERGE_MAX_TOTAL_DIFF_CHARS,
+  DEFAULT_MERGE_SIGNING_TIMEOUT_MS,
+  MAX_MERGE_CONFLICT_PATHS,
+  MAX_MERGE_MESSAGE_CHARS,
+  MIN_MERGE_GIT_VERSION,
+  assertMergeTargetPathsUnoccupied,
+  ensureMergeCapableGit,
+  isMergeCommitAncestor,
+  prepareMergeTree,
+  publishMerge,
+  syncTargetCheckout
+};