@bevel-software/platform-core-backend 0.4.1 → 0.5.0

package/src/modules/auth/__tests__/onboarding-done.route.test.ts

@@ -0,0 +1,147 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createAuthRoutes } from '../auth.routes.js';
+import type { AuthService } from '../auth.service.js';
+
+/**
+ * POST /auth/onboarding-done — the one write behind the welcome page's Done
+ * AND the reminder pill's ×. The contract worth pinning:
+ *
+ *  - it acts on the AUTHENTICATED user (req.userId), never on a body param —
+ *    there is no way to conclude someone else's onboarding;
+ *  - it REQUIRES the caller to name the account it means, and refuses anything
+ *    that is not an exact match — including a claim that is absent or not a
+ *    string, since "said nothing" is not the same as "meant this account";
+ *  - it is idempotent from the caller's view (the service call is an UPDATE
+ *    to the value it may already have), so both buttons can fire it blind;
+ *  - unauthenticated callers never reach the service.
+ */
+
+const USER_ID = 'user-123';
+
+let server: HttpServer | null = null;
+
+afterEach(() => {
+  server?.close();
+  server = null;
+  // In a hook, not at the end of a test body: a failing assertion would
+  // otherwise leave a `console.error` spy installed and silence the rest of
+  // the file.
+  vi.restoreAllMocks();
+});
+
+/**
+ * Mount the auth router on a throwaway port with a stand-in auth middleware,
+ * and return its base URL. `authed: false` makes that middleware reject like
+ * the real one, which is how the "never reaches the service" case is proved
+ * rather than assumed.
+ */
+function listen(service: Pick<AuthService, 'markOnboardingDone'>, authed = true): string {
+  const app = express();
+  app.use(express.json());
+  const middleware: express.RequestHandler = (req, res, next) => {
+    if (!authed) {
+      res.status(401).json({ error: 'Unauthorized' });
+      return;
+    }
+    req.userId = USER_ID;
+    next();
+  };
+  app.use('/api', createAuthRoutes(service as AuthService, middleware));
+  server = app.listen(0);
+  const { port } = server.address() as AddressInfo;
+  return `http://127.0.0.1:${port}`;
+}
+
+describe('POST /auth/onboarding-done', () => {
+  it('marks the caller done when the claimed account matches the token', async () => {
+    const markOnboardingDone = vi.fn().mockResolvedValue(undefined);
+    const base = listen({ markOnboardingDone });
+    const res = await fetch(`${base}/api/auth/onboarding-done`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ userId: USER_ID }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+    expect(markOnboardingDone).toHaveBeenCalledTimes(1);
+    expect(markOnboardingDone).toHaveBeenCalledWith(USER_ID);
+  });
+
+  /**
+   * A caller that names no account has not expressed the intent this route
+   * needs. Accepting `{}` as consent would reopen the stale-tab hole from the
+   * other side — an old or malformed client posting an empty body while
+   * rendering account A would conclude account B's onboarding unopposed — so
+   * the absent claim is refused exactly like a wrong one.
+   */
+  it('refuses a caller that claims nothing, and writes nothing', async () => {
+    const markOnboardingDone = vi.fn();
+    const base = listen({ markOnboardingDone });
+    const res = await fetch(`${base}/api/auth/onboarding-done`, { method: 'POST' });
+    expect(res.status).toBe(409);
+    expect(markOnboardingDone).not.toHaveBeenCalled();
+  });
+
+  // Same rule for a claim of the wrong TYPE: only an exact string match is
+  // consent, so a number that happens to stringify to the user id is not.
+  it('refuses a claim that is not a string', async () => {
+    const markOnboardingDone = vi.fn();
+    const base = listen({ markOnboardingDone });
+    const res = await fetch(`${base}/api/auth/onboarding-done`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ userId: { toString: () => USER_ID } }),
+    });
+    expect(res.status).toBe(409);
+    expect(markOnboardingDone).not.toHaveBeenCalled();
+  });
+
+  /**
+   * The stale-tab case. Two accounts share one bearer-token key in
+   * localStorage: a tab still rendering A, after B signs in elsewhere, sends
+   * A's intent with B's token. Concluding B's onboarding there would be
+   * irreversible — there is no API to undo it — so the mismatch is refused
+   * and NOTHING is written.
+   */
+  it('refuses when the claimed account is not the token holder, and writes nothing', async () => {
+    const markOnboardingDone = vi.fn();
+    const base = listen({ markOnboardingDone });
+    const res = await fetch(`${base}/api/auth/onboarding-done`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ userId: 'a-different-account' }),
+    });
+    expect(res.status).toBe(409);
+    expect(markOnboardingDone).not.toHaveBeenCalled();
+  });
+
+  it('never reaches the service unauthenticated', async () => {
+    const markOnboardingDone = vi.fn();
+    const base = listen({ markOnboardingDone }, false);
+    const res = await fetch(`${base}/api/auth/onboarding-done`, { method: 'POST' });
+    expect(res.status).toBe(401);
+    expect(markOnboardingDone).not.toHaveBeenCalled();
+  });
+
+  // A failed write must not be reported as success — and must not narrate the
+  // database to the client either. Same rule as /auth/login.
+  it('reports a failed write as a generic 500, keeping the detail server-side', async () => {
+    const detail = 'connection to 10.0.0.4:5432 refused';
+    const markOnboardingDone = vi.fn().mockRejectedValue(new Error(detail));
+    const logged = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const base = listen({ markOnboardingDone });
+    const res = await fetch(`${base}/api/auth/onboarding-done`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ userId: USER_ID }),
+    });
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe('Could not save that');
+    expect(body.error).not.toContain(detail);
+    expect(logged).toHaveBeenCalledWith('Onboarding-done error:', detail);
+  });
+});

package/src/modules/auth/auth.routes.ts

@@ -65,8 +65,19 @@ export function createAuthRoutes(
       return;
     }
     const ip = clientIp(req);
+    // IP budget FIRST, and it returns before the pair key exists. Order is the
+    // whole guard here: `consume` inserts an entry for any key it has not seen,
+    // and that entry lives for the full 15-minute window. Consuming the pair
+    // budget first therefore let an address that was ALREADY over its IP limit
+    // keep minting `ip|email` entries, one per attacker-chosen email — and
+    // since `consume` scans the whole map on every call, that growth is also a
+    // latency tax on every legitimate login for the rest of the window.
+    if (!loginIpLimiter.consume(ip)) {
+      res.status(429).json({ error: 'Too many attempts. Try again later.' });
+      return;
+    }
     const pairKey = `${ip}|${email.trim().toLowerCase()}`;
-    if (!loginPairLimiter.consume(pairKey) || !loginIpLimiter.consume(ip)) {
+    if (!loginPairLimiter.consume(pairKey)) {
       res.status(429).json({ error: 'Too many attempts. Try again later.' });
       return;
     }
@@ -136,6 +147,44 @@ export function createAuthRoutes(
     }
   });
 
+  // POST /api/auth/onboarding-done — conclude the connect-your-agent
+  // onboarding for the caller (protected). One-way and idempotent; the
+  // welcome page's Done and the reminder pill's × are its two callers.
+  router.post('/auth/onboarding-done', authMiddleware, async (req, res) => {
+    try {
+      // The caller must state WHICH account it believes it is concluding, and
+      // anything but an exact match is refused rather than applied to the
+      // token's owner.
+      //
+      // The bearer token lives in one shared localStorage key, so two accounts
+      // in two tabs share it: a stale tab still rendering A, after B signs in
+      // elsewhere, would otherwise send A's intent with B's token and
+      // irreversibly conclude B's onboarding — an account B has no way to
+      // reopen. `userId` is an assertion about intent, never an authorization:
+      // the write still targets `req.userId` alone.
+      //
+      // REQUIRED, not merely checked-when-present. Treating an absent claim as
+      // consent reopens the same hole from the other side: a stale or malformed
+      // client that posts `{}` while rendering A would conclude B's onboarding
+      // unopposed. A caller that cannot name the account it means has not
+      // expressed the intent this route needs.
+      const claimed = (req.body as { userId?: unknown } | undefined)?.userId;
+      if (typeof claimed !== 'string' || claimed !== req.userId) {
+        res.status(409).json({ error: 'Session changed — sign in again' });
+        return;
+      }
+      await authService.markOnboardingDone(req.userId!);
+      res.json({ ok: true });
+    } catch (error) {
+      // Logged in full, returned generic — same rule as `/auth/login` above.
+      // A raw driver message here would hand an unauthenticated-adjacent
+      // caller the schema, the host, or the connection string.
+      const msg = error instanceof Error ? error.message : 'Unknown error';
+      console.error('Onboarding-done error:', msg);
+      res.status(500).json({ error: 'Could not save that' });
+    }
+  });
+
   // GET /api/auth/me — validate stored JWT, return user info (protected)
   router.get('/auth/me', authMiddleware, async (req, res) => {
     try {

package/src/modules/auth/auth.service.ts

@@ -27,24 +27,46 @@ function decoyHash(): Promise<string> {
   return decoyHashPromise;
 }
 
+/**
+ * Narrow a `users` row down to what a client is allowed to see. One place
+ * rather than three inline object literals, so a column added to the table is
+ * never accidentally shipped to the browser — and so every session-issuing
+ * path returns the same shape.
+ */
 function toAuthUser(user: {
   id: string;
   email: string;
   name: string;
   avatarUrl: string | null;
+  onboardingDone: boolean;
 }): AuthUser {
   return {
     id: user.id,
     email: user.email,
     name: user.name,
     avatarUrl: user.avatarUrl ?? undefined,
+    onboardingDone: user.onboardingDone,
   };
 }
 
+/**
+ * What this service needs from the deployment's configuration, and nothing
+ * more. Narrowed from `CoreConfig` so the caller can supply a value that is
+ * RESOLVED rather than read straight off the environment — the SSO domain
+ * allow-list is settable from the setup screen, and taking the whole config
+ * object would have quietly pinned it to the env-only half.
+ */
+export interface AuthConfig {
+  jwtSecret: string;
+  adminEmail: string;
+  adminPassword: string;
+  allowedEmailDomains: string[];
+}
+
 export class AuthService {
   constructor(
     private readonly db: Database,
-    private readonly config: CoreConfig,
+    private readonly config: AuthConfig,
   ) {}
 
   /**
@@ -71,7 +93,6 @@ export class AuthService {
     if (!EMAIL_REGEX.test(normalizedEmail)) {
       throw new Error('Invalid credentials');
     }
-    this.assertAllowedDomain(normalizedEmail);
 
     const provided = password ?? '';
     const isEnvAdmin =
@@ -139,7 +160,6 @@ export class AuthService {
     if (!EMAIL_REGEX.test(normalizedEmail)) {
       throw new Error('Invalid email');
     }
-    this.assertAllowedDomain(normalizedEmail);
     this.assertPasswordPolicy(password);
     const suppliedName = (name ?? '').trim();
     const displayName = suppliedName || normalizedEmail.split('@')[0] || normalizedEmail;
@@ -280,21 +300,31 @@ export class AuthService {
 
     if (!user) return null;
 
-    return {
-      id: user.id,
-      email: user.email,
-      name: user.name,
-      avatarUrl: user.avatarUrl ?? undefined,
-    };
+    return toAuthUser(user);
   }
 
   /**
-   * Whether `email` passes the optional `ALLOWED_EMAIL_DOMAINS` guard. Returns
-   * true when no guard is configured (the default). Matches the email's domain
-   * exactly or as a subdomain, so `bevel.software` admits `a@bevel.software`
-   * and `a@eu.bevel.software` but not `a@notbevel.software`. When a guard IS
-   * configured, a missing/blank email fails closed. Exposed so non-login
-   * surfaces (the embed panel) can apply the same gate.
+   * Conclude the connect-your-agent onboarding for `userId`. Idempotent by
+   * construction (an UPDATE to the value it already has), so the welcome
+   * page's Done and the reminder pill's dismiss can both call it without
+   * coordinating. There is deliberately no way back to false over the API:
+   * "not onboarded again" is not a state a user can be put in.
+   */
+  async markOnboardingDone(userId: string): Promise<void> {
+    await this.db
+      .update(users)
+      .set({ onboardingDone: true, updatedAt: new Date() })
+      .where(eq(users.id, userId));
+  }
+
+  /**
+   * Whether `email` passes the optional `ALLOWED_EMAIL_DOMAINS` guard — the
+   * SSO allow-list. Returns true when no guard is configured (the default).
+   * Matches the email's domain exactly or as a subdomain, so `bevel.software`
+   * admits `a@bevel.software` and `a@eu.bevel.software` but not
+   * `a@notbevel.software`. When a guard IS configured, a missing/blank email
+   * fails closed. Exposed so non-login surfaces (the embed panel) can apply
+   * the same gate.
    */
   isEmailDomainAllowed(email: string): boolean {
     const allowed = this.config.allowedEmailDomains;
@@ -305,9 +335,17 @@ export class AuthService {
   }
 
   /**
-   * Enforce {@link isEmailDomainAllowed} at the login paths. No-op when the
-   * guard is unset. Expects an already-normalized (trimmed, lower-cased,
+   * Enforce {@link isEmailDomainAllowed} on SSO sign-in. No-op when the guard
+   * is unset. Expects an already-normalized (trimmed, lower-cased,
    * regex-validated) email.
+   *
+   * SSO ONLY, deliberately. It exists because SSO auto-provisions — an account
+   * appears the first time the issuer authenticates someone, with nobody
+   * approving it. The other two entry points do not have that property: an
+   * admin-created account is vetted by the act of creating it, and password
+   * login can only reach an account that already exists. Applying it there
+   * gated nothing, and could lock out a bootstrap admin whose own address sits
+   * outside the list.
    */
   private assertAllowedDomain(normalizedEmail: string): void {
     if (!this.isEmailDomainAllowed(normalizedEmail)) {

package/src/modules/database/core-schema.ts

@@ -24,6 +24,19 @@ export const users = pgTable('users', {
    * until an admin (or the user, from their Account page) sets one.
    */
   passwordHash: text('password_hash'),
+  /**
+   * The one onboarding fact the server keeps: has this person concluded the
+   * connect-your-agent setup (the welcome page's Done, or the reminder
+   * pill's dismiss — one field, both doors). False drives the pill in every
+   * browser the account signs into; true ends it everywhere at once, which
+   * is exactly what localStorage could not promise.
+   *
+   * Existing accounts are NOT backfilled to true: the column simply defaults
+   * to false, so everyone is greeted once and anyone already connected
+   * clicks Done. A plain `ADD COLUMN` is worth more than the branching a
+   * backfill would need, and being shown the setup once costs a click.
+   */
+  onboardingDone: boolean('onboarding_done').default(false).notNull(),
   createdAt: timestamp('created_at').defaultNow().notNull(),
   updatedAt: timestamp('updated_at').defaultNow().notNull(),
 });
@@ -435,3 +448,36 @@ export const sessionOntologyTouches = pgTable('session_ontology_touches', {
   // Backstop sweep of abandoned runs via `touched_at < cutoff`.
   byTouchedAt: index('session_ontology_touches_by_touched_at').on(t.touchedAt),
 }));
+
+/**
+ * Deployment-wide settings an admin can change from the setup screen, so a
+ * fresh install does not have to be told everything through the environment
+ * before it will boot.
+ *
+ * KEY/VALUE rather than typed columns: the set grows (the KB remote first, the
+ * branch model after it), and a migration per setting buys nothing when every
+ * value arrives from a text input anyway. Validation lives with the setting's
+ * definition, not in the column type.
+ *
+ * The ENVIRONMENT still wins over anything stored here — a row is a fallback,
+ * never an override. That is what lets an existing deployment adopt this table
+ * with no behaviour change, and stops a value typed once in a browser from
+ * quietly outranking the infrastructure config that is under review.
+ */
+export const deploymentSettings = pgTable('deployment_settings', {
+  key: text('key').primaryKey(),
+  /** Ciphertext when `encrypted`, plain text otherwise. */
+  value: text('value').notNull(),
+  /**
+   * Whether `value` is sealed with the secrets key. Stored per row rather than
+   * inferred from the key name so a reader never has to know the catalogue to
+   * know whether it is holding a secret.
+   */
+  encrypted: boolean('encrypted').default(false).notNull(),
+  /**
+   * Who last wrote it. `set null` on delete rather than cascade: erasing a
+   * person must not take the deployment's configuration with them.
+   */
+  updatedBy: uuid('updated_by').references(() => users.id, { onDelete: 'set null' }),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});

package/src/modules/groups/__tests__/group-index.service.test.ts

@@ -0,0 +1,225 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { GroupIndexService } from '../groups.service.js';
+import { workspaceIdForBranch } from '../../workspace/workspace.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { ISkillService, SkillSummary } from '../../skills/skills.contract.js';
+import type { IToolManualService, ToolManualSummary } from '../../tool-manuals/tool-manuals.contract.js';
+
+const KB_DIR = 'knowledge-base';
+const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+
+const OLGA = { name: 'Olga Ivanova', email: 'olga@bevel.software' };
+
+function skills(...paths: string[]): SkillSummary[] {
+  return paths.map((path) => ({ name: path.split('/').pop()!, description: '', path }));
+}
+
+function tools(...paths: string[]): ToolManualSummary[] {
+  return paths.map((path) => {
+    const name = path.split('/').pop()!.replace(/\.tool$/, '');
+    return { slug: name, name, path, type: 'inline' as const };
+  });
+}
+
+describe('GroupIndexService', () => {
+  let root: string;
+
+  const workspaceService = {
+    getOrCreateForBranch: async () => ({ id: wsId }),
+    getWorkspacePath: async (id: string) => join(root, id),
+  } as unknown as WorkspaceService;
+
+  const principals: IAccessControl = {
+    eligibleOwners: async () => ({ roles: [], users: [OLGA] }),
+    eligibleWriters: async () => ({ roles: ['Admin'], users: [] }),
+    eligibleReaders: async () => ({ restricted: true, roles: ['GTM Team'], users: [] }),
+  } as unknown as IAccessControl;
+
+  const skillService = (list: SkillSummary[] = []): ISkillService =>
+    ({ listSkills: async () => list }) as unknown as ISkillService;
+
+  const toolService = (list: ToolManualSummary[] = []): IToolManualService =>
+    ({ listAllSummaries: async () => list }) as unknown as IToolManualService;
+
+  const svc = (opts: {
+    access?: IAccessControl;
+    skills?: SkillSummary[];
+    tools?: ToolManualSummary[];
+    workspace?: WorkspaceService;
+  } = {}) =>
+    new GroupIndexService(
+      opts.workspace ?? workspaceService,
+      opts.access ?? principals,
+      skillService(opts.skills),
+      toolService(opts.tools),
+      KB_DIR,
+    );
+
+  const kb = () => join(root, wsId, KB_DIR);
+
+  /** A REAL group: a folder carrying the access.md that makes it exist. */
+  const groupDir = async (name: string) => {
+    await mkdir(join(kb(), 'Groups', name), { recursive: true });
+    await writeFile(join(kb(), 'Groups', name, 'access.md'), '---\nread:\n  - everyone\n---\n');
+  };
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'group-index-'));
+    await mkdir(kb(), { recursive: true });
+  });
+  afterEach(() => rm(root, { recursive: true, force: true }));
+
+  test('enumerates Groups/ folders carrying an access.md, sorted by name', async () => {
+    await groupDir('GTM');
+    await groupDir('Engineering');
+
+    const catalog = await svc().catalog();
+    expect(catalog.map((g) => g.name)).toEqual(['Engineering', 'GTM']);
+    expect(catalog[1].folders).toEqual(['Groups/GTM']);
+  });
+
+  test('a folder without an access.md is not a group', async () => {
+    // The residue a deleted group leaves behind: git cannot record an empty
+    // directory, so the folder outlives its files on live checkouts — and a
+    // folder with content but no access.md is just as much a non-group.
+    await mkdir(join(kb(), 'Groups', 'Ghost'), { recursive: true });
+    await mkdir(join(kb(), 'Groups', 'Residue'), { recursive: true });
+    await writeFile(join(kb(), 'Groups', 'Residue', 'notes.md'), 'leftover');
+    await groupDir('Real');
+
+    const catalog = await svc().catalog();
+    expect(catalog.map((g) => g.name)).toEqual(['Real']);
+  });
+
+  test('the retired Skills/ and Tools/ roots are NOT group roots', async () => {
+    await mkdir(join(kb(), 'Skills', 'GTM'), { recursive: true });
+    await mkdir(join(kb(), 'Tools', 'GTM'), { recursive: true });
+    await groupDir('Engineering');
+
+    const catalog = await svc().catalog();
+    expect(catalog.map((g) => g.name)).toEqual(['Engineering']);
+  });
+
+  test('ignores loose files and dot-dirs under the group root', async () => {
+    // The dot filter wins even over a folder that carries an access.md.
+    await mkdir(join(kb(), 'Groups', '.hidden'), { recursive: true });
+    await writeFile(join(kb(), 'Groups', '.hidden', 'access.md'), '---\nread:\n  - everyone\n---\n');
+    await groupDir('GTM');
+    await writeFile(join(kb(), 'Groups', 'slack.tool'), '{}');
+
+    const catalog = await svc().catalog();
+    expect(catalog.map((g) => g.name)).toEqual(['GTM']);
+  });
+
+  test('counts skills and tools from the global catalogs by groupOfPath', async () => {
+    await groupDir('GTM');
+    await groupDir('Product');
+
+    const catalog = await svc({
+      skills: skills('Groups/GTM/outreach', 'Groups/GTM/newsletter', 'Groups/Product/roadmap'),
+      // `Groups/slack.tool` is ungrouped (two segments) — it counts nowhere.
+      tools: tools('Groups/GTM/heyreach.tool', 'Groups/slack.tool'),
+    }).catalog();
+
+    const gtm = catalog.find((g) => g.name === 'GTM')!;
+    expect(gtm.skillCount).toBe(2);
+    expect(gtm.toolCount).toBe(1);
+    const product = catalog.find((g) => g.name === 'Product')!;
+    expect(product.skillCount).toBe(1);
+    expect(product.toolCount).toBe(0);
+  });
+
+  test('resolves principals on the group folder', async () => {
+    await groupDir('GTM');
+
+    const seen: string[] = [];
+    const access = {
+      eligibleOwners: async (_w: string, p: string) => {
+        seen.push(p);
+        return { roles: [], users: [OLGA] };
+      },
+      eligibleWriters: async () => ({ roles: [], users: [] }),
+      eligibleReaders: async () => ({ restricted: false, roles: [], users: [] }),
+    } as unknown as IAccessControl;
+
+    const catalog = await svc({ access }).catalog();
+    expect(catalog[0].folders).toEqual(['Groups/GTM']);
+    expect(seen).toEqual(['Groups/GTM']);
+    expect(catalog[0].owners.users).toEqual([OLGA]);
+    expect(catalog[0].readers).toEqual({ restricted: false, roles: [], users: [] });
+  });
+
+  test('a missing Groups/ root yields an empty list, not an error', async () => {
+    await expect(svc().catalog()).resolves.toEqual([]);
+  });
+
+  test('degrades to [] when the workspace cannot be created', async () => {
+    const broken = {
+      getOrCreateForBranch: async () => {
+        throw new Error('no clone');
+      },
+      getWorkspacePath: async () => root,
+    } as unknown as WorkspaceService;
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    await expect(svc({ workspace: broken }).catalog()).resolves.toEqual([]);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  test('a failed scan is served but NOT cached — the next call retries', async () => {
+    await groupDir('GTM');
+    let fail = true;
+    const flaky = {
+      // Fails once, the way a default-branch clone mid-creation does, then
+      // recovers. If the empty result were cached, GTM would stay hidden from
+      // every user for the full TTL after the cause was gone.
+      getOrCreateForBranch: async () => {
+        if (fail) throw new Error('clone in progress');
+        return { id: wsId };
+      },
+      getWorkspacePath: async (id: string) => join(root, id),
+    } as unknown as WorkspaceService;
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const service = svc({ workspace: flaky });
+
+    await expect(service.catalog()).resolves.toEqual([]);
+
+    fail = false;
+    expect((await service.catalog()).map((g) => g.name)).toEqual(['GTM']);
+    warn.mockRestore();
+  });
+
+  test('a genuinely empty KB IS cached — an empty result is a fact, not a failure', async () => {
+    let scans = 0;
+    const counting = {
+      getOrCreateForBranch: async () => {
+        scans += 1;
+        return { id: wsId };
+      },
+      getWorkspacePath: async (id: string) => join(root, id),
+    } as unknown as WorkspaceService;
+    const service = svc({ workspace: counting });
+
+    await expect(service.catalog()).resolves.toEqual([]);
+    await expect(service.catalog()).resolves.toEqual([]);
+    expect(scans).toBe(1);
+  });
+
+  test('caches for the TTL and rescans after invalidate()', async () => {
+    await groupDir('GTM');
+    const service = svc();
+
+    expect((await service.catalog()).map((g) => g.name)).toEqual(['GTM']);
+    // A group added out of band is NOT seen while the cache holds…
+    await groupDir('Finance');
+    expect((await service.catalog()).map((g) => g.name)).toEqual(['GTM']);
+    // …and IS seen once the file-change subscriber drops it.
+    service.invalidate();
+    expect((await service.catalog()).map((g) => g.name)).toEqual(['Finance', 'GTM']);
+  });
+});