Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

54.3 KB
Raw Blame
/**
 * The Harness GitHub App (docs/swarm-github-app.md): how the backend proves it is the app, finds the app's installation
 * on a repository and creates installation access tokens for that one repository.
 *
 * A token comes from an installation, never from a person: GitHub user tokens cannot be narrowed to one repository, an
 * installation token can, and it lasts an hour (docs/plans/2026-10-24-swarm-team-account.md, Findings). Only node's
 * crypto signs the app's JWT. Nothing here logs a token or the private key.
 */
import { createPrivateKey, hkdfSync, sign, type KeyObject } from 'node:crypto'
import { readPushOrigin, type GitHubRead, type PushOrigin } from './pushOrigin.js'
import { githubRepository, type GitHubRepository } from './repository.js'
import type { PullRequestWatch } from '../superTabs/pullRequestEvents.js'
import type { PullRequestFile } from '../superTabs/pullRequestPatch.js'
import type { MergeSides } from '../superTabs/mergeCarry.js'

/** What a Swarm agent's token may do, and nothing more: push to and read the repository, open and update pull requests,
 *  and read checks and workflow runs to see whether its pull request passes. */
export const TOKEN_PERMISSIONS = { contents: 'write', pull_requests: 'write', checks: 'read', actions: 'read', metadata: 'read' } as const
/**
 * What an agent's token also asks for where the repository's installation has granted it, at no more than the granted level
 * (Scholes, task #2755, Ken approved): push changes to `.github/workflows`, which GitHub refuses without `workflows`, and
 * read and write issues. Never asked for where not granted: GitHub refuses a token that asks for a permission its
 * installation has not accepted, and every agent on it would lose its token. Ken accepted the risk: a workflow change runs
 * in CI with the repository's secrets, and Team-written branches are among the pushers.
 */
export const GRANTED_TOKEN_PERMISSIONS = { workflows: 'write', issues: 'write' } as const
/** What no installation token may ever ask for (task #1788): a new repository is created with the person's own sign-in
 *  token only (github/repositoryCreate.ts), so a token minted from the app's key can never create, delete or transfer a
 *  repository, nor widen which repositories the installation covers. */
export const NEVER_ON_INSTALLATION_TOKENS = ['administration', 'repository_creation', 'installation_repositories'] as const
/** What preparing an agent's folder may do before the agent has a task: clone and fetch the repository, nothing more. */
export const PREPARE_PERMISSIONS = { contents: 'read', metadata: 'read' } as const
/** What the Swarm's tidying reads before it archives a finished group: whether its pull requests are merged or closed. */
export const PULL_READ_PERMISSIONS = { pull_requests: 'read', metadata: 'read' } as const
/** What the route's read of running CI jobs may do: read workflow runs and their jobs, nothing more. */
export const ACTIONS_READ_PERMISSIONS = { actions: 'read', metadata: 'read' } as const
/** What reading who pushed a pull request's commits may do (pushOrigin.ts): read the pull request and the repository's activity log. */
export const PUSH_ORIGIN_PERMISSIONS = { contents: 'read', pull_requests: 'read', metadata: 'read' } as const
/** What watching a task's pull request for its Engineer reads (superTabs/pullRequestEvents.ts): the pull request, its reviews
 *  and comments, and its head's checks. All already among the app's permissions ([TOKEN_PERMISSIONS]). */
/** The release watch (superTabs/releaseWatch.ts): release workflow runs, where their tags sit on the default branch, and a
 *  pull request's files. */
export const RELEASE_READ_PERMISSIONS = { contents: 'read', pull_requests: 'read', actions: 'read', metadata: 'read' } as const
export const PULL_WATCH_PERMISSIONS = { pull_requests: 'read', checks: 'read', metadata: 'read' } as const
/** What reading a pull request head's patch may do (superTabs/pullRequestPatch.ts, #3394): read the pull request, and the
 *  comparison of its base and head commits, which is repository contents. Read only, revoked when the watch's pass ends. */
export const PULL_PATCH_PERMISSIONS = { contents: 'read', pull_requests: 'read', metadata: 'read' } as const
/** The watch's answers kept for conditional reads: an unchanged one comes back 304, which GitHub's rate limit does not count. */
const WATCH_KEPT = 2000
/** The most files GitHub gives for a comparison of two commits (GET /compare/{base}...{head}). */
export const COMPARE_FILES_MAX = 300
/** Pages of 100 a pull request's file list reads: GitHub lists at most 3,000 files. */
const PULL_FILES_PAGES = 30
const PUSH_ORIGINS_KEPT = 1000
/** GitHub's files of a comparison as [PullRequestFile]s, or null when one lacks its name, status or blob. */
function filesOf(body: unknown[]): PullRequestFile[] | null {
  const text = (value: unknown) => typeof value === 'string' ? value : undefined
  const files: PullRequestFile[] = []
  for (const file of body as Array<Record<string, unknown>>) {
    const filename = text(file?.filename), status = text(file?.status), sha = text(file?.sha), patch = text(file?.patch), previousFilename = text(file?.previous_filename)
    if (!filename || !status || sha === undefined) return null
    files.push({ filename, status, sha, ...patch === undefined ? {} : { patch }, ...previousFilename === undefined ? {} : { previousFilename } })
  }
  return files
}
const PUSH_UNKNOWN_MS = 60_000
export type TokenPermissions = Readonly<Record<string, 'read' | 'write'>>
/** Jobs running and waiting on a repository's GitHub Actions, in all and on macOS runners: counts only. */
export interface CiLoad { running: number; queued: number; macosRunning: number; macosQueued: number }

/** A refusal with the code clients act on; `details` adds fields beside it, such as the install link. */
export class GitHubAppError extends Error {
  constructor(readonly code: string, message: string, readonly status: number, readonly details?: Record<string, unknown>) {
    super(message)
    this.name = 'GitHubAppError'
  }
}

/** Whether an organization lets Harness create a repository there (task #1788): the app is installed on it and its owner
 *  accepted Repository creation; [canAdd] when it also accepted installation repository access, so a new repository the
 *  installation does not cover yet can be added to it. */
export type OwnerReadiness = { state: 'ready'; installation: number; canAdd: boolean } | { state: 'not-installed'; installUrl: string | null } | { state: 'not-accepted' }

export interface GitHubAppConfig { appId: string; privateKey: KeyObject; slug: string | null }

/** The app's private key as GitHub hands it out (a PEM file), with its line breaks written as `\n`, or base64 of it. The
 *  error never repeats the value. */
export function readPrivateKey(value: string): KeyObject {
  let pem = value.trim().replace(/\\n/g, '\n')
  if (!pem.includes('-----BEGIN')) {
    const decoded = /^[A-Za-z0-9+/=\s]+$/.test(pem) ? Buffer.from(pem, 'base64').toString('utf8') : ''
    if (!decoded.includes('-----BEGIN')) throw new Error('GITHUB_APP_PRIVATE_KEY is not a PEM private key or base64 of one.')
    pem = decoded.trim()
  }
  let key: KeyObject
  try { key = createPrivateKey(pem) } catch { throw new Error('GITHUB_APP_PRIVATE_KEY could not be read as a private key.') }
  if (key.asymmetricKeyType !== 'rsa') throw new Error('GITHUB_APP_PRIVATE_KEY must be the RSA key GitHub generated for the app.')
  return key
}

/** Both empty: the feature is off. One without the other, or a value that cannot be right, stops the backend at startup
 *  rather than failing the first agent that asks. */
/** The name a Harness GitHub App's commits carry, whatever the app is called on GitHub (cli/src/lib/swarmGitHub.ts accepts it). */
export const COMMIT_IDENTITY: CommitIdentity = { name: 'Harness by Autonomous', email: '[email protected]' }
/** The line a commit, or the merge helper's squash message, names Harness by (attribution.ts; scripts/merge-validated-pr.py). */
export const HARNESS_CO_AUTHOR = `Co-authored-by: ${COMMIT_IDENTITY.name} <${COMMIT_IDENTITY.email}>`

export function githubAppConfig(env: { GITHUB_APP_ID: string; GITHUB_APP_PRIVATE_KEY: string; GITHUB_APP_SLUG: string }): GitHubAppConfig | null {
  const appId = env.GITHUB_APP_ID.trim(), key = env.GITHUB_APP_PRIVATE_KEY.trim(), slug = env.GITHUB_APP_SLUG.trim()
  if (!appId && !key) return null
  if (!appId || !key) throw new Error('Set both GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY for the Harness GitHub App, or neither.')
  // The numeric App ID, or the app's Client ID, which GitHub also takes as the JWT issuer.
  if (!/^(?:[0-9]{1,12}|Iv[0-9A-Za-z.]{4,40})$/.test(appId)) throw new Error('GITHUB_APP_ID must be the app\'s numeric App ID or its Client ID.')
  if (slug && !/^[a-z0-9](?:[a-z0-9-]{0,98}[a-z0-9])?$/.test(slug)) throw new Error('GITHUB_APP_SLUG must be the app\'s name as in github.com/apps/NAME.')
  return { appId, privateKey: readPrivateKey(key), slug: slug || null }
}

/** The key that seals cached tokens (github/tokens.ts), derived from the app's own private key: whoever can read the cache
 *  without it learns nothing, and no further secret has to be configured. */
export function cacheSecret(config: GitHubAppConfig): Buffer {
  const der = config.privateKey.export({ type: 'pkcs8', format: 'der' })
  return Buffer.from(hkdfSync('sha256', der, 'harness-github-token-cache', config.appId, 32))
}

/** Where the default branch stands: a ruleset requires a pull request; classic branch protection is on, which an app
 *  without administration access cannot read further; nothing protects it; or it could not be read. */
export type BranchProtection = 'pull_request' | 'classic' | 'none' | 'unknown'
export interface DefaultBranch { branch: string | null; protection: BranchProtection }

const base64url = (value: string | Buffer) => Buffer.from(value).toString('base64url')
const samePermissions = (a: TokenPermissions, b: TokenPermissions) =>
  Object.keys(a).length === Object.keys(b).length && Object.entries(a).every(([name, level]) => b[name] === level)
const INSTALLATION_TTL_MS = 10 * 60_000
const NOT_INSTALLED_TTL_MS = 60_000
/** How often a person's "check again" may make the server ask GitHub again about one repository. */
const REFRESH_MS = 15_000
const BRANCH_TTL_MS = 10 * 60_000
const REQUEST_TIMEOUT_MS = 10_000
/** How long a CI load is kept: routes come minutes apart, and a job takes minutes. */
export const CI_LOAD_TTL_MS = 30_000
/** The most GitHub calls one CI load makes: the token, the two run lists, the jobs of at most [CI_MAX_RUNS] runs, and the
 *  revoke (Lead, 10-31: a read's calls are counted and capped). The installation lookup is kept ten minutes apart. */
export const CI_MAX_CALLS = 10
/** The most runs whose jobs are read in one CI load; a run beyond it counts as one waiting job, on no particular runner. */
export const CI_MAX_RUNS = CI_MAX_CALLS - 4
/** The most CI loads one server process reads for one repository in an hour: past it, the last load is answered while it is
 *  at most [CI_STALE_MS] old, and after that none, which the route says as "not checked". The count, like the 30 s cache, is
 *  per server process, and production runs 2 to 8 pods (security review 2 of #2428): the worst case is 8 × 3 = 24 reads and,
 *  with [CI_MAX_CALLS], 240 calls an hour per repository, about 5% of an installation's 5,000. */
export const CI_READS_PER_HOUR = 3
/** The most server processes production runs (its autoscaler's maximum), for the worst case above. */
export const SERVER_PROCESSES_MAX = 8
export const CI_STALE_MS = 5 * 60_000
const CI_WAITING = new Set(['queued', 'waiting', 'requested', 'pending'])

/** A git author and committer. */
export interface CommitIdentity { name: string; email: string }

export interface GitHubAppOptions {
  fetch?: typeof fetch
  now?: () => number
  /** api.github.com unless a test serves a fake. */
  apiUrl?: string
}

export class GitHubApp {
  private readonly fetch: typeof fetch
  private readonly now: () => number
  private readonly apiUrl: string
  private signed: { jwt: string; until: number } | null = null
  /** The app's name, as GitHub answers it (botLogin). */
  private slug: string | null = null
  private readonly installations = new Map<string, { id: number | null; until: number }>()
  /** What each installation has granted, by its id, for [GRANTED_TOKEN_PERMISSIONS]: null when GitHub did not say. */
  private readonly grants = new Map<number, { permissions: TokenPermissions | null; until: number }>()
  private readonly branches = new Map<string, { value: DefaultBranch; until: number }>()
  /** A repository's name now, by the name asked for (lower case): null when it was not renamed. */
  private readonly renames = new Map<string, { repository: GitHubRepository | null; until: number }>()
  private readonly shownNames = new Map<string, { name: string; until: number }>()
  /** Each repository's CI load while fresh, or being read ([ciLoad]), by its name in lower case; per server process. */
  private readonly ciLoads = new Map<string, { value: Promise<CiLoad | null>; until: number }>()
  private readonly pushOrigins = new Map<string, { origin: PushOrigin; until: number }>()
  /** Each repository's CI reads in the last hour, and its last load read, for [CI_READS_PER_HOUR]. */
  private readonly ciReads = new Map<string, { at: number[]; last: { load: CiLoad | null; at: number } | null }>()
  /** The app's installation on each organization, by its login in lower case, for [ownerReadiness]; null when not installed. */
  private readonly orgInstallations = new Map<string, { id: number | null; until: number }>()
  /** When each repository's "not installed" was last forgotten on request ([forget]). */
  private readonly forgotten = new Map<string, number>()
  /** The watch's last answer and its ETag, by path ([watchPullRequest]). */
  private readonly watched = new Map<string, { etag: string; body: Record<string, unknown> | unknown[]; link: string | null }>()

  constructor(readonly config: GitHubAppConfig, options: GitHubAppOptions = {}) {
    this.fetch = options.fetch ?? fetch
    this.now = options.now ?? Date.now
    this.apiUrl = (options.apiUrl ?? 'https://api.github.com').replace(/\/$/, '')
  }

  /** Where an owner installs the app, when its URL name is configured. */
  installUrl(): string | null {
    return this.config.slug ? `https://github.com/apps/${this.config.slug}/installations/new` : null
  }

  /**
   * Who the app's commits are by, as Claude's are by its own line (Dee, task #2136). A Harness Team account has no git identity
   * of its own, so its commits would read "Harness Team <harnessteam@<host>.local>" (PR #1934). No GitHub account owns this
   * address, so GitHub links these commits to nobody: telling a Team agent's commits apart rests on who pushed (pushOrigin.ts).
   */
  commitIdentity(): CommitIdentity { return COMMIT_IDENTITY }

  /** The app's bot account's login, which GitHub's activity log names as the actor of every push with the app's token: GitHub's
   *  own answer, remembered. Never a configured name, as a wrong one asks the log for a bot that never pushed, and its empty
   *  answer reads as clean. Null while GitHub cannot say, which reads as unknown. Never read from a commit. */
  async botLogin(): Promise<string | null> {
    if (this.slug) return `${this.slug}[bot]`
    try {
      const app = await this.call('GET', '/app', `Bearer ${this.jwt()}`)
      const named = (app.body as { slug?: unknown }).slug
      if (app.status === 200 && typeof named === 'string' && /^[a-z0-9-]{1,100}$/.test(named)) this.slug = named
    } catch (error) {
      if (!(error instanceof GitHubAppError)) throw error
    }
    return this.slug ? `${this.slug}[bot]` : null
  }

  /** The app's own JWT (RS256, ten minutes at most): issued a minute back against clock drift, valid nine minutes, and
   *  reused until a minute before it ends. */
  jwt(): string {
    const now = this.now()
    if (this.signed && this.signed.until > now) return this.signed.jwt
    const iat = Math.floor(now / 1000) - 60
    const exp = iat + 60 + 9 * 60
    const input = `${base64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }))}.${base64url(JSON.stringify({ iat, exp, iss: this.config.appId }))}`
    const jwt = `${input}.${base64url(sign('sha256', Buffer.from(input), this.config.privateKey))}`
    this.signed = { jwt, until: (exp - 60) * 1000 }
    return jwt
  }

  private async call(method: string, path: string, auth: string | null, body?: unknown, headers: Record<string, string> = {}):
    Promise<{ link?: string | null; etag?: string | null; status: number; body: Record<string, unknown> | unknown[] }> {
    let response: Response
    try {
      response = await this.fetch(`${this.apiUrl}${path}`, {
        method, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
        headers: { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'harness-backend',
          ...(auth ? { Authorization: auth } : {}), ...(body ? { 'Content-Type': 'application/json' } : {}), ...headers },
        ...(body ? { body: JSON.stringify(body) } : {}),
      })
    } catch {
      throw new GitHubAppError('GITHUB_UNAVAILABLE', 'GitHub did not answer. Try again in a minute.', 503)
    }
    const text = await response.text().catch(() => '')
    let parsed: unknown = {}
    try { parsed = text ? JSON.parse(text) : {} } catch { parsed = {} }
    return { status: response.status, body: parsed && typeof parsed === 'object' ? parsed as Record<string, unknown> : {},
      link: response.headers.get('link'), etag: response.headers.get('etag') }
  }

  private misconfigured(): GitHubAppError {
    return new GitHubAppError('GITHUB_APP_MISCONFIGURED', 'GitHub refused the Harness GitHub App\'s credentials. Check GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY on the server.', 503)
  }

  notInstalled(repository: GitHubRepository): GitHubAppError {
    const installUrl = this.installUrl()
    return new GitHubAppError('GITHUB_APP_NOT_INSTALLED',
      `The Harness GitHub App is not installed on ${repository.fullName}. Ask an owner of ${repository.owner} to install it${installUrl ? `: ${installUrl}` : ''}.`,
      409, installUrl ? { installUrl } : undefined)
  }

  /** The installation that covers [repository], or null when the app is not installed there. Remembered ten minutes,
   *  and a missing installation one minute, so a busy Swarm does not ask GitHub for every token. */
  async installation(repository: GitHubRepository): Promise<number | null> {
    const key = repository.fullName.toLowerCase()
    const known = this.installations.get(key)
    if (known && known.until > this.now()) return known.id
    const answer = await this.call('GET', `/repos/${repository.owner}/${repository.name}/installation`, `Bearer ${this.jwt()}`)
    if (answer.status === 401) throw this.misconfigured()
    if (answer.status === 404) {
      this.installations.set(key, { id: null, until: this.now() + NOT_INSTALLED_TTL_MS })
      return null
    }
    const id = (answer.body as Record<string, unknown>).id
    if (answer.status !== 200 || typeof id !== 'number') throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub could not look up the app on ${repository.fullName}.`, 502)
    this.installations.set(key, { id, until: this.now() + INSTALLATION_TTL_MS })
    return id
  }

  /**
   * The installation that covers [repository], with the repository under the name GitHub knows it by now; null when the
   * app is not installed there. A repository renamed on GitHub still answers to its old name for git, but not for the
   * app's installation lookup, and a Swarm project's repository address is set once: a project made from a checkout
   * whose remote still had the old name could never get a token (2026-10-27, autonomous-harness renamed openharness).
   */
  async resolve(repository: GitHubRepository): Promise<{ installation: number; repository: GitHubRepository } | null> {
    const direct = await this.installation(repository)
    if (direct !== null) return { installation: direct, repository }
    const current = await this.currentName(repository)
    if (!current) return null
    const renamed = await this.installation(current)
    return renamed === null ? null : { installation: renamed, repository: current }
  }

  /**
   * [repository]'s name as GitHub shows it now, for people to read: a project keeps the address it was given, and GitHub
   * answers an old name by redirect, so a renamed repository was shown by the name it no longer has (autonomous-harness
   * for autonomous-ai/openharness, 2026-10-28). Its own name when GitHub cannot say. Kept ten minutes either way, so a
   * status read costs at most one lookup per repository in that time.
   */
  async currentFullName(repository: GitHubRepository): Promise<string> {
    const key = repository.fullName.toLowerCase()
    const known = this.shownNames.get(key)
    if (known && known.until > this.now()) return known.name
    const name = (await this.currentName(repository))?.fullName ?? repository.fullName
    this.shownNames.set(key, { name, until: this.now() + INSTALLATION_TTL_MS })
    return name
  }

  /** [repository]'s name now when it was renamed, else null: read with a read-only token of its owner's installation of
   *  the app, which GitHub answers by the repository's id once it moved. The token is revoked at once. */
  private async currentName(repository: GitHubRepository): Promise<GitHubRepository | null> {
    const key = repository.fullName.toLowerCase()
    const known = this.renames.get(key)
    if (known && known.until > this.now()) return known.repository
    let current: GitHubRepository | null = null
    try {
      const owner = await this.ownerInstallation(repository.owner)
      if (owner !== null) {
        const minted = await this.call('POST', `/app/installations/${owner}/access_tokens`, `Bearer ${this.jwt()}`, { permissions: { metadata: 'read' } })
        const token = (minted.body as Record<string, unknown>).token
        if (minted.status === 201 && typeof token === 'string') {
          try {
            const read = await this.call('GET', `/repos/${repository.owner}/${repository.name}`, `Bearer ${token}`)
            const fullName = (read.body as Record<string, unknown>).full_name
            const found = read.status === 200 && typeof fullName === 'string' ? githubRepository(`https://github.com/${fullName}`) : null
            if (found && found.fullName.toLowerCase() !== key) current = found
          } finally {
            await this.revoke(token).catch(() => {})
          }
        }
      }
    } catch (error) {
      if (error instanceof GitHubAppError && error.code === 'GITHUB_APP_MISCONFIGURED') throw error
      // GitHub did not say: the repository reads as not installed, as it did before.
    }
    this.renames.set(key, { repository: current, until: this.now() + (current ? INSTALLATION_TTL_MS : NOT_INSTALLED_TTL_MS) })
    return current
  }

  /** The app's installation on [owner], an organization or a user, or null. */
  private async ownerInstallation(owner: string): Promise<number | null> {
    for (const path of [`/orgs/${owner}/installation`, `/users/${owner}/installation`]) {
      const answer = await this.call('GET', path, `Bearer ${this.jwt()}`)
      if (answer.status === 401) throw this.misconfigured()
      const id = (answer.body as Record<string, unknown>).id
      if (answer.status === 200 && typeof id === 'number') return id
    }
    return null
  }

  /** Whether [owner], an organization, lets Harness create a repository there (task #1788). Its installation is remembered
   *  ten minutes (a missing one a minute), and what it granted as for agents' tokens ([granted]). A personal account reads
   *  as not installed: v1 creates in organizations only. */
  async ownerReadiness(owner: string): Promise<OwnerReadiness> {
    const key = owner.toLowerCase()
    let known = this.orgInstallations.get(key)
    if (!known || known.until <= this.now()) {
      const answer = await this.call('GET', `/orgs/${encodeURIComponent(owner)}/installation`, `Bearer ${this.jwt()}`)
      if (answer.status === 401) throw this.misconfigured()
      const id = (answer.body as Record<string, unknown>).id
      if (answer.status === 200 && typeof id === 'number') known = { id, until: this.now() + INSTALLATION_TTL_MS }
      else if (answer.status === 404) known = { id: null, until: this.now() + NOT_INSTALLED_TTL_MS }
      else throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub could not look up the app on ${owner}.`, 502)
      if (this.orgInstallations.size >= 1000) this.orgInstallations.delete(this.orgInstallations.keys().next().value!)
      this.orgInstallations.set(key, known)
    }
    if (known.id === null) return { state: 'not-installed', installUrl: this.installUrl() }
    const granted = await this.granted(known.id)
    if (granted?.repository_creation !== 'write') return { state: 'not-accepted' }
    return { state: 'ready', installation: known.id, canAdd: granted.installation_repositories === 'write' }
  }

  /** Forgets that the app was not on [repository] (and its rename), so the next lookup asks GitHub: a person just
   *  installed it. At most once every REFRESH_MS per repository, so a refresh cannot become a stream of lookups. */
  forget(repository: GitHubRepository): void {
    const key = repository.fullName.toLowerCase()
    const last = this.forgotten.get(key)
    if (last !== undefined && this.now() - last < REFRESH_MS) return
    this.forgotten.set(key, this.now())
    if (this.installations.get(key)?.id === null) this.installations.delete(key)
    if (this.renames.get(key)?.repository === null) this.renames.delete(key)
  }

  /** What [installationId] has granted (GET /app/installations/{id}, with the app's JWT), remembered ten minutes; [fresh]
   *  asks GitHub again. Null when GitHub does not say, remembered a minute: the token then asks for TOKEN_PERMISSIONS alone. */
  private async granted(installationId: number, fresh = false): Promise<TokenPermissions | null> {
    const known = this.grants.get(installationId)
    if (!fresh && known && known.until > this.now()) return known.permissions
    let permissions: TokenPermissions | null = null
    try {
      const answer = await this.call('GET', `/app/installations/${installationId}`, `Bearer ${this.jwt()}`)
      if (answer.status === 401) throw this.misconfigured()
      const listed = (answer.body as Record<string, unknown>).permissions
      if (answer.status === 200 && listed && typeof listed === 'object' && !Array.isArray(listed)) {
        permissions = Object.fromEntries(Object.entries(listed as Record<string, unknown>)
          .filter((entry): entry is [string, 'read' | 'write'] => entry[1] === 'read' || entry[1] === 'write'))
      } else {
        // Said every time, as agents then lose workflow pushes and issue writes with nothing else to show why (review 2 of #2956).
        console.warn(`[github] installation ${installationId}'s permissions unreadable (HTTP ${answer.status}); agent tokens ask for today's set alone`)
      }
    } catch (error) {
      if (!(error instanceof GitHubAppError) || error.code === 'GITHUB_APP_MISCONFIGURED') throw error
      console.warn(`[github] installation ${installationId}'s permissions unreadable (${error.code}); agent tokens ask for today's set alone`)
      // GitHub did not answer: today's set, asked again next time.
      return null
    }
    if (this.grants.size >= 1000) this.grants.delete(this.grants.keys().next().value!)
    this.grants.set(installationId, { permissions, until: this.now() + (permissions ? INSTALLATION_TTL_MS : NOT_INSTALLED_TTL_MS) })
    return permissions
  }

  /** An agent's token's permissions on [installationId]: TOKEN_PERMISSIONS, and each of GRANTED_TOKEN_PERMISSIONS the
   *  installation granted, at the lower of the two levels. */
  private async agentPermissions(installationId: number, fresh = false): Promise<TokenPermissions> {
    const granted = await this.granted(installationId, fresh)
    const permissions: Record<string, 'read' | 'write'> = { ...TOKEN_PERMISSIONS }
    for (const [name, wanted] of Object.entries(GRANTED_TOKEN_PERMISSIONS)) {
      const level = granted?.[name]
      if (level) permissions[name] = level === 'write' && wanted === 'write' ? 'write' : 'read'
    }
    return permissions
  }

  /**
   * A token for [repository] alone. With [permissions] given, those alone; without, an agent's token: TOKEN_PERMISSIONS and
   * what of GRANTED_TOKEN_PERMISSIONS its installation granted. A permission refusal of an agent's token reads the grant
   * again and asks once more when that changes what to ask for: an owner took a permission away within the ten minutes.
   */
  async createToken(installationId: number, repository: GitHubRepository, permissions?: TokenPermissions): Promise<{ token: string; expiresAt: string }> {
    if (permissions) return this.mint(installationId, repository, permissions)
    const asked = await this.agentPermissions(installationId)
    try {
      return await this.mint(installationId, repository, asked)
    } catch (error) {
      if (!(error instanceof GitHubAppError) || error.code !== 'GITHUB_APP_PERMISSIONS') throw error
      const now = await this.agentPermissions(installationId, true)
      if (samePermissions(asked, now)) throw error
      return this.mint(installationId, repository, now)
    }
  }

  private async mint(installationId: number, repository: GitHubRepository, permissions: TokenPermissions): Promise<{ token: string; expiresAt: string }> {
    const forbidden = Object.keys(permissions).filter(name => (NEVER_ON_INSTALLATION_TOKENS as readonly string[]).includes(name))
    if (forbidden.length) throw new GitHubAppError('GITHUB_APP_PERMISSIONS_FORBIDDEN', `An installation token never asks for ${forbidden.join(', ')}.`, 500)
    const answer = await this.call('POST', `/app/installations/${installationId}/access_tokens`, `Bearer ${this.jwt()}`,
      { repositories: [repository.name], permissions })
    const body = answer.body as Record<string, unknown>
    if (answer.status === 201 && typeof body.token === 'string' && typeof body.expires_at === 'string' && Number.isFinite(Date.parse(body.expires_at))) {
      return { token: body.token, expiresAt: body.expires_at }
    }
    if (answer.status === 401) throw this.misconfigured()
    if (answer.status === 404 || answer.status === 422 || answer.status === 403) {
      this.installations.delete(repository.fullName.toLowerCase())
      // GitHub says which: the installation lacks the repository, or has not accepted a permission asked for.
      if (/permission/i.test(String(body.message ?? ''))) {
        throw new GitHubAppError('GITHUB_APP_PERMISSIONS',
          `The Harness GitHub App on ${repository.owner} has not been granted all the permissions it needs. An owner of ${repository.owner} should accept its requested permissions in the app's installation settings.`, 409)
      }
      throw this.notInstalled(repository)
    }
    throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub could not create a token for ${repository.fullName}.`, 502)
  }

  /** One call with an installation [token] this server minted (the merge train's, github/train.ts): its status and JSON body.
   *  Throws [GitHubAppError] GITHUB_UNAVAILABLE when GitHub does not answer. */
  async installationCall(token: string, method: string, path: string, body?: unknown): Promise<{ status: number; body: Record<string, unknown> | unknown[] }> {
    const answer = await this.call(method, path, `Bearer ${token}`, body)
    return { status: answer.status, body: answer.body }
  }

  /** Ends [token] at once (DELETE /installation/token, authorised by the token itself). One GitHub already ended reads as
   *  done. */
  /** One GET of [path] with an installation [token], for readers that page and judge answers themselves (superTabs/releaseWatch.ts):
   *  its status, body, and the next page's path from the Link header. Throws [GitHubAppError] when GitHub does not answer. */
  async get(path: string, token: string): Promise<{ status: number; body: unknown; next?: string }> {
    const answer = await this.call('GET', path, `Bearer ${token}`)
    const next = /<https:\/\/[^/>]+(\/[^>]+)>;\s*rel="next"/.exec(answer.link ?? '')?.[1]
    return { status: answer.status, body: answer.body, ...(next ? { next } : {}) }
  }

  async revoke(token: string): Promise<void> {
    const answer = await this.call('DELETE', '/installation/token', `Bearer ${token}`)
    if (answer.status === 204 || answer.status === 401) return
    throw new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub did not revoke the token (HTTP ${answer.status}).`, 502)
  }

  /** The jobs running and waiting on [repository]'s GitHub Actions (Scholes's goals, piece 5: work that starts heavy CI waits
   *  for the account's limit), or null when the app is not installed there. Read with a token that can only read workflow
   *  runs, revoked as soon as the counts are in; the token, run names and branches never leave this method. Kept
   *  [CI_LOAD_TTL_MS], and routes asking at once share one read; a failed read is not kept. Throws [GitHubAppError] when
   *  GitHub cannot say. */
  async ciLoad(repository: GitHubRepository): Promise<CiLoad | null> {
    const key = repository.fullName.toLowerCase(), now = this.now()
    const known = this.ciLoads.get(key)
    if (known && known.until > now) return known.value
    // Kept per repository a Swarm routes for; the expired ones go once there are many.
    if (this.ciLoads.size >= 200) for (const [k, v] of this.ciLoads) if (v.until <= now) this.ciLoads.delete(k)
    if (this.ciReads.size >= 200) for (const [k, v] of this.ciReads) if (!v.at.some(t => now - t < 3_600_000)) this.ciReads.delete(k)
    const reads = this.ciReads.get(key) ?? { at: [], last: null }
    reads.at = reads.at.filter(t => now - t < 3_600_000)
    this.ciReads.set(key, reads)
    if (reads.at.length >= CI_READS_PER_HOUR) {
      if (reads.last && now - reads.last.at <= CI_STALE_MS) return reads.last.load
      throw new GitHubAppError('GITHUB_CI_BUDGET', `This hour's CI reads for ${repository.fullName} are spent.`, 429)
    }
    reads.at.push(now)
    const value = this.readCiLoad(repository)
    this.ciLoads.set(key, { value, until: now + CI_LOAD_TTL_MS })
    // A failed read leaves the cache only if it is still this read's: one that fails late never drops a newer read's entry.
    value.then(load => { reads.last = { load, at: now } }, () => { if (this.ciLoads.get(key)?.value === value) this.ciLoads.delete(key) })
    return value
  }

  /**
   * Who pushed the pull request [number]'s commits (pushOrigin.ts), remembered by its head alone. A failure never reads as clean.
   */
  async pushOrigin(repository: GitHubRepository, number: number): Promise<PushOrigin> {
    try {
      const resolved = await this.resolve(repository)
      if (!resolved) return 'unknown'
      const { token } = await this.createToken(resolved.installation, resolved.repository, PUSH_ORIGIN_PERMISSIONS)
      const auth = `Bearer ${token}`, name = `${resolved.repository.owner}/${resolved.repository.name}`
      const call: GitHubRead = async path => {
        const answer = await this.call('GET', path, auth)
        const next = /<https:\/\/[^/>]+(\/[^>]+)>;\s*rel="next"/.exec(answer.link ?? '')?.[1]
        return { status: answer.status, body: answer.body, ...(next ? { next } : {}) }
      }
      const pullPath = `/repos/${name}/pulls/${number}`
      const pull = await call(pullPath)
      const sha = (pull.body as { head?: { sha?: unknown } }).head?.sha
      const key = typeof sha === 'string' ? `${name.toLowerCase()}@${sha}` : null
      const known = key ? this.pushOrigins.get(key) : undefined
      if (known && known.until > this.now()) return known.origin
      // The same read of the pull request decides the head and the answer, so a push in between cannot file it under another commit.
      const read: GitHubRead = path => path === pullPath ? Promise.resolve(pull) : call(path)
      const origin = await readPushOrigin(read, name, number, await this.botLogin())
      if (key) {
        if (this.pushOrigins.size >= PUSH_ORIGINS_KEPT) this.pushOrigins.delete(this.pushOrigins.keys().next().value!)
        // An answer for a head holds for good. An `unknown` is asked again a minute later, so retries cost no more than that.
        this.pushOrigins.set(key, { origin, until: origin === 'unknown' ? this.now() + PUSH_UNKNOWN_MS : Infinity })
      }
      return origin
    } catch {
      return 'unknown'
    }
  }

  /** Who pushed [branch]: the default branch is clean, as it passed review; any other reads its one open pull request, and with none is unknown. */
  async branchOrigin(repository: GitHubRepository, branch: string): Promise<PushOrigin> {
    try {
      const resolved = await this.resolve(repository)
      if (!resolved) return 'unknown'
      const { token } = await this.createToken(resolved.installation, resolved.repository, PUSH_ORIGIN_PERMISSIONS)
      const auth = `Bearer ${token}`, { owner, name } = resolved.repository
      const about = await this.call('GET', `/repos/${owner}/${name}`, auth)
      if (about.status === 200 && (about.body as { default_branch?: unknown }).default_branch === branch) return 'clean'
      const listed = await this.call('GET', `/repos/${owner}/${name}/pulls?state=open&head=${encodeURIComponent(`${owner}:${branch}`)}&per_page=2`, auth)
      const number = Array.isArray(listed.body) && listed.body.length === 1 ? (listed.body[0] as { number?: unknown }).number : null
      return listed.status === 200 && typeof number === 'number' ? await this.pushOrigin(repository, number) : 'unknown'
    } catch {
      return 'unknown'
    }
  }

  private async readCiLoad(repository: GitHubRepository): Promise<CiLoad | null> {
    const resolved = await this.resolve(repository)
    if (!resolved) return null
    const { token } = await this.createToken(resolved.installation, resolved.repository, ACTIONS_READ_PERMISSIONS)
    const auth = `Bearer ${token}`, runs = `/repos/${resolved.repository.owner}/${resolved.repository.name}/actions/runs`
    const read = (path: string) => this.call('GET', path, auth)
    const unavailable = () => new GitHubAppError('GITHUB_UNAVAILABLE', `GitHub did not say what runs on ${resolved.repository.fullName}.`, 502)
    const listOf = (body: unknown, field: string) => {
      const items = (body as Record<string, unknown>)[field]
      return Array.isArray(items) ? items.filter((i): i is Record<string, unknown> => !!i && typeof i === 'object') : []
    }
    try {
      const pages = await Promise.all(['in_progress', 'queued'].map(async status => {
        const answer = await read(`${runs}?status=${status}&per_page=${CI_MAX_RUNS}`)
        if (answer.status !== 200) throw unavailable()
        const listed = listOf(answer.body, 'workflow_runs'), total = (answer.body as Record<string, unknown>).total_count
        return { ids: listed.map(r => r.id).filter((id): id is number => Number.isSafeInteger(id)),
          more: Math.max(0, (Number.isSafeInteger(total) ? total as number : 0) - listed.length) }
      }))
      const ids = [...new Set(pages.flatMap(p => p.ids))]
      const counted = ids.slice(0, CI_MAX_RUNS)
      const load: CiLoad = { running: 0, queued: ids.length - counted.length + pages.reduce((n, p) => n + p.more, 0), macosRunning: 0, macosQueued: 0 }
      for (const jobs of await Promise.all(counted.map(async id => {
        const answer = await read(`${runs}/${id}/jobs?filter=latest&per_page=100`)
        if (answer.status !== 200) throw unavailable()
        return listOf(answer.body, 'jobs')
      }))) {
        for (const job of jobs) {
          const mac = Array.isArray(job.labels) && job.labels.some(l => typeof l === 'string' && /macos/i.test(l))
          if (job.status === 'in_progress') { load.running++; if (mac) load.macosRunning++ }
          else if (CI_WAITING.has(String(job.status))) { load.queued++; if (mac) load.macosQueued++ }
        }
      }
      return load
    } finally {
      await this.revoke(token).catch(() => { console.warn(`[github] a CI read's token for ${resolved.repository.fullName} was not revoked; it expires within the hour`) })
    }
  }

  /** Whether pull request [number] is open, merged or closed (GET /repos/{owner}/{repo}/pulls/{number}); missing when GitHub
   *  answers 404, as for another repository's number read in this one (#2602); null when GitHub cannot say, which a caller
   *  must read as possibly open. */
  async pullRequestState(repository: GitHubRepository, number: number, token: string): Promise<'open' | 'merged' | 'closed' | 'missing' | null> {
    try {
      const answer = await this.call('GET', `/repos/${repository.owner}/${repository.name}/pulls/${number}`, `Bearer ${token}`)
      if (answer.status === 404) return 'missing'
      const body = answer.body as Record<string, unknown>
      if (answer.status !== 200 || !['open', 'closed'].includes(String(body.state))) return null
      return body.state === 'open' ? 'open' : typeof body.merged_at === 'string' ? 'merged' : 'closed'
    } catch (error) {
      if (error instanceof GitHubAppError) return null
      throw error
    }
  }

  /**
   * What a task's Engineer is told of its pull request [number] (superTabs/pullRequestEvents.ts): the pull request, its head's
   * latest check runs and its check suites, its reviews and its conversation comments, read with a [PULL_WATCH_PERMISSIONS]
   * token. Each read names the last answer's ETag, and a 304 reuses that answer. Reviews and comments come oldest first, so
   * their last page is read too when there is more than one (review of #2750). Null when GitHub cannot say.
   */
  async watchPullRequest(repository: GitHubRepository, number: number, token: string): Promise<PullRequestWatch | null> {
    const base = `/repos/${repository.owner}/${repository.name}`
    const answerOf = async (path: string, fresh = false): Promise<{ body: Record<string, unknown> | unknown[]; link: string | null } | null> => {
      const kept = this.watched.get(path)
      const answer = await this.call('GET', path, `Bearer ${token}`, undefined, kept && !fresh ? { 'If-None-Match': kept.etag } : {})
      if (answer.status === 304 && kept) return kept
      if (answer.status !== 200) return null
      this.watched.delete(path)
      if (answer.etag) {
        if (this.watched.size >= WATCH_KEPT) this.watched.delete(this.watched.keys().next().value!)
        this.watched.set(path, { etag: answer.etag, body: answer.body, link: answer.link ?? null })
      }
      return { body: answer.body, link: answer.link ?? null }
    }
    const read = async (path: string) => (await answerOf(path))?.body ?? null
    // A full first page is read afresh: a new last page changes its Link, not its body.
    const pages = async (path: string): Promise<unknown[] | null> => {
      const first = await answerOf(path, (this.watched.get(path)?.body as unknown[] | undefined)?.length === 100)
      if (!first || !Array.isArray(first.body)) return null
      const last = /<([^>]+)>;\s*rel="last"/.exec(first.link ?? '')?.[1]
      const lastPath = last?.startsWith(this.apiUrl) ? last.slice(this.apiUrl.length) : null
      if (!lastPath) return first.body
      const tail = await read(lastPath)
      return Array.isArray(tail) ? [...first.body, ...tail] : null
    }
    const text = (value: unknown) => typeof value === 'string' ? value : ''
    const login = (value: unknown) => text((value as { login?: unknown } | null)?.login)
    const at = (value: unknown) => typeof value === 'string' && Number.isFinite(Date.parse(value)) ? Date.parse(value) : null
    try {
      const pull = await read(`${base}/pulls/${number}`) as Record<string, unknown> | null
      const head = text((pull?.head as { sha?: unknown } | undefined)?.sha)
      if (!pull || (pull.state !== 'open' && pull.state !== 'closed') || !/^[0-9a-f]{7,64}$/.test(head)) return null
      const [runs, suites, reviews, comments] = await Promise.all([read(`${base}/commits/${head}/check-runs?per_page=100`),
        read(`${base}/commits/${head}/check-suites?per_page=100`), pages(`${base}/pulls/${number}/reviews?per_page=100`),
        pages(`${base}/issues/${number}/comments?per_page=100`)])
      if (!runs || !suites || !Array.isArray(reviews) || !Array.isArray(comments)) return null
      const list = (value: unknown) => Array.isArray(value) ? value as Array<Record<string, unknown>> : []
      return {
        url: text(pull.html_url) || `https://github.com/${repository.owner}/${repository.name}/pull/${number}`, number,
        state: pull.state, ...typeof pull.merged_at === 'string' ? { merged: true as const } : {}, draft: pull.draft === true, head, base: text((pull.base as { ref?: unknown } | undefined)?.ref) || 'main',
        mergeable: typeof pull.mergeable === 'boolean' ? pull.mergeable : null,
        checkRuns: list((runs as Record<string, unknown>).check_runs).map(run => ({ name: text(run.name), status: text(run.status),
          conclusion: typeof run.conclusion === 'string' ? run.conclusion : null, completedAt: at(run.completed_at) })),
        checkSuites: list((suites as Record<string, unknown>).check_suites).map(suite => ({ status: text(suite.status),
          runs: typeof suite.latest_check_runs_count === 'number' ? suite.latest_check_runs_count : 0 })),
        reviews: list(reviews).filter(review => typeof review.id === 'number').map(review => ({ id: review.id as number, login: login(review.user),
          association: text(review.author_association) || 'NONE', state: text(review.state), body: text(review.body), url: text(review.html_url) })),
        comments: list(comments).filter(comment => typeof comment.id === 'number').map(comment => ({ id: comment.id as number,
          login: login(comment.user), association: text(comment.author_association) || 'NONE', body: text(comment.body), url: text(comment.html_url) })),
      }
    } catch (error) {
      if (error instanceof GitHubAppError) return null
      throw error
    }
  }

  /** The files of a pull request at [head], for its patch id (superTabs/pullRequestPatch.ts, #3394), read with a token of
   *  [PULL_PATCH_PERMISSIONS]: the comparison of the base and head commits the pull request names in one answer
   *  (GET /pulls/{number}, then GET /compare/{base}...{head}), two fixed commits no push changes (review of #3218, round 3:
   *  a listing of the pull request's files ties removed ones to no head, and pages to no single head). Null unless the pull request still names [head], and when GitHub cannot
   *  say or gives as many files as it ever gives ([COMPARE_FILES_MAX]), as it may then have left some out. With the branch it
   *  merges into from the same answer, which the patch id names (security review of #3218, round 3). */
  async pullRequestPatchFiles(repository: GitHubRepository, number: number, token: string, head: string): Promise<{ base: string; files: PullRequestFile[] } | null> {
    const base = `/repos/${repository.owner}/${repository.name}`
    const sha = (value: unknown) => typeof value === 'string' && /^[0-9a-f]{40}$/i.test(value) ? value.toLowerCase() : undefined
    try {
      const pull = await this.call('GET', `${base}/pulls/${number}`, `Bearer ${token}`)
      if (pull.status !== 200) return null
      const named = pull.body as { head?: { sha?: unknown }; base?: { sha?: unknown; ref?: unknown } }
      const at = sha(named.head?.sha), from = sha(named.base?.sha), branch = typeof named.base?.ref === 'string' ? named.base.ref : ''
      if (!at || !from || !branch || at !== head.toLowerCase()) return null
      const compared = await this.call('GET', `${base}/compare/${from}...${at}?per_page=1`, `Bearer ${token}`)
      const listed = compared.status === 200 ? (compared.body as { files?: unknown }).files : undefined
      if (!Array.isArray(listed) || listed.length >= COMPARE_FILES_MAX) return null
      const files = filesOf(listed)
      return files && { base: branch, files }
    } catch (error) {
      if (error instanceof GitHubAppError) return null
      throw error
    }
  }

  /** What the head [head] of pull request [number] is, to judge whether it is git's own merge of its reviewed head and main
   *  (superTabs/mergeCarry.ts, task #3553), read with a token of [PULL_PATCH_PERMISSIONS]: its parents (GET /git/commits); for
   *  a two-parent head, whether its second parent is on the branch the pull request merges into (GET /compare/{it}...{tip},
   *  the base commit the same answer names: identical or ahead), and the files of the three comparisons of fixed commits, each GET /compare/{a}...{b} from their merge
   *  base: main's side (first parent to second), the pull request's (second to first) and the merge (first parent to head). Null
   *  unless the pull request still names [head], when GitHub cannot say, or when a side gives as many files as GitHub ever
   *  gives ([COMPARE_FILES_MAX]), as it may have left some out. With the branch from the same answer as the pull request. */
  async mainMergeSides(repository: GitHubRepository, number: number, token: string, head: string): Promise<{ base: string; sides: MergeSides } | null> {
    const base = `/repos/${repository.owner}/${repository.name}`
    const sha = (value: unknown) => typeof value === 'string' && /^[0-9a-f]{40}$/i.test(value) ? value.toLowerCase() : undefined
    const files = async (from: string, to: string) => {
      const compared = await this.call('GET', `${base}/compare/${from}...${to}?per_page=1`, `Bearer ${token}`)
      const listed = compared.status === 200 ? (compared.body as { files?: unknown }).files : undefined
      return Array.isArray(listed) && listed.length < COMPARE_FILES_MAX ? filesOf(listed) : null
    }
    try {
      const pull = await this.call('GET', `${base}/pulls/${number}`, `Bearer ${token}`)
      if (pull.status !== 200) return null
      const named = pull.body as { head?: { sha?: unknown }; base?: { sha?: unknown; ref?: unknown } }
      // The base as a commit, from the same answer (security review of #3284, Important 1): a branch name a tag of the same
      // name could shadow is never compared against.
      const at = sha(named.head?.sha), tip = sha(named.base?.sha), branch = typeof named.base?.ref === 'string' ? named.base.ref : ''
      if (!at || !tip || !branch || at !== head.toLowerCase()) return null
      const commit = await this.call('GET', `${base}/git/commits/${at}`, `Bearer ${token}`)
      const listed = commit.status === 200 ? (commit.body as { parents?: unknown }).parents : undefined
      if (!Array.isArray(listed)) return null
      const parents = listed.map(p => sha((p as { sha?: unknown })?.sha))
      if (parents.some(p => p === undefined)) return null
      const none: MergeSides = { parents: parents as string[], onBase: false, prSide: [], mainSide: [], mergeSide: [] }
      if (parents.length !== 2) return { base: branch, sides: none }
      const [parent, merged] = parents as [string, string]
      const onBranch = await this.call('GET', `${base}/compare/${merged}...${tip}?per_page=1`, `Bearer ${token}`)
      const status = onBranch.status === 200 ? (onBranch.body as { status?: unknown }).status : undefined
      if (status !== 'identical' && status !== 'ahead') return { base: branch, sides: none }
      const [mainSide, prSide, mergeSide] = [await files(parent, merged), await files(merged, parent), await files(parent, at)]
      if (!mainSide || !prSide || !mergeSide) return null
      return { base: branch, sides: { parents: [parent, merged], onBase: true, prSide, mainSide, mergeSide } }
    } catch (error) {
      if (error instanceof GitHubAppError) return null
      throw error
    }
  }

  /**
   * The files pull request [number] changes, read with the watch's read-only token (task #3401: its review steps are planned
   * from them): GET /pulls/{n}/files, 100 a page. A renamed file is listed under its old name too, so moving a file out of a
   * sensitive path still counts as changing it. Null when GitHub cannot say, or when the list may be cut at GitHub's 3,000.
   */
  async pullRequestFiles(repository: GitHubRepository, number: number, token: string): Promise<Array<{ filename: string }> | null> {
    const names = new Set<string>()
    const text = (value: unknown) => typeof value === 'string' && value ? value : undefined
    try {
      for (let page = 1; page <= PULL_FILES_PAGES; page++) {
        const answer = await this.call('GET', `/repos/${repository.owner}/${repository.name}/pulls/${number}/files?per_page=100&page=${page}`, `Bearer ${token}`)
        if (answer.status !== 200 || !Array.isArray(answer.body)) return null
        for (const file of answer.body as Array<Record<string, unknown>>) {
          const filename = text(file.filename)
          if (!filename) return null
          names.add(filename)
          const previous = text(file.previous_filename)
          if (previous) names.add(previous)
        }
        if (answer.body.length < 100) return [...names].map(filename => ({ filename }))
      }
      // A full last page: GitHub lists at most 3,000 files, so more may exist.
      return null
    } catch (error) {
      if (error instanceof GitHubAppError) return null
      throw error
    }
  }

  /** The default branch and whether pushing to it straight needs a pull request, read with the agent's own token
   *  (metadata and contents read): rulesets first (GET /repos/{owner}/{repo}/rules/branches/{branch}), then classic
   *  protection's flag on the branch. Remembered ten minutes; a failed read is `unknown`, never a refusal. */
  async defaultBranch(repository: GitHubRepository, token: string): Promise<DefaultBranch> {
    const key = repository.fullName.toLowerCase()
    const known = this.branches.get(key)
    if (known && known.until > this.now()) return known.value
    const auth = `Bearer ${token}`, path = `/repos/${repository.owner}/${repository.name}`
    let value: DefaultBranch = { branch: null, protection: 'unknown' }
    try {
      const repo = await this.call('GET', path, auth)
      const branch = (repo.body as Record<string, unknown>).default_branch
      if (repo.status === 200 && typeof branch === 'string' && branch) {
        value = { branch, protection: 'unknown' }
        const rules = await this.call('GET', `${path}/rules/branches/${encodeURIComponent(branch)}`, auth)
        if (rules.status === 200 && Array.isArray(rules.body) && rules.body.some(rule => (rule as Record<string, unknown>)?.type === 'pull_request')) {
          value = { branch, protection: 'pull_request' }
        } else {
          const classic = await this.call('GET', `${path}/branches/${encodeURIComponent(branch)}`, auth)
          const flag = (classic.body as Record<string, unknown>).protected
          if (classic.status === 200 && typeof flag === 'boolean') value = { branch, protection: flag ? 'classic' : 'none' }
        }
      }
    } catch (error) {
      if (!(error instanceof GitHubAppError)) throw error
    }
    if (value.protection !== 'unknown') this.branches.set(key, { value, until: this.now() + BRANCH_TTL_MS })
    return value
  }
}