@bongos/core 1.21.175 → 1.21.177

package/scripts/gds/main-audit.js

@@ -1,625 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/main-audit.js — post-push main audit (SEC #863, ADR 0043).
-//
-// LAYER 3, the AUTHORITATIVE net. The pre-push hook (layer 1) and the grader
-// pre-pass (layer 2) gate the cooperative path, but a free-plan private repo
-// can't forbid a raw `git push origin main` at GitHub, and a builder can
-// `--no-verify`. This audit reads the REAL git history on main and the REAL
-// builder ranks (from the GDS roster) and flags commits where a builder BELOW
-// Metic edited a permission-sensitive surface — exactly the Builder 25 incident
-// (a Thetes editing the rank-tier CASE in src/bongos/db.js and pushing to main).
-//
-// Two modes:
-//   (report, default)   list findings on a commit range; non-zero exit if any
-//                        blocker — usable from CI.
-//   --verify-head       gate for the deploy step (infra/deploy.sh): exit non-zero
-//                        if HEAD's range contains a blocker, so a poisoned main
-//                        never reaches production. THIS is the bridge to Option
-//                        A: even though builders technically can push main today,
-//                        the DEPLOY refuses un-authorized commits.
-//
-// Identity: a commit's author NAME is the builder's github_login in this
-// pipeline (verified on the #863 commit: author "IAMMASTERQUA"). We resolve the
-// author against the GDS roster (github_login / display_name). MERGE commits are
-// skipped — their protected-path content is attributed to the feature commits
-// they bring in (which carry the real author). An author we cannot resolve to a
-// rank on a protected-path commit is a 'review' finding (in --verify-head it
-// blocks unless --allow-unverified, fail-closed).
-//
-// THE ATTESTATION PASS (task 1001433; owner's option 1, 2026-09-26). The author
-// NAME above is typed text — anyone can commit as 'IAMMASTERQUA'. What cannot be
-// typed is the `gate-author-trust` commit status the SERVER posts on a ship's
-// pushed tip after resolving the builder's CLI session to a Metic+ rank
-// (POST /tasks/:id/attest-gate + publish-branch, ADR 0058). So each protected-path
-// commit is traced to the pull request that brought it onto main (the second
-// parent of its first-parent merge) and that head must carry a SUCCESS status of
-// that context, posted by the server's own GitHub identity. A status with the same
-// name posted by any other account is ignored: anyone with write access can post a
-// status, so the CREATOR is the part that cannot be faked. FLAG-ONLY for now, by
-// the owner's ruling: an unattested commit is a 'review' finding and never changes
-// the exit code. It needs a GitHub token (GITHUB_TOKEN / GH_TOKEN); without one it
-// says it did not run rather than passing.
-//
-// Usage:
-//   node scripts/gds/main-audit.js                       # audit last 50 on origin/main
-//   node scripts/gds/main-audit.js --range A..B          # audit an explicit range
-//   node scripts/gds/main-audit.js --verify-head         # deploy gate: HEAD~30..HEAD
-//   node scripts/gds/main-audit.js --verify-head --db    # deploy gate on the droplet (rank from Postgres)
-//   node scripts/gds/main-audit.js --revert              # also print `git revert` plan
-//   node scripts/gds/main-audit.js --strict              # also block on unresolved authors
-//   node scripts/gds/main-audit.js --db                  # resolve ranks from Postgres instead of the API
-//   node scripts/gds/main-audit.js --require-roster      # CI: an empty roster is a loud DID-NOT-RUN, not a vacuous green
-//   node scripts/gds/main-audit.js --require-attestation # CI: an attestation pass that could not run exits 2
-//   node scripts/gds/main-audit.js --attest-login <login> # the account the server posts statuses as (default: the repo owner)
-//   node scripts/gds/main-audit.js --no-attestation      # skip the attestation pass
-//   GH_TOKEN=$(gh auth token) node scripts/gds/main-audit.js   # a local run with the attestation pass
-//
-// EXIT CONTRACT — never `process.exit()` here, use `cliExit(code)` + `return`
-// (task 1003772). Every exit in this file lands after the roster request, and a
-// hard exit mid-teardown aborts node natively on Windows (UV_HANDLE_CLOSING),
-// printing the verdict and THEN dying at 127. That is worse here than in any
-// other CLI: --verify-head IS the deploy gate, so the destroyed code makes a
-// clean audit look like a refusal and a real blocker indistinguishable from a
-// crash. Guarded by the static check in tests/cli_exit_no_abort.mjs.
-// Codes: 0 = clean · 1 = blocker found · 2 = DID NOT RUN (never a pass).
-
+// scripts/gds/main-audit.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/main-audit.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-
-const { execSync } = require('node:child_process');
-const ppc = require(require('node:path').join(__dirname, '..', '..', 'src', 'bongos', 'permission-path-check.js'));
-const { cliClient, cliExit, API_BASE } = require('./cli-lib');
-const { resolveEnv, envPrefix } = require(require('node:path').join(__dirname, '..', '..', 'src', 'instance-config.js'));
-
-// ---------- pure analyzer (tested in tests/main_audit.mjs) ----------
-
-// commits: [{ sha, subject, authorName, authorEmail, isMerge, files: [] }]
-// rankByIdentity: { '<lowercased login-or-name-or-email>': '<rank>' }
-// Returns { ok, hardFail, findings[] }.
-// strict=true escalates "author couldn't be resolved to a rank" from a
-// 'review' note to a hard blocker. Default is NON-strict: only a RESOLVED
-// sub-Metic author is a blocker (the high-confidence, zero-false-positive
-// signal — the #863 case). This matters because the trusted operator/deployer
-// commits under a git author name ('Lars Kristensen') that is a display name,
-// not a GDS github_login, and every builder shares one commit email — so the
-// author NAME is the only distinguishing signal, and an unresolved name is
-// 'needs a human glance', not 'definitely a violation'.
-//
-// `registry` is the protected-surface matcher, defaulting to the real one. It
-// is a parameter for the same reason `rankByIdentity` is: this analyzer is pure
-// and its callers supply its inputs. Tests inject a MIXED-FLOOR fixture through
-// it — the real registry floors every surface at 'metic' today, so without the
-// seam the per-hit floor comparison below is untestable and would silently rot
-// back into a global-minimum test. The CLI never passes it.
-function analyzeCommits(commits, rankByIdentity, { strict = false, registry = ppc } = {}) {
-  const findings = [];
-  for (const c of commits || []) {
-    // #863-followup (finding #5): we no longer blanket-skip merges. For a
-    // regular commit, `files` is its name-only diff. For a MERGE commit, the
-    // git layer (parseCommits) populates `files` with the EVIL-MERGE surface —
-    // the `git diff-tree --cc` set, i.e. changes the merge introduced that are
-    // in NEITHER parent (conflict resolutions / smuggled edits). A normal
-    // pipeline merge has an empty --cc set → no files → no finding, so feature
-    // changes are still attributed to their feature commits (no double-count);
-    // but a merge that smuggles a protected change is now caught and attributed
-    // to the MERGE author.
-    const hits = registry.matchProtected(c.files || []);
-    if (hits.length === 0) continue;
-
-    const rank = resolveRank(c, rankByIdentity);
-    const fileList = hits.map((h) => h.file).join(', ');
-    if (rank == null) {
-      const need = strictestFloorLabel(hits, registry);
-      findings.push({
-        severity: strict ? 'blocker' : 'review',
-        sha: c.sha,
-        author: c.authorName,
-        rank: null,
-        files: hits.map((h) => h.file),
-        summary: `commit ${short(c.sha)} by '${c.authorName}' touched permission-sensitive path(s) [${fileList}] but the author could not be resolved to a GDS rank. Verify it is ${need}+ work.`,
-      });
-      continue;
-    }
-
-    // Each hit is judged against ITS OWN registry floor — not against the
-    // registry's global minimum. `isBelowFloor` tests the lowest floor any
-    // surface declares, which is identical only while every surface floors at
-    // the same rank (true today). The moment governance RAISES one surface's
-    // floor, a global-minimum test silently downgrades that raise back to the
-    // minimum here — in the one layer that catches a raw `git push origin main`
-    // (task 1003191; the cooperative layers already compare per-hit via
-    // checkPermissionPaths). Unknown ranks stay non-blocking, as before: an
-    // unresolvable rank is the `rank == null` case above.
-    const tier = registry.tierOf(rank);
-    const below = tier === null ? [] : hits.filter((h) => tier < registry.RANK_TIER[h.floor]);
-    if (below.length > 0) {
-      const need = strictestFloorLabel(below, registry);
-      const belowList = below.map((h) => `${h.file} (floor ${h.floor})`).join(', ');
-      findings.push({
-        severity: 'blocker',
-        sha: c.sha,
-        author: c.authorName,
-        rank,
-        files: below.map((h) => h.file),
-        floors: below.map((h) => h.floor),
-        summary: `commit ${short(c.sha)} by '${c.authorName}' (rank '${rank}') modified permission-sensitive path(s) [${belowList}] whose registry floor it does not clear — this is the SEC #863 violation class. It must be reverted and re-landed by a ${need}+ builder if genuinely needed.`,
-      });
-    }
-  }
-  return {
-    ok: findings.every((f) => f.severity !== 'blocker'),
-    hardFail: findings.some((f) => f.severity === 'blocker'),
-    findings,
-  };
-}
-
-// #863-followup (red-team finding #6): resolve ONLY against github_login.
-// We deliberately do NOT match on email (everyone shares one commit email —
-// non-distinguishing) nor display_name (builder-controlled — a malicious builder
-// can set display_name to another builder's login to ALIAS/poison resolution).
-// github_login is GitHub-controlled and immutable per account. A commit whose
-// git author name is not a known github_login resolves to null → handled by the
-// strict gate (block) rather than silently passing.
-function resolveRank(c, rankByIdentity) {
-  const name = (c.authorName || '').toLowerCase();
-  return name && rankByIdentity[name] != null ? rankByIdentity[name] : null;
-}
-
-function short(sha) {
-  return String(sha || '').slice(0, 9);
-}
-
-// The highest rank floor demanded by a set of protected hits, title-cased for
-// prose ('Metic', 'Archon'). What a reader has to clear to own the whole commit
-// — so a finding names the floor that actually governs it rather than a
-// hardcoded 'Metic+' that a governance floor raise would make a lie.
-function strictestFloorLabel(hits, registry) {
-  const floors = hits.map((h) => h.floor);
-  const top = floors.reduce((a, b) => (registry.RANK_TIER[b] > registry.RANK_TIER[a] ? b : a), floors[0]);
-  return top ? top.charAt(0).toUpperCase() + top.slice(1) : 'Metic';
-}
-
-// ---------- attestation pass (task 1001433) — pure half ----------
-
-// The status context the server posts on a ship's pushed tip (task-route-helpers.js
-// postGateAuthorTrust). Only a SUCCESS of this context by the trusted creator counts.
-const ATTEST_CONTEXT = 'gate-author-trust';
-
-// Which pull-request head vouches for each commit. For every MAINLINE merge (a
-// first-parent commit of main with two parents), the commits it brought in —
-// reachable from its second parent and not from its first — are covered by that
-// second parent: the PR head the server attested at ship time. `revList(range)`
-// returns the shas of a `git rev-list` range; it is a parameter so the mapping is
-// testable without a repository.
-//
-// Only MAINLINE merges may be passed in. A merge INSIDE a pull request ("Merge
-// origin/main into my-branch") has main commits as its second parent, and letting
-// it vouch would credit a branch's merge-from-main for work it never carried.
-function mapIntroducingHeads(mainlineMerges, revList) {
-  const headOf = new Map();
-  for (const m of mainlineMerges || []) {
-    const [first, second] = m.parents || [];
-    if (!first || !second) continue;
-    for (const sha of revList(`${first}..${second}`)) {
-      if (!headOf.has(sha)) headOf.set(sha, second);
-    }
-  }
-  return headOf;
-}
-
-// Did the trusted account attest this head? `statuses` is GitHub's list for one
-// commit, newest first. Statuses from any other creator are ignored outright —
-// they can neither attest nor revoke — and of the trusted creator's own statuses
-// for the context, only the newest decides, so a later failure withdraws a success.
-function isAttested(statuses, trustedLogin) {
-  const want = String(trustedLogin || '').toLowerCase();
-  if (!want) return false;
-  const latest = (Array.isArray(statuses) ? statuses : []).find((s) => s
-    && s.context === ATTEST_CONTEXT
-    && String(s.creator?.login || '').toLowerCase() === want);
-  return !!latest && latest.state === 'success';
-}
-
-// commits: parsed commits (only the protected-path ones matter; others are skipped).
-// headOf: Map sha → the PR head that brought it in (mapIntroducingHeads). A commit
-// with no entry — a direct push to main, or a merge's own smuggled --cc surface —
-// can only be vouched for by an attestation on ITSELF.
-// attested: Set of head shas that carry the trusted attestation (fetchAttestations).
-// Returns { checked, findings[] }. Every finding is severity 'review': the owner
-// ruled this pass flag-only, so it can never make the audit fail.
-function analyzeAttestation(commits, { headOf = new Map(), attested = new Set(), trustedLogin = '', registry = ppc } = {}) {
-  const findings = [];
-  let checked = 0;
-  for (const c of commits || []) {
-    const hits = registry.matchProtected(c.files || []);
-    if (hits.length === 0) continue;
-    checked += 1;
-    // `viaPr`, not `head === c.sha`: a one-commit pull request's head IS the commit.
-    const viaPr = headOf.has(c.sha);
-    const head = viaPr ? headOf.get(c.sha) : c.sha;
-    if (attested.has(head)) continue;
-    const fileList = hits.map((h) => h.file).join(', ');
-    const mark = `successful '${ATTEST_CONTEXT}' status from '${trustedLogin}'`;
-    const confirm = `Confirm it came through a Bongos ship by a ${strictestFloorLabel(hits, registry)}+ builder.`;
-    const summary = viaPr
-      ? `commit ${short(c.sha)} by '${c.authorName}' touched permission-sensitive path(s) [${fileList}], but the pull request that brought it in (head ${short(head)}) carries no ${mark}. ${confirm}`
-      : `commit ${short(c.sha)} by '${c.authorName}' touched permission-sensitive path(s) [${fileList}] and reached main without passing through a pull request (a direct push, or changes a merge made itself), and it carries no ${mark} of its own. ${confirm}`;
-    findings.push({
-      severity: 'review',
-      kind: 'unattested',
-      sha: c.sha,
-      author: c.authorName,
-      head,
-      files: hits.map((h) => h.file),
-      summary,
-    });
-  }
-  return { checked, findings };
-}
-
-// Where the pass reads GitHub from. The token and repository come from the
-// environment GitHub Actions already provides (GITHUB_TOKEN, GITHUB_REPOSITORY),
-// with GH_TOKEN and the origin remote as the laptop fallbacks. The trusted login
-// defaults to the repository OWNER: this platform's server posts statuses with the
-// owner's push token (observed on PR 1233: the status creator is the owner's account), and the owner can
-// push to main directly anyway, so trusting that identity grants nothing new. An
-// instance whose server posts as a GitHub App passes --attest-login <app>[bot].
-function attestationConfig({ env = process.env, remoteUrl = '', loginArg = null } = {}) {
-  const token = env.GITHUB_TOKEN || env.GH_TOKEN || null;
-  let repo = env.GITHUB_REPOSITORY || null;
-  if (!repo && remoteUrl) {
-    const m = /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/.exec(String(remoteUrl).trim());
-    if (m) repo = m[1];
-  }
-  const trustedLogin = (typeof loginArg === 'string' && loginArg) || (repo ? repo.split('/')[0] : null);
-  return { token, repo, trustedLogin };
-}
-
-// ---------- git + API glue (CLI) ----------
-
-function git(args) {
-  return execSync(`git ${args}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-}
-
-// How far back the default scan reaches, in first-parent steps.
-const DEFAULT_WINDOW = 200;
-
-// First-parent depth of a ref. `<ref>~N` walks FIRST parents N times, so this —
-// not the total commit count — is what bounds the window. On a repo where every
-// land is a --no-ff merge the two diverge sharply: this one has 526 commits
-// reachable from origin/main but a first-parent chain only 186 deep.
-function firstParentDepth(ref) {
-  try {
-    return Number(git(`rev-list --count --first-parent ${ref}`).trim());
-  } catch (_) {
-    return NaN;
-  }
-}
-
-// Clamp the window to what the history actually holds. Returns null when there
-// is nothing to audit, so the caller reports that plainly instead of emitting a
-// `<ref>~200..<ref>` that git rejects as an unknown revision (task 1002566).
-function clampWindow(depth, want = DEFAULT_WINDOW) {
-  if (typeof depth !== 'number' || !Number.isFinite(depth) || depth < 2) return null;
-  return Math.min(want, depth - 1);
-}
-
-function defaultRange(ref, depth, want = DEFAULT_WINDOW) {
-  const n = clampWindow(depth, want);
-  return n === null ? null : `${ref}~${n}..${ref}`;
-}
-
-// Parse `git log --name-only` with a NUL-delimited custom format into commits.
-function parseCommits(range) {
-  // %x00 = NUL. Format: NUL sha NUL parents NUL authorName NUL authorEmail NUL subject \n files...
-  const fmt = '%x00%H%x00%P%x00%an%x00%ae%x00%s';
-  let out;
-  try {
-    out = git(`log ${range} --name-only --format=${JSON.stringify(fmt)}`);
-  } catch (e) {
-    // Say plainly that nothing was audited. A bare git error here used to read
-    // as a transient glitch, which is how a dead check passed for a clean one.
-    return { error: `DID NOT RUN — git log could not resolve range ${range}, so no commits were audited: ${e.message}` };
-  }
-  const records = out.split('\x00').slice(1); // first chunk is empty / pre-first-NUL
-  const commits = [];
-  // Each commit emits: sha, parents, an, ae, "subject\nfile\nfile...". We split
-  // on NUL so chunks come in groups of 5; the 5th holds subject + file list.
-  for (let i = 0; i + 4 < records.length; i += 5) {
-    const sha = records[i].trim();
-    const parents = records[i + 1].trim();
-    const authorName = records[i + 2];
-    const authorEmail = records[i + 3];
-    const rest = records[i + 4].split('\n');
-    const subject = rest.shift();
-    const files = rest.map((s) => s.trim()).filter(Boolean);
-    if (!sha) continue;
-    // Kept in order: the attestation pass needs a merge's SECOND parent (the PR head).
-    const parentList = parents.split(/\s+/).filter(Boolean);
-    const isMerge = parentList.length > 1;
-    commits.push({ sha, subject, authorName, authorEmail, isMerge, parents: parentList, files });
-  }
-  // #863-followup (finding #5): `git log --name-only` emits NO files for merge
-  // commits, so a merge that SMUGGLES a protected change (an "evil merge" /
-  // conflict resolution that edits a file present in neither parent) would slip
-  // through. Backfill each merge's `files` with the combined-diff (`--cc`)
-  // surface — exactly the changes the merge introduced vs. all parents. A clean
-  // pipeline merge has an empty --cc set (nothing to flag); a smuggled edit
-  // shows up here and is attributed to the merge author by analyzeCommits.
-  for (const c of commits) {
-    if (!c.isMerge) continue;
-    try {
-      const cc = git(`diff-tree --cc --name-only --no-commit-id -r ${c.sha}`);
-      c.files = cc.split('\n').map((s) => s.trim()).filter(Boolean);
-    } catch (_) {
-      c.files = []; // can't compute → empty (the nightly full-history audit re-checks)
-    }
-  }
-  return { commits };
-}
-
-// #863-followup (finding #6): key ONLY on github_login. display_name is
-// builder-controlled — keying it let a malicious builder alias another login's
-// rank (last-write-wins poisoning). github_login is GitHub-controlled.
-function rowsToMap(rows) {
-  const map = {};
-  for (const b of rows || []) {
-    if (b.github_login) map[String(b.github_login).toLowerCase()] = b.rank;
-  }
-  return map;
-}
-
-// Where getBuildersRoster lives. It was carved out of src/bongos/db.js into the
-// lifecycle module (goal 1000010's per-domain db.js split) and this file was not
-// updated with it, so `--db` threw `db.getBuildersRoster is not a function` on every
-// run — for however long that carve has been landed. Kept as a named constant so the
-// next carve breaks a test (tests/main_audit_db_roster.mjs) rather than a deploy gate.
-const ROSTER_DB_MODULE = '../../modules/lifecycle/db.js';
-
-// API mode (default): for an Archon session / operator laptop. DB mode (--db):
-// for the droplet deploy gate, which has DB access but no GDS session — it reads
-// the roster straight from Postgres. db.js is lazy-required so importing this
-// module (e.g. in tests) never pulls in pg.
-async function fetchRankMap({ useDb = false } = {}) {
-  if (useDb) {
-    try {
-      const db = require(ROSTER_DB_MODULE);
-      if (typeof db.getBuildersRoster !== 'function') {
-        // The exact failure this file already shipped once, named rather than caught as a
-        // generic TypeError: a moved export reads identically to "no database" otherwise.
-        throw new Error(`${ROSTER_DB_MODULE} exports no getBuildersRoster — it has moved again`);
-      }
-      const roster = await db.getBuildersRoster({ staleHours: 24 });
-      const map = rowsToMap(roster.builders || roster);
-      if (Object.keys(map).length) return map;
-      console.error('main-audit: --db roster read returned NO builders — falling through to the API/public roster.');
-    } catch (e) {
-      console.error(`main-audit: --db roster read failed (${e.message}) — falling through to the API/public roster.`);
-    }
-    // FALL THROUGH, do not return {}. Returning an empty map here is the vacuous green
-    // this file's own comment warns about twelve lines down: with no ranks, every author
-    // resolves to null, no blocker can ever fire, and the gate reports success for the
-    // reason it was built to prevent. A `--db` gate that cannot reach Postgres is better
-    // served by the public leaderboard than by silence.
-  }
-  try {
-    const api = await cliClient({ allowUnauthenticated: true });
-    const res = await api.builders.getBuildersRoster();
-    if (res && res.ok) {
-      const map = rowsToMap(res.data?.builders || []);
-      if (Object.keys(map).length) return map;
-    }
-  } catch (_) { /* offline / no session — fall through to the public surface */ }
-  // Public fallback (task 1002612): CI has no GDS session, and with an empty
-  // rank map every author resolves to null so a blocker can NEVER fire — a
-  // vacuous green. github_login + rank are public facts on this platform (the
-  // status dashboard serves them), and the public leaderboard is server-
-  // authoritative, so resolving from it is as trustworthy as the roster route.
-  // Caveat: a zero-activity builder may be absent → resolves as UNRESOLVED
-  // ('review' finding), never as falsely-trusted.
-  try {
-    const res = await fetch(`${API_BASE}/api/bongos/public/leaderboard`);
-    if (res.ok) {
-      const data = await res.json();
-      return rowsToMap(data?.leaderboard || []);
-    }
-  } catch (_) { /* offline — map stays empty → unresolved authors */ }
-  return {};
-}
-
-// ---------- attestation pass (task 1001433) — I/O half ----------
-
-const GITHUB_API = 'https://api.github.com';
-
-// Read each head's statuses and keep the ones the trusted account attested. A head
-// whose statuses could not be read is reported as `unreadable`, never guessed at:
-// an unread head is not an unattested one, and treating it as attested would be
-// the vacuous pass this file keeps refusing.
-async function fetchAttestations(heads, { repo, token, trustedLogin, fetchImpl = fetch, apiBase = GITHUB_API } = {}) {
-  const attested = new Set();
-  const unreadable = [];
-  for (const sha of new Set(heads || [])) {
-    try {
-      const res = await fetchImpl(`${apiBase}/repos/${repo}/commits/${sha}/statuses?per_page=100`, {
-        headers: { Accept: 'application/vnd.github+json', Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28' },
-      });
-      if (!res.ok) { unreadable.push({ sha, reason: `HTTP ${res.status}` }); continue; }
-      if (isAttested(await res.json(), trustedLogin)) attested.add(sha);
-    } catch (e) {
-      unreadable.push({ sha, reason: e.message });
-    }
-  }
-  return { attested, unreadable };
-}
-
-function shaLines(out) {
-  return String(out || '').split('\n').map((s) => s.trim()).filter(Boolean);
-}
-
-// The whole pass for one audited range. Returns { ran: true, checked, findings }
-// or { ran: false, reason } — the caller prints either, and only
-// --require-attestation turns a pass that could not run into a non-zero exit.
-async function runAttestationPass(commits, range, { loginArg = null, env = process.env, gitImpl = git, fetchImpl } = {}) {
-  const protectedCommits = (commits || []).filter((c) => ppc.matchProtected(c.files || []).length > 0);
-  if (protectedCommits.length === 0) return { ran: true, checked: 0, findings: [] };
-  let remoteUrl = '';
-  try { remoteUrl = gitImpl('remote get-url origin').trim(); } catch (_) { /* no origin: env must name the repo */ }
-  const cfg = attestationConfig({ env, remoteUrl, loginArg });
-  if (!cfg.token) return { ran: false, reason: 'no GitHub token (set GITHUB_TOKEN or GH_TOKEN) to read commit statuses with' };
-  if (!cfg.repo) return { ran: false, reason: 'could not tell which GitHub repository this is (set GITHUB_REPOSITORY=owner/repo)' };
-
-  let mainline;
-  try {
-    mainline = new Set(shaLines(gitImpl(`rev-list --first-parent ${range}`)));
-  } catch (e) {
-    return { ran: false, reason: `git could not list the first-parent history of ${range}: ${e.message}` };
-  }
-  const merges = (commits || []).filter((c) => mainline.has(c.sha) && (c.parents || []).length > 1);
-  let headOf;
-  try {
-    headOf = mapIntroducingHeads(merges, (r) => shaLines(gitImpl(`rev-list ${r}`)));
-  } catch (e) {
-    return { ran: false, reason: `git could not trace which pull request brought each commit in: ${e.message}` };
-  }
-  const heads = protectedCommits.map((c) => headOf.get(c.sha) || c.sha);
-  const { attested, unreadable } = await fetchAttestations(heads, { ...cfg, ...(fetchImpl ? { fetchImpl } : {}) });
-  if (unreadable.length) {
-    const sample = unreadable.slice(0, 3).map((u) => `${short(u.sha)} (${u.reason})`).join(', ');
-    return { ran: false, reason: `could not read the commit statuses of ${unreadable.length} pull-request head(s): ${sample}` };
-  }
-  return { ran: true, ...analyzeAttestation(protectedCommits, { headOf, attested, trustedLogin: cfg.trustedLogin }), trustedLogin: cfg.trustedLogin };
-}
-
-function arg(name, fallback = null) {
-  const i = process.argv.indexOf(name);
-  return i >= 0 ? (process.argv[i + 1] && !process.argv[i + 1].startsWith('--') ? process.argv[i + 1] : true) : fallback;
-}
-
-// requestedRange — the range this run was asked to audit, or null for the default
-// window. An explicit --range wins; otherwise the <PREFIX>_AUDIT_RANGE env knob
-// (BONGOS_AUDIT_RANGE on a vanilla instance; the legacy OTB_AUDIT_RANGE is still
-// read, and warned about). The deploy gate and the CI workflow hand the range over
-// as --range, because neither can compute the branded env prefix from a shell
-// (task 1001441).
-function requestedRange(argValue, env = process.env) {
-  if (argValue && argValue !== true) return argValue;
-  return resolveEnv('AUDIT_RANGE', { env }) || null;
-}
-
-async function main() {
-  const verifyHead = process.argv.includes('--verify-head');
-  const doRevert = process.argv.includes('--revert');
-  const strict = process.argv.includes('--strict');
-  const useDb = process.argv.includes('--db');
-  // #863-followup (findings #8/#14): the verify-head window was a fixed
-  // HEAD~30..HEAD — a poisoned commit buried under >30 commits (merges inflate
-  // the count) or landed before a rebase/force-push could escape it. The deploy
-  // gate now passes the EXACT previously-deployed SHA as --range
-  // <prev-deployed-sha>..HEAD (deploy-main-audit-gate.sh), so the gate audits
-  // precisely what this deploy introduces — no window to slip under.
-  // Fallbacks widen to HEAD~200 (verify-head) / a deeper origin scan otherwise.
-  let range = requestedRange(arg('--range'));
-  if (!range) {
-    const ref = verifyHead ? 'HEAD' : 'origin/main';
-    if (!verifyHead) {
-      // Default: recent origin/main. Fetch first so we're auditing the truth.
-      try { git('fetch origin main'); } catch (_) { /* offline — audit local */ }
-    }
-    // Clamp to the ref's real first-parent depth. A fixed ~200 silently made
-    // this audit unrunnable on any repo with a shorter chain (task 1002566).
-    const depth = firstParentDepth(ref);
-    range = defaultRange(ref, depth);
-    if (!range) {
-      console.error(
-        `main-audit: DID NOT RUN — cannot build a default range for ${ref}: its first-parent history is `
-        + `${Number.isFinite(depth) ? `${depth} commit(s)` : 'unreadable'} deep. `
-        + `Pass --range <A..B> or set ${envPrefix()}_AUDIT_RANGE. This is a check that did not execute, not a clean audit.`
-      );
-      cliExit(2);
-      return;
-    }
-  }
-
-  const parsed = parseCommits(range);
-  if (parsed.error) {
-    console.error(`main-audit: ${parsed.error}`);
-    cliExit(2);
-    return;
-  }
-  const rankMap = await fetchRankMap({ useDb });
-  if (Object.keys(rankMap).length === 0) {
-    // --require-roster (task 1002612): the CI caller refuses to "pass" an audit
-    // that could not have failed. With no ranks, every author is unresolved and
-    // a blocker can never fire — that is a check that did not execute, not a
-    // clean audit (the same false-green shape parseCommits guards against).
-    if (process.argv.includes('--require-roster')) {
-      console.error('main-audit: DID NOT RUN — the roster is unavailable (offline / no session / public leaderboard unreachable). An empty rank map can never produce a blocker, so exiting green would be a vacuous pass. Fix connectivity or drop --require-roster for a best-effort local read.');
-      cliExit(2);
-      return;
-    }
-    console.error('main-audit: WARNING — could not load the GDS roster (offline / insufficient rank / no DB). Authors will be unresolved; run as a Metic+ builder or with --db (on the droplet) for a definitive audit.');
-  }
-
-  const result = analyzeCommits(parsed.commits, rankMap, { strict });
-  // Task 1001433: the attestation pass. FLAG-ONLY — its findings are 'review' and
-  // never reach `hardFail`; the one thing it can do to the exit code is report
-  // that it did not run, and only when the caller asked with --require-attestation.
-  const loginArg = arg('--attest-login');
-  const attestation = process.argv.includes('--no-attestation')
-    ? { ran: false, skipped: true, reason: 'skipped (--no-attestation)' }
-    : await runAttestationPass(parsed.commits, range, { loginArg: loginArg === true ? null : loginArg });
-  const findings = result.findings.concat(attestation.findings || []);
-
-  console.log(`\nMain audit (SEC #863) — range ${range}, ${parsed.commits.length} commit(s)`);
-  if (attestation.ran) {
-    console.log(`  attestation (task 1001433, flag-only): ${attestation.checked} permission-sensitive commit(s) checked, ${attestation.findings.length} without the server's '${ATTEST_CONTEXT}' mark.`);
-  } else {
-    console.log(`  attestation (task 1001433, flag-only): DID NOT RUN — ${attestation.reason}.`);
-  }
-  const attestationMissing = !attestation.ran && !attestation.skipped && process.argv.includes('--require-attestation');
-  if (findings.length === 0) {
-    console.log('  ✓ clean — no sub-Metic edits to permission-sensitive paths.\n');
-    cliExit(attestationMissing ? 2 : 0);
-    return;
-  }
-  for (const f of findings) {
-    const tag = f.severity === 'blocker' ? '\x1b[31m[BLOCKER]\x1b[0m' : '\x1b[33m[review]\x1b[0m';
-    console.log(`  ${tag} ${f.summary}`);
-  }
-  if (doRevert) {
-    const blockers = result.findings.filter((f) => f.severity === 'blocker');
-    if (blockers.length) {
-      console.log('\nRevert plan (review before running — an Archon decides):');
-      for (const f of blockers) console.log(`  git revert --no-edit ${f.sha}   # ${f.author} / ${f.rank}`);
-    }
-  }
-  console.log('');
-
-  // verify-head is the deploy gate: any blocker (and, unless allowed, any
-  // unresolved author) must stop the deploy.
-  if (verifyHead) {
-    cliExit(result.hardFail ? 1 : 0);
-    return;
-  }
-  // report mode: non-zero on a real blocker so CI can fail. A blocker outranks an
-  // attestation pass that did not run: 1 is a definite answer, 2 is "no answer".
-  cliExit(result.hardFail ? 1 : (attestationMissing ? 2 : 0));
-}
-
-if (require.main === module) {
-  main().catch((e) => {
-    console.error(`main-audit: ${e.message}`);
-    cliExit(2);
-  });
-}
-
-module.exports = {
-  analyzeCommits, resolveRank, parseCommits, rowsToMap,
-  clampWindow, defaultRange, firstParentDepth, DEFAULT_WINDOW, requestedRange,
-  // Exported so a test can assert the address is LIVE without a database. The --db
-  // path was dead for as long as the db.js carve has been landed precisely because
-  // nothing checked that this require target still exports what it is called for.
-  ROSTER_DB_MODULE, fetchRankMap,
-  // The attestation pass (task 1001433): pure halves + the I/O half with its seams.
-  ATTEST_CONTEXT, mapIntroducingHeads, isAttested, analyzeAttestation, attestationConfig,
-  fetchAttestations, runAttestationPass,
-};
+require('../bongos/forwarder.js').forward(module, 'main-audit.js');