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

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

@@ -31,8 +31,26 @@ 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 { 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';
 
@@ -138,8 +156,14 @@ 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,
 ): 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 +208,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 +266,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() } } : {}),
@@ -265,7 +313,13 @@ 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;
       const oidc = await signInHoldsFor(entries, res);
       if (!oidc) return;
@@ -277,7 +331,35 @@ 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);
+      const saved = await settings.save(entries, req.userId ?? null);
+      /**
+       * A deployment that was not serving has nothing on the mode it had:
+       * the mode chosen takes effect now, and the startup phase below is
+       * what a restart would have run. One that WAS serving stays on the
+       * mode it is on, working copies and credential alike, until it is
+       * started again.
+       *
+       * SERVING, not answered. The pin protects what is running on the
+       * mode in effect, and behind a shut gate nothing is: a first run
+       * 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 — the admin chooses another, the retry
+       * below runs against the one that just failed, and the screen asks
+       * for a restart that changes nothing.
+       */
+      if (source && !wasServing) 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. */
@@ -320,7 +402,7 @@ export function createSetupRoutes(
        * 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 || kbInit !== null || bootFailure() !== null) && isComplete(settings, kb)) {
+      if ((!wasComplete || kbInit !== null || bootFailure() !== null) && 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
@@ -360,6 +442,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,8 +469,9 @@ export function createSetupRoutes(
               )
             : restartRequired,
         complete: kbReady(),
-        awaitingRestart: awaitingRestart(settings, kb),
+        awaitingRestart: awaitingRestart(settings, kb, source),
         settings: settings.describe(),
+        ...repositoryStatus(),
         oidcVerification: await settings.oidcVerification(),
       });
     } catch (err) {
@@ -402,6 +486,101 @@ export function createSetupRoutes(
     }
   }
 
+  /**
+   * 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 +606,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'),
@@ -763,8 +961,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 +993,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__/skill-access-requests.routes.test.ts

@@ -27,15 +27,19 @@ const FOLDER = 'Skills/Eng/deploy';
 
 async function makeHarness(listBranches: IWorkflowService['listBranches']) {
   const workflow = {
-    listChangeRequestsAuthoredBy: vi.fn(async () => []),
+    listChangeRequests: vi.fn(async () => []),
     listBranches: vi.fn(listBranches),
     createBranch: vi.fn(async () => ({ name: 'x', isDefault: false, isProtected: false })),
+    deleteBranch: vi.fn(async () => undefined),
     commitChanges: vi.fn(async () => null),
     openChangeRequest: vi.fn(async () => ({ number: 42 })),
+    getChangeRequestDetail: vi.fn(async () => ({ body: '' })),
   } as unknown as IWorkflowService;
   const workspaceService = {
     getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: workspaceIdForBranch(branch) })),
     readFile: vi.fn(async () => '---\n---\nwrite:\n  - Eve <eve@x.io>\n'),
+    readFileAtRef: vi.fn(async () => null),
+    ensureRemotesFetched: vi.fn(async () => undefined),
     writeFile: vi.fn(async () => undefined),
   } as unknown as WorkspaceService;
   const accessControl = { canWrite: vi.fn(async () => false) } as unknown as IAccessControl;

package/src/modules/skills/skill-access-requests.routes.ts

@@ -3,16 +3,12 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('skills');
 import '../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
-import {
-  joinBranchFor,
-  type AuthUser,
-  type IWorkflowService,
-} from '@bevel-software/platform-shared';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { spliceGrant } from '../access-model/access-splice.js';
+import { folderTarget } from '../access/access-requests.contract.js';
+import { AccessRequestsService } from '../access/access-requests.service.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
-import { isAbsence } from '../../shared/fs.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { JoinRequestsService } from '../plugins/join-requests.service.js';
@@ -28,13 +24,11 @@ import type { ISkillService } from './skills.contract.js';
  *
  * Why it exists: linking a skill into a plugin needs write on the skill's
  * rules (the link grants the plugin's principal there), and a plugin manager
- * often has no say over a skill some other scope owns. The request is a plain
- * change request whose branch splices `write: <requester>` into the skill
- * folder's `access.md`; the skill's editors see its proposals and accept
- * through the ordinary grant path, and it retires itself once the default
- * branch carries the grant (`JoinRequestsService`, keyed on the skill FOLDER
- * path rather than a plugin name — the branch-name convention takes any
- * exact string).
+ * often has no say over a skill some other scope owns. The request is opened
+ * by the shared `AccessRequestsService` — the same one the Manage access
+ * dialog's Request access uses — keyed on the skill FOLDER path, so this
+ * button and a Can edit request on that same folder are ONE request, shown in
+ * the skill page's banner and in the folder's dialog alike.
  *
  * Fail-closed like the skill catalog: a skill the caller cannot read answers
  * as unknown, and the editors' listing answers `[]` to anyone else.
@@ -49,10 +43,18 @@ export function createSkillAccessRequestRoutes(deps: {
   resolveUser: (req: express.Request) => Promise<AuthUser | null>;
 }): express.Router {
   const { skillService, accessControl, workflow, workspaceService, joinRequests, kb, resolveUser } = deps;
-  const { kbDirName } = kb;
   const router = express.Router();
   const wsId = () => kb.defaultWorkspaceId();
   const rulesOf = (folder: string) => `${folder}/access.md`;
+  // The same opener the Manage access dialog uses, pointed at a skill's
+  // folder. Keyed on that folder's PATH, which is what makes this button and
+  // a Can edit request on the same folder one request rather than two.
+  const requests = new AccessRequestsService({
+    workflow,
+    workspaceService,
+    lifecycle: joinRequests,
+    kb,
+  });
 
   /** The skill the caller may read, by name — or null after answering 404. */
   async function readableSkill(
@@ -82,65 +84,13 @@ export function createSkillAccessRequestRoutes(deps: {
         res.status(409).json({ error: 'You can already edit this skill', kind: 'already-writable' });
         return;
       }
-      const branch = joinBranchFor(user.email, folder);
-      // FRESH: a repeated click must find the request the previous one opened,
-      // and the cached listing can trail it — a miss here would send the
-      // retry into a duplicate refusal.
-      const existing = (await workflow.listChangeRequestsAuthoredBy(user.email, { fresh: true })).find(
-        (cr) => cr.state === 'open' && cr.branch === branch,
-      );
-      if (existing) {
-        res.json({ ok: true, number: existing.number });
-        return;
-      }
-      // The branch may already exist (a request listed as closed, a retry
-      // after a failed open). Existence is PROBED, before and — if creation
-      // fails — after: the race shows up as "already exists" locally or as a
-      // rejected push when origin got there first, and a message is not a
-      // contract. A branch that is there is proceeded against; anything else
-      // is a real failure, and a proposal on a branch that was not made would
-      // be worse than the error. STRICT: the list proves absence, and a
-      // listing that could not fetch proves nothing — it throws instead of
-      // serving refs from before the branch was made (or deleted).
-      const branchExists = async () =>
-        (await workflow.listBranches(wsId(), { freshFetch: true, strictFetch: true })).some(
-          (b) => b.name === branch,
-        );
-      if (!(await branchExists())) {
-        try {
-          await workflow.createBranch(wsId(), branch, kb.defaultBranch);
-        } catch (err) {
-          if (!(await branchExists())) throw err;
-        }
-      }
-      const ws = await workspaceService.getOrCreateForBranch(branch);
-      const accessPath = `${kbDirName}/${rulesOf(folder)}`;
-      // Only a PROVEN absence reads as "no rules yet": any other failure must
-      // not be turned into an empty file that a splice then overwrites.
-      const current = await workspaceService.readFile(ws.id, accessPath).catch((err: unknown) => {
-        if (!isAbsence(err)) throw err;
-        return '';
-      });
-      const spliced = spliceGrant(
-        current,
-        'write',
-        { kind: 'user', email: user.email, displayName: user.name },
-        { target: 'folder' },
-      );
-      if (spliced.changed) {
-        await workspaceService.writeFile(ws.id, accessPath, spliced.text);
-        await workflow.commitChanges(ws.id, user, `Request write access to ${name}`);
-      }
-      const detail = await workflow.openChangeRequest(ws.id, user, {
-        sourceBranch: branch,
-        targetBranch: kb.defaultBranch,
-        title: `Access request: ${name}`,
-        description:
-          `${user.name} asked to edit the skill ${name}. An editor of the skill accepts by ` +
-          `granting the access this branch proposes; the request closes itself once ` +
-          `every proposal has landed.`,
+      const { number } = await requests.open({
+        user,
+        target: folderTarget(folder),
+        itemName: name,
+        level: 'write',
       });
-      res.json({ ok: true, number: detail.number });
+      res.json({ ok: true, number });
     } catch (err) {
       if (err instanceof WorkflowDomainError) {
         res.status(err.status).json(domainErrorBody(err));
@@ -171,7 +121,7 @@ export function createSkillAccessRequestRoutes(deps: {
       const ctx = await requireEditor(req, res, () => res.json({ requests: [] }));
       if (!ctx) return;
       const crs = await workflow.listChangeRequests();
-      res.json({ requests: await joinRequests.list(ctx.folder, ctx.folder, crs, ctx.user) });
+      res.json({ requests: await joinRequests.list(ctx.folder, folderTarget(ctx.folder), crs, ctx.user) });
     } catch (err) {
       log.error('failed to list access requests:', { err });
       res.status(500).json({ error: 'Failed to list access requests' });
@@ -192,7 +142,7 @@ export function createSkillAccessRequestRoutes(deps: {
         res.status(404).json({ error: 'Not found' });
         return;
       }
-      res.json({ closed: await joinRequests.reconcile(ctx.folder, ctx.folder, cr, ctx.user) });
+      res.json({ closed: await joinRequests.reconcile(ctx.folder, folderTarget(ctx.folder), cr, ctx.user) });
     } catch (err) {
       log.error('failed to reconcile an access request:', { err });
       res.status(500).json({ error: 'Failed to reconcile the request' });

package/src/modules/tool-helpers/tool-context.ts

@@ -12,6 +12,7 @@ import type { ICreatorAccess } from '../access-model/creator.js';
 import type { GroupsIndex } from '../access-model/group-files.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import { isAbsence } from '../../shared/fs.contract.js';
+import { assertBranchProvided } from '../../shared/domain-errors.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
 import type { AuthService } from '../auth/auth.service.js';
@@ -77,6 +78,20 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
     const { loadActiveGroups } = deps;
     const fsCache = new Map<string, LocalFilesystem>();
     const getFilesystem = async (branch: string): Promise<LocalFilesystem> => {
+      // THE choke point: every knowledge-base tool resolves its workspace
+      // through here, and a `call_tool_chain` call reaches the very same route
+      // over loopback — so refusing a branch-less call here refuses it on both
+      // paths at once, with no per-tool guard to keep in step.
+      //
+      // Before ANY workspace work, because both things downstream do with this
+      // value are wrong when it is absent: `getOrCreateForUser` defaults a
+      // missing branch to the deployment's default (protected) branch, so an
+      // omitted argument would silently act on `main`; and a present-but-absent
+      // value like the string "undefined" goes to `workspaceIdForBranch`, which
+      // makes it a workspace directory of that name and then tries to clone a
+      // branch nobody ever pushed. Failing closed here means no workspace is
+      // created and no clone is attempted.
+      assertBranchProvided(branch);
       const cached = fsCache.get(branch);
       if (cached) return cached;
       const ws = await deps.workspaceService.getOrCreateForUser(user, branch);

package/src/modules/workflow/__tests__/apply-failure.test.ts

@@ -582,7 +582,7 @@ describe('WorkflowService — a refusal clears when a change makes it obsolete',
     const { svc } = service(
       store.db,
       (e) => emitted.push(e as { kind: string }),
-      {},
+      { carryApprovalsForward: vi.fn(async () => 0) },
       {
         git: {
           pull: vi.fn(async () => ({ treeChanged: false })),
@@ -591,6 +591,14 @@ describe('WorkflowService — a refusal clears when a change makes it obsolete',
             return { kind: 'merged', alreadyUpToDate: false };
           }),
           push: vi.fn(async () => undefined),
+          hasUnpushedCommits: vi.fn(async () => true),
+          pathsChangedBetween: vi.fn(async () => []),
+          // The head this test is named for: one sha before the merge,
+          // another after it.
+          resolvePrShas: vi
+            .fn()
+            .mockResolvedValueOnce({ baseSha: 'b'.repeat(40), headSha: 'a'.repeat(40) })
+            .mockResolvedValue({ baseSha: 'b'.repeat(40), headSha: 'd'.repeat(40) }),
         } as unknown as Partial<GitService>,
         prs: {
           getPrDetail: vi.fn(async () => ({ state: 'open', branch: 'bo/suggestions', base: 'main', viewerCanUpdate: true })),