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

package/src/modules/database/migrate.ts

@@ -1,9 +1,11 @@
 import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import { sql } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('database');
-import { DEFAULT_DB_SCHEMA, dbSchemaOf, type Database } from './connection.js';
+import { DEFAULT_DB_SCHEMA, dbSchemaOf, piiKeysOf, type Database } from './connection.js';
 import { AdvisoryLock, withAdvisoryLock } from './advisory-lock.js';
+import { PII_SEALED_SHAPE_SQL_REGEX, isEncryptedBlob, type PiiKeys } from '../../shared/column-crypto.js';
 
 /*
  * ── Per-tier migration folders ──────────────────────────────────────────────
@@ -69,6 +71,9 @@ export async function runCoreMigrations(db: Database, folder: string): Promise<v
       log.info('Running core database migrations...');
       await migrate(db, { migrationsFolder: folder, migrationsTable: '__drizzle_migrations_core', migrationsSchema });
       log.info('Core migrations complete.');
+      // Under the same lock, before anything reads or writes a PII column:
+      // the data half of migration 0016, which SQL cannot do (see below).
+      await runPiiEncryptionBackfill(db);
     },
     { tenantKey },
   );
@@ -96,3 +101,350 @@ export async function runEnterpriseMigrations(db: Database, folder: string): Pro
     { tenantKey },
   );
 }
+
+/*
+ * ── PII column encryption backfill ──────────────────────────────────────────
+ *
+ * Migration 0016 adds the `*_bidx` columns; the DATA change — rewriting
+ * pre-existing plaintext PII to AES-256-GCM ciphertext and filling the blind
+ * indexes — happens here, programmatically, because it needs the key the
+ * handle holds (SQL migrations cannot encrypt). Runs on every start right after
+ * the core history, under the migrations lock, and is idempotent: sealed rows
+ * carry the `PII_CIPHERTEXT_PREFIX` marker and are excluded by the SELECT's
+ * own WHERE clause, so a completed backfill degenerates to one cheap,
+ * empty-result query per table.
+ *
+ * Concurrency: the migrations lock (keyed per tenant, like the history it
+ * guards) serialises two processes booting at once. Each UPDATE is also
+ * compare-and-swap — the WHERE clause pins every value the row was read with
+ * — so a writer that slips in between the scan and the write (an old-version
+ * instance in a mixed-version window) loses nothing: the CAS update matches
+ * zero rows and the next start's pass seals whatever that writer left
+ * behind. Deployments should still stop the old app before starting the new
+ * one (see UPGRADING.md); the lock and CAS make the failure mode of not doing
+ * so "unsealed until next start", never "silently overwritten".
+ *
+ * Once every row is sealed, the same transaction applies the constraints that
+ * could not ship in the SQL migration: SET NOT NULL on the bidx columns and
+ * the unique-index swaps (`users_email_unique` on the now-randomized
+ * ciphertext is meaningless, `users_email_bidx_unq` takes over; the same for
+ * the approvals and the join requests). The new unique index goes up BEFORE
+ * the old one is dropped so duplicate protection never has a gap. Legacy rows
+ * that collide under the normalized blind index are handled first: duplicate
+ * approval and join-request rows (the same logical row, a case-variant email)
+ * are collapsed; duplicate USERS are a genuine account conflict and abort the
+ * start with the row ids so an operator can merge them deliberately. All
+ * statements are IF-EXISTS-guarded — re-running is a no-op.
+ *
+ * Runs against whatever schema the handle searches first: a tenant's own, or
+ * `public`, under that handle's key. Every table name is unqualified for that
+ * reason.
+ *
+ * This is the one place that works on the STORED form. The handle's
+ * connection opens every sealed value of a result, which here would hide
+ * exactly what has to be told apart — so the columns are read as bytes
+ * ({@link asStored}), which it leaves alone, and written as ready-made
+ * ciphertext, which it passes through.
+ */
+
+interface PiiBackfillTable {
+  table: string;
+  /** Columns that uniquely identify a row for the write-back UPDATE. */
+  key: string[];
+  /** Columns whose plaintext values get rewritten as ciphertext. */
+  encrypted: string[];
+  /** Blind-index column to fill from the plaintext of `source`. */
+  bidx?: { source: string; column: string };
+}
+
+const PII_BACKFILL_TABLES: PiiBackfillTable[] = [
+  { table: 'users', key: ['id'], encrypted: ['email', 'name', 'avatar_url'], bidx: { source: 'email', column: 'email_bidx' } },
+  { table: 'pr_file_approvals', key: ['id'], encrypted: ['approver_email', 'approver_name'], bidx: { source: 'approver_email', column: 'approver_email_bidx' } },
+  { table: 'pr_merge_log', key: ['id'], encrypted: ['triggered_by_email', 'triggered_by_name', 'error'], bidx: { source: 'triggered_by_email', column: 'triggered_by_email_bidx' } },
+  { table: 'pr_comments', key: ['id'], encrypted: ['author_email', 'author_name', 'body'], bidx: { source: 'author_email', column: 'author_email_bidx' } },
+  { table: 'change_requests', key: ['id'], encrypted: ['author_email', 'author_name', 'title', 'body', 'apply_failure_reason', 'apply_failed_by_name'], bidx: { source: 'author_email', column: 'author_email_bidx' } },
+  { table: 'pending_commits', key: ['id'], encrypted: ['author_email', 'author_name', 'last_error'], bidx: { source: 'author_email', column: 'author_email_bidx' } },
+  { table: 'file_locks', key: ['workspace_id', 'branch', 'path'], encrypted: ['holder_name'] },
+  { table: 'plugin_join_requests', key: ['id'], encrypted: ['requester_email', 'requester_name', 'failure_reason'], bidx: { source: 'requester_email', column: 'requester_email_bidx' } },
+];
+
+const ident = (name: string) => sql.raw(`"${name}"`);
+
+/** What the backfill needs from a drizzle client — the db or a transaction. */
+type Executor = Pick<Database, 'execute'>;
+
+/** A text column as it is stored: bytes, so the handle's connection does not open it. */
+const asStored = (col: string) => sql`convert_to(${ident(col)}, 'UTF8') AS ${ident(col)}`;
+
+/** What {@link asStored} selected, back as text; anything else as it came. */
+const storedText = (value: unknown): unknown => (Buffer.isBuffer(value) ? value.toString('utf8') : value);
+
+/**
+ * A column "needs sealing" when it holds non-empty text that isn't a blob.
+ * The shape regex is deliberately used as a NEGATIVE filter: anything failing
+ * it — including plaintext that merely BEGINS with the prefix — is selected
+ * and sealed, and `isEncryptedBlob` is the same pattern, so the two can never
+ * disagree about a value. Sealed rows all match, keeping the steady-state scan
+ * an empty-result query.
+ *
+ * `trustShape` is false on the FIRST backfill of a database (see
+ * {@link isFirstBackfill}): nothing has been sealed yet, so a value in this
+ * shape is plaintext somebody typed, and every non-empty value is selected.
+ */
+function needsSealing(col: string, trustShape: boolean) {
+  if (!trustShape) return sql`(${ident(col)} IS NOT NULL AND ${ident(col)} <> '')`;
+  return sql`(${ident(col)} IS NOT NULL AND ${ident(col)} <> '' AND ${ident(col)} !~ ${PII_SEALED_SHAPE_SQL_REGEX})`;
+}
+
+/**
+ * Whether this database has never been through the backfill: the blind-index
+ * column of `users` is still nullable. The backfill, the duplicate collapse
+ * and the constraints run in ONE transaction, so a nullable column means no
+ * backfill has ever committed here — and therefore that nothing in it is
+ * sealed, whatever it looks like.
+ *
+ * That is what lets a first backfill trust no shape at all. A blob is
+ * recognised by its shape, and a title or a display name is text a person
+ * chose: one typed in that shape before the upgrade would be read as sealed,
+ * skipped, and left in clear for good — and, sampled by
+ * {@link assertKeyOpensSealedRows}, would refuse the start for a key that is
+ * perfectly right. Once the first backfill has committed, every write goes
+ * through a handle that seals it, so no such value can arrive again.
+ */
+async function isFirstBackfill(tx: Executor): Promise<boolean> {
+  const result = await tx.execute(sql`
+    SELECT is_nullable FROM information_schema.columns
+    WHERE table_schema = current_schema() AND table_name = 'users' AND column_name = 'email_bidx'
+  `);
+  return (result.rows[0] as { is_nullable?: string } | undefined)?.is_nullable === 'YES';
+}
+
+/** How many rows one backfill query reads: a table is walked in batches, never loaded whole. */
+const BACKFILL_BATCH_ROWS = 500;
+
+/**
+ * The configured key must open what earlier starts sealed. A rotated or
+ * mistyped `SECRETS_ENC_KEY` would otherwise go unnoticed here — sealed rows
+ * are exactly the ones the scan skips — and surface only as every login
+ * failing and every lookup by email missing, because the blind indexes would
+ * be computed under the new key. One sealed value per table is enough: all
+ * rows of a deployment are sealed under one key. Refusing the start is the
+ * loud failure; re-keying a database is a deliberate operation, not a boot.
+ */
+async function assertKeyOpensSealedRows(tx: Executor, keys: PiiKeys): Promise<void> {
+  for (const t of PII_BACKFILL_TABLES) {
+    const col = t.bidx?.source ?? t.encrypted[0]!;
+    const sample = await tx.execute(
+      sql`SELECT ${asStored(col)} FROM ${ident(t.table)} WHERE ${ident(col)} ~ ${PII_SEALED_SHAPE_SQL_REGEX} LIMIT 1`,
+    );
+    const value = storedText((sample.rows[0] as Record<string, unknown> | undefined)?.[col]);
+    if (typeof value === 'string' && !keys.open(value).ok) {
+      throw new Error(
+        `PII encryption: ${t.table}.${col} is sealed with a key the configured SECRETS_ENC_KEY ` +
+          '(for a tenant: the one derived from TENANT_MASTER_KEY) does not open — refusing to start. ' +
+          'Restore the key that sealed it; changing the key is a re-keying of the database, not a configuration change.',
+      );
+    }
+  }
+}
+
+async function backfillTable(
+  tx: Executor,
+  keys: PiiKeys,
+  t: PiiBackfillTable,
+  trustShape: boolean,
+): Promise<number> {
+  // The key columns are read as text beside themselves, so the next batch can
+  // be asked for by value whatever their type is (a uuid, a serial, a path).
+  const keyText = (k: string) => `${k}__key`;
+  const cols = [
+    ...t.key.map(ident),
+    ...t.key.map((k) => sql`${ident(k)}::text AS ${ident(keyText(k))}`),
+    ...t.encrypted.map(asStored),
+    ...(t.bidx ? [ident(t.bidx.column)] : []),
+  ];
+  // Only rows with work left: the ciphertext prefix makes "unsealed" a plain
+  // SQL predicate, so a fully-sealed table costs one empty-result query.
+  const pending = [
+    ...t.encrypted.map((col) => needsSealing(col, trustShape)),
+    ...(t.bidx ? [sql`${ident(t.bidx.column)} IS NULL`] : []),
+  ];
+  const keyTuple = sql`(${sql.join(t.key.map((k) => sql`${ident(k)}::text`), sql`, `)})`;
+  // A blob, as far as this pass may believe one. On a first backfill nothing
+  // is sealed yet, so nothing is believed (see `isFirstBackfill`).
+  const sealedAlready = (value: string): boolean => trustShape && isEncryptedBlob(value);
+  let rewritten = 0;
+  /** The key of the last row read, as text: the next batch starts after it. */
+  let after: string[] | null = null;
+  // IN BATCHES, in key order. A table is never loaded whole: a deployment with
+  // years of change requests holds every title and body it ever had, and
+  // reading them into one result held the first start after the upgrade — and
+  // the memory of the process making it — for as long as that took. Walking by
+  // key rather than re-asking for "what is left" also ends: a row this pass
+  // leaves as it found it (a write overtook it) is passed, not met again.
+  for (;;) {
+    const past = after ? sql` AND ${keyTuple} > (${sql.join(after.map((v) => sql`${v}`), sql`, `)})` : sql``;
+    const result = await tx.execute(
+      sql`SELECT ${sql.join(cols, sql`, `)} FROM ${ident(t.table)} WHERE (${sql.join(pending, sql` OR `)})${past} ORDER BY ${keyTuple} LIMIT ${BACKFILL_BATCH_ROWS}`,
+    );
+    const batch = result.rows as Array<Record<string, unknown>>;
+    for (const read of batch) {
+      const row = Object.fromEntries(Object.entries(read).map(([col, value]) => [col, storedText(value)]));
+      const sets = [];
+      // Compare-and-swap: pin every value this row was read with, so a write
+      // that lands between scan and update makes this UPDATE match zero rows
+      // instead of clobbering the newer value.
+      const where = t.key.map((k) => sql`${ident(k)} = ${row[k]}`);
+      for (const col of t.encrypted) {
+        const value = row[col];
+        if (typeof value === 'string' && value !== '' && !sealedAlready(value)) {
+          sets.push(sql`${ident(col)} = ${keys.seal(value)}`);
+          where.push(sql`${ident(col)} = ${value}`);
+        }
+      }
+      if (t.bidx) {
+        // The blind index is derived from its source, so it is (re)computed
+        // whenever the source is being sealed in this pass — a legacy writer
+        // that put a NEW plaintext email on an already-indexed row left a stale
+        // index behind, and sealing the email alone would freeze that mismatch
+        // — and whenever it was never filled. The source may already be
+        // ciphertext (an index that was never filled beside a sealed address);
+        // the index is always computed over the plaintext, never over a blob
+        // the key cannot open.
+        const source = row[t.bidx.source];
+        const stored = row[t.bidx.column];
+        const text = typeof source === 'string' ? source : '';
+        const sealingSource = text !== '' && !sealedAlready(text);
+        if (sealingSource || stored == null) {
+          const opened = sealedAlready(text) ? keys.open(text) : ({ ok: true, plain: text } as const);
+          if (!opened.ok) {
+            throw new Error(
+              `PII encryption backfill: ${t.table}.${t.bidx.source} cannot be decrypted with the ` +
+                'configured SECRETS_ENC_KEY — refusing to derive a blind index from ciphertext. ' +
+                'Restore the key that sealed it, then restart.',
+            );
+          }
+          sets.push(sql`${ident(t.bidx.column)} = ${keys.index(opened.plain)}`);
+          // Pin the index AND its source: if a concurrent writer replaces the
+          // email between scan and write, the CAS must not attach the OLD
+          // email's blind index to the NEW value.
+          where.push(sql`${ident(t.bidx.column)} IS NOT DISTINCT FROM ${stored ?? null}`);
+          where.push(sql`${ident(t.bidx.source)} IS NOT DISTINCT FROM ${source ?? null}`);
+        }
+      }
+      if (sets.length === 0) continue;
+      const updated = await tx.execute(
+        sql`UPDATE ${ident(t.table)} SET ${sql.join(sets, sql`, `)} WHERE ${sql.join(where, sql` AND `)}`,
+      );
+      rewritten += updated.rowCount ?? 0;
+    }
+    if (batch.length < BACKFILL_BATCH_ROWS) return rewritten;
+    const last = batch[batch.length - 1]!;
+    after = t.key.map((k) => String(last[keyText(k)]));
+  }
+}
+
+/**
+ * The name on a refused apply that was recorded BEFORE this release: the
+ * address of whoever it names was never kept, so no blind index stands beside
+ * it and an account erasure has nothing to find it by.
+ *
+ * Matching it by display name instead got both mistakes at once: a person
+ * who had since changed their name kept the old one on the request for good,
+ * and somebody else of the same name had theirs taken away. So the name goes,
+ * once, here. The refusal itself stays, with its reason and its time; it
+ * reads "could not apply" without saying who. A refusal recorded from this
+ * release on carries its index and is never touched by this.
+ */
+async function clearUnindexedRefusalNames(tx: Executor): Promise<number> {
+  const cleared = await tx.execute(sql.raw(`
+    UPDATE "change_requests" SET "apply_failed_by_name" = NULL
+    WHERE "apply_failed_by_name" IS NOT NULL AND "apply_failed_by_email_bidx" IS NULL
+  `));
+  return cleared.rowCount ?? 0;
+}
+
+/**
+ * Legacy uniqueness was on the RAW email, so rows differing only by case or
+ * whitespace could coexist; under the normalized blind index they collide and
+ * the unique-index creation below would abort the start. Approval rows and
+ * join-request rows are the same logical row — collapse them, keeping the
+ * earliest. Colliding USER rows are distinct accounts; refuse loudly with the
+ * ids so an operator resolves the conflict deliberately instead of the
+ * upgrade guessing.
+ */
+async function resolveBidxCollisions(tx: Executor): Promise<void> {
+  await tx.execute(sql.raw(`
+    DELETE FROM "pr_file_approvals" a USING "pr_file_approvals" b
+    WHERE a."pr_number" = b."pr_number" AND a."path" = b."path"
+      AND a."approver_email_bidx" = b."approver_email_bidx" AND a."head_sha" = b."head_sha"
+      AND (a."approved_at" > b."approved_at" OR (a."approved_at" = b."approved_at" AND a."id" > b."id"))
+  `));
+  await tx.execute(sql.raw(`
+    DELETE FROM "plugin_join_requests" a USING "plugin_join_requests" b
+    WHERE a."plugin_key" = b."plugin_key" AND a."requester_email_bidx" = b."requester_email_bidx"
+      AND (a."created_at" > b."created_at" OR (a."created_at" = b."created_at" AND a."id" > b."id"))
+  `));
+  const dupes = await tx.execute(sql.raw(`
+    SELECT array_agg("id") AS ids FROM "users" GROUP BY "email_bidx" HAVING count(*) > 1
+  `));
+  if (dupes.rows.length > 0) {
+    const groups = (dupes.rows as Array<{ ids: string[] }>).map((r) => r.ids.join(', '));
+    throw new Error(
+      'PII encryption backfill: multiple user rows share the same email after normalization ' +
+        '(case/whitespace variants of one address). Merge or delete the duplicates, then restart. ' +
+        `Conflicting user ids: [${groups.join('], [')}]`,
+    );
+  }
+}
+
+const PII_FINALIZE_STATEMENTS = [
+  'ALTER TABLE "users" ALTER COLUMN "email_bidx" SET NOT NULL',
+  'CREATE UNIQUE INDEX IF NOT EXISTS "users_email_bidx_unq" ON "users" ("email_bidx")',
+  'ALTER TABLE "users" DROP CONSTRAINT IF EXISTS "users_email_unique"',
+  'ALTER TABLE "pr_file_approvals" ALTER COLUMN "approver_email_bidx" SET NOT NULL',
+  'CREATE UNIQUE INDEX IF NOT EXISTS "pr_file_approvals_bidx_unq" ON "pr_file_approvals" ("pr_number","path","approver_email_bidx","head_sha")',
+  'DROP INDEX IF EXISTS "pr_file_approvals_unq"',
+  'ALTER TABLE "pr_merge_log" ALTER COLUMN "triggered_by_email_bidx" SET NOT NULL',
+  'ALTER TABLE "pr_comments" ALTER COLUMN "author_email_bidx" SET NOT NULL',
+  'ALTER TABLE "change_requests" ALTER COLUMN "author_email_bidx" SET NOT NULL',
+  'ALTER TABLE "pending_commits" ALTER COLUMN "author_email_bidx" SET NOT NULL',
+  'ALTER TABLE "plugin_join_requests" ALTER COLUMN "requester_email_bidx" SET NOT NULL',
+  'CREATE UNIQUE INDEX IF NOT EXISTS "plugin_join_requests_requester_bidx_plugin_unq" ON "plugin_join_requests" ("requester_email_bidx","plugin_key")',
+  'DROP INDEX IF EXISTS "plugin_join_requests_requester_plugin_unq"',
+];
+
+/**
+ * Encrypt pre-existing plaintext PII rows, fill the blind-index columns, and
+ * apply the constraints migration 0016 deferred. Idempotent; `runCoreMigrations`
+ * runs it under the migrations lock right after the history. The handle must
+ * hold the knowledge base's key (`createDb(url, { piiKey })`; the composition
+ * root's does): one that holds none is refused before anything is read.
+ */
+export async function runPiiEncryptionBackfill(db: Database): Promise<void> {
+  const keys = piiKeysOf(db);
+  await db.transaction(async (tx) => {
+    const first = await isFirstBackfill(tx);
+    // Nothing is sealed before the first backfill, so there is no sealed row
+    // for the key to be checked against — and a value that only LOOKS sealed
+    // must not be taken for one (see `isFirstBackfill`).
+    if (!first) await assertKeyOpensSealedRows(tx, keys);
+    let rewritten = 0;
+    for (const t of PII_BACKFILL_TABLES) {
+      rewritten += await backfillTable(tx, keys, t, !first);
+    }
+    if (rewritten > 0) log.info(`PII encryption backfill: rewrote ${rewritten} row(s).`);
+    const cleared = await clearUnindexedRefusalNames(tx);
+    if (cleared > 0) {
+      log.info(`PII encryption backfill: took the name off ${cleared} refused apply(ies) recorded before this release.`);
+    }
+    // Only where the unique indexes are not up yet. Once they are, they are
+    // what keeps two rows from sharing an index, so there is nothing to
+    // collapse — and the collapse is two self-joins and an aggregate over
+    // whole tables, which every later start paid for nothing.
+    if (first) await resolveBidxCollisions(tx);
+    for (const statement of PII_FINALIZE_STATEMENTS) {
+      await tx.execute(sql.raw(statement));
+    }
+  });
+}

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
@@ -262,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 });
@@ -534,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),
@@ -548,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 () => {
@@ -566,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'),

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

@@ -27,7 +27,7 @@ import {
 } from '@utcp/sdk';
 import { CodeModeUtcpClient } from '@utcp/code-mode';
 import {
-  CODE_MODE_META_TOOLS,
+  codeModeMetaTools,
   META_TOOL_NAMES,
   dispatchMetaTool,
   dispatchToolCall,
@@ -43,6 +43,7 @@ import {
   type SkillSummary,
   type LoadedSkill,
 } from '@bevel-software/platform-mcp-core';
+import type { KbLayout } from '@bevel-software/platform-shared';
 import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
 import {
   scopesCovered,
@@ -65,6 +66,7 @@ import {
   composeAgentInstructions,
   prefixToolDescription,
   PREFIXED_TOOLS,
+  sharedRulesPointer,
   type AgentPreambleReader,
   type ComposedAgentInstructions,
 } from '../agent-instructions/index.js';
@@ -91,6 +93,13 @@ export interface McpProxyOptions {
    * carries the platform header alone.
    */
   readAgentPreamble?: AgentPreambleReader;
+  /**
+   * The layout in effect, read per request: the shared file rules name the
+   * managed guide, and a deployment may rename it after boot (the setup save
+   * applies a name without a restart). A GETTER, so nothing snapshots the
+   * pre-setup default. Absent, the rules name `AGENTS.md`.
+   */
+  kbLayout?: () => KbLayout;
   /** Bounds of the downstream (`mcp.json`) connection pool; defaults are 4h idle / 5000 entries. */
   downstreamPool?: Pick<DownstreamPoolOptions<unknown>, 'idleTtlMs' | 'maxEntries' | 'now'>;
   /**
@@ -434,12 +443,26 @@ export class McpService {
       const seen = new Set(META_TOOL_NAMES);
       const dropped: string[] = [];
       const direct: McpTool[] = [];
+      const examplePool: ProxiedTool[] = [];
       for (const t of listed) {
         const entry = toListedTool(t); // logs its own reason on a name/schema drop
         if (!entry) {
           dropped.push(t.mcpName);
           continue;
         }
+        // Kept for the worked example in the meta-tool descriptions: it must
+        // be derived from the tools THIS caller actually gets, not from the
+        // whole catalog, or a connection-key caller is shown an example naming
+        // a credential-gated tool the filter above just removed from its
+        // listing — a copied call that cannot work.
+        //
+        // BEFORE the duplicate drop below, on purpose. A tool dropped from the
+        // LISTING for sharing its name with another is still in the catalog a
+        // chain dispatches to, so the chain sees two tools under one name and
+        // refuses the call as ambiguous. The example has to know about both to
+        // steer clear of either (`chainExample` skips a name two tools share);
+        // shown only the survivor, it took that name for a safe one.
+        examplePool.push(t);
         if (seen.has(entry.name)) {
           dropped.push(`${entry.name} (duplicate)`);
           continue;
@@ -456,18 +479,33 @@ export class McpService {
             : entry,
         );
       }
+      // The meta-tools' examples name the namespace THIS endpoint registers the
+      // knowledge-base tools under, and a tool this caller is really served, so
+      // a chain copied out of the description runs. Built here rather than held
+      // as a constant: the local MCP server registers the same tools under a
+      // different name, and one fixed example is necessarily wrong on one of the
+      // two surfaces.
+      //
+      // The chain's description ends with the same pointer every file tool ends
+      // with: what a chain does with a failure, a large result or an image is
+      // stated once, in the shared rules, and the clients that drop
+      // `instructions` have the description and the guide to go on. Composed
+      // here because the guide's name is this deployment's setting.
+      const metaTools = codeModeMetaTools(EXTERNAL_KB_MANUAL_NAME, examplePool, {
+        sharedRulesPointer: sharedRulesPointer(this.opts.kbLayout?.()),
+      });
       // Log only when a tool was dropped (name/schema/duplicate) — that's the
       // anomaly worth surfacing, since a downstream client would otherwise hide
       // it by rejecting the whole response.
       if (dropped.length) {
         log.warn(
-          `tools/list: serving ${CODE_MODE_META_TOOLS.length + direct.length} tool(s); ` +
+          `tools/list: serving ${metaTools.length + direct.length} tool(s); ` +
             `dropped ${dropped.length} non-listable: ${dropped.join(', ')}`,
         );
       }
       return {
         // Code-mode meta-tools first, then every validated direct tool.
-        tools: [...CODE_MODE_META_TOOLS, ...direct],
+        tools: [...metaTools, ...direct],
       };
     });
 
@@ -613,13 +651,14 @@ export class McpService {
    * fails over its preamble.
    */
   private async composeAgentInstructions(): Promise<ComposedAgentInstructions> {
+    const layout = this.opts.kbLayout?.();
     const read = this.opts.readAgentPreamble;
-    if (!read) return composeAgentInstructions(null);
+    if (!read) return composeAgentInstructions(null, layout);
     try {
-      return composeAgentInstructions(await read());
+      return composeAgentInstructions(await read(), layout);
     } catch (err) {
-      log.warn('could not read mcp-description.md; this request gets the platform header alone:', { err });
-      return composeAgentInstructions(null);
+      log.warn('could not read mcp-description.md; this request gets the platform text alone:', { err });
+      return composeAgentInstructions(null, layout);
     }
   }
 

package/src/modules/plugins/join-request-records.store.ts

@@ -143,11 +143,14 @@ export class DbJoinRequestStore implements JoinRequestStore {
     pluginKey: string;
   }): Promise<JoinRequestRecord> {
     const requesterEmail = input.requesterEmail.toLowerCase();
+    // Keyed by the blind index throughout: the email column is randomized
+    // ciphertext, so the uniqueness and every lookup go through its index,
+    // which is written and compared with the address.
     const [inserted] = await this.db
       .insert(pluginJoinRequests)
-      .values({ requesterEmail, requesterName: input.requesterName, pluginKey: input.pluginKey })
+      .values({ requesterEmail, requesterEmailBidx: requesterEmail, requesterName: input.requesterName, pluginKey: input.pluginKey })
       .onConflictDoNothing({
-        target: [pluginJoinRequests.requesterEmail, pluginJoinRequests.pluginKey],
+        target: [pluginJoinRequests.requesterEmailBidx, pluginJoinRequests.pluginKey],
       })
       .returning();
     if (inserted) return toRecord(inserted);
@@ -170,7 +173,7 @@ export class DbJoinRequestStore implements JoinRequestStore {
       })
       .where(
         and(
-          eq(pluginJoinRequests.requesterEmail, requesterEmail),
+          eq(pluginJoinRequests.requesterEmailBidx, requesterEmail),
           eq(pluginJoinRequests.pluginKey, input.pluginKey),
         ),
       )
@@ -191,7 +194,7 @@ export class DbJoinRequestStore implements JoinRequestStore {
     const rows = await this.db
       .select()
       .from(pluginJoinRequests)
-      .where(eq(pluginJoinRequests.requesterEmail, requesterEmail.toLowerCase()));
+      .where(eq(pluginJoinRequests.requesterEmailBidx, requesterEmail));
     return rows.map(toRecord);
   }