@bongos/core 1.17.0

package/modules/lifecycle/github-push.js

@@ -0,0 +1,969 @@
+// GDS server-mediated branch publish (ADR 0055 / task 1025).
+//
+// WHY THIS EXISTS
+// A builder on a cloud dev box cannot publish in `ci` deploy mode: the box has
+// NO GitHub push credential by design (credential-less HTTPS origin, no gh, no
+// GH_TOKEN — infra/builder-box-cloud-init.yaml scrubs the clone token), and its
+// baked GDS session is box-scoped (deny-by-default, #919/ADR 0053). CI self-
+// deploy (#859/ADR 0042) fixed only the LAST leg (Actions deploys main->prod);
+// the box still can't get its branch onto GitHub to open the PR.
+//
+// THE FIX (owner-chosen: "the box holds nothing"). The box uploads its branch as
+// a THIN git bundle to the GDS over a RE-AUTHED (non-box) cli session; the server
+// pushes the branch to GitHub + opens the PR + enables auto-merge using a SERVER-
+// side push credential. The box never holds a GitHub push credential, so the #919
+// model is preserved. The credential is scoped to a single repo (Contents:write +
+// Pull-requests:write + Actions:read) and CANNOT push to branch-protected `main`
+// nor bypass required checks — a leaked server credential can only land code on a
+// feature branch behind the same checks every PR faces.
+//
+// THE SERVER CREDENTIAL (task 1028 / ADR 0055 hardening). Preferred: a GitHub
+// APP — the server holds ONLY the App private key and mints a SHORT-LIVED,
+// repo-scoped INSTALLATION token (1h) per push window, so there's no standing
+// push secret at rest. Set GITHUB_APP_ID + GITHUB_APP_INSTALLATION_ID +
+// GITHUB_APP_PRIVATE_KEY. Fallback (v1, kept for cutover): a standing fine-grained
+// PAT in GITHUB_PUSH_TOKEN. resolveToken() prefers the App, then the PAT; the App
+// JWT is RS256-signed with node:crypto (no jsonwebtoken / Octokit dependency).
+//
+// This module is the server seam: push a bundle, open/find the PR, enable auto-
+// merge, report status. All git runs through execFile arg-arrays (shell:false,
+// the #681 injection discipline); the credentialed URL is built in-process and
+// NEVER persisted to a remote nor echoed on an error path (the box-source-fetch.sh
+// "one-shot URL, scrub the credential" pattern). The GitHub API calls are raw
+// global fetch (no Octokit — fetch is used throughout auth.js), header shape
+// mirrors auth.js fetchGithubUser.
+
+const { execFile } = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { promisify } = require('node:util');
+const { repoInfo, userAgent } = require('../../src/module-api');
+const { loadRepoInfo } = repoInfo;
+
+const execFileP = promisify(execFile);
+
+// The server's own checkout root — a fast LOCAL object source for the bundle's
+// `main..HEAD` prerequisites (so we never clone the whole repo over the network).
+// Reading it via `git clone --bare --local` does NOT touch its working tree, so
+// it never races the deploy worktree that `~/deploy.sh` resets.
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// A branch ref the server will interpolate into argv + the GitHub API. Keep it
+// to the chars a real `claude/*` worktree branch uses; reject anything that could
+// be an option (leading '-'), a traversal ('..'), or a fully-qualified ref.
+const SAFE_BRANCH_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,200}$/;
+const SAFE_SHA_RE = /^[0-9a-f]{7,64}$/;
+
+// Configured if EITHER credential is present: a GitHub App (preferred) or the
+// v1 PAT fallback. The route 503s when neither is set (task 1028).
+function appConfigured() {
+  return !!(
+    process.env.GITHUB_APP_ID &&
+    process.env.GITHUB_APP_INSTALLATION_ID &&
+    process.env.GITHUB_APP_PRIVATE_KEY
+  );
+}
+
+function isConfigured() {
+  return !!process.env.GITHUB_PUSH_TOKEN || appConfigured();
+}
+
+function isSafeBranch(branch) {
+  return (
+    typeof branch === 'string' &&
+    SAFE_BRANCH_RE.test(branch) &&
+    !branch.includes('..') &&
+    !branch.startsWith('refs/')
+  );
+}
+
+function err(code, extra = {}) {
+  const e = new Error(code);
+  e.code = code;
+  Object.assign(e, extra);
+  return e;
+}
+
+// Extract the usable `repository` from a GraphQL response, tolerating PARTIAL errors.
+//
+// GitHub GraphQL returns `data` (with the un-readable field nulled) ALONGSIDE an
+// `errors` array on a partial failure — e.g. a FORBIDDEN on statusCheckRollup.contexts
+// when the App installation lacks the `Checks: read` permission (operator blocker). A
+// brittle `if (out.errors) throw` discards the whole usable response and surfaces to the
+// caller as a 502; instead, use the data we DID get (the forbidden sub-fields come back
+// null, which every reader here already null-guards) and throw GRAPHQL_FAILED ONLY when
+// there is no repository data at all (a genuine top-level failure: bad credential, SAML,
+// rate-limit). Returns { repository, partialErrors } — partialErrors is the list of
+// GraphQL error types present on an otherwise-usable response, so a caller can signal
+// reduced fidelity (e.g. "checks unreadable") instead of silently degrading.
+function graphqlRepository(out) {
+  const repository = out && out.data && out.data.repository;
+  const errors = (out && out.errors) || [];
+  if (repository) {
+    return { repository, partialErrors: errors.map((e) => e && e.type).filter(Boolean) };
+  }
+  // No data → fatal. Surface the error detail (truncated) so the cause is loud in logs
+  // and in the structured route response.
+  throw err('GRAPHQL_FAILED', { detail: JSON.stringify(errors.length ? errors : 'no data').slice(0, 200) });
+}
+
+// Build the one-shot authenticated push URL. NEVER logged, NEVER written to a
+// persisted remote — it lives only as an argv element to a single git push/fetch.
+function buildAuthUrl(owner, repo, token) {
+  const u = new URL(`https://github.com/${owner}/${repo}.git`);
+  u.username = 'x-access-token';
+  u.password = token;
+  return u.toString();
+}
+
+// Strip any embedded push credential from captured git output before it is logged
+// or returned. The auth URL is x-access-token:<token>@github.com/…; git usually
+// redacts the password in its own messages, but belt-and-brace it here too (task
+// 1547 — we now SURFACE git stderr for diagnosability, so it must be scrubbed).
+function scrubCredential(s) {
+  return String(s || '')
+    .replace(/x-access-token:[^@\s/]+@/gi, 'x-access-token:***@')
+    .replace(/(ghs_|ghp_|github_pat_)[A-Za-z0-9_]+/g, '$1***');
+}
+
+// Default git seam: execFile arg-array, shell:false, stdout captured. On failure
+// throws GIT_FAILED. We never echo the (possibly credentialed) argv, but DO attach
+// the credential-scrubbed stderr + the caller's step label (task 1547) so a real
+// failure is a one-line log read instead of a multi-hour mystery — the BV1.R04/R05
+// outage was a ~2h opaque GIT_FAILED window with no clue WHICH step or WHY. Tests
+// inject their own `exec`.
+async function defaultExec(args, opts = {}) {
+  const { step, ...execOpts } = opts;
+  try {
+    const { stdout } = await execFileP('git', args, {
+      encoding: 'utf8',
+      timeout: 120000,
+      maxBuffer: 64 * 1024 * 1024,
+      ...execOpts,
+      shell: false,
+    });
+    return stdout;
+  } catch (e) {
+    // Identify the failing step by the caller's label, never by echoing argv.
+    // Surface the scrubbed stderr (truncated) so the cause is loud in the log.
+    const stderr = scrubCredential(e && (e.stderr || e.message)).trim().slice(0, 500);
+    throw err('GIT_FAILED', { git_step: step || (args && args[0]) || null, stderr });
+  }
+}
+
+// Default GitHub-API seam (raw fetch). Tests inject `fetchImpl`.
+function ghHeaders(token) {
+  return {
+    Authorization: `Bearer ${token}`,
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': userAgent(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// GitHub App credential (task 1028 / ADR 0055 hardening)
+// Hold only the App private key at rest; mint a short-lived, repo-scoped
+// installation token per push window instead of a standing PAT.
+// ---------------------------------------------------------------------------
+
+function b64url(input) {
+  return Buffer.from(input)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+// A PEM may arrive as a single env-line with literal "\n"; restore real newlines
+// (and tolerate a key already containing real newlines).
+function normalizePem(pem) {
+  return pem.includes('\\n') && !pem.includes('\n') ? pem.replace(/\\n/g, '\n') : pem;
+}
+
+// Mint an App JWT (RS256, node:crypto — no jsonwebtoken dependency). iat is
+// backdated 60s for clock skew; exp is +9min (GitHub caps App JWTs at 10).
+function mintAppJwt({ appId, privateKeyPem, nowSec }) {
+  const iat = nowSec - 60;
+  const exp = nowSec + 9 * 60;
+  const header = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+  const payload = b64url(JSON.stringify({ iat, exp, iss: String(appId) }));
+  const signingInput = `${header}.${payload}`;
+  const signer = crypto.createSign('RSA-SHA256');
+  signer.update(signingInput);
+  signer.end();
+  const sig = b64url(signer.sign(normalizePem(privateKeyPem)));
+  return `${signingInput}.${sig}`;
+}
+
+// Module-level cache of the current installation token, reused until ~60s before
+// expiry. Installation tokens are short-lived by construction (1h) and repo-
+// scoped to the single repo this server serves.
+let _instCache = { token: null, expEpoch: 0 };
+function _resetAppTokenCacheForTests() {
+  _instCache = { token: null, expEpoch: 0 };
+}
+
+// Returns a fresh/cached App installation token, or null if the App isn't
+// configured (so resolveToken can fall through to the PAT). Throws
+// APP_TOKEN_FAILED if the App IS configured but the exchange fails.
+async function getInstallationToken(deps = {}) {
+  if (!appConfigured()) return null;
+  const nowSec = Math.floor((deps.now ? deps.now() : Date.now()) / 1000);
+  if (_instCache.token && _instCache.expEpoch - nowSec > 60) return _instCache.token;
+
+  const jwt = mintAppJwt({
+    appId: process.env.GITHUB_APP_ID,
+    privateKeyPem: process.env.GITHUB_APP_PRIVATE_KEY,
+    nowSec,
+  });
+  const doFetch = deps.fetchImpl || fetch;
+  const res = await doFetch(
+    `https://api.github.com/app/installations/${process.env.GITHUB_APP_INSTALLATION_ID}/access_tokens`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${jwt}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'User-Agent': userAgent(),
+      },
+    }
+  );
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '');
+    throw err('APP_TOKEN_FAILED', { status: res.status, detail: detail.slice(0, 200) });
+  }
+  const data = await res.json();
+  _instCache = {
+    token: data.token,
+    expEpoch: Math.floor(new Date(data.expires_at).getTime() / 1000),
+  };
+  return data.token;
+}
+
+// Resolve the credential for git push + GitHub API: an explicitly-injected token
+// (tests) first, then a GitHub App installation token, then the v1 PAT, else null.
+async function resolveToken(deps = {}) {
+  if (deps.token) return deps.token;
+  const appTok = await getInstallationToken(deps);
+  if (appTok) return appTok;
+  return process.env.GITHUB_PUSH_TOKEN || null;
+}
+
+// ---------------------------------------------------------------------------
+// pushBundle — receive a thin branch bundle, push it to origin via the server's
+// credential. Returns { head_sha } (the tip actually pushed). Throws:
+//   PUSH_UNCONFIGURED  — no server push credential (neither GitHub App nor PAT)
+//   NO_REPO_INFO       — couldn't resolve owner/repo
+//   BAD_BRANCH         — branch ref failed the safe pattern
+//   TIP_MISMATCH       — the bundle's tip != the claimed head_sha (with {tip})
+//   GIT_FAILED         — any git step failed
+// ---------------------------------------------------------------------------
+async function pushBundle({ bundlePath, branch, headSha }, deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token) throw err('PUSH_UNCONFIGURED');
+  if (!isSafeBranch(branch)) throw err('BAD_BRANCH');
+  if (headSha != null && !SAFE_SHA_RE.test(String(headSha))) throw err('BAD_SHA');
+
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfo;
+
+  const exec = deps.exec || defaultExec;
+  const repoRoot = deps.repoRoot || REPO_ROOT;
+  const authUrl = buildAuthUrl(owner, repo, token);
+  const ref = `refs/heads/${branch}`;
+
+  const tmp = (deps.mkdtemp || (() => fs.mkdtempSync(path.join(os.tmpdir(), 'otb-publish-'))))();
+  const workGit = path.join(tmp, 'work.git');
+  try {
+    // 1. Fast LOCAL bare clone for main's objects (no network, no worktree touch).
+    //    Fall back to a shallow network clone if the local checkout isn't a repo
+    //    (stripped container, test env).
+    try {
+      await exec(['clone', '--bare', '--local', repoRoot, workGit], { step: 'clone-local' });
+    } catch (_) {
+      await exec(['clone', '--bare', '--depth=200', authUrl, workGit], { step: 'clone-network' });
+    }
+    // 2. Top up recent `main` objects so a freshly-branched base commit is present
+    //    even if the droplet checkout trails origin/main (just-merged-not-deployed).
+    //    Best-effort: the bundle is usually self-sufficient against the local main.
+    try {
+      await exec(['-C', workGit, 'fetch', '--no-tags', authUrl, 'main'], { step: 'fetch-main' });
+    } catch (_) {
+      /* tolerated — step 3 fails loudly if a prerequisite is genuinely missing */
+    }
+    // 3. Unbundle the thin branch bundle (prerequisites = main, present above).
+    await exec(['-C', workGit, 'fetch', bundlePath, `${ref}:${ref}`], { step: 'unbundle' });
+    // 4. Verify the unbundled tip equals the claimed head_sha (anti-spoof: the
+    //    grade ran against THIS sha client-side; the pushed code must match).
+    const tip = (await exec(['-C', workGit, 'rev-parse', ref], { step: 'rev-parse' })).trim();
+    if (headSha && tip !== headSha) throw err('TIP_MISMATCH', { tip });
+    // 5. Push to GitHub via the explicit authenticated URL (never the inherited
+    //    remote). Refuse non-fast-forward implicitly (no --force, ever).
+    await exec(['-C', workGit, 'push', authUrl, `${ref}:${ref}`], { step: 'push' });
+    return { head_sha: tip };
+  } finally {
+    try {
+      (deps.rmtmp || ((d) => fs.rmSync(d, { recursive: true, force: true })))(tmp);
+    } catch (_) {
+      /* temp cleanup is best-effort */
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// openOrFindPullRequest — open a PR branch->main, or reuse the existing open one
+// (gh pr create is not idempotent; mirror ciLand's "check first" behaviour).
+// Returns { number, url, node_id }.
+// ---------------------------------------------------------------------------
+async function openOrFindPullRequest({ branch, title, body }, deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token) throw err('PUSH_UNCONFIGURED');
+  if (!isSafeBranch(branch)) throw err('BAD_BRANCH');
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const api = `https://api.github.com/repos/${owner}/${repo}`;
+
+  // Reuse an existing open PR for this head if one exists.
+  const listRes = await doFetch(
+    `${api}/pulls?head=${encodeURIComponent(`${owner}:${branch}`)}&state=open`,
+    { headers: ghHeaders(token) }
+  );
+  if (listRes.ok) {
+    const existing = await listRes.json();
+    if (Array.isArray(existing) && existing.length) {
+      const pr = existing[0];
+      return { number: pr.number, url: pr.html_url, node_id: pr.node_id };
+    }
+  }
+
+  const createRes = await doFetch(`${api}/pulls`, {
+    method: 'POST',
+    headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ title, head: branch, base: 'main', body }),
+  });
+  if (!createRes.ok) {
+    const detail = await createRes.text().catch(() => '');
+    throw err('PR_CREATE_FAILED', { status: createRes.status, detail: detail.slice(0, 300) });
+  }
+  const pr = await createRes.json();
+  return { number: pr.number, url: pr.html_url, node_id: pr.node_id };
+}
+
+// enableAutoMerge — arm GitHub to merge once required checks + branch protection
+// pass (the GraphQL analogue of `gh pr merge --auto --merge`). mergeMethod MERGE
+// keeps the project's --no-ff merge-commit convention. Best-effort: a repo
+// without auto-merge enabled, or a PR already mergeable, returns false and the
+// caller surfaces the open PR (exactly like ciLand on a failed enable).
+async function enableAutoMerge({ nodeId }, deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token || !nodeId) return false;
+  const doFetch = deps.fetchImpl || fetch;
+  const query = `mutation($id:ID!){enablePullRequestAutoMerge(input:{pullRequestId:$id,mergeMethod:MERGE}){clientMutationId}}`;
+  try {
+    const res = await doFetch('https://api.github.com/graphql', {
+      method: 'POST',
+      headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query, variables: { id: nodeId } }),
+    });
+    if (!res.ok) return false;
+    const out = await res.json();
+    return !out.errors;
+  } catch (_) {
+    return false;
+  }
+}
+
+// getPublishStatus — report the PR + prod-deploy state so ship.js can poll
+// WITHOUT gh on the box. Returns:
+//   { pr_state, merged, merge_sha, deploy_status }  where
+//   pr_state ∈ open|closed|none, deploy_status ∈ pending|success|none.
+// Mirrors ship.js pollCiDeploy's two-stage check (PR merged -> deploy run).
+async function getPublishStatus({ branch }, deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token) throw err('PUSH_UNCONFIGURED');
+  if (!isSafeBranch(branch)) throw err('BAD_BRANCH');
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const api = `https://api.github.com/repos/${owner}/${repo}`;
+
+  // Find the most-recent PR for this head (open OR closed/merged).
+  const prRes = await doFetch(
+    `${api}/pulls?head=${encodeURIComponent(`${owner}:${branch}`)}&state=all&sort=created&direction=desc&per_page=1`,
+    { headers: ghHeaders(token) }
+  );
+  if (!prRes.ok) throw err('STATUS_FETCH_FAILED', { status: prRes.status });
+  const prs = await prRes.json();
+  if (!Array.isArray(prs) || !prs.length) {
+    return {
+      pr_state: 'none', merged: false, merge_sha: null, deploy_status: 'none',
+      pr_url: null, pr_number: null, pr_title: null, pr_body: null,
+    };
+  }
+  const pr = prs[0];
+  const merged = !!pr.merged_at;
+  const mergeSha = pr.merge_commit_sha || null;
+  // task 1547: surface the matched PR's identity so the reconcile can verify the PR
+  // belongs to THIS task (anti branch-reuse) when no published tip was recorded.
+  const prMeta = { pr_number: pr.number || null, pr_title: pr.title || null, pr_body: pr.body || null };
+  if (!merged) {
+    return { pr_state: pr.state, merged: false, merge_sha: mergeSha, deploy_status: 'pending', pr_url: pr.html_url, ...prMeta };
+  }
+
+  // Merged → did the prod-deploy workflow succeed for the merge commit?
+  let deployStatus = 'pending';
+  try {
+    const runsRes = await doFetch(
+      `${api}/actions/workflows/deploy-prod.yml/runs?branch=main&per_page=15`,
+      { headers: ghHeaders(token) }
+    );
+    if (runsRes.ok) {
+      const data = await runsRes.json();
+      const runs = (data && data.workflow_runs) || [];
+      const hit = runs.some(
+        (r) => r && r.head_sha === mergeSha && r.status === 'completed' && r.conclusion === 'success'
+      );
+      if (hit) deployStatus = 'success';
+    }
+  } catch (_) {
+    /* leave pending on a transient runs-API miss */
+  }
+  return { pr_state: pr.state, merged: true, merge_sha: mergeSha, deploy_status: deployStatus, pr_url: pr.html_url, ...prMeta };
+}
+
+// task 1547 — does the PR matched by getPublishStatus actually belong to THIS task?
+// The robust land proof is published-tip containment; this is the fallback used when
+// no published tip was recorded (a legacy row, or a publish in flight across the
+// deploy that introduced the tip column). The server-mediated publish writes
+// "task <id>:" in the PR title and "for task <id>" in the body (routes/tasks.js),
+// and ship.js's local path titles its PR "task <id>: …" too, so a word-boundary
+// "task #?<id>" match positively binds the matched PR to this task — and a REUSED
+// branch whose latest PR was a DIFFERENT task (the BV1.R04/R05 → PR #386/task 1297
+// case) fails the match, so the reconcile refuses to ship. Pure + sync.
+function prReferencesTask(status, taskId) {
+  if (!status || !Number.isInteger(Number(taskId))) return false;
+  const hay = `${status.pr_title || ''}\n${status.pr_body || ''}`;
+  return new RegExp(`\\btask\\s+#?${Number(taskId)}\\b`, 'i').test(hay);
+}
+
+// ---------------------------------------------------------------------------
+// Active merge driver (task 1162) — land a green PR the moment it's mergeable
+// instead of waiting on GitHub's auto-merge daemon.
+//
+// WHY. enableAutoMerge only ARMS GitHub; GitHub's auto-merge fires on check-
+// completion EVENTS. When a publish is re-driven and auto-merge is re-armed on a
+// PR whose checks are ALREADY green, no fresh event arrives and the daemon never
+// re-evaluates — the PR sits open + CLEAN + mergeable indefinitely, getPublishStatus
+// reports merged:false forever, and the task strands at 'confirmed' (observed live
+// on PR #125 / task 1093: 7/7 checks green, CLEAN, ~30+ min, never merged, needed a
+// human click). This makes the SERVER perform the merge.
+//
+// SAFETY. The merge uses the same server credential that pushed the branch + opened
+// the PR — it merges exactly where it is already allowed and CANNOT bypass branch
+// protection. We merge ONLY when GitHub's own gate is satisfied (mergeable AND
+// mergeStateStatus===CLEAN, the same condition GitHub auto-merge waits for). A
+// review-gated PR the App can't approve reports BLOCKED here and the merge API 405s
+// — we surface that reason, we never force it.
+
+// getMergeState — one GraphQL read of the most-recent PR for `branch`: its merged
+// flag, mergeability, merge-state (the CLEAN/BLOCKED/… GitHub's auto-merge gates
+// on), review decision, head sha, and per-check rollup. Pure w.r.t. injected
+// fetchImpl/repoInfo/token so it's unit-tested with no network.
+async function getMergeState({ branch }, deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token) throw err('PUSH_UNCONFIGURED');
+  if (!isSafeBranch(branch)) throw err('BAD_BRANCH');
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const query = `query($owner:String!,$repo:String!,$head:String!){
+    repository(owner:$owner,name:$repo){
+      pullRequests(headRefName:$head, first:1, orderBy:{field:CREATED_AT,direction:DESC}){
+        nodes{
+          number id state merged mergeable reviewDecision mergeStateStatus
+          commits(last:1){ nodes{ commit{ oid
+            statusCheckRollup{ state contexts(first:50){ nodes{
+              __typename
+              ... on CheckRun{ name conclusion status }
+              ... on StatusContext{ context state }
+            }}}
+          }}}
+        }
+      }
+    }
+  }`;
+  const res = await doFetch('https://api.github.com/graphql', {
+    method: 'POST',
+    headers: {
+      ...ghHeaders(token),
+      'Content-Type': 'application/json',
+      // mergeStateStatus historically required this preview media type; GA now,
+      // but sending it is harmless and belt-and-braces against older endpoints.
+      Accept: 'application/vnd.github.merge-info-preview+json',
+    },
+    body: JSON.stringify({ query, variables: { owner, repo, head: branch } }),
+  });
+  if (!res.ok) throw err('STATUS_FETCH_FAILED', { status: res.status });
+  const out = await res.json();
+  // Partial FORBIDDEN on the check rollup (App lacks Checks:read) must not sink the whole
+  // read: mergeIfGreen gates on mergeable/mergeStateStatus (top-level, readable), and the
+  // checks array only feeds the human-readable block reason.
+  const { repository } = graphqlRepository(out);
+  const node = repository.pullRequests
+    && repository.pullRequests.nodes && repository.pullRequests.nodes[0];
+  if (!node) {
+    return {
+      pr_state: 'none', number: null, node_id: null, merged: false, head_sha: null,
+      mergeable: null, merge_state: null, review_decision: null, rollup_state: null, checks: [],
+    };
+  }
+  const commit = (node.commits && node.commits.nodes && node.commits.nodes[0] && node.commits.nodes[0].commit) || {};
+  const rollup = commit.statusCheckRollup || null;
+  // .filter(Boolean): a partial FORBIDDEN (App lacks Checks:read) nulls the individual
+  // CheckRun ELEMENTS inside contexts.nodes; drop the holes before mapping.
+  const checks = ((rollup && rollup.contexts && rollup.contexts.nodes) || []).filter(Boolean).map((c) =>
+    c.__typename === 'CheckRun'
+      ? { name: c.name, conclusion: c.conclusion, status: c.status }
+      : { name: c.context, conclusion: c.state, status: 'COMPLETED' }
+  );
+  return {
+    pr_state: String(node.state || '').toLowerCase(), // open|closed|merged
+    number: node.number,
+    node_id: node.id,
+    merged: !!node.merged,
+    head_sha: commit.oid || null,
+    mergeable: node.mergeable || null,          // MERGEABLE|CONFLICTING|UNKNOWN
+    merge_state: node.mergeStateStatus || null, // CLEAN|BLOCKED|BEHIND|DIRTY|DRAFT|UNSTABLE|HAS_HOOKS|UNKNOWN
+    review_decision: node.reviewDecision || null, // APPROVED|REVIEW_REQUIRED|CHANGES_REQUESTED|null
+    rollup_state: (rollup && rollup.state) || null, // SUCCESS|PENDING|FAILURE|ERROR|EXPECTED
+    checks,
+  };
+}
+
+// A non-passing check conclusion (everything that isn't a clean success/skip).
+const _BAD_CHECK = (c) =>
+  c.conclusion && !['SUCCESS', 'NEUTRAL', 'SKIPPED'].includes(String(c.conclusion).toUpperCase());
+
+// Human-readable reason a not-yet-merged PR isn't mergeable, surfaced to a
+// credential-less session so it reports the truth instead of guessing.
+function mergeBlockReason(s) {
+  if (!s) return 'unknown';
+  if (s.merged) return null;
+  if (s.pr_state !== 'open') return 'no_open_pr';
+  if (s.mergeable === 'CONFLICTING' || s.merge_state === 'DIRTY') return 'merge_conflict';
+  if (s.merge_state === 'BEHIND') return 'branch_behind_base';
+  if (s.merge_state === 'DRAFT') return 'draft_pr';
+  if (s.review_decision === 'CHANGES_REQUESTED') return 'changes_requested';
+  if (s.review_decision === 'REVIEW_REQUIRED') return 'review_required';
+  if (s.merge_state === 'BLOCKED') {
+    const bad = s.checks.filter(_BAD_CHECK);
+    if (bad.length) return `failing_check:${bad[0].name}`;
+    return 'blocked_required_review_or_pending_check';
+  }
+  if (s.merge_state === 'UNSTABLE') {
+    const bad = s.checks.filter(_BAD_CHECK);
+    return bad.length ? `non_required_check_failing:${bad[0].name}` : 'non_required_check_pending';
+  }
+  if (s.mergeable === 'UNKNOWN' || s.merge_state === 'UNKNOWN' || s.merge_state == null) {
+    return 'mergeability_computing';
+  }
+  return String(s.merge_state).toLowerCase();
+}
+
+// mergeIfGreen — read the PR's merge state and, IFF GitHub's own gate is satisfied
+// (mergeable AND CLEAN), perform the merge the auto-merge daemon didn't. Returns a
+// rich result that doubles as diagnostics for the publish-status route:
+//   { pr_state, number, merged, merged_now, mergeable, merge_state,
+//     review_decision, rollup_state, checks, reason }
+// merged_now is true ONLY when this call performed the merge. reason is the blocker
+// when merged stays false. Best-effort merge: a 405 (review-gated)/409 (head moved)
+// leaves the PR for the next sweep with the status surfaced, never forced.
+async function mergeIfGreen({ branch }, deps = {}) {
+  const s = await getMergeState({ branch }, deps);
+  const base = {
+    pr_state: s.pr_state, number: s.number, merged: s.merged, merged_now: false,
+    mergeable: s.mergeable, merge_state: s.merge_state, review_decision: s.review_decision,
+    rollup_state: s.rollup_state, checks: s.checks, reason: null,
+  };
+  if (s.merged) return base;
+  if (s.pr_state !== 'open') return { ...base, reason: 'no_open_pr' };
+  if (!(s.mergeable === 'MERGEABLE' && s.merge_state === 'CLEAN')) {
+    return { ...base, reason: mergeBlockReason(s) };
+  }
+  // Green + stalled → merge it. mergeMethod MERGE keeps the --no-ff convention
+  // (matches enableAutoMerge). Pin the expected head sha so a race that moved the
+  // tip 409s instead of merging stale code.
+  const token = await resolveToken(deps);
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const res = await doFetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${s.number}/merge`, {
+    method: 'PUT',
+    headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ merge_method: 'merge', ...(s.head_sha ? { sha: s.head_sha } : {}) }),
+  });
+  if (res.ok) return { ...base, merged: true, merged_now: true };
+  const detail = await res.text().catch(() => '');
+  return { ...base, reason: `merge_api_${res.status}`, detail: detail.slice(0, 160) };
+}
+
+// task 1139 (ADR 0058): server-set commit status — the TRUSTLESS rank attestation the
+// gate-review CI check reads. Only the server (holding the App/PAT credential AND the
+// authenticated builder's server-resolved rank) can set it, so CI can trust it where it
+// must NOT trust a PR-author-controlled signal (a PR title is spoofable). Best-effort:
+// returns false on any failure, in which case the gate-review check sees no attestation
+// and escalates — the SAFE direction (no rank bypass without a real server signal).
+async function setCommitStatus({ sha, state, context, description, targetUrl }, deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token) return false;
+  if (!SAFE_SHA_RE.test(String(sha || ''))) return false;
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) return false;
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  try {
+    const res = await doFetch(`https://api.github.com/repos/${owner}/${repo}/statuses/${sha}`, {
+      method: 'POST',
+      headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        state,
+        context,
+        description: String(description || '').slice(0, 140),
+        ...(targetUrl ? { target_url: targetUrl } : {}),
+      }),
+    });
+    return res.ok;
+  } catch (_) {
+    return false;
+  }
+}
+
+// task 1049 (B — server-side reconcile-on-read): does a publish-status report a
+// fully-landed change — PR MERGED and deploy-prod SUCCEEDED? When true, the
+// publish-status route flips the task confirmed→shipped so a successful publish
+// never strands at confirmed waiting on a human to re-poll (the #1027
+// retrospective). Pure + exported so the route's reconcile trigger is unit-tested.
+function landConfirmed(status) {
+  return !!status && status.merged === true && status.deploy_status === 'success';
+}
+
+// task 1547 — is a landConfirmed status PROVEN to be THIS task's land, and not a
+// reused worktree branch matching an OLDER task's already-merged PR (the BV1.R04/R05
+// false-ship: branch claude/jovial-rosalind-84d6c3 → PR #386 / task 1297, merged,
+// matched again for tasks 1299/1300 whose own push had failed)?
+//
+// The robust proof is the SERVER-pushed tip (claims.published_head_sha, task 1547):
+// it must be an ancestor of main. NOTE claims.head_sha is the claim-TIME base — for a
+// task whose base is already on main (e.g. an R03 base) an ancestry check on it
+// false-positives — so we deliberately key on the published tip, never the base.
+// When no tip was recorded (a legacy row, or a publish in flight across the deploy
+// that introduced the column), fall back to verifying the matched PR references this
+// task id. Returns { proven, reason }. The compare call is the only network hop and
+// is injected-deps-pure for tests.
+async function landProvenForTask({ taskId, publishedSha, status }, deps = {}) {
+  if (publishedSha && SAFE_SHA_RE.test(String(publishedSha))) {
+    const inMain = await isAncestorOfDefaultBranch({ sha: publishedSha }, deps);
+    return inMain
+      ? { proven: true, reason: `published tip ${publishedSha.slice(0, 8)} in main` }
+      : { proven: false, reason: `published tip ${publishedSha.slice(0, 8)} not in main (branch-reuse/stale PR)` };
+  }
+  if (prReferencesTask(status, taskId)) {
+    return { proven: true, reason: `matched PR references task ${taskId} (no published tip recorded)` };
+  }
+  return { proven: false, reason: `no published tip recorded and matched PR does not reference task ${taskId}` };
+}
+
+// task 1313 — proof-of-land that does NOT depend on the PR/branch still existing.
+//
+// WHY. getPublishStatus keys a land on finding the head branch's PR (merged +
+// deploy succeeded). But a merge-commit merge that DELETES the branch afterwards
+// leaves no PR discoverable by `head=owner:branch`, so getPublishStatus returns
+// pr_state:'none' forever and the task strands at 'confirmed' even though the work
+// is live on main. Other strand shapes have no branch at all (a claim with no
+// worktree_name) or a corrupt head_sha. The branch/PR is incidental; the durable
+// truth is "is the work's commit in main's history?" — answer that directly.
+//
+// Uses GitHub's compare API: compare/{base}...{head}. The `status` field is one of
+// ahead | behind | identical | diverged, describing HEAD relative to BASE. When
+// the claim's head_sha is an ancestor of main it has NO commits main lacks, so it
+// is `behind` (or `identical` when it IS main's tip) — both mean "contained in
+// main" ⇒ merged. `ahead`/`diverged` mean head carries commits not on main (e.g. a
+// squash-merge produced a different commit, or it never landed) ⇒ NOT landed here;
+// those still heal via the normal PR path, which getPublishStatus handles.
+//
+// SAFETY. sha MUST be a real commit-sha (SAFE_SHA_RE). The compare endpoint
+// resolves refs, so passing a ref like "HEAD" or a branch name would resolve
+// against the repo and could FALSE-POSITIVE (e.g. "HEAD" → main's tip → identical).
+// We reject anything non-sha-shaped up front. A 404 (unknown commit — never pushed)
+// is a clean "not landed", not an error. Pure w.r.t. injected fetchImpl/repoInfo/
+// token so it unit-tests with no network.
+async function isAncestorOfDefaultBranch({ sha, base = 'main' } = {}, deps = {}) {
+  if (typeof sha !== 'string' || !SAFE_SHA_RE.test(sha)) return false;
+  const token = await resolveToken(deps);
+  if (!token) throw err('PUSH_UNCONFIGURED');
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const res = await doFetch(
+    `https://api.github.com/repos/${owner}/${repo}/compare/${encodeURIComponent(base)}...${encodeURIComponent(sha)}`,
+    { headers: ghHeaders(token) }
+  );
+  if (res.status === 404) return false; // unknown commit → not in main's history
+  if (!res.ok) throw err('STATUS_FETCH_FAILED', { status: res.status });
+  const data = await res.json();
+  return !!data && (data.status === 'behind' || data.status === 'identical');
+}
+
+// ---------------------------------------------------------------------------
+// Gate-surface PR approval from the hall (task 1179, ADR 0058 amendment).
+//
+// The gate-review CI check clears an ESCALATE (hard floor) ONLY on an owner
+// approval. Historically that was a GitHub APPROVED review by the owner on the
+// head sha. This adds a SECOND, trust-equal owner-approval channel the hall can
+// drive: a server-set `gate-owner-approved` commit status — set EXACTLY like the
+// existing `gate-author-trust` status (setCommitStatus), so only the server (which
+// re-checks the caller's Archon rank server-side, ADR 0016) can produce it; a PR
+// author cannot forge it. The gate-review workflow's trust step reads it on the
+// head sha (sha-pinned, so a later commit's head carries no approval — the same
+// red-team #2b protection as the GitHub-review path).
+// ---------------------------------------------------------------------------
+const GATE_OWNER_APPROVED_CONTEXT = 'gate-owner-approved';
+
+// Set the server-attested owner-approval status on `sha`. Thin wrapper over
+// setCommitStatus that pins the context + a provenance description (who approved,
+// via where). Best-effort (returns false on failure → the gate simply stays
+// un-approved, the safe direction). `login` is the approving Archon's handle.
+async function setGateOwnerApproved({ sha, login, targetUrl }, deps = {}) {
+  return setCommitStatus(
+    {
+      sha,
+      state: 'success',
+      context: GATE_OWNER_APPROVED_CONTEXT,
+      description: `owner approval (${login || 'archon'}) via GDS hall`,
+      targetUrl,
+    },
+    deps
+  );
+}
+
+// listOpenPullRequests — one GraphQL read of the open PRs (most-recently-updated
+// first) with the metadata the hall's gate-approval list needs: number, title,
+// url, head ref + head sha, author login, body (for "task NNNN" extraction), and
+// the head commit's check rollup (so the route can read the live `gate-review`
+// check conclusion — the authoritative "is this awaiting approval" signal, rather
+// than re-deriving it). Pure w.r.t. injected fetchImpl/repoInfo/token.
+async function listOpenPullRequests(deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token) throw err('PUSH_UNCONFIGURED');
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const first = Math.min(Math.max(Number(deps.first) || 40, 1), 100);
+  const query = `query($owner:String!,$repo:String!,$first:Int!){
+    repository(owner:$owner,name:$repo){
+      pullRequests(states:OPEN, first:$first, orderBy:{field:UPDATED_AT,direction:DESC}){
+        nodes{
+          number title url isDraft headRefName bodyText
+          author{ login }
+          reviewDecision
+          commits(last:1){ nodes{ commit{ oid
+            statusCheckRollup{ state contexts(first:50){ nodes{
+              __typename
+              ... on CheckRun{ name conclusion status detailsUrl }
+              ... on StatusContext{ context state targetUrl }
+            }}}
+          }}}
+        }
+      }
+    }
+  }`;
+  const res = await doFetch('https://api.github.com/graphql', {
+    method: 'POST',
+    headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, variables: { owner, repo, first } }),
+  });
+  if (!res.ok) throw err('STATUS_FETCH_FAILED', { status: res.status });
+  const out = await res.json();
+  // Tolerate a partial FORBIDDEN (App lacks Checks:read → statusCheckRollup.contexts
+  // nulled): the PR list itself is still usable, so the approve path keeps working; the
+  // per-PR `checks` array just comes back empty.
+  const { repository, partialErrors } = graphqlRepository(out);
+  const nodes = ((repository.pullRequests || {}).nodes || []);
+  const result = nodes.map((n) => {
+    const commit = (n.commits && n.commits.nodes && n.commits.nodes[0] && n.commits.nodes[0].commit) || {};
+    const rollup = commit.statusCheckRollup || null;
+    // .filter(Boolean): a partial FORBIDDEN (App lacks Checks:read) nulls the individual
+    // CheckRun ELEMENTS inside contexts.nodes (the array survives with null holes); the
+    // readable StatusContexts — gate-author-trust / gate-owner-approved — remain.
+    const checks = ((rollup && rollup.contexts && rollup.contexts.nodes) || []).filter(Boolean).map((c) =>
+      c.__typename === 'CheckRun'
+        ? { name: c.name, conclusion: c.conclusion, status: c.status, url: c.detailsUrl || null }
+        : { name: c.context, conclusion: c.state, status: 'COMPLETED', url: c.targetUrl || null }
+    );
+    return {
+      number: n.number,
+      title: n.title || '',
+      url: n.url,
+      is_draft: !!n.isDraft,
+      head_ref: n.headRefName || null,
+      head_sha: commit.oid || null,
+      author: (n.author && n.author.login) || null,
+      body: n.bodyText || '',
+      review_decision: n.reviewDecision || null,
+      rollup_state: (rollup && rollup.state) || null,
+      checks,
+    };
+  });
+  // Signal reduced fidelity (e.g. checks unreadable → App lacks Checks:read) so a caller
+  // can say so instead of silently presenting an empty check rollup as "all clear".
+  // Non-enumerable: the array is JSON-serialized directly by the GET route and this must
+  // not leak into that payload — the route reads it explicitly.
+  if (partialErrors.length) {
+    Object.defineProperty(result, 'partialErrors', { value: partialErrors, enumerable: false });
+  }
+  return result;
+}
+
+// getPullRequestFiles — the changed paths of a PR, mapped to the shape
+// classifyChanges() consumes ({ path, mode, deleted }). The REST files API does
+// not return the git file mode, so we default to a regular-file mode; the symlink
+// pre-flight reject is a CI-authoritative edge that does not affect this read-only
+// "why did it escalate" display. Caps at 300 files (3 pages) — far beyond any real
+// gate PR; a larger PR is itself an escalate-by-size in CI.
+async function getPullRequestFiles({ number }, deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token) throw err('PUSH_UNCONFIGURED');
+  if (!Number.isInteger(number) || number < 1) throw err('BAD_PR');
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const api = `https://api.github.com/repos/${owner}/${repo}`;
+  const files = [];
+  for (let page = 1; page <= 3; page += 1) {
+    const res = await doFetch(`${api}/pulls/${number}/files?per_page=100&page=${page}`, {
+      headers: ghHeaders(token),
+    });
+    if (!res.ok) throw err('STATUS_FETCH_FAILED', { status: res.status });
+    const batch = await res.json();
+    if (!Array.isArray(batch) || !batch.length) break;
+    for (const f of batch) {
+      files.push({
+        path: f.filename,
+        mode: '100644',
+        deleted: f.status === 'removed',
+        status: f.status,
+        additions: f.additions || 0,
+        deletions: f.deletions || 0,
+      });
+    }
+    if (batch.length < 100) break;
+  }
+  return files;
+}
+
+// How long to wait between the close PATCH and the reopen PATCH (task 1241). See the
+// recheckPullRequest header for WHY this delay exists; overridable via deps.reopenDelayMs
+// so tests run instantly (and an operator can tune it without a code change).
+const RECHECK_REOPEN_DELAY_MS = 4000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// recheckPullRequest — re-trigger the gate-review check after an owner approval was
+// recorded. WHY close+reopen: setting a commit status does NOT fire a `pull_request`
+// event, so the (red) gate-review check would not re-evaluate the new approval and
+// the required check would stay failing. Re-running the check via the Actions API
+// would need an `actions:write` App permission the publish App is not granted;
+// closing then reopening the PR fires `pull_request: reopened` (a default activity
+// type for the gate-review trigger) using the `pull_requests:write` the App already
+// holds — zero new permission, and the re-run carries the real PR context so the
+// fresh `gate-review` check posts on the correct head sha. Re-arms auto-merge after
+// reopen (closing clears it). Best-effort; the publish reconciler's mergeIfGreen
+// sweep (task 1162) is the backstop if auto-merge does not re-fire.
+//
+// WHY THE DELAY (task 1241). When the close + reopen PATCHes land ~1s apart, GitHub
+// COALESCES them into no net state change and dispatches NO `pull_request: reopened`
+// event — so the gate-review run never re-fires and the required check stays red after
+// an owner Approve (observed on PR #167: close 22:36:39Z, reopen 22:36:40Z by the App
+// bot, zero gate-review runs followed; a later manual rerun cleared it green, proving
+// only the auto-re-trigger was broken). Sleeping a few seconds between the two PATCHes
+// makes GitHub register two DISTINCT state transitions, so the reopen fires a real
+// `reopened` event carrying full PR context. Stays inside the App's existing
+// `pull_requests:write` — no new permission (the deterministic Actions rerun API would
+// need `actions:write`, deliberately not granted; see blocker 37).
+async function recheckPullRequest({ number }, deps = {}) {
+  const token = await resolveToken(deps);
+  if (!token) throw err('PUSH_UNCONFIGURED');
+  if (!Number.isInteger(number) || number < 1) throw err('BAD_PR');
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) throw err('NO_REPO_INFO');
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const reopenDelayMs = Number.isFinite(deps.reopenDelayMs) ? deps.reopenDelayMs : RECHECK_REOPEN_DELAY_MS;
+  const api = `https://api.github.com/repos/${owner}/${repo}`;
+  const patchState = async (state) => {
+    const res = await doFetch(`${api}/pulls/${number}`, {
+      method: 'PATCH',
+      headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ state }),
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => '');
+      throw err('PR_PATCH_FAILED', { status: res.status, detail: detail.slice(0, 200) });
+    }
+    return res.json();
+  };
+  await patchState('closed');
+  // Let GitHub register the close as a distinct state transition before reopening, so
+  // the reopen actually dispatches a `pull_request: reopened` event (task 1241).
+  if (reopenDelayMs > 0) await sleep(reopenDelayMs);
+  const reopened = await patchState('open');
+  let autoMerge = false;
+  try {
+    if (reopened && reopened.node_id) autoMerge = await enableAutoMerge({ nodeId: reopened.node_id }, deps);
+  } catch (_) {
+    /* auto-merge re-arm is best-effort; mergeIfGreen sweep backstops it */
+  }
+  return { reopened: true, auto_merge: autoMerge, node_id: (reopened && reopened.node_id) || null };
+}
+
+module.exports = {
+  isConfigured,
+  appConfigured,
+  isSafeBranch,
+  pushBundle,
+  openOrFindPullRequest,
+  enableAutoMerge,
+  getPublishStatus,
+  getMergeState,
+  mergeIfGreen,
+  setCommitStatus,
+  setGateOwnerApproved,
+  listOpenPullRequests,
+  getPullRequestFiles,
+  recheckPullRequest,
+  GATE_OWNER_APPROVED_CONTEXT,
+  landConfirmed,
+  landProvenForTask,
+  prReferencesTask,
+  scrubCredential,
+  isAncestorOfDefaultBranch,
+  resolveToken,
+  getInstallationToken,
+  // exported for unit tests
+  buildAuthUrl,
+  mintAppJwt,
+  mergeBlockReason,
+  _resetAppTokenCacheForTests,
+  SAFE_BRANCH_RE,
+};