canopycms 0.0.67 → 0.0.68-int.94

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/cms-worker.js

@@ -8,7 +8,8 @@ import { isTransientAuthFailure, resolveWorkerGitHubAuth, } from './github-auth.
 import { 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 { writeWorkerStatus } from '../task-queue/worker-status.js';
+import { readLastFatalError, writeWorkerStatus } from '../task-queue/worker-status.js';
+import { CANOPYCMS_VERSION } from '../version.js';
 import { workerLog, workerLogWarn, workerLogError } from './log.js';
 import { executeTask, orphanRecoveryMaxAgeMs, processTaskQueue, pushBranchToGitHub, updateBranchMetadata, } from './task-runner.js';
 import { pollMergeState, runRebaseCycle } from './rebase.js';
@@ -67,7 +68,12 @@ export class CmsWorker {
     ensureStatusReport() {
         if (!this.statusReport) {
             const now = new Date().toISOString();
-            this.statusReport = { version: 1, startedAt: now, updatedAt: now };
+            this.statusReport = {
+                version: 1,
+                workerVersion: CANOPYCMS_VERSION,
+                startedAt: now,
+                updatedAt: now,
+            };
         }
         return this.statusReport;
     }
@@ -144,6 +150,21 @@ export class CmsWorker {
         workerLog('CMS Worker starting...');
         this.ensureStatusReport();
         await this.acquireLock();
+        // Replace the previous holder's status file now: the first sync can take
+        // minutes, and until then System health would report the old worker's
+        // version. Best-effort, like the startup-failure write below. The previous
+        // `lastFatalError` rides along in this snapshot only, so a crash loop keeps
+        // its alert between restarts while the first successful sync still clears it.
+        try {
+            const lastFatalError = await readLastFatalError(this.taskDir);
+            await writeWorkerStatus(this.taskDir, {
+                ...this.ensureStatusReport(),
+                ...(lastFatalError ? { lastFatalError } : {}),
+            });
+        }
+        catch (err) {
+            workerLogError('Failed to write worker status after acquiring the lock:', getErrorMessage(err));
+        }
         // Everything below runs while holding the cross-host worker lock. A failure
         // here (most notably the empty-remote guard inside ensureRemoteGit) means
         // the process is about to exit and systemd (Restart=always) will retry —

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,15 @@ 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.
+ *
+ * Holds the provisioning lock and then, like the rebase loop, the [SYNC-C1]
+ * content-write lock, both try-only: the base branch is writable in dev, and
+ * a save racing the merge's working-tree update can be overwritten by it.
  */
-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,18 @@ 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 { tryAcquireContentWriteLock } from '../utils/content-write-lock.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 +309,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 +326,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 +401,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,29 +415,62 @@ 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
  * history) is left untouched rather than force-resolved.
+ *
+ * Holds the provisioning lock and then, like the rebase loop, the [SYNC-C1]
+ * content-write lock, both try-only: the base branch is writable in dev, and
+ * a save racing the merge's working-tree update can be overwritten by it.
  */
 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;
+    let releaseContentLock;
     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;
+        let contentLockCompromised = false;
+        try {
+            releaseContentLock = await tryAcquireContentWriteLock(basePath, (lockErr) => {
+                contentLockCompromised = true;
+                workerLogWarn(`Base branch workspace (${ctx.baseBranch}): content-write lock compromised mid-refresh: ${getErrorMessage(lockErr)}`);
+            });
+        }
+        catch (lockErr) {
+            if (isNodeError(lockErr) && lockErr.code === 'ELOCKED') {
+                workerLog(`Base branch workspace (${ctx.baseBranch}): content write in progress, skipping refresh`);
+                return { outcome: 'skipped-locked' };
+            }
+            throw lockErr;
+        }
+        // Checked before each destructive step: a lost provisioning lock means
+        // another process may be cloning into this directory, a lost content lock
+        // that an editor save may be landing in it.
+        const lockLost = () => {
+            if (!hold.isCompromised() && !contentLockCompromised)
+                return null;
+            const lost = hold.isCompromised() ? 'provisioning' : 'content-write';
+            workerLogWarn(`Base branch workspace (${ctx.baseBranch}): ${lost} 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 +484,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 +535,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 +583,30 @@ 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 (releaseContentLock) {
+            await releaseContentLock().catch((err) => {
+                workerLogWarn(`Base branch workspace (${ctx.baseBranch}): failed to release content-write lock: ${getErrorMessage(err)}`);
+            });
+        }
+        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.d.ts

@@ -20,7 +20,7 @@ import type { WorkerContext } from './worker-context.js';
  * but still need their PR's resolution polled, and this loop is the only thing
  * that walks every branch workspace.
  */
-export type RebaseContext = Pick<WorkerContext, 'githubOwner' | 'githubRepo' | 'baseBranch' | 'sanitizedBaseBranch' | 'contentBranchesPath' | 'contentRoot' | 'remoteGitPath' | 'taskDir' | 'taskTimeoutMs' | 'octokit' | 'afterConflictDetectedForTesting' | 'afterRebaseCompletedForTesting'>;
+export type RebaseContext = Pick<WorkerContext, 'githubOwner' | 'githubRepo' | 'baseBranch' | 'sanitizedBaseBranch' | 'contentBranchesPath' | 'contentRoot' | 'remoteGitPath' | 'taskDir' | 'taskTimeoutMs' | 'octokit' | 'afterConflictDetectedForTesting' | 'afterRebaseCompletedForTesting' | 'ensureSettingsBranch'>;
 /**
  * Per-cycle outcome of `rebaseActiveBranches()`, folded by `syncGit()` into the
  * worker's self-reported status (`WorkerStatusReport.lastGitSync`, see