@bevel-software/platform-core-backend 0.26.0 → 0.28.0

package/dist/modules/workflow/workflow.service.js

@@ -25,20 +25,24 @@ const syncLog = logger('sync');
 const lockLog = logger('lock');
 const crLog = logger('cr');
 const mergeLog = logger('merge');
+/** Who the leftover cleanup deletes as. Its deletions skip the authorship check, and the log names them `system`. */
+const SYSTEM_ACTOR = { id: 'system', email: 'system', name: 'system' };
 import { promises as fs } from 'node:fs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { isFolderPlaceholder, folderPlaceholderPath, isPlatformRestoreShape, } from '@bevel-software/platform-shared';
 import { and, desc, eq, inArray, isNotNull, isNull, lt, ne, or, sql } from 'drizzle-orm';
 import { changeRequests } from '../database/schema.js';
+import { pgErrorCode } from '../database/pg-error.js';
 import { redactSecret } from '../../shared/redact-secret.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
 import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
-import { sanitizeError } from './sanitize-error.js';
+import { describeSyncFailure, sanitizeError } from './sanitize-error.js';
 import { WorkflowHooks } from './workflow-hooks.js';
 import { WorkspaceMutex } from '../kb-fs/mutex.js';
+import { assertValidBranchName } from '../kb-fs/branch-name.js';
 import { canonicalEmail, hashEmail } from '../../shared/email-identity.js';
-import { ChangeRequestConflictsError, DuplicateChangeRequestError, OpenChangeRequestBlocksMergeError, RolesYamlPreservationError, PullRebaseConflictError, PushNeedsAgentResolutionError, RemoteBranchGoneError, WorkflowDomainError, WorkflowValidationError, } from '../../shared/domain-errors.js';
+import { BranchAuthorshipError, BranchDeleteBlockedError, BranchNotFoundError, ChangeRequestConflictsError, DuplicateChangeRequestError, OpenChangeRequestBlocksMergeError, ProtectedBranchError, RolesYamlPreservationError, PullRebaseConflictError, PushNeedsAgentResolutionError, RemoteBranchGoneError, WorkflowDomainError, WorkflowValidationError, } from '../../shared/domain-errors.js';
 import { RECOVERY_BOT_EMAIL, RECOVERY_BOT_NAME } from './recovery-bot.js';
 import { AccessDeniedError } from '../access-model/access-errors.js';
 import { printable } from '../../shared/printable.js';
@@ -59,7 +63,7 @@ function isOpenPairViolation(err) {
     // sometimes wraps that error in `.cause`, so unwrap one level and check both.
     const fieldOf = (e, key) => typeof e === 'object' && e !== null ? e[key] : undefined;
     const cause = typeof err === 'object' && err !== null ? err.cause : undefined;
-    const is23505 = fieldOf(err, 'code') === '23505' || fieldOf(cause, 'code') === '23505';
+    const is23505 = pgErrorCode(err) === '23505';
     if (!is23505)
         return false;
     // Prefer the structured `constraint` name; some pg drivers omit it, so fall
@@ -391,9 +395,19 @@ export class WorkflowService {
             // request has to be withdrawn or declined first. `systemCleanup` does
             // its own open-request check under this same lock, and the legacy
             // `onlyIfNoRemote` prune only fires when origin no longer has the ref.
+            // A request that proposes nothing any more is closed first, and then
+            // blocks nothing. Only for a caller the deletion would go ahead for: a
+            // refused deletion changes nothing, a closed request included — so one
+            // that fails after the close reopens what it closed.
+            let closed = [];
             if (!opts?.systemCleanup && !opts?.onlyIfNoRemote) {
-                const open = await this.openChangeRequestOn(name);
+                let open = await this.openChangeRequestOn(name);
+                if (open !== null && !this.kb.isProtectedBranch(name) && (await this.mayDelete(workspaceId, name, user))) {
+                    closed = await this.closeEmptyRequestsOn(name, user.id, { workspaceId, fresh: false });
+                    open = await this.openChangeRequestOn(name);
+                }
                 if (open !== null) {
+                    await this.reopenAfterFailedDelete(closed, name, user.id);
                     // Two different situations, two different actors. A request FROM
                     // this branch is the deleter's own to withdraw; a request INTO it
                     // belongs to someone else, and telling the branch owner to
@@ -406,12 +420,24 @@ export class WorkflowService {
                             `after that the branch can be deleted.`);
                 }
             }
-            await this.deleteBranchUnlocked(workspaceId, name, user, opts);
+            try {
+                await this.deleteBranchUnlocked(workspaceId, name, user, opts);
+            }
+            catch (err) {
+                await this.reopenAfterFailedDelete(closed, name, user.id);
+                throw err;
+            }
         });
     }
     /** The deletion itself — callers must hold the branch-lifecycle lock. */
     async deleteBranchUnlocked(workspaceId, name, user, opts) {
-        await this.git.deleteBranch(workspaceId, name, user, opts);
+        const { lastCommit } = await this.git.deleteBranch(workspaceId, name, user, opts);
+        // One line per deletion, whoever asked: the commit is what a restore
+        // starts from, and for a deletion made in the app or by the cleanup this
+        // line is the only trace there is.
+        // By id, never by address: log lines carry no email (the release's own promise).
+        const actor = opts?.systemCleanup ? 'system' : user.id;
+        log.info(`branch deleted by ${actor}: "${name}" at ${lastCommit ?? '(no commit)'}`);
         // Retire the deleted branch's own workspace clone, best-effort. A stale
         // clone left on disk would be silently REUSED if the branch name is ever
         // recreated (the workspace bootstrap short-circuits on an existing
@@ -425,6 +451,305 @@ export class WorkflowService {
         catch (err) {
             log.warn(`could not retire workspace clone of deleted branch "${name}":`, { err });
         }
+        return { lastCommit };
+    }
+    /**
+     * Every open change request naming `branch`, at either end — the preview's
+     * list. `openChangeRequestOn` answers the first one, which is all a refusal
+     * needs.
+     */
+    async openChangeRequestsOn(branch) {
+        const rows = await this.db
+            .select({ number: changeRequests.number, sourceBranch: changeRequests.sourceBranch })
+            .from(changeRequests)
+            .where(and(or(eq(changeRequests.sourceBranch, branch), eq(changeRequests.targetBranch, branch)), eq(changeRequests.state, 'open')));
+        return rows.map((row) => ({
+            number: row.number,
+            end: row.sourceBranch === branch ? 'source' : 'target',
+        }));
+    }
+    /**
+     * Whether open change request `summary` proposes nothing at this moment:
+     * its changes, recomputed now, are empty, and no save to its source branch
+     * is still landing (a save under a held lock or queued for the commit
+     * worker is on disk but not yet in the diff). Anything that cannot be
+     * determined is a no — a request is never closed on a guess.
+     *
+     * `workspaceId` is the clone to compute in (any clone will do: the diff is
+     * between origin's refs); absent, the source branch's own, as the app's
+     * lazy close always did. `fresh` says that clone was just fetched, so the
+     * refs are read as they are instead of fetched again per request.
+     */
+    async proposesNothing(summary, opts = {}) {
+        try {
+            const wsId = opts.workspaceId ?? (await this.workspaceService.getOrCreateForBranch(summary.branch)).id;
+            const paths = await this.git.changedPathsForPr(wsId, summary.base, summary.branch, opts.fresh ? { fetch: false } : {});
+            if (paths.length > 0)
+                return false;
+        }
+        catch (err) {
+            crLog.warn(`empty-check for change request #${summary.number} failed — leaving it open:`, { err });
+            return false;
+        }
+        return !(await this.savesInFlight(workspaceIdForBranch(summary.branch)));
+    }
+    /**
+     * Close open change request `number` if it proposes nothing right now
+     * ({@link proposesNothing}), recorded as today's empty-close: closed state
+     * and closing time, guarded on `state = 'open'` so a concurrent merge or
+     * withdrawal wins. Writes the log line every such close owes. Does NOT
+     * retire the source branch — the caller decides that, and a caller holding
+     * that branch's lifecycle lock must not. Answers the request's target when
+     * this call closed it, else null.
+     */
+    async closeIfEmpty(number, opts) {
+        const summary = await this.prs.getPr(number);
+        if (!summary || summary.state !== 'open')
+            return null;
+        if (!(await this.proposesNothing(summary, opts)))
+            return null;
+        const now = new Date();
+        const updated = await this.db
+            .update(changeRequests)
+            .set({ state: 'closed', closedAt: now, updatedAt: now })
+            .where(and(eq(changeRequests.number, number), eq(changeRequests.state, 'open')))
+            .returning({ id: changeRequests.id });
+        if (updated.length === 0)
+            return null;
+        this.prs.invalidateDetailCache(number);
+        this.events?.emit({ kind: 'change-request-rejected', number });
+        crLog.info(`closed change request #${number} ("${summary.branch}" into "${summary.base}") by ${opts.actor}: ` +
+            `it proposes nothing (${opts.reason})`);
+        return { base: summary.base };
+    }
+    /**
+     * The deletion's close-empty move: every open request from or into
+     * `branch` that proposes nothing is closed. Best effort per request — one
+     * that cannot be judged or closed stays open, and the open-request check
+     * after this refuses on it. Never retires a branch: the caller holds
+     * `branch`'s lifecycle lock, and the deletion itself removes it. Answers
+     * the numbers it closed, so a deletion that then fails can reopen them
+     * ({@link reopenAfterFailedDelete}).
+     */
+    async closeEmptyRequestsOn(branch, actor, opts) {
+        const closed = [];
+        for (const cr of await this.openChangeRequestsOn(branch)) {
+            try {
+                if (await this.closeIfEmpty(cr.number, { ...opts, actor, reason: `empty when "${branch}" was deleted` })) {
+                    closed.push(cr.number);
+                }
+            }
+            catch (err) {
+                crLog.warn(`could not close empty change request #${cr.number} before deleting "${branch}":`, { err });
+            }
+        }
+        return closed;
+    }
+    /**
+     * Undo {@link closeEmptyRequestsOn} for a deletion that failed after it: a
+     * refused deletion changes nothing, and the requests it closed are open
+     * again. Still under the branch's lifecycle lock, so nothing can have
+     * merged, withdrawn or declined them in between; guarded on `closed` all
+     * the same. Best effort: a request that cannot be reopened is logged.
+     */
+    async reopenAfterFailedDelete(numbers, branch, actor) {
+        if (numbers.length === 0)
+            return;
+        try {
+            const reopened = await this.db
+                .update(changeRequests)
+                .set({ state: 'open', closedAt: null, updatedAt: new Date() })
+                .where(and(inArray(changeRequests.number, numbers), eq(changeRequests.state, 'closed')))
+                .returning({ number: changeRequests.number });
+            for (const { number } of reopened) {
+                this.prs.invalidateDetailCache(number);
+                crLog.info(`reopened change request #${number} for ${actor}: deleting "${branch}" failed after it was closed`);
+                // The close told every tab the request was gone; announce it back,
+                // as an open does, so none keeps leaving it out.
+                const summary = await this.prs.getPr(number).catch(() => null);
+                if (summary) {
+                    this.events?.emit({
+                        kind: 'change-request-opened',
+                        number,
+                        source: summary.branch,
+                        target: summary.base,
+                        authorIdHash: summary.authorId ?? null,
+                        title: summary.title,
+                    });
+                }
+            }
+        }
+        catch (err) {
+            crLog.warn(`could not reopen change requests ${numbers.map((n) => `#${n}`).join(', ')} after deleting "${branch}" failed:`, { err });
+        }
+    }
+    /** The author-or-Admin rule, as a yes/no; a rule that cannot be read is a no. */
+    async mayDelete(workspaceId, name, user) {
+        try {
+            return await this.git.mayDeleteBranch(workspaceId, name, user);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * The refusal for an open request that still proposes something: names it,
+     * links to it, and says who can act — its author withdraws it, an Admin can
+     * decline it.
+     */
+    openRequestRefusal(branch, cr, visible = true) {
+        // One the caller may not see is not named, linked or placed at an end:
+        // `get_change_request` answers it as not found, and so does this.
+        if (!visible) {
+            return new BranchDeleteBlockedError('open-change-request', branch, `An open change request you cannot see still proposes changes from or into "${branch}". ` +
+                `An Admin can decline it in the app; then the branch can be deleted.`);
+        }
+        return new BranchDeleteBlockedError('open-change-request', branch, `Change request #${cr.number} (${cr.url}) is open ${cr.end === 'source' ? 'from' : 'into'} "${branch}" and still ` +
+            `proposes changes. Its author can withdraw it, or an Admin can decline it, in the app; then the branch can be deleted.`, { number: cr.number, url: cr.url });
+    }
+    /**
+     * The default branch's workspace, freshly fetched — where an agent's
+     * deletion and the leftover cleanup both decide and act. Never the
+     * branch's own checkout (which git refuses to delete from), and always
+     * after a strict, forced fetch: the refs are about to authorize a
+     * deletion, and a fetch that failed proves nothing about them.
+     */
+    async freshDefaultWorkspace() {
+        const ws = await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch);
+        await this.workspaceService.ensureRemotesFetched(ws.id, { strict: true, force: true });
+        return ws.id;
+    }
+    async deleteBranchChecked(user, name, opts = {}) {
+        assertValidBranchName(name);
+        // The caller's view of a request, as `get_change_request` gives it: one
+        // they may not see is never named, linked or judged in an answer. Absent,
+        // every request is visible. A verdict that fails is a no.
+        const maySee = async (number) => opts.maySee ? opts.maySee(number).catch(() => false) : true;
+        // Under the lock `deleteBranch`, `createBranch` and `openChangeRequest`
+        // take, so nothing this answer depends on — a request being opened, the
+        // branch being recreated — can change between the checks and the delete.
+        // A preview takes it too: it is short, and it then answers a settled state.
+        return this.branchLifecycle.run(`branch:${name}`, async () => {
+            const isProtected = this.kb.isProtectedBranch(name);
+            if (isProtected && !opts.dryRun)
+                throw new ProtectedBranchError(name, 'deleting a protected branch');
+            let wsId;
+            try {
+                wsId = await this.freshDefaultWorkspace();
+            }
+            catch (err) {
+                log.warn(`delete_branch "${name}": could not fetch the shared repository — deleting nothing:`, { err });
+                throw new BranchDeleteBlockedError('state-unconfirmed', name, `Could not reach the shared repository to confirm the current state of "${name}", so nothing was deleted. Try again shortly.`);
+            }
+            const state = await this.git.branchState(wsId, name, this.kb.defaultBranch);
+            if (!state.exists) {
+                if (!opts.dryRun)
+                    throw new BranchNotFoundError(name);
+                return {
+                    kind: 'preview',
+                    branch: name,
+                    exists: false,
+                    canDelete: false,
+                    refusals: [new BranchNotFoundError(name).message],
+                    unmergedCommits: 0,
+                    openChangeRequests: [],
+                    lastCommit: null,
+                };
+            }
+            // Every refusal, in the order a deletion meets them. The preview lists
+            // them all; a deletion throws the first.
+            const refusals = [];
+            if (isProtected)
+                refusals.push(new ProtectedBranchError(name, 'deleting a protected branch'));
+            if (!(await this.git.mayDeleteBranch(wsId, name, user)))
+                refusals.push(new BranchAuthorshipError(name));
+            // Every open request at either end, each judged now: one that proposes
+            // nothing is closed by the deletion and blocks nothing; one that still
+            // proposes something — or whose changes cannot be determined — blocks.
+            // A request the caller may not see is not part of a preview at all —
+            // not listed, not judged, not weighed in `canDelete` — so the preview
+            // reads the same whether one exists, and whether it is empty. A
+            // deletion still closes it or is refused on it like any other, without
+            // naming it: the rules above are the deletion's, not the caller's view.
+            const open = [];
+            for (const cr of await this.openChangeRequestsOn(name)) {
+                const visible = await maySee(cr.number);
+                if (!visible && opts.dryRun)
+                    continue;
+                const summary = await this.prs.getPr(cr.number).catch(() => null);
+                const empty = summary ? await this.proposesNothing(summary, { workspaceId: wsId, fresh: true }) : false;
+                open.push({
+                    ...cr,
+                    url: summary?.url ?? `/change-requests/${cr.number}`,
+                    proposesNothing: empty,
+                    visible,
+                });
+            }
+            const blocking = open.find((cr) => !cr.proposesNothing);
+            if (blocking)
+                refusals.push(this.openRequestRefusal(name, blocking, blocking.visible));
+            // Not coverable by `discardUnmerged`: these are a person's saves on
+            // their way into the branch, not work already on it.
+            if (await this.savesInFlight(workspaceIdForBranch(name))) {
+                refusals.push(this.savesLandingRefusal(name));
+            }
+            if (state.unmergedCommits > 0 && !opts.discardUnmerged) {
+                const n = state.unmergedCommits;
+                refusals.push(new BranchDeleteBlockedError('unmerged-commits', name, `"${name}" holds ${n} commit${n === 1 ? '' : 's'} that ${n === 1 ? 'is' : 'are'} not on ${this.kb.defaultBranch}; ` +
+                    `deleting it would lose ${n === 1 ? 'it' : 'them'}. Pass discardUnmerged: true to delete it anyway.`, { unmergedCommits: n }));
+            }
+            if (opts.dryRun) {
+                return {
+                    kind: 'preview',
+                    branch: name,
+                    exists: true,
+                    canDelete: refusals.length === 0,
+                    refusals: refusals.map((r) => r.message),
+                    unmergedCommits: state.unmergedCommits,
+                    openChangeRequests: open.map(({ number, end, url, proposesNothing }) => ({ number, end, url, proposesNothing })),
+                    lastCommit: state.lastCommit,
+                };
+            }
+            // A refused deletion changes nothing: no request is closed either.
+            if (refusals[0])
+                throw refusals[0];
+            // The saves check above is a snapshot; a save could take its file lock
+            // since. With no lock grantable on the branch, it is made again and
+            // nothing can start landing between it and the deletion.
+            const { lastCommit } = await this.fileLocks.whileNoneAcquired(name, async () => {
+                if (await this.savesInFlight(workspaceIdForBranch(name)))
+                    throw this.savesLandingRefusal(name);
+                // Every open request proposes nothing: close them, each re-judged at
+                // the moment of closing — the last step before the deletion, so no
+                // later check can refuse after it. Nothing here takes this branch's
+                // lifecycle lock, so a request whose source IS this branch cannot make
+                // the deletion wait on itself. Should the deletion still fail (the
+                // leased push below), the requests closed here are reopened.
+                const closed = await this.closeEmptyRequestsOn(name, user.id, { workspaceId: wsId, fresh: true });
+                try {
+                    const still = (await this.openChangeRequestsOn(name))[0];
+                    if (still) {
+                        const summary = await this.prs.getPr(still.number).catch(() => null);
+                        throw this.openRequestRefusal(name, { ...still, url: summary?.url ?? `/change-requests/${still.number}` }, await maySee(still.number));
+                    }
+                    // Leased on the tip the checks above were made against, so a commit
+                    // pushed since is refused by the host instead of deleted unseen.
+                    return await this.deleteBranchUnlocked(wsId, name, user, {
+                        ...(state.lastCommit ? { expectTip: state.lastCommit } : {}),
+                    });
+                }
+                catch (err) {
+                    await this.reopenAfterFailedDelete(closed, name, user.id);
+                    throw err;
+                }
+            });
+            return {
+                kind: 'deleted',
+                branch: name,
+                lastCommit: lastCommit ?? state.lastCommit ?? '',
+                discardedCommits: state.unmergedCommits,
+            };
+        });
     }
     // No `switchBranch` here on purpose. Under the per-branch workspace model,
     // switching branches is a frontend navigation that triggers a workspace
@@ -440,7 +765,7 @@ export class WorkflowService {
     // `discardWorkingChanges` removed: under save=share there's nothing dirty
     // to discard.
     shareCurrentBranch(workspaceId, user) {
-        return this.trackedPush(workspaceId, user);
+        return this.pushWithRecovery(workspaceId, branchForWorkspaceId(workspaceId), '(share)', user);
     }
     refreshRemotes(workspaceId) {
         return this.git.fetch(workspaceId);
@@ -584,7 +909,7 @@ export class WorkflowService {
             }
             const message = sanitizeError(err);
             syncLog.warn(`pull failed for branch "${branch}": ${message}`);
-            this.noteGitSyncFailed(gitId, branch, err);
+            this.noteGitSyncFailed(gitId, branch, err, undefined, 'pull');
             return { branch, outcome: 'error', error: message };
         }
         // A clean pull is proof origin is reachable and this clone rebases onto
@@ -905,7 +1230,9 @@ export class WorkflowService {
             });
         }
         else {
-            lockLog.info(`ACQUIRE ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → contended, held by ${result.lock.holderName} (${result.lock.holderUserId})`);
+            lockLog.info(
+            // The holder by id only: log lines carry no names.
+            `ACQUIRE ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → contended, held by ${result.lock.holderUserId}`);
         }
         return result;
     }
@@ -969,7 +1296,8 @@ export class WorkflowService {
                 let recoveryError = null;
                 if (looksLikeNonFastForward) {
                     try {
-                        await this.pullWorkspace(workspaceId);
+                        // Same as `pushWithRecovery`: keep a stranded merge a merge.
+                        await this.pullWorkspace(workspaceId, { preserveMerges: true });
                         await this.git.push(workspaceId, user);
                         recovered = true;
                         this.noteGitSyncOk(workspaceId, branch);
@@ -1049,7 +1377,7 @@ export class WorkflowService {
         lockLog.info(`RELEASE start ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id}`);
         const lock = await this.fileLocks.get(workspaceId, branch, targetPath);
         if (!lock || lock.holderUserId !== user.id) {
-            lockLog.warn(`RELEASE refused ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → ${lock ? `held by ${lock.holderName} (${lock.holderUserId})` : 'no lock row'}`);
+            lockLog.warn(`RELEASE refused ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → ${lock ? `held by ${lock.holderUserId}` : 'no lock row'}`);
             throw new WorkflowValidationError(`Cannot release lock on "${targetPath}": not held by you (or no longer exists).`, { kind: 'lock-not-held', branch, path: targetPath });
         }
         // Releasing a coordination hold must NEVER enqueue a commit: the hold was
@@ -1192,7 +1520,13 @@ export class WorkflowService {
      * clip would make the banner disagree with them. Callers that already
      * hold the sentence pass it; otherwise it is derived below.
      */
-    explicitConflict) {
+    explicitConflict, 
+    /**
+     * Which side of the sync failed. A 403 or "Repository not found" on a
+     * pull means the credentials cannot READ the repository, and telling the
+     * operator to grant push access would send them to the wrong setting.
+     */
+    operation = 'push') {
         // A rebase conflict is a conflict whichever path ran into it. The remote
         // sync names its files on purpose; the push-recovery paths (autosave, the
         // lock release, the queued retries) raise the same banner with the raw
@@ -1213,48 +1547,34 @@ export class WorkflowService {
             kind: 'git-sync-failed',
             workspaceId: id,
             branch,
-            // Git stderr can quote a credentialed URL; the banner is user-facing and
-            // the string also lands in client logs, so sanitize before it leaves.
-            reason: conflict ? conflict.message : sanitizeError(err),
+            // Never the git output itself — not even sanitised: stderr quotes the
+            // host's own error text and URLs, and the banner is user-facing. A
+            // fixed sentence says what kind of failure it was; the raw text is in
+            // the server log, where the banner points whoever can act on it.
+            reason: conflict ? conflict.message : describeSyncFailure(err, operation),
             ...(conflict ? { conflictedPaths: conflict.paths } : {}),
         });
     }
-    /**
-     * A bare push wrapped in the sync tracker: a failure raises the banner, a
-     * success clears it. For the workflow paths that push directly — sharing a
-     * branch, publishing a CR's source, update-from-base, the decline revert,
-     * the roles.yaml restore — rather than through `pushWithRecovery`'s
-     * cooperative ladder. Behaviour is otherwise unchanged: the error still
-     * propagates to the caller exactly as the bare push's did. Without this,
-     * those pushes could fail invisibly (no banner) and, worse, a successful
-     * share could not CLEAR a banner an earlier save had raised.
-     *
-     * The branch is derived from the workspace id (they are the same string,
-     * URL-encoding aside) so call sites cannot pass a mismatched pair.
-     */
-    async trackedPush(workspaceId, user, opts) {
-        const branch = branchForWorkspaceId(workspaceId);
-        try {
-            // Preserve the exact call shape of the bare pushes this replaces — an
-            // explicit `undefined` third argument is a different call signature to
-            // every spy that asserts on it.
-            await (opts ? this.git.push(workspaceId, user, opts) : this.git.push(workspaceId, user));
-            this.noteGitSyncOk(workspaceId, branch);
-        }
-        catch (err) {
-            this.noteGitSyncFailed(workspaceId, branch, err);
-            throw err;
-        }
-    }
     /**
      * Shared implementation of "push, and on non-fast-forward try a
      * cooperative pull-rebase + retry, then hand off to the agent if that
      * still fails." The full rationale lives at the call site in
      * `releaseLock`; this method is the de-duplicated body.
+     *
+     * EVERY workflow push goes through here — saves, sharing a branch, opening
+     * a request, update-from-target, the decline revert, the roles.yaml
+     * restore — so a push the host refuses answers one way everywhere: the
+     * commit stays local, the sync banner goes up, and the caller gets the
+     * 409 saved-locally sentence instead of a raw git error (which a route
+     * would turn into a 500). A later successful push of the branch carries
+     * the commits and clears the banner.
      */
     async pushWithRecovery(workspaceId, branch, targetPath, user, opts) {
+        // No explicit `undefined` third argument when there are no options: the
+        // call shape stays the bare `push(workspaceId, user)` every caller made.
+        const push = () => opts ? this.git.push(workspaceId, user, opts) : this.git.push(workspaceId, user);
         try {
-            await this.git.push(workspaceId, user, opts);
+            await push();
             this.noteGitSyncOk(workspaceId, branch);
         }
         catch (firstPushErr) {
@@ -1263,10 +1583,25 @@ export class WorkflowService {
             let recovered = false;
             let recoveryDetail = '(cooperative path not attempted)';
             let recoveryError = null;
+            // The retry push's own rejection, when the pull got that far: the
+            // divergence is cured by then, so it — not the first rejection — says
+            // whether the host is refusing.
+            let retryDetail = null;
             if (looksLikeNonFastForward) {
                 try {
-                    await this.pullWorkspace(workspaceId);
-                    await this.git.push(workspaceId, user, opts);
+                    // `preserveMerges` on every push, not only the ones that make a
+                    // merge: a merge stranded by a refused open or update rides along
+                    // with whatever push of the branch comes next — a save, a share —
+                    // and a plain rebase would flatten it into cherry-picks. With no
+                    // merge among the local commits the two spellings replay the same.
+                    await this.pullWorkspace(workspaceId, { preserveMerges: true });
+                    try {
+                        await push();
+                    }
+                    catch (retryErr) {
+                        retryDetail = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                        throw retryErr;
+                    }
                     recovered = true;
                     this.noteGitSyncOk(workspaceId, branch);
                     log.info(`non-fast-forward push recovered via pull --rebase for workspace=${workspaceId} branch=${branch} path=${targetPath}`);
@@ -1285,9 +1620,17 @@ export class WorkflowService {
                 // When recovery RAN, its error is the current state of the world (the
                 // first rejection may be a stale non-fast-forward the pull already
                 // cured); when it was skipped, the first error is all there is.
-                this.noteGitSyncFailed(workspaceId, branch, recoveryError ?? firstPushErr);
+                // A recovery that failed before its retry push failed in the PULL.
+                const failedInPull = recoveryError !== null && retryDetail === null;
+                this.noteGitSyncFailed(workspaceId, branch, recoveryError ?? firstPushErr, undefined, failedInPull ? 'pull' : 'push');
                 log.warn(`push failed for workspace=${workspaceId} user=${user.id}; throwing PushNeedsAgentResolutionError so the frontend can hand off to the agent:`, { detail: firstDetail });
-                throw new PushNeedsAgentResolutionError(branch, targetPath, firstDetail, recoveryDetail);
+                throw new PushNeedsAgentResolutionError(branch, targetPath, firstDetail, recoveryDetail, 
+                // `rejected` above also matches the host's own `[remote rejected]`
+                // (an outage, a hook): worth the cooperative try, but only a real
+                // divergence is described as one.
+                /non-fast-forward|fetch first|updates were rejected|! \[rejected\]/i.test(retryDetail ?? firstDetail)
+                    ? 'diverged'
+                    : 'refused');
             }
         }
     }
@@ -1527,10 +1870,21 @@ export class WorkflowService {
             if (mergeOutcome.kind === 'conflicts') {
                 throw new ChangeRequestConflictsError(input.sourceBranch, input.targetBranch, mergeOutcome.paths);
             }
-            // Push the source — `gh pr create` against an unpushed branch returns
-            // "head branch does not exist on remote". Push *after* the auto-merge
-            // so the remote sees the merge commit too.
-            await this.trackedPush(workspaceId, user);
+            // Push the source *after* the auto-merge so the remote sees the merge
+            // commit too. A push the host refuses does not undo the open: the merge
+            // is committed locally, the request is a DB row, and the next push of
+            // the branch carries the commits — so the row is still created below and
+            // the refusal (409, the saved-locally sentence, the sync banner) is
+            // answered once it exists.
+            let pushRefused = null;
+            try {
+                await this.pushWithRecovery(workspaceId, branchForWorkspaceId(workspaceId), '(opening a change request)', user);
+            }
+            catch (err) {
+                if (!(err instanceof PushNeedsAgentResolutionError))
+                    throw err;
+                pushRefused = err;
+            }
             const workspacePath = await this.workspaceService.getWorkspacePath(workspaceId);
             const cwd = path.join(workspacePath, this.kbDirName);
             // Touched paths between target and source — basis for the
@@ -1592,6 +1946,21 @@ export class WorkflowService {
                 throw new WorkflowValidationError(`Failed to open change request: ${redactTokens(rawMsg, this.git.credentials?.token())}`, { kind: 'open-change-request-failed' });
             }
             this.prs.invalidateDetailCache(prNumber);
+            const opened = {
+                kind: 'change-request-opened',
+                number: prNumber,
+                source: input.sourceBranch,
+                target: input.targetBranch,
+                authorIdHash: hashEmail(user.email),
+                title: input.title,
+            };
+            if (pushRefused) {
+                // The request exists; its detail reads the published refs, which the
+                // refused push never moved — answering the refusal is what the caller
+                // needs, not a detail read that may fail on a branch the host lacks.
+                this.events?.emit(opened);
+                throw pushRefused;
+            }
             const detail = await this.prs.getPrDetail(prNumber, {
                 fresh: true,
                 workspaceId,
@@ -1600,14 +1969,7 @@ export class WorkflowService {
             if (!detail) {
                 throw new WorkflowValidationError(`Created change request #${prNumber} but could not fetch its detail`);
             }
-            this.events?.emit({
-                kind: 'change-request-opened',
-                number: prNumber,
-                source: input.sourceBranch,
-                target: input.targetBranch,
-                authorIdHash: hashEmail(user.email),
-                title: input.title,
-            });
+            this.events?.emit(opened);
             return detail;
         });
     }
@@ -1719,7 +2081,7 @@ export class WorkflowService {
         // do. Asking git what is unpushed retries it instead.
         //
         // A failed probe falls back to the old gate rather than to "push
-        // anyway": `trackedPush` on a clone with nothing to push is a wasted
+        // anyway": a push on a clone with nothing to push is a wasted
         // round trip on every single update.
         const hasUnpushed = await this.git
             .hasUnpushedCommits(workspaceId)
@@ -1728,7 +2090,10 @@ export class WorkflowService {
             return !outcome.alreadyUpToDate;
         });
         if (hasUnpushed) {
-            await this.trackedPush(workspaceId, user);
+            // A refusal answers 409 with the saved-locally sentence and leaves the
+            // merge applied in the clone; the probe above makes the next update
+            // (or any save on the branch) push it.
+            await this.pushWithRecovery(workspaceId, branchForWorkspaceId(workspaceId), `(update from ${detail.base})`, user);
         }
         // Where the branch ended up, as PUBLISHED — two rev-parses, not a second
         // detail read. Everything below needs only the sha, and the detail that
@@ -1904,8 +2269,10 @@ export class WorkflowService {
         // Best-effort freshen of the source checkout: the diff below reads origin
         // refs, but the restore commits from the working tree — a stale tree
         // would push non-fast-forward and fail loudly anyway; this just makes
-        // that rare.
-        await this.pullWorkspace(ws.id).catch(() => undefined);
+        // that rare. `preserveMerges`: the branch may carry a merge a refused open
+        // or update stranded locally, and a plain rebase would flatten it before
+        // the revert's push publishes the branch.
+        await this.pullWorkspace(ws.id, { preserveMerges: true }).catch(() => undefined);
         // The verb acts on the request as it is NOW — never a cached file list.
         const paths = await this.git.changedPathsForPr(ws.id, baseBranch, headBranch);
         if (!paths.includes(repoRelPath)) {
@@ -1925,6 +2292,10 @@ export class WorkflowService {
         // save must not race the restore between write and commit.
         const held = [];
         let revertError = null;
+        // A push the host refuses leaves the revert committed on the branch
+        // locally; it is answered (409, the saved-locally sentence) only after
+        // the locks are released and the request's caches reflect the new head.
+        let pushRefused = null;
         try {
             for (const p of reverted) {
                 const lockPath = `${this.kbDirName}/${p}`;
@@ -1940,7 +2311,14 @@ export class WorkflowService {
                 await this.git.restorePathFromRef(ws.id, mergeBase, p);
                 await this.git.commitFile(ws.id, user, p, `Revert ${p} (declined in change request #${number})`, true);
             }
-            await this.trackedPush(ws.id, user);
+            try {
+                await this.pushWithRecovery(ws.id, headBranch, repoRelPath, user);
+            }
+            catch (err) {
+                if (!(err instanceof PushNeedsAgentResolutionError))
+                    throw err;
+                pushRefused = err;
+            }
         }
         catch (err) {
             revertError = { reason: err };
@@ -1956,9 +2334,15 @@ export class WorkflowService {
         const failedRelease = released.find((r) => r.status === 'rejected');
         if (failedRelease)
             throw failedRelease.reason;
+        this.prs.invalidateDetailCache(number);
+        // A refused push moved nothing the request is judged on. A recorded
+        // apply failure describes the published head, which is still where it
+        // was, so it stays; and the file list reads the published refs, so
+        // closing an "empty" request is decided once the push lands.
+        if (pushRefused)
+            throw pushRefused;
         // The source head moved: the refusal described a revision that is gone.
         await this.clearApplyFailure(number, { recordedBefore: headMovedAfter });
-        this.prs.invalidateDetailCache(number);
         const remaining = await this.git.changedPathsForPr(ws.id, baseBranch, headBranch);
         if (remaining.length > 0) {
             // Answered like the file list: the placeholder is not a remaining file.
@@ -2076,7 +2460,9 @@ export class WorkflowService {
                 continue;
             const ws = await this.workspaceService.getOrCreateForBranch(summary.branch);
             try {
-                await this.pullWorkspace(ws.id);
+                // `preserveMerges`: a merge a refused open or update stranded on the
+                // request's branch must survive until the branch's next push.
+                await this.pullWorkspace(ws.id, { preserveMerges: true });
             }
             catch (err) {
                 log.warn(`pull failed for #${summary.number} before removing folder ${printable(folder)}: ${printable(sanitizeError(err))}`);
@@ -2339,37 +2725,10 @@ export class WorkflowService {
      * Returns true when THIS call closed it.
      */
     async closeEmptyChangeRequest(number, user) {
-        const summary = await this.prs.getPr(number);
-        if (!summary || summary.state !== 'open')
-            return false;
-        let paths;
-        let wsId;
-        try {
-            const ws = await this.workspaceService.getOrCreateForBranch(summary.branch);
-            wsId = ws.id;
-            paths = await this.git.changedPathsForPr(ws.id, summary.base, summary.branch);
-        }
-        catch (err) {
-            crLog.warn(`empty-check for change request #${number} failed — leaving it open:`, { err });
-            return false;
-        }
-        if (paths.length > 0)
+        const closed = await this.closeIfEmpty(number, { reason: 'found empty', actor: user.email });
+        if (!closed)
             return false;
-        if (await this.savesInFlight(wsId))
-            return false;
-        // Guard on `state = 'open'` so a concurrent merge or withdraw wins the
-        // race and this becomes a no-op.
-        const now = new Date();
-        const updated = await this.db
-            .update(changeRequests)
-            .set({ state: 'closed', closedAt: now, updatedAt: now })
-            .where(and(eq(changeRequests.number, number), eq(changeRequests.state, 'open')))
-            .returning({ id: changeRequests.id });
-        if (updated.length === 0)
-            return false;
-        this.prs.invalidateDetailCache(number);
-        this.events?.emit({ kind: 'change-request-rejected', number });
-        await this.retireMergedSourceBranch(number, summary.base, user);
+        await this.retireMergedSourceBranch(number, closed.base, user);
         return true;
     }
     /**
@@ -2378,6 +2737,9 @@ export class WorkflowService {
      * (their file is still only on disk). An answer that cannot be read is a
      * yes — the caller is about to delete the checkout.
      */
+    savesLandingRefusal(name) {
+        return new BranchDeleteBlockedError('saves-landing', name, `"${name}" still has saves waiting to be committed or a file held for editing. Try again once they have landed.`);
+    }
     async savesInFlight(wsId) {
         try {
             return (await this.fileLocks.hasAnyActive(wsId)) || (await this.pendingCommits.hasAnyForWorkspace(wsId));
@@ -2611,10 +2973,245 @@ export class WorkflowService {
             }
         })
             .catch((err) => crLog.warn('on-demand deleted-branch sweep failed:', { err }))
+            // Every sweep is followed by the tidy-up, which never throws.
+            .then(() => this.tidyAfterSweep())
+            .then(() => undefined)
             .finally(() => {
             this.sweepKick = null;
         });
     }
+    tidyRound = null;
+    tidyStopped = false;
+    /**
+     * Stop the tidy-up when the graph stops: no round starts after this, and a
+     * round under way stops at its next request or branch. Then
+     * {@link drainTidy} waits for it, so it cannot fetch or delete once the
+     * pool is ended or a replacement graph owns the same checkout.
+     */
+    stopTidying() {
+        this.tidyStopped = true;
+    }
+    /** Settles once no tidy-up (nor the sweep that leads into one) is running. */
+    async drainTidy() {
+        await Promise.allSettled([this.sweepKick, this.tidyRound]);
+    }
+    /**
+     * What follows every sweep for deleted branches — at startup, on a remote
+     * sync, after a merge and on demand: first the open requests that propose
+     * nothing are closed and their source branch removed
+     * ({@link closeEmptyOpenChangeRequests}), then the branches merged requests
+     * left behind ({@link retireLeftoverMergedBranches}, behind its own
+     * setting). In that order, because closing an empty request is what can
+     * free a branch for the second. Never throws; coalesced.
+     */
+    tidyAfterSweep() {
+        if (this.tidyRound)
+            return this.tidyRound;
+        if (this.tidyStopped)
+            return Promise.resolve({ closedEmpty: 0, removedLeftovers: 0 });
+        this.tidyRound = (async () => {
+            const closedEmpty = await this.closeEmptyOpenChangeRequests().catch((err) => {
+                crLog.warn('background close of empty change requests failed:', { err });
+                return 0;
+            });
+            const removedLeftovers = await this.retireLeftoverMergedBranches();
+            return { closedEmpty, removedLeftovers };
+        })().finally(() => {
+            this.tidyRound = null;
+        });
+        return this.tidyRound;
+    }
+    /**
+     * Close every open change request that proposes nothing, and remove its
+     * source branch — what opening such a request's page in the app does
+     * (`closeEmptyChangeRequest`), done without anyone opening it. Each is
+     * judged from the default branch's workspace against origin's refs, after
+     * ONE strict fetch, so no request's branch is cloned for the question; a
+     * round whose fetch fails closes nothing. A request whose changes cannot be
+     * determined, or with a save still landing on its branch, stays open.
+     * Returns how many it closed.
+     *
+     * The source branch is removed under the same guards as any other
+     * deletion: under its lifecycle lock, only with no request open from or
+     * into it, with no save landing and no lock grantable on it at that moment,
+     * and leased on the tip the request was judged empty at — a commit pushed
+     * since is refused by the host instead of deleted unseen.
+     */
+    async closeEmptyOpenChangeRequests() {
+        const open = await this.db
+            .select({ number: changeRequests.number, sourceBranch: changeRequests.sourceBranch })
+            .from(changeRequests)
+            .where(eq(changeRequests.state, 'open'));
+        if (open.length === 0)
+            return 0;
+        let wsId;
+        try {
+            wsId = await this.freshDefaultWorkspace();
+        }
+        catch (err) {
+            crLog.warn('background close of empty change requests skipped — could not fetch the shared repository:', { err });
+            return 0;
+        }
+        let closed = 0;
+        for (const { number, sourceBranch } of open) {
+            if (this.tidyStopped)
+                break;
+            try {
+                // Read before the request is judged, so the lease below covers
+                // anything that reached the branch after the judgement.
+                const tip = this.kb.isProtectedBranch(sourceBranch)
+                    ? null
+                    : (await this.git.branchState(wsId, sourceBranch, this.kb.defaultBranch)).lastCommit;
+                const done = await this.closeIfEmpty(number, {
+                    workspaceId: wsId,
+                    fresh: true,
+                    actor: 'system',
+                    reason: 'empty in the background sweep',
+                });
+                if (!done)
+                    continue;
+                closed++;
+                if (tip)
+                    await this.retireEmptySourceBranch(wsId, sourceBranch, tip);
+            }
+            catch (err) {
+                crLog.warn(`background close of change request #${number} failed — leaving it open:`, { err });
+            }
+        }
+        return closed;
+    }
+    /**
+     * Remove the source branch of a request the background sweep just closed
+     * as empty, from the default branch's freshly fetched workspace `wsId`.
+     * Skips quietly when another request is open from or into it or a save is
+     * landing on it; the delete is leased on `tip`. Never throws.
+     */
+    async retireEmptySourceBranch(wsId, branch, tip) {
+        try {
+            await this.branchLifecycle.run(`branch:${branch}`, async () => {
+                if ((await this.openChangeRequestOn(branch)) !== null)
+                    return;
+                await this.fileLocks.whileNoneAcquired(branch, async () => {
+                    if (await this.savesInFlight(workspaceIdForBranch(branch))) {
+                        crLog.info(`kept "${branch}" after closing its empty change request: a save is still landing on it`);
+                        return;
+                    }
+                    await this.deleteBranchUnlocked(wsId, branch, SYSTEM_ACTOR, { systemCleanup: true, expectTip: tip });
+                });
+            });
+        }
+        catch (err) {
+            crLog.warn(`could not remove "${branch}" after closing its empty change request (non-fatal):`, { err });
+        }
+    }
+    /**
+     * Whether the leftover cleanup below runs — the `retireMergedBranches`
+     * deployment setting, read at every round so the Deployment page applies
+     * without a restart. Set by the composition root; on by default.
+     */
+    leftoverCleanupEnabled = () => true;
+    leftoverRound = null;
+    /**
+     * Remove the branches merged change requests left behind: sources of a
+     * merge from before the post-merge retirement existed (core-backend 0.5.0),
+     * and ones whose retirement failed. What `retireMergedSourceBranch` does
+     * after a merge, applied to every merge on record.
+     *
+     * A branch goes only when ALL hold: it is not protected; it was the source
+     * of a merged request; it has no commit that is not on the default branch;
+     * no request is open from or into it; its tip is contained in the merge
+     * commit recorded for one of those requests — a branch recreated under the
+     * same name after the merge is somebody's new draft, and a request with no
+     * recorded merge commit proves nothing; and its checkout has no saves
+     * landing and no file held. Each is decided and deleted under the branch's
+     * lifecycle lock, like the post-merge retirement.
+     *
+     * Fails SAFE, like the deleted-branch sweep it runs beside: a round whose
+     * fetch fails removes nothing, and a branch whose state cannot be read is
+     * left. The switch covers this round only; the post-merge retirement is not
+     * asked. Never throws. Coalesced, because boot, the remote sync and the
+     * on-demand sweep can all start one. Returns how many it removed.
+     */
+    retireLeftoverMergedBranches() {
+        if (this.leftoverRound)
+            return this.leftoverRound;
+        this.leftoverRound = this.retireLeftoverMergedBranchesOnce()
+            .catch((err) => {
+            log.warn('leftover branch cleanup failed:', { err });
+            return 0;
+        })
+            .finally(() => {
+            this.leftoverRound = null;
+        });
+        return this.leftoverRound;
+    }
+    async retireLeftoverMergedBranchesOnce() {
+        if (!this.leftoverCleanupEnabled())
+            return 0;
+        const merged = await this.db
+            .select({ sourceBranch: changeRequests.sourceBranch, mergedSha: changeRequests.mergedSha })
+            .from(changeRequests)
+            .where(eq(changeRequests.state, 'merged'));
+        const mergeCommits = new Map();
+        for (const row of merged) {
+            if (this.kb.isProtectedBranch(row.sourceBranch))
+                continue;
+            const shas = mergeCommits.get(row.sourceBranch) ?? [];
+            if (row.mergedSha)
+                shas.push(row.mergedSha);
+            mergeCommits.set(row.sourceBranch, shas);
+        }
+        if (mergeCommits.size === 0)
+            return 0;
+        let wsId;
+        try {
+            wsId = await this.freshDefaultWorkspace();
+        }
+        catch (err) {
+            log.warn('leftover branch cleanup skipped — could not fetch the shared repository:', { err });
+            return 0;
+        }
+        let removed = 0;
+        for (const [branch, shas] of mergeCommits) {
+            if (this.tidyStopped)
+                break;
+            if (shas.length === 0)
+                continue;
+            try {
+                const done = await this.branchLifecycle.run(`branch:${branch}`, async () => {
+                    const state = await this.git.branchState(wsId, branch, this.kb.defaultBranch);
+                    if (!state.exists || state.lastCommit === null || state.unmergedCommits > 0)
+                        return false;
+                    if ((await this.openChangeRequestOn(branch)) !== null)
+                        return false;
+                    let contained = false;
+                    for (const sha of shas) {
+                        if (await this.git.isAncestor(wsId, state.lastCommit, sha).catch(() => false)) {
+                            contained = true;
+                            break;
+                        }
+                    }
+                    if (!contained)
+                        return false;
+                    const tip = state.lastCommit;
+                    return this.fileLocks.whileNoneAcquired(branch, async () => {
+                        if (await this.savesInFlight(workspaceIdForBranch(branch)))
+                            return false;
+                        await this.deleteBranchUnlocked(wsId, branch, SYSTEM_ACTOR, { systemCleanup: true, expectTip: tip });
+                        return true;
+                    });
+                });
+                if (done)
+                    removed++;
+            }
+            catch (err) {
+                log.warn(`leftover branch cleanup could not remove "${branch}":`, { err });
+            }
+        }
+        if (removed > 0)
+            log.info(`removed ${removed} branch${removed === 1 ? '' : 'es'} left over from merged change requests`);
+        return removed;
+    }
     /**
      * Reject (close-without-merging) a change request. Per PLAN.md spec, the
      * authorized set is:
@@ -2744,6 +3341,9 @@ export class WorkflowService {
         // AFTER the event: the applying UI is waiting on `change-request-merged`,
         // and branch retirement is git IO it must never wait behind.
         await this.retireMergedSourceBranch(number, baseBranch, user);
+        // A merge can empty OTHER open requests into the same target; the sweep's
+        // tidy-up closes those. Detached and coalesced, like every kick.
+        this.kickDeletedBranchSweep();
         return { kind: 'merged', result };
     }
     /**
@@ -2811,10 +3411,82 @@ export class WorkflowService {
             this.events?.emit({ kind: 'fs-tree-changed', workspaceId: targetWorkspaceId, branch: targetBranch });
         }
     }
+    /**
+     * How long `mergeBranch` waits for the source's queued commits, and how
+     * often it asks. The worker polls every half second and a commit takes a few
+     * seconds; twenty seconds of waiting is an outage, not latency.
+     *
+     * Twenty, not thirty, because of who is waiting on THIS call: an agent over
+     * `/api/mcp` reaches the tool through `@utcp/http`, whose request timeout is
+     * a fixed 30 seconds (its call-template schema drops any `timeout` field).
+     * The wait plus the merge after it (fetch, merge, push) must fit inside
+     * that, or the agent hears "timeout of 30000ms exceeded" instead of the
+     * `pending-commits` answer this wait exists to give. Mutable for tests only.
+     */
+    mergeWaitForPendingCommits = { timeoutMs: 20_000, pollMs: 250 };
+    /**
+     * Wait until no commit is queued on `branch`, or the bound runs out. A
+     * commit escalated to a person ends the wait at once: nothing will land it.
+     *
+     * Polls the queue rather than draining it: the worker's own per-workspace
+     * serialization stays the only writer to the clone, and the row is deleted
+     * only after its push, so "no row" means the remote holds the commit.
+     */
+    async awaitPendingCommits(branch) {
+        const { timeoutMs, pollMs } = this.mergeWaitForPendingCommits;
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const { queued, stuck, needsAttention } = await this.pendingCommits.queuedOnBranch(branch);
+            if (needsAttention !== null)
+                return { ok: false, pending: queued + stuck, needsAttention };
+            if (queued === 0)
+                return { ok: true };
+            if (Date.now() >= deadline)
+                return { ok: false, pending: queued };
+            await new Promise((resolve) => setTimeout(resolve, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
+        }
+    }
+    /** The one question `mergeBranch` refuses on: is a request from `source` into `target` open? */
+    async openRequestBlockingMerge(sourceBranch, targetBranch) {
+        const [open] = await this.db
+            .select({ number: changeRequests.number })
+            .from(changeRequests)
+            .where(and(eq(changeRequests.sourceBranch, sourceBranch), eq(changeRequests.targetBranch, targetBranch), eq(changeRequests.state, 'open')))
+            .limit(1);
+        return open ? open.number : null;
+    }
     async mergeBranch(user, sourceBranch, targetBranch) {
         if (sourceBranch === targetBranch) {
             throw new WorkflowValidationError(`\`source\` and \`target\` are both "${sourceBranch}" — name two different branches.`);
         }
+        // Asked once BEFORE waiting, so a merge the open request forbids is refused
+        // at once rather than after the source's commits have landed. Not the
+        // answer that counts — that one is asked again under the locks below.
+        const openBefore = await this.openRequestBlockingMerge(sourceBranch, targetBranch);
+        if (openBefore !== null)
+            throw new OpenChangeRequestBlocksMergeError(sourceBranch, targetBranch, openBefore);
+        // Writes are committed asynchronously: a write tool answers once the bytes
+        // are on disk and the pending-commits worker commits and pushes them a few
+        // seconds later. The merge below merges what the REMOTE holds of the
+        // source, so issued in those seconds it would find nothing new and land
+        // nothing. Wait for them first — OUTSIDE the lifecycle locks, which guard
+        // creating, deleting and opening requests on these branches, and must not
+        // be held for seconds of waiting on a queue.
+        const settled = await this.awaitPendingCommits(sourceBranch);
+        if (!settled.ok) {
+            const message = settled.needsAttention
+                ? `A commit queued on "${sourceBranch}" failed and needs a person: ${settled.needsAttention} ` +
+                    `Nothing was merged. Tell the user; merge again once it has been resolved.`
+                : `${settled.pending} write(s) on "${sourceBranch}" are still being committed. ` +
+                    `Nothing was merged. Retry the merge shortly.`;
+            return {
+                kind: 'pending-commits',
+                branch: sourceBranch,
+                pending: settled.pending,
+                ...(settled.needsAttention ? { needsAttention: settled.needsAttention } : {}),
+                message,
+            };
+        }
         // Under the lifecycle lock of BOTH branches, the same protocol
         // `openChangeRequest` follows — and for the same window. That method holds
         // these keys across its whole check-then-insert (an auto-merge and a push,
@@ -2828,13 +3500,9 @@ export class WorkflowService {
             // A person merges a change request. Only the request's OWN direction is
             // blocked: the target merged into the source is how a draft under review
             // stays current, and that must keep working while the request is open.
-            const [open] = await this.db
-                .select({ number: changeRequests.number })
-                .from(changeRequests)
-                .where(and(eq(changeRequests.sourceBranch, sourceBranch), eq(changeRequests.targetBranch, targetBranch), eq(changeRequests.state, 'open')))
-                .limit(1);
-            if (open)
-                throw new OpenChangeRequestBlocksMergeError(sourceBranch, targetBranch, open.number);
+            const open = await this.openRequestBlockingMerge(sourceBranch, targetBranch);
+            if (open !== null)
+                throw new OpenChangeRequestBlocksMergeError(sourceBranch, targetBranch, open);
             // The merge runs in the target's own workspace, like a change request's.
             const targetWorkspaceId = (await this.workspaceService.getOrCreateForBranch(targetBranch)).id;
             if (!(await this.git.remoteBranchExists(targetWorkspaceId, sourceBranch))) {
@@ -2894,6 +3562,13 @@ export class WorkflowService {
                 return { kind: 'conflicts-need-resolution', conflictedPaths: result.paths };
             }
             await this.pullMergeTarget(targetBranch, user);
+            // No merge commit: the target already held everything on the source, and
+            // `sha` is its unchanged tip. Reported as such — a `merged` that applied
+            // nothing is what sent agents on as if their write had landed.
+            if (result.mergeCommit === null)
+                return { kind: 'nothing-to-merge', sha: result.sha };
+            // What landed on the target may have emptied open requests into it.
+            this.kickDeletedBranchSweep();
             return { kind: 'merged', sha: result.sha };
         });
     }
@@ -3143,8 +3818,9 @@ export class WorkflowService {
                 // sweep those unrelated edits into our "preserve roles.yaml" commit under the
                 // wrong author/message. Feature branch → the protected-branch gate doesn't
                 // fire, so this commits cleanly. Then publish so the merge sees the
-                // neutralised source. A non-fast-forward push (the source advanced under us)
-                // throws → RolesYamlPreservationError → the merge aborts, fail-closed.
+                // neutralised source. A push that still fails after the cooperative
+                // pull-rebase throws PushNeedsAgentResolutionError → the merge aborts,
+                // fail-closed, with the restore kept locally for the next push.
                 const committed = await this.git.commitFile(ws.id, user, ROLES_YAML, 'Preserve official roles.yaml (not editable via change request)', true);
                 // We are past the `baseRoles === headRoles` check, so origin/<head> and
                 // origin/<base> DO differ — a restore commit is REQUIRED to protect the
@@ -3153,10 +3829,27 @@ export class WorkflowService {
                 // with origin/<head>), then origin/<head> STILL carries the divergent
                 // roles.yaml and the merge would land it. Treat that as a hard failure —
                 // returning false here would fail OPEN. Fail closed instead.
-                if (!committed) {
+                //
+                // One shape of "nothing to commit" is not out of sync: a restore an
+                // earlier merge attempt committed, whose push the host refused. The
+                // clone's HEAD already carries the base version — that is why there
+                // was nothing new to commit — and only the push is owed. Without this,
+                // the retry the refusal promises could never succeed: every attempt
+                // would find the file already restored and stop here, and the merge
+                // would stay refused until some unrelated save pushed the branch.
+                //
+                // The question is NOT "does the clone hold unpushed commits" — any
+                // queued save answers yes. It is whether HEAD already holds all of
+                // origin/<head>, so that the push fast-forwards origin to a head whose
+                // roles.yaml is the base version. A clone BEHIND origin would have
+                // origin's divergent copy rebased into HEAD by the cooperative pull on
+                // the way to the push, and the merge would land it: that clone is the
+                // out-of-sync one this guard refuses. A probe that cannot answer
+                // throws, and the guard fails closed with it.
+                if (!committed && !(await this.git.headContainsOrigin(ws.id))) {
                     throw new Error('roles.yaml restore produced no commit while origin still diverges from base — source workspace out of sync; refusing to merge');
                 }
-                await this.trackedPush(ws.id, user);
+                await this.pushWithRecovery(ws.id, headBranch, ROLES_YAML, user);
                 this.accessControl.invalidate(ws.id);
                 return true;
             }
@@ -3167,6 +3860,13 @@ export class WorkflowService {
             }
         }
         catch (err) {
+            // A refused push: the restore is committed on the source locally and the
+            // merge does not run (origin still carries the divergent roles.yaml).
+            // Answer it like every other refused push — 409, the saved-locally
+            // sentence, the banner already raised — so the merge can be retried
+            // once the host accepts the push.
+            if (err instanceof PushNeedsAgentResolutionError)
+                throw err;
             const detail = err instanceof Error ? err.message : String(err);
             // Log the raw git/push detail server-side; the thrown error keeps it OFF
             // the client-facing 502 message (see RolesYamlPreservationError).