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

package/src/modules/settings/__tests__/setup.routes.layout-phase.test.ts

@@ -7,7 +7,7 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 import express from 'express';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
 import { KbStartupRunner } from '../../workspace/startup/kb-startup-runner.js';
@@ -71,7 +71,6 @@ beforeEach(async () => {
 afterEach(async () => {
   server?.close();
   server = null;
-  configureKbLayout({ ...DEFAULT_KB_LAYOUT });
   for (const k of KB_ENV) {
     const original = savedEnv[k];
     if (original === undefined) delete process.env[k];
@@ -102,17 +101,20 @@ function boot() {
     delete: () => ({ where: () => Promise.resolve() }),
   } as unknown as Database;
   const settings = new DeploymentSettingsService(db, ENC_KEY);
+  // ONE context for the step and the routes, as the composition root builds
+  // it: the completing save applies the admin's names to it, and the step
+  // reads them from it when the phase runs.
+  const kb = testKbContext();
   const runner = new KbStartupRunner({
     gitRunner: new NodeGitRunner(),
     kbRepoUrl: () => upstream,
-    gitUsername: () => 'x-access-token',
     workspacesRoot: path.join(root, 'workspaces'),
     kbDirName: 'knowledge-base',
     templateDir: defaultKbTemplateDir(),
     defaultBranch: () => BRANCH,
     protectedBranches: () => [BRANCH],
     seedAdminEmails: ['admin@example.com'],
-    steps: [new TemplateFilesStep(new NodeFs())],
+    steps: [new TemplateFilesStep(new NodeFs(), kb)],
     buildSeedTree: async () => [],
   });
   const app = express();
@@ -128,6 +130,7 @@ function boot() {
       settings,
       { isAdmin: async () => true } as IAdminAccessService,
       runner,
+      kb,
       undefined,
       // The save now proves the connection first; the remote here is local, so
       // the stand-in answers for the host the stored address names.

package/src/modules/settings/__tests__/setup.routes.oidc.test.ts

@@ -9,6 +9,7 @@ import { OidcAuthProvider, oidcSettingsFrom } from '../../auth/oidc-auth-provide
 import type { AuthService } from '../../auth/auth.service.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const ENC_KEY = 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=';
 const ISSUER = 'https://login.example.com/tenant/v2.0';
@@ -118,6 +119,7 @@ function listen(opts: {
       settings,
       { isAdmin: async () => opts.isAdmin ?? true } as IAdminAccessService,
       { runAll: async () => {} },
+      testKbContext(),
       undefined,
       // No repository in these suites, so the connection check is never reached.
       async () => {

package/src/modules/settings/__tests__/setup.routes.sync-status.test.ts

@@ -7,6 +7,7 @@ import { createSetupRoutes, type LastSyncStatus } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import type { Database } from '../../database/connection.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The remote-sync facts on `GET /setup/status`: the address a hook calls and
@@ -41,6 +42,7 @@ function listen(isAdmin: boolean, last: LastSyncStatus | null) {
       settings,
       { isAdmin: async () => isAdmin } as IAdminAccessService,
       { runAll: async () => {} },
+      testKbContext(),
       { url: 'https://hexis.example.test/api/sync', lastSync: () => last },
     ),
   );

package/src/modules/settings/__tests__/setup.routes.test.ts

@@ -1,34 +1,10 @@
 import type { Server as HttpServer } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import {
-  DEFAULT_KB_LAYOUT,
-  branchModelFromEnv,
-  configureBranchModel,
-  configureKbLayout,
-  currentKbLayout,
-  type KbLayout,
-} from '@bevel-software/platform-shared';
-
-/**
- * test-setup configures the branch model from the environment, and nothing
- * unconfigures it; a test that needs the first-run "no branch model yet" state
- * says so here. Everything else is the real module.
- */
-const branchModel = vi.hoisted(() => ({ pretendUnconfigured: false }));
-vi.mock('@bevel-software/platform-shared', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('@bevel-software/platform-shared')>();
-  return {
-    ...actual,
-    isBranchModelConfigured: () => !branchModel.pretendUnconfigured && actual.isBranchModelConfigured(),
-    // Applying a model configures it, as the real module does.
-    configureBranchModel: (model: Parameters<typeof actual.configureBranchModel>[0]) => {
-      actual.configureBranchModel(model);
-      branchModel.pretendUnconfigured = false;
-    },
-  };
-});
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { KbLayout } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import type { KbContext } from '../../../shared/kb-context.js';
 import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
 import type { Database } from '../../database/connection.js';
@@ -98,6 +74,12 @@ function listen(
   runAll: () => Promise<void> = async () => {},
   checkConnection?: (connection: RepositoryConnection) => Promise<ConnectionCheck>,
   listFolders?: (listing: RootFolderListing) => Promise<string[] | null>,
+  /**
+   * The running graph's knowledge-base context, which the completing save
+   * applies the admin's names to. The default is a configured deployment; a
+   * suite that needs the first-run "no branch model yet" state passes its own.
+   */
+  kb: KbContext = testKbContext(),
 ) {
   const db = {
     select: () => ({ from: () => Promise.resolve([]) }),
@@ -122,6 +104,7 @@ function listen(
       // Default no-op: most suites never complete setup, so the runner is
       // never reached. The completion-transition suite passes its own spy.
       { runAll },
+      kb,
       undefined,
       checkConnection,
       listFolders,
@@ -129,7 +112,7 @@ function listen(
   );
   server = app.listen(0);
   const { port } = server.address() as AddressInfo;
-  return { base: `http://127.0.0.1:${port}`, settings };
+  return { base: `http://127.0.0.1:${port}`, settings, kb };
 }
 
 const post = (base: string, path: string, body: unknown) =>
@@ -576,13 +559,13 @@ describe('POST /setup/settings — the completion transition and the KB startup
  */
 describe('POST /setup/settings — the folder names on the completing save', () => {
   const completing = { kbRepoUrl: 'https://example.com/acme/kb.git', gitToken: 'ghp_x' };
-  afterEach(() => configureKbLayout({ ...DEFAULT_KB_LAYOUT }));
 
   it('applies them before the phase runs, and asks for no restart over them', async () => {
     const seenByPhase: KbLayout[] = [];
+    const kb = testKbContext();
     const { base } = listen(true, async () => {
-      seenByPhase.push(currentKbLayout());
-    }, connectedCheck().check);
+      seenByPhase.push(kb.layout);
+    }, connectedCheck().check, undefined, kb);
     const res = await post(base, '/api/setup/settings', {
       settings: { ...completing, knowledgeBaseDir: 'Docs', skillsDir: 'skills' },
     });
@@ -592,35 +575,36 @@ describe('POST /setup/settings — the folder names on the completing save', ()
     expect(body.restartRequired).toBe(false);
     const applied = { knowledgeBaseDir: 'Docs', skillsDir: 'skills', pluginsDir: 'Plugins', agentsFile: 'AGENTS.md' };
     expect(seenByPhase).toEqual([applied]);
-    expect(currentKbLayout()).toEqual(applied);
+    expect(kb.layout).toEqual(applied);
   });
 
   it('applies names stored by an earlier, incomplete save', async () => {
     const seenByPhase: KbLayout[] = [];
+    const kb = testKbContext();
     const { base } = listen(true, async () => {
-      seenByPhase.push(currentKbLayout());
-    }, connectedCheck().check);
+      seenByPhase.push(kb.layout);
+    }, connectedCheck().check, undefined, kb);
     await post(base, '/api/setup/settings', { settings: { pluginsDir: 'plugins' } });
-    expect(currentKbLayout().pluginsDir).toBe('Plugins');
+    expect(kb.layout.pluginsDir).toBe('Plugins');
     await post(base, '/api/setup/settings', { settings: completing });
     expect(seenByPhase[0]?.pluginsDir).toBe('plugins');
   });
 
   it('leaves them restart-to-apply once setup is complete', async () => {
-    const { base } = listen(true, undefined, connectedCheck().check);
+    const { base, kb } = listen(true, undefined, connectedCheck().check);
     await post(base, '/api/setup/settings', { settings: completing });
     const res = await post(base, '/api/setup/settings', { settings: { pluginsDir: 'plugins' } });
     expect(res.status).toBe(200);
     expect((await res.json()).restartRequired).toBe(true);
-    expect(currentKbLayout().pluginsDir).toBe('Plugins');
+    expect(kb.layout.pluginsDir).toBe('Plugins');
   });
 
   it('does not replace a layout the process already runs', async () => {
-    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    const kb = testKbContext({ layout: { knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' } });
     const seenByPhase: KbLayout[] = [];
     const { base } = listen(true, async () => {
-      seenByPhase.push(currentKbLayout());
-    }, connectedCheck().check);
+      seenByPhase.push(kb.layout);
+    }, connectedCheck().check, undefined, kb);
     const res = await post(base, '/api/setup/settings', {
       settings: { ...completing, skillsDir: 'capabilities' },
     });
@@ -634,10 +618,11 @@ describe('POST /setup/settings — the folder names on the completing save', ()
     try {
       const seenByPhase: KbLayout[] = [];
       let fail = true;
+      const kb = testKbContext();
       const { base } = listen(true, async () => {
-        seenByPhase.push(currentKbLayout());
+        seenByPhase.push(kb.layout);
         if (fail) throw new Error('remote said no');
-      }, connectedCheck().check);
+      }, connectedCheck().check, undefined, kb);
       const first = await post(base, '/api/setup/settings', {
         settings: { ...completing, skillsDir: 'skills' },
       });
@@ -650,7 +635,7 @@ describe('POST /setup/settings — the folder names on the completing save', ()
       expect(body.complete).toBe(true);
       expect(body.restartRequired).toBe(false);
       expect(seenByPhase.map((l) => l.skillsDir)).toEqual(['skills', 'capabilities']);
-      expect(currentKbLayout().skillsDir).toBe('capabilities');
+      expect(kb.layout.skillsDir).toBe('capabilities');
     } finally {
       console.error = consoleError;
     }
@@ -671,16 +656,14 @@ describe('POST /setup/settings — the folder names on the completing save', ()
         if (value === undefined) delete process.env[key];
         else process.env[key] = value;
       }
-      // Whatever the test applied, the rest of the worker runs on the pinned model.
-      configureBranchModel(branchModelFromEnv());
     }
   }
 
   it('asks for no restart over a branch model the completing save also applied', () =>
     withoutBranchEnv(async () => {
-    branchModel.pretendUnconfigured = true;
-    try {
-      const { base } = listen(true, undefined, connectedCheck().check);
+      // A fresh deployment: no branch model yet, so the save applies the one it carries.
+      const fresh = testKbContext({ branchModel: null });
+      const { base, kb } = listen(true, undefined, connectedCheck().check, undefined, fresh);
       const res = await post(base, '/api/setup/settings', {
         settings: {
           ...completing,
@@ -693,9 +676,7 @@ describe('POST /setup/settings — the folder names on the completing save', ()
       const body = await res.json();
       expect(body.complete).toBe(true);
       expect(body.restartRequired).toBe(false);
-    } finally {
-      branchModel.pretendUnconfigured = false;
-    }
+      expect(kb.defaultBranch).toBe('production');
     }));
 
   it('still asks for a restart over a branch change once a branch model is in effect', () =>

package/src/modules/settings/deployment-settings.service.ts

@@ -181,7 +181,9 @@ export const CORE_SETTINGS: SettingDef[] = [
      */
     key: 'agentsFile',
     section: 'knowledge-base',
-    validate: (v) => validateAgentsFileName(v),
+    // Judged against the default roots here; the quartet check in `plan`
+    // judges it against the roots the same save puts in effect.
+    validate: (v) => validateAgentsFileName(v, DEFAULT_KB_LAYOUT),
     restartToApply: true,
     unsetMeans: DEFAULT_KB_LAYOUT.agentsFile,
   },
@@ -422,11 +424,23 @@ export class DeploymentSettingsService {
   private stored = new Map<string, string>();
   private readonly crypto: TokenCrypto | null;
 
+  /**
+   * The environment the env-first layer reads. The process's own for a
+   * single-tenant deployment; a host serving several knowledge bases hands
+   * each graph one built from its tenant record, so a variable set on the
+   * host process can never leak into every tenant, and a record's values
+   * behave exactly as environment-pinned ones do (they win over the setup
+   * screen and the screen shows them as such).
+   */
+  private readonly env: NodeJS.ProcessEnv;
+
   constructor(
     private readonly db: Database,
     private readonly secretsEncKey: string,
     defs: SettingDef[] = CORE_SETTINGS,
+    options: { env?: NodeJS.ProcessEnv } = {},
   ) {
+    this.env = options.env ?? process.env;
     for (const def of defs) this.defs.set(def.key, def);
     // No key configured means secrets cannot be stored — surfaced when someone
     // tries, rather than pretended away by writing plaintext.
@@ -470,7 +484,7 @@ export class DeploymentSettingsService {
   resolve(key: string): string {
     const def = this.defs.get(key);
     if (!def) return '';
-    const fromEnv = def.envVar ? (process.env[def.envVar] ?? '').trim() : '';
+    const fromEnv = def.envVar ? (this.env[def.envVar] ?? '').trim() : '';
     if (fromEnv) return fromEnv;
     return (this.stored.get(key) ?? '').trim();
   }
@@ -521,7 +535,7 @@ export class DeploymentSettingsService {
    */
   async importLegacyLayoutEnv(): Promise<void> {
     for (const [key, envVar] of Object.entries(LEGACY_LAYOUT_ENV_VARS)) {
-      const fromEnv = (process.env[envVar] ?? '').trim();
+      const fromEnv = (this.env[envVar] ?? '').trim();
       if (!fromEnv) continue;
       const saved = (this.stored.get(key) ?? '').trim();
       if (saved) {
@@ -559,7 +573,7 @@ export class DeploymentSettingsService {
     // A setting with no variable can never read `env`, whatever the process
     // environment happens to hold — which is what makes the layout fields
     // editable in the app on a deployment that still sets the old variables.
-    if (def.envVar && (process.env[def.envVar] ?? '').trim()) return 'env';
+    if (def.envVar && (this.env[def.envVar] ?? '').trim()) return 'env';
     return (this.stored.get(key) ?? '').trim() ? 'stored' : 'unset';
   }
 
@@ -629,10 +643,9 @@ export class DeploymentSettingsService {
       this.stored.set(key, value);
     }
 
-    // The git token is consumed through the environment (the credential helper
-    // reads `$GITHUB_TOKEN` at call time, so it never appears in argv). Putting
-    // it there is what makes a token saved here work without a restart.
-    this.syncGitTokenEnv();
+    // A token saved here is in effect at once: the git runner's credentials
+    // read `resolve('gitToken')` on every call, so nothing is published to
+    // the process environment and no restart is needed.
     return { restartRequired: restartKeys.length > 0, restartKeys };
   }
 
@@ -777,18 +790,6 @@ export class DeploymentSettingsService {
     }
   }
 
-  /**
-   * Publish the resolved git token as `GITHUB_TOKEN`, the name the credential
-   * helper and every redaction path already read. Only when the environment did
-   * not supply one — otherwise this would overwrite the operator's value with
-   * a stored fallback, inverting the precedence everything else here obeys.
-   */
-  syncGitTokenEnv(): void {
-    if (this.sourceOf('gitToken') !== 'stored') return;
-    const token = this.resolve('gitToken');
-    if (token) process.env.GITHUB_TOKEN = token;
-  }
-
   /** The single sign-on values in effect, issuer normalized the way the provider uses it. */
   resolveOidcCredentials(): OidcCredentials {
     return {

package/src/modules/settings/setup.routes.ts

@@ -23,13 +23,11 @@ import {
   type RepositoryConnection,
 } from './connection-check.js';
 import {
-  configureBranchModel,
-  configureKbLayout,
-  isBranchModelConfigured,
   isDefaultKbLayout,
   validateBranchModel,
   validateKbLayout,
 } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import { failureOf, type GitFailure } from '../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { listRootFolders, pickListingBranch } from './git-root-folders.js';
@@ -105,6 +103,12 @@ export function createSetupRoutes(
     /** That failure classified, for the setup screen; absent, the message is read instead. */
     lastFailureKind?(): GitFailure | null;
   },
+  /**
+   * The knowledge base's context as the running graph holds it: the save
+   * that completes setup applies the branch model and the layout to it, so
+   * every service reads the admin's answer without a restart.
+   */
+  kb: KbContext,
   /**
    * The remote-sync facts the Deployment page shows beside the sync secret:
    * the address a webhook or pipeline must call, and what the last call did.
@@ -180,7 +184,7 @@ export function createSetupRoutes(
   };
   /** The app-gate answer: settings complete AND the KB phase settled clean, whoever ran it. */
   const kbReady = () =>
-    isComplete(settings) && kbInit === null && kbInitInFlight === null && bootFailure() === null;
+    isComplete(settings, kb) && kbInit === null && kbInitInFlight === null && bootFailure() === null;
 
   const requireAdmin: express.RequestHandler = async (req, res, next) => {
     if (!(await adminAccess.isAdmin(req.userEmail))) {
@@ -215,7 +219,7 @@ export function createSetupRoutes(
     }
     res.json({
       complete: kbReady(),
-      awaitingRestart: awaitingRestart(settings),
+      awaitingRestart: awaitingRestart(settings, kb),
       isAdmin: true,
       settings: settings.describe(),
       oidcVerification: await settings.oidcVerification(),
@@ -261,7 +265,7 @@ export function createSetupRoutes(
       // save that flips it false→true — whichever field arrives last — is the
       // one that must run the KB startup phase, regardless of which save
       // configured the branch model.
-      const wasComplete = isComplete(settings);
+      const wasComplete = isComplete(settings, kb);
       if (!(await connectionHoldsFor(entries, wasComplete, res))) return;
       const oidc = await signInHoldsFor(entries, res);
       if (!oidc) return;
@@ -292,13 +296,13 @@ export function createSetupRoutes(
        * capturing it at construction, which is what makes applying it here
        * enough.
        */
-      if (!isBranchModelConfigured()) {
+      if (!kb.isBranchModelConfigured()) {
         const model = {
           defaultBranch: settings.resolve('defaultBranch'),
           protectedBranches: settings.resolve('protectedBranches'),
         };
         if (!validateBranchModel(model)) {
-          configureBranchModel(model);
+          kb.applyBranchModel(model);
           branchModelApplied = true;
         }
       }
@@ -316,7 +320,7 @@ export function createSetupRoutes(
        * on a re-save of a complete, healthy setup: with the gate open,
        * sessions may be live and that is no longer a quiet moment.
        */
-      if ((!wasComplete || kbInit !== null || bootFailure() !== null) && isComplete(settings)) {
+      if ((!wasComplete || kbInit !== null || bootFailure() !== null) && isComplete(settings, kb)) {
         /**
          * The folder names, applied BEFORE the phase for the same reason as
          * the branch model above: they are otherwise applied once at boot, so
@@ -327,10 +331,10 @@ export function createSetupRoutes(
          * the names an earlier setup save applied before a run that failed:
          * the gate never opened, so the retry initializes what is saved now.
          */
-        if (isDefaultKbLayout() || (kbInit !== null && layoutAppliedBySetup)) {
+        if (isDefaultKbLayout(kb.layout) || (kbInit !== null && layoutAppliedBySetup)) {
           const layout = settings.resolveKbLayout();
           if (!validateKbLayout(layout)) {
-            configureKbLayout(layout);
+            kb.applyLayout(layout);
             layoutApplied = true;
             layoutAppliedBySetup = true;
           }
@@ -382,7 +386,7 @@ export function createSetupRoutes(
               )
             : restartRequired,
         complete: kbReady(),
-        awaitingRestart: awaitingRestart(settings),
+        awaitingRestart: awaitingRestart(settings, kb),
         settings: settings.describe(),
         oidcVerification: await settings.oidcVerification(),
       });
@@ -784,11 +788,17 @@ export function settingsAnswered(settings: DeploymentSettingsService): boolean {
  * that puts it there. {@link awaitingRestart} is what tells the screen to ask
  * for one rather than claim a field is missing.
  */
-export function isComplete(settings: DeploymentSettingsService): boolean {
-  return settingsAnswered(settings) && isBranchModelConfigured();
+export function isComplete(
+  settings: DeploymentSettingsService,
+  kb: Pick<KbContext, 'isBranchModelConfigured'>,
+): boolean {
+  return settingsAnswered(settings) && kb.isBranchModelConfigured();
 }
 
 /** Answered, but not yet in effect: everything is stored, the process is stale. */
-export function awaitingRestart(settings: DeploymentSettingsService): boolean {
-  return settingsAnswered(settings) && !isBranchModelConfigured();
+export function awaitingRestart(
+  settings: DeploymentSettingsService,
+  kb: Pick<KbContext, 'isBranchModelConfigured'>,
+): boolean {
+  return settingsAnswered(settings) && !kb.isBranchModelConfigured();
 }

package/src/modules/skills/__tests__/allowed-tools-check.test.ts

@@ -7,6 +7,7 @@ import {
 } from '../allowed-tools-check.js';
 import type { UtcpTool } from '../../tool-registry/tool.contract.js';
 import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const visible: VisibleTools = {
   core: ['read_file', 'get_skill', 'list_skills'],
@@ -110,10 +111,10 @@ describe('checkAllowedTools', () => {
 
 describe('skillFileRepoPath', () => {
   test('recognises skill files under the plugin and skills roots only', () => {
-    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Plugins/Sales/rfi/SKILL.md')).toBe('Plugins/Sales/rfi/SKILL.md');
-    expect(skillFileRepoPath('knowledge-base', './knowledge-base/Skills/triage/SKILL.md')).toBe('Skills/triage/SKILL.md');
-    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Plugins/Sales/rfi/notes.md')).toBeNull();
-    expect(skillFileRepoPath('knowledge-base', 'knowledge-base/Data/SKILL.md')).toBeNull();
+    expect(skillFileRepoPath(testKbContext(),'knowledge-base/Plugins/Sales/rfi/SKILL.md')).toBe('Plugins/Sales/rfi/SKILL.md');
+    expect(skillFileRepoPath(testKbContext(),'./knowledge-base/Skills/triage/SKILL.md')).toBe('Skills/triage/SKILL.md');
+    expect(skillFileRepoPath(testKbContext(),'knowledge-base/Plugins/Sales/rfi/notes.md')).toBeNull();
+    expect(skillFileRepoPath(testKbContext(),'knowledge-base/Data/SKILL.md')).toBeNull();
   });
 });
 
@@ -138,7 +139,7 @@ describe('AllowedToolsChecker', () => {
           }
         : null,
   };
-  const checker = new AllowedToolsChecker(registry, manuals, 'knowledge-base');
+  const checker = new AllowedToolsChecker(registry, manuals, testKbContext());
 
   const skill = (tools: string) => `---\nname: rfi\ndescription: RFI.\nallowed-tools: ${tools}\n---\n\n# RFI\n`;
 
@@ -160,7 +161,7 @@ describe('AllowedToolsChecker', () => {
     const broken = new AllowedToolsChecker(
       { listExternal: async () => { throw new Error('down'); } },
       manuals,
-      'knowledge-base',
+      testKbContext(),
     );
     await expect(
       broken.checkSave('a@x.com', 'knowledge-base/Plugins/Sales/rfi/SKILL.md', skill('hubspot.serch')),
@@ -168,7 +169,7 @@ describe('AllowedToolsChecker', () => {
   });
 
   test('a capped capability list is treated as unknown, never as proof of absence', async () => {
-    const capped = new AllowedToolsChecker(registry, manuals, 'knowledge-base', 1);
+    const capped = new AllowedToolsChecker(registry, manuals, testKbContext(), 1);
     expect(await capped.check('a@x.com', ['hubspot.whatever'])).toEqual([]);
   });
 
@@ -179,7 +180,7 @@ describe('AllowedToolsChecker', () => {
     const listExternal = vi.fn(registry.listExternal);
     const listAccessible = vi.fn(manuals.listAccessible);
     const getDetail = vi.fn(manuals.getDetail);
-    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, testKbContext());
 
     expect(entries(await spying.check('alice@example.com', ['hubspot.serch']))).toEqual(['hubspot.serch']);
     expect(listExternal).toHaveBeenCalledWith({ userEmail: 'alice@example.com' });
@@ -193,7 +194,7 @@ describe('AllowedToolsChecker', () => {
     const listExternal = vi.fn(registry.listExternal);
     const listAccessible = vi.fn(manuals.listAccessible);
     const getDetail = vi.fn(manuals.getDetail);
-    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, testKbContext());
 
     const results = await spying.checkSaves('a@x.com', [
       { path: 'knowledge-base/Plugins/Sales/rfi/SKILL.md', content: skill('hubspot.serch') },
@@ -214,7 +215,7 @@ describe('AllowedToolsChecker', () => {
     const listExternal = vi.fn(registry.listExternal);
     const listAccessible = vi.fn(manuals.listAccessible);
     const getDetail = vi.fn(manuals.getDetail);
-    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, 'knowledge-base');
+    const spying = new AllowedToolsChecker({ listExternal }, { listAccessible, getDetail }, testKbContext());
 
     expect(await spying.check('a@x.com', ['Bash', 'Read', 'Bash(git:*)', 'mcp__github__create_issue', 'shell'])).toEqual([]);
     expect(listExternal).not.toHaveBeenCalled();

package/src/modules/skills/__tests__/allowed-tools-warn.tools.test.ts

@@ -19,6 +19,7 @@ import type { ToolManualDetail, ToolManualSummary } from '../../tool-manuals/too
 import { registerSkillsTools } from '../skills.tools.js';
 import type { ISkillService } from '../skills.contract.js';
 import { AllowedToolsChecker } from '../allowed-tools-check.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The agent surfaces end to end: a SKILL.md written through the file tools
@@ -41,7 +42,7 @@ const checker = new AllowedToolsChecker(
       capabilities: [{ name: 'search', description: null }],
     }),
   },
-  KB_DIR,
+  testKbContext({ kbDirName: KB_DIR }),
 );
 
 /** What the tool handed the service on its last `getSkill` — the tool's one job is to pass it on. */
@@ -109,8 +110,8 @@ async function start(): Promise<string> {
   const router = express.Router();
   registerWorkspaceTools(
     registry, router, fakeAuth, 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(),
     {} as never,
     checker,

package/src/modules/skills/__tests__/pending-skills.service.test.ts

@@ -5,6 +5,7 @@ import { hashEmail } from '../../../shared/email-identity.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ISkillService, SkillSummary } from '../skills.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The half of the catalog that is NOT on the default branch.
@@ -77,7 +78,7 @@ function harness(opts: {
     listChangeRequests: async () => opts.crs,
   } as unknown as IWorkflowService;
 
-  return new PendingSkillsService(workspaceService, accessControl, skillService, workflow);
+  return new PendingSkillsService(workspaceService, accessControl, skillService, workflow, testKbContext());
 }
 
 const ADMIN_WRITES = {
@@ -210,6 +211,7 @@ describe('PendingSkillsService', () => {
       {} as unknown as IAccessControl,
       { listSkills: async () => [] } as unknown as ISkillService,
       workflow,
+      testKbContext(),
     );
     await expect(svc.listPendingSkills(AUTHOR)).resolves.toEqual([]);
   });

package/src/modules/skills/__tests__/skill-access-requests.routes.test.ts

@@ -11,6 +11,7 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { JoinRequestsService } from '../../plugins/join-requests.service.js';
 import type { ISkillService } from '../skills.contract.js';
 import { createSkillAccessRequestRoutes } from '../skill-access-requests.routes.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The branch probe behind an access request: the listing is used to PROVE a
@@ -52,7 +53,7 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
       workflow,
       workspaceService,
       joinRequests: { list: vi.fn(), reconcile: vi.fn() } as unknown as JoinRequestsService,
-      kbDirName: KB,
+      kb: testKbContext({ kbDirName: KB }),
       resolveUser: async () => MIA,
     }),
   );

package/src/modules/skills/__tests__/skills.routes.warnings.test.ts

@@ -5,6 +5,7 @@ import '../../auth/auth.middleware.js'; // Express Request.userEmail augmentatio
 import { createSkillsRoutes } from '../skills.routes.js';
 import type { ISkillService } from '../skills.contract.js';
 import type { IAllowedToolsChecker } from '../allowed-tools-check.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The browser's skill read carries the same `allowed-tools` warnings as
@@ -42,7 +43,7 @@ async function start(checker?: IAllowedToolsChecker): Promise<string> {
     req.userEmail = EMAIL;
     next();
   });
-  app.use('/api', createSkillsRoutes(skillService, undefined, undefined, undefined, checker));
+  app.use('/api', createSkillsRoutes(skillService, testKbContext(), undefined, undefined, undefined, checker));
   server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));
   });