@open-everywhere/core 0.1.0

package/agent/scm/broker.ts

@@ -0,0 +1,130 @@
+// The firewall-brokered git READ credential — the prod-hardening path from
+// docs/capabilities/source-control.md. Mints ONE installation token per owner, scoped
+// to the UNION of the session's granted repo set (not just the one repo being checked
+// out), and turns it into firewall rules that checkout_repo merges into the standing
+// egress policy at SCM-call time. The token is injected as a header TRANSFORM at the
+// sandbox firewall (Vercel's `setNetworkPolicy`) — it never rides in the git command or
+// touches the clone's config. Header shape mirrors Eve's own GitHub-channel checkout
+// broker (buildBrokerNetworkPolicy in eve/dist/src/public/channels/github/checkout.js)
+// exactly, so this is the SAME auth form GitHub's own actions/checkout and Eve's native
+// channel use, not a bespoke one: `Authorization: Basic base64("x-access-token:<token>")`.
+//
+// One token can't span installations (each GitHub App installation is owner-scoped), so
+// "union-scoped" means union WITHIN each owner; a session whose granted repos span
+// multiple owners gets one rule per owner, narrowed by an `/<owner>/` path prefix so
+// each owner's token only ever rides toward that owner's own repos.
+//
+// WRITE stays out of this plane entirely (see tools/open_pull_request.ts / stagePushCommand):
+// a standing firewall header is reachable by ANY concurrent sandbox code, not just the
+// tool that minted it, so only the read-only token is ever installed here.
+
+import type { SandboxNetworkPolicy } from "eve/sandbox";
+import { GIT_BROKER_HOSTS, type EgressRule } from "../access/egress.js";
+import type { GitHubApp } from "./app.js";
+import { READ_PERMISSIONS } from "./mint.js";
+
+/** Hosts the git read-broker authenticates — mirrors Eve's own broker's pair exactly. DECLARED in
+ *  access/reserved-hosts.ts, a module that imports nothing, and re-exported here (through
+ *  access/egress.ts) because FOUR rungs RESERVE the set: the access lint and the resolve-time refusal
+ *  against bundle connections (OPE-1684), and the browser host declaration's own lint and the policy
+ *  compile against a declared browse target (OPE-1708). See that declaration for why one list has to
+ *  answer all four. */
+export { GIT_BROKER_HOSTS } from "../access/egress.js";
+
+/** GitHub's cap on repositories per installation-token mint. */
+const MAX_MINT_REPOS = 500;
+
+/** `Authorization: Basic base64("x-access-token:<token>")` — Eve's own broker header shape. */
+export function brokerAuthHeader(token: string): Record<string, string> {
+  return { Authorization: `Basic ${Buffer.from(`x-access-token:${token}`, "utf-8").toString("base64")}` };
+}
+
+export interface GitReadBrokerResult {
+  /** owner → the firewall rule carrying that owner's scoped read token. */
+  readonly rulesByOwner: ReadonlyMap<string, EgressRule>;
+  /** Granted repos whose owner has no linked installation (same shape as tokensForRepos). */
+  readonly ungranted: readonly string[];
+}
+
+/**
+ * Mint the union-scoped READ token(s) for `repos` (a session's full granted set — see
+ * access.repos) and build the per-owner firewall rule for each. GitHub rejects a mint
+ * over MAX_MINT_REPOS repositories in one call; the caller asked for firewall-visible
+ * enforcement, so silently slicing the list would quietly narrow what's actually
+ * reachable instead of surfacing the misconfiguration — this throws instead, naming the
+ * offending owner and count.
+ */
+export async function mintGitReadBroker(app: GitHubApp, repos: readonly string[]): Promise<GitReadBrokerResult> {
+  const perOwnerCount = new Map<string, number>();
+  for (const ref of repos) {
+    const slash = ref.indexOf("/");
+    if (slash <= 0) continue; // malformed — tokensForRepos below drops it the same way
+    const owner = ref.slice(0, slash);
+    perOwnerCount.set(owner, (perOwnerCount.get(owner) ?? 0) + 1);
+  }
+  for (const [owner, count] of perOwnerCount) {
+    if (count > MAX_MINT_REPOS) {
+      throw new Error(
+        `owner "${owner}" has ${count} repos granted to this session — GitHub caps a single installation ` +
+          `token mint at ${MAX_MINT_REPOS} repositories. Narrow the grant (split it across more bundles/scopes) ` +
+          `rather than widen this cap.`,
+      );
+    }
+  }
+
+  const { tokens, ungranted } = await app.tokensForRepos(repos, READ_PERMISSIONS);
+  const rulesByOwner = new Map<string, EgressRule>();
+  for (const [owner, tok] of tokens) {
+    rulesByOwner.set(owner, {
+      match: { path: { startsWith: `/${owner}/` } },
+      transform: [{ headers: brokerAuthHeader(tok.token) }],
+    });
+  }
+  return { rulesByOwner, ungranted };
+}
+
+/**
+ * Merge the git read-broker's owner-scoped rules into a standing compiled policy.
+ * github.com and codeload.github.com are REPLACED wholesale (not appended) — the base
+ * compiler emits at most a BARE allow for github.com (egress.ts's repos>0 fallback, for
+ * the unenforced path), and a plain merge would leave that sitting alongside these as an
+ * unauthenticated duplicate. Empty `rulesByOwner` (no granted repos, or no owner had a
+ * usable installation) leaves the base policy untouched, including `"deny-all"`.
+ */
+export function mergeGitReadBroker(
+  base: SandboxNetworkPolicy,
+  rulesByOwner: ReadonlyMap<string, EgressRule>,
+): SandboxNetworkPolicy {
+  if (rulesByOwner.size === 0) return base;
+  const rules = [...rulesByOwner.values()];
+  const allow: Record<string, EgressRule[]> = typeof base === "string" ? {} : { ...(base.allow as Record<string, EgressRule[]>) };
+  for (const host of GIT_BROKER_HOSTS) allow[host] = rules;
+  return { allow };
+}
+
+/**
+ * Lift the read-broker's credential stamp off ONE host: return a copy of `policy` with
+ * `host`'s rules replaced by a BARE allow (allowed, no transform, no match). This is the
+ * #104 fix seam. checkout_repo installs the READ installation token as a firewall header
+ * TRANSFORM over all github.com traffic (mintGitReadBroker above); the firewall SETS
+ * (overrides) the request's Authorization header, so a gated staging push — which injects
+ * the WRITE token inline via `git -c http.extraheader` — arrives read-authenticated and
+ * 403s ("Write access to repository not granted"). Around that single push
+ * (tools/open_pull_request.ts) the caller swaps github.com to this bare allow so only git's
+ * inline write token rides, then restores the brokered policy immediately.
+ *
+ * Everything else is preserved byte-for-byte — every other host, and codeload's own broker
+ * rule — so the swapped policy stays complete (setNetworkPolicy replaces the WHOLE policy)
+ * and the restore is exact. A string policy ("deny-all"/"allow-all") is returned unchanged:
+ * there is no per-host rule to lift, and manufacturing an allow map would WIDEN a deny-all
+ * (fail-closed). Lifting a host's transform is strictly NARROWING — it can only drop an
+ * injected credential, never grant reach the base policy didn't already allow.
+ */
+export function withBareAllowHost(policy: SandboxNetworkPolicy, host: string): SandboxNetworkPolicy {
+  if (typeof policy === "string") return policy;
+  const allow: Record<string, EgressRule[]> = { ...(policy.allow as Record<string, EgressRule[]>) };
+  allow[host] = [];
+  // Spread the source policy so any non-`allow` field (e.g. a future `subnets`) survives the
+  // swap/restore round-trip — this helper must only ever touch the one host's rules.
+  return { ...policy, allow };
+}

package/agent/scm/capability-fit.ts

@@ -0,0 +1,164 @@
+// THE ASK-TIME CHECK (OPE-1024) — "can the App installation honour this capability expansion?"
+//
+// 🔴 ASK TIME IS THE ONLY IMPLEMENTATION POINT (Tommy, 2026-08-23). There is deliberately NO
+// deploy-chain preflight rung and NO boot-time drift check. The always-on backstop for drift is
+// GitHub itself: a mint that asks past the installation is refused, and the refusal is audited
+// (`github.token_mint_failed`). This module is the UX half — it turns "the mint will 403 later"
+// into "here is the config line, and here is the owner-approval step you will need first".
+//
+// 🔴 IT IS NOT AN INTROSPECTION VERB, and that shapes the API. There is no "enumerate what this
+// credential can do" entry point: `capabilityInstallationFit` answers only about the closed set of
+// capability names we implement, and only for a caller that already named a concrete config change.
+// The risk of the answer itself is accepted as low — an installation's grants are org-internal
+// metadata, not a secret — but knowing what is grantable grants nothing: the config PR, the merge
+// and the mint body remain the enforcement.
+//
+// FAIL-SOFT, ON PURPOSE. This check gates nothing. A vendor that cannot report its granted families
+// (the contract models grant-reporting as OPTIONAL) degrades to "unreported", never to a refusal.
+// A hard fail here would convert a UX affordance into an outage the moment GitHub's App API blips.
+
+import { REPO_CAPABILITIES, type RepoCapability } from "../access/repo-capabilities.js";
+import { REPO_CAPABILITY_PERMISSIONS } from "./mint.js";
+
+/** One family a named capability needs that the installation does not grant at the needed grade. */
+export interface CapabilityShortfall {
+  readonly capability: RepoCapability;
+  /** The GitHub permission family, in GitHub's own spelling (what the owner sees on the consent screen). */
+  readonly family: string;
+  /** The grade the mint will ask for. */
+  readonly need: string;
+  /** What the installation grants today for that family — absent when it grants none. */
+  readonly granted?: string;
+}
+
+export interface CapabilityFit {
+  /** True when every named capability is supported, or when the installation did not report. */
+  readonly ok: boolean;
+  /** False when the installation could not report its granted families — `ok` is then not a claim. */
+  readonly reported: boolean;
+  readonly missing: readonly CapabilityShortfall[];
+}
+
+/** Is `granted` at least as strong as `need`? "write" covers "read"; absent covers nothing. */
+function covers(granted: string | undefined, need: string): boolean {
+  if (granted === undefined) return false;
+  return granted === "write" || granted === need;
+}
+
+/**
+ * PURE. Join the named capability sets to the installation's reported permission families and
+ * report every shortfall. `granted === undefined` means the installation did not report: the fit
+ * is `reported: false` with no shortfalls, which reads as "cannot tell", never as "supported".
+ *
+ * An unknown capability name is skipped rather than thrown on: config load already refuses one
+ * (`assertBundlesValid`), and this path must stay total so a stale name can never take down the
+ * report that would explain it.
+ */
+export function capabilityInstallationFit(
+  capabilities: readonly RepoCapability[],
+  granted: Readonly<Record<string, string>> | undefined,
+): CapabilityFit {
+  if (granted === undefined) return { ok: true, reported: false, missing: [] };
+  const missing: CapabilityShortfall[] = [];
+  for (const capability of capabilities) {
+    const families = REPO_CAPABILITY_PERMISSIONS[capability];
+    if (!families) continue;
+    for (const [family, need] of Object.entries(families)) {
+      const has = Object.hasOwn(granted, family) ? granted[family] : undefined;
+      if (!covers(has, need)) missing.push({ capability, family, need, ...(has === undefined ? {} : { granted: has }) });
+    }
+  }
+  return { ok: missing.length === 0, reported: true, missing };
+}
+
+/**
+ * Where the installation OWNER accepts an App permission update. GitHub routes a permission change
+ * to the installing account for approval; an org installation and a user installation live at
+ * different settings paths, and we cannot tell which an owner is from the owner login alone — so
+ * both are named rather than one guessed.
+ */
+export function installationApprovalUrls(owner: string, installationId: string): readonly string[] {
+  return [
+    `https://github.com/organizations/${owner}/settings/installations/${installationId}`,
+    `https://github.com/settings/installations/${installationId}`,
+  ];
+}
+
+/** The owner half of an "owner/name" repo ref, or "" when the ref is malformed. */
+export function repoOwner(repo: string): string {
+  const slash = repo.indexOf("/");
+  return slash > 0 ? repo.slice(0, slash) : "";
+}
+
+/** What one repo's capability picture looks like — every implemented set, with its status here. */
+export interface RepoCapabilityRow {
+  readonly repo: string;
+  readonly capability: RepoCapability;
+  /** True when a binding in this scope already opted the repo into the set. */
+  readonly declared: boolean;
+  /** The installation fit for JUST this capability. */
+  readonly fit: CapabilityFit;
+}
+
+/**
+ * PURE. Join this scope's repo grants to the implemented capability sets and to each owner's
+ * reported installation families. One row per (repo, capability) — including the sets NOT taken,
+ * which is the half that answers "what would it take to let this domain do X?".
+ */
+export function repoCapabilityRows(
+  repos: readonly string[],
+  declared: Readonly<Record<string, readonly RepoCapability[]>>,
+  grantedByOwner: Readonly<Record<string, Readonly<Record<string, string>> | undefined>>,
+): readonly RepoCapabilityRow[] {
+  const rows: RepoCapabilityRow[] = [];
+  for (const repo of [...repos].sort()) {
+    const owner = repoOwner(repo);
+    const granted = Object.hasOwn(grantedByOwner, owner) ? grantedByOwner[owner] : undefined;
+    const here = new Set(declared[repo] ?? []);
+    for (const capability of Object.keys(REPO_CAPABILITIES).sort() as RepoCapability[]) {
+      rows.push({ repo, capability, declared: here.has(capability), fit: capabilityInstallationFit([capability], granted) });
+    }
+  }
+  return rows;
+}
+
+/**
+ * The report section, as lines — the ask-time answer for a whole domain's repo grants. Each line
+ * names the capability, whether this scope already has it, the exact config edit, and whether the
+ * App installation can honour it today.
+ */
+export function renderRepoCapabilityRows(
+  rows: readonly RepoCapabilityRow[],
+  installationIdByOwner: Readonly<Record<string, string | undefined>> = {},
+): string[] {
+  if (rows.length === 0) return ["No GitHub repos are granted to this domain, so there is nothing to expand."];
+  const lines: string[] = [];
+  let repo = "";
+  for (const row of rows) {
+    if (row.repo !== repo) {
+      repo = row.repo;
+      lines.push(`${repo}:`);
+    }
+    const spec = REPO_CAPABILITIES[row.capability];
+    const state = row.declared ? "declared" : "not declared";
+    const fit = !row.fit.reported
+      ? "installation not reported"
+      : row.fit.ok
+        ? "the installation grants it"
+        : `the installation does NOT grant ${row.fit.missing.map((m) => `${m.family}:${m.need}`).join(", ")}`;
+    lines.push(`  ${row.capability} — ${state}; ${fit}. ${spec?.summary ?? ""}`);
+    if (!row.declared) {
+      lines.push(`    to add: repos: [{ repo: "${row.repo}", capabilities: ["${row.capability}"] }] in agent/access/bundles.ts`);
+    }
+    if (row.fit.reported && !row.fit.ok) {
+      const owner = repoOwner(row.repo);
+      const id = installationIdByOwner[owner];
+      lines.push(
+        `    first: update the GitHub App's repository permissions, then the installation owner (${owner}) approves the update at ` +
+          (id ? installationApprovalUrls(owner, id).join(" or ") : "the installation's settings page") +
+          ".",
+      );
+    }
+  }
+  return lines;
+}

package/agent/scm/config-repo-token.ts

@@ -0,0 +1,44 @@
+// THE ONE MINTED WRITE TOKEN FOR THE CONFIG-REPO BOT-PR FLOWS (OPE-1823).
+//
+// Five flows open a bot-PR against the DEPLOYMENT'S OWN CONFIG REPO, and each held its own copy of
+// the eight-line mint below: approvals/access-request.ts, approvals/agent-create.ts,
+// approvals/webhook-declare.ts, credentials/config-pr-github.ts and identity/groups-delivery.ts.
+// The copies had not drifted. OPE-1794 is what happens when copies of this body do drift, so the
+// copies are gone and the five mint here.
+//
+// 🔴 CAPABILITIES ARE `[]`, AND THAT IS A PROPERTY, NOT AN OMISSION.
+//
+// A repo capability (access/repo-capabilities.ts) is declared BY A BINDING, on a repo that binding
+// grants, and is read as `access.repoCapabilities[repo]` from a resolved `EffectiveAccess`. None of
+// the five can read one, and none should:
+//
+//  1. THE REPO IS NOT NAMED BY A BINDING. It is `AccessRequestsConfig.configRepo`, an operator
+//     setting (`OE_ACCESS_CONFIG_REPO`), so there is no `access.repoCapabilities[repo]` entry to
+//     read for it. A `repoAllowed(repo, access.repos)` check would also be the WRONG fence: it
+//     would refuse every requester whose own scope does not grant the config repo, which is the
+//     normal case and the exact case these flows exist to serve. Note the two sets are not
+//     disjoint — this deployment DOES grant its own repo, in `agent/access/bundles.ts`'s `coding`
+//     bundle — which is a further reason the requester's bundle set is not the fence here. The
+//     fence these flows have is the fail-closed config gate plus the human merge.
+//  2. THERE IS NO ACCESS TO RESOLVE FROM. `ActionKind.execute(args, decidedBy)` takes no context by
+//     contract — it sees only what was frozen at propose time — `deliverGroupsOverlay(plan, deps)`
+//     takes none, and `ConfigPrProvider.resolveWriteToken(repo)` takes only the repo.
+//     `resolveAccessFor` needs a `BindableContext`; none of the five holds one.
+//  3. WIDENING HERE WOULD RUN THE WRONG WAY. The config repo holds the grants. A token minted for
+//     it on a MEMBER'S request, widened by that member's own binding, would let the binding decide
+//     what the credential that edits the grants may do. The narrow default job set is the point.
+//
+// What the five write is a single overlay file each — the grants, agents, hooks, credential
+// bindings or person-group module — and its bytes are always TypeScript emitted by a deterministic
+// codemod. Each path is an operator setting with a code default (`OE_ACCESS_GRANTS_PATH`,
+// `agentsPath`, `OE_WEBHOOK_HOOKS_PATH`, `OE_CREDENTIAL_BINDINGS_PATH`, `groupsPath`); nothing
+// validates one against `.github/workflows/**`, and no default sits there. So none of the five
+// needs the `workflows` capability that OPE-1794 was about. An operator who pointed one of those
+// settings under `.github/workflows/**` would fail closed at GitHub's own push refusal.
+
+import { resolvePrWriteToken } from "./write-token.js";
+
+/** A minted WRITE installation token for the deployment's config repo, or the PAT fallback. */
+export async function resolveConfigRepoWriteToken(repo: string): Promise<string> {
+  return resolvePrWriteToken(repo, [], "the config repo");
+}

package/agent/scm/config.ts

@@ -0,0 +1,37 @@
+// Load the org-level GitHub App config from the environment. The plane is OPTIONAL:
+// returns null when not configured (no app id / key / slug), so the agent simply has no
+// source-control capability rather than erroring. Secrets are read from env (secretRef);
+// the private key is never inlined in repo config.
+
+import type { GitHubAppConfig } from "./types.js";
+
+export function loadGitHubAppConfig(env: NodeJS.ProcessEnv = process.env): GitHubAppConfig | null {
+  const appId = env.OE_GITHUB_APP_ID;
+  const privateKeyPem = env.OE_GITHUB_APP_PRIVATE_KEY;
+  const appSlug = env.OE_GITHUB_APP_SLUG;
+  if (!appId || !privateKeyPem || !appSlug) return null;
+
+  // owner → installation id. JSON map covers multi-org; a single org can also use the
+  // OE_GITHUB_OWNER + OE_GITHUB_INSTALLATION_ID pair.
+  let installations: Record<string, string> = {};
+  if (env.OE_GITHUB_INSTALLATIONS) {
+    try {
+      const parsed = JSON.parse(env.OE_GITHUB_INSTALLATIONS) as Record<string, string>;
+      if (parsed && typeof parsed === "object") installations = parsed;
+    } catch {
+      // ignore malformed map; the single-owner pair below may still apply
+    }
+  }
+  if (env.OE_GITHUB_OWNER && env.OE_GITHUB_INSTALLATION_ID) {
+    installations[env.OE_GITHUB_OWNER] = env.OE_GITHUB_INSTALLATION_ID;
+  }
+
+  return {
+    appId,
+    clientId: env.OE_GITHUB_APP_CLIENT_ID,
+    privateKeyPem,
+    appSlug,
+    botUserId: env.OE_GITHUB_BOT_USER_ID,
+    installations,
+  };
+}

package/agent/scm/contents.ts

@@ -0,0 +1,162 @@
+// A thin GitHub Contents API client — read/write/list/delete files in a repo subtree
+// with a scoped installation token. Used by the github memory backing
+// (packages/providers/github/agent/memory/memory.ts, reached through the adapter barrel)
+// so a domain's memory can durably live in a git repo (the second consumer of the
+// GitHub App plane after code checkout — docs/capabilities/memory.md "Git backing").
+//
+// Per-file Contents API (vs the lower-level Git Data API): a memory tier is a handful
+// of small markdown files, so one request per file is fine and keeps this — and its
+// test fake — simple. `fetchFn` is injectable for deterministic, offline tests.
+//
+// 429/`Retry-After` BACKOFF (OPE-1253): every call goes through `withRetryAfterLoose`
+// (channels/rate-limit-retry.ts) — see that primitive's doc comment for why `HttpFetch` is not
+// widened with a `headers` field of its own (it also types five modules this ticket does not touch).
+
+import type { Selector } from "../memory/selection.js";
+import { withRetryAfterLoose, type RetryPolicy } from "../channels/rate-limit-retry.js";
+
+const API = "https://api.github.com";
+
+/** Minimal fetch shape (the global fetch satisfies it); body optional so GETs are clean. */
+export type HttpFetch = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body?: string },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string>; json(): Promise<unknown> }>;
+
+export interface CommitId {
+  readonly name: string;
+  readonly email: string;
+}
+
+interface ContentEntry {
+  type: string;
+  path: string;
+  name: string;
+  sha: string;
+}
+interface FileResponse {
+  content?: string;
+  encoding?: string;
+  sha: string;
+}
+interface WriteResponse {
+  commit?: { sha?: string };
+  content?: { sha?: string };
+}
+
+export class GitHubContents {
+  constructor(
+    private readonly fetchFn: HttpFetch = globalThis.fetch as unknown as HttpFetch,
+    private readonly apiBase: string = API,
+    /** Tightens or drives the 429 backoff (OPE-1253) — a test injects a stub `sleep`; omitted takes
+     *  the shared defaults from `channels/rate-limit-retry.ts`. */
+    private readonly retry?: RetryPolicy,
+  ) {}
+
+  private headers(token: string): Record<string, string> {
+    return {
+      authorization: `Bearer ${token}`,
+      accept: "application/vnd.github+json",
+      "x-github-api-version": "2022-11-28",
+      "content-type": "application/json",
+    };
+  }
+
+  private url(repo: string, path: string): string {
+    // Encode each segment but keep the slashes that delimit the repo path.
+    const encoded = path.split("/").map(encodeURIComponent).join("/");
+    return `${this.apiBase}/repos/${repo}/contents/${encoded}`;
+  }
+
+  /**
+   * List files under `dir` as relPath (to `dir`) → blob sha. Absent dir → {}.
+   * `selector` (memory/selection.ts) decides which directories to descend into and which
+   * files to take, relative to `dir` — the silo root. The common cases: take everything
+   * (default "recurse"), top-level files only (default "include"), or a curated subset
+   * (per-node rules). Segments are directory/file names relative to `dir`.
+   */
+  async listFiles(repo: string, dir: string, branch: string, token: string, selector: Selector): Promise<Record<string, string>> {
+    const out: Record<string, string> = {};
+    const walk = async (path: string, segs: string[]): Promise<void> => {
+      const res = await withRetryAfterLoose(
+        () => this.fetchFn(`${this.url(repo, path)}?ref=${encodeURIComponent(branch)}`, { method: "GET", headers: this.headers(token) }),
+        { ...this.retry, surface: "github", operation: "repos.contents.list" },
+      );
+      if (res.status === 404) return; // dir/file doesn't exist
+      if (!res.ok) throw new Error(`github contents list ${repo}/${path}: ${res.status} ${await res.text()}`);
+      const body = (await res.json()) as ContentEntry[] | ContentEntry;
+      const entries = Array.isArray(body) ? body : [body];
+      for (const e of entries) {
+        if (e.type === "dir") {
+          if (selector.descends([...segs, e.name])) await walk(e.path, [...segs, e.name]);
+        } else if (e.type === "file" && selector.includesLeaf(segs, e.name)) {
+          out[e.path.slice(dir.length + 1)] = e.sha;
+        }
+      }
+    };
+    await walk(dir, []);
+    return out;
+  }
+
+  /** Read one file's text + sha, or null if it doesn't exist. */
+  async getFile(repo: string, path: string, branch: string, token: string): Promise<{ content: string; sha: string } | null> {
+    const res = await withRetryAfterLoose(
+      () => this.fetchFn(`${this.url(repo, path)}?ref=${encodeURIComponent(branch)}`, { method: "GET", headers: this.headers(token) }),
+      { ...this.retry, surface: "github", operation: "repos.contents.get" },
+    );
+    if (res.status === 404) return null;
+    if (!res.ok) throw new Error(`github get ${repo}/${path}: ${res.status} ${await res.text()}`);
+    const body = (await res.json()) as FileResponse;
+    const content = body.encoding === "base64" && body.content ? Buffer.from(body.content, "base64").toString("utf-8") : "";
+    return { content, sha: body.sha };
+  }
+
+  /** Create or update one file; returns the new commit sha. `sha` is required to UPDATE. */
+  async putFile(
+    repo: string,
+    path: string,
+    content: string,
+    message: string,
+    branch: string,
+    token: string,
+    committer: CommitId,
+    sha?: string,
+  ): Promise<string | null> {
+    const res = await withRetryAfterLoose(
+      () =>
+        this.fetchFn(this.url(repo, path), {
+          method: "PUT",
+          headers: this.headers(token),
+          body: JSON.stringify({
+            message,
+            content: Buffer.from(content, "utf-8").toString("base64"),
+            branch,
+            committer,
+            ...(sha ? { sha } : {}),
+          }),
+        }),
+      { ...this.retry, surface: "github", operation: "repos.contents.put" },
+    );
+    if (!res.ok) throw new Error(`github put ${repo}/${path}: ${res.status} ${await res.text()}`);
+    const body = (await res.json()) as WriteResponse;
+    return body.commit?.sha ?? body.content?.sha ?? null;
+  }
+
+  /**
+   * Delete one file (requires its current sha). Idempotent: a 404 returns `null` (the
+   * "already gone" case, not an error). Returns the new commit sha otherwise — widened
+   * (OPE-64) from a bare `void` so the github memory backing's `deleteFile` can report
+   * an opaque version token, matching `putFile`'s contract. This client has exactly one
+   * caller (the github bundle's memory backing), so widening it isn't a source-control-plane-wide change.
+   */
+  async deleteFile(repo: string, path: string, sha: string, message: string, branch: string, token: string, committer: CommitId): Promise<string | null> {
+    const res = await withRetryAfterLoose(
+      () => this.fetchFn(this.url(repo, path), { method: "DELETE", headers: this.headers(token), body: JSON.stringify({ message, sha, branch, committer }) }),
+      { ...this.retry, surface: "github", operation: "repos.contents.delete" },
+    );
+    if (res.status === 404) return null;
+    if (!res.ok) throw new Error(`github delete ${repo}/${path}: ${res.status} ${await res.text()}`);
+    const body = (await res.json()) as WriteResponse;
+    return body.commit?.sha ?? null;
+  }
+}