canopycms 0.0.67 → 0.0.68-int.101

package/dist/assets/types.d.ts

@@ -41,6 +41,12 @@ export interface PublicObject {
     contentDisposition?: string;
     cacheControl?: string;
 }
+/**
+ * What a create-only write did. Every key the store writes this way is content-addressed, so no
+ * correct writer ever replaces an object: `already-exists` means an object was already at the key
+ * and was left alone.
+ */
+export type CreateOnlyResult = 'created' | 'already-exists';
 export interface AssetStore {
     readonly capabilities: {
         directUpload: boolean;
@@ -49,26 +55,47 @@ export interface AssetStore {
     writeStaging(stagingKey: string, data: Uint8Array, contentType?: string): Promise<void>;
     readStaging(stagingKey: string): Promise<Uint8Array | null>;
     deleteStaging(stagingKey: string): Promise<void>;
+    /** Create-only; see `CreateOnlyResult`. */
     putOriginal(input: {
         hash32: string;
         ext: string;
         data: Uint8Array;
         contentType: string;
-    }): Promise<void>;
-    readOriginal(hash32: string): Promise<{
+    }): Promise<CreateOnlyResult>;
+    /**
+     * `ext` is where the original is expected (its meta's `ext`): that key is read first, and any
+     * `{hash32}.*` is looked for only on a miss. A hit needs no list permission; on S3 without
+     * `s3:ListBucket` a miss is a 403, which throws.
+     */
+    readOriginal(hash32: string, ext?: string): Promise<{
         data: Uint8Array;
         ext: string;
         contentType?: string;
     } | null>;
+    /** Create-only; see `CreateOnlyResult`. */
     putPublicObject(input: {
         key: string;
         data: Uint8Array;
         contentType: string;
         contentDisposition?: string;
         cacheControl?: string;
-    }): Promise<void>;
+        /** Object tags; bucket lifecycle rules can filter on them. */
+        tags?: Readonly<Record<string, string>>;
+    }): Promise<CreateOnlyResult>;
+    /**
+     * Copy the public object at `sourceKey` to `destKey` inside the store, create-only like
+     * `putPublicObject`. The copy keeps the source's headers and carries no tags. `source-missing`
+     * when nothing is at `sourceKey`.
+     */
+    copyPublicObject(sourceKey: string, destKey: string): Promise<CreateOnlyResult | 'source-missing'>;
     readPublicObject(key: string): Promise<PublicObject | null>;
-    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<'created' | 'already-exists'>;
+    /** Whether a public object exists at `key`, without reading its body. */
+    hasPublicObject(key: string): Promise<boolean>;
+    /** Every public object key under `prefix`, in the store's own pages. S3 only. */
+    listPublicObjectKeys?(prefix: string): AsyncIterable<string>;
+    /** A short-lived URL a browser can GET `key` from directly, or `null` if absent. S3 only. */
+    presignPublicObjectRead?(key: string): Promise<string | null>;
+    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<CreateOnlyResult>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
     listMeta(input?: {
         cursor?: string;

package/dist/auth/file-based-auth-cache.js

@@ -168,14 +168,13 @@ export async function writeAuthCacheSnapshot(cachePath, files) {
         await fs.rename(tmpPath, finalPath);
     }
     // The symlink target MUST be relative (the bare `snapshot-<ts>` basename),
-    // because writer and reader do not share a mount namespace: in prod the EC2
-    // worker writes through /mnt/efs/workspace/.cache while the CMS Lambda mounts
-    // the /workspace access point and reads the SAME directory as /mnt/efs/.cache.
-    // An absolute target recorded by one is a nonexistent path to the other, and
-    // `resolveActiveCacheDir`'s escape guard then falls back to the flat layout,
-    // where the worker never writes — leaving the Lambda a permanently empty
-    // cache. A relative target resolves against whichever cachePath the reader
-    // was given, so it is correct from both.
+    // because writer and reader are separate hosts (in prod, the EC2 worker and
+    // the CMS Lambda) that each mount EFS themselves, so nothing guarantees they
+    // reach this directory by the same path. An absolute target recorded by one
+    // can be a nonexistent path to the other, and `resolveActiveCacheDir`'s
+    // escape guard then falls back to the flat layout, where the worker never
+    // writes, leaving the reader a permanently empty cache. A relative target
+    // resolves against whichever cachePath the reader was given.
     const currentLink = path.join(cachePath, 'current');
     const tmpLink = path.join(cachePath, `current-${timestamp}`);
     await fs.symlink(path.basename(snapshotDir), tmpLink);

package/dist/authorization/content.d.ts

@@ -6,12 +6,13 @@ import type { BranchContext } from '../types.js';
 import type { PermissionLevel } from '../config/index.js';
 import type { CanopyUser } from '../user.js';
 import type { ContentAccessResult, ContentAccessDeps } from './types.js';
-import type { PhysicalPath } from '../paths/types.js';
+import type { LogicalPath } from '../paths/types.js';
 /**
  * A bound content-access checker: evaluates a single path/level synchronously
  * against permissions that were already loaded when the checker was created.
+ * The path is the entry's logical path (see `checkPathAccess`).
  */
-export type ContentAccessChecker = (relativePath: PhysicalPath, level: PermissionLevel) => ContentAccessResult;
+export type ContentAccessChecker = (logicalPath: LogicalPath, level: PermissionLevel) => ContentAccessResult;
 /**
  * Resolve the request-constant work once -- branch access, the
  * settings/permissions root and the path-permission rules, all identical for a
@@ -26,5 +27,5 @@ export declare function createContentAccessChecker(deps: ContentAccessDeps, cont
  * Single-path check; loads the path permissions from the branch root per call.
  * @internal Exported for tests.
  */
-export declare function checkContentAccess(deps: ContentAccessDeps, context: BranchContext, branchRoot: string, relativePath: PhysicalPath, user: CanopyUser, level: PermissionLevel): Promise<ContentAccessResult>;
-export declare function createCheckContentAccess(deps: ContentAccessDeps): (context: BranchContext, branchRoot: string, relativePath: PhysicalPath, user: CanopyUser, level: PermissionLevel) => Promise<ContentAccessResult>;
+export declare function checkContentAccess(deps: ContentAccessDeps, context: BranchContext, branchRoot: string, logicalPath: LogicalPath, user: CanopyUser, level: PermissionLevel): Promise<ContentAccessResult>;
+export declare function createCheckContentAccess(deps: ContentAccessDeps): (context: BranchContext, branchRoot: string, logicalPath: LogicalPath, user: CanopyUser, level: PermissionLevel) => Promise<ContentAccessResult>;

package/dist/authorization/content.js

@@ -28,9 +28,9 @@ export async function createContentAccessChecker(deps, context, branchRoot, user
     }
     const rules = await deps.loadPathPermissions(permissionsRoot, deps.mode);
     const pathChecker = createCheckPathAccess(rules, deps.defaultPathAccess);
-    return (relativePath, level) => {
+    return (logicalPath, level) => {
         const path = pathChecker({
-            relativePath,
+            logicalPath,
             user,
             level,
         });
@@ -45,10 +45,10 @@ export async function createContentAccessChecker(deps, context, branchRoot, user
  * Single-path check; loads the path permissions from the branch root per call.
  * @internal Exported for tests.
  */
-export async function checkContentAccess(deps, context, branchRoot, relativePath, user, level) {
+export async function checkContentAccess(deps, context, branchRoot, logicalPath, user, level) {
     const check = await createContentAccessChecker(deps, context, branchRoot, user);
-    return check(relativePath, level);
+    return check(logicalPath, level);
 }
 export function createCheckContentAccess(deps) {
-    return (context, branchRoot, relativePath, user, level) => checkContentAccess(deps, context, branchRoot, relativePath, user, level);
+    return (context, branchRoot, logicalPath, user, level) => checkContentAccess(deps, context, branchRoot, logicalPath, user, level);
 }

package/dist/authorization/path.d.ts

@@ -1,7 +1,7 @@
 import type { PathPermission, DefaultPathAccess, PermissionLevel } from '../config/index.js';
 import type { CanopyUser } from '../user.js';
 import type { PathPermissionResult } from './types.js';
-import type { PhysicalPath } from '../paths/types.js';
+import type { LogicalPath } from '../paths/types.js';
 /**
  * Resolve `defaultPathAccess` to an 'allow'/'deny' verdict for one permission
  * level. String form applies to every level; object form looks up the level,
@@ -11,19 +11,24 @@ import type { PhysicalPath } from '../paths/types.js';
  */
 export declare function resolveDefaultPathAccess(defaultAccess: DefaultPathAccess, level: PermissionLevel): 'allow' | 'deny';
 /**
- * Evaluate access for a relative path against config-defined rules.
- * Uses defaultAccess when no rule matches. First matching rule wins.
+ * Evaluate access for a path against config-defined rules. First matching rule wins;
+ * defaultAccess applies when none matches.
+ *
+ * Rule globs and the checked path are both LOGICAL paths: content-root-prefixed and
+ * id-free, the space the Permission Manager writes rules in. An entry's logical path is
+ * `<collection logical path>/<slug>` (`entryLogicalPath`), e.g. `content/blog/my-post`, never
+ * its on-disk `content/blog.<id>/post.my-post.<id>.json`.
  * @internal Exported for tests.
  */
-export declare function checkPathAccess({ rules, relativePath, user, defaultAccess, level, }: {
+export declare function checkPathAccess({ rules, logicalPath, user, defaultAccess, level, }: {
     rules: PathPermission[];
-    relativePath: PhysicalPath;
+    logicalPath: LogicalPath;
     user: CanopyUser;
     defaultAccess: DefaultPathAccess;
     level: PermissionLevel;
 }): PathPermissionResult;
 export declare function createCheckPathAccess(rules: PathPermission[], defaultAccess: DefaultPathAccess): (input: {
-    relativePath: PhysicalPath;
+    logicalPath: LogicalPath;
     user: CanopyUser;
     level: PermissionLevel;
 }) => PathPermissionResult;

package/dist/authorization/path.js

@@ -5,8 +5,8 @@ function normalize(p) {
     const normalized = p.split(path.sep).join('/');
     return normalized.replace(/^\.?\/*/, '');
 }
-function matchesRule(rule, relativePath) {
-    return minimatch(relativePath, rule.path, { dot: true });
+function matchesRule(rule, logicalPath) {
+    return minimatch(logicalPath, rule.path, { dot: true });
 }
 function isAllowedByTarget(target, user) {
     const hasUserConstraint = !!target.allowedUsers?.length;
@@ -32,12 +32,17 @@ export function resolveDefaultPathAccess(defaultAccess, level) {
     return defaultAccess[level] ?? 'deny';
 }
 /**
- * Evaluate access for a relative path against config-defined rules.
- * Uses defaultAccess when no rule matches. First matching rule wins.
+ * Evaluate access for a path against config-defined rules. First matching rule wins;
+ * defaultAccess applies when none matches.
+ *
+ * Rule globs and the checked path are both LOGICAL paths: content-root-prefixed and
+ * id-free, the space the Permission Manager writes rules in. An entry's logical path is
+ * `<collection logical path>/<slug>` (`entryLogicalPath`), e.g. `content/blog/my-post`, never
+ * its on-disk `content/blog.<id>/post.my-post.<id>.json`.
  * @internal Exported for tests.
  */
-export function checkPathAccess({ rules, relativePath, user, defaultAccess, level, }) {
-    const normalizedPath = normalize(relativePath);
+export function checkPathAccess({ rules, logicalPath, user, defaultAccess, level, }) {
+    const normalizedPath = normalize(logicalPath);
     // Only Admins bypass all path permissions
     if (isAdmin(user.groups)) {
         return { allowed: true, reason: 'admin' };

package/dist/authorization/types.d.ts

@@ -1,6 +1,6 @@
 /**
- * A path used in permission rules, e.g. "content/posts".
- * SECURITY CRITICAL: always validated to prevent path traversal.
+ * A logical-path glob used in permission rules, e.g. "content/posts/**" (see
+ * `PathPermission.path`). SECURITY CRITICAL: always validated to prevent path traversal.
  */
 export type PermissionPath = string & {
     readonly __brand: 'PermissionPath';

package/dist/branch-health.d.ts

@@ -6,13 +6,19 @@ import { type DuplicateContentId } from './content-id-index.js';
  * Without it two stuck states have no in-product recovery, and prod admins have
  * no filesystem access to see them: a branch dir whose `.canopy-meta/branch.json`
  * is corrupt (the registry drops it silently) and an orphan dir with no
- * `branch.json` at all (a partial delete crash — see `api/branch.ts`).
+ * `branch.json` at all (a clone or delete killed in place, until the worker
+ * quarantines it — see branch-provisioning.ts).
  *
  * `scanBranchHealth` mirrors the registry's own directory-listing rules (skip
  * non-directories and dot-prefixed names) so the two never disagree about what
  * counts as missing.
  */
 type BranchHealthKind = 'healthy' | 'corrupt-metadata' | 'orphan';
+/**
+ * An orphan younger than this may still be a clone in progress: admin purge refuses it and the
+ * worker does not quarantine it. Corrupt-metadata dirs are exempt.
+ */
+export declare const ORPHAN_YOUTH_THRESHOLD_MS: number;
 export interface BranchHealthEntry {
     dirName: string;
     kind: BranchHealthKind;

package/dist/branch-health.js

@@ -5,16 +5,21 @@ import { ContentIdIndex } from './content-id-index.js';
 import { sanitizeBranchName } from './paths/branch-name.js';
 import { getErrorMessage, isNodeError, isNotFoundError } from './utils/error.js';
 import { isRebaseInProgress } from './utils/git.js';
+import { branchProvisioningLockName } from './utils/provisioning-lock.js';
 /**
- * The provisioning lock marker's path for a branch directory, matching what
- * `branch-workspace.ts`'s `ensureGitWorkspace()` passes exactly.
+ * An orphan younger than this may still be a clone in progress: admin purge refuses it and the
+ * worker does not quarantine it. Corrupt-metadata dirs are exempt.
+ */
+export const ORPHAN_YOUTH_THRESHOLD_MS = 15 * 60_000;
+/**
+ * The provisioning lock marker's path for a branch directory.
  *
  * `acquireProvisioningLock` passes the name as `lockfilePath`, overriding
  * proper-lockfile's default `${target}.lock`, so the marker (a mkdir-based
  * directory) sits at exactly this path — no extra `.lock` suffix.
  */
 function provisioningLockPath(baseRoot, dirName) {
-    return path.join(baseRoot, `.${dirName}.init.lock`);
+    return path.join(baseRoot, branchProvisioningLockName(dirName));
 }
 /** Stat the provisioning lock marker, if present. Never throws. */
 async function readProvisioningLock(baseRoot, dirName) {

package/dist/branch-metadata.d.ts

@@ -63,16 +63,16 @@ export declare class BranchMetadataFileManager {
      * entry with no clone behind it. It runs BEFORE the lock stack so a doomed
      * save fails fast instead of paying for a lock.
      *
-     * Accepted residual window: a save that passes the check can still race a
-     * `rm` that starts moments later and is mid-flight when the write lands.
-     * Closing that needs a tombstone OUTSIDE the tree being removed, and the
-     * lockfile taken next lives INSIDE `branchRoot`, so it can promise no more
-     * than "the directory existed a moment ago".
+     * A save that passes the check just before a delete still cannot write: the
+     * delete renames the tree away under the same lockfile, and that lockfile
+     * creates only its own directory (`withOccFileLock`), so the save fails there.
      */
     save(incoming: BranchMetadataUpdate): Promise<BranchMetadataFile>;
     /** Invalidate the registry cache so the next list() regenerates. */
     private invalidateRegistry;
 }
+/** The branch.json a brand-new branch starts with: {@link mergeBranchMetadata} over nothing. */
+export declare function buildInitialBranchMetadata(incoming: BranchMetadataUpdate, now?: string): BranchMetadataFile;
 /**
  * Fields save() accepts. `createdBy` applies on creation only and is ignored
  * once metadata exists; createdAt/updatedAt are managed here, not by callers.

package/dist/branch-metadata.js

@@ -101,11 +101,9 @@ export class BranchMetadataFileManager {
      * entry with no clone behind it. It runs BEFORE the lock stack so a doomed
      * save fails fast instead of paying for a lock.
      *
-     * Accepted residual window: a save that passes the check can still race a
-     * `rm` that starts moments later and is mid-flight when the write lands.
-     * Closing that needs a tombstone OUTSIDE the tree being removed, and the
-     * lockfile taken next lives INSIDE `branchRoot`, so it can promise no more
-     * than "the directory existed a moment ago".
+     * A save that passes the check just before a delete still cannot write: the
+     * delete renames the tree away under the same lockfile, and that lockfile
+     * creates only its own directory (`withOccFileLock`), so the save fails there.
      */
     async save(incoming) {
         try {
@@ -121,37 +119,7 @@ export class BranchMetadataFileManager {
         try {
             saved = await withLock(this.filePath, () => withOccFileLock(this.filePath, () => withOccRetry(async () => {
                 const { meta: existing, version } = await this.load();
-                const now = new Date().toISOString();
-                const defaults = {
-                    name: 'unknown',
-                    status: 'editing',
-                    access: {},
-                    createdBy: 'unknown',
-                    createdAt: now,
-                    updatedAt: now,
-                };
-                const merged = {
-                    schemaVersion: CURRENT_SCHEMA_VERSION,
-                    version: version ?? 0,
-                    branch: {
-                        ...defaults,
-                        ...existing?.branch,
-                        ...incoming.branch,
-                        access: {
-                            ...existing?.branch?.access,
-                            ...incoming.branch?.access,
-                        },
-                        // Immutable after creation
-                        createdBy: existing?.branch.createdBy ?? incoming.branch?.createdBy ?? defaults.createdBy,
-                        createdAt: existing?.branch.createdAt ?? defaults.createdAt,
-                        // Fork point is recorded once at creation; later saves must not move it
-                        baseBranch: existing?.branch.baseBranch ?? incoming.branch?.baseBranch,
-                        // Always stamped fresh; the spreads above would otherwise let
-                        // the creation-time value win forever, freezing the timestamp
-                        // the editor's Branches panel sorts and displays by
-                        updatedAt: now,
-                    },
-                };
+                const merged = mergeBranchMetadata(existing, version, incoming);
                 const written = await this.write(merged, version);
                 merged.version = written.version;
                 merged.writeId = written.writeId;
@@ -178,6 +146,46 @@ export class BranchMetadataFileManager {
         await registry.invalidate();
     }
 }
+/**
+ * The branch.json that {@link BranchMetadataFileManager.save} writes for `incoming` over
+ * `existing`. Pure, so a staged workspace's first branch.json (branch-provisioning.ts) is built by
+ * the same rules as a save and the two cannot drift.
+ */
+function mergeBranchMetadata(existing, version, incoming, now = new Date().toISOString()) {
+    const defaults = {
+        name: 'unknown',
+        status: 'editing',
+        access: {},
+        createdBy: 'unknown',
+        createdAt: now,
+        updatedAt: now,
+    };
+    return {
+        schemaVersion: CURRENT_SCHEMA_VERSION,
+        version: version ?? 0,
+        branch: {
+            ...defaults,
+            ...existing?.branch,
+            ...incoming.branch,
+            access: {
+                ...existing?.branch?.access,
+                ...incoming.branch?.access,
+            },
+            // Immutable after creation
+            createdBy: existing?.branch.createdBy ?? incoming.branch?.createdBy ?? defaults.createdBy,
+            createdAt: existing?.branch.createdAt ?? defaults.createdAt,
+            // Fork point is recorded once at creation; later saves must not move it
+            baseBranch: existing?.branch.baseBranch ?? incoming.branch?.baseBranch,
+            // Always stamped fresh; the spreads above would otherwise let the creation-time value win
+            // forever, freezing the timestamp the editor's Branches panel sorts and displays by
+            updatedAt: now,
+        },
+    };
+}
+/** The branch.json a brand-new branch starts with: {@link mergeBranchMetadata} over nothing. */
+export function buildInitialBranchMetadata(incoming, now) {
+    return mergeBranchMetadata(null, null, incoming, now);
+}
 /**
  * The metadata update for archiving a branch whose PR merged. Shared by the
  * worker's merge-poll (CmsWorker.pollMergeState) and the manual markAsMerged

package/dist/branch-provisioning.d.ts

@@ -0,0 +1,167 @@
+import { type BranchMetadataFile } from './branch-metadata-file.js';
+import { type CloneRepoOptions } from './git-manager.js';
+import type { ProvisionLog } from './utils/provision-log.js';
+/** How long residue must have been untouched before a create request moves it aside. */
+export declare const CREATE_RESIDUE_MIN_QUIET_MS = 60000;
+/**
+ * Retriable: another process is setting this branch up, or what is at its path is too recently
+ * touched (or under an admin repair) to judge. Callers answer 503.
+ */
+export declare class BranchProvisioningBusyError extends Error {
+    readonly dirName: string;
+    constructor(dirName: string, message?: string);
+}
+/** The branch's path holds a git repository this deployment did not create (prod only). */
+export declare class BranchDirOccupiedError extends Error {
+    readonly dirName: string;
+    constructor(dirName: string);
+}
+/** `YYYYMMDDTHHMMSSZ` in UTC, with no colons. */
+export declare function formatDirStamp(date: Date): string;
+/**
+ * The date in a name ending `-{STAMP}`, or null. Leftovers are aged by this alone, never by
+ * mtime: `rename()` keeps a directory's mtime, so a months-old residue would look old the
+ * moment it was moved.
+ */
+export declare function parseDirStamp(name: string): Date | null;
+/**
+ * A branch directory name cut to a bounded, still-unique form: branch names run to 250 chars.
+ * @internal Exported for tests.
+ */
+export declare function shortDirName(dirName: string): string;
+/** Where a branch directory goes the moment it is deleted, before its `rm`. */
+export declare const deletingDirName: (dirName: string, now?: Date) => string;
+/** The settings workspace's staging and trash siblings, under the workspace root. */
+export declare const settingsStagingDirName: (now?: Date) => string;
+export declare const settingsTrashDirName: (now?: Date) => string;
+interface ResidueSignature {
+    hasGitDir: boolean;
+    configLock: boolean;
+    hasIndex: boolean;
+}
+/**
+ * What occupies a branch's final path.
+ *
+ * - `live` / `corrupt`: branch.json is there. Never touched by provisioning.
+ * - `protected`: an admin repair-metadata is mid-way (`branch.json.corrupt-*` with no
+ *   branch.json), or branch.json vanished between the listing and the read. Left alone.
+ * - `residue`: nothing this deployment could still be using — no `.git`, or a `.git` whose config
+ *   is missing or unreadable (an interrupted clone), or one whose remote is this deployment's own
+ *   (an interrupted clone or delete).
+ * - `foreign`: any other repository, such as a dev CLI-sync workspace, which has no remote.
+ */
+export type FinalDirState = {
+    kind: 'vacant';
+} | {
+    kind: 'live';
+} | {
+    kind: 'corrupt';
+} | {
+    kind: 'protected';
+} | {
+    kind: 'foreign';
+} | {
+    kind: 'residue';
+    signature: ResidueSignature;
+};
+/** Classify what is at `dirPath`; see {@link FinalDirState}. */
+export declare function classifyFinalDir(dirPath: string, expectedRemoteUrl: string): Promise<FinalDirState>;
+/**
+ * Milliseconds since anything was last created or removed in the directory, its `.git` or its
+ * `.canopy-meta`. A clone killed inside `git config` touched `.git` when it made `config.lock`.
+ */
+export declare function quietAgeMs(dirPath: string, now?: number): Promise<number>;
+type KeptReason = 'live' | 'corrupt' | 'protected' | 'foreign' | 'too-young' | 'replaced';
+export type QuarantineResult = {
+    kind: 'quarantined';
+    trashName: string;
+} | {
+    kind: 'vacant';
+} | {
+    kind: 'kept';
+    reason: KeptReason;
+};
+export interface QuarantineOptions {
+    minQuietMs: number;
+    expectedRemoteUrl: string;
+    now?: number;
+}
+/**
+ * Move residue at `baseRoot/dirName` to `.trash-*`. The caller MUST hold the branch's
+ * provisioning lock: admin repair-metadata holds it while it legitimately leaves a directory
+ * with real edits and no branch.json.
+ *
+ * Move-then-verify: the name is renamed aside first and only what arrived at the new name is
+ * judged — the same inode the old name showed, still residue, quiet for `minQuietMs` — because
+ * a look through the old name can come from a stale NFS dentry for a directory another host has
+ * since replaced with a live clone. Anything that fails a check, or cannot be checked, is
+ * renamed straight back: the sweep would trash a `.repair-*` without branch.json.
+ */
+export declare function quarantineResidueAt(baseRoot: string, dirName: string, options: QuarantineOptions): Promise<QuarantineResult>;
+export interface StageBranchOptions {
+    baseRoot: string;
+    dirName: string;
+    branchName: string;
+    baseBranch: string;
+    remoteUrl: string;
+    clone: Pick<CloneRepoOptions, 'remoteName' | 'config'>;
+    gitExcludePattern: string;
+    metadata: BranchMetadataFile;
+    provisionLog: ProvisionLog;
+    /** The sparse-checkout cone (branch-sparse.ts), set before the checkout; none for a full clone. */
+    sparseCone?: readonly string[] | null;
+}
+export type StageResult = {
+    kind: 'staged';
+    stagingPath: string;
+    meta: BranchMetadataFile;
+} | {
+    kind: 'exists';
+};
+/** Remove a staging or deleted directory, leaving it to the worker's sweep on failure. */
+export declare function removeLeftoverDir(dirPath: string): Promise<void>;
+/**
+ * Build a complete branch workspace, branch.json included, in a staging sibling of the final
+ * path. Takes no lock. Returns `exists` without checking out when a competitor published first.
+ * A failure removes the staging directory; a kill leaves it for the worker.
+ */
+export declare function stageBranchWorkspace(options: StageBranchOptions): Promise<StageResult>;
+/**
+ * The branch's provisioning lock with a bounded wait; contention is
+ * {@link BranchProvisioningBusyError}.
+ */
+export declare function lockBranchName(baseRoot: string, dirName: string): Promise<() => Promise<void>>;
+/** What blocks a refused publish rename, as {@link publishStaging} sees it. */
+export type BlockingKind = 'live' | 'protected' | 'residue';
+export interface PublishOptions {
+    baseRoot: string;
+    dirName: string;
+    stagingPath: string;
+    /** branch.json's `writeId` in the staged workspace: proof the rename was ours. */
+    writeId: string | undefined;
+    expectedRemoteUrl: string;
+    /** Test seam replacing the look at what blocks a refused rename. */
+    inspectBlocked?: (finalPath: string) => Promise<BlockingKind>;
+}
+/**
+ * Publish a staged workspace at its final path, under the branch's provisioning lock.
+ *
+ * A refused rename is inspected: branch.json there means another request won (`exists`);
+ * residue is quarantined and the rename retried once. ENOENT can be an NFS retransmission of a
+ * rename that already landed, so it counts as published when the final branch.json carries our
+ * `writeId`. The caller removes the staging directory on any outcome but `published`.
+ */
+export declare function publishStaging(options: PublishOptions): Promise<'published' | 'exists'>;
+export interface LeftoverAction {
+    name: string;
+    action: 'removed' | 'restored' | 'trashed' | 'failed';
+    detail?: string;
+}
+/**
+ * Clear what killed processes left beside the branch directories (`baseRoot`) and the settings
+ * workspace (`workspaceRoot`): stale `.prov-*` builds, `.deleting-*` directories whose `rm` never
+ * finished, `.repair-*` from an interrupted quarantine, and expired settings trash. Ages come
+ * from the stamp in each name.
+ */
+export declare function sweepProvisioningLeftovers(baseRoot: string, workspaceRoot: string, now?: number): Promise<LeftoverAction[]>;
+export {};