@golden-frijoles/kit 0.5.4 → 0.7.0

package/dist/lib/secret-guard.mjs

@@ -0,0 +1,212 @@
+// secret-guard.mjs — never POST a reviewer's reply that carries one of this machine's secrets.
+//
+// ── Why this exists (distribute-what-we-use S1, the fresh pr-reviewer's round 2 on #188) ──────────────
+// A reviewer CLI is fed an attacker-controllable diff. The rail removes every tool it can (Vibe runs with
+// all tools disabled, Devin is refused, Claude runs `--tools ""`, codex runs `--sandbox read-only
+// --ignore-user-config`), but codex's read-only sandbox still lets it READ host files, and there is no
+// flag that stops that. An injected diff can therefore ask for `cat .env.local`, and cross-review would
+// post the answer as a comment — on a public repo, to anyone.
+//
+// Refusing codex would leave no working reviewer, so the CHANNEL is closed instead: before anything is
+// posted, the reply is checked for (1) any value from the project's own env files or from this process's
+// secret-named env vars, and (2) the shapes of the credentials a developer machine commonly holds. A match
+// fails the run and posts nothing; the reply is printed locally (it is the operator's own machine) with
+// every match redacted, so a false positive costs a look, never a leak.
+//
+// Deliberately NOT a general secret scanner: GitHub push protection and CodeQL own that for commits. This
+// guards one path — a model's text on its way to a PR comment. Zero npm deps.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** Shorter values are too likely to occur in ordinary review prose ("development", a port, a flag). */
+export const MIN_SECRET_LENGTH = 16;
+
+/** Credential shapes with a distinctive prefix — low false-positive by construction. */
+export const SECRET_SHAPES = Object.freeze([
+  { name: 'private key block', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+  { name: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{30,}\b/ },
+  { name: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{40,}\b/ },
+  { name: 'OpenAI/Anthropic-style key', re: /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{24,}\b/ },
+  { name: 'Slack token', re: /\bxox[abposr]-[A-Za-z0-9-]{10,}\b/ },
+  { name: 'Slack webhook', re: /hooks\.slack\.com\/services\/[A-Za-z0-9/]{20,}/ },
+  { name: 'Telegram bot token', re: /\b\d{8,10}:[A-Za-z0-9_-]{35}\b/ },
+  { name: 'AWS access key id', re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { name: 'Supabase access token', re: /\bsbp_[a-f0-9]{40}\b/ },
+  { name: 'npm token', re: /\bnpm_[A-Za-z0-9]{36}\b/ },
+  { name: 'Supabase secret key', re: /\bsb_secret_[A-Za-z0-9_-]{16,}\b/ },
+  // A signed JWT (header.payload.signature, both JSON parts base64url `eyJ…`): service-role keys are JWTs.
+  // An opaque base64 run long enough to carry a key. Real reviews quote code, not 80-char blobs; this is
+  // defence in depth against an injected "encode it" (the author-trust check below is the real control).
+  { name: 'opaque base64 blob', re: /[A-Za-z0-9+/]{80,}={0,2}/ },
+  { name: 'JWT', re: /\beyJ[\w-]{10,}\.eyJ[\w-]{10,}\.[\w-]{10,}/ },
+]);
+
+const SECRET_KEY_RE = /(KEY|TOKEN|SECRET|PASSWORD|PASS|PRIVATE|CREDENTIAL|WEBHOOK|DSN)/i;
+
+/** `KEY=value` pairs from a dotenv-shaped text; quotes stripped, comments and blanks ignored. */
+export function parseEnvValues(text) {
+  const out = [];
+  for (const line of String(text || '').split('\n')) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const raw = m[2].trim();
+    // A quoted value ends at its closing quote (a trailing `# comment` is dropped); an unquoted one ends
+    // before ` #` (dotenv's inline-comment rule).
+    const q = /^(['"])(.*?)\1(?:\s+#.*)?$/.exec(raw);
+    const v = q ? q[2] : raw.replace(/\s+#.*$/, '').trim();
+    if (v) out.push({ key: m[1], value: v });
+  }
+  return out;
+}
+
+const ENV_FILE_RE = /^\.env(?:rc|\..+)?$/;
+const SKIP_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.vercel', '.turbo']);
+
+/**
+ * Every `.env*` file (and `.envrc`) at the root and up to `depth` directories below it — a monorepo keeps
+ * its app's secrets in `apps/<app>/.env.local`, not at the root. `.example` files are templates, not secrets.
+ */
+export function envFiles(root, { depth = 2, list = readdirSync, exists = existsSync } = {}) {
+  const out = [];
+  const walk = (dir, left) => {
+    let names;
+    try {
+      names = exists(dir) ? list(dir, { withFileTypes: true }) : [];
+    } catch {
+      return;
+    }
+    for (const d of names) {
+      const name = typeof d === 'string' ? d : d.name;
+      const isDir = typeof d === 'string' ? false : d.isDirectory();
+      if (isDir) {
+        if (left > 0 && !SKIP_DIRS.has(name)) walk(join(dir, name), left - 1);
+      } else if (ENV_FILE_RE.test(name) && !/\.example$/.test(name)) out.push(join(dir, name));
+    }
+  };
+  walk(root, depth);
+  return out;
+}
+
+/**
+ * The operator's own credential stores, by path under $HOME. A collaborator's diff can still steer a reviewer
+ * into reading one of these (codex's read-only sandbox reads the whole disk), and their values often have no
+ * distinctive shape (an AWS secret access key is 40 plain characters) — so their VALUES are matched verbatim.
+ * Only `key = value` / `key: value` style lines are read; nothing is stored or printed.
+ */
+export const HOME_CREDENTIAL_FILES = Object.freeze([
+  '.aws/credentials',
+  '.netrc',
+  '.npmrc',
+  '.pypirc',
+  '.config/gh/hosts.yml',
+  '.docker/config.json',
+  '.git-credentials',
+  '.codex/auth.json',
+]);
+
+/** Pure: every long value on a `key = value`, `key: value`, `"key": "value"` or `login x password y` line. */
+export function credentialValues(text) {
+  const out = [];
+  for (const line of String(text || '').split('\n')) {
+    // The value after the LAST `=`/`:` on the line (`//registry.npmjs.org/:_authToken=npm_…` keeps only the
+    // token), and the word after `password` (netrc).
+    // Trailing base64 `=` padding is part of the value (`_auth=…==`, docker "auth": "…="); a URL remainder
+    // (`registry=https://…` → `//registry…`) is configuration, not a secret (round 5 on #188).
+    const kv = /[=:]\s*"?([^\s"',=:]{16,}={0,2})"?\s*,?\s*$/.exec(line);
+    // Skip ONLY a URL's `scheme://` remainder; a base64 value can itself start with `//` (round 6).
+    if (kv && !(kv[1].startsWith('//') && /https?:$/i.test(line.slice(0, kv.index + 1)))) out.push(kv[1]);
+    const pw = /\bpassword\s+(\S{16,})/.exec(line);
+    if (pw) out.push(pw[1]);
+    const url = /https?:\/\/[^:\s]+:([^@\s]{16,})@/.exec(line);
+    if (url) out.push(url[1]);
+  }
+  return out;
+}
+
+/**
+ * The secret VALUES this machine could leak for this project: every value in the root's `.env*` files (a
+ * dotenv file is secrets by convention; nested ones too, see envFiles), plus this process's env vars whose NAME says secret. Values
+ * shorter than MIN_SECRET_LENGTH are skipped. Unreadable files are skipped — could not look is not a leak.
+ */
+export function collectSecretValues({
+  root = process.cwd(),
+  env = process.env,
+  home = homedir(),
+  read = readFileSync,
+  list = readdirSync,
+  exists = existsSync,
+} = {}) {
+  const values = new Set();
+  for (const rel of home ? HOME_CREDENTIAL_FILES : []) {
+    try {
+      const p = join(home, rel);
+      if (exists(p)) for (const v of credentialValues(read(p, 'utf8'))) values.add(v);
+    } catch {
+      /* unreadable: skip */
+    }
+  }
+  for (const file of envFiles(root, { list, exists })) {
+    try {
+      for (const { value } of parseEnvValues(read(file, 'utf8')))
+        if (value.length >= MIN_SECRET_LENGTH) values.add(value);
+    } catch {
+      /* unreadable: skip */
+    }
+  }
+  for (const [k, v] of Object.entries(env || {}))
+    if (SECRET_KEY_RE.test(k) && typeof v === 'string' && v.length >= MIN_SECRET_LENGTH) values.add(v);
+  return [...values];
+}
+
+/**
+ * Pure: which secrets does `text` carry? Returns `{ leaks: [{kind, name}], redacted }`, where `redacted`
+ * is `text` with every match replaced by `[REDACTED <name>]`. Names only — never the value itself.
+ */
+export function findSecretLeaks(text, { values = [] } = {}) {
+  let redacted = String(text || '');
+  const leaks = [];
+  for (const v of values) {
+    if (v && redacted.includes(v)) {
+      leaks.push({ kind: 'env-value', name: `an env value (${v.length} chars)` });
+      redacted = redacted.split(v).join('[REDACTED env value]');
+    }
+  }
+  for (const { name, re } of SECRET_SHAPES) {
+    const g = new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`);
+    if (g.test(redacted)) {
+      leaks.push({ kind: 'shape', name });
+      redacted = redacted.replace(new RegExp(re.source, g.flags), `[REDACTED ${name}]`);
+    }
+  }
+  return { leaks, redacted };
+}
+
+// ── Who wrote the diff decides whether a reviewer may read it at all (codex security lens on #188) ─────
+// No reviewer flag stops codex READING host files, and no string matcher catches a secret the model was
+// told to encode. What closes the realistic threat on a public repo is the input: a hostile diff comes from
+// someone without write access (a fork PR). So cross-review refuses such a PR unless the operator says so.
+
+/** Repo permissions that can already push code here — their diff is not a new attacker. */
+export const TRUSTED_PERMISSIONS = Object.freeze(['admin', 'maintain', 'write']);
+
+/**
+ * Pure: may a reviewer read this PR? `permission` is the author's repo permission as GitHub reports it
+ * (`null` when it could not be read — treated as untrusted: could-not-look must not open the door).
+ */
+export function decideAuthorTrust({ permission, allowUntrusted = false }) {
+  if (TRUSTED_PERMISSIONS.includes(permission)) return { ok: true, why: `author has ${permission} access` };
+  if (allowUntrusted)
+    return {
+      ok: true,
+      why: `author has ${permission ?? 'unknown'} access — allowed by --allow-untrusted-author`,
+    };
+  return {
+    ok: false,
+    why:
+      `the PR author has ${permission ?? 'UNKNOWN'} access to this repo. A reviewer fed an outsider's diff can be ` +
+      `steered by it into reading this machine's files; review it only after reading the diff yourself, then ` +
+      `re-run with --allow-untrusted-author.`,
+  };
+}

package/dist/lib/session-journal.mjs

@@ -0,0 +1,99 @@
+// session-journal.mjs — pure builder/parser for the session-continuity intent journal (README.md D2).
+// Shared by scripts/session-note.mjs (writer) and scripts/session-resume.mjs (reader) so the line format
+// has exactly one definition. Zero I/O in this file on purpose — it's the pure seam both scripts unit-test
+// against without touching git/gh/a branch.
+//
+// The journal is APPEND-ONLY and intent-only (D2): timestamp, session label, kind, one line of text,
+// optional refs. No status field, no "done" marker, no update/delete — the history is the point. It lives
+// on `claude/session-journal` via scripts/lib/log-branch.mjs (reused unchanged), one JSON object per line
+// (JSONL, matching standup.mjs's standups.log convention already on the same kind of `claude/`-branch log).
+//
+// JOURNAL_PATH is a flat filename — log-branch.mjs's writeLogToBranch requires this (git mktree only
+// builds a single-level tree; a nested path fails loud there, not here).
+
+export const JOURNAL_BRANCH = 'claude/session-journal';
+export const JOURNAL_PATH = 'session-journal.jsonl';
+
+export const VALID_KINDS = ['decision', 'doing', 'next', 'blocked', 'declined'];
+
+export function isValidKind(kind) {
+  return VALID_KINDS.includes(kind);
+}
+
+// A stable per-day label so entries from the same calendar day (UTC) group without an agent having to
+// invent or remember one. `now` is injectable for tests.
+export function defaultSessionLabel(now = new Date()) {
+  return now.toISOString().slice(0, 10);
+}
+
+// "PR#312,D4" → ["PR#312", "D4"]. Accepts an array too (already-split callers), undefined/empty → [].
+export function parseRefs(refs) {
+  if (!refs) return [];
+  if (Array.isArray(refs)) return refs.map((r) => String(r).trim()).filter(Boolean);
+  return String(refs)
+    .split(',')
+    .map((r) => r.trim())
+    .filter(Boolean);
+}
+
+// Pure line-builder — THE unit under test, no I/O (D1's "pure line-builder unit-tested separately from
+// the I/O" acceptance). Throws on a bad kind or empty text — those are usage errors the CLI turns into a
+// loud exit 1, distinct from D1's "failed append" soft-fail (that's about the I/O call, not this).
+export function buildJournalEntry({ kind, text, session, refs, ts, now } = {}) {
+  if (!isValidKind(kind)) {
+    throw new Error(`invalid --kind "${kind}" — must be one of: ${VALID_KINDS.join(' | ')}`);
+  }
+  // Normalise embedded line breaks to a single space. JSON.stringify escapes them so the FILE stays
+  // one-line-per-entry, but the rendered report prints `text` verbatim — so `$'decision A\nfake entry'`
+  // displayed as two journal lines, one of which never happened. A journal that can be made to show
+  // fabricated entries is worse than no journal, and this is an intent record a later agent trusts.
+  const trimmed = (text || '').replace(/[\r\n]+/g, ' ').trim();
+  if (!trimmed) {
+    throw new Error('journal text must not be empty');
+  }
+  return {
+    ts: ts || (now || new Date()).toISOString(),
+    session: session || defaultSessionLabel(now),
+    kind,
+    text: trimmed,
+    refs: parseRefs(refs),
+  };
+}
+
+// One JSON line + trailing newline — the exact bytes appended to the journal file.
+export function serializeEntry(entry) {
+  return `${JSON.stringify(entry)}\n`;
+}
+
+// Parses journal file content into entries, oldest→newest. A single corrupt/partial line is DROPPED, not
+// fatal — an append-only log must survive a bad line (e.g. a torn write) rather than making the whole
+// journal unreadable. Returns [] for empty/null content (the "no journal yet" case).
+export function parseJournal(content) {
+  if (!content) return [];
+  return content
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch {
+        return null;
+      }
+    })
+    .filter((e) => e && typeof e === 'object');
+}
+
+// The last N entries, still in chronological (oldest→newest) order — D3's "then the last N journal
+// lines" section reads top-to-bottom as a mini-timeline, not most-recent-first.
+export function lastNEntries(entries, n) {
+  if (!Array.isArray(entries) || n <= 0) return [];
+  return entries.slice(Math.max(0, entries.length - n));
+}
+
+// One human-readable line per entry, for resume's "last N" section and any console echo.
+export function formatEntry(entry) {
+  const refs = entry.refs && entry.refs.length ? ` [${entry.refs.join(', ')}]` : '';
+  const session = entry.session ? ` (${entry.session})` : '';
+  return `[${entry.kind}] ${entry.ts}${session} — ${entry.text}${refs}`;
+}

package/dist/review-config.json

@@ -0,0 +1,25 @@
+{
+  "_about": "Which PRs get which review layers (ways-of-work-lean-pass D5/D7). reviewScope: 'every-pr' = the fresh reviewer + one external general pass on every non-trivial PR; 'security-paths-only' = only when a securityPaths glob is touched (or the body declares risk: high). securityPaths ALSO decides the lean external security lens in every scope. TEMPLATE FILL-IN: replace these globs with your project's real money/auth/migration paths. NOTE: a basename glob like `**/*webhook*` matches a FILE named for it; in an App Router every route file is `route.ts`, so each basename glob is paired with a `/**` directory form.",
+  "reviewScope": "every-pr",
+  "securityPaths": [
+    "**/auth/**",
+    "**/*webhook*",
+    "**/*webhook*/**",
+    "**/checkout/**",
+    "**/payments/**",
+    "**/*stripe*",
+    "**/*stripe*/**",
+    "middleware.ts",
+    "**/middleware.ts",
+    "supabase/migrations/*.sql",
+    "**/*secret*",
+    "**/*secret*/**",
+    ".github/workflows/**",
+    ".claude/settings.json",
+    "scripts/review-route.mjs",
+    "scripts/review-config.json",
+    "scripts/cross-review.mjs",
+    "scripts/lib/review-guard.mjs",
+    "golden-frijoles.config.json"
+  ]
+}

package/dist/review-route.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+// review-route.mjs — WHICH families review this PR. One rule, not a table.
+//
+// ── The rule ──────────────────────────────────────────────────────────────────────────────────────
+//   The highest-preference family that did NOT build the diff runs the general pass.
+//   If the PR touches a security path, the NEXT eligible family runs the lean security lens.
+//   The fresh `pr-reviewer` subagent runs too, in whatever scope the project's review-config.json sets.
+//
+// That is the whole policy. It replaces a 273-line router with a four-row table, a two-passes-per-PR
+// count, a HIGH-only branch on the fresh reviewer, and the REFUND-ASK / --fallback-after / DARK-layer
+// protocol (ways-of-work-lean-pass S2.5 + S2.8). A capped family now simply falls to the next one:
+// external quota is not worth a human round-trip when the next family is one line away.
+//
+// ── The two guards that survive, and why ──────────────────────────────────────────────────────────
+//   1. A family NEVER reviews its own diff. With several families building, the default agent flag on a
+//      Codex-built diff is Codex reviewing Codex — a same-family pass wearing a cross-family label, and
+//      a silent downgrade nothing in a hand-driven flow would catch.
+//   2. The security lens prefers a DIFFERENT family from the general pass, so the two external reads
+//      bring different blind spots. With only one family available it runs both prompts and SAYS SO —
+//      a missing layer that reads like a clean one is worse than no layer.
+//
+// Usage:
+//   node scripts/review-route.mjs --builder claude <PR#> [--repo owner/repo] [--security] [--json]
+//                                  [--exclude <family>]   # a family is quota-capped: route past it
+//
+// `--security` forces the lens on; without it the trigger is the PR's own changed paths
+// (scripts/review-config.json → securityPaths), which is what makes it un-skippable by judgement.
+//
+// Zero npm deps — Node 18+. Pure policy exported for node:test; the CLI is a thin shell.
+
+import { spawnSync } from 'node:child_process';
+import { writeSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { die, need, hasCmd, AGENT_BIN } from './lib/cross-agent-cli.mjs';
+import { changedFileCount, decideSecurityPass, parseReviewConfig } from './lib/review-guard.mjs';
+import { readSection } from './lib/config.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Every family that can build — which is exactly why guard 1 exists. */
+export const BUILDERS = ['claude', 'codex', 'agy', 'vibe'];
+
+/**
+ * Preference order. One editable list, not roles hardcoded per pass.
+ * codex first: the strongest observed review signal here. agy and vibe are independent quota pools.
+ * claude LAST — not because it reviews badly, but because Claude capacity is usually the thing BUILDING.
+ */
+export const PREFERENCE = ['codex', 'agy', 'vibe', 'claude'];
+
+/** `cross-review.mjs --agent` takes the long name for antigravity; the rest match. */
+export const AGENT_FLAG = { codex: 'codex', agy: 'antigravity', vibe: 'vibe', claude: 'claude' };
+
+/**
+ * THE POLICY. Pure — no I/O, no availability probing — so it reads as one decision and is pinned by tests.
+ * Returns { general, security, notes }. `security` is null when the lens is not triggered.
+ */
+export function planReview({ builder, available = PREFERENCE, securityPass = false }) {
+  if (!BUILDERS.includes(builder))
+    throw new Error(`unknown builder '${builder}' (expected: ${BUILDERS.join(' | ')})`);
+  const eligible = PREFERENCE.filter((f) => f !== builder && available.includes(f));
+  const general = eligible[0] ?? null;
+  // Prefer a different family for the security lens; fall back to the general one rather than skipping.
+  const security = securityPass ? (eligible[1] ?? general) : null;
+
+  const notes = [];
+  if (general)
+    notes.push(
+      `${general} runs the general pass because ${builder} built it — a family never reviews its own diff.`
+    );
+  else
+    notes.push(
+      `NO external family is available: the cross-family layer is DARK for this PR. Say so in the PR body rather than letting a missing layer look like a clean one.`
+    );
+  if (securityPass) {
+    if (security && security !== general)
+      notes.push(
+        `${security} runs the security lens — a different family from the general pass, so the two reads have different blind spots.`
+      );
+    else if (security)
+      notes.push(
+        `${security} runs BOTH passes (no second family available) — two prompts, one family. Record that in the PR body: family independence is short here.`
+      );
+    else notes.push(`The security lens is triggered but no family can run it. Say so in the PR body.`);
+  }
+  notes.push(
+    'The fresh `pr-reviewer` subagent runs as well — context independence is a different axis from family independence.'
+  );
+  return { builder, general, security, notes };
+}
+
+/** The exact commands to run, in order. Pure. */
+export function renderPlan(plan, pr, repo) {
+  // `--builder` rides along so cross-review's pairing guard (and its codex→agy heal re-check) fire in
+  // normal use, not only when someone remembers to pass it (distribute-what-we-use S1, pr-reviewer B3).
+  const arg = (f) =>
+    `node scripts/cross-review.mjs ${pr}${repo ? ` --repo ${repo}` : ''} --agent ${AGENT_FLAG[f]} --builder ${plan.builder}`;
+  const l = [
+    `Review plan — PR #${pr}${repo ? ` (${repo})` : ''}`,
+    `  built by:       ${plan.builder}`,
+    `  general pass:   ${plan.general || '⚠ NONE AVAILABLE'}`,
+    `  security lens:  ${plan.security || 'not triggered'}`,
+    '',
+  ];
+  for (const n of plan.notes) l.push(`  · ${n}`);
+  l.push('');
+  l.push('  Run:');
+  if (plan.general) l.push(`    ${arg(plan.general)}`);
+  if (plan.security) l.push(`    ${arg(plan.security)} --lens security`);
+  l.push(`    then: use the pr-reviewer subagent on PR #${pr}`);
+  return l.join('\n');
+}
+
+/** Changed files + body for the security trigger. Degrades to "not triggered" only with a loud note. */
+function prFacts(pr, repo, deps = {}) {
+  const run = deps.spawn ?? spawnSync;
+  const args = ['pr', 'view', String(pr), '--json', 'files,body'];
+  if (repo) args.push('--repo', repo);
+  const r = run('gh', args, { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  if (r.status !== 0) return null;
+  try {
+    const j = JSON.parse(r.stdout);
+    return { files: j.files || [], body: j.body || '' };
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  let builder = null;
+  let pr = null;
+  let repo = null;
+  let json = false;
+  let forceSecurity = false;
+  let tierIgnored = false;
+  const excluded = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--builder') builder = need(argv[++i], '--builder');
+    else if (a === '--repo') repo = need(argv[++i], '--repo');
+    else if (a === '--json') json = true;
+    else if (a === '--security') forceSecurity = true;
+    else if (a === '--tier') {
+      // Accepted so an old invocation does not die, but SAID OUT LOUD: the tier no longer selects
+      // reviewers, and silently ignoring it would let an old `--tier high` call believe it had asked
+      // for the security lens.
+      argv[++i];
+      tierIgnored = true;
+    } else if (a === '--exclude') excluded.push(need(argv[++i], '--exclude'));
+    else if (!a.startsWith('-') && pr === null) pr = a;
+    else die(`unknown argument '${a}'`);
+  }
+  if (!builder) die('--builder is required (who wrote the diff): ' + BUILDERS.join(' | '));
+  if (!pr) die('a PR number is required');
+  if (!/^\d+$/.test(String(pr))) die(`PR number must be numeric, got '${pr}'.`);
+  if (!BUILDERS.includes(builder)) die(`unknown --builder '${builder}' (expected: ${BUILDERS.join(' | ')})`);
+
+  // The `review` section of golden-frijoles.config.json over scripts/review-config.json (D9).
+  const { raw: reviewRaw, present: reviewPresent } = readSection('review', {
+    legacyPath: join(__dirname, 'review-config.json'),
+    onLegacyError: (_p, e) => {
+      throw e;
+    },
+  });
+  if (!reviewPresent)
+    die('scripts/review-config.json not found, and golden-frijoles.config.json has no review section');
+  const config = parseReviewConfig(reviewRaw);
+  let securityPass = forceSecurity;
+  let trigger = forceSecurity ? 'forced with --security' : null;
+  if (!forceSecurity) {
+    const facts = prFacts(pr, repo);
+    if (!facts && hasCmd('gh')) {
+      // gh is installed and still could not read the PR: a wrong number or --repo, expired auth, the
+      // network. A route printed for a PR that may not exist is worse than stopping (#189 review, S1).
+      die(
+        `could not read PR #${pr}'s changed files — the security trigger is UNKNOWN, not false. Check the PR ` +
+          'number and --repo, and `gh auth status`; re-run when gh works, or pass --security.'
+      );
+    } else if (!facts) {
+      // No gh at all — a stranger's machine. UNKNOWN is not "no security path", but refusing to print a route
+      // hides the DARK state the kickoff needs to explain, so render it with the lens forced instead.
+      securityPass = true;
+      trigger =
+        `could not look: GitHub CLI could not read PR #${pr}'s changed files — install GitHub CLI ` +
+        '(https://cli.github.com), then `gh auth login`. Security trigger is UNKNOWN; lens requested conservatively.';
+    } else {
+      const decision = decideSecurityPass({
+        files: facts.files,
+        body: facts.body,
+        securityPaths: config.securityPaths,
+        totalFiles: changedFileCount({ pr, repo }),
+      });
+      securityPass = decision.run;
+      trigger = decision.reason;
+    }
+  }
+  // `hasCmd` says INSTALLED, not UNCAPPED — a quota-capped CLI is present and answers `--version`.
+  // There is no way to know a family is capped without spending a run on it, so the fallback is
+  // operator-driven and one command long: re-run with `--exclude <family>` and the next one is routed.
+  // (cross-review.mjs additionally self-heals the common case: a dead codex token falls to agy mid-run.)
+  const available = PREFERENCE.filter((f) => hasCmd(AGENT_BIN[AGENT_FLAG[f]]) && !excluded.includes(f));
+  const plan = planReview({ builder, available, securityPass });
+  if (tierIgnored) {
+    process.stderr.write(
+      '⚠ --tier is ignored: the risk tier no longer selects reviewers. The security lens is triggered by ' +
+        'the changed paths (scripts/review-config.json) or a `risk: high` PR body — pass --security to force it.\n'
+    );
+  }
+  if (json) {
+    writeSync(
+      1,
+      `${JSON.stringify({ pr, repo, trigger, reviewScope: config.reviewScope, ...plan }, null, 2)}\n`
+    );
+    return;
+  }
+  writeSync(
+    1,
+    `${renderPlan(plan, pr, repo)}\n\n  security trigger: ${trigger}\n  review scope:     ${config.reviewScope}\n`
+  );
+}
+
+// realpath on both sides: through a symlinked path a plain compare is false and the script exits 0 having
+// done nothing (#189 review).
+const isMain = (() => {
+  try {
+    return (
+      !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+    );
+  } catch {
+    return false;
+  }
+})();
+if (isMain) main();