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

package/src/core/__tests__/set-aside-root-is-one-place.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setAsideRootFor } from '../../modules/workspace/set-aside-clone.js';
+
+/**
+ * A working copy of a repository that is no longer the configured one is SET
+ * ASIDE rather than deleted, and two places do it: the KB startup phase,
+ * sweeping the whole workspaces root, and the workspace service, refusing to
+ * adopt one on a branch open. They must set aside into ONE directory.
+ *
+ * They did not. The composition root gave the phase a root under the backups
+ * volume and the workspace service nothing at all, so that one fell back to a
+ * sibling of the workspaces root — which in the shipped compose file is the
+ * container's own filesystem, not a volume. A copy the workspace service kept
+ * was therefore gone at the next ordinary recreate, after the setup screen had
+ * told the admin it was being kept and where to find it.
+ *
+ * Read off the source, like `migrations-unqualified.test.ts` reads the
+ * migrations: the wiring is a single call graph that cannot be built in a unit
+ * test (it wants a database, a git host and a disk), and the invariant is
+ * about the TEXT — that the folder is named once and that one name reaches
+ * both. A second literal is exactly how the two came apart.
+ */
+
+const compositionRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../create-core-services.ts',
+);
+
+describe('the set-aside root the composition root wires', () => {
+  it('is named once, and handed to both the startup phase and the workspace service', async () => {
+    const source = await fs.readFile(compositionRoot, 'utf8');
+
+    // Named once. Two occurrences means two expressions, which is how a
+    // change to one of them silently stops applying to the other.
+    const literals = source.match(/'replaced-working-copies'/g) ?? [];
+    expect(literals).toHaveLength(1);
+
+    // And that one name is rooted at the backups volume, which the deployment
+    // mounts — not at the workspaces root's parent, which it does not.
+    expect(source).toMatch(
+      /const replacedWorkingCopiesRoot = path\.join\(config\.backupsRoot, 'replaced-working-copies'\)/,
+    );
+
+    // Both consumers read the one variable.
+    expect(source).toMatch(/new WorkspaceService\([\s\S]*?replacedWorkingCopiesRoot,[\s\S]*?\);/);
+    expect(source).toMatch(/setAsideRoot: replacedWorkingCopiesRoot,/);
+  });
+});
+
+describe('setAsideRootFor', () => {
+  it('uses the root it is given, whatever the workspaces root is', () => {
+    expect(setAsideRootFor('/app/apps/server/workspaces', '/app/apps/server/backups/replaced-working-copies')).toBe(
+      '/app/apps/server/backups/replaced-working-copies',
+    );
+  });
+
+  it('falls back beside the workspaces root — a place a container deployment must not rely on', () => {
+    expect(setAsideRootFor('/app/apps/server/workspaces')).toBe('/app/apps/server/replaced-working-copies');
+  });
+});

package/src/core/core-ports.ts

@@ -7,6 +7,7 @@ import type { ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
 import type { AuthProviderPlugin } from '../modules/auth/auth.routes.js';
 import type { IErasureParticipant } from '../modules/auth/account-erasure.service.js';
 import type { IAccountAdmission } from '../modules/auth/account-admission.js';
+import type { IWriteAccess } from '../modules/write-access/write-access.js';
 import type { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
 
 /**
@@ -34,7 +35,7 @@ import type { OnServerStart } from '../modules/workspace/startup/on-server-start
  *   enterprise root overwrites the `CoreServices` fields (or pushes into the
  *   `authProviders` array) after construction, before the server is built.
  *
- * (Commit-time KB validation and the ontology write block are NOT ports:
+ * (Commit-time KB validation and the agent read/write hooks are NOT ports:
  * they are workflow lifecycle HOOKS the enterprise root registers on
  * `workflowService.hooks` after construction — see
  * `modules/workflow/workflow-hooks.ts`.)
@@ -117,6 +118,15 @@ export interface CorePorts {
    * admin who asked. See `modules/auth/account-admission.ts`.
    */
   accountAdmission?: IAccountAdmission;
+  /**
+   * Whether the deployment may be changed right now. Asked before every
+   * mutating route (bar the ones that sign people in, manage accounts or
+   * configure the deployment) and every write tool. Core default: always.
+   * A host that sells seats answers no while more accounts are on than its
+   * plan allows, so the workspace is read-only until an admin fixes it. See
+   * `modules/write-access/write-access.ts`.
+   */
+  writeAccess?: IWriteAccess;
 }
 
 /**

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

@@ -4,6 +4,10 @@ import path from 'node:path';
 import type { Router, RequestHandler } from 'express';
 import { createAuthRoutes } from '../modules/auth/auth.routes.js';
 import { createWorkspaceRoutes } from '../modules/workspace/workspace.routes.js';
+import {
+  createAgentUploadRoutes,
+  isAgentUploadRawBodyPath,
+} from '../modules/workspace/agent-upload.routes.js';
 import { createGitInternalsRouteGuard } from '../modules/workspace/git-internals.middleware.js';
 import { startCore } from './lifecycle.js';
 import { createDiffRoutes } from '../modules/diff/diff.routes.js';
@@ -37,7 +41,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 +76,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 +90,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,8 +205,23 @@ 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();
+    // The agent upload route is exempt for the same reason `/api/sync` is:
+    // whoever needs the EXACT bytes has to see them before any parser can
+    // drain the stream. `curl --data-binary @file.zip` with a JSON
+    // content-type is a request an agent can make, and the parser would
+    // otherwise leave the handler nothing to store.
+    if (jsonExemptPaths.has(req.path) || isSyncRawBodyPath(req.path) || isAgentUploadRawBodyPath(req.path)) {
+      return next();
+    }
     return globalJson(req, res, next);
   });
 
@@ -420,24 +440,30 @@ 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, core.agentUploadStore);
+  // The agent upload route, on the same router as the tool endpoints so it
+  // mounts ahead of the JWT `/api` mounts below — but WITHOUT `toolAuth`: its
+  // whole credential is the single-use token in its path, which is the point
+  // (an agent's `curl` carries no session and no connection key). It resolves
+  // no workspace and writes into none; every access, platform-file and branch
+  // rule is applied later by `apply_file_upload`.
+  toolsRouter.use(createAgentUploadRoutes({ uploads: core.agentUploadStore }));
   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 +481,7 @@ export async function createCoreServer(
     router: toolsRouter,
     toolAuth: ta,
     toolHandler: th,
-    sessionOntologyGate,
+    agentAccessGate,
     core,
   });
   toolsRouter.use(createManualRoutes(
@@ -481,7 +507,7 @@ export async function createCoreServer(
   // What every connected agent is told at session start, as the hosted proxy
   // composes it: read by the local `hexis-mcp` bridge at startup and by the
   // External agent access card. Same `manualAuth`, same router, as `all-tools`.
-  toolsRouter.use(createAgentInstructionsRoutes(core.manualAuthMiddleware, core.readAgentPreamble));
+  toolsRouter.use(createAgentInstructionsRoutes(core.manualAuthMiddleware, core.readAgentPreamble, () => core.kb.layout));
   // The fingerprint of the caller's released catalog. The local `hexis-mcp`
   // server polls it to learn that a manual or a skill changed under a
   // connection it cannot be pushed to; nothing else consults it. Same
@@ -546,6 +572,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 +749,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 {
@@ -53,6 +54,7 @@ function parseDomainList(raw: string): string[] {
     .filter((d) => d.length > 0);
 }
 import { SpillStore } from '../modules/workspace/spill-store.js';
+import { AgentUploadStore, assertUploadsRootOutsideWorkspaces } from '../modules/workspace/agent-upload.store.js';
 import { DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
@@ -110,7 +112,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 +143,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 +184,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
@@ -213,12 +221,13 @@ export interface CoreServices {
   /** The scope this graph's vault is registered under with the UTCP variable loader. */
   secretsScope: string;
   spillStore: SpillStore;
+  /** The bytes an agent uploaded, held until `apply_file_upload` lands them or their token expires. */
+  agentUploadStore: AgentUploadStore;
   docExtractService: DocExtractService;
   accessControl: AccessControlService;
   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 +336,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;
@@ -349,7 +360,11 @@ export async function createCoreServices(
   // the default schema, so a single-tenant deployment keeps the lock ids and
   // the ledger it always had.
   const tenantKey = config.dbSchema === DEFAULT_DB_SCHEMA ? '' : config.dbSchema;
-  const db = getDb(config.databaseUrl, { schema: config.dbSchema });
+  // The handle holds this knowledge base's key for its personal-data columns:
+  // the same `SECRETS_ENC_KEY` that seals its stored credentials — its own
+  // derived one, for a tenant — so everything in the schema opens with one
+  // key and nothing in it opens with another tenant's.
+  const db = getDb(config.databaseUrl, { schema: config.dbSchema, piiKey: config.secretsEncKey });
   // A schema of its own is created on first use, so a tenant's first
   // activation needs nothing done by hand; `public` always exists. Then the
   // server is asked whether the connections really search that schema: a
@@ -369,6 +384,10 @@ export async function createCoreServices(
   // package runs its own squashed idempotent CORE history from the packaged
   // `migrations/` folder, tracked in `__drizzle_migrations_core`. An
   // enterprise overlay runs its own history AFTER this (see migrate.ts).
+  // `runCoreMigrations` also seals any pre-encryption plaintext PII rows and
+  // swaps the unique constraints onto the blind-index columns (see
+  // migrate.ts), under the same lock, before any service reads or writes a
+  // PII column.
   await runCoreMigrations(db, coreMigrationsDir());
 
   // Deployment settings come next, before ANY service is built: the KB remote
@@ -486,12 +505,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 +619,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,10 +632,48 @@ 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.
   const spillStore = new SpillStore(config.spillRoot);
+  // The upload route an agent lands files by, so their content never passes
+  // through the model. Bytes live BESIDE the workspaces root (never inside
+  // one) until the apply commits them or the token expires — checked here
+  // rather than assumed, because a root configured inside a workspace would
+  // put bytes no gate has judged where the file tools read.
+  await assertUploadsRootOutsideWorkspaces(config.agentUploadsRoot, config.workspacesRoot);
+  const agentUploadStore = new AgentUploadStore({
+    root: config.agentUploadsRoot,
+    publicBaseUrl: config.publicBackendUrl,
+    tokenPrefix: config.uploadTokenPrefix,
+  });
   // Office-document/PDF text extraction for `read_file`/`grep`, cached by
   // content hash beside the workspaces root (see `DocExtractionCache`).
   const docExtractService = new DocExtractService(config.docExtractCacheRoot);
@@ -574,14 +701,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 +755,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 +854,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,
   );
@@ -1066,6 +1189,9 @@ export async function createCoreServices(
       // For the needs-authorization setup link surfaced to external agents.
       publicFrontendUrl: config.publicFrontendUrl,
       readAgentPreamble: readPreamble,
+      // The guide's name the shared file rules spell, read per request so a name
+      // the setup save applies lands without a restart.
+      kbLayout: () => kb.layout,
       secretsScope,
     },
     // Pre-dispatch per-user credential check: the vault answers "has this caller
@@ -1134,8 +1260,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 +1314,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 +1413,7 @@ export async function createCoreServices(
     db,
     gitRunner,
     commitWorker,
+    whileCommitsHeld: (work) => leased.whileHeld(work),
     startupRetry: null,
     tenantKey,
     secretsScope,
@@ -1298,11 +1429,11 @@ export async function createCoreServices(
     kb,
     kbDirName,
     spillStore,
+    agentUploadStore,
     docExtractService,
     accessControl,
     creatorAccess,
     changeGate,
-    sessionOntologyService,
     routineWritePolicy,
     skillService,
     pendingSkillsService,
@@ -1353,6 +1484,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(),