pi-webdesk 0.1.0

package/dist/apps/daemon/src/task-merge.js

@@ -0,0 +1,912 @@
+// apps/daemon/src/task-merge.ts
+import { randomUUID } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import {
+  GitMergeConflictError,
+  assertMergeTargetPathsUnoccupied,
+  captureWorktreeState,
+  ensureMergeCapableGit,
+  isMergeCommitAncestor,
+  isGitServiceError,
+  prepareMergeTree,
+  publishMerge,
+  syncTargetCheckout
+} from "../../../packages/git/src/index.js";
+import { sanitizeApprovalDisplayText } from "../../../packages/pi-bridge/src/index.js";
+import {
+  PROTOCOL_VERSION,
+  TASK_MERGE_MAX_COMMIT_SUBJECTS,
+  TASK_MERGE_MAX_COMMIT_SUBJECT_CHARS,
+  TASK_MERGE_MAX_CONFLICT_PATHS,
+  TASK_MERGE_MAX_FILE_DIFF_CHARS,
+  TASK_MERGE_MAX_TOTAL_DIFF_CHARS,
+  repositoryMergeSyncResultSchema,
+  taskMergePreflightSchema,
+  taskMergeResultSchema
+} from "../../../packages/protocol/src/index.js";
+var MERGE_PREFLIGHT_TTL_MS = 10 * 60 * 1e3;
+var TaskMergeOperationError = class extends Error {
+  name = "TaskMergeOperationError";
+  code;
+  status;
+  /** Escaped, bounded conflicted paths; only for merge-conflicted. */
+  conflictPaths;
+  omittedConflictPaths;
+  constructor(code, message, status, options) {
+    super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+    this.code = code;
+    this.status = status;
+    if (options?.conflictPaths !== void 0) {
+      this.conflictPaths = options.conflictPaths;
+      this.omittedConflictPaths = options.omittedConflictPaths ?? 0;
+    }
+  }
+};
+var WORKTREE_UNAVAILABLE_CODES = /* @__PURE__ */ new Set([
+  "GIT_PATH_NOT_FOUND",
+  "GIT_PATH_NOT_DIRECTORY",
+  "GIT_NOT_A_REPOSITORY",
+  "GIT_BARE_REPOSITORY",
+  "GIT_NOT_A_WORK_TREE",
+  "GIT_HEAD_UNRESOLVED"
+]);
+var TASK_UNAVAILABLE_MESSAGE = "The task worktree is missing or is no longer a healthy Git worktree. Recover it before merging.";
+var TASK_MISMATCH_MESSAGE = "The recorded worktree no longer matches the task's repository. Recover it before merging.";
+var TARGET_UNAVAILABLE_MESSAGE = "The registered target checkout is missing or is no longer a healthy Git worktree. Re-register the repository before merging.";
+var TARGET_MISMATCH_MESSAGE = "The registered target checkout is not on its recorded branch. Switch it back or re-register the repository before merging.";
+var MAX_PATH_DISPLAY_CHARS = 4096;
+function boundedDisplay(text, maxChars) {
+  const clippedInput = text.length > maxChars;
+  const safe = sanitizeApprovalDisplayText(text.slice(0, maxChars));
+  if (safe.length <= maxChars) return { text: safe, clipped: clippedInput };
+  return { text: safe.slice(0, maxChars), clipped: true };
+}
+function boundedPathDisplay(text) {
+  const bounded = boundedDisplay(text, MAX_PATH_DISPLAY_CHARS);
+  if (!bounded.clipped) return bounded.text;
+  return `${bounded.text.slice(0, MAX_PATH_DISPLAY_CHARS - 1)}\u2026`;
+}
+function boundedSubjectDisplay(subject) {
+  const bounded = boundedDisplay(subject, TASK_MERGE_MAX_COMMIT_SUBJECT_CHARS);
+  const text = bounded.clipped ? `${bounded.text.slice(0, TASK_MERGE_MAX_COMMIT_SUBJECT_CHARS - 1)}\u2026` : bounded.text;
+  return text.length === 0 ? "(no subject)" : text;
+}
+function createTaskMergeService(options) {
+  const capture = options.captureWorktreeState ?? captureWorktreeState;
+  const prepare = options.prepareMergeTree ?? prepareMergeTree;
+  const publish = options.publishMerge ?? publishMerge;
+  const sync = options.syncTargetCheckout ?? syncTargetCheckout;
+  const guardAddedPaths = options.assertMergeTargetPathsUnoccupied ?? assertMergeTargetPathsUnoccupied;
+  const ensureGitVersion = options.ensureMergeCapableGit ?? ensureMergeCapableGit;
+  const isAncestor = options.isMergeCommitAncestor ?? isMergeCommitAncestor;
+  const preflightTtlMs = options.preflightTtlMs ?? MERGE_PREFLIGHT_TTL_MS;
+  const now = options.now ?? Date.now;
+  const createId = options.createId ?? randomUUID;
+  const activePhases = /* @__PURE__ */ new Map();
+  const activeRepositories = /* @__PURE__ */ new Set();
+  const pendingPreflights = /* @__PURE__ */ new Map();
+  const inspectedRecoveryHeads = /* @__PURE__ */ new Map();
+  async function resolveTask(taskId) {
+    let task;
+    try {
+      task = await options.getTask(taskId);
+    } catch (error) {
+      throw new TaskMergeOperationError(
+        "merge-failed",
+        "The task could not be resolved from the local workspace.",
+        503,
+        { cause: error }
+      );
+    }
+    if (task === null) {
+      throw new TaskMergeOperationError(
+        "task-not-found",
+        "The selected task no longer exists.",
+        404
+      );
+    }
+    if (task.status !== "ready") {
+      throw new TaskMergeOperationError(
+        "task-not-ready",
+        `Only a ready task can be merged; this task is ${task.status}.`,
+        409
+      );
+    }
+    return task;
+  }
+  async function resolveRepository(repositoryId) {
+    let repository;
+    try {
+      repository = await options.getRepository(repositoryId);
+    } catch (error) {
+      throw new TaskMergeOperationError(
+        "merge-failed",
+        "The repository could not be resolved from the local workspace.",
+        503,
+        { cause: error }
+      );
+    }
+    if (repository === null) {
+      throw new TaskMergeOperationError(
+        "repository-not-found",
+        "The registered repository no longer exists.",
+        404
+      );
+    }
+    return repository;
+  }
+  function claimTaskPhase(taskId, phase) {
+    if (activePhases.has(taskId)) {
+      throw new TaskMergeOperationError(
+        "merge-in-progress",
+        "A merge preflight or execution is already in progress for this task.",
+        409
+      );
+    }
+    activePhases.set(taskId, phase);
+  }
+  function claimRepository(repositoryId) {
+    if (activeRepositories.has(repositoryId)) {
+      throw new TaskMergeOperationError(
+        "merge-in-progress",
+        "Another merge or merge recovery is already in progress for this repository.",
+        409
+      );
+    }
+    activeRepositories.add(repositoryId);
+  }
+  function refuseBusyStates(taskId) {
+    if (options.isValidationRunning(taskId)) {
+      throw new TaskMergeOperationError(
+        "validation-running",
+        "A validation is running for this task. Wait for it to finish before merging.",
+        409
+      );
+    }
+    if (options.isCommitActive(taskId)) {
+      throw new TaskMergeOperationError(
+        "commit-in-progress",
+        "A commit preflight or execution is active for this task. Wait for it to finish before merging.",
+        409
+      );
+    }
+  }
+  async function refuseWorkingAgent(taskId) {
+    let working;
+    try {
+      working = await options.isAgentWorking(taskId);
+    } catch (error) {
+      throw new TaskMergeOperationError(
+        "merge-failed",
+        "The task's runtime state could not be verified. Check the daemon output for details.",
+        503,
+        { cause: error }
+      );
+    }
+    if (working) {
+      throw new TaskMergeOperationError(
+        "agent-working",
+        "The task's agent is still working. Wait for the turn to settle before merging.",
+        409
+      );
+    }
+  }
+  function refusePendingSync(repository) {
+    if (repository.pendingMerge !== void 0) {
+      throw new TaskMergeOperationError(
+        "sync-pending",
+        "An earlier merge requires reconciliation; publication or checkout sync may be incomplete. Reconcile it from the repository card first.",
+        409
+      );
+    }
+  }
+  function mapGitError(error, side) {
+    if (error instanceof GitMergeConflictError) {
+      const retained = error.conflictPaths.slice(0, TASK_MERGE_MAX_CONFLICT_PATHS);
+      return new TaskMergeOperationError("merge-conflicted", error.message, 409, {
+        cause: error,
+        conflictPaths: retained.map(boundedPathDisplay),
+        omittedConflictPaths: error.omittedConflictPaths + (error.conflictPaths.length - retained.length)
+      });
+    }
+    if (isGitServiceError(error)) {
+      if (WORKTREE_UNAVAILABLE_CODES.has(error.code)) {
+        return side === "task" ? new TaskMergeOperationError("task-not-ready", TASK_UNAVAILABLE_MESSAGE, 409, {
+          cause: error
+        }) : new TaskMergeOperationError("target-unavailable", TARGET_UNAVAILABLE_MESSAGE, 409, {
+          cause: error
+        });
+      }
+      switch (error.code) {
+        case "GIT_MERGE_ALREADY_MERGED":
+          return new TaskMergeOperationError(
+            "already-merged",
+            "The task branch is already merged into the target branch. Archive the task instead.",
+            409,
+            { cause: error }
+          );
+        case "GIT_MERGE_UNRELATED_HISTORIES":
+          return new TaskMergeOperationError(
+            "unrelated-histories",
+            "The task and target branches share no history; Webdesk refuses to merge unrelated histories.",
+            409,
+            { cause: error }
+          );
+        case "GIT_MERGE_NOTHING_TO_MERGE":
+          return new TaskMergeOperationError(
+            "nothing-to-merge",
+            "The merge would not change the target branch's content. Archive the task instead.",
+            409,
+            { cause: error }
+          );
+        case "GIT_MERGE_STATE_UNSUPPORTED":
+          return new TaskMergeOperationError(
+            "state-unsupported",
+            "The merge changes a submodule pointer, which Webdesk cannot publish and sync safely yet.",
+            422,
+            { cause: error }
+          );
+        case "GIT_STATE_UNFINGERPRINTABLE":
+        case "GIT_STATE_TOO_LARGE":
+          return new TaskMergeOperationError(
+            "state-unsupported",
+            "A worktree has state that is too large or cannot be fingerprinted safely yet.",
+            422,
+            { cause: error }
+          );
+        case "GIT_MERGE_TARGET_PATH_OCCUPIED": {
+          let occupied = "";
+          if (typeof error.details.path === "string") {
+            const display = boundedDisplay(error.details.path, 160);
+            occupied = ` (${display.clipped ? `${display.text.slice(0, 159)}\u2026` : display.text})`;
+          }
+          return new TaskMergeOperationError(
+            "target-path-occupied",
+            `A file already exists in the target checkout where the merge would create a tracked file${occupied}. It may be ignored by Git; move it away and preflight again.`,
+            409,
+            { cause: error }
+          );
+        }
+        case "GIT_COMMIT_IDENTITY_MISSING":
+          return new TaskMergeOperationError(
+            "identity-missing",
+            "Git identity is not configured for the target checkout. Set user.name and user.email, then try again.",
+            409,
+            { cause: error }
+          );
+        case "GIT_MERGE_VERSION_UNSUPPORTED":
+          return new TaskMergeOperationError(
+            "git-version-unsupported",
+            "Webdesk merges require Git 2.38 or newer for exact checkout-free merge computation. Upgrade Git to merge.",
+            422,
+            { cause: error }
+          );
+        case "GIT_MERGE_WRONG_BASE":
+          return new TaskMergeOperationError(
+            "wrong-base",
+            "The task's recorded base is no longer an ancestor of both the task and target branches. Recreate or repair the task before merging.",
+            409,
+            { cause: error }
+          );
+        case "GIT_MERGE_SIGNING_FAILED":
+          return new TaskMergeOperationError(
+            "signing-failed",
+            "Merge-commit signing failed or timed out; nothing was published. Check your signing setup.",
+            502,
+            { cause: error }
+          );
+        case "GIT_MERGE_REF_CAS_FAILED":
+          return new TaskMergeOperationError(
+            "ref-cas-failed",
+            "The ref transaction was refused (a branch moved, or a repository hook aborted it); nothing was published. Preflight again.",
+            409,
+            { cause: error }
+          );
+        case "GIT_MERGE_SOURCE_MOVED":
+          return new TaskMergeOperationError(
+            "ref-cas-failed",
+            "The task branch changed underneath the approved merge; nothing was published. Preflight again.",
+            409,
+            { cause: error }
+          );
+        case "GIT_MERGE_TARGET_MOVED":
+          return new TaskMergeOperationError(
+            "ref-cas-failed",
+            "The target branch moved before publication; nothing was published. Preflight again.",
+            409,
+            { cause: error }
+          );
+        case "GIT_MERGE_PUBLICATION_UNKNOWN": {
+          const commit = typeof error.details.commit === "string" ? error.details.commit.slice(0, 12) : "unknown";
+          return new TaskMergeOperationError(
+            "publication-unknown",
+            `Git stopped before Webdesk could determine whether merge commit ${commit} was published. Inspect the target branch, then use the repository's merge-sync action.`,
+            502,
+            { cause: error }
+          );
+        }
+        case "GIT_MERGE_TREE_MISMATCH":
+          return new TaskMergeOperationError(
+            "merge-failed",
+            "The created merge does not carry the approved tree; nothing was published. Preflight again.",
+            502,
+            { cause: error }
+          );
+        case "GIT_MERGE_TARGET_MISMATCHED":
+          return new TaskMergeOperationError("target-mismatched", TARGET_MISMATCH_MESSAGE, 409, {
+            cause: error
+          });
+        case "GIT_MERGE_SYNC_REFUSED":
+          return new TaskMergeOperationError(
+            "target-dirty",
+            "Git refused to update the target checkout (local edits, an untracked file, or a held index lock). Nothing was modified; resolve the local state and retry the merge sync.",
+            409,
+            { cause: error }
+          );
+        case "GIT_REPOSITORY_CHANGED_DURING_CAPTURE":
+        case "GIT_STATE_CHANGED_DURING_CAPTURE":
+        case "GIT_STATE_DEADLINE_EXCEEDED":
+          return new TaskMergeOperationError(
+            "merge-failed",
+            "A worktree changed or could not be captured in time. Try again.",
+            409,
+            { cause: error }
+          );
+        default:
+          break;
+      }
+    }
+    return new TaskMergeOperationError(
+      "merge-failed",
+      "Git could not complete the merge operation. Check the daemon output for details.",
+      502,
+      { cause: error }
+    );
+  }
+  async function captureVerifiedTaskState(task, repository) {
+    let canonicalWorktree;
+    try {
+      canonicalWorktree = await realpath(task.worktreePath);
+    } catch (error) {
+      throw new TaskMergeOperationError("task-not-ready", TASK_UNAVAILABLE_MESSAGE, 409, {
+        cause: error
+      });
+    }
+    let state;
+    try {
+      state = await capture({ worktreePath: canonicalWorktree });
+    } catch (error) {
+      throw mapGitError(error, "task");
+    }
+    if (state.worktree.root !== canonicalWorktree || state.worktree.commonDir !== repository.commonDir || state.worktree.branch !== task.branch) {
+      throw new TaskMergeOperationError("task-not-ready", TASK_MISMATCH_MESSAGE, 409);
+    }
+    if (state.statusEntryCount !== 0) {
+      throw new TaskMergeOperationError(
+        "task-dirty",
+        "The task worktree has uncommitted changes. Commit the snapshot first; only committed content can be merged.",
+        409
+      );
+    }
+    return state;
+  }
+  async function captureVerifiedTargetState(task, repository) {
+    let canonicalRoot;
+    try {
+      canonicalRoot = await realpath(repository.rootPath);
+    } catch (error) {
+      throw new TaskMergeOperationError("target-unavailable", TARGET_UNAVAILABLE_MESSAGE, 409, {
+        cause: error
+      });
+    }
+    if (canonicalRoot !== repository.rootPath) {
+      throw new TaskMergeOperationError("target-mismatched", TARGET_MISMATCH_MESSAGE, 409);
+    }
+    let state;
+    try {
+      state = await capture({ worktreePath: canonicalRoot });
+    } catch (error) {
+      throw mapGitError(error, "target");
+    }
+    if (state.worktree.root !== canonicalRoot || state.worktree.commonDir !== repository.commonDir) {
+      throw new TaskMergeOperationError("target-mismatched", TARGET_MISMATCH_MESSAGE, 409);
+    }
+    if (state.worktree.branch === null || repository.branch === null || state.worktree.branch !== repository.branch) {
+      throw new TaskMergeOperationError("target-mismatched", TARGET_MISMATCH_MESSAGE, 409);
+    }
+    if (state.worktree.branch === task.branch) {
+      throw new TaskMergeOperationError(
+        "target-mismatched",
+        "The registered target checkout is on the task's own branch; a task can never merge into itself.",
+        409
+      );
+    }
+    if (state.statusEntryCount !== 0) {
+      throw new TaskMergeOperationError(
+        "target-dirty",
+        "The registered target checkout has uncommitted changes. Commit or stash them before merging.",
+        409
+      );
+    }
+    return { canonicalRoot, state };
+  }
+  function validationVerdict(task, taskFingerprint) {
+    const result = task.validation;
+    if (result === void 0) return "none";
+    if (result.stateFingerprint !== taskFingerprint) return "stale";
+    return result.outcome === "passed" ? "current-passed" : "current-failed";
+  }
+  function defaultMergeMessage(taskBranch, targetBranch) {
+    return `Merge branch '${taskBranch}' into ${targetBranch}`;
+  }
+  function assertApprovalSafeBranch(branch) {
+    if ([...branch].some(
+      (character) => /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}\p{Default_Ignorable_Code_Point}]/u.test(character) || new RegExp("\\p{Zs}", "u").test(character) && character !== " " || /[\u115F\u1160\u2800\u3164\uFFA0]/u.test(character)
+    )) {
+      throw new TaskMergeOperationError(
+        "state-unsupported",
+        "A task or target branch contains invisible formatting characters and cannot be shown safely for merge approval. Rename the branch before merging.",
+        422
+      );
+    }
+  }
+  function preflightPayload(taskId, pending, prepared, createdAtMs) {
+    let remainingChars = TASK_MERGE_MAX_TOTAL_DIFF_CHARS;
+    let totalDiffTruncated = prepared.totalDiffTruncated;
+    const files = prepared.files.map((file) => {
+      let diff = null;
+      let diffTruncated = file.diffTruncated;
+      let diffOmittedReason = file.diffOmittedReason;
+      if (file.diff !== null) {
+        if (remainingChars <= 0) {
+          diffOmittedReason = "total-budget";
+          diffTruncated = false;
+          totalDiffTruncated = true;
+        } else {
+          const perFileLimit = Math.min(TASK_MERGE_MAX_FILE_DIFF_CHARS, remainingChars);
+          const bounded = boundedDisplay(file.diff, perFileLimit);
+          diff = bounded.text;
+          if (bounded.clipped) {
+            diffTruncated = true;
+            if (perFileLimit < TASK_MERGE_MAX_FILE_DIFF_CHARS) totalDiffTruncated = true;
+          }
+          remainingChars -= diff.length;
+        }
+      }
+      return {
+        entryId: file.entryId,
+        path: boundedPathDisplay(file.path),
+        previousPath: file.previousPath === null ? null : boundedPathDisplay(file.previousPath),
+        kind: file.kind,
+        binary: file.binary,
+        diff,
+        diffTruncated,
+        diffOmittedReason
+      };
+    });
+    return taskMergePreflightSchema.parse({
+      protocol: PROTOCOL_VERSION,
+      type: "task-merge-preflight",
+      taskId,
+      preflightId: pending.preflightId,
+      mode: pending.mode,
+      taskBranch: pending.taskBranch,
+      targetBranch: pending.targetBranch,
+      taskHead: pending.taskHead,
+      targetHead: pending.targetHead,
+      mergedTree: pending.mergedTree,
+      mergeMessage: pending.mergeMessage,
+      files,
+      totalFiles: prepared.totalFiles,
+      omittedFiles: prepared.omittedFiles,
+      totalDiffTruncated,
+      commitCount: prepared.commitCount,
+      commitSubjects: prepared.commitSubjects.slice(0, TASK_MERGE_MAX_COMMIT_SUBJECTS).map(boundedSubjectDisplay),
+      validationVerdict: pending.validationVerdict,
+      validationCoversResult: pending.validationCoversResult,
+      acknowledgementRequired: pending.acknowledgementRequired,
+      hooksBypassed: true,
+      createdAtMs,
+      expiresAtMs: pending.expiresAtMs
+    });
+  }
+  async function preflight(taskId, request) {
+    claimTaskPhase(taskId, "preflight");
+    pendingPreflights.delete(taskId);
+    let repositoryClaimed = null;
+    try {
+      if (options.isArchiveActive?.(taskId) === true) {
+        throw new TaskMergeOperationError(
+          "archive-in-progress",
+          "This task is being archived or restored. Wait for that operation to finish.",
+          409
+        );
+      }
+      refuseBusyStates(taskId);
+      const task = await resolveTask(taskId);
+      claimRepository(task.repositoryId);
+      repositoryClaimed = task.repositoryId;
+      const repository = await resolveRepository(task.repositoryId);
+      refusePendingSync(repository);
+      await refuseWorkingAgent(taskId);
+      const taskBefore = await captureVerifiedTaskState(task, repository);
+      const { canonicalRoot, state: targetBefore } = await captureVerifiedTargetState(
+        task,
+        repository
+      );
+      assertApprovalSafeBranch(task.branch);
+      assertApprovalSafeBranch(targetBefore.worktree.branch);
+      try {
+        await ensureGitVersion(void 0, canonicalRoot);
+      } catch (error) {
+        throw mapGitError(error, "target");
+      }
+      let prepared;
+      try {
+        prepared = await prepare({
+          targetRootPath: canonicalRoot,
+          targetHead: targetBefore.worktree.headCommit,
+          taskHead: taskBefore.worktree.headCommit,
+          baseCommit: task.baseCommit
+        });
+      } catch (error) {
+        throw mapGitError(error, "target");
+      }
+      try {
+        await guardAddedPaths(canonicalRoot, prepared.addedPaths);
+      } catch (error) {
+        throw mapGitError(error, "target");
+      }
+      const verdict = validationVerdict(task, taskBefore.stateFingerprint);
+      const validationCoversResult = prepared.mode === "fast-forward";
+      const mergeMessage = prepared.mode === "fast-forward" ? null : request.message ?? defaultMergeMessage(task.branch, targetBefore.worktree.branch);
+      const taskAfter = await captureVerifiedTaskState(task, repository);
+      const { state: targetAfter } = await captureVerifiedTargetState(task, repository);
+      if (taskAfter.stateFingerprint !== taskBefore.stateFingerprint || targetAfter.stateFingerprint !== targetBefore.stateFingerprint) {
+        throw new TaskMergeOperationError(
+          "merge-failed",
+          "A worktree changed while the merge was being prepared. Review the new state and try again.",
+          409
+        );
+      }
+      const createdAtMs = now();
+      const pending = {
+        preflightId: createId(),
+        repositoryId: repository.id,
+        mode: prepared.mode,
+        taskBranch: task.branch,
+        targetBranch: targetBefore.worktree.branch,
+        taskHead: taskBefore.worktree.headCommit,
+        targetHead: targetBefore.worktree.headCommit,
+        mergedTree: prepared.mergedTree,
+        mergeMessage,
+        addedPaths: prepared.addedPaths,
+        taskFingerprint: taskBefore.stateFingerprint,
+        targetFingerprint: targetBefore.stateFingerprint,
+        validationVerdict: verdict,
+        validationCoversResult,
+        acknowledgementRequired: verdict !== "current-passed" || prepared.mode === "merge-commit",
+        expiresAtMs: createdAtMs + preflightTtlMs
+      };
+      const payload = preflightPayload(taskId, pending, prepared, createdAtMs);
+      pendingPreflights.set(taskId, pending);
+      return payload;
+    } finally {
+      activePhases.delete(taskId);
+      if (repositoryClaimed !== null) activeRepositories.delete(repositoryClaimed);
+    }
+  }
+  async function execute(taskId, request) {
+    claimTaskPhase(taskId, "execute");
+    let repositoryClaimed = null;
+    try {
+      if (options.isArchiveActive?.(taskId) === true) {
+        throw new TaskMergeOperationError(
+          "archive-in-progress",
+          "This task is being archived or restored. Wait for that operation to finish.",
+          409
+        );
+      }
+      refuseBusyStates(taskId);
+      const task = await resolveTask(taskId);
+      claimRepository(task.repositoryId);
+      repositoryClaimed = task.repositoryId;
+      const repository = await resolveRepository(task.repositoryId);
+      refusePendingSync(repository);
+      await refuseWorkingAgent(taskId);
+      const pending = pendingPreflights.get(taskId);
+      if (pending === void 0 || pending.preflightId !== request.preflightId || pending.repositoryId !== repository.id) {
+        throw new TaskMergeOperationError(
+          "preflight-not-found",
+          "This merge preflight is no longer valid. Review the current state and preflight again.",
+          409
+        );
+      }
+      if (now() >= pending.expiresAtMs) {
+        pendingPreflights.delete(taskId);
+        throw new TaskMergeOperationError(
+          "preflight-not-found",
+          "This merge preflight expired. Review the current state and preflight again.",
+          409
+        );
+      }
+      const currentVerdict = validationVerdict(task, pending.taskFingerprint);
+      if (currentVerdict !== pending.validationVerdict) {
+        pendingPreflights.delete(taskId);
+        throw new TaskMergeOperationError(
+          "preflight-outdated",
+          "The validation verdict changed after this preflight. Review the current result and preflight again.",
+          409
+        );
+      }
+      if (pending.acknowledgementRequired && request.acknowledgeValidation !== true) {
+        throw new TaskMergeOperationError(
+          "acknowledgement-required",
+          "Acknowledge the validation coverage explicitly before merging.",
+          409
+        );
+      }
+      let canonicalRoot;
+      try {
+        const taskCurrent = await captureVerifiedTaskState(task, repository);
+        const target = await captureVerifiedTargetState(task, repository);
+        canonicalRoot = target.canonicalRoot;
+        if (taskCurrent.stateFingerprint !== pending.taskFingerprint || target.state.stateFingerprint !== pending.targetFingerprint) {
+          throw new TaskMergeOperationError(
+            "preflight-outdated",
+            "A worktree changed after this preflight was approved. Review the new state and preflight again.",
+            409
+          );
+        }
+        try {
+          await guardAddedPaths(canonicalRoot, pending.addedPaths);
+        } catch (error) {
+          throw mapGitError(error, "target");
+        }
+      } catch (error) {
+        pendingPreflights.delete(taskId);
+        throw error;
+      }
+      pendingPreflights.delete(taskId);
+      let publication;
+      try {
+        publication = await publish({
+          targetRootPath: canonicalRoot,
+          mode: pending.mode,
+          taskBranch: pending.taskBranch,
+          targetBranch: pending.targetBranch,
+          taskHead: pending.taskHead,
+          targetHead: pending.targetHead,
+          mergedTree: pending.mergedTree,
+          message: pending.mergeMessage,
+          reflogReason: `pita-merge: task ${taskId} preflight ${pending.preflightId}`,
+          // The durable intent is written after the publishable commit exists
+          // and immediately before the ref transaction.
+          recordIntent: (newCommit) => options.recordPendingMerge(repository.id, {
+            taskId,
+            preflightId: pending.preflightId,
+            mode: pending.mode,
+            targetBranch: pending.targetBranch,
+            previousTargetHead: pending.targetHead,
+            newTargetHead: newCommit,
+            recordedAtMs: now()
+          })
+        });
+      } catch (error) {
+        if (isGitServiceError(error, "GIT_MERGE_PUBLICATION_UNKNOWN")) {
+          throw mapGitError(error, "target");
+        }
+        await options.clearPendingMerge(repository.id, pending.preflightId).catch(() => void 0);
+        if (error instanceof TaskMergeOperationError) throw error;
+        throw mapGitError(error, "target");
+      }
+      let targetSynced = false;
+      let targetHeadVerified = false;
+      try {
+        const facts = await sync({
+          targetRootPath: canonicalRoot,
+          targetBranch: pending.targetBranch,
+          previousTargetHead: pending.targetHead,
+          newTargetHead: publication.newCommit,
+          addedPaths: pending.addedPaths
+        });
+        targetHeadVerified = facts.headVerified;
+        targetSynced = facts.headVerified && facts.statusClean;
+      } catch (error) {
+        targetSynced = false;
+        targetHeadVerified = false;
+      }
+      if (targetSynced) {
+        await options.clearPendingMerge(repository.id, pending.preflightId, publication.newCommit).catch(() => void 0);
+      }
+      return taskMergeResultSchema.parse({
+        protocol: PROTOCOL_VERSION,
+        type: "task-merge-result",
+        taskId,
+        mode: publication.mode,
+        taskBranch: pending.taskBranch,
+        targetBranch: pending.targetBranch,
+        taskHead: publication.taskHead,
+        previousTargetHead: publication.previousTargetHead,
+        newTargetHead: publication.newCommit,
+        mergeCommit: publication.mode === "merge-commit" ? publication.newCommit : null,
+        treeOid: publication.treeOid,
+        signed: publication.signed,
+        targetSynced,
+        targetHeadVerified,
+        capturedAtMs: now()
+      });
+    } finally {
+      activePhases.delete(taskId);
+      if (repositoryClaimed !== null) activeRepositories.delete(repositoryClaimed);
+    }
+  }
+  async function syncRepository(repositoryId, request = {
+    acknowledgeRecoveryDismissal: false
+  }) {
+    claimRepository(repositoryId);
+    try {
+      let result2 = function(outcome, currentTargetHead) {
+        return repositoryMergeSyncResultSchema.parse({
+          protocol: PROTOCOL_VERSION,
+          type: "repository-merge-sync-result",
+          repositoryId,
+          outcome,
+          taskId: pending.taskId,
+          mode: pending.mode,
+          targetBranch: pending.targetBranch,
+          previousTargetHead: pending.previousTargetHead,
+          newTargetHead: pending.newTargetHead,
+          currentTargetHead,
+          pendingMergeCleared: !["publication-unconfirmed", "target-moved"].includes(outcome),
+          capturedAtMs: now()
+        });
+      };
+      var result = result2;
+      const repository = await resolveRepository(repositoryId);
+      const pending = repository.pendingMerge;
+      if (pending === void 0) {
+        inspectedRecoveryHeads.delete(repositoryId);
+        throw new TaskMergeOperationError(
+          "sync-not-pending",
+          "No interrupted merge is pending for this repository.",
+          409
+        );
+      }
+      if (options.isArchiveActive?.(pending.taskId) === true) {
+        throw new TaskMergeOperationError(
+          "archive-in-progress",
+          "This task is being archived or restored. Wait for that operation to finish before reconciling its merge.",
+          409
+        );
+      }
+      let canonicalRoot;
+      try {
+        canonicalRoot = await realpath(repository.rootPath);
+      } catch (error) {
+        throw new TaskMergeOperationError("target-unavailable", TARGET_UNAVAILABLE_MESSAGE, 409, {
+          cause: error
+        });
+      }
+      if (canonicalRoot !== repository.rootPath) {
+        throw new TaskMergeOperationError("target-mismatched", TARGET_MISMATCH_MESSAGE, 409);
+      }
+      let state;
+      try {
+        state = await capture({ worktreePath: canonicalRoot });
+      } catch (error) {
+        throw mapGitError(error, "target");
+      }
+      if (state.worktree.root !== canonicalRoot || state.worktree.commonDir !== repository.commonDir) {
+        throw new TaskMergeOperationError("target-mismatched", TARGET_MISMATCH_MESSAGE, 409);
+      }
+      if (state.worktree.branch !== pending.targetBranch) {
+        throw new TaskMergeOperationError(
+          "target-mismatched",
+          "The target checkout was switched away from the branch of the interrupted merge. Switch it back, then retry the merge sync.",
+          409
+        );
+      }
+      const currentHead = state.worktree.headCommit;
+      if (currentHead === pending.previousTargetHead) {
+        const inspected = inspectedRecoveryHeads.get(repositoryId);
+        if (request.acknowledgeRecoveryDismissal === true && inspected?.preflightId === pending.preflightId && inspected.currentTargetHead === currentHead) {
+          await clearPending(repositoryId, pending.preflightId, pending.previousTargetHead);
+          inspectedRecoveryHeads.delete(repositoryId);
+          return result2("publication-unconfirmed-cleared", currentHead);
+        }
+        inspectedRecoveryHeads.set(repositoryId, {
+          preflightId: pending.preflightId,
+          currentTargetHead: currentHead
+        });
+        return result2("publication-unconfirmed", currentHead);
+      }
+      if (currentHead !== pending.newTargetHead) {
+        if (state.statusEntryCount !== 0) {
+          throw new TaskMergeOperationError(
+            "target-dirty",
+            "The target branch moved and its checkout is not clean. Inspect and settle the checkout before reconciling the merge.",
+            409
+          );
+        }
+        let integrated;
+        try {
+          integrated = await isAncestor(canonicalRoot, pending.newTargetHead, currentHead);
+        } catch (error) {
+          throw mapGitError(error, "target");
+        }
+        if (integrated) {
+          await clearPending(repositoryId, pending.preflightId, currentHead);
+          inspectedRecoveryHeads.delete(repositoryId);
+          return result2("advanced-integrated", currentHead);
+        }
+        const inspected = inspectedRecoveryHeads.get(repositoryId);
+        if (request.acknowledgeRecoveryDismissal === true && inspected?.preflightId === pending.preflightId && inspected.currentTargetHead === currentHead) {
+          await clearPending(repositoryId, pending.preflightId, currentHead);
+          inspectedRecoveryHeads.delete(repositoryId);
+          return result2("target-moved-cleared", currentHead);
+        }
+        inspectedRecoveryHeads.set(repositoryId, {
+          preflightId: pending.preflightId,
+          currentTargetHead: currentHead
+        });
+        return result2("target-moved", currentHead);
+      }
+      if (state.statusEntryCount === 0) {
+        await clearPending(repositoryId, pending.preflightId, pending.newTargetHead);
+        inspectedRecoveryHeads.delete(repositoryId);
+        return result2("synced", null);
+      }
+      let facts;
+      try {
+        facts = await sync({
+          targetRootPath: canonicalRoot,
+          targetBranch: pending.targetBranch,
+          previousTargetHead: pending.previousTargetHead,
+          newTargetHead: pending.newTargetHead
+        });
+      } catch (error) {
+        throw mapGitError(error, "target");
+      }
+      if (!facts.statusClean || !facts.headVerified) {
+        throw new TaskMergeOperationError(
+          facts.headVerified ? "target-dirty" : "target-mismatched",
+          facts.headVerified ? "Git updated the target checkout, but it is not clean. Resolve the remaining local state and retry merge sync." : "Git updated the target checkout, but Webdesk could not verify the published target head. Inspect the repository and retry merge sync.",
+          409
+        );
+      }
+      await clearPending(repositoryId, pending.preflightId, pending.newTargetHead);
+      inspectedRecoveryHeads.delete(repositoryId);
+      return result2("synced", null);
+    } finally {
+      activeRepositories.delete(repositoryId);
+    }
+  }
+  async function clearPending(repositoryId, preflightId, resolvedHead) {
+    try {
+      await options.clearPendingMerge(repositoryId, preflightId, resolvedHead);
+    } catch (error) {
+      throw new TaskMergeOperationError(
+        "merge-failed",
+        "The merge sync completed but the pending record could not be cleared. Retry the merge sync.",
+        503,
+        { cause: error }
+      );
+    }
+  }
+  return {
+    preflight,
+    execute,
+    syncRepository,
+    isBusy: (taskId) => activePhases.has(taskId),
+    isRepositoryBusy: (repositoryId) => activeRepositories.has(repositoryId),
+    invalidate(taskId) {
+      pendingPreflights.delete(taskId);
+    }
+  };
+}
+export {
+  MERGE_PREFLIGHT_TTL_MS,
+  TaskMergeOperationError,
+  createTaskMergeService
+};