@bevel-software/platform-core-backend 0.25.2 → 0.27.0

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

@@ -2,13 +2,14 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 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 { 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 { assertValidBranchName, assertValidRelativePath, isBranchAuthoredBy, isOwnSuggestionsBranch, } from '../../kb-fs/branch-name.js';
-import { BranchAuthorshipError, WorkflowDomainError, WorkflowValidationError, ProtectedBranchError, PullRebaseConflictError, RemoteBranchGoneError, VersionNotOnBranchError, isMissingRemoteBranchFailure, } from '../../../shared/domain-errors.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 { NodeGitRunner } from './node-git-runner.js';
 import { printable } from '../../../shared/printable.js';
@@ -648,6 +649,16 @@ export class GitService {
     //   - The diff-backup reseed that used to fire here is unnecessary: a
     //     fresh per-branch workspace gets its backup seeded by the workspace
     //     bootstrap path, not by a branch switch on an existing one.
+    /**
+     * Delete a branch, here and on origin. Answers the tip it had — origin's
+     * when origin had it, else the local head's; null when neither existed —
+     * so the caller can say which commit a restore would start from.
+     *
+     * `expectTip`, when given, is the tip the caller's checks were made
+     * against: the remote delete is then leased on it, and a branch that moved
+     * since (a colleague pushed) is refused by the host rather than deleted
+     * with work nobody looked at.
+     */
     async deleteBranch(workspaceId, name, user, opts = {}) {
         assertValidBranchName(name);
         if (this.kb.isProtectedBranch(name)) {
@@ -674,27 +685,33 @@ export class GitService {
                     throw new WorkflowValidationError(`Branch "${name}" still exists on origin — refusing to auto-prune.`);
                 }
             }
-            else {
-                // Authored-or-admin delete path. The branch's author (per the
-                // `<email-localpart>/...` naming convention — see `isBranchAuthoredBy`)
-                // can always delete their own draft. Admins (per the workspace's
-                // `roles.yaml`) can additionally clean up anyone's branch, including
-                // unprefixed CLI branches like `fix/...` that have no recognisable
-                // author. We detect admin via `canWrite(_, _, 'roles.yaml')` because
-                // that predicate is the existing source of truth for `Admin`-role
-                // membership inside the access model — no separate `isAdmin()` plumbing
-                // needed.
-                // Two authorship conventions: `<localpart>/…` UI drafts, and the
-                // `suggestions/<who>-<id8>/…` namespace the propose flow files its
-                // branches under — a user resetting THEIR OWN suggestion bundle is
-                // deleting their own branch.
-                const isAuthor = isBranchAuthoredBy(name, user.email) ||
-                    isOwnSuggestionsBranch(name, { email: user.email, id: user.id });
-                const isAdmin = this.accessControl
-                    ? await this.accessControl.canWrite(workspaceId, user.email, 'roles.yaml')
-                    : false;
-                if (!isAuthor && !isAdmin) {
-                    throw new BranchAuthorshipError(name);
+            else if (!(await this.mayDeleteBranch(workspaceId, name, user))) {
+                throw new BranchAuthorshipError(name);
+            }
+            // Remote delete FIRST. Skip in `onlyIfNoRemote` mode (the contract is
+            // local-only cleanup) and skip when origin has no such branch. Origin
+            // is asked, not this clone's remote-tracking ref: a branch pushed from
+            // another clone since the last fetch has no tracking ref here, and
+            // trusting the cache would delete it locally while it lives on.
+            // A refusal by the host — or a host that cannot be asked — fails the
+            // whole delete: the local branch is untouched, so nothing is
+            // half-deleted and the person can try again. Deleting locally first
+            // would leave a branch that vanished here but lives on the remote —
+            // and, unlike a refused write, a deleted branch has no later push to
+            // reconcile it.
+            let remoteTip = null;
+            if (!opts.onlyIfNoRemote) {
+                try {
+                    remoteTip = await this.originBranchTip(cwd, name);
+                    if (remoteTip !== null) {
+                        const lease = opts.expectTip ? [`--force-with-lease=refs/heads/${name}:${opts.expectTip}`] : [];
+                        await this.git(cwd, ['push', ...lease, 'origin', '--delete', name]);
+                    }
+                }
+                catch (err) {
+                    const detail = sanitizeError(err);
+                    log.warn(`the repository host refused to delete branch "${name}"; leaving it in place:`, { detail });
+                    throw new BranchDeleteRefusedError(name, detail);
                 }
             }
             // Local delete. `-D` force-deletes even if the branch isn't "fully
@@ -705,18 +722,87 @@ export class GitService {
             // Skip when no local ref exists — the picker can surface branches that
             // exist only as `refs/remotes/origin/<name>` (the user hasn't worked on
             // them locally), and "discard from origin" must still work for those.
+            let localTip = null;
             if (await this.refExists(cwd, `refs/heads/${name}`)) {
+                localTip = await this.revParseOrNull(cwd, `refs/heads/${name}`);
                 await this.git(cwd, ['branch', '-D', name]);
             }
-            // Remote delete. Skip in `onlyIfNoRemote` mode (the contract is
-            // local-only cleanup) and skip when there's no remote ref to delete.
-            // A push failure here surfaces to the caller — the local ref is
-            // already gone, and we don't try to resurrect it because rolling back
-            // a "merged-into-the-deleted-branch" local commit would be even more
-            // confusing than the half-finished state.
-            if (!opts.onlyIfNoRemote
-                && await this.refExists(cwd, `refs/remotes/origin/${name}`)) {
-                await this.git(cwd, ['push', 'origin', '--delete', name]);
+            return { lastCommit: remoteTip ?? localTip };
+        });
+    }
+    /**
+     * The author-or-Admin rule for deleting `name`. The branch's author (per
+     * the `<email-localpart>/...` naming convention — see `isBranchAuthoredBy`)
+     * can always delete their own draft. Admins (per the workspace's
+     * `roles.yaml`) can additionally clean up anyone's branch, including
+     * unprefixed CLI branches like `fix/...` that have no recognisable author.
+     * Admin is detected via `canWrite(_, _, 'roles.yaml')` because that
+     * predicate is the existing source of truth for `Admin`-role membership
+     * inside the access model — no separate `isAdmin()` plumbing needed.
+     *
+     * Two authorship conventions: `<localpart>/…` UI drafts, and the
+     * `suggestions/<who>-<id8>/…` namespace the propose flow files its branches
+     * under — a user resetting THEIR OWN suggestion bundle is deleting their
+     * own branch.
+     */
+    async mayDeleteBranch(workspaceId, name, user) {
+        const isAuthor = isBranchAuthoredBy(name, user.email) ||
+            isOwnSuggestionsBranch(name, { email: user.email, id: user.id });
+        if (isAuthor)
+            return true;
+        return this.accessControl
+            ? await this.accessControl.canWrite(workspaceId, user.email, 'roles.yaml')
+            : false;
+    }
+    /**
+     * Where `name` stands in this clone, read from its refs as the last fetch
+     * left them (the caller fetches first): whether it exists on origin or as a
+     * local head, its tip (origin's when it has one), and how many commits on
+     * it — on either ref — are not on `defaultBranch`.
+     *
+     * The default branch is read from origin's ref, falling back to the local
+     * head on a clone whose default was never pushed. A default that resolves
+     * on neither throws: a count against nothing would call every commit
+     * unmerged, or none.
+     */
+    async branchState(workspaceId, name, defaultBranch) {
+        assertValidBranchName(name);
+        assertValidBranchName(defaultBranch);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const remote = await this.revParseOrNull(cwd, `refs/remotes/origin/${name}`);
+            const local = await this.revParseOrNull(cwd, `refs/heads/${name}`);
+            if (remote === null && local === null)
+                return { exists: false, lastCommit: null, unmergedCommits: 0 };
+            const base = (await this.revParseOrNull(cwd, `refs/remotes/origin/${defaultBranch}`)) ??
+                (await this.revParseOrNull(cwd, `refs/heads/${defaultBranch}`));
+            if (base === null) {
+                throw new Error(`the default branch "${defaultBranch}" does not resolve in this clone`);
+            }
+            const tips = [remote, local].filter((sha) => sha !== null);
+            const { stdout } = await this.git(cwd, ['rev-list', '--count', ...tips, `^${base}`]);
+            return { exists: true, lastCommit: remote ?? local, unmergedCommits: Number(stdout.trim()) || 0 };
+        });
+    }
+    /**
+     * Whether commit `ancestor` is contained in commit `descendant`. Exit 1 is
+     * git's "no"; anything else — a commit this clone does not have — throws,
+     * so a caller deciding to delete on a yes never gets one by accident.
+     */
+    async isAncestor(workspaceId, ancestor, descendant) {
+        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;
             }
         });
     }
@@ -1250,12 +1336,23 @@ export class GitService {
      * the new base and re-merge on top of it. Conflicts are deterministic — they
      * return immediately (no retry) so the caller can route into resolution.
      *
-     * Returns the merge commit SHA, or the conflicting paths.
+     * Returns the state the target is left at (`sha`) together with the merge
+     * commit this change request owns (`mergeCommit`, null when there is none), or
+     * the conflicting paths.
      */
     async mergeChangeRequest(baseWorkspaceId, sourceBranch, targetBranch, commit, user, opts = {}) {
         assertValidBranchName(sourceBranch);
         assertValidBranchName(targetBranch);
         assertValidAuthor(user);
+        // The same single-line rule `commit` applies, and for a sharper reason here:
+        // `git commit -m` takes the first PARAGRAPH of this string as the subject, so
+        // a blank line inside it would silently push everything after the break into
+        // the body — including the `(#N)` an applied request is read back by.
+        // `mergeCommitSubject` already flattens the title it builds from; this is the
+        // guard that keeps any other caller from reintroducing the break.
+        if (/\n\s*\n/.test(commit.subject)) {
+            throw new WorkflowValidationError('merge commit subject must be a single paragraph');
+        }
         const MAX_ATTEMPTS = 3;
         return this.mutex.run(baseWorkspaceId, async () => {
             const cwd = await this.repoDir(baseWorkspaceId);
@@ -1320,13 +1417,28 @@ export class GitService {
                     // (e.g. missing identity, unrelated histories) is diagnosable.
                     throw new Error(`git merge failed without detectable conflicts: ${redactGitToken(err instanceof Error ? err.message : String(err), this.credentials.token())}`);
                 }
-                // Nothing staged ⇒ base already contains source (empty CR). The base tip
-                // is the "merged" state; report it without an empty commit.
+                // Nothing staged ⇒ the target already contains the source. The target tip
+                // is the "merged" state; report it without an empty commit — but NOT as
+                // this request's own merge commit. It is whatever landed on the target
+                // last, usually another request's merge commit, and a reader that took it
+                // for this request's would answer with that other request's files under
+                // this number (cubic P1 on #347).
+                //
+                // There are two ways to arrive here, and they differ in exactly one
+                // thing: whether this request has a merge commit on the target already.
+                // An EMPTY request never had anything to land and has none. A request
+                // whose previous attempt pushed its merge commit and then failed to
+                // finalize the row (a transient database fault between the push and the
+                // update) has one, and it is the only place its file list survives — so
+                // it is looked for rather than assumed absent (cubic P2 on #347).
                 const { stdout: staged } = await this.git(cwd, ['diff', '--cached', '--name-only']);
                 if (staged.trim() === '') {
                     const { stdout: sha } = await this.git(cwd, ['rev-parse', 'HEAD']);
                     await this.git(cwd, ['merge', '--abort']).catch(() => undefined);
-                    return { kind: 'merged', sha: sha.trim() };
+                    const own = opts.appliedChangeNumber === undefined
+                        ? null
+                        : await this.ownMergeCommitOn(cwd, `origin/${targetBranch}`, opts.appliedChangeNumber, opts.appliedChangeTitle);
+                    return { kind: 'merged', sha: sha.trim(), mergeCommit: own };
                 }
                 await this.git(cwd, [
                     'commit',
@@ -1338,7 +1450,8 @@ export class GitService {
                 try {
                     await this.git(cwd, ['push', 'origin', `HEAD:refs/heads/${targetBranch}`]);
                     this.accessControl?.invalidate(baseWorkspaceId);
-                    return { kind: 'merged', sha: sha.trim() };
+                    // A commit of this request's own, with the subject the reader verifies.
+                    return { kind: 'merged', sha: sha.trim(), mergeCommit: sha.trim() };
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -1352,6 +1465,100 @@ export class GitService {
             throw new Error(`merge push to "${targetBranch}" kept being rejected after ${MAX_ATTEMPTS} attempts (base moving concurrently)`);
         });
     }
+    /**
+     * The merge commit change request `number` OWNS on `targetBranch`, or null when
+     * the target carries none. Asks the published target only — no source branch,
+     * no working tree, nothing merged, nothing written.
+     *
+     * This is the same question {@link mergeChangeRequest} answers for itself when
+     * it finds nothing to merge, asked WITHOUT attempting a merge at all. The
+     * merge path cannot be the only way to ask it: a request whose merge commit
+     * was pushed by an attempt that then failed to record the row has an empty
+     * diff against the target, so the approval gate refuses the retry ("no file
+     * changes to approve") BEFORE any merge runs, and the recovery inside the
+     * merge never gets its turn (cubic P2 on #347). The gate asks here instead.
+     *
+     * The target ref is refreshed first, because the attempt that pushed the
+     * commit may have run in another process or another clone — and a fetch that
+     * FAILS answers null without looking, which is the only safe answer: what the
+     * caller does with a commit is record it as this request's published state, so
+     * a decision taken on a stale tracking ref could finalize a request with a
+     * commit the published branch no longer carries, and a clone that has no
+     * tracking ref at all would turn the gate's clean refusal into a git error
+     * (cubic P1 on #347). No authority, no answer; the caller then refuses exactly
+     * as it did before this method existed.
+     */
+    async appliedMergeCommitOnTarget(baseWorkspaceId, targetBranch, number, title) {
+        assertValidBranchName(targetBranch);
+        const cwd = await this.repoDir(baseWorkspaceId);
+        // The fetch runs outside the workspace mutex, the way the implicit and
+        // per-request fetches do (see `fetchLocks`, `fetchPrRefs`): it writes only
+        // `refs/remotes/origin/*` and new objects, never HEAD, the index or the
+        // working tree, so nothing it does needs serializing against a checkout or
+        // a commit, and holding the mutex through a network round trip would park
+        // every other git op behind the origin. (`mergeChangeRequest` fetches under
+        // the mutex for a reason this method lacks: its fetch is one step of a
+        // merge whose working tree must not move between the fetch and the push.)
+        // The read that follows is a local one, and takes the mutex like
+        // `appliedChangeShas` does.
+        const refreshed = await this.git(cwd, [
+            'fetch', '--no-write-fetch-head', 'origin',
+            `+refs/heads/${targetBranch}:refs/remotes/origin/${targetBranch}`,
+        ]).then(() => true, () => false);
+        if (!refreshed) {
+            log.warn(`could not refresh "${targetBranch}" to look for change request #${number}'s merge commit, ` +
+                'so it is reported as owning none.');
+            return null;
+        }
+        return this.mutex.run(baseWorkspaceId, () => this.ownMergeCommitOn(cwd, `origin/${targetBranch}`, number, title));
+    }
+    /**
+     * The newest merge commit reachable from `targetRef` that is change request
+     * `number`'s OWN, or null if the target carries none.
+     *
+     * Asked when a merge finds nothing to merge, to tell "this request never had
+     * anything to land" apart from "a previous attempt already landed it". The
+     * second happens when the push succeeded and the row update did not — the
+     * merge commit is on the target, and if this attempt then records no sha the
+     * request becomes permanently fileless, readable by its author alone, with the
+     * commit that holds its files still sitting there unreferenced (cubic P2 on
+     * #347).
+     *
+     * The two conditions are the reader's own (`appliedChangeShas`): a merge
+     * commit, whose subject names this number. Deciding it here with the same
+     * predicate means the writer records only what the reader will accept. The
+     * walk is bounded by `--grep` (the number, as a fixed string), which is the
+     * whole of the target's history for commits mentioning the number — and not
+     * by a count: a fixed count of newer merges once hid a stuck request's commit
+     * from the probe on a busy target, and a request that could no longer be
+     * finalized is worse than a log walk. The message check then confirms a
+     * body-only mention is not the request's own. Never on an ordinary merge:
+     * the two callers are the empty-merge case here and
+     * {@link appliedMergeCommitOnTarget}, which the approval gate asks before it
+     * refuses a retry that has nothing left to merge.
+     *
+     * `title` lets the old message format be recognised — see
+     * {@link mergeCommitMessageNames}.
+     */
+    async ownMergeCommitOn(cwd, targetRef, number, title) {
+        // The whole message per commit. Records are NUL-separated (`-z`), the one
+        // byte a commit message cannot hold, and the sha is the record's first
+        // line: nothing a title may contain can split a record or a line early.
+        const { stdout } = await this.git(cwd, [
+            'log', '-z', '--merges', '--fixed-strings', `--grep=(#${number})`,
+            '--format=%H%n%B', targetRef,
+        ]);
+        for (const record of stdout.split('\0')) {
+            const newline = record.indexOf('\n');
+            const sha = (newline === -1 ? record : record.slice(0, newline)).trim();
+            if (!/^[0-9a-f]{40,64}$/.test(sha))
+                continue;
+            const message = newline === -1 ? '' : record.slice(newline + 1);
+            if (mergeCommitMessageNames(message, number, title))
+                return sha;
+        }
+        return null;
+    }
     /** Conflicted paths from a half-done merge, parsed from porcelain status. */
     async conflictedPaths(cwd) {
         const { stdout } = await this.git(cwd, ['status', '--porcelain=v1']);
@@ -1466,7 +1673,21 @@ export class GitService {
      */
     async remoteBranchExists(workspaceId, branch) {
         assertValidBranchName(branch);
-        const cwd = await this.repoDir(workspaceId);
+        return this.originHasBranch(await this.repoDir(workspaceId), branch);
+    }
+    /** Origin's tip of `branch`, asked of origin itself; null when it has no such branch. */
+    async originBranchTip(cwd, branch) {
+        try {
+            const { stdout } = await this.git(cwd, ['ls-remote', '--exit-code', '--heads', 'origin', `refs/heads/${branch}`]);
+            return /^([0-9a-f]+)\s/.exec(stdout)?.[1] ?? null;
+        }
+        catch (err) {
+            if (err.exitCode === 2)
+                return null;
+            throw err;
+        }
+    }
+    async originHasBranch(cwd, branch) {
         try {
             await this.git(cwd, ['ls-remote', '--exit-code', '--heads', 'origin', `refs/heads/${branch}`]);
             return true;
@@ -1554,9 +1775,10 @@ export class GitService {
             // commit the clone holds but origin has not seen into cherry-picks of
             // the commits it merged — the merged branch stops being a parent, so
             // "does the published head contain the target's head" answers no
-            // however many times the update runs. Only the change-request update
-            // asks for it; every other pull replays plain saves, where the two
-            // spellings produce the same history.
+            // however many times the update runs. The change-request update and
+            // every push's cooperative recovery ask for it (a merge a refused push
+            // stranded rides along with the branch's next push); with no merge
+            // among the local commits the two spellings produce the same history.
             await this.git(cwd, [
                 'rebase',
                 '--autostash',
@@ -1671,7 +1893,12 @@ export class GitService {
                 }
                 throw err;
             }
-            await this.rebaseOntoRemote(cwd, branch, remoteRef);
+            // `preserveMerges` here too: this sync runs on a timer, so it is the
+            // pull most likely to reach a branch while a merge a refused open or
+            // update left local is still waiting for its push. A plain rebase would
+            // flatten that merge before the push ever ran, and the branch would be
+            // "behind" its target again however many times it was updated.
+            await this.rebaseOntoRemote(cwd, branch, remoteRef, { preserveMerges: true });
             this.accessControl?.invalidate(workspaceId);
             const after = await this.revParseOrNull(cwd, 'HEAD');
             const treeAfter = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
@@ -1723,6 +1950,37 @@ export class GitService {
     async hasUnpushedCommits(workspaceId) {
         return this.mutex.run(workspaceId, async () => this.hasUnpushedCommitsAt(await this.repoDir(workspaceId)));
     }
+    /**
+     * Whether this clone's HEAD already holds everything origin has on its
+     * branch: a push would then fast-forward origin to HEAD, and no cooperative
+     * pull-rebase would replay origin's commits INTO HEAD first. Asked after a
+     * fetch, about the fetched ref.
+     *
+     * The roles.yaml preservation asks this before pushing a restore it finds
+     * already committed. "HEAD's roles.yaml is the base version" is only worth
+     * publishing when origin ends up AT HEAD — a clone behind origin would have
+     * origin's divergent copy rebased into it on the way, and the push would
+     * land exactly what the restore exists to keep off the base.
+     *
+     * Exit 1 is git's "not an ancestor". Every other failure propagates — a
+     * tracking ref that does not exist, a broken repository — so a probe that
+     * cannot answer fails the guard closed, never open.
+     */
+    async headContainsOrigin(workspaceId) {
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const branch = await this.currentBranch(cwd);
+            try {
+                await this.git(cwd, ['merge-base', '--is-ancestor', `refs/remotes/origin/${branch}`, 'HEAD']);
+                return true;
+            }
+            catch (err) {
+                if (err instanceof GitRunError && !err.timedOut && err.exitCode === 1)
+                    return false;
+                throw err;
+            }
+        });
+    }
     /**
      * `hasUnpushedCommits` without the workspace reservation — for a caller that
      * already holds one (`mergeChangeRequest`, which has to ask inside the same
@@ -2216,70 +2474,234 @@ export class GitService {
         return this.mutex.run(workspaceId, async () => {
             const baseRef = opts.at ? opts.at.baseSha : await this.resolvePublishedBranchRef(cwd, baseBranch);
             const headRef = opts.at ? opts.at.headSha : await this.resolvePublishedBranchRef(cwd, headBranch);
-            const range = `${baseRef}...${headRef}`; // three-dot = changes on head since merge-base
-            const [{ stdout: nameStatusOut }, { stdout: numstatOut }] = await Promise.all([
-                this.git(cwd, ['diff', '-M', '-z', '--name-status', range]),
-                this.git(cwd, ['diff', '-M', '-z', '--numstat', range]),
-            ]);
-            let statuses = parseNameStatusZ(nameStatusOut);
-            let counts = parseNumstatZ(numstatOut);
-            // roles.yaml can NEVER change through a merge — `preserveBaseRolesYaml`
-            // restores the base copy onto the source branch before every merge — so
-            // listing it as "changed" claims something the merge will not do, and
-            // (worse) makes its approval a requirement for a change that cannot
-            // land. Filter it from the review surface entirely; the neutralisation
-            // reads the raw refs itself and is unaffected. Both lists are filtered
-            // IN STEP so the index-zip below stays aligned.
-            // The empty-folder placeholder is filtered the same way: it is never
-            // content, so it is not a file to review or approve. It still merges
-            // with the rest, and `changedPathsForPr` keeps it, so a request that
-            // only creates a folder is not mistaken for an empty one and closed.
-            // An empty file deleted as its folder gets the (equally empty)
-            // placeholder reads to `-M` as a RENAME onto it; the real side of such
-            // a pair is first made the plain removal (or addition) it is, so
-            // dropping the placeholder never drops the file with it.
-            statuses = statuses.map(withoutPlaceholderRename);
-            if (statuses.some((s) => s.path === 'roles.yaml' || isFolderPlaceholder(s.path))) {
-                const keep = statuses.map((s) => s.path !== 'roles.yaml' && !isFolderPlaceholder(s.path));
-                statuses = statuses.filter((_, i) => keep[i]);
-                if (counts.length === keep.length)
-                    counts = counts.filter((_, i) => keep[i]);
-            }
-            // `--name-status` and `--numstat` enumerate the same files in the same
-            // order (same `-M` over the same range), so we zip by index. If the two
-            // ever disagree in length, the index alignment is unsafe — fall back to
-            // zeroed counts (statuses/paths stay correct) rather than pin the wrong
-            // +/- to a file.
-            const aligned = counts.length === statuses.length;
-            if (!aligned) {
-                crLog.warn(`diff name-status/numstat length mismatch (${statuses.length} vs ${counts.length}) ` +
-                    `for ${range} — reporting file list without +/- counts`);
-            }
-            const files = statuses.map((s, i) => {
-                const c = (aligned ? counts[i] : undefined) ?? { additions: 0, deletions: 0, isBinary: false };
-                return {
-                    path: s.path,
-                    previousPath: s.previousPath,
-                    status: s.status,
-                    additions: c.additions,
-                    deletions: c.deletions,
-                    patch: undefined,
-                    isBinary: c.isBinary,
-                    sha: '',
-                    rawUrl: '',
-                };
-            });
-            // Generate per-file patches for the first `patchCap` non-binary files.
-            let generated = 0;
-            for (const f of files) {
-                if (generated >= patchCap)
-                    break;
-                if (f.isBinary)
-                    continue;
-                f.patch = await this.filePatchForPr(cwd, range, f);
-                generated += 1;
+            // three-dot = changes on head since merge-base
+            return this.prFilesForRange(cwd, `${baseRef}...${headRef}`, patchCap);
+        });
+    }
+    /**
+     * The changed-file list over one already-decided diff `range`, with the
+     * statuses, the +/- counts and up to `patchCap` patches — everything
+     * `changedFilesForPr` does once it knows which two commits it is comparing.
+     *
+     * Separated from the ref resolution because a change request has a second
+     * diff that means exactly the same thing and resolves nothing: the one a
+     * MERGE COMMIT holds, read against its first parent. Both must filter
+     * `roles.yaml` and the folder placeholder the same way and zip the two
+     * `--name-status` / `--numstat` lists by the same index, or a merged request
+     * would answer a different file list from the one it answered while open.
+     *
+     * The caller holds the workspace reservation; this takes none.
+     */
+    async prFilesForRange(cwd, range, patchCap) {
+        const [{ stdout: nameStatusOut }, { stdout: numstatOut }] = await Promise.all([
+            this.git(cwd, ['diff', '-M', '-z', '--name-status', range]),
+            this.git(cwd, ['diff', '-M', '-z', '--numstat', range]),
+        ]);
+        let statuses = parseNameStatusZ(nameStatusOut);
+        let counts = parseNumstatZ(numstatOut);
+        // roles.yaml can NEVER change through a merge — `preserveBaseRolesYaml`
+        // restores the base copy onto the source branch before every merge — so
+        // listing it as "changed" claims something the merge will not do, and
+        // (worse) makes its approval a requirement for a change that cannot
+        // land. Filter it from the review surface entirely; the neutralisation
+        // reads the raw refs itself and is unaffected. Both lists are filtered
+        // IN STEP so the index-zip below stays aligned.
+        // The empty-folder placeholder is filtered the same way: it is never
+        // content, so it is not a file to review or approve. It still merges
+        // with the rest, and `changedPathsForPr` keeps it, so a request that
+        // only creates a folder is not mistaken for an empty one and closed.
+        // An empty file deleted as its folder gets the (equally empty)
+        // placeholder reads to `-M` as a RENAME onto it; the real side of such
+        // a pair is first made the plain removal (or addition) it is, so
+        // dropping the placeholder never drops the file with it.
+        statuses = statuses.map(withoutPlaceholderRename);
+        if (statuses.some((s) => s.path === 'roles.yaml' || isFolderPlaceholder(s.path))) {
+            const keep = statuses.map((s) => s.path !== 'roles.yaml' && !isFolderPlaceholder(s.path));
+            statuses = statuses.filter((_, i) => keep[i]);
+            if (counts.length === keep.length)
+                counts = counts.filter((_, i) => keep[i]);
+        }
+        // `--name-status` and `--numstat` enumerate the same files in the same
+        // order (same `-M` over the same range), so we zip by index. If the two
+        // ever disagree in length, the index alignment is unsafe — fall back to
+        // zeroed counts (statuses/paths stay correct) rather than pin the wrong
+        // +/- to a file.
+        const aligned = counts.length === statuses.length;
+        if (!aligned) {
+            crLog.warn(`diff name-status/numstat length mismatch (${statuses.length} vs ${counts.length}) ` +
+                `for ${range} — reporting file list without +/- counts`);
+        }
+        const files = statuses.map((s, i) => {
+            const c = (aligned ? counts[i] : undefined) ?? { additions: 0, deletions: 0, isBinary: false };
+            return {
+                path: s.path,
+                previousPath: s.previousPath,
+                status: s.status,
+                additions: c.additions,
+                deletions: c.deletions,
+                patch: undefined,
+                isBinary: c.isBinary,
+                sha: '',
+                rawUrl: '',
+            };
+        });
+        // Generate per-file patches for the first `patchCap` non-binary files.
+        let generated = 0;
+        for (const f of files) {
+            if (generated >= patchCap)
+                break;
+            if (f.isBinary)
+                continue;
+            f.patch = await this.filePatchForPr(cwd, range, f);
+            generated += 1;
+        }
+        return files;
+    }
+    /**
+     * The FIRST PARENT of a commit, resolved — the other end of the diff one
+     * commit introduced, and the check that this clone holds the commit at all.
+     *
+     * This is how an applied change request is read back. Its source branch is
+     * retired, so there are no two branch refs left to diff; what is left is the
+     * merge commit the row records, whose first parent is the target as it stood
+     * before the merge and whose tree is the target with the change in it. The
+     * diff between the two is precisely what the request applied — and it is
+     * immutable, which the branch pair never was.
+     *
+     * First-parent and TWO dots, both deliberately. A three-dot diff would be
+     * read from the merge base of the two parents, i.e. it would re-report the
+     * source branch's whole history rather than what landed. `^1` is the target
+     * side for a merge commit, and for a squashed or fast-forwarded commit it is
+     * simply the commit before — the same answer either way.
+     *
+     * Throws `WorkflowValidationError` whenever the recorded commit cannot be
+     * PROVEN to be this request's own merge commit — see
+     * {@link appliedChangeShas}. Every caller reads that as "the file set could
+     * not be resolved" and falls back to its own fail-closed answer, which is what
+     * a clone that has not fetched the merge yet must get: no files, never
+     * somebody else's.
+     */
+    async appliedEnds(cwd, applied) {
+        const { mergeSha, number } = applied;
+        if (!/^[0-9a-f]{40,64}$/.test(mergeSha)) {
+            throw new WorkflowValidationError(`invalid commit sha: ${mergeSha}`);
+        }
+        const revParse = async (rev) => {
+            try {
+                // One question, both answers: `--verify --quiet` prints what it resolved
+                // and exits 1 if there is nothing to resolve.
+                const { stdout } = await this.git(cwd, ['rev-parse', '--verify', '--quiet', rev]);
+                return stdout.trim();
             }
-            return files;
+            catch (err) {
+                // Exit 1 under --quiet is git's own "no such object": this clone does
+                // not have the commit, or the commit has no such parent. Anything else
+                // (a deadline, a broken repository) is the caller's to see.
+                if (err instanceof GitRunError && !err.timedOut && err.exitCode === 1)
+                    return null;
+                throw err;
+            }
+        };
+        // Two refusals, told apart for the caller's sake. A commit this clone does
+        // NOT HOLD is a passing state — the next fetch may bring it — and is
+        // reported as plain validation failure, to be asked again. A commit the
+        // clone holds that is NOT THIS REQUEST'S merge commit (no second parent,
+        // or a message that does not name the request) never becomes it, and is
+        // reported as a mismatch the caller may remember.
+        if (!(await revParse(`${mergeSha}^{commit}`))) {
+            throw new WorkflowValidationError(`commit ${mergeSha} is not in this clone, so change request #${number} cannot be read from it yet`);
+        }
+        // The SECOND parent first, because its absence is the whole P1: a merge
+        // `--no-ff` always has one, and a commit that does not is not a merge this
+        // request made.
+        const headSha = await revParse(`${mergeSha}^2^{commit}`);
+        if (!headSha) {
+            throw new AppliedChangeMismatchError(`commit ${mergeSha} is not a merge commit, so it cannot be change request #${number}'s`);
+        }
+        const baseSha = await revParse(`${mergeSha}^1^{commit}`);
+        if (!baseSha) {
+            throw new AppliedChangeMismatchError(`no first parent for commit ${mergeSha}`);
+        }
+        const { stdout: message } = await this.git(cwd, ['log', '-1', '--format=%B', mergeSha]);
+        if (!mergeCommitMessageNames(message, number, applied.title)) {
+            throw new AppliedChangeMismatchError(`commit ${mergeSha} is not the merge commit of change request #${number}`);
+        }
+        return { baseSha, headSha };
+    }
+    /**
+     * The two commits an APPLIED change request spanned, recovered from the merge
+     * commit its row records: the target as it stood before the merge (`^1`) and
+     * the source tip that was merged (`^2`).
+     *
+     * These are what the detail of a merged request reports as its `baseSha` and
+     * `headSha`, and the `headSha` matters beyond being informative: an approval
+     * row stores the source head it was given against, and the detail calls an
+     * approval stale when that sha is not the detail's `headSha`. Answering the
+     * merge commit itself there would report every approval a merged request ever
+     * collected as stale, and every file of it as unapproved — the opposite of
+     * what happened.
+     *
+     * ## Why the commit is VERIFIED rather than taken
+     *
+     * `merged_sha` is not reliably a commit this request created. When the target
+     * already contains the source there is nothing to merge, so
+     * `mergeChangeRequest` writes no commit and reports the TARGET TIP as the
+     * merged state — and in a deployment that lands everything through change
+     * requests, that tip is usually ANOTHER request's merge commit. Reading "the
+     * recorded commit's own change" then answers with somebody else's files under
+     * this request's number: the request looks like it changed files it never
+     * touched, and becomes visible to whoever may read THOSE (cubic P1 on #347).
+     *
+     * So three things must hold, and all three are cheap:
+     *
+     *   1. the commit is in this clone,
+     *   2. it has a SECOND parent — `mergeChangeRequest` merges `--no-ff`, so
+     *      every merge commit it writes has one, and a commit that has none was
+     *      not written by a merge,
+     *   3. its subject names THIS request — see `merge-commit.ts`.
+     *
+     * Anything else fails closed: no files, so author-only, rather than a file
+     * list that belongs to another change. The write side no longer records a
+     * no-op merge's sha at all, so for rows written from now on all three hold by
+     * construction; the verification is what protects the rows written before it.
+     */
+    async appliedChangeShas(workspaceId, applied) {
+        const cwd = await this.repoDir(workspaceId);
+        return this.mutex.run(workspaceId, async () => this.appliedEnds(cwd, applied));
+    }
+    /**
+     * The changed-file list an APPLIED change request landed, read from its merge
+     * commit against that commit's first parent, and shaped the way
+     * `changedFilesForPr` shapes a branch pair — how an applied request is read
+     * back, since its source branch is retired and the merge commit is what is
+     * left of it.
+     *
+     * TWO dots, from the first parent. A three-dot diff would be read from the
+     * merge base of the merge commit's two parents, i.e. it would re-report the
+     * source branch's whole history instead of what landed on the target.
+     *
+     * Verified, not assumed — see {@link appliedChangeShas}. No fetch: the commit
+     * is in this clone or this rejects.
+     */
+    async changedFilesOfAppliedChange(workspaceId, applied, opts = {}) {
+        const cwd = await this.repoDir(workspaceId);
+        return this.mutex.run(workspaceId, async () => {
+            const { baseSha } = await this.appliedEnds(cwd, applied);
+            return this.prFilesForRange(cwd, `${baseSha}..${applied.mergeSha}`, opts.patchCap ?? 400);
+        });
+    }
+    /**
+     * The same applied change as the two path views a change-request SUMMARY needs
+     * — the flat touched-path list and the rename-aware pairs — out of one
+     * `git diff`, exactly as {@link changedPathsAndPairsForPr} does for a branch
+     * pair. Same verification and same no-fetch contract.
+     */
+    async changedPathsAndPairsOfAppliedChange(workspaceId, applied) {
+        const cwd = await this.repoDir(workspaceId);
+        return this.mutex.run(workspaceId, async () => {
+            const { baseSha } = await this.appliedEnds(cwd, applied);
+            const entries = await this.prChangedEntriesForRange(cwd, `${baseSha}..${applied.mergeSha}`);
+            return { paths: flattenChangedPaths(entries, {}), pairs: changedPathPairs(entries) };
         });
     }
     /**
@@ -2335,28 +2757,54 @@ export class GitService {
      * deadlock — and where the refs are the ones the merge is actually built on.
      */
     async prChangedPathsAt(cwd, baseRef, headRef, opts = {}) {
-        const { stdout } = await this.git(cwd, [
-            'diff', '-M', '-z', '--name-status', `${baseRef}...${headRef}`,
-        ]);
-        // Deduped: both sides of a rename can collide with another entry's path.
-        return [
-            ...new Set(parseNameStatusZ(stdout)
-                // A rename onto or off the placeholder is a real file removed or
-                // added (see `withoutPlaceholderRename`): both of its paths are
-                // touched, or filtering the placeholder would lose the file.
-                //
-                // Authorizing the change needs both sides of EVERY rename, not just
-                // the placeholder's: git reports a rename under its new name alone,
-                // and the old name is a path the change deletes.
-                .flatMap((s) => s.previousPath &&
-                (opts.forAccessCheck || isFolderPlaceholder(s.path) || isFolderPlaceholder(s.previousPath))
-                ? [s.previousPath, s.path]
-                : [s.path])
-                // Same rule as `changedFilesForPr`: a roles.yaml change never
-                // survives a merge, so it is not a touched path for routing or
-                // summaries either.
-                .filter((p) => opts.forAccessCheck || p !== 'roles.yaml')),
-        ];
+        return flattenChangedPaths(await this.prChangedEntriesAt(cwd, baseRef, headRef), opts);
+    }
+    /**
+     * The same diff, left as parsed ENTRIES: each changed file with the path it
+     * came from when git detected a rename.
+     *
+     * The flat path list cannot express that pairing, and a caller deciding what
+     * someone may READ needs it. A file renamed out of a folder the caller cannot
+     * open is readable under neither of its names — the diff of a rename shows
+     * the old side's content — and a flat list that offers both paths unlabelled
+     * cannot say which new file the closed old path belongs to. `forAccessCheck`
+     * solves the write side of this by taking the union; a read gate needs the
+     * pairing itself.
+     */
+    async prChangedEntriesAt(cwd, baseRef, headRef) {
+        return this.prChangedEntriesForRange(cwd, `${baseRef}...${headRef}`);
+    }
+    /**
+     * The same parsed entries over an already-decided `range`, so a merge
+     * commit's own diff ({@link firstParentRange}) is read by the same parser as a
+     * change request's branch pair.
+     */
+    async prChangedEntriesForRange(cwd, range) {
+        const { stdout } = await this.git(cwd, ['diff', '-M', '-z', '--name-status', range]);
+        return parseNameStatusZ(stdout);
+    }
+    /**
+     * One diff, both views of it: the flat touched-path list every existing
+     * caller reads, and the rename-aware pairs a read gate needs. The change-
+     * request summary builder wants both, and must not pay for two `git diff`s
+     * to get them — it is on the list path that is polled every 60s.
+     */
+    async changedPathsAndPairsForPr(workspaceId, baseBranch, headBranch, opts = {}) {
+        assertValidBranchName(baseBranch);
+        assertValidBranchName(headBranch);
+        const cwd = await this.repoDir(workspaceId);
+        // Same ref pinning and the same fetch skip as `changedPathsForPr`, for the
+        // same reasons spelled out there.
+        const pinned = opts.fetch === false ? await this.publishedPrCommits(cwd, baseBranch, headBranch) : null;
+        if (!pinned) {
+            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);
+            return { paths: flattenChangedPaths(entries, {}), pairs: changedPathPairs(entries) };
+        });
     }
     /**
      * The merge-base commit of a change request's two branches (their origin
@@ -3135,6 +3583,59 @@ function mapGitStatus(letter) {
  * Parse `git diff -M -z --name-status` output. NUL-separated tokens: each record
  * is `<statusLetter>\0<path>`, or for a rename/copy `<Rxxx|Cxxx>\0<old>\0<new>`.
  */
+/**
+ * The flat touched-path list of a parsed `--name-status` diff. Lifted out of
+ * `prChangedPathsAt` unchanged, so the pair-returning reader can share one
+ * diff with it rather than running a second.
+ */
+function flattenChangedPaths(entries, opts = {}) {
+    // Deduped: both sides of a rename can collide with another entry's path.
+    return [
+        ...new Set(entries
+            // A rename onto or off the placeholder is a real file removed or
+            // added (see `withoutPlaceholderRename`): both of its paths are
+            // touched, or filtering the placeholder would lose the file.
+            //
+            // Authorizing the change needs both sides of EVERY rename, not just
+            // the placeholder's: git reports a rename under its new name alone,
+            // and the old name is a path the change deletes.
+            .flatMap((s) => s.previousPath &&
+            (opts.forAccessCheck || isFolderPlaceholder(s.path) || isFolderPlaceholder(s.previousPath))
+            ? [s.previousPath, s.path]
+            : [s.path])
+            // Same rule as `changedFilesForPr`: a roles.yaml change never
+            // survives a merge, so it is not a touched path for routing or
+            // summaries either.
+            .filter((p) => opts.forAccessCheck || p !== 'roles.yaml')),
+    ];
+}
+/**
+ * The changed files of a diff as read-gate pairs: every file the request
+ * proposes, carrying the path it was renamed from when it has one.
+ *
+ * Normalised and filtered EXACTLY as `changedFilesForPr` does it, through the
+ * same `withoutPlaceholderRename` and the same two drops — because this is the
+ * file set a change-request LIST decides visibility over and that one is the
+ * file set its DETAIL decides over, and the two answering differently is how a
+ * list comes to advertise a request its own detail refuses (or to hide one the
+ * detail serves). Any future change to one filter belongs in both.
+ */
+function changedPathPairs(entries) {
+    const byPath = new Map();
+    for (const raw of entries) {
+        // A rename between a real file and the placeholder is a removal or an
+        // addition of the real side; after this, the placeholder filter below
+        // cannot take the file with it.
+        const entry = withoutPlaceholderRename(raw);
+        if (isFolderPlaceholder(entry.path) || entry.path === 'roles.yaml')
+            continue;
+        byPath.set(entry.path, {
+            path: entry.path,
+            ...(entry.previousPath ? { previousPath: entry.previousPath } : {}),
+        });
+    }
+    return [...byPath.values()];
+}
 export function parseNameStatusZ(out) {
     const tokens = out.split('\0');
     const entries = [];