Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
30.2 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Master-push reuse of an identical-tree full-suite run (P2, docs/ci-event-parity.md#master-push-reuse).
 *
 *   bun scripts/ci-reuse.ts --workflow test|e2e --sha <push sha> --repo <owner/name>
 *        --output <GITHUB_OUTPUT> [--summary <GITHUB_STEP_SUMMARY>] [--record <reuse.json>]
 *
 * A push to master is a merge commit M or a one-parent (squashed) commit S. Its
 * run may reuse the full run of the same workflow that already ran the complete
 * full suite on its tree: the workflow_dispatch on the PR head branch
 * (full-ci.yml, or a hand-run `gh workflow run`) or an earlier push run.
 * Pull-request runs are the cheap tier and never candidates. Fail-closed:
 * reuse=true only when
 *   (a) the push is a merge commit (two parents) or a one-parent commit, and
 *       its tree equals the candidate's recorded tree;
 *   (b) the candidate is a same-repository workflow_dispatch or push run
 *       whose LATEST attempt completed with conclusion success;
 *   (c) its full-suite job (`full-suite` / `e2e-full-suite`, by name, exactly
 *       one) concluded success in that latest attempt;
 *   (d) its tested-tree artifact (`full-suite-tree` / `e2e-full-suite-tree`,
 *       tree.json) is readable, has profile full, names this run, attempt,
 *       event, head and workflow, and its tree equals both M's tree and the
 *       tree of the run's head commit.
 * A diagnostic dispatch (test.yml native_only, race_hunt, stress_*; e2e.yml
 * full_corpus, order_hunt) skips the full-suite job, so (c) rejects it.
 * Candidates on head M^2 (the merged PR head) come first, newest first; then
 * recent successful dispatch and push runs whose head tree equals M's tree. S
 * has no merged head, so its tree alone decides: the heads with S's tree are
 * the heads GitHub names for S (commits/<sha>/pulls), each with the first
 * parents that still have that tree (a merge of master that changed no file),
 * and the heads of recent dispatch and push runs with that tree. Their newest
 * dispatch or push run decides, as in the remote gate: a newer failed or
 * in-progress full run gives no reuse, a cancelled run or one that skipped the
 * full job looks further back. Any API error, cancelled, failed or in-progress attempt,
 * missing or cheap artifact, tree mismatch or root commit gives reuse=false
 * with a reason.
 *
 * Writes reuse, source_run_id, source_run_attempt, source_sha, tree and reason
 * to --output, one summary line (the reused run URL, or the fallback reason)
 * to --summary, and the reuse record (REUSE_FILE, read by
 * scripts/release-gate.ts) to --record. Exit 0 whenever a decision was
 * written (a fallback is not an error), 2 on usage.
 *
 *   bun scripts/ci-reuse.ts --gate --sha <HEAD> --tree <tree> --repo <owner/name> [--wait-minutes N] [--poll-seconds S]
 *
 * Remote-gate reuse (decideGate, runGate): scripts/pregate-remote-gate.sh asks whether Test and E2E already
 * passed their complete full runs on this exact tree; exit 0 reuse, 3 a full run on the tree failed, 4 no reuse.
 */
import { appendFileSync, writeFileSync } from 'node:fs';
import { fetchArtifactJson, inert, restClient, type GitHubClient } from './lib/gh-issue.ts';

export const PROFILES = {
  test: { file: 'test.yml', workflow: 'Test', job: 'full-suite', artifact: 'full-suite-tree' },
  e2e: { file: 'e2e.yml', workflow: 'E2E Tests', job: 'e2e-full-suite', artifact: 'e2e-full-suite-tree' },
} as const;
export type Profile = (typeof PROFILES)[keyof typeof PROFILES];
export const TREE_FILE = 'tree.json';
/** The push run's marker job and artifact when it reused a run; scripts/release-gate.ts reads both. */
export const REUSE_JOB = 'reused-full-suite';
export const REUSE_ARTIFACT = 'reused-full-suite';
export const REUSE_FILE = 'reuse.json';
const MAX_FALLBACK_HEADS = 20;
const SHA = /^[0-9a-f]{40}$/;
/** Full runs have the push shape; pull_request runs are the cheap tier. */
export const CANDIDATE_EVENTS = ['workflow_dispatch', 'push'] as const;
const isCandidate = (run: FullRun) => (CANDIDATE_EVENTS as readonly string[]).includes(run.event);

export interface Commit { tree: string; parents: string[] }
export interface FullRun { id: number; run_number: number; run_attempt: number; status: string; conclusion: string | null; head_sha: string; event: string; head_repository?: { full_name: string } | null }
export interface JobRow { name: string; status?: string; conclusion: string | null; started_at?: string | null }
export interface ReuseDeps {
  commit(sha: string): Promise<Commit>;
  runsForHead(file: string, sha: string): Promise<FullRun[]>;
  recentSuccessfulRuns(file: string): Promise<FullRun[]>;
  /** Head commits of the pull requests GitHub associates with commit `sha` (a squashed landing names its pull request); a fork head's runs are refused like any fork run. */
  pullHeads(sha: string): Promise<string[]>;
  /** The newest workflow_dispatch and push runs of `file`, whatever their status (a failed run counts against its tree too). */
  recentRuns(file: string): Promise<FullRun[]>;
  jobs(runId: number, attempt: number): Promise<JobRow[]>;
  artifact(runId: number, name: string): Promise<{ value?: unknown; reason?: string }>;
}
export type Reason =
  | 'identical_tree_full_run' | 'not_merge_commit' | 'api_error' | 'no_candidate' | 'fork_run'
  | 'run_in_progress' | 'run_cancelled' | 'run_failed' | 'full_suite_missing' | 'full_suite_ambiguous' | 'full_suite_not_success'
  | 'artifact_missing' | 'artifact_mismatch' | 'artifact_not_full' | 'tree_mismatch';
export interface Rejection { run_id: number; reason: Reason; detail: string }
export interface Decision { reuse: boolean; reason: Reason; detail: string; tree?: string; source?: { run_id: number; run_attempt: number; sha: string }; rejected: Rejection[] }

async function reject(deps: ReuseDeps, p: Profile, run: FullRun, repo: string, pushTree: string, headTree: string): Promise<Omit<Rejection, 'run_id'> | undefined> {
  const at = `run ${run.id} attempt ${run.run_attempt}`;
  if (run.head_repository?.full_name !== repo) return { reason: 'fork_run', detail: `${at} ran for ${run.head_repository?.full_name ?? 'an unknown repository'}, not ${repo}` };
  if (run.status !== 'completed') return { reason: 'run_in_progress', detail: `${at} is ${run.status}` };
  if (run.conclusion === 'cancelled') return { reason: 'run_cancelled', detail: `${at} was cancelled` };
  if (run.conclusion !== 'success') return { reason: 'run_failed', detail: `${at} concluded ${run.conclusion}` };
  const jobs = (await deps.jobs(run.id, run.run_attempt)).filter(j => j.name === p.job);
  if (jobs.length === 0) return { reason: 'full_suite_missing', detail: `${at} has no ${p.job} job (not a full-profile run)` };
  if (jobs.length > 1) return { reason: 'full_suite_ambiguous', detail: `${at} has ${jobs.length} jobs named ${p.job}` };
  if (jobs[0]!.conclusion !== 'success') return { reason: 'full_suite_not_success', detail: `${at}'s ${p.job} job concluded ${jobs[0]!.conclusion}` };
  const got = await deps.artifact(run.id, p.artifact);
  if (got.reason) return { reason: 'artifact_missing', detail: got.reason };
  const rec = got.value as Record<string, unknown> | null;
  if (!rec || typeof rec !== 'object') return { reason: 'artifact_mismatch', detail: `${at}'s ${p.artifact} ${TREE_FILE} is not a JSON object` };
  if (rec.profile !== 'full') return { reason: 'artifact_not_full', detail: `${at}'s ${p.artifact} records profile ${String(rec.profile)}` };
  const expected: Array<[string, string | number]> = [['run_id', run.id], ['run_attempt', run.run_attempt], ['sha', run.head_sha], ['event', run.event], ['workflow', p.workflow]];
  if (rec.head_sha !== undefined) expected.push(['head_sha', run.head_sha]);
  const wrong = expected.filter(([k, v]) => rec[k] !== v);
  if (wrong.length) return { reason: 'artifact_mismatch', detail: `${at}'s ${p.artifact} records ${wrong.map(([k, v]) => `${k} ${String(rec[k])} (expected ${v})`).join(', ')}` };
  if (rec.tree !== pushTree) return { reason: 'tree_mismatch', detail: `${at} tested tree ${String(rec.tree)}, the push tree is ${pushTree}` };
  if (rec.tree !== headTree) return { reason: 'tree_mismatch', detail: `${at} recorded tree ${String(rec.tree)} but its head ${run.head_sha} has tree ${headTree}` };
  return undefined;
}

/** The reuse decision for push commit `sha` (pure over its dependencies; every failure is a fallback). */
export async function decide(deps: ReuseDeps, p: Profile, sha: string, repo: string): Promise<Decision> {
  const rejected: Rejection[] = [];
  let tree: string | undefined;
  try {
    const push = await deps.commit(sha);
    tree = push.tree;
    if (push.parents.length === 1) return await decideOneParent(deps, p, sha, tree, repo, rejected);
    if (push.parents.length !== 2) return { reuse: false, reason: 'not_merge_commit', detail: `push ${sha} has ${push.parents.length} parent(s); only a merge commit or a one-parent commit can reuse a run`, tree, rejected };
    const head = push.parents[1]!;
    const headTree = (await deps.commit(head)).tree;
    const primary = (await deps.runsForHead(p.file, head)).filter(r => r.head_sha === head && isCandidate(r)).sort((a, b) => b.id - a.id);
    for (const run of primary) {
      const why = await reject(deps, p, run, repo, tree, headTree);
      if (!why) return accept(run, tree, rejected, 'the merged head');
      rejected.push({ run_id: run.id, ...why });
    }
    const tried = new Set(primary.map(r => r.id));
    const heads = new Map<string, string>();
    for (const run of (await deps.recentSuccessfulRuns(p.file)).sort((a, b) => b.id - a.id)) {
      if (tried.has(run.id) || !isCandidate(run) || run.head_sha === head || run.head_sha === sha || run.head_repository?.full_name !== repo) continue;
      if (!heads.has(run.head_sha)) {
        if (heads.size >= MAX_FALLBACK_HEADS) continue;
        heads.set(run.head_sha, (await deps.commit(run.head_sha)).tree);
      }
      if (heads.get(run.head_sha) !== tree) continue;
      const why = await reject(deps, p, run, repo, tree, tree);
      if (!why) return accept(run, tree, rejected, `head ${run.head_sha.slice(0, 12)} (same tree as the merged head)`);
      rejected.push({ run_id: run.id, ...why });
    }
  } catch (e) {
    return { reuse: false, reason: 'api_error', detail: `reading the push commit, runs, jobs or artifacts failed: ${e instanceof Error ? e.message : String(e)}`, tree, rejected };
  }
  if (!rejected.length) return { reuse: false, reason: 'no_candidate', detail: `no ${p.workflow} workflow_dispatch or push run exists on the merged head or on another head with tree ${tree}`, tree, rejected };
  return { reuse: false, reason: rejected[0]!.reason, detail: rejected.map(r => r.detail).join('; '), tree, rejected };
}

/**
 * A one-parent push (a squashed landing, a hand revert, a direct push) has no merged head, so its tree alone decides:
 * the newest full run on any head with that tree, as in the remote gate. The landed pull request's head counts, and
 * so do its first parents with the same tree, since a merge of master that changed no file leaves the full run on the
 * commit before it.
 */
async function decideOneParent(deps: ReuseDeps, p: Profile, sha: string, tree: string, repo: string, rejected: Rejection[]): Promise<Decision> {
  const seeds: string[] = [];
  for (const head of new Set(await deps.pullHeads(sha))) {
    let at = head;
    for (let i = 0; i < MAX_FALLBACK_HEADS && at !== sha && !seeds.includes(at); i++) {
      const c = await deps.commit(at);
      if (c.tree !== tree) break;
      seeds.push(at);
      if (!c.parents[0]) break;
      at = c.parents[0];
    }
  }
  const found = await newestFullRun(deps, p, await sameTreeHeads(deps, p, tree, repo, seeds, sha), tree, repo, rejected);
  if (found && !found.why) return accept(found.run, tree, rejected, `head ${found.run.head_sha.slice(0, 12)} (same tree as the one-parent push)`);
  if (found?.why) return { reuse: false, reason: found.why.reason, detail: `the newest full run on tree ${tree} decides: ${found.why.detail}`, tree, rejected };
  if (!rejected.length) return { reuse: false, reason: 'no_candidate', detail: `no ${p.workflow} workflow_dispatch or push run exists on a head with tree ${tree} (the pull request heads GitHub names for one-parent push ${sha} or recent runs)`, tree, rejected };
  return { reuse: false, reason: rejected[0]!.reason, detail: rejected.map(r => r.detail).join('; '), tree, rejected };
}

/** `seeds` plus the heads of recent dispatch and push runs whose commit has `tree`, never `skip` (the push itself). */
async function sameTreeHeads(deps: ReuseDeps, p: Profile, tree: string, repo: string, seeds: string[], skip?: string): Promise<string[]> {
  const shas = [...seeds];
  const trees = new Map<string, string>();
  for (const run of (await deps.recentRuns(p.file)).sort((a, b) => b.id - a.id)) {
    if (!isCandidate(run) || run.head_sha === skip || shas.includes(run.head_sha) || run.head_repository?.full_name !== repo || trees.has(run.head_sha)) continue;
    if (trees.size >= MAX_FALLBACK_HEADS) break;
    trees.set(run.head_sha, (await deps.commit(run.head_sha)).tree);
    if (trees.get(run.head_sha) === tree) shas.push(run.head_sha);
  }
  return shas;
}

/**
 * The newest full run across `shas` that decides: a passed complete one (no `why`), or one in progress, failed or with
 * a failed full job (`why` says which). A run that skipped its full job or lacks it (a diagnostic dispatch, a push
 * that reused) and any other rejected run is recorded in `rejected` and passed over. Undefined when none decides.
 */
async function newestFullRun(deps: ReuseDeps, p: Profile, shas: string[], tree: string, repo: string, rejected: Rejection[]): Promise<{ run: FullRun; why?: Omit<Rejection, 'run_id'> } | undefined> {
  const runs = (await Promise.all(shas.map(async sha => (await deps.runsForHead(p.file, sha)).filter(r => r.head_sha === sha && isCandidate(r) && r.head_repository?.full_name === repo)))).flat().sort((a, b) => b.id - a.id);
  for (const run of runs) {
    const full = (await deps.jobs(run.id, run.run_attempt)).filter(j => j.name === p.job);
    if (full.some(j => j.conclusion === 'skipped') || (run.status === 'completed' && full.length === 0)) {
      rejected.push({ run_id: run.id, reason: 'full_suite_missing', detail: `run ${run.id} attempt ${run.run_attempt} did not run ${p.job} (not a full-profile run)` });
      continue;
    }
    const why = await reject(deps, p, run, repo, tree, tree);
    if (!why || why.reason === 'run_in_progress' || why.reason === 'run_failed' || why.reason === 'full_suite_not_success') return { run, why };
    rejected.push({ run_id: run.id, ...why });
  }
  return undefined;
}

function accept(run: FullRun, tree: string, rejected: Rejection[], where: string): Decision {
  return { reuse: true, reason: 'identical_tree_full_run', detail: `run ${run.id} attempt ${run.run_attempt} on ${where} ran the complete full suite on tree ${tree}`, tree, source: { run_id: run.id, run_attempt: run.run_attempt, sha: run.head_sha }, rejected };
}

/**
 * Remote-gate reuse (scripts/pregate-remote-gate.sh, docs/ci-event-parity.md#remote-gate-reuse): GitHub's full
 * profile is the source of truth, so a clean working tree whose commit `head` (or another head with the same tree)
 * already passed the complete full run of a workflow needs no Ubicloud gate. Same fail-closed checks as a push:
 * the run's latest attempt and its full-suite job succeeded and its tested-tree artifact records `tree`. Only
 * the identical tree reuses; a stamp-only difference goes through gstack-pregate's stamp rule, never through here.
 * The newest full run on the tree decides, across `head` and every other recent head with the same tree: in progress
 * waits, a failure refuses (no receipt, no VMs), cancelled or not a full run (its full job skipped or absent: a
 * diagnostic dispatch, a push that reused) looks further back; a passed run on `head` whose executed-test receipt is
 * refused is `rejected`, since no later dispatch of `head` is coming (on another same-tree head it is `none`: `head`'s
 * own dispatch can still appear); anything else is `none` and the caller runs the VM gate.
 */
export type GateState = 'reuse' | 'pending' | 'failed' | 'rejected' | 'none';
/**
 * Executed test counts; `partial` names the attempt when they cover only the jobs that attempt re-ran, and
 * `ledgerAttempt` the earlier attempt that wrote the ledger when it is older than the run's latest attempt.
 */
export interface ExecutedCounts { tests: number; failed: number; partial?: number; ledgerAttempt?: number }
/** The job that writes the executed-identities ledger, in test.yml and e2e.yml. */
export const LEDGER_JOB = 'executed-receipts';
export interface GateDecision { state: GateState; detail: string; tests?: number; failed?: number; partial?: number; url?: string }
export interface GateDeps extends ReuseDeps {
  /** Executed (pass, fail) test identities in the run's executed-identities artifact, each job at its newest attempt (`ledgerAttempt` when an earlier attempt wrote it), or why they cannot be read. */
  executed(run: FullRun): Promise<ExecutedCounts | { reason: string; transient?: boolean }>;
}

export async function decideGate(deps: GateDeps, p: Profile, head: string, tree: string, repo: string): Promise<GateDecision> {
  const rejected: Rejection[] = [];
  try {
    const headTree = (await deps.commit(head)).tree;
    if (headTree !== tree) return { state: 'none', detail: `${p.workflow}: commit ${head} has tree ${headTree} on GitHub, not the working tree ${tree}` };
    const found = await newestFullRun(deps, p, await sameTreeHeads(deps, p, tree, repo, [head]), tree, repo, rejected);
    if (found && !found.why) {
      const d = await gateAccept(deps, p, found.run, tree, repo);
      return d.state === 'rejected' && found.run.head_sha !== head ? { ...d, state: 'none' } : d;
    }
    if (found?.why?.reason === 'run_in_progress') return { state: 'pending', detail: `${p.workflow} ${found.why.detail}` };
    if (found?.why) return { state: 'failed', detail: `${p.workflow} ${found.why.detail}`, url: runUrl(repo, found.run) };
  } catch (e) {
    return { state: 'none', detail: `${p.workflow}: reading commits, runs, jobs or artifacts failed: ${e instanceof Error ? e.message : String(e)}` };
  }
  return { state: 'none', detail: rejected.length ? `${p.workflow}: ${rejected.map(r => r.detail).join('; ')}` : `${p.workflow}: no workflow_dispatch or push run on ${head} or on another head with tree ${tree}` };
}

const runUrl = (repo: string, run: FullRun) => `https://github.com/${repo}/actions/runs/${run.id}/attempts/${run.run_attempt}`;

async function gateAccept(deps: GateDeps, p: Profile, run: FullRun, tree: string, repo: string): Promise<GateDecision> {
  const got = await deps.executed(run);
  if ('reason' in got) return { state: got.transient ? 'none' : 'rejected', detail: `${p.workflow}: ${got.reason}` };
  const { ledgerAttempt, ...counts } = got;
  // A re-run that leaves the ledger job alone carries it into the new attempt with its original start; a ledger job
  // that ran again but uploaded nothing leaves the older attempt's ledger behind, now stale.
  if (ledgerAttempt !== undefined) {
    const started = async (attempt: number) => (await deps.jobs(run.id, attempt)).filter(j => j.name === LEDGER_JOB).map(j => j.started_at);
    const [wrote, latest] = await Promise.all([started(ledgerAttempt), started(run.run_attempt)]);
    if (wrote.length !== 1 || latest.length !== 1 || !wrote[0] || wrote[0] !== latest[0]) {
      return { state: 'rejected', detail: `${p.workflow}: run ${run.id}'s executed-identities.json is from attempt ${ledgerAttempt}, but its ${LEDGER_JOB} job ran again by attempt ${run.run_attempt} without replacing it` };
    }
  }
  if (counts.tests <= 0) return { state: 'rejected', detail: `${p.workflow}: run ${run.id}'s executed-identities artifact lists no executed test` };
  return { state: 'reuse', detail: `${p.workflow} run ${runUrl(repo, run)} passed the complete full suite on tree ${tree}`, url: runUrl(repo, run), ...counts };
}

export const GATE_WAIT_MINUTES = 90;
export const GATE_POLL_SECONDS = 60;

/**
 * The gate's decision over Test and E2E, waiting while a full run on the tree is still in progress, up to the wait
 * bound. A workflow with no full run on the tree does not end the wait: full-ci dispatches Test and E2E separately, so
 * its run can still appear, and a failure of the run in progress refuses (exit 3) instead of starting VMs on a tree
 * GitHub already failed (#8096). A `rejected` workflow ends the wait at once: reuse needs both. Prints progress
 * at least every poll (gstack's stall timeout kills a silent gate) and, on reuse, a last line
 * `GBRAIN_REUSE_RESULT tests=<n> failed=<n>`. Exit codes: 0 reuse, 3 a full run on this tree failed, 4 no reuse.
 */
export async function runGate(deps: GateDeps, o: { head: string; tree: string; repo: string; waitMs: number; pollMs: number; log: (line: string) => void; sleep?: (ms: number) => Promise<unknown>; now?: () => number }): Promise<number> {
  const now = o.now ?? Date.now;
  const deadline = now() + o.waitMs;
  for (;;) {
    const ds = await Promise.all([PROFILES.test, PROFILES.e2e].map(p => decideGate(deps, p, o.head, o.tree, o.repo)));
    const failed = ds.find(d => d.state === 'failed');
    if (failed) {
      o.log(`[ci-reuse] gate: ${failed.detail} (${failed.url}); the full run on this tree failed, so no receipt and no Ubicloud gate`);
      return 3;
    }
    if (ds.every(d => d.state === 'reuse')) {
      for (const d of ds) o.log(`[ci-reuse] gate: ${d.detail} (${d.tests} tests, ${d.failed} failed${d.partial ? `; attempt ${d.partial}, partial count` : ''})`);
      o.log(`GBRAIN_REUSE_RESULT tests=${ds.reduce((n, d) => n + d.tests!, 0)} failed=${ds.reduce((n, d) => n + d.failed!, 0)}`);
      return 0;
    }
    const pending = ds.filter(d => d.state === 'pending');
    if (!pending.length || ds.some(d => d.state === 'rejected') || now() >= deadline) {
      for (const d of ds.filter(x => x.state !== 'reuse')) o.log(`[ci-reuse] gate: no reuse: ${inert(d.detail, 600)}`);
      return 4;
    }
    const none = ds.filter(d => d.state === 'none').map(d => `; no full run to reuse yet (${inert(d.detail, 300)}), so this wait reuses only if one appears and otherwise refuses if the run in progress fails`).join('');
    o.log(`[ci-reuse] gate: waiting for ${pending.map(d => d.detail).join('; ')}${none} (${Math.ceil((deadline - now()) / 60_000)} min left)`);
    await (o.sleep ?? Bun.sleep)(o.pollMs);
  }
}

/**
 * Every job of one attempt. The jobs API pages at up to 100, but GitHub has answered a 100-job page of a rerun attempt
 * with a 502 on every retry while 30-job pages of the same attempt answered (Release run 39712021085, v0.60.361.0), so a
 * 5xx that outlives the client's retries restarts the listing at 30 per page.
 */
export async function attemptJobs(client: GitHubClient, runId: number, attempt: number): Promise<JobRow[]> {
  for (const perPage of [100, 30]) {
    const out: JobRow[] = [];
    try {
      for (let page = 1; page * perPage <= 1000; page++) {
        const r = await client.request<{ total_count: number; jobs: JobRow[] }>('GET', `repos/{repo}/actions/runs/${runId}/attempts/${attempt}/jobs?per_page=${perPage}&page=${page}`);
        out.push(...r.jobs);
        if (r.jobs.length < perPage || out.length >= r.total_count) return out;
      }
    } catch (e) {
      if (perPage === 30 || ((e as { status?: number }).status ?? 0) < 500) throw e;
      continue;
    }
    throw new Error(`run ${runId} attempt ${attempt} lists more than 1000 jobs`);
  }
  throw new Error('unreachable');
}

export function apiDeps(client: GitHubClient): ReuseDeps {
  return {
    async commit(sha) {
      const c = await client.request<{ tree: { sha: string }; parents: Array<{ sha: string }> }>('GET', `repos/{repo}/git/commits/${sha}`);
      return { tree: c.tree.sha, parents: c.parents.map(x => x.sha) };
    },
    async runsForHead(file, sha) {
      return (await client.request<{ workflow_runs: FullRun[] }>('GET', `repos/{repo}/actions/workflows/${file}/runs?head_sha=${sha}&per_page=100`)).workflow_runs;
    },
    async recentSuccessfulRuns(file) {
      const pages = await Promise.all(CANDIDATE_EVENTS.map(event => client.request<{ workflow_runs: FullRun[] }>('GET', `repos/{repo}/actions/workflows/${file}/runs?event=${event}&status=success&per_page=100`)));
      return pages.flatMap(p => p.workflow_runs);
    },
    async pullHeads(sha) {
      return (await client.request<Array<{ head: { sha: string } }>>('GET', `repos/{repo}/commits/${sha}/pulls`)).map(pr => pr.head.sha);
    },
    async recentRuns(file) {
      const pages = await Promise.all(CANDIDATE_EVENTS.map(event => client.request<{ workflow_runs: FullRun[] }>('GET', `repos/{repo}/actions/workflows/${file}/runs?event=${event}&per_page=100`)));
      return pages.flatMap(p => p.workflow_runs);
    },
    jobs: (runId, attempt) => attemptJobs(client, runId, attempt),
    artifact: (runId, name) => fetchArtifactJson(client, runId, name, TREE_FILE),
  };
}

export function gateDeps(client: GitHubClient): GateDeps {
  return {
    ...apiDeps(client),
    async executed(run) {
      const got = await fetchArtifactJson(client, run.id, 'executed-identities', 'executed-identities.json');
      if (got.reason) return got.transient ? { reason: got.reason, transient: true } : { reason: got.reason };
      const doc = got.value as { head?: { identities?: Array<{ status?: string }> }; issues?: Array<{ kind?: string }>; run?: { id?: unknown; attempt?: unknown } | null; job_latest?: { executed?: unknown; failed?: unknown } } | null;
      const ids = doc?.head?.identities;
      if (!Array.isArray(ids)) return { reason: `run ${run.id}'s executed-identities.json has no head.identities list` };
      const by = doc!.run;
      if (by && (by.id !== run.id || typeof by.attempt !== 'number' || by.attempt > run.run_attempt)) {
        return { reason: `run ${run.id} attempt ${run.run_attempt}'s executed-identities.json was written by run ${String(by.id)} attempt ${String(by.attempt)}` };
      }
      const older = by && (by.attempt as number) < run.run_attempt ? { ledgerAttempt: by.attempt as number } : {};
      const latest = doc!.job_latest;
      if (latest && Number.isSafeInteger(latest.executed) && Number.isSafeInteger(latest.failed)) return { tests: latest.executed as number, failed: latest.failed as number, ...older };
      const counts = { tests: ids.filter(i => i.status === 'pass' || i.status === 'fail').length, failed: ids.filter(i => i.status === 'fail').length, ...older };
      return Array.isArray(doc!.issues) && doc!.issues.some(i => i?.kind === 'prior-attempt') ? { ...counts, partial: run.run_attempt } : counts;
    },
  };
}

/** The validated source run of a reuse record, or why the record cannot prove one. */
export function checkRecord(value: unknown, workflow: string, pushSha: string): { run_id: number; run_attempt: number; sha: string } | string {
  const rec = value as Record<string, unknown> | null | undefined;
  if (!rec || typeof rec !== 'object') return `${REUSE_FILE} is not a JSON object`;
  if (rec.reuse !== true) return `${REUSE_FILE} says reuse is not true`;
  if (rec.workflow !== workflow) return `${REUSE_FILE} is for workflow ${String(rec.workflow)}, not ${workflow}`;
  if (rec.push_sha !== pushSha) return `${REUSE_FILE} is for push ${String(rec.push_sha)}, not ${pushSha}`;
  const id = rec.source_run_id, attempt = rec.source_run_attempt, sha = rec.source_sha;
  if (!Number.isSafeInteger(id) || (id as number) <= 0 || !Number.isSafeInteger(attempt) || (attempt as number) <= 0 || typeof sha !== 'string' || !SHA.test(sha)) return `${REUSE_FILE} names no valid source run`;
  return { run_id: id as number, run_attempt: attempt as number, sha };
}

export function writeDecision(d: Decision, p: Profile, opts: { repo: string; sha: string; output: string; summary?: string; record?: string }): string {
  const url = d.source && `https://github.com/${opts.repo}/actions/runs/${d.source.run_id}/attempts/${d.source.run_attempt}`;
  appendFileSync(opts.output, [
    `reuse=${d.reuse}`, `source_run_id=${d.source?.run_id ?? ''}`, `source_run_attempt=${d.source?.run_attempt ?? ''}`,
    `source_sha=${d.source?.sha ?? ''}`, `tree=${d.tree ?? ''}`, `reason=${d.reason}`, '',
  ].join('\n'));
  const line = d.reuse
    ? `${p.workflow} push ${opts.sha.slice(0, 12)}: reused the complete full-suite run ${url} (head ${d.source!.sha.slice(0, 12)}, identical tree ${d.tree}).`
    : `${p.workflow} push ${opts.sha.slice(0, 12)}: full run, no reuse (reason \`${d.reason}\`: ${inert(d.detail, 600)}).`;
  if (opts.summary) appendFileSync(opts.summary, `${line}\n`);
  if (opts.record) {
    writeFileSync(opts.record, `${JSON.stringify({
      reuse: d.reuse, workflow: p.workflow, push_sha: opts.sha, tree: d.tree ?? null, reason: d.reason,
      source_run_id: d.source?.run_id ?? null, source_run_attempt: d.source?.run_attempt ?? null, source_sha: d.source?.sha ?? null, source_url: url ?? null,
    }, null, 2)}\n`);
  }
  return line;
}

const flag = (name: string) => { const i = process.argv.indexOf(name); return i >= 0 ? process.argv[i + 1] : undefined; };
if (import.meta.main && process.argv.includes('--gate')) {
  const head = flag('--sha') ?? '', tree = flag('--tree') ?? '', repo = flag('--repo') ?? '';
  const minutes = Number(flag('--wait-minutes') ?? GATE_WAIT_MINUTES), poll = Number(flag('--poll-seconds') ?? GATE_POLL_SECONDS);
  if (!SHA.test(head) || !SHA.test(tree) || !/^[\w.-]+\/[\w.-]+$/.test(repo) || !(minutes >= 0) || !(poll > 0)) {
    console.log(`Usage: bun scripts/ci-reuse.ts --gate --sha <40-hex HEAD> --tree <40-hex tree> --repo <owner/name> [--wait-minutes ${GATE_WAIT_MINUTES}] [--poll-seconds ${GATE_POLL_SECONDS}]`);
    process.exit(2);
  }
  process.exit(await runGate(gateDeps(restClient(repo)), { head, tree, repo, waitMs: minutes * 60_000, pollMs: poll * 1000, log: line => console.log(line) }));
} else if (import.meta.main) {
  const key = flag('--workflow') ?? '';
  const sha = flag('--sha') ?? '';
  const repo = flag('--repo') ?? '';
  const output = flag('--output');
  if (!(key === 'test' || key === 'e2e') || !SHA.test(sha) || !/^[\w.-]+\/[\w.-]+$/.test(repo) || !output) {
    console.log('Usage: bun scripts/ci-reuse.ts --workflow test|e2e --sha <40-hex push sha> --repo <owner/name> --output <GITHUB_OUTPUT> [--summary <GITHUB_STEP_SUMMARY>] [--record <reuse.json>]');
    process.exit(2);
  }
  const p = PROFILES[key];
  const d = await decide(apiDeps(restClient(repo)), p, sha, repo);
  console.log(`[ci-reuse] ${writeDecision(d, p, { repo, sha, output, summary: flag('--summary'), record: flag('--record') })}`);
}