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

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

@@ -0,0 +1,253 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { GitService } from '../git.service.js';
+import { RemoteBranchGoneError } from '../../../../shared/domain-errors.js';
+import { runGit, gitOut, stubWorkflowHooks, stubWorkspaceService } from './git-test-helpers.js';
+
+/**
+ * `syncFromRemote` against real repositories: what it reports about the clone
+ * before and after, the paths it names, an upstream that has no commits yet,
+ * and a branch the host has deleted.
+ */
+const BRANCH = 'target-company-state';
+
+async function bareUpstream(root: string, withCommit: boolean): Promise<string> {
+  const upstream = path.join(root, 'upstream.git');
+  await runGit(root, ['init', '--bare', '-b', BRANCH, upstream]);
+  if (withCommit) {
+    const seed = path.join(root, '.seed');
+    await fs.mkdir(seed);
+    await runGit(seed, ['init', '-b', BRANCH]);
+    await runGit(seed, ['remote', 'add', 'origin', upstream]);
+    await fs.writeFile(path.join(seed, 'a.md'), 'a\n');
+    await fs.writeFile(path.join(seed, 'old name.md'), 'same content that survives a rename\n');
+    await runGit(seed, ['add', '.']);
+    await runGit(seed, ['commit', '-m', 'init']);
+    await runGit(seed, ['push', 'origin', BRANCH]);
+  }
+  await runGit(upstream, ['symbolic-ref', 'HEAD', `refs/heads/${BRANCH}`]);
+  return upstream;
+}
+
+async function cloneWorkspace(root: string, upstream: string, workspaceId: string, branch = BRANCH) {
+  const workspaceDir = path.join(root, workspaceId);
+  const repo = path.join(workspaceDir, 'knowledge-base');
+  await fs.mkdir(workspaceDir, { recursive: true });
+  await runGit(root, ['-c', 'core.autocrlf=false', 'clone', '-b', branch, upstream, repo]);
+  await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
+  await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
+  await runGit(repo, ['config', 'core.autocrlf', 'false']);
+  return { workspaceDir, repo };
+}
+
+/** Land one commit on origin from a second clone; returns the paths it touched. */
+async function pushFromElsewhere(root: string, upstream: string, edit: (dir: string) => Promise<void>, branch = BRANCH) {
+  const pusher = path.join(root, `.pusher-${Math.random().toString(36).slice(2)}`);
+  await runGit(root, ['-c', 'core.autocrlf=false', 'clone', '-b', branch, upstream, pusher]);
+  await runGit(pusher, ['config', 'user.email', 'other@bevel.test']);
+  await runGit(pusher, ['config', 'user.name', 'Other']);
+  await edit(pusher);
+  await runGit(pusher, ['add', '-A']);
+  await runGit(pusher, ['commit', '-m', 'from origin']);
+  await runGit(pusher, ['push', 'origin', branch]);
+}
+
+describe('GitService.syncFromRemote', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-sync-'));
+  });
+
+  afterEach(async () => {
+    for (let i = 0; i < 5; i++) {
+      try {
+        await fs.rm(root, { recursive: true, force: true });
+        return;
+      } catch {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    }
+  });
+
+  it('reports where HEAD was and is, that the tree changed, and every path including both ends of a rename', async () => {
+    const upstream = await bareUpstream(root, true);
+    const { workspaceDir, repo } = await cloneWorkspace(root, upstream, 'ws');
+    const before = (await gitOut(repo, ['rev-parse', 'HEAD'])).trim();
+    await pushFromElsewhere(root, upstream, async (dir) => {
+      await fs.writeFile(path.join(dir, 'a.md'), 'a changed\n');
+      await fs.writeFile(path.join(dir, 'b.md'), 'b\n');
+      await fs.rename(path.join(dir, 'old name.md'), path.join(dir, 'new name.md'));
+    });
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+
+    const r = await git.syncFromRemote('ws');
+    expect(r.before).toBe(before);
+    expect(r.after).toBe((await gitOut(repo, ['rev-parse', 'HEAD'])).trim());
+    expect(r.after).not.toBe(before);
+    expect(r.treeChanged).toBe(true);
+    expect([...r.changedPaths].sort()).toEqual(['a.md', 'b.md', 'new name.md', 'old name.md'].sort());
+
+    // Nothing new: same shas, no change, no paths.
+    const again = await git.syncFromRemote('ws');
+    expect(again).toEqual({ before: r.after, after: r.after, treeChanged: false, changedPaths: [] });
+  });
+
+  it('an unborn clone of an empty upstream is tolerated, and receives its first content as a change from null', async () => {
+    const upstream = await bareUpstream(root, false);
+    const workspaceDir = path.join(root, 'ws');
+    const repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(workspaceDir, { recursive: true });
+    // Cloning an empty repository warns but succeeds; HEAD is unborn.
+    await runGit(root, ['-c', 'core.autocrlf=false', 'clone', upstream, repo]);
+    await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
+    await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
+    await runGit(repo, ['checkout', '-b', BRANCH]).catch(() => undefined);
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+
+    // Still empty on both sides: nothing to sync, and NOT 'remote gone' — a
+    // fresh deployment nobody has pushed to must never have its clone retired.
+    expect(await git.syncFromRemote('ws')).toEqual({ before: null, after: null, treeChanged: false, changedPaths: [] });
+
+    // Origin gains its first commit.
+    const seed = path.join(root, '.first');
+    await fs.mkdir(seed);
+    await runGit(seed, ['init', '-b', BRANCH]);
+    await runGit(seed, ['config', 'user.email', 'other@bevel.test']);
+    await runGit(seed, ['config', 'user.name', 'Other']);
+    await fs.writeFile(path.join(seed, 'README.md'), 'hello\n');
+    await runGit(seed, ['add', '.']);
+    await runGit(seed, ['commit', '-m', 'first']);
+    await runGit(seed, ['push', upstream, BRANCH]);
+
+    const r = await git.syncFromRemote('ws');
+    expect(r.before).toBeNull();
+    expect(r.after).toMatch(/^[0-9a-f]{40}$/);
+    expect(r.treeChanged).toBe(true);
+    expect(r.changedPaths).toEqual(['README.md']);
+  });
+
+  it('a branch deleted on the host is a typed "remote branch gone", not an unreachable remote', async () => {
+    const upstream = await bareUpstream(root, true);
+    await runGit(upstream, ['branch', 'ali/x', BRANCH]);
+    const { workspaceDir } = await cloneWorkspace(root, upstream, 'ali%2Fx', 'ali/x');
+    await runGit(upstream, ['update-ref', '-d', 'refs/heads/ali/x']);
+    const git = new GitService(stubWorkspaceService({ 'ali%2Fx': workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+    await expect(git.syncFromRemote('ali%2Fx')).rejects.toBeInstanceOf(RemoteBranchGoneError);
+  });
+});
+
+describe('GitService.syncFromRemote — the cases git exits 0 on but should not pass', () => {
+  let root: string;
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-sync2-'));
+  });
+  afterEach(async () => {
+    for (let i = 0; i < 5; i++) {
+      try {
+        await fs.rm(root, { recursive: true, force: true });
+        return;
+      } catch {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    }
+  });
+
+  it('an autostashed edit that conflicts on reapply is a typed conflict, the tree is left clean, the edit is kept in stash', async () => {
+    const upstream = await bareUpstream(root, true);
+    const { workspaceDir, repo } = await cloneWorkspace(root, upstream, 'ws');
+    // A tracked edit nobody committed — what a lock-holder's in-progress save looks like.
+    await fs.writeFile(path.join(repo, 'a.md'), 'edited locally\n');
+    await pushFromElsewhere(root, upstream, async (dir) => {
+      await fs.writeFile(path.join(dir, 'a.md'), 'edited on the host\n');
+    });
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+
+    await expect(git.syncFromRemote('ws')).rejects.toMatchObject({
+      name: 'PullRebaseConflictError',
+      conflictedPaths: ['a.md'],
+    });
+    // Clean tree at the remote commit; the local edit survives in the stash.
+    expect(await gitOut(repo, ['status', '--porcelain'])).toBe('');
+    expect(await gitOut(repo, ['rev-parse', 'HEAD'])).toBe(await gitOut(repo, ['rev-parse', 'refs/remotes/origin/' + BRANCH]));
+    expect((await gitOut(repo, ['stash', 'list'])).split('\n').filter(Boolean)).toHaveLength(1);
+  });
+
+  it('an unborn clone whose branch was created and deleted on an origin that has other branches is remote gone, not fresh', async () => {
+    const upstream = await bareUpstream(root, true); // origin has BRANCH
+    const workspaceDir = path.join(root, 'ws');
+    const repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(workspaceDir, { recursive: true });
+    // An unborn clone checked out on a branch origin does not have.
+    await runGit(root, ['-c', 'core.autocrlf=false', 'clone', upstream, repo]);
+    await runGit(repo, ['checkout', '--orphan', 'ali/x']);
+    await runGit(repo, ['rm', '-rf', '--cached', '.']).catch(() => undefined);
+    await fs.rm(path.join(repo, 'a.md'), { force: true });
+    await fs.rm(path.join(repo, 'old name.md'), { force: true });
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+    await expect(git.syncFromRemote('ws')).rejects.toBeInstanceOf(RemoteBranchGoneError);
+  });
+
+  it('remoteBranchExists answers from origin, not from the clone', async () => {
+    const upstream = await bareUpstream(root, true);
+    await runGit(upstream, ['branch', 'ali/x', BRANCH]);
+    const { workspaceDir } = await cloneWorkspace(root, upstream, 'ws');
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+    expect(await git.remoteBranchExists('ws', 'ali/x')).toBe(true);
+    await runGit(upstream, ['update-ref', '-d', 'refs/heads/ali/x']);
+    expect(await git.remoteBranchExists('ws', 'ali/x')).toBe(false);
+  });
+});
+
+describe('GitService.syncFromRemote — an unborn clone that already holds staged files', () => {
+  let root: string;
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-sync3-'));
+  });
+  afterEach(async () => {
+    for (let i = 0; i < 5; i++) {
+      try {
+        await fs.rm(root, { recursive: true, force: true });
+        return;
+      } catch {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    }
+  });
+
+  it('is refused as a typed conflict naming the staged paths; nothing on disk is touched', async () => {
+    const upstream = await bareUpstream(root, false);
+    const workspaceDir = path.join(root, 'ws');
+    const repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(workspaceDir, { recursive: true });
+    await runGit(root, ['-c', 'core.autocrlf=false', 'clone', upstream, repo]);
+    await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
+    await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
+    await runGit(repo, ['checkout', '-b', BRANCH]).catch(() => undefined);
+    // Someone wrote and staged a file before the first commit ever existed —
+    // with a name git's line output would quote ("Entw\\303\\274rfe.md"), so
+    // the outcome has to carry the real spelling.
+    await fs.writeFile(path.join(repo, 'Entwürfe.md'), 'not yet committed\n');
+    await runGit(repo, ['add', 'Entwürfe.md']);
+    // Origin gains its first commit meanwhile.
+    const seed = path.join(root, '.first');
+    await fs.mkdir(seed);
+    await runGit(seed, ['init', '-b', BRANCH]);
+    await runGit(seed, ['config', 'user.email', 'other@bevel.test']);
+    await runGit(seed, ['config', 'user.name', 'Other']);
+    await fs.writeFile(path.join(seed, 'README.md'), 'hello\n');
+    await runGit(seed, ['add', '.']);
+    await runGit(seed, ['commit', '-m', 'first']);
+    await runGit(seed, ['push', upstream, BRANCH]);
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+
+    await expect(git.syncFromRemote('ws')).rejects.toMatchObject({
+      name: 'PullRebaseConflictError',
+      conflictedPaths: ['Entwürfe.md'],
+    });
+    expect(await fs.readFile(path.join(repo, 'Entwürfe.md'), 'utf8')).toBe('not yet committed\n');
+    expect((await gitOut(repo, ['ls-files', '--cached', '-z'])).replace(/\0$/, '')).toBe('Entwürfe.md');
+  });
+});

package/src/modules/workflow/git/__tests__/node-git-runner.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { NodeGitRunner } from '../node-git-runner.js';
+import { GitRunError, isGitTimeout } from '../../../../shared/git.contract.js';
+
+/**
+ * These run REAL git, like the rest of this module's suites: the behaviours
+ * under test — what a deadline does to a live child, what an exit code means,
+ * what git puts in a message — are properties of the process, and a stubbed
+ * spawn would only re-assert the stub.
+ */
+describe('NodeGitRunner', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'git-runner-'));
+    const runner = new NodeGitRunner();
+    await runner.run(dir, ['init', '--initial-branch=main']);
+  });
+
+  afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+  });
+
+  it('returns what git wrote', async () => {
+    const runner = new NodeGitRunner();
+    // `symbolic-ref` rather than `rev-parse HEAD`: the repository has no commit
+    // yet, and an unborn HEAD is not a revision `rev-parse` can resolve.
+    const { stdout } = await runner.run(dir, ['symbolic-ref', '--short', 'HEAD']);
+    expect(stdout.trim()).toBe('main');
+  });
+
+  it('feeds stdin to commands that read it', async () => {
+    const runner = new NodeGitRunner();
+    const { stdout } = await runner.run(dir, ['hash-object', '--stdin'], { input: 'hello' });
+    // git's hash for the blob "hello" — stable across every git version.
+    expect(stdout.trim()).toBe('b6fc4c620b67d95f953a5c1c1230aaab5db5a1b0');
+  });
+
+  it('carries the exit code so callers can read an expected non-zero exit', async () => {
+    const runner = new NodeGitRunner();
+    // `merge-base --is-ancestor` exits 1 for "no", which several callers read
+    // as an answer rather than a failure.
+    const err = await runner
+      .run(dir, ['merge-base', '--is-ancestor', 'HEAD', 'HEAD'])
+      .catch((e: unknown) => e);
+    // An unborn HEAD makes this fail outright; either way the point is that a
+    // failure arrives as GitRunError with git's own exit code attached.
+    expect(err).toBeInstanceOf(GitRunError);
+    expect(typeof (err as GitRunError).exitCode).toBe('number');
+    expect(isGitTimeout(err)).toBe(false);
+  });
+
+  it('names the failing subcommand past any leading -c pairs', async () => {
+    const runner = new NodeGitRunner();
+    const err = await runner
+      .run(dir, ['-c', 'user.name=x', '-c', 'user.email=y', 'checkout', 'no-such-branch'])
+      .catch((e: unknown) => e);
+    expect((err as Error).message).toMatch(/^git checkout failed:/);
+  });
+
+  it('kills a command that outlives its deadline, and says that is what happened', async () => {
+    const runner = new NodeGitRunner();
+    // `git ls-remote` against a routable-but-dead address hangs in connect:
+    // 203.0.113.0/24 is TEST-NET-3, reserved for documentation and guaranteed
+    // not to be routed to anything that answers.
+    const started = Date.now();
+    const err = await runner
+      .run(dir, ['ls-remote', 'http://203.0.113.1/repo.git'], { timeoutMs: 1_000 })
+      .catch((e: unknown) => e);
+
+    expect(isGitTimeout(err)).toBe(true);
+    expect((err as Error).message).toMatch(/timed out after 1000ms/);
+    // The deadline has to bound the WAIT, not just fire a timer. Signalling
+    // git alone does not: the transport helper it spawned keeps the stdio
+    // pipes open, and node resolves an execFile when the pipes close, so the
+    // call returned after the helper's own connect timeout (measured at 21s
+    // against this address) rather than after ours. The tree kill is what
+    // makes this assertion hold.
+    expect(Date.now() - started).toBeLessThan(10_000);
+  });
+
+  it('does not hold the event loop open after a call that beat its deadline', async () => {
+    const runner = new NodeGitRunner();
+    // A generous deadline on a command that finishes immediately. The
+    // escalation timer is armed only on the timeout path, but the deadline
+    // timer is armed on every call and would keep the process alive for its
+    // full duration if it were not cleared.
+    await runner.run(dir, ['rev-parse', '--git-dir'], { timeoutMs: 600_000 });
+    // Vitest fails the run on a leaked handle; reaching here with no open
+    // timer is the assertion.
+    expect(true).toBe(true);
+  });
+
+  it('keeps the configured git token out of failures', async () => {
+    const runner = new NodeGitRunner();
+    const previous = process.env.GITHUB_TOKEN;
+    process.env.GITHUB_TOKEN = 'ghp_secret_value_here';
+    try {
+      const err = await runner
+        .run(dir, ['ls-remote', 'https://x-access-token:ghp_secret_value_here@127.0.0.1:1/r.git'], {
+          timeoutMs: 15_000,
+        })
+        .catch((e: unknown) => e);
+      const text = `${(err as Error).message} ${(err as GitRunError).stderr ?? ''}`;
+      expect(text).not.toContain('ghp_secret_value_here');
+    } finally {
+      if (previous === undefined) delete process.env.GITHUB_TOKEN;
+      else process.env.GITHUB_TOKEN = previous;
+    }
+  });
+});

package/src/modules/workflow/git/__tests__/pull-request.service.getPrDetail.test.ts

@@ -34,6 +34,7 @@ function makeDb(): Database {
 
 const BASE = 'b'.repeat(40);
 const HEAD = 'a'.repeat(40);
+const FORK = 'c'.repeat(40);
 
 /**
  * A detail read is the hot path behind every change-request poll, every
@@ -47,7 +48,8 @@ describe('PullRequestService.getPrDetail — git work per read', () => {
   function harness() {
     const resolvePrShas = vi.fn(async () => ({ baseSha: BASE, headSha: HEAD }));
     const changedFilesForPr = vi.fn(async () => []);
-    const git = { resolvePrShas, changedFilesForPr } as unknown as GitService;
+    const forkPointForPr = vi.fn(async () => ({ mergeBaseSha: FORK, behind: true }));
+    const git = { resolvePrShas, changedFilesForPr, forkPointForPr } as unknown as GitService;
     const workspace = {
       findAnyWorkspaceId: async () => 'ws-main',
       ensureRemotesFetched: async () => undefined,
@@ -61,7 +63,7 @@ describe('PullRequestService.getPrDetail — git work per read', () => {
       getApprovalStates,
       evaluateMergeGate: () => ({ mergeable: false, reasons: [], warnings: [] }),
     });
-    return { svc, resolvePrShas, changedFilesForPr, getApprovalStates };
+    return { svc, resolvePrShas, changedFilesForPr, forkPointForPr, getApprovalStates };
   }
 
   it('pins the file list to the SHAs it just resolved, and keeps patches for a client read', async () => {
@@ -111,4 +113,69 @@ describe('PullRequestService.getPrDetail — git work per read', () => {
       { at: { baseSha: BASE, headSha: HEAD } },
     );
   });
+
+  it('carries the fork point and "needs updating", pinned to the same SHAs as the file list', async () => {
+    const { svc, forkPointForPr } = harness();
+    const detail = await svc.getPrDetail(7, { fresh: true });
+    expect(forkPointForPr).toHaveBeenCalledWith('ws-main', { baseSha: BASE, headSha: HEAD });
+    expect(detail?.mergeBaseSha).toBe(FORK);
+    expect(detail?.behind).toBe(true);
+    // Anonymous read: no viewer, no Update.
+    expect(detail?.viewerCanUpdate).toBe(false);
+  });
+
+  it('the target moving on invalidates a cached detail, even with the head unchanged', async () => {
+    const { svc, resolvePrShas, getApprovalStates } = harness();
+    await svc.getPrDetail(7, { fresh: true });
+    resolvePrShas.mockResolvedValueOnce({ baseSha: 'd'.repeat(40), headSha: HEAD });
+    await svc.getPrDetail(7);
+    expect(getApprovalStates).toHaveBeenCalledTimes(2);
+  });
+});
+
+/**
+ * The link on a change request is what an agent hands a person, so it is built
+ * from the configured public frontend address — never from the source branch.
+ */
+describe('PullRequestService — change request link', () => {
+  function detailWith(publicFrontendUrl?: string | null) {
+    const git = {
+      resolvePrShas: async () => ({ baseSha: BASE, headSha: HEAD }),
+      changedFilesForPr: async () => [],
+      forkPointForPr: async () => ({ mergeBaseSha: FORK, behind: false }),
+    } as unknown as GitService;
+    const workspace = {
+      findAnyWorkspaceId: async () => 'ws-main',
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    const access = { canWriteAtRef: async () => false } as unknown as IAccessControl;
+    const svc = new PullRequestService(makeDb(), workspace, access, git, publicFrontendUrl);
+    svc.setDetailEnricher({
+      listComments: async () => [],
+      getApprovalStates: async () => [],
+      evaluateMergeGate: () => ({ mergeable: false, reasons: [], warnings: [] }),
+    });
+    return svc.getPrDetail(7, { fresh: true });
+  }
+
+  it('is absolute under a configured address, with no note', async () => {
+    const detail = await detailWith('https://bevel.example.com');
+    expect(detail?.number).toBe(7);
+    expect(detail?.url).toBe('https://bevel.example.com/change-requests/7');
+    expect(detail).not.toHaveProperty('urlNote');
+    expect(detail?.url).not.toContain('alice');
+    expect(detail?.url).not.toContain('feature');
+  });
+
+  it('includes a proxied deployment\'s path prefix', async () => {
+    const detail = await detailWith('https://example.com/hexis/');
+    expect(detail?.url).toBe('https://example.com/hexis/change-requests/7');
+  });
+
+  it('stays relative with a note when no address is configured', async () => {
+    const detail = await detailWith(null);
+    expect(detail?.number).toBe(7);
+    expect(detail?.url).toBe('/change-requests/7');
+    expect(detail?.urlNote).toBe('Set PUBLIC_FRONTEND_URL to get absolute links.');
+  });
 });

package/src/modules/workflow/git/__tests__/pull-request.service.list-fetch.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { PullRequestService } from '../pull-request.service.js';
+import type { Database } from '../../../database/connection.js';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { GitService } from '../git.service.js';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+
+/**
+ * What a change-request LIST is allowed to cost.
+ *
+ * REPRODUCED against a running instance (ticket log, 2026-09-18): a cold
+ * `GET /api/workflow/change-requests/for-me?fresh=1` took 1.31s at two open
+ * requests and 3.48s at five — about 0.55s more per additional request. The
+ * cause is per-request: every summary needs the request's touched paths, and
+ * `changedPathsForPr` fetches the two refs it is about before diffing them,
+ * so the list paid one NETWORK ROUND TRIP per open request. It is re-read
+ * after every proposal and polled every 60s, and the tree asks two list
+ * endpoints at once, so the cost landed twice over.
+ *
+ * The refs still have to be fresh. They are refreshed once for the whole
+ * clone instead — `ensureRemotesFetched` is one `git fetch --prune origin`,
+ * TTL-cached, sharing an in-flight fetch between callers.
+ */
+
+const row = (number: number, sourceBranch: string) => ({
+  id: `cr-${number}`,
+  number,
+  sourceBranch,
+  targetBranch: 'main',
+  title: `Changes ${number}`,
+  body: '',
+  authorEmail: 'biz2@bevel.software',
+  authorName: 'Biz Two',
+  state: 'open',
+  mergedSha: null,
+  createdAt: new Date('2026-09-18T00:00:00Z'),
+  updatedAt: null,
+  closedAt: null,
+});
+
+function harness(rows = [row(1, 'suggestions/a/knowledge'), row(2, 'suggestions/b/knowledge')]) {
+  const db = {
+    select: () => ({
+      from: () => ({
+        where: () => ({ orderBy: async () => rows, limit: async () => rows }),
+      }),
+    }),
+  } as unknown as Database;
+  const changedPathsForPr = vi.fn(async () => ['Shared/one.pdf']);
+  const git = { changedPathsForPr } as unknown as GitService;
+  const ensureRemotesFetched = vi.fn(async () => undefined);
+  const workspace = {
+    findAnyWorkspaceId: async () => 'ws-main',
+    ensureRemotesFetched,
+  } as unknown as WorkspaceService;
+  const access = {
+    canWriteBatchAtRef: async (_w: string, _r: string, _e: string, asked: string[]) =>
+      new Map(asked.map((p) => [p, true])),
+  } as unknown as IAccessControl;
+  return {
+    svc: new PullRequestService(db, workspace, access, git),
+    changedPathsForPr,
+    ensureRemotesFetched,
+  };
+}
+
+describe('the change-request list refreshes the clone once, not once per request', () => {
+  it('fetches the clone once and asks for no per-request fetch', async () => {
+    const { svc, changedPathsForPr, ensureRemotesFetched } = harness();
+
+    const list = await svc.listOpenPrs({ fresh: true });
+
+    expect(list).toHaveLength(2);
+    expect(ensureRemotesFetched).toHaveBeenCalledTimes(1);
+    // FORCED on a fresh read, for the reason the read is fresh at all: the
+    // caller knows the remote just moved, and a fetch skipped by its own 30s
+    // TTL would answer about a request whose branch this clone has not seen.
+    expect(ensureRemotesFetched).toHaveBeenCalledWith('ws-main', { force: true });
+    // Two requests, two diffs — and neither of them a network round trip.
+    expect(changedPathsForPr).toHaveBeenCalledTimes(2);
+    for (const call of changedPathsForPr.mock.calls) {
+      expect(call[3]).toEqual({ fetch: false });
+    }
+  });
+
+  it('does not grow its fetch count with the number of open requests', async () => {
+    const five = [1, 2, 3, 4, 5].map((n) => row(n, `suggestions/${n}/knowledge`));
+    const { svc, ensureRemotesFetched } = harness(five);
+    expect(await svc.listOpenPrs({ fresh: true })).toHaveLength(5);
+    expect(ensureRemotesFetched).toHaveBeenCalledTimes(1);
+  });
+
+  it('touches the network not at all when there is nothing to summarise', async () => {
+    const { svc, ensureRemotesFetched, changedPathsForPr } = harness([]);
+    expect(await svc.listOpenPrs({ fresh: true })).toEqual([]);
+    expect(ensureRemotesFetched).not.toHaveBeenCalled();
+    expect(changedPathsForPr).not.toHaveBeenCalled();
+  });
+
+  it('leaves the fetch TTL alone for a background poll', async () => {
+    const { svc, ensureRemotesFetched } = harness();
+    // No `fresh`: nobody said the remote moved, so the clone is refreshed at
+    // whatever rate `ensureRemotesFetched` sees fit. (A branch the clone has
+    // never heard of is still fetched — `changedPathsForPr` does that for
+    // itself, so a poll can be a poll without hiding a request.)
+    await svc.listOpenPrs();
+    expect(ensureRemotesFetched).toHaveBeenCalledWith('ws-main', { force: false });
+  });
+
+  it('still answers when the refresh itself fails — the refs are then as old as the last one', async () => {
+    const { svc, changedPathsForPr, ensureRemotesFetched } = harness();
+    ensureRemotesFetched.mockRejectedValue(new Error('origin unreachable'));
+    // Degrades exactly as the per-request fetch did (it was `.catch(() => undefined)`
+    // too): the local refs are used, and a request whose diff cannot be
+    // computed reports no touched paths.
+    const list = await svc.listOpenPrs({ fresh: true });
+    expect(list).toHaveLength(2);
+    expect(changedPathsForPr).toHaveBeenCalledTimes(2);
+  });
+});

package/src/modules/workflow/git/__tests__/pull-request.service.placeholder.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { PullRequestService } from '../pull-request.service.js';
+import type { Database } from '../../../database/connection.js';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { GitService } from '../git.service.js';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+
+const ROW = {
+  id: 'cr-9',
+  number: 9,
+  sourceBranch: 'alice/new-folders',
+  targetBranch: 'current-company-state',
+  title: 'Folders',
+  body: '',
+  authorEmail: 'alice@bevel.software',
+  authorName: 'Alice',
+  state: 'open',
+  mergedSha: null,
+  createdAt: new Date('2026-09-01T00:00:00Z'),
+  updatedAt: null,
+  closedAt: null,
+};
+
+/**
+ * The empty-folder placeholder is never content, so the change-request LIST
+ * (the summaries every "for me" view counts and routes by) leaves it out, just
+ * as the detail's file list does. The raw `changedPathsForPr` keeps it — that
+ * is the authoritative empty-request check, and is not what a list shows.
+ */
+describe('PullRequestService summaries — folder placeholder', () => {
+  function harness(paths: string[] = ['Reports/.gitkeep', 'Reports/Empty/.gitkeep', 'Reports/q3.md']) {
+    const db = {
+      select: () => ({
+        from: () => ({
+          where: () => ({
+            orderBy: async () => [ROW],
+            limit: async () => [ROW],
+          }),
+        }),
+      }),
+    } as unknown as Database;
+    const changedPathsForPr = vi.fn(async () => paths);
+    const git = { changedPathsForPr } as unknown as GitService;
+    const workspace = {
+      findAnyWorkspaceId: async () => 'ws-main',
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    // Bob may write under `Reports/` and nowhere else.
+    const canWriteBatchAtRef = vi.fn(async (_ws: string, _ref: string, _email: string, asked: string[]) =>
+      new Map(asked.map((p) => [p, p.startsWith('Reports/')])),
+    );
+    const access = { canWriteBatchAtRef } as unknown as IAccessControl;
+    const svc = new PullRequestService(db, workspace, access, git);
+    return { svc, changedPathsForPr, canWriteBatchAtRef };
+  }
+
+  it('listOpenPrs reports only real files as touched paths', async () => {
+    const { svc, changedPathsForPr } = harness();
+    const [summary] = await svc.listOpenPrs({ fresh: true });
+    expect(changedPathsForPr).toHaveBeenCalledTimes(1);
+    expect(summary.touchedNodePaths).toEqual(['Reports/q3.md']);
+  });
+
+  it('a request that only creates a folder still routes to the folder\'s owners', async () => {
+    const { svc, canWriteBatchAtRef } = harness(['Reports/Empty/.gitkeep']);
+    const [routed] = await svc.listPrsForOwnerEmail('ws-main', 'bob@bevel.software', { fresh: true });
+    expect(routed?.number).toBe(9);
+    // Routed by the placeholder, but never showing it.
+    expect(routed.touchedNodePaths).toEqual([]);
+    // Access was asked about the placeholder, however the lookup is batched.
+    expect(canWriteBatchAtRef.mock.calls.some((c) => c[3].includes('Reports/Empty/.gitkeep'))).toBe(true);
+  });
+
+  it('a folder-only request outside the viewer\'s scope does not route to them', async () => {
+    const { svc } = harness(['Elsewhere/.gitkeep']);
+    expect(await svc.listPrsForOwnerEmail('ws-main', 'bob@bevel.software', { fresh: true })).toEqual([]);
+  });
+});