canopycms 0.0.67 → 0.0.68-int.93

package/dist/types.d.ts

@@ -102,6 +102,24 @@ export interface BranchContext extends BranchPaths {
 export interface BranchContextWithSchema extends BranchContext {
     flatSchema: import('./config/index.js').FlatSchemaItem[];
 }
+/**
+ * Outcome of the worker's per-cycle fast-forward of the base branch's own clone
+ * (worker/git-sync.ts's `refreshBaseBranchWorkspace`); the rebase loop skips
+ * that clone.
+ */
+export interface BaseRefreshReport {
+    outcome: 'refreshed' | 'up-to-date' | 'skipped-dirty' | 'skipped-locked' | 'skipped-not-provisioned' | 'failed';
+    /** Tracked files blocking the refresh, at most 10; set when `skipped-dirty`. */
+    dirtyFiles?: string[];
+    /** What went wrong, credential-redacted; set when `failed` or `skipped-dirty`. */
+    message?: string;
+    /**
+     * Files under `.canopy-meta/` the adopter's repo tracks, at most 10. canopycms
+     * rewrites that state per branch, so tracking it is an adopter misconfiguration
+     * the panel surfaces with its fix, whatever the outcome.
+     */
+    trackedCanopyMeta?: string[];
+}
 /**
  * Wire shape of the worker's self-reported status file (worker-status.json, under
  * the task queue dir), written by the CmsWorker daemon. Read-only here: GET
@@ -123,8 +141,9 @@ export interface WorkerStatusReport {
         rebased: string[];
         skippedDirty: string[];
         /**
-         * [SYNC-C1] Branches skipped because a content write held the branch's
-         * cross-host content-write lock (utils/content-write-lock.ts); the worker
+         * Branches skipped because another process held a lock the worker
+         * try-acquires: the [SYNC-C1] content-write lock (utils/content-write-lock.ts)
+         * or the provisioning lock (worker/provisioned-workspace.ts). The worker
          * yields and retries next cycle. Optional for the same reason as `tracked`
          * below, and readers must tolerate its absence.
          */
@@ -133,6 +152,8 @@ export interface WorkerStatusReport {
             branch: string;
             error: string;
         }[];
+        /** Optional for the same reason as `tracked` below. */
+        baseRefresh?: BaseRefreshReport;
         /**
          * Outcome of reconciling remote.git's `refs/heads/*` against GitHub's fetched
          * tips, non-destructively (worker/git-sync.ts's `reconcileTrackedBranches`).

package/dist/utils/content-write-lock.d.ts

@@ -21,9 +21,9 @@
  *
  * The marker lives under `{branchRoot}/.canopy-meta` and the lock anchors on that marker path like
  * every other lock (see provisioning-lock.ts), so it can never alias the branch's provisioning
- * lock; the two are never both required and the only possible order (provision, then write) is
- * consistent, so they cannot deadlock. `.canopy-meta/` is git-excluded in every branch clone
- * (`ensureGitExclude`), so the lock directory cannot dirty the tree or be swept into `git add .`.
+ * lock. The worker's rebase holds both, provisioning outside this one, and takes each try-only,
+ * so they cannot deadlock. `.canopy-meta/` is git-excluded in every branch clone
+ * (`ensureGitExclude`), so the lock directory cannot dirty the tree or be staged.
  *
  * Mutual exclusion is not proven: on EFS a stale cached mtime lets a waiter take over a live lock,
  * leaving two unsynchronized writers -- the unlocked behaviour, so still a strict improvement.
@@ -59,10 +59,6 @@ export declare const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
 export declare class ContentWriteLockBusyError extends Error {
     constructor(message?: string);
 }
-/**
- * Acquire the branch's content-write lock WITHOUT waiting, for the worker's rebase loop, which
- * skips the branch and retries next cycle. Throws with `code === 'ELOCKED'` on a live holder.
- */
 export declare function tryAcquireContentWriteLock(branchRoot: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;
 /** Run `fn` holding the branch's content-write lock, releasing in a `finally` so a throw cannot
  * strand it. */

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

@@ -21,9 +21,9 @@
  *
  * The marker lives under `{branchRoot}/.canopy-meta` and the lock anchors on that marker path like
  * every other lock (see provisioning-lock.ts), so it can never alias the branch's provisioning
- * lock; the two are never both required and the only possible order (provision, then write) is
- * consistent, so they cannot deadlock. `.canopy-meta/` is git-excluded in every branch clone
- * (`ensureGitExclude`), so the lock directory cannot dirty the tree or be swept into `git add .`.
+ * lock. The worker's rebase holds both, provisioning outside this one, and takes each try-only,
+ * so they cannot deadlock. `.canopy-meta/` is git-excluded in every branch clone
+ * (`ensureGitExclude`), so the lock directory cannot dirty the tree or be staged.
  *
  * Mutual exclusion is not proven: on EFS a stale cached mtime lets a waiter take over a live lock,
  * leaving two unsynchronized writers -- the unlocked behaviour, so still a strict improvement.
@@ -81,8 +81,10 @@ const sleep = (ms) => new Promise((resolve) => {
  * Acquire the branch's content-write lock WITHOUT waiting, for the worker's rebase loop, which
  * skips the branch and retries next cycle. Throws with `code === 'ELOCKED'` on a live holder.
  */
+/** Below provisioning's, so a crashed worker blocks saves for at most 30s (docs/concurrency.md). */
+const CONTENT_WRITE_LOCK_STALE_MS = 30_000;
 export 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);
 }
 /**
  * Acquire the branch's content-write lock with a short bounded wait.

package/dist/utils/debug.d.ts

@@ -26,8 +26,16 @@ export declare class DebugLogger {
     info(category: string, message: string, data?: unknown): void;
     warn(category: string, message: string, data?: unknown): void;
     error(category: string, message: string, data?: unknown): void;
+    /**
+     * Keyed by label alone, so two overlapping timers with one label overwrite each other;
+     * anything that can run concurrently uses {@link timed}.
+     */
     time(label: string): void;
     timeEnd(category: string, label: string): number | undefined;
+    /**
+     * 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.
+     */
     timed<T>(category: string, label: string, fn: () => Promise<T>): Promise<T>;
 }
 export declare function createDebugLogger(options?: DebugOptions): DebugLogger;

package/dist/utils/debug.js

@@ -55,6 +55,10 @@ export class DebugLogger {
             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());
     }
@@ -69,13 +73,17 @@ export class DebugLogger {
         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 });
         }
     }
 }

package/dist/utils/git.d.ts

@@ -1,3 +1,4 @@
+import { type SimpleGit } from 'simple-git';
 import type { OperatingMode } from '../operating-mode/index.js';
 /**
  * Whether a git remote URL points at a network location rather than a local filesystem path. Only
@@ -39,6 +40,15 @@ export declare function isNonFastForwardRejection(message: string): boolean;
  * surfacing as the permanent, human-actionable state it is. Same locale caveat as above.
  */
 export declare function isStaleLeaseRejection(message: string): boolean;
+/**
+ * The workflow file named by GitHub's refusal of a push that would add workflow content the
+ * credential lacks the workflows permission for, or null if the message is not that refusal.
+ *
+ * GitHub refuses only content it does not already hold: carrying a base-branch workflow change by
+ * rebase, merge or fast-forward is accepted. Retrying the identical push can never succeed, so the
+ * worker fails it fast. The text is GitHub's own, not git's, so no locale pinning is needed.
+ */
+export declare function workflowPushRefusalFile(message: string): string | null;
 /**
  * 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.
@@ -50,6 +60,24 @@ export declare function isStaleLeaseRejection(message: string): boolean;
  * caveat as the predicates above.
  */
 export declare function isMissingRemoteRefFailure(message: string): boolean;
+/**
+ * The directory, at every workspace root, holding canopycms's own per-workspace state: branch
+ * metadata, comments, generation markers and lock markers. None of it is content, so it never
+ * belongs in a commit.
+ */
+export declare const CANOPY_META_DIR = ".canopy-meta";
+/**
+ * Whether a repo-relative path from `git status` / `git ls-files` is {@link CANOPY_META_DIR}
+ * or lies under it.
+ */
+export declare function isCanopyInternalPath(repoRelativePath: string): boolean;
+/**
+ * Stage every working-tree change (additions, edits, deletions) except anything under
+ * {@link CANOPY_META_DIR}, including files an adopter committed there by mistake. Stage-all then
+ * unstage, because git rejects `:(exclude)` pathspecs (six spellings tried) with "paths are ignored" when
+ * the excluded directory is itself ignored, which `.git/info/exclude` makes it in every clone.
+ */
+export declare function stageAllExceptCanopyState(git: SimpleGit): Promise<void>;
 /**
  * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge` (interactive/merge
  * backend) or `rebase-apply` (am backend) state directory git leaves when a rebase stops for

package/dist/utils/git.js

@@ -88,6 +88,21 @@ const STALE_LEASE_REASON = 'stale info';
 export function isStaleLeaseRejection(message) {
     return message.includes(REJECTED_MARKER) && message.includes(STALE_LEASE_REASON);
 }
+// GitHub's reason text when a push would introduce workflow content the credential may not write.
+// It names the credential kind ("a GitHub App", "an OAuth App", ...) and then the file.
+// Both classes stop at a newline, so the match stays on the one status line that carries it.
+const WORKFLOW_REFUSAL_PATTERN = /refusing to allow an? [^`\n]+? to create or update workflow `([^`\n]+)`/;
+/**
+ * The workflow file named by GitHub's refusal of a push that would add workflow content the
+ * credential lacks the workflows permission for, or null if the message is not that refusal.
+ *
+ * GitHub refuses only content it does not already hold: carrying a base-branch workflow change by
+ * rebase, merge or fast-forward is accepted. Retrying the identical push can never succeed, so the
+ * worker fails it fast. The text is GitHub's own, not git's, so no locale pinning is needed.
+ */
+export function workflowPushRefusalFile(message) {
+    return WORKFLOW_REFUSAL_PATTERN.exec(message)?.[1] ?? null;
+}
 // 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.
@@ -135,6 +150,29 @@ async function resolveGitDir(repoPath) {
         return null;
     }
 }
+/**
+ * The directory, at every workspace root, holding canopycms's own per-workspace state: branch
+ * metadata, comments, generation markers and lock markers. None of it is content, so it never
+ * belongs in a commit.
+ */
+export const CANOPY_META_DIR = '.canopy-meta';
+/**
+ * Whether a repo-relative path from `git status` / `git ls-files` is {@link CANOPY_META_DIR}
+ * or lies under it.
+ */
+export function isCanopyInternalPath(repoRelativePath) {
+    return repoRelativePath === CANOPY_META_DIR || repoRelativePath.startsWith(`${CANOPY_META_DIR}/`);
+}
+/**
+ * Stage every working-tree change (additions, edits, deletions) except anything under
+ * {@link CANOPY_META_DIR}, including files an adopter committed there by mistake. Stage-all then
+ * unstage, because git rejects `:(exclude)` pathspecs (six spellings tried) with "paths are ignored" when
+ * the excluded directory is itself ignored, which `.git/info/exclude` makes it in every clone.
+ */
+export async function stageAllExceptCanopyState(git) {
+    await git.add(['-A']);
+    await git.raw(['reset', '-q', '--', CANOPY_META_DIR]);
+}
 /**
  * Whether a repository has an INTERRUPTED rebase on disk — the `rebase-merge` (interactive/merge
  * backend) or `rebase-apply` (am backend) state directory git leaves when a rebase stops for

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

@@ -9,6 +9,13 @@
  * inside the refresh timer, so a throw is an uncaught exception that kills the process.
  */
 export type OnLockCompromised = (err: Error) => void;
+/**
+ * The provisioning lock's name for the branch workspace directory `dirName`, held in that
+ * directory's parent. Every party to a branch workspace's provisioning names it through this:
+ * the Lambda while it clones, the admin purge, branch-health's freshness rail, and the worker
+ * while it refreshes or rebases.
+ */
+export declare function branchProvisioningLockName(dirName: string): string;
 /**
  * Acquire a cross-process filesystem lock for content provisioning. Returns a release function —
  * always call it in a `finally`.
@@ -27,12 +34,15 @@ export declare function acquireProvisioningLock(lockTargetDir: string, lockName:
  * request/response cycle (a Lambda-backed API handler). `acquireProvisioningLock`'s ~600-retry
  * budget waits minutes for a live provisioner; an admin request must fail fast instead.
  *
- * `stale: 30_000` is unchanged from the patient variant: a genuinely stale lock (holder crashed
- * more than 30s ago) is still taken over normally. Only the RETRY loop for live contention is
- * removed, not the staleness recovery a caller depends on -- see branch-health.ts's [H1]
- * freshness rail, which reads this lock's mtime before an admin purge/repair proceeds.
+ * Staleness recovery is unchanged from the patient variant: a genuinely stale lock is still taken
+ * over normally. Only the RETRY loop for live contention is removed, not the staleness recovery a
+ * caller depends on -- see branch-health.ts's [H1] freshness rail, which reads this lock's mtime
+ * before an admin purge/repair proceeds.
  *
  * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale holder) -- callers
  * translate that into a 409.
+ *
+ * @param staleMs how old the marker must look before this caller takes it over; defaults to
+ *   {@link PROVISIONING_LOCK_STALE_MS}
  */
-export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;
+export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised, staleMs?: number): Promise<() => Promise<void>>;

package/dist/utils/provisioning-lock.js

@@ -3,6 +3,12 @@ import path from 'node:path';
 import lockfile from 'proper-lockfile';
 import { getErrorMessage, isNodeError } from './error.js';
 import { canopyLogWarn } from './logger.js';
+/**
+ * When an acquirer may take a provisioning marker over. Staleness is read from the marker's mtime,
+ * which EFS serves from the NFS attribute cache for up to 60s, so a live holder's 15s refreshes
+ * can look 60s late; one threshold above that for every acquirer means none reaps a live hold.
+ */
+const PROVISIONING_LOCK_STALE_MS = 90_000;
 /**
  * Shared option set for both provisioning-lock variants.
  *
@@ -16,12 +22,14 @@ import { canopyLogWarn } from './logger.js';
  * share one. `realpath: false` because that anchor path does not exist before we create it
  * (realpath would ENOENT). See docs/concurrency.md ("Anchor path matters").
  */
-function provisioningLockOptions(lockPath, retries, onCompromised) {
+function provisioningLockOptions(lockPath, retries, onCompromised, staleMs) {
     return {
         lockfilePath: lockPath,
         realpath: false,
         retries,
-        stale: 30_000,
+        stale: staleMs,
+        // Fixed, not stale/2: every holder refreshes at 15s whatever threshold it judges others by.
+        update: 15_000,
         // 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
@@ -76,6 +84,15 @@ function releaseIgnoringAlreadyReleased(release, lockPath) {
         }
     };
 }
+/**
+ * The provisioning lock's name for the branch workspace directory `dirName`, held in that
+ * directory's parent. Every party to a branch workspace's provisioning names it through this:
+ * the Lambda while it clones, the admin purge, branch-health's freshness rail, and the worker
+ * while it refreshes or rebases.
+ */
+export function branchProvisioningLockName(dirName) {
+    return `.${dirName}.init.lock`;
+}
 /**
  * Acquire a cross-process filesystem lock for content provisioning. Returns a release function —
  * always call it in a `finally`.
@@ -94,9 +111,9 @@ export async function acquireProvisioningLock(lockTargetDir, lockName, onComprom
     // Generous, jittered retries: several processes may contend for one workspace (Lambda
     // containers cold-starting together against one EFS root), and the holder can take seconds to
     // init plus clone/push. `randomize` de-syncs the herd so a waiter is not perpetually colliding
-    // on the same tick. `stale` stays modest because proper-lockfile auto-refreshes a live holder's
-    // lock, so it expires only when a process actually dies.
-    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised));
+    // on the same tick. A live holder's lock never goes stale, because proper-lockfile refreshes it;
+    // it expires only when a process actually dies.
+    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);
 }
 /**
@@ -104,17 +121,20 @@ export async function acquireProvisioningLock(lockTargetDir, lockName, onComprom
  * request/response cycle (a Lambda-backed API handler). `acquireProvisioningLock`'s ~600-retry
  * budget waits minutes for a live provisioner; an admin request must fail fast instead.
  *
- * `stale: 30_000` is unchanged from the patient variant: a genuinely stale lock (holder crashed
- * more than 30s ago) is still taken over normally. Only the RETRY loop for live contention is
- * removed, not the staleness recovery a caller depends on -- see branch-health.ts's [H1]
- * freshness rail, which reads this lock's mtime before an admin purge/repair proceeds.
+ * Staleness recovery is unchanged from the patient variant: a genuinely stale lock is still taken
+ * over normally. Only the RETRY loop for live contention is removed, not the staleness recovery a
+ * caller depends on -- see branch-health.ts's [H1] freshness rail, which reads this lock's mtime
+ * before an admin purge/repair proceeds.
  *
  * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale holder) -- callers
  * translate that into a 409.
+ *
+ * @param staleMs how old the marker must look before this caller takes it over; defaults to
+ *   {@link PROVISIONING_LOCK_STALE_MS}
  */
-export async function tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised) {
+export async function tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised, staleMs = PROVISIONING_LOCK_STALE_MS) {
     await fs.mkdir(lockTargetDir, { recursive: true });
     const lockPath = path.join(lockTargetDir, 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);
 }

package/dist/utils/request-timing.d.ts

@@ -0,0 +1,25 @@
+interface PhaseTotal {
+    count: number;
+    ms: number;
+}
+/** Record `fn` as `phase` in the active request scope; outside one, just run it. */
+export declare function timeRequestPhase<T>(phase: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Whether a request scope is open here.
+ * @internal Exported for tests.
+ */
+export declare function isRequestTimingScopeActive(): boolean;
+/** Name the matched route (a pattern, never raw path segments) for the summary line. */
+export declare function setRequestTimingRoute(route: string): void;
+/**
+ * The summary line's message, after the logger's timestamp/category prefix:
+ * `GET :branch/entries 200 1172ms | context=0 auth=12 route=1110 route>settingsRoot=1080(x2) untimed=50`.
+ * @internal Exported for tests.
+ */
+export declare function formatRequestTimingSummary(method: string, route: string, status: number | 'error', totalMs: number, phases: ReadonlyMap<string, PhaseTotal>): string;
+/**
+ * Run one API request inside a timing scope and log its summary line when it settles,
+ * thrown or not. `statusOf` reads the status from the result.
+ */
+export declare function runWithRequestTiming<T>(method: string, fn: () => Promise<T>, statusOf: (result: T) => number): Promise<T>;
+export {};

package/dist/utils/request-timing.js

@@ -0,0 +1,101 @@
+/**
+ * Per-request phase timing for the API handler, enabled by `CANOPYCMS_DEBUG=true`.
+ *
+ * `runWithRequestTiming` opens a request scope in AsyncLocalStorage and, when the request
+ * finishes, emits ONE summary line: method, route pattern, status, total, and every phase
+ * recorded inside the scope. `timeRequestPhase` records a phase into whichever scope is
+ * active. Scopes are per async context, so concurrent requests in one process never share
+ * or overwrite a span, and a phase reached outside any request (the worker, a build, a
+ * page render) just runs its function.
+ *
+ * Disabled, `runWithRequestTiming` calls straight through without opening a scope, so each
+ * `timeRequestPhase` costs one `getStore()` that returns undefined.
+ *
+ * A phase started inside another records under the joined name (`route>settingsRoot`), so
+ * nesting stays visible and nested time is never added to its parent's siblings. A phase
+ * run several times in one request accumulates, and the line shows the count. `untimed` is
+ * the total minus the top-level phases, which run sequentially in the handler.
+ *
+ * Server-only: `node:async_hooks`.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createDebugLogger } from './debug.js';
+const storage = new AsyncLocalStorage();
+const log = createDebugLogger({ prefix: 'CanopyCMS' });
+/** Read per call, like DebugLogger, so toggling the env var needs no restart. */
+function isRequestTimingEnabled() {
+    return process.env.CANOPYCMS_DEBUG === 'true';
+}
+/** Record `fn` as `phase` in the active request scope; outside one, just run it. */
+export async function timeRequestPhase(phase, fn) {
+    const parent = storage.getStore();
+    if (!parent)
+        return fn();
+    const key = parent.path ? `${parent.path}>${phase}` : phase;
+    // Created at START so the summary lists phases in the order they began.
+    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;
+    }
+}
+/**
+ * Whether a request scope is open here.
+ * @internal Exported for tests.
+ */
+export function isRequestTimingScopeActive() {
+    return storage.getStore() !== undefined;
+}
+/** Name the matched route (a pattern, never raw path segments) for the summary line. */
+export function setRequestTimingRoute(route) {
+    const scope = storage.getStore();
+    if (scope)
+        scope.request.route = route;
+}
+/**
+ * The summary line's message, after the logger's timestamp/category prefix:
+ * `GET :branch/entries 200 1172ms | context=0 auth=12 route=1110 route>settingsRoot=1080(x2) untimed=50`.
+ * @internal Exported for tests.
+ */
+export function formatRequestTimingSummary(method, route, status, totalMs, phases) {
+    let topLevelMs = 0;
+    const parts = [];
+    for (const [name, { count, ms }] of phases) {
+        if (!name.includes('>'))
+            topLevelMs += ms;
+        parts.push(`${name}=${Math.round(ms)}${count > 1 ? `(x${count})` : ''}`);
+    }
+    parts.push(`untimed=${Math.max(0, Math.round(totalMs - topLevelMs))}`);
+    return `${method} ${route} ${status} ${Math.round(totalMs)}ms | ${parts.join(' ')}`;
+}
+/**
+ * Run one API request inside a timing scope and log its summary line when it settles,
+ * thrown or not. `statusOf` reads the status from the result.
+ */
+export async function runWithRequestTiming(method, fn, statusOf) {
+    if (!isRequestTimingEnabled())
+        return fn();
+    const scope = {
+        phases: new Map(),
+        path: '',
+        request: { route: '(unmatched)' },
+    };
+    const start = performance.now();
+    let status = 'error';
+    try {
+        const result = await storage.run(scope, fn);
+        status = statusOf(result);
+        return result;
+    }
+    finally {
+        log.debug('timing', formatRequestTimingSummary(method, scope.request.route, status, performance.now() - start, scope.phases));
+    }
+}

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

@@ -119,3 +119,18 @@ export declare function sanitizeUnprefixedPath(url: string): string;
  * neutralizing it would silently rewrite a legitimate protocol-relative CDN base into a path.
  */
 export declare function joinUrlPrefix(prefix: string | undefined, path: string): string;
+/**
+ * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
+ *
+ * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
+ * `/blog/rss.xml`) alone, and never doubles an existing slash. So it never produces a URL that
+ * Next's `trailingSlash: true` redirects (`next/dist/lib/load-custom-routes.js:489,502` in
+ * 15.5.21): Next adds a slash only to a last segment with no dot, and strips one from a segment
+ * ending `.ext`.
+ *
+ * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
+ * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
+ * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
+ * with a trailing slash" means and breaks the URL).
+ */
+export declare function withTrailingSlash(path: string): string;

package/dist/utils/url-prefix.js

@@ -156,3 +156,29 @@ export function joinUrlPrefix(prefix, path) {
         : `/${trimmedPrefix}`;
     return `${normalizedPrefix}${normalizedPath}`;
 }
+/**
+ * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
+ *
+ * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
+ * `/blog/rss.xml`) alone, and never doubles an existing slash. So it never produces a URL that
+ * Next's `trailingSlash: true` redirects (`next/dist/lib/load-custom-routes.js:489,502` in
+ * 15.5.21): Next adds a slash only to a last segment with no dot, and strips one from a segment
+ * ending `.ext`.
+ *
+ * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
+ * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
+ * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
+ * with a trailing slash" means and breaks the URL).
+ */
+export function withTrailingSlash(path) {
+    const splitIndex = path.search(/[?#]/);
+    const base = splitIndex === -1 ? path : path.slice(0, splitIndex);
+    const suffix = splitIndex === -1 ? '' : path.slice(splitIndex);
+    const withLeading = base.startsWith('/') ? base : `/${base}`;
+    if (withLeading === '/' || withLeading.endsWith('/'))
+        return withLeading + suffix;
+    const lastSegment = withLeading.slice(withLeading.lastIndexOf('/') + 1);
+    if (lastSegment.includes('.'))
+        return withLeading + suffix;
+    return `${withLeading}/${suffix}`;
+}

package/dist/worker/canopy-state.d.ts

@@ -0,0 +1,45 @@
+import type { FileStatusResult, SimpleGit, StatusResult } from 'simple-git';
+/**
+ * How the sync loop treats canopycms's own state (`.canopy-meta/`) in a branch clone. It is
+ * never content, so untracked state never makes a clone "dirty" for sync, but git refuses some
+ * operations over it while the adopter's repo tracks it. Only the adopter can stop that; once
+ * they have, the base clone follows on its next fast-forward ({@link untrackInIndex}), and a
+ * branch clone with modified tracked state needs an operator.
+ */
+/** The fix an operator applies when an adopter repo tracks `.canopy-meta/`. */
+export declare const TRACKED_CANOPY_STATE_FIX = "run `git rm -r --cached .canopy-meta` in the site repo, add `.canopy-meta/` to its .gitignore, and commit";
+/** Paths listed in worker-status.json per category; the admin panel shows them in a tooltip. */
+export declare const MAX_REPORTED_PATHS = 10;
+export declare function isUntracked(file: FileStatusResult): boolean;
+/** Files under `.canopy-meta/` that the clone's index tracks. */
+export declare function listTrackedCanopyState(git: SimpleGit): Promise<string[]>;
+/**
+ * Discard local changes to the schema cache's retired in-tree copy, so a clone of a repo that
+ * committed it can sync again. Nothing reads or writes that path in a clone any more, so its
+ * content is dead; but while it differs from HEAD, `git rebase` refuses to start and a
+ * fast-forward that touches it (including the adopter's own commit untracking it) refuses too.
+ * An untracked copy blocks neither and a newly staged one has nothing in HEAD to restore, so
+ * both are left alone. Returns whether it restored anything; the caller re-reads status if so.
+ */
+export declare function restoreRetiredSchemaCache(git: SimpleGit, status: StatusResult): Promise<boolean>;
+/**
+ * The changed tracked `.canopy-meta/` files in `status`: what git refuses to rebase over, and
+ * what a fast-forward refuses to overwrite where it touches them.
+ */
+export declare function trackedCanopyStateChanges(status: StatusResult): string[];
+/**
+ * Split `paths` by whether the commit `tip` still tracks them. Those it no longer tracks, the
+ * adopter has untracked upstream, so a fast-forward onto `tip` would delete them from disk unless
+ * {@link untrackInIndex} takes them out of the index first.
+ */
+export declare function splitByUpstreamTracking(git: SimpleGit, paths: string[], tip: string): Promise<{
+    droppedUpstream: string[];
+    stillTracked: string[];
+}>;
+/**
+ * Remove `paths` from this clone's index, leaving them on disk as untracked, excluded state.
+ * Index-only, so a concurrent write to them (branch metadata, comments) is not lost. Only for a
+ * clone with no commits of its own: a rebase that replays a commit touching these paths writes
+ * that commit's bytes over them. Paths already out of the index are ignored.
+ */
+export declare function untrackInIndex(git: SimpleGit, paths: string[]): Promise<void>;