canopycms 0.0.63 → 0.0.65

package/dist/utils/content-write-lock.js

@@ -26,22 +26,18 @@
  * an acceptable price, and a read racing a rebase gets a consistent-enough
  * older or newer file, never a destroyed one.
  *
- * ## Why the lock is anchored on `{branchRoot}/.canopy-meta`
+ * ## Why the lock marker lives under `{branchRoot}/.canopy-meta`
  *
  * proper-lockfile keys its module-level `locks{}` bookkeeping (refresh timer,
  * release function) by the **target path** passed to `lock()`, NOT by
- * `lockfilePath`. The provisioning lock targets `path.dirname(branchRoot)` --
- * the shared content-branches directory -- so anchoring here on that same
- * directory with a different lock NAME would land on the same registry key:
- * one process holding both (a Lambda container provisioning a workspace and
- * writing content) would have the second acquisition clobber the first's
- * bookkeeping. Targeting `{branchRoot}/.canopy-meta` instead gives:
- *
- * - a distinct in-process registry key from the provisioning lock (and from
- *   every other branch's content lock -- the provisioning locks already share
- *   one key across branches);
- * - a distinct on-disk lock directory, so the server-enforced mkdir cannot
- *   collide either; and
+ * `lockfilePath`. `provisioning-lock.ts` now anchors every lock on its own
+ * marker path, so the registry key equals the on-disk lock identity and two
+ * live locks can no longer share a key -- aliasing is structurally impossible
+ * rather than merely avoided by convention. Keeping the content lock under
+ * `{branchRoot}/.canopy-meta` still buys:
+ *
+ * - a per-branch marker, so one branch's content lock is independent of every
+ *   other branch's and of that branch's provisioning lock; and
  * - no deadlock potential: the two locks are never both required, and the only
  *   possible acquisition order (provision, then write) is consistent.
  *
@@ -60,7 +56,8 @@
  * mutual exclusion. See docs/concurrency.md.
  */
 import path from 'node:path';
-import { isNodeError } from './error.js';
+import { getErrorMessage, isNodeError } from './error.js';
+import { canopyLogWarn } from './logger.js';
 import { tryAcquireProvisioningLock } from './provisioning-lock.js';
 /** Directory the lock marker lives in, relative to the branch root. */
 const META_DIR = '.canopy-meta';
@@ -108,7 +105,8 @@ export class ContentWriteLockBusyError extends Error {
         this.name = 'ContentWriteLockBusyError';
     }
 }
-/** The directory proper-lockfile anchors on -- also its in-process registry key. */
+/** Directory the lock marker is created in. proper-lockfile anchors on the
+ * marker path itself (see provisioning-lock.ts), not on this directory. */
 function lockTargetDir(branchRoot) {
     return path.join(path.resolve(branchRoot), META_DIR);
 }
@@ -122,8 +120,8 @@ const sleep = (ms) => new Promise((resolve) => {
  * the worker's rebase loop (which skips the branch and retries next cycle) and
  * by tests standing in for a writer.
  */
-export function tryAcquireContentWriteLock(branchRoot) {
-    return tryAcquireProvisioningLock(lockTargetDir(branchRoot), CONTENT_WRITE_LOCK_NAME);
+export function tryAcquireContentWriteLock(branchRoot, onCompromised) {
+    return tryAcquireProvisioningLock(lockTargetDir(branchRoot), CONTENT_WRITE_LOCK_NAME, onCompromised);
 }
 /**
  * Acquire the branch's content-write lock with a short bounded wait.
@@ -135,11 +133,11 @@ export function tryAcquireContentWriteLock(branchRoot) {
  *
  * @throws ContentWriteLockBusyError when the budget expires under contention.
  */
-export async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS) {
+export async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, onCompromised) {
     const startedAt = Date.now();
     for (let attempt = 0;; attempt++) {
         try {
-            return await tryAcquireContentWriteLock(branchRoot);
+            return await tryAcquireContentWriteLock(branchRoot, onCompromised);
         }
         catch (err) {
             if (!isNodeError(err) || err.code !== 'ELOCKED')
@@ -159,12 +157,30 @@ export async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTE
  * `finally` so a throw can never strand it.
  */
 export async function withContentWriteLock(branchRoot, fn, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS) {
-    const release = await acquireContentWriteLock(branchRoot, waitMs);
+    // A compromise means this write may no longer have been exclusive -- the
+    // worker's rebase (or another writer) could have been running against the
+    // same tree. Reporting success would silently accept a possibly-raced write,
+    // so surface the same retriable "branch busy" error contention already maps
+    // to (409) and let the caller re-save against the settled tree.
+    let compromised = false;
+    const release = await acquireContentWriteLock(branchRoot, waitMs, (err) => {
+        compromised = true;
+        canopyLogWarn(`[canopy] Content-write lock compromised mid-hold for ${branchRoot}:`, getErrorMessage(err));
+    });
+    let result;
     try {
-        return await fn();
+        result = await fn();
     }
     finally {
         await release();
     }
+    if (compromised) {
+        // Deliberately NOT the default "was not saved" message: `fn()` completed,
+        // so the write is on disk. What we lost is the proof it was exclusive, so
+        // the honest instruction is "reload, then decide" rather than "retry",
+        // which would resend a now-stale expectedVersion and bounce off the
+        // caller's own landed write as a phantom editor collision.
+        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.');
+    }
+    return result;
 }
-//# sourceMappingURL=content-write-lock.js.map

package/dist/utils/debug.d.ts

@@ -52,4 +52,3 @@ export declare function createDebugLogger(options?: DebugOptions): DebugLogger;
  * Enabled via E2E_DEBUG=true
  */
 export declare const testLogger: DebugLogger;
-//# sourceMappingURL=debug.d.ts.map

package/dist/utils/debug.js

@@ -107,4 +107,3 @@ export const testLogger = createDebugLogger({
     prefix: 'E2E',
     throwOnError: false,
 });
-//# sourceMappingURL=debug.js.map

package/dist/utils/entry-url.d.ts

@@ -4,6 +4,23 @@
  * This module has NO server-only dependencies (no node:fs, etc.)
  * so it can be safely imported into browser bundles.
  */
+/**
+ * Is this slug the collection-index slug?
+ *
+ * The shared home for that decision. Six sites route through here: `computeEntryUrl` below,
+ * `content-tree.ts`'s `defaultBuildPath`, `content-reader.ts`'s `buildEntryPath` and the
+ * editor's `buildPreviewSrc` (the four forward-rule implementations), the reverse
+ * `resolveUrlPathCandidates`, and `canopycms-next`'s `collectStaticParams`, which skips index
+ * entries for a single-segment route. Re-exported from `canopycms/server` for adopters. (`content-tree.ts`'s `indexEntry` lookup still does its own
+ * `slug === 'index'`; it is fed slugs already lowercased by the listing, so it is safe rather
+ * than shared.) Slug matching is case-insensitive throughout
+ * CanopyCMS (`parseSlug` lowercases, and `ContentStore` resolves slugs by a lowercased
+ * directory scan), so this compares lowercased — a bare `slug === 'index'` is correct only
+ * for callers whose input was already normalized, and silently wrong for the ones handling
+ * raw URL segments or on-disk names. `resolveUrlPathCandidates` was exactly that case: its
+ * strict compare left `/x/Index` resolving the index entry after `/x/index` stopped.
+ */
+export declare function isIndexSlug(slug: string | undefined): boolean;
 /**
  * Compute a URL path from an entry's collection path and slug.
  *
@@ -18,4 +35,3 @@
  *   ("content", "index", "content")              => "/"
  */
 export declare function computeEntryUrl(collection: string, slug: string, contentRoot: string): string;
-//# sourceMappingURL=entry-url.d.ts.map

package/dist/utils/entry-url.js

@@ -5,6 +5,25 @@
  * so it can be safely imported into browser bundles.
  */
 import { trimSlashes } from '../paths/normalize.js';
+/**
+ * Is this slug the collection-index slug?
+ *
+ * The shared home for that decision. Six sites route through here: `computeEntryUrl` below,
+ * `content-tree.ts`'s `defaultBuildPath`, `content-reader.ts`'s `buildEntryPath` and the
+ * editor's `buildPreviewSrc` (the four forward-rule implementations), the reverse
+ * `resolveUrlPathCandidates`, and `canopycms-next`'s `collectStaticParams`, which skips index
+ * entries for a single-segment route. Re-exported from `canopycms/server` for adopters. (`content-tree.ts`'s `indexEntry` lookup still does its own
+ * `slug === 'index'`; it is fed slugs already lowercased by the listing, so it is safe rather
+ * than shared.) Slug matching is case-insensitive throughout
+ * CanopyCMS (`parseSlug` lowercases, and `ContentStore` resolves slugs by a lowercased
+ * directory scan), so this compares lowercased — a bare `slug === 'index'` is correct only
+ * for callers whose input was already normalized, and silently wrong for the ones handling
+ * raw URL segments or on-disk names. `resolveUrlPathCandidates` was exactly that case: its
+ * strict compare left `/x/Index` resolving the index entry after `/x/index` stopped.
+ */
+export function isIndexSlug(slug) {
+    return slug?.toLowerCase() === 'index';
+}
 /**
  * Compute a URL path from an entry's collection path and slug.
  *
@@ -30,12 +49,11 @@ export function computeEntryUrl(collection, slug, contentRoot) {
     }
     // Build URL segments
     const segments = stripped.split('/').filter(Boolean);
-    // Append slug unless it's "index" (index entries collapse to parent)
-    if (slug && slug !== 'index') {
+    // Append slug unless it's an index slug (index entries collapse to parent)
+    if (slug && !isIndexSlug(slug)) {
         segments.push(slug);
     }
     const path = segments.length > 0 ? `/${segments.join('/')}` : '/';
     // Lowercase to match content-listing.ts and content-tree.ts URL conventions
     return path.toLowerCase();
 }
-//# sourceMappingURL=entry-url.js.map

package/dist/utils/error.d.ts

@@ -84,4 +84,3 @@ export declare function isPermissionError(err: unknown): boolean;
  * @returns True if the error is EEXIST (file already exists)
  */
 export declare function isFileExistsError(err: unknown): boolean;
-//# sourceMappingURL=error.d.ts.map

package/dist/utils/error.js

@@ -150,4 +150,3 @@ export function isPermissionError(err) {
 export function isFileExistsError(err) {
     return isNodeError(err) && err.code === 'EEXIST';
 }
-//# sourceMappingURL=error.js.map

package/dist/utils/flatten-group-fields.d.ts

@@ -1,4 +1,4 @@
-import type { FieldConfig } from '../config';
+import type { FieldConfig } from '../config/index.js';
 /**
  * Recursively flatten inline groups out of a field array.
  * Group children are inlined at the parent level — groups are transparent to data.
@@ -10,4 +10,3 @@ import type { FieldConfig } from '../config';
  * Not needed when using traverseFields() — that already handles groups transparently.
  */
 export declare function flattenGroupFields(fields: readonly FieldConfig[]): FieldConfig[];
-//# sourceMappingURL=flatten-group-fields.d.ts.map

package/dist/utils/flatten-group-fields.js

@@ -20,4 +20,3 @@ export function flattenGroupFields(fields) {
     }
     return result;
 }
-//# sourceMappingURL=flatten-group-fields.js.map

package/dist/utils/format.d.ts

@@ -1,4 +1,4 @@
-import type { ContentFormat } from '../config';
+import type { ContentFormat } from '../config/index.js';
 /**
  * Get the file extension for a content format
  * @param format - The content format (md, mdx, json, yaml)
@@ -9,4 +9,3 @@ export declare const getFormatExtension: (format: ContentFormat) => string;
 export declare const isDataOnlyFormat: (format: ContentFormat) => boolean;
 /** Safely coerce a parsed value to a record, returning {} for non-object values */
 export declare const asRecord: (value: unknown) => Record<string, unknown>;
-//# sourceMappingURL=format.d.ts.map

package/dist/utils/format.js

@@ -18,4 +18,3 @@ export const isDataOnlyFormat = (format) => format === 'json' || format === 'yam
 export const asRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
     ? value
     : {};
-//# sourceMappingURL=format.js.map

package/dist/utils/fs.d.ts

@@ -1,3 +1,9 @@
 /** Check if a path exists on disk. */
 export declare function filePathExists(filePath: string): Promise<boolean>;
-//# sourceMappingURL=fs.d.ts.map
+/**
+ * Read a UTF-8 file, or return undefined if it does not exist.
+ *
+ * Only ENOENT is swallowed — a permissions or I/O failure still throws, so a caller cannot
+ * mistake "unreadable" for "not there yet".
+ */
+export declare function readFileIfExists(filePath: string): Promise<string | undefined>;

package/dist/utils/fs.js

@@ -12,4 +12,19 @@ export async function filePathExists(filePath) {
         throw err;
     }
 }
-//# sourceMappingURL=fs.js.map
+/**
+ * Read a UTF-8 file, or return undefined if it does not exist.
+ *
+ * Only ENOENT is swallowed — a permissions or I/O failure still throws, so a caller cannot
+ * mistake "unreadable" for "not there yet".
+ */
+export async function readFileIfExists(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return undefined;
+        throw err;
+    }
+}

package/dist/utils/git.d.ts

@@ -1,4 +1,4 @@
-import type { OperatingMode } from '../operating-mode';
+import type { OperatingMode } from '../operating-mode/index.js';
 /**
  * Whether a git remote URL points at a network location — http(s)://,
  * ssh://, git://, scp-like `[user@]host:path`, a transport-helper `scheme::`
@@ -72,6 +72,23 @@ export declare function isStaleLeaseRejection(message: string): boolean;
  * so callers MUST run git with a locale-pinning env (`gitChildEnv`).
  */
 export declare function isMissingRemoteRefFailure(message: string): boolean;
+/**
+ * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge`
+ * (interactive/merge backend) or `rebase-apply` (am backend) state directory
+ * git leaves behind when a rebase stops for conflicts or the process dies
+ * mid-way.
+ *
+ * This state is invisible to every other check the worker makes: a clone left
+ * mid-rebase reports uncommitted changes, so the sync loop's dirty check skips
+ * it as `skippedDirty` on every cycle forever, and `branch-health` sees valid
+ * branch.json and scans it as healthy. Nothing self-heals, and recovery
+ * previously meant an operator running `git rebase --abort` on EFS by hand.
+ *
+ * Never throws — a missing or unreadable repo is reported as "no rebase",
+ * which is the safe direction for both callers (the worker only ever uses a
+ * `true` to justify an abort it holds the content-write lock for).
+ */
+export declare function isRebaseInProgress(repoPath: string): Promise<boolean>;
 /**
  * Detect the current HEAD branch name for a given repository root.
  * Returns the branch name, or the provided fallback (default 'main')
@@ -98,4 +115,3 @@ export declare function resolveBaseBranch(options: {
     /** Repo root used for dev-mode HEAD detection. Defaults to process.cwd(). */
     detectFrom?: string;
 }): Promise<string>;
-//# sourceMappingURL=git.d.ts.map

package/dist/utils/git.js

@@ -1,3 +1,5 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { simpleGit } from 'simple-git';
 // Matches scheme://... URLs (http, https, ssh, git — case-insensitive).
 const NETWORK_SCHEME_PATTERN = /^(https?|ssh|git):\/\//i;
@@ -137,6 +139,65 @@ const MISSING_REMOTE_REF_REASONS = ["couldn't find remote ref", "Couldn't find r
 export function isMissingRemoteRefFailure(message) {
     return MISSING_REMOTE_REF_REASONS.some((reason) => message.includes(reason));
 }
+/**
+ * Resolve a repository's git directory from its working-tree root, handling
+ * both layouts: a real `.git` directory, and a `.git` FILE containing a
+ * `gitdir: <path>` pointer (linked worktrees, submodules).
+ *
+ * Deliberately fs-only rather than `git rev-parse --git-dir`: the callers are
+ * a per-branch sync loop and an admin-facing health scan that already walk
+ * every branch directory, and neither should pay a subprocess per branch just
+ * to find a path.
+ */
+async function resolveGitDir(repoPath) {
+    const dotGit = path.join(repoPath, '.git');
+    let stat;
+    try {
+        stat = await fs.stat(dotGit);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isDirectory())
+        return dotGit;
+    try {
+        const pointer = await fs.readFile(dotGit, 'utf-8');
+        const match = /^gitdir:\s*(.+)$/m.exec(pointer);
+        if (!match)
+            return null;
+        const target = match[1].trim();
+        return path.isAbsolute(target) ? target : path.resolve(repoPath, target);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge`
+ * (interactive/merge backend) or `rebase-apply` (am backend) state directory
+ * git leaves behind when a rebase stops for conflicts or the process dies
+ * mid-way.
+ *
+ * This state is invisible to every other check the worker makes: a clone left
+ * mid-rebase reports uncommitted changes, so the sync loop's dirty check skips
+ * it as `skippedDirty` on every cycle forever, and `branch-health` sees valid
+ * branch.json and scans it as healthy. Nothing self-heals, and recovery
+ * previously meant an operator running `git rebase --abort` on EFS by hand.
+ *
+ * Never throws — a missing or unreadable repo is reported as "no rebase",
+ * which is the safe direction for both callers (the worker only ever uses a
+ * `true` to justify an abort it holds the content-write lock for).
+ */
+export async function isRebaseInProgress(repoPath) {
+    const gitDir = await resolveGitDir(repoPath);
+    if (!gitDir)
+        return false;
+    const results = await Promise.all(['rebase-merge', 'rebase-apply'].map((dir) => fs
+        .stat(path.join(gitDir, dir))
+        .then(() => true)
+        .catch(() => false)));
+    return results.some(Boolean);
+}
 /**
  * Detect the current HEAD branch name for a given repository root.
  * Returns the branch name, or the provided fallback (default 'main')
@@ -174,4 +235,3 @@ export async function resolveBaseBranch(options) {
     }
     return 'main';
 }
-//# sourceMappingURL=git.js.map

package/dist/utils/logger.d.ts

@@ -68,4 +68,3 @@ export declare function canopyLog(...args: unknown[]): void;
 export declare function canopyLogWarn(...args: unknown[]): void;
 /** Failure worth alerting on. Routes to stderr. */
 export declare function canopyLogError(...args: unknown[]): void;
-//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.js

@@ -82,4 +82,3 @@ export function canopyLogWarn(...args) {
 export function canopyLogError(...args) {
     active.error(...args);
 }
-//# sourceMappingURL=logger.js.map

package/dist/utils/occ-json-write.d.ts

@@ -97,4 +97,3 @@ export declare function withOccRetry<T>(operation: () => Promise<T>, options?: W
  * legitimately take many seconds.
  */
 export declare function withOccFileLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=occ-json-write.d.ts.map

package/dist/utils/occ-json-write.js

@@ -238,4 +238,3 @@ export async function withOccFileLock(filePath, fn) {
         });
     }
 }
-//# sourceMappingURL=occ-json-write.js.map

package/dist/utils/provisioning-lock.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Called when proper-lockfile reports the lock was lost mid-hold (its directory
+ * vanished, or a refresh failed and another holder may have taken over).
+ *
+ * Every call site must decide what that means for ITS critical section, which
+ * is why this is a parameter rather than a fixed policy: a compromise during
+ * idempotent provisioning is survivable, but a compromise during the worker's
+ * rebase means a second writer may be live and the next destructive git step
+ * must not run. What is NOT negotiable is that it must not throw --
+ * proper-lockfile invokes it from inside the refresh timer, so a throw is an
+ * uncaught exception that kills the process.
+ */
+export type OnLockCompromised = (err: Error) => void;
 /**
  * Acquire a cross-process filesystem lock for content provisioning.
  *
@@ -11,10 +24,11 @@
  *
  * Returns a release function — always call it in a `finally`.
  *
- * @param lockTargetDir directory the lock is anchored on (created if missing)
+ * @param lockTargetDir directory the lock marker lives in (created if missing)
  * @param lockName name of the on-disk lock marker, created inside lockTargetDir
+ * @param onCompromised see {@link OnLockCompromised}; defaults to log-and-continue
  */
-export declare function acquireProvisioningLock(lockTargetDir: string, lockName: string): Promise<() => Promise<void>>;
+export declare function acquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;
 /**
  * Zero-retry variant of {@link acquireProvisioningLock}, for admin actions
  * running inside a synchronous request/response cycle (e.g. a Lambda-backed
@@ -33,5 +47,4 @@ export declare function acquireProvisioningLock(lockTargetDir: string, lockName:
  * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale
  * holder) -- callers should translate that into a 409.
  */
-export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string): Promise<() => Promise<void>>;
-//# sourceMappingURL=provisioning-lock.d.ts.map
+export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;

package/dist/utils/provisioning-lock.js

@@ -1,6 +1,90 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import lockfile from 'proper-lockfile';
+import { getErrorMessage, isNodeError } from './error.js';
+import { canopyLogWarn } from './logger.js';
+/**
+ * Shared option set for both provisioning-lock variants.
+ *
+ * **The lock is anchored on the lock file's own path, not its directory.**
+ * proper-lockfile keys its module-level `locks{}` bookkeeping (refresh timer,
+ * release fn) by the TARGET path passed to `lock()` — not by `lockfilePath`.
+ * Passing the shared branches directory made every branch under one root alias
+ * a single registry entry: acquiring `.b.init.lock` overwrote `.a.init.lock`'s
+ * entry, so releasing A tore down B's refresh timer, made B's own release fail
+ * with `ERELEASED`, and leaked B's lock directory on disk until `stale`
+ * expired. The orphaned refresh timer then `stat`ed a path its owner had
+ * already deleted, raising `ECOMPROMISED`. Anchoring here makes the registry
+ * key identical to the on-disk lock identity, so two live locks can never
+ * share a key. `realpath: false` because the anchor path is the lock marker
+ * itself and does not exist before we create it (realpath would ENOENT).
+ * See docs/concurrency.md ("Anchor path matters").
+ */
+function provisioningLockOptions(lockPath, retries, onCompromised) {
+    return {
+        lockfilePath: lockPath,
+        realpath: false,
+        retries,
+        stale: 30_000,
+        // proper-lockfile invokes this from inside its refresh timer, so ANY throw
+        // escaping here is an uncaught exception that kills the process -- the very
+        // failure the handler exists to prevent. Call sites are told not to throw
+        // (see OnLockCompromised); this makes it structural rather than a
+        // convention, and also covers the LOGGER throwing: under `CI=true`,
+        // vitest's `onConsoleLog` turns any console write into a throw.
+        onCompromised: (err) => {
+            try {
+                if (onCompromised) {
+                    onCompromised(err);
+                    return;
+                }
+                // Default: log and let the holder finish. proper-lockfile's own default
+                // rethrows from the refresh timer, which protects nothing -- by the time
+                // a compromise is reported the mutual exclusion is already gone.
+                // `canopyLogWarn` (not the debug logger) because this means "two
+                // holders may now be live": it must be visible without CANOPYCMS_DEBUG.
+                canopyLogWarn(`[canopy] Provisioning lock compromised mid-hold for ${lockPath}:`, getErrorMessage(err));
+            }
+            catch {
+                // Last resort: a raw stderr write goes around both a replaced logger
+                // and vitest's console interception, so the compromise still leaves a
+                // trace. Guarded in turn, because nothing above this line is allowed
+                // to throw out of a refresh timer.
+                try {
+                    process.stderr.write(`[canopy] lock compromised for ${lockPath}; its handler or logger threw\n`);
+                }
+                catch {
+                    // Nothing further is safe to attempt.
+                }
+            }
+        },
+    };
+}
+/**
+ * proper-lockfile's release rejects with `ERELEASED` once the lock has been
+ * marked compromised (`setLockAsCompromised` sets `released = true` before the
+ * caller ever gets to release). Callers hold this in a `finally`, so letting
+ * that escape would convert a COMPLETED operation into a spurious failure.
+ * There is nothing left to release in that state, so swallow just that code and
+ * let every other release error propagate to the caller that asked for it.
+ */
+function releaseIgnoringAlreadyReleased(release, lockPath) {
+    return async () => {
+        try {
+            await release();
+        }
+        catch (err) {
+            if (isNodeError(err) && err.code === 'ERELEASED') {
+                // Deliberately does not name a cause: ERELEASED is raised both by a
+                // lock compromised mid-hold AND by a plain double-release bug, and
+                // from here the two are indistinguishable.
+                canopyLogWarn(`[canopy] Lock at ${lockPath} was already released (compromised mid-hold, or released twice); nothing to release`);
+                return;
+            }
+            throw err;
+        }
+    };
+}
 /**
  * Acquire a cross-process filesystem lock for content provisioning.
  *
@@ -14,22 +98,21 @@ import lockfile from 'proper-lockfile';
  *
  * Returns a release function — always call it in a `finally`.
  *
- * @param lockTargetDir directory the lock is anchored on (created if missing)
+ * @param lockTargetDir directory the lock marker lives in (created if missing)
  * @param lockName name of the on-disk lock marker, created inside lockTargetDir
+ * @param onCompromised see {@link OnLockCompromised}; defaults to log-and-continue
  */
-export async function acquireProvisioningLock(lockTargetDir, lockName) {
+export async function acquireProvisioningLock(lockTargetDir, lockName, onCompromised) {
     await fs.mkdir(lockTargetDir, { recursive: true });
+    const lockPath = path.join(lockTargetDir, lockName);
     // Generous, jittered retries: many waiters (one per build worker process, each
     // prerendering several pages) may contend, and the holder can take several
     // seconds to init + clone/push. `randomize` de-syncs the herd so a waiter isn't
     // perpetually colliding on the same tick. `stale` stays modest because proper-
     // lockfile auto-refreshes a live holder's lock, so it only expires when a
     // process actually dies.
-    return lockfile.lock(lockTargetDir, {
-        lockfilePath: path.join(lockTargetDir, lockName),
-        retries: { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true },
-        stale: 30_000,
-    });
+    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised));
+    return releaseIgnoringAlreadyReleased(release, lockPath);
 }
 /**
  * Zero-retry variant of {@link acquireProvisioningLock}, for admin actions
@@ -49,12 +132,9 @@ export async function acquireProvisioningLock(lockTargetDir, lockName) {
  * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale
  * holder) -- callers should translate that into a 409.
  */
-export async function tryAcquireProvisioningLock(lockTargetDir, lockName) {
+export async function tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised) {
     await fs.mkdir(lockTargetDir, { recursive: true });
-    return lockfile.lock(lockTargetDir, {
-        lockfilePath: path.join(lockTargetDir, lockName),
-        retries: 0,
-        stale: 30_000,
-    });
+    const lockPath = path.join(lockTargetDir, lockName);
+    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised));
+    return releaseIgnoringAlreadyReleased(release, lockPath);
 }
-//# sourceMappingURL=provisioning-lock.js.map

package/dist/utils/sanitize-href.d.ts

@@ -7,7 +7,7 @@
  * equivalent to forward slash for special schemes, so `/\evil.com`, `\\evil.com` and `\/evil.com`
  * are all protocol-relative in effect despite declaring no scheme). Exported so every "is this
  * URL off-site" check in the package shares one answer instead of re-deriving it -- see
- * `isImplicitlyOffOrigin` below and `static/seo.ts`'s `isAbsoluteUrl`.
+ * `isImplicitlyOffOrigin` below and `utils/url-prefix.ts`'s `isAbsoluteUrl`.
  */
 export declare function declaresScheme(url: string): boolean;
 /**
@@ -22,7 +22,7 @@ export declare function declaresScheme(url: string): boolean;
  * (`declaresScheme` already identifies those as intentionally off-site on their own).
  *
  * Callers that want to treat a LITERAL `//host` as an intentionally-supported off-site pointer
- * (e.g. `static/seo.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
+ * (e.g. `utils/url-prefix.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
  * separately and only fall back to this function to catch the spellings that slip past a
  * `startsWith('//')` check.
  */
@@ -87,4 +87,3 @@ export declare function neutralizeImplicitOffOrigin(url: string): string;
  * ```
  */
 export declare function sanitizeHref(url: string, fallback?: string): string;
-//# sourceMappingURL=sanitize-href.d.ts.map

package/dist/utils/sanitize-href.js

@@ -11,7 +11,7 @@ const SENTINEL_BASE = 'https://relative.invalid';
  * equivalent to forward slash for special schemes, so `/\evil.com`, `\\evil.com` and `\/evil.com`
  * are all protocol-relative in effect despite declaring no scheme). Exported so every "is this
  * URL off-site" check in the package shares one answer instead of re-deriving it -- see
- * `isImplicitlyOffOrigin` below and `static/seo.ts`'s `isAbsoluteUrl`.
+ * `isImplicitlyOffOrigin` below and `utils/url-prefix.ts`'s `isAbsoluteUrl`.
  */
 export function declaresScheme(url) {
     return /^[a-z][a-z0-9+.-]*:/i.test(url.trim());
@@ -28,7 +28,7 @@ export function declaresScheme(url) {
  * (`declaresScheme` already identifies those as intentionally off-site on their own).
  *
  * Callers that want to treat a LITERAL `//host` as an intentionally-supported off-site pointer
- * (e.g. `static/seo.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
+ * (e.g. `utils/url-prefix.ts`'s `isAbsoluteUrl`, for a CDN-hosted `ogImage`) should check that
  * separately and only fall back to this function to catch the spellings that slip past a
  * `startsWith('//')` check.
  */
@@ -146,4 +146,3 @@ export function sanitizeHref(url, fallback = '#') {
     }
     return fallback;
 }
-//# sourceMappingURL=sanitize-href.js.map

package/dist/utils/title-field.d.ts

@@ -1,4 +1,4 @@
-import type { FieldConfig } from '../config';
+import type { FieldConfig } from '../config/index.js';
 /**
  * Find the field marked `isTitle: true` in a schema and extract its value from data.
  * Recurses into object fields to support nested title fields (e.g., hero.title).
@@ -37,4 +37,3 @@ export declare function findInvalidTitleFields(fields: readonly FieldConfig[], p
  * Returns dotted paths of such fields.
  */
 export declare function findTitleFieldsInLists(fields: readonly FieldConfig[], parentPath?: string): string[];
-//# sourceMappingURL=title-field.d.ts.map