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

package/src/modules/plugins/discovery/__tests__/kb-plugin-source.test.ts

@@ -1,8 +1,9 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+import { DEFAULT_KB_LAYOUT, configureKbLayout, pluginDisplayNameOf } from '@bevel-software/platform-shared';
 import { KbPluginSource } from '../kb-plugin-source.js';
 
 /**
@@ -56,6 +57,12 @@ describe('KbPluginSource — bundles', () => {
     await write('plugins/departments/engineering/shared/unnamed/plugin.bundle.json', JSON.stringify({ sourceSkillRoots: ['../escape', 'skills/x'] }));
     // A bundle whose name is not its folder's, with no display name of its own.
     await write('plugins/departments/business/finance/ledger-folder/plugin.bundle.json', JSON.stringify({ name: 'ledger' }));
+    // A declared display name with padding around it — the one field of the
+    // presentation block that is also a name.
+    await write(
+      'plugins/functional/cluster-a/padded/plugin.bundle.json',
+      JSON.stringify({ name: 'padded', interface: { displayName: '  Padded Plugin  ', category: 'Ops' } }),
+    );
     await write('plugins/broken/plugin.bundle.json', '{ not json');
   });
   afterEach(async () => {
@@ -64,12 +71,16 @@ describe('KbPluginSource — bundles', () => {
   });
 
   it('finds bundles at any depth and reads them as plugins that link skill roots', async () => {
-    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
     const byName = new Map(plugins.map((p) => [p.name, p]));
-    expect([...byName.keys()].sort()).toEqual(['close', 'example-plugin', 'ledger', 'unnamed']);
-    // The shared contract: a declared display name, else the FOLDER — never the identity.
+    expect([...byName.keys()].sort()).toEqual(['close', 'example-plugin', 'ledger', 'padded', 'unnamed']);
+    // The bundle dialect's own rule — a declared display name, else the
+    // FOLDER — which this foreign, read-only format keeps. It is resolved
+    // INTO the manifest the reader synthesizes, so the shared manifest-only
+    // reader says the same thing about a bundle that discovery does.
     expect(byName.get('example-plugin')!.displayName).toBe('Example Plugin');
     expect(byName.get('ledger')!.displayName).toBe('ledger-folder');
+    expect(pluginDisplayNameOf(byName.get('ledger')!.manifest)).toBe('ledger-folder');
 
     const example = byName.get('example-plugin')!;
     expect(example.folder).toBe('plugins/functional/cluster-a/example-plugin');
@@ -85,7 +96,22 @@ describe('KbPluginSource — bundles', () => {
       version: '1.3.1',
       description: 'What this plugin is for',
       displayName: 'Example Plugin',
+      // The presentation block rides along whole, for the compiled Codex manifest.
+      interface: { displayName: 'Example Plugin', category: 'Productivity' },
     });
+    // One answer, in both fields: the presentation block is carried whole,
+    // but the name inside it is the trimmed one the manifest and discovery
+    // report — the compile step fills that field only when it is blank, so a
+    // padded spelling left here would ship a Codex manifest calling the
+    // plugin something the catalog does not.
+    const padded = byName.get('padded')!;
+    expect(padded.displayName).toBe('Padded Plugin');
+    expect(padded.manifest).toMatchObject({
+      displayName: 'Padded Plugin',
+      interface: { displayName: 'Padded Plugin', category: 'Ops' },
+    });
+    expect(pluginDisplayNameOf(padded.manifest)).toBe('Padded Plugin');
+
     // An unnamed bundle takes its folder's name; a bad root is dropped with a warning.
     expect(byName.get('unnamed')!.linkedRoots).toEqual(['skills/x']);
     expect(warnings.some((w) => w.includes('../escape'))).toBe(true);
@@ -93,7 +119,7 @@ describe('KbPluginSource — bundles', () => {
   });
 
   it('expands mcpProfile through the registry, following extends and reporting unknowns', async () => {
-    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
     const example = plugins.find((p) => p.name === 'example-plugin')!;
     expect(example.mcpServers).toEqual({
       confluence: { type: 'streamable-http', url: 'https://mcp.confluence.example' },
@@ -101,6 +127,8 @@ describe('KbPluginSource — bundles', () => {
     });
     expect(JSON.parse(example.mcpJsonText!)).toEqual({ mcpServers: example.mcpServers });
     expect(warnings.some((w) => w.includes('unknown server "ghost"'))).toBe(true);
+    // `Jira` and `Confluence` cannot be server names, so both run under their ids — and the author is told.
+    expect(warnings.filter((w) => w.includes('cannot be a server name'))).toHaveLength(2);
     // An empty profile is valid and selects nothing.
     expect(plugins.find((p) => p.name === 'close')!.mcpServers).toBeNull();
   });
@@ -128,7 +156,7 @@ describe('KbPluginSource — bundles', () => {
         ],
       }),
     );
-    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
     const example = plugins.find((p) => p.name === 'example-plugin')!;
     expect(example.mcpServers).toEqual({
       jira: { type: 'stdio', command: 'npx', args: ['-y', 'jira-mcp'] },
@@ -146,7 +174,7 @@ describe('KbPluginSource — bundles', () => {
 
   it('cuts an extends cycle instead of hanging, and keeps what it collected', async () => {
     await write('plugins/loop/plugin.bundle.json', JSON.stringify({ name: 'loop', mcpProfile: 'loop-a' }));
-    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
     const loop = plugins.find((p) => p.name === 'loop')!;
     expect(loop.mcpServers).toEqual({ 'flat-http': { type: 'streamable-http', url: 'https://flat.example' } });
     expect(warnings.some((w) => w.includes('cycle'))).toBe(true);
@@ -154,7 +182,7 @@ describe('KbPluginSource — bundles', () => {
 
   it('a missing registry leaves the plugins standing, servers-less, with a warning per profile', async () => {
     await fs.rm(path.join(kb, 'configs'), { recursive: true });
-    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
     expect(plugins.find((p) => p.name === 'example-plugin')!.mcpServers).toBeNull();
     expect(warnings.some((w) => w.includes('no registry'))).toBe(true);
   });
@@ -198,7 +226,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
     // beneath: a container, not a plugin.
     await write('Plugins/functional/access.md', '---\n---\nread:\n  - everyone\n');
 
-    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
     // Folders are visited in locale order (case-insensitive), depth first.
     // Position means nothing: only the two files make a plugin.
     expect(plugins.map((p) => [p.name, p.folder, p.linksAreManaged, p.exists])).toEqual([
@@ -217,7 +245,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
     await write('Plugins/b/GTM/plugin.json', '{}');
     // Different spelling, same manifest slug: still one plugin.
     await write('Plugins/c/gtm/plugin.json', '{}');
-    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
     expect(plugins.map((p) => p.folder)).toEqual(['Plugins/a/GTM']);
     expect(warnings).toEqual([
       'Plugins/b/GTM: plugin name "gtm" is already used by Plugins/a/GTM — plugin skipped',
@@ -225,7 +253,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
     ]);
   });
 
-  it('the manifest name is the identity and the folder only the label — unless the name is no identifier', async () => {
+  it('reads both names from the manifest and neither from the folder — the name standing in only when there is none', async () => {
     await write('Plugins/GTM/plugin.json', JSON.stringify({ name: 'go-to-market', displayName: 'Go To Market' }));
     await write('Plugins/Numeric/plugin.json', '{"name":42}');
     // A name nested deeper than any stack would serialise: the warning must
@@ -233,13 +261,21 @@ describe('KbPluginSource — one walk, both shapes', () => {
     await write('Plugins/Nested/plugin.json', `{"name":${'['.repeat(20000)}${']'.repeat(20000)}}`);
     await write('Plugins/Ops/plugin.json', JSON.stringify({ name: 'Not An Identifier' }));
     await write('Plugins/Plain/plugin.json', '{}');
-    const { plugins, warnings } = await new KbPluginSource().discover(kb);
+    const { plugins, warnings } = await new KbPluginSource(new NodeFs()).discover(kb);
     expect(plugins.map((p) => [p.name, p.displayName, p.folder])).toEqual([
+      // Both fields present: both are read, and `Plugins/GTM` says nothing.
       ['go-to-market', 'Go To Market', 'Plugins/GTM'],
-      ['nested', 'Nested', 'Plugins/Nested'],
-      ['numeric', 'Numeric', 'Plugins/Numeric'],
-      ['ops', 'Ops', 'Plugins/Ops'],
-      ['plain', 'Plain', 'Plugins/Plain'],
+      // The three below name nothing usable at all — the shape the folder
+      // stands in as the IDENTITY for, out loud. What they are called follows
+      // that identity; the folder is never read for the label directly, which
+      // is why `Nested` shows as `nested`.
+      ['nested', 'nested', 'Plugins/Nested'],
+      ['numeric', 'numeric', 'Plugins/Numeric'],
+      // A name that is no identifier cannot BE the identity — the folder
+      // stands in for that too — but it is still what the manifest SAYS the
+      // plugin is called, so it is the display name.
+      ['ops', 'Not An Identifier', 'Plugins/Ops'],
+      ['plain', 'plain', 'Plugins/Plain'],
     ]);
     // Every PRESENT name that is no identifier is said out loud — whatever its type.
     expect(warnings).toEqual([
@@ -267,7 +303,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
           : (realReadFile as (f: string, o: unknown) => Promise<unknown>).call(fs, file, opts)) as never),
     ];
     try {
-      const { plugins, warnings, unreadable } = await new KbPluginSource().discover(kb);
+      const { plugins, warnings, unreadable } = await new KbPluginSource(new NodeFs()).discover(kb);
       // The container could not be listed: nothing beneath it was seen. The
       // manifest could not be read: an identity nobody could see, so the
       // plugin is not listed under a guessed one. Both are holes, not absence.
@@ -295,7 +331,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
         ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
         : (realReadFile as (f: string, o: unknown) => Promise<unknown>).call(fs, file, opts)) as never);
     try {
-      const { plugins, unreadable } = await new KbPluginSource().discover(kb);
+      const { plugins, unreadable } = await new KbPluginSource(new NodeFs()).discover(kb);
       expect(unreadable).toEqual(['Plugins/Hidden/plugin.json']);
       expect(plugins.map((p) => p.name)).toEqual(['gtm']);
     } finally {
@@ -312,7 +348,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
         ? Promise.reject(Object.assign(new Error('ENOENT: no such file'), { code: 'ENOENT' }))
         : (realReadFile as (f: string, o: unknown) => Promise<unknown>).call(fs, file, opts)) as never);
     try {
-      const { plugins, unreadable } = await new KbPluginSource().discover(kb);
+      const { plugins, unreadable } = await new KbPluginSource(new NodeFs()).discover(kb);
       expect(plugins.map((p) => p.name)).toEqual(['gtm']);
       expect(unreadable).toEqual([]);
     } finally {
@@ -321,7 +357,7 @@ describe('KbPluginSource — one walk, both shapes', () => {
   });
 
   it('a knowledge base without a plugins root has no plugins and no complaint', async () => {
-    const { plugins, warnings, unreadable } = await new KbPluginSource().discover(kb);
+    const { plugins, warnings, unreadable } = await new KbPluginSource(new NodeFs()).discover(kb);
     expect(plugins).toEqual([]);
     expect(warnings).toEqual([]);
     expect(unreadable).toEqual([]);

package/src/modules/plugins/discovery/bundle-dialect/bundle.source.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { isPersonalPluginDir, normalizeSkillRoot, pluginManifestName } from '@bevel-software/platform-shared';
-import { isAbsence } from '../../../../shared/fs-errors.js';
+import { isAbsence } from '../../../../shared/fs.contract.js';
 import type { DiscoveredPlugin } from '../plugin-source.js';
 import { expandProfile, parseRegistry, type McpRegistry } from './registry.js';
 
@@ -37,6 +37,10 @@ import { expandProfile, parseRegistry, type McpRegistry } from './registry.js';
 export const BUNDLE_FILE = 'plugin.bundle.json';
 export const DEFAULT_REGISTRY_PATH = 'configs/mcp/registry.json';
 
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
 /** The registry, when the repository has one; a missing file is null, a broken one warns. */
 export async function loadRegistry(kbRoot: string, warnings: string[]): Promise<McpRegistry | null> {
   let text: string;
@@ -110,20 +114,37 @@ export async function readBundlePlugin(
     }
   }
 
-  const ui =
-    typeof bundle.interface === 'object' && bundle.interface !== null
-      ? (bundle.interface as Record<string, unknown>)
-      : {};
+  // A record, or nothing: a list where the block should be is not a block.
+  const ui = isRecord(bundle.interface) ? bundle.interface : {};
+  // The bundle's own rule for what it is called: `interface.displayName`,
+  // else the FOLDER — this dialect is a foreign repository's, read-only, and
+  // its folders are its presentation. The synthesized manifest carries the
+  // answer so the shared reader (`pluginDisplayNameOf`, manifest-only) tells
+  // anyone who asks the same thing this discovery reports.
+  const displayName = typeof ui.displayName === 'string' && ui.displayName.trim() ? ui.displayName.trim() : leaf;
+  // The presentation block is carried as written (below) — except for the
+  // one field that is also a name: the block gets the SAME answer the
+  // manifest does. The compile step fills `interface.displayName` only when
+  // it is blank, so a padded or blank spelling left here would ship a Codex
+  // manifest whose `interface` calls the plugin something the catalog and
+  // the API do not — the split answer this whole rule removes.
+  const carriedUi = typeof ui.displayName === 'string' ? { ...ui, displayName } : ui;
   const manifest: Record<string, unknown> = { name: pluginManifestName(name) };
   if (typeof bundle.version === 'string') manifest.version = bundle.version;
   if (typeof bundle.description === 'string') manifest.description = bundle.description;
-  if (typeof ui.displayName === 'string') manifest.displayName = ui.displayName;
+  manifest.displayName = displayName;
+  // What the bundle says about itself beyond the four fields above — who
+  // wrote it, what it is for, how a catalogue should present it — is carried
+  // as written, so the compiled plugin can say the same. Shapes are the
+  // vendor manifests' own (`author` an object or a string, `keywords` a list,
+  // `interface` the Codex presentation block); anything else is left where it is.
+  if (isRecord(bundle.author) || typeof bundle.author === 'string') manifest.author = bundle.author;
+  if (Array.isArray(bundle.keywords) && bundle.keywords.every((k) => typeof k === 'string')) manifest.keywords = bundle.keywords;
+  if (Object.keys(carriedUi).length > 0) manifest.interface = carriedUi;
 
   return {
     name,
-    // The shared contract (`DiscoveredPlugin.displayName`): the declared
-    // display name, else the FOLDER — never the identity.
-    displayName: typeof ui.displayName === 'string' && ui.displayName.trim() ? ui.displayName.trim() : leaf,
+    displayName,
     folder,
     relFolder,
     // The same rule as the native reader: a reserved personal folder directly

package/src/modules/plugins/discovery/bundle-dialect/registry.ts

@@ -21,10 +21,22 @@ import {
 } from '../../../tool-manuals/mcp-json-discovery.js';
 
 export interface RegistryServer {
+  /** The registry's own key: what a profile lists, unique across the file. */
   id: string;
-  name?: string;
-  /** The server as one `mcp.json` entry — judged, and therefore usable, at parse time. */
-  entry: PortableStdioEntry | PortableHttpEntry;
+  /**
+   * What the server is CALLED once it runs — the `mcp.json` key, the
+   * `mcp__<name>__*` tool namespace a skill is written against. Several
+   * entries may share one (two transports of one server); a profile picks
+   * one of them. Absent, the id is the name.
+   */
+  name: string;
+  /**
+   * The server as one `mcp.json` entry — judged, and therefore usable, at
+   * parse time — plus every field of the config the judgement does not
+   * know (`startup_timeout_sec`, say), carried through untouched: a field a
+   * client understands must reach it, and one it does not it ignores.
+   */
+  entry: (PortableStdioEntry | PortableHttpEntry) & Record<string, unknown>;
 }
 
 export interface RegistryProfile {
@@ -36,6 +48,8 @@ export interface RegistryProfile {
 export interface McpRegistry {
   servers: Map<string, RegistryServer>;
   profiles: Map<string, RegistryProfile>;
+  /** Servers the registry declared but could not keep, by id, with the reason — so a profile selecting one can say why it is missing. */
+  rejected: Map<string, string>;
   warnings: string[];
 }
 
@@ -43,20 +57,21 @@ export function parseRegistry(text: string): McpRegistry {
   const warnings: string[] = [];
   const servers = new Map<string, RegistryServer>();
   const profiles = new Map<string, RegistryProfile>();
+  const rejected = new Map<string, string>();
   let root: unknown;
   try {
     root = JSON.parse(text);
   } catch {
-    return { servers, profiles, warnings: ['registry.json is not valid JSON'] };
+    return { servers, profiles, rejected, warnings: ['registry.json is not valid JSON'] };
   }
-  if (!isRecord(root)) return { servers, profiles, warnings: ['registry.json must be a JSON object'] };
+  if (!isRecord(root)) return { servers, profiles, rejected, warnings: ['registry.json must be a JSON object'] };
 
   for (const raw of asArray(root.servers)) {
     if (!isRecord(raw) || typeof raw.id !== 'string' || !raw.id) {
       warnings.push('registry.json: a server without an id was skipped');
       continue;
     }
-    if (servers.has(raw.id)) {
+    if (servers.has(raw.id) || rejected.has(raw.id)) {
       warnings.push(`registry.json: server "${raw.id}" is declared twice — the second declaration is ignored`);
       continue;
     }
@@ -64,12 +79,35 @@ export function parseRegistry(text: string): McpRegistry {
     // entry a client can run — judged by the ONE rule every mcp.json entry
     // meets (name, transport, required fields), after the customer's shape
     // is translated into that of mcp.json.
-    const converted = mcpEntryOf(raw.id, isRecord(raw.config) ? raw.config : raw);
+    const config = isRecord(raw.config) ? raw.config : raw;
+    const converted = mcpEntryOf(raw.id, config);
     if ('reason' in converted) {
       warnings.push(`registry.json: server "${raw.id}" ${converted.reason} — skipped`);
+      rejected.set(raw.id, converted.reason);
       continue;
     }
-    servers.set(raw.id, { id: raw.id, name: typeof raw.name === 'string' ? raw.name : undefined, entry: converted.entry });
+    // The running name is the key a client sees, so it meets the same
+    // spelling rule the id just did. One that does not is not a reason to
+    // lose the server: it runs under its id, and the registry's author is
+    // told which skills will not find it.
+    let name = raw.id;
+    if (raw.name !== undefined) {
+      const declared = typeof raw.name === 'string' ? raw.name.trim() : '';
+      if (declared === raw.id) {
+        // Named as it is keyed: nothing to say.
+      } else if (declared && judgeMcpServerEntry(declared, { ...config, ...converted.entry }).ok) {
+        name = declared;
+      } else {
+        // Every name that is present and unusable is said, blank or not a
+        // string included: a skill written against it will not find the server.
+        warnings.push(
+          declared
+            ? `registry.json: server "${raw.id}" is named "${declared}", which cannot be a server name (lowercase alphanumeric with \`_\`/\`-\`) — it runs as "${raw.id}"`
+            : `registry.json: server "${raw.id}" has a name that is blank or not a string — it runs as "${raw.id}"`,
+        );
+      }
+    }
+    servers.set(raw.id, { id: raw.id, name, entry: converted.entry });
   }
   for (const raw of asArray(root.profiles)) {
     if (!isRecord(raw) || typeof raw.id !== 'string' || !raw.id) {
@@ -86,14 +124,20 @@ export function parseRegistry(text: string): McpRegistry {
       extends: typeof raw.extends === 'string' ? raw.extends : undefined,
     });
   }
-  return { servers, profiles, warnings };
+  return { servers, profiles, rejected, warnings };
 }
 
 /**
  * The `mcpServers` map a profile resolves to, in `mcp.json` terms. Keyed by
- * server id — the namespace vault secrets bind to, so the same registry
- * server in three plugins shares one credential, which is what a registry
- * means.
+ * the server's NAME, not its registry id: the name is what a client
+ * registers the server as and what a skill's `mcp__<name>__*` calls are
+ * written against, and it is the namespace vault secrets bind to — so the
+ * two transports of one server (`figma-stdio` and `figma-remote`, both
+ * named `figma`) present as one server whichever a profile picks, and share
+ * one credential. A profile may select only one of them: two servers of one
+ * name in one expansion is a conflict, reported, and the nearer profile's
+ * wins. A selected server the registry could not keep is reported with the
+ * reason it was rejected, so the plugin's page can say what is missing.
  */
 export function expandProfile(
   registry: McpRegistry,
@@ -120,13 +164,27 @@ export function expandProfile(
     current = profile.extends;
   }
   const mcpServers: Record<string, unknown> = {};
+  const holder = new Map<string, string>();
   for (const id of ids) {
     const server = registry.servers.get(id);
     if (!server) {
-      warnings.push(`registry.json: profile "${profileId}" selects unknown server "${id}"`);
+      const reason = registry.rejected.get(id);
+      warnings.push(
+        reason
+          ? `registry.json: profile "${profileId}" selects server "${id}", which was left out — ${reason}`
+          : `registry.json: profile "${profileId}" selects unknown server "${id}"`,
+      );
+      continue;
+    }
+    const first = holder.get(server.name);
+    if (first !== undefined) {
+      warnings.push(
+        `registry.json: profile "${profileId}" selects both "${first}" and "${id}", which are both named "${server.name}" — "${id}" left out`,
+      );
       continue;
     }
-    mcpServers[id] = server.entry;
+    holder.set(server.name, id);
+    mcpServers[server.name] = server.entry;
   }
   return { mcpServers, warnings };
 }
@@ -143,9 +201,9 @@ export function expandProfile(
  * transport the client speaks (no `sse`), the field that transport needs.
  */
 function mcpEntryOf(
-  id: string,
+  name: string,
   config: Record<string, unknown>,
-): { entry: PortableStdioEntry | PortableHttpEntry } | { reason: string } {
+): { entry: RegistryServer['entry'] } | { reason: string } {
   const declared = typeof config.type === 'string' ? config.type.trim().toLowerCase() : undefined;
   const url = nonBlank(config.url);
   const command = nonBlank(config.command);
@@ -158,10 +216,27 @@ function mcpEntryOf(
   for (const key of ['args', 'env', 'cwd', 'headers'] as const) {
     if (config[key] !== undefined) candidate[key] = config[key];
   }
-  const verdict = judgeMcpServerEntry(id, candidate);
-  return verdict.ok ? { entry: verdict.entry } : { reason: verdict.reason };
+  const verdict = judgeMcpServerEntry(name, candidate);
+  if (!verdict.ok) return { reason: verdict.reason };
+  // Every field the judgement did not read rides along as written: a
+  // `startup_timeout_sec` is meaningful to the client that knows it and
+  // harmless to one that does not, and dropping it silently was the
+  // customer's first complaint. The registry's own keys (`id`, `name`, a
+  // flat entry's) are the record's, not the server's.
+  const entry: Record<string, unknown> = { ...verdict.entry };
+  for (const [key, value] of Object.entries(config)) {
+    // Defined, not assigned: a field spelled `__proto__` is a field to
+    // carry, and assignment would set the object's prototype instead.
+    if (!JUDGED_OR_RECORD_KEYS.has(key)) {
+      Object.defineProperty(entry, key, { value, enumerable: true, configurable: true, writable: true });
+    }
+  }
+  return { entry: entry as RegistryServer['entry'] };
 }
 
+/** The config keys the judgement reads, plus the record's own; everything else passes through. */
+const JUDGED_OR_RECORD_KEYS = new Set(['type', 'url', 'command', 'args', 'env', 'cwd', 'headers', 'id', 'name', 'config']);
+
 function nonBlank(v: unknown): string | undefined {
   return typeof v === 'string' && v.trim() ? v : undefined;
 }

package/src/modules/plugins/discovery/kb-plugin-source.ts

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, pluginManifestName } from '@bevel-software/platform-shared';
 import type { DiscoveredPlugin, Discovery, PluginSource, PluginSourceWalk } from './plugin-source.js';
-import { walkKb, type KbWalkListener } from '../../../shared/kb-walk.js';
+import type { IFsProbe, ITreeWalker, WalkListener } from '../../../shared/fs.contract.js';
 import { readNativePlugin } from './native.source.js';
 import { BUNDLE_FILE, loadRegistry, readBundlePlugin } from './bundle-dialect/bundle.source.js';
 import type { McpRegistry } from './bundle-dialect/registry.js';
@@ -38,25 +38,28 @@ import type { McpRegistry } from './bundle-dialect/registry.js';
 export class KbPluginSource implements PluginSource {
   readonly dialect = 'kb';
 
+  constructor(private readonly disk: ITreeWalker & IFsProbe) {}
+
   async discover(kbRoot: string): Promise<Discovery> {
     return (await this.walkWith(kbRoot, [])).discovery;
   }
 
-  async walkWith(kbRoot: string, listeners: readonly KbWalkListener[]): Promise<PluginSourceWalk> {
+  async walkWith(kbRoot: string, listeners: readonly WalkListener[]): Promise<PluginSourceWalk> {
     const warnings: string[] = [];
     const registry = await loadRegistry(kbRoot, warnings);
-    const listener = pluginListener(kbRoot, registry, warnings);
-    const { holes } = await walkKb(kbRoot, [listener.listener, ...listeners]);
+    const listener = pluginListener(this.disk, kbRoot, registry, warnings);
+    const { holes } = await this.disk.walkKb(kbRoot, [listener.listener, ...listeners]);
     return { discovery: listener.result(), holes };
   }
 }
 
 /** The discovery listener over one walk, and the `Discovery` it has built once the walk is done. */
 function pluginListener(
+  disk: IFsProbe,
   kbRoot: string,
   registry: McpRegistry | null,
   warnings: string[],
-): { listener: KbWalkListener; result(): Discovery } {
+): { listener: WalkListener; result(): Discovery } {
   const unreadable: string[] = [];
   const plugins: DiscoveredPlugin[] = [];
   const seen = new Map<string, string>();
@@ -91,7 +94,7 @@ function pluginListener(
         if (has(PLUGIN_MANIFEST_FILE)) {
           claimed.push(rel);
           // A manifest that could not be read: a hole, and still claimed.
-          const native = await readNativePlugin(dir, rel, relFolder, warnings, unreadable);
+          const native = await readNativePlugin(disk, dir, rel, relFolder, warnings, unreadable);
           if (native) claim(native);
         } else if (has(BUNDLE_FILE)) {
           claimed.push(rel);
@@ -109,6 +112,6 @@ function pluginListener(
         unreadable.push(rel);
       },
     },
-    result: () => ({ plugins, warnings, unreadable }),
+    result: () => ({ plugins, warnings, unreadable, claimed }),
   };
 }

package/src/modules/plugins/discovery/native.source.ts

@@ -9,7 +9,7 @@ import {
   pluginDisplayNameOf,
   pluginIdentityOf,
 } from '@bevel-software/platform-shared';
-import { isAbsence } from '../../../shared/fs-errors.js';
+import { isAbsence, type IFsProbe } from '../../../shared/fs.contract.js';
 import type { DiscoveredPlugin } from './plugin-source.js';
 
 /**
@@ -25,6 +25,7 @@ import type { DiscoveredPlugin } from './plugin-source.js';
  * failure is a warning and nothing more.
  */
 export async function readNativePlugin(
+  disk: IFsProbe,
   dir: string,
   folder: string,
   relFolder: string,
@@ -52,7 +53,13 @@ export async function readNativePlugin(
   // in, and the mismatch is said out loud so a grant written against the
   // manifest's spelling is not a mystery.
   const name = pluginIdentityOf(manifest, folderName);
-  const displayName = pluginDisplayNameOf(manifest, folderName);
+  // The display name comes from the MANIFEST alone — `displayName`, else
+  // `name` — never from the folder. `|| name` is not a folder fallback in
+  // disguise: it catches only the manifest that names nothing usable, the
+  // same shape `pluginIdentityOf` just stood the folder in for, so the
+  // display name follows the identity the reader resolved rather than
+  // arriving empty.
+  const displayName = pluginDisplayNameOf(manifest) || name;
   // Any PRESENT name that is not an identifier is worth a word — a number or
   // an object as much as a capitalised string. Only an absent name is silent.
   if (manifest && manifest.name !== undefined && !isPluginIdentifier(manifest.name)) {
@@ -72,7 +79,18 @@ export async function readNativePlugin(
     mcp && typeof mcp.mcpServers === 'object' && mcp.mcpServers !== null && !Array.isArray(mcp.mcpServers)
       ? (mcp.mcpServers as Record<string, unknown>)
       : null;
-  const exists = await fs.stat(path.join(dir, 'access.md')).then((s) => s.isFile(), () => false);
+  // The plugin EXISTS to the index when its folder carries an `access.md`
+  // (links followed). Absence is "no rules yet"; a probe that fails for any
+  // other reason is a hole like an unreadable manifest — the plugin is not
+  // listed under a guessed answer, and a writer can refuse.
+  let exists: boolean;
+  try {
+    exists = (await disk.statOrNull(path.join(dir, 'access.md')))?.isFile() ?? false;
+  } catch (err) {
+    warnings.push(`${folder}/access.md could not be read — ${err instanceof Error ? err.message : String(err)}`);
+    unreadable.push(`${folder}/access.md`);
+    return null;
+  }
   return {
     name,
     displayName,

package/src/modules/plugins/discovery/plugin-source.ts

@@ -1,4 +1,4 @@
-import type { KbWalkListener } from '../../../shared/kb-walk.js';
+import type { WalkListener } from '../../../shared/fs.contract.js';
 
 /**
  * Plugin DISCOVERY as an interface — the one seam between "what a plugin is
@@ -26,7 +26,12 @@ export interface DiscoveredPlugin {
    * plugin's is the bundle's `name`. Unique per source.
    */
   name: string;
-  /** What a person sees it called: the manifest's `displayName`, else the folder name. */
+  /**
+   * What a person sees it called: the manifest's `displayName`, else its
+   * `name`. The manifest is the only source — never the folder. (The bundle
+   * dialect's own folder rule is resolved INTO the manifest it synthesizes,
+   * so the shared reader still says what the source reports.)
+   */
   displayName: string;
   /** Repo-relative folder holding the plugin, e.g. `Plugins/GTM`. */
   folder: string;
@@ -75,6 +80,15 @@ export interface Discovery {
    * may take an identity it could not see.
    */
   unreadable: string[];
+  /**
+   * Every folder a plugin CLAIMS, repo-relative — in `plugins` or not: a
+   * twin skipped for sharing a slug, a manifest that could not be read.
+   * Nothing beneath a claimed folder is a plugin to discovery, so nothing
+   * may be CREATED beneath one either: a plugin made inside a skipped twin
+   * would be listed by no catalog. `plugins` answers "what is there";
+   * this answers "where may nothing new go".
+   */
+  claimed: string[];
 }
 
 /** What one walk yields when discovery shares it: the plugins, and every hole the walk met anywhere. */
@@ -95,5 +109,5 @@ export interface PluginSource {
    * one set of holes. Optional: a source that cannot share its walk is
    * discovered on its own and the caller walks separately.
    */
-  walkWith?(kbRoot: string, listeners: readonly KbWalkListener[]): Promise<PluginSourceWalk>;
+  walkWith?(kbRoot: string, listeners: readonly WalkListener[]): Promise<PluginSourceWalk>;
 }