canopycms 0.0.67 → 0.0.68-int.94

package/dist/cli/generate-ai-content.js

@@ -89,6 +89,9 @@ function createLogicalPath(...segments) {
   }
   return normalized;
 }
+function entryLogicalPath(collectionLogicalPath, slug) {
+  return collectionLogicalPath ? `${collectionLogicalPath}/${slug}` : slug;
+}
 function trimSlashes(path22) {
   let start = 0;
   let end = path22.length;
@@ -310,7 +313,8 @@ var init_field = __esm({
     });
     objectFieldSchema = fieldBaseSchema.extend({
       type: z2.literal("object"),
-      fields: z2.array(z2.lazy(() => fieldHolder[0])).min(1)
+      fields: z2.array(z2.lazy(() => fieldHolder[0])).min(1),
+      itemTitleField: z2.string().min(1).optional()
     });
     inlineGroupFieldSchema = z2.object({
       type: z2.literal("group"),
@@ -375,7 +379,7 @@ var init_collection = __esm({
 
 // dist/config/schemas/url.js
 import { z as z4 } from "zod";
-var uploadTargetUrlSchema, assetMountUrlSchema;
+var uploadTargetUrlSchema, assetMountUrlSchema, previewPrefixSchema;
 var init_url = __esm({
   "dist/config/schemas/url.js"() {
     "use strict";
@@ -386,6 +390,9 @@ var init_url = __esm({
     assetMountUrlSchema = z4.string().trim().refine((value) => isHttpUrlOrSameOriginPath(value, { allowProtocolRelative: true }), {
       message: 'must be an absolute http(s) URL, a protocol-relative "//host" URL, or a site-relative path beginning with a single "/", with no query or fragment'
     });
+    previewPrefixSchema = z4.string().trim().refine((value) => isHttpUrlOrSameOriginPath(value), {
+      message: 'editor.previewPrefix must be an absolute http(s) URL or a site-relative path beginning with a single "/", with no query or fragment'
+    });
   }
 });
 
@@ -443,6 +450,7 @@ var init_config = __esm({
     "use strict";
     init_collection();
     init_media();
+    init_url();
     defaultBranchAccessSchema = z6.enum(["allow", "deny"]).default("deny");
     defaultPathAccessLevelSchema = z6.enum(["allow", "deny"]);
     defaultPathAccessLevelsSchema = z6.object({
@@ -474,6 +482,7 @@ var init_config = __esm({
       subtitle: z6.string().optional(),
       theme: z6.unknown().optional(),
       previewBase: z6.record(z6.string()).optional(),
+      previewPrefix: previewPrefixSchema.optional(),
       // UI handler functions (runtime only, don't serialize)
       onAccountClick: z6.function().returns(z6.void()).optional(),
       onLogoutClick: z6.function().returns(z6.void()).optional(),
@@ -501,6 +510,9 @@ var init_config = __esm({
       defaultRemoteUrl: defaultRemoteUrlSchema.optional(),
       gitBotAuthorName: gitBotAuthorNameSchema,
       gitBotAuthorEmail: gitBotAuthorEmailSchema,
+      // Unset reads as on for Edited-by and off for Co-authored-by (services.ts submitBranch).
+      gitEditedByTrailers: z6.boolean().optional(),
+      gitCoAuthoredByTrailers: z6.boolean().optional(),
       githubTokenEnvVar: githubTokenEnvVarSchema.optional(),
       // Required by design (follow-up to SEC-C1): a prod deploy that omits `mode` must fail
       // validation loudly rather than silently running header-trusting dev auth semantics.
@@ -512,7 +524,6 @@ var init_config = __esm({
       // Default false/unset — the standard AWS Lambda+worker topology must leave this unset.
       allowNetworkRemoteInProd: z6.boolean().optional(),
       settingsBranch: z6.string().optional(),
-      autoCreateSettingsPR: z6.boolean().optional(),
       // `.optional()`, NOT bare `deploymentNameSchema`: its own `.default('prod')` would make
       // `parse(undefined)` resolve to 'prod' instead of staying `undefined`, collapsing the
       // env > config > modeDefault precedence chain `resolveDeploymentName`
@@ -835,9 +846,6 @@ var init_client_unsafe_strategy = __esm({
           throw new Error("gitBotAuthorName and gitBotAuthorEmail are required in prod mode");
         }
       }
-      shouldCreateSettingsPR(config) {
-        return config.autoCreateSettingsPR ?? true;
-      }
     };
     DevStrategy = class extends DevClientSafeStrategy {
       getWorkspaceRoot(sourceRoot) {
@@ -884,9 +892,6 @@ var init_client_unsafe_strategy = __esm({
       }
       validateConfig(_config) {
       }
-      shouldCreateSettingsPR(_config) {
-        return false;
-      }
     };
     strategyCache = /* @__PURE__ */ new Map();
   }
@@ -1193,12 +1198,15 @@ import fs2 from "node:fs/promises";
 import path2 from "node:path";
 import lockfile from "proper-lockfile";
 init_logger();
-function provisioningLockOptions(lockPath, retries, onCompromised) {
+var PROVISIONING_LOCK_STALE_MS = 9e4;
+function provisioningLockOptions(lockPath, retries, onCompromised, staleMs) {
   return {
     lockfilePath: lockPath,
     realpath: false,
     retries,
-    stale: 3e4,
+    stale: staleMs,
+    // Fixed, not stale/2: every holder refreshes at 15s whatever threshold it judges others by.
+    update: 15e3,
     // proper-lockfile invokes this from inside its refresh timer, so ANY throw escaping here is
     // an uncaught exception that kills the process. Call sites are told not to throw (see
     // OnLockCompromised); this makes it structural rather than a convention, and also covers the
@@ -1234,16 +1242,19 @@ function releaseIgnoringAlreadyReleased(release, lockPath) {
     }
   };
 }
+function branchProvisioningLockName(dirName) {
+  return `.${dirName}.init.lock`;
+}
 async function acquireProvisioningLock(lockTargetDir2, lockName, onCompromised) {
   await fs2.mkdir(lockTargetDir2, { recursive: true });
   const lockPath = path2.join(lockTargetDir2, lockName);
-  const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised));
+  const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised, PROVISIONING_LOCK_STALE_MS));
   return releaseIgnoringAlreadyReleased(release, lockPath);
 }
-async function tryAcquireProvisioningLock(lockTargetDir2, lockName, onCompromised) {
+async function tryAcquireProvisioningLock(lockTargetDir2, lockName, onCompromised, staleMs = PROVISIONING_LOCK_STALE_MS) {
   await fs2.mkdir(lockTargetDir2, { recursive: true });
   const lockPath = path2.join(lockTargetDir2, lockName);
-  const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised));
+  const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised, staleMs));
   return releaseIgnoringAlreadyReleased(release, lockPath);
 }
 
@@ -1252,8 +1263,9 @@ var META_DIR = ".canopy-meta";
 var CONTENT_WRITE_LOCK_NAME = "content-write.lock";
 var DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2e3;
 var ContentWriteLockBusyError = class extends Error {
-  constructor(message = "This branch is busy (syncing with the base branch, or another save is in flight); the change was not saved. Try again in a moment.") {
+  constructor(message = "This branch is busy (syncing with the base branch, or another save is in flight); the change was not saved. Try again in a moment.", outcome = "not-run") {
     super(message);
+    this.outcome = outcome;
     this.name = "ContentWriteLockBusyError";
   }
 };
@@ -1263,8 +1275,9 @@ function lockTargetDir(branchRoot) {
 var sleep = (ms) => new Promise((resolve2) => {
   setTimeout(resolve2, ms);
 });
+var CONTENT_WRITE_LOCK_STALE_MS = 3e4;
 function tryAcquireContentWriteLock(branchRoot, onCompromised) {
-  return tryAcquireProvisioningLock(lockTargetDir(branchRoot), CONTENT_WRITE_LOCK_NAME, onCompromised);
+  return tryAcquireProvisioningLock(lockTargetDir(branchRoot), CONTENT_WRITE_LOCK_NAME, onCompromised, CONTENT_WRITE_LOCK_STALE_MS);
 }
 async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, onCompromised) {
   const startedAt = Date.now();
@@ -1295,7 +1308,7 @@ async function withContentWriteLock(branchRoot, fn, waitMs = DEFAULT_CONTENT_WRI
     await release();
   }
   if (compromised) {
-    throw new ContentWriteLockBusyError("This branch was being synced while your change was written, so the change may or may not have been recorded. Reload the entry to see the current state before saving again.");
+    throw new ContentWriteLockBusyError("This branch was being synced while your change was written, so the change may or may not have been recorded. Reload the entry to see the current state before saving again.", "unknown");
   }
   return result;
 }
@@ -1345,8 +1358,21 @@ function buildResolvedReference(data, meta, body) {
   resolved.slug = meta.slug;
   resolved.collection = meta.collection;
   resolved.urlPath = meta.urlPath;
+  delete resolved[RESTRICTED_REFERENCE_MARKER];
   return resolved;
 }
+var RESTRICTED_REFERENCE_MARKER = "unavailable";
+function buildRestrictedReference(meta, title) {
+  return {
+    id: meta.id,
+    slug: meta.slug,
+    collection: meta.collection,
+    urlPath: meta.urlPath,
+    title,
+    unavailable: true,
+    reason: "restricted"
+  };
+}
 var SEO_GROUP_FIELDS = [
   {
     name: DEFAULT_SEO_FIELD_NAMES.title,
@@ -1399,6 +1425,50 @@ var SEO_GROUP_FIELDS = [
   }
 ];
 
+// dist/utils/title-field.js
+function isGroupField(field) {
+  return field.type === "group";
+}
+function extractTitleFromSchema(fields, data) {
+  return findTitleValue(fields, data);
+}
+function findTitleValue(fields, data) {
+  for (const field of fields) {
+    if (isGroupField(field)) {
+      const result = findTitleValue(field.fields, data);
+      if (result !== void 0)
+        return result;
+    } else if ("isTitle" in field && field.isTitle) {
+      const value = data[field.name];
+      return typeof value === "string" ? value : void 0;
+    } else if (field.type === "object" && "fields" in field && field.fields && !field.list) {
+      const nested = data[field.name];
+      if (nested != null && typeof nested === "object" && !Array.isArray(nested)) {
+        const result = findTitleValue(field.fields, nested);
+        if (result !== void 0)
+          return result;
+      }
+    }
+  }
+  return void 0;
+}
+function humanizeSlug(slug) {
+  return slug.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()).trim();
+}
+function resolveEntryTitle(data, options) {
+  if (options?.schema) {
+    const schemaTitle = extractTitleFromSchema(options.schema, data);
+    if (schemaTitle)
+      return schemaTitle;
+  }
+  const title = data.title ?? data.name;
+  if (typeof title === "string")
+    return title;
+  if (options?.entryTypeLabel)
+    return options.entryTypeLabel;
+  return options?.slug ? humanizeSlug(options.slug) : "Untitled";
+}
+
 // dist/utils/entry-url.js
 init_normalize();
 function isIndexSlug(slug) {
@@ -2048,6 +2118,10 @@ var DebugLogger = class {
       throw new Error(errorMsg);
     }
   }
+  /**
+   * Keyed by label alone, so two overlapping timers with one label overwrite each other;
+   * anything that can run concurrently uses {@link timed}.
+   */
   time(label) {
     this.timers.set(label, Date.now());
   }
@@ -2062,12 +2136,16 @@ var DebugLogger = class {
     this.debug(category, `${label} completed`, { durationMs: duration });
     return duration;
   }
+  /**
+   * Log `<label> completed {durationMs}` once `fn` settles. The start time is local to the
+   * call, so concurrent spans with the same label on one logger never overwrite each other.
+   */
   async timed(category, label, fn) {
-    this.time(label);
+    const start = Date.now();
     try {
       return await fn();
     } finally {
-      this.timeEnd(category, label);
+      this.debug(category, `${label} completed`, { durationMs: Date.now() - start });
     }
   }
 };
@@ -2393,9 +2471,80 @@ var STATIC_DEPLOY_USER = Object.freeze({
   name: "Static Deploy"
 });
 
+// dist/utils/request-timing.js
+import { AsyncLocalStorage } from "node:async_hooks";
+var storage = new AsyncLocalStorage();
+var log2 = createDebugLogger({ prefix: "CanopyCMS" });
+async function timeRequestPhase(phase, fn) {
+  const parent = storage.getStore();
+  if (!parent)
+    return fn();
+  const key = parent.path ? `${parent.path}>${phase}` : phase;
+  let total = parent.phases.get(key);
+  if (!total) {
+    total = { count: 0, ms: 0 };
+    parent.phases.set(key, total);
+  }
+  const start = performance.now();
+  try {
+    return await storage.run({ ...parent, path: key }, fn);
+  } finally {
+    total.count += 1;
+    total.ms += performance.now() - start;
+  }
+}
+
+// dist/utils/git.js
+import { simpleGit } from "simple-git";
+var NETWORK_SCHEME_PATTERN = /^(https?|ssh|git):\/\//i;
+var TRANSPORT_HELPER_PATTERN = /^[a-z][a-z0-9+.-]*::/i;
+var LEADING_OPTION_PATTERN = /^-/;
+var WINDOWS_DRIVE_PATTERN = /^[a-zA-Z]:[\\/]/;
+var COLON_BEFORE_SLASH_PATTERN = /^[^/\\\s]+:/;
+function isNetworkRemoteUrl(url) {
+  if (/^file:\/\//i.test(url))
+    return false;
+  if (NETWORK_SCHEME_PATTERN.test(url))
+    return true;
+  if (TRANSPORT_HELPER_PATTERN.test(url))
+    return true;
+  if (LEADING_OPTION_PATTERN.test(url))
+    return true;
+  if (WINDOWS_DRIVE_PATTERN.test(url))
+    return false;
+  return COLON_BEFORE_SLASH_PATTERN.test(url);
+}
+var MISSING_REMOTE_REF_REASONS = ["couldn't find remote ref", "Couldn't find remote ref"];
+function isMissingRemoteRefFailure(message) {
+  return MISSING_REMOTE_REF_REASONS.some((reason) => message.includes(reason));
+}
+var CANOPY_META_DIR = ".canopy-meta";
+async function stageAllExceptCanopyState(git) {
+  await git.add(["-A"]);
+  await git.raw(["reset", "-q", "--", CANOPY_META_DIR]);
+}
+async function detectHeadBranch(repoRoot, fallback = "main") {
+  try {
+    const git = simpleGit({ baseDir: repoRoot });
+    const head = (await git.revparse(["--abbrev-ref", "HEAD"])).trim();
+    return head && head !== "HEAD" ? head : fallback;
+  } catch {
+    return fallback;
+  }
+}
+async function resolveBaseBranch(options) {
+  if (options.defaultBaseBranch)
+    return options.defaultBaseBranch;
+  if (options.mode === "dev") {
+    return detectHeadBranch(options.detectFrom ?? process.cwd());
+  }
+  return "main";
+}
+
 // dist/branch-schema-cache.js
 var SCHEMA_CACHE_VERSION = 3;
 var MTIME_CHECK_DEBOUNCE_MS = 1e3;
+var SCHEMA_CACHE_FILE = "schema-cache.json";
 var SCHEMA_GENERATION_RESOURCE = "schema";
 async function isStaleByMtime(dir, cachedAt) {
   let entries;
@@ -2418,6 +2567,11 @@ async function isStaleByMtime(dir, cachedAt) {
   }
   return false;
 }
+async function schemaCacheDir(branchRoot) {
+  const gitDir = path8.join(branchRoot, ".git");
+  const isClone = await fs7.stat(gitDir).then((stat) => stat.isDirectory(), () => false);
+  return isClone ? path8.join(gitDir, "canopycms") : path8.join(branchRoot, CANOPY_META_DIR);
+}
 var BranchSchemaCache = class {
   constructor(mode = "prod") {
     this.lastMtimeCheck = /* @__PURE__ */ new Map();
@@ -2426,7 +2580,7 @@ var BranchSchemaCache = class {
   /**
    * Whether to skip the on-disk cache for this branchRoot.
    *
-   * Never write `.canopy-meta/` at the project root, whichever entrypoint
+   * Never write a schema cache at the project root, whichever entrypoint
    * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
    * synthetic contexts static deployments and build phases use; a real branch
    * root is always nested under the workspace.
@@ -2436,7 +2590,7 @@ var BranchSchemaCache = class {
   }
   /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
   async getSchema(branchRoot, entrySchemaRegistry, contentRootName = "content") {
-    return this.loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName);
+    return timeRequestPhase("schema", () => this.loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName));
   }
   /**
    * Resolve the schema from disk. Protected rather than a direct resolveSchema
@@ -2450,8 +2604,7 @@ var BranchSchemaCache = class {
     const contentRoot = path8.join(branchRoot, contentRootName);
     const skipDiskCache = this.skipDiskCache(branchRoot);
     if (!skipDiskCache) {
-      const cacheDir = path8.join(branchRoot, ".canopy-meta");
-      const cachePath = path8.join(cacheDir, "schema-cache.json");
+      const cachePath = path8.join(await schemaCacheDir(branchRoot), SCHEMA_CACHE_FILE);
       let cacheData = null;
       try {
         const cacheContent = await fs7.readFile(cachePath, "utf-8");
@@ -2493,7 +2646,7 @@ var BranchSchemaCache = class {
     const { skipDiskCache } = options;
     const contentRoot = path8.join(branchRoot, contentRootName);
     const read = skipDiskCache ? null : await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
-    const result = await this.resolveFresh(contentRoot, entrySchemaRegistry);
+    const result = await timeRequestPhase("resolve", () => this.resolveFresh(contentRoot, entrySchemaRegistry));
     if (!isValidSchema(result.schema)) {
       throw new Error(`No schema found in ${contentRoot}. Create .collection.json files with references to field schemas defined in your entry schema registry.`);
     }
@@ -2504,9 +2657,9 @@ var BranchSchemaCache = class {
     }
     const flatSchema = flattenSchema(result.schema, contentRootName);
     if (!skipDiskCache) {
-      const cacheDir = path8.join(branchRoot, ".canopy-meta");
-      const cachePath = path8.join(cacheDir, "schema-cache.json");
-      await fs7.unlink(path8.join(cacheDir, "schema-cache.stale")).catch(() => {
+      const cacheDir = await schemaCacheDir(branchRoot);
+      const cachePath = path8.join(cacheDir, SCHEMA_CACHE_FILE);
+      await fs7.unlink(path8.join(branchRoot, CANOPY_META_DIR, "schema-cache.stale")).catch(() => {
       });
       if (read && read.ok) {
         const newCache = {
@@ -2644,6 +2797,11 @@ function sanitizeBranchName(branchName) {
   const trimmedDots = squashed.replace(/^\.+/, "").replace(/(?<!\.)\.+$/, "");
   return trimmedDots || "branch";
 }
+var RESERVED_SETTINGS_BRANCH_PREFIX = "canopycms-settings-";
+function isSettingsBranchName(branchName, settingsBranchName) {
+  const sanitized = sanitizeBranchName(branchName);
+  return sanitized.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX) || settingsBranchName !== void 0 && sanitized === sanitizeBranchName(settingsBranchName);
+}
 
 // dist/paths/branch.js
 var BranchPathError = class extends Error {
@@ -2655,6 +2813,9 @@ function resolveBranchPath(options) {
   if (options.branchName.includes("..")) {
     throw new BranchPathError("Branch name cannot contain traversal segments");
   }
+  if (isSettingsBranchName(options.branchName)) {
+    throw new BranchPathError("Settings branches are not content branches");
+  }
   const safeBranch = sanitizeBranchName(options.branchName);
   const strategy = operatingStrategy(options.mode);
   const baseRoot = resolveContentBranchesRoot(options.mode, options.basePathOverride);
@@ -3116,6 +3277,7 @@ var ContentStore = class {
       return {
         absolutePath: resolved,
         relativePath: path11.relative(this.root, resolved),
+        logicalPath: entryLogicalPath(schemaItem.logicalPath, safeSlug),
         id,
         entryTypeName: finalEntryTypeName,
         existed
@@ -3145,6 +3307,10 @@ var ContentStore = class {
     const schemaItem = this.assertSchemaItem(schemaPath);
     return await this.buildPaths(schemaItem, slug);
   }
+  /**
+   * Read one entry. References resolve unless `resolveReferences: false`; a target that
+   * `referenceAccess` denies resolves to a `RestrictedReference` rather than its data.
+   */
   async read(collectionPath, slug = "", options = {}) {
     const schemaItem = this.assertSchemaItem(collectionPath);
     const { absolutePath, relativePath, entryTypeName: resolvedEntryTypeName } = await this.buildPaths(schemaItem, slug);
@@ -3206,7 +3372,7 @@ var ContentStore = class {
       };
     }
     if (options.resolveReferences !== false) {
-      doc.data = await this.resolveReferencesInData(doc.data, fields);
+      doc.data = await this.resolveReferencesInData(doc.data, fields, void 0, options.referenceAccess);
     }
     doc.version = stat.mtimeMs;
     return doc;
@@ -3660,20 +3826,25 @@ var ContentStore = class {
    * a target referenced by many entries is read once; omit `cache` for exactly `read()`'s
    * unmemoized behavior.
    *
-   * **Path ACLs are not consulted for the targets.** Resolution goes through this store's own
-   * `read()`, below the per-entry permission check in content-reader.ts, so a resolved target
-   * may be an entry the caller could not `read()` directly -- pre-existing `read()` behavior,
-   * matched here on purpose so one rule covers both.
+   * `access` applies to every target exactly as in `read()`; see {@link ReferenceTargetAccess}.
    */
-  async resolveReferences(data, fields, cache) {
-    return this.resolveReferencesInData(data, fields, cache);
+  async resolveReferences(data, fields, cache, access) {
+    return this.resolveReferencesInData(data, fields, cache, access);
   }
-  async resolveReferencesInData(data, fields, cache) {
+  /**
+   * Resolve one reference id the way a reference field resolves it, for the editor's
+   * live-preview endpoint (api/resolve-references.ts), which has ids but no field to walk. Null
+   * when the id names no entry. No body is embedded, since there is no field to ask for one.
+   */
+  async resolveReferenceTarget(id, access) {
+    return this.resolveSingleReference(id, await this.idIndex(), false, void 0, access);
+  }
+  async resolveReferencesInData(data, fields, cache, access) {
     const resolved = { ...data };
     const idIndex = await this.idIndex();
     for (const field of fields) {
       if (field.type === "group") {
-        const groupResolved = await this.resolveReferencesInData(resolved, field.fields, cache);
+        const groupResolved = await this.resolveReferencesInData(resolved, field.fields, cache, access);
         Object.assign(resolved, groupResolved);
         continue;
       }
@@ -3681,18 +3852,18 @@ var ContentStore = class {
       if (field.type === "reference") {
         const includeBody = field.includeBody === true;
         if (typeof value === "string" && value) {
-          resolved[field.name] = await this.resolveSingleReference(value, idIndex, includeBody, cache);
+          resolved[field.name] = await this.resolveSingleReference(value, idIndex, includeBody, cache, access);
         } else if (field.list && Array.isArray(value)) {
-          resolved[field.name] = await Promise.all(value.map((id) => typeof id === "string" ? this.resolveSingleReference(id, idIndex, includeBody, cache) : null));
+          resolved[field.name] = await Promise.all(value.map((id) => typeof id === "string" ? this.resolveSingleReference(id, idIndex, includeBody, cache, access) : null));
         }
       } else if (field.type === "object" && value) {
         const objectField = field;
         if (!objectField.fields)
           continue;
         if (objectField.list && Array.isArray(value)) {
-          resolved[field.name] = await Promise.all(value.map((item) => typeof item === "object" && item !== null ? this.resolveReferencesInData(item, objectField.fields, cache) : item));
+          resolved[field.name] = await Promise.all(value.map((item) => typeof item === "object" && item !== null ? this.resolveReferencesInData(item, objectField.fields, cache, access) : item));
         } else if (typeof value === "object") {
-          resolved[field.name] = await this.resolveReferencesInData(value, objectField.fields, cache);
+          resolved[field.name] = await this.resolveReferencesInData(value, objectField.fields, cache, access);
         }
       } else if (field.type === "block" && Array.isArray(value)) {
         const blockField = field;
@@ -3705,7 +3876,7 @@ var ContentStore = class {
             return block;
           return {
             ...b,
-            value: await this.resolveReferencesInData(b.value, template.fields, cache)
+            value: await this.resolveReferencesInData(b.value, template.fields, cache, access)
           };
         }));
       }
@@ -3736,13 +3907,13 @@ var ContentStore = class {
    * `includeBody` is opt-in per field: an embedded body sits inside the memoized object and is
    * cloned once per referencing entry.
    */
-  resolveSingleReference(id, idIndex, includeBody, cache) {
+  resolveSingleReference(id, idIndex, includeBody, cache, access) {
     if (!cache)
-      return this.resolveSingleReferenceUncached(id, idIndex, includeBody);
+      return this.resolveSingleReferenceUncached(id, idIndex, includeBody, access);
     const key = includeBody ? `${id}:body` : id;
     let pending = cache.get(key);
     if (!pending) {
-      pending = this.resolveSingleReferenceUncached(id, idIndex, includeBody);
+      pending = this.resolveSingleReferenceUncached(id, idIndex, includeBody, access);
       cache.set(key, pending);
     }
     return pending.then((resolved) => resolved === null ? null : structuredClone(resolved));
@@ -3760,15 +3931,27 @@ var ContentStore = class {
    * A {@link ReferenceResolveCache} sits ABOVE this, never inside it, so every distinct id
    * still runs the full refresh-and-retry; a cache only makes repeats of the SAME id share it.
    */
-  async resolveSingleReferenceUncached(id, idIndex, includeBody) {
-    const first = await this.resolveSingleReferenceOnce(id, idIndex, includeBody);
+  async resolveSingleReferenceUncached(id, idIndex, includeBody, access) {
+    const first = await this.resolveSingleReferenceOnce(id, idIndex, includeBody, access);
     if (first !== STALE_LOOKUP)
       return first;
     await this.refreshIndexForSuspiciousLookup();
-    const second = await this.resolveSingleReferenceOnce(id, await this.idIndex(), includeBody);
+    const second = await this.resolveSingleReferenceOnce(id, await this.idIndex(), includeBody, access);
     return second === STALE_LOOKUP ? null : second;
   }
-  async resolveSingleReferenceOnce(id, idIndex, includeBody) {
+  /**
+   * The entry type an entry file was written as, by its filename's type token, falling back to
+   * the collection's default the way `read()` does for a legacy untyped file.
+   */
+  entryTypeOf(collectionPath, relativePath) {
+    const schemaItem = this.assertSchemaItem(collectionPath);
+    if (schemaItem.type === "entry-type")
+      return schemaItem;
+    const entries = schemaItem.entries;
+    const typeName = extractEntryTypeFromFilename(path11.basename(relativePath));
+    return entries?.find((e) => e.name === typeName) ?? getDefaultEntryType(schemaItem.entries);
+  }
+  async resolveSingleReferenceOnce(id, idIndex, includeBody, access) {
     try {
       const location = idIndex.findById(id);
       if (!location)
@@ -3779,13 +3962,22 @@ var ContentStore = class {
       const doc = await this.read(location.collection, location.slug, {
         resolveReferences: false
       });
-      const bodyForEmbed = includeBody && "body" in doc ? { fieldName: doc.bodyFieldName, value: doc.body } : void 0;
-      return buildResolvedReference(doc.data, {
+      const meta = {
         id,
         slug: location.slug,
         collection: location.collection,
         urlPath: computeEntryUrl(location.collection, location.slug, this.contentRootName)
-      }, bodyForEmbed);
+      };
+      if (access && !access(entryLogicalPath(location.collection, location.slug))) {
+        const entryType = this.entryTypeOf(location.collection, location.relativePath);
+        return buildRestrictedReference(meta, resolveEntryTitle(doc.data, {
+          schema: entryType?.schema,
+          entryTypeLabel: entryType?.label,
+          slug: location.slug
+        }));
+      }
+      const bodyForEmbed = includeBody && "body" in doc ? { fieldName: doc.bodyFieldName, value: doc.body } : void 0;
+      return buildResolvedReference(doc.data, meta, bodyForEmbed);
     } catch (error) {
       if (isNodeError(error) && error.code === "ENOENT")
         return STALE_LOOKUP;
@@ -4353,7 +4545,7 @@ function yamlValue(value) {
 }
 
 // dist/entry-link-resolver.js
-var log2 = createDebugLogger({ prefix: "EntryLinks" });
+var log3 = createDebugLogger({ prefix: "EntryLinks" });
 var BASE58_CHAR = "[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]";
 var ENTRY_LINK_PATTERN = new RegExp(`entry:(${BASE58_CHAR}{12})(#[^\\s)>"']*)?`, "g");
 function resolveEntryUrl(location, contentRoot) {
@@ -4367,7 +4559,7 @@ function resolveEntryLinksInText(text, idIndex, contentRoot, customResolver) {
     return part.text.replace(ENTRY_LINK_PATTERN, (_match, id, anchor) => {
       const location = idIndex.findById(id);
       if (!location || location.type !== "entry" || !location.collection || !location.slug) {
-        log2.warn("resolve", `Entry link target not found: entry:${id}`);
+        log3.warn("resolve", `Entry link target not found: entry:${id}`);
         return anchor ?? "#";
       }
       let url;
@@ -4765,7 +4957,7 @@ async function readBranchMetadataFile(branchRoot) {
 
 // dist/branch-registry.js
 init_logger();
-var log3 = createDebugLogger({ prefix: "BranchRegistry" });
+var log4 = createDebugLogger({ prefix: "BranchRegistry" });
 var REGISTRY_FILE = "branches.json";
 var REGISTRY_STALE_FILE = "branches.stale.json";
 var REGISTRY_TEMP_FILE = "branches.tmp.json";
@@ -4845,7 +5037,7 @@ var BranchRegistry = class {
         });
       await this.regenerate();
     } catch (err) {
-      log3.warn("invalidate", "Eager regeneration after invalidate() failed", {
+      log4.warn("invalidate", "Eager regeneration after invalidate() failed", {
         error: getErrorMessage(err)
       });
     }
@@ -4936,7 +5128,7 @@ import fs14 from "node:fs/promises";
 import path15 from "node:path";
 import { randomUUID as randomUUID2 } from "node:crypto";
 import lockfile2 from "proper-lockfile";
-var log4 = createDebugLogger({ prefix: "OccJsonWrite" });
+var log5 = createDebugLogger({ prefix: "OccJsonWrite" });
 var OccWriteConflictError = class extends Error {
   constructor(message = "Concurrent modification detected") {
     super(message);
@@ -5031,7 +5223,7 @@ async function withOccFileLock(filePath, fn) {
         // Our critical sections are short and idempotent-on-conflict (OCC
         // verify inside); log and let the section finish.
         onCompromised: (err) => {
-          log4.warn("lock", `Lock compromised mid-hold for ${filePath}`, {
+          log5.warn("lock", `Lock compromised mid-hold for ${filePath}`, {
             error: getErrorMessage(err)
           });
         }
@@ -5053,7 +5245,7 @@ async function withOccFileLock(filePath, fn) {
     await release().catch((err) => {
       if (isNodeError(err) && err.code === "ENOENT")
         return;
-      log4.warn("lock", `Failed to release lock for ${filePath}`, { error: getErrorMessage(err) });
+      log5.warn("lock", `Failed to release lock for ${filePath}`, { error: getErrorMessage(err) });
     });
   }
 }
@@ -5229,51 +5421,7 @@ init_operating_mode();
 import fs16 from "node:fs/promises";
 import path17 from "node:path";
 import { simpleGit as simpleGit2 } from "simple-git";
-
-// dist/utils/git.js
-import { simpleGit } from "simple-git";
-var NETWORK_SCHEME_PATTERN = /^(https?|ssh|git):\/\//i;
-var TRANSPORT_HELPER_PATTERN = /^[a-z][a-z0-9+.-]*::/i;
-var LEADING_OPTION_PATTERN = /^-/;
-var WINDOWS_DRIVE_PATTERN = /^[a-zA-Z]:[\\/]/;
-var COLON_BEFORE_SLASH_PATTERN = /^[^/\\\s]+:/;
-function isNetworkRemoteUrl(url) {
-  if (/^file:\/\//i.test(url))
-    return false;
-  if (NETWORK_SCHEME_PATTERN.test(url))
-    return true;
-  if (TRANSPORT_HELPER_PATTERN.test(url))
-    return true;
-  if (LEADING_OPTION_PATTERN.test(url))
-    return true;
-  if (WINDOWS_DRIVE_PATTERN.test(url))
-    return false;
-  return COLON_BEFORE_SLASH_PATTERN.test(url);
-}
-var MISSING_REMOTE_REF_REASONS = ["couldn't find remote ref", "Couldn't find remote ref"];
-function isMissingRemoteRefFailure(message) {
-  return MISSING_REMOTE_REF_REASONS.some((reason) => message.includes(reason));
-}
-async function detectHeadBranch(repoRoot, fallback = "main") {
-  try {
-    const git = simpleGit({ baseDir: repoRoot });
-    const head = (await git.revparse(["--abbrev-ref", "HEAD"])).trim();
-    return head && head !== "HEAD" ? head : fallback;
-  } catch {
-    return fallback;
-  }
-}
-async function resolveBaseBranch(options) {
-  if (options.defaultBaseBranch)
-    return options.defaultBaseBranch;
-  if (options.mode === "dev") {
-    return detectHeadBranch(options.detectFrom ?? process.cwd());
-  }
-  return "main";
-}
-
-// dist/git-manager.js
-var log5 = createDebugLogger({ prefix: "GitManager" });
+var log6 = createDebugLogger({ prefix: "GitManager" });
 var GIT_ENV_PASSTHROUGH = /^(PATH|HOME|USER|LANG|LC_[A-Z]+|TZ|TMPDIR|GIT_(AUTHOR|COMMITTER)_(NAME|EMAIL|DATE)|GIT_TERMINAL_PROMPT|GIT_TRACE[0-9A-Z_]*)$/;
 var FORCE_C_LOCALE = { LC_ALL: "C", LANG: "C" };
 function gitChildEnv(overrides) {
@@ -5298,13 +5446,13 @@ async function ensureGitExcludePattern(repoPath, pattern) {
   }
   const lines = content.split("\n");
   if (lines.some((line) => line.trim() === pattern)) {
-    log5.debug("git", "Pattern already in .git/info/exclude", { pattern });
+    log6.debug("git", "Pattern already in .git/info/exclude", { pattern });
     return;
   }
   const needsLeadingNewline = content.length > 0 && !content.endsWith("\n");
   const newContent = content + (needsLeadingNewline ? "\n" : "") + pattern + "\n";
   await fs16.writeFile(excludePath, newContent, "utf-8");
-  log5.debug("git", "Added pattern to .git/info/exclude", { pattern });
+  log6.debug("git", "Added pattern to .git/info/exclude", { pattern });
 }
 var GitConflictError = class extends Error {
   constructor(conflictedFiles) {
@@ -5322,6 +5470,41 @@ var GitRemoteRefMissingError = class extends Error {
     this.name = "GitRemoteRefMissingError";
   }
 };
+var RemoteNotReadyError = class 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";
+  }
+};
+var SettingsRemoteUnreadableError = class extends Error {
+  constructor(branch, remote, 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";
+  }
+};
+var SettingsBranchDivergedError = class extends Error {
+  constructor(branch, workspacePath, 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";
+  }
+};
+var SETTINGS_BRANCH_FILES = /* @__PURE__ */ new Set(["permissions.json", "groups.json"]);
+var SettingsBranchHasContentHistoryError = class extends Error {
+  constructor(branch, remote, 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";
+  }
+};
 var GitManager = class _GitManager {
   constructor(options, gitOptions) {
     this.repoPath = path17.resolve(options.repoPath);
@@ -5332,14 +5515,14 @@ var GitManager = class _GitManager {
     this.git.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path17.dirname(this.repoPath) }));
   }
   static async cloneRepo(remoteUrl, targetPath, baseBranch = "main") {
-    log5.debug("git", "Cloning repository", {
+    log6.debug("git", "Cloning repository", {
       remoteUrl,
       targetPath,
       baseBranch
     });
     const git = simpleGit2();
     await git.clone(remoteUrl, targetPath, ["--branch", baseBranch, "--single-branch"]);
-    log5.debug("git", "Clone complete");
+    log6.debug("git", "Clone complete");
   }
   /**
    * Initializes a local bare git repository to simulate a remote for dev mode,
@@ -5353,15 +5536,15 @@ var GitManager = class _GitManager {
   static async ensureLocalSimulatedRemote(options) {
     const existingLock = remoteInitLocks.get(options.remotePath);
     if (existingLock) {
-      log5.debug("git", "Waiting for existing remote initialization", {
+      log6.debug("git", "Waiting for existing remote initialization", {
         remotePath: options.remotePath
       });
       await existingLock;
     }
-    const lockPromise = log5.timed("git", "ensureLocalSimulatedRemote", async () => {
+    const lockPromise = log6.timed("git", "ensureLocalSimulatedRemote", async () => {
       let releaseLock;
       try {
-        log5.debug("git", "Initializing local simulated remote", {
+        log6.debug("git", "Initializing local simulated remote", {
           remotePath: options.remotePath,
           baseBranch: options.baseBranch
         });
@@ -5376,7 +5559,7 @@ var GitManager = class _GitManager {
             throw err;
         }
         if (remoteExists && await _GitManager.bareRemoteHasBranch(options.remotePath, options.baseBranch)) {
-          log5.debug("git", "Remote already has base branch, skipping");
+          log6.debug("git", "Remote already has base branch, skipping");
           return;
         }
         let gitRoot = options.sourcePath;
@@ -5395,8 +5578,8 @@ var GitManager = class _GitManager {
         }
         let hasCommits = false;
         try {
-          const log8 = await sourceGit.log(["-1"]);
-          hasCommits = log8.total > 0;
+          const log9 = await sourceGit.log(["-1"]);
+          hasCommits = log9.total > 0;
         } catch {
           hasCommits = false;
         }
@@ -5408,12 +5591,12 @@ var GitManager = class _GitManager {
           throw new Error(`Cannot initialize local simulated remote: base branch '${options.baseBranch}' does not exist locally. Please checkout '${options.baseBranch}' first or provide an explicit remoteUrl.`);
         }
         if (remoteExists) {
-          log5.debug("git", "Existing remote is missing base branch \u2014 pushing it from source", {
+          log6.debug("git", "Existing remote is missing base branch \u2014 pushing it from source", {
             remotePath: options.remotePath,
             baseBranch: options.baseBranch
           });
         } else {
-          log5.debug("git", "Creating bare remote repository");
+          log6.debug("git", "Creating bare remote repository");
           await simpleGit2().raw([
             "init",
             "--bare",
@@ -5427,13 +5610,13 @@ var GitManager = class _GitManager {
           baseBranch: options.baseBranch,
           subdirectory: options.subdirectory
         });
-        log5.debug("git", "Remote initialization complete");
+        log6.debug("git", "Remote initialization complete");
       } finally {
         if (releaseLock) {
           try {
             await releaseLock();
           } catch (err) {
-            log5.debug("git", "Failed to release remote-init lock", { err });
+            log6.debug("git", "Failed to release remote-init lock", { err });
           }
         }
         remoteInitLocks.delete(options.remotePath);
@@ -5501,7 +5684,7 @@ var GitManager = 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.
@@ -5632,6 +5815,12 @@ var GitManager = class _GitManager {
       return;
     throw new Error(`CanopyCMS: refusing to use a network remote URL in prod mode (from ${source}: "${url}"). The standard AWS Lambda+EC2-worker topology runs the CMS Lambda with no internet access \u2014 the EC2 worker owns all network git I/O, and the Lambda is expected to reach the EFS-local bare repo ({workspace}/remote.git) via auto-detect instead. Pointing a network URL here would make the internet-less Lambda try to clone/fetch/push it directly and hang until timeout. If this prod host genuinely has internet access and 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: operatingStrategy2 } = await Promise.resolve().then(() => (init_operating_mode(), operating_mode_exports));
+    const { autoDetectRemotePath } = operatingStrategy2(mode).getRemoteUrlConfig();
+    return autoDetectRemotePath ? new RemoteNotReadyError(autoDetectRemotePath) : void 0;
+  }
   /**
    * Resolves the remote URL for git operations following the priority:
    * 1. Explicit remoteUrl parameter
@@ -5668,7 +5857,7 @@ var GitManager = class _GitManager {
       try {
         const stat = await fs16.stat(config.autoDetectRemotePath);
         if (stat.isDirectory()) {
-          log5.debug("git", "Auto-detected local remote", {
+          log6.debug("git", "Auto-detected local remote", {
             path: config.autoDetectRemotePath
           });
           return config.autoDetectRemotePath;
@@ -5732,7 +5921,7 @@ var GitManager = class _GitManager {
       try {
         const stat = await fs16.stat(gitPath);
         if (stat.isDirectory()) {
-          log5.debug("git", "Removing corrupt .git directory", {
+          log6.debug("git", "Removing corrupt .git directory", {
             workspacePath: options.workspacePath
           });
           await fs16.rm(gitPath, { recursive: true });
@@ -5743,6 +5932,7 @@ var GitManager = class _GitManager {
       }
     }
     let justCloned = false;
+    let resolvedRemoteUrl;
     if (!repoExists) {
       const remoteUrl = await _GitManager.resolveRemoteUrl({
         mode: options.mode,
@@ -5753,6 +5943,9 @@ var GitManager = class _GitManager {
         allowNetworkRemoteInProd: options.allowNetworkRemoteInProd
       });
       if (!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");
       }
       try {
@@ -5761,6 +5954,7 @@ var GitManager = class _GitManager {
         throw new Error(`Failed to clone branch workspace at ${options.workspacePath} from ${remoteUrl} (base branch '${baseBranch}'): ${getErrorMessage(err)}`);
       }
       justCloned = true;
+      resolvedRemoteUrl = remoteUrl;
       const freshGit = simpleGit2({ baseDir: options.workspacePath });
       freshGit.env(gitChildEnv({ GIT_CEILING_DIRECTORIES: path17.dirname(options.workspacePath) }));
       await freshGit.addConfig("canopycms.managed", "true");
@@ -5776,7 +5970,7 @@ var GitManager = class _GitManager {
     await git.git.addConfig("canopycms.managed", "true");
     await git.git.addConfig("user.name", options.gitBotAuthorName);
     await git.git.addConfig("user.email", options.gitBotAuthorEmail);
-    log5.debug("git", "Marked workspace as CanopyCMS-managed", {
+    log6.debug("git", "Marked workspace as CanopyCMS-managed", {
       workspacePath: options.workspacePath
     });
     if (!justCloned) {
@@ -5791,9 +5985,17 @@ var GitManager = class _GitManager {
       if (remoteUrl) {
         await git.ensureRemote(remoteUrl);
       }
+      resolvedRemoteUrl = remoteUrl;
     }
     if (options.branchType === "orphan") {
-      await git.createOrphanSettingsBranch(options.branchName, {});
+      try {
+        await git.createOrphanSettingsBranch(options.branchName, {});
+      } catch (err) {
+        if (err instanceof SettingsRemoteUnreadableError && !resolvedRemoteUrl) {
+          throw await _GitManager.remoteNotReadyError(options.mode) ?? err;
+        }
+        throw err;
+      }
       await git.ensureGitExclude("*.lock");
     } else {
       await git.checkoutBranch(options.branchName);
@@ -5902,7 +6104,7 @@ var GitManager = class _GitManager {
     const branches = await this.git.branch();
     const currentBranch = branches.current;
     try {
-      await this.git.fetch(this.remote, currentBranch);
+      await this.git.fetch(this.remote, `refs/heads/${currentBranch}`);
     } catch (err) {
       if (!isMissingRemoteRefFailure(getErrorMessage(err)))
         throw err;
@@ -5959,19 +6161,34 @@ var GitManager = class _GitManager {
     const fileArray = Array.isArray(files) ? files : [files];
     await this.git.add(fileArray);
   }
+  /** 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"]);
+    const target = branch ?? await this.currentBranchName();
     await this.git.raw([
       "push",
       "--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.
@@ -5990,12 +6207,12 @@ var GitManager = class _GitManager {
    * ("couldn't find remote ref"); that counts as "ahead", not an error.
    */
   async hasUnpushedCommits(branch) {
-    const target = branch ?? await this.git.revparse(["--abbrev-ref", "--end-of-options", "HEAD"]);
-    const localSha = (await this.git.revparse(["--end-of-options", target])).trim();
+    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 {
       return true;
     }
@@ -6004,6 +6221,25 @@ var GitManager = 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]);
+    const baseTip = (await this.git.revparse(["--verify", "--end-of-options", "FETCH_HEAD"])).trim();
+    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();
     const isManaged = config.all["canopycms.managed"] === "true";
@@ -6057,10 +6293,24 @@ var GitManager = 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 {
@@ -6070,11 +6320,31 @@ var GitManager = class _GitManager {
     }
   }
   async createOrphanSettingsBranchInner(branchName, initialFiles) {
-    log5.debug("git", "Creating orphan settings branch", { branchName });
+    log6.debug("git", "Ensuring settings branch", { branchName });
     const branches = await this.git.branch();
-    if (branches.all.includes(branchName)) {
-      log5.debug("git", "Orphan branch already exists", { branchName });
+    const localExists = branches.all.includes(branchName);
+    if (localExists) {
       await this.git.checkout(branchName);
+    }
+    let remoteTip;
+    try {
+      remoteTip = await this.remoteBranchTip(branchName);
+    } catch (err) {
+      if (localExists && !await this.isEmptyInitialBranch(branchName)) {
+        log6.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);
+      await this.git.raw(["checkout", "-b", branchName, fetchedTip]);
+      log6.debug("git", "Checked out the remote settings branch", { branchName });
       return;
     }
     await this.git.raw(["checkout", "--orphan", branchName]);
@@ -6089,19 +6359,129 @@ var GitManager = class _GitManager {
       await this.git.add(filePath);
     }
     await this.git.commit("Initialize settings branch", ["--allow-empty"]);
-    log5.debug("git", "Orphan settings branch created", { branchName });
+    log6.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);
+    await this.git.raw(["checkout", "-B", branchName, fetchedTip]);
+    log6.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("	");
+      if (sha && name === ref)
+        return sha;
+    }
+    return void 0;
+  }
+  /**
+   * 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 ? ", \u2026" : "");
+      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}`
+    ]) {
+      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() === "";
   }
 };
 
 // dist/branch-workspace.js
-var log6 = createDebugLogger({ prefix: "BranchWorkspace" });
+var log7 = createDebugLogger({ prefix: "BranchWorkspace" });
 var workspaceInitLocks = /* @__PURE__ */ new Map();
 var BranchWorkspaceManager = class {
   constructor(config) {
     this.config = config;
   }
   async ensureGitWorkspace(options) {
-    return log6.timed("workspace", "ensureGitWorkspace", async () => {
+    return log7.timed("workspace", "ensureGitWorkspace", async () => {
       const existingLock = workspaceInitLocks.get(options.branchRoot);
       if (existingLock) {
         await existingLock;
@@ -6110,11 +6490,11 @@ var BranchWorkspaceManager = class {
       const lockPromise = (async () => {
         let releaseLock;
         try {
-          log6.debug("workspace", "Ensuring git workspace", {
+          log7.debug("workspace", "Ensuring git workspace", {
             branchName: options.branchName,
             mode: options.mode
           });
-          releaseLock = await acquireProvisioningLock(path18.dirname(options.branchRoot), `.${path18.basename(options.branchRoot)}.init.lock`);
+          releaseLock = await acquireProvisioningLock(path18.dirname(options.branchRoot), branchProvisioningLockName(path18.basename(options.branchRoot)));
           await GitManager.initializeWorkspace({
             workspacePath: options.branchRoot,
             branchName: options.branchName,
@@ -6135,7 +6515,7 @@ var BranchWorkspaceManager = class {
             try {
               await releaseLock();
             } catch (err) {
-              log6.debug("workspace", "Failed to release workspace-init lock", { err });
+              log7.debug("workspace", "Failed to release workspace-init lock", { err });
             }
           }
           workspaceInitLocks.delete(options.branchRoot);
@@ -6147,6 +6527,9 @@ var BranchWorkspaceManager = class {
   }
   async openOrCreateBranch(options) {
     const { branchName, mode, basePathOverride, title, description, access, createdBy, remoteUrl } = options;
+    if (isSettingsBranchName(branchName, operatingStrategy(mode).getSettingsBranchName(this.config))) {
+      throw new BranchPathError("Settings branches are not content branches");
+    }
     const { branchRoot, baseRoot, branchName: safeName } = await ensureBranchRoot({
       mode,
       branchName,
@@ -6243,7 +6626,7 @@ import fs17 from "node:fs/promises";
 import path19 from "node:path";
 import matter3 from "gray-matter";
 import { parse as yamlParse2 } from "yaml";
-var log7 = createDebugLogger({ prefix: "ContentListing" });
+var log8 = createDebugLogger({ prefix: "ContentListing" });
 var normalizePath = (root, target) => {
   const result = validateAndNormalizePath(root, target);
   if (!result.valid) {
@@ -6269,13 +6652,17 @@ var readEntryData = async (filePath, format, bodyFieldName = "body") => {
   } catch (err) {
     if (isNotFoundError(err))
       return {};
-    log7.warn("readEntryData", `Failed to read entry data from ${filePath}: ${getErrorMessage(err)}`);
+    log8.warn("readEntryData", `Failed to read entry data from ${filePath}: ${getErrorMessage(err)}`);
     return {};
   }
 };
-var createReferenceResolver = (branchRoot, flatSchema, contentRootName) => ({
+var createReferenceResolver = (branchRoot, flatSchema, contentRootName, visibility) => ({
   store: new ContentStore(branchRoot, flatSchema, { contentRootName }),
-  cache: createReferenceResolveCache()
+  cache: createReferenceResolveCache(),
+  // The predicate that hides an entry from the listing is the one that restricts it as a
+  // reference target, so a target is never shown in a sibling's data that its own listing
+  // row would have hidden.
+  access: visibility?.shouldInclude
 });
 var resolveCollectionItemReferences = async (items, collection, resolver) => Promise.all(items.map(async (item) => {
   const fields = collection.entries?.find((e) => e.name === item.entryType)?.schema;
@@ -6283,7 +6670,7 @@ var resolveCollectionItemReferences = async (items, collection, resolver) => Pro
     return item;
   return {
     ...item,
-    data: await resolver.store.resolveReferences(item.data, fields, resolver.cache)
+    data: await resolver.store.resolveReferences(item.data, fields, resolver.cache, resolver.access)
   };
 }));
 async function listEntries(branchRoot, flatSchema, contentRootName, options, visibility) {
@@ -6294,10 +6681,10 @@ async function listEntries(branchRoot, flatSchema, contentRootName, options, vis
   const collections = flatSchema.filter((item) => item.type === "collection" && item.entries !== void 0 && (item.logicalPath === rootPath || item.logicalPath.startsWith(`${rootPath}/`)));
   const shouldInclude = visibility?.shouldInclude;
   const skippedFiles = [];
-  const resolver = options?.resolveReferences ? createReferenceResolver(branchRoot, flatSchema, contentRootName) : null;
+  const resolver = options?.resolveReferences ? createReferenceResolver(branchRoot, flatSchema, contentRootName, visibility) : null;
   const collectionResults = await Promise.all(collections.map(async (collection) => {
     const entries = await listCollectionEntries(branchRoot, collection, (file) => skippedFiles.push(file));
-    const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.physicalPath)) : entries;
+    const visible = shouldInclude ? entries.filter((e) => shouldInclude(e.logicalPath)) : entries;
     const resolved = resolver ? await resolveCollectionItemReferences(visible, collection, resolver) : visible;
     return resolved.map((entry) => ({ entry, collection }));
   }));
@@ -6387,7 +6774,7 @@ var listCollectionEntries = async (root, collection, onSkip) => {
     const relativePath = normalizePath(root, absolutePath);
     const parsed = parseTypedFilename(file.name, entryTypes);
     if (!parsed) {
-      log7.warn("listCollectionEntries", `Skipping file with unrecognized filename format: ${file.name} (expected {type}.{slug}.{id}.{ext} with a known entry type and valid 12-char Base58 ID)`);
+      log8.warn("listCollectionEntries", `Skipping file with unrecognized filename format: ${file.name} (expected {type}.{slug}.{id}.{ext} with a known entry type and valid 12-char Base58 ID)`);
       if (looksLikeMalformedEntry(file.name, entryTypes)) {
         onSkip?.({ filename: file.name, collectionPath: collection.logicalPath });
       }
@@ -6402,7 +6789,7 @@ var listCollectionEntries = async (root, collection, onSkip) => {
       readEntryData(absolutePath, format, bodyField)
     ]);
     const item = {
-      logicalPath: `${collection.logicalPath}/${slug}`,
+      logicalPath: entryLogicalPath(collection.logicalPath, slug),
       contentId,
       slug,
       collectionPath: collection.logicalPath,