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

package/src/modules/kb-fs/ref-files.ts

@@ -0,0 +1,279 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isAbsence } from '../../shared/fs.contract.js';
+import { gitDirOf } from './git-dir.js';
+
+/**
+ * Where a ref points, read from the repository's own files instead of a
+ * `git rev-parse` process.
+ *
+ * A branch tip is a small file git maintains: `refs/remotes/origin/<branch>`
+ * as a loose file, or one line of `packed-refs`. Reading it costs a file read
+ * and no fork, and it is exactly as current as the last fetch — the same
+ * freshness a `rev-parse` has. A change-request listing resolves two tips per
+ * open request and the access gates resolve every ref they decide at; with a
+ * hundred open requests that was hundreds of forks per listing, each costing
+ * tens of milliseconds of the main thread on a server holding a large heap.
+ *
+ * What is read, in git's own order: a loose file under the common directory
+ * (a worktree shares `refs/` with the repository it belongs to), then
+ * `packed-refs`. `HEAD` and the per-worktree namespaces (`refs/worktree/`,
+ * `refs/bisect/`, `refs/rewritten/`) are a worktree's own: read loose from
+ * its git directory, never from the common directory, and never packed. A
+ * symbolic ref (`ref: refs/heads/main`) is followed. A tag is never decided
+ * here: its file may hold a tag object, and what that peels to is git's to
+ * say.
+ *
+ * The answer is one of three things, and the caller treats them differently:
+ * `{ sha }` is what git would answer too; `'missing'` means every file git
+ * would consult says there is no such ref, which is as authoritative as
+ * `rev-parse` answering nothing; `'unreadable'` means this reader could not
+ * decide — a repository it does not understand (one whose refs live in a
+ * reftable, say), a tag, a corrupt file, a name it refuses — and the caller
+ * asks git, which is authoritative. Never a guess: a read error is
+ * `'unreadable'`, not `'missing'`, so a flaky disk sends the caller to git
+ * rather than making a branch disappear.
+ *
+ * What the files guarantee about the object: git itself refuses to write a
+ * non-commit under `refs/heads/`, and `refs/remotes/origin/` mirrors the
+ * remote's `refs/heads/`, so a branch tip read here is a commit as surely
+ * as `rev-parse <branch>^{commit}` would make it one. A caller that holds
+ * an object id rather than a name, or a `<rev>^{...}` form, asks git.
+ */
+export type RefFileAnswer = { sha: string } | 'missing' | 'unreadable';
+
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const MAX_SYMREF_DEPTH = 5;
+const PER_WORKTREE = /^refs\/(?:worktree|bisect|rewritten)\//;
+
+/** A ref name this reader is willing to turn into a path under `.git`. */
+function isSafeRefName(ref: string): boolean {
+  if (ref === 'HEAD') return true;
+  if (!ref.startsWith('refs/')) return false;
+  if (!/^[A-Za-z0-9._\-/@+]+$/.test(ref)) return false;
+  return !ref.split('/').some((segment) => segment === '' || segment === '.' || segment === '..');
+}
+
+/**
+ * One resolution's view of the repository: the two directories, and the
+ * `packed-refs` table read at most once however many candidates a name
+ * tries — the table can grow with the history, and a name that is missing
+ * as itself consults it for every prefix.
+ */
+interface GitDirs {
+  /** The worktree's own git directory: `HEAD` lives here. */
+  gitDir: string;
+  /** Where `refs/` and `packed-refs` live: the repository, shared by every worktree. */
+  commonDir: string;
+  /** The `packed-refs` table, read on first need; null when it could not be read. */
+  packed?: Promise<Map<string, string> | null>;
+}
+
+async function gitDirsOf(repoDir: string): Promise<GitDirs | null> {
+  let gitDir: string | null;
+  try {
+    gitDir = await gitDirOf(repoDir);
+  } catch {
+    return null;
+  }
+  if (gitDir === null) return null;
+  let commonDir = gitDir;
+  try {
+    const pointer = (await fs.readFile(path.join(gitDir, 'commondir'), 'utf-8')).trim();
+    if (pointer) commonDir = path.resolve(gitDir, pointer);
+  } catch (err) {
+    if (!isAbsence(err)) return null;
+  }
+  // A repository whose refs live in a reftable (`extensions.refStorage`)
+  // keeps nothing this reader understands under `refs/` or in `packed-refs`:
+  // every name would read as missing. Not a repository for this reader.
+  try {
+    await fs.stat(path.join(commonDir, 'reftable'));
+    return null;
+  } catch (err) {
+    if (!isAbsence(err)) return null;
+  }
+  try {
+    if (/^\s*refstorage\s*=\s*reftable\s*$/im.test(await fs.readFile(path.join(commonDir, 'config'), 'utf-8'))) {
+      return null;
+    }
+  } catch (err) {
+    if (!isAbsence(err)) return null;
+  }
+  return { gitDir, commonDir };
+}
+
+/**
+ * `packed-refs`: `<sha> <name>` lines, `^<sha>` peel lines, `#` comments.
+ * Absent file → an empty table. A line that is none of those is a file this
+ * reader does not understand, and the whole table is null (unreadable): a
+ * record it skipped could be the one that was asked for.
+ */
+async function readPackedRefs(commonDir: string): Promise<Map<string, string> | null> {
+  let text: string;
+  try {
+    text = await fs.readFile(path.join(commonDir, 'packed-refs'), 'utf-8');
+  } catch (err) {
+    return isAbsence(err) ? new Map() : null;
+  }
+  const table = new Map<string, string>();
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('^')) {
+      if (!SHA.test(line.slice(1))) return null;
+      continue;
+    }
+    const space = line.indexOf(' ');
+    const sha = space < 0 ? '' : line.slice(0, space);
+    const name = space < 0 ? '' : line.slice(space + 1).trim();
+    if (!SHA.test(sha) || !name) return null;
+    table.set(name, sha);
+  }
+  return table;
+}
+
+/**
+ * The file at `<dir>/<relative>`, read as git reads a loose ref: a symbolic
+ * ref is followed, an object id is the answer, anything else is not decided.
+ */
+async function readLooseRef(dirs: GitDirs, dir: string, relative: string, depth: number): Promise<RefFileAnswer> {
+  let text: string;
+  try {
+    text = (await fs.readFile(path.join(dir, ...relative.split('/')), 'utf-8')).trim();
+  } catch (err) {
+    return isAbsence(err) ? 'missing' : 'unreadable';
+  }
+  if (text.startsWith('ref:')) {
+    const answer = await resolveIn(dirs, text.slice('ref:'.length).trim(), depth + 1);
+    // A symbolic ref whose target is gone is dangling, and git reports it
+    // as such; a packed entry under the symbolic ref's own name does not
+    // stand in for it. Git's to report, then.
+    return answer === 'missing' ? 'unreadable' : answer;
+  }
+  return SHA.test(text) ? { sha: text } : 'unreadable';
+}
+
+async function resolveIn(dirs: GitDirs, ref: string, depth: number): Promise<RefFileAnswer> {
+  if (depth > MAX_SYMREF_DEPTH) return 'unreadable';
+  if (!isSafeRefName(ref)) return 'unreadable';
+  // `HEAD` and the per-worktree namespaces (`refs/worktree/`, `refs/bisect/`,
+  // `refs/rewritten/`) are a worktree's own, kept loose in its git directory
+  // and never packed; everything else is the repository's.
+  const own = ref === 'HEAD' || PER_WORKTREE.test(ref);
+  const loose = await readLooseRef(dirs, own ? dirs.gitDir : dirs.commonDir, ref, depth);
+  if (loose !== 'missing') return decidedHere(ref, loose);
+  if (own) return 'missing';
+  const packed = await (dirs.packed ??= readPackedRefs(dirs.commonDir));
+  if (!packed) return 'unreadable';
+  const sha = packed.get(ref);
+  return sha ? decidedHere(ref, { sha }) : 'missing';
+}
+
+/**
+ * The files decide only where git itself guarantees the object is a commit:
+ * `HEAD` and `refs/heads/*`, which git refuses to point at anything else,
+ * and `refs/remotes/*`, fetched from a remote's `refs/heads/*` under the
+ * same refusal. Anything else that exists — a tag, a ref directly under
+ * `refs/` — may name a tree or a blob, which only git's `^{commit}` refuses,
+ * so it is git's to resolve. Anything that does not exist is as missing as
+ * any other ref, so a short name can move on to the branch git would find
+ * next.
+ */
+function decidedHere(ref: string, answer: RefFileAnswer): RefFileAnswer {
+  if (answer !== 'missing' && answer !== 'unreadable' && !commitGuaranteed(ref)) return 'unreadable';
+  return answer;
+}
+
+function commitGuaranteed(ref: string): boolean {
+  return ref === 'HEAD' || ref.startsWith('refs/heads/') || ref.startsWith('refs/remotes/');
+}
+
+/**
+ * The commit a full ref name (`refs/...`) or `HEAD` points at in the
+ * repository behind `repoDir` (a clone, or a worktree of one). See the module
+ * doc for the three answers and what each means to the caller.
+ *
+ * "Missing" is what `rev-parse` answers nothing for, and `rev-parse` tries
+ * the same prefixes for a full name as for a short one (`refs/heads/x` is
+ * also looked for as `refs/heads/refs/heads/x`), so a name that is missing
+ * as itself but present under a prefix is git's to resolve.
+ */
+export async function readRefSha(repoDir: string, ref: string): Promise<RefFileAnswer> {
+  const dirs = await gitDirsOf(repoDir);
+  if (!dirs) return 'unreadable';
+  const exact = await resolveIn(dirs, ref, 0);
+  if (exact !== 'missing') return exact;
+  for (const name of prefixedCandidates(ref)) {
+    if ((await resolveIn(dirs, name, 0)) !== 'missing') return 'unreadable';
+  }
+  return 'missing';
+}
+
+/**
+ * The names `git rev-parse` tries for `<name>` after `$GIT_DIR/<name>`
+ * itself, in git's order (gitrevisions(7)): `refs/<name>`,
+ * `refs/tags/<name>`, `refs/heads/<name>`, `refs/remotes/<name>`,
+ * `refs/remotes/<name>/HEAD`. The same for every spelling, a full `refs/...`
+ * name included.
+ */
+function prefixedCandidates(name: string): string[] {
+  return [`refs/${name}`, `refs/tags/${name}`, `refs/heads/${name}`, `refs/remotes/${name}`, `refs/remotes/${name}/HEAD`];
+}
+
+/**
+ * Every name `git rev-parse` tries for a spelling, in git's order: the
+ * spelling itself at `$GIT_DIR/<name>` (which for `HEAD` and a full
+ * `refs/...` name is the ref file), then the prefixed forms. Null for a
+ * spelling this reader does not resolve — an object id or its abbreviation,
+ * a `<rev>^{...}` or `@{...}` form, an empty or option-looking name — which
+ * the caller sends to git.
+ */
+function refNameCandidates(ref: string): string[] | null {
+  if (!ref || ref.startsWith('-')) return null;
+  if (/[\^~:@{}\\\s]/.test(ref)) return null;
+  if (/^[0-9a-f]{4,64}$/i.test(ref)) return null;
+  // `main-worktree/<ref>` and `worktrees/<name>/<ref>` reach another
+  // worktree's own refs (gitrevisions(7)): git's to resolve.
+  if (/^(?:main-worktree|worktrees)\//.test(ref)) return null;
+  return [ref, ...prefixedCandidates(ref)];
+}
+
+/**
+ * {@link readRefSha} for a name as a caller holds it (`main`, `origin/main`,
+ * `HEAD`, `refs/heads/main`): the first of git's candidates that resolves,
+ * starting where git starts, at `$GIT_DIR/<name>` itself. Whatever is found
+ * there (`MERGE_HEAD`, `FETCH_HEAD`, `AUTO_MERGE`, which may name a tree) is
+ * git's to resolve; only its absence lets the `refs/` candidates be read.
+ * `'missing'` only when every candidate is missing; `'unreadable'` as soon
+ * as one cannot be decided, because the undecided one might be the one git
+ * would pick.
+ */
+export async function readRevSha(repoDir: string, rev: string): Promise<RefFileAnswer> {
+  const candidates = refNameCandidates(rev);
+  if (!candidates) return 'unreadable';
+  const dirs = await gitDirsOf(repoDir);
+  if (!dirs) return 'unreadable';
+  for (const name of candidates) {
+    const answer = name === rev ? await resolveAsItself(dirs, rev) : await resolveIn(dirs, name, 0);
+    if (answer !== 'missing') return answer;
+  }
+  return 'missing';
+}
+
+/**
+ * Git's first step for any spelling: `$GIT_DIR/<name>`. For `HEAD` and a
+ * full `refs/...` name that is the ref itself, read as such. For anything
+ * else it is a pseudoref (`MERGE_HEAD`, `AUTO_MERGE`, which may name a
+ * tree), and whatever exists there is git's to resolve.
+ */
+async function resolveAsItself(dirs: GitDirs, rev: string): Promise<RefFileAnswer> {
+  if (rev === 'HEAD' || rev.startsWith('refs/')) return resolveIn(dirs, rev, 0);
+  if (!isSafeRefName(`refs/${rev}`)) return 'unreadable';
+  try {
+    await fs.stat(path.join(dirs.gitDir, ...rev.split('/')));
+    return 'unreadable';
+  } catch (err) {
+    return isAbsence(err) ? 'missing' : 'unreadable';
+  }
+}

package/src/modules/plugins/__tests__/join-request-jobs.service.test.ts

@@ -1,11 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { DEFAULT_BRANCH, joinBranchFor } from '@bevel-software/platform-shared';
-import {
-  PluginJoinRequestJobs,
-  JoinRequestNotReadyError,
-  type JoinRequestJobsDeps,
-  CLAIM_STALE_AFTER_MS,
-} from '../join-request-jobs.service.js';
+import { DrizzleQueryError } from 'drizzle-orm';
+import { PluginJoinRequestJobs, JoinRequestNotReadyError, type JoinRequestJobsDeps } from '../index.js';
+// The claim window is not part of the module's surface: a test that moves
+// the clock past it reads the number the service itself uses.
+import { CLAIM_STALE_AFTER_MS } from '../join-request-jobs.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { FakeJoinRequestStore } from './fake-join-request-store.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -146,6 +145,48 @@ describe('PluginJoinRequestJobs', () => {
     expect(row.failureReason).not.toContain('ghp_secret');
   });
 
+  it("logs a database failure as the database's reason, and shows the requester one stable sentence", async () => {
+    const h = harness();
+    // What Drizzle throws: its own error class, the SQL in the message, the
+    // driver's error as the cause.
+    h.workflow.openChangeRequest.mockRejectedValue(
+      new DrizzleQueryError(
+        'insert into "change_requests" ("id", "number", "title", "body", "source_branch", "target_branch", "author_id", "status", "created_at", "updated_at") values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)',
+        [],
+        new Error('relation "change_requests" does not exist'),
+      ),
+    );
+    await h.jobs.start(pendingRow(h.store));
+
+    // The operator gets the reason, not the wrapper's cut-off SQL…
+    const logged = consoleError.mock.calls.map((c) => String(c[0]));
+    // (`printable` renders the reason as a JSON string, so its own quotes come escaped.)
+    expect(logged).toContainEqual(expect.stringMatching(/failed: "relation \\"change_requests\\" does not exist"/));
+    expect(logged.some((l) => l.includes('Failed query'))).toBe(false);
+    // …and the requester's card names no table.
+    const [row] = h.store.all();
+    expect(row.status).toBe('failed');
+    expect(row.failureReason).toBe('the request could not be recorded; an admin can find the reason in the server log');
+  });
+
+  it("shows the requester a wrapped failure's own words when it is not the database's", async () => {
+    const h = harness();
+    // The git work failing behind a wrapper of its own: the cause is what is
+    // logged, and what the requester reads, credentials stripped — the
+    // database's stable sentence would hide the detail they can act on.
+    h.workflow.openChangeRequest.mockRejectedValue(
+      new Error('opening the change request failed', {
+        cause: new Error('fatal: unable to access https://x:ghp_secret@github.com/acme/kb: could not resolve host'),
+      }),
+    );
+    await h.jobs.start(pendingRow(h.store));
+    const [row] = h.store.all();
+    expect(row.status).toBe('failed');
+    expect(row.failureReason).toContain('unable to access');
+    expect(row.failureReason).not.toContain('ghp_secret');
+    expect(row.failureReason).not.toContain('could not be recorded');
+  });
+
   it('fails the record rather than throwing when the plugin is gone', async () => {
     const h = harness({ target: async () => null });
     await expect(h.jobs.start(pendingRow(h.store))).resolves.toBeUndefined();
@@ -524,6 +565,32 @@ describe('PluginJoinRequestJobs', () => {
     expect(h.workflow.openChangeRequest).not.toHaveBeenCalled();
   });
 
+  it("a sweep that cannot read the table logs the database's reason, not the wrapper's cut-off SQL", async () => {
+    vi.useFakeTimers();
+    const warned = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const h = harness();
+      // What Drizzle throws: its own error class, the SQL in the message, the driver's error underneath.
+      const wrapped = new DrizzleQueryError(
+        'select "id", "requester_email", "requester_email_bidx", "requester_name", "plugin_key", "status", "failure_reason", "change_request_number", "claimed_at", "claim_token", "created_at" from "plugin_join_requests" where status = $1',
+        [],
+        new Error('Cannot use a pool after calling end on the pool'),
+      );
+      h.store.pending = async () => {
+        throw wrapped;
+      };
+      h.jobs.startSweeping(1000);
+      await vi.advanceTimersByTimeAsync(0);
+      h.jobs.stopSweeping();
+      const lines = warned.mock.calls.map((c) => String(c[0]));
+      expect(lines).toHaveLength(1);
+      expect(lines[0]).toContain('could not look at the join requests still owed: "Cannot use a pool after calling end on the pool"');
+      expect(lines[0]).not.toContain('Failed query');
+    } finally {
+      warned.mockRestore();
+    }
+  });
+
   it('proceeds past a createBranch failure only when the branch is really there', async () => {
     const h = harness();
     const branch = joinBranchFor(ALI, 'Finance');

package/src/modules/plugins/__tests__/teams.routes.test.ts

@@ -4,6 +4,7 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 
 import type { IAccessControl } from '../../access/access-control.interface.js';
+import { AccessControlService } from '../../access/access-control.service.js';
 import type { ISkillService, SkillSummary } from '../../skills/skills.contract.js';
 import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
 import type { IPluginIndexService, PluginCatalogEntry } from '../plugins.contract.js';
@@ -62,6 +63,10 @@ interface HarnessOpts {
   /** What the org-wide `everyone` principal reads. */
   everyone?: string[];
   email?: string | null;
+  /** Whether the caller is an admin, who is shown every group. Defaults to true. */
+  admin?: boolean;
+  /** The groups the caller is a member of, which is all a non-admin is shown. */
+  memberOf?: string[];
 }
 
 /** The org-wide entry every answer opens with — empty unless `everyone` says otherwise. */
@@ -82,6 +87,12 @@ async function harness(opts: HarnessOpts = {}) {
       opts.team && group in opts.team ? tableVerdict(opts.team[group], paths) : null,
     ),
     canReadAsEveryoneBatch: vi.fn(async (_w: string, paths: string[]) => tableVerdict(opts.everyone, paths)),
+    holdsAdminRootWrite: vi.fn(async () => opts.admin ?? true),
+    groupsOfUser: vi.fn(async () => opts.memberOf ?? []),
+    // The real policy over the two stubs above: who sees which group is the
+    // resolver's one answer, not something a route (or this double) decides.
+    visibleGroups: (wsId: string, email: string, groups: readonly string[]) =>
+      AccessControlService.prototype.visibleGroups.call(accessControl, wsId, email, groups),
   } as unknown as IAccessControl;
   const index = { catalog: async () => CATALOG, invalidate: () => undefined } as IPluginIndexService;
   const skills = { listSkills: async () => SKILLS } as unknown as ISkillService;
@@ -242,6 +253,50 @@ describe('GET /api/teams', () => {
     );
   });
 
+  it("shows someone who is not an admin only the groups they are in, never another group's name", async () => {
+    const h = await harness({
+      groups: ['Sales Team', 'Finance Team'],
+      caller: EVERYTHING,
+      team: {
+        'Sales Team': ['Plugins/GTM', 'Skills/Sales/outreach/SKILL.md', 'Plugins/GTM/mcp.json'],
+        'Finance Team': ['Plugins/Finance', 'Skills/Finance/ledger/SKILL.md', 'Plugins/Finance/books.tool'],
+      },
+      admin: false,
+      memberOf: ['Sales Team'],
+    });
+    const res = await h.get();
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      teams: [
+        NOTHING_ORG_WIDE,
+        { name: 'Sales Team', plugins: ['gtm'], skills: ['outreach'], tools: ['hubspot'] },
+      ],
+    });
+    // A group that is not listed is not asked about either.
+    expect(h.accessControl.canReadAsGroupBatch).not.toHaveBeenCalledWith(
+      expect.anything(),
+      'Finance Team',
+      expect.anything(),
+    );
+  });
+
+  it('shows someone in no group, who is not an admin, Everyone alone', async () => {
+    const h = await harness({ groups: ['Sales Team'], caller: EVERYTHING, team: { 'Sales Team': [] }, admin: false });
+    expect(await (await h.get()).json()).toEqual({ teams: [NOTHING_ORG_WIDE] });
+  });
+
+  it('shows an admin every group, including ones they are not in', async () => {
+    const h = await harness({
+      groups: ['Sales Team', 'Finance Team'],
+      caller: EVERYTHING,
+      team: { 'Sales Team': [], 'Finance Team': [] },
+      admin: true,
+      memberOf: [],
+    });
+    const body = (await (await h.get()).json()) as { teams: { name: string }[] };
+    expect(body.teams.map((t) => t.name)).toEqual(['Everyone', 'Sales Team', 'Finance Team']);
+  });
+
   it('is 401 without a caller', async () => {
     const h = await harness({ email: null });
     expect((await h.get()).status).toBe(401);

package/src/modules/plugins/join-request-jobs.service.ts

@@ -4,6 +4,7 @@ import {
   type ChangeRequestState,
   type IWorkflowService,
 } from '@bevel-software/platform-shared';
+import { DrizzleQueryError } from 'drizzle-orm';
 import { spliceGrant } from '../access-model/access-splice.js';
 import { sanitizeError } from '../workflow/sanitize-error.js';
 import { logger } from '../../shared/logging.js';
@@ -358,12 +359,12 @@ export class PluginJoinRequestJobs {
    */
   startSweeping(intervalMs: number = SWEEP_INTERVAL_MS): void {
     void this.sweep().catch((err: unknown) => {
-      log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(err))}`);
+      log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(underlying(err)))}`);
     });
     if (this.sweepTimer) return;
     this.sweepTimer = setInterval(() => {
       void this.sweep().catch((err: unknown) => {
-        log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(err))}`);
+        log.warn(`could not look at the join requests still owed: ${loggable(sanitizeError(underlying(err)))}`);
       });
     }, intervalMs);
     // Never a reason for the process to stay alive: every row is durable, and
@@ -398,7 +399,7 @@ export class PluginJoinRequestJobs {
     // wrap the whole attempt: the claim has to be refreshed for as long as
     // the work runs, and the work is the part that can take minutes.
     const live = await this.store.claim(record.id, CLAIM_STALE_AFTER_MS).catch((err: unknown) => {
-      log.warn(`could not claim a join request: ${loggable(sanitizeError(err))}`);
+      log.warn(`could not claim a join request: ${loggable(sanitizeError(underlying(err)))}`);
       return null;
     });
     if (!live) {
@@ -426,7 +427,7 @@ export class PluginJoinRequestJobs {
         if (!still) held = false;
         return still ? 'held' : 'lost';
       } catch (err: unknown) {
-        log.warn(`could not refresh a join-request claim: ${loggable(sanitizeError(err))}`);
+        log.warn(`could not refresh a join-request claim: ${loggable(sanitizeError(underlying(err)))}`);
         return 'unknown';
       }
     };
@@ -453,7 +454,10 @@ export class PluginJoinRequestJobs {
         if (state !== 'held') throw new ClaimLostError(state);
       });
     } catch (err) {
-      const reason = sanitizeError(err);
+      // The cause when there is one (see `underlying`), for the log; a
+      // database's reason, where a wrapper's cut-off column list is not.
+      const cause = underlying(err);
+      const reason = sanitizeError(cause);
       // `pluginKey` is a persisted folder path, so it is escaped before it
       // reaches a log line: a folder carrying control characters could
       // otherwise write newlines of its own into the log.
@@ -473,22 +477,31 @@ export class PluginJoinRequestJobs {
         // claim held by a process that never really started.
         log.warn(`join request for ${key} postponed: ${loggable(reason)}`);
         await this.store.release(record.id, live.claimToken).catch((releaseErr: unknown) => {
-          log.warn(`could not release that claim: ${loggable(sanitizeError(releaseErr))}`);
+          log.warn(`could not release that claim: ${loggable(sanitizeError(underlying(releaseErr)))}`);
         });
         return;
       }
       log.error(`join request for ${key} failed: ${loggable(reason)}`);
+      // What the requester reads on their card. The git work's own words
+      // are theirs to see (credentials stripped); a database's reason is
+      // not — it names tables and columns and is for the operator, who has
+      // it in the line above — so a database failure is recorded in one
+      // stable sentence. The database's failures are the ones the query
+      // layer wraps (`DrizzleQueryError`, its cause the driver's error);
+      // any other wrapped error keeps its own sanitised words, which may be
+      // what the requester needs to act on.
+      const shown = err instanceof DrizzleQueryError ? DATABASE_FAILURE_REASON : reason;
       await this.store
         // Named with the token, so this lands only if the row is still this
         // process's. A worker that overran the window and had its row taken
         // writes nothing here rather than stamping its failure on the attempt
         // that replaced it — which would show the requester a failure for
         // work that is, at that moment, succeeding.
-        .markFailed(record.id, live.claimToken, reason)
+        .markFailed(record.id, live.claimToken, shown)
         // Nothing left to do if even that write fails: the row stays
         // `pending` and the next boot's sweep tries the whole thing again.
         .catch((writeErr: unknown) => {
-          log.error(`could not record that failure: ${loggable(sanitizeError(writeErr))}`);
+          log.error(`could not record that failure: ${loggable(sanitizeError(underlying(writeErr)))}`);
         });
     } finally {
       held = false;
@@ -669,6 +682,30 @@ function loggable(reason: string): string {
   return printable(reason);
 }
 
+/**
+ * The error behind a wrapped one. Drizzle reports a failed query as its own
+ * error whose message is the SQL and whose `cause` is the database's reason;
+ * the sanitizer caps a message at a couple of hundred characters, so logging
+ * the wrapper showed a cut-off column list and never the reason. The reason
+ * is what every LOG line this service writes needs — "the pool has been
+ * ended", "relation does not exist" — the sweep's warning, the claim and
+ * heartbeat warnings, the failure line. The requester's card is the one
+ * place it does not go: a wrapped failure is recorded there as
+ * `DATABASE_FAILURE_REASON`, since a table name is the operator's to read.
+ * An error with no cause (git's, the claim's own) is reported as it is.
+ */
+function underlying(err: unknown): unknown {
+  const cause = typeof err === 'object' && err !== null ? (err as { cause?: unknown }).cause : undefined;
+  return cause instanceof Error ? cause : err;
+}
+
+/**
+ * The sentence a requester's card carries when the database, not the git
+ * work, refused the request: stable, and naming no table or column. The
+ * database's own words go to the server log beside it.
+ */
+const DATABASE_FAILURE_REASON = 'the request could not be recorded; an admin can find the reason in the server log';
+
 /** Node's "there is no such file" errors, and only those. */
 function isFileAbsent(err: unknown): boolean {
   const code = (err as NodeJS.ErrnoException | null)?.code;

package/src/modules/plugins/teams.routes.ts

@@ -37,6 +37,10 @@ import type { IPluginIndexService, PluginCatalogEntry } from './plugins.contract
  * what `read: everyone` (or a public plugin) reaches. Same slice, same
  * caller gate, asked of the resolver as `canReadAsEveryoneBatch`. The name
  * cannot collide with a group's: `everyone` is reserved by the grammar.
+ *
+ * The groups listed after it are every group for an admin, and only the
+ * caller's own groups for anyone else (`groupsOfUser`), so the lens never
+ * names a group the caller has no part in.
  */
 export interface TeamAccess {
   name: string;
@@ -110,10 +114,19 @@ export function createTeamsRoutes(
         };
       };
 
+      // Which groups to list: the resolver's one answer to who sees which
+      // group (every group for an admin, only their own for anyone else), the
+      // same the share dialog offers and a grant may name. A group's NAME is
+      // information too: a deployment that gives each client, author or
+      // customer a group of their own would otherwise show every member the
+      // whole roster, even though the slices of groups they are not in come
+      // back empty.
+      const listed = await accessControl.visibleGroups(wsId, email, groups);
+
       const teams: TeamAccess[] = [
         slice(EVERYONE_TEAM, await accessControl.canReadAsEveryoneBatch(wsId, probes)),
       ];
-      for (const name of groups) {
+      for (const name of listed) {
         const team = await accessControl.canReadAsGroupBatch(wsId, name, probes);
         if (team === null) continue; // gone between the two reads — nothing to say
         teams.push(slice(name, team));

package/src/modules/settings/__tests__/setup.routes.layout-phase.test.ts

@@ -10,13 +10,13 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
-import { KbStartupRunner } from '../../workspace/startup/kb-startup-runner.js';
 import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { defaultKbTemplateDir } from '../../../assets.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import { newKbStartupRunner } from '../../../__tests__/workspace-service.js';
 
 /**
  * The completing save and the REAL initialization phase, wired the way the
@@ -105,7 +105,7 @@ function boot() {
   // it: the completing save applies the admin's names to it, and the step
   // reads them from it when the phase runs.
   const kb = testKbContext();
-  const runner = new KbStartupRunner({
+  const runner = newKbStartupRunner({
     gitRunner: new NodeGitRunner(),
     kbRepoUrl: () => upstream,
     workspacesRoot: path.join(root, 'workspaces'),

package/src/modules/settings/__tests__/setup.routes.managed-phase.test.ts

@@ -12,7 +12,6 @@ import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
 import { ManagedRepository } from '../managed-repository.js';
 import { RepositorySource } from '../repository-source.js';
-import { KbStartupRunner } from '../../workspace/startup/kb-startup-runner.js';
 import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
@@ -20,6 +19,7 @@ import { defaultKbTemplateDir } from '../../../assets.js';
 import type { Database } from '../../database/connection.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import type { KbContext } from '../../../shared/kb-context.js';
+import { newKbStartupRunner } from '../../../__tests__/workspace-service.js';
 
 /**
  * A repository the deployment keeps, and the REAL startup phase, wired the
@@ -89,7 +89,7 @@ function boot(kb: KbContext) {
   const gitRunner = new NodeGitRunner(60_000, source.credentials);
   const workspacesRoot = path.join(root, 'workspaces');
   const setAsideRoot = path.join(root, 'backups', 'replaced-working-copies');
-  const runner = new KbStartupRunner({
+  const runner = newKbStartupRunner({
     gitRunner,
     kbRepoUrl: () => source.url(),
     workspacesRoot,