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

package/src/modules/secrets-vault/index.ts

@@ -21,6 +21,8 @@ export {
 } from './secrets-vault.contract.js';
 export {
   registerBevelSecretsVariableLoader,
+  unregisterBevelSecretsVariableLoader,
   bevelSecretsLoaderConfig,
   BEVEL_SECRETS_LOADER_TYPE,
+  DEFAULT_SECRETS_SCOPE,
 } from './secrets-variable-loader.js';

package/src/modules/secrets-vault/secrets-variable-loader.ts

@@ -18,29 +18,43 @@ const log = logger('secrets-vault');
  * The `UtcpClient.create` path re-validates the whole config through the
  * serializer registry, so a loader can't be handed in as a bare live object — it
  * must round-trip through a registered serializer. We therefore put a plain
- * descriptor `{ variable_loader_type, user_id }` in `load_variables_from` (via
- * {@link bevelSecretsLoaderConfig}) and let the registered serializer rebuild a
- * live loader bound to the process-wide vault. Swapping the vault backend (e.g.
- * to a client's external secret manager) is just a different
- * `ISecretsVaultService` passed to {@link registerBevelSecretsVariableLoader}.
+ * descriptor `{ variable_loader_type, user_id, scope }` in `load_variables_from`
+ * (via {@link bevelSecretsLoaderConfig}) and let the registered serializer
+ * rebuild a live loader bound to the vault registered under that scope.
+ *
+ * ONE VAULT PER SCOPE, NOT PER PROCESS. The serializer registry is UTCP's and
+ * process-wide, but a process can host several knowledge bases, each with a
+ * vault of its own, and a user id is only unique within one of them. So the
+ * descriptor names the scope its vault was registered under, and a loader
+ * reads through that vault alone: two knowledge bases whose users both stored
+ * `weather_WEATHER_KEY` never see each other's value. A single-tenant
+ * deployment registers under {@link DEFAULT_SECRETS_SCOPE} and names nothing.
+ * Swapping the vault backend (e.g. to a client's external secret manager) is
+ * just a different `ISecretsVaultService` passed to
+ * {@link registerBevelSecretsVariableLoader}.
  */
 export const BEVEL_SECRETS_LOADER_TYPE = 'bevel_secrets';
 
+/** The scope a deployment that hosts one knowledge base registers under. */
+export const DEFAULT_SECRETS_SCOPE = 'default';
+
 /**
- * Process-wide vault the reconstructed loaders read through. Set once at
- * composition time (before any client is built) so the serializer — which only
- * receives a plain dict — can bind live loaders to it.
+ * The vaults the reconstructed loaders read through, by scope. A composition
+ * root registers its vault before any client is built; a graph that is torn
+ * down unregisters it so a stale descriptor resolves nothing.
  */
-let sharedSecretsVault: ISecretsVaultService | null = null;
+const vaults = new Map<string, ISecretsVaultService>();
 
 export class BevelSecretsVariableLoader implements VariableLoader {
   readonly variable_loader_type = BEVEL_SECRETS_LOADER_TYPE;
   readonly user_id: string;
+  readonly scope: string;
   // VariableLoader is an open shape; allow arbitrary extra props.
   [key: string]: unknown;
 
-  constructor(userId: string) {
+  constructor(userId: string, scope: string = DEFAULT_SECRETS_SCOPE) {
     this.user_id = userId;
+    this.scope = scope;
   }
 
   /**
@@ -52,9 +66,10 @@ export class BevelSecretsVariableLoader implements VariableLoader {
    * harvest a secret the user configured for a different manual.
    */
   async get(effectiveKey: string): Promise<string | null> {
-    if (!sharedSecretsVault || !this.user_id) return null;
+    const vault = vaults.get(this.scope);
+    if (!vault || !this.user_id) return null;
     try {
-      return await sharedSecretsVault.resolve(this.user_id, effectiveKey);
+      return await vault.resolve(this.user_id, effectiveKey);
     } catch (err) {
       // Log the fault so a backend failure is distinguishable from a merely
       // unset secret (resolve returning null) when troubleshooting.
@@ -66,15 +81,18 @@ export class BevelSecretsVariableLoader implements VariableLoader {
 
 class BevelSecretsVariableLoaderSerializer extends Serializer<VariableLoader> {
   toDict(obj: VariableLoader): Record<string, unknown> {
+    const loader = obj as BevelSecretsVariableLoader;
     return {
       variable_loader_type: BEVEL_SECRETS_LOADER_TYPE,
-      user_id: (obj as BevelSecretsVariableLoader).user_id ?? '',
+      user_id: loader.user_id ?? '',
+      scope: loader.scope ?? DEFAULT_SECRETS_SCOPE,
     };
   }
 
   validateDict(obj: Record<string, unknown>): VariableLoader {
     const userId = typeof obj.user_id === 'string' ? obj.user_id : '';
-    return new BevelSecretsVariableLoader(userId);
+    const scope = typeof obj.scope === 'string' && obj.scope ? obj.scope : DEFAULT_SECRETS_SCOPE;
+    return new BevelSecretsVariableLoader(userId, scope);
   }
 }
 
@@ -91,14 +109,26 @@ VariableLoaderSerializer.registerVariableLoader(
 );
 
 /**
- * Bind the process-wide vault the reconstructed loaders read through. Called
- * once at composition time; before it runs, loaders resolve to null.
+ * Bind the vault the loaders of `scope` read through. Called once per
+ * knowledge base at composition time; before it runs, loaders of that scope
+ * resolve to null.
  */
-export function registerBevelSecretsVariableLoader(secretsVault: ISecretsVaultService): void {
-  sharedSecretsVault = secretsVault;
+export function registerBevelSecretsVariableLoader(
+  secretsVault: ISecretsVaultService,
+  scope: string = DEFAULT_SECRETS_SCOPE,
+): void {
+  vaults.set(scope, secretsVault);
+}
+
+/** Forget a scope's vault — the last step of tearing a knowledge base's graph down. */
+export function unregisterBevelSecretsVariableLoader(scope: string = DEFAULT_SECRETS_SCOPE): void {
+  vaults.delete(scope);
 }
 
-/** The plain descriptor to place in a `UtcpClientConfig.load_variables_from` for a given user. */
-export function bevelSecretsLoaderConfig(userId: string): Record<string, unknown> {
-  return { variable_loader_type: BEVEL_SECRETS_LOADER_TYPE, user_id: userId };
+/**
+ * The plain descriptor to place in a `UtcpClientConfig.load_variables_from`
+ * for a given user of the knowledge base registered under `scope`.
+ */
+export function bevelSecretsLoaderConfig(userId: string, scope: string = DEFAULT_SECRETS_SCOPE): Record<string, unknown> {
+  return { variable_loader_type: BEVEL_SECRETS_LOADER_TYPE, user_id: userId, scope };
 }

package/src/modules/secrets-vault/secrets-vault.routes.ts

@@ -3,7 +3,6 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('secrets');
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
-import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import {
   InvalidSecretError,
   SecretNotFoundError,
@@ -17,11 +16,13 @@ import type { IToolManualService, ToolManualSummary, ToolVariable } from '../too
 import type { IConnectionProbeService } from '../connection-probe/connection-probe.contract.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
 
 export interface SecretsVaultRoutesDeps {
   secretsVault: ISecretsVaultService;
+  /** The released branch's clone — where the `.tool` files the access verdicts are read from live. */
+  kb: Pick<KbContext, 'defaultWorkspaceId'>;
   /** Source of `.tool` manuals + their declared variable scopes (default-branch catalog). */
   toolManualService: IToolManualService;
   /** Gates who may set a tool's ADMIN (shared) secrets — writers of the `.tool` file. */
@@ -79,16 +80,16 @@ export function isSafeReturnPath(returnTo: unknown): returnTo is string {
  * `req.userId` — secrets are private per user. Mounted behind the JWT middleware.
  */
 export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.Router {
-  const { secretsVault, toolManualService, accessControl, connectionProbe } = deps;
+  const { secretsVault, toolManualService, accessControl, connectionProbe, kb } = deps;
   const router = express.Router();
   // A FUNCTION, not a constant. Routers are constructed at boot, and on a
   // deployment configured through the setup screen the branch model does not
-  // exist yet at that moment — `DEFAULT_BRANCH` is still ''. The live binding
-  // updates when setup applies the model, but only reads INSIDE a function
+  // exist yet at that moment — the default branch is still ''. The context
+  // learns it when setup applies the model, but only reads INSIDE a function
   // body see it; a construction-time capture would keep handing an empty
   // workspace id to the access resolver until the next restart ("Invalid
   // workspace ID" on every /secrets/tools call).
-  const defaultWs = () => workspaceIdForBranch(DEFAULT_BRANCH);
+  const defaultWs = () => kb.defaultWorkspaceId();
 
   // The vault key = the exact key UTCP looks the var up under (doubles underscores
   // in the manual namespace), so storage and resolution agree for snake_case ids.

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

@@ -84,6 +84,41 @@ describe('DeploymentSettingsService — precedence', () => {
   });
 });
 
+describe('DeploymentSettingsService — a blank that means the default', () => {
+  /**
+   * The rule everywhere else: a blank field leaves a setting alone. The Audit
+   * log's retention window is the exception that declares itself — its
+   * readers already treat "unset" as the default, so clearing the field is
+   * the one way back to that default, and a blank saves as a clear.
+   */
+  it('clears a blank-means-default setting on a blank save and leaves every other blank alone', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ auditRetentionDays: '30', kbRepoUrl: 'https://example.com/stored.git' }, null);
+    expect(settings.resolve('auditRetentionDays')).toBe('30');
+
+    await settings.save({ auditRetentionDays: '', kbRepoUrl: '' }, null);
+
+    expect(settings.resolve('auditRetentionDays')).toBe('');
+    expect(settings.sourceOf('auditRetentionDays')).toBe('unset');
+    // The repository address was blank too, and blank still means "leave it".
+    expect(settings.resolve('kbRepoUrl')).toBe('https://example.com/stored.git');
+    expect(rows.some((r) => r.key === 'kbRepoUrl')).toBe(true);
+  });
+
+  it('holds the retention window to the same rule on save as the runtime reader does', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    for (const bad of ['1.5', 'lots', 'ten days']) {
+      await expect(settings.save({ auditRetentionDays: bad }, null)).rejects.toBeInstanceOf(SettingsValidationError);
+    }
+    // A number of days, or zero / negative for "forever" — the reader's rule.
+    for (const ok of ['3650', '0', '-1', '99999']) {
+      await expect(settings.save({ auditRetentionDays: ok }, null)).resolves.toBeDefined();
+    }
+  });
+});
+
 describe('DeploymentSettingsService — secrets', () => {
   it('stores the token as ciphertext and reads it back', async () => {
     const { db, rows } = makeDb();
@@ -114,20 +149,12 @@ describe('DeploymentSettingsService — secrets', () => {
     expect(token).not.toHaveProperty('value');
   });
 
-  it('publishes a stored token as GITHUB_TOKEN, which is what git reads', async () => {
+  it('keeps a stored token out of the process environment: git reads it per call', async () => {
     const { db } = makeDb();
     const settings = new DeploymentSettingsService(db, ENC_KEY);
     await settings.save({ gitToken: 'ghp_fromsetup' }, null);
-    expect(process.env.GITHUB_TOKEN).toBe('ghp_fromsetup');
-  });
-
-  it('does not overwrite a git token the environment supplied', async () => {
-    process.env.GIT_TOKEN = 'ghp_fromenv';
-    process.env.GITHUB_TOKEN = 'ghp_fromenv';
-    const { db } = makeDb();
-    const settings = new DeploymentSettingsService(db, ENC_KEY);
-    settings.syncGitTokenEnv();
-    expect(process.env.GITHUB_TOKEN).toBe('ghp_fromenv');
+    expect(process.env.GITHUB_TOKEN).toBeUndefined();
+    expect(settings.resolve('gitToken')).toBe('ghp_fromsetup');
   });
 
   it('refuses to store a secret with no encryption key rather than writing plaintext', async () => {
@@ -493,3 +520,24 @@ describe('DeploymentSettingsService — validation', () => {
     ).toEqual([]);
   });
 });
+
+describe('DeploymentSettingsService — an environment of its own', () => {
+  it('resolves the env-first layer from the environment it was given, not the process\'s', async () => {
+    process.env.KB_REPO_URL = 'https://host.example/leaks-into-every-tenant.git';
+    const { db } = makeDb();
+    const own = new DeploymentSettingsService(db, ENC_KEY, undefined, {
+      env: { KB_REPO_URL: 'https://github.com/acme/kb.git', GIT_USERNAME: 'oauth2' },
+    });
+    await own.load();
+    expect(own.resolve('kbRepoUrl')).toBe('https://github.com/acme/kb.git');
+    expect(own.sourceOf('kbRepoUrl')).toBe('env');
+    expect(own.resolve('gitUsername')).toBe('oauth2');
+    // What the given environment leaves out is not taken from the process either.
+    expect(own.resolve('gitToken')).toBe('');
+    expect(own.sourceOf('gitToken')).toBe('unset');
+    // A service built without one keeps reading the process, as before.
+    const shared = new DeploymentSettingsService(db, ENC_KEY);
+    await shared.load();
+    expect(shared.resolve('kbRepoUrl')).toBe('https://host.example/leaks-into-every-tenant.git');
+  });
+});

package/src/modules/settings/__tests__/git-root-folders.test.ts

@@ -10,7 +10,7 @@ import {
   rootFolderListerFor,
   type GitRunner,
 } from '../git-root-folders.js';
-import type { IGitRunner } from '../../../shared/git.contract.js';
+import { NO_GIT_CREDENTIALS, type IGitRunner } from '../../../shared/git.contract.js';
 
 const LISTING = {
   url: 'https://example.com/acme/kb.git',
@@ -226,6 +226,7 @@ describe('rootFolderListerFor — the listing runs through the deployment git po
     const outcomes = ['', 'KnowledgeBase\0Plugins\0'];
     const port: IGitRunner = {
       defaultTimeoutMs: 1000,
+      credentials: NO_GIT_CREDENTIALS,
       run: (async (cwd: string, args: string[], opts: { env?: NodeJS.ProcessEnv; timeoutMs?: number } = {}) => {
         calls.push({ cwd, args, opts });
         return { stdout: outcomes.shift() ?? '', stderr: '' };

package/src/modules/settings/__tests__/setup.routes.boot-failure.test.ts

@@ -6,6 +6,7 @@ import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * A boot that survived an unreachable remote leaves the RUNNER standing on a
@@ -68,7 +69,7 @@ function listen(runner: { runAll(): Promise<void>; lastFailure(): string | null
   });
   app.use(
     '/api',
-    createSetupRoutes(settings, { isAdmin: async () => true } as IAdminAccessService, runner),
+    createSetupRoutes(settings, { isAdmin: async () => true } as IAdminAccessService, runner, testKbContext()),
   );
   server = app.listen(0);
   const { port } = server.address() as AddressInfo;

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', () =>