canopycms 0.0.67 → 0.0.68-int.101

package/dist/utils/content-serialize.js

@@ -5,7 +5,9 @@
  * deletes every comment in the file, because comments live in neither the object nor that round
  * trip. So these functions re-serialise onto the file's OWN parsed document: a node whose value
  * did not change is left untouched, and an untouched node keeps its attached comments and its
- * original quoting/block style. Only what actually changed is rewritten.
+ * original quoting/block style. Only what actually changed is rewritten, and
+ * `yaml-source-splice.ts` writes it into the file's own text, so untouched lines keep their bytes
+ * wherever it can vouch for the result.
  *
  * The file gets no authority over its own content. The reconciler makes the document's key set
  * match `data` exactly — a key the caller dropped disappears, a key the caller kept survives
@@ -14,9 +16,14 @@
  * is a schema question, answered one layer up by `findUnknownKeys`
  * (validation/entry-validator.ts) at the API boundary, not by a schema-blind serialiser.
  */
+import { isDeepStrictEqual } from 'node:util';
 import matter from 'gray-matter';
-import { isCollection, isMap, isNode, isScalar, isSeq, parseDocument, stringify as yamlStringify, } from 'yaml';
+import { isCollection, isMap, isNode, isScalar, isSeq, parseDocument, Scalar, stringify as yamlStringify, } from 'yaml';
 import { isBlockStructuralKey } from '../validation/block-structural-keys.js';
+import { createDebugLogger } from './debug.js';
+import { getErrorMessage } from './error.js';
+import { snapshotDocument, spliceSource, withSourceLineEndings } from './yaml-source-splice.js';
+const log = createDebugLogger({ prefix: 'ContentSerialize' });
 /**
  * True only for a PLAIN object — one that should be reconciled key-by-key against a YAML map.
  *
@@ -187,13 +194,13 @@ function looksLikeSameItem(node, value) {
  * Reconcile one slot of the document against the value that must occupy it, returning the node to
  * put there. `existing` is the node in that slot, or null/undefined for a slot that did not exist.
  */
-function reconcileNode(doc, existing, value) {
+function reconcileNode(ctx, existing, value) {
     if (isMap(existing) && isPlainRecord(value)) {
-        reconcileMap(doc, existing, value);
+        reconcileMap(ctx, existing, value);
         return existing;
     }
     if (isSeq(existing) && Array.isArray(value)) {
-        reconcileSeq(doc, existing, value);
+        reconcileSeq(ctx, existing, value);
         return existing;
     }
     // Unchanged scalar: return the node itself, untouched. This is the case that preserves comments
@@ -203,7 +210,16 @@ function reconcileNode(doc, existing, value) {
     // Changed, or a shape change (scalar <-> collection). A fresh node rather than mutating
     // `scalar.value` in place, which would keep the old node's representation and emit `'42'` where
     // the number 42 was meant.
-    const fresh = doc.createNode(value);
+    const fresh = ctx.doc.createNode(value);
+    if (isNode(existing))
+        ctx.replaced.set(fresh, existing);
+    if (isScalar(existing) && isScalar(fresh) && typeof value === 'string') {
+        const style = carriedStyle(existing, value);
+        if (style !== undefined) {
+            fresh.type = style;
+            ctx.restyled.push(fresh);
+        }
+    }
     // Comments move with a changed VALUE, but not off a replaced STRUCTURE. `yaml` attaches a
     // comment written above a collection's first entry to the collection node itself, so that
     // node's comments are about its innards; carrying them onto whatever replaces the collection
@@ -214,12 +230,33 @@ function reconcileNode(doc, existing, value) {
         carryComments(existing, fresh);
     return fresh;
 }
+/**
+ * The style a changed string inherits from the string it replaces: its quoting, or its block
+ * style (`>-`, `|`) unless the new value has no content or leads with whitespace, which `yaml`
+ * can print lossily in a block (`"   "` reads back as `""`). Never `PLAIN`: forcing it stops `yaml` choosing a
+ * block for a multi-line value, and some (`Requirements:\nBring a laptop`) then print as
+ * unparseable YAML. An unset style is plain where plain is safe.
+ */
+function carriedStyle(existing, value) {
+    if (typeof existing.value !== 'string')
+        return undefined;
+    switch (existing.type) {
+        case Scalar.QUOTE_DOUBLE:
+        case Scalar.QUOTE_SINGLE:
+            return existing.type;
+        case Scalar.BLOCK_FOLDED:
+        case Scalar.BLOCK_LITERAL:
+            return /\S/.test(value) && !/^\s/.test(value) ? existing.type : undefined;
+        default:
+            return undefined;
+    }
+}
 /**
  * Make a map's key set match `value` exactly. Retained pairs are reconciled in place, so their key
  * order and the comments attached to their keys survive; keys new to `value` are appended in
  * `value` order, keeping a save's diff down to the lines that actually changed.
  */
-function reconcileMap(doc, map, value) {
+function reconcileMap(ctx, map, value) {
     // An explicitly-undefined key is NOT a key: `Object.keys` reports it but `JSON.stringify` and
     // `yaml.stringify` omit it, so without this filter a key present on disk and set to `undefined`
     // in the payload is rewritten as `key: null` here while the create path drops it. Same rule on
@@ -234,14 +271,14 @@ function reconcileMap(doc, map, value) {
         if (key === undefined || !wanted.has(key) || seen.has(key))
             continue;
         seen.add(key);
-        pair.value = reconcileNode(doc, pair.value, value[key]);
+        pair.value = reconcileNode(ctx, pair.value, value[key]);
         retained.push(pair);
     }
     map.items = retained;
     for (const key of Object.keys(value)) {
         if (seen.has(key) || !wanted.has(key))
             continue;
-        map.set(doc.createNode(key), doc.createNode(value[key]));
+        map.set(ctx.doc.createNode(key), ctx.doc.createNode(value[key]));
     }
 }
 /**
@@ -261,7 +298,7 @@ function reconcileMap(doc, map, value) {
  *    replacement lands on the index it replaced.
  * 3. **Otherwise a fresh node, with no comments.**
  */
-function reconcileSeq(doc, seq, value) {
+function reconcileSeq(ctx, seq, value) {
     const oldItems = seq.items;
     // Old indices by identity, in order, so equal items are consumed first-come-first-served.
     const byIdentity = new Map();
@@ -298,28 +335,67 @@ function reconcileSeq(doc, seq, value) {
         // unclaimed?". Each iteration owns a distinct index, so a candidate cannot be taken twice.
         const candidate = index < oldItems.length && !consumed.has(index) ? oldItems[index] : undefined;
         const sameItem = candidate !== undefined && looksLikeSameItem(candidate, item) ? candidate : undefined;
-        return reconcileNode(doc, sameItem, item);
+        return reconcileNode(ctx, sameItem, item);
     });
 }
-/** Apply `data` onto a parsed document, preserving every node the data did not change. */
-function applyDataToDocument(doc, data) {
-    doc.contents = reconcileNode(doc, doc.contents, data);
+/**
+ * Re-serialise `data` onto the YAML text `raw`, or undefined when `raw` does not parse or the
+ * reconciled document cannot be printed so that it reads back as its own data.
+ *
+ * The reconciler decides WHAT changes; {@link spliceSource} then writes those changes into the
+ * source text, so untouched lines keep the author's own folding and spacing. When it cannot
+ * vouch for a splice, the result is the reconciled document's own `toString()`, which is itself
+ * kept only if it parses back to the same data: a carried style that `yaml` prints lossily is
+ * dropped and the document re-printed, and failing that the caller writes a plain stringify.
+ * The worst case is a re-folded file, or one without its comments; never different data.
+ * `rootAtColumnZero` refuses a splice whose first line is indented, for frontmatter, whose
+ * framing trims the first line's indentation.
+ */
+function reconcileYamlSource(raw, data, rootAtColumnZero = false) {
+    const doc = parseDocument(raw);
+    if (doc.errors.length > 0)
+        return undefined;
+    const snapshot = snapshotDocument(doc);
+    const ctx = { doc, replaced: new WeakMap(), restyled: [] };
+    doc.contents = reconcileNode(ctx, doc.contents, data);
+    let reconciled = withSourceLineEndings(doc.toString(), raw);
+    if (!readsBackAs(reconciled, doc)) {
+        for (const scalar of ctx.restyled)
+            scalar.type = undefined;
+        reconciled = withSourceLineEndings(doc.toString(), raw);
+        if (!readsBackAs(reconciled, doc))
+            return undefined;
+    }
+    try {
+        const spliced = spliceSource(raw, doc, snapshot, ctx.replaced, reconciled);
+        if (spliced !== undefined && !(rootAtColumnZero && /^\s*[ \t]\S/.test(spliced))) {
+            return spliced;
+        }
+        log.debug('content-serialize', 'source splice not used; writing as yaml prints it');
+    }
+    catch (err) {
+        log.debug('content-serialize', 'source splice failed; writing as yaml prints it', {
+            error: getErrorMessage(err),
+        });
+    }
+    return reconciled;
+}
+function readsBackAs(text, doc) {
+    const reparsed = parseDocument(text);
+    return reparsed.errors.length === 0 && isDeepStrictEqual(reparsed.toJS(), doc.toJS());
 }
 /**
  * Serialise entry data as a YAML file, carrying the comments of `existingRaw` through.
  *
  * Falls back to a plain stringify — byte-identical to serialising without preservation — when
  * there is nothing to preserve (a new file) or nothing trustworthy to preserve (the bytes on disk
- * do not parse). A save must not fail because the previous content was malformed.
+ * do not parse, or the reconciled document does not read back as its own data). A save must not
+ * fail because the previous content was malformed.
  */
 export function serializeYaml(data, existingRaw) {
     if (existingRaw === undefined)
         return yamlStringify(data);
-    const doc = parseDocument(existingRaw);
-    if (doc.errors.length > 0)
-        return yamlStringify(data);
-    applyDataToDocument(doc, data);
-    return doc.toString();
+    return reconcileYamlSource(existingRaw, data) ?? yamlStringify(data);
 }
 /**
  * Split a file into its raw frontmatter string, or undefined when there is nothing usable. Two
@@ -362,11 +438,9 @@ export function serializeFrontmatter(body, data, existingRaw) {
     const existingFrontmatter = extractRawFrontmatter(existingRaw);
     if (existingFrontmatter === undefined)
         return matter.stringify(body, data);
-    const doc = parseDocument(existingFrontmatter);
-    if (doc.errors.length > 0)
+    const reconciled = reconcileYamlSource(existingFrontmatter, data, true);
+    if (reconciled === undefined)
         return matter.stringify(body, data);
-    applyDataToDocument(doc, data);
-    const reconciled = doc.toString();
     return matter.stringify(body, data, {
         engines: {
             yaml: {

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

@@ -21,9 +21,10 @@
  *
  * 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 and base-branch refresh hold both, provisioning outside this one, and
+ * take each try-only; the global order is docs/concurrency.md's "Lock acquisition order".
+ * `.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.
@@ -50,14 +51,24 @@ export declare const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
  * Thrown when the bounded wait expires with the branch's content lock still held. Retriable --
  * callers translate it into a 409 with a message that says so.
  *
- * The message says "syncing OR another save" because BOTH produce it: the lock is taken by
- * `write`/`delete`/`renameEntry` and the admin repair-content-duplicates action as well as by the
- * worker's rebase, so naming only the rebase would claim more than is known. `api/content.ts`
+ * The message says "syncing OR another save" because BOTH produce it: the lock is taken by every
+ * working-tree mutator (docs/concurrency.md, "Who takes it") as well as by the worker's rebase,
+ * so naming only the rebase would claim more than is known. `api/content.ts`
  * routes this error ahead of the generic conflict so the editor sees this wording, making it
  * load-bearing rather than cosmetic.
  */
 export declare class ContentWriteLockBusyError extends Error {
-    constructor(message?: string);
+    /**
+     * `'not-run'`: the lock was never acquired, so nothing happened. `'unknown'`: the work ran
+     * but the lock was lost during it (see {@link withContentWriteLock}).
+     */
+    readonly outcome: 'not-run' | 'unknown';
+    constructor(message?: string, 
+    /**
+     * `'not-run'`: the lock was never acquired, so nothing happened. `'unknown'`: the work ran
+     * but the lock was lost during it (see {@link withContentWriteLock}).
+     */
+    outcome?: 'not-run' | 'unknown');
 }
 /**
  * Acquire the branch's content-write lock WITHOUT waiting, for the worker's rebase loop, which

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

@@ -21,9 +21,10 @@
  *
  * 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 and base-branch refresh hold both, provisioning outside this one, and
+ * take each try-only; the global order is docs/concurrency.md's "Lock acquisition order".
+ * `.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.
@@ -57,15 +58,21 @@ export const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
  * Thrown when the bounded wait expires with the branch's content lock still held. Retriable --
  * callers translate it into a 409 with a message that says so.
  *
- * The message says "syncing OR another save" because BOTH produce it: the lock is taken by
- * `write`/`delete`/`renameEntry` and the admin repair-content-duplicates action as well as by the
- * worker's rebase, so naming only the rebase would claim more than is known. `api/content.ts`
+ * The message says "syncing OR another save" because BOTH produce it: the lock is taken by every
+ * working-tree mutator (docs/concurrency.md, "Who takes it") as well as by the worker's rebase,
+ * so naming only the rebase would claim more than is known. `api/content.ts`
  * routes this error ahead of the generic conflict so the editor sees this wording, making it
  * load-bearing rather than cosmetic.
  */
 export class ContentWriteLockBusyError extends Error {
-    constructor(message = 'This branch is busy (syncing with the base branch, or another save is in flight); the change was not saved. Try again in a moment.') {
+    constructor(message = 'This branch is busy (syncing with the base branch, or another save is in flight); the change was not saved. Try again in a moment.', 
+    /**
+     * `'not-run'`: the lock was never acquired, so nothing happened. `'unknown'`: the work ran
+     * but the lock was lost during it (see {@link withContentWriteLock}).
+     */
+    outcome = 'not-run') {
         super(message);
+        this.outcome = outcome;
         this.name = 'ContentWriteLockBusyError';
     }
 }
@@ -77,12 +84,14 @@ function lockTargetDir(branchRoot) {
 const sleep = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms);
 });
+/** Below provisioning's, so a crashed worker blocks saves for at most 30s (docs/concurrency.md). */
+const CONTENT_WRITE_LOCK_STALE_MS = 30_000;
 /**
  * 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 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, false);
 }
 /**
  * Acquire the branch's content-write lock with a short bounded wait.
@@ -136,7 +145,7 @@ export async function withContentWriteLock(branchRoot, fn, waitMs = DEFAULT_CONT
         // disk and only the proof of exclusivity is lost. "Reload, then decide" rather than "retry",
         // which would resend a now-stale expectedVersion and bounce off the caller's own landed write
         // as a phantom editor collision.
-        throw new ContentWriteLockBusyError('This branch was being synced while your change was written, so the change may or may not have been recorded. Reload the entry to see the current state before saving again.');
+        throw new ContentWriteLockBusyError('This branch was being synced while your change was written, so the change may or may not have been recorded. Reload the entry to see the current state before saving again.', 'unknown');
     }
     return result;
 }

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,28 @@ 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.
+ *
+ * `--sparse`: in a sparse clone a plain `add -A` fails on any file present outside the cone.
+ * With it, such a file is staged like any other, and a tracked file absent only because it is
+ * outside the cone is still not staged as a deletion. A no-op in a full 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,33 @@ 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.
+ *
+ * `--sparse`: in a sparse clone a plain `add -A` fails on any file present outside the cone.
+ * With it, such a file is staged like any other, and a tracked file absent only because it is
+ * outside the cone is still not staged as a deletion. A no-op in a full clone.
+ */
+export async function stageAllExceptCanopyState(git) {
+    await git.raw(['add', '-A', '--sparse']);
+    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/occ-json-write.js

@@ -158,8 +158,16 @@ export async function withOccRetry(operation, options) {
  * legitimately take many seconds.
  */
 export async function withOccFileLock(filePath, fn) {
-    const dir = path.dirname(filePath);
-    await fs.mkdir(dir, { recursive: true });
+    // The lock's own directory only, never its ancestors: a waiter must not recreate a branch root
+    // that a delete removed under it (the same rule as the ENOENT case in the loop below).
+    try {
+        await fs.mkdir(path.dirname(filePath));
+    }
+    catch (err) {
+        if (!isNodeError(err) || err.code !== 'EEXIST') {
+            throw new OccWriteConflictError(`Could not acquire file lock: ${getErrorMessage(err)}`);
+        }
+    }
     // Acquisition retries are OUR loop, not proper-lockfile's built-in
     // `retries`: the built-in loop retries blindly on ANY error, so a waiter
     // whose target directory was deleted mid-poll (deleteBranch's rm removing

package/dist/utils/provision-log.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Replace where step lines go; no argument restores `canopyLog`. The test
+ * setup silences them, since nearly every suite provisions a workspace.
+ * @internal Exported for tests.
+ */
+export declare function setProvisionLogSink(next?: (line: string) => void): void;
+/**
+ * Per-step timing for one workspace provisioning, printed unconditionally
+ * (never behind `CANOPYCMS_DEBUG`). A request killed mid-step, such as a Lambda
+ * at its timeout, never reaches its own error handling, so each step prints a
+ * `start` line and a `done` line: the last line in the log names the step that
+ * was running.
+ *
+ * Lines read `[canopy] provision id=<id> dir=<dir> step=<step> start|done ms=<n>|failed ms=<n>`,
+ * then one `outcome=<outcome> total=<ms> <step>=<ms> …` summary.
+ */
+export declare class ProvisionLog {
+    readonly id: string;
+    private readonly startedAt;
+    private readonly durations;
+    private readonly prefix;
+    constructor(dir: string);
+    step<T>(name: string, run: () => Promise<T>): Promise<T>;
+    finish(outcome: string): void;
+}

package/dist/utils/provision-log.js

@@ -0,0 +1,49 @@
+import { randomBytes } from 'node:crypto';
+import { canopyLog } from './logger.js';
+const defaultSink = (line) => canopyLog(line);
+let sink = defaultSink;
+/**
+ * Replace where step lines go; no argument restores `canopyLog`. The test
+ * setup silences them, since nearly every suite provisions a workspace.
+ * @internal Exported for tests.
+ */
+export function setProvisionLogSink(next) {
+    sink = next ?? defaultSink;
+}
+/**
+ * Per-step timing for one workspace provisioning, printed unconditionally
+ * (never behind `CANOPYCMS_DEBUG`). A request killed mid-step, such as a Lambda
+ * at its timeout, never reaches its own error handling, so each step prints a
+ * `start` line and a `done` line: the last line in the log names the step that
+ * was running.
+ *
+ * Lines read `[canopy] provision id=<id> dir=<dir> step=<step> start|done ms=<n>|failed ms=<n>`,
+ * then one `outcome=<outcome> total=<ms> <step>=<ms> …` summary.
+ */
+export class ProvisionLog {
+    constructor(dir) {
+        this.id = randomBytes(3).toString('hex');
+        this.startedAt = Date.now();
+        this.durations = [];
+        this.prefix = `[canopy] provision id=${this.id} dir=${dir}`;
+    }
+    async step(name, run) {
+        sink(`${this.prefix} step=${name} start`);
+        const stepStartedAt = Date.now();
+        let state = 'failed';
+        try {
+            const result = await run();
+            state = 'done';
+            return result;
+        }
+        finally {
+            const ms = Date.now() - stepStartedAt;
+            this.durations.push(`${name}=${ms}`);
+            sink(`${this.prefix} step=${name} ${state} ms=${ms}`);
+        }
+    }
+    finish(outcome) {
+        const total = Date.now() - this.startedAt;
+        sink(`${this.prefix} outcome=${outcome} total=${total} ${this.durations.join(' ')}`.trim());
+    }
+}

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

@@ -9,6 +9,19 @@
  * inside the refresh timer, so a throw is an uncaught exception that kills the process.
  */
 export type OnLockCompromised = (err: Error) => void;
+/**
+ * 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.
+ */
+export declare const PROVISIONING_LOCK_STALE_MS = 90000;
+/**
+ * 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 +40,29 @@ 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}
+ * @param createParents whether a missing parent of `lockTargetDir` is created. A lock inside a
+ *   branch passes false: a waiter must never recreate a branch root a delete removed, so a missing
+ *   parent fails with ENOENT instead.
+ */
+export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised, staleMs?: number, createParents?: boolean): Promise<() => Promise<void>>;
+/**
+ * {@link tryAcquireProvisioningLock} retried for at most `waitMs`, for a caller whose own hold is
+ * milliseconds long (publishing a staged branch workspace). A dead holder's marker stays live for
+ * {@link PROVISIONING_LOCK_STALE_MS}, so waiting it out from a request would spend the request's
+ * whole timeout; this gives up instead.
+ *
+ * Retries only on `ELOCKED`, like the content-write lock's bounded wait.
+ *
+ * @throws the last `ELOCKED` error once the budget is spent
  */
-export declare function tryAcquireProvisioningLock(lockTargetDir: string, lockName: string, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;
+export declare function acquireProvisioningLockWithin(lockTargetDir: string, lockName: string, waitMs: number, onCompromised?: OnLockCompromised): Promise<() => Promise<void>>;