canopycms 0.0.67 → 0.0.68-int.101

package/dist/git-manager.js

@@ -19,8 +19,9 @@ import { simpleGit, } from 'simple-git';
 import { invalidateContentIndexesForRoot } from './content-index-registry.js';
 import { invalidateBranchContentCaches } from './content-index-generation.js';
 import { createDebugLogger } from './utils/debug.js';
-import { getErrorMessage, isNotFoundError } from './utils/error.js';
-import { isMissingRemoteRefFailure, isNetworkRemoteUrl, resolveBaseBranch } from './utils/git.js';
+import { getErrorMessage, isNodeError, isNotFoundError, redactCredentials } from './utils/error.js';
+import { isMissingRemoteRefFailure, isNetworkRemoteUrl, resolveBaseBranch, stageAllExceptCanopyState, } from './utils/git.js';
+import { canopyLogWarn } from './utils/logger.js';
 import { acquireProvisioningLock } from './utils/provisioning-lock.js';
 const log = createDebugLogger({ prefix: 'GitManager' });
 /**
@@ -88,6 +89,134 @@ export function gitNetworkChildEnv() {
     }
     return { ...env, ...FORCE_C_LOCALE };
 }
+/**
+ * `-c` on every git process a GitManager starts, so gc and auto-maintenance
+ * never run inside a Lambda, which can be frozen mid-run with a half-written
+ * pack or a `gc.pid` left on EFS. A provisioning clone also persists them
+ * into the workspace's own config. `remote.git`'s `receive-pack` never sees
+ * them; {@link REMOTE_GIT_CONFIG} covers that side.
+ */
+const NO_AUTO_GC_CONFIG = ['gc.auto=0', 'maintenance.auto=false'];
+/**
+ * Settings written into every bare `remote.git` CanopyCMS creates: the worker's (prod) and the
+ * simulated remote (dev). A push runs `receive-pack` with remote.git's own config and none of the
+ * pusher's: git unsets `GIT_CONFIG_PARAMETERS` before spawning it for a local-path push. Unset, a
+ * push starts auto-housekeeping there (detached, or inside a Lambda that is frozen mid-run) that
+ * repacks while another process clones, and pushes under the default `unpackLimit` (100) leave
+ * loose objects that every local clone copies one NFS round trip at a time.
+ *
+ * Never an `extensions.*` key: once a repo is at `repositoryformatversion` 1, a git that does not
+ * know the key refuses it, and Lambda runs git 2.39.
+ * @internal Exported for tests.
+ */
+export const REMOTE_GIT_CONFIG = [
+    ['gc.auto', '0'],
+    ['receive.autogc', 'false'],
+    ['maintenance.auto', 'false'],
+    ['transfer.unpackLimit', '1'],
+];
+/** Write each of {@link REMOTE_GIT_CONFIG} into the bare repo `gitDir` only where it differs. */
+export async function ensureRemoteGitConfig(gitDir) {
+    const git = simpleGit().env(gitChildEnv({}));
+    const current = new Map();
+    const listed = await git.raw(['--git-dir', gitDir, 'config', '--local', '--list']);
+    for (const line of listed.split('\n')) {
+        const eq = line.indexOf('=');
+        if (eq > 0)
+            current.set(line.slice(0, eq).toLowerCase(), line.slice(eq + 1));
+    }
+    for (const [key, value] of REMOTE_GIT_CONFIG) {
+        if (current.get(key.toLowerCase()) === value)
+            continue;
+        await git.raw(['--git-dir', gitDir, 'config', '--local', key, value]);
+    }
+}
+/** Above either count, {@link repackBareRemoteIfNeeded} repacks. */
+const REMOTE_GIT_MAX_LOOSE_OBJECTS = 50;
+const REMOTE_GIT_MAX_PACKS = 6;
+async function countObjects(git, gitDir) {
+    const output = await git.raw(['--git-dir', gitDir, 'count-objects', '-v']);
+    const fields = new Map(output.split('\n').map((line) => {
+        const [name, value = ''] = line.split(': ');
+        return [name, value.trim()];
+    }));
+    const field = (name) => {
+        const value = fields.get(name);
+        if (!value || !/^\d+$/.test(value)) {
+            throw new Error(`count-objects -v printed no '${name}' count: ${output.trim()}`);
+        }
+        return Number(value);
+    };
+    return { loose: field('count'), packs: field('packs') };
+}
+/**
+ * Repack the bare repo `gitDir` once it holds more than {@link REMOTE_GIT_MAX_LOOSE_OBJECTS}
+ * loose objects or {@link REMOTE_GIT_MAX_PACKS} packs, then pack its refs. Under
+ * {@link REMOTE_GIT_CONFIG} every push adds a pack, and nothing else ever compacts them.
+ *
+ * Safe beside concurrent pushes and clones, which is why it is `--cruft` with no expiry:
+ * unreachable objects move into a cruft pack rather than being dropped, so a push that read an
+ * old object before the repack still finds it, and a repack only deletes packs it listed when it
+ * began. A clone that hardlinked a pack keeps that inode when the repack unlinks the remote's
+ * name for it, and packs are never modified in place. `repack -d` also removes the loose objects
+ * it packed and their emptied fan-out directories.
+ */
+export async function repackBareRemoteIfNeeded(gitDir) {
+    const git = simpleGit().env(gitChildEnv({}));
+    const before = await countObjects(git, gitDir);
+    if (before.loose <= REMOTE_GIT_MAX_LOOSE_OBJECTS && before.packs <= REMOTE_GIT_MAX_PACKS) {
+        return { repacked: false, before };
+    }
+    const startedAt = Date.now();
+    await git.raw(['--git-dir', gitDir, 'repack', '-a', '-d', '--cruft', '-q']);
+    await git.raw(['--git-dir', gitDir, 'pack-refs', '--all']);
+    const after = await countObjects(git, gitDir);
+    return { repacked: true, before, after, ms: Date.now() - startedAt };
+}
+/**
+ * simple-git reads a git that exited by signal (exit code null, often with no stderr) as success,
+ * so a clone or checkout the OOM killer stopped would pass for complete. Given as `errors` to a
+ * GitManager's own instance and to `cloneRepo`'s; its static helpers and the bare-remote functions
+ * do not pass it yet (.claude/future-tasks/simple-git-signal-exit-reads-as-success.md).
+ */
+function failOnSignalExit(error, result) {
+    if (error)
+        return error;
+    if (result.exitCode === null) {
+        return new Error('git was killed by a signal before it finished');
+    }
+    return undefined;
+}
+/** EFS cost is per-file latency, which parallel file creation overlaps. git >= 2.32. */
+const PARALLEL_CHECKOUT_ARGS = [
+    '-c',
+    'checkout.workers=8',
+    '-c',
+    'checkout.thresholdForParallelism=1',
+];
+async function dirState(dir) {
+    try {
+        return (await fs.readdir(dir)).length === 0 ? 'empty' : 'occupied';
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT')
+            return 'absent';
+        throw err;
+    }
+}
+/**
+ * Config every workspace clone writes into its own `.git/config`: the managed
+ * marker that ensureRemote's guard checks, and a fallback author for internal
+ * commits such as the orphan settings init (ensureAuthor() sets the real one
+ * before user-facing commits).
+ */
+export function managedWorkspaceConfig(gitBotAuthorName, gitBotAuthorEmail) {
+    return {
+        'canopycms.managed': 'true',
+        'user.name': gitBotAuthorName,
+        'user.email': gitBotAuthorEmail,
+    };
+}
 // In-memory lock to prevent concurrent remote.git initialization
 const remoteInitLocks = new Map();
 /**
@@ -166,13 +295,90 @@ export class GitRemoteRefMissingError extends Error {
         this.name = 'GitRemoteRefMissingError';
     }
 }
+/**
+ * No git remote is configured and the one the strategy auto-detects does not
+ * exist yet: in prod, the EC2 worker creates `{workspaceRoot}/remote.git` on
+ * its first boot, so until then every request that needs a workspace fails
+ * here. Usually transient, unlike a missing remote in a mode with nothing to wait for.
+ * The HTTP layer maps it to a 503 (`http/worker-not-ready.ts`).
+ */
+export class RemoteNotReadyError extends Error {
+    constructor(expectedRemotePath) {
+        super(`CanopyCMS: no git remote is available yet. defaultRemoteUrl (or CANOPYCMS_REMOTE_URL) is ` +
+            `not set and the CMS worker has not created ${expectedRemotePath}; the worker may still be starting.`);
+        this.expectedRemotePath = expectedRemotePath;
+        this.name = 'RemoteNotReadyError';
+    }
+}
+/**
+ * Settings provisioning could not read the remote's settings branch, so it cannot tell a remote
+ * that has none from one it failed to reach. It stops instead of starting an empty settings
+ * branch: settings that silently vanish drop restrictive path rules, so content they hid
+ * becomes readable under `defaultPathAccess: { read: 'allow' }`.
+ */
+class SettingsRemoteUnreadableError extends Error {
+    constructor(branch, remote, 
+    /** The underlying git failure; see {@link GitRemoteRefMissingError.gitError}. */
+    gitError) {
+        super(`CanopyCMS: could not read settings branch '${branch}' from remote '${remote}', so ` +
+            `the settings workspace was not provisioned: ${getErrorMessage(gitError)}`);
+        this.branch = branch;
+        this.remote = remote;
+        this.gitError = gitError;
+        this.name = 'SettingsRemoteUnreadableError';
+    }
+}
+/**
+ * The workspace's settings branch shares no history with the remote's and holds work of its
+ * own, so neither copy can be chosen automatically, and a settings save could never pull.
+ */
+class SettingsBranchDivergedError extends Error {
+    constructor(branch, workspacePath, 
+    /** What the workspace holds beyond an empty initial commit. */
+    localWork) {
+        super(`CanopyCMS: settings branch '${branch}' in ${workspacePath} shares no history with the ` +
+            `remote's '${branch}', and holds ${localWork}. Settings saves cannot pull until one copy ` +
+            `is chosen. To keep the remote's settings: copy anything you need out of ` +
+            `${workspacePath}, move it aside, and restart; the next start checks out the remote's ` +
+            `'${branch}', and copied changes can then be re-applied in the editor.`);
+        this.branch = branch;
+        this.workspacePath = workspacePath;
+        this.localWork = localWork;
+        this.name = 'SettingsBranchDivergedError';
+    }
+}
+/** The only files a settings branch ever commits (explicit paths at its root). */
+const SETTINGS_BRANCH_FILES = new Set(['permissions.json', 'groups.json']);
+/**
+ * The remote's settings branch holds content rather than settings. Adopting it would load no
+ * groups or path rules, and settings saves would then commit onto content history.
+ */
+class SettingsBranchHasContentHistoryError extends Error {
+    constructor(branch, remote, 
+    /** What shows it is content. */
+    evidence) {
+        super(`CanopyCMS: the settings branch '${branch}' on remote '${remote}' holds content, not ` +
+            `settings (${evidence}), so it was not checked out. Restore '${branch}' on the remote ` +
+            `from a copy of the settings (it may hold only permissions.json and groups.json), ` +
+            `then restart.`);
+        this.branch = branch;
+        this.remote = remote;
+        this.evidence = evidence;
+        this.name = 'SettingsBranchHasContentHistoryError';
+    }
+}
 export class GitManager {
     constructor(options, gitOptions) {
         this.repoPath = path.resolve(options.repoPath);
         this.baseBranch = options.baseBranch ?? 'main';
         this.remote = options.remote ?? 'origin';
         this.skipIndexMarker = options.skipIndexMarker ?? false;
-        this.git = simpleGit({ baseDir: this.repoPath, ...gitOptions });
+        this.git = simpleGit({
+            baseDir: this.repoPath,
+            errors: failOnSignalExit,
+            ...gitOptions,
+            config: [...NO_AUTO_GC_CONFIG, ...(gitOptions?.config ?? [])],
+        });
         // `this.git` is for LOCAL working-tree ops: in the intended prod topology
         // `origin` resolves to a local path (an auto-detected/initialized
         // `remote.git`), so its env is gitChildEnv's allowlist, which drops
@@ -187,14 +393,47 @@ export class GitManager {
         // operate on the host repo above.
         this.git.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path.dirname(this.repoPath) }));
     }
-    static async cloneRepo(remoteUrl, targetPath, baseBranch = 'main') {
+    /**
+     * Single-branch clone of `baseBranch`, retried once: a clone can lose a race
+     * with the worker's repack of `remote.git` deleting a pack it had just
+     * listed. Before the retry it clears only what it created itself, so a
+     * target that held files beforehand is never touched.
+     */
+    static async cloneRepo(remoteUrl, targetPath, baseBranch = 'main', options = {}) {
         log.debug('git', 'Cloning repository', {
             remoteUrl,
             targetPath,
             baseBranch,
         });
-        const git = simpleGit();
-        await git.clone(remoteUrl, targetPath, ['--branch', baseBranch, '--single-branch']);
+        const args = ['--single-branch', '--branch', baseBranch];
+        if (options.noCheckout)
+            args.push('--no-checkout');
+        if (options.remoteName)
+            args.push('--origin', options.remoteName);
+        for (const [key, value] of Object.entries(options.config ?? {})) {
+            args.push('-c', `${key}=${value}`);
+        }
+        for (const setting of NO_AUTO_GC_CONFIG)
+            args.push('-c', setting);
+        const git = simpleGit({ config: [...NO_AUTO_GC_CONFIG], errors: failOnSignalExit });
+        git.env({
+            ...(isNetworkRemoteUrl(remoteUrl) ? gitNetworkChildEnv() : gitChildEnv({})),
+            GIT_CEILING_DIRECTORIES: path.dirname(targetPath),
+        });
+        const before = await dirState(targetPath);
+        try {
+            await git.clone(remoteUrl, targetPath, args);
+        }
+        catch (err) {
+            if (before === 'occupied')
+                throw err;
+            canopyLogWarn(`[canopy] clone into ${targetPath} failed, retrying once: ` +
+                redactCredentials(getErrorMessage(err)));
+            await fs.rm(targetPath, { recursive: true, force: true });
+            if (before === 'empty')
+                await fs.mkdir(targetPath);
+            await git.clone(remoteUrl, targetPath, args);
+        }
         log.debug('git', 'Clone complete');
     }
     /**
@@ -243,9 +482,24 @@ export class GitManager {
                     if (!isNotFoundError(err))
                         throw err;
                 }
+                if (remoteExists) {
+                    // The worker's per-cycle repack never runs in dev; once per call keeps pushes from
+                    // piling up packs. Best-effort: a remote it cannot compact still serves.
+                    try {
+                        const repack = await repackBareRemoteIfNeeded(options.remotePath);
+                        if (repack.repacked)
+                            log.debug('git', 'Repacked local simulated remote', repack);
+                    }
+                    catch (err) {
+                        log.debug('git', 'Could not repack local simulated remote', {
+                            error: getErrorMessage(err),
+                        });
+                    }
+                }
                 if (remoteExists &&
                     (await GitManager.bareRemoteHasBranch(options.remotePath, options.baseBranch))) {
                     log.debug('git', 'Remote already has base branch, skipping');
+                    await ensureRemoteGitConfig(options.remotePath);
                     return;
                 }
                 // Find the actual git root directory — the subdirectory snapshot path
@@ -303,6 +557,7 @@ export class GitManager {
                         options.remotePath,
                     ]);
                 }
+                await ensureRemoteGitConfig(options.remotePath);
                 // Push baseBranch to remote (not current HEAD)
                 await GitManager.pushBranchToLocalRemote({
                     sourceGit,
@@ -407,7 +662,7 @@ export class GitManager {
      * deleteBranchHandler: a head left in `remote.git` forever makes the
      * create -> publish -> squash-merge -> delete -> reuse-the-name cycle reject
      * the reused branch's first publish non-fast-forward against the stale head
-     * (`GitManager.push()` pushes `branch:branch`, and a squash-merged old tip is
+     * (`GitManager.push()` pushes the branch to the same name, and a squash-merged old tip is
      * not an ancestor of the new branch), and a retried submit then skips the
      * local push on a clean tree and enqueues the worker push of the STALE head,
      * resurrecting the deleted branch's content on GitHub as an apparent success.
@@ -562,6 +817,12 @@ export class GitManager {
             `intentionally runs git against a network remote (e.g. a single-VM deployment), set ` +
             `config.allowNetworkRemoteInProd: true to acknowledge this.`);
     }
+    /** The not-ready error for a mode whose remote is auto-detected, or `undefined` for other modes. */
+    static async remoteNotReadyError(mode) {
+        const { operatingStrategy } = await import('./operating-mode/index.js');
+        const { autoDetectRemotePath } = operatingStrategy(mode).getRemoteUrlConfig();
+        return autoDetectRemotePath ? new RemoteNotReadyError(autoDetectRemotePath) : undefined;
+    }
     /**
      * Resolves the remote URL for git operations following the priority:
      * 1. Explicit remoteUrl parameter
@@ -627,6 +888,33 @@ export class GitManager {
         }
         return undefined;
     }
+    /**
+     * {@link resolveRemoteUrl} for a workspace about to be cloned, which needs a
+     * remote: none resolving is the worker-not-ready error in a mode whose
+     * remote the worker creates, and a configuration error otherwise.
+     */
+    static async resolveCloneRemoteUrl(options) {
+        const remoteUrl = await GitManager.resolveRemoteUrl(options);
+        if (remoteUrl)
+            return remoteUrl;
+        const notReady = await GitManager.remoteNotReadyError(options.mode);
+        if (notReady)
+            throw notReady;
+        throw new Error('CanopyCMS: defaultRemoteUrl (or CANOPYCMS_REMOTE_URL) is required to initialize workspace');
+    }
+    /**
+     * {@link cloneRepo} for a workspace, failing with one message that names the
+     * workspace, the remote and the base branch, which git's own error mixes.
+     */
+    static async cloneWorkspace(remoteUrl, workspacePath, baseBranch, options) {
+        try {
+            await GitManager.cloneRepo(remoteUrl, workspacePath, baseBranch, options);
+        }
+        catch (err) {
+            throw new Error(`Failed to clone branch workspace at ${workspacePath} ` +
+                `from ${remoteUrl} (base branch '${baseBranch}'): ${getErrorMessage(err)}`);
+        }
+    }
     /**
      * Check whether a git repository is already initialized at `workspacePath`.
      *
@@ -685,9 +973,12 @@ export class GitManager {
                     throw cleanupErr;
             }
         }
+        const step = (name, run) => options.provisionLog ? options.provisionLog.step(name, run) : run();
+        const identity = managedWorkspaceConfig(options.gitBotAuthorName, options.gitBotAuthorEmail);
         let justCloned = false;
+        let resolvedRemoteUrl;
         if (!repoExists) {
-            const remoteUrl = await GitManager.resolveRemoteUrl({
+            const remoteUrl = await GitManager.resolveCloneRemoteUrl({
                 mode: options.mode,
                 remoteUrl: options.remoteUrl,
                 defaultRemoteUrl: options.defaultRemoteUrl,
@@ -695,28 +986,15 @@ export class GitManager {
                 sourceRoot: options.sourceRoot,
                 allowNetworkRemoteInProd: options.allowNetworkRemoteInProd,
             });
-            if (!remoteUrl) {
-                throw new Error('CanopyCMS: defaultRemoteUrl (or CANOPYCMS_REMOTE_URL) is required to initialize workspace');
-            }
-            try {
-                await GitManager.cloneRepo(remoteUrl, options.workspacePath, baseBranch);
-            }
-            catch (err) {
-                // The raw git error ("Cloning into <workspace>… branch <base> not found")
-                // mixes the workspace name and the base branch — spell both out.
-                throw new Error(`Failed to clone branch workspace at ${options.workspacePath} ` +
-                    `from ${remoteUrl} (base branch '${baseBranch}'): ${getErrorMessage(err)}`);
-            }
+            // A content clone skips its own checkout because checkoutFreshClone runs
+            // the one checkout this workspace needs.
+            await step('clone', () => GitManager.cloneWorkspace(remoteUrl, options.workspacePath, baseBranch, {
+                remoteName,
+                noCheckout: options.branchType === 'content',
+                config: identity,
+            }));
             justCloned = true;
-            // Mark as managed immediately after clone so ensureRemote's guard works,
-            // and set a fallback author identity: GIT_CEILING_DIRECTORIES blocks
-            // global gitconfig, and internal commits (e.g. orphan branch init) need
-            // one. ensureAuthor() sets the real bot author before user-facing commits.
-            const freshGit = simpleGit({ baseDir: options.workspacePath });
-            freshGit.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path.dirname(options.workspacePath) }));
-            await freshGit.addConfig('canopycms.managed', 'true');
-            await freshGit.addConfig('user.name', options.gitBotAuthorName);
-            await freshGit.addConfig('user.email', options.gitBotAuthorEmail);
+            resolvedRemoteUrl = remoteUrl;
         }
         // Settings (orphan) workspaces never host ContentStores, so they skip the
         // on-disk content-index generation marker.
@@ -726,46 +1004,55 @@ export class GitManager {
             remote: remoteName,
             skipIndexMarker: options.branchType === 'orphan',
         });
-        // The managed marker and fallback identity must be set before ensureRemote
-        // (which checks the marker) and before createOrphanSettingsBranch (which
-        // commits and needs an author). Idempotent — the clone above may have set them.
-        await git.git.addConfig('canopycms.managed', 'true');
-        await git.git.addConfig('user.name', options.gitBotAuthorName);
-        await git.git.addConfig('user.email', options.gitBotAuthorEmail);
-        log.debug('git', 'Marked workspace as CanopyCMS-managed', {
-            workspacePath: options.workspacePath,
-        });
-        // Configure the remote only if we didn't just clone (clone sets up 'origin')
+        // A reused workspace gets the same marker and identity the clone writes,
+        // set before ensureRemote checks the marker; a healthy one writes nothing.
         if (!justCloned) {
-            const remoteUrl = await GitManager.resolveRemoteUrl({
-                mode: options.mode,
-                remoteUrl: options.remoteUrl,
-                defaultRemoteUrl: options.defaultRemoteUrl,
-                baseBranch,
-                sourceRoot: options.sourceRoot,
-                allowNetworkRemoteInProd: options.allowNetworkRemoteInProd,
+            await step('config', async () => {
+                await git.ensureLocalConfig(identity);
+                const remoteUrl = await GitManager.resolveRemoteUrl({
+                    mode: options.mode,
+                    remoteUrl: options.remoteUrl,
+                    defaultRemoteUrl: options.defaultRemoteUrl,
+                    baseBranch,
+                    sourceRoot: options.sourceRoot,
+                    allowNetworkRemoteInProd: options.allowNetworkRemoteInProd,
+                });
+                if (remoteUrl) {
+                    await git.ensureRemote(remoteUrl);
+                }
+                resolvedRemoteUrl = remoteUrl;
             });
-            if (remoteUrl) {
-                await git.ensureRemote(remoteUrl);
-            }
         }
         if (options.branchType === 'orphan') {
-            await git.createOrphanSettingsBranch(options.branchName, {});
+            try {
+                await step('checkout', () => git.createOrphanSettingsBranch(options.branchName, {}));
+            }
+            catch (err) {
+                // A remote that is unreadable because the worker has not (re)created
+                // it yet is the transient not-ready case, not a broken workspace.
+                if (err instanceof SettingsRemoteUnreadableError && !resolvedRemoteUrl) {
+                    throw (await GitManager.remoteNotReadyError(options.mode)) ?? err;
+                }
+                throw err;
+            }
             // Settings mutations hold an OCC lockfile (<file>.lock, see
             // authorization/settings-file-store.ts) inside this git-committed
             // workspace. Commits here stage explicit paths, but a crash-orphaned lock
             // dir must never be committable by a future broad stage either. Runs on
             // every init, so existing clones pick it up.
-            await git.ensureGitExclude('*.lock');
+            await step('exclude', () => git.ensureGitExclude('*.lock'));
         }
         else {
-            await git.checkoutBranch(options.branchName);
+            await step('checkout', () => justCloned
+                ? git.checkoutFreshClone(options.branchName)
+                : git.checkoutBranch(options.branchName));
             // Excludes runtime metadata (.canopy-meta/) from git tracking on content
             // branches. Settings workspaces don't need it: they stage explicit file
             // paths at the workspace root and skip the index marker entirely
             // (skipIndexMarker), so nothing under .canopy-meta/ is ever staged.
-            if (options.gitExcludePattern) {
-                await git.ensureGitExclude(options.gitExcludePattern);
+            const pattern = options.gitExcludePattern;
+            if (pattern) {
+                await step('exclude', () => git.ensureGitExclude(pattern));
             }
         }
         return git;
@@ -808,6 +1095,24 @@ export class GitManager {
             await this.invalidateContentIndexes();
         }
     }
+    /**
+     * The one checkout of a `--no-checkout` clone, which has the base branch
+     * and its remote-tracking ref and nothing else, so neither the branch
+     * listing nor the fetch that {@link checkoutBranch} starts with is needed.
+     * The missing index makes git populate the whole tree, even for the base
+     * branch HEAD already names.
+     */
+    async checkoutFreshClone(branch) {
+        const target = branch === this.baseBranch
+            ? ['checkout', branch]
+            : ['checkout', '-b', branch, `${this.remote}/${this.baseBranch}`];
+        try {
+            await this.git.raw([...PARALLEL_CHECKOUT_ARGS, ...target]);
+        }
+        finally {
+            await this.invalidateContentIndexes();
+        }
+    }
     async checkoutBranchInner(branch) {
         const branches = await this.git.branch();
         if (branches.all.includes(branch)) {
@@ -893,7 +1198,8 @@ export class GitManager {
         const branches = await this.git.branch();
         const currentBranch = branches.current;
         try {
-            await this.git.fetch(this.remote, currentBranch);
+            // The full ref: a bare name resolves to a same-named tag first.
+            await this.git.fetch(this.remote, `refs/heads/${currentBranch}`);
         }
         catch (err) {
             // The only benign failure here: the branch has never been pushed, so the
@@ -966,17 +1272,31 @@ export class GitManager {
             throw err;
         }
     }
+    /** `--sparse` stages a named path outside a sparse clone's cone (branch-sparse.ts). */
     async add(files) {
         const fileArray = Array.isArray(files) ? files : [files];
-        await this.git.add(fileArray);
+        await this.git.raw(['add', '--sparse', '--', ...fileArray]);
+    }
+    /**
+     * Restrict the working tree to `dirs` in cone mode, which always keeps the root-level files.
+     * Runs before a `--no-checkout` clone's one checkout, which invalidates the content caches.
+     */
+    async setSparseCone(dirs) {
+        await this.git.raw(['sparse-checkout', 'set', '--cone', '--', ...dirs]);
+    }
+    /** Stage every working-tree change except canopycms's own state. See {@link stageAllExceptCanopyState}. */
+    async addAllExceptCanopyState() {
+        await stageAllExceptCanopyState(this.git);
     }
     async commit(message) {
         await this.git.commit(message);
     }
     async push(branch) {
-        const target = branch ?? (await this.git.revparse(['--abbrev-ref', 'HEAD']));
-        // Explicit refspec (local:remote) so push works for branches not yet in the
-        // remote (e.g. orphan settings branches). Built via raw() rather than the
+        const target = branch ?? (await this.currentBranchName());
+        // Explicit full-ref refspec (local:remote) so push works for branches not
+        // yet in the remote (e.g. orphan settings branches), and a same-named tag
+        // cannot redirect it: a short name for a new remote branch would create
+        // `refs/heads/heads/<name>`. Built via raw() rather than the
         // push() wrapper so `--end-of-options` sits immediately before the
         // positional remote/refspec, guarding against a refspec starting with '-'
         // being parsed as a git option (e.g. --receive-pack=...). Real flags must
@@ -986,9 +1306,20 @@ export class GitManager {
             '--set-upstream',
             '--end-of-options',
             this.remote,
-            `${target}:${target}`,
+            `refs/heads/${target}:refs/heads/${target}`,
         ]);
     }
+    /**
+     * The checked-out branch's plain name. `rev-parse --abbrev-ref HEAD` prints
+     * `heads/<name>` when a same-named tag exists, which is not a branch name.
+     */
+    async currentBranchName() {
+        const branches = await this.git.branch();
+        if (branches.detached || !branches.current) {
+            throw new Error(`CanopyCMS: no branch is checked out (detached HEAD) in ${this.repoPath}`);
+        }
+        return branches.current;
+    }
     /**
      * Whether the local branch has commits the remote mirror doesn't -- i.e.
      * whether push() would move the remote ref forward.
@@ -1010,12 +1341,14 @@ export class GitManager {
         // `--end-of-options` before every caller-influenced ref name, as in push()
         // above: names are sanitized upstream, but this file's rule is that a
         // positional is guarded where it is passed, not where it was validated.
-        const target = branch ?? (await this.git.revparse(['--abbrev-ref', '--end-of-options', 'HEAD']));
-        const localSha = (await this.git.revparse(['--end-of-options', target])).trim();
+        // Each rev-parse needs `--verify`: without it, rev-parse echoes
+        // `--end-of-options` as its own output line ahead of the result.
+        const target = branch ?? (await this.git.revparse(['--verify', '--abbrev-ref', '--end-of-options', 'HEAD']));
+        const localSha = (await this.git.revparse(['--verify', '--end-of-options', target])).trim();
         let fetchedTip;
         try {
             await this.git.raw(['fetch', '--end-of-options', this.remote, target]);
-            fetchedTip = (await this.git.revparse(['--end-of-options', 'FETCH_HEAD'])).trim();
+            fetchedTip = (await this.git.revparse(['--verify', '--end-of-options', 'FETCH_HEAD'])).trim();
         }
         catch {
             // No ref on the remote yet -- the branch has never been pushed.
@@ -1028,6 +1361,27 @@ export class GitManager {
         const aheadCount = (await this.git.raw(['rev-list', '--count', `${fetchedTip}..${localSha}`])).trim();
         return aheadCount !== '0';
     }
+    /**
+     * Repo-relative paths that differ between HEAD and its merge base with the
+     * base branch: everything the branch changes, across all of its commits.
+     * Diffs against the just-fetched base tip pinned to a SHA — the pullBaseInner
+     * constraint.
+     */
+    async listChangedPathsSinceBase() {
+        await this.git.raw(['fetch', '--end-of-options', this.remote, this.baseBranch]);
+        // `--verify`: without it rev-parse echoes `--end-of-options` back as output.
+        const baseTip = (await this.git.revparse(['--verify', '--end-of-options', 'FETCH_HEAD'])).trim();
+        // -z: NUL-separated and unquoted, so no path needs unescaping.
+        const output = await this.git.raw([
+            'diff',
+            '--name-only',
+            '-z',
+            '--no-renames',
+            `${baseTip}...HEAD`,
+            '--',
+        ]);
+        return output.split('\0').filter((p) => p.length > 0);
+    }
     async ensureAuthor(author) {
         const config = (await this.git.listConfig());
         // Verify this is a CanopyCMS-managed workspace before setting author
@@ -1046,6 +1400,14 @@ export class GitManager {
             await this.git.addConfig('user.email', author.email);
         }
     }
+    /** Writes each key into this repo's own config only where it differs. */
+    async ensureLocalConfig(values) {
+        const local = (await this.git.listConfig('local'));
+        for (const [key, value] of Object.entries(values)) {
+            if (local.all[key] !== value)
+                await this.git.addConfig(key, value);
+        }
+    }
     async ensureRemote(remoteUrl) {
         // Safety: verify this is a managed workspace before modifying remotes.
         // Prevents accidentally overwriting the host repo's origin if git
@@ -1089,10 +1451,24 @@ export class GitManager {
         await ensureGitExcludePattern(this.repoPath, pattern);
     }
     /**
-     * Create an orphan branch (no shared history) for settings, so
-     * deployment-specific settings never pollute content history. It holds only
-     * settings files committed by explicit path (permissions.json, groups.json at
-     * the workspace root).
+     * Put the workspace on the settings branch: an orphan (no shared history),
+     * so deployment-specific settings never pollute content history. It holds
+     * only settings files committed by explicit path (permissions.json,
+     * groups.json at the workspace root).
+     *
+     * The remote is the settings branch's durable copy, and the workspace clone
+     * is `--single-branch` at the base branch, so the remote is asked first:
+     * - no local branch: check out the remote's, or create an empty orphan only
+     *   when the remote has none. An unreadable remote throws
+     *   {@link SettingsRemoteUnreadableError} rather than guess "none".
+     * - local branch present: a history unrelated to the remote's is repaired
+     *   onto the remote's when the local branch is still its empty initial
+     *   commit with a clean working tree, and otherwise throws
+     *   {@link SettingsBranchDivergedError}; local commits are never discarded.
+     *   An unreadable remote throws only for that empty branch, since one that
+     *   holds settings can serve them and the next save surfaces the remote error.
+     * Either way a remote branch holding content is never adopted:
+     * {@link SettingsBranchHasContentHistoryError}.
      */
     async createOrphanSettingsBranch(branchName, initialFiles) {
         try {
@@ -1104,26 +1480,49 @@ export class GitManager {
         }
     }
     async createOrphanSettingsBranchInner(branchName, initialFiles) {
-        log.debug('git', 'Creating orphan settings branch', { branchName });
+        log.debug('git', 'Ensuring settings branch', { branchName });
         const branches = await this.git.branch();
-        if (branches.all.includes(branchName)) {
-            log.debug('git', 'Orphan branch already exists', { branchName });
+        const localExists = branches.all.includes(branchName);
+        if (localExists) {
             // No separator here — see checkoutBranch() above for why plain
             // `git checkout <branch>` can't safely take one. branchName is always an
             // internal/config-derived settings-branch name, never user input.
             await this.git.checkout(branchName);
+        }
+        let remoteTip;
+        try {
+            remoteTip = await this.remoteBranchTip(branchName);
+        }
+        catch (err) {
+            if (localExists && !(await this.isEmptyInitialBranch(branchName))) {
+                log.debug('git', 'Remote unreadable; serving the local settings branch', { branchName });
+                return;
+            }
+            throw new SettingsRemoteUnreadableError(branchName, this.remote, err);
+        }
+        if (localExists) {
+            await this.reconcileLocalSettingsBranch(branchName, remoteTip);
+            return;
+        }
+        if (remoteTip) {
+            const fetchedTip = await this.fetchBranchTip(branchName);
+            await this.assertNotContentHistory(branchName, fetchedTip);
+            // `-b` consumes branchName as its literal value; see checkoutBranchInner.
+            await this.git.raw(['checkout', '-b', branchName, fetchedTip]);
+            log.debug('git', 'Checked out the remote settings branch', { branchName });
             return;
         }
         // branchName is consumed as --orphan's literal argument value (like -b/-B
         // above), so it can't be reinterpreted as a flag; git's own ref-name
         // validation additionally rejects a leading-hyphen value here.
         await this.git.raw(['checkout', '--orphan', branchName]);
-        // Remove all files from index (orphan checkout keeps working tree)
-        try {
-            await this.git.raw(['rm', '-rf', '.']);
-        }
-        catch {
-            // Ignore errors (might fail if index is already empty)
+        // The orphan starts from the base branch's index. `--sparse` also removes entries outside a
+        // sparse cone, which a plain `rm` leaves in the index, and so in the first commit.
+        await this.git.raw(['rm', '-r', '-f', '-q', '--sparse', '--ignore-unmatch', '--', '.']);
+        const leftover = (await this.git.raw(['ls-files'])).trim();
+        if (leftover) {
+            throw new Error(`Settings branch '${branchName}' was not created: the base branch's files ` +
+                `(${leftover.split('\n').slice(0, 3).join(', ')}) stayed in its index`);
         }
         for (const [filePath, content] of Object.entries(initialFiles)) {
             const absolutePath = path.join(this.repoPath, filePath);
@@ -1134,4 +1533,123 @@ export class GitManager {
         await this.git.commit('Initialize settings branch', ['--allow-empty']);
         log.debug('git', 'Orphan settings branch created', { branchName });
     }
+    /**
+     * Compares the checked-out local settings branch with the remote's tip.
+     * Related histories are left for the next settings pull to reconcile; only
+     * an unrelated one is acted on here.
+     */
+    async reconcileLocalSettingsBranch(branchName, remoteTip) {
+        if (!remoteTip)
+            return;
+        const localTip = (await this.git.revparse([`refs/heads/${branchName}`])).trim();
+        if (localTip === remoteTip)
+            return;
+        const fetchedTip = await this.fetchBranchTip(branchName);
+        const [localRoots, remoteRoots] = await Promise.all([
+            this.rootCommits(localTip),
+            this.rootCommits(fetchedTip),
+        ]);
+        if (localRoots.some((root) => remoteRoots.includes(root)))
+            return;
+        const localWork = [];
+        if (!(await this.isEmptyInitialBranch(branchName))) {
+            localWork.push('commits beyond its empty initial commit');
+        }
+        const uncommitted = await this.getUncommittedFiles();
+        if (uncommitted.length > 0) {
+            localWork.push(`uncommitted changes to ${uncommitted.join(', ')}`);
+        }
+        if (localWork.length > 0) {
+            throw new SettingsBranchDivergedError(branchName, this.repoPath, localWork.join(' and '));
+        }
+        await this.assertNotContentHistory(branchName, fetchedTip);
+        // `checkout -B` resets the current branch onto the fetched tip, and
+        // refuses rather than overwrite a file written since the check above.
+        await this.git.raw(['checkout', '-B', branchName, fetchedTip]);
+        log.debug('git', 'Replaced an empty settings branch with the remote one', { branchName });
+    }
+    /**
+     * The remote's tip for `branch`, or `undefined` when the remote has no such
+     * branch. A remote that cannot be read throws: `ls-remote` exits 0 with no
+     * output only for a reachable remote without the ref.
+     */
+    async remoteBranchTip(branch) {
+        const ref = `refs/heads/${branch}`;
+        const output = await this.git.raw(['ls-remote', '--heads', this.remote, ref]);
+        for (const line of output.split('\n')) {
+            const [sha, name] = line.trim().split('\t');
+            if (sha && name === ref)
+                return sha;
+        }
+        return undefined;
+    }
+    /**
+     * Fetch `branch` from the remote and return the fetched commit, pinned as
+     * pullBaseInner explains. The full ref: a bare name resolves to a
+     * same-named tag first.
+     */
+    async fetchBranchTip(branch) {
+        await this.git.fetch(this.remote, `refs/heads/${branch}`);
+        return (await this.git.revparse(['FETCH_HEAD'])).trim();
+    }
+    /**
+     * Refuse to adopt a remote settings branch that holds content: its tip has a file other than
+     * the settings files, or its roots include the base branch's (a settings branch is an orphan).
+     * Neither alone suffices: a base can have a root of its own, and a content tree can be pruned.
+     * The base comes from the remote when the clone lacks it (it was cloned at an earlier base).
+     */
+    async assertNotContentHistory(branchName, tip) {
+        const tree = await this.git.raw(['ls-tree', '-r', '--name-only', tip]);
+        const strays = tree.split('\n').filter((file) => file && !SETTINGS_BRANCH_FILES.has(file));
+        if (strays.length > 0) {
+            const shown = strays.slice(0, 3).join(', ') + (strays.length > 3 ? ', …' : '');
+            throw new SettingsBranchHasContentHistoryError(branchName, this.remote, `it holds ${shown}`);
+        }
+        const [tipRoots, baseRoots] = await Promise.all([
+            this.rootCommits(tip),
+            this.baseBranchRev(branchName).then((rev) => this.rootCommits(rev)),
+        ]);
+        if (tipRoots.some((root) => baseRoots.includes(root))) {
+            throw new SettingsBranchHasContentHistoryError(branchName, this.remote, `it shares history with the base branch '${this.baseBranch}'`);
+        }
+    }
+    async baseBranchRev(settingsBranch) {
+        for (const ref of [
+            `refs/heads/${this.baseBranch}`,
+            `refs/remotes/${this.remote}/${this.baseBranch}`,
+        ]) {
+            // `--quiet` makes a missing ref a silent non-zero exit, which simple-git resolves
+            // with empty output rather than rejecting.
+            const sha = await this.git
+                .raw(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
+                .catch(() => '');
+            if (sha.trim())
+                return sha.trim();
+        }
+        try {
+            return await this.fetchBranchTip(this.baseBranch);
+        }
+        catch (err) {
+            throw new Error(`CanopyCMS: could not read base branch '${this.baseBranch}' from remote ` +
+                `'${this.remote}', so settings branch '${settingsBranch}' was not checked out: ` +
+                `${getErrorMessage(err)}`);
+        }
+    }
+    async rootCommits(rev) {
+        const output = await this.git.raw(['rev-list', '--max-parents=0', rev]);
+        return output.split('\n').filter(Boolean);
+    }
+    /**
+     * Whether `branch` is a single parentless commit with an empty tree, as
+     * orphan creation leaves it. Full refs throughout: a bare name resolves to a
+     * same-named tag first, and clones fetch tags.
+     */
+    async isEmptyInitialBranch(branch) {
+        const ref = `refs/heads/${branch}`;
+        const commits = await this.git.raw(['rev-list', '--max-count=2', ref]);
+        if (commits.split('\n').filter(Boolean).length !== 1)
+            return false;
+        const tree = await this.git.raw(['ls-tree', ref]);
+        return tree.trim() === '';
+    }
 }