canopycms 0.0.61-int.75 → 0.0.62

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

@@ -0,0 +1,170 @@
+/**
+ * [SYNC-C1] Cross-host mutual exclusion between the worker's rebase loop and
+ * content writes against the same branch working tree.
+ *
+ * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem.
+ * `ContentStore`'s write/delete/rename critical sections were guarded only by
+ * the in-process mutex (`utils/async-mutex`), which does not cross that
+ * boundary, while `CmsWorker.rebaseActiveBranches()` rewrites the very same
+ * working tree. A write landing after `git rebase` started is destroyed two
+ * ways -- `git checkout --theirs <file>` overwrites it with the branch's
+ * committed version (and the rebase then SUCCEEDS, logging nothing), and
+ * `git rebase --abort` hard-resets the tree. Either way the editor already got
+ * its 200. This lock is what serializes the two.
+ *
+ * **Asymmetric by design.** The worker retries every branch on its next sync
+ * cycle (~5 minutes) while the editor is a person waiting on a save, so the
+ * worker yields and the writer waits:
+ *
+ * - Worker: {@link tryAcquireContentWriteLock} -- zero retries. On contention
+ *   it skips that branch this cycle (an extension of the existing
+ *   skip-dirty-branches behavior) and picks it up next cycle.
+ * - Writers: {@link withContentWriteLock} -- a short bounded wait, then a
+ *   retriable failure the API surfaces as a 409.
+ *
+ * **Reads never take this lock.** An extra EFS round-trip on every read is not
+ * 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`
+ *
+ * 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
+ * - no deadlock potential: the two locks are never both required, and the only
+ *   possible acquisition order (provision, then write) is consistent.
+ *
+ * `.canopy-meta/` is git-excluded in every branch clone (`ensureGitExclude`),
+ * so the lock directory can never dirty the working tree or be swept into
+ * `git add .` at publish time.
+ *
+ * ## Honest caveat (do not oversell this)
+ *
+ * `proper-lockfile` decides a holder is dead by reading the lock directory's
+ * mtime with `fs.stat`, which on EFS is served through the NFS attribute
+ * cache. A live holder refreshes every `stale/2`, but a waiter can read a
+ * cached mtime and conclude the lock is stale when it is not, taking it over.
+ * The failure mode of a bad takeover is exactly today's behavior (two
+ * unsynchronized writers), so this is a strict improvement -- not a proof of
+ * mutual exclusion. See docs/concurrency.md.
+ */
+import path from 'node:path';
+import { isNodeError } from './error.js';
+import { tryAcquireProvisioningLock } from './provisioning-lock.js';
+/** Directory the lock marker lives in, relative to the branch root. */
+const META_DIR = '.canopy-meta';
+/** On-disk name of the lock marker (a directory, created by mkdir). */
+export const CONTENT_WRITE_LOCK_NAME = 'content-write.lock';
+/**
+ * Default bounded wait for a content write.
+ *
+ * Deliberately short. A rebase holds this lock for a fetch plus a replay plus
+ * N conflict rounds of git subprocesses on EFS -- far longer than any wait an
+ * interactive save can absorb, and longer than the API's own latency budget.
+ * So the wait is not sized to outlast a rebase (nothing reasonable could); it
+ * is sized to absorb lock handoff and the short holds of other writers, and to
+ * turn everything longer into a fast, explicit "retry" the editor can act on
+ * rather than a request that hangs toward the Lambda timeout. The worker
+ * revisits the branch next cycle, so the blocked state is transient.
+ *
+ * This is ALSO the writer-vs-writer budget, not only the rebase one. The lock
+ * is per-branch-root, so every write to one branch now serializes behind it
+ * where in-process serialization used to be per-entry -- bounded on Lambda
+ * (one invocation per container), but real under `next dev` and build-time
+ * provisioning across worker processes. The case to watch is a write whose
+ * in-lock path triggers a full `idIndex()` rescan of a large tree over EFS:
+ * that can plausibly exceed this budget and start 409ing unrelated saves.
+ * Making it configurable for prod tuning is tracked in
+ * .claude/future-tasks/content-write-lock-tuning-and-granularity.md.
+ */
+export const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
+/**
+ * Thrown when the bounded wait expires with the branch's content lock still
+ * held. Retriable -- callers translate this into a 409 with a message that
+ * says so.
+ *
+ * The message says "syncing OR another save" because BOTH produce it. The
+ * lock is taken by `write`/`delete`/`renameEntry` and by the admin
+ * repair-content-duplicates action as well as by the worker's rebase, so a
+ * message naming only the rebase was a confident claim about something that
+ * may not be happening. `api/content.ts` routes this error ahead of the
+ * generic conflict specifically so the editor sees this wording, which makes
+ * the wording load-bearing rather than cosmetic.
+ */
+export class ContentWriteLockBusyError 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.') {
+        super(message);
+        this.name = 'ContentWriteLockBusyError';
+    }
+}
+/** The directory proper-lockfile anchors on -- also its in-process registry key. */
+function lockTargetDir(branchRoot) {
+    return path.join(path.resolve(branchRoot), META_DIR);
+}
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Acquire the branch's content-write lock WITHOUT waiting.
+ *
+ * Throws an error with `code === 'ELOCKED'` when a live holder has it. Used by
+ * 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);
+}
+/**
+ * Acquire the branch's content-write lock with a short bounded wait.
+ *
+ * Retries ONLY on genuine contention (`ELOCKED`), the same discipline
+ * `withOccFileLock` uses: proper-lockfile's own retry loop retries blindly on
+ * any error, which would burn the whole budget re-hitting e.g. ENOENT after
+ * the branch directory was deleted out from under the caller.
+ *
+ * @throws ContentWriteLockBusyError when the budget expires under contention.
+ */
+export async function acquireContentWriteLock(branchRoot, waitMs = DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS) {
+    const startedAt = Date.now();
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await tryAcquireContentWriteLock(branchRoot);
+        }
+        catch (err) {
+            if (!isNodeError(err) || err.code !== 'ELOCKED')
+                throw err;
+            const remaining = waitMs - (Date.now() - startedAt);
+            if (remaining <= 0)
+                throw new ContentWriteLockBusyError();
+            // Exponential backoff with jitter, capped so a long budget still polls
+            // often enough to pick the lock up promptly when the holder releases.
+            const base = Math.min(40 * 2 ** attempt, 250);
+            await sleep(Math.min(base * (0.5 + Math.random()), remaining));
+        }
+    }
+}
+/**
+ * Run `fn` holding the branch's content-write lock, releasing it in a
+ * `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);
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=content-write-lock.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content-write-lock.js","sourceRoot":"","sources":["../../src/utils/content-write-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAA;AAEhE,uEAAuE;AACvE,MAAM,QAAQ,GAAG,cAAc,CAAA;AAE/B,uEAAuE;AACvE,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,IAAI,CAAA;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YACE,OAAO,GAAG,oIAAoI;QAE9I,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAA;IACzC,CAAC;CACF;AAED,oFAAoF;AACpF,SAAS,aAAa,CAAC,UAAkB;IACvC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,CAAA;AACtD,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAC1C,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;IACtB,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;AACzB,CAAC,CAAC,CAAA;AAEJ;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,UAAkB;IAC3D,OAAO,0BAA0B,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,uBAAuB,CAAC,CAAA;AACvF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,UAAkB,EAClB,SAAiB,kCAAkC;IAEnD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;IAC5B,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,OAAO,MAAM,0BAA0B,CAAC,UAAU,CAAC,CAAA;QACrD,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;gBAAE,MAAM,GAAG,CAAA;YAC1D,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAA;YACnD,IAAI,SAAS,IAAI,CAAC;gBAAE,MAAM,IAAI,yBAAyB,EAAE,CAAA;YACzD,uEAAuE;YACvE,sEAAsE;YACtE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,IAAI,OAAO,EAAE,GAAG,CAAC,CAAA;YAC7C,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC,CAAA;QAChE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,UAAkB,EAClB,EAAoB,EACpB,SAAiB,kCAAkC;IAEnD,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;IACjE,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAA;IACnB,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAA;IACjB,CAAC;AACH,CAAC"}

package/dist/utils/debug.d.ts

@@ -14,6 +14,17 @@ export declare class DebugLogger {
     private timers;
     constructor(options?: DebugOptions);
     private shouldLog;
+    /**
+     * The ISO-8601 timestamp leads the line BARE - not wrapped in brackets as it
+     * once was. `CANOPYCMS_DEBUG=true` can be set on the EC2 worker, whose stdout
+     * appends to /var/log/canopy-worker/worker.log; the CloudWatch agent's
+     * `multi_line_start_pattern` matches the timestamp at the START of a line
+     * (see worker/log.ts's INVARIANT and cms-service.ts's agent config), so a
+     * leading `[` meant every debug line was silently folded into the previous
+     * event instead of starting its own. The bracketed `[prefix:category]` and
+     * `[level]` fields still follow, so the human-readable shape is unchanged
+     * apart from those two characters.
+     */
     private formatMessage;
     debug(category: string, message: string, data?: unknown): void;
     info(category: string, message: string, data?: unknown): void;

package/dist/utils/debug.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AASD,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,MAAM,CAAiC;gBAEnC,OAAO,GAAE,YAAiB;IAItC,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,aAAa;IAMrB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMvD,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMtD,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMtD,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAcvD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM;IAIlB;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAavC;;OAEG;IACG,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAQlF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CAErE;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,aAIrB,CAAA"}
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAE1D,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AASD,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,MAAM,CAAiC;gBAEnC,OAAO,GAAE,YAAiB;IAItC,OAAO,CAAC,SAAS;IASjB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;IAMrB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMvD,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMtD,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAMtD,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAcvD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM;IAIlB;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAavC;;OAEG;IACG,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAQlF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CAErE;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,aAIrB,CAAA"}

package/dist/utils/debug.js

@@ -17,10 +17,21 @@ export class DebugLogger {
         const minLevel = this.options.minLevel ?? 'DEBUG';
         return LOG_LEVELS[level] >= LOG_LEVELS[minLevel];
     }
+    /**
+     * The ISO-8601 timestamp leads the line BARE - not wrapped in brackets as it
+     * once was. `CANOPYCMS_DEBUG=true` can be set on the EC2 worker, whose stdout
+     * appends to /var/log/canopy-worker/worker.log; the CloudWatch agent's
+     * `multi_line_start_pattern` matches the timestamp at the START of a line
+     * (see worker/log.ts's INVARIANT and cms-service.ts's agent config), so a
+     * leading `[` meant every debug line was silently folded into the previous
+     * event instead of starting its own. The bracketed `[prefix:category]` and
+     * `[level]` fields still follow, so the human-readable shape is unchanged
+     * apart from those two characters.
+     */
     formatMessage(level, category, message) {
         const timestamp = new Date().toISOString();
         const prefix = this.options.prefix ?? 'CanopyCMS';
-        return `[${timestamp}] [${prefix}:${category}] [${level}] ${message}`;
+        return `${timestamp} [${prefix}:${category}] [${level}] ${message}`;
     }
     debug(category, message, data) {
         if (this.shouldLog('DEBUG')) {

package/dist/utils/debug.js.map

@@ -1 +1 @@
-{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/utils/debug.ts"],"names":[],"mappings":"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"}

package/dist/utils/error.d.ts

@@ -15,7 +15,7 @@
  * try {
  *   await riskyOperation()
  * } catch (err: unknown) {
- *   console.error('Operation failed:', getErrorMessage(err))
+ *   canopyLogError('Operation failed:', getErrorMessage(err))
  * }
  * ```
  */

package/dist/utils/error.js

@@ -15,7 +15,7 @@
  * try {
  *   await riskyOperation()
  * } catch (err: unknown) {
- *   console.error('Operation failed:', getErrorMessage(err))
+ *   canopyLogError('Operation failed:', getErrorMessage(err))
  * }
  * ```
  */

package/dist/utils/git.d.ts

@@ -18,6 +18,60 @@ import type { OperatingMode } from '../operating-mode';
  * `@`-required heuristic for scp-like syntax.
  */
 export declare function isNetworkRemoteUrl(url: string): boolean;
+/**
+ * Whether a git push failure message is git's non-fast-forward rejection --
+ * the remote has diverged (moved ahead with commits this side never fetched),
+ * so retrying the IDENTICAL push can never succeed. In CanopyCMS this is the
+ * signature of two CanopyCMS deployments sharing one GitHub repo and picking
+ * the same content-branch name, or someone pushing directly to GitHub.
+ *
+ * Deliberately narrow: ordinary transient push failures -- network drops,
+ * auth/permission denial, lock contention -- must keep retrying with backoff
+ * (see worker/cms-worker.ts's `isPermanentTaskFailure`, which treats git
+ * failures as transient precisely so those cases still get retried). Only
+ * this specific, structurally-unretryable shape should fail fast (worker) or
+ * return 409 (API) instead.
+ *
+ * Matches git's literal (English) rejection text, which is gettext-
+ * translated -- callers MUST run the underlying git command with a
+ * locale-pinning env (see `gitChildEnv` in `../git-manager.ts`) or an ambient
+ * LANG/LC_ALL could silently turn this into a permanent no-op.
+ */
+export declare function isNonFastForwardRejection(message: string): boolean;
+/**
+ * Whether a git push failure message is a refused `--force-with-lease` --
+ * the remote ref is NOT at the commit the pusher expected, so the forced
+ * update was declined and nothing was overwritten.
+ *
+ * A SEPARATE predicate from `isNonFastForwardRejection` because git's output
+ * for the two is disjoint: a refused lease prints
+ * ` ! [rejected]        branch -> branch (stale info)` and, unlike an
+ * ordinary rejection, emits NEITHER `non-fast-forward`/`fetch first` NOR the
+ * `Updates were rejected because` hint. Without this predicate every lease
+ * refusal would be classified transient and retried -- three identical,
+ * guaranteed-to-fail force attempts -- instead of surfacing as the permanent,
+ * human-actionable state it is.
+ *
+ * Same locale caveat as above: the reason text is gettext-translated, so
+ * callers MUST pin the locale (`gitChildEnv`/`gitNetworkChildEnv`).
+ */
+export declare function isStaleLeaseRejection(message: string): boolean;
+/**
+ * Whether a `git fetch <remote> <branch>` failure is specifically "that ref
+ * doesn't exist on the remote" -- the ONLY benign fetch outcome, meaning the
+ * branch has never been pushed.
+ *
+ * Narrow on purpose, and the narrowness is the whole point. This predicate
+ * exists because a bare `catch` around the fetch classified EVERY failure --
+ * unreachable remote, auth denial, permission error on the workspace, corrupt
+ * object store -- as "nothing to pull", which callers then logged as normal
+ * and proceeded past. Anything this does not recognize must reach the caller
+ * as the genuine error it is.
+ *
+ * Same locale caveat as the predicates above: the text is gettext-translated,
+ * so callers MUST run git with a locale-pinning env (`gitChildEnv`).
+ */
+export declare function isMissingRemoteRefFailure(message: string): boolean;
 /**
  * Detect the current HEAD branch name for a given repository root.
  * Returns the branch name, or the provided fallback (default 'main')

package/dist/utils/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAmBtD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAe,GACxB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,IAAI,EAAE,aAAa,CAAA;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMlB"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAmBtD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOvD;AAyBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAKlE;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE9D;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAElE;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAe,GACxB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,IAAI,EAAE,aAAa,CAAA;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAMlB"}

package/dist/utils/git.js

@@ -46,6 +46,97 @@ export function isNetworkRemoteUrl(url) {
         return false;
     return COLON_BEFORE_SLASH_PATTERN.test(url);
 }
+// Matches git's per-ref push-status summary line marking a ref as rejected.
+// Present verbatim in BOTH output shapes CanopyCMS's push call sites produce:
+// the plain CLI form (`GitManager.push()`'s `.raw(['push', ...])`, e.g.
+// ` ! [rejected]        branch -> branch (non-fast-forward)`) and the
+// machine-readable `--porcelain` form simple-git's `.push()` wrapper requests
+// (`CmsWorker.pushBranchToGitHub`/`pushSettingsBranches`, e.g.
+// `!\trefs/heads/branch:refs/heads/branch\t[rejected] (non-fast-forward)`) --
+// `--porcelain` only changes the per-ref summary's leading fields, not this
+// trailing human-readable bracket text.
+const REJECTED_MARKER = '[rejected]';
+// git's two names for the SAME underlying condition: `non-fast-forward` fires
+// when the pusher's own remote-tracking ref is present but stale;
+// `fetch first` fires when no local knowledge of the remote ref exists at all
+// (e.g. it was never fetched). Both mean the remote has commits this side
+// doesn't have -- retrying the identical push can never succeed until the
+// caller fetches and integrates (or picks a different branch name).
+const NON_FAST_FORWARD_REASONS = ['non-fast-forward', 'fetch first'];
+// git always prints this stderr hint immediately after a rejected push,
+// regardless of --porcelain (porcelain only affects the machine-readable
+// summary line, not the human hint text that follows it) -- a second,
+// independent signal for the same condition.
+const REJECTION_HINT = 'Updates were rejected because';
+/**
+ * Whether a git push failure message is git's non-fast-forward rejection --
+ * the remote has diverged (moved ahead with commits this side never fetched),
+ * so retrying the IDENTICAL push can never succeed. In CanopyCMS this is the
+ * signature of two CanopyCMS deployments sharing one GitHub repo and picking
+ * the same content-branch name, or someone pushing directly to GitHub.
+ *
+ * Deliberately narrow: ordinary transient push failures -- network drops,
+ * auth/permission denial, lock contention -- must keep retrying with backoff
+ * (see worker/cms-worker.ts's `isPermanentTaskFailure`, which treats git
+ * failures as transient precisely so those cases still get retried). Only
+ * this specific, structurally-unretryable shape should fail fast (worker) or
+ * return 409 (API) instead.
+ *
+ * Matches git's literal (English) rejection text, which is gettext-
+ * translated -- callers MUST run the underlying git command with a
+ * locale-pinning env (see `gitChildEnv` in `../git-manager.ts`) or an ambient
+ * LANG/LC_ALL could silently turn this into a permanent no-op.
+ */
+export function isNonFastForwardRejection(message) {
+    const hasNonFastForwardRejection = message.includes(REJECTED_MARKER) &&
+        NON_FAST_FORWARD_REASONS.some((reason) => message.includes(reason));
+    return hasNonFastForwardRejection || message.includes(REJECTION_HINT);
+}
+// git's reason text when a `--force-with-lease=<ref>:<sha>` push is refused
+// because the remote is not at `<sha>`.
+const STALE_LEASE_REASON = 'stale info';
+/**
+ * Whether a git push failure message is a refused `--force-with-lease` --
+ * the remote ref is NOT at the commit the pusher expected, so the forced
+ * update was declined and nothing was overwritten.
+ *
+ * A SEPARATE predicate from `isNonFastForwardRejection` because git's output
+ * for the two is disjoint: a refused lease prints
+ * ` ! [rejected]        branch -> branch (stale info)` and, unlike an
+ * ordinary rejection, emits NEITHER `non-fast-forward`/`fetch first` NOR the
+ * `Updates were rejected because` hint. Without this predicate every lease
+ * refusal would be classified transient and retried -- three identical,
+ * guaranteed-to-fail force attempts -- instead of surfacing as the permanent,
+ * human-actionable state it is.
+ *
+ * Same locale caveat as above: the reason text is gettext-translated, so
+ * callers MUST pin the locale (`gitChildEnv`/`gitNetworkChildEnv`).
+ */
+export function isStaleLeaseRejection(message) {
+    return message.includes(REJECTED_MARKER) && message.includes(STALE_LEASE_REASON);
+}
+// git's message when `git fetch <remote> <branch>` names a ref the remote does
+// not have. Both spellings occur: modern git prints the lowercase form, older
+// versions and some transports capitalize it.
+const MISSING_REMOTE_REF_REASONS = ["couldn't find remote ref", "Couldn't find remote ref"];
+/**
+ * Whether a `git fetch <remote> <branch>` failure is specifically "that ref
+ * doesn't exist on the remote" -- the ONLY benign fetch outcome, meaning the
+ * branch has never been pushed.
+ *
+ * Narrow on purpose, and the narrowness is the whole point. This predicate
+ * exists because a bare `catch` around the fetch classified EVERY failure --
+ * unreachable remote, auth denial, permission error on the workspace, corrupt
+ * object store -- as "nothing to pull", which callers then logged as normal
+ * and proceeded past. Anything this does not recognize must reach the caller
+ * as the genuine error it is.
+ *
+ * Same locale caveat as the predicates above: the text is gettext-translated,
+ * so callers MUST run git with a locale-pinning env (`gitChildEnv`).
+ */
+export function isMissingRemoteRefFailure(message) {
+    return MISSING_REMOTE_REF_REASONS.some((reason) => message.includes(reason));
+}
 /**
  * Detect the current HEAD branch name for a given repository root.
  * Returns the branch name, or the provided fallback (default 'main')

package/dist/utils/git.js.map

@@ -1 +1 @@
-{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAItC,wEAAwE;AACxE,MAAM,sBAAsB,GAAG,yBAAyB,CAAA;AACxD,6EAA6E;AAC7E,8EAA8E;AAC9E,6DAA6D;AAC7D,MAAM,wBAAwB,GAAG,uBAAuB,CAAA;AACxD,4EAA4E;AAC5E,4EAA4E;AAC5E,MAAM,sBAAsB,GAAG,IAAI,CAAA;AACnC,uEAAuE;AACvE,6EAA6E;AAC7E,8EAA8E;AAC9E,uEAAuE;AACvE,8BAA8B;AAC9B,MAAM,qBAAqB,GAAG,iBAAiB,CAAA;AAC/C,MAAM,0BAA0B,GAAG,aAAa,CAAA;AAEhD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAA;IACzC,IAAI,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjD,IAAI,wBAAwB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACnD,IAAI,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjD,IAAI,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAA;IACjD,OAAO,0BAA0B,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAgB,EAChB,WAAmB,MAAM;IAEzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,SAAS,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC5C,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAClE,OAAO,IAAI,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAA;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAA;IACjB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAKvC;IACC,IAAI,OAAO,CAAC,iBAAiB;QAAE,OAAO,OAAO,CAAC,iBAAiB,CAAA;IAC/D,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAC3B,OAAO,gBAAgB,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAC9D,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/utils/git.ts"],"names":[],"mappings":"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"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Process-scoped logger indirection for modules that run in BOTH the worker
+ * daemon and the Lambda/dev server.
+ *
+ * ## Why this exists
+ *
+ * `worker/log.ts` documents a hard invariant: every line written to
+ * `/var/log/canopy-worker/worker.log` must start with an ISO-8601 timestamp,
+ * because the CloudWatch agent's `multi_line_start_pattern` is keyed on that
+ * prefix (see `canopycms-cdk/src/constructs/cms-service.ts`). A line WITHOUT
+ * the prefix is not a new event - it is appended to the PREVIOUS one,
+ * inheriting that event's timestamp and carrying none of its own severity tag.
+ *
+ * The worker's own code honoured that by calling `workerLog*`. But the worker
+ * process also executes shared modules that were never worker-specific and
+ * called bare `console.warn`: `github-service.ts` (the throttling plugin's
+ * rate-limit callbacks fire on the worker's own Octokit, and the PR
+ * create/update path runs on the worker's submit task) and `branch-registry.ts`
+ * (registry regeneration, reached from every worker `meta.save()`). Their
+ * output landed in worker.log unprefixed, so an operationally interesting
+ * warning - "GitHub throttled us" - was silently folded into a minutes-old
+ * event and became invisible to `filter @message like /WARN/`. Invisible
+ * locally too, since vitest intercepts console.
+ *
+ * ## Why process-scoped rather than a threaded parameter
+ *
+ * The invariant is a property of the PROCESS's stdout/stderr, not of any
+ * particular call: the same `branch-registry.ts` line is correct as bare
+ * console under Lambda and wrong under the worker. Threading a logger down to
+ * it would mean touching every signature between `CmsWorker.rebase*` and
+ * `BranchMetadataFileManager.loadOnly` to carry a logging concern. One
+ * process-wide switch, set once at the worker entrypoint, expresses exactly
+ * the thing that is actually true.
+ *
+ * Lambda and the dev server install nothing and keep plain `console`, which is
+ * correct there - CloudWatch's Lambda integration stamps and delimits events
+ * on its own.
+ *
+ * ## Usage
+ *
+ * Shared server-side modules call `canopyLogWarn`/`canopyLogError`/`canopyLog`
+ * instead of `console.*`. The worker entrypoint calls `installWorkerLogger()`
+ * (`worker/log.ts`, re-exported from `worker/cms-worker.ts`) once, before doing
+ * any work.
+ *
+ * Not for browser/editor code: those keep `console` directly. This module is
+ * dependency-free so importing it can never drag a server-only dependency into
+ * a client bundle, but there is nothing for it to do in a browser.
+ */
+/** The three levels the shared modules use. Structurally satisfied by `console`. */
+export interface CanopyLogger {
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * Route subsequent `canopyLog*` calls through `logger`. Idempotent, and safe to
+ * call after the modules that use the helpers have already been imported.
+ */
+export declare function setCanopyLogger(logger: CanopyLogger): void;
+/** Restore the default (`console`). Exists for tests; production installs once and never reverts. */
+export declare function resetCanopyLogger(): void;
+/** The logger currently installed. Exported for assertions; prefer the helpers below. */
+export declare function getCanopyLogger(): CanopyLogger;
+/** Informational. Routes to stdout (or the worker's timestamped stdout). */
+export declare function canopyLog(...args: unknown[]): void;
+/** Recoverable problem - the caller carries on. Routes to stderr. */
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC7B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAChC;AAWD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED,qGAAqG;AACrG,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,yFAAyF;AACzF,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAElD;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAEtD;AAED,mDAAmD;AACnD,wBAAgB,cAAc,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAEvD"}

package/dist/utils/logger.js

@@ -0,0 +1,85 @@
+/**
+ * Process-scoped logger indirection for modules that run in BOTH the worker
+ * daemon and the Lambda/dev server.
+ *
+ * ## Why this exists
+ *
+ * `worker/log.ts` documents a hard invariant: every line written to
+ * `/var/log/canopy-worker/worker.log` must start with an ISO-8601 timestamp,
+ * because the CloudWatch agent's `multi_line_start_pattern` is keyed on that
+ * prefix (see `canopycms-cdk/src/constructs/cms-service.ts`). A line WITHOUT
+ * the prefix is not a new event - it is appended to the PREVIOUS one,
+ * inheriting that event's timestamp and carrying none of its own severity tag.
+ *
+ * The worker's own code honoured that by calling `workerLog*`. But the worker
+ * process also executes shared modules that were never worker-specific and
+ * called bare `console.warn`: `github-service.ts` (the throttling plugin's
+ * rate-limit callbacks fire on the worker's own Octokit, and the PR
+ * create/update path runs on the worker's submit task) and `branch-registry.ts`
+ * (registry regeneration, reached from every worker `meta.save()`). Their
+ * output landed in worker.log unprefixed, so an operationally interesting
+ * warning - "GitHub throttled us" - was silently folded into a minutes-old
+ * event and became invisible to `filter @message like /WARN/`. Invisible
+ * locally too, since vitest intercepts console.
+ *
+ * ## Why process-scoped rather than a threaded parameter
+ *
+ * The invariant is a property of the PROCESS's stdout/stderr, not of any
+ * particular call: the same `branch-registry.ts` line is correct as bare
+ * console under Lambda and wrong under the worker. Threading a logger down to
+ * it would mean touching every signature between `CmsWorker.rebase*` and
+ * `BranchMetadataFileManager.loadOnly` to carry a logging concern. One
+ * process-wide switch, set once at the worker entrypoint, expresses exactly
+ * the thing that is actually true.
+ *
+ * Lambda and the dev server install nothing and keep plain `console`, which is
+ * correct there - CloudWatch's Lambda integration stamps and delimits events
+ * on its own.
+ *
+ * ## Usage
+ *
+ * Shared server-side modules call `canopyLogWarn`/`canopyLogError`/`canopyLog`
+ * instead of `console.*`. The worker entrypoint calls `installWorkerLogger()`
+ * (`worker/log.ts`, re-exported from `worker/cms-worker.ts`) once, before doing
+ * any work.
+ *
+ * Not for browser/editor code: those keep `console` directly. This module is
+ * dependency-free so importing it can never drag a server-only dependency into
+ * a client bundle, but there is nothing for it to do in a browser.
+ */
+/**
+ * Deliberately mutable module state, read at CALL time by the helpers below
+ * rather than captured at import time. Module import order is not something a
+ * call site controls, so a captured reference would mean whether a line got its
+ * prefix depended on whether `github-service.ts` happened to be imported before
+ * or after the entrypoint installed the worker logger.
+ */
+let active = console;
+/**
+ * Route subsequent `canopyLog*` calls through `logger`. Idempotent, and safe to
+ * call after the modules that use the helpers have already been imported.
+ */
+export function setCanopyLogger(logger) {
+    active = logger;
+}
+/** Restore the default (`console`). Exists for tests; production installs once and never reverts. */
+export function resetCanopyLogger() {
+    active = console;
+}
+/** The logger currently installed. Exported for assertions; prefer the helpers below. */
+export function getCanopyLogger() {
+    return active;
+}
+/** Informational. Routes to stdout (or the worker's timestamped stdout). */
+export function canopyLog(...args) {
+    active.log(...args);
+}
+/** Recoverable problem - the caller carries on. Routes to stderr. */
+export function canopyLogWarn(...args) {
+    active.warn(...args);
+}
+/** Failure worth alerting on. Routes to stderr. */
+export function canopyLogError(...args) {
+    active.error(...args);
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AASH;;;;;;GAMG;AACH,IAAI,MAAM,GAAiB,OAAO,CAAA;AAElC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,MAAM,GAAG,MAAM,CAAA;AACjB,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,OAAO,CAAA;AAClB,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,eAAe;IAC7B,OAAO,MAAM,CAAA;AACf,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,SAAS,CAAC,GAAG,IAAe;IAC1C,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;AACrB,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,GAAG,IAAe;IAC9C,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;AACtB,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,cAAc,CAAC,GAAG,IAAe;IAC/C,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAA;AACvB,CAAC"}