@bevel-software/platform-core-backend 0.29.0 → 0.31.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,10 +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,
@@ -47,7 +55,6 @@ import {
 import {
   GitRunError,
   assertOneSpecPerLine,
-  isGitTimeout,
   redactGitToken,
   type GitCredentials,
   type GitRunOptions,
@@ -294,6 +301,25 @@ export class GitService implements IGitService {
   // counts, calm under large branch lists.
   private static readonly MAX_AHEAD_BEHIND_CONCURRENCY = 8;
 
+  /**
+   * A change request's changed entries, keyed by the two commits its diff
+   * was read between. Two commits never change, and neither does the
+   * merge-base between them, so the three-dot diff of a pair is a fact: a
+   * push moves a tip, the pair changes, the old entry is simply never asked
+   * for again. No TTL, no invalidation.
+   *
+   * This is what a change-request listing was paying git for on every read:
+   * one `diff` per open request, polled every minute and refetched on every
+   * event, where nothing had moved. Now git is asked once per pair, which is
+   * once per push. Keyed by commits alone, not by workspace: every clone of
+   * the knowledge base holds the same objects, so the answer is the same in
+   * all of them. Bounded FIFO; the bound only caps memory.
+   */
+  private readonly changedEntriesByCommits = new Map<string, NameStatusEntry[]>();
+  /** Diffs being read right now, so concurrent misses on one pair share one `git diff`. */
+  private readonly changedEntriesInFlight = new Map<string, Promise<NameStatusEntry[]>>();
+  private static readonly CHANGED_ENTRIES_MAX = 4096;
+
   constructor(
     private readonly workspaceService: WorkspaceService,
     /**
@@ -305,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
@@ -378,7 +407,9 @@ export class GitService implements IGitService {
    * above rather than kept separately, so it cannot disagree with it.
    */
   lastRemoteContact(): { at: number; ok: boolean } | null {
-    let latest: { at: number; ok: boolean } | null = null;
+    // The repository's fetches are every worktree's; the per-workspace record
+    // is a full clone's.
+    let latest: { at: number; ok: boolean } | null = this.workspaceService.repository?.lastContact() ?? null;
     for (const [workspaceId, at] of this.lastImplicitFetchAt) {
       if (latest === null || at > latest.at) {
         latest = { at, ok: this.lastImplicitFetchOk.get(workspaceId) ?? false };
@@ -495,12 +526,27 @@ export class GitService implements IGitService {
       // Union local heads with origin's remote-tracking refs: a fresh per-user
       // clone only has one local head (HEAD's default), so without this we'd hide
       // target-company-state and every draft pushed by another user.
+      //
+      // The workspace is a worktree of the one repository, which holds every
+      // OTHER worktree's local branch too. Those are not this workspace's: a
+      // clone never had them. A local head checked out in another worktree
+      // is read as that branch's remote-tracking ref alone (and not at all
+      // once origin no longer has it), so a branch deleted on origin is not
+      // kept alive by its own worktree's local ref — the orphan sweep reads
+      // this list. A branch is checked out in at most one worktree, so "not
+      // this one's HEAD" is "another's".
       const { stdout } = await this.git(cwd, [
         'for-each-ref',
-        '--format=%(refname:short)%09%(refname)',
+        '--format=%(refname:short)%09%(refname)%09%(worktreepath)',
         'refs/heads',
         'refs/remotes/origin',
       ]);
+      const ownBranch = (
+        await this.git(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']).then(
+          (r) => r.stdout,
+          () => '',
+        )
+      ).trim();
 
       type Row = { shortName: string; ref: string; hasLocal: boolean; hasRemote: boolean };
       const buckets = new Map<string, Row>();
@@ -510,7 +556,7 @@ export class GitService implements IGitService {
         const tab = trimmed.indexOf('\t');
         if (tab < 0) continue;
         const rawShort = trimmed.slice(0, tab);
-        const ref = trimmed.slice(tab + 1);
+        const [ref = '', worktreePath = ''] = trimmed.slice(tab + 1).split('\t');
         if (!rawShort || !ref) continue;
         // Skip symbolic refs up-front. Different git versions report
         // `refs/remotes/origin/HEAD` as either `origin` (older) or `origin/HEAD`
@@ -521,6 +567,7 @@ export class GitService implements IGitService {
         const isLocal = ref.startsWith('refs/heads/');
         const shortName = isLocal ? rawShort : rawShort.replace(/^origin\//, '');
         if (!shortName) continue;
+        if (isLocal && worktreePath !== '' && shortName !== ownBranch) continue;
         // Final guard: the strip above turns `origin/HEAD` into `HEAD`. Even
         // if a future git version lands us here, don't bucket it as a branch.
         if (shortName === 'HEAD') continue;
@@ -614,6 +661,20 @@ export class GitService implements IGitService {
     workspaceId: string,
     force = false,
   ): Promise<boolean> {
+    // A worktree's remote-tracking refs are the repository's: ONE fetch for
+    // every workspace, throttled, joined and reserved there. The per-workspace
+    // record below is for a full clone from an earlier release, which fetches
+    // on its own until the boot phase converts it.
+    const repository = (await this.workspaceService.repositoryOfCheckout?.(cwd)) ?? null;
+    if (repository) {
+      return repository.fetch({
+        maxAgeMs: GitService.IMPLICIT_FETCH_TTL_MS,
+        // A host that is down is not asked again by every poll inside the
+        // window, as the per-workspace record below stamps a failure too.
+        failureBackoffMs: GitService.IMPLICIT_FETCH_TTL_MS,
+        force,
+      });
+    }
     const last = this.lastImplicitFetchAt.get(workspaceId) ?? 0;
     if (!force && Date.now() - last < GitService.IMPLICIT_FETCH_TTL_MS) {
       return this.lastImplicitFetchOk.get(workspaceId) ?? true;
@@ -692,8 +753,9 @@ export class GitService implements IGitService {
       // navigation to the new draft's URL fails with
       // "Remote branch <name> not found in upstream origin". Roll the local
       // ref back on failure so a retry isn't blocked by "branch already exists".
+      // No `-u`: the local head is dropped right below, and its upstream with it.
       try {
-        await this.git(cwd, ['push', '-u', 'origin', name]);
+        await this.git(cwd, ['push', 'origin', name]);
       } catch (err) {
         await this.git(cwd, ['branch', '-D', name]).catch(() => undefined);
         throw err;
@@ -829,7 +891,14 @@ export class GitService implements IGitService {
       let localTip: string | null = null;
       if (await this.refExists(cwd, `refs/heads/${name}`)) {
         localTip = await this.revParseOrNull(cwd, `refs/heads/${name}`);
-        await this.git(cwd, ['branch', '-D', name]);
+        await this.git(cwd, ['branch', '-D', name]).catch((err: unknown) => {
+          // In a repository of worktrees the branch's local ref is shared, and
+          // git keeps it while the branch's own workspace has it checked out.
+          // Removing that workspace — which the caller does next — takes the
+          // worktree and the ref with it.
+          if (/checked out at|used by worktree/i.test(err instanceof Error ? err.message : String(err))) return;
+          throw err;
+        });
       }
       return { lastCommit: remoteTip ?? localTip };
     });
@@ -903,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;
+    }
   }
 
   /**
@@ -1409,7 +1480,25 @@ export class GitService implements IGitService {
         );
       }
 
-      await this.git(cwd, ['push', '-u', 'origin', branch]);
+      // No `-u`: it writes the upstream into the config during the push, and
+      // a worktree's config is the repository's, shared by every workspace —
+      // git refuses a second writer of it rather than waiting. The upstream is
+      // stamped after the push instead, as one short write made as the
+      // repository's administrator (see `git`).
+      await this.git(cwd, ['push', 'origin', 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()),
+        });
+      }
     }
   }
 
@@ -1454,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 };
+    }
+
+    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 };
+  }
 
-      // `--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 = '';
+  /**
+   * 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) };
     });
   }
 
@@ -1985,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;
     }
   }
 
@@ -2206,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 };
   }
 
   /**
@@ -2708,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);
@@ -2718,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
@@ -2739,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) {
@@ -2765,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(
@@ -3166,9 +3644,8 @@ export class GitService implements IGitService {
       await this.fetchPrRefs(cwd, baseBranch, headBranch);
     }
     return this.mutex.run(workspaceId, async () => {
-      const baseRef = pinned ? pinned.base : await this.resolvePublishedBranchRef(cwd, baseBranch);
-      const headRef = pinned ? pinned.head : await this.resolvePublishedBranchRef(cwd, headBranch);
-      return this.prChangedPathsAt(cwd, baseRef, headRef, opts);
+      const at = pinned ?? (await this.publishedPrEnds(cwd, baseBranch, headBranch));
+      return flattenChangedPaths(await this.prChangedEntriesBetweenCommits(cwd, at.base, at.head), opts);
     });
   }
 
@@ -3243,13 +3720,51 @@ export class GitService implements IGitService {
       await this.fetchPrRefs(cwd, baseBranch, headBranch);
     }
     return this.mutex.run(workspaceId, async () => {
-      const baseRef = pinned ? pinned.base : await this.resolvePublishedBranchRef(cwd, baseBranch);
-      const headRef = pinned ? pinned.head : await this.resolvePublishedBranchRef(cwd, headBranch);
-      const entries = await this.prChangedEntriesAt(cwd, baseRef, headRef);
+      const at = pinned ?? (await this.publishedPrEnds(cwd, baseBranch, headBranch));
+      const entries = await this.prChangedEntriesBetweenCommits(cwd, at.base, at.head);
       return { paths: flattenChangedPaths(entries, {}), pairs: changedPathPairs(entries) };
     });
   }
 
+  /**
+   * {@link prChangedEntriesAt} for a pair of COMMITS, read once per pair
+   * (see `changedEntriesByCommits`). The caller holds the reservation, as for
+   * `prChangedEntriesAt`; a memo hit holds it for nothing, which is cheaper
+   * than a second code path around the lock.
+   */
+  private async prChangedEntriesBetweenCommits(
+    cwd: string,
+    baseSha: string,
+    headSha: string,
+  ): Promise<NameStatusEntry[]> {
+    const key = `${baseSha}\0${headSha}`;
+    const known = this.changedEntriesByCommits.get(key);
+    if (known) return known;
+    let pending = this.changedEntriesInFlight.get(key);
+    if (!pending) {
+      pending = this.prChangedEntriesAt(cwd, baseSha, headSha)
+        .then((entries) => {
+          if (this.changedEntriesByCommits.size >= GitService.CHANGED_ENTRIES_MAX) {
+            const oldest = this.changedEntriesByCommits.keys().next().value;
+            if (oldest !== undefined) this.changedEntriesByCommits.delete(oldest);
+          }
+          this.changedEntriesByCommits.set(key, entries);
+          return entries;
+        })
+        .finally(() => {
+          if (this.changedEntriesInFlight.get(key) === pending) this.changedEntriesInFlight.delete(key);
+        });
+      // Same bound as the memo: evicting an in-flight entry costs at most one
+      // redundant diff for that pair, never a lost answer.
+      if (this.changedEntriesInFlight.size >= GitService.CHANGED_ENTRIES_MAX) {
+        const oldest = this.changedEntriesInFlight.keys().next().value;
+        if (oldest !== undefined) this.changedEntriesInFlight.delete(oldest);
+      }
+      this.changedEntriesInFlight.set(key, pending);
+    }
+    return pending;
+  }
+
   /**
    * The merge-base commit of a change request's two branches (their origin
    * refs), or null when they share no history. This is the "before" the CR's
@@ -3590,16 +4105,23 @@ export class GitService implements IGitService {
     baseBranch: string,
     headBranch: string,
   ): Promise<{ base: string; head: string } | null> {
-    const shas: string[] = [];
-    for (const branch of [baseBranch, headBranch]) {
-      try {
-        shas.push((await this.resolvePublishedBranch(cwd, branch)).sha);
-      } catch (err) {
-        if (err instanceof WorkflowValidationError) return null;
-        throw err;
-      }
+    try {
+      return await this.publishedPrEnds(cwd, baseBranch, headBranch);
+    } catch (err) {
+      if (err instanceof WorkflowValidationError) return null;
+      throw err;
     }
-    return { base: shas[0], head: shas[1] };
+  }
+
+  /** The two commits a change request is read between, each resolved as {@link resolvePublishedBranch} does. */
+  private async publishedPrEnds(
+    cwd: string,
+    baseBranch: string,
+    headBranch: string,
+  ): Promise<{ base: string; head: string }> {
+    const base = (await this.resolvePublishedBranch(cwd, baseBranch)).sha;
+    const head = (await this.resolvePublishedBranch(cwd, headBranch)).sha;
+    return { base, head };
   }
 
   /**
@@ -3625,6 +4147,13 @@ export class GitService implements IGitService {
     branch: string,
   ): Promise<{ ref: string; sha: string }> {
     for (const ref of [`refs/remotes/origin/${branch}`, `refs/heads/${branch}`]) {
+      // The ref file first (`readRefSha`): no process, same answer, same
+      // freshness. Git is asked only for what the files cannot decide — a
+      // missing ref is decided by the files and the loop moves on; an
+      // unreadable one is git's to answer, as the authority.
+      const fromFiles = await readRefSha(cwd, ref);
+      if (fromFiles === 'missing') continue;
+      if (fromFiles !== 'unreadable') return { ref, sha: fromFiles.sha };
       try {
         const { stdout } = await this.git(cwd, ['rev-parse', '--verify', '--quiet', ref]);
         return { ref, sha: stdout.trim() };
@@ -3639,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
@@ -4097,7 +4646,7 @@ export class GitService implements IGitService {
    * from a real failure are unaffected.
    */
   private git(cwd: string, args: string[], opts?: Omit<GitRunOptions, 'encoding'>): Promise<GitRunResult> {
-    return this.gitRunner.run(cwd, args, {
+    const run = () => this.gitRunner.run(cwd, args, {
       ...opts,
       // `GIT_LITERAL_PATHSPECS=1` makes git treat every pathspec literally
       // instead of interpreting `[`, `]`, `*`, `?`, `!`, or `:(magic)` as glob
@@ -4112,6 +4661,18 @@ export class GitService implements IGitService {
       // a search for a file literally named that.
       env: { GIT_LITERAL_PATHSPECS: '1', ...opts?.env },
     });
+    // A write to the git config is a write to the ONE file every worktree of
+    // the repository shares, which git refuses a second writer of rather than
+    // waiting: it runs as the repository's administrator. Everything else —
+    // a fetch, a commit, a branch delete — git serializes with its own locks,
+    // as it does for any two worktrees of one repository.
+    return writesSharedConfig(args) ? this.asRepositoryAdministrator(cwd, run) : run();
+  }
+
+  /** `run` as the repository's administrator when `cwd` is a worktree of it; as itself for a full clone. */
+  private async asRepositoryAdministrator<T>(cwd: string, run: () => Promise<T>): Promise<T> {
+    const repository = (await this.workspaceService.repositoryOfCheckout?.(cwd)) ?? null;
+    return repository ? repository.exclusive(run) : run();
   }
 
   /**
@@ -4299,3 +4860,35 @@ export function parseNumstatZ(out: string): NumstatEntry[] {
   }
   return entries;
 }
+
+/**
+ * Whether a git command WRITES the config — the one file every worktree of
+ * the knowledge base's repository shares, which git refuses a second writer
+ * of rather than waiting — and so must run as the repository's administrator
+ * (`IKbRepository.exclusive`): a `config` that sets or unsets, a `remote`
+ * change, a branch rename, delete or upstream change (its config section is
+ * written, or removed with the branch), a push that sets the upstream. Reads
+ * of the config are not writes. Nothing else is: the refs, `packed-refs` and
+ * the object store are locked by git itself, and the worktree list is the
+ * repository's own to serialize (`KbRepository`).
+ *
+ * Leading `-c key=value` / `-C dir` options are skipped to find the subcommand.
+ */
+function writesSharedConfig(args: readonly string[]): boolean {
+  let i = 0;
+  while (i < args.length && (args[i] === '-c' || args[i] === '-C')) i += 2;
+  const sub = args[i];
+  const rest = args.slice(i + 1);
+  switch (sub) {
+    case 'remote':
+      return true;
+    case 'config':
+      return !rest.some((a) => /^(--get|--get-all|--get-regexp|--list|-l|--show-origin)$/.test(a));
+    case 'branch':
+      return rest.some((a) => /^(-d|-D|--delete|-m|-M|--move|-u|--set-upstream-to=.*|--unset-upstream)$/.test(a));
+    case 'push':
+      return rest.some((a) => a === '-u' || a === '--set-upstream');
+    default:
+      return false;
+  }
+}