canopycms 0.0.67 → 0.0.68-int.94

package/dist/schema/schema-store.d.ts

@@ -1,6 +1,5 @@
 /**
- * Schema Store - handles reading and writing .collection.json files.
- * All mutations are branch-specific (like content edits).
+ * Schema Store - reads and writes .collection.json files, per branch.
  *
  * ## Concurrency
  *
@@ -16,11 +15,11 @@
  *
  * Protection is instead layer 1 ({@link withLock}) + layer 3
  * ({@link withOccFileLock}) on one COARSE per-branch SURROGATE lock path
- * OUTSIDE the content tree (`{branchRoot}/.canopy-meta/schema`, see
- * `withSchemaLock`), covering every schema mutation on the branch including
- * multi-file ones. Layer 2 (OCC read-back) is skipped, since there's no
- * version field to check; layer 4 (generation marker) guards the schema
- * CACHE separately, not this write path.
+ * OUTSIDE the content tree (`{branchRoot}/.canopy-meta/schema`), covering
+ * every schema mutation including multi-file ones, inside the [SYNC-C1]
+ * content-write lock the worker's rebase also takes (`withBranchSchemaLock`).
+ * Layer 2 (OCC read-back) is skipped, since there's no version field to
+ * check; layer 4 (generation marker) guards the schema CACHE separately.
  *
  * Accepted residual: `deleteBranch` does not take this lock before its
  * recursive `rm`, so an in-flight write can race a concurrent branch
@@ -182,7 +181,30 @@ declare const updateEntryTypeInputSchema: z.ZodObject<{
  * into a 409 so the editor can retry rather than surfacing a raw 400.
  */
 export declare class SchemaStoreBusyError extends Error {
-    constructor(message?: string);
+    /** As on `ContentWriteLockBusyError`: `'unknown'` means the mutation ran and may have landed. */
+    readonly outcome: 'not-run' | 'unknown';
+    constructor(message?: string, 
+    /** As on `ContentWriteLockBusyError`: `'unknown'` means the mutation ran and may have landed. */
+    outcome?: 'not-run' | 'unknown');
+}
+/**
+ * Run `fn` holding every lock a schema mutation needs on `branchRoot`, in the
+ * global order (docs/concurrency.md, "Lock acquisition order"): the branch's
+ * content-write lock, then the `.canopy-meta/schema` surrogate's in-process
+ * mutex, then its lockfile. Shared with `cli/migrate.ts` so the two cannot
+ * drift.
+ *
+ * NOT re-entrant, and nothing inside `fn` may take the content-write lock
+ * (no `ContentStore` writes): proper-lockfile refuses a second acquisition in
+ * the same process, so a nested one burns its wait and fails busy.
+ *
+ * Errors propagate untranslated: `ContentWriteLockBusyError` (contention, or
+ * a compromise reported after `fn` completed) and `OccWriteConflictError`.
+ */
+export declare function withBranchSchemaLock<T>(branchRoot: string, fn: () => Promise<T>, contentWriteLockWaitMs?: number): Promise<T>;
+export interface SchemaOpsOptions {
+    /** Bounded wait for the branch's content-write lock; defaults to `DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS`. */
+    contentWriteLockWaitMs?: number;
 }
 export declare class SchemaOps {
     private readonly contentRoot;
@@ -199,21 +221,19 @@ export declare class SchemaOps {
      * and never match the root collection's logical path).
      */
     private readonly contentRootName;
-    /** Coarse per-branch surrogate lock path — see the module doc comment. */
-    private readonly schemaLockPath;
-    constructor(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry, services?: CanopyServices | undefined, branchRoot?: string);
+    /** See SchemaOpsOptions.contentWriteLockWaitMs. */
+    private readonly contentWriteLockWaitMs;
+    constructor(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry, services?: CanopyServices | undefined, branchRoot?: string, options?: SchemaOpsOptions);
     /**
-     * Serialize an entire read-modify-write schema mutation behind the coarse
-     * per-branch surrogate lock described in the module doc comment: layer 1
-     * ({@link withLock}, in-process FIFO mutex) wraps layer 3
-     * ({@link withOccFileLock}, cross-process/cross-host mkdir-based mutual
-     * exclusion, immune to NFS attribute caching), same structure as
-     * `BranchMetadataFileManager.save()` in branch-metadata.ts.
+     * Serialize an entire read-modify-write schema mutation behind
+     * {@link withBranchSchemaLock}: the content-write lock, then the surrogate
+     * ({@link withLock} wrapping {@link withOccFileLock}, as in
+     * `BranchMetadataFileManager.save()`).
      *
      * NOT re-entrant — callers must never invoke this from inside a callback
-     * already running under it, or `withLock` deadlocks waiting on itself;
-     * that's why `updateOrderInner` calls `updateCollectionInner` directly
-     * instead of the public `updateCollection`.
+     * already running under it, or the nested acquisition fails busy; that's
+     * why `updateOrderInner` calls `updateCollectionInner` directly instead of
+     * the public `updateCollection`.
      *
      * Phantom-resurrection guard: `branchRoot` can be removed by a concurrent
      * `deleteBranch` between the caller resolving its BranchContext and this
@@ -226,7 +246,13 @@ export declare class SchemaOps {
      * since `deleteBranch` never takes this lock (see the module doc comment).
      *
      * Translation happens ONLY at this boundary: inner code always sees the
-     * raw {@link OccWriteConflictError} bubble up here untranslated.
+     * raw {@link OccWriteConflictError} bubble up here untranslated, and a
+     * {@link ContentWriteLockBusyError} becomes a `SchemaStoreBusyError` with
+     * its message, so every caller's 409 mapping covers both.
+     *
+     * A content-lock compromise is reported after `fn` completed, so the
+     * mutation is on disk while the caller's post-lock `invalidateSchemaCache()`
+     * never runs; this runs it before throwing.
      */
     private withSchemaLock;
     /**
@@ -322,7 +348,7 @@ export declare class SchemaOps {
      * Body of updateCollection, holding the schema lock for its full
      * read-modify-write. Called directly (not via the public `updateCollection`)
      * by `updateOrderInner` for non-root collections — `withSchemaLock` is NOT
-     * re-entrant, so going through the public method there would deadlock.
+     * re-entrant, so going through the public method there would fail busy.
      *
      * `collectionPath` here is always already normalized (content-root prefix
      * stripped, if it had one) by whichever public method reached this — either

package/dist/schema/schema-store.js

@@ -1,6 +1,5 @@
 /**
- * Schema Store - handles reading and writing .collection.json files.
- * All mutations are branch-specific (like content edits).
+ * Schema Store - reads and writes .collection.json files, per branch.
  *
  * ## Concurrency
  *
@@ -16,11 +15,11 @@
  *
  * Protection is instead layer 1 ({@link withLock}) + layer 3
  * ({@link withOccFileLock}) on one COARSE per-branch SURROGATE lock path
- * OUTSIDE the content tree (`{branchRoot}/.canopy-meta/schema`, see
- * `withSchemaLock`), covering every schema mutation on the branch including
- * multi-file ones. Layer 2 (OCC read-back) is skipped, since there's no
- * version field to check; layer 4 (generation marker) guards the schema
- * CACHE separately, not this write path.
+ * OUTSIDE the content tree (`{branchRoot}/.canopy-meta/schema`), covering
+ * every schema mutation including multi-file ones, inside the [SYNC-C1]
+ * content-write lock the worker's rebase also takes (`withBranchSchemaLock`).
+ * Layer 2 (OCC read-back) is skipped, since there's no version field to
+ * check; layer 4 (generation marker) guards the schema CACHE separately.
  *
  * Accepted residual: `deleteBranch` does not take this lock before its
  * recursive `rm`, so an in-flight write can race a concurrent branch
@@ -34,6 +33,7 @@ import { z } from 'zod';
 import { atomicWriteFile } from '../utils/atomic-write.js';
 import { withLock } from '../utils/async-mutex.js';
 import { createDebugLogger } from '../utils/debug.js';
+import { ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, withContentWriteLock, } from '../utils/content-write-lock.js';
 import { getErrorMessage, isNotFoundError } from '../utils/error.js';
 import { withOccFileLock, OccWriteConflictError } from '../utils/occ-json-write.js';
 import { resolveCollectionPath } from '../content-id-index.js';
@@ -107,13 +107,34 @@ const log = createDebugLogger({ prefix: 'SchemaOps' });
  * into a 409 so the editor can retry rather than surfacing a raw 400.
  */
 export class SchemaStoreBusyError extends Error {
-    constructor(message = 'Schema is being modified by another operation, try again') {
+    constructor(message = 'Schema is being modified by another operation, try again', 
+    /** As on `ContentWriteLockBusyError`: `'unknown'` means the mutation ran and may have landed. */
+    outcome = 'not-run') {
         super(message);
+        this.outcome = outcome;
         this.name = 'SchemaStoreBusyError';
     }
 }
+/**
+ * Run `fn` holding every lock a schema mutation needs on `branchRoot`, in the
+ * global order (docs/concurrency.md, "Lock acquisition order"): the branch's
+ * content-write lock, then the `.canopy-meta/schema` surrogate's in-process
+ * mutex, then its lockfile. Shared with `cli/migrate.ts` so the two cannot
+ * drift.
+ *
+ * NOT re-entrant, and nothing inside `fn` may take the content-write lock
+ * (no `ContentStore` writes): proper-lockfile refuses a second acquisition in
+ * the same process, so a nested one burns its wait and fails busy.
+ *
+ * Errors propagate untranslated: `ContentWriteLockBusyError` (contention, or
+ * a compromise reported after `fn` completed) and `OccWriteConflictError`.
+ */
+export async function withBranchSchemaLock(branchRoot, fn, contentWriteLockWaitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS) {
+    const schemaLockPath = path.join(path.resolve(branchRoot), '.canopy-meta', 'schema');
+    return withContentWriteLock(branchRoot, () => withLock(schemaLockPath, () => withOccFileLock(schemaLockPath, fn)), contentWriteLockWaitMs);
+}
 export class SchemaOps {
-    constructor(contentRoot, entrySchemaRegistry, services, branchRoot) {
+    constructor(contentRoot, entrySchemaRegistry, services, branchRoot, options = {}) {
         this.contentRoot = contentRoot;
         this.entrySchemaRegistry = entrySchemaRegistry;
         this.services = services;
@@ -130,20 +151,19 @@ export class SchemaOps {
             .relative(this.branchRoot, resolvedContentRoot)
             .split(path.sep)
             .join('/');
-        this.schemaLockPath = path.join(this.branchRoot, '.canopy-meta', 'schema');
+        this.contentWriteLockWaitMs =
+            options.contentWriteLockWaitMs ?? DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS;
     }
     /**
-     * Serialize an entire read-modify-write schema mutation behind the coarse
-     * per-branch surrogate lock described in the module doc comment: layer 1
-     * ({@link withLock}, in-process FIFO mutex) wraps layer 3
-     * ({@link withOccFileLock}, cross-process/cross-host mkdir-based mutual
-     * exclusion, immune to NFS attribute caching), same structure as
-     * `BranchMetadataFileManager.save()` in branch-metadata.ts.
+     * Serialize an entire read-modify-write schema mutation behind
+     * {@link withBranchSchemaLock}: the content-write lock, then the surrogate
+     * ({@link withLock} wrapping {@link withOccFileLock}, as in
+     * `BranchMetadataFileManager.save()`).
      *
      * NOT re-entrant — callers must never invoke this from inside a callback
-     * already running under it, or `withLock` deadlocks waiting on itself;
-     * that's why `updateOrderInner` calls `updateCollectionInner` directly
-     * instead of the public `updateCollection`.
+     * already running under it, or the nested acquisition fails busy; that's
+     * why `updateOrderInner` calls `updateCollectionInner` directly instead of
+     * the public `updateCollection`.
      *
      * Phantom-resurrection guard: `branchRoot` can be removed by a concurrent
      * `deleteBranch` between the caller resolving its BranchContext and this
@@ -156,7 +176,13 @@ export class SchemaOps {
      * since `deleteBranch` never takes this lock (see the module doc comment).
      *
      * Translation happens ONLY at this boundary: inner code always sees the
-     * raw {@link OccWriteConflictError} bubble up here untranslated.
+     * raw {@link OccWriteConflictError} bubble up here untranslated, and a
+     * {@link ContentWriteLockBusyError} becomes a `SchemaStoreBusyError` with
+     * its message, so every caller's 409 mapping covers both.
+     *
+     * A content-lock compromise is reported after `fn` completed, so the
+     * mutation is on disk while the caller's post-lock `invalidateSchemaCache()`
+     * never runs; this runs it before throwing.
      */
     async withSchemaLock(fn) {
         try {
@@ -168,13 +194,31 @@ export class SchemaOps {
             }
             throw err;
         }
+        let landed = false;
         try {
-            return await withLock(this.schemaLockPath, () => withOccFileLock(this.schemaLockPath, fn));
+            return await withBranchSchemaLock(this.branchRoot, async () => {
+                const result = await fn();
+                landed = true;
+                return result;
+            }, this.contentWriteLockWaitMs);
         }
         catch (err) {
             if (err instanceof OccWriteConflictError) {
                 throw new SchemaStoreBusyError();
             }
+            if (err instanceof ContentWriteLockBusyError) {
+                if (landed) {
+                    await this.invalidateSchemaCache().catch((invalidateErr) => {
+                        log.warn('schema-cache', 'Invalidation after a lost content-write lock failed', {
+                            branchRoot: this.branchRoot,
+                            error: getErrorMessage(invalidateErr),
+                        });
+                    });
+                }
+                throw new SchemaStoreBusyError(err.outcome === 'unknown'
+                    ? 'This branch was being synced while the schema change was written, so it may or may not have been recorded. Reload before changing the schema again.'
+                    : err.message, err.outcome);
+            }
             throw err;
         }
     }
@@ -461,7 +505,7 @@ export class SchemaOps {
      * Body of updateCollection, holding the schema lock for its full
      * read-modify-write. Called directly (not via the public `updateCollection`)
      * by `updateOrderInner` for non-root collections — `withSchemaLock` is NOT
-     * re-entrant, so going through the public method there would deadlock.
+     * re-entrant, so going through the public method there would fail busy.
      *
      * `collectionPath` here is always already normalized (content-root prefix
      * stripped, if it had one) by whichever public method reached this — either

package/dist/services.d.ts

@@ -24,11 +24,16 @@ import { GitManager } from './git-manager.js';
 import { BranchRegistry } from './branch-registry.js';
 import { type GitHubService } from './github-service.js';
 import { BranchSchemaCache } from './branch-schema-cache.js';
+import { type SubmissionEditor } from './submission-attribution.js';
 /**
  * Bootstrap admin IDs from the environment. These users are treated as Admins
  * whatever their group membership.
  */
 export declare const getBootstrapAdminIds: () => Set<string>;
+export interface SubmitBranchResult {
+    /** Repo-relative paths the branch changes, excluding canopycms runtime metadata. */
+    changedPaths: string[];
+}
 export interface CanopyServices {
     config: CanopyConfig;
     /**
@@ -58,27 +63,34 @@ export interface CanopyServices {
     githubService?: GitHubService;
     /** Bootstrap admin user IDs that are always treated as Admins */
     bootstrapAdminIds: Set<string>;
-    /** Commit files to git with automatic author handling */
+    /**
+     * Commit files to git with automatic author handling. Holds the branch's
+     * content-write lock; rejects with `ContentWriteLockBusyError` when busy.
+     */
     commitFiles: (options: {
         context: BranchContext;
         files: string | string[];
         message: string;
     }) => Promise<void>;
-    /** Submit branch: commit all changes and push to remote */
+    /**
+     * Submit branch: commit all changes (with the submitter's trailers) and push
+     * to remote. Resolves with every path the branch changes against its base.
+     * Holds the branch's content-write lock; rejects with
+     * `ContentWriteLockBusyError` when busy.
+     */
     submitBranch: (options: {
         context: BranchContext;
+        submitter?: SubmissionEditor;
         message?: string;
-    }) => Promise<void>;
-    /** Commit to settings branch (for permissions/groups), with optional PR creation */
+    }) => Promise<SubmitBranchResult>;
+    /** Commit to the settings branch (for permissions/groups) and push it; never opens a PR */
     commitToSettingsBranch: (options: {
         branchRoot: string;
         files: string | string[];
         message: string;
-        createPR?: boolean;
     }) => Promise<{
         committed: boolean;
         pushed: boolean;
-        prUrl?: string;
         error?: string;
         syncStatus?: 'pending-sync' | 'synced' | 'sync-failed';
     }>;

package/dist/services.js

@@ -9,8 +9,13 @@ import { operatingStrategy } from './operating-mode/index.js';
 import { BranchSchemaCache } from './branch-schema-cache.js';
 import { enqueueTask } from './task-queue/cms-task-queue.js';
 import { getTaskQueueDir } from './task-queue/task-queue-config.js';
-import { detectHeadBranch } from './utils/git.js';
+import { detectHeadBranch, isCanopyInternalPath } from './utils/git.js';
 import { readsFromCheckout } from './build-mode.js';
+import { timeRequestPhase } from './utils/request-timing.js';
+import { BRANCH_META_DIR } from './branch-metadata-file.js';
+import { appendTrailers, buildEditorTrailers, } from './submission-attribution.js';
+import { getErrorMessage, redactCredentials } from './utils/error.js';
+import { withContentWriteLock } from './utils/content-write-lock.js';
 /**
  * A per-instance active-branch detector with its own 5s TTL cache, in priority
  * order: an explicitly configured value; `defaultBaseBranch ?? 'main'` with no
@@ -97,7 +102,7 @@ async function _createCanopyServicesInternal(config, options) {
     const branchSchemaCache = options.branchSchemaCache ?? new BranchSchemaCache(config.mode);
     const checkBranchAccess = createCheckBranchAccess(config.defaultBranchAccess ?? 'deny', config);
     // Content access loads permissions dynamically from the settings branch (orphan git branch)
-    const getSettingsBranchRoot = options.getSettingsBranchRoot ??
+    const ensureSettingsBranchRoot = options.getSettingsBranchRoot ??
         (async () => {
             const strategy = operatingStrategy(config.mode);
             const settingsRoot = strategy.getSettingsRoot();
@@ -111,9 +116,10 @@ async function _createCanopyServicesInternal(config, options) {
             });
             return settingsRoot;
         });
+    const getSettingsBranchRoot = () => timeRequestPhase('settingsRoot', ensureSettingsBranchRoot);
     const contentAccessDeps = {
         checkBranchAccess,
-        loadPathPermissions,
+        loadPathPermissions: (repoRoot, mode) => timeRequestPhase('permissions', () => loadPathPermissions(repoRoot, mode)),
         defaultPathAccess: config.defaultPathAccess ?? 'deny',
         mode: config.mode,
         getSettingsBranchRoot,
@@ -137,8 +143,13 @@ async function _createCanopyServicesInternal(config, options) {
             name: config.gitBotAuthorName,
             email: config.gitBotAuthorEmail,
         });
-        await git.add(options.files);
-        await git.commit(options.message);
+        // [SYNC-C1] Unlocked, a commit made while a rebase is stopped on a conflict
+        // lands on its detached head with the rebase's half-resolved index, and the
+        // rebase's `--abort` discards it.
+        await withContentWriteLock(options.context.branchRoot, async () => {
+            await git.add(options.files);
+            await git.commit(options.message);
+        });
     };
     const submitBranch = async (options) => {
         // Defense-in-depth: refuse to push the base branch to itself even if the
@@ -156,23 +167,53 @@ async function _createCanopyServicesInternal(config, options) {
             name: config.gitBotAuthorName,
             email: config.gitBotAuthorEmail,
         });
-        await git.checkoutBranch(options.context.branch.name);
-        const status = await git.status();
-        // Commit and push answer two DIFFERENT questions. Committing cleans the
-        // working tree, so one combined "tree is dirty" gate makes a retry after a
-        // failed push a silent no-op: nothing left to commit, the block is skipped,
-        // and success is reported though the commit never reached the remote. Push
-        // whenever there is something new to send — we just committed, or the local
-        // branch already had unpushed commits from an earlier attempt.
-        let committed = false;
-        if (status.files.length > 0) {
-            await git.add('.');
-            await git.commit(options.message ?? `Submit ${options.context.branch.name}`);
-            committed = true;
+        // [SYNC-C1] Commits the whole working tree, so it holds the branch's
+        // content-write lock from checkout through push. Unlocked, its checkout
+        // succeeds while the worker's rebase is stopped on a conflict, the commit
+        // lands on the branch, and the rebase's `--abort` resets the branch past it
+        // after this reported success. The push stays inside so no rebase rewrites
+        // the commit between commit and push.
+        const submitted = await withContentWriteLock(options.context.branchRoot, async () => {
+            await git.checkoutBranch(options.context.branch.name);
+            const status = await git.status();
+            // Commit and push answer two DIFFERENT questions. Committing cleans the
+            // working tree, so one combined "tree is dirty" gate makes a retry after a
+            // failed push a silent no-op: nothing left to commit, the block is skipped,
+            // and success is reported though the commit never reached the remote. Push
+            // whenever there is something new to send — we just committed, or the local
+            // branch already had unpushed commits from an earlier attempt.
+            // canopycms's own state under .canopy-meta/ is never content, so it neither
+            // makes a commit worth creating nor gets staged into one.
+            let committed = false;
+            if (status.files.some((f) => !isCanopyInternalPath(f.path))) {
+                await git.addAllExceptCanopyState();
+                const trailers = buildEditorTrailers(options.submitter ? [options.submitter] : [], {
+                    editedBy: config.gitEditedByTrailers ?? true,
+                    coAuthoredBy: config.gitCoAuthoredByTrailers ?? false,
+                });
+                await git.commit(appendTrailers(options.message ?? `Submit ${options.context.branch.name}`, trailers));
+                committed = true;
+            }
+            if (committed || (await git.hasUnpushedCommits(options.context.branch.name))) {
+                await git.push(options.context.branch.name);
+            }
+            return status;
+        });
+        // The list only feeds the PR body, so a failure to compute it falls back to
+        // this submit's own working-tree changes rather than failing a submit that
+        // has already been pushed.
+        let changedPaths;
+        try {
+            changedPaths = await git.listChangedPathsSinceBase();
         }
-        if (committed || (await git.hasUnpushedCommits(options.context.branch.name))) {
-            await git.push(options.context.branch.name);
+        catch (err) {
+            console.warn(`CanopyCMS: Could not list the changes on ${options.context.branch.name} against its base; ` +
+                "the PR body lists only this submit's changes:", redactCredentials(getErrorMessage(err)));
+            changedPaths = submitted.files.map((f) => f.path);
         }
+        return {
+            changedPaths: changedPaths.filter((p) => !p.startsWith(`${BRANCH_META_DIR}/`)),
+        };
     };
     // Must be initialized before closures that reference it (commitToSettingsBranch)
     let githubService;
@@ -233,57 +274,31 @@ async function _createCanopyServicesInternal(config, options) {
                     error: error instanceof Error ? error.message : 'Push failed',
                 };
             }
-            // Create or update PR — dual-path like content branches (api/github-sync.ts)
-            if (options.createPR !== false) {
-                // Permissions and groups are read live from the settings workspace
-                // (getSettingsBranchRoot), never from this PR's base branch, so the
-                // change took effect when it was committed and pushed above, before
-                // this PR existed. Merging re-activates nothing; it only records the
-                // change on `base` for review and audit history.
-                const settingsPRBody = 'Automated PR for permission and group changes. These changes already took ' +
-                    'effect in the CMS when they were saved — merging this PR does not change ' +
-                    "what's live; it only records the change here for review and audit history.";
-                // Direct path: githubService available (has internet)
-                if (githubService) {
-                    let prUrl;
-                    try {
-                        // Settings-branch PRs never pass markReadyIfDraft: a settings sync
-                        // has no explicit "submit for review" step the way a content submit
-                        // does, so an existing draft PR stays draft until an admin says so.
-                        const result = await githubService.createOrUpdatePR({
-                            head: settingsBranch,
-                            base: config.defaultBaseBranch ?? 'main',
-                            title: 'Update permissions and groups',
-                            body: settingsPRBody,
-                        });
-                        prUrl = result.url;
-                    }
-                    catch (err) {
-                        console.warn('Failed to create/update PR:', err);
-                        return { committed: true, pushed: true, syncStatus: 'sync-failed' };
-                    }
-                    return { committed: true, pushed: true, prUrl, syncStatus: 'synced' };
-                }
-                // Async path: queue task for worker (prod Lambda has no internet)
-                const taskDir = getTaskQueueDir(config);
-                try {
-                    await enqueueTask(taskDir, {
-                        action: 'push-and-create-or-update-pr',
-                        payload: {
-                            branch: settingsBranch,
-                            baseBranch: config.defaultBaseBranch ?? 'main',
-                            title: 'Update permissions and groups',
-                            body: settingsPRBody,
-                        },
-                    });
-                    return { committed: true, pushed: true, syncStatus: 'pending-sync' };
-                }
-                catch (err) {
-                    console.warn('Failed to enqueue settings PR task:', err);
-                    return { committed: true, pushed: true, syncStatus: 'sync-failed' };
-                }
+            // The settings branch is an orphan: it shares no history with the base
+            // branch, so GitHub rejects a PR for it. The change took effect when it
+            // was committed and pushed above (permissions and groups are read live
+            // from the settings workspace); the only GitHub step is mirroring the
+            // branch, so there is never a PR.
+            if (!operatingStrategy(mode).supportsPullRequests()) {
+                return { committed: true, pushed: true };
+            }
+            // With a githubService the push above already reached GitHub: both it and
+            // the workspace remote come from `defaultRemoteUrl`. Without one (prod
+            // Lambda has no internet) the worker pushes it.
+            if (githubService) {
+                return { committed: true, pushed: true, syncStatus: 'synced' };
+            }
+            try {
+                await enqueueTask(getTaskQueueDir(config), {
+                    action: 'push-branch',
+                    payload: { branch: settingsBranch },
+                });
+                return { committed: true, pushed: true, syncStatus: 'pending-sync' };
+            }
+            catch (err) {
+                console.warn('Failed to enqueue settings push task:', err);
+                return { committed: true, pushed: true, syncStatus: 'sync-failed' };
             }
-            return { committed: true, pushed: true };
         }
         catch (error) {
             return {

package/dist/settings-workspace.js

@@ -9,6 +9,36 @@ const log = createDebugLogger({ prefix: 'SettingsWorkspace' });
 // In-memory lock against concurrent init within one process. One lock suffices,
 // unlike content branches, which need one per branch.
 let settingsInitLock = null;
+/**
+ * Settings workspaces this process has fully ensured, keyed by {@link ensuredKey}. A hit
+ * skips the guard, the init lock and initializeWorkspace's dozen git subprocesses, which
+ * otherwise ran on every API request. It is sound because settings freshness never comes from
+ * that pass: it reads the remote only to provision the settings branch or repair an empty one
+ * (GitManager.createOrphanSettingsBranch), saves pull, and every process reads the one shared
+ * workspace. Everything it verified is fixed for the process: the settings-branch name resolves once
+ * from config, the remote URL comes from config, and nothing in CanopyCMS checks the settings
+ * workspace out onto another branch. groups.json and permissions.json are still read from
+ * disk on every request; only the provisioning is memoized. Failures are never recorded. In
+ * dev, a hit also skips re-seeding a deleted `.canopy-dev/remote.git`; a dev-server restart
+ * re-seeds it.
+ *
+ * A hit still reads `.git/HEAD`, so a workspace removed, re-cloned onto another branch, or
+ * caught mid-clone by another process (HEAD still on the base branch) misses and runs the full
+ * path, guard and lock included.
+ */
+const ensuredSettingsWorkspaces = new Set();
+function ensuredKey(options) {
+    return `${path.resolve(options.settingsRoot)}\0${options.branchName}`;
+}
+async function checkedOutOn(settingsRoot, branchName) {
+    try {
+        const head = await fs.readFile(path.join(settingsRoot, '.git', 'HEAD'), 'utf-8');
+        return head.trim() === `ref: refs/heads/${branchName}`;
+    }
+    catch {
+        return false;
+    }
+}
 const SETTINGS_INIT_LOCK_DIR = '.settings-init';
 const SETTINGS_INIT_LOCK_NAME = 'lock';
 /**
@@ -54,8 +84,8 @@ async function settingsFilesPresent(settingsRoot) {
  * branch name.
  *
  * Without it, GitManager.initializeWorkspace sees an existing .git, skips the
- * clone, and calls createOrphanSettingsBranch(branchName); for an unknown name
- * git then runs `checkout --orphan <name>` + `rm -rf .` + an empty commit.
+ * clone, and calls createOrphanSettingsBranch(branchName); for a name neither the
+ * workspace nor its remote has, git then runs `checkout --orphan <name>` + `rm -rf .` + an empty commit.
  * Orphan branches share no history, so that is not a migration — it
  * PERMANENTLY WIPES permissions.json/groups.json with nothing to recover from.
  * The trigger is almost always deploymentName / settingsBranch /
@@ -103,8 +133,9 @@ async function assertSettingsWorkspaceIdentity(options) {
             `deploymentName, settingsBranch, or CANOPYCMS_DEPLOYMENT_NAME changed on a ` +
             `deployment that already has a populated settings workspace. To resolve: restore ` +
             `the previous value so this resolves back to ` +
-            `'${currentBranch ?? options.branchName}', or, if starting fresh is genuinely ` +
-            `intended, move ${options.settingsRoot} aside manually first.`);
+            `'${currentBranch ?? options.branchName}', or, if switching is genuinely intended, ` +
+            `move ${options.settingsRoot} aside manually first: the next start checks out ` +
+            `'${options.branchName}' from the remote, or starts it empty if the remote has none.`);
     }
 }
 /**
@@ -122,6 +153,12 @@ export class SettingsWorkspaceManager {
         this.config = config;
     }
     async ensureGitWorkspace(options) {
+        const key = ensuredKey(options);
+        if (ensuredSettingsWorkspaces.has(key)) {
+            if (await checkedOutOn(options.settingsRoot, options.branchName))
+                return;
+            ensuredSettingsWorkspaces.delete(key);
+        }
         return log.timed('workspace', 'ensureGitWorkspace', async () => {
             // Layer 1: In-memory lock (prevents redundant async calls within same process)
             if (settingsInitLock) {
@@ -170,6 +207,7 @@ export class SettingsWorkspaceManager {
                             gitBotAuthorName: this.config.gitBotAuthorName,
                             gitBotAuthorEmail: this.config.gitBotAuthorEmail,
                         });
+                        ensuredSettingsWorkspaces.add(key);
                     }
                     finally {
                         try {