@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/modules/tool-manuals/__tests__/tool-manuals.pending.route.test.ts

@@ -0,0 +1,102 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createToolManualsBrowserRoutes } from '../tool-manuals.routes.js';
+import type {
+  IPendingToolService,
+  IToolManualService,
+  PendingTool,
+} from '../tool-manuals.contract.js';
+
+/**
+ * `GET /api/tools/pending` — the library's review shelf for tools.
+ *
+ * Two things this route must get right and nothing else does for it: it is
+ * declared BEFORE `/tools/:slug`, so the parameterised route cannot swallow
+ * `pending` and answer "no such tool"; and the pending service is OPTIONAL, so
+ * a host that composes its own service set answers with an empty shelf rather
+ * than a 404 the frontend would have to special-case.
+ */
+
+const PENDING: PendingTool = {
+  slug: 'weather',
+  name: 'weather',
+  path: 'Plugins/Ops/weather.tool',
+  type: 'http',
+  description: 'Forecasts for a place.',
+  plugin: 'Ops',
+  changeRequestNumber: 7,
+  branch: 'agent/weather',
+  authorName: 'Ali Raza',
+  createdAt: '2026-09-06T09:00:00.000Z',
+  isAuthor: true,
+};
+
+let httpServer: HttpServer | undefined;
+
+/** Mount the browser routes behind a fake auth middleware; `email` undefined ⇒ unauthenticated. */
+async function baseUrlAs(
+  email: string | undefined,
+  pendingTools?: IPendingToolService,
+): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    if (email) req.userEmail = email;
+    next();
+  });
+  // The detail read must never be what answers `/tools/pending`; a service that
+  // throws on any slug is how this test would notice the route order breaking.
+  const toolManualService = {
+    getDetail: async () => {
+      throw new Error('/tools/:slug should not have matched "pending"');
+    },
+  } as unknown as IToolManualService;
+  app.use('/api', createToolManualsBrowserRoutes(toolManualService, undefined, undefined, pendingTools));
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return `http://127.0.0.1:${port}`;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((resolve) => httpServer!.close(() => resolve()));
+  httpServer = undefined;
+});
+
+describe('GET /api/tools/pending', () => {
+  it('serves the caller their visible proposals', async () => {
+    const seen: string[] = [];
+    const base = await baseUrlAs('ali@bevel.software', {
+      listPendingTools: async (email) => {
+        seen.push(email);
+        return [PENDING];
+      },
+    });
+    const res = await fetch(`${base}/api/tools/pending`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ tools: [PENDING] });
+    // The route asks on behalf of the CALLER — the whole visibility rule hangs
+    // off this one argument.
+    expect(seen).toEqual(['ali@bevel.software']);
+  });
+
+  it('refuses an unauthenticated caller without asking the service', async () => {
+    const listPendingTools = vi.fn(async () => [PENDING]);
+    const base = await baseUrlAs(undefined, { listPendingTools });
+    const res = await fetch(`${base}/api/tools/pending`);
+    expect(res.status).toBe(401);
+    // The status alone would still pass if the route asked FIRST and refused
+    // after — and the whole visibility rule is an argument this caller has
+    // not got. Not asking is the guarantee; 401 is only how it reads.
+    expect(listPendingTools).not.toHaveBeenCalled();
+  });
+
+  it('answers with an empty shelf when no pending service is composed', async () => {
+    const base = await baseUrlAs('ali@bevel.software');
+    const res = await fetch(`${base}/api/tools/pending`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ tools: [] });
+  });
+});

package/src/modules/tool-manuals/__tests__/tool-manuals.restart.test.ts

@@ -0,0 +1,285 @@
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, rm, mkdir, writeFile, access } from 'node:fs/promises';
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { KbPluginSource } from '../../plugins/discovery/kb-plugin-source.js';
+import { ToolManualService } from '../tool-manuals.service.js';
+import { McpOAuthDiscoveryService } from '../../secrets-vault/mcp-oauth-discovery.service.js';
+import type { ISecretsVaultService, OAuthProviderConfig } from '../../secrets-vault/secrets-vault.contract.js';
+import { utcpNamespacedKey } from '../../../shared/utcp-namespace.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver } from '../../tool-helpers/tool-context.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import { registerToolManualsTools } from '../tool-manuals.tools.js';
+
+/**
+ * A server restart must not cost a tool or a sign-in. Everything a registered
+ * external tool is made of lives in two durable places — the default branch's
+ * files and the vault's rows — and the catalog is REBUILT from them on the
+ * first request after boot. This drives that path end to end: one "process"
+ * declares, discovers and signs in; a second, built from scratch over the same
+ * disk and the same rows (and nothing else), must list the same tools with the
+ * same sign-ins, without registering a new OAuth client (a new client id would
+ * orphan every stored grant).
+ *
+ * Reproduced on staging for hx-external-tools-survive-restart: `list_tools`,
+ * `list_tool_setup` and every vault row were identical across a container
+ * restart; this is the regression guard for that result.
+ */
+
+const KB_DIR = 'knowledge-base';
+const USER = { id: 'user-1', email: 'user@example.com' };
+const BEARER = 'bevel_user';
+const REDIRECT_URI = 'https://bevel.example.com/api/secrets/oauth/callback';
+
+const AUTO_URL = 'https://mcp.auto.example.com/mcp';
+const MANUAL_URL = 'https://mcp.manual.example.com/mcp';
+const AS = {
+  issuer: 'https://auth.example.com',
+  authorization_endpoint: 'https://auth.example.com/authorize',
+  token_endpoint: 'https://auth.example.com/token',
+  registration_endpoint: 'https://auth.example.com/register',
+};
+
+/**
+ * The vault's durable state as plain rows — what Postgres keeps across a
+ * restart — behind the slice of `ISecretsVaultService` the catalog and the
+ * discovery read. Deliberately nothing process-local: each "process" gets a
+ * fresh wrapper over the SAME rows.
+ */
+interface Row {
+  userId: string | null;
+  key: string;
+  provider?: OAuthProviderConfig;
+  accessToken?: string;
+}
+function vaultOver(rows: Row[]): ISecretsVaultService {
+  const find = (userId: string | null, key: string) => rows.find((r) => r.userId === userId && r.key === key);
+  return {
+    getSharedOAuthProvider: async (key: string) => find(null, key)?.provider ?? null,
+    putSharedOAuthProvider: async (input: { key: string; provider: OAuthProviderConfig }) => {
+      const existing = find(null, input.key);
+      if (existing) existing.provider = input.provider;
+      else rows.push({ userId: null, key: input.key, provider: input.provider });
+    },
+    statusFor: async (userId: string, keys: string[]) =>
+      keys.map((key) => {
+        const own = find(userId, key);
+        return {
+          key,
+          adminConfigured: !!find(null, key),
+          userConfigured: !!own,
+          userAuthorized: own ? Boolean(own.accessToken) : undefined,
+        };
+      }),
+  } as unknown as ISecretsVaultService;
+}
+
+/** The remote servers: both publish OAuth metadata; the AS allows dynamic registration. */
+function remoteServers() {
+  let registrations = 0;
+  const json = (body: unknown, status = 200, headers?: Record<string, string>) =>
+    new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json', ...headers } });
+  const routes: Record<string, () => Response> = {
+    [AUTO_URL]: () =>
+      json({}, 401, {
+        'WWW-Authenticate': 'Bearer resource_metadata="https://mcp.auto.example.com/.well-known/oauth-protected-resource"',
+      }),
+    'https://mcp.auto.example.com/.well-known/oauth-protected-resource': () =>
+      json({ resource: AUTO_URL, authorization_servers: [AS.issuer] }),
+    [MANUAL_URL]: () =>
+      json({}, 401, {
+        'WWW-Authenticate':
+          'Bearer resource_metadata="https://mcp.manual.example.com/.well-known/oauth-protected-resource"',
+      }),
+    'https://mcp.manual.example.com/.well-known/oauth-protected-resource': () =>
+      json({ resource: MANUAL_URL, authorization_servers: [AS.issuer] }),
+    'https://auth.example.com/.well-known/oauth-authorization-server': () => json(AS),
+    [AS.registration_endpoint]: () => json({ client_id: `dcr-client-${++registrations}` }, 201),
+  };
+  const fetchFn = (async (url: unknown) => {
+    const handler = routes[String(url)];
+    return handler ? handler() : new Response('not found', { status: 404 });
+  }) as typeof fetch;
+  return { fetchFn, registrations: () => registrations };
+}
+
+describe('external tools and their sign-ins across a restart', () => {
+  let root: string;
+  const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+  const DRAFT = 'user/add-notes';
+  const disk = new NodeFs();
+  const allowAll = {
+    canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+    canWrite: async () => true,
+  } as unknown as IAccessControl;
+  const servers: HttpServer[] = [];
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'tools-restart-'));
+    // Both servers committed to the default branch in one plugin: one bare
+    // (zero-config OAuth), one naming an owner-registered client id.
+    const plugin = join(root, wsId, KB_DIR, 'Plugins', 'Sales');
+    await mkdir(plugin, { recursive: true });
+    await writeFile(
+      join(plugin, 'mcp.json'),
+      JSON.stringify({
+        mcpServers: {
+          auto_crm: { type: 'streamable-http', url: AUTO_URL },
+          manual_crm: { type: 'streamable-http', url: MANUAL_URL },
+        },
+      }),
+    );
+    await writeFile(
+      join(plugin, 'plugin.json'),
+      JSON.stringify({
+        name: 'sales',
+        extensions: {
+          'software.bevel.hexis': {
+            mcpServers: {
+              manual_crm: {
+                headers: { Authorization: 'Bearer ${CRM_TOKEN}' },
+                variables: [{ name: 'CRM_TOKEN', scope: 'user', oauth: { clientId: 'owner-registered' } }],
+              },
+            },
+          },
+        },
+      }),
+    );
+    // The tester's shape: a third server the agent declared on its own draft
+    // and never merged. It is not live before the restart and must not become
+    // (or stop being reported as) anything else after it.
+    const draftPlugin = join(root, workspaceIdForBranch(DRAFT), KB_DIR, 'Plugins', 'Notes');
+    await mkdir(join(draftPlugin, '..', '..', '.git'), { recursive: true });
+    await mkdir(draftPlugin, { recursive: true });
+    await writeFile(join(draftPlugin, 'mcp.json'), JSON.stringify({ mcpServers: { notes: { type: 'streamable-http', url: 'https://notes.example.com/mcp' } } }));
+    await writeFile(join(draftPlugin, 'plugin.json'), JSON.stringify({ name: 'notes' }));
+  });
+
+  afterEach(async () => {
+    await Promise.all(servers.splice(0).map((s) => new Promise<void>((r) => s.close(() => r()))));
+    await rm(root, { recursive: true, force: true });
+  });
+
+  /**
+   * One server process: every service constructed from scratch, sharing only
+   * the disk and the rows, with `list_tool_setup` mounted through the
+   * production registration and auth/handler machinery and called over HTTP.
+   */
+  async function boot(rows: Row[], fetchFn: typeof fetch) {
+    const workspaceService = {
+      getOrCreateForBranch: async (branch: string) => ({ id: workspaceIdForBranch(branch) }),
+      getWorkspacePath: async (id: string) => join(root, id),
+      // Read from disk, as the real one falls back to after a restart: the
+      // in-process clone map is empty in a fresh process.
+      hasBootstrappedWorkspace: async (id: string) =>
+        access(join(root, id, KB_DIR, '.git')).then(
+          () => true,
+          () => false,
+        ),
+    } as unknown as WorkspaceService;
+    const vault = vaultOver(rows);
+    const catalog = new ToolManualService(workspaceService, allowAll, KB_DIR, disk, new KbPluginSource(disk));
+    catalog.setMcpAuthDiscovery(new McpOAuthDiscoveryService({ secretsVault: vault, redirectUri: REDIRECT_URI, fetchFn }));
+
+    const internalToken = new InternalTokenService({ secret: 'test-secret' });
+    const apiKeys = {
+      looksLikeExternalApiKey: (t: string) => t === BEARER,
+      verifyAndLoadToken: async (t: string) => (t === BEARER ? { user: { ...USER, name: 'User' }, tokenId: 'tok' } : null),
+    } as never;
+    const toolHandler = createToolHandlerFactory(
+      createToolContextResolver({
+        authService: { getUserById: async (id: string) => (id === USER.id ? { ...USER, name: 'User' } : null) } as never,
+        workspaceService: { getWorkspacePath: async () => root } as never,
+        workflowService: {} as never,
+        events: {} as never,
+        kbDirName: KB_DIR,
+        creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },
+      }),
+    );
+    const app = express();
+    app.use(express.json());
+    const router = express.Router();
+    registerToolManualsTools(new ToolRegistry(), router, createToolAuthMiddleware(apiKeys, internalToken), toolHandler, catalog, {
+      accessControl: allowAll,
+      variableStatus: vault,
+    });
+    app.use('/api', router);
+    const server = await new Promise<HttpServer>((r) => {
+      const s = app.listen(0, () => r(s));
+    });
+    servers.push(server);
+    const base = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+
+    /** `list_tool_setup` as the agent calls it, reduced to what a restart could cost. */
+    const setup = async () => {
+      const res = await fetch(`${base}/api/agent/tools/list_tool_setup`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${BEARER}` },
+        body: JSON.stringify({ branch: DRAFT }),
+      });
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as {
+        tools: { name: string; setup: { kind: string } | null; variables: { name: string; authorized: boolean | null }[] }[];
+        onBranchOnly: { name: string; branch: string }[];
+      };
+      return {
+        tools: body.tools.map((t) => ({
+          name: t.name,
+          setup: t.setup?.kind ?? null,
+          variables: t.variables.map((v) => ({ key: utcpNamespacedKey(t.name, v.name), authorized: v.authorized })),
+        })),
+        onBranchOnly: body.onBranchOnly.map((p) => ({ name: p.name, branch: p.branch })),
+      };
+    };
+    return { catalog, setup };
+  }
+
+  test('every server, its vault keys and the sign-ins are unchanged after a restart', async () => {
+    const rows: Row[] = [];
+    const remote = remoteServers();
+
+    // ── Before the restart: discover, set up, sign in. ──
+    const first = await boot(rows, remote.fetchFn);
+    const discovered = (await first.setup()).tools;
+    const autoKey = discovered.find((t) => t.name === 'auto_crm')!.variables[0].key;
+    const manualKey = discovered.find((t) => t.name === 'manual_crm')!.variables[0].key;
+    // The owner saved the client secret for the declared client; the user
+    // completed both sign-ins (a token on their own row under each key).
+    rows.push({ userId: null, key: manualKey, provider: { authorizationUrl: AS.authorization_endpoint, tokenUrl: AS.token_endpoint, clientId: 'owner-registered' } });
+    rows.push({ userId: USER.id, key: autoKey, accessToken: 'tok-auto' });
+    rows.push({ userId: USER.id, key: manualKey, accessToken: 'tok-manual' });
+    const before = await first.setup();
+    expect(before).toEqual({
+      tools: [
+        { name: 'auto_crm', setup: 'oauth-auto', variables: [{ key: autoKey, authorized: true }] },
+        { name: 'manual_crm', setup: 'oauth-manual', variables: [{ key: manualKey, authorized: true }] },
+      ],
+      onBranchOnly: [{ name: 'notes', branch: DRAFT }],
+    });
+    expect(remote.registrations()).toBe(1);
+    const rowsBefore = structuredClone(rows);
+
+    // ── Restart: nothing in memory survives; a new process boots over the same disk and rows. ──
+    const second = await boot(rows, remote.fetchFn);
+    expect(await second.setup()).toEqual(before);
+    // Same call templates too — what `list_tools` registers per request.
+    expect((await second.catalog.toManualCallTemplates(USER.email)).map((t) => t.name).sort()).toEqual([
+      'auto_crm',
+      'manual_crm',
+    ]);
+    // The grant stays keyed by what it was keyed by: the stored client is
+    // reused, never re-registered, and no row was rewritten.
+    expect(remote.registrations()).toBe(1);
+    expect(rows).toEqual(rowsBefore);
+  });
+});

package/src/modules/tool-manuals/__tests__/tool-manuals.service.test.ts

@@ -1,4 +1,9 @@
-import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { KbPluginSource } from '../../plugins/discovery/kb-plugin-source.js';
+
+/** The one disk, as production wires it: the service and its discovery read the same one. */
+const disk = new NodeFs();
 import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -64,7 +69,7 @@ describe('ToolManualService', () => {
       new Map(paths.map((p) => [p, !p.includes('weather')])),
   } as unknown as IAccessControl;
 
-  const svc = (access: IAccessControl = allowAll) => new ToolManualService(workspaceService, access, KB_DIR);
+  const svc = (access: IAccessControl = allowAll) => new ToolManualService(workspaceService, access, KB_DIR, disk, new KbPluginSource(disk));
 
   beforeEach(async () => {
     root = await mkdtemp(join(tmpdir(), 'tools-'));
@@ -228,6 +233,107 @@ describe('ToolManualService', () => {
     ]);
   });
 
+  /**
+   * A bad manual costs its author their own tool and NOBODY ELSE anything.
+   *
+   * Asserted here rather than taken on trust because the refresh work makes
+   * the catalog re-scan far more often — on every default-branch commit rather
+   * than once a minute — so a broken file is now read, and skipped, many times
+   * more often than it used to be. One file that could take the listing down
+   * would take it down constantly.
+   */
+  test('a `.tool` that cannot be read or parsed, beside good ones, costs only itself', async () => {
+    const tools = join(root, wsId, KB_DIR, 'Plugins');
+    // Four ways a manual can be wrong. Three are about its CONTENT: unparseable
+    // bytes, a valid document that is not a manual, and a manual with an
+    // invalid field.
+    await writeFile(join(tools, 'truncated.tool'), '{ "name": "truncated", "type": "htt');
+    await writeFile(join(tools, 'nottool.tool'), JSON.stringify({ hello: 'world' }));
+    await writeFile(
+      join(tools, 'badscope.tool'),
+      JSON.stringify({ name: 'badscope', type: 'http', url: 'https://x/m', variables: [{ name: 'K', scope: 'root' }] }),
+    );
+    // The fourth is the scan failing to READ the file at all — a separate
+    // branch from parsing, and the one a permissions mistake or a half-written
+    // checkout actually produces. A directory with a `.tool` name is the
+    // honest way to induce it: the walk lists it, and the read throws EISDIR
+    // with no mocking anywhere near the code under test.
+    await mkdir(join(tools, 'adirectory.tool'), { recursive: true });
+
+    const list = await svc().listAccessible('user@x.eu');
+    expect(list.map((m) => m.name).sort()).toEqual(['billing', 'weather']);
+    // And the valid ones are still usable, not merely counted.
+    expect(list.find((m) => m.name === 'billing')!.type).toBe('http');
+  });
+
+  /**
+   * The catalog fingerprint — what `GET /api/agent/catalog-revision` hashes,
+   * and therefore what decides whether a long-lived MCP client re-registers.
+   *
+   * The hard half is the change that is invisible in a listing: a `.tool` that
+   * keeps its name, path, type and description while its `url`, its headers or
+   * an inline manual's embedded tools change is a DIFFERENT callable thing,
+   * and a client still holding the old definition has to be told. Hence the
+   * source digest on the line; these pin that it is there and that it is not
+   * so eager it fires on a scan of a file nobody touched.
+   */
+  describe('catalogFingerprints', () => {
+    const tools = () => join(root, wsId, KB_DIR, 'Plugins');
+    const line = async (access = allowAll) =>
+      (await svc(access).catalogFingerprints('user@x.eu')).find((l) => l.includes('billing'))!;
+
+    test('is stable across scans of a catalog nobody touched', async () => {
+      expect(await line()).toBe(await line());
+    });
+
+    test.each([
+      ['its url', { name: 'billing', type: 'http', url: 'https://api.example.com/moved' }],
+      [
+        'a header',
+        {
+          name: 'billing',
+          type: 'http',
+          url: 'https://api.example.com/utcp',
+          headers: { Authorization: 'Bearer ${BILLING_KEY}', 'X-Tenant': 'acme' },
+        },
+      ],
+    ])('moves when %s changes, though no listing field did', async (_what, rewritten) => {
+      const before = await line();
+      await writeFile(join(tools(), 'billing.tool'), JSON.stringify(rewritten));
+
+      const after = await line();
+      expect(after).not.toBe(before);
+      // The point of the case: nothing a person browsing the catalog sees has
+      // changed, so a fingerprint built from the summary alone would not move.
+      const [summary] = (await svc().listAccessible('user@x.eu')).filter((m) => m.name === 'billing');
+      expect([summary.slug, summary.name, summary.path, summary.type, summary.description]).toEqual([
+        'billing',
+        'billing',
+        'Plugins/billing.tool',
+        'http',
+        undefined,
+      ]);
+    });
+
+    test("moves when an inline manual's embedded tools change", async () => {
+      const inlineLine = async () =>
+        (await svc().catalogFingerprints('user@x.eu')).find((l) => l.includes('weather'))!;
+      const before = await inlineLine();
+
+      const withAnother = JSON.parse(INLINE_TOOL);
+      withAnother.tools.push({ ...withAnother.tools[0], name: 'historical' });
+      await writeFile(join(tools(), 'weather.tool'), JSON.stringify(withAnother));
+
+      expect(await inlineLine()).not.toBe(before);
+    });
+
+    test('drops a line for a manual the caller cannot read', async () => {
+      const lines = await svc(denyBilling).catalogFingerprints('user@x.eu');
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain('weather');
+    });
+  });
+
   test('skips a `.tool` with a malformed `variables` entry (never silently mis-scoped)', async () => {
     root = await mkdtemp(join(tmpdir(), 'toolsvbad-'));
     const tools = join(root, wsId, KB_DIR, 'Plugins');
@@ -607,3 +713,73 @@ describe('ToolManualService', () => {
     expect(preview.errors?.length).toBeGreaterThan(0);
   });
 });
+
+describe('ToolManualService.listDeclaredOnlyOnBranch', () => {
+  let root: string;
+  const DRAFT = 'user/add-crm';
+  const draftWs = workspaceIdForBranch(DRAFT);
+
+  /** Cloned here: the default branch, the draft, and `user/gone` (its remote branch since deleted). */
+  const cloned = new Set([wsId, draftWs, workspaceIdForBranch('user/gone')]);
+  const getOrCreateForBranch = vi.fn(async (branch: string) => {
+    if (branch === 'user/gone') throw new Error('branch does not exist');
+    return { id: workspaceIdForBranch(branch) };
+  });
+  const workspaceService = {
+    getOrCreateForBranch,
+    hasBootstrappedWorkspace: async (id: string) => cloned.has(id),
+    getWorkspacePath: async (id: string) => join(root, id),
+  } as unknown as WorkspaceService;
+
+  /** Reads everything on the default branch; on the draft, everything but `Secret Plugin`. */
+  const readGate = {
+    canReadBatch: async (ws: string, _e: string, paths: string[]) =>
+      new Map(paths.map((p) => [p, ws !== draftWs || !p.startsWith('Plugins/Secret Plugin/')])),
+  } as unknown as IAccessControl;
+
+  const writeMcpJson = async (ws: string, plugin: string, servers: string[]) => {
+    const dir = join(root, ws, KB_DIR, 'Plugins', plugin);
+    await mkdir(dir, { recursive: true });
+    const mcpServers = Object.fromEntries(
+      servers.map((s) => [s, { type: 'streamable-http', url: `https://${s.replace(/_/g, '-')}.example.com/mcp` }]),
+    );
+    await writeFile(join(dir, 'mcp.json'), JSON.stringify({ mcpServers }));
+    await writeFile(join(dir, 'plugin.json'), JSON.stringify({ name: plugin.toLowerCase().replace(/ /g, '-') }));
+  };
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'tools-branch-'));
+    // Released: `billing`. The draft carries it too (an edit), plus two new servers,
+    // one of them in a plugin the caller cannot read on that branch.
+    await writeMcpJson(wsId, 'Sales', ['billing']);
+    await writeMcpJson(draftWs, 'Sales', ['billing', 'crm']);
+    await writeMcpJson(draftWs, 'Secret Plugin', ['hidden']);
+  });
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const svc = () => new ToolManualService(workspaceService, readGate, KB_DIR, disk, new KbPluginSource(disk));
+
+  test('names only the readable declarations the default branch does not serve', async () => {
+    expect(await svc().listDeclaredOnlyOnBranch('user@example.com', DRAFT)).toEqual([
+      { name: 'crm', path: 'Plugins/Sales/mcp.json', type: 'mcp' },
+    ]);
+  });
+
+  test('is empty for the default branch itself and for a branch without a workspace', async () => {
+    expect(await svc().listDeclaredOnlyOnBranch('user@example.com', DEFAULT_BRANCH)).toEqual([]);
+    expect(await svc().listDeclaredOnlyOnBranch('user@example.com', 'user/gone')).toEqual([]);
+  });
+
+  test('never bootstraps a branch this process holds no clone of', async () => {
+    getOrCreateForBranch.mockClear();
+    expect(await svc().listDeclaredOnlyOnBranch('user@example.com', 'someone/private-guess')).toEqual([]);
+    expect(getOrCreateForBranch).not.toHaveBeenCalledWith('someone/private-guess');
+  });
+
+  test('the released catalog never includes the draft declaration', async () => {
+    expect((await svc().listAccessible('user@example.com')).map((m) => m.name)).toEqual(['billing']);
+  });
+});