canopycms 0.12.0 → 0.13.0

package/dist/worker/github-commits.js

@@ -1,17 +1,20 @@
 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 { buildRekey, 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';
-import { assertNoIncomingSubmodules, fetchFromRemoteGit } from './shared-repo-git.js';
+import { decidePublish } from './publish-decision.js';
+import { SHARED_REPO_STATUS_ARGS, assertNoIncomingSubmodules, fetchFromRemoteGit, } from './shared-repo-git.js';
 export const COMMIT_ID = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
 const MAX_LISTED_PATH_LENGTH = 200;
 /** Why a push was refused while a rewrite stands (task-runner.ts); editors read it as a failed sync. */
@@ -33,9 +36,41 @@ 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(' ');
+    // A merge built on the clone's head, or a re-key built on GitHub's commits past it.
+    const builtOnHead = parents.length === 3 && parents[1] === head;
+    const rekeyPastHead = parents.length === 2 && (await contains(git, published, head));
+    if (!builtOnHead && !rekeyPastHead)
+        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;
@@ -93,6 +128,12 @@ export async function bringInGitHubCommits(ctx, args) {
     // below builds on remote.git's head whenever it can.
     if (published !== null && published !== head) {
         if ((await commitsApart(git, head, published)).onlyA === 0) {
+            // GitHub's commits, which reconcile moved `remote.git` to, come in re-keyed where they need it.
+            if (gitHubTip === published) {
+                const rekeyed = await rekeyTakenIn(ctx, args, head, published);
+                if (rekeyed)
+                    return rekeyed;
+            }
             const stopped = await fastForward(ctx, args, head, published);
             if (stopped)
                 return stopped;
@@ -285,61 +326,184 @@ async function fastForward(ctx, args, from, to) {
         await moveClone(git, branchPath, to);
     }
     catch (err) {
-        if (!/would be overwritten/.test(getErrorMessage(err)))
+        if (!overwritesSaves(err))
             throw err;
         workerLog(`  ${branchDir}: local changes overlap commits from GitHub, which wait for a submit`);
         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;
 }
+/**
+ * GitHub's commits brought in under the item keys a field merge gives, where a merge among them
+ * left an item under a key that names another item (branch-merge.ts `buildRekey`): one commit on
+ * `tip`, recorded, published and moved to in {@link mergeIntoBranch}'s order, its remaps moving the
+ * branch's comment threads once it lands. Null, for the caller to fast-forward to `tip` as git
+ * keyed it, where no item needs a new key, where the commit could not be published (gateway policy,
+ * {@link decidePublish}, a `remote.git` head it doesn't contain), or where the clone's saves would
+ * keep the clone from moving to it ({@link savesMeet}).
+ */
+async function rekeyTakenIn(ctx, args, head, tip) {
+    const { git, branchPath, branchDir, branchRef, gatewayPolicy, lockLost } = args;
+    if (gatewayPolicy && !publishesBranch(gatewayPolicy, branchRef))
+        return null;
+    const published = await readPublishedSha(ctx, branchRef);
+    if ((await decidePublish(git, { head, published })).kind !== 'publish')
+        return null;
+    const built = await rekeyOf(ctx, args, head, tip);
+    if (built === null)
+        return null;
+    const { sha } = built;
+    // A re-key the clone can't move to stays unpublished; the commits come in once the saves do.
+    if (args.dirty && (await savesMeet(git, head, sha)))
+        return null;
+    if (published !== null && !(await contains(git, sha, published)))
+        return null;
+    const refused = await refuseIncoming(args, head, sha);
+    if (refused)
+        return refused;
+    if (lockLost())
+        return { kind: 'wait' };
+    // Judged on content: the commit changes item keys only, which `isCleanMergeOf` sets aside.
+    if (await changesWhatWasReviewed(ctx, args, head, sha))
+        await returnToReview(ctx, args);
+    await recordMerge(ctx, args, built, { head, also: tip, fromGitHub: true });
+    if (lockLost())
+        return { kind: 'wait' };
+    await recordSeenOnGitHub(ctx, branchRef, tip);
+    if (!(await publishPlainToLocalRemote(ctx, branchPath, branchRef, sha)))
+        return { kind: 'wait' };
+    await enqueueGitHubPush(ctx, branchRef, gatewayPolicy);
+    if (lockLost())
+        return { kind: 'wait' };
+    try {
+        await moveClone(git, branchPath, sha);
+    }
+    catch (err) {
+        if (!overwritesSaves(err))
+            throw err;
+        // Unreached: `savesMeet` looked under the content-write lock this cycle still holds.
+        workerLog(`  ${branchDir}: local changes overlap commits from GitHub, which wait for a submit`);
+        return { kind: 'wait' };
+    }
+    await landed(ctx, args, sha).catch((err) => workerLogWarn(`  ${branchDir}: what this re-key moves is noted on the next cycle: ${getErrorMessage(err)}`));
+    await recordGitHubTip(ctx, args, tip);
+    workerLog(`  ${branchDir}: brought in commits from GitHub, with the items its merges brought in keyed anew (now at ${sha.slice(0, 7)})`);
+    return { kind: 'merged', keptEntries: 0 };
+}
+/** {@link buildRekey} on GitHub's commits from `head` to `tip`, or null when none needs a new key. */
+function rekeyOf(ctx, { git, branchPath, branchRef }, head, tip, unchangedIn) {
+    return buildRekey(git, branchPath, {
+        from: head,
+        tip,
+        contentRoot: ctx.contentRoot,
+        timeoutMs: ctx.taskTimeoutMs,
+        message: `Key the items that merges on GitHub brought into ${branchRef}`,
+        ...(unchangedIn && { unchangedIn }),
+    });
+}
+/**
+ * Whether the clone's saves (changes, deletions, new files) touch a path `from..to` changes: the
+ * clone can't move to `to` until they are committed, and that commit merges against `from`'s keys.
+ */
+async function savesMeet(git, from, to) {
+    const saved = new Set((await git.status([...SHARED_REPO_STATUS_ARGS])).files.flatMap((f) => f.from ? [f.path, f.from] : [f.path]));
+    const changed = (await git.raw(['diff-tree', '-r', '-z', '--name-only', '--end-of-options', from, to]))
+        .split('\0')
+        .filter(Boolean);
+    return changed.some((file) => saved.has(file));
+}
+/** A move of the clone refused for saves it would overwrite, as git refuses a changed file. */
+class SavesInTheWay extends Error {
+}
+/** Whether `err` is a move refused for the clone's saves: git's own refusal, or {@link moveClone}'s. */
+const overwritesSaves = (err) => err instanceof SavesInTheWay || /would be overwritten/.test(getErrorMessage(err));
 /**
  * Fast-forward the clone to `to`. The caches' markers move after it, as for any bulk mutation, and
  * before it too: nothing repairs a marker lost after the move, as the next cycle sees a clone in
- * step, and the earlier bump leaves only a read racing the move able to stamp the old tree.
+ * step, and the earlier bump leaves only a read racing the move able to stamp the old tree. Git
+ * refuses to move over a saved change to a file the commits change, but writes a file deleted in
+ * the working tree back: an entry the editor deleted, or a renamed entry's old path. So a move over
+ * such a deletion is refused here alike ({@link SavesInTheWay}), until the deletion is submitted.
  */
 async function moveClone(git, branchPath, to) {
+    const deleted = (await git.status([...SHARED_REPO_STATUS_ARGS])).files.flatMap((f) => [
+        ...(f.working_dir === 'D' || f.index === 'D' ? [f.path] : []),
+        ...(f.from ? [f.from] : []),
+    ]);
+    if (deleted.some((file) => !isCanopyInternalPath(file))) {
+        const changed = new Set((await git.raw(['diff-tree', '-r', '-z', '--name-only', '--end-of-options', 'HEAD', to]))
+            .split('\0')
+            .filter(Boolean));
+        const lost = deleted.filter((file) => changed.has(file) && !isCanopyInternalPath(file));
+        if (lost.length > 0) {
+            throw new SavesInTheWay(`saved deletions would be brought back: ${listPaths(lost)}`);
+        }
+    }
     await invalidateBranchContentCaches(branchPath);
     await git.raw(['merge', '--ff-only', '--end-of-options', 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` and queued for GitHub
+ * unless it holds unsubmitted work (publish-decision.ts), 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;
+    // GitHub's merges come in under the field merge's keys, as a fast-forward takes them in, for the
+    // entries the merge takes from GitHub whole: one the branch changed too merges by git's keys.
+    const bases = fromGitHub
+        ? (await git.raw(['merge-base', '--all', '--end-of-options', head, other]))
+            .split('\n')
+            .filter((line) => COMMIT_ID.test(line))
+        : [];
+    // With one merge base, as the field merge needs; none or several leave git's merge as it is.
+    const rekey = bases.length === 1 ? await rekeyOf(ctx, args, head, other, { head, since: bases[0] }) : null;
+    const into = rekey?.sha ?? other;
+    const plan = await planMerge(git, branchPath, {
         head,
-        other,
-        message,
+        other: into,
+        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 merged = await commitMerge(git, plan, { head, other: into, message });
+    // The re-key's remaps cover entries the branch left alone, the merge's those both changed.
+    const built = rekey ? { ...merged, keyRemaps: [...rekey.keyRemaps, ...merged.keyRemaps] } : merged;
+    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,29 +512,49 @@ 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 && { also: other }), 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)
         await recordSeenOnGitHub(ctx, branchRef, other);
-    if (published !== null) {
+    const publish = await decidePublish(git, { head, published });
+    if (publish.kind === 'publish') {
         if (!(await publishPlainToLocalRemote(ctx, branchPath, branchRef, sha))) {
             return { kind: 'blocked', reason: unpublishable };
         }
         await enqueueGitHubPush(ctx, branchRef, gatewayPolicy);
     }
-    if (conflicted.length > 0 && fromGitHub) {
-        await enqueueReviewBlockSync(ctx, branchRef, args.metaFile);
+    else if (publish.kind === 'hold') {
+        workerLog(`  ${branchDir}: holds work not yet submitted, so the merge stays unpublished`);
     }
-    await moveClone(git, branchPath, sha);
+    // Published and not yet in the clone: the next cycle brings it in, by `bringInGitHubCommits` or
+    // `catchUpWithPublished`.
+    if (lockLost())
+        return { kind: 'wait' };
+    try {
+        await moveClone(git, branchPath, sha);
+    }
+    catch (err) {
+        if (!overwritesSaves(err))
+            throw err;
+        // Callers move a clean tree. Published, the next cycle catches up with it once the saves are
+        // committed; held, reconcile turns it back.
+        workerLog(`  ${branchDir}: local changes overlap the merge, which waits for a submit`);
+        return { kind: 'wait' };
+    }
+    // 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,55 +580,263 @@ 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;
 }
 /**
- * Whether moving an approved branch from `from` to `to` changes what was approved: yes unless `to`
- * is exactly `from` with the base up to where `to` has it, which leaves the pull request's diff as
- * it was reviewed. A hand-made change inside a merge commit therefore counts. Read fresh, so an
- * approval given since the cycle's start counts too.
+ * Whether moving an approved branch to `to` changes what was approved: yes unless `to` is exactly
+ * the approved commit with the base up to where `to` has it, which leaves the pull request's diff
+ * as it was reviewed. The approved commit is the one the approval recorded, so clean merges since
+ * it are judged together; `from`, the head before this move, stands in for an approval that
+ * recorded none. A recorded commit this clone doesn't hold counts as a change, as does a
+ * hand-made change inside a merge commit. Read fresh, so an approval given since the cycle's
+ * start counts too.
  */
 async function changesWhatWasReviewed(ctx, { git, branchPath }, from, to) {
     const fresh = (await BranchMetadataFileManager.loadOnly(branchPath))?.branch;
     if (fresh?.status !== 'approved')
         return false;
+    const approved = fresh.review?.commit ?? from;
+    if (!(await holdsCommit(git, approved)))
+        return true;
     await fetchFromRemoteGit(git, ctx.remoteGitPath, fresh.baseBranch ?? ctx.baseBranch);
     const base = (await git.revparse(['FETCH_HEAD'])).trim();
     const forkPoint = (await git.raw(['merge-base', '--end-of-options', to, base])).trim();
-    return forkPoint === '' || !(await isCleanMergeOf(git, to, from, forkPoint));
+    return forkPoint === '' || !(await isCleanMergeOf(git, to, approved, forkPoint, ctx.contentRoot));
 }
 /**
- * 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);
+/**
+ * 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. A merge `also` holds, GitHub's tip the merge takes in,
+ * is landing rather than gone. An earlier landing either commit holds is published, and this one
+ * replaces it: what it kept over GitHub's commits is noted for the pull request body now.
+ */
+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, merge.also);
+    const earlier = (await new MergeConflictStore(branchPath).read())?.landing;
+    if (earlier && earlier.mergeSha !== sha && inHead(earlier.mergeSha)) {
+        await noteKeptOverGitHub(ctx, args, earlier.keptOverGitHub ?? []);
+    }
+    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;
+    await noteKeptOverGitHub(ctx, { branchPath, branchRef, metaFile }, landing.keptOverGitHub ?? []);
+    await store.update((now) => {
+        if (now?.landing?.mergeSha !== sha)
+            return null;
+        const { landing: _done, ...rest } = now;
+        return rest;
+    });
+}
+/** `kept`, paths a merge kept over GitHub's commits, in `keptOverGitHub` for the PR body. */
+async function noteKeptOverGitHub(ctx, { branchPath, branchRef, metaFile, }, kept) {
+    if (kept.length === 0)
+        return;
     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]),
-                        ],
-                    }
-                    : {}),
+                keptOverGitHub: [...new Set([...(existing.branch.keptOverGitHub ?? []), ...kept])],
             },
         }
         : null);
+    await enqueueReviewBlockSync(ctx, branchRef, metaFile);
+}
+/** 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);
+        }
+    }
+    return held;
+}
+/**
+ * The record as `head` has it, or `also` with it: comment threads take the item keys of merges
+ * `head` holds, the remaps of merges neither holds go, and records changed by merges neither holds
+ * give back the ones they replaced. Resolves whether either holds a merge the record named then; a
+ * merge recorded since counts as held, as nothing settled it.
+ */
+async function settleRecord(git, branchPath, head, also) {
+    const store = new MergeConflictStore(branchPath);
+    const current = await store.read();
+    if (current === null)
+        return () => true;
+    const [held, alsoHeld] = await mergesHeld(git, current, also ? [head, also] : [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);
+    const kept = (sha) => inHead(sha) || (alsoHeld?.has(sha) ?? false);
+    // Threads move only to merges the clone holds; the rest wait, unless neither commit holds them.
+    await applyRemaps(branchPath, inHead, (sha) => !kept(sha)).catch((err) => workerLogWarn(`  comment threads keep their item keys for now: ${getErrorMessage(err)}`));
+    return kept;
+}
+/**
+ * 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-errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reading a GitHub API failure as the gateway passes it on: an Octokit error in-process, or the
+ * wire's `GitHubRequestError`, both carrying `status` and the response headers that classify it.
+ */
+/** Extract an HTTP status from an error, if present (Octokit RequestError shape). */
+export declare function getHttpStatus(err: unknown): number | null;
+/**
+ * Whether a 403 is a GitHub rate-limit response rather than a plain permission
+ * denial. GitHub signals rate limiting on 403s three ways: the primary limit
+ * zeroes `x-ratelimit-remaining`, secondary limits often carry `retry-after`,
+ * and both produce a message containing "rate limit".
+ */
+export declare function isRateLimitSignal403(err: unknown): boolean;
+/** A 403 that is GitHub denying the credential the operation, not a rate limit. */
+export declare function isPermissionDenial(err: unknown): boolean;