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

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

@@ -2,14 +2,16 @@ import path from 'node:path';
 import { logger } from '../shared/logging.js';
 import type { AuthProviderPlugin } from '../modules/auth/auth.routes.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import {
-  DEFAULT_BRANCH,
-  configureBranchModel,
-  validateBranchModel,
-  PROTECTED_BRANCHES,
-  configureKbLayout,
-} from '@bevel-software/platform-shared';
-import { CoreConfig } from '../core-config.js';
+// The browser-side live bindings, imported here and nowhere else in this
+// package: `mirrorSharedBindings` below keeps them in step with `kb` for an
+// overlay that still reads them. Core's own modules read only `KbContext`.
+// eslint-disable-next-line no-restricted-imports
+import { configureBranchModel, configureKbLayout } from '@bevel-software/platform-shared';
+import type { TenantConfig } from '../core-config.js';
+import { sql } from 'drizzle-orm';
+import { DEFAULT_DB_SCHEMA, assertSearchPath } from '../modules/database/connection.js';
+import { DEFAULT_SECRETS_SCOPE } from '../modules/secrets-vault/secrets-variable-loader.js';
+import { KbContext } from '../shared/kb-context.js';
 import { getDb, type Database } from '../modules/database/connection.js';
 import { runCoreMigrations } from '../modules/database/migrate.js';
 import { coreMigrationsDir } from '../assets.js';
@@ -28,7 +30,7 @@ import { KbSyncService } from '../modules/kb-sync/kb-sync.service.js';
 import { NodeFs } from '../modules/kb-fs/node-fs.js';
 import { assertKbDirNameFree } from '../modules/kb-fs/repo-path.js';
 import type { IFsProbe, ITreeWalker } from '../shared/fs.contract.js';
-import type { IGitRunner } from '../shared/git.contract.js';
+import { gitCredentials, type IGitRunner } from '../shared/git.contract.js';
 import { AdvisoryLease, AdvisoryLock } from '../modules/database/advisory-lock.js';
 import { holdCommitWorkerLease, withStartupTask, type LeaseLoopHandle } from './lifecycle.js';
 
@@ -155,7 +157,7 @@ import { registerCatalogCacheInvalidation } from './catalog-cache-invalidation.j
  * core services to construct). See {@link CorePorts} for the pattern.
  */
 export interface CoreServices {
-  config: CoreConfig;
+  config: TenantConfig;
   db: Database;
   /**
    * Reading the disk without locks — the one tree walk and the one path
@@ -184,6 +186,20 @@ export interface CoreServices {
    * first-time setup completion — and never again while the process serves.
    */
   kbStartupRunner: KbStartupRunner;
+  /**
+   * The startup phase's retry when the boot survived an unreachable remote
+   * — set by `startCore`, stopped by `stopCore` (see `core/lifecycle.ts`);
+   * null while nothing is asking.
+   */
+  startupRetry: { stop(): void } | null;
+  /**
+   * What tells this graph's locks, migration ledger and secrets scope apart
+   * from another graph's in the same process and database: the schema name,
+   * or `''` for the default schema (the single-tenant ids).
+   */
+  tenantKey: string;
+  /** The scope this graph's vault is registered under with the UTCP variable loader. */
+  secretsScope: string;
   spillStore: SpillStore;
   docExtractService: DocExtractService;
   accessControl: AccessControlService;
@@ -264,12 +280,20 @@ export interface CoreServices {
   updateCheckService: UpdateCheckService;
   /** Deployment settings, env-first — the KB remote resolves through these. */
   settings: DeploymentSettingsService;
+  /**
+   * The knowledge base as this composition names it: the checkout folder,
+   * the branch model and the layout — the one object every core service reads
+   * those from (see `shared/kb-context.ts`). The setup-completing save applies
+   * the branch model and the layout to it, so an overlay reads the answer in
+   * effect here rather than from the shared package's live bindings.
+   */
+  kb: KbContext;
   /**
    * The knowledge-base directory name IN EFFECT — environment first, then the
    * stored setting, then the default. Published here because `config.kbDirName`
    * is only the environment's half of that answer: reading it directly gives
    * the empty string on any deployment configured through the setup screen, and
-   * every path built from it would be wrong.
+   * every path built from it would be wrong. The same value as `kb.kbDirName`.
    */
   kbDirName: string;
   secretsVaultService: DbSecretsVaultService;
@@ -301,14 +325,28 @@ export interface CoreServices {
 }
 
 export async function createCoreServices(
-  config: CoreConfig,
+  config: TenantConfig,
   ports: CorePorts = {},
 ): Promise<CoreServices> {
   // Fail fast on a runtime whose git is too old for `--no-write-fetch-head`
   // (see `git-version.ts`): every clone, fetch and refresh below depends on it,
   // so an unsupported binary is better surfaced here than at the first merge.
   await assertGitVersion();
-  const db = getDb(config.databaseUrl);
+  // What tells this knowledge base's locks, migration ledger and secrets
+  // loader apart from another's in the same process and database. Empty for
+  // the default schema, so a single-tenant deployment keeps the lock ids and
+  // the ledger it always had.
+  const tenantKey = config.dbSchema === DEFAULT_DB_SCHEMA ? '' : config.dbSchema;
+  const db = getDb(config.databaseUrl, { schema: config.dbSchema });
+  // A schema of its own is created on first use, so a tenant's first
+  // activation needs nothing done by hand; `public` always exists. Then the
+  // server is asked whether the connections really search that schema: a
+  // pooler that dropped the startup parameter would otherwise land every
+  // tenant's tables in `public`, silently — see `assertSearchPath`.
+  if (tenantKey) {
+    await db.execute(sql.raw(`create schema if not exists "${config.dbSchema}"`));
+    await assertSearchPath(db, config.dbSchema);
+  }
   // Migrations must run BEFORE any service that reads or writes a managed
   // table. `PendingCommitsService.startupReconcile` (called later in this
   // function) hits `pending_commits` — on a fresh DB, deferring migrations to
@@ -325,40 +363,13 @@ export async function createCoreServices(
   // is resolved through them, and a fresh install has none of it in the
   // environment. `load()` is env-first, so an existing deployment sees exactly
   // what it saw before — a stored row only answers where a variable is silent.
-  const settings = new DeploymentSettingsService(db, config.secretsEncKey);
+  const settings = new DeploymentSettingsService(db, config.secretsEncKey, undefined, { env: config.settingsEnv });
   await settings.load();
 
-  /**
-   * The branch model, before anything reads it. It used to be applied at import
-   * time from the environment, which is what forced the frontend to bake it
-   * into its bundle; it now comes through the settings store like the rest of
-   * the deployment's configuration (environment first, as always).
-   *
-   * UNCONFIGURED IS ALLOWED, and that is the point: a fresh deployment has no
-   * branch model, and refusing to boot would take away the setup screen where
-   * one gets entered. What reads it before then is the setup path itself, which
-   * does not need it — the bootstrap admin is recognised without a workspace.
-   * `isComplete` keeps the rest of the app behind the gate until it is set, and
-   * the setting is restart-to-apply because services take the value at
-   * construction.
-   */
-  const branchModel = {
-    defaultBranch: settings.resolve('defaultBranch'),
-    protectedBranches: settings.resolve('protectedBranches'),
-  };
-  if (!validateBranchModel(branchModel)) configureBranchModel(branchModel);
   // The layout variables that were retired this release, folded into their
   // saved settings before anything reads the layout — so the boot that imports
   // them also RUNS on the imported names rather than on the defaults.
   await settings.importLegacyLayoutEnv();
-  // The KB layout — the three renameable roots and the agent guide's file name
-  // — applied the same way and at the same moment, before any service captures
-  // one of them. Unlike the branch model it always resolves (every name has a
-  // default), so an invalid value is a real misconfiguration and stops the boot.
-  configureKbLayout(settings.resolveKbLayout());
-  // A token supplied through the setup screen has to reach the credential
-  // helper, which reads `$GITHUB_TOKEN` at call time.
-  settings.syncGitTokenEnv();
 
   // `kbDirName` is read ONCE and threaded into a dozen services as a plain
   // string, which is why changing it needs a restart (the setting says so).
@@ -370,19 +381,73 @@ export async function createCoreServices(
   // unnameable. Both are operator settings, so the collision is refused here,
   // by name, before any service captures either.
   assertKbDirNameFree(kbDirName, settings.resolveKbLayout());
+  /**
+   * The knowledge base's context — the checkout folder, the branch model and
+   * the layout — built before any service, and handed to each one that reads
+   * a name from it (see `shared/kb-context.ts`). The values come through the
+   * settings store like the rest of the deployment's configuration
+   * (environment first, as always).
+   *
+   * The branch model: UNCONFIGURED IS ALLOWED, and that is the point. A fresh
+   * deployment has no branch model, and refusing to boot would take away the
+   * setup screen where one gets entered. What reads it before then is the
+   * setup path itself, which does not need it — the bootstrap admin is
+   * recognised without a workspace. `isComplete` keeps the rest of the app
+   * behind the gate until it is set, and the save that completes setup applies
+   * it to this very object, which every service reads at use rather than
+   * capturing at construction.
+   *
+   * The layout — the three renameable roots and the agent guide's file name —
+   * always resolves (every name has a default), so an invalid value is a real
+   * misconfiguration and stops the boot.
+   */
+  const kb = new KbContext(
+    kbDirName,
+    KbContext.branchModelOrUnconfigured({
+      defaultBranch: settings.resolve('defaultBranch'),
+      protectedBranches: settings.resolve('protectedBranches'),
+    }),
+    settings.resolveKbLayout(),
+  );
+  // The shared package's process-wide live bindings, kept in step with `kb`
+  // for an overlay that still reads them — now, and again when the setup-
+  // completing save applies a model or a layout. Nothing in this package
+  // reads them; a host serving several knowledge bases turns this off.
+  if (ports.mirrorSharedBindings !== false) {
+    const mirrorBranchModel = () => {
+      if (kb.isBranchModelConfigured()) {
+        configureBranchModel({ defaultBranch: kb.defaultBranch, protectedBranches: [...kb.protectedBranches] });
+      }
+    };
+    const mirrorLayout = () => configureKbLayout(kb.layout);
+    mirrorBranchModel();
+    mirrorLayout();
+    kb.onBranchModelApplied(mirrorBranchModel);
+    kb.onLayoutApplied(mirrorLayout);
+  }
   // The disk: one walk, one probe, for every reader below.
   const disk = new NodeFs();
+  // What git authenticates with, read on every call: the username and token
+  // the setup screen stored, or the environment's. Environment first for the
+  // token, as for every setting (`resolve` is env-first); the legacy
+  // `GITHUB_TOKEN` / `GH_TOKEN` spellings only through `config`, since the
+  // settings catalogue knows `GIT_TOKEN` alone. Handed to the runner, which
+  // puts the token into each child's environment — never into this
+  // process's, which several knowledge bases may share.
+  const gitCredentialsInEffect = gitCredentials(
+    () => settings.resolve('gitUsername') || config.gitUsername,
+    () => settings.resolve('gitToken') || config.gitToken || null,
+  );
   // How git is run, for every module that runs it: one environment, one buffer
   // ceiling, one error shape, and — the reason it exists — one deadline, so a
   // git that never returns cannot hold a workspace (and with it the commit
   // queue) open indefinitely. See `shared/git.contract.ts`.
-  const gitRunner = new NodeGitRunner(config.gitTimeoutMs);
+  const gitRunner = new NodeGitRunner(config.gitTimeoutMs, gitCredentialsInEffect);
   const workspaceService = new WorkspaceService(
     config.workspacesRoot,
     () => settings.resolve('kbRepoUrl'),
-    kbDirName,
+    kb,
     disk,
-    () => settings.resolve('gitUsername') || 'x-access-token',
     gitRunner,
   );
   // The KB startup phase: every seeding, scaffolding and migration concern,
@@ -400,18 +465,18 @@ export async function createCoreServices(
     // read-only, needs no remote, and must be said even on a deployment whose
     // setup never finished — so `noteBesideCheckout` runs once from the server
     // builder, ahead of this gated phase.)
-    new GroupsToPluginsStep(disk),
-    new PluginManifestsStep(disk),
+    new GroupsToPluginsStep(disk, kb),
+    new PluginManifestsStep(disk, kb),
     // After the manifests step: a folder that only just got its manifest got
     // one the renderer wrote, which already carries the display name — the
     // backfill then has nothing to do for it. Ordered the other way, the
     // backfill would walk a tree still missing those manifests.
-    new PluginDisplayNamesStep(disk),
-    new PersonalSpacesStep(disk),
+    new PluginDisplayNamesStep(disk, kb),
+    new PersonalSpacesStep(disk, kb),
     // A getter, not a value: the step is built here, while the process may
     // still hold the defaults, and the save that completes first-run setup
     // applies the admin's answer afterwards.
-    new TemplateFilesStep(disk, extraDirs, () => settings.resolveAgentsFileLink()),
+    new TemplateFilesStep(disk, kb, extraDirs, () => settings.resolveAgentsFileLink()),
     new RolesYamlStep(disk, [config.adminEmail]),
     ...(ports.kbStartupSteps ?? []),
   ];
@@ -420,18 +485,16 @@ export async function createCoreServices(
     // setup screen after this object exists, and the setup-completion run is
     // the first thing that needs them.
     kbRepoUrl: () => settings.resolve('kbRepoUrl'),
-    gitUsername: () => settings.resolve('gitUsername') || 'x-access-token',
-    gitToken: () => settings.resolve('gitToken'),
     workspacesRoot: config.workspacesRoot,
     kbDirName,
     templateDir: config.kbTemplateDir,
-    defaultBranch: () => DEFAULT_BRANCH,
-    protectedBranches: () => [...PROTECTED_BRANCHES],
+    defaultBranch: () => kb.defaultBranch,
+    protectedBranches: () => [...kb.protectedBranches],
     // The deployment owner is the initial Admin of a freshly seeded KB — the
     // same answer `SEED_ADMIN_EMAILS` used to ask for a second time.
     seedAdminEmails: [config.adminEmail],
     steps: kbStartupSteps,
-    buildSeedTree: buildSeedTree(disk, config.kbTemplateDir, extraDirs, [config.adminEmail]),
+    buildSeedTree: buildSeedTree(disk, config.kbTemplateDir, extraDirs, [config.adminEmail], kb),
     gitRunner,
   });
   // Shared, workspace-independent store for oversized `call_tool_chain` results,
@@ -452,49 +515,50 @@ export async function createCoreServices(
     disk,
     [config.adminEmail],
     gitRunner,
+    kb,
   );
   // Creator read-grant on creation: read is default-deny and the roots grant
   // it to nobody, so every surface that starts a new folder at a root (human
   // routes, agent tools, upload apply) consults this planner to keep the new
   // folder visible to its creator.
-  const creatorAccess = new CreatorAccessService(workspaceService, accessControl, kbDirName, disk);
+  const creatorAccess = new CreatorAccessService(workspaceService, accessControl, kb, disk);
   // Read-before-write: the gate every lock acquire asks, on every branch —
   // nothing is created, changed or removed where its author cannot read,
   // except that new folder at a root (see `access-model/change-gate.ts`).
-  const changeGate = new ChangeReadGate(workspaceService, accessControl, kbDirName, disk);
+  const changeGate = new ChangeReadGate(workspaceService, accessControl, kb, disk);
 
   // Ontology-session boundary: records each agent run's touched ontologies and
   // blocks writes once a run has crossed ontologies. Postgres-backed so the
   // boundary survives a restart.
-  const sessionOntologyService = new SessionOntologyService(db);
+  const sessionOntologyService = new SessionOntologyService(db, kb);
   // Per-run write restriction (by file extension). Shared by the workspace tool
   // surface (which enforces it) and the routine runner (which sets it for
   // dashboard-only `watchlist_check` runs). In-memory: a restriction lives only for
   // one run, unlike the Postgres-backed ontology touched-set above.
   const routineWritePolicy = new RoutineWritePolicyService();
   // Skills: discovered from the default-branch workspace only (global catalog).
-  const skillService = new SkillService(workspaceService, accessControl, kbDirName, disk);
+  const skillService = new SkillService(workspaceService, accessControl, kb, disk);
   // Tool manuals: user-authored `*.tool` files under `Plugins/` in the default
   // branch — access-controlled like Skills, served to external agents via
   // `GET /api/agent/all-tools` and registered on the MCP proxy's UTCP client.
   // Where plugins come from: one walk of the plugins root that reads every
   // plugin folder in whichever file shape it carries (see
   // modules/plugins/discovery). Nothing to configure, nothing to document.
-  const pluginSource = new KbPluginSource(disk);
-  const toolManualService = new ToolManualService(workspaceService, accessControl, kbDirName, disk, pluginSource);
+  const pluginSource = new KbPluginSource(disk, kb);
+  const toolManualService = new ToolManualService(workspaceService, accessControl, kb, disk, pluginSource);
   // Plugins: the folders under `Plugins/` that carry a
   // team's skills AND the tools they need. Enumerated for EVERY authenticated
   // caller — a plugin they cannot read still exists for them, as a locked one —
   // with the counts read off the two catalogs above rather than a second scan.
   // The link index resolves manifests against the released catalog, and the
   // plugin index counts through it (inline + linked), so it comes first.
-  const pluginLinkIndex = new PluginLinkIndex(workspaceService, skillService, accessControl, kbDirName, pluginSource);
+  const pluginLinkIndex = new PluginLinkIndex(workspaceService, skillService, accessControl, kb, pluginSource);
   const pluginIndexService = new PluginIndexService(
     workspaceService,
     accessControl,
     skillService,
     toolManualService,
-    kbDirName,
+    kb,
     pluginSource,
     Date.now,
     pluginLinkIndex,
@@ -504,13 +568,17 @@ export async function createCoreServices(
   // PullRequestService no longer depends on it for attribution.)
   // The allow-list is resolved, not read off the environment: it is settable
   // from the setup screen alongside the SSO configuration it guards.
-  const authService = new AuthService(db, {
-    jwtSecret: config.jwtSecret,
-    adminEmail: config.adminEmail,
-    adminPassword: config.adminPassword,
-    allowedEmailDomains: parseDomainList(settings.resolve('allowedEmailDomains')),
-    loginPasswordEnabled: config.loginPasswordEnabled,
-  });
+  const authService = new AuthService(
+    db,
+    {
+      jwtSecret: config.jwtSecret,
+      adminEmail: config.adminEmail,
+      adminPassword: config.adminPassword,
+      allowedEmailDomains: parseDomainList(settings.resolve('allowedEmailDomains')),
+      loginPasswordEnabled: config.loginPasswordEnabled,
+    },
+    ports.accountAdmission,
+  );
   const authMiddleware = createAuthMiddleware(authService);
 
   // Shared mutex so git and diff operations on the same workspace serialize
@@ -526,7 +594,7 @@ export async function createCoreServices(
   const gitService = new GitService(
     workspaceService,
     workflowHooks,
-    kbDirName,
+    kb,
     workspaceMutex,
     accessControl,
     gitRunner,
@@ -611,7 +679,7 @@ export async function createCoreServices(
     accessControl,
     fileLockService,
     pendingCommitsService,
-    kbDirName,
+    kb,
     changeGate,
     eventBus,
     fileChangeNotifier,
@@ -625,7 +693,7 @@ export async function createCoreServices(
   // (the request's branch vs the default branch), so it holds no state — it
   // only needs to read files at refs and to close a request whose proposals
   // have all landed.
-  const joinRequestsService = new JoinRequestsService(workspaceService, workflowService);
+  const joinRequestsService = new JoinRequestsService(workspaceService, workflowService, kb);
   // The OTHER half of a join request: the row the subscribe endpoint writes
   // before it answers, and the branch/clone/commit/push/change-request work
   // that runs against it afterwards. The row is what lets the click be
@@ -634,7 +702,7 @@ export async function createCoreServices(
   const pluginJoinRequestJobs = new PluginJoinRequestJobs(new DbJoinRequestStore(db), {
     workflow: workflowService,
     workspaceService,
-    kbDirName,
+    kb,
     // A record keys on the plugin's primary FOLDER below the root, which the
     // catalog is the only thing that can turn back into a path and a name
     // people read. Null once nothing answers to the key — a deleted plugin,
@@ -666,7 +734,7 @@ export async function createCoreServices(
     accessControl,
     skillService,
     pluginLinkIndex,
-    kbDirName,
+    kb,
     eventBus,
     () => pluginIndexService.invalidate(),
   );
@@ -678,7 +746,7 @@ export async function createCoreServices(
     accessControl,
     pluginSource,
     disk,
-    kbDirName,
+    kb,
     eventBus,
     () => {
       pluginIndexService.invalidate();
@@ -692,7 +760,7 @@ export async function createCoreServices(
     accessControl,
     skillService,
     pluginLinkIndex,
-    kbDirName,
+    kb,
     {
       name: 'hexis',
       owner: 'Hexis',
@@ -727,7 +795,7 @@ export async function createCoreServices(
     workflowService,
     accessControl,
     toolManualService,
-    kbDirName,
+    kb,
     disk,
   );
 
@@ -739,7 +807,7 @@ export async function createCoreServices(
     workspaceService,
     workflowService,
     accessControl,
-    kbDirName,
+    kb,
     eventBus,
     pluginSource,
     disk,
@@ -755,6 +823,7 @@ export async function createCoreServices(
     accessControl,
     skillService,
     workflowService,
+    kb,
   );
 
   // The same missing half, for tools: a `.tool` manual or an `mcp.json` server
@@ -766,6 +835,7 @@ export async function createCoreServices(
     accessControl,
     toolManualService,
     workflowService,
+    kb,
   );
 
   // Catalog freshness: the skill / tool-manual / plugin-index caches all scan
@@ -777,7 +847,7 @@ export async function createCoreServices(
   registerCatalogCacheInvalidation({
     eventBus,
     fileChangeNotifier,
-    kbDirName,
+    kb,
     catalogs: [toolManualService, skillService, pluginIndexService, pluginLinkIndex],
     accessControl,
   });
@@ -787,7 +857,7 @@ export async function createCoreServices(
   const adminAccess = new AdminAccessService(
     accessControl,
     workspaceService,
-    () => DEFAULT_BRANCH,
+    () => kb.defaultBranch,
     // The deployment owner administers accounts/roles even before the KB's
     // roles.yaml lists them, and whatever the sign-in method — this list is
     // consulted before any roles.yaml lookup, so it holds for SSO too.
@@ -818,8 +888,11 @@ export async function createCoreServices(
     (key) => toolManualService.scopeOfVariable(key),
   );
   // Register the `bevel-secrets` UTCP variable loader against this vault so any
-  // UTCP client can resolve `${VAR}` from the caller's secrets at tool-call time.
-  registerBevelSecretsVariableLoader(secretsVaultService);
+  // UTCP client can resolve `${VAR}` from the caller's secrets at tool-call
+  // time — under this knowledge base's scope, since the loader registry is
+  // UTCP's and process-wide while the vault is this graph's.
+  const secretsScope = tenantKey ? `${config.tenantId}/${config.dbSchema}` : DEFAULT_SECRETS_SCOPE;
+  registerBevelSecretsVariableLoader(secretsVaultService, secretsScope);
 
   // Deleting ONE tool from its page — the owner's verb, the other end of the
   // promise that made them the owner. Built here because it is the one service
@@ -835,7 +908,7 @@ export async function createCoreServices(
     pluginIndexService,
     pluginSource,
     secretsVaultService,
-    kbDirName,
+    kb,
     disk,
   );
 
@@ -845,7 +918,7 @@ export async function createCoreServices(
   // call, the vault to resolve the credential to call it with. Holds no state
   // and takes no `db`: a verdict is returned to the caller that asked for it and
   // never outlives their page (see `ProbeVerdict`).
-  const connectionProbeService = new ConnectionProbeService(toolManualService, secretsVaultService);
+  const connectionProbeService = new ConnectionProbeService(toolManualService, secretsVaultService, secretsScope);
 
   // Zero-config OAuth for bare `type: mcp` `.tool`s: when the remote server
   // demands OAuth (MCP authorization spec), discover its authorization server,
@@ -917,7 +990,7 @@ export async function createCoreServices(
   // for readers, and the preamble is a broadcast). One reader, two consumers:
   // the proxy below composes in-process per request; the agent-facing route
   // serves the same composition to the local bridge and the frontend card.
-  const readPreamble: AgentPreambleReader = () => readAgentPreamble(workspaceService, kbDirName, disk);
+  const readPreamble: AgentPreambleReader = () => readAgentPreamble(workspaceService, kb, disk);
   // The Audit log. Records through the proxy below (every call an external
   // agent makes), reads keys through the key service so their shape is
   // defined once, and prunes past the retention setting — read per sweep, so
@@ -930,7 +1003,7 @@ export async function createCoreServices(
       // Loopback to our own REST tool surface — 127.0.0.1 (not localhost) to pin
       // IPv4 and dodge resolver ambiguity. The proxy authenticates each call with
       // the caller's own connection key.
-      loopbackBaseUrl: `http://127.0.0.1:${config.port}`,
+      loopbackBaseUrl: config.loopbackBaseUrl ?? `http://127.0.0.1:${config.port}`,
       // Manual namespace + UTCP variable prefix (KNOWLEDGE_BASE_API_URL / …).
       manualName: 'KNOWLEDGE_BASE',
       // Oversized chain results spill here too — an external MCP caller has no
@@ -939,6 +1012,7 @@ export async function createCoreServices(
       // For the needs-authorization setup link surfaced to external agents.
       publicFrontendUrl: config.publicFrontendUrl,
       readAgentPreamble: readPreamble,
+      secretsScope,
     },
     // Pre-dispatch per-user credential check: the vault answers "has this caller
     // set it?" and the manual catalog answers "which user-scoped vars does this
@@ -1060,12 +1134,6 @@ export async function createCoreServices(
     },
   });
   const leased = withStartupTask(pendingCommitsWorker, reconcileQueue);
-  // Not `start()`: the worker runs only while this process holds the
-  // commit-worker lease. On a redeploy the outgoing container still holds it,
-  // so this one serves requests and declines to drain until that one exits;
-  // then it takes the lease and starts. Two processes draining one shared
-  // clone volume is the failure this prevents — see `core/lifecycle.ts`.
-  const commitWorker = holdCommitWorkerLease(new AdvisoryLease(db, AdvisoryLock.CommitWorker), leased);
 
   // SSO providers. The array REFERENCE is shared with the caller's port — an
   // overlay pushes its own plugins into it after construction (they mount when
@@ -1112,7 +1180,7 @@ export async function createCoreServices(
         eventBus,
         kbDirName,
         bot,
-        defaultBranchOf: () => DEFAULT_BRANCH,
+        defaultBranchOf: () => kb.defaultBranch,
       }),
       debounceMs: opts?.debounceMs,
       log: opts?.log ?? ((message) => logger('directory-sync').warn(message)),
@@ -1126,7 +1194,7 @@ export async function createCoreServices(
     workflowService,
     accessControl,
     kbDirName,
-    () => DEFAULT_BRANCH,
+    () => kb.defaultBranch,
     eventBus,
   );
   // Account deletion's optional half: the erased address out of roles.yaml,
@@ -1138,22 +1206,39 @@ export async function createCoreServices(
     accessControl,
     disk,
     kbDirName,
-    () => DEFAULT_BRANCH,
+    () => kb.defaultBranch,
     eventBus,
     [config.adminEmail],
   );
 
+  // THE LAST THING STARTED, once everything above is built: the lease loop
+  // is the one piece of this function that keeps running on its own, and a
+  // throw anywhere after it would leave a loop holding — or forever asking
+  // for — this knowledge base's lock with no graph to stop it. Single-tenant
+  // never noticed (the process exited with the throw); a host that retries
+  // an activation would. Not `start()`: the worker runs only while this
+  // process holds the commit-worker lease. On a redeploy the outgoing
+  // container still holds it, so this one serves requests and declines to
+  // drain until that one exits; then it takes the lease and starts. Two
+  // processes draining one shared clone volume is the failure this prevents
+  // — see `core/lifecycle.ts`.
+  const commitWorker = holdCommitWorkerLease(new AdvisoryLease(db, AdvisoryLock.CommitWorker, { tenantKey }), leased);
+
   return {
     config,
     db,
     gitRunner,
     commitWorker,
+    startupRetry: null,
+    tenantKey,
+    secretsScope,
     disk,
     mcpServerEditService,
     toolDeleteService,
     workspaceService,
     kbStartupRunner,
     settings,
+    kb,
     kbDirName,
     spillStore,
     docExtractService,