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

package/src/modules/access/access-control.service.ts

@@ -1,24 +1,33 @@
 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';
 
-import { isAbsence } from '../../shared/fs-errors.js';
-import { walkKb, type KbWalkListener } from '../../shared/kb-walk.js';
+const log = logger('access');
+
+import { isAbsence, type ITreeWalker, type WalkListener } from '../../shared/fs.contract.js';
+import { isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
+import { hashEmail } from '../../shared/email-identity.js';
+import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type {
   IAccessControl,
+  AccessDecision,
+  AccessDecisionSource,
   AccessTargetKind,
+  DenialSources,
   GrantPrincipal,
   GrantSource,
   GrantSources,
+  PathHolders,
+  ProspectiveHolders,
   ResolvedPrincipal,
 } from './access-control.interface.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,
@@ -40,6 +49,7 @@ import {
   parseAccessFile,
   parseOwnAccessEntries,
   parseRolesYaml,
+  requiredVerbsFor,
   sourceVerbsFor,
   type AccessFile,
   type OwnEntries,
@@ -52,8 +62,6 @@ import {
   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
@@ -62,60 +70,39 @@ 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: string, specs: string[]): Promise<(string | null)[]> {
-  return new Promise((resolve, reject) => {
-    const child = spawn('git', ['-C', repoDir, 'cat-file', '--batch'], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    const chunks: Buffer[] = [];
-    const errChunks: Buffer[] = [];
-    child.stdout.on('data', (c: Buffer) => chunks.push(c));
-    child.stderr.on('data', (c: Buffer) => 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: (string | null)[] = [];
-        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: IGitRunner,
+  repoDir: string,
+  specs: string[],
+): Promise<(string | null)[]> {
+  // 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: string): string {
-  return createHash('sha256').update(email.trim().toLowerCase()).digest('hex');
+  const results: (string | null)[] = [];
+  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;
 }
 
 
@@ -133,10 +120,11 @@ interface AccessModel {
    * Canonical emails that count as Admin whatever `roles.yaml` says — the
    * deployment owner (`ADMIN_EMAIL`). Empty when none is configured.
    *
-   * This exists for the two hardcoded `write` rescues below, and only those.
-   * It is NOT a general grant: it never enters scope resolution, so it gives
-   * no read, no download, and no write anywhere except `roles.yaml` and
-   * `access.md`. The deployment owner is the person who can already change
+   * This exists for the two hardcoded `write` rescues below and the root write
+   * floor, and only those. It is NOT a general grant: it never enters scope
+   * resolution, so it gives no read, no download, and no write beyond
+   * `roles.yaml`, `access.md`, and what the root floor reaches (see
+   * `hasPermissionResolved`). The deployment owner is the person who can already change
    * `ADMIN_EMAIL` itself, so admitting them to the rescue path concedes
    * nothing they could not already take — while withholding it turns a
    * `roles.yaml` that has lost its last Admin into a knowledge base nobody
@@ -160,7 +148,7 @@ function roleKnown(roles: RolesIndex, canonicalRole: string): boolean {
  * nothing, bare grant tokens fall through to roles, and group-backed denies
  * drop (the owner's explicit degrade-loudly decision, NOT fail-closed). The
  * marker is carried on the loaded model and surfaced by the groups admin
- * endpoints so the Groups page can banner it.
+ * endpoints so the Groups & Members page can banner it.
  */
 export type GroupsHealth = { ok: true } | { ok: false; file: string; reason: string };
 
@@ -171,13 +159,13 @@ export type GroupsHealth = { ok: true } | { ok: false; file: string; reason: str
  * 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: (filename: string) => Promise<string | null>,
@@ -201,14 +189,10 @@ export async function loadActiveGroups(
     // subprocess. roles.yaml and access.md already fail the build closed on
     // 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;
@@ -220,8 +204,7 @@ export async function loadActiveGroups(
       text = await read(GROUPS_YAML);
     } 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) return { groups: new Map(), sourceFile, warnings: [], health: { ok: true } };
@@ -270,6 +253,15 @@ interface AccessScope {
   byEmail: Map<string, GrantState>;
   everyone: GrantState | undefined;
   source: ScopeSource;
+  /**
+   * The keys whose `'denied'` in `byRole` / `byEmail` is IMPLIED — a denial
+   * of a verb the target presupposes (`deny write` when resolving `owner`),
+   * with no `deny <target>` line of their own here. The verdict is as real as
+   * any (the effective walk, the eligible lists and the collapsed view treat
+   * it as denied), but it is not a LINE in this file: `denialSources`, which
+   * reports the entries a person can lift, leaves it out.
+   */
+  implied: { byRole: Set<string>; byEmail: Set<string> };
 }
 
 /**
@@ -301,7 +293,7 @@ function accessFileListener(
   repoDir: string,
   out: Map<string, AccessFile>,
   pluginDirs: Map<string, string>,
-): KbWalkListener {
+): WalkListener {
   return {
     async onFile(dir, name) {
       const rel = dir ? `${dir}/${name}` : name;
@@ -316,14 +308,12 @@ function accessFileListener(
       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`);
+        for (const e of parsed.errors) log.warn(`${e} — file ignored`);
         return;
       }
-      for (const w of parsed.warnings) console.warn(`[access] ${w}`);
+      for (const w of parsed.warnings) 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);
@@ -351,13 +341,21 @@ function resolveScopes(
   fileOwn?: OwnEntries | null,
 ): AccessScope[] {
   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: Record<Verb, ParsedEntry[]>,
     filterRoles: boolean,
@@ -365,23 +363,39 @@ function resolveScopes(
   ): AccessScope => {
     const byRole = new Map<string, GrantState>();
     const byEmail = new Map<string, GrantState>();
+    const implied = { byRole: new Set<string>(), byEmail: new Set<string>() };
     const set = (entry: ParsedEntry, state: GrantState) => {
       const map = entry.kind === 'role' ? byRole : byEmail;
       const key = entry.kind === 'role' ? entry.role : entry.email;
       if (map.get(key) === 'grant') return; // a grant in this scope sticks
       map.set(key, state);
     };
+    const skip = (entry: ParsedEntry) =>
+      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)) continue;
+      if (skip(entry)) continue;
       set(entry, entry.deny ? 'denied' : 'grant');
     }
     for (const src of supersets) {
       for (const entry of entries[src]) {
         if (entry.deny) continue; // grant-only fold
-        if (filterRoles && entry.kind === 'role' && !roleKnown(model.roles, entry.role)) continue;
+        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
@@ -404,7 +418,7 @@ function resolveScopes(
       : publicDeny
         ? 'denied'
         : byRole.get(EVERYONE_CANONICAL);
-    return { byRole, byEmail, everyone, source };
+    return { byRole, byEmail, everyone, source, implied };
   };
 
   const scopes: AccessScope[] = [];
@@ -463,13 +477,105 @@ function principalKeysOf(model: AccessModel, email: string): Set<string> | undef
   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: AccessModel, keys: Set<string>): Set<string> {
+  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: AccessModel, group: string): Set<string> | null {
+  const canonical = canonicalRoleName(group);
+  const record = model.roles.byCanonical.get(canonical);
+  if (!record || record.kind !== 'group') return null;
+  const keys = new Set<string>([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: ReadonlySet<string> = 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: AccessModel,
+  verb: Verb,
+  keys: ReadonlySet<string>,
+  relativePath: string,
+  fileOwn?: OwnEntries | null,
+): boolean {
+  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: AccessScope, relativePath: string): boolean {
+  if (scope.source.kind === 'own') return !relativePath.includes('/');
+  return scope.source.path === 'access.md';
+}
+
 function isAdminEmail(model: AccessModel, email: string): boolean {
   if (model.deploymentOwners.has(email)) return true;
   const roles = model.roles.byEmail.get(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);
 }
 
 /**
@@ -503,6 +609,16 @@ function isAdminEmail(model: AccessModel, email: string): boolean {
  * 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(
@@ -512,44 +628,88 @@ function hasPermissionResolved(
   relativePath: string,
   fileOwn?: OwnEntries | null,
 ): boolean {
+  return decidePermissionResolved(model, verb, userEmail, relativePath, fileOwn).allowed;
+}
+
+/**
+ * WHAT decided one caller's verdict: `hasPermissionResolved` with its reasoning
+ * kept. `scope` is the scope whose entry settled it (null for the hardcoded
+ * admin rescues and for default-deny; the root scope, or null when there is
+ * none, for the Admin write floor); `via` is the tier that matched and `key`
+ * the principal key it matched on (the caller's email, a role/group/plugin
+ * key, or `everyone`). `hasPermissionResolved` IS this function's `allowed`,
+ * so an explanation can never disagree with the gate.
+ */
+interface PermissionDecision {
+  allowed: boolean;
+  scope: AccessScope | null;
+  via: 'email' | 'principal' | 'everyone' | 'admin-rescue' | 'admin-floor' | 'default-deny';
+  key?: string;
+}
+
+function decidePermissionResolved(
+  model: AccessModel,
+  verb: Verb,
+  userEmail: string,
+  relativePath: string,
+  fileOwn?: OwnEntries | null,
+): PermissionDecision {
   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 userRoles = principalKeysOf(model, email);
+  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 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';
+    if (direct) 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: string | undefined;
+      let denied: string | undefined;
       for (const r of userRoles) {
         const s = scope.byRole.get(r);
-        if (s === 'denied') deny = true;
-        else if (s === 'grant') grant = true;
+        if (s === 'denied') denied ??= r;
+        else if (s === 'grant') 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' };
 }
 
 /**
@@ -581,6 +741,49 @@ function scopeToGrantSource(
   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: AccessScope,
+  kind: AccessTargetKind,
+  relativePath: string,
+): AccessDecisionSource {
+  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: AccessModel,
+  decision: PermissionDecision,
+  kind: AccessTargetKind,
+  relativePath: string,
+): AccessDecision {
+  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
@@ -639,14 +842,7 @@ function resolveGrantSourcesForVerb(
     //     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')) {
@@ -672,6 +868,84 @@ function resolveGrantSourcesForVerb(
   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: AccessModel,
+  role: string,
+  tokenMatch?: 'exact' | 'name',
+): string[] {
+  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: AccessModel,
+  verb: Verb,
+  kind: AccessTargetKind,
+  relativePath: string,
+  principal: GrantPrincipal,
+  fileOwn?: OwnEntries | null,
+  tokenMatch?: 'exact' | 'name',
+): GrantSource[] {
+  const scopes = resolveScopes(model, verb, relativePath, fileOwn);
+  const out: GrantSource[] = [];
+
+  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` →
@@ -747,6 +1021,30 @@ function canReadResolved(
   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: AccessModel, token: string): Set<string> {
+  const record = model.roles.byCanonical.get(token);
+  if (record?.kind === 'group') return principalKeysOfGroup(model, token) ?? new Set([token]);
+  const keys = new Set<string>([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: AccessModel,
   verb: Verb,
@@ -771,16 +1069,31 @@ function eligibleHoldersResolved(
     const key = `${kind}\0${name.toLowerCase()}`;
     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: ReadonlySet<string>) =>
+    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') addPrincipal(EVERYONE_CANONICAL, 'role');
+  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
@@ -794,7 +1107,7 @@ function eligibleHoldersResolved(
     // 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');
   }
 
@@ -809,6 +1122,7 @@ function eligibleHoldersResolved(
   const users: { name: string; email: string }[] = [];
   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));
@@ -816,6 +1130,18 @@ function eligibleHoldersResolved(
   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: AccessModel, byEmail: CollapsedScope['byEmail']): Set<string> {
+  const candidates = new Set<string>(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.
  *
@@ -841,10 +1167,10 @@ function eligibleHolderEmailsResolved(
   // 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<string>();
-  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)) {
@@ -871,9 +1197,7 @@ function ineligibleNamedEmailsResolved(
   fileOwn?: OwnEntries | null,
 ): Set<string> {
   const { byEmail } = resolveAtPath(model, verb, relativePath, fileOwn);
-  const candidates = new Set<string>();
-  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<string>();
   for (const email of candidates) {
@@ -962,6 +1286,7 @@ export class AccessControlService implements IAccessControl {
   constructor(
     private readonly workspaceService: WorkspaceService,
     private readonly kbDirName: string,
+    private readonly disk: ITreeWalker,
     /**
      * Emails that count as Admin for the two hardcoded `write` rescues,
      * whatever `roles.yaml` says — in practice `ADMIN_EMAIL`. Optional so the
@@ -969,6 +1294,13 @@ export class AccessControlService implements IAccessControl {
      * current behaviour (no owner, roles.yaml is the only authority).
      */
     deploymentOwners: readonly string[] = [],
+    /**
+     * 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.
+     */
+    private readonly gitRunner: IGitRunner = new NodeGitRunner(),
   ) {
     this.deploymentOwners = new Set(
       deploymentOwners.filter(Boolean).map((e) => canonicalEmail(e)),
@@ -1080,6 +1412,40 @@ export class AccessControlService implements IAccessControl {
     return result;
   }
 
+  async canReadAsGroupBatch(
+    workspaceId: string,
+    group: string,
+    relativePaths: string[],
+  ): Promise<Map<string, boolean> | null> {
+    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<string, boolean>();
+    relativePaths.forEach((p, i) => {
+      result.set(p, hasPermissionForKeys(model, 'read', keys, p, owns[i]));
+    });
+    return result;
+  }
+
+  async canReadAsEveryoneBatch(workspaceId: string, relativePaths: string[]): Promise<Map<string, boolean>> {
+    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<string, boolean>();
+    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: string,
     userEmail: string,
@@ -1206,6 +1572,52 @@ export class AccessControlService implements IAccessControl {
     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: string,
+    fromPath: string,
+    toPath: string,
+  ): Promise<ProspectiveHolders> {
+    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: unknown) => {
+      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: string): PathHolders => ({
+      read: eligibleHoldersResolved(model, 'read', relativePath, own),
+      write: eligibleHoldersResolved(model, 'write', relativePath, own),
+    });
+    return { before: holdersAt(fromPath), after: holdersAt(toPath) };
+  }
+
   async eligibleWriterEmails(
     workspaceId: string,
     relativePath: string,
@@ -1255,6 +1667,111 @@ export class AccessControlService implements IAccessControl {
     return out;
   }
 
+  async denialSources(
+    workspaceId: string,
+    kind: AccessTargetKind,
+    relativePath: string,
+    principal: GrantPrincipal,
+    opts?: { tokenMatch?: 'exact' | 'name' },
+  ): Promise<DenialSources> {
+    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: DenialSources = {};
+    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: string,
+    kind: AccessTargetKind,
+    relativePath: string,
+  ): Promise<{ principals: ResolvedPrincipal[]; users: { name: string; email: string }[] }> {
+    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: OwnEntries | null =
+      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<string, ResolvedPrincipal>();
+    const byEmail = new Map<string, { name: string; email: string }>();
+    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: string,
+    userEmail: string,
+    kind: AccessTargetKind,
+    relativePath: string,
+  ): Promise<Record<Verb, AccessDecision>> {
+    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 = {} as Record<Verb, AccessDecision>;
+    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: string): Promise<{
     roles: string[];
     groups: string[];
@@ -1355,7 +1872,7 @@ export class AccessControlService implements IAccessControl {
       ...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 };
       }
@@ -1374,7 +1891,7 @@ export class AccessControlService implements IAccessControl {
    */
   private machineOwnedWriteRule(userEmail: string, relativePath: string): boolean | null {
     if (relativePath !== SYNCED_GROUPS_YAML) return null;
-    return userEmail.trim().toLowerCase() === DIRECTORY_SYNC_BOT_EMAIL;
+    return canonicalEmail(userEmail) === DIRECTORY_SYNC_BOT_EMAIL;
   }
 
   async canWriteAtRef(
@@ -1455,6 +1972,54 @@ export class AccessControlService implements IAccessControl {
     return eligibleHoldersResolved(loaded.model, 'write', relativePath, own);
   }
 
+  async holdsAdminRootWrite(workspaceId: string, userEmail: string): Promise<boolean> {
+    const model = await this.loadModel(workspaceId);
+    return isAdminEmail(model, canonicalEmail(userEmail));
+  }
+
+  async canRestorePlatformFile(
+    workspaceId: string,
+    userEmail: string,
+    destinationRelativePath: string,
+  ): Promise<boolean> {
+    const target = platformRestoreDestination(destinationRelativePath);
+    if (target === null) return false;
+    const email = canonicalEmail(userEmail);
+
+    let admin: boolean;
+    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: string,
     ref: string,
@@ -1545,23 +2110,22 @@ export class AccessControlService implements IAccessControl {
       try {
         return await fs.readFile(path.join(repoDir, filename), 'utf-8');
       } catch (err) {
-        const code = (err as NodeJS.ErrnoException | null)?.code;
-        if (code === 'ENOENT' || code === 'ENOTDIR') return null;
+        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}`);
+    for (const w of activeGroups.warnings) log.warn(w);
     const mergeWarnings = mergeGroupsIntoRoles(
       rolesParsed.index,
       activeGroups.groups,
       activeGroups.sourceFile,
     );
-    for (const w of mergeWarnings) console.warn(`[access] ${w}`);
+    for (const w of mergeWarnings) log.warn(w);
 
     const accessFiles = new Map<string, AccessFile>();
 
@@ -1579,7 +2143,7 @@ export class AccessControlService implements IAccessControl {
     // / `roles.yaml` because `hasPermissionResolved` admin-rescues those
     // paths, so the bad config remains fixable from inside the app.
     const pluginDirs = new Map<string, string>();
-    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
@@ -1596,9 +2160,7 @@ export class AccessControlService implements IAccessControl {
       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;
@@ -1686,7 +2248,7 @@ export class AccessControlService implements IAccessControl {
       else if (!wanted.includes(p)) wanted.push(p);
     }
     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) result.set(p, null);
@@ -1730,15 +2292,7 @@ export class AccessControlService implements IAccessControl {
     relativePath: string,
   ): Promise<{ kind: 'text'; text: string } | { kind: 'absent' } | { kind: 'error' }> {
     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) {
       const stderr =
@@ -1763,11 +2317,7 @@ export class AccessControlService implements IAccessControl {
     ref: string,
   ): Promise<{ accessFiles: string[]; pluginDirs: string[] } | 'error'> {
     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: string[] = [];
       const pluginDirs: string[] = [];
       for (const line of stdout.split('\n')) {
@@ -1850,14 +2400,19 @@ export class AccessControlService implements IAccessControl {
   private async revParseCommit(repoDir: string, ref: string): Promise<string | null> {
     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;
     }
   }
@@ -1894,7 +2449,7 @@ export class AccessControlService implements IAccessControl {
       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;
@@ -1914,22 +2469,22 @@ export class AccessControlService implements IAccessControl {
     // 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}`);
+    for (const w of activeGroups.warnings) logger(`access@${tag}`).warn(w);
     const mergeWarnings = mergeGroupsIntoRoles(
       rolesParsed.index,
       activeGroups.groups,
       activeGroups.sourceFile,
     );
-    for (const w of mergeWarnings) console.warn(`[access@${tag}] ${w}`);
+    for (const w of mergeWarnings) logger(`access@${tag}`).warn(w);
 
     const accessFiles = new Map<string, AccessFile>();
     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) {