ruvnet-brain 4.0.4 → 4.0.5

package/scripts/onboarding-console.mjs

@@ -69,23 +69,44 @@ import { applyNightlyChoice, nightlyStatus } from './nightly-controller.mjs';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO = path.dirname(__dirname);
 const CONSOLE_DIR = path.join(REPO, 'console');
-const HOME = os.homedir();
-const NPM_PREFIX = path.join(HOME, '.npm-global');
-const CONFIG_DIR = path.join(HOME, '.claude/ruvnet-brain');
+const SYSTEM_HOME = os.homedir();
+
+/**
+ * The console's explicit root boundary. It scopes only console-owned configuration, state, cache,
+ * and discovery; global binaries, account credentials, and external tool state retain SYSTEM_HOME.
+ */
+export function consoleRootFromEnvironment(env = process.env, systemHome = SYSTEM_HOME) {
+  const configured = env.RUVNET_CONSOLE_ROOT;
+  if (!configured) return systemHome;
+  if (typeof configured !== 'string' || !path.isAbsolute(configured)) {
+    throw new Error('RUVNET_CONSOLE_ROOT must be an absolute path');
+  }
+  return path.resolve(configured);
+}
+
+// A test or an embedded caller can isolate the console's owned files and discovery roots without
+// redefining the operating-system home directory. Normal launches retain the OS home exactly.
+const CONSOLE_ROOT = consoleRootFromEnvironment();
+const NPM_PREFIX = path.join(SYSTEM_HOME, '.npm-global');
+const CONFIG_DIR = path.join(CONSOLE_ROOT, '.claude/ruvnet-brain');
 const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
-const UNDO_JOURNAL = path.join(HOME, '.cache/ruvnet-brain/console-undo.jsonl');
+const UNDO_JOURNAL = path.join(CONSOLE_ROOT, '.cache/ruvnet-brain/console-undo.jsonl');
 const INSTALLED_KB = process.env.RUVNET_BRAIN_KB
-  || path.join(HOME, '.cache', 'ruvnet-brain', 'kb');
+  || path.join(CONSOLE_ROOT, '.cache', 'ruvnet-brain', 'kb');
 const COMPLETE_BRAIN_SOURCE = process.env.RUVNET_BRAIN_COMPLETE_SOURCE
   || path.join(REPO, 'dist', 'ruvnet-brain');
 const TOKEN = crypto.randomBytes(24).toString('hex');
-const RUNTIME_RECEIPT_DIR = path.join(HOME, '.cache', 'ruvnet-brain', 'console-instances');
+const RUNTIME_RECEIPT_DIR = path.join(CONSOLE_ROOT, '.cache', 'ruvnet-brain', 'console-instances');
 const RUNTIME_PRODUCT = 'ruvnet-brain-console';
 const RUNTIME_SCHEMA = 1;
 const RUNTIME_API_CONTRACT = 1;
 const RUNTIME_SCRIPT = fs.realpathSync(fileURLToPath(import.meta.url));
 const RUNTIME_SOURCE_SHA256 = crypto.createHash('sha256').update(fs.readFileSync(RUNTIME_SCRIPT)).digest('hex');
 
+function consoleCandidateRoots() {
+  return candidateRoots({ home: CONSOLE_ROOT, configPath: CONFIG_PATH });
+}
+
 function canonicalScope(cwd = process.cwd()) {
   try { return fs.realpathSync(cwd); } catch { return path.resolve(cwd); }
 }
@@ -356,7 +377,7 @@ function wiringSurvey() {
   // must never count the same project twice.
   const seenProjects = new Set();
   const projects = [];
-  for (const root of candidateRoots()) {
+  for (const root of consoleCandidateRoots()) {
     for (const proj of findProjects(root)) {
       const resolved = path.resolve(proj);
       if (seenProjects.has(resolved)) continue;
@@ -394,7 +415,7 @@ function wiringSurvey() {
 
 // ── Memory health (read-only probes for the project the console was launched from) ────────────────
 function sessionHookExists() {
-  return fs.existsSync(path.join(HOME, '.claude/hooks/agentdb-ensure.sh')) || fs.existsSync(path.join(HOME, '.claude/hooks'));
+  return fs.existsSync(path.join(CONSOLE_ROOT, '.claude/hooks/agentdb-ensure.sh')) || fs.existsSync(path.join(CONSOLE_ROOT, '.claude/hooks'));
 }
 function probeMemory(projectDir) {
   const db = path.join(projectDir, '.swarm/memory.db');
@@ -462,7 +483,7 @@ function scanFleet() {
 function gatherMemory(cwd, { fleet = true } = {}) {
   // health = for the project the console was launched from (fall back to this repo)
   const project = fs.existsSync(path.join(cwd, '.swarm/memory.db')) ? cwd : REPO;
-  const projName = project.replace(HOME + '/Code/', '').replace(HOME + '/', '~/');
+  const projName = project.replace(CONSOLE_ROOT + '/Code/', '').replace(CONSOLE_ROOT + '/', '~/');
   const health = scoreMemoryHealth({ project: projName, probes: probeMemory(project) });
   return { fleet: fleet ? scanFleet() : null, health };
 }
@@ -471,10 +492,10 @@ function gatherMemory(cwd, { fleet = true } = {}) {
 function gatherSavings() {
   // Primary source is the real routing-receipts ledger written by scripts/route-cheap.mjs.
   const files = [
-    path.join(HOME, '.claude/metaharness/routing-receipts.jsonl'),
-    path.join(HOME, '.cache/ruvnet-brain/metaharness-receipts.jsonl'),
+    path.join(SYSTEM_HOME, '.claude/metaharness/routing-receipts.jsonl'),
+    path.join(SYSTEM_HOME, '.cache/ruvnet-brain/metaharness-receipts.jsonl'),
     // Canonical user-level ledger (issue #36 — the hooks no longer scatter per-CWD copies).
-    path.join(HOME, '.cache/ruvnet-brain/token-ledger.jsonl'),
+    path.join(SYSTEM_HOME, '.cache/ruvnet-brain/token-ledger.jsonl'),
     // Legacy location, still read so an existing user's history is not orphaned by the move.
     path.join(REPO, 'plugin/scripts/.ruvnet-brain/token-ledger.jsonl'),
   ];
@@ -578,7 +599,7 @@ function gatherConfig() {
     });
   }
   return {
-    path: CONFIG_PATH.replace(HOME, '~'),
+    path: CONFIG_PATH.replace(CONSOLE_ROOT, '~'),
     exists: fs.existsSync(CONFIG_PATH),
     values: {
       openrouterKey: credential.configured,                // boolean only — never the secret itself
@@ -627,7 +648,7 @@ function gatherAdvocacy() {
   const chosen = raw && typeof raw === 'object' && raw.settings && typeof raw.settings === 'object'
     ? raw.settings : {};
   return {
-    path: state.path.replace(HOME, '~'),
+    path: state.path.replace(CONSOLE_ROOT, '~'),
     exists: state.exists,
     values: Object.fromEntries(LIVE_USER_FIELDS.map((field) => [
       field.key,
@@ -675,7 +696,7 @@ function saveAdvocacy(values) {
   publishSettingsToCache();
   return {
     ok: true,
-    backup: result.backup ? result.backup.replace(HOME, '~') : null,
+    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,
   };
@@ -715,7 +736,7 @@ function gatherBrainProfile() {
   const source = measureBrainProfile(COMPLETE_BRAIN_SOURCE);
   const updaterAvailable = fs.existsSync(path.join(INSTALLED_KB, 'forge-update.mjs'));
   return {
-    path: INSTALLED_KB.replace(HOME, '~'),
+    path: INSTALLED_KB.replace(CONSOLE_ROOT, '~'),
     values: { brainProfile: actual },
     stored: settings.values.brainProfile,
     disagreement: settings.values.brainProfile !== actual,
@@ -736,7 +757,7 @@ function gatherBrainProfile() {
         bytes: installed.byStore.ruvector ?? source.byStore.ruvector ?? null,
       },
     },
-    restoreSource: COMPLETE_BRAIN_SOURCE.replace(HOME, '~'),
+    restoreSource: COMPLETE_BRAIN_SOURCE.replace(CONSOLE_ROOT, '~'),
   };
 }
 
@@ -747,7 +768,7 @@ function gatherBrainPower() {
     off: state.off,
     since: state.since,
     reason: state.reason,
-    switchPath: state.path.replace(HOME, '~'),
+    switchPath: state.path.replace(CONSOLE_ROOT, '~'),
     // The RESOLVED answer — what the machine actually does — not the mirror's opinion of it.
     values: { brainEnabled: !state.off },
     defaults: { brainEnabled: BRAIN_FIELD.default },
@@ -829,7 +850,7 @@ function saveBrainProfile(values) {
     removed: changed.removed || [],
     bytesFreed: changed.bytesFreed || 0,
     mirrored: mirrored.ok,
-    backup: mirrored.backup ? mirrored.backup.replace(HOME, '~') : null,
+    backup: mirrored.backup ? mirrored.backup.replace(CONSOLE_ROOT, '~') : null,
     log: mirrored.ok
       ? (profile === PROFILE_RUVECTOR
         ? `RuVector Only is active — ${changed.removed.length} unselected artifact(s) removed`
@@ -917,7 +938,7 @@ function saveBrainPower(values) {
     ok: true,
     off: state.off,
     since: state.since,
-    backup: mirrored.backup ? mirrored.backup.replace(HOME, '~') : null,
+    backup: mirrored.backup ? mirrored.backup.replace(CONSOLE_ROOT, '~') : null,
     values: { brainEnabled: !state.off },
     // Honest about the half-failure rather than reporting a clean success: the switch is what counts
     // and it moved, but say so plainly if the visible record did not follow it.
@@ -1087,7 +1108,7 @@ function setLesson(body) {
 // setImmediate either (deferring synchronous work still blocks the loop when it runs). A machine with
 // no fleet scan yet is reported `warming`, never as a fabricated zero.
 let ACTIVITY_MACHINE_CACHE = null;
-const CONSOLE_CACHE_PATH = path.join(HOME, '.cache/ruvnet-brain/console-cache.json');
+const CONSOLE_CACHE_PATH = path.join(CONSOLE_ROOT, '.cache/ruvnet-brain/console-cache.json');
 
 // ── Warm-cache serving (2026-07-17, the demo-hang fix) ─────────────────────────────────────────────
 // Every read-model here does multi-second synchronous work: gatherState ~13s, gatherStack ~22s,
@@ -1537,7 +1558,7 @@ function refreshFleetCache() {
   const seen = new Set();
   // Scan every candidate root (issue #19) — this is what made machine-wide totals read 0 on a
   // machine whose projects live under ~/source instead of ~/Code.
-  for (const root of candidateRoots()) {
+  for (const root of consoleCandidateRoots()) {
     for (const s of findMemoryStores(root)) {
       const resolved = path.resolve(s.project);
       if (seen.has(resolved)) continue; // a project visible under two roots (e.g. a symlink) counts once
@@ -1816,11 +1837,11 @@ function brainVersionOnDisk() {
   try { return getVersion(); } catch { return null; }
 }
 function readInstallChannel() {
-  const reg = readJSON(path.join(HOME, '.claude/plugins/installed_plugins.json'));
+  const reg = readJSON(path.join(SYSTEM_HOME, '.claude/plugins/installed_plugins.json'));
   const entries = reg && reg.plugins && reg.plugins['ruvnet-brain@ruvnet-brain'];
   const e = Array.isArray(entries) ? entries[0] : null;
   if (!e || !e.installPath || !fs.existsSync(e.installPath)) return { installed: false };
-  const km = readJSON(path.join(HOME, '.claude/plugins/known_marketplaces.json'));
+  const km = readJSON(path.join(SYSTEM_HOME, '.claude/plugins/known_marketplaces.json'));
   const src = km && km['ruvnet-brain'] && km['ruvnet-brain'].source;
   const pinned = !!(src && (src.ref || src.tag || src.commit)); // no pin recorded → tracking latest
   return {
@@ -1828,7 +1849,7 @@ function readInstallChannel() {
     version: path.basename(e.installPath) || e.version || null, // the plugin cache version dir IS the truth
     channel: pinned ? 'pinned' : 'latest',
     lastUpdated: e.lastUpdated || null,
-    cacheDir: String(e.installPath).replace(HOME, '~'),
+    cacheDir: String(e.installPath).replace(SYSTEM_HOME, '~'),
     repo: (src && src.repo) || null,
   };
 }
@@ -1969,7 +1990,7 @@ function gatherState(cwd, { fleet = true } = {}) {
   // agentic-flow, and the Savings card claiming "Smart routing: ON" while the Capabilities card said
   // "not installed" — in the same render — was the contradiction that made the whole page untrustworthy.
   // The card now carries the same measurement the capability row uses, so the two cannot disagree.
-  savings.routingInstalled = fs.existsSync(path.join(HOME, '.npm-global/bin/agentic-flow'));
+  savings.routingInstalled = fs.existsSync(path.join(SYSTEM_HOME, '.npm-global/bin/agentic-flow'));
   try { savings.routerEngine = gatherRouterEngine(); } catch { savings.routerEngine = null; }
   try {
     const cat = loadCatalog();
@@ -2015,7 +2036,7 @@ function gatherState(cwd, { fleet = true } = {}) {
     token: TOKEN,
     generatedAt: new Date().toISOString(),
     preStateHash,
-    host: { user: os.userInfo().username, platform: process.platform, node: process.version, npmPrefix: NPM_PREFIX.replace(HOME, '~'), brainVersion: brainVersionOnDisk() },
+    host: { user: os.userInfo().username, platform: process.platform, node: process.version, npmPrefix: NPM_PREFIX.replace(SYSTEM_HOME, '~'), brainVersion: brainVersionOnDisk() },
     sections: { wiring, memory, savings, config, userSettings, brainPower, gates, recommendations },
   };
   // Cache the last good state so repeat page-loads paint instantly, same as the stack audit does.
@@ -2036,7 +2057,7 @@ function gatherStack() {
   // ISSUE #22 — carry `source` ('npm-global' | 'plugin') + marketplace through so the console can show
   // (and count) tools installed via the Claude Code plugin marketplace, not just `npm install -g` ones.
   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(HOME, '~'), stale: !!(s.global && s.version !== s.global) }));
+  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 recommendations = buildStackRecommendations({ rows: a.rows, stale: a.stale });
@@ -2064,29 +2085,32 @@ function runNode(scriptRelPath, args) {
   const r = spawnSync(process.execPath, [path.join(REPO, scriptRelPath), ...args], { encoding: 'utf8', timeout: 16 * 60 * 1000, cwd: REPO });
   return { ok: r.status === 0, code: r.status, log: `${r.stdout || ''}${r.stderr || ''}`.trim().slice(-4000) };
 }
+function elapsedMs(startedAt) {
+  return Math.round((performance.now() - startedAt) * 1000) / 1000;
+}
 
 // A wiring recommendation's `project` id is relative to whichever candidate root it was found under
 // (issue #19) — reconstruct the absolute path by checking each root, so reconcile/undo can act on a
 // project under ~/source just as well as one under ~/Code.
 function resolveProjectDir(project) {
-  for (const root of candidateRoots()) {
+  for (const root of consoleCandidateRoots()) {
     const p = path.join(root, project);
     if (fs.existsSync(p)) return p;
   }
-  return path.join(HOME, 'Code', project); // last-resort fallback: the previous fixed behavior
+  return path.join(CONSOLE_ROOT, 'Code', project); // last-resort fallback: the previous fixed behavior
 }
 // Re-derive the currently-valid recommendation set, so apply can only ever act on something STILL true.
 /**
  * Observe the learner's REAL state, for the health recommendations.
  *
- * Deliberately reads the GLOBAL learner (`cwd: HOME`), because that is the store the capture flush
+ * Deliberately reads the global learner, because that is the store the capture flush
  * actually writes to. Reading the project-local `.claude-flow/neural` instead is exactly the mistake
  * that made the console display a dead learner (5 trajectories, last trained 6 days earlier) while
  * the live one held 412 — rUv documents this fragmentation as issue #2245, "four contradictory
  * sources". Until it is unified upstream we read the store that learning writes, never the corpse.
  */
 function observeLearning() {
-  const queueDir = path.join(os.homedir(), '.cache', 'ruvnet-brain', 'learn');
+  const queueDir = path.join(SYSTEM_HOME, '.cache', 'ruvnet-brain', 'learn');
   let queueDepth = 0;
   try {
     for (const f of fs.readdirSync(queueDir)) {
@@ -2097,10 +2121,10 @@ function observeLearning() {
 
   let lastTrainSeconds = null; let trajectories = 0;
   try {
-    const r = spawnSync(path.join(os.homedir(), '.npm-global/bin/ruflo'),
+    const r = spawnSync(path.join(SYSTEM_HOME, '.npm-global/bin/ruflo'),
       ['hooks', 'intelligence', '--status'],
       {
-        cwd: os.homedir(),
+        cwd: SYSTEM_HOME,
         env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' },
         encoding: 'utf8',
         timeout: 20_000,
@@ -2167,11 +2191,15 @@ function currentValidIds(onlyId = null) {
   return { ids, auditRows };
 }
 function apply(ids) {
+  const startedAt = performance.now();
+  const phaseMs = { revalidationMs: 0, undoJournalMs: 0, childRemedyMs: 0 };
   const results = [];
   for (const id of ids) {
     // Re-read immediately before EACH fix. A batch can change the validity of the next item; one
     // pre-flight snapshot for the whole list would let item 2 run against the world item 1 changed.
+    const revalidationStartedAt = performance.now();
     const { ids: validNow } = currentValidIds(id);
+    phaseMs.revalidationMs += elapsedMs(revalidationStartedAt);
     if (!validNow.has(id)) { results.push({ id, ok: false, skipped: true, error: 'worldMoved', log: 'Skipped — this is already resolved, or your machine changed since the page loaded. Nothing was done. Reload to see the current state.' }); continue; }
 
     // ONE dispatch, through the registry (scripts/remedy-registry.mjs). This used to be a chain of
@@ -2213,16 +2241,22 @@ function apply(ids) {
     // flag exists so it cannot recur here.
     if (plan.exec.usesServerProject) args = [...args, '--project', process.cwd()];
     if (plan.exec.needsReceipt) {
-      const receipt = path.join(HOME, '.cache', 'ruvnet-brain', 'undo', `${plan.key}-${stamp()}.json`);
+      const receipt = path.join(CONSOLE_ROOT, '.cache', 'ruvnet-brain', 'undo', `${plan.key}-${stamp()}.json`);
       undoSpec.receipt = receipt;
       args = [...args, '--receipt', receipt];
     }
 
+    const journalStartedAt = performance.now();
     const undoToken = journalUndo(undoSpec);
+    phaseMs.undoJournalMs += elapsedMs(journalStartedAt);
+    const remedyStartedAt = performance.now();
     const res = runNode(plan.exec.script, args);
+    phaseMs.childRemedyMs += elapsedMs(remedyStartedAt);
     results.push({ id, ...res, undoToken });
   }
-  return { results };
+  // This receipt contains only aggregate durations, never the applied ids, paths, command output,
+  // or undo tokens. It makes an end-user-visible delay diagnosable without exposing their machine.
+  return { results, timings: { ...phaseMs, totalMs: elapsedMs(startedAt) } };
 }
 
 function autoEligibleIds(recommendations = []) {
@@ -2294,7 +2328,7 @@ function validateConfigPatch(values) {
  */
 function saveConfig(values) {
   try { fs.mkdirSync(CONFIG_DIR, { recursive: true }); }
-  catch (e) { return { ok: false, log: `could not create ${CONFIG_DIR.replace(HOME, '~')}: ${e.message}` }; }
+  catch (e) { return { ok: false, log: `could not create ${CONFIG_DIR.replace(CONSOLE_ROOT, '~')}: ${e.message}` }; }
 
   const { clean, rejected } = validateConfigPatch(values);
   // Nothing valid to write is not a save. Saying "Saved." here would be the dead-button failure with
@@ -2356,7 +2390,7 @@ function saveConfig(values) {
     // A successfully encrypted credential retires the legacy plaintext field on this same commit.
     if (credentialChange?.ok) delete next.openrouterKey;
     try { writeAtomic(CONFIG_PATH, JSON.stringify(next, null, 2) + '\n'); }
-    catch (e) { return { ok: false, backup, log: `write failed: ${e.message}${backup ? `; your previous settings are at ${backup.replace(HOME, '~')}` : ''}` }; }
+    catch (e) { return { ok: false, backup, log: `write failed: ${e.message}${backup ? `; your previous settings are at ${backup.replace(CONSOLE_ROOT, '~')}` : ''}` }; }
     try { fs.chmodSync(CONFIG_PATH, 0o600); } catch { /* best effort on non-posix */ }
 
     // The undo token is journalled only AFTER the write succeeded. Recording an undo for a save that
@@ -2370,7 +2404,7 @@ function saveConfig(values) {
       secretPath: credentialChange?.path ?? null,
       secretExisted: credentialChange?.existed ?? null,
     });
-    return { ok: true, backup: backup ? backup.replace(HOME, '~') : null, undoToken, rejected };
+    return { ok: true, backup: backup ? backup.replace(CONSOLE_ROOT, '~') : null, undoToken, rejected };
   });
 
   if (held.timedOut) {
@@ -2464,7 +2498,7 @@ function undo(undoToken) {
       try {
         const bytes = fs.readFileSync(entry.backup);
         held = withLock(CONFIG_PATH, () => writeAtomic(CONFIG_PATH, bytes));
-      } catch (e) { return { ok: false, log: `restore failed: ${e.message} — your backup at ${entry.backup.replace(HOME, '~')} is intact` }; }
+      } catch (e) { return { ok: false, log: `restore failed: ${e.message} — your backup at ${entry.backup.replace(CONSOLE_ROOT, '~')} is intact` }; }
       if (held.timedOut) return { ok: false, log: `another process is writing your settings and did not finish within ${LOCK_WAIT_MS}ms — NOTHING was restored and your backup is intact; try again` };
       try { fs.chmodSync(CONFIG_PATH, 0o600); } catch { /* best effort on non-posix */ }
       const effectFailures = restoreConfigEffects(entry);
@@ -2524,10 +2558,10 @@ function undo(undoToken) {
     const base = `${path.basename(entry.db)}.rescue-`;
     let baks = [];
     try { baks = fs.readdirSync(dir).filter((n) => n.startsWith(base)).sort(); } catch { /* dir gone */ }
-    if (!baks.length) return { ok: false, log: `no pre-repair backup found next to ${entry.db.replace(HOME, '~')} — nothing was restored` };
+    if (!baks.length) return { ok: false, log: `no pre-repair backup found next to ${entry.db.replace(CONSOLE_ROOT, '~')} — nothing was restored` };
     const from = path.join(dir, baks[baks.length - 1]);
     try { fs.copyFileSync(from, entry.db); }
-    catch (e) { return { ok: false, log: `could not restore ${from.replace(HOME, '~')}: ${e.message}` }; }
+    catch (e) { return { ok: false, log: `could not restore ${from.replace(CONSOLE_ROOT, '~')}: ${e.message}` }; }
     markUndoConsumed(undoToken);
     return { ok: true, log: `restored your memory store from the snapshot taken before the repair (${baks[baks.length - 1]})` };
   }
@@ -2801,7 +2835,7 @@ function startServer({ port = Number(process.env.CONSOLE_PORT) || 7411, open = f
     // precise moment a first-time user is deciding whether this thing works. The child does that
     // scan now (see --refresh-cache), and gatherActivity reports `warming` until it lands.
     if (open) openBrowser(url);
-    // Browser acceptance pre-warms a disposable HOME and disables only this redundant second scan.
+    // Browser acceptance pre-warms a disposable fixture root and disables only this redundant second scan.
     // The production default is unchanged: every ordinary console start refreshes in the background.
     if (process.env.RUVNET_CONSOLE_DISABLE_BACKGROUND_REFRESH !== '1') kickRefresh({ force: true });
   });

package/scripts/release-vector.mjs

@@ -33,9 +33,9 @@ export function verdictOf(results) {
   return results.reduce((worst, r) => (RANK.indexOf(r.state) < RANK.indexOf(worst) ? r.state : worst), 'PASS');
 }
 
-export function candidateLineage() {
+export function candidateLineage(root = ROOT) {
   const git = (args) => {
-    const r = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
     return r.status === 0 ? r.stdout.trim() : '';
   };
   return {
@@ -49,11 +49,8 @@ export function verdictWithLineage(results, lineage) {
   return lineage?.dirty ? 'FAIL' : verdictOf(results);
 }
 
-const exists = (rel) => fs.existsSync(path.join(ROOT, rel));
-const read = (rel) => { try { return fs.readFileSync(path.join(ROOT, rel), 'utf8'); } catch { return null; } };
-
 /** Run a command; UNKNOWN (not FAIL) when the runner itself could not execute. */
-function run(cmd, args, timeoutMs = 120_000, env = process.env) {
+function runAt(root, cmd, args, timeoutMs = 120_000, env = process.env) {
   // npm installs `npm.cmd` / `npx.cmd` command shims on Windows. Direct spawn does not resolve the
   // extension through PATHEXT, and .cmd files require cmd.exe, so a healthy detector otherwise
   // reads UNKNOWN with ENOENT. Invoke the command interpreter explicitly rather than `shell:true`;
@@ -62,7 +59,7 @@ function run(cmd, args, timeoutMs = 120_000, env = process.env) {
   const executable = windowsCommandShim ? (process.env.ComSpec || 'cmd.exe') : cmd;
   const spawnArgs = windowsCommandShim ? ['/d', '/c', `${cmd}.cmd`, ...args] : args;
   const r = spawnSync(executable, spawnArgs, {
-    cwd: ROOT,
+    cwd: root,
     encoding: 'utf8',
     timeout: timeoutMs,
     env,
@@ -71,6 +68,18 @@ function run(cmd, args, timeoutMs = 120_000, env = process.env) {
   return { state: r.status === 0 ? 'PASS' : 'FAIL', why: r.status === 0 ? 'exit 0' : `exit ${r.status}`, out: r.stdout };
 }
 
+/** An explicit detector root makes destructive mutants isolated and concurrency-safe. */
+function detectorScope({ root = ROOT, runCommand = null } = {}) {
+  return {
+    root,
+    exists: (relative) => fs.existsSync(path.join(root, relative)),
+    read: (relative) => {
+      try { return fs.readFileSync(path.join(root, relative), 'utf8'); } catch { return null; }
+    },
+    run: runCommand || ((cmd, args, timeoutMs, env) => runAt(root, cmd, args, timeoutMs, env)),
+  };
+}
+
 // ─── the eight invariants ────────────────────────────────────────────────────────────────────
 // Each names the dimension it gates and the dated failure it descends from. A detector with no
 // incident behind it is a checkbox; every one of these was bought with a real defect.
@@ -80,7 +89,8 @@ export const INVARIANTS = [
     name: 'INSTALL-FAILS-LOUD',
     dimension: 'D8',
     incident: 'verifyInstall() warned and continued; a stranger scored 18/100 on an install that could not fail',
-    detect() {
+    detect(options) {
+      const { exists, read } = detectorScope(options);
       if (!exists('.github/workflows/stranger-matrix.yml')) return { state: 'FAIL', why: 'no stranger matrix' };
       const inst = read('bin/install.mjs');
       if (inst === null) return { state: 'UNKNOWN', why: 'bin/install.mjs unreadable' };
@@ -95,7 +105,8 @@ export const INVARIANTS = [
     name: 'INTERFACE-CORPUS',
     dimension: 'D7',
     incident: 'shell-parsing defects recurred across issues #12/#13/#41/#44, then three stale ADRs reached main because document currency was outside every release gate',
-    detect() {
+    detect(options) {
+      const { exists, run } = detectorScope(options);
       if (!exists('tests/regression/interface-gate-corpus.test.mjs')) return { state: 'FAIL', why: 'no incident corpus' };
       if (!exists('scripts/doc-currency.mjs')) return { state: 'FAIL', why: 'no document-currency gate' };
       const corpus = run('npx', ['vitest', 'run', 'tests/regression/interface-gate-corpus.test.mjs', '--reporter=dot']);
@@ -110,23 +121,29 @@ export const INVARIANTS = [
     name: 'LATENCY-DECISION-LANE',
     dimension: 'D6',
     incident: 'latency breaches only warned; timing regressions did not block shipping',
-    detect: () => (exists('scripts/qe/card-lane-gate.mjs')
-      ? run('node', ['scripts/qe/card-lane-gate.mjs'])
-      : { state: 'FAIL', why: 'no decision-lane gate' }),
+    detect(options) {
+      const { exists, run } = detectorScope(options);
+      return exists('scripts/qe/card-lane-gate.mjs')
+        ? run('node', ['scripts/qe/card-lane-gate.mjs'])
+        : { state: 'FAIL', why: 'no decision-lane gate' };
+    },
   },
   {
     name: 'COEXIST-BYTE-EQUAL',
     dimension: 'D5',
     incident: 'the merged-registry lint found 63 findings across 42 registrations; the prior suite saw 15',
-    detect: () => (exists('tests/mesh/coexistence.test.mjs')
-      ? run('npx', ['vitest', 'run', 'tests/mesh', '--reporter=dot'])
-      : { state: 'FAIL', why: 'no coexistence suite' }),
+    detect(options) {
+      const { exists, run } = detectorScope(options);
+      return exists('tests/mesh/coexistence.test.mjs')
+        ? run('npx', ['vitest', 'run', 'tests/mesh', '--reporter=dot'])
+        : { state: 'FAIL', why: 'no coexistence suite' };
+    },
   },
   {
     name: 'LEARNING-REPLAY',
     dimension: 'D4',
     incident: 'L4 asserted the hook\'s own prose contained words — it proved the brain SPOKE, never that anything LISTENED',
-    async detect() {
+    async detect(options = {}) {
       // DELEGATED to scripts/learning-replay.mjs's own checkArtifact(), not reimplemented here.
       //
       // This detector originally required `artifact.sha === HEAD`, which is WRONG in a way worth
@@ -141,7 +158,9 @@ export const INVARIANTS = [
       try { mod = await import(new URL('./learning-replay.mjs', import.meta.url).href); }
       catch { return { state: 'UNKNOWN', why: 'counterfactual replay harness absent' }; }
       let r;
-      try { r = mod.checkPortfolio(); } catch (e) { return { state: 'UNKNOWN', why: `replay portfolio unreadable: ${e.message}` }; }
+      try {
+        r = options.checkReplay ? options.checkReplay() : mod.checkPortfolio({ repo: options.root || ROOT });
+      } catch (e) { return { state: 'UNKNOWN', why: `replay portfolio unreadable: ${e.message}` }; }
       // `.status` is the field checkArtifact() actually returns — read, not assumed. Reaching for
       // `.verdict` (the name used INSIDE the nested artifact) silently yielded undefined and made a
       // real PASS read UNKNOWN: the delegation "worked" while reporting the opposite of the truth.
@@ -157,7 +176,8 @@ export const INVARIANTS = [
     name: 'SIGNAL-WATCH-FIRES',
     dimension: 'D3',
     incident: 'the OWNER had to report that CI was red — every local surface stayed calm',
-    detect() {
+    detect(options) {
+      const { exists, read, run } = detectorScope(options);
       if (!exists('scripts/signal-watch.mjs')) return { state: 'FAIL', why: 'no signal watcher' };
       const raw = read('plugin/hooks/hooks.json');
       if (raw === null) return { state: 'UNKNOWN', why: 'plugin/hooks/hooks.json unreadable' };
@@ -207,15 +227,19 @@ export const INVARIANTS = [
     name: 'SCENARIOS-CURRENT',
     dimension: 'D2',
     incident: 'ADR-053 specified a mental-model scenario list; it was simply absent',
-    detect: () => (exists('tests/experience/report.mjs')
-      ? run('node', ['tests/experience/report.mjs'])
-      : { state: 'FAIL', why: 'no scenario report' }),
+    detect(options) {
+      const { exists, run } = detectorScope(options);
+      return exists('tests/experience/report.mjs')
+        ? run('node', ['tests/experience/report.mjs'])
+        : { state: 'FAIL', why: 'no scenario report' };
+    },
   },
   {
     name: 'GUARANTEE-RUNS',
     dimension: 'D1',
     incident: 'the product guarantee skipped on every CI runner; REQUIRE_BRAIN=1 was set nowhere in the repo',
-    detect() {
+    detect(options) {
+      const { read, run } = detectorScope(options);
       const ci = read('.github/workflows/ci.yml');
       if (ci === null) return { state: 'UNKNOWN', why: 'ci.yml unreadable' };
       if (!/REQUIRE_BRAIN/.test(ci)) {
@@ -247,12 +271,12 @@ export function headSha() {
 /** Strings a non-PASS verdict mechanically bans from release surfaces (ADR-058). */
 export const BANNED_WHEN_DEGRADED = ['healthy', 'proven', 'all pass'];
 
-export async function evaluate(invariants = INVARIANTS) {
-  const lineage = candidateLineage();
+export async function evaluate(invariants = INVARIANTS, options = {}) {
+  const lineage = candidateLineage(options.root || ROOT);
   const sha = lineage.sha;
   const results = [];
   for (const inv of invariants) {
-    const r = await inv.detect();
+    const r = await inv.detect(options);
     results.push({ name: inv.name, dimension: inv.dimension, state: r.state, why: r.why, sha });
   }
   return { sha, lineage, results, verdict: verdictWithLineage(results, lineage) };