canopycms 0.0.67 → 0.0.68-int.100

package/dist/api/branch-review.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { BranchResponse } from './branch.js';
+import { type BranchListItemResponse } from './branch.js';
 export declare const requestChanges: import("./route-builder.js").RouteDefinition<z.ZodObject<{
     branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
 }, "strip", z.ZodTypeAny, {
@@ -10,7 +10,7 @@ export declare const requestChanges: import("./route-builder.js").RouteDefinitio
     branch: string & {
         readonly __brand: "BranchName";
     };
-}>, undefined, BranchResponse>;
+}>, undefined, BranchListItemResponse>;
 export declare const approveBranch: import("./route-builder.js").RouteDefinition<z.ZodObject<{
     branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
 }, "strip", z.ZodTypeAny, {
@@ -21,4 +21,4 @@ export declare const approveBranch: import("./route-builder.js").RouteDefinition
     branch: string & {
         readonly __brand: "BranchName";
     };
-}>, undefined, BranchResponse>;
+}>, undefined, BranchListItemResponse>;

package/dist/api/branch-review.js

@@ -1,4 +1,5 @@
 import { branchParamSchema } from './validators.js';
+import { toBranchListItem } from './branch.js';
 import { getBranchMetadataFileManager } from '../branch-metadata.js';
 import { defineEndpoint } from './route-builder.js';
 import { syncConvertToDraft } from './github-sync.js';
@@ -17,9 +18,13 @@ const requestChangesHandler = async (gc, ctx, _req, _params) => {
         branch: { name: branchContext.branch.name, status: 'editing' },
     });
     // TODO: Optionally record comment in .canopycms/comments.json when comment system is implemented
-    return { ok: true, status: 200, data: { branch: updated.branch } };
+    return {
+        ok: true,
+        status: 200,
+        data: { branch: toBranchListItem(ctx.services.config, updated.branch) },
+    };
 };
-const approveBranchHandler = async (gc, _ctx, _req, _params) => {
+const approveBranchHandler = async (gc, ctx, _req, _params) => {
     const { branchContext } = gc;
     if (branchContext.branch.status !== 'submitted') {
         return {
@@ -33,7 +38,11 @@ const approveBranchHandler = async (gc, _ctx, _req, _params) => {
         branch: { name: branchContext.branch.name, status: 'approved' },
     });
     // TODO: Optionally call githubService.approvePullRequest() when GitHub integration is needed
-    return { ok: true, status: 200, data: { branch: updated.branch } };
+    return {
+        ok: true,
+        status: 200,
+        data: { branch: toBranchListItem(ctx.services.config, updated.branch) },
+    };
 };
 export const requestChanges = defineEndpoint({
     namespace: 'workflow',
@@ -43,7 +52,7 @@ export const requestChanges = defineEndpoint({
     params: branchParamSchema,
     // body/bodyType removed: comment field was declared but never stored.
     // Re-add when comment storage is implemented (see TODO in handler).
-    responseType: 'BranchResponse',
+    responseType: 'BranchListItemResponse',
     response: {},
     defaultMockData: {
         branch: {
@@ -64,7 +73,7 @@ export const approveBranch = defineEndpoint({
     method: 'POST',
     path: '/:branch/approve',
     params: branchParamSchema,
-    responseType: 'BranchResponse',
+    responseType: 'BranchListItemResponse',
     response: {},
     defaultMockData: {
         branch: {

package/dist/api/branch-status.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { BranchResponse } from './branch.js';
+import { type BranchListItemResponse, type BranchResponse } from './branch.js';
 export type { BranchMergeResponse } from './branch-merge.js';
 export declare const WORKFLOW_ROUTES: {
     readonly getStatus: import("./route-builder.js").RouteDefinition<z.ZodObject<{
@@ -23,7 +23,7 @@ export declare const WORKFLOW_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-    }>, undefined, BranchResponse>;
+    }>, undefined, BranchListItemResponse>;
     readonly withdraw: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {
@@ -34,7 +34,7 @@ export declare const WORKFLOW_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-    }>, undefined, BranchResponse>;
+    }>, undefined, BranchListItemResponse>;
     readonly requestChanges: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {
@@ -45,7 +45,7 @@ export declare const WORKFLOW_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-    }>, undefined, BranchResponse>;
+    }>, undefined, BranchListItemResponse>;
     readonly approve: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {
@@ -56,7 +56,7 @@ export declare const WORKFLOW_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-    }>, undefined, BranchResponse>;
+    }>, undefined, BranchListItemResponse>;
     readonly markMerged: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {

package/dist/api/branch-status.js

@@ -1,4 +1,5 @@
 import { branchParamSchema } from './validators.js';
+import { toBranchListItem } from './branch.js';
 import { getBranchMetadataFileManager } from '../branch-metadata.js';
 import { withdrawBranch } from './branch-withdraw.js';
 import { requestChanges, approveBranch } from './branch-review.js';
@@ -8,6 +9,8 @@ import { canPerformWorkflowAction, getBranchProtection } from '../authorization/
 import { syncSubmitPr } from './github-sync.js';
 import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../utils/error.js';
 import { isNonFastForwardRejection } from '../utils/git.js';
+import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
+import { submissionEditorFromUser } from '../submission-attribution.js';
 const getBranchStatusHandler = async (gc, _ctx, _req, _params) => {
     const { branchContext } = gc;
     return { ok: true, status: 200, data: { branch: branchContext.branch } };
@@ -49,10 +52,24 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         };
     }
     // Commit and push changes
+    const submitter = submissionEditorFromUser(req.user);
+    let changedPaths;
     try {
-        await ctx.services.submitBranch({ context: branchContext });
+        ;
+        ({ changedPaths } = await ctx.services.submitBranch({ context: branchContext, submitter }));
     }
     catch (err) {
+        // Retriable either way: a resubmit commits nothing new and pushes only
+        // what has not reached the remote.
+        if (err instanceof ContentWriteLockBusyError) {
+            return {
+                ok: false,
+                status: 409,
+                error: err.outcome === 'not-run'
+                    ? `Could not submit "${branchContext.branch.name}" right now: it is being synced with its base branch, or a save is in flight. Nothing was submitted; try again in a moment.`
+                    : `"${branchContext.branch.name}" was being synced while it was submitted, so the submit may not have completed. Try submitting again.`,
+            };
+        }
         const message = getErrorMessage(err);
         // Full path detail (including branchRoot, an absolute path) to server logs
         // only; the client only ever sees the sanitized form (API-H2). Credentials
@@ -62,8 +79,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         // A non-fast-forward rejection means this branch and the deployment's
         // local repository have diverged. Retrying the identical push can never
         // succeed (see isNonFastForwardRejection), so surface 409 instead of the
-        // generic 500 below. Everything else (network, auth, lock contention)
-        // keeps the existing 500 path unchanged.
+        // generic 500 below. Everything else (network, auth) keeps the 500 path.
         //
         // This push targets the deployment's OWN local origin (remote.git), not
         // GitHub, so the message deliberately states only the observable fact and
@@ -91,7 +107,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
         };
     }
     // Create or update PR (sync via githubService, or async via task queue)
-    const prResult = await syncSubmitPr(ctx, branchContext);
+    const prResult = await syncSubmitPr(ctx, branchContext, { submitter, changedPaths });
     // Update metadata with status and PR info
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
     const updated = await meta.save({
@@ -107,7 +123,11 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
             rebaseFailure: undefined,
         },
     });
-    return { ok: true, status: 200, data: { branch: updated.branch } };
+    return {
+        ok: true,
+        status: 200,
+        data: { branch: toBranchListItem(ctx.services.config, updated.branch) },
+    };
 };
 const getBranchStatus = defineEndpoint({
     namespace: 'workflow',
@@ -136,7 +156,7 @@ const submitBranchForMerge = defineEndpoint({
     method: 'POST',
     path: '/:branch/submit',
     params: branchParamSchema,
-    responseType: 'BranchResponse',
+    responseType: 'BranchListItemResponse',
     response: {},
     defaultMockData: {
         branch: {

package/dist/api/branch-withdraw.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { BranchResponse } from './branch.js';
+import { type BranchListItemResponse } from './branch.js';
 /**
  * Withdraw a submitted branch, converting the PR to draft and unlocking editing
  *
@@ -19,4 +19,4 @@ export declare const withdrawBranch: import("./route-builder.js").RouteDefinitio
     branch: string & {
         readonly __brand: "BranchName";
     };
-}>, undefined, BranchResponse>;
+}>, undefined, BranchListItemResponse>;

package/dist/api/branch-withdraw.js

@@ -1,4 +1,5 @@
 import { branchParamSchema } from './validators.js';
+import { toBranchListItem } from './branch.js';
 import { getBranchMetadataFileManager } from '../branch-metadata.js';
 import { defineEndpoint } from './route-builder.js';
 import { canPerformWorkflowAction, getBranchProtection } from '../authorization/index.js';
@@ -60,7 +61,11 @@ const withdrawBranchHandler = async (gc, ctx, req, _params) => {
                 : {}),
         },
     });
-    return { ok: true, status: 200, data: { branch: updated.branch } };
+    return {
+        ok: true,
+        status: 200,
+        data: { branch: toBranchListItem(ctx.services.config, updated.branch) },
+    };
 };
 /**
  * Withdraw a submitted branch, converting the PR to draft and unlocking editing
@@ -77,7 +82,7 @@ export const withdrawBranch = defineEndpoint({
     method: 'POST',
     path: '/:branch/withdraw',
     params: branchParamSchema,
-    responseType: 'BranchResponse',
+    responseType: 'BranchListItemResponse',
     response: {},
     defaultMockData: {
         branch: {

package/dist/api/branch.d.ts

@@ -45,6 +45,14 @@ export interface BranchListItem extends BranchMetadata {
      */
     submitBlocked?: boolean;
 }
+/**
+ * Response type for branch creation and the workflow transitions. Carries the
+ * list-item shape (server-computed flags included) so the editor can show the
+ * result without waiting for a listing that may lag behind it.
+ */
+export type BranchListItemResponse = ApiResponse<{
+    branch: BranchListItem;
+}>;
 /** Response type for listing branches */
 export type BranchListResponse = ApiResponse<{
     branches: BranchListItem[];
@@ -129,8 +137,13 @@ export interface CreateBranchBody {
     description?: string;
     access?: BranchMetadata['access'];
 }
+/**
+ * Attach server-computed protected-base-branch flags to a branch. Reads config
+ * per call so dev-mode refreshActiveBranch() updates are reflected.
+ */
+export declare const toBranchListItem: (config: ApiContext["services"]["config"], branch: BranchMetadata) => BranchListItem;
 /** @internal Exported for tests. */
-export declare const createBranchHandler: (ctx: ApiContext, req: ApiRequest, body: z.infer<typeof createBranchBodySchema>) => Promise<BranchResponse>;
+export declare const createBranchHandler: (ctx: ApiContext, req: ApiRequest, body: z.infer<typeof createBranchBodySchema>) => Promise<BranchListItemResponse>;
 /** @internal Exported for tests. */
 export declare const listBranchesHandler: (ctx: ApiContext, req: ApiRequest) => Promise<BranchListResponse>;
 /** @internal Exported for tests. */
@@ -187,7 +200,7 @@ export declare const BRANCH_ROUTES: {
             allowedUsers?: string[] | undefined;
             allowedGroups?: string[] | undefined;
         } | undefined;
-    }>, BranchResponse>;
+    }>, BranchListItemResponse>;
     readonly delete: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {

package/dist/api/branch.js

@@ -2,15 +2,17 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { z } from 'zod';
 import { BranchWorkspaceManager } from '../branch-workspace.js';
+import { BranchDirOccupiedError, BranchProvisioningBusyError, deletingDirName, removeLeftoverDir, } from '../branch-provisioning.js';
 import { getBranchMetadataFileManager } from '../branch-metadata.js';
 import { withOccFileLock } from '../utils/occ-json-write.js';
+import { isCreatorsRecentBranch } from './branch-create-window.js';
 import { defineEndpoint } from './route-builder.js';
 import { createDebugLogger } from '../utils/debug.js';
 import { clientOperatingStrategy } from '../operating-mode/index.js';
 import { isNotFoundError, getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
 import { filePathExists } from '../utils/fs.js';
 import { isNetworkRemoteUrl } from '../utils/git.js';
-import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, } from '../paths/index.js';
+import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRANCH_NAMES, isSettingsBranchName, } from '../paths/index.js';
 import { GitManager } from '../git-manager.js';
 import { branchNameSchema, branchParamSchema } from './validators.js';
 const log = createDebugLogger({ prefix: 'BranchAPI' });
@@ -87,6 +89,20 @@ const resolveReadOnlyMirrorPath = (ctx, strategy) => {
         process.env[remoteUrlConfig.envVarName] ??
         remoteUrlConfig.autoDetectRemotePath);
 };
+/**
+ * Attach server-computed protected-base-branch flags to a branch. Reads config
+ * per call so dev-mode refreshActiveBranch() updates are reflected.
+ */
+export const toBranchListItem = (config, branch) => {
+    const protection = getBranchWriteProtection(config, branch.name, branch.baseBranch, branch.status);
+    return {
+        ...branch,
+        isProtected: protection.isProtected,
+        readOnly: protection.readOnly,
+        writeBlocked: protection.writeBlocked,
+        submitBlocked: protection.submitBlockedIncludingStatus,
+    };
+};
 /** @internal Exported for tests. */
 export const createBranchHandler = async (ctx, req, body) => {
     return log.timed('api', 'createBranch', async () => {
@@ -95,15 +111,12 @@ export const createBranchHandler = async (ctx, req, body) => {
             branchName,
             userId: req.user.userId,
         });
-        // Scope note: the collision guards below (settings-branch collision,
-        // reserved canopycms-settings- prefix, and the remote-mirror check
-        // further down) apply ONLY to this user-facing creation path.
-        // http/handler.ts's auto-create (base/active/settings branches) and
-        // branch-workspace.ts's loadOrCreateBranchContext (reached from run-time
-        // content reads and the AI pipeline; build-time reads return the checkout
-        // and never provision) provision system/known branch names, not
-        // user-chosen ones, and deliberately stay uncovered -- intentional, not
-        // an oversight.
+        // Scope note: the remote-mirror check further down applies ONLY to this
+        // user-facing creation path; http/handler.ts's auto-create (base/active
+        // branches) and loadOrCreateBranchContext provision known names. The two
+        // settings-branch checks below give this path a specific 400; every
+        // provisioning path, this one included, also refuses a settings branch in
+        // BranchWorkspaceManager.openOrCreateBranch.
         // Prevent git branch name collision with the settings branch. Settings
         // live in a separate directory but share the same git remote, and
         // openOrCreateBranch (branch-workspace.ts) uses the SANITIZED name as the
@@ -154,13 +167,9 @@ export const createBranchHandler = async (ctx, req, body) => {
                 error: `Branch name "${branchName}" is reserved: it collides with the /${branchName} API route namespace`,
             };
         }
-        // Reject the base branch name outright. openOrCreateBranch's save() (see
-        // branch-metadata.ts) field-merges the caller-supplied `access` over an
-        // EXISTING branch's metadata rather than replacing it, so a request
-        // naming the base branch would let the caller inject themselves into the
-        // protected base branch's ACL (gaining e.g. withdraw rights via the
-        // allowed_by_acl path). No recorded fork point exists yet for a
-        // not-yet-created branch, so this checks config protection only.
+        // Reject the base branch name outright, even before the base branch is
+        // provisioned. No recorded fork point exists yet for a not-yet-created
+        // branch, so this checks config protection only.
         const { isProtected } = getBranchProtection(ctx.services.config, branchName);
         if (isProtected) {
             return {
@@ -169,14 +178,10 @@ export const createBranchHandler = async (ctx, req, body) => {
                 error: 'Cannot create a branch with the base branch name',
             };
         }
-        // Reject a name collision with ANY existing branch for the same
-        // field-merge reason: creating over an existing branch name would let
-        // the caller's `access` ACL overwrite that branch's real ACL instead of
-        // creating a new, separate branch. Comparison uses the sanitized name
-        // since that's what's persisted in branch.json (see
-        // BranchWorkspaceManager.openOrCreateBranch). System branches
-        // auto-provisioned via http/handler.ts's getBranchContext don't go
-        // through this handler, so rejecting collisions here doesn't affect them.
+        // A name collision with ANY existing branch answers before a clone is paid
+        // for. Provisioning never merges into an existing branch either: it reports
+        // `exists`, mapped the same way below. Compared sanitized, the form
+        // branch.json records.
         if (!ctx.services.registry) {
             return {
                 ok: false,
@@ -186,11 +191,7 @@ export const createBranchHandler = async (ctx, req, body) => {
         }
         const existingBranch = await ctx.services.registry.get(sanitizeBranchName(branchName));
         if (existingBranch) {
-            return {
-                ok: false,
-                status: 409,
-                error: 'A branch with this name already exists',
-            };
+            return existingBranchResponse(ctx, req, existingBranch);
         }
         // L2: create-time collision check against this deployment's local
         // GitHub mirror (`remote.git`). The CMS Lambda has no internet access
@@ -315,19 +316,47 @@ export const createBranchHandler = async (ctx, req, body) => {
             };
         }
         const manager = new BranchWorkspaceManager(ctx.services.config);
-        const operatingMode = ctx.services.config.mode;
-        const context = await manager.openOrCreateBranch({
-            branchName,
-            mode: operatingMode,
-            createdBy: req.user.userId,
-            title: body.title,
-            description: body.description,
-            access: body.access,
-        });
-        log.debug('api', 'Branch created', { branchName: context.branch.name });
-        return { ok: true, status: 200, data: { branch: context.branch } };
+        let outcome;
+        try {
+            outcome = await manager.provisionBranch({
+                branchName,
+                mode: ctx.services.config.mode,
+                createdBy: req.user.userId,
+                title: body.title,
+                description: body.description,
+                access: body.access,
+            });
+        }
+        catch (err) {
+            if (err instanceof BranchProvisioningBusyError) {
+                return { ok: false, status: 503, error: err.message };
+            }
+            if (err instanceof BranchDirOccupiedError) {
+                return { ok: false, status: 409, error: err.message };
+            }
+            throw err;
+        }
+        if (outcome.kind === 'exists')
+            return existingBranchResponse(ctx, req, outcome.context);
+        log.debug('api', 'Branch created', { branchName: outcome.context.branch.name });
+        return {
+            ok: true,
+            status: 200,
+            data: { branch: toBranchListItem(ctx.services.config, outcome.context.branch) },
+        };
     });
 };
+/** A create that names an existing branch: 409, unless it is that creator's recent retry. */
+const existingBranchResponse = (ctx, req, existing) => {
+    if (isCreatorsRecentBranch(existing.branch, req.user.userId)) {
+        return {
+            ok: true,
+            status: 200,
+            data: { branch: toBranchListItem(ctx.services.config, existing.branch) },
+        };
+    }
+    return { ok: false, status: 409, error: 'A branch with this name already exists' };
+};
 /** @internal Exported for tests. */
 export const listBranchesHandler = async (ctx, req) => {
     if (!ctx.services.registry) {
@@ -337,7 +366,10 @@ export const listBranchesHandler = async (ctx, req) => {
             error: 'Branch registry not initialized — ensure the workspace has been initialized',
         };
     }
-    const allBranches = await ctx.services.registry.list();
+    // A settings-branch workspace is never resolvable as a content branch (see
+    // http/handler.ts), so one left on disk is hidden rather than listed unopenable.
+    const settingsBranch = operatingStrategy(ctx.services.config.mode).getSettingsBranchName(ctx.services.config);
+    const allBranches = (await ctx.services.registry.list()).filter((context) => !isSettingsBranchName(context.branch.name, settingsBranch));
     // The branch the editor should open when none is pinned via URL/config.
     // Read per-request so dev-mode refreshActiveBranch() updates are reflected.
     // Sanitized: dev mode detects the RAW git HEAD name (e.g. 'claude/foo'),
@@ -345,24 +377,15 @@ export const listBranchesHandler = async (ctx, req) => {
     // editor matches defaultBranch against registry names, so return the form
     // that can actually be found there.
     const defaultBranch = sanitizeBranchName(ctx.services.config.defaultActiveBranch ?? ctx.services.config.defaultBaseBranch ?? 'main');
-    // Attach server-computed protected-base-branch flags; read config per-request
-    // so dev-mode refreshActiveBranch() updates are reflected here too.
-    const toListItem = (context) => {
-        const protection = getBranchWriteProtection(ctx.services.config, context.branch.name, context.branch.baseBranch, context.branch.status);
-        return {
-            ...context.branch,
-            isProtected: protection.isProtected,
-            readOnly: protection.readOnly,
-            writeBlocked: protection.writeBlocked,
-            submitBlocked: protection.submitBlockedIncludingStatus,
-        };
-    };
     // Admins and Reviewers see all branches
     if (isPrivileged(req.user.groups)) {
         return {
             ok: true,
             status: 200,
-            data: { branches: allBranches.map(toListItem), defaultBranch },
+            data: {
+                branches: allBranches.map((context) => toBranchListItem(ctx.services.config, context.branch)),
+                defaultBranch,
+            },
         };
     }
     // Regular users only see branches they created or have explicit access to
@@ -390,7 +413,10 @@ export const listBranchesHandler = async (ctx, req) => {
     return {
         ok: true,
         status: 200,
-        data: { branches: visibleBranches.map(toListItem), defaultBranch },
+        data: {
+            branches: visibleBranches.map((context) => toBranchListItem(ctx.services.config, context.branch)),
+            defaultBranch,
+        },
     };
 };
 /** @internal Exported for tests. */
@@ -456,48 +482,39 @@ export const deleteBranchHandler = async (ctx, req, params) => {
             error: 'Cannot delete branch with open pull request',
         };
     }
-    // Delete branch metadata file so it disappears from registry scans.
-    // Hold the same server-enforced lockfile branch-metadata saves hold
-    // (see utils/occ-json-write.ts): an unguarded unlink racing a concurrent
-    // save() would let the save's create path resurrect a phantom branch.json
-    // inside a deleted branch, which the registry's next scan would list as a
-    // live branch with no clone. The directory removal happens inside the
-    // same hold so a racing save cannot slip between unlink and rm either.
+    // The branch directory leaves its name by one rename, under the same
+    // server-enforced lockfile branch-metadata saves hold (see
+    // utils/occ-json-write.ts), so a save() that reaches that lock after the
+    // rename fails rather than recreating the tree, and a process killed during
+    // the `rm` leaves
+    // only a `.deleting-*` directory the worker sweeps, never residue under a
+    // name that may be created again.
     const metadataFile = path.join(branchContext.branchRoot, '.canopy-meta', 'branch.json');
     let cleanupWarning;
+    let deletingPath;
     try {
         await withOccFileLock(metadataFile, async () => {
+            if (branchContext.branchRoot === branchContext.baseRoot) {
+                await fs.unlink(metadataFile).catch((err) => {
+                    if (!isNotFoundError(err))
+                        throw err;
+                });
+                return;
+            }
+            const target = path.join(branchContext.baseRoot, deletingDirName(path.basename(branchContext.branchRoot)));
             try {
-                await fs.unlink(metadataFile);
+                await fs.rename(branchContext.branchRoot, target);
+                deletingPath = target;
             }
             catch (err) {
-                if (!isNotFoundError(err)) {
-                    console.error(`CanopyCMS: Failed to delete branch metadata for ${branchName}:`, getErrorMessage(err));
-                }
-            }
-            // In multi-branch modes, also delete the entire branch directory.
-            // Retry transient EFS/NFS errors (ENOTEMPTY from a concurrent writer,
-            // EBUSY) a few times before giving up -- rm's failure must never be
-            // swallowed: metadata is gone either way (the branch is logically
-            // deleted and will no longer appear in listings), but silently
-            // succeeding here would leave a full orphan clone on disk with
-            // nothing in the API surfacing its existence.
-            if (branchContext.branchRoot !== branchContext.baseRoot) {
-                try {
-                    await fs.rm(branchContext.branchRoot, {
-                        recursive: true,
-                        force: true,
-                        maxRetries: 3,
-                        retryDelay: 100,
-                    });
-                }
-                catch (err) {
-                    // sanitizeErrorMessage: this string goes back to the browser in the
-                    // delete response (API-H2 — no absolute EFS paths to clients);
-                    // the console line below keeps the raw detail for server logs.
-                    cleanupWarning = `Failed to fully remove branch directory: ${sanitizeErrorMessage(getErrorMessage(err))}`;
-                    console.error(`CanopyCMS: Failed to delete branch directory for ${branchName}:`, getErrorMessage(err));
-                }
+                if (isNotFoundError(err))
+                    return;
+                // Still deleted logically: without branch.json the branch is unlisted,
+                // and the worker quarantines what is left.
+                await fs.unlink(metadataFile).catch(() => { });
+                // [REDACT] Returned to the browser; the console line keeps the path.
+                cleanupWarning = `Failed to remove branch directory: ${sanitizeErrorMessage(getErrorMessage(err))}`;
+                console.error(`CanopyCMS: Failed to move branch directory for ${branchName} aside:`, getErrorMessage(err));
             }
         });
     }
@@ -510,6 +527,8 @@ export const deleteBranchHandler = async (ctx, req, params) => {
             error: `Branch is busy, try again: ${getErrorMessage(err)}`,
         };
     }
+    if (deletingPath)
+        await removeLeftoverDir(deletingPath);
     // Also delete the branch's local head from the remote.git mirror (the
     // deployment's local origin). The sync loop deliberately never deletes a
     // local head (see reconcileTrackedBranches), so THIS is the one explicit
@@ -646,7 +665,7 @@ const createBranch = defineEndpoint({
     path: '/branches',
     body: createBranchBodySchema,
     bodyType: 'CreateBranchBody',
-    responseType: 'BranchResponse',
+    responseType: 'BranchListItemResponse',
     response: {},
     defaultMockData: {
         branch: {