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

package/src/modules/access/__tests__/roles-admin.service.test.ts

@@ -160,7 +160,9 @@ describe('RolesAdminService', () => {
     access = new AccessControlService(ws, KB);
     workflow = stubWorkflow();
     bus = stubEventBus();
-    svc = new RolesAdminService(ws, workflow.svc, access, KB, () => DEFAULT_BRANCH, bus.bus);
+    svc = new RolesAdminService(ws, workflow.svc, access, KB, () => DEFAULT_BRANCH, bus.bus, [
+      'recovery-admin@example.com',
+    ]);
   });
 
   afterEach(async () => {
@@ -219,11 +221,31 @@ describe('RolesAdminService', () => {
     const restored = await readRoles();
     expect(access.validateRolesYaml(restored).ok).toBe(true);
     expect(roster.find((r) => r.canonical === 'admin')?.isAdmin).toBe(true);
-    expect(roster.find((r) => r.canonical === 'admin')!.members.length).toBeGreaterThan(0);
+    // The roster is THIS deployment's configured admin — never a list baked
+    // into the build (hard-coded emails would land one company's admins in
+    // every customer's recovered file).
+    expect(roster.find((r) => r.canonical === 'admin')!.members).toEqual([
+      'recovery-admin@example.com',
+    ]);
+    expect(restored).not.toContain('bevel.software');
     // And the file is now healthy.
     expect(await svc.getHealth()).toEqual({ ok: true, errors: [] });
   });
 
+  it('recover refuses when no admin is configured — an adminless roster is the disease, not the cure', async () => {
+    const corrupt = 'roles:\n  Admin:\n    - a@x.eu\n  Admin:\n    - b@x.eu\n';
+    await write(repo, 'roles.yaml', corrupt);
+    access.invalidate(WS);
+    const adminless = new RolesAdminService(ws, workflow.svc, access, KB, () => DEFAULT_BRANCH, bus.bus);
+    await expect(adminless.recover(ADMIN)).rejects.toMatchObject({
+      status: 500,
+      payload: { kind: 'no-recovery-admins' },
+    });
+    // Nothing parked, nothing overwritten.
+    await expect(fs.readFile(path.join(repo, 'old-roles.yaml'), 'utf-8')).rejects.toThrow();
+    expect(await fs.readFile(path.join(repo, 'roles.yaml'), 'utf-8')).toBe(corrupt);
+  });
+
   it("getRoster's referencedBy is sound — finds node-frontmatter refs, not just folder access.md", async () => {
     // A folder access.md grant (the only thing the old advisory scan saw)...
     await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');

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

@@ -61,6 +61,8 @@ export function createAccessRoutes(
   eventBus: WorkflowEventBus,
   db: Database,
   kbDirName: string,
+  /** This deployment's configured admins — the break-glass recovery roster. */
+  recoveryAdmins: readonly string[] = [],
 ): express.Router {
   const router = express.Router({ mergeParams: true });
   const mutation = new AccessMutationService(workspaceService, accessControl, kbDirName);
@@ -71,6 +73,7 @@ export function createAccessRoutes(
     kbDirName,
     () => DEFAULT_BRANCH,
     eventBus,
+    recoveryAdmins,
   );
 
   // Roles (plugins) are authoritative on the DEFAULT branch — the Roles admin

package/src/modules/access/render-roles-yaml.ts

@@ -0,0 +1,65 @@
+import { parseRolesYaml } from './access-control.service.js';
+
+/**
+ * Render a `roles.yaml` granting Admin to each email — the ONE renderer every
+ * generated roles.yaml goes through (empty-remote seeding, the startup
+ * top-up, and the break-glass recovery), so none of them can drift on
+ * validation and each fails with the same actionable message.
+ *
+ * Each email is validated first, because a malformed one renders a file with
+ * no working Admin — SILENTLY: a leading `#` turns the entry into a YAML
+ * comment, an embedded newline breaks the list, an all-whitespace value
+ * renders an empty entry. A bad ADMIN_EMAIL is operator error, and the
+ * callers' fail-closed contracts want a message naming the fix instead of an
+ * un-administrable knowledge base (or a write-validator rejection deep in the
+ * recovery path).
+ */
+export function renderRolesYaml(
+  adminEmails: readonly string[],
+  /**
+   * Provenance comment appended to the header. The seed/top-up default names
+   * where the file came from; recovery passes `null` — claiming "generated at
+   * KB-seed time" on a recovery-restored file would mislead whoever reads it.
+   */
+  provenance: string | null = 'Generated by the Bevel platform at KB-seed time from ADMIN_EMAIL.',
+): string {
+  const emails = adminEmails.map((raw) => {
+    const email = raw.trim();
+    if (email === '') {
+      throw new Error('Seed admin email is empty — set ADMIN_EMAIL to a real address.');
+    }
+    if (email.startsWith('#')) {
+      throw new Error(
+        `Seed admin email ${JSON.stringify(raw)} starts with "#", which YAML reads as a comment — fix ADMIN_EMAIL.`,
+      );
+    }
+    if (/\s/.test(email)) {
+      throw new Error(
+        `Seed admin email ${JSON.stringify(raw)} contains whitespace, which would corrupt roles.yaml — fix ADMIN_EMAIL.`,
+      );
+    }
+    return email;
+  });
+  const lines = emails.map((e) => `    - ${e}`).join('\n');
+  const text =
+    '# Identity → role mapping for access control.\n' +
+    '# Role names are case- and whitespace-insensitive. The `Admin` role is special:\n' +
+    '# only Admins may edit this file, and at least one Admin must always exist.\n' +
+    (provenance !== null ? `#\n# ${provenance}\n` : '') +
+    'roles:\n' +
+    '  Admin:\n' +
+    `${lines}\n`;
+  // Validate by PARSING with the real access parser, not by re-implementing
+  // its email grammar: whatever the parser would reject (a `<Name <email>`
+  // shape, a non-email string, tomorrow's new rule) must fail here, before an
+  // un-administrable roles.yaml gets committed. The checks above exist only
+  // to give the common mistakes sharper messages.
+  const parsed = parseRolesYaml(text);
+  if (!parsed.ok) {
+    throw new Error(
+      `Generated roles.yaml from ADMIN_EMAIL would not parse — fix the configured address(es). ` +
+        parsed.errors.join('; '),
+    );
+  }
+  return text;
+}

package/src/modules/access/roles-admin.service.ts

@@ -54,6 +54,7 @@ import {
   parseAccessEntry,
 } from './access-control.service.js';
 import { makeRolesYamlWriteValidator } from './roles-yaml-guard.js';
+import { renderRolesYaml } from './render-roles-yaml.js';
 import {
   parseRolesModel,
   createRole as editCreateRole,
@@ -92,20 +93,21 @@ const ROLES_YAML = 'roles.yaml';
 const OLD_ROLES_YAML = 'old-roles.yaml';
 
 /**
- * The known-good `roles.yaml` the break-glass recovery restores. Mirrors the
- * canonical Bevel roster — it is the ONLY content recovery ever writes, so it
- * MUST parse (the post-recovery resolver loads it immediately). Keep the Admin
- * list in sync with the canonical `osapiens-kb/roles.yaml`.
+ * The known-good `roles.yaml` the break-glass recovery restores — generated
+ * from THIS deployment's configured admins, exactly like ordinary seeding
+ * (`ADMIN_EMAIL`), never a roster baked into the build: hard-coded emails
+ * would land one company's admins in every customer's recovered file. It is
+ * the ONLY content recovery ever writes, so it MUST parse (the post-recovery
+ * resolver loads it immediately) — guaranteed by delegating to the shared
+ * validated renderer, which parse-backs its output and throws an actionable
+ * message on a malformed ADMIN_EMAIL (instead of the write-validator
+ * rejecting the finished file deep in the write path). `null` provenance:
+ * the seed-time "generated at KB-seed time" comment would mislead on a
+ * recovery-restored file.
  */
-const RECOVERY_DEFAULT_ROLES_YAML = `# Identity → role mapping for access control.
-# Role names are case- and whitespace-insensitive. The \`Admin\` role is special:
-# only Admins may edit this file, and at least one Admin must always exist.
-roles:
-  Admin:
-    - razvan.radulescu@bevel.software
-    - ali.raza@bevel.software
-    - juan@bevel.software
-`;
+function renderRecoveryRolesYaml(admins: readonly string[]): string {
+  return renderRolesYaml(admins, null);
+}
 
 /** Health of the default-branch roles.yaml: does the resolver's parser accept it? */
 export interface RolesConfigHealth {
@@ -135,6 +137,13 @@ export class RolesAdminService {
      * open tab keeps a now-stale read verdict until a manual reload.
      */
     private readonly eventBus?: WorkflowEventBus,
+    /**
+     * This deployment's configured admins (`ADMIN_EMAIL`), the roster the
+     * break-glass recovery restores. Recovery refuses outright when empty: a
+     * recovered roles.yaml with no Admin is exactly the unusable state
+     * recovery exists to escape.
+     */
+    private readonly recoveryAdmins: readonly string[] = [],
   ) {}
 
   /** Resolved per call — see the constructor note on `defaultBranchOf`. */
@@ -340,6 +349,15 @@ export class RolesAdminService {
       );
     }
 
+    if (this.recoveryAdmins.length === 0) {
+      throw new RolesAdminError(
+        'Recovery needs a configured admin (ADMIN_EMAIL) to restore — a roles.yaml ' +
+          'with no Admin is exactly the unusable state recovery exists to escape.',
+        500,
+        { kind: 'no-recovery-admins' },
+      );
+    }
+
     await this.assertRolesUnlocked(workspaceId, actor);
 
     // Back up the corrupted bytes and restore the good default atomically. The
@@ -349,7 +367,7 @@ export class RolesAdminService {
       fsys.writeFiles(
         [
           { path: `${this.kbDirName}/${OLD_ROLES_YAML}`, content: current },
-          { path: `${this.kbDirName}/${ROLES_YAML}`, content: RECOVERY_DEFAULT_ROLES_YAML },
+          { path: `${this.kbDirName}/${ROLES_YAML}`, content: renderRecoveryRolesYaml(this.recoveryAdmins) },
         ],
         'Bevel recovery: reset corrupted roles.yaml',
       ),

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);

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

@@ -30,9 +30,40 @@ const execFileAsync = promisify(execFile);
 export function createSetupRoutes(
   settings: DeploymentSettingsService,
   adminAccess: IAdminAccessService,
+  /**
+   * The KB startup phase, invoked at its SECOND quiet moment: the save that
+   * completes first-time setup. The app is gated shut until exactly then
+   * (`isComplete`), so no session can be holding a working clone the phase
+   * would race.
+   */
+  kbStartupRunner: { runAll(): Promise<void> },
 ): express.Router {
   const router = express.Router();
 
+  /**
+   * Whether the last setup-time run of the KB startup phase FAILED. While
+   * true the deployment stays GATED: the settings are saved but the KB was
+   * never initialized, and reporting setup complete would open the app over
+   * an unmaintained (possibly unseeded) knowledge base. Saving the setup
+   * form again retries the phase; a server restart retries it at boot; a
+   * success clears the flag. Per-process state, like the gate itself.
+   */
+  let kbInitFailed = false;
+  /** The failure's message, surfaced to the ADMIN on the status endpoint. */
+  let kbInitError: string | null = null;
+  /**
+   * The setup-time run currently executing, if any. Its jobs: (a) keeping the
+   * status gate SHUT while a run executes (the settings read complete the
+   * moment they save, but the phase is still mutating branch trees — no
+   * workspace request may start yet), and (b) defense in depth via the `??=`
+   * at the run site, should a second invoker ever appear. It is NOT what
+   * serializes saves — the `saveTurn` chain below runs handlers strictly one
+   * at a time, phase included, so no second run can start while one executes.
+   */
+  let kbInitInFlight: Promise<void> | null = null;
+  /** The app-gate answer: settings complete AND the KB phase settled clean. */
+  const kbReady = () => isComplete(settings) && !kbInitFailed && kbInitInFlight === null;
+
   const requireAdmin: express.RequestHandler = async (req, res, next) => {
     if (!(await adminAccess.isAdmin(req.userEmail))) {
       res.status(403).json({ error: 'Admins only' });
@@ -51,25 +82,51 @@ export function createSetupRoutes(
    * secret's value.
    */
   router.get('/setup/status', async (req, res) => {
-    const complete = isComplete(settings);
+    // A failed OR still-running setup-time KB initialization keeps setup
+    // INCOMPLETE: the frontend gates the app on this answer, and opening it
+    // over an uninitialized (or mid-mutation) KB would be worse than keeping
+    // the setup screen up.
+    //
+    // `kbReady()` is read fresh AFTER the admin check, immediately before
+    // building each response: the check awaits, a completion save can start
+    // the phase during that await, and a snapshot taken before it would
+    // resurrect a pre-phase `true` — opening the gate mid-mutation.
     if (!(await adminAccess.isAdmin(req.userEmail))) {
-      res.json({ complete, isAdmin: false });
+      res.json({ complete: kbReady(), isAdmin: false });
       return;
     }
     res.json({
-      complete,
+      complete: kbReady(),
       awaitingRestart: awaitingRestart(settings),
       isAdmin: true,
       settings: settings.describe(),
+      ...(kbInitFailed ? { kbInitError } : {}),
     });
   });
 
+  /**
+   * Setup saves run strictly ONE AT A TIME, phase included: `settings.save`
+   * updates the live cache write by write, and the completing save runs the
+   * KB startup phase, which reads its configuration through live getters —
+   * a save interleaving with either would hand half-updated state to the
+   * other. A plain promise chain is enough: saves are a setup-screen rarity,
+   * not a hot path, and a save arriving mid-run simply waits the previous
+   * save (and its phase) out before proceeding.
+   */
+  let saveTurn: Promise<unknown> = Promise.resolve();
+
   /**
    * Save settings. Validated and written as ONE batch — a repository URL
    * stored without the token that reads it is a deployment that fails at its
    * first clone, so a partial write is never better than none.
    */
   router.post('/setup/settings', requireAdmin, async (req, res) => {
+    const turn = saveTurn.then(() => handleSave(req, res));
+    saveTurn = turn.catch(() => {});
+    await turn;
+  });
+
+  async function handleSave(req: express.Request, res: express.Response): Promise<void> {
     const body = (req.body ?? {}) as { settings?: Record<string, unknown> };
     const entries: Record<string, string> = {};
     for (const [key, value] of Object.entries(body.settings ?? {})) {
@@ -80,6 +137,11 @@ export function createSetupRoutes(
       entries[key] = value;
     }
     try {
+      // Completion is a TRANSITION, so it is measured BEFORE the save: the
+      // save that flips it false→true — whichever field arrives last — is the
+      // one that must run the KB startup phase, regardless of which save
+      // configured the branch model.
+      const wasComplete = isComplete(settings);
       const { restartRequired } = await settings.save(entries, req.userId ?? null);
       /**
        * Apply the branch model to THIS process, so pressing Save finishes
@@ -102,10 +164,55 @@ export function createSetupRoutes(
         };
         if (!validateBranchModel(model)) configureBranchModel(model);
       }
+      /**
+       * The save that COMPLETES setup is the KB startup phase's SECOND quiet
+       * moment (the other is boot): the app was gated shut until this very
+       * response, so the trees are provably quiet. Run the phase now —
+       * seeding the remote, scaffolding and migrating every branch — so the
+       * first workspace request that follows finds a maintained KB.
+       *
+       * Runs on the false→true completion transition — including when the
+       * branch model was configured by an EARLIER save and the repository
+       * URL arrives on a later one — and again on any save while a previous
+       * setup-time run stands failed (`kbInitFailed`), so saving the form is
+       * the retry. Never on a re-save of a complete, healthy setup: with the
+       * gate open, sessions may be live and that is no longer a quiet moment.
+       */
+      if ((!wasComplete || kbInitFailed) && isComplete(settings)) {
+        try {
+          // One run at a time. The save chain already serializes handlers
+          // whole, so no second run can start while one executes; the `??=`
+          // is defense in depth should another invoker ever appear.
+          kbInitInFlight ??= kbStartupRunner.runAll();
+          await kbInitInFlight;
+          // Under KB_SAFE_BOOT a run that abandoned the phase still resolves
+          // and opens the gate DELIBERATELY — booting unmaintained so the
+          // operator can get in and fix things is exactly what the
+          // break-glass is for.
+          kbInitFailed = false;
+          kbInitError = null;
+        } catch (initErr) {
+          // The settings ARE saved — only the KB initialization failed. The
+          // deployment stays gated (see the status endpoint) until a retry
+          // succeeds. Logged in full, returned actionable.
+          const msg = initErr instanceof Error ? initErr.message : String(initErr);
+          console.error('[setup] KB initialization failed after setup completed:', msg);
+          kbInitFailed = true;
+          kbInitError = msg;
+          res.status(500).json({
+            error:
+              'Settings saved, but the knowledge base could not be initialized. ' +
+              'Saving the setup form again retries; restarting the server retries too.',
+          });
+          return;
+        } finally {
+          kbInitInFlight = null;
+        }
+      }
       res.json({
         ok: true,
         restartRequired,
-        complete: isComplete(settings),
+        complete: kbReady(),
         awaitingRestart: awaitingRestart(settings),
         settings: settings.describe(),
       });
@@ -119,7 +226,7 @@ export function createSetupRoutes(
       console.error('[setup] save failed:', err instanceof Error ? err.message : String(err));
       res.status(500).json({ error: 'Could not save these settings.' });
     }
-  });
+  }
 
   /**
    * Try the credentials against the real remote, BEFORE anything is saved.

package/src/modules/workspace/__tests__/workspace.service.test.ts

@@ -435,32 +435,9 @@ describe('WorkspaceService — clone bootstrap & sibling reference', () => {
     await svc.getOrCreateForBranch('alice/draft');
     expect(cloned).toEqual([workspaceIdForBranch('alice/draft')]);
   });
-
-  // An upgraded deployment REUSES the persistent clone, so a top-up bound to
-  // fresh clones alone never runs a new build's scaffolding or migrations —
-  // the Groups→Plugins rename sat out an upgrade exactly this way. Every boot
-  // must offer the top-up to an existing clone once.
-  it('offers the scaffolding top-up to an existing clone once per process', async () => {
-    const seed = {
-      ensureRemoteSeeded: vi.fn(async () => {}),
-      topUpWorkspace: vi.fn(async () => {}),
-    };
-    const firstBoot = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base');
-    firstBoot.setSeedService(seed);
-    await firstBoot.getOrCreateForBranch('target-company-state');
-    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1); // the fresh clone
-
-    // A new process over the same workspaces dir — the deployed-upgrade case:
-    // the clone exists, and the top-up must still run, once, not per access.
-    const nextBoot = new WorkspaceService(workspacesRoot, upstream, 'knowledge-base');
-    nextBoot.setSeedService(seed);
-    await nextBoot.getOrCreateForBranch('target-company-state');
-    await nextBoot.getOrCreateForBranch('target-company-state');
-    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(2);
-  });
 });
 
-describe('WorkspaceService — scaffolding top-up on restart-survivor clones', () => {
+describe('WorkspaceService.sweepOrphanedWorkspaces', () => {
   let root: string;
 
   beforeEach(async () => {
@@ -475,81 +452,15 @@ describe('WorkspaceService — scaffolding top-up on restart-survivor clones', (
     await fs.rm(root, { recursive: true, force: true });
   });
 
-  // The top-up MOVES files (the Groups→Plugins migration runs inside it), so a
-  // caller handed the workspace mid-run reads a tree with both halves missing.
-  it('makes a concurrent opener wait out the in-flight top-up instead of returning mid-migration', async () => {
-    await seedBranchWorkspace(root, 'target-company-state');
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base');
-    let release!: () => void;
-    const gate = new Promise<void>((r) => { release = r; });
-    const seed = {
-      ensureRemoteSeeded: vi.fn(async () => {}),
-      topUpWorkspace: vi.fn(() => gate),
-    };
-    svc.setSeedService(seed);
-
-    let aDone = false;
-    let bDone = false;
-    const a = svc.getOrCreateForBranch('target-company-state').then((v) => { aDone = true; return v; });
-    const b = svc.getOrCreateForBranch('target-company-state').then((v) => { bDone = true; return v; });
-    // Wait until the top-up has started (the fake clone makes the preceding
-    // git-config repair fail slowly, so poll rather than sleep), then give
-    // both callers time to settle against the gate.
-    await vi.waitFor(() => expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1));
-    await new Promise((r) => setTimeout(r, 30));
-    // Neither caller has been handed the workspace while the top-up runs —
-    // and the second did not start a rival run.
-    expect(aDone).toBe(false);
-    expect(bDone).toBe(false);
-    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1);
-
-    release();
-    const [infoA, infoB] = await Promise.all([a, b]);
-    expect(infoA.id).toBe(infoB.id);
-  });
-
-  it('re-offers the top-up after deleteWorkspace — the claim died with the clone', async () => {
-    await seedBranchWorkspace(root, 'target-company-state');
-    const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base');
-    const seed = {
-      ensureRemoteSeeded: vi.fn(async () => {}),
-      topUpWorkspace: vi.fn(async () => {}),
-    };
-    svc.setSeedService(seed);
-
-    await svc.getOrCreateForBranch('target-company-state');
-    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1);
-
-    await svc.deleteWorkspace(workspaceIdForBranch('target-company-state'));
-    // A later bootstrap re-creates the clone (seeded by hand here); it must
-    // be offered the top-up afresh — the old claim was about a clone that no
-    // longer exists.
-    await seedBranchWorkspace(root, 'target-company-state');
-    await svc.getOrCreateForBranch('target-company-state');
-    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(2);
-  });
-
-  it('re-offers the top-up after the orphan sweep removes the clone — same eviction rule', async () => {
-    await seedBranchWorkspace(root, 'target-company-state');
+  it('removes the clone of a branch that is not in the known set', async () => {
+    const { workspaceId, workspaceDir } = await seedBranchWorkspace(root, 'target-company-state');
     const svc = new WorkspaceService(root, 'https://github.com/Bevel-Software/knowledge-base.git', 'knowledge-base');
-    const seed = {
-      ensureRemoteSeeded: vi.fn(async () => {}),
-      topUpWorkspace: vi.fn(async () => {}),
-    };
-    svc.setSeedService(seed);
-
     await svc.getOrCreateForBranch('target-company-state');
-    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(1);
 
     // The branch vanishes from the known set; the sweep reclaims its clone.
     const { removed } = await svc.sweepOrphanedWorkspaces([]);
-    expect(removed).toContain(workspaceIdForBranch('target-company-state'));
-
-    // Re-created before any restart: the fresh clone must still get its one
-    // top-up — the claim died with the directory the sweep removed.
-    await seedBranchWorkspace(root, 'target-company-state');
-    await svc.getOrCreateForBranch('target-company-state');
-    expect(seed.topUpWorkspace).toHaveBeenCalledTimes(2);
+    expect(removed).toContain(workspaceId);
+    await expect(fs.stat(workspaceDir)).rejects.toThrow();
   });
 });