@bevel-software/platform-core-backend 0.4.0 → 0.5.0

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

@@ -23,9 +23,11 @@ import { promisify } from 'node:util';
 import { isProtectedBranch } from '@bevel-software/platform-shared';
 import { and, eq } from 'drizzle-orm';
 import { changeRequests } from '../database/schema.js';
+import { workspaceIdForBranch } from '../workspace/workspace.service.js';
 import { WorkflowHooks } from './workflow-hooks.js';
+import { WorkspaceMutex } from './git/mutex.js';
 import { hashEmail } from '../../shared/hash-email.js';
-import { ChangeRequestConflictsError, DuplicateChangeRequestError, RolesYamlPreservationError, PullRebaseConflictError, PushNeedsAgentResolutionError, WorkflowValidationError, } from './workflow.errors.js';
+import { ChangeRequestConflictsError, DuplicateChangeRequestError, RolesYamlPreservationError, PullRebaseConflictError, PushNeedsAgentResolutionError, WorkflowDomainError, WorkflowValidationError, } from './workflow.errors.js';
 import { RECOVERY_BOT_EMAIL, RECOVERY_BOT_NAME } from './recovery-bot.js';
 import { AccessDeniedError } from '../access/access-errors.js';
 const execFileAsync = promisify(execFile);
@@ -221,8 +223,53 @@ export class WorkflowService {
     createBranch(workspaceId, name, fromBase) {
         return this.git.createBranch(workspaceId, name, fromBase);
     }
-    deleteBranch(workspaceId, name, user, opts) {
-        return this.git.deleteBranch(workspaceId, name, user, opts);
+    /**
+     * Serialises everything that decides a branch's fate — opening a change
+     * request from it, deleting it, retiring it after a merge — by branch
+     * name. Without it, `retireMergedSourceBranch`'s check-then-delete could
+     * interleave with `openChangeRequest`'s check-then-insert (which spans a
+     * multi-second auto-merge and push) and delete a branch a request was
+     * being opened from. In-process only, which matches the deployment model:
+     * one server process owns the workspaces directory.
+     */
+    branchLifecycle = new WorkspaceMutex();
+    async deleteBranch(workspaceId, name, user, opts) {
+        return this.branchLifecycle.run(`branch:${name}`, async () => {
+            // A branch backing an OPEN change request is load-bearing: deleting it
+            // strands the request (and, in the propose flow's reset-on-reuse, would
+            // let one tab wipe the branch another tab just proposed from). The
+            // 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.
+            if (!opts?.systemCleanup && !opts?.onlyIfNoRemote) {
+                const open = await this.db
+                    .select({ number: changeRequests.number })
+                    .from(changeRequests)
+                    .where(and(eq(changeRequests.sourceBranch, name), eq(changeRequests.state, 'open')))
+                    .limit(1);
+                if (open.length > 0) {
+                    throw new WorkflowValidationError(`Branch "${name}" has an open change request (#${open[0].number}) — withdraw or decline it before deleting the branch.`);
+                }
+            }
+            await this.deleteBranchUnlocked(workspaceId, name, user, opts);
+        });
+    }
+    /** The deletion itself — callers must hold the branch-lifecycle lock. */
+    async deleteBranchUnlocked(workspaceId, name, user, opts) {
+        await this.git.deleteBranch(workspaceId, name, user, opts);
+        // 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
+        // `.git`), resurrecting the deleted branch's content under a fresh ref.
+        try {
+            const branchWorkspaceId = workspaceIdForBranch(name);
+            if (await this.workspaceService.hasBootstrappedWorkspace(branchWorkspaceId)) {
+                await this.workspaceService.deleteWorkspace(branchWorkspaceId);
+            }
+        }
+        catch (err) {
+            console.warn(`[workflow] could not retire workspace clone of deleted branch "${name}":`, err);
+        }
     }
     // No `switchBranch` here on purpose. Under the per-branch workspace model,
     // switching branches is a frontend navigation that triggers a workspace
@@ -269,10 +316,13 @@ export class WorkflowService {
      * `needs_attention` row: once the ladder has escalated to a human, more
      * agent runs on the same divergence are just a loop.
      *
-     * One row, first conflicted path as the representative: the recovery
+     * One row, smallest conflicted path as the representative: the recovery
      * agent's job is "bring the BRANCH into a pushable state", so one ladder
      * per divergence — not one per conflicted file, which would multiply
-     * agent runs for a single underlying conflict.
+     * agent runs for a single underlying conflict. Sorted so the choice is
+     * stable across retries regardless of how the caller ordered the paths —
+     * a shifting representative would slip past `enqueueIfAbsent`'s
+     * per-(workspace, branch, path) dedup and start a second ladder.
      *
      * Best-effort by design — the caller is already surfacing the conflict
      * error; a queue hiccup must not mask it.
@@ -282,7 +332,7 @@ export class WorkflowService {
             const queued = await this.pendingCommits.enqueueIfAbsent({
                 workspaceId,
                 branch: err.branch,
-                path: err.conflictedPaths[0],
+                path: [...err.conflictedPaths].sort()[0],
                 authorEmail: user?.email ?? RECOVERY_BOT_EMAIL,
                 authorName: user?.name ?? RECOVERY_BOT_NAME,
             });
@@ -337,15 +387,20 @@ export class WorkflowService {
     listChangesForFile(workspaceId, path, limit) {
         return this.git.logForFile(workspaceId, path, limit);
     }
-    revertChange(workspaceId, user, sha) {
-        return this.git.revertCommit(workspaceId, user, sha);
-    }
     compareFile(workspaceId, path, fromBranch, toBranch) {
         return this.git.diffFileBetweenBranches(workspaceId, path, fromBranch, toBranch);
     }
     showFileAtChange(workspaceId, path, sha) {
         return this.git.diffFileAtCommit(workspaceId, path, sha);
     }
+    /**
+     * Before/after file contents for one commit (`<sha>^` vs `<sha>`). Powers
+     * the rendered-markdown history view; `showFileAtChange` keeps serving the
+     * raw-patch view for non-markdown files.
+     */
+    fileAtChange(workspaceId, path, sha) {
+        return this.git.fileContentsAtCommit(workspaceId, path, sha);
+    }
     /**
      * Resolve write permission for `targetPath` against the access tree at
      * `HEAD` of `branch`. Throws `AccessDeniedError` on denial with the
@@ -581,7 +636,7 @@ export class WorkflowService {
      * retry, hand off to the recovery agent, or escalate. Emits
      * `file-changed` on success so frontends see the new sha.
      */
-    async runPendingCommit(workspaceId, branch, targetPath, user) {
+    async runPendingCommit(workspaceId, branch, targetPath, user, opts) {
         const change = await this.git.commitFile(workspaceId, user, targetPath);
         if (!change) {
             // No-op commit — the path was already clean. Usually a double-enqueue
@@ -597,11 +652,11 @@ export class WorkflowService {
             // and the worker's ladder takes over). Nothing to emit either way —
             // there's no new sha.
             if (await this.git.hasUnpushedCommits(workspaceId)) {
-                await this.pushWithRecovery(workspaceId, branch, targetPath, user);
+                await this.pushWithRecovery(workspaceId, branch, targetPath, user, opts);
             }
             return;
         }
-        await this.pushWithRecovery(workspaceId, branch, targetPath, user);
+        await this.pushWithRecovery(workspaceId, branch, targetPath, user, opts);
         this.events?.emit({
             kind: 'file-changed',
             workspaceId,
@@ -621,9 +676,9 @@ export class WorkflowService {
      * still fails." The full rationale lives at the call site in
      * `releaseLock`; this method is the de-duplicated body.
      */
-    async pushWithRecovery(workspaceId, branch, targetPath, user) {
+    async pushWithRecovery(workspaceId, branch, targetPath, user, opts) {
         try {
-            await this.git.push(workspaceId, user);
+            await this.git.push(workspaceId, user, opts);
         }
         catch (firstPushErr) {
             const firstDetail = firstPushErr instanceof Error ? firstPushErr.message : String(firstPushErr);
@@ -633,7 +688,7 @@ export class WorkflowService {
             if (looksLikeNonFastForward) {
                 try {
                     await this.git.pull(workspaceId);
-                    await this.git.push(workspaceId, user);
+                    await this.git.push(workspaceId, user, opts);
                     recovered = true;
                     console.log(`[workflow] non-fast-forward push recovered via pull --rebase for workspace=${workspaceId} branch=${branch} path=${targetPath}`);
                 }
@@ -714,8 +769,8 @@ export class WorkflowService {
     listChangeRequests(opts) {
         return this.prs.listOpenPrs(opts);
     }
-    listChangeRequestsAuthoredBy(emailOrLogin) {
-        return this.prs.listPrsAuthoredBy(emailOrLogin);
+    listChangeRequestsAuthoredBy(emailOrLogin, opts) {
+        return this.prs.listPrsAuthoredBy(emailOrLogin, opts);
     }
     listChangeRequestsForUser(workspaceId, email, opts) {
         return this.prs.listPrsForOwnerEmail(workspaceId, email, opts);
@@ -758,103 +813,111 @@ export class WorkflowService {
         if (isProtectedBranch(input.sourceBranch)) {
             throw new WorkflowValidationError(`Cannot open a change request *from* a protected branch ("${input.sourceBranch}").`, { kind: 'source-is-protected', sourceBranch: input.sourceBranch });
         }
-        // Uniqueness rule — A→B blocks A→B (the spec is explicit that B→A in
-        // parallel is still allowed). `listOpenPrs` is cached for 30s so we
-        // force-fresh to catch a CR that opened just now.
-        const openCrs = await this.prs.listOpenPrs({ fresh: true });
-        const duplicate = openCrs.find((cr) => cr.branch === input.sourceBranch && cr.base === input.targetBranch);
-        if (duplicate) {
-            throw new DuplicateChangeRequestError(input.sourceBranch, input.targetBranch, duplicate.number);
-        }
-        // Auto-merge target → source. `mergeFromOrigin` enforces "current
-        // branch == source" and "clean working tree" before attempting; both
-        // failures surface as structured workflow errors that pass straight
-        // through to the caller.
-        const mergeOutcome = await this.git.mergeFromOrigin(workspaceId, input.sourceBranch, input.targetBranch, user);
-        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.git.push(workspaceId, user);
-        const workspacePath = await this.workspaceService.getWorkspacePath(workspaceId);
-        const cwd = path.join(workspacePath, this.kbDirName);
-        // Touched paths between target and source — basis for the
-        // affected-owners block we append to the CR body. We compute it
-        // ourselves rather than waiting for GitHub to expose `pr.files`
-        // (which only populates after the PR exists). Three-dot range
-        // matches what `gh pr create` will eventually show as the diff.
-        const touchedPaths = await this.listChangedPathsBetweenBranches(cwd, input.targetBranch, input.sourceBranch);
-        const affectedOwnersBlock = await this.buildAffectedOwnersBlock(workspaceId, input.targetBranch, touchedPaths);
-        // The change request is a plain DB row now — no provider PR. Author is a
-        // real column (no hidden body marker needed, since nothing runs as a shared
-        // service account anymore).
-        const description = input.description?.trim() ?? '';
-        const body = [description, affectedOwnersBlock].filter((s) => s.length > 0).join('\n\n');
-        let prNumber;
-        try {
-            const [row] = await this.db
-                .insert(changeRequests)
-                .values({
-                sourceBranch: input.sourceBranch,
-                targetBranch: input.targetBranch,
-                title: input.title.trim(),
-                body,
-                authorEmail: user.email.trim().toLowerCase(),
-                authorName: user.name,
-            })
-                .returning({ number: changeRequests.number });
-            prNumber = row.number;
-        }
-        catch (err) {
-            // The partial unique index (source, target WHERE state='open') is the
-            // race-proof backstop for the pre-check above: a concurrent open of the
-            // same pair lands here. Surface it as the same duplicate error, with the
-            // winning CR's number. Any OTHER unique violation (e.g. the identity
-            // `change_requests_number_unq`) is a genuine integrity fault and falls
-            // through to the generic path below rather than being mislabeled.
-            if (isOpenPairViolation(err)) {
-                const [existing] = await this.db
-                    .select({ number: changeRequests.number })
-                    .from(changeRequests)
-                    .where(and(eq(changeRequests.sourceBranch, input.sourceBranch), eq(changeRequests.targetBranch, input.targetBranch), eq(changeRequests.state, 'open')))
-                    .limit(1);
-                // Normally the conflicting open CR is right there. If it vanished (the
-                // rival was merged/closed in the microsecond between the conflict and
-                // this re-query), don't fabricate a #0 — report it as a transient race.
-                if (!existing) {
-                    throw new WorkflowValidationError(`Change request for "${input.sourceBranch}" → "${input.targetBranch}" ` +
-                        'raced with a concurrent open/close; retry.', { kind: 'open-change-request-failed' });
+        // The whole open sequence — uniqueness check through row insert — runs
+        // under the source branch's lifecycle lock. `retireMergedSourceBranch`
+        // takes the same lock around its own check-then-delete, so a merge
+        // cleanup can never race into the multi-second gap between this
+        // method's "no open request" answer and its row landing, and delete the
+        // branch out from under a request being opened.
+        return this.branchLifecycle.run(`branch:${input.sourceBranch}`, async () => {
+            // Uniqueness rule — A→B blocks A→B (the spec is explicit that B→A in
+            // parallel is still allowed). `listOpenPrs` is cached for 30s so we
+            // force-fresh to catch a CR that opened just now.
+            const openCrs = await this.prs.listOpenPrs({ fresh: true });
+            const duplicate = openCrs.find((cr) => cr.branch === input.sourceBranch && cr.base === input.targetBranch);
+            if (duplicate) {
+                throw new DuplicateChangeRequestError(input.sourceBranch, input.targetBranch, duplicate.number);
+            }
+            // Auto-merge target → source. `mergeFromOrigin` enforces "current
+            // branch == source" and "clean working tree" before attempting; both
+            // failures surface as structured workflow errors that pass straight
+            // through to the caller.
+            const mergeOutcome = await this.git.mergeFromOrigin(workspaceId, input.sourceBranch, input.targetBranch, user);
+            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.git.push(workspaceId, user);
+            const workspacePath = await this.workspaceService.getWorkspacePath(workspaceId);
+            const cwd = path.join(workspacePath, this.kbDirName);
+            // Touched paths between target and source — basis for the
+            // affected-owners block we append to the CR body. We compute it
+            // ourselves rather than waiting for GitHub to expose `pr.files`
+            // (which only populates after the PR exists). Three-dot range
+            // matches what `gh pr create` will eventually show as the diff.
+            const touchedPaths = await this.listChangedPathsBetweenBranches(cwd, input.targetBranch, input.sourceBranch);
+            const affectedOwnersBlock = await this.buildAffectedOwnersBlock(workspaceId, input.targetBranch, touchedPaths);
+            // The change request is a plain DB row now — no provider PR. Author is a
+            // real column (no hidden body marker needed, since nothing runs as a shared
+            // service account anymore).
+            const description = input.description?.trim() ?? '';
+            const body = [description, affectedOwnersBlock].filter((s) => s.length > 0).join('\n\n');
+            let prNumber;
+            try {
+                const [row] = await this.db
+                    .insert(changeRequests)
+                    .values({
+                    sourceBranch: input.sourceBranch,
+                    targetBranch: input.targetBranch,
+                    title: input.title.trim(),
+                    body,
+                    authorEmail: user.email.trim().toLowerCase(),
+                    authorName: user.name,
+                })
+                    .returning({ number: changeRequests.number });
+                prNumber = row.number;
+            }
+            catch (err) {
+                // The partial unique index (source, target WHERE state='open') is the
+                // race-proof backstop for the pre-check above: a concurrent open of the
+                // same pair lands here. Surface it as the same duplicate error, with the
+                // winning CR's number. Any OTHER unique violation (e.g. the identity
+                // `change_requests_number_unq`) is a genuine integrity fault and falls
+                // through to the generic path below rather than being mislabeled.
+                if (isOpenPairViolation(err)) {
+                    const [existing] = await this.db
+                        .select({ number: changeRequests.number })
+                        .from(changeRequests)
+                        .where(and(eq(changeRequests.sourceBranch, input.sourceBranch), eq(changeRequests.targetBranch, input.targetBranch), eq(changeRequests.state, 'open')))
+                        .limit(1);
+                    // Normally the conflicting open CR is right there. If it vanished (the
+                    // rival was merged/closed in the microsecond between the conflict and
+                    // this re-query), don't fabricate a #0 — report it as a transient race.
+                    if (!existing) {
+                        throw new WorkflowValidationError(`Change request for "${input.sourceBranch}" → "${input.targetBranch}" ` +
+                            'raced with a concurrent open/close; retry.', { kind: 'open-change-request-failed' });
+                    }
+                    throw new DuplicateChangeRequestError(input.sourceBranch, input.targetBranch, existing.number);
                 }
-                throw new DuplicateChangeRequestError(input.sourceBranch, input.targetBranch, existing.number);
+                // Non-uniqueness failure AFTER the auto-merge + push already advanced the
+                // source branch: no `change_requests` row was created, but the source now
+                // carries the auto-merge commit. This is safely retryable — re-running
+                // openChangeRequest finds no duplicate, re-runs the (idempotent, already
+                // up-to-date) auto-merge, and inserts the row.
+                const rawMsg = err instanceof Error ? err.message : String(err);
+                throw new WorkflowValidationError(`Failed to open change request: ${redactTokens(rawMsg)}`, { kind: 'open-change-request-failed' });
             }
-            // Non-uniqueness failure AFTER the auto-merge + push already advanced the
-            // source branch: no `change_requests` row was created, but the source now
-            // carries the auto-merge commit. This is safely retryable — re-running
-            // openChangeRequest finds no duplicate, re-runs the (idempotent, already
-            // up-to-date) auto-merge, and inserts the row.
-            const rawMsg = err instanceof Error ? err.message : String(err);
-            throw new WorkflowValidationError(`Failed to open change request: ${redactTokens(rawMsg)}`, { kind: 'open-change-request-failed' });
-        }
-        this.prs.invalidateDetailCache(prNumber);
-        const detail = await this.prs.getPrDetail(prNumber, {
-            fresh: true,
-            workspaceId,
-            viewerEmail: user.email,
-        });
-        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.prs.invalidateDetailCache(prNumber);
+            const detail = await this.prs.getPrDetail(prNumber, {
+                fresh: true,
+                workspaceId,
+                viewerEmail: user.email,
+            });
+            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,
+            });
+            return detail;
         });
-        return detail;
     }
     /**
      * Refresh an existing change request from its target — re-runs the
@@ -937,6 +1000,164 @@ export class WorkflowService {
         });
         return approvals;
     }
+    /**
+     * Decline ONE file of an open change request: restore its merge-base
+     * version on the SOURCE branch (commit + push), so the file drops out of
+     * the request's three-dot diff — the same mechanics
+     * `preserveBaseRolesYaml` uses to neutralise roles.yaml, offered as a
+     * reviewer's verb. Accept-or-revert per file is how a reviewer takes the
+     * good half of a proposal without rejecting the whole thing.
+     *
+     * Authority: exactly the approval predicate — an eligible approver for the
+     * file per the access tree on `origin/<base>`. Declining takes the same
+     * permission as accepting.
+     *
+     * When the LAST file is reverted the request proposes nothing: it closes
+     * itself and its source branch is retired, exactly as a merge would have
+     * retired it — a shell of a request pointing at an empty diff serves
+     * nobody (see the zero-files dialog state this replaces).
+     */
+    async revertChangeRequestFile(number, user, repoRelPath) {
+        const summary = await this.prs.getPr(number);
+        if (!summary)
+            throw new WorkflowDomainError('change request not found', 404);
+        if (summary.state !== 'open') {
+            throw new WorkflowDomainError('This change request is no longer open.', 422);
+        }
+        const baseBranch = summary.base;
+        const headBranch = summary.branch;
+        const ws = await this.workspaceService.getOrCreateForBranch(headBranch);
+        // 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.git.pull(ws.id).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)) {
+            throw new WorkflowDomainError('That file is not part of this change request.', 422);
+        }
+        const canApprove = await this.accessControl.canWriteAtRef(ws.id, `origin/${baseBranch}`, user.email, repoRelPath);
+        if (canApprove !== true) {
+            throw new WorkflowDomainError('Only an eligible approver of this file can revert it — declining takes the same permission as accepting.', 403);
+        }
+        const mergeBase = await this.git.mergeBaseForPr(ws.id, baseBranch, headBranch);
+        if (!mergeBase) {
+            throw new WorkflowDomainError('These branches share no history to revert to.', 422);
+        }
+        // Same per-file lock every other editor of this path takes — a concurrent
+        // save must not race the restore between write and commit.
+        const lockPath = `${this.kbDirName}/${repoRelPath}`;
+        const lock = await this.fileLocks.acquire(ws.id, headBranch, lockPath, user);
+        if (!lock.acquired) {
+            throw new WorkflowDomainError(`${repoRelPath} is being edited by ${lock.lock.holderName} — try again once the edit settles.`, 409);
+        }
+        try {
+            await this.git.restorePathFromRef(ws.id, mergeBase, repoRelPath);
+            await this.git.commitFile(ws.id, user, repoRelPath, `Revert ${repoRelPath} (declined in change request #${number})`, true);
+            await this.git.push(ws.id, user);
+        }
+        finally {
+            // Committed inline — drop the lock row directly rather than enqueueing
+            // a duplicate commit through releaseLock.
+            await this.fileLocks.release(ws.id, headBranch, lockPath, user);
+        }
+        this.prs.invalidateDetailCache(number);
+        const remaining = await this.git.changedPathsForPr(ws.id, baseBranch, headBranch);
+        if (remaining.length > 0) {
+            return { closed: false, remainingPaths: remaining };
+        }
+        // Every change declined → the request proposes nothing.
+        await this.closeEmptyChangeRequest(number, user);
+        return { closed: true, remainingPaths: [] };
+    }
+    /**
+     * DELETE a change request outright: close it (whatever its diff says) and
+     * retire its source branch — the request, its proposal, and the branch that
+     * carried it are gone in one verb. Admin-only, resolved the same way every
+     * other admin check here is (write on `roles.yaml` at `origin/<base>`,
+     * never a local ref): this is the moderation verb for a shared deployment,
+     * stronger than reject (which the author or the files' owners can do, and
+     * which leaves the branch for a second round).
+     */
+    async deleteChangeRequest(number, user) {
+        const summary = await this.prs.getPr(number);
+        if (!summary)
+            throw new WorkflowDomainError('change request not found', 404);
+        if (summary.state === 'merged') {
+            throw new WorkflowDomainError('This change request has already been applied.', 422);
+        }
+        const ws = await this.workspaceService.getOrCreateForBranch(summary.base);
+        await this.workspaceService.ensureRemotesFetched(ws.id).catch(() => undefined);
+        const isAdmin = await this.accessControl.canWriteAtRef(ws.id, `origin/${summary.base}`, user.email, 'roles.yaml');
+        if (isAdmin !== true) {
+            throw new WorkflowDomainError('Only an admin can delete a change request.', 403);
+        }
+        // Close first (idempotent: an already-closed request just skips to the
+        // branch retirement). Guarded on `open` so a concurrent merge wins.
+        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) {
+            this.prs.invalidateDetailCache(number);
+            this.events?.emit({ kind: 'change-request-rejected', number });
+        }
+        else {
+            const fresh = await this.prs.getPr(number);
+            if (fresh?.state === 'merged') {
+                throw new WorkflowDomainError('This change request has already been applied.', 422);
+            }
+        }
+        await this.retireMergedSourceBranch(number, summary.base, user);
+    }
+    /**
+     * Close an open change request whose diff has EMPTIED — everything it
+     * proposed has since landed on the target, been reverted, or been undone on
+     * its own branch — and retire its source branch, exactly as a merge would
+     * have. A request pointing at an empty diff serves nobody: reviewers never
+     * see it (zero touched paths routes to no one) and the author sees a shell.
+     *
+     * Called after the last per-file revert, and as a lazy reconcile whenever a
+     * detail read observes an open request with no files (the join-requests
+     * pattern: derived state, settled on observation). The emptiness check here
+     * is AUTHORITATIVE — recomputed, and a diff failure aborts rather than
+     * closes, so a transient git error can never eat a live request.
+     *
+     * 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;
+        try {
+            const ws = await this.workspaceService.getOrCreateForBranch(summary.branch);
+            paths = await this.git.changedPathsForPr(ws.id, summary.base, summary.branch);
+        }
+        catch (err) {
+            console.warn(`[cr] empty-check for change request #${number} failed — leaving it open:`, err);
+            return false;
+        }
+        if (paths.length > 0)
+            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);
+        return true;
+    }
     /**
      * Reject (close-without-merging) a change request. Per PLAN.md spec, the
      * authorized set is:
@@ -1050,25 +1271,83 @@ export class WorkflowService {
         // this a read right after a merge misses the just-merged change. Best-effort:
         // the merge already succeeded on origin, so a pull hiccup must not fail the
         // response (a later fetch/pull reconciles).
+        let targetWorkspaceId;
         try {
             const targetWorkspace = await this.workspaceService.getOrCreateForBranch(baseBranch);
+            targetWorkspaceId = targetWorkspace.id;
             await this.git.pull(targetWorkspace.id);
         }
         catch (err) {
             // Still best-effort for the merge response (the merge already landed
             // on origin) — but a rebase CONFLICT here means the target workspace
             // is stranded (local commits vs origin, never self-heals), so queue
-            // the background recovery ladder before shrugging.
-            if (err instanceof PullRebaseConflictError) {
-                const targetWorkspaceId = encodeURIComponent(baseBranch);
+            // the background recovery ladder before shrugging. A conflict can
+            // only have come from the pull, so the workspace id is always set on
+            // this arm — the guard just satisfies the narrowing.
+            if (err instanceof PullRebaseConflictError && targetWorkspaceId) {
                 await this.queuePullConflictRecovery(targetWorkspaceId, err, user);
             }
             console.warn(`[merge] post-merge pull of target "${baseBranch}" failed — its workspace may be momentarily behind origin`, err);
         }
         this.prs.invalidateDetailCache(number);
         this.events?.emit({ kind: 'change-request-merged', number });
+        // 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);
         return { kind: 'merged', result };
     }
+    /**
+     * Best-effort retirement of a merged change request's source branch — the
+     * standard "delete branch on merge" a git host performs, done here because
+     * this app IS the host. Everything the branch carried is on the target
+     * now, and leaving it behind has a real cost: the propose flow REUSES an
+     * existing branch by name, so a leftover base goes stale against the
+     * target and seeds the next proposal with outdated text (or, worse,
+     * re-proposes withdrawn commits).
+     *
+     * Refuses quietly when the branch is protected or still carries another
+     * OPEN request. Runs from the TARGET's workspace (guaranteed not to be
+     * checked out on the branch being deleted) with `systemCleanup`, since the
+     * merger need not be the branch's author — the merge itself was the
+     * authorization. Never throws: the merge has already succeeded, and a
+     * cleanup failure only means the next proposal falls back to branch reuse.
+     */
+    async retireMergedSourceBranch(number, baseBranch, user) {
+        try {
+            const rows = await this.db
+                .select({ sourceBranch: changeRequests.sourceBranch })
+                .from(changeRequests)
+                .where(eq(changeRequests.number, number))
+                .limit(1);
+            const sourceBranch = rows[0]?.sourceBranch;
+            if (!sourceBranch || isProtectedBranch(sourceBranch))
+                return;
+            // The open-check and the deletion hold the branch's lifecycle lock
+            // TOGETHER — `openChangeRequest` holds the same lock across its own
+            // check-then-insert, so a request being opened from this branch either
+            // lands its row before the check below (retirement backs off) or waits
+            // until retirement finishes (and fails loudly on the missing branch,
+            // retryable, instead of losing the branch mid-open).
+            await this.branchLifecycle.run(`branch:${sourceBranch}`, async () => {
+                const stillOpen = await this.db
+                    .select({ number: changeRequests.number })
+                    .from(changeRequests)
+                    .where(and(eq(changeRequests.sourceBranch, sourceBranch), eq(changeRequests.state, 'open')))
+                    .limit(1);
+                if (stillOpen.length > 0)
+                    return;
+                const targetWs = await this.workspaceService.getOrCreateForBranch(baseBranch);
+                // The remote-tracking ref must be current, or deleteBranch's
+                // "does origin still have it?" probe skips the remote delete.
+                await this.workspaceService.ensureRemotesFetched(targetWs.id).catch(() => { });
+                await this.deleteBranchUnlocked(targetWs.id, sourceBranch, user, { systemCleanup: true });
+                console.log(`[merge] retired merged source branch "${sourceBranch}"`);
+            });
+        }
+        catch (err) {
+            console.warn(`[merge] could not retire the merged source branch of change request #${number} (non-fatal):`, err);
+        }
+    }
     /**
      * Guarantee a CR carries NO `roles.yaml` change across its merge: if the CR's
      * `roles.yaml` differs from the base branch's, restore the base version on the