@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/workflow/events.routes.ts

@@ -33,6 +33,9 @@
  */
 
 import type { Request, Response } from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('events');
 import express from 'express';
 import type { WorkflowEvent } from '@bevel-software/platform-shared';
 import type { WorkflowEventBus } from './event-bus.js';
@@ -42,16 +45,40 @@ import '../auth/auth.middleware.js'; // Express Request augmentation
  * the typical 30–100 s proxy idle timeout. */
 const HEARTBEAT_INTERVAL_MS = 25_000;
 
+/**
+ * Ceiling on how many workspaces one session may watch. The list is walked on
+ * every workspace-scoped event for every session, so it is a fan-out cost, and
+ * a client bug that appends without ever releasing would otherwise grow it
+ * without bound. Real pages want two: the branch in the address bar, and the
+ * default branch a skill page reads from.
+ */
+const MAX_WATCHED_WORKSPACES = 8;
+
 /**
  * Per-session bookkeeping the route owns. The bus's `Subscriber` holds a
- * `getFocusedWorkspaceId()` getter pointing at `session.focusedWorkspaceId`,
+ * `getFocusedWorkspaceIds()` getter pointing at `session.focusedWorkspaceIds`,
  * so the focus POST mutates this object and the next event fan-out picks
  * up the new value with no re-subscribe.
  */
 interface ActiveSession {
   sessionId: string;
   userId: string;
-  focusedWorkspaceId: string | null;
+  /**
+   * Every workspace this session wants events for, primary first.
+   *
+   * A LIST, not one id, because "the workspace the user is looking at" and
+   * "the workspaces the open page reads from" are different questions. The
+   * skill page is the case that forced it: it renders the DEFAULT branch's
+   * tree whatever branch is checked out, so a reader standing on their own
+   * suggestion branch got no `file-changed` for the images on screen and kept
+   * showing a screenshot a teammate had already replaced.
+   *
+   * The client declares the list; this is a delivery filter, not an access
+   * check. It always was — a session could name any workspace as its focus —
+   * and the events it selects carry no file contents, only paths. Whether the
+   * reader may open what changed is settled by the routes that serve it.
+   */
+  focusedWorkspaceIds: string[];
   /** Set when the SSE connection closes. Used by the focus POST so a
    *  request that arrives after the connection drops 404s cleanly. */
   closed: boolean;
@@ -75,7 +102,7 @@ export function createEventsRoutes(
 
   /**
    * Process-wide session registry. The same map services the SSE open
-   * (creates the entry) and the focus POST (mutates `focusedWorkspaceId`).
+   * (creates the entry) and the focus POST (mutates `focusedWorkspaceIds`).
    * Entries clear when the SSE connection closes.
    */
   const sessions = new Map<string, ActiveSession>();
@@ -116,26 +143,20 @@ export function createEventsRoutes(
       try {
         existing.cleanup();
       } catch (err) {
-        console.warn(
-          `[events] supersede cleanup threw for session=${sessionId}:`,
-          err instanceof Error ? err.message : err,
-        );
+        log.warn(`supersede cleanup threw for session=${sessionId}:`, { err });
       }
       existing.closed = true;
       try {
         if (!existing.res.writableEnded) existing.res.end();
       } catch (err) {
-        console.warn(
-          `[events] failed to end superseded SSE response for session=${sessionId}:`,
-          err instanceof Error ? err.message : err,
-        );
+        log.warn(`failed to end superseded SSE response for session=${sessionId}:`, { err });
       }
     }
 
     const session: ActiveSession = {
       sessionId,
       userId,
-      focusedWorkspaceId: null,
+      focusedWorkspaceIds: [],
       closed: false,
       res,
       // Filled in below once `unsubscribe` + `heartbeat` exist.
@@ -151,7 +172,7 @@ export function createEventsRoutes(
     const unsubscribe = bus.subscribe({
       sessionId,
       userId,
-      getFocusedWorkspaceId: () => session.focusedWorkspaceId,
+      getFocusedWorkspaceIds: () => session.focusedWorkspaceIds,
       push,
     });
 
@@ -163,7 +184,7 @@ export function createEventsRoutes(
     if (Number.isFinite(lastSeenId) && lastSeenId > 0) {
       const replay = bus.replayAfter(lastSeenId, {
         userId,
-        getFocusedWorkspaceId: () => session.focusedWorkspaceId,
+        getFocusedWorkspaceIds: () => session.focusedWorkspaceIds,
       });
       if (replay === null) {
         // Buffer evicted past `lastSeenId` — client must refetch from
@@ -202,7 +223,7 @@ export function createEventsRoutes(
     res.on('close', cleanup);
     res.on('error', cleanup);
 
-    console.log(`[events] open session=${sessionId} user=${userId} subscribers=${bus.size()}`);
+    log.info(`open session=${sessionId} user=${userId} subscribers=${bus.size()}`);
   });
 
   router.post('/events/:sessionId/focus', authMiddleware, express.json(), (req, res) => {
@@ -228,17 +249,31 @@ export function createEventsRoutes(
       res.status(403).json({ error: 'Session belongs to another user' });
       return;
     }
-    const { workspaceId } = (req.body ?? {}) as { workspaceId?: unknown };
+    const { workspaceId, alsoWatch } = (req.body ?? {}) as {
+      workspaceId?: unknown;
+      alsoWatch?: unknown;
+    };
     if (typeof workspaceId !== 'string' || workspaceId.length === 0) {
       res.status(400).json({ error: 'workspaceId is required in body' });
       return;
     }
-    const previous = session.focusedWorkspaceId;
-    session.focusedWorkspaceId = workspaceId;
-    console.log(
-      `[events] FOCUS session=${sessionId} user=${userId} ${previous ?? '(none)'} → ${workspaceId}`,
+    // `alsoWatch` is optional and additive: the workspaces an open page reads
+    // from besides the one in the address bar. Non-string and empty entries
+    // are dropped rather than 400-ing the whole update — the primary focus is
+    // the part the user's navigation depends on, and it is well-formed here.
+    const extra = Array.isArray(alsoWatch)
+      ? alsoWatch.filter((id): id is string => typeof id === 'string' && id.length > 0)
+      : [];
+    // Primary first, de-duplicated: `matches` walks this list per event.
+    const next = [...new Set([workspaceId, ...extra])].slice(0, MAX_WATCHED_WORKSPACES);
+    const previous = session.focusedWorkspaceIds;
+    session.focusedWorkspaceIds = next;
+    log.info(
+      `FOCUS session=${sessionId} user=${userId} ${
+        previous.join(',') || '(none)'
+      } → ${next.join(',')}`,
     );
-    res.json({ status: 'ok', focusedWorkspaceId: workspaceId });
+    res.json({ status: 'ok', focusedWorkspaceId: workspaceId, focusedWorkspaceIds: next });
   });
 
   return router;

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

@@ -11,6 +11,24 @@
  * is the source of truth and any cache would lose its purpose the moment
  * a different replica takes over.
  *
+ * Path identity: every method here canonicalises the path it was handed
+ * before it touches a row, so `./x//a.md` and `x/a.md` are ONE lock no
+ * matter which caller spelled which. It happens HERE rather than in the
+ * routes because the lock row is the coordination point: the routes are only
+ * today's callers, and a caller that reaches this service directly (the
+ * agent's lock-aware filesystem, a future route family) has to land on the
+ * same identity or it is not coordinating with anyone. Canonicalisation also
+ * REFUSES a path that escapes the workspace or that only looks relative, with
+ * the statuses the file verbs answer for the same input, so a lock row can
+ * never be keyed on a path no file verb would accept. See
+ * `canonicalFileIdentity`.
+ *
+ * There is no transition handling for rows written under a raw spelling
+ * before this landed: such a row is now unreachable by name and expires on
+ * its own TTL. For one deploy an in-flight edit's lock can linger up to the
+ * TTL below; nothing migrates and nothing dual-matches, because a dual match
+ * would be a second identity and the whole point is that there is one.
+ *
  * Stale-lock semantics: `get`, `acquire`, and `heartbeat` all treat a row
  * with `expires_at <= now()` as if the lock didn't exist. We purge it
  * lazily on next access rather than running a sweeper — the row count is
@@ -22,6 +40,7 @@ import type { Database } from '../database/connection.js';
 import { fileLocks } from '../database/schema.js';
 import type { AcquireLockResult, AuthUser, FileLock } from '@bevel-software/platform-shared';
 import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
 
 /**
  * Lock lifetime without a heartbeat. The client is expected to heartbeat
@@ -73,10 +92,11 @@ export class FileLockService {
   async acquire(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
     opts?: { coordination?: boolean },
   ): Promise<AcquireLockResult> {
+    const targetPath = canonicalFileIdentity(rawPath);
     const now = new Date();
     const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
 
@@ -175,9 +195,10 @@ export class FileLockService {
   async heartbeat(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
   ): Promise<FileLock> {
+    const targetPath = canonicalFileIdentity(rawPath);
     const now = new Date();
     const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
     // The expiry guard (`expiresAt > now`) matters because an expired
@@ -221,9 +242,10 @@ export class FileLockService {
   async release(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
   ): Promise<void> {
+    const targetPath = canonicalFileIdentity(rawPath);
     await this.db
       .delete(fileLocks)
       .where(
@@ -244,8 +266,9 @@ export class FileLockService {
   async get(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
   ): Promise<FileLock | null> {
+    const targetPath = canonicalFileIdentity(rawPath);
     const rows = await this.db
       .select()
       .from(fileLocks)

package/src/modules/workflow/git/__tests__/change-request-link.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+
+import { CHANGE_REQUEST_URL_NOTE, changeRequestLink, changeRequestLinkBase } from '../change-request-link.js';
+
+/**
+ * The link an agent hands a person for a change request: absolute under the
+ * configured public frontend address, else the relative in-app path with a note.
+ */
+describe('changeRequestLink', () => {
+  it('is absolute under a configured address, keeping the number in its own field', () => {
+    const base = changeRequestLinkBase('https://bevel.example.com');
+    expect(changeRequestLink(12, base)).toEqual({ url: 'https://bevel.example.com/change-requests/12' });
+  });
+
+  it('keeps the path prefix of a proxied deployment', () => {
+    for (const configured of ['https://example.com/hexis', 'https://example.com/hexis/']) {
+      const base = changeRequestLinkBase(configured);
+      expect(changeRequestLink(3, base).url, configured).toBe('https://example.com/hexis/change-requests/3');
+    }
+  });
+
+  it('stays the relative path with a note when no address is configured', () => {
+    for (const configured of [null, undefined, '', '   ']) {
+      expect(changeRequestLink(5, changeRequestLinkBase(configured))).toEqual({
+        url: '/change-requests/5',
+        urlNote: CHANGE_REQUEST_URL_NOTE,
+      });
+    }
+    expect(CHANGE_REQUEST_URL_NOTE).toBe('Set PUBLIC_FRONTEND_URL to get absolute links.');
+  });
+
+  it('never carries credentials, a query or a fragment from the configured address', () => {
+    const base = changeRequestLinkBase('https://user:s3cret-token@bevel.example.com/app/?token=abc#frag');
+    const { url } = changeRequestLink(9, base);
+    expect(url).toBe('https://bevel.example.com/app/change-requests/9');
+    expect(url).not.toMatch(/s3cret|token|user|frag/);
+  });
+
+  it('treats an unparseable or non-web address as unconfigured', () => {
+    expect(changeRequestLinkBase('not a url')).toBeNull();
+    expect(changeRequestLinkBase('javascript:alert(1)')).toBeNull();
+  });
+});

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

@@ -121,6 +121,7 @@ function recordingAccessControl(opts: {
       return opts.canWriteBatchAtRef?.(ref, userEmail, paths) ?? new Map(paths.map((p) => [p, true]));
     },
     eligibleWritersAtRef: async () => opts.eligible?.() ?? { roles: ['Admin'], users: [] },
+    holdsAdminRootWrite: async () => false,
     eligibleWritersForPathsAtRef: async (_w, _ref, paths) =>
       new Map(paths.map((p) => [p, { roles: [], users: [], emails: new Set<string>() }])),
     findEmailByHash: async () => null,

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

@@ -6,7 +6,8 @@ import path from 'node:path';
 import os from 'node:os';
 import type { WorkspaceService } from '../../../workspace/workspace.service.js';
 import { WorkflowHooks } from '../../workflow-hooks.js';
-import { GitService, parseNameStatusZ, parseNumstatZ } from '../git.service.js';
+import { GitService, parseNameStatusZ, parseNumstatZ, withoutPlaceholderRename } from '../git.service.js';
+import { WorkspaceMutex } from '../../../kb-fs/mutex.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -58,6 +59,26 @@ function stubWorkspaceService(workspaceId: string, repo: string): WorkspaceServi
   } as unknown as WorkspaceService;
 }
 
+describe('withoutPlaceholderRename', () => {
+  it('turns a rename onto the placeholder into a removal, and off it into an addition', () => {
+    expect(withoutPlaceholderRename({ status: 'renamed', previousPath: 'A/x.md', path: 'A/.gitkeep' })).toEqual({
+      status: 'removed',
+      path: 'A/x.md',
+    });
+    expect(withoutPlaceholderRename({ status: 'renamed', previousPath: 'A/.gitkeep', path: 'A/x.md' })).toEqual({
+      status: 'added',
+      path: 'A/x.md',
+    });
+  });
+
+  it('leaves every other entry as it is', () => {
+    const plain = { status: 'renamed' as const, previousPath: 'A/x.md', path: 'B/x.md' };
+    const moved = { status: 'renamed' as const, previousPath: 'A/.gitkeep', path: 'B/.gitkeep' };
+    const added = { status: 'added' as const, path: 'A/.gitkeep' };
+    expect([plain, moved, added].map(withoutPlaceholderRename)).toEqual([plain, moved, added]);
+  });
+});
+
 describe('parseNameStatusZ', () => {
   it('parses adds/mods/deletes and rename pairs', () => {
     const out = ['A', 'a.md', 'M', 'b.md', 'D', 'c.md', 'R100', 'old.md', 'new.md', ''].join('\0');
@@ -225,6 +246,79 @@ describe('GitService.changedFilesForPr / resolvePrShas', () => {
     expect(paths).toEqual(['honest.md']);
   });
 
+  /**
+   * The empty-folder placeholder is never content, so the change-request file
+   * list does not show it, at any depth, and the +/- counts stay aligned. The
+   * touched paths keep it: a request that only creates a folder is not empty,
+   * and must not be closed as if it were.
+   */
+  it('excludes the folder placeholder from the changed-file list but not the touched paths', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    await runGit(repo, ['checkout', '-b', 'alice/new-folders']);
+    await fs.mkdir(path.join(repo, 'Reports/Empty'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'Reports/Empty/.gitkeep'), '');
+    await fs.writeFile(path.join(repo, 'Reports/.gitkeep'), '');
+    await fs.writeFile(path.join(repo, 'Reports/q3.md'), 'one\ntwo\nthree\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'folders']);
+    await runGit(repo, ['push', '-u', 'origin', 'alice/new-folders']);
+
+    const git = new GitService(stubWorkspaceService(workspaceId, repo), new WorkflowHooks(), 'knowledge-base');
+
+    const files = await git.changedFilesForPr(workspaceId, 'current-company-state', 'alice/new-folders');
+    expect(files.map((f) => f.path)).toEqual(['Reports/q3.md']);
+    expect(files[0].additions).toBe(3);
+
+    const paths = await git.changedPathsForPr(workspaceId, 'current-company-state', 'alice/new-folders');
+    expect(paths.sort()).toEqual(['Reports/.gitkeep', 'Reports/Empty/.gitkeep', 'Reports/q3.md']);
+  });
+
+  /**
+   * Deleting a folder's last file writes the placeholder; when that file was
+   * empty too, `-M` sees an identical blob move and pairs them as a rename.
+   * The review surface must still show the file's removal.
+   */
+  it('an empty file replaced by the placeholder is reviewed as a removal, not dropped with it', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    await fs.mkdir(path.join(repo, 'Reports'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'Reports/empty.md'), '');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'empty file']);
+    await runGit(repo, ['push', 'origin', 'current-company-state']);
+    await runGit(repo, ['checkout', '-b', 'alice/emptied']);
+    await fs.rm(path.join(repo, 'Reports/empty.md'));
+    await fs.writeFile(path.join(repo, 'Reports/.gitkeep'), '');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'emptied']);
+    await runGit(repo, ['push', '-u', 'origin', 'alice/emptied']);
+
+    const git = new GitService(stubWorkspaceService(workspaceId, repo), new WorkflowHooks(), 'knowledge-base');
+
+    const files = await git.changedFilesForPr(workspaceId, 'current-company-state', 'alice/emptied');
+    expect(files.map((f) => ({ path: f.path, status: f.status, previousPath: f.previousPath }))).toEqual([
+      { path: 'Reports/empty.md', status: 'removed', previousPath: undefined },
+    ]);
+
+    const paths = await git.changedPathsForPr(workspaceId, 'current-company-state', 'alice/emptied');
+    expect(paths.sort()).toEqual(['Reports/.gitkeep', 'Reports/empty.md']);
+  });
+
+  it('pathExistsAtRef answers for files and folders at a ref, and false for what is not there', async () => {
+    const { repo } = await seedWorkspace(root, workspaceId);
+    const git = new GitService(stubWorkspaceService(workspaceId, repo), new WorkflowHooks(), 'knowledge-base');
+    await fs.mkdir(path.join(repo, 'Docs'));
+    await fs.writeFile(path.join(repo, 'Docs/.gitkeep'), '');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'folder']);
+
+    await expect(git.pathExistsAtRef(workspaceId, 'HEAD', 'base.md')).resolves.toBe(true);
+    await expect(git.pathExistsAtRef(workspaceId, 'HEAD', 'Docs/.gitkeep')).resolves.toBe(true);
+    await expect(git.pathExistsAtRef(workspaceId, 'HEAD~1', 'Docs/.gitkeep')).resolves.toBe(false);
+    await expect(git.pathExistsAtRef(workspaceId, 'HEAD', 'missing.md')).resolves.toBe(false);
+    // Not an answer about the path at all: the ref does not resolve.
+    await expect(git.pathExistsAtRef(workspaceId, 'deadbeef', 'base.md')).rejects.toThrow();
+  });
+
   /**
    * 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
@@ -279,3 +373,146 @@ describe('GitService.changedFilesForPr / resolvePrShas', () => {
     ).rejects.toThrow();
   });
 });
+
+/**
+ * `changedPathsForPr` fetches the two refs it is about before diffing them —
+ * one network round trip per call. A change-request LIST calls it once per
+ * open request, which is where the "very slow loading" reported against the
+ * request list came from (~0.55s per additional open request, measured).
+ * `fetch: false` lets the list refresh the whole clone once instead and then
+ * diff locally; every other caller keeps the fetch.
+ */
+describe('GitService.changedPathsForPr: who pays for the fetch', () => {
+  let root: string;
+  const workspaceId = 'current-company-state';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-pr-paths-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true }).catch(() => {});
+  });
+
+  /**
+   * Push a change request's head branch to the remote from a DIFFERENT
+   * clone, so the workspace clone has never seen it — which is exactly what
+   * the flag decides about.
+   */
+  async function pushedElsewhere(upstream: string, file: string): Promise<string> {
+    const other = path.join(root, `.other-${file}`);
+    await runGit(root, ['clone', upstream, other]);
+    await runGit(other, ['config', 'user.email', 'test@bevel.local']);
+    await runGit(other, ['config', 'user.name', 'Test Runner']);
+    await runGit(other, ['checkout', '-b', 'biz/proposal']);
+    await fs.writeFile(path.join(other, file), 'proposed\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'propose']);
+    await runGit(other, ['push', '-u', 'origin', 'biz/proposal']);
+    return other;
+  }
+
+  it('finds a branch pushed since the last fetch — the default', async () => {
+    const { repo, upstream } = await seedWorkspace(root, workspaceId);
+    await pushedElsewhere(upstream, 'brief.pdf');
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+    expect(
+      await git.changedPathsForPr(workspaceId, 'current-company-state', 'biz/proposal'),
+    ).toEqual(['brief.pdf']);
+  });
+
+  it('with fetch: false, reads the refs the clone already has and skips the network', async () => {
+    const { repo, upstream } = await seedWorkspace(root, workspaceId);
+    const other = await pushedElsewhere(upstream, 'brief.pdf');
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+    // The clone now knows the branch — this stands in for the one fetch a
+    // list does for the whole clone before asking about every request.
+    await runGit(repo, ['fetch', '--prune', 'origin']);
+    // A second file lands on the branch afterwards.
+    await fs.writeFile(path.join(other, 'extra.pdf'), 'more\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'second']);
+    await runGit(other, ['push', 'origin', 'biz/proposal']);
+
+    // Skipped: the answer is the clone's own refs, one push behind — which
+    // is the trade the flag makes, and why only a caller that has JUST
+    // refreshed the clone may pass it.
+    expect(
+      await git.changedPathsForPr(workspaceId, 'current-company-state', 'biz/proposal', {
+        fetch: false,
+      }),
+    ).toEqual(['brief.pdf']);
+    // The default pays for the round trip and sees both.
+    expect(
+      (await git.changedPathsForPr(workspaceId, 'current-company-state', 'biz/proposal')).sort(),
+    ).toEqual(['brief.pdf', 'extra.pdf']);
+  });
+
+  /**
+   * The one case `fetch: false` must NOT honour. A branch this clone has
+   * never heard of does not give a stale diff, it gives NO diff — an empty
+   * touched-path set, which is a change request missing from its own
+   * author's tree. So the skip only applies to refs that are actually here.
+   */
+  it('fetches anyway for a branch the clone has never seen', async () => {
+    const { repo, upstream } = await seedWorkspace(root, workspaceId);
+    await pushedElsewhere(upstream, 'brief.pdf');
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+    );
+    // Nothing has refreshed this clone since the branch was pushed.
+    expect(
+      await git.changedPathsForPr(workspaceId, 'current-company-state', 'biz/proposal', {
+        fetch: false,
+      }),
+    ).toEqual(['brief.pdf']);
+  });
+
+  /**
+   * The skip decision and the diff must be ONE reading of the refs. Both
+   * fetches in this flow (`ensureRemotesFetched` for the list,
+   * `fetchPrRefs` here) run outside the workspace mutex deliberately, so a
+   * `fetch --prune origin` CAN land between "the clone knows both branches"
+   * and the diff itself. Re-resolving inside the mutex would then fail, and
+   * `touchedPathsFor` turns that failure into an empty touched-path set —
+   * the request missing from its own author's tree that this whole path
+   * exists to prevent.
+   */
+  it('diffs the commits it decided on, even if a concurrent prune drops the ref', async () => {
+    const { repo, upstream } = await seedWorkspace(root, workspaceId);
+    await pushedElsewhere(upstream, 'brief.pdf');
+    // The list's one fetch for the whole clone.
+    await runGit(repo, ['fetch', '--prune', 'origin']);
+
+    /** Runs the race exactly in the window, then the real critical section. */
+    class PrunedMidCall extends WorkspaceMutex {
+      override async run<T>(key: string, fn: () => Promise<T>): Promise<T> {
+        return super.run(key, async () => {
+          await runGit(repo, ['update-ref', '-d', 'refs/remotes/origin/biz/proposal']);
+          return fn();
+        });
+      }
+    }
+    const git = new GitService(
+      stubWorkspaceService(workspaceId, repo),
+      new WorkflowHooks(),
+      'knowledge-base',
+      new PrunedMidCall(),
+    );
+
+    expect(
+      await git.changedPathsForPr(workspaceId, 'current-company-state', 'biz/proposal', {
+        fetch: false,
+      }),
+    ).toEqual(['brief.pdf']);
+  });
+});