@bevel-software/platform-core-backend 0.14.0 → 0.19.0

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

@@ -17,23 +17,35 @@
  * those backings land.
  */
 import path from 'node:path';
+import { logger } from '../../shared/logging.js';
+// One logger per tag this file has always written under, so a line's prefix
+// is unchanged for a reader and its `module` field is exact for a filter.
+const log = logger('workflow');
+const syncLog = logger('sync');
+const lockLog = logger('lock');
+const crLog = logger('cr');
+const mergeLog = logger('merge');
 import { promises as fs } from 'node:fs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { isProtectedBranch, DEFAULT_BRANCH } from '@bevel-software/platform-shared';
-import { and, eq, or } from 'drizzle-orm';
+import { isProtectedBranch, DEFAULT_BRANCH, isFolderPlaceholder, folderPlaceholderPath, isPlatformRestoreShape, } from '@bevel-software/platform-shared';
+import { and, eq, inArray, isNotNull, isNull, lt, or } from 'drizzle-orm';
 import { changeRequests } from '../database/schema.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
+import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
 import { sanitizeError } from './sanitize-error.js';
 import { WorkflowHooks } from './workflow-hooks.js';
 import { WorkspaceMutex } from '../kb-fs/mutex.js';
-import { hashEmail } from '../../shared/hash-email.js';
-import { ChangeRequestConflictsError, DuplicateChangeRequestError, RolesYamlPreservationError, PullRebaseConflictError, PushNeedsAgentResolutionError, WorkflowDomainError, WorkflowValidationError, } from '../../shared/domain-errors.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 { RECOVERY_BOT_EMAIL, RECOVERY_BOT_NAME } from './recovery-bot.js';
 import { AccessDeniedError } from '../access-model/access-errors.js';
+import { printable } from '../../shared/printable.js';
 const execFileAsync = promisify(execFile);
 /** The partial unique index that enforces one OPEN change request per (source, target) pair. */
 const OPEN_PAIR_CONSTRAINT = 'change_requests_open_pair_unq';
+/** Cap on a persisted apply refusal — long enough to name the files a gate waits on. */
+const APPLY_FAILURE_MAX_LEN = 1000;
 /**
  * True only for a Postgres unique violation (23505) on the open-CR-per-pair
  * index. `change_requests` also carries `change_requests_number_unq` on its
@@ -58,6 +70,28 @@ function isOpenPairViolation(err) {
     const message = fieldOf(err, 'message') ?? fieldOf(cause, 'message');
     return typeof message === 'string' && message.includes(OPEN_PAIR_CONSTRAINT);
 }
+/**
+ * The one sentence a remote-sync conflict is reported with — in the sync
+ * response, on the branch's banner and in the log — so whoever sees any of
+ * the three reads the same thing: which branch, which files, that automatic
+ * recovery is under way, and what to do if it does not clear.
+ */
+export function syncConflictMessage(branch, conflictedPaths) {
+    // Bounded: the same sentence goes to the response, the banner and the log,
+    // and it must be one sentence in all three whatever the conflict's size.
+    // The full path list rides beside it as `conflictedPaths`.
+    const shown = conflictedPaths.slice(0, SYNC_CONFLICT_FILES_NAMED);
+    const more = conflictedPaths.length - shown.length;
+    const files = conflictedPaths.length === 0
+        ? 'some files'
+        : more > 0
+            ? `${shown.join(', ')} and ${more} more file${more === 1 ? '' : 's'}`
+            : shown.join(', ');
+    return (`${branch} is not in sync yet: ${files} changed both in Hexis and on the git host. ` +
+        `Recovery is queued; if this stays, open the files on ${branch} in Hexis, keep what you want, and save.`);
+}
+/** How many conflicted files the sync-conflict sentence names before "and N more". */
+const SYNC_CONFLICT_FILES_NAMED = 3;
 /** Redact the shared GitHub token from any error string before surfacing it. */
 function redactTokens(msg) {
     const tokens = [process.env.GITHUB_TOKEN, process.env.GH_TOKEN].filter((t) => !!t && t.length > 0);
@@ -77,7 +111,9 @@ const formatWriter = (u) => u.name ? `${u.name} <${u.email}>` : u.email;
  * the overflow is collapsed into a single deduped summary of every eligible
  * approver across the change. This keeps the body bounded regardless of how
  * many files the change touches (see {@link MAX_AFFECTED_PATHS_LISTED}).
- * Returns '' when no path has resolvable eligibility.
+ * Returns '' when no path has resolvable eligibility. The empty-folder
+ * placeholder is never listed or counted: it is not content, and no one
+ * reviews it.
  */
 export function formatAffectedOwnersBlock(paths, resolved, maxListed = MAX_AFFECTED_PATHS_LISTED) {
     const listed = [];
@@ -85,6 +121,8 @@ export function formatAffectedOwnersBlock(paths, resolved, maxListed = MAX_AFFEC
     const allUsers = new Map(); // email -> display, deduped
     let eligible = 0;
     for (const p of paths) {
+        if (isFolderPlaceholder(p))
+            continue;
         const info = resolved.get(p);
         if (!info)
             continue;
@@ -116,6 +154,26 @@ export function formatAffectedOwnersBlock(paths, resolved, maxListed = MAX_AFFEC
     }
     return out.join('\n');
 }
+/** Git commit subjects are capped at 200 characters (`GitService.commitFile`). */
+const MAX_COMMIT_SUBJECT = 200;
+/**
+ * A commit subject that always fits: `full` when it does, else `short` (the
+ * file's name instead of its path, a count instead of every request), cut to
+ * the cap as a last resort. A long path or many requests on one branch must
+ * never fail the commit — and with it the whole folder removal.
+ */
+function commitSubject(full, short) {
+    if (full.length <= MAX_COMMIT_SUBJECT)
+        return full;
+    if (short.length <= MAX_COMMIT_SUBJECT)
+        return short;
+    return `${short.slice(0, MAX_COMMIT_SUBJECT - 1)}…`;
+}
+const basenameOf = (repoRelPath) => repoRelPath.split('/').pop() ?? repoRelPath;
+/** `Docs/Sub` and `Docs/Sub/` both → `Docs/Sub/`: a prefix that cannot match `Docs/Subway`. */
+function folderPrefix(folder) {
+    return `${folder.replace(/\/+$/, '')}/`;
+}
 export class WorkflowService {
     db;
     git;
@@ -126,6 +184,7 @@ export class WorkflowService {
     fileLocks;
     pendingCommits;
     kbDirName;
+    changeGate;
     events;
     fileChanges;
     hooks;
@@ -157,6 +216,13 @@ export class WorkflowService {
      * See `lock-decoupling-plan.md` for the full design.
      */
     pendingCommits, kbDirName, 
+    /**
+     * The read-before-write gate `acquireLock` asks on every branch (see
+     * `access-model/change-gate.ts`). Required, and checked at construction:
+     * a service without it would let a change land where its author cannot
+     * read, so there is no such service.
+     */
+    changeGate, 
     /**
      * Event bus that fans state changes out to connected SSE sessions.
      * Optional so test harnesses / minimal boots can omit it — emits
@@ -190,9 +256,15 @@ export class WorkflowService {
         this.fileLocks = fileLocks;
         this.pendingCommits = pendingCommits;
         this.kbDirName = kbDirName;
+        this.changeGate = changeGate;
         this.events = events;
         this.fileChanges = fileChanges;
         this.hooks = hooks;
+        // The type already requires it; this holds for a caller the compiler did
+        // not see (plain JavaScript, a positional slip in a harness).
+        if (!changeGate || typeof changeGate.assertMayChange !== 'function') {
+            throw new Error('WorkflowService requires a read-before-write gate (IChangeReadGate)');
+        }
     }
     // ── Branches ──────────────────────────────────────────────────────────────
     /**
@@ -212,17 +284,22 @@ export class WorkflowService {
                 .sweepOrphanedWorkspaces(branches.map((b) => b.name))
                 .then(({ removed }) => {
                 if (removed.length > 0) {
-                    console.log(`[workflow] swept ${removed.length} orphaned workspace(s):`, removed);
+                    log.info(`swept ${removed.length} orphaned workspace(s):`, { removed });
                 }
             })
                 .catch((err) => {
-                console.warn('[workflow] orphan workspace sweep failed:', err);
+                log.warn('orphan workspace sweep failed:', { err });
             });
         }
         return branches;
     }
     createBranch(workspaceId, name, fromBase) {
-        return this.git.createBranch(workspaceId, name, fromBase);
+        // Under the branch's lifecycle lock, like `deleteBranch` and the
+        // retirement of a clone the host deleted: creating a branch is the one
+        // operation that can bring a "gone" branch back, and the retirement's
+        // "still gone on origin?" check is only a guarantee if nothing can
+        // recreate the branch between that check and the delete.
+        return this.branchLifecycle.run(`branch:${name}`, () => this.git.createBranch(workspaceId, name, fromBase));
     }
     /**
      * Serialises everything that decides a branch's fate — opening a change
@@ -339,7 +416,7 @@ export class WorkflowService {
             }
         }
         catch (err) {
-            console.warn(`[workflow] could not retire workspace clone of deleted branch "${name}":`, err);
+            log.warn(`could not retire workspace clone of deleted branch "${name}":`, { err });
         }
     }
     // No `switchBranch` here on purpose. Under the per-branch workspace model,
@@ -361,9 +438,42 @@ export class WorkflowService {
     refreshRemotes(workspaceId) {
         return this.git.fetch(workspaceId);
     }
+    /**
+     * `git pull` on a workspace, plus the one announcement a pull owes the rest
+     * of the process.
+     *
+     * A pull rewrites a working tree without going through the write routes or
+     * the commit pipeline, so it emits neither of the signals those produce —
+     * and the catalogs that scan the DEFAULT branch's tree (skills, tool
+     * manuals, the plugin index) are keyed to exactly that tree. Every path that
+     * pulls the default workspace therefore has to say so, or those catalogs
+     * keep serving the pre-pull scan for the rest of their TTL: a merge landing
+     * an approved skill, the recovery ladder after a non-fast-forward push, and
+     * a user's update-from-remote alike. Routing every pull through here makes
+     * that ONE mechanism — "the default branch's tree changed" — instead of a
+     * separate special case per event. (The remote sync, `syncWorkspaceFromRemote`,
+     * pulls directly: it owes the same announcement to every branch and per
+     * file, and makes it from the same `treeChanged` verdict.)
+     *
+     * Announced only after the pull RESOLVES, and only when it CHANGED the
+     * tree's content: a pull that threw left the tree as it was, and so did an
+     * "already up to date" pull or one that landed only content-identical
+     * commits — dropping every catalog and making every attached browser
+     * refetch its file tree for a change that did not happen buys a re-scan
+     * and nothing else. The pull itself reports the change, since it is the
+     * only code that can observe it under the workspace mutex.
+     */
+    async pullWorkspace(workspaceId) {
+        const { treeChanged } = await this.git.pull(workspaceId);
+        if (treeChanged && branchForWorkspaceId(workspaceId) === DEFAULT_BRANCH) {
+            this.events?.emit({ kind: 'fs-tree-changed', workspaceId, branch: DEFAULT_BRANCH });
+            return true;
+        }
+        return false;
+    }
     async updateFromRemote(workspaceId, user) {
         try {
-            await this.git.pull(workspaceId);
+            await this.pullWorkspace(workspaceId);
         }
         catch (err) {
             if (err instanceof PullRebaseConflictError) {
@@ -372,6 +482,166 @@ export class WorkflowService {
             throw err;
         }
     }
+    async retireRemoteGoneClone(workspaceId) {
+        const branch = branchForWorkspaceId(workspaceId);
+        const id = workspaceIdForBranch(branch);
+        // The lock `createBranch` and `deleteBranch` take: no Hexis operation can
+        // bring this branch back into being while the clone is examined and
+        // removed. The sync's own hold on the clone ended when its outcome was
+        // returned, so the branch is asked about AGAIN here rather than trusted
+        // from then — a recreate that landed in between keeps its clone. A clone
+        // being bootstrapped right now is left alone too: it can only be cloning
+        // a branch that exists, so the retirement is already moot. What remains
+        // is a recreate pushed from OUTSIDE Hexis in the milliseconds between the
+        // origin check and the delete, with a bootstrap starting in that same
+        // window; the next sync of that branch clones it fresh.
+        return this.branchLifecycle.run(`branch:${branch}`, async () => {
+            if (!(await this.workspaceService.hasBootstrappedWorkspace(id)))
+                return false;
+            if (this.workspaceService.isBootstrapInFlight(branch))
+                return false;
+            if (await this.git.remoteBranchExists(branch, branch))
+                return false;
+            await this.workspaceService.deleteWorkspace(id);
+            // Whatever a sync still owed that clone is owed to nothing now.
+            this.owedAnnouncements.delete(id);
+            return true;
+        });
+    }
+    /**
+     * Cap on per-path `file-changed` events one sync announces for a branch.
+     * Past it the tree event alone carries the news — a bulk import that
+     * rewrote hundreds of files would otherwise fan hundreds of events out to
+     * every open browser to say what one refresh says.
+     */
+    static SYNC_FILE_EVENT_CAP = 200;
+    /**
+     * Announcements a sync still OWES, per workspace: a pull landed but the
+     * events for it could not be sent. The pull is not redone on retry — HEAD
+     * has not moved since — so the announcement cannot be re-derived from sha
+     * movement; it is remembered here and delivered by the next sync of that
+     * workspace, merged with whatever that sync finds.
+     */
+    owedAnnouncements = new Map();
+    /**
+     * The latest RUNNING apply attempt per change-request number (see
+     * `beginApplyAttempt`). Entries leave when their attempt ends, so the map
+     * holds only attempts in flight, never every number anyone ever posted.
+     */
+    applyAttempts = new Map();
+    /** Process-wide attempt counter: a token is never reissued, even after its entry leaves. */
+    applyAttemptSeq = 0;
+    async syncWorkspaceFromRemote(workspaceId) {
+        const branch = branchForWorkspaceId(workspaceId);
+        const id = workspaceIdForBranch(branch);
+        // Two spellings of one workspace id are in circulation — the encoded
+        // directory name (`ali%2Fx`, what the clone listing yields) and the
+        // Express-decoded form (`ali/x`, what every HTTP route hands the git
+        // layer) — and the git layer's mutex keys on the raw string. Speaking the
+        // routes' spelling to git is what puts a webhook's rebase in the same
+        // queue as the author's concurrent save on a slashed branch; the event
+        // bus gets the encoded form, which every SSE consumer canonicalises.
+        const gitId = branch;
+        // Every failure below is an OUTCOME, never a throw: the caller runs this
+        // over many clones, and one broken clone must not abort the others.
+        let pulled;
+        try {
+            pulled = await this.git.syncFromRemote(gitId);
+        }
+        catch (err) {
+            if (err instanceof RemoteBranchGoneError) {
+                // Not a failure: the host deleted the branch, so there is nothing to
+                // sync and the caller retires the stale clone. No banner — nobody is
+                // editing a branch that no longer exists. An announcement still owed
+                // for that clone dies with it: a branch recreated under the same name
+                // is a different tree, and replaying the old paths against it would
+                // announce changes that never happened there.
+                this.owedAnnouncements.delete(id);
+                syncLog.info(`branch "${branch}" no longer exists on the host`);
+                return { branch, outcome: 'remote-gone' };
+            }
+            if (err instanceof PullRebaseConflictError) {
+                // Same path as `updateFromRemote`: the rebase was aborted inside
+                // the pull (the clone is exactly what it was) and the divergence goes
+                // to the retry → recovery-agent → escalate ladder, attributed to the
+                // recovery bot since no person triggered this. It is still reported
+                // as a conflict because it is not resolved at request time — the
+                // caller's retry, or the ladder, settles it; the banner clears on the
+                // next clean pull or push.
+                await this.queuePullConflictRecovery(gitId, err);
+                const message = syncConflictMessage(branch, err.conflictedPaths);
+                syncLog.warn(message);
+                this.noteGitSyncFailed(gitId, branch, err, { paths: err.conflictedPaths, message });
+                return { branch, outcome: 'conflict', conflictedPaths: err.conflictedPaths, error: message };
+            }
+            const message = sanitizeError(err);
+            syncLog.warn(`pull failed for branch "${branch}": ${message}`);
+            this.noteGitSyncFailed(gitId, branch, err);
+            return { branch, outcome: 'error', error: message };
+        }
+        // A clean pull is proof origin is reachable and this clone rebases onto
+        // it — the condition a `git-sync-failed` banner on this branch was
+        // waiting for, whether a sync or a push raised it.
+        this.noteGitSyncOk(gitId, branch);
+        const { before, after, treeChanged, changedPaths } = pulled;
+        // What this branch reports about ITS clone is decided by the pull alone:
+        // `updated` when HEAD moved, `up-to-date` otherwise.
+        const outcome = after === null || after === before
+            ? { branch, outcome: 'up-to-date', to: after ?? '' }
+            : { branch, outcome: 'updated', from: before, to: after };
+        // What it ANNOUNCES is what has changed since the last announcement that
+        // was actually delivered: this pull's content change, if any, plus one an
+        // earlier sync landed but could not send. The announcement keys on the
+        // pull's verdict about CONTENT — commits that left the tree identical are
+        // nothing for a browser to refetch or a catalog to drop.
+        const owed = this.owedAnnouncements.get(id);
+        if (!treeChanged && !owed)
+            return outcome;
+        const announce = {
+            after: after ?? owed?.after ?? '',
+            changedPaths: [...new Set([...(owed?.changedPaths ?? []), ...changedPaths])],
+        };
+        try {
+            // Announce the new tree. The tree event alone already refreshes every
+            // open file explorer and, on the default branch, drops the skill / tool /
+            // plugin catalogues (`catalog-cache-invalidation.ts`); the CR list
+            // caches the touched paths it resolved against the old tree, so drop
+            // that too.
+            this.prs.invalidateListCache();
+            this.events?.emit({ kind: 'fs-tree-changed', workspaceId: id, branch });
+            // Per-file events so an open tab on a file the host rewrote refetches
+            // instead of showing stale bytes until its next tree refresh. The paths
+            // were observed under the same hold as the pull, so they are exactly
+            // this sync's — never a save that landed alongside. Capped: a bulk
+            // import would otherwise fan hundreds of events out to say what one
+            // refresh says.
+            if (announce.changedPaths.length <= WorkflowService.SYNC_FILE_EVENT_CAP) {
+                for (const p of announce.changedPaths) {
+                    this.events?.emit({
+                        kind: 'file-changed',
+                        workspaceId: id,
+                        branch,
+                        path: `${this.kbDirName}/${p}`,
+                        newSha: announce.after,
+                        byUserId: 'system',
+                        byUserName: 'Git sync',
+                    });
+                }
+            }
+        }
+        catch (err) {
+            // The pull landed, so origin is fine and no banner is raised — but the
+            // caller must hear that this branch's announcement did not happen, and
+            // the announcement stays owed: the retry the error invites will not
+            // move HEAD again, so it must find the debt here rather than in the shas.
+            this.owedAnnouncements.set(id, announce);
+            const message = sanitizeError(err);
+            syncLog.warn(`pulled "${branch}" but could not announce it: ${message}`);
+            return { branch, outcome: 'error', error: message };
+        }
+        this.owedAnnouncements.delete(id);
+        return outcome;
+    }
     /**
      * A pull hit a rebase conflict — the workspace carries local commits that
      * conflict with origin, a state that never resolves on its own (every
@@ -408,11 +678,11 @@ export class WorkflowService {
                 authorName: user?.name ?? RECOVERY_BOT_NAME,
             });
             if (queued) {
-                console.warn(`[workflow] pull conflict on ws=${workspaceId} branch=${err.branch} (${err.conflictedPaths.join(', ')}) — queued background recovery`);
+                log.warn(`pull conflict on ws=${workspaceId} branch=${err.branch} (${err.conflictedPaths.join(', ')}) — queued background recovery`);
             }
         }
         catch (queueErr) {
-            console.error(`[workflow] failed to queue pull-conflict recovery for ws=${workspaceId}:`, queueErr instanceof Error ? queueErr.message : queueErr);
+            log.error(`failed to queue pull-conflict recovery for ws=${workspaceId}:`, { err: queueErr });
         }
     }
     resetToRemote(workspaceId, branch) {
@@ -461,6 +731,12 @@ export class WorkflowService {
     compareFile(workspaceId, path, fromBranch, toBranch) {
         return this.git.diffFileBetweenBranches(workspaceId, path, fromBranch, toBranch);
     }
+    fileAtForkPoint(workspaceId, baseBranch, sha, path) {
+        return this.git.readFileAtForkPoint(workspaceId, baseBranch, sha, path);
+    }
+    changeRequestForkPoint(workspaceId, baseBranch, headBranch) {
+        return this.git.mergeBaseForPr(workspaceId, baseBranch, headBranch);
+    }
     showFileAtChange(workspaceId, path, sha) {
         return this.git.diffFileAtCommit(workspaceId, path, sha);
     }
@@ -482,8 +758,18 @@ export class WorkflowService {
      * Always reads at-ref, never at the working tree, so a user can't broaden
      * their own access by editing `roles.yaml` / `access.md` in the same
      * session.
+     *
+     * Resolves to `'restore'` when the write passed ONLY as a platform-file
+     * restore — the caller then knows the destination denies this admin, and
+     * the read gate that follows stands aside for the same rescue.
      */
-    async assertCanWriteAtPath(workspaceId, branch, userEmail, targetPath) {
+    async assertCanWriteAtPath(workspaceId, branch, userEmail, targetPath, 
+    /**
+     * The caller says this write is an admin putting a misplaced platform file
+     * back, and names where the file is coming from. Checked in both halves,
+     * never taken on trust — see `acquireLock`'s `opts`.
+     */
+    platformRestore) {
         // The lock route passes workspace-relative paths
         // (`knowledge-base/GTM/.../Foo.md`), but the access model is keyed by
         // *repo-relative* paths — `git ls-tree` runs inside the inner repo dir,
@@ -493,14 +779,30 @@ export class WorkflowService {
         // typically only grants Admin → non-admins get 403'd on files their
         // role's nested access.md actually permits. Mirrors the frontend's
         // `useFileAccess` prefix-strip on the way INTO the API.
-        const repoRelative = targetPath.startsWith(`${this.kbDirName}/`)
-            ? targetPath.slice(this.kbDirName.length + 1)
-            : targetPath;
+        const toRepoRelative = (p) => p.startsWith(`${this.kbDirName}/`) ? p.slice(this.kbDirName.length + 1) : p;
+        const repoRelative = toRepoRelative(targetPath);
         const result = await this.accessControl.canWriteBatchAtRef(workspaceId, `HEAD`, userEmail, [repoRelative]);
         if (!result)
-            return; // no config at ref → default-allow (bootstrap)
+            return 'granted'; // no config at ref → default-allow (bootstrap)
         if (result.get(repoRelative))
-            return;
+            return 'granted';
+        // The one write allowed past a destination that denies it: an admin
+        // putting a platform file back where the platform reads it. The access
+        // module decides who — a repository whose root `access.md` is the file
+        // that went missing denies everyone, including the admin who would
+        // restore it — and the shape check decides WHICH MOVE may even ask.
+        //
+        // Both are asked here rather than trusted from the route, because
+        // `canRestorePlatformFile` answers only on where the write LANDS: on its
+        // own it would approve carrying the root's own `access.md` into a folder
+        // that has none, which is the loss this feature exists to prevent, spelled
+        // as its own rescue. The source is part of the claim precisely so no
+        // future caller can make that claim by passing a flag.
+        if (typeof platformRestore?.source === 'string' &&
+            isPlatformRestoreShape(toRepoRelative(platformRestore.source), repoRelative) &&
+            (await this.accessControl.canRestorePlatformFile(workspaceId, userEmail, repoRelative))) {
+            return 'restore';
+        }
         const eligible = await this.accessControl.eligibleWritersAtRef(workspaceId, `HEAD`, repoRelative);
         throw new AccessDeniedError({
             path: targetPath,
@@ -509,7 +811,19 @@ export class WorkflowService {
         });
     }
     // ── File locks ────────────────────────────────────────────────────────────
-    async acquireLock(workspaceId, branch, targetPath, user, opts) {
+    // Every method below canonicalises the caller's spelling into ONE file
+    // identity before it does anything with it. `FileLockService` canonicalises
+    // too, and has to: it is the coordination point and a caller can reach it
+    // without coming through here. The reason to do it again at this layer is
+    // that the path does not only key a lock row here. It is also what the
+    // permission gate is evaluated against, what `commitFile` stages, what the
+    // commit queue enqueues, and what rides out on every `lock-*` event. Left
+    // raw, a checkpoint on `./x//a.md` would find its lock and then fail at the
+    // commit, and a release would enqueue a row the worker keys differently from
+    // the lock it just dropped. Canonicalising is idempotent, so the second pass
+    // inside the lock service is free.
+    async acquireLock(workspaceId, branch, rawPath, user, opts) {
+        const targetPath = canonicalFileIdentity(rawPath);
         // **Permission check at lock acquisition, not at commit time.** Under the
         // "disk is the source of truth" rule, once a write has landed on disk we
         // must never reject the commit that publishes it — otherwise we'd be
@@ -519,14 +833,24 @@ export class WorkflowService {
         // the lock and the editor never opens. Once the lock is in hand, the
         // commit + push pipeline does not re-check (see `commitFile`).
         //
-        // **Protected branches only** (mirrors the legacy commit-time gate). On
-        // feature/draft branches anyone can write; canonical state changes go
-        // through change-request approval, which is where the real security
-        // boundary lives. Checking at HEAD (not at the working tree) so a user
-        // can't grant themselves access by editing `roles.yaml` in the same
+        // **Write gate — protected branches only** (mirrors the legacy commit-time
+        // gate). On feature/draft branches anyone can write; canonical state
+        // changes go through change-request approval, which is where the real
+        // security boundary lives. Checking at HEAD (not at the working tree) so a
+        // user can't grant themselves access by editing `roles.yaml` in the same
         // session.
         //
-        // **Coordination acquires skip the gate** (see the interface doc): the
+        // **Read gate — every branch.** Nothing is created, changed or removed
+        // where its author cannot read, drafts included: a proposal that lands in
+        // a folder its author cannot see would vanish from them the moment it was
+        // added, and a write grant only implies read — a nearer `deny read` can
+        // take the read away while the write stands. The one exception, a new
+        // folder directly under one of the three roots, and the reasons are in
+        // `access-model/change-gate.ts`. A write that passed only as a
+        // platform-file restore is not asked: that rescue exists exactly for a
+        // destination whose rules deny the admin making it.
+        //
+        // **Coordination acquires skip both gates** (see the interface doc): the
         // caller wants only mutual exclusion with the path's writer — e.g. the
         // roles admin holding machine-owned `synced-groups.yaml` steady across
         // its IdP-mode recheck — and will never write the path. Gating those on
@@ -535,14 +859,20 @@ export class WorkflowService {
         // authority flows from the hold: the mode is persisted on the lock row
         // and `commitFileWhileLocked` / `releaseLock` refuse to treat a
         // coordination hold as write possession (see those methods).
-        if (isProtectedBranch(branch) && !opts?.coordination) {
-            // `assertCanWriteAtPath` throws AccessDeniedError on denial, with the
-            // eligible-writers payload so the frontend can render a useful refusal.
-            await this.assertCanWriteAtPath(workspaceId, branch, user.email, targetPath);
+        if (!opts?.coordination) {
+            let via = 'granted';
+            if (isProtectedBranch(branch)) {
+                // `assertCanWriteAtPath` throws AccessDeniedError on denial, with the
+                // eligible-writers payload so the frontend can render a useful refusal.
+                via = await this.assertCanWriteAtPath(workspaceId, branch, user.email, targetPath, opts?.platformRestore);
+            }
+            if (via !== 'restore') {
+                await this.changeGate.assertMayChange(workspaceId, user.email, targetPath, 'file');
+            }
         }
         const result = await this.fileLocks.acquire(workspaceId, branch, targetPath, user, opts);
         if (result.acquired) {
-            console.log(`[lock] ACQUIRE ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → acquired`);
+            lockLog.info(`ACQUIRE ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → acquired`);
             // Only fire on successful acquisition — a contention "false" return
             // means nothing observable changed for other users (someone else
             // already held the lock and still does). Stale-lock takeover is also
@@ -557,18 +887,19 @@ export class WorkflowService {
             });
         }
         else {
-            console.log(`[lock] ACQUIRE ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → contended, held by ${result.lock.holderName} (${result.lock.holderUserId})`);
+            lockLog.info(`ACQUIRE ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → contended, held by ${result.lock.holderName} (${result.lock.holderUserId})`);
         }
         return result;
     }
-    async heartbeatLock(workspaceId, branch, targetPath, user) {
+    async heartbeatLock(workspaceId, branch, rawPath, user) {
+        const targetPath = canonicalFileIdentity(rawPath);
         try {
             const lock = await this.fileLocks.heartbeat(workspaceId, branch, targetPath, user);
-            console.log(`[lock] HEARTBEAT ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → ok (expires ${lock.expiresAt})`);
+            lockLog.info(`HEARTBEAT ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → ok (expires ${lock.expiresAt})`);
             return lock;
         }
         catch (err) {
-            console.warn(`[lock] HEARTBEAT ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → FAIL ${err instanceof Error ? err.message : err}`);
+            lockLog.warn(`HEARTBEAT ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → FAIL ${err instanceof Error ? err.message : err}`);
             throw err;
         }
     }
@@ -579,7 +910,8 @@ export class WorkflowService {
      * the lock so a stale client can't sneak commits through after their
      * lock expired and another user took over.
      */
-    async commitFileWhileLocked(workspaceId, branch, targetPath, user, summary) {
+    async commitFileWhileLocked(workspaceId, branch, rawPath, user, summary) {
+        const targetPath = canonicalFileIdentity(rawPath);
         const lock = await this.fileLocks.get(workspaceId, branch, targetPath);
         if (!lock || lock.holderUserId !== user.id) {
             throw new WorkflowValidationError(`Cannot commit "${targetPath}": you don't hold the lock.`, { kind: 'lock-not-held', branch, path: targetPath });
@@ -619,14 +951,14 @@ export class WorkflowService {
                 let recoveryError = null;
                 if (looksLikeNonFastForward) {
                     try {
-                        await this.git.pull(workspaceId);
+                        await this.pullWorkspace(workspaceId);
                         await this.git.push(workspaceId, user);
                         recovered = true;
                         this.noteGitSyncOk(workspaceId, branch);
                     }
                     catch (recoveryErr) {
                         recoveryError = recoveryErr;
-                        console.warn('[workflow] autosave cooperative recovery (pull-rebase) failed; leaving the unpushed commit for the next save / releaseLock to surface:', recoveryErr instanceof Error ? recoveryErr.message : recoveryErr);
+                        log.warn('autosave cooperative recovery (pull-rebase) failed; leaving the unpushed commit for the next save / releaseLock to surface:', { err: recoveryErr });
                     }
                 }
                 if (!recovered) {
@@ -644,7 +976,7 @@ export class WorkflowService {
                     if (!looksLikeNonFastForward) {
                         this.noteGitSyncFailed(workspaceId, branch, recoveryError ?? err);
                     }
-                    console.warn('[workflow] push after autosave commit failed (commit landed locally):', detail);
+                    log.warn('push after autosave commit failed (commit landed locally):', { detail });
                 }
             }
             this.events?.emit({
@@ -689,16 +1021,17 @@ export class WorkflowService {
      * worker; push is the worker's job; there's no synchronous `Change`
      * object to return because the commit hasn't happened yet.
      */
-    async releaseLock(workspaceId, branch, targetPath, user) {
+    async releaseLock(workspaceId, branch, rawPath, user) {
+        const targetPath = canonicalFileIdentity(rawPath);
         // Ownership check — the lock service's `release` is idempotent and
         // would silently no-op for a non-holder, but we'd still enqueue a
         // commit attributed to whoever called us. The guard rejects callers
         // who don't actually hold the row so impersonation can't enqueue
         // commits as a third party.
-        console.log(`[lock] RELEASE start ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id}`);
+        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) {
-            console.warn(`[lock] 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.holderName} (${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
@@ -711,7 +1044,7 @@ export class WorkflowService {
         // and `releaseLockUntouched`. Worst case a refused caller strands the
         // row until its TTL.
         if (lock.mode === 'coordination') {
-            console.warn(`[lock] RELEASE refused ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → coordination hold (no commit may be enqueued)`);
+            lockLog.warn(`RELEASE refused ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → coordination hold (no commit may be enqueued)`);
             throw new WorkflowValidationError(`Cannot release lock on "${targetPath}" with a commit: it is a coordination hold. Use releaseLockNoCommit.`, { kind: 'coordination-hold', branch, path: targetPath });
         }
         // Order matters here:
@@ -732,7 +1065,7 @@ export class WorkflowService {
             authorName: user.name,
         });
         await this.fileLocks.release(workspaceId, branch, targetPath, user);
-        console.log(`[lock] RELEASE done ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} (commit queued for background worker)`);
+        lockLog.info(`RELEASE done ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} (commit queued for background worker)`);
         // The `file-changed` SSE event used to fire here after the synchronous
         // commit landed, carrying the new sha. Under the queue model the
         // commit hasn't happened yet — the worker emits `file-changed` itself
@@ -819,7 +1152,7 @@ export class WorkflowService {
         const id = branchForWorkspaceId(workspaceId);
         if (!this.gitSyncFailing.delete(id))
             return;
-        console.log(`[workflow] git sync recovered for workspace=${id} branch=${branch}`);
+        log.info(`git sync recovered for workspace=${id} branch=${branch}`);
         this.events?.emit({ kind: 'git-sync-recovered', workspaceId: id, branch });
     }
     /**
@@ -830,7 +1163,29 @@ export class WorkflowService {
      * machinery is unaffected — all this adds is that someone finds out, rather
      * than the deployment looking healthy while nothing reaches the remote.
      */
-    noteGitSyncFailed(workspaceId, branch, err) {
+    noteGitSyncFailed(workspaceId, branch, err, 
+    /**
+     * The files a person must reconcile, and the sentence we composed about
+     * them. That sentence is ours (branch name + repo paths, no git stderr),
+     * so it goes out verbatim — the same string the sync response and the
+     * log carry — rather than through the sanitiser, whose 200-character
+     * clip would make the banner disagree with them. Callers that already
+     * hold the sentence pass it; otherwise it is derived below.
+     */
+    explicitConflict) {
+        // 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
+        // error — and the banner keeps the LATEST failure per branch, so a retry
+        // landing after the sync would replace the conflict variant, with the
+        // files as links, by the generic "check the server logs" one. Seen on
+        // staging: the sync's 409 named the file, the worker's retry a moment
+        // later took the links away. Derive the paths from the error itself so
+        // every path agrees.
+        const conflict = explicitConflict ??
+            (err instanceof PullRebaseConflictError
+                ? { paths: err.conflictedPaths, message: syncConflictMessage(branch, err.conflictedPaths) }
+                : undefined);
         // Same canonicalization as `noteGitSyncOk` — the pair must agree on keys.
         const id = branchForWorkspaceId(workspaceId);
         this.gitSyncFailing.add(id);
@@ -840,7 +1195,8 @@ export class WorkflowService {
             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: sanitizeError(err),
+            reason: conflict ? conflict.message : sanitizeError(err),
+            ...(conflict ? { conflictedPaths: conflict.paths } : {}),
         });
     }
     /**
@@ -889,16 +1245,16 @@ export class WorkflowService {
             let recoveryError = null;
             if (looksLikeNonFastForward) {
                 try {
-                    await this.git.pull(workspaceId);
+                    await this.pullWorkspace(workspaceId);
                     await this.git.push(workspaceId, user, opts);
                     recovered = true;
                     this.noteGitSyncOk(workspaceId, branch);
-                    console.log(`[workflow] non-fast-forward push recovered via pull --rebase for workspace=${workspaceId} branch=${branch} path=${targetPath}`);
+                    log.info(`non-fast-forward push recovered via pull --rebase for workspace=${workspaceId} branch=${branch} path=${targetPath}`);
                 }
                 catch (recoveryErr) {
                     recoveryError = recoveryErr;
                     recoveryDetail = recoveryErr instanceof Error ? recoveryErr.message : String(recoveryErr);
-                    console.warn(`[workflow] cooperative recovery (pull-rebase) failed for workspace=${workspaceId} user=${user.id}; handing off to agent:`, recoveryDetail);
+                    log.warn(`cooperative recovery (pull-rebase) failed for workspace=${workspaceId} user=${user.id}; handing off to agent:`, { detail: recoveryDetail });
                 }
             }
             if (!recovered) {
@@ -910,7 +1266,7 @@ export class WorkflowService {
                 // 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);
-                console.warn(`[workflow] push failed for workspace=${workspaceId} user=${user.id}; throwing PushNeedsAgentResolutionError so the frontend can hand off to the agent:`, firstDetail);
+                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);
             }
         }
@@ -924,17 +1280,18 @@ export class WorkflowService {
      * its catch arm so a thrown op (path traversal, validator 422,
      * permission denied) doesn't end up committing.
      */
-    async releaseLockNoCommit(workspaceId, branch, targetPath, user) {
+    async releaseLockNoCommit(workspaceId, branch, rawPath, user) {
+        const targetPath = canonicalFileIdentity(rawPath);
         // Verify ownership first so the emit only fires when something
         // observable actually changed. `fileLocks.release` silently no-ops
         // when the caller doesn't hold the row (idempotent-by-design), so
         // without this guard a non-holder calling this method would emit
         // `lock-released` and trick every other client into clearing their
         // "Locked by X" banner even though the lock is still held.
-        console.log(`[lock] RELEASE-NO-COMMIT start ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id}`);
+        lockLog.info(`RELEASE-NO-COMMIT 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) {
-            console.log(`[lock] RELEASE-NO-COMMIT no-op ws=${workspaceId} path=${targetPath} → ${lock ? `held by ${lock.holderName}` : 'no lock row'}`);
+            lockLog.info(`RELEASE-NO-COMMIT no-op ws=${workspaceId} path=${targetPath} → ${lock ? `held by ${lock.holderName}` : 'no lock row'}`);
             return;
         }
         // **Discard the file's working-tree changes before dropping the lock.**
@@ -962,7 +1319,9 @@ export class WorkflowService {
             catch (err) {
                 // Queue unreadable — fall back to the discard (the strict default:
                 // never let a coordination hold end with publishable stray bytes).
-                console.warn(`[workflow] pending-commit lookup failed for workspace=${workspaceId} path=${targetPath}; discarding:`, err instanceof Error ? err.message : err);
+                log.warn(`pending-commit lookup failed for workspace=${workspaceId} path=${targetPath}; discarding:`, {
+                    err,
+                });
             }
         }
         let discarded = false;
@@ -975,11 +1334,13 @@ export class WorkflowService {
                 // Best-effort: a discard failure is logged but doesn't block the
                 // lock release. Worst case the working tree stays dirty for one
                 // path until the next save on it cleans up.
-                console.warn(`[workflow] discardPath failed for workspace=${workspaceId} branch=${branch} path=${targetPath}:`, err instanceof Error ? err.message : err);
+                log.warn(`discardPath failed for workspace=${workspaceId} branch=${branch} path=${targetPath}:`, {
+                    err,
+                });
             }
         }
         await this.fileLocks.release(workspaceId, branch, targetPath, user);
-        console.log(`[lock] RELEASE-NO-COMMIT done ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → ${discarded ? 'discarded + released' : 'released (working tree untouched)'}`);
+        lockLog.info(`RELEASE-NO-COMMIT done ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → ${discarded ? 'discarded + released' : 'released (working tree untouched)'}`);
         this.events?.emit({
             kind: 'lock-released',
             workspaceId,
@@ -1013,15 +1374,16 @@ export class WorkflowService {
      * lock row, nothing else. Same idempotent non-holder no-op (and emit
      * discipline) as `releaseLockNoCommit`.
      */
-    async releaseLockUntouched(workspaceId, branch, targetPath, user) {
-        console.log(`[lock] RELEASE-UNTOUCHED start ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id}`);
+    async releaseLockUntouched(workspaceId, branch, rawPath, user) {
+        const targetPath = canonicalFileIdentity(rawPath);
+        lockLog.info(`RELEASE-UNTOUCHED 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) {
-            console.log(`[lock] RELEASE-UNTOUCHED no-op ws=${workspaceId} path=${targetPath} → ${lock ? `held by ${lock.holderName}` : 'no lock row'}`);
+            lockLog.info(`RELEASE-UNTOUCHED no-op ws=${workspaceId} path=${targetPath} → ${lock ? `held by ${lock.holderName}` : 'no lock row'}`);
             return;
         }
         await this.fileLocks.release(workspaceId, branch, targetPath, user);
-        console.log(`[lock] RELEASE-UNTOUCHED done ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → released (disk + queue untouched)`);
+        lockLog.info(`RELEASE-UNTOUCHED done ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → released (disk + queue untouched)`);
         this.events?.emit({
             kind: 'lock-released',
             workspaceId,
@@ -1031,14 +1393,16 @@ export class WorkflowService {
         // No `file-changed` here on purpose — unlike the no-commit release,
         // nothing on disk moved.
     }
-    hasQueuedCommit(workspaceId, branch, targetPath) {
-        return this.pendingCommits.hasLiveRowFor(workspaceId, branch, targetPath);
+    hasQueuedCommit(workspaceId, branch, rawPath) {
+        // The row was stored under the canonical identity (`releaseLock`), so the
+        // question is asked under it too — whatever spelling the caller has.
+        return this.pendingCommits.hasLiveRowFor(workspaceId, branch, canonicalFileIdentity(rawPath));
     }
     hasUnpushedCommits(workspaceId) {
         return this.git.hasUnpushedCommits(workspaceId);
     }
-    getLock(workspaceId, branch, targetPath) {
-        return this.fileLocks.get(workspaceId, branch, targetPath);
+    getLock(workspaceId, branch, rawPath) {
+        return this.fileLocks.get(workspaceId, branch, canonicalFileIdentity(rawPath));
     }
     // ── Change Requests ───────────────────────────────────────────────────────
     listChangeRequests(opts) {
@@ -1143,7 +1507,7 @@ export class WorkflowService {
                     targetBranch: input.targetBranch,
                     title: input.title.trim(),
                     body,
-                    authorEmail: user.email.trim().toLowerCase(),
+                    authorEmail: canonicalEmail(user.email),
                     authorName: user.name,
                 })
                     .returning({ number: changeRequests.number });
@@ -1206,10 +1570,20 @@ export class WorkflowService {
      * as `ChangeRequestConflictsError`; the caller (UI or agent) is expected
      * to route into the resolution flow exactly as on open.
      *
-     * Approvals on files touched by the merge resolution invalidate
-     * automatically — they're pinned to the head SHA, and any new commit on
-     * source drops the per-file approval gate (handled by the existing
-     * approval staleness check). No special bookkeeping needed here.
+     * Approvals are carried across the merge BY CONTENT: every approval on a
+     * file whose bytes the merge left alone is re-pinned to the new head, and
+     * only a file the merge actually changed loses its approval (staleness is
+     * still `row.headSha !== headSha`, unchanged). Without this, a merge
+     * nobody asked for would void every approval on the request — including
+     * the files it never touched — and since the dialog now runs this update
+     * by itself, every stale request would cost a second round of review.
+     * This holds for EVERY caller of the route, agent or UI.
+     *
+     * Authority: the request's author, or anyone who may apply it — the
+     * detail's `viewerCanUpdate`, computed for THIS caller, so the button and
+     * the enforcement read one predicate. A conflicting merge is aborted
+     * inside `mergeFromOrigin`: nothing is committed or pushed, and the branch
+     * is exactly what it was.
      */
     async updateFromTarget(workspaceId, user, number) {
         const detail = await this.prs.getPrDetail(number, { fresh: true, workspaceId, viewerEmail: user.email });
@@ -1219,6 +1593,47 @@ export class WorkflowService {
         if (detail.state !== 'open') {
             throw new WorkflowValidationError(`Change request #${number} is ${detail.state} — only open requests can refresh from target.`, { kind: 'change-request-not-open', state: detail.state });
         }
+        if (!detail.viewerCanUpdate) {
+            throw new WorkflowDomainError('Only the author of this change request, or someone who may apply it, can update it.', 403);
+        }
+        // Taken BEFORE the head moves (the pull below can move it too): only a
+        // refusal recorded earlier describes the revision this replaces (see
+        // `clearApplyFailure`).
+        const headMovedAfter = new Date();
+        // Freshen the source checkout first, and let a failure stop the Update:
+        // merging onto a head behind its own origin branch would leave a local
+        // merge commit that then cannot push, stranding it in the workspace. A
+        // rebase conflict hands the stranded saves to recovery, as every other
+        // pull does, before the refusal reaches the caller.
+        try {
+            await this.pullWorkspace(workspaceId);
+        }
+        catch (err) {
+            if (err instanceof PullRebaseConflictError) {
+                await this.queuePullConflictRecovery(workspaceId, err, user);
+            }
+            throw err;
+        }
+        // The head an approval is pinned to is whatever is PUBLISHED on the
+        // request's branch — and the pull above may just have moved it: an agent,
+        // or the author from another client, can push while this dialog is still
+        // reading the detail. Resolve it HERE rather than trusting the
+        // `detail.headSha` read before the pull: an approval made against that
+        // newer head carries a sha the pre-pull detail does not name, so carrying
+        // forward from the stale one would find no rows and void every approval
+        // the merge never touched.
+        //
+        // Best effort, like the carry-forward it feeds: the bookkeeping must never
+        // be what stops a request from being brought up to date, so a failed
+        // resolve falls back to the sha the detail reported.
+        let headBeforeMerge = detail.headSha;
+        try {
+            const at = await this.git.resolvePrShas(workspaceId, detail.base, detail.branch);
+            headBeforeMerge = at.headSha;
+        }
+        catch (err) {
+            log.warn(`could not resolve the published head of change request #${number} before updating it from target; falling back to the head its detail reported`, { err });
+        }
         const outcome = await this.git.mergeFromOrigin(workspaceId, detail.branch, detail.base, user);
         if (outcome.kind === 'conflicts') {
             throw new ChangeRequestConflictsError(detail.branch, detail.base, outcome.paths);
@@ -1227,6 +1642,8 @@ export class WorkflowService {
         // already up to date there's nothing to share — short-circuit the push.
         if (!outcome.alreadyUpToDate) {
             await this.trackedPush(workspaceId, user);
+            // The source head moved: the refusal described a revision that is gone.
+            await this.clearApplyFailure(number, { recordedBefore: headMovedAfter });
         }
         this.prs.invalidateDetailCache(number);
         const refreshed = await this.prs.getPrDetail(number, {
@@ -1237,6 +1654,41 @@ export class WorkflowService {
         if (!refreshed) {
             throw new WorkflowValidationError(`Refreshed change request #${number} but could not re-fetch its detail.`);
         }
+        // The merge is a commit the APPROVERS did not make. Re-pin their
+        // approvals onto the new head for every file whose bytes it left alone —
+        // git's own two-dot diff between the two heads is the verdict on which
+        // those are. Best effort: a request that IS up to date is worth far more
+        // than the bookkeeping, so a failure here is logged and the fresh detail
+        // still goes back.
+        //
+        // `alreadyUpToDate` is the real gate: no merge commit, no head to compare,
+        // nothing moved under anyone. The other two conditions are belt-and-braces
+        // over a sha that is not a sha — a resolve that failed onto a detail with
+        // no head, or two heads that somehow read equal — both of which
+        // `pathsChangedBetween` and `carryApprovalsForward` would refuse anyway.
+        // A merge that authored a commit cannot leave the head where it was.
+        if (!outcome.alreadyUpToDate && headBeforeMerge && refreshed.headSha !== headBeforeMerge) {
+            try {
+                const changedPaths = await this.git.pathsChangedBetween(workspaceId, headBeforeMerge, refreshed.headSha);
+                const carried = await this.reviewWorkflow.carryApprovalsForward(number, headBeforeMerge, refreshed.headSha, changedPaths);
+                // The detail above was assembled before those rows existed, so its
+                // `approvals` (and the merge gate derived from them) still describe
+                // the pre-merge head. Only re-read when something actually carried.
+                if (carried > 0) {
+                    this.prs.invalidateDetailCache(number);
+                    const withApprovals = await this.prs.getPrDetail(number, {
+                        fresh: true,
+                        workspaceId,
+                        viewerEmail: user.email,
+                    });
+                    if (withApprovals)
+                        return withApprovals;
+                }
+            }
+            catch (err) {
+                log.warn(`could not carry approvals forward on change request #${number} after updating from target`, { err });
+            }
+        }
         return refreshed;
     }
     listComments(number) {
@@ -1257,7 +1709,17 @@ export class WorkflowService {
         this.prs.invalidateDetailCache(number);
     }
     async approveFile(number, path, user, files, headSha, baseBranch, authorIdHash, workspaceId) {
+        // Taken BEFORE the approval lands (see `clearApplyFailure`).
+        const approvedAfter = new Date();
         const approvals = await this.reviewWorkflow.approveFile(number, path, user, files, headSha, baseBranch, authorIdHash, workspaceId);
+        // A recorded approval can answer a GATE refusal only — a conflict or a git
+        // error still describes the request — and only once the gate that refused
+        // would now pass: approving one file of several leaves the rest waiting,
+        // and the refusal naming them still stands. Warnings count too, since an
+        // apply without bypass is refused on them.
+        if (this.gateWouldPass(number, approvals)) {
+            await this.clearApplyFailure(number, { kinds: ['gate'], recordedBefore: approvedAfter });
+        }
         this.prs.invalidateDetailCache(number);
         this.events?.emit({
             kind: 'approval-changed',
@@ -1280,6 +1742,26 @@ export class WorkflowService {
         });
         return approvals;
     }
+    /**
+     * The folder placeholder a file's revert takes along, or null. When a
+     * request removed a folder's last file, the placeholder that keeps the
+     * folder came with it (git may even pair them as one rename); reverting the
+     * file alone would leave that hidden placeholder as a change nobody can
+     * see. So it is reverted too — when the request changed it, and only when
+     * that cannot leave the folder with nothing in git: either the file comes
+     * back, or the base had the placeholder to restore.
+     */
+    async placeholderRevertedWith(workspaceId, mergeBase, repoRelPath, changedPaths) {
+        if (isFolderPlaceholder(repoRelPath))
+            return null;
+        const slash = repoRelPath.lastIndexOf('/');
+        const placeholder = folderPlaceholderPath(slash === -1 ? '' : repoRelPath.slice(0, slash));
+        if (!changedPaths.includes(placeholder))
+            return null;
+        if (await this.git.pathExistsAtRef(workspaceId, mergeBase, repoRelPath))
+            return placeholder;
+        return (await this.git.pathExistsAtRef(workspaceId, mergeBase, placeholder)) ? placeholder : null;
+    }
     /**
      * 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
@@ -1306,12 +1788,14 @@ export class WorkflowService {
         }
         const baseBranch = summary.base;
         const headBranch = summary.branch;
+        // Taken BEFORE the head moves (see `clearApplyFailure`).
+        const headMovedAfter = new Date();
         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);
+        await this.pullWorkspace(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)) {
@@ -1325,32 +1809,310 @@ export class WorkflowService {
         if (!mergeBase) {
             throw new WorkflowDomainError('These branches share no history to revert to.', 422);
         }
+        const placeholder = await this.placeholderRevertedWith(ws.id, mergeBase, repoRelPath, paths);
+        const reverted = placeholder ? [repoRelPath, placeholder] : [repoRelPath];
         // 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);
-        }
+        const held = [];
+        let revertError = null;
         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);
+            for (const p of reverted) {
+                const lockPath = `${this.kbDirName}/${p}`;
+                const lock = await this.fileLocks.acquire(ws.id, headBranch, lockPath, user);
+                if (!lock.acquired) {
+                    throw new WorkflowDomainError(p === repoRelPath
+                        ? `${repoRelPath} is being edited by ${lock.lock.holderName} — try again once the edit settles.`
+                        : `The folder of ${repoRelPath} is being changed by ${lock.lock.holderName} — try again once the edit settles.`, 409);
+                }
+                held.push(lockPath);
+            }
+            for (const p of reverted) {
+                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);
         }
-        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);
-        }
+        catch (err) {
+            revertError = { reason: err };
+        }
+        // Committed inline — drop the lock rows directly rather than enqueueing
+        // a duplicate commit through releaseLock. Each is released on its own, on
+        // success and failure alike: one failed release must not leave the other
+        // lock held. The revert's own error wins; otherwise a failed release
+        // still surfaces, as a single release's did.
+        const released = await Promise.allSettled(held.map((lockPath) => this.fileLocks.release(ws.id, headBranch, lockPath, user)));
+        if (revertError)
+            throw revertError.reason;
+        const failedRelease = released.find((r) => r.status === 'rejected');
+        if (failedRelease)
+            throw failedRelease.reason;
+        // 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) {
-            return { closed: false, remainingPaths: remaining };
+            // Answered like the file list: the placeholder is not a remaining file.
+            return { closed: false, remainingPaths: remaining.filter((p) => !isFolderPlaceholder(p)) };
         }
         // Every change declined → the request proposes nothing.
         await this.closeEmptyChangeRequest(number, user);
         return { closed: true, remainingPaths: [] };
     }
+    /**
+     * The open change requests that propose files under a KB folder, and
+     * whether the caller may take those files out of each — what a folder
+     * delete asks before it offers "Delete folder and its proposed changes".
+     *
+     * The caller may act on a request they authored, on any request as an
+     * admin, or on a request whose every proposed file under the folder they
+     * may write — per file, not at the folder's top: a subfolder can deny a
+     * writer of its parent. The last two are judged on `origin/<base>`, like
+     * every other request verb. An access answer that cannot be resolved
+     * (null) is a no.
+     */
+    async changeRequestsUnderFolder(folder, user) {
+        const prefix = folderPrefix(folder);
+        const open = await this.prs.listOpenPrs({ fresh: true });
+        // The list's touched paths are best-effort: a diff it could not read comes
+        // back EMPTY, indistinguishable from a request proposing nothing. This
+        // answer gates a destructive action, so a request listed empty is read
+        // again here, and one whose diff still cannot be read fails the question
+        // rather than dropping out of it.
+        const resolved = await Promise.all(open.map(async (cr) => {
+            if (cr.touchedNodePaths.length > 0)
+                return { cr, touched: cr.touchedNodePaths };
+            try {
+                const ws = await this.workspaceService.getOrCreateForBranch(cr.branch);
+                return { cr, touched: await this.git.changedPathsForPr(ws.id, cr.base, cr.branch) };
+            }
+            catch (err) {
+                log.warn(`changedPathsForPr failed for #${cr.number} under folder ${printable(folder)}: ${printable(sanitizeError(err))}`);
+                throw new WorkflowDomainError(`Couldn't read what change request #${cr.number} proposes — try again in a moment.`, 500);
+            }
+        }));
+        const touching = resolved
+            .map(({ cr, touched }) => ({ cr, paths: touched.filter((p) => p.startsWith(prefix)) }))
+            .filter((t) => t.paths.length > 0);
+        if (touching.length === 0)
+            return [];
+        const callerHash = hashEmail(user.email);
+        // One admin answer per base branch; the requests almost always share one.
+        const baseWorkspaces = new Map();
+        const baseWorkspace = (base) => {
+            let ws = baseWorkspaces.get(base);
+            if (!ws) {
+                ws = this.workspaceService.getOrCreateForBranch(base).then((w) => w.id);
+                baseWorkspaces.set(base, ws);
+            }
+            return ws;
+        };
+        const adminByBase = new Map();
+        const adminOn = (base) => {
+            let admin = adminByBase.get(base);
+            if (!admin) {
+                admin = baseWorkspace(base).then(async (wsId) => (await this.accessControl.canWriteAtRef(wsId, `origin/${base}`, user.email, 'roles.yaml')) === true);
+                adminByBase.set(base, admin);
+            }
+            return admin;
+        };
+        const writerOfAll = async (base, paths) => {
+            const answers = await this.accessControl.canWriteBatchAtRef(await baseWorkspace(base), `origin/${base}`, user.email, paths);
+            return answers !== null && paths.every((p) => answers.get(p) === true);
+        };
+        return Promise.all(touching.map(async ({ cr, paths }) => {
+            const mine = !!cr.authorId && cr.authorId === callerHash;
+            const listed = {
+                number: cr.number,
+                title: cr.title,
+                authorName: cr.appAuthor?.name ?? cr.author.name ?? null,
+                mine,
+                paths,
+            };
+            if (mine || (await adminOn(cr.base)) || (await writerOfAll(cr.base, paths))) {
+                return { ...listed, mayRemove: true };
+            }
+            return {
+                ...listed,
+                mayRemove: false,
+                reason: `#${cr.number} was proposed by ${cr.appAuthor?.name ?? 'someone else'}; only its author, an admin or someone who can write every file it proposes here can change it.`,
+            };
+        }));
+    }
+    /**
+     * Take every file under `folder` out of every open change request that
+     * proposes one — the request half of "Delete folder and its proposed
+     * changes". All-or-nothing on permission: when the caller may not act on
+     * even one of the requests, nothing is touched. A request left proposing
+     * nothing is withdrawn (closed, its branch retired), exactly as declining
+     * its last file would.
+     */
+    async removeFolderFromChangeRequests(folder, user) {
+        const requests = await this.changeRequestsUnderFolder(folder, user);
+        const refused = requests.filter((r) => !r.mayRemove);
+        if (refused.length > 0) {
+            throw new WorkflowDomainError(`You can't remove proposed changes from ${refused.map((r) => `#${r.number}`).join(', ')} — only the author, an admin or someone who can write every file it proposes here can.`, 403);
+        }
+        const prefix = folderPrefix(folder);
+        // Everything that can refuse happens before the first commit, so a
+        // refusal leaves every request as it was: each request's source checkout
+        // brought up to date (a failed pull stops here — restoring into a stale
+        // or conflicted tree could commit the wrong content), its paths read as
+        // they are NOW rather than as the list saw them, its merge base found,
+        // and every file's lock held.
+        const plans = [];
+        for (const request of requests) {
+            const summary = await this.prs.getPr(request.number);
+            if (!summary || summary.state !== 'open')
+                continue;
+            const ws = await this.workspaceService.getOrCreateForBranch(summary.branch);
+            try {
+                await this.pullWorkspace(ws.id);
+            }
+            catch (err) {
+                log.warn(`pull failed for #${summary.number} before removing folder ${printable(folder)}: ${printable(sanitizeError(err))}`);
+                throw new WorkflowDomainError(`#${summary.number} could not be brought up to date, so nothing was removed — try again in a moment.`, 409);
+            }
+            const paths = (await this.git.changedPathsForPr(ws.id, summary.base, summary.branch)).filter((p) => p.startsWith(prefix));
+            // The permission above was judged on the paths the request proposed
+            // then. One proposed since was never judged — a writer of every earlier
+            // file need not be one of it — so the request has to be asked about again.
+            const unjudged = paths.filter((p) => !request.paths.includes(p));
+            if (unjudged.length > 0) {
+                throw new WorkflowDomainError(`#${summary.number} changed while the folder was being deleted (${unjudged.length === 1 ? unjudged[0] : `${unjudged.length} new files`}), so no proposed changes were removed — try again.`, 409);
+            }
+            let mergeBase = null;
+            if (paths.length > 0) {
+                mergeBase = await this.git.mergeBaseForPr(ws.id, summary.base, summary.branch);
+                if (!mergeBase) {
+                    throw new WorkflowDomainError(`#${summary.number} shares no history with its target to revert to.`, 422);
+                }
+            }
+            plans.push({ number: summary.number, branch: summary.branch, wsId: ws.id, paths, mergeBase });
+        }
+        // Requests can share a source branch, and so a workspace and even a file.
+        // The work is grouped per workspace: each file is locked, restored and
+        // committed once, and each branch pushed once. One restore can only undo a
+        // shared file for requests that agree on what it reverts TO — requests on
+        // one branch aimed at targets with different merge bases do not, and one
+        // of them would be reported emptied while still proposing the file. That
+        // combination is refused here, before anything is locked or changed.
+        const byWorkspace = new Map();
+        for (const plan of plans) {
+            let group = byWorkspace.get(plan.wsId);
+            if (!group) {
+                group = { wsId: plan.wsId, branch: plan.branch, plans: [], paths: [] };
+                byWorkspace.set(plan.wsId, group);
+            }
+            group.plans.push(plan);
+            for (const repoRelPath of plan.paths) {
+                const seen = group.paths.find((p) => p.path === repoRelPath);
+                if (!seen) {
+                    group.paths.push({ path: repoRelPath, mergeBase: plan.mergeBase });
+                }
+                else if (seen.mergeBase !== plan.mergeBase) {
+                    const sharing = group.plans.map((other) => `#${other.number}`).join(', ');
+                    throw new WorkflowDomainError(`${sharing} propose ${repoRelPath} from the same branch against different targets, so it can't be taken out of both at once. Decline it in each request instead.`, 422);
+                }
+            }
+        }
+        const groups = [...byWorkspace.values()];
+        const toChange = groups.filter((g) => g.paths.length > 0);
+        const held = [];
+        // Every held lock is let go, each on its own: one failed release must not
+        // keep the rest held until they expire.
+        const releaseAll = async () => {
+            for (const h of held.splice(0)) {
+                try {
+                    await this.fileLocks.release(h.wsId, h.branch, h.lockPath, user);
+                }
+                catch (err) {
+                    log.warn(`lock release failed for ${printable(h.lockPath)}: ${printable(sanitizeError(err))}`);
+                }
+            }
+        };
+        const pushed = [];
+        let pushFailure = null;
+        try {
+            for (const group of toChange) {
+                for (const { path: repoRelPath } of group.paths) {
+                    const lockPath = `${this.kbDirName}/${repoRelPath}`;
+                    const lock = await this.fileLocks.acquire(group.wsId, group.branch, lockPath, user);
+                    if (!lock.acquired) {
+                        throw new WorkflowDomainError(`${repoRelPath} is being edited by ${lock.lock.holderName} — try again once the edit settles.`, 409);
+                    }
+                    held.push({ wsId: group.wsId, branch: group.branch, lockPath });
+                }
+            }
+            // The git half is ONE operation under one reservation of every checkout
+            // involved: it records each HEAD, commits every revert before pushing
+            // anything, pushes branch by branch, and undoes what didn't publish (see
+            // `GitService.revertPathsAndPush`). A failed restore or commit throws
+            // with every request left as it was. Pushes can't be made atomic, so a
+            // failed push leaves the requests split into "done" and "untouched", and
+            // running the action again finishes the rest.
+            if (toChange.length > 0) {
+                const outcome = await this.git.revertPathsAndPush(user, toChange.map((group) => {
+                    const numbers = group.plans.map((plan) => `#${plan.number}`).join(', ');
+                    return {
+                        workspaceId: group.wsId,
+                        paths: group.paths.map(({ path: repoRelPath, mergeBase }) => ({
+                            path: repoRelPath,
+                            ref: mergeBase,
+                            subject: commitSubject(`Revert ${repoRelPath} (folder deleted; removed from change request ${numbers})`, `Revert ${basenameOf(repoRelPath)} (folder deleted; removed from ${group.plans.length === 1 ? `change request ${numbers}` : `${group.plans.length} change requests`})`),
+                            undoSubject: commitSubject(`Undo revert of ${repoRelPath} (folder removal stopped)`, `Undo revert of ${basenameOf(repoRelPath)} (folder removal stopped)`),
+                        })),
+                    };
+                }));
+                for (const group of toChange) {
+                    if (outcome.pushed.includes(group.wsId)) {
+                        this.noteGitSyncOk(group.wsId, group.branch);
+                        pushed.push(group);
+                        for (const plan of group.plans)
+                            this.prs.invalidateDetailCache(plan.number);
+                    }
+                    else if (outcome.failed?.workspaceId === group.wsId) {
+                        this.noteGitSyncFailed(group.wsId, group.branch, outcome.failed.error);
+                        pushFailure = { group, err: outcome.failed.error };
+                    }
+                }
+            }
+        }
+        finally {
+            await releaseAll();
+        }
+        const finished = (pushFailure ? pushed : groups).flatMap((group) => group.plans);
+        if (pushFailure && finished.length === 0)
+            throw pushFailure.err;
+        const results = [];
+        for (const plan of finished) {
+            const withdrawn = await this.closeEmptyChangeRequest(plan.number, user);
+            // A request still open is read once more, to say why: a file under the
+            // folder proposed while this ran (never judged, so left alone), or —
+            // proposing nothing at all — a save still landing kept it open.
+            let stillProposed = [];
+            let keptForSaves = false;
+            if (!withdrawn) {
+                try {
+                    const summary = await this.prs.getPr(plan.number);
+                    if (summary?.state === 'open') {
+                        const now = await this.git.changedPathsForPr(plan.wsId, summary.base, summary.branch);
+                        stillProposed = now.filter((p) => p.startsWith(prefix) && !isFolderPlaceholder(p));
+                        keptForSaves = now.length === 0;
+                    }
+                }
+                catch (err) {
+                    log.warn(`could not re-read #${plan.number} after removing folder ${printable(folder)}: ${printable(sanitizeError(err))}`);
+                }
+            }
+            results.push({ number: plan.number, removedPaths: plan.paths, withdrawn, stillProposed, keptForSaves });
+        }
+        if (pushFailure) {
+            const failed = pushFailure.group.plans.map((plan) => `#${plan.number}`).join(', ');
+            log.warn(`push failed for ${failed} removing folder ${printable(folder)}: ${printable(sanitizeError(pushFailure.err))}`);
+            throw new WorkflowDomainError(`The folder's files were removed from ${finished.map((plan) => `#${plan.number}`).join(', ')}, but ${failed} could not be updated and it and any later requests were left as they were. Run the delete again to finish.`, 500);
+        }
+        return results;
+    }
     /**
      * DELETE a change request outright: close it (whatever its diff says) and
      * retire its source branch — the request, its proposal, and the branch that
@@ -1444,6 +2206,12 @@ export class WorkflowService {
      * is AUTHORITATIVE — recomputed, and a diff failure aborts rather than
      * closes, so a transient git error can never eat a live request.
      *
+     * An empty diff is not yet an empty request while a save to its branch is
+     * still landing: one under a held lock or queued for the commit worker is
+     * on disk but not in the diff. Retiring the branch deletes its checkout and
+     * that save with it, so such a request stays open — the save commits and it
+     * proposes something again, or a later look closes it.
+     *
      * Returns true when THIS call closed it.
      */
     async closeEmptyChangeRequest(number, user) {
@@ -1451,16 +2219,20 @@ export class WorkflowService {
         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) {
-            console.warn(`[cr] empty-check for change request #${number} failed — leaving it open:`, err);
+            crLog.warn(`empty-check for change request #${number} failed — leaving it open:`, { err });
             return false;
         }
         if (paths.length > 0)
             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();
@@ -1476,6 +2248,21 @@ export class WorkflowService {
         await this.retireMergedSourceBranch(number, summary.base, user);
         return true;
     }
+    /**
+     * Whether a save to this branch's checkout is still landing: a live file
+     * lock (the write is mid-flight) or any queued commit, stuck ones included
+     * (their file is still only on disk). An answer that cannot be read is a
+     * yes — the caller is about to delete the checkout.
+     */
+    async savesInFlight(wsId) {
+        try {
+            return (await this.fileLocks.hasAnyActive(wsId)) || (await this.pendingCommits.hasAnyForWorkspace(wsId));
+        }
+        catch (err) {
+            crLog.warn(`could not tell whether saves are landing on ${printable(wsId)} — keeping its request open:`, { err });
+            return true;
+        }
+    }
     /**
      * Close every open change request either of whose branches no longer exists.
      *
@@ -1540,13 +2327,13 @@ export class WorkflowService {
             live = new Set(branches.map((b) => b.name));
         }
         catch (err) {
-            console.warn('[cr] branch sweep skipped — could not list branches:', err);
+            crLog.warn('branch sweep skipped — could not list branches:', { err });
             return 0;
         }
         // An empty branch list means something is wrong with the clone, not that
         // every branch in the repo was deleted at once. Refuse to act on it.
         if (live.size === 0) {
-            console.warn('[cr] branch sweep skipped — branch list came back empty');
+            crLog.warn('branch sweep skipped — branch list came back empty');
             return 0;
         }
         let closed = 0;
@@ -1573,7 +2360,7 @@ export class WorkflowService {
                 continue;
             this.prs.invalidateDetailCache(cr.number);
             this.events?.emit({ kind: 'change-request-rejected', number: cr.number });
-            console.log(`[cr] closed change request #${cr.number}: branch "${missing}" no longer exists`);
+            crLog.info(`closed change request #${cr.number}: branch "${missing}" no longer exists`);
             closed++;
         }
         return closed;
@@ -1599,10 +2386,10 @@ export class WorkflowService {
         this.sweepKick = this.closeChangeRequestsWithDeletedBranches()
             .then((n) => {
             if (n > 0) {
-                console.log(`[cr] on-demand sweep closed ${n} stranded change request${n === 1 ? '' : 's'}`);
+                crLog.info(`on-demand sweep closed ${n} stranded change request${n === 1 ? '' : 's'}`);
             }
         })
-            .catch((err) => console.warn('[cr] on-demand deleted-branch sweep failed:', err))
+            .catch((err) => crLog.warn('on-demand deleted-branch sweep failed:', { err }))
             .finally(() => {
             this.sweepKick = null;
         });
@@ -1693,7 +2480,7 @@ export class WorkflowService {
         // roles.yaml differs from the base branch's, we restore the base version on
         // the source branch (commit + push) BEFORE merging, so the merged diff
         // carries no roles.yaml change. roles.yaml is mutable ONLY via the admin
-        // Roles & Members surface (itself admin-gated). The rest of the CR merges
+        // App roles surface (itself admin-gated). The rest of the CR merges
         // normally. Best-effort by design is NOT acceptable here — a failure to
         // neutralise must abort the merge, never fall through.
         const preserved = await this.preserveBaseRolesYaml(number, user, baseBranch);
@@ -1730,17 +2517,30 @@ export class WorkflowService {
             }
             throw err;
         }
-        // The merge landed on `origin/<baseBranch>`. Pull the
-        // TARGET branch's own workspace so its working tree doesn't fall behind the
-        // remote — the file tools serve the working tree (not origin), so without
-        // 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).
+        await this.pullMergeTarget(baseBranch, user);
+        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 };
+    }
+    /**
+     * The merge landed on `origin/<targetBranch>`. Pull the TARGET branch's own
+     * workspace so its working tree doesn't fall behind the remote — the file
+     * tools serve the working tree (not origin), so without 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).
+     */
+    async pullMergeTarget(targetBranch, user) {
         let targetWorkspaceId;
+        /** Whether the pull below already announced the new tree. See the emit after it. */
+        let announced = false;
         try {
-            const targetWorkspace = await this.workspaceService.getOrCreateForBranch(baseBranch);
+            const targetWorkspace = await this.workspaceService.getOrCreateForBranch(targetBranch);
             targetWorkspaceId = targetWorkspace.id;
-            await this.git.pull(targetWorkspace.id);
+            announced = await this.pullWorkspace(targetWorkspace.id);
         }
         catch (err) {
             // Still best-effort for the merge response (the merge already landed
@@ -1752,14 +2552,243 @@ export class WorkflowService {
             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);
+            mergeLog.warn(`post-merge pull of target "${targetBranch}" failed — its workspace may be momentarily behind origin`, {
+                err,
+            });
         }
+        // THE MERGE ITSELF CHANGED THE TREE, and the pull above almost never says
+        // so. Both callers — applying a change request, and an agent merging a
+        // branch — run `git merge --no-ff` in this very workspace and push the
+        // result, so by the time we pull, the clone is already at origin: the pull
+        // reports "up to date", `treeChanged` is false, and nothing is announced —
+        // while the working tree holds a `.tool` or a `SKILL.md` that was not
+        // there a second ago.
+        //
+        // Nothing else covers it. `change-request-merged` carries no branch and no
+        // workspace, so the catalog subscriber cannot act on it; a later
+        // `POST /api/sync/<branch>` answers "up-to-date" without pulling, for the
+        // same reason. So an approved tool stayed invisible — to every open MCP
+        // connection and every browser — until some unrelated write to the default
+        // branch happened to drop the caches, or the catalogs' own TTL ran out.
+        // That is the merge path of "whichever path made the commit".
+        //
+        // Emitted only when the pull did not already: on the rare path where the
+        // clone WAS behind (someone else pushed between the merge and the pull),
+        // the pull announced the same tree and a second event buys a duplicate
+        // re-scan and a duplicate browser refetch.
+        //
+        // A pull that FAILED is still announced, and that is not a guess about a
+        // tree nobody reconciled. The merge ran in THIS workspace — the target
+        // branch's own, resolved above — before pushing, so the merged bytes were
+        // on that disk before the pull was attempted, and a pull that could not
+        // run cannot un-merge them. (For a change request, `targetBranch` is the
+        // branch the merge acted on: `preserveBaseRolesYaml` refuses the merge
+        // outright if it disagrees with the request's own base.) The failure the
+        // pull reports is about OTHER people's commits not arriving, which leaves
+        // the catalogs no staler than they were.
+        if (!announced && targetWorkspaceId && targetBranch === DEFAULT_BRANCH) {
+            this.events?.emit({ kind: 'fs-tree-changed', workspaceId: targetWorkspaceId, branch: DEFAULT_BRANCH });
+        }
+    }
+    async mergeBranch(user, sourceBranch, targetBranch) {
+        if (sourceBranch === targetBranch) {
+            throw new WorkflowValidationError(`\`source\` and \`target\` are both "${sourceBranch}" — name two different branches.`);
+        }
+        // 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,
+        // seconds of it), so the "no open request" answer below is only sound
+        // while they are held: a bare read would let a person open the request
+        // mid-merge and the agent would land its content anyway, which is the one
+        // thing this tool exists to prevent. `runOnBranchPair` drops a protected
+        // target's key; the source key is held either way, and every competing
+        // request from this source takes it too.
+        return this.runOnBranchPair(sourceBranch, targetBranch, async () => {
+            // 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);
+            // 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))) {
+                throw new WorkflowValidationError(`No branch named "${sourceBranch}" on the shared remote.`);
+            }
+            const result = await this.git.mergeChangeRequest(targetWorkspaceId, sourceBranch, targetBranch, {
+                subject: `Merge ${sourceBranch} into ${targetBranch}`,
+                body: `Merged via Bevel by ${user.name} <${user.email}>`,
+            }, user, {
+                // The merge resets that workspace to the published target tip, which
+                // would throw away edits still on their way out. Refuse until they
+                // are shared — asked inside the merge's own reservation, so a save
+                // cannot land between the question and the reset.
+                requireCleanTarget: true,
+                // Into a protected branch, a merge is a commit of every file it
+                // changes: allowed only for a caller who could commit each of them
+                // directly (the same at-HEAD rule the write lock applies). The hook
+                // runs inside that reservation too, against the target tip this
+                // merge is built on rather than a workspace HEAD that may be behind
+                // it — so the rules read are the ones the merge is about to change.
+                //
+                // `changedPaths` is the authorizing set: roles.yaml kept (unlike a
+                // change request's merge, nothing strips it here — so its presence
+                // is what the hook refuses on) and both sides of a rename, since the
+                // old name is a file this merge deletes.
+                authorize: isProtectedBranch(targetBranch)
+                    ? async ({ sha, changedPaths }) => {
+                        if (changedPaths.length === 0)
+                            return;
+                        // roles.yaml never changes through a merge. A change request's
+                        // merge restores the target's copy on the source first
+                        // (`preserveBaseRolesYaml`): a draft is a free-for-all, and the
+                        // merge is what lands its content on a protected branch. This
+                        // path lands draft content the same way, so it refuses rather
+                        // than authorizing — even an admin, who could write the file
+                        // directly, gets the app's roles surface for that, where the
+                        // file is validated (parsable, groups that exist); the agent's
+                        // own write tools refuse it under the same guard. A merged
+                        // roles.yaml would bypass both, on the one file the access
+                        // model cannot survive being wrong.
+                        if (changedPaths.includes('roles.yaml')) {
+                            throw new WorkflowDomainError(`"${targetBranch}" is protected and this merge would change its roles.yaml. ` +
+                                `Roles never change through a merge: restore roles.yaml on "${sourceBranch}" to the version on ` +
+                                `"${targetBranch}" and merge again, and ask the user to change roles in the app.`, 403, { kind: 'protected-merge-changes-roles', targetBranch, sourceBranch });
+                        }
+                        const allowed = await this.accessControl.canWriteBatchAtRef(targetWorkspaceId, sha, user.email, changedPaths);
+                        const denied = allowed ? changedPaths.filter((p) => !allowed.get(p)) : [];
+                        if (denied.length === 0)
+                            return;
+                        throw new WorkflowDomainError(`"${targetBranch}" is protected and you cannot commit directly to it: ` +
+                            `${denied.length} changed file(s) are outside your write access (${denied.join(', ')}). ` +
+                            `Open a change request from "${sourceBranch}" into "${targetBranch}" and ask the user to review it in the app.`, 403, { kind: 'protected-merge-target', targetBranch, deniedPaths: denied });
+                    }
+                    : undefined,
+            });
+            if (result.kind === 'conflicts') {
+                return { kind: 'conflicts-need-resolution', conflictedPaths: result.paths };
+            }
+            await this.pullMergeTarget(targetBranch, user);
+            return { kind: 'merged', sha: result.sha };
+        });
+    }
+    /**
+     * Start an apply attempt on `number` and return its token. Only the latest
+     * attempt may record a refusal: when two people apply the same request at
+     * once, an older attempt that finishes last must not overwrite the newer
+     * one's verdict. In-process, like the detail and list caches this reads with.
+     * Every attempt must be ended with `endApplyAttempt`.
+     */
+    beginApplyAttempt(number) {
+        const attempt = ++this.applyAttemptSeq;
+        this.applyAttempts.set(number, attempt);
+        return attempt;
+    }
+    /**
+     * An attempt finished. Its entry leaves only if no newer attempt replaced it;
+     * an older attempt ending later then finds no entry and records nothing,
+     * because its token can never match one issued again.
+     */
+    endApplyAttempt(number, attempt) {
+        if (this.applyAttempts.get(number) === attempt)
+            this.applyAttempts.delete(number);
+    }
+    /**
+     * Persist why an apply did not land and tell every session. The apply route
+     * already answers the clicker directly (user-scoped `merge-failed`); this is
+     * for everyone else who can see the still-open request — above all its
+     * author, who otherwise sees it pending forever with no word of the refusal.
+     * The event carries only the number: the reason is read back through the
+     * list and detail endpoints, so a session that misses the event gets the
+     * same answer on its next fetch.
+     *
+     * Returns false, writing and announcing nothing, when a newer attempt has
+     * started since `attempt` or the request is no longer open (a concurrent
+     * apply landed it) — a refusal nobody can act on must not reach anyone.
+     */
+    async recordApplyFailure(number, failure, user, attempt) {
+        if (this.applyAttempts.get(number) !== attempt)
+            return false;
+        const at = failure.at ?? new Date();
+        const updated = await this.db
+            .update(changeRequests)
+            .set({
+            applyFailureReason: sanitizeError(failure.reason, { maxLen: APPLY_FAILURE_MAX_LEN }),
+            applyFailureConflicts: failure.kind === 'conflicts',
+            applyFailureKind: failure.kind,
+            applyFailedAt: at,
+            applyFailedByName: user.name,
+        })
+            // The write itself refuses to go backwards: the attempt map above is an
+            // early exit within this process, but an older UPDATE still in flight (or
+            // one from another replica) must never replace a newer refusal.
+            .where(and(eq(changeRequests.number, number), eq(changeRequests.state, 'open'), or(isNull(changeRequests.applyFailedAt), lt(changeRequests.applyFailedAt, at))))
+            .returning({ number: changeRequests.number });
+        if (updated.length === 0)
+            return false;
         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 };
+        this.events?.emit({ kind: 'change-request-apply-failed', number });
+        return true;
+    }
+    /**
+     * Forget a request's recorded refusal because a change made it obsolete.
+     * Otherwise the request keeps saying "<name> could not apply this: Waiting on
+     * approval…" after the approval arrived, with nothing dating it.
+     *
+     * WHICH refusals a change makes obsolete is `kinds`: an approval answers only
+     * the gate — a conflict or a git error is untouched by it and must keep
+     * saying so — while a moved source head replaces the revision every kind of
+     * refusal described (omit `kinds` to clear any). A row with no recorded kind
+     * is only cleared by the latter. `recordedBefore` is taken before the change
+     * starts: a refusal recorded after it is newer than the change and stays. Announced on the same event a new refusal
+     * uses — every list and open dialog re-reads the request. Best-effort: the
+     * mutation that triggered it already happened and must not fail on this.
+     */
+    /**
+     * Whether the merge gate would now let an apply through without bypass — no
+     * hard reason, no warning. Part of the best-effort clear: an evaluation that
+     * fails answers "no" (the refusal stays) instead of failing the approval.
+     */
+    gateWouldPass(number, approvals) {
+        try {
+            const gate = this.reviewWorkflow.evaluateMergeGate({ prNumber: number, state: 'open', approvals });
+            return gate?.mergeable === true && gate.warnings.length === 0;
+        }
+        catch (err) {
+            crLog.warn(`could not re-evaluate the merge gate of change request #${number}; keeping its refusal:`, { err });
+            return false;
+        }
+    }
+    async clearApplyFailure(number, scope) {
+        const { kinds, recordedBefore } = scope;
+        try {
+            const cleared = await this.db
+                .update(changeRequests)
+                .set({
+                applyFailureReason: null,
+                applyFailureConflicts: null,
+                applyFailedAt: null,
+                applyFailedByName: null,
+                applyFailureKind: null,
+            })
+                .where(and(eq(changeRequests.number, number), isNotNull(changeRequests.applyFailedAt), 
+            // Only a refusal that PREDATES the change: one an apply recorded
+            // while the change was landing may already have seen it, and is
+            // the newer verdict — never erase it.
+            lt(changeRequests.applyFailedAt, recordedBefore), kinds ? inArray(changeRequests.applyFailureKind, [...kinds]) : undefined))
+                .returning({ number: changeRequests.number });
+            if (cleared.length === 0)
+                return;
+            this.prs.invalidateDetailCache(number);
+            this.events?.emit({ kind: 'change-request-apply-failed', number });
+        }
+        catch (err) {
+            crLog.warn(`could not clear the recorded apply failure of change request #${number}:`, { err });
+        }
     }
     /**
      * Best-effort retirement of a merged change request's source branch — the
@@ -1806,11 +2835,13 @@ export class WorkflowService {
                 // "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}"`);
+                mergeLog.info(`retired merged source branch "${sourceBranch}"`);
             });
         }
         catch (err) {
-            console.warn(`[merge] could not retire the merged source branch of change request #${number} (non-fatal):`, err);
+            mergeLog.warn(`could not retire the merged source branch of change request #${number} (non-fatal):`, {
+                err,
+            });
         }
     }
     /**
@@ -1916,7 +2947,7 @@ export class WorkflowService {
             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).
-            console.warn(`[merge] roles.yaml preservation failed for #${number}:`, detail);
+            mergeLog.warn(`roles.yaml preservation failed for #${number}:`, { detail });
             throw new RolesYamlPreservationError(detail);
         }
     }
@@ -1933,7 +2964,9 @@ export class WorkflowService {
             return stdout.split('\n').map((s) => s.trim()).filter(Boolean);
         }
         catch (err) {
-            console.warn('[workflow] listChangedPathsBetweenBranches failed:', redactTokens(err instanceof Error ? err.message : String(err)));
+            log.warn('listChangedPathsBetweenBranches failed:', {
+                detail: redactTokens(err instanceof Error ? err.message : String(err)),
+            });
             return [];
         }
     }
@@ -1958,7 +2991,7 @@ export class WorkflowService {
             resolved = await this.accessControl.eligibleWritersForPathsAtRef(workspaceId, `origin/${targetBranch}`, paths);
         }
         catch (err) {
-            console.warn('[workflow] eligibleWritersForPathsAtRef failed:', err instanceof Error ? err.message : String(err));
+            log.warn('eligibleWritersForPathsAtRef failed:', { err });
         }
         if (!resolved || resolved.size === 0)
             return '';