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

package/src/modules/embed/embed.tools.ts

@@ -0,0 +1,206 @@
+import type { Router, RequestHandler } from 'express';
+import type { IToolRegistry } from '../tool-registry/tool.contract.js';
+import { ToolError } from '../tool-helpers/tool.contract.js';
+import { toolDef } from '../tool-helpers/tool-def.js';
+import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
+import type { ToolContext } from '../tool-helpers/tool.contract.js';
+import type { KbContext } from '../../shared/kb-context.js';
+import type { ReadForTool } from '../workspace/workspace.tools.js';
+import type { IEmbedService } from './embed.interface.js';
+import { requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
+import { SESSION_ID_INPUT, type ToolDescriptionNotes } from '../workspace/agent-access.gate.js';
+import { sessionIdInputOf } from '../workspace/workspace.tools.js';
+
+/** The tool name, in one place: the app manifest keys its view by it. */
+export const OPEN_PAGE_TOOL = 'open_page';
+
+/** What `open_page` answers when the deployment cannot be framed. */
+export const HTTP_DEPLOYMENT_NOTE =
+  'This deployment is reached over plain http, so no chat host can show the page inline — ' +
+  'an embedded view needs an https deployment. The page is above, and its address in the app ' +
+  'opens the whole thing.';
+
+/** What a path outside the knowledge base is told. */
+export const OUTSIDE_REPO = (kbDirName: string): string =>
+  `open_page shows a knowledge-base page, so \`path\` has to name a file under \`${kbDirName}/\`.`;
+
+export interface EmbedToolsDeps {
+  embedService: IEmbedService;
+  kb: KbContext;
+  /** `read_file`'s own read — see {@link ReadForTool}. */
+  readForTool: ReadForTool;
+  /** Whether a chat host's sandbox can load from this deployment's public address at all (https). */
+  canBeReached: () => boolean;
+  /** The file's address in the app, for the answer and for the view's fallback link. */
+  appUrlFor: (repoRelative: string, slug?: string) => string;
+  /** The notes a deployment registers for the gated tools — `read_file`'s, and so this tool's. */
+  notes: ToolDescriptionNotes;
+}
+
+/**
+ * `open_page`: the knowledge-base page, in the chat.
+ *
+ * The tool answers the file's TEXT exactly as `read_file` does — the same
+ * read hook, the same access gate, the same refusals — and adds the address
+ * of an embedded view that renders the page with the app's own renderer, so a
+ * host that supports MCP Apps shows it inline and lets the reader edit it or
+ * propose a change. A host that does not support them shows the text and the
+ * app address, and nothing errors: the answer stands on its own.
+ *
+ * `read_file` is deliberately untouched (Decision 2). Carrying a view on it
+ * would mint a token and render an iframe on every read an agent makes, for
+ * every file it reads while thinking.
+ *
+ * No `branch` argument, by decision: the embedded view is editable, and an
+ * editable embed targets the default branch only. The branch it rendered
+ * comes back in the answer so nothing is implied.
+ */
+export function registerEmbedTools(
+  registry: IToolRegistry,
+  router: Router,
+  toolAuth: RequestHandler,
+  toolHandler: ToolHandlerFactory,
+  deps: EmbedToolsDeps,
+): void {
+  const { kbDirName } = deps.kb;
+  const DESCRIPTION =
+    'Show a knowledge-base page to the person you are talking to, rendered inside this chat. ' +
+    'Returns the same `{ path, content }` `read_file` returns — the page as text, for you to read — ' +
+    'plus `embedUrl` (the view the chat renders), `appUrl` (the page in the app), and `branch` ' +
+    "(always the default branch). The rendered view uses the app's own renderer for the file's type, " +
+    'and offers the reader Edit when they may write the page and Propose changes when they may not, ' +
+    'as that same person — not as you. Use it when somebody wants to SEE or FIX a page; use `read_file` ' +
+    'when you only need to read one yourself. A chat host that cannot render a view shows the text, ' +
+    'so calling this is never worse than reading.';
+  const def = toolDef({
+    name: OPEN_PAGE_TOOL,
+    description: DESCRIPTION + deps.notes.gatedToolNote(),
+    path: `/api/agent/tools/${OPEN_PAGE_TOOL}`,
+    inputs: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          minLength: 1,
+          description:
+            `Path of the page to show, under \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`), ` +
+            'with or without a leading slash — a path without that prefix is placed under ' +
+            `\`${kbDirName}/\`. The page is always shown from the default branch.`,
+        },
+        heading: {
+          type: 'string',
+          description:
+            'Optional: the anchor slug of one heading (e.g. `problem-statement`) the view should open at. ' +
+            'The whole page is shown either way — this only says where to start reading.',
+        },
+        // As `read_file` takes it: the read is `read_file`'s own, and a
+        // deployment whose read hook wants the session must be able to get it.
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The path that was shown (echoes the input).' },
+        content: { type: 'string', description: "The page's text, exactly as `read_file` answers it." },
+        embedUrl: {
+          type: 'string',
+          description:
+            'The address of the view the chat renders. Absent when this deployment cannot be framed — ' +
+            'see `note`.',
+        },
+        appUrl: { type: 'string', description: "The page's address in the app." },
+        branch: { type: 'string', description: 'The branch the page was rendered from — the default branch.' },
+        note: {
+          type: 'string',
+          description: 'Present only when there is no `embedUrl`: why there is no embedded view.',
+        },
+      },
+      required: ['path', 'content', 'appUrl', 'branch'],
+    },
+    tags: ['workspace'],
+  });
+  // EXTERNAL only. The view exists for a chat somewhere else; the in-app
+  // agent's reader is already looking at the app, where every page is a
+  // click away — handing it an iframe of the page it is standing on would be
+  // a tool that cannot help.
+  registry.registerExternalTool(def);
+  // The read is `read_file`'s own, so what the agent reads about it is too:
+  // the note a deployment registers for the gated tools, and the `sessionId`
+  // description with its note — applied now and on every later registration,
+  // exactly as the file tools apply them (`sessionIdInputOf` is theirs).
+  const redescribe = (): void => {
+    def.description = DESCRIPTION + deps.notes.gatedToolNote();
+    const sessionId = sessionIdInputOf(def);
+    if (sessionId) sessionId.description = deps.notes.sessionIdDescription();
+  };
+  redescribe();
+  deps.notes.onChange(redescribe);
+
+  router.post(
+    `/agent/tools/${OPEN_PAGE_TOOL}`,
+    toolAuth,
+    // Registered external-only above; the route holds the same line, so an
+    // in-process agent that guessed the endpoint is refused here too.
+    requireExternalSource,
+    toolHandler(async (args, ctx: ToolContext) => {
+      const raw = typeof args.path === 'string' ? args.path.trim() : '';
+      if (!raw) throw new ToolError('`path` is required.', 400);
+      const heading = typeof args.heading === 'string' && args.heading.trim() ? args.heading.trim() : undefined;
+      const repoRelative = toRepoRelative(raw, kbDirName);
+      if (repoRelative === null) throw new ToolError(OUTSIDE_REPO(kbDirName), 400);
+      const branch = deps.kb.defaultBranch;
+      const wsPath = `${kbDirName}/${repoRelative}`;
+
+      // The read comes FIRST, and it is `read_file`'s own: a path the caller
+      // may not read, or one that is not there, is refused here in the words
+      // `read_file` refuses it — and no token is minted, because the mint is
+      // below this line.
+      const result = await deps.readForTool(branch, wsPath, ctx);
+      const content =
+        result.kind === 'text' ? result.text : result.kind === 'image' ? result.note : result.message;
+
+      const appUrl = deps.appUrlFor(repoRelative, heading);
+      // No view on a plain-http deployment (Decision 8): a host's https
+      // sandbox cannot load from it. The text and the app address are still
+      // the answer, and the tool says why there is no view rather than
+      // handing back an address no host can open.
+      if (!deps.canBeReached()) {
+        return { path: raw, content, appUrl, branch, note: HTTP_DEPLOYMENT_NOTE };
+      }
+      // Minted for the identity THIS MCP session authenticated — the
+      // signed-in user, or the owner of the connection key the agent carries.
+      // Whoever is in the chat therefore sees and may change exactly what
+      // that person may, and the audit log attributes it to them.
+      const { embedUrl } = await deps.embedService.mintForUser({
+        userId: ctx.user.id,
+        reference: heading ? `${repoRelative}#${heading}` : repoRelative,
+      });
+      return { path: raw, content, embedUrl, appUrl, branch };
+    }),
+  );
+}
+
+/**
+ * `path` as a repo-relative path, or null when it names nothing inside the
+ * knowledge base. Accepts it with or without the `<kbDir>/` prefix and with
+ * or without a leading slash, which is what `read_file` documents.
+ */
+export function toRepoRelative(path: string, kbDirName: string): string | null {
+  // A backslash is refused, not read as a separator — `read_file`'s contract,
+  // and a token must never name a file other than the one the caller wrote.
+  if (path.includes('\\')) return null;
+  const norm = path.replace(/^\.?\/+/, '').replace(/\/+$/, '');
+  if (!norm) return null;
+  const rel = norm === kbDirName ? '' : norm.startsWith(`${kbDirName}/`) ? norm.slice(kbDirName.length + 1) : norm;
+  if (!rel) return null;
+  // Traversal and the odd segment are refused HERE rather than deeper: the
+  // path is about to become part of a signed token, and a token is the one
+  // place a bad path would outlive the request that sent it.
+  // eslint-disable-next-line no-control-regex
+  if (/[\x00-\x1f\x7f]/.test(rel)) return null;
+  if (!rel.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..')) return null;
+  return rel;
+}

package/src/modules/embed/mcp-app.routes.ts

@@ -0,0 +1,41 @@
+import express, { type RequestHandler } from 'express';
+import type { McpAppManifest } from '@bevel-software/platform-mcp-core';
+
+/**
+ * The deployment's MCP Apps over REST, for the LOCAL MCP server.
+ *
+ * `hexis-mcp` bridges a host to this deployment over HTTP: it discovers the
+ * tools as a UTCP manual, which has nowhere to carry a view, and it serves
+ * `resources/read` itself. So it needs the manifest — which tools carry a
+ * view, and the view's HTML and sandbox metadata — as data. One route, one
+ * answer, so the local server advertises the same apps the hosted endpoint
+ * does without knowing what any of them render.
+ *
+ * `manualAuth` for the same reason `all-tools` and `catalog-revision` use it:
+ * this is the agent surface, reached with a connection key or an exchanged
+ * grant. Nothing here is per-caller — every connection gets the same view —
+ * so the credential is a door, not a filter.
+ */
+export function createMcpAppRoutes(
+  apps: { manifest(): Promise<McpAppManifest> },
+  manualAuth: RequestHandler,
+): express.Router {
+  const router = express.Router();
+
+  router.get('/agent/mcp-app', manualAuth, async (_req, res) => {
+    try {
+      const manifest = await apps.manifest();
+      // The view's HTML rides the manifest rather than sitting behind a
+      // second round trip per resource: it is one small static file, the
+      // local server needs all of it before it can declare the capability at
+      // all, and a second fetch is a second thing that can half-fail.
+      res.setHeader('Cache-Control', 'no-store');
+      res.json(manifest);
+    } catch (err) {
+      console.error('[embed] could not build the MCP App manifest:', err);
+      res.status(500).json({ error: 'Something went wrong.' });
+    }
+  });
+
+  return router;
+}

package/src/modules/embed/mcp-app.ts

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import {
+  MCP_APP_MIME_TYPE,
+  type McpAppManifest,
+  type McpAppResource,
+} from '@bevel-software/platform-mcp-core';
+import { mcpAppDir } from '../../assets.js';
+import { logger } from '../../shared/logging.js';
+import { OPEN_PAGE_TOOL } from './embed.tools.js';
+
+const log = logger('embed');
+
+/**
+ * The `ui://` URI of the one view this deployment serves, NAMED BY ITS
+ * CONTENT: `ui://hexis/page-<hash>.html`, the hash being the view's own
+ * bytes.
+ *
+ * A host caches a view by its URI, and a changed view under an unchanged
+ * URI is served stale until the host happens to refetch — which is what
+ * Claude did after the view was rewritten (#391): it kept rendering the
+ * view it had cached, the one that goes blank. With the content in the
+ * name, every change to the view is a new URI, so no host can keep serving
+ * the old one. The prefix is stable so a reader can still tell what the
+ * resource is.
+ */
+export const OPEN_PAGE_VIEW_URI_PREFIX = 'ui://hexis/page-';
+
+/** The URI the view with these bytes is served under. */
+export function openPageViewUri(text: string): string {
+  return `${OPEN_PAGE_VIEW_URI_PREFIX}${createHash('sha256').update(text).digest('hex').slice(0, 12)}.html`;
+}
+
+/** The view's file inside the packaged `mcp-app/` folder. */
+const OPEN_PAGE_VIEW_FILE = 'page.html';
+
+/** The MCP App views a deployment serves — the port the MCP endpoint, the manifest route and the catalog revision consume. */
+export interface IMcpAppService {
+  /** The manifest: which tools carry a view, and the views themselves. */
+  manifest(): Promise<McpAppManifest>;
+  /** One view by its `ui://` address, or null when this deployment serves none at it. */
+  resource(uri: string): Promise<McpAppResource | null>;
+}
+
+/**
+ * The deployment's MCP Apps, built once per process: which tools carry a
+ * view, and the views themselves with the sandbox metadata the host needs.
+ *
+ * Read once and cached — the file ships with the package and cannot change
+ * under a running process, and `resources/read` is on the handshake path of
+ * every connection that renders a page.
+ */
+export class McpAppService implements IMcpAppService {
+  private cached: Promise<McpAppManifest> | null = null;
+
+  constructor(
+    private readonly config: {
+      /** The deployment's public frontend address — the ONE origin the view may reach. */
+      readonly publicFrontendUrl: string;
+      /** Where the view's file lives. The packaged `mcp-app/` folder unless a test says otherwise. */
+      readonly viewDir?: string;
+    },
+  ) {}
+
+  /** Every app this deployment serves. Empty only if the packaged view is unreadable. */
+  manifest(): Promise<McpAppManifest> {
+    return (this.cached ??= this.build());
+  }
+
+  /** One view by URI, or null when this deployment serves none under it. */
+  async resource(uri: string): Promise<McpAppResource | null> {
+    const { resources } = await this.manifest();
+    return resources.find((r) => r.uri === uri) ?? null;
+  }
+
+  private async build(): Promise<McpAppManifest> {
+    const file = path.join(this.config.viewDir ?? mcpAppDir(), OPEN_PAGE_VIEW_FILE);
+    let text: string;
+    try {
+      text = await readFile(file, 'utf8');
+    } catch (err) {
+      // No view, no app. Advertising a `resourceUri` whose resource cannot be
+      // read would have a host preload a failure and show an empty frame
+      // where the tool's text used to be; with no manifest `open_page` is an
+      // ordinary tool answering ordinary text, which is the graceful shape.
+      log.error(
+        `could not read the MCP App view at ${file}; ` +
+          `open_page will carry no view: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      return { tools: {}, resources: [] };
+    }
+    const origin = originOf(this.config.publicFrontendUrl);
+    const uri = openPageViewUri(text);
+    return {
+      tools: { [OPEN_PAGE_TOOL]: { resourceUri: uri } },
+      resources: [
+        {
+          uri,
+          name: 'knowledge-base-page',
+          title: 'Knowledge base page',
+          description:
+            "The knowledge-base page an agent opened, rendered by the app's own renderer for its type, " +
+            'with Edit for a writer and Propose changes for everybody else.',
+          mimeType: MCP_APP_MIME_TYPE,
+          text,
+          ui: {
+            // EXACTLY this deployment's own public origin, and nothing else,
+            // for the two things the view asks of the host's sandbox:
+            // FETCHING the build manifest and the token-only embed API
+            // (`connectDomains`), and LOADING the embed bundle's scripts and
+            // stylesheets and the bytes the renderers draw
+            // (`resourceDomains`). No `frameDomains`: the view frames
+            // nothing. Claude's host drops that field and pins the sandbox's
+            // `frame-src` to `'self'`, which turned a framed `/embed` into a
+            // blank box — so the view loads the deployment's embed bundle
+            // into its own document instead. A knowledge-base HTML page
+            // still renders through the renderer's `srcdoc` sandbox, which
+            // that policy allows.
+            csp: {
+              connectDomains: origin ? [origin] : [],
+              resourceDomains: origin ? [origin] : [],
+            },
+            // Deliberately NO `domain`. The field asks the host for a
+            // dedicated sandbox origin, and the specification leaves its
+            // format and validation to each host ("servers MUST consult
+            // host-specific documentation") — a value one host accepts,
+            // another may reject, and a rejected resource is a view that
+            // never renders. This view keeps no storage and has no OAuth
+            // callback, so it needs no stable origin of its own; the host's
+            // default sandbox is the right one.
+            // The framed page draws its own surface; a second border around
+            // it reads as a box inside a box.
+            prefersBorder: false,
+          },
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * `url`'s origin, or null when it does not parse. Only the origin: a
+ * `connectDomains` / `resourceDomains` entry is an origin, and a path or a
+ * credential in one is either ignored or rejected by the host.
+ */
+export function originOf(url: string): string | null {
+  try {
+    const origin = new URL(url).origin;
+    // An address that parses but has no web origin (`file:`, `data:`) is
+    // serialised as the literal "null" — not an origin a host's CSP can name.
+    return origin === 'null' ? null : origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a public address can be reached from inside a host's sandbox at all.
+ *
+ * Hosts run an MCP App's view in a sandboxed, https iframe, and no browser
+ * will let an https document load scripts from, or fetch from, a plain-http
+ * origin. So a deployment reached over http has no embedded view —
+ * `open_page` still answers the page's text and its address in the app, and
+ * says why there is nothing rendered (see Decision 8).
+ */
+export function isSandboxReachableOrigin(url: string): boolean {
+  try {
+    return new URL(url).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}

package/src/modules/github-app/__tests__/github-app.test.ts

@@ -9,6 +9,8 @@ import { DeploymentSettingsService, SettingsValidationError } from '../../settin
 import { GitHubAppClient, GitHubAppError, appJwt, normalizePrivateKey } from '../github-app.client.js';
 import { GitHubAppConnection } from '../github-app.connection.js';
 import { createGitHubAppRoutes, githubAppManifest } from '../github-app.routes.js';
+import { setLogger } from '../../../shared/logging.js';
+import type { ILogger, LogFields } from '../../../shared/logger.contract.js';
 
 const ENC_KEY = 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=';
 const { privateKey: PEM, publicKey: PUBLIC } = generateKeyPairSync('rsa', {
@@ -393,6 +395,80 @@ describe('GitHubAppConnection: the token git presents', () => {
     await settled();
     expect(connection.token()).toBe('installation-token-1');
   });
+
+  /**
+   * The git runner reporting that the host threw the token out. The clock
+   * may still give it fifty minutes: the host's verdict wins, the token is
+   * dropped, and GitHub is asked for another at once — past the backoff a
+   * recent failure would otherwise impose. When GitHub will not replace it,
+   * NO token remains: that is what keeps the runner from offering the
+   * refused one again.
+   */
+  it('replaces a token the host refused, with time to spare or not, and drops it when GitHub will not', async () => {
+    const world: Parameters<typeof github>[0] = {};
+    const { connection, hub, clock } = connected(world);
+    await connection.prepare();
+    expect(connection.token()).toBe('installation-token-1');
+    clock.now += 5 * 60_000;
+    await connection.prepare({ refused: true });
+    expect(connection.token()).toBe('installation-token-2');
+    expect(hub.tokensIssued()).toBe(2);
+
+    // Inside a remembered failure's backoff, the refusal still asks.
+    world.down = true;
+    await expect(connection.prepare({ refused: true })).rejects.toThrow();
+    expect(connection.token()).toBeNull();
+    world.down = false;
+    await expect(connection.prepare({ refused: true })).resolves.toBeUndefined();
+    expect(connection.token()).toBe('installation-token-3');
+  });
+
+  /**
+   * A deployment whose app settings are incomplete used to run every git
+   * call without a credential and say nothing about it — for hours, with
+   * every push failing. It says so now: once per state, not before every
+   * call, and again if the state changes.
+   */
+  it('says ONCE which settings keep it from asking for a token, and says it again when they change', async () => {
+    const lines: string[] = [];
+    const capture = (bindings: LogFields = {}): ILogger => {
+      const line = (level: string) => (message: string, fields?: LogFields) =>
+        void lines.push(`${level} ${message} ${JSON.stringify({ ...bindings, ...fields })}`);
+      return { debug: line('debug'), info: line('info'), warn: line('warn'), error: line('error'), child: (m) => capture({ ...bindings, ...m }) };
+    };
+    const previous = setLogger(capture());
+    try {
+      const { connection, values } = connected();
+      const key = values.githubAppPrivateKey!;
+      values.githubAppPrivateKey = '';
+      await connection.prepare();
+      await connection.prepare();
+      await connection.prepare();
+      const said = lines.filter((l) => l.includes('no installation token can be asked for'));
+      expect(said).toHaveLength(1);
+      expect(said[0]).toContain('githubAppPrivateKey');
+      expect(said[0]).not.toContain('githubInstallationId');
+      expect(connection.token()).toBeNull();
+
+      // The state changes: a second setting goes too. Said again, naming both.
+      values.githubInstallationId = '';
+      await connection.prepare();
+      await connection.prepare();
+      expect(lines.filter((l) => l.includes('no installation token can be asked for'))).toHaveLength(2);
+      expect(lines.at(-1)).toContain('githubAppPrivateKey, githubInstallationId');
+
+      // Settings back: a token is asked for, and the next gap is said afresh.
+      values.githubAppPrivateKey = key;
+      values.githubInstallationId = '77';
+      await connection.prepare();
+      expect(connection.token()).toBe('installation-token-1');
+      values.githubInstallationId = '';
+      await connection.prepare();
+      expect(lines.filter((l) => l.includes('no installation token can be asked for'))).toHaveLength(3);
+    } finally {
+      setLogger(previous);
+    }
+  });
 });
 
 describe('GitHubAppConnection: what the deployment may be pointed at', () => {

package/src/modules/github-app/github-app.connection.ts

@@ -59,6 +59,13 @@ export class GitHubAppConnection implements GitHubAppRepository {
   private renewing: Promise<void> | null = null;
   /** The last renewal failed: how many in a row have, and until when GitHub is not asked again. */
   private failed: { times: number; until: number } | null = null;
+  /**
+   * The settings that were empty the last time no token could be asked for,
+   * so the log says so ONCE per state and not before every git call. A
+   * deployment in this state used to run for hours with every push failing
+   * and nothing in the log naming the cause.
+   */
+  private saidUnaskable: string | null = null;
 
   constructor(private readonly opts: GitHubAppConnectionOptions) {
     this.client = opts.client ?? new GitHubAppClient();
@@ -138,20 +145,47 @@ export class GitHubAppConnection implements GitHubAppRepository {
    * `asked` is for an admin waiting on the answer itself (the setup screen
    * listing repositories, proving a connection): GitHub is asked whatever
    * is remembered, and the failure is thrown.
+   *
+   * `refused` is the git runner reporting that the host threw out the token
+   * in hand. However much time the clock gives it, that token is dead: it is
+   * dropped first, so nothing presents it again, and GitHub is asked for
+   * another the way `asked` asks — now, and with the failure thrown. A
+   * renewal that fails leaves NO token, which is what tells the runner not
+   * to run the command again with the one the host just refused.
    */
-  async prepare(opts: { asked?: boolean } = {}): Promise<void> {
+  async prepare(opts: { asked?: boolean; refused?: boolean } = {}): Promise<void> {
     const credentials = this.credentials();
     const installationId = this.installationId();
-    if (!credentials || !installationId) return;
+    if (!credentials || !installationId) {
+      // Said once per state: every git call lands here while it lasts.
+      const empty = ['githubAppId', 'githubAppSlug', 'githubAppPrivateKey', 'githubAppClientId', 'githubAppClientSecret', 'githubInstallationId']
+        .filter((key) => !this.opts.read(key))
+        .join(', ');
+      if (this.saidUnaskable !== empty) {
+        this.saidUnaskable = empty;
+        this.log().error(
+          `no installation token can be asked for while these settings are empty: ${empty}. ` +
+            'Every git call to the repository host runs without a credential until they are set.',
+        );
+      }
+      return;
+    }
+    this.saidUnaskable = null;
+    if (opts.refused) {
+      // The host's verdict outranks the clock: what it refused is not
+      // presented again, by anyone, whatever a renewal in flight brings.
+      this.held = null;
+    }
+    const insist = Boolean(opts.asked || opts.refused);
     const held = this.held?.for === this.holder() ? this.held : null;
     const good = held !== null && held.expiresAt > this.now();
     if (good && held.expiresAt - this.now() > RENEW_AHEAD_MS) return;
-    if (!opts.asked && this.failed && this.now() < this.failed.until) return;
+    if (!insist && this.failed && this.now() < this.failed.until) return;
 
     this.renewing ??= this.renew(credentials, installationId).finally(() => {
       this.renewing = null;
     });
-    if (good && !opts.asked) {
+    if (good && !insist) {
       // Not waited on, so not thrown to anyone: the renewal has logged it.
       this.renewing.catch(() => undefined);
       return;