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

package/src/modules/kb-sync/__tests__/kb-sync.service.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
 import { KbSyncService } from '../kb-sync.service.js';
-import type { SyncWorkflowPort, SyncWorkspacePort } from '../kb-sync.interface.js';
+import type { SyncVersionControlPort, SyncWorkspacePort } from '../kb-sync.interface.js';
 
 function deferred<T>() {
   let resolve!: (v: T) => void;
@@ -24,7 +24,7 @@ function updated(branch: string): BranchSyncOutcome {
 describe('KbSyncService', () => {
   it('answers the sync without waiting for the tidy-up after it', async () => {
     let finish = (): void => undefined;
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
       // A tidy-up that never ends unless told to — and one that fails.
@@ -36,36 +36,36 @@ describe('KbSyncService', () => {
         .mockRejectedValueOnce(new Error('boom')),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main']));
+    const svc = new KbSyncService(versionControl, workspaces(['main']));
     await expect(svc.sync({ branches: 'all' })).resolves.toMatchObject({ status: 'synced' });
-    expect(workflow.tidyAfterSweep).toHaveBeenCalledTimes(1);
+    expect(versionControl.tidyAfterSweep).toHaveBeenCalledTimes(1);
     await expect(svc.sync({ branches: 'all' })).resolves.toMatchObject({ status: 'synced' });
     finish();
   });
 
   it('syncs every known clone for an "all" request and reports unknown branches as not cloned', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x']));
 
     const all = await svc.sync({ branches: 'all' });
     expect(all.status).toBe('synced');
     expect(all.results.map((r) => r.branch)).toEqual(['main', 'ali/x']);
     expect(all.changeRequests.closedDeletedBranch).toBe(1);
     // Every sweep for deleted branches is followed by the leftover cleanup.
-    expect(workflow.tidyAfterSweep).toHaveBeenCalledTimes(1);
-    expect(workflow.syncWorkspaceFromRemote).toHaveBeenCalledWith('ali%2Fx');
+    expect(versionControl.tidyAfterSweep).toHaveBeenCalledTimes(1);
+    expect(versionControl.syncWorkspaceFromRemote).toHaveBeenCalledWith('ali%2Fx');
 
     const some = await svc.sync({ branches: ['ali/x', 'juan/other'] });
     expect(some.results).toEqual([updated('ali/x'), { branch: 'juan/other', outcome: 'not-cloned' }]);
   });
 
   it('a conflict or an error makes the result partial; the other branches still sync', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> =>
         id === 'main'
           ? { branch: 'main', outcome: 'conflict', conflictedPaths: ['a.md'], error: 'msg' }
@@ -75,14 +75,14 @@ describe('KbSyncService', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x']));
     const r = await svc.sync({ branches: 'all' });
     expect(r.status).toBe('partial');
     expect(r.results[1]).toEqual(updated('ali/x'));
   });
 
   it('a failing sweep does not fail the sync', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async () => updated('main')),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => {
         throw new Error('origin down');
@@ -90,7 +90,7 @@ describe('KbSyncService', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main']));
+    const svc = new KbSyncService(versionControl, workspaces(['main']));
     const r = await svc.sync({ branches: 'all' });
     expect(r.status).toBe('synced');
     expect(r.changeRequests.closedDeletedBranch).toBe(0);
@@ -103,7 +103,7 @@ describe('KbSyncService', () => {
     // landing after the gate opened.
     const calls: string[][] = [['']];
     let gateOpened = false;
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         const branch = decodeURIComponent(id);
         if (!gateOpened && branch === 'main') {
@@ -120,7 +120,7 @@ describe('KbSyncService', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x', 'juan/y']));
 
     const first = svc.sync({ branches: ['main'] });
     // Three requests land while the first is parked on `gate`.
@@ -137,12 +137,12 @@ describe('KbSyncService', () => {
     expect(r2.results.map((r) => r.branch)).toEqual(['ali/x']);
     expect(r3.results.map((r) => r.branch)).toEqual(['juan/y']);
     expect(r4.results.map((r) => r.branch)).toEqual(['ali/x']);
-    expect(workflow.closeChangeRequestsWithDeletedBranches).toHaveBeenCalledTimes(2);
+    expect(versionControl.closeChangeRequestsWithDeletedBranches).toHaveBeenCalledTimes(2);
   });
 
   it('an "all" arriving mid-run absorbs the queued branches', async () => {
     const gate = deferred<void>();
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         if (id === 'main') await gate.promise;
         return updated(decodeURIComponent(id));
@@ -151,7 +151,7 @@ describe('KbSyncService', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x', 'juan/y']));
     const first = svc.sync({ branches: ['main'] });
     const second = svc.sync({ branches: ['ali/x'] });
     const third = svc.sync({ branches: 'all' });
@@ -166,14 +166,14 @@ describe('KbSyncService', () => {
 
 describe('KbSyncService.lastSync', () => {
   it('is null before the first sync, then records when, who and what', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     let clock = 1_000;
-    const svc = new KbSyncService(workflow, workspaces(['main']), () => clock);
+    const svc = new KbSyncService(versionControl, workspaces(['main']), () => clock);
     expect(svc.lastSync()).toBeNull();
 
     await svc.sync({ branches: 'all', by: 'bearer' });
@@ -191,7 +191,7 @@ describe('KbSyncService.lastSync', () => {
 
   it('a coalesced follow-up names everyone who asked for it', async () => {
     const gate = deferred<void>();
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         if (id === 'main') await gate.promise;
         return updated(decodeURIComponent(id));
@@ -200,7 +200,7 @@ describe('KbSyncService.lastSync', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x']));
     const first = svc.sync({ branches: ['main'], by: 'bearer' });
     const second = svc.sync({ branches: ['ali/x'], by: 'github-signature' });
     const third = svc.sync({ branches: ['ali/x'], by: 'admin@example.com' });
@@ -212,7 +212,7 @@ describe('KbSyncService.lastSync', () => {
 
 describe('KbSyncService — a throwing branch step', () => {
   it('becomes an error outcome; the other branches, the sweep and the record all still happen', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         if (id === 'main') throw new Error('fatal: unable to access https://x:ghp_secret@host/r');
         return updated(decodeURIComponent(id));
@@ -221,7 +221,7 @@ describe('KbSyncService — a throwing branch step', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x']));
     const r = await svc.sync({ branches: 'all', by: 'bearer' });
     expect(r.status).toBe('partial');
     expect(r.results[0]).toMatchObject({ branch: 'main', outcome: 'error' });
@@ -233,8 +233,8 @@ describe('KbSyncService — a throwing branch step', () => {
 });
 
 describe('KbSyncService — clones the host no longer has, and clones that cannot be read', () => {
-  it('a remote-gone branch is retired through the workflow, counts as clean, and does not stop the others', async () => {
-    const workflow: SyncWorkflowPort = {
+  it('a remote-gone branch is retired through version control, counts as clean, and does not stop the others', async () => {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> =>
         id === 'ali%2Fx' ? { branch: 'ali/x', outcome: 'remote-gone' } : updated(decodeURIComponent(id)),
       ),
@@ -242,16 +242,16 @@ describe('KbSyncService — clones the host no longer has, and clones that canno
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['ali/x', 'main']));
+    const svc = new KbSyncService(versionControl, workspaces(['ali/x', 'main']));
     const r = await svc.sync({ branches: 'all' });
     expect(r.status).toBe('synced');
     expect(r.results).toEqual([{ branch: 'ali/x', outcome: 'remote-gone' }, updated('main')]);
-    expect(workflow.retireRemoteGoneClone).toHaveBeenCalledTimes(1);
-    expect(workflow.retireRemoteGoneClone).toHaveBeenCalledWith('ali%2Fx');
+    expect(versionControl.retireRemoteGoneClone).toHaveBeenCalledTimes(1);
+    expect(versionControl.retireRemoteGoneClone).toHaveBeenCalledWith('ali%2Fx');
   });
 
   it('a clone that could not be read is that branch’s error, not everyone’s', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
@@ -263,21 +263,21 @@ describe('KbSyncService — clones the host no longer has, and clones that canno
         { id: 'juan%2Fy', branch: 'juan/y', unreadable: "Could not read this branch's clone: EPERM" },
       ],
     };
-    const svc = new KbSyncService(workflow, port);
+    const svc = new KbSyncService(versionControl, port);
     const r = await svc.sync({ branches: 'all' });
     expect(r.status).toBe('partial');
     expect(r.results).toEqual([
       updated('main'),
       { branch: 'juan/y', outcome: 'error', error: "Could not read this branch's clone: EPERM" },
     ]);
-    expect(workflow.syncWorkspaceFromRemote).toHaveBeenCalledTimes(1);
+    expect(versionControl.syncWorkspaceFromRemote).toHaveBeenCalledTimes(1);
   });
 });
 
 describe('KbSyncService — a coalesced caller is judged by its own branches', () => {
   it("branch A's hook is not failed by branch B's conflict in the same follow-up", async () => {
     const gate = deferred<void>();
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> => {
         if (id === 'main') await gate.promise;
         if (id === 'juan%2Fy') return { branch: 'juan/y', outcome: 'conflict', conflictedPaths: ['a.md'], error: 'msg' };
@@ -287,7 +287,7 @@ describe('KbSyncService — a coalesced caller is judged by its own branches', (
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x', 'juan/y']));
     const first = svc.sync({ branches: ['main'] });
     const hookA = svc.sync({ branches: ['ali/x'] });
     const hookB = svc.sync({ branches: ['juan/y'] });
@@ -306,7 +306,7 @@ describe('KbSyncService — a coalesced caller is judged by its own branches', (
 describe('KbSyncService — a waiter keeps the branches it asked for', () => {
   it('a caller that edits its array after queueing changes nothing about its sync or its answer', async () => {
     const gate = deferred<void>();
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         if (id === 'main') await gate.promise;
         return updated(decodeURIComponent(id));
@@ -315,7 +315,7 @@ describe('KbSyncService — a waiter keeps the branches it asked for', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x', 'juan/y']));
     const first = svc.sync({ branches: ['main'] });
     const asked = ['ali/x'];
     const waiting = svc.sync({ branches: asked });
@@ -325,6 +325,6 @@ describe('KbSyncService — a waiter keeps the branches it asked for', () => {
     await first;
     const r = await waiting;
     expect(r.results.map((x) => x.branch)).toEqual(['ali/x']);
-    expect(workflow.syncWorkspaceFromRemote).not.toHaveBeenCalledWith('juan%2Fy');
+    expect(versionControl.syncWorkspaceFromRemote).not.toHaveBeenCalledWith('juan%2Fy');
   });
 });

package/src/modules/kb-sync/index.ts

@@ -3,7 +3,7 @@ export type {
   LastSync,
   SyncRequest,
   SyncResult,
-  SyncWorkflowPort,
+  SyncVersionControlPort,
   SyncWorkspacePort,
 } from './kb-sync.interface.js';
 export { KbSyncService } from './kb-sync.service.js';

package/src/modules/kb-sync/kb-sync.interface.ts

@@ -5,7 +5,7 @@ import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
  * Hexis "the repository changed" and Hexis brings the clones it holds up to
  * date. The module owns the HTTP surface, the credential check, the payload
  * parsing and the coalescing; every git operation happens behind the
- * workflow port below, never here.
+ * version-control port below, never here.
  */
 
 /** Which branches a caller asked to sync. `'all'` = every clone Hexis holds. */
@@ -51,8 +51,8 @@ export interface IKbSyncService {
   lastSync(): LastSync | null;
 }
 
-/** The slice of the workflow module a sync drives. */
-export interface SyncWorkflowPort {
+/** The slice of the version-control module a sync drives. */
+export interface SyncVersionControlPort {
   syncWorkspaceFromRemote(workspaceId: string): Promise<BranchSyncOutcome>;
   /**
    * Retire the clone of a branch the host deleted, under the branch-lifecycle

package/src/modules/kb-sync/kb-sync.service.ts

@@ -2,13 +2,13 @@ import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('sync');
-import { sanitizeError } from '../workflow/index.js';
+import { sanitizeError } from '../version-control/index.js';
 import type {
   IKbSyncService,
   LastSync,
   SyncRequest,
   SyncResult,
-  SyncWorkflowPort,
+  SyncVersionControlPort,
   SyncWorkspacePort,
 } from './kb-sync.interface.js';
 
@@ -44,7 +44,7 @@ export class KbSyncService implements IKbSyncService {
   private last: LastSync | null = null;
 
   constructor(
-    private readonly workflow: SyncWorkflowPort,
+    private readonly versionControl: SyncVersionControlPort,
     private readonly workspaces: SyncWorkspacePort,
     private readonly now: () => number = () => Date.now(),
   ) {}
@@ -152,9 +152,9 @@ export class KbSyncService implements IKbSyncService {
       }
       let outcome: BranchSyncOutcome;
       try {
-        outcome = await this.workflow.syncWorkspaceFromRemote(id);
+        outcome = await this.versionControl.syncWorkspaceFromRemote(id);
       } catch (err) {
-        // The workflow step promises outcomes, not throws — but one broken
+        // The version-control sync step promises outcomes, not throws — but one broken
         // clone must never take the other branches, the sweep, or every
         // coalesced caller down with it, so the promise is enforced here too.
         const message = sanitizeError(err);
@@ -165,11 +165,11 @@ export class KbSyncService implements IKbSyncService {
       if (outcome.outcome === 'remote-gone') {
         // The host deleted the branch. Left in place, the stale clone would
         // fail its fetch on every following full sync — and a webhook host
-        // disables a subscription that keeps failing. The workflow retires it
+        // disables a subscription that keeps failing. The version-control service retires it
         // under the branch-lifecycle lock, after asking origin again, so a
         // branch recreated since the pull keeps its clone. Best-effort.
         try {
-          const removed = await this.workflow.retireRemoteGoneClone(id);
+          const removed = await this.versionControl.retireRemoteGoneClone(id);
           if (removed) log.info(`removed the clone of "${branch}" — deleted on the host`);
           else log.info(`kept the clone of "${branch}" — it is back on the host, or already gone`);
         } catch (err) {
@@ -183,7 +183,7 @@ export class KbSyncService implements IKbSyncService {
     // pointed at it. Best-effort — it fails safe by closing nothing.
     let closedDeletedBranch = 0;
     try {
-      closedDeletedBranch = await this.workflow.closeChangeRequestsWithDeletedBranches();
+      closedDeletedBranch = await this.versionControl.closeChangeRequestsWithDeletedBranches();
     } catch (err) {
       log.warn('deleted-branch sweep failed:', { err });
     }
@@ -192,7 +192,7 @@ export class KbSyncService implements IKbSyncService {
     // large repository, and the sync (often a webhook with a short timeout)
     // must not wait on it. It never throws; the catch is for a mock or a
     // future change that does.
-    void this.workflow.tidyAfterSweep().catch((err: unknown) => log.warn('post-sync tidy-up failed:', { err }));
+    void this.versionControl.tidyAfterSweep().catch((err: unknown) => log.warn('post-sync tidy-up failed:', { err }));
 
     const result: SyncResult = {
       status: KbSyncService.statusOf(results),

package/src/modules/marketplace/__tests__/github-facade.test.ts

@@ -9,7 +9,7 @@ import express from 'express';
 import type { AuthUser } from '@bevel-software/platform-shared';
 
 import { MarketplaceRepoService, type MarketplaceCompiler } from '../marketplace-repo.service.js';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import {
   GitHubFacadeCredentialsService,
   GitHubFacade,

package/src/modules/marketplace/__tests__/marketplace-git.test.ts

@@ -10,7 +10,7 @@ import type { AuthUser } from '@bevel-software/platform-shared';
 
 import { MarketplaceRepoService, type MarketplaceCompiler } from '../marketplace-repo.service.js';
 import { createMarketplaceGitRoutes } from '../git-http.routes.js';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import type { VirtualTree } from '../../plugins/compile/compile-marketplace.js';
 
 const execFileAsync = promisify(execFile);

package/src/modules/mcp/__tests__/mcp-proxy-helpers.test.ts

@@ -6,8 +6,8 @@ import {
   flattenDiscoveredTool,
   toCallToolResult,
   toListedTool,
-} from '../mcp.service.js';
-import type { ProxiedTool } from '../mcp.service.js';
+} from '@bevel-software/platform-mcp-core';
+import type { ProxiedTool } from '@bevel-software/platform-mcp-core';
 
 function utcpTool(name: string, bodyProps: Record<string, unknown>, required: string[] = []): UtcpTool {
   return {
@@ -72,8 +72,10 @@ describe('toListedTool', () => {
     const listed = toListedTool(proxied({ mcpName: 'gmail_send_email' }));
     expect(listed).toEqual({
       name: 'gmail_send_email',
+      title: 'Gmail send email',
       description: 'Call: m.t({})\n\na tool',
       inputSchema: { type: 'object', properties: {} },
+      annotations: { readOnlyHint: false },
     });
   });
 

package/src/modules/mcp/__tests__/mcp.e2e.test.ts

@@ -12,16 +12,15 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createMcpRoutes } from '../mcp.routes.js';
 import { McpService } from '../mcp.service.js';
-import { SpillStore } from '../../workspace/spill-store.js';
-import { createManualRoutes } from '../../tool-registry/manual.routes.js';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { toolDef } from '../../tool-helpers/tool-def.js';
+import { SpillStore } from '../../workspace/index.js';
+import { ToolRegistry, createManualRoutes } from '../../tool-registry/index.js';
+import { toolDef } from '../../tool-helpers/index.js';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { platformInstructions } from '../../agent-instructions/index.js';
 import { startFakeDownstreamMcpServer, type FakeDownstreamMcpServer } from './fake-downstream-mcp-server.js';
-import { registerBevelSecretsVariableLoader } from '../../secrets-vault/secrets-variable-loader.js';
-import type { ForcedRefreshOutcome, ISecretsVaultService } from '../../secrets-vault/secrets-vault.contract.js';
-import type { IToolManualService } from '../../tool-manuals/tool-manuals.contract.js';
+import { registerBevelSecretsVariableLoader } from '../../secrets-vault/index.js';
+import type { ForcedRefreshOutcome, ISecretsVaultService } from '../../secrets-vault/index.js';
+import type { IToolManualService } from '../../tool-manuals/index.js';
 import { setLogger } from '../../../shared/logging.js';
 import type { ILogger } from '../../../shared/logger.contract.js';
 import { formatProbeReport, probeFirstCall } from '../first-call-probe.js';
@@ -117,6 +116,8 @@ interface PlatformOptions {
   /** Bind this port — how a "restarted" platform comes back at the same address. */
   port?: number;
   readAgentPreamble?: () => Promise<string | null>;
+  /** The default branch the instructions name, read per request as the composition root wires it. */
+  defaultBranch?: () => string;
   /** Extra manuals the catalog serves each caller (beyond the KB manual). */
   manualsFor?: (bearer: string) => unknown[];
   poolNow?: () => number;
@@ -185,6 +186,7 @@ async function startPlatform(opts: PlatformOptions = {}): Promise<Platform> {
     spillStore: new SpillStore(join(tmpdir(), 'bevel-test-spills')),
     publicFrontendUrl: 'http://localhost:5173',
     readAgentPreamble: opts.readAgentPreamble,
+    defaultBranch: opts.defaultBranch,
     downstreamPool: opts.poolNow ? { now: opts.poolNow } : undefined,
   }, opts.secretsVault, opts.toolManuals);
   const stub = {} as never;
@@ -487,11 +489,28 @@ describe('agent instructions over the real transport', () => {
   it('the initialize result carries the platform text and the preamble body inline', async () => {
     const { baseUrl } = await startPlatform({
       readAgentPreamble: async () => 'Acme builds solar farms.\n\n<!-- private -->Look in Projects/ first.',
+      defaultBranch: () => 'target-company-state',
     });
     const { client } = await connectSdkClient(baseUrl);
     const instructions = client.getInstructions();
-    expect(instructions).toBe(`${platformInstructions(DEFAULT_KB_LAYOUT)}\n\nAcme builds solar farms.\n\nLook in Projects/ first.`);
+    expect(instructions).toBe(
+      `${platformInstructions(DEFAULT_KB_LAYOUT, 'target-company-state')}\n\nAcme builds solar farms.\n\nLook in Projects/ first.`,
+    );
     expect(instructions).not.toContain('private');
+    // The deployment's default branch, by its own name — not `main`.
+    expect(instructions).toContain("This knowledge base's default branch is `target-company-state`");
+  });
+
+  it('a default branch renamed between two initializes is the one the second names', async () => {
+    let branch = 'target-company-state';
+    const { baseUrl } = await startPlatform({ defaultBranch: () => branch });
+    const { client: before } = await connectSdkClient(baseUrl);
+    branch = 'company-state';
+    const { client: after } = await connectSdkClient(baseUrl);
+    expect(after.getInstructions()).toContain("This knowledge base's default branch is `company-state`");
+    expect(after.getInstructions()).not.toContain('target-company-state');
+    // Nothing else moved: the text is the old one with the name swapped.
+    expect(after.getInstructions()).toBe(before.getInstructions()!.replaceAll('target-company-state', 'company-state'));
   });
 
   it('a later initialize on the SAME process after the file changed carries the new text — read per request', async () => {
@@ -651,6 +670,7 @@ describe('proxied third-party MCP servers: a rejected token gets one refresh and
     } as unknown as ISecretsVaultService;
     registerBevelSecretsVariableLoader(vault);
     const toolManuals = {
+      sharedSignInKeysForManual: async () => [],
       userScopedKeysForManual: async (manual: string) =>
         manual === 'notion' ? [{ key: KEY, name: 'ACCESS_TOKEN', label: 'Notion sign-in', oauth: true }] : [],
     } as unknown as IToolManualService;
@@ -770,6 +790,45 @@ describe('proxied third-party MCP servers: a rejected token gets one refresh and
     expect(refreshLines(logs)[0]).toContain('manual=\\"notion\\" user=\\"user-A\\" outcome=rejected');
   });
 
+  it('a WORKSPACE connection rejected on refresh tells the caller a tool owner has to reconnect it, and does not retry', async () => {
+    quiet();
+    let valid = 'token-1';
+    downstream = await startFakeDownstreamMcpServer({ acceptsToken: (t) => t === valid });
+    // The same sign-in, declared as one shared connection: the manual reports
+    // it under `sharedSignInKeysForManual`, the vault under the owner's row.
+    const state = { token: 'token-1' as string | null, refreshes: 0 };
+    const vault = {
+      resolve: async (_userId: string, key: string) => (key === KEY ? state.token : null),
+      statusFor: async (_userId: string, keys: string[]) =>
+        keys.map((key) => ({ key, adminConfigured: true, adminKind: 'oauth', userConfigured: false, adminAuthorized: state.token !== null })),
+      forceRefresh: async (_userId: string, key: string) => {
+        expect(key).toBe(KEY);
+        state.refreshes += 1;
+        state.token = null;
+        return 'rejected' as const;
+      },
+    } as unknown as ISecretsVaultService;
+    registerBevelSecretsVariableLoader(vault);
+    const toolManuals = {
+      sharedSignInKeysForManual: async (manual: string) =>
+        manual === 'notion' ? [{ key: KEY, name: 'ACCESS_TOKEN', label: 'Notion sign-in' }] : [],
+      userScopedKeysForManual: async () => [],
+    } as unknown as IToolManualService;
+    const { baseUrl } = await startPlatform({ manualsFor: notionManual(downstream), secretsVault: vault, toolManuals });
+    const { client } = await connectSdkClient(baseUrl);
+    await client.callTool({ name: 'notion_srv_echo', arguments: { text: 'one' } });
+
+    valid = 'nothing-valid-any-more';
+
+    const res = await client.callTool({ name: 'notion_srv_echo', arguments: { text: 'two' } });
+    expect(res.isError).toBe(true);
+    expect(toolText(res)).toContain('The workspace connection for "notion" was rejected by the provider and has been disconnected');
+    expect(toolText(res)).toContain('A tool owner has to reconnect it on http://localhost:5173/connect');
+    expect(toolText(res)).not.toContain('Your sign-in');
+    expect(state.refreshes).toBe(1);
+    expect(downstream.executions()).toBe(1); // nothing was retried against a dead workspace grant
+  });
+
   it('transient refresh failure: the original error comes back, the token is kept, and a later call tries again', async () => {
     quiet();
     let now = 1_000_000;
@@ -940,6 +999,7 @@ describe('proxied third-party MCP servers: a rejected token gets one refresh and
     const { state, vault } = fakeSignIn('token-1', () => 'refreshed');
     const boom = new Error('catalog read failed\u009b31m\nerror: forged by the manual name\u2028tail');
     const toolManuals = {
+      sharedSignInKeysForManual: async () => [],
       userScopedKeysForManual: async (manual: string) => {
         if (broken) throw boom;
         return manual === 'notion' ? [{ key: KEY, name: 'ACCESS_TOKEN', label: 'Notion sign-in', oauth: true }] : [];
@@ -1061,6 +1121,7 @@ describe('proxied third-party MCP servers: a rejected token gets one refresh and
     } as unknown as ISecretsVaultService;
     registerBevelSecretsVariableLoader(withKind);
     const toolManuals = {
+      sharedSignInKeysForManual: async () => [],
       userScopedKeysForManual: async (manual: string) =>
         manual === 'notion' ? [{ key: KEY, name: 'ACCESS_TOKEN', label: 'Notion key', oauth: false }] : [],
     } as unknown as IToolManualService;