@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/session-eval.js

@@ -0,0 +1,631 @@
+#!/usr/bin/env node
+// BFG session-inefficiency evaluator — analysis engine (6D.3, ADR 0027).
+//
+// Productizes the manual #506 post-mortem: given a session's uploaded digest
+// (the per-turn metadata + scrubbed snippets that 6D.1 stores + 6D.2 serves),
+// it COMPUTES the ceremony-vs-work token ratio and a footgun taxonomy — the
+// signals a human read by hand for #506. The BFG routine
+// (.claude/scheduled-tasks/bfg-session-eval/) calls the 6D.2 search API to pick
+// candidates, fetches each, runs evaluateSession() here, and reports.
+//
+// The exported functions are PURE (no I/O) and unit-tested (tests/session_eval.mjs
+// + the #506 corpus check in 6D.5). The CLI at the bottom does the I/O (search,
+// fetch, write report) and only runs when invoked directly.
+//
+// Heuristic, by design: classification works from tool names + short snippets,
+// so it APPROXIMATES the human judgment. The thresholds are tuned to reproduce
+// the #506 hand-labelled case (6D.5 is the regression gate).
+
+// Pure helper (no I/O) — resolves the per-rank wandering default so the
+// off-task signal below only fires for the CONSTRAINING ranks (task 1268).
+const wanderingPrefs = require('../../modules/builder-settings/wandering-prefs'); // carved → modules/builder-settings/ (BV1.R80 / ADR 0093 §1)
+// task 1002516 (clause 4 of criterion `accessibility-fluency-profile`): the
+// transcript accessibility dimension. The upload route scores it server-side and
+// stores it on the session row; this file re-scores a row that predates the
+// dimension so the BFG's history is not a blank column. Same sibling-read
+// posture as wanderingPrefs above — scripts/ is outside the module boundary
+// fitness scans (modules/sessions/CLAUDE.md, "NOT in this module").
+const { scoreAccessibility } = require('../../modules/sessions/accessibility');
+const { resolveDefaultVersion } = require('./version-select.js');
+
+// ---- classification vocabularies -----------------------------------------
+
+// GDS process plumbing — claiming, shipping, grading, merging, status. Tokens
+// spent driving these are "ceremony", not the actual change.
+const GDS_PLUMBING_RE =
+  /\b(claim|ship|release|start|status|merge-lock|conductor-dispatch|smoke-gds|smoke-write|builder-|\/api\/gds\/|gds\/[a-z-]+\.js)\b|git (commit|push|merge|fetch|checkout|reset|status)|psql |\bgrade\b/i;
+// Methodology / process reading + session bookkeeping.
+const METHODOLOGY_RE = /\b(CLAUDE\.md|session log|session-log|handoff|touches\[\]|methodology|ADR \d|done-when|criterion)\b/i;
+// Real edits to files = work (the change itself).
+const WORK_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit']);
+
+// Footgun snippet signatures (the #506 worked example seeds these).
+const API_ERROR_RE = /\b(bad_kind|bad_discipline|status_not_patchable|no_supported_fields|must be one of|_required|cannot_promote|task_not_gradable)\b|"error":|\b(400|409|422)\b/i;
+const TEST_FAIL_RE = /\b(assert|assertion|expected .* (to|got)|FAIL|smoke .*fail|test.*fail|\d+ failed)\b/i;
+const PANEL_RE = /panel of \d+ workers?/i;
+const EMPTY_DIFF_RE = /nothing to grade|empty.*(diff|commit)|diff.*empty/i;
+const CLAIM_FAIL_RE = /grade not passed|don't have an active claim|no active claim|stays at completed/i;
+// Wrong-path / wrong-worktree — the June 2026 corpus's #1 error class (84 hits):
+// a Read/Edit/Bash aimed at a path that isn't on THIS tree (the worktree ↔
+// main-checkout split, feedback_edit_under_worktree_path), a require() with the
+// wrong relative path, or a tool the box lacks on PATH. These are navigation
+// mistakes, not genuine first-time absences — distinct from the API-guess class.
+const WRONG_PATH_RE =
+  /\bEISDIR\b|cannot find module|command not found:\s*(psql|timeout|node|npm|gh|jq)\b|File does not exist|no such file or directory/i;
+// Off-task wandering (task 1268): the agent OFFERING to open a new thread beyond
+// the claim — "want me to investigate…", "should I dig into…", "worth a closer
+// look". This is the escalation the wandering knob suppresses (the phantom
+// "credit discrepancy → want me to dig in?" derailment). Deliberately
+// high-precision (the offer-to-pursue framing, not bare mentions) so the signal
+// is trustworthy; only scored for constraining-default ranks (see detectFootguns).
+const OFF_TASK_WANDER_RE =
+  /\b(want me to|should i|shall i|do you want me to|would you like me to)\b[^.?!\n]{0,48}\b(investigate|look into|dig into|dig in|explore|chase|track (?:it|this|that) down)\b|\bworth (?:investigating|a (?:closer |second )?look|looking into)\b/i;
+
+function turnTokens(t) {
+  return (t.in || 0) + (t.out || 0) + (t.cache_read || 0) + (t.cache_creation || 0);
+}
+
+// classifyTurn — bucket one ASSISTANT turn into work | ceremony | recovery.
+// `prevWasError` = the immediately preceding tool_result carried an error, so
+// this turn is spent recovering. Pure.
+function classifyTurn(turn, opts = {}) {
+  if (opts.prevWasError) return 'recovery';
+  const tools = Array.isArray(turn.tools) ? turn.tools : [];
+  if (tools.some((t) => WORK_TOOLS.has(t))) return 'work';
+  const snippet = typeof turn.snippet === 'string' ? turn.snippet : '';
+  const drivesPlumbing = tools.includes('Bash') && GDS_PLUMBING_RE.test(snippet);
+  if (drivesPlumbing || METHODOLOGY_RE.test(snippet)) return 'ceremony';
+  return 'work'; // reading / reasoning toward the task
+}
+
+// computeOverhead — single pass over the per-turn detail. Token-weights the
+// ASSISTANT turns (only they carry model usage); user turns drive the
+// prevWasError flag + recovery turn-count. Pure.
+function computeOverhead(detail) {
+  const b = {
+    work: { tokens: 0, turns: 0 },
+    ceremony: { tokens: 0, turns: 0 },
+    recovery: { tokens: 0, turns: 0 },
+  };
+  let recoveryUserTurns = 0;
+  let prevWasError = false;
+  for (const turn of Array.isArray(detail) ? detail : []) {
+    if (!turn || typeof turn !== 'object') continue;
+    if (turn.role === 'user') {
+      if ((turn.tool_errors || 0) > 0) {
+        recoveryUserTurns++;
+        prevWasError = true;
+      } else {
+        prevWasError = false;
+      }
+      continue;
+    }
+    if (turn.role === 'assistant') {
+      const bucket = classifyTurn(turn, { prevWasError });
+      b[bucket].tokens += turnTokens(turn);
+      b[bucket].turns += 1;
+      prevWasError = false;
+    }
+  }
+  const totalTokens = b.work.tokens + b.ceremony.tokens + b.recovery.tokens;
+  const overheadTokens = b.ceremony.tokens + b.recovery.tokens;
+  // Turn-weighted overhead (task 961): the token weighting scores cache-heavy
+  // marathons (150M+ tokens, mostly cache reads) as 97–99% "work" even when the
+  // turn sequence is hours of ceremony — the BFG goes blind to exactly the
+  // sessions that bleed most. Counting each assistant turn equally (regardless of
+  // its cache-inflated token total) restores visibility. Reported alongside the
+  // token metric; the verdict is driven off this one (see verdictFor caller).
+  const totalTurns = b.work.turns + b.ceremony.turns + b.recovery.turns;
+  const overheadTurns = b.ceremony.turns + b.recovery.turns;
+  return {
+    buckets: b,
+    recoveryUserTurns,
+    totalAssistantTokens: totalTokens,
+    totalAssistantTurns: totalTurns,
+    overheadRatio: totalTokens > 0 ? overheadTokens / totalTokens : 0,
+    workRatio: totalTokens > 0 ? b.work.tokens / totalTokens : 0,
+    overheadRatioTurns: totalTurns > 0 ? overheadTurns / totalTurns : 0,
+    workRatioTurns: totalTurns > 0 ? b.work.turns / totalTurns : 0,
+  };
+}
+
+// detectFootguns — pattern-match the #506-class waste signatures over the
+// per-turn digest. `overhead` is the computeOverhead() result, used to qualify
+// the heavyweight-pipeline footgun (panel ran AND the real change was tiny).
+// Returns [{ type, count, evidence }]. Pure.
+function detectFootguns(detail, overhead = {}, opts = {}) {
+  // Filter non-object turns up front (mirrors the guard in computeOverhead) so a
+  // single null/malformed turn can't crash the whole evaluation downstream.
+  const turns = (Array.isArray(detail) ? detail : []).filter((t) => t && typeof t === 'object');
+  const out = [];
+  const push = (type, count, evidence) => {
+    if (count > 0) out.push({ type, count, evidence });
+  };
+
+  // 1. repeated tool failures (errors across the session).
+  const errorTurns = turns.filter((t) => t.role === 'user' && (t.tool_errors || 0) > 0);
+  if (errorTurns.length >= 2) {
+    push('repeated_tool_failures', errorTurns.length, `${errorTurns.length} tool_result errors`);
+  }
+
+  // 2. guess-and-retry on API enums/routes: an error snippet that looks like a
+  //    GDS API validation error (the #514 class). Each is a wasted guess.
+  let apiGuesses = 0;
+  let firstApi = '';
+  for (const t of errorTurns) {
+    if (typeof t.snippet === 'string' && API_ERROR_RE.test(t.snippet)) {
+      apiGuesses++;
+      if (!firstApi) firstApi = t.snippet.slice(0, 80);
+    }
+  }
+  push('guess_and_retry_api', apiGuesses, firstApi);
+
+  // 3. stale-test red herring: a test/smoke failure in an error snippet (#468 class).
+  let testFails = 0;
+  let firstTest = '';
+  for (const t of errorTurns) {
+    if (typeof t.snippet === 'string' && TEST_FAIL_RE.test(t.snippet)) {
+      testFails++;
+      if (!firstTest) firstTest = t.snippet.slice(0, 80);
+    }
+  }
+  push('stale_test_red_herring', testFails, firstTest);
+
+  // 3b. wrong-path / wrong-worktree (the corpus's #1 error class). Like the API
+  //     guess, each is a wasted action aimed at a path/tool not on this tree.
+  let wrongPath = 0;
+  let firstWrong = '';
+  for (const t of errorTurns) {
+    if (typeof t.snippet === 'string' && WRONG_PATH_RE.test(t.snippet)) {
+      wrongPath++;
+      if (!firstWrong) firstWrong = t.snippet.slice(0, 80);
+    }
+  }
+  push('wrong_path_worktree', wrongPath, firstWrong);
+
+  // Snippet-wide scans (assistant + user) for the remaining signatures — one
+  // pass over the snippets counts all three.
+  let panelRuns = 0;
+  let emptyDiff = 0;
+  let claimFail = 0;
+  for (const t of turns) {
+    const s = typeof t.snippet === 'string' ? t.snippet : '';
+    if (!s) continue;
+    if (PANEL_RE.test(s)) panelRuns++;
+    if (EMPTY_DIFF_RE.test(s)) emptyDiff++;
+    if (CLAIM_FAIL_RE.test(s)) claimFail++;
+  }
+  // 4. heavyweight-pipeline-on-trivial-change (the #513 class). The footgun is
+  //    the full grader panel running on a TRIVIAL change. The session digest has
+  //    no diff size, so we proxy "trivial" with a tiny work bucket (few/small
+  //    real edits): a panel that ran while almost no real work happened.
+  if (panelRuns > 0) {
+    const workTurns = overhead && overhead.buckets ? overhead.buckets.work.turns : 0;
+    if (workTurns <= 2) {
+      push('heavyweight_pipeline_on_trivial_change', panelRuns, `panel ran with only ${workTurns} work turn(s)`);
+    }
+  }
+  // 5. empty-diff grade attempt.  6. claim consumed on a failed grade.
+  push('empty_diff_grade', emptyDiff, '');
+  push('claim_consumed_on_fail', claimFail, '');
+
+  // 7. off-task wandering (task 1268): the agent offering to open a NEW THREAD
+  //    beyond the claim. ONLY a footgun for builders whose rank default is a
+  //    CONSTRAINING wandering level (Xenos→Locked, Thetes→Focused); for Metic+
+  //    (Balanced/Exploratory by default) surfacing tangents is the intended
+  //    behavior, so it's not flagged. Rank is the available proxy for the
+  //    effective level — the digest doesn't carry the resolved knob yet, so
+  //    level-relative per-builder scoring is the follow-up (needs the digest to
+  //    capture wandering + the §6C per-builder delivery path). Unknown/absent
+  //    rank → not scanned (conservative; avoids false positives).
+  const rank = opts.rank;
+  const rankConstrains = rank
+    && Object.prototype.hasOwnProperty.call(wanderingPrefs.RANK_DEFAULT, rank)
+    && wanderingPrefs.shouldInject(wanderingPrefs.defaultLevelForRank(rank));
+  if (rankConstrains) {
+    let wander = 0;
+    let firstWander = '';
+    for (const t of turns) {
+      if (!t || t.role !== 'assistant') continue;
+      const s = typeof t.snippet === 'string' ? t.snippet : '';
+      if (s && OFF_TASK_WANDER_RE.test(s)) {
+        wander++;
+        if (!firstWander) firstWander = s.slice(0, 80);
+      }
+    }
+    push('off_task_wandering', wander, firstWander);
+  }
+
+  // 8. unplain speech (task 1002516). The accessibility dimension is scored by
+  //    modules/sessions/accessibility.js and arrives here already profile-relative
+  //    — an engineer's session waives every signal and scores null, so it can
+  //    never reach this branch. Two guards keep the finding worth reading:
+  //    the rubric's own 6.0 threshold (below it is the 'dense'/'opaque' bands),
+  //    and a sample big enough to stand behind. count is 1 because this is a
+  //    property of the WHOLE session, not a tally of turns.
+  const acc = opts.accessibility;
+  if (acc && acc.score != null && acc.confidence !== 'low' && acc.score < 6) {
+    const worst = (acc.signals || [])
+      .filter((s) => !s.waived && s.penalty > 0)
+      .sort((a, b) => b.penalty - a.penalty)[0];
+    push('unplain_speech', 1, `accessibility ${acc.score}/10 (${acc.band})${worst ? ` — worst signal: ${worst.type}${worst.evidence ? `; ${worst.evidence}` : ''}` : ''}`);
+  }
+
+  return out;
+}
+
+// accessibilityFor — the dimension for one session record. Prefers the score the
+// upload route already computed (it had the builder's real profile in hand);
+// falls back to re-scoring the stored detail for a row uploaded before the
+// dimension existed. The fallback scores at the DEFAULT profile, which is
+// deliberately stated on the result rather than guessed at — a historical row
+// does not carry what the builder's settings were at the time.
+function accessibilityFor(record) {
+  const r = record || {};
+  const stored = r.metrics && typeof r.metrics === 'object' ? r.metrics.accessibility : null;
+  if (stored && typeof stored === 'object') return stored;
+  return { ...scoreAccessibility(Array.isArray(r.detail) ? r.detail : []), rescored: true };
+}
+
+// verdictFor — a coarse label off the overhead ratio, for ranking + reporting.
+function verdictFor(overheadRatio) {
+  if (overheadRatio >= 0.7) return 'wasteful';
+  if (overheadRatio >= 0.4) return 'mixed';
+  return 'efficient';
+}
+
+// evaluateSession — the full deep-dive for one session record (as returned by
+// GET /sessions/:id: summary fields + detail + metrics). Pure.
+function evaluateSession(record) {
+  const r = record || {};
+  const detail = Array.isArray(r.detail) ? r.detail : [];
+  const metrics = r.metrics && typeof r.metrics === 'object' ? r.metrics : {};
+  const overhead = computeOverhead(detail);
+  const accessibility = accessibilityFor(r);
+  const footguns = detectFootguns(detail, overhead, { rank: r.rank, accessibility });
+  return {
+    session_id: r.session_id,
+    builder: r.github_login,
+    rank: r.rank,
+    task_ids: r.task_ids,
+    total_tokens: r.total_tokens,
+    // drachmae_earned (task 722): the credit_log delta attributable to this
+    // session (session_records.drachmae_earned, present since migration 062 — so
+    // past records already carry it; no records-backfill needed, only this
+    // forward-looking read). Surfaced so session efficiency can be weighed
+    // against the reward it produced — a high-overhead session that still earned
+    // a lot is a different story than one that earned nothing.
+    drachmae_earned: Number.isFinite(Number(r.drachmae_earned)) ? Number(r.drachmae_earned) : 0,
+    duration_seconds: r.duration_seconds,
+    overhead_ratio: Number(overhead.overheadRatio.toFixed(3)), // token-weighted (legacy)
+    work_ratio: Number(overhead.workRatio.toFixed(3)),
+    overhead_ratio_turns: Number(overhead.overheadRatioTurns.toFixed(3)), // turn-weighted (verdict driver, task 961)
+    work_ratio_turns: Number(overhead.workRatioTurns.toFixed(3)),
+    buckets: overhead.buckets,
+    recovery_user_turns: overhead.recoveryUserTurns,
+    footguns,
+    // task 1002516 — the accessibility dimension, per builder (the record carries
+    // github_login + rank), scored against THIS builder's own interaction profile.
+    // Advisory: it is reported and coached, and gates nothing.
+    accessibility,
+    // Verdict is driven off the TURN-weighted ratio (task 961) so cache-dominated
+    // marathons can no longer hide their ceremony behind a huge token-work bucket.
+    verdict: verdictFor(overhead.overheadRatioTurns),
+    detail_truncated: !!metrics.detail_truncated,
+  };
+}
+
+// ---- 6D.4: findings delivery ---------------------------------------------
+//
+// Systemic findings → idea_inbox (built here). Per-builder findings → the
+// ADR 0026 §6C transparent BFG-note path, which is NOT built yet (6C.1/6C.2),
+// so they DEGRADE to a report section (findingsByBuilder) until §6C lands.
+
+// One idea_inbox template per systemic footgun class. The #506 fixes
+// (#513/#514/#468) are the worked examples these are modelled on.
+const FINDING_TEMPLATES = {
+  guess_and_retry_api: {
+    title: 'Builders guess-and-retry on GDS API enums/routes — sharpen error messages',
+    body: 'The session evaluator saw repeated guess-and-retry on GDS API validation errors (the #514 pattern: a 4xx with no actionable hint → a wasted retry). Audit write endpoints for self-explaining errors (valid values + the right route in the message).',
+  },
+  heavyweight_pipeline_on_trivial_change: {
+    title: 'Grader panel runs on trivial changes — widen the trivial-diff fast-path',
+    body: 'The session evaluator saw the full grader panel run on near-trivial changes (the #513 pattern). Revisit grader.isTrivialDiff coverage so tiny / copy / docs changes take the single-shot path.',
+  },
+  stale_test_red_herring: {
+    title: 'Stale tests send builders down rabbit holes',
+    body: 'The session evaluator saw test/smoke failures that were red herrings (the #468 pattern: an assertion stale vs the current pipeline). Audit smoke/test assertions for drift.',
+  },
+  repeated_tool_failures: {
+    title: 'Repeated tool failures across sessions — find the common cause',
+    body: 'The session evaluator saw sessions with many repeated tool failures. Look for a shared footgun (env, path, auth) worth a guardrail.',
+  },
+  empty_diff_grade: {
+    title: 'Grader spawned on empty diffs',
+    body: 'The session evaluator saw grader runs attempted on an empty committed diff. The empty-diff guard may need tightening.',
+  },
+  claim_consumed_on_fail: {
+    title: 'Claims consumed on a failed grade (no clean re-grade path)',
+    body: 'The session evaluator saw claims consumed when a grade did not pass, forcing awkward re-grade paths (the #528 / claim-preserving --regrade gap).',
+  },
+  wrong_path_worktree: {
+    title: 'Wrong-path / worktree↔main-checkout confusion — the corpus #1 error class',
+    body: 'The session evaluator saw repeated wrong-path / wrong-worktree failures (File does not exist, EISDIR, Cannot find module, command not found: psql/timeout) — an edit or command aimed at a path/tool not present on this tree (the worktree↔main-checkout split, feedback_edit_under_worktree_path). Make the claim-time context pack push the worktree root + held paths (V4.R04), keep the worktree write guard loud (V4.R13), and ensure the box has psql/timeout on PATH.',
+  },
+  unplain_speech: {
+    title: 'Sessions read as jargon, terminal-first or implementation-framed to the builder they were pitched at (task 1002516)',
+    body: 'The session evaluator scored the accessibility dimension below the 6.0 threshold on sessions whose OWN interaction profile did not sanction it — unexplained SWE vocabulary, a terminal command where the hall already has a click-path, or a trade-off framed as architecture instead of cost, time and what the reader will see. The score is profile-relative (an engineer\'s session waives every signal and is never marked down), so a recurring finding means the accessible-by-default posture is not actually arriving. Sharpen the interaction contract the Conductor injects (modules/builder-settings/interaction-prefs.js), or the click-path table in modules/sessions/accessibility.js if a finding named a UI that does not exist.',
+  },
+  off_task_wandering: {
+    title: 'Off-task wandering — focused-rank agents offering tangents/investigations beyond the claim (task 1268)',
+    body: 'The session evaluator saw a constraining-rank builder (Xenos/Thetes, whose wandering default is Locked/Focused) offered to open a new thread beyond the claim — "want me to investigate…", "worth a closer look" — the escalation the wandering knob suppresses (the motivating phantom "credit discrepancy → want me to dig in?" derailment). If this recurs, sharpen the per-rank wandering contract (src/bongos/wandering-prefs.js) the Conductor injects, or build out the level-relative session penalty (the grade-it layer).',
+  },
+};
+
+// summarizeSystemicFindings — aggregate footguns across the evaluated sessions
+// into systemic findings (a class seen in >= minSessions sessions is systemic,
+// worth one idea_inbox row — conservative, NOT one row per instance). Pure.
+function summarizeSystemicFindings(evaluated, opts = {}) {
+  const minSessions = opts.minSessions || 2;
+  const byType = new Map();
+  for (const e of Array.isArray(evaluated) ? evaluated : []) {
+    for (const f of (e && e.footguns) || []) {
+      const agg = byType.get(f.type) || { type: f.type, sessions: 0, total: 0, examples: [] };
+      agg.sessions += 1;
+      agg.total += f.count || 1;
+      if (f.evidence && agg.examples.length < 3) agg.examples.push(f.evidence);
+      byType.set(f.type, agg);
+    }
+  }
+  return [...byType.values()]
+    .filter((a) => a.sessions >= minSessions)
+    .sort((a, b) => b.sessions - a.sessions);
+}
+
+// findingsByBuilder — group per-builder findings for the report. These are what
+// 6C.2 will deliver as transparent BFG notes once §6C exists; until then they
+// surface in the report only. Pure.
+function findingsByBuilder(evaluated) {
+  const map = {};
+  for (const e of Array.isArray(evaluated) ? evaluated : []) {
+    if (!e || !e.builder || !(e.footguns && e.footguns.length)) continue;
+    (map[e.builder] = map[e.builder] || []).push({
+      session_id: e.session_id,
+      verdict: e.verdict,
+      overhead_ratio: e.overhead_ratio,
+      footguns: e.footguns.map((f) => f.type),
+    });
+  }
+  return map;
+}
+
+// interpretCorpusSearch — decide whether an EMPTY candidate set from the 6D.2
+// corpus search is benign or an ANOMALY worth a loud, non-zero exit.
+//
+// Why this exists (#608, 2026-06-04): the routine used to treat `0 candidates`
+// as "nothing to do" and write a clean, successful-looking empty report (exit
+// 0). But an empty result has three causes, only some benign:
+//   - genuinely empty corpus (only true at bootstrap)          -> benign, opt in via allowEmpty
+//   - a --min-karma mining pass no builder qualifies for        -> benign, expected
+//   - a transient stale read / upload gap with data present     -> ANOMALY, must surface
+// We hit the third case live (#608): cross-builder search returned 0 while the
+// corpus actually held 6 sessions, then self-corrected seconds later. A silent
+// empty report would have hidden that indefinitely. So the DEFAULT pass (no
+// min-karma) returning empty is an anomaly unless the operator asserts an empty
+// corpus with --allow-empty. Pure.
+function interpretCorpusSearch(count, opts = {}) {
+  const { minKarma = null, allowEmpty = false } = opts;
+  if (count > 0) return { anomaly: false };
+  if (allowEmpty) return { anomaly: false, note: 'empty corpus accepted (--allow-empty)' };
+  if (minKarma != null) return { anomaly: false, note: `no sessions matched min_karma=${minKarma}` };
+  return {
+    anomaly: true,
+    message:
+      'corpus search returned 0 sessions on the default pass. Once any session has shipped this is ' +
+      'unexpected — most likely a transient stale read or an upload gap (see #608), NOT an empty corpus. ' +
+      'Refusing to write a clean empty report. If the corpus really is empty (bootstrap), re-run with --allow-empty.',
+  };
+}
+
+module.exports = {
+  classifyTurn,
+  computeOverhead,
+  detectFootguns,
+  verdictFor,
+  accessibilityFor,
+  evaluateSession,
+  summarizeSystemicFindings,
+  findingsByBuilder,
+  interpretCorpusSearch,
+  FINDING_TEMPLATES,
+};
+
+// ---- CLI (only when run directly) -----------------------------------------
+// Orchestrates: search candidates (6D.2) -> fetch each -> evaluateSession ->
+// rank by overhead -> write docs/audits/bfg-session-eval-<date>.md. Read-only.
+if (require.main === module) {
+  const path = require('node:path');
+  const fs = require('node:fs');
+  const { cliClient } = require('./cli-lib');
+
+  const arg = (name, def) => {
+    const i = process.argv.indexOf(name);
+    return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : def;
+  };
+
+  // Escape a value for a markdown table cell (a stray `|` or newline from an
+  // API-sourced field would otherwise break the table).
+  const cell = (v) => String(v == null ? '' : v).replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ');
+
+  (async () => {
+    const api = await cliClient();
+    const limit = arg('--limit', '15');
+    const order = arg('--order', 'tool_errors');
+    const minKarma = arg('--min-karma', null); // good-practice mining: top performers
+    const dateStamp = arg('--date', null);
+    // --date is interpolated into a file path below, so constrain it to a plain
+    // ISO date — a crafted value (slashes / ..) could otherwise escape docs/audits.
+    if (dateStamp && !/^\d{4}-\d{2}-\d{2}$/.test(dateStamp)) {
+      console.error('--date must be YYYY-MM-DD');
+      process.exit(1);
+    }
+    // 1. candidate selection via 6D.2 search (stored facets only). --min-karma
+    //    pulls in top performers for good-practice mining (ADR 0026 §6B).
+    const searchQuery = { order, limit };
+    if (minKarma != null) searchQuery.min_karma = minKarma;
+    // Retry an empty result a few times before believing it: the corpus search
+    // has been observed to return 0 transiently (a stale read post-outage, #608)
+    // and self-correct within seconds. Only the default pass retries — a
+    // --min-karma mining pass legitimately returns empty, so don't waste time.
+    const allowEmpty = process.argv.includes('--allow-empty');
+    const maxAttempts = minKarma == null ? 3 : 1;
+    let candidates = [];
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const search = await api.sessions.getSessionsSearch({ query: searchQuery });
+      if (!search.ok) {
+        console.error(`search failed (${search.status}):`, search.data && search.data.error);
+        process.exit(1);
+      }
+      candidates = (search.data && search.data.sessions) || [];
+      if (candidates.length > 0 || attempt === maxAttempts) break;
+      console.error(`search returned 0 candidates (attempt ${attempt}/${maxAttempts}) — retrying in 1500ms (possible stale read, #608)...`);
+      await new Promise((r) => setTimeout(r, 1500));
+    }
+    // An empty corpus is an ANOMALY by default (stale read / upload gap), NOT a
+    // clean "nothing to do" — refuse to write a misleadingly-empty report so the
+    // condition surfaces instead of hiding (#608).
+    const corpus = interpretCorpusSearch(candidates.length, { minKarma, allowEmpty });
+    if (corpus.anomaly) {
+      console.error('');
+      console.error('⚠️  BFG session-eval ANOMALY — empty corpus search');
+      console.error(`   ${corpus.message}`);
+      console.error('');
+      process.exit(2);
+    }
+    console.log(`candidates: ${candidates.length} (order=${order}, limit=${limit}${minKarma != null ? `, min_karma=${minKarma}` : ''})${corpus.note ? ` — ${corpus.note}` : ''}`);
+
+    // 2. deep-dive each candidate (parallel fetch — independent reads).
+    const fetched = await Promise.all(
+      candidates.map((c) => api.sessions.getSessionsId({ id: c.id }).catch(() => null))
+    );
+    const evaluated = fetched
+      .filter((f) => f && f.ok && f.data && f.data.session)
+      .map((f) => evaluateSession(f.data.session));
+    // 3. rank by the turn-weighted overhead ratio (the verdict driver, task 961
+    //    — token weighting buries ceremony on cache-heavy marathons). Wasteful first.
+    evaluated.sort((a, b) => b.overhead_ratio_turns - a.overhead_ratio_turns);
+
+    // 4. report.
+    const date = dateStamp || new Date().toISOString().slice(0, 10);
+    const lines = [
+      `# BFG session-inefficiency report — ${date}`,
+      '',
+      `Evaluated ${evaluated.length} candidate session(s) (search order=${order}${minKarma != null ? `, min_karma=${minKarma}` : ''}).`,
+      '',
+      '| session | builder | overhead (turn / tok) | verdict | plain speech | footguns | tokens | drachmae |',
+      '|---|---|---|---|---|---|---|---|',
+    ];
+    for (const e of evaluated) {
+      const fg = cell(e.footguns.map((f) => `${f.type}×${f.count}`).join(', ') || '—');
+      // Turn-weighted % first (the verdict driver), token-weighted % second — so a
+      // cache-heavy marathon that reads "99% work" by tokens is no longer hidden.
+      const oh = `${Math.round((e.overhead_ratio_turns || 0) * 100)}% / ${Math.round((e.overhead_ratio || 0) * 100)}%`;
+      // drachmae_earned alongside the overhead (task 722) so a reviewer can weigh
+      // efficiency against the reward the session produced.
+      // task 1002516: an em dash means NOT SCORED — the builder's own profile
+      // waived every signal — never a zero. `~` marks a score re-derived here at
+      // the default profile because the row predates the dimension.
+      const a = e.accessibility || {};
+      const acc = a.score == null ? '—' : `${a.score}/10 ${a.band}${a.rescored ? ' ~' : ''}${a.confidence === 'low' ? ' (thin)' : ''}`;
+      lines.push(`| ${cell(e.session_id ? e.session_id.slice(0, 8) : '?')} | ${cell(e.builder || '?')} | ${oh} | ${cell(e.verdict)} | ${cell(acc)} | ${fg} | ${e.total_tokens || 0} | ${e.drachmae_earned || 0} |`);
+    }
+    // Systemic findings (footgun classes seen across multiple sessions).
+    const systemic = summarizeSystemicFindings(evaluated);
+    lines.push('');
+    lines.push('## Systemic findings (across sessions)');
+    if (systemic.length === 0) {
+      lines.push('None — no footgun class recurred across multiple sessions.');
+    } else {
+      for (const s of systemic) {
+        const tmpl = FINDING_TEMPLATES[s.type] || { title: s.type };
+        lines.push(`- **${cell(s.type)}** — ${s.sessions} session(s), ${s.total} occurrence(s). ${cell(tmpl.title)}`);
+      }
+      lines.push('');
+      lines.push(process.argv.includes('--file')
+        ? '(Filing these to idea_inbox — see below.)'
+        : '(Re-run with --file to file these as idea_inbox rows.)');
+    }
+
+    // Per-builder findings: these are what ADR 0026 §6C will deliver as
+    // transparent BFG notes once that write path exists (6C.1/6C.2). Until then
+    // they surface here only — NOT written to anyone's memory.
+    const perBuilder = findingsByBuilder(evaluated);
+    const builders = Object.keys(perBuilder);
+    lines.push('');
+    lines.push('## Per-builder findings (held for §6C delivery — not yet written to memory)');
+    if (builders.length === 0) {
+      lines.push('None.');
+    } else {
+      for (const b of builders) {
+        const fset = new Set();
+        for (const row of perBuilder[b]) row.footguns.forEach((t) => fset.add(t));
+        lines.push(`- **${cell(b)}**: ${perBuilder[b].length} flagged session(s); patterns: ${cell([...fset].join(', '))}`);
+      }
+    }
+    lines.push('');
+    lines.push('Read-only: this report proposes. Systemic → idea_inbox (--file); per-builder → §6C when built (6C.1/6C.2).');
+    const body = lines.join('\n');
+
+    const outDir = path.resolve(__dirname, '..', '..', 'docs', 'audits');
+    const dry = process.argv.includes('--dry-run');
+    if (dry) {
+      console.log(body);
+    } else {
+      fs.mkdirSync(outDir, { recursive: true });
+      const file = path.join(outDir, `bfg-session-eval-${date}.md`);
+      fs.writeFileSync(file, body + '\n');
+      console.log(`wrote ${file}`);
+    }
+
+    // 5. (--file) file SYSTEMIC findings to idea_inbox. Deduped by a stable
+    //    title prefix so re-runs don't pile up duplicate rows. Per-builder
+    //    findings are NOT written anywhere (they await §6C — 6C.1/6C.2).
+    if (process.argv.includes('--file') && systemic.length) {
+      const PREFIX = '[session-eval]';
+      const existing = await api.inbox.getInbox({ query: { limit: 200 } }).catch(() => null);
+      const openTitles = (existing && existing.ok && existing.data && existing.data.ideas
+        ? existing.data.ideas.map((i) => String(i.title || ''))
+        : []);
+      let filed = 0;
+      let skipped = 0;
+      // task 1003166 (G02): resolved ONCE — it is invariant for the run, and this
+      // is a network round trip. The first version of this called it per finding.
+      const suggestedVersion = await resolveDefaultVersion();
+      for (const s of systemic) {
+        const tmpl = FINDING_TEMPLATES[s.type] || { title: s.type, body: '' };
+        const title = `${PREFIX} ${tmpl.title}`.slice(0, 200);
+        // Dedup: skip if an open idea already carries this finding's prefix+type.
+        const marker = `${PREFIX} ${tmpl.title}`.slice(0, 60);
+        if (openTitles.some((t) => t.startsWith(marker))) {
+          skipped++;
+          continue;
+        }
+        const bodyMd = `${tmpl.body}\n\nSeen in ${s.sessions} session(s), ${s.total} occurrence(s). Filed by the BFG session-inefficiency evaluator (6D, ADR 0027).`;
+        const r = await api.inbox.postInbox({
+          body: {
+            title,
+            body_md: bodyMd,
+            // task 1003166 (G02): was 'GDS-V4', which has shipped.
+            suggested_version: suggestedVersion,
+          },
+        }).catch(() => null);
+        if (r && r.ok) filed++;
+        else skipped++;
+      }
+      console.log(`idea_inbox: filed ${filed}, skipped ${skipped} (dedup/error) of ${systemic.length} systemic finding(s).`);
+    }
+  })().catch((e) => {
+    console.error('fatal:', e && e.message ? e.message : e);
+    process.exit(1);
+  });
+}