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

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

@@ -1,17 +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 { isAbsence } from '../../shared/fs-errors.js';
-import { walkKb } from '../../shared/kb-walk.js';
-import { PLUGINS_DIR, PLUGIN_MANIFEST_FILE, isPersonalPluginDir, pluginIdentityOf, } from '@bevel-software/platform-shared';
+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
@@ -20,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;
@@ -89,13 +65,13 @@ function roleKnown(roles, canonicalRole) {
  * 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) => ({
@@ -118,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 (isAbsence(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;
@@ -140,10 +111,7 @@ export async function loadActiveGroups(read) {
         catch (err) {
             if (err instanceof AccessUnreadableError)
                 throw err; // see above
-            if (isAbsence(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)
@@ -195,13 +163,13 @@ function accessFileListener(repoDir, out, pluginDirs) {
                 // 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`);
+                    log.warn(`${e} — file ignored`);
                 return;
             }
             for (const w of parsed.warnings)
-                console.warn(`[access] ${w}`);
+                log.warn(w);
             if (out.has(parsed.file.dir)) {
-                console.warn(`[access] ${rel}: duplicate access.md for directory '${parsed.file.dir}' — keeping the first one seen`);
+                log.warn(`${rel}: duplicate access.md for directory '${parsed.file.dir}' — keeping the first one seen`);
                 return;
             }
             out.set(parsed.file.dir, parsed.file);
@@ -224,15 +192,24 @@ function parseManifestText(text) {
 }
 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;
@@ -240,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');
         }
@@ -249,11 +227,27 @@ 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');
             }
         }
+        // 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
@@ -279,7 +273,7 @@ function resolveScopes(model, verb, relativePath, fileOwn) {
             : publicDeny
                 ? 'denied'
                 : byRole.get(EVERYONE_CANONICAL);
-        return { byRole, byEmail, everyone, source };
+        return { byRole, byEmail, everyone, source, implied };
     };
     const scopes = [];
     // The node's own frontmatter is the most specific scope. Role refs there are
@@ -330,6 +324,97 @@ function principalKeysOf(model, email) {
         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;
@@ -337,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`.
@@ -370,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 = principalKeysOf(model, 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 scope.everyone === 'grant';
+        if (scope.everyone) {
+            return { allowed: scope.everyone === 'grant', scope, via: 'everyone', key: EVERYONE_CANONICAL };
+        }
         // 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.
@@ -438,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
@@ -487,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')) {
@@ -520,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` →
@@ -588,6 +791,32 @@ 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, everyone } = resolveAtPath(model, verb, relativePath, fileOwn);
     // (kind, display name) → one entry. The `byRole` keys are the merged
@@ -607,17 +836,33 @@ 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')
+    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
@@ -629,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);
@@ -641,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.
  *
@@ -665,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 });
@@ -690,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))
@@ -705,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
@@ -757,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)));
     }
     /**
@@ -853,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);
@@ -925,6 +1219,45 @@ export class AccessControlService {
         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);
@@ -951,6 +1284,85 @@ 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 {
@@ -1043,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 };
             }
@@ -1062,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);
@@ -1123,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
@@ -1193,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
@@ -1222,7 +1677,7 @@ export class AccessControlService {
         // / `roles.yaml` because `hasPermissionResolved` admin-rescues those
         // paths, so the bad config remains fixable from inside the app.
         const pluginDirs = new Map();
-        await walkKb(repoDir, [accessFileListener(repoDir, accessFiles, pluginDirs)]);
+        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
@@ -1237,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;
@@ -1318,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)
@@ -1358,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) {
@@ -1381,7 +1832,7 @@ 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')) {
@@ -1470,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;
         }
     }
@@ -1506,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;
@@ -1526,17 +1987,17 @@ 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.accessFiles) {