@bevel-software/platform-core-backend 0.28.1 → 0.30.0

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

@@ -8,6 +8,7 @@ import { isAbsence, type ITreeWalker, type WalkListener } from '../../shared/fs.
 import { assertOneSpecPerLine, 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 { readRevSha } from '../kb-fs/index.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type {
   IAccessControl,
@@ -66,19 +67,35 @@ import {
   DIRECTORY_SYNC_BOT_NAME,
 } from './directory-sync-bot.js';
 
+/** A full object id, which is what every at-ref gate resolves its ref to before reading. */
+function isCommitSha(ref: string): boolean {
+  return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(ref);
+}
+
+/**
+ * What one spec of a batched read came back as: a blob's text, nothing at
+ * that path, or an object that is not a file (a directory, say). The last
+ * two are told apart on purpose: for the model at a commit, a path that is
+ * there but is not a file is not "absent", it is config the model cannot be
+ * read from.
+ */
+type CatFileOutcome =
+  | { kind: 'blob'; text: string }
+  | { kind: 'missing' }
+  | { kind: 'non-blob'; type: string };
+
 /**
  * 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
- * them — the blob's text, or null when the spec is missing/ambiguous at the
- * ref or resolves to a non-blob (e.g. a directory). Output protocol per
- * request: `<oid> <type> <size>\n<size bytes>\n`, or `<spec> missing\n`
- * (the spec may itself contain spaces, hence the endsWith checks).
+ * them. Output protocol per request: `<oid> <type> <size>\n<size bytes>\n`,
+ * or `<spec> missing\n` (the spec may itself contain spaces, hence the
+ * endsWith checks).
  */
-async function catFileBatch(
+async function catFileBatchOutcomes(
   runner: IGitRunner,
   repoDir: string,
   specs: string[],
-): Promise<(string | null)[]> {
+): Promise<CatFileOutcome[]> {
   // 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.
   // One spec per LINE is the protocol, and this walk depends on getting back
@@ -91,7 +108,7 @@ async function catFileBatch(
     input: `${specs.join('\n')}\n`,
     encoding: 'buffer',
   });
-  const results: (string | null)[] = [];
+  const results: CatFileOutcome[] = [];
   let off = 0;
   for (let i = 0; i < specs.length; i++) {
     const nl = out.indexOf(0x0a, off);
@@ -99,7 +116,7 @@ async function catFileBatch(
     const header = out.subarray(off, nl).toString('utf-8');
     off = nl + 1;
     if (header.endsWith(' missing') || header.endsWith(' ambiguous')) {
-      results.push(null);
+      results.push({ kind: 'missing' });
       continue;
     }
     const parts = header.split(' ');
@@ -107,14 +124,33 @@ async function catFileBatch(
     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);
+    // A non-blob (a directory path resolves to a tree) is reported as such,
+    // and its payload still has to be skipped to stay aligned.
+    results.push(
+      parts[1] === 'blob'
+        ? { kind: 'blob', text: out.subarray(off, off + size).toString('utf-8') }
+        : { kind: 'non-blob', type: parts[1]! },
+    );
     off += size + 1; // payload + trailing LF
   }
   return results;
 }
 
+/**
+ * {@link catFileBatchOutcomes} for callers that want text or nothing: the
+ * blob's text, or null when the spec is missing at the ref or resolves to a
+ * non-blob — the own-entries reads, where a directory where a file was
+ * named simply carries no entries.
+ */
+async function catFileBatch(
+  runner: IGitRunner,
+  repoDir: string,
+  specs: string[],
+): Promise<(string | null)[]> {
+  const outcomes = await catFileBatchOutcomes(runner, repoDir, specs);
+  return outcomes.map((o) => (o.kind === 'blob' ? o.text : null));
+}
+
 
 interface AccessModel {
   roles: RolesIndex;
@@ -1340,7 +1376,13 @@ function ineligibleNamedEmailsResolved(
  * was built from (not the ref name that led there), so the per-file
  * own-entries reads that follow a gate resolve against exactly that tree.
  */
-type AtRefModel = { model: AccessModel; resolvedRef: string };
+/**
+ * A model built at a commit, with the commit it was built at and, when the
+ * tree is not too large to hold, every path the commit carries: what the
+ * own-entries reads need to tell a path that is absent at the commit (a
+ * fact, remembered) from a blob the batch could not read (never remembered).
+ */
+type AtRefModel = { model: AccessModel; resolvedRef: string; tree: ReadonlySet<string> | null };
 /**
  * One build's outcome: a model, no roles.yaml at the commit, or one that
  * doesn't parse. A git read failure is none of these: it throws
@@ -1384,22 +1426,50 @@ export class AccessControlService implements IAccessControl {
    *
    * This is what makes the change-request gates affordable. One detail read
    * plus one approval click runs six at-ref gates, and before this cache
-   * every one of them rebuilt the model from git: an `ls-tree -r` plus a
-   * `git show` per `access.md`, ~270ms each on a real knowledge base. Six
-   * builds per click was the lag behind the approve checkmark.
+   * every one of them rebuilt the model from git. A build is two git calls
+   * (`buildModelAtCommit`: one `ls-tree`, one `cat-file --batch` for every
+   * file the model reads), and each call forks the server process, which
+   * costs tens of milliseconds on a server holding a large heap.
+   *
+   * Bounded FIFO. The bound is sized for a listing that resolves access at
+   * every open change request's two refs: one commit per open request plus
+   * the targets, and a knowledge base with a hundred open requests was
+   * evicting in a cycle under the old bound of 64, rebuilding every model on
+   * every listing — thousands of forks, minutes of the main thread, and
+   * every other request waiting behind them. A commit's tree never changes,
+   * so a model is good for as long as it is held; the bound only caps memory.
    *
-   * Bounded FIFO, so a long-lived server holds the last few tips rather than
-   * one model per commit it ever gated against. A build that found no usable
-   * roles.yaml is deliberately NOT cached, and a build that saw any git read
-   * fail never becomes a model at all: it throws AccessUnreadableError and the
-   * gate fails closed for that call. Both are what a transient failure looks
-   * like, and pinning either to a commit would turn one hiccup into a wrong
-   * verdict, denying or granting, until the base branch moved. Concurrent
-   * misses on the same commit share one build via `atRefInFlight`.
+   * A commit with no roles.yaml is remembered too (`atRefNoRoles`): the batch
+   * read answers "missing" for it from git itself, which is as final as the
+   * commit. What is never cached is a build that saw a git read FAIL: it
+   * throws AccessUnreadableError and the gate fails closed for that call, and
+   * pinning that to a commit would turn one hiccup into a wrong verdict until
+   * the branch moved. Concurrent misses on the same commit share one build
+   * via `atRefInFlight`.
    */
   private readonly atRefCache = new Map<string, AtRefModel>();
+  private readonly atRefNoRoles = new Set<string>();
   private readonly atRefInFlight = new Map<string, Promise<AtRefBuild>>();
-  private static readonly AT_REF_CACHE_MAX = 64;
+  private static readonly AT_REF_CACHE_MAX = 512;
+
+  /**
+   * A path's own access entries AT A COMMIT, keyed by commit + path. A blob
+   * at a commit never changes, so neither does what it declares for itself:
+   * no TTL, no invalidation, and no workspace in the key (every clone holds
+   * the same objects). This is the read every at-ref gate makes after the
+   * model: one `cat-file --batch` per call for the paths asked, which a
+   * change-request listing made once per ref per listing for the same paths
+   * at the same commits. Bounded FIFO; the bound only caps memory.
+   */
+  private readonly ownEntriesAtCommit = new Map<string, OwnEntries | null>();
+  private static readonly OWN_ENTRIES_AT_COMMIT_MAX = 16_384;
+  /** Paths a cached model keeps of its commit's tree, at most; a larger tree is not kept. */
+  private static readonly TREE_INDEX_MAX_PATHS = 20_000;
+  /** Paths held across every cached model's tree, at most; past it the oldest models let their tree go. */
+  private static readonly TREE_INDEX_BUDGET = 500_000;
+  private readonly treeIndexMaxPaths: number;
+  private readonly treeIndexBudget: number;
+  private treePathsHeld = 0;
 
   /**
    * Canonicalised deployment-owner emails (see `AccessModel.deploymentOwners`).
@@ -1434,10 +1504,19 @@ export class AccessControlService implements IAccessControl {
      * run on the default layout.
      */
     private readonly kb: Pick<KbContext, 'layout'> = { layout: DEFAULT_KB_LAYOUT },
+    /**
+     * How much of the commits' trees the at-ref models may hold (see
+     * `TREE_INDEX_MAX_PATHS`, `TREE_INDEX_BUDGET`). The defaults are the
+     * deployment's; a suite lowers them to reach the bounds with a small
+     * repository.
+     */
+    limits: { treeIndexMaxPaths?: number; treeIndexBudget?: number } = {},
   ) {
     this.deploymentOwners = new Set(
       deploymentOwners.filter(Boolean).map((e) => canonicalEmail(e)),
     );
+    this.treeIndexMaxPaths = limits.treeIndexMaxPaths ?? AccessControlService.TREE_INDEX_MAX_PATHS;
+    this.treeIndexBudget = limits.treeIndexBudget ?? AccessControlService.TREE_INDEX_BUDGET;
   }
 
   /**
@@ -1579,6 +1658,23 @@ export class AccessControlService implements IAccessControl {
     return result;
   }
 
+  async groupsOfUser(workspaceId: string, userEmail: string): Promise<string[]> {
+    const model = await this.loadModel(workspaceId);
+    const email = canonicalEmail(userEmail);
+    const names: string[] = [];
+    for (const principal of model.roles.byCanonical.values()) {
+      if (principal.kind === 'group' && principal.emails.has(email)) names.push(principal.displayName);
+    }
+    return names;
+  }
+
+  async visibleGroups(workspaceId: string, userEmail: string, groups: readonly string[]): Promise<string[]> {
+    if (groups.length === 0) return [];
+    if (await this.holdsAdminRootWrite(workspaceId, userEmail)) return [...groups];
+    const mine = new Set(await this.groupsOfUser(workspaceId, userEmail));
+    return groups.filter((g) => mine.has(g));
+  }
+
   async canWriteBatch(
     workspaceId: string,
     userEmail: string,
@@ -2096,7 +2192,7 @@ export class AccessControlService implements IAccessControl {
     const loaded = await this.loadModelAtRef(workspaceId, ref);
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
-    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
     return hasPermissionResolved(loaded.model, 'write', userEmail, relativePath, own);
   }
 
@@ -2109,7 +2205,7 @@ export class AccessControlService implements IAccessControl {
     const loaded = await this.loadModelAtRef(workspaceId, ref);
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
-    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
     return canReadResolved(loaded.model, userEmail, relativePath, own);
   }
 
@@ -2132,7 +2228,7 @@ export class AccessControlService implements IAccessControl {
     const repoDir = await this.repoDir(workspaceId);
     // One `git cat-file --batch` for the whole path set — a per-path `git
     // show` spawn made CR owner-routing take minutes on large change sets.
-    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
     const result = new Map<string, boolean>();
     for (const p of relativePaths) {
       const machineOwned = machineAnswers.get(p);
@@ -2157,7 +2253,7 @@ export class AccessControlService implements IAccessControl {
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
     // One `git cat-file --batch` for the whole set — see canWriteBatchAtRef.
-    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
     const result = new Map<string, boolean>();
     for (const p of relativePaths) {
       result.set(p, canReadResolved(loaded.model, userEmail, p, owns.get(p) ?? null));
@@ -2180,7 +2276,7 @@ export class AccessControlService implements IAccessControl {
     const loaded = await this.loadModelAtRef(workspaceId, ref);
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
-    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath);
+    const own = await this.readOwnEntriesAtRef(repoDir, loaded.resolvedRef, relativePath, loaded.tree);
     return eligibleHoldersResolved(loaded.model, 'write', relativePath, own);
   }
 
@@ -2294,7 +2390,7 @@ export class AccessControlService implements IAccessControl {
     if (!loaded) return null;
     const repoDir = await this.repoDir(workspaceId);
     // One `git cat-file --batch` for the whole path set — see canWriteBatchAtRef.
-    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths);
+    const owns = await this.readOwnEntriesAtRefBatch(repoDir, loaded.resolvedRef, relativePaths, loaded.tree);
     for (const p of relativePaths) {
       if (result.has(p)) continue;
       const own = owns.get(p) ?? null;
@@ -2512,8 +2608,14 @@ export class AccessControlService implements IAccessControl {
     repoDir: string,
     ref: string,
     relativePath: string,
+    tree: ReadonlySet<string> | null = null,
   ): Promise<OwnEntries | null> {
     if (relativePath === 'roles.yaml') return null;
+    // At a commit (what every gate passes: `resolvedRef`), the batched read
+    // and its memo answer; a single `git show` stays for a symbolic ref.
+    if (isCommitSha(ref)) {
+      return (await this.readOwnEntriesAtRefBatch(repoDir, ref, [relativePath], tree)).get(relativePath) ?? null;
+    }
     const text = await this.showAtRef(repoDir, ref, relativePath);
     if (text === null) return null;
     if (isAccessMdPath(relativePath)) return accessMdSelfEntries(text);
@@ -2532,23 +2634,60 @@ export class AccessControlService implements IAccessControl {
     repoDir: string,
     ref: string,
     relativePaths: string[],
+    tree: ReadonlySet<string> | null = null,
   ): Promise<Map<string, OwnEntries | null>> {
     const result = new Map<string, OwnEntries | null>();
     const wanted: string[] = [];
+    const memo = isCommitSha(ref) ? this.ownEntriesAtCommit : null;
     for (const p of relativePaths) {
-      if (p === 'roles.yaml') result.set(p, null);
-      else if (!wanted.includes(p)) wanted.push(p);
+      if (p === 'roles.yaml') {
+        result.set(p, null);
+        continue;
+      }
+      const key = `${ref}\0${p}`;
+      if (memo?.has(key)) {
+        result.set(p, memo.get(key) ?? null);
+        continue;
+      }
+      // A path the commit's tree does not carry has no own entries, as a
+      // fact about the commit: remembered, and not read. (A change request
+      // that adds a file asks about it at the base, where it does not exist
+      // yet; one that deletes a file asks at the head.)
+      if (tree && !tree.has(p)) {
+        result.set(p, null);
+        if (memo) this.rememberOwnEntriesAtCommit(key, null);
+        continue;
+      }
+      if (!wanted.includes(p)) wanted.push(p);
     }
     if (wanted.length === 0) return result;
     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);
-      else result.set(p, isAccessMdPath(p) ? accessMdSelfEntries(text) : parseOwnAccessEntries(text));
+      if (text === null) {
+        // Absent at the commit (when no tree was there to say so first), or
+        // a blob git could not read: the batch says "missing" for both, and
+        // only the first is a fact about the commit. Answered as no own
+        // entries, as before, but never remembered.
+        result.set(p, null);
+        return;
+      }
+      const own = isAccessMdPath(p) ? accessMdSelfEntries(text) : parseOwnAccessEntries(text);
+      result.set(p, own);
+      // What a blob declares for itself — including nothing — is a fact about the commit.
+      if (memo) this.rememberOwnEntriesAtCommit(`${ref}\0${p}`, own);
     });
     return result;
   }
 
+  private rememberOwnEntriesAtCommit(key: string, value: OwnEntries | null): void {
+    this.ownEntriesAtCommit.set(key, value);
+    if (this.ownEntriesAtCommit.size > AccessControlService.OWN_ENTRIES_AT_COMMIT_MAX) {
+      const oldest = this.ownEntriesAtCommit.keys().next().value;
+      if (oldest !== undefined) this.ownEntriesAtCommit.delete(oldest);
+    }
+  }
+
   /**
    * Resolve a candidate ref to one git accepts. Falls back to `origin/<ref>`
    * for short branch names, matching the heuristic in
@@ -2600,28 +2739,38 @@ export class AccessControlService implements IAccessControl {
   /**
    * List every `access.md` path that exists at any depth as of `ref`.
    * The access tree is structure-agnostic: any `access.md` participates
-   * regardless of where it sits. Uses `git ls-tree -r --name-only`.
-   * `'error'` when git failed: a model built without its access files is
-   * not the model, and the caller must not cache it as one.
+   * regardless of where it sits. Uses `git ls-tree -r -z --name-only`: `-z`
+   * puts a NUL between paths and prints them as they are, where the default
+   * output C-quotes a path with a non-ASCII or special character, which would
+   * then name nothing when read back. `'error'` when git failed: a model
+   * built without its access files is not the model, and the caller must not
+   * cache it as one.
    */
   private async listAccessFilesAtRef(
     repoDir: string,
     ref: string,
-  ): Promise<{ accessFiles: string[]; pluginDirs: string[] } | 'error'> {
+  ): Promise<{ accessFiles: string[]; pluginDirs: string[]; named: Set<string>; all: string[] } | 'error'> {
     try {
-      const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '--name-only', ref]);
+      const { stdout } = await this.gitRunner.run(repoDir, ['ls-tree', '-r', '-z', '--name-only', ref]);
       const out: string[] = [];
       const pluginDirs: string[] = [];
+      const all: string[] = [];
+      // The fixed-name sources the tree carries (roles.yaml, the groups
+      // files): a read of one of these that comes back empty is "absent"
+      // only when the tree does not name it.
+      const named = new Set<string>();
       const { pluginsDir } = this.kb.layout;
-      for (const line of stdout.split('\n')) {
-        const p = line.trim();
+      for (const p of stdout.split('\0')) {
         if (!p) continue;
+        // One past the cap is enough to know the tree is not kept.
+        if (all.length <= this.treeIndexMaxPaths) all.push(p);
         if (p === 'access.md' || p.endsWith('/access.md')) out.push(p);
+        else if (p === 'roles.yaml' || p === SYNCED_GROUPS_YAML || p === GROUPS_YAML) named.add(p);
         else if (p.startsWith(`${pluginsDir}/`) && p.endsWith(`/${PLUGIN_MANIFEST_FILE}`)) {
           pluginDirs.push(p.slice(0, -(PLUGIN_MANIFEST_FILE.length + 1)));
         }
       }
-      return { accessFiles: out, pluginDirs };
+      return { accessFiles: out, pluginDirs, named, all };
     } catch {
       return 'error';
     }
@@ -2666,6 +2815,9 @@ export class AccessControlService implements IAccessControl {
       const key = `${workspaceId}\0${commit}`;
       const hit = this.atRefCache.get(key);
       if (hit) return hit;
+      // A commit known to carry no roles.yaml: the next candidate, without a
+      // build (see `atRefNoRoles`).
+      if (this.atRefNoRoles.has(key)) continue;
       // Registered BEFORE the first await on the build path, so concurrent
       // misses on one commit share a single build instead of all racing past
       // an empty in-flight check together.
@@ -2674,6 +2826,7 @@ export class AccessControlService implements IAccessControl {
         pending = this.buildModelAtCommit(repoDir, commit, candidate)
           .then((built) => {
             if (typeof built !== 'string') this.rememberAtRef(key, built);
+            else if (built === 'no-roles') this.rememberNoRolesAtRef(key);
             return built;
           })
           .finally(() => {
@@ -2692,6 +2845,14 @@ export class AccessControlService implements IAccessControl {
   /** The commit `ref` points at in this clone, or null when it doesn't resolve. */
   private async revParseCommit(repoDir: string, ref: string): Promise<string | null> {
     if (!ref || ref.startsWith('-')) return null;
+    // The ref files first (`readRevSha`): the names git would try, in git's
+    // order, read without a process. "Missing" from the files is what
+    // rev-parse answers nothing for; "unreadable" — a spelling the reader
+    // does not resolve, a tag it cannot peel, a file it could not read — is
+    // git's to decide, as the authority.
+    const fromFiles = await readRevSha(repoDir, ref);
+    if (fromFiles === 'missing') return null;
+    if (fromFiles !== 'unreadable') return fromFiles.sha;
     try {
       const { stdout } = await this.gitRunner.run(repoDir, [
         'rev-parse',
@@ -2712,9 +2873,30 @@ export class AccessControlService implements IAccessControl {
 
   private rememberAtRef(key: string, value: AtRefModel): void {
     this.atRefCache.set(key, value);
+    this.treePathsHeld += value.tree?.size ?? 0;
     if (this.atRefCache.size > AccessControlService.AT_REF_CACHE_MAX) {
       const oldest = this.atRefCache.keys().next().value;
-      if (oldest !== undefined) this.atRefCache.delete(oldest);
+      if (oldest !== undefined) {
+        this.treePathsHeld -= this.atRefCache.get(oldest)?.tree?.size ?? 0;
+        this.atRefCache.delete(oldest);
+      }
+    }
+    // The trees are a budget of their own, across every held model: past
+    // it, the oldest models keep their model and let their tree go — the
+    // gate still answers, absence is just no longer remembered for them.
+    for (const held of this.atRefCache.values()) {
+      if (this.treePathsHeld <= this.treeIndexBudget) break;
+      if (!held.tree) continue;
+      this.treePathsHeld -= held.tree.size;
+      held.tree = null;
+    }
+  }
+
+  private rememberNoRolesAtRef(key: string): void {
+    this.atRefNoRoles.add(key);
+    if (this.atRefNoRoles.size > AccessControlService.AT_REF_CACHE_MAX) {
+      const oldest = this.atRefNoRoles.values().next().value;
+      if (oldest !== undefined) this.atRefNoRoles.delete(oldest);
     }
   }
 
@@ -2725,6 +2907,15 @@ export class AccessControlService implements IAccessControl {
    * means the commit carries no roles.yaml (the caller tries its next
    * candidate); `'malformed'` means it does but it doesn't parse (the caller
    * answers null, as it always has).
+   *
+   * TWO git calls, whatever the tree holds: one `ls-tree` to learn which
+   * files the model is made of, then one `cat-file --batch` that reads all of
+   * them — roles.yaml, the groups sources, every access.md and every plugin
+   * manifest. It used to be one `git show` per file, and each git call forks
+   * the server process, which on a server holding a large heap costs tens of
+   * milliseconds of the main thread per call: a knowledge base with a few
+   * dozen access files paid a second or more per commit, times every ref a
+   * listing resolves.
    */
   private async buildModelAtCommit(
     repoDir: string,
@@ -2737,20 +2928,74 @@ export class AccessControlService implements IAccessControl {
     // and the caller fails closed (AccessUnreadableError, a 503) until a
     // retry reads the tree in full.
     const tag = `${label}@${commit.slice(0, 7)}`;
+
+    const listed = await this.listAccessFilesAtRef(repoDir, commit);
+    if (listed === 'error') {
+      logger(`access@${tag}`).warn('listing access.md files failed; refusing to decide from a partial tree');
+      throw new AccessUnreadableError(label, 'access.md (ls-tree)');
+    }
+    const wanted = [
+      'roles.yaml',
+      SYNCED_GROUPS_YAML,
+      GROUPS_YAML,
+      ...listed.accessFiles,
+      ...listed.pluginDirs.map((dir) => `${dir}/${PLUGIN_MANIFEST_FILE}`),
+    ];
+    let outcomes: CatFileOutcome[];
+    try {
+      outcomes = await catFileBatchOutcomes(this.gitRunner, repoDir, wanted.map((p) => `${commit}:${p}`));
+    } catch (err) {
+      // The operational signal: one line per failed build, naming the commit,
+      // so a run of these is visible in the logs.
+      logger(`access@${tag}`).warn(
+        `git read of the access tree failed; refusing to decide from a partial tree: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      throw new AccessUnreadableError(label, 'access tree (cat-file)');
+    }
+    const fetched = new Map<string, CatFileOutcome>();
+    wanted.forEach((p, i) => fetched.set(p, outcomes[i] ?? { kind: 'missing' }));
+    const refuse = (relativePath: string, why: string): never => {
+      logger(`access@${tag}`).warn(`${relativePath} ${why}; refusing to decide from a partial tree`);
+      throw new AccessUnreadableError(label, relativePath);
+    };
+    // What the build reads. "Missing" from the batch is "absent" only for a
+    // groups source the tree does not name. A path the tree names — an
+    // access.md, a plugin manifest, or a groups file the listing carried —
+    // that comes back missing has a blob git could not read (a lost object),
+    // and one that is not a file is a tree the model cannot be read from:
+    // either way the build fails closed rather than drop what that file
+    // would deny. A path the build did not prefetch (none today) is read on
+    // its own, told apart from a git failure as before.
+    const inTree = (relativePath: string) =>
+      listed.named.has(relativePath) || !(relativePath === SYNCED_GROUPS_YAML || relativePath === GROUPS_YAML);
     const read = async (relativePath: string): Promise<string | null> => {
-      const outcome = await this.showAtRefOutcome(repoDir, commit, relativePath);
-      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.
-        logger(`access@${tag}`).warn(`git read of ${relativePath} failed; refusing to decide from a partial tree`);
-        throw new AccessUnreadableError(label, relativePath);
+      const got = fetched.get(relativePath);
+      if (got === undefined) {
+        const outcome = await this.showAtRefOutcome(repoDir, commit, relativePath);
+        if (outcome.kind === 'error') refuse(relativePath, 'could not be read');
+        return outcome.kind === 'text' ? outcome.text : null;
       }
-      return outcome.kind === 'text' ? outcome.text : null;
+      if (got.kind === 'blob') return got.text;
+      if (got.kind === 'non-blob') return refuse(relativePath, `is a ${got.type}, not a file`);
+      if (!inTree(relativePath)) return null;
+      return refuse(relativePath, 'is in the tree but its blob could not be read');
     };
 
-    const rolesYaml = await read('roles.yaml');
-    if (rolesYaml === null) return 'no-roles';
-    const rolesParsed = parseRolesYaml(rolesYaml);
+    // roles.yaml decides the build's outcome, so its states are read
+    // directly. Absent from the tree is "no roles here" (the caller tries
+    // its next candidate ref). In the tree but unreadable refuses the build:
+    // answering "no roles" for it would be remembered for the commit and
+    // would send a short ref through to origin, which may grant. A directory
+    // of that name is as malformed as a file that does not parse (the caller
+    // answers null, and never falls through to a ref that might grant what
+    // this one does not).
+    const roles = fetched.get('roles.yaml') ?? { kind: 'missing' as const };
+    if (roles.kind === 'missing') {
+      if (listed.named.has('roles.yaml')) refuse('roles.yaml', 'is in the tree but its blob could not be read');
+      return 'no-roles';
+    }
+    if (roles.kind === 'non-blob') return 'malformed';
+    const rolesParsed = parseRolesYaml(roles.text);
     if (!rolesParsed.ok) return 'malformed';
 
     // Same group loading as the working-tree model, read AT THE COMMIT — the
@@ -2775,11 +3020,6 @@ export class AccessControlService implements IAccessControl {
     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') {
-      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) {
       const text = await read(p);
       if (text === null) continue;
@@ -2824,6 +3064,10 @@ export class AccessControlService implements IAccessControl {
         deploymentOwners: this.deploymentOwners,
       },
       resolvedRef: commit,
+      // The listing already named every path; held so an own-entries read
+      // can tell absence from a lost blob, unless the tree is too large to
+      // hold for every cached commit (then absence is simply not remembered).
+      tree: listed.all.length <= this.treeIndexMaxPaths ? new Set(listed.all) : null,
     };
   }
 }

package/src/modules/access/access.routes.ts

@@ -128,6 +128,18 @@ export function createAccessRoutes(
     return { roles, groups, plugins: plugins ?? [] };
   };
 
+  /**
+   * The groups `email` may be offered as a grantee, or name in a grant: the
+   * resolver's ONE answer to who sees which group (`visibleGroups`: every
+   * group for an admin, only their own for anyone else), the same the
+   * Library's Groups tab lists. Read on the default branch, where the active
+   * group source lives. The picker never names a group the caller has no
+   * part in, and the grant route refuses one with the same words as a group
+   * that does not exist.
+   */
+  const visibleGroups = (email: string, groups: string[]): Promise<string[]> =>
+    accessControl.visibleGroups(kb.defaultWorkspaceId(), email, groups);
+
   /**
    * The plugins `email` may DISCOVER — read the folder's access.md, the same
    * verdict the plugin index lists on. Both the suggest list and the grant
@@ -491,8 +503,9 @@ export function createAccessRoutes(
    * names — resolved from the DEFAULT branch, the authoritative source),
    * groups (the ACTIVE group source, same authority), and people (branch-local
    * to `:id`). Roles/groups come from the resolver's CACHED model — no fresh
-   * file reads per keystroke. Roles + groups are small + non-sensitive so they
-   * always show; PEOPLE are withheld until `q` is ≥ 2 chars, so an empty query
+   * file reads per keystroke. Roles are small + non-sensitive so they always
+   * show; GROUPS are the caller's own unless they are an admin (see
+   * `visibleGroups`); PEOPLE are withheld until `q` is ≥ 2 chars, so an empty query
    * can't dump the whole directory (email-harvesting guard). People are the
    * union of the KB-canonical set (roles.yaml + access.md grants) and the
    * `users` table (logged-in users). Results are capped. Each person carries
@@ -527,7 +540,7 @@ export function createAccessRoutes(
         .filter((g) => !q || g.toLowerCase().includes(q))
         .slice(0, CAP);
 
-      const matchedGroups = groups
+      const matchedGroups = (await visibleGroups(user.email, groups))
         .filter((g) => !q || g.toLowerCase().includes(q))
         .slice(0, CAP);
 
@@ -934,9 +947,12 @@ export function createAccessRoutes(
       } else if (principal.kind === 'group') {
         // A group grant must name a group in the ACTIVE source (IdP-synced or
         // manual) on the default branch — same authority the suggest list
-        // uses. No role-collision refusal: bare tokens resolve GROUP-FIRST,
-        // so the written bare name IS the group.
-        const { groups } = await defaultBranchPrincipals();
+        // uses — and one the caller may see (`visibleGroups`): a group hidden
+        // from the picker is refused here with the same words as one that
+        // does not exist, so the grant route is no oracle for group names.
+        // No role-collision refusal: bare tokens resolve GROUP-FIRST, so the
+        // written bare name IS the group.
+        const groups = await visibleGroups(user.email, (await defaultBranchPrincipals()).groups);
         const canonical = canonicalRoleName(principal.group);
         if (!groups.some((g) => canonicalRoleName(g) === canonical)) {
           throw new AccessMutationError(

package/src/modules/agent-instructions/shared-file-rules.ts

@@ -3,7 +3,7 @@
  *
  * They used to be appended, in full, to every tool description that they
  * covered: the content rule rode on all twelve file tools, the agent-guide
- * reminder on all of them plus the shell, the write-mode and escape-sequence
+ * reminder on all of them, the write-mode and escape-sequence
  * paragraphs on two or three apiece. A description then ran to two or three
  * thousand characters, most of it text the agent had already read on the tool
  * above — and clients cut long descriptions from the END, which is where the