@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/src/modules/settings/__tests__/deployment-settings.service.test.ts

@@ -1,10 +1,13 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { randomBytes } from 'node:crypto';
+import type { SQL } from 'drizzle-orm';
+import { PgDialect } from 'drizzle-orm/pg-core';
 import {
   DeploymentSettingsService,
   SettingsValidationError,
   CORE_SETTINGS,
   LEGACY_LAYOUT_ENV_VARS,
+  retireMergedBranchesOn,
 } from '../deployment-settings.service.js';
 import type { Database } from '../../database/connection.js';
 
@@ -28,13 +31,54 @@ function makeDb() {
           else rows.push({ key: v.key, value: v.value, encrypted: v.encrypted });
           return Promise.resolve();
         },
+        onConflictDoNothing: () => ({
+          returning: () => {
+            if (rows.some((r) => r.key === v.key)) return Promise.resolve([]);
+            rows.push({ key: v.key, value: v.value, encrypted: v.encrypted });
+            return Promise.resolve([{ key: v.key }]);
+          },
+        }),
+      }),
+    }),
+    // `delete … where … returning` / `update … set … where … returning`: the
+    // conditional swap. The fake applies the one predicate the service sends,
+    // key AND value, by reading the bound parameters off the drizzle `where`.
+    delete: () => ({
+      where: (predicate: unknown) => {
+        const done = Promise.resolve();
+        return Object.assign(done, {
+          returning: () => {
+            const [key, value] = boundParams(predicate);
+            const at = rows.findIndex((r) => r.key === key && r.value === value);
+            if (at === -1) return Promise.resolve([]);
+            rows.splice(at, 1);
+            return Promise.resolve([{ key }]);
+          },
+        });
+      },
+    }),
+    update: () => ({
+      set: (v: { value: string }) => ({
+        where: (predicate: unknown) => ({
+          returning: () => {
+            const [key, value] = boundParams(predicate);
+            const row = rows.find((r) => r.key === key && r.value === value);
+            if (!row) return Promise.resolve([]);
+            row.value = v.value;
+            return Promise.resolve([{ key }]);
+          },
+        }),
       }),
     }),
-    delete: () => ({ where: () => Promise.resolve() }),
   } as unknown as Database;
   return { db, rows };
 }
 
+/** The parameters a drizzle predicate binds, in order — what the fake table matches on. */
+function boundParams(predicate: unknown): unknown[] {
+  return new PgDialect().sqlToQuery(predicate as SQL).params;
+}
+
 let saved: NodeJS.ProcessEnv;
 beforeEach(() => {
   saved = { ...process.env };
@@ -119,6 +163,56 @@ describe('DeploymentSettingsService — a blank that means the default', () => {
   });
 });
 
+describe('DeploymentSettingsService — the leftover-branch cleanup switch', () => {
+  /**
+   * On by default; an admin switches it off on the Deployment page, and the
+   * environment variable wins over the page, as for every setting.
+   */
+  it('is on by default, off once saved as false, and on again when cleared — after a reload too', async () => {
+    const { db, rows } = makeDb();
+    // Clearing deletes the row: the fake does so for real, so a reload proves it.
+    (db as unknown as { delete: () => unknown }).delete = () => ({
+      where: () => {
+        const at = rows.findIndex((r) => r.key === 'retireMergedBranches');
+        if (at >= 0) rows.splice(at, 1);
+        return Promise.resolve();
+      },
+    });
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    const on = (s: DeploymentSettingsService) => retireMergedBranchesOn(s.resolve('retireMergedBranches'));
+    const reloaded = async () => {
+      const fresh = new DeploymentSettingsService(db, ENC_KEY);
+      await fresh.load();
+      return fresh;
+    };
+    expect(on(settings)).toBe(true);
+    await settings.save({ retireMergedBranches: 'false' }, null);
+    expect(on(settings)).toBe(false);
+    expect(on(await reloaded())).toBe(false);
+    await settings.save({ retireMergedBranches: '' }, null);
+    expect(on(settings)).toBe(true);
+    expect(rows.some((r) => r.key === 'retireMergedBranches')).toBe(false);
+    expect(on(await reloaded())).toBe(true);
+  });
+
+  it('lets RETIRE_MERGED_BRANCHES win over the page', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ retireMergedBranches: 'true' }, null);
+    process.env.RETIRE_MERGED_BRANCHES = 'false';
+    expect(settings.sourceOf('retireMergedBranches')).toBe('env');
+    expect(retireMergedBranchesOn(settings.resolve('retireMergedBranches'))).toBe(false);
+  });
+
+  it('saves only true or false, and reads the ways a person writes "off" as off', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await expect(settings.save({ retireMergedBranches: 'maybe' }, null)).rejects.toBeInstanceOf(SettingsValidationError);
+    for (const off of ['false', 'FALSE', '0', 'off', 'no']) expect(retireMergedBranchesOn(off), off).toBe(false);
+    for (const on of ['', 'true', '1', 'yes']) expect(retireMergedBranchesOn(on), on).toBe(true);
+  });
+});
+
 describe('DeploymentSettingsService — secrets', () => {
   it('stores the token as ciphertext and reads it back', async () => {
     const { db, rows } = makeDb();
@@ -191,8 +285,6 @@ describe('DeploymentSettingsService — KB layout', () => {
       pluginsDir: 'Plugins',
       agentsFile: 'AGENTS.md',
     });
-    // The pointer is on until someone says otherwise.
-    expect(settings.resolveAgentsFileLink()).toBe(true);
   });
 
   /**
@@ -225,9 +317,9 @@ describe('DeploymentSettingsService — KB layout', () => {
   it('ignores the environment for the four layout names', async () => {
     const { db } = makeDb();
     const settings = new DeploymentSettingsService(db, ENC_KEY);
-    await settings.save({ skillsDir: 'skills', pluginsDir: 'plugins', agentsFile: 'HEXIS.md' }, null);
+    await settings.save({ skillsDir: 'skills', pluginsDir: 'plugins' }, null);
     process.env.KB_SKILLS_DIR = 'capabilities';
-    expect(settings.resolveKbLayout()).toMatchObject({ skillsDir: 'skills', agentsFile: 'HEXIS.md' });
+    expect(settings.resolveKbLayout()).toMatchObject({ skillsDir: 'skills' });
     expect(settings.sourceOf('skillsDir')).toBe('stored');
     // Not locked: the field stays editable in the app, and a save of it is
     // accepted rather than refused as 'set by the environment'.
@@ -284,68 +376,41 @@ describe('DeploymentSettingsService — KB layout', () => {
   });
 
   /**
-   * The guide's file name is saved beside the folders and judged with them:
-   * the four must differ, and a name that is not one markdown file is refused
-   * with the rule it broke.
+   * The guide's name was a setting while the guide was written to disk. It is
+   * gone: the setup screen no longer offers it, a save naming it is refused
+   * as unknown, and the guide is read as `AGENTS.md` on every deployment
+   * whatever a deployment saved before.
    */
-  it('refuses a guide name that is not one markdown file of its own', async () => {
-    const { db } = makeDb();
-    const settings = new DeploymentSettingsService(db, ENC_KEY);
-    for (const bad of ['guides/HEXIS.md', 'HEXIS.txt', 'CLAUDE.md', 'access.md', 'roles.yaml']) {
-      await expect(settings.save({ agentsFile: bad }, null)).rejects.toBeInstanceOf(
-        SettingsValidationError,
-      );
-    }
-    await expect(settings.save({ agentsFile: 'HEXIS.md' }, null)).resolves.toBeTruthy();
-  });
-
-  it('refuses a guide named after a root folder, from either side of the pair', async () => {
-    const { db } = makeDb();
-    const settings = new DeploymentSettingsService(db, ENC_KEY);
-    // The plugins folder already in effect, named by the guide alone.
-    await settings.save({ pluginsDir: 'Guide.md' }, null);
-    await expect(settings.save({ agentsFile: 'guide.md' }, null)).rejects.toBeInstanceOf(
-      SettingsValidationError,
-    );
-    // And the other way round, in one batch.
-    await expect(
-      settings.save({ agentsFile: 'HEXIS.md', skillsDir: 'hexis.md' }, null),
-    ).rejects.toBeInstanceOf(SettingsValidationError);
-  });
-
-  it('marks the guide name and its pointer setting as restart-to-apply', async () => {
-    const { db } = makeDb();
+  it('knows no guide name any more: a save naming one is refused, and the layout always says AGENTS.md', async () => {
+    const { db, rows } = makeDb();
+    // The row a deployment saved while the setting existed is still in its
+    // database. It is loaded like any other row, and changes nothing.
+    rows.push({ key: 'agentsFile', value: 'HEXIS.md', encrypted: false });
     const settings = new DeploymentSettingsService(db, ENC_KEY);
-    expect((await settings.save({ agentsFile: 'HEXIS.md' }, null)).restartKeys).toContain('agentsFile');
-    expect((await settings.save({ agentsFileLink: 'false' }, null)).restartKeys).toContain(
-      'agentsFileLink',
-    );
-    expect(settings.resolveAgentsFileLink()).toBe(false);
+    await settings.load();
+    expect(settings.resolveKbLayout().agentsFile).toBe('AGENTS.md');
+    await expect(settings.save({ agentsFile: 'HEXIS.md' }, null)).rejects.toMatchObject({
+      problems: { agentsFile: 'Unknown setting.' },
+    });
+    await expect(settings.save({ agentsFile: 'HEXIS.md' }, null, 'deployment')).rejects.toMatchObject({
+      problems: { agentsFile: 'Unknown setting.' },
+    });
+    expect(settings.resolveKbLayout().agentsFile).toBe('AGENTS.md');
+    expect(settings.describe().map((s) => s.key)).not.toContain('agentsFile');
   });
 
   /**
    * A restart is owed for a CHANGE, and saving what a deployment is already
-   * running on is not one. Both of these settings mean something while unset —
-   * the guide is `AGENTS.md`, the pointer is on — so the first save of that
-   * same answer changes nothing the process would pick up at a restart.
+   * running on is not one. A root name means something while unset — the
+   * default — so the first save of that same answer changes nothing the
+   * process would pick up at a restart.
    */
   it('owes no restart for saving the value an unset setting already meant', async () => {
     const { db } = makeDb();
     const settings = new DeploymentSettingsService(db, ENC_KEY);
-    // The checkbox arrives ticked, and ticked is what an unset one already is.
-    expect((await settings.save({ agentsFileLink: 'true' }, null)).restartKeys).not.toContain(
-      'agentsFileLink',
-    );
-    expect((await settings.save({ agentsFile: 'AGENTS.md' }, null)).restartKeys).not.toContain(
-      'agentsFile',
-    );
     expect((await settings.save({ skillsDir: 'Skills' }, null)).restartKeys).not.toContain('skillsDir');
-    // And the setting still reads as it did.
-    expect(settings.resolveAgentsFileLink()).toBe(true);
-    // Turning it off from there IS a change, and still reports one.
-    expect((await settings.save({ agentsFileLink: 'false' }, null)).restartKeys).toContain(
-      'agentsFileLink',
-    );
+    // Renaming it from there IS a change, and still reports one.
+    expect((await settings.save({ skillsDir: 'Abilities' }, null)).restartKeys).toContain('skillsDir');
   });
 
   /**
@@ -557,3 +622,58 @@ describe('DeploymentSettingsService — an environment of its own', () => {
     expect(shared.resolve('kbRepoUrl')).toBe('https://host.example/leaks-into-every-tenant.git');
   });
 });
+
+describe('DeploymentSettingsService — recordIfAbsent', () => {
+  /**
+   * The claim a once-only flow rests on: the row is the lock, and the
+   * database — shared by every replica — lets exactly one insert through.
+   */
+  it('claims a setting once, and tells the second caller it was not theirs', async () => {
+    const { db, rows } = makeDb();
+    const one = new DeploymentSettingsService(db, ENC_KEY);
+    const two = new DeploymentSettingsService(db, ENC_KEY);
+    await one.load();
+    await two.load();
+
+    expect(await one.recordIfAbsent('starterPack', 'sales', 'u-ada')).toBe(true);
+    expect(await two.recordIfAbsent('starterPack', 'none', 'u-bo')).toBe(false);
+
+    expect(rows.filter((r) => r.key === 'starterPack')).toEqual([{ key: 'starterPack', value: 'sales', encrypted: false }]);
+    expect(one.resolve('starterPack')).toBe('sales');
+    // The loser's cache was not touched: it reads the winner's row on its next `reload`.
+    expect(two.resolve('starterPack')).toBe('');
+  });
+
+  it('is no claim at all with a blank value, which would be a clear', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.load();
+    expect(await settings.recordIfAbsent('starterPack', '', null)).toBe(false);
+    expect(rows).toEqual([]);
+  });
+
+  /**
+   * The conditional swap the claim flows rest on: a value is replaced, or
+   * removed, only while it still reads what the caller saw — so two
+   * replicas acting on one read cannot both succeed.
+   */
+  it('swaps a value only while it still reads what was expected, and removes it the same way', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.load();
+    expect(await settings.recordIfAbsent('starterPackClaim', 'u-a 1', 'u-a')).toBe(true);
+
+    // The value moved under the second caller: refused, untouched.
+    expect(await settings.swapIfValue('starterPackClaim', 'u-z 0', 'u-b 2', 'u-b')).toBe(false);
+    expect(await settings.swapIfValue('starterPackClaim', 'u-a 1', 'u-b 2', 'u-b')).toBe(true);
+    expect(rows.find((r) => r.key === 'starterPackClaim')?.value).toBe('u-b 2');
+    expect(settings.resolve('starterPackClaim')).toBe('u-b 2');
+
+    // A release names its own claim: the holder's row stays for a stale one.
+    expect(await settings.swapIfValue('starterPackClaim', 'u-a 1', null, null)).toBe(false);
+    expect(rows.find((r) => r.key === 'starterPackClaim')?.value).toBe('u-b 2');
+    expect(await settings.swapIfValue('starterPackClaim', 'u-b 2', null, null)).toBe(true);
+    expect(rows.find((r) => r.key === 'starterPackClaim')).toBeUndefined();
+    expect(settings.resolve('starterPackClaim')).toBe('');
+  });
+});

package/src/modules/settings/__tests__/repository-source.test.ts

@@ -124,6 +124,15 @@ describe('RepositorySource: a repository reached through a GitHub App', () => {
     expect(renewed).toBe(1);
   });
 
+  it("hands the app the runner's word that the host refused the token", async () => {
+    const seen: unknown[] = [];
+    const githubApp = app({ prepare: async (opts) => void seen.push(opts) });
+    const { source: s } = source({ gitMode: 'github-app' }, { githubApp });
+    await s.credentials.prepare?.({ refused: true });
+    await s.credentials.prepare?.();
+    expect(seen).toEqual([{ refused: true }, undefined]);
+  });
+
   it('is unanswered on a deployment that has no such app', () => {
     const { source: s } = source({ gitMode: 'github-app' });
     expect(s.answered()).toBe(false);

package/src/modules/settings/deployment-settings.service.ts

@@ -1,4 +1,4 @@
-import { eq, inArray } from 'drizzle-orm';
+import { and, eq, inArray } from 'drizzle-orm';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('settings');
@@ -7,7 +7,6 @@ import { deploymentSettings } from '../database/core-schema.js';
 import {
   DEFAULT_KB_LAYOUT,
   type KbLayout,
-  validateAgentsFileName,
   validateBranchModel,
   validateKbLayout,
   validateKbRootName,
@@ -110,6 +109,16 @@ export const validateHttpsRemote = (value: string): string | null => {
 /**
  * The core catalogue. Order is the order the setup screen renders them in.
  */
+/**
+ * What the `retireMergedBranches` value in effect means: on, unless it says
+ * off. The page saves only `true` or `false`; the environment variable is
+ * typed by a person, so `0`, `off` and `no` (any case) mean off too, and
+ * anything else — unset included — leaves the cleanup on.
+ */
+export function retireMergedBranchesOn(raw: string): boolean {
+  return !/^(false|0|off|no)$/i.test(raw.trim());
+}
+
 export const CORE_SETTINGS: SettingDef[] = [
   {
     /**
@@ -228,14 +237,16 @@ export const CORE_SETTINGS: SettingDef[] = [
   /**
    * The KB layout: the three root folders a deployment may rename so hexis can
    * read a repository laid out by someone else (`skills/` and `plugins/` in
-   * lowercase, say), and the file name of the managed agent guide.
+   * lowercase, say). The agent guide's name is not among them any more: the
+   * guide is served by the platform as `AGENTS.md` everywhere, and a name a
+   * deployment saved for the written guide is ignored.
    * Restart-to-apply like the branch model — the names are applied once at boot
    * through `configureKbLayout` and served to the browser once by
    * `/api/config`. Each has a default, so an unset field means the default, not
-   * an unconfigured deployment. Checked as a QUARTET in `save`: the four must
+   * an unconfigured deployment. Checked as a TRIO in `save`: the three must
    * differ, and one field alone cannot see the other three.
    *
-   * NO `envVar`, on any of the four. Layout is deployment configuration that is
+   * NO `envVar`, on any of the three. Layout is deployment configuration that is
    * entered once in the app; the three that used to be environment-driven are
    * imported into their saved setting on the first boot after the upgrade
    * ({@link DeploymentSettingsService.importLegacyLayoutEnv}) so nothing
@@ -262,37 +273,6 @@ export const CORE_SETTINGS: SettingDef[] = [
     restartToApply: true,
     unsetMeans: DEFAULT_KB_LAYOUT.pluginsDir,
   },
-  {
-    /**
-     * The managed agent guide's file name. Its own validator says what a guide
-     * may be called; the quartet check in `plan` is what keeps it clear of the
-     * three folder names it is saved beside.
-     */
-    key: 'agentsFile',
-    section: 'knowledge-base',
-    // Judged against the default roots here; the quartet check in `plan`
-    // judges it against the roots the same save puts in effect.
-    validate: (v) => validateAgentsFileName(v, DEFAULT_KB_LAYOUT),
-    restartToApply: true,
-    unsetMeans: DEFAULT_KB_LAYOUT.agentsFile,
-  },
-  {
-    /**
-     * Whether to keep the platform's one-sentence pointer in a customer's own
-     * `AGENTS.md` — the admin's consent to the only text the platform ever adds
-     * to a file it does not own. On unless it is explicitly turned off, because
-     * a renamed guide nothing points at is a guide no coding agent will find.
-     *
-     * Restart-to-apply like the name it belongs to: the check runs once per
-     * start, in the KB startup phase.
-     */
-    key: 'agentsFileLink',
-    section: 'knowledge-base',
-    validate: (v) => (v === 'true' || v === 'false' ? null : 'Use "true" or "false".'),
-    restartToApply: true,
-    // On unless explicitly turned off — the reading `resolveAgentsFileLink` applies.
-    unsetMeans: 'true',
-  },
 
 
   /**
@@ -319,6 +299,23 @@ export const CORE_SETTINGS: SettingDef[] = [
     restartToApply: true,
   },
 
+  {
+    /**
+     * Whether the server removes, on its own, the branches merged change
+     * requests left behind (`WorkflowService.retireLeftoverMergedBranches`).
+     * On unless set to `false`; a blanked field puts the default back. Read
+     * at every round, so it applies without a restart. It covers that cleanup
+     * only: the removal of a branch when its change request is merged does
+     * not ask it.
+     */
+    key: 'retireMergedBranches',
+    envVar: 'RETIRE_MERGED_BRANCHES',
+    section: 'knowledge-base',
+    blankMeansDefault: true,
+    unsetMeans: 'true',
+    validate: (v) => (v === 'true' || v === 'false' ? null : 'Either true or false.'),
+  },
+
   {
     /**
      * The credential a git host's webhook or a pipeline presents to
@@ -402,6 +399,35 @@ export const CORE_SETTINGS: SettingDef[] = [
     validate: (v) =>
       parseRetentionWindow(v) === null ? 'Enter a whole number of days, or 0 to keep events forever.' : null,
   },
+
+  {
+    /**
+     * Which starter pack the first admin chose for a new knowledge base — a
+     * pack's id, or `none` for "I'll start from scratch" — written once, by
+     * the deployment, when the choice landed (see
+     * `modules/onboarding/starter-pack.service.ts`). Its presence is what
+     * retires the "What does your team do?" card for good; its value is what
+     * the first-page prompt and the agent's first-run note follow. Internal:
+     * a fact about what happened, not something the setup screen offers.
+     */
+    key: 'starterPack',
+    section: 'knowledge-base',
+    internal: true,
+    validate: (v) => (/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(v) ? null : 'A starter pack id is lowercase letters, digits and hyphens.'),
+  },
+  {
+    /**
+     * The claim an admin holds while their starter-pack choice is being
+     * written: `<user id> <epoch ms>`, inserted only if absent so two replicas
+     * cannot both write, and released once the choice is recorded. A claim
+     * nobody released in time is a process that died mid-write and is taken
+     * over (see `starter-pack.service.ts`). Internal, like the choice.
+     */
+    key: 'starterPackClaim',
+    section: 'knowledge-base',
+    internal: true,
+    validate: (v) => (/^\S+ \d+$/.test(v) ? null : 'A claim is a user id and a time.'),
+  },
 ];
 
 /**
@@ -587,20 +613,10 @@ export class DeploymentSettingsService {
       knowledgeBaseDir: this.resolve('knowledgeBaseDir') || DEFAULT_KB_LAYOUT.knowledgeBaseDir,
       skillsDir: this.resolve('skillsDir') || DEFAULT_KB_LAYOUT.skillsDir,
       pluginsDir: this.resolve('pluginsDir') || DEFAULT_KB_LAYOUT.pluginsDir,
-      agentsFile: this.resolve('agentsFile') || DEFAULT_KB_LAYOUT.agentsFile,
+      agentsFile: DEFAULT_KB_LAYOUT.agentsFile,
     };
   }
 
-  /**
-   * Whether the platform should keep its pointer sentence in a customer-owned
-   * `AGENTS.md`. On unless the admin turned it off — an unset setting is a
-   * deployment that never saw the checkbox, and the sentence is what makes a
-   * renamed guide findable at all.
-   */
-  resolveAgentsFileLink(): boolean {
-    return this.resolve('agentsFileLink') !== 'false';
-  }
-
   /**
    * Import the retired layout environment variables into their saved settings,
    * ONCE, on a deployment that still sets them.
@@ -764,6 +780,61 @@ export class DeploymentSettingsService {
     await this.save(entries, updatedBy, 'deployment');
   }
 
+  /**
+   * {@link record} one value ONLY IF NOTHING IS THERE, and say whether it was
+   * this call that put it there. The row is the claim for a flow that must
+   * happen once across every replica (the starter-pack choice): the insert
+   * yields to a row already there, so of two replicas claiming at once the
+   * database lets exactly one through. Validated as `record` is; a blank
+   * value is no claim (it would be a clear) and answers false.
+   */
+  async recordIfAbsent(key: string, value: string, updatedBy: string | null): Promise<boolean> {
+    const write = this.plan({ [key]: value }, 'deployment').toWrite.find((w) => w.key === key);
+    if (!write) return false;
+    const encrypted = write.def.secret === true;
+    const stored = encrypted ? this.crypto!.encrypt(write.value) : write.value;
+    const inserted = await this.db
+      .insert(deploymentSettings)
+      .values({ key, value: stored, encrypted, updatedBy })
+      .onConflictDoNothing({ target: deploymentSettings.key })
+      .returning({ key: deploymentSettings.key });
+    if (inserted.length === 0) return false;
+    this.stored.set(key, write.value);
+    return true;
+  }
+
+  /**
+   * Replace a plain setting's value ONLY IF it still reads `expected` —
+   * with `next`, or with nothing when `next` is null — and say whether it
+   * was this call that did it. One statement, so of two replicas acting on
+   * what they both read, the database lets exactly one through: the other
+   * finds the value gone or changed and answers false. For the claim flows
+   * that {@link recordIfAbsent} opens: taking over a claim that expired, and
+   * releasing one's own without touching a successor's. Plain settings only;
+   * `next` is validated as {@link record} would.
+   */
+  async swapIfValue(key: string, expected: string, next: string | null, updatedBy: string | null): Promise<boolean> {
+    const def = this.defs.get(key);
+    if (!def || def.secret) return false;
+    const same = and(eq(deploymentSettings.key, key), eq(deploymentSettings.value, expected));
+    if (next === null) {
+      const gone = await this.db.delete(deploymentSettings).where(same).returning({ key: deploymentSettings.key });
+      if (gone.length === 0) return false;
+      this.stored.delete(key);
+      return true;
+    }
+    const write = this.plan({ [key]: next }, 'deployment').toWrite.find((w) => w.key === key);
+    if (!write) return false;
+    const swapped = await this.db
+      .update(deploymentSettings)
+      .set({ value: write.value, updatedBy, updatedAt: new Date() })
+      .where(same)
+      .returning({ key: deploymentSettings.key });
+    if (swapped.length === 0) return false;
+    this.stored.set(key, write.value);
+    return true;
+  }
+
   /** Validate a batch and return the writes (and the clears) it amounts to; throws on any problem. */
   private plan(
     entries: Record<string, string>,
@@ -832,12 +903,12 @@ export class DeploymentSettingsService {
       if (problem) problems.protectedBranches = problem;
     }
 
-    // The layout quartet is the other cross-field rule: three folder names and
-    // a guide file name that must all differ. Judged on the layout this save
-    // WOULD produce, with the default standing in for anything neither written
-    // nor stored — so renaming the plugins folder to what the guide is already
-    // called is refused whichever of the two the save names.
-    const layoutKeys = ['knowledgeBaseDir', 'skillsDir', 'pluginsDir', 'agentsFile'] as const;
+    // The layout trio is the other cross-field rule: three folder names that
+    // must all differ. Judged on the layout this save WOULD produce, with the
+    // default standing in for anything neither written nor stored — so
+    // renaming one folder to what another is already called is refused
+    // whichever of the two the save names.
+    const layoutKeys = ['knowledgeBaseDir', 'skillsDir', 'pluginsDir'] as const;
     if (toWrite.some((w) => (layoutKeys as readonly string[]).includes(w.key))) {
       const effective = (key: (typeof layoutKeys)[number]) =>
         toWrite.find((w) => w.key === key)?.value || this.resolve(key) || DEFAULT_KB_LAYOUT[key];
@@ -845,7 +916,6 @@ export class DeploymentSettingsService {
         knowledgeBaseDir: effective('knowledgeBaseDir'),
         skillsDir: effective('skillsDir'),
         pluginsDir: effective('pluginsDir'),
-        agentsFile: effective('agentsFile'),
       });
       // Against the field being written — the first one in the batch — since
       // any of the three could be the one that collides.
@@ -873,7 +943,7 @@ export class DeploymentSettingsService {
           knowledgeBaseDir: effective('knowledgeBaseDir'),
           skillsDir: effective('skillsDir'),
           pluginsDir: effective('pluginsDir'),
-          agentsFile: effective('agentsFile'),
+          agentsFile: DEFAULT_KB_LAYOUT.agentsFile,
         });
       } catch (err) {
         // Against the field this save is writing — the checkout name when that
@@ -993,6 +1063,25 @@ export class DeploymentSettingsService {
     return `${OIDC_VERIFICATION_PREFIX}${fingerprint}`;
   }
 
+  /**
+   * One plain (never sealed) setting as the DATABASE has it now, taken into
+   * this replica's cache on the way: for the rare setting a running
+   * deployment writes, so a replica that did not serve the write still
+   * answers with it. The environment still wins, as in {@link resolve}.
+   */
+  async reload(key: string): Promise<string> {
+    const def = this.defs.get(key);
+    if (!def || def.secret) return this.resolve(key);
+    const rows = await this.db
+      .select({ value: deploymentSettings.value, encrypted: deploymentSettings.encrypted })
+      .from(deploymentSettings)
+      .where(eq(deploymentSettings.key, key));
+    const row = rows.find((r) => !r.encrypted);
+    if (row) this.stored.set(key, row.value);
+    else this.stored.delete(key);
+    return this.resolve(key);
+  }
+
   /** Remove one stored row (used by tests and by `prune`). */
   async clear(key: string): Promise<void> {
     await this.db.delete(deploymentSettings).where(eq(deploymentSettings.key, key));

package/src/modules/settings/repository-source.ts

@@ -34,7 +34,7 @@ export interface GitHubAppRepository {
    * Make sure {@link token} answers with one that is still good. `asked`
    * is for a caller waiting on the answer itself, who is told a failure.
    */
-  prepare(opts?: { asked?: boolean }): Promise<void>;
+  prepare(opts?: { asked?: boolean; refused?: boolean }): Promise<void>;
   /** Whether the deployment may be pointed at this repository (`owner/name`). */
   permits(repository: string, read: SettingReader): boolean;
   /** Whether the app, its installation and a repository are all there. */
@@ -98,7 +98,7 @@ export class RepositorySource {
     this.credentials = {
       username: () => this.username(),
       token: () => this.token(),
-      prepare: () => this.prepare(),
+      prepare: (opts) => this.prepare(opts),
     };
   }
 
@@ -185,8 +185,8 @@ export class RepositorySource {
     }
   }
 
-  private async prepare(): Promise<void> {
-    if (this.inEffect === 'github-app') await this.opts.githubApp?.prepare();
+  private async prepare(opts?: { refused?: boolean }): Promise<void> {
+    if (this.inEffect === 'github-app') await this.opts.githubApp?.prepare(opts);
   }
 
   private tokenIn(read: SettingReader): string {

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

@@ -64,17 +64,14 @@ const SECRET_FOR_THAT_PROVIDER =
   'Enter the application secret for that provider — the saved one is only sent to the provider it was saved for.';
 
 /**
- * The knowledge-base layout as setting keys: the three renameable roots, the
- * guide's file name, and the consent that rides with it — which the KB startup
- * phase reads through a getter, so the completing save puts it in effect along
- * with the names.
+ * The knowledge-base layout as setting keys: the three renameable roots. The
+ * guide's file name is not one of them — the settings layer sets none, so the
+ * layout it produces carries the default, `AGENTS.md`.
  */
 const LAYOUT_KEYS: readonly string[] = [
   'knowledgeBaseDir',
   'skillsDir',
   'pluginsDir',
-  'agentsFile',
-  'agentsFileLink',
 ];
 /** The branch model, as setting keys. */
 const BRANCH_KEYS: readonly string[] = ['defaultBranch', 'protectedBranches'];