canopycms 0.0.68-int.98 → 0.1.0

package/dist/server.js

@@ -96,6 +96,11 @@ export { collectRoutableEntries } from './static/index.js';
  * hand-rolling the same scan over `listEntries`.
  */
 export { findDuplicateUrlPaths } from './static/index.js';
+/**
+ * Find every reference naming no entry — the check a production build runs and fails on unless
+ * `danglingReferences: 'warn'`. Pass an unscoped `listEntries()`.
+ */
+export { findDanglingReferences } from './static/index.js';
 /**
  * SEO field extraction and URL shaping, framework-agnostic. `isNoindexEntry` is the single
  * predicate behind both `robots: noindex` and sitemap exclusion.
@@ -115,28 +120,77 @@ export { createAssetStore } from './assets/factory.js';
 /**
  * The five S3/local bucket-prefix strings (`asset-originals/`, `asset-staging/`, `asset-meta/`,
  * `assets/`, `assets/t/`). Exported so server-only consumers outside this package — notably the
- * prod transform Lambda (`packages/canopycms-cdk/lambda/asset-transform`) — build and parse
+ * lazy transform Lambda (`packages/canopycms-cdk/lambda/asset-transform`) — build and parse
  * asset keys through the same constants `S3AssetStore` uses rather than duplicating the strings.
  */
 export { ASSET_PREFIXES } from './assets/keys.js';
 /**
  * Parse the three path segments after `assets/t/` (`{directives}/{hash32}/{slug}.{ext}`) into a
- * validated `TransformDirectives` set, or a structured parse error. Reused unchanged by the
- * dev-mode lazy `/assets/t/*` emulation (`api/assets.ts`) and the prod transform Lambda, so the
- * URL grammar is defined in exactly one place.
+ * validated `TransformDirectives` set, or a structured parse error, so the URL grammar is
+ * defined in exactly one place.
  */
 export { parseTransformPath } from './assets/transform-directives.js';
 /**
  * Canonical string form of a `TransformDirectives` set — the cache key every transform output is
  * stored under (`assets/t/{formatDirectives(...)}/{hash32}/{slug}.{ext}`). Equivalent directive
- * sets (different key order or float formatting) always format to the same string. Reused by the
- * prod transform Lambda so its writes agree with the dev-mode emulation and `assetUrl()`.
+ * sets (different key order or float formatting) always format to the same string.
  */
 export { formatDirectives } from './assets/transform-directives.js';
+/**
+ * Parse `assets/t/` path segments and resolve them to the canonical spelling their output is
+ * stored under, with directives re-parsed from that spelling. The lazy transform Lambda 301s a
+ * non-canonical request to it; the authenticated raw route serves the canonical bytes.
+ */
+export { canonicalizeTransformPath } from './assets/transform-directives.js';
 /**
  * Apply a parsed `TransformDirectives` set to source image bytes with sharp:
  * resize/format/quality/crop, EXIF stripped on every re-encode, identity included. Server-only
- * (sharp); reused unchanged by the dev-mode lazy `/assets/t/*` emulation and the prod transform
- * Lambda.
+ * (sharp); `storeTransform` below wraps it for every caller that stores the output.
  */
 export { applyTransform } from './assets/transform.js';
+/**
+ * Compute the transform a canonical `assets/t/` path names and store it under that key: meta
+ * lookup, raster-only, slug and ext checks, then `applyTransform`. Shared by the authenticated raw
+ * route, `materialize-assets` and the lazy transform Lambda. A 404's `error` names hashes and
+ * slugs, so a caller answering a browser replaces it.
+ */
+export { storeTransform } from './assets/materialize.js';
+/** The `Cache-Control` every stored transform output carries: content-addressed, so immutable. */
+export { TRANSFORM_CACHE_CONTROL } from './assets/materialize.js';
+/** The object tag the lazy transform Lambda's outputs carry, which its `assets/t/` expiry filters on. */
+export { LAZY_TRANSFORM_TAG } from './assets/materialize.js';
+/**
+ * Make every `assets/t/` key a build references exist in `store` (transforming only the missing
+ * ones from the stored originals) and check every referenced svg/pdf key exists. Under an
+ * `outputPrefix`, keys are written beneath it, and those production already stores are copied. A
+ * release job that bundles its own tool calls this with a store from `createAssetStore` and gates
+ * on the returned report; no site config is involved. Needs sharp only when something is missing.
+ */
+export { materializeAssets } from './assets/materialize.js';
+/**
+ * The live preview's asset prefix on the server: the signed-in raw route under a `basePath`, the
+ * same-origin check every preview prefix passes, and the hook registering the request-scoped getter
+ * `assetUrl` reads.
+ * @internal `canopycms-next`'s preview page is their consumer.
+ */
+export { authenticatedAssetBase, readAssetBase } from './editor/raw-asset-base.js';
+/** @internal */
+export { setServerPreviewAssetBaseGetter } from './editor/preview-asset-base.js';
+/** Thrown by `materializeAssets` when sharp cannot load and keys are missing, so none can be produced. */
+export { SharpUnavailableError } from './assets/materialize.js';
+/**
+ * Thrown by `materializeAssets` before any store request when `outputPrefix` is not a relative,
+ * `/`-terminated run of `[A-Za-z0-9._-]` segments outside every canopy prefix.
+ */
+export { InvalidOutputPrefixError } from './assets/materialize.js';
+/** The `schemaVersion` carried by every `MaterializeReport`. */
+export { MATERIALIZE_REPORT_SCHEMA_VERSION } from './assets/materialize.js';
+/**
+ * Scan a static build's output for `/assets/…` URLs and write `canopy-asset-refs.json` into it.
+ * Throws `AssetRefsError` for a URL no stored object can answer (non-canonical or malformed).
+ */
+export { collectAssetRefs } from './build/asset-refs.js';
+/** Read and validate a `canopy-asset-refs.json`; throws when it is unreadable or malformed. */
+export { readAssetRefsFile } from './build/asset-refs.js';
+/** Thrown by `collectAssetRefs`; `problems` lists each offending file and URL. */
+export { AssetRefsError } from './build/asset-refs.js';

package/dist/services.d.ts

@@ -17,22 +17,35 @@
  */
 import type { CanopyConfig } from './config/index.js';
 import type { EntrySchemaRegistry } from './schema/types.js';
-import type { BranchContext } from './types.js';
+import type { BranchContext, BranchPaths } from './types.js';
 import type { CanopyUser } from './user.js';
 import { createCheckBranchAccess, createCheckContentAccess, type ContentAccessChecker } from './authorization/index.js';
 import { GitManager } from './git-manager.js';
 import { BranchRegistry } from './branch-registry.js';
 import { type GitHubService } from './github-service.js';
 import { BranchSchemaCache } from './branch-schema-cache.js';
-import { type SubmissionEditor } from './submission-attribution.js';
+import { type EditorLookup, type SubmissionEditor } from './submission-attribution.js';
+import { type StampedEntry } from './stamp-on-publish.js';
 /**
  * Bootstrap admin IDs from the environment. These users are treated as Admins
  * whatever their group membership.
  */
 export declare const getBootstrapAdminIds: () => Set<string>;
+/**
+ * Submit found nothing to send: the branch's saved content, committed or not, matches its base
+ * as of the fork point. Raised before anything is pushed and after undoing any commit the
+ * submit made, so the branch's commits and saved edits are as they were.
+ */
+export declare class NothingToSubmitError extends Error {
+    constructor(branch: string, base: string);
+}
 export interface SubmitBranchResult {
     /** Repo-relative paths the branch changes, excluding canopycms runtime metadata. */
     changedPaths: string[];
+    /** Every recorded editor of the branch, for the PR body. */
+    editors: SubmissionEditor[];
+    /** The entries this submit stamped (stamp-on-publish.ts), for the editor's open forms. */
+    stamped: StampedEntry[];
 }
 export interface CanopyServices {
     config: CanopyConfig;
@@ -42,6 +55,14 @@ export interface CanopyServices {
      * content serving since the editor is pinned to its own branch via URL params.
      */
     refreshActiveBranch: () => Promise<void>;
+    /**
+     * Resolve a prod base branch that was still pending at creation because the worker had not yet
+     * created the remote it is read from; a no-op once resolved. Rejects with RemoteNotReadyError
+     * (a 503) until the remote exists. The HTTP handler (http/handler.ts) and
+     * createCanopyContext's getContext (context.ts) await it before reading
+     * `config.defaultBaseBranch`.
+     */
+    resolvePendingBaseBranch: () => Promise<void>;
     /** Entry schema registry mapping entry schema names to field definitions */
     entrySchemaRegistry: EntrySchemaRegistry;
     /** Per-branch schema cache */
@@ -73,14 +94,19 @@ export interface CanopyServices {
         message: string;
     }) => Promise<void>;
     /**
-     * Submit branch: commit all changes (with the submitter's trailers) and push
-     * to remote. Resolves with every path the branch changes against its base.
+     * Submit branch: fill new entries' empty `stampOnPublish` fields
+     * (stamp-on-publish.ts), commit all changes (with the submitter's trailers)
+     * and push to remote. Resolves with every path the branch changes against its base,
+     * and with `stamped`, the entries this submit stamped.
      * Holds the branch's content-write lock; rejects with
-     * `ContentWriteLockBusyError` when busy.
+     * `ContentWriteLockBusyError` when busy, and with `NothingToSubmitError`
+     * before pushing when the branch changes nothing.
      */
     submitBranch: (options: {
         context: BranchContext;
         submitter?: SubmissionEditor;
+        /** Names the recorded editors; without it they are credited by id. */
+        lookupEditor?: EditorLookup;
         message?: string;
     }) => Promise<SubmitBranchResult>;
     /** Commit to the settings branch (for permissions/groups) and push it; never opens a PR */
@@ -96,6 +122,8 @@ export interface CanopyServices {
     }>;
     /** Get the root path for settings storage (ensures workspace exists) */
     getSettingsBranchRoot: () => Promise<string>;
+    /** Records `user` as an editor of the branch for its next submit (branch-metadata.ts). */
+    recordBranchEditor: (context: BranchPaths, user: CanopyUser) => Promise<void>;
 }
 export interface CreateCanopyServicesOptions {
     /** Entry schema names → field definitions, for resolving .collection.json references. */

package/dist/services.js

@@ -9,18 +9,22 @@ import { operatingStrategy } from './operating-mode/index.js';
 import { BranchSchemaCache } from './branch-schema-cache.js';
 import { enqueueTask } from './task-queue/cms-task-queue.js';
 import { getTaskQueueDir } from './task-queue/task-queue-config.js';
+import { baseBranchOf } from './utils/base-branch.js';
 import { detectHeadBranch, isCanopyInternalPath } from './utils/git.js';
 import { readsFromCheckout } from './build-mode.js';
 import { timeRequestPhase } from './utils/request-timing.js';
-import { BRANCH_META_DIR } from './branch-metadata-file.js';
-import { appendTrailers, buildEditorTrailers, } from './submission-attribution.js';
+import { appendTrailers, buildEditorTrailers, describeEditors, } from './submission-attribution.js';
+import { getBranchMetadataFileManager, recordBranchEditor } from './branch-metadata.js';
+import { readBranchMetadataFile } from './branch-metadata-file.js';
 import { getErrorMessage, redactCredentials } from './utils/error.js';
 import { withContentWriteLock } from './utils/content-write-lock.js';
+import { ContentStore } from './content-store.js';
+import { stampNewEntries } from './stamp-on-publish.js';
 /**
  * A per-instance active-branch detector with its own 5s TTL cache, in priority
  * order: an explicitly configured value; `defaultBaseBranch ?? 'main'` with no
  * git for static deployments and builds; git HEAD in dev; and
- * `defaultBaseBranch ?? 'main'` in prod.
+ * `defaultBaseBranch` in prod, `undefined` while that is still unresolved.
  */
 function createActiveBranchDetector() {
     let cache = null;
@@ -42,7 +46,7 @@ function createActiveBranchDetector() {
             cache = { value: branch, expiresAt: now + 5000 };
             return branch;
         }
-        return config.defaultBaseBranch ?? 'main';
+        return config.defaultBaseBranch;
     };
 }
 /**
@@ -58,6 +62,42 @@ export const getBootstrapAdminIds = () => {
         .map((id) => id.trim())
         .filter(Boolean));
 };
+/**
+ * Submit found nothing to send: the branch's saved content, committed or not, matches its base
+ * as of the fork point. Raised before anything is pushed and after undoing any commit the
+ * submit made, so the branch's commits and saved edits are as they were.
+ */
+export class NothingToSubmitError extends Error {
+    constructor(branch, base) {
+        super(`Nothing to submit yet: "${branch}" has no saved changes compared with "${base}". ` +
+            'Save your edits, then submit.');
+        this.name = 'NothingToSubmitError';
+    }
+}
+/** The branch's recorded editor ids, or undefined, with a warning, when branch.json cannot be read. */
+async function readRecordedEditors(context) {
+    try {
+        return (await readBranchMetadataFile(context.branchRoot))?.branch;
+    }
+    catch (err) {
+        console.warn(`CanopyCMS: Could not read the recorded editors of ${context.branch.name}:`, getErrorMessage(err));
+        return undefined;
+    }
+}
+/** One lookup per user per submit, however often the submit asks. */
+function memoizeLookup(lookup) {
+    if (!lookup)
+        return undefined;
+    const seen = new Map();
+    return (userId) => {
+        let found = seen.get(userId);
+        if (!found) {
+            found = lookup(userId);
+            seen.set(userId, found);
+        }
+        return found;
+    };
+}
 /**
  * Build the reusable helpers from a validated CanopyConfig — once at startup,
  * then injected into request handlers and loaders. Schema is not loaded here;
@@ -89,25 +129,30 @@ async function _createCanopyServicesInternal(config, options) {
     const detectActiveBranch = createActiveBranchDetector();
     const explicitActiveBranch = config.defaultActiveBranch;
     const explicitBaseBranch = config.defaultBaseBranch;
-    const defaultActiveBranch = await detectActiveBranch(config);
-    // Unset, the base branch follows the same dev-mode HEAD detection, matching
-    // resolveBaseBranch in utils/git.ts — the canonical definition workspace
-    // provisioning uses.
+    // Unset, the base branch follows the rule workspace provisioning uses
+    // (GitManager.resolveWorkspaceBaseBranch): dev detects git HEAD, prod reads
+    // the remote's HEAD and fails loudly when it cannot. Prod stays pending
+    // (undefined) only while the worker has not created the remote yet; see
+    // resolvePendingBaseBranch.
     const defaultBaseBranch = explicitBaseBranch ??
-        (config.mode === 'dev' && !readsFromCheckout(config)
-            ? await detectActiveBranch({ ...config, defaultActiveBranch: undefined })
-            : 'main');
+        (readsFromCheckout(config)
+            ? 'main'
+            : config.mode === 'dev'
+                ? await detectActiveBranch({ ...config, defaultActiveBranch: undefined })
+                : await GitManager.detectBaseBranch(config, 'pending'));
+    const defaultActiveBranch = await detectActiveBranch({ ...config, defaultBaseBranch });
     config = { ...config, defaultActiveBranch, defaultBaseBranch };
     const bootstrapAdminIds = getBootstrapAdminIds();
     const branchSchemaCache = options.branchSchemaCache ?? new BranchSchemaCache(config.mode);
-    const checkBranchAccess = createCheckBranchAccess(config.defaultBranchAccess ?? 'deny', config);
+    // Reads services.config per call: the protected base branch may resolve after creation.
+    const checkBranchAccess = (context, user) => createCheckBranchAccess(config.defaultBranchAccess ?? 'deny', services.config)(context, user);
     // Content access loads permissions dynamically from the settings branch (orphan git branch)
     const ensureSettingsBranchRoot = options.getSettingsBranchRoot ??
         (async () => {
             const strategy = operatingStrategy(config.mode);
             const settingsRoot = strategy.getSettingsRoot();
             const branchName = strategy.getSettingsBranchName(config);
-            const manager = new SettingsWorkspaceManager(config);
+            const manager = new SettingsWorkspaceManager(services.config);
             await manager.ensureGitWorkspace({
                 settingsRoot,
                 branchName,
@@ -129,7 +174,7 @@ async function _createCanopyServicesInternal(config, options) {
     const configDefaults = getConfigDefaults();
     const createGitManagerFor = (repoPath, opts) => new GitManager({
         repoPath,
-        baseBranch: opts?.baseBranch ?? config.defaultBaseBranch ?? 'main',
+        baseBranch: opts?.baseBranch ?? baseBranchOf(services.config),
         remote: opts?.remote ?? config.defaultRemoteName ?? configDefaults.remoteName,
         skipIndexMarker: opts?.skipIndexMarker,
     });
@@ -151,12 +196,33 @@ async function _createCanopyServicesInternal(config, options) {
             await git.commit(options.message);
         });
     };
+    /** Runs inside submitBranch's content-write lock; a stamp that fails never blocks the submit. */
+    const stampNewEntriesOrWarn = async (context, git) => {
+        const contentRoot = services.config.contentRoot || 'content';
+        try {
+            const { flatSchema } = await services.branchSchemaCache.getSchema(context.branchRoot, services.entrySchemaRegistry, contentRoot);
+            return await stampNewEntries({
+                git,
+                store: new ContentStore(context.branchRoot, flatSchema, { contentRootName: contentRoot }),
+                branchRoot: context.branchRoot,
+                flatSchema,
+                contentRoot,
+                stampedAt: new Date().toISOString(),
+                warn: (message) => console.warn(redactCredentials(message)),
+            });
+        }
+        catch (err) {
+            console.warn(`CanopyCMS: Could not finish stamping the new entries on ${context.branch.name}; ` +
+                'submitting with only the stamps already written:', redactCredentials(getErrorMessage(err)));
+            return [];
+        }
+    };
     const submitBranch = async (options) => {
         // Defense-in-depth: refuse to push the base branch to itself even if the
         // 'submittableBranch' guard was somehow bypassed. Prefer the recorded fork
-        // point (context.branch.baseBranch) over config.defaultBaseBranch — the
-        // closure-captured `config` can go stale after dev refreshActiveBranch().
-        const effectiveBase = options.context.branch.baseBranch ?? config.defaultBaseBranch ?? 'main';
+        // point (context.branch.baseBranch) over the config value, which dev's
+        // refreshActiveBranch() can move.
+        const effectiveBase = options.context.branch.baseBranch ?? baseBranchOf(services.config);
         if (sanitizeBranchName(options.context.branch.name) === sanitizeBranchName(effectiveBase)) {
             throw new Error(`Refusing to commit and push the base branch "${options.context.branch.name}" — submitting requires a separate editing branch`);
         }
@@ -173,9 +239,25 @@ async function _createCanopyServicesInternal(config, options) {
         // lands on the branch, and the rebase's `--abort` resets the branch past it
         // after this reported success. The push stays inside so no rebase rewrites
         // the commit between commit and push.
+        const lookupEditor = memoizeLookup(options.lookupEditor);
+        const readRecorded = () => readRecordedEditors(options.context);
+        // Names are looked up before taking the lock, so a slow auth provider never holds it.
+        const named = new Map((await describeEditors((await readRecorded())?.editors ?? [], lookupEditor)).map((e) => [
+            e.userId,
+            e,
+        ]));
+        let recorded = {};
+        let stamped = [];
         const submitted = await withContentWriteLock(options.context.branchRoot, async () => {
             await git.checkoutBranch(options.context.branch.name);
+            // Before the status read, so the stamp joins this commit even when an earlier attempt
+            // already committed the entry and only its push failed.
+            stamped = await stampNewEntriesOrWarn(options.context, git);
             const status = await git.status();
+            // A save records its editor only after releasing this lock, so a save that lands just
+            // before this submit can be committed here while its editor is named by the next commit.
+            recorded = (await readRecorded()) ?? {};
+            const uncommitted = recorded.uncommittedEditors ?? [];
             // Commit and push answer two DIFFERENT questions. Committing cleans the
             // working tree, so one combined "tree is dirty" gate makes a retry after a
             // failed push a silent no-op: nothing left to commit, the block is skipped,
@@ -185,34 +267,56 @@ async function _createCanopyServicesInternal(config, options) {
             // canopycms's own state under .canopy-meta/ is never content, so it neither
             // makes a commit worth creating nor gets staged into one.
             let committed = false;
+            const preCommitSha = await git.headSha();
             if (status.files.some((f) => !isCanopyInternalPath(f.path))) {
                 await git.addAllExceptCanopyState();
-                const trailers = buildEditorTrailers(options.submitter ? [options.submitter] : [], {
+                const committers = uncommitted.map((userId) => named.get(userId) ?? { userId });
+                const trailers = buildEditorTrailers(options.submitter ? [options.submitter, ...committers] : committers, {
                     editedBy: config.gitEditedByTrailers ?? true,
                     coAuthoredBy: config.gitCoAuthoredByTrailers ?? false,
                 });
                 await git.commit(appendTrailers(options.message ?? `Submit ${options.context.branch.name}`, trailers));
                 committed = true;
             }
+            // The diff runs after the commit so it covers saved-but-uncommitted edits too, and
+            // before the push so a branch with nothing to submit never reaches the remote. A diff
+            // that cannot be computed lets the submit through: the list only feeds the PR body, and
+            // GitHub's own refusal of an empty branch is handled on both paths (api/github-sync.ts,
+            // worker/task-runner.ts).
+            let changedPaths;
+            try {
+                changedPaths = (await git.listChangedPathsSinceBase()).filter((p) => !isCanopyInternalPath(p));
+            }
+            catch (err) {
+                console.warn(`CanopyCMS: Could not list the changes on ${options.context.branch.name} against its base; ` +
+                    "the PR body lists only this submit's changes:", redactCredentials(getErrorMessage(err)));
+            }
+            if (changedPaths?.length === 0) {
+                if (committed)
+                    await git.resetKeepingChanges(preCommitSha);
+                throw new NothingToSubmitError(options.context.branch.name, effectiveBase);
+            }
+            // A failure here leaves them uncommitted, so the next commit names them again.
+            if (committed && uncommitted.length > 0) {
+                try {
+                    await getBranchMetadataFileManager(options.context.branchRoot, options.context.baseRoot).markEditorsCommitted(uncommitted);
+                }
+                catch (err) {
+                    console.warn(`CanopyCMS: Could not clear the committed editors of ${options.context.branch.name}:`, getErrorMessage(err));
+                }
+            }
             if (committed || (await git.hasUnpushedCommits(options.context.branch.name))) {
                 await git.push(options.context.branch.name);
             }
-            return status;
+            return changedPaths ?? status.files.map((f) => f.path).filter((p) => !isCanopyInternalPath(p));
         });
-        // The list only feeds the PR body, so a failure to compute it falls back to
-        // this submit's own working-tree changes rather than failing a submit that
-        // has already been pushed.
-        let changedPaths;
-        try {
-            changedPaths = await git.listChangedPathsSinceBase();
-        }
-        catch (err) {
-            console.warn(`CanopyCMS: Could not list the changes on ${options.context.branch.name} against its base; ` +
-                "the PR body lists only this submit's changes:", redactCredentials(getErrorMessage(err)));
-            changedPaths = submitted.files.map((f) => f.path);
-        }
+        // Re-read after the lock, so the PR body also names an editor recorded after the read above:
+        // one whose save this commit carries, or one whose save will reach the PR with a later push.
+        const editorIds = (await readRecorded())?.editors ?? recorded.editors ?? [];
         return {
-            changedPaths: changedPaths.filter((p) => !p.startsWith(`${BRANCH_META_DIR}/`)),
+            changedPaths: submitted,
+            editors: await describeEditors(editorIds, lookupEditor),
+            stamped,
         };
     };
     // Must be initialized before closures that reference it (commitToSettingsBranch)
@@ -328,6 +432,7 @@ async function _createCanopyServicesInternal(config, options) {
         submitBranch,
         commitToSettingsBranch,
         getSettingsBranchRoot,
+        recordBranchEditor,
         refreshActiveBranch: async () => {
             if (services.config.mode !== 'dev')
                 return;
@@ -358,14 +463,27 @@ async function _createCanopyServicesInternal(config, options) {
                 changed = true;
             }
             if (changed) {
-                // The closures above (getSettingsBranchRoot, checkContentAccess,
-                // createGitManagerFor, …) captured the original `config` local. Only
-                // branch identity changes here: git operations on existing branches use
-                // the fork point in branch metadata, and anything needing the fresh
-                // values must read services.config.
+                // The closures above captured the original `config` local. Only branch
+                // identity changes here: git operations on existing branches use the
+                // fork point in branch metadata, and anything needing the fresh values
+                // reads services.config.
                 services.config = next;
             }
         },
+        resolvePendingBaseBranch: async () => {
+            if (services.config.defaultBaseBranch)
+                return;
+            // In-process and write-once in effect: concurrent requests each read the
+            // same remote HEAD and assign the same value, and nothing is written to
+            // disk, so no lock is needed. Later changes to that HEAD are not followed
+            // (configure defaultBaseBranch to move the base branch).
+            const detected = await GitManager.detectBaseBranch(services.config, 'throw');
+            services.config = {
+                ...services.config,
+                defaultBaseBranch: detected,
+                defaultActiveBranch: services.config.defaultActiveBranch ?? detected,
+            };
+        },
     };
     return services;
 }

package/dist/settings-workspace.d.ts

@@ -8,8 +8,8 @@ import type { OperatingMode } from './operating-mode/index.js';
  * its target, and `GitManager.initializeWorkspace` clones INTO the settings
  * root, which `git clone` refuses if anything is already there. A dedicated
  * dot-directory also keeps this marker out of `path.dirname(settingsRoot)`,
- * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — settings init
- * calls into that while holding this lock, so separate directories make the
+ * where `ensureLocalSimulatedRemote` puts `.remote-init.lock` — an in-place
+ * settings re-init calls into that while holding this lock, so separate directories make the
  * nesting obvious rather than incidental. For how a lock's anchor path is
  * chosen, see utils/provisioning-lock.ts and docs/concurrency.md.
  * @internal Exported for tests.
@@ -27,12 +27,32 @@ export interface EnsureSettingsWorkspaceOptions {
  * BranchWorkspaceManager this writes no metadata files and never touches the
  * branch registry.
  *
+ * A first clone follows [PROV-1] (branch-provisioning.ts): it is built in a
+ * staging sibling and renamed into place, so a process killed mid-clone never
+ * leaves a half-made workspace at the settings root. Never sparse: the orphan
+ * init's `git rm -rf .` would leave out-of-cone base files in the tree.
+ *
  * Two locking layers, mirroring BranchWorkspaceManager: an in-memory promise
  * lock within the process, and `acquireProvisioningLock` (proper-lockfile)
- * across processes and hosts.
+ * across processes and hosts around the publish and every in-place init.
  */
 export declare class SettingsWorkspaceManager {
     private readonly config;
     constructor(config: CanopyConfig);
     ensureGitWorkspace(options: EnsureSettingsWorkspaceOptions): Promise<void>;
+    private initOptions;
+    /**
+     * Layer 2 around the init itself (proper-lockfile: heartbeat-refreshed while the holder lives,
+     * so a slow EFS operation is not mistaken for a crash, and patient retries so a loser WAITS
+     * instead of racing into a concurrent init).
+     */
+    private withInitLock;
+    /** Re-init an existing workspace where it is; false when, under the lock, there is none. */
+    private ensureInPlace;
+    /**
+     * Clone and set up the settings branch in a staging sibling, then publish it under the init
+     * lock, moving an interrupted first init aside to `.trash-settings-*`. A workspace someone
+     * else published meanwhile wins and the staging copy is dropped.
+     */
+    private provisionStaged;
 }