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

package/migrations/meta/_journal.json

@@ -43,6 +43,48 @@
       "when": 1788791352625,
       "tag": "0005_github_facade",
       "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "7",
+      "when": 1789034558662,
+      "tag": "0006_api_tokens_revoked_by",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "7",
+      "when": 1789406950616,
+      "tag": "0007_github_facade_registered",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1789563611048,
+      "tag": "0008_change_request_apply_failure",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "7",
+      "when": 1789649918539,
+      "tag": "0009_change_request_apply_failure_kind",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "7",
+      "when": 1789813372971,
+      "tag": "0010_plugin_join_requests",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1789903776474,
+      "tag": "0011_plugin_join_request_claim",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.15.1",
+  "version": "0.19.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,8 +36,8 @@
     "@utcp/code-mode": "^1.2.13",
     "@utcp/direct-call": "^1.1.1",
     "@utcp/http": "^1.1.12",
-    "@utcp/mcp": "^1.1.7",
-    "@utcp/sdk": "^1.1.1",
+    "@utcp/mcp": "^1.2.0",
+    "@utcp/sdk": "^1.2.0",
     "adm-zip": "^0.6.0",
     "cors": "^2.8.5",
     "dotenv": "^16.4.0",
@@ -52,8 +52,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.15.1",
-    "@bevel-software/platform-shared": "0.15.1"
+    "@bevel-software/platform-mcp-core": "0.19.0",
+    "@bevel-software/platform-shared": "0.19.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",
@@ -83,6 +83,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:live": "vitest run .live.test",
+    "probe:first-call": "tsx src/modules/mcp/first-call-probe.cli.ts",
     "db:generate": "drizzle-kit generate"
   }
 }

package/src/__tests__/core-config.domain.test.ts

@@ -1,5 +1,5 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { CoreConfig } from '../core-config.js';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { CoreConfig, withoutUserinfo } from '../core-config.js';
 
 /**
  * The public-shape derivation from `DOMAIN`.
@@ -90,3 +90,68 @@ describe('CoreConfig — DOMAIN derives the public shape', () => {
     expect(config.publicFrontendUrl).toBe('https://bevel.example.com');
   });
 });
+
+/**
+ * Change-request links an agent hands a person are built on the public
+ * frontend address only when one is configured — never on a localhost default.
+ */
+describe('CoreConfig — configuredPublicFrontendUrl', () => {
+  it('is the frontend address when PUBLIC_FRONTEND_URL is set', () => {
+    process.env.PUBLIC_FRONTEND_URL = 'https://example.com/hexis/';
+    expect(new CoreConfig().configuredPublicFrontendUrl).toBe('https://example.com/hexis');
+  });
+
+  it('is derived from DOMAIN', () => {
+    process.env.DOMAIN = 'bevel.example.com';
+    expect(new CoreConfig().configuredPublicFrontendUrl).toBe('https://bevel.example.com');
+  });
+
+  it('follows an explicit backend origin in production', () => {
+    process.env.NODE_ENV = 'production';
+    process.env.PUBLIC_BACKEND_URL = 'https://bevel.example.com';
+    expect(new CoreConfig().configuredPublicFrontendUrl).toBe('https://bevel.example.com');
+  });
+
+  it('is null when nothing is configured, in development and production alike', () => {
+    expect(new CoreConfig().configuredPublicFrontendUrl).toBeNull();
+    process.env.NODE_ENV = 'production';
+    expect(new CoreConfig().configuredPublicFrontendUrl).toBeNull();
+  });
+});
+
+describe('CoreConfig — PUBLIC_BACKEND_URL never carries credentials', () => {
+  it('strips a proxy user:pass@ once, at parse time, and keeps every other byte', () => {
+    process.env.PUBLIC_BACKEND_URL = 'https://proxy:hunter2@Hexis.Example.com:443/base/';
+    expect(new CoreConfig().publicBackendUrl).toBe('https://Hexis.Example.com:443/base');
+  });
+
+  it('warns that the credentials were ignored, without ever printing them', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      process.env.PUBLIC_BACKEND_URL = 'https://proxy:hunter2@hexis.example.com';
+      new CoreConfig();
+      const printed = warn.mock.calls.map((args) => args.map(String).join(' ')).join('\n');
+      expect(printed).toMatch(/PUBLIC_BACKEND_URL contains credentials/);
+      expect(printed).not.toMatch(/hunter2|proxy:/);
+      warn.mockClear();
+      process.env.PUBLIC_BACKEND_URL = 'https://hexis.example.com';
+      new CoreConfig();
+      expect(warn.mock.calls.map((args) => args.join(' ')).join('\n')).not.toMatch(/credentials/);
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it.each([
+    ['https://user@host.example.com', 'https://host.example.com'],
+    ['http://u:p%40ss@localhost:3001', 'http://localhost:3001'],
+    // An unencoded `@` inside the password: the whole userinfo goes, not the head of it.
+    ['https://u:p@ss@host.example.com/cb', 'https://host.example.com/cb'],
+    ['https://u:p@ss@host.example.com?next=a@b', 'https://host.example.com?next=a@b'],
+    ['https://host.example.com/path@not-userinfo', 'https://host.example.com/path@not-userinfo'],
+    ['https://host.example.com?next=a@b', 'https://host.example.com?next=a@b'],
+    ['https://host.example.com', 'https://host.example.com'],
+  ])('withoutUserinfo(%s) is %s', (input, expected) => {
+    expect(withoutUserinfo(input)).toBe(expected);
+  });
+});

package/src/__tests__/kb-layout-config.test.ts

@@ -1,15 +1,22 @@
 import { describe, test, expect, afterEach } from 'vitest';
 import {
+  AGENTS_FILE,
   DEFAULT_KB_LAYOUT,
   KNOWLEDGE_BASE_DIR,
   PLUGINS_DIR,
   SKILLS_DIR,
+  agentsFilePointerSentence,
   configureKbLayout,
   currentKbLayout,
+  isPlatformFile,
+  mentionsAgentsFile,
   ontologyRoots,
+  platformFileNames,
   pluginOfPath,
   renderKbLayoutPlaceholders,
+  retargetAgentsFilePointer,
   reservedRootDirNames,
+  validateAgentsFileName,
   validateKbLayout,
   validateKbRootName,
   normalizeSkillRoot,
@@ -83,7 +90,12 @@ describe('KB layout — configuration', () => {
     expect(KNOWLEDGE_BASE_DIR).toBe('docs');
     expect(SKILLS_DIR).toBe('skills');
     expect(PLUGINS_DIR).toBe('plugins');
-    expect(currentKbLayout()).toEqual({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    expect(currentKbLayout()).toEqual({
+      knowledgeBaseDir: 'docs',
+      skillsDir: 'skills',
+      pluginsDir: 'plugins',
+      agentsFile: 'AGENTS.md',
+    });
   });
 
   test('the derived sets follow the configured names rather than snapshotting the defaults', () => {
@@ -108,3 +120,176 @@ describe('KB layout — configuration', () => {
     expect(KNOWLEDGE_BASE_DIR).toBe('docs');
   });
 });
+
+/**
+ * The agent guide's file name — the fourth thing a deployment may name. The
+ * default is what every deployment before this change ran with, so the
+ * default-name tests here are the regression net for all of them.
+ */
+describe('KB layout — the agent guide\'s file name', () => {
+  test('defaults to AGENTS.md, and a layout that names no guide is the default layout', () => {
+    expect(AGENTS_FILE).toBe('AGENTS.md');
+    expect(DEFAULT_KB_LAYOUT.agentsFile).toBe('AGENTS.md');
+    // An older server's /api/config body, and a deployment that saved three
+    // folder names before the setting existed, both look like this.
+    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    expect(AGENTS_FILE).toBe('AGENTS.md');
+  });
+
+  test('accepts a plain markdown name and applies it to the live binding', () => {
+    expect(validateAgentsFileName('HEXIS.md')).toBeNull();
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    expect(AGENTS_FILE).toBe('HEXIS.md');
+    expect(currentKbLayout().agentsFile).toBe('HEXIS.md');
+  });
+
+  test('refuses every shape that is not one markdown file name of its own', () => {
+    // A folder path: the guide is read from the repository root and nowhere else.
+    expect(validateAgentsFileName('guides/HEXIS.md')).toMatch(/single file name/);
+    expect(validateAgentsFileName('guides\\HEXIS.md')).toMatch(/single file name/);
+    // Not markdown: the per-file access rules apply to `.md` alone.
+    expect(validateAgentsFileName('HEXIS.txt')).toMatch(/end in \.md/);
+    // Nothing at all.
+    expect(validateAgentsFileName('')).toMatch(/required/);
+    expect(validateAgentsFileName('   ')).toMatch(/required/);
+    // A dot-file every scanner skips — including the one that draws the tree.
+    expect(validateAgentsFileName('.hidden.md')).toMatch(/start with a dot/);
+    // The guide's own pre-rename name stays legacy content.
+    expect(validateAgentsFileName('CLAUDE.md')).toMatch(/pre-rename name/);
+    expect(validateAgentsFileName('claude.md')).toMatch(/pre-rename name/);
+    // The other platform files: two platform roles on one path.
+    expect(validateAgentsFileName('access.md')).toMatch(/platform file name/);
+    expect(validateAgentsFileName('roles.yaml')).toMatch(/platform file name/);
+    expect(validateAgentsFileName('.bevelignore')).toMatch(/platform file name/);
+    expect(validateAgentsFileName('mcp-description.md')).toMatch(/platform file name/);
+    // The rule every path component passes.
+    expect(validateAgentsFileName('CON.md')).not.toBeNull();
+    expect(validateAgentsFileName('a:b.md')).not.toBeNull();
+  });
+
+  test('refuses the name of a root folder, whichever of the two the save names', () => {
+    expect(validateAgentsFileName('Plugins.md', { ...DEFAULT_KB_LAYOUT, pluginsDir: 'Plugins.md' }))
+      .toMatch(/already the plugins folder/);
+    // Case-insensitively, like the folders are to each other: one entry on a
+    // case-insensitive disk.
+    expect(validateKbLayout({ ...DEFAULT_KB_LAYOUT, skillsDir: 'guide.md', agentsFile: 'GUIDE.md' }))
+      .toMatch(/already the skills folder/);
+    // And the whole-layout check says which field it is about.
+    expect(validateKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.txt' }))
+      .toMatch(/agent guide's file name/);
+  });
+
+  test('renders {{agentsFile}} so the written guide names the file it lives in', () => {
+    expect(
+      renderKbLayoutPlaceholders('see {{agentsFile}}', { ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' }),
+    ).toBe('see HEXIS.md');
+    // A `$`-pattern in the name is a name, not a replacement pattern.
+    expect(
+      renderKbLayoutPlaceholders('{{agentsFile}}', { ...DEFAULT_KB_LAYOUT, agentsFile: 'A$&.md' }),
+    ).toBe('A$&.md');
+    expect(renderKbLayoutPlaceholders('see {{agentsFile}}', DEFAULT_KB_LAYOUT)).toBe('see AGENTS.md');
+  });
+
+  test('the platform-file gate follows the name: ours is managed, theirs is content', () => {
+    expect(platformFileNames(DEFAULT_KB_LAYOUT)).toEqual([
+      'access.md',
+      'roles.yaml',
+      '.bevelignore',
+      'AGENTS.md',
+    ]);
+    expect(isPlatformFile('AGENTS.md')).toBe(true);
+
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    expect(platformFileNames()).toEqual(['access.md', 'roles.yaml', '.bevelignore', 'HEXIS.md']);
+    // The guide the platform writes is immovable and undeletable…
+    expect(isPlatformFile('HEXIS.md')).toBe(true);
+    // …and the customer's own AGENTS.md is a page like any other.
+    expect(isPlatformFile('AGENTS.md')).toBe(false);
+    // Still root-only, as `roles.yaml` is: a nested copy is content.
+    expect(isPlatformFile('KnowledgeBase/HEXIS.md')).toBe(false);
+  });
+
+  test('the pointer sentence is one sentence, naming the guide twice, from one place', () => {
+    expect(agentsFilePointerSentence('HEXIS.md')).toBe(
+      'Read [HEXIS.md](./HEXIS.md) before working in this knowledge base — ' +
+        "it is the platform's guide to its layout, files and rules.",
+    );
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    expect(agentsFilePointerSentence()).toContain('HEXIS.md');
+  });
+
+  /**
+   * A guide name is a FILE NAME: spaces, brackets, parentheses, `#` and `%`
+   * all pass `validateFilename`, and every one of them means something in an
+   * inline link. The label must not end early and the destination must still
+   * point at the file.
+   */
+  test('the pointer sentence links correctly for a name full of markdown punctuation', () => {
+    const name = 'Our [Agent] Guide (v2).md';
+    expect(validateAgentsFileName(name)).toBeNull();
+    const sentence = agentsFilePointerSentence(name);
+    // The label cannot end early: the brackets in it are escaped…
+    expect(sentence).toContain('[Our \\[Agent\\] Guide (v2).md]');
+    // …and the destination is percent-encoded, parentheses included — a bare
+    // `)` would close the link half way through the name.
+    expect(sentence).toContain('(./Our%20%5BAgent%5D%20Guide%20%28v2%29.md)');
+    // The ordinary name reads as it always has — no escapes, nothing encoded.
+    expect(agentsFilePointerSentence('AGENTS.md')).toContain('[AGENTS.md](./AGENTS.md)');
+  });
+
+  test('the pointer sentence encodes a name that would otherwise open a URL fragment', () => {
+    // `#` is legal in a filename and opens a fragment in a URL: `./#2 Guide.md`
+    // links to the customer's OWN file with a fragment, not to the guide.
+    expect(validateAgentsFileName('#2 Guide.md')).toBeNull();
+    expect(agentsFilePointerSentence('#2 Guide.md')).toContain('(./%232%20Guide.md)');
+    // `%` is legal too, and an unencoded one is a malformed escape.
+    expect(agentsFilePointerSentence('100%.md')).toContain('(./100%25.md)');
+  });
+
+  /**
+   * The startup step asks this before appending, and it has to recognise the
+   * sentence the LAST boot wrote — whose spelling of the name is escaped in
+   * the label and encoded in the destination. Asking for the raw name alone
+   * would append a second copy on every boot after the first.
+   */
+  test('a file already carrying the pointer sentence counts as mentioning the guide', () => {
+    for (const name of ['AGENTS.md', 'Our [Agent] Guide (v2).md', '#2 Guide.md', '100%.md']) {
+      const appended = `# Acme\n\n${agentsFilePointerSentence(name)}\n`;
+      expect(mentionsAgentsFile(appended, name), name).toBe(true);
+    }
+    // A file that says nothing about the guide still reads as silent…
+    expect(mentionsAgentsFile('# Acme\n\nWrite tickets in the present tense.\n', 'HEXIS.md')).toBe(false);
+    // …and the customer's own plain mention counts, in their own words.
+    expect(mentionsAgentsFile('See HEXIS.md for the platform.', 'HEXIS.md')).toBe(true);
+  });
+
+  /**
+   * A second rename. The sentence written for the previous guide points at a
+   * file that is no longer there, and the new name appears nowhere in the
+   * text — so it has to be recognised by its SHAPE and aimed again.
+   */
+  test('a pointer sentence the platform wrote is retargeted, whatever guide it named', () => {
+    for (const before of ['HEXIS.md', 'Our [Agent] Guide (v2).md', '#2 Guide.md']) {
+      const text = `# Acme\n\n${agentsFilePointerSentence(before)}\n`;
+      expect(retargetAgentsFilePointer(text, 'GUIDE.md'), before).toBe(
+        `# Acme\n\n${agentsFilePointerSentence('GUIDE.md')}\n`,
+      );
+    }
+    // Already aimed right: ours, and unchanged — which is not the same answer
+    // as "none of ours here", and the caller tells them apart.
+    const current = `# Acme\n\n${agentsFilePointerSentence('GUIDE.md')}\n`;
+    expect(retargetAgentsFilePointer(current, 'GUIDE.md')).toBe(current);
+  });
+
+  test('leaves a file holding nothing of the platform\'s alone', () => {
+    // Null, not the text: there is nothing of ours to aim, so the caller goes
+    // on to ask whether the customer mentioned the guide themselves.
+    expect(retargetAgentsFilePointer('# Acme\n\nWrite tickets in the present tense.\n', 'GUIDE.md')).toBeNull();
+    // Their own link to their own file is not our sentence.
+    expect(retargetAgentsFilePointer('Read [notes](./notes.md) before working here.', 'GUIDE.md')).toBeNull();
+    // Our opening words, their sentence.
+    expect(
+      retargetAgentsFilePointer('Read [HEXIS.md](./HEXIS.md) when you have a moment.', 'GUIDE.md'),
+    ).toBeNull();
+  });
+});

package/src/__tests__/open-change-gate.ts

@@ -0,0 +1,15 @@
+import type { IChangeReadGate } from '../modules/access-model/change-gate.js';
+
+/**
+ * A read-before-write gate that lets every change through — for tests whose
+ * subject is something else. `WorkflowService` refuses to exist without a
+ * gate (see its constructor), so a harness that only exercises branches,
+ * change requests or commits passes this one. Never wired in production: the
+ * composition root builds the real `ChangeReadGate`.
+ */
+export function openChangeGate(): IChangeReadGate {
+  return {
+    judge: async () => ({ allowed: true, via: 'readable' }),
+    assertMayChange: async () => undefined,
+  };
+}

package/src/core/__tests__/catalog-cache-invalidation.test.ts

@@ -3,6 +3,7 @@ import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { FileChangeNotifier } from '../../modules/kb-fs/file-change-notifier.js';
 import { WorkflowEventBus } from '../../modules/workflow/event-bus.js';
 import { registerCatalogCacheInvalidation } from '../catalog-cache-invalidation.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 
 const KB_DIR = 'knowledge-base';
 
@@ -20,11 +21,13 @@ function setup() {
     { invalidate: vi.fn() },
     { invalidate: vi.fn() },
   ];
+  const accessControl = { invalidate: vi.fn() };
   const off = registerCatalogCacheInvalidation({
     eventBus,
     fileChangeNotifier,
     kbDirName: KB_DIR,
     catalogs,
+    accessControl,
   });
   /** How many times EVERY catalog was dropped — they are only ever dropped together. */
   const drops = () => {
@@ -32,7 +35,7 @@ function setup() {
     expect(new Set(counts).size).toBe(1);
     return counts[0];
   };
-  return { eventBus, fileChangeNotifier, drops, off };
+  return { eventBus, fileChangeNotifier, drops, off, accessControl };
 }
 
 describe('registerCatalogCacheInvalidation', () => {
@@ -48,6 +51,56 @@ describe('registerCatalogCacheInvalidation', () => {
       expect(drops()).toBe(1);
     });
 
+    /**
+     * The four files a released catalog is MADE of. A commit touching any of
+     * them has to drop the caches at once — the agent tester's report was a
+     * valid `.tool` that stayed absent and uncallable until the connection was
+     * recreated, and each of these declares tools or skills the same way.
+     */
+    it.each([
+      ['a `.tool` manual', `${KB_DIR}/Plugins/Everyone/software.bevel.hexis/tools/serper.tool`],
+      ['an mcp.json', `${KB_DIR}/Plugins/Everyone/mcp.json`],
+      ['a plugin.json', `${KB_DIR}/Plugins/Everyone/plugin.json`],
+      ['a SKILL.md under a plugin', `${KB_DIR}/Plugins/Everyone/skills/rfi/SKILL.md`],
+      ['a SKILL.md under the shared root', `${KB_DIR}/Skills/Ops/rfi/SKILL.md`],
+    ])('drops the catalogs when a default-branch commit touches %s', (_what, path) => {
+      const { fileChangeNotifier, drops } = setup();
+      fileChangeNotifier.emit({ workspaceId: 'ws', branch: DEFAULT_BRANCH, paths: [path], byUser: USER });
+      expect(drops()).toBe(1);
+    });
+
+    /**
+     * A REMOVAL is the same signal as an addition: the notifier reports the
+     * paths a commit touched, and a deleted manual is one of them. Without
+     * this the removed tool stays listed — and callable — for a full TTL.
+     */
+    it('drops them for a removal, which reaches here as the same touched path', () => {
+      const { fileChangeNotifier, drops } = setup();
+      fileChangeNotifier.emit({
+        workspaceId: 'ws',
+        branch: DEFAULT_BRANCH,
+        paths: [`${KB_DIR}/Plugins/Everyone/software.bevel.hexis/tools/retired.tool`],
+        byUser: USER,
+      });
+      expect(drops()).toBe(1);
+    });
+
+    /** One drop per commit, whichever of its paths qualified. */
+    it('drops them once for a batch that touches several catalog files', () => {
+      const { fileChangeNotifier, drops } = setup();
+      fileChangeNotifier.emit({
+        workspaceId: 'ws',
+        branch: DEFAULT_BRANCH,
+        paths: [
+          `${KB_DIR}/KnowledgeBase/Note.md`,
+          `${KB_DIR}/Plugins/Everyone/mcp.json`,
+          `${KB_DIR}/Plugins/Everyone/plugin.json`,
+        ],
+        byUser: USER,
+      });
+      expect(drops()).toBe(1);
+    });
+
     it('ignores commits on other branches, and commits outside Plugins/', () => {
       const { fileChangeNotifier, drops } = setup();
       fileChangeNotifier.emit({
@@ -107,8 +160,8 @@ describe('registerCatalogCacheInvalidation', () => {
         sessionId: 's1',
         userId: 'u1',
         // `fs-tree-changed` is workspace-scoped, so a session only receives
-        // it while focused on that workspace.
-        getFocusedWorkspaceId: () => 'ws',
+        // it while watching that workspace.
+        getFocusedWorkspaceIds: () => ['ws'],
         // The browser reloads the library off this event; if the caches were
         // still warm here, the reload would re-read the stale catalog.
         push: () => seenAtPush.push(drops()),
@@ -130,6 +183,33 @@ describe('registerCatalogCacheInvalidation', () => {
     });
   });
 
+  /**
+   * The read gate goes with them. Every catalog here is ACL-filtered, and a
+   * skill's or a manual's own `read:` frontmatter lives in the very file the
+   * commit rewrote — but the batch gate memoizes those own-entry rules per
+   * workspace for five minutes. A fresh catalog resolved through a stale gate
+   * is the pair disagreeing: a revoked skill still loadable by name, a
+   * just-granted one still missing from the listing, for the rest of the memo.
+   */
+  it('drops the access gate for the default workspace with them', () => {
+    const { fileChangeNotifier, eventBus, drops, accessControl } = setup();
+    fileChangeNotifier.emit({
+      workspaceId: 'ws',
+      branch: DEFAULT_BRANCH,
+      paths: [`${KB_DIR}/Skills/Ops/rfi/SKILL.md`],
+      byUser: USER,
+    });
+    expect(drops()).toBe(1);
+    expect(accessControl.invalidate).toHaveBeenCalledExactlyOnceWith(workspaceIdForBranch(DEFAULT_BRANCH));
+
+    eventBus.emit({ kind: 'fs-tree-changed', workspaceId: 'ws', branch: DEFAULT_BRANCH });
+    expect(accessControl.invalidate).toHaveBeenCalledTimes(2);
+
+    // And not for a branch these catalogs never read.
+    eventBus.emit({ kind: 'fs-tree-changed', workspaceId: 'ws2', branch: 'agent/draft' });
+    expect(accessControl.invalidate).toHaveBeenCalledTimes(2);
+  });
+
   it('detaches every subscription on unsubscribe', () => {
     const { eventBus, fileChangeNotifier, drops, off } = setup();
     off();