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

package/dist/modules/access/access-control.service.js

@@ -1,13 +1,18 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { execFile, spawn } from 'node:child_process';
-import { promisify } from 'node:util';
-import { createHash } from 'node:crypto';
+import { logger } from '../../shared/logging.js';
+const log = logger('access');
+import { isAbsence } from '../../shared/fs.contract.js';
+import { isGitTimeout } from '../../shared/git.contract.js';
+import { hashEmail } from '../../shared/email-identity.js';
+import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, isPersonalPluginDir, pluginIdentityOf, platformRestoreDestination, } from '@bevel-software/platform-shared';
 import { AccessConfigError, AccessUnreadableError } from '../access-model/access-errors.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { synthesizePluginPrincipals } from '../access-model/plugin-principals.js';
 import { GROUPS_YAML, SYNCED_GROUPS_YAML, parseGroupsFile, } from '../access-model/group-files.js';
-import { ADMIN_CANONICAL, EVERYONE_CANONICAL, EVERYONE_DISPLAY, KNOWN_VERBS, ROLE_TOKEN_PREFIX, accessMdSelfEntries, canonicalEmail, canonicalRoleName, isAccessMdPath, mergeGroupsIntoRoles, parseAccessFile, parseOwnAccessEntries, parseRolesYaml, sourceVerbsFor, } from '../access-model/access-grammar.js';
+import { ADMIN_CANONICAL, EVERYONE_CANONICAL, EVERYONE_DISPLAY, KNOWN_VERBS, ROLE_TOKEN_PREFIX, accessMdSelfEntries, canonicalEmail, canonicalRoleName, isAccessMdPath, mergeGroupsIntoRoles, parseAccessFile, parseOwnAccessEntries, parseRolesYaml, requiredVerbsFor, sourceVerbsFor, } from '../access-model/access-grammar.js';
 import { DIRECTORY_SYNC_BOT_EMAIL, DIRECTORY_SYNC_BOT_NAME, } from './directory-sync-bot.js';
-const execFileAsync = promisify(execFile);
 /**
  * Read many objects from a git repo in ONE `git cat-file --batch` process.
  * `specs` are `<ref>:<path>` lines; the result array is index-aligned with
@@ -16,61 +21,36 @@ const execFileAsync = promisify(execFile);
  * request: `<oid> <type> <size>\n<size bytes>\n`, or `<spec> missing\n`
  * (the spec may itself contain spaces, hence the endsWith checks).
  */
-function catFileBatch(repoDir, specs) {
-    return new Promise((resolve, reject) => {
-        const child = spawn('git', ['-C', repoDir, 'cat-file', '--batch'], {
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        const chunks = [];
-        const errChunks = [];
-        child.stdout.on('data', (c) => chunks.push(c));
-        child.stderr.on('data', (c) => errChunks.push(c));
-        // A dying git can close stdin mid-write; the 'close' handler below still
-        // fires with the exit code, which is the error we want to surface.
-        child.stdin.on('error', () => undefined);
-        child.on('error', reject);
-        child.on('close', (code) => {
-            if (code !== 0) {
-                reject(new Error(`git cat-file --batch exited ${code}: ${Buffer.concat(errChunks).toString('utf-8').trim()}`));
-                return;
-            }
-            try {
-                const out = Buffer.concat(chunks);
-                const results = [];
-                let off = 0;
-                for (let i = 0; i < specs.length; i++) {
-                    const nl = out.indexOf(0x0a, off);
-                    if (nl < 0)
-                        throw new Error('unexpected end of git cat-file output');
-                    const header = out.subarray(off, nl).toString('utf-8');
-                    off = nl + 1;
-                    if (header.endsWith(' missing') || header.endsWith(' ambiguous')) {
-                        results.push(null);
-                        continue;
-                    }
-                    const parts = header.split(' ');
-                    const size = Number(parts[2]);
-                    if (parts.length !== 3 || !Number.isInteger(size) || size < 0) {
-                        throw new Error(`unexpected git cat-file header: ${header}`);
-                    }
-                    // Non-blob (a directory path resolves to a tree) → null, but the
-                    // payload still has to be skipped to stay aligned.
-                    results.push(parts[1] === 'blob' ? out.subarray(off, off + size).toString('utf-8') : null);
-                    off += size + 1; // payload + trailing LF
-                }
-                resolve(results);
-            }
-            catch (err) {
-                reject(err);
-            }
-        });
-        child.stdin.write(`${specs.join('\n')}\n`);
-        child.stdin.end();
+async function catFileBatch(runner, repoDir, specs) {
+    // Bytes, not text: every `<size>` in the header counts bytes, and the walk
+    // below has to step by that count through content that is not all ASCII.
+    const { stdout: out } = await runner.run(repoDir, ['cat-file', '--batch'], {
+        input: `${specs.join('\n')}\n`,
+        encoding: 'buffer',
     });
-}
-/** Mirrors `shared/hash-email.ts`. Duplicated to avoid a cross-cutting import. */
-function sha256Email(email) {
-    return createHash('sha256').update(email.trim().toLowerCase()).digest('hex');
+    const results = [];
+    let off = 0;
+    for (let i = 0; i < specs.length; i++) {
+        const nl = out.indexOf(0x0a, off);
+        if (nl < 0)
+            throw new Error('unexpected end of git cat-file output');
+        const header = out.subarray(off, nl).toString('utf-8');
+        off = nl + 1;
+        if (header.endsWith(' missing') || header.endsWith(' ambiguous')) {
+            results.push(null);
+            continue;
+        }
+        const parts = header.split(' ');
+        const size = Number(parts[2]);
+        if (parts.length !== 3 || !Number.isInteger(size) || size < 0) {
+            throw new Error(`unexpected git cat-file header: ${header}`);
+        }
+        // Non-blob (a directory path resolves to a tree) → null, but the
+        // payload still has to be skipped to stay aligned.
+        results.push(parts[1] === 'blob' ? out.subarray(off, off + size).toString('utf-8') : null);
+        off += size + 1; // payload + trailing LF
+    }
+    return results;
 }
 function isBuiltInRole(canonicalRole) {
     return canonicalRole === EVERYONE_CANONICAL;
@@ -78,11 +58,6 @@ function isBuiltInRole(canonicalRole) {
 function roleKnown(roles, canonicalRole) {
     return roles.byCanonical.has(canonicalRole) || isBuiltInRole(canonicalRole);
 }
-/** True for the errno codes that mean "the file genuinely is not there". */
-function isAbsenceError(err) {
-    const code = err?.code;
-    return code === 'ENOENT' || code === 'ENOTDIR';
-}
 /**
  * Load the ACTIVE group source through `read` (working tree or at-ref — the
  * caller supplies the reader, so both model loaders share one mode rule):
@@ -90,13 +65,13 @@ function isAbsenceError(err) {
  * even when the synced file is empty or malformed — falling back would
  * resurrect retired manual groups); otherwise `groups.yaml` → manual mode.
  *
- * `read` returns null for a genuinely-absent file and may THROW for any other
- * failure. Only ENOENT/ENOTDIR count as absent (the caller may also whitelist
- * them into null); every other read error — notably a non-absence error on
- * `synced-groups.yaml` — is treated as a BROKEN source: no groups, no
- * fallback to the manual file (falling back would resurrect retired groups),
- * and an `ok: false` health marker. Structural parse failures degrade the
- * same way; this function never throws.
+ * `read` returns null for a genuinely-absent file — ENOENT/ENOTDIR, the
+ * reader's judgement through the fs probe — and THROWS for any other failure.
+ * Every thrown error — notably one on `synced-groups.yaml` — is treated as a
+ * BROKEN source: no groups, no fallback to the manual file (falling back
+ * would resurrect retired groups), and an `ok: false` health marker.
+ * Structural parse failures degrade the same way; this function never throws
+ * (except to let an `AccessUnreadableError` through — see below).
  */
 export async function loadActiveGroups(read) {
     const broken = (file, reason) => ({
@@ -119,15 +94,10 @@ export async function loadActiveGroups(read) {
         // the same error; groups cannot be the one input that does not.
         if (err instanceof AccessUnreadableError)
             throw err;
-        if (isAbsenceError(err)) {
-            syncedText = null;
-        }
-        else {
-            // A non-absence read error on the SYNCED source must NOT fall back to
-            // groups.yaml — the synced file may exist and its manual predecessor is
-            // retired. Broken-groups instead.
-            return broken(SYNCED_GROUPS_YAML, err instanceof Error ? err.message : String(err));
-        }
+        // A read error on the SYNCED source must NOT fall back to groups.yaml —
+        // the synced file may exist and its manual predecessor is retired.
+        // Broken-groups instead.
+        return broken(SYNCED_GROUPS_YAML, err instanceof Error ? err.message : String(err));
     }
     const sourceFile = syncedText !== null ? SYNCED_GROUPS_YAML : GROUPS_YAML;
     let text;
@@ -141,10 +111,7 @@ export async function loadActiveGroups(read) {
         catch (err) {
             if (err instanceof AccessUnreadableError)
                 throw err; // see above
-            if (isAbsenceError(err))
-                text = null;
-            else
-                return broken(GROUPS_YAML, err instanceof Error ? err.message : String(err));
+            return broken(GROUPS_YAML, err instanceof Error ? err.message : String(err));
         }
     }
     if (text === null)
@@ -165,17 +132,84 @@ export async function loadActiveGroups(read) {
  * `hasPermissionResolved`). `collapseScopes` flattens this into the
  * closest-wins-per-principal view the display helpers use.
  */
+/**
+ * The rules listener on the one walk of the checkout: every `access.md` at
+ * any depth (the access tree is structure-agnostic — the root's included),
+ * plus every plugin manifest under the plugins root, for principal
+ * synthesis. A reader: a folder the walk could not list is simply not in
+ * the model (a writer that needs completeness asks the walk for its holes).
+ *
+ * Per-file failures (malformed YAML, bad role refs, unknown verbs) are
+ * logged and the offending file is dropped from the model — they do NOT
+ * throw. A typo in one nested access.md must not 500 the entire editor;
+ * admins can still write `access.md` / `roles.yaml` because
+ * `hasPermissionResolved` admin-rescues those paths, so the bad config
+ * remains fixable from inside the app.
+ */
+function accessFileListener(repoDir, out, pluginDirs) {
+    return {
+        async onFile(dir, name) {
+            const rel = dir ? `${dir}/${name}` : name;
+            if (name === PLUGIN_MANIFEST_FILE && dir.startsWith(`${PLUGINS_DIR}/`)) {
+                const text = await fs.readFile(path.join(repoDir, rel), 'utf-8').catch(() => null);
+                pluginDirs.set(dir, pluginIdentityOf(parseManifestText(text), path.posix.basename(dir)));
+                return;
+            }
+            if (name !== 'access.md')
+                return;
+            const text = await fs.readFile(path.join(repoDir, rel), 'utf-8');
+            const parsed = parseAccessFile(text, rel);
+            if (!parsed.ok) {
+                // Treat as if the file didn't exist for resolution purposes.
+                // Admin-rescue on access.md paths still lets an admin fix it.
+                for (const e of parsed.errors)
+                    log.warn(`${e} — file ignored`);
+                return;
+            }
+            for (const w of parsed.warnings)
+                log.warn(w);
+            if (out.has(parsed.file.dir)) {
+                log.warn(`${rel}: duplicate access.md for directory '${parsed.file.dir}' — keeping the first one seen`);
+                return;
+            }
+            out.set(parsed.file.dir, parsed.file);
+        },
+    };
+}
+/** A manifest's parsed object, or null for absent, unparsable or not-an-object text. */
+function parseManifestText(text) {
+    if (text === null)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 function resolveScopes(model, verb, relativePath, fileOwn) {
     const target = verb;
+    // Both lists come from the grammar's one dependency graph (`VERB_REQUIRES`):
+    // the verbs whose grant confers the target, and the verbs the target
+    // presupposes, whose denial strips it.
     const supersets = sourceVerbsFor(verb).filter((v) => v !== verb);
+    const prerequisites = requiredVerbsFor(verb).filter((v) => v !== verb);
     // Build one scope's effective verdicts. The target verb contributes both
-    // grants and denials; superset verbs contribute grants only (a `deny write`
-    // never strips `read`). Within the scope a grant always wins over a deny of
-    // the same principal, so a same-file superset grant overrides a target deny
-    // (e.g. `owner:` beats `deny write`, `write:` beats `deny read`).
+    // grants and denials. Superset verbs contribute grants only (a `deny write`
+    // never strips `read`); prerequisite verbs contribute DENIALS only (a `deny
+    // write` strips `owner`, a `deny read` strips all three — nobody owns what
+    // they may not edit, or edits what they may not open), and a `read` grant
+    // confers no `write`. Within the scope a grant always wins over a deny of
+    // the same principal, so a same-file grant of the target or of a superset
+    // overrides a deny of the target or of a prerequisite (`owner:` beats `deny
+    // write`, `write:` beats `deny read`).
     const buildScope = (entries, filterRoles, source) => {
         const byRole = new Map();
         const byEmail = new Map();
+        const implied = { byRole: new Set(), byEmail: new Set() };
         const set = (entry, state) => {
             const map = entry.kind === 'role' ? byRole : byEmail;
             const key = entry.kind === 'role' ? entry.role : entry.email;
@@ -183,8 +217,9 @@ function resolveScopes(model, verb, relativePath, fileOwn) {
                 return; // a grant in this scope sticks
             map.set(key, state);
         };
+        const skip = (entry) => filterRoles && entry.kind === 'role' && !roleKnown(model.roles, entry.role);
         for (const entry of entries[target]) {
-            if (filterRoles && entry.kind === 'role' && !roleKnown(model.roles, entry.role))
+            if (skip(entry))
                 continue;
             set(entry, entry.deny ? 'denied' : 'grant');
         }
@@ -192,12 +227,53 @@ function resolveScopes(model, verb, relativePath, fileOwn) {
             for (const entry of entries[src]) {
                 if (entry.deny)
                     continue; // grant-only fold
-                if (filterRoles && entry.kind === 'role' && !roleKnown(model.roles, entry.role))
+                if (skip(entry))
                     continue;
                 set(entry, 'grant');
             }
         }
-        return { byRole, byEmail, source };
+        // Last, so a target or superset GRANT already in the map stands, and a
+        // target's own `deny` line is never re-labelled as implied.
+        for (const src of prerequisites) {
+            for (const entry of entries[src]) {
+                if (!entry.deny)
+                    continue; // deny-only fold
+                if (skip(entry))
+                    continue;
+                const map = entry.kind === 'role' ? byRole : byEmail;
+                const key = entry.kind === 'role' ? entry.role : entry.email;
+                if (map.has(key))
+                    continue; // an own verdict (grant or deny) is already the answer
+                map.set(key, 'denied');
+                (entry.kind === 'role' ? implied.byRole : implied.byEmail).add(key);
+            }
+        }
+        // The anonymous caller's verdict at this scope — what someone who holds
+        // exactly the PUBLIC keys (a plugin principal whose plugin admits
+        // everyone, so everyone holds it) resolves to, by the same tiers a named
+        // caller gets: a grant via any public key wins, else a denial via one
+        // denies, else the built-in `everyone` entry decides. Derived HERE, where
+        // a scope's verdicts are built, so every reader of it — the permission
+        // check, the eligible lists, the `restricted` flag, the compiler's
+        // everyone audience — sees one truth; and derived into its own field,
+        // never into `byRole`, so the entries a person can remove stay exactly
+        // the lines the files hold.
+        let publicGrant = false;
+        let publicDeny = false;
+        for (const [key, state] of byRole) {
+            if (!model.roles.publicKeys?.has(key))
+                continue;
+            if (state === 'grant')
+                publicGrant = true;
+            else if (state === 'denied')
+                publicDeny = true;
+        }
+        const everyone = publicGrant
+            ? 'grant'
+            : publicDeny
+                ? 'denied'
+                : byRole.get(EVERYONE_CANONICAL);
+        return { byRole, byEmail, everyone, source, implied };
     };
     const scopes = [];
     // The node's own frontmatter is the most specific scope. Role refs there are
@@ -221,17 +297,124 @@ function resolveScopes(model, verb, relativePath, fileOwn) {
 function collapseScopes(scopes) {
     const byRole = new Map();
     const byEmail = new Map();
+    let everyone;
     for (let i = scopes.length - 1; i >= 0; i--) {
         for (const [k, v] of scopes[i].byRole)
             byRole.set(k, v);
         for (const [k, v] of scopes[i].byEmail)
             byEmail.set(k, v);
+        if (scopes[i].everyone !== undefined)
+            everyone = scopes[i].everyone;
     }
-    return { byRole, byEmail };
+    return { byRole, byEmail, everyone };
 }
 function resolveAtPath(model, verb, relativePath, fileOwn) {
     return collapseScopes(resolveScopes(model, verb, relativePath, fileOwn));
 }
+/**
+ * Every principal key a caller holds: the tokens their email is a member of,
+ * plus the PUBLIC keys every caller holds regardless (a plugin principal
+ * whose plugin grants `everyone`). Undefined when there is nothing at all,
+ * matching the plain `byEmail.get` the tier-2 check used to read.
+ */
+function principalKeysOf(model, email) {
+    const own = model.roles.byEmail.get(email);
+    const pub = model.roles.publicKeys;
+    if (!pub?.size)
+        return own;
+    return new Set([...(own ?? []), ...pub]);
+}
+/** The explicit key of the Admin ROLE — never the bare token, which a same-named group may own. */
+const ADMIN_ROLE_KEY = `${ROLE_TOKEN_PREFIX}${ADMIN_CANONICAL}`;
+/**
+ * Add to `keys` what holding them confers on top: every plugin principal
+ * expanded from one of the keys, and the public keys every caller holds.
+ */
+function addDerivedKeys(model, keys) {
+    for (const [key, principal] of model.roles.byCanonical) {
+        if (principal.kind !== 'plugin' || !principal.sourceKeys)
+            continue;
+        for (const source of principal.sourceKeys) {
+            if (keys.has(source)) {
+                keys.add(key);
+                break;
+            }
+        }
+    }
+    for (const key of model.roles.publicKeys ?? [])
+        keys.add(key);
+    return keys;
+}
+/**
+ * Every principal key that being in `group` confers — the group's OWN key,
+ * the roles that list the group (`group:<Name>` in roles.yaml), the plugin
+ * principals whose roster admits the group directly or through one of those
+ * roles, and the public keys every caller holds. This is the group-shaped
+ * twin of `principalKeysOf`: a member's key set minus everything they hold
+ * for reasons of their own. `null` when no group of that name exists.
+ *
+ * Groups are keyed by their bare canonical name (`mergeGroupsIntoRoles`);
+ * roles by `role/<name>`. A bare key whose record is a ROLE is not a group,
+ * however it was spelled.
+ */
+function principalKeysOfGroup(model, group) {
+    const canonical = canonicalRoleName(group);
+    const record = model.roles.byCanonical.get(canonical);
+    if (!record || record.kind !== 'group')
+        return null;
+    const keys = new Set([canonical]);
+    for (const [key, principal] of model.roles.byCanonical) {
+        if (principal.kind === 'role' && principal.groupRefs?.has(canonical))
+            keys.add(key);
+    }
+    // Plugin principals were expanded from role/group entries; a plugin that
+    // admits the group, or a role the group is folded into, admits the group.
+    return addDerivedKeys(model, keys);
+}
+/** The key set of a caller who holds nothing: `hasPermissionForKeys` then answers as `everyone`. */
+const NO_KEYS = new Set();
+/**
+ * The tier-2 half of `hasPermissionResolved` on its own: a verdict for a set
+ * of principal KEYS with no person behind them — no direct-email tier, no
+ * admin rescue, no machine-owned rule — only the Admin write floor, when the
+ * keys include the Admin role. Closest scope first; within a scope a
+ * grant to any key wins over a denial to another, exactly as for a person.
+ */
+function hasPermissionForKeys(model, verb, keys, relativePath, fileOwn) {
+    const adminFloor = verb === 'write' && keys.has(ADMIN_ROLE_KEY);
+    for (const scope of resolveScopes(model, verb, relativePath, fileOwn)) {
+        if (adminFloor && isAdminFloorScope(scope, relativePath))
+            return true;
+        let grant = false;
+        let deny = false;
+        for (const key of keys) {
+            const state = scope.byRole.get(key);
+            if (state === 'denied')
+                deny = true;
+            else if (state === 'grant')
+                grant = true;
+        }
+        if (grant)
+            return true;
+        if (deny)
+            return false;
+        if (scope.everyone)
+            return scope.everyone === 'grant';
+    }
+    return adminFloor;
+}
+/**
+ * Whether a scope sits at the Admin write floor: the repository root's own
+ * `access.md`, or the own frontmatter of a file directly in the root (those
+ * files are part of the root, so their own rules cannot take Admin's write
+ * away either). A folder directly in the root is not covered — its own
+ * `access.md` is an ordinary subfolder scope that may exclude Admin.
+ */
+function isAdminFloorScope(scope, relativePath) {
+    if (scope.source.kind === 'own')
+        return !relativePath.includes('/');
+    return scope.source.path === 'access.md';
+}
 function isAdminEmail(model, email) {
     if (model.deploymentOwners.has(email))
         return true;
@@ -239,7 +422,7 @@ function isAdminEmail(model, email) {
     // Check the explicit `role/admin` alias, NOT the bare token: bare-name
     // precedence is group-first, so a group that happens to be named "Admin"
     // owns the bare key — and its members must never inherit the capability.
-    return !!roles && roles.has(`${ROLE_TOKEN_PREFIX}${ADMIN_CANONICAL}`);
+    return !!roles && roles.has(ADMIN_ROLE_KEY);
 }
 /**
  * Resolve whether `userEmail` has `verb` on `relativePath`.
@@ -272,48 +455,76 @@ function isAdminEmail(model, email) {
  * owner is whoever can already set `ADMIN_EMAIL`, so this concedes no
  * authority they did not have; it only gives it a door.
  *
+ * One floor for `write`, applied during the walk: an admin (same definition)
+ * always holds `write` at the repository root. When the walk reaches the root
+ * `access.md` (or the own frontmatter of a file directly in the root) — or runs
+ * out of scopes without a verdict — an admin is granted,
+ * whatever the root file says, so no root rule can lock the deployment out of
+ * its own tree. A NEARER scope still decides first: a subfolder that denies
+ * Admin (or denies `everyone` without naming Admin) excludes admins there like
+ * anyone else. The root file's own entries are not rewritten — the floor is a
+ * verdict, not a grant line — so `grantSources` stays file-backed.
+ *
  * No special-cases for `read`/`download` — they fall through to scope resolution.
  */
 function hasPermissionResolved(model, verb, userEmail, relativePath, fileOwn) {
+    return decidePermissionResolved(model, verb, userEmail, relativePath, fileOwn).allowed;
+}
+function decidePermissionResolved(model, verb, userEmail, relativePath, fileOwn) {
     const email = canonicalEmail(userEmail);
     if (verb === 'write') {
-        if (relativePath === 'roles.yaml')
-            return isAdminEmail(model, email);
-        if (isAccessMdPath(relativePath) && isAdminEmail(model, email))
-            return true;
+        if (relativePath === 'roles.yaml') {
+            return { allowed: isAdminEmail(model, email), scope: null, via: 'admin-rescue' };
+        }
+        if (isAccessMdPath(relativePath) && isAdminEmail(model, email)) {
+            return { allowed: true, scope: null, via: 'admin-rescue' };
+        }
+    }
+    const adminFloor = verb === 'write' && isAdminEmail(model, email);
+    // For write, the deployment owner IS Admin — the floor admits them, so the
+    // Admin rules along the way bind them too: a subfolder denying Admin excludes
+    // the owner exactly as it excludes the role's members.
+    let userRoles = principalKeysOf(model, email);
+    if (adminFloor && !userRoles?.has(ADMIN_ROLE_KEY)) {
+        userRoles = new Set([...(userRoles ?? []), ...principalKeysOfToken(model, ADMIN_ROLE_KEY)]);
     }
-    const userRoles = model.roles.byEmail.get(email);
     const scopes = resolveScopes(model, verb, relativePath, fileOwn);
     for (const scope of scopes) {
+        if (adminFloor && isAdminFloorScope(scope, relativePath))
+            return { allowed: true, scope, via: 'admin-floor' };
         // Tier 1 — direct email entry is the most specific verdict at this scope.
         const direct = scope.byEmail.get(email);
         if (direct)
-            return direct === 'grant';
+            return { allowed: direct === 'grant', scope, via: 'email', key: email };
         // Tier 2 — the caller's roles. A grant via any one of them wins over a deny
         // via another at this same scope (a `deny Engineer` doesn't undo an
         // unrelated `Admin` grant).
         if (userRoles && userRoles.size) {
-            let grant = false;
-            let deny = false;
+            let granted;
+            let denied;
             for (const r of userRoles) {
                 const s = scope.byRole.get(r);
                 if (s === 'denied')
-                    deny = true;
+                    denied ??= r;
                 else if (s === 'grant')
-                    grant = true;
+                    granted ??= r;
             }
-            if (grant)
-                return true;
-            if (deny)
-                return false;
+            if (granted !== undefined)
+                return { allowed: true, scope, via: 'principal', key: granted };
+            if (denied !== undefined)
+                return { allowed: false, scope, via: 'principal', key: denied };
+        }
+        // Tier 3 — the built-in `everyone` role (derived: a public plugin
+        // principal granted here counts, see `AccessScope.everyone`).
+        if (scope.everyone) {
+            return { allowed: scope.everyone === 'grant', scope, via: 'everyone', key: EVERYONE_CANONICAL };
         }
-        // Tier 3 — the built-in `everyone` role.
-        const everyone = scope.byRole.get(EVERYONE_CANONICAL);
-        if (everyone)
-            return everyone === 'grant';
         // No verdict at this scope — fall through to the next (farther) one.
     }
-    return false;
+    // No verdict anywhere (and no root access.md to stop at): the floor still holds.
+    return adminFloor
+        ? { allowed: true, scope: null, via: 'admin-floor' }
+        : { allowed: false, scope: null, via: 'default-deny' };
 }
 /**
  * The `access.md` that a FOLDER target's own grants live in — its direct scope.
@@ -340,6 +551,39 @@ function scopeToGrantSource(scope, kind, relativePath) {
         return { kind: 'direct' };
     return { kind: 'ancestor', path };
 }
+/**
+ * Where a scope's rules live, as the place a person edits: a folder (the
+ * directory of its `access.md`) or the target's own frontmatter.
+ */
+function decisionSourceOf(scope, kind, relativePath) {
+    if (scope.source.kind === 'own')
+        return { kind: 'frontmatter', path: relativePath, inherited: false };
+    const folder = path.posix.dirname(scope.source.path);
+    const dir = folder === '.' ? '' : folder;
+    const grant = scopeToGrantSource(scope, kind, relativePath);
+    return { kind: 'folder', path: dir, inherited: grant.kind === 'ancestor' };
+}
+/** A resolver decision in the terms `explainAccess` reports. */
+function explainDecision(model, decision, kind, relativePath) {
+    const source = decision.scope ? decisionSourceOf(decision.scope, kind, relativePath) : null;
+    const base = { allowed: decision.allowed, source };
+    switch (decision.via) {
+        case 'admin-rescue':
+        case 'default-deny':
+            return { ...base, via: decision.via, principal: null };
+        case 'admin-floor':
+            return { ...base, via: decision.via, principal: 'Admin' };
+        case 'email':
+            return { ...base, via: 'person', principal: decision.key ?? null };
+        case 'everyone':
+            return { ...base, via: 'everyone', principal: EVERYONE_CANONICAL };
+        case 'principal': {
+            const key = decision.key ?? '';
+            const record = model.roles.byCanonical.get(key);
+            return { ...base, via: record?.kind ?? 'role', principal: record?.displayName ?? key };
+        }
+    }
+}
 /**
  * Resolve EVERY file scope that names a principal for `verb`, ordered
  * closest-first — the source-returning twin of `hasPermissionResolved`, but
@@ -389,13 +633,7 @@ function resolveGrantSourcesForVerb(model, verb, kind, relativePath, principal,
         //     a GROUP whose group has VANISHED reads "unshadowed" here, and the
         //     alias-tolerant pair would then attribute a same-named role's
         //     surviving `role/<name>` grant to the group.
-        const canonical = canonicalRoleName(principal.role);
-        const explicit = canonical.startsWith(ROLE_TOKEN_PREFIX);
-        const bare = explicit ? canonical.slice(ROLE_TOKEN_PREFIX.length) : canonical;
-        const shadowed = model.roles.byCanonical.get(bare)?.kind === 'group';
-        const tokens = tokenMatch === 'exact' || shadowed
-            ? [explicit ? `${ROLE_TOKEN_PREFIX}${bare}` : bare]
-            : [bare, `${ROLE_TOKEN_PREFIX}${bare}`];
+        const tokens = ownTokensOf(model, principal.role, tokenMatch);
         for (const scope of scopes) {
             const states = tokens.map((t) => scope.byRole.get(t));
             if (states.includes('grant')) {
@@ -422,6 +660,69 @@ function resolveGrantSourcesForVerb(model, verb, kind, relativePath, principal,
     }
     return out;
 }
+/**
+ * WHICH token spellings in a file are THIS role-shaped principal's own entries
+ * — the shadowing rule, in one place because the grant walk, the denial walk
+ * and the revoke splice must all agree on it (a disagreement attributes a
+ * shadowed bare token to the wrong principal, which is how a "restrict" silently
+ * strips a same-named role's grant). See `resolveGrantSourcesForVerb` for the
+ * full reasoning behind each branch.
+ */
+function ownTokensOf(model, role, tokenMatch) {
+    const canonical = canonicalRoleName(role);
+    const explicit = canonical.startsWith(ROLE_TOKEN_PREFIX);
+    const bare = explicit ? canonical.slice(ROLE_TOKEN_PREFIX.length) : canonical;
+    const shadowed = model.roles.byCanonical.get(bare)?.kind === 'group';
+    return tokenMatch === 'exact' || shadowed
+        ? [explicit ? `${ROLE_TOKEN_PREFIX}${bare}` : bare]
+        : [bare, `${ROLE_TOKEN_PREFIX}${bare}`];
+}
+/**
+ * The polarity twin of {@link resolveGrantSourcesForVerb}: every file scope
+ * whose own entry for this principal DENIES `verb`, closest-first.
+ *
+ * Same walk, mirrored stopping rule. A grant in the principal's own entry at a
+ * scope ENDS the list — under closest-wins a farther deny is dead, and reporting
+ * it would have the dialog say "restricted" about a verb the principal holds.
+ * A grant or deny reaching the principal through a group/role/`everyone` is not
+ * their own entry: it is neither a denial to report nor a reason to stop, so the
+ * walk carries on past it, exactly as the grant twin does.
+ *
+ * Returns `[]` when the principal is not denied `verb` by any file entry.
+ */
+function resolveDenialSourcesForVerb(model, verb, kind, relativePath, principal, fileOwn, tokenMatch) {
+    const scopes = resolveScopes(model, verb, relativePath, fileOwn);
+    const out = [];
+    if (principal.kind === 'role') {
+        const tokens = ownTokensOf(model, principal.role, tokenMatch);
+        for (const scope of scopes) {
+            const states = tokens.map((t) => scope.byRole.get(t));
+            // A grant under EITHER spelling wins within the scope (`buildScope` lets a
+            // grant stick over a deny of the same principal), so it ends the walk
+            // whether or not the other spelling denies here.
+            if (states.includes('grant'))
+                break;
+            // Only a `deny <verb>` LINE is a source; a denial the scope implies from
+            // a prerequisite verb's line (`deny write` when asking about owner) is
+            // real but is not this verb's entry — the prerequisite's own report is
+            // where it can be lifted.
+            const written = tokens.some((t) => scope.byRole.get(t) === 'denied' && !scope.implied.byRole.has(t));
+            if (written)
+                out.push(scopeToGrantSource(scope, kind, relativePath));
+        }
+        return out;
+    }
+    const email = canonicalEmail(principal.email);
+    for (const scope of scopes) {
+        const own = scope.byEmail.get(email);
+        if (own === 'grant')
+            break;
+        if (own === 'denied' && !scope.implied.byEmail.has(email)) {
+            out.push(scopeToGrantSource(scope, kind, relativePath));
+        }
+    }
+    return out;
+}
 /**
  * Build the repo-root → path chain of directory scopes that govern
  * `relativePath`, e.g. `Knowledge/Sales/Foo.md` →
@@ -454,11 +755,11 @@ function dirChainFor(relativePath) {
  * reported as restricted.
  */
 function canEveryoneReadResolved(model, relativePath, fileOwn) {
-    const { byRole, byEmail } = resolveAtPath(model, 'read', relativePath, fileOwn);
+    const { byEmail, everyone } = resolveAtPath(model, 'read', relativePath, fileOwn);
     // Baseline: an unnamed signed-in user (no email/role entries) reads only via
     // `everyone`. As a single principal, its collapsed verdict is its closest —
     // exactly what that user resolves to.
-    if (byRole.get(EVERYONE_CANONICAL) !== 'grant')
+    if (everyone !== 'grant')
         return false;
     // Every *named* principal must also still read. A collapsed deny may have
     // been shadowed by a closer-scope `everyone` grant, so re-resolve each
@@ -490,8 +791,34 @@ function canEveryoneReadResolved(model, relativePath, fileOwn) {
 function canReadResolved(model, userEmail, relativePath, fileOwn) {
     return hasPermissionResolved(model, 'read', userEmail, relativePath, fileOwn);
 }
+/**
+ * The key set someone holding exactly the principal behind `token` carries —
+ * the question "would a member of this principal be allowed?" put to
+ * `hasPermissionForKeys`. A group gets its full member key set
+ * (`principalKeysOfGroup`); a role or plugin principal gets every key its
+ * record is registered under (the bare name and the `role/` alias share one
+ * record) plus the plugin principals expanded from those keys; a token with no
+ * record (`everyone`, a vanished principal) is just itself. Public keys are
+ * always included — every caller holds them.
+ */
+function principalKeysOfToken(model, token) {
+    const record = model.roles.byCanonical.get(token);
+    if (record?.kind === 'group')
+        return principalKeysOfGroup(model, token) ?? new Set([token]);
+    const keys = new Set([token]);
+    if (!record) {
+        for (const key of model.roles.publicKeys ?? [])
+            keys.add(key);
+        return keys;
+    }
+    for (const [key, principal] of model.roles.byCanonical) {
+        if (principal === record)
+            keys.add(key);
+    }
+    return addDerivedKeys(model, keys);
+}
 function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
-    const { byRole, byEmail } = resolveAtPath(model, verb, relativePath, fileOwn);
+    const { byRole, byEmail, everyone } = resolveAtPath(model, verb, relativePath, fileOwn);
     // (kind, display name) → one entry. The `byRole` keys are the merged
     // index's canonical tokens exactly as granted (bare, or the
     // `role/<canonical>` alias); the `byCanonical` record a key hits carries
@@ -509,12 +836,34 @@ function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
         if (!byIdentity.has(key))
             byIdentity.set(key, { name, kind });
     };
+    // Every row is re-checked against the resolver. The collapsed view keeps a
+    // principal's closest OWN verdict, but a nearer scope can still decide for
+    // them without naming them — a `deny everyone` in a subfolder cuts off a
+    // root `write: Admin` — and a list that named them anyway would tell the
+    // dialog and the denial message that someone is eligible whom the gate then
+    // refuses.
+    const allowedFor = (keys) => hasPermissionForKeys(model, verb, keys, relativePath, fileOwn);
     for (const [canonical, state] of byRole) {
         if (state !== 'grant')
             continue;
+        if (!allowedFor(principalKeysOfToken(model, canonical)))
+            continue;
         const record = model.roles.byCanonical.get(canonical);
         addPrincipal(record ? record.displayName : canonical, record?.kind ?? 'role');
     }
+    // The Admin write floor (see `hasPermissionResolved`): Admin holds write here
+    // whenever no nearer scope excludes it, whether or not any file names it.
+    if (verb === 'write' && model.roles.byCanonical.has(ADMIN_ROLE_KEY)) {
+        const adminRole = model.roles.byCanonical.get(ADMIN_ROLE_KEY);
+        if (allowedFor(principalKeysOfToken(model, ADMIN_ROLE_KEY)))
+            addPrincipal(adminRole.displayName, 'role');
+    }
+    // The derived everyone verdict: a public plugin principal granted here
+    // means anyone signed in holds the verb, and a list that counts holders (an
+    // approval gate, a "restricted to" banner) must say so — as `everyone`, the
+    // same row a literal grant produces.
+    if (everyone === 'grant' && allowedFor(NO_KEYS))
+        addPrincipal(EVERYONE_CANONICAL, 'role');
     // Mirror the admin overrides applied in `hasPermissionResolved`: write on
     // `roles.yaml` and on any `access.md` is granted to Admin even if the
     // file content doesn't list it. Without surfacing that here, the
@@ -525,7 +874,7 @@ function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
         // Look the Admin ROLE up via its explicit alias — the bare key may be
         // owned by a same-named group under group-first precedence. The override
         // is the ROLE's capability, so the row's kind is 'role' regardless.
-        const adminRole = model.roles.byCanonical.get(`${ROLE_TOKEN_PREFIX}${ADMIN_CANONICAL}`);
+        const adminRole = model.roles.byCanonical.get(ADMIN_ROLE_KEY);
         addPrincipal(adminRole ? adminRole.displayName : ADMIN_CANONICAL, 'role');
     }
     const principals = [...byIdentity.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0);
@@ -537,11 +886,26 @@ function eligibleHoldersResolved(model, verb, relativePath, fileOwn) {
     for (const [email, state] of byEmail) {
         if (state !== 'grant')
             continue;
+        if (!hasPermissionResolved(model, verb, email, relativePath, fileOwn))
+            continue;
         users.push({ name: '', email });
     }
     users.sort((a, b) => a.email.localeCompare(b.email));
     return { principals, roles, users };
 }
+/**
+ * Every individual the model names: `roles.yaml` members, emails named inline
+ * at this path's scope, and the deployment owner (Admin for the write floor
+ * even when `roles.yaml` does not list them).
+ */
+function namedCandidateEmails(model, byEmail) {
+    const candidates = new Set(model.deploymentOwners);
+    for (const email of model.roles.byEmail.keys())
+        candidates.add(email);
+    for (const email of byEmail.keys())
+        candidates.add(email);
+    return candidates;
+}
 /**
  * Expand the eligible-writer set to the underlying emails.
  *
@@ -561,12 +925,10 @@ function eligibleHolderEmailsResolved(model, verb, relativePath, fileOwn) {
     // in an access.md entry at this path's scope (whether granted or denied —
     // `hasPermissionResolved` filters denials out below). The built-in
     // `everyone` role can grant arbitrary signed-in users, but this finite
-    // expansion can only return emails the access tree explicitly names.
-    const candidates = new Set();
-    for (const email of model.roles.byEmail.keys())
-        candidates.add(email);
-    for (const email of byEmail.keys())
-        candidates.add(email);
+    // expansion can only return emails the access tree explicitly names. The
+    // deployment owner is a candidate too: the Admin write floor admits them
+    // whether or not `roles.yaml` lists them.
+    const candidates = namedCandidateEmails(model, byEmail);
     for (const email of candidates) {
         if (hasPermissionResolved(model, verb, email, relativePath, fileOwn)) {
             out.set(email, { name: '', email });
@@ -586,11 +948,7 @@ function eligibleHolderEmailsResolved(model, verb, relativePath, fileOwn) {
  */
 function ineligibleNamedEmailsResolved(model, verb, relativePath, fileOwn) {
     const { byEmail } = resolveAtPath(model, verb, relativePath, fileOwn);
-    const candidates = new Set();
-    for (const email of model.roles.byEmail.keys())
-        candidates.add(email);
-    for (const email of byEmail.keys())
-        candidates.add(email);
+    const candidates = namedCandidateEmails(model, byEmail);
     const out = new Set();
     for (const email of candidates) {
         if (!hasPermissionResolved(model, verb, email, relativePath, fileOwn))
@@ -601,6 +959,8 @@ function ineligibleNamedEmailsResolved(model, verb, relativePath, fileOwn) {
 export class AccessControlService {
     workspaceService;
     kbDirName;
+    disk;
+    gitRunner;
     /**
      * Per-workspace cache: `model` is the resolved access tree and `loadedAt`
      * is when we computed it. We re-load on a TTL — the validator runs on
@@ -653,16 +1013,25 @@ export class AccessControlService {
      * environment, not from the knowledge base.
      */
     deploymentOwners;
-    constructor(workspaceService, kbDirName, 
+    constructor(workspaceService, kbDirName, disk, 
     /**
      * Emails that count as Admin for the two hardcoded `write` rescues,
      * whatever `roles.yaml` says — in practice `ADMIN_EMAIL`. Optional so the
      * many test fixtures that construct this service directly keep their
      * current behaviour (no owner, roles.yaml is the only authority).
      */
-    deploymentOwners = []) {
+    deploymentOwners = [], 
+    /**
+     * How git is run — see `shared/git.contract.ts`. The composition root
+     * passes the one runner; the default is the same runner on its default
+     * deadline, kept for the same reason as `deploymentOwners` above: a great
+     * many fixtures construct this service directly.
+     */
+    gitRunner = new NodeGitRunner()) {
         this.workspaceService = workspaceService;
         this.kbDirName = kbDirName;
+        this.disk = disk;
+        this.gitRunner = gitRunner;
         this.deploymentOwners = new Set(deploymentOwners.filter(Boolean).map((e) => canonicalEmail(e)));
     }
     /**
@@ -674,7 +1043,29 @@ export class AccessControlService {
     invalidate(workspaceId) {
         this.cache.delete(workspaceId);
         this.ownEntriesCache.delete(workspaceId);
+        this.generation++;
     }
+    /**
+     * Bumped by every `invalidate()`, for any workspace. A model load reads the
+     * tree across many awaits, and an invalidation fires exactly when that tree
+     * changes underneath it: the load that started on the old tree would
+     * otherwise store its model AFTER the drop, and every read for the next TTL
+     * would resolve against a tree that is already gone. `loadModel` takes the
+     * generation before its first read and refuses to store a model fetched
+     * under an older one — the caller that started it still gets its answer,
+     * as old as the moment it started, and the next caller reloads.
+     *
+     * ONE counter, not one per workspace: a per-workspace map would keep an
+     * entry for every branch workspace the process ever loaded, with nothing to
+     * tell it when a workspace is gone. The price of sharing is that a drop on
+     * some other workspace, landing mid-load, costs this one a single reload —
+     * a load is tens of milliseconds and a drop is a commit, so that is rare
+     * and cheap, and it never stores a wrong model. (The own-entries memo needs
+     * no token: it is keyed by the map object a reader took BEFORE its disk
+     * read, and `invalidate()` replaces the map, so a late store lands in an
+     * orphan nobody consults.)
+     */
+    generation = 0;
     /** Memoized `readOwnEntries` for the batch paths; see `ownEntriesCache`. */
     async cachedOwnEntries(workspaceId, repoDir, relativePath) {
         let ws = this.ownEntriesCache.get(workspaceId);
@@ -727,6 +1118,35 @@ export class AccessControlService {
         });
         return result;
     }
+    async canReadAsGroupBatch(workspaceId, group, relativePaths) {
+        const model = await this.loadModel(workspaceId);
+        const keys = principalKeysOfGroup(model, group);
+        if (keys === null)
+            return null;
+        const repoDir = await this.repoDir(workspaceId);
+        // The same per-path own-entries `canReadBatch` folds in: a file's own
+        // frontmatter rules are part of the walk for a group as for a person.
+        const owns = await Promise.all(relativePaths.map((p) => this.cachedOwnEntries(workspaceId, repoDir, p)));
+        const result = new Map();
+        relativePaths.forEach((p, i) => {
+            result.set(p, hasPermissionForKeys(model, 'read', keys, p, owns[i]));
+        });
+        return result;
+    }
+    async canReadAsEveryoneBatch(workspaceId, relativePaths) {
+        const model = await this.loadModel(workspaceId);
+        const repoDir = await this.repoDir(workspaceId);
+        const owns = await Promise.all(relativePaths.map((p) => this.cachedOwnEntries(workspaceId, repoDir, p)));
+        const result = new Map();
+        relativePaths.forEach((p, i) => {
+            // No keys at all: the walk then falls through to each scope's derived
+            // `everyone` verdict — the built-in entry, or a public plugin's grant
+            // or denial, whichever the scope builder settled on — which is exactly
+            // what a caller holding nothing of their own resolves to.
+            result.set(p, hasPermissionForKeys(model, 'read', NO_KEYS, p, owns[i]));
+        });
+        return result;
+    }
     async canWriteBatch(workspaceId, userEmail, relativePaths) {
         const model = await this.loadModel(workspaceId);
         const repoDir = await this.repoDir(workspaceId);
@@ -773,20 +1193,71 @@ export class AccessControlService {
     async eligibleReaders(workspaceId, relativePath) {
         const model = await this.loadModel(workspaceId);
         const own = await this.readOwnEntries(await this.repoDir(workspaceId), relativePath);
-        // When `read: everyone` applies cleanly, the node is readable by all users
-        // and the role/user lists are meaningless. Otherwise return the explicit
-        // reader set; it may be empty for a default-denied path with no grants.
-        if (canEveryoneReadResolved(model, relativePath, own)) {
-            return { restricted: false, principals: [], roles: [], users: [] };
-        }
+        // `restricted` is the verdict — whether `read: everyone` applies cleanly —
+        // and the lists are the GRANTS that exist regardless: on a public node
+        // they name what makes it public (`everyone`, and a public plugin
+        // principal whose grant is the one to remove), so the share dialog can
+        // show that grant as a row. Consumers that only want to know whether the
+        // node is public read the flag; the lists may be empty for a
+        // default-denied path with no grants.
         const { principals, roles, users } = eligibleHoldersResolved(model, 'read', relativePath, own);
-        return { restricted: true, principals, roles, users };
+        // WHY it is public, when it is: the public plugin principals granted read
+        // here — the one thing the dialog cannot tell from the lists alone (a
+        // plugin principal in them may or may not be public), so the resolver,
+        // which knows, says it. A literal `everyone` line shows up as a source
+        // of the `everyone` row instead; together the two answer "what remains
+        // public after this grant is removed".
+        const collapsed = resolveAtPath(model, 'read', relativePath, own);
+        const publicVia = [...collapsed.byRole]
+            .filter(([key, state]) => state === 'grant' && model.roles.publicKeys?.has(key))
+            .map(([key]) => key)
+            .sort();
+        return { restricted: !canEveryoneReadResolved(model, relativePath, own), principals, roles, users, publicVia };
     }
     async eligibleDownloaders(workspaceId, relativePath) {
         const model = await this.loadModel(workspaceId);
         const own = await this.readOwnEntries(await this.repoDir(workspaceId), relativePath);
         return eligibleHoldersResolved(model, 'download', relativePath, own);
     }
+    /**
+     * The read and write holders of one file at its current path and at a path
+     * it has not moved to yet (see the interface).
+     *
+     * A move changes nothing about the file's own frontmatter — that travels
+     * with the bytes — and everything about the folder chain above it. So the
+     * hypothetical side is the ordinary resolution with the destination path
+     * substituted: the same model, the same own-entries (read from the SOURCE,
+     * since nothing sits at the destination to read), resolved against the
+     * destination's ancestors. One model load and one file read serve all four
+     * lookups.
+     */
+    async prospectiveHolders(workspaceId, fromPath, toPath) {
+        const model = await this.loadModel(workspaceId);
+        const repoDir = await this.repoDir(workspaceId);
+        // A FILE question only. A folder carries its own `access.md` — which moves
+        // with it and governs everything under it — so resolving it as a file
+        // would read frontmatter it does not have and omit the rules it does,
+        // naming principals that are not the ones a folder move changes. Refuse
+        // rather than answer the wrong question convincingly.
+        //
+        // Only absence is an answer here (see `isAbsence`): a probe that failed on
+        // permissions or I/O does not say "this is a file", and folding it into
+        // one would let the very case above through on an unreadable source.
+        const fromStat = await fs.stat(path.join(repoDir, fromPath)).catch((err) => {
+            if (isAbsence(err))
+                return null;
+            throw err;
+        });
+        if (fromStat?.isDirectory()) {
+            throw new WorkflowDomainError('prospective access answers for a file, not a folder', 400);
+        }
+        const own = await this.readOwnEntries(repoDir, fromPath);
+        const holdersAt = (relativePath) => ({
+            read: eligibleHoldersResolved(model, 'read', relativePath, own),
+            write: eligibleHoldersResolved(model, 'write', relativePath, own),
+        });
+        return { before: holdersAt(fromPath), after: holdersAt(toPath) };
+    }
     async eligibleWriterEmails(workspaceId, relativePath) {
         const model = await this.loadModel(workspaceId);
         const own = await this.readOwnEntries(await this.repoDir(workspaceId), relativePath);
@@ -813,13 +1284,92 @@ export class AccessControlService {
         }
         return out;
     }
+    async denialSources(workspaceId, kind, relativePath, principal, opts) {
+        const model = await this.loadModel(workspaceId);
+        // Same own-scope rule as `grantSources`: a file target consults its own
+        // frontmatter, a folder target's own access.md is already in the dir chain.
+        const own = kind === 'file'
+            ? await this.readOwnEntries(await this.repoDir(workspaceId), relativePath)
+            : null;
+        const out = {};
+        for (const verb of KNOWN_VERBS) {
+            const sources = resolveDenialSourcesForVerb(model, verb, kind, relativePath, principal, own, opts?.tokenMatch);
+            if (sources.length > 0)
+                out[verb] = sources;
+        }
+        return out;
+    }
+    async locallyDeniedPrincipals(workspaceId, kind, relativePath) {
+        const model = await this.loadModel(workspaceId);
+        // The target's OWN entries, and only those — the one scope whose rules a
+        // restriction made here is written into. A folder's are its `access.md` in
+        // the dir model; a file node's are its own frontmatter.
+        const own = kind === 'folder'
+            ? (model.accessFilesByDir.get(relativePath)?.entries ?? null)
+            : await this.readOwnEntries(await this.repoDir(workspaceId), relativePath);
+        if (!own)
+            return { principals: [], users: [] };
+        const byIdentity = new Map();
+        const byEmail = new Map();
+        for (const verb of KNOWN_VERBS) {
+            for (const entry of own[verb] ?? []) {
+                // Grants are already reported by the eligible lists; only the denials
+                // are invisible there, and only they are this method's business.
+                if (!entry.deny)
+                    continue;
+                if (entry.kind === 'user') {
+                    if (!byEmail.has(entry.email)) {
+                        byEmail.set(entry.email, { name: entry.displayName, email: entry.email });
+                    }
+                    continue;
+                }
+                // A token naming a role nobody knows is not a rule: `loadModel` drops
+                // such entries from every `access.md`, and `resolveScopes` filters them
+                // out of a file's own frontmatter (the one scope it does not pre-filter)
+                // — so the resolver denies nothing, `denialSources` reports nothing, and
+                // a row here would claim a restriction the server does not enforce. Skip
+                // it on the same rule, so this list and the denial sources agree.
+                if (!roleKnown(model.roles, entry.role))
+                    continue;
+                // Resolve the token's kind and display name through the SAME merged
+                // index the eligible lists use, so a denied group keys as `g:` and a
+                // denied role as `r:` — matching the row keys the view is built on. A
+                // KNOWN token with no record is a built-in (`everyone`, `admin` before
+                // roles.yaml names it), which displays as the role it is.
+                const record = model.roles.byCanonical.get(entry.role);
+                const name = record ? record.displayName : (entry.displayRole || entry.role);
+                const kindOf = record?.kind ?? 'role';
+                const key = `${kindOf}\0${name.toLowerCase()}`;
+                if (!byIdentity.has(key))
+                    byIdentity.set(key, { name, kind: kindOf });
+            }
+        }
+        const principals = [...byIdentity.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0);
+        const users = [...byEmail.values()].sort((a, b) => a.email.localeCompare(b.email));
+        return { principals, users };
+    }
+    async explainAccess(workspaceId, userEmail, kind, relativePath) {
+        const model = await this.loadModel(workspaceId);
+        // The same own-entries read `canRead`/`canWrite`/… make, whatever the
+        // kind: a directory simply has none.
+        const own = await this.readOwnEntries(await this.repoDir(workspaceId), relativePath);
+        const out = {};
+        for (const verb of KNOWN_VERBS) {
+            const machineOwned = verb === 'write' ? this.machineOwnedWriteRule(userEmail, relativePath) : null;
+            out[verb] =
+                machineOwned !== null
+                    ? { allowed: machineOwned, source: null, via: 'machine-owned', principal: null }
+                    : explainDecision(model, decidePermissionResolved(model, verb, userEmail, relativePath, own), kind, relativePath);
+        }
+        return out;
+    }
     async kbPrincipals(workspaceId) {
         let model;
         try {
             model = await this.loadModel(workspaceId);
         }
         catch {
-            return { roles: [], groups: [], people: [] };
+            return { roles: [], groups: [], plugins: [], people: [] };
         }
         // Roles = the built-in `everyone` role plus every declared role's display
         // name — ROLE principals only, never groups. Each role is enumerated via
@@ -831,11 +1381,22 @@ export class AccessControlService {
         // direct-access.md edit).
         const roles = [EVERYONE_DISPLAY];
         const groups = [];
+        // Plugins = the identities behind the synthesised `plugin/<name>/<verb>`
+        // principals, once each (three keys share a folder). Personal shelves are
+        // plugins to the resolver but not to a person picking a grantee — told
+        // apart by their FOLDER (the one structural rule), never by their name.
+        const plugins = new Map();
         for (const [key, principal] of model.roles.byCanonical) {
             if (key.startsWith(ROLE_TOKEN_PREFIX))
                 roles.push(principal.displayName);
             else if (principal.kind === 'group')
                 groups.push(principal.displayName);
+            else if (principal.kind === 'plugin' &&
+                principal.pluginName &&
+                principal.pluginDir &&
+                !isPersonalPluginDir(principal.pluginDir)) {
+                plugins.set(principal.pluginName, principal.pluginDir);
+            }
         }
         // People = roles.yaml member emails (name-less) ∪ access.md `Name <email>`
         // grants (named). The login-only users table is unioned in by the caller.
@@ -857,7 +1418,14 @@ export class AccessControlService {
             name: name || email.split('@')[0],
             email,
         }));
-        return { roles, groups, people };
+        return {
+            roles,
+            groups,
+            plugins: [...plugins.entries()]
+                .map(([name, folder]) => ({ name, folder }))
+                .sort((a, b) => a.name.localeCompare(b.name)),
+            people,
+        };
     }
     async findEmailByHash(workspaceId, hash) {
         let model;
@@ -887,7 +1455,7 @@ export class AccessControlService {
             ...namesByEmail.keys(),
         ]);
         for (const email of candidates) {
-            if (sha256Email(email) === hash) {
+            if (hashEmail(email) === hash) {
                 const displayName = namesByEmail.get(email) ?? email.split('@')[0];
                 return { email, displayName };
             }
@@ -906,7 +1474,7 @@ export class AccessControlService {
     machineOwnedWriteRule(userEmail, relativePath) {
         if (relativePath !== SYNCED_GROUPS_YAML)
             return null;
-        return userEmail.trim().toLowerCase() === DIRECTORY_SYNC_BOT_EMAIL;
+        return canonicalEmail(userEmail) === DIRECTORY_SYNC_BOT_EMAIL;
     }
     async canWriteAtRef(workspaceId, ref, userEmail, relativePath) {
         const machineOwned = this.machineOwnedWriteRule(userEmail, relativePath);
@@ -967,6 +1535,50 @@ export class AccessControlService {
         const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
         return eligibleHoldersResolved(loaded.model, 'write', relativePath, own);
     }
+    async holdsAdminRootWrite(workspaceId, userEmail) {
+        const model = await this.loadModel(workspaceId);
+        return isAdminEmail(model, canonicalEmail(userEmail));
+    }
+    async canRestorePlatformFile(workspaceId, userEmail, destinationRelativePath) {
+        const target = platformRestoreDestination(destinationRelativePath);
+        if (target === null)
+            return false;
+        const email = canonicalEmail(userEmail);
+        let admin;
+        try {
+            admin = isAdminEmail(await this.loadModel(workspaceId), email);
+        }
+        catch {
+            // The repository this rescue exists for is exactly the one whose
+            // `roles.yaml` may be the file that went missing, and `loadModel`
+            // throws when it cannot be read. With no model to ask, the deployment
+            // owner is the only admin left — and they are the person who sets
+            // `ADMIN_EMAIL`, so admitting them concedes nothing they did not have.
+            admin = this.deploymentOwners.has(email);
+        }
+        if (!admin)
+            return false;
+        // A restore puts back what is MISSING, so the place it lands must be
+        // empty. An `access.md` goes back only into a folder that has none —
+        // into a folder that already has one it would not be a restore but a rule
+        // change wearing a move's clothes, and the destination's own rules would
+        // be the thing it bypassed the write gate to overwrite. The same holds at
+        // the root: a move is a rename on disk, so landing `.bevelignore` on a
+        // root that already has one would silently replace it, and the repository
+        // was never missing that file to begin with.
+        const destination = target.kind === 'root' ? target.name : path.join(target.dir, 'access.md');
+        const repoDir = await this.repoDir(workspaceId);
+        try {
+            await fs.stat(path.join(repoDir, destination));
+            return false;
+        }
+        catch (err) {
+            if (isAbsence(err))
+                return true;
+            // Anything other than genuine absence is not an answer: fail closed.
+            return false;
+        }
+    }
     async eligibleWritersForPathsAtRef(workspaceId, ref, relativePaths) {
         const result = new Map();
         // Machine-owned paths resolve without the model — same answer
@@ -1012,6 +1624,8 @@ export class AccessControlService {
         if (cached && Date.now() - cached.loadedAt < AccessControlService.CACHE_TTL_MS) {
             return cached.model;
         }
+        // Taken before the first read; see `generation`.
+        const generation = this.generation;
         const repoDir = await this.repoDir(workspaceId);
         let rolesYaml;
         try {
@@ -1035,20 +1649,19 @@ export class AccessControlService {
                 return await fs.readFile(path.join(repoDir, filename), 'utf-8');
             }
             catch (err) {
-                const code = err?.code;
-                if (code === 'ENOENT' || code === 'ENOTDIR')
+                if (isAbsence(err))
                     return null;
                 throw err;
             }
         });
         if (!activeGroups.health.ok) {
-            console.error(`[access] groups source ${activeGroups.health.file} is broken (${activeGroups.health.reason}) — groups contribute nothing until it is fixed`);
+            log.error(`groups source ${activeGroups.health.file} is broken (${activeGroups.health.reason}) — groups contribute nothing until it is fixed`);
         }
         for (const w of activeGroups.warnings)
-            console.warn(`[access] ${w}`);
+            log.warn(w);
         const mergeWarnings = mergeGroupsIntoRoles(rolesParsed.index, activeGroups.groups, activeGroups.sourceFile);
         for (const w of mergeWarnings)
-            console.warn(`[access] ${w}`);
+            log.warn(w);
         const accessFiles = new Map();
         // Walk the entire repo for `access.md` files. The access tree is
         // structure-agnostic — any `access.md` at any depth (including repo
@@ -1063,7 +1676,14 @@ export class AccessControlService {
         // must not 500 the entire editor; admins can still write `access.md`
         // / `roles.yaml` because `hasPermissionResolved` admin-rescues those
         // paths, so the bad config remains fixable from inside the app.
-        await this.collectAccessFiles(repoDir, '', accessFiles);
+        const pluginDirs = new Map();
+        await this.disk.walkKb(repoDir, [accessFileListener(repoDir, accessFiles, pluginDirs)]);
+        // Plugin principals (`plugin/<Name>/<verb>`), derived from each plugin
+        // folder's own access.md — a plugin being a folder with a manifest, at
+        // any depth — after groups merged (so their rosters expand through the
+        // finished index) and before the unknown-role sweep below (so a grant
+        // naming one counts as known).
+        synthesizePluginPrincipals(rolesParsed.index, accessFiles, pluginDirs);
         // Validate role refs against roles.yaml. `everyone` is a built-in role and
         // is valid without a roles.yaml entry. Unknown refs are dropped from the
         // parsed entry list (along with a warn log) so the rest of the file still
@@ -1072,7 +1692,7 @@ export class AccessControlService {
             for (const verb of KNOWN_VERBS) {
                 file.entries[verb] = file.entries[verb].filter((entry) => {
                     if (entry.kind === 'role' && !roleKnown(rolesParsed.index, entry.role)) {
-                        console.warn(`[access] ${file.path}: '${verb}' references unknown role '${entry.displayRole}' — entry ignored`);
+                        log.warn(`${file.path}: '${verb}' references unknown role '${entry.displayRole}' — entry ignored`);
                         return false;
                     }
                     return true;
@@ -1085,49 +1705,12 @@ export class AccessControlService {
             groupsHealth: activeGroups.health,
             deploymentOwners: this.deploymentOwners,
         };
-        this.cache.set(workspaceId, { model, loadedAt: Date.now() });
-        return model;
-    }
-    async collectAccessFiles(absDir, relDir, out) {
-        let entries;
-        try {
-            entries = await fs.readdir(absDir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const entry of entries) {
-            // Skip VCS metadata + vendored deps. Hidden dirs (`.git`, `.vscode`,
-            // etc.) and `node_modules` can't host KB rules and are often huge —
-            // walking them would slow every cache miss without benefit.
-            if (entry.name.startsWith('.'))
-                continue;
-            if (entry.name === 'node_modules')
-                continue;
-            const abs = path.join(absDir, entry.name);
-            const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
-            if (entry.isDirectory()) {
-                await this.collectAccessFiles(abs, rel, out);
-            }
-            else if (entry.isFile() && entry.name === 'access.md') {
-                const text = await fs.readFile(abs, 'utf-8');
-                const parsed = parseAccessFile(text, rel);
-                if (!parsed.ok) {
-                    // Treat as if the file didn't exist for resolution purposes.
-                    // Admin-rescue on access.md paths still lets an admin fix it.
-                    for (const e of parsed.errors)
-                        console.warn(`[access] ${e} — file ignored`);
-                    continue;
-                }
-                for (const w of parsed.warnings)
-                    console.warn(`[access] ${w}`);
-                if (out.has(parsed.file.dir)) {
-                    console.warn(`[access] ${rel}: duplicate access.md for directory '${parsed.file.dir}' — keeping the first one seen`);
-                    continue;
-                }
-                out.set(parsed.file.dir, parsed.file);
-            }
+        // An invalidation landed mid-load: this model describes a tree that is
+        // already gone, so it is returned to this caller but never stored.
+        if (this.generation === generation) {
+            this.cache.set(workspaceId, { model, loadedAt: Date.now() });
         }
+        return model;
     }
     async repoDir(workspaceId) {
         const wsDir = await this.workspaceService.getWorkspacePath(workspaceId);
@@ -1190,7 +1773,7 @@ export class AccessControlService {
         }
         if (wanted.length === 0)
             return result;
-        const texts = await catFileBatch(repoDir, wanted.map((p) => `${ref}:${p}`));
+        const texts = await catFileBatch(this.gitRunner, repoDir, wanted.map((p) => `${ref}:${p}`));
         wanted.forEach((p, i) => {
             const text = texts[i];
             if (text === null)
@@ -1230,11 +1813,7 @@ export class AccessControlService {
      */
     async showAtRefOutcome(repoDir, ref, relativePath) {
         try {
-            const { stdout } = await execFileAsync('git', ['-C', repoDir, 'show', `${ref}:${relativePath}`], {
-                encoding: 'utf-8',
-                maxBuffer: 16 * 1024 * 1024,
-                env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
-            });
+            const { stdout } = await this.gitRunner.run(repoDir, ['show', `${ref}:${relativePath}`]);
             return { kind: 'text', text: stdout };
         }
         catch (err) {
@@ -1253,16 +1832,20 @@ export class AccessControlService {
      */
     async listAccessFilesAtRef(repoDir, ref) {
         try {
-            const { stdout } = await execFileAsync('git', ['-C', repoDir, 'ls-tree', '-r', '--name-only', ref], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+            const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '--name-only', ref]);
             const out = [];
+            const pluginDirs = [];
             for (const line of stdout.split('\n')) {
                 const p = line.trim();
                 if (!p)
                     continue;
                 if (p === 'access.md' || p.endsWith('/access.md'))
                     out.push(p);
+                else if (p.startsWith(`${PLUGINS_DIR}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
+                    pluginDirs.push(p.slice(0, -(PLUGIN_MANIFEST_FILE.length + 1)));
+                }
             }
-            return out;
+            return { accessFiles: out, pluginDirs };
         }
         catch {
             return 'error';
@@ -1338,11 +1921,21 @@ export class AccessControlService {
         if (!ref || ref.startsWith('-'))
             return null;
         try {
-            const { stdout } = await execFileAsync('git', ['-C', repoDir, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { encoding: 'utf-8' });
+            const { stdout } = await this.gitRunner.run(repoDir, [
+                'rev-parse',
+                '--verify',
+                '--quiet',
+                `${ref}^{commit}`,
+            ]);
             const sha = stdout.trim();
             return /^[0-9a-f]{40,64}$/.test(sha) ? sha : null;
         }
-        catch {
+        catch (err) {
+            // Null means "does not resolve". A deadline says nothing about the ref,
+            // and as a null it would turn a stalled git into a gate that quietly
+            // reads no roles at that ref; it surfaces instead, as a read failure.
+            if (isGitTimeout(err))
+                throw err;
             return null;
         }
     }
@@ -1374,7 +1967,7 @@ export class AccessControlService {
             if (outcome.kind === 'error') {
                 // The operational signal: one line per failed read, naming the commit
                 // and the path, so a run of these is visible in the logs.
-                console.warn(`[access@${tag}] git read of ${relativePath} failed; refusing to decide from a partial tree`);
+                logger(`access@${tag}`).warn(`git read of ${relativePath} failed; refusing to decide from a partial tree`);
                 throw new AccessUnreadableError(label, relativePath);
             }
             return outcome.kind === 'text' ? outcome.text : null;
@@ -1394,20 +1987,20 @@ export class AccessControlService {
         // fires only on a file that was read and would not parse.
         const activeGroups = await loadActiveGroups(read);
         if (!activeGroups.health.ok) {
-            console.error(`[access@${tag}] groups source ${activeGroups.health.file} is broken (${activeGroups.health.reason}) — groups contribute nothing until it is fixed`);
+            logger(`access@${tag}`).error(`groups source ${activeGroups.health.file} is broken (${activeGroups.health.reason}) — groups contribute nothing until it is fixed`);
         }
         for (const w of activeGroups.warnings)
-            console.warn(`[access@${tag}] ${w}`);
+            logger(`access@${tag}`).warn(w);
         const mergeWarnings = mergeGroupsIntoRoles(rolesParsed.index, activeGroups.groups, activeGroups.sourceFile);
         for (const w of mergeWarnings)
-            console.warn(`[access@${tag}] ${w}`);
+            logger(`access@${tag}`).warn(w);
         const accessFiles = new Map();
         const listed = await this.listAccessFilesAtRef(repoDir, commit);
         if (listed === 'error') {
-            console.warn(`[access@${tag}] listing access.md files failed; refusing to decide from a partial tree`);
+            logger(`access@${tag}`).warn('listing access.md files failed; refusing to decide from a partial tree');
             throw new AccessUnreadableError(label, 'access.md (ls-tree)');
         }
-        for (const p of listed) {
+        for (const p of listed.accessFiles) {
             const text = await read(p);
             if (text === null)
                 continue;
@@ -1419,6 +2012,16 @@ export class AccessControlService {
             // duplicates, but be defensive.
             accessFiles.set(parsed.file.dir, parsed.file);
         }
+        // Mirror `loadModel`: plugin principals from the plugins the ref carries,
+        // each under the identity its manifest AT THAT REF declares, so a PR-time
+        // verdict on a skill granted to `plugin/<name>/write` counts the plugin's
+        // writers exactly as the working tree would.
+        const pluginIdentities = new Map();
+        for (const dir of listed.pluginDirs) {
+            const manifest = parseManifestText(await read(`${dir}/${PLUGIN_MANIFEST_FILE}`));
+            pluginIdentities.set(dir, pluginIdentityOf(manifest, path.posix.basename(dir)));
+        }
+        synthesizePluginPrincipals(rolesParsed.index, accessFiles, pluginIdentities);
         // Mirror `loadModel`: drop entries whose role ref is unknown to roles.yaml,
         // while preserving the built-in `everyone` role.
         for (const [, file] of accessFiles) {