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

package/src/modules/plugins/__tests__/plugin-links.service.test.ts

@@ -0,0 +1,287 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { DEFAULT_BRANCH, type AuthUser } from '@bevel-software/platform-shared';
+
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../../access/access-control.service.js';
+import { SkillService } from '../../skills/skills.service.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { PluginLinkIndex } from '../plugin-links.js';
+import { PluginLinksService, PluginLinkError } from '../plugin-links.service.js';
+import type { ProvisionCommitDriver } from '../plugin-provision.service.js';
+
+/**
+ * Linking end to end over a real tree: the real resolver decides who may
+ * link and who may read afterwards, the real catalog resolves roots, and the
+ * commit driver is the only thing stubbed (it records what would land).
+ */
+
+const KB_DIR = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+
+const manager: AuthUser = { id: 'u-mia', email: 'mia@x.io', name: 'Mia' } as AuthUser;
+const editor: AuthUser = { id: 'u-eve', email: 'eve@x.io', name: 'Eve' } as AuthUser;
+const member: AuthUser = { id: 'u-sam', email: 'sam@x.io', name: 'Sam' } as AuthUser;
+
+const ROLES_YAML = `roles:
+  Admin:
+    - admin@x.io
+`;
+
+describe('PluginLinksService', () => {
+  let root: string;
+  let repo: string;
+  let commits: string[];
+  let access: AccessControlService;
+  let skills: SkillService;
+  let index: PluginLinkIndex;
+  let svc: PluginLinksService;
+
+  const write = async (rel: string, text: string) => {
+    const abs = path.join(repo, rel);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, text);
+  };
+  const read = (rel: string) => fs.readFile(path.join(repo, rel), 'utf-8');
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-links-'));
+    repo = path.join(root, wsId, KB_DIR);
+    commits = [];
+    const workspaceService = {
+      getOrCreateForBranch: async () => ({ id: wsId }),
+      getWorkspacePath: async (id: string) => path.join(root, id),
+      readFile: async (id: string, rel: string) => fs.readFile(path.join(root, id, rel), 'utf-8'),
+      writeFile: async (id: string, rel: string, text: string) => {
+        const abs = path.join(root, id, rel);
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, text);
+      },
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    const driver: ProvisionCommitDriver = {
+      runPendingCommit: async (_ws, _branch, target) => {
+        commits.push(target);
+      },
+    };
+
+    await write('roles.yaml', ROLES_YAML);
+    await write('access.md', '---\nwrite:\n  - Admin\n---\n');
+    // GTM: Mia manages, Sam is a member.
+    await write(
+      'Plugins/GTM/access.md',
+      '---\nread:\n  - everyone\n---\nread:\n  - Sam <sam@x.io>\nwrite:\n  - Mia <mia@x.io>\nowner:\n  - Mia <mia@x.io>\n',
+    );
+    await write('Plugins/GTM/plugin.json', '{\n  "name": "gtm",\n  "version": "1.0.0"\n}\n');
+    // A shared scope Eve edits, holding two skills.
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Eve <eve@x.io>\n');
+    await write('Skills/Eng/deploy/SKILL.md', '---\ndescription: Ship it.\n---\n');
+    await write('Skills/Eng/rollback/SKILL.md', '---\ndescription: Undo it.\n---\n');
+
+    access = new AccessControlService(workspaceService, KB_DIR);
+    skills = new SkillService(workspaceService, access, KB_DIR);
+    index = new PluginLinkIndex(workspaceService, skills, access, KB_DIR);
+    svc = new PluginLinksService(workspaceService, driver, access, skills, index, KB_DIR);
+  });
+  afterEach(() => fs.rm(root, { recursive: true, force: true }));
+
+  it('links a skill: manifest entry + read/write grants for the plugin principals, both committed', async () => {
+    // Mia manages GTM but cannot edit Skills/Eng — Eve grants her write first.
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Eve <eve@x.io>\n  - Mia <mia@x.io>\n');
+    access.invalidate(wsId);
+
+    const result = await svc.link(manager, 'gtm', 'Skills/Eng/deploy');
+    expect(result).toEqual({ root: 'Skills/Eng/deploy', skills: ['Skills/Eng/deploy'] });
+
+    const manifest = JSON.parse(await read('Plugins/GTM/plugin.json'));
+    expect(manifest.version).toBe('1.0.0'); // untouched
+    expect(manifest.extensions['software.bevel.hexis'].skills).toEqual(['Skills/Eng/deploy']);
+    const rules = await read('Skills/Eng/deploy/access.md');
+    expect(rules).toContain('plugin/gtm/read');
+    expect(rules).toContain('plugin/gtm/write');
+    expect(commits).toEqual([
+      `${KB_DIR}/Plugins/GTM/plugin.json`,
+      `${KB_DIR}/Skills/Eng/deploy/access.md`,
+    ]);
+
+    // The point of it all: Sam, a GTM member, can now read the skill; Mia can edit it.
+    expect(await access.canRead(wsId, member.email, 'Skills/Eng/deploy/SKILL.md')).toBe(true);
+    expect(await access.canWrite(wsId, manager.email, 'Skills/Eng/deploy/SKILL.md')).toBe(true);
+    // And the index reports the membership as linked and granted.
+    expect(await index.pluginsOf('Skills/Eng/deploy')).toEqual([{ name: 'gtm', linked: true, granted: true }]);
+    expect(await index.pluginsOf('Skills/Eng/rollback')).toEqual([]);
+  });
+
+  it('a plugin whose folder is not its own slug links, re-links and unlinks through ONE spelling', async () => {
+    // The folder "Sales Team" is only where the plugin lives; its manifest
+    // name "sales-team" is the plugin. Every grant, comparison and revocation
+    // goes through that one key, so a second link adds nothing and an unlink
+    // finds what it wrote.
+    await write(
+      'Plugins/Sales Team/access.md',
+      '---\nread:\n  - everyone\n---\nread:\n  - Sam <sam@x.io>\nwrite:\n  - Mia <mia@x.io>\nowner:\n  - Mia <mia@x.io>\n',
+    );
+    await write('Plugins/Sales Team/plugin.json', '{"name":"sales-team"}');
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Eve <eve@x.io>\n  - Mia <mia@x.io>\n');
+    access.invalidate(wsId);
+
+    await svc.link(manager, 'sales-team', 'Skills/Eng/deploy');
+    await svc.link(manager, 'sales-team', 'Skills/Eng/deploy');
+    const rules = await read('Skills/Eng/deploy/access.md');
+    expect(rules.match(/plugin\/sales-team\/read/g)).toHaveLength(1);
+    expect(rules.match(/plugin\/sales-team\/write/g)).toHaveLength(1);
+    expect(await access.canRead(wsId, member.email, 'Skills/Eng/deploy/SKILL.md')).toBe(true);
+
+    await svc.unlink(manager, 'sales-team', 'Skills/Eng/deploy');
+    expect(await read('Skills/Eng/deploy/access.md')).not.toContain('plugin/sales-team');
+    access.invalidate(wsId);
+    expect(await access.canRead(wsId, member.email, 'Skills/Eng/deploy/SKILL.md')).toBe(false);
+  });
+
+  it('two plugins linking one root at once both land their grants — the root is locked, not only the plugin', async () => {
+    await write(
+      'Plugins/Ops/access.md',
+      '---\nread:\n  - everyone\n---\nread:\n  - Sam <sam@x.io>\nwrite:\n  - Mia <mia@x.io>\nowner:\n  - Mia <mia@x.io>\n',
+    );
+    await write('Plugins/Ops/plugin.json', '{"name":"ops"}');
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Eve <eve@x.io>\n  - Mia <mia@x.io>\n');
+    access.invalidate(wsId);
+
+    await Promise.all([svc.link(manager, 'gtm', 'Skills/Eng'), svc.link(manager, 'ops', 'Skills/Eng')]);
+    const rules = await read('Skills/Eng/access.md');
+    expect(rules).toContain('plugin/gtm/read');
+    expect(rules).toContain('plugin/ops/read');
+    expect(rules).toContain('plugin/gtm/write');
+    expect(rules).toContain('plugin/ops/write');
+  });
+
+  it('refuses with needs-skill-write when the manager cannot edit the skill\'s rules', async () => {
+    await expect(svc.link(manager, 'gtm', 'Skills/Eng/deploy')).rejects.toMatchObject({
+      status: 409,
+      payload: { kind: 'needs-skill-write' },
+    });
+    expect(commits).toEqual([]);
+    expect(await fs.readFile(path.join(repo, 'Plugins/GTM/plugin.json'), 'utf-8')).not.toContain('skills');
+  });
+
+  it('a folder of skills links every skill beneath it with one grant on the folder', async () => {
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Eve <eve@x.io>\n  - Mia <mia@x.io>\n');
+    access.invalidate(wsId);
+    const result = await svc.link(manager, 'gtm', 'Skills/Eng');
+    expect(result.skills.sort()).toEqual(['Skills/Eng/deploy', 'Skills/Eng/rollback']);
+    expect(await read('Skills/Eng/access.md')).toContain('plugin/gtm/read');
+    expect(await access.canRead(wsId, member.email, 'Skills/Eng/rollback/SKILL.md')).toBe(true);
+    const m = await index.membership();
+    expect(m.byPlugin.get('gtm')?.linkedSkills.sort()).toEqual(['Skills/Eng/deploy', 'Skills/Eng/rollback']);
+  });
+
+  it('is fail-closed on the plugin side: a non-manager, or an unknown plugin, gets the same 404', async () => {
+    await expect(svc.link(member, 'gtm', 'Skills/Eng/deploy')).rejects.toMatchObject({ status: 404 });
+    await expect(svc.link(manager, 'Ghost', 'Skills/Eng/deploy')).rejects.toMatchObject({ status: 404 });
+    await expect(svc.link(manager, 'personal-abc', 'Skills/Eng/deploy')).rejects.toMatchObject({ status: 404 });
+  });
+
+  it('rejects a root that holds no released skill, and a path that could escape the repo', async () => {
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
+    access.invalidate(wsId);
+    await expect(svc.link(manager, 'gtm', 'Skills/Nowhere')).rejects.toMatchObject({
+      status: 422,
+      payload: { kind: 'no-skills' },
+    });
+    await expect(svc.link(manager, 'gtm', '../etc')).rejects.toMatchObject({ status: 422, payload: { kind: 'bad-root' } });
+  });
+
+  it('refuses a root that holds a retired skill anywhere beneath it — the grant would reach it', async () => {
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
+    await write('Skills/Eng/old-deploy/SKILL.md', '---\ndescription: Gone.\nmetadata:\n  lifecycle: retired\n---\n');
+    access.invalidate(wsId);
+    skills.invalidate();
+
+    await expect(svc.link(manager, 'gtm', 'Skills/Eng')).rejects.toMatchObject({
+      status: 422,
+      payload: { kind: 'retired-skills', retired: ['Skills/Eng/old-deploy'] },
+    });
+    await expect(svc.link(manager, 'gtm', 'Skills/Eng/old-deploy')).rejects.toMatchObject({ status: 422 });
+    // The active skill on its own is fine.
+    await svc.link(manager, 'gtm', 'Skills/Eng/deploy');
+    expect(await read('Skills/Eng/deploy/access.md')).toContain('plugin/gtm/read');
+    expect(await access.canRead(wsId, member.email, 'Skills/Eng/old-deploy/SKILL.md')).toBe(false);
+  });
+
+  it('unlink removes the entry and revokes the tokens when the actor may edit the skill', async () => {
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
+    access.invalidate(wsId);
+    await svc.link(manager, 'gtm', 'Skills/Eng/deploy');
+    commits.length = 0;
+
+    expect(await svc.unlink(manager, 'gtm', 'Skills/Eng/deploy')).toEqual({ root: 'Skills/Eng/deploy', revoked: true });
+    expect(JSON.parse(await read('Plugins/GTM/plugin.json')).extensions).toBeUndefined();
+    expect(await read('Skills/Eng/deploy/access.md')).not.toContain('plugin/gtm');
+    expect(await access.canRead(wsId, member.email, 'Skills/Eng/deploy/SKILL.md')).toBe(false);
+    // Revoke lands first, manifest second: a failure between the two leaves
+    // the visible half-state (still listed, no grant), never the silent one.
+    expect(commits).toEqual([`${KB_DIR}/Skills/Eng/deploy/access.md`, `${KB_DIR}/Plugins/GTM/plugin.json`]);
+  });
+
+  it('unlink leaves the grant in place when the actor may not edit the skill — and says so', async () => {
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
+    access.invalidate(wsId);
+    await svc.link(manager, 'gtm', 'Skills/Eng/deploy');
+    // Eve takes Mia's write on the scope away, and hand-edits the skill's own
+    // rules down to the read token — the link's write token, which would still
+    // let GTM's managers edit, is gone.
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Eve <eve@x.io>\n');
+    await write('Skills/Eng/deploy/access.md', '---\n---\nread:\n  - plugin/gtm/read\n');
+    access.invalidate(wsId);
+
+    expect(await svc.unlink(manager, 'gtm', 'Skills/Eng/deploy')).toEqual({ root: 'Skills/Eng/deploy', revoked: false });
+    expect(await read('Skills/Eng/deploy/access.md')).toContain('plugin/gtm/read');
+    await expect(svc.unlink(manager, 'gtm', 'Skills/Eng/deploy')).rejects.toMatchObject({ status: 404, payload: { kind: 'not-linked' } });
+  });
+
+  it('a hand-removed grant shows as not granted, and repair puts it back', async () => {
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
+    access.invalidate(wsId);
+    await svc.link(manager, 'gtm', 'Skills/Eng/deploy');
+
+    await write('Skills/Eng/deploy/access.md', '---\n---\nread:\n  - Sam <sam@x.io>\n');
+    access.invalidate(wsId);
+    index.invalidate();
+    expect(await index.pluginsOf('Skills/Eng/deploy')).toEqual([{ name: 'gtm', linked: true, granted: false }]);
+
+    await svc.repair(manager, 'gtm', 'Skills/Eng/deploy');
+    expect(await index.pluginsOf('Skills/Eng/deploy')).toEqual([{ name: 'gtm', linked: true, granted: true }]);
+    // Repair is a skill-editor's action, not a plugin-manager's: with both the
+    // scope grant and the link's write token gone, Mia may not touch the rules.
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Eve <eve@x.io>\n');
+    await write('Skills/Eng/deploy/access.md', '---\n---\nread:\n  - Sam <sam@x.io>\n');
+    access.invalidate(wsId);
+    await expect(svc.repair(manager, 'gtm', 'Skills/Eng/deploy')).rejects.toBeInstanceOf(PluginLinkError);
+    // Eve, who edits the scope, can.
+    await svc.repair(editor, 'gtm', 'Skills/Eng/deploy');
+    expect(await read('Skills/Eng/deploy/access.md')).toContain('plugin/gtm/read');
+  });
+
+  it('a plugin nested below the root links like any other — position means nothing', async () => {
+    await write('Plugins/teams/Deep/plugin.json', '{\n  "name": "deep"\n}\n');
+    await write('Plugins/teams/Deep/access.md', '---\n---\nread:\n  - Sam <sam@x.io>\nwrite:\n  - Mia <mia@x.io>\n');
+    await write('Skills/Eng/access.md', '---\n---\nwrite:\n  - Mia <mia@x.io>\n');
+    access.invalidate(wsId);
+    index.invalidate();
+
+    await svc.link(manager, 'deep', 'Skills/Eng/rollback');
+    expect(JSON.parse(await read('Plugins/teams/Deep/plugin.json')).extensions['software.bevel.hexis'].skills).toEqual(['Skills/Eng/rollback']);
+    expect(await read('Skills/Eng/rollback/access.md')).toContain('plugin/deep/read');
+    expect(await access.canRead(wsId, member.email, 'Skills/Eng/rollback/SKILL.md')).toBe(true);
+    expect(await index.pluginsOf('Skills/Eng/rollback')).toEqual([{ name: 'deep', linked: true, granted: true }]);
+  });
+
+  it('a skill inside a plugin folder is inline membership, never a link', async () => {
+    await write('Plugins/GTM/skills/outreach/SKILL.md', '---\ndescription: Reach out.\n---\n');
+    skills.invalidate();
+    index.invalidate();
+    expect(await index.pluginsOf('Plugins/GTM/skills/outreach')).toEqual([{ name: 'gtm', linked: false, granted: true }]);
+  });
+});

package/src/modules/plugins/__tests__/plugin-provision.service.test.ts

@@ -51,6 +51,20 @@ async function makeHarness() {
   return { svc, dir, commits, accessControl, events, writeFile };
 }
 
+/** Wait until a delete has parked `dir` (it is gone from its place) — the moment a racing creation may start. */
+async function untilParked(dir: string): Promise<void> {
+  for (let i = 0; i < 200; i++) {
+    if (await fs.stat(dir).then(() => false, () => true)) return;
+    await new Promise((r) => setTimeout(r, 5));
+  }
+  throw new Error(`${dir} was never parked`);
+}
+
+/** Let every pending microtask and short timer run — enough for a queued lock waiter to be queued. */
+async function settle(): Promise<void> {
+  for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 5));
+}
+
 describe('PluginProvisionService.createPlugin', () => {
   let h: Awaited<ReturnType<typeof makeHarness>>;
   beforeEach(async () => {
@@ -59,7 +73,9 @@ describe('PluginProvisionService.createPlugin', () => {
 
   it('writes the discoverable template, commits it inline, and drops the access cache', async () => {
     const result = await h.svc.createPlugin(USER, 'GTM');
-    expect(result).toEqual({ folder: 'GTM', created: true });
+    // The folder is where it lives; the name is what it IS (the identity the
+    // page navigates to and the grants spell).
+    expect(result).toEqual({ folder: 'GTM', name: 'gtm', created: true });
 
     const accessMd = await fs.readFile(path.join(h.dir, KB, 'Plugins/GTM/access.md'), 'utf-8');
     // Discoverable FILE (frontmatter read: everyone), creator-run FOLDER
@@ -87,7 +103,7 @@ describe('PluginProvisionService.createPlugin', () => {
     expect(h.accessControl.invalidate).toHaveBeenCalledWith('ws-main');
   });
 
-  it('writes a conformant plugin.json naming the folder in slug form', async () => {
+  it('writes a conformant plugin.json: the identifier in slug form, the typed name as the display name', async () => {
     await h.svc.createPlugin(USER, 'GTM');
     const manifest = JSON.parse(
       await fs.readFile(path.join(h.dir, KB, 'Plugins/GTM/plugin.json'), 'utf-8'),
@@ -95,6 +111,7 @@ describe('PluginProvisionService.createPlugin', () => {
     expect(manifest).toEqual({
       $schema: 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json',
       name: 'gtm',
+      displayName: 'GTM',
     });
     // The schema's `name` pattern is the thing a conformant client refuses on.
     expect(manifest.name).toMatch(/^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/);
@@ -118,6 +135,7 @@ describe('PluginProvisionService.createPlugin', () => {
     // A genuinely distinct slug still goes through.
     await expect(h.svc.createPlugin(USER, 'Sales Ops')).resolves.toEqual({
       folder: 'Sales Ops',
+      name: 'sales-ops',
       created: true,
     });
   });
@@ -145,6 +163,7 @@ describe('PluginProvisionService.createPlugin', () => {
     await fs.writeFile(path.join(h.dir, KB, 'Plugins', 'slack.tool'), 'id: slack\n', 'utf-8');
     await expect(h.svc.createPlugin(USER, 'Slack Tool')).resolves.toEqual({
       folder: 'Slack Tool',
+      name: 'slack-tool',
       created: true,
     });
   });
@@ -180,7 +199,7 @@ describe('PluginProvisionService.createPlugin', () => {
     await expect(h.svc.createPlugin(USER, 'GTM')).rejects.toThrow('push refused');
     // The folder is gone again — the next attempt starts clean.
     await expect(fs.stat(path.join(h.dir, KB, 'Plugins/GTM'))).rejects.toThrow();
-    await expect(h.svc.createPlugin(USER, 'GTM')).resolves.toEqual({ folder: 'GTM', created: true });
+    await expect(h.svc.createPlugin(USER, 'GTM')).resolves.toEqual({ folder: 'GTM', name: 'gtm', created: true });
   });
 });
 
@@ -220,6 +239,116 @@ describe('PluginProvisionService.deletePlugin', () => {
     );
   });
 
+  it('refuses a folder path the filesystem cannot carry with 422 — control characters, a reserved name, a dot-prefix', async () => {
+    for (const bad of ['teams/Deep', 'a\tb', 'teams/NUL', '.deleting-x', 'teams/.hidden']) {
+      await expect(h.svc.deletePlugin(USER, bad)).rejects.toMatchObject({ status: 422 });
+    }
+  });
+
+  it('a bundle-shaped plugin locks on the SLUG of the name its bundle declares — the one a creation would take', async () => {
+    await fs.mkdir(path.join(h.dir, KB, 'Plugins/Ext'), { recursive: true });
+    // Declared as people write it, not as the marketplace publishes it.
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/Ext/plugin.bundle.json'), '{"name":"Ext Id"}');
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/Ext/access.md'), '---\n---\n');
+    let refuse: (err: Error) => void = () => {};
+    h.commits.runPendingCommit.mockImplementationOnce(
+      () => new Promise<undefined>((_resolve, reject) => { refuse = reject; }),
+    );
+    const deleting = h.svc.deletePlugin(USER, 'Ext');
+    await untilParked(path.join(h.dir, KB, 'Plugins/Ext'));
+    // Spelled differently, same identity: must wait for the delete, then see the twin.
+    const creating = h.svc.createPlugin(USER, 'Ext Id');
+    await settle();
+    refuse(new Error('push refused'));
+    await expect(deleting).rejects.toThrow('push refused');
+    await expect(creating).rejects.toMatchObject({ status: 409 });
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/Ext/plugin.bundle.json'))).resolves.toBeDefined();
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/Ext Id'))).rejects.toThrow();
+  });
+
+  it('validates the folder path AS GIVEN — a padded spelling is refused, never trimmed into a real folder', async () => {
+    await h.svc.createPlugin(USER, 'GTM');
+    for (const padded of [' GTM', 'GTM ', 'teams/ Deep']) {
+      await expect(h.svc.deletePlugin(USER, padded)).rejects.toMatchObject({ status: 422 });
+    }
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/GTM/plugin.json'))).resolves.toBeDefined();
+    expect(h.commits.runPendingCommit).toHaveBeenCalledTimes(1); // the create above only
+  });
+
+  it('a hole ANYWHERE in discovery stops a delete — even of a plugin whose own folder was read fine', async () => {
+    await h.svc.createPlugin(USER, 'GTM');
+    await fs.mkdir(path.join(h.dir, KB, 'Plugins/Other'), { recursive: true });
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/Other/plugin.json'), '{"name":"other"}');
+    const real = fs.readFile;
+    const spy = vi.spyOn(fs, 'readFile').mockImplementation(((file: string, opts: unknown) =>
+      String(file).endsWith(path.join('Other', 'plugin.json'))
+        ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
+        : (real as (f: string, o: unknown) => Promise<unknown>).call(fs, file, opts)) as never);
+    try {
+      await expect(h.svc.deletePlugin(USER, 'GTM')).rejects.toMatchObject({ status: 503 });
+    } finally {
+      spy.mockRestore();
+    }
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/GTM/plugin.json'))).resolves.toBeDefined();
+    expect(h.commits.runPendingCommit).toHaveBeenCalledTimes(1); // the create above only
+  });
+
+  it('a manifest that is there but cannot be read stops the delete — never a guessed identity lock', async () => {
+    await h.svc.createPlugin(USER, 'GTM');
+    const real = fs.readFile;
+    const spy = vi.spyOn(fs, 'readFile').mockImplementation(((file: string, opts: unknown) =>
+      String(file).endsWith(path.join('GTM', 'plugin.json'))
+        ? Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }))
+        : (real as (f: string, o: unknown) => Promise<unknown>).call(fs, file, opts)) as never);
+    try {
+      // Discovery reports the hole; the delete refuses the way a creation would.
+      await expect(h.svc.deletePlugin(USER, 'GTM')).rejects.toMatchObject({ status: 503 });
+    } finally {
+      spy.mockRestore();
+    }
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/GTM/plugin.json'))).resolves.toBeDefined();
+  });
+
+  it('a nested plugin holds its identity against a creation at the root — taken is discovery\'s answer', async () => {
+    await fs.mkdir(path.join(h.dir, KB, 'Plugins/teams/Deep'), { recursive: true });
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/plugin.json'), '{"name":"deep"}');
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/access.md'), '---\n---\n');
+    await expect(h.svc.createPlugin(USER, 'Deep')).rejects.toMatchObject({ status: 409 });
+    await expect(h.svc.createPlugin(USER, 'Deep')).rejects.toThrow('Plugins/teams/Deep');
+  });
+
+  it('a delete and a creation of one IDENTITY never overlap — even when the identity is not the folder path', async () => {
+    await fs.mkdir(path.join(h.dir, KB, 'Plugins/teams/Deep'), { recursive: true });
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/plugin.json'), '{"name":"deep"}');
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/access.md'), '---\n---\n');
+    // The delete's commit hangs, then is REFUSED — the folder comes back.
+    let refuse: (err: Error) => void = () => {};
+    h.commits.runPendingCommit.mockImplementationOnce(
+      () => new Promise<undefined>((_resolve, reject) => { refuse = reject; }),
+    );
+    const deleting = h.svc.deletePlugin(USER, 'teams/Deep');
+    await untilParked(path.join(h.dir, KB, 'Plugins/teams/Deep'));
+    // A creation of the same identity, started while the folder is parked
+    // and invisible: it must wait for the delete, not slip in beside it.
+    const creating = h.svc.createPlugin(USER, 'Deep');
+    await settle();
+    refuse(new Error('push refused'));
+    await expect(deleting).rejects.toThrow('push refused');
+    // The delete rolled back, so `deep` is still taken — and the creation sees it.
+    await expect(creating).rejects.toMatchObject({ status: 409 });
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/teams/Deep/plugin.json'))).resolves.toBeDefined();
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/Deep'))).rejects.toThrow();
+  });
+
+  it('deletes a plugin whose name sits at the filesystem component limit — the park adds nothing to the name', async () => {
+    // 240 characters: valid to create (≤ 255 bytes), and long enough that a
+    // park spelled `.<name>.deleting-<uuid>` would not be a legal component.
+    const long = 'a'.repeat(240);
+    await h.svc.createPlugin(USER, long);
+    await h.svc.deletePlugin(USER, long);
+    expect(await fs.readdir(path.join(h.dir, KB, 'Plugins'))).toEqual([]);
+  });
+
   it('refuses an unknown name — and a casing mismatch, which is the same thing — with 404', async () => {
     await h.svc.createPlugin(USER, 'GTM');
     for (const name of ['Nope', 'gtm']) {
@@ -228,6 +357,77 @@ describe('PluginProvisionService.deletePlugin', () => {
     expect(await fs.readdir(path.join(h.dir, KB, 'Plugins'))).toEqual(['GTM']);
   });
 
+  it('deletes a plugin nested below the root by its folder PATH, parking it beside itself', async () => {
+    await fs.mkdir(path.join(h.dir, KB, 'Plugins/teams/Deep'), { recursive: true });
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/plugin.json'), '{"name":"deep"}');
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/access.md'), '---\n---\n');
+
+    await h.svc.deletePlugin(USER, 'teams/Deep');
+
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/teams/Deep'))).rejects.toThrow();
+    expect(await fs.readdir(path.join(h.dir, KB, 'Plugins/teams'))).toEqual([]);
+    expect(h.commits.runPendingCommit).toHaveBeenCalledWith(
+      'ws-main',
+      DEFAULT_BRANCH,
+      `${KB}/Plugins/teams/Deep`,
+      USER,
+      { systemAuthorized: true },
+    );
+    // Segments only — nothing climbs out of the root, and no backslash (a
+    // second separator on Windows); a missing nested folder is unknown.
+    await expect(h.svc.deletePlugin(USER, '../etc')).rejects.toMatchObject({ status: 422 });
+    await expect(h.svc.deletePlugin(USER, 'teams\\Deep')).rejects.toMatchObject({ status: 422 });
+    await expect(h.svc.deletePlugin(USER, 'teams/Nope')).rejects.toMatchObject({ status: 404 });
+  });
+
+  it('removes nothing but the plugin it names — a sibling that happens to look like a park survives', async () => {
+    await fs.mkdir(path.join(h.dir, KB, 'Plugins/teams/Deep'), { recursive: true });
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/plugin.json'), '{"name":"deep"}');
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/access.md'), '---\n---\n');
+    // Whatever this is — a person's folder, the residue of a crashed run — it is not ours to delete.
+    await fs.mkdir(path.join(h.dir, KB, 'Plugins/teams/.Deep.deleting'), { recursive: true });
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/.Deep.deleting/keep.md'), 'mine');
+
+    await h.svc.deletePlugin(USER, 'teams/Deep');
+
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/teams/Deep'))).rejects.toThrow();
+    expect(await fs.readFile(path.join(h.dir, KB, 'Plugins/teams/.Deep.deleting/keep.md'), 'utf-8')).toBe('mine');
+    expect(await fs.readdir(path.join(h.dir, KB, 'Plugins/teams'))).toEqual(['.Deep.deleting']);
+  });
+
+  it('deletes only the exact spelling, at every depth — a stale casing must not park a replacement at the same place', async () => {
+    await fs.mkdir(path.join(h.dir, KB, 'Plugins/teams/Deep'), { recursive: true });
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/plugin.json'), '{"name":"deep"}');
+    await fs.writeFile(path.join(h.dir, KB, 'Plugins/teams/Deep/access.md'), '---\n---\n');
+
+    // On a case-insensitive filesystem both of these `stat` fine — and must still be refused.
+    await expect(h.svc.deletePlugin(USER, 'teams/deep')).rejects.toMatchObject({ status: 404 });
+    await expect(h.svc.deletePlugin(USER, 'Teams/Deep')).rejects.toMatchObject({ status: 404 });
+    expect(await fs.readdir(path.join(h.dir, KB, 'Plugins/teams'))).toEqual(['Deep']);
+    expect(h.commits.runPendingCommit).not.toHaveBeenCalled();
+  });
+
+  it('a folder that cannot be LISTED is an error, never "unknown plugin" — absence and failure are different answers', async () => {
+    await h.svc.createPlugin(USER, 'GTM');
+    const real = fs.readdir;
+    const spy = vi.spyOn(fs, 'readdir').mockImplementation(((dir: string, opts: unknown) => {
+      if (String(dir).endsWith('Plugins')) {
+        return Promise.reject(Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' }));
+      }
+      return (real as (d: string, o: unknown) => Promise<unknown>).call(fs, dir, opts);
+    }) as never);
+    try {
+      // Discovery cannot list the root: a hole, refused as such — never "unknown plugin" (404).
+      await expect(h.svc.deletePlugin(USER, 'GTM')).rejects.toMatchObject({ status: 503 });
+      await expect(h.svc.createPlugin(USER, 'Ops')).rejects.toMatchObject({ status: 503 });
+    } finally {
+      spy.mockRestore();
+    }
+    // Nothing moved, nothing committed: the plugin is exactly where it was.
+    await expect(fs.stat(path.join(h.dir, KB, 'Plugins/GTM/plugin.json'))).resolves.toBeDefined();
+    expect(h.commits.runPendingCommit).toHaveBeenCalledTimes(1); // the create above only
+  });
+
   it('never deletes a personal folder through the plugin door', async () => {
     await h.svc.ensurePersonalPlugin(USER);
     const folder = personalPluginFolderName(USER.id);
@@ -260,7 +460,7 @@ describe('PluginProvisionService.ensurePersonalPlugin', () => {
     const folder = personalPluginFolderName(USER.id);
 
     const first = await h.svc.ensurePersonalPlugin(USER);
-    expect(first).toEqual({ folder, created: true });
+    expect(first).toEqual({ folder, name: folder, created: true });
     const accessMd = await fs.readFile(
       path.join(h.dir, KB, 'Plugins', folder, 'access.md'),
       'utf-8',
@@ -273,7 +473,7 @@ describe('PluginProvisionService.ensurePersonalPlugin', () => {
     }
 
     const second = await h.svc.ensurePersonalPlugin(USER);
-    expect(second).toEqual({ folder, created: false });
+    expect(second).toEqual({ folder, name: folder, created: false });
     // Idempotent for real: one provision (access.md + plugin.json), one commit.
     expect(h.writeFile).toHaveBeenCalledTimes(2);
     expect(h.commits.runPendingCommit).toHaveBeenCalledTimes(1);