@bevel-software/platform-core-backend 0.30.0 → 0.32.0

package/src/modules/workflow/git/git.service.ts

@@ -8,7 +8,11 @@ import type {
   BranchInfo,
   ChangedPathPair,
   CommitAttribution,
+  ConflictedFile,
   IGitService,
+  MergeIntoBranchOutcome,
+  MergeResolution,
+  ReservedPushOps,
   RemoteSyncPullResult,
   PrFileStatus,
   PullRequestFile,
@@ -21,11 +25,14 @@ import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { WorkflowHooks, CommitValidationContext } from '../workflow-hooks.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
-import { WorkspaceMutex } from '../../kb-fs/mutex.js';
+import { WorkspaceIdMutex, type WorkspaceMutex } from '../../kb-fs/index.js';
 import { isAbsence } from '../../../shared/fs.contract.js';
 import { assertInsideRepo } from '../../kb-fs/repo-path.js';
 import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../../kb-fs/clone-config.js';
 import { readRefSha } from '../../kb-fs/index.js';
+import { utf8Text } from '../../../shared/utf8-text.js';
+import { lstatOrNull } from '../../../shared/rename-no-replace.js';
+import { linkedAncestor } from '../../../shared/no-link-below.js';
 import {
   assertValidBranchName,
   assertValidRelativePath,
@@ -48,7 +55,6 @@ import {
 import {
   GitRunError,
   assertOneSpecPerLine,
-  isGitTimeout,
   redactGitToken,
   type GitCredentials,
   type GitRunOptions,
@@ -325,7 +331,10 @@ export class GitService implements IGitService {
      */
     private readonly hooks: WorkflowHooks,
     private readonly kb: KbContext,
-    private readonly mutex: WorkspaceMutex = new WorkspaceMutex(),
+    // Keyed by the CANONICAL workspace id: a route's Express-decoded `:id`
+    // (`alice/feature`) and a tool's `alice%2Ffeature` name one clone, and
+    // must take one reservation.
+    private readonly mutex: WorkspaceMutex = new WorkspaceIdMutex(),
     private readonly accessControl: IAccessControl | null = null,
     /**
      * How git is actually run — see `shared/git.contract.ts`. The composition
@@ -963,16 +972,18 @@ export class GitService implements IGitService {
   async isAncestor(workspaceId: string, ancestor: string, descendant: string): Promise<boolean> {
     const sha = /^[0-9a-f]{4,64}$/i;
     if (!sha.test(ancestor) || !sha.test(descendant)) throw new Error('isAncestor takes commit ids');
-    return this.mutex.run(workspaceId, async () => {
-      const cwd = await this.repoDir(workspaceId);
-      try {
-        await this.git(cwd, ['merge-base', '--is-ancestor', ancestor, descendant]);
-        return true;
-      } catch (err) {
-        if (err instanceof GitRunError && !err.timedOut && err.exitCode === 1) return false;
-        throw err;
-      }
-    });
+    return this.mutex.run(workspaceId, async () => this.isAncestorUnlocked(await this.repoDir(workspaceId), ancestor, descendant));
+  }
+
+  /** `isAncestor`'s body, for a caller that already holds the workspace's reservation. */
+  private async isAncestorUnlocked(cwd: string, ancestor: string, descendant: string): Promise<boolean> {
+    try {
+      await this.git(cwd, ['merge-base', '--is-ancestor', ancestor, descendant]);
+      return true;
+    } catch (err) {
+      if (err instanceof GitRunError && !err.timedOut && err.exitCode === 1) return false;
+      throw err;
+    }
   }
 
   /**
@@ -1475,8 +1486,19 @@ export class GitService implements IGitService {
       // stamped after the push instead, as one short write made as the
       // repository's administrator (see `git`).
       await this.git(cwd, ['push', 'origin', branch]);
-      await this.git(cwd, ['config', '--replace-all', `branch.${branch}.remote`, 'origin']);
-      await this.git(cwd, ['config', '--replace-all', `branch.${branch}.merge`, `refs/heads/${branch}`]);
+      // The stamp is maintenance after a push that LANDED: a config the
+      // repository's administrator could not write just now (a lock held by
+      // another worktree's stamp) does not make the branch unpublished, and
+      // reporting it as a refused push would hand a published commit to
+      // recovery. Logged; the next push stamps it.
+      try {
+        await this.git(cwd, ['config', '--replace-all', `branch.${branch}.remote`, 'origin']);
+        await this.git(cwd, ['config', '--replace-all', `branch.${branch}.merge`, `refs/heads/${branch}`]);
+      } catch (err) {
+        log.warn(`"${branch}" is pushed; its tracking config could not be stamped after the push:`, {
+          detail: redactGitToken(err instanceof Error ? err.message : String(err), this.credentials.token()),
+        });
+      }
     }
   }
 
@@ -1521,73 +1543,438 @@ export class GitService implements IGitService {
     assertValidBranchName(sourceBranch);
     assertValidBranchName(targetBranch);
     assertValidAuthor(user);
+    // The one merge protocol (`mergeRefIntoCheckout`), asked for what the
+    // auto-merge needs: no resolutions, the conflicted paths alone, no
+    // publish. Under the per-branch workspace model the workspace IS the
+    // source branch, so the checked-out guard is not asked for; nor is the
+    // dirty-tree one — save=share keeps the tree clean before an auto-merge,
+    // and a dirty one is an upstream bug `statusInternal` already logs.
     return this.mutex.run(workspaceId, async () => {
-      const cwd = await this.repoDir(workspaceId);
-      // Under the per-branch workspace model, the workspace's identity is
-      // the source branch — the legacy "current branch must equal sourceBranch"
-      // guard was an artifact of the single-workspace-many-branches model and
-      // is no longer needed. The legacy dirty-tree refusal is also gone:
-      // save=share guarantees the tree is clean before any auto-merge runs,
-      // and the only way it could be dirty now is an upstream bug, which
-      // `statusInternal` already logs server-side.
-      // Refresh the target ref so we merge against the latest published
-      // state. Failing the fetch here is non-recoverable for this
-      // operation: a stale `origin/<target>` would let us silently miss
-      // conflicts the next push would surface, and the whole point of
-      // `mergeFromOrigin` is to surface those conflicts now. Propagate
-      // the error so the auto-merge aborts cleanly instead of producing
-      // a merge based on a stale ref. Explicit destination refspec for the
-      // same reason as `mergeChangeRequest`: a bare `fetch origin <branch>`
-      // updates `origin/<branch>` only as far as `remote.origin.fetch` allows,
-      // and a drifted refspec would hand this merge the stale ref it is
-      // explicitly trying to avoid.
-      await this.git(cwd, [
-        'fetch', '--no-write-fetch-head', 'origin',
-        `+refs/heads/${targetBranch}:refs/remotes/origin/${targetBranch}`,
-      ]);
+      const outcome = await this.mergeRefIntoCheckout(workspaceId, await this.repoDir(workspaceId), sourceBranch, targetBranch, user, {
+        subject: `Refresh ${sourceBranch} from ${targetBranch}`,
+        body:
+          `Workflow auto-merge: incorporates the latest ${targetBranch} into ${sourceBranch} ` +
+          `as part of opening or refreshing a change request. ` +
+          `Conflicts (if any) would have been surfaced to the caller before this commit landed; ` +
+          `none were detected, so the merge applied cleanly.`,
+        resolutions: new Map(),
+        guardCheckout: false,
+        describeConflicts: false,
+      });
+      if (outcome.kind === 'conflicts') return { kind: 'conflicts' as const, paths: outcome.unresolved };
+      return { kind: 'clean' as const, alreadyUpToDate: outcome.kind === 'nothing-to-merge' };
+    });
+  }
+
+  /** The most of one side of a conflicted file that travels in an answer; past it the side is read by the caller instead. */
+  private static readonly CONFLICT_SIDE_MAX_CHARS = 200_000;
+
+  async mergeIntoBranch(
+    workspaceId: string,
+    branch: string,
+    fromBranch: string,
+    user: AuthUser,
+    opts: {
+      subject: string;
+      body: string;
+      resolutions?: MergeResolution[];
+      publish?: (ops: ReservedPushOps) => Promise<void>;
+      authorizeResolutions?: (merge: { ours: string; theirs: string }) => Promise<void>;
+    },
+  ): Promise<MergeIntoBranchOutcome> {
+    assertValidBranchName(branch);
+    assertValidBranchName(fromBranch);
+    assertValidAuthor(user);
+    if (/\n\s*\n/.test(opts.subject)) {
+      throw new WorkflowValidationError('merge commit subject must be a single paragraph');
+    }
+    // Every resolution names a repository path; which of them are conflicted
+    // is only known inside the merge, where they are matched exactly.
+    const resolutions = new Map<string, MergeResolution>();
+    // A resolution writes a file on the branch: it is somebody's to
+    // authorize, and a caller that brings none writes nothing (closed).
+    if ((opts.resolutions?.length ?? 0) > 0 && typeof opts.authorizeResolutions !== 'function') {
+      throw new Error('mergeIntoBranch: resolutions need an `authorizeResolutions` to be asked inside the merge');
+    }
+    for (const r of opts.resolutions ?? []) {
+      assertValidRelativePath(r.path);
+      const p = this.stripRepoPrefix(r.path);
+      const ways = [r.content !== undefined, r.choose !== undefined].filter(Boolean).length;
+      if (ways !== 1) {
+        throw new WorkflowValidationError(`resolution for "${p}": give either \`content\` or \`choose\`, not ${ways === 0 ? 'neither' : 'both'}`);
+      }
+      if (r.choose !== undefined && !['ours', 'theirs', 'delete'].includes(r.choose)) {
+        throw new WorkflowValidationError(`resolution for "${p}": \`choose\` is \`ours\`, \`theirs\` or \`delete\``);
+      }
+      if (resolutions.has(p)) throw new WorkflowValidationError(`"${p}" is resolved twice`);
+      resolutions.set(p, { ...r, path: p });
+    }
+    return this.mutex.run(workspaceId, async () =>
+      this.mergeRefIntoCheckout(workspaceId, await this.repoDir(workspaceId), branch, fromBranch, user, {
+        subject: opts.subject,
+        body: opts.body,
+        resolutions,
+        guardCheckout: true,
+        describeConflicts: true,
+        publish: opts.publish,
+        authorizeResolutions: opts.authorizeResolutions,
+      }),
+    );
+  }
+
+  /**
+   * THE merge of `origin/<fromBranch>` into the checkout at `cwd` — what
+   * `mergeFromOrigin` (the change-request auto-merge) and `mergeIntoBranch`
+   * (the agent's update) both run. The caller holds the workspace's
+   * reservation. `--no-commit --no-ff`, so the commit is authored as `user`
+   * and the record of what was merged is never fast-forwarded past.
+   *
+   * The checkout is never left mid-merge, whatever happens: every exit after
+   * `git merge` has started — a conflict described, a resolution refused or
+   * failed, a commit or a publish that failed — runs `merge --abort` first,
+   * and an abort that itself fails is reported, never swallowed, because a
+   * checkout stuck in a merge is what breaks the commit worker and every
+   * later operation on the branch.
+   *
+   * `publish` runs over the merge commit inside this same reservation, so no
+   * save or sync can land between the commit and its push; it is the
+   * caller's push policy (the workflow's `pushWithRecovery`: one replay onto
+   * the moved branch with the merge kept, `--rebase-merges`, then the typed
+   * hand-off) over this checkout's own unlocked moves.
+   */
+  private async mergeRefIntoCheckout(
+    workspaceId: string,
+    cwd: string,
+    branch: string,
+    fromBranch: string,
+    user: AuthUser,
+    opts: {
+      subject: string;
+      body: string;
+      resolutions: Map<string, MergeResolution>;
+      /** Refuse a checkout that is not on `branch`, or holds uncommitted edits. */
+      guardCheckout: boolean;
+      /** Carry every conflicted file's sides in the answer; else the paths alone. */
+      describeConflicts: boolean;
+      /** Run over the merge commit inside the reservation, with the pushes it may make. */
+      publish?: (ops: ReservedPushOps) => Promise<void>;
+      /**
+       * Decide whether the caller may settle the paths the resolutions name,
+       * given the two commits the merge is actually between — asked INSIDE
+       * the reservation, after the fetch and BEFORE the merge touches the
+       * checkout: the source rules read are those of the commit being
+       * merged, not of a tracking ref from before it moved, and the
+       * checkout's are the branch's own commit (`ours`), clean — never a
+       * tree mid-merge, where a rule file's conflict markers or merged
+       * content would decide. Throwing refuses before anything is written.
+       */
+      authorizeResolutions?: (merge: { ours: string; theirs: string }) => Promise<void>;
+    },
+  ): Promise<MergeIntoBranchOutcome> {
+    const theirsRef = `refs/remotes/origin/${fromBranch}`;
+    if (opts.guardCheckout) {
+      const checkedOut = await this.currentBranch(cwd);
+      if (checkedOut !== branch) {
+        throw new WorkflowValidationError(`the workspace is on "${checkedOut}", not on "${branch}"`);
+      }
+      // A merge rewrites tracked files. Edits still on their way to a commit
+      // (a save the worker has not landed) would be swept into the merge
+      // commit under this user's name, or lost under the merge's version.
+      const { stdout: dirty } = await this.git(cwd, ['status', '--porcelain=v1', '-z']);
+      if (parsePorcelainZ(dirty).length > 0) {
+        throw new WorkflowDomainError(
+          `"${branch}" has edits that are not committed yet. Try again once they are saved.`,
+          409,
+          { kind: 'branch-busy', branch },
+        );
+      }
+    }
+    // `git merge`/`git commit` need a committer identity (see `mergeChangeRequest`).
+    await this.git(cwd, ['config', 'user.name', BOT_NAME]);
+    await this.git(cwd, ['config', 'user.email', BOT_EMAIL]);
+    // The published tip, explicitly: a bare `fetch origin <branch>` updates
+    // the tracking ref only as far as `remote.origin.fetch` allows, and a
+    // stale ref would hide exactly the conflicts this merge exists to surface.
+    await this.git(cwd, ['fetch', '--no-write-fetch-head', 'origin', `+refs/heads/${fromBranch}:${theirsRef}`]);
+    const ours = (await this.git(cwd, ['rev-parse', 'HEAD'])).stdout.trim();
+    // The COMMIT the merge is of, from here on — never the ref it was read
+    // from: the repository's refs are shared by every worktree and moved by
+    // every fetch (the timer's sync, another workspace's merge), so what is
+    // authorized, merged, described and recorded is this one sha.
+    const theirs = (await this.git(cwd, ['rev-parse', theirsRef])).stdout.trim();
+    // Resolutions are authorized here, on the clean checkout at `ours` with
+    // `theirs` fetched, before the merge changes a single file. Which of
+    // them are conflicted is matched after the merge; a stray one is refused.
+    if (opts.resolutions.size > 0 && opts.authorizeResolutions) await opts.authorizeResolutions({ ours, theirs });
+    // A merge with nothing to settle leaves no resolution a place to go: one
+    // supplied anyway names a path that is not conflicted, and is refused as
+    // such rather than dropped on the floor behind a published merge.
+    const noConflictsFor = (): WorkflowValidationError =>
+      new WorkflowValidationError(
+        `nothing conflicted, so nothing is resolved here: ${[...opts.resolutions.keys()].join(', ')}.`,
+        { kind: 'not-conflicted', paths: [...opts.resolutions.keys()] },
+      );
+    // Nothing to merge is a question of ANCESTRY, not of content: a source
+    // the branch already reaches is merged; one it does not reach is merged
+    // in even when the two trees are identical, so the branch records that
+    // it holds the source's history and stops reading as behind it.
+    if (await this.isAncestorUnlocked(cwd, theirs, ours)) {
+      if (opts.resolutions.size > 0) throw noConflictsFor();
+      return { kind: 'nothing-to-merge', sha: ours, from: fromBranch };
+    }
 
-      // `--no-commit --no-ff` so we control the commit (need to override
-      // author) and so we never sneak a fast-forward past the merge-commit
-      // explanation gate.
-      let mergeStdout = '';
+    try {
+      await this.git(cwd, ['merge', '--no-commit', '--no-ff', theirs]);
+    } catch (err) {
+      // A conflict, or another failure: either way the merge may be on disk
+      // from here on, and every exit below undoes it.
+      return this.settleMerge(cwd, async () => {
+        const conflicted = await this.conflictedPaths(cwd);
+        if (conflicted.length === 0) {
+          throw new Error(
+            `git merge failed without detectable conflicts: ${redactGitToken(
+              err instanceof Error ? err.message : String(err),
+              this.credentials.token(),
+            )}`,
+          );
+        }
+        const stray = [...opts.resolutions.keys()].filter((p) => !conflicted.includes(p));
+        if (stray.length > 0) {
+          // Only a conflicted path is written by a resolution: anything else
+          // is an ordinary write, which goes through the file tools and their
+          // locks. Refused whole, before any resolution is applied — naming
+          // the caller's own paths only, never the conflicted set (which the
+          // caller is told of, cut to what they may read, by the answer).
+          throw new WorkflowValidationError(
+            `not conflicted, so not resolved here: ${stray.join(', ')}.`,
+            { kind: 'not-conflicted', paths: stray },
+          );
+        }
+        const unresolved = conflicted.filter((p) => !opts.resolutions.has(p));
+        if (unresolved.length > 0) {
+          // Described while the merge is on disk — the three stages and the
+          // marked-up working copy exist only then — and undone (by
+          // `settleMerge`) before the answer leaves the reservation.
+          const mergeBase = await this.git(cwd, ['merge-base', ours, theirs])
+            .then((r) => r.stdout.trim() || null)
+            .catch(() => null);
+          const files: ConflictedFile[] = [];
+          if (opts.describeConflicts) for (const p of conflicted) files.push(await this.describeConflict(cwd, p));
+          return { done: false, outcome: { kind: 'conflicts', from: fromBranch, mergeBase, ours, theirs, files, unresolved } };
+        }
+        for (const p of conflicted) await this.applyResolution(cwd, opts.resolutions.get(p)!);
+        const still = await this.conflictedPaths(cwd);
+        if (still.length > 0) throw new Error(`still conflicted after the resolutions were applied: ${still.join(', ')}`);
+        return {
+          done: true,
+          outcome: await this.commitMerge(workspaceId, cwd, branch, fromBranch, user, opts, conflicted),
+        };
+      });
+    }
+    // A clean merge: committed whatever it staged — an empty diff (the two
+    // sides made the same change) is still the source's history joined.
+    return this.settleMerge(cwd, async () => {
+      if (opts.resolutions.size > 0) throw noConflictsFor();
+      return { done: true, outcome: await this.commitMerge(workspaceId, cwd, branch, fromBranch, user, opts, []) };
+    });
+  }
+
+
+  /**
+   * Run `work` while a merge may be on disk, and leave none: an answer with
+   * `done: false` (a conflict described, nothing to merge) is aborted before
+   * it is returned, and a failure anywhere in `work` is aborted before it is
+   * rethrown. A commit that landed (`done: true`) needs no abort. An abort
+   * that fails while a merge is still in progress is the one thing never
+   * swallowed: it is reported with the failure it followed.
+   */
+  private async settleMerge(
+    cwd: string,
+    work: () => Promise<{ done: boolean; outcome: MergeIntoBranchOutcome }>,
+  ): Promise<MergeIntoBranchOutcome> {
+    let result: { done: boolean; outcome: MergeIntoBranchOutcome };
+    try {
+      result = await work();
+    } catch (err) {
+      await this.abortMerge(cwd, err);
+      throw err;
+    }
+    if (!result.done) await this.abortMerge(cwd);
+    return result.outcome;
+  }
+
+  /**
+   * `git merge --abort`, and proof that nothing is left: a failed abort with
+   * no `MERGE_HEAD` is the benign "no merge to abort"; one that leaves
+   * `MERGE_HEAD` behind is thrown (wrapping `after`, the failure that led
+   * here, when there is one), because the checkout is now stuck.
+   */
+  private async abortMerge(cwd: string, after?: unknown): Promise<void> {
+    try {
+      await this.git(cwd, ['merge', '--abort']);
+      return;
+    } catch (abortErr) {
+      const merging = await this.refExists(cwd, 'MERGE_HEAD').catch(() => true);
+      if (!merging) return;
+      const detail = redactGitToken(abortErr instanceof Error ? abortErr.message : String(abortErr), this.credentials.token());
+      log.error(`a merge in ${cwd} could not be undone; the checkout is left mid-merge:`, { detail });
+      const lead = after === undefined ? 'the merge could not be undone' : `${after instanceof Error ? after.message : String(after)}; and the merge could not be undone`;
+      throw new Error(`${lead}: ${detail}`, { cause: after ?? abortErr });
+    }
+  }
+
+  /** The merge commit, as `user`, and its publish when asked for. The caller settles a failure. */
+  private async commitMerge(
+    workspaceId: string,
+    cwd: string,
+    branch: string,
+    fromBranch: string,
+    user: AuthUser,
+    opts: { subject: string; body: string; publish?: (ops: ReservedPushOps) => Promise<void> },
+    resolvedPaths: string[],
+  ): Promise<MergeIntoBranchOutcome> {
+    await this.git(cwd, ['commit', `--author=${user.name} <${user.email}>`, '-m', opts.subject, '-m', opts.body]);
+    this.accessControl?.invalidate(workspaceId);
+    // The publish runs here, inside the reservation the merge was made in,
+    // over this checkout's own push and pull-rebase (the merge kept as a
+    // merge) — the caller's policy, the git layer's moves. Whatever it
+    // throws leaves the merge commit on the branch locally; a replay that
+    // conflicts aborts itself (`rebaseOntoRemote`), so the checkout is clean.
+    if (opts.publish) {
+      await opts.publish({
+        push: () => this.pushUnlocked(workspaceId, cwd, user),
+        pullRebase: () => this.pullUnlocked(workspaceId, cwd, { preserveMerges: true }),
+      });
+    }
+    // Read AFTER the publish: a push the host rejected is retried with the
+    // local commits replayed onto the moved branch, which gives the merge
+    // commit a new id — the one that is now the published tip.
+    const sha = (await this.git(cwd, ['rev-parse', 'HEAD'])).stdout.trim();
+    return { kind: 'merged', sha, from: fromBranch, resolvedPaths };
+  }
+
+  /**
+   * One conflicted path as the merge on disk has it: the three index stages
+   * (base, ours, theirs) and the working copy with git's markers. A side that
+   * is not there (a delete on that side) is null; one that is not text or too
+   * large to carry is left out and marked, for the caller to read at the
+   * commit instead. Read while the merge is on disk — the stages exist only
+   * then.
+   */
+  private async describeConflict(cwd: string, repoRelativePath: string): Promise<ConflictedFile> {
+    const truncated: NonNullable<ConflictedFile['truncated']> = [];
+    const side = async (name: 'base' | 'ours' | 'theirs', stage: 1 | 2 | 3): Promise<string | null> => {
+      let bytes: Buffer;
       try {
-        const r = await this.git(cwd, [
-          'merge', '--no-commit', '--no-ff', `origin/${targetBranch}`,
-        ]);
-        mergeStdout = r.stdout;
+        bytes = (await this.gitRunner.run(cwd, ['show', `:${stage}:${repoRelativePath}`], { encoding: 'buffer' })).stdout;
       } catch (err) {
-        // Conflict or other failure. Disambiguate via the shared porcelain parse.
-        const conflictPaths = await this.conflictedPaths(cwd);
-        // Always attempt to abort so a partial merge doesn't poison the tree.
-        try {
-          await this.git(cwd, ['merge', '--abort']);
-        } catch {
-          // Already aborted (no MERGE_HEAD) — fine.
-        }
-        if (conflictPaths.length === 0) throw err;
-        return { kind: 'conflicts' as const, paths: conflictPaths };
+        // ONLY a stage git says is not there is a side that has no file (that
+        // side deleted it; the base never had it). Anything else — a deadline,
+        // a repository failure — is not "deleted", and reporting it as such
+        // would have a resolver drop a file over a hiccup.
+        const msg = (err as { stderr?: string }).stderr ?? (err instanceof Error ? err.message : String(err));
+        if (/is in the index, but not at stage|does not exist in|exists on disk, but not in|invalid object name/i.test(msg)) return null;
+        throw err;
       }
-
-      // No conflicts. Detect "already up to date" — git prints that exact
-      // phrase and stages nothing. Otherwise the merge is staged and waiting
-      // for the commit we now author as `user`.
-      if (/Already up to date/i.test(mergeStdout)) {
-        return { kind: 'clean' as const, alreadyUpToDate: true };
+      return this.carriedText(bytes, () => truncated.push(name));
+    };
+    const base = await side('base', 1);
+    const ours = await side('ours', 2);
+    const theirs = await side('theirs', 3);
+    let merged: string | null = null;
+    // The working copy is read from disk, so it is read only where that
+    // stays inside the checkout: a link (the path itself, or a folder on
+    // the way to it) is never followed — the side is left out instead.
+    const file = path.join(cwd, repoRelativePath);
+    const leaf = await lstatOrNull(file);
+    if (leaf?.isSymbolicLink() || (await linkedAncestor(cwd, path.dirname(file))) !== null) {
+      truncated.push('merged');
+    } else {
+      try {
+        merged = this.carriedText(await fs.readFile(file), () => truncated.push('merged'));
+      } catch (err) {
+        if (!isAbsence(err)) throw err;
       }
-      const subject = `Refresh ${sourceBranch} from ${targetBranch}`;
-      const body =
-        `Workflow auto-merge: incorporates the latest ${targetBranch} into ${sourceBranch} ` +
-        `as part of opening or refreshing a change request. ` +
-        `Conflicts (if any) would have been surfaced to the caller before this commit landed; ` +
-        `none were detected, so the merge applied cleanly.`;
-      await this.git(cwd, [
-        'commit',
-        `--author=${user.name} <${user.email}>`,
-        '-m', subject,
-        '-m', body,
-      ]);
-      this.accessControl?.invalidate(workspaceId);
-      return { kind: 'clean' as const, alreadyUpToDate: false };
+    }
+    return { path: repoRelativePath, base, ours, theirs, merged, ...(truncated.length > 0 ? { truncated } : {}) };
+  }
+
+  /**
+   * `bytes` as text when they are text by the one rule every reader applies
+   * (`utf8Text`: no NUL, valid UTF-8, BOM kept) and small enough to carry;
+   * else null, and `left` is told.
+   */
+  private carriedText(bytes: Buffer, left: () => void): string | null {
+    const text = bytes.length > GitService.CONFLICT_SIDE_MAX_CHARS ? null : utf8Text(bytes);
+    if (text === null) left();
+    return text;
+  }
+
+  /**
+   * Settle one conflicted path on disk and in the index, as the resolution
+   * says. `r.path` is one the merge itself listed as conflicted (matched
+   * exactly by the caller), so it is a path git owns inside the checkout.
+   * A side kept whole is restored by git from its index stage, byte for
+   * byte — never through a text decoding — so a binary file survives it.
+   */
+  private async applyResolution(cwd: string, r: MergeResolution): Promise<void> {
+    const file = path.join(cwd, r.path);
+    // Written and removed where that stays inside the checkout: a folder on
+    // the way that is a link is refused, and a path that is itself a link is
+    // replaced as a path (the link removed first), never written through.
+    if ((await linkedAncestor(cwd, path.dirname(file))) !== null) {
+      throw new WorkflowValidationError(`"${r.path}" is reached through a link, so it is not resolved here`);
+    }
+    if (r.content !== undefined) {
+      if ((await lstatOrNull(file))?.isSymbolicLink()) await fs.unlink(file);
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, r.content, 'utf-8');
+      await this.git(cwd, ['add', '--', r.path]);
+      return;
+    }
+    if (r.choose === 'delete') {
+      // `rm` removes a link itself, never what it points at.
+      await fs.rm(file, { force: true });
+      await this.git(cwd, ['add', '-A', '--', r.path]);
+      return;
+    }
+    // `ours`/`theirs`: git checks that side's stage out as it is. A side with
+    // no stage (deleted there) is "does not have our/their version": the
+    // file goes.
+    try {
+      await this.git(cwd, ['checkout', r.choose === 'ours' ? '--ours' : '--theirs', '--', r.path]);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!/does not have (our|their) version/i.test(msg)) throw err;
+      await fs.rm(file, { force: true });
+    }
+    await this.git(cwd, ['add', '-A', '--', r.path]);
+  }
+
+  async readFileAtBranch(
+    workspaceId: string,
+    relativePath: string,
+    branch: string,
+    authorize?: (commits: string[]) => Promise<void>,
+  ): Promise<{ sha: string; ref: string; content: string | null }> {
+    assertValidRelativePath(relativePath);
+    assertValidBranchName(branch);
+    const repoRelativePath = this.stripRepoPrefix(relativePath);
+    return this.mutex.run(workspaceId, async () => {
+      const cwd = await this.repoDir(workspaceId);
+      // The PUBLISHED tip: what the branch's own workspace holds and has not
+      // shared is nobody else's to read, so `origin/<branch>` comes first and
+      // the local head serves only a branch origin does not have.
+      const { ref, sha } = await this.resolvePublishedBranch(cwd, branch);
+      // The caller's verdict, at every commit the branch resolves to here
+      // (the served one first), BEFORE anything is said about the path at
+      // it: a refusal that names what the path is (a folder) is an answer
+      // about content the caller may not read.
+      if (authorize) await authorize(await this.branchCommits(cwd, branch, sha));
+      // Per file, as every history read: a folder's content at a commit is
+      // every child's, which the per-file gate never checked.
+      await this.assertNotTreeAtRef(cwd, sha, repoRelativePath, relativePath);
+      return { sha, ref, content: await this.readFileAtRef(workspaceId, sha, repoRelativePath) };
     });
   }
 
@@ -2052,15 +2439,23 @@ export class GitService implements IGitService {
     return stdout.trim().length > 0;
   }
 
-  /** `git rev-parse --verify` that answers null for a rev that does not resolve (an unborn HEAD). */
+  /**
+   * `git rev-parse --verify --quiet`: the commit `rev` names, or null when
+   * the rev is ABSENT (an unborn HEAD, a ref nobody made) — and nothing
+   * else. Git says "absent" with exit 1 and an empty stderr; a lookup that
+   * fails any other way (a corrupt repository, a deadline) throws, because
+   * every caller reads null as a fact about the repository — "unborn",
+   * "no such tip", "nothing to authorize at" — and a failure dressed as that
+   * fact would make a sync reset an unborn clone or a verdict list lose a
+   * commit.
+   */
   private async revParseOrNull(cwd: string, rev: string): Promise<string | null> {
     try {
       const { stdout } = await this.git(cwd, ['rev-parse', '--verify', '--quiet', rev]);
       return stdout.trim() || null;
     } catch (err) {
-      // Null is "no such rev"; a deadline is not that answer (see GitRunError).
-      if (isGitTimeout(err)) throw err;
-      return null;
+      if (err instanceof GitRunError && !err.timedOut && err.exitCode === 1 && (err.stderr ?? '').trim() === '') return null;
+      throw err;
     }
   }
 
@@ -2273,23 +2668,29 @@ export class GitService implements IGitService {
     workspaceId: string,
     opts: { preserveMerges?: boolean } = {},
   ): Promise<{ treeChanged: boolean }> {
-    return this.mutex.run(workspaceId, async () => {
-      const cwd = await this.repoDir(workspaceId);
-      const branch = await this.checkedOutBranch(cwd);
-      // For `treeChanged` (see IGitService.pull): TREE ids, not commit ids —
-      // a pull that lands only content-identical commits (an empty commit)
-      // must not read as a content change. Tolerant of an unborn HEAD (a
-      // clone of an empty upstream): "" before + a tree after correctly
-      // reads as changed, "" both sides as not.
-      const treeBefore = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
-      // Refresh WITHOUT `git pull`, and without touching `FETCH_HEAD` — see
-      // `refreshRemoteBranchRef` for why both halves are load-bearing.
-      const remoteRef = await this.refreshRemoteBranchRef(cwd, branch);
-      await this.rebaseOntoRemote(cwd, branch, remoteRef, opts);
-      this.accessControl?.invalidate(workspaceId);
-      const treeAfter = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
-      return { treeChanged: treeAfter !== treeBefore };
-    });
+    return this.mutex.run(workspaceId, async () => this.pullUnlocked(workspaceId, await this.repoDir(workspaceId), opts));
+  }
+
+  /** `pull`'s body, for a caller that already holds the workspace's reservation. */
+  private async pullUnlocked(
+    workspaceId: string,
+    cwd: string,
+    opts: { preserveMerges?: boolean } = {},
+  ): Promise<{ treeChanged: boolean }> {
+    const branch = await this.checkedOutBranch(cwd);
+    // For `treeChanged` (see IGitService.pull): TREE ids, not commit ids —
+    // a pull that lands only content-identical commits (an empty commit)
+    // must not read as a content change. Tolerant of an unborn HEAD (a
+    // clone of an empty upstream): "" before + a tree after correctly
+    // reads as changed, "" both sides as not.
+    const treeBefore = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
+    // Refresh WITHOUT `git pull`, and without touching `FETCH_HEAD` — see
+    // `refreshRemoteBranchRef` for why both halves are load-bearing.
+    const remoteRef = await this.refreshRemoteBranchRef(cwd, branch);
+    await this.rebaseOntoRemote(cwd, branch, remoteRef, opts);
+    this.accessControl?.invalidate(workspaceId);
+    const treeAfter = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
+    return { treeChanged: treeAfter !== treeBefore };
   }
 
   /**
@@ -2775,7 +3176,8 @@ export class GitService implements IGitService {
     relativePath: string,
     fromBranch: string,
     toBranch: string,
-  ): Promise<string> {
+    authorize?: (sides: { from: string[]; to: string[] }) => Promise<void>,
+  ): Promise<{ diff: string; from: string; to: string }> {
     assertValidRelativePath(relativePath);
     assertValidBranchName(fromBranch);
     assertValidBranchName(toBranch);
@@ -2785,8 +3187,21 @@ export class GitService implements IGitService {
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
-      const fromRef = await this.resolveBranchRef(cwd, fromBranch);
-      const toRef = await this.resolveBranchRef(cwd, toBranch);
+      // Each side's COMMIT, read once here and diffed from here on: what the
+      // caller authorizes the answer at. The ref is a name a fetch may move.
+      const fromRef = (await this.git(cwd, ['rev-parse', await this.resolveBranchRef(cwd, fromBranch)])).stdout.trim();
+      const toRef = (await this.git(cwd, ['rev-parse', await this.resolveBranchRef(cwd, toBranch)])).stdout.trim();
+      const pinned = (diff: string): { diff: string; from: string; to: string } => ({ diff, from: fromRef, to: toRef });
+      // The caller's verdict at every commit each side resolves to here (the
+      // served one first) BEFORE anything is said about the path at either:
+      // a refusal that names what the path is there (a folder) is an answer
+      // about content the caller may not read.
+      if (authorize) {
+        await authorize({
+          from: await this.branchCommits(cwd, fromBranch, fromRef),
+          to: await this.branchCommits(cwd, toBranch, toRef),
+        });
+      }
       await this.assertNotTreeAtRef(cwd, fromRef, repoRelativePath, relativePath);
       await this.assertNotTreeAtRef(cwd, toRef, repoRelativePath, relativePath);
       // When one side is the currently-checked-out branch, diff against the
@@ -2806,11 +3221,7 @@ export class GitService implements IGitService {
         isToCurrent !== isFromCurrent &&
         (await this.isPathUntracked(cwd, repoRelativePath))
       ) {
-        return synthesizeUntrackedSideDiff(
-          cwd,
-          repoRelativePath,
-          isToCurrent ? 'added' : 'removed',
-        );
+        return pinned(await synthesizeUntrackedSideDiff(cwd, repoRelativePath, isToCurrent ? 'added' : 'removed'));
       }
       const args = ['diff', '--no-color'];
       if (isToCurrent && !isFromCurrent) {
@@ -2832,7 +3243,7 @@ export class GitService implements IGitService {
       args.push('--', repoRelativePath);
       try {
         const { stdout } = await this.git(cwd, args);
-        return stdout;
+        return pinned(stdout);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         throw new Error(
@@ -3757,6 +4168,26 @@ export class GitService implements IGitService {
     throw new WorkflowValidationError(`unknown branch: ${branch}`);
   }
 
+  /**
+   * Every commit `branch` resolves to in this repository — its local head
+   * and its published tip (`origin/<branch>`), whichever resolve, deduped,
+   * `served` first. What a caller's read verdict is asked at: content of
+   * another branch is served from one of them, and a grant at the served one
+   * must not outrun a denial at the other (a draft's unshared commits may
+   * carry rules its published tip does not, and the other way round) — the
+   * rule the compare route always applied to both refs, pinned to commits.
+   */
+  private async branchCommits(cwd: string, branch: string, served: string): Promise<string[]> {
+    const commits = [served];
+    for (const ref of [`refs/heads/${branch}`, `refs/remotes/origin/${branch}`]) {
+      // Null is ABSENT and nothing else (`revParseOrNull`): a lookup that
+      // fails otherwise throws, so this list never quietly loses a commit.
+      const sha = await this.revParseOrNull(cwd, ref);
+      if (sha && !commits.includes(sha)) commits.push(sha);
+    }
+    return commits;
+  }
+
   /**
    * Resolve a branch name to a concrete ref the local clone knows about.
    * Tries the local head first, falls back to the matching remote-tracking