@bevel-software/platform-core-backend 0.35.0 → 0.36.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.35.0",
-  "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
+  "version": "0.36.1",
+  "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, version control (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -55,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.35.0",
-    "@bevel-software/platform-shared": "0.35.0"
+    "@bevel-software/platform-mcp-core": "0.36.1",
+    "@bevel-software/platform-shared": "0.36.1"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/account-admin.ts

@@ -0,0 +1,27 @@
+import type express from 'express';
+import { AdminAccessService } from '../modules/admin/admin-access.service.js';
+import { createAccountRoutes } from '../modules/auth/account.routes.js';
+import type { IAccessControl } from '../modules/access/index.js';
+import type { WorkspaceService } from '../modules/workspace/index.js';
+
+/**
+ * The deployment admin check and the account admin routes, composed the way
+ * the composition root composes them (`core/create-core-services.ts` and
+ * `core/create-core-server.ts`). A module's suite that drives those routes
+ * end to end takes them from HERE rather than constructing another module's
+ * implementation itself: the admin and auth entries hold their contracts,
+ * and the classes and routers behind them are the root's to wire — as
+ * `real-disk.ts` stands in for the root for the filesystem.
+ */
+export function realAdminAccess(
+  access: IAccessControl,
+  workspace: WorkspaceService,
+  defaultBranch: string,
+  owners: string[],
+): AdminAccessService {
+  return new AdminAccessService(access, workspace, defaultBranch, owners);
+}
+
+export function realAccountRoutes(...args: Parameters<typeof createAccountRoutes>): express.Router {
+  return createAccountRoutes(...args);
+}

package/src/__tests__/hexis-catalog.ts

@@ -11,11 +11,11 @@ import { agentGuideSections, registerAgentGuideTool } from '../modules/agent-gui
 import {
   RoutineWritePolicyService,
   UuidSessionSink,
-  WorkflowHooks,
+  VersionControlHooks,
   createToolHandlerFactory,
   registerChangeRequestReadTools,
   registerEmbedTools,
-  registerWorkflowTools,
+  registerVersionControlTools,
   registerWorkspaceTools,
 } from './tool-wiring.js';
 
@@ -72,7 +72,7 @@ export async function hexisCatalog(
   const toolAuth = ((_req, _res, next) => next()) as unknown as ToolAuth;
   const toolHandler = createToolHandlerFactory(unused());
   const kb = testKbContext();
-  const gate = { recoveryBotEmail: 'bot@x', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() };
+  const gate = { recoveryBotEmail: 'bot@x', hooks: new VersionControlHooks(), notes: new ToolDescriptionNotes() };
 
   // The change-request readers come first, as the root mounts them: they
   // gate their whole payload on the caller's read access and take the access
@@ -106,7 +106,7 @@ export async function hexisCatalog(
     undefined,
     new RipgrepPatternMatcher(),
   );
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
+  registerVersionControlTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
   registerPluginsTools(registry, kb);
   registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
   registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {

package/src/__tests__/kb-context.ts

@@ -1,30 +1,30 @@
-import {
-  DEFAULT_KB_LAYOUT,
-  resolveBranchModel,
-  type BranchModel,
-  type KbLayout,
-} from '@bevel-software/platform-shared';
-import { KbContext } from '../shared/kb-context.js';
-
-/**
- * The knowledge-base context suites hand to the services they construct: the
- * historical two-branch pair `vitest.config.ts` pins (and `test-setup.ts`
- * mirrors onto the shared bindings, for the fixtures that still spell a
- * branch by its binding), the default layout, and `knowledge-base` as the
- * checkout folder. Override any part for a suite that needs another.
- */
-export const TEST_BRANCH_MODEL: BranchModel = {
-  defaultBranch: 'target-company-state',
-  protectedBranches: ['current-company-state', 'target-company-state'],
-};
-
-export function testKbContext(
-  overrides: { kbDirName?: string; branchModel?: BranchModel | null; layout?: KbLayout } = {},
-): KbContext {
-  const model = overrides.branchModel === undefined ? TEST_BRANCH_MODEL : overrides.branchModel;
-  return new KbContext(
-    overrides.kbDirName ?? 'knowledge-base',
-    model === null ? KbContext.branchModelOrUnconfigured({ defaultBranch: '', protectedBranches: [] }) : resolveBranchModel(model),
-    overrides.layout ?? DEFAULT_KB_LAYOUT,
-  );
-}
+import {
+  DEFAULT_KB_LAYOUT,
+  resolveBranchModel,
+  type BranchModel,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
+import { KbContext } from '../shared/kb-context.js';
+
+/**
+ * The knowledge-base context suites hand to the services they construct: the
+ * historical two-branch pair `vitest.config.ts` pins (and `test-setup.ts`
+ * mirrors onto the shared bindings, for the fixtures that still spell a
+ * branch by its binding), the default layout, and `knowledge-base` as the
+ * checkout folder. Override any part for a suite that needs another.
+ */
+export const TEST_BRANCH_MODEL: BranchModel = {
+  defaultBranch: 'target-company-state',
+  protectedBranches: ['current-company-state', 'target-company-state'],
+};
+
+export function testKbContext(
+  overrides: { kbDirName?: string; branchModel?: BranchModel | null; layout?: KbLayout } = {},
+): KbContext {
+  const model = overrides.branchModel === undefined ? TEST_BRANCH_MODEL : overrides.branchModel;
+  return new KbContext(
+    overrides.kbDirName ?? 'knowledge-base',
+    model === null ? KbContext.branchModelOrUnconfigured({ defaultBranch: '', protectedBranches: [] }) : resolveBranchModel(model),
+    overrides.layout ?? DEFAULT_KB_LAYOUT,
+  );
+}

package/src/__tests__/kb-layout-config.test.ts

@@ -16,6 +16,7 @@ import {
   validateKbLayout,
   validateKbRootName,
   normalizeSkillRoot,
+  WORKFLOWS_DIR,
   type KbLayout,
 } from '@bevel-software/platform-shared';
 
@@ -71,6 +72,26 @@ describe('KB layout — validation', () => {
     ).toMatch(/reserved folder name/);
   });
 
+  test('reserves Data, Agents and Workflows, in any letter case, and names them in the refusal', () => {
+    for (const name of ['Data', 'agents', 'Workflows', 'WORKFLOWS']) {
+      expect(
+        validateKbLayout({ knowledgeBaseDir: 'KnowledgeBase', skillsDir: name, pluginsDir: 'Plugins' }),
+        name,
+      ).toBe(`"${name.toLowerCase()}" is a reserved folder name (Data, Agents, Workflows).`);
+    }
+    expect(WORKFLOWS_DIR).toBe('Workflows');
+    expect([...reservedRootDirNames(DEFAULT_KB_LAYOUT)]).toEqual(
+      expect.arrayContaining(['Data', 'Agents', 'Workflows']),
+    );
+  });
+
+  test('no longer knows Pipelines: not reserved, and free to be a root', () => {
+    expect(reservedRootDirNames(DEFAULT_KB_LAYOUT).has('Pipelines')).toBe(false);
+    expect(
+      validateKbLayout({ knowledgeBaseDir: 'KnowledgeBase', skillsDir: 'Pipelines', pluginsDir: 'Plugins' }),
+    ).toBeNull();
+  });
+
   test('renders placeholders without interpreting $-patterns in a folder name', () => {
     expect(
       renderKbLayoutPlaceholders('a {{skillsDir}} b', { knowledgeBaseDir: 'K', skillsDir: 'Sales$&', pluginsDir: 'P' }),

package/src/__tests__/open-change-gate.ts

@@ -2,7 +2,7 @@ import type { IChangeReadGate } from '../modules/access-model/change-gate.js';
 
 /**
  * A read-before-write gate that lets every change through — for tests whose
- * subject is something else. `WorkflowService` refuses to exist without a
+ * subject is something else. `VersionControlService` refuses to exist without a
  * gate (see its constructor), so a harness that only exercises branches,
  * change requests or commits passes this one. Never wired in production: the
  * composition root builds the real `ChangeReadGate`.

package/src/__tests__/tool-handler.ts

@@ -0,0 +1,15 @@
+import { createToolHandlerFactory } from '../modules/tool-helpers/tool-handler.js';
+import type { ToolHandlerFactory } from '../modules/tool-helpers/index.js';
+
+/**
+ * The tool-handler factory, wired the way the composition root wires it
+ * (`core/create-core-services.ts`) minus the write-access and branch ports a
+ * suite about one tool's answer does not exercise. A module's suite that
+ * mounts its tools takes the factory from HERE rather than constructing it
+ * from `tool-helpers`' file: the factory is on no module entry (only its type
+ * is — a handler factory arrives by injection), and this fixture stands in
+ * for the root, as `real-disk.ts` does for the disk.
+ */
+export function toolHandlerFactory(resolve: Parameters<typeof createToolHandlerFactory>[0]): ToolHandlerFactory {
+  return createToolHandlerFactory(resolve);
+}

package/src/__tests__/tool-wiring.ts

@@ -3,7 +3,8 @@
  * that builds a tool surface the way `core/create-core-server.ts` does: the
  * handler factory and context resolver, the tool-auth middleware, the two
  * registrars that take their dependencies by hand, the session sink, the
- * routine write policy, the access resolver and the workflow hooks.
+ * routine write policy, the access resolver, the version-control hooks, the
+ * manual auth middleware and the auth cookie reader, and the MCP routes and service.
  *
  * A module's entry holds its contracts, and a suite asserts through entries.
  * These are not contracts: they are what the root composes, so a suite that
@@ -16,10 +17,15 @@ export { createToolContextResolver } from '../modules/tool-helpers/tool-context.
 export { createToolAuthMiddleware } from '../modules/tool-auth/tool-auth.middleware.js';
 export { InternalTokenService } from '../modules/tool-auth/internal-token.service.js';
 export { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
-export { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.tools.js';
-export { registerChangeRequestReadTools } from '../modules/workflow/agent-tools/change-request-read.tools.js';
+export { registerVersionControlTools } from '../modules/version-control/agent-tools/version-control.tools.js';
+export { registerChangeRequestReadTools } from '../modules/version-control/agent-tools/change-request-read.tools.js';
 export { registerEmbedTools } from '../modules/embed/embed.tools.js';
 export { UuidSessionSink } from '../modules/workspace/session-sink.js';
 export { RoutineWritePolicyService } from '../modules/workspace/routine-write-policy.js';
 export { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
-export { WorkflowHooks, type AgentOperationContext } from '../modules/workflow/workflow-hooks.js';
+export { VersionControlHooks, type AgentOperationContext } from '../modules/version-control/version-control-hooks.js';
+export { createManualAuthMiddleware } from '../modules/tool-auth/tool-auth.middleware.js';
+export { readAuthCookie } from '../modules/auth/auth.middleware.js';
+export type { ToolBranchPort } from '../modules/tool-helpers/tool-handler.js';
+export { createMcpRoutes } from '../modules/mcp/mcp.routes.js';
+export { McpService } from '../modules/mcp/mcp.service.js';

package/src/__tests__/workspace-service.ts

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { NodeGitRunner } from '../modules/workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../modules/version-control/git/node-git-runner.js';
 import type { IGitRunner } from '../shared/git.contract.js';
 import type { ITreeWalker } from '../shared/fs.contract.js';
 import type { KbContext } from '../shared/kb-context.js';

package/src/core/__tests__/catalog-cache-invalidation.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { FileChangeNotifier } from '../../modules/kb-fs/file-change-notifier.js';
-import { WorkflowEventBus } from '../../modules/workflow/event-bus.js';
+import { VersionControlEventBus } from '../../modules/version-control/event-bus.js';
 import { registerCatalogCacheInvalidation } from '../catalog-cache-invalidation.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { testKbContext } from '../../__tests__/kb-context.js';
@@ -15,7 +15,7 @@ const USER = {
 } as unknown as Parameters<Parameters<FileChangeNotifier['onFilesChanged']>[0]>[0]['byUser'];
 
 function setup() {
-  const eventBus = new WorkflowEventBus();
+  const eventBus = new VersionControlEventBus();
   const fileChangeNotifier = new FileChangeNotifier();
   const catalogs = [
     { invalidate: vi.fn() },
@@ -132,7 +132,7 @@ describe('registerCatalogCacheInvalidation', () => {
      * working-tree write does — NOT as a `change-request-merged` special
      * case. That a pull of the default workspace actually emits this event
      * (only after it resolves, and only when it changed the tree's content) is the emitter's
-     * own contract, pinned in workflow.service.releaseLock.test.ts under
+     * own contract, pinned in version-control.service.releaseLock.test.ts under
      * "the tree-change announcement".
      */
     it('drops the catalogs when the default tree changes (write or post-merge pull alike)', () => {

package/src/core/__tests__/compose-embed.test.ts

@@ -26,7 +26,7 @@ function deps(): EmbedComposition {
     },
     accessControl: { canRead: vi.fn(async () => true), canWrite: vi.fn(async () => true) } as never,
     authService: { getUserById: vi.fn(async () => USER), isEmailDomainAllowed: () => true, isActive: async () => true },
-    workflowService: {} as never,
+    versionControlService: {} as never,
     gitService: {} as never,
     accountLinks: { getUserId: async () => null, link: async () => undefined, listForUser: async () => [], unlink: async () => true },
     readers: createFileReaderRegistry({ extract } satisfies Pick<DocExtractService, 'extract'> as DocExtractService),

package/src/core/__tests__/damaged-document.tools.test.ts

@@ -13,7 +13,7 @@ import type { ToolContext } from '../../modules/tool-helpers/tool.contract.js';
 import type { ToolAuth } from '../../modules/tool-auth/tool-auth.middleware.js';
 import { registerWorkspaceTools } from '../../modules/workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../modules/workspace/routine-write-policy.js';
-import { WorkflowHooks } from '../../modules/workflow/workflow-hooks.js';
+import { VersionControlHooks } from '../../modules/version-control/version-control-hooks.js';
 import { ToolDescriptionNotes } from '../../modules/workspace/agent-access.gate.js';
 import { SpillStore } from '../../modules/workspace/spill-store.js';
 import { RipgrepPatternMatcher } from '../../modules/workspace/index.js';
@@ -92,7 +92,7 @@ async function startPlatform(extractorOpts: WorkerDocumentExtractorOptions = {})
     sessionId,
     abortSignal: signal,
     workspaceService: { getWorkspacePath: async () => tempDir } as never,
-    workflowService: {} as never,
+    versionControlService: {} as never,
     events: {} as never,
     getFilesystem: async () => fs,
   });
@@ -123,7 +123,7 @@ async function startPlatform(extractorOpts: WorkerDocumentExtractorOptions = {})
     docExtract,
     allowAll,
     testKbContext({ kbDirName: KB }),
-    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
+    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new VersionControlHooks(), notes: new ToolDescriptionNotes() },
     new RoutineWritePolicyService(),
     {} as never,
     undefined,

package/src/core/__tests__/erasure-slices-wired-once.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Account erasure runs two kinds of slice: core's own (the vault's managed
+ * sign-ins, revoked with their provider before the user row and its rows
+ * cascade away) and the distribution's, from `CorePorts.erasureParticipants`.
+ * The port's array is held by reference so a root may fill it AFTER
+ * construction, and core never writes into it: a root that builds a graph
+ * over the same array more than once (a tenant brought back after eviction)
+ * would otherwise accumulate every past graph's vault slice, each pointing
+ * at that graph's closed pool.
+ *
+ * Read off the source, as `set-aside-root-is-one-place.test.ts` reads it:
+ * the composition root cannot be built in a unit test (it wants a database,
+ * a git host and a disk), and the invariant is about the TEXT — the service
+ * is constructed once, the port's array is passed as it is, core's slice
+ * travels beside it, and nothing pushes into or copies the port's array.
+ * `AccountErasureService`'s own suite pins what that argument order means.
+ */
+
+const compositionRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../create-core-services.ts');
+
+describe('the erasure slices the composition root wires', () => {
+  it('passes the port’s array untouched and the vault’s slice beside it, once', async () => {
+    const source = await fs.readFile(compositionRoot, 'utf8');
+
+    const constructions = source.match(/new AccountErasureService\(/g) ?? [];
+    expect(constructions).toHaveLength(1);
+
+    // The one construction: the port's array as the root received it (or an
+    // empty one of core's own), then core's slices with the vault's first.
+    const call = source.slice(source.indexOf('new AccountErasureService('));
+    const args = call.slice(0, call.indexOf(');') + 2);
+    expect(args).toMatch(/ports\.erasureParticipants \?\? \[\]/);
+    expect(args).toMatch(/\[\s*managedSignInErasure\(secretsVaultService\),?\s*\]/);
+    expect(args.indexOf('ports.erasureParticipants')).toBeLessThan(args.indexOf('managedSignInErasure'));
+
+    // Never written into, never copied: the array a root fills after
+    // construction is the array erasure reads, with nothing of core's in it.
+    expect(source).not.toMatch(/erasureParticipants\s*\.\s*(push|unshift|splice)\(/);
+    expect(source).not.toMatch(/\.\.\.\s*\(?\s*ports\.erasureParticipants/);
+  });
+});

package/src/core/__tests__/gated-boot.test.ts

@@ -48,10 +48,10 @@ function bootable(runAll: () => Promise<void>) {
         return { stop() {} };
       },
     } as BootableCore['kbStartupRunner'],
-    workflowService: {
+    versionControlService: {
       closeChangeRequestsWithDeletedBranches: async () => 0,
       tidyAfterSweep: async () => ({ closedEmpty: 0, removedLeftovers: 0 }),
-    } as BootableCore['workflowService'],
+    } as BootableCore['versionControlService'],
     pluginJoinRequestJobs: { startSweeping() {} } as BootableCore['pluginJoinRequestJobs'],
     tmpSweeper: {
       startSweeping() {

package/src/core/__tests__/lifecycle.test.ts

@@ -460,12 +460,12 @@ describe('stopCore', () => {
             order.push('startupRetry.stop');
           },
         },
-        workflowService: {
+        versionControlService: {
           stopTidying() {
-            order.push('workflowService.stopTidying');
+            order.push('versionControlService.stopTidying');
           },
           async drainTidy() {
-            order.push('workflowService.drainTidy');
+            order.push('versionControlService.drainTidy');
           },
         },
         db: {
@@ -488,10 +488,10 @@ describe('stopCore', () => {
       'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
-      'workflowService.stopTidying',
+      'versionControlService.stopTidying',
       'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
-      'workflowService.drainTidy',
+      'versionControlService.drainTidy',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -550,10 +550,10 @@ describe('stopCore', () => {
     expect(g.order).toEqual([
       'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
-      'workflowService.stopTidying',
+      'versionControlService.stopTidying',
       'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
-      'workflowService.drainTidy',
+      'versionControlService.drainTidy',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -594,10 +594,10 @@ describe('stopCore', () => {
       'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
-      'workflowService.stopTidying',
+      'versionControlService.stopTidying',
       'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
-      'workflowService.drainTidy',
+      'versionControlService.drainTidy',
       'db.end',
     ]);
   });

package/src/core/catalog-cache-invalidation.ts

@@ -1,5 +1,5 @@
 import type { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
-import type { WorkflowEventBus } from '../modules/workflow/event-bus.js';
+import type { VersionControlEventBus } from '../modules/version-control/event-bus.js';
 import type { KbContext } from '../shared/kb-context.js';
 
 /**
@@ -23,7 +23,7 @@ export interface InvalidatableCatalog {
  * Returns an unsubscribe that detaches all three.
  */
 export function registerCatalogCacheInvalidation(deps: {
-  eventBus: WorkflowEventBus;
+  eventBus: VersionControlEventBus;
   fileChangeNotifier: FileChangeNotifier;
   /**
    * The KB folder inside the workspace (`paths` are workspace-relative), the

package/src/core/compose-embed.ts

@@ -1,4 +1,4 @@
-import type { IGitService, IWorkflowService } from '@bevel-software/platform-shared';
+import type { IGitService, IVersionControlService } from '@bevel-software/platform-shared';
 import type { KbContext } from '../shared/kb-context.js';
 import type { IAccessControl } from '../modules/access/access-control.interface.js';
 import type { WriteValidator } from '../modules/kb-fs/index.js';
@@ -15,7 +15,7 @@ export interface EmbedComposition {
   workspaceService: EmbedWorkspacePort;
   accessControl: IAccessControl;
   authService: EmbedAuthPort;
-  workflowService: IWorkflowService;
+  versionControlService: IVersionControlService;
   gitService: IGitService;
   accountLinks: IAccountLinkService;
   /** The SAME extension-to-reader registry `read_file` dispatches on. */
@@ -40,7 +40,7 @@ export function composeEmbedService(deps: EmbedComposition, ports: Pick<CorePort
     deps.workspaceService,
     deps.accessControl,
     deps.authService,
-    deps.workflowService,
+    deps.versionControlService,
     deps.gitService,
     deps.accountLinks,
     deps.readers,

package/src/core/core-ports.ts

@@ -2,7 +2,7 @@ import type { ISessionSink } from '../modules/workspace/session-sink.js';
 import type {
   ISystemNoticeSink,
   RecoveryAgentRunner,
-} from '../modules/workflow/pending-commits.worker.js';
+} from '../modules/version-control/pending-commits.worker.js';
 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';
@@ -12,6 +12,7 @@ import type { OnServerStart } from '../modules/workspace/startup/on-server-start
 import type { AgentGuideHook } from '../modules/agent-guide/agent-guide.js';
 import type { IAgentScopeResolver } from '../modules/agent-scope/index.js';
 import type { EmbedNodeIdResolver } from '../modules/embed/embed.interface.js';
+import type { ManagedSignInPort } from '../modules/secrets-vault/secrets-vault.contract.js';
 import type { IWorkspaceService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../modules/access/index.js';
 import type { KbContext } from '../shared/kb-context.js';
@@ -64,10 +65,15 @@ export interface AgentScopeCollaborators {
  *   enterprise root overwrites the `CoreServices` fields (or pushes into the
  *   `authProviders` array) after construction, before the server is built.
  *
+ * - REQUEST-TIME seams (`managedSignIns`, the third of the three patterns): seeded onto `CoreServices` the same
+ *   way, but the routes that use it read the field on every request rather
+ *   than at mount, so the enterprise root may assign it at any point after
+ *   construction — even after the server is listening.
+ *
  * (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`.)
+ * they are version-control lifecycle HOOKS the enterprise root registers on
+ * `versionControlService.hooks` after construction — see
+ * `modules/version-control/version-control-hooks.ts`.)
  */
 export interface CorePorts {
   /**
@@ -190,6 +196,15 @@ export interface CorePorts {
    * for an id that names nothing. See `modules/embed/embed.interface.ts`.
    */
   embedNodeIdResolver?: EmbedNodeIdResolver;
+  /**
+   * The distribution's side of a MANAGED sign-in (a `.tool` sign-in whose
+   * `oauth` block names a platform connector): what the Connect page shows
+   * for it and how a sign-in through the broker is opened. Core default:
+   * none, so such a sign-in is listed as waiting on the deployment. Also
+   * settable after construction (`CoreServices.managedSignIns`), like the
+   * session sink. See `modules/secrets-vault/secrets-vault.contract.ts`.
+   */
+  managedSignIns?: ManagedSignInPort;
 }
 
 /**