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

package/src/modules/onboarding/starter-packs.ts

@@ -0,0 +1,182 @@
+/**
+ * Starter packs: the pages and the plugin a new knowledge base can be filled
+ * with in one click, chosen by what the team does.
+ *
+ * A pack is a folder under the packs root (`starter-packs/` in this package,
+ * or a distribution's `STARTER_PACKS_DIR`):
+ *
+ *   <id>/pack.yaml          id, name, description, order, firstPagePrompt, suggestedPages
+ *   <id>/KnowledgeBase/…    pages, under the DEFAULT layout's folder names
+ *   <id>/Plugins/<name>/…   a team plugin in the normal plugin layout
+ *   <id>/Skills/…           shared skills, if a pack carries any
+ *
+ * The three folders are written under the deployment's OWN names for them
+ * (`KnowledgeBase/` lands in whatever `knowledgeBaseDir` is), so a pack is
+ * authored once and fits every layout. Anything else in a pack folder (a
+ * README, notes for whoever maintains it) is the pack's, not the knowledge
+ * base's, and is never copied.
+ *
+ * A pack that does not read as one — no `pack.yaml`, a field missing or of
+ * the wrong kind, an id that is not its folder's name — is passed over with
+ * a warning: one broken folder must not take the choice away from everyone.
+ *
+ * The disk is read through the one walk and the one probe
+ * (`shared/fs.contract.ts`), handed in by the caller; only a file's bytes are
+ * read here, which neither contract covers.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { renderKbLayoutPlaceholders, type KbLayout } from '@bevel-software/platform-shared';
+import type { IFsProbe, ITreeWalker, WalkedEntry } from '../../shared/fs.contract.js';
+import { logger } from '../../shared/logging.js';
+import { utf8Text } from '../../shared/utf8-text.js';
+
+const log = logger('starter-packs');
+
+/** The file that makes a folder a pack. */
+export const PACK_MANIFEST = 'pack.yaml';
+
+/** The answer that chooses no pack: "Skip, I'll start from scratch". Never a pack's id. */
+export const NO_STARTER_PACK = 'none';
+
+/** A pack id: the folder's name, kebab-case, so it is safe in a URL, a setting and a path. */
+const PACK_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** The pack's own folders, by their default-layout names, and the layout key each one is written under. */
+export const PACK_ROOTS: ReadonlyArray<readonly [string, keyof Pick<KbLayout, 'knowledgeBaseDir' | 'pluginsDir' | 'skillsDir'>]> = [
+  ['KnowledgeBase', 'knowledgeBaseDir'],
+  ['Plugins', 'pluginsDir'],
+  ['Skills', 'skillsDir'],
+];
+
+/** What a chip shows, and the order the chips come in. */
+export interface StarterPackSummary {
+  id: string;
+  name: string;
+  description: string;
+  order: number;
+}
+
+export interface StarterPack extends StarterPackSummary {
+  /** Replaces the generic "write your first page" request for a team that chose this pack. */
+  firstPagePrompt: string;
+  /** The pages the agent's first-run note offers to draft. */
+  suggestedPages: string[];
+  /** The pack's folder, absolute. */
+  dir: string;
+}
+
+/** One file a pack would add, at the path it would have in the knowledge base. */
+export interface StarterPackFile {
+  /** Repository-relative, under the deployment's layout: `KnowledgeBase/About us.md`, `Plugins/x/skills/y/SKILL.md`. */
+  repoPath: string;
+  /** Which of the pack's folders it came from, by its default name. */
+  root: (typeof PACK_ROOTS)[number][0];
+  /** The bytes to write: text with the layout placeholders filled, or the file as it is. */
+  content: string | Buffer;
+}
+
+/**
+ * Every valid pack under `root`, chip order first (then name). A root that
+ * is not there offers no packs; it is not an error, since a distribution may
+ * ship none.
+ */
+export async function loadStarterPacks(disk: IFsProbe, root: string): Promise<StarterPack[]> {
+  let entries: WalkedEntry[] | null;
+  try {
+    entries = await disk.listDir(root);
+  } catch (err) {
+    log.warn(`could not read the starter packs folder "${root}" — no packs offered:`, { err });
+    return [];
+  }
+  if (entries === null) return [];
+  const packs: StarterPack[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const pack = await readStarterPack(disk, path.join(root, entry.name));
+    if (pack) packs.push(pack);
+  }
+  return packs.sort((a, b) => a.order - b.order || a.name.localeCompare(b.name));
+}
+
+/** The pack in `dir`, or null (with a warning saying why) when it does not read as one. */
+export async function readStarterPack(disk: IFsProbe, dir: string): Promise<StarterPack | null> {
+  const folder = path.basename(dir);
+  let raw: string;
+  try {
+    raw = await disk.readTextFile(path.join(dir, PACK_MANIFEST));
+  } catch {
+    log.warn(`starter pack "${folder}" has no readable ${PACK_MANIFEST} — skipped.`);
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch (err) {
+    log.warn(`starter pack "${folder}": ${PACK_MANIFEST} is not valid YAML — skipped.`, {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+  const problem = packProblem(parsed, folder);
+  if (problem) {
+    log.warn(`starter pack "${folder}": ${problem} — skipped.`);
+    return null;
+  }
+  const m = parsed as Record<string, unknown>;
+  return {
+    id: m.id as string,
+    name: (m.name as string).trim(),
+    description: (m.description as string).trim(),
+    order: m.order as number,
+    firstPagePrompt: (m.firstPagePrompt as string).trim(),
+    suggestedPages: (m.suggestedPages as string[]).map((p) => p.trim()),
+    dir,
+  };
+}
+
+/** Why a parsed `pack.yaml` is not a pack, or null when it is one. */
+export function packProblem(manifest: unknown, folder: string): string | null {
+  if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {
+    return `${PACK_MANIFEST} is not a mapping`;
+  }
+  const m = manifest as Record<string, unknown>;
+  if (typeof m.id !== 'string' || !PACK_ID_RE.test(m.id)) return '`id` must be lowercase letters, digits and hyphens';
+  if (m.id !== folder) return `\`id\` ("${m.id}") must be the folder's name`;
+  if (m.id === NO_STARTER_PACK) return `"${NO_STARTER_PACK}" is reserved for skipping`;
+  for (const key of ['name', 'description', 'firstPagePrompt'] as const) {
+    if (typeof m[key] !== 'string' || !(m[key] as string).trim()) return `\`${key}\` must be a non-empty string`;
+  }
+  if (typeof m.order !== 'number' || !Number.isFinite(m.order)) return '`order` must be a number';
+  if (!Array.isArray(m.suggestedPages) || m.suggestedPages.some((p) => typeof p !== 'string' || !p.trim())) {
+    return '`suggestedPages` must be a list of page names';
+  }
+  return null;
+}
+
+/**
+ * Every file the pack would add, at its path under `layout`, in walk order.
+ * The knowledge-base walk lists them: dot-entries are left behind (an
+ * editor's or an OS's droppings, never content), and so is anything that is
+ * not a regular file — a pack is files. A pack folder that is not there, or
+ * is a file where a folder was expected, holds nothing; a folder in one that
+ * cannot be listed is the error, since a pack with a hole is not the pack.
+ */
+export async function starterPackFiles(disk: ITreeWalker, pack: StarterPack, layout: Required<KbLayout>): Promise<StarterPackFile[]> {
+  const out: StarterPackFile[] = [];
+  for (const [root, layoutKey] of PACK_ROOTS) {
+    const base = path.join(pack.dir, root);
+    for (const rel of await disk.walkFiles(base, () => true, { strict: true })) {
+      const bytes = await fs.readFile(path.join(base, ...rel.split('/')));
+      const text = utf8Text(bytes);
+      out.push({
+        repoPath: `${layout[layoutKey]}/${rel}`,
+        root,
+        content: text === null ? bytes : renderKbLayoutPlaceholders(text, layout),
+      });
+    }
+  }
+  return out;
+}

package/src/modules/plugins/__tests__/plugins.tools.test.ts

@@ -152,11 +152,12 @@ describe('what my_plugin tells an agent about the personal plugin', () => {
     const def = myPluginDef(DEFAULT_KB_LAYOUT);
     expect((def.tool_call_template as { url: string; http_method: string }).url).toBe('${API_URL}/api/plugins/personal');
     expect((def.tool_call_template as { http_method: string }).http_method).toBe('POST');
-    // The flat inputs are wrapped under `body` by `toolDef`; `my_plugin` takes none.
+    // The flat inputs are wrapped under `body` by `toolDef`; `my_plugin` takes
+    // none, so the envelope is optional too and `my_plugin({})` is a call
+    // that matches (see `bodyEnvelope`).
     expect(def.inputs).toEqual({
       type: 'object',
       properties: { body: { type: 'object', properties: {}, additionalProperties: false } },
-      required: ['body'],
       additionalProperties: false,
     });
     expect(Object.keys((def.outputs as { properties: Record<string, unknown> }).properties)).toEqual([
@@ -279,4 +280,26 @@ describe('the creation endpoints behind the key-or-session gate', () => {
     expect(refused.status).toBe(404);
     expect(await refused.json()).toEqual({ error: 'There is no folder "Nope" under Plugins/.' });
   });
+
+  it('refuses an agent call whose arguments do not match the tool, before anything is provisioned', async () => {
+    // These two routes ARE the tools, so they check a call against what the
+    // tools declare, as every route-hosted tool does. `my_plugin` takes no
+    // arguments; `create_plugin` takes a non-empty `name` and an optional `parent`.
+    myPluginDef(DEFAULT_KB_LAYOUT);
+    const base = await start();
+    const stray = await post(base, '/api/plugins/personal', { unexpected: 1 }, 'bevel_alice');
+    expect(stray.status).toBe(400);
+    const strayBody = (await stray.json()) as { kind: string; error: string };
+    expect(strayBody.kind).toBe('arguments-do-not-match');
+    expect(strayBody.error).toContain('"unexpected" is not an argument of this tool.');
+    expect(strayBody.error.split('\n').pop()).toBe('Call: KNOWLEDGE_BASE.my_plugin({})');
+    expect(ensurePersonalPlugin).not.toHaveBeenCalled();
+
+    const empty = await post(base, '/api/plugins', { name: '' }, 'bevel_alice');
+    expect(empty.status).toBe(400);
+    expect(((await empty.json()) as { error: string }).error).toContain(
+      '"name" must be at least 1 character(s) long, but 0 was given.',
+    );
+    expect(createPlugin).not.toHaveBeenCalled();
+  });
 });

package/src/modules/plugins/index.ts

@@ -4,6 +4,7 @@ export {
   PluginProvisionError,
   pluginAccessMd,
   personalAccessMd,
+  withCreatorGrants,
 } from './plugin-provision.service.js';
 export { JoinRequestsService, type JoinRequest } from './join-requests.service.js';
 export {

package/src/modules/plugins/plugin-provision.service.ts

@@ -151,6 +151,20 @@ export class PluginProvisionService {
    */
   private readonly creations = new WorkspaceMutex();
 
+  /**
+   * Run `fn` holding the creation lock of every plugin name in `names` — for
+   * a writer outside this service that publishes plugins of its own (a
+   * starter pack) and whose name check and commit must be one step against
+   * a creation or a deletion of the same name. The set is taken in one
+   * `runAll`; `fn` must not take this lock again (see `WorkspaceMutex`).
+   */
+  withIdentities<T>(names: string[], fn: () => Promise<T>): Promise<T> {
+    return this.creations.runAll(
+      names.map((name) => `plugin:${pluginManifestName(name)}`),
+      fn,
+    );
+  }
+
   constructor(
     private readonly workspaceService: WorkspaceService,
     private readonly commits: ProvisionCommitDriver,
@@ -693,7 +707,14 @@ export function personalAccessMd(creator: { name: string; email: string }): stri
   return spliceGrant(seeded, 'read', creatorPrincipal(creator), { allowScalar: false, target: 'node' }).text;
 }
 
-function withCreatorGrants(base: string, creator: { name: string; email: string }): string {
+/**
+ * `base` — an access.md in the two-block shape — with `creator` named under
+ * `read`, `write` and `owner` of the folder: how a plugin made by someone is
+ * run by them. Exported for the one other door that brings a plugin into
+ * being, a starter pack (`modules/onboarding`), whose shipped rules it adds
+ * the admin who applied the pack to.
+ */
+export function withCreatorGrants(base: string, creator: { name: string; email: string }): string {
   const principal = creatorPrincipal(creator);
   let out = base;
   for (const verb of ['read', 'write', 'owner'] as const) {

package/src/modules/plugins/plugins.routes.ts

@@ -16,6 +16,7 @@ import { domainErrorBody } from '../../shared/http-errors.js';
 import { pluginFolderBelowRoot } from './plugins.service.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { PluginProvisionError, type PluginProvisionService } from './plugin-provision.service.js';
+import { argumentsRefusal } from '../tool-helpers/route-argument-check.js';
 import { PluginLinkError, type PluginLinksService } from './plugin-links.service.js';
 import { PluginRenameError, type PluginRenameService } from './plugin-rename.service.js';
 import type { JoinRequestsService } from './join-requests.service.js';
@@ -64,6 +65,24 @@ import type {
  * middleware change can never silently un-gate one. Nothing here is reachable
  * with an agent connection key or a manual-auth bearer.
  */
+/**
+ * Answer the arguments-do-not-match refusal when the body does not match the
+ * tool hosted at this route; `true` when it answered. A body that is not a
+ * JSON object is refused here too, with the sentence `toolHandler` uses, so a
+ * `null` or an array never reaches the handler as if it were `{}`.
+ */
+function refuseMismatchedArguments(req: express.Request, res: express.Response): boolean {
+  const body: unknown = req.body === undefined ? {} : req.body;
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    res.status(400).json({ error: 'Request body must be a JSON object.' });
+    return true;
+  }
+  const mismatch = argumentsRefusal(req.originalUrl, body as Record<string, unknown>, req.query);
+  if (!mismatch) return false;
+  res.status(mismatch.status).json({ ...mismatch.details, error: mismatch.message });
+  return true;
+}
+
 /**
  * The two doors through which plugin folders come to exist — ONE
  * implementation each, for the app and for agents alike:
@@ -96,6 +115,11 @@ export function createPluginCreationRoutes(
       res.status(401).json({ error: 'Unauthenticated' });
       return;
     }
+    // These two routes ARE the `create_plugin` and `my_plugin` tools, so an
+    // agent's call is checked against what those tools declare, exactly as a
+    // route-hosted tool's is in `toolHandler`: a call that does not match is
+    // refused before anything is provisioned.
+    if (refuseMismatchedArguments(req, res)) return;
     // `req.body` is undefined when no JSON body was sent at all — that is a
     // 400, not a destructuring crash.
     const { name, parent } = (req.body ?? {}) as { name?: string; parent?: unknown };
@@ -129,6 +153,11 @@ export function createPluginCreationRoutes(
       res.status(401).json({ error: 'Unauthenticated' });
       return;
     }
+    // These two routes ARE the `create_plugin` and `my_plugin` tools, so an
+    // agent's call is checked against what those tools declare, exactly as a
+    // route-hosted tool's is in `toolHandler`: a call that does not match is
+    // refused before anything is provisioned.
+    if (refuseMismatchedArguments(req, res)) return;
     try {
       res.json(await provision.ensurePersonalPlugin(user));
     } catch (err) {

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();
@@ -528,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);