@bevel-software/platform-core-backend 0.21.0 → 0.23.0

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

@@ -31,8 +31,27 @@ import type { KbContext } from '../../shared/kb-context.js';
 import { failureOf, type GitFailure } from '../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { listRootFolders, pickListingBranch } from './git-root-folders.js';
+import { sameRepository } from '../kb-fs/remote-url.js';
+import { MANAGED_DEFAULT_BRANCH } from './managed-repository.js';
+import { GIT_MODES, type GitHubAppRepository, type RepositorySource } from './repository-source.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation
 
+/**
+ * What setup needs of the ways a deployment can be given its repository:
+ * the source every reader of the repository asks, and the one thing a mode
+ * has to have DONE before a save that chooses it may go through.
+ */
+export interface RepositorySetup {
+  source: RepositorySource;
+  /** Create the repository the deployment keeps for itself, if it is not there. Never touches one that is. */
+  ensureManaged(initialBranch: string): Promise<void>;
+  /**
+   * The connection to GitHub through a GitHub App. Absent, that way is not
+   * offered, and a save that names it is refused.
+   */
+  githubApp?: Pick<GitHubAppRepository, 'url' | 'answered' | 'prepare' | 'token' | 'permits'>;
+}
+
 /** Which name a host expects beside the token when none is configured. */
 const DEFAULT_GIT_USERNAME = 'x-access-token';
 
@@ -72,6 +91,49 @@ export interface LastSyncStatus {
   results: Array<{ branch: string; outcome: string; error?: string }>;
 }
 
+/**
+ * The open change requests, as the repository-change confirmation needs them:
+ * how many there are to decide about, and the close the admin may choose.
+ *
+ * Deliberately narrow — the setup routes never read a request, never write
+ * one, and never learn what is in it. Nothing here deletes anything: closing
+ * leaves every row where it is.
+ */
+export interface RepositoryChangeRequests {
+  /** How many change requests are open right now. */
+  countOpen(): Promise<number>;
+  /** Close every open request as "repository replaced", releasing the file locks on their branches. Answers how many closed. */
+  closeAsRepositoryReplaced(): Promise<number>;
+  /**
+   * Run the move with no queued commit being written. The startup phase sets
+   * working copies aside and clones them again while the deployment is
+   * serving, and a commit worker left running would write into a directory
+   * that is being renamed away, or into the fresh clone of a repository the
+   * commit was never meant for. Absent (a minimal mount has no worker), the
+   * move runs as it is.
+   */
+  whileCommitsHeld?<T>(work: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * What the admin is asked to confirm before a save MOVES the deployment to
+ * another repository, and what they answered about its open change requests.
+ *
+ * `keep` — the repository only moved: its branches came along, so the open
+ * change requests still mean something and stay open.
+ * `close` — it is a different repository: none of those branches is in it,
+ * so the requests are closed as "repository replaced" (nothing deleted).
+ *
+ * What happens to the working copies is not a choice, and is decided by the
+ * histories, not by this answer (see the startup phase's
+ * `reconcileClonesWithConfiguredRepository`): a copy whose history the new
+ * repository holds is pointed at it and kept, unpushed commits included; any
+ * other is set aside whole and cloned fresh. Nothing is deleted. The
+ * confirmation exists so that work which leaves the app this way does so
+ * KNOWINGLY.
+ */
+export type RepositoryChangeChoice = 'keep' | 'close';
+
 /**
  * First-run setup — the deployment's own configuration, for the things that
  * used to be environment-only.
@@ -138,8 +200,24 @@ export function createSetupRoutes(
   checkOidc: (config: OidcConfiguration) => Promise<OidcCheck> = checkOidcConfiguration,
   /** The issuer-only half, for a test with no application id or secret yet. */
   checkIssuer: (issuerUrl: string) => Promise<IssuerCheck> = (url) => checkOidcIssuer(url),
+  /**
+   * The ways a deployment can be given its repository. Absent, there is the
+   * one there always was: an address and a token, read from the settings.
+   */
+  repository?: RepositorySetup,
+  /**
+   * What a change of the knowledge-base repository has to decide about, and
+   * what to do when the admin decides to close.
+   *
+   * Injected because the setup routes must stay free of the workflow module —
+   * and a minimal mount (tests, a distribution without change requests) simply
+   * has none: the default answers "no open requests", so the confirmation
+   * offers no choice it cannot honour.
+   */
+  changeRequests: RepositoryChangeRequests = { async countOpen() { return 0; }, async closeAsRepositoryReplaced() { return 0; } },
 ): express.Router {
   const router = express.Router();
+  const source = repository?.source;
 
   /**
    * Why the last setup-time run of the KB startup phase FAILED, or null. While
@@ -184,7 +262,30 @@ export function createSetupRoutes(
   };
   /** The app-gate answer: settings complete AND the KB phase settled clean, whoever ran it. */
   const kbReady = () =>
-    isComplete(settings, kb) && kbInit === null && kbInitInFlight === null && bootFailure() === null;
+    isComplete(settings, kb, source) && kbInit === null && kbInitInFlight === null && bootFailure() === null;
+
+  /**
+   * Which ways of having a repository this deployment offers and which one
+   * it is on, for the setup screen. `mode` is the one IN EFFECT, inferred
+   * for a deployment that never chose; `chosen` is the one the settings
+   * say, which differs from it between a move and the restart the move
+   * owes. The screen opens on what was chosen, says a restart is pending
+   * when the two differ, and offers the first of `modes` to a deployment
+   * that has none. `pinned` names the variable that chose for the
+   * deployment, when one did. Nothing at all from a mount without the
+   * choice, which the screen reads as the one way there was.
+   */
+  const repositoryStatus = () =>
+    source
+      ? {
+          repository: {
+            mode: source.mode(),
+            chosen: source.chosen(),
+            ...(settings.sourceOf('gitMode') === 'env' ? { pinned: 'GIT_MODE' } : {}),
+            modes: GIT_MODES.filter((mode) => mode !== 'github-app' || repository?.githubApp !== undefined),
+          },
+        }
+      : {};
 
   const requireAdmin: express.RequestHandler = async (req, res, next) => {
     if (!(await adminAccess.isAdmin(req.userEmail))) {
@@ -219,9 +320,10 @@ export function createSetupRoutes(
     }
     res.json({
       complete: kbReady(),
-      awaitingRestart: awaitingRestart(settings, kb),
+      awaitingRestart: awaitingRestart(settings, kb, source),
       isAdmin: true,
       settings: settings.describe(),
+      ...repositoryStatus(),
       oidcVerification: await settings.oidcVerification(),
       ...(kbInit ? { kbInit } : bootFailure() !== null ? { kbInit: bootFailureKind() } : {}),
       ...(sync ? { sync: { url: sync.url, last: sync.lastSync() } } : {}),
@@ -251,7 +353,15 @@ export function createSetupRoutes(
   });
 
   async function handleSave(req: express.Request, res: express.Response): Promise<void> {
-    const body = (req.body ?? {}) as { settings?: Record<string, unknown> };
+    const body = (req.body ?? {}) as {
+      settings?: Record<string, unknown>;
+      /** The admin's answer to the repository-change confirmation, when they have given one. */
+      confirmRepositoryChange?: unknown;
+      /** The count of open change requests that answer was given about. */
+      seenOpenChangeRequests?: unknown;
+    };
+    /** Lets the commit worker go again, once a move has held it. */
+    let releaseCommits: (() => void) | undefined;
     const entries: Record<string, string> = {};
     for (const [key, value] of Object.entries(body.settings ?? {})) {
       if (typeof value !== 'string') {
@@ -265,8 +375,40 @@ export function createSetupRoutes(
       // 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, kb);
+      const wasComplete = isComplete(settings, kb, source);
+      // A different question, asked of the GATE: whether anyone is being
+      // served. Settings that are answered are not a deployment that works
+      // — one whose first clone failed has answered everything and serves
+      // nobody.
+      const wasServing = kbReady();
+      nameBranchesOfManagedRepository(entries);
       if (!(await connectionHoldsFor(entries, wasComplete, res))) return;
+      // AFTER the connection check, BEFORE anything is stored. After, because
+      // an address the host will not answer for is refused on its own terms
+      // and there is then nothing to confirm — nobody should have to agree to
+      // losing their working copies only to be told the token was missing.
+      // Before, because a refused save must destroy nothing: the check only
+      // reads the new address and dry-runs a push to it.
+      // Asked only of a deployment that has SERVED on the repository it would
+      // leave. A first run whose initialisation failed has answered
+      // everything and served nobody: correcting its address is finishing
+      // setup, and a question about leaving a repository nobody ever worked
+      // on would be a question with nothing behind it.
+      const hasServed = wasComplete && kbInit === null;
+      const repositoryChange = await repositoryChangeFor(
+        entries,
+        body.confirmRepositoryChange,
+        body.seenOpenChangeRequests,
+        hasServed,
+        res,
+      );
+      if (!repositoryChange) return;
+      // HELD FROM HERE, before anything is stored. The way chosen takes
+      // effect a few lines down, and with it the credential git is handed; a
+      // commit worker still running in between would push a queued commit
+      // from a working copy of the repository being left, with the
+      // credential of the one moved to. Let go in the `finally` below.
+      if (repositoryChange.changing) releaseCommits = await holdCommits();
       const oidc = await signInHoldsFor(entries, res);
       if (!oidc) return;
       // Recorded BEFORE the save: the record is keyed by the values it is
@@ -277,7 +419,75 @@ export function createSetupRoutes(
       if (oidc.record) {
         await settings.recordOidcVerification(oidc.record.state, oidc.record.credentials);
       }
-      const { restartRequired, restartKeys } = await settings.save(entries, req.userId ?? null);
+      /**
+       * How many open change requests this save closed as "repository
+       * replaced". Nothing is ever deleted; `keep` leaves them exactly as they
+       * are, and answers 0.
+       *
+       * Closed BEFORE the address is stored, as a PRECONDITION of the save. A
+       * close that fails after the address is stored has nowhere to go: the
+       * address now matches, so the next save sees no change, asks nothing and
+       * never retries — leaving requests open on branches the new repository
+       * does not have, and their file locks refusing paths to everybody else,
+       * with no way for the admin to put it right. Refusing the save instead
+       * destroys nothing: the old address still stands, the working copies are
+       * untouched (the phase below never ran), and pressing Save again asks the
+       * same question and tries again.
+       *
+       * The other order of failure — closed, then the save itself fails — is
+       * recoverable by the admin, who wanted these requests closed and whose
+       * next Save completes the replacement. Closing deletes nothing either
+       * way.
+       */
+      let closedChangeRequests = 0;
+      if (repositoryChange.choice === 'close') {
+        try {
+          closedChangeRequests = await changeRequests.closeAsRepositoryReplaced();
+        } catch (err) {
+          log.error('the open change requests could not be closed, so the repository was not replaced:', { err });
+          res.status(500).json({
+            error:
+              'The open change requests could not be closed, so the repository was not changed. ' +
+              'Nothing was saved and no working copy was touched. Try again.',
+          });
+          return;
+        }
+      }
+      const saved = await settings.save(entries, req.userId ?? null);
+      /**
+       * THE WAY CHOSEN TAKES EFFECT ON THIS SAVE, in the two cases where the
+       * startup phase below runs for it.
+       *
+       * A deployment that was not serving has nothing on the mode it had: a
+       * first run, one whose initialisation failed, a boot that found its
+       * repository unreachable. Pinned there, the way out of a repository
+       * that does not work would be closed.
+       *
+       * And a deployment that WAS serving, when its admin has just confirmed
+       * the move. The mode in effect was once held until the next restart, so
+       * that the running process never presented one way's credential to
+       * another way's repository. That reason is answered differently now:
+       * the phase below sets the working copies of the repository that was
+       * left aside, under a held commit worker, before anything uses the new
+       * credential. And an admin of a hosted workspace has no restart to
+       * give, so a move that waited for one never happened.
+       *
+       * What is left pinned is a save that changes the mode WITHOUT moving
+       * the repository, which no path produces today; it keeps the restart.
+       */
+      if (source && (!wasServing || repositoryChange.changing)) source.takeEffect();
+      /**
+       * The restart the mode owes is read off the two modes themselves, not
+       * off what this save wrote: it is owed for as long as the mode chosen
+       * is not the one in effect, whichever save chose it, and no longer
+       * once a save chooses the mode in effect back.
+       */
+      const modePending = source !== undefined && source.chosen() !== source.mode();
+      const restartKeys = [
+        ...saved.restartKeys.filter((key) => key !== 'gitMode'),
+        ...(modePending ? ['gitMode'] : []),
+      ];
+      const restartRequired = restartKeys.length > 0;
       /** Whether this save put the stored folder names into the running process. */
       let layoutApplied = false;
       /** Whether this save put the stored branch model into the running process. */
@@ -316,11 +526,27 @@ export function createSetupRoutes(
        * 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 (`kbInit`), so a save 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.
+       * setup-time run stands failed (`kbInit`), so a save is the retry.
+       *
+       * AND on a save that MOVES THE REPOSITORY, complete and healthy or
+       * not. That one is not a quiet moment — the gate is open and sessions
+       * may be live — but it is the moment the working copies stop belonging
+       * to the configured repository, and leaving them until the next restart
+       * is what made Save and Retry fail against a repository that was gone.
+       * The admin has just confirmed the move, so the phase runs, with the
+       * commit worker held for as long as it does, and the app opens on the
+       * new repository's content.
+       *
+       * Never on an ordinary re-save of a complete, healthy setup: with the
+       * gate open, sessions may be live and nothing needs doing.
        */
-      if ((!wasComplete || kbInit !== null || bootFailure() !== null) && isComplete(settings, kb)) {
+      if (
+        (!wasComplete ||
+          kbInit !== null ||
+          bootFailure() !== null ||
+          repositoryChange.changing) &&
+        isComplete(settings, kb, source)
+      ) {
         /**
          * The folder names, applied BEFORE the phase for the same reason as
          * the branch model above: they are otherwise applied once at boot, so
@@ -343,6 +569,9 @@ export function createSetupRoutes(
           // 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.
+          // A move runs with the commit worker held (see `holdCommits`
+          // above): nothing queued is written while working copies are set
+          // aside and cloned again.
           kbInitInFlight ??= kbStartupRunner.runAll();
           await kbInitInFlight;
           // Under KB_SAFE_BOOT a run that abandoned the phase still resolves
@@ -360,6 +589,7 @@ export function createSetupRoutes(
           const raw = initErr instanceof Error ? initErr.message : String(initErr);
           const msg = redactSecret(raw, [
             settings.resolve('gitToken'),
+            source?.credentials.token() ?? '',
             ...urlQuerySecrets(settings.resolve('kbRepoUrl')),
           ]);
           log.error(`KB initialization failed after setup completed: ${msg}`);
@@ -386,9 +616,15 @@ export function createSetupRoutes(
               )
             : restartRequired,
         complete: kbReady(),
-        awaitingRestart: awaitingRestart(settings, kb),
+        awaitingRestart: awaitingRestart(settings, kb, source),
         settings: settings.describe(),
+        ...repositoryStatus(),
         oidcVerification: await settings.oidcVerification(),
+        // Only on the save that changed the repository, so an ordinary save
+        // carries no word about change requests at all.
+        ...(repositoryChange.changing
+          ? { repositoryChange: { choice: repositoryChange.choice, closedChangeRequests } }
+          : {}),
       });
     } catch (err) {
       if (err instanceof SettingsValidationError) {
@@ -399,9 +635,193 @@ export function createSetupRoutes(
       // the schema or the connection string.
       log.error('save failed:', { err });
       res.status(500).json({ error: 'Could not save these settings.' });
+    } finally {
+      releaseCommits?.();
     }
   }
 
+  /**
+   * Stop the commit worker until the function this resolves to is called.
+   * The hold the composition root offers runs a piece of work with the
+   * worker stopped; a move spans the store, the way taking effect and the
+   * startup phase, with refusals in between, so the hold is taken here and
+   * let go in the handler's `finally`. A mount without a worker holds
+   * nothing.
+   */
+  function holdCommits(): Promise<() => void> {
+    if (!changeRequests.whileCommitsHeld) return Promise.resolve(() => {});
+    return new Promise((held, failed) => {
+      changeRequests.whileCommitsHeld!<void>(() => new Promise<void>((release) => held(release))).catch(failed);
+    });
+  }
+
+  /**
+   * What this save does to the knowledge-base repository, and whether the
+   * admin has said yes to it.
+   *
+   * A MOVE IS ANY SAVE AFTER WHICH THE DEPLOYMENT READS ANOTHER REPOSITORY
+   * than the one it is running on, however it came about: another address,
+   * another way of having the repository (managed, GitHub, address and
+   * token), another repository on GitHub. So the question is asked of the
+   * one thing that knows where the repository is under every way — the
+   * repository source — comparing the address IN EFFECT with the one this
+   * save would choose. A mount without a source has the one way there
+   * always was, and the address is the setting.
+   *
+   * A move takes the working copies of the repository that is left out of
+   * use: one whose history the new repository holds is pointed at it and
+   * kept, any other is set aside and cloned fresh. Work that was never
+   * pushed leaves the app with a copy that is set aside. That is not
+   * something to discover afterwards, so the save is REFUSED (409) until the
+   * answer comes back with the admin's decision.
+   *
+   * Only a real move asks: an address that differs from the one in effect in
+   * nothing but its spelling — a trailing slash, a `.git` suffix, the case
+   * of the host — is the same repository (see `kb-fs/remote-url.ts`), and so
+   * is a first-run save, where no repository is in effect and nothing on
+   * disk could be left.
+   *
+   * Returns null when it has already answered the request.
+   */
+  async function repositoryChangeFor(
+    entries: Record<string, string>,
+    confirmation: unknown,
+    /** How many open change requests the screen showed when the answer was given, when it says. */
+    seenOpenChangeRequests: unknown,
+    /** Whether the deployment is serving on the repository in effect. One that never served and has no open request is not asked. */
+    hasServed: boolean,
+    res: express.Response,
+  ): Promise<{ changing: boolean; choice: RepositoryChangeChoice | null } | null> {
+    const unchanged = { changing: false, choice: null } as const;
+    const after = settings.resolveAfter(entries);
+    const now = (source ? source.url() : settings.resolve('kbRepoUrl')).trim();
+    const next = (source ? source.url(after) : after('kbRepoUrl')).trim();
+    if (now === '' || next === '' || sameRepository(now, next)) return unchanged;
+    // The count is what the choice is ABOUT, so it is read here rather than
+    // left for the screen to ask for separately: the two questions would
+    // otherwise be answered a round trip apart, and the number on screen
+    // would be the one from before whatever happened in between.
+    const openChangeRequests = await changeRequests.countOpen();
+    // An answer stands for the count it was given about. A request opened
+    // while the question stood was never offered "close", and the "keep" the
+    // screen sends when there is nothing to choose would decide it unasked:
+    // the question is put again, with the count as it is now.
+    const answered = confirmation === 'keep' || confirmation === 'close';
+    const answerIsCurrent = typeof seenOpenChangeRequests !== 'number' || seenOpenChangeRequests === openChangeRequests;
+    if (answered && answerIsCurrent) return { changing: true, choice: confirmation };
+    // A move all the same, and the phase treats it as one; nobody is asked.
+    // Open change requests are themselves proof that the deployment served,
+    // whatever `hasServed` says: a move that failed part-way leaves it gated
+    // with a failure standing, and the next save must still ask about them.
+    if (!answered && !hasServed && openChangeRequests === 0) return { changing: true, choice: null };
+    res.status(409).json({
+      error: 'This moves the deployment to another repository.',
+      repositoryChange: {
+        openChangeRequests,
+        // The way left and the way moved to, for the screen to name them.
+        // Equal when the move is within one way (another address, another
+        // repository on GitHub); absent from a mount with one way only.
+        ...(source ? { from: source.mode(), to: source.mode(after) } : {}),
+      },
+    });
+    return null;
+  }
+
+  /**
+   * A repository the deployment keeps for itself is new, and empty, and has
+   * no branches for anyone to look up: the branch model is ours to name. It
+   * is named only when nobody has — an admin's own answer, or one the
+   * environment supplies, stands. Every other mode has a repository that
+   * already exists, whose branches are asked for, never guessed.
+   */
+  function nameBranchesOfManagedRepository(entries: Record<string, string>): void {
+    if (!source) return;
+    const after = settings.resolveAfter(entries);
+    if (source.mode(after) !== 'managed') return;
+    if (after('defaultBranch') || after('protectedBranches')) return;
+    entries.defaultBranch = MANAGED_DEFAULT_BRANCH;
+    entries.protectedBranches = MANAGED_DEFAULT_BRANCH;
+  }
+
+  /**
+   * The same rule for a repository reached through a GitHub App: a saved
+   * connection is one GitHub has accepted for reading and writing, asked
+   * with the token git will present, which is the installation's.
+   *
+   * That token is also what keeps the repository's NAME honest. It is the
+   * one part of this connection an admin types, and a name the installation
+   * does not reach is refused here by GitHub, not by a list of ours.
+   *
+   * The repository has just said what it calls its trunk, so a deployment
+   * with no branch model is given that one: the same answer the setup
+   * screen fills in for a repository reached by its address.
+   */
+  async function githubConnectionHoldsFor(
+    setup: RepositorySetup,
+    entries: Record<string, string>,
+    after: (key: string) => string,
+    wasComplete: boolean,
+    res: express.Response,
+  ): Promise<boolean> {
+    const refuse = (problem: string, field = 'githubRepository') => {
+      res.status(400).json({ error: problem, problems: { [field]: problem } });
+      return false;
+    };
+    const app = setup.githubApp;
+    if (!app) return refuse('This deployment cannot connect to GitHub through a GitHub App.', 'gitMode');
+    if (!app.answered(after)) {
+      return refuse(
+        after('githubRepository')
+          ? 'Connect GitHub before choosing a repository.'
+          : 'Choose the repository the knowledge base lives in.',
+      );
+    }
+    const url = app.url(after);
+    const unanswered =
+      validateBranchModel({ defaultBranch: after('defaultBranch'), protectedBranches: after('protectedBranches') }) !== null;
+    // Against what is CHOSEN now, not what is in effect: a repository that
+    // was proven by the save that chose it is not proven again by the next.
+    const stored = (key: string) => settings.resolve(key);
+    const changes = setup.source.chosen() !== 'github-app' || url !== setup.source.url(stored);
+    if (!changes && (wasComplete || unanswered)) return true;
+    // BEFORE GitHub is asked anything with the installation token: that
+    // token reaches every repository the installation covers, and would
+    // answer for one the person connecting it could never have written to.
+    if (!app.permits(after('githubRepository'), after)) {
+      log.warn('a repository was named that the person who connected GitHub could not push to');
+      return refuse(
+        'Choose a repository your own GitHub account can write to. If this one should be, press “Refresh the list” so it is brought up to date.',
+      );
+    }
+    try {
+      await app.prepare({ asked: true });
+    } catch (err) {
+      log.error('GitHub gave no token for the installation:', { detail: err instanceof Error ? err.message : String(err) });
+    }
+    const token = app.token();
+    if (!token) {
+      return refuse('GitHub gave this deployment no access. The app may have been uninstalled: connect it again.', 'gitMode');
+    }
+    const check = await checkConnection({ url, token, username: DEFAULT_GIT_USERNAME });
+    if (check.outcome !== 'connected') {
+      return refuse(
+        check.outcome === 'read-only'
+          ? 'The GitHub App can read that repository but not write to it. Grant it write access to the repository’s contents.'
+          : check.reason === 'unreachable'
+            ? 'GitHub could not be reached. Try again shortly.'
+            : 'The GitHub App cannot reach that repository. Add the repository to the app’s installation on GitHub.',
+      );
+    }
+    if (!after('defaultBranch') && !after('protectedBranches')) {
+      const trunk = check.defaultBranch || check.branches[0] || (check.empty ? MANAGED_DEFAULT_BRANCH : '');
+      if (trunk) {
+        entries.defaultBranch = trunk;
+        entries.protectedBranches = trunk;
+      }
+    }
+    return true;
+  }
+
   /**
    * A SAVED CONNECTION IS ONE THE HOST HAS ACCEPTED FOR READING AND WRITING.
    *
@@ -427,6 +847,25 @@ export function createSetupRoutes(
     res: express.Response,
   ): Promise<boolean> {
     const after = settings.resolveAfter(entries);
+    if (repository && repository.source.mode(after) === 'managed') {
+      // Nothing to prove to a host: the repository is the deployment's own.
+      // What has to hold is that it EXISTS before the save that points
+      // everything at it, so a disk that cannot take it refuses the choice
+      // instead of failing the first clone.
+      try {
+        await repository.ensureManaged(after('defaultBranch') || MANAGED_DEFAULT_BRANCH);
+        return true;
+      } catch (err) {
+        log.error('the managed repository could not be created:', { err });
+        const problem =
+          'The repository could not be created on this deployment’s storage. Check that its backups folder is writable, or connect a repository of your own.';
+        res.status(400).json({ error: problem, problems: { gitMode: problem } });
+        return false;
+      }
+    }
+    if (repository && repository.source.mode(after) === 'github-app') {
+      return githubConnectionHoldsFor(repository, entries, after, wasComplete, res);
+    }
     const now: RepositoryConnection = {
       url: settings.resolve('kbRepoUrl'),
       token: settings.resolve('gitToken'),
@@ -451,7 +890,10 @@ export function createSetupRoutes(
     // the environment, whose field the form cannot even edit) is that token's
     // first and only pairing, not a change of it.
     const tokenSupplied = Boolean(entries.gitToken?.trim());
-    if (now.url && next.url !== now.url && next.token && !tokenSupplied) {
+    // A different SPELLING of the configured address is the same repository,
+    // so the stored token is still the token it was saved for: asking for it
+    // again over a trailing slash would be a question with no answer.
+    if (now.url && !sameRepository(next.url, now.url) && next.token && !tokenSupplied) {
       return settings.sourceOf('gitToken') === 'env'
         ? refuse({
             kbRepoUrl:
@@ -763,8 +1205,12 @@ export function createSetupRoutes(
  * deployment signs in perfectly well without it, and gating on it would lock
  * an admin out of the screen where they would set it up.
  */
-export function settingsAnswered(settings: DeploymentSettingsService): boolean {
-  const kb = Boolean(settings.resolve('kbRepoUrl') && settings.resolve('gitToken'));
+export function settingsAnswered(
+  settings: DeploymentSettingsService,
+  /** What answers for the repository. Absent: an address and a token, the one way there was. */
+  source?: Pick<RepositorySource, 'answered'>,
+): boolean {
+  const kb = source ? source.answered() : Boolean(settings.resolve('kbRepoUrl') && settings.resolve('gitToken'));
   const branches =
     validateBranchModel({
       defaultBranch: settings.resolve('defaultBranch'),
@@ -791,14 +1237,16 @@ export function settingsAnswered(settings: DeploymentSettingsService): boolean {
 export function isComplete(
   settings: DeploymentSettingsService,
   kb: Pick<KbContext, 'isBranchModelConfigured'>,
+  source?: Pick<RepositorySource, 'answered'>,
 ): boolean {
-  return settingsAnswered(settings) && kb.isBranchModelConfigured();
+  return settingsAnswered(settings, source) && kb.isBranchModelConfigured();
 }
 
 /** Answered, but not yet in effect: everything is stored, the process is stale. */
 export function awaitingRestart(
   settings: DeploymentSettingsService,
   kb: Pick<KbContext, 'isBranchModelConfigured'>,
+  source?: Pick<RepositorySource, 'answered'>,
 ): boolean {
-  return settingsAnswered(settings) && !kb.isBranchModelConfigured();
+  return settingsAnswered(settings, source) && !kb.isBranchModelConfigured();
 }

package/src/modules/skills/__tests__/allowed-tools-warn.tools.test.ts

@@ -12,6 +12,7 @@ import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
@@ -111,7 +112,7 @@ async function start(): Promise<string> {
   registerWorkspaceTools(
     registry, router, fakeAuth, toolHandler,
     new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
-    { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
     new RoutineWritePolicyService(),
     {} as never,
     checker,