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

package/src/modules/kb-sync/__tests__/kb-sync.routes.test.ts

@@ -0,0 +1,297 @@
+import { createHmac } from 'node:crypto';
+import type { Server } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createKbSyncRoutes, isSyncRawBodyPath } from '../kb-sync.routes.js';
+import type { IKbSyncService, SyncResult } from '../kb-sync.interface.js';
+
+const SECRET = 'a-very-long-and-random-sync-secret';
+
+const SYNCED: SyncResult = {
+  status: 'synced',
+  results: [{ branch: 'main', outcome: 'updated', from: 'aaa', to: 'bbb' }],
+  changeRequests: { closedDeletedBranch: 0 },
+};
+
+let server: Server | undefined;
+afterEach(() => {
+  server?.close();
+  server = undefined;
+});
+
+async function mount(opts: {
+  secret?: string;
+  result?: SyncResult;
+  admin?: boolean;
+  /** Install the production-shaped global JSON parser in front of the router. */
+  globalJson?: boolean;
+}): Promise<{ base: string; sync: ReturnType<typeof vi.fn> }> {
+  // A suite may mount twice in one test; the earlier server must not outlive it.
+  server?.close();
+  const sync = vi.fn(async () => opts.result ?? SYNCED);
+  const kbSync: IKbSyncService = { sync };
+  const app = express();
+  // Mirrors production: the global JSON parser skips `/api/sync`, so the
+  // router's own raw parser sees the bytes. Installing `express.json()` here
+  // would hide exactly the wiring bug the signature path depends on.
+  if (opts.globalJson) {
+    const json = express.json();
+    app.use((req, res, next) => (isSyncRawBodyPath(req.path) ? next() : json(req, res, next)));
+  }
+  app.use(
+    '/api',
+    createKbSyncRoutes({
+      kbSync,
+      syncSecret: () => opts.secret ?? SECRET,
+      authService: {
+        verifyToken: (token: string) => {
+          if (token !== 'jwt-ok') throw new Error('bad token');
+          return { userId: 'u1', email: 'person@example.com' };
+        },
+      },
+      adminAccess: { isAdmin: async () => opts.admin === true },
+    }),
+  );
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, resolve);
+  });
+  const address = server!.address();
+  if (typeof address === 'string' || !address) throw new Error('no port');
+  return { base: `http://127.0.0.1:${address.port}/api/sync`, sync };
+}
+
+function post(url: string, init: { headers?: Record<string, string>; body?: string } = {}) {
+  return fetch(url, { method: 'POST', headers: init.headers ?? {}, body: init.body });
+}
+
+describe('POST /api/sync — credentials', () => {
+  it('401 with no credential, and advertises the bearer challenge', async () => {
+    const { base, sync } = await mount({});
+    const res = await post(base);
+    expect(res.status).toBe(401);
+    expect(res.headers.get('www-authenticate')).toContain('Bearer');
+    expect(sync).not.toHaveBeenCalled();
+  });
+
+  it('401 with the wrong secret', async () => {
+    const { base, sync } = await mount({});
+    const res = await post(base, { headers: { authorization: 'Bearer wrong' } });
+    expect(res.status).toBe(401);
+    expect(sync).not.toHaveBeenCalled();
+  });
+
+  it('503 when no secret is configured and a hook presents one', async () => {
+    const { base } = await mount({ secret: '' });
+    const res = await post(base, { headers: { authorization: `Bearer ${SECRET}` } });
+    expect(res.status).toBe(503);
+    expect(((await res.json()) as { error: string }).error).toContain('KB_SYNC_SECRET');
+  });
+
+  it("an admin's session works; a non-admin's does not", async () => {
+    const admin = await mount({ admin: true });
+    expect((await post(admin.base, { headers: { authorization: 'Bearer jwt-ok' } })).status).toBe(200);
+    const person = await mount({ admin: false });
+    expect((await post(person.base, { headers: { authorization: 'Bearer jwt-ok' } })).status).toBe(401);
+  });
+
+  it('accepts the GitLab token header', async () => {
+    const { base } = await mount({});
+    const res = await post(base, { headers: { 'x-gitlab-token': SECRET } });
+    expect(res.status).toBe(200);
+  });
+
+  it('accepts a GitHub signature computed over the exact bytes received', async () => {
+    const { base, sync } = await mount({});
+    const body = '{"ref":"refs/heads/main","after":"b"}';
+    const sig = 'sha256=' + createHmac('sha256', SECRET).update(body).digest('hex');
+    const res = await post(base, {
+      headers: { 'x-hub-signature-256': sig, 'content-type': 'application/json' },
+      body,
+    });
+    expect(res.status).toBe(200);
+    expect(sync).toHaveBeenCalledWith(expect.objectContaining({ branches: ['main'] }));
+  });
+});
+
+describe('POST /api/sync — body and result', () => {
+  it('an empty body syncs everything', async () => {
+    const { base, sync } = await mount({});
+    const res = await post(base, { headers: { authorization: `Bearer ${SECRET}` } });
+    expect(res.status).toBe(200);
+    expect(sync).toHaveBeenCalledWith(expect.objectContaining({ branches: 'all' }));
+    expect(await res.json()).toEqual(SYNCED);
+  });
+
+  it('an explicit body names the branches', async () => {
+    const { base, sync } = await mount({});
+    await post(base, {
+      headers: { authorization: `Bearer ${SECRET}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ branches: ['main', 'ali/x'] }),
+    });
+    expect(sync).toHaveBeenCalledWith(expect.objectContaining({ branches: ['main', 'ali/x'] }));
+  });
+
+  it('an Azure DevOps push payload names the pushed branch', async () => {
+    const { base, sync } = await mount({});
+    await post(base, {
+      headers: { authorization: `Bearer ${SECRET}`, 'content-type': 'application/json' },
+      body: JSON.stringify({
+        eventType: 'git.push',
+        resource: { refUpdates: [{ name: 'refs/heads/ali/x' }] },
+      }),
+    });
+    expect(sync).toHaveBeenCalledWith(expect.objectContaining({ branches: ['ali/x'] }));
+  });
+
+  it('400 for a branch name git would refuse, and for a body that is not JSON', async () => {
+    const { base, sync } = await mount({});
+    const bad = await post(base, {
+      headers: { authorization: `Bearer ${SECRET}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ branches: ['--upload-pack=x'] }),
+    });
+    expect(bad.status).toBe(400);
+    const notJson = await post(base, {
+      headers: { authorization: `Bearer ${SECRET}`, 'content-type': 'application/json' },
+      body: '{not json',
+    });
+    expect(notJson.status).toBe(400);
+    expect(sync).not.toHaveBeenCalled();
+  });
+
+  it('409 when any branch is in conflict — the message rides in the body', async () => {
+    const { base } = await mount({
+      result: {
+        status: 'partial',
+        results: [
+          { branch: 'ali/x', outcome: 'updated', from: 'a', to: 'b' },
+          {
+            branch: 'main',
+            outcome: 'conflict',
+            conflictedPaths: ['Plugins/x/SKILL.md'],
+            error: 'main is not in sync yet: Plugins/x/SKILL.md changed both in Hexis and on the git host. Recovery is queued; if this stays, open the files on main in Hexis, keep what you want, and save.',
+          },
+        ],
+        changeRequests: { closedDeletedBranch: 0 },
+      },
+    });
+    const res = await post(base, { headers: { authorization: `Bearer ${SECRET}` } });
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as SyncResult;
+    expect(body.results[1]).toMatchObject({ outcome: 'conflict' });
+    expect((body.results[1] as { error: string }).error).toContain('Recovery is queued');
+  });
+
+  it('503 when a branch could not be pulled and none is in conflict', async () => {
+    const { base } = await mount({
+      result: {
+        status: 'partial',
+        results: [{ branch: 'main', outcome: 'error', error: 'could not read from remote' }],
+        changeRequests: { closedDeletedBranch: 0 },
+      },
+    });
+    expect((await post(base, { headers: { authorization: `Bearer ${SECRET}` } })).status).toBe(503);
+  });
+});
+
+describe('POST /api/sync/<branch> — the branch in the URL', () => {
+  it('syncs exactly that branch, spelled as segments or percent-encoded', async () => {
+    for (const spelling of ['main', 'ali/new-skill', 'ali%2Fnew-skill']) {
+      const { base, sync } = await mount({});
+      const res = await post(`${base}/${spelling}`, { headers: { authorization: `Bearer ${SECRET}` } });
+      expect(res.status).toBe(200);
+      expect(sync).toHaveBeenCalledWith(expect.objectContaining({ branches: [decodeURIComponent(spelling)] }));
+      server?.close();
+    }
+  });
+
+  it('ignores the body for branch selection — a GitHub Action can post anything', async () => {
+    const { base, sync } = await mount({});
+    await post(`${base}/main`, {
+      headers: { authorization: `Bearer ${SECRET}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ branches: ['other'] }),
+    });
+    expect(sync).toHaveBeenCalledWith(expect.objectContaining({ branches: ['main'] }));
+  });
+
+  it('still checks the credential first', async () => {
+    const { base, sync } = await mount({});
+    expect((await post(`${base}/main`)).status).toBe(401);
+    expect(sync).not.toHaveBeenCalled();
+  });
+
+  it('400 for a branch name git would refuse', async () => {
+    const { base, sync } = await mount({});
+    const res = await post(`${base}/--upload-pack=x`, { headers: { authorization: `Bearer ${SECRET}` } });
+    expect(res.status).toBe(400);
+    expect(sync).not.toHaveBeenCalled();
+  });
+});
+
+describe('POST /api/sync — behind the production JSON parser', () => {
+  it('the branch route still sees the raw bytes, so a GitHub signature verifies', async () => {
+    const { base, sync } = await mount({ globalJson: true });
+    const body = '{"ref":"refs/heads/main"}';
+    const sig = 'sha256=' + createHmac('sha256', SECRET).update(body).digest('hex');
+    const res = await post(`${base}/main`, {
+      headers: { 'x-hub-signature-256': sig, 'content-type': 'application/json' },
+      body,
+    });
+    expect(res.status).toBe(200);
+    expect(sync).toHaveBeenCalledWith(expect.objectContaining({ branches: ['main'] }));
+  });
+
+  it('and so does the bare route', async () => {
+    const { base } = await mount({ globalJson: true });
+    const body = '{"ref":"refs/heads/main"}';
+    const sig = 'sha256=' + createHmac('sha256', SECRET).update(body).digest('hex');
+    const res = await post(base, {
+      headers: { 'x-hub-signature-256': sig, 'content-type': 'application/json' },
+      body,
+    });
+    expect(res.status).toBe(200);
+  });
+
+  it('isSyncRawBodyPath covers both shapes and nothing else', () => {
+    expect(isSyncRawBodyPath('/api/sync')).toBe(true);
+    expect(isSyncRawBodyPath('/api/sync/main')).toBe(true);
+    expect(isSyncRawBodyPath('/api/sync/ali/new-skill')).toBe(true);
+    expect(isSyncRawBodyPath('/api/synchronise')).toBe(false);
+    expect(isSyncRawBodyPath('/api/setup/status')).toBe(false);
+  });
+});
+
+describe('POST /api/sync — the response marker', () => {
+  it('every answer carries the header a proxy never sets, including the 503 and the 401', async () => {
+    const ok = await mount({});
+    expect((await post(ok.base, { headers: { authorization: `Bearer ${SECRET}` } })).headers.get('x-hexis-sync')).toBe('result');
+    server?.close();
+    const down = await mount({
+      result: {
+        status: 'partial',
+        results: [{ branch: 'main', outcome: 'error', error: 'could not read from remote' }],
+        changeRequests: { closedDeletedBranch: 0 },
+      },
+    });
+    const res = await post(down.base, { headers: { authorization: `Bearer ${SECRET}` } });
+    expect(res.status).toBe(503);
+    expect(res.headers.get('x-hexis-sync')).toBe('result');
+    expect((await post(down.base)).headers.get('x-hexis-sync')).toBe('result');
+  });
+});
+
+describe('POST /api/Sync — an odd-cased URL', () => {
+  it('is matched by Express and by the raw-body carve-out alike, so it works exactly like the lower-case one', async () => {
+    const { base, sync } = await mount({ globalJson: true });
+    const oddCase = base.replace('/api/sync', '/api/Sync');
+    const body = '{"ref":"refs/heads/main"}';
+    const sig = 'sha256=' + createHmac('sha256', SECRET).update(body).digest('hex');
+    const res = await post(`${oddCase}/main`, {
+      headers: { 'x-hub-signature-256': sig, 'content-type': 'application/json' },
+      body,
+    });
+    expect(res.status).toBe(200);
+    expect(sync).toHaveBeenCalledWith(expect.objectContaining({ branches: ['main'] }));
+    expect(isSyncRawBodyPath('/api/Sync')).toBe(true);
+    expect(isSyncRawBodyPath('/API/SYNC/main')).toBe(true);
+  });
+});

package/src/modules/kb-sync/__tests__/kb-sync.service.test.ts

@@ -0,0 +1,295 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
+import { KbSyncService } from '../kb-sync.service.js';
+import type { SyncWorkflowPort, SyncWorkspacePort } from '../kb-sync.interface.js';
+
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+function workspaces(branches: string[]): SyncWorkspacePort {
+  return {
+    listClonedWorkspaces: async () => branches.map((branch) => ({ id: encodeURIComponent(branch), branch })),
+  };
+}
+
+function updated(branch: string): BranchSyncOutcome {
+  return { branch, outcome: 'updated', from: 'aaa', to: 'bbb' };
+}
+
+describe('KbSyncService', () => {
+  it('syncs every known clone for an "all" request and reports unknown branches as not cloned', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+
+    const all = await svc.sync({ branches: 'all' });
+    expect(all.status).toBe('synced');
+    expect(all.results.map((r) => r.branch)).toEqual(['main', 'ali/x']);
+    expect(all.changeRequests.closedDeletedBranch).toBe(1);
+    expect(workflow.syncWorkspaceFromRemote).toHaveBeenCalledWith('ali%2Fx');
+
+    const some = await svc.sync({ branches: ['ali/x', 'juan/other'] });
+    expect(some.results).toEqual([updated('ali/x'), { branch: 'juan/other', outcome: 'not-cloned' }]);
+  });
+
+  it('a conflict or an error makes the result partial; the other branches still sync', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> =>
+        id === 'main'
+          ? { branch: 'main', outcome: 'conflict', conflictedPaths: ['a.md'], error: 'msg' }
+          : updated(decodeURIComponent(id)),
+      ),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const r = await svc.sync({ branches: 'all' });
+    expect(r.status).toBe('partial');
+    expect(r.results[1]).toEqual(updated('ali/x'));
+  });
+
+  it('a failing sweep does not fail the sync', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async () => updated('main')),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => {
+        throw new Error('origin down');
+      }),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main']));
+    const r = await svc.sync({ branches: 'all' });
+    expect(r.status).toBe('synced');
+    expect(r.changeRequests.closedDeletedBranch).toBe(0);
+  });
+
+  it('coalesces everything that arrives mid-run into ONE follow-up carrying the union', async () => {
+    const gate = deferred<void>();
+    // Each run's branches, in order. The first run parks on `gate` so the
+    // others arrive mid-run; a new run is recognised by its first branch
+    // landing after the gate opened.
+    const calls: string[][] = [['']];
+    let gateOpened = false;
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        const branch = decodeURIComponent(id);
+        if (!gateOpened && branch === 'main') {
+          await gate.promise;
+          gateOpened = true;
+          calls[0] = [];
+        } else if (gateOpened && calls.length === 1) {
+          calls.push([]);
+        }
+        calls[calls.length - 1].push(branch);
+        return updated(branch);
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+
+    const first = svc.sync({ branches: ['main'] });
+    // Three requests land while the first is parked on `gate`.
+    const second = svc.sync({ branches: ['ali/x'] });
+    const third = svc.sync({ branches: ['juan/y'] });
+    const fourth = svc.sync({ branches: ['ali/x'] });
+    gate.resolve();
+
+    const [r1, r2, r3, r4] = await Promise.all([first, second, third, fourth]);
+    expect(r1.results.map((r) => r.branch)).toEqual(['main']);
+    // One follow-up, the union, in arrival order — and every mid-run caller
+    // answered for the branches IT asked about, never for the others'.
+    expect(calls).toEqual([['main'], ['ali/x', 'juan/y']]);
+    expect(r2.results.map((r) => r.branch)).toEqual(['ali/x']);
+    expect(r3.results.map((r) => r.branch)).toEqual(['juan/y']);
+    expect(r4.results.map((r) => r.branch)).toEqual(['ali/x']);
+    expect(workflow.closeChangeRequestsWithDeletedBranches).toHaveBeenCalledTimes(2);
+  });
+
+  it('an "all" arriving mid-run absorbs the queued branches', async () => {
+    const gate = deferred<void>();
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        if (id === 'main') await gate.promise;
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const first = svc.sync({ branches: ['main'] });
+    const second = svc.sync({ branches: ['ali/x'] });
+    const third = svc.sync({ branches: 'all' });
+    gate.resolve();
+    await first;
+    // The follow-up pulled everything; the "all" caller hears all of it, the
+    // one-branch caller only its branch.
+    expect((await third).results.map((x) => x.branch)).toEqual(['main', 'ali/x', 'juan/y']);
+    expect((await second).results.map((x) => x.branch)).toEqual(['ali/x']);
+  });
+});
+
+describe('KbSyncService.lastSync', () => {
+  it('is null before the first sync, then records when, who and what', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    let clock = 1_000;
+    const svc = new KbSyncService(workflow, workspaces(['main']), () => clock);
+    expect(svc.lastSync()).toBeNull();
+
+    await svc.sync({ branches: 'all', by: 'bearer' });
+    expect(svc.lastSync()).toEqual({
+      at: 1_000,
+      by: 'bearer',
+      status: 'synced',
+      results: [updated('main')],
+    });
+
+    clock = 2_000;
+    await svc.sync({ branches: ['main'], by: 'admin@example.com' });
+    expect(svc.lastSync()).toMatchObject({ at: 2_000, by: 'admin@example.com' });
+  });
+
+  it('a coalesced follow-up names everyone who asked for it', async () => {
+    const gate = deferred<void>();
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        if (id === 'main') await gate.promise;
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const first = svc.sync({ branches: ['main'], by: 'bearer' });
+    const second = svc.sync({ branches: ['ali/x'], by: 'github-signature' });
+    const third = svc.sync({ branches: ['ali/x'], by: 'admin@example.com' });
+    gate.resolve();
+    await Promise.all([first, second, third]);
+    expect(svc.lastSync()?.by).toBe('github-signature, admin@example.com');
+  });
+});
+
+describe('KbSyncService — a throwing branch step', () => {
+  it('becomes an error outcome; the other branches, the sweep and the record all still happen', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        if (id === 'main') throw new Error('fatal: unable to access https://x:ghp_secret@host/r');
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const r = await svc.sync({ branches: 'all', by: 'bearer' });
+    expect(r.status).toBe('partial');
+    expect(r.results[0]).toMatchObject({ branch: 'main', outcome: 'error' });
+    expect((r.results[0] as { error: string }).error).not.toContain('ghp_secret');
+    expect(r.results[1]).toEqual(updated('ali/x'));
+    expect(r.changeRequests.closedDeletedBranch).toBe(1);
+    expect(svc.lastSync()?.status).toBe('partial');
+  });
+});
+
+describe('KbSyncService — clones the host no longer has, and clones that cannot be read', () => {
+  it('a remote-gone branch is retired through the workflow, counts as clean, and does not stop the others', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> =>
+        id === 'ali%2Fx' ? { branch: 'ali/x', outcome: 'remote-gone' } : updated(decodeURIComponent(id)),
+      ),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['ali/x', 'main']));
+    const r = await svc.sync({ branches: 'all' });
+    expect(r.status).toBe('synced');
+    expect(r.results).toEqual([{ branch: 'ali/x', outcome: 'remote-gone' }, updated('main')]);
+    expect(workflow.retireRemoteGoneClone).toHaveBeenCalledTimes(1);
+    expect(workflow.retireRemoteGoneClone).toHaveBeenCalledWith('ali%2Fx');
+  });
+
+  it('a clone that could not be read is that branch’s error, not everyone’s', async () => {
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const port: SyncWorkspacePort = {
+      listClonedWorkspaces: async () => [
+        { id: 'main', branch: 'main' },
+        { id: 'juan%2Fy', branch: 'juan/y', unreadable: "Could not read this branch's clone: EPERM" },
+      ],
+    };
+    const svc = new KbSyncService(workflow, port);
+    const r = await svc.sync({ branches: 'all' });
+    expect(r.status).toBe('partial');
+    expect(r.results).toEqual([
+      updated('main'),
+      { branch: 'juan/y', outcome: 'error', error: "Could not read this branch's clone: EPERM" },
+    ]);
+    expect(workflow.syncWorkspaceFromRemote).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('KbSyncService — a coalesced caller is judged by its own branches', () => {
+  it("branch A's hook is not failed by branch B's conflict in the same follow-up", async () => {
+    const gate = deferred<void>();
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> => {
+        if (id === 'main') await gate.promise;
+        if (id === 'juan%2Fy') return { branch: 'juan/y', outcome: 'conflict', conflictedPaths: ['a.md'], error: 'msg' };
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const first = svc.sync({ branches: ['main'] });
+    const hookA = svc.sync({ branches: ['ali/x'] });
+    const hookB = svc.sync({ branches: ['juan/y'] });
+    gate.resolve();
+    await first;
+    const a = await hookA;
+    const b = await hookB;
+    expect(a).toMatchObject({ status: 'synced', results: [updated('ali/x')] });
+    expect(b.status).toBe('partial');
+    expect(b.results.map((r) => r.outcome)).toEqual(['conflict']);
+    // The record keeps the whole follow-up.
+    expect(svc.lastSync()?.results.map((r) => r.branch)).toEqual(['ali/x', 'juan/y']);
+  });
+});
+
+describe('KbSyncService — a waiter keeps the branches it asked for', () => {
+  it('a caller that edits its array after queueing changes nothing about its sync or its answer', async () => {
+    const gate = deferred<void>();
+    const workflow: SyncWorkflowPort = {
+      syncWorkspaceFromRemote: vi.fn(async (id: string) => {
+        if (id === 'main') await gate.promise;
+        return updated(decodeURIComponent(id));
+      }),
+      closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
+      retireRemoteGoneClone: vi.fn(async () => true),
+    };
+    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const first = svc.sync({ branches: ['main'] });
+    const asked = ['ali/x'];
+    const waiting = svc.sync({ branches: asked });
+    asked.push('juan/y');
+    asked[0] = 'main';
+    gate.resolve();
+    await first;
+    const r = await waiting;
+    expect(r.results.map((x) => x.branch)).toEqual(['ali/x']);
+    expect(workflow.syncWorkspaceFromRemote).not.toHaveBeenCalledWith('juan%2Fy');
+  });
+});