canopycms 0.0.67 → 0.0.68-int.93

package/dist/worker/canopy-state.js

@@ -0,0 +1,75 @@
+import { SCHEMA_CACHE_FILE } from '../branch-schema-cache.js';
+import { CANOPY_META_DIR, isCanopyInternalPath } from '../utils/git.js';
+/**
+ * How the sync loop treats canopycms's own state (`.canopy-meta/`) in a branch clone. It is
+ * never content, so untracked state never makes a clone "dirty" for sync, but git refuses some
+ * operations over it while the adopter's repo tracks it. Only the adopter can stop that; once
+ * they have, the base clone follows on its next fast-forward ({@link untrackInIndex}), and a
+ * branch clone with modified tracked state needs an operator.
+ */
+/** The fix an operator applies when an adopter repo tracks `.canopy-meta/`. */
+export const TRACKED_CANOPY_STATE_FIX = 'run `git rm -r --cached .canopy-meta` in the site repo, add `.canopy-meta/` to its .gitignore, and commit';
+/** Paths listed in worker-status.json per category; the admin panel shows them in a tooltip. */
+export const MAX_REPORTED_PATHS = 10;
+/** The schema cache's location in a clone before it moved under `.git/` (branch-schema-cache.ts). */
+const RETIRED_SCHEMA_CACHE_PATH = `${CANOPY_META_DIR}/${SCHEMA_CACHE_FILE}`;
+export function isUntracked(file) {
+    return file.index === '?' && file.working_dir === '?';
+}
+/** NUL-separated git output, which is never quoted, unlike `core.quotePath` line output. */
+function splitNul(out) {
+    return out.split('\0').filter((entry) => entry.length > 0);
+}
+/** Files under `.canopy-meta/` that the clone's index tracks. */
+export async function listTrackedCanopyState(git) {
+    return splitNul(await git.raw(['ls-files', '-z', '--', CANOPY_META_DIR]));
+}
+/**
+ * Discard local changes to the schema cache's retired in-tree copy, so a clone of a repo that
+ * committed it can sync again. Nothing reads or writes that path in a clone any more, so its
+ * content is dead; but while it differs from HEAD, `git rebase` refuses to start and a
+ * fast-forward that touches it (including the adopter's own commit untracking it) refuses too.
+ * An untracked copy blocks neither and a newly staged one has nothing in HEAD to restore, so
+ * both are left alone. Returns whether it restored anything; the caller re-reads status if so.
+ */
+export async function restoreRetiredSchemaCache(git, status) {
+    const entry = status.files.find((f) => f.path === RETIRED_SCHEMA_CACHE_PATH);
+    if (!entry || entry.index === '?' || entry.index === 'A')
+        return false;
+    await git.raw(['checkout', 'HEAD', '--', RETIRED_SCHEMA_CACHE_PATH]);
+    return true;
+}
+/**
+ * The changed tracked `.canopy-meta/` files in `status`: what git refuses to rebase over, and
+ * what a fast-forward refuses to overwrite where it touches them.
+ */
+export function trackedCanopyStateChanges(status) {
+    return status.files
+        .filter((f) => isCanopyInternalPath(f.path) && !isUntracked(f))
+        .map((f) => f.path);
+}
+/**
+ * Split `paths` by whether the commit `tip` still tracks them. Those it no longer tracks, the
+ * adopter has untracked upstream, so a fast-forward onto `tip` would delete them from disk unless
+ * {@link untrackInIndex} takes them out of the index first.
+ */
+export async function splitByUpstreamTracking(git, paths, tip) {
+    if (paths.length === 0)
+        return { droppedUpstream: [], stillTracked: [] };
+    const tracked = new Set(splitNul(await git.raw(['ls-tree', '-r', '-z', '--name-only', tip, '--', CANOPY_META_DIR])));
+    return {
+        droppedUpstream: paths.filter((p) => !tracked.has(p)),
+        stillTracked: paths.filter((p) => tracked.has(p)),
+    };
+}
+/**
+ * Remove `paths` from this clone's index, leaving them on disk as untracked, excluded state.
+ * Index-only, so a concurrent write to them (branch metadata, comments) is not lost. Only for a
+ * clone with no commits of its own: a rebase that replays a commit touching these paths writes
+ * that commit's bytes over them. Paths already out of the index are ignored.
+ */
+export async function untrackInIndex(git, paths) {
+    if (paths.length === 0)
+        return;
+    await git.raw(['rm', '--cached', '--ignore-unmatch', '-q', '--', ...paths]);
+}

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

@@ -1,4 +1,5 @@
 import { simpleGit } from 'simple-git';
+import type { BaseRefreshReport } from '../types.js';
 import { type RebaseContext } from './rebase.js';
 import type { WorkerContext } from './worker-context.js';
 /**
@@ -56,10 +57,11 @@ export declare function cleanupTrashedBranchDirs(ctx: Pick<GitSyncContext, 'cont
  * A dedicated, explicit and LOUD step rather than a side effect of the rebase
  * loop, whose skip paths (a dirty tree, a missing .git) are silent: a wedged
  * base clone otherwise leaves no diagnosable signal, and an editor forking a
- * new branch "from base" silently gets a stale snapshot.
+ * new branch "from base" silently gets a stale snapshot. The returned outcome
+ * goes to worker-status.json for the same reason.
  *
  * ff-only on purpose: this clone must stay a linear mirror of
  * origin/<baseBranch>, so a merge that isn't a fast-forward (diverged local
  * history) is left untouched rather than force-resolved.
  */
-export declare function refreshBaseBranchWorkspace(ctx: GitSyncContext): Promise<void>;
+export declare function refreshBaseBranchWorkspace(ctx: GitSyncContext): Promise<BaseRefreshReport>;

package/dist/worker/git-sync.js

@@ -3,15 +3,17 @@ import path from 'node:path';
 import { simpleGit } from 'simple-git';
 import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../branch-metadata.js';
 import { invalidateBranchContentCaches } from '../content-index-generation.js';
-import { GITHUB_TRACKING_REF_PREFIX, gitNetworkChildEnv } from '../git-manager.js';
+import { GITHUB_TRACKING_REF_PREFIX, ensureGitExcludePattern, gitNetworkChildEnv, } from '../git-manager.js';
 import { RESERVED_SETTINGS_BRANCH_PREFIX } from '../paths/branch-name.js';
 import { getErrorMessage, isNodeError, redactCredentials } from '../utils/error.js';
-import { isNonFastForwardRejection } from '../utils/git.js';
+import { CANOPY_META_DIR, isCanopyInternalPath, isNonFastForwardRejection } from '../utils/git.js';
+import { MAX_REPORTED_PATHS, TRACKED_CANOPY_STATE_FIX, isUntracked, listTrackedCanopyState, restoreRetiredSchemaCache, splitByUpstreamTracking, untrackInIndex, } from './canopy-state.js';
 import { hasPendingHistoryRewrite } from './history-rewrite.js';
 import { runRebaseCycle } from './rebase.js';
 import { cleanupOldTasks } from '../task-queue/cms-task-queue.js';
 import { writeWorkerStatus } from '../task-queue/worker-status.js';
 import { workerLog, workerLogError, workerLogWarn } from './log.js';
+import { holdProvisionedWorkspace, releaseProvisionedWorkspace } from './provisioned-workspace.js';
 /**
  * [C1] Retention window for `.trash-*` branch directories left behind by the
  * admin purge action (api/admin-branch-health.ts). Matches
@@ -306,7 +308,7 @@ export async function syncGit(ctx) {
         // correctness dependency now that the fetch can't clobber refs/heads/*
         // -- this could run before or after them just as safely.
         await pushSettingsBranches(ctx, git, trackedNames);
-        await refreshBaseBranchWorkspace(ctx);
+        const baseRefresh = await refreshBaseBranchWorkspace(ctx);
         const rebaseSummary = await runRebaseCycle(ctx);
         await cleanupOldTasks(ctx.taskDir, undefined, ctx.log);
         // [C1] Sweep branch directories the admin purge action trashed more than
@@ -323,9 +325,14 @@ export async function syncGit(ctx) {
         report.lastGitSync = {
             durationMs: Date.now() - cycleStartedAt,
             rebased: rebaseSummary.rebased,
-            skippedDirty: rebaseSummary.skippedDirty,
-            skippedLocked: rebaseSummary.skippedLocked,
+            skippedDirty: baseRefresh.outcome === 'skipped-dirty'
+                ? [ctx.sanitizedBaseBranch, ...rebaseSummary.skippedDirty]
+                : rebaseSummary.skippedDirty,
+            skippedLocked: baseRefresh.outcome === 'skipped-locked'
+                ? [ctx.sanitizedBaseBranch, ...rebaseSummary.skippedLocked]
+                : rebaseSummary.skippedLocked,
             failed: rebaseSummary.failed,
+            baseRefresh,
             tracked: trackedSummary,
         };
         await writeWorkerStatus(ctx.taskDir, report).catch((writeErr) => workerLogError('Failed to write worker status:', getErrorMessage(writeErr)));
@@ -393,6 +400,12 @@ export async function cleanupTrashedBranchDirs(ctx) {
     }
     return removed;
 }
+/**
+ * Warned (base path + tracked file list) pairs, so a repo that tracks
+ * `.canopy-meta/` is called out once per worker process rather than every cycle;
+ * worker-status.json carries it every cycle regardless.
+ */
+const warnedTrackedCanopyState = new Set();
 /**
  * Fast-forward the base branch's own working-tree clone
  * (content-branches/<baseBranch>) to match origin/<baseBranch>, every sync
@@ -401,7 +414,8 @@ export async function cleanupTrashedBranchDirs(ctx) {
  * A dedicated, explicit and LOUD step rather than a side effect of the rebase
  * loop, whose skip paths (a dirty tree, a missing .git) are silent: a wedged
  * base clone otherwise leaves no diagnosable signal, and an editor forking a
- * new branch "from base" silently gets a stale snapshot.
+ * new branch "from base" silently gets a stale snapshot. The returned outcome
+ * goes to worker-status.json for the same reason.
  *
  * ff-only on purpose: this clone must stay a linear mirror of
  * origin/<baseBranch>, so a merge that isn't a fast-forward (diverged local
@@ -411,19 +425,30 @@ export async function refreshBaseBranchWorkspace(ctx) {
     // Sanitized name for the workspace directory (a base branch containing
     // e.g. '/' would otherwise stat a wrong nested path here forever).
     const basePath = path.join(ctx.contentBranchesPath, ctx.sanitizedBaseBranch);
-    const gitDir = path.join(basePath, '.git');
+    let trackedCanopyMeta;
+    let releaseProvisioning;
     try {
-        let gitDirStat;
-        try {
-            gitDirStat = await fs.stat(gitDir);
-        }
-        catch {
-            gitDirStat = null;
+        // Held to the end, so no git step below races a clone of this directory.
+        const hold = await holdProvisionedWorkspace(ctx.contentBranchesPath, ctx.sanitizedBaseBranch);
+        if (hold.kind === 'locked') {
+            workerLog(`Base branch workspace (${ctx.baseBranch}): provisioning lock held elsewhere, skipping refresh`);
+            return { outcome: 'skipped-locked' };
         }
-        if (!gitDirStat || !gitDirStat.isDirectory()) {
+        if (hold.kind === 'not-provisioned') {
             workerLog(`Base branch workspace (${ctx.baseBranch}): not yet provisioned, skipping refresh`);
-            return;
+            return { outcome: 'skipped-not-provisioned' };
         }
+        releaseProvisioning = hold.release;
+        // Checked before each destructive step: a lost lock means another process
+        // may be cloning into this directory.
+        const lockLost = () => {
+            if (!hold.isCompromised())
+                return null;
+            workerLogWarn(`Base branch workspace (${ctx.baseBranch}): provisioning lock lost mid-refresh, stopping`);
+            return { outcome: 'skipped-locked', trackedCanopyMeta };
+        };
+        // Idempotent, and applied every cycle so any clone lacking it gets it.
+        await ensureGitExcludePattern(basePath, `${CANOPY_META_DIR}/`);
         const baseGit = simpleGit({
             baseDir: basePath,
             // Keep git non-interactive during the merge so it never blocks on an
@@ -437,17 +462,43 @@ export async function refreshBaseBranchWorkspace(ctx) {
             // Inactivity-based, so a slow-but-flowing transfer is unaffected.
             timeout: { block: ctx.taskTimeoutMs },
         });
+        const trackedState = await listTrackedCanopyState(baseGit);
+        if (trackedState.length > 0) {
+            trackedCanopyMeta = trackedState.slice(0, MAX_REPORTED_PATHS);
+            const warnKey = `${basePath}\0${trackedState.join('\0')}`;
+            if (!warnedTrackedCanopyState.has(warnKey)) {
+                warnedTrackedCanopyState.add(warnKey);
+                workerLogWarn(`Base branch (${ctx.baseBranch}) tracks canopycms state that must not be committed: ` +
+                    `${trackedState.join(', ')}. To fix, ${TRACKED_CANOPY_STATE_FIX}.`);
+            }
+        }
+        let status = await baseGit.status();
+        const lostBeforeRestore = lockLost();
+        if (lostBeforeRestore)
+            return lostBeforeRestore;
+        if (await restoreRetiredSchemaCache(baseGit, status)) {
+            workerLog(`Base branch workspace (${ctx.baseBranch}): restored the retired in-tree schema cache`);
+            status = await baseGit.status();
+        }
         // Nothing makes this clone read-only, and a direct edit here wedges every
         // editor's view of the base branch until an operator intervenes, so a dirty
-        // tree is loud, not a quiet skip. Only TRACKED changes block the refresh: a
-        // stray untracked file must not wedge the fast-forward forever, and if one
-        // would collide with incoming content the --ff-only merge below refuses on
-        // its own and that failure is already logged loudly.
-        const status = await baseGit.status();
-        const trackedDirty = status.files.filter((f) => f.index !== '?' || f.working_dir !== '?');
+        // tree is loud, not a quiet skip. Only TRACKED content changes block the
+        // refresh: canopycms's own state never does, and neither does a stray
+        // untracked file. A modified tracked file or an untracked one that would
+        // collide with incoming content makes the --ff-only merge below refuse and
+        // report `failed`; an IGNORED file, which every .canopy-meta file is, git
+        // overwrites instead.
+        const trackedDirty = status.files
+            .filter((f) => !isUntracked(f) && !isCanopyInternalPath(f.path))
+            .map((f) => f.path);
         if (trackedDirty.length > 0) {
-            workerLogError(`Base branch workspace (${ctx.baseBranch}) has uncommitted changes -- skipping refresh. Dirty files: ${trackedDirty.map((f) => f.path).join(', ')}`);
-            return;
+            workerLogError(`Base branch workspace (${ctx.baseBranch}) has uncommitted changes -- skipping refresh. Dirty files: ${trackedDirty.join(', ')}`);
+            return {
+                outcome: 'skipped-dirty',
+                dirtyFiles: trackedDirty.slice(0, MAX_REPORTED_PATHS),
+                message: `${trackedDirty.length} uncommitted tracked file(s) in the base branch workspace`,
+                trackedCanopyMeta,
+            };
         }
         // Raw (unsanitized) name from here on: these are git ref operations
         // against origin/<baseBranch>, not filesystem paths, so they must use
@@ -462,12 +513,31 @@ export async function refreshBaseBranchWorkspace(ctx) {
         const fetchedTip = (await baseGit.revparse(['FETCH_HEAD'])).trim();
         const behindCount = parseInt((await baseGit.raw(['rev-list', '--count', `HEAD..${fetchedTip}`])).trim(), 10);
         if (behindCount > 0) {
+            const lostBeforeMerge = lockLost();
+            if (lostBeforeMerge)
+                return lostBeforeMerge;
+            // Untrack, in the index only, any state the tip has stopped tracking:
+            // the merge would otherwise refuse to overwrite a modified copy, or
+            // delete a clean one from disk. Safe here and not in the rebase loop,
+            // because this clone has no commits of its own to replay. State still
+            // tracked upstream is left for the merge, which refuses where upstream
+            // changed a locally modified copy.
+            const { droppedUpstream } = await splitByUpstreamTracking(baseGit, trackedState, fetchedTip);
+            if (droppedUpstream.length > 0) {
+                await untrackInIndex(baseGit, droppedUpstream);
+                workerLog(`Base branch workspace (${ctx.baseBranch}): stopped tracking ${droppedUpstream.join(', ')}, as upstream has`);
+            }
             try {
                 await baseGit.merge(['--ff-only', fetchedTip]);
             }
             catch (err) {
                 workerLogError(`Base branch workspace (${ctx.baseBranch}) failed to fast-forward (diverged local history?): ${getErrorMessage(err)}`);
-                return;
+                return {
+                    outcome: 'failed',
+                    // [REDACT] Served to the browser by the admin panel.
+                    message: redactCredentials(`failed to fast-forward: ${getErrorMessage(err)}`),
+                    trackedCanopyMeta,
+                };
             }
             await invalidateBranchContentCaches(basePath);
         }
@@ -491,8 +561,25 @@ export async function refreshBaseBranchWorkspace(ctx) {
         workerLog(behindCount > 0
             ? `Base branch workspace (${ctx.baseBranch}): fast-forwarded ${behindCount} commit(s)`
             : `Base branch workspace (${ctx.baseBranch}): up to date`);
+        if (trackedCanopyMeta && behindCount > 0) {
+            const stillTracked = await listTrackedCanopyState(baseGit);
+            trackedCanopyMeta =
+                stillTracked.length > 0 ? stillTracked.slice(0, MAX_REPORTED_PATHS) : undefined;
+        }
+        return { outcome: behindCount > 0 ? 'refreshed' : 'up-to-date', trackedCanopyMeta };
     }
     catch (err) {
         workerLogError(`Base branch workspace (${ctx.baseBranch}) refresh failed: ${getErrorMessage(err)}`);
+        // [REDACT] Served to the browser by the admin panel.
+        return {
+            outcome: 'failed',
+            message: redactCredentials(getErrorMessage(err)),
+            trackedCanopyMeta,
+        };
+    }
+    finally {
+        if (releaseProvisioning) {
+            await releaseProvisionedWorkspace(releaseProvisioning, ctx.sanitizedBaseBranch);
+        }
     }
 }

package/dist/worker/provisioned-workspace.d.ts

@@ -0,0 +1,35 @@
+export type ProvisionedWorkspaceHold = {
+    kind: 'held';
+    release: () => Promise<void>;
+    /**
+     * Whether the lock was lost mid-hold (its marker vanished or was taken over), so another
+     * process may now be cloning into this directory. Callers check it before each destructive
+     * git step and stop rather than carry on unguarded.
+     */
+    isCompromised: () => boolean;
+}
+/** Another process holds the provisioning lock: a clone, or an admin purge or repair, is in flight. */
+ | {
+    kind: 'locked';
+}
+/** No clone with metadata at this path yet. */
+ | {
+    kind: 'not-provisioned';
+};
+/**
+ * Take a branch workspace's provisioning lock for the sync loop, the same cross-host lock the
+ * Lambda holds while it clones the workspace (`branch-workspace.ts`), so the worker never runs git
+ * against a half-made clone. The caller holds it across its dirty check and every git step, and
+ * releases it in a `finally`.
+ *
+ * Zero retries: the worker skips and retries next cycle rather than wait, so it never blocks on
+ * the Lambda and cannot deadlock with it. The rebase nests the content-write lock inside this one;
+ * the worker takes that one try-only as well, so the nesting cannot deadlock either.
+ *
+ * Provisioned means a `.git` directory AND `branch.json`. The Lambda clones directly into the
+ * target path, so `.git` appears early, and writes `branch.json` only after the clone and its
+ * lock are done.
+ */
+export declare function holdProvisionedWorkspace(contentBranchesPath: string, dirName: string): Promise<ProvisionedWorkspaceHold>;
+/** Release a hold, logging rather than throwing: the sync loop's callers never throw. */
+export declare function releaseProvisionedWorkspace(release: () => Promise<void>, dirName: string): Promise<void>;

package/dist/worker/provisioned-workspace.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { BRANCH_META_DIR, BRANCH_META_FILE } from '../branch-metadata-file.js';
+import { getErrorMessage, isNodeError } from '../utils/error.js';
+import { branchProvisioningLockName, tryAcquireProvisioningLock } from '../utils/provisioning-lock.js';
+import { workerLogWarn } from './log.js';
+/**
+ * Take a branch workspace's provisioning lock for the sync loop, the same cross-host lock the
+ * Lambda holds while it clones the workspace (`branch-workspace.ts`), so the worker never runs git
+ * against a half-made clone. The caller holds it across its dirty check and every git step, and
+ * releases it in a `finally`.
+ *
+ * Zero retries: the worker skips and retries next cycle rather than wait, so it never blocks on
+ * the Lambda and cannot deadlock with it. The rebase nests the content-write lock inside this one;
+ * the worker takes that one try-only as well, so the nesting cannot deadlock either.
+ *
+ * Provisioned means a `.git` directory AND `branch.json`. The Lambda clones directly into the
+ * target path, so `.git` appears early, and writes `branch.json` only after the clone and its
+ * lock are done.
+ */
+export async function holdProvisionedWorkspace(contentBranchesPath, dirName) {
+    let release;
+    let compromised = false;
+    try {
+        release = await tryAcquireProvisioningLock(contentBranchesPath, branchProvisioningLockName(dirName), (err) => {
+            compromised = true;
+            workerLogWarn(`  Provisioning lock for ${dirName} was compromised mid-hold: ${getErrorMessage(err)}`);
+        });
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ELOCKED')
+            return { kind: 'locked' };
+        throw err;
+    }
+    const root = path.join(contentBranchesPath, dirName);
+    const [gitIsDir, hasMetadata] = await Promise.all([
+        fs.stat(path.join(root, '.git')).then((stat) => stat.isDirectory(), () => false),
+        fs.stat(path.join(root, BRANCH_META_DIR, BRANCH_META_FILE)).then(() => true, () => false),
+    ]);
+    if (gitIsDir && hasMetadata)
+        return { kind: 'held', release, isCompromised: () => compromised };
+    await releaseProvisionedWorkspace(release, dirName);
+    return { kind: 'not-provisioned' };
+}
+/** Release a hold, logging rather than throwing: the sync loop's callers never throw. */
+export async function releaseProvisionedWorkspace(release, dirName) {
+    await release().catch((err) => {
+        workerLogWarn(`  Failed to release the provisioning lock for ${dirName}: ${getErrorMessage(err)}`);
+    });
+}

package/dist/worker/rebase.js

@@ -7,8 +7,10 @@ import { invalidateBranchContentCaches } from '../content-index-generation.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 { isRebaseInProgress } from '../utils/git.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';
 import { workerLog, workerLogWarn } from './log.js';
 /**
@@ -123,7 +125,7 @@ const MAX_REBASE_ROUNDS = 50;
  * - the **unexpected-error** exit aborts HERE, before breaking, so the caller's
  *   `!completed` abort is a caught no-op for that path;
  * - the **lock-compromised** exit leaves the rebase in progress and is aborted
- *   by `rebaseOneBranch`'s own `contentLockCompromised && !completed` branch,
+ *   by `rebaseOneBranch`'s own `lockCompromised() && !completed` branch,
  *   which returns `skippedLocked` before the `!completed` block below it is
  *   reached -- a distinct site that cannot be folded into that one;
  * - the **conflict-resolution-failure** and **MAX_REBASE_ROUNDS** exits are the
@@ -406,7 +408,7 @@ export async function runRebaseCycle(ctx) {
             workerLog(`  Skipping ${branchDir}: base branch (refreshed separately)`);
             continue;
         }
-        const outcome = await rebaseOneBranch(ctx, branchDir, branchPath);
+        const outcome = await holdAndRebaseOneBranch(ctx, branchDir, branchPath);
         if (outcome.kind === 'rebased')
             rebased.push(branchDir);
         else if (outcome.kind === 'skippedDirty')
@@ -423,6 +425,39 @@ export async function runRebaseCycle(ctx) {
     }
     return { rebased, skippedDirty, skippedLocked, failed };
 }
+/**
+ * {@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;
+ * one with no `branch.json` yet is skipped as not provisioned. Lock order: provisioning, then the
+ * 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) {
+    let hold;
+    try {
+        hold = await holdProvisionedWorkspace(ctx.contentBranchesPath, branchDir);
+    }
+    catch (err) {
+        // [REDACT] failed[] is served to the browser via worker-status.json.
+        const error = redactCredentials(`could not take the provisioning lock: ${getErrorMessage(err)}`);
+        workerLogWarn(`  Skipping ${branchDir}: ${error}`);
+        return { kind: 'failed', error };
+    }
+    if (hold.kind === 'locked') {
+        workerLog(`  Skipping ${branchDir}: provisioning lock held elsewhere (retrying next cycle)`);
+        return { kind: 'skippedLocked' };
+    }
+    if (hold.kind === 'not-provisioned') {
+        workerLog(`  Skipping ${branchDir}: not yet provisioned (no branch.json)`);
+        return { kind: 'none' };
+    }
+    try {
+        return await rebaseOneBranch(ctx, branchDir, branchPath, hold.isCompromised);
+    }
+    finally {
+        await releaseProvisionedWorkspace(hold.release, branchDir);
+    }
+}
 /**
  * Rebase ONE branch workspace onto the base branch, keeping the branch's
  * version of every conflicting file.
@@ -435,7 +470,7 @@ export async function runRebaseCycle(ctx) {
  * returned as `{ kind: 'failed' }`, so one unreadable branch cannot halt the
  * rest of the cycle ([SYNC-M2]).
  */
-async function rebaseOneBranch(ctx, branchDir, branchPath) {
+async function rebaseOneBranch(ctx, branchDir, branchPath, isProvisioningLockCompromised) {
     // Read only by the catch below. See the `rebased` rider on
     // BranchRebaseOutcome.
     let didRebase = false;
@@ -489,6 +524,9 @@ async function rebaseOneBranch(ctx, branchDir, branchPath) {
         // record it and bail before the next one rather than replaying over
         // an editor's concurrent save.
         let contentLockCompromised = false;
+        // Either lock lost means another writer may be live against this tree;
+        // both get the same bail-before-the-next-destructive-step treatment.
+        const lockCompromised = () => contentLockCompromised || isProvisioningLockCompromised();
         try {
             releaseContentLock = await tryAcquireContentWriteLock(branchPath, (lockErr) => {
                 contentLockCompromised = true;
@@ -574,12 +612,37 @@ async function rebaseOneBranch(ctx, branchDir, branchPath) {
             }
             // Skip dirty branches — the editor has changes that cannot be rebased.
             // Inside the lock, so no write can land between this check and the rebase
-            // below.
-            const dirtyCheck = await branchGit.status();
-            if (dirtyCheck.files.length > 0) {
+            // below. canopycms's own untracked state is not dirt.
+            let dirtyCheck = await branchGit.status();
+            if (await restoreRetiredSchemaCache(branchGit, dirtyCheck)) {
+                workerLog(`  ${branchDir}: restored the retired in-tree schema cache`);
+                dirtyCheck = await branchGit.status();
+            }
+            const editorDirt = dirtyCheck.files.filter((f) => !isCanopyInternalPath(f.path));
+            if (editorDirt.length > 0) {
                 workerLog(`  Skipping ${branchDir}: has uncommitted changes`);
                 return { kind: 'skippedDirty' };
             }
+            // `git rebase` refuses to start over ANY modified tracked file, so
+            // tracked canopycms state blocks. The worker never untracks it here:
+            // replaying a branch commit that touched it writes historical bytes over
+            // the live file, and the abort that follows deletes it. So the index and
+            // the bytes stay untouched, and the wedge is recorded for an operator.
+            const trackedState = trackedCanopyStateChanges(dirtyCheck);
+            if (trackedState.length > 0) {
+                await branchGit.fetch('origin', ctx.baseBranch);
+                const baseTip = (await branchGit.revparse(['FETCH_HEAD'])).trim();
+                const { stillTracked } = await splitByUpstreamTracking(branchGit, trackedState, baseTip);
+                const reason = stillTracked.length > 0
+                    ? `git cannot rebase over modified canopycms state the repo tracks ` +
+                        `(${trackedState.join(', ')}). To fix, ${TRACKED_CANOPY_STATE_FIX}.`
+                    : `git cannot rebase over modified canopycms state this clone still tracks ` +
+                        `(${trackedState.join(', ')}), though the base branch no longer does; ` +
+                        `the clone needs manual repair`;
+                workerLogWarn(`  Skipping ${branchDir}: ${reason}`);
+                await recordRebaseFailure(ctx, branchPath, branchDir, reason);
+                return { kind: 'failed', error: reason };
+            }
             // The clone's own ref name: branchDir is the sanitized DIRECTORY name and
             // need not match it. A literal 'HEAD' means a detached clone (a crashed
             // rebase can leave one), where nothing below can safely name a ref, so
@@ -651,7 +714,7 @@ async function rebaseOneBranch(ctx, branchDir, branchPath) {
             // the rebase makes unreadable.
             const preRebaseHead = (await branchGit.revparse(['HEAD'])).trim();
             const publishedSha = canPublish ? await readPublishedSha(ctx, branchRef) : null;
-            const { completed, conflictedFiles, failureReason } = await runRebaseRounds(ctx, branchGit, branchDir, fetchedBaseTip, () => contentLockCompromised);
+            const { completed, conflictedFiles, failureReason } = await runRebaseRounds(ctx, branchGit, branchDir, fetchedBaseTip, lockCompromised);
             // Outside the round loop's try/catch, so a throwing test hook can
             // never be misread as a rebase error.
             if (completed)
@@ -676,14 +739,14 @@ async function rebaseOneBranch(ctx, branchDir, branchPath) {
             // history while a concurrent save is uncommitted working-tree state, and
             // that writer is already told to retry via ContentWriteLockBusyError. So
             // when the rebase completed, log the lost exclusivity loudly and finish.
-            if (contentLockCompromised && !completed) {
-                workerLogWarn(`  Skipping ${branchDir}: content-write lock was compromised mid-rebase (retrying next cycle)`);
+            if (lockCompromised() && !completed) {
+                workerLogWarn(`  Skipping ${branchDir}: a lock it held was compromised mid-rebase (retrying next cycle)`);
                 // No-op when no rebase is in progress; failure is expected there.
                 await branchGit.rebase(['--abort']).catch(() => { });
                 return { kind: 'skippedLocked' };
             }
-            if (contentLockCompromised) {
-                workerLogWarn(`  Content-write lock for ${branchDir} was compromised, but its rebase had already completed -- finishing the sync (history is rewritten; skipping now would strand the history-rewrite marker and wedge the branch)`);
+            if (lockCompromised()) {
+                workerLogWarn(`  A lock held for ${branchDir} was compromised, but its rebase had already completed -- finishing the sync (history is rewritten; skipping now would strand the history-rewrite marker and wedge the branch)`);
             }
             if (!completed) {
                 // failureReason is only set on the "unexpected error" break above;