canopycms 0.12.1 → 0.13.0

package/dist/worker/github-commits.js

@@ -9,11 +9,12 @@ 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 { commitMerge, commitsApart, isCleanMergeOf, planMerge, publishPlainToLocalRemote, } 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. */
@@ -63,7 +64,10 @@ export async function catchUpWithPublished(ctx, args) {
     const parents = (await git.raw(['rev-list', '--parents', '-n', '1', '--end-of-options', published]))
         .trim()
         .split(' ');
-    if (parents.length !== 3 || parents[1] !== head)
+    // 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);
 }
@@ -124,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;
@@ -316,7 +326,7 @@ 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' };
@@ -329,29 +339,139 @@ async function fastForward(ctx, args, from, to) {
     }
     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, 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
+ * `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, 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,
+        other: into,
         contentRoot: ctx.contentRoot,
         timeoutMs: ctx.taskTimeoutMs,
     });
@@ -371,7 +491,9 @@ export async function mergeIntoBranch(ctx, args, merge) {
                 `To continue, a developer merges them by hand.`,
         };
     }
-    const built = await commitMerge(git, plan, { head, other, message });
+    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)
@@ -392,24 +514,38 @@ export async function mergeIntoBranch(ctx, args, merge) {
     // 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. A merge that never lands leaves records the
     // next cycle's reconcile turns back.
-    await recordMerge(ctx, args, built, { head, fromGitHub });
+    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);
     }
+    else if (publish.kind === 'hold') {
+        workerLog(`  ${branchDir}: holds work not yet submitted, so the merge stays unpublished`);
+    }
     // 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);
+    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)
@@ -450,19 +586,25 @@ export async function contains(git, commit, ancestor) {
     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. Called before the
@@ -482,12 +624,18 @@ export async function returnToReview(ctx, { branchPath, branchDir, branchRef, me
  * 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.
+ * {@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);
+    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: [
@@ -519,17 +667,7 @@ async function landed(ctx, { git, branchPath, branchRef, branchDir, metaFile, },
     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 noteKeptOverGitHub(ctx, { branchPath, branchRef, metaFile }, landing.keptOverGitHub ?? []);
     await store.update((now) => {
         if (now?.landing?.mergeSha !== sha)
             return null;
@@ -537,6 +675,19 @@ async function landed(ctx, { git, branchPath, branchRef, branchDir, metaFile, },
         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: {
+                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 [
@@ -562,25 +713,26 @@ async function mergesHeld(git, state, tips) {
     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.
+ * 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) {
+async function settleRecord(git, branchPath, head, also) {
     const store = new MergeConflictStore(branchPath);
     const current = await store.read();
     if (current === null)
         return () => true;
-    const [held] = await mergesHeld(git, current, [head]);
+    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);
-    // 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;
+    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

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;

package/dist/worker/github-errors.js

@@ -0,0 +1,47 @@
+/**
+ * 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 function getHttpStatus(err) {
+    if (err instanceof Error && 'status' in err) {
+        const status = err.status;
+        if (typeof status === 'number')
+            return status;
+    }
+    return null;
+}
+/** Narrow an unknown value to a response-headers record, if present (Octokit lowercases header names). */
+function getResponseHeaders(err) {
+    if (typeof err !== 'object' || err === null || !('response' in err))
+        return null;
+    const response = err.response;
+    if (typeof response !== 'object' || response === null || !('headers' in response))
+        return null;
+    const headers = response.headers;
+    if (typeof headers !== 'object' || headers === null)
+        return null;
+    return headers;
+}
+/**
+ * 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 function isRateLimitSignal403(err) {
+    const headers = getResponseHeaders(err);
+    if (headers) {
+        if (headers['x-ratelimit-remaining'] === '0')
+            return true;
+        if (typeof headers['retry-after'] === 'string' && headers['retry-after'].length > 0)
+            return true;
+    }
+    if (err instanceof Error && /rate limit/i.test(err.message))
+        return true;
+    return false;
+}
+/** A 403 that is GitHub denying the credential the operation, not a rate limit. */
+export function isPermissionDenial(err) {
+    return getHttpStatus(err) === 403 && !isRateLimitSignal403(err);
+}

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

@@ -231,6 +231,10 @@ class GatewayRequestHandler {
                 await gateway.convertPullRequestToDraft(number, signal);
                 return {};
             },
+            setConflictsStatus: async (status, signal) => {
+                await gateway.setConflictsStatus(status, signal);
+                return {};
+            },
             deleteBranch: async ({ branch }, signal) => {
                 await gateway.deleteBranch(branch, signal);
                 return {};
@@ -824,6 +828,9 @@ class GitHubGatewayClient {
     async convertPullRequestToDraft(number, signal) {
         await this.call('convertPullRequestToDraft', { number }, signal);
     }
+    async setConflictsStatus(status, signal) {
+        await this.call('setConflictsStatus', status, signal);
+    }
     async deleteBranch(branch, signal) {
         await this.call('deleteBranch', { branch }, signal);
     }

package/dist/worker/github-gateway-wire.d.ts

@@ -119,6 +119,25 @@ export declare const requests: {
     }, {
         number: number;
     }>;
+    readonly setConflictsStatus: z.ZodObject<{
+        pullRequest: z.ZodNumber;
+        sha: z.ZodString;
+        state: z.ZodEnum<["success", "failure"]>;
+        description: z.ZodString;
+        targetUrl: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        description: string;
+        state: "success" | "failure";
+        sha: string;
+        pullRequest: number;
+        targetUrl?: string | undefined;
+    }, {
+        description: string;
+        state: "success" | "failure";
+        sha: string;
+        pullRequest: number;
+        targetUrl?: string | undefined;
+    }>;
     readonly deleteBranch: z.ZodObject<{
         branch: z.ZodString;
     }, "strict", z.ZodTypeAny, {
@@ -146,15 +165,15 @@ export declare const answers: {
         }, "strict", z.ZodTypeAny, {
             settingsBranch: string | null;
             namespace: string;
-            legacy: string[];
             configured: string[];
             githubDefault: string | null;
+            legacy: string[];
         }, {
             settingsBranch: string | null;
             namespace: string;
-            legacy: string[];
             configured: string[];
             githubDefault: string | null;
+            legacy: string[];
         }>;
     }, "strict", z.ZodTypeAny, {
         ready: boolean;
@@ -164,9 +183,9 @@ export declare const answers: {
         branchPolicy: {
             settingsBranch: string | null;
             namespace: string;
-            legacy: string[];
             configured: string[];
             githubDefault: string | null;
+            legacy: string[];
         };
     }, {
         ready: boolean;
@@ -176,9 +195,9 @@ export declare const answers: {
         branchPolicy: {
             settingsBranch: string | null;
             namespace: string;
-            legacy: string[];
             configured: string[];
             githubDefault: string | null;
+            legacy: string[];
         };
     }>;
     readonly defaultBranch: z.ZodObject<{
@@ -249,6 +268,7 @@ export declare const answers: {
         url: string;
     }>;
     readonly convertPullRequestToDraft: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+    readonly setConflictsStatus: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     readonly deleteBranch: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
     readonly authSnapshot: z.ZodObject<{
         users: z.ZodArray<z.ZodObject<{
@@ -432,24 +452,24 @@ export declare function readAnswerBody(json: unknown): {
 declare const errorEnvelope: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     kind: z.ZodLiteral<"refusal">;
     push: z.ZodBoolean;
-    operation: z.ZodEnum<["push", "delete", "pull-request"]>;
+    operation: z.ZodEnum<["push", "delete", "pull-request", "commit-status"]>;
     branch: z.ZodString;
-    reason: z.ZodEnum<["invalid", "protected", "settings", "other-settings", "outside-namespace", "not-a-commit", "too-long"]>;
+    reason: z.ZodEnum<["invalid", "protected", "settings", "other-settings", "outside-namespace", "not-a-commit", "too-long", "not-head"]>;
     message: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     branch: string;
     push: boolean;
     message: string;
-    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
+    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long" | "not-head";
     kind: "refusal";
-    operation: "push" | "delete" | "pull-request";
+    operation: "push" | "delete" | "pull-request" | "commit-status";
 }, {
     branch: string;
     push: boolean;
     message: string;
-    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
+    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long" | "not-head";
     kind: "refusal";
-    operation: "push" | "delete" | "pull-request";
+    operation: "push" | "delete" | "pull-request" | "commit-status";
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"push">;
     pushKind: z.ZodEnum<["rejected", "rejected-after-stale-lease", "seen-commit-gone"]>;

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

@@ -77,6 +77,15 @@ export const requests = {
     })
         .strict(),
     convertPullRequestToDraft: z.object({ number: prNumber }).strict(),
+    setConflictsStatus: z
+        .object({
+        pullRequest: prNumber,
+        sha: objectId,
+        state: z.enum(['success', 'failure']),
+        description: z.string().max(4096),
+        targetUrl: z.string().max(4096).optional(),
+    })
+        .strict(),
     deleteBranch: z.object({ branch: name }).strict(),
     authSnapshot: z.object({}).strict(),
     termination: z.object({}).strict(),
@@ -121,6 +130,7 @@ export const answers = {
         .strict(),
     createOrUpdatePullRequest: pullRequestRef.extend({ created: z.boolean() }).strict(),
     convertPullRequestToDraft: empty,
+    setConflictsStatus: empty,
     deleteBranch: empty,
     authSnapshot: z
         .object({
@@ -168,6 +178,7 @@ export const JSON_ROUTES = {
     getPullRequest: `${WIRE_PREFIX}/pull-request/get`,
     createOrUpdatePullRequest: `${WIRE_PREFIX}/pull-request/create-or-update`,
     convertPullRequestToDraft: `${WIRE_PREFIX}/pull-request/convert-to-draft`,
+    setConflictsStatus: `${WIRE_PREFIX}/pull-request/conflicts-status`,
     deleteBranch: `${WIRE_PREFIX}/branch/delete`,
     authSnapshot: `${WIRE_PREFIX}/auth-snapshot`,
     termination: `${WIRE_PREFIX}/termination`,
@@ -240,7 +251,7 @@ const errorEnvelope = z.discriminatedUnion('kind', [
         .object({
         kind: z.literal('refusal'),
         push: z.boolean(),
-        operation: z.enum(['push', 'delete', 'pull-request']),
+        operation: z.enum(['push', 'delete', 'pull-request', 'commit-status']),
         branch: name,
         reason: z.enum([
             'invalid',
@@ -250,6 +261,7 @@ const errorEnvelope = z.discriminatedUnion('kind', [
             'outside-namespace',
             'not-a-commit',
             'too-long',
+            'not-head',
         ]),
         message,
     })
@@ -461,7 +473,7 @@ export function decodeError(value) {
             const { push, operation, branch, reason } = envelope;
             if (!push)
                 return new GatewayRefusalError(operation, branch, reason, envelope.message);
-            if (operation !== 'push' || reason === 'too-long') {
+            if (operation !== 'push' || reason === 'too-long' || reason === 'not-head') {
                 return new GitHubGatewayProtocolError(`The GitHub gateway answered with a push refusal for ${operation}, reason ${reason}`);
             }
             const err = new RefusedPushError(branch, reason);

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

@@ -89,6 +89,16 @@ export type GitHubPullRequest = Pick<RestEndpointMethodTypes['pulls']['get']['re
     /** The pull request's head commit, read with `mergeable_state`. */
     headSha?: string;
 };
+/** A "CanopyCMS conflicts" status for the head of pull request `pullRequest`. */
+export interface GitHubConflictsStatus {
+    pullRequest: number;
+    /** The pull request's head commit; the gateway refuses any other. */
+    sha: string;
+    state: 'success' | 'failure';
+    description: string;
+    /** The editor, opened on the branch. */
+    targetUrl?: string;
+}
 export type GitHubCreateOrUpdatePullRequest = Omit<CreateOrUpdatePullRequestParams, 'octokit' | 'owner' | 'repo' | 'signal'>;
 /**
  * Everything the worker does with GitHub, and the only place the credential and Octokit are used.
@@ -166,6 +176,13 @@ export interface GitHubGateway {
         created: boolean;
     }>;
     convertPullRequestToDraft(number: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * Set the {@link CONFLICTS_STATUS_CONTEXT} status on a pull request's head. Refused
+     * (`GatewayRefusalError`) with reason `not-head` unless `sha` is the head GitHub holds now, as
+     * `updatePullRequest` refuses a pull request it would not update, and for a description or link
+     * `assertCommitStatusText` refuses (worker/branch-policy.ts).
+     */
+    setConflictsStatus(status: GitHubConflictsStatus, signal?: AbortSignal): Promise<void>;
     deleteBranch(branch: string, signal?: AbortSignal): Promise<void>;
     /**
      * The auth provider's users, groups and memberships, which the worker writes to the auth cache: