canopycms 0.7.1 → 0.8.1

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

@@ -131,34 +131,49 @@ export declare const answers: {
         fatalError: z.ZodNullable<z.ZodString>;
         preflight: z.ZodEnum<["not-an-app", "verified", "unverified", "pending"]>;
         clerkConfigured: z.ZodBoolean;
-        protectedBranches: z.ZodObject<{
+        branchPolicy: z.ZodObject<{
             configured: z.ZodArray<z.ZodString, "many">;
             githubDefault: z.ZodNullable<z.ZodString>;
+            namespace: z.ZodString;
+            legacy: z.ZodArray<z.ZodString, "many">;
+            settingsBranch: z.ZodNullable<z.ZodString>;
         }, "strict", z.ZodTypeAny, {
+            settingsBranch: string | null;
+            namespace: string;
+            legacy: string[];
             configured: string[];
             githubDefault: string | null;
         }, {
+            settingsBranch: string | null;
+            namespace: string;
+            legacy: string[];
             configured: string[];
             githubDefault: string | null;
         }>;
     }, "strict", z.ZodTypeAny, {
         ready: boolean;
-        protectedBranches: {
-            configured: string[];
-            githubDefault: string | null;
-        };
         preflight: "pending" | "not-an-app" | "verified" | "unverified";
         fatalError: string | null;
         clerkConfigured: boolean;
-    }, {
-        ready: boolean;
-        protectedBranches: {
+        branchPolicy: {
+            settingsBranch: string | null;
+            namespace: string;
+            legacy: string[];
             configured: string[];
             githubDefault: string | null;
         };
+    }, {
+        ready: boolean;
         preflight: "pending" | "not-an-app" | "verified" | "unverified";
         fatalError: string | null;
         clerkConfigured: boolean;
+        branchPolicy: {
+            settingsBranch: string | null;
+            namespace: string;
+            legacy: string[];
+            configured: string[];
+            githubDefault: string | null;
+        };
     }>;
     readonly defaultBranch: z.ZodObject<{
         branch: z.ZodString;
@@ -227,13 +242,13 @@ export declare const answers: {
             email: z.ZodString;
             avatarUrl: z.ZodOptional<z.ZodString>;
         }, "strict", z.ZodTypeAny, {
-            name: string;
             id: string;
+            name: string;
             email: string;
             avatarUrl?: string | undefined;
         }, {
-            name: string;
             id: string;
+            name: string;
             email: string;
             avatarUrl?: string | undefined;
         }>, "many">;
@@ -243,41 +258,41 @@ export declare const answers: {
             description: z.ZodOptional<z.ZodString>;
             memberCount: z.ZodOptional<z.ZodNumber>;
         }, "strict", z.ZodTypeAny, {
-            name: string;
             id: string;
+            name: string;
             description?: string | undefined;
             memberCount?: number | undefined;
         }, {
-            name: string;
             id: string;
+            name: string;
             description?: string | undefined;
             memberCount?: number | undefined;
         }>, "many">;
         memberships: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
         groups: {
-            name: string;
             id: string;
+            name: string;
             description?: string | undefined;
             memberCount?: number | undefined;
         }[];
         users: {
-            name: string;
             id: string;
+            name: string;
             email: string;
             avatarUrl?: string | undefined;
         }[];
         memberships: Record<string, string[]>;
     }, {
         groups: {
-            name: string;
             id: string;
+            name: string;
             description?: string | undefined;
             memberCount?: number | undefined;
         }[];
         users: {
-            name: string;
             id: string;
+            name: string;
             email: string;
             avatarUrl?: string | undefined;
         }[];
@@ -325,11 +340,11 @@ export declare const fetchPoll: z.ZodDiscriminatedUnion<"state", [z.ZodObject<{
     state: z.ZodLiteral<"running">;
     progress: z.ZodNumber;
 }, "strict", z.ZodTypeAny, {
-    progress: number;
     state: "running";
-}, {
     progress: number;
+}, {
     state: "running";
+    progress: number;
 }>, z.ZodObject<{
     state: z.ZodLiteral<"done">;
     progress: z.ZodNumber;
@@ -337,13 +352,13 @@ export declare const fetchPoll: z.ZodDiscriminatedUnion<"state", [z.ZodObject<{
     refs: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>, "many">;
     bundleId: z.ZodNullable<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    progress: number;
     state: "done";
+    progress: number;
     refs: [string, string][];
     bundleId: string | null;
 }, {
-    progress: number;
     state: "done";
+    progress: number;
     refs: [string, string][];
     bundleId: string | null;
 }>]>;
@@ -401,22 +416,22 @@ declare const errorEnvelope: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     push: z.ZodBoolean;
     operation: z.ZodEnum<["push", "delete", "pull-request"]>;
     branch: z.ZodString;
-    reason: z.ZodEnum<["invalid", "protected", "settings", "not-a-commit", "too-long"]>;
+    reason: z.ZodEnum<["invalid", "protected", "settings", "other-settings", "outside-namespace", "not-a-commit", "too-long"]>;
     message: z.ZodString;
 }, "strict", z.ZodTypeAny, {
+    branch: string;
     push: boolean;
     message: string;
-    branch: string;
-    reason: "settings" | "protected" | "invalid" | "not-a-commit" | "too-long";
+    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
     kind: "refusal";
-    operation: "push" | "pull-request" | "delete";
+    operation: "push" | "delete" | "pull-request";
 }, {
+    branch: string;
     push: boolean;
     message: string;
-    branch: string;
-    reason: "settings" | "protected" | "invalid" | "not-a-commit" | "too-long";
+    reason: "settings" | "protected" | "invalid" | "other-settings" | "outside-namespace" | "not-a-commit" | "too-long";
     kind: "refusal";
-    operation: "push" | "pull-request" | "delete";
+    operation: "push" | "delete" | "pull-request";
 }>, z.ZodObject<{
     kind: z.ZodLiteral<"push">;
     pushKind: z.ZodEnum<["rejected", "rejected-after-stale-lease"]>;

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { GatewayRefusalError, MAX_PROTECTED_BRANCHES } from './branch-policy.js';
+import { GatewayRefusalError, MAX_LEGACY_BRANCHES, MAX_PROTECTED_BRANCHES } from './branch-policy.js';
 import { GitHubPushError, MAX_FETCH_HAVE } from './github-gateway.js';
 import { GitHubTransientError, RefusedPushError } from './github-mirror.js';
 import { gatewayLogWarn, redactEgress } from './gateway-egress.js';
@@ -89,10 +89,13 @@ export const answers = {
         fatalError: message.nullable(),
         preflight: z.enum(['not-an-app', 'verified', 'unverified', 'pending']),
         clerkConfigured: z.boolean(),
-        protectedBranches: z
+        branchPolicy: z
             .object({
             configured: z.array(name).max(MAX_PROTECTED_BRANCHES + 1),
             githubDefault: name.nullable(),
+            namespace: name,
+            legacy: z.array(name).max(MAX_LEGACY_BRANCHES),
+            settingsBranch: name.nullable(),
         })
             .strict(),
     })
@@ -232,7 +235,15 @@ const errorEnvelope = z.discriminatedUnion('kind', [
         push: z.boolean(),
         operation: z.enum(['push', 'delete', 'pull-request']),
         branch: name,
-        reason: z.enum(['invalid', 'protected', 'settings', 'not-a-commit', 'too-long']),
+        reason: z.enum([
+            'invalid',
+            'protected',
+            'settings',
+            'other-settings',
+            'outside-namespace',
+            'not-a-commit',
+            'too-long',
+        ]),
         message,
     })
         .strict(),

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

@@ -4,6 +4,7 @@ import type { AuthCacheSnapshot } from '../auth/cache.js';
 import { type CreateOrUpdatePullRequestParams } from '../github-service.js';
 import { type ResolvedGitHubAuth } from './github-auth.js';
 import { type GitHubRefUpdate } from './github-mirror.js';
+import { type BranchPolicyDescription } from './branch-policy.js';
 import { type GatewayInstanceOptions } from './gateway-instance.js';
 /** What a {@link GitHubGateway.fetch} brought back. */
 export interface GitHubFetchResult {
@@ -62,7 +63,14 @@ export declare function describeMove(update: Extract<GitHubRefUpdate, {
     moved: true;
 }>): string;
 /** The fields of a pull request the worker reads. */
-export type GitHubPullRequest = Pick<RestEndpointMethodTypes['pulls']['get']['response']['data'], 'merged' | 'merged_at' | 'state' | 'node_id' | 'body'>;
+export type GitHubPullRequest = Pick<RestEndpointMethodTypes['pulls']['get']['response']['data'], 'merged' | 'merged_at' | 'state' | 'node_id'> & {
+    /**
+     * The pull request's body, `''` when it has none. `null` when the gateway withholds it, as it
+     * does for every pull request it would not update (`LocalGitHubGateway.getPullRequest`). A pull
+     * request a person opened from a branch in the namespace has its body answered.
+     */
+    body: string | null;
+};
 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.
@@ -178,11 +186,8 @@ export interface GitHubGatewayHealth {
     preflight: 'not-an-app' | 'verified' | 'unverified' | 'pending';
     /** Whether the gateway holds a Clerk secret key. */
     clerkConfigured: boolean;
-    /** The protected set (worker/branch-policy.ts): configured names and globs, and GitHub's default as last read. */
-    protectedBranches: {
-        configured: string[];
-        githubDefault: string | null;
-    };
+    /** The branch policy as it stands (`BranchPolicy.describe`). */
+    branchPolicy: BranchPolicyDescription;
 }
 /** `GatewayInstanceOptions` carries the termination watch and the lifecycle completion. */
 export interface LocalGitHubGatewayOptions extends GatewayInstanceOptions {
@@ -211,6 +216,12 @@ export interface LocalGitHubGatewayOptions extends GatewayInstanceOptions {
     baseBranch?: string;
     /** Further branches it protects alike: names and `*` globs (worker/branch-policy.ts). */
     protectedBranches?: readonly string[];
+    /** This deployment's settings branch, the only settings branch the gateway pushes. */
+    settingsBranch?: string;
+    /** The branch namespace it writes, resolved (operating-mode/branch-namespace.ts). */
+    branchNamespace?: string;
+    /** Branches outside the namespace it may still write: exact names (worker/branch-policy.ts). */
+    legacyBranches?: readonly string[];
     /**
      * Fetches the auth provider's snapshot with the provider's key; its presence is
      * `health().clerkConfigured`. Without it, `authSnapshot()` throws.

package/dist/worker/github-gateway.js

@@ -5,7 +5,7 @@ import { getErrorMessage } from '../utils/error.js';
 import { isStaleLeaseRejection, workflowPushRefusalFile } from '../utils/git.js';
 import { isTransientAuthFailure } from './github-auth.js';
 import { GitHubMirror, GitHubTransientError, RefusedPushError, assertPlainBranchName, isObjectId, } from './github-mirror.js';
-import { BranchPolicy, GatewayRefusalError, assertPullRequestText } from './branch-policy.js';
+import { BranchPolicy, GatewayRefusalError, 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. */
@@ -78,6 +78,9 @@ class LocalGitHubGateway {
         this.policy = new BranchPolicy({
             baseBranch: options.baseBranch,
             protectedBranches: options.protectedBranches,
+            settingsBranch: options.settingsBranch,
+            legacyBranches: options.legacyBranches,
+            namespace: options.branchNamespace,
         });
     }
     get repo() {
@@ -341,7 +344,7 @@ class LocalGitHubGateway {
             fatalError,
             preflight: this.preflight,
             clerkConfigured: this.options.authSnapshot !== undefined,
-            protectedBranches: this.policy.describe(),
+            branchPolicy: this.policy.describe(),
         };
     }
     /**
@@ -618,7 +621,9 @@ class LocalGitHubGateway {
     }
     updatePullRequest(number, update, signal) {
         return this.credentialed(signal, async (reach) => {
-            assertPullRequestText(`Refusing to update pull request #${number}`, `#${number}`, update);
+            const refusing = `Refusing to ${update.state === 'closed' ? 'close' : 'update'} pull request #${number}`;
+            assertPullRequestText(refusing, `#${number}`, update);
+            await this.assertOwnPullRequest(reach, number, refusing, signal);
             await this.api(reach, () => this.octokit.pulls.update({
                 ...this.repo,
                 pull_number: number,
@@ -627,11 +632,62 @@ class LocalGitHubGateway {
             }));
         });
     }
+    /**
+     * Pull request `number`'s merge state, for any number, and its body only when `updatePullRequest`
+     * would take its head: a branch of this repository that `BranchPolicy.takesPullRequestFrom`
+     * admits (the namespace or a `legacyBranches` entry) and that is not protected, whoever opened
+     * the pull request. Withholding more would protect nothing a write cannot change. When GitHub's
+     * default branch cannot be read, the configured protected set and the default as last read
+     * decide. The number comes from the worker, which a compromised CMS Lambda can steer; the head is
+     * GitHub's record.
+     */
     getPullRequest(number, signal) {
-        return this.credentialed(signal, (reach) => this.pullRequest(reach, number, signal));
+        return this.credentialed(signal, async (reach) => {
+            const { data } = await this.api(reach, () => this.octokit.pulls.get({ ...this.repo, pull_number: number, request: { signal } }));
+            const head = data.head.ref;
+            // By id, as `assertOwnPullRequest` compares; a deleted fork has no repo. A protected head is
+            // one the gateway refuses to update the pull request of, so its body is withheld too.
+            let ours = data.head.repo?.id === data.base.repo.id && this.policy.takesPullRequestFrom(head);
+            if (ours) {
+                try {
+                    ours = !(await this.policy.isProtected(head, () => this.readDefaultBranch(reach, signal)));
+                }
+                catch (err) {
+                    // `isProtected` reads GitHub only for a head the configured set (the base branch and
+                    // each `protectedBranches` entry) does not cover. The merge poll needs the merge state,
+                    // so an unread default branch leaves the body to that set and to the default as last
+                    // read, however old: `updatePullRequest` judges the head again before writing it.
+                    if (signal?.aborted)
+                        throw err;
+                    if (this.policy.matchesLastReadDefault(head))
+                        ours = false;
+                    gatewayLogWarn(`Could not read GitHub's default branch for pull request #${number} ` +
+                        `(${redactEgress(getErrorMessage(err))}); judging its head by the configured protected set and the default as last read`);
+                }
+            }
+            return {
+                merged: data.merged,
+                merged_at: data.merged_at,
+                state: data.state,
+                node_id: data.node_id,
+                body: ours ? (data.body ?? '') : null,
+            };
+        });
     }
-    async pullRequest(reach, number, signal) {
+    /**
+     * Read pull request `number` and refuse it unless its head is a branch of this repository that
+     * a pull request may come from (`BranchPolicy.assertPullRequestHeadAllowed`). The number comes
+     * from the worker; the head is GitHub's record, which the worker cannot choose.
+     */
+    async assertOwnPullRequest(reach, number, refusing, signal) {
         const { data } = await this.api(reach, () => this.octokit.pulls.get({ ...this.repo, pull_number: number, request: { signal } }));
+        const head = data.head.ref;
+        // By id, not name: the configured name keeps working after a rename or transfer, and the base
+        // repository is the one asked. A deleted fork has no repo.
+        if (data.head.repo?.id !== data.base.repo.id) {
+            throw new GatewayRefusalError('pull-request', head, 'outside-namespace', `${refusing}: its head is not a branch of this repository`);
+        }
+        await this.policy.assertPullRequestHeadAllowed(`${refusing}, whose head is ${JSON.stringify(head)}`, head, () => this.readDefaultBranch(reach, signal));
         return data;
     }
     createOrUpdatePullRequest(request, signal) {
@@ -649,7 +705,7 @@ class LocalGitHubGateway {
     convertPullRequestToDraft(number, signal) {
         return this.credentialed(signal, async (reach) => {
             // The REST API cannot convert a PR to a draft; GraphQL can.
-            const pr = await this.pullRequest(reach, number, signal);
+            const pr = await this.assertOwnPullRequest(reach, number, `Refusing to convert pull request #${number} to a draft`, signal);
             await this.api(reach, () => this.octokit.graphql(`mutation($id: ID!) { convertPullRequestToDraft(input: { pullRequestId: $id }) { pullRequest { isDraft } } }`, { id: pr.node_id, request: { signal } }));
         });
     }

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

@@ -1,7 +1,7 @@
 import type { Readable } from 'node:stream';
 import { type SimpleGit } from 'simple-git';
 import { type BundleHeader } from './bundle-header.js';
-import { BranchPolicy, GatewayRefusalError } from './branch-policy.js';
+import { BranchPolicy, GatewayRefusalError, type PushPolicyRefusal } from './branch-policy.js';
 /**
  * The worker's private bare mirror of the GitHub repository, in a state directory the CMS Lambda
  * cannot reach. It and the quarantines beside it are the only repositories in which git ever runs
@@ -222,11 +222,14 @@ export interface GitHubCredential {
  */
 export declare function isOwnLockFailure(message: string): boolean;
 /**
- * A push the worker never makes: to a name that is not a plain branch name, to a protected branch
- * (`BranchPolicy`), to a settings branch under a lease, or of an object that is not a commit.
+ * A push the worker never makes: to a name that is not a plain branch name, one the policy refuses
+ * (`BranchPolicy.assertPushAllowed`, which owns those messages), or of an object that is not a
+ * commit.
  */
 export declare class RefusedPushError extends GatewayRefusalError {
-    constructor(branch: string, reason: 'invalid' | 'protected' | 'settings' | 'not-a-commit', sha?: string);
+    constructor(branch: string, reason: 'invalid' | PushPolicyRefusal | 'not-a-commit', sha?: string, 
+    /** The policy's own message, which names the namespace (`pushRefusalMessage`). */
+    message?: string);
 }
 /**
  * Throw {@link RefusedPushError} (or, for another `operation`, {@link GatewayRefusalError}) unless

package/dist/worker/github-mirror.js

@@ -7,7 +7,7 @@ import { getErrorMessage } from '../utils/error.js';
 import { BundleHeaderError, BundleHeaderReader, hasOnlyHead, } from './bundle-header.js';
 import { runGit } from './git-process.js';
 import { MaintenanceMutex, findCorruption, maintainMirror, objectStoreKiB, rebuildPaths, recoverRebuild, sweepLocksAndTemporaries, } from './github-mirror-upkeep.js';
-import { GatewayRefusalError, MAX_BRANCH_NAME_LENGTH, branchNameProblem, } from './branch-policy.js';
+import { GatewayRefusalError, MAX_BRANCH_NAME_LENGTH, branchNameProblem, namespaceBlockedMessage, branchInsideMessage, } from './branch-policy.js';
 import { gatewayLog, gatewayLogError, gatewayLogWarn, redactEgress } from './gateway-egress.js';
 import { mirrorGitOptions, mirrorPins, quarantinePins } from './shared-repo-git.js';
 /**
@@ -553,23 +553,22 @@ async function assertOwnDirectory(dir) {
     }
 }
 /**
- * A push the worker never makes: to a name that is not a plain branch name, to a protected branch
- * (`BranchPolicy`), to a settings branch under a lease, or of an object that is not a commit.
+ * A push the worker never makes: to a name that is not a plain branch name, one the policy refuses
+ * (`BranchPolicy.assertPushAllowed`, which owns those messages), or of an object that is not a
+ * commit.
  */
 export class RefusedPushError extends GatewayRefusalError {
-    constructor(branch, reason, sha) {
-        super('push', branch, reason, reason === 'invalid'
-            ? `Refusing to push ${JSON.stringify(branch)} to GitHub: it is not a valid branch name.`
-            : reason === 'protected'
-                ? `Refusing to push "${branch}" to GitHub: it is protected (the base branch, GitHub's ` +
-                    `default branch, or a name protectedBranches lists), which the CanopyCMS worker never ` +
-                    `pushes. Nothing in CanopyCMS queues such a push; find out what wrote this task.`
-                : reason === 'settings'
-                    ? `Refusing to push "${branch}" to GitHub under a lease: a settings branch only ever ` +
-                        `fast-forwards. Find out what set a history-rewrite marker on it.`
-                    : `Refusing to push "${branch}" to GitHub: ${sha ?? 'the object asked for'} is not a ` +
+    constructor(branch, reason, sha, 
+    /** The policy's own message, which names the namespace (`pushRefusalMessage`). */
+    message) {
+        super('push', branch, reason, message ??
+            (reason === 'invalid'
+                ? `Refusing to push ${JSON.stringify(branch)} to GitHub: it is not a valid branch name.`
+                : reason === 'not-a-commit'
+                    ? `Refusing to push "${branch}" to GitHub: ${sha ?? 'the object asked for'} is not a ` +
                         `commit, and a branch can only point at one. Find out what put it at ` +
-                        `refs/heads/${branch} in remote.git.`);
+                        `refs/heads/${branch} in remote.git.`
+                    : `Refusing to push ${JSON.stringify(branch)} to GitHub (${reason}).`));
         this.name = 'RefusedPushError';
     }
 }
@@ -890,7 +889,19 @@ export class MirrorSession {
         () => this.githubDefaultBranch(credential, options.signal).catch((err) => {
             throw new GitHubTransientError('default-branch-unread', `Could not read GitHub's default branch before pushing ${branch}: ` +
                 redactEgress(getErrorMessage(err)).trim());
-        }), (reason) => new RefusedPushError(branch, reason));
+        }), (reason, message) => new RefusedPushError(branch, reason, undefined, message));
+        // The mirror's heads are GitHub's as of this session's fetch.
+        if (branch.startsWith(options.policy.namespace)) {
+            const heads = await this.heads();
+            const blocker = options.policy.namespaceBlocker(heads);
+            if (blocker !== null) {
+                throw new RefusedPushError(branch, 'invalid', undefined, namespaceBlockedMessage(branch, blocker));
+            }
+            const inside = [...heads.keys()].find((name) => name.startsWith(`${branch}/`));
+            if (inside !== undefined) {
+                throw new RefusedPushError(branch, 'invalid', undefined, branchInsideMessage(branch, inside));
+            }
+        }
         options.onPushing?.();
         const status = await this.githubBound(credential, [
             'push',

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

@@ -1,3 +1,4 @@
+import { type BranchPolicyDescription } from './branch-policy.js';
 import type { WorkerContext } from './worker-context.js';
 /**
  * [SYNC-H1] The history-rewrite kernel: what happens when the rebase loop
@@ -29,19 +30,25 @@ export type HistoryRewriteContext = Pick<WorkerContext, 'remoteGitPath' | 'conte
  */
 export declare function readPublishedSha(ctx: Pick<HistoryRewriteContext, 'remoteGitPath'>, branchRef: string): Promise<string | null>;
 /**
- * Record that this worker rewrote `expectedSha` out of a branch's already
- * published history (see BranchMetadata.historyRewrittenFrom).
+ * Record that this worker rewrote `expectedSha` out of `branchRef`'s already
+ * published history (see BranchMetadata.historyRewrittenFrom), on a branch.json
+ * whose `name` is `branchRef` only: it never creates one, nor marks another
+ * branch's that shares the key.
  *
  * Set-once: an existing marker is LEFT ALONE. Across two rebases before any
  * GitHub push lands, GitHub still holds the commit the FIRST rebase replaced,
  * so advancing the marker would aim the lease at a commit GitHub never had and
  * permanently wedge the branch.
  *
- * Re-reads metadata rather than trusting the caller's snapshot: the task loop
- * runs concurrently with syncGit() and may have cleared the marker while this
- * branch was rebasing.
+ * Decided against the metadata on disk inside the write's lock, not the
+ * caller's snapshot: the task loop runs concurrently with syncGit() and may
+ * have cleared the marker while this branch was rebasing.
+ *
+ * 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, branchDir: string, expectedSha: string): Promise<void>;
+export declare function markHistoryRewritten(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchPath: string, branchRef: string, expectedSha: string): Promise<boolean>;
 /**
  * Clear the marker once GitHub is confirmed to hold the rewritten history.
  *
@@ -56,7 +63,7 @@ export declare function markHistoryRewritten(ctx: Pick<HistoryRewriteContext, 'c
  * Tracked, with the concurrent-clear race that can drop a marker mid-arming,
  * in safeinsights/canopycms#902.
  */
-export declare function clearHistoryRewrittenMarker(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchPath: string, branchDir: string): Promise<void>;
+export declare function clearHistoryRewrittenMarker(ctx: Pick<HistoryRewriteContext, 'contentBranchesPath'>, branchPath: string, branchRef: string): Promise<void>;
 /**
  * Publish a branch clone's rebased history into `remote.git`, replacing
  * EXACTLY `expectedSha` and nothing else.
@@ -79,10 +86,15 @@ export declare function forcePublishToLocalRemote(ctx: Pick<HistoryRewriteContex
  *
  * Deliberately NOT skipped when a marker is already set: inferring "a task must
  * already be queued" from the marker starves this hop whenever a task was lost,
- * failed permanently, or was never written. Duplicate push tasks are bounded by
- * base-branch advances and are idempotent.
+ * failed permanently, or was never written. Skipped instead when `gatewayPolicy`,
+ * the gateway's own description, says it would refuse the branch: the marker
+ * clears only on a push that lands, so such a task would fail permanently on
+ * every cycle, and System health's unpublishable alert already names the branch.
+ * Without a description every hop is queued. So while a marker stands, at most
+ * one push task is in flight and one is added per sync cycle, only for a failure
+ * the policy does not predict; the tasks are idempotent.
  */
-export declare function enqueueGitHubPush(ctx: Pick<HistoryRewriteContext, 'taskDir'>, branchRef: string): Promise<void>;
+export declare function enqueueGitHubPush(ctx: Pick<HistoryRewriteContext, 'taskDir'>, branchRef: string, gatewayPolicy: BranchPolicyDescription | undefined): Promise<void>;
 /**
  * Complete a rewrite this worker started but did not finish: get the rebased
  * history into `remote.git` and queued for GitHub.
@@ -100,6 +112,7 @@ export declare function reconcilePendingRewrite(ctx: HistoryRewriteContext, opti
     branchRef: string;
     headSha: string;
     marker: string;
+    gatewayPolicy: BranchPolicyDescription | undefined;
 }): Promise<void>;
 /**
  * Whether this branch carries a pending history rewrite -- the rebase loop