canopycms 0.8.0 → 0.8.2

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

@@ -18,6 +18,7 @@ export declare const pushRequest: z.ZodObject<{
     branch: z.ZodString;
     sha: z.ZodString;
     lease: z.ZodOptional<z.ZodString>;
+    seen: z.ZodOptional<z.ZodString>;
     prerequisites: z.ZodArray<z.ZodString, "many">;
     /** Whether the request body is a bundle; without one it is empty. */
     bundle: z.ZodBoolean;
@@ -26,12 +27,14 @@ export declare const pushRequest: z.ZodObject<{
     sha: string;
     prerequisites: string[];
     bundle: boolean;
+    seen?: string | undefined;
     lease?: string | undefined;
 }, {
     branch: string;
     sha: string;
     prerequisites: string[];
     bundle: boolean;
+    seen?: string | undefined;
     lease?: string | undefined;
 }>;
 export declare const requests: {
@@ -52,13 +55,13 @@ export declare const requests: {
         base: z.ZodString;
     }, "strict", z.ZodTypeAny, {
         title: string;
-        head: string;
         base: string;
+        head: string;
         body: string;
     }, {
         title: string;
-        head: string;
         base: string;
+        head: string;
         body: string;
     }>;
     readonly updatePullRequest: z.ZodObject<{
@@ -93,15 +96,15 @@ export declare const requests: {
         base: z.ZodString;
     }, "strict", z.ZodTypeAny, {
         title: string;
-        head: string;
         base: string;
+        head: string;
         body: string;
         markReadyIfDraft?: boolean | undefined;
         mergeSectionIntoBody?: boolean | undefined;
     }, {
         title: string;
-        head: string;
         base: string;
+        head: string;
         body: string;
         markReadyIfDraft?: boolean | undefined;
         mergeSectionIntoBody?: boolean | undefined;
@@ -206,18 +209,24 @@ export declare const answers: {
         state: z.ZodEnum<["open", "closed"]>;
         node_id: z.ZodString;
         body: z.ZodNullable<z.ZodString>;
+        mergeable_state: z.ZodOptional<z.ZodString>;
+        baseRef: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         merged: boolean;
         state: "open" | "closed";
         body: string | null;
         merged_at: string | null;
         node_id: string;
+        mergeable_state?: string | undefined;
+        baseRef?: string | undefined;
     }, {
         merged: boolean;
         state: "open" | "closed";
         body: string | null;
         merged_at: string | null;
         node_id: string;
+        mergeable_state?: string | undefined;
+        baseRef?: string | undefined;
     }>;
     readonly createOrUpdatePullRequest: z.ZodObject<{
         number: z.ZodNumber;
@@ -303,21 +312,21 @@ export declare const answers: {
             kind: z.ZodEnum<["auto-scaling", "spot"]>;
             reason: z.ZodString;
         }, "strict", z.ZodTypeAny, {
-            reason: string;
             kind: "auto-scaling" | "spot";
-        }, {
             reason: string;
+        }, {
             kind: "auto-scaling" | "spot";
+            reason: string;
         }>>;
     }, "strict", z.ZodTypeAny, {
         notice: {
-            reason: string;
             kind: "auto-scaling" | "spot";
+            reason: string;
         } | null;
     }, {
         notice: {
-            reason: string;
             kind: "auto-scaling" | "spot";
+            reason: string;
         } | null;
     }>;
     readonly completeLifecycle: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
@@ -422,28 +431,28 @@ declare const errorEnvelope: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     branch: string;
     push: boolean;
     message: string;
-    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
     kind: "refusal";
-    operation: "push" | "pull-request" | "delete";
+    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
+    operation: "push" | "delete" | "pull-request";
 }, {
     branch: string;
     push: boolean;
     message: string;
-    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
     kind: "refusal";
-    operation: "push" | "pull-request" | "delete";
+    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
+    operation: "push" | "delete" | "pull-request";
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"push">;
-    pushKind: z.ZodEnum<["rejected", "rejected-after-stale-lease"]>;
+    pushKind: z.ZodEnum<["rejected", "rejected-after-stale-lease", "seen-commit-gone"]>;
     message: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     message: string;
     kind: "push";
-    pushKind: "rejected" | "rejected-after-stale-lease";
+    pushKind: "rejected" | "rejected-after-stale-lease" | "seen-commit-gone";
 }, {
     message: string;
     kind: "push";
-    pushKind: "rejected" | "rejected-after-stale-lease";
+    pushKind: "rejected" | "rejected-after-stale-lease" | "seen-commit-gone";
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"transient">;
     code: z.ZodEnum<["github-fetch-failed", "bundle-rejected", "prerequisite-gone", "bundle-gone", "mirror-corrupt", "objects-still-needed", "ref-kept-moving", "default-branch-unread"]>;

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

@@ -43,6 +43,7 @@ export const pushRequest = z
     branch: name,
     sha: objectId,
     lease: objectId.optional(),
+    seen: objectId.optional(),
     prerequisites: z.array(objectId).max(3),
     /** Whether the request body is a bundle; without one it is empty. */
     bundle: z.boolean(),
@@ -111,6 +112,8 @@ export const answers = {
         state: z.enum(['open', 'closed']),
         node_id: z.string().max(256),
         body: pullRequestText.body.nullable(),
+        mergeable_state: z.string().max(64).optional(),
+        baseRef: z.string().max(256).optional(),
     })
         .strict(),
     createOrUpdatePullRequest: pullRequestRef.extend({ created: z.boolean() }).strict(),
@@ -250,7 +253,7 @@ const errorEnvelope = z.discriminatedUnion('kind', [
     z
         .object({
         kind: z.literal('push'),
-        pushKind: z.enum(['rejected', 'rejected-after-stale-lease']),
+        pushKind: z.enum(['rejected', 'rejected-after-stale-lease', 'seen-commit-gone']),
         message,
     })
         .strict(),

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

@@ -24,6 +24,12 @@ export interface GitHubPushRequest {
     sha: string;
     /** The commit GitHub must still be at for the push to replace it (`--force-with-lease`). */
     lease?: string;
+    /**
+     * The last commit the caller saw on GitHub's branch. A reset on GitHub leaves a tip the push
+     * would fast-forward, restoring what it removed, so a push is refused while GitHub's branch
+     * doesn't contain this commit.
+     */
+    seen?: string;
     /**
      * At most {@link MAX_PUSH_PREREQUISITES} commits the caller would build a bundle of the branch
      * on, so an answer of `need-objects` can say which of them the gateway can use.
@@ -50,13 +56,14 @@ export type GitHubPushAnswer = ({
 };
 /**
  * A push to GitHub failed: `rejected` on the first attempt, `rejected-after-stale-lease` on the
- * plain retry after GitHub refused a stale lease. The message is the failure's own: git's output,
- * for a refusal, which the task runner classifies. A {@link RefusedPushError} from the first
- * attempt is thrown as itself.
+ * plain retry after GitHub refused a stale lease, `seen-commit-gone` before any attempt, when
+ * GitHub's branch no longer holds {@link GitHubPushRequest.seen}. The message is the failure's
+ * own: git's output, for a refusal, which the task runner classifies. A {@link RefusedPushError}
+ * from the first attempt is thrown as itself.
  */
 export declare class GitHubPushError extends Error {
-    readonly kind: 'rejected' | 'rejected-after-stale-lease';
-    constructor(kind: 'rejected' | 'rejected-after-stale-lease', message: string);
+    readonly kind: 'rejected' | 'rejected-after-stale-lease' | 'seen-commit-gone';
+    constructor(kind: 'rejected' | 'rejected-after-stale-lease' | 'seen-commit-gone', message: string);
 }
 /** A moved ref for a log line: `<old7>..<new7>`, or `new branch at <new7>`. */
 export declare function describeMove(update: Extract<GitHubRefUpdate, {
@@ -70,6 +77,10 @@ export type GitHubPullRequest = Pick<RestEndpointMethodTypes['pulls']['get']['re
      * request a person opened from a branch in the namespace has its body answered.
      */
     body: string | null;
+    /** GitHub's own word on what stands between the pull request and a merge; `behind` needs the base. */
+    mergeable_state?: string;
+    /** The branch the pull request merges into on GitHub, which a person can change. */
+    baseRef?: string;
 };
 export type GitHubCreateOrUpdatePullRequest = Omit<CreateOrUpdatePullRequestParams, 'octokit' | 'owner' | 'repo' | 'signal'>;
 /**

package/dist/worker/github-gateway.js

@@ -30,9 +30,10 @@ const MAX_PUSH_PREREQUISITES = 3;
 const DEFAULT_MAX_BUNDLE_BYTES = 1024 * 1024 * 1024;
 /**
  * A push to GitHub failed: `rejected` on the first attempt, `rejected-after-stale-lease` on the
- * plain retry after GitHub refused a stale lease. The message is the failure's own: git's output,
- * for a refusal, which the task runner classifies. A {@link RefusedPushError} from the first
- * attempt is thrown as itself.
+ * plain retry after GitHub refused a stale lease, `seen-commit-gone` before any attempt, when
+ * GitHub's branch no longer holds {@link GitHubPushRequest.seen}. The message is the failure's
+ * own: git's output, for a refusal, which the task runner classifies. A {@link RefusedPushError}
+ * from the first attempt is thrown as itself.
  */
 export class GitHubPushError extends Error {
     constructor(kind, message) {
@@ -498,6 +499,8 @@ class LocalGitHubGateway {
         assertObjectId(request.sha, 'a commit ID');
         if (request.lease !== undefined)
             assertObjectId(request.lease, 'a commit ID');
+        if (request.seen !== undefined)
+            assertObjectId(request.seen, 'a commit ID');
         if (request.prerequisites.length > MAX_PUSH_PREREQUISITES) {
             throw new Error(`A push names at most ${MAX_PUSH_PREREQUISITES} prerequisites`);
         }
@@ -513,6 +516,10 @@ class LocalGitHubGateway {
         // and sessions are not re-entrant. So does resolving the credential, so the session never
         // waits on GitHub's API. A body is read first, so its writer is not left waiting.
         const session = (received) => this.afterGitHubFetch(async () => {
+            // A reused fetch can predate a reset, whose heads would still show the commit `seen`
+            // names. Nothing moved at GitHub, so this ends the reuse and leaves other fetches good.
+            if (request.seen !== undefined)
+                this.githubFetch = null;
             const snapshot = await this.joinGitHubFetchForPush(credential, request.branch, signal);
             await credential();
             return snapshot;
@@ -573,8 +580,15 @@ class LocalGitHubGateway {
         else {
             repo = await mirror.quarantine(received, request, heads, signal);
         }
-        const attempt = (lease) => mirror.pushToGitHub(credential, branch, sha, {
+        const tip = heads.get(branch);
+        if (request.seen !== undefined &&
+            tip !== undefined &&
+            !(await mirror.historyHolds(tip, request.seen))) {
+            throw new GitHubPushError('seen-commit-gone', `GitHub's ${branch} no longer contains ${request.seen}, the last commit seen there`);
+        }
+        const attempt = (lease, pin) => mirror.pushToGitHub(credential, branch, sha, {
             lease,
+            pin,
             signal,
             repo,
             policy: this.policy,
@@ -582,7 +596,8 @@ class LocalGitHubGateway {
             onPushing: () => this.invalidateGitHubFetch(),
         });
         try {
-            return { kind: 'pushed', ...(await attempt(request.lease)), pastStaleLease: false };
+            const pin = request.seen === undefined || request.lease !== undefined ? undefined : tip;
+            return { kind: 'pushed', ...(await attempt(request.lease, pin)), pastStaleLease: false };
         }
         catch (err) {
             if (err instanceof RefusedPushError || err instanceof GitHubTransientError)
@@ -671,6 +686,8 @@ class LocalGitHubGateway {
                 state: data.state,
                 node_id: data.node_id,
                 body: ours ? (data.body ?? '') : null,
+                mergeable_state: data.mergeable_state,
+                baseRef: data.base.ref,
             };
         });
     }

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

@@ -294,6 +294,8 @@ export declare class MirrorSession {
     reachableFromHeads(sha: string): Promise<boolean>;
     /** Of `prerequisites`, the commits a GitHub branch contained at the last fetch. */
     usablePrerequisites(prerequisites: readonly string[]): Promise<string[]>;
+    /** Whether `tip`'s history holds `commit`. One the mirror doesn't hold, GitHub's heads don't. */
+    historyHolds(tip: string, commit: string): Promise<boolean>;
     /**
      * Whether every one of `commits` is reachable from one of `tips`, in ONE walk: rev-list fed the
      * commits and a `^<tip>` per tip lists what the tips do not reach, so empty output means all
@@ -337,6 +339,12 @@ export declare class MirrorSession {
      */
     pushToGitHub(credential: GitHubCredential, branch: string, sha: string, options: {
         lease?: string;
+        /**
+         * The tip a caller's check saw. A reset to an ancestor of `sha` after that check would
+         * otherwise take a plain push, so a push that fast-forwards this tip carries it as a lease,
+         * which forces nothing there and is refused if the ref moved.
+         */
+        pin?: string;
         signal?: AbortSignal;
         repo?: string;
         policy: BranchPolicy;

package/dist/worker/github-mirror.js

@@ -775,6 +775,12 @@ export class MirrorSession {
         }
         return usable;
     }
+    /** Whether `tip`'s history holds `commit`. One the mirror doesn't hold, GitHub's heads don't. */
+    async historyHolds(tip, commit) {
+        if ((await this.objectTypes([commit])).get(commit) !== 'commit')
+            return false;
+        return this.allReachable([commit], [tip]);
+    }
     /**
      * Whether every one of `commits` is reachable from one of `tips`, in ONE walk: rev-list fed the
      * commits and a `^<tip>` per tip lists what the tips do not reach, so empty output means all
@@ -902,12 +908,17 @@ export class MirrorSession {
                 throw new RefusedPushError(branch, 'invalid', undefined, branchInsideMessage(branch, inside));
             }
         }
+        const pinned = options.pin !== undefined &&
+            (await this.run(['rev-list', '--max-count=1', '--end-of-options', options.pin, `^${sha}`], {
+                repo: options.repo,
+            })) === '';
+        const lease = options.lease ?? (pinned ? options.pin : undefined);
         options.onPushing?.();
         const status = await this.githubBound(credential, [
             'push',
             '--porcelain',
             '--progress',
-            ...(options.lease ? [`--force-with-lease=refs/heads/${branch}:${options.lease}`] : []),
+            ...(lease ? [`--force-with-lease=refs/heads/${branch}:${lease}`] : []),
             '--end-of-options',
             credential.url,
             `${sha}:refs/heads/${branch}`,

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

@@ -32,7 +32,9 @@ export declare function seedFromGitHub(ctx: TransferContext, gitDir: string, bas
  */
 export declare function unreachableFrom(ctx: TransferContext, gitDir: string, ids: readonly string[], tips: readonly string[]): Promise<Set<string>>;
 /** A push to GitHub of the commit `readSha` finds, as {@link pushToGitHub} takes it. */
-export interface TransferPushRequest extends Omit<GitHubPushRequest, 'sha' | 'prerequisites'> {
+export interface TransferPushRequest extends Omit<GitHubPushRequest, 'sha' | 'prerequisites' | 'seen'> {
+    /** {@link GitHubPushRequest.seen}, read after each attempt's commit, as the two go together. */
+    readSeen?: () => Promise<string | undefined>;
     /**
      * Branches whose GitHub tips, as `remote.git`'s tracking namespace holds them, a bundle of
      * `branch` is built on: the branch itself, and the base for a content branch. Missing ones are

package/dist/worker/github-transfer.js

@@ -109,11 +109,12 @@ export async function unreachableFrom(ctx, gitDir, ids, tips) {
  * {@link MAX_PUSH_RESTARTS} times, so a ref moved on every pass cannot hold a task for ever.
  */
 export async function pushToGitHub(ctx, request, readSha, signal) {
-    const { prerequisiteBranches, ...rest } = request;
+    const { prerequisiteBranches, readSeen, ...rest } = request;
     for (let restarts = 0;; restarts++) {
         const sha = await readSha();
+        const seen = await readSeen?.();
         const prerequisites = await trackingTips(ctx.remoteGitPath, prerequisiteBranches);
-        const ask = { ...rest, sha, prerequisites };
+        const ask = { ...rest, sha, ...(seen ? { seen } : {}), prerequisites };
         const first = await ctx.github().push(ask, undefined, signal);
         if (first.kind === 'pushed')
             return { sha, outcome: outcomeOf(first) };

package/dist/worker/history-rewrite.d.ts

@@ -44,11 +44,15 @@ export declare function readPublishedSha(ctx: Pick<HistoryRewriteContext, 'remot
  * caller's snapshot: the task loop runs concurrently with syncGit() and may
  * have cleared the marker while this branch was rebasing.
  *
+ * `rewrittenTip` goes in the same write as `lastGitHubTip`, so a push that lands
+ * and dies before its stamp is never read as someone rewriting the branch on
+ * GitHub (github-commits.ts).
+ *
  * Resolves whether `branchRef`'s branch.json now holds a marker, set here or kept by set-once.
  * When it does not, the caller publishes nothing: a rewrite pushed without its marker leaves
  * remote.git rewritten and the queued GitHub push failing with a false divergence diagnosis.
  */
-export declare function markHistoryRewritten(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchPath: string, branchRef: string, expectedSha: string): Promise<boolean>;
+export declare function markHistoryRewritten(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchPath: string, branchRef: string, expectedSha: string, rewrittenTip: string): Promise<boolean>;
 /**
  * Clear the marker once GitHub is confirmed to hold the rewritten history.
  *
@@ -126,3 +130,11 @@ export declare function reconcilePendingRewrite(ctx: HistoryRewriteContext, opti
  * louder `diverged` bucket.
  */
 export declare function hasPendingHistoryRewrite(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchName: string): Promise<boolean>;
+/**
+ * Records that GitHub's `branchName` holds `sha`, in `lastGitHubTip`. It runs before `remote.git`
+ * takes the commit, so `remote.git` never holds a GitHub commit the record doesn't name: a clone
+ * can lag `remote.git` for as long as it stays busy, and once GitHub drops that commit it could not
+ * be told from the branch's own work (github-commits.ts). A branch name with no workspace has no
+ * record, and a directory whose branch.json names another ref is that ref's.
+ */
+export declare function recordSeenOnGitHub(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchName: string, sha: string): Promise<void>;

package/dist/worker/history-rewrite.js

@@ -47,18 +47,28 @@ export async function readPublishedSha(ctx, branchRef) {
  * caller's snapshot: the task loop runs concurrently with syncGit() and may
  * have cleared the marker while this branch was rebasing.
  *
+ * `rewrittenTip` goes in the same write as `lastGitHubTip`, so a push that lands
+ * and dies before its stamp is never read as someone rewriting the branch on
+ * GitHub (github-commits.ts).
+ *
  * Resolves whether `branchRef`'s branch.json now holds a marker, set here or kept by set-once.
  * When it does not, the caller publishes nothing: a rewrite pushed without its marker leaves
  * remote.git rewritten and the queued GitHub push failing with a false divergence diagnosis.
  */
-export async function markHistoryRewritten(ctx, branchPath, branchRef, expectedSha) {
+export async function markHistoryRewritten(ctx, branchPath, branchRef, expectedSha, rewrittenTip) {
     const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
     let marked = false;
     await meta.update((current) => {
         marked = current?.branch.name === branchRef;
-        if (!marked || typeof current?.branch.historyRewrittenFrom === 'string')
+        if (!marked)
             return null;
-        return { branch: { historyRewrittenFrom: expectedSha } };
+        const marker = current?.branch.historyRewrittenFrom;
+        return {
+            branch: {
+                historyRewrittenFrom: typeof marker === 'string' ? marker : expectedSha,
+                lastGitHubTip: rewrittenTip,
+            },
+        };
     });
     return marked;
 }
@@ -226,3 +236,17 @@ export async function hasPendingHistoryRewrite(ctx, branchName) {
         return false;
     }
 }
+/**
+ * Records that GitHub's `branchName` holds `sha`, in `lastGitHubTip`. It runs before `remote.git`
+ * takes the commit, so `remote.git` never holds a GitHub commit the record doesn't name: a clone
+ * can lag `remote.git` for as long as it stays busy, and once GitHub drops that commit it could not
+ * be told from the branch's own work (github-commits.ts). A branch name with no workspace has no
+ * record, and a directory whose branch.json names another ref is that ref's.
+ */
+export async function recordSeenOnGitHub(ctx, branchName, sha) {
+    const branchPath = path.join(ctx.contentBranchesPath, sanitizeBranchName(branchName));
+    const metaFile = await BranchMetadataFileManager.loadOnly(branchPath);
+    if (metaFile?.branch.name !== branchName)
+        return;
+    await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).update((current) => (current?.branch.name === branchName ? { branch: { lastGitHubTip: sha } } : null), { keepUpdatedAt: true });
+}

package/dist/worker/rebase.d.ts

@@ -1,5 +1,7 @@
 import { type BranchMetadataFile } from '../branch-metadata.js';
-import type { BranchPolicyDescription } from './branch-policy.js';
+import { type BranchPolicyDescription } from './branch-policy.js';
+import type { GitHubPullRequest } from './github-gateway.js';
+import { type GitHubSnapshot } from './github-commits.js';
 import type { WorkerContext } from './worker-context.js';
 /**
  * The rebase loop: the deepest leaf of the git-sync cluster, and the most
@@ -16,12 +18,16 @@ import type { WorkerContext } from './worker-context.js';
  * - it carries a rewritten history forward into remote.git and GitHub under a
  *   lease keyed to the exact commit it replaced ([SYNC-H1], history-rewrite.ts).
  *
+ * Ahead of the rebase it brings commits made on GitHub into the clone, for every
+ * status (github-commits.ts): the rebase would otherwise rewrite the clone away
+ * from a tip it never had.
+ *
  * `pollMergeState` lives here rather than in git-sync.ts because the rebase
  * loop is its only caller: submitted/approved branches are skipped for rebasing
  * but still need their PR's resolution polled, and this loop is the only thing
  * that walks every branch workspace.
  */
-export type RebaseContext = Pick<WorkerContext, 'baseBranch' | 'sanitizedBaseBranch' | 'contentBranchesPath' | 'contentRoot' | 'remoteGitPath' | 'taskDir' | 'taskTimeoutMs' | 'github' | 'afterConflictDetectedForTesting' | 'afterRebaseCompletedForTesting' | 'ensureSettingsBranch' | 'isDraining'>;
+export type RebaseContext = Pick<WorkerContext, 'baseBranch' | 'sanitizedBaseBranch' | 'contentBranchesPath' | 'contentRoot' | 'remoteGitPath' | 'taskDir' | 'taskTimeoutMs' | 'github' | 'ensureStatusReport' | 'afterConflictDetectedForTesting' | 'afterRebaseCompletedForTesting' | 'ensureSettingsBranch' | 'isDraining'>;
 /**
  * Per-cycle outcome of `rebaseActiveBranches()`, folded by `syncGit()` into the
  * worker's self-reported status (`WorkerStatusReport.lastGitSync`, see
@@ -29,8 +35,8 @@ export type RebaseContext = Pick<WorkerContext, 'baseBranch' | 'sanitizedBaseBra
  */
 export interface RebaseSummary {
     /**
-     * Branches that were behind and completed a rebase onto the base branch,
-     * whether or not conflicts were resolved via --theirs. Branches already up to
+     * Branches that were behind and caught up with the base branch, by a rebase or
+     * by merging it, whether or not conflicts were resolved. Branches already up to
      * date are NOT listed here.
      */
     rebased: string[];
@@ -64,9 +70,9 @@ export interface RebaseSummary {
  * markAsMerged API so both paths produce identical archived-branch metadata.
  * closed-without-merge -> record pullRequestState only; an admin decides the
  * workflow transition. Best-effort: a failure is logged, swallowed and retried
- * next sync cycle.
+ * next sync cycle. Resolves GitHub's answer for a pull request not merged.
  */
-export declare function pollMergeState(ctx: RebaseContext, branchDir: string, branchPath: string, metaFile: BranchMetadataFile | null): Promise<void>;
+export declare function pollMergeState(ctx: RebaseContext, branchDir: string, branchPath: string, metaFile: BranchMetadataFile | null): Promise<GitHubPullRequest | null>;
 /**
  * Rebase every branch workspace that is behind the base branch, one cycle.
  *
@@ -79,4 +85,4 @@ export declare function pollMergeState(ctx: RebaseContext, branchDir: string, br
  * that branch's cross-host content-write lock and runs a series of git
  * subprocesses against a shared filesystem.
  */
-export declare function runRebaseCycle(ctx: RebaseContext, gatewayPolicy?: BranchPolicyDescription): Promise<RebaseSummary>;
+export declare function runRebaseCycle(ctx: RebaseContext, gatewayPolicy?: BranchPolicyDescription, gitHub?: GitHubSnapshot): Promise<RebaseSummary>;