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

package/src/modules/secrets-vault/secrets-vault.routes.ts

@@ -12,6 +12,8 @@ import {
   configuredAs,
   type DeclaredOAuthProvider,
   type ISecretsVaultService,
+  type ManagedSignInPort,
+  type SecretConfigStatus,
 } from './secrets-vault.contract.js';
 import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/index.js';
 import type { IConnectionProbeService } from '../connection-probe/index.js';
@@ -48,6 +50,36 @@ export interface SecretsVaultRoutesDeps {
   publicBackendUrl: string;
   /** Public base URL of the SPA — where the OAuth callback lands the browser. */
   publicFrontendUrl: string;
+  /**
+   * The distribution's managed sign-in port, read per request (the overlay
+   * binds it after boot). Absent or null: a managed sign-in is listed as
+   * waiting on the deployment, and starting one is refused with that reason.
+   */
+  managedSignIns?: () => ManagedSignInPort | null;
+}
+
+/**
+ * The card a managed sign-in renders as on the Connect page, as `/connect/pending`
+ * and `/secrets/tools` report it beside the ordinary fields.
+ */
+interface ManagedSignInView {
+  connectorId: string;
+  scopeSet: string;
+  /** Who the connection belongs to: each person, or the workspace. */
+  tokenScope: 'user' | 'shared';
+  displayName: string;
+  icon: string;
+  description: string;
+  permissions: string[];
+  scopeSetLabel: string;
+  dataResidency: string;
+  subprocessor: string;
+  /** The connected account the row remembers, for "Connected as …". */
+  account: string | null;
+  /** The owner replaced the managed app with the deployment's own (the ordinary flow then applies). */
+  ownApp: boolean;
+  /** Sign-ins through the broker can be started on this deployment. */
+  available: boolean;
 }
 
 function redirectUriFor(publicBackendUrl: string): string {
@@ -66,7 +98,9 @@ function declaredProvider(variable: ToolVariable): DeclaredOAuthProvider | null
   return {
     authorizationUrl: oauth.authorizationUrl,
     tokenUrl: oauth.tokenUrl,
-    clientId: oauth.clientId,
+    // A managed sign-in declares no client of its own (the broker's app is
+    // the client); the one route that pins a provider requires an owner's.
+    clientId: oauth.clientId ?? '',
     scopes: oauth.scopes,
     // Static authorize params (e.g. Google's `access_type=offline`) so the
     // provider returns a refresh token.
@@ -149,6 +183,36 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
     return variable ? { manual, variable } : null;
   }
 
+  /**
+   * The card for a managed sign-in, or null for an ordinary one. Built from
+   * the variable (which connector), the port (what the connector is) and
+   * the row (whose account, whether an owner brought their own app).
+   */
+  function managedView(v: ToolVariable, st: SecretConfigStatus | undefined): ManagedSignInView | null {
+    const ref = v.oauth?.managed;
+    if (!ref) return null;
+    const port = deps.managedSignIns?.() ?? null;
+    const card = port?.describe(ref) ?? null;
+    const shared = v.scope === 'admin';
+    return {
+      connectorId: ref.connectorId,
+      scopeSet: ref.scopeSet,
+      tokenScope: shared ? 'shared' : 'user',
+      displayName: card?.displayName ?? v.label ?? ref.connectorId,
+      icon: card?.icon ?? 'Plug',
+      description: card?.description ?? '',
+      permissions: card?.permissions ?? [],
+      scopeSetLabel: card?.scopeSetLabel ?? ref.scopeSet,
+      dataResidency: card?.dataResidency ?? '',
+      subprocessor: card?.subprocessor ?? '',
+      account: (shared ? st?.adminAccount : st?.userAccount) ?? null,
+      ownApp: st?.adminBringsOwnApp === true,
+      // Startable only for a connector this distribution knows: a broker that
+      // is up cannot open a sign-in through a connector it has no card for.
+      available: port?.available() === true && card !== null,
+    };
+  }
+
   router.get('/secrets', async (req, res) => {
     const userId = req.userId;
     if (!userId) return void res.status(401).json({ error: 'Not authenticated' });
@@ -269,22 +333,31 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
             const key = varKey(m.name, v.name);
             const st = statusByKey.get(key);
             const isOAuth = v.oauth != null;
-            const authorized = isOAuth ? (st?.userAuthorized ?? false) : undefined;
+            // A SHARED sign-in (a managed workspace connection) is authorized
+            // when the shared row holds tokens — one connection for everyone.
+            const shared = isOAuth && v.scope === 'admin';
+            const authorized = isOAuth ? ((shared ? st?.adminAuthorized : st?.userAuthorized) ?? false) : undefined;
             // For an OAuth var: which declared permissions the token doesn't cover,
             // so the panel can say WHAT it works for and what it doesn't. Only
             // meaningful once authorized (an unauthorized var has no token at all).
-            const missing = isOAuth && authorized ? missingScopes(v.oauth?.scopes, st?.grantedScopes) : [];
+            const granted = shared ? st?.adminGrantedScopes : st?.grantedScopes;
+            const missing = isOAuth && authorized ? missingScopes(v.oauth?.scopes, granted) : [];
+            const managed = managedView(v, st);
             return {
               name: v.name,
               scope: v.scope,
               label: v.label ?? null,
               key,
               adminConfigured: st?.adminConfigured ?? false,
+              // What the owner's row IS, so a surface can tell a client of the
+              // OAuth kind from a key left from when the variable was static.
+              adminKind: st?.adminKind ?? null,
               userConfigured: st?.userConfigured ?? false,
               oauth: isOAuth,
               authorized,
               needsReauth: isOAuth && authorized === true && missing.length > 0,
               missingScopes: missing,
+              ...(managed ? { managed } : {}),
             };
           }),
         })),
@@ -389,21 +462,35 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       const toolOAuth = manuals.flatMap((m) => {
         const canWrite = canWriteBySlug.get(m.slug) ?? false;
         return (m.variables ?? [])
-          .filter((v) => v.scope === 'user' && v.oauth)
+          // Every per-user sign-in, plus a managed WORKSPACE connection (the
+          // one `admin`-scoped sign-in there is): listed for everyone who can
+          // read the tool, since everyone calls through it, with Connect
+          // offered to the writers who can make it.
+          .filter((v) => v.oauth && (v.scope === 'user' || v.oauth.managed))
           .map((v) => {
             const st = statusByKey.get(varKey(m.name, v.name));
-            const authorized = st?.userAuthorized ?? false;
+            const managed = managedView(v, st);
+            const shared = v.scope === 'admin';
+            const authorized = (shared ? st?.adminAuthorized : st?.userAuthorized) ?? false;
             // Signed in, but the token's granted scopes no longer cover what the
             // tool declares → surface as needing re-authorization, not as connected.
             const needsReauth =
-              authorized && !scopesCovered(v.oauth?.scopes, st?.grantedScopes);
+              authorized && !scopesCovered(v.oauth?.scopes, shared ? st?.adminGrantedScopes : st?.grantedScopes);
             // On an oauth var the ADMIN row is the provider registration — the
             // client secret — without which nobody's Authorize can work. It is a
             // workspace value like any other, so it carries the same flag. It
             // must be an OAUTH row: `beginToolOAuthByKey` refuses a static one,
             // so a shared key left over from before this var was made OAuth
             // would otherwise light up Authorize with nothing behind it.
-            const ownerConfigured = configuredAs('oauth', st?.adminConfigured, st?.adminKind);
+            //
+            // A MANAGED sign-in needs no registration here — the broker holds
+            // it — so it is configured when the deployment can reach a broker,
+            // when an owner replaced the managed app with their own, or when a
+            // token is already stored (nothing is outstanding for a connection
+            // that works, whatever the broker is doing).
+            const ownerConfigured = managed
+              ? managed.ownApp || managed.available || authorized
+              : configuredAs('oauth', st?.adminConfigured, st?.adminKind);
             return {
               slug: m.slug,
               varName: v.name,
@@ -413,7 +500,13 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
               authorized,
               needsReauth,
               ownerConfigured,
-              ownerOnly: !ownerConfigured && !canWrite,
+              // Not the caller's to do: an ordinary sign-in waiting on a
+              // registration the caller may not write, or a managed WORKSPACE
+              // connection seen by someone who may not write the tool. A
+              // managed personal sign-in is always the caller's own, broker or
+              // no broker.
+              ownerOnly: managed ? shared && !canWrite : !ownerConfigured && !canWrite,
+              ...(managed ? { managed, canWrite } : {}),
             };
           });
       });
@@ -516,10 +609,21 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       const provider = declaredProvider(found.variable);
       if (!provider) return void res.status(422).json({ error: endpointsUnknown(found.manual) });
       const clientSecret = (req.body ?? {}).clientSecret;
+      // A managed sign-in names no client of its own; an owner who brings
+      // the deployment's own app ("use our own app") supplies its id here
+      // with the secret, and the pinned row then runs the ordinary flow:
+      // this deployment's redirect URI, a direct token exchange and refresh.
+      const ownClientId = typeof (req.body ?? {}).clientId === 'string' ? (req.body.clientId as string).trim() : '';
+      const clientId = provider.clientId || ownClientId;
+      if (!clientId) {
+        return void res.status(422).json({
+          error: 'This sign-in goes through the managed connector. To use your own OAuth app instead, send its client id with the secret.',
+        });
+      }
       await secretsVault.putSharedOAuthClientSecret({
         key: varKey(found.manual.name, found.variable.name),
         clientSecret,
-        provider,
+        provider: { ...provider, clientId },
       });
       res.status(201).json({ ok: true });
     } catch (err) {
@@ -566,6 +670,50 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       if (!signIn?.oauth) {
         throw new SecretOAuthError("This tool's owner hasn't finished setting this up");
       }
+      const returnTo: unknown = (req.body ?? {}).returnTo;
+      // A MANAGED sign-in goes through the broker — unless an owner pinned the
+      // deployment's own app on the shared row, in which case the ordinary
+      // flow below applies exactly as for a file-declared client. Read from
+      // the LIVE declaration like everything else here.
+      const ref = signIn.oauth.managed;
+      if (ref) {
+        const [st] = await secretsVault.statusFor(userId, [key]);
+        // An owner's own app runs the ordinary flow, whose tokens land on the
+        // caller's own row. A WORKSPACE connection reads the shared row, so
+        // the two cannot meet: that combination is refused here rather than
+        // signing an owner in to a row nobody reads.
+        if (st?.adminBringsOwnApp === true && signIn.scope === 'admin') {
+          return void res.status(422).json({
+            error: 'A workspace connection cannot use your own OAuth app yet. Remove the client secret to connect it through the managed connector.',
+          });
+        }
+        if (st?.adminBringsOwnApp !== true) {
+          const port = deps.managedSignIns?.() ?? null;
+          if (!port || !port.available()) {
+            return void res.status(409).json({
+              error: 'This deployment is not connected to a connector broker yet. Ask your admin to configure it.',
+            });
+          }
+          // The same answer the card gives (`available`): a connector the
+          // distribution does not know cannot be started through its broker.
+          if (!port.describe(ref)) {
+            return void res.status(409).json({
+              error: 'This deployment does not offer the connector this sign-in names. Ask your admin.',
+            });
+          }
+          const shared = signIn.scope === 'admin';
+          if (shared && !(await accessControl.canWrite(defaultWs(), email, manual.path))) {
+            return void res.status(403).json({ error: 'Only a writer of this tool can connect its workspace account.' });
+          }
+          const { url } = await port.start({
+            userId: shared ? null : userId,
+            key,
+            ref,
+            returnTo: isSafeReturnPath(returnTo) ? returnTo : '/connect',
+          });
+          return void res.json({ url });
+        }
+      }
       const provider = declared ? declaredProvider(declared) : undefined;
       if (provider === null) return void res.status(422).json({ error: endpointsUnknown(manual) });
       // Provision the caller's oauth row (from the owner-set secret) FIRST — its id
@@ -587,7 +735,6 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       // the provider, so the state is the only thing it can trust. An absent or
       // unsafe `returnTo` falls back to the legacy `'connect'` marker, which
       // keeps a body-less start byte-identical to what it produced before.
-      const returnTo: unknown = (req.body ?? {}).returnTo;
       const state = signState(deps.stateSecret, {
         u: userId,
         i: id,

package/src/modules/settings/__tests__/repository-source.test.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import { ManagedRepository, MANAGED_REPOSITORY_DIR } from '../managed-repository.js';
 import { RepositorySource, type GitHubAppRepository } from '../repository-source.js';
 

package/src/modules/settings/__tests__/setup.routes.layout-phase.test.ts

@@ -10,7 +10,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { defaultKbTemplateDir } from '../../../assets.js';

package/src/modules/settings/__tests__/setup.routes.managed-phase.test.ts

@@ -12,7 +12,7 @@ import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
 import { ManagedRepository } from '../managed-repository.js';
 import { RepositorySource } from '../repository-source.js';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { defaultKbTemplateDir } from '../../../assets.js';

package/src/modules/settings/connection-check.ts

@@ -6,7 +6,7 @@ import { validateHttpsRemote } from './deployment-settings.service.js';
 import { classifyGitFailure } from '../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { GitRunError, type IGitRunner } from '../../shared/git.contract.js';
-import { NodeGitRunner } from '../workflow/index.js';
+import { NodeGitRunner } from '../version-control/index.js';
 
 /** The repository connection a deployment reads and writes its knowledge base with. */
 export interface RepositoryConnection {

package/src/modules/settings/deployment-settings.service.ts

@@ -325,7 +325,7 @@ export const CORE_SETTINGS: SettingDef[] = [
   {
     /**
      * Whether the server removes, on its own, the branches merged change
-     * requests left behind (`WorkflowService.retireLeftoverMergedBranches`).
+     * requests left behind (`VersionControlService.retireLeftoverMergedBranches`).
      * On unless set to `false`; a blanked field puts the default back. Read
      * at every round, so it applies without a restart. It covers that cleanup
      * only: the removal of a branch when its change request is merged does

package/src/modules/settings/git-root-folders.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import type { IGitRunner } from '../../shared/git.contract.js';
 import { printable } from '../../shared/printable.js';
 import { logger } from '../../shared/logging.js';
-import { NodeGitRunner } from '../workflow/index.js';
+import { NodeGitRunner } from '../version-control/index.js';
 import { probeCredentialArgs, probeGitEnv } from './connection-check.js';
 
 const log = logger('setup');

package/src/modules/settings/setup.routes.ts

@@ -207,7 +207,7 @@ export function createSetupRoutes(
    * What a change of the knowledge-base repository has to decide about, and
    * what to do when the admin decides to close.
    *
-   * Injected because the setup routes must stay free of the workflow module —
+   * Injected because the setup routes must stay free of the version-control module —
    * and a minimal mount (tests, a distribution without change requests) simply
    * has none: the default answers "no open requests", so the confirmation
    * offers no choice it cannot honour.

package/src/modules/skills/__tests__/allowed-tools-warn.tools.test.ts

@@ -11,7 +11,7 @@ import type { ToolContext } from '../../tool-helpers/tool.contract.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { VersionControlHooks } from '../../version-control/version-control-hooks.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService, WorkerDocumentExtractor } from '../../workspace/index.js';
@@ -96,7 +96,7 @@ async function start(): Promise<string> {
     sessionId,
     abortSignal: signal,
     workspaceService: {} as never,
-    workflowService: {} as never,
+    versionControlService: {} as never,
     events: {} as never,
     getFilesystem: async () => fs,
   });
@@ -112,7 +112,7 @@ async function start(): Promise<string> {
   registerWorkspaceTools(
     registry, router, fakeAuth, toolHandler,
     new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), new WorkerDocumentExtractor()), allowAll, testKbContext({ kbDirName: KB_DIR }),
-    { 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,
     checker,

package/src/modules/skills/__tests__/branch-skills.tools.test.ts

@@ -93,7 +93,7 @@ async function start(): Promise<string> {
       source: auth.source,
       abortSignal: signal,
       workspaceService: {} as never,
-      workflowService: {} as never,
+      versionControlService: {} as never,
       events: {} as never,
       getFilesystem: async () => ({}) as never,
     }) as unknown as ToolContext;

package/src/modules/skills/__tests__/pending-skills.service.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'vitest';
-import { DEFAULT_BRANCH, type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, type ChangeRequest, type IVersionControlService } from '@bevel-software/platform-shared';
 import { PendingSkillsService } from '../pending-skills.service.js';
 import { hashEmail } from '../../../shared/email-identity.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
@@ -74,11 +74,11 @@ function harness(opts: {
     listSkills: async () => opts.released ?? [],
   } as unknown as ISkillService;
 
-  const workflow = {
+  const versionControl = {
     listChangeRequests: async () => opts.crs,
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 
-  return new PendingSkillsService(workspaceService, accessControl, skillService, workflow, testKbContext());
+  return new PendingSkillsService(workspaceService, accessControl, skillService, versionControl, testKbContext());
 }
 
 const ADMIN_WRITES = {
@@ -197,20 +197,20 @@ describe('PendingSkillsService', () => {
   });
 
   /**
-   * This hangs off the library's list load. A workflow service that cannot
+   * This hangs off the library's list load. A version-control service that cannot
    * answer must cost the reader an empty review shelf, not their whole library.
    */
   test('degrades to nothing pending when the change requests cannot be listed', async () => {
-    const workflow = {
+    const versionControl = {
       listChangeRequests: async () => {
         throw new Error('offline');
       },
-    } as unknown as IWorkflowService;
+    } as unknown as IVersionControlService;
     const svc = new PendingSkillsService(
       {} as unknown as WorkspaceService,
       {} as unknown as IAccessControl,
       { listSkills: async () => [] } as unknown as ISkillService,
-      workflow,
+      versionControl,
       testKbContext(),
     );
     await expect(svc.listPendingSkills(AUTHOR)).resolves.toEqual([]);

package/src/modules/skills/__tests__/skill-access-requests.routes.test.ts

@@ -3,7 +3,7 @@ import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { DEFAULT_BRANCH, joinBranchFor } from '@bevel-software/platform-shared';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
@@ -26,8 +26,8 @@ const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
 const MIA = { id: 'u-mia', email: 'mia@x.io', name: 'Mia' };
 const FOLDER = 'Skills/Eng/deploy';
 
-async function makeHarness(listBranches: IWorkflowService['listBranches']) {
-  const workflow = {
+async function makeHarness(listBranches: IVersionControlService['listBranches']) {
+  const versionControl = {
     listChangeRequests: vi.fn(async () => []),
     listBranches: vi.fn(listBranches),
     createBranch: vi.fn(async () => ({ name: 'x', isDefault: false, isProtected: false })),
@@ -35,7 +35,7 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
     commitChanges: vi.fn(async () => null),
     openChangeRequest: vi.fn(async () => ({ number: 42 })),
     getChangeRequestDetail: vi.fn(async () => ({ body: '' })),
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
   const workspaceService = {
     getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: workspaceIdForBranch(branch) })),
     readFile: vi.fn(async () => '---\n---\nwrite:\n  - Eve <eve@x.io>\n'),
@@ -57,8 +57,8 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
     createSkillAccessRequestRoutes({
       skillService,
       accessControl,
-      workflow,
-      requests: new AccessRequestsService({ workflow, workspaceService, lifecycle: joinRequests, kb }),
+      versionControl,
+      requests: new AccessRequestsService({ versionControl, workspaceService, lifecycle: joinRequests, kb }),
       joinRequests,
       kb,
       resolveUser: async () => MIA,
@@ -68,7 +68,7 @@ async function makeHarness(listBranches: IWorkflowService['listBranches']) {
     const s = app.listen(0, () => resolve(s));
   });
   const { port } = server.address() as AddressInfo;
-  return { server, url: `http://127.0.0.1:${port}/api/skills/deploy/access-request`, workflow, workspaceService };
+  return { server, url: `http://127.0.0.1:${port}/api/skills/deploy/access-request`, versionControl, workspaceService };
 }
 
 describe('POST /skills/:name/access-request — the branch probe', () => {
@@ -87,11 +87,11 @@ describe('POST /skills/:name/access-request — the branch probe', () => {
     const res = await fetch(h.url, { method: 'POST' });
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({ ok: true, number: 42 });
-    expect(h.workflow.listBranches).toHaveBeenCalledWith(wsId, { freshFetch: true, strictFetch: true });
-    expect(h.workflow.createBranch).toHaveBeenCalledWith(wsId, joinBranchFor(MIA.email, FOLDER), DEFAULT_BRANCH);
+    expect(h.versionControl.listBranches).toHaveBeenCalledWith(wsId, { freshFetch: true, strictFetch: true });
+    expect(h.versionControl.createBranch).toHaveBeenCalledWith(wsId, joinBranchFor(MIA.email, FOLDER), DEFAULT_BRANCH);
     // The whole chain the probe exists to enable: the grant is written AND committed.
     expect(h.workspaceService.writeFile).toHaveBeenCalledTimes(1);
-    expect(h.workflow.commitChanges).toHaveBeenCalledTimes(1);
+    expect(h.versionControl.commitChanges).toHaveBeenCalledTimes(1);
   });
 
   it('a create that loses the race proceeds once the fresh re-probe shows the branch', async () => {
@@ -99,26 +99,26 @@ describe('POST /skills/:name/access-request — the branch probe', () => {
     // Absent on the first probe, present on the second: someone else cut it in between.
     let probes = 0;
     const h = await makeHarness(async () => (probes++ === 0 ? [] : [{ name: branch, isDefault: false, isProtected: false }]));
-    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('already exists'));
+    (h.versionControl.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('already exists'));
     server = h.server;
     const res = await fetch(h.url, { method: 'POST' });
     expect(res.status).toBe(200);
     expect(await res.json()).toEqual({ ok: true, number: 42 });
-    expect(h.workflow.listBranches).toHaveBeenCalledTimes(2);
+    expect(h.versionControl.listBranches).toHaveBeenCalledTimes(2);
     expect(h.workspaceService.writeFile).toHaveBeenCalledTimes(1);
-    expect(h.workflow.commitChanges).toHaveBeenCalledTimes(1);
+    expect(h.versionControl.commitChanges).toHaveBeenCalledTimes(1);
   });
 
   it('a create that fails with no branch to show for it stops the request — nothing is written on a branch that was not made', async () => {
     vi.spyOn(console, 'error').mockImplementation(() => {});
     const h = await makeHarness(async () => []);
-    (h.workflow.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('origin refused'));
+    (h.versionControl.createBranch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('origin refused'));
     server = h.server;
     const res = await fetch(h.url, { method: 'POST' });
     expect(res.status).toBe(500);
-    expect(h.workflow.listBranches).toHaveBeenCalledTimes(2);
+    expect(h.versionControl.listBranches).toHaveBeenCalledTimes(2);
     expect(h.workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+    expect(h.versionControl.openChangeRequest).not.toHaveBeenCalled();
   });
 
   it('a listing that could not prove anything stops the request before a branch or a byte is written', async () => {
@@ -129,8 +129,8 @@ describe('POST /skills/:name/access-request — the branch probe', () => {
     server = h.server;
     const res = await fetch(h.url, { method: 'POST' });
     expect(res.status).toBe(500);
-    expect(h.workflow.createBranch).not.toHaveBeenCalled();
+    expect(h.versionControl.createBranch).not.toHaveBeenCalled();
     expect(h.workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
+    expect(h.versionControl.openChangeRequest).not.toHaveBeenCalled();
   });
 });

package/src/modules/skills/__tests__/skills.service.test.ts

@@ -12,8 +12,8 @@ import type { IAccessControl } from '../../access/access-control.interface.js';
 import { readFile as fsReadFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
-import { GitService } from '../../workflow/git/git.service.js';
+import { VersionControlHooks } from '../../version-control/version-control-hooks.js';
+import { GitService } from '../../version-control/git/git.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const execFileAsync = promisify(execFile);
@@ -423,7 +423,7 @@ describe('SkillService', () => {
 
     const versioned = (access: IAccessControl = allowAll) => {
       const service = svc(access);
-      service.setHistory(new GitService(workspaceService, new WorkflowHooks(), testKbContext({ kbDirName: KB_DIR })));
+      service.setHistory(new GitService(workspaceService, new VersionControlHooks(), testKbContext({ kbDirName: KB_DIR })));
       return service;
     };
 

package/src/modules/skills/pending-skills.service.ts

@@ -1,4 +1,4 @@
-import type { KbLayout, IWorkflowService } from '@bevel-software/platform-shared';
+import type { KbLayout, IVersionControlService } from '@bevel-software/platform-shared';
 import { type WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from '../access/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
@@ -36,7 +36,7 @@ export class PendingSkillsService implements IPendingSkillService {
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
     private readonly skillService: ISkillService,
-    private readonly workflow: IWorkflowService,
+    private readonly versionControl: IVersionControlService,
     private readonly kb: KbContext,
   ) {}
 
@@ -57,7 +57,7 @@ export class PendingSkillsService implements IPendingSkillService {
       {
         workspaceService: this.workspaceService,
         accessControl: this.accessControl,
-        workflow: this.workflow,
+        versionControl: this.versionControl,
         kb: this.kb,
       },
       userEmail,

package/src/modules/skills/skill-access-requests.routes.ts

@@ -3,10 +3,10 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('skills');
 import '../auth/index.js'; // Express Request.userId / userEmail augmentation
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { IAccessControl, IAccessRequests } from '../access/index.js';
 import { folderTarget } from '../access/index.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import type { JoinRequestsService } from '../plugins/index.js';
@@ -34,14 +34,14 @@ import type { ISkillService } from './skills.contract.js';
 export function createSkillAccessRequestRoutes(deps: {
   skillService: ISkillService;
   accessControl: IAccessControl;
-  workflow: IWorkflowService;
+  versionControl: IVersionControlService;
   /** Opens an access request — the same opener the Manage access dialog uses, wired by the composition root. */
   requests: IAccessRequests;
   joinRequests: JoinRequestsService;
   kb: KbContext;
   resolveUser: (req: express.Request) => Promise<AuthUser | null>;
 }): express.Router {
-  const { skillService, accessControl, workflow, requests, joinRequests, kb, resolveUser } = deps;
+  const { skillService, accessControl, versionControl, requests, joinRequests, kb, resolveUser } = deps;
   const router = express.Router();
   const wsId = () => kb.defaultWorkspaceId();
   const rulesOf = (folder: string) => `${folder}/access.md`;
@@ -85,7 +85,7 @@ export function createSkillAccessRequestRoutes(deps: {
       });
       res.json({ ok: true, number });
     } catch (err) {
-      if (err instanceof WorkflowDomainError) {
+      if (err instanceof VersionControlDomainError) {
         res.status(err.status).json(domainErrorBody(err));
         return;
       }
@@ -113,7 +113,7 @@ export function createSkillAccessRequestRoutes(deps: {
     try {
       const ctx = await requireEditor(req, res, () => res.json({ requests: [] }));
       if (!ctx) return;
-      const crs = await workflow.listChangeRequests();
+      const crs = await versionControl.listChangeRequests();
       res.json({ requests: await joinRequests.list(ctx.folder, folderTarget(ctx.folder), crs, ctx.user) });
     } catch (err) {
       log.error('failed to list access requests:', { err });
@@ -130,7 +130,7 @@ export function createSkillAccessRequestRoutes(deps: {
         res.status(400).json({ error: 'Invalid change request number' });
         return;
       }
-      const cr = await workflow.getChangeRequest(crNumber);
+      const cr = await versionControl.getChangeRequest(crNumber);
       if (!cr) {
         res.status(404).json({ error: 'Not found' });
         return;