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

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

@@ -1,7 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
-  DEFAULT_BRANCH,
   PLUGIN_MANIFEST_FILE,
   linkedSkillRoots,
   normalizeSkillRoot,
@@ -19,8 +18,57 @@ import { pluginPrincipalKey } from '../access-model/access-grammar.js';
 import type { Principal } from '../access-model/access-splice.js';
 import { WorkspaceMutex } from '../kb-fs/mutex.js';
 import type { ISkillService } from '../skills/skills.contract.js';
+import { logger } from '../../shared/logging.js';
 import type { ProvisionCommitDriver } from './plugin-provision.service.js';
-import { linksWorkspaceId, type PluginLinkIndex } from './plugin-links.js';
+import type { PluginLinkIndex } from './plugin-links.js';
+import type { KbContext } from '../../shared/kb-context.js';
+
+const log = logger('plugins');
+
+/** Who may edit one skill root's access file, in the terms the banner names them. */
+export interface LinkEditors {
+  roles: string[];
+  users: { name: string; email: string }[];
+}
+
+/** One link the automatic repair left alone, and why — see `repairAll`. */
+export interface UnrepairedLink {
+  /** Repo-relative root, as the manifest declares it. */
+  root: string;
+  /**
+   * `needs-skill-write` — the viewer may not write the root's access file, so
+   * nothing was attempted; `failed` — the write was attempted and did not
+   * land; `denied` — both lines are already in the file and the link is still
+   * not granted, which is a `deny` of the plugin at that root: nothing to
+   * write, and only an editor removing the deny would change it. All three
+   * leave the link broken and all three keep the banner.
+   */
+  reason: 'needs-skill-write' | 'failed' | 'denied';
+  /** The skills the plugin's members still cannot read through the root. */
+  skills: { path: string; name: string }[];
+  /** Who can repair it from the skill page. */
+  editors: LinkEditors;
+}
+
+/** What one page-open repair did and what it could not do. */
+export interface LinkRepairReport {
+  /** Roots whose two grant lines are now in place (silent: nothing to show). */
+  repaired: string[];
+  /** What is still broken, and who can fix it. */
+  skipped: UnrepairedLink[];
+}
+
+/**
+ * The commit subject for an automatic repair. It names the plugin, the root
+ * and the fact that nobody asked for it — the commit is the ONLY trace a
+ * silent repair leaves, so the history has to explain itself. Falls back to
+ * the path-derived default when a very long root would blow the 200-character
+ * subject limit: a missed explanation is not worth a failed repair.
+ */
+function repairSummary(plugin: string, root: string): string | undefined {
+  const subject = `Repair link: ${plugin} → ${root} (automatic, on opening the plugin page)`;
+  return subject.length <= 200 ? subject : undefined;
+}
 
 /** A refusal the route passes through: message + HTTP status + a machine-readable kind. */
 export class PluginLinkError extends Error {
@@ -59,7 +107,9 @@ export class PluginLinkError extends Error {
  * skill page says so, for a skill editor to remove.
  *
  * Repair re-grants the tokens for a link that exists but whose grant was
- * hand-removed: the amber dot's one action.
+ * hand-removed — the amber dot's one action, run one link at a time from the
+ * skill page, or over a whole plugin's links by `repairAll` the moment
+ * somebody who may write that plugin opens its page.
  *
  * Every operation is serialised on BOTH sides it writes — the plugin's
  * manifest slug (the same key provisioning locks on) and the skill root whose
@@ -77,19 +127,23 @@ export class PluginLinksService {
     private readonly accessControl: IAccessControl,
     private readonly skillService: ISkillService,
     private readonly links: PluginLinkIndex,
-    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,
   ) {
-    this.mutation = new AccessMutationService(workspaceService, accessControl, kbDirName);
+    this.mutation = new AccessMutationService(workspaceService, accessControl, kb.kbDirName);
+  }
+
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
   }
 
   async link(user: AuthUser, plugin: string, rawRoot: string): Promise<{ root: string; skills: string[] }> {
     const folder = await this.pluginFolder(plugin);
     const root = this.rootOrThrow(rawRoot);
-    const wsId = linksWorkspaceId();
+    const wsId = this.kb.defaultWorkspaceId();
     await this.requirePluginWrite(wsId, user, folder);
     const skills = await this.resolvedSkills(root);
     if (skills.length === 0) {
@@ -125,7 +179,7 @@ export class PluginLinksService {
           manifestRel,
           `${JSON.stringify(withLinkedSkillRoots(manifest, [...roots, root]), null, 2)}\n`,
         );
-        await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, manifestRel, user);
+        await this.commits.runPendingCommit(wsId, this.kb.defaultBranch, manifestRel, user);
       }
       await this.grantTokens(wsId, user, folder, root);
       this.changed(wsId);
@@ -136,7 +190,7 @@ export class PluginLinksService {
   async unlink(user: AuthUser, plugin: string, rawRoot: string): Promise<{ root: string; revoked: boolean }> {
     const folder = await this.pluginFolder(plugin);
     const root = this.rootOrThrow(rawRoot);
-    const wsId = linksWorkspaceId();
+    const wsId = this.kb.defaultWorkspaceId();
     await this.requirePluginWrite(wsId, user, folder);
     return this.locks.runAll(this.lockKeys(folder, root), async () => {
       const { manifest, manifestRel } = await this.readManifest(wsId, folder);
@@ -163,7 +217,7 @@ export class PluginLinksService {
         if (changed) {
           await this.commits.runPendingCommit(
             wsId,
-            DEFAULT_BRANCH,
+            this.kb.defaultBranch,
             `${this.kbDirName}/${accessMdPathForFolder(root)}`,
             user,
           );
@@ -175,16 +229,36 @@ export class PluginLinksService {
         manifestRel,
         `${JSON.stringify(withLinkedSkillRoots(manifest, roots.filter((r) => r !== root)), null, 2)}\n`,
       );
-      await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, manifestRel, user);
+      await this.commits.runPendingCommit(wsId, this.kb.defaultBranch, manifestRel, user);
       this.changed(wsId);
       return { root, revoked };
     });
   }
 
-  async repair(user: AuthUser, plugin: string, rawRoot: string): Promise<{ root: string }> {
+  /**
+   * Re-grant one link's two tokens. The skill EDITOR's verb (the plugin side
+   * is not consulted): the amber dot's one manual action, and the single
+   * write the automatic repair runs too — see {@link repairAll}.
+   *
+   * `summary` is the commit subject when the caller has a better one than the
+   * path-derived default; the automatic repair passes one that says it was
+   * automatic, because the commit is the only trace it leaves.
+   *
+   * `written` says whether the file changed. A root that already carried
+   * both lines is left alone and reports false — which, for a root the index
+   * called ungranted, means the lines are not what is missing (a `deny`
+   * beside them is): the automatic repair reads it as "still broken", not as
+   * repaired.
+   */
+  async repair(
+    user: AuthUser,
+    plugin: string,
+    rawRoot: string,
+    opts?: { summary?: string },
+  ): Promise<{ root: string; written: boolean }> {
     const folder = await this.pluginFolder(plugin);
     const root = this.rootOrThrow(rawRoot);
-    const wsId = linksWorkspaceId();
+    const wsId = this.kb.defaultWorkspaceId();
     // Everything under the lock, the manifest read included: a repair that
     // checked the link and then waited on an unlink would re-grant a root the
     // manifest no longer names.
@@ -199,14 +273,98 @@ export class PluginLinksService {
           root,
         });
       }
-      await this.grantTokens(wsId, user, folder, root);
+      const written = await this.grantTokens(wsId, user, folder, root, opts?.summary);
       this.changed(wsId);
-      return { root };
+      return { root, written };
     });
   }
 
+  /**
+   * Repair EVERY link of `plugin` that is missing its grants — what opening
+   * the plugin's page runs for someone who may write the plugin.
+   *
+   * Two gates, in this order: the caller must be able to write the PLUGIN
+   * (this is the plugin's page repairing its own links, not a way to write
+   * other people's access files), and then, per root, to write that root's
+   * access file. A root they cannot write is left exactly as it is and comes
+   * back in `skipped` with the people who CAN write it, which is the sentence
+   * the banner then says. Nothing comes back for a root that was repaired:
+   * the commit is the trace, the page simply renders with the link healthy.
+   *
+   * Root by root through {@link repair} — the same write, the same manifest
+   * check, the same pair of locks — so the automatic path and the button on
+   * the skill page can never write different things. Each root's failure is
+   * caught into `skipped`: one unwritable file must not cost the others their
+   * repair, nor the page its render.
+   *
+   * A root the repair did not have to write is NOT repaired. The work list
+   * holds only roots the index called ungranted, so a root whose two lines
+   * were already there is broken by something the lines cannot fix — a `deny`
+   * of the plugin in that same file — and reporting it repaired would hide
+   * the one link the writer opening this page could not see anywhere else.
+   */
+  async repairAll(user: AuthUser, plugin: string): Promise<LinkRepairReport> {
+    const folder = await this.pluginFolder(plugin);
+    const wsId = this.kb.defaultWorkspaceId();
+    await this.requirePluginWrite(wsId, user, folder);
+    // Read the work list ONCE, before the first write: `repair` invalidates
+    // the index, and re-reading it per root would rebuild the whole membership
+    // between every commit.
+    const work = (await this.links.membership()).byPlugin.get(folder)?.ungrantedRoots ?? [];
+    if (work.length === 0) return { repaired: [], skipped: [] };
+    const named = new Map((await this.skillService.listSkills(undefined)).map((s) => [s.path, s.name]));
+    const repaired: string[] = [];
+    const skipped: UnrepairedLink[] = [];
+    const leftBroken = async (item: (typeof work)[number], reason: UnrepairedLink['reason']) => {
+      skipped.push({
+        root: item.root,
+        reason,
+        skills: item.skills.map((path) => ({ path, name: named.get(path) ?? path.split('/').pop() ?? path })),
+        editors: await this.editorsOf(wsId, item.root),
+      });
+    };
+    for (const item of work) {
+      try {
+        const { written } = await this.repair(user, folder, item.root, { summary: repairSummary(folder, item.root) });
+        if (written) repaired.push(item.root);
+        else await leftBroken(item, 'denied');
+      } catch (err) {
+        const needsWrite = err instanceof PluginLinkError && err.payload.kind === 'needs-skill-write';
+        if (!needsWrite) log.warn('automatic link repair failed:', { plugin: folder, root: item.root, err });
+        await leftBroken(item, needsWrite ? 'needs-skill-write' : 'failed');
+      }
+    }
+    return { repaired, skipped };
+  }
+
   // --- internal --------------------------------------------------------------
 
+  /**
+   * Who may edit a root's access file — the principals the banner names as
+   * the people who can repair a link this viewer cannot.
+   *
+   * Plugin principals are dropped: `plugin/gtm/write` is a real holder of the
+   * verb, and naming it in a sentence addressed to a person says nothing they
+   * could act on. The eligible lists carry emails and no display names, so an
+   * email stands in — every name here has to be something a reader can go and
+   * ask. A lookup that fails names nobody rather than failing the whole
+   * repair — the banner has a sentence for that.
+   */
+  private async editorsOf(wsId: string, root: string): Promise<LinkEditors> {
+    try {
+      const writers = await this.accessControl.eligibleWriters(wsId, accessMdPathForFolder(root));
+      return {
+        roles: writers.principals
+          ? writers.principals.filter((p) => p.kind !== 'plugin').map((p) => p.name)
+          : writers.roles,
+        users: writers.users.map((u) => ({ name: u.name || u.email, email: u.email })),
+      };
+    } catch (err) {
+      log.warn("couldn't resolve a skill root's editors:", { root, err });
+      return { roles: [], users: [] };
+    }
+  }
+
   /**
    * ONE reservation for both sides of a link: the plugin's manifest AND the
    * skill root's access.md. Two plugins linking the same root write the same
@@ -232,13 +390,28 @@ export class PluginLinksService {
     ];
   }
 
-  private async grantTokens(wsId: string, user: AuthUser, folder: string, root: string): Promise<void> {
+  /**
+   * The two lines, and a commit only if they were not already there — the
+   * `changed` check is what makes re-linking, Repair and the page-open repair
+   * idempotent rather than a stream of empty commits. Returns whether the
+   * file changed, so a caller can tell a repair that wrote from one that had
+   * nothing to write.
+   */
+  private async grantTokens(
+    wsId: string,
+    user: AuthUser,
+    folder: string,
+    root: string,
+    summary?: string,
+  ): Promise<boolean> {
     const [read, write] = this.tokens(folder);
     const a = await this.mutation.grant(wsId, 'folder', root, 'read', read);
     const b = await this.mutation.grant(wsId, 'folder', root, 'write', write);
-    if (a.changed || b.changed) {
-      await this.commits.runPendingCommit(wsId, DEFAULT_BRANCH, `${this.kbDirName}/${a.editPath}`, user);
-    }
+    if (!(a.changed || b.changed)) return false;
+    await this.commits.runPendingCommit(wsId, this.kb.defaultBranch, `${this.kbDirName}/${a.editPath}`, user, {
+      summary,
+    });
+    return true;
   }
 
   private rootOrThrow(raw: string): string {
@@ -345,6 +518,6 @@ export class PluginLinksService {
     this.links.invalidate();
     this.accessControl.invalidate(wsId);
     this.onChanged?.();
-    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 });
   }
 }

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
+    }
+  }
 }