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

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

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -36,7 +37,7 @@ describe('WorkspaceService.listClonedWorkspaces', () => {
     // 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 svc = new WorkspaceService(root, 'https://example.test/kb.git', testKbContext(), 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' },
@@ -45,7 +46,7 @@ describe('WorkspaceService.listClonedWorkspaces', () => {
   });
 
   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());
+    const svc = new WorkspaceService(path.join(root, 'missing'), 'https://example.test/kb.git', testKbContext(), new NodeFs());
     expect(await svc.listClonedWorkspaces()).toEqual([]);
   });
 });
@@ -66,14 +67,14 @@ describe('WorkspaceService.listClonedWorkspaces — what is not a clone', () =>
     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());
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', testKbContext(), 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());
+    const svc = new WorkspaceService(root, 'https://example.test/kb.git', testKbContext(), 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.
@@ -88,7 +89,7 @@ describe('WorkspaceService.listClonedWorkspaces — what is not a clone', () =>
     // 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());
+    const svc = new WorkspaceService(file, 'https://example.test/kb.git', testKbContext(), new NodeFs());
     expect(await svc.listClonedWorkspaces()).toEqual([]);
   });
 });

package/src/modules/workspace/__tests__/workspace.service.move-never-overwrites.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -57,7 +58,7 @@ describe('WorkspaceService.moveEntry — a name that is taken is refused, never
     svc = new WorkspaceService(
       root,
       'https://github.com/Bevel-Software/knowledge-base.git',
-      KB,
+      testKbContext({ kbDirName: KB }),
       new NodeFs(),
     );
   });

package/src/modules/workspace/__tests__/workspace.service.read-filter.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -47,7 +48,7 @@ describe('WorkspaceService.listFiles — read filter', () => {
     // readers, say), and its files are readable.
     await mkFile(workspaceDir, 'Scopes/Deploy/SKILL.md');
     await mkFile(workspaceDir, 'Scopes/other.md');
-    svc = new WorkspaceService(root, 'https://example.invalid/repo.git', KB, new NodeFs());
+    svc = new WorkspaceService(root, 'https://example.invalid/repo.git', testKbContext({ kbDirName: KB }), new NodeFs());
     await svc.getWorkspacePath(workspaceId);
   });
 

package/src/modules/workspace/__tests__/workspace.service.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -65,7 +66,7 @@ describe('WorkspaceService — branch-keyed identity', () => {
   });
 
   it('a malformed workspace id (bad percent-escape) rejects as a 400 BranchNameError, not a 500', async () => {
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     // `%zz` fails decodeURIComponent, falls back to itself, and `%` never
     // passes the branch-name rules — the cold-path bootstrap must surface
     // that as the status-carrying domain error, not a wrapped plain Error.
@@ -77,7 +78,7 @@ describe('WorkspaceService — branch-keyed identity', () => {
 
   it('returns workspace info derived from the branch — no .workspace.json on disk', async () => {
     const { workspaceId, workspaceDir } = await seedBranchWorkspace(root, 'target-company-state');
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     const info = await svc.getOrCreateForBranch('target-company-state');
 
     expect(info.id).toBe(workspaceId);
@@ -90,7 +91,7 @@ describe('WorkspaceService — branch-keyed identity', () => {
   it('two branches map to distinct directories', async () => {
     const a = await seedBranchWorkspace(root, 'target-company-state');
     const b = await seedBranchWorkspace(root, 'alice/feature');
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
 
     const infoA = await svc.getOrCreateForBranch('target-company-state');
     const infoB = await svc.getOrCreateForBranch('alice/feature');
@@ -113,7 +114,7 @@ describe('WorkspaceService — branch-keyed identity', () => {
     const squatter = path.join(workspaceDir, 'knowledge-base');
     await fs.writeFile(squatter, 'not a clone', 'utf8');
 
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     await expect(svc.getOrCreateForBranch('target-company-state')).rejects.toThrow(
       /"knowledge-base" in this workspace exists but is not a directory/,
     );
@@ -121,21 +122,21 @@ describe('WorkspaceService — branch-keyed identity', () => {
   });
 
   it('rejects invalid branch names before touching disk', async () => {
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     await expect(svc.getOrCreateForBranch('')).rejects.toThrow();
     await expect(svc.getOrCreateForBranch('-bad-leading-dash')).rejects.toThrow();
   });
 
   it('getOrCreateForUser falls back to target-company-state when no branch is supplied', async () => {
     await seedBranchWorkspace(root, 'target-company-state');
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     const info = await svc.getOrCreateForUser({ id: 'u', email: 'a@b.c', name: 'A' });
     expect(info.id).toBe(workspaceIdForBranch('target-company-state'));
   });
 
   it('getOrCreateForUser respects an explicit branch override', async () => {
     await seedBranchWorkspace(root, 'alice/feature');
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     const info = await svc.getOrCreateForUser({ id: 'u', email: 'a@b.c', name: 'A' }, 'alice/feature');
     expect(info.id).toBe(workspaceIdForBranch('alice/feature'));
   });
@@ -155,7 +156,7 @@ describe('WorkspaceService.createDirectory', () => {
     workspaceDir = seeded.workspaceDir;
     repoDir = path.join(workspaceDir, 'knowledge-base');
     workspaceId = seeded.workspaceId;
-    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     // Hydrate the in-memory map so subsequent ops resolve fast.
     await svc.getWorkspacePath(workspaceId);
   });
@@ -266,7 +267,7 @@ describe('WorkspaceService.writeFile — expectedContent', () => {
     const seeded = await seedBranchWorkspace(root, 'target-company-state');
     workspaceDir = seeded.workspaceDir;
     workspaceId = seeded.workspaceId;
-    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
   });
 
   afterEach(async () => {
@@ -407,7 +408,7 @@ describe('WorkspaceService.withPathTurn', () => {
     const seeded = await seedBranchWorkspace(root, 'target-company-state');
     workspaceDir = seeded.workspaceDir;
     workspaceId = seeded.workspaceId;
-    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
   });
 
   afterEach(async () => {
@@ -420,51 +421,68 @@ describe('WorkspaceService.withPathTurn', () => {
     await Promise.resolve();
   };
 
-  it('runs one turn at a time, so two bodies never interleave', async () => {
-    const order: string[] = [];
+  /**
+   * A turn whose body records when it runs — and, for the FIRST one, tells
+   * the test when it HOLDS the turn, so the next can be issued behind it.
+   *
+   * What the queue guarantees is one body at a time per file. It does NOT
+   * guarantee that turns issued together chain in the order they were
+   * issued: before a turn joins the queue its spelling is resolved and judged
+   * against the git folder on disk, and those probes finish in whatever order
+   * the disk answers, so a later call can join first. Asserting on names in a
+   * fixed order therefore needs the earlier turn to be HELD before the later
+   * one is issued; interleaving is then the only thing that could reorder.
+   */
+  const recorder = (order: string[]) => {
+    let holding: (() => void) | undefined;
+    const held = new Promise<void>((resolve) => { holding = resolve; });
     const body = (name: string) => async (): Promise<void> => {
       order.push(`${name}:enter`);
+      holding?.();
       await yieldTwice();
       order.push(`${name}:exit`);
     };
+    return { body, held };
+  };
+
+  /** Each name's exit follows its own enter at once: no body ran inside another. */
+  const expectNoInterleaving = (order: string[], names: string[]): void => {
+    for (const name of names) {
+      const enter = order.indexOf(`${name}:enter`);
+      expect(enter).toBeGreaterThanOrEqual(0);
+      expect(order[enter + 1]).toBe(`${name}:exit`);
+    }
+  };
 
-    // Warm the workspace lookup first, for the reason the next test gives:
-    // a COLD lookup resolves its callers in disk order rather than call
-    // order, so `b` can reach the queue first and this assertion — which
-    // names `a` as the one that goes first — fails for a scheduling reason
-    // rather than an interleaving one.
-    await svc.withPathTurn(workspaceId, 'knowledge-base/mcp-description.md', async () => undefined);
+  it('runs one turn at a time, so two bodies never interleave', async () => {
+    const order: string[] = [];
+    const { body, held } = recorder(order);
 
-    await Promise.all([
-      svc.withPathTurn(workspaceId, 'knowledge-base/mcp-description.md', body('a')),
-      svc.withPathTurn(workspaceId, 'knowledge-base/mcp-description.md', body('b')),
-    ]);
+    const a = svc.withPathTurn(workspaceId, 'knowledge-base/mcp-description.md', body('a'));
+    await held;
+    const b = svc.withPathTurn(workspaceId, 'knowledge-base/mcp-description.md', body('b'));
+    await Promise.all([a, b]);
 
     expect(order).toEqual(['a:enter', 'a:exit', 'b:enter', 'b:exit']);
   });
 
   it('treats two spellings of one file as one queue', async () => {
     const order: string[] = [];
-    const body = (name: string) => async (): Promise<void> => {
-      order.push(`${name}:enter`);
-      await yieldTwice();
-      order.push(`${name}:exit`);
-    };
-
-    // Warm the workspace lookup first: a turn chains onto the queue only after
-    // it, and a COLD lookup resolves its three callers in disk order rather
-    // than call order — the queue is one either way, but this asserts FIFO.
-    await svc.withPathTurn(workspaceId, 'knowledge-base/mcp-description.md', async () => undefined);
+    const { body, held } = recorder(order);
 
+    const plain = svc.withPathTurn(workspaceId, 'knowledge-base/mcp-description.md', body('plain'));
+    await held;
+    // Issued together: they may join in either order, but each waits for
+    // `plain` and for each other, because all three name one file.
     await Promise.all([
-      svc.withPathTurn(workspaceId, 'knowledge-base/mcp-description.md', body('plain')),
+      plain,
       svc.withPathTurn(workspaceId, './knowledge-base/mcp-description.md', body('dotted')),
       svc.withPathTurn(workspaceId, 'knowledge-base//mcp-description.md', body('doubled')),
     ]);
 
-    expect(order).toEqual([
-      'plain:enter', 'plain:exit', 'dotted:enter', 'dotted:exit', 'doubled:enter', 'doubled:exit',
-    ]);
+    expect(order.slice(0, 2)).toEqual(['plain:enter', 'plain:exit']);
+    expect(order).toHaveLength(6);
+    expectNoInterleaving(order, ['plain', 'dotted', 'doubled']);
   });
 
   it('lets another file run while one path is held: a turn is per file', async () => {
@@ -506,10 +524,16 @@ describe('WorkspaceService.withPathTurn', () => {
         svc.writeFile(workspaceId, rel, 'From B.', { expectedContent: '' }),
       ]),
     );
+    const [a] = results;
     expect(results.filter((r) => r.status === 'fulfilled')).toHaveLength(1);
     const refused = results.find((r) => r.status === 'rejected') as PromiseRejectedResult;
     expect(refused.reason).toMatchObject({ status: 409 });
-    expect(await fs.readFile(path.join(workspaceDir, rel), 'utf-8')).toBe('From A.');
+    // Which of the two goes first is not promised (each resolves its path
+    // before it chains onto the held turn's tail); what is, is that the file
+    // holds the winner's text whole and the loser was refused.
+    expect(await fs.readFile(path.join(workspaceDir, rel), 'utf-8')).toBe(
+      a.status === 'fulfilled' ? 'From A.' : 'From B.',
+    );
   });
 
   it('updates the diff baseline inside the turn, in the order the mutations landed', async () => {
@@ -612,7 +636,7 @@ describe('WorkspaceService.assertContentMatches', () => {
     const seeded = await seedBranchWorkspace(root, 'target-company-state');
     workspaceDir = seeded.workspaceDir;
     workspaceId = seeded.workspaceId;
-    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
   });
 
   afterEach(async () => {
@@ -657,7 +681,7 @@ describe('WorkspaceService.createFolderZip', () => {
     workspaceDir = seeded.workspaceDir;
     repoDir = path.join(workspaceDir, 'knowledge-base');
     workspaceId = seeded.workspaceId;
-    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     await svc.getWorkspacePath(workspaceId);
   });
 
@@ -813,7 +837,7 @@ describe('WorkspaceService — clone bootstrap & sibling reference', () => {
   });
 
   it('clones a branch on first bootstrap and checks out the right ref', async () => {
-    const svc = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs());
     const info = await svc.getOrCreateForBranch('target-company-state');
 
     const repo = path.join(info.absolutePath, 'knowledge-base');
@@ -822,7 +846,7 @@ describe('WorkspaceService — clone bootstrap & sibling reference', () => {
   });
 
   it('uses an existing sibling clone as a --reference and stays dissociated', async () => {
-    const svc = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs());
     // First branch: plain clone — becomes the sibling for the next bootstrap.
     await svc.getOrCreateForBranch('target-company-state');
     // Second branch: should borrow the first clone's objects, then dissociate.
@@ -850,7 +874,7 @@ describe('WorkspaceService — clone bootstrap & sibling reference', () => {
   // post-merge pull of a target branch. Every clone this service hands out must
   // therefore track exactly one upstream ref through exactly one refspec.
   it('stamps a single fetch refspec and upstream ref on a fresh clone', async () => {
-    const svc = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs());
     const info = await svc.getOrCreateForBranch('target-company-state');
     const repo = path.join(info.absolutePath, 'knowledge-base');
 
@@ -874,7 +898,7 @@ describe('WorkspaceService — clone bootstrap & sibling reference', () => {
     await runGit(repo, ['config', '--add', 'remote.origin.fetch', '+refs/heads/*:refs/remotes/origin/*']);
     await runGit(repo, ['config', '--add', 'branch.alice/draft.merge', 'refs/heads/target-company-state']);
 
-    const svc = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs());
     await svc.getOrCreateForBranch('alice/draft');
 
     expect(await gitOut(repo, ['config', '--get-all', 'remote.origin.fetch']))
@@ -886,7 +910,7 @@ describe('WorkspaceService — clone bootstrap & sibling reference', () => {
   });
 
   it('notifies the cloned-workspace listener with the workspace id after a clone', async () => {
-    const svc = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs());
     const cloned: string[] = [];
     svc.setWorkspaceClonedListener((id) => cloned.push(id));
 
@@ -914,7 +938,7 @@ describe('WorkspaceService — symbolic links', () => {
     const seeded = await seedBranchWorkspace(root, 'main');
     workspaceDir = seeded.workspaceDir;
     workspaceId = seeded.workspaceId;
-    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
   });
 
   afterEach(async () => {
@@ -999,7 +1023,7 @@ describe('WorkspaceService — symbolic links', () => {
     // A mounted-volume shape: the whole workspaces root reached through a link.
     const mount = path.join(root, 'mount');
     await fs.symlink(root, mount, linkType);
-    const viaMount = new WorkspaceService(mount, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    const viaMount = new WorkspaceService(mount, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     expect(await viaMount.readFile(workspaceId, rel)).toBe('Hello.');
     await viaMount.writeFile(workspaceId, rel, 'Hello again.');
     expect(await fs.readFile(path.join(workspaceDir, rel), 'utf-8')).toBe('Hello again.');
@@ -1032,7 +1056,7 @@ describe('WorkspaceService.sweepOrphanedWorkspaces', () => {
 
   it('removes the clone of a branch that is not in the known set', async () => {
     const { workspaceId, workspaceDir } = await seedBranchWorkspace(root, 'target-company-state');
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     await svc.getOrCreateForBranch('target-company-state');
 
     // The branch vanishes from the known set; the sweep reclaims its clone.
@@ -1053,7 +1077,7 @@ describe('WorkspaceService.readAllKbFiles', () => {
     const seeded = await seedBranchWorkspace(root, 'target-company-state');
     repoRoot = path.join(seeded.workspaceDir, 'knowledge-base');
     workspaceId = seeded.workspaceId;
-    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     await svc.getWorkspacePath(workspaceId);
   });
 
@@ -1112,7 +1136,7 @@ describe('WorkspaceService.unzipFile — ontology-session write guard', () => {
     workspaceDir = seeded.workspaceDir;
     repoDir = path.join(workspaceDir, 'knowledge-base');
     workspaceId = seeded.workspaceId;
-    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base', new NodeFs());
+    svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', testKbContext(), new NodeFs());
     await svc.getWorkspacePath(workspaceId);
   });
 
@@ -1255,7 +1279,7 @@ describe('WorkspaceService — every operation resolves inside the repository',
     workspaceDir = seeded.workspaceDir;
     repoDir = path.join(workspaceDir, 'knowledge-base');
     workspaceId = seeded.workspaceId;
-    svc = new WorkspaceService(root, 'https://example.invalid/kb.git', 'knowledge-base', new NodeFs());
+    svc = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext(), new NodeFs());
     await svc.getWorkspacePath(workspaceId);
   });
 
@@ -1294,11 +1318,21 @@ describe('WorkspaceService — every operation resolves inside the repository',
   });
 
   it('takes its path and folder turns on the repository path, so two spellings are one queue', async () => {
+    // The second spelling is issued only once the first HOLDS its turn. What
+    // is asserted is the queue — the second waits for the first to finish —
+    // not the order two calls enter it: before the queue each spelling is
+    // judged against the git folder on disk, and those probes take as long as
+    // the spelling makes them, so two calls issued together can chain in
+    // either order (the FIFO case is pinned above, on warmed equal spellings).
     const order: string[] = [];
+    let holding!: () => void;
+    const held = new Promise<void>((r) => { holding = r; });
     const slow = svc.withPathTurn(workspaceId, 'contended.md', async () => {
+      holding();
       await new Promise((r) => setTimeout(r, 20));
       order.push('first');
     });
+    await held;
     const fast = svc.withPathTurn(workspaceId, 'knowledge-base/contended.md', async () => {
       order.push('second');
     });

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

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
@@ -63,7 +64,7 @@ describe('WorkspaceService — a branch origin does not have', () => {
   const deleteOnHost = (branch: string): Promise<void> => runGit(upstream, ['branch', '-D', branch]);
 
   const service = (repoUrl = upstream): WorkspaceService =>
-    new WorkspaceService(workspacesRoot, repoUrl, 'knowledge-base', new NodeFs());
+    new WorkspaceService(workspacesRoot, repoUrl, testKbContext(), new NodeFs());
 
   it('a name nothing has ever cloned or listed is a 404 that names only the branch', async () => {
     const svc = service();

package/src/modules/workspace/__tests__/workspace.tools.agents-file.test.ts

@@ -2,7 +2,8 @@ import express from 'express';
 import { afterEach, describe, expect, it } from 'vitest';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
@@ -24,6 +25,8 @@ import { registerWorkspaceTools } from '../workspace.tools.js';
  * for it.
  */
 const KB_DIR = 'knowledge-base';
+/** The context the tools read; a case applies a deployment's own names to it. */
+const kb = testKbContext({ kbDirName: KB_DIR });
 
 /** Every workspace tool's description, keyed by name, under the layout in effect. */
 async function descriptions(registry: ToolRegistry = new ToolRegistry()): Promise<Map<string, string>> {
@@ -37,11 +40,11 @@ async function descriptions(registry: ToolRegistry = new ToolRegistry()): Promis
     new SpillStore(join(tmpdir(), 'bevel-test-spills')),
     new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')),
     {} as unknown as IAccessControl,
-    KB_DIR,
+    kb,
     {
       service: {} as never,
       enabled: false,
-      kbDirName: KB_DIR,
+      kb,
       recoveryBotEmail: 'recovery-bot@bevel.local',
       hooks: new WorkflowHooks(),
     },
@@ -57,7 +60,7 @@ async function listed(registry: ToolRegistry): Promise<Map<string, string>> {
   return new Map(tools.map((t) => [t.name, t.description ?? '']));
 }
 
-afterEach(() => configureKbLayout({ ...DEFAULT_KB_LAYOUT }));
+afterEach(() => kb.applyLayout({ ...DEFAULT_KB_LAYOUT }));
 
 describe('the conventions note every workspace tool carries', () => {
   it('names AGENTS.md, and CLAUDE.md beside it, under the default name', async () => {
@@ -71,7 +74,7 @@ describe('the conventions note every workspace tool carries', () => {
   });
 
   it('names the configured file first and the organisation\'s own AGENTS.md second', async () => {
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     const byName = await descriptions();
     const note = byName.get('grep') ?? '';
     expect(note).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');
@@ -83,7 +86,7 @@ describe('the conventions note every workspace tool carries', () => {
   });
 
   it('describes the platform files under the configured name, and no longer under AGENTS.md', async () => {
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     const byName = await descriptions();
     const stat = byName.get('file_stat') ?? '';
     expect(stat).toContain('`access.md`, `roles.yaml`, `.bevelignore`, `HEXIS.md`');
@@ -117,7 +120,7 @@ describe('the conventions note every workspace tool carries', () => {
     const atMount = await descriptions(registry);
     expect(atMount.get('grep')).toContain('read `AGENTS.md` at the KB root');
 
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
 
     const now = await listed(registry);
     expect(now.get('grep')).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');

package/src/modules/workspace/__tests__/workspace.tools.branch-errors.test.ts

@@ -6,6 +6,7 @@ import { join } from 'node:path';
 import { promisify } from 'node:util';
 import express from 'express';
 import { afterEach, describe, expect, it } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
@@ -109,7 +110,7 @@ describe('workspace tools — a branch that cannot be opened', () => {
     workspaces = new WorkspaceService(
       workspacesRoot,
       opts.repoUrl === 'unreachable' ? join(root, 'no-such-repo.git') : upstream,
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
       new NodeFs(),
     );
 
@@ -138,11 +139,11 @@ describe('workspace tools — a branch that cannot be opened', () => {
       new SpillStore(spillRoot),
       new DocExtractService(docCacheDir),
       allowAll,
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
       {
         service: {} as never,
         enabled: false,
-        kbDirName: KB_DIR,
+        kb: testKbContext({ kbDirName: KB_DIR }),
         recoveryBotEmail: 'recovery-bot@bevel.local',
         hooks: new WorkflowHooks(),
       },

package/src/modules/workspace/__tests__/workspace.tools.test.ts

@@ -7,6 +7,7 @@ import { promisify } from 'node:util';
 import AdmZip from 'adm-zip';
 import express from 'express';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { LocalFilesystem } from '@mastra/core/workspace';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
@@ -218,10 +219,10 @@ async function start(
   const app = express();
   app.use(express.json());
   const router = express.Router();
-  registerWorkspaceTools(registry, router, fakeAuth, toolHandler, new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(docCacheDir), access, KB_DIR, {
+  registerWorkspaceTools(registry, router, fakeAuth, toolHandler, new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(docCacheDir), access, testKbContext({ kbDirName: KB_DIR }), {
     service: {} as never,
     enabled: false, // these tests predate and don't exercise the ontology boundary
-    kbDirName: KB_DIR,
+    kb: testKbContext({ kbDirName: KB_DIR }),
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
   }, writePolicy, {} as never /* sessionSink — start_session not exercised here */);
@@ -1831,8 +1832,8 @@ describe('start_session', () => {
     const router = express.Router();
     registerWorkspaceTools(
       registry, router, auth, toolHandler,
-      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, KB_DIR,
-      { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       sink ?? fakeSessionSink,
     );
@@ -1956,8 +1957,8 @@ describe('start_session', () => {
     const noopAuth: express.RequestHandler = (_req, _res, next) => next();
     registerWorkspaceTools(
       registry, router, noopAuth, (() => () => {}) as never,
-      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, KB_DIR,
-      { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       {} as never,
     );
@@ -1998,8 +1999,8 @@ describe('branch is a required parameter in the tool contract', () => {
       new SpillStore(join(tmpdir(), 'bevel-test-spills')),
       new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')),
       allowAll,
-      KB_DIR,
-      { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      testKbContext({ kbDirName: KB_DIR }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       {} as never,
     );

package/src/modules/workspace/__tests__/write-denial.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { writeDenial } from '../write-denial.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
 import type { ChangeReadVerdict, IChangeReadGate } from '../../access-model/change-gate.js';
@@ -34,7 +35,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
       eligibleUsers: [],
       targetKind: 'dir',
     });
-    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    const out = await writeDenial(err, INPUT, noAccess, testKbContext({ kbDirName: KB }), gate);
     expect(judge).toHaveBeenCalledWith(
       'target-company-state',
       'alice@example.com',
@@ -48,7 +49,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
   it('a refusal that says nothing about its kind is judged as a file', async () => {
     const { gate, judge } = gateThat({ allowed: false, unreadable: 'KnowledgeBase' });
     const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/loose.md`, eligibleRoles: [], eligibleUsers: [] });
-    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    const out = await writeDenial(err, INPUT, noAccess, testKbContext({ kbDirName: KB }), gate);
     expect(judge).toHaveBeenCalledWith(expect.any(String), 'alice@example.com', `${KB}/KnowledgeBase/loose.md`, 'file');
     expect(out.details).toMatchObject({
       kind: 'write-denied',
@@ -60,7 +61,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
   it('without a gate the read verdict alone decides, as before', async () => {
     const accessControl = { canRead: vi.fn(async () => true) } as unknown as IAccessControl;
     const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/Sales/deal.md`, eligibleRoles: [], eligibleUsers: [] });
-    const out = await writeDenial(err, INPUT, accessControl, KB);
+    const out = await writeDenial(err, INPUT, accessControl, testKbContext({ kbDirName: KB }));
     expect(accessControl.canRead).toHaveBeenCalledWith('target-company-state', 'alice@example.com', 'KnowledgeBase/Sales/deal.md');
     expect(out.details).toMatchObject({ kind: 'write-denied', canPropose: true });
   });
@@ -68,7 +69,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
   it('a gate that cannot answer refuses to offer the route', async () => {
     const gate: IChangeReadGate = { judge: vi.fn(async () => { throw new Error('git down'); }), assertMayChange: vi.fn() };
     const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/Sales/deal.md`, eligibleRoles: [], eligibleUsers: [] });
-    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    const out = await writeDenial(err, INPUT, noAccess, testKbContext({ kbDirName: KB }), gate);
     expect(out.details).toMatchObject({ canPropose: false });
     expect(out.details?.cannotProposeReason).toContain('could not be determined');
   });