canopycms 0.0.68-int.111 → 0.0.68-int.112

package/dist/branch-health.js

@@ -45,15 +45,17 @@ async function readMetaMtime(branchRoot) {
 }
 /**
  * Scan a healthy branch's content tree for duplicate embedded IDs, giving up
- * at `deadline` (epoch ms). Never throws: one branch's unreadable content tree
+ * when `budget` runs out. Never throws: one branch's unreadable content tree
  * must not take down the whole health scan. Costs a full recursive readdir, so
  * it runs only on request and under a budget. A readdir cannot be cancelled: a
  * scan that misses the deadline keeps running unobserved until it settles.
  */
-async function scanDuplicateContentIds(branchRoot, contentRootName, deadline) {
-    const remainingMs = deadline - Date.now();
-    if (remainingMs <= 0)
+async function scanDuplicateContentIds(branchRoot, contentRootName, budget) {
+    const remainingMs = budget.deadline - Date.now();
+    if (budget.spent || remainingMs <= 0) {
+        budget.spent = true;
         return { state: 'unknown', reason: 'out-of-time' };
+    }
     const scan = (async () => {
         try {
             const idIndex = new ContentIdIndex(branchRoot);
@@ -67,7 +69,10 @@ async function scanDuplicateContentIds(branchRoot, contentRootName, deadline) {
     })();
     let timer;
     const outOfTime = new Promise((resolve) => {
-        timer = setTimeout(() => resolve({ state: 'unknown', reason: 'out-of-time' }), remainingMs);
+        timer = setTimeout(() => {
+            budget.spent = true;
+            resolve({ state: 'unknown', reason: 'out-of-time' });
+        }, remainingMs);
     });
     try {
         return await Promise.race([scan, outOfTime]);
@@ -88,8 +93,8 @@ async function scanDuplicateContentIds(branchRoot, contentRootName, deadline) {
  * reached after the budget is spent reports `unknown`/`out-of-time`.
  */
 export async function scanBranchHealth(baseRoot, opts) {
-    const duplicateScanDeadline = opts.duplicateIdScan
-        ? Date.now() + opts.duplicateIdScan.budgetMs
+    const duplicateScanBudget = opts.duplicateIdScan
+        ? { deadline: Date.now() + opts.duplicateIdScan.budgetMs, spent: false }
         : undefined;
     const resolvedRoot = path.resolve(baseRoot);
     const sanitizedBaseBranchName = sanitizeBranchName(opts.baseBranchName);
@@ -154,9 +159,9 @@ export async function scanBranchHealth(baseRoot, opts) {
         }
         if (meta) {
             const [duplicateIdScan, rebaseInProgress] = await Promise.all([
-                duplicateScanDeadline === undefined
+                duplicateScanBudget === undefined
                     ? undefined
-                    : scanDuplicateContentIds(branchRoot, contentRootName, duplicateScanDeadline),
+                    : scanDuplicateContentIds(branchRoot, contentRootName, duplicateScanBudget),
                 isRebaseInProgress(branchRoot),
             ]);
             entries.push({

package/dist/git-manager.d.ts

@@ -49,6 +49,16 @@ export type BareRemoteRepackResult = {
  * it packed and their emptied fan-out directories. `git` as for `ensureRemoteGitConfig`.
  */
 export declare function repackBareRemoteIfNeeded(gitDir: string, git?: SimpleGit): Promise<BareRemoteRepackResult>;
+/**
+ * simple-git reads a git that exited by signal (exit code null, often with no stderr) as success,
+ * so a clone or checkout the OOM killer stopped would pass for complete. Given as `errors` to a
+ * GitManager's own instance, to `cloneRepo`'s, and to the worker's ref probes of an existing
+ * remote.git (worker/cms-worker.ts); its static helpers and the bare-remote functions do not pass
+ * it yet (.claude/future-tasks/simple-git-signal-exit-reads-as-success.md).
+ */
+export declare function failOnSignalExit(error: Buffer | Error | undefined, result: {
+    exitCode: number;
+}): Buffer | Error | undefined;
 /**
  * Config every workspace clone writes into its own `.git/config`: the managed
  * marker that ensureRemote's guard checks, and a fallback author for internal

package/dist/git-manager.js

@@ -179,10 +179,11 @@ export async function repackBareRemoteIfNeeded(gitDir, git = simpleGit().env(git
 /**
  * simple-git reads a git that exited by signal (exit code null, often with no stderr) as success,
  * so a clone or checkout the OOM killer stopped would pass for complete. Given as `errors` to a
- * GitManager's own instance and to `cloneRepo`'s; its static helpers and the bare-remote functions
- * do not pass it yet (.claude/future-tasks/simple-git-signal-exit-reads-as-success.md).
+ * GitManager's own instance, to `cloneRepo`'s, and to the worker's ref probes of an existing
+ * remote.git (worker/cms-worker.ts); its static helpers and the bare-remote functions do not pass
+ * it yet (.claude/future-tasks/simple-git-signal-exit-reads-as-success.md).
  */
-function failOnSignalExit(error, result) {
+export function failOnSignalExit(error, result) {
     if (error)
         return error;
     if (result.exitCode === null) {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CANOPYCMS_VERSION = "0.0.68-int.111";
+export declare const CANOPYCMS_VERSION = "0.0.68-int.112";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/bump-version.mjs, its only writer. The package builds with plain
 // tsc (rootDir: src), so src/ cannot import ../package.json; version.test.ts keeps the two equal.
-export const CANOPYCMS_VERSION = '0.0.68-int.111';
+export const CANOPYCMS_VERSION = '0.0.68-int.112';

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

@@ -278,9 +278,19 @@ export declare class CmsWorker {
     /**
      * An unconfigured base branch is the one remote.git's HEAD names, which is what the Lambda
      * reads too (GitManager.detectBaseBranch); before remote.git exists, it is GitHub's default
-     * branch, which the clone then records as that HEAD. Never assumes 'main'.
+     * branch, which the clone then records as that HEAD. So it is too when remote.git has no branch
+     * outside the settings namespace: no base branch is there for HEAD to name, and ensureRemoteGit
+     * replaces it from GitHub unless something in it is at stake. Never assumes 'main'.
      */
     private resolveBaseBranch;
+    /**
+     * Check remote.git's config at boot. A refusal is never a case for replacement: it reports that
+     * something wrote there, and listing the refs a replacement would lose means running git under
+     * that config. The message says so, so System health does not read it as a routine failure.
+     */
+    private assertRemoteGitConfig;
+    /** Whether the bare repo at `gitDir` has a branch that is not a settings branch. */
+    private hasContentBranch;
     /**
      * Point remote.git's HEAD at the base branch this worker uses, so a Lambda left to detect it
      * (GitManager.detectBaseBranch) reads the same name. Only the worker writes it, at boot under
@@ -337,9 +347,27 @@ export declare class CmsWorker {
      * pushed) succeeds and leaves a refs-less repo that `fs.stat` cannot tell from a healthy one, so
      * left unchecked it silently poisons remote.git and the stat short-circuit means it never heals.
      * The base branch is therefore verified right after seeding AND on the already-exists fast
-     * path, since a previous run can have left a poisoned remote.git behind.
+     * path, where a poisoned remote.git is replaced (`replacePoisonedRemoteGit`).
      */
     private ensureRemoteGit;
+    /**
+     * Replace an existing remote.git that has no base branch with a fresh seed from GitHub, but only
+     * when every ref in it names a commit a GitHub branch contains, so replacing it loses no commit;
+     * a branch name GitHub lacks, such as a merged branch deleted there, goes. Otherwise refuse,
+     * naming the refs at stake: unpushed work such as a settings branch.
+     *
+     * The refs are compared in the same mirror session that fetches GitHub and seeds the
+     * replacement, and listed again just before the swap, since the Lambda can push into remote.git
+     * while the seed runs. The swap is two renames, so the name remote.git resolves to the old repo,
+     * the new one, or for an instant nothing, never a half-built or half-deleted one.
+     */
+    private replacePoisonedRemoteGit;
+    /**
+     * Seed a new bare repo from GitHub at `<remote.git>.cloning`, verified and configured, and
+     * return its path for the caller to rename into place. `check` runs in the mirror session right
+     * after the GitHub fetch, and its throw stops the seed. Throws with the staging directory gone.
+     */
+    private seedRemoteGitStaging;
     /**
      * Refuse a state directory on the shared filesystem: the mirror there would be as writable by
      * the Lambda as remote.git is.

package/dist/worker/cms-worker.js

@@ -6,9 +6,9 @@ import lockfile from 'proper-lockfile';
 import { recoverOrphanedTasks, cmsTaskQueueLogger } from '../task-queue/cms-task-queue.js';
 import { createCanopyOctokit } from '../github-service.js';
 import { isTransientAuthFailure, resolveWorkerGitHubAuth, } from './github-auth.js';
-import { ensureRemoteGitConfig } from '../git-manager.js';
+import { GITHUB_TRACKING_REF_PREFIX, ensureRemoteGitConfig, failOnSignalExit } from '../git-manager.js';
 import { readHeadBranch } from '../utils/git.js';
-import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX } from '../paths/branch-name.js';
+import { isSettingsBranchName, sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, } from '../paths/branch-name.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';
@@ -55,6 +55,44 @@ function defaultStateDirectory(workspacePath) {
     const key = createHash('sha256').update(path.resolve(workspacePath)).digest('hex').slice(0, 16);
     return path.join(os.tmpdir(), `canopycms-worker-${key}`);
 }
+/** How many refs a refusal to replace remote.git names before summarising the rest. */
+const MAX_REFS_LISTED = 20;
+/** A refusal to replace a poisoned remote.git because it holds work GitHub does not have. */
+class RemoteGitKeptError extends Error {
+}
+/**
+ * Every ref in the bare repo at `gitDir` outside the GitHub tracking namespace, which only ever
+ * holds GitHub's own branches, mapped to the object it names. A ref missing from this list is one
+ * a replacement would discard unchecked, so it throws when git reports anything on stderr
+ * (`for-each-ref` skips a ref it cannot read with only a warning and exit 0) and when git is killed
+ * by a signal, which simple-git otherwise resolves as empty output. A dangling symbolic ref is
+ * skipped without a warning, and names nothing to lose.
+ */
+async function listRemoteGitRefs(gitDir) {
+    let stderr = '';
+    const output = await sharedRepoGit(gitDir, 'bare', { errors: failOnSignalExit })
+        .outputHandler((_command, _stdout, err) => {
+        err.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+    })
+        .raw(['for-each-ref', '--format=%(objectname) %(refname)']);
+    if (stderr.trim() !== '')
+        throw new Error(stderr.trim());
+    const refs = new Map();
+    for (const line of output.split('\n')) {
+        const space = line.indexOf(' ');
+        if (space === -1)
+            continue;
+        const ref = line.slice(space + 1);
+        if (!ref.startsWith(GITHUB_TRACKING_REF_PREFIX))
+            refs.set(ref, line.slice(0, space));
+    }
+    return refs;
+}
+function sameRefs(a, b) {
+    return a.size === b.size && [...a].every(([ref, id]) => b.get(ref) === id);
+}
 const DEFAULT_TASK_TIMEOUT = 60_000;
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_LOCK_STALE_MS = 60_000;
@@ -675,7 +713,9 @@ export class CmsWorker {
     /**
      * An unconfigured base branch is the one remote.git's HEAD names, which is what the Lambda
      * reads too (GitManager.detectBaseBranch); before remote.git exists, it is GitHub's default
-     * branch, which the clone then records as that HEAD. Never assumes 'main'.
+     * branch, which the clone then records as that HEAD. So it is too when remote.git has no branch
+     * outside the settings namespace: no base branch is there for HEAD to name, and ensureRemoteGit
+     * replaces it from GitHub unless something in it is at stake. Never assumes 'main'.
      */
     async resolveBaseBranch() {
         if (this.resolvedBaseBranch)
@@ -698,10 +738,11 @@ export class CmsWorker {
         // Before the first git to read it, and on its own: a refusal is recorded as itself, not as a
         // base branch to configure or a remote.git to delete.
         if (remoteGitExists)
-            await assertSharedRepoConfig(this.remoteGitPath, 'bare');
+            await this.assertRemoteGitConfig();
         let name;
         try {
-            name = remoteGitExists
+            const fromRemoteGit = remoteGitExists && (await this.hasContentBranch(this.remoteGitPath));
+            name = fromRemoteGit
                 ? await readHeadBranch(this.remoteGitPath, sharedRepoGit(this.remoteGitPath, 'bare'))
                 : (await this.octokitClient().repos.get({
                     owner: this.config.githubOwner,
@@ -714,6 +755,33 @@ export class CmsWorker {
         this.setBaseBranch(name);
         workerLog(`Base branch: '${name}' (detected; CANOPYCMS_BASE_BRANCH is not set)`);
     }
+    /**
+     * Check remote.git's config at boot. A refusal is never a case for replacement: it reports that
+     * something wrote there, and listing the refs a replacement would lose means running git under
+     * that config. The message says so, so System health does not read it as a routine failure.
+     */
+    async assertRemoteGitConfig() {
+        try {
+            await assertSharedRepoConfig(this.remoteGitPath, 'bare');
+        }
+        catch (err) {
+            if (!(err instanceof SharedRepoRefusalError))
+                throw err;
+            throw new SharedRepoRefusalError(`${err.message.replace(/\.$/, '')}. This needs an operator: the worker never repairs or ` +
+                `replaces a remote.git whose config was tampered with or cannot be read.`);
+        }
+    }
+    /** Whether the bare repo at `gitDir` has a branch that is not a settings branch. */
+    async hasContentBranch(gitDir) {
+        const branches = await sharedRepoGit(gitDir, 'bare', { errors: failOnSignalExit }).raw([
+            'for-each-ref',
+            '--format=%(refname:strip=2)',
+            'refs/heads/',
+        ]);
+        return branches
+            .split('\n')
+            .some((branch) => branch !== '' && !isSettingsBranchName(branch, this.ensureSettingsBranch()));
+    }
     /**
      * Point remote.git's HEAD at the base branch this worker uses, so a Lambda left to detect it
      * (GitManager.detectBaseBranch) reads the same name. Only the worker writes it, at boot under
@@ -843,7 +911,7 @@ export class CmsWorker {
      * pushed) succeeds and leaves a refs-less repo that `fs.stat` cannot tell from a healthy one, so
      * left unchecked it silently poisons remote.git and the stat short-circuit means it never heals.
      * The base branch is therefore verified right after seeding AND on the already-exists fast
-     * path, since a previous run can have left a poisoned remote.git behind.
+     * path, where a poisoned remote.git is replaced (`replacePoisonedRemoteGit`).
      */
     async ensureRemoteGit() {
         let exists;
@@ -857,7 +925,7 @@ export class CmsWorker {
         if (exists) {
             // At boot, so a refusal lands in worker-status.json as a startup failure, and first: the
             // scrub is git reading this config too.
-            await assertSharedRepoConfig(this.remoteGitPath, 'bare');
+            await this.assertRemoteGitConfig();
             // SELF-HEAL, before anything else changes this repo: a remote.git cloned from GitHub by an
             // older worker recorded the token-bearing clone URL in its config.
             await this.scrubPersistedRemote(this.remoteGitPath);
@@ -866,15 +934,121 @@ export class CmsWorker {
             }
             catch (err) {
                 workerLogError(`remote.git base branch verification failed: ${getErrorMessage(err)}`);
-                // Do NOT auto-delete: an existing remote.git can hold unpushed
-                // canopycms-settings-* branches or other state worth preserving, so
-                // deletion is the operator's call.
-                throw new Error(`remote.git at ${this.remoteGitPath} has no branch '${this.baseBranch}' (likely cloned while the GitHub repo was empty). Delete ${this.remoteGitPath} and restart the worker to re-clone.`);
+                await this.replacePoisonedRemoteGit();
+                return;
             }
             await this.applyRemoteGitConfig(this.remoteGitPath);
             return; // Already exists and has the base branch
         }
         workerLog('Initializing remote.git from GitHub...');
+        const stagingPath = await this.seedRemoteGitStaging();
+        await fs.rename(stagingPath, this.remoteGitPath);
+        workerLog('remote.git initialized');
+    }
+    /**
+     * Replace an existing remote.git that has no base branch with a fresh seed from GitHub, but only
+     * when every ref in it names a commit a GitHub branch contains, so replacing it loses no commit;
+     * a branch name GitHub lacks, such as a merged branch deleted there, goes. Otherwise refuse,
+     * naming the refs at stake: unpushed work such as a settings branch.
+     *
+     * The refs are compared in the same mirror session that fetches GitHub and seeds the
+     * replacement, and listed again just before the swap, since the Lambda can push into remote.git
+     * while the seed runs. The swap is two renames, so the name remote.git resolves to the old repo,
+     * the new one, or for an instant nothing, never a half-built or half-deleted one.
+     */
+    async replacePoisonedRemoteGit() {
+        const poisoned = `remote.git at ${this.remoteGitPath} has no branch '${this.baseBranch}' (cloned while the ` +
+            `GitHub repository was empty, or the base branch is set to one it never had)`;
+        const notReplaced = (reason) => new Error(`${poisoned}, and it was not replaced: ${reason}`);
+        let refs;
+        try {
+            refs = await listRemoteGitRefs(this.remoteGitPath);
+        }
+        catch (err) {
+            throw notReplaced(`its refs could not all be read (${redactCredentials(getErrorMessage(err)).trim()}), so ` +
+                `the worker cannot tell whether replacing it would lose work. Deleting ` +
+                `${this.remoteGitPath} and restarting the worker re-clones it and discards every ref in it.`);
+        }
+        // Only a base branch the listing confirms absent: a check that failed for any other reason
+        // is no evidence the repo is poisoned.
+        if (refs.has(`refs/heads/${this.baseBranch}`)) {
+            throw new Error(`remote.git at ${this.remoteGitPath} has branch '${this.baseBranch}', but git could not ` +
+                `verify it, so the worker will not replace remote.git. Restarting the worker checks again.`);
+        }
+        workerLog(`remote.git has no branch '${this.baseBranch}': replacing it if GitHub has every ref in it`);
+        const stagingPath = await this.seedRemoteGitStaging(async (mirror) => {
+            const unpushed = [];
+            for (const [ref, id] of refs) {
+                if (!(await mirror.isOnGitHub(id)))
+                    unpushed.push(ref);
+            }
+            if (unpushed.length === 0)
+                return;
+            const shown = unpushed.slice(0, MAX_REFS_LISTED);
+            const more = unpushed.length - shown.length;
+            throw new RemoteGitKeptError(`${poisoned}, and it holds ${unpushed.length === 1 ? 'a ref' : `${unpushed.length} refs`} ` +
+                `GitHub does not have, so the worker will not replace it: ${shown.join(', ')}` +
+                `${more > 0 ? ` and ${more} more` : ''}. Deleting ${this.remoteGitPath} and restarting ` +
+                `the worker re-clones it and discards ${unpushed.length === 1 ? 'that ref' : 'those refs'}.`);
+        }).catch((err) => {
+            if (err instanceof RemoteGitKeptError)
+                throw err;
+            throw notReplaced(redactCredentials(getErrorMessage(err)));
+        });
+        const discardStaging = () => fs.rm(stagingPath, { recursive: true, force: true });
+        let current;
+        try {
+            current = await listRemoteGitRefs(this.remoteGitPath);
+        }
+        catch (err) {
+            await discardStaging();
+            throw notReplaced(`its refs could not all be read again (${getErrorMessage(err).trim()}). Restarting the ` +
+                `worker checks again.`);
+        }
+        if (!sameRefs(refs, current)) {
+            await discardStaging();
+            throw notReplaced('its refs changed while the worker seeded its replacement. Restarting the worker checks again.');
+        }
+        const replaced = `${this.remoteGitPath}.replaced-${Date.now()}`;
+        try {
+            await fs.rename(this.remoteGitPath, replaced);
+        }
+        catch (err) {
+            await discardStaging();
+            throw err;
+        }
+        try {
+            await fs.rename(stagingPath, this.remoteGitPath);
+        }
+        catch (err) {
+            await fs.rename(replaced, this.remoteGitPath);
+            await discardStaging();
+            throw err;
+        }
+        // A push that resolved remote.git before the rename can still land in the old repo. One that
+        // lands before this listing keeps it; a later one is lost from remote.git, though the clone
+        // that pushed still has its commit.
+        const after = await listRemoteGitRefs(replaced).catch(() => null);
+        if (after !== null && sameRefs(refs, after)) {
+            // remote.git is already replaced, so a push still writing here costs only this directory.
+            await fs
+                .rm(replaced, { recursive: true, force: true, maxRetries: 3 })
+                .catch((err) => {
+                workerLogWarn(`Could not remove the replaced remote.git at ${replaced}: ${getErrorMessage(err)}`);
+            });
+        }
+        else {
+            workerLogError(`Kept the replaced remote.git at ${replaced}: its refs changed as it was swapped out, so ` +
+                `it may hold work GitHub does not have.`);
+        }
+        workerLog('remote.git replaced');
+    }
+    /**
+     * Seed a new bare repo from GitHub at `<remote.git>.cloning`, verified and configured, and
+     * return its path for the caller to rename into place. `check` runs in the mirror session right
+     * after the GitHub fetch, and its throw stops the seed. Throws with the staging directory gone.
+     */
+    async seedRemoteGitStaging(check) {
         // Seeded under a TEMP name and renamed into place only once verified, so a crash mid-seed
         // leaves only this staging directory, which the next boot deletes, rather than a poisoned
         // `remote.git` that fs.stat cannot distinguish from a healthy one.
@@ -884,6 +1058,7 @@ export class CmsWorker {
             const githubUrl = await this.buildGitHubUrl();
             await this.githubMirror.exclusive(async (mirror) => {
                 await mirror.fetchFromGitHub(githubUrl);
+                await check?.(mirror);
                 if ((await mirror.branchTip(this.baseBranch)) === null) {
                     throw new Error(`GitHub has no branch '${this.baseBranch}'`);
                 }
@@ -899,11 +1074,15 @@ export class CmsWorker {
             await this.applyRemoteGitConfig(stagingPath);
         }
         catch (err) {
-            workerLogError(`remote.git seeding failed: ${redactCredentials(getErrorMessage(err))}`);
+            if (!(err instanceof RemoteGitKeptError)) {
+                workerLogError(`remote.git seeding failed: ${redactCredentials(getErrorMessage(err))}`);
+            }
             // Deleting before throwing is what makes this recoverable: the next
             // start() sees no remote.git and re-clones, instead of sticking forever
             // behind a poisoned bare repo fs.stat alone cannot detect.
             await fs.rm(stagingPath, { recursive: true, force: true });
+            if (err instanceof RemoteGitKeptError)
+                throw err;
             if (err instanceof SharedRepoRefusalError) {
                 // Not the refusal's own advice: the directory it names is gone.
                 throw new SharedRepoRefusalError(`Refusing to run git in ${stagingPath}: something wrote to it while the worker seeded ` +
@@ -915,8 +1094,7 @@ export class CmsWorker {
             }
             throw new Error(`remote.git clone of ${this.config.githubOwner}/${this.config.githubRepo} failed or has no branch '${this.baseBranch}' - the GitHub repository may be empty, or the base branch may not exist. Push an initial commit to '${this.baseBranch}' and restart the worker (systemd will retry automatically).`);
         }
-        await fs.rename(stagingPath, this.remoteGitPath);
-        workerLog('remote.git initialized');
+        return stagingPath;
     }
     /**
      * Refuse a state directory on the shared filesystem: the mirror there would be as writable by

package/dist/worker/git-sync.js

@@ -87,9 +87,10 @@ export async function pushSettingsBranches(ctx, git, trackedNames) {
             // worker's private mirror, which alone ever sees the credential.
             const sha = (await git.revparse(['--verify', `refs/heads/${settingsBranch}`])).trim();
             const githubUrl = await ctx.buildGitHubUrl();
-            await ctx
-                .githubMirror()
-                .exclusive((mirror) => mirror.pushToGitHub(githubUrl, settingsBranch, sha, { signal: ctx.shutdownSignal() }));
+            await ctx.githubMirror().exclusive((mirror) => mirror.pushToGitHub(githubUrl, settingsBranch, sha, {
+                signal: ctx.shutdownSignal(),
+                protectedBranches: [ctx.baseBranch],
+            }));
             workerLog(`Pushed settings branch ${settingsBranch} to GitHub`);
         }
         catch (err) {

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

@@ -43,6 +43,22 @@ export declare class GitHubMirror {
     /** Repack when it needs it, and say once if it has grown past {@link MIRROR_SIZE_WARN_KIB}. */
     maintain(): Promise<BareRemoteRepackResult>;
 }
+/**
+ * A push the worker never makes: to a name that is not a plain branch name, to the base branch, or
+ * to GitHub's default branch. No CanopyCMS flow asks for any of these, so a task that does was not
+ * written by CanopyCMS.
+ */
+export declare class RefusedPushError extends Error {
+    readonly branch: string;
+    constructor(branch: string, reason: 'invalid' | 'protected');
+}
+/**
+ * Throw {@link RefusedPushError} unless `branch` is a plain branch name: one
+ * `git check-ref-format --branch` accepts unchanged. That rules out a `:` (git would read what
+ * follows it in a refspec as another destination), `..`, `^`, `~`, `@{`, spaces and a leading
+ * `-`, so `refs/heads/<branch>` is exactly the ref a push names.
+ */
+export declare function assertPlainBranchName(branch: string): Promise<void>;
 /** What one {@link GitHubMirror.exclusive} call may do. */
 export declare class MirrorSession {
     private readonly gitDir;
@@ -66,8 +82,19 @@ export declare class MirrorSession {
      * objects the Lambda can write.
      */
     private fetchFromRemoteGit;
+    /**
+     * The branch GitHub's HEAD names, or null for a repository with none (empty, or HEAD unborn). A
+     * failure to reach GitHub throws, so a push that cannot learn it does not happen.
+     */
+    private githubDefaultBranch;
     /** The mirror's tip for `branch`, or null when GitHub had no such branch at the last fetch. */
     branchTip(branch: string): Promise<string | null>;
+    /**
+     * Whether a branch GitHub had at the last fetch contains the commit `id`, or the commit an
+     * annotated tag `id` points at. False for an object the mirror does not have, or one git cannot
+     * read as a commit.
+     */
+    isOnGitHub(id: string): Promise<boolean>;
     /**
      * Copy GitHub's branches into `remote.git`'s tracking namespace, pruning the ones GitHub no
      * longer has. `reconcileTrackedBranches` (worker/git-sync.ts) moves `refs/heads/*` from there.
@@ -83,8 +110,9 @@ export declare class MirrorSession {
      * commit from `remote.git` first is the step that brings the Lambda's objects across, through
      * the pinned `upload-pack`.
      */
-    pushToGitHub(githubUrl: string, branch: string, sha: string, options?: {
+    pushToGitHub(githubUrl: string, branch: string, sha: string, options: {
         lease?: string;
         signal?: AbortSignal;
+        protectedBranches: readonly string[];
     }): Promise<void>;
 }

package/dist/worker/github-mirror.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { simpleGit } from 'simple-git';
 import { GITHUB_TRACKING_REF_PREFIX, gitNetworkChildEnv, repackBareRemoteIfNeeded, } from '../git-manager.js';
+import { sanitizeBranchName } from '../paths/branch-name.js';
 import { getErrorMessage, redactCredentials } from '../utils/error.js';
 import { workerLogWarn } from './log.js';
 import { mirrorGitOptions, pinnedReceivePack, pinnedUploadPack } from './shared-repo-git.js';
@@ -119,6 +120,44 @@ async function assertOwnDirectory(dir) {
             `credential is used in the repository there`);
     }
 }
+/**
+ * A push the worker never makes: to a name that is not a plain branch name, to the base branch, or
+ * to GitHub's default branch. No CanopyCMS flow asks for any of these, so a task that does was not
+ * written by CanopyCMS.
+ */
+export class RefusedPushError extends Error {
+    constructor(branch, reason) {
+        super(reason === 'invalid'
+            ? `Refusing to push ${JSON.stringify(branch)} to GitHub: it is not a valid branch name.`
+            : `Refusing to push "${branch}" to GitHub: it is the base branch or GitHub's default ` +
+                `branch, which the CanopyCMS worker never pushes. Nothing in CanopyCMS queues such a ` +
+                `push; find out what wrote this task.`);
+        this.branch = branch;
+        this.name = 'RefusedPushError';
+    }
+}
+/**
+ * Throw {@link RefusedPushError} unless `branch` is a plain branch name: one
+ * `git check-ref-format --branch` accepts unchanged. That rules out a `:` (git would read what
+ * follows it in a refspec as another destination), `..`, `^`, `~`, `@{`, spaces and a leading
+ * `-`, so `refs/heads/<branch>` is exactly the ref a push names.
+ */
+export async function assertPlainBranchName(branch) {
+    let normalized;
+    try {
+        normalized = (await simpleGit().raw(['check-ref-format', '--branch', branch])).trim();
+    }
+    catch (err) {
+        // Only git's own verdict is a refusal; a failure to run git at all is transient.
+        if (/is not a valid branch name/.test(getErrorMessage(err))) {
+            throw new RefusedPushError(branch, 'invalid');
+        }
+        throw err;
+    }
+    // `@{-1}` and the like resolve to some other name.
+    if (normalized !== branch)
+        throw new RefusedPushError(branch, 'invalid');
+}
 /** What one {@link GitHubMirror.exclusive} call may do. */
 export class MirrorSession {
     constructor(gitDir, remoteGitPath, timeoutMs) {
@@ -186,6 +225,21 @@ export class MirrorSession {
             ...refspecs,
         ]);
     }
+    /**
+     * The branch GitHub's HEAD names, or null for a repository with none (empty, or HEAD unborn). A
+     * failure to reach GitHub throws, so a push that cannot learn it does not happen.
+     */
+    async githubDefaultBranch(githubUrl, signal) {
+        const out = await this.git(signal).raw([
+            'ls-remote',
+            '--symref',
+            '--end-of-options',
+            githubUrl,
+            'HEAD',
+        ]);
+        const match = /^ref: refs\/heads\/(.+)\tHEAD$/m.exec(out);
+        return match ? match[1] : null;
+    }
     /** The mirror's tip for `branch`, or null when GitHub had no such branch at the last fetch. */
     async branchTip(branch) {
         try {
@@ -196,6 +250,28 @@ export class MirrorSession {
             return null;
         }
     }
+    /**
+     * Whether a branch GitHub had at the last fetch contains the commit `id`, or the commit an
+     * annotated tag `id` points at. False for an object the mirror does not have, or one git cannot
+     * read as a commit.
+     */
+    async isOnGitHub(id) {
+        if (!isObjectId(id))
+            return false;
+        try {
+            const found = await this.git().raw([
+                'for-each-ref',
+                '--count=1',
+                '--format=%(refname)',
+                `--contains=${id}`,
+                'refs/heads/',
+            ]);
+            return found.trim() !== '';
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Copy GitHub's branches into `remote.git`'s tracking namespace, pruning the ones GitHub no
      * longer has. `reconcileTrackedBranches` (worker/git-sync.ts) moves `refs/heads/*` from there.
@@ -225,11 +301,25 @@ export class MirrorSession {
      * commit from `remote.git` first is the step that brings the Lambda's objects across, through
      * the pinned `upload-pack`.
      */
-    async pushToGitHub(githubUrl, branch, sha, options = {}) {
+    async pushToGitHub(githubUrl, branch, sha, options) {
         for (const id of [sha, ...(options.lease === undefined ? [] : [options.lease])]) {
             if (!isObjectId(id))
                 throw new Error(`Not a commit ID: ${JSON.stringify(id)}`);
         }
+        // Here, at the one place every GitHub push (plain or under a lease) goes through, so no caller
+        // can skip it, and before any git runs with `branch` in a refspec. The task queue, remote.git
+        // and the lease marker are all Lambda-writable, and the worker's base branch comes from
+        // Lambda-writable state when it is not configured (`CmsWorker.resolveBaseBranch`); GitHub's default branch is read from GitHub
+        // itself, per push.
+        await assertPlainBranchName(branch);
+        const protectedNames = [...options.protectedBranches];
+        const githubDefault = await this.githubDefaultBranch(githubUrl, options.signal);
+        if (githubDefault !== null)
+            protectedNames.push(githubDefault);
+        const target = sanitizeBranchName(branch);
+        if (protectedNames.some((name) => name === branch || sanitizeBranchName(name) === target)) {
+            throw new RefusedPushError(branch, 'protected');
+        }
         const staging = `${STAGING_PREFIX}${branch}`;
         const git = this.git(options.signal);
         try {

package/dist/worker/task-runner.js

@@ -5,6 +5,7 @@ import { BranchMetadataCorruptError, BranchMetadataFileManager, getBranchMetadat
 import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX } from '../paths/branch-name.js';
 import { getErrorMessage, redactCredentials } from '../utils/error.js';
 import { isNonFastForwardRejection, isStaleLeaseRejection, workflowPushRefusalFile, } from '../utils/git.js';
+import { RefusedPushError, assertPlainBranchName } from './github-mirror.js';
 import { clearHistoryRewrittenMarker, readPublishedSha } from './history-rewrite.js';
 import { writeWorkerStatus } from '../task-queue/worker-status.js';
 import { workerLog, workerLogError, workerLogWarn } from './log.js';
@@ -565,6 +566,16 @@ export async function pushBranchToGitHub(ctx, branch, signal) {
     // commit remote.git held when it was read, so what the marker logic at the end compares is
     // what GitHub received.
     await assertSharedRepoConfig(ctx.remoteGitPath, 'bare');
+    // Before `branch` reaches any git: `readPublishedSha` below would read a `<rev>:<path>` form as a
+    // tree lookup in remote.git. A refusal is permanent; a failure to run git is retried.
+    try {
+        await assertPlainBranchName(branch);
+    }
+    catch (err) {
+        if (err instanceof RefusedPushError)
+            throw new PermanentTaskError(err.message);
+        throw err;
+    }
     // Resolve the tokenized URL ONCE, here: all three pushes below use this
     // const and none calls ctx.buildGitHubUrl() again. A correctness
     // requirement, not tidiness, since resolution is async: the retry push sits
@@ -591,12 +602,19 @@ export async function pushBranchToGitHub(ctx, branch, signal) {
     // only after receiving the whole pack: a push killed before that changes nothing, and one
     // killed after it is found already done by the re-run.
     const outcome = await ctx.githubMirror().exclusive(async (mirror) => {
-        const push = (lease) => mirror.pushToGitHub(githubUrl, branch, outgoingSha, { lease, signal });
+        const push = (lease) => mirror.pushToGitHub(githubUrl, branch, outgoingSha, {
+            lease,
+            signal,
+            protectedBranches: [ctx.baseBranch],
+        });
         try {
             await push(marker);
             return 'pushed';
         }
         catch (err) {
+            // A retry can never make the branch not protected.
+            if (err instanceof RefusedPushError)
+                throw new PermanentTaskError(err.message);
             const message = getErrorMessage(err);
             throwIfWorkflowRefusal(branch, message);
             // A refused lease means GitHub is not at the commit we rewrote, so the

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@codemirror/language, @lezer/highlight: workaround — @mdxeditor/editor uses cm6-theme-basic-light which peer-requires these but mdxeditor doesn't declare them as dependencies",
   "name": "canopycms",
-  "version": "0.0.68-int.111",
+  "version": "0.0.68-int.112",
   "description": "CanopyCMS core package: schema-driven content, branch-aware editing, and editor UI for Next.js.",
   "license": "MIT",
   "repository": {