canopycms 0.0.67 → 0.0.68-int.101

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

package/dist/worker/rebase.js

@@ -4,11 +4,14 @@ import { simpleGit } from 'simple-git';
 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 { 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 +126,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
@@ -159,8 +162,8 @@ async function runRebaseRounds(ctx, branchGit, branchDir, fetchedBaseTip, isLock
             break;
         try {
             if (nextAction === 'start') {
-                // The pinned base tip fetched above (single-branch clones have
-                // no origin/<base> remote-tracking ref for other branches).
+                // The pinned base tip fetched above; a fetch by path updates no
+                // remote-tracking ref.
                 await branchGit.rebase([fetchedBaseTip]);
             }
             else if (nextAction === 'continue') {
@@ -196,20 +199,23 @@ async function runRebaseRounds(ctx, branchGit, branchDir, fetchedBaseTip, isLock
                 //
                 // A per-file resolution that STILL fails routes into the `!completed`
                 // path below, which aborts and records, rather than escaping.
+                //
+                // `--sparse` on add/rm: a conflicted path outside a sparse clone's cone
+                // is materialised for the conflict, but git refuses to stage it without.
                 const conflictKind = new Map(st.files.map((f) => [f.path, `${f.index}${f.working_dir}`]));
                 let resolutionFailure;
                 for (const file of st.conflicted) {
                     const kind = conflictKind.get(file);
                     try {
                         if (kind === 'UD') {
-                            await branchGit.raw(['rm', '-f', '--', file]);
+                            await branchGit.raw(['rm', '-f', '--sparse', '--', file]);
                         }
                         else if (kind === 'DU') {
-                            await branchGit.add(file);
+                            await branchGit.raw(['add', '--sparse', '--', file]);
                         }
                         else {
                             await branchGit.raw(['checkout', '--theirs', file]);
-                            await branchGit.add(file);
+                            await branchGit.raw(['add', '--sparse', '--', file]);
                         }
                     }
                     catch (resolveErr) {
@@ -406,7 +412,14 @@ export async function runRebaseCycle(ctx) {
             workerLog(`  Skipping ${branchDir}: base branch (refreshed separately)`);
             continue;
         }
-        const outcome = await rebaseOneBranch(ctx, branchDir, branchPath);
+        // A settings branch is an orphan: rebasing it onto the base would give it content
+        // history. The API refuses to provision one, so a directory under that name is a
+        // leftover and is left alone.
+        if (isSettingsBranchName(branchDir, ctx.ensureSettingsBranch())) {
+            workerLogWarn(`  Skipping ${branchDir}: settings branch, never a content workspace`);
+            continue;
+        }
+        const outcome = await holdAndRebaseOneBranch(ctx, branchDir, branchPath);
         if (outcome.kind === 'rebased')
             rebased.push(branchDir);
         else if (outcome.kind === 'skippedDirty')
@@ -423,6 +436,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` is skipped. 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' };
+    }
+    // Silent: a directory without branch.json is a staging-era leftover, which
+    // repairBranchDirResidue (git-sync.ts) quarantines and logs at the cycle's start.
+    if (hold.kind === 'not-provisioned')
+        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 +481,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 +535,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 +623,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(ctx.remoteGitPath, 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
@@ -601,14 +675,12 @@ async function rebaseOneBranch(ctx, branchDir, branchPath) {
                     marker: metaFile.branch.historyRewrittenFrom,
                 });
             }
-            await branchGit.fetch('origin', ctx.baseBranch);
+            await branchGit.fetch(ctx.remoteGitPath, ctx.baseBranch);
             // rev-list, not status.behind, which needs an upstream tracking branch
             // that checkoutBranch's fallback paths do not always configure. Against
-            // the just-fetched tip, not origin/<base>: branch clones are
-            // --single-branch, so no remote-tracking ref exists for any base branch
-            // other than the one they were cloned from. Pinned to a SHA immediately
-            // — FETCH_HEAD is one shared mutable file per repo, repointed by any
-            // concurrent fetch.
+            // the just-fetched tip: a fetch by path updates no remote-tracking ref.
+            // Pinned to a SHA immediately — FETCH_HEAD is one shared mutable file per
+            // repo, repointed by any concurrent fetch.
             const fetchedBaseTip = (await branchGit.revparse(['FETCH_HEAD'])).trim();
             const behindCount = parseInt((await branchGit.raw(['rev-list', '--count', `HEAD..${fetchedBaseTip}`])).trim(), 10);
             const meta = getBranchMetadataFileManager(branchPath, ctx.contentBranchesPath);
@@ -651,7 +723,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 +748,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;

package/dist/worker/remote-git-maintenance.d.ts

@@ -0,0 +1,3 @@
+import { type BareRemoteRepackResult } from '../git-manager.js';
+/** The worker's per-cycle repack of `remote.git` (git-manager.ts owns the rule), logged. */
+export declare function maintainRemoteGit(gitDir: string): Promise<BareRemoteRepackResult>;

package/dist/worker/remote-git-maintenance.js

@@ -0,0 +1,11 @@
+import { repackBareRemoteIfNeeded } from '../git-manager.js';
+import { workerLog } from './log.js';
+/** The worker's per-cycle repack of `remote.git` (git-manager.ts owns the rule), logged. */
+export async function maintainRemoteGit(gitDir) {
+    const result = await repackBareRemoteIfNeeded(gitDir);
+    if (result.repacked) {
+        workerLog(`remote.git maintenance: loose ${result.before.loose}→${result.after.loose} ` +
+            `packs ${result.before.packs}→${result.after.packs} in ${result.ms} ms`);
+    }
+    return result;
+}

package/dist/worker/sparse-cone.d.ts

@@ -0,0 +1,20 @@
+export interface SparseConeReport {
+    reapplied: string[];
+    failed: {
+        branch: string;
+        error: string;
+    }[];
+}
+/**
+ * Move each provisioned sparse clone to the cone the deployment's config now asks for, as
+ * recorded beside the branch directories by the Lambda (branch-sparse.ts): a changed content
+ * root would otherwise leave every existing clone without its content. A full clone stays
+ * full. Best-effort per clone, like [SYNC-M2].
+ *
+ * The cone is compared without a lock, and changed only under the clone's provisioning lock
+ * and content-write lock, both zero-retry, outside a rebase: `sparse-checkout set` rewrites the
+ * working tree. A clone that is busy, or holds an unpublished deletion, is retried next cycle.
+ */
+export declare function reapplySparseCones(ctx: {
+    contentBranchesPath: string;
+}): Promise<SparseConeReport>;

package/dist/worker/sparse-cone.js

@@ -0,0 +1,132 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { simpleGit } from 'simple-git';
+import { readRecordedSparseCone, sameCone } from '../branch-sparse.js';
+import { invalidateBranchContentCaches } from '../content-index-generation.js';
+import { tryAcquireContentWriteLock } from '../utils/content-write-lock.js';
+import { getErrorMessage, isNodeError } from '../utils/error.js';
+import { isRebaseInProgress } from '../utils/git.js';
+import { workerLog, workerLogWarn } from './log.js';
+import { holdProvisionedWorkspace, releaseProvisionedWorkspace } from './provisioned-workspace.js';
+/** A clone's cone directories, or null when it is not sparse (or cannot be read). */
+async function currentCone(git) {
+    try {
+        const listed = (await git.raw(['sparse-checkout', 'list'])).trim();
+        return listed ? listed.split('\n') : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Move each provisioned sparse clone to the cone the deployment's config now asks for, as
+ * recorded beside the branch directories by the Lambda (branch-sparse.ts): a changed content
+ * root would otherwise leave every existing clone without its content. A full clone stays
+ * full. Best-effort per clone, like [SYNC-M2].
+ *
+ * The cone is compared without a lock, and changed only under the clone's provisioning lock
+ * and content-write lock, both zero-retry, outside a rebase: `sparse-checkout set` rewrites the
+ * working tree. A clone that is busy, or holds an unpublished deletion, is retried next cycle.
+ */
+export async function reapplySparseCones(ctx) {
+    const report = { reapplied: [], failed: [] };
+    const recorded = await readRecordedSparseCone(ctx.contentBranchesPath);
+    if (!recorded)
+        return report;
+    let entries;
+    try {
+        entries = await fs.readdir(ctx.contentBranchesPath, { withFileTypes: true });
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return report;
+        throw err;
+    }
+    const dirNames = entries
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+        .map((entry) => entry.name)
+        .sort();
+    for (const dirName of dirNames) {
+        const branchPath = path.join(ctx.contentBranchesPath, dirName);
+        // Without its own .git, git would answer for a repository above the branches root.
+        const isClone = await fs.stat(path.join(branchPath, '.git')).then((stat) => stat.isDirectory(), () => false);
+        if (!isClone)
+            continue;
+        const git = simpleGit({ baseDir: branchPath });
+        const cone = await currentCone(git);
+        if (cone === null || sameCone(cone, recorded.cone))
+            continue;
+        try {
+            const outcome = await reapplyOne(ctx.contentBranchesPath, dirName, git, recorded.cone);
+            if (outcome === 'applied') {
+                workerLog(`  ${dirName}: sparse-checkout cone ${[...cone].sort().join(',')} -> ` +
+                    (recorded.cone ? [...recorded.cone].sort().join(',') : 'full checkout'));
+                report.reapplied.push(dirName);
+            }
+            else if (typeof outcome === 'number') {
+                workerLog(`  ${dirName}: sparse-checkout cone waits for ${outcome} unpublished ` +
+                    `deletion${outcome === 1 ? '' : 's'} to be published`);
+            }
+        }
+        catch (err) {
+            const error = getErrorMessage(err);
+            workerLogWarn(`  ${dirName}: could not change the sparse-checkout cone: ${error}`);
+            report.failed.push({ branch: dirName, error });
+        }
+    }
+    return report;
+}
+/**
+ * Apply `target` under both locks: `'applied'`, `'skipped'` when the clone is busy or no longer
+ * differs, or the count of its unpublished deletions, which hold the cone where it is.
+ */
+async function reapplyOne(contentBranchesPath, dirName, git, target) {
+    const branchPath = path.join(contentBranchesPath, dirName);
+    const hold = await holdProvisionedWorkspace(contentBranchesPath, dirName);
+    if (hold.kind !== 'held')
+        return 'skipped';
+    try {
+        let releaseContent;
+        let contentLost = false;
+        try {
+            releaseContent = await tryAcquireContentWriteLock(branchPath, () => {
+                contentLost = true;
+            });
+        }
+        catch (err) {
+            if (isNodeError(err) && err.code === 'ELOCKED')
+                return 'skipped';
+            throw err;
+        }
+        try {
+            if (await isRebaseInProgress(branchPath))
+                return 'skipped';
+            const cone = await currentCone(git);
+            if (cone === null || sameCone(cone, target))
+                return 'skipped';
+            // A tracked file missing from the working tree is the one edit a cone change loses: leaving
+            // the cone marks it skip-worktree, so the deletion drops out of `status` and `add -A`, and a
+            // wider cone checks the file out again. Modified, untracked and staged changes all survive.
+            const deleted = (await git.raw(['ls-files', '--deleted', '-z'])).split('\0').filter(Boolean);
+            if (deleted.length > 0)
+                return deleted.length;
+            if (hold.isCompromised() || contentLost)
+                return 'skipped';
+            try {
+                await git.raw(target
+                    ? ['sparse-checkout', 'set', '--cone', '--', ...target]
+                    : ['sparse-checkout', 'disable']);
+            }
+            finally {
+                await invalidateBranchContentCaches(branchPath);
+            }
+            return 'applied';
+        }
+        finally {
+            await releaseContent().catch(() => { });
+        }
+    }
+    finally {
+        await releaseProvisionedWorkspace(hold.release, dirName);
+    }
+}