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

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

@@ -5,6 +5,7 @@ import path from 'node:path';
 import os from 'node:os';
 import express from 'express';
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
@@ -103,7 +104,7 @@ describe('GET /file/raw on a download-only path (real resolver)', () => {
         {} as unknown as IWorkflowService,
         {} as unknown as WorkflowEventBus,
         accessControl,
-        KB,
+        testKbContext({ kbDirName: KB }),
         stubCreatorAccess,
         { isAdmin: async () => false } as unknown as IAdminAccessService,
         new NodeFs(),

package/src/modules/workspace/__tests__/workspace.routes.download.test.ts

@@ -2,6 +2,7 @@ import { get as httpGet, type Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { PathTraversalError } from '../../../shared/domain-errors.js';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
@@ -129,7 +130,7 @@ async function makeHarness(opts: {
     workflowService,
     eventBus,
     accessControl,
-    KB,
+    testKbContext({ kbDirName: KB }),
     stubCreatorAccess,
     // Not exercised here — only `.bevelignore`'s tree visibility consults it.
     { isAdmin: async () => false } as unknown as IAdminAccessService,

package/src/modules/workspace/__tests__/workspace.routes.file-writes.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 { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { PathTraversalError } from '../../../shared/domain-errors.js';
 import { EntryExistsError } from '../workspace.service.js';
@@ -149,7 +150,7 @@ async function makeHarness(opts: { canRead?: boolean; skillSaveCheck?: SkillSave
       workflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       accessControl,
-      KB,
+      testKbContext({ kbDirName: KB }),
       stubCreatorAccess,
       { isAdmin: async () => true } as unknown as IAdminAccessService,
       new NodeFs(),

package/src/modules/workspace/__tests__/workspace.routes.folders.test.ts

@@ -5,6 +5,7 @@ import path from 'node:path';
 import os from 'node:os';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import type { FileTreeEntry, IWorkflowService } from '@bevel-software/platform-shared';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
@@ -55,7 +56,7 @@ async function makeHarness(): Promise<Harness> {
   const workspaceDir = path.join(root, workspaceId);
   // The inner `.git` lets the service accept the workspace without cloning.
   await fs.mkdir(path.join(workspaceDir, KB, '.git'), { recursive: true });
-  const workspaceService = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs());
+  const workspaceService = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs());
   await workspaceService.getWorkspacePath(workspaceId);
 
   const releaseLock = vi.fn<(...args: unknown[]) => Promise<never>>(async () => undefined as never);
@@ -85,7 +86,7 @@ async function makeHarness(): Promise<Harness> {
       workflowService,
       { emit } as unknown as WorkflowEventBus,
       allowAll,
-      KB,
+      testKbContext({ kbDirName: KB }),
       stubCreatorAccess,
       { isAdmin: async () => false } as unknown as IAdminAccessService,
       new NodeFs(),
@@ -334,7 +335,7 @@ describe('WorkspaceService.writeFolderPlaceholder', () => {
     const workspaceId = workspaceIdForBranch('placeholders');
     const kbDir = path.join(root, workspaceId, KB);
     await fs.mkdir(path.join(kbDir, '.git'), { recursive: true });
-    return { svc: new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs()), workspaceId, kbDir };
+    return { svc: new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs()), workspaceId, kbDir };
   }
 
   it('writes into an empty folder, and leaves a full or a vanished one alone', async () => {
@@ -377,7 +378,7 @@ describe('WorkspaceService.withFolderTurn', () => {
     root = await fs.mkdtemp(path.join(os.tmpdir(), 'folder-turn-'));
     const workspaceId = workspaceIdForBranch('turns');
     await fs.mkdir(path.join(root, workspaceId, KB, '.git'), { recursive: true });
-    const svc = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs());
+    const svc = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs());
 
     const events: string[] = [];
     let open!: () => void;

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

@@ -5,6 +5,7 @@ import path from 'node:path';
 import os from 'node:os';
 import express from 'express';
 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 type { IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
@@ -95,7 +96,7 @@ async function makeHarness(): Promise<Harness> {
     workflowService,
     eventBus,
     accessControl,
-    KB,
+    testKbContext({ kbDirName: KB }),
     creatorAccess,
     { isAdmin: async () => false } as unknown as IAdminAccessService,
     new NodeFs(),

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 { testKbContext } from '../../../__tests__/kb-context.js';
 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';
@@ -93,7 +94,7 @@ async function makeHarness(opts: {
       {} as unknown as IWorkflowService,
       {} as unknown as WorkflowEventBus,
       accessControl,
-      KB,
+      testKbContext({ kbDirName: KB }),
       stubCreatorAccess,
       { isAdmin: async () => opts.isAdmin === true } as unknown as IAdminAccessService,
       new NodeFs(),

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

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } 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';
@@ -44,9 +45,8 @@ describe('WorkspaceService.ensureRemotesFetched', () => {
     new WorkspaceService(
       root,
       'https://example.test/kb.git',
-      'knowledge-base',
+      testKbContext(),
       new NodeFs(),
-      'x-access-token',
       runner,
     );
 

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();