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

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

@@ -1,4 +1,6 @@
-import { DEFAULT_BRANCH, configureBranchModel, validateBranchModel, PROTECTED_BRANCHES, PLUGINS_DIR, } from '@bevel-software/platform-shared';
+import path from 'node:path';
+import { logger } from '../shared/logging.js';
+import { DEFAULT_BRANCH, configureBranchModel, validateBranchModel, PROTECTED_BRANCHES, configureKbLayout, } from '@bevel-software/platform-shared';
 import { getDb } from '../modules/database/connection.js';
 import { runCoreMigrations } from '../modules/database/migrate.js';
 import { coreMigrationsDir } from '../assets.js';
@@ -6,10 +8,25 @@ import { WorkspaceService } from '../modules/workspace/workspace.service.js';
 import { RoutineWritePolicyService } from '../modules/workspace/routine-write-policy.js';
 import { KbStartupRunner } from '../modules/workspace/startup/kb-startup-runner.js';
 import { GroupsToPluginsStep } from '../modules/workspace/startup/steps/groups-to-plugins.step.js';
+import { PluginDisplayNamesStep } from '../modules/workspace/startup/steps/plugin-display-names.step.js';
+import { PluginManifestsStep } from '../modules/workspace/startup/steps/plugin-manifests.step.js';
+import { PersonalSpacesStep } from '../modules/workspace/startup/steps/personal-spaces.step.js';
 import { TemplateFilesStep } from '../modules/workspace/startup/steps/template-files.step.js';
 import { RolesYamlStep } from '../modules/workspace/startup/steps/roles-yaml.step.js';
 import { buildSeedTree } from '../modules/workspace/startup/steps/seed-tree.js';
 import { DeploymentSettingsService } from '../modules/settings/deployment-settings.service.js';
+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 { 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. */
+function mcpEndpointUrl(publicBackendUrl) {
+    const url = new URL('/api/mcp', publicBackendUrl);
+    url.username = '';
+    url.password = '';
+    return url.toString();
+}
 /** `a.com, b.com` → `['a.com','b.com']`, tolerating a leading `@` or `.`. */
 function parseDomainList(raw) {
     return raw
@@ -22,18 +39,24 @@ import { DocExtractService } from '../modules/workspace/file-readers/doc-extract
 import { UuidSessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
 import { AccountErasureService } from '../modules/auth/account-erasure.service.js';
-import { OidcAuthProvider } from '../modules/auth/oidc-auth-provider.js';
+import { OidcAuthProvider, oidcSettingsFrom } from '../modules/auth/oidc-auth-provider.js';
 import { createAuthMiddleware } from '../modules/auth/auth.middleware.js';
-import { AccessControlService } from '../modules/access/access-control.service.js';
+import { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
 import { CreatorAccessService } from '../modules/access/creator-access.js';
+import { ChangeReadGate } from '../modules/access/change-read-gate.js';
 import { GroupsAdminService } from '../modules/access/groups-admin.service.js';
+import { UserAccessRemovalService } from '../modules/access/user-access-removal.service.js';
 import { PendingSkillsService, SkillService } from '../modules/skills/index.js';
-import { ToolManualService } from '../modules/tool-manuals/index.js';
+import { PendingToolsService, ToolManualService } from '../modules/tool-manuals/index.js';
 import { McpServerEditService } from '../modules/tool-manuals/mcp-server-edit.service.js';
-import { PluginIndexService, PluginProvisionService, JoinRequestsService } from '../modules/plugins/index.js';
+import { ToolDeleteService } from '../modules/tool-manuals/tool-delete.service.js';
+import { PluginIndexService, pluginFolderBelowRoot, PluginProvisionService, JoinRequestsService, PluginJoinRequestJobs, JoinRequestNotReadyError, DbJoinRequestStore, PluginLinkIndex, PluginLinksService, PluginRenameService, MarketplaceCompilerService, KbPluginSource, } from '../modules/plugins/index.js';
+import { MarketplaceRepoService } from '../modules/marketplace/index.js';
+import { GitHubFacadeCredentialsService, GitHubFacade, DbGitHubFacadeCodeStore, DbGitHubFacadeCredentialsStore, CLAUDE_CONSUMER, GITHUB_LINK_KEY_KIND, GITHUB_LINK_KEY_SPEC, } from '../modules/marketplace/github-facade/index.js';
 import { DbSecretsVaultService, McpOAuthDiscoveryService, registerBevelSecretsVariableLoader, } from '../modules/secrets-vault/index.js';
 import { ConnectionProbeService } from '../modules/connection-probe/index.js';
 import { GitService } from '../modules/workflow/git/git.service.js';
+import { NodeGitRunner } from '../modules/workflow/git/node-git-runner.js';
 import { PullRequestService } from '../modules/workflow/git/pull-request.service.js';
 import { WorkspaceMutex } from '../modules/kb-fs/mutex.js';
 import { assertGitVersion } from '../modules/workflow/git/git-version.js';
@@ -56,8 +79,8 @@ import { ExternalApiKeyService } from '../modules/tool-auth/external-api-key.ser
 import { InternalTokenService, deriveInternalTokenSecret, } from '../modules/tool-auth/internal-token.service.js';
 import { createToolAuthMiddleware, createManualAuthMiddleware, } from '../modules/tool-auth/tool-auth.middleware.js';
 import { unmeteredLlmUsage } from '../modules/tool-auth/llm-usage-meter.js';
-import { McpSessionStore } from '../modules/mcp/mcp-session-store.js';
 import { McpService } from '../modules/mcp/mcp.service.js';
+import { readAgentPreamble } from '../modules/agent-instructions/index.js';
 import { createMcpAuthMiddleware } from '../modules/mcp/mcp-auth.middleware.js';
 import { BevelOAuthProvider } from '../modules/mcp/oauth/bevel-oauth-provider.js';
 import { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
@@ -68,6 +91,7 @@ import { TokenCrypto } from '../shared/token-crypto.js';
 import { UpdateCheckService } from '../modules/update-check/update-check.service.js';
 import { resolveAppVersion } from '../version.js';
 import { noopRecoveryAgent } from './core-ports.js';
+import { registerCatalogCacheInvalidation } from './catalog-cache-invalidation.js';
 export async function createCoreServices(config, ports = {}) {
     // 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,
@@ -111,6 +135,15 @@ export async function createCoreServices(config, ports = {}) {
     };
     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();
@@ -119,7 +152,19 @@ export async function createCoreServices(config, ports = {}) {
     // The remote URL and username are read per-operation instead, so an admin
     // finishing setup can clone immediately without bouncing the process.
     const kbDirName = settings.resolve('kbDirName') || 'knowledge-base';
-    const workspaceService = new WorkspaceService(config.workspacesRoot, () => settings.resolve('kbRepoUrl'), kbDirName, () => settings.resolve('gitUsername') || 'x-access-token');
+    // A checkout folder named like one of the repository's own roots would make
+    // every path under that root read as the checkout itself, and the root
+    // unnameable. Both are operator settings, so the collision is refused here,
+    // by name, before any service captures either.
+    assertKbDirNameFree(kbDirName, settings.resolveKbLayout());
+    // The disk: one walk, one probe, for every reader below.
+    const disk = new NodeFs();
+    // 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);
     // 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
@@ -131,9 +176,23 @@ export async function createCoreServices(config, ports = {}) {
     // reshapes trees the template top-up would otherwise re-scaffold — then
     // whatever the distribution appends.
     const kbStartupSteps = [
-        new GroupsToPluginsStep(),
-        new TemplateFilesStep(extraDirs),
-        new RolesYamlStep([config.adminEmail]),
+        // (The note about anything sitting BESIDE a checkout is not a step: it is
+        // 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),
+        // 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),
+        // 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 RolesYamlStep(disk, [config.adminEmail]),
         ...(ports.kbStartupSteps ?? []),
     ];
     const kbStartupRunner = new KbStartupRunner({
@@ -142,6 +201,7 @@ export async function createCoreServices(config, ports = {}) {
         // 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,
@@ -151,7 +211,8 @@ export async function createCoreServices(config, ports = {}) {
         // same answer `SEED_ADMIN_EMAILS` used to ask for a second time.
         seedAdminEmails: [config.adminEmail],
         steps: kbStartupSteps,
-        buildSeedTree: buildSeedTree(config.kbTemplateDir, extraDirs, [config.adminEmail]),
+        buildSeedTree: buildSeedTree(disk, config.kbTemplateDir, extraDirs, [config.adminEmail]),
+        gitRunner,
     });
     // Shared, workspace-independent store for oversized `call_tool_chain` results,
     // read back via `read_file`. Sibling of `workspacesRoot`, never committed.
@@ -163,15 +224,18 @@ export async function createCoreServices(config, ports = {}) {
     // rescues (`roles.yaml` and any `access.md`) — the SAME list
     // `AdminAccessService` below is given, so the admin surfaces and the write
     // gate cannot disagree about who the owner is. They did: the owner could
-    // open Roles & Members and then be refused the save, with the UI showing
+    // 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, [
-        config.adminEmail,
-    ]);
-    // Creator read-grant on creation: read is default-deny, so every surface
-    // that creates KB files/folders (human routes, agent tools, upload apply)
-    // consults this planner to keep creations visible to their creator.
-    const creatorAccess = new CreatorAccessService(workspaceService, accessControl, kbDirName);
+    const accessControl = new AccessControlService(workspaceService, kbDirName, disk, [config.adminEmail], gitRunner);
+    // 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);
+    // 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);
     // 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.
@@ -182,16 +246,23 @@ export async function createCoreServices(config, ports = {}) {
     // 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);
+    const skillService = new SkillService(workspaceService, accessControl, kbDirName, 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.
-    const toolManualService = new ToolManualService(workspaceService, accessControl, kbDirName);
+    // 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);
     // 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.
-    const pluginIndexService = new PluginIndexService(workspaceService, accessControl, skillService, toolManualService, kbDirName);
+    // 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);
     // 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.)
@@ -202,6 +273,7 @@ export async function createCoreServices(config, ports = {}) {
         adminEmail: config.adminEmail,
         adminPassword: config.adminPassword,
         allowedEmailDomains: parseDomainList(settings.resolve('allowedEmailDomains')),
+        loginPasswordEnabled: config.loginPasswordEnabled,
     });
     const authMiddleware = createAuthMiddleware(authService);
     // Shared mutex so git and diff operations on the same workspace serialize
@@ -214,12 +286,20 @@ 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);
+    const gitService = new GitService(workspaceService, workflowHooks, kbDirName, 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.
+    skillService.setHistory(gitService);
     // A fresh clone has already fetched every ref — let the git layer skip the
     // redundant implicit `git fetch` on the first `listBranches` after bootstrap.
     workspaceService.setWorkspaceClonedListener((id) => gitService.noteWorkspaceFetched(id));
-    const pullRequestService = new PullRequestService(db, workspaceService, accessControl, gitService);
-    const diffService = new DiffService(workspaceService, workspaceMutex, config.workspacesRoot, config.backupsRoot, kbDirName);
+    // A branch listing is also the platform's memory of which branch names it
+    // has ever heard of — what tells a deleted branch (410) from one that never
+    // existed (404) when a bootstrap finds no such ref on origin.
+    gitService.setBranchesListedListener((names) => workspaceService.noteBranchesListed(names));
+    const pullRequestService = new PullRequestService(db, workspaceService, accessControl, gitService, config.configuredPublicFrontendUrl);
+    const diffService = new DiffService(workspaceService, workspaceMutex, config.workspacesRoot, config.backupsRoot, kbDirName, disk);
     // Late-bind the diff service into WorkspaceService so file writes/moves
     // trigger backup updates. (GitService used to take a diffService too — for
     // the post-switch backup reseed — but switchBranch is gone with the
@@ -257,7 +337,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, eventBus, fileChangeNotifier, 
+    const workflowService = new WorkflowService(db, gitService, pullRequestService, reviewWorkflowService, workspaceService, accessControl, fileLockService, pendingCommitsService, kbDirName, 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.
@@ -267,60 +347,98 @@ export async function createCoreServices(config, ports = {}) {
     // only needs to read files at refs and to close a request whose proposals
     // have all landed.
     const joinRequestsService = new JoinRequestsService(workspaceService, workflowService);
+    // 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
+    // answered in a database round-trip instead of a clone, and what survives a
+    // restart with the request still owed.
+    const pluginJoinRequestJobs = new PluginJoinRequestJobs(new DbJoinRequestStore(db), {
+        workflow: workflowService,
+        workspaceService,
+        kbDirName,
+        // 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,
+        // a moved folder — which the job records as a failure the requester sees.
+        //
+        // An EMPTY catalog is not that. Discovery degrades to empty whenever it
+        // cannot read the knowledge base — a boot that has not finished cloning,
+        // a remote that blipped — and answering "null" then would tell everyone
+        // with a request outstanding that their plugin is gone, permanently, for
+        // a fault that healed in seconds. A request is only refused when the
+        // catalog has something to say and this key is absent from it; when it
+        // has nothing to say at all, the failure is raised as a transient one, so
+        // the row stays `pending` for the next sweep to retry.
+        target: async (pluginKey) => {
+            const catalog = await pluginIndexService.catalog();
+            if (catalog.length === 0) {
+                throw new JoinRequestNotReadyError('the plugin catalog is not available yet');
+            }
+            const entry = catalog.find((g) => pluginFolderBelowRoot(g.folders[0]) === pluginKey);
+            return entry ? { folder: entry.folders[0], displayName: entry.displayName } : null;
+        },
+        requester: (email) => authService.getUserByEmail(email),
+    });
+    // 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());
+    // 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, () => {
+        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, {
+        name: 'hexis',
+        owner: 'Hexis',
+        description: 'Skills and plugins from this knowledge base',
+        // The knowledge base as a tool, shipped in the skills plugin so an
+        // agent installing from the marketplace can read what its skills refer
+        // to. The same address `/api/config` and the OAuth metadata publish,
+        // userinfo stripped; the client's OAuth flow supplies the identity.
+        knowledgeBaseMcp: { name: 'hexis', url: mcpEndpointUrl(config.publicBackendUrl) },
+    }, pluginSource, disk, gitRunner);
+    // Sibling of the workspaces root, like the spill store: one bare repo, one
+    // git namespace per caller (see marketplace-repo.service.ts).
+    const marketplaceRepo = new MarketplaceRepoService(path.resolve(config.workspacesRoot, '..', 'marketplace.git'), marketplaceCompiler, gitRunner);
+    // Remote sync. Drives the workflow module's per-branch pull-and-announce
+    // over every clone the workspace service knows about; owns no git of its own.
+    const kbSyncService = new KbSyncService(workflowService, workspaceService);
     // Server-scoped MCP editing — the tool page's edit form. One server's truth
     // 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);
+    const mcpServerEditService = new McpServerEditService(workspaceService, workflowService, accessControl, toolManualService, kbDirName, 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);
+    const pluginProvisionService = new PluginProvisionService(workspaceService, workflowService, accessControl, kbDirName, 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);
-    // Subscriber A — catalog freshness: a committed change drops the affected
-    // caches immediately instead of waiting out their TTLs. The tool/skill
-    // catalogs are global but read the DEFAULT branch only, so only
-    // default-branch changes under their folders matter. (The kb-graph id-index
-    // invalidation that used to live in this subscriber is registered by the
-    // enterprise overlay, next to the kb-graph service it belongs to — the
-    // caches are independent, so the split preserves behavior.)
-    fileChangeNotifier.onFilesChanged(({ branch, paths }) => {
-        if (branch !== DEFAULT_BRANCH)
-            return;
-        // Skills, tools and the plugin index all live under `Plugins/`, so one
-        // touch check drives all three caches. An access grant lands as a
-        // default-branch change to `Plugins/<plugin>/access.md`, so this is also
-        // what makes a newly-granted plugin unlock within one round-trip instead
-        // of one TTL.
-        const touched = paths.some((p) => p.startsWith(`${kbDirName}/${PLUGINS_DIR}/`));
-        if (touched) {
-            toolManualService.invalidate();
-            skillService.invalidate();
-            pluginIndexService.invalidate();
-        }
-    });
-    // Subscriber B — WRITE-time freshness for the same three caches. The
-    // workspace routes emit `fs-tree-changed` the moment bytes hit a working
-    // tree; Subscriber A above fires only when the ASYNC commit lands. Between
-    // the two, "create a skill, reload the catalog" raced the commit pipeline
-    // and lost — the new skill's card stayed invisible until a refresh outlived
-    // the TTL. The catalogs scan the working tree anyway, so invalidating at
-    // write time makes the very next read see the file. No path filter: this
-    // event carries none, and a spurious drop only costs one re-scan.
-    eventBus.onEmit((event) => {
-        if (event.kind !== 'fs-tree-changed')
-            return;
-        if (!('branch' in event) || event.branch !== DEFAULT_BRANCH)
-            return;
-        toolManualService.invalidate();
-        skillService.invalidate();
-        pluginIndexService.invalidate();
+    // 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);
+    // 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
+    // model they are filtered through. Wired in one place so a new way of
+    // reaching the default branch cannot refresh two of them and leave the
+    // third serving last minute's answer.
+    registerCatalogCacheInvalidation({
+        eventBus,
+        fileChangeNotifier,
+        kbDirName,
+        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).
@@ -350,6 +468,12 @@ export async function createCoreServices(config, ports = {}) {
     // 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);
+    // 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);
     // 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
@@ -383,44 +507,70 @@ export async function createCoreServices(config, ports = {}) {
     });
     // GDPR erasure path: admin-driven user deletion. The core service erases the
     // rows it owns; each module contributes its slice as a participant.
-    const accountErasureService = new AccountErasureService(db, ports.erasureParticipants ?? []);
+    const accountErasureService = new AccountErasureService(db, reviewWorkflowService, ports.erasureParticipants ?? []);
     // MCP (remote agent access). ExternalApiKeyService handles connection-key
-    // lifecycle; McpSessionStore holds per-session userId in memory
-    // (single-replica — see docs/mcp-remote-access.md). McpService is now a
-    // GENERIC proxy: per session it discovers the UTCP manual at /api/agent/utcp
-    // over loopback and re-exposes every tool, dispatching calls back through the
-    // REST tool surface (so agent logic + metering live there, once).
-    const externalApiKeyService = new ExternalApiKeyService(db, config.externalApiKeyPrefix);
-    const mcpSessionStore = new McpSessionStore();
-    const mcpService = new McpService(mcpSessionStore, {
+    // lifecycle. McpService is a GENERIC, STATELESS proxy: per request it
+    // discovers the caller's catalog at /api/agent/all-tools over loopback and
+    // re-exposes every tool, dispatching calls back through the REST tool
+    // surface (so agent logic + metering live there, once). No MCP session is
+    // kept, so a restart is invisible to connected clients.
+    // Connection keys also come as GitHub-shaped links (`gho_…`, kind
+    // `github-link`): the same key, minted by the marketplace facade below when
+    // a person connects an account on claude.ai, told apart by its stored kind.
+    const externalApiKeyService = new ExternalApiKeyService(db, config.externalApiKeyPrefix, {
+        [GITHUB_LINK_KEY_KIND]: GITHUB_LINK_KEY_SPEC,
+    });
+    // The facade that lets products which sync marketplaces only from a GitHub
+    // Enterprise Server (claude.ai, Cowork) add the per-user marketplace:
+    // generated app credentials an Owner registers once, and the connect flow
+    // that turns a hexis session into a connection key the product holds.
+    // Reuses the MCP flow's signed state and /connect page — see
+    // modules/marketplace/github-facade.
+    const githubFacadeCredentials = new GitHubFacadeCredentialsService(new DbGitHubFacadeCredentialsStore(db, config.secretsEncKey ? new TokenCrypto(config.secretsEncKey) : null));
+    const githubFacade = new GitHubFacade({
+        credentials: githubFacadeCredentials,
+        codes: new DbGitHubFacadeCodeStore(db),
+        keys: externalApiKeyService,
+        consumers: [CLAUDE_CONSUMER],
+        stateSecret: config.jwtSecret,
+        publicFrontendUrl: config.publicFrontendUrl,
+    });
+    // What every connected agent is told at initialize: the admin's preamble
+    // at the repository root, read as the platform (the root is default-deny
+    // 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 mcpService = new McpService({
         // 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}`,
         // Manual namespace + UTCP variable prefix (KNOWLEDGE_BASE_API_URL / …).
         manualName: 'KNOWLEDGE_BASE',
-        // Oversized chain results spill here too — an external MCP session has no
+        // Oversized chain results spill here too — an external MCP caller has no
         // ambient workspace, so it reads the spill back by ref via `read_file`.
         spillStore,
         // For the needs-authorization setup link surfaced to external agents.
         publicFrontendUrl: config.publicFrontendUrl,
+        readAgentPreamble: readPreamble,
     }, 
     // 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
     // tool need?".
     secretsVaultService, toolManualService, 
-    // Loopback bearer mint for OAuth/JWT sessions — their own bearer would
+    // Loopback bearer mint for OAuth/JWT requests — their own bearer would
     // 401 at the connection-key/internal-only /api/agent/* hop.
     internalTokenService, 
-    // Session-grant reset for broken tool sign-ins. A closure because the
+    // Grant reset for broken tool sign-ins. A closure because the
     // provider is constructed just below (it needs nothing from McpService;
     // the binding is only dereferenced at call time, long after boot).
     (bearer) => mcpOAuthProvider.revokeByAccessToken(bearer));
-    // A changed secret invalidates the proxy's remembered manual failures for
-    // that user (null = shared secret → everyone), so a just-repaired
-    // credential is retried on the very next session build instead of waiting
-    // out the failure memo's TTL.
-    secretsVaultService.onMutation((changedUserId) => mcpService.clearManualFailures(changedUserId));
+    // A changed secret invalidates what the proxy built from the old value for
+    // that user (null = shared secret → everyone): remembered manual failures,
+    // so a just-repaired credential is retried on the very next request instead
+    // of waiting out the failure memo's TTL, and pooled downstream connections.
+    secretsVaultService.onMutation((changedUserId) => mcpService.onSecretsChanged(changedUserId));
     // MCP OAuth 2.1 authorization server (our own AS): lets MCP clients with no
     // pre-shared connection key connect via the standard 401 → discovery → DCR →
     // authorize (PKCE) flow. The authorize step routes the browser to /connect
@@ -458,6 +608,7 @@ export async function createCoreServices(config, ports = {}) {
         events: eventBus,
         kbDirName: kbDirName,
         creatorAccess,
+        loadActiveGroups,
     });
     const toolHandlerFactory = createToolHandlerFactory(resolveToolContext);
     const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService);
@@ -475,12 +626,12 @@ export async function createCoreServices(config, ports = {}) {
     // retry budget AND recovery-agent budget exhausted) the worker emits
     // a `'system'` feedback notice that admins triage out of band.
     //
-    // The orphan-startup sweep runs BEFORE start() so any rows that
-    // previous deploys left as `running` (process crashed mid-commit) get
-    // reset to `pending` before the worker starts claiming. The sweep
-    // also enqueues working-tree dirt that pre-dates the queue (the
-    // existing `target-company-state` orphans).
-    await pendingCommitsService.startupReconcile(workspaceService.knownWorkspaces(), { scan: (ws) => workspaceService.scanOrphanedPaths(ws.id) }, { email: recoveryBot.email, name: recoveryBot.name });
+    // The queue's recovery — rows a dead process left `running` go back to
+    // `pending`, and working-tree dirt that pre-dates the queue is enqueued —
+    // runs under the commit-worker lease, right before the worker starts (see
+    // `withStartupTask` below). At boot, before the lease, it would reset rows
+    // the outgoing process of a redeploy is still committing.
+    const reconcileQueue = () => pendingCommitsService.startupReconcile(workspaceService.knownWorkspaces(), { scan: (ws) => workspaceService.scanOrphanedPaths(ws.id) }, { email: recoveryBot.email, name: recoveryBot.name });
     const pendingCommitsWorker = new PendingCommitsWorker({
         service: pendingCommitsService,
         // The service IS the driver — passed directly rather than wrapped in a
@@ -505,30 +656,37 @@ export async function createCoreServices(config, ports = {}) {
             name: recoveryBot.name,
         },
     });
-    pendingCommitsWorker.start();
+    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
-    // when the env configures one.
+    // the server is built, later). Core contributes the generic OIDC provider.
     const authProviders = ports.authProviders ?? [];
-    // Resolved through settings, so an admin can configure SSO from the setup
-    // screen instead of the environment. Env still wins, so a deployment that
-    // sets these keeps behaving exactly as it did.
-    const oidcIssuerUrl = settings.resolve('oidcIssuerUrl');
-    const oidcClientId = settings.resolve('oidcClientId');
-    const oidcClientSecret = settings.resolve('oidcClientSecret');
-    if (oidcIssuerUrl && oidcClientId && oidcClientSecret) {
-        authProviders.push(new OidcAuthProvider({
-            issuerUrl: oidcIssuerUrl,
-            clientId: oidcClientId,
-            clientSecret: oidcClientSecret,
-            scopes: settings.resolve('oidcScopes') || 'openid profile email',
-            label: settings.resolve('oidcProviderLabel') || 'Single sign-on',
-            publicBackendUrl: config.publicBackendUrl,
-            publicFrontendUrl: config.publicFrontendUrl,
-            cookieSecure: config.publicBackendUrl.startsWith('https'),
-        }));
-    }
+    // Registered unconditionally and resolved through settings on every use, so
+    // an admin can configure SSO from the setup screen — or change it — without
+    // a restart; the provider advertises itself only while the configuration is
+    // complete. Env still wins, so a deployment that sets these keeps behaving
+    // exactly as it did.
+    authProviders.push(new OidcAuthProvider({
+        settings: () => oidcSettingsFrom(settings),
+        publicBackendUrl: config.publicBackendUrl,
+        publicFrontendUrl: config.publicFrontendUrl,
+        cookieSecure: config.publicBackendUrl.startsWith('https'),
+        // A real sign-in proves the values that sign-in used. Recorded against
+        // those — under their own key — so it says nothing about any saved
+        // since, and cannot overwrite what was recorded about them.
+        onSignedIn: async ({ issuerUrl, clientId, clientSecret }) => {
+            const credentials = { issuerUrl, clientId, clientSecret };
+            if ((await settings.oidcVerificationOf(credentials)) === 'verified')
+                return;
+            await settings.recordOidcVerification('verified', credentials);
+        },
+    }));
     // Materializer factory for an overlay-provided directory source: every
     // provisioning burst regenerates `synced-groups.yaml` on the default branch
     // (debounced), committed by the sync bot — that file is what puts access
@@ -548,17 +706,25 @@ export async function createCoreServices(config, ports = {}) {
                 defaultBranchOf: () => DEFAULT_BRANCH,
             }),
             debounceMs: opts?.debounceMs,
-            log: opts?.log ?? ((message) => console.warn(message)),
+            log: opts?.log ?? ((message) => logger('directory-sync').warn(message)),
         });
     };
     // 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);
+    // 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]);
     return {
         config,
         db,
+        gitRunner,
+        commitWorker,
+        disk,
         mcpServerEditService,
+        toolDeleteService,
         workspaceService,
         kbStartupRunner,
         settings,
@@ -567,14 +733,25 @@ export async function createCoreServices(config, ports = {}) {
         docExtractService,
         accessControl,
         creatorAccess,
+        changeGate,
         sessionOntologyService,
         routineWritePolicy,
         skillService,
         pendingSkillsService,
         toolManualService,
+        pendingToolsService,
+        readAgentPreamble: readPreamble,
         pluginIndexService,
         pluginProvisionService,
         joinRequestsService,
+        pluginJoinRequestJobs,
+        pluginLinkIndex,
+        pluginLinksService,
+        pluginRenameService,
+        marketplaceCompiler,
+        marketplaceRepo,
+        githubFacade,
+        githubFacadeCredentials,
         authService,
         authMiddleware,
         accountErasureService,
@@ -584,6 +761,7 @@ export async function createCoreServices(config, ports = {}) {
         reviewWorkflowService,
         fileLockService,
         workflowService,
+        kbSyncService,
         eventBus,
         fileChangeNotifier,
         pendingCommitsService,
@@ -591,6 +769,7 @@ export async function createCoreServices(config, ports = {}) {
         recoveryBot,
         adminAccess,
         groupsAdminService,
+        userAccessRemovalService,
         createSyncedGroupsMaterializer,
         updateCheckService,
         secretsVaultService,