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

package/dist/modules/workflow/git/git.service.js

@@ -4,14 +4,17 @@ import { logger } from '../../../shared/logging.js';
 import { isFolderPlaceholder } from '@bevel-software/platform-shared';
 import { mergeCommitMessageNames } from './merge-commit.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
-import { WorkspaceMutex } from '../../kb-fs/mutex.js';
+import { WorkspaceIdMutex } 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, isBranchAuthoredBy, isOwnSuggestionsBranch, } from '../../kb-fs/branch-name.js';
 import { AppliedChangeMismatchError, BranchAuthorshipError, BranchDeleteRefusedError, WorkflowDomainError, WorkflowValidationError, ProtectedBranchError, PullRebaseConflictError, RemoteBranchGoneError, VersionNotOnBranchError, isMissingRemoteBranchFailure, } from '../../../shared/domain-errors.js';
-import { GitRunError, assertOneSpecPerLine, isGitTimeout, redactGitToken, } from '../../../shared/git.contract.js';
+import { GitRunError, assertOneSpecPerLine, redactGitToken, } from '../../../shared/git.contract.js';
 import { NodeGitRunner } from './node-git-runner.js';
 import { printable } from '../../../shared/printable.js';
 import { sanitizeError } from '../sanitize-error.js';
@@ -270,7 +273,11 @@ export class GitService {
      * replaced). No hooks registered = no commit-time validation, which is
      * safe because validation is advisory and never blocks a commit.
      */
-    hooks, kb, mutex = new WorkspaceMutex(), accessControl = null, 
+    hooks, kb, 
+    // 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.
+    mutex = new WorkspaceIdMutex(), accessControl = null, 
     /**
      * How git is actually run — see `shared/git.contract.ts`. The composition
      * root passes the one runner, carrying the deployment's configured
@@ -849,18 +856,19 @@ export class GitService {
         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. */
+    async isAncestorUnlocked(cwd, ancestor, descendant) {
+        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;
+        }
     }
     /**
      * True iff the given ref (e.g. `refs/heads/foo`, `refs/remotes/origin/foo`)
@@ -1283,8 +1291,20 @@ export class GitService {
             // 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()),
+                });
+            }
         }
     }
     // `forcePush` method removed. The workflow layer no longer auto-force-pushes
@@ -1319,73 +1339,375 @@ export class GitService {
         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}`,
-            ]);
-            // `--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 {
-                const r = await this.git(cwd, [
-                    'merge', '--no-commit', '--no-ff', `origin/${targetBranch}`,
-                ]);
-                mergeStdout = r.stdout;
+            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', paths: outcome.unresolved };
+            return { kind: 'clean', 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. */
+    static CONFLICT_SIDE_MAX_CHARS = 200_000;
+    async mergeIntoBranch(workspaceId, branch, fromBranch, user, opts) {
+        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();
+        // 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'}`);
             }
-            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']);
+            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.
+     */
+    async mergeRefIntoCheckout(workspaceId, cwd, branch, fromBranch, user, opts) {
+        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 = () => 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())}`);
                 }
-                catch {
-                    // Already aborted (no MERGE_HEAD) — fine.
+                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 = [];
+                    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 } };
                 }
-                if (conflictPaths.length === 0)
+                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.
+     */
+    async settleMerge(cwd, work) {
+        let result;
+        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.
+     */
+    async abortMerge(cwd, after) {
+        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. */
+    async commitMerge(workspaceId, cwd, branch, fromBranch, user, opts, resolvedPaths) {
+        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.
+     */
+    async describeConflict(cwd, repoRelativePath) {
+        const truncated = [];
+        const side = async (name, stage) => {
+            let bytes;
+            try {
+                bytes = (await this.gitRunner.run(cwd, ['show', `:${stage}:${repoRelativePath}`], { encoding: 'buffer' })).stdout;
+            }
+            catch (err) {
+                // 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.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;
+            }
+            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 = 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;
-                return { kind: 'conflicts', paths: conflictPaths };
-            }
-            // 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', alreadyUpToDate: true };
-            }
-            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', 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.
+     */
+    carriedText(bytes, left) {
+        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.
+     */
+    async applyResolution(cwd, r) {
+        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, relativePath, branch, authorize) {
+        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) };
         });
     }
     /**
@@ -1766,17 +2088,25 @@ export class GitService {
         const { stdout } = await this.git(cwd, ['ls-remote', '--heads', 'origin']);
         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.
+     */
     async revParseOrNull(cwd, rev) {
         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;
         }
     }
     /**
@@ -1973,23 +2303,24 @@ export class GitService {
         });
     }
     async pull(workspaceId, opts = {}) {
-        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. */
+    async pullUnlocked(workspaceId, cwd, opts = {}) {
+        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 };
     }
     /**
      * Does the checked-out branch carry commits its remote-tracking ref
@@ -2414,7 +2745,7 @@ export class GitService {
             return { baseline, current };
         });
     }
-    async diffFileBetweenBranches(workspaceId, relativePath, fromBranch, toBranch) {
+    async diffFileBetweenBranches(workspaceId, relativePath, fromBranch, toBranch, authorize) {
         assertValidRelativePath(relativePath);
         assertValidBranchName(fromBranch);
         assertValidBranchName(toBranch);
@@ -2424,8 +2755,21 @@ export class GitService {
         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) => ({ 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
@@ -2443,7 +2787,7 @@ export class GitService {
             // same pattern diffFileWorking uses for HEAD-vs-working-tree.
             if (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) {
@@ -2467,7 +2811,7 @@ export class GitService {
             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);
@@ -3260,6 +3604,26 @@ export class GitService {
         }
         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.
+     */
+    async branchCommits(cwd, branch, served) {
+        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