@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/exec-path-guard.js

@@ -0,0 +1,564 @@
+#!/usr/bin/env node
+// scripts/bongos/exec-path-guard.js — server-side code must not EXECUTE a path it does
+// not statically control (task 1003371, audit ref B50, 2026-08-29 security audit).
+//
+// THE BLIND SPOT THIS EXISTS TO CLOSE. Every other gate asks who may CALL something:
+// route-rank-check.js checks who may reach a route, fitness Check 4 checks the gates
+// exist, permission-path-check.js checks who may EDIT a file. Nothing asked what the
+// server RUNS, or out of whose tree. All three CRITICALs in the 2026-08-29 audit lived
+// in that one gap, and none of them were caught by anything.
+//
+// THE DEFECT SHAPE. modules/lifecycle/conflict-resolve.js clones a builder's branch to
+// a temp dir and runs `execFile(process.execPath, [path.join(work, rel)])` — a script
+// out of the CLONE, with the live server's DATABASE_URL and BUILDER_SECRET_KEY
+// inherited. The path is assembled from `work`, a runtime value, so no amount of
+// reading the call site tells you what binary actually runs.
+//
+// THE RULE. An executed path must be STATICALLY ROOTED AT THE CORE CHECKOUT: built only
+// from string literals, __dirname/__filename, process.execPath, and module-level consts
+// that are themselves so built. A path that reaches the call through a parameter, a
+// let, or any other runtime value is flagged. That is a deliberately blunt rule — it
+// cannot tell a safe runtime path from an unsafe one, so it insists the question never
+// arises. Where a runtime path is genuinely correct, EXEMPTIONS below records why, and
+// the exemption is the review.
+//
+// WHY STATIC AND NOT A RUNTIME GUARD. The dangerous call already ran with full
+// privilege by the time a runtime check could see it, and the sites are few and rarely
+// touched — this is exactly the shape a build-time scan handles well.
+//
+// THE RESIDUAL ASSUMPTION, stated so it can be re-checked rather than rediscovered.
+// This is a LINE/BRACKET scan, not a parse (the repo ships no JS parser — see
+// route-rank-check.js, which reads route files the same way for the same reason). It
+// resolves child_process bindings per file, so a regex's `.exec()` is never mistaken
+// for the child_process one, and it balances brackets to read a multi-line call. It
+// does NOT follow a value across files or through a function return. A path laundered
+// through a helper in another module would read as a bare identifier here and be
+// FLAGGED, not missed — the scan fails toward noise, never toward silence.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const NAME = 'no server-side exec/spawn runs a path that is not statically rooted at the core checkout (task 1003371)';
+
+// The child_process members that start a process. `fork` included: it runs a module
+// path the same way execFile does.
+const SPAWNERS = new Set([
+  'exec', 'execSync', 'execFile', 'execFileSync', 'spawn', 'spawnSync', 'fork',
+]);
+
+// Identifiers an executed path may be built from without the scan knowing more. These
+// are fixed at module load and cannot be steered by a request or a branch.
+const STATIC_ROOTS = new Set([
+  '__dirname', '__filename', 'process', 'path', 'require',
+  'String', 'Number', 'JSON', 'Boolean', 'Array', 'Object',
+]);
+
+// Reviewed exemptions. Each is a call the scan flags where a runtime path is the
+// correct behaviour, with the reason it is safe. An entry is a REVIEW, not a mute:
+// adding one is the moment to argue the case, which is why `why` is asserted non-empty
+// by tests/exec_path_guard.mjs. Keyed `<repo-relative file>:<line>` is deliberately
+// brittle — a line shift re-opens the review rather than carrying a stale approval.
+const EXEMPTIONS = [
+  {
+    at: 'modules/lifecycle/conflict-resolve.js:382',
+    why: 'THE site this check was written for (audit ref B1), and the one place a runtime path is '
+       + 'REQUIRED rather than tolerated. Each generator derives its repo root from its own '
+       + '__dirname, so running the SERVER\'s copy would regenerate the deploy tree instead of the '
+       + 'throwaway clone — rooting this statically would break the feature and corrupt the live '
+       + 'checkout. It is safe because of a control OUTSIDE this call: task 1003367 made '
+       + 'resolveBranchConflicts refuse to auto-resolve any branch touching '
+       + 'computeExecutedClosure() (steps 5b/4b), so this line is unreachable for a branch that '
+       + 'edited executed code, and task 1003366 put all eight execution roots at the Metic floor. '
+       + 'If that refusal is ever removed this exemption dies with it.',
+  },
+  {
+    at: 'modules/grading/generated-provenance.js:173',
+    why: '`dir` defaults to path.join(__dirname, ..., \'scripts\', \'bongos\') — the SERVER\'s own tree — '
+       + 'and `script` comes from the module-level GENERATORS table, which holds string literals '
+       + 'only. The `scriptDir` seam exists so the unit test never spawns a process and is never '
+       + 'set in production. The untrusted input here is the CWD, not the script: this runs a '
+       + 'trusted generator against a suspect tree, which is the inverse of the B50 shape.',
+  },
+  {
+    at: 'modules/grading/generated-provenance.js:240',
+    why: 'The async twin of the call at :173 — same `dir` default, same literal GENERATORS table, '
+       + 'same test-only `scriptDir` seam. Listed separately rather than folded in because an '
+       + 'exemption is keyed to a line: if one of the two calls changes shape, only that one '
+       + 're-opens for review.',
+  },
+  {
+    at: 'src/module-loader/loader.js:198',
+    why: 'The plugin loader, and the second site the audit named (B50 "motivating sites"). It '
+       + 'require()s a discovered module\'s route file, so the specifier is a runtime path BY '
+       + 'DESIGN — a plugin system whose module paths are compile-time constants is not a plugin '
+       + 'system. What bounds it is not this call but WHICH ROOTS are discovered: DEFAULT_ROOTS is '
+       + 'the core package\'s modules/ plus the instance\'s own, both operator-controlled, never a '
+       + 'builder branch. The residual risk — an instance accepting an untrusted module — is a '
+       + 'different boundary with its own control: ADR 0107 designates an accept-time module '
+       + 'security review, tracked as task 1003400. Exempt here so that work is not silently '
+       + 'absorbed into this check.',
+  },
+  {
+    at: 'src/module-loader/loader.js:350',
+    why: 'The poller twin of the route require at :196 — same DEFAULT_ROOTS bound, same plugin-by-'
+       + 'design rationale, same ADR 0107 / task 1003400 follow-on. Listed on its own line so a '
+       + 'change to either call re-opens only that one.',
+  },
+  {
+    at: 'modules/ui-design/scripts/validate-design.js:222',
+    why: 'A developer validation script, not a server path: it require()s each adapter\'s index.js '
+       + 'to check the adapter contract, and loading the thing under test is the whole point. '
+       + 'indexPath is path.join(ADAPTERS_DIR, adapterName, \'index.js\') where ADAPTERS_DIR is '
+       + '__dirname-rooted and adapterName comes from reading that same directory — so it cannot '
+       + 'escape the core checkout. Flagged only because the scan does not model a directory '
+       + 'listing as a constrained source.',
+  },
+  {
+    at: 'src/bongos/llm-cache.js:116',
+    why: 'Not an executed path at all. `cmd` is a `git rev-parse HEAD:<p>` command string built in '
+       + 'scopeShaFor from a code-defined paths list; the binary is git, resolved from PATH, and '
+       + 'nothing is run out of a builder tree. Flagged because the check reads arg 0 of every '
+       + 'spawner and cannot tell a command string from a path — the honest cost of a rule blunt '
+       + 'enough to have no gaps. NOTE for a future reader: interpolating `p` into a shell string '
+       + 'is a real smell of a DIFFERENT class (shell metacharacters, not tree provenance). It is '
+       + 'not exploitable today because every caller passes a literal, and it is out of scope for '
+       + 'B50 — but it is the thing to fix if `paths` ever becomes request-derived.',
+  },
+];
+
+// ---------------------------------------------------------------------------
+// binding resolution — which local names in THIS file are child_process spawners
+// ---------------------------------------------------------------------------
+
+const REQUIRE_CP_RE = /(?:const|let|var)\s+(\{[^}]*\}|[A-Za-z_$][\w$]*)\s*=\s*require\(\s*['"](?:node:)?child_process['"]\s*\)/g;
+
+// ESM: `import { execFile, spawn as sp } from 'node:child_process'`, and the namespace
+// form. The repo is CJS today, but a check that only understands CJS quietly stops
+// working the day a file converts — and stops without a signal, which is the failure
+// mode this file exists to avoid.
+const IMPORT_CP_RE = /import\s+(\*\s*as\s*[A-Za-z_$][\w$]*|\{[^}]*\}|[A-Za-z_$][\w$]*)\s*from\s*['"](?:node:)?child_process['"]/g;
+
+// The UNBOUND form: `require('node:child_process').execFileSync(...)` called straight off
+// the require. It binds no name, so binding resolution alone never sees it — and the
+// first draft of this check short-circuited the WHOLE FILE on "no bindings", so a file
+// spawning this way was skipped entirely rather than scanned. That is the exact
+// inversion of this scan's stated "fails toward noise, never toward silence" contract,
+// and the form is not hypothetical: scripts/bongos/autonomy-gate.js and
+// scripts/bongos/ship-land.js both already use it.
+const INLINE_CP_RE = new RegExp(
+  `require\\(\\s*['"](?:node:)?child_process['"]\\s*\\)\\s*\\.\\s*(?:${[...SPAWNERS].join('|')})\\s*\\(`,
+  'g',
+);
+
+// A require() whose specifier is not a literal: the server LOADS AND RUNS that module in
+// its own process, which is the same question this check asks of exec/spawn through a
+// different mechanism. src/module-loader/loader.js is the motivating site the audit named
+// alongside conflict-resolve.js.
+const REQUIRE_CALL_RE = /(?<![.\w$])require\s*\(/g;
+
+// Returns { direct:Set<name>, namespaces:Set<name> } — `direct` are names bound to a
+// spawner (destructuring or ESM named import, renames included), `namespaces` are
+// whole-module bindings used as `cp.execFile(...)`.
+function resolveBindings(src) {
+  const direct = new Set();
+  const namespaces = new Set();
+  const takeList = (lhs) => {
+    if (!lhs.startsWith('{')) {
+      namespaces.add(lhs.replace(/^\*\s*as\s*/, '').trim());
+      return;
+    }
+    for (const part of lhs.slice(1, -1).split(',')) {
+      const [orig, alias] = part.split(/:|\bas\b/).map((s) => s.trim());
+      if (orig && SPAWNERS.has(orig)) direct.add(alias || orig);
+    }
+  };
+  for (const re of [REQUIRE_CP_RE, IMPORT_CP_RE]) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(src))) takeList(m[1].trim());
+  }
+  return { direct, namespaces };
+}
+
+// ---------------------------------------------------------------------------
+// argument extraction — read a call's arguments, balancing brackets and strings
+// ---------------------------------------------------------------------------
+
+// From the index of a call's '(', return the raw argument text, or null if unbalanced.
+function readCallArgs(src, openIdx) {
+  let depth = 0;
+  let quote = null;
+  for (let i = openIdx; i < src.length; i += 1) {
+    const c = src[i];
+    if (quote) {
+      if (c === '\\') { i += 1; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') { quote = c; continue; }
+    if (c === '(' || c === '[' || c === '{') depth += 1;
+    else if (c === ')' || c === ']' || c === '}') {
+      depth -= 1;
+      if (depth === 0) return src.slice(openIdx + 1, i);
+    }
+  }
+  return null;
+}
+
+// Split argument text on TOP-LEVEL commas only.
+function splitArgs(argText) {
+  const out = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+  for (let i = 0; i < argText.length; i += 1) {
+    const c = argText[i];
+    if (quote) {
+      if (c === '\\') { i += 1; continue; }
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') { quote = c; continue; }
+    if (c === '(' || c === '[' || c === '{') depth += 1;
+    else if (c === ')' || c === ']' || c === '}') depth -= 1;
+    else if (c === ',' && depth === 0) { out.push(argText.slice(start, i)); start = i + 1; }
+  }
+  out.push(argText.slice(start));
+  return out.map((s) => s.trim()).filter((s) => s.length);
+}
+
+// ---------------------------------------------------------------------------
+// staticness — is an expression built only from roots fixed at module load?
+// ---------------------------------------------------------------------------
+
+// Blank string CONTENT so it cannot contribute identifiers — with one exception that
+// decides whether this check works at all.
+//
+// A template literal's `${...}` holes are CODE, not content. Blanking a whole template
+// the way a quoted string is blanked leaves `${work}/gen.js` with no free identifiers,
+// and isStatic()'s every() over an empty set is vacuously TRUE — so the path reads as
+// static and the call is never flagged. That is not a missed edge: it is a one-character
+// bypass of the entire check (write a backtick instead of calling path.join) for exactly
+// the runtime-derived path B1/B50 are about. Found by the grader, reproduced, pinned by
+// tests/exec_path_guard.mjs.
+//
+// So a template is reduced to a call-shaped list of its interpolated expressions —
+// `${a}/x/${b}` becomes `(a,b)` — which keeps every identifier the hole referenced and
+// discards the literal text around it. Templates are handled BEFORE the quoted forms so
+// a quote inside a hole cannot be mistaken for a string opener.
+const TEMPLATE_RE = /`(?:[^`\\]|\\.)*`/g;
+const HOLE_RE = /\$\{([^{}]*(?:\{[^{}]*\}[^{}]*)*)\}/g;
+
+function stripStrings(expr) {
+  return expr
+    .replace(TEMPLATE_RE, (lit) => {
+      const holes = [];
+      HOLE_RE.lastIndex = 0;
+      let m;
+      while ((m = HOLE_RE.exec(lit))) holes.push(m[1]);
+      return holes.length ? `(${holes.join(',')})` : '``';
+    })
+    .replace(/'(?:[^'\\]|\\.)*'/g, "''")
+    .replace(/"(?:[^"\\]|\\.)*"/g, '""');
+}
+
+// Free identifiers: tokens not preceded by '.' (property names) and not object keys.
+function freeIdentifiers(expr) {
+  const bare = stripStrings(expr);
+  const out = new Set();
+  const re = /(^|[^.\w$])([A-Za-z_$][\w$]*)/g;
+  let m;
+  while ((m = re.exec(bare))) out.add(m[2]);
+  return out;
+}
+
+// Module-level `const NAME = <expr>;` declarations — the only indirection the scan
+// follows. Column 0 is the test for module level; a const nested in a function is
+// re-assigned per call and is not a fixed root.
+function moduleConsts(src) {
+  const out = new Map();
+  const re = /^const\s+([A-Za-z_$][\w$]*)\s*=\s*([^\n]*?);?\s*$/gm;
+  let m;
+  while ((m = re.exec(src))) out.set(m[1], m[2]);
+  return out;
+}
+
+// The safe set: STATIC_ROOTS plus module consts that resolve to safe expressions.
+// Iterated to a fixpoint so `const A = __dirname; const B = path.join(A, 'x')` works.
+function safeIdentifiers(src) {
+  const consts = moduleConsts(src);
+  const safe = new Set(STATIC_ROOTS);
+  for (let pass = 0; pass < 5; pass += 1) {
+    let grew = false;
+    for (const [name, expr] of consts) {
+      if (safe.has(name)) continue;
+      if ([...freeIdentifiers(expr)].every((id) => safe.has(id))) { safe.add(name); grew = true; }
+    }
+    if (!grew) break;
+  }
+  return safe;
+}
+
+function isStatic(expr, safe) {
+  return [...freeIdentifiers(expr)].every((id) => safe.has(id));
+}
+
+// ---------------------------------------------------------------------------
+// masking — blank comments, string bodies and regex literals before matching
+// ---------------------------------------------------------------------------
+
+// Call sites are matched against a MASKED copy of the source, never the raw text.
+// Without this the scan reads prose: modules/grading/grader.js carries the words
+// "before worker spawn (GRADER_BYPASS_ENABLED / runOpts.bypass)" inside a note string,
+// and a bare /spawn\s*\(/ matches it and reports the sentence as an executed path.
+// Masking preserves LENGTH and NEWLINES, so offsets and line numbers computed on the
+// mask still address the original text and argument text is read back from it.
+//
+// Regex literals are detected by what precedes them — after an operator or an opening
+// bracket a `/` starts a pattern, after a value it is division. That heuristic is the
+// standard one and it can be wrong; being wrong here masks or unmasks a few characters
+// and can only add a finding, never hide one, which is the direction this scan fails in
+// everywhere else too.
+function maskNonCode(src) {
+  const out = src.split('');
+  const blank = (i) => { if (out[i] !== '\n') out[i] = ' '; };
+  let i = 0;
+  let prev = '';
+  while (i < src.length) {
+    const c = src[i];
+    const next = src[i + 1];
+    if (c === '/' && next === '/') {
+      while (i < src.length && src[i] !== '\n') { blank(i); i += 1; }
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      blank(i); blank(i + 1); i += 2;
+      while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) { blank(i); i += 1; }
+      if (i < src.length) { blank(i); blank(i + 1); i += 2; }
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      i += 1; // keep the opening quote so string-shaped args stay recognisable
+      while (i < src.length && src[i] !== c) {
+        if (src[i] === '\\') { blank(i); i += 1; }
+        if (i < src.length) { blank(i); i += 1; }
+      }
+      if (i < src.length) i += 1;
+      prev = c;
+      continue;
+    }
+    if (c === '/' && /[(,=:[!&|?{};+\-*%<>~^]/.test(prev)) {
+      i += 1;
+      while (i < src.length && src[i] !== '/' && src[i] !== '\n') {
+        if (src[i] === '\\') { blank(i); i += 1; }
+        if (i < src.length) { blank(i); i += 1; }
+      }
+      if (i < src.length && src[i] === '/') i += 1;
+      prev = '/';
+      continue;
+    }
+    if (!/\s/.test(c)) prev = c;
+    i += 1;
+  }
+  return out.join('');
+}
+
+// ---------------------------------------------------------------------------
+// the scan
+// ---------------------------------------------------------------------------
+
+// Which argument carries the executed path? Always arg 0. When arg 0 is the node
+// binary, the SCRIPT is the first element of the args array, so that is checked too —
+// `execFile(process.execPath, [path.join(work, rel)])` is the exact defect and its
+// arg 0 is perfectly static.
+function executedExpressions(args) {
+  const out = [];
+  if (!args.length) return out;
+  out.push({ expr: args[0], role: 'executable' });
+  const isNode = /process\.execPath/.test(args[0]) || /^['"](?:node|node\.exe)['"]$/.test(args[0].trim());
+  if (isNode && args[1] && args[1].trim().startsWith('[')) {
+    const first = splitArgs(args[1].trim().slice(1, -1))[0];
+    if (first) out.push({ expr: first, role: 'script' });
+  }
+  return out;
+}
+
+// Record one finding if the expression is not statically rooted.
+function consider(findings, { rel, masked, src, idx, callText, role, expr, safe }) {
+  if (expr == null || isStatic(expr, safe)) return;
+  findings.push({
+    file: rel,
+    line: src.slice(0, idx).split('\n').length,
+    role,
+    expr: expr.replace(/\s+/g, ' ').slice(0, 120),
+    call: callText,
+  });
+}
+
+function scanFile(rel, src) {
+  // Everything regex-matched below runs against `masked`; argument TEXT is read back
+  // from `src` at the same offsets, which masking keeps aligned.
+  const masked = maskNonCode(src);
+  // Bindings are resolved from the ORIGINAL text: masking blanks string bodies, and the
+  // require specifier 'node:child_process' IS a string body — reading bindings off the
+  // mask finds none, and the scan silently passes every file (caught in review).
+  const { direct, namespaces } = resolveBindings(src);
+  const safe = safeIdentifiers(masked);
+  const findings = [];
+
+  // Every way a spawner can be reached: a bound name, a namespace member, and the
+  // unbound require('child_process').x() form. NOT short-circuited on "no bindings" —
+  // the inline form has none by construction.
+  const forms = [
+    ...[...direct].map((n) => `(?<![.\\w$])${n}\\s*\\(`),
+    ...[...namespaces].map((ns) => `(?<![.\\w$])${ns}\\s*\\.\\s*(?:${[...SPAWNERS].join('|')})\\s*\\(`),
+  ];
+
+  // Bound spawner calls are matched against the MASK, so prose can never be one.
+  const hits = [];
+  if (forms.length) {
+    const bound = new RegExp(forms.join('|'), 'g');
+    let b;
+    while ((b = bound.exec(masked))) hits.push(b);
+  }
+
+  // The UNBOUND form is matched against the ORIGINAL text, because the thing that
+  // identifies it IS a specifier string and masking blanks string bodies — the same trap
+  // that once made binding resolution see nothing at all. Prose is still excluded
+  // without re-reading the raw text wholesale: had the construct sat inside a comment or
+  // a string, its trailing '(' would have been blanked too, so the mask is consulted for
+  // that one character.
+  INLINE_CP_RE.lastIndex = 0;
+  let im;
+  while ((im = INLINE_CP_RE.exec(src))) {
+    if (masked[im.index + im[0].length - 1] === '(') hits.push(im);
+  }
+
+  for (const m of hits) {
+    const openIdx = m.index + m[0].length - 1;
+    const argText = readCallArgs(src, openIdx);
+    if (argText == null) continue;
+    const args = splitArgs(argText);
+    const callText = m[0].slice(0, -1).trim().replace(/\s+/g, '');
+    for (const { expr, role } of executedExpressions(args)) {
+      consider(findings, { rel, masked, src, idx: m.index, callText, role, expr, safe });
+    }
+  }
+
+  // Dynamic require(): the server loads and RUNS that module in-process. Same question,
+  // different mechanism — src/module-loader/loader.js is the site the audit named.
+  REQUIRE_CALL_RE.lastIndex = 0;
+  let r;
+  while ((r = REQUIRE_CALL_RE.exec(masked))) {
+    const openIdx = r.index + r[0].length - 1;
+    const argText = readCallArgs(src, openIdx);
+    if (argText == null) continue;
+    const spec = splitArgs(argText)[0];
+    consider(findings, {
+      rel, masked, src, idx: r.index, callText: 'require', role: 'module', expr: spec, safe,
+    });
+  }
+
+  return findings;
+}
+
+// Every tracked first-party server file. Browser assets under public/ never spawn.
+function trackedServerFiles() {
+  try {
+    // DIRECTORY pathspecs, filtered by extension here, rather than '**/*.js' globs.
+    // NOT a bug fix — the glob form enumerated the same 351 files, because a git pathspec
+    // '*' crosses '/' (fnmatch without FNM_PATHNAME), so 'src/*.js' already matched every
+    // nested file and 'src/**/*.js' — which matches only 63 — was pure redundancy. That
+    // equivalence is a non-obvious property of git that a reader has to know to trust the
+    // line, and the cost of being wrong about it is coverage that narrows with no signal.
+    // A directory pathspec needs no such knowledge. Pinned by the enumeration test below.
+    const out = execFileSync('git', ['ls-files', '--', 'src', 'modules'],
+      { cwd: REPO_ROOT, encoding: 'utf8' });
+    return [...new Set(out.split('\n').map((x) => x.trim()).filter(Boolean))]
+      .filter((f) => f.endsWith('.js'))
+      .filter((f) => !f.includes('/public/') && !f.includes('/app/'));
+  } catch {
+    return [];
+  }
+}
+
+function exemptionFor(f) {
+  return EXEMPTIONS.find((e) => e.at === `${f.file}:${f.line}`) || null;
+}
+
+function checkExecPathsStatic({ files, read } = {}) {
+  const list = files || trackedServerFiles();
+  if (!list.length) {
+    return {
+      name: NAME, ok: false, hardFail: true,
+      violations: ['scan defect — enumerated 0 tracked server files; a broken enumeration, not a clean result.'],
+      warnings: [], note: 'static scan of src/ + modules/ for executed paths.',
+    };
+  }
+  const reader = read || ((rel) => {
+    try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return null; }
+  });
+
+  const violations = [];
+  // Exemptions are NOT warnings. Four reviewed entries emitted as warnings make this check
+  // read WARN on every single run, and a check that is permanently yellow is one people stop
+  // reading. They ride in `exempt` instead: counted in the note, listed in full by the
+  // standalone run (node scripts/bongos/exec-path-guard.js).
+  const exempt = [];
+  let scanned = 0;
+  let callSites = 0;
+  for (const rel of list) {
+    const src = reader(rel);
+    if (src == null) continue;
+    scanned += 1;
+    for (const f of scanFile(rel, src)) {
+      callSites += 1;
+      const ex = exemptionFor(f);
+      if (ex) { exempt.push(`${f.file}:${f.line} exempt — ${ex.why}`); continue; }
+      violations.push(
+        `${f.file}:${f.line} ${f.call}() runs a ${f.role} path that is not statically rooted at the core `
+        + `checkout: \`${f.expr}\`. The server executes it with its OWN environment — DATABASE_URL, `
+        + 'BUILDER_SECRET_KEY — so a path assembled at runtime is a path an untrusted tree can steer. '
+        + 'Root it at __dirname or a module-level const, or add a reviewed EXEMPTIONS entry in '
+        + 'scripts/bongos/exec-path-guard.js saying why a runtime path is correct here.',
+      );
+    }
+  }
+
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    exempt,
+    note: `${scanned} server file(s) scanned for child_process calls; ${callSites} non-static executed `
+      + `path(s) found, ${EXEMPTIONS.length} reviewed exemption(s). An executed path must be built only `
+      + 'from literals, __dirname/__filename, process.execPath and module-level consts — the server runs '
+      + 'it with its own credentials, so "what runs" must be answerable by reading the call site.',
+  };
+}
+
+function main() {
+  const r = checkExecPathsStatic();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  for (const w of r.exempt) console.log(`  - ${w}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+// Exported surface = what fitness.js, the standalone main and the tests actually use.
+// stripStrings/maskNonCode/isStatic are exported because the template-literal bypass
+// above is the kind of defect that needs a test at ITS OWN altitude, not only through
+// scanFile — a unit-level probe is how that regression stays visible.
+module.exports = {
+  checkExecPathsStatic, scanFile, resolveBindings, trackedServerFiles,
+  stripStrings, maskNonCode, isStatic, safeIdentifiers,
+  EXEMPTIONS, NAME,
+};