@swarmdo/cli 1.4.8

package/plugins/swarmdo-metaharness/scripts/audit-trend.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+// audit-trend.mjs — diff two oia-audit records to detect drift over time.
+//
+// The iter-7 oia-audit composite worker stores timestamped records under
+// the `metaharness-audit` memory namespace. This script reads two such
+// records and surfaces the delta:
+//   - composite worst severity change (clean → low, low → medium, etc.)
+//   - per-component (oia / threat-model / mcp-scan) status change
+//   - new HIGH-severity findings introduced
+//   - findings cleared
+//
+// Pairs with iter-7's oia-audit + iter-8's weekly cron — accumulated
+// records enable drift detection without ad-hoc tooling.
+//
+// USAGE
+//   node scripts/audit-trend.mjs --baseline audit-<ts1>.json --current audit-<ts2>.json
+//   node scripts/audit-trend.mjs --baseline-key audit-2026-06-01... --current-key audit-2026-06-15...
+//     # pulls both from memory namespace `metaharness-audit`
+//   node scripts/audit-trend.mjs ... --alert-on-worsening
+//   node scripts/audit-trend.mjs ... --format json
+//
+// EXIT CODES
+//   0  ok (no worsening, or --alert-on-worsening not set)
+//   1  --alert-on-worsening AND composite severity worsened
+//   2  config error or input not found
+
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+// iter 38 — structural-distance drift via ADR-152 §3.1 production module.
+// Falls back to null if either record predates iter-38 oia-audit (no
+// fingerprint field) — graceful degradation, never throws.
+import { similarity } from './_similarity.mjs';
+// iter 63 — shared SEVERITY_RANK from _harness.mjs (was a local literal
+// missing info/warn/error/critical, which caused NaN-compare hazards).
+import { SEVERITY_RANK, rankSeverity } from './_harness.mjs';
+
+// iter 63 — SEVERITY_RANK moved to _harness.mjs (imported above)
+const NS = process.env.AUDIT_TREND_NAMESPACE || 'metaharness-audit';
+const CLI_PKG = process.env.CLI_CORE === '1'
+  ? '@swarmdo/cli-core@alpha'
+  : '@swarmdo/cli@latest';
+
+const ARGS = (() => {
+  const a = {
+    baseline: null, current: null,
+    baselineKey: null, currentKey: null,
+    alertOnWorsening: false, format: 'table',
+    // iter 38 — structural-distance gate (ADR-152 §3.1 dep)
+    alertOnDistanceBelow: null,
+  };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--baseline') a.baseline = process.argv[++i];
+    else if (v === '--current') a.current = process.argv[++i];
+    else if (v === '--baseline-key') a.baselineKey = process.argv[++i];
+    else if (v === '--current-key') a.currentKey = process.argv[++i];
+    else if (v === '--alert-on-worsening') a.alertOnWorsening = true;
+    else if (v === '--alert-on-distance-below') a.alertOnDistanceBelow = Number(process.argv[++i]);
+    else if (v === '--format') a.format = process.argv[++i];
+  }
+  return a;
+})();
+
+function memRetrieve(key) {
+  const r = spawnSync('npx', [
+    CLI_PKG, 'memory', 'retrieve',
+    '--namespace', NS, '--key', key,
+  ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8', shell: process.platform === 'win32' });
+  if (r.status !== 0) return null;
+  const m = /\{[\s\S]*\}/.exec(r.stdout || '');
+  if (!m) return null;
+  try { return JSON.parse(m[0]); } catch { return null; }
+}
+
+function loadRecord(label, filePath, memKey) {
+  if (filePath) {
+    if (!existsSync(filePath)) {
+      console.error(`audit-trend: ${label} file not found: ${filePath}`);
+      process.exit(2);
+    }
+    try { return JSON.parse(readFileSync(filePath, 'utf-8')); }
+    catch (e) {
+      console.error(`audit-trend: ${label} file invalid JSON: ${e.message}`);
+      process.exit(2);
+    }
+  }
+  if (memKey) {
+    const rec = memRetrieve(memKey);
+    if (!rec) {
+      console.error(`audit-trend: ${label} key not found in namespace ${NS}: ${memKey}`);
+      process.exit(2);
+    }
+    return rec;
+  }
+  console.error(`audit-trend: --${label} or --${label}-key is required`);
+  process.exit(2);
+}
+
+function main() {
+  const baseline = loadRecord('baseline', ARGS.baseline, ARGS.baselineKey);
+  const current  = loadRecord('current',  ARGS.current,  ARGS.currentKey);
+
+  // Sanity: both must look like oia-audit records (composite + components).
+  if (!baseline.composite || !current.composite) {
+    console.error('audit-trend: snapshots must contain `composite` (from oia-audit.mjs)');
+    process.exit(2);
+  }
+
+  const baseWorst = String(baseline.composite.worst || 'clean').toLowerCase();
+  const currWorst = String(current.composite.worst || 'clean').toLowerCase();
+  // iter 63 — safe rankSeverity() eliminates NaN-compare when either
+  // severity is unknown (was a latent bug in audit-trend's drift verdict).
+  const deltaRank = rankSeverity(currWorst) - rankSeverity(baseWorst);
+  const worsened = deltaRank > 0;
+  const improved = deltaRank < 0;
+
+  // Per-component status change. Each `components.{oiaManifest, threatModel,
+  // mcpScan}` has degraded:bool + exitCode + (for threat-model) json.worst.
+  const componentDelta = (label, b, c) => {
+    if (!b || !c) return { label, delta: 'missing' };
+    if (b.degraded !== c.degraded) {
+      return { label, delta: c.degraded ? 'became degraded' : 'recovered from degraded' };
+    }
+    if (b.exitCode !== c.exitCode) {
+      return { label, delta: `exit code ${b.exitCode} → ${c.exitCode}` };
+    }
+    return { label, delta: 'unchanged' };
+  };
+  const components = {
+    oiaManifest: componentDelta('oia-manifest', baseline.components?.oiaManifest, current.components?.oiaManifest),
+    threatModel: componentDelta('threat-model', baseline.components?.threatModel, current.components?.threatModel),
+    mcpScan: componentDelta('mcp-scan', baseline.components?.mcpScan, current.components?.mcpScan),
+  };
+
+  // mcp-scan findings — what was introduced vs cleared.
+  const baseFindings = Array.isArray(baseline.components?.mcpScan?.json?.findings)
+    ? baseline.components.mcpScan.json.findings : [];
+  const currFindings = Array.isArray(current.components?.mcpScan?.json?.findings)
+    ? current.components.mcpScan.json.findings : [];
+  const fingerprint = (f) => `${f.severity}:${f.id ?? '-'}:${f.server ?? '-'}:${f.tool ?? '-'}:${(f.message ?? '').slice(0, 80)}`;
+  const baseSet = new Set(baseFindings.map(fingerprint));
+  const currSet = new Set(currFindings.map(fingerprint));
+  const introduced = currFindings.filter((f) => !baseSet.has(fingerprint(f)));
+  const cleared    = baseFindings.filter((f) => !currSet.has(fingerprint(f)));
+
+  // iter 38 — structural distance via ADR-152 §3.1 similarity().
+  // Both records need a fingerprint (score+genome) — iter-38 oia-audit
+  // adds it; older records skip with verdict 'unavailable'.
+  let structuralDistance = null;
+  if (baseline.fingerprint?.score && baseline.fingerprint?.genome
+      && current.fingerprint?.score && current.fingerprint?.genome) {
+    const sim = similarity(baseline.fingerprint, current.fingerprint);
+    structuralDistance = {
+      overall: sim.overall,
+      // Distance is the complement of similarity in [0,1]
+      distance: Number((1 - sim.overall).toFixed(4)),
+      components: sim.components,
+      verdict: sim.overall >= 0.95 ? 'near-identical'
+        : sim.overall >= 0.80 ? 'minor-drift'
+        : sim.overall >= 0.50 ? 'moderate-drift'
+        : 'major-drift',
+    };
+  } else {
+    structuralDistance = {
+      verdict: 'unavailable',
+      reason: 'one or both records predate iter-38 oia-audit fingerprint bundling',
+    };
+  }
+
+  // Distance alert is independent of severity worsening — a harness can
+  // structurally drift while keeping the same worst-severity verdict.
+  const distanceAlertTriggered = ARGS.alertOnDistanceBelow != null
+    && structuralDistance.overall != null
+    && structuralDistance.overall < ARGS.alertOnDistanceBelow;
+
+  const payload = {
+    baseline: {
+      startedAt: baseline.startedAt,
+      composite: baseline.composite,
+    },
+    current: {
+      startedAt: current.startedAt,
+      composite: current.composite,
+    },
+    delta: {
+      worst: { baseline: baseWorst, current: currWorst, rankDelta: deltaRank,
+        verdict: worsened ? 'worsened' : (improved ? 'improved' : 'unchanged') },
+      components,
+      findings: {
+        introducedCount: introduced.length,
+        clearedCount: cleared.length,
+        introduced: introduced.slice(0, 20),  // truncate for output sanity
+        cleared: cleared.slice(0, 20),
+      },
+      // iter 38 — structural distance via ADR-152 §3.1
+      structuralDistance,
+    },
+    alert: (ARGS.alertOnWorsening || ARGS.alertOnDistanceBelow != null) ? {
+      triggered: worsened || distanceAlertTriggered,
+      reasons: [
+        ARGS.alertOnWorsening && worsened
+          ? `composite worst ${baseWorst} → ${currWorst}` : null,
+        distanceAlertTriggered
+          ? `structural similarity ${structuralDistance.overall} < threshold ${ARGS.alertOnDistanceBelow}` : null,
+      ].filter(Boolean),
+    } : null,
+    generatedAt: new Date().toISOString(),
+  };
+
+  if (ARGS.format === 'json') {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(`# audit-trend`);
+    console.log('');
+    console.log(`Baseline: ${baseline.startedAt}`);
+    console.log(`Current:  ${current.startedAt}`);
+    console.log('');
+    console.log(`| Metric | Baseline | Current | Verdict |`);
+    console.log(`|---|---|---|---|`);
+    const verdictIcon = worsened ? '⚠ worsened' : (improved ? '✓ improved' : '— unchanged');
+    console.log(`| composite worst | ${baseWorst} | ${currWorst} | ${verdictIcon} |`);
+    for (const [label, c] of Object.entries(components)) {
+      console.log(`| ${label} | — | — | ${c.delta} |`);
+    }
+    console.log('');
+    console.log(`Findings: **+${introduced.length} introduced**, **−${cleared.length} cleared**`);
+    if (introduced.length > 0) {
+      console.log('');
+      console.log('## Introduced findings');
+      console.log('');
+      console.log('| Severity | Server | Tool | Message |');
+      console.log('|---|---|---|---|');
+      for (const f of introduced.slice(0, 20)) {
+        console.log(`| ${f.severity ?? '-'} | ${f.server ?? '-'} | ${f.tool ?? '-'} | ${(f.message ?? '').slice(0, 80)} |`);
+      }
+    }
+    if (cleared.length > 0) {
+      console.log('');
+      console.log('## Cleared findings');
+      console.log('');
+      for (const f of cleared.slice(0, 5)) {
+        console.log(`- ${f.severity ?? '-'} ${f.id ?? '-'} (${f.server ?? '-'}/${f.tool ?? '-'})`);
+      }
+    }
+    console.log('');
+    // iter 38 — structural distance row
+    if (structuralDistance.verdict !== 'unavailable') {
+      console.log(`## Structural distance (ADR-152 §3.1)`);
+      console.log('');
+      console.log(`| Metric | Value |`);
+      console.log(`|---|---:|`);
+      console.log(`| overall similarity | ${structuralDistance.overall.toFixed(4)} |`);
+      console.log(`| distance (1 − sim) | ${structuralDistance.distance.toFixed(4)} |`);
+      console.log(`| verdict | **${structuralDistance.verdict}** |`);
+      console.log('');
+    } else {
+      console.log(`Structural distance: _unavailable — ${structuralDistance.reason}_`);
+      console.log('');
+    }
+    if (payload.alert) {
+      if (payload.alert.triggered) {
+        console.log(`⚠ **ALERT**: ${payload.alert.reasons.join('; ')}`);
+      } else {
+        console.log(`✓ no alert triggered`);
+      }
+    }
+  }
+
+  if (payload.alert?.triggered) process.exit(1);
+}
+
+main();

package/plugins/swarmdo-metaharness/scripts/bench-parse-mcp-scan.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// bench-parse-mcp-scan — perf characterization for iter-50's
+// parseMcpScanText. Sister to iter-41's bench-similarity.mjs.
+//
+// THE CLAIM
+// parseMcpScanText is a small regex over short text. Sub-microsecond
+// per call expected. Phase-3 consumers (oia-audit + the audit-trend
+// introduced/cleared diff) call it once per audit run, so the per-call
+// cost compounds if the parser is on a slow path.
+//
+// WHAT IT MEASURES
+// Per-call mean + p50 + p99 over 100k iters, across 3 categories:
+//   - empty: parseMcpScanText('') — fastest path
+//   - typical: swarmdo's actual single-INFO output
+//   - rich: a synthetic multi-finding payload with continuation lines
+//
+// USAGE
+//   node scripts/bench-parse-mcp-scan.mjs                  # default 100k iters
+//   node scripts/bench-parse-mcp-scan.mjs --iters 1000000
+//   node scripts/bench-parse-mcp-scan.mjs --format json
+//   node scripts/bench-parse-mcp-scan.mjs --max-mean-us 5  # CI gate
+//
+// EXIT CODES
+//   0  ok (or threshold satisfied)
+//   1  --max-mean-us exceeded by any category
+
+import { performance } from 'node:perf_hooks';
+import { parseMcpScanText } from './_harness.mjs';
+
+const ARGS = (() => {
+  const a = { iters: 100_000, format: 'table', maxMeanUs: null };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--iters') a.iters = parseInt(process.argv[++i], 10);
+    else if (v === '--format') a.format = process.argv[++i];
+    else if (v === '--max-mean-us') a.maxMeanUs = parseFloat(process.argv[++i]);
+  }
+  return a;
+})();
+
+const EMPTY = '';
+
+const TYPICAL = `harness mcp-scan — /repo
+
+  [INFO] No MCP security issues found
+         Policy is default-deny with safe capability grants and an audit log.
+
+Result: INFO (1 finding, 0 high)
+`;
+
+const RICH = `harness mcp-scan — /repo
+
+  [HIGH] First high-severity finding
+         Continuation line 1
+         Continuation line 2
+  [WARN] Second warning finding
+         Some additional context
+  [HIGH] Third high finding
+  [INFO] Fourth informational
+         Multi-line message body
+         Spanning three lines
+         Ending here
+  [CRITICAL] Fifth critical issue
+         With single continuation
+
+Result: HIGH (5 findings, 2 high)
+`;
+
+function bench(label, input, iters) {
+  // Warm-up
+  for (let i = 0; i < 10_000; i++) parseMcpScanText(input);
+
+  const samples = new Float64Array(iters);
+  for (let i = 0; i < iters; i++) {
+    const t0 = performance.now();
+    parseMcpScanText(input);
+    samples[i] = performance.now() - t0;
+  }
+  let sum = 0;
+  for (let i = 0; i < iters; i++) sum += samples[i];
+  const mean = sum / iters;
+  const sorted = Array.from(samples).sort((x, y) => x - y);
+  const p50 = sorted[Math.floor(iters * 0.5)];
+  const p99 = sorted[Math.floor(iters * 0.99)];
+  return {
+    label, iters,
+    meanMs: mean, p50Ms: p50, p99Ms: p99,
+    meanUs: mean * 1000, p99Us: p99 * 1000,
+  };
+}
+
+// iter 87 — suppress markdown header in --format json so captured
+// file stays valid JSON.
+if (ARGS.format !== 'json') {
+  console.log(`# bench-parse-mcp-scan — iter-50 parser per-call cost\n`);
+  console.log(`iters: ${ARGS.iters.toLocaleString()}\n`);
+}
+
+const results = [
+  bench('empty', EMPTY, ARGS.iters),
+  bench('typical (1 INFO)', TYPICAL, ARGS.iters),
+  bench('rich (5 findings)', RICH, ARGS.iters),
+];
+
+let gate = { triggered: false, reasons: [] };
+if (ARGS.maxMeanUs != null) {
+  for (const r of results) {
+    if (r.meanUs > ARGS.maxMeanUs) {
+      gate.triggered = true;
+      gate.reasons.push(`${r.label}: mean ${r.meanUs.toFixed(3)}μs > ceiling ${ARGS.maxMeanUs}μs`);
+    }
+  }
+}
+
+const payload = {
+  iters: ARGS.iters,
+  results,
+  gate: ARGS.maxMeanUs != null ? {
+    thresholdUs: ARGS.maxMeanUs,
+    triggered: gate.triggered,
+    reasons: gate.reasons,
+  } : null,
+  generatedAt: new Date().toISOString(),
+  contract: 'parseMcpScanText is sub-microsecond for empty/typical; rich (5 findings, 14 lines) stays under 10μs.',
+};
+
+if (ARGS.format === 'json') {
+  console.log(JSON.stringify(payload, null, 2));
+} else {
+  console.log(`| Category            |       mean |        p50 |        p99 |`);
+  console.log(`|---------------------|-----------:|-----------:|-----------:|`);
+  for (const r of results) {
+    console.log(`| ${r.label.padEnd(19)} | ${r.meanUs.toFixed(3).padStart(7)}μs | ${(r.p50Ms * 1000).toFixed(3).padStart(7)}μs | ${r.p99Us.toFixed(3).padStart(7)}μs |`);
+  }
+  console.log('');
+  if (payload.gate) {
+    if (payload.gate.triggered) {
+      console.log(`⚠ ALERT: ceiling ${ARGS.maxMeanUs}μs exceeded by:`);
+      for (const reason of payload.gate.reasons) console.log(`    - ${reason}`);
+    } else {
+      console.log(`✓ all categories within --max-mean-us ${ARGS.maxMeanUs}μs ceiling`);
+    }
+  }
+}
+
+if (gate.triggered) process.exit(1);

package/plugins/swarmdo-metaharness/scripts/bench-recordpair-overhead.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// bench-recordpair-overhead.mjs — micro-benchmark proving iter-12's
+// "zero default-path overhead" claim with measured numbers.
+//
+// THE CLAIM
+// Iter 12 added one env-flag check to model-router.ts route() so
+// recordPair() fires only when SWARMDO_ROUTER_PARALLEL_LOG=1.
+// When unset (default), the cost is:
+//
+//   if (process.env.SWARMDO_ROUTER_PARALLEL_LOG === '1') { ... }
+//
+// This benchmark measures that exact pattern over 1,000,000 iterations
+// and reports the per-call mean + p99. For the claim to hold, the
+// per-call overhead must be sub-microsecond.
+//
+// USAGE
+//   node scripts/bench-recordpair-overhead.mjs               # 1M iters
+//   node scripts/bench-recordpair-overhead.mjs --iters 5000000
+//   node scripts/bench-recordpair-overhead.mjs --format json
+//
+// EXIT CODES
+//   0  benchmark complete (always; this is informational, not pass/fail)
+
+import { performance } from 'node:perf_hooks';
+
+const ARGS = (() => {
+  const a = {
+    iters: 1_000_000,
+    format: 'table',
+    // iter 25 — CI regression gate. When --max-overhead-ns N is set,
+    // exit 1 if the measured iter-12 default-path overhead exceeds N
+    // nanoseconds per call. Default threshold 500ns chosen as ~3.5×
+    // headroom over the iter-24 measured baseline of ~147ns on Apple
+    // Silicon / Node 22.
+    maxOverheadNs: null,
+  };
+  for (let i = 2; i < process.argv.length; i++) {
+    const v = process.argv[i];
+    if (v === '--iters') a.iters = parseInt(process.argv[++i], 10);
+    else if (v === '--format') a.format = process.argv[++i];
+    else if (v === '--max-overhead-ns') a.maxOverheadNs = parseFloat(process.argv[++i]);
+  }
+  return a;
+})();
+
+function bench(label, fn, iters) {
+  // Warm-up
+  for (let i = 0; i < 10_000; i++) fn();
+
+  const samples = new Float64Array(iters);
+  for (let i = 0; i < iters; i++) {
+    const start = performance.now();
+    fn();
+    samples[i] = performance.now() - start;
+  }
+  // performance.now() resolution is ~1 microsecond on most platforms.
+  // For sub-microsecond ops we can't measure individual iterations
+  // accurately; report aggregate timing instead.
+
+  // Also measure batched timing — sum of N calls in one hot loop —
+  // which IS accurate for sub-μs ops.
+  const batchStart = performance.now();
+  for (let i = 0; i < iters; i++) fn();
+  const batchTotal = performance.now() - batchStart;
+  const meanNs = (batchTotal * 1e6) / iters;  // ms → ns / iters
+
+  // Sort samples for percentile reporting (per-call resolution-limited)
+  const sortedMs = Array.from(samples).sort((a, b) => a - b);
+  const p99 = sortedMs[Math.floor(0.99 * sortedMs.length)];
+
+  return {
+    label,
+    iters,
+    batchTotalMs: Math.round(batchTotal * 1000) / 1000,
+    meanNsPerCall: Math.round(meanNs * 100) / 100,
+    p99PerCallMs: Math.round(p99 * 10000) / 10000,
+  };
+}
+
+function main() {
+  const iters = ARGS.iters;
+  if (!Number.isInteger(iters) || iters < 1000) {
+    console.error('bench-recordpair-overhead: --iters must be ≥ 1000');
+    process.exit(2);
+  }
+
+  // iter 137 — guard the markdown header behind table-format so
+  // --format json emits pure JSON (consumed by CI's JSON.parse).
+  // Same fix-class as bench-similarity's iter 87 fix.
+  if (ARGS.format !== 'json') {
+    console.log(`# bench-recordpair-overhead`);
+    console.log('');
+    console.log(`Iterations: ${iters.toLocaleString()}`);
+    console.log(`Platform: ${process.platform} ${process.arch}, Node ${process.version}`);
+    console.log('');
+  }
+
+  // Baseline — no-op
+  const baseline = bench('baseline (no-op)', () => {}, iters);
+
+  // The iter-12 env-flag check, OFF case
+  // Match the exact source pattern from model-router.ts
+  delete process.env.SWARMDO_ROUTER_PARALLEL_LOG;  // ensure OFF
+  const envCheckOff = bench(
+    'iter-12 env check (FLAG OFF — default path)',
+    () => { if (process.env.SWARMDO_ROUTER_PARALLEL_LOG === '1') { /* unreached */ } },
+    iters,
+  );
+
+  // ON case — but no actual loadParallelRecorder().then() call (that's
+  // a one-time microtask amortized over the process lifetime). Measure
+  // just the conditional.
+  process.env.SWARMDO_ROUTER_PARALLEL_LOG = '1';
+  const envCheckOn = bench(
+    'iter-12 env check (FLAG ON — branch taken, NO recordPair)',
+    () => { if (process.env.SWARMDO_ROUTER_PARALLEL_LOG === '1') { /* branch taken */ } },
+    iters,
+  );
+  delete process.env.SWARMDO_ROUTER_PARALLEL_LOG;
+
+  // What does the LAZY-LOADER short-circuit cost when called repeatedly?
+  // Once initialized, it's a single nullness check on a module-level var.
+  let _cached = null;
+  const lazyLoaderInit = () => {
+    if (_cached === null) _cached = { mod: { recordPair: () => {} } };
+    return _cached;
+  };
+  // Run once to populate the cache
+  lazyLoaderInit();
+  const lazyLoaderHot = bench(
+    'lazy loader (post-init nullness check)',
+    () => { lazyLoaderInit(); },
+    iters,
+  );
+
+  const results = [baseline, envCheckOff, envCheckOn, lazyLoaderHot];
+
+  if (ARGS.format === 'json') {
+    console.log(JSON.stringify({
+      platform: { os: process.platform, arch: process.arch, node: process.version },
+      iters,
+      results,
+      generatedAt: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  console.log(`| Variant | Total (ms) | Mean per-call (ns) | p99 sample (ms) |`);
+  console.log(`|---|---:|---:|---:|`);
+  for (const r of results) {
+    console.log(`| ${r.label} | ${r.batchTotalMs} | ${r.meanNsPerCall} | ${r.p99PerCallMs} |`);
+  }
+
+  // Interpret
+  const overhead = envCheckOff.meanNsPerCall - baseline.meanNsPerCall;
+  console.log('');
+  console.log(`**Iter-12 default-path overhead**: ~${Math.round(overhead)}ns per route() call`);
+  console.log('');
+  if (overhead < 100) {
+    console.log(`✓ Overhead < 100ns confirms iter-12's "zero default-path overhead" claim.`);
+    console.log(`  At 1000 routing decisions per workload, total added cost is ~${Math.round(overhead * 1000 / 1000)}μs — imperceptible.`);
+  } else if (overhead < 1000) {
+    console.log(`✓ Overhead < 1μs is well within tolerable bounds.`);
+  } else {
+    console.log(`⚠ Overhead ${Math.round(overhead)}ns is higher than expected; investigate engine optimization.`);
+  }
+
+  // CI regression gate (iter 25).
+  if (ARGS.maxOverheadNs !== null) {
+    if (!isFinite(ARGS.maxOverheadNs) || ARGS.maxOverheadNs <= 0) {
+      console.error('bench-recordpair-overhead: --max-overhead-ns must be a positive number');
+      process.exit(2);
+    }
+    console.log('');
+    if (overhead > ARGS.maxOverheadNs) {
+      console.log(`⚠ **REGRESSION**: measured ${Math.round(overhead)}ns > threshold ${ARGS.maxOverheadNs}ns`);
+      console.log(`  The iter-12 dispatch wiring may have grown beyond the env-flag check.`);
+      console.log(`  Inspect v3/@swarmdo/cli/src/swarmvector/model-router.ts route() for new work in the default path.`);
+      process.exit(1);
+    } else {
+      console.log(`✓ Within regression threshold (${Math.round(overhead)}ns ≤ ${ARGS.maxOverheadNs}ns).`);
+    }
+  }
+}
+
+main();