@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/main-audit.js

@@ -0,0 +1,625 @@
+#!/usr/bin/env node
+// scripts/bongos/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/bongos/main-audit.js                       # audit last 50 on origin/main
+//   node scripts/bongos/main-audit.js --range A..B          # audit an explicit range
+//   node scripts/bongos/main-audit.js --verify-head         # deploy gate: HEAD~30..HEAD
+//   node scripts/bongos/main-audit.js --verify-head --db    # deploy gate on the droplet (rank from Postgres)
+//   node scripts/bongos/main-audit.js --revert              # also print `git revert` plan
+//   node scripts/bongos/main-audit.js --strict              # also block on unresolved authors
+//   node scripts/bongos/main-audit.js --db                  # resolve ranks from Postgres instead of the API
+//   node scripts/bongos/main-audit.js --require-roster      # CI: an empty roster is a loud DID-NOT-RUN, not a vacuous green
+//   node scripts/bongos/main-audit.js --require-attestation # CI: an attestation pass that could not run exits 2
+//   node scripts/bongos/main-audit.js --attest-login <login> # the account the server posts statuses as (default: the repo owner)
+//   node scripts/bongos/main-audit.js --no-attestation      # skip the attestation pass
+//   GH_TOKEN=$(gh auth token) node scripts/bongos/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).
+
+'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,
+};