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

package/src/modules/workflow/workflow.service.ts

@@ -18,6 +18,15 @@
  */
 
 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';
@@ -25,24 +34,36 @@ import type {
   AcquireLockResult,
   AuthUser,
   Branch,
+  BranchSyncOutcome,
   BranchWorkspaceStatus,
   CancelChangeRequestResult,
   Change,
   ChangeInput,
   ChangeRequest,
+  ChangeRequestApplyFailureKind,
   ChangeRequestComment,
   ChangeRequestDetail,
   ChangeRequestState,
   ChangedFile,
   FileApproval,
   FileLock,
+  FolderChangeRequest,
+  FolderChangeRequestRemoval,
   IWorkflowService,
+  MergeBranchOutcome,
   MergeChangeRequestOutcome,
   OpenChangeRequestInput,
   PostChangeRequestCommentInput,
+  RemoteSyncPullResult,
 } from '@bevel-software/platform-shared';
-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 type { Database } from '../database/connection.js';
 import { changeRequests } from '../database/schema.js';
 import type { GitService } from './git/git.service.js';
@@ -52,30 +73,38 @@ import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { FileLockService } from './file-lock.service.js';
+import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
 import { PendingCommitsService } from './pending-commits.service.js';
 import type { WorkflowEventBus } from './event-bus.js';
 import { sanitizeError } from './sanitize-error.js';
 import type { FileChangeNotifier } from '../kb-fs/file-change-notifier.js';
 import { WorkflowHooks } from './workflow-hooks.js';
 import { WorkspaceMutex } from '../kb-fs/mutex.js';
-import { hashEmail } from '../../shared/hash-email.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 type { IChangeReadGate } from '../access-model/change-gate.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
@@ -100,6 +129,33 @@ function isOpenPairViolation(err: unknown): boolean {
   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: string, conflictedPaths: string[]): string {
+  // 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: string): string {
   const tokens = [process.env.GITHUB_TOKEN, process.env.GH_TOKEN].filter(
@@ -130,7 +186,9 @@ const formatWriter = (u: { name: string; email: string }): string =>
  * 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: string[],
@@ -142,6 +200,7 @@ export function formatAffectedOwnersBlock(
   const allUsers = new Map<string, string>(); // email -> display, deduped
   let eligible = 0;
   for (const p of paths) {
+    if (isFolderPlaceholder(p)) continue;
     const info = resolved.get(p);
     if (!info) continue;
     const parts: string[] = [];
@@ -174,6 +233,28 @@ export function formatAffectedOwnersBlock(
   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: string, short: string): string {
+  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: string): string => repoRelPath.split('/').pop() ?? repoRelPath;
+
+/** `Docs/Sub` and `Docs/Sub/` both → `Docs/Sub/`: a prefix that cannot match `Docs/Subway`. */
+function folderPrefix(folder: string): string {
+  return `${folder.replace(/\/+$/, '')}/`;
+}
+
 export class WorkflowService implements IWorkflowService {
   /**
    * Concrete `PullRequestService` (not the interface) so the facade can call
@@ -211,6 +292,13 @@ export class WorkflowService implements IWorkflowService {
      */
     private readonly pendingCommits: PendingCommitsService,
     private readonly kbDirName: string,
+    /**
+     * 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.
+     */
+    private readonly changeGate: IChangeReadGate,
     /**
      * Event bus that fans state changes out to connected SSE sessions.
      * Optional so test harnesses / minimal boots can omit it — emits
@@ -235,7 +323,13 @@ export class WorkflowService implements IWorkflowService {
      * exercise hooks) unchanged.
      */
     public readonly hooks: WorkflowHooks = new WorkflowHooks(),
-  ) {}
+  ) {
+    // 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 ──────────────────────────────────────────────────────────────
 
@@ -246,7 +340,10 @@ export class WorkflowService implements IWorkflowService {
    */
   private orphanSweepStarted = false;
 
-  async listBranches(workspaceId: string, opts?: { freshFetch?: boolean }): Promise<Branch[]> {
+  async listBranches(
+    workspaceId: string,
+    opts?: { freshFetch?: boolean; strictFetch?: boolean },
+  ): Promise<Branch[]> {
     const branches = await this.git.listBranches(workspaceId, opts);
     if (!this.orphanSweepStarted) {
       this.orphanSweepStarted = true;
@@ -257,18 +354,25 @@ export class WorkflowService implements IWorkflowService {
         .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: string, name: string, fromBase?: string): Promise<Branch> {
-    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),
+    );
   }
 
   /**
@@ -413,10 +517,7 @@ export class WorkflowService implements IWorkflowService {
         await this.workspaceService.deleteWorkspace(branchWorkspaceId);
       }
     } 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 });
     }
   }
 
@@ -445,9 +546,43 @@ export class WorkflowService implements IWorkflowService {
     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.
+   */
+  private async pullWorkspace(workspaceId: string): Promise<boolean> {
+    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: string, user?: AuthUser): Promise<void> {
     try {
-      await this.git.pull(workspaceId);
+      await this.pullWorkspace(workspaceId);
     } catch (err) {
       if (err instanceof PullRebaseConflictError) {
         await this.queuePullConflictRecovery(workspaceId, err, user);
@@ -456,6 +591,166 @@ export class WorkflowService implements IWorkflowService {
     }
   }
 
+  async retireRemoteGoneClone(workspaceId: string): Promise<boolean> {
+    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.
+   */
+  private static readonly 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.
+   */
+  private readonly owedAnnouncements = new Map<string, { after: string; changedPaths: string[] }>();
+
+  /**
+   * 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.
+   */
+  private readonly applyAttempts = new Map<number, number>();
+  /** Process-wide attempt counter: a token is never reissued, even after its entry leaves. */
+  private applyAttemptSeq = 0;
+
+  async syncWorkspaceFromRemote(workspaceId: string): Promise<BranchSyncOutcome> {
+    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: RemoteSyncPullResult;
+    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: BranchSyncOutcome =
+      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
@@ -496,15 +791,12 @@ export class WorkflowService implements IWorkflowService {
         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 });
     }
   }
 
@@ -574,6 +866,23 @@ export class WorkflowService implements IWorkflowService {
     return this.git.diffFileBetweenBranches(workspaceId, path, fromBranch, toBranch);
   }
 
+  fileAtForkPoint(
+    workspaceId: string,
+    baseBranch: string,
+    sha: string,
+    path: string,
+  ): Promise<string | null> {
+    return this.git.readFileAtForkPoint(workspaceId, baseBranch, sha, path);
+  }
+
+  changeRequestForkPoint(
+    workspaceId: string,
+    baseBranch: string,
+    headBranch: string,
+  ): Promise<string | null> {
+    return this.git.mergeBaseForPr(workspaceId, baseBranch, headBranch);
+  }
+
   showFileAtChange(workspaceId: string, path: string, sha: string): Promise<string> {
     return this.git.diffFileAtCommit(workspaceId, path, sha);
   }
@@ -601,13 +910,23 @@ export class WorkflowService implements IWorkflowService {
    * 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.
    */
   private async assertCanWriteAtPath(
     workspaceId: string,
     branch: string,
     userEmail: string,
     targetPath: string,
-  ): Promise<void> {
+    /**
+     * 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?: { source: string },
+  ): Promise<'granted' | 'restore'> {
     // 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,
@@ -617,17 +936,36 @@ export class WorkflowService implements IWorkflowService {
     // 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: string): string =>
+      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)
-    if (result.get(repoRelative)) return;
+    if (!result) return 'granted'; // no config at ref → default-allow (bootstrap)
+    if (result.get(repoRelative)) 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`,
@@ -642,13 +980,26 @@ export class WorkflowService implements IWorkflowService {
 
   // ── File locks ────────────────────────────────────────────────────────────
 
+  // 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: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
-    opts?: { coordination?: boolean },
+    opts?: { coordination?: boolean; platformRestore?: { source: string } },
   ): Promise<AcquireLockResult> {
+    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
@@ -658,14 +1009,24 @@ export class WorkflowService implements IWorkflowService {
     // 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
@@ -674,15 +1035,27 @@ export class WorkflowService implements IWorkflowService {
     // 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' | 'restore' = '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
@@ -697,8 +1070,8 @@ export class WorkflowService implements IWorkflowService {
         holderName: user.name,
       });
     } 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;
@@ -707,18 +1080,19 @@ export class WorkflowService implements IWorkflowService {
   async heartbeatLock(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
   ): Promise<FileLock> {
+    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;
     }
@@ -734,10 +1108,11 @@ export class WorkflowService implements IWorkflowService {
   async commitFileWhileLocked(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
     summary?: string,
   ): Promise<Change | null> {
+    const targetPath = canonicalFileIdentity(rawPath);
     const lock = await this.fileLocks.get(workspaceId, branch, targetPath);
     if (!lock || lock.holderUserId !== user.id) {
       throw new WorkflowValidationError(
@@ -782,15 +1157,15 @@ export class WorkflowService implements IWorkflowService {
         let recoveryError: unknown = 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 },
             );
           }
         }
@@ -809,10 +1184,7 @@ export class WorkflowService implements IWorkflowService {
           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({
@@ -861,21 +1233,20 @@ export class WorkflowService implements IWorkflowService {
   async releaseLock(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
   ): Promise<void> {
+    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).`,
@@ -892,8 +1263,8 @@ export class WorkflowService implements IWorkflowService {
     // 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.`,
@@ -918,8 +1289,8 @@ export class WorkflowService implements IWorkflowService {
       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
@@ -1021,7 +1392,7 @@ export class WorkflowService implements IWorkflowService {
     // emitted id so every consumer sees one spelling.
     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 });
   }
 
@@ -1033,7 +1404,34 @@ export class WorkflowService implements IWorkflowService {
    * machinery is unaffected — all this adds is that someone finds out, rather
    * than the deployment looking healthy while nothing reaches the remote.
    */
-  private noteGitSyncFailed(workspaceId: string, branch: string, err: unknown): void {
+  private noteGitSyncFailed(
+    workspaceId: string,
+    branch: string,
+    err: unknown,
+    /**
+     * 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?: { paths: string[]; message: string },
+  ): void {
+    // 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);
@@ -1043,7 +1441,8 @@ export class WorkflowService implements IWorkflowService {
       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 } : {}),
     });
   }
 
@@ -1102,19 +1501,19 @@ export class WorkflowService implements IWorkflowService {
       let recoveryError: unknown = 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 },
           );
         }
       }
@@ -1127,9 +1526,9 @@ export class WorkflowService implements IWorkflowService {
         // 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);
       }
@@ -1148,22 +1547,23 @@ export class WorkflowService implements IWorkflowService {
   async releaseLockNoCommit(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
   ): Promise<void> {
+    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;
     }
@@ -1191,10 +1591,9 @@ export class WorkflowService implements IWorkflowService {
       } 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;
@@ -1206,15 +1605,14 @@ export class WorkflowService implements IWorkflowService {
         // 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',
@@ -1253,22 +1651,23 @@ export class WorkflowService implements IWorkflowService {
   async releaseLockUntouched(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
   ): Promise<void> {
-    console.log(
-      `[lock] RELEASE-UNTOUCHED start ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id}`,
+    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',
@@ -1280,8 +1679,10 @@ export class WorkflowService implements IWorkflowService {
     // nothing on disk moved.
   }
 
-  hasQueuedCommit(workspaceId: string, branch: string, targetPath: string): Promise<boolean> {
-    return this.pendingCommits.hasLiveRowFor(workspaceId, branch, targetPath);
+  hasQueuedCommit(workspaceId: string, branch: string, rawPath: string): Promise<boolean> {
+    // 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: string): Promise<boolean> {
@@ -1291,9 +1692,9 @@ export class WorkflowService implements IWorkflowService {
   getLock(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
   ): Promise<FileLock | null> {
-    return this.fileLocks.get(workspaceId, branch, targetPath);
+    return this.fileLocks.get(workspaceId, branch, canonicalFileIdentity(rawPath));
   }
 
   // ── Change Requests ───────────────────────────────────────────────────────
@@ -1449,7 +1850,7 @@ export class WorkflowService implements IWorkflowService {
           targetBranch: input.targetBranch,
           title: input.title.trim(),
           body,
-          authorEmail: user.email.trim().toLowerCase(),
+          authorEmail: canonicalEmail(user.email),
           authorName: user.name,
         })
         .returning({ number: changeRequests.number });
@@ -1531,10 +1932,20 @@ export class WorkflowService implements IWorkflowService {
    * 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: string,
@@ -1554,6 +1965,51 @@ export class WorkflowService implements IWorkflowService {
         { 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,
@@ -1567,6 +2023,8 @@ export class WorkflowService implements IWorkflowService {
     // 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, {
@@ -1579,6 +2037,51 @@ export class WorkflowService implements IWorkflowService {
         `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;
   }
 
@@ -1623,6 +2126,8 @@ export class WorkflowService implements IWorkflowService {
     authorIdHash: string | null,
     workspaceId: string,
   ): Promise<FileApproval[]> {
+    // Taken BEFORE the approval lands (see `clearApplyFailure`).
+    const approvedAfter = new Date();
     const approvals = await this.reviewWorkflow.approveFile(
       number,
       path,
@@ -1633,6 +2138,14 @@ export class WorkflowService implements IWorkflowService {
       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',
@@ -1675,6 +2188,29 @@ export class WorkflowService implements IWorkflowService {
     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.
+   */
+  private async placeholderRevertedWith(
+    workspaceId: string,
+    mergeBase: string,
+    repoRelPath: string,
+    changedPaths: string[],
+  ): Promise<string | null> {
+    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
@@ -1704,13 +2240,15 @@ export class WorkflowService implements IWorkflowService {
     }
     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);
@@ -1736,42 +2274,373 @@ export class WorkflowService implements IWorkflowService {
       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: string[] = [];
+    let revertError: { reason: unknown } | null = 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, // skipValidator — this restores an already-validated base version
-      );
+      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, // skipValidator — this restores an already-validated base version
+        );
+      }
       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 is PromiseRejectedResult => 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: string, user: AuthUser): Promise<FolderChangeRequest[]> {
+    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<string, Promise<string>>();
+    const baseWorkspace = (base: string): Promise<string> => {
+      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<string, Promise<boolean>>();
+    const adminOn = (base: string): Promise<boolean> => {
+      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: string, paths: string[]): Promise<boolean> => {
+      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 }): Promise<FolderChangeRequest> => {
+        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: string,
+    user: AuthUser,
+  ): Promise<FolderChangeRequestRemoval[]> {
+    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: { number: number; branch: string; wsId: string; paths: string[]; mergeBase: string | null }[] = [];
+    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: string | null = 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<
+      string,
+      { wsId: string; branch: string; plans: typeof plans; paths: { path: string; mergeBase: string }[] }
+    >();
+    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: { wsId: string; branch: string; lockPath: string }[] = [];
+    // 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: typeof toChange = [];
+    let pushFailure: { group: (typeof toChange)[number]; err: unknown } | null = 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: FolderChangeRequestRemoval[] = [];
+    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: string[] = [];
+      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
@@ -1875,23 +2744,29 @@ export class WorkflowService implements IWorkflowService {
    * 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: number, user: AuthUser): Promise<boolean> {
     const summary = await this.prs.getPr(number);
     if (!summary || summary.state !== 'open') return false;
     let paths: string[];
+    let wsId: string;
     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.
@@ -1908,6 +2783,21 @@ export class WorkflowService implements IWorkflowService {
     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.
+   */
+  private async savesInFlight(wsId: string): Promise<boolean> {
+    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.
    *
@@ -1971,13 +2861,13 @@ export class WorkflowService implements IWorkflowService {
       });
       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;
     }
 
@@ -2003,9 +2893,7 @@ export class WorkflowService implements IWorkflowService {
       if (updated.length === 0) 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;
@@ -2031,12 +2919,10 @@ export class WorkflowService implements IWorkflowService {
     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;
       });
@@ -2161,7 +3047,7 @@ export class WorkflowService implements IWorkflowService {
     // 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);
@@ -2211,17 +3097,31 @@ export class WorkflowService implements IWorkflowService {
       }
       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).
+   */
+  private async pullMergeTarget(targetBranch: string, user: AuthUser): Promise<void> {
     let targetWorkspaceId: string | undefined;
+    /** 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
       // on origin) — but a rebase CONFLICT here means the target workspace
@@ -2232,17 +3132,289 @@ export class WorkflowService implements IWorkflowService {
       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`,
+      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: AuthUser, sourceBranch: string, targetBranch: string): Promise<MergeBranchOutcome> {
+    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: number): 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: number, attempt: number): void {
+    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: number,
+    failure: { reason: string; kind: ChangeRequestApplyFailureKind; at?: Date },
+    user: AuthUser,
+    attempt: number,
+  ): Promise<boolean> {
+    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.
+   */
+  private gateWouldPass(number: number, approvals: FileApproval[]): boolean {
+    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;
+    }
+  }
+
+  private async clearApplyFailure(
+    number: number,
+    scope: { kinds?: readonly ChangeRequestApplyFailureKind[]; recordedBefore: Date },
+  ): Promise<void> {
+    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 });
+    }
   }
 
   /**
@@ -2293,13 +3465,12 @@ export class WorkflowService implements IWorkflowService {
         // "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):`,
+      mergeLog.warn(`could not retire the merged source branch of change request #${number} (non-fatal):`, {
         err,
-      );
+      });
     }
   }
 
@@ -2423,7 +3594,7 @@ export class WorkflowService implements IWorkflowService {
       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);
     }
   }
@@ -2448,10 +3619,9 @@ export class WorkflowService implements IWorkflowService {
       );
       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 [];
     }
   }
@@ -2483,10 +3653,7 @@ export class WorkflowService implements IWorkflowService {
         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 '';