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

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

@@ -37,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,
@@ -72,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>;
 
@@ -85,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;
 }
 
@@ -200,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);
@@ -420,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.
@@ -455,7 +463,7 @@ export async function createCoreServer(
     router: toolsRouter,
     toolAuth: ta,
     toolHandler: th,
-    sessionOntologyGate,
+    agentAccessGate,
     core,
   });
   toolsRouter.use(createManualRoutes(
@@ -546,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,
@@ -722,6 +731,15 @@ export async function createCoreServer(
         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

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';
@@ -35,7 +36,7 @@ import { ManagedRepository, MANAGED_DEFAULT_BRANCH } from '../modules/settings/m
 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 {
@@ -110,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,
@@ -142,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';
@@ -182,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
@@ -218,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;
@@ -327,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;
@@ -486,12 +494,83 @@ export async function createCoreServices(
   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,
     () => 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
@@ -529,10 +608,9 @@ export async function createCoreServices(
     // the first thing that needs them.
     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'),
+    // 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,
@@ -543,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.
@@ -574,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);
@@ -632,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,
@@ -731,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,
   );
@@ -1134,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.
@@ -1187,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
@@ -1283,6 +1388,7 @@ export async function createCoreServices(
     db,
     gitRunner,
     commitWorker,
+    whileCommitsHeld: (work) => leased.whileHeld(work),
     startupRetry: null,
     tenantKey,
     secretsScope,
@@ -1302,7 +1408,6 @@ export async function createCoreServices(
     accessControl,
     creatorAccess,
     changeGate,
-    sessionOntologyService,
     routineWritePolicy,
     skillService,
     pendingSkillsService,
@@ -1353,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(),

package/src/core/lifecycle.ts

@@ -1,7 +1,7 @@
 import type { Server } from 'node:http';
 import { closeDb, type Database } from '../modules/database/connection.js';
 import type { AdvisoryLease } from '../modules/database/advisory-lock.js';
-import { KbRemoteUnreachableError, type KbStartupRunner } from '../modules/workspace/startup/kb-startup-runner.js';
+import { bootMaySurvive, type KbStartupRunner } from '../modules/workspace/startup/kb-startup-runner.js';
 import { noteBesideCheckout } from '../modules/workspace/startup/beside-checkout.js';
 import { unregisterBevelSecretsVariableLoader } from '../modules/secrets-vault/secrets-variable-loader.js';
 import type { WorkflowService } from '../modules/workflow/workflow.service.js';
@@ -164,7 +164,13 @@ export function holdCommitWorkerLease(
         running = false;
         wake?.();
         await loop;
+        // The worker is asked to stop whether or not this process is running
+        // it: a worker that can be held still (`holdable`) may be in the
+        // middle of a hold that uses the database, and its stop is what
+        // waits for that. Stopping a worker that is not running is nothing.
+        const idle = !workerRunning && !stopping;
         await stopWorker();
+        if (idle) await worker.stop().catch((err: unknown) => log(`commit worker stop failed: ${String(err)}`));
         await lease.release();
       })();
       return stopped;
@@ -202,6 +208,80 @@ export function withStartupTask(
   };
 }
 
+/** A worker the lease loop drives, which something else may hold still for a while. */
+export interface HoldableWorker extends LeasedWorker {
+  /**
+   * Run `work` with the worker stopped, and start it again afterwards if the
+   * lease loop still wants it running. A hold waits for the commit in flight
+   * to finish, as a stop does. Holds may overlap; the worker starts again
+   * when the last one ends, whether `work` resolved or threw.
+   */
+  whileHeld<T>(work: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * A worker that can be HELD STILL without the lease loop knowing.
+ *
+ * The lease loop decides whether this process is the one draining the commit
+ * queue; it starts the worker when the lease is taken and stops it when the
+ * lease is lost. Moving the deployment to another repository needs a second,
+ * independent reason for the worker not to run: while working copies are
+ * being set aside and cloned again, a queued commit must not be written into
+ * a directory that is being renamed away, nor into the fresh clone of a
+ * repository it was never meant for. Stopping the loop itself would release
+ * the lease, and another process would take the queue over mid-move.
+ *
+ * So the two reasons are kept apart. `wanted` is the lease loop's word,
+ * `holds` counts the moves in flight, and the worker runs exactly when it is
+ * wanted and nothing holds it.
+ *
+ * A stop waits for the holds in flight as well as for the worker. Shutdown
+ * awaits this stop (bounded by its own budget) before it ends the database
+ * pool, and a move still setting copies aside and cloning needs that pool:
+ * it is either finished, or known to have been cut.
+ */
+export function holdable(worker: LeasedWorker): HoldableWorker {
+  let wanted = false;
+  const inFlight = new Set<Promise<unknown>>();
+  /**
+   * ONE stop at a time, shared by everyone who asks. A worker's own stop is
+   * idempotent by answering a second caller at once, while the first is
+   * still waiting for the commit in flight; a second hold given that answer
+   * would set a working copy aside under that commit.
+   */
+  let stopping: Promise<void> | null = null;
+  const stopWorker = (): Promise<void> => {
+    stopping ??= worker.stop().finally(() => {
+      stopping = null;
+    });
+    return stopping;
+  };
+  return {
+    start() {
+      wanted = true;
+      if (inFlight.size === 0) worker.start();
+    },
+    async stop() {
+      wanted = false;
+      await stopWorker();
+      await Promise.allSettled([...inFlight]);
+    },
+    whileHeld<T>(work: () => Promise<T>): Promise<T> {
+      const held = (async () => {
+        await stopWorker();
+        return work();
+      })();
+      inFlight.add(held);
+      const ended = (): void => {
+        inFlight.delete(held);
+        if (inFlight.size === 0 && wanted) worker.start();
+      };
+      held.then(ended, ended);
+      return held;
+    },
+  };
+}
+
 /**
  * What one knowledge base's graph needs of itself to be STARTED: the boot
  * side effects that used to run inside `createCoreServer`, named so a host
@@ -228,7 +308,8 @@ export interface BootableCore {
  * jobs. `createCoreServer` runs this for a single-tenant deployment; a host
  * serving several knowledge bases runs it when a tenant is activated.
  *
- * Throws to stop the boot on every failure but an unreachable remote — the
+ * Throws to stop the boot on every failure but the ones the host answered
+ * about the repository or the credentials (see `bootMaySurvive`) — the
  * container's restart policy is the retry — see `kb-startup-runner.ts`.
  */
 export async function startCore<C extends BootableCore>(
@@ -267,18 +348,22 @@ export async function startCore<C extends BootableCore>(
   try {
     await core.kbStartupRunner.runAll();
   } catch (err) {
-    // The one failure a boot survives: the remote cannot be reached. That
-    // says nothing about the knowledge base — what we would write is not
-    // known to be wrong, we cannot get there — so refusing to boot only took
-    // away the login and setup screens an operator needs to fix it (a
-    // rotated token, say). The deployment comes up GATED: the setup routes
+    // The failures a boot survives: the host ANSWERED about the repository or
+    // the credentials, or could not be reached at all. None of them says
+    // anything about the knowledge base — what we would write is not known to
+    // be wrong — and every one of them is fixed somewhere else: the host comes
+    // back, the repository is created, the token is granted access, a rotated
+    // token is typed into the setup screen. Refusing to boot took away the
+    // login and setup screens the fix is entered on, and on 2026-09-28 a
+    // repository that had been replaced crash-looped a deployment for exactly
+    // that reason. The deployment comes up GATED instead: the setup routes
     // read the runner's standing failure and keep the app shut, the setup
-    // screen shows why, saving it retries, and the runner keeps trying on
-    // its own. Every other failure still stops the boot, because it means
-    // the template or a step would write something wrong.
-    if (!(err instanceof KbRemoteUnreachableError)) throw err;
-    startupLog.error('booting UNMAINTAINED and gated — the knowledge-base remote could not be reached:', {
-      detail: err.message,
+    // screen shows why, saving it retries, and the runner keeps trying on its
+    // own. Every other failure still stops the boot, because it means the
+    // template or a step would write something wrong. See `bootMaySurvive`.
+    if (!bootMaySurvive(err)) throw err;
+    startupLog.error('booting UNMAINTAINED and gated — the knowledge base could not be initialized:', {
+      detail: err instanceof Error ? err.message : String(err),
     });
     // Kept on the graph so that stopping the graph stops the asking: a
     // retry that outlived its graph would clone into a workspaces folder

package/src/core-config.ts

@@ -6,6 +6,8 @@ import { assertKeyDecodesTo32Bytes } from './shared/token-crypto.js';
 import { DEFAULT_GIT_TIMEOUT_MS } from './modules/workflow/git/node-git-runner.js';
 import { DEFAULT_DB_SCHEMA, assertSchemaName } from './modules/database/connection.js';
 import { logger } from './shared/logging.js';
+import { hasControlCharacter } from './modules/kb-fs/repo-path.js';
+import { sanitizedPath } from './shared/printable.js';
 
 const log = logger('config');
 
@@ -100,7 +102,6 @@ export interface TenantConfig {
   readonly gitUsername: string;
   readonly gitToken: string;
   readonly kbTemplateDir: string;
-  readonly ontologySessionBlock: boolean;
   readonly updateCheckEnabled: boolean;
   readonly loginPasswordEnabled: boolean;
   readonly allowedEmailDomains: string[];
@@ -259,17 +260,6 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
    * existing one. Override with `KB_TEMPLATE_DIR`.
    */
   readonly kbTemplateDir: string;
-  /**
-   * Ontology-session boundary kill-switch. When true (default), an agent run
-   * that has read across more than one ontology can no longer write. A no-op on
-   * a single-ontology KB. Set `ONTOLOGY_SESSION_BLOCK=false` to disable.
-   *
-   * Stays on CORE config (not `AppConfig`) even though the write BLOCK itself
-   * is an enterprise-registered hook: the flag also switches off the core-owned
-   * touch TRACKING (the gate skips entirely when false — see
-   * `session-ontology.gate.ts`), so it must exist wherever the tracking runs.
-   */
-  readonly ontologySessionBlock: boolean;
   /**
    * In-app update check. When true (default), `GET /api/update-check` lazily
    * asks api.github.com for the newest Hexis release — only when an admin's
@@ -469,8 +459,6 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     // Default: the `kb-template/` folder shipped inside this package (works
     // both from src/ and compiled dist/ — see assets.ts).
     this.kbTemplateDir = process.env.KB_TEMPLATE_DIR || defaultKbTemplateDir();
-    this.ontologySessionBlock =
-      (process.env.ONTOLOGY_SESSION_BLOCK ?? 'true').trim().toLowerCase() !== 'false';
     this.updateCheckEnabled =
       (process.env.UPDATE_CHECK ?? 'true').trim().toLowerCase() !== 'false';
     this.allowedEmailDomains = (process.env.ALLOWED_EMAIL_DOMAINS || '')
@@ -621,5 +609,16 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     ) {
       throw new Error(`KB_DIR_NAME must be a single path segment: ${this.kbDirName}`);
     }
+    // A control character, a line break above all: this name is PREFIXED onto
+    // every workspace-relative path, and a line break in a path is a separator
+    // in git's line-oriented stdin protocols (`cat-file --batch` reads one
+    // `<ref>:<path>` per line). A name carrying one would make the normaliser
+    // emit the very path it refuses from a caller — so the deployment fails to
+    // boot rather than resolving paths nothing downstream can safely read.
+    if (hasControlCharacter(this.kbDirName)) {
+      throw new Error(
+        `KB_DIR_NAME must not contain a control character: "${sanitizedPath(this.kbDirName)}"`,
+      );
+    }
   }
 }

package/src/index.ts

@@ -101,8 +101,18 @@ export type {
 export type { ILlmUsageMeter } from './modules/tool-auth/llm-usage-meter.js';
 export type { AuthProviderPlugin } from './modules/auth/auth.routes.js';
 export type { IErasureParticipant } from './modules/auth/account-erasure.service.js';
+export {
+  alwaysWritable,
+  READ_ONLY_CODE,
+  type IWriteAccess,
+  type WriteAccessVerdict,
+} from './modules/write-access/write-access.js';
 export {
   AccountAdmissionRefusedError,
+  AccountDeactivatedError,
+  AccountChangeRefusedError,
+  AuthBackendError,
+  ACCOUNT_DEACTIVATED_MESSAGE,
   admitEveryone,
   type AccountAdmissionVerdict,
   type AccountProvisionReason,
@@ -112,6 +122,7 @@ export {
   WorkflowHooks,
   type CommitValidationHook,
   type CommitValidationContext,
+  type AgentOperationContext,
+  type AgentReadHook,
   type PreWriteHook,
-  type PreWriteContext,
 } from './modules/workflow/workflow-hooks.js';