@bevel-software/platform-core-backend 0.4.1 → 0.5.1

package/src/modules/workflow/__tests__/event-bus.test.ts

@@ -319,4 +319,39 @@ describe('WorkflowEventBus', () => {
       expect(bus.size()).toBe(0);
     });
   });
+
+  describe('onEmit — the server-side tap', () => {
+    it('sees every event, unfiltered by SSE scope, and unsubscribes cleanly', () => {
+      const bus = new WorkflowEventBus();
+      const seen: string[] = [];
+      const off = bus.onEmit((e) => seen.push(e.kind));
+      // A workspace-scoped event with NO matching SSE session still reaches
+      // the tap — scope filtering exists for sessions, not in-process
+      // consumers (write-time cache invalidation must never miss one).
+      bus.emit({ kind: 'fs-tree-changed', workspaceId: 'ws-1', branch: 'main' });
+      expect(seen).toEqual(['fs-tree-changed']);
+      off();
+      bus.emit({ kind: 'fs-tree-changed', workspaceId: 'ws-1', branch: 'main' });
+      expect(seen).toEqual(['fs-tree-changed']);
+    });
+
+    it('a throwing listener is contained — emit never propagates it', () => {
+      const bus = new WorkflowEventBus();
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      bus.onEmit(() => {
+        throw new Error('bad listener');
+      });
+      const after: string[] = [];
+      bus.onEmit((e) => after.push(e.kind));
+      expect(() =>
+        bus.emit({ kind: 'fs-tree-changed', workspaceId: 'ws-1', branch: 'main' }),
+      ).not.toThrow();
+      // …and the listeners after the bad one still ran.
+      expect(after).toEqual(['fs-tree-changed']);
+      // The containment is LOGGED, not silent — a listener dying quietly
+      // would be undebuggable.
+      expect(warn).toHaveBeenCalledWith('[event-bus] onEmit listener threw:', 'bad listener');
+      warn.mockRestore();
+    });
+  });
 });

package/src/modules/workflow/__tests__/workflow.service.facade.test.ts

@@ -15,10 +15,17 @@ import { WorkflowService } from '../workflow.service.js';
 import { PullRebaseConflictError } from '../workflow.errors.js';
 import type { Database } from '../../database/connection.js';
 
-// The facade tests never exercise `openChangeRequest` (the only method that
-// touches the DB), so a bare stub is enough to satisfy the constructor.
-function makeDb(): Database {
-  return {} as unknown as Database;
+// `deleteBranch`'s open-request guard is the only DB touch these tests
+// exercise: a chainable select→from→where→limit stub resolving `rows` covers
+// it (rows default to "no open request").
+function makeDb(rows: unknown[] = []): Database {
+  const chain = {
+    select: vi.fn(() => chain),
+    from: vi.fn(() => chain),
+    where: vi.fn(() => chain),
+    limit: vi.fn(async () => rows),
+  };
+  return chain as unknown as Database;
 }
 
 function makeWorkspaceService(): WorkspaceService {
@@ -29,6 +36,9 @@ function makeWorkspaceService(): WorkspaceService {
     getWorkspacePath: vi.fn().mockResolvedValue('/tmp/ws'),
     sweepOrphanedWorkspaces: vi.fn().mockResolvedValue({ removed: [] }),
     getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: encodeURIComponent(branch) })),
+    ensureRemotesFetched: vi.fn().mockResolvedValue(undefined),
+    hasBootstrappedWorkspace: vi.fn().mockResolvedValue(false),
+    deleteWorkspace: vi.fn().mockResolvedValue(undefined),
   } as unknown as WorkspaceService;
 }
 
@@ -130,7 +140,6 @@ function makeGit(): GitService {
     diffStat: vi.fn(),
     pendingChanges: vi.fn(),
     resolveForkBase: vi.fn(),
-    revertCommit: vi.fn(),
     logForFile: vi.fn(),
     diffFileAtCommit: vi.fn(),
     diffFileBetweenBranches: vi.fn(),
@@ -412,6 +421,48 @@ describe('WorkflowService — file lock delegation', () => {
     expect(fileLocks.release).toHaveBeenCalledWith('w1', 'feat', 'Foo.md', expect.any(Object));
   });
 
+  it('deleteBranch refuses while the branch carries an open change request', async () => {
+    const git = makeGit();
+    // One open request rides the branch — deleting it would strand the request.
+    const svc = new WorkflowService(makeDb([{ number: 7 }]), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), 'knowledge-base');
+    await expect(svc.deleteBranch('w1', 'feat/x', makeUser())).rejects.toThrow(/open change request \(#7\)/);
+    expect(git.deleteBranch).not.toHaveBeenCalled();
+  });
+
+  it('deleteBranch deletes when the branch has no open change request', async () => {
+    const git = makeGit();
+    const svc = new WorkflowService(makeDb(), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), 'knowledge-base');
+    await expect(svc.deleteBranch('w1', 'feat/x', makeUser())).resolves.toBeUndefined();
+    expect(git.deleteBranch).toHaveBeenCalledWith('w1', 'feat/x', expect.objectContaining({ email: 'alice@example.com' }), undefined);
+  });
+
+  /**
+   * The lifecycle lock is what keeps merge-time retirement from deleting a
+   * branch mid-`openChangeRequest`. The full interleaving needs a real git
+   * repo + DB; what IS unit-testable is the lock's contract — two operations
+   * keyed on the same branch never overlap, the second fully waiting out the
+   * first.
+   */
+  it('serialises same-branch lifecycle operations', async () => {
+    const order: string[] = [];
+    const git = makeGit();
+    let releaseFirst!: () => void;
+    const gate = new Promise<void>((resolve) => { releaseFirst = resolve; });
+    vi.mocked(git.deleteBranch)
+      .mockImplementationOnce(async () => { order.push('first:start'); await gate; order.push('first:end'); })
+      .mockImplementationOnce(async () => { order.push('second'); });
+    const svc = new WorkflowService(makeDb(), git, makePrs(), makeReviewWorkflow(), makeWorkspaceService(), makeAccessControl(), makeFileLockService(), makePendingCommits(), 'knowledge-base');
+    const first = svc.deleteBranch('w1', 'feat/x', makeUser());
+    const second = svc.deleteBranch('w1', 'feat/x', makeUser());
+    // Only release the gate once the first operation is provably inside its
+    // critical section — otherwise a non-serialised second could sneak
+    // through before 'first:start' and the assertion would not distinguish.
+    await vi.waitFor(() => { expect(order).toContain('first:start'); });
+    releaseFirst();
+    await Promise.all([first, second]);
+    expect(order).toEqual(['first:start', 'first:end', 'second']);
+  });
+
   it('releaseLock refuses when the caller does not hold the lock', async () => {
     const git = makeGit();
     const fileLocks = makeFileLockService(); // default: get → null
@@ -422,3 +473,198 @@ describe('WorkflowService — file lock delegation', () => {
     expect(git.commitFile).not.toHaveBeenCalled();
   });
 });
+
+/**
+ * The reviewer's per-file scalpel, and the empty-close it can trigger. All
+ * collaborators stubbed — what's under test is the orchestration: the auth
+ * predicate, the restore→commit→push order, the lock discipline, and the
+ * authoritative emptiness re-check before anything closes.
+ */
+describe('WorkflowService — revertChangeRequestFile / closeEmptyChangeRequest', () => {
+  const SUMMARY = { number: 7, base: 'main', branch: 'ali/x', state: 'open' };
+
+  function makeRevertGit(overrides: Record<string, unknown> = {}): GitService {
+    return Object.assign(makeGit(), {
+      pull: vi.fn().mockResolvedValue(undefined),
+      changedPathsForPr: vi.fn().mockResolvedValue(['Docs/a.md', 'Docs/b.md']),
+      mergeBaseForPr: vi.fn().mockResolvedValue('mb-sha'),
+      restorePathFromRef: vi.fn().mockResolvedValue(undefined),
+      commitFile: vi.fn().mockResolvedValue({}),
+      push: vi.fn().mockResolvedValue(undefined),
+      ...overrides,
+    }) as unknown as GitService;
+  }
+
+  function makeHarness(opts: {
+    git?: GitService;
+    canWriteAtRef?: boolean | null;
+    prState?: string;
+    updateRows?: unknown[];
+  } = {}) {
+    const git = opts.git ?? makeRevertGit();
+    const prs = makePrs();
+    (prs.getPr as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ...SUMMARY,
+      state: opts.prState ?? 'open',
+    });
+    const access = makeAccessControl();
+    (access.canWriteAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(
+      opts.canWriteAtRef ?? true,
+    );
+    const fileLocks = makeFileLockService();
+    // The chainable stub answers SELECTs with [] (no open request rows) and
+    // UPDATE...returning with `updateRows` (default: one row = the close won).
+    const updateRows = opts.updateRows ?? [{ id: 1 }];
+    const chain: Record<string, unknown> = {};
+    Object.assign(chain, {
+      select: vi.fn(() => chain),
+      from: vi.fn(() => chain),
+      where: vi.fn(() => chain),
+      limit: vi.fn(async () => []),
+      update: vi.fn(() => chain),
+      set: vi.fn(() => chain),
+      returning: vi.fn(async () => updateRows),
+    });
+    const db = chain as unknown as Database;
+    const svc = new WorkflowService(db, git, prs, makeReviewWorkflow(), makeWorkspaceService(), access, fileLocks, makePendingCommits(), 'knowledge-base');
+    return { svc, git, prs, access, fileLocks, db: chain };
+  }
+
+  it('restores the merge-base copy on the source branch: restore, commit (validator skipped), push — under the file lock', async () => {
+    const { svc, git, prs, fileLocks } = makeHarness();
+    const result = await svc.revertChangeRequestFile(7, makeUser(), 'Docs/a.md');
+
+    expect(git.restorePathFromRef).toHaveBeenCalledWith('ali%2Fx', 'mb-sha', 'Docs/a.md');
+    expect(git.commitFile).toHaveBeenCalledWith(
+      'ali%2Fx',
+      expect.objectContaining({ email: 'alice@example.com' }),
+      'Docs/a.md',
+      expect.stringContaining('change request #7'),
+      true,
+    );
+    expect(git.push).toHaveBeenCalled();
+    expect(fileLocks.acquire).toHaveBeenCalledWith(
+      'ali%2Fx',
+      'ali/x',
+      'knowledge-base/Docs/a.md',
+      expect.anything(),
+    );
+    expect(fileLocks.release).toHaveBeenCalled();
+    expect(prs.invalidateDetailCache).toHaveBeenCalledWith(7);
+    // Both diffs answered two paths → one revert leaves one.
+    expect(result).toEqual({ closed: false, remainingPaths: ['Docs/a.md', 'Docs/b.md'] });
+  });
+
+  it('refuses a caller who could not approve the file — same permission, both verbs', async () => {
+    const { svc, git } = makeHarness({ canWriteAtRef: false });
+    await expect(svc.revertChangeRequestFile(7, makeUser(), 'Docs/a.md')).rejects.toMatchObject({
+      status: 403,
+    });
+    expect(git.restorePathFromRef).not.toHaveBeenCalled();
+    expect(git.push).not.toHaveBeenCalled();
+  });
+
+  it('refuses a path the request does not touch', async () => {
+    const { svc, git } = makeHarness();
+    await expect(svc.revertChangeRequestFile(7, makeUser(), 'Docs/elsewhere.md')).rejects.toMatchObject({
+      status: 422,
+    });
+    expect(git.restorePathFromRef).not.toHaveBeenCalled();
+  });
+
+  it('refuses a request that is no longer open', async () => {
+    const { svc } = makeHarness({ prState: 'closed' });
+    await expect(svc.revertChangeRequestFile(7, makeUser(), 'Docs/a.md')).rejects.toMatchObject({
+      status: 422,
+    });
+  });
+
+  it('closes the request when the LAST file is reverted', async () => {
+    const git = makeRevertGit({
+      changedPathsForPr: vi
+        .fn()
+        // in order: the pre-revert list, the post-revert remainder, and the
+        // close path's own authoritative re-check.
+        .mockResolvedValueOnce(['Docs/a.md'])
+        .mockResolvedValueOnce([])
+        .mockResolvedValueOnce([]),
+    });
+    const { svc, db } = makeHarness({ git });
+    const result = await svc.revertChangeRequestFile(7, makeUser(), 'Docs/a.md');
+    expect(result).toEqual({ closed: true, remainingPaths: [] });
+    expect(db.update).toHaveBeenCalled();
+  });
+
+  it('closeEmptyChangeRequest never closes on a FAILED diff', async () => {
+    const git = makeRevertGit({
+      changedPathsForPr: vi.fn().mockRejectedValue(new Error('git down')),
+    });
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { svc, db } = makeHarness({ git });
+    await expect(svc.closeEmptyChangeRequest(7, makeUser())).resolves.toBe(false);
+    expect(db.update).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('closeEmptyChangeRequest leaves a request with real changes alone', async () => {
+    const { svc, db } = makeHarness();
+    await expect(svc.closeEmptyChangeRequest(7, makeUser())).resolves.toBe(false);
+    expect(db.update).not.toHaveBeenCalled();
+  });
+
+  it('closeEmptyChangeRequest closes an emptied request', async () => {
+    const git = makeRevertGit({ changedPathsForPr: vi.fn().mockResolvedValue([]) });
+    const { svc, db, prs } = makeHarness({ git });
+    await expect(svc.closeEmptyChangeRequest(7, makeUser())).resolves.toBe(true);
+    expect(db.update).toHaveBeenCalled();
+    expect(prs.invalidateDetailCache).toHaveBeenCalledWith(7);
+  });
+});
+
+describe('WorkflowService — deleteChangeRequest (admin moderation verb)', () => {
+  function makeDeleteHarness(opts: { isAdmin?: boolean; prState?: string } = {}) {
+    const git = Object.assign(makeGit(), {
+      changedPathsForPr: vi.fn().mockResolvedValue(['Docs/a.md']),
+    }) as unknown as GitService;
+    const prs = makePrs();
+    (prs.getPr as ReturnType<typeof vi.fn>).mockResolvedValue({
+      number: 9,
+      base: 'main',
+      branch: 'mallory/spam',
+      state: opts.prState ?? 'open',
+    });
+    const access = makeAccessControl();
+    (access.canWriteAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(opts.isAdmin ?? false);
+    const chain: Record<string, unknown> = {};
+    Object.assign(chain, {
+      select: vi.fn(() => chain),
+      from: vi.fn(() => chain),
+      where: vi.fn(() => chain),
+      limit: vi.fn(async () => []),
+      update: vi.fn(() => chain),
+      set: vi.fn(() => chain),
+      returning: vi.fn(async () => [{ id: 1 }]),
+    });
+    const svc = new WorkflowService(chain as unknown as Database, git, prs, makeReviewWorkflow(), makeWorkspaceService(), access, makeFileLockService(), makePendingCommits(), 'knowledge-base');
+    return { svc, prs, db: chain, access };
+  }
+
+  it('refuses a non-admin with 403 and touches nothing', async () => {
+    const { svc, db } = makeDeleteHarness({ isAdmin: false });
+    await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toMatchObject({ status: 403 });
+    expect(db.update).not.toHaveBeenCalled();
+  });
+
+  it('an admin closes the request (row flipped, cache dropped)', async () => {
+    const { svc, prs, db } = makeDeleteHarness({ isAdmin: true });
+    await svc.deleteChangeRequest(9, makeUser());
+    expect(db.update).toHaveBeenCalled();
+    expect(prs.invalidateDetailCache).toHaveBeenCalledWith(9);
+  });
+
+  it('refuses a merged request — applied history is not deletable', async () => {
+    const { svc, db } = makeDeleteHarness({ isAdmin: true, prState: 'merged' });
+    await expect(svc.deleteChangeRequest(9, makeUser())).rejects.toMatchObject({ status: 422 });
+    expect(db.update).not.toHaveBeenCalled();
+  });
+});

package/src/modules/workflow/agent-tools/workflow.tools.ts

@@ -7,7 +7,9 @@ import type { ToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { requireInternalSource } from '../../tool-auth/tool-auth.middleware.js';
 import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
 
-const PROTECTED_INLINE = [...PROTECTED_BRANCHES].map((b) => `\`${b}\``).join(' / ');
+// A function, not a constant: the branch model is applied during boot, and a
+// module-scope capture would freeze this at the empty set that exists before it.
+const protectedInline = () => [...PROTECTED_BRANCHES].map((b) => `\`${b}\``).join(' / ');
 
 // Output sub-schemas for the git-aliased workflow payloads (Branch, Change,
 // ChangeRequestComment, …). Defined once and referenced by the individual tool
@@ -268,7 +270,7 @@ export function registerWorkflowTools(
     name: 'create_branch',
     description:
       'Create a new unprotected draft named `name`, forked from the existing branch `branch`. The ' +
-      `backend rejects protected names (${PROTECTED_INLINE}) and filesystem-invalid names — surface ` +
+      `backend rejects protected names (${protectedInline()}) and filesystem-invalid names — surface ` +
       'those errors verbatim. Convention: `<email-localpart>/<kebab-slug>`. Does NOT switch the ' +
       'agent onto the new draft.',
     // `branch` here is the fork BASE — its own meaning — so skip the generic

package/src/modules/workflow/event-bus.ts

@@ -91,6 +91,21 @@ export class WorkflowEventBus {
   private nextId = 1;
   private readonly buffer: WorkflowEvent[] = [];
   private readonly subscribers = new Map<string, Subscriber>();
+  private readonly emitListeners = new Set<(event: WorkflowEvent) => void>();
+
+  /**
+   * Server-side tap: called for EVERY emitted event, before the per-session
+   * scope filtering (which exists for SSE fan-out, not for in-process
+   * consumers). The composition root uses this for write-time cache
+   * invalidation — the routes emit `fs-tree-changed` the moment bytes hit a
+   * working tree, long before the async commit reaches `FileChangeNotifier`.
+   * Best-effort like SSE dispatch: a throwing listener is logged, never
+   * propagated to the emitter. Returns the unsubscribe.
+   */
+  onEmit(listener: (event: WorkflowEvent) => void): () => void {
+    this.emitListeners.add(listener);
+    return () => this.emitListeners.delete(listener);
+  }
 
   /**
    * Stamp `payload` with `id` + `ts`, append to the ring buffer, then fan
@@ -108,6 +123,16 @@ export class WorkflowEventBus {
     if (this.buffer.length > BUFFER_CAPACITY) {
       this.buffer.shift();
     }
+    for (const listener of this.emitListeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.warn(
+          '[event-bus] onEmit listener threw:',
+          err instanceof Error ? err.message : err,
+        );
+      }
+    }
     // Single-line emit log with all the fields most useful for tracing a
     // failed delivery: which event, which scope it'll filter on, and the
     // total subscriber pool size before fan-out. Per-subscriber matched/

package/src/modules/workflow/file-lock.service.ts

@@ -266,4 +266,21 @@ export class FileLockService {
     }
     return rowToFileLock(row);
   }
+
+  /**
+   * Is ANY unexpired lock held anywhere in this workspace? Feeds the git
+   * status sanity check: a held lock means a mutation is mid-flight — the
+   * file may already be changed (or deleted) on disk while its commit is only
+   * queued at RELEASE — so a dirty tree during that window is expected, not
+   * the "missed lock-release commit" the loud warning is for. Expired rows
+   * don't count (their holder is gone; they explain nothing).
+   */
+  async hasAnyActive(workspaceId: string): Promise<boolean> {
+    const rows = await this.db
+      .select({ path: fileLocks.path })
+      .from(fileLocks)
+      .where(and(eq(fileLocks.workspaceId, workspaceId), gt(fileLocks.expiresAt, new Date())))
+      .limit(1);
+    return rows.length > 0;
+  }
 }

package/src/modules/workflow/git/__tests__/git.service.accessGating.test.ts

@@ -232,55 +232,6 @@ describe('GitService — commit gate uses HEAD (not working tree)', () => {
   });
 });
 
-describe('GitService — revert gate uses HEAD', () => {
-  let root: string;
-  const workspaceId = 'ws-revert-gate';
-
-  beforeEach(async () => {
-    root = await mkTmpRoot();
-  });
-  afterEach(async () => {
-    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
-  });
-
-  it('passes ref=HEAD when gating a revert', async () => {
-    const { ac, calls } = recordingAccessControl();
-    const { svc, repo } = await makeSvc(root, workspaceId, ac);
-    await commitFile(repo, 'Knowledge/Foo.md', 'a\n', 'seed');
-    await commitFile(repo, 'Knowledge/Foo.md', 'b\n', 'second');
-    const { stdout: sha } = await execFileAsync('git', ['-C', repo, 'rev-parse', 'HEAD'], {
-      encoding: 'utf-8',
-    });
-
-    // We only care that the gate is invoked with `HEAD`; downstream
-    // behaviour of `git revert` (which may or may not succeed for unrelated
-    // environmental reasons — author parsing, signing config, etc.) is out
-    // of scope for this test.
-    await svc.revertCommit(workspaceId, USER, sha.trim()).catch(() => undefined);
-
-    const gateCalls = calls.filter((c) => c.method === 'canWriteBatchAtRef');
-    expect(gateCalls).toHaveLength(1);
-    expect(gateCalls[0].ref).toBe('HEAD');
-    expect(gateCalls[0].paths).toContain('Knowledge/Foo.md');
-  });
-
-  it('refuses with AccessDeniedError when the gate denies', async () => {
-    const { ac } = recordingAccessControl({
-      canWriteBatchAtRef: (_ref, _email, paths) => new Map(paths.map((p) => [p, false])),
-    });
-    const { svc, repo } = await makeSvc(root, workspaceId, ac);
-    await commitFile(repo, 'Knowledge/Foo.md', 'a\n', 'seed');
-    await commitFile(repo, 'Knowledge/Foo.md', 'b\n', 'second');
-    const { stdout: sha } = await execFileAsync('git', ['-C', repo, 'rev-parse', 'HEAD'], {
-      encoding: 'utf-8',
-    });
-
-    await expect(svc.revertCommit(workspaceId, USER, sha.trim())).rejects.toBeInstanceOf(
-      AccessDeniedError,
-    );
-  });
-});
-
 describe('GitService — push gate uses origin/<branch> (not HEAD or working tree)', () => {
   let root: string;
   const workspaceId = 'ws-push-gate';
@@ -327,6 +278,15 @@ describe('GitService — push gate uses origin/<branch> (not HEAD or working tre
     expect(gateCalls[0].paths).toContain('Knowledge/Foo.md');
   });
 
+  it('systemAuthorized skips the gate entirely, and the push still lands', async () => {
+    // The group-provisioning path: its endpoint IS the authorization (any
+    // signed-in user may claim an unused name under Groups/), and the gate
+    // could only read the new folder's chain at origin as `write: Admin`.
+    const { svc, calls } = await setupWithOrigin();
+    await svc.push(workspaceId, USER, { systemAuthorized: true });
+    expect(calls.filter((c) => c.method === 'canWriteBatchAtRef')).toHaveLength(0);
+  });
+
   it('refuses the push when origin/<branch> rules deny the caller', async () => {
     const { workspaceDir, repo } = await seedWorkspace(root, workspaceId);
     const originDir = path.join(root, 'origin.git');

package/src/modules/workflow/git/__tests__/git.service.changedFilesForPr.test.ts

@@ -38,6 +38,14 @@ async function seedWorkspace(root: string, workspaceId: string) {
   const repo = path.join(workspaceDir, 'knowledge-base');
   await fs.mkdir(workspaceDir, { recursive: true });
   await runGit(root, ['clone', upstream, repo]);
+  // Repo-local identity, because `GitService` spawns its own git children
+  // with the AMBIENT env — `runGit`'s `GIT_COMMITTER_*` vars never reach
+  // them. A dev machine hides this behind a global git config; a CI runner
+  // has none, so anything committing through the service (here:
+  // `commitFile`) fails with "Committer identity unknown". Same reason
+  // `git.service.commitFile.test.ts` configures its fixture this way.
+  await runGit(repo, ['config', 'user.email', 'test@bevel.local']);
+  await runGit(repo, ['config', 'user.name', 'Test Runner']);
   return { upstream, repo };
 }
 
@@ -121,4 +129,97 @@ describe('GitService.changedFilesForPr / resolvePrShas', () => {
     expect(headSha).toMatch(/^[0-9a-f]{40}$/);
     expect(baseSha).not.toBe(headSha);
   });
+
+  /**
+   * roles.yaml can never change through a merge — `preserveBaseRolesYaml`
+   * restores the base copy onto the source before every merge — so the review
+   * surface must not list it as changed: the claim would be false, the empty
+   * diff reads as a bug, and its per-file approval would gate the merge on a
+   * change that cannot land. Counts stay aligned with the surviving files.
+   */
+  it('excludes roles.yaml from the changed-file list and the touched paths', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    await runGit(repo, ['checkout', '-b', 'mallory/self-promote']);
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles:\n  Admin:\n    - mallory@x.com\n');
+    await fs.writeFile(path.join(repo, 'honest.md'), 'real change\nsecond line\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'work + attempted escalation']);
+    await runGit(repo, ['push', '-u', 'origin', 'mallory/self-promote']);
+
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+
+    const files = await git.changedFilesForPr(
+      workspaceId,
+      'current-company-state',
+      'mallory/self-promote',
+    );
+    expect(files.map((f) => f.path)).toEqual(['honest.md']);
+    // The counts filter moved in step with the statuses filter.
+    expect(files[0].additions).toBe(2);
+
+    const paths = await git.changedPathsForPr(
+      workspaceId,
+      'current-company-state',
+      'mallory/self-promote',
+    );
+    expect(paths).toEqual(['honest.md']);
+  });
+
+  /**
+   * The per-file revert's two primitives: the merge-base a revert restores
+   * from, and the restore itself — byte-exact via git, with "absent at the
+   * merge-base" meaning deletion (the revert of an added file).
+   */
+  it('mergeBaseForPr + restorePathFromRef restore a modified file and delete an added one', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    await runGit(repo, ['checkout', '-b', 'alice/feature']);
+    await fs.writeFile(path.join(repo, 'base.md'), 'rewritten\n');
+    await fs.writeFile(path.join(repo, 'added.md'), 'brand new\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'feature work']);
+    await runGit(repo, ['push', '-u', 'origin', 'alice/feature']);
+
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+
+    const mergeBase = await git.mergeBaseForPr(workspaceId, 'current-company-state', 'alice/feature');
+    expect(mergeBase).toMatch(/^[0-9a-f]{40}$/);
+
+    await git.restorePathFromRef(workspaceId, mergeBase!, 'base.md');
+    // Normalized: a Windows dev box with core.autocrlf smudges the checkout
+    // to CRLF; the blob git commits back is what matters, not the smudge.
+    const restored = await fs.readFile(path.join(repo, 'base.md'), 'utf8');
+    expect(restored.replace(/\r\n/g, '\n')).toBe('base\n');
+
+    // Simulate the wreckage a previously-failed attempt leaves behind: a
+    // STAGED deletion (index entry gone). The restore must self-heal it —
+    // without the index realignment, the commit below fatals on `git add`.
+    await runGit(repo, ['rm', '--force', '--quiet', '--', 'added.md']);
+
+    await git.restorePathFromRef(workspaceId, mergeBase!, 'added.md');
+    await expect(fs.access(path.join(repo, 'added.md'))).rejects.toThrow();
+
+    // The chain that actually failed in production: committing the DELETION
+    // through commitFile, whose `git add -- <path>` can only stage it while
+    // the index still tracks the path — a `git rm`-based restore broke here
+    // with "pathspec did not match any files".
+    const committed = await git.commitFile(
+      workspaceId,
+      { id: 'u1', email: 'reviewer@x.com', name: 'Reviewer' },
+      'added.md',
+      'Revert added.md (declined in change request #1)',
+      true,
+    );
+    expect(committed).not.toBeNull();
+    await expect(
+      execFileAsync('git', ['-C', repo, 'cat-file', '-e', 'HEAD:added.md']),
+    ).rejects.toThrow();
+  });
 });