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

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

@@ -10,6 +10,7 @@ import { createDiffRoutes } from '../modules/diff/diff.routes.js';
 import { createWorkflowRoutes } from '../modules/workflow/workflow.routes.js';
 import { createEventsRoutes } from '../modules/workflow/events.routes.js';
 import { createAccessRoutes } from '../modules/access/access.routes.js';
+import { createAccessRequestRoutes } from '../modules/access/access-requests.routes.js';
 import { createMcpRoutes } from '../modules/mcp/mcp.routes.js';
 import { createOAuthConsentRoutes } from '../modules/mcp/oauth/oauth-consent.routes.js';
 import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
@@ -36,7 +37,7 @@ import {
   registerPluginsTools,
 } from '../modules/plugins/index.js';
 import { keyOrSessionAuth } from '../modules/tool-auth/key-or-session.middleware.js';
-import type { SessionOntologyGate } from '../modules/workspace/session-ontology.gate.js';
+import { ToolDescriptionNotes, type AgentAccessGate } from '../modules/workspace/agent-access.gate.js';
 import {
   createSecretsVaultRoutes,
   createSecretsVaultPublicRoutes,
@@ -50,7 +51,8 @@ import { createConnectionKeysAdminRoutes } from '../modules/tool-auth/connection
 import { createAuditRoutes } from '../modules/audit/audit.routes.js';
 import { createAgentRestAuditMiddleware } from '../modules/audit/agent-rest-audit.middleware.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../modules/tool-manuals/tool-manuals.contract.js';
-import { createSetupRoutes } from '../modules/settings/setup.routes.js';
+import { createSetupRoutes, isComplete } from '../modules/settings/setup.routes.js';
+import { createGitHubAppRoutes } from '../modules/github-app/index.js';
 import { oidcRedirectUri } from '../modules/auth/oidc-auth-provider.js';
 import { repositoryConnectionCheck } from '../modules/settings/connection-check.js';
 import { rootFolderListerFor } from '../modules/settings/git-root-folders.js';
@@ -70,6 +72,7 @@ import { publicConfig } from './public-config.js';
 import { createReadiness } from './readiness.js';
 import { createAgentInstructionsRoutes } from '../modules/agent-instructions/index.js';
 import type { CoreServices } from './create-core-services.js';
+import { createWriteAccessRoutes, createWriteGateMiddleware } from '../modules/write-access/write-access.js';
 
 type ExpressApp = ReturnType<typeof express>;
 
@@ -83,8 +86,8 @@ export interface ToolSurfaceCtx {
   router: Router;
   toolAuth: RequestHandler;
   toolHandler: CoreServices['toolHandlerFactory'];
-  /** Shared ontology-session boundary gate config (file tools + graph tools). */
-  sessionOntologyGate: SessionOntologyGate;
+  /** Shared agent-access gate config (file tools + graph tools). */
+  agentAccessGate: AgentAccessGate;
   core: CoreServices;
 }
 
@@ -198,6 +201,14 @@ export async function createCoreServer(
   // is mounted again below, once the body is parsed and once the caller is
   // known (see the two mounts under `/api/workspace/:id`).
   app.use('/api/workspace/:id', createGitInternalsRouteGuard(core.workspaceService));
+  // The read-only gate, ahead of every route — core's, the tool surface's
+  // and an overlay's alike — so a read-only deployment refuses a change
+  // wherever it would enter. It lets through what signs people in, manages
+  // accounts and configures the deployment (see `ALWAYS_WRITABLE`); write
+  // tools are judged by the tool layer. A no-op unless a host fills
+  // `ports.writeAccess`. Ahead of the body parser too: a refused write is
+  // refused with its own 403, never parsed first (and answered 400 or 413).
+  app.use(createWriteGateMiddleware(core.writeAccess));
   app.use((req, res, next) => {
     if (jsonExemptPaths.has(req.path) || isSyncRawBodyPath(req.path)) return next();
     return globalJson(req, res, next);
@@ -418,24 +429,23 @@ export async function createCoreServer(
       },
     }),
   );
-  // Shared ontology-session boundary gate config, consumed by every tool
-  // surface that touches the KB (file tools + graph tools). The gate's
-  // blocking decision runs through the workflow hooks: core registers none
-  // (tracking only); the enterprise root registers the ontology block on
-  // `workflowService.hooks` before this server is built.
-  const sessionOntologyGate = {
-    service: core.sessionOntologyService,
-    enabled: core.config.ontologySessionBlock,
-    kb: core.kb,
+  // Shared agent-access gate config, consumed by every tool surface that
+  // touches the KB (file tools + graph tools). The gate decides nothing
+  // itself: it calls the read and write hooks a deployment registered on
+  // `workflowService.hooks`, and carries the notes that deployment wants
+  // agents to read about the gated tools. Core registers neither, so a
+  // core-only deployment refuses nothing and says nothing extra.
+  const agentAccessGate: AgentAccessGate = {
     recoveryBotEmail: RECOVERY_BOT_EMAIL,
     hooks: core.workflowService.hooks,
+    notes: new ToolDescriptionNotes(),
   };
   // A skill's `allowed-tools`, checked against what the caller can see — on
   // every save surface (agent write tools, the app's PUT /file) and on
   // `get_skill`. Warnings only; it never refuses a save.
   const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kb);
   registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb);
-  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, sessionOntologyGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate);
+  registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate);
   registerSkillsTools(core.toolRegistry, toolsRouter, ta, th, core.skillService, allowedToolsChecker);
   // Definitions only: the endpoints they describe are the app's own plugin
   // creation routes, mounted below behind the key-or-session gate.
@@ -453,7 +463,7 @@ export async function createCoreServer(
     router: toolsRouter,
     toolAuth: ta,
     toolHandler: th,
-    sessionOntologyGate,
+    agentAccessGate,
     core,
   });
   toolsRouter.use(createManualRoutes(
@@ -544,6 +554,7 @@ export async function createCoreServer(
   // request also gets the resolved form judged — a link in the repository that
   // points into the git folder — before any read gate or lock.
   app.use('/api/workspace/:id', core.authMiddleware, createGitInternalsRouteGuard(core.workspaceService));
+  app.use('/api', core.authMiddleware, createWriteAccessRoutes(core.writeAccess));
   app.use('/api', core.authMiddleware, createWorkspaceRoutes(
     core.workspaceService,
     core.authService,
@@ -591,6 +602,18 @@ export async function createCoreServer(
     core.kb,
     [core.config.adminEmail],
   ));
+  // Asking for Can edit or Owner on an item from its Manage access dialog, and
+  // the editors' Accept / Decline. Mounted beside the access routes it shares
+  // its gate with: the request is refused by the same canWrite it would
+  // otherwise have to wait for.
+  app.use('/api', core.authMiddleware, createAccessRequestRoutes({
+    accessControl: core.accessControl,
+    workspaceService: core.workspaceService,
+    authService: core.authService,
+    workflow: core.workflowService,
+    lifecycle: core.joinRequestsService,
+    kb: core.kb,
+  }));
   app.use(
     '/api',
     core.authMiddleware,
@@ -700,8 +723,39 @@ export async function createCoreServer(
       repositoryConnectionCheck(core.gitRunner),
       rootFolderListerFor(core.gitRunner),
       oidcRedirectUri(core.config.publicBackendUrl),
+      // The two sign-in checks keep their defaults.
+      undefined,
+      undefined,
+      {
+        source: core.repositorySource,
+        ensureManaged: (branch) => core.managedRepository.ensure(core.gitRunner, branch),
+        githubApp: core.githubApp,
+      },
+      // What a move to another repository has to decide about, and what it
+      // runs under. Bound here rather than handed the whole workflow service:
+      // the setup routes ask two questions, hold the commit worker for the
+      // move, and know nothing else about a request or a commit.
+      {
+        countOpen: () => core.workflowService.countOpenChangeRequests(),
+        closeAsRepositoryReplaced: () => core.workflowService.closeOpenChangeRequestsAsRepositoryReplaced(),
+        whileCommitsHeld: (work) => core.whileCommitsHeld(work),
+      },
     ),
   );
+  // Connecting a repository on GitHub through a GitHub App: the round trips
+  // to GitHub the setup screen starts, behind the same sign-in.
+  app.use(
+    '/api',
+    core.authMiddleware,
+    createGitHubAppRoutes({
+      settings: core.settings,
+      connection: core.githubApp,
+      adminAccess: core.adminAccess,
+      publicBackendUrl: core.config.publicBackendUrl,
+      publicFrontendUrl: core.config.publicFrontendUrl,
+      isComplete: () => isComplete(core.settings, core.kb, core.repositorySource),
+    }),
+  );
   const toolPageUser = async (userId: string): Promise<AuthUser | undefined> => {
     const u = await core.authService.getUserById(userId);
     return u ? ({ id: u.id, email: u.email, name: u.name } as AuthUser) : undefined;

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

@@ -12,6 +12,7 @@ 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 { branchForWorkspaceId } from '../shared/workspace-id.js';
 import { getDb, type Database } from '../modules/database/connection.js';
 import { runCoreMigrations } from '../modules/database/migrate.js';
 import { coreMigrationsDir } from '../assets.js';
@@ -30,9 +31,12 @@ 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 { gitCredentials, type IGitRunner } from '../shared/git.contract.js';
+import type { IGitRunner } from '../shared/git.contract.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, type LeaseLoopHandle } from './lifecycle.js';
+import { holdCommitWorkerLease, holdable, withStartupTask, type LeaseLoopHandle } from './lifecycle.js';
 
 /** The hosted MCP endpoint at a deployment address, with any userinfo stripped. */
 function mcpEndpointUrl(publicBackendUrl: string): string {
@@ -107,7 +111,6 @@ import { WorkflowEventBus } from '../modules/workflow/event-bus.js';
 import { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import { WorkflowService } from '../modules/workflow/workflow.service.js';
 import { WorkflowHooks } from '../modules/workflow/workflow-hooks.js';
-import { SessionOntologyService } from '../modules/workflow/session-ontology.service.js';
 import { PendingCommitsService } from '../modules/workflow/pending-commits.service.js';
 import {
   PendingCommitsWorker,
@@ -139,6 +142,7 @@ import { BevelOAuthProvider } from '../modules/mcp/oauth/bevel-oauth-provider.js
 import { getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
 import { ToolRegistry } from '../modules/tool-registry/tool-registry.js';
 import { createToolContextResolver } from '../modules/tool-helpers/tool-context.js';
+import { alwaysWritable, type IWriteAccess } from '../modules/write-access/write-access.js';
 import { createToolHandlerFactory } from '../modules/tool-helpers/tool-handler.js';
 import { TokenCrypto } from '../shared/token-crypto.js';
 import { UpdateCheckService } from '../modules/update-check/update-check.service.js';
@@ -179,6 +183,12 @@ export interface CoreServices {
    * lease to the replacement.
    */
   commitWorker: LeaseLoopHandle;
+  /**
+   * Run something with no queued commit being written: the commit worker is
+   * stopped for its duration and started again afterwards, the lease kept.
+   * What a move to another repository runs the startup phase under.
+   */
+  whileCommitsHeld<T>(work: () => Promise<T>): Promise<T>;
   workspaceService: WorkspaceService;
   /**
    * The KB startup phase (see `startup/on-server-start.ts`): run at the
@@ -186,6 +196,15 @@ export interface CoreServices {
    * first-time setup completion — and never again while the process serves.
    */
   kbStartupRunner: KbStartupRunner;
+  /**
+   * Where the knowledge base's repository is and what git presents to it,
+   * whichever way the deployment was given one (see `RepositorySource`).
+   */
+  repositorySource: RepositorySource;
+  /** The repository the deployment keeps for itself, when that is the way it chose. */
+  managedRepository: ManagedRepository;
+  /** The connection to GitHub through a GitHub App, when that is the way it chose. */
+  githubApp: GitHubAppConnection;
   /**
    * The startup phase's retry when the boot survived an unreachable remote
    * — set by `startCore`, stopped by `stopCore` (see `core/lifecycle.ts`);
@@ -206,7 +225,6 @@ export interface CoreServices {
   creatorAccess: CreatorAccessService;
   /** Read-before-write, for the surfaces that ask ahead of the lock (see `access-model/change-gate.ts`). */
   changeGate: ChangeReadGate;
-  sessionOntologyService: SessionOntologyService;
   routineWritePolicy: RoutineWritePolicyService;
   skillService: SkillService;
   pendingSkillsService: PendingSkillsService;
@@ -315,6 +333,8 @@ export interface CoreServices {
   toolAuthMiddleware: ReturnType<typeof createToolAuthMiddleware>;
   manualAuthMiddleware: ReturnType<typeof createManualAuthMiddleware>;
   toolHandlerFactory: ReturnType<typeof createToolHandlerFactory>;
+  /** Whether the deployment may be changed right now — `ports.writeAccess`, or always. */
+  writeAccess: IWriteAccess;
   // ── Server-time seams (enterprise overwrites after construction) ────────
   /** `start_session` backing — core default {@link UuidSessionSink}. */
   sessionSink: ISessionSink;
@@ -434,21 +454,123 @@ export async function createCoreServices(
   // 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,
-  );
+  //
+  // 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, 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: unknown) => 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);
+  }
+  /**
+   * Where a working copy of a replaced repository is kept, for BOTH the places
+   * that find one: the KB startup phase sweeping the workspaces root, and the
+   * workspace service refusing to adopt one on a branch open. One variable,
+   * passed to both, because they move the same clones for the same reason and
+   * an admin looking for their work must have one folder to look in — the two
+   * drifted apart once already, and the copy the workspace service set aside
+   * landed in the image's own filesystem and was gone at the next recreate.
+   *
+   * Under the backups root: a persistent volume of its own, and one nothing
+   * sweeps (see the runner's `reconcileClonesWithConfiguredRepository`).
+   */
+  const replacedWorkingCopiesRoot = path.join(config.backupsRoot, 'replaced-working-copies');
+  /**
+   * What must leave with a working copy that is set aside, whoever sets it
+   * aside: the startup phase, or the workspace service on a branch open.
+   *
+   * Its queue: whatever still waits to be committed into that copy was
+   * written against the repository that was left, and the path it names is
+   * about to hold a fresh clone of another one. Held for a person, on every
+   * branch, never written and never deleted.
+   *
+   * And the locks on its branch: each is a claim on a file of the copy that
+   * is going. Left standing, a holder still connected keeps one alive with
+   * heartbeats, and the same path in the new repository refuses everybody
+   * else. Dropped without enqueueing anything, as when change requests are
+   * closed as "repository replaced".
+   *
+   * Throws when either cannot be done, and the caller then leaves the copy
+   * where it is. Reaches FORWARD to both services, like `gitService` below:
+   * it is only ever called long after this function has returned them.
+   */
+  const releaseWorkOnSetAsideCopy = async (workspaceId: string): Promise<void> => {
+    const held = await pendingCommitsService.markNeedsAttentionInWorkspace(
+      workspaceId,
+      'The knowledge-base repository was replaced while this commit was still queued, so it was never ' +
+        'written. The bytes are kept here: the working copy it was meant for belongs to the previous repository.',
+    );
+    if (held > 0) {
+      logger('kb-startup').warn(
+        `${held} queued commit(s) for the working copy "${workspaceId}" need attention: the repository was ` +
+          'replaced before they landed, so they were not written to the new one.',
+      );
+    }
+    await fileLockService.releaseAllOnBranch(branchForWorkspaceId(workspaceId));
+  };
   const workspaceService = new WorkspaceService(
     config.workspacesRoot,
-    () => settings.resolve('kbRepoUrl'),
+    () => repositorySource.url(),
     kb,
     disk,
     gitRunner,
+    replacedWorkingCopiesRoot,
+    // A branch opened onto a clone of another repository sets it aside on
+    // the spot, with nobody having stopped the commit worker for it. So it
+    // is held here, for the one move, and the copy's work leaves first and
+    // is looked for again once the copy has gone: a release that queued its
+    // bytes in between was writing to the copy that left.
+    //
+    // Only the first look may refuse the branch: the copy has not moved yet.
+    // The second runs after the move, so its failure is tried once more and
+    // then logged, as the startup phase logs the same step. Refusing then
+    // would report a move that did happen as one that did not.
+    (workspaceId, move) =>
+      leased.whileHeld(async () => {
+        await releaseWorkOnSetAsideCopy(workspaceId);
+        await move();
+        await releaseWorkOnSetAsideCopy(workspaceId)
+          .catch(() => releaseWorkOnSetAsideCopy(workspaceId))
+          .catch((err: unknown) => {
+            logger('workspace').error(
+              `the working copy "${workspaceId}" was set aside, but what was queued or locked on it meanwhile ` +
+                'could not be looked for again:',
+              { err },
+            );
+          });
+      }),
   );
   // The KB startup phase: every seeding, scaffolding and migration concern,
   // run through one runner at the deployment's quiet moments (boot + setup
@@ -484,8 +606,11 @@ export async function createCoreServices(
     // 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'),
+    kbRepoUrl: () => repositorySource.url(),
     workspacesRoot: config.workspacesRoot,
+    // The same folder the workspace service sets aside into — see
+    // `replacedWorkingCopiesRoot` above for why the two must agree.
+    setAsideRoot: replacedWorkingCopiesRoot,
     kbDirName,
     templateDir: config.kbTemplateDir,
     defaultBranch: () => kb.defaultBranch,
@@ -496,6 +621,33 @@ export async function createCoreServices(
     steps: kbStartupSteps,
     buildSeedTree: buildSeedTree(disk, config.kbTemplateDir, extraDirs, [config.adminEmail], kb),
     gitRunner,
+    // The work on a working copy that is about to be set aside leaves first:
+    // its queued commits and the locks on its branch (see
+    // `releaseWorkOnSetAsideCopy`). A failure here stops the phase before
+    // the copy moves: a replacement cloned over an untouched queue is how
+    // those bytes would land in the wrong repository.
+    beforeCloneSetAside: releaseWorkOnSetAsideCopy,
+    // And once it is set aside it must leave the workspace service's cache:
+    // on the SAVE that moves the deployment the process is already running,
+    // and a cached path to a directory that is gone is how the next reader
+    // gets an ENOENT instead of a fresh clone.
+    //
+    // Then the copy's work is looked for once more. A release that queued
+    // its bytes between the first look and the move was writing to the copy
+    // that has now gone; nothing can queue against it after this.
+    onCloneDiscarded: async (workspaceId) => {
+      workspaceService.forgetClone(workspaceId);
+      await releaseWorkOnSetAsideCopy(workspaceId);
+    },
+    // And the replacement it cloned in its place: a fresh clone holds every
+    // ref, so the git layer's per-workspace fetch record is told so. Without
+    // it that record still holds the FAILED fetch of the repository that was
+    // replaced, and a strict branch listing within its TTL refuses the new
+    // clone's refs as unproven. Reaches FORWARD to `gitService`, which is
+    // built further down: safe because the runner only ever calls this from
+    // `runAll`, which the server builder invokes long after this function has
+    // returned every service.
+    onCloneCreated: (workspaceId) => gitService.noteWorkspaceFetched(workspaceId),
   });
   // Shared, workspace-independent store for oversized `call_tool_chain` results,
   // read back via `read_file`. Sibling of `workspacesRoot`, never committed.
@@ -527,14 +679,10 @@ export async function createCoreServices(
   // except that new folder at a root (see `access-model/change-gate.ts`).
   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, 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.
+  // dashboard-only `watchlist_check` runs). In-memory: a restriction lives only
+  // for one run.
   const routineWritePolicy = new RoutineWritePolicyService();
   // Skills: discovered from the default-branch workspace only (global catalog).
   const skillService = new SkillService(workspaceService, accessControl, kb, disk);
@@ -585,11 +733,11 @@ export async function createCoreServices(
   // against each other — a backup-reseed races a concurrent commit otherwise.
   const workspaceMutex = new WorkspaceMutex();
   // Workflow lifecycle hooks — the ONE registry this composition shares
-  // between GitService (advisory commit validation), the session-ontology
-  // gate (blocking preWrite), and the enterprise composition root, which
-  // registers module-owned handlers on `workflowService.hooks` right after
-  // this function returns. Core registers none: no commit-time validation
-  // (advisory anyway) and no ontology write block.
+  // between GitService (advisory commit validation), the agent-access gate
+  // (the blocking agentRead / preWrite hooks), and the composition root,
+  // which registers module-owned handlers on `workflowService.hooks` right
+  // after this function returns. Core registers none: no commit-time
+  // validation (advisory anyway) and nothing that refuses an agent call.
   const workflowHooks = new WorkflowHooks();
   const gitService = new GitService(
     workspaceService,
@@ -684,7 +832,7 @@ export async function createCoreServices(
     eventBus,
     fileChangeNotifier,
     // Exposed as `workflowService.hooks` — the SAME instance GitService and
-    // the session-ontology gate consult, so enterprise registrations against
+    // the agent-access gate consult, so a deployment's registrations against
     // it reach every hook point.
     workflowHooks,
   );
@@ -693,7 +841,14 @@ 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, kb);
+  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
@@ -1080,8 +1235,9 @@ export async function createCoreServices(
     creatorAccess,
     loadActiveGroups,
   });
-  const toolHandlerFactory = createToolHandlerFactory(resolveToolContext);
-  const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService);
+  const writeAccess = ports.writeAccess ?? alwaysWritable;
+  const toolHandlerFactory = createToolHandlerFactory(resolveToolContext, writeAccess);
+  const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService, authService);
   // Read-only manual endpoints accept the above PLUS a browser JWT, so a
   // logged-in user can browse the catalog with their session. Execution routes
   // keep `toolAuthMiddleware` (no JWT), so a session can read but not invoke.
@@ -1133,7 +1289,10 @@ export async function createCoreServices(
       name: recoveryBot.name,
     },
   });
-  const leased = withStartupTask(pendingCommitsWorker, reconcileQueue);
+  // Holdable: a move to another repository stops the worker for as long as
+  // working copies are being set aside and cloned again, without giving up
+  // the lease (see `holdable` in `core/lifecycle.ts`).
+  const leased = holdable(withStartupTask(pendingCommitsWorker, reconcileQueue));
 
   // 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
@@ -1229,6 +1388,7 @@ export async function createCoreServices(
     db,
     gitRunner,
     commitWorker,
+    whileCommitsHeld: (work) => leased.whileHeld(work),
     startupRetry: null,
     tenantKey,
     secretsScope,
@@ -1237,6 +1397,9 @@ export async function createCoreServices(
     toolDeleteService,
     workspaceService,
     kbStartupRunner,
+    repositorySource,
+    managedRepository,
+    githubApp,
     settings,
     kb,
     kbDirName,
@@ -1245,7 +1408,6 @@ export async function createCoreServices(
     accessControl,
     creatorAccess,
     changeGate,
-    sessionOntologyService,
     routineWritePolicy,
     skillService,
     pendingSkillsService,
@@ -1296,6 +1458,7 @@ export async function createCoreServices(
     toolAuthMiddleware,
     manualAuthMiddleware,
     toolHandlerFactory,
+    writeAccess,
     // Server-time seams — defaults here; the enterprise overlay overwrites
     // (or, for the array, pushes into) these after construction.
     sessionSink: ports.sessionSink ?? new UuidSessionSink(),