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

package/src/modules/access/__tests__/access.routes.revoke.test.ts

@@ -10,6 +10,7 @@ import type { WorkflowService } from '../../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP-level contract tests for the revoke route's CLASSIFICATION + MODE logic —
@@ -133,7 +134,7 @@ async function makeHarness(opts: {
     (req as unknown as { userId: string }).userId = USER.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, KB));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));

package/src/modules/access/__tests__/access.routes.unknown-email.test.ts

@@ -11,6 +11,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createAccessRoutes } from '../access.routes.js';
 import type { Database } from '../../database/connection.js';
 import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * A grant to an email with NO ACCOUNT says so, and stays allowed.
@@ -107,7 +108,7 @@ async function makeHarness(opts: {
       workflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       opts.db ?? usersDbDouble(opts.accounts ?? []),
-      KB,
+      testKbContext({ kbDirName: KB }),
     ),
   );
 

package/src/modules/access/__tests__/change-read-gate.test.ts

@@ -8,6 +8,8 @@ import { AccessControlService } from '../access-control.service.js';
 import { ChangeReadGate, isNewTopLevelFolderPath } from '../change-read-gate.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
 import { SYNCED_GROUPS_YAML } from '../../access-model/group-files.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB = 'knowledge-base';
 const WS = 'ws-gate';
@@ -56,7 +58,7 @@ describe('ChangeReadGate', () => {
     await write(repo, 'roles.yaml', ROLES_YAML);
     const ws = stubWorkspaceService(workspaceDir);
     access = new AccessControlService(ws, KB, new NodeFs());
-    gate = new ChangeReadGate(ws, access, KB, new NodeFs());
+    gate = new ChangeReadGate(ws, access, testKbContext({ kbDirName: KB }), new NodeFs());
   });
 
   afterEach(async () => {
@@ -255,18 +257,18 @@ describe('isNewTopLevelFolderPath', () => {
   const exists = async (p: string) => onDisk.has(p);
 
   it('is true for a path inside a folder directly under a creatable root that is not on disk', async () => {
-    expect(await isNewTopLevelFolderPath('KnowledgeBase/New/a.md', 'file', exists)).toBe(true);
-    expect(await isNewTopLevelFolderPath('Skills/fresh/SKILL.md', 'file', exists)).toBe(true);
-    expect(await isNewTopLevelFolderPath('Plugins/team/deep/er/x', 'file', exists)).toBe(true);
-    expect(await isNewTopLevelFolderPath('KnowledgeBase/New', 'dir', exists)).toBe(true);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/New/a.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(true);
+    expect(await isNewTopLevelFolderPath('Skills/fresh/SKILL.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(true);
+    expect(await isNewTopLevelFolderPath('Plugins/team/deep/er/x', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(true);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/New', 'dir', exists, DEFAULT_KB_LAYOUT)).toBe(true);
   });
 
   it('is false when the top-level folder exists, for a loose file at the root, and outside the three roots', async () => {
-    expect(await isNewTopLevelFolderPath('KnowledgeBase/Existing/a.md', 'file', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('Skills/known', 'dir', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('KnowledgeBase/loose.md', 'file', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('KnowledgeBase', 'dir', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('Data/New/a.md', 'file', exists)).toBe(false);
-    expect(await isNewTopLevelFolderPath('roles.yaml', 'file', exists)).toBe(false);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/Existing/a.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('Skills/known', 'dir', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase/loose.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('KnowledgeBase', 'dir', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('Data/New/a.md', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(false);
+    expect(await isNewTopLevelFolderPath('roles.yaml', 'file', exists, DEFAULT_KB_LAYOUT)).toBe(false);
   });
 });

package/src/modules/access/__tests__/creator-access.test.ts

@@ -7,6 +7,7 @@ import os from 'node:os';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../access-control.service.js';
 import { CreatorAccessService } from '../creator-access.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB = 'knowledge-base';
 const WS = 'ws-creator';
@@ -61,7 +62,7 @@ describe('CreatorAccessService.planForCreate', () => {
     await fs.mkdir(path.join(repo, 'Plugins'), { recursive: true });
     await write(repo, 'roles.yaml', ROLES_YAML);
     const ws = stubWorkspaceService(workspaceDir);
-    svc = new CreatorAccessService(ws, new AccessControlService(ws, KB, new NodeFs()), KB, new NodeFs());
+    svc = new CreatorAccessService(ws, new AccessControlService(ws, KB, new NodeFs()), testKbContext({ kbDirName: KB }), new NodeFs());
   });
 
   afterEach(async () => {
@@ -175,7 +176,7 @@ describe('CreatorAccessService.planForCreate', () => {
       },
     });
     const ws = stubWorkspaceService(path.join(root, WS));
-    const withFailingDisk = new CreatorAccessService(ws, new AccessControlService(ws, KB, real), KB, failing);
+    const withFailingDisk = new CreatorAccessService(ws, new AccessControlService(ws, KB, real), testKbContext({ kbDirName: KB }), failing);
     expect(await withFailingDisk.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/Projects`, 'dir')).toBeNull();
     expect(await withFailingDisk.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/Projects/a.md`, 'file')).toBeNull();
     // The same creation on a disk that answers is planned, so it was the

package/src/modules/access/__tests__/roles.routes.test.ts

@@ -15,6 +15,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { FileTreeEntry } from '@bevel-software/platform-shared';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP-level contract tests for the /api/access/roles routes: the admin gate
@@ -137,7 +138,7 @@ async function makeHarness(opts: { isAdmin?: boolean } = {}): Promise<{ server:
     (req as unknown as { userId: string }).userId = ADMIN.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, KB));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));

package/src/modules/access/access-control.service.ts

@@ -22,10 +22,14 @@ import type {
   ProspectiveHolders,
   ResolvedPrincipal,
 } from './access-control.interface.js';
-import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, isPersonalPluginDir,
+import {
+  DEFAULT_KB_LAYOUT,
+  PLUGIN_MANIFEST_FILE,
+  isPersonalPluginDir,
   pluginIdentityOf,
   platformRestoreDestination,
 } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import { AccessConfigError, AccessUnreadableError } from '../access-model/access-errors.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { synthesizePluginPrincipals } from '../access-model/plugin-principals.js';
@@ -291,13 +295,14 @@ interface AccessScope {
  */
 function accessFileListener(
   repoDir: string,
+  pluginsDir: string,
   out: Map<string, AccessFile>,
   pluginDirs: Map<string, string>,
 ): WalkListener {
   return {
     async onFile(dir, name) {
       const rel = dir ? `${dir}/${name}` : name;
-      if (name === PLUGIN_MANIFEST_FILE && dir.startsWith(`${PLUGINS_DIR}/`)) {
+      if (name === PLUGIN_MANIFEST_FILE && dir.startsWith(`${pluginsDir}/`)) {
         const text = await fs.readFile(path.join(repoDir, rel), 'utf-8').catch(() => null);
         pluginDirs.set(dir, pluginIdentityOf(parseManifestText(text), path.posix.basename(dir)));
         return;
@@ -1301,6 +1306,14 @@ export class AccessControlService implements IAccessControl {
      * many fixtures construct this service directly.
      */
     private readonly gitRunner: IGitRunner = new NodeGitRunner(),
+    /**
+     * The knowledge base's layout — which folder is the plugins root, what the
+     * platform files are called. Read per use, never captured: the roots are
+     * renameable from the setup screen. Defaulted for the same reason as
+     * `deploymentOwners`: the fixtures that construct this service directly
+     * run on the default layout.
+     */
+    private readonly kb: Pick<KbContext, 'layout'> = { layout: DEFAULT_KB_LAYOUT },
   ) {
     this.deploymentOwners = new Set(
       deploymentOwners.filter(Boolean).map((e) => canonicalEmail(e)),
@@ -1806,7 +1819,7 @@ export class AccessControlService implements IAccessControl {
         principal.kind === 'plugin' &&
         principal.pluginName &&
         principal.pluginDir &&
-        !isPersonalPluginDir(principal.pluginDir)
+        !isPersonalPluginDir(principal.pluginDir, this.kb.layout)
       ) {
         plugins.set(principal.pluginName, principal.pluginDir);
       }
@@ -1982,7 +1995,7 @@ export class AccessControlService implements IAccessControl {
     userEmail: string,
     destinationRelativePath: string,
   ): Promise<boolean> {
-    const target = platformRestoreDestination(destinationRelativePath);
+    const target = platformRestoreDestination(destinationRelativePath, this.kb.layout);
     if (target === null) return false;
     const email = canonicalEmail(userEmail);
 
@@ -2143,7 +2156,7 @@ export class AccessControlService implements IAccessControl {
     // / `roles.yaml` because `hasPermissionResolved` admin-rescues those
     // paths, so the bad config remains fixable from inside the app.
     const pluginDirs = new Map<string, string>();
-    await this.disk.walkKb(repoDir, [accessFileListener(repoDir, accessFiles, pluginDirs)]);
+    await this.disk.walkKb(repoDir, [accessFileListener(repoDir, this.kb.layout.pluginsDir, accessFiles, pluginDirs)]);
 
     // Plugin principals (`plugin/<Name>/<verb>`), derived from each plugin
     // folder's own access.md — a plugin being a folder with a manifest, at
@@ -2320,11 +2333,12 @@ export class AccessControlService implements IAccessControl {
       const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '--name-only', ref]);
       const out: string[] = [];
       const pluginDirs: string[] = [];
+      const { pluginsDir } = this.kb.layout;
       for (const line of stdout.split('\n')) {
         const p = line.trim();
         if (!p) continue;
         if (p === 'access.md' || p.endsWith('/access.md')) out.push(p);
-        else if (p.startsWith(`${PLUGINS_DIR}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
+        else if (p.startsWith(`${pluginsDir}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
           pluginDirs.push(p.slice(0, -(PLUGIN_MANIFEST_FILE.length + 1)));
         }
       }

package/src/modules/access/access.routes.ts

@@ -9,8 +9,6 @@ const grantLog = logger('access.grant');
 const revokeLog = logger('access.revoke');
 import type { AuthUser } from '@bevel-software/platform-shared';
 import {
-  isProtectedBranch,
-  DEFAULT_BRANCH,
   pluginManifestName,
   FOLDER_GOVERNS_ACCESS_KIND,
 } from '@bevel-software/platform-shared';
@@ -20,7 +18,8 @@ import type {
   GrantSources,
 } from './access-control.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { branchForWorkspaceId, workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
+import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { AuthService } from '../auth/auth.service.js';
 import type { WorkflowService } from '../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
@@ -89,18 +88,19 @@ export function createAccessRoutes(
   workflowService: WorkflowService,
   eventBus: WorkflowEventBus,
   db: Database,
-  kbDirName: string,
+  kb: KbContext,
   /** This deployment's configured admins — the break-glass recovery roster. */
   recoveryAdmins: readonly string[] = [],
 ): express.Router {
   const router = express.Router({ mergeParams: true });
+  const { kbDirName } = kb;
   const mutation = new AccessMutationService(workspaceService, accessControl, kbDirName);
   const rolesAdmin = new RolesAdminService(
     workspaceService,
     workflowService,
     accessControl,
     kbDirName,
-    () => DEFAULT_BRANCH,
+    () => kb.defaultBranch,
     eventBus,
     recoveryAdmins,
   );
@@ -118,10 +118,8 @@ export function createAccessRoutes(
     groups: string[];
     plugins: { name: string; folder: string }[];
   }> => {
-    await workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
-    const { roles, groups, plugins } = await accessControl.kbPrincipals(
-      workspaceIdForBranch(DEFAULT_BRANCH),
-    );
+    await workspaceService.getOrCreateForBranch(kb.defaultBranch);
+    const { roles, groups, plugins } = await accessControl.kbPrincipals(kb.defaultWorkspaceId());
     // `plugins` is defensive: an older resolver double may omit it.
     return { roles, groups, plugins: plugins ?? [] };
   };
@@ -139,7 +137,7 @@ export function createAccessRoutes(
   ): Promise<{ name: string; folder: string }[]> => {
     if (plugins.length === 0) return [];
     const verdicts = await accessControl.canReadBatch(
-      workspaceIdForBranch(DEFAULT_BRANCH),
+      kb.defaultWorkspaceId(),
       email,
       plugins.map((p) => `${p.folder}/access.md`),
     );
@@ -711,7 +709,6 @@ export function createAccessRoutes(
     // resolves to false and is rejected above. Nothing extra needed here — but
     // keep the branch check explicit so the intent is legible.
     void branch;
-    void isProtectedBranch;
   }
 
   /**
@@ -1211,8 +1208,8 @@ export function createAccessRoutes(
 
   /** Fail-fast admin gate for the roles routes. Throws AccessDeniedError. */
   async function assertRolesAdmin(userEmail: string): Promise<void> {
-    await workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
-    await assertCanMutate(workspaceIdForBranch(DEFAULT_BRANCH), DEFAULT_BRANCH, userEmail, 'roles.yaml');
+    await workspaceService.getOrCreateForBranch(kb.defaultBranch);
+    await assertCanMutate(kb.defaultWorkspaceId(), kb.defaultBranch, userEmail, 'roles.yaml');
   }
 
   router.get('/access/roles', async (req, res) => {

package/src/modules/access/change-read-gate.ts

@@ -15,8 +15,9 @@
  */
 
 import path from 'node:path';
-import { creatableRootDirNames } from '@bevel-software/platform-shared';
+import { creatableRootDirNames, type KbLayout } from '@bevel-software/platform-shared';
 import type { IFsProbe } from '../../shared/fs.contract.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { IAccessControl } from './access-control.interface.js';
 import { AccessConfigError, AccessDeniedError } from '../access-model/access-errors.js';
@@ -39,10 +40,11 @@ export async function isNewTopLevelFolderPath(
   kbRel: string,
   kind: ChangeTargetKind,
   exists: (kbRel: string) => Promise<boolean>,
+  layout: KbLayout,
 ): Promise<boolean> {
   const segments = kbRel.split('/');
   const root = segments[0];
-  if (root === undefined || !creatableRootDirNames().has(root)) return false;
+  if (root === undefined || !creatableRootDirNames(layout).has(root)) return false;
   if (segments.length < (kind === 'dir' ? 2 : 3)) return false;
   return !(await exists(`${root}/${segments[1]}`));
 }
@@ -51,10 +53,14 @@ export class ChangeReadGate implements IChangeReadGate {
   constructor(
     private readonly workspaceService: Pick<WorkspaceService, 'getWorkspacePath'>,
     private readonly accessControl: Pick<IAccessControl, 'canRead' | 'holdsAdminRootWrite'>,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     private readonly disk: IFsProbe,
   ) {}
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   async judge(
     workspaceId: string,
     userEmail: string,
@@ -88,7 +94,7 @@ export class ChangeReadGate implements IChangeReadGate {
           return { allowed: true, via: 'admin-rescue' };
         }
       }
-      if (await isNewTopLevelFolderPath(rel, kind, exists)) {
+      if (await isNewTopLevelFolderPath(rel, kind, exists, this.kb.layout)) {
         return { allowed: true, via: 'new-top-level-folder' };
       }
       if (await this.accessControl.canRead(workspaceId, userEmail, rel)) {

package/src/modules/access/creator-access.ts

@@ -33,6 +33,7 @@ import { printable } from '../../shared/printable.js';
 const log = logger('creator-access');
 
 import type { IFsProbe } from '../../shared/fs.contract.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { IAccessControl } from './access-control.interface.js';
 import { spliceGrant, type Principal } from '../access-model/access-splice.js';
@@ -49,10 +50,14 @@ export class CreatorAccessService implements ICreatorAccess {
   constructor(
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     private readonly disk: IFsProbe,
   ) {}
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   /**
    * Whether something is at `abs`. Links are NOT followed: a link, dangling
    * or not, is something there — never a "new" folder to seed a grant under,
@@ -106,7 +111,7 @@ export class CreatorAccessService implements ICreatorAccess {
     const segments = rel.split('/');
     if (kind === 'file') segments.pop();
     const root = segments[0];
-    if (root === undefined || segments.length < 2 || !creatableRootDirNames().has(root)) return null;
+    if (root === undefined || segments.length < 2 || !creatableRootDirNames(this.kb.layout).has(root)) return null;
     const top = `${root}/${segments[1]}`;
     try {
       if (await this.exists(path.join(repoDir, top))) return null;

package/src/modules/agent-instructions/__tests__/read-preamble.test.ts

@@ -6,6 +6,7 @@ import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { readAgentPreamble, type PreambleWorkspace } from '../read-preamble.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /** The one disk, as production wires it. */
 const disk = new NodeFs();
@@ -42,7 +43,7 @@ describe('readAgentPreamble', () => {
   it('reads the default branch copy at <kbDirName>/mcp-description.md, creating the workspace first', async () => {
     await fs.writeFile(path.join(wsDir, KB, 'mcp-description.md'), 'Acme.\n', 'utf8');
     const ws = workspace();
-    expect(await readAgentPreamble(ws, KB, disk)).toBe('Acme.\n');
+    expect(await readAgentPreamble(ws, testKbContext({ kbDirName: KB }), disk)).toBe('Acme.\n');
     expect(ws.getOrCreateForBranch).toHaveBeenCalledWith(DEFAULT_BRANCH);
     expect(ws.getWorkspacePath).toHaveBeenCalledWith(workspaceIdForBranch(DEFAULT_BRANCH));
   });
@@ -50,19 +51,19 @@ describe('readAgentPreamble', () => {
   it("spells the path with the deployment's own KB dir name", async () => {
     await fs.mkdir(path.join(wsDir, 'kb'), { recursive: true });
     await fs.writeFile(path.join(wsDir, 'kb', 'mcp-description.md'), 'Renamed root.', 'utf8');
-    expect(await readAgentPreamble(workspace(), 'kb', disk)).toBe('Renamed root.');
-    expect(await readAgentPreamble(workspace(), KB, disk)).toBeNull(); // the default-named root has none
+    expect(await readAgentPreamble(workspace(), testKbContext({ kbDirName: 'kb' }), disk)).toBe('Renamed root.');
+    expect(await readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).toBeNull(); // the default-named root has none
   });
 
   it('a file that is not there is an absence, not a fault', async () => {
-    expect(await readAgentPreamble(workspace(), KB, disk)).toBeNull();
+    expect(await readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).toBeNull();
   });
 
   it('refuses a symlink: the secret it points at is never read, and it is not an absence either', async () => {
     const secret = path.join(root, 'secret.txt');
     await fs.writeFile(secret, 'DATABASE_URL=postgres://…', 'utf8');
     await fs.symlink(secret, path.join(wsDir, KB, 'mcp-description.md'));
-    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toThrow(/symlink, not a regular file/);
+    await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toThrow(/symlink, not a regular file/);
   });
 
   it('refuses a repository folder reached through a link — the whole path must be its own, not only the file', async () => {
@@ -72,7 +73,7 @@ describe('readAgentPreamble', () => {
     await fs.writeFile(path.join(elsewhere, 'mcp-description.md'), 'Not the repository.', 'utf8');
     await fs.rm(path.join(wsDir, KB), { recursive: true });
     await fs.symlink(elsewhere, path.join(wsDir, KB), process.platform === 'win32' ? 'junction' : 'dir');
-    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toThrow(/through a symlink/);
+    await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toThrow(/through a symlink/);
   });
 
   it('reads through a link ABOVE the workspace — a mounted volume is the operator\'s, not the repository\'s', async () => {
@@ -81,12 +82,12 @@ describe('readAgentPreamble', () => {
     await fs.symlink(wsDir, mount, process.platform === 'win32' ? 'junction' : 'dir');
     const ws = workspace();
     ws.getWorkspacePath.mockImplementation(async () => mount);
-    expect(await readAgentPreamble(ws, KB, disk)).toBe('Acme.\n');
+    expect(await readAgentPreamble(ws, testKbContext({ kbDirName: KB }), disk)).toBe('Acme.\n');
   });
 
   it('refuses a directory squatting the name', async () => {
     await fs.mkdir(path.join(wsDir, KB, 'mcp-description.md'));
-    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toThrow(/directory, not a regular file/);
+    await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toThrow(/directory, not a regular file/);
   });
 
   it('a KB directory that is a regular file is an ABSENT preamble, the shared rule for "nothing can be there"', async () => {
@@ -96,7 +97,7 @@ describe('readAgentPreamble', () => {
     // squatted this way is the startup phase's to refuse, loudly, once.
     await fs.rm(path.join(wsDir, KB), { recursive: true });
     await fs.writeFile(path.join(wsDir, KB), 'not a directory', 'utf8');
-    expect(await readAgentPreamble(workspace(), KB, disk)).toBeNull();
+    expect(await readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).toBeNull();
   });
 
   it('an lstat that fails for any reason but absence throws, never an empty preamble', async () => {
@@ -110,7 +111,7 @@ describe('readAgentPreamble', () => {
         ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
         : (real as (p: string) => Promise<unknown>).call(fs, p)) as never);
     try {
-      await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toMatchObject({ code: 'EACCES' });
+      await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toMatchObject({ code: 'EACCES' });
     } finally {
       spy.mockRestore();
     }
@@ -121,7 +122,7 @@ describe('readAgentPreamble', () => {
     const file = path.join(wsDir, KB, 'mcp-description.md');
     await fs.writeFile(file, 'Acme.', 'utf8');
     await fs.chmod(file, 0o000); // the lstat still passes; the open is what fails
-    await expect(readAgentPreamble(workspace(), KB, disk)).rejects.toMatchObject({ code: 'EACCES' });
+    await expect(readAgentPreamble(workspace(), testKbContext({ kbDirName: KB }), disk)).rejects.toMatchObject({ code: 'EACCES' });
   });
 
   it('a workspace that cannot be located throws too', async () => {
@@ -130,6 +131,6 @@ describe('readAgentPreamble', () => {
     ws.getWorkspacePath.mockImplementation(async () => {
       throw eio;
     });
-    await expect(readAgentPreamble(ws, KB, disk)).rejects.toBe(eio);
+    await expect(readAgentPreamble(ws, testKbContext({ kbDirName: KB }), disk)).rejects.toBe(eio);
   });
 });

package/src/modules/agent-instructions/read-preamble.ts

@@ -1,7 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import { isAbsence, type IFsProbe } from '../../shared/fs.contract.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { PREAMBLE_FILE } from './compose.js';
@@ -43,11 +42,17 @@ export type PreambleWorkspace = Pick<WorkspaceService, 'getOrCreateForBranch' |
  */
 export async function readAgentPreamble(
   workspace: PreambleWorkspace,
-  kbDirName: string,
+  kb: Pick<KbContext, 'kbDirName' | 'defaultBranch' | 'defaultWorkspaceId'>,
   disk: IFsProbe,
 ): Promise<string | null> {
-  await workspace.getOrCreateForBranch(DEFAULT_BRANCH);
-  const wsDir = await workspace.getWorkspacePath(workspaceIdForBranch(DEFAULT_BRANCH));
+  const { kbDirName, defaultBranch } = kb;
+  const notRegular = (kind: string): Error =>
+    new Error(
+      `${PREAMBLE_FILE} on branch "${defaultBranch}" is a ${kind}, not a regular file at its own place; ` +
+        'refusing to read it. Replace it with a plain markdown file in the repository folder.',
+    );
+  await workspace.getOrCreateForBranch(defaultBranch);
+  const wsDir = await workspace.getWorkspacePath(kb.defaultWorkspaceId());
   const abs = path.join(wsDir, kbDirName, PREAMBLE_FILE);
 
   const found = await disk.lstatOrNull(abs);
@@ -79,10 +84,3 @@ export async function readAgentPreamble(
     await handle.close();
   }
 }
-
-function notRegular(kind: string): Error {
-  return new Error(
-    `${PREAMBLE_FILE} on branch "${DEFAULT_BRANCH}" is a ${kind}, not a regular file at its own place; ` +
-      'refusing to read it. Replace it with a plain markdown file in the repository folder.',
-  );
-}