@bevel-software/platform-core-backend 0.7.5 → 0.9.0

package/src/modules/{groups/groups.service.ts → plugins/plugins.service.ts}

@@ -3,9 +3,9 @@ import fs from 'node:fs/promises';
 import type { Dirent } from 'node:fs';
 import {
   DEFAULT_BRANCH,
-  GROUPS_DIR,
-  groupOfPath,
-  isPersonalGroupFolder,
+  PLUGINS_DIR,
+  pluginOfPath,
+  isPersonalPluginFolder,
 } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { workspaceIdForBranch } from '../workspace/workspace.service.js';
@@ -13,37 +13,37 @@ import type { IAccessControl } from '../access/access-control.interface.js';
 import type { ISkillService } from '../skills/skills.contract.js';
 import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
 import { TtlCache } from '../../shared/ttl-cache.js';
-import type { GroupCatalogEntry, IGroupIndexService } from './groups.contract.js';
+import type { PluginCatalogEntry, IPluginIndexService } from './plugins.contract.js';
 
 const CACHE_TTL_MS = 60_000;
 
 /**
- * The group index: every group folder in the default-branch KB, with its
+ * The plugin index: every plugin folder in the default-branch KB, with its
  * caller-independent totals and access principals.
  *
  * Two decisions worth keeping straight:
  *
- *  - **Existence is an `access.md`, counting is not.** A group EXISTS because
+ *  - **Existence is an `access.md`, counting is not.** A plugin EXISTS because
  *    its folder carries an `access.md` — the file the provisioning endpoint
  *    seeds and the one every per-caller verdict (member / manager /
- *    discoverable) resolves against. A bare directory under `Groups/` is NOT
- *    a group: git cannot record an empty folder, so deleting a group's files
+ *    discoverable) resolves against. A bare directory under `Plugins/` is NOT
+ *    a plugin: git cannot record an empty folder, so deleting a plugin's files
  *    leaves its directory behind on live checkouts, and enumerating by
  *    directory would resurrect every such ghost. Counts come from the
  *    already-cached global catalogs — `skillService.listSkills(undefined)` and
- *    `toolManualService.listAllSummaries()` — bucketed by `groupOfPath`. A
+ *    `toolManualService.listAllSummaries()` — bucketed by `pluginOfPath`. A
  *    second `walkFiles` pass would re-read the same tree and could disagree
  *    with the catalogs about what counts as a skill.
- *  - **Loose files are not groups.** `Groups/slack.tool` sits directly under
+ *  - **Loose files are not plugins.** `Plugins/slack.tool` sits directly under
  *    the root, so it is a file, not a directory — the same ≥3-segment rule
- *    `groupOfPath` applies, arrived at from the other side.
+ *    `pluginOfPath` applies, arrived at from the other side.
  *
  * Cached for {@link CACHE_TTL_MS} and dropped by `invalidate()` from the
  * file-change subscriber, so a grant committed on the default branch is
  * reflected within one round-trip rather than one TTL.
  */
-export class GroupIndexService implements IGroupIndexService {
-  private readonly cache: TtlCache<GroupCatalogEntry[]>;
+export class PluginIndexService implements IPluginIndexService {
+  private readonly cache: TtlCache<PluginCatalogEntry[]>;
 
   constructor(
     private readonly workspaceService: WorkspaceService,
@@ -60,13 +60,13 @@ export class GroupIndexService implements IGroupIndexService {
     this.cache.invalidate();
   }
 
-  async catalog(): Promise<GroupCatalogEntry[]> {
+  async catalog(): Promise<PluginCatalogEntry[]> {
     const cached = this.cache.get();
     if (cached) return cached;
     const entries = await this.build();
-    // A failed scan and a KB with genuinely no group folders both serve `[]`,
+    // A failed scan and a KB with genuinely no plugin folders both serve `[]`,
     // but only the second is a fact worth holding for the TTL. Caching the
-    // failure would hide every group from every user for the full 60s AFTER
+    // failure would hide every plugin from every user for the full 60s AFTER
     // the cause is gone — a clone mid-creation, a readdir that raced a
     // checkout — and `invalidate()` only fires on a file-change event that may
     // never arrive in that window. So a degraded read is served, not stored,
@@ -80,16 +80,16 @@ export class GroupIndexService implements IGroupIndexService {
 
    /**
    * Degrades on ANY failure rather than throwing. The Library must never break
-   * because a group folder can't be read — same philosophy as the skill and
+   * because a plugin folder can't be read — same philosophy as the skill and
    * tool-manual scanners, and the reason the route's 500 is reserved for the
    * per-caller half.
    *
    * `null` is that degraded case and is deliberately NOT the same value as an
-   * empty array: a KB with no group folders returns `[]`, which is true and
+   * empty array: a KB with no plugin folders returns `[]`, which is true and
    * cacheable, while a failure returns `null`, which `catalog()` serves as `[]`
    * without storing it.
    */
-  private async build(): Promise<GroupCatalogEntry[] | null> {
+  private async build(): Promise<PluginCatalogEntry[] | null> {
     try {
       const wsId = (await this.workspaceService.getOrCreateForBranch(DEFAULT_BRANCH)).id;
       const kbRoot = path.join(await this.workspaceService.getWorkspacePath(wsId), this.kbDirName);
@@ -102,10 +102,10 @@ export class GroupIndexService implements IGroupIndexService {
         this.countTools(),
       ]);
 
-      const entries: GroupCatalogEntry[] = [];
-      for (const [name, groupFolders] of folders) {
-        // One folder, one access boundary — the folder IS the group.
-        const [primary] = groupFolders;
+      const entries: PluginCatalogEntry[] = [];
+      for (const [name, pluginFolders] of folders) {
+        // One folder, one access boundary — the folder IS the plugin.
+        const [primary] = pluginFolders;
         const [owners, writers, readers] = await Promise.all([
           this.accessControl.eligibleOwners(wsId, primary),
           this.accessControl.eligibleWriters(wsId, primary),
@@ -113,7 +113,7 @@ export class GroupIndexService implements IGroupIndexService {
         ]);
         entries.push({
           name,
-          folders: groupFolders,
+          folders: pluginFolders,
           skillCount: skillCounts.get(name) ?? 0,
           toolCount: toolCounts.get(name) ?? 0,
           owners,
@@ -124,70 +124,70 @@ export class GroupIndexService implements IGroupIndexService {
       return entries.sort((a, b) => a.name.localeCompare(b.name));
     } catch (err) {
       console.warn(
-        `[groups] group index unavailable: ${err instanceof Error ? err.message : String(err)}`,
+        `[plugins] plugin index unavailable: ${err instanceof Error ? err.message : String(err)}`,
       );
       return null;
     }
   }
 
-  /** name → repo-relative group folder (always a single-element list). */
+  /** name → repo-relative plugin folder (always a single-element list). */
   private async scanFolders(kbRoot: string): Promise<Map<string, string[]>> {
     const byName = new Map<string, string[]>();
     let children: Dirent[];
     try {
-      children = await fs.readdir(path.join(kbRoot, GROUPS_DIR), { withFileTypes: true });
+      children = await fs.readdir(path.join(kbRoot, PLUGINS_DIR), { withFileTypes: true });
     } catch {
-      return byName; // a KB without a `Groups/` root simply has no groups
+      return byName; // a KB without a `Plugins/` root simply has no plugins
     }
     const candidates = children.filter(
       (child) =>
         child.isDirectory() &&
         !child.name.startsWith('.') &&
-        // Personal folders live under Groups/ but are not groups: one exists
+        // Personal folders live under Plugins/ but are not plugins: one exists
         // per person, private by construction, and listing them would put a
         // locked row per employee in everyone's index.
-        !isPersonalGroupFolder(child.name),
+        !isPersonalPluginFolder(child.name),
     );
-    // A group exists exactly when its folder carries an `access.md` (see the
+    // A plugin exists exactly when its folder carries an `access.md` (see the
     // class doc) — stat that file, don't trust the directory.
     const verdicts = await Promise.all(
       candidates.map(async (child) => {
         try {
-          return (await fs.stat(path.join(kbRoot, GROUPS_DIR, child.name, 'access.md'))).isFile();
+          return (await fs.stat(path.join(kbRoot, PLUGINS_DIR, child.name, 'access.md'))).isFile();
         } catch {
           return false;
         }
       }),
     );
     candidates.forEach((child, i) => {
-      if (verdicts[i]) byName.set(child.name, [`${GROUPS_DIR}/${child.name}`]);
+      if (verdicts[i]) byName.set(child.name, [`${PLUGINS_DIR}/${child.name}`]);
     });
     return byName;
   }
 
   private async countSkills(): Promise<Map<string, number>> {
     // `undefined` is the documented GLOBAL, unfiltered mode — counts are a
-    // property of the group, not of who is asking.
-    return bucketByGroup(await this.skillService.listSkills(undefined));
+    // property of the plugin, not of who is asking.
+    return bucketByPlugin(await this.skillService.listSkills(undefined));
   }
 
   private async countTools(): Promise<Map<string, number>> {
-    return bucketByGroup(await this.toolManualService.listAllSummaries());
+    return bucketByPlugin(await this.toolManualService.listAllSummaries());
   }
 }
 
-/** Count items per group folder name; ungrouped items (`null`) count nowhere. */
-function bucketByGroup(items: { path: string }[]): Map<string, number> {
+/** Count items per plugin folder name; ungrouped items (`null`) count nowhere. */
+function bucketByPlugin(items: { path: string }[]): Map<string, number> {
   const counts = new Map<string, number>();
   for (const item of items) {
-    const group = groupOfPath(item.path);
-    if (group === null) continue;
-    counts.set(group, (counts.get(group) ?? 0) + 1);
+    const plugin = pluginOfPath(item.path);
+    if (plugin === null) continue;
+    counts.set(plugin, (counts.get(plugin) ?? 0) + 1);
   }
   return counts;
 }
 
-/** The default-branch workspace id every group resolution runs against. */
-export function groupsWorkspaceId(): string {
+/** The default-branch workspace id every plugin resolution runs against. */
+export function pluginsWorkspaceId(): string {
   return workspaceIdForBranch(DEFAULT_BRANCH);
 }

package/src/modules/secrets-vault/__tests__/tool-owner-gate.route.test.ts

@@ -1,143 +1,143 @@
-import type { Server as HttpServer } from 'node:http';
-import express from 'express';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { createSecretsVaultRoutes } from '../secrets-vault.routes.js';
-
-/**
- * THE OWNER GATE: a tool's shared (admin) secrets — plain values and OAuth
- * client secrets — are settable by whoever can WRITE that `.tool` FILE (its
- * frontmatter `write:`/`owner:` verbs + the access.md chain), and by no one
- * else. There is deliberately NO platform-role check here: a non-Admin who
- * manages a `.tool` configures it; an Admin who can't write the file doesn't.
- * The per-file resolution itself (frontmatter verbs on `.tool` files) is
- * covered in access-control.service.test.ts — this locks the route gate to
- * `canWrite(path)` so no role-based shortcut regresses it.
- */
-
-const TOOL_PATH = 'Tools/weather.tool';
-const WRITER = 'writer@x.com';
-const READER = 'reader@x.com';
-
-const toolManualService = {
-  listAccessible: async () => [
-    {
-      slug: 'weather',
-      name: 'weather',
-      path: TOOL_PATH,
-      type: 'mcp' as const,
-      variables: [
-        { name: 'SHARED_KEY', scope: 'admin' as const, label: 'Org key' },
-        {
-          name: 'SIGNIN',
-          scope: 'user' as const,
-          label: 'Weather sign-in',
-          oauth: {
-            authorizationUrl: 'https://auth.example.com/authorize',
-            tokenUrl: 'https://auth.example.com/token',
-            clientId: 'client-1',
-          },
-        },
-      ],
-    },
-  ],
-} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
-
-const putSharedStatic = vi.fn(async () => ({ id: 's1' }));
-const putSharedOAuthClientSecret = vi.fn(async () => {});
-const secretsVault = {
-  putSharedStatic,
-  putSharedOAuthClientSecret,
-} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
-
-// Per-FILE write: only WRITER may write THIS tool's path. No role concept at all.
-const accessControl = {
-  canRead: async () => true,
-  canWrite: async (_ws: string, email: string, path: string) => email === WRITER && path === TOOL_PATH,
-} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['accessControl'];
-
-let httpServer: HttpServer | undefined;
-
-async function baseUrlAs(email: string): Promise<string> {
-  const app = express();
-  app.use(express.json());
-  app.use((req, _res, next) => {
-    req.userId = `id-${email}`;
-    req.userEmail = email;
-    next();
-  });
-  app.use(
-    '/api',
-    createSecretsVaultRoutes({
-      secretsVault,
-      toolManualService,
-      accessControl,
-      stateSecret: 'test-secret',
-      publicBackendUrl: 'http://localhost:3000',
-      publicFrontendUrl: 'http://localhost:5173',
-    }),
-  );
-  httpServer = await new Promise<HttpServer>((resolve) => {
-    const s = app.listen(0, () => resolve(s));
-  });
-  const port = (httpServer.address() as { port: number }).port;
-  return `http://127.0.0.1:${port}`;
-}
-
-afterEach(async () => {
-  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
-  httpServer = undefined;
-  putSharedStatic.mockClear();
-  putSharedOAuthClientSecret.mockClear();
-});
-
-describe('tool owner gate — shared config requires WRITE on the `.tool` file', () => {
-  it('a writer of the file sets the shared admin value', async () => {
-    const base = await baseUrlAs(WRITER);
-    const res = await fetch(`${base}/api/secrets/tools/weather/vars/SHARED_KEY/admin`, {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ value: 'k-123' }),
-    });
-    expect(res.status).toBe(201);
-    expect(putSharedStatic).toHaveBeenCalledWith(expect.objectContaining({ key: 'weather_SHARED_KEY' }));
-  });
-
-  it('a non-writer is refused (403), even though they can READ the tool', async () => {
-    const base = await baseUrlAs(READER);
-    const res = await fetch(`${base}/api/secrets/tools/weather/vars/SHARED_KEY/admin`, {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ value: 'k-123' }),
-    });
-    expect(res.status).toBe(403);
-    expect(putSharedStatic).not.toHaveBeenCalled();
-  });
-
-  it('a writer of the file sets the OAuth client secret, pinned to the declared provider', async () => {
-    const base = await baseUrlAs(WRITER);
-    const res = await fetch(`${base}/api/secrets/tools/weather/vars/SIGNIN/oauth/admin`, {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ clientSecret: 'cs-123' }),
-    });
-    expect(res.status).toBe(201);
-    expect(putSharedOAuthClientSecret).toHaveBeenCalledWith(
-      expect.objectContaining({
-        key: 'weather_SIGNIN',
-        clientSecret: 'cs-123',
-        provider: expect.objectContaining({ clientId: 'client-1' }),
-      }),
-    );
-  });
-
-  it('a non-writer cannot set the client secret (403)', async () => {
-    const base = await baseUrlAs(READER);
-    const res = await fetch(`${base}/api/secrets/tools/weather/vars/SIGNIN/oauth/admin`, {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ clientSecret: 'cs-123' }),
-    });
-    expect(res.status).toBe(403);
-    expect(putSharedOAuthClientSecret).not.toHaveBeenCalled();
-  });
-});
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createSecretsVaultRoutes } from '../secrets-vault.routes.js';
+
+/**
+ * THE OWNER GATE: a tool's shared (admin) secrets — plain values and OAuth
+ * client secrets — are settable by whoever can WRITE that `.tool` FILE (its
+ * frontmatter `write:`/`owner:` verbs + the access.md chain), and by no one
+ * else. There is deliberately NO platform-role check here: a non-Admin who
+ * manages a `.tool` configures it; an Admin who can't write the file doesn't.
+ * The per-file resolution itself (frontmatter verbs on `.tool` files) is
+ * covered in access-control.service.test.ts — this locks the route gate to
+ * `canWrite(path)` so no role-based shortcut regresses it.
+ */
+
+const TOOL_PATH = 'Tools/weather.tool';
+const WRITER = 'writer@x.com';
+const READER = 'reader@x.com';
+
+const toolManualService = {
+  listAccessible: async () => [
+    {
+      slug: 'weather',
+      name: 'weather',
+      path: TOOL_PATH,
+      type: 'mcp' as const,
+      variables: [
+        { name: 'SHARED_KEY', scope: 'admin' as const, label: 'Org key' },
+        {
+          name: 'SIGNIN',
+          scope: 'user' as const,
+          label: 'Weather sign-in',
+          oauth: {
+            authorizationUrl: 'https://auth.example.com/authorize',
+            tokenUrl: 'https://auth.example.com/token',
+            clientId: 'client-1',
+          },
+        },
+      ],
+    },
+  ],
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
+
+const putSharedStatic = vi.fn(async () => ({ id: 's1' }));
+const putSharedOAuthClientSecret = vi.fn(async () => {});
+const secretsVault = {
+  putSharedStatic,
+  putSharedOAuthClientSecret,
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
+
+// Per-FILE write: only WRITER may write THIS tool's path. No role concept at all.
+const accessControl = {
+  canRead: async () => true,
+  canWrite: async (_ws: string, email: string, path: string) => email === WRITER && path === TOOL_PATH,
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['accessControl'];
+
+let httpServer: HttpServer | undefined;
+
+async function baseUrlAs(email: string): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userId = `id-${email}`;
+    req.userEmail = email;
+    next();
+  });
+  app.use(
+    '/api',
+    createSecretsVaultRoutes({
+      secretsVault,
+      toolManualService,
+      accessControl,
+      stateSecret: 'test-secret',
+      publicBackendUrl: 'http://localhost:3000',
+      publicFrontendUrl: 'http://localhost:5173',
+    }),
+  );
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return `http://127.0.0.1:${port}`;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  putSharedStatic.mockClear();
+  putSharedOAuthClientSecret.mockClear();
+});
+
+describe('tool owner gate — shared config requires WRITE on the `.tool` file', () => {
+  it('a writer of the file sets the shared admin value', async () => {
+    const base = await baseUrlAs(WRITER);
+    const res = await fetch(`${base}/api/secrets/tools/weather/vars/SHARED_KEY/admin`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 'k-123' }),
+    });
+    expect(res.status).toBe(201);
+    expect(putSharedStatic).toHaveBeenCalledWith(expect.objectContaining({ key: 'weather_SHARED_KEY' }));
+  });
+
+  it('a non-writer is refused (403), even though they can READ the tool', async () => {
+    const base = await baseUrlAs(READER);
+    const res = await fetch(`${base}/api/secrets/tools/weather/vars/SHARED_KEY/admin`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 'k-123' }),
+    });
+    expect(res.status).toBe(403);
+    expect(putSharedStatic).not.toHaveBeenCalled();
+  });
+
+  it('a writer of the file sets the OAuth client secret, pinned to the declared provider', async () => {
+    const base = await baseUrlAs(WRITER);
+    const res = await fetch(`${base}/api/secrets/tools/weather/vars/SIGNIN/oauth/admin`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ clientSecret: 'cs-123' }),
+    });
+    expect(res.status).toBe(201);
+    expect(putSharedOAuthClientSecret).toHaveBeenCalledWith(
+      expect.objectContaining({
+        key: 'weather_SIGNIN',
+        clientSecret: 'cs-123',
+        provider: expect.objectContaining({ clientId: 'client-1' }),
+      }),
+    );
+  });
+
+  it('a non-writer cannot set the client secret (403)', async () => {
+    const base = await baseUrlAs(READER);
+    const res = await fetch(`${base}/api/secrets/tools/weather/vars/SIGNIN/oauth/admin`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ clientSecret: 'cs-123' }),
+    });
+    expect(res.status).toBe(403);
+    expect(putSharedOAuthClientSecret).not.toHaveBeenCalled();
+  });
+});

package/src/modules/settings/__tests__/setup.routes.test.ts

@@ -18,7 +18,7 @@ let server: HttpServer | null = null;
  * that runs later in the same worker would otherwise see a different
  * environment than the one it was written against.
  */
-const KB_ENV = ['KB_REPO_URL', 'GIT_TOKEN', 'GIT_USERNAME', 'KB_DIR_NAME'] as const;
+const KB_ENV = ['KB_REPO_URL', 'GIT_TOKEN', 'GIT_USERNAME', 'KB_DIR_NAME', 'GITHUB_TOKEN'] as const;
 let savedEnv: Partial<Record<(typeof KB_ENV)[number], string | undefined>> = {};
 
 beforeEach(() => {
@@ -40,7 +40,7 @@ afterEach(() => {
 });
 
 /** Mount the setup router on a throwaway port and hand back its base URL. */
-function listen(isAdmin = true) {
+function listen(isAdmin = true, runAll: () => Promise<void> = async () => {}) {
   const db = {
     select: () => ({ from: () => Promise.resolve([]) }),
     insert: () => ({ values: () => ({ onConflictDoUpdate: () => Promise.resolve() }) }),
@@ -54,7 +54,16 @@ function listen(isAdmin = true) {
     req.userId = 'user-1';
     next();
   });
-  app.use('/api', createSetupRoutes(settings, { isAdmin: async () => isAdmin } as IAdminAccessService));
+  app.use(
+    '/api',
+    createSetupRoutes(
+      settings,
+      { isAdmin: async () => isAdmin } as IAdminAccessService,
+      // Default no-op: most suites never complete setup, so the runner is
+      // never reached. The completion-transition suite passes its own spy.
+      { runAll },
+    ),
+  );
   server = app.listen(0);
   const { port } = server.address() as AddressInfo;
   return { base: `http://127.0.0.1:${port}`, settings };
@@ -182,6 +191,118 @@ describe('POST /setup/test-connection — the command git is given', () => {
   });
 });
 
+/**
+ * The KB startup phase's SECOND quiet moment: the save that completes setup.
+ * Completion is a false→true TRANSITION (whichever field arrives last, on
+ * whichever save), and a failed setup-time run keeps the deployment gated —
+ * settings saved, KB uninitialized — until a retry succeeds.
+ *
+ * The branch model rides in from the environment the vitest config pins
+ * (DEFAULT_BRANCH / PROTECTED_BRANCHES) and is configured by test-setup, so
+ * completing setup here means storing the repository URL and token — exactly
+ * the "branch model configured on an earlier save" gap.
+ */
+describe('POST /setup/settings — the completion transition and the KB startup phase', () => {
+  const completing = { kbRepoUrl: 'https://example.com/acme/kb.git', gitToken: 'ghp_x' };
+
+  it('runs the phase exactly once: on the save that completes setup, not before, not after', async () => {
+    let runs = 0;
+    const { base } = listen(true, async () => {
+      runs++;
+    });
+    // First save: an incomplete configuration — no phase.
+    let res = await post(base, '/api/setup/settings', { settings: { gitUsername: 'x-access-token' } });
+    expect(res.status).toBe(200);
+    expect(runs).toBe(0);
+    // Second save completes setup — the transition runs the phase.
+    res = await post(base, '/api/setup/settings', { settings: completing });
+    expect(res.status).toBe(200);
+    expect((await res.json()).complete).toBe(true);
+    expect(runs).toBe(1);
+    // A re-save of a complete, healthy setup is NOT a quiet moment.
+    res = await post(base, '/api/setup/settings', { settings: { gitUsername: 'x-access-token' } });
+    expect(res.status).toBe(200);
+    expect(runs).toBe(1);
+  });
+
+  it('keeps setup gated after a failed run; a re-save retries, and success clears the gate', async () => {
+    const consoleError = console.error;
+    console.error = () => {};
+    try {
+      let attempts = 0;
+      let fail = true;
+      const { base } = listen(true, async () => {
+        attempts++;
+        if (fail) throw new Error('remote said no');
+      });
+      const res = await post(base, '/api/setup/settings', { settings: completing });
+      expect(res.status).toBe(500);
+      expect((await res.json()).error).toMatch(/could not be initialized/i);
+      expect(attempts).toBe(1);
+      // The gate stays shut: status reports incomplete, with the admin's hint.
+      let status = await (await fetch(`${base}/api/setup/status`)).json();
+      expect(status.complete).toBe(false);
+      expect(status.kbInitError).toMatch(/remote said no/);
+      // Any save while the failure stands retries the phase.
+      fail = false;
+      const retry = await post(base, '/api/setup/settings', {
+        settings: { gitUsername: 'x-access-token' },
+      });
+      expect(retry.status).toBe(200);
+      expect(attempts).toBe(2);
+      expect((await retry.json()).complete).toBe(true);
+      status = await (await fetch(`${base}/api/setup/status`)).json();
+      expect(status.complete).toBe(true);
+      expect(status.kbInitError).toBeUndefined();
+    } finally {
+      console.error = consoleError;
+    }
+  });
+
+  it('keeps the gate shut while the phase runs, and a save landing mid-run waits the phase out', async () => {
+    let runs = 0;
+    let release!: () => void;
+    const running = new Promise<void>((r) => (release = r));
+    const { base } = listen(true, async () => {
+      runs++;
+      await running;
+    });
+    // The completing save blocks inside the phase...
+    const first = post(base, '/api/setup/settings', { settings: completing });
+    // release() in a finally: a mid-test assertion failure must still unblock
+    // the phase, or `first`/`second` hang pending until the vitest timeout.
+    let second!: Promise<Response>;
+    try {
+      await new Promise((r) => setTimeout(r, 50));
+      // ...during which the settings read complete but the GATE must not open —
+      // the phase is still mutating branch trees.
+      const status = await (await fetch(`${base}/api/setup/status`)).json();
+      expect(status.complete).toBe(false);
+      // A save landing mid-run is HELD until the phase settles: the runner
+      // reads its configuration through live getters, and a save applied under
+      // it would split the run across two configurations. It must neither
+      // resolve early nor start a second run over the same trees.
+      let secondSettled = false;
+      second = post(base, '/api/setup/settings', {
+        settings: { gitUsername: 'x-access-token' },
+      }).then((r) => {
+        secondSettled = true;
+        return r;
+      });
+      await new Promise((r) => setTimeout(r, 100));
+      expect(secondSettled).toBe(false);
+      expect(runs).toBe(1);
+    } finally {
+      release();
+    }
+    const [res1, res2] = await Promise.all([first, second]);
+    expect(res1.status).toBe(200);
+    expect(res2.status).toBe(200);
+    expect(runs).toBe(1);
+    expect((await (await fetch(`${base}/api/setup/status`)).json()).complete).toBe(true);
+  });
+});
+
 describe('GET /setup/status', () => {
   it('tells a non-admin whether setup is done, and nothing else', async () => {
     const { base } = listen(false);