canopycms 0.7.1 → 0.8.1

package/dist/worker/branch-policy.js

@@ -1,8 +1,9 @@
 /**
  * The GitHub gateway's branch policy: what it never does to GitHub, whatever the worker asks. The
  * task queue, remote.git and every branch's metadata are on the shared workspace, which the CMS
- * Lambda can write, so nothing here takes a branch to protect from a request.
+ * Lambda can write, so nothing here takes a branch to protect, or one to allow, from a request.
  */
+import { DEFAULT_BRANCH_NAMESPACE_TEMPLATE, branchNamespaceProblem, namespaceAncestors, resolveBranchNamespaceTemplate, } from '../operating-mode/branch-namespace.js';
 import { RESERVED_SETTINGS_BRANCH_PREFIX, sanitizeBranchName } from '../paths/branch-name.js';
 /**
  * How long GitHub's default branch, once read, is taken to be still the default.
@@ -40,6 +41,46 @@ const openingFrom = (head) => `Refusing to open a pull request from ${JSON.strin
 const PROTECTED_WHY = "it is protected (the base branch, GitHub's default branch, or a name protectedBranches " +
     'lists), which the CanopyCMS worker never changes. Nothing in CanopyCMS queues this; find out ' +
     'what wrote this task.';
+const outsideNamespaceWhy = (namespace) => `it is outside this deployment's branch namespace (names starting ${namespace}), and is ` +
+    'neither its settings branch nor on its legacyBranches list. CanopyCMS creates every branch ' +
+    'it edits in that namespace; a branch made before it reaches GitHub only once ' +
+    'legacyBranches lists it.';
+const outsideNamespaceDeleteWhy = (namespace) => `it is outside this deployment's branch namespace (names starting ${namespace}), and is ` +
+    'neither its settings branch nor on its legacyBranches list, so the branch stays on GitHub. ' +
+    'To delete it there, add it to legacyBranches, retry this task in System health, then remove ' +
+    'the entry.';
+/**
+ * Why the policy refuses to push `branch`, for `reason`, in `namespace`.
+ * @internal Exported for tests.
+ */
+export function pushRefusalMessage(branch, reason, namespace) {
+    const refusing = `Refusing to push ${JSON.stringify(branch)} to GitHub`;
+    switch (reason) {
+        case 'protected':
+            return `${refusing}: ${PROTECTED_WHY}`;
+        case 'settings':
+            return (`${refusing} under a lease: a settings branch only ever fast-forwards. Find out what ` +
+                'set a history-rewrite marker on it.');
+        case 'other-settings':
+            return (`${refusing}: it is a settings branch, and not this deployment's, which is the only one ` +
+                'this gateway pushes. Check that CANOPYCMS_DEPLOYMENT_NAME and CANOPYCMS_SETTINGS_BRANCH ' +
+                "match the CMS's own settings branch; if they do, find out what asked for this push.");
+        case 'outside-namespace':
+            return `${refusing}: ${outsideNamespaceWhy(namespace)}`;
+    }
+}
+/** Why the gateway refuses to push `branch`, in the namespace, while GitHub has `blocker`. */
+export function namespaceBlockedMessage(branch, blocker) {
+    return (`Refusing to push ${JSON.stringify(branch)} to GitHub: GitHub has a branch named ` +
+        `${JSON.stringify(blocker)}, which is part of this deployment's branch namespace, and git ` +
+        'cannot hold a branch inside another. Rename or delete that branch on GitHub.');
+}
+/** Why a push of `branch` is refused while GitHub has `inside`, a branch inside it. */
+export function branchInsideMessage(branch, inside) {
+    return (`Refusing to push ${JSON.stringify(branch)} to GitHub: GitHub has a branch named ` +
+        `${JSON.stringify(inside)} inside it, and git cannot hold both. Rename or delete that ` +
+        'branch on GitHub.');
+}
 /**
  * Why `branch` is not a name the gateway takes, before git sees it, or null. Printable ASCII only,
  * so no two names differ invisibly; no `"`, `%`, `{` or `}`, which reach URLs and log lines; no
@@ -88,6 +129,32 @@ export function protectedPatternProblem(pattern) {
     }
     return null;
 }
+/**
+ * Why `entry` cannot be a `legacyBranches` entry, whatever the namespace, or null. An entry is an
+ * exact branch name git can push: a `*` would admit names no one listed, and one alone would
+ * switch the namespace off. A comma separates entries in `CANOPYCMS_LEGACY_BRANCHES`. The CDK's
+ * `assertValidLegacyBranches` holds a copy of these rules and the constructor's, both held to
+ * worker/legacy-branch-fixtures.ts.
+ * @internal Exported for tests.
+ */
+export function legacyBranchProblem(entry) {
+    if (entry.includes('*'))
+        return 'an entry is an exact branch name, and * is not a wildcard here';
+    if (entry.includes(','))
+        return 'it contains a comma, which separates entries';
+    if (entry.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX)) {
+        return 'it is a settings branch, which the gateway pushes without being listed';
+    }
+    const problem = protectedPatternProblem(entry);
+    if (problem !== null)
+        return problem;
+    if (entry === 'HEAD' || entry === '@')
+        return `git reserves ${JSON.stringify(entry)}`;
+    if (entry.split('/').some((part) => part.startsWith('.') || part.endsWith('.lock'))) {
+        return "a part of it starts with '.' or ends with '.lock', which git refuses";
+    }
+    return null;
+}
 /**
  * Whether `name` matches `pattern`, where `*` matches any run of characters. Never a regex.
  * @internal Exported for tests.
@@ -117,8 +184,16 @@ export function matchesBranchPattern(pattern, name) {
  * branch (`describe()`), so its bound is one above this.
  */
 export const MAX_PROTECTED_BRANCHES = 1024;
+/** The most `legacyBranches` entries a policy takes. */
+export const MAX_LEGACY_BRANCHES = 1024;
 /**
- * The protected set and the settings rules.
+ * The namespace a policy enforces when it is given none: the default template's, for the default
+ * deployment name.
+ * @internal Exported for tests.
+ */
+export const DEFAULT_BRANCH_NAMESPACE = resolveBranchNamespaceTemplate(DEFAULT_BRANCH_NAMESPACE_TEMPLATE, 'prod', 'the default');
+/**
+ * The protected set, the namespace and the settings rules.
  *
  * A branch is protected when it is the configured base branch, GitHub's default branch or a
  * `protectedBranches` entry, compared case-sensitively as GitHub compares refs. An exact entry
@@ -129,15 +204,47 @@ export const MAX_PROTECTED_BRANCHES = 1024;
  * Reads are not shared between concurrent callers, because a push reads inside a mirror session
  * and an operation that joined it from outside one would wait on that session.
  *
+ * Nothing outside the namespace is written: a push, deletion or pull request head must start with
+ * the namespace, be this deployment's settings branch, or be a `legacyBranches` entry, compared
+ * exactly. Sanitized equivalence, right for the protected set where matching more refuses more,
+ * would let an allow-list admit more. The protected set wins inside the namespace too. The
+ * namespace comes from the gateway's own configuration, never a request. The base and settings
+ * branches must lie outside it, by name and by workspace directory, and not be named after part of
+ * it, since git then holds no branch in it; a legacy entry inside it is refused as pointless, and
+ * one named after part of it as blocking it.
+ *
  * Settings branches are pushed plainly or not at all: no lease, no deletion, no pull request.
- * One is a name with the reserved prefix, the task runner's own test (`isSettingsBranch`): branch
- * creation refuses the prefix, while a configured settings name without it could be a content
- * branch's.
+ * One is a name with the reserved prefix or this deployment's settings branch. Only this
+ * deployment's is pushed: another deployment sharing the repository owns its own.
  */
 export class BranchPolicy {
     constructor(options = {}) {
         this.githubDefault = null;
         this.now = options.now ?? (() => Date.now());
+        this.namespace = options.namespace ?? DEFAULT_BRANCH_NAMESPACE;
+        const namespaceProblem = branchNamespaceProblem(this.namespace);
+        if (namespaceProblem !== null) {
+            throw new Error(`Invalid branch namespace ${JSON.stringify(this.namespace)}: ${namespaceProblem}`);
+        }
+        for (const [what, name] of [
+            ['base branch', options.baseBranch],
+            ['settings branch', options.settingsBranch],
+        ]) {
+            // Sanitized too: a workspace directory is the sanitized name, so `cms-prod-main` would share
+            // one with `cms/prod/main`.
+            if (name !== undefined &&
+                (name.startsWith(this.namespace) ||
+                    sanitizeBranchName(name).startsWith(sanitizeBranchName(this.namespace)))) {
+                throw new Error(`The ${what} ${JSON.stringify(name)} is inside the branch namespace ${JSON.stringify(this.namespace)}, ` +
+                    'or shares a workspace directory with a branch in it, and the namespace holds only the ' +
+                    'branches editors create; choose a namespace it is outside');
+            }
+            // git holds no ref under a path that is itself a branch.
+            if (name !== undefined && this.namespace.startsWith(`${name}/`)) {
+                throw new Error(`The ${what} ${JSON.stringify(name)} is a branch named after part of the branch namespace ` +
+                    `${JSON.stringify(this.namespace)}, so git can hold no branch in it; choose another namespace`);
+            }
+        }
         const entries = [...(options.protectedBranches ?? [])];
         if (entries.length > MAX_PROTECTED_BRANCHES) {
             throw new Error(`protectedBranches has ${entries.length} entries; the most it takes is ${MAX_PROTECTED_BRANCHES}`);
@@ -152,14 +259,61 @@ export class BranchPolicy {
             entries.push(options.baseBranch);
         this.exact = entries.filter((entry) => !entry.includes('*'));
         this.globs = entries.filter((entry) => entry.includes('*'));
+        const settingsBranch = options.settingsBranch;
+        if (settingsBranch !== undefined) {
+            const problem = branchNameProblem(settingsBranch);
+            if (problem !== null) {
+                throw new Error(`Invalid settings branch ${JSON.stringify(settingsBranch)}: ${problem}`);
+            }
+        }
+        this.settingsBranch = settingsBranch ?? null;
+        const legacy = options.legacyBranches ?? [];
+        if (legacy.length > MAX_LEGACY_BRANCHES) {
+            throw new Error(`legacyBranches has ${legacy.length} entries; the most it takes is ${MAX_LEGACY_BRANCHES}`);
+        }
+        for (const entry of legacy) {
+            const problem = entry.startsWith(this.namespace)
+                ? `it starts with ${this.namespace}, so it is already in the namespace`
+                : this.namespace.startsWith(`${entry}/`)
+                    ? `it is a branch named after part of the namespace ${this.namespace}, so git can hold no branch in it`
+                    : legacyBranchProblem(entry);
+            if (problem !== null) {
+                throw new Error(`Invalid legacyBranches entry ${JSON.stringify(entry)}: ${problem}`);
+            }
+        }
+        if (new Set(legacy).size !== legacy.length) {
+            throw new Error('legacyBranches lists a branch more than once');
+        }
+        this.legacy = new Set(legacy);
     }
-    /** The protected set as it stands: configured names and globs, and GitHub's default as last read. */
+    /** The policy as it stands. */
     describe() {
         return {
             configured: [...this.exact, ...this.globs],
             githubDefault: this.githubDefault?.name ?? null,
+            namespace: this.namespace,
+            legacy: [...this.legacy],
+            settingsBranch: this.settingsBranch,
         };
     }
+    /** Whether the gateway may write `branch` at all: the namespace, the settings branch, the list. */
+    inNamespace(branch) {
+        return (branch.startsWith(this.namespace) || branch === this.settingsBranch || this.legacy.has(branch));
+    }
+    /**
+     * Whether the gateway opens and updates a pull request from `head`, protection aside: a branch it
+     * writes that is not a settings branch. `isProtected`, which may read GitHub, judges the rest.
+     */
+    takesPullRequestFrom(head) {
+        return !this.isSettings(head) && this.inNamespace(head);
+    }
+    /**
+     * The branch among `branches` named after part of the namespace, or null. While one exists git
+     * holds no branch in the namespace, so the gateway refuses a push into it rather than send it.
+     */
+    namespaceBlocker(branches) {
+        return namespaceAncestors(this.namespace).find((name) => branches.has(name)) ?? null;
+    }
     /** Whether `branch` is protected; GitHub's default is read only when nothing else matches. */
     async isProtected(branch, readDefault) {
         if (this.matchesConfigured(branch))
@@ -167,14 +321,32 @@ export class BranchPolicy {
         const githubDefault = await this.githubDefaultBranch(readDefault);
         return githubDefault !== null && sameBranch(githubDefault, branch);
     }
-    /** Refuse a push to a protected branch, or a leased push to a settings branch. */
+    /**
+     * Whether `branch` is GitHub's default branch as last read, even once that read has expired:
+     * what protection is judged by when a fresh read fails.
+     */
+    matchesLastReadDefault(branch) {
+        const name = this.githubDefault?.name ?? null;
+        return name !== null && sameBranch(name, branch);
+    }
+    /**
+     * Refuse a push to a protected branch, a leased push to a settings branch, a push to another
+     * deployment's settings branch, and a push outside the namespace.
+     */
     async assertPushAllowed(branch, lease, readDefault, refuse) {
+        const refusal = (reason) => refuse(reason, pushRefusalMessage(branch, reason, this.namespace));
         if (await this.isProtected(branch, readDefault))
-            throw refuse('protected');
-        if (lease !== undefined && this.isSettings(branch))
-            throw refuse('settings');
+            throw refusal('protected');
+        if (this.isSettings(branch)) {
+            if (lease !== undefined)
+                throw refusal('settings');
+            if (branch !== this.settingsBranch)
+                throw refusal('other-settings');
+        }
+        if (!this.inNamespace(branch))
+            throw refusal('outside-namespace');
     }
-    /** Refuse to delete a protected branch or a settings branch. */
+    /** Refuse to delete a protected branch, a settings branch, or one outside the namespace. */
     async assertDeleteAllowed(branch, readDefault) {
         if (this.isSettings(branch)) {
             throw new GatewayRefusalError('delete', branch, 'settings', `${deleting(branch)}: it is a settings branch, which is never deleted`);
@@ -182,24 +354,37 @@ export class BranchPolicy {
         if (await this.isProtected(branch, readDefault)) {
             throw new GatewayRefusalError('delete', branch, 'protected', `${deleting(branch)}: ${PROTECTED_WHY}`);
         }
+        if (!this.inNamespace(branch)) {
+            throw new GatewayRefusalError('delete', branch, 'outside-namespace', `${deleting(branch)}: ${outsideNamespaceDeleteWhy(this.namespace)}`);
+        }
     }
     /**
-     * Refuse a pull request whose head is protected or a settings branch, or whose text is over its
-     * cap. The base is not restricted: a branch keeps the base it was created from after the
-     * adopter moves theirs, and a pull request merges nothing by itself.
+     * Refuse a pull request whose head is protected, a settings branch or outside the namespace, or
+     * whose text is over its cap. The base is not restricted: a branch keeps the base it was created
+     * from after the adopter moves theirs, and a pull request merges nothing by itself.
      */
     async assertPullRequestAllowed(request, readDefault) {
         const { head } = request;
         assertPullRequestText(openingFrom(head), head, request);
+        await this.assertPullRequestHeadAllowed(openingFrom(head), head, readDefault);
+    }
+    /**
+     * Refuse a pull request head the gateway may not open one from, or act on one with. `refusing`
+     * opens the message and names `head`, which the rest calls "it".
+     */
+    async assertPullRequestHeadAllowed(refusing, head, readDefault) {
         if (this.isSettings(head)) {
-            throw new GatewayRefusalError('pull-request', head, 'settings', `${openingFrom(head)}: it is a settings branch, which never gets one`);
+            throw new GatewayRefusalError('pull-request', head, 'settings', `${refusing}: it is a settings branch, which never gets one`);
         }
         if (await this.isProtected(head, readDefault)) {
-            throw new GatewayRefusalError('pull-request', head, 'protected', `${openingFrom(head)}: ${PROTECTED_WHY}`);
+            throw new GatewayRefusalError('pull-request', head, 'protected', `${refusing}: ${PROTECTED_WHY}`);
+        }
+        if (!this.takesPullRequestFrom(head)) {
+            throw new GatewayRefusalError('pull-request', head, 'outside-namespace', `${refusing}: ${outsideNamespaceWhy(this.namespace)}`);
         }
     }
     isSettings(branch) {
-        return branch.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX);
+        return branch.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX) || branch === this.settingsBranch;
     }
     matchesConfigured(branch) {
         return (this.exact.some((name) => sameBranch(name, branch)) ||
@@ -226,6 +411,26 @@ export class BranchPolicy {
         return name;
     }
 }
+/**
+ * Whether the gateway that described its policy as `policy` would take a plain push of `branch`:
+ * `BranchPolicy.assertPushAllowed`'s rules, for a reader that has only the description, with
+ * GitHub's default as last read. A test holds the two equal.
+ */
+export function publishesBranch(policy, branch) {
+    // No namespace is the description a gateway that failed to boot answers, and it pushes nothing.
+    if (policy.namespace === '')
+        return false;
+    const settings = branch.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX) || branch === policy.settingsBranch;
+    const protectedMatch = policy.configured.some((entry) => entry.includes('*')
+        ? !settings && matchesBranchPattern(entry, branch)
+        : sameBranch(entry, branch)) ||
+        (policy.githubDefault !== null && sameBranch(policy.githubDefault, branch));
+    if (protectedMatch)
+        return false;
+    if (settings)
+        return branch === policy.settingsBranch;
+    return branch.startsWith(policy.namespace) || policy.legacy.includes(branch);
+}
 /** Refuse pull request text over its cap; `refusing` opens the message, `branch` names its head. */
 export function assertPullRequestText(refusing, branch, text) {
     const over = (text.title?.length ?? 0) > MAX_PULL_REQUEST_TITLE_LENGTH

package/dist/worker/cms-worker.d.ts

@@ -7,6 +7,7 @@ export { resolveWorkerGitHubAuth, normalizeGitHubAppPrivateKey, DEFAULT_GIT_TOKE
 export { createLocalGitHubGateway, type GitHubGateway, type GitHubGatewayHealth, type LocalGitHubGatewayOptions, } from './github-gateway.js';
 export { serveGitHubGateway, connectGitHubGateway, type GitHubGatewayClientOptions, type GitHubGatewayListen, type GitHubGatewayServer, type GitHubGatewayServerOptions, } from './github-gateway-http.js';
 export { GitHubGatewayUnreachableError } from './github-gateway-wire.js';
+export { resolveBranchNamespace } from '../operating-mode/branch-namespace.js';
 export { GatewayInstance, type GatewayInstanceOptions } from './gateway-instance.js';
 export { gatewayLog, gatewayLogWarn, gatewayLogError, registerSecretText, registerPrivateKey, redactEgress, } from './gateway-egress.js';
 export { assertSelfChecks, gatewaySelfChecks, workerSelfChecks, type SelfCheckEnvironment, type SelfCheckName, type SelfCheckResult, } from './self-checks.js';
@@ -36,8 +37,9 @@ export interface CmsWorkerConfig extends GitHubAuthConfig {
     /**
      * A GitHub gateway to use instead of building the in-process one: a client of a gateway another
      * process serves (`connectGitHubGateway`), which holds the credential, the protected set and the
-     * mirror. Exclusive with `githubToken`, `githubAppAuth`, `refreshGitHubToken` and
-     * `protectedBranches`, which configure the in-process one.
+     * mirror. Exclusive with `githubToken`, `githubAppAuth`, `refreshGitHubToken`,
+     * `protectedBranches`, `legacyBranches` and `branchNamespace`, which configure the in-process
+     * one.
      */
     githubGateway?: GitHubGateway;
     /** GitHub owner (e.g., 'acme') */
@@ -60,6 +62,16 @@ export interface CmsWorkerConfig extends GitHubAuthConfig {
      * characters (`release/*`), which never match a settings branch. See worker/branch-policy.ts.
      */
     protectedBranches?: readonly string[];
+    /**
+     * Branches outside the namespace the in-process gateway may still write: exact names of
+     * branches from before the namespace. See worker/branch-policy.ts.
+     */
+    legacyBranches?: readonly string[];
+    /**
+     * The in-process gateway's branch namespace template (`CANOPYCMS_BRANCH_NAMESPACE` wins);
+     * resolved as operating-mode/branch-namespace.ts says.
+     */
+    branchNamespace?: string;
     /**
      * Names THIS worker's own settings branch
      * (`canopycms-settings-{deploymentName}`, default 'prod' — ProdStrategy's
@@ -104,6 +116,16 @@ export interface CmsWorkerConfig extends GitHubAuthConfig {
      */
     drainDeadlineMs?: number;
 }
+/**
+ * The settings branch a worker owns: `settingsBranch` when set, else
+ * `canopycms-settings-{deploymentName}` by `resolveDeploymentName`, which reads
+ * `CANOPYCMS_DEPLOYMENT_NAME` first. The split gateway resolves its own the same way, from its own
+ * environment, so the one branch it pushes is the one its worker owns.
+ */
+export declare function resolveWorkerSettingsBranch(config: {
+    settingsBranch?: string;
+    deploymentName?: string;
+}): string;
 /**
  * The default `taskTimeoutMs`. Exported because a split worker's gateway client passes it as its
  * `fetchInactivityMs` and the gateway uses it as its `timeoutMs`, as the in-process gateway does.

package/dist/worker/cms-worker.js

@@ -10,12 +10,14 @@ import { createLocalGitHubGateway, } from './github-gateway.js';
 import { GITHUB_TRACKING_REF_PREFIX, ensureRemoteGitConfig, failOnSignalExit } from '../git-manager.js';
 import { readHeadBranch } from '../utils/git.js';
 import { isSettingsBranchName, sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, } from '../paths/branch-name.js';
+import { resolveBranchNamespace } from '../operating-mode/branch-namespace.js';
 import { resolveDeploymentName } from '../operating-mode/deployment-name.js';
 import { getErrorMessage, isNodeError, redactCredentials } from '../utils/error.js';
 import { readCarriedOverStatus, readWorkerStatusStartedAt, writeWorkerStatus, } from '../task-queue/worker-status.js';
 import { CANOPYCMS_VERSION } from '../version.js';
 import { workerLog, workerLogWarn, workerLogError } from './log.js';
 import { DEFAULT_SCHEMA_HOLD_MAX_MS, readCarriedBaseHold } from './schema-gate.js';
+import { readCarriedGatewayPolicy, readCarriedUnpublishableBranches, } from './unpublishable-branches.js';
 import { SharedRepoRefusalError, UntrustedRepoConfigError, assertSharedRepoConfig, sharedRepoGit, } from './shared-repo-git.js';
 import { executeTask, orphanRecoveryMaxAgeMs, processTaskQueue, pushBranchToGitHub, updateBranchMetadata, } from './task-runner.js';
 import { pollMergeState, runRebaseCycle } from './rebase.js';
@@ -40,6 +42,8 @@ resolveWorkerGitHubAuth, normalizeGitHubAppPrivateKey, DEFAULT_GIT_TOKEN_MINT_TI
 export { createLocalGitHubGateway, } from './github-gateway.js';
 export { serveGitHubGateway, connectGitHubGateway, } from './github-gateway-http.js';
 export { GitHubGatewayUnreachableError } from './github-gateway-wire.js';
+// The split gateway resolves its branch namespace as the in-process one does.
+export { resolveBranchNamespace } from '../operating-mode/branch-namespace.js';
 // A gateway that failed to boot still serves the instance operations.
 export { GatewayInstance } from './gateway-instance.js';
 // The gateway process's scrubbed log lines, and the exact scrubs for the secrets it holds that
@@ -92,6 +96,16 @@ async function listRemoteGitRefs(gitDir) {
 function sameRefs(a, b) {
     return a.size === b.size && [...a].every(([ref, id]) => b.get(ref) === id);
 }
+/**
+ * The settings branch a worker owns: `settingsBranch` when set, else
+ * `canopycms-settings-{deploymentName}` by `resolveDeploymentName`, which reads
+ * `CANOPYCMS_DEPLOYMENT_NAME` first. The split gateway resolves its own the same way, from its own
+ * environment, so the one branch it pushes is the one its worker owns.
+ */
+export function resolveWorkerSettingsBranch(config) {
+    return (config.settingsBranch ??
+        `${RESERVED_SETTINGS_BRANCH_PREFIX}${resolveDeploymentName({ deploymentName: config.deploymentName }, 'prod')}`);
+}
 /**
  * The default `taskTimeoutMs`. Exported because a split worker's gateway client passes it as its
  * `fetchInactivityMs` and the gateway uses it as its `timeoutMs`, as the in-process gateway does.
@@ -150,18 +164,16 @@ function lockWorkerTaskDir(taskDir, lockStaleMs, options) {
             : {}),
     });
 }
-/**
- * The fields a new status snapshot carries from the previous file: `lastFatalError` and
- * `lastShutdown` (task-queue/worker-status.ts) and the schema gate's hold, so its bound keeps
- * counting from the first worker that saw each schema missing.
- */
 async function readCarriedFields(taskDir) {
     const { lastFatalError, lastShutdown } = await readCarriedOverStatus(taskDir);
     const baseHold = await readCarriedBaseHold(taskDir);
+    const unpublishableBranches = await readCarriedUnpublishableBranches(taskDir);
     return {
         ...(lastFatalError ? { lastFatalError } : {}),
         ...(lastShutdown ? { lastShutdown } : {}),
         ...(baseHold ? { baseHold } : {}),
+        ...(unpublishableBranches ? { unpublishableBranches } : {}),
+        ...(await readCarriedGatewayPolicy(taskDir)),
     };
 }
 /**
@@ -184,7 +196,7 @@ export async function recordWorkerStartupFailure(options) {
             onCompromised: (err) => workerLogError('Worker lock lost while recording a startup failure:', getErrorMessage(err)),
         });
         const now = new Date().toISOString();
-        const { lastFatalError, lastShutdown, baseHold } = await readCarriedFields(taskDir);
+        const { lastFatalError, ...carried } = await readCarriedFields(taskDir);
         if (lastFatalError &&
             options.keepRecordedFatal &&
             lastFatalError.workerStartedAt === (await readWorkerStatusStartedAt(taskDir)) &&
@@ -196,8 +208,7 @@ export async function recordWorkerStartupFailure(options) {
             workerVersion: CANOPYCMS_VERSION,
             startedAt: now,
             updatedAt: now,
-            ...(lastShutdown ? { lastShutdown } : {}),
-            ...(baseHold ? { baseHold } : {}),
+            ...carried,
             lastFatalError: {
                 // [REDACT] Served to the browser by the admin panel and the API's not-ready answer.
                 message: redactCredentials(getErrorMessage(options.error)),
@@ -299,9 +310,7 @@ export class CmsWorker {
      */
     ensureSettingsBranch() {
         if (this.settingsBranchResolved === undefined) {
-            this.settingsBranchResolved =
-                this.config.settingsBranch ??
-                    `${RESERVED_SETTINGS_BRANCH_PREFIX}${resolveDeploymentName({ deploymentName: this.config.deploymentName }, 'prod')}`;
+            this.settingsBranchResolved = resolveWorkerSettingsBranch(this.config);
         }
         return this.settingsBranchResolved;
     }
@@ -370,17 +379,12 @@ export class CmsWorker {
         // version. Best-effort, like the startup-failure write below. The previous
         // `lastFatalError` rides along in this snapshot only, so a crash loop keeps
         // its alert between restarts while the first successful sync still clears
-        // it. Two fields carry into the report itself: `lastShutdown`, which
-        // describes the last worker that ran until this worker's own stop() replaces it,
-        // and the schema gate's hold, so its bound keeps counting from the first
-        // worker that saw each schema missing.
+        // it. The other carried fields (readCarriedFields) go into the report itself;
+        // `lastShutdown` describes the last worker that ran until this worker's own
+        // stop() replaces it.
         try {
-            const { lastFatalError, lastShutdown, baseHold } = await readCarriedFields(this.taskDir);
-            const report = this.ensureStatusReport();
-            if (lastShutdown)
-                report.lastShutdown = lastShutdown;
-            if (baseHold)
-                report.baseHold = baseHold;
+            const { lastFatalError, ...carried } = await readCarriedFields(this.taskDir);
+            const report = Object.assign(this.ensureStatusReport(), carried);
             await writeWorkerStatus(this.taskDir, {
                 ...report,
                 ...(lastFatalError ? { lastFatalError } : {}),
@@ -1164,9 +1168,13 @@ export class CmsWorker {
             conflicting.push('refreshGitHubToken');
         if ((this.config.protectedBranches?.length ?? 0) > 0)
             conflicting.push('protectedBranches');
+        if ((this.config.legacyBranches?.length ?? 0) > 0)
+            conflicting.push('legacyBranches');
+        if (this.config.branchNamespace !== undefined)
+            conflicting.push('branchNamespace');
         if (conflicting.length > 0) {
             throw new Error(`CmsWorker: githubGateway is exclusive with ${conflicting.join(', ')}, which configure the ` +
-                'in-process gateway; the gateway it is given holds the credential and the protected set');
+                'in-process gateway; the gateway it is given holds the credential and the branch policy');
         }
         this.gateway = githubGateway;
         return this.gateway;
@@ -1191,6 +1199,9 @@ export class CmsWorker {
             timeoutMs: this.taskTimeoutMs,
             baseBranch: this.config.baseBranch,
             protectedBranches: this.config.protectedBranches,
+            settingsBranch: this.ensureSettingsBranch(),
+            legacyBranches: this.config.legacyBranches,
+            branchNamespace: resolveBranchNamespace(this.config, 'prod'),
         };
     }
     /**
@@ -1241,8 +1252,8 @@ export class CmsWorker {
     // `rebaseActiveBranches` also has a consumer outside the test files:
     // apps/test-app/app/api/e2e-test/rebase/route.ts drives it from an e2e
     // fixture route. Do not delete it as unused.
-    async rebaseActiveBranches() {
-        return runRebaseCycle(this.ctx());
+    async rebaseActiveBranches(gatewayPolicy) {
+        return runRebaseCycle(this.ctx(), gatewayPolicy);
     }
     // --- Git-sync cluster (worker/git-sync.ts) -----------------------------
     //

package/dist/worker/git-sync.d.ts

@@ -15,9 +15,9 @@ import type { WorkerContext } from './worker-context.js';
  * (`reconcileTrackedBranches`, which holds the base branch while schema-gate.ts
  * says the serving editor lacks a schema the incoming content names), push this
  * deployment's own settings
- * branch, fast-forward the base branch's workspace, rebase every branch that is
- * behind it (rebase.ts), then sweep old tasks and expired trashed branch
- * directories.
+ * branch, fast-forward the base branch's workspace, ask the gateway for its branch policy,
+ * rebase every branch that is behind it (rebase.ts), then sweep old tasks and expired trashed
+ * branch directories.
  *
  * One ordering is load-bearing and nothing enforces it: `runRebaseCycle` MUST
  * follow `reconcileTrackedBranches`. Branch clones fetch the base tip from

package/dist/worker/git-sync.js

@@ -25,6 +25,7 @@ import { maintainRemoteGit } from './remote-git-maintenance.js';
 import { decideBaseAdvance } from './schema-gate.js';
 import { SHARED_REPO_STATUS_ARGS, assertNoIncomingSubmodules, assertSharedRepoConfig, fetchFromRemoteGit, sharedRepoGit, } from './shared-repo-git.js';
 import { reapplySparseCones } from './sparse-cone.js';
+import { findUnpublishableBranches } from './unpublishable-branches.js';
 import { readEditorWork, settleStaleMirror, } from './stale-mirror.js';
 /**
  * [C1] Retention window for `.trash-*` branch directories left behind by the
@@ -485,10 +486,50 @@ export async function syncGit(ctx) {
         const baseRefresh = await refreshBaseBranchWorkspace(ctx);
         if (stoppedForDrain(ctx, 'the rebase cycle'))
             return;
-        const rebaseSummary = await runRebaseCycle(ctx);
+        // The gateway's policy, which the rebase loop needs to tell its own namespace and what the
+        // gateway would refuse to publish. A gateway that cannot answer, or answers with no namespace
+        // (a failed boot), gives none.
+        let health;
+        try {
+            health = await ctx.github().health(ctx.shutdownSignal());
+        }
+        catch (err) {
+            workerLogWarn(`Could not read the GitHub gateway's branch policy: ${getErrorMessage(err)}`);
+        }
+        const branchPolicy = health && health.branchPolicy.namespace !== '' ? health.branchPolicy : undefined;
+        // The namespace System health compares with the one the CMS creates branches in, and the
+        // names creation refuses. Written at once, as the catch below writes on a failure: branch
+        // creation waits for the namespace (api/branch.ts), so it must not wait on the rest of the
+        // cycle succeeding. Without a policy the last values stand.
+        if (branchPolicy) {
+            const report = ctx.ensureStatusReport();
+            report.gatewayBranchNamespace = branchPolicy.namespace;
+            report.gatewayProtectedBranches = branchPolicy.configured.filter((n) => !n.includes('*'));
+            await writeWorkerStatus(ctx.taskDir, report).catch((writeErr) => workerLogError('Failed to write worker status:', getErrorMessage(writeErr)));
+        }
+        const rebaseSummary = await runRebaseCycle(ctx, branchPolicy);
         if (stoppedForDrain(ctx, 'the cleanup sweeps'))
             return;
         await cleanupOldTasks(ctx.taskDir, undefined, ctx.log);
+        // For System health: the branches the gateway would refuse to publish, read after the rebase
+        // cycle, which archives merged branches and restores renamed ones. Without a policy, a fatal
+        // error, or a branches directory or branch.json that cannot be read, the last report stands.
+        if (health && branchPolicy) {
+            const report = ctx.ensureStatusReport();
+            if (health.fatalError === null) {
+                try {
+                    const unpublishable = await findUnpublishableBranches(ctx, branchPolicy);
+                    if (unpublishable.count > 0) {
+                        report.unpublishableBranches = { ...unpublishable, at: new Date().toISOString() };
+                    }
+                    else
+                        delete report.unpublishableBranches;
+                }
+                catch (err) {
+                    workerLogWarn(`Could not list the branches the gateway will not publish: ${getErrorMessage(err)}`);
+                }
+            }
+        }
         // [C1] Sweep branch directories the admin purge action trashed more than
         // TRASH_RETENTION_MS ago. Worker-only by design: purge itself never deletes
         // anything (it stays reversible), and this is the sole place removal

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

@@ -220,8 +220,8 @@ class GatewayRequestHandler {
             },
             getPullRequest: async ({ number }, signal) => {
                 const { merged, merged_at, state, node_id, body } = await gateway.getPullRequest(number, signal);
-                // Octokit's type says string | null; a payload without the field crosses as null.
-                return { merged, merged_at, state, node_id, body: body ?? null };
+                // A null body is the gateway withholding it (`GitHubPullRequest.body`), and crosses as one.
+                return { merged, merged_at, state, node_id, body };
             },
             createOrUpdatePullRequest: async (input, signal) => {
                 const { number, url, created } = await gateway.createOrUpdatePullRequest(input, signal);