canopycms 0.12.0 → 0.13.0

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

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

@@ -9,10 +9,13 @@ export declare const MAX_JSON_REQUEST_BYTES: number;
 export declare const MAX_JSON_ANSWER_BYTES: number;
 export declare const fetchRequest: z.ZodObject<{
     have: z.ZodArray<z.ZodString, "many">;
+    fresh: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     have: string[];
+    fresh?: boolean | undefined;
 }, {
     have: string[];
+    fresh?: boolean | undefined;
 }>;
 export declare const pushRequest: z.ZodObject<{
     branch: z.ZodString;
@@ -56,13 +59,13 @@ export declare const requests: {
     }, "strict", z.ZodTypeAny, {
         title: string;
         base: string;
-        head: string;
         body: string;
+        head: string;
     }, {
         title: string;
         base: string;
-        head: string;
         body: string;
+        head: string;
     }>;
     readonly updatePullRequest: z.ZodObject<{
         number: z.ZodNumber;
@@ -97,15 +100,15 @@ export declare const requests: {
     }, "strict", z.ZodTypeAny, {
         title: string;
         base: string;
-        head: string;
         body: string;
+        head: string;
         markReadyIfDraft?: boolean | undefined;
         mergeSectionIntoBody?: boolean | undefined;
     }, {
         title: string;
         base: string;
-        head: string;
         body: string;
+        head: string;
         markReadyIfDraft?: boolean | undefined;
         mergeSectionIntoBody?: boolean | undefined;
     }>;
@@ -116,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, {
@@ -143,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;
@@ -161,9 +183,9 @@ export declare const answers: {
         branchPolicy: {
             settingsBranch: string | null;
             namespace: string;
-            legacy: string[];
             configured: string[];
             githubDefault: string | null;
+            legacy: string[];
         };
     }, {
         ready: boolean;
@@ -173,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<{
@@ -211,12 +233,14 @@ export declare const answers: {
         body: z.ZodNullable<z.ZodString>;
         mergeable_state: z.ZodOptional<z.ZodString>;
         baseRef: z.ZodOptional<z.ZodString>;
+        headSha: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         merged: boolean;
         state: "open" | "closed";
         body: string | null;
         merged_at: string | null;
         node_id: string;
+        headSha?: string | undefined;
         mergeable_state?: string | undefined;
         baseRef?: string | undefined;
     }, {
@@ -225,6 +249,7 @@ export declare const answers: {
         body: string | null;
         merged_at: string | null;
         node_id: string;
+        headSha?: string | undefined;
         mergeable_state?: string | undefined;
         baseRef?: string | undefined;
     }>;
@@ -243,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<{
@@ -312,21 +338,21 @@ export declare const answers: {
             kind: z.ZodEnum<["auto-scaling", "spot"]>;
             reason: z.ZodString;
         }, "strict", z.ZodTypeAny, {
-            kind: "auto-scaling" | "spot";
             reason: string;
-        }, {
             kind: "auto-scaling" | "spot";
+        }, {
             reason: string;
+            kind: "auto-scaling" | "spot";
         }>>;
     }, "strict", z.ZodTypeAny, {
         notice: {
-            kind: "auto-scaling" | "spot";
             reason: string;
+            kind: "auto-scaling" | "spot";
         } | null;
     }, {
         notice: {
-            kind: "auto-scaling" | "spot";
             reason: string;
+            kind: "auto-scaling" | "spot";
         } | null;
     }>;
     readonly completeLifecycle: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
@@ -360,15 +386,18 @@ export declare const fetchPoll: z.ZodDiscriminatedUnion<"state", [z.ZodObject<{
     /** Every GitHub branch and its tip, as pairs: a `Map` has no JSON form of its own. */
     refs: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>, "many">;
     bundleId: z.ZodNullable<z.ZodString>;
+    startedAt: z.ZodNumber;
 }, "strict", z.ZodTypeAny, {
     state: "done";
     refs: [string, string][];
     progress: number;
+    startedAt: number;
     bundleId: string | null;
 }, {
     state: "done";
     refs: [string, string][];
     progress: number;
+    startedAt: number;
     bundleId: string | null;
 }>]>;
 export declare const pushAnswer: z.ZodUnion<[z.ZodObject<{
@@ -391,15 +420,15 @@ export declare const pushAnswer: z.ZodUnion<[z.ZodObject<{
     pastStaleLease: z.ZodBoolean;
 }, "strict", z.ZodTypeAny, {
     kind: "pushed";
+    moved: true;
     from: string | null;
     to: string;
-    moved: true;
     pastStaleLease: boolean;
 }, {
     kind: "pushed";
+    moved: true;
     from: string | null;
     to: string;
-    moved: true;
     pastStaleLease: boolean;
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"need-objects">;
@@ -423,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" | "not-head";
     kind: "refusal";
-    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
-    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" | "not-head";
     kind: "refusal";
-    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
-    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

@@ -37,7 +37,9 @@ const objectId = z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/, 'not a full
 const name = z.string().max(4096);
 const prNumber = z.number().int().safe();
 const message = z.string().max(MAX_MESSAGE_LENGTH);
-export const fetchRequest = z.object({ have: z.array(objectId).max(MAX_FETCH_HAVE) }).strict();
+export const fetchRequest = z
+    .object({ have: z.array(objectId).max(MAX_FETCH_HAVE), fresh: z.boolean().optional() })
+    .strict();
 export const pushRequest = z
     .object({
     branch: name,
@@ -75,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(),
@@ -114,10 +125,12 @@ export const answers = {
         body: pullRequestText.body.nullable(),
         mergeable_state: z.string().max(64).optional(),
         baseRef: z.string().max(256).optional(),
+        headSha: objectId.optional(),
     })
         .strict(),
     createOrUpdatePullRequest: pullRequestRef.extend({ created: z.boolean() }).strict(),
     convertPullRequestToDraft: empty,
+    setConflictsStatus: empty,
     deleteBranch: empty,
     authSnapshot: z
         .object({
@@ -165,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`,
@@ -187,6 +201,7 @@ export const fetchPoll = z.discriminatedUnion('state', [
         /** Every GitHub branch and its tip, as pairs: a `Map` has no JSON form of its own. */
         refs: z.array(z.tuple([name, objectId])).max(1_000_000),
         bundleId: jobId.nullable(),
+        startedAt: z.number().int().nonnegative(),
     })
         .strict(),
 ]);
@@ -236,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',
@@ -246,6 +261,7 @@ const errorEnvelope = z.discriminatedUnion('kind', [
             'outside-namespace',
             'not-a-commit',
             'too-long',
+            'not-head',
         ]),
         message,
     })
@@ -457,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

@@ -15,6 +15,11 @@ export interface GitHubFetchResult {
      * request's `have` and their history; null when that leaves nothing to send.
      */
     bundleId: string | null;
+    /**
+     * When the GitHub fetch `refs` come from began, by the gateway's clock, which is the worker's:
+     * they share the instance. A fetch can be joined or reused, so this can predate the request.
+     */
+    startedAt: number;
 }
 /** The most `have` IDs one fetch takes. */
 export declare const MAX_FETCH_HAVE = 10000;
@@ -81,7 +86,19 @@ export type GitHubPullRequest = Pick<RestEndpointMethodTypes['pulls']['get']['re
     mergeable_state?: string;
     /** The branch the pull request merges into on GitHub, which a person can change. */
     baseRef?: string;
+    /** 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.
@@ -114,10 +131,12 @@ export interface GitHubGateway {
      * Fetch every GitHub branch, and answer with all of them and a bundle of the commits `have`
      * lacks. `have` is the caller's own tips, at most {@link MAX_FETCH_HAVE} object IDs; any the
      * gateway does not hold as a commit is ignored. A new fetch replaces a bundle not yet opened.
-     * `onProgress` is told of each sign of life from the gateway's git while the caller waits.
+     * `fresh` takes no GitHub fetch begun before the request arrived. `onProgress` is told of each
+     * sign of life from the gateway's git while the caller waits.
      */
     fetch(request: {
         have: readonly string[];
+        fresh?: boolean;
     }, signal?: AbortSignal, onProgress?: () => void): Promise<GitHubFetchResult>;
     /**
      * The bundle a fetch answered with, readable once. Throws {@link GitHubTransientError}
@@ -157,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:

package/dist/worker/github-gateway.js

@@ -4,8 +4,9 @@ import { createCanopyOctokit, createOrUpdatePullRequest, } from '../github-servi
 import { getErrorMessage } from '../utils/error.js';
 import { isStaleLeaseRejection, workflowPushRefusalFile } from '../utils/git.js';
 import { isTransientAuthFailure } from './github-auth.js';
+import { isPermissionDenial } from './github-errors.js';
 import { GitHubMirror, GitHubTransientError, RefusedPushError, assertPlainBranchName, isObjectId, } from './github-mirror.js';
-import { BranchPolicy, GatewayRefusalError, assertPullRequestText, } from './branch-policy.js';
+import { BranchPolicy, GatewayRefusalError, assertCommitStatusText, assertPullRequestText, } from './branch-policy.js';
 import { gatewayLog, gatewayLogError, gatewayLogWarn, redactEgress, redactError, redactValue, registerLiveSecret, } from './gateway-egress.js';
 import { GatewayInstance, untilAborted } from './gateway-instance.js';
 /** The most `have` IDs one fetch takes. */
@@ -47,6 +48,11 @@ export function describeMove(update) {
     const to = update.to.slice(0, 7);
     return update.from === null ? `new branch at ${to}` : `${update.from.slice(0, 7)}..${to}`;
 }
+/**
+ * The context of the commit status the worker sets on a pull request's head. Fixed by the gateway,
+ * so a worker can set no other; adopters name it when they make it a required check.
+ */
+const CONFLICTS_STATUS_CONTEXT = 'CanopyCMS conflicts';
 /** The in-process {@link GitHubGateway}. */
 export function createLocalGitHubGateway(options) {
     return new LocalGitHubGateway(options);
@@ -197,11 +203,14 @@ class LocalGitHubGateway {
      * own, which repairs a corrupt mirror first ({@link GitHubMirror.heal}), and its failure re-reads
      * the credential when it reached GitHub, whoever started it.
      */
-    async joinGitHubFetch(resolve, signal) {
+    async joinGitHubFetch(resolve, signal, 
+    /** Join or reuse only a fetch that began at or after this time. */
+    notBefore) {
         const current = this.githubFetch;
         const window = this.options.fetchCoalesceMs ?? FETCH_COALESCE_MS;
         const reusable = current !== null &&
             !current.failed &&
+            (notBefore === undefined || current.startedAt >= notBefore) &&
             (current.completedAt === null ||
                 (Date.now() - current.completedAt < window && this.isCurrent(current.snapshot)));
         const job = reusable ? current : this.startGitHubFetch(resolve);
@@ -223,7 +232,7 @@ class LocalGitHubGateway {
     async afterGitHubFetch(join, fn) {
         for (let attempt = 1;; attempt++) {
             const snapshot = await join();
-            const result = await this.mirror.exclusive(async (session) => this.isCurrent(snapshot) ? { value: await fn(session) } : null);
+            const result = await this.mirror.exclusive(async (session) => this.isCurrent(snapshot) ? { value: await fn(session, snapshot) } : null);
             if (result !== null)
                 return result.value;
             if (attempt === 2) {
@@ -234,6 +243,7 @@ class LocalGitHubGateway {
     /** Start a GitHub fetch, taking its place at once, before the credential resolves. */
     startGitHubFetch(resolve) {
         let reachedGitHub = false;
+        const startedAt = Date.now();
         const run = async () => {
             const credential = await resolve();
             const own = {
@@ -248,12 +258,18 @@ class LocalGitHubGateway {
                 const pushes = this.pushes;
                 await this.mirror.heal(mirror, own);
                 await this.mirror.fetchFromGitHub(mirror, own);
-                return { generation: this.mirror.generation, pushes };
+                return { generation: this.mirror.generation, pushes, startedAt };
             });
             await this.mirror.afterFetch();
             return snapshot;
         };
-        const job = { failed: false, completedAt: null, snapshot: null, done: run() };
+        const job = {
+            failed: false,
+            completedAt: null,
+            snapshot: null,
+            startedAt,
+            done: run(),
+        };
         job.done.then((snapshot) => {
             job.completedAt = Date.now();
             job.snapshot = snapshot;
@@ -472,19 +488,20 @@ class LocalGitHubGateway {
         }
     }
     fetchOnce(request, signal) {
+        const notBefore = request.fresh ? Date.now() : undefined;
         const have = [...new Set(request.have)];
         if (have.length > MAX_FETCH_HAVE) {
             throw new Error(`A fetch takes at most ${MAX_FETCH_HAVE} have IDs, not ${have.length}`);
         }
         for (const id of have)
             assertObjectId(id);
-        return this.credentialed(signal, (reach) => this.afterGitHubFetch(() => this.joinGitHubFetch(() => this.credential(reach), signal), async (mirror) => {
+        return this.credentialed(signal, (reach) => this.afterGitHubFetch(() => this.joinGitHubFetch(() => this.credential(reach), signal, notBefore), async (mirror, snapshot) => {
             this.mirror.assertUsable();
             const refs = await mirror.heads();
             const file = await this.mirror.outgoingBundlePath();
             const created = await mirror.createBundle(have, file, signal);
             const bundleId = await this.mirror.setPendingBundle(created ? file : null);
-            return { refs, bundleId };
+            return { refs, bundleId, startedAt: snapshot.startedAt };
         }));
     }
     openBundle(bundleId) {
@@ -688,6 +705,7 @@ class LocalGitHubGateway {
                 body: ours ? (data.body ?? '') : null,
                 mergeable_state: data.mergeable_state,
                 baseRef: data.base.ref,
+                headSha: data.head.sha,
             };
         });
     }
@@ -726,6 +744,36 @@ class LocalGitHubGateway {
             await this.api(reach, () => this.octokit.graphql(`mutation($id: ID!) { convertPullRequestToDraft(input: { pullRequestId: $id }) { pullRequest { isDraft } } }`, { id: pr.node_id, request: { signal } }));
         });
     }
+    setConflictsStatus(status, signal) {
+        return this.credentialed(signal, async (reach) => {
+            const { pullRequest, sha, state, description, targetUrl } = status;
+            const refusing = `Refusing to set a status on pull request #${pullRequest}`;
+            const pr = await this.assertOwnPullRequest(reach, pullRequest, refusing, signal);
+            assertCommitStatusText(refusing, pr.head.ref, { description, targetUrl });
+            if (pr.head.sha !== sha) {
+                throw new GatewayRefusalError('commit-status', pr.head.ref, 'not-head', `${refusing}: ${sha.slice(0, 7)} is not its head, ${pr.head.sha.slice(0, 7)}`);
+            }
+            try {
+                await this.api(reach, () => this.octokit.repos.createCommitStatus({
+                    ...this.repo,
+                    sha,
+                    state,
+                    context: CONFLICTS_STATUS_CONTEXT,
+                    description,
+                    ...(targetUrl !== undefined && { target_url: targetUrl }),
+                    request: { signal },
+                }));
+            }
+            catch (err) {
+                // A credential without the Commit statuses permission, which the worker meets every cycle
+                // until it is granted: the `pulls.get` above just proved the credential works, so a
+                // re-read would only spend the refresh floor.
+                if (isPermissionDenial(err))
+                    reach.failed = false;
+                throw err;
+            }
+        });
+    }
     deleteBranch(branch, signal) {
         return this.credentialed(signal, async (reach) => {
             await assertPlainBranchName(branch, await this.mirror.checkGit(), 'delete');

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

@@ -12,11 +12,13 @@ export interface TransferContext {
 /**
  * Fetch every GitHub branch into `remote.git`'s tracking namespace (`GITHUB_TRACKING_REF_PREFIX`),
  * which then holds exactly GitHub's branches. `have` is every tip `remote.git` holds, so the
- * bundle carries only what it lacks. Returns GitHub's branches, and what an operator must fix in
- * remote.git for the namespace to keep up, if anything (see {@link moveTrackingRefs}).
+ * bundle carries only what it lacks. `fresh` takes no GitHub fetch the gateway began before this
+ * call. Returns GitHub's branches, when the GitHub fetch they come from began, and what an operator
+ * must fix in remote.git for the namespace to keep up, if anything (see {@link moveTrackingRefs}).
  */
-export declare function fetchGitHubIntoRemoteGit(ctx: TransferContext, signal?: AbortSignal): Promise<{
+export declare function fetchGitHubIntoRemoteGit(ctx: TransferContext, signal?: AbortSignal, fresh?: boolean): Promise<{
     refs: ReadonlyMap<string, string>;
+    fetchedAt: number;
     needsOperator: string | null;
 }>;
 /**