ruvnet-brain 4.4.1 → 4.5.0

package/scripts/onboarding-console.mjs

@@ -48,7 +48,7 @@ import { inspectSessionSnapshots } from './session-snapshot-contract.mjs';
 import { learnings } from './learnings.mjs';
 import { gatesSurvey } from './gates.mjs';
 // The write-safety primitives, borrowed rather than re-implemented. See saveConfig for why.
-import { withLock, writeAtomic, LOCK_WAIT_MS, loadSettings, saveSettings, SETTINGS_SCHEMA as USER_SETTINGS_SCHEMA } from './user-settings.mjs';
+import { withLock, writeAtomic, LOCK_WAIT_MS, loadSettings, saveSettings, revertSettings, SETTINGS_SCHEMA as USER_SETTINGS_SCHEMA } from './user-settings.mjs';
 // The brain on/off switch (ADR-054). The sentinel is the enforcement artifact; settings.json holds
 // only a mirror. The console is the ONE surface allowed to flip it — protect-brain-state.sh walls
 // the file off from agent edits — so both halves of the write live here, in saveBrainPower().
@@ -68,6 +68,7 @@ import {
   openRouterCredentialStatus,
   saveOpenRouterCredential,
   learnerCwd,
+  loadRuntimePreferences,
 } from '../plugin/scripts/runtime-preferences.mjs';
 import { applyNightlyChoice, nightlyStatus } from './nightly-controller.mjs';
 // One canonical answer to "which directory is this, and have I counted it already?" — shared with
@@ -770,6 +771,30 @@ function gatherInventory() {
   };
 }
 
+/**
+ * Keys a project-level <project>/.swarm/ruvnet-brain-settings.json overrides FOR THE RUNTIME THAT
+ * READS IT. runtime-preferences merges that file over the user-level choices, and route-cheap, the
+ * managed-CLI gate (routing, qeFleet) and learn-capture/learn-flush (learningScope) obey the merge.
+ * The console saves user-level values only, so without this a project seeded by "Apply these choices
+ * to new projects" silently ignored every later change made here (RNBC QA 2026-10-01). Only keys whose
+ * consumer honours the project file are reported — advocacy, autoApply and provider are read at user
+ * level by their consumers, so a project value for them changes nothing and is not claimed to.
+ */
+const PROJECT_HONOURED_KEYS = Object.freeze(['routing', 'qeFleet', 'learningScope']);
+function projectOverrides(keys) {
+  try {
+    const prefs = loadRuntimePreferences({ cwd: process.cwd() });
+    if (!prefs.projectInherited) return null;
+    const raw = readJSON(prefs.paths.project) || {};
+    const values = raw.values && typeof raw.values === 'object' ? raw.values : raw;
+    const out = {};
+    for (const key of keys) {
+      if (PROJECT_HONOURED_KEYS.includes(key) && Object.hasOwn(values, key) && prefs.values[key] === values[key]) out[key] = values[key];
+    }
+    return Object.keys(out).length ? { path: prefs.paths.project.replace(CONSOLE_ROOT, '~'), values: out } : null;
+  } catch { return null; }
+}
+
 function gatherConfig() {
   const cfg = readJSON(CONFIG_PATH) || {};
   const credential = openRouterCredentialStatus({ cwd: process.cwd() });
@@ -797,6 +822,7 @@ function gatherConfig() {
     // What the project would pick FOR you, kept separate from what you actually picked. The form can
     // then say "recommended: on" without ever claiming that is the current state.
     defaults: { provider: 'auto', nightly: true, routing: 'auto', qeFleet: false },
+    projectOverrides: projectOverrides(CONFIG_SCHEMA.map((field) => field.key)),
     schema: CONFIG_SCHEMA.filter((field) =>
       !Object.hasOwn(CONFIG_CONTROL_SUPPORT, field.key)
       && (field.key !== 'nightly' || schedule.artifact.supported)),
@@ -841,6 +867,7 @@ function gatherAdvocacy() {
       Object.hasOwn(chosen, field.key) ? state.values[field.key] : null,
     ])),
     defaults: Object.fromEntries(LIVE_USER_FIELDS.map((field) => [field.key, field.default])),
+    projectOverrides: projectOverrides(LIVE_USER_SETTING_KEYS),
     schema: LIVE_USER_FIELDS,
     unavailable: [],
   };
@@ -880,8 +907,19 @@ function saveAdvocacy(values) {
   const result = saveSettings(supplied);
   if (!result.ok) return { ok: false, rejected: result.errors || [], log: result.log };
   publishSettingsToCache();
+  // THE SAVE IS REVERSIBLE FROM WHERE IT WAS MADE. The Settings card promises "every save is
+  // reversible", and saveSettings already writes the backup and the existedBefore flag its own
+  // revertSettings() consumes — but this form returned no undo token, so the console showed an Undo
+  // button for config.json and none here (RNBC QA 2026-10-01). Journalled only after the write.
+  const undoToken = journalUndo({
+    kind: 'restore-user-settings',
+    file: result.file,
+    backup: result.backup,
+    existedBefore: result.existedBefore,
+  });
   return {
     ok: true,
+    undoToken,
     backup: result.backup ? result.backup.replace(CONSOLE_ROOT, '~') : null,
     values: Object.fromEntries(LIVE_USER_SETTING_KEYS.map((key) => [key, result.values[key]])),
     log: result.log,
@@ -1113,6 +1151,14 @@ function publishSettingsToCache() {
     if (!c || !c.data || !c.data.sections) return;
     c.data.sections.config = gatherConfig();
     c.data.sections.userSettings = gatherAdvocacy();
+    // The Savings card reads two of the same choices (routing, and whether an OpenRouter key exists).
+    // Patching only Settings left the Savings card saying "No key added" / the old routing state on
+    // the next reload, beside a Settings card saying the opposite (RNBC QA 2026-10-01).
+    if (c.data.sections.savings) {
+      const cfgNow = readJSON(CONFIG_PATH) || {};
+      c.data.sections.savings.routing = cfgNow.routing === 'off' ? 'off' : cfgNow.routing === 'auto' ? 'auto' : null;
+      try { c.data.sections.savings.routerEngine = gatherRouterEngine(); } catch { /* the refresh replaces it */ }
+    }
     writeCache(STATE_CACHE, new Date(0).toISOString(), c.data, c.scope ?? null);
   } catch { /* the authoritative stores are already correct; refresh will replace an unreadable cache */ }
 }
@@ -1199,7 +1245,13 @@ function gatherLessons() {
     const trig = TRIGGER_BY_KEY.get(l.trigger);
     const meaning = ENFORCEMENT_MEANING[l.enforcement] || { label: l.enforcement, detail: '' };
     const userStated = l.origin === ORIGIN.USER_STATED && l.sourceClass === SOURCE_CLASS.CURRENT_USER;
-    const quarantined = l.sourceClass === SOURCE_CLASS.IMPORTED_OWNER || l.sourceClass === SOURCE_CLASS.DEMONSTRATION;
+    // Quarantine is about whether history can BECOME policy, so it applies to an imported row that
+    // was never ratified. A row that WAS ratified is delivered by lessonsFor() today whatever its
+    // source class — RNBC QA 2026-10-01 measured 12 such rows filed here as "quarantined, cannot be
+    // switched on" behind a checked, disabled box while the gate enforced every one of them. A rule in
+    // force must be reported in force and must keep a working off switch.
+    const importedClass = l.sourceClass === SOURCE_CLASS.IMPORTED_OWNER || l.sourceClass === SOURCE_CLASS.DEMONSTRATION;
+    const quarantined = importedClass && l.status !== STATUS.RATIFIED && l.status !== STATUS.ACTIVE;
     const origin = l.sourceClass === SOURCE_CLASS.CURRENT_USER
       ? 'you taught me this'
       : l.sourceClass === SOURCE_CLASS.IMPORTED_OWNER
@@ -1234,7 +1286,7 @@ function gatherLessons() {
       // Honest ceiling: ratifying a model-inferred lesson can NOT raise it to block
       // (lesson-store.mjs:380). Say so before they click, not after.
       canReachBlock: userStated,
-      canRatify: !quarantined,
+      canRatify: !importedClass,
       intendedEnforcement: l.intendedEnforcement || null,
     };
   });
@@ -1969,8 +2021,12 @@ function gatherRouterEngine() {
   const cfg = readJSON(CONFIG_PATH) || {};
   // User-constraint detection (Brain-side by design — a fact about THIS user, not routing logic):
   // an OpenRouter key decides whether metered cross-provider candidates are even reachable.
-  let openrouterKey = !!process.env.OPENROUTER_API_KEY;
-  if (!openrouterKey) openrouterKey = !!(cfg.openrouterKey && String(cfg.openrouterKey).length > 8);
+  // The SAME reader the Settings card uses (env → SOPS+age store → legacy plaintext). This read only
+  // env + plaintext, so a key saved through Settings (encrypted, plaintext retired) showed "No key
+  // added" here under a Settings row saying "•••• set" (RNBC QA 2026-10-01).
+  let openrouterKey = false;
+  try { openrouterKey = openRouterCredentialStatus({ cwd: process.cwd() }).configured === true; }
+  catch { openrouterKey = !!process.env.OPENROUTER_API_KEY || !!(cfg.openrouterKey && String(cfg.openrouterKey).length > 8); }
   // House (issue #21): three mechanisms used to disagree — Settings wrote config.json's `provider`,
   // but the chip strip derived "yours" from whichever pool candidate happened to be
   // subscriptionCovered first, sourced from profile.json (a file nothing in the console writes). The
@@ -2383,7 +2439,7 @@ function gatherStack() {
   const rows = a.rows.map((r) => ({ name: r.name, installed: r.installed, target: r.target, tag: r.tag, state: r.state, source: r.source ?? 'npm-global', marketplace: r.marketplace ?? null }));
   const shadows = a.shadows.map((s) => ({ name: s.name, version: s.version, global: s.global, dir: String(s.dir).replace(SYSTEM_HOME, '~'), stale: !!(s.global && s.version !== s.global) }));
   const by = (st) => rows.filter((r) => r.state === st).length;
-  const summary = { total: rows.length, behind: by('BEHIND'), broken: by('BROKEN'), ahead: by('AHEAD'), current: by('CURRENT'), unresolved: by('UNRESOLVED'), shadows: shadows.length, stale: a.stale.length };
+  const summary = { total: rows.length, behind: by('BEHIND'), broken: by('BROKEN'), ahead: by('AHEAD'), current: by('CURRENT'), unresolved: by('UNRESOLVED'), unverified: by('INSTALLED_UNVERIFIED'), shadows: shadows.length, stale: a.stale.length };
   const recommendations = buildStackRecommendations({ rows: a.rows, stale: a.stale });
   const result = { error: a.error, packages: rows, shadows, summary, recommendations };
   // Cache the last good audit so repeat page-loads render instantly ("as of HH:MM — re-checking").
@@ -2708,7 +2764,12 @@ function saveConfig(values) {
     credentialChange = saveOpenRouterCredential(requestedSecret, { cwd: process.cwd() });
     if (!credentialChange.ok) return { ok: false, rejected, log: credentialChange.log };
   }
-  if (requestedNightly !== undefined) {
+  // The page sends every field the person has ever chosen, so changing only the model house carries the
+  // already-saved nightly value with it. Re-running the installer for a choice the scheduler already
+  // satisfies rewrote the plist and re-registered the runner on every unrelated save (RNBC review
+  // 2026-10-01). Only a request that differs from the measured scheduler state is a scheduler change; a
+  // degraded or unknown state still goes to the installer, which is how it gets repaired.
+  if (requestedNightly !== undefined && nightlyStatus().state !== (requestedNightly ? 'on' : 'off')) {
     nightlyChange = applyNightlyChoice(requestedNightly);
     if (!nightlyChange.ok) {
       rollbackCredential();
@@ -2809,6 +2870,10 @@ function undo(undoToken) {
   if (!fs.existsSync(UNDO_JOURNAL)) return { ok: false, log: 'no undo history' };
   const journal = readUndoJournal();
   const entry = journal.find((e) => e.token === undoToken);
+  // "Saved again after this point" is decided by POSITION in the append-only journal, never by the `at`
+  // stamp: it has millisecond resolution and two saves do land in the same millisecond (a Linux runner,
+  // 2026-10-01), which made the later save invisible and let a stale undo wipe it.
+  const savedLater = (kind) => journal.slice(journal.indexOf(entry) + 1).some((e) => e.kind === kind && e.token && e.token !== undoToken);
   if (!entry) return { ok: false, log: 'that undo token was not found' };
 
   // ONE UNDO, ONCE. The token was never consumed, so the same button replayed forever: clicking it
@@ -2829,7 +2894,7 @@ function undo(undoToken) {
     // An undo can only speak for the last write. If something was written after it, the honest answer
     // is to refuse and say so — restoring anyway would be destroying newer data while claiming to
     // protect older data.
-    const laterSave = journal.some((e) => e.kind === 'restore-config' && e.at > entry.at && e.token !== undoToken);
+    const laterSave = savedLater('restore-config');
     if (laterSave) {
       return { ok: false, log: 'your settings were saved again after this point, so this undo would wipe out that newer save — nothing was changed. Use the undo from the most recent save, or restore a backup by hand.' };
     }
@@ -2869,6 +2934,19 @@ function undo(undoToken) {
     }
     return { ok: false, log: 'no backup available to restore' };
   }
+  if (entry.kind === 'restore-user-settings') {
+    // Same "an undo speaks only for the last write" rule as restore-config: a later save through this
+    // form would be wiped out by restoring an older backup.
+    const laterSave = savedLater('restore-user-settings');
+    if (laterSave) {
+      return { ok: false, log: 'your settings were saved again after this point, so this undo would wipe out that newer save — nothing was changed. Use the undo from the most recent save.' };
+    }
+    const r = revertSettings({ file: entry.file, backup: entry.backup || undefined, existedBefore: entry.existedBefore });
+    if (!r.ok) return { ok: false, log: r.log };
+    markUndoConsumed(undoToken);
+    publishSettingsToCache();
+    return { ok: true, log: entry.backup ? 'restored your previous settings' : 'removed the settings file (there was none before this save)' };
+  }
   // EVERY branch below marks its token consumed on success, for the reason spelled out on the
   // restore-config branch above: these all copy a saved snapshot over a live file, so replaying one
   // re-applies an old state over whatever the user has done since. The replay guard at the top of
@@ -2953,7 +3031,7 @@ function undo(undoToken) {
 // The undo kinds this function actually implements. Exported so the closure test can check the
 // registry against the REAL handler set rather than a hand-copied list that would drift from it.
 export const HANDLED_UNDO_KINDS = Object.freeze([
-  'restore-config', 'reinstall-version', 'restore-backup',
+  'restore-config', 'restore-user-settings', 'reinstall-version', 'restore-backup',
   'restore-memory-backup', 'restore-store-backups', 'restore-project-distill', 'auto-rebuild', 'none',
 ]);
 
@@ -2962,7 +3040,10 @@ const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; cha
 function serveStatic(req, res) {
   const rel = decodeURIComponent(req.url.split('?')[0]).replace(/^\/+/, '') || 'index.html';
   const file = path.join(CONSOLE_DIR, rel);
-  if (!file.startsWith(CONSOLE_DIR) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) return send(res, 404, 'text/plain', 'not found');
+  // Containment by path, not by string prefix: `startsWith(CONSOLE_DIR)` also accepted a sibling such
+  // as `<root>/console-anything/…` reached with an encoded `..` (RNBC review 2026-10-01).
+  const inside = path.relative(CONSOLE_DIR, file);
+  if (!inside || inside === '..' || inside.startsWith(`..${path.sep}`) || path.isAbsolute(inside) || !fs.existsSync(file) || fs.statSync(file).isDirectory()) return send(res, 404, 'text/plain', 'not found');
   let body = fs.readFileSync(file);
   const ext = path.extname(file);
   if (ext === '.html') body = Buffer.from(String(body).replace('</head>', `<script>window.__CONSOLE_TOKEN__=${JSON.stringify(TOKEN)}</script></head>`));
@@ -3444,6 +3525,8 @@ export {
   saveBrainPower,
   gatherBrainProfile,
   saveBrainProfile,
+  setLesson,
+  gatherLessons,
   gatherRouterEngine,
   autoEligibleIds,
   gatherConfig,

package/scripts/oracle/abstain-threshold-sweep.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/abstain-threshold-sweep.mjs — what would moving the abstain threshold do?
+ *
+ * The product abstains when the top cross-encoder logit is below 0. The threshold is applied AFTER
+ * scoring, so replaying a measured run at another threshold t is exact for the top citation: no
+ * model is re-run. For each t it reports, with 95% Wilson intervals:
+ *   (abstained = no citation, or a numeric top logit < t -- the rule both harnesses apply)
+ *   needs        confident hits (gold or pre-registered alternative within 5 AND top logit >= t),
+ *                confident misses (top logit >= t but neither within 5), their precision, and how
+ *                many confident answers at least cite the gold repository first
+ *   offTopic     adversarial questions still abstained (no citation, or top logit < t)
+ *   heldOut      routed passes of the named/described/scenario strata (grounded AND routed AND
+ *                a citation with logit >= t), the gated eval-brain metric
+ *
+ *   node scripts/oracle/abstain-threshold-sweep.mjs --needs <needs.json> --adversarial <adversarial.json>
+ *     --heldout <heldout.json> [--thresholds 0,-1,-2,-3,-4] [--out <file>]
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { wilson } from '../eval-brain.mjs';
+
+const rate = (k, n) => { const w = wilson(k, n); return { k, n, p: +w.p.toFixed(4), lo: +w.lo.toFixed(4), hi: +w.hi.toFixed(4) }; };
+const within5 = (r) => (r.fileRank != null && r.fileRank <= 5) || (r.altFileRank != null && r.altFileRank <= 5);
+
+export function sweep({ needs = [], adversarial = [], heldout = [] }, thresholds) {
+  return thresholds.map((t) => {
+    // The abstain rule both harnesses apply (measure-need-set scoreRow, eval-brain gradeQuestion): no
+    // citation, or a NUMERIC top logit below the threshold. A citation without a logit (a card answer)
+    // is not an abstention.
+    const answered = (cited, ce) => Boolean(cited) && !(typeof ce === 'number' && ce < t);
+    const confident = needs.filter((r) => answered(r.cited, r.topCe));
+    const hits = confident.filter(within5).length;
+    const routedRows = heldout.filter((r) => ['named', 'described', 'scenario'].includes(r.stratum));
+    return {
+      threshold: t,
+      needs: { confidentHit: rate(hits, needs.length), confidentMiss: rate(confident.length - hits, needs.length),
+        precision: rate(hits, confident.length),
+        // Weaker than a file hit: the top citation is at least from the gold repository.
+        confidentRightRepo: rate(confident.filter((r) => r.repoRank === 1).length, confident.length) },
+      offTopicAbstain: rate(adversarial.filter((r) => !answered(r.citedPath, r.ce)).length, adversarial.length),
+      heldOutRouted: rate(routedRows.filter((r) => r.grounded && r.routed && answered(r.citedPath, r.ce)).length, routedRows.length),
+    };
+  });
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const arg = (n) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : undefined; };
+  const read = (f) => (f ? JSON.parse(fs.readFileSync(f, 'utf8')).rows : []);
+  const thresholds = String(arg('--thresholds') || '0,-0.5,-1,-1.5,-2,-3,-4').split(',').map(Number);
+  const out = { kind: 'ruvnet-brain-abstain-threshold-sweep',
+    rows: sweep({ needs: read(arg('--needs')), adversarial: read(arg('--adversarial')), heldout: read(arg('--heldout')) }, thresholds) };
+  if (arg('--out')) fs.writeFileSync(arg('--out'), `${JSON.stringify(out, null, 1)}\n`);
+  const f = (m) => `${m.k}/${m.n} [${(100 * m.lo).toFixed(1)}-${(100 * m.hi).toFixed(1)}]`;
+  for (const r of out.rows) {
+    console.log(`t=${r.threshold}: needs hit ${f(r.needs.confidentHit)} miss ${f(r.needs.confidentMiss)} precision ${f(r.needs.precision)} right-repo ${f(r.needs.confidentRightRepo)} | off-topic abstain ${f(r.offTopicAbstain)} | held-out routed ${f(r.heldOutRouted)}`);
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/oracle/abstain-trace.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/abstain-trace.mjs — WHY does the reranker abstain on a novice need whose gold
+ * repository WAS searched?
+ *
+ * For each need it measures, in the gold store, with the production models:
+ *   poolRank       rank of the gold file among the store's dense pool (searchKb, depth --pool)
+ *   ceProduction   cross-encoder logit on the text production reranks (the assembled document, which
+ *                  the reranker reads only through its first 3000 chars / 512 tokens)
+ *   ceBestChunk    best logit over the gold file's own sidecar chunks, each read on its own
+ *   ceSpan         logit on the verbatim gold span the question was written from (an upper bound:
+ *                  the answer text itself, nothing else)
+ *   ceTopProd      production's top logit for this need (from the measured needs run)
+ * and classifies the abstention:
+ *   not-in-pool        dense retrieval never surfaced the gold file
+ *   window             gold scores >= 0 on some chunk but < 0 on the text production reads
+ *   calibration        even the verbatim span scores < 0: the model, not the window, says "irrelevant"
+ *   chunking           span >= 0 but every stored chunk < 0 (the answer is split across chunks)
+ *   outranked          production text >= 0, yet the top citation is another file
+ *
+ *   node scripts/oracle/abstain-trace.mjs --kb <kbDir> --set <need-set.json> --rows <needs.json>
+ *     [--runtime <dir>] [--keyword 8] [--sample 20] [--pool 64] [--out <file>]
+ *
+ * --rows is a measure-need-set output (it supplies reposSearched and the production top logit);
+ * only needs whose gold repository was searched are traced. Nothing written contains a local path.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const args = process.argv.slice(2);
+const arg = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
+
+export function classify({ poolRank, ceProduction, ceBestChunk, ceSpan }) {
+  if (poolRank == null) return 'not-in-pool';
+  if (ceProduction >= 0) return 'outranked';
+  if (ceBestChunk >= 0) return 'window';
+  if (ceSpan < 0) return 'calibration';
+  return 'chunking';
+}
+
+/** Deterministic sample: every step-th need of the eligible list, spread over the whole list. */
+export function sampleEvenly(list, n) {
+  if (list.length <= n) return list;
+  const step = list.length / n;
+  return Array.from({ length: n }, (_, i) => list[Math.floor(i * step)]);
+}
+
+async function chunksOf(kb, store, file) {
+  const out = [];
+  for (const name of [`${store}.passages.jsonl`, `${store}.big.passages.jsonl`]) {
+    const p = path.join(kb, name);
+    if (!fs.existsSync(p)) continue;
+    const rl = readline.createInterface({ input: fs.createReadStream(p), crlfDelay: Infinity });
+    for await (const line of rl) {
+      if (!line.includes(file)) continue;
+      try { const r = JSON.parse(line); if (r.path === file) out.push(String(r.text || '')); } catch { /* skip */ }
+    }
+    if (out.length) break;
+  }
+  return out;
+}
+
+async function main() {
+  const kb = arg('--kb');
+  const set = JSON.parse(fs.readFileSync(arg('--set'), 'utf8'));
+  const rows = JSON.parse(fs.readFileSync(arg('--rows'), 'utf8')).rows;
+  const poolDepth = Number(arg('--pool', 64));
+  const want = Number(arg('--sample', 20));
+  const byId = new Map(set.questions.map((q) => [q.id, q]));
+  // The runtime is the KB directory's own copy of the reader (as in production), unless --runtime
+  // names another directory holding forge-ask.mjs / forge-rerank.mjs and their node_modules.
+  const runtime = path.resolve(arg('--runtime', kb));
+  const { searchKb } = await import(pathToFileURL(path.join(runtime, 'forge-ask.mjs')).href);
+  const { rerankPairs } = await import(pathToFileURL(path.join(runtime, 'forge-rerank.mjs')).href);
+  // --keyword N also counts the keyword lane (keyword-lane.mjs in the runtime) as part of the pool.
+  const keywordTopN = Number(arg('--keyword', 0));
+  const keywordCandidates = keywordTopN > 0
+    ? (await import(pathToFileURL(path.join(runtime, 'keyword-lane.mjs')).href)).keywordCandidates : null;
+  const ce = async (query, texts) => {
+    if (!texts.length) return [];
+    const scored = await rerankPairs(query, texts.map((t, i) => ({ fullText: t, i })));
+    const out = new Array(texts.length);
+    for (const s of scored) out[s.i] = s.ceScore;
+    return out;
+  };
+  const eligible = rows.filter((r) => (r.reposSearched || []).some((s) => s.toLowerCase() === r.repo.toLowerCase()));
+  const traced = [];
+  for (const r of eligible) {
+    const q = byId.get(r.id);
+    const store = r.repo.toLowerCase();
+    const hits = await searchKb({ dir: kb, name: store, query: q.need, k: poolDepth, n: poolDepth });
+    const idx = hits.findIndex((h) => h.path === q.path);
+    let lane = idx < 0 ? null : 'dense';
+    let gold = idx < 0 ? null : hits[idx];
+    if (!gold && keywordCandidates) {
+      const kw = keywordCandidates(kb, store, q.need, { topN: keywordTopN, exclude: new Set(hits.map((h) => h.path)) });
+      const k = kw.findIndex((c) => c.path === q.path);
+      if (k >= 0) { gold = kw[k]; lane = 'keyword'; }
+    }
+    traced.push({ r, q, store, gold, lane, poolRank: idx < 0 ? (gold ? poolDepth + 1 : null) : idx + 1 });
+    process.stderr.write(`\r[abstain-trace] pool ${traced.length}/${eligible.length}`);
+  }
+  const inPool = traced.filter((t) => t.poolRank != null);
+  const sample = sampleEvenly(inPool, want);
+  const out = [];
+  for (const t of sample) {
+    const { gold } = t;
+    const chunks = await chunksOf(kb, t.store, t.q.path);
+    const [ceProduction] = await ce(t.q.need, [gold.fullText || gold.text || '']);
+    const chunkScores = await ce(t.q.need, chunks);
+    const [ceSpan] = await ce(t.q.need, [t.q.span || '']);
+    const row = {
+      id: t.q.id, repo: t.r.repo, need: t.q.need, poolRank: t.poolRank, lane: t.lane,
+      ceProduction: +ceProduction.toFixed(3),
+      ceBestChunk: chunkScores.length ? +Math.max(...chunkScores).toFixed(3) : null,
+      chunks: chunks.length, goldDocChars: (gold.fullText || '').length,
+      ceSpan: +ceSpan.toFixed(3), ceTopProd: t.r.topCe, prodTop: t.r.topPath, prodAbstained: t.r.abstained,
+    };
+    row.cause = classify(row);
+    out.push(row);
+    process.stderr.write(`\r[abstain-trace] ce ${out.length}/${sample.length}   `);
+  }
+  const count = (k) => out.filter((x) => x.cause === k).length;
+  const report = {
+    kind: 'ruvnet-brain-abstain-trace', poolDepth,
+    eligible: eligible.length, goldInPool: inPool.length, goldViaKeyword: traced.filter((t) => t.lane === 'keyword').length, notInPool: traced.length - inPool.length, sampled: out.length,
+    causes: Object.fromEntries(['not-in-pool', 'window', 'calibration', 'chunking', 'outranked'].map((k) => [k, count(k)])),
+    rows: out,
+    poolRanks: traced.map((t) => ({ id: t.q.id, poolRank: t.poolRank })),
+  };
+  const file = arg('--out');
+  if (file) fs.writeFileSync(file, `${JSON.stringify(report, null, 1)}\n`);
+  console.log(JSON.stringify({ ...report, rows: undefined, poolRanks: undefined }, null, 1));
+  process.exit(0);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/oracle/doc2query-generate.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * scripts/oracle/doc2query-generate.mjs — ADR-099 arm A, generation: newcomer-style questions per
+ * documentation file ("doc2query"), produced ONCE where the corpus is built, never on a customer
+ * machine.
+ *
+ * The generator sees only the file's title, path and opening text, never the need set. Each question
+ * must describe a NEED in plain words. Deterministic checks drop any question that:
+ *   - names the product, the repository or a code identifier, or
+ *   - shares more than 3 consecutive words with the excerpt
+ * (the need-set producer's leak rules). Output is append-only JSONL
+ * {store, path, questions[], rejected}, so a run can be resumed and interrupted runs keep their work.
+ *
+ *   node scripts/oracle/doc2query-generate.mjs --kb <kbDir> --stores ruflo,ruvector,ruview --out <file.jsonl>
+ *     [--kind md] [--per-file 3] [--batch 25] [--model haiku] [--limit N] [--conc 2]
+ *
+ * Children run with scripts/subscription-hosts.mjs#subscriptionOnlyEnv (no API billing keys) and the
+ * same minimised-context claude flags as scripts/oracle/producer-hosts.mjs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { claudeArgs, spawnHost, isQuotaRefusal } from './producer-hosts.mjs';
+import { subscriptionOnlyEnv } from '../subscription-hosts.mjs';
+
+export const EXCERPT_CHARS = 1500;
+export const D2Q_SCHEMA = Object.freeze({
+  type: 'object', additionalProperties: false,
+  properties: { items: { type: 'array', items: { type: 'object', additionalProperties: false,
+    properties: { docId: { type: 'string' }, questions: { type: 'array', items: { type: 'string' } } },
+    required: ['docId', 'questions'] } } },
+  required: ['items'],
+});
+export const D2Q_SYSTEM = 'You write search questions for documentation. You see only the documents in the message, '
+  + 'you have no tools, and you use no outside knowledge. Return only the structured output.';
+
+export function d2qPrompt(docs, perFile) {
+  return [
+    `For each DOC below write ${perFile} different questions that a newcomer might type into a search box, `
+      + 'where this document is what would help them.',
+    'Rules for every question:',
+    '- 12-35 words, plain everyday language, describing the person\'s NEED or problem, not the document.',
+    '- The person has never heard of this project: no product, project, repository, package, library or tool names, no code, no identifiers, no file names.',
+    '- Do not copy more than 3 consecutive words from the document.',
+    '- The three questions should cover different things the document helps with.',
+    'Return one item per DOC with its docId copied exactly.',
+    '',
+    ...docs.map((d) => `===DOC docId=${d.docId}\ntitle: ${d.title}\n${d.excerpt}\n===END`),
+  ].join('\n');
+}
+
+const PRODUCT_NAME = /^(?:ruv\w*|ruflo|rufl\w*|ruview|claudeflow|agentdb|agentic|sona|rvf|ruvllm|cognitum|densepose|metaharness|reasoningbank)$/;
+const words = (s) => String(s).toLowerCase().match(/[a-z0-9]+/g) || [];
+/** Longest run of consecutive words a question shares with the excerpt. */
+export function sharedRun(question, excerpt) {
+  const q = words(question);
+  const grams = new Set();
+  const e = words(excerpt);
+  let best = 0;
+  for (let n = 1; n <= q.length; n++) {
+    grams.clear();
+    for (let i = 0; i + n <= e.length; i++) grams.add(e.slice(i, i + n).join(' '));
+    let found = false;
+    for (let i = 0; i + n <= q.length; i++) if (grams.has(q.slice(i, i + n).join(' '))) { found = true; break; }
+    if (!found) break;
+    best = n;
+  }
+  return best;
+}
+
+/** Keep a question only if it obeys the leak rules; return the reason when it does not. */
+export function leakReason(question, { excerpt, store, path: p }) {
+  const q = String(question || '').trim();
+  const n = words(q).length;
+  if (n < 8 || n > 45) return 'length';
+  if (/[`{}<>=]|::|\w\(|\b[a-z]+[A-Z][A-Za-z]+\b|\b\w+\.(?:md|js|ts|rs|py|json|toml)\b|@[a-z0-9-]+\//.test(q)) return 'identifier';
+  // Product names: the store itself and the rUv family's own names (a newcomer has heard none of them).
+  if (words(q).some((w) => w === String(store).toLowerCase() || PRODUCT_NAME.test(w))) return 'names-source';
+  void p;
+  if (sharedRun(q, excerpt) > 3) return 'copies-source';
+  return null;
+}
+
+export function excerptOf(chunks) {
+  return chunks.join('\n\n').slice(0, EXCERPT_CHARS);
+}
+
+function readStoreDocs(kb, store, kind) {
+  const big = path.join(kb, `${store}.big.passages.jsonl`);
+  const file = fs.existsSync(big) ? big : path.join(kb, `${store}.passages.jsonl`);
+  const byPath = new Map();
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    if (!line) continue;
+    let r;
+    try { r = JSON.parse(line); } catch { continue; }
+    if (kind === 'md' && !/\.md$/i.test(r.path)) continue;
+    if (!byPath.has(r.path)) byPath.set(r.path, { title: r.title || path.basename(r.path), chunks: [] });
+    const d = byPath.get(r.path);
+    if (d.chunks.join('').length < EXCERPT_CHARS) d.chunks.push(String(r.text || ''));
+  }
+  return [...byPath.entries()].sort(([a], [b]) => a.localeCompare(b))
+    .map(([p, d]) => ({ store, path: p, title: d.title, excerpt: excerptOf(d.chunks) }));
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const arg = (n, d) => { const i = args.indexOf(n); return i >= 0 ? args[i + 1] : d; };
+  const kb = arg('--kb');
+  const out = arg('--out');
+  const perFile = Number(arg('--per-file', 3));
+  const batchSize = Number(arg('--batch', 25));
+  const conc = Number(arg('--conc', 2));
+  const model = arg('--model', 'haiku');
+  const done = new Set();
+  if (fs.existsSync(out)) {
+    for (const l of fs.readFileSync(out, 'utf8').split('\n')) { try { const r = JSON.parse(l); done.add(`${r.store}|${r.path}`); } catch { /* partial */ } }
+  }
+  let docs = String(arg('--stores')).split(',').flatMap((s) => readStoreDocs(kb, s.trim(), arg('--kind', 'md')))
+    .filter((d) => !done.has(`${d.store}|${d.path}`));
+  if (arg('--limit')) docs = docs.slice(0, Number(arg('--limit')));
+  const batches = [];
+  for (let i = 0; i < docs.length; i += batchSize) batches.push(docs.slice(i, i + batchSize));
+  const env = { ...subscriptionOnlyEnv(), CLAUDE_HOOK: '/usr/bin/true' };
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'd2q-'));
+  let next = 0;
+  let stop = false;
+  let written = 0;
+  const worker = async () => {
+    while (!stop && next < batches.length) {
+      const b = batches[next++];
+      const withIds = b.map((d, i) => ({ ...d, docId: `d${i}` }));
+      const res = await spawnHost('claude', claudeArgs({ model, effort: 'low', schema: D2Q_SCHEMA, systemPrompt: D2Q_SYSTEM }),
+        { cwd, env, timeoutMs: 600_000 }, d2qPrompt(withIds, perFile));
+      let items = null;
+      try {
+        const env2 = JSON.parse(res.stdout);
+        items = (env2.structured_output || JSON.parse(env2.result)).items;
+      } catch { items = null; }
+      if (!items) {
+        if (isQuotaRefusal(res.stdout + res.stderr)) { stop = true; process.stderr.write('\n[d2q] quota refusal: stopping\n'); }
+        else process.stderr.write(`\n[d2q] batch failed (status ${res.status}${res.timedOut ? ', timeout' : ''})\n`);
+        continue;
+      }
+      const byId = new Map(items.map((it) => [it.docId, it.questions || []]));
+      const lines = withIds.map((d) => {
+        const qs = byId.get(d.docId) || [];
+        const kept = [];
+        const rejected = [];
+        for (const q of qs) { const why = leakReason(q, d); if (why) rejected.push({ q, why }); else kept.push(q); }
+        return JSON.stringify({ store: d.store, path: d.path, questions: kept, rejected });
+      });
+      fs.appendFileSync(out, `${lines.join('\n')}\n`);
+      written += lines.length;
+      process.stderr.write(`\r[d2q] ${written}/${docs.length} files`);
+    }
+  };
+  await Promise.all(Array.from({ length: conc }, worker));
+  console.log(JSON.stringify({ files: docs.length, written, stopped: stop }));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();