canopycms 0.0.67 → 0.0.68-int.100

package/dist/utils/sanitize-href.js

@@ -90,34 +90,22 @@ export function neutralizeImplicitOffOrigin(url) {
  * this file either way, so the two surfaces cannot drift into disagreeing about which schemes
  * are acceptable (that drift is exactly why `utils/url-prefix.ts` exists — see its header).
  *
- * `allowProtocolRelative` exists because the two callers genuinely differ, and the difference
- * is blast radius rather than taste:
- *
- * - A READ-side prefix (`media.publicBaseUrl`, joined onto `/assets/…`) may legitimately be
- *   `//cdn.example.com`. `utils/url-prefix.ts`'s `isAbsoluteUrl` documents that literal
- *   spelling as an intentionally-supported off-site pointer, so rejecting it here would break
- *   a working configuration. A bad value costs a broken `<img>`.
- * - A WRITE-side endpoint (`media.uploadUrl`, where the browser POSTs a presigned upload) must
- *   not be protocol-relative even when spelled literally, because such a URL is AMBIGUOUS: it
- *   resolves to http or https depending on the scheme of whichever editor page happens to
- *   issue the upload, so the stored config does not determine where a live presigned credential
- *   and the user's file bytes are sent. That is the same principle every other rule here
- *   enforces — a config value must describe what actually happens.
- *
- *   Note this is NOT an argument that http is forbidden on the write side; bare `http://` is
- *   accepted, because a loopback or in-cluster S3-compatible endpoint is a real need and a
- *   browser on an https editor blocks the mixed-content request anyway, so it fails closed. The
- *   objection to `//host` is that it is undetermined, not that it might be insecure.
+ * A protocol-relative `//host` is refused even when spelled literally, because it is AMBIGUOUS:
+ * it resolves to http or https depending on the page issuing the request, so the stored config
+ * does not determine where, for `media.uploadUrl`, a live presigned credential and the user's
+ * file bytes are sent. Bare `http://` is accepted: a loopback or in-cluster S3-compatible
+ * endpoint is a real need, and a browser on an https editor blocks the mixed-content request
+ * anyway, so it fails closed.
  *
  * Every spelling that READS as site-relative while redefining the authority — `/\host`,
- * `\\host`, `\/host`, `///host` — is rejected for both, in both modes. Those look site-relative
+ * `\\host`, `\/host`, `///host` — is rejected too. Those look site-relative
  * to a human and to a naive `startsWith('/')` check, but WHATWG URL resolves each to a
  * different authority (measured: `///x` resolves to host `x`, not to pathname `/x`), so they
  * are never what an adopter meant. A scheme-qualified absolute URL is a separate case and is
  * accepted — `https:///cdn.example.com/` is unusual but unambiguous, resolving identically
  * standalone and against any base.
  */
-export function isHttpUrlOrSameOriginPath(value, opts = {}) {
+export function isHttpUrlOrSameOriginPath(value) {
     if (value === '')
         return false;
     // Reject ASCII control characters and spaces ANYWHERE in the value, not only at the edges.
@@ -132,7 +120,7 @@ export function isHttpUrlOrSameOriginPath(value, opts = {}) {
     }
     // A query or fragment is meaningless on both sides this predicate serves. S3's POST Object
     // takes no query parameters and a browser never transmits a fragment; and on the read side a
-    // prefix carrying either produces `https://cdn.example.com/?x=1/assets/…` once joined.
+    // prefix carrying either produces `https://cdn.example.com/?x=1/…` once joined.
     if (value.includes('?') || value.includes('#'))
         return false;
     // A backslash is never legitimate in a configured URL, and it is not merely cosmetic: WHATWG
@@ -169,13 +157,8 @@ export function isHttpUrlOrSameOriginPath(value, opts = {}) {
             return false;
         }
     }
-    // A LITERAL `//host` is the only off-origin spelling that can be intentional, and only for
-    // callers that opt in. `value[2] !== '/'` matters: `///x` and `////x` are also "implicitly
-    // off-origin" and also start with `//`, but resolve to a host named `x` rather than to a
-    // path — so they must not ride in on the opt-in.
-    if (isImplicitlyOffOrigin(value)) {
-        return opts.allowProtocolRelative === true && value.startsWith('//') && value[2] !== '/';
-    }
+    if (isImplicitlyOffOrigin(value))
+        return false;
     // Site-relative, with exactly one leading slash. The second clause also covers `//`, which
     // `isImplicitlyOffOrigin` reports as false only because `new URL('//', base)` throws.
     return value.startsWith('/') && value[1] !== '/';

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

@@ -119,3 +119,33 @@ 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;
+/**
+ * Give a URL's path the trailing-slash form a Next host serves, so loading it draws no 308:
+ * `withTrailingSlash`'s rule when `trailingSlash` is true, else no trailing slash on any path
+ * but the root (Next also redirects `<basePath>/` to `<basePath>`, `load-custom-routes.js:528`). An
+ * absolute URL's origin, and any query or fragment, are kept as they are.
+ */
+export declare function matchTrailingSlash(url: string, trailingSlash: boolean): string;
+/**
+ * Whether the host is built with Next's `trailingSlash: true`. `withCanopy` sets
+ * `CANOPY_TRAILING_SLASH` in Next's `env` config, which Next substitutes for this literal member
+ * expression in server and browser bundles (`getNextConfigEnv`, `next/dist/build/define-env.js:54`).
+ * The try/catch covers a host whose bundler neither substitutes it nor shims `process` in the
+ * browser.
+ */
+export declare function readTrailingSlashEnv(): boolean;

package/dist/utils/url-prefix.js

@@ -156,3 +156,64 @@ 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}`;
+}
+// Linear: `[^/?#]*` cannot overlap the literal `//` before it, so there is one way to match.
+// eslint-disable-next-line security/detect-unsafe-regex
+const URL_ORIGIN = /^(?:[a-z][a-z0-9+.-]*:)?\/\/[^/?#]*/i;
+/**
+ * Give a URL's path the trailing-slash form a Next host serves, so loading it draws no 308:
+ * `withTrailingSlash`'s rule when `trailingSlash` is true, else no trailing slash on any path
+ * but the root (Next also redirects `<basePath>/` to `<basePath>`, `load-custom-routes.js:528`). An
+ * absolute URL's origin, and any query or fragment, are kept as they are.
+ */
+export function matchTrailingSlash(url, trailingSlash) {
+    const origin = isAbsoluteUrl(url) ? (URL_ORIGIN.exec(url)?.[0] ?? '') : '';
+    const rest = url.slice(origin.length);
+    if (trailingSlash)
+        return origin + withTrailingSlash(rest);
+    const splitIndex = rest.search(/[?#]/);
+    const base = splitIndex === -1 ? rest : rest.slice(0, splitIndex);
+    const suffix = splitIndex === -1 ? '' : rest.slice(splitIndex);
+    const trimmed = stripTrailingSlashes(base);
+    return origin + (trimmed || (origin ? '' : '/')) + suffix;
+}
+/**
+ * Whether the host is built with Next's `trailingSlash: true`. `withCanopy` sets
+ * `CANOPY_TRAILING_SLASH` in Next's `env` config, which Next substitutes for this literal member
+ * expression in server and browser bundles (`getNextConfigEnv`, `next/dist/build/define-env.js:54`).
+ * The try/catch covers a host whose bundler neither substitutes it nor shims `process` in the
+ * browser.
+ */
+export function readTrailingSlashEnv() {
+    try {
+        return process.env.CANOPY_TRAILING_SLASH === 'true';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/validation/entry-validator.js

@@ -12,7 +12,7 @@
  * `ReferenceValidator` at the write boundary.
  */
 import { fieldTypes } from '../config/index.js';
-import { isValidCropRect } from '../assets/transform-directives.js';
+import { isValidCropRect, roundCropRect } from '../assets/transform-directives.js';
 import { BLOCK_STRUCTURAL_KEYS } from './block-structural-keys.js';
 import { resolveBlockItem, traverseFields } from './field-traversal.js';
 import { findBodyFieldName } from '../utils/body-field.js';
@@ -27,7 +27,10 @@ function isPlainRecord(value) {
 function isPositiveInt(value) {
     return typeof value === 'number' && Number.isInteger(value) && value > 0;
 }
-/** True when `value` is a well-formed `{ x, y, w, h }` normalized crop rect. */
+/**
+ * True when `value` is a well-formed `{ x, y, w, h }` normalized crop rect that is still valid
+ * after `roundCropRect`, the rounding its transform URL applies.
+ */
 function isValidImageCropValue(value) {
     if (!isPlainRecord(value))
         return false;
@@ -38,7 +41,10 @@ function isValidImageCropValue(value) {
         typeof h !== 'number') {
         return false;
     }
-    return isValidCropRect(x, y, w, h);
+    if (!isValidCropRect(x, y, w, h))
+        return false;
+    const rounded = roundCropRect({ x, y, w, h });
+    return isValidCropRect(rounded.x, rounded.y, rounded.w, rounded.h);
 }
 /**
  * Validate a structured `image` field value: `{ src, alt, width?, height?, crop? }`

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const CANOPYCMS_VERSION = "0.0.68-int.100";

package/dist/version.js

@@ -0,0 +1,3 @@
+// Generated by scripts/bump-version.mjs, its only writer. The package builds with plain
+// tsc (rootDir: src), so src/ cannot import ../package.json; version.test.ts keeps the two equal.
+export const CANOPYCMS_VERSION = '0.0.68-int.100';

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>;

package/dist/worker/canopy-state.js

@@ -0,0 +1,75 @@
+import { SCHEMA_CACHE_FILE } from '../branch-schema-cache.js';
+import { CANOPY_META_DIR, isCanopyInternalPath } from '../utils/git.js';
+/**
+ * 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 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 const MAX_REPORTED_PATHS = 10;
+/** The schema cache's location in a clone before it moved under `.git/` (branch-schema-cache.ts). */
+const RETIRED_SCHEMA_CACHE_PATH = `${CANOPY_META_DIR}/${SCHEMA_CACHE_FILE}`;
+export function isUntracked(file) {
+    return file.index === '?' && file.working_dir === '?';
+}
+/** NUL-separated git output, which is never quoted, unlike `core.quotePath` line output. */
+function splitNul(out) {
+    return out.split('\0').filter((entry) => entry.length > 0);
+}
+/** Files under `.canopy-meta/` that the clone's index tracks. */
+export async function listTrackedCanopyState(git) {
+    return splitNul(await git.raw(['ls-files', '-z', '--', CANOPY_META_DIR]));
+}
+/**
+ * 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 async function restoreRetiredSchemaCache(git, status) {
+    const entry = status.files.find((f) => f.path === RETIRED_SCHEMA_CACHE_PATH);
+    if (!entry || entry.index === '?' || entry.index === 'A')
+        return false;
+    await git.raw(['checkout', 'HEAD', '--', RETIRED_SCHEMA_CACHE_PATH]);
+    return true;
+}
+/**
+ * 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 function trackedCanopyStateChanges(status) {
+    return status.files
+        .filter((f) => isCanopyInternalPath(f.path) && !isUntracked(f))
+        .map((f) => f.path);
+}
+/**
+ * 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 async function splitByUpstreamTracking(git, paths, tip) {
+    if (paths.length === 0)
+        return { droppedUpstream: [], stillTracked: [] };
+    const tracked = new Set(splitNul(await git.raw(['ls-tree', '-r', '-z', '--name-only', tip, '--', CANOPY_META_DIR])));
+    return {
+        droppedUpstream: paths.filter((p) => !tracked.has(p)),
+        stillTracked: paths.filter((p) => tracked.has(p)),
+    };
+}
+/**
+ * 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 async function untrackInIndex(git, paths) {
+    if (paths.length === 0)
+        return;
+    await git.raw(['rm', '--cached', '--ignore-unmatch', '-q', '--', ...paths]);
+}

package/dist/worker/cms-worker.d.ts

@@ -15,11 +15,11 @@ export type AuthCacheRefresher = () => Promise<void>;
  * interface for the two shapes and why an App is optional.
  */
 export interface CmsWorkerConfig extends GitHubAuthConfig {
-    /** Path to workspace root on EFS (e.g., /mnt/efs/workspace) */
+    /** Path to workspace root on EFS (e.g., /mnt/efs) */
     workspacePath: string;
-    /** GitHub owner (e.g., 'safeinsights') */
+    /** GitHub owner (e.g., 'acme') */
     githubOwner: string;
-    /** GitHub repo name (e.g., 'docs-site') */
+    /** GitHub repo name (e.g., 'site') */
     githubRepo: string;
     /** Called periodically to update the auth metadata cache on EFS. */
     refreshAuthCache?: AuthCacheRefresher;
@@ -203,6 +203,11 @@ export declare class CmsWorker {
      * survives, so a failed scrub is never indistinguishable from a clean one.
      */
     private scrubPersistedRemote;
+    /**
+     * Best-effort: without these settings remote.git still works, and a boot that
+     * cannot write its own config has a louder problem to report elsewhere.
+     */
+    private applyRemoteGitConfig;
     /**
      * Ensure the remote.git bare repo exists, cloning it from GitHub on first
      * run.

package/dist/worker/cms-worker.js

@@ -5,10 +5,12 @@ import lockfile from 'proper-lockfile';
 import { recoverOrphanedTasks, cmsTaskQueueLogger } from '../task-queue/cms-task-queue.js';
 import { createCanopyOctokit } from '../github-service.js';
 import { isTransientAuthFailure, resolveWorkerGitHubAuth, } from './github-auth.js';
+import { ensureRemoteGitConfig } from '../git-manager.js';
 import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX } from '../paths/branch-name.js';
 import { resolveDeploymentName } from '../operating-mode/deployment-name.js';
 import { getErrorMessage, isNodeError, redactCredentials } from '../utils/error.js';
-import { writeWorkerStatus } from '../task-queue/worker-status.js';
+import { readLastFatalError, writeWorkerStatus } from '../task-queue/worker-status.js';
+import { CANOPYCMS_VERSION } from '../version.js';
 import { workerLog, workerLogWarn, workerLogError } from './log.js';
 import { executeTask, orphanRecoveryMaxAgeMs, processTaskQueue, pushBranchToGitHub, updateBranchMetadata, } from './task-runner.js';
 import { pollMergeState, runRebaseCycle } from './rebase.js';
@@ -67,7 +69,12 @@ export class CmsWorker {
     ensureStatusReport() {
         if (!this.statusReport) {
             const now = new Date().toISOString();
-            this.statusReport = { version: 1, startedAt: now, updatedAt: now };
+            this.statusReport = {
+                version: 1,
+                workerVersion: CANOPYCMS_VERSION,
+                startedAt: now,
+                updatedAt: now,
+            };
         }
         return this.statusReport;
     }
@@ -144,6 +151,21 @@ export class CmsWorker {
         workerLog('CMS Worker starting...');
         this.ensureStatusReport();
         await this.acquireLock();
+        // Replace the previous holder's status file now: the first sync can take
+        // minutes, and until then System health would report the old worker's
+        // version. Best-effort, like the startup-failure write below. The previous
+        // `lastFatalError` rides along in this snapshot only, so a crash loop keeps
+        // its alert between restarts while the first successful sync still clears it.
+        try {
+            const lastFatalError = await readLastFatalError(this.taskDir);
+            await writeWorkerStatus(this.taskDir, {
+                ...this.ensureStatusReport(),
+                ...(lastFatalError ? { lastFatalError } : {}),
+            });
+        }
+        catch (err) {
+            workerLogError('Failed to write worker status after acquiring the lock:', getErrorMessage(err));
+        }
         // Everything below runs while holding the cross-host worker lock. A failure
         // here (most notably the empty-remote guard inside ensureRemoteGit) means
         // the process is about to exit and systemd (Restart=always) will retry —
@@ -411,6 +433,18 @@ export class CmsWorker {
                 `shared storage. Refusing to continue.`);
         }
     }
+    /**
+     * Best-effort: without these settings remote.git still works, and a boot that
+     * cannot write its own config has a louder problem to report elsewhere.
+     */
+    async applyRemoteGitConfig(gitDir) {
+        try {
+            await ensureRemoteGitConfig(gitDir);
+        }
+        catch (err) {
+            workerLogWarn(`Could not apply remote.git config in ${gitDir}: ${getErrorMessage(err)}`);
+        }
+    }
     /**
      * Ensure the remote.git bare repo exists, cloning it from GitHub on first
      * run.
@@ -450,6 +484,7 @@ export class CmsWorker {
                 // deletion is the operator's call.
                 throw new Error(`remote.git at ${this.remoteGitPath} has no branch '${this.baseBranch}' (likely cloned while the GitHub repo was empty). Delete ${this.remoteGitPath} and restart the worker to re-clone.`);
             }
+            await this.applyRemoteGitConfig(this.remoteGitPath);
             return; // Already exists and has the base branch
         }
         workerLog('Initializing remote.git from GitHub...');
@@ -468,6 +503,7 @@ export class CmsWorker {
             // swallowing) if the scrub does not take.
             await this.scrubPersistedRemote(stagingPath);
             await this.verifyBaseBranchExists(stagingPath);
+            await this.applyRemoteGitConfig(stagingPath);
         }
         catch (err) {
             workerLogError(`remote.git clone failed: ${redactCredentials(getErrorMessage(err))}`);

package/dist/worker/git-sync.d.ts

@@ -1,4 +1,5 @@
 import { simpleGit } from 'simple-git';
+import type { BaseRefreshReport } from '../types.js';
 import { type RebaseContext } from './rebase.js';
 import type { WorkerContext } from './worker-context.js';
 /**
@@ -6,7 +7,10 @@ import type { WorkerContext } from './worker-context.js';
  * slower of the worker's two poll loops (default 5 minutes, against the task
  * queue's 5 seconds).
  *
- * One cycle, in order: fetch every GitHub branch into the tracking namespace,
+ * One cycle, in order: repair what killed provisioning and deletes left under
+ * the branches root (`repairBranchDirResidue`), move sparse clones to a changed
+ * content root's cone (sparse-cone.ts), repack `remote.git` when it needs it
+ * (remote-git-maintenance.ts), fetch every GitHub branch into the tracking namespace,
  * bring `refs/heads/*` toward it non-destructively (`reconcileTrackedBranches`),
  * push this deployment's own settings branch, fast-forward the base branch's
  * workspace, rebase every branch that is behind it (rebase.ts), then sweep old
@@ -14,7 +18,7 @@ import type { WorkerContext } from './worker-context.js';
  *
  * One ordering is load-bearing and nothing enforces it: `runRebaseCycle` MUST
  * follow `reconcileTrackedBranches`. Branch clones fetch the base tip from
- * `remote.git` (`origin`), and `reconcileTrackedBranches` is what advances
+ * `remote.git`, and `reconcileTrackedBranches` is what advances
  * `remote.git`'s `refs/heads/*` toward what the fetch above put in the tracking
  * namespace; reorder them and every branch rebases onto the PREVIOUS cycle's
  * base tip -- not corrupting, but silently a cycle behind.
@@ -39,27 +43,41 @@ export type GitSyncContext = Pick<WorkerContext, 'baseBranch' | 'sanitizedBaseBr
  */
 export declare function pushSettingsBranches(ctx: GitSyncContext, git: ReturnType<typeof simpleGit>, trackedNames: ReadonlySet<string>): Promise<void>;
 export declare function syncGit(ctx: GitSyncContext): Promise<void>;
+/**
+ * Repair what killed provisioning and deletes left under the branches root: quarantine residue
+ * at a branch's name (branch-provisioning.ts's `classifyFinalDir`) once it has been quiet for
+ * {@link ORPHAN_YOUTH_THRESHOLD_MS}, then sweep stale `.prov-*`, `.deleting-*` and `.repair-*`
+ * siblings and settings leftovers. Each directory is best-effort, like [SYNC-M2]. The provisioning
+ * lock is taken zero-retry, so a live provisioner or admin action wins and the directory is
+ * revisited next cycle.
+ * @internal Exported for tests; `syncGit` runs it.
+ */
+export declare function repairBranchDirResidue(ctx: Pick<GitSyncContext, 'contentBranchesPath' | 'remoteGitPath'>, now?: number): Promise<void>;
 /**
  * [C1] Remove `.trash-*` branch directories (created by the admin purge action,
- * api/admin-branch-health.ts) whose name-embedded stamp is older than
- * {@link TRASH_RETENTION_MS}. A name that doesn't match `.trash-{dirName}-
- * {STAMP}`, or whose stamp fails to parse, is left alone and logged once per
- * cycle: purge is the only writer of this naming scheme, so an unparseable name
- * is unexpected and worth a human looking rather than a silent skip.
+ * api/admin-branch-health.ts, and by residue quarantine, branch-provisioning.ts)
+ * whose name-embedded stamp is older than {@link TRASH_RETENTION_MS}. A name
+ * whose trailing stamp fails to parse is left alone and logged once per cycle:
+ * both writers end every name with one, so it is worth a human looking.
  */
 export declare function cleanupTrashedBranchDirs(ctx: Pick<GitSyncContext, 'contentBranchesPath'>): Promise<number>;
 /**
  * Fast-forward the base branch's own working-tree clone
- * (content-branches/<baseBranch>) to match origin/<baseBranch>, every sync
+ * (content-branches/<baseBranch>) to match remote.git's <baseBranch>, every sync
  * cycle, so the drift window is bounded by gitSyncInterval.
  *
  * A dedicated, explicit and LOUD step rather than a side effect of the rebase
  * loop, whose skip paths (a dirty tree, a missing .git) are silent: a wedged
  * base clone otherwise leaves no diagnosable signal, and an editor forking a
- * new branch "from base" silently gets a stale snapshot.
+ * new branch "from base" silently gets a stale snapshot. The returned outcome
+ * goes to worker-status.json for the same reason.
  *
- * ff-only on purpose: this clone must stay a linear mirror of
- * origin/<baseBranch>, so a merge that isn't a fast-forward (diverged local
+ * ff-only on purpose: this clone must stay a linear mirror of remote.git's
+ * <baseBranch>, so a merge that isn't a fast-forward (diverged local
  * history) is left untouched rather than force-resolved.
+ *
+ * Holds the provisioning lock and then, like the rebase loop, the [SYNC-C1]
+ * content-write lock, both try-only: the base branch is writable in dev, and
+ * a save racing the merge's working-tree update can be overwritten by it.
  */
-export declare function refreshBaseBranchWorkspace(ctx: GitSyncContext): Promise<void>;
+export declare function refreshBaseBranchWorkspace(ctx: GitSyncContext): Promise<BaseRefreshReport>;