canopycms 0.0.67 → 0.0.68-int.100

package/dist/worker/git-sync.js

@@ -2,39 +2,31 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { simpleGit } from 'simple-git';
 import { BranchMetadataFileManager, getBranchMetadataFileManager } from '../branch-metadata.js';
+import { BRANCH_META_DIR, BRANCH_META_FILE } from '../branch-metadata-file.js';
+import { ORPHAN_YOUTH_THRESHOLD_MS } from '../branch-health.js';
+import { classifyFinalDir, parseDirStamp, quarantineResidueAt, sweepProvisioningLeftovers, } from '../branch-provisioning.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 { branchProvisioningLockName, tryAcquireProvisioningLock } from '../utils/provisioning-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';
+import { maintainRemoteGit } from './remote-git-maintenance.js';
+import { reapplySparseCones } from './sparse-cone.js';
 /**
  * [C1] Retention window for `.trash-*` branch directories left behind by the
  * admin purge action (api/admin-branch-health.ts). Matches
  * cleanupOldTasks's default task retention for consistency.
  */
 const TRASH_RETENTION_MS = 30 * 24 * 60 * 60_000;
-/** Matches `.trash-{dirName}-{STAMP}` names, capturing the trailing stamp. */
-const TRASH_DIR_STAMP_RE = /-(\d{8}T\d{6}Z)$/;
-/**
- * Parse a purge-generated `YYYYMMDDTHHMMSSZ` stamp into a Date, or null if
- * malformed. Age comes ONLY from this name-embedded stamp, never the dir's
- * own mtime -- `fs.rename` preserves the original directory's mtime, so an
- * mtime-based retention check would delete a months-stale orphan's trash on
- * the very first cleanup pass after purge.
- */
-function parseTrashStamp(stamp) {
-    const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(stamp);
-    if (!match)
-        return null;
-    const [, year, month, day, hour, minute, second] = match;
-    const date = new Date(`${year}-${month}-${day}T${hour}:${minute}:${second}.000Z`);
-    return Number.isNaN(date.getTime()) ? null : date;
-}
 /**
  * Push THIS deployment's own settings branch (`ensureSettingsBranch()`) from
  * remote.git to GitHub. Non-fatal: a no-op push for an up-to-date branch just
@@ -288,6 +280,27 @@ export async function syncGit(ctx) {
     // mask the real error on a failed one. Failures rethrow, so scheduleLoop's
     // per-cycle catch stays the loud path.
     try {
+        // Best-effort and ahead of the GitHub fetch, so a GitHub outage never
+        // stalls upkeep and a failure here never costs the cycle. start() runs a
+        // cycle at once, so residue repair also runs on boot.
+        try {
+            await repairBranchDirResidue(ctx);
+        }
+        catch (err) {
+            workerLogWarn(`Branch directory residue repair failed: ${getErrorMessage(err)}`);
+        }
+        try {
+            await reapplySparseCones(ctx);
+        }
+        catch (err) {
+            workerLogWarn(`Sparse-checkout cone update failed: ${getErrorMessage(err)}`);
+        }
+        try {
+            await maintainRemoteGit(ctx.remoteGitPath);
+        }
+        catch (err) {
+            workerLogWarn(`remote.git maintenance failed: ${getErrorMessage(err)}`);
+        }
         // Direct URL (no named remote), into the GITHUB_TRACKING_REF_PREFIX
         // remote-tracking namespace rather than refs/heads/* -- see that constant's
         // doc comment for the destructive-fetch bug this avoids. Raw git, because
@@ -306,7 +319,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 +336,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)));
@@ -343,13 +361,87 @@ export async function syncGit(ctx) {
         throw err;
     }
 }
+/** Foreign repositories already reported by this process, so each is logged once. */
+const reportedForeignDirs = new Set();
+/**
+ * Repair what killed provisioning and deletes left under the branches root: quarantine residue
+ * at a branch's name (branch-provisioning.ts's `classifyFinalDir`) once it has been quiet for
+ * {@link ORPHAN_YOUTH_THRESHOLD_MS}, then sweep stale `.prov-*`, `.deleting-*` and `.repair-*`
+ * siblings and settings leftovers. Each directory is best-effort, like [SYNC-M2]. The provisioning
+ * lock is taken zero-retry, so a live provisioner or admin action wins and the directory is
+ * revisited next cycle.
+ * @internal Exported for tests; `syncGit` runs it.
+ */
+export async function repairBranchDirResidue(ctx, now = Date.now()) {
+    let entries;
+    try {
+        entries = await fs.readdir(ctx.contentBranchesPath, { withFileTypes: true });
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        try {
+            await repairOneBranchDir(ctx, entry.name, now);
+        }
+        catch (err) {
+            workerLogWarn(`  Residue check of ${entry.name} failed: ${getErrorMessage(err)}`);
+        }
+    }
+    const leftovers = await sweepProvisioningLeftovers(ctx.contentBranchesPath, path.dirname(ctx.contentBranchesPath), now);
+    for (const { name, action, detail } of leftovers) {
+        const line = `  Leftover ${name}: ${action}${detail ? ` (${detail})` : ''}`;
+        if (action === 'removed')
+            workerLog(line);
+        else if (action === 'failed')
+            workerLogWarn(line);
+        else
+            workerLogError(line);
+    }
+}
+async function repairOneBranchDir(ctx, dirName, now) {
+    const dirPath = path.join(ctx.contentBranchesPath, dirName);
+    // One stat for the common case: a live (or corrupt) branch is never residue.
+    const hasMeta = await fs.access(path.join(dirPath, BRANCH_META_DIR, BRANCH_META_FILE)).then(() => true, () => false);
+    if (hasMeta)
+        return;
+    const state = await classifyFinalDir(dirPath, ctx.remoteGitPath);
+    if (state.kind === 'foreign' && !reportedForeignDirs.has(dirPath)) {
+        reportedForeignDirs.add(dirPath);
+        workerLogWarn(`  ${dirName} holds a git repository this deployment did not create; left for an admin`);
+    }
+    if (state.kind !== 'residue')
+        return;
+    let release;
+    try {
+        release = await tryAcquireProvisioningLock(ctx.contentBranchesPath, branchProvisioningLockName(dirName));
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ELOCKED')
+            return;
+        throw err;
+    }
+    try {
+        await quarantineResidueAt(ctx.contentBranchesPath, dirName, {
+            minQuietMs: ORPHAN_YOUTH_THRESHOLD_MS,
+            expectedRemoteUrl: ctx.remoteGitPath,
+            now,
+        });
+    }
+    finally {
+        await releaseProvisionedWorkspace(release, dirName);
+    }
+}
 /**
  * [C1] Remove `.trash-*` branch directories (created by the admin purge action,
- * api/admin-branch-health.ts) whose name-embedded stamp is older than
- * {@link TRASH_RETENTION_MS}. A name that doesn't match `.trash-{dirName}-
- * {STAMP}`, or whose stamp fails to parse, is left alone and logged once per
- * cycle: purge is the only writer of this naming scheme, so an unparseable name
- * is unexpected and worth a human looking rather than a silent skip.
+ * api/admin-branch-health.ts, and by residue quarantine, branch-provisioning.ts)
+ * whose name-embedded stamp is older than {@link TRASH_RETENTION_MS}. A name
+ * whose trailing stamp fails to parse is left alone and logged once per cycle:
+ * both writers end every name with one, so it is worth a human looking.
  */
 export async function cleanupTrashedBranchDirs(ctx) {
     let entries;
@@ -367,8 +459,7 @@ export async function cleanupTrashedBranchDirs(ctx) {
     for (const name of entries) {
         if (!name.startsWith('.trash-'))
             continue;
-        const stampMatch = TRASH_DIR_STAMP_RE.exec(name);
-        const stampDate = stampMatch ? parseTrashStamp(stampMatch[1]) : null;
+        const stampDate = parseDirStamp(name);
         if (!stampDate) {
             if (!loggedUnparseable) {
                 workerLog(`CanopyCMS: Skipping trash dir with unparseable stamp: ${name}`);
@@ -393,37 +484,76 @@ 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
+ * (content-branches/<baseBranch>) to match remote.git's <baseBranch>, every sync
  * cycle, so the drift window is bounded by gitSyncInterval.
  *
  * 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
+ * ff-only on purpose: this clone must stay a linear mirror of remote.git's
+ * <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,37 +567,80 @@ 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
+        // against remote.git's <baseBranch>, not filesystem paths, so they must use
         // the same name GitHub knows the branch by.
-        await baseGit.fetch('origin', ctx.baseBranch);
+        await baseGit.fetch(ctx.remoteGitPath, ctx.baseBranch);
         // rev-list, not status.behind, which needs an upstream tracking branch that
-        // is not guaranteed here. Against the just-fetched tip rather than
-        // origin/<base>: workspaces are cloned --single-branch (git-manager.ts), so
-        // for any other base branch origin/<base> never exists and rev-list dies
-        // with "ambiguous argument". Pin FETCH_HEAD to a SHA immediately -- it is
-        // one shared mutable file per repo, silently repointed by any other fetch.
+        // is not guaranteed here. Against the just-fetched tip: a fetch by path
+        // updates no remote-tracking ref. Pin FETCH_HEAD to a SHA immediately -- it
+        // is one shared mutable file per repo, silently repointed by any other fetch.
         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 +664,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/history-rewrite.d.ts

@@ -72,7 +72,7 @@ export declare function clearHistoryRewrittenMarker(ctx: Pick<HistoryRewriteCont
  * Returns whether the push landed. A refused lease means a concurrent Lambda
  * push moved the ref; logged and retried by the self-heal pass, never thrown.
  */
-export declare function forcePublishToLocalRemote(ctx: Pick<HistoryRewriteContext, 'taskTimeoutMs'>, branchPath: string, branchRef: string, expectedSha: string): Promise<boolean>;
+export declare function forcePublishToLocalRemote(ctx: Pick<HistoryRewriteContext, 'remoteGitPath' | 'taskTimeoutMs'>, branchPath: string, branchRef: string, expectedSha: string): Promise<boolean>;
 /**
  * Queue the GitHub hop for a branch whose rewritten history now sits in
  * `remote.git`, so an open PR's head follows the rebase within a cycle instead

package/dist/worker/history-rewrite.js

@@ -108,7 +108,7 @@ export async function forcePublishToLocalRemote(ctx, branchPath, branchRef, expe
             // Real flags must precede --end-of-options; everything after it is
             // positional (see GitManager.push() for the same guard).
             '--end-of-options',
-            'origin',
+            ctx.remoteGitPath,
             `${branchRef}:${branchRef}`,
         ]);
         workerLog(`  Published rebased ${branchRef} into remote.git`);

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 publishes the workspace (branch-provisioning.ts) and admin actions hold
+ * while they repair or purge it. 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`. A workspace is published complete with
+ * both ([PROV-1], branch-provisioning.ts), so anything else at a branch name is a leftover for
+ * `repairBranchDirResidue` (git-sync.ts).
+ */
+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 publishes the workspace (branch-provisioning.ts) and admin actions hold
+ * while they repair or purge it. 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`. A workspace is published complete with
+ * both ([PROV-1], branch-provisioning.ts), so anything else at a branch name is a leftover for
+ * `repairBranchDirResidue` (git-sync.ts).
+ */
+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