canopycms 0.0.67-int.90 → 0.0.67

package/dist/services.js

@@ -7,18 +7,15 @@ import { getDefaultBranchBase, sanitizeBranchName } from './paths/index.js';
 import { createGitHubService } from './github-service.js';
 import { operatingStrategy } from './operating-mode/index.js';
 import { BranchSchemaCache } from './branch-schema-cache.js';
-import { enqueueTask } from './worker/task-queue.js';
-import { getTaskQueueDir } from './worker/task-queue-config.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 { readsFromCheckout } from './build-mode.js';
 /**
- * Create a per-instance active branch detector with its own 5-second TTL cache.
- *
- * Detection priority:
- * - If explicitly configured, use that value (both modes).
- * - Static deployments and builds read the checkout: defaultBaseBranch ?? 'main', no git.
- * - In dev mode, auto-detect from the current git HEAD branch.
- * - In prod mode, fall back to defaultBaseBranch ?? 'main'.
+ * A per-instance active-branch detector with its own 5s TTL cache, in priority
+ * order: an explicitly configured value; `defaultBaseBranch ?? 'main'` with no
+ * git for static deployments and builds; git HEAD in dev; and
+ * `defaultBaseBranch ?? 'main'` in prod.
  */
 function createActiveBranchDetector() {
     let cache = null;
@@ -33,10 +30,9 @@ function createActiveBranchDetector() {
             if (cache && now < cache.expiresAt) {
                 return cache.value;
             }
-            // Always use cwd for branch detection — git walks up to find .git.
-            // sourceRoot is about content location, not the repo root.
-            // On detached HEAD or no git repo, detectHeadBranch returns the
-            // base-branch fallback instead of throwing.
+            // Detect from cwd, never sourceRoot: git walks up to find .git, and
+            // sourceRoot locates content, not the repo root. On a detached HEAD or
+            // outside a repo, detectHeadBranch falls back instead of throwing.
             const branch = await detectHeadBranch(process.cwd(), config.defaultBaseBranch ?? 'main');
             cache = { value: branch, expiresAt: now + 5000 };
             return branch;
@@ -45,8 +41,8 @@ function createActiveBranchDetector() {
     };
 }
 /**
- * Parse bootstrap admin IDs from environment variable.
- * These users are always treated as Admins regardless of group membership.
+ * Bootstrap admin IDs from the environment. These users are treated as Admins
+ * whatever their group membership.
  */
 export const getBootstrapAdminIds = () => {
     const envVar = process.env.CANOPY_BOOTSTRAP_ADMIN_IDS;
@@ -58,28 +54,17 @@ export const getBootstrapAdminIds = () => {
         .filter(Boolean));
 };
 /**
- * Create reusable helpers from a validated CanopyConfig.
- * Intended to be called once at startup and injected where needed
- * (e.g., request handlers, loaders).
- *
- * Schema is now loaded per-branch via BranchSchemaCache, not at startup.
- *
- * @param config - Validated Canopy configuration
- * @param options - Optional settings including entry schema registry
+ * Build the reusable helpers from a validated CanopyConfig — once at startup,
+ * then injected into request handlers and loaders. Schema is not loaded here;
+ * BranchSchemaCache loads it per branch.
  */
 export const createCanopyServices = async (config, options = {}) => {
     return _createCanopyServicesInternal(config, options);
 };
-/**
- * Create services for testing.
- * Schema is loaded per-branch via BranchSchemaCache.
- *
- * @param config - Validated Canopy configuration
- * @param options - Optional settings including entry schema registry
- */
+/** {@link createCanopyServices} for tests, with branch identity pinned. */
 export const createTestCanopyServices = async (config, options = {}) => {
-    // In tests, pin both branch identity fields to avoid auto-detecting from
-    // git HEAD (which varies depending on the developer's working branch).
+    // Pin both branch identity fields rather than auto-detect from git HEAD,
+    // which varies with the developer's working branch.
     const testConfig = {
         ...config,
         defaultBaseBranch: config.defaultBaseBranch ?? 'main',
@@ -87,35 +72,28 @@ export const createTestCanopyServices = async (config, options = {}) => {
     };
     return _createCanopyServicesInternal(testConfig, options);
 };
-/**
- * Internal implementation shared by both production and test functions.
- * Not exported - use createCanopyServices() or createTestCanopyServices().
- */
+/** Shared implementation; call createCanopyServices or createTestCanopyServices. */
 async function _createCanopyServicesInternal(config, options) {
-    // Validate mode-specific requirements (e.g., prod requires git bot credentials for GitHub)
+    // Mode-specific requirements, e.g. prod's git bot credentials for GitHub.
     const strategy = operatingStrategy(config.mode);
     strategy.validateConfig(config);
-    // Resolve branch identity once (see ARCHITECTURE.md "Branch Identity"):
-    // - active branch: which workspace to serve from (dev: git HEAD, prod: base)
-    // - base branch: fork point for new editing branches (dev: git HEAD when
-    //   unset, otherwise the configured value; prod: configured value or 'main')
-    // Bake both into config so all downstream code reads one consistent value.
-    // The detector has its own per-instance 5s TTL cache for git HEAD checks.
+    // Resolve branch identity once and bake both into config, so downstream code
+    // reads one consistent value (see ARCHITECTURE.md "Branch Identity"): the
+    // active branch is the workspace to serve from, the base branch the fork
+    // point for new editing branches.
     const detectActiveBranch = createActiveBranchDetector();
     const explicitActiveBranch = config.defaultActiveBranch;
     const explicitBaseBranch = config.defaultBaseBranch;
     const defaultActiveBranch = await detectActiveBranch(config);
-    // When unset, the base branch follows the same dev-mode HEAD detection
-    // (matching resolveBaseBranch in utils/git.ts, the canonical definition used
-    // by workspace provisioning). Reuses the detector's 5s TTL cache.
+    // Unset, the base branch follows the same dev-mode HEAD detection, matching
+    // resolveBaseBranch in utils/git.ts — the canonical definition workspace
+    // provisioning uses.
     const defaultBaseBranch = explicitBaseBranch ??
         (config.mode === 'dev' && !readsFromCheckout(config)
             ? await detectActiveBranch({ ...config, defaultActiveBranch: undefined })
             : 'main');
     config = { ...config, defaultActiveBranch, defaultBaseBranch };
-    // Load bootstrap admin IDs from environment
     const bootstrapAdminIds = getBootstrapAdminIds();
-    // Create per-branch schema cache (or use provided one for testing)
     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)
@@ -124,8 +102,6 @@ async function _createCanopyServicesInternal(config, options) {
             const strategy = operatingStrategy(config.mode);
             const settingsRoot = strategy.getSettingsRoot();
             const branchName = strategy.getSettingsBranchName(config);
-            // Use SettingsWorkspaceManager to ensure git workspace for settings
-            // This is Lambda-safe because the lock is in-memory per process
             const manager = new SettingsWorkspaceManager(config);
             await manager.ensureGitWorkspace({
                 settingsRoot,
@@ -182,14 +158,12 @@ async function _createCanopyServicesInternal(config, options) {
         });
         await git.checkoutBranch(options.context.branch.name);
         const status = await git.status();
-        // Commit and push are gated on two DIFFERENT questions. Committing
-        // cleans the working tree, so gating the push on "tree is dirty" (as a
-        // single combined check) makes a retry after a failed push a silent
-        // no-op: the earlier commit already cleaned the tree, so the retry sees
-        // nothing to commit, skips the whole block, and reports success even
-        // though the commit never reached the remote. Push instead whenever
-        // there's something new to send -- we just committed, or the local
-        // branch already had unpushed commits from an earlier failed attempt.
+        // 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('.');
@@ -200,7 +174,6 @@ async function _createCanopyServicesInternal(config, options) {
             await git.push(options.context.branch.name);
         }
     };
-    // Create GitHub service if applicable (only for modes that support pull requests)
     // Must be initialized before closures that reference it (commitToSettingsBranch)
     let githubService;
     if (operatingStrategy(config.mode).supportsPullRequests()) {
@@ -220,7 +193,6 @@ async function _createCanopyServicesInternal(config, options) {
     }
     const commitToSettingsBranch = async (options) => {
         const mode = config.mode;
-        // Check if this mode supports git operations
         if (!operatingStrategy(mode).shouldCommit()) {
             return { committed: false, pushed: false };
         }
@@ -228,9 +200,9 @@ async function _createCanopyServicesInternal(config, options) {
         // Settings workspace: no ContentStore roots here, skip the index marker
         const git = createGitManagerFor(options.branchRoot, { skipIndexMarker: true });
         try {
-            // Pull latest changes from remote settings branch (not base branch!)
-            // Settings branches are orphan branches and should never merge from main
-            // Note: BranchWorkspaceManager already ensured we're on the settings branch
+            // Pull the remote SETTINGS branch, never the base branch: settings
+            // branches are orphans and must never merge from main.
+            // BranchWorkspaceManager has already put us on the settings branch.
             try {
                 await git.pullCurrentBranch();
             }
@@ -239,17 +211,11 @@ async function _createCanopyServicesInternal(config, options) {
                 // pushed, so the remote has no ref to pull. Anything else — a
                 // GitConflictError, a merge that cannot proceed, a broken workspace —
                 // must surface (the outer catch turns it into an error result).
-                // A blanket catch here previously logged every failure as "normal for
-                // first commit", which is how pullCurrentBranch could stay broken on
-                // every call without anyone noticing: the settings branch then silently
-                // never converged with the remote, and each save reported
-                // `committed: true, pushed: false` from the push below, forever.
                 if (!(err instanceof GitRemoteRefMissingError))
                     throw err;
                 console.info('CanopyCMS: settings branch has no remote ref yet, nothing to pull ' +
                     '(normal for the first settings commit)');
             }
-            // Commit
             await git.ensureAuthor({
                 name: config.gitBotAuthorName,
                 email: config.gitBotAuthorEmail,
@@ -269,16 +235,11 @@ async function _createCanopyServicesInternal(config, options) {
             }
             // Create or update PR — dual-path like content branches (api/github-sync.ts)
             if (options.createPR !== false) {
-                // Both permissions and groups are read live from the settings
-                // workspace (getSettingsBranchRoot) — never from this PR's base
-                // branch — so the change already took effect the moment it was
-                // committed and pushed above, before this PR even exists. Merging
-                // does not (re-)activate anything; it only records the change on
-                // `base` for review/audit history. Previously worded as "will be
-                // persisted when this PR is merged", which implied merging was what
-                // made the change durable/live — false for both settings files, and
-                // for groups specifically the read side didn't even look at this
-                // branch until that bug was fixed (see resolve-canopy-user.ts).
+                // 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.";
@@ -286,10 +247,9 @@ async function _createCanopyServicesInternal(config, options) {
                 if (githubService) {
                     let prUrl;
                     try {
-                        // Settings-branch PRs deliberately never pass markReadyIfDraft:
-                        // unlike content submits, a settings sync has no explicit "submit
-                        // for review" step, so an existing draft PR here should stay
-                        // draft until an admin is ready — don't "helpfully" enable this.
+                        // 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',
@@ -335,8 +295,6 @@ async function _createCanopyServicesInternal(config, options) {
     };
     const operatingMode = config.mode;
     const modeStrategy = operatingStrategy(operatingMode);
-    // Create branch registry only in branching modes
-    // Settings are now in separate directory, no filtering needed
     const registry = modeStrategy.supportsBranching()
         ? new BranchRegistry(getDefaultBranchBase(operatingMode))
         : undefined;
@@ -361,16 +319,15 @@ async function _createCanopyServicesInternal(config, options) {
             // Static deployments and builds serve from the checkout — no git HEAD to track
             if (readsFromCheckout(services.config))
                 return;
-            // Explicitly configured values are respected — never overridden by
-            // git HEAD detection. Only re-detect what the adopter left unset.
+            // An explicitly configured value is never overridden by HEAD detection;
+            // only what the adopter left unset is re-detected.
             if (explicitActiveBranch && explicitBaseBranch)
                 return;
-            // Re-detect from git HEAD (5s TTL cache prevents excessive shell-outs).
-            // Silently switch — the public dev site should reflect the current branch
-            // just like code hot-reloads. The editor is pinned to its own branch via
-            // URL params, so this only affects non-editor content serving. The base
-            // branch (fork point) follows HEAD too when unset, so workspaces
-            // provisioned mid-session fork from the developer's current branch.
+            // The switch is silent, so the dev site tracks the current branch the way
+            // code hot-reloads; the editor is pinned to its own branch via URL params,
+            // so only non-editor content serving is affected. The base branch follows
+            // HEAD too when unset, so a workspace provisioned mid-session forks from
+            // the developer's current branch.
             const fresh = await detectActiveBranch({
                 ...services.config,
                 defaultActiveBranch: undefined,
@@ -386,11 +343,11 @@ async function _createCanopyServicesInternal(config, options) {
                 changed = true;
             }
             if (changed) {
-                // Note: closures in this function (getSettingsBranchRoot, checkContentAccess,
-                // createGitManagerFor, etc.) capture the original `config` local variable.
-                // Only the branch identity fields change here — git operations on existing
-                // branches use the fork point recorded in branch metadata, and consumers
-                // that need the fresh values must read services.config.
+                // The closures above (getSettingsBranchRoot, checkContentAccess,
+                // createGitManagerFor, …) captured the original `config` local. Only
+                // branch identity changes here: git operations on existing branches use
+                // the fork point in branch metadata, and anything needing the fresh
+                // values must read services.config.
                 services.config = next;
             }
         },

package/dist/settings-workspace.d.ts

@@ -2,24 +2,17 @@ import type { CanopyConfig } from './config/index.js';
 import type { OperatingMode } from './operating-mode/index.js';
 /**
  * Directory the cross-process init lock is anchored on — a dedicated sibling of
- * the settings root, and NOT the settings root itself.
+ * the settings root, NOT the settings root itself.
  *
- * Two properties this name has to satisfy:
- *
- * 1. **It must not pre-create the settings root.** `acquireProvisioningLock`
- *    mkdir's its target, and `GitManager.initializeWorkspace` clones INTO the
- *    settings root — `git clone` refuses a destination that already has content
- *    in it. So the lock lives beside the settings root, never inside it.
- * 2. **Its marker must not collide with another lock's marker.** Since
- *    2026-08-20 `acquireProvisioningLock` anchors proper-lockfile on the lock
- *    MARKER's own path rather than on the directory holding it, so its
- *    in-process registry key is the on-disk lock identity and two live locks
- *    can no longer clobber each other's bookkeeping (see docs/concurrency.md,
- *    "Anchor path matters"). A dedicated dot-directory is still the right home
- *    for this marker: `path.dirname(settingsRoot)` is where
- *    `ensureLocalSimulatedRemote` puts `.remote-init.lock`, and settings init
- *    calls into it while holding this lock, so keeping the two markers in
- *    separate directories keeps that nesting obvious rather than incidental.
+ * It must not pre-create the settings root: `acquireProvisioningLock` mkdir's
+ * its target, and `GitManager.initializeWorkspace` clones INTO the settings
+ * root, which `git clone` refuses if anything is already there. A dedicated
+ * dot-directory also keeps this marker out of `path.dirname(settingsRoot)`,
+ * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — settings init
+ * calls into that while holding this lock, so separate directories make the
+ * nesting obvious rather than incidental. For how a lock's anchor path is
+ * chosen, see utils/provisioning-lock.ts and docs/concurrency.md.
+ * @internal Exported for tests.
  */
 export declare function settingsInitLockTarget(settingsRoot: string): string;
 export interface EnsureSettingsWorkspaceOptions {
@@ -29,20 +22,14 @@ export interface EnsureSettingsWorkspaceOptions {
     remoteUrl?: string;
 }
 /**
- * Manages settings filesystem workspace and git operations.
- *
- * Settings are stored separately from content branches:
- * - prod/dev: Orphan git branches (no shared history with content)
- *
- * Unlike BranchWorkspaceManager, this does not:
- * - Create or manage metadata files
- * - Interact with the branch registry
- * - Check for special cases (settings are always settings)
+ * The settings filesystem workspace and its git operations. Settings live on an
+ * orphan git branch, sharing no history with content, and unlike
+ * BranchWorkspaceManager this writes no metadata files and never touches the
+ * branch registry.
  *
- * Uses two layers of locking, mirroring BranchWorkspaceManager:
- * - In-memory Promise lock for within-process serialization (Lambda request lifecycle)
- * - `acquireProvisioningLock` (proper-lockfile) for cross-process/cross-host
- *   synchronization of the init itself (multiple Lambda containers on EFS)
+ * Two locking layers, mirroring BranchWorkspaceManager: an in-memory promise
+ * lock within the process, and `acquireProvisioningLock` (proper-lockfile)
+ * across processes and hosts.
  */
 export declare class SettingsWorkspaceManager {
     private readonly config;

package/dist/settings-workspace.js

@@ -6,41 +6,34 @@ import { getErrorMessage } from './utils/error.js';
 import { acquireProvisioningLock } from './utils/provisioning-lock.js';
 import { RESERVED_SETTINGS_BRANCH_PREFIX } from './paths/index.js';
 const log = createDebugLogger({ prefix: 'SettingsWorkspace' });
-// In-memory lock to prevent concurrent workspace initialization within the same process.
-// Settings only need one lock (not per-branch like content branches).
+// In-memory lock against concurrent init within one process. One lock suffices,
+// unlike content branches, which need one per branch.
 let settingsInitLock = null;
 const SETTINGS_INIT_LOCK_DIR = '.settings-init';
 const SETTINGS_INIT_LOCK_NAME = 'lock';
 /**
  * Directory the cross-process init lock is anchored on — a dedicated sibling of
- * the settings root, and NOT the settings root itself.
+ * the settings root, NOT the settings root itself.
  *
- * Two properties this name has to satisfy:
- *
- * 1. **It must not pre-create the settings root.** `acquireProvisioningLock`
- *    mkdir's its target, and `GitManager.initializeWorkspace` clones INTO the
- *    settings root — `git clone` refuses a destination that already has content
- *    in it. So the lock lives beside the settings root, never inside it.
- * 2. **Its marker must not collide with another lock's marker.** Since
- *    2026-08-20 `acquireProvisioningLock` anchors proper-lockfile on the lock
- *    MARKER's own path rather than on the directory holding it, so its
- *    in-process registry key is the on-disk lock identity and two live locks
- *    can no longer clobber each other's bookkeeping (see docs/concurrency.md,
- *    "Anchor path matters"). A dedicated dot-directory is still the right home
- *    for this marker: `path.dirname(settingsRoot)` is where
- *    `ensureLocalSimulatedRemote` puts `.remote-init.lock`, and settings init
- *    calls into it while holding this lock, so keeping the two markers in
- *    separate directories keeps that nesting obvious rather than incidental.
+ * It must not pre-create the settings root: `acquireProvisioningLock` mkdir's
+ * its target, and `GitManager.initializeWorkspace` clones INTO the settings
+ * root, which `git clone` refuses if anything is already there. A dedicated
+ * dot-directory also keeps this marker out of `path.dirname(settingsRoot)`,
+ * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — settings init
+ * calls into that while holding this lock, so separate directories make the
+ * nesting obvious rather than incidental. For how a lock's anchor path is
+ * chosen, see utils/provisioning-lock.ts and docs/concurrency.md.
+ * @internal Exported for tests.
  */
 export function settingsInitLockTarget(settingsRoot) {
     return path.join(path.dirname(path.resolve(settingsRoot)), SETTINGS_INIT_LOCK_DIR);
 }
 /**
- * Whether a settings workspace actually holds settings data yet. Used by the
- * rename guard to tell an already-populated workspace (refuse) apart from a
- * clone that was interrupted before its orphan branch was ever created
- * (harmless — let init finish). File names come from the operating-mode
- * strategy so this stays in step with whatever the mode calls them.
+ * Whether a settings workspace holds settings data yet. The rename guard uses
+ * it to tell an already-populated workspace (refuse) from a clone interrupted
+ * before its orphan branch existed (harmless — let init finish). File names
+ * come from the operating-mode strategy so this stays in step with whatever
+ * the mode calls them.
  */
 async function settingsFilesPresent(settingsRoot) {
     const names = ['permissions.json', 'groups.json'];
@@ -56,34 +49,28 @@ async function settingsFilesPresent(settingsRoot) {
     return false;
 }
 /**
- * Rename guard (settings-branch protection). Refuses to boot when an
+ * Rename guard (settings-branch protection): refuse to boot when an
  * ALREADY-POPULATED settings workspace would be re-orphaned under a different
  * branch name.
  *
- * Trace of what happens without it: GitManager.initializeWorkspace sees an
- * existing .git (no clone happens) and goes straight to
- * createOrphanSettingsBranch(branchName). If that name isn't already known, git
- * runs `checkout --orphan <name>` + `rm -rf .` + an empty `--allow-empty`
- * commit — orphan branches share no history, so this isn't a "migration", it
+ * 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.
+ * Orphan branches share no history, so that is not a migration — it
  * PERMANENTLY WIPES permissions.json/groups.json with nothing to recover from.
- * That almost always means deploymentName / settingsBranch /
- * CANOPYCMS_DEPLOYMENT_NAME changed on a live deployment (see
+ * The trigger is almost always deploymentName / settingsBranch /
+ * CANOPYCMS_DEPLOYMENT_NAME changing on a live deployment (see
  * resolveDeploymentName in operating-mode/deployment-name.ts).
  *
- * What this deliberately does NOT refuse, and why it matters:
- * initializeWorkspace clones at the BASE branch and only creates the orphan
- * branch several steps later (addConfig, resolveRemoteUrl, ensureRemote come in
- * between). If that first init is interrupted — a Lambda timeout on a slow EFS
- * clone, an OOM, a spot interruption — it leaves a perfectly valid repo sitting
- * on the base branch with NO settings files in it. Refusing on "branch differs"
- * alone would then brick the deployment permanently on every subsequent boot, to
- * protect data that was never written. So the refusal additionally requires
- * evidence that this really is a populated settings workspace: either it is
- * checked out on some OTHER settings branch, or the settings files are actually
- * on disk.
+ * The refusal therefore needs evidence of a populated workspace — checked out
+ * on some OTHER settings branch, or settings files on disk — not just a
+ * differing branch name. initializeWorkspace clones at the BASE branch and
+ * creates the orphan branch several steps later, so an interrupted first init
+ * (Lambda timeout on a slow EFS clone, OOM, spot interruption) leaves a valid
+ * repo on the base branch with no settings files, and refusing on name alone
+ * would brick that deployment on every boot to protect data never written.
  *
- * This function is NEVER gated on holding the init lock — see its two call
- * sites in ensureGitWorkspace and the comment there.
+ * NEVER gated on holding the init lock — see its two call sites below.
  */
 async function assertSettingsWorkspaceIdentity(options) {
     const repoExists = await GitManager.repoExistsAt(options.settingsRoot);
@@ -121,20 +108,14 @@ async function assertSettingsWorkspaceIdentity(options) {
     }
 }
 /**
- * Manages settings filesystem workspace and git operations.
- *
- * Settings are stored separately from content branches:
- * - prod/dev: Orphan git branches (no shared history with content)
- *
- * Unlike BranchWorkspaceManager, this does not:
- * - Create or manage metadata files
- * - Interact with the branch registry
- * - Check for special cases (settings are always settings)
+ * The settings filesystem workspace and its git operations. Settings live on an
+ * orphan git branch, sharing no history with content, and unlike
+ * BranchWorkspaceManager this writes no metadata files and never touches the
+ * branch registry.
  *
- * Uses two layers of locking, mirroring BranchWorkspaceManager:
- * - In-memory Promise lock for within-process serialization (Lambda request lifecycle)
- * - `acquireProvisioningLock` (proper-lockfile) for cross-process/cross-host
- *   synchronization of the init itself (multiple Lambda containers on EFS)
+ * Two locking layers, mirroring BranchWorkspaceManager: an in-memory promise
+ * lock within the process, and `acquireProvisioningLock` (proper-lockfile)
+ * across processes and hosts.
  */
 export class SettingsWorkspaceManager {
     constructor(config) {
@@ -147,7 +128,6 @@ export class SettingsWorkspaceManager {
                 await settingsInitLock;
                 return;
             }
-            // Create new in-memory lock promise
             settingsInitLock = (async () => {
                 try {
                     log.debug('workspace', 'Ensuring settings git workspace', {
@@ -156,34 +136,26 @@ export class SettingsWorkspaceManager {
                     });
                     // Rename guard, run LOCK-FREE and unconditionally, before any waiting.
                     // A deployment whose settings-branch name no longer matches the
-                    // workspace on disk is misconfigured, not contended: it must refuse
-                    // immediately rather than queue behind a live provisioner for what can
-                    // be minutes. Running it here also keeps the guarantee the guard has
-                    // always had — no code path reaches initializeWorkspace without it
-                    // having run in THIS process.
+                    // workspace on disk is misconfigured, not contended, so it must refuse
+                    // immediately rather than queue behind a live provisioner for minutes.
+                    // Running it here also means no path reaches initializeWorkspace
+                    // without the guard having run in THIS process.
                     await assertSettingsWorkspaceIdentity(options);
                     // Layer 2: cross-process/cross-host lock around the init itself
                     // (proper-lockfile: heartbeat-refreshed while the holder lives, so a
                     // slow EFS clone is not mistaken for a crash, and patient retries so a
                     // loser WAITS instead of racing into a concurrent clone).
-                    //
-                    // This replaced a bespoke O_CREAT|O_EXCL + 30s-mtime scheme whose
-                    // return value was only ever used to decide whether to release: the
-                    // loser proceeded into initializeWorkspace anyway, concurrently with
-                    // the holder, where it could see a half-written .git, classify it
-                    // corrupt, and `rm -rf` it out from under the in-flight clone.
                     const releaseLock = await acquireProvisioningLock(settingsInitLockTarget(options.settingsRoot), SETTINGS_INIT_LOCK_NAME);
                     try {
-                        // Re-run the guard on the now-stable state. If we waited above, the
-                        // previous holder may have created the workspace (or moved it onto
-                        // its own settings branch) after we sampled it, and acting on that
-                        // stale sample is exactly the destructive path the guard exists to
-                        // stop. Still not gated on any "did I win the race" flag — there is
-                        // no such flag by design; every process either holds the lock here
-                        // or has already thrown.
+                        // Re-run the guard on the now-stable state: a previous holder may
+                        // have created the workspace, or moved it onto its own settings
+                        // branch, after we sampled it above, and acting on that stale
+                        // sample is the destructive path the guard exists to stop. Not
+                        // gated on any "did I win the race" flag — by design there is none;
+                        // every process here either holds the lock or has already thrown.
                         await assertSettingsWorkspaceIdentity(options);
-                        // GitManager.initializeWorkspace is idempotent (checks for .git),
-                        // so it's safe to call even if another process just finished init.
+                        // initializeWorkspace is idempotent (it checks for .git), so this
+                        // is safe even if another process just finished init.
                         await GitManager.initializeWorkspace({
                             workspacePath: options.settingsRoot,
                             branchName: options.branchName,
@@ -209,11 +181,9 @@ export class SettingsWorkspaceManager {
                     }
                 }
                 finally {
-                    // Always clean up the in-memory lock when done (success or failure)
                     settingsInitLock = null;
                 }
             })();
-            // Wait for initialization to complete
             await settingsInitLock;
         });
     }