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

package/src/modules/workspace/__tests__/workspace.routes.move-platform-files.test.ts

@@ -0,0 +1,327 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import express from 'express';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import { createWorkspaceRoutes } from '../workspace.routes.js';
+import type { ICreatorAccess } from '../../access-model/creator.js';
+import type { WorkspaceService } from '../workspace.service.js';
+
+/**
+ * `PATCH /workspace/:id/file` is the one door rename, move and the sidebar's
+ * drag all come through, so the platform-file rule is stated once, here.
+ *
+ * The bug it closes: the tester moved `access.md` and `.bevelignore` out of
+ * the repository root. A root with no `access.md` denies write to everyone,
+ * so the move that would put it back was the move the gate refused, and
+ * deleting the instance looked like the only way out.
+ */
+
+const KB = 'knowledge-base';
+const USER_ID = 'user-1';
+const USER = { id: USER_ID, email: 'alice@example.com', name: 'Alice' };
+const WORKSPACE_ID = 'main';
+
+interface Harness {
+  server: Server;
+  baseUrl: string;
+  moveEntry: ReturnType<typeof vi.fn>;
+  acquireLock: ReturnType<typeof vi.fn>;
+  canRestorePlatformFile: ReturnType<typeof vi.fn>;
+  workspaceDir: string;
+}
+
+async function makeHarness(): Promise<Harness> {
+  const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), 'platform-files-'));
+
+  const canRestorePlatformFile = vi.fn(async () => false);
+  const accessControl = {
+    canWrite: vi.fn(),
+    canWriteBatch: vi.fn(),
+    canDownload: vi.fn(),
+    eligibleWriters: vi.fn(),
+    eligibleWriterEmails: vi.fn(),
+    invalidate: vi.fn(),
+    findEmailByHash: vi.fn(),
+    canWriteAtRef: vi.fn(),
+    canWriteBatchAtRef: vi.fn(),
+    eligibleWritersAtRef: vi.fn(),
+    eligibleWritersForPathsAtRef: vi.fn(),
+    canRestorePlatformFile,
+  } as unknown as IAccessControl;
+
+  const moveEntry = vi.fn(async () => undefined);
+  const workspaceServiceMock: Partial<WorkspaceService> = {
+    getWorkspacePath: vi.fn(async () => workspaceDir),
+    withFolderTurn: async <T>(_id: string, _dir: string, op: () => Promise<T>) => op(),
+    moveEntry: moveEntry as unknown as WorkspaceService['moveEntry'],
+  };
+  const workspaceService = workspaceServiceMock as WorkspaceService;
+
+  const acquireLock = vi.fn(async () => ({ acquired: true, lock: {} as never }));
+  const workflowServiceMock: Partial<IWorkflowService> = {
+    getLock: vi.fn(async () => null),
+    acquireLock: acquireLock as unknown as IWorkflowService['acquireLock'],
+    releaseLock: vi.fn(async () => undefined as never),
+    releaseLockNoCommit: vi.fn(async () => undefined as never),
+  };
+  const workflowService = workflowServiceMock as unknown as IWorkflowService;
+
+  const authService = { getUserById: vi.fn(async () => USER) } as unknown as AuthService;
+  const eventBus = { emit: vi.fn() } as unknown as WorkflowEventBus;
+  const creatorAccess: ICreatorAccess = {
+    planForCreate: async () => null,
+    grantInExtractedFile: async () => null,
+    noteAccessFileWritten: () => {},
+  };
+
+  const app = express();
+  app.use(express.json());
+  app.use('/api', (req, _res, next) => {
+    (req as unknown as { userId: string }).userId = USER_ID;
+    next();
+  });
+  app.use('/api', createWorkspaceRoutes(
+    workspaceService,
+    authService,
+    workflowService,
+    eventBus,
+    accessControl,
+    KB,
+    creatorAccess,
+    { isAdmin: async () => false } as unknown as IAdminAccessService,
+    new NodeFs(),
+  ));
+
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const port = (server.address() as AddressInfo).port;
+  return {
+    server,
+    baseUrl: `http://127.0.0.1:${port}`,
+    moveEntry,
+    acquireLock,
+    canRestorePlatformFile,
+    workspaceDir,
+  };
+}
+
+async function move(h: Harness, oldPath: string, newPath: string) {
+  const res = await fetch(`${h.baseUrl}/api/workspace/${WORKSPACE_ID}/file`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ oldPath, newPath }),
+  });
+  return { status: res.status, body: await res.json() as { error?: string; status?: string } };
+}
+
+describe('a platform file stays in its folder', () => {
+  let h: Harness;
+
+  beforeEach(async () => {
+    h = await makeHarness();
+  });
+  afterEach(async () => {
+    await new Promise<void>((resolve) => h.server.close(() => resolve()));
+    await fs.rm(h.workspaceDir, { recursive: true, force: true });
+  });
+
+  // Each of the four, at a place the platform reads it from. `access.md` and
+  // `.bevelignore` are read wherever they sit; `roles.yaml` and `AGENTS.md`
+  // are read from the repository root only.
+  const PLATFORM_FILES = [
+    { name: 'access.md', at: `${KB}/Sales/access.md` },
+    { name: '.bevelignore', at: `${KB}/Sales/.bevelignore` },
+    { name: 'roles.yaml', at: `${KB}/roles.yaml` },
+    { name: 'AGENTS.md', at: `${KB}/AGENTS.md` },
+  ];
+
+  it.each(PLATFORM_FILES)('refuses a rename of $name with the sentence', async ({ name, at }) => {
+    const renamed = `${at.slice(0, at.lastIndexOf('/'))}/renamed-${name}`;
+    const res = await move(h, at, renamed);
+    expect(res.status).toBe(409);
+    expect(res.body.error).toBe(`${name} is a platform file and stays in its folder.`);
+    expect(h.moveEntry).not.toHaveBeenCalled();
+    expect(h.acquireLock).not.toHaveBeenCalled();
+  });
+
+  it.each(PLATFORM_FILES)('refuses a move of $name into another folder with the sentence', async ({ name, at }) => {
+    const res = await move(h, at, `${KB}/Elsewhere/${name}`);
+    expect(res.status).toBe(409);
+    expect(res.body.error).toBe(`${name} is a platform file and stays in its folder.`);
+    expect(h.moveEntry).not.toHaveBeenCalled();
+  });
+
+  // A drag is a move: the sidebar's drop sends this same call with the
+  // dropped-on folder as the destination, so it meets the same rule rather
+  // than one of its own. What the drop adds is the destination the drag
+  // makes easy to reach — the repository root — where a caller who is not an
+  // admin gets the refusal like anywhere else. (The sidebar's own refusal,
+  // before the call, is covered in `FileExplorer.test.tsx`.)
+  it.each(PLATFORM_FILES.filter((f) => f.at !== `${KB}/${f.name}`))(
+    'refuses a drop of $name onto the repository root with the sentence',
+    async ({ name, at }) => {
+      const res = await move(h, at, `${KB}/${name}`);
+      expect(res.status).toBe(409);
+      expect(res.body.error).toBe(`${name} is a platform file and stays in its folder.`);
+      expect(h.moveEntry).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(PLATFORM_FILES.filter((f) => f.at === `${KB}/${f.name}`))(
+    'refuses a drop of the root $name onto a folder with the sentence',
+    async ({ name, at }) => {
+      const res = await move(h, at, `${KB}/Archive/${name}`);
+      expect(res.status).toBe(409);
+      expect(res.body.error).toBe(`${name} is a platform file and stays in its folder.`);
+      expect(h.moveEntry).not.toHaveBeenCalled();
+    },
+  );
+
+  // The recovery move, for each of the four, from the place a misplaced copy
+  // is actually found to the place the platform reads it.
+  const RESTORES = [
+    { name: 'access.md', from: `${KB}/Misplaced/access.md`, to: `${KB}/access.md`, dest: 'access.md' },
+    { name: '.bevelignore', from: `${KB}/Misplaced/.bevelignore`, to: `${KB}/.bevelignore`, dest: '.bevelignore' },
+    { name: 'roles.yaml', from: `${KB}/Misplaced/roles.yaml`, to: `${KB}/roles.yaml`, dest: 'roles.yaml' },
+    { name: 'AGENTS.md', from: `${KB}/Misplaced/AGENTS.md`, to: `${KB}/AGENTS.md`, dest: 'AGENTS.md' },
+  ];
+
+  it.each(RESTORES)(
+    'an admin restores a misplaced $name, and only the destination carries the claim',
+    async ({ from, to, dest }) => {
+      h.canRestorePlatformFile.mockResolvedValue(true);
+      const res = await move(h, from, to);
+      expect(res.status).toBe(200);
+      expect(res.body).toEqual({ status: 'moved' });
+      expect(h.moveEntry).toHaveBeenCalledWith(WORKSPACE_ID, from, to);
+      // Asked about where the move LANDS, repo-relative — never about what it
+      // takes away. (What it takes away is the source, which the claim names
+      // so the write gate can check it without trusting this route.)
+      expect(h.canRestorePlatformFile).toHaveBeenCalledWith(WORKSPACE_ID, USER.email, dest);
+      // The source side is an ordinary write the caller must already hold; only
+      // the destination lock may present the restore claim to the write gate.
+      const claims = new Map(
+        h.acquireLock.mock.calls.map(
+          (c) => [c[2] as string, (c[4] as { platformRestore?: { source: string } })?.platformRestore],
+        ),
+      );
+      expect(claims.get(to)).toEqual({ source: from });
+      expect(claims.get(from)).toBeUndefined();
+    },
+  );
+
+  it.each(RESTORES)('a non-admin never gets the restore for $name', async ({ name, from, to }) => {
+    h.canRestorePlatformFile.mockResolvedValue(false);
+    const res = await move(h, from, to);
+    expect(h.canRestorePlatformFile).toHaveBeenCalledWith(WORKSPACE_ID, USER.email, name);
+    expect(res.status).toBe(409);
+    // Two sentences, because two different things are wrong. `access.md` and
+    // `.bevelignore` are read wherever they sit, so the misplaced copy is
+    // itself a platform file and the refusal is about MOVING one. A nested
+    // `roles.yaml` / `AGENTS.md` is ordinary content, so nothing is being
+    // moved out of place — what is refused is the file the destination would
+    // BECOME, which is the root's own `roles.yaml`, written by someone the
+    // access module just said may not restore it.
+    expect(res.body.error).toBe(
+      name === 'access.md' || name === '.bevelignore'
+        ? `${name} is a platform file and stays in its folder.`
+        : `${name} is a platform file name; a move cannot create a platform file.`,
+    );
+    expect(h.moveEntry).not.toHaveBeenCalled();
+    expect(h.acquireLock).not.toHaveBeenCalled();
+  });
+
+  it('an ordinary file cannot BECOME a platform file, at a free destination or an occupied one', async () => {
+    // `moveEntry` is a rename, so this is the only thing standing between a
+    // note and the rules of the folder it is renamed into. Nothing on the
+    // SOURCE side has anything to say about it: `Sales/deal.md` is content.
+    const created = await move(h, `${KB}/Sales/deal.md`, `${KB}/access.md`);
+    expect(created.status).toBe(409);
+    expect(created.body.error).toBe('access.md is a platform file name; a move cannot create a platform file.');
+
+    const renamedInPlace = await move(h, `${KB}/Sales/deal.md`, `${KB}/Sales/access.md`);
+    expect(renamedInPlace.status).toBe(409);
+    expect(renamedInPlace.body.error).toBe('access.md is a platform file name; a move cannot create a platform file.');
+
+    // The same answer with the file already there — the destination is a
+    // platform path either way, and the restore is the only move that lands
+    // on one.
+    await fs.mkdir(path.join(h.workspaceDir, KB), { recursive: true });
+    await fs.writeFile(path.join(h.workspaceDir, KB, '.bevelignore'), '*.tmp\n');
+    const onto = await move(h, `${KB}/Sales/deal.md`, `${KB}/.bevelignore`);
+    expect(onto.status).toBe(409);
+    expect(onto.body.error).toBe('.bevelignore is a platform file name; a move cannot create a platform file.');
+
+    expect(h.moveEntry).not.toHaveBeenCalled();
+    expect(h.acquireLock).not.toHaveBeenCalled();
+  });
+
+  it('a destination that fills up after the access check is caught under the lock', async () => {
+    // The access module answers on the disk it saw: `canRestorePlatformFile`
+    // said yes because the root had no `access.md` when it looked. Here it
+    // says yes and the file IS there — the state a racing writer leaves — and
+    // the move refuses rather than renaming over the rules it came to bring
+    // back. Both locks are held by then, so this is the last place the answer
+    // can change.
+    h.canRestorePlatformFile.mockResolvedValue(true);
+    await fs.mkdir(path.join(h.workspaceDir, KB), { recursive: true });
+    await fs.writeFile(path.join(h.workspaceDir, KB, 'access.md'), '---\nread: everyone\n---\n');
+
+    const res = await move(h, `${KB}/Misplaced/access.md`, `${KB}/access.md`);
+
+    expect(res.status).toBe(409);
+    expect(res.body.error).toBe('access.md is a platform file and stays in its folder.');
+    expect(h.moveEntry).not.toHaveBeenCalled();
+    // It got as far as the locks — that is the point of the second look.
+    expect(h.acquireLock).toHaveBeenCalled();
+  });
+
+  it('a restore must keep the name: a misplaced access.md may not arrive as something else', async () => {
+    h.canRestorePlatformFile.mockResolvedValue(true);
+    const res = await move(h, `${KB}/Misplaced/access.md`, `${KB}/rules.md`);
+    expect(res.status).toBe(409);
+    expect(res.body.error).toBe('access.md is a platform file and stays in its folder.');
+    expect(h.moveEntry).not.toHaveBeenCalled();
+  });
+
+  it("the root's own access.md is never a restore, however willing the access module is", async () => {
+    // Otherwise the rescue would describe the bug it repairs: "move the root's
+    // access.md into a folder that has none" is exactly how the root loses it.
+    h.canRestorePlatformFile.mockResolvedValue(true);
+    const res = await move(h, `${KB}/access.md`, `${KB}/Sales/access.md`);
+    expect(res.status).toBe(409);
+    expect(res.body.error).toBe('access.md is a platform file and stays in its folder.');
+    expect(h.moveEntry).not.toHaveBeenCalled();
+    expect(h.canRestorePlatformFile).not.toHaveBeenCalled();
+  });
+
+  it('an ordinary file is unaffected — renamed and moved, with no restore claim anywhere', async () => {
+    const renamed = await move(h, `${KB}/Sales/deal.md`, `${KB}/Sales/contract.md`);
+    expect(renamed.status).toBe(200);
+    const moved = await move(h, `${KB}/Sales/contract.md`, `${KB}/Legal/contract.md`);
+    expect(moved.status).toBe(200);
+    expect(h.moveEntry).toHaveBeenCalledTimes(2);
+    expect(h.canRestorePlatformFile).not.toHaveBeenCalled();
+    for (const call of h.acquireLock.mock.calls) {
+      expect((call[4] as { platformRestore?: unknown })?.platformRestore).toBeUndefined();
+    }
+  });
+
+  it('a nested roles.yaml or AGENTS.md is ordinary content and moves freely', async () => {
+    // They are read from the root and nowhere else, so a nested file of
+    // either name carries no platform meaning to protect.
+    expect((await move(h, `${KB}/Sales/roles.yaml`, `${KB}/Sales/old-roles.yaml`)).status).toBe(200);
+    expect((await move(h, `${KB}/Sales/AGENTS.md`, `${KB}/Legal/AGENTS.md`)).status).toBe(200);
+    expect(h.moveEntry).toHaveBeenCalledTimes(2);
+  });
+});

package/src/modules/workspace/__tests__/workspace.routes.read-gate.test.ts

@@ -2,6 +2,7 @@ import type { Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
@@ -95,6 +96,7 @@ async function makeHarness(opts: {
       KB,
       stubCreatorAccess,
       { isAdmin: async () => opts.isAdmin === true } as unknown as IAdminAccessService,
+      new NodeFs(),
     ),
   );
   const server = await new Promise<Server>((resolve) => {
@@ -134,13 +136,28 @@ describe('read-permission gates on human read routes', () => {
     expect(h.canRead).toHaveBeenCalledWith(WS, USER.email, 'Knowledge/Secret/x.md');
   });
 
-  it('GET /file: a non-KB path (reserved workspace file) is not read-gated', async () => {
+  it('GET /file: an unprefixed path is placed in the repository and gated THERE', async () => {
     h = await makeHarness();
-    // Outside `kbDirName` → carries no read rules → served without a canRead
-    // check (matches the agent tools and diff routes). Previously this 403'd
-    // because the full path was passed to default-deny canRead.
+    // No route path can be outside `kbDirName` any more: the normaliser places
+    // `reserved-config.json` at the repository root, and the read gate is asked
+    // about exactly the repo-relative path the read will use. Before this it was
+    // taken as a workspace file, carried no read rules, and was served ungated
+    // — the same reading that let a write land beside the checkout.
     const res = await get(`/file?path=${encodeURIComponent('reserved-config.json')}`);
     expect(res.status).toBe(200);
+    expect(h.canRead).toHaveBeenCalledWith(WS, USER.email, 'reserved-config.json');
+    // …and a denied one is refused on that same repo-relative name.
+    const denied = await get(`/file?path=${encodeURIComponent('Secret-config.json')}`);
+    expect(denied.status).toBe(403);
+    expect(h.canRead).toHaveBeenCalledWith(WS, USER.email, 'Secret-config.json');
+  });
+
+  it('GET /file: the clone folder itself carries no read rules', async () => {
+    h = await makeHarness();
+    // `toKbRelative` gives nothing for the folder itself, so there is no
+    // repo-relative path to resolve rules against — unchanged.
+    const res = await get(`/file?path=${encodeURIComponent(KB)}`);
+    expect(res.status).not.toBe(403);
     expect(h.canRead).not.toHaveBeenCalled();
   });
 
@@ -182,11 +199,10 @@ describe('read-permission gates on human read routes', () => {
 
   it('keeps the structural root folders visible even when nothing is readable', async () => {
     // A user with no read grants: the access batch denies everything. The
-    // structural top-level folders (KnowledgeBase, Data, Agents, Pipelines,
-    // Plugins) must still resolve readable (so the explorer renders its
-    // section view), while their contents stay gated. The retired Skills/
-    // and Tools/ roots get NO structural treatment — they are ordinary
-    // (denied) folders now.
+    // structural top-level folders (KnowledgeBase, Skills, Data, Agents,
+    // Pipelines, Plugins) must still resolve readable (so the explorer renders
+    // its section view), while their contents stay gated. The retired Tools/
+    // root gets NO structural treatment — it is an ordinary (denied) folder.
     h = await makeHarness({ allowFn: () => false });
     expect((await get('/files')).status).toBe(200);
     const filter = h.listFilesFilter();
@@ -208,8 +224,8 @@ describe('read-permission gates on human read routes', () => {
     expect(verdict.get(`${KB}/Agents`)).toBe(true);
     expect(verdict.get(`${KB}/Pipelines`)).toBe(true);
     expect(verdict.get(`${KB}/Plugins`)).toBe(true);
-    // Retired roots: no override, the deny-all batch verdict stands.
-    expect(verdict.get(`${KB}/Skills`)).toBe(false);
+    expect(verdict.get(`${KB}/Skills`)).toBe(true);
+    // Retired root: no override, the deny-all batch verdict stands.
     expect(verdict.get(`${KB}/Tools`)).toBe(false);
     // Their contents: still gated (the override matches only the exact folder).
     expect(verdict.get(`${KB}/KnowledgeBase/Open/a.md`)).toBe(false);
@@ -313,7 +329,9 @@ describe('.bevelignore is admin-only in the file tree', () => {
       `${KB}/.bevelignore`,
       `${KB}/Knowledge/Open/a.md`,
     ]);
-    expect(verdict.get(`${KB}/.bevelignore`)).toBe(false);
+    // Unlisted, not denied: hiding it withholds no content, so it never
+    // counts toward the tree's `withheld`.
+    expect(verdict.get(`${KB}/.bevelignore`)).toBe('unlisted');
     // Only that one file — the rest of the tree is untouched.
     expect(verdict.get(`${KB}/Knowledge/Open/a.md`)).toBe(true);
   });
@@ -326,7 +344,7 @@ describe('.bevelignore is admin-only in the file tree', () => {
   /** The stack is hierarchical — a nested one governs its own subtree. */
   it('hides a nested one too, not just the repo-root file', async () => {
     const verdict = await (await treeFilter(false))([`${KB}/KnowledgeBase/Product/.bevelignore`]);
-    expect(verdict.get(`${KB}/KnowledgeBase/Product/.bevelignore`)).toBe(false);
+    expect(verdict.get(`${KB}/KnowledgeBase/Product/.bevelignore`)).toBe('unlisted');
   });
 
   /** Basename match, not substring: a file merely NAMED after it stays visible. */

package/src/modules/workspace/__tests__/workspace.service.ensure-remotes-fetched.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { WorkspaceService } from '../workspace.service.js';
+import type { IGitRunner } from '../../../shared/git.contract.js';
+
+/**
+ * `ensureRemotesFetched` is one `git fetch --prune origin` for a whole clone,
+ * and it is now what a change-request LIST pays instead of one fetch per open
+ * request. Two properties matter to that caller, and they pull in opposite
+ * directions: it must not storm the remote, and it must not answer a read
+ * that KNOWS the remote just moved out of a 30s-old window — a request whose
+ * branch the clone has not fetched has no diff, which is a request missing
+ * from its own author's tree.
+ */
+describe('WorkspaceService.ensureRemotesFetched', () => {
+  let root: string;
+  let runs: string[][];
+  let runner: IGitRunner;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-ws-fetch-'));
+    // `.git` and not just the directory: `resolveWorkspaceDir` probes for it,
+    // and without it every first call falls through to the lazy-clone
+    // bootstrap before the fetch-cache logic under test even starts. These
+    // tests count fetches — they must count this method's, not a clone's.
+    await fs.mkdir(path.join(root, 'main', 'knowledge-base', '.git'), { recursive: true });
+    runs = [];
+    runner = {
+      defaultTimeoutMs: 1000,
+      run: vi.fn(async (_cwd: string, args: string[]) => {
+        runs.push(args);
+        return { stdout: '', stderr: '' };
+      }),
+    } as unknown as IGitRunner;
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true }).catch(() => {});
+  });
+
+  const service = () =>
+    new WorkspaceService(
+      root,
+      'https://example.test/kb.git',
+      'knowledge-base',
+      new NodeFs(),
+      'x-access-token',
+      runner,
+    );
+
+  const fetches = () => runs.filter((args) => args[0] === 'fetch');
+
+  it('caches a successful fetch, so a poll cannot storm the remote', async () => {
+    const svc = service();
+    await svc.ensureRemotesFetched('main');
+    await svc.ensureRemotesFetched('main');
+    await svc.ensureRemotesFetched('main');
+    expect(fetches()).toHaveLength(1);
+  });
+
+  it('force skips that window — an event-driven read is not a poll', async () => {
+    const svc = service();
+    await svc.ensureRemotesFetched('main');
+    await svc.ensureRemotesFetched('main', { force: true });
+    expect(fetches()).toHaveLength(2);
+  });
+
+  it('force still joins a fetch already in flight — that is the storm guard', async () => {
+    let hold: Promise<void> | null = null;
+    let release: () => void = () => {};
+    runner = {
+      defaultTimeoutMs: 1000,
+      run: vi.fn(async (_cwd: string, args: string[]) => {
+        runs.push(args);
+        if (hold) await hold;
+        return { stdout: '', stderr: '' };
+      }),
+    } as unknown as IGitRunner;
+    const svc = service();
+
+    // One call first, so the clone's directory is resolved and cached — which
+    // it is for every request after a process's first. The join under test is
+    // about the FETCH; a COLD workspace lookup is an async step of its own,
+    // long enough for one caller's whole fetch to finish inside the other's,
+    // and it would decide this test instead of the thing it is about.
+    await svc.ensureRemotesFetched('main');
+    const beforeTheRace = fetches().length;
+    hold = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+
+    // The two list endpoints the tree asks together, both forced.
+    const both = Promise.all([
+      svc.ensureRemotesFetched('main', { force: true }),
+      svc.ensureRemotesFetched('main', { force: true }),
+    ]);
+    // Held until both callers have reached the in-flight check: releasing on
+    // the tick they were started lets the first fetch settle, and be cleared,
+    // before the second one looks. A real fetch is a network round trip; this
+    // is what "already in flight" looks like.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    release();
+    await both;
+
+    expect(fetches().length - beforeTheRace).toBe(1);
+  });
+});

package/src/modules/workspace/__tests__/workspace.service.list-cloned.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { WorkspaceService } from '../workspace.service.js';
+
+/**
+ * `listClonedWorkspaces` is what the remote sync enumerates. It must read the
+ * DISK, not the in-memory bootstrap cache: clones survive a restart, and a
+ * hook that fires before anyone has opened a branch must still find them.
+ */
+describe('WorkspaceService.listClonedWorkspaces', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-ws-list-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function clone(dirName: string, withGit = true) {
+    const repo = path.join(root, dirName, 'knowledge-base');
+    await fs.mkdir(withGit ? path.join(repo, '.git') : repo, { recursive: true });
+  }
+
+  it('finds every finished clone on disk without any branch having been opened this process', async () => {
+    await clone('main');
+    await clone('ali%2Fnew-skill');
+    // Half-built: the directory exists but the clone never finished.
+    await clone('juan%2Fabandoned', false);
+    // Not one of ours: the name is not the encoding of any branch.
+    await clone('weird%zz');
+    // A stray file at the root is ignored.
+    await fs.writeFile(path.join(root, 'notes.txt'), 'x');
+
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', 'knowledge-base', new NodeFs());
+    const found = await svc.listClonedWorkspaces();
+    expect(found.sort((a, b) => a.branch.localeCompare(b.branch))).toEqual([
+      { id: 'ali%2Fnew-skill', branch: 'ali/new-skill' },
+      { id: 'main', branch: 'main' },
+    ]);
+  });
+
+  it('is empty when the workspaces root does not exist yet', async () => {
+    const svc = new WorkspaceService(path.join(root, 'missing'), 'https://example.test/kb.git', 'knowledge-base', new NodeFs());
+    expect(await svc.listClonedWorkspaces()).toEqual([]);
+  });
+});
+
+describe('WorkspaceService.listClonedWorkspaces — what is not a clone', () => {
+  let root: string;
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-ws-list-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('a directory whose name round-trips but is not a branch git accepts', async () => {
+    // `foo!`, `-leading-dash` and `a..b` survive encodeURIComponent unchanged, so
+    // only the validator can exclude them; `has space` does not round-trip and
+    // is excluded one step earlier. Both guards have to hold.
+    for (const name of ['main', 'foo!', '-leading-dash', 'a..b', 'has space']) {
+      await fs.mkdir(path.join(root, name, 'knowledge-base', '.git'), { recursive: true });
+    }
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', 'knowledge-base', new NodeFs());
+    expect(await svc.listClonedWorkspaces()).toEqual([{ id: 'main', branch: 'main' }]);
+  });
+
+  it('a branch whose bootstrap is in flight right now', async () => {
+    await fs.mkdir(path.join(root, 'main', 'knowledge-base', '.git'), { recursive: true });
+    await fs.mkdir(path.join(root, 'ali%2Fx', 'knowledge-base', '.git'), { recursive: true });
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', 'knowledge-base', new NodeFs());
+    // While a clone runs, `.git` exists but the tree is not checked out yet.
+    // The listing asks the public predicate, which is stubbed here rather than
+    // the tracker behind it — no public seam can hold a real clone open.
+    vi.spyOn(svc, 'isBootstrapInFlight').mockImplementation((branch) => branch === 'ali/x');
+    expect(await svc.listClonedWorkspaces()).toEqual([{ id: 'main', branch: 'main' }]);
+  });
+
+  it('a root that is a file counts as no root, not as a clone list', async () => {
+    // A FILE where the root should be: readdir fails with ENOTDIR on POSIX and
+    // ENOENT on Windows — both "no root", so an empty list. A permission
+    // failure is the case that must propagate, and there is no portable way
+    // to stage one in a temp dir; the code path is the same `throw err`.
+    const file = path.join(root, 'not-a-dir');
+    await fs.writeFile(file, 'x');
+    const svc = new WorkspaceService(file, 'https://example.test/kb.git', 'knowledge-base', new NodeFs());
+    expect(await svc.listClonedWorkspaces()).toEqual([]);
+  });
+});

package/src/modules/workspace/__tests__/workspace.service.missing-branch.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { isMissingRemoteBranchFailure } from '../../../shared/domain-errors.js';
+
+/**
+ * The one line that decides whether a failed bootstrap is "this branch does
+ * not exist" (410, the browser says so) or "something is wrong" (500). Git's
+ * two wordings for a missing ref are matched; an unreachable host or a
+ * refused credential must NOT be, or a deployment outage would read as
+ * "your branch is gone".
+ */
+describe('isMissingRemoteBranchFailure', () => {
+  it('recognises both of git’s wordings for a ref origin does not have', () => {
+    expect(
+      isMissingRemoteBranchFailure(
+        "Command failed: git clone -b sync-test/conflict-2 https://[REDACTED]@github.com/x/y.git /w\nfatal: Remote branch sync-test/conflict-2 not found in upstream origin",
+      ),
+    ).toBe(true);
+    expect(isMissingRemoteBranchFailure("fatal: couldn't find remote ref refs/heads/ali/x")).toBe(true);
+  });
+
+  it('does not mistake an unreachable host or a refused credential for a missing branch', () => {
+    expect(
+      isMissingRemoteBranchFailure("fatal: unable to access 'https://github.com/x/y.git/': Could not resolve host: github.com"),
+    ).toBe(false);
+    expect(isMissingRemoteBranchFailure('remote: Invalid username or password.\nfatal: Authentication failed')).toBe(false);
+    expect(isMissingRemoteBranchFailure('fatal: repository not found')).toBe(false);
+  });
+});