canopycms 0.7.1 → 0.8.0

package/dist/worker/history-rewrite.js

@@ -2,8 +2,10 @@ import path from 'node:path';
 import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../branch-metadata.js';
 import { sanitizeBranchName } from '../paths/branch-name.js';
 import { getErrorMessage, redactCredentials } from '../utils/error.js';
+import { escapeForLog } from '../utils/escape-text.js';
 import { isStaleLeaseRejection } from '../utils/git.js';
 import { enqueueTask, listTasks } from '../task-queue/cms-task-queue.js';
+import { publishesBranch } from './branch-policy.js';
 import { pinnedReceivePack, sharedRepoGit } from './shared-repo-git.js';
 import { workerLog, workerLogWarn } from './log.js';
 /**
@@ -31,24 +33,34 @@ export async function readPublishedSha(ctx, branchRef) {
     }
 }
 /**
- * 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 async function markHistoryRewritten(ctx, branchPath, branchDir, expectedSha) {
-    const current = await BranchMetadataFileManager.loadOnly(branchPath);
-    if (typeof current?.branch.historyRewrittenFrom === 'string')
-        return;
+export async function markHistoryRewritten(ctx, branchPath, branchRef, expectedSha) {
     const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
-    await meta.save({ branch: { name: branchDir, historyRewrittenFrom: expectedSha } });
+    let marked = false;
+    await meta.update((current) => {
+        marked = current?.branch.name === branchRef;
+        if (!marked || typeof current?.branch.historyRewrittenFrom === 'string')
+            return null;
+        return { branch: { historyRewrittenFrom: expectedSha } };
+    });
+    return marked;
 }
 /**
  * Clear the marker once GitHub is confirmed to hold the rewritten history.
@@ -64,15 +76,17 @@ export async function markHistoryRewritten(ctx, branchPath, branchDir, expectedS
  * Tracked, with the concurrent-clear race that can drop a marker mid-arming,
  * in safeinsights/canopycms#902.
  */
-export async function clearHistoryRewrittenMarker(ctx, branchPath, branchDir) {
+export async function clearHistoryRewrittenMarker(ctx, branchPath, branchRef) {
     try {
         const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
         // Explicit undefined clears the key -- save()'s merge only overwrites
-        // keys present in the update (same pattern as rebaseFailure).
-        await meta.save({ branch: { name: branchDir, historyRewrittenFrom: undefined } });
+        // keys present in the update (same pattern as rebaseFailure). Only a
+        // marker on `branchRef`'s own branch.json is cleared, so none is ever created here.
+        await meta.saveIf({ branch: { historyRewrittenFrom: undefined } }, (current) => current?.branch.name === branchRef &&
+            typeof current.branch.historyRewrittenFrom === 'string');
     }
     catch (err) {
-        workerLogWarn(`  Failed to clear history-rewrite marker for ${branchDir}: ${getErrorMessage(err)}`);
+        workerLogWarn(`  Failed to clear history-rewrite marker for ${branchRef}: ${getErrorMessage(err)}`);
     }
 }
 /**
@@ -124,10 +138,19 @@ export async function forcePublishToLocalRemote(ctx, branchPath, branchRef, expe
  *
  * 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 async function enqueueGitHubPush(ctx, branchRef) {
+export async function enqueueGitHubPush(ctx, branchRef, gatewayPolicy) {
+    if (gatewayPolicy && !publishesBranch(gatewayPolicy, branchRef)) {
+        workerLog(`  Not queueing a GitHub push for ${escapeForLog(branchRef)}: the GitHub gateway would refuse it`);
+        return;
+    }
     try {
         // Dedupe against tasks actually in flight rather than against the
         // marker: a branch whose GitHub push keeps failing would otherwise
@@ -157,7 +180,7 @@ export async function enqueueGitHubPush(ctx, branchRef) {
  * is the one commit we know our own rebase replaced.
  */
 export async function reconcilePendingRewrite(ctx, options) {
-    const { branchPath, branchDir, branchRef, headSha, marker } = options;
+    const { branchPath, branchDir, branchRef, headSha, marker, gatewayPolicy } = options;
     const publishedSha = await readPublishedSha(ctx, branchRef);
     if (publishedSha === null) {
         workerLogWarn(`  ${branchDir}: a rewritten history is recorded but ${branchRef} is gone from remote.git -- nothing to publish`);
@@ -166,14 +189,14 @@ export async function reconcilePendingRewrite(ctx, options) {
     if (publishedSha === headSha) {
         // remote.git already carries the rewrite; only the GitHub hop is left
         // (a crash between the push and the queue, or a task that was lost).
-        await enqueueGitHubPush(ctx, branchRef);
+        await enqueueGitHubPush(ctx, branchRef, gatewayPolicy);
         return;
     }
     if (publishedSha === marker) {
         // The publish into remote.git never landed -- a crash right after the
         // marker was written, or a lease refused by a concurrent submit.
         if (await forcePublishToLocalRemote(ctx, branchPath, branchRef, marker)) {
-            await enqueueGitHubPush(ctx, branchRef);
+            await enqueueGitHubPush(ctx, branchRef, gatewayPolicy);
         }
         return;
     }

package/dist/worker/legacy-branch-fixtures.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared `legacyBranches` test fixture.
+ *
+ * The rules deciding whether a `legacyBranches` list is usable exist TWICE by necessity: at
+ * runtime (`branch-policy.ts`'s `legacyBranchProblem` and the `BranchPolicy` constructor) and at
+ * synth time (`canopycms-cdk`'s `constructs/cms-service.ts`, which does not import core). A rule
+ * tightened at runtime but not at synth synths clean and then crash-loops the gateway at boot, so
+ * the CDK suite (`cms-deploy.test.ts`) requires both copies' verdict on every list here. Add a
+ * case when you change either copy of the rule.
+ *
+ * Dependency-free (plain arrays, no vitest import) so the CDK suite can import it across the
+ * package boundary. Each case is a resolved namespace and the list checked against it.
+ */
+/** Lists both copies must ACCEPT: `[label, namespace, entries]`. */
+export declare const VALID_LEGACY_BRANCH_LISTS: readonly (readonly [string, string, readonly string[]])[];
+/** Lists both copies must REJECT: `[label, namespace, entries]`. */
+export declare const INVALID_LEGACY_BRANCH_LISTS: readonly (readonly [
+    string,
+    string,
+    readonly string[]
+])[];

package/dist/worker/legacy-branch-fixtures.js

@@ -0,0 +1,71 @@
+/**
+ * Shared `legacyBranches` test fixture.
+ *
+ * The rules deciding whether a `legacyBranches` list is usable exist TWICE by necessity: at
+ * runtime (`branch-policy.ts`'s `legacyBranchProblem` and the `BranchPolicy` constructor) and at
+ * synth time (`canopycms-cdk`'s `constructs/cms-service.ts`, which does not import core). A rule
+ * tightened at runtime but not at synth synths clean and then crash-loops the gateway at boot, so
+ * the CDK suite (`cms-deploy.test.ts`) requires both copies' verdict on every list here. Add a
+ * case when you change either copy of the rule.
+ *
+ * Dependency-free (plain arrays, no vitest import) so the CDK suite can import it across the
+ * package boundary. Each case is a resolved namespace and the list checked against it.
+ */
+const DEFAULT_NAMESPACE = 'canopycms/prod/';
+/** Lists both copies must ACCEPT: `[label, namespace, entries]`. */
+export const VALID_LEGACY_BRANCH_LISTS = [
+    ['no entries', DEFAULT_NAMESPACE, []],
+    ['plain names', DEFAULT_NAMESPACE, ['spring', 'feature/x', 'v1.0', 'Release-2']],
+    ['a name of 255 characters, the most a branch name has', DEFAULT_NAMESPACE, ['a'.repeat(255)]],
+    ['a dash where the namespace has a slash', DEFAULT_NAMESPACE, ['canopycms-spring']],
+    ['a sibling of the namespace', DEFAULT_NAMESPACE, ['canopycms/prodigy', 'canopycms/staging/x']],
+    ['a name that only sanitizes into the namespace', DEFAULT_NAMESPACE, ['canopycms-prod-x']],
+    ['another namespace', 'cms/', ['canopycms/prod/x', 'cmsx']],
+    ['a sibling inside the parent of a custom namespace', 'cms/a/', ['cms/b']],
+    ['1024 entries', DEFAULT_NAMESPACE, Array.from({ length: 1024 }, (_, i) => `r${i}`)],
+];
+/** Lists both copies must REJECT: `[label, namespace, entries]`. */
+export const INVALID_LEGACY_BRANCH_LISTS = [
+    ['an entry in the namespace', DEFAULT_NAMESPACE, ['canopycms/prod/fix']],
+    ['an entry in a custom namespace', 'cms/', ['cms/fix']],
+    ['an entry named after the namespace', DEFAULT_NAMESPACE, ['canopycms/prod']],
+    ['an entry named after part of the namespace', DEFAULT_NAMESPACE, ['canopycms']],
+    ['an entry named after part of a custom namespace', 'edits/prod/drafts/', ['edits/prod']],
+    ['a wildcard', DEFAULT_NAMESPACE, ['release/*']],
+    ['a lone wildcard, which would switch the namespace off', DEFAULT_NAMESPACE, ['*']],
+    ['a comma', DEFAULT_NAMESPACE, ['a,b']],
+    ['a settings branch', DEFAULT_NAMESPACE, ['canopycms-settings-prod']],
+    ['an empty entry', DEFAULT_NAMESPACE, ['']],
+    ['a space', DEFAULT_NAMESPACE, ['a b']],
+    ['a control character', DEFAULT_NAMESPACE, ['a\tb']],
+    ['non-ASCII', DEFAULT_NAMESPACE, ['café']],
+    ['a percent sign', DEFAULT_NAMESPACE, ['a%2fb']],
+    ['a double quote', DEFAULT_NAMESPACE, ['a"b']],
+    ['a brace', DEFAULT_NAMESPACE, ['a{b']],
+    ['a closing brace', DEFAULT_NAMESPACE, ['a}b']],
+    ['a caret', DEFAULT_NAMESPACE, ['a^b']],
+    ['a colon', DEFAULT_NAMESPACE, ['a:b']],
+    ['an opening bracket', DEFAULT_NAMESPACE, ['a[b']],
+    ['DEL', DEFAULT_NAMESPACE, ['a\x7fb']],
+    ['a leading dash', DEFAULT_NAMESPACE, ['-x']],
+    ['a leading refs/', DEFAULT_NAMESPACE, ['refs/heads/main']],
+    ['a leading tags/ in another case', DEFAULT_NAMESPACE, ['Tags/x']],
+    ['a leading heads/', DEFAULT_NAMESPACE, ['heads/x']],
+    ['a leading remotes/', DEFAULT_NAMESPACE, ['remotes/origin/x']],
+    ['a git-forbidden character', DEFAULT_NAMESPACE, ['release-?']],
+    ['a tilde', DEFAULT_NAMESPACE, ['a~1']],
+    ['a backslash', DEFAULT_NAMESPACE, ['a\\b']],
+    ['dot-dot', DEFAULT_NAMESPACE, ['a..b']],
+    ['a reflog selector', DEFAULT_NAMESPACE, ['a@{1}']],
+    ['an empty path component', DEFAULT_NAMESPACE, ['a//b']],
+    ['a leading slash', DEFAULT_NAMESPACE, ['/a']],
+    ['a trailing slash', DEFAULT_NAMESPACE, ['a/']],
+    ['a trailing dot', DEFAULT_NAMESPACE, ['a.']],
+    ['a dot-led component', DEFAULT_NAMESPACE, ['a/.b']],
+    ['a .lock component', DEFAULT_NAMESPACE, ['a.lock/b']],
+    ['HEAD', DEFAULT_NAMESPACE, ['HEAD']],
+    ['a lone @', DEFAULT_NAMESPACE, ['@']],
+    ['a name of 256 characters, one over the most', DEFAULT_NAMESPACE, ['a'.repeat(256)]],
+    ['an entry listed twice', DEFAULT_NAMESPACE, ['spring', 'summer', 'spring']],
+    ['1025 entries', DEFAULT_NAMESPACE, Array.from({ length: 1025 }, (_, i) => `r${i}`)],
+];

package/dist/worker/rebase.d.ts

@@ -1,4 +1,5 @@
 import { type BranchMetadataFile } from '../branch-metadata.js';
+import type { BranchPolicyDescription } from './branch-policy.js';
 import type { WorkerContext } from './worker-context.js';
 /**
  * The rebase loop: the deepest leaf of the git-sync cluster, and the most
@@ -78,4 +79,4 @@ export declare function pollMergeState(ctx: RebaseContext, branchDir: string, br
  * that branch's cross-host content-write lock and runs a series of git
  * subprocesses against a shared filesystem.
  */
-export declare function runRebaseCycle(ctx: RebaseContext): Promise<RebaseSummary>;
+export declare function runRebaseCycle(ctx: RebaseContext, gatewayPolicy?: BranchPolicyDescription): Promise<RebaseSummary>;

package/dist/worker/rebase.js

@@ -3,12 +3,13 @@ import path from 'node:path';
 import { BranchMetadataFileManager, buildMergedBranchUpdate, getBranchMetadataFileManager, } from '../branch-metadata.js';
 import { extractIdFromFilename } from '../content-id-index.js';
 import { invalidateBranchContentCaches } from '../content-index-generation.js';
-import { isSettingsBranchName } from '../paths/branch-name.js';
+import { isSettingsBranchName, sanitizeBranchName } from '../paths/branch-name.js';
 import { normalizeFilesystemPath } from '../paths/normalize.js';
 import { ROOT_COLLECTION_ID } from '../paths/types.js';
 import { tryAcquireContentWriteLock } from '../utils/content-write-lock.js';
 import { holdProvisionedWorkspace, releaseProvisionedWorkspace, } from './provisioned-workspace.js';
 import { getErrorMessage, isNodeError, redactCredentials } from '../utils/error.js';
+import { escapeForLog } from '../utils/escape-text.js';
 import { isCanopyInternalPath, isRebaseInProgress } from '../utils/git.js';
 import { TRACKED_CANOPY_STATE_FIX, restoreRetiredSchemaCache, splitByUpstreamTracking, trackedCanopyStateChanges, } from './canopy-state.js';
 import { enqueueGitHubPush, forcePublishToLocalRemote, markHistoryRewritten, readPublishedSha, reconcilePendingRewrite, } from './history-rewrite.js';
@@ -29,6 +30,9 @@ export async function pollMergeState(ctx, branchDir, branchPath, metaFile) {
     const prNumber = metaFile?.branch.pullRequestNumber;
     if (!prNumber)
         return;
+    // Recorded only on a branch.json that still names the branch this poll read: never a missing
+    // one, nor another branch's that shares the key.
+    const sameBranch = (current) => current?.branch.name === metaFile?.branch.name;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), ctx.taskTimeoutMs);
     try {
@@ -37,10 +41,11 @@ export async function pollMergeState(ctx, branchDir, branchPath, metaFile) {
             const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
             // GitHub's actual merge time when available; buildMergedBranchUpdate
             // falls back to "now" when merged_at is absent.
-            await meta.save({
-                branch: buildMergedBranchUpdate(branchDir, data.merged_at ? new Date(data.merged_at) : undefined),
-            });
-            workerLog(`  PR #${prNumber} for ${branchDir} is merged -> archived`);
+            const saved = await meta.saveIf({
+                branch: buildMergedBranchUpdate(data.merged_at ? new Date(data.merged_at) : undefined),
+            }, sameBranch);
+            if (saved)
+                workerLog(`  PR #${prNumber} for ${branchDir} is merged -> archived`);
             return;
         }
         const newState = data.state === 'closed' ? 'closed' : 'open';
@@ -50,8 +55,9 @@ export async function pollMergeState(ctx, branchDir, branchPath, metaFile) {
         if (currentMeta?.branch.pullRequestState === newState)
             return;
         const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
-        await meta.save({ branch: { name: branchDir, pullRequestState: newState } });
-        workerLog(`  PR #${prNumber} for ${branchDir}: pullRequestState -> ${newState}`);
+        const saved = await meta.saveIf({ branch: { pullRequestState: newState } }, sameBranch);
+        if (saved)
+            workerLog(`  PR #${prNumber} for ${branchDir}: pullRequestState -> ${newState}`);
     }
     catch (err) {
         // Non-fatal: transient GitHub/network errors are retried next cycle.
@@ -72,9 +78,10 @@ export async function pollMergeState(ctx, branchDir, branchPath, metaFile) {
  * paths: a corrupt branch.json, lock contention or any other save failure must
  * never abort the per-branch iteration. One of the two call sites is inside the
  * outer per-branch catch with no further catch around it, so the WHOLE method
- * is wrapped, not just the load.
+ * is wrapped, not just the load. It updates an existing branch.json only, never creating one,
+ * and, given `branchRef`, only the one whose `name` is that ref.
  */
-async function recordRebaseFailure(ctx, branchPath, branchDir, message) {
+async function recordRebaseFailure(ctx, branchPath, branchDir, message, branchRef) {
     const RECORD_REFRESH_MS = 60 * 60 * 1000; // 1 hour
     // [REDACT] Defense in depth: rebaseFailure.message is persisted to
     // branch.json and served to the browser by the branch-health admin endpoint.
@@ -96,12 +103,7 @@ async function recordRebaseFailure(ctx, branchPath, branchDir, message) {
         const nowIso = now.toISOString();
         const firstAt = sameMessage ? prior.firstAt : nowIso;
         const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
-        await meta.save({
-            branch: {
-                name: branchDir,
-                rebaseFailure: { message: redactedMessage, firstAt, lastAt: nowIso },
-            },
-        });
+        await meta.saveIf({ branch: { rebaseFailure: { message: redactedMessage, firstAt, lastAt: nowIso } } }, (current) => current !== null && (branchRef === undefined || current.branch.name === branchRef));
     }
     catch (err) {
         // Includes BranchMetadataCorruptError from the load above (a save() against
@@ -328,7 +330,7 @@ function recordConflicts(recorded, found) {
  * clone's pre-rebase tip is exactly what the rebase destroys.
  */
 async function carryForwardRewrittenHistory(ctx, args) {
-    const { branchPath, branchDir, branchRef, publishedSha, preRebaseHead } = args;
+    const { branchPath, branchDir, branchRef, publishedSha, preRebaseHead, gatewayPolicy } = args;
     if (publishedSha !== null) {
         if (publishedSha === preRebaseHead) {
             // ARMING GUARD: remote.git holds EXACTLY what this clone just rebased
@@ -345,14 +347,19 @@ async function carryForwardRewrittenHistory(ctx, args) {
             // delete that fixup from remote.git and then GitHub. Keying the lease to
             // the pre-rebase tip turns that case into the visible divergence it is.
             //
-            // Order matters: mark, then push, then queue. A crash after any step
+            // Order matters: mark, then push, then queue, and a mark that declines
+            // (no branch.json names this ref) publishes nothing. A crash after any step
             // leaves the marker set with the work unfinished, which
             // reconcilePendingRewrite() completes on a later cycle. Pushing first
             // would leave remote.git rewritten, GitHub stale and nothing recorded --
             // unrecoverable, and diagnosed as a false "another deployment" collision.
-            await markHistoryRewritten(ctx, branchPath, branchDir, publishedSha);
+            if (!(await markHistoryRewritten(ctx, branchPath, branchRef, publishedSha))) {
+                workerLogWarn(`  ${branchDir}: rebased, but its branch.json is gone or names another branch than ` +
+                    `${branchRef}, so the rewrite is not published`);
+                return;
+            }
             if (await forcePublishToLocalRemote(ctx, branchPath, branchRef, publishedSha)) {
-                await enqueueGitHubPush(ctx, branchRef);
+                await enqueueGitHubPush(ctx, branchRef, gatewayPolicy);
             }
         }
         else {
@@ -360,7 +367,7 @@ async function carryForwardRewrittenHistory(ctx, args) {
                 `clone never had (a direct push to the branch?). Left untouched -- reconcile it ` +
                 `before submitting again.`;
             workerLogWarn(`  ${branchDir}: ${divergence}`);
-            await recordRebaseFailure(ctx, branchPath, branchDir, divergence);
+            await recordRebaseFailure(ctx, branchPath, branchDir, divergence, branchRef);
         }
     }
 }
@@ -376,7 +383,7 @@ async function carryForwardRewrittenHistory(ctx, args) {
  * that branch's cross-host content-write lock and runs a series of git
  * subprocesses against a shared filesystem.
  */
-export async function runRebaseCycle(ctx) {
+export async function runRebaseCycle(ctx, gatewayPolicy) {
     const rebased = [];
     const skippedDirty = [];
     const skippedLocked = [];
@@ -433,7 +440,7 @@ export async function runRebaseCycle(ctx) {
             workerLogWarn(`  Skipping ${branchDir}: settings branch, never a content workspace`);
             continue;
         }
-        const outcome = await holdAndRebaseOneBranch(ctx, branchDir, branchPath);
+        const outcome = await holdAndRebaseOneBranch(ctx, branchDir, branchPath, gatewayPolicy);
         if (outcome.kind === 'rebased')
             rebased.push(branchDir);
         else if (outcome.kind === 'skippedDirty')
@@ -450,6 +457,50 @@ export async function runRebaseCycle(ctx) {
     }
     return { rebased, skippedDirty, skippedLocked, failed };
 }
+/**
+ * The ref a branch clone's HEAD names, or null for a detached or unreadable one. Read from the
+ * file rather than through git, so it runs before `assertSharedRepoConfig` vets the clone.
+ */
+async function readCloneRef(branchPath) {
+    try {
+        const head = (await fs.readFile(path.join(branchPath, '.git', 'HEAD'), 'utf-8')).trim();
+        return head.startsWith('ref: refs/heads/') ? head.slice('ref: refs/heads/'.length) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Restore `name` to the clone's own ref when a worker that predates the namespace renamed a
+ * namespace branch to its directory (`canopycms-prod-x` for `canopycms/prod/x`), which no request
+ * resolves. Only when the ref is in `namespace` and the directory is that ref sanitized, so the
+ * ref is the name the branch was created with. Runs for every status, so a branch in review heals
+ * too. Resolves the metadata the rest of the cycle reads; a branch left alone, or a write that
+ * fails, keeps `metaFile`.
+ */
+async function restoreRenamedBranch(ctx, branchDir, branchPath, metaFile, namespace) {
+    // A name already in the namespace was never renamed; one that differs from the ref shares its
+    // key with another branch, which this does not decide.
+    if (metaFile === null || namespace === undefined || metaFile.branch.name.startsWith(namespace)) {
+        return metaFile;
+    }
+    const staleName = metaFile.branch.name;
+    const ref = await readCloneRef(branchPath);
+    if (ref === null || !ref.startsWith(namespace) || sanitizeBranchName(ref) !== branchDir) {
+        return metaFile;
+    }
+    try {
+        const restored = await getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath).update((existing) => (existing?.branch.name === staleName ? { branch: { name: ref } } : null), { keepUpdatedAt: true });
+        if (restored === null)
+            return BranchMetadataFileManager.loadOnly(branchPath);
+        workerLog(`  ${branchDir}: restored its name ${escapeForLog(ref)} from ${escapeForLog(staleName)}`);
+        return restored;
+    }
+    catch (err) {
+        workerLogWarn(`  ${branchDir}: could not restore its name ${escapeForLog(ref)}: ${getErrorMessage(err)}`);
+        return metaFile;
+    }
+}
 /**
  * {@link rebaseOneBranch} under the branch's provisioning lock, so no git step races a clone of
  * this directory. A branch whose lock is held elsewhere is `skippedLocked` and retried next cycle;
@@ -457,7 +508,7 @@ export async function runRebaseCycle(ctx) {
  * content-write lock inside it; see `provisioned-workspace.ts` for why that order cannot deadlock.
  * Never throws, like rebaseOneBranch.
  */
-async function holdAndRebaseOneBranch(ctx, branchDir, branchPath) {
+async function holdAndRebaseOneBranch(ctx, branchDir, branchPath, gatewayPolicy) {
     let hold;
     try {
         hold = await holdProvisionedWorkspace(ctx.contentBranchesPath, branchDir);
@@ -477,7 +528,7 @@ async function holdAndRebaseOneBranch(ctx, branchDir, branchPath) {
     if (hold.kind === 'not-provisioned')
         return { kind: 'none' };
     try {
-        return await rebaseOneBranch(ctx, branchDir, branchPath, hold.isCompromised);
+        return await rebaseOneBranch(ctx, branchDir, branchPath, hold.isCompromised, gatewayPolicy);
     }
     finally {
         await releaseProvisionedWorkspace(hold.release, branchDir);
@@ -495,12 +546,13 @@ async function holdAndRebaseOneBranch(ctx, branchDir, branchPath) {
  * returned as `{ kind: 'failed' }`, so one unreadable branch cannot halt the
  * rest of the cycle ([SYNC-M2]).
  */
-async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCompromised) {
+async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCompromised, gatewayPolicy) {
     // Read only by the catch below. See the `rebased` rider on
     // BranchRebaseOutcome.
     let didRebase = false;
     try {
-        const metaFile = await BranchMetadataFileManager.loadOnly(branchPath);
+        // Restored first: everything below this cycle compares `name`.
+        const metaFile = await restoreRenamedBranch(ctx, branchDir, branchPath, await BranchMetadataFileManager.loadOnly(branchPath), gatewayPolicy?.namespace);
         const branchStatus = metaFile?.branch.status;
         // Skip branches that must not be mutated:
         // - submitted/approved: in review, so never rewrite history under an active
@@ -683,6 +735,7 @@ async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCom
                     branchRef,
                     headSha: (await branchGit.revparse(['HEAD'])).trim(),
                     marker: metaFile.branch.historyRewrittenFrom,
+                    gatewayPolicy,
                 });
             }
             await fetchFromRemoteGit(branchGit, ctx.remoteGitPath, ctx.baseBranch);
@@ -714,7 +767,8 @@ async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCom
                 if (currentMeta?.branch.rebaseFailure === undefined) {
                     return { kind: 'none' };
                 }
-                await meta.save({ branch: { name: branchDir, rebaseFailure: undefined } });
+                const storedName = currentMeta.branch.name;
+                await meta.saveIf({ branch: { rebaseFailure: undefined } }, (existing) => existing?.branch.name === storedName);
                 return { kind: 'none' };
             }
             workerLog(`Rebasing ${branchDir} (${behindCount} commits behind)...`);
@@ -790,15 +844,17 @@ async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCom
             workerLog(hadConflicts
                 ? `  Rebased ${branchDir} (kept branch version for ${conflictIdsDeduped.length} conflicting file(s))`
                 : `  Rebased ${branchDir} successfully`);
-            await meta.update((existing) => ({
-                branch: {
-                    name: branchDir,
-                    ...recordConflicts(existing?.branch.conflictFiles, conflictIdsDeduped),
-                    // The cycle completed, so clear any prior failure record regardless
-                    // of the conflict outcome.
-                    rebaseFailure: undefined,
-                },
-            }));
+            // Recorded only on a branch.json that still names the branch this cycle read.
+            await meta.update((existing) => existing !== null && existing.branch.name === metaFile?.branch.name
+                ? {
+                    branch: {
+                        ...recordConflicts(existing.branch.conflictFiles, conflictIdsDeduped),
+                        // The cycle completed, so clear any prior failure record regardless
+                        // of the conflict outcome.
+                        rebaseFailure: undefined,
+                    },
+                }
+                : null);
             didRebase = true;
             await carryForwardRewrittenHistory(ctx, {
                 branchPath,
@@ -806,6 +862,7 @@ async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCom
                 branchRef,
                 publishedSha,
                 preRebaseHead,
+                gatewayPolicy,
             });
             return { kind: 'rebased' };
         }

package/dist/worker/task-runner.d.ts

@@ -62,7 +62,10 @@ export declare function orphanRecoveryMaxAgeMs(ctx: Pick<TaskRunnerContext, 'tas
 export declare function processTaskQueue(ctx: TaskRunnerContext): Promise<void>;
 export declare function executeTask(ctx: TaskRunnerContext, task: Task, signal: AbortSignal): Promise<Record<string, unknown>>;
 /**
- * Update branch metadata after successful task completion.
+ * Update branch metadata after successful task completion. Like every outcome write here, it
+ * updates only a branch.json whose `name` is the task's ref: a workspace without one is not a
+ * branch whose name could be recorded, and one naming another ref is that branch's
+ * (`noMetadataToRecord`).
  */
 export declare function updateBranchMetadata(ctx: TaskRunnerContext, task: Task, result: Record<string, unknown>): Promise<void>;
 export declare function pushBranchToGitHub(ctx: TaskRunnerContext, branch: string, signal?: AbortSignal): Promise<void>;