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

package/src/__tests__/kb-layout-config.test.ts

@@ -20,6 +20,7 @@ import {
   validateKbLayout,
   validateKbRootName,
   normalizeSkillRoot,
+  type KbLayout,
 } from '@bevel-software/platform-shared';
 
 /**
@@ -29,6 +30,10 @@ import {
  */
 afterEach(() => configureKbLayout({ ...DEFAULT_KB_LAYOUT }));
 
+/** The helpers under the browser's configured layout — the shape these cases were written against. */
+const validateGuideName = (name: string, roots: KbLayout = DEFAULT_KB_LAYOUT) => validateAgentsFileName(name, roots);
+const platformFile = (path: string) => isPlatformFile(path, currentKbLayout());
+
 describe('KB layout — validation', () => {
   test('accepts the defaults and any three distinct plain folder names', () => {
     expect(validateKbLayout({ ...DEFAULT_KB_LAYOUT })).toBeNull();
@@ -100,12 +105,12 @@ describe('KB layout — configuration', () => {
 
   test('the derived sets follow the configured names rather than snapshotting the defaults', () => {
     configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
-    expect(ontologyRoots()).toEqual(['docs', 'Data']);
-    expect(reservedRootDirNames().has('plugins')).toBe(true);
-    expect(reservedRootDirNames().has('Plugins')).toBe(false);
-    // Path rules read the live name too.
-    expect(pluginOfPath('plugins/GTM/skills/x/SKILL.md')).toBe('GTM');
-    expect(pluginOfPath('Plugins/GTM/skills/x/SKILL.md')).toBeNull();
+    expect(ontologyRoots(currentKbLayout())).toEqual(['docs', 'Data']);
+    expect(reservedRootDirNames(currentKbLayout()).has('plugins')).toBe(true);
+    expect(reservedRootDirNames(currentKbLayout()).has('Plugins')).toBe(false);
+    // Path rules read the configured name too.
+    expect(pluginOfPath('plugins/GTM/skills/x/SKILL.md', currentKbLayout())).toBe('GTM');
+    expect(pluginOfPath('Plugins/GTM/skills/x/SKILL.md', currentKbLayout())).toBeNull();
   });
 
   test('throws on an invalid layout and leaves the current one untouched', () => {
@@ -137,7 +142,7 @@ describe('KB layout — the agent guide\'s file name', () => {
   });
 
   test('accepts a plain markdown name and applies it to the live binding', () => {
-    expect(validateAgentsFileName('HEXIS.md')).toBeNull();
+    expect(validateGuideName('HEXIS.md')).toBeNull();
     configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     expect(AGENTS_FILE).toBe('HEXIS.md');
     expect(currentKbLayout().agentsFile).toBe('HEXIS.md');
@@ -145,30 +150,30 @@ describe('KB layout — the agent guide\'s file name', () => {
 
   test('refuses every shape that is not one markdown file name of its own', () => {
     // A folder path: the guide is read from the repository root and nowhere else.
-    expect(validateAgentsFileName('guides/HEXIS.md')).toMatch(/single file name/);
-    expect(validateAgentsFileName('guides\\HEXIS.md')).toMatch(/single file name/);
+    expect(validateGuideName('guides/HEXIS.md')).toMatch(/single file name/);
+    expect(validateGuideName('guides\\HEXIS.md')).toMatch(/single file name/);
     // Not markdown: the per-file access rules apply to `.md` alone.
-    expect(validateAgentsFileName('HEXIS.txt')).toMatch(/end in \.md/);
+    expect(validateGuideName('HEXIS.txt')).toMatch(/end in \.md/);
     // Nothing at all.
-    expect(validateAgentsFileName('')).toMatch(/required/);
-    expect(validateAgentsFileName('   ')).toMatch(/required/);
+    expect(validateGuideName('')).toMatch(/required/);
+    expect(validateGuideName('   ')).toMatch(/required/);
     // A dot-file every scanner skips — including the one that draws the tree.
-    expect(validateAgentsFileName('.hidden.md')).toMatch(/start with a dot/);
+    expect(validateGuideName('.hidden.md')).toMatch(/start with a dot/);
     // The guide's own pre-rename name stays legacy content.
-    expect(validateAgentsFileName('CLAUDE.md')).toMatch(/pre-rename name/);
-    expect(validateAgentsFileName('claude.md')).toMatch(/pre-rename name/);
+    expect(validateGuideName('CLAUDE.md')).toMatch(/pre-rename name/);
+    expect(validateGuideName('claude.md')).toMatch(/pre-rename name/);
     // The other platform files: two platform roles on one path.
-    expect(validateAgentsFileName('access.md')).toMatch(/platform file name/);
-    expect(validateAgentsFileName('roles.yaml')).toMatch(/platform file name/);
-    expect(validateAgentsFileName('.bevelignore')).toMatch(/platform file name/);
-    expect(validateAgentsFileName('mcp-description.md')).toMatch(/platform file name/);
+    expect(validateGuideName('access.md')).toMatch(/platform file name/);
+    expect(validateGuideName('roles.yaml')).toMatch(/platform file name/);
+    expect(validateGuideName('.bevelignore')).toMatch(/platform file name/);
+    expect(validateGuideName('mcp-description.md')).toMatch(/platform file name/);
     // The rule every path component passes.
-    expect(validateAgentsFileName('CON.md')).not.toBeNull();
-    expect(validateAgentsFileName('a:b.md')).not.toBeNull();
+    expect(validateGuideName('CON.md')).not.toBeNull();
+    expect(validateGuideName('a:b.md')).not.toBeNull();
   });
 
   test('refuses the name of a root folder, whichever of the two the save names', () => {
-    expect(validateAgentsFileName('Plugins.md', { ...DEFAULT_KB_LAYOUT, pluginsDir: 'Plugins.md' }))
+    expect(validateGuideName('Plugins.md', { ...DEFAULT_KB_LAYOUT, pluginsDir: 'Plugins.md' }))
       .toMatch(/already the plugins folder/);
     // Case-insensitively, like the folders are to each other: one entry on a
     // case-insensitive disk.
@@ -197,16 +202,16 @@ describe('KB layout — the agent guide\'s file name', () => {
       '.bevelignore',
       'AGENTS.md',
     ]);
-    expect(isPlatformFile('AGENTS.md')).toBe(true);
+    expect(platformFile('AGENTS.md')).toBe(true);
 
     configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    expect(platformFileNames()).toEqual(['access.md', 'roles.yaml', '.bevelignore', 'HEXIS.md']);
+    expect(platformFileNames(currentKbLayout())).toEqual(['access.md', 'roles.yaml', '.bevelignore', 'HEXIS.md']);
     // The guide the platform writes is immovable and undeletable…
-    expect(isPlatformFile('HEXIS.md')).toBe(true);
+    expect(platformFile('HEXIS.md')).toBe(true);
     // …and the customer's own AGENTS.md is a page like any other.
-    expect(isPlatformFile('AGENTS.md')).toBe(false);
+    expect(platformFile('AGENTS.md')).toBe(false);
     // Still root-only, as `roles.yaml` is: a nested copy is content.
-    expect(isPlatformFile('KnowledgeBase/HEXIS.md')).toBe(false);
+    expect(platformFile('KnowledgeBase/HEXIS.md')).toBe(false);
   });
 
   test('the pointer sentence is one sentence, naming the guide twice, from one place', () => {
@@ -215,7 +220,7 @@ describe('KB layout — the agent guide\'s file name', () => {
         "it is the platform's guide to its layout, files and rules.",
     );
     configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    expect(agentsFilePointerSentence()).toContain('HEXIS.md');
+    expect(agentsFilePointerSentence(currentKbLayout().agentsFile)).toContain('HEXIS.md');
   });
 
   /**
@@ -226,7 +231,7 @@ describe('KB layout — the agent guide\'s file name', () => {
    */
   test('the pointer sentence links correctly for a name full of markdown punctuation', () => {
     const name = 'Our [Agent] Guide (v2).md';
-    expect(validateAgentsFileName(name)).toBeNull();
+    expect(validateGuideName(name)).toBeNull();
     const sentence = agentsFilePointerSentence(name);
     // The label cannot end early: the brackets in it are escaped…
     expect(sentence).toContain('[Our \\[Agent\\] Guide (v2).md]');
@@ -240,7 +245,7 @@ describe('KB layout — the agent guide\'s file name', () => {
   test('the pointer sentence encodes a name that would otherwise open a URL fragment', () => {
     // `#` is legal in a filename and opens a fragment in a URL: `./#2 Guide.md`
     // links to the customer's OWN file with a fragment, not to the guide.
-    expect(validateAgentsFileName('#2 Guide.md')).toBeNull();
+    expect(validateGuideName('#2 Guide.md')).toBeNull();
     expect(agentsFilePointerSentence('#2 Guide.md')).toContain('(./%232%20Guide.md)');
     // `%` is legal too, and an unencoded one is a malformed escape.
     expect(agentsFilePointerSentence('100%.md')).toContain('(./100%25.md)');

package/src/core/__tests__/catalog-cache-invalidation.test.ts

@@ -4,6 +4,7 @@ import { FileChangeNotifier } from '../../modules/kb-fs/file-change-notifier.js'
 import { WorkflowEventBus } from '../../modules/workflow/event-bus.js';
 import { registerCatalogCacheInvalidation } from '../catalog-cache-invalidation.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { testKbContext } from '../../__tests__/kb-context.js';
 
 const KB_DIR = 'knowledge-base';
 
@@ -25,7 +26,7 @@ function setup() {
   const off = registerCatalogCacheInvalidation({
     eventBus,
     fileChangeNotifier,
-    kbDirName: KB_DIR,
+    kb: testKbContext({ kbDirName: KB_DIR }),
     catalogs,
     accessControl,
   });

package/src/core/__tests__/lifecycle.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { createShutdown, holdCommitWorkerLease, withStartupTask, type LeasedWorker } from '../lifecycle.js';
+import { createShutdown, holdCommitWorkerLease, stopCore, withStartupTask, type LeasedWorker } from '../lifecycle.js';
+import { BevelSecretsVariableLoader, registerBevelSecretsVariableLoader } from '../../modules/secrets-vault/secrets-variable-loader.js';
 import type { AdvisoryLease } from '../../modules/database/advisory-lock.js';
 
 /** A lease the suite scripts: what each `tryAcquire` answers, and a way to lose it. */
@@ -367,3 +368,79 @@ describe('createShutdown', () => {
     expect(d.order.filter((step) => step === 'db.end')).toHaveLength(1);
   });
 });
+
+describe('stopCore', () => {
+  function graph() {
+    const order: string[] = [];
+    return {
+      order,
+      core: {
+        commitWorker: {
+          async stop() {
+            order.push('commitWorker.stop');
+          },
+        },
+        backgroundJobs: {
+          stopSweeping() {
+            order.push('backgroundJobs.stopSweeping');
+          },
+          async drain() {
+            order.push('backgroundJobs.drain');
+          },
+        },
+        startupRetry: {
+          stop() {
+            order.push('startupRetry.stop');
+          },
+        },
+        db: {
+          $client: {
+            async end() {
+              order.push('db.end');
+            },
+          },
+        },
+        secretsScope: 'acme/t_acme',
+        log: () => undefined,
+      },
+    };
+  }
+
+  it('stops a graph without a server: sweeps and the retry first, the worker, then the pool', async () => {
+    const g = graph();
+    await stopCore(g.core as never);
+    expect(g.order).toEqual([
+      'backgroundJobs.stopSweeping',
+      'startupRetry.stop',
+      'backgroundJobs.drain',
+      'commitWorker.stop',
+      'db.end',
+    ]);
+  });
+
+  it('forgets the graph\'s secrets scope, so a descriptor that outlives it resolves nothing', async () => {
+    const g = graph();
+    registerBevelSecretsVariableLoader(
+      { resolve: async () => 'sk-live' } as never,
+      g.core.secretsScope,
+    );
+    const loader = new BevelSecretsVariableLoader('user-1', g.core.secretsScope);
+    expect(await loader.get('weather_KEY')).toBe('sk-live');
+    await stopCore(g.core as never);
+    expect(await loader.get('weather_KEY')).toBeNull();
+  });
+
+  it('stops a graph that never left a retry asking and never registered a scope', async () => {
+    const g = graph();
+    const core = { ...g.core, startupRetry: null, secretsScope: undefined };
+    await stopCore(core as never);
+    expect(g.order).toEqual(['backgroundJobs.stopSweeping', 'backgroundJobs.drain', 'commitWorker.stop', 'db.end']);
+  });
+
+  it('does not wait past the budget for a worker that never stops, and still ends the pool', async () => {
+    const g = graph();
+    const core = { ...g.core, commitWorker: { stop: () => new Promise<void>(() => undefined) } };
+    await stopCore(core as never, { deadlineMs: 50 });
+    expect(g.order).toEqual(['backgroundJobs.stopSweeping', 'startupRetry.stop', 'backgroundJobs.drain', 'db.end']);
+  });
+});

package/src/core/__tests__/public-config.test.ts

@@ -1,9 +1,13 @@
 import { describe, expect, it } from 'vitest';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { publicConfig } from '../public-config.js';
+import { testKbContext } from '../../__tests__/kb-context.js';
 
 describe('GET /api/config payload', () => {
-  const body = publicConfig({ marketplaceGitUrl: 'https://kb.acme.com/git/marketplace.git', mcpUrl: 'https://kb.acme.com/api/mcp' });
+  const body = publicConfig(testKbContext(), {
+    marketplaceGitUrl: 'https://kb.acme.com/git/marketplace.git',
+    mcpUrl: 'https://kb.acme.com/api/mcp',
+  });
 
   it('advertises the agent-instructions capability, which the local bridge keys on', () => {
     expect(body.agentInstructions).toBe(true);

package/src/core/catalog-cache-invalidation.ts

@@ -1,7 +1,6 @@
-import { DEFAULT_BRANCH, PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
 import type { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import type { WorkflowEventBus } from '../modules/workflow/event-bus.js';
-import { workspaceIdForBranch } from '../shared/workspace-id.js';
+import type { KbContext } from '../shared/kb-context.js';
 
 /**
  * A catalog that scans the DEFAULT branch's working tree and caches the result
@@ -26,8 +25,12 @@ export interface InvalidatableCatalog {
 export function registerCatalogCacheInvalidation(deps: {
   eventBus: WorkflowEventBus;
   fileChangeNotifier: FileChangeNotifier;
-  /** The KB folder inside the workspace — `paths` are workspace-relative. */
-  kbDirName: string;
+  /**
+   * The KB folder inside the workspace (`paths` are workspace-relative), the
+   * released branch, and the roots the catalogs read — read per event, never
+   * captured: a deployment may rename the roots from the setup screen.
+   */
+  kb: Pick<KbContext, 'kbDirName' | 'defaultBranch' | 'defaultWorkspaceId' | 'layout'>;
   catalogs: InvalidatableCatalog[];
   /**
    * The read gate every one of those catalogs is FILTERED through, dropped on
@@ -44,13 +47,13 @@ export function registerCatalogCacheInvalidation(deps: {
    */
   accessControl: { invalidate(workspaceId: string): void };
 }): () => void {
-  const { eventBus, fileChangeNotifier, kbDirName, catalogs, accessControl } = deps;
+  const { eventBus, fileChangeNotifier, kb, catalogs, accessControl } = deps;
   const invalidateAll = () => {
     for (const c of catalogs) c.invalidate();
     // Scoped to the branch the catalogs read, and no wider: a drop here costs
     // the next reader one model load, so it must not reach workspaces this
     // event says nothing about.
-    accessControl.invalidate(workspaceIdForBranch(DEFAULT_BRANCH));
+    accessControl.invalidate(kb.defaultWorkspaceId());
   };
 
   // Subscriber A — COMMIT-time freshness: a committed change drops the affected
@@ -61,17 +64,19 @@ export function registerCatalogCacheInvalidation(deps: {
   // service it belongs to — the caches are independent, so the split preserves
   // behavior.)
   const offFiles = fileChangeNotifier.onFilesChanged(({ branch, paths }) => {
-    if (branch !== DEFAULT_BRANCH) return;
+    if (branch !== kb.defaultBranch) return;
     // Skills, tools, the plugin index and the link index all read `Plugins/`
     // or `Skills/`, so one touch check drives every cache. An access grant
     // lands as a default-branch change to `Plugins/<plugin>/access.md` or a
     // skill folder's `access.md`, so this is also what makes a newly-granted
     // plugin or link unlock within one round-trip instead of one TTL. Both
-    // names are live bindings (a deployment may rename the roots), hence read
-    // per event rather than captured.
+    // names are read per event rather than captured: a deployment may rename
+    // the roots.
+    const { kbDirName, layout } = kb;
     if (
       paths.some(
-        (p) => p.startsWith(`${kbDirName}/${PLUGINS_DIR}/`) || p.startsWith(`${kbDirName}/${SKILLS_DIR}/`),
+        (p) =>
+          p.startsWith(`${kbDirName}/${layout.pluginsDir}/`) || p.startsWith(`${kbDirName}/${layout.skillsDir}/`),
       )
     ) {
       invalidateAll();
@@ -100,7 +105,7 @@ export function registerCatalogCacheInvalidation(deps: {
     if (event.kind !== 'fs-tree-changed' && event.kind !== 'git-sync-recovered') return;
     // Both events declare `branch`, so no `in` guard: the kind check above has
     // already narrowed the union to the two that carry one.
-    if (event.branch !== DEFAULT_BRANCH) return;
+    if (event.branch !== kb.defaultBranch) return;
     invalidateAll();
   });
 

package/src/core/core-ports.ts

@@ -6,6 +6,7 @@ import type {
 import type { ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
 import type { AuthProviderPlugin } from '../modules/auth/auth.routes.js';
 import type { IErasureParticipant } from '../modules/auth/account-erasure.service.js';
+import type { IAccountAdmission } from '../modules/auth/account-admission.js';
 import type { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
 
 /**
@@ -98,6 +99,24 @@ export interface CorePorts {
    * contract each step signs up to). Core default: `[]`.
    */
   kbStartupSteps?: readonly OnServerStart[];
+  /**
+   * Mirror this composition's branch model and knowledge-base layout onto the
+   * shared package's PROCESS-WIDE live bindings (`DEFAULT_BRANCH`,
+   * `PLUGINS_DIR`, …), for an overlay that still reads them. Core itself
+   * reads only `CoreServices.kb`. Default true, so an overlay behaves as it
+   * did; a host that serves several knowledge bases in one process passes
+   * false, since there is no single value to put there.
+   */
+  mirrorSharedBindings?: boolean;
+  /**
+   * Whether a NEW account may be provisioned, asked before the row is
+   * inserted on every path that creates one (a first SSO sign-in, an admin
+   * creating an account, the owner's bootstrap sign-in, an embed identity).
+   * Core default: everyone is admitted. A host that sells seats answers
+   * from its plan; a refusal carries the port's own words to the person or
+   * admin who asked. See `modules/auth/account-admission.ts`.
+   */
+  accountAdmission?: IAccountAdmission;
 }
 
 /**

package/src/core/create-core-server.ts

@@ -1,16 +1,11 @@
 import express from 'express';
-import { logger } from '../shared/logging.js';
-
-const startupLog = logger('kb-startup');
-const crLog = logger('cr');
 import cors from 'cors';
 import path from 'node:path';
 import type { Router, RequestHandler } from 'express';
 import { createAuthRoutes } from '../modules/auth/auth.routes.js';
 import { createWorkspaceRoutes } from '../modules/workspace/workspace.routes.js';
 import { createGitInternalsRouteGuard } from '../modules/workspace/git-internals.middleware.js';
-import { noteBesideCheckout } from '../modules/workspace/startup/beside-checkout.js';
-import { printable } from '../shared/printable.js';
+import { startCore } from './lifecycle.js';
 import { createDiffRoutes } from '../modules/diff/diff.routes.js';
 import { createWorkflowRoutes } from '../modules/workflow/workflow.routes.js';
 import { createEventsRoutes } from '../modules/workflow/events.routes.js';
@@ -73,7 +68,6 @@ import type { AuthUser } from '@bevel-software/platform-shared';
 import { GIT_SHA } from '../version.js';
 import { publicConfig } from './public-config.js';
 import { createReadiness } from './readiness.js';
-import { KbRemoteUnreachableError } from '../modules/workspace/startup/kb-startup-runner.js';
 import { createAgentInstructionsRoutes } from '../modules/agent-instructions/index.js';
 import type { CoreServices } from './create-core-services.js';
 
@@ -143,7 +137,11 @@ export interface ServerExtensions {
 export async function createCoreServer(
   core: CoreServices,
   ext: ServerExtensions = {},
-  opts: { staticDir?: string } = {},
+  opts: {
+    staticDir?: string;
+    /** Run {@link startCore} at the usual point of the mount order. Default true. */
+    boot?: boolean;
+  } = {},
 ): Promise<ExpressApp> {
   const app = express();
 
@@ -277,7 +275,7 @@ export async function createCoreServer(
    * on purpose; see `publicConfig` for what it discloses and why.
    */
   app.get('/api/config', (_req, res) => {
-    res.json(publicConfig({ marketplaceGitUrl: marketplaceGitUrl.toString(), mcpUrl: mcpResourceUrl.toString() }));
+    res.json(publicConfig(core.kb, { marketplaceGitUrl: marketplaceGitUrl.toString(), mcpUrl: mcpResourceUrl.toString() }));
   });
 
   // The per-user marketplace as a git remote. Outside `/api` and ahead of
@@ -310,93 +308,12 @@ export async function createCoreServer(
     }),
   );
 
-  // Overlay boot-time side effects (startup reconciles, periodic sweeps).
-  await ext.onBoot?.(core);
-
-  // What is already sitting beside a checkout, named once per boot and touched
-  // by nothing. Outside the KB startup phase below on purpose: that phase is
-  // gated on the branch model and the repository URL, and a deployment whose
-  // setup never finished — or whose remote is down — is exactly one whose
-  // strays would otherwise go unmentioned. A diagnostic never stops a boot, so
-  // an unreadable workspaces root is logged and the boot carries on.
-  try {
-    await noteBesideCheckout(core.config.workspacesRoot, core.kbDirName);
-  } catch (err) {
-    // `printable`, because the message quotes a path off the disk (an ENOENT
-    // or EACCES names the file it failed on) and a name carrying a control
-    // character would forge a second line of the operator's log.
-    startupLog.warn('could not look for content beside the checkouts:', {
-      detail: printable(err instanceof Error ? err.message : String(err)),
-    });
-  }
-
-  // The KB startup phase — AFTER the distribution's onBoot, because a FATAL
-  // template finding raised there must stop the boot before anything seeds
-  // from that template; the runner then brings every branch up to this build
-  // before any route can serve KB content. Throws to stop the boot (the
-  // container's restart policy is the retry) — see kb-startup-runner.ts.
-  //
-  // Runs in the booting process whether or not it holds the commit-worker
-  // lease, so on a redeploy it overlaps the outgoing holder's commits for the
-  // seconds it takes — the documented window at `holdCommitWorkerLease`.
-  try {
-    await core.kbStartupRunner.runAll();
-  } catch (err) {
-    // The one failure a boot survives: the remote cannot be reached. That
-    // says nothing about the knowledge base — what we would write is not
-    // known to be wrong, we cannot get there — so refusing to boot only took
-    // away the login and setup screens an operator needs to fix it (a
-    // rotated token, say). The deployment comes up GATED: the setup routes
-    // read the runner's standing failure and keep the app shut, the setup
-    // screen shows why, saving it retries, and the runner keeps trying on
-    // its own. Every other failure still stops the boot, because it means
-    // the template or a step would write something wrong.
-    if (!(err instanceof KbRemoteUnreachableError)) throw err;
-    startupLog.error('booting UNMAINTAINED and gated — the knowledge-base remote could not be reached:', {
-      detail: err.message,
-    });
-    core.kbStartupRunner.retryUntilMaintained();
-  }
-
-  // Close change requests whose source branch has been deleted. SEQUENCED
-  // AFTER the startup phase above, for two reasons: the sweep's fresh fetch
-  // lazily bootstraps and fetches the same default-branch clone the runner
-  // maintains (kicking it off earlier races the runner's clone/fetch of that
-  // very directory), and on a brand-new deployment it would run before the
-  // empty remote is seeded, fail its clone, swallow the error, and leave
-  // deleted-branch CRs open for the whole process. Still not awaited from
-  // here on: a slow or unreachable remote must not hold up the server —
-  // nothing downstream depends on the result, and the requests it closes
-  // have been unusable since the branch went away, so landing a few seconds
-  // into uptime is soon enough. Errors are swallowed inside the sweep, which
-  // fails safe by closing nothing.
-  void core.workflowService
-    .closeChangeRequestsWithDeletedBranches()
-    .then((n) => {
-      if (n > 0) {
-        crLog.info(`closed ${n} change request${n === 1 ? '' : 's'} with a deleted branch`);
-      }
-    })
-    .catch((err) => crLog.warn('deleted-branch sweep failed:', { err }));
-
-  // Recorded join requests that are still owed, resumed — now, and then on a
-  // timer. SEQUENCED AFTER the startup phase for the same reason as the sweep
-  // above: the work needs the default-branch clone the runner maintains and
-  // the plugin catalog read from it, and a sweep that ran first would refuse
-  // every row for a knowledge base that simply was not ready — telling people
-  // their request could not be sent when nothing had gone wrong with it.
-  //
-  // ON A TIMER rather than at boot alone, because boot cannot cover the
-  // redeploy: this process sweeps while the outgoing one still holds a
-  // record, skips it (correctly — two servers must not do git on one branch),
-  // and the outgoing process then exits mid-work. Nothing else would look at
-  // that row again. The requester cannot prompt it either: a pending record
-  // shows them the "Requested" card, not a button.
-  //
-  // Not awaited, and nothing to report here but the failure to read the table
-  // at all: a first request from a person is a full clone, nothing else at
-  // boot depends on it, and each row records its own outcome.
-  core.pluginJoinRequestJobs.startSweeping();
+  // The graph's boot side effects — the distribution's onBoot, the
+  // knowledge-base startup phase, the sweeps — live in `startCore` so a host
+  // that activates a graph on demand can run and later undo them. Here, at
+  // this point in the mount order, for a single-tenant deployment; a caller
+  // that has already started the graph (or will) passes `boot: false`.
+  if (opts.boot ?? true) await startCore(core, ext);
 
   // Auth routes (unprotected — login endpoint must be accessible)
   app.use(
@@ -468,6 +385,7 @@ export async function createCoreServer(
     stateSecret: core.config.jwtSecret,
     publicBackendUrl: core.config.publicBackendUrl,
     publicFrontendUrl: core.config.publicFrontendUrl,
+    kb: core.kb,
   };
   app.use('/api', createSecretsVaultPublicRoutes(secretsVaultRoutesDeps));
 
@@ -508,16 +426,16 @@ export async function createCoreServer(
   const sessionOntologyGate = {
     service: core.sessionOntologyService,
     enabled: core.config.ontologySessionBlock,
-    kbDirName: core.kbDirName,
+    kb: core.kb,
     recoveryBotEmail: RECOVERY_BOT_EMAIL,
     hooks: core.workflowService.hooks,
   };
   // A skill's `allowed-tools`, checked against what the caller can see — on
   // every save surface (agent write tools, the app's PUT /file) and on
   // `get_skill`. Warnings only; it never refuses a save.
-  const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kbDirName);
-  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kbDirName);
-  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kbDirName, sessionOntologyGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate);
+  const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kb);
+  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb);
+  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, sessionOntologyGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate);
   registerSkillsTools(core.toolRegistry, toolsRouter, ta, th, core.skillService, allowedToolsChecker);
   // Definitions only: the endpoints they describe are the app's own plugin
   // creation routes, mounted below behind the key-or-session gate.
@@ -527,6 +445,7 @@ export async function createCoreServer(
     // The vault satisfies the module's local VariableStatusPort — `list_tool_setup`
     // reports configuration booleans only; secret values never ride through tools.
     variableStatus: core.secretsVaultService,
+    kb: core.kb,
   });
   // Overlay tool registrations (defs + module-hosted endpoints).
   ext.tools?.({
@@ -552,7 +471,7 @@ export async function createCoreServer(
     {
       workspaceService: core.workspaceService,
       accessControl: core.accessControl,
-      kbDirName: core.kbDirName,
+      kb: core.kb,
       disk: core.disk,
       pluginIndex: core.pluginIndexService,
     },
@@ -631,7 +550,7 @@ export async function createCoreServer(
     core.workflowService,
     core.eventBus,
     core.accessControl,
-    core.kbDirName,
+    core.kb,
     core.creatorAccess,
     core.adminAccess,
     core.disk,
@@ -669,13 +588,13 @@ export async function createCoreServer(
     core.workflowService,
     core.eventBus,
     core.db,
-    core.kbDirName,
+    core.kb,
     [core.config.adminEmail],
   ));
   app.use(
     '/api',
     core.authMiddleware,
-    createSkillsRoutes(core.skillService, core.pendingSkillsService, core.pluginLinkIndex, core.accessControl, allowedToolsChecker),
+    createSkillsRoutes(core.skillService, core.kb, core.pendingSkillsService, core.pluginLinkIndex, core.accessControl, allowedToolsChecker),
   );
   // Asking for write on a shared skill — the join-request machinery pointed
   // at a skill folder. Same JWT gate, same fail-closed shape.
@@ -688,7 +607,7 @@ export async function createCoreServer(
       workflow: core.workflowService,
       workspaceService: core.workspaceService,
       joinRequests: core.joinRequestsService,
-      kbDirName: core.kbDirName,
+      kb: core.kb,
       resolveUser: async (req) =>
         req.userId ? ((await core.authService.getUserById(req.userId)) ?? null) : null,
     }),
@@ -707,6 +626,7 @@ export async function createCoreServer(
     core.pluginJoinRequestJobs,
     core.pluginProvisionService,
     async (req) => (req.userId ? ((await core.authService.getUserById(req.userId)) ?? null) : null),
+    core.kb,
     core.pluginLinksService,
     core.pluginRenameService,
   ));
@@ -716,7 +636,7 @@ export async function createCoreServer(
   app.use(
     '/api',
     core.authMiddleware,
-    createTeamsRoutes(core.accessControl, core.pluginIndexService, core.skillService, core.toolManualService),
+    createTeamsRoutes(core.accessControl, core.pluginIndexService, core.skillService, core.toolManualService, core.kb),
   );
   // Admin-status resolver (CORE — see the note in admin-access.routes.ts;
   // the full admin router is an enterprise `ext.authed` extension).
@@ -768,6 +688,7 @@ export async function createCoreServer(
       core.settings,
       core.adminAccess,
       core.kbStartupRunner,
+      core.kb,
       {
         // Same address family as the MCP endpoint above, userinfo stripped for
         // the same reason: this string is handed to admins to paste elsewhere.