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

package/dist/core/create-core-services.js

@@ -1,6 +1,14 @@
 import path from 'node:path';
 import { logger } from '../shared/logging.js';
-import { DEFAULT_BRANCH, configureBranchModel, validateBranchModel, PROTECTED_BRANCHES, configureKbLayout, } from '@bevel-software/platform-shared';
+// 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 { 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 } from '../modules/database/connection.js';
 import { runCoreMigrations } from '../modules/database/migrate.js';
 import { coreMigrationsDir } from '../assets.js';
@@ -18,6 +26,9 @@ import { DeploymentSettingsService } from '../modules/settings/deployment-settin
 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 { ManagedRepository, MANAGED_DEFAULT_BRANCH } from '../modules/settings/managed-repository.js';
+import { RepositorySource } from '../modules/settings/repository-source.js';
+import { GitHubAppConnection } from '../modules/github-app/index.js';
 import { AdvisoryLease, AdvisoryLock } from '../modules/database/advisory-lock.js';
 import { holdCommitWorkerLease, withStartupTask } from './lifecycle.js';
 /** The hosted MCP endpoint at a deployment address, with any userinfo stripped. */
@@ -98,7 +109,21 @@ export async function createCoreServices(config, ports = {}) {
     // (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
@@ -114,40 +139,12 @@ export async function createCoreServices(config, ports = {}) {
     // 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).
     // The remote URL and username are read per-operation instead, so an admin
@@ -158,14 +155,96 @@ export async function createCoreServices(config, ports = {}) {
     // 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.
+    //
+    // Both come from the repository source, which is the one place that knows
+    // a deployment can be given its repository in more than one way; what
+    // comes back is the address and the credential, as it always was.
+    const managedRepository = new ManagedRepository(path.join(config.backupsRoot, 'managed-repository'));
+    const githubApp = new GitHubAppConnection({
+        read: (key) => settings.resolve(key),
+        sourceOf: (key) => settings.sourceOf(key),
+    });
+    const repositorySource = new RepositorySource({
+        read: (key) => settings.resolve(key),
+        fallback: { username: config.gitUsername, token: config.gitToken },
+        managed: managedRepository,
+        githubApp,
+    });
+    const gitCredentialsInEffect = repositorySource.credentials;
     // 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 workspaceService = new WorkspaceService(config.workspacesRoot, () => settings.resolve('kbRepoUrl'), kbDirName, disk, () => settings.resolve('gitUsername') || 'x-access-token', gitRunner);
+    const gitRunner = new NodeGitRunner(config.gitTimeoutMs, gitCredentialsInEffect);
+    // A deployment that keeps its own repository has it before anything asks
+    // for it: one that chose the mode through the environment never passes
+    // through the save that would have created it, and the startup phase's
+    // first question would be asked of a folder that is not there. Left to
+    // that phase to report if it cannot be made: its failures are classified
+    // and shown on the setup screen, where a throw here would take the screen
+    // down with the boot.
+    if (repositorySource.mode() === 'managed') {
+        await managedRepository
+            .ensure(gitRunner, settings.resolve('defaultBranch') || MANAGED_DEFAULT_BRANCH)
+            .catch((err) => logger('setup').error('the managed repository could not be created:', { err }));
+    }
+    // One reached through a GitHub App has a token in hand before anything
+    // reads it: a working copy's credential helper is stamped according to
+    // whether there is a token, by code that cannot wait for one. A failure is
+    // the startup phase's to report, for the same reason as above.
+    if (repositorySource.mode() === 'github-app') {
+        await githubApp.prepare().catch(() => undefined);
+    }
+    const workspaceService = new WorkspaceService(config.workspacesRoot, () => repositorySource.url(), kb, disk, gitRunner);
     // The KB startup phase: every seeding, scaffolding and migration concern,
     // run through one runner at the deployment's quiet moments (boot + setup
     // completion) instead of lazily on branch loads. Root folders this
@@ -181,18 +260,18 @@ export async function createCoreServices(config, ports = {}) {
         // 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 ?? []),
     ];
@@ -200,19 +279,21 @@ export async function createCoreServices(config, ports = {}) {
         // Getters, not values: the remote and the branch model can arrive from the
         // 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'),
+        kbRepoUrl: () => repositorySource.url(),
         workspacesRoot: config.workspacesRoot,
+        // Under the backups root, a persistent volume of its own and one nothing
+        // sweeps: a working copy of a repository that was replaced is kept there,
+        // never deleted (see the runner's `reconcileClonesWithConfiguredRepository`).
+        setAsideRoot: path.join(config.backupsRoot, 'replaced-working-copies'),
         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,
@@ -227,43 +308,43 @@ export async function createCoreServices(config, ports = {}) {
     // gate cannot disagree about who the owner is. They did: the owner could
     // open App roles and then be refused the save, with the UI showing
     // them as an admin and the gate saying "Eligible: Admin".
-    const accessControl = new AccessControlService(workspaceService, kbDirName, disk, [config.adminEmail], gitRunner);
+    const accessControl = new AccessControlService(workspaceService, kbDirName, 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 pluginIndexService = new PluginIndexService(workspaceService, accessControl, skillService, toolManualService, kbDirName, pluginSource, Date.now, pluginLinkIndex);
+    const pluginLinkIndex = new PluginLinkIndex(workspaceService, skillService, accessControl, kb, pluginSource);
+    const pluginIndexService = new PluginIndexService(workspaceService, accessControl, skillService, toolManualService, kb, pluginSource, Date.now, pluginLinkIndex);
     // Auth service — resolves identities for login, PR author attribution, and
     // access lookups. (Change requests now store the author email directly, so
     // PullRequestService no longer depends on it for attribution.)
@@ -275,7 +356,7 @@ export async function createCoreServices(config, ports = {}) {
         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
     // against each other — a backup-reseed races a concurrent commit otherwise.
@@ -287,7 +368,7 @@ export async function createCoreServices(config, ports = {}) {
     // this function returns. Core registers none: no commit-time validation
     // (advisory anyway) and no ontology write block.
     const workflowHooks = new WorkflowHooks();
-    const gitService = new GitService(workspaceService, workflowHooks, kbDirName, workspaceMutex, accessControl, gitRunner);
+    const gitService = new GitService(workspaceService, workflowHooks, kb, workspaceMutex, accessControl, gitRunner);
     // `get_skill` with a `version` reads the skill out of the default branch's
     // history; the skill service is built before git exists, so git is handed
     // to it here.
@@ -338,7 +419,7 @@ export async function createCoreServices(config, ports = {}) {
     // id-repair keeps the id namespace collision-free. Subscribers are registered
     // below, once the reacting services exist.
     const fileChangeNotifier = new FileChangeNotifier();
-    const workflowService = new WorkflowService(db, gitService, pullRequestService, reviewWorkflowService, workspaceService, accessControl, fileLockService, pendingCommitsService, kbDirName, changeGate, eventBus, fileChangeNotifier, 
+    const workflowService = new WorkflowService(db, gitService, pullRequestService, reviewWorkflowService, workspaceService, accessControl, fileLockService, pendingCommitsService, kb, changeGate, eventBus, fileChangeNotifier, 
     // Exposed as `workflowService.hooks` — the SAME instance GitService and
     // the session-ontology gate consult, so enterprise registrations against
     // it reach every hook point.
@@ -347,7 +428,10 @@ export async function createCoreServices(config, ports = {}) {
     // (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, 
+    // Read-only: the one question a request asks of the resolver is whether
+    // the person it names already holds what it proposes.
+    accessControl);
     // 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
@@ -356,7 +440,7 @@ export async function createCoreServices(config, ports = {}) {
     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,
@@ -382,16 +466,16 @@ export async function createCoreServices(config, ports = {}) {
     });
     // Links land as ordinary default-branch commits and change what the plugin
     // index counts, so a link drops that cache too.
-    const pluginLinksService = new PluginLinksService(workspaceService, workflowService, accessControl, skillService, pluginLinkIndex, kbDirName, eventBus, () => pluginIndexService.invalidate());
+    const pluginLinksService = new PluginLinksService(workspaceService, workflowService, accessControl, skillService, pluginLinkIndex, kb, eventBus, () => pluginIndexService.invalidate());
     // A rename rewrites grants across the knowledge base in one batch commit,
     // then drops every cache that keyed on the old identity.
-    const pluginRenameService = new PluginRenameService(workspaceService, workflowService, accessControl, pluginSource, disk, kbDirName, eventBus, () => {
+    const pluginRenameService = new PluginRenameService(workspaceService, workflowService, accessControl, pluginSource, disk, kb, eventBus, () => {
         pluginIndexService.invalidate();
         pluginLinkIndex.invalidate();
     });
     // Source → distribution. The marketplace's identity is fixed for now; the
     // per-user git endpoint and any mirror both compile through this.
-    const marketplaceCompiler = new MarketplaceCompilerService(workspaceService, accessControl, skillService, pluginLinkIndex, kbDirName, {
+    const marketplaceCompiler = new MarketplaceCompilerService(workspaceService, accessControl, skillService, pluginLinkIndex, kb, {
         name: 'hexis',
         owner: 'Hexis',
         description: 'Skills and plugins from this knowledge base',
@@ -411,23 +495,23 @@ export async function createCoreServices(config, ports = {}) {
     // spans a plugin's mcp.json AND plugin.json extensions block, and this is
     // the ONE writer that rewrites both entries and commits them together (see
     // McpServerEditService).
-    const mcpServerEditService = new McpServerEditService(workspaceService, workflowService, accessControl, toolManualService, kbDirName, disk);
+    const mcpServerEditService = new McpServerEditService(workspaceService, workflowService, accessControl, toolManualService, kb, disk);
     // Plugin provisioning — the one privileged door that brings `Plugins/<name>/`
     // folders into existence (named plugins and personal folders alike). Commits
     // INLINE through the same pipeline the pending-commits worker uses, so the
     // folder's rules are at HEAD before the endpoint answers.
-    const pluginProvisionService = new PluginProvisionService(workspaceService, workflowService, accessControl, kbDirName, eventBus, pluginSource, disk);
+    const pluginProvisionService = new PluginProvisionService(workspaceService, workflowService, accessControl, kb, eventBus, pluginSource, disk);
     // Pending skills: the other half of the catalog — skills that exist only on
     // an open change request's branch. Built here rather than beside
     // `skillService` because it needs the workflow service, which does not exist
     // that early; it holds no state of its own, so where it is constructed is the
     // only thing the ordering decides.
-    const pendingSkillsService = new PendingSkillsService(workspaceService, accessControl, skillService, workflowService);
+    const pendingSkillsService = new PendingSkillsService(workspaceService, accessControl, skillService, workflowService, kb);
     // The same missing half, for tools: a `.tool` manual or an `mcp.json` server
     // an agent proposes is nowhere in the product until its change request
     // merges. Built here for the same reason — it needs the workflow service —
     // and stateless for the same reason.
-    const pendingToolsService = new PendingToolsService(workspaceService, accessControl, toolManualService, workflowService);
+    const pendingToolsService = new PendingToolsService(workspaceService, accessControl, toolManualService, workflowService, kb);
     // Catalog freshness: the skill / tool-manual / plugin-index caches all scan
     // the DEFAULT branch's working tree, and all three go stale on the same
     // events (a commit, a working-tree write, a merge) — as does the access
@@ -437,13 +521,13 @@ export async function createCoreServices(config, ports = {}) {
     registerCatalogCacheInvalidation({
         eventBus,
         fileChangeNotifier,
-        kbDirName,
+        kb,
         catalogs: [toolManualService, skillService, pluginIndexService, pluginLinkIndex],
         accessControl,
     });
     // Admin = `Admin` role in roles.yaml, resolved through the access model on the
     // default branch (no env allow-list).
-    const adminAccess = new AdminAccessService(accessControl, workspaceService, () => DEFAULT_BRANCH, 
+    const adminAccess = new AdminAccessService(accessControl, workspaceService, () => 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.
@@ -467,21 +551,24 @@ export async function createCoreServices(config, ports = {}) {
     // `resolve` reads the shared (admin) row or the caller's own per-user row.
     (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
     // that spans both halves of a tool: the definition (a `.tool` file or an
     // mcp.json entry) and the credentials stored under its name, which is why it
     // can only exist once the vault does.
-    const toolDeleteService = new ToolDeleteService(workspaceService, workflowService, accessControl, toolManualService, skillService, pluginIndexService, pluginSource, secretsVaultService, kbDirName, disk);
+    const toolDeleteService = new ToolDeleteService(workspaceService, workflowService, accessControl, toolManualService, skillService, pluginIndexService, pluginSource, secretsVaultService, kb, disk);
     // The credential probe: whether a tool's stored credential actually WORKS, as
     // distinct from whether one is stored. Built here — after the vault and the
     // tool catalog — because a probe needs both: the catalog to know what to
     // 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,
     // dynamically register a public PKCE client, and persist the provider as the
@@ -541,7 +628,7 @@ export async function createCoreServices(config, ports = {}) {
     // 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 = () => readAgentPreamble(workspaceService, kbDirName, disk);
+    const readPreamble = () => 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
@@ -551,7 +638,7 @@ export async function createCoreServices(config, ports = {}) {
         // 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
@@ -560,6 +647,7 @@ export async function createCoreServices(config, ports = {}) {
         // 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
@@ -665,12 +753,6 @@ export async function createCoreServices(config, ports = {}) {
         },
     });
     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
     // the server is built, later). Core contributes the generic OIDC provider.
@@ -711,7 +793,7 @@ export async function createCoreServices(config, ports = {}) {
                 eventBus,
                 kbDirName,
                 bot,
-                defaultBranchOf: () => DEFAULT_BRANCH,
+                defaultBranchOf: () => kb.defaultBranch,
             }),
             debounceMs: opts?.debounceMs,
             log: opts?.log ?? ((message) => logger('directory-sync').warn(message)),
@@ -720,22 +802,41 @@ export async function createCoreServices(config, ports = {}) {
     // Groups — the "who you are" principal sets. Manual-mode CRUD on
     // groups.yaml, IdP-mode refusals, and the connect-time retirement the
     // directory token route drives.
-    const groupsAdminService = new GroupsAdminService(workspaceService, workflowService, accessControl, kbDirName, () => DEFAULT_BRANCH, eventBus);
+    const groupsAdminService = new GroupsAdminService(workspaceService, workflowService, accessControl, kbDirName, () => kb.defaultBranch, eventBus);
     // Account deletion's optional half: the erased address out of roles.yaml,
     // groups.yaml and every access rule, in one commit on the default branch.
     // The deployment owner is never removed this way.
-    const userAccessRemovalService = new UserAccessRemovalService(workspaceService, workflowService, accessControl, disk, kbDirName, () => DEFAULT_BRANCH, eventBus, [config.adminEmail]);
+    const userAccessRemovalService = new UserAccessRemovalService(workspaceService, workflowService, accessControl, disk, kbDirName, () => 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,
+        repositorySource,
+        managedRepository,
+        githubApp,
         settings,
+        kb,
         kbDirName,
         spillStore,
         docExtractService,