canopycms 0.8.1 → 0.8.3

package/dist/worker/git-sync.js

@@ -13,7 +13,7 @@ import { getErrorMessage, isNodeError, redactCredentials } from '../utils/error.
 import { escapeForLog } from '../utils/escape-text.js';
 import { CANOPY_META_DIR, isCanopyInternalPath, isNonFastForwardRejection } from '../utils/git.js';
 import { MAX_REPORTED_PATHS, TRACKED_CANOPY_STATE_FIX, isUntracked, listTrackedCanopyState, restoreRetiredSchemaCache, splitByUpstreamTracking, untrackInIndex, } from './canopy-state.js';
-import { hasPendingHistoryRewrite } from './history-rewrite.js';
+import { hasPendingHistoryRewrite, recordSeenOnGitHub } from './history-rewrite.js';
 import { runRebaseCycle } from './rebase.js';
 import { describeMove } from './github-gateway.js';
 import { fetchGitHubIntoRemoteGit, pushToGitHub } from './github-transfer.js';
@@ -145,7 +145,7 @@ export async function pushSettingsBranches(ctx, git, trackedTips) {
  * stale copy of a branch rebased and force-pushed on GitHub, and is moved to GitHub's tip
  * (`repointed`); one holding editor work is a real collision (another deployment moved the same
  * branch name, or GitHub's branch was rewritten under an editor's work), never resolved by picking
- * a winner: it stays `diverged`, and the next push is rejected non-fast-forward.
+ * a winner: it stays `diverged`, and github-commits.ts decides whether a merge can reconcile it.
  *
  * A head GitHub has no branch for is deleted through the same function when it holds no editor work
  * and shares history with the base (`pruned`), and only when GitHub's answer names the base branch:
@@ -277,13 +277,16 @@ async function reconcileTrackedBranches(ctx, git, githubTips) {
                     }
                 }
                 try {
+                    if (name !== ctx.baseBranch)
+                        await recordSeenOnGitHub(ctx, name, trackedSha);
                     await git.raw(['update-ref', '--no-deref', localRef, trackedSha, localSha]);
                     fastForwarded.push(name);
                 }
                 catch (err) {
-                    // Concurrent Lambda push moved the ref since the read above --
-                    // the guard did its job; this branch is simply revisited next cycle.
-                    workerLogWarn(`  Tracked-branch reconcile: failed to fast-forward ${escapeForLog(name)} (concurrent update?): ${escapeForLog(getErrorMessage(err))}`);
+                    // Concurrent Lambda push moved the ref since the read above -- the guard did its job
+                    // -- or the record couldn't be written. Either way the ref stays, and this branch is
+                    // simply revisited next cycle.
+                    workerLogWarn(`  Tracked-branch reconcile: failed to fast-forward ${escapeForLog(name)} (concurrent update, or its branch.json?): ${escapeForLog(getErrorMessage(err))}`);
                 }
             }
             else if (localBehindCount === 0 && localAheadCount > 0) {
@@ -390,8 +393,8 @@ function divergedWarning({ name, local, github, state, error }) {
         said: `${local} ${github} ${state}`,
         line: `  Tracked-branch reconcile: ${escapeForLog(name)} diverged from GitHub and was left untouched, ` +
             `because ${EDITOR_STATE_WORDS[state]}${error === undefined ? '' : ` (${escapeForLog(error)})`} ` +
-            `(here ${local}, GitHub ${github}). Publishing it fails until the two are reconciled; ` +
-            `System health lists it.`,
+            `(here ${local}, GitHub ${github}). The next rebase cycle merges commits added on GitHub; ` +
+            `otherwise publishing it fails until the two are reconciled. System health lists it.`,
     };
 }
 /**
@@ -464,6 +467,7 @@ export async function syncGit(ctx) {
         // deadline: the wait for the gateway's GitHub fetch, which runs on detached, then the gateway's
         // bundle, the unbundle and the ref update; a killed ref update leaves each ref as it was or
         // fully moved.
+        const fetchedAt = Date.now();
         const { refs: githubTips, needsOperator } = await fetchGitHubIntoRemoteGit(ctx, ctx.shutdownSignal());
         workerLog('Fetched from GitHub');
         if (needsOperator !== null)
@@ -507,7 +511,10 @@ export async function syncGit(ctx) {
             report.gatewayProtectedBranches = branchPolicy.configured.filter((n) => !n.includes('*'));
             await writeWorkerStatus(ctx.taskDir, report).catch((writeErr) => workerLogError('Failed to write worker status:', getErrorMessage(writeErr)));
         }
-        const rebaseSummary = await runRebaseCycle(ctx, branchPolicy);
+        const rebaseSummary = await runRebaseCycle(ctx, branchPolicy, {
+            tips: githubTips,
+            fetchedAt,
+        });
         if (stoppedForDrain(ctx, 'the cleanup sweeps'))
             return;
         await cleanupOldTasks(ctx.taskDir, undefined, ctx.log);

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

@@ -0,0 +1,106 @@
+import type { SimpleGit } from 'simple-git';
+import { type BranchMetadataFile } from '../branch-metadata.js';
+import type { BranchMetadata } from '../types.js';
+import { type BranchPolicyDescription } from './branch-policy.js';
+import type { WorkerContext } from './worker-context.js';
+/**
+ * Commits that reach a branch on GitHub without passing through its clone: Update branch, a
+ * maintainer's fix, or a push this worker made. `reconcileTrackedBranches` fast-forwards
+ * `remote.git` to them, but branch clones never fetch their own branch, so without this step the
+ * clone's next rebase or commit diverges from `remote.git` and every submit after that is refused.
+ *
+ * Runs once per cycle for every branch this deployment has published, in every status but
+ * archived, under the provisioning and content-write locks the caller holds, ahead of the rebase.
+ * It never forces anything: a clone behind GitHub fast-forwards, and a clone with commits GitHub
+ * lacks gets a real merge (branch-merge.ts), which keeps every commit on both sides.
+ *
+ * Two commits are compared. `remote.git`'s head is what the clone must contain for its next push,
+ * and it stays behind GitHub only while a head is diverged; GitHub's tip, from this cycle's fetch,
+ * is the one a diverged head is reconciled against.
+ *
+ * A merge commit in a branch's history, or a commit touching canopycms state, is why the rebase
+ * loop merges base into it rather than rebasing (rebase.ts): `git rebase` drops merge commits, and
+ * with them whatever they settled, and replays commits over the live files.
+ */
+export type GitHubCommitsContext = Pick<WorkerContext, 'baseBranch' | 'contentBranchesPath' | 'contentRoot' | 'remoteGitPath' | 'taskDir' | 'taskTimeoutMs' | 'ensureStatusReport'>;
+/** GitHub's branches as a sync cycle's fetch reported them, and when that fetch began. */
+export interface GitHubSnapshot {
+    tips: ReadonlyMap<string, string>;
+    fetchedAt: number;
+}
+export type GitHubCommitsOutcome = 
+/** GitHub's commits are in the clone, or there are none to bring in. */
+{
+    kind: 'in-step';
+}
+/** Looked at again next cycle. Nothing else in this cycle may move the branch. */
+ | {
+    kind: 'wait';
+}
+/**
+ * `remote.git` holds commits GitHub lacks, whose push failed for good. A rebase would replace
+ * commits GitHub never received, so the base comes in by a merge, which keeps them.
+ */
+ | {
+    kind: 'unpushed';
+}
+/** A merge landed. A rebase now would replace a merge GitHub has not received. */
+ | {
+    kind: 'merged';
+}
+/** Left as it is until a person acts. `reason` says what to do. */
+ | {
+    kind: 'blocked';
+    reason: string;
+};
+export interface GitHubCommitsArgs {
+    git: SimpleGit;
+    branchPath: string;
+    branchDir: string;
+    branchRef: string;
+    metaFile: BranchMetadataFile;
+    gitHub: GitHubSnapshot | undefined;
+    /** Whether the working tree holds saves, which only a fast-forward can pass. */
+    dirty: boolean;
+    gatewayPolicy: BranchPolicyDescription | undefined;
+    /** Whether a lock the caller holds was lost; checked before each step that moves a ref. */
+    lockLost: () => boolean;
+}
+export declare const COMMIT_ID: RegExp;
+/** Why a push was refused while a rewrite stands (task-runner.ts); editors read it as a failed sync. */
+export declare const REWRITTEN_PUSH_REFUSAL = "This branch was changed on GitHub in a way CanopyCMS can't combine with the work here, so nothing was pushed. Nothing is lost.";
+/** Why a push was refused before any sync had seen the rewrite (task-runner.ts). */
+export declare const SEEN_COMMIT_GONE_PUSH_REFUSAL = "A commit this branch had on GitHub is no longer there, so nothing was pushed. Nothing is lost.";
+/**
+ * What clears a rewrite: the flag, and the refusal's text, which would go on saying the work can't
+ * be combined. The failed sync it left goes too, unless {@link awaitsSubmitRetry}.
+ */
+export declare function rewriteCleared(branch: BranchMetadata): Partial<BranchMetadata>;
+/** 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.
+ */
+export declare function mergeIntoBranch(ctx: GitHubCommitsContext, args: GitHubCommitsArgs, merge: {
+    head: string;
+    other: string;
+    message: string;
+    fromGitHub: boolean;
+    stopOnConflict?: 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.
+ */
+export declare function returnToReview(ctx: GitHubCommitsContext, { branchPath, branchDir, branchRef, metaFile }: GitHubCommitsArgs): 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
+ * until the branch's next sync.
+ */
+export declare function enqueueReviewBlockSync(ctx: Pick<GitHubCommitsContext, 'taskDir'>, branchRef: string, { branch }: BranchMetadataFile): Promise<void>;

package/dist/worker/github-commits.js

@@ -0,0 +1,485 @@
+import { BranchMetadataFileManager, awaitsSubmitRetry, getBranchMetadataFileManager, } from '../branch-metadata.js';
+import { invalidateBranchContentCaches } from '../content-index-generation.js';
+import { GITHUB_TRACKING_REF_PREFIX } from '../git-manager.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 { 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';
+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. */
+export const REWRITTEN_PUSH_REFUSAL = "This branch was changed on GitHub in a way CanopyCMS can't combine with the work here, so nothing was pushed. Nothing is lost.";
+/** Why a push was refused before any sync had seen the rewrite (task-runner.ts). */
+export const SEEN_COMMIT_GONE_PUSH_REFUSAL = 'A commit this branch had on GitHub is no longer there, so nothing was pushed. Nothing is lost.';
+/**
+ * What clears a rewrite: the flag, and the refusal's text, which would go on saying the work can't
+ * be combined. The failed sync it left goes too, unless {@link awaitsSubmitRetry}.
+ */
+export function rewriteCleared(branch) {
+    const reason = branch.syncFailureReason;
+    if (!reason?.includes(REWRITTEN_PUSH_REFUSAL) &&
+        !reason?.includes(SEEN_COMMIT_GONE_PUSH_REFUSAL)) {
+        return { rewrittenOnGitHub: undefined };
+    }
+    return awaitsSubmitRetry(branch)
+        ? { rewrittenOnGitHub: undefined, syncFailureReason: undefined }
+        : { 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 }) {
+    return branch.pushedToGitHubAt !== undefined || branch.pullRequestNumber !== undefined;
+}
+/** 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;
+    const { branch } = metaFile;
+    // A branch.json naming another ref is that branch's, which shares this directory's name.
+    if (branch.name !== branchRef || !isPublished(metaFile))
+        return { kind: 'in-step' };
+    const gitHubTip = args.gitHub?.tips.get(branchRef);
+    // No GitHub branch leaves nothing a push could restore.
+    if (args.gitHub !== undefined && gitHubTip === undefined && branch.rewrittenOnGitHub) {
+        await clearRewritten(ctx, args);
+    }
+    const published = await readPublishedSha(ctx, branchRef);
+    const tip = gitHubTip ?? published;
+    if (tip === null)
+        return { kind: 'in-step' };
+    let head = (await git.revparse(['HEAD'])).trim();
+    if (tip === head && (published === null || published === head)) {
+        await recordGitHubTip(ctx, args, tip);
+        return { kind: 'in-step' };
+    }
+    // Holding base keeps content the serving editor has no schema for out of every clone, and a
+    // merge of base on GitHub would carry it in here.
+    if (ctx.ensureStatusReport().baseHold)
+        return { kind: 'wait' };
+    if (published !== null && published !== head) {
+        await fetchFromRemoteGit(git, ctx.remoteGitPath, `refs/heads/${branchRef}`);
+    }
+    if (tip !== head && tip !== published) {
+        await fetchFromRemoteGit(git, ctx.remoteGitPath, `${GITHUB_TRACKING_REF_PREFIX}${branchRef}`);
+    }
+    // First, before any step reads this tip as commits to take in or a push to make: both would
+    // restore what someone removed.
+    let rewriteResolved = false;
+    if (args.gitHub !== undefined && gitHubTip !== undefined) {
+        // Unreadable means the tip's objects did not reach this clone, which says nothing about GitHub.
+        if (!(await holdsCommit(git, tip)))
+            return { kind: 'wait' };
+        const lastSeen = await rewrittenFrom(args, tip, head, published);
+        if (lastSeen !== null) {
+            return (await pushedSinceFetch(args, args.gitHub.fetchedAt))
+                ? { kind: 'wait' }
+                : blockAsRewritten(ctx, args, lastSeen);
+        }
+        if (branch.rewrittenOnGitHub !== undefined) {
+            await clearRewritten(ctx, args);
+            rewriteResolved = true;
+        }
+    }
+    // A crash after a merge reached remote.git leaves the clone behind it, like any fast-forward
+    // reconcile made, and the check above has ruled out a head GitHub dropped. Taken first, so a merge
+    // below builds on remote.git's head whenever it can.
+    if (published !== null && published !== head) {
+        if ((await commitsApart(git, head, published)).onlyA === 0) {
+            const stopped = await fastForward(ctx, args, head, published);
+            if (stopped)
+                return stopped;
+            head = published;
+        }
+    }
+    if (tip !== head) {
+        const { onlyA, onlyB } = await commitsApart(git, head, tip);
+        if (onlyB > 0 && onlyA === 0) {
+            // Reconcile didn't take this tip in. The clone stays level with `remote.git`, or the next
+            // force-push would find a commit in the clone that neither the record nor `remote.git` names.
+            if (gitHubTip !== undefined && published !== null && published !== tip) {
+                return { kind: 'wait' };
+            }
+            const stopped = await fastForward(ctx, args, head, tip);
+            if (stopped)
+                return stopped;
+            head = tip;
+        }
+        else if (onlyB > 0) {
+            // The worker's own rewrite with its push still on the way: GitHub stands at the commit it
+            // replaced, and history-rewrite.ts completes that hop.
+            if (branch.historyRewrittenFrom === tip) {
+                if (rewriteResolved)
+                    await enqueueGitHubPush(ctx, branchRef, gatewayPolicy);
+                return { kind: 'in-step' };
+            }
+            if (dirty)
+                return { kind: 'wait' };
+            // Nothing it made could reach GitHub, and each base move would make another.
+            if (gatewayPolicy && !publishesBranch(gatewayPolicy, branchRef))
+                return { kind: 'in-step' };
+            return mergeIntoBranch(ctx, args, {
+                head,
+                other: tip,
+                message: `Merge commits from GitHub into ${branchRef}`,
+                fromGitHub: true,
+            });
+        }
+    }
+    await recordGitHubTip(ctx, args, tip);
+    // A merge or a submit that reached remote.git with no GitHub push queued, as after a crash
+    // between the two. A rebase now would strand the push, which leases on a commit GitHub never
+    // held, and read as a rewrite on GitHub once it failed. So the branch waits for the push, or takes
+    // the base by a merge when the push failed for good, which isn't queued again unless a cleared
+    // rewrite was all that stopped it: a new attempt would fail the same way every cycle.
+    if (gitHubTip !== undefined &&
+        published !== null &&
+        published !== tip &&
+        (!gatewayPolicy || publishesBranch(gatewayPolicy, branchRef)) &&
+        (await contains(git, published, tip))) {
+        if (branch.syncStatus === 'sync-failed' && !rewriteResolved)
+            return { kind: 'unpushed' };
+        await enqueueGitHubPush(ctx, branchRef, gatewayPolicy);
+        return { kind: 'wait' };
+    }
+    return { kind: 'in-step' };
+}
+/**
+ * Whether the task loop pushed this branch after the cycle's fetch began, which makes the cycle's
+ * tip old news rather than a rewrite. Read fresh: the caller's metadata is from the cycle's start.
+ */
+async function pushedSinceFetch({ branchPath }, fetchedAt) {
+    const pushedAt = (await BranchMetadataFileManager.loadOnly(branchPath))?.branch.pushedToGitHubAt;
+    return pushedAt !== undefined && Date.parse(pushedAt) >= fetchedAt;
+}
+/**
+ * The commit a rewrite on GitHub removed, or null. A commit removed on GitHub stays removed: its
+ * clone and `remote.git` may still hold it, and nothing here may put it back. Any commit GitHub is
+ * known to hold counts: the last tip seen, and the commit a pending rewrite of the worker's own
+ * replaced, since GitHub stays there until that push lands. A tip holding everything the clone and
+ * `remote.git` hold has nothing to restore, whatever the record says. A commit in neither was
+ * never taken in, so `remote.git`'s head has to be part of that test: the clone can lag it for a
+ * cycle, and the fast-forward below would then bring back what GitHub dropped.
+ */
+async function rewrittenFrom({ git, metaFile }, tip, head, published) {
+    const { lastGitHubTip, historyRewrittenFrom } = metaFile.branch;
+    // A branch with no record yet: a `remote.git` head the clone lags, diverged from GitHub, is a
+    // commit reconcile took in before a force-push, barring a crash mid-merge on that first cycle.
+    const unrecorded = lastGitHubTip === undefined &&
+        published !== null &&
+        published !== head &&
+        (await contains(git, published, head)) &&
+        !(await contains(git, published, tip))
+        ? published
+        : undefined;
+    // The marker first: what is named here must be a commit GitHub really held, and a rewrite's
+    // stamp may not have reached it yet.
+    const known = [historyRewrittenFrom, lastGitHubTip ?? unrecorded].filter((sha) => sha !== undefined && COMMIT_ID.test(sha));
+    if (known.length === 0)
+        return null;
+    if ((await contains(git, tip, head)) &&
+        (published === null || (await contains(git, tip, published)))) {
+        return null;
+    }
+    for (const sha of known)
+        if (await contains(git, tip, sha))
+            return null;
+    // Git says a commit is missing when a pack it lives in can't be read, so only a full read of the
+    // tip's history makes "not contained" an answer.
+    const walked = await git.raw(['rev-list', '--count', '--end-of-options', tip]);
+    if (walked.trim() === '')
+        throw new Error(`No answer reading the history of ${tip}`);
+    return known[0];
+}
+/** Record the rewrite, which refuses pushes (task-runner.ts) for as long as it stands. */
+async function blockAsRewritten(ctx, { branchPath, branchRef, metaFile }, lastSeen) {
+    if (metaFile.branch.rewrittenOnGitHub !== lastSeen) {
+        await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).saveIf({ branch: { rewrittenOnGitHub: lastSeen } }, (current) => current?.branch.name === branchRef);
+    }
+    return {
+        kind: 'blocked',
+        reason: `GitHub's ${branchRef} no longer contains ${lastSeen}, the last commit this deployment saw ` +
+            `there: it was force-pushed or rewritten. Nothing was merged or pushed, so the rewrite ` +
+            `stands, and this branch's changes cannot reach GitHub. To continue, a developer merges ` +
+            `that commit back into the branch on GitHub.`,
+    };
+}
+async function clearRewritten(ctx, { branchPath, branchRef }) {
+    await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).update((current) => current?.branch.name === branchRef ? { branch: rewriteCleared(current.branch) } : null);
+}
+/** A short, one-line list of paths from a commit, safe in a log line and on branch metadata. */
+function listPaths(paths) {
+    return paths
+        .slice(0, MAX_REPORTED_PATHS)
+        .map((file) => escapeForLog(file).slice(0, MAX_LISTED_PATH_LENGTH))
+        .join(', ');
+}
+/**
+ * What stops `to` entering this clone, or null. `.git/info/exclude` hides canopycms's own state, and
+ * git overwrites an ignored file without asking, so a commit that changes it would replace the live
+ * branch.json and comments. A deletion counts: taken in, it would delete the live file, and
+ * untracking it first leaves the branch holding a commit that does.
+ */
+async function refuseIncoming({ git, branchPath }, from, to) {
+    await assertNoIncomingSubmodules(git, branchPath, from, to);
+    const fields = (await git.raw([
+        'diff-tree',
+        '-r',
+        '-z',
+        '--name-status',
+        '--no-renames',
+        '--end-of-options',
+        from,
+        to,
+    ])).split('\0');
+    const deleted = [];
+    const changed = [];
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+        const file = fields[i + 1];
+        // Nothing reads the retired cache, so its deletion, which an adopter's fix makes, is harmless.
+        if (!isCanopyInternalPath(file))
+            continue;
+        if (fields[i] !== 'D')
+            changed.push(file);
+        else if (file !== RETIRED_SCHEMA_CACHE_PATH)
+            deleted.push(file);
+    }
+    if (changed.length > 0) {
+        return {
+            kind: 'blocked',
+            reason: `Commits coming into this branch change canopycms's own state, which must not be committed ` +
+                `(${listPaths(changed)}). Nothing was brought in. To fix, ${TRACKED_CANOPY_STATE_FIX}.`,
+        };
+    }
+    if (deleted.length > 0) {
+        return {
+            kind: 'blocked',
+            reason: `Commits coming into this branch stop tracking canopycms state this clone still tracks ` +
+                `(${listPaths(deleted)}). Nothing was brought in; the clone needs manual repair.`,
+        };
+    }
+    return null;
+}
+/**
+ * Move the clone to `to`, or say why it did not. Saves that touch a file the commits change make
+ * git refuse before it writes anything, and those commits wait for the submit that commits them.
+ * Any other failure throws: the message is git's, in the C locale `sharedRepoGit` pins.
+ */
+async function fastForward(ctx, args, from, to) {
+    const { git, branchPath, branchDir, lockLost } = args;
+    const refused = await refuseIncoming(args, from, to);
+    if (refused)
+        return refused;
+    if (lockLost())
+        return { kind: 'wait' };
+    if (await changesWhatWasReviewed(ctx, args, from, to))
+        await returnToReview(ctx, args);
+    try {
+        await moveClone(git, branchPath, to);
+    }
+    catch (err) {
+        if (!/would be overwritten/.test(getErrorMessage(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)})`);
+    return null;
+}
+/**
+ * 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.
+ */
+async function moveClone(git, branchPath, to) {
+    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.
+ */
+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, {
+        head,
+        other,
+        message,
+        timeoutMs: ctx.taskTimeoutMs,
+    });
+    if (stopOnConflict && (built.kind === 'unsettled' || built.conflicted.length > 0)) {
+        workerLog(`  ${branchDir}: conflicts with ${other.slice(0, 7)}, so it stays as it is`);
+        return { kind: 'wait' };
+    }
+    if (built.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. ` +
+                `To continue, a developer merges them by hand.`,
+        };
+    }
+    const { sha, conflicted } = 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))) {
+        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 ` +
+        `copies with a developer before submitting again.`;
+    if (published !== null && !(await contains(git, sha, published))) {
+        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);
+    // 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) {
+        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);
+    }
+    await moveClone(git, branchPath, sha);
+    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))`
+        : `  ${branchDir}: merged ${other.slice(0, 7)}`);
+    return { kind: 'merged' };
+}
+/**
+ * Whether this clone holds `sha`, on git's word for it. A killed `git` answers nothing at all,
+ * which simple-git resolves empty, and that throws. Git says the same of a commit in a pack it
+ * can't read, so a caller that acts on "no" reads the history too, as `rewrittenFrom` does.
+ */
+async function holdsCommit(git, sha) {
+    let found;
+    try {
+        found = await git.raw(['rev-parse', '--verify', '--end-of-options', `${sha}^{commit}`]);
+    }
+    catch (err) {
+        if (/Needed a single revision/.test(getErrorMessage(err)))
+            return false;
+        throw err;
+    }
+    if (found.trim() === '')
+        throw new Error(`No answer looking for ${sha}`);
+    return true;
+}
+/**
+ * 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.
+ */
+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.
+ */
+async function changesWhatWasReviewed(ctx, { git, branchPath }, from, to) {
+    const fresh = (await BranchMetadataFileManager.loadOnly(branchPath))?.branch;
+    if (fresh?.status !== 'approved')
+        return false;
+    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));
+}
+/**
+ * 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.
+ */
+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`);
+    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]),
+                        ],
+                    }
+                    : {}),
+            },
+        }
+        : null);
+}
+/**
+ * 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
+ * until the branch's next sync.
+ */
+export async function enqueueReviewBlockSync(ctx, branchRef, { branch }) {
+    if (branch.pullRequestNumber === undefined)
+        return;
+    try {
+        await enqueueTask(ctx.taskDir, {
+            action: SYNC_PR_COMMENTS_ACTION,
+            payload: {
+                branch: branchRef,
+                pullRequestNumber: branch.pullRequestNumber,
+                reviewBlockOnly: true,
+            },
+        });
+    }
+    catch (err) {
+        workerLogWarn(`  Failed to queue a PR body update for ${branchRef}: ${getErrorMessage(err)}`);
+    }
+}
+/**
+ * Skipped when nothing changes: every save regenerates the branch registry. Bookkeeping, so it
+ * leaves `updatedAt`, which the card shows as an edit.
+ */
+async function recordGitHubTip(ctx, { branchPath, branchRef, metaFile, gitHub }, tip) {
+    const { lastGitHubTip, rewrittenOnGitHub } = metaFile.branch;
+    if (gitHub?.tips.get(branchRef) !== tip)
+        return;
+    if (lastGitHubTip === tip && rewrittenOnGitHub === undefined)
+        return;
+    await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).update((current) => {
+        if (current?.branch.name !== branchRef)
+            return null;
+        // A stamp newer than this cycle's fetch is a push that landed since, which GitHub holds.
+        const seen = current.branch.lastGitHubTip === lastGitHubTip ? { lastGitHubTip: tip } : {};
+        return { branch: { ...seen, ...rewriteCleared(current.branch) } };
+    }, { keepUpdatedAt: true });
+}