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

package/src/modules/kb-fs/repo-path.ts

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { sanitizedPath } from '../../shared/printable.js';
 
 /**
  * Workspace-relative paths and the repository folder.
@@ -20,6 +21,51 @@ import { WorkflowValidationError } from '../../shared/domain-errors.js';
  * rule were allowed to exist.
  */
 
+/**
+ * NUL, the C0 controls (a line break among them) and DEL — refused in a
+ * workspace path wherever one enters.
+ *
+ * Not merely hygiene about names nobody can type. A `\n` is a SEPARATOR in
+ * git's own line-oriented stdin protocols: `cat-file --batch` reads one
+ * `<ref>:<path>` object name per LINE, so `Docs/secret.md\nzzz` is TWO specs.
+ * Everything upstream — the read gate, the download gate, the not-a-directory
+ * check — is then asked about the whole string, which names nothing, while git
+ * answers about `Docs/secret.md` and hands over its bytes. A file denied by
+ * its own frontmatter inside a folder its reader may list would be readable
+ * that way, and in a batch of several specs the extra answer shifts every
+ * result after it, so the access resolver reads one directory's `access.md` as
+ * another's.
+ *
+ * Refused HERE, at the normaliser every accepted path goes through, rather
+ * than at each route: the fence has to be at the mechanism, because the next
+ * caller to assemble a git spec from a path will not remember this. The
+ * shared `validateFilename` has always refused the same range per segment, so
+ * no name any surface can create is lost — this closes the gap between it and
+ * the paths that reach git. U+2028/U+2029 are NOT in it: they are nothing to
+ * git's protocols (which read bytes, and a line break there is 0x0A), a name
+ * carrying one is creatable today, and refusing it here would make an existing
+ * file unreadable. They are escaped for display instead, which is what
+ * `sanitizedPath` is for.
+ */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\x00-\x1F\x7F]/;
+
+/**
+ * Whether `value` carries one of them — THE predicate, so the places that
+ * accept a NAME enforce the same rule as the normaliser that joins it into a
+ * path. The checkout folder name is the one that matters: it is not a caller's
+ * path, it is deployment configuration (`KB_DIR_NAME`, and the `kbDirName`
+ * setting), and it is PREFIXED onto every workspace-relative path. A name with
+ * a line break in it would therefore make the normaliser emit exactly the path
+ * this rule exists to exclude, from inputs that were each clean. Refused where
+ * the name is set — at boot in `core-config` and in the settings validator —
+ * so the deployment fails loudly instead of serving a path nothing downstream
+ * can safely read.
+ */
+export function hasControlCharacter(value: string): boolean {
+  return CONTROL_CHARACTERS.test(value);
+}
+
 /**
  * True when `wsPath` is the repository folder or lies under it.
  *
@@ -33,6 +79,10 @@ import { WorkflowValidationError } from '../../shared/domain-errors.js';
  */
 export function isInsideRepo(wsPath: string, kbDirName: string): boolean {
   if (typeof wsPath !== 'string' || wsPath.includes('\\')) return false;
+  // A control character is not a spelling of any path under the repository —
+  // see {@link CONTROL_CHARACTERS}. Refused here too, so the check AFTER the
+  // normaliser cannot pass one that somehow skipped it.
+  if (CONTROL_CHARACTERS.test(wsPath)) return false;
   const segments = wsPath.replace(/\/$/, '').split('/');
   if (segments[0] !== kbDirName) return false;
   return segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..');
@@ -52,6 +102,22 @@ export function isInsideRepo(wsPath: string, kbDirName: string): boolean {
  */
 export function assertInsideRepo(wsPath: string, kbDirName: string): void {
   if (isInsideRepo(wsPath, kbDirName)) return;
+  // Said as what it is, before the suggestion below: a control character is
+  // not a path that landed in the wrong place, and a "use this instead"
+  // carrying an invisible character back to the caller would be nonsense.
+  if (typeof wsPath === 'string' && CONTROL_CHARACTERS.test(wsPath)) {
+    // Through `sanitizedPath`, like every other refusal that names a path: the
+    // character that makes this path invalid is also the character that would
+    // forge a second line of the answer, in the message and in the `path` a
+    // JSON consumer reads.
+    const shown = sanitizedPath(wsPath);
+    throw new WorkflowValidationError(
+      `"${shown}" contains a control character: a line break, a NUL or another invisible byte is not part of any ` +
+        'file name, and git reads a line break in a path as the end of one object name and the start of another. ' +
+        'Remove it and send the name as it is written.',
+      { kind: 'path-control-character', path: shown, kbDirName },
+    );
+  }
   // The suggestion collapses what made the path wrong: backslashes, leading
   // `./` or `/`, and any `..` climbing back out (a bare `..` included, so the
   // suggestion is never itself a climb). The agent gets a path it can use.
@@ -103,6 +169,25 @@ export function normalizeWorkspacePath(wsPath: string, kbDirName: string): strin
   // `\` separates segments on Windows, so `foo\..\..` is a climb this cannot
   // read. Refused before anything is collapsed, never rewritten to `/`.
   if (wsPath.includes('\\')) refuse();
+  // A line break (or any other control character) is a SEPARATOR to git, not
+  // part of a name — see {@link CONTROL_CHARACTERS}. Refused before the path
+  // is normalised, so no gate downstream is ever asked about a string that
+  // means one thing to it and two things to git.
+  if (CONTROL_CHARACTERS.test(wsPath)) refuse();
+  // …and the FOLDER NAME, which is prefixed onto the result rather than read
+  // from it: a clean path joined to `kb\nname` comes out carrying the line
+  // break, so the normaliser would itself emit what the check above refuses.
+  // Said as the configuration error it is — the caller's path is fine, and an
+  // operator reading a refusal about their own path would have nothing to fix.
+  // `core-config` and the `kbDirName` setting validator both refuse this at
+  // the point it is SET, so reaching here means the two drifted.
+  if (CONTROL_CHARACTERS.test(kbDirName)) {
+    throw new WorkflowValidationError(
+      `the configured checkout folder name (kbDirName / KB_DIR_NAME) contains a control character: "${sanitizedPath(kbDirName)}". ` +
+        'Every workspace path is prefixed with it, so no path can be resolved until the setting is corrected.',
+      { kind: 'kb-dir-name-control-character', kbDirName: sanitizedPath(kbDirName) },
+    );
+  }
   // The root-anchored form, and ONLY for the repository folder: `/<kbDirName>/…`
   // is what the app's Copy path gives (it is the form a Markdown link resolves
   // from) and names the same workspace path. `/tmp/x` and `//x` are not that

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

@@ -4,6 +4,7 @@ import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createKbSyncRoutes, isSyncRawBodyPath } from '../kb-sync.routes.js';
 import type { IKbSyncService, SyncResult } from '../kb-sync.interface.js';
+import { AuthBackendError } from '../../auth/account-admission.js';
 
 const SECRET = 'a-very-long-and-random-sync-secret';
 
@@ -23,6 +24,8 @@ async function mount(opts: {
   secret?: string;
   result?: SyncResult;
   admin?: boolean;
+  /** No account can be looked up: every session check fails as the database being down. */
+  outage?: boolean;
   /** Install the production-shaped global JSON parser in front of the router. */
   globalJson?: boolean;
 }): Promise<{ base: string; sync: ReturnType<typeof vi.fn> }> {
@@ -44,7 +47,8 @@ async function mount(opts: {
       kbSync,
       syncSecret: () => opts.secret ?? SECRET,
       authService: {
-        verifyToken: (token: string) => {
+        resolveSession: async (token: string) => {
+          if (opts.outage) throw new AuthBackendError(new Error('the database is down'));
           if (token !== 'jwt-ok') throw new Error('bad token');
           return { userId: 'u1', email: 'person@example.com' };
         },
@@ -94,6 +98,27 @@ describe('POST /api/sync — credentials', () => {
     expect((await post(person.base, { headers: { authorization: 'Bearer jwt-ok' } })).status).toBe(401);
   });
 
+  it('500, not 401, when the session’s account cannot be looked up', async () => {
+    const { base, sync } = await mount({ admin: true, outage: true });
+    const res = await post(base, { headers: { authorization: 'Bearer jwt-ok' } });
+    // An outage is not a wrong credential: a 401 would send the admin to sign in again.
+    expect(res.status).toBe(500);
+    expect(res.headers.get('www-authenticate')).toBeNull();
+    expect(sync).not.toHaveBeenCalled();
+  });
+
+  it('the shared secret still works while accounts cannot be looked up', async () => {
+    const { base, sync } = await mount({ outage: true });
+    expect((await post(base, { headers: { authorization: `Bearer ${SECRET}` } })).status).toBe(200);
+    expect(sync).toHaveBeenCalledTimes(1);
+  });
+
+  it('a request with no credential is still a 401 during an outage', async () => {
+    const { base } = await mount({ outage: true });
+    // No bearer at all: nothing was looked up, so nothing failed.
+    expect((await post(base)).status).toBe(401);
+  });
+
   it('accepts the GitLab token header', async () => {
     const { base } = await mount({});
     const res = await post(base, { headers: { 'x-gitlab-token': SECRET } });

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

@@ -7,6 +7,7 @@ import { assertValidBranchName } from '../kb-fs/branch-name.js';
 import type { IKbSyncService, SyncResult } from './kb-sync.interface.js';
 import { parseSyncPayload, type SyncPayloadSource } from './sync-payload.js';
 import { verifySyncCredential } from './sync-auth.js';
+import { AuthBackendError } from '../auth/account-admission.js';
 
 /**
  * Remote sync — a git host or a pipeline tells Hexis the repository changed.
@@ -45,7 +46,7 @@ export interface KbSyncRouteDeps {
   kbSync: IKbSyncService;
   /** The configured secret, read per request so a setup-screen save applies at once. */
   syncSecret: () => string;
-  authService: { verifyToken(token: string): { userId: string; email: string } };
+  authService: { resolveSession(token: string): Promise<{ userId: string; email: string }> };
   adminAccess: IAdminAccessService;
 }
 
@@ -107,6 +108,7 @@ export function createKbSyncRoutes(deps: KbSyncRouteDeps): express.Router {
   ): Promise<void> {
     res.setHeader(SYNC_RESPONSE_HEADER, SYNC_RESPONSE_MARKER);
     const raw: Buffer | undefined = Buffer.isBuffer(req.body) ? req.body : undefined;
+    let lookupFailed: AuthBackendError | null = null as AuthBackendError | null;
 
     const auth = await verifySyncCredential(
       {
@@ -117,10 +119,11 @@ export function createKbSyncRoutes(deps: KbSyncRouteDeps): express.Router {
         rawBody: raw,
       },
       {
-        verifyJwt: (token) => {
+        verifyJwt: async (token) => {
           try {
-            return { email: deps.authService.verifyToken(token).email };
-          } catch {
+            return { email: (await deps.authService.resolveSession(token)).email };
+          } catch (err) {
+            if (err instanceof AuthBackendError) lookupFailed = err;
             return null;
           }
         },
@@ -128,6 +131,13 @@ export function createKbSyncRoutes(deps: KbSyncRouteDeps): express.Router {
       },
     );
     if (!auth.ok) {
+      // The session's account could not be looked up: an outage, not a wrong
+      // credential, and saying 401 would send an admin to sign in again.
+      if (lookupFailed) {
+        log.error('session account lookup failed:', { err: lookupFailed.cause });
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+        return;
+      }
       if (auth.status === 401) res.setHeader('WWW-Authenticate', 'Bearer realm="hexis-sync"');
       res.status(auth.status).json({ error: auth.message });
       return;

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

@@ -42,7 +42,7 @@ export interface SyncAuthInput {
 
 export interface SyncSessionVerifier {
   /** Resolve a browser JWT to its email, or null when it is not one. */
-  verifyJwt(token: string): { email: string } | null;
+  verifyJwt(token: string): { email: string } | null | Promise<{ email: string } | null>;
   isAdmin(email: string): Promise<boolean>;
 }
 
@@ -98,7 +98,7 @@ export async function verifySyncCredential(
   // An admin's own session, carried as the bearer. Checked after the secret
   // so a secret that happens to parse as a JWT is never mistaken for one.
   if (bearer) {
-    const claim = session.verifyJwt(bearer);
+    const claim = await session.verifyJwt(bearer);
     if (claim && (await session.isAdmin(claim.email))) {
       return { ok: true, credential: { kind: 'admin-session', email: claim.email } };
     }

package/src/modules/mcp/__tests__/mcp-auth.middleware.test.ts

@@ -5,6 +5,7 @@ import type { AuthService } from '../../auth/auth.service.js';
 import type { IExternalApiKeyService } from '../../tool-auth/external-api-key.interface.js';
 import type { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
 import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
+import { AccountDeactivatedError, AuthBackendError } from '../../auth/account-admission.js';
 
 const RESOURCE_METADATA_URL = 'https://bevel.example/.well-known/oauth-protected-resource/api/mcp';
 
@@ -19,10 +20,14 @@ function makeReqRes(authorization?: string) {
 }
 
 function makeAuthService(verify?: (t: string) => { userId: string; email: string }) {
+  const verifyToken = vi.fn(verify ?? (() => {
+    throw new Error('invalid');
+  }));
   return {
-    verifyToken: vi.fn(verify ?? (() => {
-      throw new Error('invalid');
-    })),
+    verifyToken,
+    // The session path checks the account is still on; every account here is.
+    resolveSession: vi.fn(async (t: string) => verifyToken(t)),
+    isActive: vi.fn(async () => true),
   } as unknown as AuthService;
 }
 
@@ -424,3 +429,55 @@ describe('createMcpAuthMiddleware', () => {
     });
   });
 });
+
+describe('createMcpAuthMiddleware — a switched-off account', () => {
+  const internal = new InternalTokenService({ secret: 'test-secret-32-bytes-long-enough!!' });
+
+  it('401s a session whose account was switched off, and says why', async () => {
+    const auth = makeAuthService();
+    (auth.resolveSession as ReturnType<typeof vi.fn>) = vi.fn(async () => {
+      throw new AccountDeactivatedError();
+    });
+    const { req, res, next, status, json } = makeReqRes('Bearer some.jwt.token');
+    await makeMw({ auth })(req, res, next);
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(401);
+    expect(json.mock.calls[0][0].error).toContain('switched off');
+  });
+
+  it('500s — not 401s — when the session account cannot be looked up', async () => {
+    const auth = makeAuthService();
+    (auth.resolveSession as ReturnType<typeof vi.fn>) = vi.fn(async () => {
+      throw new AuthBackendError(new Error('db down'));
+    });
+    const { req, res, next, status } = makeReqRes('Bearer some.jwt.token');
+    await makeMw({ auth })(req, res, next);
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(500);
+  });
+
+  it('401s an internal token whose account was switched off, and says why', async () => {
+    const token = internal.mint({ userId: 'user-7', externalProxy: true }, 60_000);
+    const auth = makeAuthService();
+    (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({ id: 'user-7', email: 'seven@example.com' }));
+    (auth.isActive as ReturnType<typeof vi.fn>) = vi.fn(async () => false);
+    const { req, res, next, status, json } = makeReqRes(`Bearer ${token}`);
+    await makeMw({ internal, auth })(req, res, next);
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(401);
+    expect(json.mock.calls[0][0].error).toContain('switched off');
+  });
+
+  it('500s — not 401s — when an internal token\'s account cannot be looked up', async () => {
+    const token = internal.mint({ userId: 'user-7', externalProxy: true }, 60_000);
+    const auth = makeAuthService();
+    (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({ id: 'user-7', email: 'seven@example.com' }));
+    (auth.isActive as ReturnType<typeof vi.fn>) = vi.fn(async () => {
+      throw new Error('db down');
+    });
+    const { req, res, next, status } = makeReqRes(`Bearer ${token}`);
+    await makeMw({ internal, auth })(req, res, next);
+    expect(next).not.toHaveBeenCalled();
+    expect(status).toHaveBeenCalledWith(500);
+  });
+});

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

@@ -16,7 +16,8 @@ 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 { PLATFORM_HEADER } from '../../agent-instructions/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';
@@ -483,13 +484,13 @@ describe('per-request identity: catalog, metering and continuity', () => {
 });
 
 describe('agent instructions over the real transport', () => {
-  it('the initialize result carries the header and the preamble body inline', async () => {
+  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.',
     });
     const { client } = await connectSdkClient(baseUrl);
     const instructions = client.getInstructions();
-    expect(instructions).toBe(`${PLATFORM_HEADER}\n\nAcme builds solar farms.\n\nLook in Projects/ first.`);
+    expect(instructions).toBe(`${platformInstructions(DEFAULT_KB_LAYOUT)}\n\nAcme builds solar farms.\n\nLook in Projects/ first.`);
     expect(instructions).not.toContain('private');
   });
 

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

@@ -11,9 +11,13 @@ 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 { PLATFORM_HEADER, TOOL_PREFIX_LINE } from '../../agent-instructions/index.js';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { TOOL_PREFIX_LINE, platformInstructions, sharedRulesPointer } from '../../agent-instructions/index.js';
 import type { AgentEventInput, IAgentEventRecorder } from '../../audit/audit.contract.js';
 
+/** The platform-owned part of the handshake text: the header plus the shared file rules. */
+const PLATFORM = platformInstructions(DEFAULT_KB_LAYOUT);
+
 /**
  * End-to-end proxy test: a real express app serving the registry-driven tool
  * surface over loopback, a real per-request `UtcpClient` discovering it, and a
@@ -24,6 +28,8 @@ import type { AgentEventInput, IAgentEventRecorder } from '../../audit/audit.con
 
 let httpServer: HttpServer | undefined;
 const cleanups: Array<() => Promise<void>> = [];
+/** Every loopback call the skill routes saw this test, in order — with its body. */
+let skillRequests: { tool: string; body: Record<string, unknown> }[] = [];
 
 // Module-hosted tool endpoints + their registered defs: a stand-in echo `ask`
 // (mirrors the real `{text, sessionId}` contract) and an erroring `boom`.
@@ -49,6 +55,7 @@ async function setup(deps?: {
   /** The agent connection an OAuth caller arrived through (with `tokenId: null`). */
   connectionId?: string | null;
 }) {
+  skillRequests = [];
   const registry = new ToolRegistry();
   registry.registerExternalTool(
     toolDef({
@@ -99,9 +106,47 @@ async function setup(deps?: {
   // The two the Audit log's skill classification reads through: a catalog of
   // one skill, and a file read that answers for any path (registered as
   // tools only by the tests that need them, via `extraTools`).
-  app.post('/api/agent/tools/list_skills', (_req, res) =>
-    res.json({ skills: [{ name: 'rfi', description: 'RFI answers', path: 'Plugins/Sales/rfi' }] }),
-  );
+  //
+  // Both skill routes answer like the real ones: a `branch` in the body reads
+  // that draft (an extra, unmerged skill), no `branch` reads the released
+  // catalog. Every call is recorded, so a test can assert which of the two the
+  // prompt surface asked for.
+  const RFI_BODY = '# RFI\n\nAnswer the RFI.';
+  app.post('/api/agent/tools/list_skills', (req, res) => {
+    const b = (req.body ?? {}) as Record<string, unknown>;
+    skillRequests.push({ tool: 'list_skills', body: b });
+    const released = [{ name: 'rfi', description: 'RFI answers', path: 'Plugins/Sales/rfi' }];
+    res.json({
+      skills:
+        typeof b.branch === 'string'
+          ? [
+              ...released,
+              { name: 'make-deck', description: 'Decks.', path: 'Plugins/make-deck', unmerged: true, branch: b.branch },
+            ]
+          : released,
+    });
+  });
+  app.post('/api/agent/tools/get_skill', (req, res) => {
+    const b = (req.body ?? {}) as Record<string, unknown>;
+    skillRequests.push({ tool: 'get_skill', body: b });
+    if (b.name !== 'rfi' && typeof b.branch !== 'string') {
+      res.json({ ok: false, error: 'not_found' });
+      return;
+    }
+    const unmergedLine =
+      typeof b.branch === 'string' ? `This skill is read from the unmerged branch "${b.branch}" and is not approved.\n\n` : '';
+    res.json({
+      ok: true,
+      kind: 'skill',
+      skill: {
+        name: b.name,
+        description: 'RFI answers',
+        path: 'Plugins/Sales/rfi',
+        body: `${unmergedLine}${RFI_BODY}`,
+        files: [],
+      },
+    });
+  });
   app.post('/api/agent/tools/read_file', (req, res) => {
     const b = (req.body ?? {}) as { path?: string };
     res.json({ content: `contents of ${b.path}` });
@@ -221,6 +266,25 @@ describe('McpService (UTCP→MCP proxy)', () => {
     expect(askSchema.properties.body?.properties?.prompt).toBeDefined();
   });
 
+  it('ends the served call_tool_chain description with the shared-rules pointer', async () => {
+    // What a chained read does to an IMAGE is one of the rules the file tools
+    // share, so it is stated once — in the handshake instructions and in the
+    // managed guide — and the chain, like every file tool, ends with the one
+    // sentence saying where. The clients that drop `instructions` have only
+    // descriptions to go on, so that sentence is their way to the rule.
+    const client = await setup();
+    const { tools } = await client.listTools();
+    const chain = tools.find((t) => t.name === 'call_tool_chain')!;
+    const pointer = sharedRulesPointer(DEFAULT_KB_LAYOUT);
+    expect(chain.description!.endsWith(pointer)).toBe(true);
+    // Once, and not on the two meta-tools that describe the registry rather
+    // than a file.
+    expect(chain.description!.split(pointer)).toHaveLength(2);
+    for (const name of ['list_tools', 'tools_info']) {
+      expect(tools.find((t) => t.name === name)!.description, name).not.toContain(pointer);
+    }
+  });
+
   it('a $defs/$ref tool schema survives tools/list and a real MCP client accepts it', async () => {
     // No tokenId filter for this assertion — an OAuth-style session lists all.
     const client = await setup({ tokenId: null });
@@ -493,6 +557,23 @@ describe('McpService — per-user credential pre-check', () => {
       expect(await toolNames(client)).toEqual(['ask', 'boom', 'call_tool_chain', 'list_tools', 'refy', 'tools_info']);
     });
 
+    /**
+     * The worked example in `call_tool_chain`'s description has to be derived
+     * from the tools THIS caller is actually served. Derived from the unfiltered
+     * catalog it could name a credential-gated tool the filter just removed —
+     * an example a connection-key caller copies and cannot call at all.
+     */
+    it('never writes the worked example against a tool it just hid', async () => {
+      const hidden = await setup({ secretsVault: vault(false), toolManuals: manualsWithUserVar });
+      const chain = (await hidden.listTools()).tools.find((t) => t.name === 'call_tool_chain')!;
+      expect(chain.description).not.toMatch(/return KNOWLEDGE_BASE\.\w+\(/);
+      // The same catalog, with the credential set, does print one — so the
+      // assertion above is the filter at work, not an example that never exists.
+      const served = await setup({ secretsVault: vault(true), toolManuals: manualsWithUserVar });
+      const shown = (await served.listTools()).tools.find((t) => t.name === 'call_tool_chain')!;
+      expect(shown.description).toMatch(/return KNOWLEDGE_BASE\.\w+\(/);
+    });
+
     it('keeps the full listing for an OAuth/JWT session (tokenId null) — the caller configures interactively', async () => {
       const client = await setup({
         secretsVault: vault(false),
@@ -507,17 +588,17 @@ describe('McpService — per-user credential pre-check', () => {
 describe('McpService — agent instructions', () => {
   const KB_TOOLS = ['start_session', 'grep', 'list_files', 'read_file'];
 
-  it('sends the header and the preamble as the session\'s instructions', async () => {
+  it("sends the platform text and the preamble as the session's instructions", async () => {
     const client = await setup({ readAgentPreamble: async () => 'Acme builds solar farms.\n\nProjects live in Projects/.' });
-    expect(client.getInstructions()).toBe(`${PLATFORM_HEADER}\n\nAcme builds solar farms.\n\nProjects live in Projects/.`);
+    expect(client.getInstructions()).toBe(`${PLATFORM}\n\nAcme builds solar farms.\n\nProjects live in Projects/.`);
   });
 
-  it('sends the header alone when no reader is wired', async () => {
+  it('sends the platform text alone when no reader is wired', async () => {
     const client = await setup();
-    expect(client.getInstructions()).toBe(PLATFORM_HEADER);
+    expect(client.getInstructions()).toBe(PLATFORM);
   });
 
-  it('a throwing reader still yields a session, with the header as its instructions and a warning', async () => {
+  it('a throwing reader still yields a session, with the platform text as its instructions and a warning', async () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
     const client = await setup({
       readAgentPreamble: async () => {
@@ -525,7 +606,7 @@ describe('McpService — agent instructions', () => {
       },
       extraTools: KB_TOOLS,
     });
-    expect(client.getInstructions()).toBe(PLATFORM_HEADER);
+    expect(client.getInstructions()).toBe(PLATFORM);
     // The error itself rides along, so a terminal shows its stack.
     expect(warn).toHaveBeenCalledWith(
       expect.stringContaining('mcp-description.md'),
@@ -773,10 +854,31 @@ describe('McpService — the Audit log records what an agent calls', () => {
   it('records a prompt read as a skill, with an error outcome when the skill is unknown', async () => {
     const recorder = spyRecorder();
     const client = await setup({ auditRecorder: recorder });
-    // The harness serves no get_skill endpoint, so every prompt is unknown here.
-    await expect(client.getPrompt({ name: 'rfi' })).rejects.toThrow(/Unknown skill/);
+    // A name the harness's catalog does not have: get_skill answers not_found.
+    await expect(client.getPrompt({ name: 'nope' })).rejects.toThrow(/Unknown skill/);
     await settle();
-    expect(recorder.events[0]).toMatchObject({ kind: 'skill', name: 'rfi', outcome: 'error' });
+    expect(recorder.events[0]).toMatchObject({ kind: 'skill', name: 'nope', outcome: 'error' });
+  });
+
+  /**
+   * Prompts ARE skills, and a skill offered as a prompt is one the
+   * organisation released: the two prompt handlers name no branch, so a draft's
+   * skills never reach a client's slash-command menu.
+   */
+  it('serves prompts from the default branch only, never a draft', async () => {
+    const client = await setup();
+    const { prompts } = await client.listPrompts();
+    expect(prompts.map((p) => p.name)).toEqual(['rfi']);
+
+    const got = await client.getPrompt({ name: 'rfi' });
+    const text = got.messages[0].content.text as string;
+    expect(text).toContain('Answer the RFI.');
+    expect(text).not.toContain('unmerged');
+
+    // The loopback bodies prove it: had either handler passed a branch, the
+    // harness would have answered with the draft's skill and its notice.
+    expect(skillRequests.map((r) => r.tool)).toEqual(['list_skills', 'get_skill']);
+    expect(skillRequests.every((r) => r.body.branch === undefined)).toBe(true);
   });
 
   it('records a call refused for a missing sign-in as denied, without running the tool', async () => {

package/src/modules/mcp/mcp-auth.middleware.ts

@@ -4,6 +4,7 @@ import { logger } from '../../shared/logging.js';
 const log = logger('mcp-auth');
 import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import type { AuthService } from '../auth/auth.service.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, AccountDeactivatedError, AuthBackendError } from '../auth/account-admission.js';
 import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
 import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
 import { rejectConnectionKey } from '../tool-auth/connection-key-rejection.js';
@@ -170,8 +171,10 @@ export function createMcpAuthMiddleware(
         return;
       }
       let user;
+      let active = false;
       try {
         user = await authService.getUserById(claim.userId);
+        if (user) active = await authService.isActive(user.id);
       } catch (err) {
         log.error('internal-token user lookup failed:', { err });
         res.status(500).json({ error: 'Authentication backend unavailable' });
@@ -181,6 +184,10 @@ export function createMcpAuthMiddleware(
         unauthorized(res, 'Invalid or expired internal token');
         return;
       }
+      if (!active) {
+        unauthorized(res, ACCOUNT_DEACTIVATED_MESSAGE);
+        return;
+      }
       req.userId = user.id;
       req.userEmail = user.email;
       // The local server's exchanged grant names its agent connection (see
@@ -214,13 +221,20 @@ export function createMcpAuthMiddleware(
     // JWT path — same logic as `createAuthMiddleware` in modules/auth, kept
     // duplicated rather than imported because that one writes its own 401
     // body shape and we want the WWW-Authenticate header set.
+    let session: { userId: string; email: string };
     try {
-      const { userId, email } = authService.verifyToken(token);
-      req.userId = userId;
-      req.userEmail = email;
-      next();
-    } catch {
-      unauthorized(res, 'Invalid or expired token');
+      session = await authService.resolveSession(token);
+    } catch (err) {
+      if (err instanceof AuthBackendError) {
+        log.error('session account lookup failed:', { err: err.cause });
+        res.status(500).json({ error: 'Authentication backend unavailable' });
+        return;
+      }
+      unauthorized(res, err instanceof AccountDeactivatedError ? err.message : 'Invalid or expired token');
+      return;
     }
+    req.userId = session.userId;
+    req.userEmail = session.email;
+    next();
   };
 }