@bevel-software/platform-core-backend 0.20.0 → 0.21.0

package/src/modules/plugins/plugin-links.ts

@@ -2,9 +2,9 @@ import path from 'node:path';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('plugins');
-import { DEFAULT_BRANCH, pluginManifestName, skillUnderRoot } from '@bevel-software/platform-shared';
+import { pluginManifestName, skillUnderRoot } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
-import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import type { ISkillService } from '../skills/skills.contract.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
@@ -26,10 +26,35 @@ export interface PluginLinks {
   linkedSkills: string[];
   /** Roots that resolve to no released skill — a typo, or a skill not yet merged. */
   unresolvedRoots: string[];
+  /**
+   * The declared roots whose OWN access file does not carry this plugin's two
+   * grant lines, each with the linked skills its members cannot read through
+   * it — the automatic repair's work list, and the only thing that says WHICH
+   * file to write (`brokenLinks` counts skills, and a root holding twenty of
+   * them is still one file). Empty for an unmanaged (dialect) plugin, whose
+   * links grant nothing, and for a plugin whose links are all healthy.
+   */
+  ungrantedRoots: UngrantedRoot[];
   /** Whether hexis writes these links and checks their grants — see `DiscoveredPlugin`. */
   linksAreManaged: boolean;
 }
 
+/** One declared root missing its grants, with the skills that go without. */
+export interface UngrantedRoot {
+  /** Repo-relative root, exactly as the manifest declares it. */
+  root: string;
+  /** The released skill folders under it the plugin's members cannot read. */
+  skills: string[];
+}
+
+/**
+ * The two verbs a link grants — the pair `PluginLinksService.grantTokens`
+ * writes and this index looks for. `owner` is deliberately not one of them: a
+ * link shares a skill and lets the plugin's managers edit it; it never hands
+ * over who validates it.
+ */
+export const LINK_GRANT_VERBS = ['read', 'write'] as const;
+
 export interface LinkMembership {
   /** skill path → every plugin that holds it, inline or by link. */
   bySkill: Map<string, PluginMembership[]>;
@@ -49,10 +74,15 @@ export interface LinkMembership {
  * and the global-name dedup, and a second walk here would be a second
  * opinion about what a skill is.
  *
- * `granted` is the consistency check the amber dot renders: a linked skill
- * whose own access rules DO grant the plugin's `plugin/<Name>/read`
- * principal (directly or from a scope above it). The link service writes
- * that grant with the link; only a hand edit takes it away.
+ * `granted` is the consistency check the amber dot renders, and it is a
+ * question about the FILE, not about who happens to be able to read the skill
+ * today: a link is granted when the declared ROOT's own access file carries
+ * both `plugin/<Name>/read` and `plugin/<Name>/write`, and neither is denied
+ * at that root or between it and the skill. A root that is readable by
+ * everyone, or that inherits a plugin grant from a folder above, is NOT
+ * granted — the grant is the link's contract, and a public root merely hides
+ * its absence until the day someone restricts the tree. The link service
+ * writes those two lines with the link; only a hand edit takes them away.
  *
  * Cached briefly, dropped by `invalidate()` from the same file-change
  * subscriber that drops the plugin index, so a link committed on the default
@@ -65,7 +95,7 @@ export class PluginLinkIndex {
     private readonly workspaceService: WorkspaceService,
     private readonly skillService: ISkillService,
     private readonly accessControl: IAccessControl,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     /** Where plugins come from — the one discovery every catalog shares. */
     private readonly source: PluginSource,
     now: () => number = Date.now,
@@ -73,6 +103,10 @@ export class PluginLinkIndex {
     this.cache = new TtlCache(CACHE_TTL_MS, now);
   }
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   invalidate(): void {
     this.cache.invalidate();
   }
@@ -104,7 +138,7 @@ export class PluginLinkIndex {
     let wsId: string;
     let kbRoot: string;
     try {
-      wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
+      wsId = (await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch)).id;
       kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
     } catch {
       return null;
@@ -140,10 +174,58 @@ export class PluginLinkIndex {
       const roots = plugin.linkedRoots;
       const linkedSkills: string[] = [];
       const unresolvedRoots: string[] = [];
+      /** Which declared roots each linked skill arrives through. */
+      const rootsOfSkill = new Map<string, string[]>();
       for (const root of roots) {
         const hits = skills.filter((s) => skillUnderRoot(s.path, root)).map((s) => s.path);
         if (hits.length === 0) unresolvedRoots.push(root);
-        for (const hit of hits) if (!linkedSkills.includes(hit)) linkedSkills.push(hit);
+        for (const hit of hits) {
+          if (!linkedSkills.includes(hit)) linkedSkills.push(hit);
+          rootsOfSkill.set(hit, [...(rootsOfSkill.get(hit) ?? []), root]);
+        }
+      }
+      // A skill — or a root — that sits INSIDE this plugin's folder is inline:
+      // its membership already stands, and no grant is written for it.
+      const inline = (p: string) => p === plugin.folder || p.startsWith(`${plugin.folder}/`);
+      const slug = pluginManifestName(plugin.name);
+      // Root by root FIRST, skill by skill second: the grant lives on the
+      // root's access file, so a root holding twenty skills is one question to
+      // the resolver, not twenty. An unmanaged (dialect) link is a plain
+      // reference — nothing to grant, nothing to repair — so it asks none.
+      const carriesGrants = new Map<string, boolean>();
+      if (plugin.linksAreManaged) {
+        for (const root of roots) {
+          if (inline(root)) continue;
+          carriesGrants.set(root, await this.rootCarriesGrants(wsId, root, slug));
+        }
+      }
+      const grantedSkills = new Map<string, boolean>();
+      for (const skillPath of linkedSkills) {
+        if (inline(skillPath)) continue;
+        if (!plugin.linksAreManaged) {
+          grantedSkills.set(skillPath, true);
+          continue;
+        }
+        let granted = false;
+        for (const root of rootsOfSkill.get(skillPath) ?? []) {
+          if (!carriesGrants.get(root)) continue;
+          if (await this.deniedBetween(wsId, root, skillPath, slug)) continue;
+          granted = true;
+          break;
+        }
+        grantedSkills.set(skillPath, granted);
+      }
+      // What the automatic repair has to write: a root missing its lines, with
+      // the skills that are actually going without because of it. A root whose
+      // skills all reach the plugin through ANOTHER declared root is nothing to
+      // repair — there is no broken link to fix, and a write would be noise.
+      const ungrantedRoots: UngrantedRoot[] = [];
+      for (const root of roots) {
+        if (inline(root) || carriesGrants.get(root) !== false) continue;
+        const without = linkedSkills.filter(
+          (s) => !inline(s) && (rootsOfSkill.get(s) ?? []).includes(root) && grantedSkills.get(s) === false,
+        );
+        if (without.length > 0) ungrantedRoots.push({ root, skills: without });
       }
       byPlugin.set(plugin.name, {
         name: plugin.name,
@@ -151,37 +233,75 @@ export class PluginLinkIndex {
         roots,
         linkedSkills,
         unresolvedRoots,
+        ungrantedRoots,
         linksAreManaged: plugin.linksAreManaged,
       });
-      if (linkedSkills.length === 0) continue;
-      const token = pluginPrincipalKey(pluginManifestName(plugin.name), 'read');
       for (const skillPath of linkedSkills) {
-        // A skill that also sits INSIDE this plugin folder is inline, and its
-        // inline membership already stands.
-        if (skillPath.startsWith(`${plugin.folder}/`)) continue;
-        // An unmanaged (dialect) link is a plain reference: nothing to grant,
-        // nothing to repair — the skill's own scope decides who reads it.
-        const granted = plugin.linksAreManaged ? await this.isGranted(wsId, skillPath, token) : true;
-        add(skillPath, { name: plugin.name, linked: true, granted });
+        if (inline(skillPath)) continue;
+        add(skillPath, { name: plugin.name, linked: true, granted: grantedSkills.get(skillPath) === true });
       }
     }
     return { bySkill, byPlugin };
   }
 
-  /** Whether the skill folder's effective readers include the plugin's read principal. */
-  private async isGranted(wsId: string, skillPath: string, token: string): Promise<boolean> {
+  /**
+   * Whether the ROOT's own access file carries both of the link's grant lines.
+   *
+   * "Its own" is the whole rule: `grantSources` reports every scope that
+   * grants the principal, closest-first, so `[0].kind === 'direct'` is
+   * "granted by the file this root's link writes" — a grant inherited from a
+   * folder above is an `ancestor` source and does not count, and a root that
+   * is simply public names the principal nowhere and yields no source at all.
+   * `tokenMatch: 'exact'` pins the comparison to the canonical token the
+   * grant is written as, the same spelling `grantTokens` splices.
+   *
+   * A `deny` of either token in that same file is not granted either, whatever
+   * the resolver makes of a grant beside it: the deny is the operator's, the
+   * repair never removes it, and reporting the link as healthy would hide the
+   * one thing the banner exists to say. `locallyDeniedPrincipals` is what sees
+   * it — the per-verb denial walk cannot, since a grant in the same scope wins
+   * there and ends the walk.
+   */
+  private async rootCarriesGrants(wsId: string, root: string, slug: string): Promise<boolean> {
     try {
-      const readers = await this.accessControl.eligibleReaders(wsId, skillPath);
-      if (!readers.restricted) return true; // readable by everyone — the plugin's members included
+      for (const verb of LINK_GRANT_VERBS) {
+        const principal = { kind: 'role' as const, role: pluginPrincipalKey(slug, verb) };
+        const sources = await this.accessControl.grantSources(wsId, 'folder', root, principal, {
+          tokenMatch: 'exact',
+        });
+        if (sources[verb]?.[0]?.kind !== 'direct') return false;
+      }
+      const denied = await this.accessControl.locallyDeniedPrincipals?.(wsId, 'folder', root);
+      const tokens: string[] = LINK_GRANT_VERBS.map((verb) => pluginPrincipalKey(slug, verb));
       // The resolver reports display names; compare through the one canonicaliser.
-      return (readers.principals ?? []).some((p) => p.kind === 'plugin' && canonicalRoleName(p.name) === token);
+      return !(denied?.principals ?? []).some((p) => tokens.includes(canonicalRoleName(p.name)));
     } catch {
       return false; // fail closed: an unreadable tree reports the link as needing repair
     }
   }
-}
 
-/** The default-branch workspace id every link resolution runs against. */
-export function linksWorkspaceId(): string {
-  return workspaceIdForBranch(DEFAULT_BRANCH);
+  /**
+   * Whether either grant is DENIED below the root — at the skill's own folder
+   * or at anything between it and the root.
+   *
+   * The denial walk stops at a closer grant, and the root's grant is what
+   * brought us here, so what this reports is exactly the scopes under the
+   * root: a `deny` above the root is dead under closeness-first and is not
+   * this link's problem.
+   */
+  private async deniedBetween(wsId: string, root: string, skillPath: string, slug: string): Promise<boolean> {
+    if (skillPath === root) return false; // the root's own file is `rootCarriesGrants`' business
+    try {
+      for (const verb of LINK_GRANT_VERBS) {
+        const principal = { kind: 'role' as const, role: pluginPrincipalKey(slug, verb) };
+        const denials = await this.accessControl.denialSources?.(wsId, 'folder', skillPath, principal, {
+          tokenMatch: 'exact',
+        });
+        if ((denials?.[verb] ?? []).length > 0) return true;
+      }
+      return false;
+    } catch {
+      return true; // fail closed, as above
+    }
+  }
 }

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

@@ -38,8 +38,6 @@ import type { IFsProbe } from '../../shared/fs.contract.js';
 import type { Discovery, PluginSource } from './discovery/plugin-source.js';
 
 import {
-  DEFAULT_BRANCH,
-  PLUGINS_DIR,
   PLUGIN_MANIFEST_FILE,
   PLUGIN_SKILLS_DIR,
   pluginDisplayNameOf,
@@ -52,6 +50,7 @@ import {
   validateFilename,
   type AuthUser,
 } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { creatorPrincipal } from '../access-model/creator.js';
@@ -65,7 +64,8 @@ export interface ProvisionCommitDriver {
     branch: string,
     targetPath: string,
     user: AuthUser,
-    opts?: { systemAuthorized?: boolean },
+    /** `summary` overrides the path-derived commit subject — see `GitService.commitFile`. */
+    opts?: { systemAuthorized?: boolean; summary?: string },
   ): Promise<void>;
 }
 
@@ -129,8 +129,14 @@ export class PluginProvisionError extends Error {
 }
 
 /** The one shape every provisioning answer has: the folder in both spellings, and where its skills go. */
-function provisioned(folder: string, name: string, displayName: string, created: boolean): ProvisionedPlugin {
-  const path = `${PLUGINS_DIR}/${folder}`;
+function provisioned(
+  pluginsDir: string,
+  folder: string,
+  name: string,
+  displayName: string,
+  created: boolean,
+): ProvisionedPlugin {
+  const path = `${pluginsDir}/${folder}`;
   return { folder, path, skillsDir: `${path}/${PLUGIN_SKILLS_DIR}`, name, displayName, created };
 }
 
@@ -149,13 +155,22 @@ export class PluginProvisionService {
     private readonly workspaceService: WorkspaceService,
     private readonly commits: ProvisionCommitDriver,
     private readonly accessControl: IAccessControl,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     private readonly events: { emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void } | undefined,
     /** Which names are TAKEN is discovery's answer — the same one every catalog gets. */
     private readonly source: PluginSource,
     private readonly disk: IFsProbe,
   ) {}
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
+  /** The plugins root's name, read per use: a deployment may rename it from the setup screen. */
+  private get pluginsRoot(): string {
+    return this.kb.layout.pluginsDir;
+  }
+
   /**
    * Create `Plugins/<name>/` — or `Plugins/<parent>/<name>/` — for `user`.
    * Throws `PluginProvisionError` 422 on a name the filesystem or the model
@@ -226,7 +241,7 @@ export class PluginProvisionService {
       // `name` is the creator's own spelling, trimmed — the folder's leaf AND
       // the display name persisted for it, whether or not it equals either.
       await this.provision(user, folder, name, pluginAccessMd(user));
-      return provisioned(folder, pluginManifestName(name), name, true);
+      return provisioned(this.pluginsRoot, folder, pluginManifestName(name), name, true);
     });
   }
 
@@ -246,7 +261,7 @@ export class PluginProvisionService {
     if (segments.some((s) => validateFilename(s) !== null || s.startsWith('.'))) {
       throw new PluginProvisionError(`"${rawParent}" is not a folder name the knowledge base can carry.`, 422);
     }
-    const rel = `${PLUGINS_DIR}/${rawParent}`;
+    const rel = `${this.pluginsRoot}/${rawParent}`;
     // The personal namespace is the FIRST segment below the root — the same
     // structural rule as `isPersonalPluginDir`, applied to the parent and
     // everything under it. A `personal-*` folder there is a personal space
@@ -257,8 +272,8 @@ export class PluginProvisionService {
     }
     const wsId = await this.readyWorkspaceId();
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-    if (!(await this.exactFolderExists(path.join(wsDir, this.kbDirName, PLUGINS_DIR), segments))) {
-      throw new PluginProvisionError(`There is no folder "${rawParent}" under ${PLUGINS_DIR}/.`, 404);
+    if (!(await this.exactFolderExists(path.join(wsDir, this.kbDirName, this.pluginsRoot), segments))) {
+      throw new PluginProvisionError(`There is no folder "${rawParent}" under ${this.pluginsRoot}/.`, 404);
     }
     // Judged against every folder discovery CLAIMS, not only the plugins it
     // lists: a twin skipped for its slug still owns its subtree, and a
@@ -287,7 +302,13 @@ export class PluginProvisionService {
     return this.creations.run(`plugin:${pluginManifestName(folder)}`, async () => {
       const existing = await this.existingFolder(folder);
       if (existing !== null) {
-        return provisioned(folder, pluginManifestName(folder), await this.persistedDisplayName(existing, folder), false);
+        return provisioned(
+          this.pluginsRoot,
+          folder,
+          pluginManifestName(folder),
+          await this.persistedDisplayName(existing, folder),
+          false,
+        );
       }
       try {
         await this.provision(user, folder, folder, personalAccessMd(user));
@@ -296,11 +317,17 @@ export class PluginProvisionService {
         // process, a checkout that appeared between check and write): the
         // folder existing is this method's success case, never its error.
         if (err instanceof PluginProvisionError && err.status === 409) {
-          return provisioned(folder, pluginManifestName(folder), await this.persistedDisplayName(folder, folder), false);
+          return provisioned(
+            this.pluginsRoot,
+            folder,
+            pluginManifestName(folder),
+            await this.persistedDisplayName(folder, folder),
+            false,
+          );
         }
         throw err;
       }
-      return provisioned(folder, pluginManifestName(folder), folder, true);
+      return provisioned(this.pluginsRoot, folder, pluginManifestName(folder), folder, true);
     });
   }
 
@@ -343,14 +370,14 @@ export class PluginProvisionService {
     if (!name || segments.some((s) => validateFilename(s) !== null || s.startsWith('.'))) {
       throw new PluginProvisionError('A plugin needs a name.', 422);
     }
-    if (isPersonalPluginDir(`${PLUGINS_DIR}/${name}`)) {
+    if (isPersonalPluginDir(`${this.pluginsRoot}/${name}`, this.kb.layout)) {
       // Personal folders are not plugins (the catalog never lists them), and
       // nobody deletes somebody's private shelf through the plugin door.
       throw new PluginProvisionError('Unknown plugin', 404);
     }
     const wsId = await this.readyWorkspaceId();
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-    const pluginsDir = path.join(wsDir, this.kbDirName, PLUGINS_DIR);
+    const pluginsDir = path.join(wsDir, this.kbDirName, this.pluginsRoot);
     const folderDir = path.join(pluginsDir, ...segments);
     // Locked on the plugin's IDENTITY — the same key a creation of that name
     // takes — not on a slug of the folder path, which for a nested plugin is a
@@ -361,7 +388,7 @@ export class PluginProvisionService {
     // discovery refuses, as it does for creation. A folder discovery does not
     // list (no manifest at all) locks on its own slug — nothing else can
     // claim that identity either.
-    const identity = await this.discoveredIdentity(`${PLUGINS_DIR}/${name}`, segments[segments.length - 1]!);
+    const identity = await this.discoveredIdentity(`${this.pluginsRoot}/${name}`, segments[segments.length - 1]!);
     return this.creations.run(`plugin:${identity}`, async () => {
       // Exact spelling of EVERY component — the catalog hands the route the
       // on-disk spelling, so a mismatch means the plugin is gone (or was
@@ -392,8 +419,8 @@ export class PluginProvisionService {
         // deletion under it: one commit, one removed plugin.
         await this.commits.runPendingCommit(
           wsId,
-          DEFAULT_BRANCH,
-          `${this.kbDirName}/${PLUGINS_DIR}/${name}`,
+          this.kb.defaultBranch,
+          `${this.kbDirName}/${this.pluginsRoot}/${name}`,
           user,
           { systemAuthorized: true },
         );
@@ -411,7 +438,7 @@ export class PluginProvisionService {
       // The folder's rules left the access model — drop the resolver cache
       // so the very next check runs against a tree without them.
       this.accessControl.invalidate(wsId);
-      this.events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: DEFAULT_BRANCH });
+      this.events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: this.kb.defaultBranch });
     });
   }
 
@@ -422,7 +449,7 @@ export class PluginProvisionService {
    */
   private async exactFolderExists(root: string, segments: string[]): Promise<boolean> {
     let dir = root;
-    let rel = PLUGINS_DIR;
+    let rel = this.pluginsRoot;
     for (const segment of segments) {
       const entries = await listDirOrIncomplete(this.disk, dir, rel);
       if (!entries?.some((e) => e.isDirectory() && e.name === segment)) return false;
@@ -439,7 +466,7 @@ export class PluginProvisionService {
   private async existingFolder(name: string, parent = ''): Promise<string | null> {
     const wsId = await this.readyWorkspaceId();
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-    const rel = parent ? `${PLUGINS_DIR}/${parent}` : PLUGINS_DIR;
+    const rel = parent ? `${this.pluginsRoot}/${parent}` : this.pluginsRoot;
     // No Plugins/ root yet — nothing can collide.
     const children = await listDirOrIncomplete(this.disk, path.join(wsDir, this.kbDirName, rel), rel);
     if (!children) return null;
@@ -461,7 +488,7 @@ export class PluginProvisionService {
     const wsId = await this.readyWorkspaceId();
     const wsDir = await this.workspaceService.getWorkspacePath(wsId);
     const manifest = await this.disk.readJsonObject(
-      path.join(wsDir, this.kbDirName, PLUGINS_DIR, ...folder.split('/'), PLUGIN_MANIFEST_FILE),
+      path.join(wsDir, this.kbDirName, this.pluginsRoot, ...folder.split('/'), PLUGIN_MANIFEST_FILE),
     );
     return pluginDisplayNameOf(manifest) || fallback;
   }
@@ -518,7 +545,7 @@ export class PluginProvisionService {
    */
   private async provision(user: AuthUser, folder: string, leaf: string, accessMd: string): Promise<void> {
     const wsId = await this.readyWorkspaceId();
-    const folderPath = `${this.kbDirName}/${PLUGINS_DIR}/${folder}`;
+    const folderPath = `${this.kbDirName}/${this.pluginsRoot}/${folder}`;
     const wsRelPath = `${folderPath}/access.md`;
     try {
       // Exclusive create — the fs is the arbiter of a same-name race, not
@@ -557,7 +584,7 @@ export class PluginProvisionService {
       // rule this endpoint exists to carve through. The endpoint has already
       // authorized the write (any signed-in user, unused name, exclusive
       // create), so the per-user gate is skipped for exactly this commit.
-      await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, folderPath, user, {
+      await this.commits.runPendingCommit(wsId, this.kb.defaultBranch, folderPath, user, {
         systemAuthorized: true,
       });
     } catch (err) {
@@ -568,7 +595,7 @@ export class PluginProvisionService {
       // so a concurrent writer's bytes can't be collateral.
       try {
         const wsDir = await this.workspaceService.getWorkspacePath(wsId);
-        const folderDir = path.join(wsDir, this.kbDirName, PLUGINS_DIR, folder);
+        const folderDir = path.join(wsDir, this.kbDirName, this.pluginsRoot, folder);
         await fs.rm(path.join(folderDir, 'access.md'), { force: true });
         await fs.rm(path.join(folderDir, PLUGIN_MANIFEST_FILE), { force: true });
         await fs.rmdir(folderDir).catch(() => {});
@@ -580,11 +607,11 @@ export class PluginProvisionService {
     // The folder's rules changed the access model — drop the resolver cache
     // so the very next check (the creator's first skill write) sees them.
     this.accessControl.invalidate(wsId);
-    this.events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: DEFAULT_BRANCH });
+    this.events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: this.kb.defaultBranch });
   }
 
   private async readyWorkspaceId(): Promise<string> {
-    const ws = await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH);
+    const ws = await this.workspaceService.getOrCreateForBranch(this.kb.defaultBranch);
     return ws.id;
   }
 }

package/src/modules/plugins/plugin-rename.service.ts

@@ -18,8 +18,8 @@ import {
   parsePluginPrincipalKey,
 } from '../access-model/access-grammar.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import type { PluginSource } from './discovery/plugin-source.js';
-import { linksWorkspaceId } from './plugin-links.js';
 
 export class PluginRenameError extends Error {
   constructor(
@@ -70,15 +70,19 @@ export class PluginRenameService {
     private readonly accessControl: IAccessControl,
     private readonly source: PluginSource,
     private readonly disk: ITreeWalker,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     private readonly events?: {
       emit(event: { kind: 'fs-tree-changed'; workspaceId: string; branch: string }): void;
     },
     private readonly onChanged?: () => void,
   ) {}
 
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   private noteChanged(wsId: string): void {
-    noteChangedFor(this.accessControl, this.events, this.onChanged, wsId);
+    noteChangedFor(this.accessControl, this.events, this.onChanged, wsId, this.kb.defaultBranch);
   }
 
   /** The READ phase must have seen everything it needed; a hole refuses the rename before any write. */
@@ -96,7 +100,7 @@ export class PluginRenameService {
     current: string,
     patch: { name?: unknown; displayName?: unknown },
   ): Promise<RenameResult> {
-    const wsId = linksWorkspaceId();
+    const wsId = this.kb.defaultWorkspaceId();
     const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
     // ONE walk of the checkout for everything the rename needs to know:
     // the plugins (discovery's listener) and every file that can carry a
@@ -277,9 +281,10 @@ function noteChangedFor(
   events: PluginRenameService['events'],
   onChanged: (() => void) | undefined,
   wsId: string,
+  branch: string,
 ): void {
   accessControl.invalidate(wsId);
-  events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch: linksWorkspaceIdBranch() });
+  events?.emit({ kind: 'fs-tree-changed', workspaceId: wsId, branch });
   onChanged?.();
 }
 
@@ -303,8 +308,3 @@ export function renamePluginPrincipalInText(text: string, oldName: string, nextN
     })
     .join('\n');
 }
-
-function linksWorkspaceIdBranch(): string {
-  // The default branch's workspace id IS its encoded branch name.
-  return decodeURIComponent(linksWorkspaceId());
-}