canopycms 0.11.1 → 0.12.1

package/dist/worker/github-commits.d.ts

@@ -44,9 +44,13 @@ export type GitHubCommitsOutcome =
  | {
     kind: 'unpushed';
 }
-/** A merge landed. A rebase now would replace a merge GitHub has not received. */
+/**
+ * A merge landed. A rebase now would replace a merge GitHub has not received. `keptEntries`
+ * counts the entries with a conflict it left for a person.
+ */
  | {
     kind: 'merged';
+    keptEntries: number;
 }
 /** Left as it is until a person acts. `reason` says what to do. */
  | {
@@ -76,28 +80,56 @@ export declare const SEEN_COMMIT_GONE_PUSH_REFUSAL = "A commit this branch had o
  * be combined. The failed sync it left goes too, unless {@link awaitsSubmitRetry}.
  */
 export declare function rewriteCleared(branch: BranchMetadata): Partial<BranchMetadata>;
+/** A branch this deployment put on GitHub. Any other GitHub branch of that name is not its own. */
+export declare function isPublished({ branch }: BranchMetadataFile): boolean;
+/**
+ * Fast-forward the clone to the merge this worker was landing, when `remote.git` holds it on top of
+ * the clone, as a crash or a lost lock between publishing it and moving the clone leaves it,
+ * whether or not the branch is on GitHub. Resolves why it stopped, or null when there was nothing
+ * to catch up with or it caught up.
+ */
+export declare function catchUpWithPublished(ctx: GitHubCommitsContext, args: GitHubCommitsArgs): Promise<GitHubCommitsOutcome | null>;
 /** Bring GitHub's commits into the clone. Throws what git throws; the caller records it. */
 export declare function bringInGitHubCommits(ctx: GitHubCommitsContext, args: GitHubCommitsArgs): Promise<GitHubCommitsOutcome>;
 /**
- * `other` merged into the branch: built, published to `remote.git`, queued for GitHub, and the
- * clone moved to it, in that order, so each step leaves what the next cycle picks up and only the
- * last touches the working tree. `fromGitHub` says `other` is GitHub's tip rather than the base.
- * `stopOnConflict` leaves a branch in review as it is: nobody is at the editor to see what a kept
- * version replaced, and GitHub's own conflict notice stands on the pull request.
+ * `other` merged into the branch: built, recorded, published to `remote.git`, queued for GitHub,
+ * and the clone moved to it, in that order, so each step leaves what the next cycle picks up and
+ * only the last touches the working tree. `fromGitHub` says `other` is GitHub's tip rather than the
+ * base. `inReview` takes only a merge with nothing for a person to choose; any other leaves the
+ * branch as it is and records nothing, and GitHub's own conflict notice stands on the pull request. A lock lost before the clone moves leaves it where it was: `wait`.
  */
 export declare function mergeIntoBranch(ctx: GitHubCommitsContext, args: GitHubCommitsArgs, merge: {
     head: string;
     other: string;
     message: string;
     fromGitHub: boolean;
-    stopOnConflict?: boolean;
+    inReview?: boolean;
 }): Promise<GitHubCommitsOutcome>;
 /**
- * Send an approved branch back to review and clear the verdict from the PR body. Before the clone
- * moves, and a failed save throws, so a crash or a failure leaves the commits for the next cycle
- * to judge again rather than an approval standing over them.
+ * Whether `commit` contains `ancestor`. A commit this clone does not hold counts as no. Any other
+ * failure throws, since it says nothing about either commit, and the caller's catch retries next
+ * cycle: read as no, it would report a rewrite that never happened.
+ */
+export declare function contains(git: SimpleGit, commit: string, ancestor: string): Promise<boolean>;
+/**
+ * Send an approved branch back to review and clear the verdict from the PR body. Called before the
+ * clone moves, where a failed save throws, so a crash or a failure leaves the commits for the next
+ * cycle to judge again rather than an approval standing over them.
  */
 export declare function returnToReview(ctx: GitHubCommitsContext, { branchPath, branchDir, branchRef, metaFile }: GitHubCommitsArgs): Promise<void>;
+/**
+ * Bring merge-conflicts.json in line with the branch's history: a record changed by a merge the
+ * branch never got gives back the one it replaced (`withoutMergesGone`), and `branch.json`
+ * `conflictFiles` follows the record when the two differ. A merge counts as held while the clone or
+ * `remote.git` holds it, since a clone behind its published merge catches up with it; comment
+ * threads take a merge's item keys only once the clone holds it. While either can't be read in the
+ * clone, nothing is judged. A record that does not parse is moved aside, so the branch's merges
+ * carry on with a new one. Each cycle, before the branch takes anything in. A clone with no record
+ * has no conflict open, so `conflictFiles` written before the record existed clears. Never throws.
+ */
+export declare function reconcileMergeConflicts(ctx: GitHubCommitsContext, { git, branchPath, branchDir, branchRef, }: Pick<GitHubCommitsArgs, 'git' | 'branchPath' | 'branchDir'> & {
+    branchRef: string | null;
+}): Promise<void>;
 /**
  * Re-render the PR body's review block alone: the worker has no `config.editorUrl`, so a full
  * sync from here would strip the comment summary's links. Best-effort: a failure leaves the block

package/dist/worker/github-commits.js

@@ -1,13 +1,15 @@
 import { BranchMetadataFileManager, awaitsSubmitRetry, getBranchMetadataFileManager, } from '../branch-metadata.js';
+import { CommentStore } from '../comment-store.js';
 import { invalidateBranchContentCaches } from '../content-index-generation.js';
 import { GITHUB_TRACKING_REF_PREFIX } from '../git-manager.js';
+import { MergeConflictStore, MergeConflictsFileMalformedError, conflictFilesOf, withFoundConflicts, withRemappedItemKeys, withoutMergesGone, } from '../merge-conflicts.js';
 import { SYNC_PR_COMMENTS_ACTION } from '../pr-comments.js';
 import { enqueueTask } from '../task-queue/cms-task-queue.js';
 import { getErrorMessage } from '../utils/error.js';
 import { escapeForLog } from '../utils/escape-text.js';
 import { isCanopyInternalPath } from '../utils/git.js';
 import { publishesBranch } from './branch-policy.js';
-import { buildMergeCommit, commitsApart, conflictFilesToContentIds, isCleanMergeOf, publishPlainToLocalRemote, recordConflicts, } from './branch-merge.js';
+import { commitMerge, commitsApart, isCleanMergeOf, planMerge, publishPlainToLocalRemote, } from './branch-merge.js';
 import { MAX_REPORTED_PATHS, RETIRED_SCHEMA_CACHE_PATH, TRACKED_CANOPY_STATE_FIX, } from './canopy-state.js';
 import { enqueueGitHubPush, readPublishedSha, recordSeenOnGitHub } from './history-rewrite.js';
 import { workerLog, workerLogWarn } from './log.js';
@@ -33,9 +35,38 @@ export function rewriteCleared(branch) {
         : { rewrittenOnGitHub: undefined, syncStatus: 'synced', syncFailureReason: undefined };
 }
 /** A branch this deployment put on GitHub. Any other GitHub branch of that name is not its own. */
-function isPublished({ branch }) {
+export function isPublished({ branch }) {
     return branch.pushedToGitHubAt !== undefined || branch.pullRequestNumber !== undefined;
 }
+/**
+ * Fast-forward the clone to the merge this worker was landing, when `remote.git` holds it on top of
+ * the clone, as a crash or a lost lock between publishing it and moving the clone leaves it,
+ * whether or not the branch is on GitHub. Resolves why it stopped, or null when there was nothing
+ * to catch up with or it caught up.
+ */
+export async function catchUpWithPublished(ctx, args) {
+    const { git, branchPath, branchRef } = args;
+    const published = await readPublishedSha(ctx, branchRef);
+    if (published === null)
+        return null;
+    // Only the merge this worker stamped as landing: `remote.git` can also hold a same-named branch,
+    // or a reviewer's commit, that it never wrote, which other steps judge.
+    const landing = await new MergeConflictStore(branchPath).read().then((record) => record?.landing?.mergeSha, () => undefined);
+    if (landing !== published)
+        return null;
+    const head = (await git.revparse(['HEAD'])).trim();
+    if (published === head)
+        return null;
+    if (!(await holdsCommit(git, published))) {
+        await fetchFromRemoteGit(git, ctx.remoteGitPath, `refs/heads/${branchRef}`);
+    }
+    const parents = (await git.raw(['rev-list', '--parents', '-n', '1', '--end-of-options', published]))
+        .trim()
+        .split(' ');
+    if (parents.length !== 3 || parents[1] !== head)
+        return null;
+    return fastForward(ctx, args, head, published);
+}
 /** Bring GitHub's commits into the clone. Throws what git throws; the caller records it. */
 export async function bringInGitHubCommits(ctx, args) {
     const { git, branchRef, metaFile, dirty, gatewayPolicy } = args;
@@ -291,6 +322,11 @@ async function fastForward(ctx, args, from, to) {
         return { kind: 'wait' };
     }
     workerLog(`  ${branchDir}: brought in commits from GitHub (now at ${to.slice(0, 7)})`);
+    // A merge this worker was landing, which the clone now holds, has landed.
+    const landing = await new MergeConflictStore(branchPath).read().then((record) => record?.landing?.mergeSha, () => undefined);
+    if (landing !== undefined && (await contains(git, to, landing))) {
+        await landed(ctx, args, landing).catch((err) => workerLogWarn(`  ${branchDir}: what a merge kept is noted on the next cycle: ${getErrorMessage(err)}`));
+    }
     return null;
 }
 /**
@@ -304,42 +340,48 @@ async function moveClone(git, branchPath, to) {
     await invalidateBranchContentCaches(branchPath);
 }
 /**
- * `other` merged into the branch: built, published to `remote.git`, queued for GitHub, and the
- * clone moved to it, in that order, so each step leaves what the next cycle picks up and only the
- * last touches the working tree. `fromGitHub` says `other` is GitHub's tip rather than the base.
- * `stopOnConflict` leaves a branch in review as it is: nobody is at the editor to see what a kept
- * version replaced, and GitHub's own conflict notice stands on the pull request.
+ * `other` merged into the branch: built, recorded, published to `remote.git`, queued for GitHub,
+ * and the clone moved to it, in that order, so each step leaves what the next cycle picks up and
+ * only the last touches the working tree. `fromGitHub` says `other` is GitHub's tip rather than the
+ * base. `inReview` takes only a merge with nothing for a person to choose; any other leaves the
+ * branch as it is and records nothing, and GitHub's own conflict notice stands on the pull request. A lock lost before the clone moves leaves it where it was: `wait`.
  */
 export async function mergeIntoBranch(ctx, args, merge) {
     const { git, branchPath, branchDir, branchRef, gatewayPolicy, lockLost } = args;
-    const { head, other, message, fromGitHub, stopOnConflict } = merge;
-    const built = await buildMergeCommit(git, branchPath, {
+    const { head, other, message, fromGitHub, inReview } = merge;
+    const plan = await planMerge(git, branchPath, {
         head,
         other,
-        message,
+        contentRoot: ctx.contentRoot,
         timeoutMs: ctx.taskTimeoutMs,
     });
-    if (stopOnConflict && (built.kind === 'unsettled' || built.conflicted.length > 0)) {
+    // Nobody is at the editor of a branch in review to choose: a value or file kept over the other
+    // side's change would stand unseen in the pull request. Held before any commit is written, as a
+    // branch can stay held for days.
+    if (inReview &&
+        (plan.kind === 'unsettled' || plan.conflicts.length > 0 || plan.keptPaths.length > 0)) {
         workerLog(`  ${branchDir}: conflicts with ${other.slice(0, 7)}, so it stays as it is`);
         return { kind: 'wait' };
     }
-    if (built.kind === 'unsettled') {
+    if (plan.kind === 'unsettled') {
         return {
             kind: 'blocked',
-            reason: `Git cannot merge ${other} into ${branchRef} by rule: ${built.conflicts.join(', ')}` +
-                `${built.paths.length > 0 ? ` (${listPaths(built.paths)})` : ''}. Nothing was changed. ` +
+            reason: `Git cannot merge ${other} into ${branchRef} by rule: ${plan.conflicts.join(', ')}` +
+                `${plan.paths.length > 0 ? ` (${listPaths(plan.paths)})` : ''}. Nothing was changed. ` +
                 `To continue, a developer merges them by hand.`,
         };
     }
-    const { sha, conflicted } = built;
+    const built = await commitMerge(git, plan, { head, other, message });
+    const { sha, conflicts } = built;
     const refused = await refuseIncoming(args, head, sha);
     if (refused)
         return refused;
     if (lockLost())
         return { kind: 'wait' };
-    if (fromGitHub && (await changesWhatWasReviewed(ctx, args, head, sha))) {
+    // A field merge of the base settles what git could not, which no reviewer has seen either.
+    // Approving waits for the content-write lock the caller holds, so none lands after this check.
+    if (await changesWhatWasReviewed(ctx, args, head, sha))
         await returnToReview(ctx, args);
-    }
     const published = await readPublishedSha(ctx, branchRef);
     const unpublishable = `This deployment's repository holds commits for ${branchRef} that neither this clone nor ` +
         `GitHub has, so a merge of the two cannot be published. Nothing was changed. Compare the ` +
@@ -348,9 +390,11 @@ export async function mergeIntoBranch(ctx, args, merge) {
         return { kind: 'blocked', reason: unpublishable };
     }
     // Recorded before the merge is visible anywhere: the next cycle only fast-forwards to it, and
-    // the conflicts cannot be read back from the merge.
-    if (conflicted.length > 0)
-        await recordKeptVersions(ctx, args, conflicted, fromGitHub);
+    // the conflicts cannot be read back from the merge. A merge that never lands leaves records the
+    // next cycle's reconcile turns back.
+    await recordMerge(ctx, args, built, { head, fromGitHub });
+    if (lockLost())
+        return { kind: 'wait' };
     // Before `remote.git` holds it, as reconcile does: a crash past this point leaves GitHub's commit
     // in `remote.git`, and a removal then has to read as one (`rewrittenFrom`).
     if (fromGitHub)
@@ -361,16 +405,20 @@ export async function mergeIntoBranch(ctx, args, merge) {
         }
         await enqueueGitHubPush(ctx, branchRef, gatewayPolicy);
     }
-    if (conflicted.length > 0 && fromGitHub) {
-        await enqueueReviewBlockSync(ctx, branchRef, args.metaFile);
-    }
+    // Published and not yet in the clone: the next cycle brings it in, by `bringInGitHubCommits` or
+    // `catchUpWithPublished`.
+    if (lockLost())
+        return { kind: 'wait' };
     await moveClone(git, branchPath, sha);
+    // Landed: a failure here leaves the remaps and the stamp for the next cycle's reconcile.
+    await landed(ctx, args, sha).catch((err) => workerLogWarn(`  ${branchDir}: what this merge kept is noted on the next cycle: ${getErrorMessage(err)}`));
     if (fromGitHub)
         await recordGitHubTip(ctx, args, other);
-    workerLog(conflicted.length > 0
-        ? `  ${branchDir}: merged ${other.slice(0, 7)} (kept this branch's version of ${conflicted.length} file(s))`
+    const keptEntries = new Set(conflicts.map(({ contentId }) => contentId)).size;
+    workerLog(keptEntries > 0
+        ? `  ${branchDir}: merged ${other.slice(0, 7)} (${keptEntries} entr${keptEntries === 1 ? 'y' : 'ies'} with values for a person to choose: ${listPaths(conflicts.map(({ path }) => path))})`
         : `  ${branchDir}: merged ${other.slice(0, 7)}`);
-    return { kind: 'merged' };
+    return { kind: 'merged', keptEntries };
 }
 /**
  * Whether this clone holds `sha`, on git's word for it. A killed `git` answers nothing at all,
@@ -396,7 +444,7 @@ async function holdsCommit(git, sha) {
  * failure throws, since it says nothing about either commit, and the caller's catch retries next
  * cycle: read as no, it would report a rewrite that never happened.
  */
-async function contains(git, commit, ancestor) {
+export async function contains(git, commit, ancestor) {
     if (!(await holdsCommit(git, commit)) || !(await holdsCommit(git, ancestor)))
         return false;
     return (await commitsApart(git, ancestor, commit)).onlyA === 0;
@@ -417,34 +465,226 @@ async function changesWhatWasReviewed(ctx, { git, branchPath }, from, to) {
     return forkPoint === '' || !(await isCleanMergeOf(git, to, from, forkPoint));
 }
 /**
- * Send an approved branch back to review and clear the verdict from the PR body. Before the clone
- * moves, and a failed save throws, so a crash or a failure leaves the commits for the next cycle
- * to judge again rather than an approval standing over them.
+ * Send an approved branch back to review and clear the verdict from the PR body. Called before the
+ * clone moves, where a failed save throws, so a crash or a failure leaves the commits for the next
+ * cycle to judge again rather than an approval standing over them.
  */
 export async function returnToReview(ctx, { branchPath, branchDir, branchRef, metaFile }) {
     const saved = await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).saveIf({ branch: { status: 'submitted', review: undefined } }, (current) => current?.branch.name === branchRef && current.branch.status === 'approved');
     if (saved === null)
         return;
-    workerLog(`  ${branchDir}: back in review, as commits from GitHub changed what was approved`);
+    workerLog(`  ${branchDir}: back in review, as what was approved changed`);
     await enqueueReviewBlockSync(ctx, branchRef, metaFile);
 }
-/** Record what a merge kept, for the editor and, for GitHub's commits, the PR body. */
-async function recordKeptVersions(ctx, { branchPath, branchRef }, conflicted, fromGitHub) {
-    const ids = conflictFilesToContentIds(conflicted, ctx.contentRoot);
-    await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).update((existing) => existing?.branch.name === branchRef
-        ? {
-            branch: {
-                ...recordConflicts(existing.branch.conflictFiles, ids),
-                ...(fromGitHub
-                    ? {
-                        keptOverGitHub: [
-                            ...new Set([...(existing.branch.keptOverGitHub ?? []), ...conflicted]),
-                        ],
-                    }
-                    : {}),
-            },
+/**
+ * Record what a merge left for a person in merge-conflicts.json, with the item keys it changed for
+ * the branch's comment threads to take once it lands and the merge as `landing`, and the content
+ * IDs it names in `branch.json` `conflictFiles`. The record is first settled against `head`, which
+ * the merge builds on, so a record of a merge that never landed can't carry into this one. Before
+ * the merge is visible: one that never lands leaves records the next
+ * {@link reconcileMergeConflicts} turns back.
+ */
+async function recordMerge(ctx, args, built, merge) {
+    const { git, branchPath, branchRef } = args;
+    const { sha, conflicts, keptPaths, keyRemaps, paths } = built;
+    const inHead = await settleRecord(git, branchPath, merge.head);
+    const state = await new MergeConflictStore(branchPath).update((current) => ({
+        entries: withFoundConflicts(withRemappedItemKeys(current ? withoutMergesGone(current.entries, inHead) : {}, keyRemaps, sha), conflicts, sha, paths),
+        remaps: [
+            ...(current?.remaps ?? []),
+            ...keyRemaps.map(({ entryPath, remaps }) => ({ mergeSha: sha, entryPath, remaps })),
+        ],
+        landing: {
+            mergeSha: sha,
+            ...(merge.fromGitHub && keptPaths.length > 0 && { keptOverGitHub: keptPaths }),
+        },
+    }));
+    if (state === null)
+        return;
+    await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).update((existing) => existing?.branch.name === branchRef ? { branch: conflictFilesOf(state.entries) } : null);
+}
+/**
+ * After the clone moved to `sha`, the merge being landed: the remaps of every merge it holds apply,
+ * in the order recorded, the paths it kept over GitHub's commits go in `keptOverGitHub` for the PR
+ * body, and it is no longer landing. A remap that fails waits for the next cycle, and keeps nothing
+ * else from being noted.
+ */
+async function landed(ctx, { git, branchPath, branchRef, branchDir, metaFile, }, sha) {
+    const store = new MergeConflictStore(branchPath);
+    const current = await store.read();
+    if (current === null)
+        return;
+    const [inSha] = await mergesHeld(git, current, [sha]);
+    await applyRemaps(branchPath, (mergeSha) => inSha.has(mergeSha)).catch((err) => workerLogWarn(`  ${branchDir}: comment threads keep their item keys for now: ${getErrorMessage(err)}`));
+    const landing = current.landing;
+    if (landing?.mergeSha !== sha)
+        return;
+    const kept = landing.keptOverGitHub ?? [];
+    if (kept.length > 0) {
+        await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).update((existing) => existing?.branch.name === branchRef
+            ? {
+                branch: {
+                    keptOverGitHub: [...new Set([...(existing.branch.keptOverGitHub ?? []), ...kept])],
+                },
+            }
+            : null);
+        await enqueueReviewBlockSync(ctx, branchRef, metaFile);
+    }
+    await store.update((now) => {
+        if (now?.landing?.mergeSha !== sha)
+            return null;
+        const { landing: _done, ...rest } = now;
+        return rest;
+    });
+}
+/** Every merge a record names, its earlier versions' included. */
+function mergesNamedBy(entry) {
+    return [
+        entry.mergeSha,
+        ...(entry.fields ?? []).map((f) => f.mergeSha),
+        ...(entry.previous ? mergesNamedBy(entry.previous) : []),
+    ];
+}
+/** The merges merge-conflicts.json names, and which of them each of `tips` holds. */
+async function mergesHeld(git, state, tips) {
+    const shas = new Set([
+        ...Object.values(state.entries).flatMap(mergesNamedBy),
+        ...(state.remaps ?? []).map(({ mergeSha }) => mergeSha),
+        ...(state.landing ? [state.landing.mergeSha] : []),
+    ]);
+    const held = tips.map(() => new Set());
+    for (const sha of shas) {
+        for (const [n, tip] of tips.entries()) {
+            if (await contains(git, tip, sha))
+                held[n].add(sha);
         }
-        : null);
+    }
+    return held;
+}
+/**
+ * The record as `head` has it: comment threads take the item keys of merges `head` holds, other
+ * merges' remaps go, and records changed by merges it lacks give back the ones they replaced.
+ * Resolves whether `head` holds a merge the record named then; a merge recorded since counts as
+ * held, as nothing settled it.
+ */
+async function settleRecord(git, branchPath, head) {
+    const store = new MergeConflictStore(branchPath);
+    const current = await store.read();
+    if (current === null)
+        return () => true;
+    const [held] = await mergesHeld(git, current, [head]);
+    const known = new Set([
+        ...Object.values(current.entries).flatMap(mergesNamedBy),
+        ...(current.remaps ?? []).map(({ mergeSha }) => mergeSha),
+    ]);
+    const inHead = (sha) => held.has(sha) || !known.has(sha);
+    // The threads can wait: the remaps stay for the next cycle.
+    await applyRemaps(branchPath, inHead, (sha) => !inHead(sha)).catch((err) => workerLogWarn(`  comment threads keep their item keys for now: ${getErrorMessage(err)}`));
+    return inHead;
+}
+/**
+ * Point the branch's comment threads at the item keys the merges in `landed` gave their items, in
+ * the order they were recorded, then drop those remaps from the record, and those `gone` names
+ * unapplied.
+ */
+async function applyRemaps(branchPath, landed, gone = () => false) {
+    const store = new MergeConflictStore(branchPath);
+    const pending = (await store.read())?.remaps ?? [];
+    const due = pending.filter(({ mergeSha }) => landed(mergeSha));
+    if (due.length === 0 && !pending.some(({ mergeSha }) => gone(mergeSha)))
+        return;
+    const comments = new CommentStore(branchPath);
+    for (const { entryPath, remaps } of due)
+        await comments.remapItemKeys(entryPath, remaps);
+    await store.update((current) => current && {
+        ...current,
+        remaps: (current.remaps ?? []).filter(({ mergeSha }) => !landed(mergeSha) && !gone(mergeSha)),
+    });
+}
+/** `branch.json` `conflictFiles` as `entries` has them, written only when the two differ. */
+async function followRecord(ctx, branchPath, branchDir, branchRef, entries) {
+    const { conflictFiles, conflictStatus } = conflictFilesOf(entries);
+    const same = (ids) => JSON.stringify([...(ids ?? [])].sort()) === JSON.stringify(conflictFiles);
+    // Read first: the locked update costs every branch a lock each cycle, and nearly all agree.
+    const read = (await BranchMetadataFileManager.loadOnly(branchPath))?.branch;
+    if (read === undefined || (branchRef !== null && read.name !== branchRef))
+        return;
+    if (same(read.conflictFiles))
+        return;
+    const saved = await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).update((existing) => existing !== null &&
+        (branchRef === null || existing.branch.name === branchRef) &&
+        !same(existing.branch.conflictFiles)
+        ? { branch: { conflictFiles, conflictStatus } }
+        : null, { keepUpdatedAt: true });
+    if (saved)
+        workerLog(`  ${branchDir}: ${conflictFiles.length} entries with conflicts on record`);
+}
+/**
+ * Bring merge-conflicts.json in line with the branch's history: a record changed by a merge the
+ * branch never got gives back the one it replaced (`withoutMergesGone`), and `branch.json`
+ * `conflictFiles` follows the record when the two differ. A merge counts as held while the clone or
+ * `remote.git` holds it, since a clone behind its published merge catches up with it; comment
+ * threads take a merge's item keys only once the clone holds it. While either can't be read in the
+ * clone, nothing is judged. A record that does not parse is moved aside, so the branch's merges
+ * carry on with a new one. Each cycle, before the branch takes anything in. A clone with no record
+ * has no conflict open, so `conflictFiles` written before the record existed clears. Never throws.
+ */
+export async function reconcileMergeConflicts(ctx, { git, branchPath, branchDir, branchRef, }) {
+    try {
+        const store = new MergeConflictStore(branchPath);
+        let current;
+        try {
+            current = await store.read();
+        }
+        catch (err) {
+            if (!(err instanceof MergeConflictsFileMalformedError))
+                throw err;
+            const aside = await store.quarantine();
+            if (aside !== null) {
+                workerLogWarn(`  ${branchDir}: its conflict record does not parse; copied it to ${aside}`);
+            }
+            // The held record, or one another writer left in its place.
+            current = await store.read();
+        }
+        if (current === null) {
+            await followRecord(ctx, branchPath, branchDir, branchRef, {});
+            return;
+        }
+        const published = branchRef === null ? null : await readPublishedSha(ctx, branchRef);
+        if (published !== null && !(await holdsCommit(git, published))) {
+            await fetchFromRemoteGit(git, ctx.remoteGitPath, `refs/heads/${branchRef}`);
+        }
+        const tips = ['HEAD', ...(published === null ? [] : [published])];
+        for (const tip of tips)
+            if (!(await holdsCommit(git, tip)))
+                return;
+        const [inHead, inPublished = new Set()] = await mergesHeld(git, current, tips);
+        const held = (sha) => inHead.has(sha) || inPublished.has(sha);
+        const entries = (await store.update((now) => {
+            if (now === null)
+                return null;
+            const kept = withoutMergesGone(now.entries, held);
+            const { landing, ...rest } = now;
+            // A clone catches up only with a merge `remote.git` holds; one it holds lands below.
+            // Without `remote.git`'s head to read, a published merge can't be told from a lost one.
+            const stays = landing !== undefined && (branchRef === null || held(landing.mergeSha));
+            if (JSON.stringify(kept) === JSON.stringify(now.entries) && (stays || !landing)) {
+                return null;
+            }
+            return { ...rest, entries: kept, ...(stays && { landing }) };
+        }))?.entries ?? current.entries;
+        await followRecord(ctx, branchPath, branchDir, branchRef, entries);
+        await applyRemaps(branchPath, (sha) => inHead.has(sha), (sha) => !held(sha));
+        if (current.landing && inHead.has(current.landing.mergeSha) && branchRef !== null) {
+            const metaFile = await BranchMetadataFileManager.loadOnly(branchPath);
+            if (metaFile) {
+                await landed(ctx, { git, branchPath, branchRef, branchDir, metaFile }, current.landing.mergeSha);
+            }
+        }
+    }
+    catch (err) {
+        workerLogWarn(`  ${branchDir}: could not reconcile its conflict record: ${getErrorMessage(err)}`);
+    }
 }
 /**
  * Re-render the PR body's review block alone: the worker has no `config.editorUrl`, so a full

package/dist/worker/github-gateway-http.js

@@ -219,9 +219,9 @@ class GatewayRequestHandler {
                 return {};
             },
             getPullRequest: async ({ number }, signal) => {
-                const { merged, merged_at, state, node_id, body, mergeable_state, baseRef } = await gateway.getPullRequest(number, signal);
+                const { merged, merged_at, state, node_id, body, mergeable_state, baseRef, headSha } = await gateway.getPullRequest(number, signal);
                 // A null body is the gateway withholding it (`GitHubPullRequest.body`), and crosses as one.
-                return { merged, merged_at, state, node_id, body, mergeable_state, baseRef };
+                return { merged, merged_at, state, node_id, body, mergeable_state, baseRef, headSha };
             },
             createOrUpdatePullRequest: async (input, signal) => {
                 const { number, url, created } = await gateway.createOrUpdatePullRequest(input, signal);
@@ -409,7 +409,7 @@ class GatewayRequestHandler {
     }
     async startFetch(req, res) {
         await this.prepared;
-        const { have } = parseRequest(fetchRequest, await readJsonBody(req), 'fetch');
+        const { have, fresh } = parseRequest(fetchRequest, await readJsonBody(req), 'fetch');
         this.evictJobs();
         const running = [...this.jobs.values()].filter((job) => job.settledAt === null).length;
         if (running >= MAX_RUNNING_FETCH_JOBS) {
@@ -434,13 +434,19 @@ class GatewayRequestHandler {
             progress: 0,
             // No signal: the job outlives the request that started it (see the module doc).
             settled: this.gateway
-                .fetch({ have }, undefined, () => {
+                .fetch({ have, fresh }, undefined, () => {
                 job.progress++;
             })
-                .then(({ refs, bundleId }) => {
+                .then(({ refs, bundleId, startedAt }) => {
                 job.answer = {
                     ok: true,
-                    value: { state: 'done', progress: job.progress, refs: [...refs], bundleId },
+                    value: {
+                        state: 'done',
+                        progress: job.progress,
+                        refs: [...refs],
+                        bundleId,
+                        startedAt,
+                    },
                 };
             }, (err) => {
                 job.answer = { ok: false, error: encodeError(err) };
@@ -703,11 +709,12 @@ class GitHubGatewayClient {
      */
     async fetch(request, signal, onProgress) {
         const have = [...new Set(request.have)];
+        const json = { have, fresh: request.fresh === true };
         for (let attempt = 1;; attempt++) {
             const started = await this.send({
                 method: 'POST',
                 path: FETCH_ROUTE,
-                json: { have },
+                json,
                 signal,
             });
             const { job } = await readAnswer(started, fetchStarted, signal);
@@ -754,8 +761,9 @@ class GitHubGatewayClient {
                 progress = poll.progress;
                 movedAt = performance.now();
             }
-            if (poll.state === 'done')
-                return { refs: new Map(poll.refs), bundleId: poll.bundleId };
+            if (poll.state === 'done') {
+                return { refs: new Map(poll.refs), bundleId: poll.bundleId, startedAt: poll.startedAt };
+            }
             if (performance.now() - movedAt >= this.fetchInactivityMs) {
                 throw new GitHubTransientError('github-fetch-failed', `The GitHub gateway's fetch showed no progress for ${this.fetchInactivityMs}ms; it runs on, ` +
                     'and the next fetch joins it');